TotalPhaseChangeEnergy

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/roof_wall_road_snow_temperatures.jl:1071\nUpstream `TotalPhaseChangeEnergy` is an MTK `@component` whose two inputs (E_p1S, E_p_layers) are `@parameters` and whose single output (E_p_total) is a time-indexed `@variable` with one algebraic equation (Eq. 4.72). Identical equation structure preserved here.\n\nThe upstream component declares no `@constants` — both inputs are upstream-component outputs (E_p1S from `SnowMeltNoLayers` per Eq. 4.71; E_p_layers from a column-sum over `LayerPhaseChangeEnergy` per Eq. 4.73). The output is the additive identity E_p_total = E_p1S + E_p_layers — the simplest possible aggregation in the urban canopy temps suite.\n\nObservability classification: this component is functionally observed-only — the single output variable is given by a single algebraic equation in terms of the two 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 in this rig (snow_capping_runoff.esm, snow_melt_no_layers.esm, ideal_gas.esm).\n\nTolerance rationale (model-level rel=1e-9): observed-only single-equation algebraic system (no ODE integration); the 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 (snow_capping_runoff.esm uses 1e-9 for the analogous additive-identity equations of Eqs. 5.153-5.154). 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": {
    "E_p1S": {
      "type": "parameter",
      "units": "W/m^2",
      "default": 0.0,
      "description": "Surface snow melt energy (Oleson Eq. 4.71 — output of SnowMeltNoLayers)"
    },
    "E_p_layers": {
      "type": "parameter",
      "units": "W/m^2",
      "default": 0.0,
      "description": "Sum of per-layer phase change energies (Oleson Eq. 4.73 — column sum over LayerPhaseChangeEnergy outputs)"
    },
    "E_p_total": {
      "type": "unknown",
      "units": "W/m^2",
      "description": "Total phase change energy for the column (Oleson Eq. 4.72): E_p1S + E_p_layers"
    }
  },
  "equations": [
    {
      "lhs": "E_p_total",
      "rhs": {
        "op": "+",
        "args": [
          "E_p1S",
          "E_p_layers"
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "upstream_equation_verification",
      "description": "Reproduces upstream `TotalPhaseChangeEnergy - Equation Verification` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:1254). Inputs: E_p1S = 50.0 W/m^2, E_p_layers = 30.0 W/m^2. E_p_total = 50.0 + 30.0 = 80.0. Anchors fidelity to the upstream Julia component at the same parameter values.",
      "parameter_overrides": {
        "E_p1S": 50.0,
        "E_p_layers": 30.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 80.0
        }
      ]
    },
    {
      "id": "all_zero_inputs",
      "description": "No phase change anywhere (no surface melt, no layer phase change). E_p_total must be exactly zero — exercises the additive-zero limit of Eq. 4.72.",
      "parameter_overrides": {
        "E_p1S": 0.0,
        "E_p_layers": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        }
      ]
    },
    {
      "id": "surface_only",
      "description": "Surface snow melt with no subsurface layer phase change (typical for a thin-snow no-layer regime where SnowMeltNoLayers fires but the column has no frozen layers). E_p1S = 200 W/m^2, E_p_layers = 0 → E_p_total = 200. Exercises the E_p1S-only branch.",
      "parameter_overrides": {
        "E_p1S": 200.0,
        "E_p_layers": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 200.0
        }
      ]
    },
    {
      "id": "layers_only",
      "description": "Subsurface phase change with no surface snow melt (e.g. soil freezing/thawing under bare ground or under a snow-free road surface). E_p1S = 0, E_p_layers = 75 → E_p_total = 75. Exercises the E_p_layers-only branch.",
      "parameter_overrides": {
        "E_p1S": 0.0,
        "E_p_layers": 75.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 75.0
        }
      ]
    },
    {
      "id": "freezing_branch",
      "description": "Negative phase change energies — the upstream component does not constrain sign of either input. In the freezing branch (water → ice, releasing latent heat), upstream components produce negative E_p1S and/or E_p_layers. E_p1S = -40, E_p_layers = -60 → E_p_total = -100. Confirms the addition is sign-preserving and that no spurious clamp has been introduced.",
      "parameter_overrides": {
        "E_p1S": -40.0,
        "E_p_layers": -60.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": -100.0
        }
      ]
    },
    {
      "id": "mixed_sign_cancellation",
      "description": "Mixed sign — surface melting (E_p1S > 0) coincident with subsurface freezing (E_p_layers < 0). Exercises cross-sign cancellation: E_p1S = 100, E_p_layers = -100 → E_p_total = 0 by construction. Verifies the additive identity does not lose precision in the cancelling-magnitudes regime.",
      "parameter_overrides": {
        "E_p1S": 100.0,
        "E_p_layers": -100.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-09
          }
        }
      ]
    },
    {
      "id": "high_magnitude",
      "description": "Stress-test the high-flux regime: heavy melt event with concurrent strong subsurface phase change. E_p1S = 1500, E_p_layers = 800 → E_p_total = 2300. Magnitudes representative of a peak-melt afternoon under high solar forcing on a deep snowpack.",
      "parameter_overrides": {
        "E_p1S": 1500.0,
        "E_p_layers": 800.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "E_p_total",
          "time": 0.0,
          "expected": 2300.0
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "total_vs_surface_with_layer_offset",
      "description": "Sweep E_p1S across a typical CLMU range with a small fixed subsurface layer phase change contribution (E_p_layers = 50 W/m^2). E_p_total = E_p1S + 50 — a unit-slope line offset by the layer term, surfacing Eq. 4.72 directly.",
      "initial_state": {},
      "parameters": {
        "E_p_layers": 50.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "E_p1S",
            "range": {
              "start": -200.0,
              "stop": 1500.0,
              "count": 18,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "E_p_total_curve",
          "type": "line",
          "description": "E_p_total vs E_p1S (E_p_layers = 50): unit-slope line offset by the layer term per Eq. 4.72.",
          "x": {
            "variable": "E_p1S",
            "label": "E_p1S (W/m^2)"
          },
          "y": {
            "variable": "E_p_total",
            "label": "E_p_total (W/m^2)"
          }
        }
      ]
    },
    {
      "id": "two_d_sweep_surface_layers",
      "description": "Joint sweep over E_p1S and E_p_layers covering the four sign-combinations (melt/freeze on surface vs subsurface). Surfaces the planar additive surface E_p_total = E_p1S + E_p_layers per Eq. 4.72 — iso-energy contours are 45-degree lines.",
      "initial_state": {},
      "parameters": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "E_p1S",
            "range": {
              "start": -500.0,
              "stop": 1500.0,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "E_p_layers",
            "range": {
              "start": -500.0,
              "stop": 1000.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "E_p_total_heatmap",
          "type": "heatmap",
          "description": "E_p_total as a function of surface and column-summed layer phase change energies: planar additive surface per Eq. 4.72.",
          "x": {
            "variable": "E_p1S",
            "label": "E_p1S (W/m^2)"
          },
          "y": {
            "variable": "E_p_layers",
            "label": "E_p_layers (W/m^2)"
          },
          "value": {
            "variable": "E_p_total",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}