SIP273 Add waterDrainFrac to allow water > WHC

CMakeLists.txt

@@ -56,6 +56,7 @@ add_library(tests
         tests/sipnet/test_modeling/testNitrogenCycle.c
         tests/sipnet/test_modeling/testDependencyFunctions.c
         tests/sipnet/test_modeling/testBalance.c
+        tests/sipnet/test_modeling/testSoilMoisture.c
         tests/sipnet/test_restart_infrastructure/testRestartMVP.c
         tests/sipnet/test_restart_infrastructure/testRestartMissedEnvi.c
         tests/sipnet/test_restart_infrastructure/testRestartMissedCtx.c

docs/.alternate-model-structure-ideas.md

@@ -16,31 +16,33 @@ $$
 
 Heterotrophic respiration ($R_h$) is a function of soil carbon content ($C_S$), a scaling factor ($K_h$), the $Q_{10}$ factor, and the ratio of soil moisture ($W$) to water holding capacity ($W_e$).
 
-## Irrigation
+## Irrigation and Flooding
 
-### Moisture based irrigation
+Some alternative ways to represent irrigation and flooding:
 
-Currently, irrigation is specified as an amount.
+* **Explicit flood events**
+  * `flood_on` / `flood_off` toggle ponded (saturated) conditions
+  * set flood depth
+  * While active: set W to WHC+flood depth
+  * Simple to implement (only applies to flooding)
 
-Additional approach based on farmer behavior:
-To represent an irrigation program that sets a moisture range and turns irrigation on at a lower moisture threshold and of at an upper threshold. This could be done internally by directly changing the soil moisture content - while keeping track of the amount of water added to report in events.out.
+* **Moisture-threshold irrigation**
+  * Maintain soil moisture within bounds (`W_min`, `W_max`)
+  * If `W_soil < W_min`, add water to reach `W_max`
+  * Track applied water diagnostically and write to events.out (no explicit scheduling)
+  * Pros: consistent with actual management
 
-### Flooding
+* **Externally specified water state**
+  * Ingest `W_soil` or pond depth time series from upstream pipeline
+  * Internal water balance becomes diagnostic (no prognostic water dynamics)
+  * Soil moisture was previously an optional input that was removed (I think because it didn't work as intended)
+  * Cons: requires time series of soil moisture.
 
-There are multiple options for representing flooding.
+Notes:
 
-Set indicator variable to 1 if the site is a wetland, 0 otherwise. Then
-
-1. if the site is a wetland, set the drainage to zero OR
-2. increase the threshold above which water drains e.g.
-
-𝐹drainage= max(𝑊soil − WHC, 0)
-
-becomes
-
-𝐹drainage= max(𝑊soil − k * WHC, 0)
-
-K could be a fixed value like 2 or 10. Or a site level parameter if warranted (e.g. based on soil type, or to allow different flood irrigation depths).
+* Event-based (flood_on/off) and threshold-based approaches are simplest to implement  
+* Key tradeoff: explicit management representation vs simplicity and dependence on upstream data
+* Moisture threshold irrigation supports a scheme that 'assume no water limitation', but also supports common scenarios in whic drying is permitted.
 
 ## Splitting $N_\text{min}$ into $NH_4$$ and $NO_3$
 

docs/CHANGELOG.md

@@ -13,8 +13,6 @@ sections to include in release notes:
 
 ### Added
 
-- Add woodCreation to sipnet.out (#161)
-
 ### Fixed
 
 ### Changed
@@ -50,6 +48,7 @@ sections to include in release notes:
 - Nitrogen demand, fixation flux, and uptake flux (#265)
 - Methane production option, controlled by the `anaerobic` cli option (#269)
 - Nitrogen limitation support (#298)
+- `flooding` cli option and `waterDrainFrac` parameter added (#273, #307)
 
 ### Fixed
 

docs/model-structure.md

@@ -737,18 +737,29 @@ irrigation) is assumed to evaporate the same day and therefore never enters $W_{
 
 ### Drainage
 
-Under well-drained conditions, drainage occurs when soil water content $(W_{\text{soil}})$ exceeds the soil water
-holding capacity  $(W_{\text{WHC}})$. Beyond this point, additional water drains off at a rate controlled by the
-drainage parameter $f_{\text{drain}}$ defined as the fraction of soil water that can be removed in one day. For well
-drained soils, this $f_{\text{drain}}=1$. Setting $f_{\text{drain}}<1$ reduces the rate of drainage. Flooding can be
-simulated by requiring a combination of a low $f_{\text{drain}}$ and sufficient $F^W_\text{irrig|precip,soil}$ to
-maintain flooded conditions.
+Drainage occurs when soil water content $(W_{\text{soil}})$ exceeds the soil water holding capacity $(W_{\text{WHC}})$.
+Beyond this point, additional water drains off at a rate that depends on whether `FLOODING` is enabled 
+(CLI: `--flooding`).
+
+If `FLOODING` is not enabled (the default behavior), all excess water drains away at each time step. This mode is
+appropriate for well-drained soil.
+
+\begin{equation}
+F^W_{\text{drainage}} = \frac{\max(W_{\text{soil}} - W_{\text{WHC}}, 0)}{\Delta t}
+\label{eq:drainage_no_flooding}
+\end{equation}
+
+If `FLOODING` is enabled, the rate is controlled by the drainage parameter $f_{\text{drain}}$, defined as the fraction
+of excess soil water that can be removed per day.
 
 \begin{equation}
 F^W_{\text{drainage}} = f_\text{drain} \cdot \max(W_{\text{soil}} - W_{\text{WHC}}, 0)
-\label{eq:drainage}
+\label{eq:drainage_flooding}
 \end{equation}
 
+Flooding can be simulated by using a combination of low $f_{\text{drain}}$ and sufficient 
+$F^W_\text{irrig|precip,soil}$ to maintain flooded conditions.
+
 This is adapted from the original SIPNET formulation (Braswell et al 2005), adding a new parameter that controls the
 drainage rate.
 
@@ -821,8 +832,13 @@ r_d = \frac{\text{rdConst}}{u},
 \qquad r_{\text{soil}} = \exp\!\left(r_{\text{soil},1} - r_{\text{soil},2}\frac{W_{\text{soil}}}{W_{\text{WHC}}}\right)
 \end{equation*}
 
+For soil evaporation, SIPNET assumes a saturated-surface approximation by clipping $\frac{W_\text{soil}}{W_\text{WHC}}$
+to $[0,1]$ before calculating $r_\text{soil}$.
+
 Negative (condensation) values are clipped to zero. If snow > 0 then $F^W_{\text{soil,evap}}=0$.
 
+For soil evaporation, SIPNET assumes a saturated-surface approximation by clipping $\frac{W_\text{soil}}{W_\text{WHC}}$ to $[0,1]$ before calculating $r_\text{soil}$.
+
 #### Total Evaporation
 
 Total evaporation is calculated as the sum of intercepted water, soil evaporation, and sublimation:
@@ -866,7 +882,8 @@ F^W_\text{trans} = \min(F^W_\text{trans, pot}, f \cdot W_\text{soil})
 This is equation (A15) from Braswell, et al. (2005).
 
 Actual transpiration  $(F^W_\text{trans})$ is the minimum of potential transpiration  $(F^W_{\text{trans,pot}})$ and the
-fraction  $(f)$ of the total soil water  $(W_\text{soil})$ that is removable in one day.
+fraction  $(f)$ of the plant-available soil water  $(W_\text{soil})$ that is removable in one day.
+Plant-available soil water is capped at the water holding capacity $W_\text{WHC}$.
 
 ## Dependence Functions for Temperature and Moisture