SIP325 document proposed C and N limited leaf-on events

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}
+s_{\text{C,stress},t}
+=
+1 -
+\min\left(
+1,
+\frac{C_{\text{NSC},t}}
+{C_{\text{NSC,ref},t}}
+\right)
+\end{equation}
+
+where $C_{\text{NSC},t}$ is an explicit non-structural carbon pool or a documented proxy, and $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}
+I_{\text{mort},t}
+=
+1
+\quad \text{if} \quad
+\overline{s}_{\text{C,stress},t} >
+s_{\text{mort}}
+\quad \text{for at least } \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}
+F^C_{\text{mort},j,t}
+=
+m_{j,t} C_{j,t}
+\end{equation}
+
+where $j$ indexes live biomass pools and $0 \le 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}$
 

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:
 
@@ -128,6 +127,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:
 
@@ -144,9 +147,9 @@ are part of $R_A$, their costs are subtracted from GPP before calculating NPP an
 Note that $\alpha_i$ are specified input parameters and $\sum_i{\alpha_i} = 1$.
 
 \begin{equation}
+\frac{dC_{\text{plant,}i}}{dt} = \alpha_i \cdot \overline{\text{NPP}} - F^C_{\text{harvest,removed,}i} - F^C_{\text{litter,}i}
 \frac{dC_{\text{plant,}i}}{dt}
 = \alpha_i \cdot \overline{\text{NPP}}
-
 - F^C_{\text{harvest,removed,}i}
 - F^C_{\text{litter,}i}
 \label{eq:Zobitz_3}
@@ -155,11 +158,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 +207,126 @@ 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}
+F^C_{\text{leaf,on}} =
+f_{\text{leaf,on}} \cdot F^C_{\text{demand,leaf,on}}
+\label{eq:leaf_on_creation}
+\end{equation}
+
+where $0 \le f_{\text{leaf,on}} \le 1$.
+
+A minimal limiter combines carbon and nitrogen constraints:
+
+\begin{equation}
+f_{\text{leaf,on}} =
+\min(f^C_{\text{limit}}, f^N_{\text{limit}})
+\label{eq:leaf_on_limiter}
+\end{equation}
+
+with $0 \le f^C_{\text{limit}} \le 1$ and $0 \le f^N_{\text{limit}} \le 1$.
+
+Carbon available for leaf growth at leaf-on comes from a fraction of the perennial wood and coarse root biomass pools:
+
+\begin{equation}
+C_{\text{realloc}} =
+f^C_{\text{realloc}} \cdot
+(C_{\text{wood}} + C_{\text{coarse root}})
+\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 structural biomass is greater than zero, carbon is transferred to leaf carbon. 
+Carbon is taken from the source pools in proportion to their size:
+
+\begin{equation}
+F^C_{\text{source,}j} =
+F^C_{\text{leaf,on}}
+\frac{C_j}{C_{\text{wood}} + C_{\text{coarse root}}}
+\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} + F^C_{\text{leaf,on}} = 0
+\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}
+f^C_{\text{limit}} =
+\min\left(1, \frac{C_{\text{realloc}}}{F^C_{\text{demand,leaf,on}}}\right)
+\label{eq:leaf_on_c_limiter}
+\end{equation}
+
+and the nitrogen-side limiter is:
+
+\begin{equation}
+f^N_{\text{limit}} =
+\min\left(1, \frac{F^N_{\text{supply,leaf,on}}}{F^N_{\text{demand,leaf,on}}}\right)
+\label{eq:leaf_on_n_limiter}
+\end{equation}
+
+where $F^N_{\text{supply,leaf,on}}$ 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. 
+The leaf-off carbon transfer is controlled by the leaf fall 
+fraction parameter, $f_{\text{fall}}$.
+
+\begin{equation}
+F^C_{\text{senescing,leaf}} = f_\text{fall} \cdot C_\text{leaf}
+\end{equation}
+
+When the litter pool is enabled, leaf litter enters the litter pool; 
+otherwise, leaf litter is routed to soil carbon.
+
+At leaf-off, 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}
+F^N_{\text{storage,in}} =
+f^N_{\text{resorb}} \cdot F^N_{\text{senescing,leaf}}
+\label{eq:leaf_n_resorb}
+\end{equation}
+
+where 
+\begin{equation}
+F^N_{\text{senescing,leaf}} = F^C_{\text{senescing,leaf}} \cdot CN_\text{leaf}
+\end{equation}
+\begin{equation}
+F^N_{\text{litter,leaf,residual}} =
+(1 - f^N_{\text{resorb}}) \cdot F^N_{\text{senescing,leaf}}
+\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{dN_{\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 (indicated as $F^N_{\text{storage,use}}$).
 
 ### Root Carbon
 
@@ -611,11 +728,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{source,leaf,on}} =
+\sum_j \frac{F^C_{\text{source,}j}}{CN_j}
+\label{eq:leaf_on_source_n}
+\end{equation}
+
+\begin{equation*}
+\small j \in \{\text{wood, coarse root}\}
+\end{equation*}
 
 \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}}}
