FreezeCurves

AbstractSFCCObjective

Base type for non-linear SFCC optimization objectives.

BrooksCorey{Twp,Tψₛ,Tλ} <: SWRC

van Genuchten MT, 1980. A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal, 44(5): 892–898. DOI: 10.2136/sssaj 1980.03615995004400050002x.

DallAmico{TFT,Tg,Tswrc<:SWRC} <: SFCC

Dall'Amico M, 2010. Coupled water and heat transfer in permafrost modeling. Ph.D. Thesis, University of Trento, pp. 43.

DallAmicoSalt{TFT,Tsc,TR,Tg,Tswrc<:SWRC} <: SFCC

Freeze curve from Dall'Amico (2011) with saline freezing point depression.

Angelopoulos M, Westermann S, Overduin P, Faguet A, Olenchenko V, Grosse G, Grigoriev MN. Heat and salt flow in subsea permafrost modeled with CryoGRID2. Journal of Geophysical Research: Earth Surface. 2019 Apr;124(4):920-37.

FreeWater <: FreezeCurve

"Free water" freeze curve in terms of enthalpy (H), total water content (θtot), and the latent heat of fusion of water (L).

FreezeCurve

Base type for freezing characteristic curves which relate temperature or enthalpy to unfrozen water content.

Hu2020{TFT,Tvol,Tb}  <: SFCC

Soil freezing characteristic curve formulation of Hu et al. 2020.

Hu G, Zhao L, Zhu X, Wu X, Wu T, Li R, Xie C, Hao J. Review of algorithms and parameterizations to determine unfrozen water content in frozen soil. Geoderma. 2020 Jun 1;368:114277.

LUT{N,T,coordnames,TCoords,TData}

Generic implementation of an N-dimensional lookup table with support for reverse lookups w.r.t one variable.

Langer{TFT,Tvol,Ta,Tb} <: SFCC

Langer, M., Westermann, S., Muster, S., Piel, K., & Boike, J. (2011). The surface energy balance of a polygonal tundra site in northern Siberia – Part 2: Winter. The Cryosphere, 5(2), 509–524. https://doi.org/10.5194/tc-5-509-2011

McKenzie{TFT,Tvol,Tγ} <: SFCC

McKenzie JM, Voss CI, Siegel DI, 2007. Groundwater flow with energy transport and water-ice phase change: numerical simulations, benchmarks, and application to freezing in peat bogs. Advances in Water Resources, 30(4): 966–983. DOI: 10.1016/j.advwatres.2006.08.008.

PainterKarra{TFT,Tβ,Tω,Tg,Tswrc<:SWRC} <: SFCC

Painter SL, Karra S. Constitutive Model for Unfrozen Water Content in Subfreezing Unsaturated Soils. Vadose zone j. 2014 Apr;13(4):1-8.

PowerLaw{Tvol,Tα,Tβ} <: SFCC

Commonly used power law relation of Lovell (1957).

Lovell, C.: Temperature effects on phase composition and strength of partially frozen soil, Highway Research Board Bulletin, 168, 74–95, 1957.

SFCC <: FreezeCurve

Base type for a soil freeze characteristic curve (SFCC) function. Subtypes should be callable structs that implement the freeze curve and contain any necessary additional constants or configuration options. User-specified parameters can either be supplied in the struct or declared as model parameters via the variables method.

SFCCInverseEnthalpyObjective{TF,Tkwargs<:NamedTuple,Thc,TL,TH,Tsat} <: AbstractSFCCObjective

Optimization objective for finding a temperature, T, wich resolves the conservation equation:

\[0 = (H - Lθ)/C - T\]

given a fixed enthalpy value H and freeze curve arguments f_args.

SFCCNewtonSolver <: SFCCSolver

Fast, specialized implementation of Newton's method with backtracking line search for resolving the energy conservation law, H = TC + Lθ. Attempts to find the root of the corresponding temperature residual: ϵ = T - (H - Lθ(T)) / C(θ(T)) and uses backtracking to avoid jumping over the solution. This prevents convergence issues that arise due to discontinuities and strong non-linearity in most common soil freeze curves.

