Merge branch 'soil_layer_def_cleanup'

Soil layer definition clean-up and user-defined option

Code clean-up clarifes that there are two types of soil layer
definition: the node-based and the thickness-based.

User-defined option allows user to specify a soil layer profile in the
form of a dzsoi vector (values in meters) in the thickness-based
approach.

Default nlevsoi for NWP configurations had to change from 5 to 4 for
consistency with the new error check described in known bugs below.

Other code clean-up removes a couple of sections of repeating code.

Resolves #279
Resolves #728

bld/CLMBuildNamelist.pm

@@ -2089,10 +2089,31 @@ sub setup_logic_soilstate {
   my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
 
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'organic_frac_squared' );
-  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'soil_layerstruct',
-              'structure'=>$nl_flags->{'structure'});
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_bedrock',
               'use_fates'=>$nl_flags->{'use_fates'}, 'vichydro'=>$nl_flags->{'vichydro'} );
+
+  my $var1 = "soil_layerstruct_predefined";
+  my $var2 = "soil_layerstruct_userdefined";
+  my $var3 = "soil_layerstruct_userdefined_nlevsoi";
+  my $soil_layerstruct_predefined = $nl->get_value($var1);
+  my $soil_layerstruct_userdefined = $nl->get_value($var2);
+  my $soil_layerstruct_userdefined_nlevsoi = $nl->get_value($var3);
+
+  if (defined($soil_layerstruct_userdefined)) {
+    if (defined($soil_layerstruct_predefined)) {
+      $log->fatal_error("You have set both soil_layerstruct_userdefined and soil_layerstruct_predefined in your namelist; model cannot determine which to use");
+    }
+    if (not defined($soil_layerstruct_userdefined_nlevsoi)) {
+      $log->fatal_error("You have set soil_layerstruct_userdefined and NOT set soil_layerstruct_userdefined_nlevsoi in your namelist; both MUST be set");
+    }
+  } else {
+    if (defined($soil_layerstruct_userdefined_nlevsoi)) {
+      $log->fatal_error("You have set soil_layerstruct_userdefined_nlevsoi and NOT set soil_layerstruct_userdefined in your namelist; EITHER set both OR neither; in the latter case soil_layerstruct_predefined will be assigned a default value");
+    } else {
+      add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'soil_layerstruct_predefined',
+                  'structure'=>$nl_flags->{'structure'});
+    }
+  }
 }
 
 #-------------------------------------------------------------------------------

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -125,9 +125,9 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 <organic_frac_squared phys="clm4_5" >.true.</organic_frac_squared>
 <organic_frac_squared phys="clm5_0" >.false.</organic_frac_squared>
 
-<soil_layerstruct structure="fast"                  >5SL_3m</soil_layerstruct>
-<soil_layerstruct structure="standard" phys="clm5_0">20SL_8.5m</soil_layerstruct>
-<soil_layerstruct structure="standard" phys="clm4_5">10SL_3.5m</soil_layerstruct>
+<soil_layerstruct_predefined structure="fast">4SL_2m</soil_layerstruct_predefined>
+<soil_layerstruct_predefined structure="standard" phys="clm5_0">20SL_8.5m</soil_layerstruct_predefined>
+<soil_layerstruct_predefined structure="standard" phys="clm4_5">10SL_3.5m</soil_layerstruct_predefined>
 
 <use_bedrock phys="clm5_0" use_fates =".true.">.false.</use_bedrock>
 <use_bedrock phys="clm5_0" vichydro ="1"      >.false.</use_bedrock>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -114,13 +114,25 @@ If TRUE, square the organic fraction when it's used (as was done in CLM4.5)
 Otherwise use the fraction straight up              (the default for CLM5.0)
 </entry>
 
-<entry id="soil_layerstruct" type="char*16" category="clm_physics"
-       group="clm_inparm" valid_values="10SL_3.5m,23SL_3.5m,49SL_10m,20SL_8.5m,5SL_3m" >
+<entry id="soil_layerstruct_predefined" type="char*16" category="clm_physics"
+       group="clm_inparm" valid_values="10SL_3.5m,23SL_3.5m,49SL_10m,20SL_8.5m,4SL_2m" >
 10SL_3.5m    = standard CLM4 and CLM4.5 version
 23SL_3.5m    = more vertical layers for permafrost simulations 
 49SL_10m     = 49 layer soil column, 10m of soil, 5 bedrock layers
 20SL_8.5m    = 20 layer soil column, 8m of soil, 5 bedrock layers
