# API Docs¶

## Jupyter notebooks with API examples¶

A jupyter notebook with tables of importable variables and equations can be found at https://github.com/environmentalscience/essm/blob/master/docs/examples/importable_variables_equations.ipynb

A jupyter notebook with use examples for the API can be found at https://github.com/environmentalscience/essm/blob/master/docs/examples/api_features.ipynb

## Variables¶

Variables module to deal with physical variables and units.

It allows attaching docstrings to variable names, defining their domains (e.g. integer, real or complex), their units and LaTeX representations. You can also provide a default value, which is particularly useful for physical constants.

### Creating variables¶

To create custom variables, first import Variable:

>>> from essm.variables import Variable


To define units, you must first import these units from the library:

>>> from essm.variables.units import joule, kelvin, meter


Then you can define a custom variable with its name, description, domain, latex_name, unit, and an optional default value.

Example: .. code-block:: python

from .variables.units import meter

class demo_chamber_volume1(Variable):

‘’‘Volume of Chamber 1.’‘’

name = ‘V_c1’ domain = ‘real’ latex_name = ‘V_{c1}’ unit = meter ** 3 default = 1

Now, demo_chamber_volume is displayed as V_c1 and it will be nicely rendered in LaTeX as $$V_{c1}$$.

You can type help(demo_chamber_volume) to inspects its metadata.

Variable.__defaults__ returns a dictionary with all variables and their default values, Variable.__units__ returns their units, and demo_chamber_volume.short_unit() can be used to obtain the units in short notation.

This module also contains libraries of pre-defined variables, which can be imported into your session, e.g.:

>>> from essm.variables.physics.thermodynamics import *
>>> from essm.variables.leaf.energy_water import *


### Chamber¶

Chamber related variables.

#### Mass¶

Chamber mass and energy balance.

class essm.variables.chamber.mass.W_c

Chamber width.

assumptions = {'real': True}
latex_name = 'W_c'
name = 'W_c'
unit = meter
class essm.variables.chamber.mass.L_c

Chamber length.

assumptions = {'real': True}
latex_name = 'L_c'
name = 'L_c'
unit = meter
class essm.variables.chamber.mass.H_c

Chamber height.

assumptions = {'real': True}
latex_name = 'H_c'
name = 'H_c'
unit = meter
class essm.variables.chamber.mass.V_c

Chamber volume.

assumptions = {'real': True}
latex_name = 'V_c'
name = 'V_c'
unit = meter**3
class essm.variables.chamber.mass.n_c

molar mass of gas in chamber.

assumptions = {'real': True}
latex_name = 'n_c'
name = 'n_c'
unit = mole
class essm.variables.chamber.mass.F_in_v

Volumetric flow rate into chamber.

assumptions = {'real': True}
latex_name = 'F_{in,v}'
name = 'F_in_v'
unit = meter**3/second
class essm.variables.chamber.mass.F_in_mola

Molar flow rate of dry air into chamber.

assumptions = {'real': True}
latex_name = 'F_{in,mol,a}'
name = 'F_in_mola'
unit = mole/second
class essm.variables.chamber.mass.F_in_molw

Molar flow rate of water vapour into chamber.

assumptions = {'real': True}
latex_name = 'F_{in,mol,w}'
name = 'F_in_molw'
unit = mole/second
class essm.variables.chamber.mass.F_out_mola

Molar flow rate of dry air out of chamber.

assumptions = {'real': True}
latex_name = 'F_{out,mol,a}'
name = 'F_out_mola'
unit = mole/second
class essm.variables.chamber.mass.F_out_molw

Molar flow rate of water vapour out of chamber.

assumptions = {'real': True}
latex_name = 'F_{out,mol,w}'
name = 'F_out_molw'
unit = mole/second
class essm.variables.chamber.mass.F_out_v

Volumetric flow rate out of chamber.

assumptions = {'real': True}
latex_name = 'F_{out,v}'
name = 'F_out_v'
unit = meter**3/second
class essm.variables.chamber.mass.T_d

Dew point temperature of incoming air.

