Merge pull request #1897 from dmleung/dustemis_dev

A new physically based dust emission scheme with more aeolian physics (updated)

bld/CLMBuildNamelist.pm

@@ -1764,6 +1764,7 @@ sub process_namelist_inline_logic {
   # namelist options for dust emissions
   ######################################
   setup_logic_dust_emis($opts, $nl_flags, $definition, $defaults, $nl, $envxml_ref);
+  setup_logic_prigent_roughness($opts, $nl_flags, $definition, $defaults, $nl);
 
   #################################
   # namelist group: megan_emis_nl #
@@ -4075,9 +4076,6 @@ sub setup_logic_dust_emis {
                                  "$option is being set, need to change one or the other" );
             }
          }
-         if ( $dust_emis_method eq "Leung_2023" ) {
-            $log->warning("dust_emis_method is Leung_2023 and that option has NOT been brought into CTSM yet");
-         }
       }
   # Otherwise make sure dust settings are NOT being set in CLM
   } else {
@@ -5081,6 +5079,33 @@ sub setup_logic_misc {
 
 #-------------------------------------------------------------------------------
 
+sub setup_logic_prigent_roughness {
+  #
+  # The Prigent roughness stream data set read in if needed
+  #
+  my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
+  my $var = "use_prigent_roughness";
+  my $dust_emis_method = remove_leading_and_trailing_quotes( $nl->get_value('dust_emis_method') );
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, $var,
+              'dust_emis_method'=>$dust_emis_method );
+  my $use_prigent = $nl->get_value($var);
+  if ( &value_is_true($use_prigent) ) {
+     if ( $dust_emis_method ne "Leung_2023" ) {
+       # The Prigent dataset could be used for other purposes
+       # (such as roughness as in https://github.com/ESCOMP/CTSM/issues/2349)
+       $log->warning( "$var does NOT need to on without dust_emis_method being Leung_2023, it simply won't be used" );
+     }
+     add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'stream_fldfilename_prigentroughness' );
+     add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'stream_meshfile_prigentroughness' );
+  } elsif ( $dust_emis_method eq "Leung_2023" ) {
+    # In the future we WILL allow it to be turned off for testing and Paleo work
+    # see: https://github.com/ESCOMP/CTSM/issues/2381)
+    $log->fatal_error("variable \"$var\" MUST be true when Leung_2023 dust emission method is being used" );
+  }
+}
+
+#-------------------------------------------------------------------------------
+
 sub write_output_files {
   my ($opts, $nl_flags, $defaults, $nl) = @_;
 
@@ -5133,6 +5158,7 @@ sub write_output_files {
   push @groups, "clm_temperature_inparm";
   push @groups, "soilbgc_decomp";
   push @groups, "clm_canopy_inparm";
+  push @groups, "prigentroughness";
   push @groups, "zendersoilerod";
   if (remove_leading_and_trailing_quotes($nl->get_value('snow_cover_fraction_method')) eq 'SwensonLawrence2012') {
      push @groups, "scf_swenson_lawrence_2012_inparm";

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -2565,6 +2565,17 @@ lnd/clm2/surfdata_esmf/NEON/surfdata_1x1_NEON_TOOL_hist_78pfts_CMIP6_simyr2000_c
 <stream_meshfile_zendersoilerod dust_emis_method="Zender_2003" zender_soil_erod_source="lnd"
 >lnd/clm2/dustemisdata/dust_2x2_ESMFmesh_cdf5_c230730.nc</stream_meshfile_zendersoilerod>
 
+<!-- =========================================  -->
+<!-- Defaults for Prigent's roughness data      -->
+<!-- =========================================  -->
+
+<use_prigent_roughness dust_emis_method="Leung_2023">.true.</use_prigent_roughness>
+<use_prigent_roughness                              >.false.</use_prigent_roughness>
+<stream_fldfilename_prigentroughness
+>lnd/clm2/dustemisdata/Prigent_2005_roughness_0.25x0.25_cdf5_c240127.nc</stream_fldfilename_prigentroughness>
+<stream_meshfile_prigentroughness
+>lnd/clm2/dustemisdata/dust_0.25x0.25_ESMFmesh_cdf5_c240222.nc</stream_meshfile_prigentroughness>
+
 <!-- =========================================  -->
 <!-- Defaults for different BGC/decomp modes    -->
 <!-- =========================================  -->

bld/namelist_files/namelist_definition_ctsm.xml

@@ -1694,6 +1694,25 @@ Mapping method from Nitrogen deposition input file to the model resolution
     copy     = copy using the same indices
 </entry>
 
+<!-- ========================================================================================  -->
+<!-- Prigent roughness stream -->
+<!-- ========================================================================================  -->
+
+<entry id="use_prigent_roughness" type="logical" category="clm_physics"
+        group="prigentroughness" valid_values="" >
+If TRUE use the Prigent roughness dataset
+</entry>
+
+<entry id="stream_fldfilename_prigentroughness" type="char*256" category="datasets"
+       input_pathname="abs" group="prigentroughness" valid_values="" >
+Filename of input stream data for aeolian roughness length (from Prigent's roughness dataset)
+</entry>
+
+<entry id="stream_meshfile_prigentroughness" type="char*256" category="datasets"
+       input_pathname="abs" group="prigentroughness" valid_values="" >
+mesh filename of input stream data for aeolian roughness length (from Prigent's roughness dataset)
+</entry>
+
 <!-- ========================================================================================  -->
 <!-- Dust namelist and Zender soil erodibility stream                                          -->
 <!-- ========================================================================================  -->
@@ -1783,6 +1802,7 @@ If true, will ignore the prescribed soilm data for that point and let the model
 prescribed data.
 </entry>
 
+
 <!-- ========================================================================================  -->
 <!-- lai_streams streams Namelist (when phys = CLM4_5)                              -->
 <!-- ========================================================================================  -->

bld/unit_testers/build-namelist_test.pl

@@ -163,7 +163,7 @@ sub cat_and_create_namelistinfile {
 #
 # Figure out number of tests that will run
 #
-my $ntests = 3338;
+my $ntests = 3339;
 
 if ( defined($opts{'compare'}) ) {
    $ntests += 1999;
@@ -517,6 +517,10 @@ sub cat_and_create_namelistinfile {
                                      namelst=>"use_crop=.true.",
                                      phys=>"clm4_5",
                                    },
+     "LeungDust_WO_Prigent"      =>{ options=>" -envxml_dir . -bgc sp",
+                                     namelst=>"use_prigent_roughness=.false.",
+                                     phys=>"clm5_1",
+                                   },
      "soilm_stream off w file"      =>{ options=>"-res 0.9x1.25 -envxml_dir .",
                                      namelst=>"use_soil_moisture_streams = .false.,stream_fldfilename_soilm='file_provided_when_off'",
                                      phys=>"clm5_0",
@@ -539,17 +543,14 @@ sub cat_and_create_namelistinfile {
                                    },
      "coldstart exice on wo stream"=>{ options=>"-res 0.9x1.25 -envxml_dir . --clm_start_type cold",
                                      namelst=>"use_excess_ice=.true., use_excess_ice_streams = .false.",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm6_0",
                                    },
      "coldstart exice on bad temp" =>{ options=>"-res 0.9x1.25 -envxml_dir . --clm_start_type cold",
                                      namelst=>"use_excess_ice=.true., use_excess_ice_streams = .true., excess_ice_coldstart_temp=0.0",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm6_0",
                                    },
      "coldstart exice on bad depth" =>{ options=>"-res 0.9x1.25 -envxml_dir . --clm_start_type cold",
                                      namelst=>"use_excess_ice=.true., use_excess_ice_streams = .true., excess_ice_coldstart_depth=0.0",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm6_0",
                                    },
      "clm50CNDVwtransient"       =>{ options=>" -envxml_dir . -use_case 20thC_transient -dynamic_vegetation -res 10x15 -ignore_warnings",
@@ -1235,10 +1236,6 @@ sub cat_and_create_namelistinfile {
 
 my %warntest = (
      # Warnings without the -ignore_warnings option given
-     "dustemisLeung"             =>{ options=>"-envxml_dir .",
-                                     namelst=>"dust_emis_method = 'Leung_2023'",
-                                     phys=>"clm5_1",
-                                   },
      "coldwfinidat"              =>{ options=>"-envxml_dir . -clm_start_type cold",
                                      namelst=>"finidat = 'testfile.nc'",
                                      phys=>"clm5_0",
@@ -1273,12 +1270,14 @@ sub cat_and_create_namelistinfile {
                                    },
      "Set coldtemp wo coldstart" =>{ options=>"-envxml_dir . --clm_start_type startup",
                                      namelst=>"use_excess_ice=.true.,excess_ice_coldstart_temp=-10.",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
                                      phys=>"clm6_0",
                                    },
      "Set colddepth wo coldstart" =>{ options=>"-envxml_dir . --clm_start_type startup",
                                      namelst=>"use_excess_ice=.true.,excess_ice_coldstart_depth=0.5",
-                                     GLC_TWO_WAY_COUPLING=>"FALSE",
+                                     phys=>"clm6_0",
+                                   },
+     "PrigentOnWOLeung"          =>{ options=>"-envxml_dir . -bgc sp",
+                                     namelst=>"use_prigent_roughness=.true.,dust_emis_method='Zender_2003'",
                                      phys=>"clm6_0",
                                    },
      "NotNEONbutNEONlightres"    =>{ options=>"--res CLM_USRDAT --clm_usr_name regional --envxml_dir . --bgc bgc --light_res 106x174",

cime_config/testdefs/testlist_clm.xml

@@ -100,7 +100,7 @@
       <option name="comment">Simple test use soil eroditability in CTSM for CAM5 tuning</option>
     </options>
   </test>
-  <test name="ERP_D_Ld9" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningMode">
+  <test name="ERP_D_Ld9" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningModeLDust">
     <machines>
       <machine name="derecho" compiler="intel" category="aux_clm"/>
     </machines>
@@ -109,7 +109,7 @@
       <option name="comment">CESM3 development Exact restart test with change in the processor count at the standard coupled resolution</option>
     </options>
   </test>
-    <test name="ERP_D_Ld9" grid="f10_f10_mg37" compset="I1850Clm60BgcCrop" testmods="clm/clm60cam7LndTuningMode">
+    <test name="ERP_D_Ld9" grid="f10_f10_mg37" compset="I1850Clm60BgcCrop" testmods="clm/clm60cam7LndTuningModeLDust">
     <machines>
       <machine name="izumi" compiler="nag" category="aux_clm"/>
     </machines>
@@ -129,7 +129,7 @@
       <option name="comment">CESM3 development Exact restart test with change in the processor count at the standard coupled resolution</option>
     </options>
   </test>
-  <test name="ERP_D_Ld9" grid="ne30pg3_t232" compset="IHistClm60BgcCropG" testmods="clm/clm60cam7LndTuningMode">
+  <test name="ERP_D_Ld9" grid="ne30pg3_t232" compset="IHistClm60BgcCropG" testmods="clm/clm60cam7LndTuningModeLDust">
     <machines>
       <machine name="derecho" compiler="intel" category="aux_clm"/>
     </machines>
@@ -138,15 +138,6 @@
       <option name="comment">CESM3 development Exact restart test with change in the processor count at the standard coupled resolution for transient</option>
     </options>
   </test>
-  <test name="PEM_D_Ld9" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningMode">
-    <machines>
-      <machine name="derecho" compiler="intel" category="aux_clm"/>
-    </machines>
-    <options>
-      <option name="wallclock">00:20:00</option>
-      <option name="comment">CESM3 development test with change in the processor count at the standard coupled resolution</option>
-    </options>
-  </test>
   <test name="ERS_D_Ld9" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningMode">
     <machines>
       <machine name="derecho" compiler="intel" category="aux_clm"/>
@@ -156,7 +147,7 @@
       <option name="comment">CESM3 development simple exact restart test at the standard coupled resolution</option>
     </options>
   </test>
-  <test name="ERI_D" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningMode">
+  <test name="ERI_D" grid="ne30pg3_t232" compset="I1850Clm60BgcCropG" testmods="clm/clm60cam7LndTuningModeLDust">
     <machines>
       <machine name="derecho" compiler="intel" category="aux_clm"/>
     </machines>
@@ -247,7 +238,7 @@
       <option name="comment">Test that the workhorse mpasa resolution functions for CAM, for both Hist and 2000 with latest CLM version. No need to run this test with every tag, but include it in the less frequent ctsm_sci testing.</option>
     </options>
   </test>
-  <test name="SMS_Ln9" grid="mpasa60_mpasa60" compset="I2000Clm60Sp" testmods="clm/clm60cam7LndTuningMode">
+  <test name="SMS_Ln9" grid="mpasa60_mpasa60" compset="I2000Clm60Sp" testmods="clm/clm60cam7LndTuningModeLDust">
     <machines>
       <machine name="derecho" compiler="intel" category="ctsm_sci"/>
     </machines>

cime_config/testdefs/testmods_dirs/clm/clm45cam4LndTuningModeZDustSoilErod/user_nl_clm

@@ -1,3 +1,4 @@
 ! Turn on using the soil eroditability file in CTSM
 dust_emis_method = 'Zender_2003'
 zender_soil_erod_source = 'lnd'
+hist_fincl1   += 'FV'

cime_config/testdefs/testmods_dirs/clm/clm50cam5LndTuningModeZDustSoilErod/user_nl_clm

@@ -1,3 +1,4 @@
 ! Turn on using the soil eroditability file in CTSM
 dust_emis_method = 'Zender_2003'
 zender_soil_erod_source = 'lnd'
+hist_fincl1   += 'FV'

cime_config/testdefs/testmods_dirs/clm/clm51cam6LndTuningModeZDustSoilErod/user_nl_clm

@@ -1,3 +1,4 @@
 ! Turn on using the soil eroditability file in CTSM
 dust_emis_method = 'Zender_2003'
 zender_soil_erod_source = 'lnd'
+hist_fincl1   += 'FV'

cime_config/testdefs/testmods_dirs/clm/clm60cam7LndTuningModeLDust/include_user_mods

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

cime_config/testdefs/testmods_dirs/clm/clm60cam7LndTuningModeLDust/user_nl_clm

@@ -0,0 +1,5 @@
+dust_emis_method = 'Leung_2023'
+! Add all of the Leung optional history fields
+hist_fincl1   += 'FV', 'DUST_EMIS_COEFF', 'WND_FRC_FT', 'WND_FRC_FT_DRY', 'WND_FRC_IT', 'WND_FRC_SOIL', 'LND_FRC_MBLE', 'GWC', 'LIQ_FRAC', 
+                  'U_S_MEAN', 'U_S_MEAN', 'ZETAOBU', 'U_FT', 'U_IT', 'ALPHA_TC_RATE', 'P_IT', 'ETA', 'SSR', 'VAI_OKIN',
+                  'FRC_THR_RGHN_FCT', 'WND_FRC_FT_STD', 'DPFCT_ROCK'

doc/ChangeLog

@@ -1,4 +1,117 @@
 ===============================================================
+Tag name: ctsm5.2.019
+Originator(s): erik (Erik Kluzek,UCAR/TSS,303-497-1326)
+Date: Sun 11 Aug 2024 09:00:43 AM MDT
+One-line Summary: Add in an additional dust emission method Leung_2023, by default off
+
+Purpose and description of changes
+----------------------------------
+
+Author: Danny Leung
+This is a scheme that builds upon a switch of CESM2's default dust emission scheme (Zender et al., 2003) to
+@jfkok's more physical and less empirical one (Kok et al., 2014). This brings in additional modifications and add new aeolian
+physics to the Kok's scheme, most notably, by adding the roughness effect (or called drag partition effect) which discounts surface
+soil erosion by winds due to the presence of local-scale land-surface roughness elements (mostly plants and rocks). We use a hybrid
+approach to account for both roughness from rocks (with a 2-D time-invariant dataset provided by Prigent et al., 2005; 2012) and
+roughness from plants (time-varying, as a function of CLM's LAI). We further include the dust emission intermittency effects due to
+boundary-layer turbulence.
+
+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.]
+
+[ ] clm6_0
+
+[ ] clm5_1
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+   #1604 -- A new physically based dust emission scheme with more aeolian physics (updated) 
+
+Notes of particular relevance for users
+---------------------------------------
+
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): New namelist items
+   dust_emis_method can now be set to Leung_2023
+
+    use_prigent_roughness ---------------- Logical to use the Prigent dataset (default on when Leung_2023 is used)
+    stream_fldfilename_prigentroughness -- Prigent streams dataset
+    stream_meshile_prigentroughness ------ Mesh file for the dataset
+
+    History field FV can now be output for any compset, but it's default off
+
+Changes to the datasets (e.g., parameter, surface or initial files):
+    New Prigent streams dataset with aeolian roughness length
+
+Notes of particular relevance for developers:
+---------------------------------------------
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+  Some issues will be worked on later
+
+    #2568 -- Turn on Leung by default for clm6_0 physics
+
+    #2381 -- Allow Prigent streams to be off in Leung_2023 dust emissions for Paleo work
+             (Fixing this will allow a unit-test module to be removed)
+
+    #2680 -- prigentroughnessmapalgo is hardcoded to bilinear add it to the namelist so it can change (change name to snake-case)
+
+    #2681 -- Add global dust variables to the DustEmisBase class that apply to both Zender and Leung dust emission methods bfb enhancement next
+
+    #2682 -- Small function and saved constants for convective velocity code cleanup enhancement priority
+
+Changes to tests or testing:
+   New test mod that explicitly turns on Leung_2023 dust emissions: clm60cam7LndTuningModeLDust
+   Some of the tests with clm60cam7LndTuningMode were converted to this test mod
+   PF unit tester was added for Leung_2023
+   More work could be done in the unit-testers to exercise more of the code
+
+Testing summary: regular
+----------------
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho - PASS (1002 are different)
+
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
+
+    derecho - PASS
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: no bit-for-bit (unless you turn the new dust scheme on)
+  Tests with BGC change answers because fieldlists are different (FV is no longer on history files by default)
+
+Other details
+-------------
+
+Pull Requests that document the changes (include PR ids):
+(https://github.com/ESCOMP/ctsm/pull)
+   #1897 -- A new physically based dust emission scheme with more aeolian physics (updated) 
+
+===============================================================
+===============================================================
 Tag name: ctsm5.2.018
 Originator(s): mvdebolskiy
 Date: Fri 02 Aug 2024 09:26:33 AM MDT

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.2.019     erik 08/11/2024 Add in an additional dust emission method Leung_2023, by default off
        ctsm5.2.018 mvdebols 08/02/2024 Fix/excess ice cold start
        ctsm5.2.017     erik 07/30/2024 Dust emissions control moved to cmeps
        ctsm5.2.016 samrabin 07/27/2024 Enable new crop calendars for clm60 compsets

src/biogeochem/CMakeLists.txt

@@ -7,6 +7,7 @@ list(APPEND clm_sources
   CNSpeciesMod.F90
   CNDVType.F90
   DustEmisBase.F90
+  DustEmisLeung2023.F90
   DustEmisZender2003.F90
   DustEmisFactory.F90
   CropReprPoolsMod.F90