potential changes to the parameter file (post API 22)

[rgknox]

Let's use this space to generate our wish-list of updates to the parameter file.

---

From review of PR #736, @xuchongang suggested we consider adding the option to use gross assimilation in the conductance calculations, instead of net assimilation. As of #736, it is defined as a hard-coded logical at the top of the photosynthesis module "use_agross = .false.

---

From PR #768, we introduce parameters modify vcmax based on nutrient concentrations a la Walker et al.. This issue also takes over for #682

double fates_eca_vcmax_np1(fates_pft) ;
                fates_eca_vcmax_np1:long_name = "vcmax~np relationship coefficient" ;
                fates_eca_vcmax_np1:unit = "" ;
        double fates_eca_vcmax_np2(fates_pft) ;
                fates_eca_vcmax_np2:long_name = "vcmax~np relationship coefficient" ;
                fates_eca_vcmax_np2:unit = "" ;
        double fates_eca_vcmax_np3(fates_pft) ;
                fates_eca_vcmax_np3:long_name = "vcmax~np relationship coefficient" ;
                fates_eca_vcmax_np3:unit = "" ;
        double fates_eca_vcmax_np4(fates_pft) ;
                fates_eca_vcmax_np4:long_name = "vcmax~np relationship coefficient" ;
                fates_eca_vcmax_np4:unit = "" ;

This PR is still a work in progress, and we are likely to add in a control parameter that switches this hypothesis on/off as well. Likewise, we may also add in other parameters as well via this PR.

---

Rename: "fates_fire_crown_depth_frac" to "fates_crown_depth_frac" as per #780

---

Add in a switch for the plant hydraulics solver: ie 1D taylor solve, 2D newton (deprecated) or 2D picard. Also, see #766

[rgknox]

Copied over from #841 , to quote @rosiealice :

"I am finding, following @walkeranthonyp's observations from MAAT, that the radiation code is sensitive to the number of diffuse radiation bins, which is currently 9. It would be useful, mostly to facilitate sensitivity analysis, for this to be modifiable via the parameter file. "

fates/biogeophys/EDSurfaceAlbedoMod.F90

Line 418 in 7edf030

do j = 1,9

[JessicaNeedham]

The crown damage module PR#788 introduces five new parameters.

    double fates_damage_frac(fates_pft) ;
            fates_damage_frac:units = "fraction";         
            fates_damage_frac:long_name = "fraction of cohort damaged in each damage event (event frequency specified in the is_it_damage_time subroutine)";
    double fates_damage_mort_p1(fates_pft) ;
           fates_damage_mort_p1:units = "fraction crown loss - a value of 0.8 means 50% mortality with 80% loss of crown";
           fates_damage_mort_p1:long_name = "inflection point of damage mortality function - to turn off damage mortality set this to a large number" ;
    double fates_damage_mort_p2(fates_pft) ;
            fates_damage_mort_p2:units = "unitless";
            fates_damage_mort_p2:long_name = "rate of mortality increase with damage";
    double fates_damage_recovery_scalar(fates_pft) ;
            fates_damage_recovery_scalar:units = "unitless";
            fates_damage_recovery_scalar:long_name = "fraction of cohort that recovers from damage"; 

fates_damage_frac = 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01,
0.01, 0.01, 0.01, 0.01 ;

fates_damage_mort_p1 = 9.0,9.0,9.0,9.0,9.0,9.0,9.0,9.0,9.0,9.0,9.0,9.0 ;

fates_damage_mort_p2 = 5.5, 5.5, 5.5, 5.5, 5.5, 5.5, 5.5, 5.5, 5.5, 5.5,
5.5, 5.5 ;

fates_damage_recovery_scalar = 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
0.0, 0.0, 0.0, 0.0 ;

fates_history_damage_bins = 6 ;

double fates_history_damage_bin_edges(fates_history_damage_bins) ;
fates_history_damage_bin_edges:units = "% crown loss" ;
fates_history_damage_bin_edges:long_name = "Lower edges for damage class bins used in cohort history output" ;

fates_history_damage_bin_edges = 0, 20, 40, 60, 80 100 ;

@rgknox , I've added an additional parameter (sorry!) to the damage module that allows the timing of damage events to be set by the user, as in the logging module.

