Skip to content

Commit

Permalink
Merge tag 'ctsm5.1.dev145' into CESM3_dev
Browse files Browse the repository at this point in the history 
SNICAR snow albedo scheme updates

A few substantial changes in the SNICAR module for the following updated snow albedo calculation features:
 - Updated ice optical properties from Flanner et al. (2021), with multiple types for ice refractive indices.
 - Updated aerosol optical properties from Flanner et al. (2021) with multiple dust types & new BC and OC optics.
 - Updated downward solar spectra from Flanner et al. (2021) for multiple condition types.
 - More accurate radiative transfer solver (adding-doubling) from Dang et al. (2019).
 - Nonspherical snow grain scheme from He et al. (2017).
 - BC-snow internal mixing scheme from He et al. (2017).
 - Dust-snow internal mixing scheme from He et al. (2019).
 - Hyperspectral (480-band, 10-nm spectral res) capability with all the above features.
 - New namelist controls for aerosol in snow and additional snow albedo diagnostic output variables.

 Specific notes
 - Code contributors: Cenlin He (NCAR/RAL) with advice from Dave Lawrence (NCAR/CGD) and Mark Flanner (UMich).
 - The manuscript to report this update is
 Cenlin He, Mark Flanner, David M Lawrence, Yu Gu: New features and enhancements in Community Land Model (CLM5) snow albedo modeling: description, sensitivity, and evaluation. Authorea. June 08, 2023. DOI:10.22541/essoar.168626390.01530324/v1
 - These updates will change the snow and surface albedo results along with other surface fluxes changes.
 - There are a few new namelist options related to SNICAR scheme added to the namelist control.

New namelist variables:
 snicar_numrad_snw = 5 or 480 wavelength bands, default 5
 snicar_solarspec, default "mid_latitude_winter" among six available options
 snicar_dust_optics, default "sahara" among three avail. options
 snicar_snw_shape, default "hexagonal_plate" among fourn avail. options
 snicar_use_aerosol, default .true.
 snicar_snobc_intmix and snicar_snodst_intmix, default .false. means do not activate bc-snow and dust-snow internal mixing

 do_sno_oc, default .false., already appeared in previous code but in caps
 use_snicar_frc, default .false., existed before
 fsnowoptics now points to an updated 5-band file and gives the option for a 480-band file
  • Loading branch information
@ekluzek
ekluzek committed Oct 22, 2023
2 parents 62b63c3 + 167b011 commit 3636565
Show file tree
Hide file tree
Showing 100 changed files with 5,200 additions and 11,344 deletions.
50 changes: 49 additions & 1 deletion bld/CLMBuildNamelist.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1557,6 +1557,7 @@ sub process_namelist_inline_logic {
setup_logic_irrigate($opts, $nl_flags, $definition, $defaults, $nl);
setup_logic_start_type($opts, $nl_flags, $nl);
setup_logic_decomp_performance($opts, $nl_flags, $definition, $defaults, $nl);
setup_logic_snicar_methods($opts, $nl_flags, $definition, $defaults, $nl);
setup_logic_snow($opts, $nl_flags, $definition, $defaults, $nl);
setup_logic_glacier($opts, $nl_flags, $definition, $defaults, $nl, $envxml_ref);
setup_logic_dynamic_plant_nitrogen_alloc($opts, $nl_flags, $definition, $defaults, $nl, $physv);
Expand Down Expand Up @@ -1982,10 +1983,57 @@ sub setup_logic_decomp_performance {

#-------------------------------------------------------------------------------

sub setup_logic_snicar_methods {
my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;

add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_snw_shape' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_solarspec' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_dust_optics' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_numrad_snw' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_snobc_intmix' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_snodst_intmix' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snicar_use_aerosol' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_snicar_frc' );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'do_sno_oc' );

# Error checking in loop
my %supportedSettings = ( 'snicar_solarspec' => "'mid_latitude_winter'", 'snicar_dust_optics' => "'sahara'", 'snicar_numrad_snw' => '5', 'snicar_snobc_intmix' => '.false.', 'snicar_snodst_intmix' => '.false.', 'snicar_use_aerosol' => '.true.', 'do_sno_oc' => '.false.' );
keys %supportedSettings;
while ( my ($key, $val) = each %supportedSettings ) {
my $var = $nl->get_value($key);
if ( $var ne $val ) {
$log->warning("$key=$val is the supported option; $var is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!");
}
}

# Error checking not in loop
my $key1 = 'snicar_snw_shape';
my $var1 = $nl->get_value($key1);
my $val1a = "'sphere'"; # supported value for this option
my $val1b = "'hexagonal_plate'"; # supported value for this option
if (($var1 ne $val1a) && ($var1 ne $val1b)) {
$log->warning("$key1=$val1a and $val1b are supported; $var1 is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!");
}

# snicar_snobc_intmix and snicar_snodst_intmix cannot both be true
my $key1 = 'snicar_snobc_intmix';
my $key2 = 'snicar_snodst_intmix';
my $var1 = $nl->get_value($key1);
my $var2 = $nl->get_value($key2);
my $val1 = $supportedSettings{$key1}; # supported value for this option
if (($var1 eq $var2) && ($var1 ne $val1)) {
$log->warning("$key1 = $var1 and $key2 = $var2 do not work together!");
}
}

