climag.modvege_lib

modvege_lib.py

Main ModVege functions.

climag.modvege_lib.leaf_area_index(ts_vals: dict[str, float], params: dict[str, float]) → float

Calculate the leaf area index (LAI)

Equation (12) in Jouven et al. (2006a)

Parameters

paramsdict[str, float]

A dictionary containing these model parameters:

• pct_lam: Percentage of laminae in the green vegetative (GV) biomass compartment; default is 0.68 (%LAM) [dimensionless]

• sla: Specific leaf area; default is 0.033 (SLA) [m² g⁻¹]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• bm_gv: Standing biomass of the green vegetative (GV) compartment (BM_GV) [kg DM ha⁻¹]

• bm_gr: Standing biomass of the green reproductive (GR) compartment (BM_GR) [kg DM ha⁻¹]

Returns

float

Leaf area index (LAI) [dimensionless]

climag.modvege_lib.actual_evapotranspiration(pet: float, ts_vals: dict[str, float]) → float

Calculate the actual evapotranspiration (AET)

AET is equivalent to potential evapotranspiration (PET) when the cover intercepts approximately 0.95 of the incident photosynthetically active radiation (PAR), i.e., when the leaf area index (LAI) > 3, based on Johnson and Parsons (1985). AET is proportional to LAI when the proportion of intercepted radiation is lower than 0.95, i.e. LAI < 3.

See Equation (14) in Jouven et al. (2006a)

Parameters

petfloat

Potential evapotranspiration (PET) [mm]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• lai: Leaf area index (LAI) [dimensionless]

Returns

float

Actual evapotranspiration (AET) [mm]

climag.modvege_lib.potential_growth(par_i: float, ts_vals: dict[str, float], params: dict[str, float]) → float

Calculate potential growth (PGRO)

See Equation (12) in Jouven et al. (2006a)

Based on Schapendonk et al. (1998).

The model extinction coefficient is set to a constant value of 0.6 according to Schapendonk et al. (1998) and Bonesmo and Bélanger (2002).

The maximum radiation use efficiency is 3 g DM MJ⁻¹ based on Schapendonk et al. (1998).

Parameters

par_ifloat

Incident photosynthetically active radiation (PAR_i) [MJ m⁻²]

paramsdict[str, float]

A dictionary containing model parameters:

• rue_max: Maximum radiation use efficiency (RUE_max); default is 3.0 [g DM MJ⁻¹]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• lai: Leaf area index (LAI) [dimensionless]

Returns

float

Potential growth (PGRO) [kg DM ha⁻¹]

climag.modvege_lib.par_function(par_i: float) → float

Incident photosynthetically active radiation

Incident photosynthetically active radiation (PAR_i) function (f(PAR_i)) needed to calculate the environmental limitation of growth (ENV).

The definition has been derived from Schapendonk et al. (1998). This function accounts for the decrease in radiation use efficiency (RUE) at light intensities higher than 5 MJ m⁻².

See Figure 2(a), Equation (13), and the section on “Growth functions” in Jouven et al. (2006a).

Parameters

par_ifloat

Incident photosynthetically active radiation (PAR_i) [MJ m⁻²]

Returns

float

PAR_i function (f(PAR_i)) [dimensionless]

climag.modvege_lib.sum_of_temperatures(params: dict[str, float], ts_vals: dict[str, float], t_ts: list[float], day: int) → float

Sum of temperature threshold

Return the sum of temperatures for each day of the year above the minimum temperature for growth (ST)

Parameters

t_tslist[float]

Temperature (T) field of the input time series data (temperature should be in °C)

dayint

Day number

paramsdict[str, float]

A dictionary containing model parameters:

• t_0: Minimum temperature for growth (T₀); default is 4 [°C]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• st: Sum of temperatures value for the previous data row (ST) [°C d]

Returns

float

Sum of temperatures above T₀ corresponding to each day of the year (ST) [°C d]

Notes

• Degree days are measures of how cold or warm a location is

• A degree day compares the mean (the average of the high and low) outdoor temperatures recorded for a location to a standard temperature

• Also known as heat units or thermal units

• All species of plants have a cutoff temperature below which no development occurs (developmental threshold)

• Degree days are accumulated whenever the temperature exceeds the predetermined developmental threshold

• Calculate degree days by subtracting the developmental threshold from the average daily temperature

• If the average degree day value for a given day is less than zero, just record zero, not a negative number

References

• https://hort.extension.wisc.edu/articles/degree-day-calculation/

• https://www.eia.gov/energyexplained/units-and-calculators/degree-days.php

climag.modvege_lib.ten_day_moving_avg_temperature(day: int, t_ts: list[float], t_init: list[float] = None) → float

