Tree Box Model documentation

Details of the model

• Description of the modelled system
  • Introduction
  • Input and output of the model
  • The fluxes inside the tree
  • How the root water uptake is modelled
  • The change of pressure, sugar concentration and element radius due to sap flux
  • Sugar loading and unloading rates
  • How the element radii are modelled
• Instructions to run the model
  • Running from main.py
  • Importing src.model

Installation

• Download the source

>>> git clone git@github.com:LukeEcomod/TreeBoxModel.git

or

download the source https://github.com/LukeEcomod/TreeBoxModel

• Install the required packages

Ideally you have created a new virtual environment for this project.

To install all the packages required for the model to run use

>>> pip install -r requirements_pip.txt

Quick start

run main.py.

>>> python main.py

See instructions to run the model for detailed instructions.

main.py

The purpose of this main file is to provide an easy way to run the model.

The model parameters for the modelled tree are set in the file and taken from Hölttä et. al. 2006 or Nikinmaa et. al., (2014).

A sine-like behaviour is assumed for the transpiration and photosynthesis

Modules, Classes & functions

class src.model.Model(tree: src.tree.Tree, soil: src.soil.Soil, outputfile: str = '')

Calculates the next time step for given tree and saves the tree stage.

Provides functionality for solving the ordinary differential equations (ODE) describing the behaviour of the modelled system.

Parameters

• tree (Tree) – instance of the tree class for which the ODEs are solved

• outputfile (str) – name of the file where the NETCDF4 output is written

tree

instance of the tree class for which the ODEs are solved

Type

Tree

ncf

the output file

Type

netCDF4.Dataset

axial_fluxes() → numpy.ndarray

Calculates axial sap mass flux for every element.

The axial flux in the xylem and phloem are calculated independently from the sum of bottom and top fluxes.

\[Q_{ax,i} = Q_{ax,bottom,i} + Q_{ax,top,i} - E\]

\[ \begin{align}\begin{aligned}Q_{ax,bottom,i} = \frac{k_i \: A_{ax,i} \: \rho_w}{\eta_i \: l_i}(P_{i+1} - P_{i} - P_h)\\Q_{ax,top,i} = \frac{k_i \: A_{ax,i+1} \: \rho_w}{\eta_i \: l_i}(P_{i-1} - P_{i} + P_h)\end{aligned}\end{align} \]

where

• \(E_i\): transpiration rate of the ith element (\(\frac{kg}{s}\))

• \(k_i\): axial permeability of the ith element (\(m^2\))

• \(A_{ax,i}\): base surface area of xylem or phloem (\(m^2\))

• \(\rho_w\): liquid phase density of water (\(\frac{kg}{m^3}\))

• \(\eta\): viscosity of the sap in the ith element (\(Pa \: s\))

• \(l_i\): length (height) of the ith element (\(m\))

• \(P_{i}\): Pressure in the ith element (\(Pa\))

• \(P_h\): Hydrostatic pressure (\(Pa\)) \(P_h = \rho_w a_{gravitation} l_i\)

Returns

numpy.ndarray (dtype=float, ndim=2)[self.tree.num_elements, 2] – The axial fluxes in units kg/s

properties_to_dict() → Dict

Transfers tree properties into a dictionary.

Parameters

tree (Tree) – Instance of the tree class.

Returns

(Dict) – Dictionary of the tree properties.

radial_fluxes() → numpy.ndarray

Calculates radial sap mass flux for every element.

The radial flux for the phloem of the ith axial is calculated similar to Hölttä et. al. 2006

\[Q_{radial,phloem} = L_r A_{rad,i}\rho_{w} [P_{i,xylem} - P_{i,phloem} - \sigma(C_{i,xylem} - C_{i,phloem})RT)]\]

where

• \(L_r\): radial hydraulic conductivity (\(\frac{m}{Pa \: s}\))

• \(A_{rad,i}\): lateral surface area of the xylem (\(m^2\))

• \(\rho_w\): liquid phase density of water (\(\frac{kg}{m^3}\))

• \(P_{i}\): Pressure in the ith element (\(Pa\))

• \(\sigma\): Reflection coefficient (Van’t hoff factor) (unitless)

• \(C_{i}\): Sucrose concentration in the ith element (\(\frac{mol}{m^3}\))

