Merge pull request #3328 from slevis-lmwg/upd_pfts1d_wt_with_time

ctsm5.3.064: Add time dimension to *1d_wt* fields that change in transient simulations

Author: slevis-lmwg

bld/CLMBuildNamelist.pm

@@ -2867,14 +2867,20 @@ sub setup_logic_do_transient_pfts {
    }
 
    # if do_transient_pfts is .true. and any of these (n_dom_* or toosmall_*)
-   # are > 0 or collapse_urban = .true., then give fatal error
+   # are > 0 or collapse_urban = .true., or vars_1dwt_w_time = .false., then give fatal error
    if (&value_is_true($nl->get_value($var))) {
       if (&value_is_true($nl->get_value('collapse_urban'))) {
          $log->fatal_error("$var cannot be combined with collapse_urban");
       }
       if ($n_dom_pfts > 0 || $n_dom_landunits > 0 || $toosmall_soil > 0 || $toosmall_crop > 0 || $toosmall_glacier > 0 || $toosmall_lake > 0 || $toosmall_wetland > 0 || $toosmall_urban > 0) {
          $log->fatal_error("$var cannot be combined with any of the of the following > 0: n_dom_pfts > 0, n_dom_landunit > 0, toosmall_soi > 0._r8, toosmall_crop > 0._r8, toosmall_glacier > 0._r8, toosmall_lake > 0._r8, toosmall_wetland > 0._r8, toosmall_urban > 0._r8");
       }
+
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'vars_1dwt_w_time',
+               'do_transient_pfts'=>$nl_flags->{'do_transient_pfts'});
+      if (!&value_is_true($nl->get_value('vars_1dwt_w_time'))) {
+        $log->fatal_error("vars_1dwt_w_time cannot be .false. if do_transient_pfts is .true.");
+      }
    }
 }
 
@@ -2944,14 +2950,20 @@ sub setup_logic_do_transient_crops {
    }
 
    # if do_transient_crops is .true. and any of these (n_dom_* or toosmall_*)
-   # are > 0 or collapse_urban = .true., then give fatal error
+   # are > 0 or collapse_urban = .true., or vars_1dwt_w_time = .false., then give fatal error
    if (&value_is_true($nl->get_value($var))) {
       if (&value_is_true($nl->get_value('collapse_urban'))) {
          $log->fatal_error("$var cannot be combined with collapse_urban");
       }
       if ($n_dom_pfts > 0 || $n_dom_landunits > 0 || $toosmall_soil > 0 || $toosmall_crop > 0 || $toosmall_glacier > 0 || $toosmall_lake > 0 || $toosmall_wetland > 0 || $toosmall_urban > 0) {
          $log->fatal_error("$var cannot be combined with any of the of the following > 0: n_dom_pfts > 0, n_dom_landunit > 0, toosmall_soil > 0._r8, toosmall_crop > 0._r8, toosmall_glacier > 0._r8, toosmall_lake > 0._r8, toosmall_wetland > 0._r8, toosmall_urban > 0._r8");
       }
+
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'vars_1dwt_w_time',
+               'do_transient_crops'=>$nl_flags->{'do_transient_crops'});
+      if (!&value_is_true($nl->get_value('vars_1dwt_w_time'))) {
+        $log->fatal_error("vars_1dwt_w_time cannot be .false. if do_transient_crops is .true.");
+      }
    }
 
    my $dopft = "do_transient_pfts";
@@ -3021,7 +3033,7 @@ sub setup_logic_do_transient_lakes {
    }
 
    # if do_transient_lakes is .true. and any of these (n_dom_* or toosmall_*)
