Merge branch 'docs-week' into docs-crops-2023-10

doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst

@@ -726,38 +726,40 @@ The soil moisture deficit :math:`D_{irrig}` is
 
    D_{irrig} = \left\{
    \begin{array}{lr}
-   w_{thresh} - w_{avail} &\qquad w_{thresh} > w_{avail} \\
+   w_{target} - w_{avail} &\qquad w_{thresh} > w_{avail} \\
    0 &\qquad w_{thresh} \le w_{avail}
    \end{array} \right\}
 
-where :math:`w_{thresh}` is the irrigation moisture threshold (mm) and :math:`w_{avail}` is the available moisture (mm). The moisture threshold is
+where :math:`w_{target}` is the irrigation target soil moisture (mm)
 
 .. math::
    :label: 25.62
 
-   w_{thresh} = f_{thresh} \left(w_{target} - w_{wilt}\right) + w_{wilt}
+   w_{target} = \sum_{j=1}^{N_{irr}} \theta_{target} \Delta z_{j} \ .
 
-where :math:`w_{target}` is the irrigation target soil moisture (mm)
+The irrigation moisture threshold (mm) is
 
 .. math::
    :label: 25.63
 
-   w_{target} = \sum_{j=1}^{N_{irr}} \theta_{target} \Delta z_{j} \ ,
+   w_{thresh} = f_{thresh} \left(w_{target} - w_{wilt}\right) + w_{wilt}
 
-:math:`w_{wilt}` is the wilting point soil moisture (mm)
+where :math:`w_{wilt}` is the wilting point soil moisture (mm)
 
 .. math::
    :label: 25.64
 
    w_{wilt} = \sum_{j=1}^{N_{irr}} \theta_{wilt} \Delta z_{j} \ ,
 
-and :math:`f_{thresh}` is a tuning parameter. The available moisture in the soil is
+and :math:`f_{thresh}` is a tuning parameter.  The available moisture in the soil (mm) is
 
 .. math::
    :label: 25.65
 
    w_{avail} = \sum_{j=1}^{N_{irr}} \theta_{j} \Delta z_{j} \ ,
 