• \(R\): Universal gas constant (\(\frac{J}{K \: mol}\))

• \(T\): Ambient temperature (\(K\))

The radial flux for the xylem is equal to the additive inverse of the phloem flux

\[Q_{radial,xylem} = -Q_{radial,phloem}\]

Returns

numpy.ndarray (dtype=float, ndim=2)[self.tree.num_elements, 2] – The radial fluxes in units kg/s

root_fluxes()

Calculates root water uptake for every element. If the part of the tree is not part of the root system, the flux is set to zero.

Conductance between soil and root xylem is calculated similar to Volpe et. al. 2013

\[Q_{root,i} = \frac{g_i}{g} (P_{soil,i} - P_{root,xylem,i})\]

where

• \(g_i\): Total conductance from soil to root xylem (\(\frac{1}{s}\)). See

  Roots class for details

• \(g\): gravitational acceleration (\(\frac{m}{s^2}\))

• \(P\): Pressure in either the soil element or root xylem element

The resulting flux has units :math:\frac{kg}{m^2s} and it is assumed that this flux is multiplied with soil area per tree which is assumed to equal 1

Returns

numpy.ndarray (dtype=float, ndim=2)[self.tree.num_elements, 1] – The root water uptake in units kg/s

References

Volpe, V. et. al., “Root controls on water redistribution and carbon uptake in the soil–plant system under current and future climate”, Advances in Water Resources, 60, 110-120, 2013.

run(time_start: float = 0.001, time_end: float = 120.0, dt: float = 0.01, output_interval: float = 60) → None

Propagates the tree in time using explicit Euler method (very slow).

NB! This function needs to be updated. Use run_scipy instead!

Parameters

• time_start (float) – Time in seconds where to start the simulation.

• time_ned (float) – Time in seconds where to end the simulation.

• dt (float) – time step in seconds

• output_interval – Time interval in seconds when to save the tree stage

run_scipy(time_start: float = 0.001, time_end: float = 120.0, ind: int = 0) → None

Propagates the tree in time using the solve_ivp function in the SciPy package.

The stage of the tree is saved only at the start of the simulation if time_start < 1e-3 and at time_end. If the tree stage is desired on multiple time points the function needs to be called recurrently by splitting the time interval into multiple sub intervals.

Parameters

• time_start (float) – Time in seconds where to start the simulation.

• time_ned (float) – Time in seconds where to end the simulation.

• ind (int) – index which refers to the index in self.outputfile. The last stage of the tree is saved to self.outputfile[ind].

class src.tree.Tree(height: float, element_height: List[float], initial_radius: List[float], num_elements: int, transpiration_profile: List[float], photosynthesis_profile: List[float], sugar_profile: List[float], sugar_loading_profile: List[float], sugar_unloading_profile: List[float], sugar_target_concentration: float, sugar_unloading_slope: float, axial_permeability_profile: List[List[float]], radial_hydraulic_conductivity_profile: List[float], elastic_modulus_profile: List[List[float]], roots: src.roots.Roots, temperature: float = 298.15, space_division: Optional[List[float]] = None)

Model of a tree.

Provides properties and functionality for saving and editing the modelled tree. Arguments whose type is List[float] or List[List[float]] are converted to numpy.ndarray with numpy.asarray method. Thus, also numpy.ndarray is a valid type for these arguments.

For arguemnts whose type is List[float] (except for initial_radius) the length of the arguments must be equal to num_elements. The order of the list should be from the top of the tree (the first item) to the bottom of the tree (the last item)

For arguments whose type is List[List[float]] the length of the arguemnts must be equal to num_elements and each sub list must contain two elements, one for the xylem and one for the phloem in this order. The order of the sub lists should be from the top of the tree (the first sub list) to the bottom of the tree (the last sub list).

Parameters

• height (float) – total tree height (\(m\))

• initial_radius (List[float] or numpy.ndarray) –

  the radius of the heartwood, xylem and phloem (\(m\)) in this order. See from the modelled system, how the radii should be given. Only three values can be given and the radius of each element is set to be the same in the tree initialization.

• num_elements (int) – number of vertical elemenets in the tree. The height of an element is determined by \(\text{element height} = \frac{\text{tree height}}{\text{number of elements}}\)