SFCCPreSolver{TCache} <: SFCCSolver

A fast SFCC "solver" which pre-builds an interpolant for the freeze curve in terms of enthalpy, θ(H).

SFCCPreSolverCache1D{TF} <: AbstractPreSolverCache

Efficient "presolver" implementation that builds a 1D interpolant for θw(H) over an adaptive range of H values determined based on local approximation error. Note that this presolver implementation is only valid when all other freeze curve parameters are held constant and will produce incorrect results otherwise.

SFCCPreSolverCacheND{N,TF} <: AbstractPreSolverCache

More general "presolver" implementation that builds a ND lookup-table/interpolant for θw(H, sat, args...) where args is a set of all other freeze curve parameters passed to initialize!. Note that this implementation currently does not perform any error control so there approximation error is not guaranteed.

SFCCSolver

Base type representing non-linear solvers for implicit SFCC functions.

SFCCTable{F,I} <: SFCC

Pre-tabulated soil freezing characteristic curve. See Tabulated and tabulate.

SWRC

Base type for soil water retention curves (SWRC) which relate soil water matric potential to water content.

SoilFreezeThawProperties{TTₘ,TLsl}

Struct containing constants/parameters common to some or all SFCCs.

SoilFreezeThawProperties(f::SFCC)

Retrieves the default SoilFreezeThawProperties from f; should be defined for all freeze curves.

SoilWaterVolume{Tρw,Tθres,Tθsat}

Struct containing basic physical constants and propeties related to soil pore water.

SoilWaterVolume(f::SFCC)

Retrieves the nested SoilWaterVolume from the SoilFreezeThawProperties of the freeze curve f.

SoilWaterVolume(f::SWRC)

Get the SoilWaterVolume defined for the given SWRC f. Must be implemented for all SWRC types. Default implementation retrieves the field water.

VanGenuchten{Tvol,Tα,Tn} <: SWRC

van Genuchten MT, 1980. A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal, 44(5): 892–898. DOI: 10.2136/sssaj 1980.03615995004400050002x.

Westermann{TFT,Tvol,Tδ} <: SFCC

Westermann, S., Boike, J., Langer, M., Schuler, T. V., and Etzelmüller, B.: Modeling the impact of wintertime rain events on the thermal regime of permafrost, The Cryosphere, 5, 945–959, https://doi.org/10.5194/tc-5-945-2011, 2011.

Base.inv(f::SWRC)

Returns a function that evaluates the inverse of the soil water retention curve, f.

Tabulated(f; kwargs...)

Alias for tabulate intended for function types.

Tabulated(f::SFCC, args...)

Produces an SFCCTable function which is a tabulation of f.

adstrip(x::Number) adstrip(x::ForwardDiff.Dual)

adstrip extracts the underlying numeric value from x if x is a ForwardDiff.Dual number. If x is a non-tracked numeric type, then adstrip simply returns x.

build_lut(f, coords::Pair{Symbol,<:Union{Number,AbstractVector}}...; f_kwargs...)

Builds an n-dimensional lookup table LUT by invoking f on the given coords. f should be a function which accepts keyword arguments matching coords as well as any additional constant keyword arguments f_kwargs.

Example:

f(; x=1.0, y=1.0) = x + y
lut = build_lut(f, :x => -10.0:10.0, :y=-10.0:10.0)
lut(; x=2.2, y=1.5)
# output
3.7

derivative(f::SWRC)

Returns a function that evaluates the derivative ∂f∂ψ of the soil water retention curve, f.

dual(x::Number, ::Type{tag}) where {tag}
dual(x::A, ::Type{tag}) where {N,T,A<:SVector{N,T},tag}

Constructs a ForwardDiff.Dual number (or static array thereof) with tag from x.

enthalpy(T, C, L, θw)

