Some fire-related fixes and clarifications

[ckoven]

there were a bunch of issues with the fire code, which this PR fixes.

Description:

There were a bunch of fire-related issues, which include:

1. fire area was wrongly using the patch%frac_burnt to modify the fire intensity, which because intensity is used via a threshold to determine whether or not a fire actually occurs, was leading to too-low burned area
2. the decay flux from the seed pool was being routed to the FATES leaf litter pool, where it could act as a fuel source. this meant we were both double-counting the seed C stocks in the scheme and also meant that under the special cases where a plant allocates a large fraction of its NPP to seeds (this can particularly happen with grasses right now) it would build up huge amounts of fuel and thus fire area. I've changed this to reroute the seed decay fluxes straight to the HLM decomposition cascade rather than the intermediate step of the FATES leaf litter pool. some day we may want to directly couple the seed pool to the fire behavior and effects but for now this should make the model behavior more as expected.
3. re-added the fire ellipse length-to-breadth calculation in the fire code. This had been hard-coded to one (thus all fires are circular rather than elliptical), which was making the fire areas too big. also there were typos in the equations for the length-to-breadth code. One of the typos goes back to the original 1992 Canadian fire behavior model (which noted in a 2009 errata that there had been a typo) and thus possibly exists in all extant versions of SPITFIRE (not just FATES-SPITFIRE). In addition to the typos, we reverted the length-to-breadth logic to be categorically distinct—rather than a continuous transition—between grasslands and forests. we can revisit this later, as well as what value of tree cover should switch between them, but for changed it to the separate equation approach.
4. added some more comment tracing the provenance of various equations and more info on the units where helpful.
5. added a couple more history variables that are helpful (e.g. PFT-level NPP and GPP) for investigating things. also fixed and simplified some unit descriptions.
6. the MEF (moisture extinction factor) equation didn't have a clear provenance; once that was sorted out we realized there was a typo there as well (log10->log).
7. nan (rather than zero) the fire-relevant patch variables when initializing them.

Fixes #713
Fixes #473
Fixes #575

Collaborators:

Lots of discussion and code from @jkshuman and also discussion with @lmkueppers @pollybuotte @rosiealice @rgknox @glemieux @JunyanDing

Expectation of Answer Changes:

highly answer changing if fire on. also answer-changing litter and belowground BGC dynamics for case where fire is off.

Checklist:

• My change requires a change to the documentation.
• I have updated the in-code documentation .AND. (the technical note .OR. the wiki) accordingly.
• I have read the CONTRIBUTING document.
• FATES PASS/FAIL regression tests were run
• If answers were expected to change, evaluation was performed and provided

still need to update the tech note to be consistent with the changes here. will do so before merging this PR.

Test Results:

not yet tested

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

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

FATES baseline hash-tag:

Test Output:

[rgknox]

some tests on cheyenne are failing at line 2213 in main/FatesHistoryInterfaceMod.F90

Here is the log:

