AquiferWaterBalance

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/hydrology.jl:791\nUpstream `AquiferWaterBalance` is an MTK `@component` whose two inputs (q_recharge, q_drai) are `@parameters` (driven by a parent soil-column / drainage coupler) and whose single output (dW_a) is a time-indexed `@variable` with one algebraic equation and no derivatives. Identical structure preserved here.\n\nPhysical context: per Oleson Eq. 5.143, when the water table lies below the soil column the aquifer water W_a (kg/m^2) is updated as dW_a/dt = q_recharge - q_drai. This component computes the *rate* (dW_a, kg/(m^2*s)); the actual integration of W_a is performed by the parent column model that couples this component to the recharge and drainage flux producers. Since 1 mm water = 1 kg/m^2, the kg/m^2 storage and kg/(m^2*s) rate units are unit-consistent without conversion.\n\nObservability classification: this component is functionally observed-only — dW_a is given by a single subtraction of two parameters. The `(t)` time index has no role since there is no derivative on the LHS of the equation. 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 directory (impervious_water_balance.esm, soil_water_content_calc.esm, snow_compaction.esm).\n\nTolerance rationale (model-level rel=1e-9): observed-only algebraic system (no ODE integration); the equation is a single IEEE-754 subtraction so worst-case roundoff is ~1 ULP ≈ 1e-16. 1e-9 leaves ~7 orders of magnitude of headroom above ULP roundoff and is well below any plausible physical-discrimination scale on aquifer recharge/drainage flux densities (typical CLMU values fall in the 1e-8 to 1e-4 kg/(m^2*s) range). Tests that yield exact algebraic zeros use `abs: 1e-15` to assert IEEE-754 zero."
  },
  "tolerance": {
    "rel": 1e-09
  },
  "variables": {
    "q_recharge": {
      "type": "parameter",
      "units": "kg/(m^2*s)",
      "default": 0.0,
      "description": "Recharge rate to aquifer"
    },
    "q_drai": {
      "type": "parameter",
      "units": "kg/(m^2*s)",
      "default": 0.0,
      "description": "Sub-surface drainage rate"
    },
    "dW_a": {
      "type": "unknown",
      "units": "kg/(m^2*s)",
      "description": "Rate of change of aquifer water (Oleson Eq. 5.143): dW_a = q_recharge - q_drai"
    }
  },
  "equations": [
    {
      "lhs": "dW_a",
      "rhs": {
        "op": "-",
        "args": [
          "q_recharge",
          "q_drai"
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "all_zero",
      "description": "Quiescent state — no recharge, no drainage. dW_a must be exactly zero. Exercises the additive-zero limit of Eq. 5.143.",
      "parameter_overrides": {
        "q_recharge": 0.0,
        "q_drai": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-15
          }
        }
      ]
    },
    {
      "id": "recharge_only",
      "description": "Pure recharge with no drainage (q_recharge = 1e-5 kg/(m^2*s), q_drai = 0). dW_a must equal q_recharge — a wetting-front state where the aquifer is gaining water from above with no lateral drainage outflow.",
      "parameter_overrides": {
        "q_recharge": 1e-05,
        "q_drai": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 1e-05
        }
      ]
    },
    {
      "id": "drainage_only",
      "description": "Pure drainage with no recharge (q_recharge = 0, q_drai = 2e-5 kg/(m^2*s)). dW_a = -q_drai = -2e-5 — a dry-down state where the aquifer is losing water to lateral drainage with no incoming recharge. Verifies that drainage enters with the correct (negative) sign.",
      "parameter_overrides": {
        "q_recharge": 0.0,
        "q_drai": 2e-05
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": -2e-05
        }
      ]
    },
    {
      "id": "balanced_recharge_drainage",
      "description": "Steady-state limit of Eq. 5.143: q_recharge = q_drai = 5e-6 kg/(m^2*s). dW_a = 0 to roundoff — exercises the cancellation case where the aquifer is in mass balance (a long-term equilibrium between recharge and drainage). Asserted at IEEE-754 zero (abs=1e-15).",
      "parameter_overrides": {
        "q_recharge": 5e-06,
        "q_drai": 5e-06
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-15
          }
        }
      ]
    },
    {
      "id": "net_recharge",
      "description": "Wet-period state — recharge exceeds drainage: q_recharge = 8e-6, q_drai = 3e-6 kg/(m^2*s). dW_a = 8e-6 - 3e-6 = 5e-6 kg/(m^2*s) (net gain). Represents a typical wet-season aquifer state where the column is recharging faster than it drains.",
      "parameter_overrides": {
        "q_recharge": 8e-06,
        "q_drai": 3e-06
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 5e-06
        }
      ]
    },
    {
      "id": "net_drainage",
      "description": "Dry-period state — drainage exceeds recharge: q_recharge = 2e-6, q_drai = 7e-6 kg/(m^2*s). dW_a = 2e-6 - 7e-6 = -5e-6 kg/(m^2*s) (net loss). Represents a typical dry-season aquifer state where the column is losing water to lateral drainage faster than it is being recharged from above.",
      "parameter_overrides": {
        "q_recharge": 2e-06,
        "q_drai": 7e-06
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": -5e-06
        }
      ]
    },
    {
      "id": "high_flux_storm_recharge",
      "description": "Intense post-storm recharge episode (q_recharge = 1e-3 kg/(m^2*s), q_drai = 1e-4) representing the upper end of the plausible CLMU urban-soil percolation range. dW_a = 1e-3 - 1e-4 = 9e-4 kg/(m^2*s). Exercises the formulation at flux magnitudes ~2 orders above the typical baseline to verify scale invariance of the simple subtraction.",
      "parameter_overrides": {
        "q_recharge": 0.001,
        "q_drai": 0.0001
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 0.0009
        }
      ]
    },
    {
      "id": "low_flux_baseline",
      "description": "Low-flux baseline state (q_recharge = 1e-8, q_drai = 5e-9 kg/(m^2*s)) at the lower end of the plausible CLMU recharge range. dW_a = 5e-9 kg/(m^2*s). Exercises the formulation at small flux magnitudes to verify that the subtraction does not lose precision near the lower end of the dynamic range.",
      "parameter_overrides": {
        "q_recharge": 1e-08,
        "q_drai": 5e-09
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "dW_a",
          "time": 0.0,
          "expected": 5e-09
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "dW_a_vs_recharge_at_fixed_drainage",
      "description": "Net aquifer-storage rate as a function of recharge rate at fixed sub-surface drainage (q_drai = 5e-6 kg/(m^2*s)). The unit-slope linear dependence in Eq. 5.143 is visible: each kg/(m^2*s) of additional recharge raises dW_a by exactly 1 kg/(m^2*s). The line crosses zero at q_recharge = q_drai (the steady-state balance point). Sweeps q_recharge over the typical CLMU range (0 to 2e-5 kg/(m^2*s)).",
      "initial_state": {},
      "parameters": {
        "q_drai": 5e-06
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "q_recharge",
            "range": {
              "start": 0.0,
              "stop": 2e-05,
              "count": 21,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "dW_a_vs_q_recharge",
          "type": "line",
          "description": "dW_a vs q_recharge at fixed q_drai = 5e-6 — linear with intercept = -q_drai.",
          "x": {
            "variable": "q_recharge",
            "label": "q_recharge (kg/(m^2*s))"
          },
          "y": {
            "variable": "dW_a",
            "label": "dW_a (kg/(m^2*s))"
          }
        }
      ]
    },
    {
      "id": "dW_a_recharge_drainage_grid",
      "description": "Joint sweep over q_recharge and q_drai — surfaces the iso-dW_a contours of Eq. 5.143 across the (recharge, drainage) plane. The contour dW_a = 0 is the steady-state line q_recharge = q_drai (the diagonal); points above it represent net aquifer gain, points below it represent net aquifer loss.",
      "initial_state": {},
      "parameters": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "q_recharge",
            "range": {
              "start": 0.0,
              "stop": 1e-05,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "q_drai",
            "range": {
              "start": 0.0,
              "stop": 1e-05,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "dW_a_heatmap",
          "type": "heatmap",
          "description": "dW_a as a function of q_recharge and q_drai — the dW_a = 0 isocontour is the diagonal q_recharge = q_drai.",
          "x": {
            "variable": "q_recharge",
            "label": "q_recharge (kg/(m^2*s))"
          },
          "y": {
            "variable": "q_drai",
            "label": "q_drai (kg/(m^2*s))"
          },
          "value": {
            "variable": "dW_a",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}