Merge branch 'glemieux/lnd/fates-landuse-v2' into next (PR #6353)

This pull request adds the capability to read a landuse x pft mapping file to then be passed to fates.
It also refactors the use_fates_logging namelist option from a switch to a mode select.
This update allows the user to select a harvest mode that provides the mass or area-based
land use harvest rates from the LUH2 landuse timeseries dataset.

The fates pull request associated with this update is NGEET/fates#1116

[non-BFB] for FATES

cime_config/tests.py

@@ -436,21 +436,30 @@
         },
 
     #fates testmod coverage
+    "fates_landuse" : {
+        "time"    : "00:40:00",
+        "tests"   : (
+            "ERS_Ld60.f45_g37.IELMFATES.elm-fates_cold_logging",
+            "ERS_D_Ld30.f45_g37.IELMFATES.elm-fates_cold_landuse",
+            "ERS_D_Ld30.f45_g37.IELMFATES.elm-fates_cold_luh2",
+            "ERS_D_Ld30.f45_g37.IELMFATES.elm-fates_cold_luh2harvestarea",
+            "ERS_D_Ld30.f45_g37.IELMFATES.elm-fates_cold_luh2harvestmass",
+            )
+        },
+    #fates testmod coverage
     "fates" : {
-        "inherit" : ("fates_long_tests", "fates_elm_developer"),
+        "inherit" : ("fates_long_tests", "fates_elm_developer", "fates_landuse"),
         "tests" : (
             "ERP_Ld15.ne4pg2_ne4pg2.IELMFATES.elm-fates_cold_allvars",
             "ERP_Ld3.f09_g16.IELMFATES.elm-fates_cold",
             "ERP_D_Ld3.f19_g16.IELMFATES.elm-fates_cold",
             "ERS_D_Ld3_PS.f09_g16.IELMFATES.elm-fates_cold",
             "ERS_D_Ld5.f45_g37.IELMFATES.elm-fates_cold",
-            "ERS_D_Ld30.f45_g37.IELMFATES.elm-fates_cold_landuse",
             "ERS_Ld30.f45_g37.IELMFATES.elm-fates_satphen",
             "ERS_Ld30.f45_g37.IELMFATES.elm-fates_cold_fixedbiogeo",
             "ERS_Ld30.f45_g37.IELMFATES.elm-fates_cold_nocomp",
             "ERS_Ld30.f45_g37.IELMFATES.elm-fates_cold_nocomp_fixedbiogeo",
             "ERS_Ld60.f45_g37.IELMFATES.elm-fates",
-            "ERS_Ld60.f45_g37.IELMFATES.elm-fates_cold_logging",
             "ERS_Ld60.f45_g37.IELMFATES.elm-fates_cold_nofire",
             "ERS_Ld60.f45_g37.IELMFATES.elm-fates_cold_st3",
             "ERS_Ld60.f45_g37.IELMFATES.elm-fates_cold_pphys",

components/elm/bld/namelist_files/namelist_defaults.xml

@@ -134,7 +134,7 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 <!-- ================================================================== -->
 <!-- FATES default parameter file                                       -->
 <!-- ================================================================== -->
-<fates_paramfile >lnd/clm2/paramdata/fates_params_api.35.0.0_12pft_c240326.nc</fates_paramfile>
+<fates_paramfile >lnd/clm2/paramdata/fates_params_api.36.0.0_12pft_c240517.nc</fates_paramfile>
 
 <!-- soil order related parameters (relative to {csmdata}) -->
 <fsoilordercon             >lnd/clm2/paramdata/CNP_parameters_c131108.nc</fsoilordercon>
@@ -587,10 +587,15 @@ lnd/clm2/surfdata_map/surfdata_conusx4v1_simyr2000_c160503.nc</fsurdat>
 <flanduse_timeseries hgrid="ne30np4"       rcp="2.6" sim_year_range="1850-2100"
  use_crop=".false." >lnd/clm2/surfdata_map/surfdata.pftdyn_ne30np4_rcp2.6_simyr1850-2100_c130524.nc</flanduse_timeseries>
 
-<!-- Land Use Harmonization unified data sets for dynamic FATES land use change -->
+<!-- Land Use Harmonization unified timeseries data sets for dynamic FATES land use change -->
 <fluh_timeseries hgrid="4x5" sim_year_range="1850-2015" use_fates=".true."
  >lnd/clm2/surfdata_map/fates-sci.1.68.3_api.31.0.0_tools.1.0.1/LUH2_states_transitions_management.timeseries_4x5_hist_simyr1850-2015_c231101.nc</fluh_timeseries>
 
+<fluh_timeseries hgrid="4x5" sim_year_range="constant" use_fates=".true."
+>lnd/clm2/surfdata_map/fates-sci.1.68.3_api.31.0.0_tools.1.0.1/LUH2_states_transitions_management.timeseries_4x5_hist_simyr1850-2015_c231101.nc</fluh_timeseries>
+
+<!-- Land Use Harmonization static landuse x pft mapping data sets for FATES land use change -->
+<flandusepftdat hgrid="4x5" use_fates=".true." >lnd/clm2/surfdata_map/fates-sci.1.77.0_api.36.0.0/fates_landuse_pft_map_4x5_240206.nc</flandusepftdat>
 
 <!-- GLC mask datasets (relative to {csmdata}) -->
 <!-- Currently glc_grid is not being read from anywhere, so these rules are broken.  -->
@@ -2177,25 +2182,31 @@ this mask will have smb calculated over the entire global land surface
 <!-- Defaults for FATES interface -->
 <!-- =========================================  -->
 <fates_spitfire_mode           use_fates=".true.">0</fates_spitfire_mode>
-<use_fates_fixed_biogeog       use_fates=".true.">.false.</use_fates_fixed_biogeog>
-<use_fates_nocomp              use_fates=".true.">.false.</use_fates_nocomp>
+<fates_harvest_mode            use_fates=".true.">no_harvest</fates_harvest_mode>
+<fates_history_dimlevel        use_fates=".true.">2,2</fates_history_dimlevel>
+<fates_inventory_ctrl_filename use_fates=".true."> "/dev/null" </fates_inventory_ctrl_filename>
+<fates_parteh_mode             use_fates=".true.">1</fates_parteh_mode>
+<fates_seeddisp_cadence        use_fates=".true.">0</fates_seeddisp_cadence>
 <use_fates_planthydro          use_fates=".true.">.false.</use_fates_planthydro>
 <use_fates_tree_damage         use_fates=".true.">.false.</use_fates_tree_damage>
 <use_fates_ed_st3              use_fates=".true.">.false.</use_fates_ed_st3>
 <use_fates_ed_prescribed_phys  use_fates=".true.">.false.</use_fates_ed_prescribed_phys>
-<use_fates_logging             use_fates=".true.">.false.</use_fates_logging>
 <use_fates_cohort_age_tracking use_fates=".true.">.false.</use_fates_cohort_age_tracking>
 <use_fates_sp                  use_fates=".true.">.false.</use_fates_sp>
-<use_fates_luh                 use_fates=".true.">.false.</use_fates_luh>
-<fates_parteh_mode             use_fates=".true.">1</fates_parteh_mode>
-<fates_seeddisp_cadence        use_fates=".true.">0</fates_seeddisp_cadence>
+<use_fates_lupft               use_fates=".true.">.false.</use_fates_lupft>
+<use_fates_potentialveg        use_fates=".true.">.false.</use_fates_potentialveg>
+<use_fates_luh                 use_fates=".true." fates_harvest_mode="luhdata_area"  >.true.</use_fates_luh>
+<use_fates_luh                 use_fates=".true." fates_harvest_mode="luhdata_mass"  >.true.</use_fates_luh>
+<use_fates_luh                 use_fates=".true." use_fates_lupft=".true.">.true.</use_fates_luh>
+<use_fates_luh                 use_fates=".true." use_fates_potentialveg=".true.">.true.</use_fates_luh>
+<use_fates_luh                 use_fates=".true."                                  >.false.</use_fates_luh>
 <use_fates_inventory_init      use_fates=".true.">.false.</use_fates_inventory_init>
-<fates_inventory_ctrl_filename use_fates=".true."> "/dev/null" </fates_inventory_ctrl_filename>
 <use_fates_nocomp              use_fates=".true." use_fates_sp=".true.">.true.</use_fates_nocomp>
+<use_fates_nocomp              use_fates=".true." use_fates_lupft=".true.">.true.</use_fates_nocomp>
 <use_fates_nocomp              use_fates=".true."                      >.false.</use_fates_nocomp>
 <use_fates_fixed_biogeog       use_fates=".true." use_fates_sp=".true.">.true.</use_fates_fixed_biogeog>
+<use_fates_fixed_biogeog       use_fates=".true." use_fates_lupft=".true.">.true.</use_fates_fixed_biogeog>
 <use_fates_fixed_biogeog       use_fates=".true."                      >.false.</use_fates_fixed_biogeog>
-<fates_history_dimlevel        use_fates=".true.">2,2</fates_history_dimlevel>
 <use_vertsoilc                 bgc_mode="fates"  >.true.</use_vertsoilc>
 <use_century_decomp            bgc_mode="fates"  >.true.</use_century_decomp>
 <use_lch4                      bgc_mode="fates"  >.false.</use_lch4>

components/elm/bld/namelist_files/namelist_definition.xml

@@ -308,6 +308,20 @@ Allowed values are:
  5 : use gross domestic production and population datasets to simulate anthropogenic fire supression
 </entry>
 
+<entry id="fates_harvest_mode" type="char*18" category="physics"
+        group="elm_inparm"
+        valid_values="no_harvest,event_code,landuse_timeseries,luhdata_area,luhdata_mass" >
+Set FATES harvesting mode by setting fates_harvest_mode
+Allowed values are:
+ no_harvest   : no fates harvesting of any kind
+ event_code   : fates logging via fates logging event codes only (via fates parameter file)
+ landuse_timeseries: fates harvest driven by HLM landuse timeseries data (dynHarvestMod)
+ luhdata_area : fates harvest driven by LUH2 raw harvest data, area-based (dynFATESLandUseChangeMod)
+ luhdata_mass : fates harvest driven by LUH2 raw harvest data, mass-based (dynFATESLandUseChangeMod)
+Note that the landuse_timeseries option is not the same as the FATES fluh_timeseries data file.
+This option is older than the luhdata options and may be depricated at some point in the future.
+</entry>
+
 <entry id="fates_parteh_mode" type="integer" category="physics"
        group="elm_inparm" valid_values="1,2">
 Switch deciding which nutrient model to use in FATES.
@@ -339,11 +353,6 @@ Toggle to turn on FATES no competition mode (only relevant if FATES is being use
 Toggle to turn on FATES satellite phenology mode (only relevant if FATES is being used).
 </entry>
 
-<entry id="use_fates_logging" type="logical" category="physics"
-        group="elm_inparm" valid_values="" value=".false.">
-Toggle to turn on the logging module (only relevant if FATES is being used).
-</entry>
-
 <entry id="use_fates_planthydro" type="logical" category="physics"
         group="elm_inparm" valid_values="" value=".false.">
 Toggle to turn on plant hydraulics (only relevant if FATES is on).
@@ -382,12 +391,29 @@ Full pathname to the inventory initialization control file.
 
 <!-- This may eventually migrate to the dynamic_subgrid group-->
 <entry id="use_fates_luh" type="logical" category="physics"
-       group="elm_inparm" valid_values="" >
+       group="elm_inparm" valid_values="" value=".false.">
 If TRUE, enable use of land use state and transition data from luh_timeseries file.
-(Only valid for fates land use change runs, where there is a luh_timeseries file.)
+This is enabled by default if fates_harvest_mode is set to use the raw LUH2 harvest data
 (Also, only valid for use_fates = true and is incompatible with transient runs currently.)
 </entry>
 
+<entry id="use_fates_lupft" type="logical" category="physics"
+       group="elm_inparm" valid_values="" value=".false.">
+If TRUE, enable use of fates land use x pft mapping data file.  This mode
+requires the use of the land use x pft association static data map file.  See the
+flandusepftdat definition entry in this file for more information.
+(Only valid for use_fates = true and is incompatible with transient runs currently.)
+</entry>
+
+<entry id="use_fates_potentialveg" type="logical" category="physics"
+       group="elm_inparm" valid_values="" value=".false.">
+If TRUE, ignore the land-use state vector and transitions, and assert that all lands
+are primary, and that there is no harvest.  This mode is only relevant for FATES
+spin-up workflows that are intending to use the spin-up restart output to start a
+FATES land use transient case using the use_fates_lupft namelist option.  The option
+should be set to true for the spin-up case and false for the transient case.
+</entry>
+
 <!-- This could eventually be included in the "dynamic_subgrid" -->
 <entry id="fluh_timeseries" type="char*256" category="datasets"
        input_pathname="abs" group="elm_inparm" valid_values="" >
@@ -408,6 +434,18 @@ output level is not enabled.
 (Only relevant if FATES is on)
 </entry>
 
+<entry id="flandusepftdat" type="char*256" category="datasets"
+       input_pathname="abs" group="elm_inparm" valid_values="" >
+Full pathname of fates landuse x pft data map.
+The file associates land use types with pfts across a static global map.
+This file is necessary for running FATES with use_fates_luh,
+use_fates_nocomp, and use_fates_fixedbiogeo engaged (note that use_fates_lupft
+is provided as a namelist option to engage all necessary options).  The file is output
+by the FATES land use data tool (https://github.com/NGEET/tools-fates-landusedata)
+which processes the raw land use data from the THEMIS tool data sets
+(https://doi.org/10.5065/29s7-7b41)
+</entry>
+
 <entry id="use_hydrstress" type="logical" category="physics"
         group="elm_inparm" valid_values="" value=".false.">
 Toggle to turn on if Kennedy et al plant hydraulics model is used.

components/elm/cime_config/testdefs/testmods_dirs/elm/fates/user_nl_elm

@@ -16,7 +16,7 @@ hist_fincl1       = 'FATES_NCOHORTS', 'FATES_TRIMMING', 'FATES_AREA_PLANTS',
 'FATES_SAPWOODC', 'FATES_LEAFC', 'FATES_FROOTC', 'FATES_REPROC',
 'FATES_STRUCTC', 'FATES_NONSTRUCTC', 'FATES_VEGC_ABOVEGROUND',
 'FATES_CANOPY_VEGC', 'FATES_USTORY_VEGC', 'FATES_PRIMARY_PATCHFUSION_ERR',
-'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_WOODPROD_C_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_landuse/user_nl_elm

@@ -1,2 +1,2 @@
 flanduse_timeseries = '$DIN_LOC_ROOT/lnd/clm2/surfdata_map/landuse.timeseries_4x5_hist_simyr1850-2015_200311.nc'
-do_harvest = .true.
+fates_harvest_mode = 'landuse_timeseries'

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_logging/user_nl_elm

@@ -1 +1 @@
-use_fates_logging= .true.
+fates_harvest_mode = 'event_code'

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2/README

@@ -0,0 +1,2 @@
+Currently the FATES LUH2 category of test mods currently only supports 
+4x5 grid resolutions.

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2/user_nl_elm

@@ -1 +1,5 @@
 use_fates_luh = .true.
+use_fates_nocomp = .true.
+use_fates_fixed_biogeog = .true.
+use_fates_sp = .false.
+use_fates_potentialveg = .false.

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2harvestarea/include_user_mods

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

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2harvestarea/user_nl_elm

@@ -0,0 +1 @@
+fates_harvest_mode = 'luhdata_area'

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2harvestmass/include_user_mods

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

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2harvestmass/user_nl_elm

@@ -0,0 +1 @@
+fates_harvest_mode = 'luhdata_mass'

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_eca/user_nl_elm

@@ -21,7 +21,7 @@ hist_fincl1       = 'FATES_NCOHORTS', 'FATES_TRIMMING', 'FATES_AREA_PLANTS',
 'FATES_SAPWOODC', 'FATES_LEAFC', 'FATES_FROOTC', 'FATES_REPROC',
 'FATES_STRUCTC', 'FATES_NONSTRUCTC', 'FATES_VEGC_ABOVEGROUND',
 'FATES_CANOPY_VEGC', 'FATES_USTORY_VEGC', 'FATES_PRIMARY_PATCHFUSION_ERR',
-'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_WOODPROD_C_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_long/user_nl_elm

@@ -16,7 +16,7 @@ hist_fincl1       = 'FATES_NCOHORTS', 'FATES_TRIMMING', 'FATES_AREA_PLANTS',
 'FATES_SAPWOODC', 'FATES_LEAFC', 'FATES_FROOTC', 'FATES_REPROC',
 'FATES_STRUCTC', 'FATES_NONSTRUCTC', 'FATES_VEGC_ABOVEGROUND',
 'FATES_CANOPY_VEGC', 'FATES_USTORY_VEGC', 'FATES_PRIMARY_PATCHFUSION_ERR',
-'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_WOODPROD_C_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_rd/user_nl_elm

@@ -21,7 +21,7 @@ hist_fincl1       = 'FATES_NCOHORTS', 'FATES_TRIMMING', 'FATES_AREA_PLANTS',
 'FATES_SAPWOODC', 'FATES_LEAFC', 'FATES_FROOTC', 'FATES_REPROC',
 'FATES_STRUCTC', 'FATES_NONSTRUCTC', 'FATES_VEGC_ABOVEGROUND',
 'FATES_CANOPY_VEGC', 'FATES_USTORY_VEGC', 'FATES_PRIMARY_PATCHFUSION_ERR',
-'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_WOODPROD_C_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',