-   # are > 0 or collapse_urban = .true., then give fatal error
+   # are > 0 or collapse_urban = .true., or vars_1dwt_w_time = .false., then give fatal error
    if (&value_is_true($nl->get_value($var))) {
       if (&value_is_true($nl->get_value('collapse_urban'))) {
          $log->fatal_error("$var cannot be combined with collapse_urban");
@@ -3031,6 +3043,12 @@ sub setup_logic_do_transient_lakes {
       if ($n_dom_pfts > 0 || $n_dom_landunits > 0 || $toosmall_soil > 0 || $toosmall_crop > 0 || $toosmall_glacier > 0 || $toosmall_lake > 0 || $toosmall_wetland > 0 || $toosmall_urban > 0) {
          $log->fatal_error("$var cannot be combined with any of the of the following > 0: n_dom_pfts > 0, n_dom_landunit > 0, toosmall_soil > 0._r8, toosmall_crop > 0._r8, toosmall_glacier > 0._r8, toosmall_lake > 0._r8, toosmall_wetland > 0._r8, toosmall_urban > 0._r8");
       }
+
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'vars_1dwt_w_time',
+               'do_transient_lakes'=>$nl_flags->{'do_transient_lakes'});
+      if (!&value_is_true($nl->get_value('vars_1dwt_w_time'))) {
+        $log->fatal_error("vars_1dwt_w_time cannot be .false. if do_transient_lakes is .true.");
+      }
    }
 }
 
@@ -3093,7 +3111,7 @@ sub setup_logic_do_transient_urban {
    }
 
    # if do_transient_urban is .true. and any of these (n_dom_* or toosmall_*)
-   # are > 0 or collapse_urban = .true., then give fatal error
+   # are > 0 or collapse_urban = .true., or vars_1dwt_w_time = .false., then give fatal error
    if (&value_is_true($nl->get_value($var))) {
       if (&value_is_true($nl->get_value('collapse_urban'))) {
          $log->fatal_error("$var cannot be combined with collapse_urban");
@@ -3103,6 +3121,12 @@ sub setup_logic_do_transient_urban {
       if ($n_dom_pfts > 0 || $n_dom_landunits > 0 || $toosmall_soil > 0 || $toosmall_crop > 0 || $toosmall_glacier > 0 || $toosmall_lake > 0 || $toosmall_wetland > 0 || $toosmall_urban > 0) {
          $log->fatal_error("$var cannot be combined with any of the of the following > 0: n_dom_pfts > 0, n_dom_landunit > 0, toosmall_soil > 0._r8, toosmall_crop > 0._r8, toosmall_glacier > 0._r8, toosmall_lake > 0._r8, toosmall_wetland > 0._r8, toosmall_urban > 0._r8");
       }
+
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'vars_1dwt_w_time',
+               'do_transient_urban'=>$nl_flags->{'do_transient_urban'});
+      if (!&value_is_true($nl->get_value('vars_1dwt_w_time'))) {
+        $log->fatal_error("vars_1dwt_w_time cannot be .false. if do_transient_urban is .true.");
+      }
    }
 }
 

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -2472,6 +2472,11 @@ lnd/clm2/surfdata_esmf/NEON/ctsm5.3.0/surfdata_1x1_NEON_TOOL_hist_2000_78pfts_c2
 <do_transient_lakes>.false.</do_transient_lakes>
 <do_transient_urban>.false.</do_transient_urban>
 <reset_dynbal_baselines>.false.</reset_dynbal_baselines>
+<vars_1dwt_w_time do_transient_pfts=".true.">.true.</vars_1dwt_w_time>
+<vars_1dwt_w_time do_transient_crops=".true.">.true.</vars_1dwt_w_time>
+<vars_1dwt_w_time do_transient_lakes=".true.">.true.</vars_1dwt_w_time>
+<vars_1dwt_w_time do_transient_urban=".true.">.true.</vars_1dwt_w_time>
+<vars_1dwt_w_time>.false.</vars_1dwt_w_time>
 
 <!-- =========================================  -->
 <!-- Defaults for water tracers                 -->

bld/namelist_files/namelist_definition_ctsm.xml