assumptions = {'real': True}
latex_name = 'T_d'
name = 'T_d'
unit = kelvin
class essm.variables.chamber.mass.T_in

Temperature of incoming air.

assumptions = {'real': True}
latex_name = 'T_{in}'
name = 'T_in'
unit = kelvin
class essm.variables.chamber.mass.T_out

Temperature of outgoing air (= chamber T_a).

assumptions = {'real': True}
latex_name = 'T_{out}'
name = 'T_out'
unit = kelvin
class essm.variables.chamber.mass.T_room

Lab air temperature.

assumptions = {'real': True}
latex_name = 'T_{room}'
name = 'T_room'
unit = kelvin
class essm.variables.chamber.mass.P_w_in

Vapour pressure of incoming air.

assumptions = {'real': True}
latex_name = 'P_{w,in}'
name = 'P_w_in'
unit = pascal
class essm.variables.chamber.mass.P_w_out

Vapour pressure of outgoing air.

assumptions = {'real': True}
latex_name = 'P_{w,out}'
name = 'P_w_out'
unit = pascal
class essm.variables.chamber.mass.R_H_in

Relative humidity of incoming air.

assumptions = {'real': True}
latex_name = 'R_{H,in}'
name = 'R_H_in'
unit = 1
class essm.variables.chamber.mass.L_A

Leaf area.

assumptions = {'real': True}
latex_name = 'L_A'
name = 'L_A'
unit = meter**2

#### Insulation¶

Chamber insulation material.

class essm.variables.chamber.insulation.c_pi

Heat capacity of insulation material.

assumptions = {'real': True}
latex_name = 'c_{pi}'
name = 'c_pi'
unit = joule/(kelvin*kilogram)
class essm.variables.chamber.insulation.lambda_i

Heat conductivity of insulation material.

assumptions = {'real': True}
latex_name = 'lambda_i'
name = 'lambda_i'
unit = joule/(kelvin*meter*second)
class essm.variables.chamber.insulation.rho_i

Density of insulation material.

assumptions = {'real': True}
latex_name = 'rho_i'
name = 'rho_i'
unit = kilogram/meter**3
class essm.variables.chamber.insulation.L_i

Thickness of insulation material.

assumptions = {'real': True}
latex_name = 'L_i'
name = 'L_i'
unit = meter
class essm.variables.chamber.insulation.A_i

Conducting area of insulation material.

assumptions = {'real': True}
latex_name = 'A_i'
name = 'A_i'
unit = meter**2
class essm.variables.chamber.insulation.Q_i

Heat conduction through insulation material.

assumptions = {'real': True}
latex_name = 'Q_i'
name = 'Q_i'
unit = joule/second
class essm.variables.chamber.insulation.dT_i

Temperature increment of insulation material.

assumptions = {'real': True}
latex_name = 'dT_i'
name = 'dT_i'
unit = kelvin

### Leaf¶

Variables related to leaf energy and water balance.

class essm.variables.leaf.radiation.alpha_l

Leaf albedo, fraction of shortwave radiation reflected by the leaf.

assumptions = {'real': True}
latex_name = 'alpha_l'
name = 'alpha_l'
unit = 1
class essm.variables.leaf.radiation.R_d

assumptions = {'real': True}
latex_name = 'R_d'
name = 'R_d'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.R_la

assumptions = {'real': True}
latex_name = 'R_{la}'
name = 'R_la'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.R_ld

Downwards emitted/reflected global radiation from leaf.

assumptions = {'real': True}
latex_name = 'R_{ld}'
name = 'R_ld'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.R_lu

Upwards emitted/reflected global radiation from leaf.

assumptions = {'real': True}
latex_name = 'R_{lu}'
name = 'R_lu'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.R_u

assumptions = {'real': True}
latex_name = 'R_u'
name = 'R_u'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.S_a

assumptions = {'real': True}
latex_name = 'S_a'
name = 'S_a'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.S_b

assumptions = {'real': True}
latex_name = 'S_b'
name = 'S_b'
unit = joule/(meter**2*second)
class essm.variables.leaf.radiation.S_s