• transpiration_profile (List[float] or numpy.ndarray) – The rate of transpiration (\(\frac{kg}{s}\)) in the xylem. The length of the list must be equal to num_elements and the order is from the top of the tree (first value) in the list to the bottom of the tree (last value in the list).

• photosynthesis_profile (List[float]) – The rate of photosynthesis (\(\frac{mol}{s}\)). Currently this variable is not used and the rate of photosynthesis should be equal to the sugar_loading_profile.

• sugar_profile (List[float]] or numpy.ndarray) – The initial sugar (sucrose) concentration in the phloem (\(\frac{mol}{m^3}\))

• sugar_loading_profile (List[List[float]] or numpy.ndarray) – the rate at which sugar concentration increases in each phloem element (\(\frac{mol}{s}\))

• sugar_unloading_profile (List[float] or numpy.ndarray) – The initial sugar unloading rate (the rate at which the sugar concentration decreases in a given phloem element) (\(\frac{mol}{s}\)). The unloading rate is updated in src.odefun.odefun.

• sugar_target_concentration (float) – the target concentration after which the sugar unloading starts (\(\frac{mol}{m^3}\))

• sugar_unloading_slope (float) –

  the slope parameter for unloading (see Nikinmaa et. al., (2014)).

• axial_permeability_profile (List[List[float]] or numpy.ndarray) – axial permeabilities of both xylem and phloem (\(m^2\))

• radial_hydraulic_conductivity_profile (List[float]] or numpy.ndarray) – radial hydraulic conductivity between the xylem and the phloem (\(\frac{m}{Pa \: s}\))

• elastic_modulus_profile (List[List[float]] or numpy.ndarray) – Elastic modulus of every element (\(Pa\)).

• temperature (float) – Temperature of the tree (\(K\))

• space_division (List[float] or numpy.ndarray) – fraction of air, water and cell in each element in this order. Only one value for each element

height

total tree height (\(m\))

Type

float

num_elements

number of vertical elemenets in the tree.

Type

float

space_division

Space division of air, water and cell in the tree. Only one value per air, water or cell for all elements.

Type

numpy.ndarray(dtype=float, ndim=1), [3,]

transpiration_rate

The rate of transpiration (\(\frac{kg}{s}\)) in the xylem.

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 1]

photosynthesis_rate

The rate of photosynthesis (\(\frac{mol}{s}\)). Currently this variable is not used.

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 1]

sugar_loading_rate

The rate at which sugar concentration increases in each phloem element (\(\frac{mol}{s}\)).

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 1]

sugar_unloading_rate

The rate at which the sugar concentration decreases in a given phloem element (\(\frac{mol}{s}\)).

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 1]

sugar_target_concentration

The target concentration after which the sugar unloading starts (\(\frac{mol}{m^3}\)).

Type

float

sugar_unloading_slope

The slope parameter for unloading (see [Nikinmaa et. al., (2014)](https://academic.oup.com/aob/article/114/4/653/2769025)).

Type

float

solutes

Array of src.solute.Solute which contain the solutes in the sap of xylem and phloem.

Type

numpy.ndarray(dtype=src.solute.Solute, ndim=2) [tree.num_elements, 2]

axial_permeability

Axial permeabilities of both xylem and phloem (\(m^2\)).

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 2]

radial_hydraulic_conductivity

Radial hydraulic conductivity between the xylem and the phloem (\(\frac{m}{Pa \: s}\)).

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 1]

elastic_modulus

Elastic modulus of every element (\(Pa\)).

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 2]

ground_water_potential

The water potential in the soil.

Type

float

pressure

Pressure of each element (\(Pa\))

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 2]

element_radius

Radius of each element (\(m\))

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 3]

element_height

Height of each element (\(m\))

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 2]

viscosity

The dynamic viscosity of each element (\(Pa \: s\))

Type

numpy.ndarray(dtype=float, ndim=2) [tree.num_elements, 2]

cross_sectional_area(ind: Optional[List[int]] = None) → numpy.ndarray

Calculates the cross-sectional area between the xylemn and the phloem.

The cross sectional area is equal to lateral surface area of the xylem.

Parameters

ind (List[int] or numpy.ndarray(dtype=int, ndim=1), optional) – the indices of the elements for which the cross-sectinoal area is calculated. If no ind is given, the cross-sectional area is calculated for every element.

