Crown fire Scott & Reinhardt 2001

[XiulinGao]

Description:

This PR is based off Sam Levis and Jackie Shuman's previous work on implementing crown fire into FATES, and @adrifoster 's effort of refactoring SPITFIRE.
I went through the previous code and all the applied equations in Scott & Reinhardt 2001, corrected few errors in equations coded and fixed some coding and logical bugs to make the code now can compile and run when crown fire is turned on. I also did some refactor there so it's compatible with the current SPITFIRE after Adrianna's refactor work.
What the PR does:

• Calculate patch level canopy fuel load [kg biomass in total], canopy fuel bulk density [kg biomass / m3], and finds the canopy base height at which the biomass density is above the critical density for vertical fire spreading through canopy

• Calculate the minimum fire intensity for initiating a crown fire using EQ 11 in Scott & Reinhardt 2001. If surface fire FI is above this threhsold, there is a crown fire.

• Check whether it's a passive or active crown fire by comparing the theoretical crown fire ROS (ROS_active, EQ. 10 in Scott & Reinhardt 2001) to the critical ROS required for sustaining a fully active crown fire (ROS_active_min, EQ. 14).

• Update ROS and fire intensity once there is a crown fire using EQ. 21 & 22 in Scott & Reinhardt 2001.

What I added:

1. I added a statistical model for predicting live canopy water content based on plant phenology (LAI) and soil water condition (soil matric potential) using a similar model structure as EQ. 4 in McNorton and Giuseppe 2024 'A global fuel characteristic model and dataset for wildfire prediction' but changed the original mass-based soil water content to SMP. Currently the parameters are just for testing, nothing is constrained by data. I haven't included these parameters as PFT-specific parameters (which I think it makes sense to do). Let me know if I should do that (only 4 parameters ).

2. when calculate crown damage, I separate the calculation of crown fraction burned of crown fire from surface fire. When there is only a surface fire, crown fraction burned at cohort still uses the SPITFIRE equation; but when there is a passive crown fire, cohort crown fraction burned now uses EQ. 28 in Scott & Reinhardt 2001 and set to 1 for an active crown fire.

To-Do in the future:

1. We need to add another live canopy water content model that is based on FATES-HYDRO.

2. Calculation of the theoretical crown fire rate of spread (ROS_active) and the Crowning Index open wind speed uses fuel characteristics from the fuel model 10, one of the 13 Anderson's fire behavior fuel models. I think these fuel model constants should be included as parameter instead of being hard-coded, since some users might want to switch to different fuel models for calculating the crown fire ROS when their systems are totally different than a timber forest. But adding 10+ new parameters does not make sense to me. This can be something to discuss in the future.

Collaborators:

@slevis-lmwg @jkshuman @adrifoster @samsrabin @ckoven @mpaiao @lmkueppers
#857
#1108

Expectation of Answer Changes:

Expect answer change when crown fire is turned on.

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
• 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:

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

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

FATES baseline hash-tag:

Test Output:

[XiulinGao]

@samsrabin Thanks Sam! This is now ready for review.

[samsrabin]

Is it okay if I wait on reviewing this until the conflicts are resolved?

[XiulinGao]

@samsrabin yep, that totally makes sense! probably after the RX fire branch is merged into main.