Implement grass allometric equations and update default allometric parameters for grass PFT

[XiulinGao]

Description:

This pull request implements new leaf and AGB allometric equations using basal diameter (cm) and plant height (m) as predictors for grass PFT. In addiiton, a new sapwood option was added in which I set bsap = bagw + bbgw - bdead and bdead is always zero by setting agb_frac to 1. This change will skip the bsap_ltarg_slatop routine for sapwood biomass calculation for grass, and basically make bsap = bagw and there won't be any dead biomass produced for grasses if agb_frac is set to be 1. Lastly, all default allometric parameters, including reproduction allocation, are updated for all three grass PFTs, based on data from Gao et al., 2024. (https://esajournals.onlinelibrary.wiley.com/doi/pdfdirect/10.1002/eap.2976)

Collaborators:

I have talked with @ckoven, @glemieux , and @mpaiao about implementing this new grass allometry and had discussions with them.

Expectation of Answer Changes:

This change will result in different model results for grass PFTs in terms of carbon allocation and the resulting impacts on PFT competitions.

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

• [ x ] 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

Documentation

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

Test Results:

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

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

FATES baseline hash-tag:

Test Output:

[mpaiao]

@XiulinGao Thanks for submitting this pull request! I went through it and I think it looks great! I just have a couple of comments that are probably something for us to think in future pull requests:

1. Many of these modes (especially for crown area and leaf/AG biomass) really could be simplified into 1 generic allometric mode. This may make the code a bit simpler overall.
2. All the derivatives are fine, but in most cases, it could be rewritten in terms of the biomass itself, which saves come floating point operations. I've done this for a few allometric modes. I don't think it's high priority because it's not something computed multiple times a day, but it could save a few milliseconds ;).

[mpaiao]

I suggest removing case (5) and replacing case (3) with case(3,5). This way future changes to care_2pwr don't need to be applied twice.

[XiulinGao]

Thanks Marcos! I have made changes in response to you comments on derivative calculation and the crown area function. But I haven't changed the agb and bleaf allometry to generic function yet. Hope now the code looks less redundant.

[mpaiao]

@XiulinGao Thanks for the follow up. My comment about the generic function was something for a future pull request, not yours. This would likely require significant changes in the parameter files for most users, so it's probably something we want to discuss with the broader FATES community before implementing.

[rgknox]

@XiulinGao : "addiiton, a new sapwood option was added in which I set bsap = bagw + bbgw - bdead and bdead is always zero by setting agb_frac to 1."

My understanding of the code is that bdead is set to zero because allom_smode = 2. Is that correct?

This is a fantastic addition to the code, thanks for submitting this work. Looking forward to getting this in. Originally, I had one request, that we add more description to these new allometry functions in the parameter file, and/or the module that reads in the parameters. However, we don't really have a precedent for that, so we will have to get back to this.

[rgknox]

tagging @JessicaNeedham

[JessicaNeedham]

Agree @XiulinGao that we should think ahead about possible grazing functionality. But as written the crown damage module doesn't change plant height, only crown area and the biomass of aboveground tissues, so I'm not sure how applicable it is to grasses. Maybe we could skip this for now, but think about making the damage code more general so it could be used in the future?

[glemieux]

Per discussion in the fates software meeting today @rgknox will make a PR to this branch to remove this and include a graceful failure.

[XiulinGao]

I see. In that case then I think this is not that helpful for grass grazing. I agree that we can remove this for grasses for now.

[XiulinGao]

@XiulinGao : "addiiton, a new sapwood option was added in which I set bsap = bagw + bbgw - bdead and bdead is always zero by setting agb_frac to 1."

My understanding of the code is that bdead is set to zero because allom_smode = 2. Is that correct?

This is a fantastic addition to the code, thanks for submitting this work. Looking forward to getting this in. Originally, I had one request, that we add more description to these new allometry functions in the parameter file, and/or the module that reads in the parameters. However, we don't really have a precedent for that, so we will have to get back to this.

Yes. The new sapwood function just calculate bsap as the sum of above- and belowground live woody biomass for grasses. But as we set agb_frac to 1, so bsap = agb. I get the logic backwards in documentation here... it's bdead that calculated as bagw + bbgw - bsap not the other way around.....

[rgknox]

ok, thanks for confirming my understanding @XiulinGao . There are some small tweaks I'll submit to your fork as a PR, but we should be able to integrate this PR fairly soon.