Skip to content

Commit

Permalink
Merge pull request ESCOMP#2390 from ESCOMP/hillslope-merge
Browse files Browse the repository at this point in the history
Bring in hillslope hydrology.
  • Loading branch information
samsrabin authored Feb 29, 2024
2 parents 4ba1501 + c222737 commit 07051e3
Show file tree
Hide file tree
Showing 70 changed files with 3,901 additions and 973 deletions.
2 changes: 1 addition & 1 deletion Externals.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -98,4 +98,4 @@ tag = v1.0.8
required = False

[externals_description]
schema_version = 1.0.0
schema_version = 1.0.0
42 changes: 33 additions & 9 deletions bld/CLMBuildNamelist.pm
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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!");
}
Expand All @@ -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" );
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 {
#
Expand Down Expand Up @@ -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
Expand All @@ -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);

Expand Down
12 changes: 12 additions & 0 deletions bld/namelist_files/namelist_defaults_ctsm.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
41 changes: 35 additions & 6 deletions bld/namelist_files/namelist_definition_ctsm.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 -->
<!-- ======================================================================================== -->
Expand Down
15 changes: 0 additions & 15 deletions bld/unit_testers/build-namelist_test.pl
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
41 changes: 41 additions & 0 deletions cime_config/testdefs/testlist_clm.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../default
Original file line number Diff line number Diff line change
@@ -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}
11 changes: 11 additions & 0 deletions cime_config/testdefs/testmods_dirs/clm/Hillslope/user_nl_clm
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../Hillslope
7 changes: 7 additions & 0 deletions cime_config/testdefs/testmods_dirs/clm/HillslopeC/user_nl_clm
Original file line number Diff line number Diff line change
@@ -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'
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../Hillslope
3 changes: 3 additions & 0 deletions cime_config/testdefs/testmods_dirs/clm/HillslopeD/user_nl_clm
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
! Various hillslope options not exercised by other testmods
hillslope_pft_distribution_method = 'DominantPftLowland'
hillslope_soil_profile_method = 'Linear'
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../Hillslope
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
hillslope_pft_distribution_method = 'FromFile'
hillslope_soil_profile_method = 'FromFile'
1 change: 0 additions & 1 deletion cime_config/testdefs/testmods_dirs/clm/oldhyd/user_nl_clm
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
snow_cover_fraction_method = 'NiuYang2007'
h2osfcflag = 0
origflag = 1
use_subgrid_fluxes = .false.
73 changes: 73 additions & 0 deletions doc/ChangeLog
Original file line number Diff line number Diff line change
@@ -1,4 +1,77 @@
===============================================================
Tag name: ctsm5.1.dev170
Originator(s): samrabin (Sam Rabin, UCAR/TSS, [email protected])
Date: Wed Feb 28 11:01:43 MST 2024
One-line Summary: Add hillslope hydrology

Purpose and description of changes
----------------------------------

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

Described in:
Swenson, S. C., Clark, M., Fan, Y., Lawrence, D. M., & Perket, J. (2019). Representing intra-hillslope lateral subsurface flow in the community land model. Journal of Advances in Modeling Earth Systems, 11, 4044–4065. https://doi.org/10.1029/2019MS001833


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_1

[ ] clm5_0

[ ] ctsm5_0-nwp

[ ] clm4_5


Notes of particular relevance for developers:
---------------------------------------------

Changes to tests or testing:
* oldhyd test changes answers due to removal of origflag parameter
* Adds several hillslope-specific tests


Testing summary:
----------------

regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):

derecho ----- DIFF
izumi ------- DIFF


Answer changes
--------------

Summarize any changes to answers, i.e.,
- what code configurations: all
- what platforms/compilers: all
- nature of change: roundoff

If bitwise differences were observed, how did you show they were no worse
than roundoff? Roundoff differences means one or more lines of code change results
only by roundoff level (because order of operation changes for example). Roundoff
changes to state fields usually grow to greater than roundoff as the simulation progresses.
* FSDS answers change due to rounding differences, since the history field now uses a column-level variable instead of a gridcell-level one. Note that this is JUST the history field that's affected, which is why there are no diffs in any other variable. (Confirmed using branch at https://github.com/samsrabin/CTSM/tree/hillslope-revert-fsds-diffs.)
* The origflag parameter (used to reproduce CLM4 behavior) was removed, so anything using that will break. This includes the oldhyd test.


Other details
-------------

Pull Requests that document the changes (include PR ids):
* ESCOMP/CTSM#1715: Hillslope hydrology (https://github.com/ESCOMP/CTSM/pull/1715)
* ESCOMP/CTSM#2390: Hillslope merge (https://github.com/ESCOMP/CTSM/pull/2390)

===============================================================
===============================================================
Tag name: ctsm5.1.dev169
Originator(s): samrabin (Sam Rabin, UCAR/TSS, [email protected])
Date: Thu 22 Feb 2024 09:42:57 AM MST
Expand Down
1 change: 1 addition & 0 deletions doc/ChangeSum
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
Tag Who Date Summary
============================================================================================================================
ctsm5.1.dev170 samrabin 02/28/2024 Add hillslope hydrology
ctsm5.1.dev169 samrabin 02/22/2024 Merge b4b-dev
ctsm5.1.dev168 slevis 02/16/2024 Remove a source of negative snocan in CanopyFluxesMod
ctsm5.1.dev167 samrabin 02/08/2024 Delete _FillValue and history from parameter files
Expand Down
Loading

0 comments on commit 07051e3

Please sign in to comment.