Returns

numpy.ndarray(dtype=float, ndim=2) [len(ind) or self.num_elements, 1] – Cross-sectional area between the xylem and phloem elements (\(m^2\))

element_area(ind: Optional[List[int]] = None, column: int = 0) → numpy.ndarray

Calculates the base area of the xylem or the phloem.

Parameters

• ind (List[int] or numpy.ndarray(dtype=int, ndim=1), optional) – the indices of the elements for which the base area is calculated. If no ind is given, the base area is calculated for every element.

• column (int, optional) – The column in the tree grid for which the base area is calculated. use column=0 for the xylem and column=1 for the phloem. If not column is given returns the base area for the xylem.

Returns

numpy.ndarray(dtype=float, ndim=2) [len(ind) or self.num_elements, 1] – Base area of either the xylem or the phloem (\(m^2\))

element_volume_water(ind: Optional[List[int]] = None, column: int = 0) → numpy.ndarray

Calculates the volume of the xylem or the phloem.

Parameters

• ind (List[int] or numpy.ndarray(dtype=int, ndim=1), optional) – the indices of the elements for which the volume is calculated. If no ind is given, the volume is calculated for every element.

• column (int, optional) – The column in the tree grid for which the volume is calculated. use column=0 for the xylem and column=1 for the phloem. If not column is given returns the volume for the xylem.

Returns

numpy.ndarray(dtype=float, ndim=2) [len(ind) or self.num_elements, 1] – Volume of either the xylem or the phloem (\(m^3\))

sugar_concentration_as_numpy_array() → numpy.ndarray

Transforms the phloem sugar concentration in self.solutes into numpy.ndarray.

Returns

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1] – The sugar concentration in the phloem. (\(\frac{mol}{m^3}\))

update_sap_viscosity() → None

Calculates and sets the viscosity in the phloem according to the sugar concenration.

The sap viscosity is calculated according to Morrison (2002)

\[\eta = \eta_w \exp{\frac{4.68 \cdot 0.956 \Phi_s}{1-0.956 \Phi_s}}\]

where

• \(\eta_w\): Dynamic viscosity of water (\(\eta_w \approx 0.001\))

• \(\Phi_s\): Volume fraction of sugar (sucrose) in the phloem sap.

References

Morison, Ken R. “Viscosity equations for sucrose solutions: old and new 2002.” Proceedings of the 9th APCChE Congress and CHEMECA. 2002.

update_sugar_concentration(new_concentration: numpy.ndarray) → None

Sets the sugar concentration in self.solutes to new_concentration.

Parameters

new_concentration (numpy.ndarray(dtype=float, ndim=2)[self.num_elements,1]) – new concentration values. the order is from top of the tree (first element, new_concentration[0]) to bottom of the tree (last element, new_concentration[self.num_elements-1]) (\(\frac{mol}{m^3}\))

class src.solute.Solute(name: str, molar_mass: float, density: float, concentration: float)

Contains the variables to model a solute compound

Parameters

• name (str) – Name of the compound

• molar_mass (float) – Molar mass of the compound (\(\frac{kg}{mol}\))

• density – Liquid phase density of the compound (\(\frac{kg}{m^3}\))

• concentration – Concentration of the compound in the sap solution (\(\frac{mol}{m^3}\))

concentration: float

density: float

molar_mass: float

name: str

class src.soil.Soil(layer_thickness, pressure, hydraulic_conductivity)

Model of a soil. Each array should have the same length except for the depth array whose length should be one higher than all the other arrays

Parameters

• layer_thickness (List[float] or numpy.ndarray) – Thickness of each layer in units \(m\).

• pressure (List[float] or numpy.ndarray) – Pressure (soil water potential) in every layer in units \(Pa\)

• hydraulic_conductivity (List[float] or numpy.ndarray) – Hydraulic conductivity in each soil layer in units \(\frac{m}{s}\)

layer_thickness

Thickness of each layer in units \(m\).

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

pressure

Pressure (soil water potential) in every layer in units \(Pa\)

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

hydraulic_conductivity

Hydraulic conductivity in each soil layer in units \(\frac{m}{s}\)

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

num_elements

Number of soil elements. Calculated from the length of layer_thickness argument.

Type

float

depth() → numpy.ndarray

