Chapter 7 Advanced water balance model

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 Sperry et al. (2017) and were described in detail in De Cáceres et al. (2021).
  • If transpirationMode = "Cochard", the sub-models of plant hydraulics and stomatal conductance follow SurEau-ECOS and were described in Ruffault et al. (2022).

The following model overview is structured as in chapter 3. 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 sub-modules that are exclusive of the advanced model. Whenever necessary, we will detail the difference between the two sub-models of plant hydraulics and stomatal conductance corresponding to De Cáceres et al. (2021) and Ruffault et al. (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 a background on the processes implemented to fully understand and exploit model outputs. Since the scope of this book is focused on the model, interested readers should address relevant eco-physiological bibliography complement the material exposed here.

7.1 Design principles

The 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. Soil water balance is 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.

Hydrological processes are the same as in chapter 3. Thus, the model includes water interception loss (Gash et al. 1995; Liu 2001), plant transpiration, evaporation from soil (Ritchie 1972), transpiration of the herbaceous layer, partition between infiltration and runoff (Green & Ampt 1911; Boughton 1989), Darcian vertical water movement (Bonan 2019) and deep drainage.

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 3, 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.

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 (De Pury & Farquhar 1997). 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 model of Anten & Bastiaans (2016). The scheme for long-wave radiation transfer between the atmosphere, the different canopy layers and the soil follows the SHAW model (Flerchinger et al. 2009).

Energy balances are conducted at two levels: the canopy (or canopy layers) level and the leaf level. 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. (2011) for JULES. Alternatively, energy balance can be conducted for each vertical layer following Bonan et al. (2014). 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 (Ma & Liu 2019), determined using a canopy turbulence model by Katul et al. (2004).

The model also performs the energy balance at the leaf level to determine transpiration. At this 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) level. 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. (1998) model, and stomatal regulation follows the profit maximization approach of Sperry et al. (2017).

  • If transpirationMode = "Cochard", plant water compartments are always included, and water flows follow Darcy’s law, as described in Ruffault et al. (2022). In this case, stomatal regulation follows a 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. water sources corresponding to 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.

7.2 State variables

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 4.1).
  • 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 (which can happen if deep drainage is not allowed).
  • 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 7.5.3):

  • If transpirationMode = "Cochard", 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\}\):
    1. Air temperature, \(T_{air,j}\)
    2. Water vapor pressure, \(e_{air,j}\)
    3. \(CO_2\) concentration, \(C_{air,j}\).

7.3 Water and energy balances

7.3.1 Water balance

Daily variations in soil water content (\(\Delta{V_{soil}}\) in mm) can be summarized as:

\[\begin{equation} \Delta{V_{soil}} = Pr + Sm - In - Ru - Dd - Es - Tr_{herb} - Ex_{woody} \tag{7.1} \end{equation}\]

where \(Pr\) is precipitation as rainfall, \(Sm\) is water reaching the soil from snow melt (if snow-pack dynamics are considered), \(In\) is the interception loss (i.e., water evaporated after being intercepted by the canopy), \(Ru\) is surface runoff, \(Dd\) is deep drainage (i.e. water percolated to layers beyond soil depth), \(Es\) is evaporation from soil surface, \(Tr_{herb}\) is the transpiration of the herbaceous layer and \(Ex_{woody}\) is soil water extraction done by woody plants.

Although the advanced water balance model includes hydraulic redistribution, this does not change the total amount of water in the soil, so the water balance equation is is very similar to that of the basic water balance model (eq.(3.1)). Soil water extraction (\(Ex_{woody}\)) and plant transpiration (\(Tr_{woody}\)) will be equal if 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} \tag{7.2} \end{equation}\]

While the above describes the default water balance equation, variations can occur depending on specific control flags:

  1. If snow dynamics are considered, the water balance of the snow pack is defined as: \[\begin{equation} \Delta{S_{snow}} = Ps - Sm \end{equation}\] where \(Ps\) is precipitation as snowfall and \(Sm\) is snow melt. Evaporation from bare soil cannot occur if there is a snow pack over the soil surface (i.e., if \(S_{snow}>0\) then \(Es = 0\)).
  2. If plant water pools are considered, the water balance equation applies not only to the soil of the overall stand but also to the soil beneath each plant cohort. The fraction of stand area covered by each cohort is used to keep the water balance at the two scales aligned. Moreover, the water balances of soils beneath the different plant cohort are more or less correlated depending on root overlap.

