SnowSoilBlendedHeatCapacity

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/roof_wall_road_snow_temperatures.jl:1003\nUpstream `SnowSoilBlendedHeatCapacity` is an MTK `@component` whose three inputs (c_soil, W_sno, Δz) are `@parameters` and whose single output (c_blended) is a time-indexed `@variable` with one algebraic equation (Eq. 4.88). Identical equation structure preserved here.\n\nThe upstream component declares one `@constant`: C_ice = 2117.27 J/(kg*K) (specific heat of ice, Oleson Table 1.4). It is encoded here as a zero-default-overridden parameter with the upstream value, matching the convention used by sibling observed-only ESM files in this rig that translate `@constants` to fixed-default parameters (snow_melt_no_layers.esm encodes L_f, zero_kgm2, zero_m the same way).\n\nUnicode `Δz` (top layer thickness) is preserved from upstream — the schema's identifier pattern allows it and other ESM components in this rig already use unicode delta in identifiers (e.g. snow_melt_no_layers.esm uses `Δt`).\n\nObservability classification: this component is functionally observed-only — the single output variable 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 sibling observed-only ESM files (snow_melt_no_layers.esm, total_phase_change_energy.esm).\n\nTolerance rationale (model-level rel=1e-10): observed-only single-equation algebraic system (no ODE integration); the equation is one division, one multiplication, and one addition, so roundoff is at the IEEE-754 ULP level (~1e-16). The upstream tests use `rtol = 1.0e-10` (test/roof_wall_road_snow_temperatures_test.jl:1165, 1183) and we mirror that for fidelity. Tighter `abs: 1e-9` is asserted on outputs that take their full magnitude from c_soil so the assertion does not silently accept a stuck-at-zero regression."
  },
  "tolerance": {
    "rel": 1e-10
  },
  "variables": {
    "c_soil": {
      "type": "parameter",
      "units": "J/(m^3*K)",
      "default": 0.0,
      "description": "Soil volumetric heat capacity (Oleson Eq. 4.85 — input from soil thermal properties)"
    },
    "W_sno": {
      "type": "parameter",
      "units": "kg/m^2",
      "default": 0.0,
      "description": "Snow mass (water-equivalent per m^2)"
    },
    "Δz": {
      "type": "parameter",
      "units": "m",
      "default": 1.0,
      "description": "Top layer thickness (must be > 0; 1.0 m default chosen so divide-by-Δz is well-defined when other parameters are at their zero defaults)"
    },
    "C_ice": {
      "type": "parameter",
      "units": "J/(kg*K)",
      "default": 2117.27,
      "description": "Specific heat of ice (Oleson Table 1.4 — 2117.27 J/(kg*K))"
    },
    "c_blended": {
      "type": "unknown",
      "units": "J/(m^3*K)",
      "description": "Blended snow/soil volumetric heat capacity (Oleson Eq. 4.88): c_soil + C_ice * W_sno / Δz"
    }
  },
  "equations": [
    {
      "lhs": "c_blended",
      "rhs": {
        "op": "+",
        "args": [
          "c_soil",
          {
            "op": "/",
            "args": [
              {
                "op": "*",
                "args": [
                  "C_ice",
                  "W_sno"
                ]
              },
              "Δz"
            ]
          }
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "upstream_equation_verification",
      "description": "Reproduces upstream `SnowSoilBlendedHeatCapacity - Equation Verification` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:1145-1166). Inputs: c_soil = 2.0e6 J/(m^3*K), W_sno = 5.0 kg/m^2, Δz = 0.1 m. Expected c_blended = 2.0e6 + 2117.27 * 5.0 / 0.1 = 2.0e6 + 105863.5 = 2105863.5 J/(m^3*K). Anchors fidelity to the upstream Julia component at the same parameter values.",
      "parameter_overrides": {
        "c_soil": 2000000.0,
        "W_sno": 5.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 2105863.5
        }
      ]
    },
    {
      "id": "upstream_no_snow",
      "description": "Reproduces upstream `SnowSoilBlendedHeatCapacity - No Snow` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:1168-1184). With W_sno = 0, the snow contribution vanishes and c_blended = c_soil exactly. Inputs: c_soil = 2.0e6, W_sno = 0, Δz = 0.1.",
      "parameter_overrides": {
        "c_soil": 2000000.0,
        "W_sno": 0.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 2000000.0,
          "tolerance": {
            "abs": 1e-09
          }
        }
      ]
    },
    {
      "id": "snow_only_zero_soil",
      "description": "No soil contribution (c_soil = 0, e.g. an idealized pure-snow regime): c_blended = C_ice * W_sno / Δz = 2117.27 * 10 / 0.05 = 423454.0 J/(m^3*K). Exercises the snow-only branch of Eq. 4.88.",
      "parameter_overrides": {
        "c_soil": 0.0,
        "W_sno": 10.0,
        "Δz": 0.05
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 423454.0
        }
      ]
    },
    {
      "id": "thick_layer_thin_snow",
      "description": "Deep top layer (Δz = 1.0 m) with thin snow (W_sno = 1 kg/m^2): the snow contribution C_ice*W_sno/Δz = 2117.27 J/(m^3*K) is small relative to a typical c_soil of 2.0e6, so c_blended ≈ c_soil. Confirms the Δz scaling: doubling Δz halves the snow contribution per Eq. 4.88.",
      "parameter_overrides": {
        "c_soil": 2000000.0,
        "W_sno": 1.0,
        "Δz": 1.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 2002117.27
        }
      ]
    },
    {
      "id": "thin_layer_heavy_snow",
      "description": "Thin top layer (Δz = 0.01 m) with heavy snow (W_sno = 50 kg/m^2): snow contribution = 2117.27 * 50 / 0.01 = 1.0586350e7, dominating the c_soil = 2.0e6 baseline. c_blended = 2.0e6 + 1.0586350e7 = 1.2586350e7 J/(m^3*K). Exercises the snow-dominated regime where the blended capacity is several times the dry-soil value.",
      "parameter_overrides": {
        "c_soil": 2000000.0,
        "W_sno": 50.0,
        "Δz": 0.01
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 12586350.0
        }
      ]
    },
    {
      "id": "high_soil_capacity",
      "description": "Saturated peat-like soil (c_soil = 4.0e6 J/(m^3*K), the upper end of the CLM soil-thermal-properties range) with moderate snow (W_sno = 5 kg/m^2, Δz = 0.1 m). c_blended = 4.0e6 + 2117.27 * 5 / 0.1 = 4105863.5. Confirms the additive structure scales correctly across the full c_soil range.",
      "parameter_overrides": {
        "c_soil": 4000000.0,
        "W_sno": 5.0,
        "Δz": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "c_blended",
          "time": 0.0,
          "expected": 4105863.5
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "blended_capacity_vs_W_sno",
      "description": "Sweep snow mass W_sno across the typical CLMU range (0-50 kg/m^2) at fixed c_soil = 2.0e6 and Δz = 0.05 m. c_blended = c_soil + (C_ice/Δz) * W_sno is a line of slope C_ice/Δz = 42345.4 J/(m^3*K)/(kg/m^2), surfacing the linear dependence in Eq. 4.88.",
      "initial_state": {},
      "parameters": {
        "c_soil": 2000000.0,
        "Δz": 0.05
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "W_sno",
            "range": {
              "start": 0.0,
              "stop": 50.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "c_blended_curve",
          "type": "line",
          "description": "c_blended vs W_sno: linear rise of slope C_ice/Δz above the c_soil baseline per Eq. 4.88.",
          "x": {
            "variable": "W_sno",
            "label": "W_sno (kg/m^2)"
          },
          "y": {
            "variable": "c_blended",
            "label": "c_blended (J/(m^3*K))"
          }
        }
      ]
    },
    {
      "id": "two_d_sweep_W_dz",
      "description": "Joint sweep over W_sno and Δz at fixed c_soil = 2.0e6 J/(m^3*K). The snow contribution C_ice*W_sno/Δz forms a hyperbolic surface in (W_sno, Δz) — large for thick snow on thin layers, small for thin snow on thick layers. Iso-c_blended contours are lines of constant W_sno/Δz.",
      "initial_state": {},
      "parameters": {
        "c_soil": 2000000.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "W_sno",
            "range": {
              "start": 0.0,
              "stop": 50.0,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "Δz",
            "range": {
              "start": 0.01,
              "stop": 0.5,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "c_blended_heatmap",
          "type": "heatmap",
          "description": "c_blended as a function of snow mass and top-layer thickness: hyperbolic snow-contribution surface superposed on the c_soil baseline per Eq. 4.88.",
          "x": {
            "variable": "W_sno",
            "label": "W_sno (kg/m^2)"
          },
          "y": {
            "variable": "Δz",
            "label": "Δz (m)"
          },
          "value": {
            "variable": "c_blended",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}