Hydrology

Aquifer water-storage update for the case when the water table lies below the soil column. The rate of change of aquifer water dW_a (kg/(m^2*s)) is the balance of recharge into the aquifer and sub-surface drainage out of it (Oleson et al. 2010, CLM Tech Note Ch. 5, Eq. 5.143). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:791 (`AquiferWaterBalance` @component). Observed-only: both inputs are parameters and dW_a is given by a single algebraic equation.

Sub-surface drainage out of the soil column as an exponential function of water table depth, modulated by an impermeable-fraction reduction in frozen soils, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eqs. 5.140 (drainage) and 5.141 (impermeable fraction). q_drai = (1 - f_imp) * q_drai_max * exp(-f_drai * z_v); f_imp = max((exp(-α(1 - f_ice_weighted)) - exp(-α)) / (1 - exp(-α)), 0). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:698 (`GroundwaterDrainage` @component). Observed-only: both inputs are parameters and both outputs are given by single algebraic equations.

Surface runoff and updated surface liquid-water content for roof and impervious-road surfaces, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eqs. 5.47-5.48. With no snow layers (has_snow = 0): runoff is the excess of (w_liq_1/Δt + q_liq_0 - q_seva) above the ponding limit w_pond_max/Δt. With snow layers (has_snow = 1): all liquid water reaching the surface becomes runoff and the surface liquid-water content passes through unchanged. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:991 (`ImperviousRunoff` @component). Parameterized as observed-only: w_liq_1, q_liq_0, q_seva, has_snow are inputs (parameters); q_over_nosnow, q_over, w_liq_1_new are algebraic outputs.

Surface water balance for roof and impervious-road urban surfaces, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eqs. 5.2-5.5. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:937 (`ImperviousWaterBalance` @component). Parameterized as observed-only: precipitation (q_rain, q_sno) and loss fluxes (E_surface, q_over, q_rgwl, q_snwcp_ice) are inputs; q_grnd_liq, q_grnd_ice, and water_input are algebraic outputs.

Hydraulic conductivity at a soil-layer interface as a Clapp-Hornberger function of the average volumetric water content and porosity of the two adjacent layers, scaled by the unfrozen fraction. Implements Oleson et al. (2010, CLM Tech Note Ch. 5) Eq. 5.69 (interface conductivity) with the frozen-fraction multiplier of Eq. 5.70. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:1053 (`InterfaceHydraulicConductivity` @component). Observed-only: all eight inputs are parameters and k_h is given by a single algebraic equation.

Net water-input rate for the pervious-road column (Oleson et al. 2010, CLM Tech Note Ch. 5, Eq. 5.1, p. 110). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:900 (`PerviousRoadWaterBalance` @component). Algebraic single-equation balance: water_input = (precipitation gains) − (evaporation + surface runoff + sub-surface drainage + groundwater liquid runoff + snow-capping solid runoff).

Full 1D Saint-Venant PDE system for surface overland flow: mass conservation ∂h̃/∂t = −∂q/∂l + (P − I) and momentum conservation ∂q/∂t = −∂F/∂l + g·h̃·(S₀ − Sᶠ), where the momentum flux F = q²/h̃ + g·h̃²/2 is an auxiliary (observed) PDE field. Migrated from EnvironmentalTransport.jl@a48559c4 src/surface_runoff.jl:117 (SaintVenantPDE builder). This is a DISCRETIZATION-AGNOSTIC leaf (esm-spec §9.7.10): the spatial fluxes are written with the rewrite-target spatial derivative op `D(·, wrt: l)` and the component imports NO discretization of its own, so it can be composed under different schemes. Its inline tests and examples inject a discretization (form C) — here the sibling adapter `saint_venant_upwind1_inflow.esm` (first-order upwind, per-variable inflow BC) — for that run only; the persisted leaf keeps its spatial `D` intact. The 1D spatial variable l is the along-slope coordinate; the sibling SurfaceRunoff component (surface_runoff_component.esm) is the single-node ODE reduction of this same PDE system with the spatial-divergence terms exposed as input parameters.