@@ -2779,6 +2779,15 @@ or more, which causes CAM to blow up. However, note that setting it to true will
 break water and energy conservation!
 </entry>
 
+<entry id="vars_1dwt_w_time" type="logical" category="physics"
+       group="dynamic_subgrid" valid_values="" >
+A TRUE setting adds the time dimension to all 1dwt variables that appear in
+files generated as a result of hist_dov2xy = .false. (e.g. pfts1d_wtcol).
+Transient simulations (run_has_transient_landcover = .true.) have the same
+outcome as vars_1dwt_w_time = .true..
+Use this flag if you wish to change FALSE to TRUE when run_has_transient_landcover = .false..
+</entry>
+
 <!-- ========================================================================================  -->
 <!-- Namelist options related to finidat consistency checks                                    -->
 <!-- ========================================================================================  -->

doc/ChangeLog

@@ -1,4 +1,81 @@
 ===============================================================
+Tag name: ctsm5.3.064
+Originator(s): slevis (Samuel Levis)
+Date: Thu 24 Jul 2025 01:13:00 PM MDT
+One-line Summary: Add time dimension to 1d_wt fields in transient runs
+
+Purpose and description of changes
+----------------------------------
+
+ 1d_wt fields (e.g. pfts1d_wtgcell) appear in history when hist_dov2xy = .false.
+ This PR:
+ - adds the time dimension to these variables in Hist runs because these variables change with time
+ - adds new namelist variable vars_1dwt_w_time to let users add the time dimension when it is not added by default, i.e. in non-transient runs
+ - throws a build namelist error when the new namelist variable is .false. in a transient simulation
+
+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]:
+ Resolves #3307 Updating vector history file output...
+
+Notes of particular relevance for users
+---------------------------------------
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+ New namelist variable vars_1dwt_w_time; user will get an error if they set it to .false. when any of the following is .true.:
+ do_transient_pfts, do_transient_crops, do_transient_lakes, do_transient_urban
+
+Changes made to namelist defaults (e.g., changed parameter values):
+ vars_1dwt_w_time defaults to true when any of the following is .true.:
+ do_transient_pfts, do_transient_crops, do_transient_lakes, do_transient_urban
+ else vars_1dwt_w_time defaults to .false.
+
+Changes to documentation:
+ Added vars_1dwt_w_time to namelist_definition_ctsm.xml with an explanation of its use
+
+Testing summary:
+----------------
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho - PASS
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: Yes
+ - 1d_wt fields with the time dimension will display different answers in transient simulations, though this is diagnostic in nature.
+ - Only one test is affected in aux_clm: RXCROPMATURITYSKIPGEN_Ld1097.f10_f10_mg37.IHistClm60BgcCrop.derecho_intel.clm-cropMonthOutput
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/3328
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.063
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Thu Jul 10 12:28:36 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.064   slevis 07/24/2025 Add time dimension to 1d_wt fields in transient runs
        ctsm5.3.063 samrabin 07/10/2025 Merge b4b-dev to master
        ctsm5.3.062   slevis 07/09/2025 Put inst. and non-inst. fields on separate hist files
        ctsm5.3.061   slevis 06/26/2025 Merge b4b-dev to master

src/dyn_subgrid/dynSubgridControlMod.F90

@@ -26,6 +26,7 @@ module dynSubgridControlMod
   public :: get_do_transient_crops  ! return the value of the do_transient_crops control flag
   public :: get_do_transient_lakes  ! return the value of the do_transient_lakes control flag
   public :: get_do_transient_urban  ! return the value of the do_transient_urban control flag
+  public :: get_vars_1dwt_w_time  ! return the value of the vars_1dwt_w_time control flag
   public :: run_has_transient_landcover ! returns true if any aspects of prescribed transient landcover are enabled
   public :: get_do_harvest          ! return the value of the do_harvest control flag
   public :: get_do_grossunrep       ! return the value of the do_grossunrep control flag
