ctsm5.3.072: Incorporating a new vertical movement scheme for soil nitrate

bld/CLMBuildNamelist.pm

@@ -1006,6 +1006,13 @@ sub setup_cmdl_bgc {
   if ( &value_is_true($nl->get_value($var)) && $nl_flags->{'soil_decomp_method'} ne "CENTURYKoven2013" ) {
      $log->fatal_error("$var can only be on with CENTURYKoven2013 soil decomposition");
   }
+
+  # Set use_nvmovement
+  $var = "use_nvmovement";
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, $var);
+  if ( &value_is_true($nl->get_value($var)) && !&value_is_true($nl_flags->{'use_nitrif_denitrif'}) ) {
+     $log->fatal_error("$var cannot be on with use_nitrif_denitrif = .false.");
+  }
 } # end bgc
 
 

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -2431,6 +2431,7 @@ lnd/clm2/surfdata_esmf/NEON/ctsm5.3.0/surfdata_1x1_NEON_TOOL_hist_2000_78pfts_c2
 <use_lch4                                      >.true.</use_lch4>
 <use_nitrif_denitrif soil_decomp_method="None" >.false.</use_nitrif_denitrif>
 <use_nitrif_denitrif                           >.true.</use_nitrif_denitrif>
+<use_nvmovement >.false.</use_nvmovement>
 
 <!-- ===== FATES DEFAULTS =========== -->
 <fates_electron_transport_model use_fates=".true.">FvCB1980</fates_electron_transport_model>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -1002,6 +1002,12 @@ How LUNA and Photosynthesis (if needed) will get Leaf nitrogen content
    lnc_opt = true  get from leaf N from CN model
    lnc_opt = false get based on LAI and fixed CN ratio from parameter file
 </entry>
+<entry id="use_nvmovement" type="logical" category="bgc"
+       group="clm_inparm" value=".false.">
+   use_nvmovement = true use soil nitrogen vertical movement
+   use_nvmovement = false do not use soil nitrogen vertical movement
+   use_nvmovement cannot be true while use_nitrif_denitrif is false
+</entry>
 
 <entry id="paramfile" type="char*512" category="datasets"
        input_pathname="abs" group="clm_inparm" valid_values="" >

cime_config/testdefs/testlist_clm.xml

@@ -595,6 +595,24 @@
       <option name="wallclock">00:50:00</option>
     </options>
   </test>
+  <test name="ERP_D_Ld5" grid="f10_f10_mg37" compset="IHistClm60Bgc" testmods="clm/decStart--clm/nvmovement">
+    <machines>
+      <machine name="izumi" compiler="nag" category="aux_clm"/>
+    </machines>
+    <options>
+      <option name="wallclock">01:00:00</option>
+      <option name="comment">Confirms that use_nvmovement = .true. works with bit-for-bit restarts in IHist</option>
+    </options>
+  </test>
+  <test name="ERP_D_Ld5" grid="f10_f10_mg37" compset="I1850Clm60BgcCrop" testmods="clm/nvmovement--clm/matrixcnOn">
+    <machines>
+      <machine name="derecho" compiler="intel" category="aux_clm"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment">Confirms that use_nvmovement = .true. works with bit-for-bit restarts when matrixcnOn</option>
+    </options>
+  </test>
   <test name="ERS_D" grid="f10_f10_mg37" compset="I1850Clm60Sp" testmods="clm/ExcessIceStreams">
     <machines>
       <machine name="izumi" compiler="nag" category="aux_clm"/>

cime_config/testdefs/testmods_dirs/clm/nvmovement/include_user_mods

@@ -0,0 +1 @@
+../default

cime_config/testdefs/testmods_dirs/clm/nvmovement/user_nl_clm

@@ -0,0 +1 @@
+ use_nvmovement = .true.

doc/ChangeLog

@@ -1,4 +1,89 @@
 ===============================================================
