Merge pull request #1319 from fvitt/esmf_tem_diags

cam6_4_097: An alternative for TEM diagnostics

Author: fvitt

bld/namelist_files/namelist_definition.xml

@@ -538,6 +538,13 @@ Default: .false.,  unless it is overridden (WACCM with interactive chemistry and
           configurations do this)
 </entry>
 
+<entry id="ctem_diags_numlats" type="integer"  category="diagnostics"
+       group="ctem_diags_nl" valid_values="" >
+Number of latitude grid points for zonal average Transformed Eulerian Mean (TEM)
+diagnostics history fields.  Values greater than zero turn on the TEM diagostics.
+Default: 0
+</entry>
+
 <entry id="phys_grid_ctem_zm_nbas" type="integer"  category="diagnostics"
        group="phys_grid_ctem_opts" valid_values="" >
 Number of zonal mean basis functions (number of m=0 spherical harmonics) used in
@@ -3226,7 +3233,7 @@ Default: .false.
 
 <entry id="zmconv_parcel_hscale" type="real" category="conv"
        group="zmconv_nl" valid_values="" >
- The fraction of the boundary layer (PBL) depth, over which to mix the initial ZM convective parcel properties (fraction). 
+ The fraction of the boundary layer (PBL) depth, over which to mix the initial ZM convective parcel properties (fraction).
 Default: 0.5
 </entry>
 

cime_config/testdefs/testlist_cam.xml

@@ -1138,7 +1138,7 @@
       <option name="wallclock">00:30:00</option>
     </options>
   </test>
-  <test compset="FHISTC_WXma" grid="ne30pg3_ne30pg3_mg17" name="ERS_Ln9" testmods="cam/outfrq9s">
+  <test compset="FHISTC_WXma" grid="ne30pg3_ne30pg3_mg17" name="ERS_Ln9" testmods="cam/outfrq9s_ctem">
     <machines>
       <machine name="derecho" compiler="intel" category="aux_cam"/>
       <machine name="derecho" compiler="intel" category="waccmx"/>

cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/shell_commands

@@ -0,0 +1,2 @@
+./xmlchange ROF_NCPL=\$ATM_NCPL
+./xmlchange GLC_NCPL=\$ATM_NCPL

cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/user_nl_cam

@@ -0,0 +1,14 @@
+mfilt=1,1,1,1,1,1,1,1,1,1
+ndens=1,1,1,1,1,1,1,1,1,1
+nhtfrq=9,9,9,9,9,9,9,9,9,9
+write_nstep0=.true.
+inithist='ENDOFRUN'
+
+cam_physics_mesh = '$ATM_DOMAIN_MESH'
+ctem_diags_numlats = 90
+
+fincl2 = 'THtem','Utem','Vtem','Wtem','VTHtem','WTHtem','UVtem', 'UWtem', 'MSKtem', 'PStem'
+fincl3 = 'Uzm', 'Vzm','Wzm', 'THzm','VTHzm','WTHzm','UVzm', 'UWzm', 'PSzm'
+
+do_circulation_diags = .false.
+fincl7 = ' '

cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/user_nl_clm