Solid and liquid runoff from snow capping for snow-covered surfaces, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eqs. 5.153-5.154. When the model has reached its prescribed maximum snow water equivalent, additional precipitation and atmospheric deposition cannot accumulate on the snowpack and is shed to the surface as `snow capping runoff` — the solid stream comes from solid precipitation plus frost (Eq. 5.153) and the liquid stream from liquid precipitation plus dew (Eq. 5.154). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:823 (`SnowCappingRunoff` @component). Parameterized as observed-only: q_grnd_ice, q_grnd_liq, q_frost, q_dew are inputs (parameters); q_snwcp_ice and q_snwcp_liq are algebraic outputs.

Total fractional snow-layer compaction rate combining destructive metamorphism (Eq. 5.26), overburden pressure (Eq. 5.28), and melt-induced compaction (Eq. 5.31). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:174 (`SnowCompaction` @component). Implements Oleson et al. (2010) CLM4 Tech Note Chapter 5, Section 5.1.4, Eqs. 5.24–5.33. Parameterized as observed-only: T_i, w_ice, w_liq, dz, P_s, f_ice_n, f_ice_n1 are inputs; c_1, c_2, C_R1, eta, C_R2, C_R3, C_R are algebraic outputs.

Bulk density of newly fallen snow as a piecewise function of atmospheric temperature, following Anderson (1976) as parameterized in Eq. 5.10 of Oleson et al. (2010, CLM Tech Note Ch. 5). Three regimes: (1) warm snow (T_atm > T_f + 2 K) → rho_sno = 50 + 1.7*17^1.5 (saturated warm-side value); (2) intermediate (T_f - 15 K < T_atm <= T_f + 2 K) → rho_sno = 50 + 1.7*((T_atm - T_f + 15)/1K)^1.5; (3) cold (T_atm <= T_f - 15 K) → rho_sno = 50 (saturated cold-side floor). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:25 (`SnowDensity` @component). Parameterized as observed-only: T_atm is the input parameter; rho_sno is an algebraic output.

Conservation of ice mass in snow layers and new snowfall accumulation (Oleson et al. 2010, CLM4 Tech Note Ch. 5, Section 5.1.1, Eqs. 5.6-5.14). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:79 (`SnowIceContent` @component). Parameterized as observed-only: q_grnd_ice, q_frost, q_subl, rho_sno are inputs (parameters); dz_sno_dt, q_ice_top are algebraic outputs.

Combined-layer properties when two snow layers are merged (Oleson et al. 2010, Section 5.1.5.1, Eqs. 5.38–5.42). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:253 (`SnowLayerCombination` @component). Observed-only: per-layer thicknesses, water/ice contents, and temperatures are inputs (parameters); combined thickness/water/ice/enthalpies/temperature are algebraic outputs.

Volumetric ice/liquid contents and outgoing liquid-water flux for a snow layer (Oleson et al. 2010, CLM4 Tech Note Ch. 5, Eqs. 5.18–5.20). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:119 (`SnowWaterContent` @component). Parameterized as observed-only: w_ice, w_liq, dz are inputs (parameters); theta_ice, theta_liq, q_liq_out are algebraic outputs.

Soil hydraulic properties for an urban-canopy pervious-road soil column following Section 5.3.1 of Oleson et al. (2010, CLM4 Tech Note). Computes five Clapp-Hornberger / Cosby-style properties from the soil sand and clay fractions and the local volumetric water content: saturated hydraulic conductivity k_sat (Eq. 5.70), porosity θ_sat (Eq. 5.71), Clapp-Hornberger exponent B (Eq. 5.72), saturated matric potential ψ_sat (Eq. 5.74), and matric potential ψ (Eq. 5.73, clamped on both sides). Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:322 (`SoilHydraulicProperties` @component). Observed-only: all three inputs are parameters and all five outputs are given by single algebraic equations.

Total volumetric soil water content from per-layer liquid-water and ice masses, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eq. 5.137. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:1091 (`SoilWaterContentCalc` @component). Parameterized as observed-only: w_liq, w_ice, Δz are inputs (parameters); θ_i is an algebraic output combining both phases via their respective densities.