assumptions = {'real': True}
latex_name = 'S_s'
name = 'S_s'
unit = joule/(meter**2*second)

#### Energy and Water¶

Unsorted variables related to leaf model.

class essm.variables.leaf.energy_water.alpha_l

Leaf albedo, fraction of shortwave radiation reflected by the leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = '\\alpha_l'
name = 'alpha_l'
unit = 1
class essm.variables.leaf.energy_water.a_s

Fraction of one-sided leaf area covered by stomata.

(1 if stomata are on one side only, 2 if they are on both sides).

assumptions = {'real': True}
domain = 'real'
latex_name = 'a_s'
name = 'a_s'
unit = 1
class essm.variables.leaf.energy_water.a_sh

Fraction of projected area exchanging sensible heat with the air.

assumptions = {'real': True}
default = 2.0
domain = 'real'
latex_name = 'a_{sh}'
name = 'a_sh'
unit = 1
class essm.variables.leaf.energy_water.C_wl

Concentration of water in the leaf air space.

assumptions = {'real': True}
domain = 'real'
latex_name = 'C_{wl}'
name = 'C_wl'
unit = mole/meter**3
class essm.variables.leaf.energy_water.E_lmol

Transpiration rate in molar units.

assumptions = {'real': True}
domain = 'real'
latex_name = 'E_{l,mol}'
name = 'E_lmol'
unit = mole/(meter**2*second)
class essm.variables.leaf.energy_water.E_l

Latent heat flux from leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'E_l'
name = 'E_l'
unit = joule/(meter**2*second)
class essm.variables.leaf.energy_water.epsilon_l

Longwave emmissivity of the leaf surface.

assumptions = {'real': True}
default = 1.0
domain = 'real'
latex_name = '\\epsilon_l'
name = 'epsilon_l'
unit = 1
class essm.variables.leaf.energy_water.g_bw

Boundary layer conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{bw}'
name = 'g_bw'
unit = meter/second
class essm.variables.leaf.energy_water.g_bwmol

Boundary layer conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{bw,mol}'
name = 'g_bwmol'
unit = mole/(meter**2*second)
class essm.variables.leaf.energy_water.Gr

Grashof number.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Gr_L}'
name = 'Gr'
unit = 1
class essm.variables.leaf.energy_water.g_sw

Stomatal conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{sw}'
name = 'g_sw'
unit = meter/second
class essm.variables.leaf.energy_water.g_swmol

Stomatal conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{sw,mol}'
name = 'g_swmol'
unit = mole/(meter**2*second)
class essm.variables.leaf.energy_water.g_tw

Total leaf conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{tw}'
name = 'g_tw'
unit = meter/second
class essm.variables.leaf.energy_water.g_twmol

Total leaf layer conductance to water vapour.

assumptions = {'real': True}
domain = 'real'
latex_name = 'g_{tw,mol}'
name = 'g_twmol'
unit = mole/(meter**2*second)
class essm.variables.leaf.energy_water.h_c

Average 1-sided convective heat transfer coefficient.

assumptions = {'real': True}
domain = 'real'
latex_name = 'h_c'
name = 'h_c'
unit = joule/(kelvin*meter**2*second)
class essm.variables.leaf.energy_water.H_l

Sensible heat flux from leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'H_l'
name = 'H_l'
unit = joule/(meter**2*second)
class essm.variables.leaf.energy_water.L_A

Leaf area.

assumptions = {'real': True}
domain = 'real'
latex_name = 'L_A'
name = 'L_A'
unit = meter**2
class essm.variables.leaf.energy_water.L_l

Leaf width as characteristic length scale for convection.

assumptions = {'real': True}
domain = 'real'
latex_name = 'L_l'
name = 'L_l'
unit = meter
class essm.variables.leaf.energy_water.P_wl

Water vapour pressure inside the leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_{wl}'
name = 'P_wl'
unit = pascal
class essm.variables.leaf.energy_water.r_bw

Boundary layer resistance to water vapour, inverse of $g_{bw}$.

assumptions = {'real': True}
domain = 'real'
latex_name = 'r_{bw}'
name = 'r_bw'
unit = second/meter
class essm.variables.leaf.energy_water.r_sw