+F^N_{\text{demand,leaf,on}} =
+\max\left(0,
+\frac{F^C_{\text{leaf,on}}}{CN_{\text{leaf}}} -
+F^N_{\text{source,leaf,on}}
+\right)
 \label{eq:leaf_on_n_demand}
 \end{equation}
 
@@ -637,8 +770,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,31 +1287,15 @@ 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:**
+### Leaf On/Leaf Off Events
 
-| Parameter | Value                | Description       |
-| --------- | -------------------- | ----------------- |
-| Year      | integer              | Year              |
-| Day       | integer              | Day of year       |
-| Type      | `leafon` / `leafoff` | The type of event |
+Leaf-on and leaf-off may be triggered either by explicit `leafon` / `leafoff` records in `events.in` or by calculated phenology. 
+Explicit leaf events specify timing only and take no additional event-file parameters. 
+Calculated leaf-on timing is controlled by `gdd`, `soil-phenol` runtime options, or the `leafOnDay` parameter, depending on configuration; calculated
+leaf-off timing is controlled by `leafOffDay`. 
+Leaf on/off specified as events are incompatible with temperature (GDD or soil) or parameter based leaf timing.
 
-There are no other parameters needed for these events, as the amount of transfer is determined by the parameters
-mentioned above.
+Once triggered, leaf-on and leaf-off use the same dynamics described in [Leaf On](#leaf-on) and [Leaf Off](#leaf-off).
 
 <!-- 
 **Flooding** increases soil water to water holding capacity and then adds water equivalent to the depth of flooding. Subsequent irrigation events maintain flooding by topping off water content.

docs/parameters.md

@@ -107,6 +107,7 @@ Run-time parameters can change from one run to the next, or when the model is st
 | $N_{\text{org, litter},0}$        | litterOrgNInit | Initial litter organic nitrogen content                                  | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
 | $N_{\text{org, soil},0}$          | soilOrgNInit   | Initial soil organic nitrogen content                                    | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
 | $N_{\text{min, soil},0}$          | mineralNInit   | Initial soil mineral nitrogen content                                    | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
+| $N_{\text{plant,storage},0}$ | plantNStorageInit | Initial plant nitrogen storage                                      | $\text{g N} \cdot \text{m}^{-2}$                                    | Expected range $\ge 0$                                                                   |
 | $f_{\text{fine root},0}$          | fineRootFrac   | Fraction of `plantWoodInit` allocated to initial fine root carbon pool   | unitless                                                            |                                                                                          |
 | $f_{\text{coarse root},0}$        | coarseRootFrac | Fraction of `plantWoodInit` allocated to initial coarse root carbon pool | unitless                                                            |                                                                                          |
 | $W_{\text{snow},0}$               | snowInit       | Initial snow water equivalent                                            | cm water equivalent                                                 |                                                                                          |
@@ -162,6 +163,7 @@ Run-time parameters can change from one run to the next, or when the model is st
 | $D_{\text{off}}$          | leafOffDay       | Day of year for leaf drop                                             | unitless                         | day of year (1–365); 0 to turn off   |
 | $\Delta C_{\text{leaf}}$  | leafGrowth       | Additional leaf growth at start of growing season                     | $\text{g C} \cdot \text{m}^{-2}$ |                                      |
 | $f_{\text{fall}}$         | fracLeafFall     | Additional fraction of leaves that fall at end of growing season      | unitless                         |                                      |
+| $f^C_{\text{realloc}}$ | leafOnReallocFrac | Fraction of wood and coarse root C available for leaf-on reallocation | unitless                         | Expected range $[0,1]$              |
 | $\alpha_{\text{leaf}}$    | leafAllocation   | Fraction of $NPP$ allocated to leaf growth                            | unitless                         |                                      |
 | $K_{\text{leaf}}$         | leafTurnoverRate | Average turnover rate of leaves                                       | $\text{year}^{-1}$               | Converted to per-day rate internally |
 

docs/user-guide/model-inputs.md

@@ -93,9 +93,9 @@ loc	year day  time length tair tsoil par    precip vpd   vpdSoil vPress wspd
 0	  1998 306  7.00  0.417 2.2  1.4   2.7104 1.0000 114.1 71.6    741.8  0.9690
 ```
 
-## Agronomic Events
+## Events
 
-Agronomic (management) events are read from `events.in` by default, or from
+Events are read from `events.in` by default, or from
 `<EVENTS_PREFIX>.in` when `EVENTS_PREFIX` / `--events-prefix` is set. This
 file specifies one event per line:
 
@@ -186,6 +186,12 @@ Specifically:
   - for perennials, some biomass may remain (col 5 + col 7 <= 1 and col 6 + col 8 <= 1; remainder is living).
    - root biomass is only removed for root crops
 
+### Leaf On and Off
+
+| parameter | col | req? | description            |
+| --------- | --- | -----| ---------------------- |
+| type      |  3  |  Y   | `leafon` or `leafoff`  |
+
 ### Example of `events.in` file:
 
 ```