Layer-averaged equilibrium volumetric water content (θ_E, Eq. 5.101) and equilibrium matric potential at the layer node (ψ_E, Eq. 5.106) for a single soil layer, following Oleson et al. (2010, CLM4 Tech Note Ch. 5, §5.3.2.1, Eqs. 5.98–5.106). θ_E is fully saturated (θ_sat) when the water table is above the layer (z_v < z_h_upper), otherwise is computed by integrating the hydrostatic-equilibrium Clapp-Hornberger profile across the layer, clamped to [0, θ_sat]. ψ_E is derived from the Brooks-Corey inverse relation with a 1% saturation floor and a hard lower bound at ψ_min = −10⁵ m to prevent numerical underflow. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:509 (`SoilWaterEquilibrium` @component). Note: the migration-tracker row for this component carried the blocking_gap `other:discretization-plan` because the row description mentioned an in-file Richards-equation PDE at src/hydrology.jl:674. Inspection shows that PDESystem lives in a separate non-`@component` helper function (`RichardsEquation`) and is not part of `SoilWaterEquilibrium`, which is a plain two-equation algebraic `@component`. No discretization plan is needed.

Soil water flux at the interface between two adjacent soil layers, computed from Darcy's law with the Zeng and Decker (2009) equilibrium-potential correction (Oleson et al. 2010, CLM4 Tech Note Eq. 5.88). q = -k_interface * ((ψ_upper - ψ_lower) + (ψ_E_lower - ψ_E_upper)) / (z_lower - z_upper), positive upward. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:471 (`SoilWaterFlux` @component). Observed-only: the seven inputs are parameters and q is given by a single algebraic equation.

Top-layer ice and liquid water mass-rate updates from surface dew, frost, and sublimation, following Oleson et al. (2010, CLM Tech Note Ch. 5) Eqs. 5.150-5.152. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:860 (`SurfaceLayerUpdate` @component). Parameterized as observed-only: q_sdew, q_frost, q_subl are inputs (parameters); dw_liq_1, dw_ice_1_frost, dw_ice_1_subl are algebraic outputs that pass each input through (with a sign flip on sublimation). Applies to the top layer of all surfaces (roof, pervious road, impervious road).

Single-node surface-runoff model based on the Saint-Venant overland-flow equations, from Wang et al. (2020), Eq. 1. The component tracks two ODE states at one surface computing node — the ponded flow depth h_tilde and the surface runoff flux per unit width q — plus one algebraic (observed) state, the Manning friction slope S_f. Mass conservation (Eq. 1a) reads dh_tilde/dt = -dqdl + (P - I_infil): the flow depth rises with the net of precipitation P over infiltration I_infil and falls with the spatial divergence of runoff flux dqdl. Momentum conservation (Eq. 1b) reads dq/dt = -dFdl + g*max(h_tilde,h_tilde_0)*(S_0 - S_f): the runoff flux is driven by the imbalance between the surface slope S_0 and the friction slope S_f, minus the spatial divergence of momentum flux dFdl. The friction slope closes the system via Manning's equation S_f = (n_mann*q)^2 / h_tilde^(10/3), written here in non-dimensionalized form so the fractional powers act on dimensionless bases. Because this is a single-node reduction of a spatial PDE, the two spatial-divergence terms dqdl and dFdl are exposed as input parameters to be supplied by a discretization scheme or a coupled model; with both at zero the component reduces to the local mass/momentum response. Migrated from EnvironmentalTransport.jl@a48559c4 src/surface_runoff.jl:35 (`SurfaceRunoff` @component).

Surface runoff and infiltration for the pervious-road urban surface, following Oleson et al. (2010, CLM Tech Note Ch. 5) §5.2, Eqs. 5.49-5.57. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:384 (`SurfaceRunoffInfiltration` @component). Implements the SIMTOP-based (Niu et al., 2005) runoff partition with frozen-soil-modulated saturated fraction (Eqs. 5.50-5.51), a maximum infiltration capacity built from top-layer matric-potential and saturation (Eqs. 5.52-5.55), and snow-aware surface infiltration (Eqs. 5.56-5.57). Observed-only: all 14 inputs are parameters and the seven outputs (f_frz_1, f_sat, s, v, q_infl_max, q_over, q_infl) are given by algebraic equations.

Water table depth z_v as a function of unconfined-aquifer water storage W_a and the depth of the bottom soil interface z_h_bottom. Implements Oleson et al. (2010) CLM Tech Note Eq. 5.146 (p. 143) with hard clamps at z_v_min = 0.05 m and z_v_max = 80 m. Migrated from UrbanCanopy.jl@9200edd4 src/hydrology.jl:743 (`WaterTableDepth` @component). Observed-only: z_h_bottom and W_a are parameters and z_v is given by a single algebraic equation.