double fates_damage_event_code ;
fates_damage_event_code:units = "unitless" ;
fates_damage_event_code:long_name = "Integer code that options how damage events are structured" ;

fates_damage_event_code = 1 ;

[rgknox]

Here are potential new parameters for parteh_mode = 2 (ie the CNP model):

	double fates_store_ovrflw_frac(fates_pft) ;
		fates_store_ovrflw_frac:units = "fraction" ;
		fates_store_ovrflw_frac:long_name = "size of overflow storage (CNP only) as a fraction of storage target" ;
	double fates_fnrt_adapt_tscale(fates_pft) ;
		fates_fnrt_adapt_tscale:units = "days" ;
		fates_fnrt_adapt_tscale:long_name = "Number of days that is the shortest possible doubling period for fine-root adaptation (CNP only)" ;

deafaults:

fates_store_ovrflw_frac = 1.0 ;
fates_fnrt_adapt_tscale = 30.0 ;

[mpaiao]

List of potential new parameters for the revised drought-deciduous phenology (pull request #801):

1. Parameter that sets the drought-deciduous phenology hypothesis. Currently only 2 options available, but new options may be eventually added:

	double fates_phen_drought_model ;
 		fates_phen_drought_model:units = "none" ;
 		fates_phen_drought_model:long_name = "which method to use for drought phenology: 0 - FATES default; 1 - Semi-deciduous (ED2-like)" ;

2. This is not a new parameter, but the drought-deciduous moisture threshold could be provided both in volumetric soil moisture (positive values, m³ m⁻³, as it is currently done) or in soil matric potential (negative values, mm). In case of semi-deciduous PFTs (fates_phen_drought_model=1), this is threshold below which plants are completely leafless:

	double fates_phen_drought_threshold ;
 		fates_phen_drought_threshold:units = "m3/m3 or mm" ;
 		fates_phen_drought_threshold:long_name = "threshold for drought phenology (or lower threshold when fates_phen_drought_model = 1); the quantity depends on the sign: if positive, the threshold is volumetric soil moisture (m3/m3). If negative, the threshold is soil matric potentical (mm)." ;

3. Similar to fates_phen_drought_threshold , but this threshold defines the upper threshold for semi-deciduous PFTs (fates_phen_drought_model=1) to start abscising leaves:

	double fates_phen_moist_threshold ;
 		fates_phen_moist_threshold:units = "m3/m3 or mm" ;
 		fates_phen_moist_threshold:long_name = "upper threshold for drought phenology (only for fates_phen_drought_model=1); the quantity depends on the sign: if positive, the threshold is volumetric soil moisture (m3/m3). If negative, the threshold is soil matric potentical (mm)." ;

4. This parameter is similar to existing fates_phen_stem_drop_fraction parameter, but allow to actively abscise fine roots for both drought-decidous and winter-deciduous phenologies. Setting fates_phen_fnrt_drop_fraction = 1 would cause plants to lose fine roots at the same rate as leaves, whereas fates_phen_fnrt_drop_fraction=0 means that fine roots are not actively abscised (which is the default FATES behaviour). Intermediate values are also accepted.

	double fates_phen_fnrt_drop_fraction(fates_pft) ;
 		fates_phen_fnrt_drop_fraction:units = "fraction" ;
 		fates_phen_fnrt_drop_fraction:long_name = "fraction of fine roots to drop during drought/cold" ;

Default values:

 fates_phen_drought_model = 0 ;

 fates_phen_drought_threshold = 0.15;

 fates_phen_moist_threshold = 0.18;

 fates_phen_fnrt_drop_fraction = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ;

There may be a couple of additional parameters in case I implement a photoperiod-based flushing approach for drought deciduous.

[ckoven]

Another thing is we should remove the "NOT USED" comments in the description names for the two variables fates_vai_top_bin_width and fates_vai_width_increase_factor now that they are being used.

https://github.com/NGEET/fates/blob/master/parameter_files/fates_params_default.cdl#L752-L757

[adrifoster]

As discussed at the meeting I can help with updating the metadata so that the description of the units is consistent. Note, I won't be changing the actual units of the parameters, just the metadata description. (e.g. m^2/m^2 ----> m2 m-2).

[jenniferholm]

In addition to vcmax_np1, vcmax_np2, vcmax_np3, vcmax_np4 listed above.....and also related to PR #768, the reviewers have noted that it would be cleaner in the code, and better for potentially future tuning, if a few more parameters would included in the parameter file.
These are: jmax_np1, jmax_np2, jmax_np3 (not PFT specific), and flnr (PFT specific)

Below are new parameters to include that are related to the calculation of vcmax and jmax. (Let's also remove the "eca" from the parameter, as these are not necessarily only related to the ECA approach.) How about similar to fates_leaf_vcmax25top, we include the "leaf" indicator?

double fates_leaf_vcmax_np1(fates_pft) ;
	fates_leaf_vcmax_np1:long_name = "vcmax~np relationship coefficient" ;
	fates_leaf_vcmax_np1:unit = "unitless" ;
double fates_leaf_vcmax_np2(fates_pft) ;
	fates_leaf_vcmax_np2:long_name = "vcmax~np relationship coefficient" ;
	fates_leaf_vcmax_np2:unit = "unitless" ;
double fates_leaf_vcmax_np3(fates_pft) ;
	fates_leaf_vcmax_np3:long_name = "vcmax~np relationship coefficient" ;
	fates_leaf_vcmax_np3:unit = "unitless" ;
double fates_leaf_vcmax_np4(fates_pft) ;
	fates_leaf_vcmax_np4:long_name = "vcmax~np relationship coefficient" ;
	fates_leaf_vcmax_np4:unit = "unitless" ;

double fates_leaf_jmax_np1 ;
	fates_leaf_jmax_np1:long_name = "jmax~np relationship coefficient" ;
	fates_leaf_jmax_np1:unit = "unitless" ;
double fates_leaf_jmax_np2 ;
	fates_leaf_jmax_np2:long_name = "jmax~np relationship coefficient" ;
	fates_leaf_jmax_np2:unit = "unitless" ;
double fates_leaf_jmax_np3 ;
	fates_leaf_jmax_np3:long_name = "jmax~np relationship coefficient" ;
	fates_leaf_jmax_np3:unit = "unitless" ;

double fates_leaf_flnr(fates_pft) ;
	fates_leaf_flnr:units = "gN Rubisco / gN leaf" ;
	fates_leaf_flnr:long_name = "fraction of leaf N in the Rubisco enzyme" ;

fates_leaf_vcmax_np1 = 4.02421875, 3.2345, 4.8, 3.878125, 4.8, 4.7175,
3.9421875, 3.7, 3.7859375, 3.86757, 3.7859375, 4.43859375 ;

fates_leaf_vcmax_np2 = 0.7640625, 0.7828125, 0.7453125, 0.9140625, 0.8015625,
0.91875, 1.096875, 0.6, 1.134375, 0.742968, 1.134375, 0.6703125 ;

fates_leaf_vcmax_np3 = 0.07125, 0.08375, 0.08625, 0.19125, 0.12125, 0.185,
0.1225, 0.04, 0.1725, 0.126875, 0.1725, 0.14625 ;

fates_leaf_vcmax_np4 = 0.282, 0.282, 0.282, 0.282, 0.282, 0.282, 0.282,
0.282, 0.282, 0.282, 0.282, 0.282 ;

     fates_leaf_jmax_np1 = 1.246_r8     
     fates_leaf_jmax_np2 = 0.886_r8        
     fates_leaf_jmax_np3 = 0.089_r8        

The updated values for fates_leaf_flnr, still need to be gathered from the analysis by [Luo et al 2021].(https://www.nature.com/articles/s41467-021-25163-9). I can hopefully get these soon.

[rgknox]

started a branch to consolidate these, will eventually also include the maximum patch settings for both nat and anthro, as well as re-ordering code to pass maxpatch to CLM/ELM.

https://github.com/rgknox/fates/tree/params-maxpatch-logfinal

[rgknox]

From external discussion with @sshu88

One new parameter is added following the discussion in https://github.com/NGEET/fates/pull/825.

|    double fates_pprodharv10_forest_mean ;
|        fates_pprodharv10_forest_mean:units = "fraction" ;
|        fates_pprodharv10_forest_mean:long_name = "mean harvest mortality proportion of deadstem to 10-yr product (pprodharv10) of all woody PFT types." ;
| fates_pprodharv10_forest_mean = 0.8125 ;

Best,
Shijie