WasteHeatAllocation

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/roof_wall_road_snow_temperatures.jl:561\nUpstream `WasteHeatAllocation` is an MTK `@component` with three `@parameters` (H_wasteheat, H_aircond, W_roof), four time-indexed `@variables` (H_wasteheat_prvrd, H_wasteheat_imprvrd, H_aircond_prvrd, H_aircond_imprvrd), and four algebraic equations (no derivatives). Identical equation structure preserved here. Upstream structural test (test/roof_wall_road_snow_temperatures_test.jl:477) asserts `length(equations(sys)) == 4` and `length(unknowns(sys)) == 4` — matched here.\n\nThe upstream component declares no `@constants` — all three inputs are upstream-component outputs (H_wasteheat and H_aircond are accumulated column-total fluxes from the urban building energy balance per Eqs. 4.55-4.56; W_roof is the roof areal fraction from the urban geometry tile-fractions submodel). The output structure is the simplest possible per-tile allocation: each of the four output variables equals one of the two anthropogenic flux totals divided by the non-roof areal fraction (1 - W_roof). Both road tiles (pervious and impervious) receive the same per-unit-area allocation by construction of Eq. 4.27 — this is the equal-distribution property explicitly verified by the upstream `Equal Distribution` test fixture.\n\nObservability classification: this component is functionally observed-only — the four output variables are each given by a single algebraic equation in terms of the parameters (the `(t)` time index has no role since there are no derivatives). 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_density.esm, snow_capping_runoff.esm, total_phase_change_energy.esm, heating_cooling_flux.esm).\n\nTolerance rationale (model-level rel=1e-9): observed-only algebraic system (no ODE integration); the equations involve only one division and one subtraction, both at IEEE-754 ULP precision (~1e-16). 1e-9 leaves comfortable headroom above ULP roundoff and matches the convention used by sibling observed-only files (total_phase_change_energy.esm uses 1e-9 for additive-identity equations; heating_cooling_flux.esm uses 1e-9 for the analogous Crank-Nicholson + ifelse equations of Eqs. 4.51-4.54). The upstream test asserts `rtol = 1e-10` (test/roof_wall_road_snow_temperatures_test.jl:506) — the walker uses `reltol=1e-10, abstol=1e-12` so the assertion tolerances here match. Tighter `abs: 1e-12` is asserted on outputs that are exactly zero by construction (zero-flux inputs) so the assertion does not silently accept a stuck-at-1e-3 regression.\n\nDomain constraint: W_roof is an areal fraction in [0, 1) — the equation is undefined at W_roof = 1 (entire tile is roof, no road to allocate heat to). The upstream component does not assert this guard, and neither does this `.esm` — it is the responsibility of the upstream geometry submodel to keep W_roof strictly less than 1. The test fixtures here sample W_roof in [0, 0.95] to stay well clear of the singularity."
  },
  "tolerance": {
    "rel": 1e-09
  },
  "variables": {
    "H_wasteheat": {
      "type": "parameter",
      "units": "W/m^2",
      "default": 0.0,
      "description": "Total anthropogenic waste heat (Oleson Eq. 4.55) — column-total per-unit-tile-area waste heat flux from the urban energy balance, to be allocated to the pervious and impervious road surfaces"
    },
    "H_aircond": {
      "type": "parameter",
      "units": "W/m^2",
      "default": 0.0,
      "description": "Total heat removed by air conditioning (Oleson Eq. 4.56) — column-total per-unit-tile-area air conditioning heat-removal flux, to be allocated to the pervious and impervious road surfaces"
    },
    "W_roof": {
      "type": "parameter",
      "units": "1",
      "default": 0.3,
      "description": "Roof areal fraction of the urban tile (dimensionless, in [0, 1)) — non-roof areal fraction (1 - W_roof) is the denominator that scales the per-unit-area allocation onto the two road tiles"
    },
    "H_wasteheat_prvrd": {
      "type": "unknown",
      "units": "W/m^2",
      "description": "Waste heat allocated to the pervious road (Oleson Eq. 4.27): H_wasteheat / (1 - W_roof)"
    },
    "H_wasteheat_imprvrd": {
      "type": "unknown",
      "units": "W/m^2",
      "description": "Waste heat allocated to the impervious road (Oleson Eq. 4.27): H_wasteheat / (1 - W_roof) — equal to H_wasteheat_prvrd by Eq. 4.27"
    },
    "H_aircond_prvrd": {
      "type": "unknown",
      "units": "W/m^2",
      "description": "Air conditioning heat removal allocated to the pervious road (Oleson Eq. 4.27): H_aircond / (1 - W_roof)"
    },
    "H_aircond_imprvrd": {
      "type": "unknown",
      "units": "W/m^2",
      "description": "Air conditioning heat removal allocated to the impervious road (Oleson Eq. 4.27): H_aircond / (1 - W_roof) — equal to H_aircond_prvrd by Eq. 4.27"
    }
  },
  "equations": [
    {
      "lhs": "H_wasteheat_prvrd",
      "rhs": {
        "op": "/",
        "args": [
          "H_wasteheat",
          {
            "op": "-",
            "args": [
              1.0,
              "W_roof"
            ]
          }
        ]
      }
    },
    {
      "lhs": "H_wasteheat_imprvrd",
      "rhs": {
        "op": "/",
        "args": [
          "H_wasteheat",
          {
            "op": "-",
            "args": [
              1.0,
              "W_roof"
            ]
          }
        ]
      }
    },
    {
      "lhs": "H_aircond_prvrd",
      "rhs": {
        "op": "/",
        "args": [
          "H_aircond",
          {
            "op": "-",
            "args": [
              1.0,
              "W_roof"
            ]
          }
        ]
      }
    },
    {
      "lhs": "H_aircond_imprvrd",
      "rhs": {
        "op": "/",
        "args": [
          "H_aircond",
          {
            "op": "-",
            "args": [
              1.0,
              "W_roof"
            ]
          }
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "upstream_equation_verification",
      "description": "Reproduces upstream `WasteHeatAllocation - Equation Verification` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:487). Inputs: H_wasteheat = 80.0 W/m^2, H_aircond = 20.0 W/m^2, W_roof = 0.3. Expected: each road tile gets H_wasteheat / (1 - W_roof) = 80.0 / 0.7 = 114.2857142857... W/m^2 of waste heat and H_aircond / (1 - W_roof) = 20.0 / 0.7 = 28.5714285714... W/m^2 of air-conditioning heat. Anchors fidelity to the upstream Julia component at the canonical fixture point.",
      "parameter_overrides": {
        "H_wasteheat": 80.0,
        "H_aircond": 20.0,
        "W_roof": 0.3
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 114.28571428571429
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 114.28571428571429
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 28.571428571428573
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 28.571428571428573
        }
      ]
    },
    {
      "id": "upstream_equal_distribution",
      "description": "Reproduces upstream `WasteHeatAllocation - Equal Distribution` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:514). Inputs: H_wasteheat = 50.0 W/m^2, H_aircond = 10.0 W/m^2, W_roof = 0.25. Each tile gets H_wasteheat / 0.75 = 66.6666... W/m^2 of waste heat and H_aircond / 0.75 = 13.3333... W/m^2 of air-conditioning heat. The two road tiles must receive identical allocations by the equal-distribution property of Eq. 4.27 — pervious and impervious values match to within ULP.",
      "parameter_overrides": {
        "H_wasteheat": 50.0,
        "H_aircond": 10.0,
        "W_roof": 0.25
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 66.66666666666667
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 66.66666666666667
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 13.333333333333334
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 13.333333333333334
        }
      ]
    },
    {
      "id": "all_zero_inputs",
      "description": "Edge case: no anthropogenic activity (rural-like fixture or nighttime/quiescent diurnal phase with HVAC off). H_wasteheat = H_aircond = 0 with non-zero W_roof — all four output tiles must be exactly zero. Exercises the additive-zero limit of Eq. 4.27 and confirms no spurious constant has been added in either output equation.",
      "parameter_overrides": {
        "H_wasteheat": 0.0,
        "H_aircond": 0.0,
        "W_roof": 0.3
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        }
      ]
    },
    {
      "id": "zero_roof_fraction",
      "description": "Edge case: all-road tile (W_roof = 0 — no roof in this column). Denominator (1 - W_roof) = 1, so each road tile receives the full column-total flux (no amplification). H_wasteheat = 100, H_aircond = 40 → all four outputs equal their respective input total. Verifies the identity branch of the divide.",
      "parameter_overrides": {
        "H_wasteheat": 100.0,
        "H_aircond": 40.0,
        "W_roof": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 100.0
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 100.0
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 40.0
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 40.0
        }
      ]
    },
    {
      "id": "high_roof_fraction",
      "description": "Dense-downtown stress test: W_roof = 0.9, only 10% of the tile is road. The road tiles concentrate the column-total fluxes by a factor of 1 / (1 - 0.9) = 10. H_wasteheat = 50 → 500 W/m^2 per road tile; H_aircond = 10 → 100 W/m^2 per road tile. Surfaces the high-amplification regime of Eq. 4.27 directly relevant to urban-heat-island studies in dense cores.",
      "parameter_overrides": {
        "H_wasteheat": 50.0,
        "H_aircond": 10.0,
        "W_roof": 0.9
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 500.0
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 500.0
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 100.0
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 100.0
        }
      ]
    },
    {
      "id": "negative_wasteheat_branch",
      "description": "Sign-preservation check: H_wasteheat is allowed to be negative if the upstream urban-energy-balance submodel reports net heat extraction (rare but not prohibited by the upstream component). H_wasteheat = -60, H_aircond = 20, W_roof = 0.4 → H_wasteheat_{prvrd,imprvrd} = -60 / 0.6 = -100 W/m^2; H_aircond_{prvrd,imprvrd} = 20 / 0.6 = 33.333... W/m^2. Verifies no spurious clamp has been introduced and the division is sign-preserving.",
      "parameter_overrides": {
        "H_wasteheat": -60.0,
        "H_aircond": 20.0,
        "W_roof": 0.4
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": -100.0
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": -100.0
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 33.333333333333336
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 33.333333333333336
        }
      ]
    },
    {
      "id": "wasteheat_only_no_ac",
      "description": "Asymmetric input: heating-dominated regime with active waste heat but no air conditioning (winter scenario). H_wasteheat = 120, H_aircond = 0, W_roof = 0.5 → H_wasteheat_{prvrd,imprvrd} = 240 W/m^2; H_aircond_{prvrd,imprvrd} = 0 by construction. Confirms the two flux pathways are decoupled — zeroing one does not affect the other.",
      "parameter_overrides": {
        "H_wasteheat": 120.0,
        "H_aircond": 0.0,
        "W_roof": 0.5
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 240.0
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 240.0
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        }
      ]
    },
    {
      "id": "ac_only_no_wasteheat",
      "description": "Asymmetric input: cooling-dominated regime with active air conditioning but no waste heat (a summer peak-AC scenario where building cooling dwarfs the residual waste-heat term, or a fixture isolating the AC pathway). H_wasteheat = 0, H_aircond = 75, W_roof = 0.5 → H_wasteheat_{prvrd,imprvrd} = 0; H_aircond_{prvrd,imprvrd} = 150 W/m^2. The complement of the wasteheat-only test — confirms decoupling in both directions.",
      "parameter_overrides": {
        "H_wasteheat": 0.0,
        "H_aircond": 75.0,
        "W_roof": 0.5
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "H_wasteheat_prvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_wasteheat_imprvrd",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        },
        {
          "variable": "H_aircond_prvrd",
          "time": 0.0,
          "expected": 150.0
        },
        {
          "variable": "H_aircond_imprvrd",
          "time": 0.0,
          "expected": 150.0
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "allocation_vs_roof_fraction",
      "description": "Sweep W_roof across the full physical range [0, 0.95] with fixed column-total fluxes (H_wasteheat = 50, H_aircond = 20 W/m^2). Each road tile receives a flux that grows hyperbolically toward the W_roof → 1 singularity per 1/(1 - W_roof), with a 20-fold amplification at W_roof = 0.95 (a worst-case dense-downtown tile). Surfaces the urban-heat-island amplification factor that motivates Eq. 4.27 directly: shrinking the road fraction concentrates anthropogenic heating into a smaller area, raising local surface temperature.",
      "initial_state": {},
      "parameters": {
        "H_wasteheat": 50.0,
        "H_aircond": 20.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "W_roof",
            "range": {
              "start": 0.0,
              "stop": 0.95,
              "count": 20,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "wasteheat_allocation_curve",
          "type": "line",
          "description": "H_wasteheat_prvrd vs W_roof: hyperbolic 1/(1-W_roof) amplification of the column-total waste heat onto the road tiles per Eq. 4.27. The pervious and impervious tiles overlap exactly by the equal-distribution property.",
          "x": {
            "variable": "W_roof",
            "label": "W_roof (dimensionless)"
          },
          "y": {
            "variable": "H_wasteheat_prvrd",
            "label": "H_wasteheat_prvrd (W/m^2)"
          }
        },
        {
          "id": "aircond_allocation_curve",
          "type": "line",
          "description": "H_aircond_prvrd vs W_roof: same 1/(1-W_roof) amplification applied to the air-conditioning flux per Eq. 4.27 — the two anthropogenic pathways carry the same geometric weighting.",
          "x": {
            "variable": "W_roof",
            "label": "W_roof (dimensionless)"
          },
          "y": {
            "variable": "H_aircond_prvrd",
            "label": "H_aircond_prvrd (W/m^2)"
          }
        }
      ]
    },
    {
      "id": "two_d_sweep_wasteheat_roof",
      "description": "Joint sweep over H_wasteheat and W_roof at fixed H_aircond = 0 (isolates the wasteheat pathway). Surfaces the planar product structure of Eq. 4.27 in the (H_wasteheat, W_roof) plane: H_wasteheat_prvrd = H_wasteheat / (1 - W_roof) — linear in H_wasteheat at fixed W_roof, hyperbolic in W_roof at fixed H_wasteheat. Iso-allocation contours follow H_wasteheat = const * (1 - W_roof). Reproduces the canonical CLMU urban-heat-island sensitivity surface.",
      "initial_state": {},
      "parameters": {
        "H_aircond": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "H_wasteheat",
            "range": {
              "start": 0.0,
              "stop": 200.0,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "W_roof",
            "range": {
              "start": 0.0,
              "stop": 0.9,
              "count": 10,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "wasteheat_allocation_heatmap",
          "type": "heatmap",
          "description": "H_wasteheat_prvrd as a function of column-total waste heat and roof fraction per Eq. 4.27. Iso-allocation contours follow H_wasteheat ∝ (1 - W_roof) — straight lines through the origin in (H_wasteheat, 1 - W_roof) and hyperbolae in (H_wasteheat, W_roof).",
          "x": {
            "variable": "H_wasteheat",
            "label": "H_wasteheat (W/m^2)"
          },
          "y": {
            "variable": "W_roof",
            "label": "W_roof (dimensionless)"
          },
          "value": {
            "variable": "H_wasteheat_prvrd",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}