-5SL_3m       = 5 layer soil column, 3m of soil, 0 bedrock layers
+4SL_2m       = 4 layer soil column, 2m of soil, 0 bedrock layers
+</entry>
+
+<entry id="soil_layerstruct_userdefined" type="real(99)" category="clm_physics"
+       group="clm_inparm" valid_values="" >
+User-defined vector of dzsoi. The length of this vector determines nlevgrnd. When the user sets this vector, they have to set soil_layerstruct_userdefined_nlevsoi in the namelist, too; soil_layerstruct_userdefined_nlevsoi must be less than nlevgrnd in this version of the model, even though ideally soil_layerstruct_userdefined_nlevsoi could also equal nlevgrnd.
+<default>Default: rundef</default>
+</entry>
+
+<entry id="soil_layerstruct_userdefined_nlevsoi" type="integer" category="clm_physics"
+       group="clm_inparm" valid_values="" >
+User-defined number of soil layers required to be set in the namelist when the user sets soil_layerstruct_userdefined in the namelist.
+<default>Default: iundef</default>
 </entry>
 
 <entry id="use_bedrock" type="logical" category="clm_physics"

cime_config/SystemTests/soilstructud.py

@@ -0,0 +1,37 @@
+"""
+Implementation of the CIME SOILSTRUCTUD test.
+
+This is a CLM specific test:
+Verifies that a simulation that points to user_nl_clm containing
+soil_layerstruct_userdefined_nlevsoi = 4
+soil_layerstruct_userdefined = 0.1d0,0.3d0,0.6d0,1.0d0,1.0d0
+gives bfb same results as one that points to user_nl_clm containing
+soil_layerstruct_predefined = '4SL_2m'
+
+"""
+
+from CIME.SystemTests.system_tests_compare_two import SystemTestsCompareTwo
+from CIME.XML.standard_module_setup import *
+from CIME.SystemTests.test_utils.user_nl_utils import append_to_user_nl_files
+
+logger = logging.getLogger(__name__)
+
+class SOILSTRUCTUD(SystemTestsCompareTwo):
+
+    def __init__(self, case):
+        SystemTestsCompareTwo.__init__(self, case,
+                                       separate_builds = False,
+                                       run_two_suffix = '4SL_2m',
+                                       run_one_description = 'soil_layerstruct_userdefined',
+                                       run_two_description = 'soil_layerstruct_predefined')
+
+    def _case_one_setup(self):
+        append_to_user_nl_files(caseroot = self._get_caseroot(),
+                                component = "clm",
+                                contents = "soil_layerstruct_userdefined_nlevsoi = 4,soil_layerstruct_userdefined = 0.1d0,0.3d0,0.6d0,1.0d0,1.0d0")
+
+    def _case_two_setup(self):
+        append_to_user_nl_files(caseroot = self._get_caseroot(),
+                                component = "clm",
+                                contents = "soil_layerstruct_predefined = '4SL_2m'")
+

cime_config/config_component.xml

@@ -15,7 +15,7 @@
   <!-- Descriptions of all the different valid configurations for different model versions -->
   <description modifier_mode="1">
     <desc lnd="CLM45[%SP][%SP-VIC][%CN][%CNDV][%CN-CROP][%CNDV-CROP][%BGC][%BGC-CROP][%FATES][%BGCDV][%BGCDV-CROP]"                  >clm4.5:</desc>
-    <desc lnd="CLM50[%SP][%SP-VIC][%CN][%BGC][%BGC-CROP][%FATES][%BGCDV][%BGCDV-CROP][%BGC-CROP-CMIP6DECK][%BGC-CROP-CMIP6WACCMDECK][%NWP-SP]">clm5.0:</desc>
+    <desc lnd="CLM50[%SP][%SP-VIC][%CN][%BGC][%BGC-CROP][%FATES][%BGCDV][%BGCDV-CROP][%BGC-CROP-CMIP6DECK][%BGC-CROP-CMIP6WACCMDECK][%NWP-SP][%NWP-BGC-CROP]">clm5.0:</desc>
     <desc option="SP"              >Satellite phenology:</desc>
     <desc option="CN"              >CN: Carbon Nitrogen model</desc>
     <desc option="CNDV"            >CNDV: CN with Dynamic Vegetation</desc>
@@ -32,6 +32,7 @@
     <desc option="BGC-CROP-CMIP6WACCMDECK">BGC (vert. resol. CN and methane) with prognostic crop, with modifications appropriate for CMIP6 WACCM DECK experiments:</desc>
 
     <desc option="NWP-SP"          >NWP configuration with satellite phenology:</desc>
+    <desc option="NWP-BGC-CROP"    >NWP configuration with BGC and CROP:</desc>
   </description>
 
   <entry id="COMP_LND">

cime_config/config_compsets.xml

