ESCOMP · samsrabin · Oct 30, 2023 · Jul 27, 2023 · Aug 22, 2023 · Aug 22, 2023
diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg
@@ -2,7 +2,7 @@
 local_path = src/fates
 protocol = git
 repo_url = https://github.com/NGEET/fates
-tag = sci.1.67.2_api.27.0.0
+tag = sci.1.68.0_api.28.0.0
 required = True
 
 [externals_description]

diff --git a/bld/CLMBuildNamelist.pm b/bld/CLMBuildNamelist.pm
@@ -769,8 +769,8 @@ sub setup_cmdl_fates_mode {
        # dis-allow fates specific namelist items with non-fates runs
        my @list  = (  "fates_spitfire_mode", "use_fates_planthydro", "use_fates_ed_st3", "use_fates_ed_prescribed_phys",
                       "use_fates_cohort_age_tracking","use_fates_inventory_init","use_fates_fixed_biogeog",
-		      "use_fates_nocomp","use_fates_sp","fates_inventory_ctrl_filename","use_fates_logging",
-		      "fates_parteh_mode","use_fates_tree_damage" );
+                      "use_fates_nocomp","use_fates_sp","fates_inventory_ctrl_filename","use_fates_logging",
+                      "fates_parteh_mode","use_fates_tree_damage","fates_seeddisp_cadence" );
        # dis-allow fates specific namelist items with non-fates runs
        foreach my $var ( @list ) {
           if ( defined($nl->get_value($var)) ) {
@@ -4010,21 +4010,28 @@ sub setup_logic_cropcal_streams {
   # Option checks
   my $generate_crop_gdds = $nl->get_value('generate_crop_gdds') ;
   my $use_mxmat = $nl->get_value('use_mxmat') ;
-  my $sdate_file = $nl->get_value('stream_fldFileName_sdate') ;
+  my $swindow_start_file = $nl->get_value('stream_fldFileName_swindow_start') ;
+  my $swindow_end_file = $nl->get_value('stream_fldFileName_swindow_end') ;
   my $gdd_file = $nl->get_value('stream_fldFileName_cultivar_gdds') ;
   my $mesh_file = $nl->get_value('stream_meshfile_cropcal') ;
+  if ( ($swindow_start_file eq '' and $swindow_start_file ne '') or ($swindow_start_file ne '' and $swindow_start_file eq '') ) {
+    $log->fatal_error("When specifying sowing window dates, you must provide both swindow_start_file and swindow_end_file. To specify exact sowing dates, use the same file." );
+  }
   if ( $generate_crop_gdds eq '.true.' ) {
       if ( $use_mxmat eq '.true.' ) {
           $log->fatal_error("If generate_crop_gdds is true, you must also set use_mxmat to false" );
       }
-      if ( $sdate_file eq '' ) {
-          $log->fatal_error("If generate_crop_gdds is true, you must specify stream_fldFileName_sdate")
+      if ( $swindow_start_file eq '' or $swindow_end_file eq '' ) {
+          $log->fatal_error("If generate_crop_gdds is true, you must specify stream_fldFileName_swindow_start and stream_fldFileName_swindow_end")
+      }
+      if ( $swindow_start_file ne $swindow_end_file ) {
+          $log->fatal_error("If generate_crop_gdds is true, you must specify exact sowing dates by setting stream_fldFileName_swindow_start and stream_fldFileName_swindow_end to the same file")
       }
       if ( $gdd_file ne '' ) {
           $log->fatal_error("If generate_crop_gdds is true, do not specify stream_fldFileName_cultivar_gdds")
       }
   }
-  if ( $mesh_file eq '' and ( $sdate_file ne '' or $gdd_file ne '' ) ) {
+  if ( $mesh_file eq '' and ( $swindow_start_file ne '' or $gdd_file ne '' ) ) {
       $log->fatal_error("If prescribing crop sowing dates and/or maturity requirements, you must specify stream_meshfile_cropcal")
   }
 }
@@ -4325,7 +4332,7 @@ sub setup_logic_fates {
     if (&value_is_true( $nl_flags->{'use_fates'})  ) {
         add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fates_paramfile', 'phys'=>$nl_flags->{'phys'});
         my @list  = (  "fates_spitfire_mode", "use_fates_planthydro", "use_fates_ed_st3", "use_fates_ed_prescribed_phys",
-                       "use_fates_inventory_init","use_fates_fixed_biogeog","use_fates_nocomp",
+                       "use_fates_inventory_init","use_fates_fixed_biogeog","use_fates_nocomp","fates_seeddisp_cadence",
                        "use_fates_logging","fates_parteh_mode", "use_fates_cohort_age_tracking","use_fates_tree_damage" );
         foreach my $var ( @list ) {
  	  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, $var, 'use_fates'=>$nl_flags->{'use_fates'},

diff --git a/bld/namelist_files/namelist_defaults_ctsm.xml b/bld/namelist_files/namelist_defaults_ctsm.xml
@@ -2714,6 +2714,7 @@ use_crop=".true.">lnd/clm2/surfdata_map/ctsm5.1.dev052/landuse.timeseries_mpasa1
 <use_fates_inventory_init      use_fates=".true.">.false.</use_fates_inventory_init>
 <use_fates_sp                  use_fates=".true.">.false.</use_fates_sp>
 <fates_parteh_mode             use_fates=".true.">1</fates_parteh_mode>
+<fates_seeddisp_cadence        use_fates=".true.">0</fates_seeddisp_cadence>
 
 <use_fates_nocomp              use_fates=".true." use_fates_sp=".true.">.true.</use_fates_nocomp>
 <use_fates_nocomp              use_fates=".true."                      >.false.</use_fates_nocomp>

diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml
@@ -686,6 +686,17 @@ Switch deciding which nutrient model to use in FATES.
 (Only relevant if FATES is on)
 </entry>
 
+<entry id="fates_seeddisp_cadence" type="integer" category="physics"
+        group="clm_inparm" valid_values="0,1,2,3">
+Switch defining the cadence at which seeds are dispersed across
+gridcells.  Setting the switch value to zero turns off dispersal.
+Setting the switch to 1, 2, or 3 sets the dispersal cadence to
+daily, monthly or yearly.  The daily cadence is primarily
+recommended for test and debug only. Note that turning this
+feature on will result in more memory usage.
+(Only relevant if FATES is on)
+</entry>
+
 <entry id="use_fates_tree_damage" type="logical" category="physics"
         group="clm_inparm" valid_values="" value=".false."> 
 Toggle to turn on the tree damage module in FATES
@@ -1882,9 +1893,19 @@ Last year to loop over for crop calendar data
 Simulation year that aligns with stream_year_first_cropcal value
 </entry>
 
-<entry id="stream_fldfilename_sdate" type="char*256(30)" category="datasets"
+<entry id="allow_invalid_swindow_inputs" type="logical" category="datasets"
+       group="cropcal_streams" valid_values="" >
+By default, a value in stream_fldFileName_swindow_start or _end outside the range [1, 365] (or 366 in leap years) will cause the run to fail. Set this to .true. to instead fall back on the paramfile sowing windows.
+</entry>
+
+<entry id="stream_fldFileName_swindow_start" type="char*256(30)" category="datasets"
+       input_pathname="abs" group="cropcal_streams" valid_values="" >
+Filename of input stream data for date (day of year) of start of sowing window. Cells with the same sowing window start and end date are always planted on that date, regardless of climatic conditions/history.
+</entry>
+
+<entry id="stream_fldFileName_swindow_end" type="char*256(30)" category="datasets"
        input_pathname="abs" group="cropcal_streams" valid_values="" >
-Filename of input stream data for sowing dates
+Filename of input stream data for date (day of year) of end of sowing window. Cells with the same sowing window start and end date are always planted on that date, regardless of climatic conditions/history.
 </entry>
 
 <entry id="stream_fldfilename_cultivar_gdds" type="char*256(30)" category="datasets"

diff --git a/cime_config/SystemTests/rxcropmaturity.py b/cime_config/SystemTests/rxcropmaturity.py
@@ -357,7 +357,8 @@ def _run_check_rxboth_run(self):
     def _modify_user_nl_allruns(self):
         nl_additions = [
             "stream_meshfile_cropcal = '{}'".format(self._case.get_value("LND_DOMAIN_MESH")),
-            "stream_fldFileName_sdate = '{}'".format(self._sdatefile),
+            "stream_fldFileName_swindow_start = '{}'".format(self._sdatefile),
+            "stream_fldFileName_swindow_end   = '{}'".format(self._sdatefile),
             "stream_year_first_cropcal = 2000",
             "stream_year_last_cropcal = 2000",
             "model_year_align_cropcal = 2000",

diff --git a/cime_config/testdefs/ExpectedTestFails.xml b/cime_config/testdefs/ExpectedTestFails.xml
@@ -109,7 +109,12 @@
     </phase>
   </test>
 
-
+  <test name="PEM_D_Ld15.5x5_amazon.I2000Clm50FatesRs.cheyenne_gnu.clm-FatesColdSeedDisp">
+    <phase name="COMPARE_base_modpes">
+      <status>FAIL</status>
+      <issue>FATES#1089</issue>
+    </phase>
+  </test>
 
 
 </expectedFails>
diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml
@@ -1835,6 +1835,24 @@
       <option name="wallclock">00:20:00</option>
     </options>
   </test>
+  <test name="ERS_D_Ld15" grid="5x5_amazon" compset="I2000Clm50FatesRs" testmods="clm/FatesColdSeedDisp">
+    <machines>
+      <machine name="cheyenne" compiler="gnu" category="fates"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment"  >This test should be convered to an ERP test once the PEM version of this test is passing COMPARE_base_modpes.</option>
+    </options>
+  </test>
+  <test name="PEM_D_Ld15" grid="5x5_amazon" compset="I2000Clm50FatesRs" testmods="clm/FatesColdSeedDisp">
+    <machines>
+      <machine name="cheyenne" compiler="gnu" category="fates"/>
+    </machines>
+    <options>
+      <option name="wallclock">00:40:00</option>
+      <option name="comment"  >This checks that the FATES seed dispersal MPI communication is consistent when the PE layout changes.</option>
+    </options>
+  </test>
   <test name="ERS_D_Ld15" grid="f45_f45_mg37" compset="I2000Clm50FatesRs" testmods="clm/FatesColdTreeDamage">
     <machines>
       <machine name="cheyenne" compiler="intel" category="fates"/>

diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README
@@ -0,0 +1,26 @@
+Testing FATES cross grid seed dispersal is activated by enabling the 
+namelist switch option fates_seeddisp_cadence as well as providing reasonable
+values to the fates parameter file for the following variables:
+
+fates_seed_dispersal_fraction
+fates_seed_dispersal_max_dist
+fates_seed_dispersal_pdf_scale
+fates_seed_dispersal_pdf_shape
+
+Given that the default fates parameter file has the above variables as unset,
+a custom fates parameter file must be supplied to appropriately test this mode.
+This testmod itself addresses CTSM issue 2151: https://github.com/ESCOMP/CTSM/issues/2151
+Note that to avoid exceeding the filename string length maximu, the parameter
+file generated on the fly is placed in the $SRCROOT/src/fates/parameter_files
+directory.  This may still run into problems is the $SRCROOT string is too long.
+
+The max_dist value will impact the size of the 'neighborhood' of gridcells
+that fates will attempt to distribute seeds to.  To limit the neighborhood to
+something tractable for a regression test, the user_nl_clm file points to a 
+specific fates parameter file that was generated to work with a 5x5_amazon 
+resolution.
+
+The main downside of this method is that this file will require a custom update
+for every fates parameter file API update.  Addressing CTSM issue #2126 will alleviate
+this issue as it will provide the capability to build the fates parameter file on 
+the fly which with the appropriate values for this test.
diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods
@@ -0,0 +1 @@
+../FatesCold
diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands
@@ -0,0 +1,11 @@
+SRCDIR=`./xmlquery SRCROOT --value`
+CASEDIR=`./xmlquery CASEROOT --value`
+FATESROOT=$SRCDIR/src/fates/
+FATESPARAMFILE=$FATESROOT/parameter_files/fates_params_seeddisp_4x5.nc
+
+ncgen -o $FATESPARAMFILE $FATESROOT/parameter_files/fates_params_default.cdl
+
+$FATESROOT/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_fraction --val 0.2 --allpfts
+$FATESROOT/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_max_dist --val 2500000 --allpfts
+$FATESROOT/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_pdf_scale --val 1e-05 --allpfts
+$FATESROOT/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_pdf_shape --val 0.1 --allpfts
diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/user_nl_clm b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/user_nl_clm
@@ -0,0 +1,3 @@
+fates_paramfile = '$SRCROOT/src/fates/parameter_files/fates_params_seeddisp_4x5.nc'
+fates_seeddisp_cadence = 1
+hist_fincl1       = 'FATES_SEEDS_IN_GRIDCELL_PF', 'FATES_SEEDS_OUT_GRIDCELL_PF'
diff --git a/cime_config/testdefs/testmods_dirs/clm/crop/user_nl_clm b/cime_config/testdefs/testmods_dirs/clm/crop/user_nl_clm
@@ -10,7 +10,7 @@ hist_fincl2  += 'DYN_COL_SOIL_ADJUSTMENTS_C'
 
 
 ! Annual crop variables on per-sowing/per-harvest axes, per PFT.
-hist_fincl3 = 'SDATES', 'SDATES_PERHARV', 'SYEARS_PERHARV', 'HDATES', 'GRAINC_TO_FOOD_PERHARV', 'GRAINC_TO_FOOD_ANN', 'HDATES', 'GDDHARV_PERHARV', 'GDDACCUM_PERHARV', 'HUI_PERHARV', 'SOWING_REASON_PERHARV', 'HARVEST_REASON_PERHARV'
+hist_fincl3 = 'SDATES', 'SDATES_PERHARV', 'SYEARS_PERHARV', 'HDATES', 'GRAINC_TO_FOOD_PERHARV', 'GRAINC_TO_FOOD_ANN', 'HDATES', 'GDDHARV_PERHARV', 'GDDACCUM_PERHARV', 'HUI_PERHARV', 'SOWING_REASON_PERHARV', 'HARVEST_REASON_PERHARV', 'SWINDOW_STARTS', 'SWINDOW_ENDS'
 hist_nhtfrq(3) = 17520
 hist_mfilt(3) = 1
 hist_type1d_pertape(3) = 'PFTS'

diff --git a/cime_config/testdefs/testmods_dirs/clm/sowingWindows/include_user_mods b/cime_config/testdefs/testmods_dirs/clm/sowingWindows/include_user_mods
@@ -0,0 +1 @@
+../default
diff --git a/cime_config/testdefs/testmods_dirs/clm/sowingWindows/user_nl_clm b/cime_config/testdefs/testmods_dirs/clm/sowingWindows/user_nl_clm
@@ -0,0 +1,5 @@
+stream_fldFileName_swindow_start = '/glade/p/cesmdata/cseg/inputdata/lnd/clm2/cropdata/calendars/processed/swindow_starts_ggcmi_crop_calendar_phase3_v1.01.2000-2000.20231005_145103.nc'
+stream_fldFileName_swindow_end = '/glade/p/cesmdata/cseg/inputdata/lnd/clm2/cropdata/calendars/processed/swindow_ends_ggcmi_crop_calendar_phase3_v1.01.2000-2000.20231005_145103.nc'
+stream_meshfile_cropcal = '/glade/p/cesmdata/cseg/inputdata/share/meshes/360x720_120830_ESMFmesh_c20210507_cdf5.nc'
+stream_year_first_cropcal = 2000
+stream_year_last_cropcal = 2000
diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -1,4 +1,98 @@
 ===============================================================
+Tag name: ctsm5.1.dev146
+Originator(s): glemieux (Gregory Lemieux, LBNL, [email protected])
+Date: Tue Oct 24 20:13:17 MDT 2023
+One-line Summary: FATES cross-grid seed dispersal
+
+Purpose and description of changes
+----------------------------------
+
+This PR enables FATES to disperse seeds across neighboring grid cells using MPI. 
+The API update includes calls to new fates dispersal procedures.  There are
+four parameters that are utilized to control the dispersal kernel, although
+these were introduced in ctsm5.1.dev130 so no new default FATES parameter file
+is necessary with this update.  A new namelist parameter has been added to 
+enable the use of the seed dispersal mode.
+
+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
+
+
+Bugs fixed or introduced
+------------------------
+Known bugs introduced in this tag (include issue #):
+- ESCOMP/CTSM#1089 (Cross-grid seed dispersal mechanism is not b4b for PE layout changes)
+
+Notes of particular relevance for users
+---------------------------------------
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+- New namelist option, fates_seeddisp_cadence, added.  This option Setting the switch 
+value to zero turns off dispersal.  Setting the switch to 1, 2, or 3 sets the dispersal 
+cadence to daily, monthly or yearly.
+
+Substantial timing or memory changes:
+- Users should be careful to limit the maximum dispersal distance parameter,
+fates_seed_dispersal_max_dist, to a reasonable value based on the gridcell 
+resolution used.  Using a very large value will increase the memory requirements
+to store the gridcell neighborhood information.
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+- This PR introduces MPI calls to subroutines that are called by clm_driver.
+Comments have been provided in code to make future developers aware of these
+calls so as to avoid moving them into OpenMP threaded regions.
+
+Changes to tests or testing:
+- Two new testmods have been added into the fates suite to test seed
+dispersal.  One of the tests is to track issue CTSM#1089 which was introduced
+with this PR.
+
+Testing summary:
+----------------
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    cheyenne ---- OK
+    izumi ------- PASS
+
+  fates tests: (give name of baseline if different from CTSM tagname, normally fates baselines are fates-<FATES TAG>-<CTSM TAG>)
+    cheyenne ---- OK
+    izumi ------- OK
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: Only fates testmods in aux_clm are
+answer changing due to science updates associated with externals update.
+
+Other details
+-------------
+
+List any externals directories updated (cime, rtm, mosart, cism, fates, etc.):
+- fates: sci.1.67.2_api.27.0.0 -> sci.1.68.0_api.28.0.0
+
+Pull Requests that document the changes (include PR ids):
+https://github.com/ESCOMP/CTSM/pull/2077
+https://github.com/NGEET/fates/pull/1005
+
+===============================================================
+===============================================================
 Tag name: ctsm5.1.dev145
 Originator(s): @cenlinhe (Cenlin He,UCAR/RAL), slevis (Samuel Levis,UCAR/TSS,303-665-1310)
 Date: Thu Oct 19 14:34:25 MDT 2023

diff --git a/doc/ChangeSum b/doc/ChangeSum
@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+    ctsm5.1.dev146 glemieux 10/24/2023 FATES cross-grid seed dispersal
     ctsm5.1.dev145   slevis 10/19/2023 SNICAR snow albedo scheme updates
     ctsm5.1.dev144 samrabin 10/19/2023 Remove a deprecated shr_mpi_bcast call
     ctsm5.1.dev143   rgknox 10/13/2023 Zeroing of wood product fluxes on fates columns