Coding language: C++
Authors: German Vargas G. & William R.L. Anderegg
Contact: [email protected]
The model uses a stomatal carbon gain vs. hydraulic risk optimization (Sperry et al. 2017 -- see references below) combined with a soil water budget to run a continuous growing season simulation, producing stand outputs such as net carbon assimilation (Anet), internal [CO2] (Ci), transpiration (E), total evapotranspiration (ET), and element conductances (k) on an hourly and summary basis (see output details below).
First, fork the repository to your own account. If you don't have a github account, just download the repository. Provide plant and site traits through the parameters file, then supply hourly weather data to drive model. The model will expect these files to be located in the current working directory. See the included examples and the details below for formatting and units. These example files contain all inputs necessary to test-run the model immediately after building.
a) To run, build and execute the model program (no command line arguments -- runs from files in the working directory). Building requires c++11, GNU example:
g++ -std=c++11
The -O3 and -ffast-math optimizations are recommended with GNU compilers:
g++ -std=c++11 -O3 -ffast-math
b) To build and run from the terminal in a Mac OS system:
b.1) Clone the repository in a desired location in your system.
git clone https://github.com/gevargu/garisom.git
b.2) Navigate to the repository by usin the command cd:
cd garisom
b.3) Run the following command will compile the code and build an executable:
make
b.4) Run this program from the same folder with this command:
./garisom
b.5) Press Command + C if you want to stop the model before it completes (Ctrl + C in Windows/Linux)
This version has also been tested with Visual Studio 2017's compiler with similar optimizations (floating point mode fast, maximum optimization preferring speed). The following files (included in this repository) should be located in the working directory (normally the same directory as the executable) before running:
- parameters_2.0.0.csv (site, atmospheric, soils, stand, plant, hydraulics, and carbon assimilation parameters).
- configuration_2.0.0.csv (model controls)
- dataset.csv (hourly weather drivers).
- dataheader.csv (a header row for the hourly data output).
- sumheader.csv (a header row for the summary data output).
- seasonlimits_2.0.0.csv (growing season limits and yearly atmospheric CO2, only required if using "sequential year mode" described below)
Upon completion, two output files are produced:
- The timesteps.csv output contains all of the hourly model outputs corresponding to the weather inputs.
- The summary.csv output includes various total values for each year (for example, net growing season productivity Anet, net transpiration E, etc.)
Model Parameters:
Configure plant traits and other parameters in parameters_2.0.0.csv (expected input units are indicated). Coupled with the parameter build function in R to produce the paramaters_2.0.0.csv file.
| Group | Parameter | Description |
|---|---|---|
| Site | i_sp | Species or PFT represented in parameter data |
| Site | i_region | Geographical region of the simulations. |
| Site | i_site | Site/simulation ID. This ID is used for naming the result files that are exported |
| Site | i_latitude | Latitude in degree fraction north. |
| Site | i_longitude | Longitude in degree fraction west. |
| Site | i_elevation | Site elevation in m above sea level. |
| Site | i_slopeI | Slope inclination; degrees from horizontal. |
| Site | i_slopeA | Slope aspect; counterclockwise degrees from south. |
| Site | i_gWaterP | Ground water pressure. |
| Site | i_gWaterDist | Distance to ground water source in m from the bottom of the rootsystem. |
| Atmosphere | i_atmTrans | Atmospheric transmittance from weather data (set to 0.65 as default if no data available). |
| Atmosphere | i_solarNoon | Solar noon correction from weather data in hours. |
| Atmosphere | i_emiss | Long wave emissivity. |
| Atmosphere | i_co2AmbPPM | Atmospheric/experiment CO2 ppm, it will update if working with multiple years. |
| Soil | i_layers | Number of soil layers (select 1-5). |
| Soil | i_fieldCapFrac | Fraction that field capacity is of saturation (minus residual). |
| Soil | i_fieldCapPercInit | Percent field capacity for starting the season. |
| Soil | i_rockFrac | Fraction of soil volume as rocks (0-1). |
| Soil | i_soilAbsSol | Absorptivity of soil surface for solar. |
| Soil | i_rhizoPer | Average percent of whole plant resistance in rhizosphere (maximum soil limitation) |
| Soil | i_texture | USDA soil texture category (equal for all layers but could also be determined per layer) |
| Stand | i_baperga | Basal area per ground area m2 ha-1 |
| Stand | i_leafAreaIndex | Canopy lai (m2 m-2) |
| Stand | i_soilXHeight | Height above soil surface for understory wind and gh in m |
| Stand | i_height | Average tree height in m |
| Stand | i_treeToPhotoLAI | |
| Stand | i_leafPerBasal | Initial leaf area per basal area per individual tree; m2 m-2 |
| Tree | i_leafWidth | Leaf width in m |
| Tree | i_leafAngleParam | Leaf angle parameter; CN 15.4 |
| Tree | i_aspect | Max radius of root system per max depth |
| Tree | i_rootBeta | Root biomass distribution is allocated based on the equation reported in Love et al (2019): M = 1 - Beta^d, where M is the fraction of biomass above depth d expressed in cm. We find the Beta that provides an M of 0.995 for the maximum rooting depth. |
| Hydraulics | i_leafPercRes | Saturated % of tree resistance in leaves |
| Hydraulics | i_kmaxTree | Kmax of tree in kg hr-1 m-2 MPa-1 per basal area |
| Hydraulics | i_pinc | Pressure increment for curve generation, (MPa) - higher is faster, but less accurate (setting too high can cause Newton-Rhapson root pressure solving failure) |
| Hydraulics | i_LSC | Leaf specific conductance in mmol m-2 w-1 MPa-1 |
| Hydraulics | i_LSCpref | Water potential for LSC |
| Hydraulics | i_cr | Root element Weibull parameter c |
| Hydraulics | i_br | Root element Weibull parameter b |
| Hydraulics | i_cs | Stem element Weibull parameter c |
| Hydraulics | i_bs | Stem element Weibull parameter b |
| Hydraulics | i_cl | Leaf element Weibull parameter c |
| Hydraulics | i_bl | Leaf element Weibull parameter b |
| Hydraulics | i_sapwoodT | Change in sapwood per change in diameter at breast height |
| Hydraulics | i_conduitDiam | Vessel or tracheid diameter in um |
| Photosynthesis | i_qMax | Quantum yield of electron transport; moles e per mols photons |
| Photosynthesis | i_vmax25 | Maximum carboxylation rate (vmax) at 25C (umol m-2 s-1) |
| Photosynthesis | i_jmax25 | Maximum electron transport rate (jmax) at 25C (umol m-2 s-1), can be assumed to be Vmax25 * 1.67 |
| Photosynthesis | i_kc25 | Michaelis-Menten constant for CO2 in mole fraction at 25C. Bernacchi T response |
| Photosynthesis | i_ko25 | Michaelis-Menten constant for O2 in mole fraction at 25C. Bernacchi T response |
| Photosynthesis | i_comp25 | Photorespiratory compensation point in mole fraction at 25C. Bernacchi T response |
| Photosynthesis | i_thetaC | Shape factor for A-ci colimitation |
| Photosynthesis | i_havmax | Temp-dependency parameters from Leunig 2002 (J mol-1) |
| Photosynthesis | i_hdvmax | Temp-dependency parameters from Leunig 2002 (J mol-1) |
| Photosynthesis | i_svvmax | Temp-dependency parameters from Leunig 2002 (J mol-1) |
| Photosynthesis | i_lightCurv | Temp-dependency parameters from Leunig 2002 |
| Photosynthesis | i_lightComp | Light compensation point in ppfd |
| Photosynthesis | i_hajmax | Temp-dependency parameters from Leunig 2002 (J mol-1) |
| Photosynthesis | i_hdjmax | Temp-dependency parameters from Leunig 2002 (J mol-1) |
| Photosynthesis | i_svjmax | Temp-dependency parameters from Leunig 2002 (J mol-1 K-1) |
| BAGA_optimizer | i_iter_gwInc | |
| BAGA_optimizer | i_iter_gwStart | |
| BAGA_optimizer | i_iter_gwEnd | |
| BAGA_optimizer | i_iter_ffcInc | Note: If FFC start < FFC end_ will start curve gen by incrementing FFC before ground water |
| BAGA_optimizer | i_iter_ffcStart | |
| BAGA_optimizer | i_iter_ffcEnd | |
| BAGA_optimizer | i_iter_bagaInc | |
| BAGA_optimizer | i_iter_bagaStart | |
| BAGA_optimizer | i_iter_bagaEnd | |
| BAGA_optimizer | i_iter_bagaRef | |
| BAGA_optimizer | i_iter_bagaCutoff | WLT K dropoff threshold (fraction of reference iteration kmin) |
Model Configuratiosn:
| Group | Model Control | Description |
|---|---|---|
| Soil | igWaterEnable | Turns on/off groundwater flow. Values: n (off); y (on). It provides an unlimited source of water at a set potential and distance below the root layers. This water will flow up into the soil layers, and potentially allow layers to fill above field capacity (from the bottom layer up). When disabled (default), the only sources of water input will be the initial fraction of field capacity and observed rainfall (and any water over field capacity will become "drainage"). |
| Soil | i_soilRedEnable | Turns on/off soil redistribution routine. Values: n (off); y (on). It allows water to flow between soil layers. |
| Soil | i_soilEvapEnable | Turns on/off soil evaporation routine. Values: n (off); y (on). It enables simulation of water evaporation from the surface soil layer. |
| Climate | i_rainEnable | Turns on/off rain inputs. Values: n (off); y (on). It allows for precipitation events. Weather data rainfall will be ignored if disabled. |
| Climate | i_useGSDataStress | Turns on/off growing season data for multiple year modeling. Vakyes: n (off); y (on). If enabled, multiple years will be run "sequentially" with on and off seasons defined in seasonlimits_2.0.0.csv and a continuous water budget. When disabled (default), all weather timesteps provided are treated as part of the growing season and the user is expected to truncate individual years to their start/end days. Water budget is reset between years when disabled, treating years as totally independent. |
| Climate | i_useGSDataOpt | Turns on/off growing season data for multiple year modeling during BAGA optimization. Values: n (off); y (on). |
| Hydraulics | i_refilling | Turns on/off xylem refilling within a growing season. Values: n (off); y (on). It allows trees to restore lost conductance, however the refilling model is not sufficient to simulate authentic xylem refilling behavior and has not been thoroughly tested in the current version of the code. |
| Hydraulics | i_predawnsMode | Turns on/off if model should consider measured pre-dawn water potential values. Values: n (off); y (on). If set to 'y', disables soil simulation and runs from hourly inputs of canopy predawn water potential. These are read from the "rain" column (rain is not used with the soil sim disabled) in MPa. See "dataset - predawns example.csv". This mode is especially useful when comparing to other models which run from canopy predawn measurements, and generally runs significantly faster as it does not need to solve for root layer pressures. |
| Hydraulics | i_cavitFatigue | Turns on/off xylem stress hysteresis to carry effects from previous growing season. Values: n (off); y (on). It allows for a weighted estimation of xylem vulnerability to embolism |
| Hydraulics | i_stemOnly | Turns on/off xylem stress hysteresis only in stem xylem. Values: n (off); y (on). When disabled it allows for a weighted estimation of xylem vulnerability to embolism for both stem and roots |
| BAGA | i_iter_gwEnable | Not tested in version 2.0.1. |
| BAGA | i_iter_ffcEnable | Not tested in version 2.0.1. |
| BAGA | i_iter_bagaEnable | Increate the BA:GA to find the basal area that puts the stand in ecohydrological equilibrium with the weather conditions. Values: n (off); y (on). Not tested in version 2.0.1. |
| BAGA | i_iter_useAreaTable | if y will pull GA:BA_ LA:BA_ LAI from AreaData table per year and per site. Values: n (off); y (on). Not tested in version 2.0.1. |
| BAGA | i_iter_yearsAsCount | The "year" values represent different data set ID's_ not actual years. In this mode the "start" year is always 0. Values: n (off); y (on). Not tested in version 2.0.1. |
| BAGA | i_iter_runSupplyCurve | Turns on/off all iteration settings. Values: n (off); y (on). Not tested in version 2.0.1. |
| Community | i_multipleSP | Turns on/off whether our model configuration has 1 species per site (monodominant) or multiple species per site (diverse). Values: n (off); y (on). NOT READY FOR MULTIPLE SPECIES/PFTs in version 2.0.1. |
| Community | i_speciesN | Nnumber of species/PFT to run the model. |
| Forcing files | i_ClimateData | Path to file with climate forcing variables dataset.csv |
| Forcing files | i_GSData | Path to file with growing season data seasonlimits.2.0.0.csv |
| Forcing files | i_dataheader | Path to time-step header file dataheader.csv |
| Forcing files | i_sumheader | Path to annual summary header file sumheader.csv |
See example data for formatting. Weather drivers should be in hourly timesteps and can include multiple years of data. Note that while year values are arbitrary, they should be sequential. For example, if running data for the years 1997 and 2005 these should be numbered sequentially as 1 and 2 (or 1997 and 1998, etc). Inputs:
- Year.
- Julian Day (1-366).
- Hour (0-23).
- Obs. Solar (W m-2).
- Rain (mm).
- Wind (m s-1).
- Tair (C).
- Tsoil (C, if not available substitute air temp).
- D (kPa).
- Autosave is always enabled regardless of the setting, as this version of the model has no alternative output method. Output files will be generated in the working directory when the run completes.
-Hourly Outputs (see dataheader.csv for full list): -Pressures (predawn soil layer pressures, sun and shade "mid-day" canopy pressures, MPa), -Water flows (mmol m-2s-1), -PS assimilation (A, umol s-1m-2 (leaf area)), -Gain-risk optimized stomatal conductance to water (Gw, mmol m-2s-1), -Element and whole plant conductances, (k, kghr-1m-2), -Water content and deltas (mm), -Ci
-Summary Outputs (per year, see sumheader.csv for full list): -Total Anet (mmol yr-1 m-2(leaf area)), -Total E (mm = mm3/mm2(ground area)), -Minimum whole plant conductance during the growing season (kghr-1m-2), -Percent Loss Conductance (PLC, percent, relative to a reference conductance at field capacity), -Mean Ci/Ca (+ A weighted Ci/Ca), -Water summary (start/end content, total growing season input (mm)).
- Set "Use GS Data" to "n" under "Program Options"
- Use growing season trimmed data (see the example: "dataset.csv").
- Ensure that the growing season limits are defined in "seasonlimits.csv"
The default setting is to reset the tree hydraulics and reset the soil water content to the specified percent of field capacity every year. The years are completely independent, only run in a single dataset for convenience. In this mode, weather data should be trimmed to only the growing season days as in the included dataset.csv (so that the last day of one growing season is followed immediately by the first day of the next). Year values are used for output, and each must be unique and optimally sequential (to determine when new years begin), but the values are otherwise unused by the model and thus do not need to be meaningful values. When running in this mode the growing season limits (seasonlimits.csv) will not be used; All days in the dataset will be considered to be in the growing season.
In this mode, plant hydraulics will reset between seasons and plant transpiration/productivity will be disabled during the off-season, but soil water budget will continue to be computed. Soil may or may not be refilled to field capacity depending on the availability of off-season precipitation.
- Set "Use GS Data" to "y" under "Program Options".
- Use full-year data (see the example: "dataset - full year example.csv").
- Ensure that the growing season limits are defined in "seasonlimits.csv".
- Note: The year values in "seasonlimits.csv" are for reference only; The first row of start/end days will be used for the first year of data, etc.
- Soil surface evaporation will also be disabled during the off-season. This is not particularly realistic, but the functionality was intended to answer the question: Is there at minimum enough recorded rainfall to refill the soil? A more robust off-season water simulation would require additional data (snow pack) and simulation of soil behavior under snow and is not provided here.
Describing the version 1.0 of the C++ code:
- Venturas MD, JS Sperry, DM Love, EH Frehner, MG Allred, Y Wang, and WRL Anderegg. (2017). A Stomatal Control Model Based on Optimization of Carbon Gain versus Hydraulic Risk Predicts Aspen Sapling Responses to Drought. New Phytologist 220: 836–50.
Describing the gain/risk algorithm used in the model:
- Sperry JS, MD Venturas, WRL Anderegg, M Mencucinni, DS Mackay, Y Wang, and DM Love. (2017). Predicting stomatal responses to the environment from the optimization of photosynthetic gain and hydraulic cost. Plant Cell and Environment 40: 816-830
Describing the original hydraulic model the gain-risk optimization was based on:
- Sperry JS, and DM Love (2015) Tansley Review: What plant hydraulics can tell us about plant responses to climate-change droughts. New Phytologist 207: 14-17.
- Sperry JS, Y Wang, BT Wolfe, DS Mackay, WRL Anderegg, NG McDowell, and WT Pockman. (2016). Pragmatic hydraulic theory predicts stomatal responses to climatic water deficits. New Phytologist 212: 577-589