Land Energy Balance Solve with variable stomatal conductance coupling

[rgknox]

Description of changes

This draft set of changes is an initial stab and breaking up the Land Energy Balance iterative solve, so that updates stomatal conductance and photosynthesis as a separate loop and with variable coupling strength. The motivation behind this, is that a nearly similar answer can be achieved as the base method, but with fewer calls to photosynthesis. Photosynthesis is overwhelmingly the slowest part of the process when FATES is active, and the slowest (but probably not overwhelmingly slowest) part of the process when the native vegetation model is used.

Specific notes

The current implementation has a local flag that enables either the default or the variable control behavior. But this could easily be tied to a namelist control (UPDATE: THIS IS BEING IMPLEMENTED).

The current implementation has been written to accommodate both FATES and native CLM vegetation structure, but was really only tested with FATES.

There are various calls to subroutines in this module that are designed to make calculations over a vector of patches, that are now only being called for a single patch. So the callinng of the subroutines would potentially be re-written if the general looping structure is something that we want...

The convergence criteria is still immature. I started with a relative difference criteria on resistance. But @gbonan has advocated for absolute criteria in the past and that may be a good way to go here instead. Perhaps a sensitivity analysis on aboslute convergence criteria is in order. Using relative criteria creates a situation where areas of high resistance generate large acceptable differences and I saw larger differences in the base in places with large resistance. When I swapped to use relative conductance criteria, the opposite was true. The next step is to determine a reasonable absolute criteria.

Contributors other than yourself, if any: many people provided feedback and this was presented at the LMWG, conversations with @gbonan guided the design

CTSM Issues Fixed (include github issue #):

Are answers expected to change (and if so in what way)?

Any User Interface Changes (namelist or namelist defaults changes)? Potentially changes to the namelist

Does this create a need to change or add documentation? Did you do so? Yes, this would potentially require an update to the tech doc

Testing performed, if any:

Timing: this makes FATES quite a bit faster! No data on making non-FATES faster

Regression testing TBD

NOTE: Be sure to check your coding style against the standard
(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
the list of common problems to watch out for
(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).

[rgknox]

Slides from the LMWG here

Slides 10-16 are relevant