API

WaterPhysics uses the multiple dispatch approach to calculate the temperature and pressure dependent physical properties of water and other molecules, such as CO₂. The trace molecules and mediums are catergorized to gas or liquid subject to a general type AbstractTrace. Hierarchy of AbstractTrace:

• AbstractTraceGas
• AbstractTraceLiquid

abstract type AbstractTrace{FT<:AbstractFloat}

The gas can be either the target trace molecule (e.g., when computing diffusive coefficient of CO₂ in water using diffusive_coefficient) or the medium (e.g., when computing diffusive coefficient or CO₂ in air using diffusive_coefficient). Currently, WaterPhysics supports the following subtypes of AbstractTraceGas:

• TraceGasAir
• TraceGasCO₂
• TraceGasH₂O
• TraceGasO₂

abstract type AbstractTraceGas{FT<:AbstractFloat} <: WaterPhysics.AbstractTrace{FT<:AbstractFloat}

The liquid can be either the medium for gas (e.g., when computing diffusive coefficient of CO₂ in water using diffusive_coefficient) or the target molecule (e.g., when computing surface tension of water using surface_tension). Currently. WaterPhysics supports the following subtypes of AbstractTraceLiquid:

• TraceLiquidH₂O

abstract type AbstractTraceLiquid{FT<:AbstractFloat} <: WaterPhysics.AbstractTrace{FT<:AbstractFloat}