Calculate the 10-d moving average temperature.

See sec. “Growth functions”, par. above Equation (13) in Jouven et al. (2006a).

Parameters

t_tslist[float]

Temperature (T) field of the input time series data (temperature should be in °C)

dayint

Day number

Returns

float

10-d moving average temperature [°C]

climag.modvege_lib.temperature_function(ts_vals: dict[str, float], params: dict[str, float]) → float

Temperature function, f(T)

See Figure 2(b) of Jouven et al. (2006a) and the accompanying text for more info; f(T) has been derived based on Schapendonk et al. (1998)

Assume no growth takes place after a maximum temperature

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• t_m10: 10-d moving average temperature [°C]

paramsdict[str, float]

A dictionary containing these model parameters:

• t_0: Minimum temperature for growth (T₀); default is 4 [°C]

• t_1: Minimum temperature for optimal growth; default is 10 [°C]

• t_2: Maximum temperature for optimal growth; default is 20 [°C]

• t_max: Maximum temperature for growth; default is 40 [°C]

Returns

float

Temperature function (f(T)) [dimensionless]

climag.modvege_lib.seasonal_effect(params: dict[str, float]) → float

Seasonal effect

Calculate seasonal effect (SEA) on growth, driven by the sum of temperatures.

Note: A constant value (the average of minSEA and maxSEA) is used for the SEA if the sum of temperatures at the beginning of the reproductive period is lower than the sum of temperatures at the onset of reproductive growth.

SEA > 1 indicates above-ground stimulation by mobilisation of reserves; SEA < 1 indicates growth limitation by storage of reserves

SEA = minSEA when ST < 200°C d, then increases and reaches maxSEA when (ST₁ - 200) < ST < (ST₁ - 100) (ST = ST₁ at the beginning of the reproductive period); during summer, SEA decreases, returning to minSEA at ST₂ (ST = ST₂ at the end of the reproductive period)

“T-sum 200 date” had its origins in the Netherlands and reflects the amount of heat absorbed and hence the amount of energy available to promote grass growth, and is used by farmers as an indication of conditions suitable for nitrogen application to grass swards (Collins and Cummins, 1998).

See Figure 3 of Jouven et al. (2006a) and the accompanying paragraphs for more info

minSEA and maxSEA are functional traits arranged symmetrically around 1: (minSEA + maxSEA) / 2 = 1

Parameters

paramsdict[str, float]

A dictionary containing these model parameters:

• max_sea: Maximum seasonal effect (maxSEA); default is 1.2 [dimensionless]

• min_sea: Minimum seasonal effect (minSEA); default is 0.8 [dimensionless]

• st_1: Sum of temperatures at the beginning of the reproductive period (ST₁) [°C d]

• st_2: Sum of temperatures at the end of the reproductive period (ST₂) [°C d]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• st: Sum of temperatures (ST) [°C d]

Returns

float

Seasonal effect [dimensionless]

climag.modvege_lib.water_reserves(ts_vals: dict[str, float], params: dict[str, float], precipitation: float) → float

Calculate the water reserves (WR).

WR vary between zero and the soil water-holding capacity (WHC). Precipitation (PP) fill the WHC, increasing WR, while actual evapotranspiration (AET) empties it.

See Equation (14) in Jouven et al. (2006a).

Parameters

precipitationfloat

Precipitation (PP) [mm]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• wr: Water reserves (WR) [mm]

• aet: Actual evapotranspiration (AET) [mm]

paramsdict[str, float]

A dictionary containing model parameters:

• whc: Soil water-holding capacity (WHC) [mm]

Returns

float

Water reserves (WR) [mm]

climag.modvege_lib.water_stress(ts_vals: dict[str, float], params: dict[str, float]) → float

Calculate the water stress (W).

See Equation (14) in Jouven et al. (2006a)

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• wr: Water reserves (WR) [mm]

paramsdict[str, float]

A dictionary containing model parameters:

• whc: Soil water-holding capacity (WHC) [mm]

Returns

float

Water stress (W) [dimensionless]

climag.modvege_lib.water_stress_function(ts_vals: dict[str, float], pet: float) → float

Water stress function (f(W)).

See Figure 2(c) and Equation (14) of Jouven et al. (2006a).

Based on McCall and Bishop-Hurley (2003).

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• w: Water stress (W) [dimensionless]

petfloat

Potential evapotranspiration (PET) [mm]

Returns

float

Water stress function (f(W)) [dimensionless]

climag.modvege_lib.reproductive_function(params: dict[str, float], ts_vals: dict[str, float]) → float

Reproductive function (REP).

REP is zero when there is a cut due to grazing or harvesting. REP is also zero before and after the period of reproductive growth.