#-------------------------------------------------------------------------------

sub setup_logic_snow {
my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;

add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fsnowoptics' );
my $numrad_snw = $nl->get_value('snicar_numrad_snw');
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fsnowoptics',
'snicar_numrad_snw' => $numrad_snw);
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fsnowaging' );
}

Expand Down
20 changes: 18 additions & 2 deletions bld/namelist_files/namelist_defaults_ctsm.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1535,8 +1535,24 @@ use_crop=".true.">lnd/clm2/surfdata_map/ctsm5.1.dev052/landuse.timeseries_mpasa1

<!-- SNICAR (SNow, ICe, and Aerosol Radiative model) datasets -->
<!-- *********** Resolution independent: *********** -->
<fsnowoptics >lnd/clm2/snicardata/snicar_optics_5bnd_c090915.nc</fsnowoptics>
<fsnowaging >lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc</fsnowaging>
<fsnowaging>lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc</fsnowaging>

<snicar_numrad_snw>5</snicar_numrad_snw>

<fsnowoptics snicar_numrad_snw="480">lnd/clm2/snicardata/snicar_optics_480bnd_c012422.nc</fsnowoptics>
<fsnowoptics snicar_numrad_snw="5" >lnd/clm2/snicardata/snicar_optics_5bnd_c013122.nc</fsnowoptics>

<snicar_snw_shape phys="clm5_1">hexagonal_plate</snicar_snw_shape>
<snicar_snw_shape phys="clm5_0">sphere</snicar_snw_shape>
<snicar_snw_shape phys="clm4_5">sphere</snicar_snw_shape>

<use_snicar_frc>.false.</use_snicar_frc>
<snicar_solarspec >mid_latitude_winter</snicar_solarspec>
<snicar_dust_optics >sahara</snicar_dust_optics>
<snicar_snodst_intmix>.false.</snicar_snodst_intmix>
<snicar_snobc_intmix >.false.</snicar_snobc_intmix>
<snicar_use_aerosol >.true.</snicar_use_aerosol>
<do_sno_oc >.false.</do_sno_oc>

<!-- Nitrogen deposition streams namelist defaults -->
<stream_year_first_ndep phys="clm4_5" use_cn=".true." sim_year_range="1850-2100" >2015</stream_year_first_ndep>
Expand Down
83 changes: 65 additions & 18 deletions bld/namelist_files/namelist_definition_ctsm.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,54 @@ specify spatially variable soil thickness. If not present, use bottom
of soil column (nlevsoi).
</entry>

