From 79cc419896b71a3ef79bef3ea1386e85a11cce3d Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Thu, 5 Jun 2025 16:26:37 -0700 Subject: [PATCH 01/42] Add documentation for hydrology and plant hydraulics, converted from CLM5 technical note. --- components/elm/docs/tech-guide/hydrology.md | 961 ++++++++++++++++++++ components/elm/docs/tech-guide/index.md | 2 + components/elm/docs/tech-guide/phs.md | 679 ++++++++++++++ 3 files changed, 1642 insertions(+) create mode 100644 components/elm/docs/tech-guide/hydrology.md create mode 100644 components/elm/docs/tech-guide/phs.md diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md new file mode 100644 index 000000000000..a8044e365e0c --- /dev/null +++ b/components/elm/docs/tech-guide/hydrology.md @@ -0,0 +1,961 @@ + +<<<<<<< HEAD +======= +The model parameterizes interception, throughfall, canopy drip, snow +accumulation and melt, water transfer between snow layers, infiltration, +evaporation, surface runoff, sub-surface drainage, redistribution within +the soil column, and groundwater discharge and recharge to simulate +changes in canopy water $\Delta W_{can,\,liq}$, canopy snow water +$\Delta W_{can,\,sno}$ surface water $\Delta W_{sfc}$, snow water +$\Delta W_{sno}$, soil water $\Delta w_{liq,\, i}$, and soil ice +$\Delta w_{ice,\, i}$, and water in the unconfined aquifer +$\Delta W_{a}$ (all in kg m^-2^ or mm of H~2~O) +(`Figure Hydrologic processes`{.interpreted-text role="numref"}). + +The total water balance of the system is + +$$\begin{aligned} +\begin{array}{l} {\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} +\end{aligned}$$ + +where $q_{rain}$ is the liquid part of precipitation, $q_{sno}$ is the +solid part of precipitation, $E_{v}$ is ET from vegetation (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}), $E_{g}$ is ground evaporation (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}), $q_{over}$ is surface runoff (section +`Surface Runoff`{.interpreted-text role="numref"}), $q_{h2osfc}$ is +runoff from surface water storage (section +`Surface Runoff`{.interpreted-text role="numref"}), $q_{drai}$ is +sub-surface drainage (section +`Lateral Sub-surface Runoff`{.interpreted-text role="numref"}), +$q_{rgwl}$ and $q_{snwcp,ice}$ are liquid and solid runoff from glaciers +and lakes, and runoff from other surface types due to snow capping +(section +`Runoff from glaciers and snow-capped surfaces`{.interpreted-text +role="numref"}) (all in kg m^-2^ s^-1^), $N_{levsoi}$ is the number of +soil layers (note that hydrology calculations are only done over soil +layers 1 to $N_{levsoi}$; ground levels $N_{levsoi} +1$ to $N_{levgrnd}$ +are currently hydrologically inactive; +`(Lawrence et al. 2008) `{.interpreted-text +role="ref"} and $\Delta t$ is the time step (s). + +::: {#Figure Hydrologic processes} +![Hydrologic processes represented in CLM.](hydrologic.processes.png) +::: + +## Canopy Water {#Canopy Water} + +Liquid precipitation is either intercepted by the canopy, falls directly +to the snow/soil surface (throughfall), or drips off the vegetation +(canopy drip). Solid precipitation is treated similarly, with the +addition of unloading of previously intercepted snow. Interception by +vegetation is divided between liquid and solid phases $q_{intr,\,liq}$ +and $q_{intr,\,ice}$ (kg m^-2^ s^-1^) + +$$q_{intr,\,liq} = f_{pi,\,liq} \ q_{rain}$$ + +$$q_{intr,\,ice} = f_{pi,\,ice} \ q_{sno}$$ + +where $f_{pi,\,liq}$ and $f_{pi,\,ice}$ are the fractions of intercepted +precipitation of rain and snow, respectively + +$$f_{pi,\,liq} = \alpha_{liq} \ tanh \left(L+S\right)$$ + +$$f_{pi,\,ice} =\alpha_{sno} \ \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} \ ,$$ + +and $L$ and $S$ are the exposed leaf and stem area index, respectively +(section `Phenology and vegetation burial by snow`{.interpreted-text +role="numref"}), and the $\alpha$\'s scale the fractional area of a leaf +that collects water +(`Lawrence et al. 2007 `{.interpreted-text +role="ref"}). Default values of $\alpha_{liq}$ and $\alpha_{sno}$ are +set to 1. Throughfall (kg m^-2^ s^-1^) is also divided into liquid and +solid phases, reaching the ground (soil or snow surface) as + +$$q_{thru,\, liq} = q_{rain} \left(1 - f_{pi,\,liq}\right)$$ + +$$q_{thru,\, ice} = q_{sno} \left(1 - f_{pi,\,ice}\right)$$ + +Similarly, the liquid and solid canopy drip fluxes are + +$$q_{drip,\, liq} =\frac{W_{can,\,liq}^{intr} -W_{can,\,liq}^{max } }{\Delta t} \ge 0$$ + +$$q_{drip,\, ice} =\frac{W_{can,\,sno}^{intr} -W_{can,\,sno}^{max } }{\Delta t} \ge 0$$ + +where + +$$W_{can,liq}^{intr} =W_{can,liq}^{n} +q_{intr,\, liq} \Delta t\ge 0$$ + +and + +$$W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr,\, ice} \Delta t\ge 0$$ + +are the the canopy liquid water and snow water equivalent after +accounting for interception, $W_{can,\,liq}^{n}$ and $W_{can,\,sno}^{n}$ +are the canopy liquid and snow water from the previous time step, and +$W_{can,\,liq}^{max }$ and $W_{can,\,snow}^{max }$ (kg m^-2^ or mm of +H~2~O) are the maximum amounts of liquid water and snow the canopy can +hold. They are defined by + +$$W_{can,\,liq}^{max } =p_{liq}\left(L+S\right)$$ + +$$W_{can,\,sno}^{max } =p_{sno}\left(L+S\right).$$ + +The maximum storage of liquid water is $p_{liq}=0.1$ kg m^-2^ +(`Dickinson et al. 1993 `{.interpreted-text +role="ref"}), and that of snow is $p_{sno}=6$ kg m^-2^, consistent with +reported field measurements +(`Pomeroy et al. 1998 `{.interpreted-text role="ref"}). + +Canopy snow unloading from wind speed $u$ and above-freezing +temperatures are modeled from linear fluxes and e-folding times similar +to `Roesch et al. (2001) `{.interpreted-text role="ref"} + +$$q_{unl,\, wind} =\frac{u W_{can,sno}}{1.56\times 10^5 \text{ m}}$$ + +$$q_{unl,\, temp} =\frac{W_{can,sno}(T-270 \textrm{ K})}{1.87\times 10^5 \text{ K s}} > 0$$ + +$$q_{unl,\, tot} =\min \left( q_{unl,\, wind} +q_{unl,\, temp} ,W_{can,\, sno} \right)$$ + +The canopy liquid water and snow water equivalent are updated as + +$$W_{can,\, liq}^{n+1} =W_{can,liq}^{n} + q_{intr,\, liq} - q_{drip,\, liq} \Delta t - E_{v}^{liq} \Delta t \ge 0$$ + +and + +$$W_{can,\, sno}^{n+1} =W_{can,sno}^{n} + q_{intr,\, ice} - \left(q_{drip,\, ice}+q_{unl,\, tot} \right)\Delta t + - E_{v}^{ice} \Delta t \ge 0$$ + +where $E_{v}^{liq}$ and $E_{v}^{ice}$ are partitioned from the stem and +leaf surface evaporation $E_{v}^{w}$ (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}) based on the vegetation temperature $T_{v}$ (K) (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}) and its relation to the freezing temperature of water +$T_{f}$ (K) (`Table Physical Constants`{.interpreted-text +role="numref"}) + +$$\begin{aligned} +E_{v}^{liq} = +\left\{\begin{array}{lr} +E_{v}^{w} & T_v > T_{f} \\ +0 & T_v \le T_f +\end{array}\right\} +\end{aligned}$$ + +$$\begin{aligned} +E_{v}^{ice} = +\left\{\begin{array}{lr} +0 & T_v > T_f \\ +E_{v}^{w} & T_v \le T_f +\end{array}\right\}. +\end{aligned}$$ + +The total rate of liquid and solid precipitation reaching the ground is +then + +$$q_{grnd,liq} =q_{thru,\, liq} +q_{drip,\, liq}$$ + +$$q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} +q_{unl,\, tot} .$$ + +Solid precipitation reaching the soil or snow surface, +$q_{grnd,\, ice} \Delta t$, is added immediately to the snow pack +(Chapter `rst_Snow Hydrology`{.interpreted-text role="numref"}). The +liquid part, $q_{grnd,\, liq} \Delta t$ is added after surface fluxes +(Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}) and snow/soil temperatures (Chapter +`rst_Soil and Snow Temperatures`{.interpreted-text role="numref"}) have +been determined. + +The wetted fraction of the canopy (stems plus leaves), which is required +for surface flux (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}) calculations, is +(`Dickinson et al.1993 `{.interpreted-text +role="ref"}) + +$$\begin{aligned} +f_{wet} = +\left\{\begin{array}{lr} +\left[\frac{W_{can} }{p_{liq}\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right.} 3} } \le 1 & \qquad L+S > 0 \\ +0 &\qquad L+S = 0 +\end{array}\right\} +\end{aligned}$$ + +while the fraction of the canopy that is dry and transpiring is + +$$\begin{aligned} +f_{dry} = +\left\{\begin{array}{lr} +\frac{\left(1-f_{wet} \right)L}{L+S} & \qquad L+S > 0 \\ +0 &\qquad L+S = 0 +\end{array}\right\}. +\end{aligned}$$ + +Similarly, the snow-covered fraction of the canopy is used for surface +alebdo when intercepted snow is present (Chapter +`rst_Surface Albedos`{.interpreted-text role="numref"}) + +$$\begin{aligned} +f_{can,\, sno} = +\left\{\begin{array}{lr} +\left[\frac{W_{can,\, sno} }{p_{sno}\left(L+S\right)} \right]^{{3\mathord{\left/ {\vphantom {3 20}} \right.} 20} } \le 1 & \qquad L+S > 0 \\ +0 &\qquad L+S = 0 +\end{array}\right\}. +\end{aligned}$$ + +## Surface Runoff, Surface Water Storage, and Infiltration {#Surface Runoff, Surface Water Storage, and Infiltration} + +The moisture input at the grid cell surface,$q_{liq,\, 0}$, is the sum +of liquid precipitation reaching the ground and melt water from snow (kg +m^-2^ s^-1^). The moisture flux is then partitioned between surface +runoff, surface water storage, and infiltration into the soil. + +### Surface Runoff {#Surface Runoff} + +The simple TOPMODEL-based +(`Beven and Kirkby 1979 `{.interpreted-text +role="ref"}) runoff model (SIMTOP) described by +`Niu et al. (2005) `{.interpreted-text role="ref"} is +implemented to parameterize runoff. A key concept underlying this +approach is that of fractional saturated area $f_{sat}$, which is +determined by the topographic characteristics and soil moisture state of +a grid cell. The saturated portion of a grid cell contributes to surface +runoff, $q_{over}$, by the saturation excess mechanism (Dunne runoff) + +$$q_{over} =f_{sat} \ q_{liq,\, 0}$$ + +The fractional saturated area is a function of soil moisture + +$$f_{sat} =f_{\max } \ \exp \left(-0.5f_{over} z_{\nabla } \right)$$ + +where $f_{\max }$ is the potential or maximum value of $f_{sat}$, +$f_{over}$ is a decay factor (m^-1^), and $z_{\nabla}$ is the water +table depth (m) (section `Lateral Sub-surface Runoff`{.interpreted-text +role="numref"}). The maximum saturated fraction, $f_{\max }$, is defined +as the value of the discrete cumulative distribution function (CDF) of +the topographic index when the grid cell mean water table depth is zero. +Thus, $f_{\max }$ is the percent of pixels in a grid cell whose +topographic index is larger than or equal to the grid cell mean +topographic index. It should be calculated explicitly from the CDF at +each grid cell at the resolution that the model is run. However, because +this is a computationally intensive task for global applications, +$f_{\max }$ is calculated once at 0.125° resolution using the 1-km +compound topographic indices (CTIs) based on the HYDRO1K dataset +(`Verdin and Greenlee 1996 `{.interpreted-text +role="ref"}) from USGS following the algorithm in +`Niu et al. (2005) `{.interpreted-text role="ref"} and then +area-averaged to the desired model resolution (section +`Surface Data`{.interpreted-text role="numref"}). Pixels with CTIs +exceeding the 95 percentile threshold in each 0.125° grid cell are +excluded from the calculation to eliminate biased estimation of +statistics due to large CTI values at pixels on stream networks. For +grid cells over regions without CTIs such as Australia, the global mean +$f_{\max }$ is used to fill the gaps. See +`Li et al. (2013b) `{.interpreted-text role="ref"} for +additional details. The decay factor $f_{over}$ for global simulations +was determined through sensitivity analysis and comparison with observed +runoff to be 0.5 m^-1^. + +### Surface Water Storage {#Surface Water Storage} + +A surface water store has been added to the model to represent wetlands +and small, sub-grid scale water bodies. As a result, the wetland land +unit has been removed as of CLM4.5. The state variables for surface +water are the mass of water $W_{sfc}$ (kg m^-2^) and temperature +$T_{h2osfc}$ (Chapter `rst_Soil and Snow Temperatures`{.interpreted-text +role="numref"}). Surface water storage and outflow are functions of fine +spatial scale elevation variations called microtopography. The +microtopography is assumed to be distributed normally around the grid +cell mean elevation. Given the standard deviation of the +microtopographic distribution, $\sigma _{micro}$ (m), the fractional +area of the grid cell that is inundated can be calculated. Surface water +storage, $Wsfc$, is related to the height (relative to the grid cell +mean elevation) of the surface water, $d$, by + +$$W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } }$$ + +where $erf$ is the error function. For a given value of $W_{sfc}$, +`7.66`{.interpreted-text role="eq"} can be solved for $d$ using the +Newton-Raphson method. Once $d$ is known, one can determine the fraction +of the area that is inundated as + +$$f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)$$ + +No global datasets exist for microtopography, so the default +parameterization is a simple function of slope + +$$\sigma _{micro} =\left(\beta +\beta _{0} \right)^{\eta }$$ + +where $\beta$ is the topographic slope, +$\beta_{0} =\left(\sigma_{\max } \right)^{\frac{1}{\eta } }$ determines +the maximum value of $\sigma_{micro}$, and $\eta$ is an adjustable +parameter. Default values in the model are $\sigma_{\max } =0.4$ and +$\eta =-3$. + +If the spatial scale of the microtopography is small relative to that of +the grid cell, one can assume that the inundated areas are distributed +randomly within the grid cell. With this assumption, a result from +percolation theory can be used to quantify the fraction of the inundated +portion of the grid cell that is interconnected + +$$\begin{aligned} +\begin{array}{lr} f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } & \qquad f_{h2osfc} >f_{c} \\ f_{connected} =0 &\qquad f_{h2osfc} \le f_{c} \end{array} +\end{aligned}$$ + +where $f_{c}$ is a threshold below which no single connected inundated +area spans the grid cell and $\mu$ is a scaling exponent. Default values +of $f_{c}$ and $\mu$ are 0.4 and 0.14, respectively. When the inundated +fraction of the grid cell surpasses $f_{c}$, the surface water store +acts as a linear reservoir + +$$q_{out,h2osfc}=k_{h2osfc} \ f_{connected} \ (Wsfc-Wc)\frac{1}{\Delta t}$$ + +where $q_{out,h2osfc}$ is the surface water runoff, $k_{h2osfc}$ is a +constant, $Wc$ is the amount of surface water present when +$f_{h2osfc} =f_{c}$, and $\Delta t$ is the model time step. The linear +storage coefficent $k_{h2osfc} = \sin \left(\beta \right)$ is a function +of grid cell mean topographic slope where $\beta$ is the slope in +radians. + +### Infiltration {#Infiltration} + +The surface moisture flux remaining after surface runoff has been +removed, + +$$q_{in,surface} = (1-f_{sat}) \ q_{liq,\, 0}$$ + +is divided into inputs to surface water ($q_{in,\, h2osfc}$ ) and the +soil $q_{in,soil}$. If $q_{in,soil}$ exceeds the maximum soil +infiltration capacity (kg m^-2^ s^-1^), + +$$q_{infl,\, \max } =(1-f_{sat}) \ \Theta_{ice} k_{sat}$$ + +where $\Theta_{ice}$ is an ice impedance factor (section +`Hydraulic Properties`{.interpreted-text role="numref"}), infiltration +excess (Hortonian) runoff is generated + +$$q_{infl,\, excess} =\max \left(q_{in,soil} -\left(1-f_{h2osfc} \right)q_{\inf l,\max } ,0\right)$$ + +and transferred from $q_{in,soil}$ to $q_{in,h2osfc}$. After evaporative +losses have been removed, these moisture fluxes are + +$$q_{in,\, h2osfc} = f_{h2osfc} q_{in,surface} + q_{infl,excess} - q_{evap,h2osfc}$$ + +and + +$$q_{in,soil} = (1-f_{h2osfc} ) \ q_{in,surface} - q_{\inf l,excess} - (1 - f_{sno} - f_{h2osfc} ) \ q_{evap,soil}.$$ + +The balance of surface water is then calculated as + +$$\Delta W_{sfc} =\left(q_{in,h2osfc} - q_{out,h2osfc} - q_{drain,h2osfc} \right) \ \Delta t.$$ + +Bottom drainage from the surface water store + +$$q_{drain,h2osfc} = \min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right)$$ + +is then added to $q_{in,soil}$ giving the total infiltration into the +surface soil layer + +$$q_{infl} = q_{in,soil} + q_{drain,h2osfc}$$ + +Infiltration $q_{infl}$ and explicit surface runoff $q_{over}$ are not +allowed for glaciers. + +## Soil Water {#Soil Water} + +Soil water is predicted from a multi-layer model, in which the vertical +soil moisture transport is governed by infiltration, surface and +sub-surface runoff, gradient diffusion, gravity, and canopy +transpiration through root extraction +(`Figure Hydrologic processes`{.interpreted-text role="numref"}). + +For one-dimensional vertical water flow in soils, the conservation of +mass is stated as + +$$\frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} - e$$ + +where $\theta$ is the volumetric soil water content (mm^3^ of water / +mm^-3^ of soil), $t$ is time (s), $z$ is height above some datum in the +soil column (mm) (positive upwards), $q$ is soil water flux (kg m^-2^ +s^-1^ or mm s^-1^) (positive upwards), and $e$ is a soil moisture sink +term (mm of water mm^-1^ of soil s^-1^) (ET loss). This equation is +solved numerically by dividing the soil column into multiple layers in +the vertical and integrating downward over each layer with an upper +boundary condition of the infiltration flux into the top soil layer +$q_{infl}$ and a zero-flux lower boundary condition at the bottom of the +soil column (sub-surface runoff is removed later in the timestep, +section `Lateral Sub-surface Runoff`{.interpreted-text role="numref"}). + +The soil water flux $q$ in equation `7.79`{.interpreted-text role="eq"} +can be described by Darcy\'s law +`(Dingman 2002) `{.interpreted-text role="ref"} + +$$q = -k \frac{\partial \psi _{h} }{\partial z}$$ + +where $k$ is the hydraulic conductivity (mm s^-1^), and $\psi _{h}$ is +the hydraulic potential (mm). The hydraulic potential is + +$$\psi _{h} =\psi _{m} +\psi _{z}$$ + +where $\psi _{m}$ is the soil matric potential (mm) (which is related to +the adsorptive and capillary forces within the soil matrix), and +$\psi _{z}$ is the gravitational potential (mm) (the vertical distance +from an arbitrary reference elevation to a point in the soil). If the +reference elevation is the soil surface, then $\psi _{z} =z$. Letting +$\psi =\psi _{m}$, Darcy\'s law becomes + +$$q = -k \left[\frac{\partial \left(\psi +z\right)}{\partial z} \right].$$ + +Equation `7.82`{.interpreted-text role="eq"} can be further manipulated +to yield + +$$q = -k \left[\frac{\partial \left(\psi +z\right)}{\partial z} \right] += -k \left(\frac{\partial \psi }{\partial z} + 1 \right) \ .$$ + +Substitution of this equation into equation `7.79`{.interpreted-text +role="eq"}, with $e = 0$, yields the Richards equation +`(Dingman 2002) `{.interpreted-text role="ref"} + +$$\frac{\partial \theta }{\partial t} = +\frac{\partial }{\partial z} \left[k\left(\frac{\partial \psi }{\partial z} + 1 +\right)\right].$$ + +In practice (Section `Numerical Solution Hydrology`{.interpreted-text +role="numref"}), changes in soil water content are predicted from +`7.79`{.interpreted-text role="eq"} using finite-difference +approximations for `7.84`{.interpreted-text role="eq"}. + +### Hydraulic Properties {#Hydraulic Properties} + +The hydraulic conductivity $k_{i}$ (mm s^-1^) and the soil matric +potential $\psi _{i}$ (mm) for layer $i$ vary with volumetric soil water +$\theta _{i}$ and soil texture. As with the soil thermal properties +(section `Soil And Snow Thermal Properties`{.interpreted-text +role="numref"}) the hydraulic properties of the soil are assumed to be a +weighted combination of the mineral properties, which are determined +according to sand and clay contents based on work by +`Clapp and Hornberger (1978) `{.interpreted-text +role="ref"} and `Cosby et al. (1984) `{.interpreted-text +role="ref"}, and organic properties of the soil +(`Lawrence and Slater 2008 `{.interpreted-text +role="ref"}). + +The hydraulic conductivity is defined at the depth of the interface of +two adjacent layers $z_{h,\, i}$ +(`Figure Water flux schematic`{.interpreted-text role="numref"}) and is +a function of the saturated hydraulic conductivity +$k_{sat} \left[z_{h,\, i} \right]$, the liquid volumetric soil moisture +of the two layers $\theta _{i}$ and $\theta_{i+1}$ and an ice impedance +factor $\Theta_{ice}$ + +$$\begin{aligned} +k\left[z_{h,\, i} \right] = +\left\{\begin{array}{lr} +\Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)}{0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ +\Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} +\end{array}\right\}. +\end{aligned}$$ + +The ice impedance factor is a function of ice content, and is meant to +quantify the increased tortuosity of the water flow when part of the +pore space is filled with ice. +`Swenson et al. (2012) `{.interpreted-text role="ref"} +used a power law form + +$$\Theta_{ice} = 10^{-\Omega F_{ice} }$$ + +where $\Omega = 6$and $F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }$ is +the ice-filled fraction of the pore space. + +Because the hydraulic properties of mineral and organic soil may differ +significantly, the bulk hydraulic properties of each soil layer are +computed as weighted averages of the properties of the mineral and +organic components. The water content at saturation (i.e. porosity) is + +$$\theta_{sat,i} =(1-f_{om,i} )\theta_{sat,\min ,i} +f_{om,i} \theta_{sat,om}$$ + +where $f_{om,i}$ is the soil organic matter fraction, $\theta_{sat,om}$ +is the porosity of organic matter, and the porosity of the mineral soil +$\theta_{sat,\min,i}$ is + +$$\theta_{sat,\min ,i} = 0.489 - 0.00126(\% sand)_{i} .$$ + +The exponent $B_{i}$ is + +$$B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om}$$ + +where $B_{om}$ is for organic matter and + +$$B_{\min ,i} =2.91+0.159(\% clay)_{i} .$$ + +The soil matric potential (mm) is defined at the node depth $z_{i}$ of +each layer $i$ (`Figure Water flux schematic`{.interpreted-text +role="numref"}) + +$$\psi _{i} =\psi _{sat,\, i} \left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta_{i} }{\theta_{sat,\, i} } \le 1$$ + +where the saturated soil matric potential (mm) is + +$$\psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om}$$ + +where $\psi _{sat,om}$ is the saturated organic matter matric potential +and the saturated mineral soil matric potential $\psi _{sat,\min,i}$ is + +$$\psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } .$$ + +The saturated hydraulic conductivity, $k_{sat} \left[z_{h,\, i} \right]$ +(mm s^-1^), for organic soils ($k_{sat,\, om}$ ) may be two to three +orders of magnitude larger than that of mineral soils +($k_{sat,\, \min }$ ). Bulk soil layer values of $k_{sat}$ calculated as +weighted averages based on $f_{om}$ may therefore be determined +primarily by the organic soil properties even for values of $f_{om}$ as +low as 1 %. To better represent the influence of organic soil material +on the grid cell average saturated hydraulic conductivity, the soil +organic matter fraction is further subdivided into \"connected\" and +\"unconnected\" fractions using a result from percolation theory +(`Stauffer and Aharony 1994 `{.interpreted-text +role="ref"}, +`Berkowitz and Balberg 1992 `{.interpreted-text +role="ref"}). Assuming that the organic and mineral fractions are +randomly distributed throughout a soil layer, percolation theory +predicts that above a threshold value $f_{om} = f_{threshold}$, +connected flow pathways consisting of organic material only exist and +span the soil space. Flow through these pathways interacts only with +organic material, and thus can be described by $k_{sat,\, om}$. This +fraction of the grid cell is given by + +$$\begin{aligned} +\begin{array}{lr} +f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta_{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ +f_{perc} = 0 & \qquad f_{om} `{.interpreted-text +role="ref"}) as + +$$k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\% sand\right)_{i} } .$$ + +The bulk soil layer saturated hydraulic conductivity is then computed as + +$$k_{sat} \left[z_{h,\, i} \right]=f_{uncon,\, i} k_{sat,\, uncon} \left[z_{h,\, i} \right]+(1-f_{uncon,\, i} )k_{sat,\, om} \left[z_{h,\, i} \right].$$ + +The soil organic matter properties implicitly account for the standard +observed profile of organic matter properties as + +$$\theta_{sat,om} = max(0.93 - 0.1\times z_{i} / zsapric, 0.83).$$ + +$$B_{om} = min(2.7 + 9.3\times z_{i} / zsapric, 12.0).$$ + +$$\psi_{sat,om} = min(10.3 - 0.2\times z_{i} / zsapric, 10.1).$$ + +$$k_{sat,om} = max(0.28 - 0.2799\times z_{i} / zsapric, k_{sat,\, \min } \left[z_{h,\, i} \right]).$$ + +where $zsapric =0.5$ m is the depth that organic matter takes on the +characteristics of sapric peat. + +### Numerical Solution {#Numerical Solution Hydrology} + +With reference to `Figure Water flux schematic`{.interpreted-text +role="numref"}, the equation for conservation of mass (equation +`7.79`{.interpreted-text role="eq"}) can be integrated over each layer +as + +$$\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} } e\, dz .$$ + +Note that the integration limits are negative since $z$ is defined as +positive upward from the soil surface. This equation can be written as + +$$\Delta z_{i} \frac{\partial \theta_{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} -e_{i}$$ + +where $q_{i}$ is the flux of water across interface $z_{h,\, i}$, +$q_{i-1}$ is the flux of water across interface $z_{h,\, i-1}$, and +$e_{i}$ is a layer-averaged soil moisture sink term (ET loss) defined as +positive for flow out of the layer (mm s^-1^). Taking the finite +difference with time and evaluating the fluxes implicitly at time $n+1$ +yields + +$$\frac{\Delta z_{i} \Delta \theta_{liq,\, i} }{\Delta t} =-q_{i-1}^{n+1} +q_{i}^{n+1} -e_{i}$$ + +where +$\Delta \theta_{liq,\, i} =\theta_{liq,\, i}^{n+1} -\theta_{liq,\, i}^{n}$ +is the change in volumetric soil liquid water of layer $i$ in time +$\Delta t$and $\Delta z_{i}$ is the thickness of layer $i$ (mm). + +The water removed by transpiration in each layer $e_{i}$ is a function +of the total transpiration $E_{v}^{t}$ (Chapter +`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`{.interpreted-text +role="numref"}) and the effective root fraction $r_{e,\, i}$ + +$$e_{i} =r_{e,\, i} E_{v}^{t} .$$ + +::: {#Figure Water flux schematic} +![Schematic diagram of numerical scheme used to solve for soil water +fluxes.](image2.png) +::: + +Shown are three soil layers, $i-1$, $i$, and $i+1$. The soil matric +potential $\psi$ and volumetric soil water $\theta_{liq}$ are defined at +the layer node depth $z$. The hydraulic conductivity +$k\left[z_{h} \right]$ is defined at the interface of two layers +$z_{h}$. The layer thickness is $\Delta z$. The soil water fluxes +$q_{i-1}$ and $q_{i}$ are defined as positive upwards. The soil moisture +sink term $e$ (ET loss) is defined as positive for flow out of the +layer. + +Note that because more than one plant functional type (PFT) may share a +soil column, the transpiration $E_{v}^{t}$ is a weighted sum of +transpiration from all PFTs whose weighting depends on PFT area as + +$$E_{v}^{t} =\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j}$$ + +where $npft$ is the number of PFTs sharing a soil column, +$\left(E_{v}^{t} \right)_{j}$ is the transpiration from the $j^{th}$ PFT +on the column, and $\left(wt\right)_{j}$ is the relative area of the +$j^{th}$ PFT with respect to the column. The effective root fraction +$r_{e,\, i}$ is also a column-level quantity that is a weighted sum over +all PFTs. The weighting depends on the per unit area transpiration of +each PFT and its relative area as + +$$r_{e,\, i} =\frac{\sum _{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }$$ + +where $\left(r_{e,\, i} \right)_{j}$ is the effective root fraction for +the $j^{th}$ PFT + +$$\begin{aligned} +\begin{array}{lr} +\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } & \qquad \left(\beta _{t} \right)_{j} >0 \\ +\left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta _{t} \right)_{j} =0 +\end{array} +\end{aligned}$$ + +and $\left(r_{i} \right)_{j}$ is the fraction of roots in layer $i$ +(Chapter `rst_Stomatal Resistance and Photosynthesis`{.interpreted-text +role="numref"}), $\left(w_{i} \right)_{j}$ is a soil dryness or plant +wilting factor for layer $i$ (Chapter +`rst_Stomatal Resistance and Photosynthesis`{.interpreted-text +role="numref"}), and $\left(\beta_{t} \right)_{j}$ is a wetness factor +for the total soil column for the $j^{th}$ PFT (Chapter +`rst_Stomatal Resistance and Photosynthesis`{.interpreted-text +role="numref"}). + +The soil water fluxes in `7.103`{.interpreted-text role="eq"},, which +are a function of $\theta_{liq,\, i}$ and $\theta_{liq,\, i+1}$ because +of their dependence on hydraulic conductivity and soil matric potential, +can be linearized about $\theta$ using a Taylor series expansion as + +$$q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } \Delta \theta_{liq,\, i} +\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } \Delta \theta_{liq,\, i+1}$$ + +$$q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } \Delta \theta_{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } \Delta \theta_{liq,\, i} .$$ + +Substitution of these expressions for $q_{i}^{n+1}$ and $q_{i-1}^{n+1}$ +into `7.103`{.interpreted-text role="eq"} results in a general +tridiagonal equation set of the form + +$$r_{i} =a_{i} \Delta \theta_{liq,\, i-1} +b_{i} \Delta \theta_{liq,\, i} +c_{i} \Delta \theta_{liq,\, i+1}$$ + +where + +$$a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} }$$ + +$$b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t}$$ + +$$c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} }$$ + +$$r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} .$$ + +The tridiagonal equation set is solved over $i=1,\ldots,N_{levsoi}$. + +The finite-difference forms of the fluxes and partial derivatives in +equations `7.111`{.interpreted-text role="eq"} - +`7.114`{.interpreted-text role="eq"} can be obtained from equation +`7.82`{.interpreted-text role="eq"} as + +$$q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right]$$ + +$$q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right]$$ + +$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ + +$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ + +$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]$$ + +$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right].$$ + +The derivatives of the soil matric potential at the node depth are +derived from `7.94`{.interpreted-text role="eq"} + +$$\frac{\partial \psi _{i-1} }{\partial \theta_{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta_{\, \, i-1} }$$ + +$$\frac{\partial \psi _{i} }{\partial \theta_{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta_{i} }$$ + +$$\frac{\partial \psi _{i+1} }{\partial \theta_{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta_{\, i+1} }$$ + +with the constraint +$0.01\, \theta_{sat,\, i} \le \theta_{\, i} \le \theta_{sat,\, i}$. + +The derivatives of the hydraulic conductivity at the layer interface are +derived from `7.85`{.interpreted-text role="eq"} + +$$\begin{array}{l} +{\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } += \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } += \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}$$ + +where $\overline{\Theta}_{ice} = \Theta(\overline{\theta}_{ice})$ +`7.86`{.interpreted-text role="eq"}, +$\overline{\theta}_{ice} = 0.5\left(\theta_{ice\, i-1} +\theta_{ice\, i} \right)$, +$\overline{\theta}_{liq} = 0.5\left(\theta_{liq\, i-1} +\theta_{liq\, i} \right)$, +and +$\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i-1} +\theta_{sat,\, i} \right)$ + +and + +$$\begin{array}{l} +{\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } += \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } += \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}.$$ + +where +$\overline{\theta}_{liq} = 0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)$, +$\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)$. + +#### Equation set for layer $i=1$ + +For the top soil layer ($i=1$), the boundary condition is the +infiltration rate (section `Surface Runoff`{.interpreted-text +role="numref"}), $q_{i-1}^{n+1} =-q_{infl}^{n+1}$, and the water balance +equation is + +$$\frac{\Delta z_{i} \Delta \theta_{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} .$$ + +After grouping like terms, the coefficients of the tridiagonal set of +equations for $i=1$ are + +$$a_{i} =0$$ + +$$b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t}$$ + +$$c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} }$$ + +$$r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} .$$ + +#### Equation set for layers $i=2,\ldots ,N_{levsoi} -1$ + +The coefficients of the tridiagonal set of equations for +$i=2,\ldots,N_{levsoi} -1$ are + +$$a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} }$$ + +$$b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t}$$ + +$$c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} }$$ + +$$r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} .$$ + +#### Equation set for layer $i=N_{levsoi}$ + +For the lowest soil layer ($i=N_{levsoi}$ ), a zero-flux bottom boundary +condition is applied ($q_{i}^{n} =0$) and the coefficients of the +tridiagonal set of equations for $i=N_{levsoi}$ are + +$$a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} }$$ + +$$b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t}$$ + +$$c_{i} =0$$ + +$$r_{i} =q_{i-1}^{n} +e_{i} .$$ + +#### Adaptive Time Stepping + +The length of the time step is adjusted in order to improve the accuracy +and stability of the numerical solutions. The difference between two +numerical approximations is used to estimate the temporal truncation +error, and then the step size $\Delta t_{sub}$ is adjusted to meet a +user-prescribed error tolerance +`[Kavetski et al., 2002]`{.interpreted-text +role="ref"}. The temporal truncation error is estimated by comparing the +flux obtained from the first-order Taylor series expansion +($q_{i-1}^{n+1}$ and $q_{i}^{n+1}$, equations `7.108`{.interpreted-text +role="eq"} and `7.109`{.interpreted-text role="eq"}) against the flux at +the start of the time step ($q_{i-1}^{n}$ and $q_{i}^{n}$). Since the +tridiagonal solution already provides an estimate of +$\Delta \theta_{liq,i}$, it is convenient to compute the error for each +of the $i$ layers from equation `7.103`{.interpreted-text role="eq"} as + +$$\epsilon_{i} = \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t_{sub}} - +\left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] \ \frac{\Delta t_{sub}}{2}$$ + +and the maximum absolute error across all layers as + +$$\begin{array}{lr} +\epsilon_{crit} = {\rm max} \left( \left| \epsilon_{i} \right| \right) & \qquad 1 \le i \le nlevsoi +\end{array} \ .$$ + +The adaptive step size selection is based on specified upper and lower +error tolerances, $\tau_{U}$ and $\tau_{L}$. The solution is accepted if +$\epsilon_{crit} \le \tau_{U}$ and the procedure repeats until the +adaptive sub-stepping spans the full model time step (the sub-steps are +doubled if $\epsilon_{crit} \le \tau_{L}$, i.e., if the solution is very +accurate). Conversely, the solution is rejected if +$\epsilon_{crit} > \tau_{U}$. In this case the length of the sub-steps +is halved and a new solution is obtained. The halving of substeps +continues until either $\epsilon_{crit} \le \tau_{U}$ or the specified +minimum time step length is reached. + +Upon solution of the tridiagonal equation set, the liquid water contents +are updated as follows + +$$w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta_{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} .$$ + +The volumetric water content is + +$$\theta_{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } .$$ + +## Frozen Soils and Perched Water Table {#Frozen Soils and Perched Water Table} + +When soils freeze, the power-law form of the ice impedance factor +(section `Hydraulic Properties`{.interpreted-text role="numref"}) can +greatly decrease the hydraulic conductivity of the soil, leading to +nearly impermeable soil layers. When unfrozen soil layers are present +above relatively ice-rich frozen layers, the possibility exists for +perched saturated zones. Lateral drainage from perched saturated regions +is parameterized as a function of the thickness of the saturated zone + +$$q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right)$$ + +where $k_{drai,\, perch}$ depends on topographic slope and soil +hydraulic conductivity, + +$$k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta_{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right)$$ + +where $\Theta_{ice}$ is an ice impedance factor, $\beta$ is the mean +grid cell topographic slope in radians, $z_{frost}$ is the depth to the +frost table, and $z_{\nabla,perch}$ is the depth to the perched +saturated zone. The frost table $z_{frost}$ is defined as the shallowest +frozen layer having an unfrozen layer above it, while the perched water +table $z_{\nabla,perch}$ is defined as the depth at which the volumetric +water content drops below a specified threshold. The default threshold +is set to 0.9. Drainage from the perched saturated zone $q_{drai,perch}$ +is removed from layers $N_{perch}$ through $N_{frost}$, which are the +layers containing $z_{\nabla,perch}$ and, $z_{frost}$ respectively. + +## Lateral Sub-surface Runoff {#Lateral Sub-surface Runoff} + +Lateral sub-surface runoff occurs when saturated soil moisture +conditions exist within the soil column. Sub-surface runoff is + +$$q_{drai} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) +\Delta z_{sat}^{N_{baseflow}} \ ,$$ + +where $K_{baseflow}$ is a calibration parameter, $\beta$ is the +topographic slope, the exponent $N_{baseflow}$ = 1, and $\Delta z_{sat}$ +is the thickness of the saturated portion of the soil column. + +The saturated thickness is + +$$\Delta z_{sat} = z_{bedrock} - z_{\nabla},$$ + +where the water table $z_{\nabla}$ is determined by finding the first +soil layer above the bedrock depth (section +`Depth to Bedrock`{.interpreted-text role="numref"}) in which the +volumetric water content drops below a specified threshold. The default +threshold is set to 0.9. + +The specific yield, $S_{y}$, which depends on the soil properties and +the water table location, is derived by taking the difference between +two equilibrium soil moisture profiles whose water tables differ by an +infinitesimal amount + +$$S_{y} =\theta_{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right)$$ + +where B is the Clapp-Hornberger exponent. Because $S_{y}$ is a function +of the soil properties, it results in water table dynamics that are +consistent with the soil water fluxes described in section +`Soil Water`{.interpreted-text role="numref"}. + +After the above calculations, two numerical adjustments are implemented +to keep the liquid water content of each soil layer ($w_{liq,\, i}$ ) +within physical constraints of +$w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i}$ +where $w_{liq}^{\min } =0.01$ (mm). First, beginning with the bottom +soil layer $i=N_{levsoi}$, any excess liquid water in each soil layer +($w_{liq,\, i}^{excess} =w_{liq,\, i} -\left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i} \ge 0$) +is successively added to the layer above. Any excess liquid water that +remains after saturating the entire soil column is added to drainage +$q_{drai}$. Second, to prevent negative $w_{liq,\, i}$, each layer is +successively brought up to $w_{liq,\, i} =w_{liq}^{\min }$ by taking the +required amount of water from the layer below. If this results in +$w_{liq,\, N_{levsoi} } >>>>>> Converted from CLM5 diff --git a/components/elm/docs/tech-guide/index.md b/components/elm/docs/tech-guide/index.md index 6ce636548204..feef6d521697 100644 --- a/components/elm/docs/tech-guide/index.md +++ b/components/elm/docs/tech-guide/index.md @@ -7,3 +7,5 @@ Shortwave radiation model - [TOP Parameterization](top_solar_parameterization.md): Parameterization of sub-grid topographical effects on solar radiation. - [Longwave Radiation](longwave_radiation.md): Longwave radiation model +- [Hydrology](hydrology.md): Hydrology model +- [Plant Hydraulics](phs.md): Plant Hydraulics model diff --git a/components/elm/docs/tech-guide/phs.md b/components/elm/docs/tech-guide/phs.md new file mode 100644 index 000000000000..1f2fc254998f --- /dev/null +++ b/components/elm/docs/tech-guide/phs.md @@ -0,0 +1,679 @@ +<<<<<<< HEAD + +======= +# Plant Hydraulics + +## Roots {#Roots} + +### Vertical Root Distribution {#Vertical Root Distribution} + +The root fraction $r_{i}$ in each soil layer depends on the plant +functional type + +$$r_{i} = +\begin{array}{lr} +\left(\beta^{z_{h,\, i-1} \cdot 100} - \beta^{z_{h,\, i} \cdot 100} \right) & \qquad {\rm for\; }1 \le i \le N_{levsoi} +\end{array}$$ + +where $z_{h,\, i}$ (m) is the depth from the soil surface to the +interface between layers $i$ and $i+1$ ($z_{h,\, 0}$, the soil surface) +(section `Vertical Discretization`{.interpreted-text role="numref"}), +the factor of 100 converts from m to cm, and $\beta$ is a +plant-dependent root distribution parameter adopted from +`Jackson et al. (1996)`{.interpreted-text role="ref"} +(`Table Plant functional type root distribution parameters`{.interpreted-text +role="numref"}). + +**Table 1: Plant functional type root distribution parameters ** + +| Plant Functional Type | $\beta$ | +|----------------------|---------| +| NET Temperate | 0.976 | +| NET Boreal | 0.943 | +| NDT Boreal | 0.943 | +| BET Tropical | 0.993 | +| BET temperate | 0.966 | +| BDT tropical | 0.993 | +| BDT temperate | 0.966 | +| BDT boreal | 0.943 | +| BES temperate | 0.964 | +| BDS temperate | 0.964 | +| BDS boreal | 0.914 | +| C₃ grass arctic | 0.914 | +| C₃ grass | 0.943 | +| C₄ grass | 0.943 | +| Crop R | 0.943 | +| Crop I | 0.943 | +| Corn R | 0.943 | +| Corn I | 0.943 | +| Temp Cereal R | 0.943 | +| Temp Cereal I | 0.943 | +| Winter Cereal R | 0.943 | +| Winter Cereal I | 0.943 | +| Soybean R | 0.943 | +| Soybean I | 0.943 | +| Miscanthus R | 0.943 | +| Miscanthus I | 0.943 | +| Switchgrass R | 0.943 | +| Switchgrass I | 0.943 | + +::: {#Table Plant functional type root distribution parameters} + ----------------------------------------------------- + Plant Functional Type $\beta$ + ---------------------------------- ------------------ + NET Temperate 0.976 + + NET Boreal 0.943 + + NDT Boreal 0.943 + + BET Tropical 0.993 + + BET temperate 0.966 + + BDT tropical 0.993 + + BDT temperate 0.966 + + BDT boreal 0.943 + + BES temperate 0.964 + + BDS temperate 0.964 + + BDS boreal 0.914 + + C~3~ grass arctic 0.914 + + C~3~ grass 0.943 + + C~4~ grass 0.943 + + Crop R 0.943 + + Crop I 0.943 + + Corn R 0.943 + + Corn I 0.943 + + Temp Cereal R 0.943 + + Temp Cereal I 0.943 + + Winter Cereal R 0.943 + + Winter Cereal I 0.943 + + Soybean R 0.943 + + Soybean I 0.943 + + Miscanthus R 0.943 + + Miscanthus I 0.943 + + Switchgrass R 0.943 + + Switchgrass I 0.943 + ----------------------------------------------------- + + : Plant functional type root distribution parameters +::: + +### Root Spacing {#Root Spacing} + +To determine the conductance along the soil to root pathway (section +`Soil-to-root`{.interpreted-text role="numref"}) an estimate of the +spacing between the roots within a soil layer is required. The distance +between roots $dx_{root,i}$ (m) is calculated by assuming that roots are +distributed uniformly throughout the soil +(`Gardner 1960`{.interpreted-text role="ref"}) + +$$dx_{root,i} = \left(\pi \cdot L_i\right)^{- \frac{1}{2}}$$ + +where $L_{i}$ is the root length density (m m ^-3^) + +$$L_{i} = \frac{B_{root,i}}{\rho_{root} {CA}_{root}} \ ,$$ + +$B_{root,i}$ is the root biomass density (kg m ^-3^) + +$$B_{root,i} = \frac{c\_to\_b \cdot C_{fineroot} \cdot r_{i}}{dz_{i}}$$ + +where $c\_to\_b = 2$ (kg biomass kg carbon ^-1^) and $C_{fineroot}$ is +the amount of fine root carbon (kg m ^-2^). + +$\rho_{root}$ is the root density (kg m ^-3^), and ${CA}_{root}$ is the +fine root cross sectional area (m ^2^) + +$$CA_{root} = \pi r_{root}^{2}$$ + +where $r_{root}$ is the root radius (m). + +## Plant Hydraulic Stress {#Plant Hydraulic Stress} + +The Plant Hydraulic Stress (PHS) routine explicitly models water +transport through the vegetation according to a simple hydraulic +framework following Darcy\'s Law for porous media flow equations +influenced by `Bonan et al. (2014) `{.interpreted-text +role="ref"}, `Chuang et al. (2006) `{.interpreted-text +role="ref"}, `Sperry et al. (1998) `{.interpreted-text +role="ref"}, +`Sperry and Love (2015) `{.interpreted-text +role="ref"}, +`Williams et al (1996) `{.interpreted-text +role="ref"}. + +PHS solves for the vegetation water potential that matches water supply +with transpiration demand. Water supply is modeled according to the +circuit analog in `Figure Plant hydraulic circuit`{.interpreted-text +role="numref"}. Transpiration demand is modeled relative to maximum +transpiration by a transpiration loss function dependent on leaf water +potential. + +::: {#Figure Plant hydraulic circuit} +![Circuit diagram of plant hydraulics scheme](circuit.jpg) +::: + +### Plant Water Supply {#Plant Water Supply} + +The supply equations are used to solve for vegetation water potential +forced by transpiration demand and the set of layer-by-layer soil water +potentials. The water supply is discretized into segments: soil-to-root, +root-to-stem, and stem-to-leaf. There are typically several (1-49) +soil-to-root flows operating in parallel, one per soil layer. There are +two stem-to-leaf flows operating in parallel, corresponding to the +sunlit and shaded \"leaves\". + +In general the water fluxes (e.g. soil-to-root, root-to-stem, etc.) are +modeled according to Darcy\'s Law for porous media flow as: + +$$q = kA\left( \psi_1 - \psi_2 \right)$$ + +$q$ is the flux of water (mmH~2~O/s) spanning the segment between +$\psi_1$ and $\psi_2$ + +$k$ is the hydraulic conductance (s^-1^) + +$A$ is the area basis (m^2^/m^2^) relating the conducting area basis to +ground area $\psi_1 - \psi_2$ is the gradient in water potential +(mmH~2~O) across the segment The segments in +`Figure Plant hydraulic circuit`{.interpreted-text role="numref"} have +variable resistance, as the water potentials become lower, hydraulic +conductance decreases. This is captured by multiplying the maximum +segment conductance by a sigmoidal function capturing the percent loss +of conductivity. The function uses two parameters to fit experimental +vulnerability curves: the water potential at 50% loss of conductivity +($p50$) and a shape fitting parameter ($c_k$). + +$$k=k_{max}\cdot 2^{-\left(\dfrac{\psi_1}{p50}\right)^{c_k}}$$ + +$k_{max}$ is the maximum segment conductance (s^-1^) + +$p50$ is the water potential at 50% loss of conductivity (mmH~2~O) + +$\psi_1$ is the water potential of the lower segment terminus (mmH~2~O) + +#### Stem-to-leaf {#Stem-to-leaf} + +The area basis and conductance parameterization varies by segment. There +are two stem-to-leaf fluxes in parallel, from stem to sunlit leaf and +from stem to shaded leaf ($q_{1a}$ and $q_{1a}$). The water flux from +stem-to-leaf is the product of the segment conductance, the conducting +area basis, and the water potential gradient from stem to leaf. +Stem-to-leaf conductance is defined as the maximum conductance +multiplied by the percent of maximum conductance, as calculated by the +sigmoidal vulnerability curve. The maximum conductance is a PFT +parameter representing the maximum conductance of water from stem to +leaf per unit leaf area. This parameter can be defined separately for +sunlit and shaded segments and should already include the appropriate +length scaling (in other words this is a conductance, not conductivity). +The water potential gradient is the difference between leaf water +potential and stem water potential. There is no gravity term, assuming a +negligible difference in height across the segment. The area basis is +the leaf area index (either sunlit or shaded). + +$$q_{1a}=k_{1a}\cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right)$$ + +$$q_{1b}=k_{1b}\cdot\mbox{LAI}_{shade}\cdot\left(\psi_{stem}-\psi_{shadeleaf} \right)$$ + +$$k_{1a}=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}}$$ + +$$k_{1b}=k_{1b,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}}$$ + +Variables: + +$q_{1a}$ = flux of water (mmH~2~O/s) from stem to sunlit leaf + +$q_{1b}$ = flux of water (mmH~2~O/s) from stem to shaded leaf + +$LAI_{sun}$ = sunlit leaf area index (m2/m2) + +$LAI_{shade}$ = shaded leaf area index (m2/m2) + +$\psi_{stem}$ = stem water potential (mmH~2~O) + +$\psi_{sunleaf}$ = sunlit leaf water potential (mmH~2~O) + +$\psi_{shadeleaf}$ = shaded leaf water potential (mmH~2~O) + +Parameters: + +$k_{1a,max}$ = maximum leaf conductance (s^-1^) + +$k_{1b,max}$ = maximum leaf conductance (s^-1^) + +$p50_{1}$ = water potential at 50% loss of conductance (mmH~2~O) + +$c_{k}$ = vulnerability curve shape-fitting parameter (-) + +#### Root-to-stem {#Root-to-stem} + +There is one root-to-stem flux. This represents a flux from the root +collar to the upper branch reaches. The water flux from root-to-stem is +the product of the segment conductance, the conducting area basis, and +the water potential gradient from root to stem. Root-to-stem conductance +is defined as the maximum conductance multiplied by the percent of +maximum conductance, as calculated by the sigmoidal vulnerability curve +(two parameters). The maximum conductance is defined as the maximum +root-to-stem conductivity per unit stem area (PFT parameter) divided by +the length of the conducting path, which is taken to be the vegetation +height. The area basis is the stem area index. The gradient in water +potential is the difference between the root water potential and the +stem water potential less the difference in gravitational potential. + +$$q_2=k_2 \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right)$$ + +$$k_2=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}}$$ + +Variables: + +$q_2$ = flux of water (mmH~2~O/s) from root to stem + +$SAI$ = stem area index (m2/m2) + +$\Delta\psi_z$ = gravitational potential (mmH~2~O) + +$\psi_{root}$ = root water potential (mmH~2~O) + +$\psi_{stem}$ = stem water potential (mmH~2~O) + +Parameters: + +$k_{2,max}$ = maximum stem conductivity (m/s) + +$p50_2$ = water potential at 50% loss of conductivity (mmH~2~O) + +$z_2$ = vegetation height (m) + +#### Soil-to-root {#Soil-to-root} + +There are several soil-to-root fluxes operating in parallel (one for +each root-containing soil layer). Each represents a flux from the given +soil layer to the root collar. The water flux from soil-to-root is the +product of the segment conductance, the conducting area basis, and the +water potential gradient from soil to root. The area basis is a proxy +for root area index, defined as the summed leaf and stem area index +multiplied by the root-to-shoot ratio (PFT parameter) multiplied by the +layer root fraction. The root fraction comes from an empirical root +profile (section `Vertical Root Distribution`{.interpreted-text +role="numref"}). + +The gradient in water potential is the difference between the soil water +potential and the root water potential less the difference in +gravitational potential. There is only one root water potential to which +all soil layers are connected in parallel. A soil-to-root flux can be +either positive (vegetation water uptake) or negative (water +deposition), depending on the relative values of the root and soil water +potentials. This allows for the occurrence of hydraulic redistribution +where water moves through vegetation tissue from one soil layer to +another. + +Soil-to-root conductance is the result of two resistances in series, +first across the soil-root interface and then through the root tissue. +The root tissue conductance is defined as the maximum conductance +multiplied by the percent of maximum conductance, as calculated by the +sigmoidal vulnerability curve. The maximum conductance is defined as the +maximum root-tissue conductivity (PFT parameter) divided by the length +of the conducting path, which is taken to be the soil layer depth plus +lateral root length. + +The soil-root interface conductance is defined as the soil conductivity +divided by the conducting length from soil to root. The soil +conductivity varies by soil layer and is calculated based on soil +potential and soil properties, via the Brooks-Corey theory. The +conducting length is determined from the characteristic root spacing +(section `Root Spacing`{.interpreted-text role="numref"}). + +$$q_{3,i}=k_{3,i} \cdot \left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right)$$ + +$$k_{3,i}=\dfrac{k_{r,i} \cdot k_{s,i}}{k_{r,i}+k_{s,i}}$$ + +$$k_{r,i}=\dfrac{k_{3,max}}{z_{3,i}} \cdot RAI \cdot 2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}}$$ + +$$RAI=\left(LAI+SAI \right) \cdot r_i \cdot f_{root-leaf}$$ + +$$k_{s,i} = \dfrac{k_{soil,i}}{dx_{root,i}}$$ + +Variables: + +$q_{3,i}$ = flux of water (mmH~2~O/s) from soil layer $i$ to root + +$\Delta\psi_{z,i}$ = change in gravitational potential from soil layer +$i$ to surface (mmH~2~O) + +$LAI$ = total leaf area index (m2/m2) + +$SAI$ = stem area index (m2/m2) + +$\psi_{soil,i}$ = water potential in soil layer $i$ (mmH~2~O) + +$\psi_{root}$ = root water potential (mmH~2~O) + +$z_{3,i}$ = length of root tissue conducting path = soil layer depth + +root lateral length (m) + +$r_i$ = root fraction in soil layer $i$ (-) + +$k_{soil,i}$ = Brooks-Corey soil conductivity in soil layer $i$ (m/s) + +Parameters: + +$f_{root-leaf}$ = root-to-shoot ratio (-) + +$p50_3$ = water potential at 50% loss of root tissue conductance +(mmH~2~O) + +$ck$ = shape-fitting parameter for vulnerability curve (-) + +### Plant Water Demand {#Plant Water Demand} + +Plant water demand depends on stomatal conductance, which is described +in section `Stomatal resistance`{.interpreted-text role="numref"}. Here +we describe the influence of PHS and the coupling of vegetation water +demand and supply. PHS models vegetation water demand as transpiration +attenuated by a transpiration loss function based on leaf water +potential. Sunlit leaf transpiration is modeled as the maximum sunlit +leaf transpiration multiplied by the percent of maximum transpiration as +modeled by the sigmoidal loss function. The same follows for shaded leaf +transpiration. Maximum stomatal conductance is calculated from the +Medlyn model `(Medlyn et al. 2011) `{.interpreted-text +role="ref"} absent water stress and used to calculate the maximum +transpiration (see section +`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`{.interpreted-text +role="numref"}). Water stress is calculated as the ratio of attenuated +stomatal conductance to maximum stomatal conductance. Water stress is +calculated with distinct values for sunlit and shaded leaves. Vegetation +water stress is calculated based on leaf water potential and is used to +attenuate photosynthesis (see section `Photosynthesis`{.interpreted-text +role="numref"}) + +$$E_{sun} = E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}}$$ + +$$E_{shade} = E_{shade,max} \cdot 2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}}$$ + +$$\beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}}$$ + +$$\beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}}$$ + +$E_{sun}$ = sunlit leaf transpiration (mm/s) + +$E_{shade}$ = shaded leaf transpiration (mm/s) + +$E_{sun,max}$ = sunlit leaf transpiration absent water stress (mm/s) + +$E_{shade,max}$ = shaded leaf transpiration absent water stress (mm/s) + +$\psi_{sunleaf}$ = sunlit leaf water potential (mmH~2~O) + +$\psi_{shadeleaf}$ = shaded leaf water potential (mmH~2~O) + +$\beta_{t,sun}$ = sunlit transpiration water stress (-) + +$\beta_{t,shade}$ = shaded transpiration water stress (-) + +$g_{s,sun}$ = stomatal conductance of water corresponding to $E_{sun}$ + +$g_{s,shade}$ = stomatal conductance of water corresponding to +$E_{shade}$ + +$g_{s,sun,max}$ = stomatal conductance of water corresponding to +$E_{sun,max}$ + +$g_{s,shade,max}$ = stomatal conductance of water corresponding to +$E_{shade,max}$ + +### Vegetation Water Potential {#Vegetation Water Potential} + +Both plant water supply and demand are functions of vegetation water +potential. PHS explicitly models root, stem, shaded leaf, and sunlit +leaf water potential at each timestep. PHS iterates to find the +vegetation water potential $\psi$ (vector) that satisfies continuity +between the non-linear vegetation water supply and demand (equations +`11.103`{.interpreted-text role="eq"}, `11.104`{.interpreted-text +role="eq"}, `11.107`{.interpreted-text role="eq"}, +`11.109`{.interpreted-text role="eq"}, `11.201`{.interpreted-text +role="eq"}, `11.202`{.interpreted-text role="eq"}). + +$$\psi=\left[\psi_{sunleaf},\psi_{shadeleaf},\psi_{stem},\psi_{root}\right]$$ + +$$\begin{aligned} +\begin{aligned} +E_{sun}&=q_{1a}\\ +E_{shade}&=q_{1b}\\ +E_{sun}+E_{shade}&=q_{1a}+q_{1b}\\ +&=q_2\\ +&=\sum_{i=1}^{nlevsoi}{q_{3,i}} +\end{aligned} +\end{aligned}$$ + +PHS finds the water potentials that match supply and demand. In the +plant water transport equations `11.302`{.interpreted-text role="eq"}, +the demand terms (left-hand side) are decreasing functions of absolute +leaf water potential. As absolute leaf water potential becomes larger, +water stress increases, causing a decrease in transpiration demand. The +supply terms (right-hand side) are increasing functions of absolute leaf +water potential. As absolute leaf water potential becomes larger, the +gradients in water potential increase, causing an increase in vegetation +water supply. PHS takes a Newton\'s method approach to iteratively solve +for the vegetation water potentials that satisfy continuity +`11.302`{.interpreted-text role="eq"}. + +### Numerical Implementation {#PHS Numerical Implementation} + +The four plant water potential nodes are ( $\psi_{root}$, +$\psi_{xylem}$, $\psi_{shadeleaf}$, $\psi_{sunleaf}$). The fluxes +between each pair of nodes are labeled in Figure 1. $E_{sun}$ and +$E_{sha}$ are the transpiration from sunlit and shaded leaves, +respectively. We use the circuit-analog model to calculate the +vegetation water potential ( $\psi$) for the four plant nodes, forced by +soil matric potential and unstressed transpiration. The unstressed +transpiration is acquired by running the photosynthesis model with +$\beta_t=1$. The unstressed transpiration flux is attenuated based on +the leaf-level vegetation water potential. Using the attenuated +transpiration, we solve for $g_{s,stressed}$ and output +$\beta_t=\dfrac{g_{s,stressed}}{g_{s,unstressed}}$. + +The continuity of water flow through the system yields four equations + +$$\begin{aligned} +\begin{aligned} +E_{sun}&=q_{1a}\\ +E_{shade}&=q_{1b}\\ +q_{1a}+q_{1b}&=q_2\\ +q_2&=\sum_{i=1}^{nlevsoi}{q_{3,i}} +\end{aligned} +\end{aligned}$$ + +We seek the set of vegetation water potential values, + +$$\psi=\left[ \begin {array}{c} +\psi_{sunleaf}\cr\psi_{shadeleaf}\cr\psi_{stem}\cr\psi_{root} +\end {array} \right]$$ + +that satisfies these equations, as forced by the soil moisture and +atmospheric state. Each flux on the schematic can be represented in +terms of the relevant water potentials. Defining the transpiration +fluxes: + +$$\begin{aligned} +\begin{aligned} +E_{sun} &= E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} \\ +E_{shade} &= E_{shade,max} \cdot 2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} +\end{aligned} +\end{aligned}$$ + +Defining the water supply fluxes: + +$$\begin{aligned} +\begin{aligned} +q_{1a}&=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} \cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right) \\ +q_{1b}&=k_{1b,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}}\cdot\mbox{LAI}_{shade}\cdot\left(\psi_{stem}-\psi_{shadeleaf} \right) \\ +q_2&=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}} \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right) \\ +q_{soil}&=\sum_{i=1}^{nlevsoi}{q_{3,i}}=\sum_{i=1}^{nlevsoi}{k_{3,i}\cdot RAI\cdot\left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right)} +\end{aligned} +\end{aligned}$$ + +We\'re looking to find the vector $\psi$ that fits with soil and +atmospheric forcings while satisfying water flow continuity. Due to the +model non-linearity, we use a linearized explicit approach, iterating +with Newton\'s method. The initial guess is the solution for $\psi$ +(vector) from the previous time step. The general framework, from +iteration [m]{.title-ref} to [m+1]{.title-ref} is: + +$$\begin{aligned} +q^{m+1}=q^m+\dfrac{\delta q}{\delta\psi}\Delta\psi \\ +\psi^{m+1}=\psi^{m}+\Delta\psi +\end{aligned}$$ + +So for our first flux balance equation, at iteration [m+1]{.title-ref}, +we have: + +$$E_{sun}^{m+1}=q_{1a}^{m+1}$$ + +Which can be linearized to: + +$$E_{sun}^{m}+\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=q_{1a}^{m}+\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi$$ + +And rearranged to be: + +$$\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=E_{sun}^{m}-q_{1a}^{m}$$ + +And for the other 3 flux balance equations: + +$$\begin{aligned} +\begin{aligned} +\dfrac{\delta q_{1b}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sha}}{\delta\psi}\Delta\psi&=E_{sha}^{m}-q_{1b}^{m} \\ +\dfrac{\delta q_2}{\delta\psi}\Delta\psi-\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi-\dfrac{\delta q_{1b}}{\delta\psi}\Delta\psi&=q_{1a}^{m}+q_{1b}^{m}-q_2^{m} \\ +\dfrac{\delta q_{soil}}{\delta\psi}\Delta\psi-\dfrac{\delta q_2}{\delta\psi}\Delta\psi&=q_2^{m}-q_{soil}^{m} +\end{aligned} +\end{aligned}$$ + +Putting all four together in matrix form: + +$$\left[ \begin {array}{c} +\dfrac{\delta q_{1a}}{\delta\psi}-\dfrac{\delta E_{sun}}{\delta\psi} \cr +\dfrac{\delta q_{1b}}{\delta\psi}-\dfrac{\delta E_{sha}}{\delta\psi} \cr +\dfrac{\delta q_2}{\delta\psi}-\dfrac{\delta q_{1a}}{\delta\psi}-\dfrac{\delta q_{1b}}{\delta\psi} \cr +\dfrac{\delta q_{soil}}{\delta\psi}-\dfrac{\delta q_2}{\delta\psi} +\end {array} \right] +\Delta\psi= +\left[ \begin {array}{c} +E_{sun}^{m}-q_{1a}^{m} \cr +E_{sha}^{m}-q_{1b}^{m} \cr +q_{1a}^{m}+q_{1b}^{m}-q_2^{m} \cr +q_2^{m}-q_{soil}^{m} +\end {array} \right]$$ + +Now to expand the left-hand side, from generic $\psi$ to all four plant +water potential nodes, noting that many derivatives are zero (e.g. +$\dfrac{\delta E_{sun}}{\delta\psi_{sha}}=0$) + +Introducing the notation: $A\Delta\psi=b$ + +$$\Delta\psi=\left[ \begin {array}{c} +\Delta\psi_{sunleaf} \cr +\Delta\psi_{shadeleaf} \cr +\Delta\psi_{stem} \cr +\Delta\psi_{root} +\end {array} \right]$$ + +$$A= +\left[ \begin {array}{cccc} +\dfrac{\delta q_{1a}}{\delta \psi_{sun}}-\dfrac{\delta E_{sun}}{\delta \psi_{sun}}&0&\dfrac{\delta q_{1a}}{\delta \psi_{stem}}&0\cr +0&\dfrac{\delta q_{1b}}{\delta \psi_{sha}}-\dfrac{\delta E_{sha}}{\delta \psi_{sha}}&\dfrac{\delta q_{1b}}{\delta \psi_{stem}}&0\cr +-\dfrac{\delta q_{1a}}{\delta \psi_{sun}}& +-\dfrac{\delta q_{1b}}{\delta \psi_{sha}}& +\dfrac{\delta q_2}{\delta \psi_{stem}}-\dfrac{\delta q_{1a}}{\delta \psi_{stem}}-\dfrac{\delta q_{1b}}{\delta \psi_{stem}}& +\dfrac{\delta q_2}{\delta \psi_{root}}\cr +0&0&-\dfrac{\delta q_2}{\delta \psi_{stem}}&\dfrac{\delta q_{soil}}{\delta \psi_{root}}-\dfrac{\delta q_2}{\delta \psi_{root}} +\end {array} \right]$$ + +$$b= +\left[ \begin {array}{c} +E_{sun}^{m}-q_{b1}^{m} \cr +E_{sha}^{m}-q_{b2}^{m} \cr +q_{b1}^{m}+q_{b2}^{m}-q_{stem}^{m} \cr +q_{stem}^{m}-q_{soil}^{m} +\end {array} \right]$$ + +Now we compute all the entries for $A$ and $b$ based on the soil +moisture and maximum transpiration forcings and can solve to find: + +$$\Delta\psi=A^{-1}b$$ + +$$\psi_{m+1}=\psi_m+\Delta\psi$$ + +We iterate until $b\to 0$, signifying water flux balance through the +system. The result is a final set of water potentials ( $\psi_{root}$, +$\psi_{xylem}$, $\psi_{shadeleaf}$, $\psi_{sunleaf}$) satisfying +non-divergent water flux through the system. The magnitude of the water +flux is driven by soil matric potential and unstressed ( $\beta_t=1$) +transpiration. + +We use the transpiration solution (corresponding to the final solution +for $\psi$) to compute stomatal conductance. The stomatal conductance is +then used to compute $\beta_t$. + +$$\beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}}$$ + +$$\beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}}$$ + +The $\beta_t$ values are used in the Photosynthesis module (see section +`Photosynthesis`{.interpreted-text role="numref"}) to apply water +stress. The solution for $\psi$ is saved as a new variable (vegetation +water potential) and is indicative of plant water status. The +soil-to-root fluxes $\left( q_{3,1},q_{3,2},\mbox{...},q_{3,n}\right)$ +are used as the soil transpiration sink in the Richards\' equation +subsurface flow equations (see section `Soil Water`{.interpreted-text +role="numref"}). + +### Flow Diagram of Leaf Flux Calculations: {#Flow Diagram of Leaf Flux Calculations} + +PHS runs nested in the loop that solves for sensible and latent heat +fluxes and temperature for vegetated surfaces (see section +`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`{.interpreted-text +role="numref"}). The scheme iterates for convergence of leaf temperature +($T_l$), transpiration water stress ($\beta_t$), and intercellular CO2 +concentration ($c_i$). PHS is forced by maximum transpiration (absent +water stress, $\beta_t=1$), whereby we first solve for assimilation, +stomatal conductance, and intercellular CO2 with $\beta_{t,sun}$ and +$\beta_{t,shade}$ both set to 1. This involves iterating to convergence +of $c_i$ (see section `Photosynthesis`{.interpreted-text +role="numref"}). + +Next, using the solutions for $E_{sun,max}$ and $E_{shade,max}$, PHS +solves for $\psi$, $\beta_{t,sun}$, and $\beta_{t,shade}$. The values +for $\beta_{t,sun}$, and $\beta_{t,shade}$ are inputs to the +photosynthesis routine, which now solves for attenuated photosynthesis +and stomatal conductance (reflecting water stress). Again this involves +iterating to convergence of $c_i$. Non-linearities between $\beta_t$ and +transpiration require also iterating to convergence of $\beta_t$. The +outermost level of iteration works towards convergence of leaf +temperature, reflecting leaf surface energy balance. + +::: {#Figure PHS Flow Diagram} +![Flow diagram of leaf flux calculations](phs_iteration_schematic.*) +::: + +>>>>>>> Converted from CLM5 From ffbf84ecabdb765a6a2f454f3cf36370c83e027c Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Thu, 5 Jun 2025 16:32:38 -0700 Subject: [PATCH 02/42] Modifications --- components/elm/docs/tech-guide/hydrology.md | 4 +-- components/elm/docs/tech-guide/phs.md | 39 +-------------------- 2 files changed, 2 insertions(+), 41 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index a8044e365e0c..be160e2046f4 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -1,6 +1,5 @@ +# Hydrology {#rst_Hydrology} -<<<<<<< HEAD -======= The model parameterizes interception, throughfall, canopy drip, snow accumulation and melt, water transfer between snow layers, infiltration, evaporation, surface runoff, sub-surface drainage, redistribution within @@ -958,4 +957,3 @@ and lakes, which reduces the total amount of runoff available to the river routing model (Chapter `rst_MOSART`{.interpreted-text role="numref"}). ->>>>>>> Converted from CLM5 diff --git a/components/elm/docs/tech-guide/phs.md b/components/elm/docs/tech-guide/phs.md index 1f2fc254998f..539ae1722341 100644 --- a/components/elm/docs/tech-guide/phs.md +++ b/components/elm/docs/tech-guide/phs.md @@ -1,7 +1,4 @@ -<<<<<<< HEAD - -======= -# Plant Hydraulics +# Plant Hydraulics {#rst_Plant Hydraulics} ## Roots {#Roots} @@ -24,39 +21,6 @@ plant-dependent root distribution parameter adopted from (`Table Plant functional type root distribution parameters`{.interpreted-text role="numref"}). -**Table 1: Plant functional type root distribution parameters ** - -| Plant Functional Type | $\beta$ | -|----------------------|---------| -| NET Temperate | 0.976 | -| NET Boreal | 0.943 | -| NDT Boreal | 0.943 | -| BET Tropical | 0.993 | -| BET temperate | 0.966 | -| BDT tropical | 0.993 | -| BDT temperate | 0.966 | -| BDT boreal | 0.943 | -| BES temperate | 0.964 | -| BDS temperate | 0.964 | -| BDS boreal | 0.914 | -| C₃ grass arctic | 0.914 | -| C₃ grass | 0.943 | -| C₄ grass | 0.943 | -| Crop R | 0.943 | -| Crop I | 0.943 | -| Corn R | 0.943 | -| Corn I | 0.943 | -| Temp Cereal R | 0.943 | -| Temp Cereal I | 0.943 | -| Winter Cereal R | 0.943 | -| Winter Cereal I | 0.943 | -| Soybean R | 0.943 | -| Soybean I | 0.943 | -| Miscanthus R | 0.943 | -| Miscanthus I | 0.943 | -| Switchgrass R | 0.943 | -| Switchgrass I | 0.943 | - ::: {#Table Plant functional type root distribution parameters} ----------------------------------------------------- Plant Functional Type $\beta$ @@ -676,4 +640,3 @@ temperature, reflecting leaf surface energy balance. ![Flow diagram of leaf flux calculations](phs_iteration_schematic.*) ::: ->>>>>>> Converted from CLM5 From 9c201ea92311d37845a721767fda4250cbc4f213 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Thu, 5 Jun 2025 16:34:40 -0700 Subject: [PATCH 03/42] Modifications --- components/elm/docs/tech-guide/hydrology.md | 2 +- components/elm/docs/tech-guide/phs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index be160e2046f4..60c63c93991d 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -1,4 +1,4 @@ -# Hydrology {#rst_Hydrology} +# Hydrology The model parameterizes interception, throughfall, canopy drip, snow accumulation and melt, water transfer between snow layers, infiltration, diff --git a/components/elm/docs/tech-guide/phs.md b/components/elm/docs/tech-guide/phs.md index 539ae1722341..3c6db2af327e 100644 --- a/components/elm/docs/tech-guide/phs.md +++ b/components/elm/docs/tech-guide/phs.md @@ -1,4 +1,4 @@ -# Plant Hydraulics {#rst_Plant Hydraulics} +# Plant Hydraulics ## Roots {#Roots} From b449406f9051ea2e8b83546c78ea958470985be2 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Fri, 6 Jun 2025 15:20:05 -0700 Subject: [PATCH 04/42] correction --- components/elm/docs/tech-guide/hydrology.md | 176 ++++++++++---------- 1 file changed, 89 insertions(+), 87 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index 60c63c93991d..7fe785da36db 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -8,14 +8,15 @@ changes in canopy water $\Delta W_{can,\,liq}$, canopy snow water $\Delta W_{can,\,sno}$ surface water $\Delta W_{sfc}$, snow water $\Delta W_{sno}$, soil water $\Delta w_{liq,\, i}$, and soil ice $\Delta w_{ice,\, i}$, and water in the unconfined aquifer -$\Delta W_{a}$ (all in kg m^-2^ or mm of H~2~O) +$\Delta W_{a}$ (all in $kg\ m^{-2}$ or $mm\ of\ H_2O$) (`Figure Hydrologic processes`{.interpreted-text role="numref"}). The total water balance of the system is $$\begin{aligned} -\begin{array}{l} {\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} +{\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{aligned}$$ +

(1)

where $q_{rain}$ is the liquid part of precipitation, $q_{sno}$ is the solid part of precipitation, $E_{v}$ is ET from vegetation (Chapter @@ -32,7 +33,7 @@ $q_{rgwl}$ and $q_{snwcp,ice}$ are liquid and solid runoff from glaciers and lakes, and runoff from other surface types due to snow capping (section `Runoff from glaciers and snow-capped surfaces`{.interpreted-text -role="numref"}) (all in kg m^-2^ s^-1^), $N_{levsoi}$ is the number of +role="numref"}) (all in $kg\ m^{-2} s^{-1}$), $N_{levsoi}$ is the number of soil layers (note that hydrology calculations are only done over soil layers 1 to $N_{levsoi}$; ground levels $N_{levsoi} +1$ to $N_{levgrnd}$ are currently hydrologically inactive; @@ -43,14 +44,14 @@ role="ref"} and $\Delta t$ is the time step (s). ![Hydrologic processes represented in CLM.](hydrologic.processes.png) ::: -## Canopy Water {#Canopy Water} +## Canopy Water Liquid precipitation is either intercepted by the canopy, falls directly to the snow/soil surface (throughfall), or drips off the vegetation (canopy drip). Solid precipitation is treated similarly, with the addition of unloading of previously intercepted snow. Interception by vegetation is divided between liquid and solid phases $q_{intr,\,liq}$ -and $q_{intr,\,ice}$ (kg m^-2^ s^-1^) +and $q_{intr,\,ice}$ ($kg\ m^{-2} s^{-1}$) $$q_{intr,\,liq} = f_{pi,\,liq} \ q_{rain}$$ @@ -61,7 +62,7 @@ precipitation of rain and snow, respectively $$f_{pi,\,liq} = \alpha_{liq} \ tanh \left(L+S\right)$$ -$$f_{pi,\,ice} =\alpha_{sno} \ \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} \ ,$$ +$$f_{pi,\,ice} =\alpha_{sno} \ \left\(1-\exp \left[-0.5\left(L+S\right)\right]\right\) $$ and $L$ and $S$ are the exposed leaf and stem area index, respectively (section `Phenology and vegetation burial by snow`{.interpreted-text @@ -69,7 +70,7 @@ role="numref"}), and the $\alpha$\'s scale the fractional area of a leaf that collects water (`Lawrence et al. 2007 `{.interpreted-text role="ref"}). Default values of $\alpha_{liq}$ and $\alpha_{sno}$ are -set to 1. Throughfall (kg m^-2^ s^-1^) is also divided into liquid and +set to 1. Throughfall ($kg\ m^{-2} s^{-1}$) is also divided into liquid and solid phases, reaching the ground (soil or snow surface) as $$q_{thru,\, liq} = q_{rain} \left(1 - f_{pi,\,liq}\right)$$ @@ -93,17 +94,17 @@ $$W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr,\, ice} \Delta t\ge 0$$ are the the canopy liquid water and snow water equivalent after accounting for interception, $W_{can,\,liq}^{n}$ and $W_{can,\,sno}^{n}$ are the canopy liquid and snow water from the previous time step, and -$W_{can,\,liq}^{max }$ and $W_{can,\,snow}^{max }$ (kg m^-2^ or mm of -H~2~O) are the maximum amounts of liquid water and snow the canopy can +$W_{can,\,liq}^{max }$ and $W_{can,\,snow}^{max }$ ($kg\ m^{-2}$ or $mm\ of\ +H_2O) are the maximum amounts of liquid water and snow the canopy can hold. They are defined by $$W_{can,\,liq}^{max } =p_{liq}\left(L+S\right)$$ $$W_{can,\,sno}^{max } =p_{sno}\left(L+S\right).$$ -The maximum storage of liquid water is $p_{liq}=0.1$ kg m^-2^ +The maximum storage of liquid water is $p_{liq}=0.1$ $kg\ m^{-2}$ (`Dickinson et al. 1993 `{.interpreted-text -role="ref"}), and that of snow is $p_{sno}=6$ kg m^-2^, consistent with +role="ref"}), and that of snow is $p_{sno}=6$ $kg\ m^{-2}$, consistent with reported field measurements (`Pomeroy et al. 1998 `{.interpreted-text role="ref"}). @@ -137,18 +138,18 @@ role="numref"}) $$\begin{aligned} E_{v}^{liq} = -\left\{\begin{array}{lr} +\left\(\begin{array}{lr} E_{v}^{w} & T_v > T_{f} \\ 0 & T_v \le T_f -\end{array}\right\} +\end{array}\right\) \end{aligned}$$ $$\begin{aligned} E_{v}^{ice} = -\left\{\begin{array}{lr} +\left\(\begin{array}{lr} 0 & T_v > T_f \\ E_{v}^{w} & T_v \le T_f -\end{array}\right\}. +\end{array}\right\). \end{aligned}$$ The total rate of liquid and solid precipitation reaching the ground is @@ -175,44 +176,45 @@ role="numref"}) calculations, is (`Dickinson et al.1993 `{.interpreted-text role="ref"}) -$$\begin{aligned} -f_{wet} = -\left\{\begin{array}{lr} -\left[\frac{W_{can} }{p_{liq}\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right.} 3} } \le 1 & \qquad L+S > 0 \\ -0 &\qquad L+S = 0 -\end{array}\right\} -\end{aligned}$$ +$$ +f_{\text{wet}} = +\begin{cases} +\left[\dfrac{W_{\text{can}}}{\rho_{\text{liq}}(L + S)} \right]^{2/3}, & \text{if } L + S > 0 \text{ and } \left[\dfrac{W_{\text{can}}}{\rho_{\text{liq}}(L + S)} \right]^{2/3} \leq 1 \\ +1, & \text{if } L + S > 0 \text{ and } \left[\dfrac{W_{\text{can}}}{\rho_{\text{liq}}(L + S)} \right]^{2/3} > 1 \\ +0, & \text{if } L + S = 0 +\end{cases} +$$ while the fraction of the canopy that is dry and transpiring is -$$\begin{aligned} -f_{dry} = -\left\{\begin{array}{lr} -\frac{\left(1-f_{wet} \right)L}{L+S} & \qquad L+S > 0 \\ -0 &\qquad L+S = 0 -\end{array}\right\}. -\end{aligned}$$ +$$ +f_{\text{dry}} = +\begin{cases} +\dfrac{(1 - f_{\text{wet}}) L}{L + S}, & \text{if } L + S > 0 \\ +0, & \text{if } L + S = 0 +\end{cases} +$$ Similarly, the snow-covered fraction of the canopy is used for surface alebdo when intercepted snow is present (Chapter `rst_Surface Albedos`{.interpreted-text role="numref"}) -$$\begin{aligned} -f_{can,\, sno} = -\left\{\begin{array}{lr} -\left[\frac{W_{can,\, sno} }{p_{sno}\left(L+S\right)} \right]^{{3\mathord{\left/ {\vphantom {3 20}} \right.} 20} } \le 1 & \qquad L+S > 0 \\ -0 &\qquad L+S = 0 -\end{array}\right\}. -\end{aligned}$$ +$$ +f_{\text{can,\,sno}} = +\begin{cases} +\min\left( \left[\dfrac{W_{\text{can,\,sno}}}{\rho_{\text{sno}}(L + S)} \right]^{3/20},\ 1 \right), & \text{if } L + S > 0 \\ +0, & \text{if } L + S = 0 +\end{cases} +$$ -## Surface Runoff, Surface Water Storage, and Infiltration {#Surface Runoff, Surface Water Storage, and Infiltration} +## Surface Runoff, Surface Water Storage, and Infiltration The moisture input at the grid cell surface,$q_{liq,\, 0}$, is the sum -of liquid precipitation reaching the ground and melt water from snow (kg -m^-2^ s^-1^). The moisture flux is then partitioned between surface +of liquid precipitation reaching the ground and melt water from snow ($kg\ +m^{-2} s^{-1}$). The moisture flux is then partitioned between surface runoff, surface water storage, and infiltration into the soil. -### Surface Runoff {#Surface Runoff} +### Surface Runoff The simple TOPMODEL-based (`Beven and Kirkby 1979 `{.interpreted-text @@ -231,7 +233,7 @@ The fractional saturated area is a function of soil moisture $$f_{sat} =f_{\max } \ \exp \left(-0.5f_{over} z_{\nabla } \right)$$ where $f_{\max }$ is the potential or maximum value of $f_{sat}$, -$f_{over}$ is a decay factor (m^-1^), and $z_{\nabla}$ is the water +$f_{over}$ is a decay factor ($m^{-1}$), and $z_{\nabla}$ is the water table depth (m) (section `Lateral Sub-surface Runoff`{.interpreted-text role="numref"}). The maximum saturated fraction, $f_{\max }$, is defined as the value of the discrete cumulative distribution function (CDF) of @@ -256,14 +258,14 @@ $f_{\max }$ is used to fill the gaps. See `Li et al. (2013b) `{.interpreted-text role="ref"} for additional details. The decay factor $f_{over}$ for global simulations was determined through sensitivity analysis and comparison with observed -runoff to be 0.5 m^-1^. +runoff to be 0.5 $m^{-1}$. -### Surface Water Storage {#Surface Water Storage} +### Surface Water Storage A surface water store has been added to the model to represent wetlands and small, sub-grid scale water bodies. As a result, the wetland land unit has been removed as of CLM4.5. The state variables for surface -water are the mass of water $W_{sfc}$ (kg m^-2^) and temperature +water are the mass of water $W_{sfc}$ ($kg\ m^{-2}$) and temperature $T_{h2osfc}$ (Chapter `rst_Soil and Snow Temperatures`{.interpreted-text role="numref"}). Surface water storage and outflow are functions of fine spatial scale elevation variations called microtopography. The @@ -319,7 +321,7 @@ storage coefficent $k_{h2osfc} = \sin \left(\beta \right)$ is a function of grid cell mean topographic slope where $\beta$ is the slope in radians. -### Infiltration {#Infiltration} +### Infiltration The surface moisture flux remaining after surface runoff has been removed, @@ -328,7 +330,7 @@ $$q_{in,surface} = (1-f_{sat}) \ q_{liq,\, 0}$$ is divided into inputs to surface water ($q_{in,\, h2osfc}$ ) and the soil $q_{in,soil}$. If $q_{in,soil}$ exceeds the maximum soil -infiltration capacity (kg m^-2^ s^-1^), +infiltration capacity ($kg\ m^{-2} s^{-1}$), $$q_{infl,\, \max } =(1-f_{sat}) \ \Theta_{ice} k_{sat}$$ @@ -363,7 +365,7 @@ $$q_{infl} = q_{in,soil} + q_{drain,h2osfc}$$ Infiltration $q_{infl}$ and explicit surface runoff $q_{over}$ are not allowed for glaciers. -## Soil Water {#Soil Water} +## Soil Water Soil water is predicted from a multi-layer model, in which the vertical soil moisture transport is governed by infiltration, surface and @@ -378,9 +380,9 @@ $$\frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} - e$$ where $\theta$ is the volumetric soil water content (mm^3^ of water / mm^-3^ of soil), $t$ is time (s), $z$ is height above some datum in the -soil column (mm) (positive upwards), $q$ is soil water flux (kg m^-2^ -s^-1^ or mm s^-1^) (positive upwards), and $e$ is a soil moisture sink -term (mm of water mm^-1^ of soil s^-1^) (ET loss). This equation is +soil column (mm) (positive upwards), $q$ is soil water flux ($kg\ m^{-2} +s^{-1}$ or $mm\ s^{-1}$) (positive upwards), and $e$ is a soil moisture sink +term ($mm\ of\ water mm^{-1}\ of\ soil\ s^{-1}$) (ET loss). This equation is solved numerically by dividing the soil column into multiple layers in the vertical and integrating downward over each layer with an upper boundary condition of the infiltration flux into the top soil layer @@ -392,19 +394,19 @@ The soil water flux $q$ in equation `7.79`{.interpreted-text role="eq"} can be described by Darcy\'s law `(Dingman 2002) `{.interpreted-text role="ref"} -$$q = -k \frac{\partial \psi _{h} }{\partial z}$$ +$$q = -k \frac{\partial \psi_{h} }{\partial z}$$ -where $k$ is the hydraulic conductivity (mm s^-1^), and $\psi _{h}$ is +where $k$ is the hydraulic conductivity ($mm\ s^{-1}$), and $\psi_{h}$ is the hydraulic potential (mm). The hydraulic potential is -$$\psi _{h} =\psi _{m} +\psi _{z}$$ +$$\psi_{h} =\psi_{m} +\psi_{z}$$ -where $\psi _{m}$ is the soil matric potential (mm) (which is related to +where $\psi_{m}$ is the soil matric potential (mm) (which is related to the adsorptive and capillary forces within the soil matrix), and -$\psi _{z}$ is the gravitational potential (mm) (the vertical distance +$\psi_{z}$ is the gravitational potential (mm) (the vertical distance from an arbitrary reference elevation to a point in the soil). If the -reference elevation is the soil surface, then $\psi _{z} =z$. Letting -$\psi =\psi _{m}$, Darcy\'s law becomes +reference elevation is the soil surface, then $\psi_{z} =z$. Letting +$\psi =\psi_{m}$, Darcy\'s law becomes $$q = -k \left[\frac{\partial \left(\psi +z\right)}{\partial z} \right].$$ @@ -427,10 +429,10 @@ role="numref"}), changes in soil water content are predicted from `7.79`{.interpreted-text role="eq"} using finite-difference approximations for `7.84`{.interpreted-text role="eq"}. -### Hydraulic Properties {#Hydraulic Properties} +### Hydraulic Properties -The hydraulic conductivity $k_{i}$ (mm s^-1^) and the soil matric -potential $\psi _{i}$ (mm) for layer $i$ vary with volumetric soil water +The hydraulic conductivity $k_{i}$ ($mm\ s^{-1}$) and the soil matric +potential $\psi_{i}$ (mm) for layer $i$ vary with volumetric soil water $\theta _{i}$ and soil texture. As with the soil thermal properties (section `Soil And Snow Thermal Properties`{.interpreted-text role="numref"}) the hydraulic properties of the soil are assumed to be a @@ -450,13 +452,13 @@ $k_{sat} \left[z_{h,\, i} \right]$, the liquid volumetric soil moisture of the two layers $\theta _{i}$ and $\theta_{i+1}$ and an ice impedance factor $\Theta_{ice}$ -$$\begin{aligned} +$$ k\left[z_{h,\, i} \right] = -\left\{\begin{array}{lr} -\Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)}{0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ -\Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} -\end{array}\right\}. -\end{aligned}$$ +\begin{cases} +\Theta_{\text{ice}} \, k_{\text{sat}}\left[z_{h,\, i} \right] \left[\dfrac{0.5\left(\theta_{i} + \theta_{i+1} \right)}{0.5\left(\theta_{\text{sat},\, i} + \theta_{\text{sat},\, i+1} \right)} \right]^{2B_{i} + 3}, & \text{for } 1 \le i \le N_{\text{levsoi}} - 1 \\ +\Theta_{\text{ice}} \, k_{\text{sat}}\left[z_{h,\, i} \right] \left(\dfrac{\theta_{i}}{\theta_{\text{sat},\, i}} \right)^{2B_{i} + 3}, & \text{for } i = N_{\text{levsoi}} +\end{cases} +$$ The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the @@ -494,19 +496,19 @@ The soil matric potential (mm) is defined at the node depth $z_{i}$ of each layer $i$ (`Figure Water flux schematic`{.interpreted-text role="numref"}) -$$\psi _{i} =\psi _{sat,\, i} \left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta_{i} }{\theta_{sat,\, i} } \le 1$$ +$$\psi_{i} =\psi_{sat,\, i} \left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta_{i} }{\theta_{sat,\, i}} \le 1$$ where the saturated soil matric potential (mm) is -$$\psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om}$$ +$$\psi_{sat,i} =(1-f_{om,i} )\psi_{sat,\min ,i} +f_{om,i} \psi_{sat,om}$$ -where $\psi _{sat,om}$ is the saturated organic matter matric potential -and the saturated mineral soil matric potential $\psi _{sat,\min,i}$ is +where $\psi_{sat,om}$ is the saturated organic matter matric potential +and the saturated mineral soil matric potential $\psi_{sat,\min,i}$ is -$$\psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } .$$ +$$\psi_{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i}} .$$ The saturated hydraulic conductivity, $k_{sat} \left[z_{h,\, i} \right]$ -(mm s^-1^), for organic soils ($k_{sat,\, om}$ ) may be two to three +($mm\ s^{-1}$), for organic soils ($k_{sat,\, om}$ ) may be two to three orders of magnitude larger than that of mineral soils ($k_{sat,\, \min }$ ). Bulk soil layer values of $k_{sat}$ calculated as weighted averages based on $f_{om}$ may therefore be determined @@ -566,7 +568,7 @@ $$k_{sat,om} = max(0.28 - 0.2799\times z_{i} / zsapric, k_{sat,\, \min } \left[z where $zsapric =0.5$ m is the depth that organic matter takes on the characteristics of sapric peat. -### Numerical Solution {#Numerical Solution Hydrology} +### Numerical Solution With reference to `Figure Water flux schematic`{.interpreted-text role="numref"}, the equation for conservation of mass (equation @@ -583,7 +585,7 @@ $$\Delta z_{i} \frac{\partial \theta_{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} - where $q_{i}$ is the flux of water across interface $z_{h,\, i}$, $q_{i-1}$ is the flux of water across interface $z_{h,\, i-1}$, and $e_{i}$ is a layer-averaged soil moisture sink term (ET loss) defined as -positive for flow out of the layer (mm s^-1^). Taking the finite +positive for flow out of the layer ($mm\ s^{-1}$). Taking the finite difference with time and evaluating the fluxes implicitly at time $n+1$ yields @@ -683,26 +685,26 @@ equations `7.111`{.interpreted-text role="eq"} - `7.114`{.interpreted-text role="eq"} can be obtained from equation `7.82`{.interpreted-text role="eq"} as -$$q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right]$$ +$$q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right]$$ -$$q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right]$$ +$$q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right]$$ -$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ +$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ -$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ +$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ -$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]$$ +$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]$$ -$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right].$$ +$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right].$$ The derivatives of the soil matric potential at the node depth are derived from `7.94`{.interpreted-text role="eq"} -$$\frac{\partial \psi _{i-1} }{\partial \theta_{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta_{\, \, i-1} }$$ +$$\frac{\partial \psi_{i-1} }{\partial \theta_{liq,\, \, i-1} } =-B_{i-1} \frac{\psi_{i-1} }{\theta_{\, \, i-1} }$$ -$$\frac{\partial \psi _{i} }{\partial \theta_{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta_{i} }$$ +$$\frac{\partial \psi_{i} }{\partial \theta_{\, liq,\, i} } =-B_{i} \frac{\psi_{i} }{\theta_{i} }$$ -$$\frac{\partial \psi _{i+1} }{\partial \theta_{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta_{\, i+1} }$$ +$$\frac{\partial \psi_{i+1} }{\partial \theta_{liq,\, i+1} } =-B_{i+1} \frac{\psi_{i+1} }{\theta_{\, i+1} }$$ with the constraint $0.01\, \theta_{sat,\, i} \le \theta_{\, i} \le \theta_{sat,\, i}$. @@ -826,7 +828,7 @@ The volumetric water content is $$\theta_{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } .$$ -## Frozen Soils and Perched Water Table {#Frozen Soils and Perched Water Table} +## Frozen Soils and Perched Water Table When soils freeze, the power-law form of the ice impedance factor (section `Hydraulic Properties`{.interpreted-text role="numref"}) can @@ -854,7 +856,7 @@ is set to 0.9. Drainage from the perched saturated zone $q_{drai,perch}$ is removed from layers $N_{perch}$ through $N_{frost}$, which are the layers containing $z_{\nabla,perch}$ and, $z_{frost}$ respectively. -## Lateral Sub-surface Runoff {#Lateral Sub-surface Runoff} +## Lateral Sub-surface Runoff Lateral sub-surface runoff occurs when saturated soil moisture conditions exist within the soil column. Sub-surface runoff is @@ -921,10 +923,10 @@ $$w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} -q_{subl} \Delta t.$$ Sublimation of ice is limited to the amount of ice available. -## Runoff from glaciers and snow-capped surfaces {#Runoff from glaciers and snow-capped surfaces} +## Runoff from glaciers and snow-capped surfaces All surfaces are constrained to have a snow water equivalent -$W_{sno} \le W_{cap} = 10,000$ kg m^-2^. For snow-capped columns, any +$W_{sno} \le W_{cap} = 10,000$ $kg\ m^{-2}$. For snow-capped columns, any addition of mass at the top (precipitation, dew/riping) is balanced by an equally large mass flux at the bottom of the snow column. This so-called capping flux is separated into solid $q_{snwcp,ice}$ and From ec41a40ec4b4a620b636c2ab8909cd448f5a6043 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Fri, 6 Jun 2025 16:07:44 -0700 Subject: [PATCH 05/42] correction --- components/elm/docs/tech-guide/hydrology.md | 79 +++++++++++---------- 1 file changed, 43 insertions(+), 36 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index 7fe785da36db..dcb49c3d343d 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -13,9 +13,13 @@ $\Delta W_{a}$ (all in $kg\ m^{-2}$ or $mm\ of\ H_2O$) The total water balance of the system is -$$\begin{aligned} -{\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} -\end{aligned}$$ +$$ +\begin{aligned} +\Delta W_{can,\,liq} + \Delta W_{can,\,sno} + \Delta W_{sfc} + \Delta W_{sno} + +\sum_{i=1}^{N_{levsoi}} (\Delta w_{liq,\, i} + \Delta w_{ice,\, i}) + \Delta W_{a} \\ += \left( q_{rain} + q_{sno} - E_{v} - E_{g} - q_{over} - q_{h2osfc} - q_{drai} - q_{rgwl} - q_{snwcp,\, ice} \right) \Delta t +\end{aligned} +$$

(1)

where $q_{rain}$ is the liquid part of precipitation, $q_{sno}$ is the @@ -271,24 +275,24 @@ role="numref"}). Surface water storage and outflow are functions of fine spatial scale elevation variations called microtopography. The microtopography is assumed to be distributed normally around the grid cell mean elevation. Given the standard deviation of the -microtopographic distribution, $\sigma _{micro}$ (m), the fractional +microtopographic distribution, $\sigma_{micro}$ (m), the fractional area of the grid cell that is inundated can be calculated. Surface water storage, $Wsfc$, is related to the height (relative to the grid cell mean elevation) of the surface water, $d$, by -$$W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } }$$ +$$W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma_{micro} \sqrt{2} } \right)\right)+\frac{\sigma_{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma_{micro} ^{2} } }$$ where $erf$ is the error function. For a given value of $W_{sfc}$, `7.66`{.interpreted-text role="eq"} can be solved for $d$ using the Newton-Raphson method. Once $d$ is known, one can determine the fraction of the area that is inundated as -$$f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)$$ +$$f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma_{micro} \sqrt{2} } \right)\right)$$ No global datasets exist for microtopography, so the default parameterization is a simple function of slope -$$\sigma _{micro} =\left(\beta +\beta _{0} \right)^{\eta }$$ +$$\sigma_{micro} =\left(\beta +\beta_{0} \right)^{\eta }$$ where $\beta$ is the topographic slope, $\beta_{0} =\left(\sigma_{\max } \right)^{\frac{1}{\eta } }$ determines @@ -433,7 +437,7 @@ approximations for `7.84`{.interpreted-text role="eq"}. The hydraulic conductivity $k_{i}$ ($mm\ s^{-1}$) and the soil matric potential $\psi_{i}$ (mm) for layer $i$ vary with volumetric soil water -$\theta _{i}$ and soil texture. As with the soil thermal properties +$\theta_{i}$ and soil texture. As with the soil thermal properties (section `Soil And Snow Thermal Properties`{.interpreted-text role="numref"}) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined @@ -449,7 +453,7 @@ two adjacent layers $z_{h,\, i}$ (`Figure Water flux schematic`{.interpreted-text role="numref"}) and is a function of the saturated hydraulic conductivity $k_{sat} \left[z_{h,\, i} \right]$, the liquid volumetric soil moisture -of the two layers $\theta _{i}$ and $\theta_{i+1}$ and an ice impedance +of the two layers $\theta_{i}$ and $\theta_{i+1}$ and an ice impedance factor $\Theta_{ice}$ $$ @@ -482,7 +486,7 @@ where $f_{om,i}$ is the soil organic matter fraction, $\theta_{sat,om}$ is the porosity of organic matter, and the porosity of the mineral soil $\theta_{sat,\min,i}$ is -$$\theta_{sat,\min ,i} = 0.489 - 0.00126(\% sand)_{i} .$$ +$$\theta_{sat, min, i} = 0.489 - 0.00126(\text{% sand})_{i}$$ The exponent $B_{i}$ is @@ -490,7 +494,7 @@ $$B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om}$$ where $B_{om}$ is for organic matter and -$$B_{\min ,i} =2.91+0.159(\% clay)_{i} .$$ +$$B_{\min ,i} =2.91+0.159(\text{% clay})_{i} $$ The soil matric potential (mm) is defined at the node depth $z_{i}$ of each layer $i$ (`Figure Water flux schematic`{.interpreted-text @@ -505,7 +509,7 @@ $$\psi_{sat,i} =(1-f_{om,i} )\psi_{sat,\min ,i} +f_{om,i} \psi_{sat,om}$$ where $\psi_{sat,om}$ is the saturated organic matter matric potential and the saturated mineral soil matric potential $\psi_{sat,\min,i}$ is -$$\psi_{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i}} .$$ +$$\psi_{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\text{% sand})_{i}} $$ The saturated hydraulic conductivity, $k_{sat} \left[z_{h,\, i} \right]$ ($mm\ s^{-1}$), for organic soils ($k_{sat,\, om}$ ) may be two to three @@ -528,12 +532,13 @@ span the soil space. Flow through these pathways interacts only with organic material, and thus can be described by $k_{sat,\, om}$. This fraction of the grid cell is given by -$$\begin{aligned} -\begin{array}{lr} -f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta_{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ -f_{perc} = 0 & \qquad f_{om} `{.interpreted-text role="ref"}) as -$$k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\% sand\right)_{i} } .$$ +$$k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\text{% sand}\right)_{i} } .$$ The bulk soil layer saturated hydraulic conductivity is then computed as @@ -575,7 +580,7 @@ role="numref"}, the equation for conservation of mass (equation `7.79`{.interpreted-text role="eq"}) can be integrated over each layer as -$$\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} } e\, dz .$$ +$$\int_{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int_{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int_{-z_{h,\, i} }^{-z_{h,\, i-1} } e\, dz .$$ Note that the integration limits are negative since $z$ is defined as positive upward from the soil surface. This equation can be written as @@ -621,7 +626,9 @@ Note that because more than one plant functional type (PFT) may share a soil column, the transpiration $E_{v}^{t}$ is a weighted sum of transpiration from all PFTs whose weighting depends on PFT area as -$$E_{v}^{t} =\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j}$$ +$$ +E_{v}^{t} = \sum_{j=1}^{n_{\text{pft}}} \left( E_{v,j}^{t} \cdot \text{wt}_j \right) +$$ where $npft$ is the number of PFTs sharing a soil column, $\left(E_{v}^{t} \right)_{j}$ is the transpiration from the $j^{th}$ PFT @@ -631,15 +638,15 @@ $r_{e,\, i}$ is also a column-level quantity that is a weighted sum over all PFTs. The weighting depends on the per unit area transpiration of each PFT and its relative area as -$$r_{e,\, i} =\frac{\sum _{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }$$ +$$r_{e,\, i} =\frac{\sum_{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum_{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }$$ where $\left(r_{e,\, i} \right)_{j}$ is the effective root fraction for the $j^{th}$ PFT $$\begin{aligned} \begin{array}{lr} -\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } & \qquad \left(\beta _{t} \right)_{j} >0 \\ -\left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta _{t} \right)_{j} =0 +\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta_{t} \right)_{j} } & \qquad \left(\beta_{t} \right)_{j} >0 \\ +\left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta_{t} \right)_{j} =0 \end{array} \end{aligned}$$ @@ -689,13 +696,13 @@ $$q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi_{i-1} -\psi_{i $$q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right]$$ -$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ +$$\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i-1} }{\partial \theta_{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i-1} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ -$$\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ +$$\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi_{i} }{\partial \theta_{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i} } \left[\frac{\left(\psi_{i-1} -\psi_{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right]$$ -$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]$$ +$$\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i} }{\partial \theta_{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]$$ -$$\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right].$$ +$$\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi_{i+1} }{\partial \theta_{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i+1} } \left[\frac{\left(\psi_{i} -\psi_{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right].$$ The derivatives of the soil matric potential at the node depth are derived from `7.94`{.interpreted-text role="eq"} @@ -713,8 +720,8 @@ The derivatives of the hydraulic conductivity at the layer interface are derived from `7.85`{.interpreted-text role="eq"} $$\begin{array}{l} -{\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } -= \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } +{\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i-1} } += \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i} } = \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}$$ where $\overline{\Theta}_{ice} = \Theta(\overline{\theta}_{ice})$ @@ -727,8 +734,8 @@ $\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i-1} +\theta_{sat,\, i} \righ and $$\begin{array}{l} -{\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } -= \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } +{\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i} } += \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i+1} } = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}.$$ where @@ -826,7 +833,7 @@ $$w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta_{liq,\, i} \Delta z_{i} \q The volumetric water content is -$$\theta_{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } .$$ +$$\theta_{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho_{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho_{ice} } .$$ ## Frozen Soils and Perched Water Table @@ -843,7 +850,7 @@ $$q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right)$$ where $k_{drai,\, perch}$ depends on topographic slope and soil hydraulic conductivity, -$$k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta_{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right)$$ +$$k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum_{i=N_{perch} }^{i=N_{frost} }\Theta_{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum_{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right)$$ where $\Theta_{ice}$ is an ice impedance factor, $\beta$ is the mean grid cell topographic slope in radians, $z_{frost}$ is the depth to the @@ -883,7 +890,7 @@ the water table location, is derived by taking the difference between two equilibrium soil moisture profiles whose water tables differ by an infinitesimal amount -$$S_{y} =\theta_{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right)$$ +$$S_{y} =\theta_{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi_{sat} } \right)^{\frac{-1}{B} } \right)$$ where B is the Clapp-Hornberger exponent. Because $S_{y}$ is a function of the soil properties, it results in water table dynamics that are @@ -949,7 +956,7 @@ $$q_{rgwl} =q_{grnd,ice} +q_{grnd,liq} -E_{g} -E_{v} -\frac{\left(W_{b}^{n+1} -W where $W_{b}^{n}$ and $W_{b}^{n+1}$ are the water balances at the beginning and ending of the time step defined as -$$W_{b} =W_{can} +W_{sno} +\sum _{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) .$$ +$$W_{b} =W_{can} +W_{sno} +\sum_{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) .$$ Currently, glaciers are non-vegetated and $E_{v} =W_{can} =0$. The contribution of lake runoff to $q_{rgwl}$ is described in section From 6d2c9f80b1c946a635ac34237e4c88f6ec8f28ee Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Mon, 9 Jun 2025 11:51:27 -0700 Subject: [PATCH 06/42] Remove spaces. --- components/elm/docs/tech-guide/hydrology.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index dcb49c3d343d..9253d3ab2ebd 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -15,7 +15,7 @@ The total water balance of the system is $$ \begin{aligned} -\Delta W_{can,\,liq} + \Delta W_{can,\,sno} + \Delta W_{sfc} + \Delta W_{sno} + +\Delta W_{can,\,liq} + \Delta W_{can,\,sno} + \Delta W_{sfc} + \Delta W_{sno} + \sum_{i=1}^{N_{levsoi}} (\Delta w_{liq,\, i} + \Delta w_{ice,\, i}) + \Delta W_{a} \\ = \left( q_{rain} + q_{sno} - E_{v} - E_{g} - q_{over} - q_{h2osfc} - q_{drai} - q_{rgwl} - q_{snwcp,\, ice} \right) \Delta t \end{aligned} @@ -965,4 +965,3 @@ role="numref"}. The runoff term $q_{rgwl}$ may be negative for glaciers and lakes, which reduces the total amount of runoff available to the river routing model (Chapter `rst_MOSART`{.interpreted-text role="numref"}). - From e94dbacc4dbc89f66a91e9af1c5932335023e771 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Mon, 9 Jun 2025 12:07:02 -0700 Subject: [PATCH 07/42] correction --- components/elm/docs/tech-guide/hydrology.md | 1 - components/elm/docs/tech-guide/phs.md | 1 - 2 files changed, 2 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index 9253d3ab2ebd..3fd2e3c95516 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -20,7 +20,6 @@ $$ = \left( q_{rain} + q_{sno} - E_{v} - E_{g} - q_{over} - q_{h2osfc} - q_{drai} - q_{rgwl} - q_{snwcp,\, ice} \right) \Delta t \end{aligned} $$ -

(1)

where $q_{rain}$ is the liquid part of precipitation, $q_{sno}$ is the solid part of precipitation, $E_{v}$ is ET from vegetation (Chapter diff --git a/components/elm/docs/tech-guide/phs.md b/components/elm/docs/tech-guide/phs.md index 3c6db2af327e..60d3ca50b912 100644 --- a/components/elm/docs/tech-guide/phs.md +++ b/components/elm/docs/tech-guide/phs.md @@ -639,4 +639,3 @@ temperature, reflecting leaf surface energy balance. ::: {#Figure PHS Flow Diagram} ![Flow diagram of leaf flux calculations](phs_iteration_schematic.*) ::: - From 4aaf5850301a39c21c1e00190ba9ef2f4da02d17 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Mon, 16 Jun 2025 13:54:25 -0700 Subject: [PATCH 08/42] correction --- components/elm/docs/tech-guide/hydrology.md | 33 +++++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index 3fd2e3c95516..5ee275504a71 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -471,7 +471,7 @@ used a power law form $$\Theta_{ice} = 10^{-\Omega F_{ice} }$$ -where $\Omega = 6$and $F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }$ is +where $\Omega = 6$ and $F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }$ is the ice-filled fraction of the pore space. Because the hydraulic properties of mineral and organic soil may differ @@ -630,24 +630,26 @@ E_{v}^{t} = \sum_{j=1}^{n_{\text{pft}}} \left( E_{v,j}^{t} \cdot \text{wt}_j \ri $$ where $npft$ is the number of PFTs sharing a soil column, -$\left(E_{v}^{t} \right)_{j}$ is the transpiration from the $j^{th}$ PFT -on the column, and $\left(wt\right)_{j}$ is the relative area of the +$\left(E_{v}^{t} \right)\_{j}$ is the transpiration from the $j^{th}$ PFT +on the column, and $\left(wt\right)\_{j}$ is the relative area of the $j^{th}$ PFT with respect to the column. The effective root fraction $r_{e,\, i}$ is also a column-level quantity that is a weighted sum over all PFTs. The weighting depends on the per unit area transpiration of each PFT and its relative area as -$$r_{e,\, i} =\frac{\sum_{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum_{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }$$ +$$r_{e,i} = \frac{\sum_{j=1}^{npft} (r_{e,i})\_j (E_v^t)\_j (wt)\_j}{\sum_{j=1}^{npft} (E_v^t)\_j (wt)\_j}$$ -where $\left(r_{e,\, i} \right)_{j}$ is the effective root fraction for +where $\left(r_{e,i} \right)_{j}$ is the effective root fraction for the $j^{th}$ PFT -$$\begin{aligned} +$$ +\begin{aligned} \begin{array}{lr} -\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta_{t} \right)_{j} } & \qquad \left(\beta_{t} \right)_{j} >0 \\ -\left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta_{t} \right)_{j} =0 +\left(r_{e,i} \right)\_{j} = \frac{\left(r_{i} \right)\_{j} \left(w_{i} \right)\_{j}}{\left(\beta_{t} \right)\_{j}} & \qquad \left(\beta_{t} \right)\_{j} > 0 \\ +\left(r_{e,i} \right)\_{j} = 0 & \qquad \left(\beta_{t} \right)_{j} = 0 \end{array} -\end{aligned}$$ +\end{aligned} +$$ and $\left(r_{i} \right)_{j}$ is the fraction of roots in layer $i$ (Chapter `rst_Stomatal Resistance and Photosynthesis`{.interpreted-text @@ -718,10 +720,15 @@ $0.01\, \theta_{sat,\, i} \le \theta_{\, i} \le \theta_{sat,\, i}$. The derivatives of the hydraulic conductivity at the layer interface are derived from `7.85`{.interpreted-text role="eq"} -$$\begin{array}{l} -{\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i-1} } -= \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta_{liq,\, i} } -= \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}$$ +$$ +\begin{array}{l} +\frac{\partial k\left[z_{h,i-1} \right]}{\partial \theta_{liq,i-1}} += \frac{\partial k\left[z_{h,i-1} \right]}{\partial \theta_{liq,i}} += \left(2B_{i-1} + 3\right) \, \overline{\Theta}\_{ice} \, k_{sat}\left[z_{h,i-1} \right] +\left( \frac{\overline{\theta}\_{liq}}{\overline{\theta}\_{sat}} \right)^{2B_{i-1} + 2} +\left( \frac{0.5}{\overline{\theta}_{sat}} \right) +\end{array} +$$ where $\overline{\Theta}_{ice} = \Theta(\overline{\theta}_{ice})$ `7.86`{.interpreted-text role="eq"}, From d7390ee0a72dc82921d1147aab3eb277fa9daf16 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Mon, 16 Jun 2025 14:45:51 -0700 Subject: [PATCH 09/42] correction --- components/elm/docs/tech-guide/hydrology.md | 22 +++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/components/elm/docs/tech-guide/hydrology.md b/components/elm/docs/tech-guide/hydrology.md index 5ee275504a71..231c87d20042 100644 --- a/components/elm/docs/tech-guide/hydrology.md +++ b/components/elm/docs/tech-guide/hydrology.md @@ -730,23 +730,25 @@ $$ \end{array} $$ -where $\overline{\Theta}_{ice} = \Theta(\overline{\theta}_{ice})$ +where $\overline{\Theta}\_{ice} = \Theta(\overline{\theta}\_{ice})$ `7.86`{.interpreted-text role="eq"}, -$\overline{\theta}_{ice} = 0.5\left(\theta_{ice\, i-1} +\theta_{ice\, i} \right)$, -$\overline{\theta}_{liq} = 0.5\left(\theta_{liq\, i-1} +\theta_{liq\, i} \right)$, +$\overline{\theta}\_{ice} = 0.5\left(\theta_{ice\, i-1} +\theta_{ice\, i} \right)$, +$\overline{\theta}\_{liq} = 0.5\left(\theta_{liq\, i-1} +\theta_{liq\, i} \right)$, and -$\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i-1} +\theta_{sat,\, i} \right)$ +$\overline{\theta}\_{sat} = 0.5\left(\theta_{sat,\, i-1} +\theta_{sat,\, i} \right)$ and -$$\begin{array}{l} -{\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i} } -= \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta_{liq,\, i+1} } -= \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}.$$ +$$ +\begin{array}{l} +{\frac{\partial k\left[z_{h,i} \right]}{\partial \theta_{liq,i}} += \frac{\partial k\left[z_{h,i} \right]}{\partial \theta_{liq,i+1}} += \left(2B_{i} +3\right) \, \overline{\Theta}\_{ice} \ k_{sat} \left[z_{h,i} \right] +\ \left(\frac{\overline{\theta}\_{liq}}{\overline{\theta}\_{sat}} \right)^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}.$$ where -$\overline{\theta}_{liq} = 0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)$, -$\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)$. +$\overline{\theta}\_{liq} = 0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)$, +$\overline{\theta}\_{sat} = 0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)$. #### Equation set for layer $i=1$ From 76d528082132c55ca1fdbcb6db0fb33e1a066f55 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 10:42:34 -0700 Subject: [PATCH 10/42] Document h3d solver --- components/elm/docs/tech-guide/h3d.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 components/elm/docs/tech-guide/h3d.md diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md new file mode 100644 index 000000000000..40cdb3ca7674 --- /dev/null +++ b/components/elm/docs/tech-guide/h3d.md @@ -0,0 +1 @@ +#Hybrid-3D hillslope hydrological model From 2ebb12c7e4b655ada2541cffc39bf34056c6031f Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 10:46:02 -0700 Subject: [PATCH 11/42] Document h3d solver --- components/elm/docs/tech-guide/h3d.md | 1 + components/elm/docs/tech-guide/index.md | 1 + 2 files changed, 2 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 40cdb3ca7674..8eb569182508 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1 +1,2 @@ #Hybrid-3D hillslope hydrological model + diff --git a/components/elm/docs/tech-guide/index.md b/components/elm/docs/tech-guide/index.md index feef6d521697..08e78d7d907b 100644 --- a/components/elm/docs/tech-guide/index.md +++ b/components/elm/docs/tech-guide/index.md @@ -9,3 +9,4 @@ Parameterization of sub-grid topographical effects on solar radiation. - [Longwave Radiation](longwave_radiation.md): Longwave radiation model - [Hydrology](hydrology.md): Hydrology model - [Plant Hydraulics](phs.md): Plant Hydraulics model +- [Hybrid-3D hillslope hydrological model](h3d.md): Hybrid-3D hillslope hydrological model From f5034372e9cd103530f0366e883ad26d50533b3a Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 10:58:52 -0700 Subject: [PATCH 12/42] update --- components/elm/docs/tech-guide/h3d.md | 20 ++++++++++++++++++++ components/elm/docs/tech-guide/index.md | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 8eb569182508..56b806a6feef 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,2 +1,22 @@ #Hybrid-3D hillslope hydrological model +The model represents subsurface flow and groundwater discharge along an +idealized hillslope within each grid cell. It solves the Dupuit–Boussinesq +form of the lateral flow equation for the saturated thickness $h(x,t)$, +using a finite‐difference implicit solver. The formulation includes +variable transmissivity, slope‐driven gradients, variable drainable +porosity, and recharge coupling. + +$$ +\frac{\partial h}{\partial t} += \frac{1}{f_{\text{drain}}} +\frac{\partial}{\partial x} +\left[ +T(x,h) +\left( +\frac{\partial h}{\partial x}\cos\theta + \sin\theta +\right) +\right] ++ \frac{R}{f_{\text{drain}}} +$$ + diff --git a/components/elm/docs/tech-guide/index.md b/components/elm/docs/tech-guide/index.md index 08e78d7d907b..3a8a377ab590 100644 --- a/components/elm/docs/tech-guide/index.md +++ b/components/elm/docs/tech-guide/index.md @@ -9,4 +9,4 @@ Parameterization of sub-grid topographical effects on solar radiation. - [Longwave Radiation](longwave_radiation.md): Longwave radiation model - [Hydrology](hydrology.md): Hydrology model - [Plant Hydraulics](phs.md): Plant Hydraulics model -- [Hybrid-3D hillslope hydrological model](h3d.md): Hybrid-3D hillslope hydrological model +- [Hybrid-3D hillslope hydrology](h3d.md): Hybrid-3D hillslope hydrological model From 8f976c5f17e009e70014e28b775371876ac06ff3 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:00:31 -0700 Subject: [PATCH 13/42] update --- components/elm/docs/tech-guide/h3d.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 56b806a6feef..f67a7cf555a8 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,4 +1,4 @@ -#Hybrid-3D hillslope hydrological model +# Hybrid-3D hillslope hydrological model The model represents subsurface flow and groundwater discharge along an idealized hillslope within each grid cell. It solves the Dupuit–Boussinesq From 16d899162648539ddb72aced8255f2a4d239964f Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:07:49 -0700 Subject: [PATCH 14/42] update --- components/elm/docs/tech-guide/h3d.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index f67a7cf555a8..26c048e8d61f 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -7,16 +7,7 @@ using a finite‐difference implicit solver. The formulation includes variable transmissivity, slope‐driven gradients, variable drainable porosity, and recharge coupling. -$$ -\frac{\partial h}{\partial t} -= \frac{1}{f_{\text{drain}}} -\frac{\partial}{\partial x} -\left[ -T(x,h) -\left( -\frac{\partial h}{\partial x}\cos\theta + \sin\theta -\right) -\right] -+ \frac{R}{f_{\text{drain}}} +>$$ +\frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial }\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} $$ From 569aaf1f4fbdba5ca0dc3f1a4098eff7845d7445 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:22:53 -0700 Subject: [PATCH 15/42] update --- components/elm/docs/tech-guide/h3d.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 26c048e8d61f..d1233d161d48 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -7,7 +7,12 @@ using a finite‐difference implicit solver. The formulation includes variable transmissivity, slope‐driven gradients, variable drainable porosity, and recharge coupling. ->$$ +$$ \frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial }\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} $$ +where $h(x,t)$ is the saturated thickness [m], +$f_{\text{drain}}$ is the drainable porosity [–], +$T(x,h)$ is the transmissivity [m² s⁻¹], +$\theta$ is the hillslope angle [rad], +and $R$ is the recharge rate [m s⁻¹]. From b7c88c088b132f0e75d5a00885daf24768ecf5c3 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:25:16 -0700 Subject: [PATCH 16/42] update --- components/elm/docs/tech-guide/h3d.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index d1233d161d48..2b5e794fe63f 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -16,3 +16,14 @@ $f_{\text{drain}}$ is the drainable porosity [–], $T(x,h)$ is the transmissivity [m² s⁻¹], $\theta$ is the hillslope angle [rad], and $R$ is the recharge rate [m s⁻¹]. + +Transmissivity +$$ +T(x,h) += \frac{K_{\text{aniso}}\,K_{\text{sat}}(z_{wt})\,h\,w(x)}{1000} +$$ + +where $K_{\text{aniso}}=100$ is the horizontal/vertical anisotropy factor, +$K_{\text{sat}}(z_{wt})$ is the saturated hydraulic conductivity at the +water-table depth [mm s⁻¹], and $w(x)$ is the hillslope width [m]. +Division by 1000 converts from mm s⁻¹ to m s⁻¹. From c38a6bc81ffff4bd5148bd5d3049b44d7b6b5bbc Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:27:17 -0700 Subject: [PATCH 17/42] update --- components/elm/docs/tech-guide/h3d.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 2b5e794fe63f..1702a029a79c 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -17,10 +17,10 @@ $T(x,h)$ is the transmissivity [m² s⁻¹], $\theta$ is the hillslope angle [rad], and $R$ is the recharge rate [m s⁻¹]. -Transmissivity +## Transmissivity + $$ -T(x,h) -= \frac{K_{\text{aniso}}\,K_{\text{sat}}(z_{wt})\,h\,w(x)}{1000} +T(x,h)= \frac{K_{\text{aniso}}\,K_{\text{sat}}(z_{wt})\,h\,w(x)}{1000} $$ where $K_{\text{aniso}}=100$ is the horizontal/vertical anisotropy factor, From 06565b7a72b3f1bbc7a337f36b4703b2e736d672 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:29:18 -0700 Subject: [PATCH 18/42] update --- components/elm/docs/tech-guide/h3d.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 1702a029a79c..1daba0dfaf5d 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -27,3 +27,24 @@ where $K_{\text{aniso}}=100$ is the horizontal/vertical anisotropy factor, $K_{\text{sat}}(z_{wt})$ is the saturated hydraulic conductivity at the water-table depth [mm s⁻¹], and $w(x)$ is the hillslope width [m]. Division by 1000 converts from mm s⁻¹ to m s⁻¹. + +## Variable Drainable Porosity + +$$ +f_{\text{drain}} += \theta_{\text{sat}} +\left[ +1 - +\left( +1 + +\frac{1000\,\max(0,\,z_{\text{bed}}-h)}{\psi_{\text{sat}}} +\right)^{-1/b} +\right], +\qquad +f_{\text{drain}}\ge0.02 +$$ + +where $\theta_{\text{sat}}$ is porosity [–], +$z_{\text{bed}}$ is bedrock depth [m], +$\psi_{\text{sat}}$ is air-entry suction [mm], +and $b$ is the Brooks–Corey pore-size index [–]. From 92c48c31f72cf954bc3da1d3c249c8f661c0f6a9 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:31:41 -0700 Subject: [PATCH 19/42] update --- components/elm/docs/tech-guide/h3d.md | 28 +++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 1daba0dfaf5d..f6cf1a398de4 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -48,3 +48,31 @@ where $\theta_{\text{sat}}$ is porosity [–], $z_{\text{bed}}$ is bedrock depth [m], $\psi_{\text{sat}}$ is air-entry suction [mm], and $b$ is the Brooks–Corey pore-size index [–]. + +##Finite-Difference Discretization + +The PDE is solved implicitly in space and time using a tridiagonal +system for $h_i^{n+1}$ at each node $i$: + +$$ +a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i +$$ + + +Interior nodes ($i=2,\dots,N-1$) + +$$ +\begin{aligned} +a_i &= -\frac{T_{i-\frac12}^n \cos\theta \,\Delta t} + {\Delta x_{i-\frac12}\,\Delta x_i\,w_i}, \\ +c_i &= -\frac{T_{i+\frac12}^n \cos\theta \,\Delta t} + {\Delta x_{i+\frac12}\,\Delta x_i\,w_i}, \\ +b_i &= f_{\text{drain},i} - (a_i + c_i), \\ +r_i &= f_{\text{drain},i} h_i^n + + \frac{\Delta t\sin\theta}{w_i\Delta x_i} + (T_{i+\frac12}^n - T_{i-\frac12}^n) + + \Delta t R_i. +\end{aligned} +$$ + + From f807d18d7995e297af27b0955adf5817cc8132c9 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:36:44 -0700 Subject: [PATCH 20/42] update --- components/elm/docs/tech-guide/h3d.md | 67 +++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index f6cf1a398de4..8deee32cdc7d 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -75,4 +75,71 @@ r_i &= f_{\text{drain},i} h_i^n \end{aligned} $$ +Upper boundary ($i=N$, divide) + +$$ +\begin{aligned} +a_N &= -\frac{T_{N-\frac12}^n \cos\theta \,\Delta t} + {\Delta x_{N-\frac12}\,\Delta x_N\,w_N}, \\ +c_N &= 0, \\ +b_N &= f_{\text{drain},N} - a_N, \\ +r_N &= f_{\text{drain},N} h_N^n + - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N-\frac12}^n + + \Delta t R_N. +\end{aligned} +$$ + +Subsurface Runoff and Storage Change + +$$ +\Delta S_{\text{sat},i} += f_{\text{drain},i}(h_i^{n+1}-h_i^n), +\qquad +R_{\text{sub},i} = -\Delta S_{\text{sat},i}, +\qquad +Q_{\text{sub},i} = \frac{R_{\text{sub},i}}{\Delta t}\times1000 +$$ + +Water-Table Depth + +$$ +z_{wt,i} = z_{\text{bed},i} - h_i +$$ + +Adaptive time-stepping: + +$$ +\Delta t_{\text{new}} = 0.5\,\Delta t_{\text{old}} +$$ + + +## Tridiagonal Matrix Solution + +Forward elimination: + +$$ +\begin{aligned} +\beta_1 &= b_1, \quad \tilde{r}_1 = \frac{r_1}{\beta_1}, \\ +\gamma_i &= \frac{c_{i-1}}{\beta_{i-1}}, \\ +\beta_i &= b_i - a_i\gamma_i, \\ +\tilde{r}_i &= \frac{r_i - a_i\tilde{r}_{i-1}}{\beta_i}, \quad (i=2,\dots,N) +\end{aligned} +$$ + +Back substitution: + +$$ +h_N = \tilde{r}_N, \qquad +h_i = \tilde{r}_i - \gamma_{i+1} h_{i+1}, \quad (i=N-1,\dots,1) +$$ + +## Boundary Conditions + +| Boundary | Condition | Implementation | +| :------------- | :------------------------------------ | :----------------------- | +| Lower (stream) | Head-dependent outflow | Robin-type term in $r_1$ | +| Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | + + + From 20ee4fe9d90b631bb6bff4256b164478753f6680 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:38:51 -0700 Subject: [PATCH 21/42] update --- components/elm/docs/tech-guide/h3d.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 8deee32cdc7d..5330559ab164 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -49,7 +49,7 @@ $z_{\text{bed}}$ is bedrock depth [m], $\psi_{\text{sat}}$ is air-entry suction [mm], and $b$ is the Brooks–Corey pore-size index [–]. -##Finite-Difference Discretization +## Finite-Difference Discretization The PDE is solved implicitly in space and time using a tridiagonal system for $h_i^{n+1}$ at each node $i$: @@ -89,7 +89,7 @@ r_N &= f_{\text{drain},N} h_N^n \end{aligned} $$ -Subsurface Runoff and Storage Change +## Subsurface Runoff and Storage Change $$ \Delta S_{\text{sat},i} From f5e54cc763e9bfd76b8dfb1749475799f8bbed20 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 11:59:31 -0700 Subject: [PATCH 22/42] update --- components/elm/docs/tech-guide/h3d.md | 57 ++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 5330559ab164..5a74c307a2ef 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -142,4 +142,59 @@ $$ - +flowchart TD + A[Start H3D_DRI Solver] --> B[Initialize Variables] + B --> C[Set sub_timestep = timestep
accumulated_time = 0
h_sat_begin = current state] + + C --> D[Loop: For each land unit] + D --> E{accumulated_time < timestep?} + + E -->|Yes| F[accumulated_time += sub_timestep
Store h_sat_old] + E -->|No| S[Calculate Runoff Rates] + + F --> G{Any h_sat_old == 0?
Dry conditions?} + G -->|Yes| H[Set h_sat_new = h_sat_old
f_drain = 0.2
Continue] + G -->|No| I[Call LATERAL_RESPONSE_SOLVER] + + H --> E + + I --> J[Start Newton-Raphson Loop
iteration = 0
h_previous = h_old] + + J --> K{iteration < max_iter AND
NOT converged?} + K -->|No| M{Converged?} + K -->|Yes| L[iteration++
Update Soil Properties] + + L --> N[Calculate drainable_porosity
using Brooks-Corey model] + N --> O[Calculate transmissivity
T = K_aniso × K_sat × h × w] + + O --> P[Setup Tridiagonal Matrix
a[i], b[i], c[i], r[i]] + P --> Q[Solve using Thomas Algorithm
Forward elimination
Back substitution] + + Q --> R{Solution error OR
max_change < tolerance?} + R -->|Error| M + R -->|Converged| T[converged = TRUE] + R -->|Continue| U[h_previous = h_new] + + T --> M + U --> K + + M -->|Yes| V[Accept Solution
h_sat_new = MAX(0, h_new)
Update water_table_depth] + M -->|No| W[Reject Solution
accumulated_time -= sub_timestep
sub_timestep = 0.5 × sub_timestep] + + V --> E + W --> X{sub_timestep < 10 sec?} + X -->|Yes| Y[Print Warning:
Very small timestep] + X -->|No| E + Y --> E + + S --> Z[storage_change = f_drain × Δh_sat
runoff = -storage_change/dt × 1000] + Z --> AA[Next Land Unit] + AA --> BB{More land units?} + BB -->|Yes| D + BB -->|No| CC[End] + + style A fill:#e1f5fe + style CC fill:#e8f5e8 + style I fill:#fff3e0 + style M fill:#fce4ec + style Y fill:#ffebee From 2a637e0f38c1afcc2e06270a695f103d627d0006 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 12:45:57 -0700 Subject: [PATCH 23/42] update --- components/elm/docs/tech-guide/h3d.md | 89 ++++++++++----------------- 1 file changed, 33 insertions(+), 56 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 5a74c307a2ef..ee15e0820766 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,5 +1,38 @@ # Hybrid-3D hillslope hydrological model + +Area-Weighted Parameter Averaging +Before calling the lateral response solver, the code calculates area-weighted averages: + +$$\text{rsub_top_default} = \sum_{c=c_0}^{c_0+N-1} \text{tmp_rsub_top}(c) \times \text{hs_dA}(l,c-c_0+1) + + +$$\text{zwt\_h3d\_avg} = \frac{1}{\text{hs\_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{zwt\_h3d}(c) \times \text{hs\_dA}(l,c-c_0+1)$$ +\text{h3d_rsub_top_max_avg} = \frac{1}{\text{hs_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{h3d_rsub_top_max}(c) \times \text{hs_dA}(l,c-c_0+1) + + +$$\text{fff\_avg} = \frac{1}{\text{hs\_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{fff}(c) \times \text{hs\_dA}(l,c-c_0+1)$$ + +### 2. **Default Subsurface Runoff Calculation** +\text{rsub_top_default} = \text{h3d_rsub_top_max_avg} \times \exp(-\text{fff_avg} \times \text{zwt_h3d_avg}) \times \text{hs_area}(l) + + +### 3. **Area-Weighted Storage Change** +\text{hs_dS_sat_tot} = \sum_{c=c_0}^{c_0+N-1} \text{hs_dS_sat}(c) \times \text{hs_dA}(l,c-c_0+1) + + +### 4. **Area-Weighted Drainage Sum** +\text{tmp_sum_drain} = \sum_{c=c_0}^{c_0+N-1} \text{qflx_drain}(c) \times \text{hs_dA}(l,c-c_0+1)$$ + +Variable Definitions +Where: + +hs_dA(l,i) = surface area of h3d soil column i in land unit l [m²] +hs_area(l) = total surface area of hillslope in land unit l [m²] +l = land unit index +c_0 = first column index in land unit l +N = nh3dc_per_lunit = number of columns per land unit + The model represents subsurface flow and groundwater discharge along an idealized hillslope within each grid cell. It solves the Dupuit–Boussinesq form of the lateral flow equation for the saturated thickness $h(x,t)$, @@ -142,59 +175,3 @@ $$ -flowchart TD - A[Start H3D_DRI Solver] --> B[Initialize Variables] - B --> C[Set sub_timestep = timestep
accumulated_time = 0
h_sat_begin = current state] - - C --> D[Loop: For each land unit] - D --> E{accumulated_time < timestep?} - - E -->|Yes| F[accumulated_time += sub_timestep
Store h_sat_old] - E -->|No| S[Calculate Runoff Rates] - - F --> G{Any h_sat_old == 0?
Dry conditions?} - G -->|Yes| H[Set h_sat_new = h_sat_old
f_drain = 0.2
Continue] - G -->|No| I[Call LATERAL_RESPONSE_SOLVER] - - H --> E - - I --> J[Start Newton-Raphson Loop
iteration = 0
h_previous = h_old] - - J --> K{iteration < max_iter AND
NOT converged?} - K -->|No| M{Converged?} - K -->|Yes| L[iteration++
Update Soil Properties] - - L --> N[Calculate drainable_porosity
using Brooks-Corey model] - N --> O[Calculate transmissivity
T = K_aniso × K_sat × h × w] - - O --> P[Setup Tridiagonal Matrix
a[i], b[i], c[i], r[i]] - P --> Q[Solve using Thomas Algorithm
Forward elimination
Back substitution] - - Q --> R{Solution error OR
max_change < tolerance?} - R -->|Error| M - R -->|Converged| T[converged = TRUE] - R -->|Continue| U[h_previous = h_new] - - T --> M - U --> K - - M -->|Yes| V[Accept Solution
h_sat_new = MAX(0, h_new)
Update water_table_depth] - M -->|No| W[Reject Solution
accumulated_time -= sub_timestep
sub_timestep = 0.5 × sub_timestep] - - V --> E - W --> X{sub_timestep < 10 sec?} - X -->|Yes| Y[Print Warning:
Very small timestep] - X -->|No| E - Y --> E - - S --> Z[storage_change = f_drain × Δh_sat
runoff = -storage_change/dt × 1000] - Z --> AA[Next Land Unit] - AA --> BB{More land units?} - BB -->|Yes| D - BB -->|No| CC[End] - - style A fill:#e1f5fe - style CC fill:#e8f5e8 - style I fill:#fff3e0 - style M fill:#fce4ec - style Y fill:#ffebee From 0c6691bbb559d3cd0cb9714eb07bb7538dab15e5 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 12:52:24 -0700 Subject: [PATCH 24/42] update --- components/elm/docs/tech-guide/h3d.md | 83 +++++++++++++++++++++------ 1 file changed, 65 insertions(+), 18 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index ee15e0820766..f66411b1889b 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,37 +1,84 @@ # Hybrid-3D hillslope hydrological model -Area-Weighted Parameter Averaging -Before calling the lateral response solver, the code calculates area-weighted averages: +### Area-Weighted Parameter Averaging -$$\text{rsub_top_default} = \sum_{c=c_0}^{c_0+N-1} \text{tmp_rsub_top}(c) \times \text{hs_dA}(l,c-c_0+1) +$$ +\text{rsub\_top\_default} += \sum_{c=c_0}^{c_0+N-1} + \text{tmp\_rsub\_top}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ +$$ +\text{zwt\_h3d\_avg} += \frac{1}{\text{hs\_area}(l)} + \sum_{c=c_0}^{c_0+N-1} + \text{zwt\_h3d}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ -$$\text{zwt\_h3d\_avg} = \frac{1}{\text{hs\_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{zwt\_h3d}(c) \times \text{hs\_dA}(l,c-c_0+1)$$ -\text{h3d_rsub_top_max_avg} = \frac{1}{\text{hs_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{h3d_rsub_top_max}(c) \times \text{hs_dA}(l,c-c_0+1) +$$ +\text{h3d\_rsub\_top\_max\_avg} += \frac{1}{\text{hs\_area}(l)} + \sum_{c=c_0}^{c_0+N-1} + \text{h3d\_rsub\_top\_max}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ +$$ +\text{fff\_avg} += \frac{1}{\text{hs\_area}(l)} + \sum_{c=c_0}^{c_0+N-1} + \text{fff}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ -$$\text{fff\_avg} = \frac{1}{\text{hs\_area}(l)} \sum_{c=c_0}^{c_0+N-1} \text{fff}(c) \times \text{hs\_dA}(l,c-c_0+1)$$ +### Default Subsurface Runoff Calculation -### 2. **Default Subsurface Runoff Calculation** -\text{rsub_top_default} = \text{h3d_rsub_top_max_avg} \times \exp(-\text{fff_avg} \times \text{zwt_h3d_avg}) \times \text{hs_area}(l) +$$ +\text{rsub\_top\_default} += \text{h3d\_rsub\_top\_max\_avg} + \times + \exp(-\text{fff\_avg} \times \text{zwt\_h3d\_avg}) + \times + \text{hs\_area}(l) +$$ +### Area-Weighted Storage Change -### 3. **Area-Weighted Storage Change** -\text{hs_dS_sat_tot} = \sum_{c=c_0}^{c_0+N-1} \text{hs_dS_sat}(c) \times \text{hs_dA}(l,c-c_0+1) +$$ +\text{hs\_dS\_sat\_tot} += \sum_{c=c_0}^{c_0+N-1} + \text{hs\_dS\_sat}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ +### Area-Weighted Drainage Sum -### 4. **Area-Weighted Drainage Sum** -\text{tmp_sum_drain} = \sum_{c=c_0}^{c_0+N-1} \text{qflx_drain}(c) \times \text{hs_dA}(l,c-c_0+1)$$ +$$ +\text{tmp\_sum\_drain} += \sum_{c=c_0}^{c_0+N-1} + \text{qflx\_drain}(c) + \times + \text{hs\_dA}(l,\,c-c_0+1) +$$ Variable Definitions -Where: -hs_dA(l,i) = surface area of h3d soil column i in land unit l [m²] -hs_area(l) = total surface area of hillslope in land unit l [m²] -l = land unit index -c_0 = first column index in land unit l -N = nh3dc_per_lunit = number of columns per land unit +| Variable | Description | Units | +| :-------------------- | :--------------------------------------------------- | :---- | +| `hs_dA(l,i)` | Surface area of h3D soil column *i* in land unit *l* | m² | +| `hs_area(l)` | Total surface area of hillslope in land unit *l* | m² | +| `l` | Land unit index | – | +| `c₀` | First column index in land unit *l* | – | +| `N = nh3dc_per_lunit` | Number of columns per land unit | – | + The model represents subsurface flow and groundwater discharge along an idealized hillslope within each grid cell. It solves the Dupuit–Boussinesq From 2045e8549669eec13707ea766ae449292aa6c922 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 12:56:57 -0700 Subject: [PATCH 25/42] update --- components/elm/docs/tech-guide/h3d.md | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index f66411b1889b..cfab30c67ea5 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -4,69 +4,69 @@ ### Area-Weighted Parameter Averaging $$ -\text{rsub\_top\_default} +r_{sub,\,top}^{default} = \sum_{c=c_0}^{c_0+N-1} - \text{tmp\_rsub\_top}(c) + tmp_{rsub,\,top}(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ $$ -\text{zwt\_h3d\_avg} -= \frac{1}{\text{hs\_area}(l)} +zwt_{h3d}^{avg} += \frac{1}{hs_{area}(l)} \sum_{c=c_0}^{c_0+N-1} - \text{zwt\_h3d}(c) + zwt_{h3d}(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ $$ -\text{h3d\_rsub\_top\_max\_avg} -= \frac{1}{\text{hs\_area}(l)} +r_{sub,\,top,\,h3d}^{max,\,avg} += \frac{1}{hs_{area}(l)} \sum_{c=c_0}^{c_0+N-1} - \text{h3d\_rsub\_top\_max}(c) + r_{sub,\,top,\,h3d}^{max}(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ $$ -\text{fff\_avg} -= \frac{1}{\text{hs\_area}(l)} +fff^{avg} += \frac{1}{hs_{area}(l)} \sum_{c=c_0}^{c_0+N-1} - \text{fff}(c) + fff(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ ### Default Subsurface Runoff Calculation $$ -\text{rsub\_top\_default} -= \text{h3d\_rsub\_top\_max\_avg} +r_{sub,\,top}^{default} += r_{sub,\,top,\,h3d}^{max,\,avg} \times - \exp(-\text{fff\_avg} \times \text{zwt\_h3d\_avg}) + \exp\!\left(-fff^{avg} \times zwt_{h3d}^{avg}\right) \times - \text{hs\_area}(l) + hs_{area}(l) $$ ### Area-Weighted Storage Change $$ -\text{hs\_dS\_sat\_tot} +\Delta S_{sat}^{tot} = \sum_{c=c_0}^{c_0+N-1} - \text{hs\_dS\_sat}(c) + \Delta S_{sat}(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ ### Area-Weighted Drainage Sum $$ -\text{tmp\_sum\_drain} +Q_{drain}^{tot} = \sum_{c=c_0}^{c_0+N-1} - \text{qflx\_drain}(c) + q_{drain}(c) \times - \text{hs\_dA}(l,\,c-c_0+1) + hs_{dA}(l,\,c-c_0+1) $$ Variable Definitions From 4221acaf62b15b5fe60de437f7ec80bfb66e4851 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 13:11:38 -0700 Subject: [PATCH 26/42] update --- components/elm/docs/tech-guide/h3d.md | 300 ++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index cfab30c67ea5..2f8d051da9a3 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -87,6 +87,13 @@ using a finite‐difference implicit solver. The formulation includes variable transmissivity, slope‐driven gradients, variable drainable porosity, and recharge coupling. +Each land unit represents a single hillslope, which has consistent topographic and geometric properties: +- **Overall slope angle:** $\theta$ — mean hillslope angle (rad) +- **Width function:** $w(x)$ — lateral width distribution along the hillslope (m) +- **Distance function:** $x(i)$ — distance from the stream outlet to node $i$ (m) +- **Total hillslope area:** $A_{hs} = \displaystyle \int_0^L w(x)\,dx$ (m²) + + $$ \frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial }\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} $$ @@ -221,4 +228,297 @@ $$ | Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | +# DrainageH3D → H3D_DRI → LateralResponse + +The h3D pathway computes (a) a **default topographic drainage propensity** from SIMTOP-style scalings, (b) a **within-landunit lateral response** by solving a **1-D hillslope Dupuit–Boussinesq** problem for saturated thickness, and (c) converts the updated saturated thickness to **subsurface runoff** and **diagnostics**. + +--- + +## 1. Area-Weighted Hillslope Inputs (per landunit \(l\)) + +$$ +r_{sub,\,top}^{default} +=\sum_{c=c_0}^{c_0+N-1} + tmp_{rsub,\,top}(c)\; hs_{dA}(l,\,c-c_0+1) +\qquad[\mathrm{m^3\,s^{-1}}] +$$ + +$$ +\overline{zwt}_{h3d} +=rac{1}{hs_{area}(l)} + \sum_{c=c_0}^{c_0+N-1} + zwt_{h3d}(c)\; hs_{dA}(l,\,c-c_0+1) +\qquad[\mathrm{m}] +$$ + +$$ +\overline{r_{sub,\,top,\,h3d}^{max}} +=rac{1}{hs_{area}(l)} + \sum_{c=c_0}^{c_0+N-1} + r_{sub,\,top,\,h3d}^{max}(c)\; hs_{dA}(l,\,c-c_0+1) +\qquad[\mathrm{m\,s^{-1}}] +$$ + +$$ +\overline{fff} +=rac{1}{hs_{area}(l)} + \sum_{c=c_0}^{c_0+N-1} + fff(c)\; hs_{dA}(l,\,c-c_0+1) +\qquad[\mathrm{m^{-1}}] +$$ + +$$ +r_{sub,\,top}^{default} += +\overline{r_{sub,\,top,\,h3d}^{max}}\; +\exp\!\left(-\,\overline{fff}\;\overline{zwt}_{h3d} +ight)\; +hs_{area}(l) +\qquad[\mathrm{m^3\,s^{-1}}] +$$ + +--- + +## 2. Saturated Thickness and Bounds + +$$ +h_{sat}(c) \equiv z_{wt,\,bed}(c) - z_{wt}(c), +\qquad h_{sat}\ge 0 +\qquad[\mathrm{m}] +$$ + +$$ +z_{wt}(c) \in [\,0,\;z_{wt,\,bed}(c)\,],\quad +z_{wt,\,bed}(c)=egin{cases} +z_{ibed}(c), & ext{variable soil thickness}\ +z_{ibed}(c)+25\,\mathrm{m}, & ext{otherwise} +\end{cases} +$$ + +$$ +h_{sat}^{begin}(c)=z_{wt,\,bed}(c)-z_{wt}^{begin}(c) +$$ + +--- + +## 3. Specific Yield \(f_{ ext{drain}}\) (Brooks–Corey) + +Let \(idx=\min\{jwt(c)+1,\;n_{lev\,bed}(c)\}\). + +$$ +f_{drain}(c) += +\max\!\left[ +0.02,\; + heta_{sat}(c,idx)\left( +1-\left( +1+rac{1000\;\max\!\{0,\;z_{wt,\,bed}(c)-h_{sat}(c)\}} +{\psi_{sat}(c,idx)} + +ight)^{-1/b(c,idx)} + +ight) + +ight] +\qquad[-] +$$ + +--- + +## 4. Transmissivity Along the Hillslope (Interface Form) + +For hillslope node \(k=1,\dots,N\) (lower boundary \(k=1\) at stream; upper \(k=N\) at divide), with anisotropy \(f_{aniso}=100\): + +$$ +wK\!H(k) += +f_{aniso}\; +hs_{w,\,nod}(l,k)\; +rac{hk_{sat}(c_k,idx_k)}{1000}\; +h_{sat}^{prev}(k) +\qquad[\mathrm{m^3\,s^{-1}}] +$$ + +where \(c_k=c_0+k-1\) and \(idx_k=\min\{jwt(c_k)+1,\,n_{lev\,bed}(c_k)\}\). + +--- + +## 5. Discrete Hillslope PDE (Implicit, Tridiagonal in \(h_{sat}\)) + +Let \( heta_k = h3d\_slope(c_k)\cdot\pi/180\), and geometry \(hs_{dx}(l,k)\), \(hs_{dx,\,nod}(l,k)\), \(hs_{w,\,nod}(l,k)\). + +### 5.1 Interior Nodes \(k=2,\dots,N-1\) + +$$ +a_k += -rac{wK\!H(k)\cos heta_k\;\Delta t_{h3d}} + {hs_{dx,\,nod}(l,k)\;hs_{dx}(l,k)\;hs_{w,\,nod}(l,k)}, +\qquad +c_k += -rac{wK\!H(k+1)\cos heta_k\;\Delta t_{h3d}} + {hs_{dx,\,nod}(l,k+1)\;hs_{dx}(l,k)\;hs_{w,\,nod}(l,k)}, +$$ + +$$ +b_k = f_{drain}(c_k) - (a_k + c_k), +$$ + +$$ +r_k += f_{drain}(c_k)\;h_{sat}^{old}(k) ++ rac{\Delta t_{h3d}\,\sin heta_k}{hs_{w,\,nod}(l,k)\;hs_{dx}(l,k)} + \Big[wK\!H(k+1) - wK\!H(k)\Big], +$$ + +$$ +a_k\,h_{sat}(k-1) + b_k\,h_{sat}(k) + c_k\,h_{sat}(k+1) = r_k. +$$ + +### 5.2 Lower Boundary \(k=1\) (Stream; Head-Dependent Outflow) + +$$ +a_1=0,\qquad +c_1 += -rac{wK\!H(2)\cos heta_1\;\Delta t_{h3d}} + {hs_{dx,\,nod}(l,2)\;hs_{dx}(l,1)\;hs_{w,\,nod}(l,1)}, +$$ + +$$ +b_1=f_{drain}(c_1)-(a_1+c_1), +$$ + +$$ +r_1= +f_{drain}(c_1)\;h_{sat}^{old}(1) ++rac{\Delta t_{h3d}}{hs_{w,\,nod}(l,1)\;hs_{dx}(l,1)} +\left[ +\sin heta_1\;wK\!H(2) +-rac{\cos heta_1}{hs_{dx}(l,1)} +\,hs_{w,\,nod}(l,1)\, +rac{f_{aniso}\,hk_{sat}(c_1,idx_1)}{1000}\,ig(h_{sat}^{prev}(1ig)^2 + +ight]. +$$ + +### 5.3 Upper Boundary \(k=N\) (Divide; No-Flow) + +$$ +a_N += -rac{wK\!H(N)\cos heta_N\;\Delta t_{h3d}} + {hs_{dx,\,nod}(l,N)\;hs_{dx}(l,N)\;hs_{w,\,nod}(l,N)}, +\qquad +c_N=0, +$$ + +$$ +b_N=f_{drain}(c_N)-(a_N+c_N), +$$ + +$$ +r_N= +f_{drain}(c_N)\;h_{sat}^{old}(N) +-rac{\Delta t_{h3d}\,\sin heta_N}{hs_{w,\,nod}(l,N)\;hs_{dx}(l,N)} +\,wK\!H(N). +$$ + +--- + +## 6. Linear Solve and Iteration + +### Tridiagonal System (Thomas Algorithm) + +$$ +a_k\,h_{sat}(k-1) + b_k\,h_{sat}(k) + c_k\,h_{sat}(k+1) = r_k, +\qquad k=1,\dots,N. +$$ + +### Picard Loop & Convergence + +$$ +\max_{kig|h_{sat}^{(m+1)}(k)-h_{sat}^{(m)}(kig| +< h_{sat}^{thres}=10^{-4}\ \mathrm{m}. +$$ + +If not converged in \(n_{iter}^{max}\), halve \(\Delta t_{h3d}\) and retry: + +$$ +\Delta t_{h3d}\leftarrow frac12\,\Delta t_{h3d}, +\qquad +\sum \Delta t_{h3d} = \Delta t_{\mathrm{ELM}}. +$$ + +Recover water table: + +$$ +z_{wt}(c_k) = z_{wt,\,bed}(c_k) - h_{sat}(k), +\qquad +z_{wt}\in[0,\,80\,\mathrm{m}]\ ext{(clamp)}. +$$ + +--- + +## 7. Storage Change and Subsurface Runoff (ELM Timestep \(\Delta t\)) + +$$ +\Delta S_{sat}(c_k)= f_{drain}(c_k)\,\Big(h_{sat}(k)-h_{sat}^{begin}(k)\Big) +\qquad[\mathrm{m}], +$$ + +$$ +R_{sub}(c_k)= -\,\Delta S_{sat}(c_k)\qquad[\mathrm{m}], +\qquad +Q_{sub}(c_k)= rac{R_{sub}(c_k)}{\Delta t} imes 1000 +\qquad[\mathrm{mm\,s^{-1}}]. +$$ + +$$ +qflx_{drain}(c_k) = Q_{sub}(c_k), +\qquad +qflx_{drain,\,h3d}(c_k)=Q_{sub}(c_k). +$$ + +--- + +## 8. Coupling Back to Column Hydrology + +### Non-h3D (SIMTOP-like) + +$$ +r_{sub,\,top}(c)= imped(c)\; r_{sub,\,top}^{max}(c)\; +\exp\ig(-\,fff(c)\,z_{wt}(cig) +\qquad[\mathrm{mm\,s^{-1}}]. +$$ + +### h3D Columns + +$$ +r_{sub,\,top}(c) = imped(c)\; qflx_{drain,\,h3d}(c) +\qquad[\mathrm{mm\,s^{-1}}]. +$$ + +### Total Drainage + +$$ +qflx_{drain}(c)= qflx_{rsub,\,sat}(c) + r_{sub,\,top}(c). +$$ + +--- + +## 9. Units and Conversions + +$$ +hk_{sat}\,[\mathrm{mm\,s^{-1}}] \ +ightarrow\ \mathrm{m\,s^{-1}} ext{ via } /1000, +\qquad +Q\,[\mathrm{m\,s^{-1}}] \ +ightarrow\ \mathrm{mm\,s^{-1}} ext{ via } imes 1000. +$$ + +--- + +## 10. Indices and Mappings + +- Node \(k\) ↔ column \(c_k=c_0+k-1\), \(k=1,\dots,N=nh3dc\_{per\_lunit}\). +- \(jwt(c)\) is the index above the water table; \(idx=\min(jwt+1,n_{lev\,bed})\). +- \( heta_k\) uses degrees in code; equations use radians. From 2140e05406bcecb44ea3fbbfbbae2181b71e886d Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 14:03:26 -0700 Subject: [PATCH 27/42] update --- components/elm/docs/tech-guide/h3d.md | 442 ++++++-------------------- 1 file changed, 96 insertions(+), 346 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 2f8d051da9a3..826cf65bf519 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,91 +1,30 @@ # Hybrid-3D hillslope hydrological model +## Overview +H3D represents subsurface lateral flow and groundwater dynamics within an idealized hillslope unit inside each land +grid cell. Rather than treating each soil column as an isolated vertical profile, +h3D connects multiple columns along a topographic gradient to explicitly simulate downslope drainage, +water table redistribution, and interaction with the channel. -### Area-Weighted Parameter Averaging +This approach is conceptually one-dimensional along the hillslope, +but retains three-dimensional realism by including slope, width, and drainage area variation. +The model solves the Dupuit–Boussinesq groundwater flow equation for saturated thickness using an implicit finite-difference method. -$$ -r_{sub,\,top}^{default} -= \sum_{c=c_0}^{c_0+N-1} - tmp_{rsub,\,top}(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ - -$$ -zwt_{h3d}^{avg} -= \frac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - zwt_{h3d}(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ - -$$ -r_{sub,\,top,\,h3d}^{max,\,avg} -= \frac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - r_{sub,\,top,\,h3d}^{max}(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ - -$$ -fff^{avg} -= \frac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - fff(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ - -### Default Subsurface Runoff Calculation - -$$ -r_{sub,\,top}^{default} -= r_{sub,\,top,\,h3d}^{max,\,avg} - \times - \exp\!\left(-fff^{avg} \times zwt_{h3d}^{avg}\right) - \times - hs_{area}(l) -$$ - -### Area-Weighted Storage Change - -$$ -\Delta S_{sat}^{tot} -= \sum_{c=c_0}^{c_0+N-1} - \Delta S_{sat}(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ - -### Area-Weighted Drainage Sum +## Conceptual Representation -$$ -Q_{drain}^{tot} -= \sum_{c=c_0}^{c_0+N-1} - q_{drain}(c) - \times - hs_{dA}(l,\,c-c_0+1) -$$ +Each land unit is subdivided into several h3D columns positioned along an idealized hillslope: -Variable Definitions +- Lower boundary corresponds to the stream outlet. +- Upper boundary represents the local topographic divide. +- Intermediate nodes represent soil columns along the slope. -| Variable | Description | Units | -| :-------------------- | :--------------------------------------------------- | :---- | -| `hs_dA(l,i)` | Surface area of h3D soil column *i* in land unit *l* | m² | -| `hs_area(l)` | Total surface area of hillslope in land unit *l* | m² | -| `l` | Land unit index | – | -| `c₀` | First column index in land unit *l* | – | -| `N = nh3dc_per_lunit` | Number of columns per land unit | – | +For each node, the state variable is the saturated thickness, $h_{sat}(x,t)$, measured from the bedrock to the water table. +The model tracks how $h_{sat}(x,t)$ evolves in time due to: +- Local recharge (vertical infiltration) +- Downslope lateral flow driven by topographic gradients +- Variable transmissivity and drainable porosity along the slope -The model represents subsurface flow and groundwater discharge along an -idealized hillslope within each grid cell. It solves the Dupuit–Boussinesq -form of the lateral flow equation for the saturated thickness $h(x,t)$, -using a finite‐difference implicit solver. The formulation includes -variable transmissivity, slope‐driven gradients, variable drainable -porosity, and recharge coupling. Each land unit represents a single hillslope, which has consistent topographic and geometric properties: - **Overall slope angle:** $\theta$ — mean hillslope angle (rad) @@ -93,6 +32,17 @@ Each land unit represents a single hillslope, which has consistent topographic a - **Distance function:** $x(i)$ — distance from the stream outlet to node $i$ (m) - **Total hillslope area:** $A_{hs} = \displaystyle \int_0^L w(x)\,dx$ (m²) +Each column is a point along hillslope, representing a cross-section at distance x along the hillslope. Each has local properties, connected by lateral flow to adjacent columns: +- Soil hydraulic properties (K_sat, porosity, etc.) +- Local area contribution (hs_dA) +- Bedrock depth + +Land unit captures the hillsclope-scale connectivity, while columns capture spatial variation along the flow path. Each column contributes proportionally to the area within the land unit, conserves water mass at hillslope scale, having realistic flow convergence/divergence. Column 1 = stream/outlet, column N = hillslope divide. + + +## Govergning Equation + +The fundamental PDE is a Dupuit-style Boussinesq groundwater flow equation for saturated flow along the slope: $$ \frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial }\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} @@ -104,7 +54,11 @@ $T(x,h)$ is the transmissivity [m² s⁻¹], $\theta$ is the hillslope angle [rad], and $R$ is the recharge rate [m s⁻¹]. -## Transmissivity +## Constitutive Relationships + +### Transmissivity + +The local transmissivity depends on saturated thickness and anisotropy: $$ T(x,h)= \frac{K_{\text{aniso}}\,K_{\text{sat}}(z_{wt})\,h\,w(x)}{1000} @@ -117,6 +71,8 @@ Division by 1000 converts from mm s⁻¹ to m s⁻¹. ## Variable Drainable Porosity +The specific yield varies with depth following a Brooks–Corey relation: + $$ f_{\text{drain}} = \theta_{\text{sat}} @@ -136,7 +92,12 @@ $z_{\text{bed}}$ is bedrock depth [m], $\psi_{\text{sat}}$ is air-entry suction [mm], and $b$ is the Brooks–Corey pore-size index [–]. -## Finite-Difference Discretization +This function allows for a smooth transition between unsaturated and fully saturated conditions and ensures stability under variable soil thickness. + + +## Numerical Implementation + +### Spatial Discretization The PDE is solved implicitly in space and time using a tridiagonal system for $h_i^{n+1}$ at each node $i$: @@ -176,6 +137,28 @@ r_N &= f_{\text{drain},N} h_N^n \end{aligned} $$ +### Temporal Discretization + +A backward-Euler time step is used for stability. Nonlinear terms in transmissivity and porosity are treated by Picard iteration, updating T and $f_{drain} until: + +$$ +\max_i |h_i^{k+1} - h_i^{k}| < 10^{-4}\ \mathrm{m} +$$ + +If convergence fails, the time step is halved adaptively. + +$$ +\Delta t_{h3d}^{new} = 0.5\,\Delta t_{h3d}^{old} +$$ + +Sub-steps are accumulated until the total integration time equals the parent ELM time step: + +$$ +\sum \Delta t_{h3d} = \Delta t_{ELM} +$$ + + + ## Subsurface Runoff and Storage Change $$ @@ -228,297 +211,64 @@ $$ | Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | -# DrainageH3D → H3D_DRI → LateralResponse - -The h3D pathway computes (a) a **default topographic drainage propensity** from SIMTOP-style scalings, (b) a **within-landunit lateral response** by solving a **1-D hillslope Dupuit–Boussinesq** problem for saturated thickness, and (c) converts the updated saturated thickness to **subsurface runoff** and **diagnostics**. - ---- - -## 1. Area-Weighted Hillslope Inputs (per landunit \(l\)) - -$$ -r_{sub,\,top}^{default} -=\sum_{c=c_0}^{c_0+N-1} - tmp_{rsub,\,top}(c)\; hs_{dA}(l,\,c-c_0+1) -\qquad[\mathrm{m^3\,s^{-1}}] -$$ - -$$ -\overline{zwt}_{h3d} -=rac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - zwt_{h3d}(c)\; hs_{dA}(l,\,c-c_0+1) -\qquad[\mathrm{m}] -$$ - -$$ -\overline{r_{sub,\,top,\,h3d}^{max}} -=rac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - r_{sub,\,top,\,h3d}^{max}(c)\; hs_{dA}(l,\,c-c_0+1) -\qquad[\mathrm{m\,s^{-1}}] -$$ - -$$ -\overline{fff} -=rac{1}{hs_{area}(l)} - \sum_{c=c_0}^{c_0+N-1} - fff(c)\; hs_{dA}(l,\,c-c_0+1) -\qquad[\mathrm{m^{-1}}] -$$ - -$$ -r_{sub,\,top}^{default} -= -\overline{r_{sub,\,top,\,h3d}^{max}}\; -\exp\!\left(-\,\overline{fff}\;\overline{zwt}_{h3d} -ight)\; -hs_{area}(l) -\qquad[\mathrm{m^3\,s^{-1}}] -$$ - ---- - -## 2. Saturated Thickness and Bounds - -$$ -h_{sat}(c) \equiv z_{wt,\,bed}(c) - z_{wt}(c), -\qquad h_{sat}\ge 0 -\qquad[\mathrm{m}] -$$ - -$$ -z_{wt}(c) \in [\,0,\;z_{wt,\,bed}(c)\,],\quad -z_{wt,\,bed}(c)=egin{cases} -z_{ibed}(c), & ext{variable soil thickness}\ -z_{ibed}(c)+25\,\mathrm{m}, & ext{otherwise} -\end{cases} -$$ - -$$ -h_{sat}^{begin}(c)=z_{wt,\,bed}(c)-z_{wt}^{begin}(c) -$$ - ---- - -## 3. Specific Yield \(f_{ ext{drain}}\) (Brooks–Corey) - -Let \(idx=\min\{jwt(c)+1,\;n_{lev\,bed}(c)\}\). - -$$ -f_{drain}(c) -= -\max\!\left[ -0.02,\; - heta_{sat}(c,idx)\left( -1-\left( -1+rac{1000\;\max\!\{0,\;z_{wt,\,bed}(c)-h_{sat}(c)\}} -{\psi_{sat}(c,idx)} - -ight)^{-1/b(c,idx)} - -ight) - -ight] -\qquad[-] -$$ - ---- - -## 4. Transmissivity Along the Hillslope (Interface Form) - -For hillslope node \(k=1,\dots,N\) (lower boundary \(k=1\) at stream; upper \(k=N\) at divide), with anisotropy \(f_{aniso}=100\): - -$$ -wK\!H(k) -= -f_{aniso}\; -hs_{w,\,nod}(l,k)\; -rac{hk_{sat}(c_k,idx_k)}{1000}\; -h_{sat}^{prev}(k) -\qquad[\mathrm{m^3\,s^{-1}}] -$$ - -where \(c_k=c_0+k-1\) and \(idx_k=\min\{jwt(c_k)+1,\,n_{lev\,bed}(c_k)\}\). - ---- - -## 5. Discrete Hillslope PDE (Implicit, Tridiagonal in \(h_{sat}\)) - -Let \( heta_k = h3d\_slope(c_k)\cdot\pi/180\), and geometry \(hs_{dx}(l,k)\), \(hs_{dx,\,nod}(l,k)\), \(hs_{w,\,nod}(l,k)\). - -### 5.1 Interior Nodes \(k=2,\dots,N-1\) - -$$ -a_k -= -rac{wK\!H(k)\cos heta_k\;\Delta t_{h3d}} - {hs_{dx,\,nod}(l,k)\;hs_{dx}(l,k)\;hs_{w,\,nod}(l,k)}, -\qquad -c_k -= -rac{wK\!H(k+1)\cos heta_k\;\Delta t_{h3d}} - {hs_{dx,\,nod}(l,k+1)\;hs_{dx}(l,k)\;hs_{w,\,nod}(l,k)}, -$$ - -$$ -b_k = f_{drain}(c_k) - (a_k + c_k), -$$ - -$$ -r_k -= f_{drain}(c_k)\;h_{sat}^{old}(k) -+ rac{\Delta t_{h3d}\,\sin heta_k}{hs_{w,\,nod}(l,k)\;hs_{dx}(l,k)} - \Big[wK\!H(k+1) - wK\!H(k)\Big], -$$ - -$$ -a_k\,h_{sat}(k-1) + b_k\,h_{sat}(k) + c_k\,h_{sat}(k+1) = r_k. -$$ - -### 5.2 Lower Boundary \(k=1\) (Stream; Head-Dependent Outflow) - -$$ -a_1=0,\qquad -c_1 -= -rac{wK\!H(2)\cos heta_1\;\Delta t_{h3d}} - {hs_{dx,\,nod}(l,2)\;hs_{dx}(l,1)\;hs_{w,\,nod}(l,1)}, -$$ - -$$ -b_1=f_{drain}(c_1)-(a_1+c_1), -$$ - -$$ -r_1= -f_{drain}(c_1)\;h_{sat}^{old}(1) -+rac{\Delta t_{h3d}}{hs_{w,\,nod}(l,1)\;hs_{dx}(l,1)} -\left[ -\sin heta_1\;wK\!H(2) --rac{\cos heta_1}{hs_{dx}(l,1)} -\,hs_{w,\,nod}(l,1)\, -rac{f_{aniso}\,hk_{sat}(c_1,idx_1)}{1000}\,ig(h_{sat}^{prev}(1ig)^2 - -ight]. -$$ - -### 5.3 Upper Boundary \(k=N\) (Divide; No-Flow) - -$$ -a_N -= -rac{wK\!H(N)\cos heta_N\;\Delta t_{h3d}} - {hs_{dx,\,nod}(l,N)\;hs_{dx}(l,N)\;hs_{w,\,nod}(l,N)}, -\qquad -c_N=0, -$$ - -$$ -b_N=f_{drain}(c_N)-(a_N+c_N), -$$ - -$$ -r_N= -f_{drain}(c_N)\;h_{sat}^{old}(N) --rac{\Delta t_{h3d}\,\sin heta_N}{hs_{w,\,nod}(l,N)\;hs_{dx}(l,N)} -\,wK\!H(N). -$$ - ---- +## Subroutines and workflow -## 6. Linear Solve and Iteration +### DrainageH3D -### Tridiagonal System (Thomas Algorithm) +Top-level routine for h3D hydrology. +Responsible for preparing column-level variables (layer thickness, water table index, slope, conductivity), +computing area-weighted parameters, and calling the h3D solver (H3D_DRI). -$$ -a_k\,h_{sat}(k-1) + b_k\,h_{sat}(k) + c_k\,h_{sat}(k+1) = r_k, -\qquad k=1,\dots,N. -$$ +### H3D_DRI -### Picard Loop & Convergence +Performs the iterative time stepping of the hillslope system: -$$ -\max_{kig|h_{sat}^{(m+1)}(k)-h_{sat}^{(m)}(kig| -< h_{sat}^{thres}=10^{-4}\ \mathrm{m}. -$$ +- Initializes the saturated thickness $h_{sat}$ for each h3D column. -If not converged in \(n_{iter}^{max}\), halve \(\Delta t_{h3d}\) and retry: +- Computes area-weighted inputs (mean slope, width, transmissivity, decay factor). -$$ -\Delta t_{h3d}\leftarrow frac12\,\Delta t_{h3d}, -\qquad -\sum \Delta t_{h3d} = \Delta t_{\mathrm{ELM}}. -$$ +- Advances $h_{sat}$ over sub-steps by calling LateralResponse. -Recover water table: +- Converts changes in saturated storage to drainage flux: -$$ -z_{wt}(c_k) = z_{wt,\,bed}(c_k) - h_{sat}(k), +_{sat} = f_{drain}\,(h^{n+1} - h^{n}), \qquad -z_{wt}\in[0,\,80\,\mathrm{m}]\ ext{(clamp)}. +Q_{sub} = -\frac{\Delta S_{sat}}{\Delta t} $$ ---- +Outputs updated water-table depth and drainage rates (qflx_drain_h3d). -## 7. Storage Change and Subsurface Runoff (ELM Timestep \(\Delta t\)) +### LateralResponse -$$ -\Delta S_{sat}(c_k)= f_{drain}(c_k)\,\Big(h_{sat}(k)-h_{sat}^{begin}(k)\Big) -\qquad[\mathrm{m}], -$$ - -$$ -R_{sub}(c_k)= -\,\Delta S_{sat}(c_k)\qquad[\mathrm{m}], -\qquad -Q_{sub}(c_k)= rac{R_{sub}(c_k)}{\Delta t} imes 1000 -\qquad[\mathrm{mm\,s^{-1}}]. -$$ +Solves the implicit Dupuit–Boussinesq system for all h3D nodes in a landunit. +Constructs a tridiagonal matrix from the finite-difference discretization: $$ -qflx_{drain}(c_k) = Q_{sub}(c_k), -\qquad -qflx_{drain,\,h3d}(c_k)=Q_{sub}(c_k). +a_k\,h_{k-1} + b_k\,h_k + c_k\,h_{k+1} = r_k $$ ---- - -## 8. Coupling Back to Column Hydrology - -### Non-h3D (SIMTOP-like) +Steps: +- Computes node-specific yield $f_{drain}(c)$ and transmissivity $wK!H(k)$. -$$ -r_{sub,\,top}(c)= imped(c)\; r_{sub,\,top}^{max}(c)\; -\exp\ig(-\,fff(c)\,z_{wt}(cig) -\qquad[\mathrm{mm\,s^{-1}}]. -$$ - -### h3D Columns +- Applies slope-dependent flux terms and boundary conditions. -$$ -r_{sub,\,top}(c) = imped(c)\; qflx_{drain,\,h3d}(c) -\qquad[\mathrm{mm\,s^{-1}}]. -$$ +- Solves using the Thomas algorithm (Tridiagonal_h3D). -### Total Drainage +- Iterates until the solution converges (see § 5.2). -$$ -qflx_{drain}(c)= qflx_{rsub,\,sat}(c) + r_{sub,\,top}(c). -$$ +## Outputs ---- +After the h3D solve, the model provides: -## 9. Units and Conversions +- qflx_drain_h3d — subsurface (baseflow) drainage [mm s⁻¹] -$$ -hk_{sat}\,[\mathrm{mm\,s^{-1}}] \ -ightarrow\ \mathrm{m\,s^{-1}} ext{ via } /1000, -\qquad -Q\,[\mathrm{m\,s^{-1}}] \ -ightarrow\ \mathrm{mm\,s^{-1}} ext{ via } imes 1000. -$$ +- qflx_rsub_sat_h3d — saturation-excess runoff [mm s⁻¹] ---- +- zwt_h3d — updated water-table depth [m] -## 10. Indices and Mappings +- f_drain — variable specific yield [–] -- Node \(k\) ↔ column \(c_k=c_0+k-1\), \(k=1,\dots,N=nh3dc\_{per\_lunit}\). -- \(jwt(c)\) is the index above the water table; \(idx=\min(jwt+1,n_{lev\,bed})\). -- \( heta_k\) uses degrees in code; equations use radians. +- ΔS_sat — change in saturated storage [m] +These outputs replace or augment SIMTOP drainage for h3D-active columns and are fed into the land surface, + biogeochemical, and river-routing components of ELM. From a3a5140edbfb0d418c6058cc592f97b66cc142a9 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 14:14:39 -0700 Subject: [PATCH 28/42] update --- components/elm/docs/tech-guide/h3d.md | 50 ++++++--------------------- 1 file changed, 10 insertions(+), 40 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 826cf65bf519..f103764d9457 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -54,6 +54,13 @@ $T(x,h)$ is the transmissivity [m² s⁻¹], $\theta$ is the hillslope angle [rad], and $R$ is the recharge rate [m s⁻¹]. +## Boundary Conditions + +| Boundary | Condition | Implementation | +| :------------- | :------------------------------------ | :----------------------- | +| Lower (stream) | Head-dependent outflow | Robin-type term in $r_1$ | +| Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | + ## Constitutive Relationships ### Transmissivity @@ -69,7 +76,7 @@ $K_{\text{sat}}(z_{wt})$ is the saturated hydraulic conductivity at the water-table depth [mm s⁻¹], and $w(x)$ is the hillslope width [m]. Division by 1000 converts from mm s⁻¹ to m s⁻¹. -## Variable Drainable Porosity +### Variable Drainable Porosity The specific yield varies with depth following a Brooks–Corey relation: @@ -157,9 +164,7 @@ $$ \sum \Delta t_{h3d} = \Delta t_{ELM} $$ - - -## Subsurface Runoff and Storage Change +### Subsurface Runoff and Storage Change $$ \Delta S_{\text{sat},i} @@ -176,41 +181,6 @@ $$ z_{wt,i} = z_{\text{bed},i} - h_i $$ -Adaptive time-stepping: - -$$ -\Delta t_{\text{new}} = 0.5\,\Delta t_{\text{old}} -$$ - - -## Tridiagonal Matrix Solution - -Forward elimination: - -$$ -\begin{aligned} -\beta_1 &= b_1, \quad \tilde{r}_1 = \frac{r_1}{\beta_1}, \\ -\gamma_i &= \frac{c_{i-1}}{\beta_{i-1}}, \\ -\beta_i &= b_i - a_i\gamma_i, \\ -\tilde{r}_i &= \frac{r_i - a_i\tilde{r}_{i-1}}{\beta_i}, \quad (i=2,\dots,N) -\end{aligned} -$$ - -Back substitution: - -$$ -h_N = \tilde{r}_N, \qquad -h_i = \tilde{r}_i - \gamma_{i+1} h_{i+1}, \quad (i=N-1,\dots,1) -$$ - -## Boundary Conditions - -| Boundary | Condition | Implementation | -| :------------- | :------------------------------------ | :----------------------- | -| Lower (stream) | Head-dependent outflow | Robin-type term in $r_1$ | -| Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | - - ## Subroutines and workflow ### DrainageH3D @@ -244,7 +214,7 @@ Solves the implicit Dupuit–Boussinesq system for all h3D nodes in a landunit. Constructs a tridiagonal matrix from the finite-difference discretization: $$ -a_k\,h_{k-1} + b_k\,h_k + c_k\,h_{k+1} = r_k +a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i $$ Steps: From 738bd1e4be5047dcd52f2854c16dadbcba798256 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 14:41:59 -0700 Subject: [PATCH 29/42] update --- components/elm/docs/tech-guide/h3d.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index f103764d9457..a923a0e64552 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -18,6 +18,20 @@ Each land unit is subdivided into several h3D columns positioned along an ideali - Upper boundary represents the local topographic divide. - Intermediate nodes represent soil columns along the slope. +![Image title](../figures/h3d_schematic.jpg) + +Figure 1. The hybrid-3D hillslope hydrological model represents subsurface and surface flow along an idealized hillslope. Left panel (plan view): +A hillslope of total length $L$ is divided into $N$ vertical soil columns, each with an equal horizontal length $\Delta x$, underlain by bedrock with a topographic slope $\alpha$. +The width of the hillslope at a given position is denoted by $W(x)$, measured from the lower boundary of the lowest column (column 0). +The column index $j$ refers to the center of each hillslope column. +Land-surface properties such as bedrock depth, vegetation cover, and atmospheric forcing are assumed to be identical for all columns. +The variable $d$ represents the depth of overland flow above the surface. Right panel (vertical section): +Each hillslope column consists of multiple soil layers of variable thickness $\Delta z_i$. +Vertical flow through the unsaturated and saturated zones occurs across these layers with corresponding soil water potentials $\psi_i$. +The flow domain extends down to an impermeable bedrock boundary, which imposes a zero-flux condition at the bottom. +Vertical flow is solved using the $\theta$-based form of the Richards equation (Zeng & Decker, 2009). +The layer index $i$ denotes vertical soil layers, $h$ is the height of the saturation zone, and $\nabla$ marks the position of the water table. + For each node, the state variable is the saturated thickness, $h_{sat}(x,t)$, measured from the bedrock to the water table. The model tracks how $h_{sat}(x,t)$ evolves in time due to: From d7ebf4cdfb57d25908a5f12862a2a6a2c4c80850 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 14:42:12 -0700 Subject: [PATCH 30/42] update --- components/elm/docs/figures/h3d_schematic.jpg | Bin 0 -> 306241 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100755 components/elm/docs/figures/h3d_schematic.jpg diff --git a/components/elm/docs/figures/h3d_schematic.jpg b/components/elm/docs/figures/h3d_schematic.jpg new file mode 100755 index 0000000000000000000000000000000000000000..e8171d688e699754f96dc64c4f6ca7f09f3304bb GIT binary patch literal 306241 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�{b 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

OmCtj016$Oq<$TkNV>y@i&k-Q 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ΜUXgSx=xgD-a(we*#$7rx5JO2PE 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®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 Ay8r+H literal 0 HcmV?d00001 From 7e6eb9f7be8dad80d1d03f090b2f9b1a5ca1f34d Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 20:21:27 -0700 Subject: [PATCH 31/42] update --- components/elm/docs/tech-guide/h3d.md | 49 ++++++++++++++++++++------- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index a923a0e64552..bb693d0f5207 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -10,6 +10,15 @@ This approach is conceptually one-dimensional along the hillslope, but retains three-dimensional realism by including slope, width, and drainage area variation. The model solves the Dupuit–Boussinesq groundwater flow equation for saturated thickness using an implicit finite-difference method. +In order to use this model, the following variables need to be added in the surface dataset: + +hs_x(begg:endg, 1:nh3dc_per_lunit+1): x‐coordinates (m) of the node/edge positions along the hillslope for each grid cell g. There are N+1 nodes for N columns. + +hs_w(begg:endg, 1:nh3dc_per_lunit+1): width function values (m) at those nodes (planform width vs. distance). + +hs_area(1:nh3dc_per_lunit): Planform area between nodes k and k+1 is calculated using a trapezoid, area each column are then normalized to the total area and used later for area-weighted averages/sums across the set of hillslope columns +within a land unit (e.g., to compute landunit-level means of fluxes or states). + ## Conceptual Representation Each land unit is subdivided into several h3D columns positioned along an idealized hillslope: @@ -59,7 +68,7 @@ Land unit captures the hillsclope-scale connectivity, while columns capture spat The fundamental PDE is a Dupuit-style Boussinesq groundwater flow equation for saturated flow along the slope: $$ -\frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial }\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} +\frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial x}\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} $$ where $h(x,t)$ is the saturated thickness [m], @@ -82,7 +91,7 @@ and $R$ is the recharge rate [m s⁻¹]. The local transmissivity depends on saturated thickness and anisotropy: $$ -T(x,h)= \frac{K_{\text{aniso}}\,K_{\text{sat}}(z_{wt})\,h\,w(x)}{1000} +T(x,h)= \frac{K_{\text{aniso}}K_{\text{sat}}(z_{wt})h w(x)}{1000} $$ where $K_{\text{aniso}}=100$ is the horizontal/vertical anisotropy factor, @@ -127,20 +136,37 @@ $$ a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i $$ +Lower boundary ($i=1$, stream) + +$$ +\begin{aligned} +a_1 &= 0, \\ +c_1 &= -\frac{T_{3/2}^n \cos\theta \Delta t} + {\Delta x_{3/2}\Delta x_1 w_1}, \\ +b_1 &= f_{\text{drain},1} - c_1, \\ +r_1 &= f_{\text{drain},1} h_1^n + + \frac{\Delta t}{w_1\Delta x_1} + \left[ + \sin\theta T_{3/2}^n + - \frac{\cos\theta}{\Delta x_1} + w_1 K_{\text{aniso}} + \frac{K_{\text{sat},1}}{1000}(h_1^n)^2 + \right] +\end{aligned} +$$ Interior nodes ($i=2,\dots,N-1$) $$ \begin{aligned} -a_i &= -\frac{T_{i-\frac12}^n \cos\theta \,\Delta t} - {\Delta x_{i-\frac12}\,\Delta x_i\,w_i}, \\ -c_i &= -\frac{T_{i+\frac12}^n \cos\theta \,\Delta t} - {\Delta x_{i+\frac12}\,\Delta x_i\,w_i}, \\ +a_i &= -\frac{T_{i}^n \cos\theta \Delta t} + {\Delta x_{i}\Delta x_i w_i}, \\ +c_i &= -\frac{T_{i+1}^n \cos\theta \Delta t} + {\Delta x_{i+1}\,\Delta x_i w_i}, \\ b_i &= f_{\text{drain},i} - (a_i + c_i), \\ r_i &= f_{\text{drain},i} h_i^n + \frac{\Delta t\sin\theta}{w_i\Delta x_i} - (T_{i+\frac12}^n - T_{i-\frac12}^n) - + \Delta t R_i. + (T_{i+1}^n - T_{i}^n) \end{aligned} $$ @@ -148,13 +174,12 @@ Upper boundary ($i=N$, divide) $$ \begin{aligned} -a_N &= -\frac{T_{N-\frac12}^n \cos\theta \,\Delta t} - {\Delta x_{N-\frac12}\,\Delta x_N\,w_N}, \\ +a_N &= -\frac{T_{N}^n \cos\theta \Delta t} + {\Delta x_{N} \Delta x_N w_N}, \\ c_N &= 0, \\ b_N &= f_{\text{drain},N} - a_N, \\ r_N &= f_{\text{drain},N} h_N^n - - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N-\frac12}^n - + \Delta t R_N. + - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N}^n \end{aligned} $$ From e5fa17f38d2a04b8d0b09b9bb2a7fbbafe6f0c6d Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Tue, 21 Oct 2025 21:42:09 -0700 Subject: [PATCH 32/42] update --- components/elm/docs/tech-guide/h3d.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index bb693d0f5207..09693260c9e8 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -91,7 +91,7 @@ and $R$ is the recharge rate [m s⁻¹]. The local transmissivity depends on saturated thickness and anisotropy: $$ -T(x,h)= \frac{K_{\text{aniso}}K_{\text{sat}}(z_{wt})h w(x)}{1000} +T(x,h)= \frac{K_{\text{aniso}}K_{\text{sat}}(z_{wt}) \ h \ w(x)}{1000} $$ where $K_{\text{aniso}}=100$ is the horizontal/vertical anisotropy factor, @@ -110,7 +110,7 @@ f_{\text{drain}} 1 - \left( 1 + -\frac{1000\,\max(0,\,z_{\text{bed}}-h)}{\psi_{\text{sat}}} +\frac{1000\,\max(0,z_{\text{bed}}-h)}{\psi_{\text{sat}}} \right)^{-1/b} \right], \qquad @@ -141,13 +141,13 @@ Lower boundary ($i=1$, stream) $$ \begin{aligned} a_1 &= 0, \\ -c_1 &= -\frac{T_{3/2}^n \cos\theta \Delta t} - {\Delta x_{3/2}\Delta x_1 w_1}, \\ +c_1 &= -\frac{T_{3/2}^n \cos\theta \ \Delta t} + {\Delta x_{3/2}\,\Delta x_1\ w_1}, \\ b_1 &= f_{\text{drain},1} - c_1, \\ r_1 &= f_{\text{drain},1} h_1^n + \frac{\Delta t}{w_1\Delta x_1} \left[ - \sin\theta T_{3/2}^n + \sin\theta\,T_{3/2}^n - \frac{\cos\theta}{\Delta x_1} w_1 K_{\text{aniso}} \frac{K_{\text{sat},1}}{1000}(h_1^n)^2 @@ -159,14 +159,14 @@ Interior nodes ($i=2,\dots,N-1$) $$ \begin{aligned} -a_i &= -\frac{T_{i}^n \cos\theta \Delta t} - {\Delta x_{i}\Delta x_i w_i}, \\ -c_i &= -\frac{T_{i+1}^n \cos\theta \Delta t} - {\Delta x_{i+1}\,\Delta x_i w_i}, \\ +a_i &= -\frac{T_{i-\frac12}^n \cos\theta \ \Delta t} + {\Delta x_{i-\frac12}\ \Delta x_i\ w_i}, \\ +c_i &= -\frac{T_{i+\frac12}^n \cos\theta \ \Delta t} + {\Delta x_{i+\frac12}\ \Delta x_i\ w_i}, \\ b_i &= f_{\text{drain},i} - (a_i + c_i), \\ r_i &= f_{\text{drain},i} h_i^n + \frac{\Delta t\sin\theta}{w_i\Delta x_i} - (T_{i+1}^n - T_{i}^n) + (T_{i+\frac12}^n - T_{i-\frac12}^n) \end{aligned} $$ @@ -174,12 +174,12 @@ Upper boundary ($i=N$, divide) $$ \begin{aligned} -a_N &= -\frac{T_{N}^n \cos\theta \Delta t} - {\Delta x_{N} \Delta x_N w_N}, \\ +a_N &= -\frac{T_{N-\frac12}^n \cos\theta \ \Delta t} + {\Delta x_{N-\frac12}\ \Delta x_N\ w_N}, \\ c_N &= 0, \\ b_N &= f_{\text{drain},N} - a_N, \\ r_N &= f_{\text{drain},N} h_N^n - - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N}^n + - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N-\frac12}^n \end{aligned} $$ From e0c0d7b73604fed87e4099e3779bbfaa93326ce0 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 10:12:15 -0700 Subject: [PATCH 33/42] update --- components/elm/docs/tech-guide/h3d.md | 110 +++++++++++++++++++++++--- 1 file changed, 98 insertions(+), 12 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 09693260c9e8..3041c61d6d28 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -53,7 +53,7 @@ Each land unit represents a single hillslope, which has consistent topographic a - **Overall slope angle:** $\theta$ — mean hillslope angle (rad) - **Width function:** $w(x)$ — lateral width distribution along the hillslope (m) - **Distance function:** $x(i)$ — distance from the stream outlet to node $i$ (m) -- **Total hillslope area:** $A_{hs} = \displaystyle \int_0^L w(x)\,dx$ (m²) +- **Total hillslope area:** $A_{hs} = \displaystyle \int_0^L w(x)\ dx$ (m²) Each column is a point along hillslope, representing a cross-section at distance x along the hillslope. Each has local properties, connected by lateral flow to adjacent columns: - Soil hydraulic properties (K_sat, porosity, etc.) @@ -75,14 +75,14 @@ where $h(x,t)$ is the saturated thickness [m], $f_{\text{drain}}$ is the drainable porosity [–], $T(x,h)$ is the transmissivity [m² s⁻¹], $\theta$ is the hillslope angle [rad], -and $R$ is the recharge rate [m s⁻¹]. +and $R$ is the recharge rate [m s⁻¹]. Note - recharge rate was not in the code. ## Boundary Conditions -| Boundary | Condition | Implementation | -| :------------- | :------------------------------------ | :----------------------- | -| Lower (stream) | Head-dependent outflow | Robin-type term in $r_1$ | -| Upper (divide) | No-flow ($\partial h/\partial x = 0$) | Set $c_N = 0$ | +| Boundary | Condition | +| :------------- | :------------------------------------ | +| Lower (stream) | $\partial h/\partial x = 0$ | +| Upper (divide) | zero lateral flow | ## Constitutive Relationships @@ -110,7 +110,7 @@ f_{\text{drain}} 1 - \left( 1 + -\frac{1000\,\max(0,z_{\text{bed}}-h)}{\psi_{\text{sat}}} +\frac{1000\ \max(0,z_{\text{bed}}-h)}{\psi_{\text{sat}}} \right)^{-1/b} \right], \qquad @@ -130,24 +130,110 @@ This function allows for a smooth transition between unsaturated and fully satur ### Spatial Discretization The PDE is solved implicitly in space and time using a tridiagonal -system for $h_i^{n+1}$ at each node $i$: +system for $h_i^{n+1}$ at each node $i$. Node is ordered from 1 to N: $$ a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i $$ +#### Derivation + +- Lower boundary ($i=1$, stream) + +$$ +\begin{aligned} +f\left(h_{1}^{t,s+1}-h_{1}^{t-1}\right) +&= \frac{\Delta T\,\sin(\alpha)}{w_{1}\,\Delta x_{1}} +\left(w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}\right) \\ +&\quad + \frac{\Delta T\,\cos(\alpha)}{w_{1}\,\Delta x_{1}} +\left( +\frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_{1}}} +\left(h_{2}^{t,s+1}-h_{1}^{t,s+1}\right) +\right) \\ +&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},1}^{t}\,. +\end{aligned} +$$ +$$ +\begin{aligned} +&a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 \\[0.5em] +&\text{where:} \\ +&a_1 = 0 \\ +&b_1 = f + \frac{\Delta T\,\cos(\alpha)}{w_1\,\Delta x_1} \cdot \frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&c_1 = -\frac{\Delta T\,\cos(\alpha)}{w_1\,\Delta x_1} \cdot \frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&r_1 = f h_1^{t-1} + \frac{\Delta T\,\sin(\alpha)}{w_1\,\Delta x_1}\left(w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}\right) + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},1}^{t} +\end{aligned} +$$ + +- Interior nodes ($i=2,\dots,N-1$) + +$$ +\begin{aligned} +f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) +&= \frac{\Delta T\,\sin(\alpha)}{w_{i}\,\Delta x_{i}} +\left(w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s} + - w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \frac{\Delta T\,\cos(\alpha)}{w_{i}\,\Delta x_{i}} +\left( +\frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_{i}}} +\left(h_{i+1}^{t,s+1}-h_{i}^{t,s+1}\right) \right. \\ +&\qquad \left. - \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_{i}}} +\left(h_{i}^{t,s+1}-h_{i-1}^{t,s+1}\right) +\right) \\ +&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},i}^{t}\,. +\end{aligned} +$$ +$$ +\begin{aligned} +&a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i \\[0.5em] +&\text{where:} \\ +&a_i = \frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \cdot \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \\ +&b_i = f + \frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \left( \frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} + \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \right) \\ +&c_i = -\frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \cdot \frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} \\ +&r_i = f h_i^{t-1} + \frac{\Delta T\,\sin(\alpha)}{w_i\,\Delta x_i} \left(w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s} - w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},i}^{t} +\end{aligned} +$$ + +- Upper boundary ($i=N$, divide) + +$$ +\begin{aligned} +f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) +&= -\frac{\Delta T\,\sin(\alpha)}{w_{N}\,\Delta x_{N}} +\left(w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}\right) \\ +&\quad -\frac{\Delta T\,\cos(\alpha)}{w_{N}\,\Delta x_{N}} +\left( +\frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_{N}}} +\left(h_{N}^{t,s+1}-h_{N-1}^{t,s+1}\right) +\right) \\ +&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},N}^{t}\,. +\end{aligned} +$$ +$$ +\begin{aligned} +&a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N \\[0.5em] +&\text{where:} \\ +&a_N = -\frac{\Delta T\,\cos(\alpha)}{w_N\,\Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&b_N = f + \frac{\Delta T\,\cos(\alpha)}{w_N\,\Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&c_N = 0 \\ +&r_N = f h_N^{t-1} - \frac{\Delta T\,\sin(\alpha)}{w_N\,\Delta x_N}\left(w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}\right) + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},N}^{t} +\end{aligned} +$$ + +## IMPLEMENTATION FROM THE CODE + Lower boundary ($i=1$, stream) $$ \begin{aligned} a_1 &= 0, \\ c_1 &= -\frac{T_{3/2}^n \cos\theta \ \Delta t} - {\Delta x_{3/2}\,\Delta x_1\ w_1}, \\ + {\Delta x_{3/2}\ \Delta x_1\ w_1}, \\ b_1 &= f_{\text{drain},1} - c_1, \\ r_1 &= f_{\text{drain},1} h_1^n + \frac{\Delta t}{w_1\Delta x_1} \left[ - \sin\theta\,T_{3/2}^n + \sin\theta\ T_{3/2}^n - \frac{\cos\theta}{\Delta x_1} w_1 K_{\text{aniso}} \frac{K_{\text{sat},1}}{1000}(h_1^n)^2 @@ -194,7 +280,7 @@ $$ If convergence fails, the time step is halved adaptively. $$ -\Delta t_{h3d}^{new} = 0.5\,\Delta t_{h3d}^{old} +\Delta t_{h3d}^{new} = 0.5\ \Delta t_{h3d}^{old} $$ Sub-steps are accumulated until the total integration time equals the parent ELM time step: @@ -240,7 +326,7 @@ Performs the iterative time stepping of the hillslope system: - Converts changes in saturated storage to drainage flux: -_{sat} = f_{drain}\,(h^{n+1} - h^{n}), +_{sat} = f_{drain}\ (h^{n+1} - h^{n}), \qquad Q_{sub} = -\frac{\Delta S_{sat}}{\Delta t} $$ From 2fe37f614210358f52372d36e5e3684f209fb133 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 10:59:26 -0700 Subject: [PATCH 34/42] update --- components/elm/docs/tech-guide/h3d.md | 63 ++++++++++++++------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 3041c61d6d28..25e0e4588a36 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -143,24 +143,24 @@ $$ $$ \begin{aligned} f\left(h_{1}^{t,s+1}-h_{1}^{t-1}\right) -&= \frac{\Delta T\,\sin(\alpha)}{w_{1}\,\Delta x_{1}} -\left(w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}\right) \\ -&\quad + \frac{\Delta T\,\cos(\alpha)}{w_{1}\,\Delta x_{1}} +&= \frac{\Delta T\ \sin(\alpha)}{w_{1}\ \Delta x_{1}} +\left(w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}\right) \\ +&\quad + \frac{\Delta T\ \cos(\alpha)}{w_{1}\ \Delta x_{1}} \left( -\frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_{1}}} +\frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_{1}}} \left(h_{2}^{t,s+1}-h_{1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},1}^{t}\,. +&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t}\ . \end{aligned} $$ $$ \begin{aligned} -&a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 \\[0.5em] +&a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 \\ &\text{where:} \\ &a_1 = 0 \\ -&b_1 = f + \frac{\Delta T\,\cos(\alpha)}{w_1\,\Delta x_1} \cdot \frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ -&c_1 = -\frac{\Delta T\,\cos(\alpha)}{w_1\,\Delta x_1} \cdot \frac{w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ -&r_1 = f h_1^{t-1} + \frac{\Delta T\,\sin(\alpha)}{w_1\,\Delta x_1}\left(w_{\frac{3}{2}}\,k_{l_{\frac{3}{2}}}^{t,s}\,h_{\frac{3}{2}}^{t,s}\right) + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},1}^{t} +&b_1 = f + \frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&c_1 = -\frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&r_1 = f h_1^{t-1} + \frac{\Delta T\ \sin(\alpha)}{w_1\ \Delta x_1}\left(w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}\right) + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t} \end{aligned} $$ @@ -169,28 +169,29 @@ $$ $$ \begin{aligned} f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) -&= \frac{\Delta T\,\sin(\alpha)}{w_{i}\,\Delta x_{i}} -\left(w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s} - - w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}\right) \\ -&\quad + \frac{\Delta T\,\cos(\alpha)}{w_{i}\,\Delta x_{i}} +&= \frac{\Delta T\ \sin(\alpha)}{w_{i}\ \Delta x_{i}} +\left(w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s} + - w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \frac{\Delta T\ \cos(\alpha)}{w_{i}\ \Delta x_{i}} \left( -\frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_{i}}} +\frac{w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_{i}}} \left(h_{i+1}^{t,s+1}-h_{i}^{t,s+1}\right) \right. \\ -&\qquad \left. - \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_{i}}} +&\qquad \left. - \frac{w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_{i}}} \left(h_{i}^{t,s+1}-h_{i-1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},i}^{t}\,. +&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},i}^{t}\ . \end{aligned} $$ + $$ \begin{aligned} -&a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i \\[0.5em] +&a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j \\ &\text{where:} \\ -&a_i = \frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \cdot \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \\ -&b_i = f + \frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \left( \frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} + \frac{w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \right) \\ -&c_i = -\frac{\Delta T\,\cos(\alpha)}{w_i\,\Delta x_i} \cdot \frac{w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} \\ -&r_i = f h_i^{t-1} + \frac{\Delta T\,\sin(\alpha)}{w_i\,\Delta x_i} \left(w_{i+\frac{1}{2}}\,k_{l_{i+\frac{1}{2}}}^{t,s}\,h_{i+\frac{1}{2}}^{t,s} - w_{i-\frac{1}{2}}\,k_{l_{i-\frac{1}{2}}}^{t,s}\,h_{i-\frac{1}{2}}^{t,s}\right) \\ -&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},i}^{t} +&a_j = \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ +&b_j = f + \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ +&c_j = -\frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} \\ +&r_j = f h_j^{t-1} + \frac{\Delta T\ \sin(\alpha)}{w_j\ \Delta x_j} \left(w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s} - w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},j}^{t} \end{aligned} $$ @@ -199,24 +200,24 @@ $$ $$ \begin{aligned} f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) -&= -\frac{\Delta T\,\sin(\alpha)}{w_{N}\,\Delta x_{N}} -\left(w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}\right) \\ -&\quad -\frac{\Delta T\,\cos(\alpha)}{w_{N}\,\Delta x_{N}} +&= -\frac{\Delta T\ \sin(\alpha)}{w_{N}\ \Delta x_{N}} +\left(w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}\right) \\ +&\quad -\frac{\Delta T\ \cos(\alpha)}{w_{N}\ \Delta x_{N}} \left( -\frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_{N}}} +\frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_{N}}} \left(h_{N}^{t,s+1}-h_{N-1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},N}^{t}\,. +&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t}\ . \end{aligned} $$ $$ \begin{aligned} -&a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N \\[0.5em] +&a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N \\ &\text{where:} \\ -&a_N = -\frac{\Delta T\,\cos(\alpha)}{w_N\,\Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ -&b_N = f + \frac{\Delta T\,\cos(\alpha)}{w_N\,\Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&a_N = -\frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&b_N = f + \frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ &c_N = 0 \\ -&r_N = f h_N^{t-1} - \frac{\Delta T\,\sin(\alpha)}{w_N\,\Delta x_N}\left(w_{N-\frac{1}{2}}\,k_{l_{N-\frac{1}{2}}}^{t,s}\,h_{N-\frac{1}{2}}^{t,s}\right) + \Delta T\,\cos(\alpha)\,R_{\mathrm{sat},N}^{t} +&r_N = f h_N^{t-1} - \frac{\Delta T\ \sin(\alpha)}{w_N\ \Delta x_N}\left(w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}\right) + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t} \end{aligned} $$ From e7ca993920aaf102d2ea0bf58cd61e44a4bbd16c Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 11:10:41 -0700 Subject: [PATCH 35/42] update --- components/elm/docs/tech-guide/h3d.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 25e0e4588a36..f80667d23be4 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -133,9 +133,11 @@ The PDE is solved implicitly in space and time using a tridiagonal system for $h_i^{n+1}$ at each node $i$. Node is ordered from 1 to N: $$ -a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i +a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i^{t,s} $$ +where t and t-1 are current and previous time step, s+1 and s are current and previous iteration. + #### Derivation - Lower boundary ($i=1$, stream) @@ -153,6 +155,10 @@ f\left(h_{1}^{t,s+1}-h_{1}^{t-1}\right) &\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t}\ . \end{aligned} $$ + +\\ +\\ + $$ \begin{aligned} &a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 \\ @@ -164,6 +170,7 @@ $$ \end{aligned} $$ + - Interior nodes ($i=2,\dots,N-1$) $$ @@ -183,6 +190,9 @@ f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) \end{aligned} $$ +\\ +\\ + $$ \begin{aligned} &a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j \\ @@ -210,6 +220,10 @@ f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) &\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t}\ . \end{aligned} $$ + +\\ +\\ + $$ \begin{aligned} &a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N \\ @@ -221,6 +235,12 @@ $$ \end{aligned} $$ + +Where \Delta x_{U_{1} is +where {\Delta T} (seconds) is the h3d time step, i is the lateral node number. {\Delta x_{U_i}} and {\Delta x_{L_i}} are the distance (m) relative to the center of upper i + 1 +and lower i − 1 node. {w_i} is the width on the center of node i. i − {\frac{1}{2}} and i + {\frac{1}{2}} represent the lower and upper bounds of node i. + + ## IMPLEMENTATION FROM THE CODE Lower boundary ($i=1$, stream) From 0b5a6fdd8733ecd3dfbb2661434b0c302fcdef52 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 11:13:11 -0700 Subject: [PATCH 36/42] update --- components/elm/docs/tech-guide/h3d.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index f80667d23be4..ae0c3a9d6613 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -190,12 +190,12 @@ f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) \end{aligned} $$ -\\ \\ $$ \begin{aligned} &a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j \\ +\\ &\text{where:} \\ &a_j = \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ &b_j = f + \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ @@ -222,11 +222,13 @@ f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) $$ \\ -\\ + +$$ +a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N +$$ $$ \begin{aligned} -&a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N \\ &\text{where:} \\ &a_N = -\frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ &b_N = f + \frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ From 09fa05d44636e3091ab1ac9ae789c1a6a56557ff Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 11:18:02 -0700 Subject: [PATCH 37/42] update --- components/elm/docs/tech-guide/h3d.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index ae0c3a9d6613..e9e78b27bb68 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -156,13 +156,13 @@ f\left(h_{1}^{t,s+1}-h_{1}^{t-1}\right) \end{aligned} $$ -\\ -\\ +$$ +a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 +$$ +where $$ \begin{aligned} -&a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 \\ -&\text{where:} \\ &a_1 = 0 \\ &b_1 = f + \frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ &c_1 = -\frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ @@ -190,12 +190,13 @@ f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) \end{aligned} $$ -\\ + +$$ +a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j +$$ $$ \begin{aligned} -&a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j \\ -\\ &\text{where:} \\ &a_j = \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ &b_j = f + \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ @@ -221,7 +222,6 @@ f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) \end{aligned} $$ -\\ $$ a_N h_{N-1}^{t,s+1} + b_N h_N^{t,s+1} + c_N h_{N+1}^{t,s+1} = r_N From e50849a9ac9ed27e2e74bc3724ea80a4b8b7c9ca Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 11:49:39 -0700 Subject: [PATCH 38/42] update --- components/elm/docs/tech-guide/h3d.md | 55 +++++++++++++-------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index e9e78b27bb68..6ef7e173f435 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -38,7 +38,7 @@ The variable $d$ represents the depth of overland flow above the surface. Right Each hillslope column consists of multiple soil layers of variable thickness $\Delta z_i$. Vertical flow through the unsaturated and saturated zones occurs across these layers with corresponding soil water potentials $\psi_i$. The flow domain extends down to an impermeable bedrock boundary, which imposes a zero-flux condition at the bottom. -Vertical flow is solved using the $\theta$-based form of the Richards equation (Zeng & Decker, 2009). +Vertical flow is solved using the $\alpha$-based form of the Richards equation (Zeng & Decker, 2009). The layer index $i$ denotes vertical soil layers, $h$ is the height of the saturation zone, and $\nabla$ marks the position of the water table. For each node, the state variable is the saturated thickness, $h_{sat}(x,t)$, measured from the bedrock to the water table. @@ -50,7 +50,7 @@ The model tracks how $h_{sat}(x,t)$ evolves in time due to: Each land unit represents a single hillslope, which has consistent topographic and geometric properties: -- **Overall slope angle:** $\theta$ — mean hillslope angle (rad) +- **Overall slope angle:** $\alpha$ — mean hillslope angle (rad) - **Width function:** $w(x)$ — lateral width distribution along the hillslope (m) - **Distance function:** $x(i)$ — distance from the stream outlet to node $i$ (m) - **Total hillslope area:** $A_{hs} = \displaystyle \int_0^L w(x)\ dx$ (m²) @@ -68,14 +68,13 @@ Land unit captures the hillsclope-scale connectivity, while columns capture spat The fundamental PDE is a Dupuit-style Boussinesq groundwater flow equation for saturated flow along the slope: $$ -\frac{\partial h}{\partial t} = \frac{1}{f_{\text{drain}}} \frac{\partial}{\partial x} \left[ T(x,h)\left(\frac{\partial h}{\partial x}\cos\theta + \sin\theta\right)\right]+ \frac{R}{f_{\text{drain}}} +f\frac{\partial h}{\partial t} = \frac{1}{w}\frac{\partial}{\partial x}\left(w\ k_{l}(h)\ h\left(\sin(\alpha) + \frac{\partial h}{\partial x}\cos(\alpha)\right)\right) + \cos(\alpha)\ R} $$ where $h(x,t)$ is the saturated thickness [m], $f_{\text{drain}}$ is the drainable porosity [–], -$T(x,h)$ is the transmissivity [m² s⁻¹], -$\theta$ is the hillslope angle [rad], -and $R$ is the recharge rate [m s⁻¹]. Note - recharge rate was not in the code. +$\alpha$ is the hillslope angle [rad], +w (m) is the width of the hillslope at a given distance x (m) from the outflow point, kl(h) (m/s) is the lateral saturated hydraulic conductivity at height h. $R$ is the recharge rate between the unsaturated and saturated zones (m/s). Note - recharge rate was not in the code. ## Boundary Conditions @@ -84,7 +83,7 @@ and $R$ is the recharge rate [m s⁻¹]. Note - recharge rate was not in the co | Lower (stream) | $\partial h/\partial x = 0$ | | Upper (divide) | zero lateral flow | -## Constitutive Relationships +## Constitutive Relationships (from the code) ### Transmissivity @@ -105,7 +104,7 @@ The specific yield varies with depth following a Brooks–Corey relation: $$ f_{\text{drain}} -= \theta_{\text{sat}} += \alpha_{\text{sat}} \left[ 1 - \left( @@ -117,7 +116,7 @@ f_{\text{drain}} f_{\text{drain}}\ge0.02 $$ -where $\theta_{\text{sat}}$ is porosity [–], +where $\alpha_{\text{sat}}$ is porosity [–], $z_{\text{bed}}$ is bedrock depth [m], $\psi_{\text{sat}}$ is air-entry suction [mm], and $b$ is the Brooks–Corey pore-size index [–]. @@ -160,9 +159,9 @@ $$ a_1 h_0^{t,s+1} + b_1 h_1^{t,s+1} + c_1 h_2^{t,s+1} = r_1 $$ -where $$ \begin{aligned} +&\text{where:} \\ &a_1 = 0 \\ &b_1 = f + \frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ &c_1 = -\frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ @@ -245,21 +244,21 @@ and lower i − 1 node. {w_i} is the width on the center of node i. i − {\frac ## IMPLEMENTATION FROM THE CODE -Lower boundary ($i=1$, stream) +Lower boundary ($i=1$, stream) (NOT SURE HOW THE LAST TERM IN $r_1$ WAS DERIVED) $$ \begin{aligned} a_1 &= 0, \\ -c_1 &= -\frac{T_{3/2}^n \cos\theta \ \Delta t} - {\Delta x_{3/2}\ \Delta x_1\ w_1}, \\ +c_1 &= -\frac{T_{3/2}^{s-1} \cos\alpha \ \Delta t} + {\Delta x_{U_i}\ \Delta x_1\ w_1}, \\ b_1 &= f_{\text{drain},1} - c_1, \\ -r_1 &= f_{\text{drain},1} h_1^n +r_1 &= f_{\text{drain},1} h_1^{s-1} + \frac{\Delta t}{w_1\Delta x_1} \left[ - \sin\theta\ T_{3/2}^n - - \frac{\cos\theta}{\Delta x_1} + \sin\alpha\ T_{3/2}^{s-1} + - \frac{\cos\alpha}{\Delta x_1} w_1 K_{\text{aniso}} - \frac{K_{\text{sat},1}}{1000}(h_1^n)^2 + \frac{K_{\text{sat},1}}{1000}(h_1^{s-1})^2 \right] \end{aligned} $$ @@ -268,14 +267,14 @@ Interior nodes ($i=2,\dots,N-1$) $$ \begin{aligned} -a_i &= -\frac{T_{i-\frac12}^n \cos\theta \ \Delta t} - {\Delta x_{i-\frac12}\ \Delta x_i\ w_i}, \\ -c_i &= -\frac{T_{i+\frac12}^n \cos\theta \ \Delta t} - {\Delta x_{i+\frac12}\ \Delta x_i\ w_i}, \\ +a_i &= -\frac{T_{i-\frac12}^{s-1} \cos\alpha \ \Delta t} + {\Delta x_{L_i}\ \Delta x_i\ w_i}, \\ +c_i &= -\frac{T_{i+\frac12}^{s-1} \cos\alpha \ \Delta t} + {\Delta x_{U_i}\ \Delta x_i\ w_i}, \\ b_i &= f_{\text{drain},i} - (a_i + c_i), \\ -r_i &= f_{\text{drain},i} h_i^n - + \frac{\Delta t\sin\theta}{w_i\Delta x_i} - (T_{i+\frac12}^n - T_{i-\frac12}^n) +r_i &= f_{\text{drain},i} h_i^{s-1} + + \frac{\Delta t\sin\alpha}{w_i\Delta x_i} + (T_{i+\frac12}^{s-1} - T_{i-\frac12}^{s-1}) \end{aligned} $$ @@ -283,12 +282,12 @@ Upper boundary ($i=N$, divide) $$ \begin{aligned} -a_N &= -\frac{T_{N-\frac12}^n \cos\theta \ \Delta t} - {\Delta x_{N-\frac12}\ \Delta x_N\ w_N}, \\ +a_N &= -\frac{T_{N-\frac12}^{s-1} \cos\alpha \ \Delta t} + {\Delta x_{L_N}\ \Delta x_N\ w_N}, \\ c_N &= 0, \\ b_N &= f_{\text{drain},N} - a_N, \\ -r_N &= f_{\text{drain},N} h_N^n - - \frac{\Delta t\sin\theta}{w_N\Delta x_N} T_{N-\frac12}^n +r_N &= f_{\text{drain},N} h_N^{s-1} + - \frac{\Delta t\sin\alpha}{w_N\Delta x_N} T_{N-\frac12}^{s-1} \end{aligned} $$ From 7391f16033b99506d6d8667ee8d19616f2e2b35c Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 12:02:34 -0700 Subject: [PATCH 39/42] update --- components/elm/docs/tech-guide/h3d.md | 63 +++++++++++++-------------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index 6ef7e173f435..c19c2631f7cd 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -68,7 +68,7 @@ Land unit captures the hillsclope-scale connectivity, while columns capture spat The fundamental PDE is a Dupuit-style Boussinesq groundwater flow equation for saturated flow along the slope: $$ -f\frac{\partial h}{\partial t} = \frac{1}{w}\frac{\partial}{\partial x}\left(w\ k_{l}(h)\ h\left(\sin(\alpha) + \frac{\partial h}{\partial x}\cos(\alpha)\right)\right) + \cos(\alpha)\ R} +f\frac{\partial h}{\partial t} = \frac{1}{w}\frac{\partial}{\partial x}\left(w\ k_{l}(h)\ h\left(\sin(\alpha) + \frac{\partial h}{\partial x}\cos(\alpha)\right)\right) + \cos(\alpha)\ R $$ where $h(x,t)$ is the saturated thickness [m], @@ -144,14 +144,14 @@ where t and t-1 are current and previous time step, s+1 and s are current and pr $$ \begin{aligned} f\left(h_{1}^{t,s+1}-h_{1}^{t-1}\right) -&= \frac{\Delta T\ \sin(\alpha)}{w_{1}\ \Delta x_{1}} +&= \frac{\Delta t\ \sin(\alpha)}{w_{1}\ \Delta x_{1}} \left(w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}\right) \\ -&\quad + \frac{\Delta T\ \cos(\alpha)}{w_{1}\ \Delta x_{1}} +&\quad + \frac{\Delta t\ \cos(\alpha)}{w_{1}\ \Delta x_{1}} \left( \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_{1}}} \left(h_{2}^{t,s+1}-h_{1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t}\ . +&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t}\ . \end{aligned} $$ @@ -163,9 +163,9 @@ $$ \begin{aligned} &\text{where:} \\ &a_1 = 0 \\ -&b_1 = f + \frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ -&c_1 = -\frac{\Delta T\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ -&r_1 = f h_1^{t-1} + \frac{\Delta T\ \sin(\alpha)}{w_1\ \Delta x_1}\left(w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}\right) + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t} +&b_1 = f + \frac{\Delta t\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&c_1 = -\frac{\Delta t\ \cos(\alpha)}{w_1\ \Delta x_1} \cdot \frac{w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}}{\Delta x_{U_1}} \\ +&r_1 = f h_1^{t-1} + \frac{\Delta t\ \sin(\alpha)}{w_1\ \Delta x_1}\left(w_{\frac{3}{2}}\ k_{l_{\frac{3}{2}}}^{t,s}\ h_{\frac{3}{2}}^{t,s}\right) + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},1}^{t} \end{aligned} $$ @@ -175,17 +175,17 @@ $$ $$ \begin{aligned} f\left(h_{i}^{t,s+1}-h_{i}^{t-1}\right) -&= \frac{\Delta T\ \sin(\alpha)}{w_{i}\ \Delta x_{i}} +&= \frac{\Delta t\ \sin(\alpha)}{w_{i}\ \Delta x_{i}} \left(w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s} - w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}\right) \\ -&\quad + \frac{\Delta T\ \cos(\alpha)}{w_{i}\ \Delta x_{i}} +&\quad + \frac{\Delta t\ \cos(\alpha)}{w_{i}\ \Delta x_{i}} \left( \frac{w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_{i}}} \left(h_{i+1}^{t,s+1}-h_{i}^{t,s+1}\right) \right. \\ &\qquad \left. - \frac{w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_{i}}} \left(h_{i}^{t,s+1}-h_{i-1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},i}^{t}\ . +&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},i}^{t}\ . \end{aligned} $$ @@ -197,11 +197,11 @@ $$ $$ \begin{aligned} &\text{where:} \\ -&a_j = \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ -&b_j = f + \frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ -&c_j = -\frac{\Delta T\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} \\ -&r_j = f h_j^{t-1} + \frac{\Delta T\ \sin(\alpha)}{w_j\ \Delta x_j} \left(w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s} - w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}\right) \\ -&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},j}^{t} +&a_j = \frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ +&b_j = f + \frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ +&c_j = -\frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} \\ +&r_j = f h_j^{t-1} + \frac{\Delta t\ \sin(\alpha)}{w_j\ \Delta x_j} \left(w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s} - w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},j}^{t} \end{aligned} $$ @@ -210,14 +210,14 @@ $$ $$ \begin{aligned} f\left(h_{N}^{t,s+1}-h_{N}^{t-1}\right) -&= -\frac{\Delta T\ \sin(\alpha)}{w_{N}\ \Delta x_{N}} +&= -\frac{\Delta t\ \sin(\alpha)}{w_{N}\ \Delta x_{N}} \left(w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}\right) \\ -&\quad -\frac{\Delta T\ \cos(\alpha)}{w_{N}\ \Delta x_{N}} +&\quad -\frac{\Delta t\ \cos(\alpha)}{w_{N}\ \Delta x_{N}} \left( \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_{N}}} \left(h_{N}^{t,s+1}-h_{N-1}^{t,s+1}\right) \right) \\ -&\quad + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t}\ . +&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t}\ . \end{aligned} $$ @@ -229,17 +229,16 @@ $$ $$ \begin{aligned} &\text{where:} \\ -&a_N = -\frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ -&b_N = f + \frac{\Delta T\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&a_N = -\frac{\Delta t\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ +&b_N = f + \frac{\Delta t\ \cos(\alpha)}{w_N\ \Delta x_N} \cdot \frac{w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}}{\Delta x_{L_N}} \\ &c_N = 0 \\ -&r_N = f h_N^{t-1} - \frac{\Delta T\ \sin(\alpha)}{w_N\ \Delta x_N}\left(w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}\right) + \Delta T\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t} +&r_N = f h_N^{t-1} - \frac{\Delta t\ \sin(\alpha)}{w_N\ \Delta x_N}\left(w_{N-\frac{1}{2}}\ k_{l_{N-\frac{1}{2}}}^{t,s}\ h_{N-\frac{1}{2}}^{t,s}\right) + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},N}^{t} \end{aligned} $$ -Where \Delta x_{U_{1} is -where {\Delta T} (seconds) is the h3d time step, i is the lateral node number. {\Delta x_{U_i}} and {\Delta x_{L_i}} are the distance (m) relative to the center of upper i + 1 -and lower i − 1 node. {w_i} is the width on the center of node i. i − {\frac{1}{2}} and i + {\frac{1}{2}} represent the lower and upper bounds of node i. +Where $\Delta t$ (seconds) is the h3d time step, i is the lateral node number. $\Delta x_{U_i}$ and ${\Delta x_{L_i}}$ are the distance (m) relative to the center of upper i + 1 +and lower i − 1 node. ${w_i}$ is the width on the center of node i. $i − {\frac{1}{2}}$ and $i + {\frac{1}{2}}$ represent the lower and upper bounds of node i. ## IMPLEMENTATION FROM THE CODE @@ -293,7 +292,7 @@ $$ ### Temporal Discretization -A backward-Euler time step is used for stability. Nonlinear terms in transmissivity and porosity are treated by Picard iteration, updating T and $f_{drain} until: +A backward-Euler time step is used for stability. Nonlinear terms in transmissivity and porosity are treated by Picard iteration, updating T and $f_{drain}$ until: $$ \max_i |h_i^{k+1} - h_i^{k}| < 10^{-4}\ \mathrm{m} @@ -315,7 +314,7 @@ $$ $$ \Delta S_{\text{sat},i} -= f_{\text{drain},i}(h_i^{n+1}-h_i^n), += f_{\text{drain},i}(h_i^{t}-h_i^{t-1}), \qquad R_{\text{sub},i} = -\Delta S_{\text{sat},i}, \qquad @@ -348,7 +347,8 @@ Performs the iterative time stepping of the hillslope system: - Converts changes in saturated storage to drainage flux: -_{sat} = f_{drain}\ (h^{n+1} - h^{n}), +$$ +\Delta S_{sat} = f_{drain}\ (h^{t} - h^{t-1}), \qquad Q_{sub} = -\frac{\Delta S_{sat}}{\Delta t} $$ @@ -361,7 +361,7 @@ Solves the implicit Dupuit–Boussinesq system for all h3D nodes in a landunit. Constructs a tridiagonal matrix from the finite-difference discretization: $$ -a_i h_{i-1}^{n+1} + b_i h_i^{n+1} + c_i h_{i+1}^{n+1} = r_i +a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i^{t,s} $$ Steps: @@ -369,9 +369,9 @@ Steps: - Applies slope-dependent flux terms and boundary conditions. -- Solves using the Thomas algorithm (Tridiagonal_h3D). +- Solves using the equation (Tridiagonal_h3D). -- Iterates until the solution converges (see § 5.2). +- Iterates until the solution converges. ## Outputs @@ -387,5 +387,4 @@ After the h3D solve, the model provides: - ΔS_sat — change in saturated storage [m] -These outputs replace or augment SIMTOP drainage for h3D-active columns and are fed into the land surface, - biogeochemical, and river-routing components of ELM. +These outputs replace or augment SIMTOP drainage for h3D-active columns and are fed into the land surface river-routing components of ELM. From 7691ba4af2916ff3d3760d02fc9625329d155105 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 12:04:50 -0700 Subject: [PATCH 40/42] update --- components/elm/docs/tech-guide/h3d.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index c19c2631f7cd..db625108317d 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -129,7 +129,7 @@ This function allows for a smooth transition between unsaturated and fully satur ### Spatial Discretization The PDE is solved implicitly in space and time using a tridiagonal -system for $h_i^{n+1}$ at each node $i$. Node is ordered from 1 to N: +system for $h_i^{t}$ at each node $i$ at time t. Node is ordered from 1 to N: $$ a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i^{t,s} From 668f19cbeb81c9859c740f3162c3b9c1a78a0bf0 Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 12:52:18 -0700 Subject: [PATCH 41/42] update --- components/elm/docs/tech-guide/h3d.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index db625108317d..ef68b45c9049 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -191,17 +191,17 @@ $$ $$ -a_j h_{j-1}^{t,s+1} + b_j h_j^{t,s+1} + c_j h_{j+1}^{t,s+1} = r_j +a_i h_{i-1}^{t,s+1} + b_i h_i^{t,s+1} + c_i h_{i+1}^{t,s+1} = r_i $$ $$ \begin{aligned} &\text{where:} \\ -&a_j = \frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \\ -&b_j = f + \frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \left( \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} + \frac{w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}}{\Delta x_{L_j}} \right) \\ -&c_j = -\frac{\Delta t\ \cos(\alpha)}{w_j\ \Delta x_j} \cdot \frac{w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s}}{\Delta x_{U_j}} \\ -&r_j = f h_j^{t-1} + \frac{\Delta t\ \sin(\alpha)}{w_j\ \Delta x_j} \left(w_{j+\frac{1}{2}}\ k_{l_{j+\frac{1}{2}}}^{t,s}\ h_{j+\frac{1}{2}}^{t,s} - w_{j-\frac{1}{2}}\ k_{l_{j-\frac{1}{2}}}^{t,s}\ h_{j-\frac{1}{2}}^{t,s}\right) \\ -&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},j}^{t} +&a_i = \frac{\Delta t\ \cos(\alpha)}{w_i\ \Delta x_i} \cdot \frac{w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \\ +&b_i = f + \frac{\Delta t\ \cos(\alpha)}{w_i\ \Delta x_i} \left( \frac{w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} + \frac{w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}}{\Delta x_{L_i}} \right) \\ +&c_i = -\frac{\Delta t\ \cos(\alpha)}{w_i\ \Delta x_i} \cdot \frac{w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s}}{\Delta x_{U_i}} \\ +&r_i = f h_i^{t-1} + \frac{\Delta t\ \sin(\alpha)}{w_i\ \Delta x_i} \left(w_{i+\frac{1}{2}}\ k_{l_{i+\frac{1}{2}}}^{t,s}\ h_{i+\frac{1}{2}}^{t,s} - w_{i-\frac{1}{2}}\ k_{l_{i-\frac{1}{2}}}^{t,s}\ h_{i-\frac{1}{2}}^{t,s}\right) \\ +&\quad + \Delta t\ \cos(\alpha)\ R_{\mathrm{sat},i}^{t} \end{aligned} $$ From 63d9ff8ce08df21ecaa0d6c07871e73c918b7a4e Mon Sep 17 00:00:00 2001 From: Yilin Fang Date: Wed, 22 Oct 2025 12:58:35 -0700 Subject: [PATCH 42/42] update --- components/elm/docs/tech-guide/h3d.md | 1 + 1 file changed, 1 insertion(+) diff --git a/components/elm/docs/tech-guide/h3d.md b/components/elm/docs/tech-guide/h3d.md index ef68b45c9049..ee6b371bf4aa 100644 --- a/components/elm/docs/tech-guide/h3d.md +++ b/components/elm/docs/tech-guide/h3d.md @@ -1,6 +1,7 @@ # Hybrid-3D hillslope hydrological model ## Overview + H3D represents subsurface lateral flow and groundwater dynamics within an idealized hillslope unit inside each land grid cell. Rather than treating each soil column as an isolated vertical profile, h3D connects multiple columns along a topographic gradient to explicitly simulate downslope drainage,