SoilWaterContentCalc

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/hydrology.jl:1091\nUpstream `SoilWaterContentCalc` is an MTK `@component` whose three inputs (w_liq, w_ice, Δz) are `@parameters` and whose single output (θ_i) is a time-indexed `@variable` with one algebraic equation (no derivative). Identical structure preserved here.\n\nThe upstream component declares two `@constants`: ρ_liq = 1000.0 kg/m^3 (density of liquid water, Oleson Table 1.4) and ρ_ice = 917.0 kg/m^3 (density of ice, Oleson Table 1.4). Following the convention established by the sibling files in this directory (snow_layer_combination.esm, snow_compaction.esm, snow_melt_no_layers.esm) these are encoded as parameters with the upstream default values; they are physical constants not intended to be tuned.\n\nUnicode `Δz`, `θ_i`, `ρ_liq`, `ρ_ice` are preserved from upstream — components/urban_canopy/temps/snow_melt_no_layers.esm already established that unicode identifiers are the rig convention for new urban_canopy migrations and the canonical Python runner accepts them.\n\nObservability classification: this component is functionally observed-only — θ_i is given by a single algebraic equation 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.\n\nTolerance rationale (model-level rel=1e-9): observed-only algebraic system (no ODE integration); the equation is two divisions and one addition — three IEEE-754 float64 operations — so roundoff is ~1e-15. 1e-9 leaves comfortable headroom above ULP roundoff and is well below any plausible physical-discrimination scale on volumetric soil water content (which is bounded in [0, ~0.6] m^3/m^3 for any realistic CLMU soil column and typically known to ~1e-3)."
  },
  "tolerance": {
    "rel": 1e-09
  },
  "variables": {
    "w_liq": {
      "type": "parameter",
      "units": "kg/m^2",
      "default": 0.0,
      "description": "Mass of liquid water in soil layer"
    },
    "w_ice": {
      "type": "parameter",
      "units": "kg/m^2",
      "default": 0.0,
      "description": "Mass of ice in soil layer"
    },
    "Δz": {
      "type": "parameter",
      "units": "m",
      "default": 0.1,
      "description": "Soil layer thickness"
    },
    "ρ_liq": {
      "type": "parameter",
      "units": "kg/m^3",
      "default": 1000.0,
      "description": "Density of liquid water (Oleson 2010 Table 1.4 — 1000.0 kg/m^3)"
    },
    "ρ_ice": {
      "type": "parameter",
      "units": "kg/m^3",
      "default": 917.0,
      "description": "Density of ice (Oleson 2010 Table 1.4 — 917.0 kg/m^3)"
    },
    "θ_i": {
      "type": "unknown",
      "units": "m^3/m^3",
      "description": "Total volumetric soil water content (Oleson Eq. 5.137): w_liq/(Δz*ρ_liq) + w_ice/(Δz*ρ_ice)"
    }
  },
  "equations": [
    {
      "lhs": "θ_i",
      "rhs": {
        "op": "+",
        "args": [
          {
            "op": "/",
            "args": [
              "w_liq",
              {
                "op": "*",
                "args": [
                  "Δz",
                  "ρ_liq"
                ]
              }
            ]
          },
          {
            "op": "/",
            "args": [
              "w_ice",
              {
                "op": "*",
                "args": [
                  "Δz",
                  "ρ_ice"
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "dry_layer",
      "description": "Bone-dry soil layer (w_liq = w_ice = 0, Δz = 0.1 m). The total volumetric water content must be exactly zero — exercises the additive-zero limit of Eq. 5.137.",
      "parameter_overrides": {
        "w_liq": 0.0,
        "w_ice": 0.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        }
      ]
    },
    {
      "id": "pure_liquid_porosity_05",
      "description": "Pure-liquid limit: w_liq = 50 kg/m^2 in a 0.1 m layer with no ice. θ_i = 50 / (0.1 * 1000) = 0.5 m^3/m^3 — equivalent to a 50%-saturated mineral soil. Verifies the liquid-only branch of Eq. 5.137 and the ρ_liq density reference value.",
      "parameter_overrides": {
        "w_liq": 50.0,
        "w_ice": 0.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.5
        }
      ]
    },
    {
      "id": "pure_ice_full_volume",
      "description": "Pure-ice limit: w_ice = 91.7 kg/m^2 in a 0.1 m layer (= ρ_ice * Δz, i.e. the layer is 100% ice by volume). θ_i = 91.7 / (0.1 * 917) = 1.0 m^3/m^3 — exercises the ice-only branch and confirms that ρ_ice = 917.0 kg/m^3 is the upstream Oleson Table 1.4 value (a different ice density would shift this assertion).",
      "parameter_overrides": {
        "w_liq": 0.0,
        "w_ice": 91.7,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 1.0
        }
      ]
    },
    {
      "id": "mixed_phase_typical",
      "description": "Mixed-phase soil layer (w_liq = 30 kg/m^2, w_ice = 20 kg/m^2, Δz = 0.1 m) — the canonical Eq. 5.137 use case where both phases coexist (e.g. partially-frozen near-surface soil during a freeze-thaw transition). θ_i = 30/100 + 20/91.7 ≈ 0.5181 m^3/m^3.",
      "parameter_overrides": {
        "w_liq": 30.0,
        "w_ice": 20.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.5181025081788441
        }
      ]
    },
    {
      "id": "thick_layer_partial",
      "description": "Deeper soil layer (Δz = 0.5 m, root-zone depth) with modest moisture (w_liq = 25, w_ice = 5 kg/m^2). θ_i = 25/(0.5*1000) + 5/(0.5*917) = 0.05 + 0.01091 ≈ 0.0609 m^3/m^3. Exercises the layer-thickness scaling: a 5× deeper layer with the same masses yields ≈1/5 the volumetric content.",
      "parameter_overrides": {
        "w_liq": 25.0,
        "w_ice": 5.0,
        "Δz": 0.5
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.060905125408942204
        }
      ]
    },
    {
      "id": "near_saturation_mixed",
      "description": "Near-saturated mixed-phase layer (w_liq = 40, w_ice = 5 kg/m^2, Δz = 0.1 m). θ_i ≈ 0.455 m^3/m^3 — close to a typical CLMU mineral-soil porosity θ_sat ≈ 0.45–0.50. Represents a wet soil column in a freezing/thawing condition.",
      "parameter_overrides": {
        "w_liq": 40.0,
        "w_ice": 5.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.45452562704471106
        }
      ]
    },
    {
      "id": "thin_skin_layer",
      "description": "Thin surface skin layer (Δz = 0.02 m, e.g. CLM top sub-layer) with w_liq = 5, w_ice = 1 kg/m^2. θ_i = 5/(0.02*1000) + 1/(0.02*917) = 0.25 + 0.0545 ≈ 0.305 m^3/m^3. Exercises the small-Δz regime where each phase's contribution is amplified by the thin layer thickness.",
      "parameter_overrides": {
        "w_liq": 5.0,
        "w_ice": 1.0,
        "Δz": 0.02
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.30452562704471103
        }
      ]
    },
    {
      "id": "deep_layer_liquid_only",
      "description": "Deep root-zone layer (Δz = 0.5 m) holding 100 kg/m^2 of liquid only. θ_i = 100/500 = 0.2 m^3/m^3 — moderately moist deep soil with no frozen content (typical summer mid-column state).",
      "parameter_overrides": {
        "w_liq": 100.0,
        "w_ice": 0.0,
        "Δz": 0.5
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.2
        }
      ]
    },
    {
      "id": "ice_dominated_winter",
      "description": "Ice-dominated winter soil layer (w_liq = 30, w_ice = 60 kg/m^2, Δz = 0.1 m) — the soil is mostly frozen with a residual unfrozen-water film. θ_i = 30/100 + 60/91.7 ≈ 0.954 m^3/m^3 (near the upper limit of physical-realism). Stress-tests the ice-dominated branch where the ρ_ice path carries most of the signal.",
      "parameter_overrides": {
        "w_liq": 30.0,
        "w_ice": 60.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.9543075245365322
        }
      ]
    },
    {
      "id": "shallow_oleson_typical",
      "description": "Shallow CLM-style sub-layer (Δz = 0.025 m) with mixed phases (w_liq = 7.5, w_ice = 2.5 kg/m^2). θ_i = 7.5/(0.025*1000) + 2.5/(0.025*917) = 0.3 + 0.1091 ≈ 0.409 m^3/m^3. Reproduces a near-surface CLMU snow-soil interface where the layer is thin and a partial-melt event drives mixed-phase moisture.",
      "parameter_overrides": {
        "w_liq": 7.5,
        "w_ice": 2.5,
        "Δz": 0.025
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "θ_i",
          "time": 0.0,
          "expected": 0.409051254089422
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "theta_vs_layer_thickness",
      "description": "Volumetric water content as a function of layer thickness Δz (held fixed mass loading w_liq = 30 kg/m^2, w_ice = 10 kg/m^2). The 1/Δz dependence in Eq. 5.137 is visible: thinner layers concentrate the same mass into a smaller volume and produce higher θ_i. Sweeps Δz over the typical CLMU sub-layer-to-root-zone range (0.01 m to 0.5 m).",
      "initial_state": {},
      "parameters": {
        "w_liq": 30.0,
        "w_ice": 10.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "Δz",
            "range": {
              "start": 0.01,
              "stop": 0.5,
              "count": 25,
              "scale": "log"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "theta_vs_dz",
          "type": "line",
          "description": "θ_i vs Δz (log x) — inverse relationship per Eq. 5.137.",
          "x": {
            "variable": "Δz",
            "label": "Layer thickness (m, log scale)"
          },
          "y": {
            "variable": "θ_i",
            "label": "θ_i (m^3/m^3)"
          }
        }
      ]
    },
    {
      "id": "theta_phase_partition_sweep",
      "description": "Joint sweep over liquid and ice mass loadings at fixed Δz = 0.1 m. Highlights the asymmetric weighting between the two phases (1/ρ_liq < 1/ρ_ice, so ice contributes ~9% more per kg than liquid does). The 2-D heatmap surfaces the iso-θ_i contours of Eq. 5.137 across the freeze/thaw envelope.",
      "initial_state": {},
      "parameters": {
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "w_liq",
            "range": {
              "start": 0.0,
              "stop": 50.0,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "w_ice",
            "range": {
              "start": 0.0,
              "stop": 50.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "theta_heatmap",
          "type": "heatmap",
          "description": "θ_i as a function of liquid and ice mass loadings at Δz = 0.1 m.",
          "x": {
            "variable": "w_liq",
            "label": "w_liq (kg/m^2)"
          },
          "y": {
            "variable": "w_ice",
            "label": "w_ice (kg/m^2)"
          },
          "value": {
            "variable": "θ_i",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}