See Equation (15) in Jouven et al. (2006a)

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• st: Sum of temperatures [°C d]

• h_bm: The total harvested biomass amount [kg DM ha⁻¹]

• i_bm: The total ingested biomass amount [kg DM ha⁻¹]

paramsdict[str, float]

A dictionary containing model parameters:

• ni: Nitrogen nutritional index (NI) [dimensionless]

• st_1: Sum of temperatures at the beginning of the reproductive period [°C d]

Returns

float

Reproductive function [dimensionless]

climag.modvege_lib.environmental_limitation(ts_vals: dict[str, float], params: dict[str, float], par_i: float) → float

Environmental limitation of growth (ENV).

See Equation (13) of Jouven et al. (2006a).

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• f_t: temperature function (f(T)) [dimensionless]

• f_w: Water stress function (f(W)) [dimensionless]

paramsdict[str, float]

A dictionary containing model parameters:

• ni: Nutritional index of pixel (NNI) [dimensionless]

par_ifloat

Incident photosynthetically active radiation (PAR_i) [MJ m⁻²]

Returns

float

Environmental limitation of growth (ENV) [dimensionless]

climag.modvege_lib.total_growth(ts_vals: dict[str, float]) → float

Calculate the total biomass growth (GRO)

See Equation (11) in Jouven et al. (2006a)

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for: - pgro: Potential growth (PGRO) [kg DM ha⁻¹] - env: Environmental limitation of growth (ENV) [dimensionless] - sea: Seasonal effect (SEA) [dimensionless]

Returns

float

Total biomass growth (GRO) [kg DM ha⁻¹]

climag.modvege_lib.abscission(ts_vals: dict[str, float], params: dict[str, float], temperature: float) → dict[str, float]

Abscission biomass.

Compute abscission biomass for the dead vegetative (DV) and dead reproductive (DR) compartments. See Equation (18) and Figure 4(c) and (d) in in Jouven et al. (2006a).

Note that abscission only occurs when T > 0.

Parameters

paramsdict[str, float]

A dictionary containing model parameters:

• lls: Leaf lifespan (LLS) [500 °C d]

• kl_dv: Basic abscission rate for the dead vegetative; compartment default is 0.001 (Kl_DV) [dimensionless]

• kl_dr: Basic abscission rate for the dead reproductive compartment; default is 0.0005 (Kl_DR) [dimensionless]

• st_1: Sum of temperatures at the beginning of the reproductive period; (ST₁) [°C d]

• st_2: Sum of temperatures at the end of the reproductive period; (ST₂) [°C d]

temperaturefloat

Mean daily temperature (T) [°C]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• bm_dv: DV biomass (BM_DV) [kg DM ha⁻¹]

• age_dv: Age of the DV compartment (AGE_DV) [°C d]

• bm_dr: DR biomass (BM_DR) [kg DM ha⁻¹]

• age_dr: Age of the DR compartment (AGE_DR) [°C d]

Returns

dict[str, float]

An updated ts_vals dictionary with:

• abs_dv: Abscission of the DV biomass (ABS_DV) [kg DM ha⁻¹]

• abs_dr: Abscission of the DR biomass (ABS_DR) [kg DM ha⁻¹]

climag.modvege_lib.senescence(ts_vals: dict[str, float], params: dict[str, float], temperature: float) → dict[str, float]

Senescing biomass for the GV and GR compartments.

See Equations (16) and (17) and Figure 4(a) and (b) in Jouven et al. (2006a).

No senescence occurs when T is between zero and T₀. When T drops below zero, senescence is driven by freezing effects and is proportional to \((|T|)\).

Parameters

paramsdict[str, float]

A dictionary containing model parameters:

• k_gv: Basic senescence rate for the green vegetative compartment; default is 0.002 (K_GV) [dimensionless]

• k_gr: Basic senescence rate for the green reproductive compartment; default is 0.001 (K_GR) [dimensionless]

• t_0: Minimum temperature for growth; default is 4 (T₀) [°C]

• lls: Leaf lifespan; default is 500 (LLS) [°C d]

• st_1 : Sum of temperatures at the beginning of the reproductive period; (ST₁) [°C d]

• st_2 : Sum of temperatures at the end of the reproductive period; (ST₂) [°C d]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• bm_gv: GV biomass (BM_GV) [kg DM ha⁻¹]

• age_gv: Age of the GV compartment (AGE_GV) [°C d]

• bm_gr: Biomass available for GR (BM_GR) [kg DM ha⁻¹]

• age_gr: Age of the GR compartment (AGE_GR) [°C d]

temperaturefloat

Mean daily temperature (T) [°C]

Returns

dict[str, float]

An updated ts_vals dictionary with:

