`sgam.sgam`

sgam.sgam

SGAM (Simplified Growth/GPP Allocation Model) component.

This module provides the SgamComponent class, which simulates the allocation of gross primary productivity (GPP) to plant carbon pools (leaf_pool_size, stem_pool_size, root_pool_size) across different plant types (tree, grass, crop, shrub), including turnover, respiration, and disturbance events.

SgamComponent

SgamComponent(plant_type: PlantFunctionalType)

The Simplified Growth/GPP Allocation Model (SGAM).

Simulates the allocation of gross primary productivity (GPP) to plant carbon pools (leaf_pool_size, stem_pool_size, root_pool_size) for 4 plant types (tree, grass, crop, shrub) over time, based on environmental drivers and physiological parameters. It accounts for dynamic allocation, turnover, respiration, disturbance/harvest events, and outputs pool sizes and fluxes.

Parameters:

plant_type (PlantFunctionalType) –

Type of plant (tree, grass, crop, or shrub).

Todo

Refine crop modelling --> growing_season_limit necessary ?
Add PC output for RothC when crop harvested or not emerged
Add grazing -> manure return to RothC

call

__call__(gpp: NDArray[float64], temperature: NDArray[float64], soil_moisture: NDArray[float64], vpd: NDArray[float64], lue: NDArray[float64], iwue: NDArray[float64], week_of_year: NDArray[float64], disturbances: NDArray[float64], leaf_pool_init: float, stem_pool_init: float, root_pool_init: float) -> dict[str, NDArray]

Alias for forward.

Parameters:

gpp (NDArray[float64]) –

Weekly total gross primary productivity (gC).
temperature (NDArray[float64]) –

Weekly mean air temperature (degC).
soil_moisture (NDArray[float64]) –

Weekly mean soil moisture content (normalized or mm).
vpd (NDArray[float64]) –

Weekly mean vapor pressure deficit (Pa).
lue (NDArray[float64]) –

Weekly mean light use efficiency (gC/MJ).
iwue (NDArray[float64]) –

Weekly mean intrinsic water use efficiency (umol/mol).
week_of_year (NDArray[float64]) –

Weekly timestep index of the year (1-52).
disturbances (NDArray[float64]) –

The maximum daily relative decline (0.0 to 1.0) observed during the week.
leaf_pool_init (float) –

Initial leaf biomass pool size (gC).
stem_pool_init (float) –

Initial stem biomass pool size (gC).
root_pool_init (float) –

Initial root biomass pool size (gC).

Returns:

dict[str, NDArray] –

Carbon pools (gC), fluxes (gC), and diagnostics (LAI, NPP, CUE).

compute_allocation_fractions

compute_allocation_fractions(temperature: NDArray[float64], soil_moisture: NDArray[float64], vpd: NDArray[float64], week_of_year: NDArray[float64]) -> tuple[NDArray, NDArray, NDArray]

Compute dynamic carbon allocation fractions for leaf, stem, and root pools.

Parameters:

temperature (NDArray[float64]) –

Weekly mean air temperature (degC).
soil_moisture (NDArray[float64]) –

Weekly mean soil moisture content (normalized or mm).
vpd (NDArray[float64]) –

Weekly mean vapor pressure deficit (Pa).
week_of_year (NDArray[float64]) –

The week number of the simulation year (1 to 52).

Returns:

tuple[NDArray, NDArray, NDArray] –

Allocation fractions for (leaf, stem, root), summing to 1.0.

compute_cue

compute_cue(lue: NDArray, iwue: NDArray) -> NDArray

Compute carbon use efficiency (CUE) from light use efficiency and intrinsic water use efficiency.

CUE = CUE_{max} . f(LUE_{norm}) . f(IWUE_{norm})

Parameters:

lue (NDArray) –

Weekly mean light use efficiency (gC/MJ).
iwue (NDArray) –

Weekly mean intrinsic water use efficiency (umol/mol).

Returns:

NDArray –

Carbon use efficiency values.

compute_drought_modifier

compute_drought_modifier(soil_moisture: NDArray, vpd: NDArray) -> NDArray

Compute the environmental stress scalar using Liebig's Law of the Minimum.

This modifier accounts for both edaphic (soil) and atmospheric (VPD) water stress. The final modifier is the minimum of the two individual stress functions, ranging from 0.0 (maximum stress) to 1.0 (no stress).

Soil Moisture Stress (\(f_{sm}\)): Scales linearly between the wilting point (\(\theta_{wp}\)) and a reference soil moisture (\(\theta_{ref}\)):

\[ f_{sm} = \begin{cases} 0 & \theta < \theta_{wp} \\ \frac{\theta - \theta_{wp}}{\theta_{ref} - \theta_{wp}} & \theta_{wp} \le \theta \le \theta_{ref} \\ 1 & \theta > \theta_{ref} \end{cases} \]

VPD Stress (\(f_{vpd}\)): Represents stomatal closure as a function of vapor pressure deficit using an exponential decay:

\[ f_{vpd} = \exp(-\gamma \cdot \max(0, VPD - VPD_{threshold})) \]

Parameters:

soil_moisture (NDArray) –

Volumetric soil water content (\(m^3/m^3\)).
vpd (NDArray) –

Vapor Pressure Deficit in Pascals (Pa).

Returns:

NDArray –

The combined drought modifier \(\min(f_{sm}, f_{vpd})\).

forward

forward(gpp: NDArray[float64], temperature: NDArray[float64], soil_moisture: NDArray[float64], vpd: NDArray[float64], lue: NDArray[float64], iwue: NDArray[float64], week_of_year: NDArray[float64], disturbances: NDArray[float64], leaf_pool_init: float, stem_pool_init: float, root_pool_init: float) -> dict[str, NDArray]

Simulate weekly plant growth and carbon allocation using a mass-balance approach.

The model operates on a weekly timestep using a discrete mass-balance: 1. GPP (mass) is allocated to tissues via fractions modified by weekly climate. 2. Growth Respiration is deducted via CUE (PFT-specific stress-scaling). 3. Maintenance Respiration and Turnover are deducted from existing biomass using weekly coefficients stored in pft_params. 4. Disturbance removes biomass based on PFT: Crops are reset to zero (harvest), while others lose a fraction of leaf biomass. 5. Litter to Soil is the sum of natural turnover and disturbance biomass.

Parameters:

gpp (NDArray[float64]) –

Weekly total gross primary productivity (gC).
temperature (NDArray[float64]) –

Weekly mean air temperature (degC).
soil_moisture (NDArray[float64]) –

Weekly mean soil moisture content (normalized or mm).
vpd (NDArray[float64]) –

Weekly mean vapor pressure deficit (Pa).
lue (NDArray[float64]) –

Weekly mean light use efficiency (gC/MJ).
iwue (NDArray[float64]) –

Weekly mean intrinsic water use efficiency (umol/mol).
week_of_year (NDArray[float64]) –

Weekly timestep index of the year (1-52).
disturbances (NDArray[float64]) –

The maximum daily relative decline (0.0 to 1.0) observed during the week. Values of 0.0 indicate no disturbance event.
leaf_pool_init (float) –

Initial leaf biomass pool size (gC).
stem_pool_init (float) –

Initial stem biomass pool size (gC).
root_pool_init (float) –

Initial root biomass pool size (gC).

Returns:

dict[str, NDArray] –

Carbon pools (gC), fluxes (gC), and diagnostics (LAI, NPP, CUE).