@@ -0,0 +1,27 @@
+!----------------------------------------------------------------------------------
+! Users should add all user specific namelist changes below in the form of 
+! namelist_var = new_namelist_value 
+!
+! Include namelist variables for drv_flds_in ONLY if -megan and/or -drydep options
+! are set in the CLM_NAMELIST_OPTS env variable.
+!
+! EXCEPTIONS: 
+! Set use_cndv           by the compset you use and the CLM_BLDNML_OPTS -dynamic_vegetation setting
+! Set use_vichydro       by the compset you use and the CLM_BLDNML_OPTS -vichydro           setting
+! Set use_cn             by the compset you use and CLM_BLDNML_OPTS -bgc  setting
+! Set use_crop           by the compset you use and CLM_BLDNML_OPTS -crop setting
+! Set spinup_state       by the CLM_BLDNML_OPTS -bgc_spinup      setting
+! Set irrigate           by the CLM_BLDNML_OPTS -irrig           setting
+! Set dtime              with L_NCPL                             option
+! Set fatmlndfrc         with LND_DOMAIN_PATH/LND_DOMAIN_FILE    options
+! Set finidat            with RUN_REFCASE/RUN_REFDATE/RUN_REFTOD options for hybrid or branch cases
+!                        (includes $inst_string for multi-ensemble cases)
+! Set glc_grid           with CISM_GRID                          option
+! Set glc_smb            with GLC_SMB                            option
+! Set maxpatch_glcmec    with GLC_NEC                            option
+! Set glc_do_dynglacier  with GLC_TWO_WAY_COUPLING               env variable
+!----------------------------------------------------------------------------------
+hist_nhtfrq = 9
+hist_mfilt  = 1
+hist_ndens  = 1
+

doc/ChangeLog

@@ -1,4 +1,89 @@
+===============================================================
+
+Tag name: cam6_4_097
+Originator(s): fvitt
+Date: 13 Jun 2025
+One-line Summary: An alternative method for zonal-mean TEM diagnostics
+Github PR URL: https://github.com/ESCOMP/CAM/pull/1319
+
+Purpose of changes (include the issue number and title text for each relevant GitHub issue):
+
+Provides an method alternative to of computing zonal-mean terms of the
+Transformed Eulerian Mean (TEM) diagnostics independent of dynamical core.
+
+The method here uses regridding capabilities provided in the ESMF library to map the dynamical
+fields needed in TEM diagnostics from the physics grid to a distributed regular longitude -
+latitude grid. The TEM diagnostics are computed on this regular longitude - latitude grid and
+computing zonal means is straightforward.
+
+Describe any changes made to build system: N/A
+
+Describe any changes made to the namelist:
+
+New namelist option ctem_diags_numlats :
+ Number of latitude grid points for zonal average Transformed Eulerian Mean (TEM)
+ diagnostics history fields.  Values greater than zero turn on the TEM diagostics.
+
+List any changes to the defaults for the boundary datasets: N/A
 
+Describe any substantial timing or memory changes:
+ Performance impact is minimal
+
+Code reviewed by: nusbaume
+
+List all files eliminated: N/A
+
+List all files added and what they do:
+
+A       src/utils/ctem_diags_modc.F90
+A       src/utils/esmf_check_error_mod.F90
+A       src/utils/esmf_lonlat_grid_mod.F90
+A       src/utils/esmf_phys2lonlat_mod.F90
+A       src/utils/esmf_phys_mesh_mod.F90
+A       src/utils/esmf_zonal_mean_mod.F90
+ - module files for computing TEM diagnostics and zonal means
+
+A       cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/shell_commands
+A       cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/user_nl_cam
+A       cime_config/testdefs/testmods_dirs/cam/outfrq9s_ctem/user_nl_clm
+ - for testing the new TEM diagnostics
+
+List all existing files that have been modified, and describe the changes:
+
+M       bld/namelist_files/namelist_definition.xml
+ - new namelist option described above
+
+M       src/control/runtime_opts.F90
+ - read namelist options for ctem_diags_mod module
+
+M       src/physics/cam/physpkg.F90
+M       src/physics/cam7/physpkg.F90
+ - interface with the ctem_diags_mod module
+
+M       cime_config/testdefs/testlist_cam.xml
+ - add test for TEM diags to aux_cam test of FHISTC_WXma
+
+If there were any failures reported from running test_driver.sh on any test
+platform, and checkin with these failures has been OK'd by the gatekeeper,
+then copy the lines from the td.*.status files for the failed tests to the
+appropriate machine below.  All failed tests must be justified.
+
+derecho/intel/aux_cam:
+  DIFF ERS_Ln9.ne30pg3_ne30pg3_mg17.FHISTC_WXma.derecho_intel.cam-outfrq9s_ctem
+  - new TEM test -- no baseline to compare against
+
+  FAIL SMS_D_Ln9_P1280x1.ne0CONUSne30x8_ne0CONUSne30x8_mt12.FCHIST.derecho_intel.cam-outfrq9s
+  - pre-existing failure due to build-namelist error requiring CLM/CTSM external update
+
+derecho/nvhpc/aux_cam: All PASS
+
+izumi/nag/aux_cam: All PASS
+
+izumi/gnu/aux_cam: All PASS
+
+Summarize any changes to answers: bit-for-bit unchanged
+
+===============================================================
 ===============================================================
 
 Tag name: cam6_4_096