Unlike the basic water balance, in this model water balance components contributing to latent heat (\(Es\), \(Tr_{woody}\), \(Tr_{herb}\), \(In\) and \(Sm\)) are included in the energy balance equations of the canopy and soil, therefore coupling water and energy balances.

7.3.2 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 (Best et al. 2011). 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}\)). Finally, energy is released from the canopy to the atmosphere through latent heat (\(LE_{can}\)) produced via transpiration (\(Tr\)) and evaporation of water intercepted by the canopy (\(In\)). 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_{can} - H_{can,atm} - H_{can,soil} \tag{7.3} \end{equation}\] where \(TC_{can}\) is the canopy thermal capacitance (in \(J \cdot m^{-2} \cdot K^{-1}\)).

7.3.3 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 (Ma & Liu 2019). 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_{j} + H_{j} \tag{7.4} \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_{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\).

7.3.4 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 (\(LE_{soil}\)), which includes snow melt (\(Sm\)) and evaporation from the soil surface (\(Es\)). 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_{soil} - G_{1,2} \tag{7.5} \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. (7.5), 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} \tag{7.6} \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 Best et al. (2011), 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 5.2) 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 5.5).

7.4 Process scheduling

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

  1. Update leaf area values according to the phenology of species and recalculate radiation extinction (sections 4.1 and 4.2).
  2. Determine rainfall interception loss (\(In\)) and net rainfall (\(Pr_{net}\)) (section 5.3). 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 5.2).
  3. Divide the amount of water reaching the soil surface from the rainfall event between infiltration and surface runoff (\(Ru\)) (section 5.4). Determine the infiltration reaching each soil layer.
  4. Determine bare soil evaporation (\(Es\)), if snow is not present (section 5.5), and herbaceous transpiration (\(Tr_{herb}\); section 5.6).
  5. Determine sub-daily air temperature and direct/diffuse irradiance variations (chapter 8).
  6. Determine the proportion of sunlit/shade leaves (section 9.1.2), the shortwave radiation absorbed by plant cohorts (sections 9.1.3 and the soil (section 9.1.4) at sub-daily steps.
  7. If transpirationMode = "Sperry", update the water supply function of each plant cohort, according to the hydraulic model and the current soil water potential (chapter 10).
  8. Determine instantaneous plant cohort transpiration, photosynthesis rates and close soil/canopy energy balance at sub-daily steps (chapters 12 and 13). This involves the following actions for each sub-daily step:
    1. Determine long-wave radiation exchange between soil, canopy layers and atmosphere (section 9.2).

    2. If transpirationMode = "Sperry", for each woody cohort:

      1. 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 11.1). If plant capacitance effects are considered this concerns the stem-to-leaf hydraulic supply function.
      2. Determine stomatal conductance, transpiration and photosynthesis on shade and sunlit leaves of each plant cohort according to Sperry’s (2017) profit maximization strategy (section 12.1.2).
    3. If transpirationMode = "Cochard", for each plant cohort repeat the following in small sub-steps (e.g. 10 min):

      1. Perform energy balance of sunlit and shade leaves (section 11.1), according to the current transpiration flow.
      2. Re-estimate leaf and stem cuticular transpiration.
      3. Re-estimate stomatal regulation, transpiration and photosynthesis for sunlit and shade leaves.
      4. Update water potentials, flows and conductances across the hydraulic network.
    4. Scale transpiration (\(Tr_{woody}\)) and net photosynthesis (\(A_n\)) from sunlit/shade leaves to the plant cohort level (section 12.3).

    5. Scale water extraction from soil layers (\(Ex_{woody}\)) to the woody plant cohort level.

    6. 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 13).

  9. Determine day-level photosynthesis and transpiration from instantaneous rates and update soil moisture (section 14.1). Determine drought stress for each woody plant cohort (section 14.3).
  10. Determine 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 5.7). This updates soil moisture and lower boundary condition of water movement corresponds to deep drainage (\(Dd\)).
  11. If fire hazard calculations are requested, estimate live and dead fuel moisture and potential fire behaviour (chapter 24).

Steps 1-4 are the same as described in the basic model, and steps 10-11 here correspond to steps 6-7 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 11 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 and 4 are performed for each water pool separately because they depend on antecedent soil moisture. Steps 7-9 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 6.1.5). Soil water flows from these three steps are then averaged at the stand level. After that, Step 10 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.

7.5 Inputs and outputs

7.5.1 Soil, vegetation and meteorology


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


Vegetation input requirements were fully described in section 2.4. 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.


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 2.5.