Returns the midpoint of every soil element

class src.roots.Roots(rooting_depth: float, area_density: numpy.ndarray, effective_radius: numpy.ndarray, soil_conductance_scale: float, area_per_tree: float, num_elements: int)

Model of the root system of the tree. The number of elements (layers) is calculated from the length

of the area density variable. All the arrays should have the same length.

Parameters

• rooting_depth (float) – depth of the root system in the soil (\(m\))

• area_density (List[float] or numpy.ndarray) – surface area of roots in given layer per tree

• per soil layer thickness (and) –

• radius (effective) – effective horizontal root radius in a layer

• soil_conductance_scale (List[float] or numpy.ndarray) – typical soil conductance in a layer.

• area_per_tree (float) – area of soil that the tree takes. Used in calculating root area density.

• num_elements (int) – number of elements in the root zone.

rooting_depth

depth of the root system in the soil (\(m\))

Type

float

area_density

surface area of roots in given layer per tree and per soil layer thickness (\(\frac{m^2}{m}\))

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

effective radius

effective horizontal root radius in a layer

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

soil_conductance_scale

typical soil to root xylem conductance in a layer (\(s\))

Type

numpy.ndarray(dtype=float, ndim=2) [self.num_elements, 1]

area_per_tree

Surface area ground that the tree takes. Used in calculating root area density.

Type

float

conductivity(soil: src.soil.Soil) → numpy.ndarray

Calculates the total conductivity \(g_i\) in each root/soil layer.

The total conductivity is calculated according to Volpe et al., (2013)

\[g_i = \frac{k_{s,i} k_{r,i}}{k_{s,i}+k_{r,i}}\]

where

• \(k_{s,i}\): Conductance from soil to near the root system in root layer i. See

  soil_root_conductance for details

• \(k_{r,i}\): Conductance from near the root system to the root xylem in root layer i. See

  root_conductance for details.

Parameters

soil (Soil) – Instance of the soil class.

Returns

numpy.ndarray (dtype=float, ndim=2)[self.tree.num_elements, 1] – Total conductance from soil to the root xylem in all the root layers in units \(\frac{1}{s}\).

References

Volpe, V. et. al., “Root controls on water redistribution and carbon uptake in the soil–plant system under current and future climate”, Advances in Water Resources, 60, 110-120, 2013.

layer_depth(soil: src.soil.Soil) → numpy.ndarray

Returns the midpoint depth of every layer that has roots.

Parameters

soil (Soil) – Instance of the soil class.

Returns

numpy.ndarray(dtype=float, ndim=2)[self.num_elements+1,1] – Layer depth relative to surface in units \(m\).

layer_thickness(soil: src.soil.Soil) → numpy.ndarray

Returns the layer thickness from soil surface until the self.rooting_depth.

Parameters

soil (Soil) – Instance of the soil class.

Returns

numpy.ndarray(dtype=float, ndim=2)[n,1] – Layer thickness in units \(m\). n is the amount of soil layers whose depth is smaller than the rooting depth of the root system.

root_area_index(soil: src.soil.Soil) → float

Calculates the root area index i.e.

\[RAI = \frac{\sum_{i=1}^{N} B_i \Delta z_i}{A_{tree}}\]

where \(B_i\) is the root area density, \(\Delta z_i\) is the thickness of layer i and \(A_{tree}\) is the area of ground that the tree takes.

NB! the soil depth must match the depth for which Roots.area_density is given.

Parameters

soil (Soil) – Instance of the soil unit class. The soil layer thicknesses is used in calculation.

Returns

float – The root area index (\(\frac{m^2}{m^2}\))

root_conductance(soil: src.soil.Soil, ind: Optional[List[int]] = None) → numpy.ndarray

calculates to conductance from soil-root interface up to the xylem of the tree which is

\(k_{r,i}\) in Volpe et al., (2013).

\[k_{r,i} = \frac{B_i \Delta z_i}{\beta A_{tree}}\]

where \(B_i\) is the root area density, \(\Delta z_i\) is the thickness of layer i, \(\beta\) is typical root to soil conductance as presented in Volpe et. al., (2013) and \(A_{tree}\) is the area of ground that the tree takes.

Parameters

• soil (Soil) – Instance of the soil unit class. The soil layer thicknesses is used in calculation.

