WIP: Adding the EcoSIM for ATS PK (#335)

[AndrewGraus]

Contains the EcoSIM PK, and additional changes to CMake and header files. The EcoSIM PK replaces ATS surface balance and plant biogeochemistry with the models from EcoSIM:

https://github.com/jinyun1tang/EcoSIM

An in-depth user guide with how to install ATS with the EcoSIM TPL, and integrate the surface balance into the PK can be found here:

https://docs.google.com/document/d/157D910Ubuyw7tgoaSrVJ66M5D8bBelwTVE9CC7pv1LM/edit?tab=t.0#heading=h.rnmw1ogza2ln

Corresponding Amanzi pull request for the EcoSIM TPL can be found here:

https://github.com/amanzi/amanzi/pull/945

Overview of coupling:

1. EcoSIM PK - The purpose of this interface is to gather data from ATS state to report to EcoSIM on the subsurface flow and energy. It also uses ATS to manage surface forcings including weather, radiation and phenology and package them for forcing EcoSIM as well.

2. BGC Engine - modeled after Alquimia's chemistry engine, the idea is this is meant to be flexible to use with other BGC codes similar to Alquimia and geochemical codes.

3. Contains data structures BGCProperties, BGCState, and BGCSizes which are constructed to be translatable between c++ and fortran90, modeled off the Alquimia data structures. The code related to these is stored in pks/ecosim/data.

4. EcoSIM uses the subsurface properties and forcings from ATS to run its own submodules for surface and subsurface water and energy balance, and sums the resulting fluxes for water and energy in the surface/subsurface to transfer back to ATS, with these fluxes being passed to ATS flow and energy PKs as sources/sinks

5. Processes controlled by EcoSIM:

   • snow accumulation and snow melt
   • surface radiation balance
   • root absorption
   • canopy transpiration
   • canopy interception (precipitation and radiation)

6. In addition to passing aggregated fluxes, EcoSIM passes variables that are stored in ATS state. Some of these are stored for recall in between subsequent runs of EcoSIM within ATS or to restart, such as snow depth and canopy heat storage. Additionally, there are variables that are passed into ATS state to make use of ATS visualization and observation capabilities, such as evaporation flux components, transpiration, and snow temperature.

To Do:

1. EcoSIM needs to be informed of the Hydraulic conductivity. Currently, this is done on the EcoSIM side, but because ATS is running the hydrology model it would be more self-consistent to use ATS. I attempted to write an evaluator, but it is broken.

2. Vegetation type is not fully implemented and is being updated actively. Eventually, EcoSIM will allow more than one vegetation type per column. Some decisions need to be made about how that data will be formatted, and then the coupling will be updated to reflect that.

3. Transport - The EcoSIM PK can access concentrations and pass them to EcoSIM. However, EcoSIM's root nutrient absorption and biochemistry modules are not yet integrated, so transport has been removed from the PK tree for now.

4. Microbe biochemistry - Integrate the modules related to microbe biochemistry. Once integrated they will provide additional source/sinks to transport and flow for water and nutrient uptake, and any chemistry changes.

5. Full Plant Phenology - For now the phenology (LAI, vegetation type) needs to be input from data. However, EcoSIM has a full treatment of plant growth and phenology. The final step of the coupling will be to provide ATS access to this.