ctsm5.3.080: b4b-dev merge 2025-10-16

doc/ChangeLog

@@ -1,4 +1,68 @@
 ===============================================================
+Tag name: ctsm5.3.080
+Originator(s): samrabin (Sam Rabin, UCAR/TSS)
+Date: Thu Oct 16 13:41:08 MDT 2025
+One-line Summary: Merge b4b-dev to master
+
+Purpose and description of changes
+----------------------------------
+
+Merge b4b-dev to master. Includes these PRs:
+- [ESCOMP/CTSM Pull Request #3193: resolve issue #103: Example 1.7 typo by linniahawkins](https://github.com/ESCOMP/CTSM/pull/3193)
+- [ESCOMP/CTSM Pull Request #3518: Update of the leaching doc by jinmuluo](https://github.com/ESCOMP/CTSM/pull/3518)
+- [ESCOMP/CTSM Pull Request #3548: Finishing adding RC14_CANAIR history output by ekluzek](https://github.com/ESCOMP/CTSM/pull/3548)
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+
+List of CTSM issues fixed in the included PRs:
+- [ESCOMP/CTSM Issue #103: Example 1.7 typo](https://github.com/ESCOMP/CTSM/issues/103)
+- [ESCOMP/CTSM Issue #3488: Add RC14_CANAIR as optional to history output so that C14 time series data can be verified](https://github.com/ESCOMP/CTSM/issues/3488)
+- [ESCOMP/CTSM Issue #3490: Change history averaging of RC13_CANAIR and RC14_CANAIR so that zero's aren't averaged in](https://github.com/ESCOMP/CTSM/issues/3490)
+
+
+Notes of particular relevance for users
+---------------------------------------
+
+Changes to documentation:
+- Updated leaching documentation
+- Typo fix
+
+
+Testing summary:
+----------------
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+
+Other details
+-------------
+
+Pull Requests that document the changes (include PR ids):
+- [ESCOMP/CTSM Pull Request #3553: b4b-dev merge 2025-10-16 by samsrabin](https://github.com/ESCOMP/CTSM/pull/3553)
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.079
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Mon Oct  6 21:41:11 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.080 samrabin 10/16/2025 Merge b4b-dev to master
        ctsm5.3.079 samrabin 10/06/2025 Update submodules to match versions in cesm3_0_alpha07e
        ctsm5.3.078   slevis 10/03/2025 Merge b4b-dev to master
        ctsm5.3.077   rgknox 10/02/2025 Adjustment of timestep albedo filtering with FATES

doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst

@@ -133,6 +133,45 @@ where :math:`{WS}_{tot\_soil}` (kgH\ :sub:`2`\ O m\ :sup:`-2`) is the total mass
 
    NF_{leached} =\min \left(NF_{leached} ,\frac{NS_{sminn} sf}{\Delta t} \right).
 
+Alternative way of evaluating the Leaching Losses of Nitrogen
+--------------------------------------------------------------
+
+The previous leaching mechanism is not designed for describing the vertical transport of :math:`{NO}_{3}^{-}` in soil, an alternative way to evaluate the vertical convective, diffusive, and dispersive of dissolved :math:`{NO}_{3}^{-}` in soil is provided in (:ref:`Luo et al. 2025 <Luoetal2025>`). 
+To obtain the vertical profile of soil mineral N after vertical movement of each timestep, the vertical transport equation is summarized in :eq:`22.20`.
+
+.. math::
+   :label: 22.20
+
+   \frac{\partial NS_{sminn}}{\partial t} = \frac{\partial J}{\partial z} + S
+
+where :math:`NS_{sminn} (gN m^{-3})` is the soil :math:`{NO}_{3}^{-}` concentration in each layer, :math:`J (gN m^{-2} s^{-1})` is the different vertical transport terms (:math:`J_{convective}, J_{diffusive}, J_{dispersive}`) between two soil layers, and :math:`S` is the sources or sinks fluxes.
+Different transport terms are explained below 
+
+.. math::
+   :label: 22.21
+
+   J_{convective} = sf \frac{SN_{sminn}q_{out}}{\theta} 
+
+where :math:`q_{out} (mH_{2}Os^{-1})` is the darcy flow of water, :math:`\theta (m^3H_{2}O m^{-3}soil)` is the soil water content.
+
+.. math::
+   :label: 22.22
+
+   J_{diffusive} = -D_{aq} \frac{\theta^{7/3}}{\phi^{2}} \frac{\partial SN_{sminn}}{ \partial z}
+
+where :math:`\partial SN_{sminn}/ \partial z` is the concentration gradient, :math:`D_{aq}` is the nitrate aqueous diffusion coefficient which is taken as :math:`1.7*10^{-9} m^{2}s^{-1}`, and :math:`\phi (m^3m^{-3})` is soil porosity.
+
+.. math::
+   :label: 22.23
+
+   J_{dispersive} = -D_{dis} \frac{\theta^{7/3}}{\phi^{2}} \frac{\partial SN_{sminn}}{ \partial z}
+
+where :math:`D_{dis}` is the dispersion coefficient, which equal to :math:`L_{dis} q_{out} \theta ^{-1}`, for simplicity reasons, :math:`L_{dis}` is taken as 0.1 meter.
+
+Finally, the classical convective-diffusion algorithm described in (:ref:`Patankar.2018 <Patankaretal2018>`) is used to discrete and solve the :math:`{NO}_{3}^{-}` vertical transport :eq:`22.20` in soils. 
+The advantage of this leaching mechanism is the soil :math:`{NO}_{3}^{-}` is able to move vertically (both upward or downward) with soil water movement, the mass of :math:`{NO}_{3}^{-}` reaches bedrock layer is finally taken as the  :math:`NF_{leached}`.
+
+
 Losses of Nitrogen Due to Fire
 -----------------------------------
 

doc/source/tech_note/References/CLM50_Tech_Note_References.rst

@@ -843,6 +843,10 @@ Lowe, P.R. 1977. An approximating polynomial for the computation of saturation v
 
 Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net accumulations of carbon and nitrogen in land ecosystems: a meta-analysis. Ecology 87:53-63.
 
+.. _Luoetal2025:
+
+Luo J, Hess P G, Hall S, et al. Agricultural emissions of reactive nitrogen gases from constrained simulations using the Community Land Model. Authorea Preprints, 2025.
+
 .. _Magilletal1997:
 
 Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems to simulated chronic nitrogen deposition. Ecological Applications, 7: 402-415.
@@ -1048,6 +1052,10 @@ Parton, W. et al. 1996. Generalized model for N2 and N2O production from nitrifi
 
 Parton, W.J. et al. 2001. Generalized model for NOx and N2O emissions from soils. J. Geophys. Res. 106(D15):17403-17419.
 
+.. _Patankaretal2018:
+
+Patankar S., 2018. Numerical heat transfer and fluid flow[M]. CRC press., Boca Raton, section 5.2, 80-95 pp
+
 .. _Paterson1994:
 
 Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., New York, 480 pp.

doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst

@@ -186,7 +186,7 @@ Example: user_nl_clm namelist outputting some files in 1D Vector format
    hist_fincl5 = 'TG'
    hist_fincl6 = 'TG'
    hist_dov2xy = .true., .false., .false., .false.
-   hist_type2d_pertape = ' ', 'GRID', 'COLS', ' '
+   hist_type1d_pertape = ' ', 'GRID', 'COLS', ' '
    hist_nhtfrq = 0, -24, -24, -24
 
 .. warning:: ``LAND`` and ``COLS`` are also options to the pertape averaging, but currently there is a bug with them and they fail to work.

src/biogeophys/PhotosynthesisMod.F90

@@ -172,6 +172,8 @@ module  PhotosynthesisMod
      real(r8), pointer, public  :: rc13_psnsun_patch (:)   ! patch C13O2/C12O2 in sunlit canopy psn flux
      real(r8), pointer, public  :: rc13_psnsha_patch (:)   ! patch C13O2/C12O2 in shaded canopy psn flux
 
+     real(r8), pointer, public  :: rc14_canair_patch (:)   ! patch C14O2/C12O2 in canopy air
+
      real(r8), pointer, public  :: psnsun_patch      (:)   ! patch sunlit leaf photosynthesis     (umol CO2/m**2/s)
      real(r8), pointer, public  :: psnsha_patch      (:)   ! patch shaded leaf photosynthesis     (umol CO2/m**2/s)
      real(r8), pointer, public  :: c13_psnsun_patch  (:)   ! patch c13 sunlit leaf photosynthesis (umol 13CO2/m**2/s)
@@ -346,6 +348,7 @@ subroutine InitAllocate(this, bounds)
     allocate(this%rc13_canair_patch (begp:endp))           ; this%rc13_canair_patch (:)   = nan
     allocate(this%rc13_psnsun_patch (begp:endp))           ; this%rc13_psnsun_patch (:)   = nan
     allocate(this%rc13_psnsha_patch (begp:endp))           ; this%rc13_psnsha_patch (:)   = nan
+    allocate(this%rc14_canair_patch (begp:endp))           ; this%rc14_canair_patch (:)   = nan
 
     allocate(this%cisun_z_patch     (begp:endp,1:nlevcan)) ; this%cisun_z_patch     (:,:) = nan
     allocate(this%cisha_z_patch     (begp:endp,1:nlevcan)) ; this%cisha_z_patch     (:,:) = nan
@@ -449,6 +452,7 @@ subroutine Clean(this)
     deallocate(this%rc13_canair_patch )
     deallocate(this%rc13_psnsun_patch )
     deallocate(this%rc13_psnsha_patch )
+    deallocate(this%rc14_canair_patch )
 
     deallocate(this%cisun_z_patch     )
     deallocate(this%cisha_z_patch     )
@@ -579,7 +583,7 @@ subroutine InitHistory(this, bounds)
        this%rc13_canair_patch(begp:endp) = spval
        call hist_addfld1d (fname='RC13_CANAIR', units='proportion', &
             avgflag='A', long_name='C13/C(12+13) for canopy air', &
-            ptr_patch=this%rc13_canair_patch, default='inactive')
+            ptr_patch=this%rc13_canair_patch, set_spec=spval, default='inactive')
 
        this%rc13_psnsun_patch(begp:endp) = spval
        call hist_addfld1d (fname='RC13_PSNSUN', units='proportion', &
@@ -592,6 +596,13 @@ subroutine InitHistory(this, bounds)
             ptr_patch=this%rc13_psnsha_patch, default='inactive')
     endif
 
+    if ( use_c14 ) then
+       this%rc14_canair_patch(begp:endp) = spval
+       call hist_addfld1d (fname='RC14_CANAIR', units='proportion', &
+            avgflag='A', long_name='C14/C(12+13) for canopy air', &
+            ptr_patch=this%rc14_canair_patch, set_spec=spval, default='inactive')
+    end if
+
     ! Canopy physiology
 
     if ( use_c13 ) then
@@ -1034,6 +1045,11 @@ subroutine Restart(this, bounds, ncid, flag)
             dim1name='pft', long_name='', units='', &
             interpinic_flag='interp', readvar=readvar, data=this%rc13_psnsha_patch)
     endif
+    if ( use_c14 ) then
+       call restartvar(ncid=ncid, flag=flag, varname='rc14_canair', xtype=ncd_double,  &
+            dim1name='pft', long_name='', units='', &
+            interpinic_flag='interp', readvar=readvar, data=this%rc14_canair_patch)
+    end if
 
     call restartvar(ncid=ncid, flag=flag, varname='GSSUN', xtype=ncd_double,  &
          dim1name='pft', dim2name='levcan', switchdim=.true., &
@@ -1173,10 +1189,13 @@ subroutine TimeStepInit (this, bounds)
             .or. lun%itype(l) == istice &
             .or. lun%itype(l) == istwet) then
           if (use_c13) then
-             this%rc13_canair_patch(p) = 0._r8
+             this%rc13_canair_patch(p) = spval
              this%rc13_psnsun_patch(p) = 0._r8
              this%rc13_psnsha_patch(p) = 0._r8
           end if
+          if (use_c14) then
+             this%rc14_canair_patch(p) = spval
+          end if
        end if
     end do
 
@@ -1197,11 +1216,15 @@ subroutine NewPatchInit (this, p)
     if ( use_c13 ) then
        this%alphapsnsun_patch(p) = 0._r8
        this%alphapsnsha_patch(p) = 0._r8
-       this%rc13_canair_patch(p) = 0._r8
+       this%rc13_canair_patch(p) = spval
        this%rc13_psnsun_patch(p) = 0._r8
        this%rc13_psnsha_patch(p) = 0._r8
     endif
 
+    if ( use_c14 ) then
+       this%rc14_canair_patch(p) = spval
+    end if
+
     this%psnsun_patch(p) = 0._r8
     this%psnsha_patch(p) = 0._r8
 
@@ -2072,6 +2095,7 @@ subroutine PhotosynthesisTotal (fn, filterp, &
          rc13_canair => photosyns_inst%rc13_canair_patch , & ! Output: [real(r8) (:) ]  C13O2/C12O2 in canopy air
          rc13_psnsun => photosyns_inst%rc13_psnsun_patch , & ! Output: [real(r8) (:) ]  C13O2/C12O2 in sunlit canopy psn flux
          rc13_psnsha => photosyns_inst%rc13_psnsha_patch , & ! Output: [real(r8) (:) ]  C13O2/C12O2 in shaded canopy psn flux
+         rc14_canair => photosyns_inst%rc14_canair_patch , & ! Output: [real(r8) (:) ]  C1342/C12O2 in canopy air
          alphapsnsun => photosyns_inst%alphapsnsun_patch , & ! Output: [real(r8) (:) ]  fractionation factor in sunlit canopy psn flux
          alphapsnsha => photosyns_inst%alphapsnsha_patch , & ! Output: [real(r8) (:) ]  fractionation factor in shaded canopy psn flux
          psnsun_wc   => photosyns_inst%psnsun_wc_patch   , & ! Output: [real(r8) (:) ]  Rubsico-limited sunlit leaf photosynthesis (umol CO2 /m**2/ s)
@@ -2142,6 +2166,8 @@ subroutine PhotosynthesisTotal (fn, filterp, &
                   sector_c14 = 3
                endif
 
+               rc14_canair(p) = rc14_atm(sector_c14)
+
                c14_psnsun(p) = rc14_atm(sector_c14) * psnsun(p)
                c14_psnsha(p) = rc14_atm(sector_c14) * psnsha(p)
             endif