Add NVP (Non-Vascular Plant) PFT in CTSM–FATES

[huitang-earth]

Description:

This PR introduces a physically explicit representation of non-vascular plants (NVP; e.g., moss and lichen) in CTSM–FATES and its biophysical effect by assigning them to a dedicated vertical layer in CTSM (ESCOMP/CTSM#3927), and a NVP PFT in FATES. The core architectural decision is to use layer 0 of the soil-snow layer structure to accommodate NVP and its growth (i.e., changes in height) when it is present. This layer integrates consistently into CLM’s radiation (under snow), thermal, and hydrology schemes, while coupling to FATES for canopy radiation (without snow) and photosynthesis (see the following call graph).
Note: The implementation is not fully ready yet and is still open for discussion.

Key implementation details in FATES:

• Introduces NVP allometric subroutine linking cohort-level NVP LAI changes with site(column)-level NVP layer thickness (i.e., height).
• Implements independent NVP radiation, create new absorptance terms (fabd/fabi_nvp_pa) passed to CLM.
• Adds NVP-specific photosynthesis (disabling stomatal conductance and root-dependent processes) driven by NVP conditions (e.g., t_nvp_col, fwet_nvp_col, and absorbed PAR by nvp).

Collaborators:

@rosiealice

Expectation of Answer Changes:

This PR is expected to produce answer changes when NVP is active and NVP layer is present:

• Surface energy balance modified due to new top boundary condition at layer 0 (CLM, FATES)
• Soil temperature profiles altered due to NVP thermal properties (CLM)
• Hydrology affected by additional water storage and evaporation pathway (CLM)
• Carbon fluxes (GPP/NPP) changed due to NVP photosynthesis and modified PAR environment (FATES)

No answer changes are expected when NVP is disabled.

Description of generative AI usage (as necessary)

Claude code has been used for porting changes into the new FATES version and designing the overall structure. The call graph is also generated by Claude code.

Checklist

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
• Describe use of generative AI (if 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

Documentation

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

Test Results:

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

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

FATES baseline hash-tag: (TBD)

Test Output: (To be provided)

[samsrabin]

@huitang-earth This is great to see! I'm a software engineer on CTSM and was about to get started in earnest on similar work with @adrifoster, so I might be able to work with you on getting this in. I'll email about scheduling a call. In the meantime, do you have any results you could add here?

[rgknox]

Congratulations on this submission @huitang-earth ! Very exciting stuff! Added myself as a reviewer

[samsrabin]

@huitang-earth I've had a read through this and it looks great. I have a lot of questions and comments, but they can mostly wait until after our call Tuesday. One burning one, though—did you add a moss PFT? I don't see one in the updated parameter file, but I can't figure out how this would work without one. If you have a new parameter file with a moss PFT, could you add it to this PR?

[huitang-earth]

@samsrabin Thanks for your comments. Just a quick answer to your question. I indeed have added moss and lichen as a pft in the parameter file in the old version, with which I have made plenty simulations. But now I am wondering if it is a better idea to have a separate parameter file for NVP? The reason behind this thought is that the traits used for describing NVP are quite different from that for vascular PFT. If we use the same parameter file, there will be a lot of redundant parameters not needed by NVP, while some new parameters (not needed by vascular PFT) will be added in the same file. I am worried that this will make the parameter file quite messy in the future.

I am happy to learn more about your opinions before making such an implementation in the PR.

[samsrabin]

You're right that it will be messy, but I think for now it'd be best to include NVPs in the one existing parameter file. This is analogous to how we have woody and non-woody vascular plants in there already, even though there are parameters used by only one or the other. Well, I guess it's analogous as long as there's ANY overlap—is there?

Either way, I think this is the way to go for now. Our priority should be to get a complete working version so that scientific testing can be carried out with this branch; we can decide later if we want to add the extra infrastructure that would be required for a separate parameter file.

[rgknox]

Speaking specifically to the engineering and coding aspects of this PR, I see two paths that we can follow here. One path could potentially add a lot of technical debt. In the other path we use this set of changes to get even more organized about how to handle different types of plants in different parts of the code. I would also encourage us as we are refining this code going forward, to think about how it will work alongside other axis of differentiation of plants, that we have and maybe don't have, such as woody/non-wood, free-standing/lianas, etc.

[huitang-earth]

You're right that it will be messy, but I think for now it'd be best to include NVPs in the one existing parameter file. This is analogous to how we have woody and non-woody vascular plants in there already, even though there are parameters used by only one or the other. Well, I guess it's analogous as long as there's ANY overlap—is there?

Either way, I think this is the way to go for now. Our priority should be to get a complete working version so that scientific testing can be carried out with this branch; we can decide later if we want to add the extra infrastructure that would be required for a separate parameter file.

I have added NVP (non_vascular_phototroph) into the default parameter json file with some changes in the parameter values when it is relevant. The absent of root for NVP is also added now.