SNICAR snow albedo scheme updates

bld/CLMBuildNamelist.pm

@@ -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);
@@ -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' );
 }
 

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -1555,8 +1555,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>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -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
@@ -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"
@@ -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"
@@ -1771,7 +1818,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"
@@ -2224,7 +2271,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"
@@ -2303,13 +2350,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    -->
@@ -2345,7 +2392,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"
@@ -2357,21 +2404,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>
 
 
@@ -2429,7 +2476,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"
@@ -2448,7 +2495,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"
@@ -2461,22 +2508,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>
 
 <!-- ========================================================================================  -->