Stomatal resistance to water vapour, inverse of $g_{sw}$.

assumptions = {'real': True}
domain = 'real'
latex_name = 'r_{sw}'
name = 'r_sw'
unit = second/meter
class essm.variables.leaf.energy_water.r_tw

Total leaf resistance to water vapour, $r_{bv} + r_{sv}$.

assumptions = {'real': True}
domain = 'real'
latex_name = 'r_{tw}'
name = 'r_tw'
unit = second/meter
class essm.variables.leaf.energy_water.rho_al

Density of air at the leaf surface.

assumptions = {'real': True}
domain = 'real'
latex_name = '\\rho_{al}'
name = 'rho_al'
unit = kilogram/meter**3
class essm.variables.leaf.energy_water.R_la

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_{la}'
name = 'R_la'
unit = watt/meter**2
class essm.variables.leaf.energy_water.R_ll

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_{ll}'
name = 'R_ll'
unit = watt/meter**2
class essm.variables.leaf.energy_water.R_ld

Downwards emitted/reflected global radiation from leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_{ld}'
name = 'R_ld'
unit = watt/meter**2
class essm.variables.leaf.energy_water.R_lu

Upwards emitted/reflected global radiation from leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_{lu}'
name = 'R_lu'
unit = watt/meter**2
class essm.variables.leaf.energy_water.T_l

Leaf temperature.

assumptions = {'real': True}
domain = 'real'
latex_name = 'T_l'
name = 'T_l'
unit = kelvin
class essm.variables.leaf.energy_water.T_w

Radiative temperature of objects surrounding the leaf.

assumptions = {'real': True}
domain = 'real'
latex_name = 'T_w'
name = 'T_w'
unit = kelvin

### Physics¶

General and atmospheric thermodynamics variables.

class essm.variables.physics.thermodynamics.alpha_a

Thermal diffusivity of dry air.

assumptions = {'real': True}
domain = 'real'
latex_name = '\\alpha_a'
name = 'alpha_a'
unit = meter**2/second
class essm.variables.physics.thermodynamics.c_pa

Specific heat of dry air.

assumptions = {'real': True}
default = 1010.0
domain = 'real'
latex_name = 'c_{pa}'
name = 'c_pa'
unit = joule/(kelvin*kilogram)
class essm.variables.physics.thermodynamics.c_pamol

Molar specific heat of dry air.

https://en.wikipedia.org/wiki/Heat_capacity#Specific_heat_capacity

assumptions = {'real': True}
default = 29.19
domain = 'real'
latex_name = 'c_{pa,mol}'
name = 'c_pamol'
unit = joule/(kelvin*mole)
class essm.variables.physics.thermodynamics.c_pv

Specific heat of water vapour at 300 K.

http://www.engineeringtoolbox.com/water-vapor-d_979.html

assumptions = {'real': True}
default = 1864
domain = 'real'
latex_name = 'c_{pv}'
name = 'c_pv'
unit = joule/(kelvin*kilogram)
class essm.variables.physics.thermodynamics.C_wa

Concentration of water in air.

assumptions = {'real': True}
domain = 'real'
latex_name = 'C_{wa}'
name = 'C_wa'
unit = mole/meter**3
class essm.variables.physics.thermodynamics.D_va

Binary diffusion coefficient of water vapour in air.

assumptions = {'real': True}
domain = 'real'
latex_name = 'D_{va}'
name = 'D_va'
unit = meter**2/second
class essm.variables.physics.thermodynamics.g

Gravitational acceleration.

assumptions = {'real': True}
default = 9.81
domain = 'real'
latex_name = 'g'
name = 'g'
unit = meter/second**2
class essm.variables.physics.thermodynamics.Gr

Grashof number.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Gr_L}'
name = 'Gr'
unit = 1
class essm.variables.physics.thermodynamics.h_c

Average 1-sided convective heat transfer coefficient.

assumptions = {'real': True}
domain = 'real'
latex_name = 'h_c'
name = 'h_c'
unit = joule/(kelvin*meter**2*second)
class essm.variables.physics.thermodynamics.k_a