• ind (List[int] or numpy.ndarray(dtype=int, ndim=1), optional) – the indices of the elements for which conductance is calculated. If no ind is given, the cross-sectional area is calculated for every element.

Returns

numpy.ndarray(dtype=float, ndim=2) [len(ind) or self.num_elements, 1] – conductance from root-soil interface to root xylem (\(s^{-1}\))

References

Volpe, V. et. al., “Root controls on water redistribution and carbon uptake in the soil–plant system under current and future climate”, Advances in Water Resources, 60, 110-120, 2013.

soil_elements(soil: src.soil.Soil) → numpy.ndarray

Returns array of elements in the soil object whose depth is above rooting depth

Parameters

soil (Soil) – Instance of the soil class.

Returns

numpy.ndarray(dtype=int, ndim=1)[n,] – array of elements in the soil object for which the layer depth is smaller than the rooting depth.

soil_root_conductance(soil: src.soil.Soil, ind: Optional[List[int]] = None) → numpy.ndarray

Calculates the conductance in layer i which is \(k_{s,i}\) in Volpe et al., (2013)

which is the horizontal conductance in soil to the soil-root interface.

\[k_{s,i} = \alpha K_i \frac{B_i}{A_{tree}}\]

where \(K_i\) is the water hydraulic conductivity in layer i, \(B_i\) is the root area density in layer i and

\(\alpha = \left(\frac{L A_{tree}}{2RAI \cdot r_i}\right)^{1/2}\)

where \(L\) is the rooting depth, RAI is the root area index, \(r_i\) is the effective root radius in layer i and \(A_{tree}\) is the area of ground that the tree takes.

Parameters

• soil (Soil) – Instance of the soil class. The soil layer thicknesses is used in calculation.

• ind (List[int] or numpy.ndarray(dtype=int, ndim=1), optional) – the indices of the elements for which conductance is calculated. If no ind is given, the cross-sectional area is calculated for every element.

Returns

numpy.ndarray(dtype=float, ndim=2) [len(ind) or self.num_elements, 1] – conductance from root-soil interface to root xylem (\(s^{-1}\))

References

Volpe, V. et. al., “Root controls on water redistribution and carbon uptake in the soil–plant system under current and future climate”, Advances in Water Resources, 60, 110-120, 2013.

src.constants.MAX_ELEMENT_COLUMNS: int = 2

Max number of columns in the tree class

src.constants.M_WATER: float = 0.0182

Molar mass of water \(\left(\frac{kg}{mol}\right)\)

src.constants.RHO_WATER: float = 1000

density of liquid water \(\left(\frac{kg}{m^3}\right)\)

src.constants.VISCOSITY_WATER: float = 0.001

dynamic viscosity of water \(\left( Pa \cdot s \right)\)

src.constants.M_SUCROSE: float = 0.3423

molar mass of sucrose \(\left(\frac{kg}{mol}\right)\)

src.constants.RHO_SUCROSE: float = 1590.0

density of sucrose \(\left(\frac{kg}{m^3}\right)\)

src.constants.GRAVITATIONAL_ACCELERATION: float = 9.81

acceleration due to Earth’s gravity \(\left(\frac{m}{s^2}\right)\)

src.constants.AVOGADROS_CONSTANT: float = 6.022e+23

avogadro’s constant \(\left(\frac{1}{mol}\right)\)

src.constants.MOLAR_GAS_CONSTANT: float = 8.3145

molar gas constant \(\left(\frac{J}{K \cdot mol}\right)\)

src.model_variables = Name, descriptions, unit, dimension and precision of each variable that is saved to the netcdf dataset

src.tools.iotools.gas_properties_to_dict(gas) → Dict

Transfers gas properties into a dictionary.

Parameters

gas (Gas) – Instance of the Gas class.

Returns

(Dict) – Dictionary of the gas properties.

src.tools.iotools.initialize_netcdf(filename: str, dimensions: Dict, variables: Dict) → netCDF4._netCDF4.Dataset

Initializes a netcdf file to be ready for saving simulation properties.

Parameters

• filename (str) – name of the NETCDF4 file that is created

• dimensions (Dict) – dimensions of the ncf file to be created. Key = name of the dimension, value=dimension length.