812:MPT: #1  0x00002ab78894e866 in mpi_sgi_system (
812:MPT: #2  MPI_SGI_stacktraceback (
812:MPT:     header=header@entry=0x7ffd4aa9d600 "MPT ERROR: Rank 812(g:812) received signal SIGFPE(8).\n\tProcess ID: 43396, Host: r12i4n34, Program: /glade/scratch/rgknox/ERP_D_Ld3.f19_g16.I2000Clm50FatesCruGs.cheyenne_intel.clm-FatesColdDef.C.202012"...) at sig.c:340
812:MPT: #3  0x00002ab78894ea62 in first_arriver_handler (signo=signo@entry=8, 
812:MPT:     stack_trace_sem=stack_trace_sem@entry=0x2ab792fc0080) at sig.c:489
812:MPT: #4  0x00002ab78894edfb in slave_sig_handler (signo=8, siginfo=<optimized out>, 
812:MPT:     extra=<optimized out>) at sig.c:565
812:MPT: #5  <signal handler called>
812:MPT: #6  0x00000000016dd595 in fateshistoryinterfacemod::update_history_dyn (
812:MPT:     this=0x5ac9970 <clm_instmod_mp_clm_fates_+144>, nc=1, nsites=4, sites=...)
812:MPT:     at /glade/u/home/rgknox/ctsm/src/fates/main/FatesHistoryInterfaceMod.F90:2213
812:MPT: #7  0x00000000009ba8a0 in clmfatesinterfacemod::L_clmfatesinterfacemod_mp_init_coldstart__1453__par_loop0_2_121 ()
812:MPT:     at /glade/u/home/rgknox/ctsm/src/utils/clmfates_interfaceMod.F90:1535
812:MPT: #8  0x00002ab787131d43 in __kmp_invoke_microtask ()
812:MPT:    from /glade/u/apps/opt/intel/2019u5/compilers_and_libraries/linux/lib/intel64/libiomp5.so
812:MPT: #9  0x00002ab7870c1d65 in __kmp_fork_call (loc=0x2ac7c41b7168, gtid=95221696, 
812:MPT:     call_context=(unknown: 3286322944), argc=1252673288, 
812:MPT:     microtask=0x4ab7d08 <__STRLITPACK_22>, invoker=0x38525f49, 
812:MPT:     ap=0x7ffd4aabe160) at ../../src/kmp_runtime.cpp:2085
812:MPT: #10 0x00002ab787081c60 in __kmpc_fork_call (loc=0x2ac7c41b7168, argc=95221696, 
812:MPT:     microtask=0x2ac7c3e14f00) at ../../src/kmp_csupport.cpp:360
812:MPT: #11 0x00000000009a6413 in clmfatesinterfacemod::init_coldstart (
812:MPT:     this=0x5ac98e0 <clm_instmod_mp_clm_fates_>, waterstatebulk_inst=..., 
1155:MPT:     waterdiagnosticbulk_inst=..., canopystate_inst=..., soilstate_inst=...)
1155:MPT:     at /glade/u/home/rgknox/ctsm/src/utils/clmfates_interfaceMod.F90:1453
1155:MPT: #12 0x000000000090e112 in clm_initializemod::initialize2 ()
1155:MPT:     at /glade/u/home/rgknox/ctsm/src/main/clm_initializeMod.F90:753
1155:MPT: #13 0x0000000000888eb9 in lnd_comp_mct::lnd_init_mct (eclock=..., cdata_l=..., 
1155:MPT:     x2l_l=..., l2x_l=..., nlfilename=..., .tmp.NLFILENAME.len_V$757a=6)
1155:MPT:     at /glade/u/home/rgknox/ctsm/src/cpl/mct/lnd_comp_mct.F90:238

This seems to me like an uninitialized variable issue, probably related to patch%frac_burnt. Notice that with a cold-start, (see clmfates_interfaceMod.F90 line 1535) we do not call dynamics at time zero on that first day, but we do initialize the history variables, and thus we are trying to use variables like %frac_burnt (and some other fire variables as well) but they do not have a value yet.

Solutions:

1. short term: allow zero'ing of fire variables but only during the cold-start initialization
2. long-term: I feel this is yet another reason we should de-centralize the history variable filling process. In this situation, the history fields would be initialized with the special value flag (like ignore/invalid), and then we would update the history variable immediately upon where the variable of interest is updated in the fire code

[rgknox]

tests, not b4b changes, run tests pass:
/glade/scratch/rgknox/clmed-tests/fates-sci.1.43.3_api.14.2.0-ctsm1.0.dev113-Ca7e020f2-Fc0f3957e.fates.cheyenne

[jkshuman]

I can confirm that the last commit to re-add patch%frac_burnt=0 for below threshold intensity fires does repair the previous simulation fail. Tests across South America are successful out to 28 years, where previous runs failed in year 0 with a mass balance error. Thanks for @ckoven and @rgknox for discussions on this.