ESCOMP · billsacks · Oct 20, 2025 · Nov 6, 2025 · Nov 6, 2025 · Nov 12, 2025
diff --git a/cesm/driver/esm.F90 b/cesm/driver/esm.F90
@@ -401,6 +401,7 @@ subroutine InitAttributes(driver, rc)
     use shr_wv_sat_mod   , only : shr_wv_sat_make_tables, ShrWVSatTableSpec
     use shr_wv_sat_mod   , only : shr_wv_sat_get_scheme_idx, shr_wv_sat_valid_idx
     use glc_elevclass_mod, only : glc_elevclass_init
+    use shr_wtracers_mod , only : shr_wtracers_init
    !use shr_scam_mod     , only : shr_scam_checkSurface
 
     ! input/output variables
@@ -544,6 +545,13 @@ subroutine InitAttributes(driver, rc)
        call shr_wv_sat_make_tables(liquid_spec, ice_spec, mixed_spec)
     end if
 
+    !----------------------------------------------------------
+    ! Initialize water tracer info
+    !----------------------------------------------------------
+
+    call shr_wtracers_init(driver, maintask, rc)
+    if (chkerr(rc,__LINE__,u_FILE_u)) return
+
   end subroutine InitAttributes
 
   !================================================================================

diff --git a/cesm/share_wrappers/wtracers_mod.F90 b/cesm/share_wrappers/wtracers_mod.F90
@@ -4,15 +4,30 @@ module wtracers_mod
    ! This module wraps shr_wtracers_mod from the CESM_share repository to avoid direct
    ! dependencies on this share code from CMEPS.
    !
+   ! It is acceptable for CESM-specific CMEPS code (e.g., in the cesm directory) to call
+   ! directly into shr_wtracers_mod, but CMEPS code shared between CESM and other modeling
+   ! systems (e.g., UFS) should go through this module.
+   !
    ! See also the version of wtracers_mod in the ufs directory for when we do not have
    ! access to the CESM_share library.
    !-----------------------------------------------------------------------------
 
-   use shr_wtracers_mod, only : wtracers_is_wtracer_field => shr_wtracers_is_wtracer_field
+   use shr_wtracers_mod, only : wtracers_present             => shr_wtracers_present
+   use shr_wtracers_mod, only : wtracers_get_num_tracers     => shr_wtracers_get_num_tracers
+   use shr_wtracers_mod, only : wtracers_is_wtracer_field    => shr_wtracers_is_wtracer_field
+   use shr_wtracers_mod, only : wtracers_get_bulk_fieldname  => shr_wtracers_get_bulk_fieldname
+   use shr_wtracers_mod, only : wtracers_check_tracer_ratios => shr_wtracers_check_tracer_ratios
+   use shr_wtracers_mod, only : WTRACERS_SUFFIX
 
    implicit none
    private
 
-   public :: wtracers_is_wtracer_field  ! return true if the given field name is a water tracer field
+   public :: wtracers_present             ! return true if there are water tracers in this simulation
+   public :: wtracers_get_num_tracers     ! get number of water tracers in this simulation
+   public :: wtracers_is_wtracer_field    ! return true if the given field name is a water tracer field
+   public :: wtracers_get_bulk_fieldname  ! return the name of the equivalent bulk field corresponding to a water tracer field
+   public :: wtracers_check_tracer_ratios ! check tracer ratios against expectations
+
+   public :: WTRACERS_SUFFIX ! suffix for water tracer field names
 
 end module wtracers_mod
diff --git a/cime_config/buildnml b/cime_config/buildnml
@@ -305,6 +305,11 @@ def _create_drv_namelists(case, infile, confdir, nmlgen, files):
         nmlgen.set_value("esp_cpl_dt", value=esp_time)
     # End if pause is active
 
+    # --------------------------------
+    # Overwrite: set water tracers
+    # --------------------------------
+    _add_water_tracers(case.get_value("WATER_TRACERS"), nmlgen)
+
     # --------------------------------
     # Specify input data list file
     # --------------------------------
@@ -553,6 +558,44 @@ def _create_drv_namelists(case, infile, confdir, nmlgen, files):
         nmlgen.write_output_file(drv_flds_in)
 
 
