07-AdvancedWaterBalance.Rmd

# (PART) Advanced water balance modelling {-}

# Advanced water balance model {#advancedwaterbalance}

This chapter provides an overview of the advanced water and energy balance model available in **medfate**. It shares some characteristics with the basic water balance model described in previous chapters. Like the previous one, the model is run using function `spwb()`, for a set of days, or function `spwb_day()`, for a single day. Compared to the basic model, the advanced water balance model adds more detail in some processes (radiation transfer, plant hydraulics and photosynthesis) and incorporates other processes that were missing (canopy/soil energy balances and plant water balance). Importantly, two alternative approaches are possible regarding *plant hydraulics* and *stomatal conductance* sub-models:

  + If `transpirationMode = "Sperry"`, the sub-models of plant hydraulics and stomatal conductance follow @Sperry2016 and were described in detail in @DeCaceres2021. 
  + If `transpirationMode = "Sureau"`, the sub-models of plant hydraulics and stomatal conductance follow SurEau-ECOS and were described in @ruffault_sureau-ecos_2022. 

This chapter presents an overview of the advanced water balance model and is structured as in chapter \@ref(basicwaterbalance). Process formulations shared with the basic water balance model were presented in previous chapters and will not be repeated. The chapters following this one provide a detailed description of those processes that are represented when using the advanced model only. Whenever necessary, we will detail the difference between the two sub-models of plant hydraulics and stomatal conductance corresponding to @DeCaceres2021 and @ruffault_sureau-ecos_2022. We recommend readers to familiarize themselves with basic water balance modelling processes before reading this and the subsequent chapters. In addition, users of this model should have enough background on the processes implemented to fully understand and exploit model outputs. Since the scope of this book is focused on the model description, interested readers should address relevant eco-physiological bibliography complement the material exposed here.

## About Sureau {#aboutsureau}

SurEau is a comprehensive plant hydraulic model that already knows different versions. The first and most detailed version was developed in C by Hervé Cochard (Sureau.c, @cochard_sureau_2021), which follows a preliminary version coded in Excell and in R that has been used to understand the stomatal functioning of plants around the world [@Martin-StPaul2017].

In Sureau.c , the plant is relatively well detailed (large roots, trunk, branches, leaves, buds and even flowers). The numerical resolution of the calculations is done according to an explicit scheme, where the elementary transfers of water between each compartment must be calculated at very small time-steps to avoid numerical instabilities known as the Courant–Friedrichs–Lewy condition (for a tree time step must be around 0.001s). This complexity is an advantage for exploring questions about the physiological functioning of the tree. However, the computational demand is also a limit for large-scale application of the model and for integration in dynamic vegetation or land surface models.

Researchers from INRAE-URFM (François Pimont, Julien Ruffault, Nicolas Martin-StPaul at Avignon) and INRAE-PIAF (Hervé Cochard, at Clermont-Ferrand) therefore joined forces to develop a new version, coded in R native, where the numerical scheme for solving water transport calculations was improved (SurEau-Ecos, @ruffault_sureau-ecos_2022). They implemented two alternative resolution schemes (the so called semi-implicit and implicit) allowing to solves the water transport accounting for capacitance and cavitation at much larger time steps (of the order of 10 to 30 minutes). In this version the authors also used a tree simplified to only two organs: leaves and stems (and therefore four compartments with an apoplasm and a symplasm for each organ) to facilitate parameterization. This advance has been decisive for **medfate** because it made the model compatible in terms of plant structure and and computational demand. In **medfate** we refer to `Sureau` when this model is used for the computation of transpiration and plant water related processes.


## Design principles {#advanceddesign}

The advanced model performs soil/plant water balance and soil/canopy energy balance for a given forest stand and for the period corresponding to input weather data. Some components of the water balance (rainfall interception, soil evaporation, snow melt, etc) are calculated on a daily step basis whereas energy balances and plant transpiration are determined at subdaily steps (typically 1h steps). The model considers only the vertical spatial dimension of the stand, and not the horizontal distribution of plants within it. Still, the forest stand is divided into: (a) canopy vertical layers; (b) woody plant cohorts of different species and a herbaceous layer. Like the basic model, the soil is discretized into a number of soil layers, and the soil water balance, including water movement in the bulk soil, is addressed in daily substeps.

Hydrological processes are the same as in chapter \@ref(basicwaterbalance). Thus, the model includes water interception loss [@Gash1995; @liu_evaluation_2001], plant transpiration, evaporation from soil [@Ritchie1972], transpiration of the herbaceous layer, infiltration into the soil matrix [@Boughton1989; @green_studies_1911] and vertical water movement within the soil, the latter following either a single-domain model [@bonan_climate_2019] or a dual-permeability model [@jarvis_modelling_1991; @larsbo_improved_2005], where total porosity is partitioned into two separate flow regions (matrix and macropores), each with its own degree of saturation, conductivity and flux rate.

A great deal of the complexity of the advanced model concerns the estimation of woody plant transpiration and photosynthesis. The model simulates stomatal regulation of gas exchange separately for *sunlit* and *shade* leaves at sub-daily steps, involving detailed calculations of plant hydraulics, leaf energy balance and photosynthesis. Compared to the basic water balance model of chapter \@ref(basicwaterbalance), the higher level of complexity of the advanced model allows a more precise estimation of carbon and water flows, as well as a more nuanced evaluation of plant water status, at the expense of a more complex parametrization.

To calculate radiation balance and incident PAR at the leaf level, the leaf area of each plant cohort is divided into vertical layers according to its crown limits. Photosynthesis and transpiration of sunlit and shade leaves are treated separately [@DePury1997]. Given an input direct and diffuse short-wave irradiance at the top of the canopy, the amount of light absorbed by sunlit leaves, shade leaves and the soil follows the radiation transfer model of @Anten2016. The scheme for long-wave radiation balance between the atmosphere, the different canopy layers and the soil follows the SHAW model [@Flerchinger2009].