src/control/runtime_opts.F90

@@ -105,6 +105,7 @@ subroutine read_namelist(nlfilename, single_column, scmlat, scmlon)
    use surface_emissions_mod, only: surface_emissions_readnl
    use elevated_emissions_mod, only: elevated_emissions_readnl
    use atm_stream_ndep,     only: stream_ndep_readnl
+   use ctem_diags_mod, only: ctem_diags_readnl
 
    !---------------------------Arguments-----------------------------------
 
@@ -211,6 +212,7 @@ subroutine read_namelist(nlfilename, single_column, scmlat, scmlon)
    call surface_emissions_readnl(nlfilename)
    call elevated_emissions_readnl(nlfilename)
    call stream_ndep_readnl(nlfilename)
+   call ctem_diags_readnl(nlfilename)
 
 end subroutine read_namelist
 

src/physics/cam/physpkg.F90

@@ -164,6 +164,7 @@ subroutine phys_register
     use upper_bc,           only: ubc_fixed_conc
     use surface_emissions_mod, only: surface_emissions_reg
     use elevated_emissions_mod, only: elevated_emissions_reg
+    use ctem_diags_mod, only: ctem_diags_reg
 
     !---------------------------Local variables-----------------------------
     !
@@ -355,6 +356,9 @@ subroutine phys_register
         call HCOI_Chunk_Init()
     endif
 
+    ! TEM diagnostics
+    call ctem_diags_reg()
+
     ! This needs to be last as it requires all pbuf fields to be added
     if (cam_snapshot_before_num > 0 .or. cam_snapshot_after_num > 0) then
         call pbuf_cam_snapshot_register()
@@ -777,6 +781,7 @@ subroutine phys_init( phys_state, phys_tend, pbuf2d, cam_in, cam_out )
     use elevated_emissions_mod, only: elevated_emissions_init
 
     use ccpp_constituent_prop_mod, only: ccpp_const_props_init
+    use ctem_diags_mod, only: ctem_diags_init
 
     ! Input/output arguments
     type(physics_state), pointer       :: phys_state(:)
@@ -1059,6 +1064,8 @@ subroutine phys_init( phys_state, phys_tend, pbuf2d, cam_in, cam_out )
     dtcore_idx = pbuf_get_index('DTCORE')
     dqcore_idx = pbuf_get_index('DQCORE')
 
+    call ctem_diags_init()
+
   end subroutine phys_init
 
   !
@@ -1083,6 +1090,7 @@ subroutine phys_run1(phys_state, ztodt, phys_tend, pbuf2d,  cam_in, cam_out)
 #if ( defined OFFLINE_DYN )
      use metdata,       only: get_met_srf1
 #endif
+    use ctem_diags_mod, only: ctem_diags_calc
     !
     ! Input arguments
     !
@@ -1127,6 +1135,9 @@ subroutine phys_run1(phys_state, ztodt, phys_tend, pbuf2d,  cam_in, cam_out)
     call pbuf_allocate(pbuf2d, 'physpkg')
     call diag_allocate()
 
+    ! TEM diagnostics
+    call ctem_diags_calc(phys_state)
+
     !-----------------------------------------------------------------------
     ! Advance time information
     !-----------------------------------------------------------------------