+###############################################################################
+def _add_water_tracers(water_tracers_xml, nmlgen):
+    ###############################################################################
+
+    if not water_tracers_xml.strip():
+        water_tracers = []
+    else:
+        water_tracers = water_tracers_xml.split(":")
+    tracer_names = []
+    tracer_species = []
+    tracer_initial_ratios = []
+
+    for tracer in water_tracers:
+        # Each item in the list consists of a name and then, optionally, a '%' followed by
+        # the isotope species for this tracer. For standard water tracers (i.e., tracers
+        # of bulk water), the list item will only contain the name (without a '%').
+        expect(
+            tracer.count("%") <= 1,
+            f"Invalid WATER_TRACERS element, '{tracer}': Each element of WATER_TRACERS must contain at most 1 '%' separator",
+        )
+        parts = tracer.split("%")
+        tracer_names.append(parts[0])
+        if len(parts) > 1:
+            tracer_species.append(parts[1])
+            # We could check the validity of the species name here (confirming that it's
+            # one of the handled species), but that would lead to this allowed list being
+            # replicated in multiple places (here as well as in the Fortran), which would
+            # make it more difficult to add new species later. So we're deferring this
+            # check to runtime.
+        else:
+            tracer_species.append("-")
+        tracer_initial_ratios.append("1.0")
+
+    nmlgen.add_default("water_tracer_names", ":".join(tracer_names))
+    nmlgen.add_default("water_tracer_species", ":".join(tracer_species))
+    nmlgen.add_default("water_tracer_initial_ratios", ":".join(tracer_initial_ratios))
+
+
 ###############################################################################
 def _create_runseq(case, coupling_times, valid_comps):
     ###############################################################################

diff --git a/cime_config/config_component_cesm.xml b/cime_config/config_component_cesm.xml
@@ -501,7 +501,7 @@
   </entry>
 
   <!-- ===================================================================== -->
-  <!-- averaged history frequencies -->
+  <!-- controls over various other options -->
   <!-- ===================================================================== -->
 
   <entry id="BUDGETS">
@@ -581,5 +581,30 @@
     <desc>Freezing point calculation for salt water.</desc>
   </entry>
 
+  <entry id="WATER_TRACERS">
+   <type>char</type>
+   <default_value></default_value>
+   <group>run_coupling</group>
+   <file>env_run.xml</file>
+   <desc>
+      Colon-delimited list of water tracers enabled in this run.
+
+      Each item in the list consists of a name and then, optionally, a '%' followed by the
+      isotope species for this tracer. For standard water tracers (i.e., tracers of bulk
+      water), the list item will only contain the name (without a '%'). The name can be
+      anything; if an isotope species is specified, it must match one of the implemented
+      water isotopes: H218O, H217O or HDO. By convention, a tracer that is the full
+      quantity of a given isotope will have a name that is identical to the species (e.g.,
+      H218O:H218O).
+
+      For example, this list could be:
+      MyRegularTracer:HDO%HDO:H218O%H218O:SomeOtherTracer:MyHdoTracer%HDO:YetAnotherTracer
+
+      This specifies three standard (bulk water) tracers (MyRegularTracer, SomeOtherTracer
+      and YetAnotherTracer), two isotopes (HDO and H218O), and a tracer that is a subset
+      of HDO (MyHdoTracer). (Note that the ordering in the list is not important.)
+   </desc>
+  </entry>
+
 
 </entry_id>
diff --git a/cime_config/namelist_definition_drv.xml b/cime_config/namelist_definition_drv.xml
@@ -853,7 +853,6 @@
     </desc>
     <values>
       <value>on</value>
-      <value COMP_LND="xlnd">off</value>
     </values>
   </entry>
   <entry id="remove_negative_runoff_lnd">
@@ -2595,6 +2594,66 @@
     </values>
   </entry>
 