7.5.2 Vegetation functional parameters

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 4.1.2).
\(T_{eco}\) \(^{\circ} \mathrm{C}\) Tbgdd Base temperature for the calculation of degree days to leaf budburst (see section 4.1.2).
\(S^*_{sen}\) \(^{\circ} \mathrm{C}\) Ssen Degree days corresponding to leaf senescence (see section 4.1.3).
\(Ph_{sen}\) hours Phsen Photoperiod corresponding to start counting senescence degree-days (see section 4.1.3).
\(T_{sen}\) \(^{\circ} \mathrm{C}\) Tbsen Base temperature for the calculation of degree days to leaf senescence (see section 4.1.3).

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 (Cochard sub-model)
\(T_{gs, sens}\) Gs_Tsens Stomatal sensitivity to temperature (Cochard sub-model)
\(\Psi_{50,gs}\) MPa Gs_P50 Water potential causing 50% reduction in stomatal conductance (Cochard sub-model)
\(slope_{gs}\) %/MPa Gs_slope Rate of decrease in stomatal conductance at \(\Psi_{50,gs}\) (Cochard 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 A.4.1 and A.4.3 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() or forest2spwbInput() from species identity. However, different parameters can be specified for different cohorts of the same species if desired (see section 2.4.9).

7.5.3 Control parameters

Control parameters modulate the overall behaviour of water balance simulations (see section 2.6). There are three key control parameters:

  1. transpirationMode defines the transpiration model. If transpirationMode = "Sperry" or transpirationMode = "Cochard" 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 2.3.2).
  2. ndailysteps defines the number of daily steps. By default ndailysteps = 24, so that steps are hours, but users can increase the temporal resolution, for example to half hour substeps by setting ndailysteps = 48.
  3. multiLayerBalance is a boolean flag to indicate that multi-layer energy balance is desired (by default multiLayerBalance = FALSE).
  4. nsubsteps defines the number of substeps for multi-layer energy balance calculations. By default nsubsteps = 3600, so that substeps are 1 sec if ndailysteps = 24.

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

  • defaultWindSpeed [= 2.5]: Default value for wind speed (in \(m \cdot s^{-1}\)) when this is missing (only used for leaf fall, see section 4.1).
  • 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 (Miralles et al. 2010).
  • snowpack [= TRUE]: Whether dynamics of snow pack are included (see section 5.2).
  • leafPhenology [= TRUE]: Whether leaf phenology is simulated for winter-deciduous species (see section 4.1). If FALSE then all species are assumed to be evergreen.
  • bareSoilEvaporation [= TRUE]: Whether evaporation from the soil surface is simulated (see section 5.5).
  • interceptionMode [= "Gash1995"]: Infiltration model, either “Gash1995” or “Liu2001”; see section 5.3.
  • infiltrationMode [= "GreenAmpt1911"]: Infiltration model, either “GreenAmpt1911” or “Boughton1989”; see section 5.4.
  • sapFluidityVariation [= TRUE]: Flag to indicate that temperature affects sap fluidity (see 10.2.3).
  • 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.
  • 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 13.1.3).
  • verticalLayerSize [= 100]: The size of vertical layers (in \(cm\)) for leaf area distribution and light extinction calculations (see section 2.4.6).
  • segmentedXylemVulnerability [=TRUE]: If FALSE leaf and root vulnerability curves will be equal to those of stem.
  • cavitationRefillStem/cavitationRefillLeaves [= "annual"]: A string indicating how refilling of embolized conduits is done (see section 12.4. Allowed values are:
    • "none" - no refilling.
    • "annual" - every first day of the year.
    • "total" - instantaneous complete refilling.
    • "rate" - following a rate of new sapwood formation.
  • refillMaximumRate [= 0.05]: Maximum rate of conduit refilling (see section 12.4).

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

  • 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 = "Cochard":

  • 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 [= TRUE]: 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]).
  • TPhase_gmin [= 37.5]: Temperature for transition phase of gmin.
  • Q10_1_gmin [= 1.2]: Temperature dependence of gmin when T ≤ TPhase.
  • Q10_2_gmin [= 4.8]: Temperature dependence of gmin when T > TPhase.
  • JarvisPAR [= 0.003]: Parameter regulating the response of stomatal conductance to light (PAR) in the Jarvis model.
  • gCrown0 [= 0.150]: Reference crown conductance (mol·s-1·m-2).
  • 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).

7.5.4 Model output Daily output