Energy balances are conducted at the *stand* scale and the *leaf* scale:

 + At the *stand* scale, the model keeps track of temperature variation within the canopy (i.e. canopy energy balance) and in the uppermost soil surface (i.e. soil energy balance) as the result of energy exchanges between them and with the atmosphere. Heat conduction also occurs among soil layers. Energy balance can be performed assuming a single canopy layer, with soil and canopy energy balance equations being similar to those of Best et al. [-@Best2011] for JULES. Alternatively, energy balance can be conducted for each vertical layer following @Bonan2014. In this case, the model allows considering within-canopy gradients in temperature, water vapor pressure, and $CO_2$ as well as the turbulent transport of heat, water vapor and $CO_2$ between canopy layers [@Ma2019], determined using a canopy turbulence model by @Katul2004.
 + At the *leaf* scale, radiation inputs include shortwave radiation from the atmosphere absorbed by the leaf and the net balance of long-wave radiation. Leaf temperature is determined assuming that the temperature of the surrounding air is that of the canopy (or canopy layer). After determining stomatal regulation, the model up-scales the transpiration flux to the canopy (or canopy layer) scale and the corresponding latent heat is used to complete the calculation of the energy balance at the canopy (or canopy layer) scale. Latent heat fluxes from evaporation from the soil and evaporation of intercepted rainfall are also included in the canopy/soil energy balances.

Plant hydraulics and stomatal regulation follow different designs depending on the sub-model employed:

+ If `transpirationMode = "Sperry"`, plant hydraulics follows the steady-state approach of Sperry et al. [-@Sperry1998] model, and stomatal regulation follows the profit maximization approach of Sperry et al. [-@Sperry2016]. 

+ If `transpirationMode = "Sureau"`, plant water compartments are always included, and water flows follow Darcy's law, as described in @ruffault_sureau-ecos_2022. In this case, stomatal regulation follows a Baldocchi-type or Jarvis-type model.

Like in the basic water model, the advanced model assumes by default that soil moisture under all plant cohorts is the same (i.e. vertical soil layers are shared among cohorts). However, variations in soil moisture beneath plant cohorts (and, implicitly, horizontal variation of soil moisture) can be simulated. In this case, hydrological processes are replicated for the fraction of soil corresponding to each cohort. Transpiration of each plant cohort depends on the soil moisture beneath itself and, depending on root overlap, on the soil moisture beneath other plant cohorts.

## State variables {#statevariablesadvanced}

The following are state variables in the model under all simulations:

+ Cumulative degree days (a) to budburst, (b) to complete unfolding or (c) to senescence ($S_{eco,d}$, $S_{unf,d}$ or $S_{sen,d}$; all in $^\circ C$), are tracked by the model to determine leaf phenological status (see \@ref(leafphenology)).
+ Daily soil moisture content dynamics on each layer $s$ are tracked using $W_s = \theta_s(\Psi_s)/ \theta_{fc,s}$, the *proportion of soil moisture in relation to field capacity*, where moisture at field capacity, $\theta_{fc,s}$, is assumed to correspond to $\Psi_{fc} = -0.033$ MPa. Note that $W_s$ values larger than one are possible if the soil is between field capacity and saturation.
+ The air temperature within the canopy ($T_{can}$; ºC) and the temperature of each soil layer $s$ ($T_{soil,s}$; ºC) are tracked for every subdaily step.

Additional state variables depend on the activation of specific control flags (see subsection \@ref(advancedwaterbalancecontrol)):

+ If `transpirationMode = "Sureau"`, the model also tracks $\Psi_{apo, stem,i}$, the water potential of the stem apoplastic compartment, as well as the water potential of stem and leaf symplastic compartments, $\Psi_{symp, stem,i}$ and $\Psi_{symp, leaf,i}$ respectively.
+ *If stem cavitation is not completely reversible*, the model tracks $PLC_{stem, i}$ and $PLC_{leaf, i}$, the proportion of conductivity lost the stem and leaves, respectively, of plants of cohort $i$.
+ *If plant water pools are considered*, the model also tracks $W_{i,s}$, the proportion of soil moisture in relation to field capacity for layer $s$ within the areal fraction of stand covered by cohort $i$.
+ *If multi-layer canopy energy balance is activated*, the model tracks for each vertical layer $j \in \{1,l\}$: 
  a. Air temperature, $T_{air,j}$
  b. Water vapor pressure, $e_{air,j}$
  c. $CO_2$ concentration, $C_{air,j}$.

## Water and energy balances {#waterenergybalances}

### Water balance

