[185] Update N cycle documentation

docs/model-structure.md

@@ -572,42 +572,38 @@ F^N_\text{min} = \sum_j \left( \frac{R_{H\text{j}}}{CN_{\text{j}}} \right)
 \small j \in \{\text{soil, litter}\}
 \end{equation*}
 
-### Nitrogen Volatilization $F^N_\text{vol}: (N_\text{min,soil} \rightarrow N_2O)$
+### Nitrogen Volatilization $F^N_\text{vol}: (N_\text{min} \rightarrow N_2O)$
 
-The simplest way to represent $N_2O$ flux is as a proportion of the mineral N pool $N_\text{min}$ or the N
-mineralization rate $F^N_{min}$. For example, CLM-CN and CLM 4.0 represent $N_2O$ flux as a proportion
-of $N_\text{min}$ (Thornton et al 2007, Oleson et al. 2010). By contrast, Biome-BGC (Golinkoff et al 2010; Thornton and
-Rosenbloom, 2005 and https://github.com/bpbond/Biome-BGC, Golinkoff et al 2010; Thornton and Rosenbloom, 2005)
-represents $N_2O$ flux as a proportion of the N mineralization rate.
-
-The simplest way to represent $N_2O$ flux is as a proportion of the mineral N pool $N_\text{min}$ or the N 
-mineralization rate $F^N_{min}$. For example, CLM-CN and CLM 4.0 represent $N_2O$ flux as a proportion of $N_\text{min}$
-(Thornton et al 2007, Oleson et al. 2010). By contrast, Biome-BGC (Golinkoff et al 2010; Thornton and Rosenbloom, 2005
-and https://github.com/bpbond/Biome-BGC, Golinkoff et al 2010; Thornton and Rosenbloom, 2005) represents $N_2O$ flux as
-a proportion of the N mineralization rate. 
-
-Because we expect $N_2O$ emissions will be dominated by fertilizer N inputs, we will start with the $N_\text{min}$ pool
-size approach. This approach also has the advantage of accounting for reduced $N_2O$ flux when N is limiting (Zahele and
-Dalmorech 2011).
-
-A new parameter $K_\text{vol}$ represents the first-order rate constant governing volatilization losses from the soil
-mineral nitrogen pool. The realized volatilization flux is proportional to $N_\text{min}$ and depends on temperature and
-soil moisture.
+$K_\text{vol}$ is the nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a
+proportion of available $N_\text{min}$. The realized volatilization flux is proportional to available $N_\text{min}$, scaled by $K_\text{vol}$ and modified by temperature and soil moisture.
 
 \begin{equation}
 F^N_\text{vol} = K_\text{vol} \cdot N_\text{min} \cdot D_{\text{temp}} \cdot D_{\text{water},N_\text{vol}}
 \label{eq:n_vol}
 \end{equation}
 
+Justification: SIPNET represents $N_2O$ flux as a proportion of the mineral N pool $N_\text{min}$, rather than as a
+proportion of the N mineralization rate $F^N_\text{min}$. CLM-CN and CLM 4.0 use an $N_\text{min}$ approach (Thornton et
+al. 2007; Oleson et al. 2010), while Biome-BGC represents $N_2O$ flux as a proportion of the N mineralization rate
+(Golinkoff et al. 2010; Thornton and Rosenbloom, 2005; https://github.com/bpbond/Biome-BGC). The $N_\text{min}$
+approach accounts for reduced $N_2O$ flux when N is limiting (Zahele and Dalmorech 2011), and fertilizer N inputs are
+expected to dominate $N_2O$ emissions.
+
 ### Nitrogen Leaching $F^N_\text{leach}$
 
 \begin{equation}
-F^N_\text{leach} = N_\text{min} \cdot F^W_{drainage} \cdot f_{N leach}
+F^N_\text{leach} = N_\text{min} \cdot \phi \cdot f^N_\text{leach}
 \label{eq:n_leach}
 \end{equation}
 
-Where $f^N_\text{leach}$ is the fraction of $N_{min}$ in soil that is available to be leached, $F^W_{drainage}$ is
-drainage.
+where:
+
+\begin{equation}
+\phi = \min\left(\frac{F^W_\text{drainage}}{W_\text{WHC}}, 1\right)
+\end{equation}
+
+$f^N_\text{leach}$ is the fraction of $N_\text{min}$ available to be leached, $F^W_\text{drainage}$ is drainage, and
+$W_\text{WHC}$ is soil water holding capacity. SIPNET uses one mineral nitrogen pool, $N_\text{min}$; litter and soil mineralization are separate fluxes that both add to this pool.
 
 ### Plant Nitrogen Demand  $F^{N}_{\text{demand}}$
 
@@ -911,7 +907,7 @@ Where $T_{\text{env}}$ may be soil or air temperature  $(T_\text{soil}$ or $T_\t
 Because the function is symmetric around $T_\text{opt}$, the parameters $T_{\text{min}}$ and $T_{\text{opt}}$ are
 provided and $T_{\text{max}}$ is calculated internally as $T_{\text{max}} = 2 \cdot T_{\text{opt}} - T_{\text{min}}$.
 
-#### Exponential Function for Respiration $D_{\text(temp,Q10)}$
+#### Exponential Function for Respiration $D_{\text{temp,Q10}}$
 
 The temperature response of autotrophic  $(R_a)$ and heterotrophic  $(R_H)$ respiration represented as an exponential
 relationship using a simplified Arrhenius function.
@@ -939,8 +935,7 @@ four $Q_{10}$ values ranged from 1.4 to 5.8 when SIPNET was calibrated to $CO_2$
 ### Moisture dependence functions $D_{water}$
 
 Moisture dependence functions are typically based on soil water content as a fraction of water holding capacity, also
-referred to as soil moisture or fractional soil wetness. We will represent this fraction of soil wetness
-as $f_\text{WHC}$.
+referred to as soil moisture or fractional soil wetness ($f_\text{WHC}$).
 
 #### Soil Water Content Fraction
 

docs/parameters.md

@@ -106,7 +106,7 @@ Run-time parameters can change from one run to the next, or when the model is st
 | $f_{\text{WHC},0}$               | soilWFracInit  | Initial soil water fraction                                              | unitless                                                            | May exceed 1.0 when modeling flooded conditions; $W_{\text{soil},0} = f_{\text{WHC},0} \cdot W_{\text{WHC}}$          |
 | $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{min, soil},0}$          | mineralNInit   | Initial mineral nitrogen content                                         | $\text{g N} \cdot \text{m}^{-2}$                                    | Single mineral N pool used by soil and litter N fluxes                                   |
 | $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                                                 |                                                                                          |
@@ -200,13 +200,12 @@ Run-time parameters can change from one run to the next, or when the model is st
 
 ### Nitrogen Cycle Parameters
 
-Run-time parameters support mineralization, volatilization, leaching, and
-pool stoichiometry.
+Run-time parameters support mineral nitrogen losses through volatilization and leaching.
 
-| Symbol               | Parameter Name      | Definition                                                                             | Units             | Notes              |
-| -------------------- | ------------------- | -------------------------------------------------------------------------------------- | ----------------- | ------------------ |
-| $K_\text{vol}$       | nVolatilizationFrac | Fraction of $N_\text{min}$ volatilized per day (modulated by temperature and moisture) | $\text{day}^{-1}$ | \eqref{eq:n_vol}   |
-| $f^N_{\text{leach}}$ | nLeachingFrac       | Leaching coefficient applied to $N_\text{min}$ scaled by drainage                      | $\text{day}^{-1}$ | \eqref{eq:n_leach} |
+| Symbol                 | Parameter Name       | Definition                                                                                                                           | Units             | Notes                            |
+| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------------------------------- |
+| $K_\text{vol}$         | nVolatilizationFrac  | Nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a proportion of available $N_\text{min}$ | $\text{day}^{-1}$ | \eqref{eq:n_vol}                 |
+| $f^N_{\text{leach}}$   | nLeachingFrac        | Fraction of $N_\text{min}$ available to be leached, applied after scaling by $\phi = \min(F^W_\text{drainage}/W_\text{WHC}, 1)$      | $\text{day}^{-1}$  | \eqref{eq:n_leach}               |
 
 ### Moisture-Related Parameters
 

src/sipnet/state.h

@@ -344,7 +344,7 @@ typedef struct Parameters {
   // Fraction of mineral N available to be volatilized per day, d^-1
   double nVolatilizationFrac;
 
-  // Fraction of mineral N available to be leached, unitless
+  // Fraction of mineral N available to be leached per day, d^-1
   double nLeachingFrac;
 
   // C:N ratio for leaves, assumed static, g C/g N