Thermal conductivity of dry air.

assumptions = {'real': True}
domain = 'real'
latex_name = 'k_a'
name = 'k_a'
unit = joule/(kelvin*meter*second)
class essm.variables.physics.thermodynamics.lambda_E

Latent heat of evaporation.

assumptions = {'real': True}
default = 2450000.0
domain = 'real'
latex_name = '\\lambda_E'
name = 'lambda_E'
unit = joule/kilogram
class essm.variables.physics.thermodynamics.Le

Lewis number.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Le}'
name = 'Le'
unit = 1
class essm.variables.physics.thermodynamics.M_air

Molar mass of air.

http://www.engineeringtoolbox.com/molecular-mass-air-d_679.html

assumptions = {'real': True}
default = 0.02897
domain = 'real'
latex_name = 'M_{air}'
name = 'M_air'
unit = kilogram/mole
class essm.variables.physics.thermodynamics.M_N2

Molar mass of nitrogen.

assumptions = {'real': True}
default = 0.028
domain = 'real'
latex_name = 'M_{N_2}'
name = 'M_N2'
unit = kilogram/mole
class essm.variables.physics.thermodynamics.M_O2

Molar mass of oxygen.

assumptions = {'real': True}
default = 0.032
domain = 'real'
latex_name = 'M_{O_2}'
name = 'M_O2'
unit = kilogram/mole
class essm.variables.physics.thermodynamics.M_w

Molar mass of water.

assumptions = {'real': True}
default = 0.018
domain = 'real'
latex_name = 'M_w'
name = 'M_w'
unit = kilogram/mole
class essm.variables.physics.thermodynamics.nu_a

Kinematic viscosity of dry air.

assumptions = {'real': True}
domain = 'real'
latex_name = '\\nu_a'
name = 'nu_a'
unit = meter**2/second
class essm.variables.physics.thermodynamics.Nu

Average Nusselt number over given length.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Nu_L}'
name = 'Nu'
unit = 1
class essm.variables.physics.thermodynamics.P_a

Air pressure.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_a'
name = 'P_a'
unit = pascal
class essm.variables.physics.thermodynamics.Pr

Prandtl number (0.71 for air).

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Pr}'
name = 'Pr'
unit = 1
class essm.variables.physics.thermodynamics.P_N2

Partial pressure of nitrogen.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_{N2}'
name = 'P_N2'
unit = pascal
class essm.variables.physics.thermodynamics.P_O2

Partial pressure of oxygen.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_{O2}'
name = 'P_O2'
unit = pascal
class essm.variables.physics.thermodynamics.P_wa

Water vapour pressure in the atmosphere.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_{wa}'
name = 'P_wa'
unit = pascal
class essm.variables.physics.thermodynamics.P_was

Saturation water vapour pressure at air temperature.

assumptions = {'real': True}
domain = 'real'
latex_name = 'P_{was}'
name = 'P_was'
unit = pascal
class essm.variables.physics.thermodynamics.R_d

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_d'
name = 'R_d'
unit = watt/meter**2
class essm.variables.physics.thermodynamics.Re_c

Critical Reynolds number for the onset of turbulence.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Re_c}'
name = 'Re_c'
unit = 1
class essm.variables.physics.thermodynamics.Re

Average Reynolds number over given length.

assumptions = {'real': True}
domain = 'real'
latex_name = 'N_{Re_L}'
name = 'Re'
unit = 1
class essm.variables.physics.thermodynamics.rho_a

Density of dry air.

assumptions = {'real': True}
domain = 'real'
latex_name = '\\rho_a'
name = 'rho_a'
unit = kilogram/meter**3
class essm.variables.physics.thermodynamics.R_u

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_u'
name = 'R_u'
unit = watt/meter**2
class essm.variables.physics.thermodynamics.R_mol

Molar gas constant.

assumptions = {'real': True}
default = 8.314472
domain = 'real'
latex_name = 'R_{mol}'
name = 'R_mol'
unit = joule/(kelvin*mole)
class essm.variables.physics.thermodynamics.R_s

Solar shortwave flux per area.