<entry id="snicar_numrad_snw" type="integer" category="clm_physics"
group="clm_inparm" valid_values="5,480" value="5" >
number of wavelength bands used in SNICAR snow albedo calculation
(snicar_numrad_snw=5 is the only supported option; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_solarspec" type="char*25" category="clm_physics"
group="clm_inparm" valid_values="mid_latitude_winter,mid_latitude_summer,sub_arctic_winter,sub_arctic_summer,summit_greenland_summer,high_mountain_summer" value="mid_latitude_winter" >
type of downward solar radiation spectrum for SNICAR snow albedo calculation
(snicar_solarspec='mid_latitude_winter' is the only supported option; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_dust_optics" type="char*25" category="clm_physics"
group="clm_inparm" valid_values="sahara,san_juan_mtns_colorado,greenland" value="sahara" >
dust optics type for SNICAR snow albedo calculation
(snicar_dust_optics='sahara' is the only supported option; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_snw_shape" type="char*25" category="clm_physics"
group="clm_inparm" valid_values="sphere,spheroid,hexagonal_plate,koch_snowflake" value="hexagonal_plate" >
snow grain shape used in SNICAR snow albedo calculation
(snicar_dust_optics='hexagonal_plate' is supported in ctsm5.1 and 'sphere' in older model versions; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_use_aerosol" type="logical" category="clm_physics"
group="clm_inparm" value=".true.">
Toggle to turn on/off aerosol deposition flux in snow in SNICAR
(snicar_use_aerosol='.false.' is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_snobc_intmix" type="logical" category="clm_physics"
group="clm_inparm" value=".false." >
option to activate BC-snow internal mixing in SNICAR snow albedo calculation
(snicar_snobc_intmix='.true.' is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="snicar_snodst_intmix" type="logical" category="clm_physics"
group="clm_inparm" value=".false." >
option to activate dust-snow internal mixing in SNICAR snow albedo calculation
(snicar_snodst_intmix='.true.' is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="do_sno_oc" type="logical" category="clm_physics"
group="clm_inparm" value=".false." >
option to activate organic carbon (OC) in SNICAR snow albedo calculation
(do_sno_oc='.true.' is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="rooting_profile_method_water" type="integer" category="clm_physics"
group="rooting_profile_inparm" valid_values="0,1,2" >
Index of rooting profile for water
Expand Down Expand Up @@ -1065,13 +1113,13 @@ Maximum nitrification rate constant (1/s)
<entry id="use_extralakelayers" type="logical" category="physics"
group="clm_inparm" valid_values="" value=".false.">
Toggle to use 25 lake layers instead of 10
(extralaklayers=".true." is EXPERIMENTAL NOT SUPPORTED! Nor is it Tested!)
(extralaklayers=".true." is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="use_vichydro" type="logical" category="physics"
group="clm_inparm" valid_values="" value=".false.">
Toggle to turn on the VIC hydrologic parameterizations
(vichydro=".true." is EXPERIMENTAL NOT SUPPORTED!)
(vichydro=".true." is EXPERIMENTAL, UNSUPPORTED!)
</entry>

<entry id="use_crop" type="logical" category="physics"
Expand Down Expand Up @@ -1151,9 +1199,8 @@ DependsOnLatAndVeg - Arctic vegetation depends on latitude as above, but tempera
</entry>

<entry id="use_snicar_frc" type="logical" category="physics"
group="clm_inparm" valid_values="" value=".false.">
Toggle to turn on calculation of SNow and Ice Aerosol Radiation model (SNICAR) radiative forcing
(snicar_frc=".true." is EXPERIMENTAL NOT SUPPORTED!)
group="clm_inparm" value=".false.">
Toggle to turn on calculation of SNow and Ice Aerosol Radiation model (SNICAR) albedo forcing diagnostics for each aerosol species
</entry>

<entry id="use_noio" type="logical" category="default_settings"
Expand Down Expand Up @@ -1779,7 +1826,7 @@ prescribed data.
<entry id="use_lai_streams" type="logical" category="physics"
group="clm_inparm" valid_values="" value=".false.">
Toggle to turn on use of LAI streams in place of the LAI on the surface dataset when using Satellite Phenology mode.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="stream_year_first_lai" type="integer" category="datasets"
Expand Down Expand Up @@ -2232,7 +2279,7 @@ Profile over which to distribute C and N coming from surface pools (leaves, stem
<entry id="no_frozen_nitrif_denitrif" type="logical" category="clm_vertcn"
group="clm_inparm" valid_values="" >
If true, no denitrification or nitrification in frozen soil layers.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="nfix_timeconst" type="real" category="clm_vertcn"
Expand Down Expand Up @@ -2311,13 +2358,13 @@ tests. This namelist flag bypasses this error-check.
group="clm_inparm" valid_values="" >
If TRUE, weight btran (vegetation soil moisture availability) by unfrozen layers only, assuming that vegetation
will allocate roots preferentially to the active layer.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="perchroot_alt" type="logical" category="clm_permafrost"
group="clm_inparm" valid_values="" >
If TRUE, weight btran (vegetation soil moisture availability) by the active layer, as defined by the greatest thaw depth over the current and prior years.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<!-- stress deciduous onset trigger -->
Expand Down Expand Up @@ -2353,7 +2400,7 @@ How much Carbon to initialize vegetation pools (leafc/frootc and storage) to whe
<entry id="CNratio_floating" type="logical" category="clm_nitrogen"
group="clm_nitrogen" value=".false.">
Flexible CN ratio used for Phenology
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="reduce_dayl_factor" type="logical" category="clm_nitrogen"
Expand All @@ -2365,21 +2412,21 @@ How much Carbon to initialize vegetation pools (leafc/frootc and storage) to whe
<entry id="vcmax_opt" type="integer" category="clm_nitrogen"
group="clm_nitrogen" valid_values="0,3,4">
Vcmax calculation for Photosynthesis
vcmax_opt = 4 As for vcmax_opt=0, but using leafN, and exponential if tree (EXPERIMENTAL NOT TESTED!)
vcmax_opt = 4 As for vcmax_opt=0, but using leafN, and exponential if tree (EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
vcmax_opt = 3 Based on leafN and VCAD (used with Luna for crop and C4 vegetation)
vcmax_opt = 0 Based on canopy top and foilage Nitrogen limitation factor from params file (clm4.5)
</entry>

<entry id="CN_evergreen_phenology_opt" type="integer" category="clm_nitrogen"
group="clm_nitrogen" valid_values="0,1">
Evergreen phenology option for CNPhenology
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="carbon_resp_opt" type="integer" category="clm_nitrogen"
group="clm_nitrogen" valid_values="0,1">
Carbon respiration option to burn off carbon when CN ratio is too high (do NOT use when FUN is on)
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>


Expand Down Expand Up @@ -2437,7 +2484,7 @@ then don't fix aere (see ch4Mod.F90).
<entry id="allowlakeprod" type="logical" category="clm_methane"
group="ch4par_in" valid_values="" >
If TRUE, turn on methane biogeochemistry model for lake columns, using a simplified version of the CH4 submodel.
(EXPERIMENTAL)
(EXPERIMENTAL, UNSUPPORTED!)
</entry>

<entry id="usephfact" type="logical" category="clm_methane"
Expand All @@ -2456,7 +2503,7 @@ If TRUE, maintain constant soil carbon under lakes, and use the methane submodel
CO2 (via biological assimilation, decomposition, and methanogenesis) to CH4. If FALSE, transiently decompose initial
soil carbon stock based on soil carbon dataset. NOTE: if FALSE, a new transient source of C is added to the climate system,
so the coupled system will NOT conserve carbon in this mode if the methane model is coupled to the atmosphere.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="finundation_method" type="char*50" category="clm_methane"
Expand All @@ -2469,22 +2516,22 @@ ZWT_inversion ---- Use inversion of Prigent Satellite data to model ZWT
TWS_inversion ---- Use inversion of Prigent Satellite data to model TWS

Inversion options require additional data on fsurdat or use of stream_fldfilename_ch4finundated files.
(h2osfc option is EXPERIMENTAL and NOT tested)
(h2osfc option is EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="usefrootc" type="logical" category="clm_methane"
group="ch4par_in" valid_values="" >
If TRUE, use the fine root carbon predicted by CN when calculating the aerenchyma area, rather than the parametrization
based on annual NPP, aboveground NPP fraction, and LAI.
(EXPERIMENTAL and NOT tested)
(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
</entry>

<entry id="ch4offline" type="logical" category="clm_methane"
group="ch4par_in" valid_values="" >
If TRUE, run the methane submodel decoupled from the atmosphere. The atmospheric methane concentration is prescribed by
atmch4, the methane flux is not passed to the atmosphere, and the CO2 flux to the atmosphere is not adjusted for
net methane production. NOTE: Currently this must be TRUE.
(EXPERIMENTAL and NOT functional)
(EXPERIMENTAL, UNSUPPORTED, and NOT functional!)
</entry>

<!-- ======================================================================================== -->
Expand Down
Loading

0 comments on commit 3636565

Please sign in to comment.