Added new files to allow Gross Unrepresented Land Use transition

bld/CLMBuildNamelist.pm

@@ -2491,6 +2491,7 @@ sub setup_logic_dynamic_subgrid {
    setup_logic_do_transient_lakes($opts, $nl_flags, $definition, $defaults, $nl);
    setup_logic_do_transient_urban($opts, $nl_flags, $definition, $defaults, $nl);
    setup_logic_do_harvest($opts, $nl_flags, $definition, $defaults, $nl);
+   setup_logic_do_grossunrep($opts, $nl_flags, $definition, $defaults, $nl);
 
    add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'reset_dynbal_baselines');
    if ( &value_is_true($nl->get_value('reset_dynbal_baselines')) &&
@@ -2836,6 +2837,63 @@ sub setup_logic_do_harvest {
 
 #-------------------------------------------------------------------------------
 
+sub setup_logic_do_grossunrep {
+   #
+   # Set do_grossunrep default value, and perform error checking on do_grossunrep
+   #
+   # Assumes the following are already set in the namelist (although it's okay
+   # for them to be unset if that will be their final state):
+   # - flanduse_timeseries
+   # - use_cn
+   # - use_fates
+   #
+   my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
+
+   my $var = 'do_grossunrep';
+
+   # Start by assuming a default value of '.true.'. Then check a number of
+   # conditions under which do_grossunrep cannot be true. Under these
+   # conditions: (1) set default value to '.false.'; (2) make sure that the
+   # value is indeed false (e.g., that the user didn't try to set it to true).
+
+   my $default_val = ".false.";
+
+   # cannot_be_true will be set to a non-empty string in any case where
+   # do_grossunrep should not be true; if it turns out that do_grossunrep IS true
+   # in any of these cases, a fatal error will be generated
+   my $cannot_be_true = "";
+
+   if (string_is_undef_or_empty($nl->get_value('flanduse_timeseries'))) {
+      $cannot_be_true = "$var can only be set to true when running a transient case (flanduse_timeseries non-blank)";
+   }
+   elsif (&value_is_true($nl->get_value('use_fates'))) {
+      $cannot_be_true = "$var currently doesn't work with FATES";
+   }
+   elsif (!&value_is_true($nl->get_value('use_cn'))) {
+      $cannot_be_true = "$var can only be set to true when running with CN (use_cn = true)";
+   }
+
+   if ($cannot_be_true) {
+      $default_val = ".false.";
+   }
+
+   if (!$cannot_be_true) {
+      # Note that, if the variable cannot be true, we don't call add_default
+      # - so that we don't clutter up the namelist with variables that don't
+      # matter for this case
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, $var, val=>$default_val);
+   }
+
+   # Make sure the value is false when it needs to be false - i.e., that the
+   # user hasn't tried to set a true value at an inappropriate time.
+
+   if (&value_is_true($nl->get_value($var)) && $cannot_be_true) {
+      $log->fatal_error($cannot_be_true);
+   }
+
+}
+
+#-------------------------------------------------------------------------------
 sub setup_logic_spinup {
   my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
 

bld/namelist_files/namelist_definition_ctsm.xml

@@ -2475,6 +2475,13 @@ If TRUE, apply harvest from flanduse_timeseries file.
 (Also, only valid for use_cn = true.)
 </entry>
 
+<entry id="do_grossunrep" type="logical" category="physics"
+       group="dynamic_subgrid" valid_values="" >
+If TRUE, apply gross unrepresented landuse/land-cover change from flanduse_timeseries file.
+(Only valid for transient runs, where there is a flanduse_timeseries file.)
+(Also, only valid for use_cn = true.)
+</entry>
+
 <entry id="reset_dynbal_baselines" type="logical" category="physics"
        group="dynamic_subgrid" valid_values="">
 If TRUE, reset baseline values of total column water and energy in the

bld/unit_testers/build-namelist_test.pl

@@ -163,7 +163,7 @@ sub cat_and_create_namelistinfile {
 #
 # Figure out number of tests that will run
 #
-my $ntests = 1847;
+my $ntests = 1850;
 if ( defined($opts{'compare'}) ) {
    $ntests += 1254;
 }
@@ -1061,6 +1061,21 @@ sub cat_and_create_namelistinfile {
                                      GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm5_0",
                                    },
+     "dogrossandsp"               =>{ options=>"--envxml_dir . --bgc sp --use_case 20thC_transient",
+                                     namelst=>"do_grossunrep=.true.",
+                                     GLC_TWO_WAY_COUPLING=>"FALSE",
+                                     phys=>"clm5_0",
+                                   },
+     "dogrossandfates"            =>{ options=>"--envxml_dir . --bgc fates --use_case 20thC_transient --no-megan",
+                                     namelst=>"do_grossunrep=.true.",
+                                     GLC_TWO_WAY_COUPLING=>"FALSE",
+                                     phys=>"clm5_0",
+                                   },
+     "dogrossandnottrans"         =>{ options=>"--envxml_dir . --bgc bgc --use_case 2000_control",
+                                     namelst=>"do_grossunrep=.true.",
+                                     GLC_TWO_WAY_COUPLING=>"FALSE",
+                                     phys=>"clm5_0",
+                                   },
      "nocropwfert"                =>{ options=>"-envxml_dir . -bgc sp -no-crop",
                                      namelst=>"use_fertilizer=T",
                                      GLC_TWO_WAY_COUPLING=>"FALSE",
@@ -1444,7 +1459,7 @@ sub cat_and_create_namelistinfile {
 my $usecase  = "20thC_transient";
 my $GLC_NEC         = 10;
 foreach my $res ( @tran_res ) {
-   $options = "-res $res -use_case $usecase -envxml_dir . -namelist '&a start_ymd=18500101/'";
+   $options = "-res $res -use_case $usecase -envxml_dir . -namelist '&a start_ymd=18500101/' -bgc bgc -crop -namelist '&a do_grossunrep=T/'";
    &make_env_run();
    eval{ system( "$bldnml $options > $tempfile 2>&1 " ); };
    is( $@, '', "$options" );

cime_config/testdefs/testlist_clm.xml

@@ -462,13 +462,43 @@
       <option name="wallclock">00:20:00</option>
     </options>
   </test>
-  <test name="ERP_D_Ld10_P36x2" grid="f10_f10_mg37" compset="IHistClm51BgcCrop" testmods="clm/ciso_decStart">
+  <test name="ERP_D_Ld10" grid="f10_f10_mg37" compset="IHistClm50BgcCrop" testmods="clm/ciso_decStart_GU_LULCC">
+    <machines>
+      <machine name="izumi" compiler="nag" category="aux_clm"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment"  >Transient case with isotopes with a december start, and Gross Unrepresented Land Use and Land Cover change on, default dataset with GU_LULCC==0</option>
+    </options>
+  </test>
+  <test name="ERP_D_Ld10_P36x2" grid="f10_f10_mg37" compset="IHistClm50BgcCrop" testmods="clm/ciso_decStart_GU_LULCC">
     <machines>
       <machine name="cheyenne" compiler="intel" category="aux_clm"/>
     </machines>
     <options>
-      <option name="wallclock">00:20:00</option>
-      <option name="comment"  >Transient case with isotopes with a december start</option>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment"  >Transient case with isotopes with a december start, and Gross Unrepresented Land Use and Land Cover change on, default dataset with GU_LULCC==0</option>
+    </options>
+  </test>
+  <test name="ERP_D_Ld10" grid="f09_f09_mg17" compset="IHistClm50BgcCrop" testmods="clm/f09_dec1990Start_GU_LULCC">
+    <machines>
+      <machine name="cheyenne" compiler="intel" category="aux_clm"/>
+      <machine name="cheyenne" compiler="gnu" category="aux_clm"/>
+      <machine name="izumi" compiler="nag" category="aux_clm"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:59:00</option>
+      <option name="comment"  >Transient case with a December 1990 start, and Gross Unrepresented Land Use and Land Cover change on, with f09 datasets with non-zero GU_LULCC values</option>
+    </options>
+  </test>
+  <test name="SMS_Ld10" grid="f09_f09_mg17" compset="IHistClm50BgcCrop" testmods="clm/f09_dec1990Start_GU_LULCC_monthly">
+    <machines>
+      <machine name="cheyenne" compiler="intel" category="aux_clm"/>
+      <machine name="cheyenne" compiler="gnu" category="aux_clm"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment"  >Transient case with a December 1990 start, and Gross Unrepresented Land Use and Land Cover change on, with f09 datasets with non-zero GU_LULCC values</option>
     </options>
   </test>
   <test name="ERP_D_Ld10_P36x2_Vmct" grid="f10_f10_mg37" compset="IHistClm51BgcCrop" testmods="clm/ciso_decStart">

cime_config/testdefs/testmods_dirs/clm/ciso_decStart_GU_LULCC/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/ciso_decStart_GU_LULCC/user_nl_clm

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

cime_config/testdefs/testmods_dirs/clm/f09_dec1990Start_GU_LULCC/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/f09_dec1990Start_GU_LULCC/shell_commands

@@ -0,0 +1,3 @@
+./xmlchange RUN_STARTDATE=1990-12-25
+# Ignore warnings because we are using crop, but starting from a different date than the initial conditions were for
+./xmlchange CLM_BLDNML_OPTS=-ignore_warnings --append

cime_config/testdefs/testmods_dirs/clm/f09_dec1990Start_GU_LULCC/user_nl_clm

@@ -0,0 +1,5 @@
+ ! Specify a dataset that has non-zero Gross Unrepresented Land Use change fields on it
+ ! And turn it on
+ flanduse_timeseries = '$DIN_LOC_ROOT/lnd/clm2/surfdata_map/ctsm5.1.dev052/landuse.timeseries_0.9x1.25_hist_78pfts_CMIP6_simyr1700-2021_c220825.nc'
+ fsurdat = '$DIN_LOC_ROOT/lnd/clm2/surfdata_map/ctsm5.1.dev052/surfdata_0.9x1.25_hist_78pfts_CMIP6_simyr1700_c220825.nc'
+ do_grossunrep = .true.

cime_config/testdefs/testmods_dirs/clm/f09_dec1990Start_GU_LULCC_monthly/include_user_mods

@@ -0,0 +1,2 @@
+../f09_dec1990Start_GU_LULCC
+../monthly

doc/ChangeLog

@@ -1,4 +1,88 @@
 ===============================================================
+Tag name: ctsm5.1.dev119
+Originator(s): slevis (Samuel Levis,SLevis Consulting,303-665-1310), ekluzek Erik Kluzek), lawrencepj1 (Peter Lawrence)
+Date: Thu Mar 16 14:13:37 MDT 2023
+One-line Summary: Allow gross unrepresented land use transitions (PR #309)
+
+Purpose and description of changes
+----------------------------------
+
+ Get gross unrepresented land use transitions working in CLM5.1. This is additional optional
+ data added to the landuse.timeseries files for transient simulations. The current landuse.timseries
+ files have this data, but it's set to zero. This data will be part of the CTSM5.2 surface dataset
+ (that is upcoming) and be on by default for clm5_3 physics.
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics
+onfigurations?
+(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
+hanges.]
+
+[ ] clm5_1
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed or introduced
+------------------------
+ Known bugs introduced in this tag (include issue #): #1968
+   #1968 -- Reduce the GULU tests down to one
+
+Notes of particular relevance for users
+---------------------------------------
+Changes made to namelist defaults (e.g., changed parameter values):
+ New namelist variable: do_grossunrep
+
+Changes to the datasets (e.g., parameter, surface or initial files):
+ Surface datasets may now contain non-zero gross unrepresented land use
+ transitions.
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Changes to tests or testing:
+ Erik introduced new tests that can be identified by the GU_LULCC in
+ their names. I ran these with the test-suites and generated baselines
+ for them.
+
+Testing summary:
+----------------
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    cheyenne ---- OK
+    izumi ------- OK
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: NO (unless see next)
+
+ Code configurations: do_grossunrep = .true. and surface dataset
+                      includes non-zero gross unrepresented land use
+                      transitions. I (slevis) have not investigated the
+                      nature of the changes.
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/309 -- Added new files to allow Gross Unrepresented Land Use transition
+ https://github.com/ESCOMP/ctsm/pull/1965 -- update README
+ (NOT a PR) Update manage externals
+
+
+
+===============================================================
+===============================================================
 Tag name: ctsm5.1.dev118
 Originator(s): slevis (Samuel Levis,SLevis Consulting,303-665-1310)
 Date: Sun Feb  5 18:31:29 MST 2023

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+    ctsm5.1.dev119   slevis 03/16/2023 Allow gross unrepresented land use transition (PR #309)
     ctsm5.1.dev118   slevis 02/05/2023 Use conda environment rather than ncar_pylib with the fsurdat_modifier system test
     ctsm5.1.dev117  afoster 02/02/2023 Updates to facilitate running FATES at NEON sites
     ctsm5.1.dev116     erik 01/26/2023 Small answer changes with bug fixes, zetamaxstable=2 for BHS, new single point fsurdat files