+Note that :math:`w_{target}` is truly supposed to give the target soil moisture value that we're shooting for whenever irrigation happens; then the soil moisture deficit :math:`D_{irrig}` gives the difference between this target value and the current soil moisture. The irrigation moisture threshold :math:`w_{thresh}`, on the other hand, gives a threshold at which we decide to do any irrigation at all. The way this is written allows for the possibility that one may not want to irrigate every time there becomes even a tiny soil moisture deficit. Instead, one may want to wait until the deficit is larger before initiating irrigation; at that point, one doesn't want to just irrigate up to the "threshold" but instead up to the higher "target". The target should always be greater than or equal to the threshold.
+
 :math:`N_{irr}` is the index of the soil layer corresponding to a specified depth :math:`z_{irrig}` (:numref:`Table Irrigation parameters`) and :math:`\Delta z_{j}` is the thickness of the soil layer in layer :math:`j` (section :numref:`Vertical Discretization`). :math:`\theta_{j}` is the volumetric soil moisture in layer :math:`j` (section :numref:`Soil Water`). :math:`\theta_{target}` and :math:`\theta_{wilt}` are the target and wilting point volumetric soil moisture values, respectively, and are determined by inverting :eq:`7.94` using soil matric potential parameters :math:`\Psi_{target}` and :math:`\Psi_{wilt}` (:numref:`Table Irrigation parameters`). After the soil moisture deficit :math:`D_{irrig}` is calculated, irrigation in an amount equal to :math:`\frac{D_{irrig}}{T_{irrig}}` (mm/s) is applied uniformly over the irrigation period :math:`T_{irrig}` (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., added to :math:`{q}_{grnd,liq}`: section :numref:`Canopy Water`).
 
 To conserve mass, irrigation is removed from river water storage (Chapter :numref:`rst_River Transport Model (RTM)`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that river water storage is maintained above a specified threshold.

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

@@ -28,7 +28,7 @@ where :math:`f_{lake}` and :math:`f_{sno}` are the CLM grid cell fractions of la
 
    0\le f_{v} =\frac{L+S}{\left(L+S\right)_{t} } \le 1{\rm \; \; \; \; where\; }\left(L+S\right)_{t} =0.3{\rm \; m}^{2} {\rm m}^{-2}
 
-where equation applies only for dust mobilization and is not related to the plant functional type fractions prescribed from the CLM input data or simulated by the CLM dynamic vegetation model (Chapter 22). :math:`L` and :math:`S` are the CLM leaf and stem area index values (m :sup:`2` m\ :sup:`-2`) averaged at the land unit level so as to include all the pfts and the bare ground present in a vegetated land unit. :math:`L` and :math:`S` may be prescribed from the CLM input data (section :numref:`Phenology and vegetation burial by snow`) or simulated by the CLM biogeochemistry model (Chapter :numref:`rst_Vegetation Phenology and Turnover`).
+where equation :eq:`29.3` applies only for dust mobilization and is not related to the plant functional type fractions prescribed from the CLM input data or simulated by the CLM dynamic vegetation model (Chapter 22). :math:`L` and :math:`S` are the CLM leaf and stem area index values (m :sup:`2` m\ :sup:`-2`) averaged at the land unit level so as to include all the pfts and the bare ground present in a vegetated land unit. :math:`L` and :math:`S` may be prescribed from the CLM input data (section :numref:`Phenology and vegetation burial by snow`) or simulated by the CLM biogeochemistry model (Chapter :numref:`rst_Vegetation Phenology and Turnover`).
 
 The sandblasting mass efficiency :math:`\alpha` (m :sup:`-1`) is calculated as
 
@@ -78,7 +78,7 @@ and
 
    w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} }
 
-where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil layer (m :math:`{}^{3 }`\ m\ :sup:`-3`) (section :numref:`Soil Water`), :math:`\rho _{liq}` is the density of liquid water (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) defined as in section :numref:`Soil and Snow Thermal Properties` rather than as in :ref:`Zender et al. (2003)<Zenderetal2003>`. :math:`Re_{*t}^{f}` from equation is the threshold friction Reynolds factor
+where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil layer (m :math:`{}^{3 }`\ m\ :sup:`-3`) (section :numref:`Soil Water`), :math:`\rho _{liq}` is the density of liquid water (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) defined as in section :numref:`Soil and Snow Thermal Properties` rather than as in :ref:`Zender et al. (2003)<Zenderetal2003>`. :math:`Re_{*t}^{f}` from equation :eq:`29.6` is the threshold friction Reynolds factor
 
 .. math::
    :label: 29.10
@@ -110,7 +110,7 @@ where :math:`u_{*}` is the CLM wind friction speed (m s\ :sup:`-1`), also known
 
    U_{10,t} =u_{*t} \frac{U_{10} }{u_{*} }
 
-In equation we sum :math:`M_{i,\, j}` over :math:`I=3` source modes :math:`i` where :math:`M_{i,\, j}` is the mass fraction of each source mode :math:`i` carried in each of *:math:`J=4`* transport bins :math:`j`
+In equation :eq:`29.1` we sum :math:`M_{i,\, j}` over :math:`I=3` source modes :math:`i` where :math:`M_{i,\, j}` is the mass fraction of each source mode :math:`i` carried in each of *:math:`J=4`* transport bins :math:`j`
 
 .. math::
    :label: 29.14

doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst

@@ -803,7 +803,7 @@ When the expression for :math:`T_{s}` is substituted into equation :eq:`5.88`, t
 
    H_{v} = -\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)T_{v} \right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } .
 