assumptions = {'real': True}
domain = 'real'
latex_name = 'R_s'
name = 'R_s'
unit = joule/(meter**2*second)
class essm.variables.physics.thermodynamics.sigm

Stefan-Boltzmann constant.

assumptions = {'real': True}
default = 5.67e-08
domain = 'real'
latex_name = '\\sigma'
name = 'sigm'
unit = joule/(kelvin**4*meter**2*second)
class essm.variables.physics.thermodynamics.T0

Freezing point in Kelvin.

assumptions = {'real': True}
default = 273.15
domain = 'real'
latex_name = 'T_0'
name = 'T0'
unit = kelvin
class essm.variables.physics.thermodynamics.T_a

Air temperature.

assumptions = {'real': True}
domain = 'real'
latex_name = 'T_a'
name = 'T_a'
unit = kelvin
class essm.variables.physics.thermodynamics.v_w

Wind velocity.

assumptions = {'real': True}
domain = 'real'
latex_name = 'v_w'
name = 'v_w'
unit = meter/second
class essm.variables.physics.thermodynamics.x_N2

Mole fraction of nitrogen in dry air.

assumptions = {'real': True}
default = 0.79
domain = 'real'
latex_name = 'x_{N2}'
name = 'x_N2'
unit = 1
class essm.variables.physics.thermodynamics.x_O2

Mole fraction of oxygen in dry air.

assumptions = {'real': True}
default = 0.21
domain = 'real'
latex_name = 'x_{O2}'
name = 'x_O2'
unit = 1

### Units¶

Define unit symbols.

essm.variables.units.derive_baseunit(expr, name=None)[source]

Derive SI base unit from an expression, omitting scale factors.

essm.variables.units.derive_unit(expr, name=None)[source]

Derive SI unit from an expression, omitting scale factors.

essm.variables.units.markdown(unit)[source]

Return markdown representation of a unit.

## Equations¶

Equations module to deal with physical equations.

It allows attaching docstrings to equation names (including references) and defining internal variables.

### Creating equations¶

To create custom equations, first import Equation and variables needed:

>>> from essm.equations import Equation
>>> from essm.variables.physics.thermodynamics import *


### Importing pre-defined equations¶

You can import pre-defined equations as e.g.:

>>> from essm.equations.physics.thermodynamics import *


### Leaf¶

Equations related to leaf energy and water balance.

#### Energy Water¶

Leaf energy and water balance equations.

class essm.equations.leaf.energy_water.eq_Rs_enbal

Calculate R_s from energy balance.

(Eq. 1 in [SO17])

expr = Eq(R_s, E_l + H_l + R_ll)
name = 'eq_Rs_enbal'
class essm.equations.leaf.energy_water.eq_Rll

R_ll as function of T_l and T_w.

(Eq. 2 in [SO17])

expr = Eq(R_ll, a_sh*epsilon_l*sigm*(T_l**4 - T_w**4))
name = 'eq_Rll'
class essm.equations.leaf.energy_water.eq_Hl

H_l as function of T_l.

(Eq. 3 in [SO17])

expr = Eq(H_l, a_sh*h_c*(-T_a + T_l))
name = 'eq_Hl'
class essm.equations.leaf.energy_water.eq_El

E_l as function of E_lmol.

(Eq. 4 in [SO17])

expr = Eq(E_l, E_lmol*M_w*lambda_E)
name = 'eq_El'
class essm.equations.leaf.energy_water.eq_Elmol

E_lmol as functino of g_tw and C_wl.

(Eq. 5 in [SO17])

expr = Eq(E_lmol, g_tw*(-C_wa + C_wl))
name = 'eq_Elmol'
class essm.equations.leaf.energy_water.eq_gtw

g_tw from g_sw and g_bw.

(Eq. 6 in [SO17])

expr = Eq(g_tw, 1/(1/g_sw + 1/g_bw))
name = 'eq_gtw'
class essm.equations.leaf.energy_water.eq_gbw_hc

g_bw as function of h_c.

(Eq. B2 in [SO17])