+  <entry id="water_tracer_names" modify_via_xml="WATER_TRACERS" skip_default_entry="true">
+   <type>char</type>
+   <category>water_tracers</category>
+   <group>ALLCOMP_attributes</group>
+   <desc>
+      Colon-delimited list of names of water tracers in this run.
+   </desc>
+   <values>
+      <value></value>
+   </values>
+  </entry>
+
+  <entry id="water_tracer_species" modify_via_xml="WATER_TRACERS" skip_default_entry="true">
+   <type>char</type>
+   <category>water_tracers</category>
+   <group>ALLCOMP_attributes</group>
+   <desc>
+      Colon-delimited list of species of water tracers in this run.
+
+      Each element in the list corresponds to an element in water_tracer_names. A value of
+      '-' for a given element indicates a standard water tracer (i.e., a tracer of bulk
+      water).
+   </desc>
+   <values>
+      <value></value>
+   </values>
+  </entry>
+
+  <entry id="water_tracer_initial_ratios" skip_default_entry="true">
+   <type>char</type>
+   <category>water_tracers</category>
+   <group>ALLCOMP_attributes</group>
+   <desc>
+      Colon-delimited list of initial water tracer ratios (as a fraction of total water).
+
+      Each element in the list corresponds to an element in water_tracer_names.
+
+      For water isotopes, this ratio is typically set to 1 for numerical reasons; the
+      actual isotopic ratios can then be determined via reference to standard global
+      ratios.
+   </desc>
+   <values>
+      <value></value>
+   </values>
+  </entry>
+
+  <entry id="water_tracers_do_checks">
+   <type>logical</type>
+   <category>water_tracers</category>
+   <group>ALLCOMP_attributes</group>
+   <desc>
+      Check consistency between water tracer fields and their corresponding bulk fields.
+
+      This should only be used with artificial tracers that maintain a fixed ratio.
+   </desc>
+   <values>
+      <value>.false.</value>
+   </values>
+  </entry>
+
   <!-- =========================== -->
   <!-- CLOCK Attributes            -->
   <!-- =========================== -->

diff --git a/cime_config/testdefs/testmods_dirs/drv/glc_avg_frequently/README b/cime_config/testdefs/testmods_dirs/drv/glc_avg_frequently/README
@@ -0,0 +1,2 @@
+This testmod turns on more frequent averaging of the fields sent to glc so that the
+mapping of these fields can be tested in a run shorter than a year.
diff --git a/cime_config/testdefs/testmods_dirs/drv/glc_avg_frequently/shell_commands b/cime_config/testdefs/testmods_dirs/drv/glc_avg_frequently/shell_commands
@@ -0,0 +1 @@
+./xmlchange GLC_AVG_PERIOD=glc_coupling_period
diff --git a/med_test_comps/xatm/src/atm_comp_nuopc.F90 b/med_test_comps/xatm/src/atm_comp_nuopc.F90
@@ -15,10 +15,13 @@ module atm_comp_nuopc
   use shr_sys_mod       , only : shr_sys_abort
   use shr_kind_mod      , only : r8=>shr_kind_r8, i8=>shr_kind_i8, cl=>shr_kind_cl, cs=>shr_kind_cs
   use shr_log_mod      , only : shr_log_getlogunit, shr_log_setlogunit
+  use shr_wtracers_mod , only : WTRACERS_SUFFIX
+  use shr_wtracers_mod , only : shr_wtracers_present, shr_wtracers_get_num_tracers
   use dead_methods_mod  , only : chkerr, state_setscalar,  state_diagnose, alarmInit, memcheck
   use dead_methods_mod  , only : set_component_logging, get_component_instance, log_clock_advance
   use dead_nuopc_mod    , only : dead_read_inparms, ModelInitPhase, ModelSetRunClock
   use dead_nuopc_mod    , only : fld_list_add, fld_list_realize, fldsMax, fld_list_type
+  use dead_nuopc_mod    , only : set_all_export_fields
 
   implicit none
   private ! except
@@ -39,7 +42,6 @@ module atm_comp_nuopc
   integer                :: fldsFrAtm_num = 0
   type (fld_list_type)   :: fldsToAtm(fldsMax)
   type (fld_list_type)   :: fldsFrAtm(fldsMax)
-  integer, parameter     :: gridTofieldMap = 2 ! ungridded dimension is innermost
 
   type(ESMF_Mesh)        :: mesh
   integer                :: nxg         ! global dim i-direction
@@ -121,6 +123,8 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc)
     character(CL)     :: cvalue
     character(len=CL) :: logmsg
     logical           :: isPresent, isSet
+    logical           :: flds_wtracers
+    integer           :: num_wtracers
     character(len=*),parameter :: subname=trim(modName)//':(InitializeAdvertise) '
     !-------------------------------------------------------------------------------
 
