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.

There are still a lot needs to be discussed before this PR is ready to be merged into main.

1. The canopy water content that is currently in-use for calculating the minimum energy threshold to initiate a crown fire is hard-coded in the model now, which is supposed to be replaced by transient canopy or leaf water content.

2. Currently calculation of canopy fuel load includes both leaf and 1 hour woody biomass. However, some lit. suggests canopy fuel should only include foliage biomass (see Gruz et al. 2003, ' Assessing canopy fuel stratum characteristics in crown fire prone fuel types of western North America'). Although, I think including 1-hour woody fuel is reasonable as usually crown fire does burn small twig and branches.

3. 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. Although, I'm not sure what exact values they are used in Scott & Reinhardt 2001 in order to get to EQ. 20 for calculating crowning index. Also, 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.

4. The crown fraction burned in SPITFIRE is to account for crown fire behavior and the resulting impacts. However, now with the actual crown fire model being implemented, do we want to re-think the way how we will calculate crown fraction burned? for example, we might want to switch to use EQ. 28 in Scott & Reinhardt 2001 and only calculate crown fraction burned when there is a crown fire (as why we want to account for that when there is no crown fire??). This will also make sure the final crown fraction burned, thus the biomass that contributed to fire intensity, will match the updated fire intensity by accounting for crown fuel consumption using EQ. 22 in Scott & Reinhardt 2001.

Collaborators:

@slevis-lmwg @jkshuman @adrifoster @samsrabin @ckoven
#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

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:

[samsrabin]

Looks cool! Please ping me again when it's ready for review.