expr = Eq(g_bw, a_s*h_c/(Le**(2/3)*c_pa*rho_a))
name = 'eq_gbw_hc'
class essm.equations.leaf.energy_water.eq_Cwl

C_wl as function of P_wl and T_l.

(Eq. B4 in [SO17])

expr = Eq(C_wl, P_wl/(R_mol*T_l))
name = 'eq_Cwl'
class essm.equations.leaf.energy_water.eq_Pwl

Clausius-Clapeyron P_wl as function of T_l.

(Eq. B3 in [Har94])

expr = Eq(P_wl, p_CC1*exp(-M_w*lambda_E*(-1/p_CC2 + 1/T_l)/R_mol))
name = 'eq_Pwl'
p_CC1 = p_CC1
p_CC2 = p_CC2
class essm.equations.leaf.energy_water.eq_Elmol_conv

E_lmol as function of g_twmol and P_wl.

(Eq. B6 in [SO17])

expr = Eq(E_lmol, g_twmol*(-P_wa + P_wl)/P_a)
name = 'eq_Elmol_conv'
class essm.equations.leaf.energy_water.eq_gtwmol_gtw

g_twmol as a function of g_tw.

It uses eq_Elmol, eq_Cwl and eq_Elmol_conv.

expr = Eq(g_twmol, g_tw*(P_a*P_wa*T_l - P_a*P_wl*T_a)/(R_mol*T_a*T_l*(P_wa - P_wl)))
name = 'eq_gtwmol_gtw'
class essm.equations.leaf.energy_water.eq_gtwmol_gtw_iso

g_twmol as a function of g_tw at isothermal conditions.

expr = Eq(g_twmol, P_a*g_tw/(R_mol*T_a))
name = 'eq_gtwmol_gtw_iso'
class essm.equations.leaf.energy_water.eq_hc

h_c as a function of Nu and L_l.

(Eq. B10 in [SO17])

expr = Eq(h_c, Nu*k_a/L_l)
name = 'eq_hc'
class essm.equations.leaf.energy_water.eq_Re

Re as a function of v_w and L_l.

(Eq. B11 in [SO17])

expr = Eq(Re, L_l*v_w/nu_a)
name = 'eq_Re'
class essm.equations.leaf.energy_water.eq_Gr

Gr as function of air density within and outside of leaf.

(Eq. B12 in [SO17])

expr = Eq(Gr, L_l**3*g*(rho_a - rho_al)/(nu_a**2*rho_al))
name = 'eq_Gr'

### Physics¶

General and atmospheric thermodynamics equations.

class essm.equations.physics.thermodynamics.eq_Le

Le as function of alpha_a and D_va.

(Eq. B3 in [SO17])

expr = Eq(Le, alpha_a/D_va)
name = 'eq_Le'
class essm.equations.physics.thermodynamics.eq_Cwa

C_wa as a function of P_wa and T_a.

(Eq. B9 in [SO17])

expr = Eq(C_wa, P_wa/(R_mol*T_a))
name = 'eq_Cwa'
class essm.equations.physics.thermodynamics.eq_Nu_forced_all

Nu as function of Re and Re_c under forced conditions.

(Eqs. B13–B15 in [SO17])

expr = Eq(Nu, -Pr**(1/3)*(-37*Re**(4/5) + 37*(Re + Re_c - Abs(Re - Re_c)/2)**(4/5) - 664*sqrt(Re + Re_c - Abs(Re - Re_c)/2))/1000)
name = 'eq_Nu_forced_all'
class essm.equations.physics.thermodynamics.eq_Dva

D_va as a function of air temperature.

(Table A.3 in [MU07])

expr = Eq(D_va, T_a*p_Dva1 - p_Dva2)
name = 'eq_Dva'
p_Dva1 = p_Dva1
p_Dva2 = p_Dva2
class essm.equations.physics.thermodynamics.eq_alphaa

alpha_a as a function of air temperature.

(Table A.3 in [MU07])

expr = Eq(alpha_a, T_a*p_alpha1 - p_alpha2)
name = 'eq_alphaa'
p_alpha1 = p_alpha1
p_alpha2 = p_alpha2
class essm.equations.physics.thermodynamics.eq_ka