Functions spwb() and pwb() with transpirationMode = "Sperry" or transpirationMode = "Cochard" 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
Soil Soil variables for each soil layer: Moisture relative to field capacity (\(W_s\)), water potential (\(\Psi_s\)) and volumetric water content (\(V_s\)).
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}\)).
Plants Plant-level variables, such as \(LAI^{phi}_i\), plant transpiration, plant water potential, etc.
SunlitLeaves Leaf-level output variables for sunlit leaves.
ShadeLeaves Leaf-level output variables for shade leaves.
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 3.5.4, 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_transpirationCochard() for details of sub-daily output.


Anten, N.P.R. & Bastiaans, L. (2016). The use of canopy models to analyze light competition among plants. In: Canopy photosynthesis: From basics to application (eds. Hikosaka, K., Niinemets, Ü. & Anten, N.P.R.). Springer, pp. 379–398.
Best, M.J., Pryor, M., Clark, D.B., Rooney, G.G., Essery, R.L.H., Ménard, C.B., et al. (2011). The Joint UK Land Environment Simulator (JULES), model description – Part 1: Energy and water fluxes. Geoscientific Model Development, 4, 677–699.
Bonan, G. (2019). Climate change and terrestrial ecosystem modeling. Cambridge University Press, Cambridge, UK.
Bonan, G.B., Williams, M., Fisher, R.A. & Oleson, K.W. (2014). Modeling stomatal conductance in the earth system: Linking leaf water-use efficiency and water transport along the soil-plant-atmosphere continuum. Geoscientific Model Development, 7, 2193–2222.
Boughton, W. (1989). A review of the USDA SCS curve number method. Australian Journal of Soil Research, 27, 511–523.
De Cáceres, M., Mencuccini, M., Martin-StPaul, N., Limousin, J.-M., Coll, L., Poyatos, R., et al. (2021). Unravelling the effect of species mixing on water use and drought stress in Mediterranean forests: A modelling approach. Agricultural and Forest Meteorology, 296, 108233.
De Pury, D.G.G. & Farquhar, G.D. (1997). Simple scaling of photosynthesis from leaves to canopies without the errors of big-leaf models. Plant, Cell and Environment, 20, 537–557.
Flerchinger, G.N., Xiao, W., Sauer, T.J. & Yu, Q. (2009). Simulation of within-canopy radiation exchange. NJAS - Wageningen Journal of Life Sciences, 57, 5–15.
Gash, J., Lloyd, C. & Lachaud, G. (1995). Estimating sparse forest rainfall interception with an analytical model. Journal of Hydrology, 170.
Genuchten, M.V. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44, 892–898.
Green, H.W. & Ampt, G.A. (1911). Studies on Soil Physics. The Journal of Agricultural Science, 4, 1–24.
Katul, G.G., Mahrt, L., Poggi, D. & Sanz, C. (2004). One- and two-equation models for canopy turbulence. Boundary-Layer Meteorology, 113, 81–109.
Liu, S. (2001). Evaluation of the Liu model for predicting rainfall interception in forests world-wide. Hydrological Processes, 15, 2341–2360.
Ma, Y. & Liu, H. (2019). An Advanced Multiple-Layer Canopy Model in the WRF Model With Large-Eddy Simulations to Simulate Canopy Flows and Scalar Transport Under Different Stability Conditions. Journal of Advances in Modeling Earth Systems, 11, 2330–2351.
Miralles, D.G., Gash, J.H., Holmes, T.R.H., Jeu, R.A.M. de & Dolman, A.J. (2010). Global canopy interception from satellite observations. Journal of Geophysical Research, 115, D16122.
Ritchie, J. (1972). Model for predicting evaporation from a row crop with incomplete cover. Water resources research, 8, 1204–1213.
Ruffault, J., Pimont, F., Cochard, H., Dupuy, J.-L. & Martin-StPaul, N. (2022). SurEau-Ecos v2.0: A trait-based plant hydraulics model for simulations of plant water status and drought-induced mortality at the ecosystem level. Geoscientific Model Development, 15, 5593–5626.
Sperry, J.S., Adler, F.R., Campbell, G.S. & Comstock, J.P. (1998). Limitation of plant water use by rhizosphere and xylem conductance: Results from a model. Plant, Cell & Environment, 21, 347–359.
Sperry, J.S., Venturas, M.D., Anderegg, W.R.L., Mencuccini, M., Mackay, D.S., Wang, Y., et al. (2017). Predicting stomatal responses to the environment from the optimization of photosynthetic gain and hydraulic cost. Plant, Cell & Environment, 40, 816–830.