Merge tag 'ctsm5.1.dev003' into heat_storage_biomass

Add capability for dynamic lakes

Adds the capability for dynamic lake areas, read from the
landuse_timeseries file. This represents reservoir construction. For
now, this capability is off by default. Turning it on requires new
fields on the landuse_timeseries file which cannot yet be produced by
mksurfdata_map; these new fields will be added in
ESCOMP#1073.

A substantial part of this tag involved changing the accounting of water
and energy in lakes in order to conserve water and energy across
landunit transitions while not producing too large adjustment
fluxes. This change results in roundoff-level answer changes for all
transient cases.

The core changes in this tag are from Inne Vanderkelen, in consultation
with Bill Sacks. Additional changes are from Bill Sacks, in consultation
with Inne Vanderkelen.

 Conflicts:
	bld/namelist_files/namelist_defaults_ctsm.xml
	src/biogeophys/CanopyFluxesMod.F90

.config_files.xml

@@ -5,19 +5,20 @@
 <entry_id>
 
   <!-- This is the same as the default entry in
-       cime/config/cesm/config_files.xml except for the value for clm:
-       In a standalone clm checkout, COMP_ROOT_DIR_LND is $SRCROOT
+       cime/config/cesm/config_files.xml except for the value for CTSM:
+       In a standalone CTSM checkout, COMP_ROOT_DIR_LND is $SRCROOT
        rather than $SRCROOT/components/clm.
 
        However, because of the way overrides are handled, we need to
        re-specify the full information here rather than just overriding
-       the value for clm.
+       the value for CTSM.
   -->
   <entry id="COMP_ROOT_DIR_LND">
     <type>char</type>
     <default_value>unset</default_value>
     <values>
-      <value component="clm"      >$SRCROOT</value>
+      <value component="clm"       >$SRCROOT</value>
+      <value component="ctsm"      >$SRCROOT</value>
       <value component="dlnd" comp_interface="mct">$CIMEROOT/src/components/data_comps_mct/dlnd</value>
       <value component="dlnd" comp_interface="nuopc">$CIMEROOT/src/components/cdeps/dlnd</value>
       <value component="slnd"      >$CIMEROOT/src/components/stub_comps_$COMP_INTERFACE/slnd</value>

.gitignore

@@ -72,6 +72,7 @@ buildnmlc
 /bld/unit_testers/drv_flds_in*
 /bld/unit_testers/temp_file.txt*
 /bld/unit_testers/user_nl_clm_real_parameters*
+/bld/unit_testers/user_nl_ctsm_real_parameters*
 /bld/unit_testers/env_run.xml
 
 # tools testing output
@@ -86,8 +87,8 @@ surfdata_*.namelist
 landuse.timeseries_*.namelist
 landuse.timeseries_*.log
 landuse_timeseries_*.txt
-clm.input_data_list
-clm.input_data_list.previous
+ctsm.input_data_list
+ctsm.input_data_list.previous
 *.stdout.txt.o*
 
 # mksurfdata unit tests

bld/CLMBuildNamelist.pm

@@ -1486,7 +1486,7 @@ sub process_namelist_inline_logic {
   ##############################
   # namelist group: clm_inparm #
   ##############################
-  setup_logic_site_specific($nl_flags, $definition, $nl);
+  setup_logic_site_specific($opts, $nl_flags, $definition, $defaults, $nl);
   setup_logic_lnd_frac($opts, $nl_flags, $definition, $defaults, $nl, $envxml_ref);
   setup_logic_co2_type($opts, $nl_flags, $definition, $defaults, $nl);
   setup_logic_irrigate($opts, $nl_flags, $definition, $defaults, $nl);
@@ -1715,7 +1715,7 @@ sub process_namelist_inline_logic {
 
 sub setup_logic_site_specific {
   # site specific requirements
-  my ($nl_flags, $definition, $nl) = @_;
+  my ($opts, $nl_flags, $definition, $defaults, $nl, $physv) = @_;
 
   # res check prevents polluting the namelist with an unnecessary
   # false variable for every run
@@ -1746,6 +1746,9 @@ sub setup_logic_site_specific {
       $log->fatal_error("1x1_numaIA grids must use a compset with CN and CROP turned on.");
     }
   }
+  #  Set compname
+  add_default($opts,  $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'compname',
+              'phys'=>$nl_flags->{'phys'} );
 }
 
 #-------------------------------------------------------------------------------
@@ -2378,6 +2381,7 @@ sub setup_logic_dynamic_subgrid {
 
    setup_logic_do_transient_pfts($opts, $nl_flags, $definition, $defaults, $nl);
    setup_logic_do_transient_crops($opts, $nl_flags, $definition, $defaults, $nl);
+   setup_logic_do_transient_lakes($opts, $nl_flags, $definition, $defaults, $nl);
    setup_logic_do_harvest($opts, $nl_flags, $definition, $defaults, $nl);
 
    add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'reset_dynbal_baselines');
@@ -2543,6 +2547,69 @@ sub setup_logic_do_transient_crops {
    }
 }
 