@@ -248,6 +248,11 @@
     <lname>2000_DATM%GSWP3v1_CLM50%NWP-SP_SICE_SOCN_MOSART_SGLC_SWAV</lname>
   </compset>
 
+  <compset>
+    <alias>I2000Ctsm50NwpBgcCropGswpGs</alias>
+    <lname>2000_DATM%GSWP3v1_CLM50%NWP-BGC-CROP_SICE_SOCN_MOSART_SGLC_SWAV</lname>
+  </compset>
+
   <!-- NLDAS datm forcing, for regional runs over the CONUS, e.g., using
        the nldas grid -->
   <compset>

cime_config/config_tests.xml

@@ -87,4 +87,14 @@ SSP    smoke CLM spinup test (only valid for CLM compsets with CLM45)
     <HIST_N>$STOP_N</HIST_N>
   </test>
 
+  <test NAME="SOILSTRUCTUD">
+    <DESC>CLM user-defined soil structure test</DESC>
+    <INFO_DBUG>1</INFO_DBUG>
+    <DOUT_S>FALSE</DOUT_S>
+    <CONTINUE_RUN>FALSE</CONTINUE_RUN>
+    <REST_OPTION>never</REST_OPTION>
+    <HIST_OPTION>$STOP_OPTION</HIST_OPTION>
+    <HIST_N>$STOP_N</HIST_N>
+  </test>
+
 </config_test>

cime_config/testdefs/testlist_clm.xml

@@ -787,13 +787,13 @@
       <option name="comment"  >test transient PFTs (via HIST) with a December start, reading 78-pft data and running with 16 pfts</option>
     </options>
   </test>
-  <test name="ERS_D_Ld10" grid="f10_f10_musgs" compset="I2000Clm50BgcCropGs" testmods="clm/rm_indiv_lunits_and_collapse_to_dom">
+  <test name="SOILSTRUCTUD_Ld5" grid="f10_f10_musgs" compset="I2000Clm50BgcCropGs" testmods="clm/default">
     <machines>
       <machine name="cheyenne" compiler="intel" category="aux_clm"/>
     </machines>
     <options>
       <option name="wallclock">00:20:00</option>
-      <option name="comment"  >test toosmall_* (soil, crop, glacier, lake, wetland, urban) all set to 5% (ie keep the landunits in gridcells where they exceed 5%) and also n_dom_pfts = 2, n_dom_landunits = 2, collapse_urbar = .true. in a 2000 case</option>
+      <option name="comment"  >test soil_layerstruct_userdefined set to the same dzsoi values as in the predefined case 4SL_2m and expect bfb same answers</option>
     </options>
   </test>
   <test name="ERS_D_Ld12" grid="f10_f10_musgs" compset="I1850Clm50BgcCropG" testmods="clm/glcMEC_spunup_inc_dec_bgc">
@@ -1674,6 +1674,18 @@
 
     </machines>
   </test>
+  <test name="ERP_P36x2_D_Ld5" grid="f10_f10_musgs" compset="I2000Ctsm50NwpBgcCropGswpGs" testmods="clm/default">
+    <machines>
+
+      <machine name="cheyenne" compiler="intel" category="aux_clm">
+        <options>
+          <option name="wallclock">0:30</option>
+          <option name="comment">A debug ERP test of the NWP configuration with active BGC and CROP.</option>
+        </options>
+      </machine>
+
+    </machines>
+  </test>
   <test name="ERP_P36x2_D_Ld5" grid="f10_f10_musgs" compset="I2000Ctsm50NwpSpGswpGs" testmods="clm/default">
     <machines>
 

cime_config/testdefs/testmods_dirs/clm/deepsoil_bedrock/user_nl_clm

@@ -1,3 +1,3 @@
 lower_boundary_condition = 2
-soil_layerstruct = '49SL_10m'
+soil_layerstruct_predefined = '49SL_10m'
 use_bedrock = .true.

cime_config/testdefs/testmods_dirs/clm/vrtlay/user_nl_clm

@@ -1 +1 @@
-soil_layerstruct = '23SL_3.5m'
+soil_layerstruct_predefined = '23SL_3.5m'

doc/ChangeLog

@@ -1,4 +1,145 @@
 ===============================================================