Computes the volumetric enthalpy [J/m^3] given T, C, L, θw.

heatcapacity(c_frozen::Number, c_thawed::Number; θtot=1.0)

Piecewise constant heat capacity function:

\[f(θw,θtot,θsat) = \begin{cases} c_f & θw < θtot \\ c_t & \text{otherwise} \end{cases}\]

heatcapacity(c::Number)

Heat capacity function f(θw,θtot,θsat) = c where c is a pre-specified constant.

heaviside(x)

Differentiable implementation of heaviside step function, i.e:

$h(x) = \begin{cases} 1 & x ≥ 0 \\ 0 & x < 0 \end{cases}$

inflectionpoint(f::SFCC)

Returns the analytical inflection point (i.e. where ∂²θ/∂T^2 = 0), if available.

inflectionpoint(f::SWRC)

Returns the analytical solution for the inflection point (i.e. where ∂²θ/∂ψ² = 0) of the SWRC, if available.

initialize!(solver::SFCCSolver, fc::SFCC, hc; fc_kwargs...)

Initializes solver (if necessary) for the freeze curve function fc with arguments fc_kwargs and heat capacity function hc. Default implementation does nothing.

initialize!(solver::SFCCPreSolver{<:SFCCPreSolverCache1D}, fc::SFCC, hc::F; fc_kwargs...)

Initializes this SFCCPreSolver by building interpolants for fc and its derivatives. θtot and θsat are assumed fixed. hc must be heat capacity as a function of liquid water content.

normalize_temperature(x)
normalize_temperature(x::TemperatureQuantity)

Converts temperature x to Kelvin. If x has units, uconvert is used. Otherwise, if x a general numeric type, does a heuristic check x <= 200 and assumes the given temperature is in celsius if the condition is satisfied.

sfccsolve(obj::AbstractSFCCObjective, solver::SFCCSolver, x₀, ::Val{return_all}=Val{true}()) where {return_all}

Solve the given objective obj using solver and initial guess x₀. If return_all=true, then sfccsolve should return a named tuple with at least the temperature solution T, the liquid water content θw, the heat capacity C, and the liquid water content deriviative ∂θw∂T defined. Solver-specific additional values may also be included.

sfccsolve(obj::SFCCInverseEnthalpyObjective, solver::SFCCNewtonSolver, T₀::Number, ::Val{return_all}=Val{true}(); error_when_not_converged=true)

Solves obj using the specialized Newton solver and returns the result. If return_all is true, a named tuple (;T, Tres, θw, C, itercount) is returned; otherwise (by default), only the temperature solution is returned.

swrc(::SFCC)

Retrieves the SWRC embedded within this SFCC, if defined. The default value for freeze curve functions without an associated soil-water retention curve is nothing.

tabulate(f; kwargs...)

Tabulates the given function f using a linear, multi-dimensional interpolant. Knots should be given as keyword arguments arg = A where A is a StepRange or Vector of input values (knots) at which to evaluate the function. A may also be a Number, in which case a pseudo-point interpolant will be used (i.e valid on [A,A+ϵ]). Note that all arguments to f must be accepted as keyword arguments.

temperature_residual(f::F, hc, L, H, T, sat; θsat=SoilWaterVolume(f).θsat, f_kwargs...) where {F<:SFCC}

Helper function for updating θw, C, and the residual. hc should be a function (θw,θtot,θsat) -> C which computes the heat capacity from the unfrozen, total, and maximum (saturated) water contents respectively.

waterpotential(f::SWRC, θ; θsat=f.vol.θsat, θres=f.vol.θres, kwargs...)

Returns the water potential at volumetric water content θ by evaluating the inverse of f.

plot(T, fc::SFCC)

Simple plotting recipe for SFCC which takes care of stripping units.

plot(Ts, fc::SFCC)

Simple plotting recipe for SWRC which takes care of stripping units.

ustrip(x)

Reconstructs the type or function x with all numerical quantities stripped of units. All units are first converted to preferred SI units before being stripped.