@@ -47,6 +48,7 @@ module dynSubgridControlMod
      logical :: do_transient_urban = .false. ! whether to apply transient urban from dataset
      logical :: do_harvest         = .false. ! whether to apply harvest from dataset
      logical :: do_grossunrep      = .false. ! whether to apply gross unrepresented landcover change from dataset
+     logical :: vars_1dwt_w_time = .false. ! whether to add the time dimension to 1dwt variables, e.g. pfts1d_wtcol
 
      logical :: reset_dynbal_baselines = .false. ! whether to reset baseline values of total column water and energy in the first step of the run
 
@@ -126,6 +128,7 @@ subroutine read_namelist( NLFilename )
     logical :: do_transient_urban
     logical :: do_harvest
     logical :: do_grossunrep
+    logical :: vars_1dwt_w_time
     logical :: reset_dynbal_baselines
     logical :: for_testing_allow_non_annual_changes
     logical :: for_testing_zero_dynbal_fluxes
@@ -144,6 +147,7 @@ subroutine read_namelist( NLFilename )
          do_transient_urban, &
          do_harvest, &
          do_grossunrep, &
+         vars_1dwt_w_time, &
          reset_dynbal_baselines, &
          for_testing_allow_non_annual_changes, &
          for_testing_zero_dynbal_fluxes
@@ -156,6 +160,7 @@ subroutine read_namelist( NLFilename )
     do_transient_urban = .false.
     do_harvest         = .false.
     do_grossunrep      = .false.
+    vars_1dwt_w_time = .false.
     reset_dynbal_baselines = .false.
     for_testing_allow_non_annual_changes = .false.
     for_testing_zero_dynbal_fluxes = .false.
@@ -183,6 +188,7 @@ subroutine read_namelist( NLFilename )
     call shr_mpi_bcast (do_transient_urban, mpicom)
     call shr_mpi_bcast (do_harvest, mpicom)
     call shr_mpi_bcast (do_grossunrep, mpicom)
+    call shr_mpi_bcast (vars_1dwt_w_time, mpicom)
     call shr_mpi_bcast (reset_dynbal_baselines, mpicom)
     call shr_mpi_bcast (for_testing_allow_non_annual_changes, mpicom)
     call shr_mpi_bcast (for_testing_zero_dynbal_fluxes, mpicom)
@@ -195,6 +201,7 @@ subroutine read_namelist( NLFilename )
          do_transient_urban = do_transient_urban, &
          do_harvest = do_harvest, &
          do_grossunrep = do_grossunrep, &
+         vars_1dwt_w_time = vars_1dwt_w_time, &
          reset_dynbal_baselines = reset_dynbal_baselines, &
          for_testing_allow_non_annual_changes = for_testing_allow_non_annual_changes, &
          for_testing_zero_dynbal_fluxes = for_testing_zero_dynbal_fluxes)
@@ -397,6 +404,18 @@ logical function get_do_transient_urban()
 
   end function get_do_transient_urban
 
+  !-----------------------------------------------------------------------
+  logical function get_vars_1dwt_w_time()
+    ! !DESCRIPTION:
+    ! Return the value of the vars_1dwt_w_time control flag
+    !-----------------------------------------------------------------------
+
+    SHR_ASSERT_FL(dyn_subgrid_control_inst%initialized, sourcefile, __LINE__)
+
+    get_vars_1dwt_w_time = dyn_subgrid_control_inst%vars_1dwt_w_time
+
+  end function get_vars_1dwt_w_time
+
   !-----------------------------------------------------------------------
   logical function run_has_transient_landcover()
     ! !DESCRIPTION:
@@ -406,6 +425,7 @@ logical function run_has_transient_landcover()
     run_has_transient_landcover = &
          (get_do_transient_pfts() .or. &
          get_do_transient_crops() .or. &
+         get_do_transient_lakes() .or. &
          get_do_transient_urban())
   end function run_has_transient_landcover