From 68ff0d664dfe8cbd54b26d8a1cec638ef285acc9 Mon Sep 17 00:00:00 2001 From: David LeBauer Date: Wed, 6 May 2026 16:40:33 -0700 Subject: [PATCH 01/13] document proposed C and N limited leaf-on events --- docs/.alternate-model-structure-ideas.md | 42 ++++++ docs/model-structure.md | 174 +++++++++++++++++------ docs/parameters.md | 4 + 3 files changed, 180 insertions(+), 40 deletions(-) diff --git a/docs/.alternate-model-structure-ideas.md b/docs/.alternate-model-structure-ideas.md index 27922a55..e2a96c82 100644 --- a/docs/.alternate-model-structure-ideas.md +++ b/docs/.alternate-model-structure-ideas.md @@ -218,6 +218,48 @@ $$ For N fixing plants, the direct uptake $ F^N_\text{fix, plant} $ is added to the plant N pool, and only the residual demand $ F^N_\text{uptake, soil} $ is met by drawing down the soil mineral N. +## Mortality From Storage Exhaustion + +Mortality or plant collapse could be linked to persistent depletion of available carbon or nitrogen storage. This should remain an alternate model structure unless validation data justify the added complexity. + +A minimal NSC-based approach would treat storage exhaustion as a diagnostic stress state rather than an immediate clamp. Define a storage stress index from the ratio of available storage to a reference storage capacity: + +\begin{equation} +\mathbb{s}_{\text{C,stress},t} += +1 - +\min\left( +1, +\frac{\mathbb{C}_{\text{NSC},t}} +{\mathbb{C}_{\text{NSC,ref},t}} +\right) +\end{equation} + +where $\mathbb{C}_{\text{NSC},t}$ is an explicit non-structural carbon pool or a documented proxy, and $\mathbb{C}_{\text{NSC,ref},t}$ is a reference storage capacity such as a fraction of live structural biomass. + +Mortality would only occur after sustained stress: + +\begin{equation} +\mathbb{I}_{\text{mort},t} += +1 +\quad \text{if} \quad +\overline{\mathbb{s}}_{\text{C,stress},t} > +\mathbb{s}_{\text{mort}} +\quad \text{for at least } \mathbb{\tau}_{\text{mort}} \text{ days} +\end{equation} + +If mortality is triggered, live biomass should be routed mass-conservingly to litter, soil, or export pools: + +\begin{equation} +\mathbb{F}^C_{\text{mort},j,t} += +\mathbb{m}_{j,t} C_{j,t} +\end{equation} + +where $j$ indexes live biomass pools and $0 \le \mathbb{m}_{j,t} \le 1$. Nitrogen associated with mortality fluxes should follow the C:N ratio of the source pool. Mortality should not silently delete carbon or nitrogen. + +This structure is consistent with carbon-starvation / storage-depletion concepts, but drought mortality also involves hydraulic failure and biotic stress, so NSC alone should be treated as a simplified risk proxy rather than a complete mechanism. Key references: McDowell et al. 2008; McDowell 2011; Hartmann and Trumbore 2016; Adams et al. 2017. ## Additional Moisture dependency functions $D_\text{water}$ diff --git a/docs/model-structure.md b/docs/model-structure.md index e791ed42..e5e5b495 100644 --- a/docs/model-structure.md +++ b/docs/model-structure.md @@ -1,8 +1,7 @@ # Model Structure -Goal: simplified biogeochemical model that is capable of simulating GHG balance, including soil carbon, $CO_2$, $CH_4$, -and $N_2O$ flux. Key validation criteria is the ability to correctly capture the response of these pools and fluxes to -changes in agronomic management practices, both current and future. +SIPNET is designed to be a simplified biogeochemical model that is capable of simulating GHG balance, including soil carbon, $CO_2$, $CH_4$, +and $N_2O$ flux in managed and unmanaged ecosystems. ### Design approach: @@ -26,11 +25,15 @@ This document provides an overview of the SIPNET model’s structure. It was wri There are multiple ways to configure the model structure, and not all model structures or components are listed. Implementation in source code (sipnet.c) is annotated with references to specific publications. + #### Notes on notation: - The general approach used to define variables and subscripts is defined in [Notation](parameters.md#notation). - Specific parameter, flux, and state definitions are documented in [Model States and Parameters](parameters.md#run-time-parameters). +Symbols in blackboard bold, e.g. $\mathbb{X}$ indicates proposed model quantities that are documented here but +not yet implemented. + ## Carbon Dynamics ### Litter Pool @@ -128,6 +131,10 @@ Net primary productivity $(\text{NPP})$ is the total carbon gain of plant bioma pools in proportion to their allocation parameters $\alpha_i$. As in Zobitz, et al. (2008), plant growth is a determined by the running five-day mean NPP, $\overline{\text{NPP}}$. +Negative NPP is valid as a diagnostic net flux when autotrophic respiration exceeds GPP. Leaf, wood, and root creation +from the five-day mean NPP are non-negative in the current allocation code; when the mean NPP is negative, those +creation fluxes are set to zero rather than creating negative biomass. + To make explicit what contributes to autotrophic respiration, we decompose $R_A$ into maintenance and optional growth components: @@ -155,11 +162,6 @@ Note that $\alpha_i$ are specified input parameters and $\sum_i{\alpha_i} = 1$. This is equation (3) from Zobitz, et al. (2008), augmented with the harvest and litter terms. Summing over all plant pools shows that NPP is partitioned into biomass growth, removed harvest, and litter production. -### Plant Death - -Plant death is implemented as a harvest event with the fraction of biomass transferred to -litter, $f_{\text{harvest,transfer,}i}$ set to 1. - ### Wood Carbon As stated above, SIPNET uses a five-day averaged NPP when allocating gained carbon to plant growth. To implement this, @@ -209,7 +211,111 @@ This is equation (A2) from Braswell, et al. (2005) The change in plant leaf carbon $(C_\text{leaf})$ over time is given by the balance of leaf production $(L)$ and leaf litter production $(F^C_\text{litter,leaf})$. -**TODO:** explain $L$ in terms of $\alpha_\text{leaf}\cdot \overline{NPP}$ and leaf on/leaf off mechanics. +#### Leaf On {#leaf-on} + +Leaf-on events define the timing of leaf emergence. Leaf-on requests a transfer of carbon to the leaf pool, and the +amount transferred is limited by available carbon and nitrogen: + +\begin{equation} +\mathbb{F}^C_{\text{leaf,on,}t} = +f_{\text{leaf,on,}t} \cdot F^C_{\text{demand,leaf,on,}t} +\label{eq:leaf_on_creation} +\end{equation} + +where $0 \le f_{\text{leaf,on,}t} \le 1$. + +A minimal limiter combines carbon and nitrogen constraints: + +\begin{equation} +\mathbb{f}_{\text{leaf,on,}t} = +\min(f^C_{\text{limit,}t}, f^N_{\text{limit,}t}) +\label{eq:leaf_on_limiter} +\end{equation} + +with $0 \le f^C_{\text{limit,}t} \le 1$ and $0 \le f^N_{\text{limit,}t} \le 1$. + +Leaf-on carbon is supplied by reallocatable perennial biomass from wood and coarse root pools: + +\begin{equation} +\mathbb{C}_{\text{realloc,}t} = +f^C_{\text{realloc}} \cdot +(C_{\text{wood,}t} + C_{\text{coarse root,}t}) +\label{eq:leaf_on_realloc_c} +\end{equation} + +where $0 \le f^C_{\text{realloc}} \le 1$. Leaf-on reallocation uses structural perennial biomass only. It does not draw +from $C_{\text{wood,storage}}$, because the storage pool is a bookkeeping buffer for recent carbon allocation lag rather than a carbon pool available for reallocation. + +If the source biomass is greater than zero, carbon transfer from source pools to leaf carbon is mass conserving. Source +pools are debited in proportion to structural pool size: + +\begin{equation} +\mathbb{F}^C_{\text{source,}j,t} = +F^C_{\text{leaf,on,}t} +\frac{C_{j,t}}{C_{\text{wood,}t} + C_{\text{coarse root,}t}} +\label{eq:leaf_on_source_c} +\end{equation} + +\begin{equation*} +\small j \in \{\text{wood, coarse root}\} +\end{equation*} + +This makes the source-pool debit auditable: + +\begin{equation} +\sum_j F^C_{\text{source,}j,t} = F^C_{\text{leaf,on,}t} +\label{eq:leaf_on_source_c_sum} +\end{equation} + +If the source biomass is zero, realized leaf-on growth is zero. If the source biomass is zero and there are no leaves, +the plant will never regrow leaf biomass. + +The carbon-side limiter is: + +\begin{equation} +\mathbb{f}^C_{\text{limit,}t} = +\min\left(1, \frac{C_{\text{realloc,}t}}{F^C_{\text{demand,leaf,on,}t}}\right) +\label{eq:leaf_on_c_limiter} +\end{equation} + +and the nitrogen-side limiter is: + +\begin{equation} +\mathbb{f}^N_{\text{limit,}t} = +\min\left(1, \frac{F^N_{\text{supply,leaf,on,}t}}{F^N_{\text{demand,leaf,on,}t}}\right) +\label{eq:leaf_on_n_limiter} +\end{equation} + +where $F^N_{\text{supply,leaf,on,}t}$ includes plant N storage, mineral uptake, and fixation. + +#### Leaf Off {#leaf-off} + +Leaf-off events define the timing of leaf senescence. A leaf-off event transfers leaf biomass carbon out of the leaf +pool. When the `--litter-pool` model option is enabled, leaf litter enters the litter pool; otherwise, leaf litter is +routed to soil carbon. A fraction of nitrogen from senescing leaves is resorbed into a plant storage pool before the +rest is transferred to litter or soil. The resorption flux is: + +\begin{equation} +\mathbb{F}^N_{\text{storage,in,}t} = +f^N_{\text{resorb}} \cdot F^N_{\text{senescing,leaf,}t} +\label{eq:leaf_n_resorb} +\end{equation} + +\begin{equation} +F^N_{\text{litter,leaf,residual,}t} = +(1 - f^N_{\text{resorb}}) \cdot F^N_{\text{senescing,leaf,}t} +\label{eq:leaf_n_litter_residual} +\end{equation} + +where $0 \le f^N_{\text{resorb}} \le 1$. The plant nitrogen storage pool balance is: + +\begin{equation} +\frac{d\mathbb{N}_{\text{plant,storage}}}{dt} = +F^N_{\text{storage,in}} - F^N_{\text{storage,use}} +\label{eq:plant_n_storage} +\end{equation} + +Stored nitrogen contributes to satisfying plant growth nitrogen demand, including leaf-on demand. ### Root Carbon @@ -611,11 +717,27 @@ drainage. ### Plant Nitrogen Demand $F^{N}_{\text{demand}}$ -Plant N demand is the amount of N required to support plant growth. This is calculated as the sum of carbon creation fluxes divided by their respective C:N ratios: +Plant N demand is the amount of N required to support plant growth. This is calculated as the sum of carbon creation fluxes divided by their respective C:N ratios. + +For leaf-on reallocation, source-pool nitrogen contributes according to the source-pool C:N ratio. Net leaf-on N demand +is the additional nitrogen needed to satisfy leaf stoichiometry: \begin{equation} -F^N_{\text{demand,}leafOn} = \frac{F^C_{\text{creation,}leafOn}}{CN_{\text{leaf}}} - -\frac{F^C_{\text{creation,}leafOn}}{CN_{\text{wood}}} +\mathbb{F}^N_{\text{source,leaf,on,}t} = +\sum_j \frac{F^C_{\text{source,}j,t}}{CN_j} +\label{eq:leaf_on_source_n} +\end{equation} + +\begin{equation*} +\small j \in \{\text{wood, coarse root}\} +\end{equation*} + +\begin{equation} +\mathbb{F}^N_{\text{demand,leaf,on,}t} = +\max\left(0, +\frac{F^C_{\text{leaf,on,}t}}{CN_{\text{leaf}}} - +F^N_{\text{source,leaf,on,}t} +\right) \label{eq:leaf_on_n_demand} \end{equation} @@ -637,8 +759,6 @@ F^N_{\text{demand,}creation} Each term in the sum is calculated according to \eqref{eq:plant_n}. Total plant N demand $F^N_{\text{demand,}total}$ is then partitioned between fixation and soil N uptake using \eqref{eq:n_fix_demand} and \eqref{eq:n_uptake_demand}. -**TODO:** possibly include more context about leaf on events - ### Nitrogen Fixation and Uptake $F^N_\text{fix}, F^N_\text{uptake}$ For N-fixing plants, symbiotic nitrogen fixation is represented as supplying a fraction of plant nitrogen demand, and is @@ -1156,32 +1276,6 @@ f_{\text{intercept}} \, F^W_{\text{irrig}}, & I_{\text{irrigation}} = 0 \\ \label{eq:irrig_evap} \end{equation} -### Leaf On/Leaf Off - -Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events directly -specify the amount of carbon added to the leaf carbon pool on the leaf on date, and the fraction of carbon removed from -the leaf carbon pool on the leaf off date. - -When a leaf on event occurs, an amount of carbon (specified by the `leafGrowth` parameter) is transferred from the wood -carbon pool to the leaf carbon pool. As leaf C:N is usually lower than wood C:N, the excess nitrogen -implied by the static C:N ratios is included as part of the plant nitrogen demand. If there is insufficient nitrogen -available for this lump-sum move, nitrogen limitation will occur. - -When a leaf off event occurs, a fraction of the leaf carbon (specified by the `fracLeafFall` parameter) is transferred -from the leaf carbon pool to the litter pool (or soil pool, if the litter pool is not being used). The corresponding -nitrogen (calculated from the leaf C:N ratio) is also transferred to the litter or soil nitrogen pool. - -**Event parameters:** - -| Parameter | Value | Description | -|-----------|----------------------|-------------------| -| Year | integer | Year | -| Day | integer | Day of year | -| Type | `leafon` / `leafoff` | The type of event | - -There are no other parameters needed for these events, as the amount of transfer is determined by the parameters -mentioned above. -