-Similarly, the expression for :math:`T_{s}` can be substituted into equation to obtain the sensible heat flux from ground :math:`H_{g}`
+Similarly, the expression for :math:`T_{s}` can be substituted into equations :eq:`5.89`, :eq:`5.90`, :eq:`5.91`, and :eq:`5.92` to obtain the sensible heat flux from ground :math:`H_{g}`
 
 .. math::
    :label: 5.98
@@ -1199,7 +1199,7 @@ The numerical solution for vegetation temperature and the fluxes of momentum, se
 
 #. An initial guess for the wind speed :math:`V_{a}` is obtained from :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from :eq:`5.50` ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`).
 
-#. An initial guess for the Monin-Obukhov length :math:`L` is obtained from the bulk Richardson number using equation and :eq:`5.46` and :eq:`5.48`.
+#. An initial guess for the Monin-Obukhov length :math:`L` is obtained from the bulk Richardson number using equations :eq:`5.46` and :eq:`5.48`.
 
 #. Iteration proceeds on the following system of equations:
 
@@ -1296,7 +1296,7 @@ The sensible and water vapor heat fluxes derived above for bare soil and soil be
 
    E'_{g} =E_{g} +\left(T_{g}^{n+1} -T_{g}^{n} \right)\frac{\partial E_{g} }{\partial T_{g} }
 
-where :math:`H_{g}` and :math:`E_{g}` are the sensible heat and water vapor fluxes derived from equations and for non-vegetated surfaces and equations and for vegetated surfaces using :math:`T_{g}^{n}`. One further adjustment is made to :math:`H'_{g}` and :math:`E'_{g}`. If the soil moisture in the top snow/soil layer is not sufficient to support the updated ground evaporation, i.e., if :math:`E'_{g} > 0` and :math:`f_{evap} < 1` where
+where :math:`H_{g}`, :math:`E_{g}`, :math:`\frac{\partial H_{g} }{\partial T_{g} }`, and :math:`\frac{\partial E_{g} }{\partial T_{g} }` are the sensible heat and water vapor fluxes and their partial derivatives derived from equations :eq:`5.62`, :eq:`5.66`, :eq:`5.83`, and :eq:`5.84` for non-vegetated surfaces and equations :eq:`5.89`, :eq:`5.102`, :eq:`5.123`, and :eq:`5.124` for vegetated surfaces using :math:`T_{g}^{n}`. One further adjustment is made to :math:`H'_{g}` and :math:`E'_{g}`. If the soil moisture in the top snow/soil layer is not sufficient to support the updated ground evaporation, i.e., if :math:`E'_{g} > 0` and :math:`f_{evap} < 1` where
 
 .. math::
    :label: 5.142

doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst

@@ -358,7 +358,7 @@ For one-dimensional vertical water flow in soils, the conservation of mass is st
 
 where :math:`\theta` is the volumetric soil water content (mm\ :sup:`3` of water / mm\ :sup:`-3` of soil), :math:`t` is time (s), :math:`z` is height above some datum in the soil column (mm) (positive upwards), :math:`q` is soil water flux (kg m\ :sup:`-2` s\ :sup:`-1` or mm s\ :sup:`-1`) (positive upwards), and :math:`e` is a soil moisture sink term (mm of water mm\ :sup:`-1` of soil s\ :sup:`-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 :math:`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 :numref:`Lateral Sub-surface Runoff`).
 
-The soil water flux :math:`q` in equation can be described by Darcy's law :ref:`(Dingman 2002) <Dingman2002>`
+The soil water flux :math:`q` in equation :eq:`7.79` can be described by Darcy's law :ref:`(Dingman 2002) <Dingman2002>`
 
 .. math::
    :label: 7.80
@@ -641,7 +641,7 @@ where
 
 The tridiagonal equation set is solved over :math:`i=1,\ldots,N_{levsoi}`.
 