@@ -202,6 +206,9 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc)
 
     if (nxg /= 0 .and. nyg /= 0) then
 
+       flds_wtracers = shr_wtracers_present()
+       num_wtracers = shr_wtracers_get_num_tracers()
+
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, trim(flds_scalar_name))
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_topo'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_z'          )
@@ -210,13 +217,27 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc)
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_tbot'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_ptem'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_shum'       )
+       if (flds_wtracers) then
+          call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_shum'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+       end if
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_pbot'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_dens'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Sa_pslv'       )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_rainc'    )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_rainl'    )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_snowc'    )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_snowl'    )
+       if (flds_wtracers) then
+          call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_rainc'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+          call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_rainl'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+          call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_snowc'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+          call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_snowl'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+       end if
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_lwdn'     )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_swndr'    )
        call fld_list_add(fldsFrAtm_num, fldsFrAtm, 'Faxa_swvdr'    )
@@ -238,6 +259,10 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc)
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'So_ofrac'  )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Sx_tref'   )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Sx_qref'   )
+       if (flds_wtracers) then
+          call fld_list_add(fldsToAtm_num, fldsToAtm, 'Sx_qref'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+       end if
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Sx_t'      )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'So_t'      )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Sl_fv'     )
@@ -253,6 +278,10 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc)
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Faxx_sen'  )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Faxx_lwup' )
        call fld_list_add(fldsToAtm_num, fldsToAtm, 'Faxx_evap' )
+       if (flds_wtracers) then
+          call fld_list_add(fldsToAtm_num, fldsToAtm, 'Faxx_evap'//WTRACERS_SUFFIX, &
+               num_wtracers=num_wtracers)
+       end if
 
        do n = 1,fldsFrAtm_num
           if(mastertask) write(logunit,*)'Advertising From Xatm ',trim(fldsFrAtm(n)%stdname)
@@ -417,7 +446,7 @@ subroutine state_setexport(exportState, rc)
     integer, intent(out) :: rc
 
     ! local variables
-    integer           :: n, nf, nind
+    integer           :: n
     real(r8), pointer :: lat(:)
     real(r8), pointer :: lon(:)
     integer           :: spatialDim
@@ -440,19 +469,16 @@ subroutine state_setexport(exportState, rc)
        lat(n) = ownedElemCoords(2*n)
     end do
 
-    ! Start from index 2 in order to Skip the scalar field here
-    do nf = 2,fldsFrAtm_num
-       if (fldsFrAtm(nf)%ungridded_ubound == 0) then
-          call field_setexport(exportState, trim(fldsFrAtm(nf)%stdname), lon, lat, nf=nf, rc=rc)
-          if (chkerr(rc,__LINE__,u_FILE_u)) return
-       else
-          do nind = 1,fldsFrAtm(nf)%ungridded_ubound
-             call field_setexport(exportState, trim(fldsFrAtm(nf)%stdname), lon, lat, nf=nf+nind-1, &
-                  ungridded_index=nind, rc=rc)
-             if (chkerr(rc,__LINE__,u_FILE_u)) return
-          end do
-       end if
-    end do
+    call set_all_export_fields( &
+         exportState = exportState, &
+         flds = fldsFrAtm, &
+         fld_min = 2, &  ! Start from index 2 in order to skip the scalar field here
+         fld_max = fldsFrAtm_num, &
+         lon = lon, &
+         lat = lat, &
+         field_setexport = field_setexport, &
+         rc = rc)
+    if (ChkErr(rc,__LINE__,u_FILE_u)) return
 
     deallocate(lon)
     deallocate(lat)
@@ -478,6 +504,7 @@ subroutine field_setexport(exportState, fldname, lon, lat, nf, ungridded_index,
     type(ESMF_Field)  :: lfield
     real(r8), pointer :: data1d(:)
     real(r8), pointer :: data2d(:,:)
+    integer, parameter :: gridTofieldMap = 2 ! ungridded dimension is innermost
     !--------------------------------------------------
 
     rc = ESMF_SUCCESS
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		This testmod turns on more frequent averaging of the fields sent to glc so that the
		mapping of these fields can be tested in a run shorter than a year.