Merge remote-tracking branch 'glemfork/lnd/fates-luh2' (PR #5760)

This pull request adds a new module, the structure of which is adopted from the dyn_subgrid code,
to enable e3sm to ingest minimally processed luh2 data to be passed to FATES.
A new namelist variable is introduced use_fates_luh, to engage the module functionality,
which is off by default. The luh2 dataset to be ingested is a minimally processed concatenation
of the luh2 state, transition and management datasets.

These changes also include a minor bug fix discovered in the process of developing the code,
in which if the number of FATES patches being defined by the user in the fates parameter file is greater than the max_patch_per_col elm variable, would result in a BalanceCheck error.

To be coordinated with NGEET/fates#1040

[nonBFB] for FATES

cime_config/tests.py

@@ -416,6 +416,7 @@
             "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",

components/elm/bld/ELMBuildNamelist.pm

@@ -797,7 +797,8 @@ sub setup_cmdl_fates_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_sp",
                      "fates_inventory_ctrl_filename","use_fates_logging", "use_fates_tree_damage",
-                     "use_fates_parteh_mode","use_fates_cohort_age_tracking","use_snicar_ad");
+                     "use_fates_parteh_mode","use_fates_cohort_age_tracking","use_snicar_ad", "use_fates_luh",
+                     "fluh_timeseries");
       foreach my $var ( @list ) {
 	  if ( defined($nl->get_value($var))  ) {
 	      $nl_flags->{$var} = $nl->get_value($var);
@@ -857,6 +858,10 @@ sub setup_cmdl_fates_mode {
        if ( defined($nl->get_value($var)) ) {
 	   fatal_error("$var is being set, but can ONLY be set when -bgc fates option is used.\n");
        }
+       $var = "use_fates_luh";
+       if ( defined($nl->get_value($var)) ) {
+	   fatal_error("$var is being set, but can ONLY be set when -bgc fates option is used.\n");
+       }
        $var = "fates_inventory_ctrl_filename";
        if ( defined($nl->get_value($var)) ) {
 	   fatal_error("$var is being set, but can ONLY be set when -bgc fates option is used.\n");
@@ -3292,8 +3297,43 @@ sub setup_logic_fates {
     add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_fates_nocomp',             'use_fates'=>$nl_flags->{'use_fates'});
     add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_fates_tree_damage',        'use_fates'=>$nl_flags->{'use_fates'});
     add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fates_seeddisp_cadence',       'use_fates'=>$nl_flags->{'use_fates'});
+    add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_fates_luh',                'use_fates'=>$nl_flags->{'use_fates'});
     add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fates_paramfile', 'phys'=>$nl_flags->{'phys'});
-
+    add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fluh_timeseries', 'phys'=>$nl_flags->{'phys'});
+
+    # For FATES SP mode make sure no-competion, and fixed-biogeography are also set
+    # And also check for other settings that can't be trigged on as well
+    my $var = "use_fates_sp";
+    if ( defined($nl->get_value($var))  ) {
+       if ( &value_is_true($nl->get_value($var)) ) {
+          my @list = ( "use_fates_nocomp", "use_fates_fixed_biogeog" );
+          foreach my $var ( @list ) {
+             if ( ! &value_is_true($nl->get_value($var)) ) {
+               fatal_error("$var is required when FATES SP is on (use_fates_sp)" );
+             }
+          }
+          # spit-fire can't be on with FATES SP mode is active
+          if ( $nl->get_value('fates_spitfire_mode') > 0 ) {
+                fatal_error('fates_spitfire_mode can NOT be set to greater than 0 when use_fates_sp is true');
+          }
+       }
+    }
+    # check that fates landuse change mode has the necessary luh2 landuse timeseries data
+    my $var = "use_fates_luh";
+    if ( defined($nl->get_value($var))  ) {
+       if ( &value_is_true($nl->get_value($var)) ) {
+          $var = "fluh_timeseries";
+          add_default($test_files, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, $var,
+                      'phys'=>$nl_flags->{'phys'}, 'hgrid'=>$nl_flags->{'res'},
+                      'sim_year_range'=>$nl_flags->{'sim_year_range'}, nofail=>1 );
+          my $fname = remove_leading_and_trailing_quotes( $nl->get_value($var) );
+          if ( ! defined($nl->get_value($var))  ) {
+             fatal_error("$var is required when use_fates_luh is set" );
+          } elsif ( ! -f "$fname" ) {
+             fatal_error("$fname does NOT point to a valid filename" );
+          }
+       }
+    }
   }
 }
 

components/elm/bld/namelist_files/namelist_defaults.xml

@@ -127,7 +127,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_api25.5.0_12pft_c230710.nc</fates_paramfile>
+<fates_paramfile >lnd/clm2/paramdata/fates_params_api.32.0.0_12pft_c231215.nc</fates_paramfile>
 
 <!-- soil order related parameters (relative to {csmdata}) -->
 <fsoilordercon             >lnd/clm2/paramdata/CNP_parameters_c131108.nc</fsoilordercon>
@@ -565,6 +565,11 @@ 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 -->
+<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>
+
+
 <!-- GLC mask datasets (relative to {csmdata}) -->
 <!-- Currently glc_grid is not being read from anywhere, so these rules are broken.  -->
 <!-- Until that is fixed, the first entry matching hgrid will be used. -->
@@ -2136,6 +2141,7 @@ this mask will have smb calculated over the entire global land surface
 <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_inventory_init      use_fates=".true.">.false.</use_fates_inventory_init>

components/elm/bld/namelist_files/namelist_definition.xml

@@ -381,6 +381,21 @@ Toggle to turn on inventory initialization(only relevant if FATES is being used)
 Full pathname to the inventory initialization control file.
 </entry>
 
+<!-- This may eventually migrate to the dynamic_subgrid group-->
+<entry id="use_fates_luh" type="logical" category="physics"
+       group="elm_inparm" valid_values="" >
+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.)
+(Also, only valid for use_fates = true and is incompatible with transient runs currently.)
+</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="" >
+Full pathname of unified land use harmonization data file. This causes the land-use
+types to vary over time.
+</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,10 +16,8 @@ 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_DISTURBANCE_RATE_P2P', 'FATES_DISTURBANCE_RATE_P2S',
-'FATES_DISTURBANCE_RATE_S2S', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
-'FATES_DISTURBANCE_RATE_POTENTIAL', 'FATES_HARVEST_CARBON_FLUX',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',
 'FATES_AUTORESP_CANOPY', 'FATES_GPP_USTORY', 'FATES_AUTORESP_USTORY',
@@ -28,4 +26,5 @@ hist_fincl1       = 'FATES_NCOHORTS', 'FATES_TRIMMING', 'FATES_AREA_PLANTS',
 'FATES_NEP', 'FATES_HET_RESP', 'FATES_FIRE_CLOSS', 'FATES_FIRE_FLUX_EL',
 'FATES_CBALANCE_ERROR', 'FATES_ERROR_EL', 'FATES_LEAF_ALLOC',
 'FATES_SEED_ALLOC', 'FATES_STEM_ALLOC', 'FATES_FROOT_ALLOC',
-'FATES_CROOT_ALLOC', 'FATES_STORE_ALLOC'
+'FATES_CROOT_ALLOC', 'FATES_STORE_ALLOC',
+'FATES_PATCHAREA_LU', 'FATES_DISTURBANCE_RATE_MATRIX_LULU'

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_landuse/include_user_mods

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

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

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

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2/include_user_mods

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

components/elm/cime_config/testdefs/testmods_dirs/elm/fates_cold_luh2/shell_commands

@@ -0,0 +1 @@
+./xmlchange TEST_MEMLEAK_TOLERANCE=0.2

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

@@ -0,0 +1 @@
+use_fates_luh = .true.

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

@@ -19,10 +19,8 @@ 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_DISTURBANCE_RATE_P2P', 'FATES_DISTURBANCE_RATE_P2S',
-'FATES_DISTURBANCE_RATE_S2S', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
-'FATES_DISTURBANCE_RATE_POTENTIAL', 'FATES_HARVEST_CARBON_FLUX',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',
 'FATES_AUTORESP_CANOPY', 'FATES_GPP_USTORY', 'FATES_AUTORESP_USTORY',

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

@@ -16,10 +16,8 @@ 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_DISTURBANCE_RATE_P2P', 'FATES_DISTURBANCE_RATE_P2S',
-'FATES_DISTURBANCE_RATE_S2S', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
-'FATES_DISTURBANCE_RATE_POTENTIAL', 'FATES_HARVEST_CARBON_FLUX',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',
 'FATES_AUTORESP_CANOPY', 'FATES_GPP_USTORY', 'FATES_AUTORESP_USTORY',

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

@@ -19,10 +19,8 @@ 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_DISTURBANCE_RATE_P2P', 'FATES_DISTURBANCE_RATE_P2S',
-'FATES_DISTURBANCE_RATE_S2S', 'FATES_DISTURBANCE_RATE_FIRE',
+'FATES_HARVEST_CARBON_FLUX', 'FATES_DISTURBANCE_RATE_FIRE',
 'FATES_DISTURBANCE_RATE_LOGGING', 'FATES_DISTURBANCE_RATE_TREEFALL',
-'FATES_DISTURBANCE_RATE_POTENTIAL', 'FATES_HARVEST_CARBON_FLUX',
 'FATES_STOMATAL_COND', 'FATES_LBLAYER_COND', 'FATES_NPP', 'FATES_GPP',
 'FATES_AUTORESP', 'FATES_GROWTH_RESP', 'FATES_MAINT_RESP', 'FATES_GPP_CANOPY',
 'FATES_AUTORESP_CANOPY', 'FATES_GPP_USTORY', 'FATES_AUTORESP_USTORY',

components/elm/src/biogeophys/SurfaceAlbedoMod.F90

@@ -754,13 +754,16 @@ subroutine SurfaceAlbedo(bounds,     &
        ws(p) = esai(p) / max( elai(p)+esai(p), mpe )
     end do
 
-    do ib = 1, numrad
-       do fp = 1,num_vegsol
-          p = filter_vegsol(fp)
-          rho(p,ib) = max( rhol(veg_pp%itype(p),ib)*wl(p) + rhos(veg_pp%itype(p),ib)*ws(p), mpe )
-          tau(p,ib) = max( taul(veg_pp%itype(p),ib)*wl(p) + taus(veg_pp%itype(p),ib)*ws(p), mpe )
+    ! rho and tau are not needed if fates is on 
+    if (.not. use_fates) then
+       do ib = 1, numrad
+          do fp = 1,num_vegsol
+             p = filter_vegsol(fp)
+             rho(p,ib) = max( rhol(veg_pp%itype(p),ib)*wl(p) + rhos(veg_pp%itype(p),ib)*ws(p), mpe )
+             tau(p,ib) = max( taul(veg_pp%itype(p),ib)*wl(p) + taus(veg_pp%itype(p),ib)*ws(p), mpe )
+          end do
        end do
-    end do
+    end if
 
     ! Diagnose number of canopy layers for radiative transfer, in increments of dincmax.
     ! Add to number of layers so long as cumulative leaf+stem area does not exceed total