parameter file updates

[rgknox]

Description:

This set of changes brings in a number of new parameter constants to the fates parameter file, along with their model data structures and use. This set should include a number of new parameters from different initiatives including, phenology, crown damage, nutrient cycling, hydraulics, etc. This set of changes will also add the maximum number of patches (and potentially the number of cohorts per patch) to the parameter file workflow, which will be used to drive the CLM/ELM side patch allocations when fates is on, and will involve some re-organization of the fates initialization call sequence.

Since this is already and API changing PR, this may also include a call to finalize and declare the tallies of un-reported message counts in the log (for those messages that saturated).

Fixes: #799
Fixes: #204
Fixes: #214
Fixes: #334

Synchronized with: ESCOMP/CTSM#1766

Collaborators:

see issue #799

Expectation of Answer Changes:

At this point, no answer changes are expected.

Checklist:

• My change requires a change to the documentation.
• I have updated the in-code documentation .AND. (the technical note .OR. the wiki) accordingly.
• I have read the CONTRIBUTING document.
• FATES PASS/FAIL regression tests were run
• If answers were expected to change, evaluation was performed and provided

Test Results:

CTSM (or) E3SM (specify which) test hash-tag:

CTSM (or) E3SM (specify which) baseline hash-tag:

FATES baseline hash-tag:

Test Output:

[rgknox]

Update on this PR:

I've created a script that will allow a user to automatically update an existing parameter file (cdl) to a newer format, based on an xml file. This script and xml couplet will define parameter name changes, parameter deletions, parameter attribute and value changes, dimension name changes and dimension deletions.

xml as of 7912585: https://github.com/NGEET/fates/blob/7912585bb006b514a0ee97cf8de7e829a63ce17f/parameter_files/apichange_23to24.xml

script as of 7912585: https://github.com/NGEET/fates/blob/7912585bb006b514a0ee97cf8de7e829a63ce17f/tools/UpdateParamAPI.py

This script allows us to apply significant updates to the parameter file, while also ensuring that users who have personal parameter files, don't get left behind. They can also use this script/xml couplet to update their files.

After consulting with the FATES software team, we agreed it would be useful to re-organize the parmeter names. In particular, add more group names to parameter name prefixes. All changes to parmeter name changes are summarized in this table, and are subject to updates and feedback from the broader FATES team

https://docs.google.com/spreadsheets/d/1ZdhM8Ggv6wlqFNKdTvtWRMGHdb_7ae1zuIVfl1RKQHw/edit?usp=sharing

Summary of changes:
Added specific changes associate with #799
Removed the "prt" group (which was opaque) and converged those parameters into an alloc, turnover and stoich group
Converged parameters into the following groups, when possible:

• "mort" for mortality.
• "phen" for phenology
• "alloc" for allocation
• "turnover" for turnover
• "stoich" for stoichiometry
• "cnp" for all things using dynamic Nitrogen or Phosphorus
• "lu" for all things, including logging, that are landuse related
• "leaf" for all things, including photosynthesis, that are leaf related
• "nonhydro" for parameters that only used when hydro is off
• "hydro" (previously "hydr") for all parameters that are only used when hydro is on
• "allom" (which existed but was slightly expanded) for allometry
• "fire" already existed and was not changed much
• "damage" for parameters only active when the damage module is on
• "frag" for litter fragmentation
• "recruit" for all things related to recruitment, including on-tree allocation to seeds and seed germination
• "rad" for all things radiation and optical related

[glemieux]

Per fates software meeting discussion (May 16):

• lu to landuse
• Better name than nonhydro?

[glemieux]

A few questions and clarifications.

[glemieux]

I couldn't find this in the issue discussion. What predicated the removal of these parameters?

[rgknox]

We don't have a defensible way of having plasticity in nutrient concentrations yet, so this parameter is not useful. @jenniferholm has been investigating such a feature though, so this may change down the line. In the future depending on those findings we could introduce the necessary parameters. My sense is that when we do, the plasticity will not be introduced through this parameter, and may target individual organs that actually experience plasticity, like leaves.

[jenniferholm]

😁 👍