Updates to land use clearing logic

[JessicaNeedham]

Description:

This PR adds some flexibility to the land use clearing rules. Currently, whether or not to kill vegetation when transitioning from one land use class to another is determined by a clearing matrix, with the logic selected by a hard coded value. All vegetation is killed if clearing is true. This PR makes the clearing logic a namelist option, and adds a new parameter that determines what fraction of each PFT should be killed if clearing is true. The namelist option is to enable sensitivity analyses that don't rely on code changes.

To be fully flexible in terms of when and how much of each PFT is killed in land use transitions, we would need a PFT x land use class parameter, but for now I've just made it PFT level, and assumed that clearing mortality would be the same for pasture and rangeland, and all vegetation would still be killed regardless of PFT if we are transitioning to crops. The values for the new parameter that determine what fraction of each PFT is killed are somewhat arbitrary and should probably be updated based on observations.

CTSM side changes for the namelist option are here: https://github.com/JessicaNeedham/ctsm/tree/jfn-fates-nl-lulogic

Collaborators:

@ckoven @rosiealice

Expectation of Answer Changes:

The namelist option should not be answer changing with land use off. If land use is on, it would need to be set to 4, and the new parameter would need to be 1 for all PFTs for the same behaviour as the current default. Other values will be answer changing.

Checklist

If this is your first time contributing, please read the CONTRIBUTING document.

All checklist items must be checked to enable merging this pull request:

Contributor

• The in-code documentation has been updated with descriptive comments
• The documentation has been assessed to determine if updates are necessary

Integrator

• FATES PASS/FAIL regression tests were run
• Evaluation of test results for answer changes was performed and results provided
• FATES-CLM6 Code Freeze: satellite phenology regression tests are b4b

If satellite phenology regressions are not b4b, please hold merge and notify the FATES development team.

Documentation

• Technical Note update:
• User's Guide update:

Test Results:

These branches have not been tested - I cherry picked commits from my NorESM-FATES branches.
With NorESM branches code compiles and runs for 2 years with land use on.
I will try some longer runs and compare to current settings to assess impacts.

[rosiealice]

Could this use the 'cropland' index from

fates/main/FatesConstantsMod.F90

Line 56 in 906d03b

integer, parameter, public :: cropland = 5

?

[JessicaNeedham]

Yes, good idea. I've updated.

[JessicaNeedham]

Updates: following Ma et al. (2020) (https://doi.org/10.5194/gmd-13-3203-2020) changed logic to kill all vegetation when converting to crops or pastureland. The new clearing mortality parameter only affects conversion to rangeland. Default is for grasses and shrubs to not be killed.