SnowCappingRunoff
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.
Description
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.
Reference
_source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/hydrology.jl:823
Upstream SnowCappingRunoff is an MTK @component whose four inputs (q_grnd_ice, q_grnd_liq, q_frost, q_dew) are @parameters and whose two outputs (q_snwcp_ice, q_snwcp_liq) are time-indexed @variables with algebraic-only equations (no derivatives). Identical equation structure preserved here.
The upstream component declares no @constants — all four inputs are user-facing fluxes (precipitation, frost, dew rates) with no embedded physical constants. The two outputs are decoupled: q_snwcp_ice depends only on the ice/frost pair and q_snwcp_liq depends only on the liq/dew pair, so the component is two independent additive identities sharing a name. Tests exploit this by sweeping each branch independently.
Observability classification: this component is functionally observed-only — every output variable is given by a single algebraic equation (a two-term sum) in terms of the parameters (and the (t) time index has no role since there is no derivative). Test scenarios use time_span: [0, 1] and sample at t=0 to mirror the convention used by the other observed-only ESM files in this rig (impervious_runoff.esm, soil_water_content_calc.esm, etc.).
Tolerance rationale (model-level rel=1e-9): observed-only algebraic system (no ODE integration); each equation is a single addition, so roundoff is at the IEEE-754 ULP level (~1e-16). 1e-9 leaves comfortable headroom above ULP roundoff and matches the convention used by sibling observed-only files (soil_water_content_calc.esm uses 1e-9 for analogous algebraic-sum equations). Tighter abs: 1e-12 is asserted on outputs that are exactly zero by construction so the assertion does not silently accept a stuck-at-1e-3 regression._
Parameters
| Name | Units | Default | Description |
|---|---|---|---|
q_grnd_ice | kg/(m^2*s) | 0.0 | Solid precipitation reaching surface |
q_grnd_liq | kg/(m^2*s) | 0.0 | Liquid precipitation reaching surface |
q_frost | kg/(m^2*s) | 0.0 | Frost rate (atmospheric water vapor deposition as ice on snow surface) |
q_dew | kg/(m^2*s) | 0.0 | Dew rate (atmospheric water vapor condensation as liquid on snow surface) |
Observed
| Name | Units | Default | Description |
|---|---|---|---|
q_snwcp_ice | kg/(m^2*s) | Solid runoff from snow capping (Oleson Eq. 5.153): q_grnd_ice + q_frost | |
q_snwcp_liq | kg/(m^2*s) | Liquid runoff from snow capping (Oleson Eq. 5.154): q_grnd_liq + q_dew |
Observed expressions
$$ q_{snwcp\,ice} = q_{grnd\,ice} + q_{frost} $$Solid runoff from snow capping (Oleson Eq. 5.153): q_grnd_ice + q_frost
$$ q_{snwcp\,liq} = q_{grnd\,liq} + q_{dew} $$Liquid runoff from snow capping (Oleson Eq. 5.154): q_grnd_liq + q_dew
Analyses
ice_runoff_vs_snowfall_with_frost
Sweep solid precipitation rate q_grnd_ice across a typical CLMU range with a small fixed frost contribution (q_frost = 0.0005 kg/(m^2*s)). q_snwcp_ice = q_grnd_ice + 0.0005 — a unit-slope line offset by the frost term, surfacing Eq. 5.153 directly. Liquid-side inputs held at zero so the liquid stream is identically zero across the sweep.
Time span: 0.0 → 1.0
Swept over: q_grnd_ice
liq_runoff_phase_partition
Joint sweep over q_grnd_liq and q_dew at fixed solid-side zero. Surfaces the perfectly additive plane q_snwcp_liq = q_grnd_liq + q_dew (Eq. 5.154) — iso-runoff contours are 45-degree lines in the (q_grnd_liq, q_dew) plane. Visualizes the equal-weighting between the two liquid sources (rain and dew contribute identically per unit flux).
Time span: 0.0 → 1.0
Swept over: q_grnd_liq, q_dew
Raw .esm
Raw .esm JSON (this component)
{
"reference": {
"notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/hydrology.jl:823\nUpstream `SnowCappingRunoff` is an MTK `@component` whose four inputs (q_grnd_ice, q_grnd_liq, q_frost, q_dew) are `@parameters` and whose two outputs (q_snwcp_ice, q_snwcp_liq) are time-indexed `@variables` with algebraic-only equations (no derivatives). Identical equation structure preserved here.\n\nThe upstream component declares no `@constants` — all four inputs are user-facing fluxes (precipitation, frost, dew rates) with no embedded physical constants. The two outputs are decoupled: q_snwcp_ice depends only on the ice/frost pair and q_snwcp_liq depends only on the liq/dew pair, so the component is two independent additive identities sharing a name. Tests exploit this by sweeping each branch independently.\n\nObservability classification: this component is functionally observed-only — every output variable is given by a single algebraic equation (a two-term sum) in terms of the parameters (and the `(t)` time index has no role since there is no derivative). Test scenarios use `time_span: [0, 1]` and sample at t=0 to mirror the convention used by the other observed-only ESM files in this rig (impervious_runoff.esm, soil_water_content_calc.esm, etc.).\n\nTolerance rationale (model-level rel=1e-9): observed-only algebraic system (no ODE integration); each equation is a single addition, so roundoff is at the IEEE-754 ULP level (~1e-16). 1e-9 leaves comfortable headroom above ULP roundoff and matches the convention used by sibling observed-only files (soil_water_content_calc.esm uses 1e-9 for analogous algebraic-sum equations). Tighter `abs: 1e-12` is asserted on outputs that are exactly zero by construction so the assertion does not silently accept a stuck-at-1e-3 regression."
},
"tolerance": {
"rel": 1e-09
},
"variables": {
"q_grnd_ice": {
"type": "parameter",
"units": "kg/(m^2*s)",
"default": 0.0,
"description": "Solid precipitation reaching surface"
},
"q_grnd_liq": {
"type": "parameter",
"units": "kg/(m^2*s)",
"default": 0.0,
"description": "Liquid precipitation reaching surface"
},
"q_frost": {
"type": "parameter",
"units": "kg/(m^2*s)",
"default": 0.0,
"description": "Frost rate (atmospheric water vapor deposition as ice on snow surface)"
},
"q_dew": {
"type": "parameter",
"units": "kg/(m^2*s)",
"default": 0.0,
"description": "Dew rate (atmospheric water vapor condensation as liquid on snow surface)"
},
"q_snwcp_ice": {
"type": "unknown",
"units": "kg/(m^2*s)",
"description": "Solid runoff from snow capping (Oleson Eq. 5.153): q_grnd_ice + q_frost"
},
"q_snwcp_liq": {
"type": "unknown",
"units": "kg/(m^2*s)",
"description": "Liquid runoff from snow capping (Oleson Eq. 5.154): q_grnd_liq + q_dew"
}
},
"equations": [
{
"lhs": "q_snwcp_ice",
"rhs": {
"op": "+",
"args": [
"q_grnd_ice",
"q_frost"
]
}
},
{
"lhs": "q_snwcp_liq",
"rhs": {
"op": "+",
"args": [
"q_grnd_liq",
"q_dew"
]
}
}
],
"tests": [
{
"id": "upstream_equation_verification",
"description": "Reproduces upstream `SnowCappingRunoff - Equation Verification` test (UrbanCanopy.jl test/hydrology_test.jl:551). Inputs: q_grnd_ice = 0.001, q_frost = 0.0005, q_grnd_liq = 0.002, q_dew = 0.0003. q_snwcp_ice = 0.001 + 0.0005 = 0.0015; q_snwcp_liq = 0.002 + 0.0003 = 0.0023. Anchors fidelity to the upstream Julia component at the same parameter values.",
"parameter_overrides": {
"q_grnd_ice": 0.001,
"q_grnd_liq": 0.002,
"q_frost": 0.0005,
"q_dew": 0.0003
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0015
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0023
}
]
},
{
"id": "all_zero_inputs",
"description": "Bone-dry / zero-flux limit: no precipitation, no frost, no dew. Both runoff streams must be exactly zero — exercises the additive-zero limit of Eqs. 5.153-5.154.",
"parameter_overrides": {
"q_grnd_ice": 0.0,
"q_grnd_liq": 0.0,
"q_frost": 0.0,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
}
]
},
{
"id": "snowfall_only_no_frost",
"description": "Solid precipitation with no frost (clear-sky snowfall, no surface deposition). q_snwcp_ice = q_grnd_ice = 0.005; q_snwcp_liq = 0 (no rain, no dew). Exercises the q_grnd_ice-only branch of Eq. 5.153 and confirms the liquid stream is decoupled from the solid stream.",
"parameter_overrides": {
"q_grnd_ice": 0.005,
"q_grnd_liq": 0.0,
"q_frost": 0.0,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.005
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
}
]
},
{
"id": "frost_only_no_snow",
"description": "Frost deposition with no solid precipitation (e.g. clear cold night, surface vapor flux freezes onto snow surface). q_snwcp_ice = q_frost = 0.0008; q_snwcp_liq = 0. Exercises the q_frost-only branch of Eq. 5.153 — frost contributes to the same solid runoff stream as snowfall.",
"parameter_overrides": {
"q_grnd_ice": 0.0,
"q_grnd_liq": 0.0,
"q_frost": 0.0008,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0008
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
}
]
},
{
"id": "rainfall_only_no_dew",
"description": "Liquid precipitation with no dew (e.g. rain on saturated snowpack). q_snwcp_ice = 0; q_snwcp_liq = q_grnd_liq = 0.003. Exercises the q_grnd_liq-only branch of Eq. 5.154 and confirms the solid stream is decoupled.",
"parameter_overrides": {
"q_grnd_ice": 0.0,
"q_grnd_liq": 0.003,
"q_frost": 0.0,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.003
}
]
},
{
"id": "dew_only_no_rain",
"description": "Dew deposition with no liquid precipitation (humid cold morning, vapor condenses on snow but doesn't freeze). q_snwcp_ice = 0; q_snwcp_liq = q_dew = 0.0004. Exercises the q_dew-only branch of Eq. 5.154 — dew feeds the liquid runoff stream alongside rainfall.",
"parameter_overrides": {
"q_grnd_ice": 0.0,
"q_grnd_liq": 0.0,
"q_frost": 0.0,
"q_dew": 0.0004
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0004
}
]
},
{
"id": "heavy_snowstorm",
"description": "Heavy snowstorm with concurrent frost (cold, humid storm conditions). q_grnd_ice = 0.02, q_frost = 0.001 → q_snwcp_ice = 0.021. Negligible liquid (q_grnd_liq = q_dew = 0). Stress-tests the high-flux solid regime where snowfall dominates and frost is a small concurrent contribution.",
"parameter_overrides": {
"q_grnd_ice": 0.02,
"q_grnd_liq": 0.0,
"q_frost": 0.001,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.021
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
}
]
},
{
"id": "rain_on_snow_with_dew",
"description": "Rain-on-snow event with concurrent dew (warm front over snowpack, humid). q_grnd_liq = 0.015, q_dew = 0.0002 → q_snwcp_liq = 0.0152. Negligible solid (q_grnd_ice = q_frost = 0). Stress-tests the high-flux liquid regime where rainfall dominates and dew is a small concurrent contribution.",
"parameter_overrides": {
"q_grnd_ice": 0.0,
"q_grnd_liq": 0.015,
"q_frost": 0.0,
"q_dew": 0.0002
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0152
}
]
},
{
"id": "mixed_phase_storm",
"description": "Mixed-phase storm (sleet/wet snow, transitional temperature) with both phases of precipitation and both surface deposition modes. q_grnd_ice = 0.004, q_frost = 0.0002, q_grnd_liq = 0.006, q_dew = 0.0001. q_snwcp_ice = 0.0042; q_snwcp_liq = 0.0061. Exercises the full four-input regime simultaneously and confirms the two output streams remain orthogonal (each independent of the other branch's inputs).",
"parameter_overrides": {
"q_grnd_ice": 0.004,
"q_grnd_liq": 0.006,
"q_frost": 0.0002,
"q_dew": 0.0001
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 0.0042
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0061
}
]
},
{
"id": "branch_independence",
"description": "Cross-coupling sanity check: very large solid-side inputs and zero liquid-side inputs. q_grnd_ice = 1.0, q_frost = 0.5 → q_snwcp_ice = 1.5 (huge); q_grnd_liq = q_dew = 0 → q_snwcp_liq must remain exactly 0. Confirms the two branches do not leak into each other through any spurious coupling — solid mass on one channel cannot show up as liquid runoff on the other.",
"parameter_overrides": {
"q_grnd_ice": 1.0,
"q_grnd_liq": 0.0,
"q_frost": 0.5,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"assertions": [
{
"variable": "q_snwcp_ice",
"time": 0.0,
"expected": 1.5
},
{
"variable": "q_snwcp_liq",
"time": 0.0,
"expected": 0.0,
"tolerance": {
"abs": 1e-12
}
}
]
}
],
"analyses": [
{
"id": "ice_runoff_vs_snowfall_with_frost",
"description": "Sweep solid precipitation rate q_grnd_ice across a typical CLMU range with a small fixed frost contribution (q_frost = 0.0005 kg/(m^2*s)). q_snwcp_ice = q_grnd_ice + 0.0005 — a unit-slope line offset by the frost term, surfacing Eq. 5.153 directly. Liquid-side inputs held at zero so the liquid stream is identically zero across the sweep.",
"initial_state": {},
"parameters": {
"q_grnd_liq": 0.0,
"q_frost": 0.0005,
"q_dew": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"parameter_sweep": {
"type": "cartesian",
"dimensions": [
{
"parameter": "q_grnd_ice",
"range": {
"start": 0.0,
"stop": 0.02,
"count": 21,
"scale": "linear"
}
}
]
},
"plots": [
{
"id": "q_snwcp_ice_curve",
"type": "line",
"description": "q_snwcp_ice vs q_grnd_ice (frost = 0.0005): unit-slope line offset by the frost term per Eq. 5.153.",
"x": {
"variable": "q_grnd_ice",
"label": "q_grnd_ice (kg/(m^2*s))"
},
"y": {
"variable": "q_snwcp_ice",
"label": "q_snwcp_ice (kg/(m^2*s))"
}
}
]
},
{
"id": "liq_runoff_phase_partition",
"description": "Joint sweep over q_grnd_liq and q_dew at fixed solid-side zero. Surfaces the perfectly additive plane q_snwcp_liq = q_grnd_liq + q_dew (Eq. 5.154) — iso-runoff contours are 45-degree lines in the (q_grnd_liq, q_dew) plane. Visualizes the equal-weighting between the two liquid sources (rain and dew contribute identically per unit flux).",
"initial_state": {},
"parameters": {
"q_grnd_ice": 0.0,
"q_frost": 0.0
},
"time_span": {
"start": 0.0,
"end": 1.0
},
"parameter_sweep": {
"type": "cartesian",
"dimensions": [
{
"parameter": "q_grnd_liq",
"range": {
"start": 0.0,
"stop": 0.01,
"count": 11,
"scale": "linear"
}
},
{
"parameter": "q_dew",
"range": {
"start": 0.0,
"stop": 0.001,
"count": 11,
"scale": "linear"
}
}
]
},
"plots": [
{
"id": "q_snwcp_liq_heatmap",
"type": "heatmap",
"description": "q_snwcp_liq as a function of liquid precipitation and dew rates: planar additive surface per Eq. 5.154.",
"x": {
"variable": "q_grnd_liq",
"label": "q_grnd_liq (kg/(m^2*s))"
},
"y": {
"variable": "q_dew",
"label": "q_dew (kg/(m^2*s))"
},
"value": {
"variable": "q_snwcp_liq",
"reduce": "final"
}
}
]
}
]
}