@@ -1316,6 +1327,7 @@ subroutine phys_final( phys_state, phys_tend, pbuf2d )
     use microp_aero, only : microp_aero_final
     use phys_grid_ctem, only : phys_grid_ctem_final
     use nudging, only: Nudge_Model, nudging_final
+    use ctem_diags_mod, only: ctem_diags_final
 
     !-----------------------------------------------------------------------
     !
@@ -1346,6 +1358,8 @@ subroutine phys_final( phys_state, phys_tend, pbuf2d )
         call HCOI_Chunk_Final
     endif
 
+    call ctem_diags_final()
+
   end subroutine phys_final
 
 

src/physics/cam7/physpkg.F90

@@ -158,6 +158,7 @@ subroutine phys_register
     use hemco_interface,    only: HCOI_Chunk_Init
     use surface_emissions_mod, only: surface_emissions_reg
     use elevated_emissions_mod, only: elevated_emissions_reg
+    use ctem_diags_mod, only: ctem_diags_reg
 
     !---------------------------Local variables-----------------------------
     !
@@ -345,6 +346,9 @@ subroutine phys_register
         call HCOI_Chunk_Init()
     endif
 
+    ! TEM diagnostics
+    call ctem_diags_reg()
+
     ! This needs to be last as it requires all pbuf fields to be added
     if (cam_snapshot_before_num > 0 .or. cam_snapshot_after_num > 0) then
         call pbuf_cam_snapshot_register()
@@ -772,6 +776,7 @@ subroutine phys_init( phys_state, phys_tend, pbuf2d, cam_in, cam_out )
     use elevated_emissions_mod, only: elevated_emissions_init
 
     use ccpp_constituent_prop_mod, only: ccpp_const_props_init
+    use ctem_diags_mod, only: ctem_diags_init
 
     ! Input/output arguments
     type(physics_state), pointer       :: phys_state(:)
@@ -1053,6 +1058,8 @@ subroutine phys_init( phys_state, phys_tend, pbuf2d, cam_in, cam_out )
 
     psl_idx = pbuf_get_index('PSL')
 
+    call ctem_diags_init()
+
   end subroutine phys_init
 
   !
@@ -1076,6 +1083,7 @@ subroutine phys_run1(phys_state, ztodt, phys_tend, pbuf2d,  cam_in, cam_out)
 #if ( defined OFFLINE_DYN )
      use metdata,       only: get_met_srf1
 #endif
+    use ctem_diags_mod, only: ctem_diags_calc
     !
     ! Input arguments
     !
@@ -1121,6 +1129,9 @@ subroutine phys_run1(phys_state, ztodt, phys_tend, pbuf2d,  cam_in, cam_out)
     call pbuf_allocate(pbuf2d, 'physpkg')
     call diag_allocate()
 
+    ! TEM diagnostics
+    call ctem_diags_calc(phys_state)
+
     !-----------------------------------------------------------------------
     ! Advance time information
     !-----------------------------------------------------------------------
@@ -1310,6 +1321,7 @@ subroutine phys_final( phys_state, phys_tend, pbuf2d )
     use phys_grid_ctem, only: phys_grid_ctem_final
     use nudging,        only: Nudge_Model, nudging_final
     use hemco_interface, only: HCOI_Chunk_Final
+    use ctem_diags_mod, only: ctem_diags_final
 
     !-----------------------------------------------------------------------
     !
@@ -1336,10 +1348,12 @@ subroutine phys_final( phys_state, phys_tend, pbuf2d )
     if(Nudge_Model) call nudging_final()
 
     if(use_hemco) then
-        ! cleanup hemco
-        call HCOI_Chunk_Final
+       ! cleanup hemco
+       call HCOI_Chunk_Final
     endif
 
+    call ctem_diags_final()
+
   end subroutine phys_final