API

relative_hydraulic_conductance(vc::ComplexVC{FT}, p_25::FT) where {FT<:AbstractFloat}
relative_hydraulic_conductance(vc::LogisticVC{FT}, p_25::FT) where {FT<:AbstractFloat}

Return the hydraulic conductance ralative to maximum at reference temperature, given

• vc ComplexVC, LogisticVC, PowerVC, or WeibullVC type vulnerability curve
• p_25 Equivalent xylem water pressure at 298.15 K in [MPa] (surface tension correction made)

critical_pressure(vc::ComplexVC{FT}, kr::FT = FT(0.001)) where {FT<:AbstractFloat}
critical_pressure(vc::LogisticVC{FT}, kr::FT = FT(0.001)) where {FT<:AbstractFloat}
critical_pressure(vc::PowerVC{FT}, kr::FT = FT(0.001)) where {FT<:AbstractFloat}
critical_pressure(vc::WeibullVC{FT}, kr::FT = FT(0.001)) where {FT<:AbstractFloat}

Return the critical xylem water pressure at 25 °C that triggers a given amount of loss of conductance, given

• vc ComplexVC, LogisticVC, PowerVC, or WeibullVC type struct
• kr Reference conductance, default is 0.001

xylem_pressure(pv::LinearPVCurve{FT}, rvol::FT, T::FT) where {FT<:AbstractFloat}
xylem_pressure(pv::SegmentedPVCurve{FT}, rvol::FT, T::FT) where {FT<:AbstractFloat}

Return the xylem water pressure in MPa, given

• pv LinearPVCurve or SegmentedPVCurve type pressure volume curve
• rvol Relative volume (relative to maximum)
• T Temperature

capacitance_buffer(pvc::LinearPVCurve{FT}) where {FT<:AbstractFloat}
capacitance_buffer(pvc::SegmentedPVCurve{FT}) where {FT<:AbstractFloat}

Return the relative capacictance buffer rate, given

• pv LinearPVCurve or SegmentedPVCurve type pressure volume curve

clear_legacy!(spac::MonoElementSPAC{FT}) where {FT<:AbstractFloat}
clear_legacy!(spac::MonoMLGrassSPAC{FT}) where {FT<:AbstractFloat}
clear_legacy!(spac::MonoMLPalmSPAC{FT}) where {FT<:AbstractFloat}
clear_legacy!(spac::MonoMLTreeSPAC{FT}) where {FT<:AbstractFloat}
clear_legacy!(organ::Union{Leaf{FT}, Leaves2D{FT}, Root{FT}, Stem{FT}}) where {FT<:AbstractFloat}
clear_legacy!(organ::Leaves1D{FT}) where {FT<:AbstractFloat}

Clear the legacy for hydraulic organ or system, given

• spac MonoElementSPAC, MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type structure
• organ Leaf, Leaves1D, Leaves2D, Root, or Stem type structure

flow_in(organ::Union{Leaf{FT}, Leaves2D{FT}, Root{FT}, Stem{FT}}) where {FT<:AbstractFloat}
flow_in(organ::Leaves1D{FT}) where {FT<:AbstractFloat}
flow_in(organs::Vector{Leaves2D{FT}}) where {FT<:AbstractFloat}
flow_in(organs::Vector{Stem{FT}}) where {FT<:AbstractFloat}

Return the flow rate, given

• organ Leaf, Leaves1D, Leaves2D, Root, or Stem type struct
• organs Vector of Leaves2D or Stem type struct

flow_out(lf::Union{Leaf{FT}, Leaves2D{FT}}) where {FT<:AbstractFloat}

Return the net flow that escape from the leaf, given

• lf Leaf, Leaves2D, Root, or Stem type organ

root_pk(root::Root{FT}) where {FT<:AbstractFloat}

Return the root end pressure and total hydraulic conductance to find solution of flow rates in all roots, given

• root Root type struct

This function is designed to serve the following functionalities:

• Update flow profile in different organs
• Partition root flow rates at different layers
• Update flow profile for entire SPAC

xylem_flow_profile!(organ::Union{Leaf{FT}, Leaves2D{FT}, Root{FT}, Stem{FT}}, Δt::FT) where {FT<:AbstractFloat}
xylem_flow_profile!(organ::Leaves1D{FT}, Δt::FT) where {FT<:AbstractFloat}

Update organ flow rate profile after setting up the flow rate out, given

• organ Leaf, Leaves1D, Leaves2D, Root, or Stem type struct
• Δt Time step length

xylem_flow_profile!(roots::Vector{Root{FT}}, cache_f::Vector{FT}, cache_k::Vector{FT}, cache_p::Vector{FT}, f_sum::FT, Δt::FT) where {FT<:AbstractFloat}

Partition root flow rates at different layers for known total flow rate out, given

• roots Vector of Root in a multiple roots system
• cache_f Flow rate cache into each root
• cache_k Total conductance cache of each root
• cache_p Root xylem end pressure cache of each root
• f_sum Total flow rate out of the roots
• Δt Time step length

xylem_flow_profile!(spac::MonoElementSPAC{FT}, Δt::FT) where {FT<:AbstractFloat}
xylem_flow_profile!(spac::MonoMLGrassSPAC{FT}, Δt::FT) where {FT<:AbstractFloat}
xylem_flow_profile!(spac::MonoMLPalmSPAC{FT}, Δt::FT) where {FT<:AbstractFloat}
xylem_flow_profile!(spac::MonoMLTreeSPAC{FT}, Δt::FT) where {FT<:AbstractFloat}

Update flow profiles for the soil-plant-air continuum (set up leaf flow rate from stomatal conductance first), given

• spac MonoElementSPAC, MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type SPAC system
• Δt Time step length

xylem_end_pressure(organ::Union{Leaf{FT}, Root{FT}, Stem{FT}}, flow::FT) where {FT<:AbstractFloat}
xylem_end_pressure(spac::MonoElementSPAC{FT}, flow::FT) where {FT<:AbstractFloat}

Return the xylem end water pressure in MPa, given

• organ Leaf, Root, or Stem type struct
• flow Flow rate (per leaf area for Leaf) [mol (m⁻²) s⁻¹]
• spac MonoElementSPAC type struct

This function is designed for the following purposes:

• Update organ pressure profile
• Update pressure profile for the entire SPAC

xylem_pressure_profile!(organ::Union{Leaf{FT}, Leaves2D{FT}, Root{FT}, Stem{FT}}; update::Bool = true) where {FT<:AbstractFloat}
xylem_pressure_profile!(organ::Leaves1D{FT}; update::Bool = true) where {FT<:AbstractFloat}

Update xylem pressure profile (flow profile needs to be updated a priori), given

• organ Leaf, Leaves1D, Leaves2D, Root, or Stem type organ
• update If true, update xylem cavitation legacy and leaf critical flow (e_crit)

xylem_pressure_profile!(spac::MonoElementSPAC{FT}; update::Bool = true) where {FT<:AbstractFloat}
xylem_pressure_profile!(spac::MonoMLGrassSPAC{FT}; update::Bool = true) where {FT<:AbstractFloat}
xylem_pressure_profile!(spac::MonoMLPalmSPAC{FT}; update::Bool = true) where {FT<:AbstractFloat}
xylem_pressure_profile!(spac::MonoMLTreeSPAC{FT}; update::Bool = true) where {FT<:AbstractFloat}

Update xylem pressure profile (flow profile needs to be updated a priori), given

• spac MonoElementSPAC, MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type spac
• update If true, update xylem cavitation legacy

∂E∂P(lf::Union{Leaf{FT}, Leaves2D{FT}}, flow::FT; δe::FT = FT(1e-7)) where {FT<:AbstractFloat}
∂E∂P(lf::Leaves1D{FT}, flow::FT, ind::Int; δe::FT = FT(1e-7)) where {FT<:AbstractFloat}