The water balance equations for the soil and snowpack of the advanced model are essentially the same as introduced in section \@ref(soilwaterbalance), with some minor modifications. Although the advanced water balance model includes hydraulic redistribution, this does not change the total amount of water in the overall soil, so the water balance equation is is very similar to that of the basic water balance model (eq.\@ref(eq:basicwaterbalanceequation)), but where woody plant water uptake ($Ex_{woody}$) is used instead of woody transpiration ($Tr_{woody}$). 
\begin{equation}
\Delta{V_{soil}} = (If + Lw + Cr) - (Dd + Se + Es + Tr_{herb} + Ex_{woody})
(\#eq:advancedwaterbalanceequation)
\end{equation}
where all the other terms were defined in \@ref(soilwaterbalance). Soil water extraction ($Ex_{woody}$) and plant transpiration ($Tr_{woody}$) will be equal if plant capacitance effects are not considered. Otherwise the amount of water stored in the woody plant tissues changes according to:
\begin{equation}
\Delta{V_{plant}} = Ex_{woody} - Tr_{woody}
(\#eq:plantwaterbalance)
\end{equation}

Variations of the water balance can occur depending on specific control flags, as explained in section \@ref(soilwaterbalance). Unlike the basic water balance, in this model water balance components contributing to latent heat of vaporization (plant transpiration, evaporation from soil surface and rainfall intercepted by canopy surfaces) or latent heat of fusion (snow melt) are included in the energy balance equations of the canopy and soil, therefore coupling water and energy balances.

### Single-layer canopy energy balance

For the sake of performing energy balance, the canopy can be considered a single layer that exchanges energy with the soil and the atmosphere [@Best2011]. First, it absorbs shortwave radiation from the atmosphere ($K_{abs,can}$) and long-wave radiation resulting from net radiation balance  ($L_{net,can}$). Other energy fluxes considered are convective exchanges between the canopy and atmosphere ($H_{can,atm}$) and between the canopy and the soil ($H_{can,soil}$). Energy is absorbed from the canopy through latent heat of vaporization ($LE_{vap, can}$) produced via transpiration ($Tr$) and evaporation of water intercepted by the canopy ($In$); or via latent heat of fusion due to snow melt ($LE_{fus, snow}$). Combining all energy flows (all of them in $W \cdot m^{-2}$), the instantaneous energy balance equation for the canopy is:
\begin{equation}
  TC_{can} \cdot \frac{\delta T_{can}}{\delta t} = K_{abs,can} + L_{net,can}  - LE_{vap, can} - LE_{fus, snow}- H_{can,atm} - H_{can,soil} 
(\#eq:canopyenergybalance)
\end{equation}
where $TC_{can}$ is the canopy thermal capacitance (in $J \cdot m^{-2} \cdot K^{-1}$). 

### Multiple-layer canopy energy balance
Alternatively, the model allows performing an energy balance for each vertical layer in the canopy, including its heat storage capacity [@Ma2019]. The energy balance equation for canopy layer $j$ is:
\begin{equation}
  TC_{j} \cdot \frac{\delta T_{air,j}}{\delta t} = K_{abs,j} + L_{net,j}  - LE_{vap, j} + H_{j} 
(\#eq:canopylayerenergybalance)
\end{equation}
where $K_{abs,j}$ is the short-wave radiation absorbed by leaves in the layer, $L_{net,j}$ is the net long-wave radiation balance of the layer, $LE_{vap, j}$ is the latent heat flux and $H_j$ is the sensible heat flux, which includes heat coming from leaves or soil surfaces as well as turbulent heat transport from adjacent layers. Finally, $TC_{j}$ is the thermal capacitance (in $J \cdot m^{-2} \cdot K^{-1}$) of canopy layer $j$. Latent heat of fusion ($LE_{fus, snow}$) needs to be subtracted in the right-hand side of the equation from the bottom canopy layer.

### Soil energy balance

Like the canopy, the uppermost soil layer absorbs short-wave radiation from the atmosphere ($K_{abs,soil}$) and has a net long-wave radiation balance ($L_{net,soil}$). The uppermost soil layer also exchanges heat with the canopy ($H_{can,soil}$) and releases energy in the form of latent heat of vaporisation due to evaporation from the soil surface ($LE_{vap, soil}$). Finally, the soil layer exchanges thermal energy by conduction with the layer below ($G_{1,2}$) The energy balance equation for the uppermost soil layer is:
\begin{equation}
  TC_{soil, 1} \cdot \frac{\delta T_{soil, 1}}{\delta t} = K_{abs,soil} + L_{net,soil} + H_{can,soil} -  LE_{vap, soil} - G_{1,2}
(\#eq:soilenergybalance)
\end{equation}
where $TC_{soil,1}$ is the thermal capacitance of soil layer 1 (the uppermost layer). 

Instantaneous soil temperature changes on each soil layer depend on the balance between upward and downward energy flows. The downward energy flow for the uppermost soil layer depends on its energy exchanges with the canopy and the atmosphere, as shown in eq. \@ref(eq:soilenergybalance), whereas the remaining energy flows are generated by heat conduction and depend on the temperature gradients between soil layers. The energy balance for a soil layer $s>1$ is:
\begin{equation}
  TC_{soil, s} \cdot \frac{\delta T_{soil, s}}{\delta t} = G_{s-1,s} - G_{s,s+1}
(\#eq:deepsoilenergybalance)
\end{equation}
where $G_{s-1,s}$ is the energy inflow from layers above, $G_{s,s+1}$ is the energy outflow towards layers below and $TC_{soil,s}$ is the thermal capacitance of soil layer $s$ (in $J \cdot m^{-2} \cdot K^{-1}$).

Unlike @Best2011, the model considers the snow pack and the uppermost soil layer as a single layer in terms of energy exchange, but treats this layer differently depending on whether snow is present or not. The snow pack absorbs shortwave radiation (section \@ref(snowpack)) and snow melt is included as latent heat in the energy balance, but the snow layer does not exchange long-wave radiation with the soil nor the atmosphere. $K_{abs,soil}$ is set to zero when snow pack is present (because shortwave radiation is absorbed by snow), but the soil layer still exchanges long-wave radiation and convective energy with the canopy and the atmosphere. In addition, remember that bare soil evaporation does not occur when the snow pack is present (section \@ref(soilevaporation)).  


## Process scheduling {#advancedwaterbalancescheduling}

For every day to be simulated, the model performs the following steps:

1. Update leaf area values according to the phenology of species (section \@ref(leafphenology)).
2. Determine rainfall interception loss ($In$) and net rainfall ($Pr_{net}$) (section \@ref(interception)). The amount of water reaching the soil surface from the rainfall event is the sum of net rainfall ($Pr_{net}$) and surface runon ($Ro$), if given. If snow dynamics are included, increase snow pack from snow precipitation ($Ps$) and decrease it following snow melt ($Sm$) (section \@ref(snowpack)).
3. Determine bare soil evaporation ($Es$), if snow is not present (section \@ref(soilevaporation)), and herbaceous transpiration ($Tr_{herb}$; section \@ref(herbaceoustranspiration)).
4. Determine sub-daily air temperature and direct/diffuse irradiance variations (chapter \@ref(subdailytemplight)).
5. Determine the proportion of sunlit/shade leaves (section \@ref(sunlitshadeleaves)), the shortwave radiation absorbed by plants (sections \@ref(shortwaveradiationcanopyabs)) and the soil (section \@ref(shortwaveradiationsoilabs)) at sub-daily steps.
6. Set up plant hydraulics (chapter \@ref(planthydraulics)). If `transpirationMode = "Sperry"`, this implies building the water supply function of each plant cohort from the current soil moisture levels, whereas if `transpirationMode = "Sureau"` the state of the hydraulic network from the previous day is recovered. 
7. Determine instantaneous plant cohort transpiration, photosynthesis rates and close soil/canopy energy balance at sub-daily steps (chapters \@ref(transpirationsperrysureau) and \@ref(closecanopysoilenergybalance)). This involves the following actions for each sub-daily step:
    a. Determine long-wave radiation exchange between soil, canopy layers and atmosphere (section \@ref(longwaveradiation)).
    b. If `transpirationMode = "Sperry"`, for each woody cohort:

        i. Calculate leaf energy balance and photosynthesis (for shade and sunlit leaves of each plant cohort) corresponding to each transpiration value of the supply function (section \@ref(leafenergybalancephoto)). If plant capacitance effects are considered this concerns the stem-to-leaf hydraulic supply function.
        ii. Determine stomatal conductance, transpiration and photosynthesis on shade and sunlit leaves of each plant cohort according to Sperry's [-@Sperry2016] profit maximization strategy (section \@ref(stomatalregulation)).
        iii. Update leaf and stem PLC values.
        
    c. If `transpirationMode = "Sureau"`, for each plant cohort leaf energy balance, stomatal and cuticular conductances, transpirational flows, photosynthesis and plant hydraulics are computed iteratively in small temporal sub-steps (e.g. 10 min):
       
        i. Perform energy balance of sunlit and shade leaves (section \@ref(leafenergybalancephoto)), according to the energy inputs of the current subdaily time step and the transpiration flux of the previous small sub-step.
        ii. Calculate shade-leaf, sunlit-leaf and stem cuticular conductances and cuticular transpiration according to current temperature (\@ref(cuticularconductancesureau)).
        iii. Calculate stomatal regulation and stomatal transpiration for sunlit and shade leaves (\@ref(stomatalconductancesureau)).
        iv. Calculate instantaneous gross and net photosynthesis rates for sunlit and shade leaves.
        v. Update water potentials, water fluxes (including soil water uptake) and hydraulic conductances across the plant hydraulic network.
       
    d. Scale transpiration ($Tr_{woody}$), soil water extraction ($Ex_{woody}$) and photosynthesis to the plant cohort level (section \@ref(scalingtranspirationphotosynthesis)).
    e. Complete energy balance of the canopy and the soil, after translating plant transpiration, evaporation from bare soil, snow melt and interception loss to latent heat and calculating convective heat exchange for both the canopy and the soil. Alternatively, perform energy balance for individual canopy layers, while including turbulent heat exchange and turbulent transport of water vapor and $CO_2$ between layers (chapter \@ref(closecanopysoilenergybalance)).
8. Determine day-level photosynthesis and transpiration from instantaneous rates and update soil moisture (section \@ref(daylevelphototransp)). Determine drought stress for each woody plant cohort (section \@ref(advanceddroughtstress)).
9. Determine rainfall infiltration (section \@ref(infiltration)) and vertical water movement within the soil, while considering soil layer source/sinks from infiltration, bare soil evaporation and herbaceous transpiration and woody plant extraction/redistribution (section \@ref(soilflows)). This updates soil moisture and lower boundary condition of water movement corresponds to deep drainage ($Dd$). 
10. If fire hazard calculations are requested, estimate live and dead fuel moisture and potential fire behaviour (chapter \@ref(fuelandfirebehavior)).


Steps 1-3 are the same as described in the basic model, and steps 9-10 here correspond to steps 5-6 in the basic model. The set of steps corresponds to simulations if plant water pools *are not* considered, so that only the water balance of the overall soil matters. If plant water pools *are* considered, steps 1, 2 and 10 are the same, because they apply to the whole forest stand (note that at present infiltration does not depend on antecedent conditions). However, steps 3 is performed for each water pool separately because it depends on antecedent soil moisture. Steps 6-8 also involve defining woody plant water uptake from different plant water pools depending on the proportion of fine roots of each woody cohort in each pool (see \@ref(transpirationpools)). Soil water flows from these three steps are then averaged at the stand level. After that, Step 9 is performed on the soil corresponding to each pool, and the resulting drainage estimates are also averaged. Finally, the soil moisture of the overall soil is estimated by averaging the soil moisture of water pools.

## Inputs and outputs

### Soil, vegetation and meteorology

**Soil**

Soil input requirements are the same as for the basic water balance model and were fully described in section \@ref(soilinput). @Genuchten1980 water retention curves are forced for this model, because rhizosphere conductance is modelled using van Genuchten hydraulic equations (see subsection \@ref(vulnerabilitycurves)).


**Vegetation**

Vegetation input requirements were fully described in section \@ref(vegetationinput). Trees and shrubs do not need to be characterized with different variables in soil water balance calculations, since both kinds of cohort have a $LAI$ value. In most cases, users only need to estimate the leaf area index corresponding to live leaves, i.e. $LAI^{live}$, because normally at the starting point all leaves are expanded (i.e. $LAI^{\phi} = LAI^{live}$) and one can assume no dead leaves in the canopy (i.e., $LAI^{dead} = 0$). Vegetation characteristics stay constant during simulations using function `spwb()`, although the actual expanded leaf area ($LAI^{\phi}$) and dead leaf area may vary if the species is winter deciduous.


**Meteorology**

The minimum weather variables required to run the model are min/max temperatures ($T_{min}$ and $T_{max}$), min/max relative humidity ($RH_{min}$ and $RH_{max}$), precipitation ($P$) and solar radiation ($Rad$). Wind speed ($u$) is also needed, but the user may use missing values if not available (a default value will be used in this case). Wind speed is assumed to have been measured at a specific height above the canopy (by default at 2 m). Atmospheric $CO_2$ concentration ($C_{atm}$) may also be specified, but if missing a default constant value is assumed, which is taken from the control parameters. Definitions and units of these variables were given in section \@ref(meteoinput).


### Vegetation functional parameters {#advancedwatervegetationparameters}

The advanced water balance model requires many functional parameters to be specified for plant cohorts. A first set of parameters refers to leaf phenology (`paramsPhenology`):

| Symbol | Units | R  | Description                                  | 
|--------|-------|----| ---------------------------------------------|
|        |       |  `PhenologyType`  | Leaf phenology type (oneflush-evergreen, progressive-evergreen, winter-deciduous, winter-semideciduous)|
| $LD$ | years  | `LeafDuration` | Average duration of leaves (in years). |
| $S^*_{eco}$ | $^{\circ} \mathrm{C}$ | `Sgdd` | Degree days corresponding to leaf budburst (see section \@ref(leafphenobudburst)). |
| $T_{eco}$ | $^{\circ} \mathrm{C}$ | `Tbgdd` | Base temperature for the calculation of degree days to leaf budburst (see section \@ref(leafphenobudburst)). |
| $S^*_{sen}$ | $^{\circ} \mathrm{C}$ | `Ssen` | Degree days corresponding to leaf senescence (see section \@ref(leafphenosenescence)). |
| $Ph_{sen}$ | hours | `Phsen` | Photoperiod corresponding to start counting senescence degree-days (see section \@ref(leafphenosenescence)). |
| $T_{sen}$ | $^{\circ} \mathrm{C}$ | `Tbsen` | Base temperature for the calculation of degree days to leaf senescence (see section \@ref(leafphenosenescence)). |

A second set of functional parameters relate to light extinction and water interception (`paramsInterception`):

| Symbol | Units | R  | Description                                  | 
|--------|-------|----| ---------------------------------------------|
| $\lambda_{leaf}$ | degrees | `LeafAngle` | The (average) angle between the leaf plane and the horizontal plane (i.e. leaf zenith angle) |
| $k_{PAR}$ | (unitless) | `kPAR` | Extinction coefficient for diffuse PAR |
| $\alpha_{SWR}$ | [0-1] | `alphaSWR` | Short-wave radiation leaf absorbance coefficient |
| $\gamma_{SWR}$ | [0-1] |`gammaSWR` | Short-wave radiation leaf reflectance (albedo) |
| $s_{water}$ | $mm\,H_2O·LAI^{-1}$ | `g` | Crown water storage capacity (i.e. depth of water that can be retained by leaves and branches) per LAI unit |

A third set includes parameters related to plant anatomic and morphological attributes (`paramsAnatomy`):

| Symbol | Units | R param | Description                             |
|--------|-------|---------|-----------------------------------------|
| $H_{med}$  | $cm$ | `Hmed` | Median plant height |
| $1/H_{v}$  | $m^2 \cdot m^{-2}$ | `Al2As` | Ratio of leaf area to sapwood area |
|  $LW$   | $cm$  | `LeafWidth` | Leaf width |
| $SLA$  | $m^2 \cdot kg^{-1}$ | `SLA` | Specific leaf area |
| $\rho_{leaf}$ | $g \cdot cm^{-3}$ | `LeafDensity` | Leaf tissue density |
| $\rho_{wood}$ | $g \cdot cm^{-3}$ | `WoodDensity` | Wood tissue density |
| $\rho_{fineroot}$ | $g \cdot cm^{-3}$ | `FineRootDensity` | Fine root tissue density |
| $SRL$ | $cm \cdot g^{-1}$ | `SRL` | Specific root length |
| $RLD$ | $cm \cdot cm^{-3}$ | `RLD` | Fine root length density (i.e. density of root length per soil volume) |
| $r_{6.35}$ | | `r635` | Ratio between the weight of leaves plus branches and the weight of leaves alone for branches of 6.35 mm |

A fourth set of parameters are related to transpiration and photosynthesis (`paramsTranspiration`):

| Symbol | Units | R param | Description                             |
|--------|-------|---------|-----------------------------------------|
| $g_{swmin}$ | $mol\, H_2O \cdot s^{-1} \cdot m^{-2}$ | `Gwmin` | Minimum stomatal conductance to water vapour |
| $g_{swmax}$ | $mol\, H_2O \cdot s^{-1} \cdot m^{-2}$ | `Gwmax` | Maximum stomatal conductance to water vapour |
| $J_{max, 298}$ | $\mu mol\, e \cdot m^{-2} \cdot s^{-1}$ | `Jmax298` | Maximum rate of electron transport at 298K |
| $V_{max, 298}$ | $\mu mol\, CO_2 \cdot s^{-1} \cdot m^{-2}$ | `Vmax298` | Rubisco's maximum carboxylation rate at 298K |
| $K_{stem,max,ref}$ | $kg \cdot s^{-1} \cdot m^{-1} \cdot MPa^{-1}$ | `Kmax_stemxylem` | Maximum stem sapwood reference conductivity per leaf area unit |
| $K_{root,max,ref}$ | $kg \cdot s^{-1} \cdot m^{-1} \cdot MPa^{-1}$ | `Kmax_rootxylem` | Maximum root sapwood reference conductivity per leaf area unit |
| $k_{leaf, \max}$ | $mmol \cdot s^{-1} \cdot m^{-2} \cdot MPa^{-1}$ | `VCleaf_kmax` | Maximum leaf conductance (per leaf area unit) |
| $k_{stem, \max}$ | $mmol \cdot s^{-1} \cdot m^{-2} \cdot MPa^{-1}$ | `VCstem_kmax` | Maximum stem conductance (per leaf area unit) |
| $k_{root, \max,s}$ | $mmol \cdot s^{-1} \cdot m^{-2} \cdot MPa^{-1}$ | `VCroot_kmax` | Maximum root conductance (per leaf area unit) for each soil layer |
|$k_{rhizo,\max, s}$ | $mmol \cdot s^{-1} \cdot m^{-2} \cdot MPa^{-1}$ | `VGrhizo_kmax` | Maximum hydraulic conductance of the rhizosphere for each soil layer |
| $c_{leaf}$, $d_{leaf}$ | (unitless), MPa | `VCleaf_c`, `VCleaf_d` | Parameters of the vulnerability curve for leaves (Weibull) |
| $\Psi_{50, leaf}$, $slope_{leaf}$ | MPa, %/MPa | `VCleaf_P50`, `VCleaf_slope` | Parameters of the vulnerability curve for leaves (Sigmoid) |
| $c_{stem}$, $d_{stem}$ | (unitless), MPa | `VCstem_c`, `VCstem_d` | Parameters of the vulnerability curve for stem xylem (Weibull) |
| $\Psi_{50,stem}$, $slope_{stem}$ | MPa, %/MPa | `VCstem_P50`, `VCstem_slope` | Parameters of the vulnerability curve for stem xylem (Sigmoid) |
| $c_{root}$, $d_{root}$ | (unitless), MPa | `VCroot_c`, `VCroot_d` | Parameters of the vulnerability curve for root xylem (Weibull) |
| $\Psi_{50,root}$, $slope_{root}$ | MPa, %/MPa | `VCroot_P50`, `VCroot_slope` | Parameters of the vulnerability curve for root xylem (Sigmoid) |
| $T_{gs, optim}$ |  $^{\circ} \mathrm{C}$ | `Gs_Toptim`| Temperature corresponding to maximal stomatal conductance (Sureau sub-model) |
| $T_{gs, sens}$ | | `Gs_Tsens` | Stomatal sensitivity to temperature (Sureau sub-model) |
| $m_{wue}$ | | `Gsw_AC_slope` | Slope of the Gsw vs Ac/Cs relationship (Sureau sub-model, see \@ref(stomatalconductancesureau)) |
| $\Psi_{50,gs}$ | MPa | `Gs_P50`| Water potential causing 50% reduction in stomatal conductance (Sureau sub-model) |
| $slope_{gs}$ | %/MPa | `Gs_slope` | Rate of decrease in stomatal conductance at $\Psi_{50,gs}$ (Sureau sub-model) |

It is important to mention that stem- and root-level hydraulic conductances (i.e. $k_{stem, \max}$ and $k_{root, \max}$) are not given as inputs by the user, but are the result from scaling tissue-level conductivity parameters (i.e. $K_{stem,max,ref}$ and $K_{root,max,ref}$) according to plant size (see \@ref(scalingkstem) and \@ref(scalingkroot) for details). Similarly, parameters of Weibull vulnerability curves are estimated from the input in form of $\Psi_{50}$, $\Psi_{12}$ and $\Psi_{88}$ available in `SpParams`. The $slope$ of the Sigmoid vulnerability curves can also be estimated from the same values, or provided by the user directly as a column in `SpParams`.

A fifth (final) set of parameters are related to water storage and water relations in plant tissues (`paramsWaterStorage`):

| Symbol | Units | R  | Description                                  | 
|--------|-------|----| ---------------------------------------------|
| $LFMC_{\max}$ | % | `maxFMC` | Maximum live fuel moisture content, corresponding to fine fuels (< 6.35 mm twigs and leaves). |
| $\epsilon_{leaf}$ | MPa | `LeafEPS` | Modulus of elasticity of leaves |
| $\epsilon_{stem}$ | MPa | `StemEPS` | Modulus of elasticity of symplastic xylem tissue |
| $\pi_{0,leaf}$ | MPa | `LeafPI0` | Osmotic potential at full turgor of leaves |
| $\pi_{0,stem}$ | MPa | `StemPI0` | Osmotic potential at full turgor of symplastic xylem tissue |
| $f_{apo,leaf}$ | [0-1] | `LeafAF` | Apoplastic fraction in leaf tissues |
| $f_{apo,stem}$ | [0-1] | `StemAF` | Apoplastic fraction in stem tissues |
| $V_{leaf}$ | $l \cdot m^{-2}$ | `Vleaf` | Leaf water capacity per leaf area unit |
| $V_{sapwood}$ | $l \cdot m^{-2}$ | `Vsapwood` | Sapwood water capacity per leaf area unit |

Vegetation functional attributes are normally filled for each cohort by function `spwbInput()` from species identity. However, different parameters can be specified for different cohorts of the same species if desired (see section \@ref(functionaltraits)). 

### Control parameters {#advancedwaterbalancecontrol}

Control parameters modulate the overall behaviour of water balance simulations (see section \@ref(controlparameters)). There are three **key control parameters**:

1. `transpirationMode` defines the transpiration model. If `transpirationMode = "Sperry"` or `transpirationMode = "Sureau"` then the advanced water balance model is run with the corresponding plant hydraulics and stomatal regulation sub-models. In advanced water balance models, the water retention curve model is forced to be that of Van Genuchten, i.e. `soilFunctions = "VG"` (see section \@ref(waterretentioncurves)). 
2. `multiLayerBalance` is a boolean flag to indicate that multi-layer energy balance is desired (by default `multiLayerBalance = FALSE`).


Other relevant control parameters relevant for the advanced water balance model are:

+ `ndailysteps [= 24]`: Number of steps into which each day is divided for determination of soil water balance, stomatal conductance, transpiration and photosynthesis (24 equals 1-hour intervals).
+ `nsubsteps_canopy [= 3600]`:  Defines the number of substeps for multi-layer energy balance calculations. By default, substeps are 1 sec if `ndailysteps = 24`.
+ `soilDomains [="buckets"]`: Either `"buckets"` (for multi-bucket model), `"single"` (for single-domain Richards model) and `"dual"` (for dual-permeability model). See \@ref(soilflows).
+ `max_nsubsteps_soil [= 300]`: Maximum number of substeps for soil water balance solving.
+ `defaultWindSpeed [= 2.5]`: Default value for wind speed (in $m \cdot s^{-1}$) when this is missing (only used for leaf fall, see section \@ref(leafphenology)).
+ `defaultCO2 [=386]`: Default atmospheric (abovecanopy) $CO_2$ concentration (in micromol $CO_2 \cdot mol^{-1}$ = ppm). This value will be used whenever $CO_2$ concentration is not specified in the weather input.
+ `defaultRainfallIntensityPerMonth [= c(1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 5.6, 5.6, 5.6, 5.6, 5.6, 1.5)]`: A vector of twelve values indicating the rainfall intensity (mm/h) per month. By default synoptic storms (1.5 mm/h) are assumed between December and June, and convective storms (5.6 mm/h) are assumed between July and November [@Miralles2010].
+ `snowpack [= TRUE]`:  Whether dynamics of snow pack are included (see section \@ref(snowpack)).
+ `leafPhenology [= TRUE]`:  Whether leaf phenology is simulated for winter-deciduous species (see section \@ref(leafphenology)). If `FALSE` then all species are assumed to be evergreen.
+ `bareSoilEvaporation [= TRUE]`:  Whether evaporation from the soil surface is simulated (see section \@ref(soilevaporation)).
+ `interceptionMode [= "Gash1995"]`: Infiltration model, either "Gash1995" or "Liu2001"; see section \@ref(interception).
+ `infiltrationMode [= "GreenAmpt1911"]`: Infiltration model, either "GreenAmpt1911" or "Boughton1989"; see section \@ref(infiltration).
+ `sapFluidityVariation [= TRUE]`: Flag to indicate that temperature affects sap fluidity (see \@ref(sapviscosity)).
+ `windMeasurementHeight [= 200]`: Distance (in cm) above the top of the canopy corresponding to the measurement of wind speed.
+ `boundaryLayerSize [= 2000]`: Size of the canopy boundary layer (in cm). The boundary layer causes the model to define vertical layers above the top of the canopy. The parameter is only relevant when multi-layer canopy energy balance is performed.
+ `gCrown0 [= 0.150]`: Reference canopy conductance (in $mol \cdot s^{-1} \cdot m^{-2}$).
+ `unlimitedSoilWater [=FALSE]`: Boolean flag to indicate the simulation of plant transpiration assuming that soil water is always at field capacity.
+ `interceptionMode [= "Gash1995"]`: Infiltration model, either "Gash1995" or "Liu2001".
+ `infiltrationMode [= "Green-Ampt"]`: Infiltration model, either "Green-Ampt" or "Boughton".
+ `rhizosphereOverlap [="total]`: A string indicating the degree of rhizosphere spatial overlap between plant cohorts:
   + `"none"` - no overlap (independent water pools).
   + `"partial"` - partial overlap determined by coarse root volume.
   + `"total"` - total overlap (plants extract from common soil pools).
+ `thermalCapacityLAI [= 1000000]`: Canopy thermal capacitance per LAI unit (see section \@ref(canopycapacitancetemperature)).
+ `verticalLayerSize [= 100]`: The size of vertical layers (in $cm$) for leaf area distribution and light extinction calculations (see section \@ref(leafdistribution)).
+ `segmentedXylemVulnerability [=TRUE]`: If `FALSE` leaf and root vulnerability curves will be equal to those of stem.
+ `leafCavitationRecovery / stemCavitationRecovery [= "annual"]`: A string indicating how to model recovery of xylem conductance  (see section \@ref(cavitationRecovery)). Allowed values are: 
  + `"none"` - no recovery.
  + `"annual"` - complete recovery every first day of the year.
  + `"total"` - instantaneous complete recovery.
  + `"rate"` - following a rate of new leaf or sapwood formation.
+ `cavitationRecoveryMaximumRate [= 0.05]`: Maximum rate of conductance recovery (see section \@ref(cavitationRecovery)).
+ `lfmcComponent [= "fine"]`: Plant component used to estimate LFMC, either "leaf" or "fine" (for fine fuel) (see section \@ref(lfmc)).

A set of parameters is only relevant for `transpirationMode = "Sperry"`:

+ `leafCavitationEffects / stemCavitationEffects [= FALSE/TRUE]`: A flag indicating whether cavitation effects on conductance of leaves and stem are applied. 
+ `numericParams`: A list with parameters for numerical approximation routines:
  + `maxNsteps [= 400]` - Maximum number of steps in supply function.
  + `ntrial [= 200]` - Number of iteration trials when finding root of equation system.
  + `psiTol [= 0.0001]` - Tolerance value for water potential.
  + `ETol [= 0.0001]` - Tolerance value for flow.
  
whereas another set is only relevant for `transpirationMode = "Sureau"`:

+ `plantCapacitance [= TRUE]`: Whether the effect of (symplasmic or apoplasmic) plant water compartments is considered in simulations.
+ `leafCuticularTranspiration [= TRUE]`: Whether the effect of leaf cuticular transpiration is considered in simulations.
+ `stemCuticularTranspiration [= FALSE]`: Whether the effect of stem cuticular transpiration is considered in simulations.
+ `C_SApoInit [= 2.0e-5]`: Maximum capacitance of the stem apoplasm (mmol·m-2).
+ `C_LApoInit [= 1.0e-5]`: Maximum capacitance of the leaf apoplasm (mmol·m-2).
+ `k_SSym [= 0.26]`: Conductance from stem apoplasm to stem symplasm (mmol·s-1·m-2).
+ `k_LSym [= 2.0]`: Conductance from leaf apoplasm to leaf symplasm (mmol·s-1·m-2).
+ `gs_NightFrac [= 0.05]`: Stomatal conductance at night as fraction of maximum stomatal conductance ([0-1]).
+ `stomatalSubmodel [= "Baldocchi"]`: Stomatal regulation sub-model, either "Jarvis" or "Baldocchi".
+ `JarvisPAR [= 0.003]`: Parameter regulating the response of stomatal conductance to light (PAR) in the Jarvis model.
+ `fTRBToLeaf [= 0.8]`: Fraction of surface of bark exposed to air per leaf area.

Finally, a number of control parameters are used to modify how hydraulic parameters are estimated when calling function `spwbInput()`: 

+ `taper [= TRUE]`: Whether taper of xylem conduits is accounted for when estimating aboveground stem conductance from xylem conductivity.
+ `fracRootResistance [= 0.40]`: Fraction of plant total resistance (leaf+stem+root) that corresponds to root system. 
+ `averageFracRhizosphereResistance [= 0.15]`: Fraction to total continuum (stem+root+rhizosphere) resistance that corresponds to rhizosphere (averaged across soil water potential values).


### Model output {#advancedwaterbalanceoutput}

#### Daily output

Functions `spwb()` and `pwb()` with `transpirationMode = "Sperry"` or `transpirationMode = "Sureau"` return a list of a class with the same name. The first four elements of this list (i.e., `latitude`, `topography`, `weather` and `spwbInput`) are simply copies of model inputs. The next element is `spwbOutput`, which contains the state of the input object at the end of the simulation (this can be used to perform further simulations starting with current values of state variables). The remainng elements are:

| Element | Description                                                |
|---------|------------------------------------------------------------|
| `WaterBalance`| Climatic input and water balance flows (i.e. net precipitation, infiltration, runoff, transpiration...). All of them in $mm = l \cdot m^{-2}$. |
| `EnergyBalance` | Energy balance components (instantaneous values) for the soil and the canopy |
| `Temperature` | Minimum and maximum temperature values for topsoil, canopy and atmosphere. Only returned if `temperatureResults = TRUE`. |
| `Soil`| Soil variables for each soil layer: Moisture relative to field capacity ($W_s$), water potential ($\Psi_s$) and volumetric water content ($V_s$). Only returned if `soilResults = TRUE`. |
| `Stand`| Stand-level variables, such as $LAI^{\phi}_{stand}$, $LAI^{dead}_{stand}$, the water retention capacity of the canopy ($S_{canopy}$) or the fraction of light reaching the ground ($L^{PAR}_{ground}$ and $L^{SWR}_{ground}$). Only returned if `standResults = TRUE`.|
| `Plants`| Plant-level variables, such as $LAI^{phi}_i$, plant transpiration, plant water potential, etc. Only returned if `plantResults = TRUE`.|
| `SunlitLeaves` | Leaf-level output variables for sunlit leaves. Only returned if `leafResults = TRUE`.|
| `ShadeLeaves` | Leaf-level output variables for shade leaves. Only returned if `leafResults = TRUE`.|
| `FireHazard`| Fire hazard variables (fuel moisture, rate of spread, fire potentials, etc). Only returned if `fireHazardResults = TRUE`. |

Compared to the output of the basic water balance \@ref(basicwaterbalanceoutput), new output elements are produced. Many results are given as sub-elements of `Plants`, each of them a data frame with dates in rows and plant cohorts in columns:

| Element | Symbol    | Units | Description                               |
|---------|-----------|-------|-------------------------------------------|
|`LAI`| $LAI^{\phi}$ | $m^2 \cdot m^{-2}$ | Leaf area index (expanded).|
|`LAIlive`| $LAI^{live}$ | $m^2 \cdot m^{-2}$ | Leaf area index (live).|
|`AbsorbedSWR` |  | MJ | Shortwave radiation absorbed per ground area.|
|`AbsorbedLWR` |  | MJ | Longwave radiation absorbed per ground area.|
|`Transpiration`| $Tr$ | mm | Transpiration per ground area.|
|`GrossPhotosynthesis`| $A_{g}$ | $g\,C \cdot m^{-2}$ | Gross photosynthesis per ground area.|
|`NetPhotosynthesis`| $A_{n}$ | $g\,C \cdot m^{-2}$ | Net photosynthesis per ground area.|
| `dEdP` | $dE/d\Psi_{leaf}$ | $mmol \cdot s^{-1} \cdot m^{-2} \cdot MPa^{-1}$ | Derivative of the (aboveground) supply function. |
| `PlantWaterBalance` | | mm | Internal daily plant water balance (balance of soil extraction and transpiration). |
| `LeafPsiMin`| $\Psi_{md}$ | MPa | Minimum (midday) 'average leaf' water potential. |
| `LeafPsiMax`| $\Psi_{pd}$ | MPa | Maximum (predawn) 'average leaf' water potential. |
| `StemPsi`| $\Psi_{stem}$ | MPa | Minimum stem water potential. |
| `RootPsi`| $\Psi_{rootcrown}$ | MPa | Minimum root-crown water potential. |
| `RhizoPsi`| $\Psi_{rootsurf,s}$ | MPa | Minimum root surface water potential for each soil layer. |
| `LeafPLC`| $PLC_{leaf}$ | MPa | Proportion of leaf conductance loss. |
| `StemPLC`| $PLC_{stem}$ | MPa | Proportion of stem conductance loss. |
| `LeafRWC`| $RWC_{leaf}$ | % | Mean leaf relative water content. |
| `StemRWC`| $RWC_{stem}$ | % | Mean stem relative water content. |
| `LFMC`| $LFMC$ | % | Live fuel moisture content (as percent of dry weight), corresponding to fine fuels (< 6.35 mm twigs and leaves). |
| `PlantStress` | $DDS$ | [0-1] | Drought stress level suffered by each plant cohort (relative whole-plant conductance).|

The following table describes the child elements of `SunlitLeaves` and `ShadeLeaves`, each of them a data frame with dates in rows and plant cohorts in columns:

| Element | Symbol | Units | Description                               |
|---------|--------|-------|-------------------------------------------|
| `LeafPsiMin`|$\Psi_{md, i}^{sunlit}$, $\Psi_{md, i}^{shade}$ | MPa | Minimum (midday) (sunlit or shade) leaf water potential. |
| `LeafPsiMax`| $\Psi_{pd, i}^{sunlit}$, $\Psi_{pd, i}^{shade}$| MPa | Maximum (predawn) (sunlit or shade) leaf water potential. |
| `TempMin`| $T_{leaf, \min}^{sunlit}$, $T_{leaf,\min}^{shade}$|  $^{\circ} \mathrm{C}$ | Minimum leaf temperature. |
| `TempMax`| $T_{leaf, \max}^{sunlit}$, $T_{leaf,\max}^{shade}$|  $^{\circ} \mathrm{C}$ | Maximum leaf temperature. |
| `GSWMin`| $g_{w,i}^{sunlit}$, $g_{w,i}^{shade}$| $mol \cdot s^{-1} \cdot m^{-2}$ | Minimum stomatal conductance to water vapour. |
| `GSWMax`| $g_{w,i}^{sunlit}$, $g_{w,i}^{shade}$| $mol \cdot s^{-1} \cdot m^{-2}$ | Maximum stomatal conductance to water vapour. |

The output of simulations can be inspected using `plot`, `shinyplot` and `summary` functions specific to `spwb` objects (examples are given in the corresponding package *vignette*).

#### Sub-daily output

Calling function `spwb_day()` with the advanced water balance model results in sub-daily results for the simulated date. When running the advanced water balance model with function `spwb()` one can request sub-daily results to be included with the function output. This is done via setting  `subdailyResults = TRUE` in the control parameter list. In that case, the output list of `spwb()` will include an element `subdaily`, whose sub-elements correspond to the results of `spwb_day()` for each date simulated. Refer to the documentation of functions `spwb_day()` and `transp_transpirationSperry()` or `transp_transpirationSureau()` for details of sub-daily output.