leaf biophysics refactor and functional unit tests

[rgknox]

Description:

Leaf biophysics (photosynthesis, stomatal conductance and leaf respiration) has been refactored. Major objectives in this refactor were to 1) extract relevant routines that occur at the leaf-scale and place them in their own module that does not use the fates scaling data structures (cohort, patch and site agnostic) and 2) to have functional unit tests that exercise each of these functions.

These methods do not yet use features in our other brand of unit tests (but could!), particularly the use of cmake and parameter reading.

Design Notes

Notes on Bisection and finding bounding (starter) values

Notes on re-deriving the Medlyn solve with a boundary layer

Colab Notebook that runs the unit test: link

Fixes: #1222
Addresses: #719 (which is now a discussion)

Collaborators:

@adrifoster @ckoven

Expectation of Answer Changes:

There may be subtle differences in our standard integration tests. I do not expect the same results within round-off, but the diffs should be looked through to see if anything is very large.

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

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

TBD

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

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

FATES baseline hash-tag:

Test Output:

[rgknox]

Full model regression testing is now showing nigh-indistinguishable results with base:

Test description: BCI, inventory initialization, ST3, 5 years, 2-stream rad, 1 tropical evergreen PFT, parameter defaults otherwise:

https://drive.google.com/file/d/1HJadTpwo_MAdL5Sr8qWK4EFV98WPTlXy/view?usp=sharing

Removing draft status

Next steps:

1. evaluate gridded comparison while still retaining code that ensures near-b4b?
2. incrementally remove b4b preservation code and evaluate differences
3. clean up comments
4. evaluate timing differences (particularly related to ci precision)
5. introduce updates to btran (ie remove from stomatal intercept and add to Jmax)?

[rgknox]

I added a new test script that is a pure smoke test (ie pass/fail) on getting a solution for as many combinations as possible. The test output is as follows:

Starting smoke tests with the following nested combinations:

 2 conductance models, Medlyn and Ball-Berry
 2 pathway (C3/C4) models
 6 stomatal btran options from 0 to 5
 3 agross btran options from 0 to 2
 15 leaf temperature values [C] from -50.0 to 60.0
 15 RH values [fraction] from 0.001 to 1.0
 15 PAR Abs [W/m2] values from 0.0 to 800
 10 BL conductance (gb) [umol/m2/s] values from 50000.0 to 8500000.0
 15 BTRAN values [fraction] from 0.006737946999085467 to 1.0
 10 Vcmax 25 top values [umol/m2/s] from 1 to 250

Running a total of 303750000 tests: 

Completed 15187500 tests -- 5.0 percent complete
Completed 30375000 tests -- 10.0 percent complete
Completed 45562500 tests -- 15.0 percent complete
Completed 60750000 tests -- 20.0 percent complete
Completed 75937500 tests -- 25.0 percent complete
Completed 91125000 tests -- 30.0 percent complete
Completed 106312500 tests -- 35.0 percent complete
Completed 121500000 tests -- 40.0 percent complete
Completed 136687500 tests -- 45.0 percent complete
Completed 151875000 tests -- 50.0 percent complete
Completed 167062500 tests -- 55.0 percent complete
Completed 182250000 tests -- 60.0 percent complete
Completed 197437500 tests -- 65.0 percent complete
Completed 212625000 tests -- 70.0 percent complete
Completed 227812500 tests -- 75.0 percent complete
Completed 243000000 tests -- 80.0 percent complete
Completed 258187500 tests -- 85.0 percent complete
Completed 273375000 tests -- 90.0 percent complete
Completed 288562500 tests -- 95.0 percent complete
Completed 303750000 tests -- 100.0 percent complete

Completed Photosynthesis Smoke Test


Elapsed Time [s]: 1121.01798985

0 Failures out of 303750000 Encountered; 0.0% of Tests

[mpaiao]

Sorry for not reviewing this earlier! I think the refactoring looks great and helps a lot to understand the photosynthesis code, thanks!

I just have some minor questions and suggestions.

[glemieux]

I really like the work you did to continue modularizing the code. I have a couple of questions and identified a couple of commented out pieces of code.

[glemieux]

I'm assuming this will be updated closer to integration when we'll have a better idea what the default parameter file looks like at that time.

[glemieux]

I really like having the parameter registration broken out into "domain" specific modules. I'm just flagging here that there are being migrated to the host land model in #1300. Given this and that there are new parameters, I'm now thinking we should bring this in prior to #1300 as it might be easier to deconflict in that order and would allow us to get the new parameters into the update associated with ESCOMP/CTSM#2904.

[glemieux]

Leave this in for future work?

[glemieux]

Is checking err output here not necessary?

[glemieux]

Is checking err here not necessary as well?

[glemieux]

Code for future work, or temporary code to be removed?