Merge tag 'ctsm5.1.dev170' into multilayer_canopy

Add hillslope hydrology parameterization

Changes include multiple soil columns per vegetated landunit, additional meteorological downscaling, new subsurface lateral flow equations, and a hillslope routing parameterization.

Externals.cfg

@@ -98,4 +98,4 @@ tag = v1.0.8
 required = False
 
 [externals_description]
-schema_version = 1.0.0
+schema_version = 1.0.0

bld/CLMBuildNamelist.pm

@@ -1577,6 +1577,7 @@ sub process_namelist_inline_logic {
   setup_logic_glacier($opts, $nl_flags, $definition, $defaults, $nl,  $envxml_ref);
   setup_logic_dynamic_plant_nitrogen_alloc($opts, $nl_flags, $definition, $defaults, $nl, $physv);
   setup_logic_luna($opts, $nl_flags, $definition, $defaults, $nl, $physv);
+  setup_logic_hillslope($opts, $nl_flags, $definition, $defaults, $nl);
   setup_logic_o3_veg_stress_method($opts, $nl_flags, $definition, $defaults, $nl,$physv);
   setup_logic_hydrstress($opts,  $nl_flags, $definition, $defaults, $nl);
   setup_logic_dynamic_roots($opts,  $nl_flags, $definition, $defaults, $nl, $physv);
@@ -2706,6 +2707,8 @@ sub setup_logic_do_transient_pfts {
       $cannot_be_true = "$var cannot be combined with use_cndv";
    } elsif (&value_is_true($nl->get_value('use_fates'))) {
       $cannot_be_true = "$var cannot be combined with use_fates";
+   } elsif (&value_is_true($nl->get_value('use_hillslope'))) {
+      $cannot_be_true = "$var cannot be combined with use_hillslope";
    }
 
    if ($cannot_be_true) {
@@ -2781,6 +2784,8 @@ sub setup_logic_do_transient_crops {
       # do_transient_crops. However, this hasn't been tested, so to be safe,
       # we are not allowing this combination for now.
       $cannot_be_true = "$var has not been tested with FATES, so for now these two options cannot be combined";
+   } elsif (&value_is_true($nl->get_value('use_hillslope'))) {
+      $cannot_be_true = "$var cannot be combined with use_hillslope";
    }
 
    if ($cannot_be_true) {
@@ -2876,6 +2881,8 @@ sub setup_logic_do_transient_lakes {
    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");
+      } elsif (&value_is_true($nl->get_value('use_hillslope'))) {
+         $log->fatal_error("$var cannot be combined with use_hillslope");
       }
       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");
@@ -2939,6 +2946,8 @@ sub setup_logic_do_transient_urban {
    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");
+      } elsif (&value_is_true($nl->get_value('use_hillslope'))) {
+         $log->fatal_error("$var cannot be combined with use_hillslope");
       }
       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");
@@ -3268,12 +3277,8 @@ sub setup_logic_hydrology_switches {
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_subgrid_fluxes');
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snow_cover_fraction_method');
   my $subgrid    = $nl->get_value('use_subgrid_fluxes' );
-  my $origflag   = $nl->get_value('origflag'    );
   my $h2osfcflag = $nl->get_value('h2osfcflag'  );
   my $scf_method = $nl->get_value('snow_cover_fraction_method');
-  if ( $origflag == 1 && &value_is_true($subgrid) ) {
-    $log->fatal_error("if origflag is ON, use_subgrid_fluxes can NOT also be on!");
-  }
   if ( $h2osfcflag == 1 && ! &value_is_true($subgrid) ) {
     $log->fatal_error("if h2osfcflag is ON, use_subgrid_fluxes can NOT be off!");
   }
@@ -3297,9 +3302,6 @@ sub setup_logic_hydrology_switches {
   if ( defined($use_vic) && defined($lower) && (&value_is_true($use_vic)) && $lower != 3 && $lower != 4) {
      $log->fatal_error( "If use_vichydro is on -- lower_boundary_condition can only be table or aquifer" );
   }
-  if ( defined($origflag) && defined($use_vic) && (&value_is_true($use_vic)) && $origflag == 1 ) {
-     $log->fatal_error( "If use_vichydro is on -- origflag can NOT be equal to 1" );
-  }
   if ( defined($h2osfcflag) && defined($lower) && $h2osfcflag == 0 && $lower != 4 ) {
      $log->fatal_error( "If h2osfcflag is 0 lower_boundary_condition can only be aquifer" );
   }
@@ -3481,6 +3483,28 @@ sub setup_logic_luna {
 
 #-------------------------------------------------------------------------------
 
+sub setup_logic_hillslope {
+  #
+  # Hillslope model
+  #
+  my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
+
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_hillslope' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'downscale_hillslope_meteorology' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'hillslope_head_gradient_method' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'hillslope_transmissivity_method' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'hillslope_pft_distribution_method' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'hillslope_soil_profile_method' );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_hillslope_routing', 'use_hillslope'=>$nl_flags->{'use_hillslope'} );
+  my $use_hillslope = $nl->get_value('use_hillslope');
+  my $use_hillslope_routing = $nl->get_value('use_hillslope_routing');
+  if ( (! &value_is_true($use_hillslope)) && &value_is_true($use_hillslope_routing) ) {
+      $log->fatal_error("Cannot turn on use_hillslope_routing when use_hillslope is off\n" );
+  }
+}
+
+#-------------------------------------------------------------------------------
+
 sub setup_logic_hydrstress {
   #
   # Plant hydraulic stress model
@@ -4209,7 +4233,6 @@ sub setup_logic_soil_resis {
 
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'soil_resis_method' );
 }
-#-------------------------------------------------------------------------------
 
 sub setup_logic_canopyfluxes {
   #
@@ -4585,6 +4608,7 @@ sub write_output_files {
 
   # CLM component
   my @groups;
+
   @groups = qw(clm_inparm ndepdyn_nml popd_streams urbantv_streams light_streams
                soil_moisture_streams lai_streams atm2lnd_inparm lnd2atm_inparm clm_canopyhydrology_inparm cnphenology
                cropcal_streams
@@ -4594,7 +4618,7 @@ sub write_output_files {
                soilhydrology_inparm luna friction_velocity mineral_nitrogen_dynamics
                soilwater_movement_inparm rooting_profile_inparm
                soil_resis_inparm  bgc_shared canopyfluxes_inparm aerosol
-               clmu_inparm clm_soilstate_inparm clm_nitrogen clm_snowhydrology_inparm
+               clmu_inparm clm_soilstate_inparm clm_nitrogen clm_snowhydrology_inparm hillslope_hydrology_inparm hillslope_properties_inparm
                cnprecision_inparm clm_glacier_behavior crop_inparm irrigation_inparm
                surfacealbedo_inparm water_tracers_inparm tillage_inparm);
 

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -611,6 +611,18 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 <cnegcrit phys="clm4_5"  use_cn=".true.">-6.d+2</cnegcrit>
 <nnegcrit phys="clm4_5"  use_cn=".true.">-6.d+1</nnegcrit>
 
+
+<!-- Hillslope hydrology -->
+<use_hillslope                               >.false.</use_hillslope>
+<use_hillslope phys="clm4_5"                 >.false.</use_hillslope>
+<use_hillslope phys="clm5_0"                 >.false.</use_hillslope>
+<use_hillslope_routing                       >.false.</use_hillslope_routing>
+<hillslope_head_gradient_method              >Darcy</hillslope_head_gradient_method>
+<hillslope_transmissivity_method             >LayerSum</hillslope_transmissivity_method>
+<hillslope_pft_distribution_method           >Standard</hillslope_pft_distribution_method>
+<hillslope_soil_profile_method               >Uniform</hillslope_soil_profile_method>
+<downscale_hillslope_meteorology             >.true.</downscale_hillslope_meteorology>
+
 <!-- Plant hydraulic stress -->
 <use_hydrstress                                                       >.false.</use_hydrstress>
 <use_hydrstress phys="clm5_0"  use_fates=".false." configuration="clm">.true.</use_hydrstress>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -800,6 +800,41 @@ LUNA operates on C3 and non-crop vegetation (see vcmax_opt for how other veg is
 LUNA: Leaf Utilization of Nitrogen for Assimilation
 </entry>
 
+<entry id="use_hillslope" type="logical" category="physics"
+        group="clm_inparm" valid_values="" value=".false.">
+Toggle to turn on the hillslope model
+</entry>
+
+<entry id="downscale_hillslope_meteorology" type="logical" category="physics"
+        group="clm_inparm" valid_values="" value=".false.">
+Toggle to turn on meteorological downscaling in hillslope model
+</entry>
+
+<entry id="use_hillslope_routing" type="logical" category="physics"
+        group="clm_inparm" valid_values="" value=".false.">
+Toggle to turn on surface water routing in the hillslope hydrology model
+</entry>
+
+<entry id="hillslope_head_gradient_method" type="char*256" category="physics"
+        group="hillslope_hydrology_inparm" valid_values="Kinematic,Darcy">
+Method for calculating hillslope saturated head gradient
+</entry>
+
+<entry id="hillslope_transmissivity_method" type="char*256" category="physics"
+        group="hillslope_hydrology_inparm" valid_values="LayerSum,Uniform">
+Method for calculating transmissivity of hillslope columns
+</entry>
+
+<entry id="hillslope_pft_distribution_method" type="char*256" category="physics"
+        group="hillslope_properties_inparm" valid_values="Standard,FromFile,DominantPftUniform,DominantPftLowland,PftLowlandUpland">
+Method for distributing pfts across hillslope columns
+</entry>
+
+<entry id="hillslope_soil_profile_method" type="char*256" category="physics"
+        group="hillslope_properties_inparm" valid_values="Uniform,FromFile,SetLowlandUpland,Linear">
+Method for distributing soil thickness across hillslope columns
+</entry>
+
 <entry id="use_hydrstress" type="logical" category="physics"
         group="clm_inparm" valid_values="" value=".false.">
 Toggle to turn on the plant hydraulic stress model
@@ -2499,12 +2534,6 @@ If surface water is active or not
 (deprecated -- will be removed)
 </entry>
 
-<entry id="origflag" type="integer" category="clm_physics"
-       group="clm_soilhydrology_inparm" valid_values="0,1" >
-Use original CLM4 soil hydraulic properties
-(deprecated -- will be removed)
-</entry>
-
 <!-- ========================================================================================  -->
 <!-- namelist elements associated with the CH4 Model                                           -->
 <!-- ========================================================================================  -->

bld/unit_testers/build-namelist_test.pl

@@ -811,21 +811,6 @@ sub cat_and_create_namelistinfile {
                                      GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm4_5",
                                    },
-     "-vic with origflag=1"      =>{ options=>"-vichydro -envxml_dir .",
-                                     namelst=>"origflag=1",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
-                                     phys=>"clm4_5",
-                                   },
-     "l_bnd=flux with origflag=0"=>{ options=>"-envxml_dir .",
-                                     namelst=>"origflag=0, lower_boundary_condition=1",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
-                                     phys=>"clm4_5",
-                                   },
-     "l_bnd=zflux with origflag=0"=>{ options=>"-envxml_dir .",
-                                     namelst=>"origflag=0, lower_boundary_condition=2",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
-                                     phys=>"clm4_5",
-                                   },
      "bedrock with l_bnc=flux"   =>{ options=>"-envxml_dir .",
                                      namelst=>"use_bedrock=.true., lower_boundary_condition=1",
                                      GLC_TWO_WAY_COUPLING=>"FALSE",

cime_config/testdefs/testlist_clm.xml

@@ -3308,8 +3308,8 @@
 
   <test name="FSURDATMODIFYCTSM_D_Mmpi-serial_Ld1" grid="5x5_amazon" compset="I2000Clm50SpRs">
     <machines>
-      <machine name="cheyenne" compiler="intel" category="aux_clm"/>
-      <machine name="cheyenne" compiler="intel" category="clm_pymods"/>
+      <machine name="derecho" compiler="gnu" category="aux_clm"/>
+      <machine name="derecho" compiler="gnu" category="clm_pymods"/>
     </machines>
     <options>
       <option name="wallclock">00:20:00</option>
@@ -3451,4 +3451,45 @@
       <option name="comment">This test is designed to test the ability to prescribe crop sowing dates and maturity requirements. It first performs a GDD-generating run, then calls Python code to generate the maturity requirement file. This is then used in a sowing+maturity forced run, which finally is tested to ensure correct behavior.</option>
     </options>
   </test>
+
+  <test name="ERP_D_P64x2_Ld10" grid="f10_f10_mg37" compset="I2000Clm51Bgc" testmods="clm/Hillslope">
+    <machines>
+      <machine name="derecho" compiler="intel" category="aux_clm"/>
+      <machine name="derecho" compiler="intel" category="hillslope"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:30:00</option>
+    </options>
+  </test>
+
+  <test name="SMS_D_Ld3" grid="f10_f10_mg37" compset="I1850Clm51Bgc" testmods="clm/HillslopeFromFile">
+    <machines>
+      <machine name="derecho" compiler="intel" category="hillslope"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:20:00</option>
+    </options>
+  </test>
+
+  <test name="SMS_D_Mmpi-serial_Ld5" grid="5x5_amazon" compset="I1850Clm51Bgc" testmods="clm/HillslopeC">
+    <machines>
+      <machine name="derecho" compiler="gnu" category="aux_clm"/>
+      <machine name="derecho" compiler="gnu" category="hillslope"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:20:00</option>
+    </options>
+  </test>
+
+  <test name="SMS_D_Ld3" grid="f10_f10_mg37" compset="I2000Clm51Bgc" testmods="clm/HillslopeD">
+    <machines>
+      <machine name="izumi" compiler="nag" category="aux_clm"/>
+      <machine name="izumi" compiler="nag" category="hillslope"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:20:00</option>
+    </options>
+  </test>
+
+
 </testlist>

cime_config/testdefs/testmods_dirs/clm/Hillslope/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/Hillslope/shell_commands

@@ -0,0 +1,4 @@
+./xmlchange CLM_BLDNML_OPTS="-bgc sp"
+DIN_LOC_ROOT=$(./xmlquery --value DIN_LOC_ROOT)
+meshfile=$DIN_LOC_ROOT/lnd/clm2/testdata/ESMFmesh_10x15_synthetic_cosphill_1.0.nc
+./xmlchange ATM_DOMAIN_MESH=${meshfile},LND_DOMAIN_MESH=${meshfile}

cime_config/testdefs/testmods_dirs/clm/Hillslope/user_nl_clm

@@ -0,0 +1,11 @@
+use_hillslope = .true.
+use_hillslope_routing = .true.
+downscale_hillslope_meteorology = .false.
+hillslope_head_gradient_method = 'Darcy'
+hillslope_transmissivity_method = 'LayerSum'
+hillslope_pft_distribution_method = 'PftLowlandUpland'
+hillslope_soil_profile_method = 'Uniform'
+
+fsurdat = '$DIN_LOC_ROOT/lnd/clm2/testdata/surfdata_10x15_78pfts_simyr2000_synthetic_cosphill_1.3.nc'
+
+use_ssre = .false.

cime_config/testdefs/testmods_dirs/clm/HillslopeC/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/HillslopeC/user_nl_clm

@@ -0,0 +1,7 @@
+! Various hillslope options not exercised by other testmods
+use_hillslope_routing = .false.
+downscale_hillslope_meteorology = .true.
+hillslope_head_gradient_method = 'Kinematic'
+hillslope_transmissivity_method = 'Uniform'
+hillslope_pft_distribution_method = 'DominantPftUniform'
+hillslope_soil_profile_method = 'SetLowlandUpland'

cime_config/testdefs/testmods_dirs/clm/HillslopeD/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/HillslopeD/user_nl_clm

@@ -0,0 +1,3 @@
+! Various hillslope options not exercised by other testmods
+hillslope_pft_distribution_method = 'DominantPftLowland'
+hillslope_soil_profile_method = 'Linear'

cime_config/testdefs/testmods_dirs/clm/HillslopeFromFile/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/HillslopeFromFile/user_nl_clm

@@ -0,0 +1,2 @@
+hillslope_pft_distribution_method = 'FromFile'
+hillslope_soil_profile_method = 'FromFile'

cime_config/testdefs/testmods_dirs/clm/oldhyd/user_nl_clm

@@ -1,4 +1,3 @@
  snow_cover_fraction_method = 'NiuYang2007'
  h2osfcflag  = 0
- origflag    = 1
  use_subgrid_fluxes = .false.