+Tag name:  ctsm1.0.dev053
+Originator(s):  slevis (Samuel Levis,SLevis Consulting LLC,303-665-1310)
+Date: Thu Aug  1 16:56:09 MDT 2019
+One-line Summary: Soil layer definition clean-up and user-defined option
+
+Purpose of changes
+------------------
+
+ Code clean-up clarifes that there are two types of soil layer
+ definition: the node-based and the thickness-based.
+
+ User-defined option allows user to specify a soil layer profile in the
+ form of a dzsoi vector (values in meters) in the thickness-based
+ approach.
+
+ Default nlevsoi for NWP configurations had to change from 5 to 4 for
+ consistency with the new error check described in known bugs below.
+
+ Other code clean-up removes a couple of sections of repeating code.
+
+Bugs fixed or introduced
+------------------------
+
+Issues fixed (include CTSM Issue #): #279 #728
+
+Known bugs found since the previous tag (include github issue ID):
+ #759 (this PR) bug causes model to abort when nlevsoi = nlevgrnd;
+ bug has been corrected with an error check
+
+
+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.]
+
+[ ] clm5_0
+
+[X] ctsm5_0-nwp
+
+[ ] clm4_5
+
+Notes of particular relevance for users
+---------------------------------------
+
+Caveats for users (e.g., need to interpolate initial conditions):
+ if neither soil_layerstruct_predefined nor soil_layerstruct_userdefined
+ get specified in the namelist, then the model sets
+ soil_layerstruct_predefined to the old default setting for
+ soil_layerstruct (clm5: 20SL_8.5m, clm4.5: 10SL_3.5m)
+
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+ renamed soil_layerstruct to soil_layerstruct_predefined and added
+ soil_layerstruct_userdefined
+
+Changes made to namelist defaults (e.g., changed parameter values):
+ Default nlevsoi for NWP configurations had to change from 5 to 4 for
+ consistency with the new error check described in known bugs below
+
+Changes to the datasets (e.g., parameter, surface or initial files): none
+
+Substantial timing or memory changes: none
+
+Notes of particular relevance for developers
+--------------------------------------------
+NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance): none
+
+Changes to tests or testing:
+ 1) New test...
+ ERP_P36x2_D_Ld5.f10_f10_musgs.I2000Ctsm50NwpBgcCropGswpGs.cheyenne_intel.clm-default
+ replaces existing test
+ ERS_D_Ld10.f10_f10_musgs.I2000Clm50BgcCropGs.cheyenne_intel.clm-rm_indiv_lunits_and_collapse_to_dom
+ to check the correction described in known bugs above; the new test
+ together with existing unit tests cover what the old test was testing
+
+ 2) New test and new test type...
+ SOILSTRUCTUD_Ld5.f10_f10_musgs.I2000Clm50BgcCropGs.cheyenne_intel.clm-default
+ ensures that soil_layerstruct_userdefined gives bfb same answers as
+ soil_layerstruct_predefined = '4SL_2m' when set with the same dzsoi
+ values. The new test type was put together by:
+ - listing the test in (1) testlist_clm.xml (as all tests) and (2) config_tests.xml
+ - creating the file .../cime_config/SystemTests/soilstructud.py named after the test in lower case
+
+Code reviewed by: @billsacks
+
+
+CTSM testing:
+
+ [PASS means all tests PASS and OK means tests PASS other than expected fails.]
+
+  build-namelist tests:
+
+    cheyenne - 
+
+  tools-tests (test/tools):
+
+    cheyenne - 
+
+  PTCLM testing (tools/shared/PTCLM/test):
+
+    cheyenne - 
+
+  python testing (see instructions in python/README.md; document testing done):
+
+    (any machine) - 
+
+  regular tests (aux_clm):
+
+    cheyenne ---- OK
+    hobart ------ OK
+
+If the tag used for baseline comparisons was NOT the previous tag, note that here:
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline:
+
+  Summarize any changes to answers, i.e.,
+    - what code configurations: nwp
+    - what platforms/compilers: all
+    - nature of change: larger than roundoff/same climate
+  This is due to the change of nlevsoi from 5 to 4 (more info above).
+  I confirmed that nwp does return bfb same answers when I revert this
+  change.
+
+Detailed list of changes
+------------------------
+
+List any externals directories updated (cime, rtm, mosart, cism, fates, etc.): none
+
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/759
+
+===============================================================
+===============================================================
 Tag name:  ctsm1.0.dev052
 Originator(s):  sacks (Bill Sacks)
 Date: Mon Jul 22 14:02:43 MDT 2019

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+  ctsm1.0.dev053   slevis 08/01/2019 Soil layer definition clean-up and user-defined option
   ctsm1.0.dev052    sacks 07/22/2019 Fix rare soil color bug in mksurfdata_map
   ctsm1.0.dev051    sacks 07/19/2019 Update water tracers for remainder of first stage of hydrology
   ctsm1.0.dev050   slevis 07/15/2019 dz --> dz_lake bug-fix in LakeTemperatureMod.F90 line 960