k_a as a function of air temperature.

(Table A.3 in [MU07])

expr = Eq(k_a, T_a*p_ka1 + p_ka2)
name = 'eq_ka'
p_ka1 = p_ka1
p_ka2 = p_ka2
class essm.equations.physics.thermodynamics.eq_nua

nu_a as a function of air temperature.

(Table A.3 in [MU07])

expr = Eq(nu_a, T_a*p_nua1 - p_nua2)
name = 'eq_nua'
p_nua1 = p_nua1
p_nua2 = p_nua2
class essm.equations.physics.thermodynamics.eq_rhoa_Pwa_Ta

rho_a as a function of P_wa and T_a.

(Eq. B20 in [SO17])

expr = Eq(rho_a, (M_N2*P_N2 + M_O2*P_O2 + M_w*P_wa)/(R_mol*T_a))
name = 'eq_rhoa_Pwa_Ta'
class essm.equations.physics.thermodynamics.eq_Pa

Calculate air pressure.

From partial pressures of N2, O2 and H2O, following Dalton’s law of partial pressures.

expr = Eq(P_a, P_N2 + P_O2 + P_wa)
name = 'eq_Pa'
class essm.equations.physics.thermodynamics.eq_PN2_PO2

Calculate P_N2 as a function of P_O2.

It follows Dalton’s law of partial pressures.

expr = Eq(P_N2, P_O2*x_N2/x_O2)
name = 'eq_PN2_PO2'
class essm.equations.physics.thermodynamics.eq_PO2

Calculate P_O2 as a function of P_a, P_N2 and P_wa.

expr = Eq(P_O2, (P_a*x_O2 - P_wa*x_O2)/(x_N2 + x_O2))
name = 'eq_PO2'
class essm.equations.physics.thermodynamics.eq_PN2

Calculate P_N2 as a function of P_a, P_O2 and P_wa.

expr = Eq(P_N2, (P_a*x_N2 - P_wa*x_N2)/(x_N2 + x_O2))
name = 'eq_PN2'
class essm.equations.physics.thermodynamics.eq_rhoa

Calculate rho_a from T_a, P_a and P_wa.

expr = Eq(rho_a, (x_N2*(M_N2*P_a - P_wa*(M_N2 - M_w)) + x_O2*(M_O2*P_a - P_wa*(M_O2 - M_w)))/(R_mol*T_a*x_N2 + R_mol*T_a*x_O2))
name = 'eq_rhoa'

## Internals¶

Core variable type.

class essm.variables._core.Variable[source]

Bases: object

Base type for all physical variables.

static check_unit(expr)[source]

Check if base dimensions of expression are consistent.

Checks for dimension mismatches of the addends, thus preventing expressions like meter + second to be created.

static collect_factor_and_basedimension(expr)[source]

Return tuple with factor expression and dimension expression.

static get_dimensional_expr(expr)[source]

Return dimensions of expression.

Core equation type. Contains class definitions related to equations.

class essm.equations._core.Equation[source]

Bases: object

Base type for all equations.

classmethod args()[source]

Return equation arguments from registry if exist.

class essm.equations._core.EquationMeta[source]

Bases: essm.bases.RegistryType

Equation interface.

Defines an equation with a docstring and internal variables, if needed.

Example:

from ..variables.units import meter, second
class test(Equation):
'''Test equation.'''

class d(Variable):
'''Internal variable.'''
unit = meter

class t(Variable):
'''Internal variable.'''
unit = second

class v(Variable):
'''Internal variable.'''
unit = meter/second

expr = v == d / t

Raises: ValueError – if the units are inconsistent.

Example:

from ..variables.units import meter, second
class test(Equation):
'''Test equation with inconsistent units.'''

class d(Variable):
'''Internal variable.'''
unit = meter

class t(Variable):
'''Internal variable.'''
unit = second

class v(Variable):
'''Internal variable.'''
unit = meter/second

expr = v == d * t


Since the units of v and d*t are not the same, this returns:

ValueError: Invalid expression units: meter/second == meter*second


Build and register new variable.