+sub setup_logic_do_transient_lakes {
+   #
+   # Set do_transient_lakes default value, and perform error checking on do_transient_lakes
+   #
+   # 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
+   #
+   # NOTE(wjs, 2020-08-23) I based this function on setup_logic_do_transient_crops. I'm
+   # not sure if all of the checks here are truly important for transient lakes (in
+   # particular, my guess is that collapse_urban could probably be done with transient
+   # lakes - as well as transient pfts and transient crops for that matter), but some of
+   # the checks probably are needed, and it seems best to keep transient lakes consistent
+   # with other transient areas in this respect.
+   my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
+
+   my $var = 'do_transient_lakes';
+
+   # cannot_be_true will be set to a non-empty string in any case where
+   # do_transient_lakes should not be true; if it turns out that
+   # do_transient_lakes IS true in any of these cases, a fatal error will be
+   # generated
+   my $cannot_be_true = "";
+
+   my $n_dom_pfts = $nl->get_value( 'n_dom_pfts' );
+   my $n_dom_landunits = $nl->get_value( 'n_dom_landunits' );
+   my $toosmall_soil = $nl->get_value( 'toosmall_soil' );
+   my $toosmall_crop = $nl->get_value( 'toosmall_crop' );
+   my $toosmall_glacier = $nl->get_value( 'toosmall_glacier' );
+   my $toosmall_lake = $nl->get_value( 'toosmall_lake' );
+   my $toosmall_wetland = $nl->get_value( 'toosmall_wetland' );
+   my $toosmall_urban = $nl->get_value( 'toosmall_urban' );
+
+   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)";
+   }
+
+   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);
+   }
+
+   # 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);
+   }
+
+   # if do_transient_lakes is .true. and any of these (n_dom_* or toosmall_*)
+   # are > 0 or collapse_urban = .true., 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");
+      }
+   }
+}
+
 sub setup_logic_do_harvest {
    #
    # Set do_harvest default value, and perform error checking on do_harvest
@@ -3420,7 +3487,7 @@ sub setup_logic_megan {
 #-------------------------------------------------------------------------------
 
 sub setup_logic_soilm_streams {
-  # prescribed soil moisture streams require clm4_5/clm5_0
+  # prescribed soil moisture streams require clm4_5/clm5_0/clm5_1
   my ($opts, $nl_flags, $definition, $defaults, $nl, $physv) = @_;
 
       add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_soil_moisture_streams');

bld/config_files/clm_phys_vers.pm

@@ -28,7 +28,7 @@ use bigint;
 #use warnings;
 #use diagnostics;
 
-my @version_strings = ("clm4_5", "clm5_0");
+my @version_strings = ("clm4_5", "clm5_0", "clm5_1");
 
 #-------------------------------------------------------------------------------
 
@@ -83,12 +83,12 @@ if ( ! defined(caller) && $#ARGV == -1 ) {
    require Test::More;
    Test::More->import( );
 
-   plan( tests=>2 );
+   plan( tests=>3 );
 
    sub testit {
       print "unit tester\n";
       my %lastv;
-      my @vers_list = ( "clm4_5", "clm5_0" );
+      my @vers_list = ( "clm4_5", "clm5_0", "clm5_1" );
       foreach my $vers ( @vers_list ) {
          my $phys = config_files::clm_phys_vers->new($vers);
          isa_ok($phys, "config_files::clm_phys_vers", "created clm_phys_vers object");

bld/config_files/config_definition_ctsm.xml

@@ -5,10 +5,10 @@
 <config_definition>
 
 <entry id="phys" 
-       valid_values="clm4_5,clm5_0"
+       valid_values="clm4_5,clm5_0,clm5_1"
        value="clm4_5"
        category="physics">
-Specifies either clm4_5 or clm5_0 physics
+Specifies either clm4_5, clm5_0, or clm5_1 physics
 </entry>
 
 <entry id="clm_root" 

bld/listDefaultNamelist.pl

@@ -97,7 +97,7 @@ sub make_config_cache {
 <?xml version="1.0"?>
 <config_definition>
 <commandline></commandline>
-<entry id="phys" value="$phys" list="" valid_values="clm4_5,clm5_0">Specifies clm physics</entry>
+<entry id="phys" value="$phys" list="" valid_values="clm4_5,clm5_0,clm5_1">Specifies clm physics</entry>
 </config_definition>
 EOF
    $fh->close();