• Senescing GV biomass (SEN_GV) [kg DM ha⁻¹]

• Senescing GR biomass (SEN_GR) [kg DM ha⁻¹]

climag.modvege_lib.biomass_growth(ts_vals: dict[str, float]) → tuple[float, float]

Calculate the growth of the GV and GR biomass compartments.

See Equations (1) and (2) in Jouven et al. (2006a)

Parameters

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• gro: Total growth (GRO) [kg DM ha⁻¹]

• rep: Reproductive function (REP) [dimensionless]

Returns

tuple[float, float]

A tuple of:

• Growth of the GV compartment (GRO_GV) [kg DM ha⁻¹]

• Growth of the GR compartment (GRO_GR) [kg DM ha⁻¹]

climag.modvege_lib.standing_biomass(ts_vals: dict[str, float], params: dict[str, float]) → dict[str, float]

Update the standing biomass for each compartment.

See Equations (1), (2), (3), and (4) in Jouven et al. (2006a).

Parameters

paramsdict[str, float]

A dictionary containing model parameters:

• sigma_gv: Rate of biomass loss with respiration for GV [dimensionless]

• sigma_gr: Rate of biomass loss with respiration for GR [dimensionless]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• bm_gv: GV biomass (BM_GV) [kg DM ha⁻¹]

• sen_gv: Senescence of GV compartment (SEN_GV) [kg DM ha⁻¹]

• bm_gr: GR biomass (BM_GR) [kg DM ha⁻¹]

• sen_gr: Senescence of GR compartment (SEN_GR) [kg DM ha⁻¹]

• bm_dv: DV biomass (BM_DV) [kg DM ha⁻¹]

• abs_dv: Abscission of the DV compartment (ABS_DV) [kg DM ha⁻¹]

• bm_dr: DR biomass (BM_DR) [kg DM ha⁻¹]

• abs_dr: Abscission of the DR compartment (ABS_DR) [kg DM ha⁻¹]

• gro: Total growth (GRO) [kg DM ha⁻¹]

• rep: Reproductive function (REP) [dimensionless]

Returns

dict[str, float]

An updated ts_vals dictionary with:

• bm_gv: GV biomass (BM_GV) [kg DM ha⁻¹]

• bm_gr: GR biomass (BM_GR) [kg DM ha⁻¹]

• bm_dv: DV biomass (BM_DV) [kg DM ha⁻¹]

• bm_dr: DR biomass (BM_DR) [kg DM ha⁻¹]

climag.modvege_lib.biomass_age(temperature: float, params: dict[str, float], ts_vals: dict[str, float]) → dict[str, float]

Update the age of each biomass compartment.

See Equations (5), (6), (7), and (8) in Jouven et al. (2006a).

The age of the residual biomass is increased daily by the mean daily temperature, if this temperature is positive.

Parameters

paramsdict[str, float]

A dictionary containing model parameters:

• sigma_gv: Rate of biomass loss with respiration for GV [dimensionless]

• sigma_gr: Rate of biomass loss with respiration for GR [dimensionless]

ts_valsdict[str, float]

A dictionary with intermediate time series values for:

• bm_gv: GV biomass (BM_GV) [kg DM ha⁻¹]

• age_gv: Age of the GV compartment (AGE_GV) [°C d]

• sen_gv: Senescence of GV compartment (SEN_GV) [kg DM ha⁻¹]

• bm_gr: GR biomass (BM_GR) [kg DM ha⁻¹]

• age_gr: Age of the GR compartment (AGE_GR) [°C d]

• sen_gr: Senescence of GR compartment (SEN_GR) [kg DM ha⁻¹]

• bm_dv: DV biomass (BM_DV) [kg DM ha⁻¹]

• age_dv: Age of the DV compartment (AGE_DV) [°C d]

• abs_dv: Abscission of the DV compartment (ABS_DV) [kg DM ha⁻¹]

• bm_dr: DR biomass (BM_DR) [kg DM ha⁻¹]

• age_dr: Age of the DR compartment (AGE_DR) [°C d]

• abs_dr: Abscission of the DR compartment (ABS_DR) [kg DM ha⁻¹]

• gro: Total growth (GRO) [kg DM ha⁻¹]

• rep: Reproductive function (REP) [dimensionless]

temperaturefloat

Mean daily temperature (T) [°C]

Returns

dict[str, float]

An updated ts_vals dictionary with:

• age_gv: Age of the GV compartment (AGE_GV) [°C d]

• age_gr: Age of the GR compartment (AGE_GR) [°C d]

• age_dv: Age of the DV compartment (AGE_DV) [°C d]

• age_dr: Age of the DR compartment (AGE_DR) [°C d]