struct TraceGasAir{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceGas{FT<:AbstractFloat}

Identity trace label for air.

struct TraceGasCO₂{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceGas{FT<:AbstractFloat}

Identity trace label for gas phase CO₂.

Fields

• d_air::AbstractFloat

: Diffusive coefficient in air in [m² s⁻¹]

• a_298::AbstractFloat

: Hydrodynamic radius of the solute in [m]

• a_a::AbstractFloat

: Coefficient to make temperature correction over ydrodynamic radius

• d_water::AbstractFloat

: Diffusive coefficient in liquid water in [m² s⁻¹]

struct TraceGasH₂O{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceGas{FT<:AbstractFloat}

Identity trace label for gas phase H₂O.

Fields

• d_air::AbstractFloat

: Diffusive coefficient in air in [m² s⁻¹]

struct TraceGasN₂{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceGas{FT<:AbstractFloat}

Identity trace label for gas phase N₂.

Fields

• a_298::AbstractFloat

: Hydrodynamic radius of the solute in [m]

• a_a::AbstractFloat

: Coefficient to make temperature correction over ydrodynamic radius

• d_water::AbstractFloat

: Diffusive coefficient in liquid water in [m² s⁻¹]

struct TraceGasO₂{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceGas{FT<:AbstractFloat}

Identity trace label for gas phase O₂.

Fields

• d_air::AbstractFloat

: Diffusive coefficient in air in [m² s⁻¹]

• d_water::AbstractFloat

: Diffusive coefficient in liquid water in [m² s⁻¹]

struct TraceLiquidH₂O{FT<:AbstractFloat} <: WaterPhysics.AbstractTraceLiquid{FT<:AbstractFloat}

Identity trace label for liquid phase H₂O.

Fields

• γ_cor::AbstractFloat

: Surface tension coefficient correction

• γ_exp::AbstractFloat

: Surface tension coefficient exponent

• γ_k::AbstractFloat

: Surface tension coefficient k in [N m⁻¹]

• γ_ref::AbstractFloat

: Surface tension at 298.15 K in [N m⁻¹]

• γ_T_c::AbstractFloat

: Surface tension coefficient T_crit in [K]

• υ_A::AbstractFloat

: Viscosity coefficient A in [Pa s]

• υ_B::AbstractFloat

: Viscosity coefficient B in [K]

• υ_C::AbstractFloat

: Viscosity coefficient C in [K⁻¹]

• υ_D::AbstractFloat

: Viscosity coefficient D in [K⁻²]

Capillary pressure of the trace liquid in a pipe is a function of surface tension (γ), pipe raduis (r), and contact angle (α):

\[P_{c} = \dfrac{2 ⋅ γ ⋅ \text{cos}(α)}{r}\]

capillary_pressure(r::FT, T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}
capillary_pressure(r::FT, T::FT, α::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Capillary pressure of trace liquid in [Pa], given

• r Curvature radius in [m]
• T Trace liquid temperature in [K]
• med Medium. Optional. Default is liquid water
• α Contact angle in [°]

Diffusion of trace molecules in medium is temperature dependent, to calculate this temperature dependency, we provide a function to quick estimate this value for different trace molecules using diffusive_coefficient. The methods supports the computation for the coefficient in gas and liquid.

For the diffusive coefficient of gas in air, the coefficient is simply treated as a function of temperature and the reference coefficient at 298.15 K:

D = D_\text{ref} ⋅ \left( \dfrac{T}{298.15} \right)^{1.8}

diffusive_coefficient(T::FT, mol::Union{TraceGasCO₂{FT}, TraceGasH₂O{FT}, TraceGasO₂{FT}}, med::TraceGasAir{FT}) where {FT<:AbstractFloat}

Diffusive coefficient of trace molecule in [m² s⁻¹], given

• T Trace medium temperature in [K]
• mol Trace molecule
• med Diffusion medium (air)

The diffusive coefficient of disolved gas in liquid water is also a function of temperature. The calculation is based on the empirical formulation and variables from Cadogen et al. (2015) Diffusion coefficients of CO₂ and N₂ in water at temperatures between 298.15 K and 423.15 K at pressures up to 45 MPa.

diffusive_coefficient(T::FT, mol::Union{TraceGasCO₂{FT}, TraceGasN₂{FT}}, med::TraceLiquidH₂O{FT}) where {FT<:AbstractFloat}

Diffusive coefficient of trace molecule in [m² s⁻¹], given

• T Trace medium temperature in [K]
• mol Trace molecule
• med Diffusion medium (liquid water)

The temperature dependency of diffusive coefficient impacts leaf gas exchange via change the maximal stomatal conductance to H₂O vapor and CO₂, given that Since the stomatal conductance should not exceed its structural limit. To account for this effect, we provide a function to calculate the diffusive coefficient relative to 25 Celcius.

As mentioned in diffusive_coefficient, relative diffusive coefficient of target gas in gas medium is calculated as an exponential function of temperature. The shortcut method is

relative_diffusive_coefficient(T::FT, mol::AbstractTraceGas{FT} = TraceGasH₂O{FT}(), med::AbstractTraceGas{FT} = TraceGasAir{FT}()) where {FT<:AbstractFloat}

Relative diffusive coefficient of trace gas in medium, given

• T Water vapor temperature in [K]
• mol Trace molecule. Optional, default is water vapor
• med Medium. Optional, default is air

As to disolved gas diffsuin in liquid medium, the relative coefficient is also computed based on the empirical formulation from Cadogan et al. (2014).

relative_diffusive_coefficient(T::FT, mol::Union{TraceGasCO₂{FT}, TraceGasN₂{FT}}, med::TraceLiquidH₂O{FT}) where {FT<:AbstractFloat}

Relative diffusive coefficient of trace gas in medium, given

• T Water vapor temperature in [K]
• mol Trace molecule
• med Medium (liquid water)

Water evaporation from liquid phase is a key process to regulate leaf temperature, and to best represent this process. We computed the latent heat coefficient from water temperature:

latent_heat_vapor(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Latent heat of vaporization in [J kg⁻¹], given

• T Medium temperature in [K]
• med Medium. Optional. Default is liquid water

When water temperature increases, the surface tension at the air-water interface decreases. Surface tension changes impacts the plant water transport via two aspects. First, if surface tension is lower, for a constant soil water content, the soil matrix potential gets less negative because the capillary pressure at the air-water interface decreases. And this is beneficial to plants. Second, the air-water interface at the pit membrane also has lower capillary pressure when temperature increases, meaning that the xylem conduits are less resistant to drought-induced air-seeded cavitation. And this is harmful for plants. Though the surface tension does not differ much with temperature change within the plant physiological active range, we account for this effect in our Land model. The equation used is (see http://www.iapws.org/relguide/Surf-H2O.html)

\[γ = 0.2358 ⋅ \left( 1 - \dfrac{T}{T_c} \right)^{1.256} ⋅ \left[ 1 - 0.625 ⋅ \left( 1 - \dfrac{T}{T_c} \right) \right]\]

surface_tension(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Surface tension of trace liquid in [N m⁻¹], given

• T Liquid water temperature in [K]
• med Medium. Optional. Default is liquid water

relative_surface_tension(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Relative surface tension of trace liquid relative to 298.15 K, given

• T Liquid water temperature in [K]
• med Medium. Optional. Default is liquid water

When temperature increases, liquid water vapor pressure increases exponentially. And this correlation is accounted for using the functions below:

saturation_vapor_pressure(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}
saturation_vapor_pressure(T::FT, Ψ::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Saturation vapor pressure in [Pa], given

• T Liquid water temperature in [K]
• med Medium. Optional. Default is liquid water
• Ψ Liquid water pressure in [Pa], positive/negative for convex/concave interface; if Ψ is given, pressure_correction is made

Compute the the 1st order derivative of saturation vapor pressure over a plane surface by integration of the Clausius-Clapeyron relation. The re-arranged Clausius-Clapeyron relation is

\[\frac{∂P_{sat}^{*}}{∂T} = P_{sat} ⋅ \dfrac{ LH_0 + Δc_p ⋅ (T - T_{triple})}\]

saturation_vapor_pressure_slope(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}
saturation_vapor_pressure_slope(T::FT, Ψ::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

First order derivative of saturation vapor pressure in [Pa K⁻¹], given

• T Liquid water temperature in [K]
• med Medium. Optional. Default is liquid water
• Ψ Liquid water pressure in [Pa], positive/negative for convex/concave interface; if Ψ is given, pressure_correction is made

Yet, the saturation vapor pressure is not only a function of temperature, but also a function of the air-water interface curvature, known as the Kelvin equation. The package provide pressure_correction to make the correction. The Kelvin equation is

\[\log \left( \dfrac{P_{sat}}{P_{sat}^{*}} \right) = \dfrac{Ψ ⋅ V_{m}}{R ⋅ T}\]

pressure_correction(T::FT, Ψ::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Kelvin correction factor for saturation vapor pressure, given

• T Liquid water temperature in [K]
• Ψ Liquid water pressure in [Pa], positive/negative for convex/concave interface
• med Medium. Optional. Default is liquid water

When temperature increases, liquid water viscosuty decreases, meaning that the resistance for water decreases and the pressure drop per flow rate decreases. This effect is pretty significant as 1 degree increase of temperature results in about 2.4% drop in viscosity, and this is very beneficial to plant water transport. Unfortunately, to our knowledge, very few models account for this effect when modeling plant hydraulics because of the difficulty in modeling the energy budget along the flow path. We plan to have this effect accounted for in our CliMA Land model, by computing the water tempreature along the flow path and thus the viscosity change. Equation used is

\[υ = A ⋅ \exp \left( \dfrac{B}{T} + C⋅T + D⋅T^2 \right)\]

and the fitting parameters are from Reid, Prausnitz, & Poling (1987), valid through 273-643 K

A = 1.856E-14 # Pa s
B = 4209      # K
C = 0.04527   # K⁻¹
D = -3.376E-5 # K⁻²

viscosity(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Viscosity in [Pa s], given

• T Liquid water temperature in [K]
• med Medium. Optional. Default is liquid water

relative_viscosity(T::FT, med::TraceLiquidH₂O{FT} = TraceLiquidH₂O{FT}()) where {FT<:AbstractFloat}

Viscosity relative to 298.15 K, given

• T Liquid water temperature in [K]
• liquid Optional. Default is liquid water