+Tag name: ctsm5.3.072
+Originator(s): jinmuluo (Jinmu Luo, Cornell University)
+Date: Mon 25 Aug 2025 11:04:53 AM MDT
+One-line Summary: New vertical movement scheme for soil nitrate
+
+Purpose and description of changes
+----------------------------------
+
+ This tag introduces a new vertical movement scheme for soil nitrate but sets its use to .false. by default. Details about the new scheme in the PR #2992.
+
+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 (include CTSM Issue # and description) [one per line]:
+ No corresponding github issue
+
+Notes of particular relevance for users
+---------------------------------------
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+ use_nvmovement can be set by user
+
+Changes made to namelist defaults (e.g., changed parameter values):
+ use_nvmovement defaults to .false.
+
+Changes to documentation:
+ Planned for Jinmu's NSF-NCAR visit this Fall
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Changes to tests or testing:
+ New tests with nvmovement testmods, one with matrixcnOn and one with it off
+ ERP_D_Ld5.f10_f10_mg37.I1850Clm60BgcCrop.derecho_intel.clm-nvmovement--clm-matrixcnOn
+ ERP_D.f10_f10_mg37.IHistClm60Bgc.derecho_intel.clm-decStart--clm-nvmovement
+
+Testing summary:
+----------------
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho -
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi -------
+
+  fates tests: (give name of baseline if different from CTSM tagname, normally fates baselines are fates-<FATES TAG>-<CTSM TAG>)
+    derecho -----
+    izumi -------
+
+  any other testing (give details below):
+
+  ctsm_sci
+     derecho ----
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: No
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/2992
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.071
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Fri Aug 22 13:49:25 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.072 jinmuluo 08/xx/2025 New vertical movement scheme for soil nitrate
        ctsm5.3.071 samrabin 08/22/2025 Merge b4b-dev to master
        ctsm5.3.070 glemieux 08/22/2025 Update default FATES parameter file and add FATES managed fire namelist option
        ctsm5.3.069 samrabin 08/12/2025 Add SystemTests to run subset_data and then CTSM

src/biogeochem/CNDriverMod.F90

@@ -44,6 +44,7 @@ module CNDriverMod
   use SoilWaterRetentionCurveMod      , only : soil_water_retention_curve_type
   use CLMFatesInterfaceMod            , only : hlm_fates_interface_type
   use CropReprPoolsMod                , only : nrepr
+  use SoilHydrologyType               , only: soilhydrology_type
   !
   ! !PUBLIC TYPES:
   implicit none
@@ -1013,7 +1014,7 @@ subroutine CNDriverLeaching(bounds, &
        c13_cnveg_carbonstate_inst,c14_cnveg_carbonstate_inst, &
        c13_cnveg_carbonflux_inst,c14_cnveg_carbonflux_inst, &
        c13_soilbiogeochem_carbonstate_inst,c14_soilbiogeochem_carbonstate_inst,&
-       c13_soilbiogeochem_carbonflux_inst,c14_soilbiogeochem_carbonflux_inst)
+       c13_soilbiogeochem_carbonflux_inst,c14_soilbiogeochem_carbonflux_inst, soilhydrology_inst)
     !
     ! !DESCRIPTION:
     ! Update the nitrogen leaching rate as a function of soluble mineral N and total soil water outflow.
