G-steps 2 and 13 — the four production soil-characteristic laws and the closure-A quasi-steady recharge q₀(hᵤ, h_g). More...

#include "SubsurfaceData.hpp"

Include dependency graph for SoilCharacteristic.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	openswmm::twoD::soil::Params

Namespaces
namespace	openswmm

namespace	openswmm::twoD

namespace	openswmm::twoD::soil

Functions
double	openswmm::twoD::soil::effectiveSaturation (const Params &p, double psi) noexcept
	Effective saturation at suction head `psi` (m, ≥ 0). `Se ∈ (0, 1]`.

double	openswmm::twoD::soil::waterContent (const Params &p, double psi) noexcept
	Water content θ(ψ) = θ_r + Se·(θ_s − θ_r).

double	openswmm::twoD::soil::relativeConductivity (const Params &p, double psi) noexcept
	Relative conductivity `Kr(ψ) ∈ [0, 1]`.

double	openswmm::twoD::soil::conductivity (const Params &p, double psi) noexcept
	Unsaturated conductivity `K(ψ) = Ks·Kr(ψ)` (m/s).

double	openswmm::twoD::soil::suctionAtSaturation (const Params &p, double Se) noexcept
	Suction head at a given effective saturation — the retention inverse, needed to give the σ column a ψ from its θ. Returns 0 at `Se ≥ 1`.

double	openswmm::twoD::soil::diffusivity (const Params &p, double psi) noexcept
	Soil-moisture diffusivity `D(θ) = K(ψ)/\|dθ/dψ\|` (m²/s) at suction `psi`. Evaluated from a centered finite difference of the retention curve. Callers decide whether the capillary term is enabled.

double	openswmm::twoD::soil::equilibriumStorage (const Params &p, double L) noexcept
	Hydrostatic-equilibrium storage of a column of thickness `L` (m of water): `∫₀ᴸ θ(ψ) dψ`. Gardner and Brooks–Corey are closed form; Russo and van Genuchten use fixed-order Gauss–Legendre.

double	openswmm::twoD::soil::rechargeQ0 (const Params &p, double L, double hu) noexcept
	Closure-A quasi-steady recharge (m/s). `+` down, `−` capillary rise.

double	openswmm::twoD::soil::enslavedStorage (const Params &p, double L) noexcept
	The ENSLAVED reduction: `hᵤ` algebraic in `h_g` — the storage at which `rechargeQ0` vanishes. For Gardner this is eq. 39.

double	openswmm::twoD::soil::alphaL (const Params &p, double L) noexcept
	`αL`, the dimensionless group the AUTO closure selection reads. For Brooks–Corey and van Genuchten the law's own inverse length replaces α (`1/ψ_b`, and the van Genuchten `α`), so the thresholds mean the same thing across laws.

double	openswmm::twoD::soil::feddesStress (double psi, double psi_w) noexcept
	Feddes-style smooth stress multiplier on potential ET, from the column's mean suction. 1 in the readily-available range, falling smoothly to 0 at the wilting point — no `if (infil <= 0)` gate, which is the behaviour §7 retires. `psi_w` wilting suction (m).

Detailed Description

G-steps 2 and 13 — the four production soil-characteristic laws and the closure-A quasi-steady recharge q₀(hᵤ, h_g).

The laws

Each law supplies effective saturation Se(ψ), water content θ(ψ) and relative conductivity Kr(ψ), with suction head ψ ≥ 0 measured upward from the water table (so ψ = 0 at the table and ψ = L at the surface):

Law	`Kr(ψ)`
Gardner (1958)	`e^(−αψ)`
Russo (1988)	`[(1 + ½αψ)·e^(−½αψ)]²`
Brooks–Corey (1964)	`1` for `ψ ≤ ψ_b`, else `(ψ_b/ψ)^(2+3λ)`
van Genuchten (1980)	`Se^L·[1 − (1 − Se^(1/m))^m]²`, `Se = [1+(αψ)^n]^(−m)`

How q₀ is computed — read this before trusting a number

For Gardner, Qu & Duffy's eq. 22 is used verbatim:

q₀ = Ks · [ 1 − e^(−αL) − α·u ] / [ αL · (1 − e^(−αL)) ] , L = z_s − h_g

u = (hᵤ − θ_r L)/(θ_s − θ_r) (saturation-scale storage; hᵤ is metres of water)

That expression is algebraically identical to

q₀ = C(L) · [ u*(L) − u ] ,
     u*(L)  = (1 − e^(−αL)) / α          <- exactly eq. 39, the enslaved form
     C(L)   = Ks / ( L · (1 − e^(−αL)) )

— a relaxation of the column's stored water toward its hydrostatic equilibrium, at a conductivity-set rate. The equivalence is a genuine identity, not an approximation, and it is worth stating because it makes the sign convention obvious (hᵤ < hᵤ* ⇒ q₀ > 0, downward recharge; hᵤ > hᵤ* ⇒ capillary rise) and because it is the form that generalises.

The other three laws use that generalised form, with u*(L) the saturation integral ∫₀ᴸ Se(ψ) dψ of that law (closed form for Brooks–Corey, Gauss–Legendre for van Genuchten and Russo) and C(L) = K(L/2)/u*(L). Public equilibrium water storage is θ_r L + (θ_s − θ_r)u*(L); it is distinct from the saturation integral.

Warning: This generalisation is ours, not the literature's. Gardner reproduces the published closed form exactly and is verified against it. Russo, Brooks–Corey and van Genuchten reproduce the correct equilibrium (q₀ = 0 at hydrostatic storage) and the correct sign, but their relaxation rate is a modelling choice this file makes explicit rather than a published closed form. Plan step 18's closure-ladder benchmark and step 4's HYDRUS-1D comparison are what license them; until those run, prefer Gardner or Russo for anything quantitative, and prefer closure B (the σ column, which integrates the real Richards flux and needs none of this) where the answer matters. Recorded for the migration guide.

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

License: Apache-2.0

Classes

Namespaces

Functions

Detailed Description

The laws

How q₀ is computed — read this before trusting a number