-The finite-difference forms of the fluxes and partial derivatives in equations :eq:`7.111` - :eq:`7.114` can be obtained from equation as
+The finite-difference forms of the fluxes and partial derivatives in equations :eq:`7.111` - :eq:`7.114` can be obtained from equation :eq:`7.82` as
 
 .. math::
    :label: 7.115
@@ -895,7 +895,7 @@ The specific yield, :math:`S_{y}`, which depends on the soil properties and the
 
 where B is the Clapp-Hornberger exponent. Because :math:`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 :numref:`Soil Water`.
 
-After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer (:math:`w_{liq,\, i}` ) within physical constraints of :math:`w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i}` where :math:`w_{liq}^{\min } =0.01` (mm). First, beginning with the bottom soil layer :math:`i=N_{levsoi}`, any excess liquid water in each soil layer (:math:`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 (plus a maximum surface ponding depth :math:`w_{liq}^{pond} =10` kg m\ :sup:`-2`), is added to drainage :math:`q_{drai}`. Second, to prevent negative :math:`w_{liq,\, i}`, each layer is successively brought up to :math:`w_{liq,\, i} =w_{liq}^{\min }` by taking the required amount of water from the layer below. If this results in :math:`w_{liq,\, N_{levsoi} } <w_{liq}^{\min }`, then the layers above are searched in succession for the required amount of water (:math:`w_{liq}^{\min } -w_{liq,\, N_{levsoi} }` ) and removed from those layers subject to the constraint :math:`w_{liq,\, i} \ge w_{liq}^{\min }`. If sufficient water is not found, then the water is removed from :math:`W_{t}` and :math:`q_{drai}`.
+After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer (:math:`w_{liq,\, i}` ) within physical constraints of :math:`w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i}` where :math:`w_{liq}^{\min } =0.01` (mm). First, beginning with the bottom soil layer :math:`i=N_{levsoi}`, any excess liquid water in each soil layer (:math:`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 :math:`q_{drai}`. Second, to prevent negative :math:`w_{liq,\, i}`, each layer is successively brought up to :math:`w_{liq,\, i} =w_{liq}^{\min }` by taking the required amount of water from the layer below. If this results in :math:`w_{liq,\, N_{levsoi} } <w_{liq}^{\min }`, then the layers above are searched in succession for the required amount of water (:math:`w_{liq}^{\min } -w_{liq,\, N_{levsoi} }` ) and removed from those layers subject to the constraint :math:`w_{liq,\, i} \ge w_{liq}^{\min }`. If sufficient water is not found, then the water is removed from :math:`W_{t}` and :math:`q_{drai}`.
 
 The soil surface layer liquid water and ice contents are then updated for dew :math:`q_{sdew}`, frost :math:`q_{frost}`, or sublimation :math:`q_{subl}` (section :numref:`Update of Ground Sensible and Latent Heat Fluxes`) as
 

doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst

@@ -316,7 +316,7 @@ The fluxes of momentum, sensible heat, and water vapor are solved for simultaneo
 
       E_{g} =-\frac{\rho _{atm} }{r_{aw} } \left[q_{atm} -q_{sat}^{T_{g} } -\frac{\partial q_{sat}^{T_{g} } }{\partial T_{g} } \left(T_{g}^{n+1} -T_{g}^{n} \right)\right]
 
-where the last term on the right side of equation is the change in saturated specific humidity due to the change in :math:`T_{g}` between iterations.
+where the last term on the right side of equation :eq:`12.23` is the change in saturated specific humidity due to the change in :math:`T_{g}` between iterations.
 
 #. Saturated specific humidity :math:`q_{sat}^{T_{g} }` and its derivative :math:`\frac{dq_{sat}^{T_{g} } }{dT_{g} }` are updated for :math:`T_{g}^{n+1}` (section :numref:`Monin-Obukhov Similarity Theory`).
 
@@ -337,7 +337,7 @@ Once the four iterations for lake surface temperature have been yielded a tentat
 
 where :math:`T_{m}` \ is the temperature of maximum liquid water density, 3.85°C (:ref:`Hostetler and Bartlein (1990) <HostetlerBartlein1990>`). The first condition requires that, if there is any snow or ice present, the surface temperature is restricted to be less than or equal to freezing. The second and third conditions maintain convective stability in the top lake layer.
 
-If eq. XXX is applied, the turbulent fluxes :math:`H_{g}` and :math:`E_{g}` are re-evaluated. The emitted longwave radiation and the momentum fluxes are re-evaluated in any case. The final ground heat flux :math:`G` is calculated from the residual of the energy balance eq. XXX in order to precisely conserve energy. XXX This ground heat flux is taken as a prescribed flux boundary condition for the lake temperature solution (section :numref:`Boundary Conditions Lake`). An energy balance check is included at each timestep to insure that eq. XXX is obeyed to within 0.1 W m\ :sup:`-2`.
+If equation :eq:`12.24` is applied, the turbulent fluxes :math:`H_{g}` and :math:`E_{g}` are re-evaluated. The emitted longwave radiation and the momentum fluxes are re-evaluated in any case. The final ground heat flux :math:`G` is calculated from the residual of the energy balance (equation :eq:`12.7`) in order to precisely conserve energy. This ground heat flux is taken as a prescribed flux boundary condition for the lake temperature solution (section :numref:`Boundary Conditions Lake`). A check is included at each timestep to insure that energy balance is obeyed to within 0.1 W m\ :sup:`-2` (see :numref:`Energy Conservation Lake`).
 
 .. _Lake Temperature:
 
@@ -678,7 +678,7 @@ The ice is lumped together at the top. For each lake layer *j* from 1 to *i* + 1
 Energy Conservation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To check energy conservation, the left-hand side of eq. XXX is re-written to yield the total enthalpy of the lake system (J m\ :sup:`-2`) :math:`H_{tot}` :
+To check energy conservation, the left-hand side of equation :eq:`12.27` is re-written to yield the total enthalpy of the lake system (J m\ :sup:`-2`) :math:`H_{tot}` :
 
 .. math::
    :label: 12.57

doc/source/tech_note/Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst

@@ -21,7 +21,7 @@ The total solar radiation is also provided at three hour intervals. The data is
    S_{atm} \left(t_{M} \right)=0 & \qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001
    \end{array}
 
-where :math:`\Delta t_{FD}` is the time step of the forcing data (3 hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 10800 seconds), :math:`\Delta t_{M}` is the model time step (seconds), :math:`S_{atm} \left(t_{FD} \right)` is the three-hourly solar radiation from the forcing data (W m\ :sup:`-2`), and :math:`\mu \left(t_{M} \right)` is the cosine of the solar zenith angle at model time step :math:`t_{M}` (section :numref:`Solar Zenith Angle`). The term in the denominator of equation (1) is the sum of the cosine of the solar zenith angle for each model time step falling within the three hour period. For numerical purposes, :math:`\mu \left(t_{M_{i} } \right)\ge 0.001`.
+where :math:`\Delta t_{FD}` is the time step of the forcing data (3 hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 10800 seconds), :math:`\Delta t_{M}` is the model time step (seconds), :math:`S_{atm} \left(t_{FD} \right)` is the three-hourly solar radiation from the forcing data (W m\ :sup:`-2`), and :math:`\mu \left(t_{M} \right)` is the cosine of the solar zenith angle at model time step :math:`t_{M}` (section :numref:`Solar Zenith Angle`). The term in the denominator of equation :eq:`31.1` is the sum of the cosine of the solar zenith angle for each model time step falling within the three hour period. For numerical purposes, :math:`\mu \left(t_{M_{i} } \right)\ge 0.001`.
 
 The total incident solar radiation :math:`S_{atm}` at the model time step :math:`t_{M}` is then split into near-infrared and visible radiation and partitioned into direct and diffuse according to factors derived from one year's worth of hourly CAM output from CAM version cam3\_5\_55 as