@@ -1028,6 +1029,8 @@ subroutine CNDriverLeaching(bounds, &
     use clm_time_manager          , only: is_first_step_of_this_run_segment,is_beg_curr_year,is_end_curr_year,get_curr_date
     use CNSharedParamsMod         , only: use_matrixcn
     use SoilBiogeochemDecompCascadeConType, only: use_soil_matrixcn
+    use SoilNitrogenMovementMod           , only: SoilNitrogenMovement
+    use clm_varctl, only : use_nvmovement
     !
     ! !ARGUMENTS:
     type(bounds_type)                       , intent(in)    :: bounds  
@@ -1045,6 +1048,7 @@ subroutine CNDriverLeaching(bounds, &
     type(cnveg_carbonflux_type)             , intent(inout) :: cnveg_carbonflux_inst
     type(cnveg_carbonstate_type)            , intent(inout) :: cnveg_carbonstate_inst
     type(soilstate_type)                    , intent(inout) :: soilstate_inst
+    type(soilhydrology_type)                , intent(in)    :: soilhydrology_inst
     type(soilbiogeochem_state_type)         , intent(inout) :: soilbiogeochem_state_inst
     type(soilbiogeochem_carbonflux_type)    , intent(inout) :: soilbiogeochem_carbonflux_inst
     type(soilbiogeochem_carbonstate_type)   , intent(inout) :: soilbiogeochem_carbonstate_inst
@@ -1062,8 +1066,16 @@ subroutine CNDriverLeaching(bounds, &
     type(soilbiogeochem_carbonflux_type)    , intent(inout) :: c14_soilbiogeochem_carbonflux_inst
     integer p,fp,yr,mon,day,sec
     !-----------------------------------------------------------------------
-
-    ! Mineral nitrogen dynamics (deposition, fixation, leaching)
+
+    ! soil nitrate fast aqueous movement, leaching will be evaluted here
+    if (use_nitrif_denitrif .and. use_nvmovement) then
+       call t_startf('SoilNitrogenMovementMod')
+       call SoilNitrogenMovement(bounds, num_bgc_soilc, filter_bgc_soilc, waterstatebulk_inst, &
+            soilstate_inst, soilhydrology_inst, soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst)
+       call t_stopf('SoilNitrogenMovementMod')
+    end if
+
+    ! Mineral nitrogen dynamics: deposition, fixation. If use_nvmoment  false, also leaching.
 
     call t_startf('SoilBiogeochemNLeaching')
     call SoilBiogeochemNLeaching(bounds, num_bgc_soilc, filter_bgc_soilc, &

src/biogeochem/CNVegetationFacade.F90

@@ -96,6 +96,7 @@ module CNVegetationFacade
   use SoilBiogeochemPrecisionControlMod , only: SoilBiogeochemPrecisionControl
   use SoilWaterRetentionCurveMod      , only : soil_water_retention_curve_type
   use CLMFatesInterfaceMod            , only : hlm_fates_interface_type
+  use SoilHydrologyType               , only : soilhydrology_type
   !
   implicit none
   private
@@ -1074,7 +1075,7 @@ subroutine EcosystemDynamicsPostDrainage(this, bounds, num_allc, filter_allc, &
        soilbiogeochem_carbonflux_inst, soilbiogeochem_carbonstate_inst, &
        c13_soilbiogeochem_carbonflux_inst, c13_soilbiogeochem_carbonstate_inst, &
        c14_soilbiogeochem_carbonflux_inst, c14_soilbiogeochem_carbonstate_inst, &
-       soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst)
+       soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst, soilhydrology_inst)
     !
     ! !DESCRIPTION:
     ! Do the main science for CN vegetation that needs to be done after hydrology-drainage
@@ -1113,6 +1114,7 @@ subroutine EcosystemDynamicsPostDrainage(this, bounds, num_allc, filter_allc, &
     type(soilbiogeochem_carbonstate_type)   , intent(inout) :: c14_soilbiogeochem_carbonstate_inst
     type(soilbiogeochem_nitrogenflux_type)  , intent(inout) :: soilbiogeochem_nitrogenflux_inst
     type(soilbiogeochem_nitrogenstate_type) , intent(inout) :: soilbiogeochem_nitrogenstate_inst
+    type(soilhydrology_type)                , intent(in)    :: soilhydrology_inst
     !
     ! !LOCAL VARIABLES:
 
@@ -1135,7 +1137,7 @@ subroutine EcosystemDynamicsPostDrainage(this, bounds, num_allc, filter_allc, &
          this%c13_cnveg_carbonstate_inst,this%c14_cnveg_carbonstate_inst, &
          this%c13_cnveg_carbonflux_inst,this%c14_cnveg_carbonflux_inst, &
          c13_soilbiogeochem_carbonstate_inst,c14_soilbiogeochem_carbonstate_inst,&
-         c13_soilbiogeochem_carbonflux_inst,c14_soilbiogeochem_carbonflux_inst)
+         c13_soilbiogeochem_carbonflux_inst,c14_soilbiogeochem_carbonflux_inst, soilhydrology_inst)
 
     ! Set controls on very low values in critical state variables 
 

src/biogeophys/SoilHydrologyType.F90

@@ -51,6 +51,8 @@ Module SoilHydrologyType
      real(r8), pointer :: top_ice_col       (:)     ! col VIC ice len in top layers
      real(r8), pointer :: top_moist_limited_col(:)  ! col VIC soil moisture in top layers, limited to no greater than top_max_moist_col
      real(r8), pointer :: ice_col           (:,:)   ! col VIC soil ice (kg/m2) for VIC soil layers
+     real(r8), pointer :: qout_col          (:,:)   ! flux of water out of soil layer [mm H2O/s]
+     real(r8), pointer :: qin_col           (:,:)   ! flux of water into soil layer [mm H2O/s]
 
    contains
 
@@ -142,14 +144,16 @@ subroutine InitAllocate(this, bounds)
     allocate(this%top_ice_col       (begc:endc))                 ; this%top_ice_col       (:)     = nan
     allocate(this%top_moist_limited_col(begc:endc))              ; this%top_moist_limited_col(:)  = nan
     allocate(this%ice_col           (begc:endc,nlayert))         ; this%ice_col           (:,:)   = nan
+    allocate(this%qout_col          (begc:endc,nlevsoi))         ; this%qout_col          (:,:)   = nan
+    allocate(this%qin_col           (begc:endc,nlevsoi))         ; this%qin_col           (:,:)   = nan
 
   end subroutine InitAllocate
 
   !------------------------------------------------------------------------
   subroutine InitHistory(this, bounds, use_aquifer_layer)
     !
     ! !USES:
-    use histFileMod    , only : hist_addfld1d
+    use histFileMod    , only : hist_addfld1d, hist_addfld2d
     !
     ! !ARGUMENTS:
     class(soilhydrology_type) :: this
@@ -192,6 +196,16 @@ subroutine InitHistory(this, bounds, use_aquifer_layer)
          avgflag='A', long_name='perched water table depth (natural vegetated and crop landunits only)', &
          ptr_col=this%zwt_perched_col, l2g_scale_type='veg')
 
+    this%qout_col(begc:endc, :) = spval
+    call hist_addfld2d (fname="QOUT", units='mm H2O/s',  type2d='levsoi', &
+         avgflag='A', long_name='flux of water out of soil layer', &
+         ptr_col=this%qout_col, default='inactive')
+
+    this%qin_col(begc:endc, :) = spval
+    call hist_addfld2d (fname="QIN", units='mm H2O/s',  type2d='levsoi', &
+         avgflag='A', long_name='flux of water into soil layer', &
+         ptr_col=this%qin_col, default='inactive')
+
   end subroutine InitHistory
 
   !-----------------------------------------------------------------------
@@ -287,7 +301,6 @@ subroutine Restart(this, bounds, ncid, flag)
     character(len=*)  , intent(in)    :: flag   ! 'read' or 'write'
     !
     ! !LOCAL VARIABLES:
-    integer :: j,c ! indices
     logical :: readvar      ! determine if variable is on initial file
     !-----------------------------------------------------------------------
 

src/biogeophys/SoilWaterMovementMod.F90

@@ -579,7 +579,8 @@ subroutine soilwater_zengdecker2009(bounds, num_hydrologyc, filter_hydrologyc, &
          zwt               =>    soilhydrology_inst%zwt_col         , & ! Input:  [real(r8) (:)   ]  water table depth (m)                             
          icefrac           =>    soilhydrology_inst%icefrac_col     , & ! Input:  [real(r8) (:,:) ]  fraction of ice                                 
          hkdepth           =>    soilhydrology_inst%hkdepth_col     , & ! Input:  [real(r8) (:)   ]  decay factor (m)                                  
-
+         qout_col          =>    soilhydrology_inst%qout_col        , & ! Output: [real(r8) (:,:) ]  soil water out of the bottom, mm h2o/s 
+         qin_col           =>    soilhydrology_inst%qin_col         , & ! Output: [real(r8) (:,:) ]  soil water into the bottom, mm h2o/s 
          smpmin            =>    soilstate_inst%smpmin_col          , & ! Input:  [real(r8) (:)   ]  restriction for min of soil potential (mm)        
          watsat            =>    soilstate_inst%watsat_col          , & ! Input:  [real(r8) (:,:) ]  volumetric soil water at saturation (porosity)  
          hksat             =>    soilstate_inst%hksat_col           , & ! Input:  [real(r8) (:,:) ]  hydraulic conductivity at saturation (mm H2O /s)
@@ -787,7 +788,8 @@ subroutine soilwater_zengdecker2009(bounds, num_hydrologyc, filter_hydrologyc, &
          amx(c,j) =  0._r8
          bmx(c,j) =  dzmm(c,j)*(sdamp+1._r8/dtime) + dqodw1(c,j)
          cmx(c,j) =  dqodw2(c,j)
-
+         qin_col(c,j) = qin(c,j)
+         qout_col(c,j) = qout(c,j)   
       end do
 
       ! Nodes j=2 to j=nlevsoi-1
@@ -811,7 +813,8 @@ subroutine soilwater_zengdecker2009(bounds, num_hydrologyc, filter_hydrologyc, &
             amx(c,j)    = -dqidw0(c,j)
             bmx(c,j)    =  dzmm(c,j)/dtime - dqidw1(c,j) + dqodw1(c,j)
             cmx(c,j)    =  dqodw2(c,j)
-
+            qin_col(c,j) = qin(c,j)
+            qout_col(c,j) = qout(c,j)            
          end do
       end do
 
@@ -833,6 +836,8 @@ subroutine soilwater_zengdecker2009(bounds, num_hydrologyc, filter_hydrologyc, &
             amx(c,j)    = -dqidw0(c,j)
             bmx(c,j)    =  dzmm(c,j)/dtime - dqidw1(c,j) + dqodw1(c,j)
             cmx(c,j)    =  0._r8
+            qin_col(c,j) = qin(c,j)
+            qout_col(c,j) = qout(c,j)
 
             ! next set up aquifer layer; hydrologically inactive
             rmx(c,j+1) = 0._r8
@@ -883,6 +888,8 @@ subroutine soilwater_zengdecker2009(bounds, num_hydrologyc, filter_hydrologyc, &
             amx(c,j+1) = -dqidw0(c,j+1)
             bmx(c,j+1) =  dzmm(c,j+1)/dtime - dqidw1(c,j+1) + dqodw1(c,j+1)
             cmx(c,j+1) =  0._r8
+            qin_col(c,j) = qin(c,j)
+            qout_col(c,j) = qout(c,j)
          endif
       end do
 
@@ -1154,7 +1161,8 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
 
          qcharge           =>    soilhydrology_inst%qcharge_col     , & ! Input:  [real(r8) (:)   ]  aquifer recharge rate (mm/s)                      
          zwt               =>    soilhydrology_inst%zwt_col         , & ! Input:  [real(r8) (:)   ]  water table depth (m)                             
-
+         qout_col          =>    soilhydrology_inst%qout_col        , & ! Output: [real(r8) (:,:) ]  soil water out of the bottom, mm h2o/s
+         qin_col           =>    soilhydrology_inst%qin_col         , & ! Output: [real(r8) (:,:) ]  soil water into the bottom, mm h2o/s
          watsat            =>    soilstate_inst%watsat_col          , & ! Input:  [real(r8) (:,:) ] volumetric soil water at saturation (porosity)
          smp_l             =>    soilstate_inst%smp_l_col           , & ! Input:  [real(r8) (:,:) ]  soil matrix potential [mm]                      
          hk_l              =>    soilstate_inst%hk_l_col            , & ! Input:  [real(r8) (:,:) ]  hydraulic conductivity (mm/s)                   
@@ -1402,7 +1410,8 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
                !      call endrun(subname // ':: negative soil moisture values found!')
             endif
          end do
-
+         qin_col(c,1:nlayers) = qin(c,1:nlayers)
+         qout_col(c,1:nlayers) = qout(c,1:nlayers)
       end do  ! spatial loop
 
 

src/main/clm_driver.F90

@@ -1157,7 +1157,7 @@ subroutine clm_drv(doalb, nextsw_cday, declinp1, declin, rstwr, nlend, rdate, ro
                soilbiogeochem_carbonflux_inst, soilbiogeochem_carbonstate_inst, &
                c13_soilbiogeochem_carbonflux_inst, c13_soilbiogeochem_carbonstate_inst, &
                c14_soilbiogeochem_carbonflux_inst, c14_soilbiogeochem_carbonstate_inst, &
-               soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst)
+               soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst, soilhydrology_inst)
           call t_stopf('EcosysDynPostDrainage')
        end if
 

src/main/clm_varcon.F90

@@ -127,6 +127,7 @@ module clm_varcon
   real(r8), public, parameter :: g_to_mg = 1.0e3_r8  ! coefficient to convert g to mg
   real(r8), public, parameter :: cm3_to_m3 = 1.0e-6_r8  ! coefficient to convert cm3 to m3
   real(r8), public, parameter :: pct_to_frac = 1.0e-2_r8  ! coefficient to convert % to fraction
+  real(r8), public, parameter :: mmh2o_to_m3h2o_per_m2 = 1.0e-3_r8  ! coefficient to convert mm H2O to m3 H2O/m2
 
   !!! C13
   real(r8), public, parameter :: preind_atm_del13c = -6.0_r8   ! preindustrial value for atmospheric del13C

src/main/clm_varctl.F90

@@ -522,6 +522,7 @@ module clm_varctl
 
   logical, public :: use_lch4            = .true.
   logical, public :: use_nitrif_denitrif = .true.
+  logical, public :: use_nvmovement      = .false.
   logical, public :: use_extralakelayers = .false.
   logical, public :: use_vichydro        = .false.
   logical, public :: use_cn              = .false.