• variables (Dict) – The names, descriptions, units, dimensions and precision of each variable that is saved to the netcdf file. The key of each dictionary element is used to label the variables. The value of each dictionary element needs to be a list where
  list[0] (str) Description of the variable
  list[1] (str): unit of the variable
  list[2] (Tuple): NETCDF dimensions of the variable
  list[3] (str): Datatype (precision) of the variable
  The possible NETCDF dimensions are “index”, “radial_layers” and “axial_layers”.

Returns

(NETCDF4.Dataset) – A NETCDF4 file where the simulation properties can be saved.

src.tools.iotools.write_netcdf(ncf: netCDF4._netCDF4.Dataset, properties: Dict) → None

Write a simulation result dictionary into a netcdf file.

The variables that can be written are defined in the src.model_variables file

Parameters

• ncf (netCDF4.Dataset) – the netcdf file where the properties are written

• properties (Dict) – the properties dictionary. Use the tree_properties_to_dict function to create the dictionary.

src.tools.plotting.plot_ax_up_change(filenames)

Plot upward axial flux and transpiration rate.

src.tools.plotting.plot_phloem_pressure_top_bottom(filename: str) → None

Plot the phloem pressure at the top and bottom of the tree.

The figure is saved in the current working directory with the same name as the filename with “_phloem_pressure.png” appended.

Parameters

filename (str) – name of the NetCDF file in the current directory that includes the simulation results.

src.tools.plotting.plot_simulation_results(filename: str, foldername: str) → None

Plot sugar concentration, fluxes and pressures from one simulation.

Currently you need edit tha start and end indeces in the code to capture the correct time window in the simulation results. The indices refer to the index dimension in the NetCDF files.

Parameters

• filename (str) – name of the NetCDF file in the current directory that includes the simulation results.

• foldername (str) – name of the folder where the figures are saved

src.tools.plotting.plot_variable_vs_time(filename: str, params: Optional[Dict] = None) → None

Plot any variable as a function of time from the NetCDF file that contains the simulation results.

Parameters

• filename (str) – name of the NetCDF file in the current directory that includes the simulation results.

• params (Dict, optional) – Parameters and instructions for making the plot (see Examples)

Examples

An example of the params dictionary is

params = {'variable_name': 'pressure',
'time_divide': 86400,
'variable_divide': 1e6
'labels': [['top'], ['bottom'], ['middle']],
'line_colors': [['k'], ['r'], ['b']],
'line_widths': [[3], [3], [3]],
'cut': {'index': range(1500),
        'axial_layers': [0, 39],
        'radial_layers': [1]},
'xticks': np.linspace(0, 10, 11),
'xlabel': 'Time (d)'
'ylabel': 'Pressure (MPa)',
'title': 'Pressure in the xylem'
'folder', 'figure/',
'filename_ending': 'xylem_pressure.png'}

• Variable name is the name of the variable that is to be plotted. The name must equal to a variable in the NetCDF file

• time_divide is a float which is used to divide the time vector (x-axis) in the plot. e.g., 86400 converts seconds to days

• variable_divide is a float which is used to divide the variable vector (y-axis) in the plot

• labels are the labels of each line that is drawn

• line_colors are the colors of each line that is drawn

• line_widths are the line widths of each line that is drawn

• cut contains the data range in the NetCDF file that are plotted. The function can handle only 3-dimensional data. If the variable that is plotted has shape (1500,2,1) like in this example, the function expects that there will be 2*1=3 lines in the plot. Consequently, the labels, line_colors, and line_widhths values in the params dictionary need to have 3 elements like in this example.

• xticks are the matplotlib.pyplot.xticks function argument

• xlabel is the matplotlib.pyplot.xlabel function argument

• ylabel is the matplotlib.pyplot.ylabel function argument

• title is the matplotlib.pyplot.title function argument

• folder refers to the folder starting from the current working directory where the figure is saved

• filename_ending is a string that is appended to the filename when the figure is saved

• If no folder is specified the argument filename and filename_ending is used to create the name of the figure that is saved.

src.tools.plotting.plot_xylem_pressure_top_bottom(filename: str) → None

Plot the xylem pressure at the top and bottom of the tree.

The figure is saved in the current working directory with the same name as the filename with “_xylem_pressure.png” appended.

Parameters

filename (str) – name of the NetCDF file in the current directory that includes the simulation results.