Return the marginal hydraulic conductance, given

• lf Leaf, Leaves1D, or Leaves2D type struct
• flow Flow rate through the leaf xylem [mol m⁻² s⁻¹]
• δe Incremental flow rate, default is 1e-7
• ind Which leaf in Leaves1D (1 for sunlit and 2 for shaded)

This function returns the critical flow rate that triggers a given amount of loss of hydraulic conductance for

• Leaf hydraulic system
• Mono element SPAC system

critical_flow(hs::LeafHydraulics{FT}, T::FT, ini::FT = FT(0.5); kr::FT = FT(0.001)) where {FT<:AbstractFloat}

Return the critical flow rate that triggers a given amount of loss of conductance, given

• hs LeafHydraulics type struct
• T Liquid temperature
• ini Initial guess
• kr Reference conductance, default is 0.001

critical_flow(spac::MonoElementSPAC{FT}, ini::FT = FT(0.5); kr::FT = FT(0.001)) where {FT<:AbstractFloat}

Return the critical flow rate that triggers a given amount of loss of conductance, given

• spac MonoElementSPAC type struct
• ini Initial guess
• kr Reference conductance, default is 0.001

β_factor(f::Function, vc::AbstractXylemVC{FT}, x_25::FT) where {FT<:AbstractFloat}
β_factor(f::Function, vc::AbstractSoilVC{FT}, x_25::FT) where {FT<:AbstractFloat}
β_factor(f::Function, x_25::FT) where {FT<:AbstractFloat}

Return the β factor based on relative conductance or soil potential/pressure, given

• f Function to translate relative k to β, for example f(x) = x, f(x) = x², and f(x) = sqrt(x) for x in [0,1]
• vc Leaf vulnerability curve or soil vulnerability curve (moisture retention curve)
• x_25 Leaf xylem pressure corrected to 25 °C, soil water potential corrected to 25 °C (forcing on roots, note that this function may not be useful for plants with salt stress), or soil water content

This function updates the beta factor for SPAC if empirical models are used. The method is meant to support all SPAC defined in ClimaCache.jl:

• MonoElementSPAC
• MonoMLGrassSPAC
• MonoMLPalmSPAC
• MonoMLTreeSPAC

β_factor!(spac::MonoElementSPAC{FT}) where {FT<:AbstractFloat}

Update the beta factor for the LEAF component in SPAC, given

• spac MonoElementSPAC type SPAC

β_factor!(spac::Union{MonoMLGrassSPAC{FT}, MonoMLPalmSPAC{FT}, MonoMLTreeSPAC{FT}}) where {FT<:AbstractFloat}

Update the β factor for the LEAVES component in SPAC, given

• spac MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type SPAC

Note that if the β function is based on Kleaf or Pleaf, β factor is taken as that of leaf; if the β function is based on Ksoil, Psoil, or Θ, β is taken as the average weighted by flow rate in each root.

This function has two major functionalities:

• Compute marginal energy increase in each organ
• Update the temperature in each organ when time step provided

plant_energy!(spac::MonoMLGrassSPAC{FT}) where {FT<:AbstractFloat}
plant_energy!(spac::MonoMLPalmSPAC{FT}) where {FT<:AbstractFloat}
plant_energy!(spac::MonoMLTreeSPAC{FT}) where {FT<:AbstractFloat}

Compute the marginal energy increase in spac, given

• spac MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type SPAC

plant_energy!(spac::MonoMLGrassSPAC{FT}, δt::FT) where {FT<:AbstractFloat}
plant_energy!(spac::MonoMLPalmSPAC{FT}, δt::FT) where {FT<:AbstractFloat}
plant_energy!(spac::MonoMLTreeSPAC{FT}, δt::FT) where {FT<:AbstractFloat}

Compute the marginal energy increase in spac, given

• spac MonoMLGrassSPAC, MonoMLPalmSPAC, or MonoMLTreeSPAC type SPAC
• δt Time step