AdjustedLayerThickness

{
  "reference": {
    "notes": "source_ref: UrbanCanopy.jl@9200edd4f15609f20339d3a7d104de8064544310:src/roof_wall_road_snow_temperatures.jl:601\nUpstream `AdjustedLayerThickness` is an MTK `@component` whose three geometry inputs (z_i, z_h_im1, z_ip1) are `@parameters` and whose single output (Δz_star) is a time-indexed `@variable` with one algebraic equation (Eq. 4.30). Identical equation structure preserved here.\n\nThe upstream component declares one `@constant`: c_a = 0.34 (dimensionless tunable coefficient from Yang 1998). It is encoded here as a fixed-default parameter with the upstream value, matching the convention used by sibling observed-only ESM files in this rig that translate `@constants` to parameters (snow_soil_blended_heat_capacity.esm encodes C_ice the same way, snow_melt_no_layers.esm encodes L_f, zero_kgm2, zero_m the same way).\n\nUnicode `Δz_star` (adjusted 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_soil_blended_heat_capacity.esm uses `Δz`, 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_soil_blended_heat_capacity.esm, 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 two subtractions, one multiplication, one addition, and one halving, 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:566) and we mirror that for fidelity. Tighter `abs: 1e-9` is asserted on outputs that are exactly zero by construction (degenerate equal-z case) so the assertion does not silently accept a stuck-at-zero regression."
  },
  "tolerance": {
    "rel": 1e-10
  },
  "variables": {
    "z_i": {
      "type": "parameter",
      "units": "m",
      "default": 0.0,
      "description": "Node depth of top layer i (depth at which the layer-averaged temperature is carried)"
    },
    "z_h_im1": {
      "type": "parameter",
      "units": "m",
      "default": 0.0,
      "description": "Interface depth above layer i (z_{h,i-1} — the upper boundary of the top layer, i.e. the surface for a surface-layer column where z_h_im1 = 0)"
    },
    "z_ip1": {
      "type": "parameter",
      "units": "m",
      "default": 0.0,
      "description": "Node depth of layer i+1 (the second-from-top layer used in the Eq. 4.30 averaging stencil)"
    },
    "c_a": {
      "type": "parameter",
      "units": "1",
      "default": 0.34,
      "description": "Tunable Yang (1998) coefficient. Dimensionless. Default 0.34 from Oleson Eq. 4.30."
    },
    "Δz_star": {
      "type": "unknown",
      "units": "m",
      "description": "Adjusted top layer thickness (Oleson Eq. 4.30): 0.5 * (z_i - z_h_im1 + c_a * (z_ip1 - z_h_im1))"
    }
  },
  "equations": [
    {
      "lhs": "Δz_star",
      "rhs": {
        "op": "*",
        "args": [
          0.5,
          {
            "op": "+",
            "args": [
              {
                "op": "-",
                "args": [
                  "z_i",
                  "z_h_im1"
                ]
              },
              {
                "op": "*",
                "args": [
                  "c_a",
                  {
                    "op": "-",
                    "args": [
                      "z_ip1",
                      "z_h_im1"
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "upstream_equation_verification",
      "description": "Reproduces upstream `AdjustedLayerThickness - Equation Verification` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:546-567). Inputs: z_i = 0.05 m, z_h_im1 = 0.0 m, z_ip1 = 0.15 m, c_a = 0.34. Expected Δz_star = 0.5 * (0.05 - 0.0 + 0.34 * (0.15 - 0.0)) = 0.5 * 0.101 = 0.0505 m. Anchors fidelity to the upstream Julia component at the same parameter values.",
      "parameter_overrides": {
        "z_i": 0.05,
        "z_h_im1": 0.0,
        "z_ip1": 0.15
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.0505
        }
      ]
    },
    {
      "id": "upstream_positive_output",
      "description": "Reproduces upstream `AdjustedLayerThickness - Positive Output` test (UrbanCanopy.jl test/roof_wall_road_snow_temperatures_test.jl:569-584). With a typical road geometry (z_i = 0.1, z_h_im1 = 0.0, z_ip1 = 0.3), the adjusted thickness is 0.5 * (0.1 + 0.34 * 0.3) = 0.5 * 0.202 = 0.101 m. Upstream only asserts >0; this entry pins the exact expected value so any sign-flip or coefficient regression is caught.",
      "parameter_overrides": {
        "z_i": 0.1,
        "z_h_im1": 0.0,
        "z_ip1": 0.3
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.101
        }
      ]
    },
    {
      "id": "nonzero_upper_interface",
      "description": "Sub-surface layer geometry with a non-zero upper interface (z_h_im1 = 0.02 m): z_i = 0.05, z_ip1 = 0.20, c_a = 0.34. Expected Δz_star = 0.5 * (0.05 - 0.02 + 0.34 * (0.20 - 0.02)) = 0.5 * (0.03 + 0.0612) = 0.5 * 0.0912 = 0.0456 m. Exercises the full subtraction structure of Eq. 4.30 — the upstream tests only cover z_h_im1 = 0 (top-surface) cases.",
      "parameter_overrides": {
        "z_i": 0.05,
        "z_h_im1": 0.02,
        "z_ip1": 0.2
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.0456
        }
      ]
    },
    {
      "id": "degenerate_equal_z",
      "description": "Degenerate geometry where all three depths are equal (z_i = z_h_im1 = z_ip1 = 0.1): both differences in Eq. 4.30 vanish, so Δz_star = 0 exactly. Confirms the equation collapses to zero in the trivial case and catches any spurious additive offset.",
      "parameter_overrides": {
        "z_i": 0.1,
        "z_h_im1": 0.1,
        "z_ip1": 0.1
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.0,
          "tolerance": {
            "abs": 1e-12
          }
        }
      ]
    },
    {
      "id": "c_a_zero_override",
      "description": "Override c_a = 0 (drops the Yang correction term): Δz_star reduces to the plain half-layer thickness 0.5 * (z_i - z_h_im1). At z_i = 0.04, z_h_im1 = 0.0, z_ip1 = 0.12 the expected value is 0.5 * 0.04 = 0.02 m. Exercises the c_a-as-parameter override path and confirms the Yang-coefficient term is what it claims to be.",
      "parameter_overrides": {
        "z_i": 0.04,
        "z_h_im1": 0.0,
        "z_ip1": 0.12,
        "c_a": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.02
        }
      ]
    },
    {
      "id": "c_a_unity_override",
      "description": "Override c_a = 1 (full Yang weight): Δz_star = 0.5 * (z_i + z_ip1 - 2*z_h_im1). At z_i = 0.05, z_h_im1 = 0.0, z_ip1 = 0.15 the expected value is 0.5 * (0.05 + 0.15) = 0.10 m — the simple symmetric midpoint thickness. Pairs with `c_a_zero_override` to bracket the tuning-coefficient sensitivity.",
      "parameter_overrides": {
        "z_i": 0.05,
        "z_h_im1": 0.0,
        "z_ip1": 0.15,
        "c_a": 1.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.1
        }
      ]
    },
    {
      "id": "deep_subgrade",
      "description": "Deep subgrade layer geometry representative of mid-column CLM levels (z_i = 1.0 m, z_h_im1 = 0.6 m, z_ip1 = 1.5 m, c_a = 0.34). Expected Δz_star = 0.5 * (1.0 - 0.6 + 0.34 * (1.5 - 0.6)) = 0.5 * (0.4 + 0.306) = 0.5 * 0.706 = 0.353 m. Exercises the equation away from the surface-layer regime covered by the upstream tests.",
      "parameter_overrides": {
        "z_i": 1.0,
        "z_h_im1": 0.6,
        "z_ip1": 1.5
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.353
        }
      ]
    },
    {
      "id": "intermediate_layer",
      "description": "Intermediate-depth layer geometry with non-zero upper interface and substantial spacing to layer i+1 (z_i = 0.3, z_h_im1 = 0.1, z_ip1 = 0.7, c_a = 0.34): Δz_star = 0.5 * (0.3 - 0.1 + 0.34 * (0.7 - 0.1)) = 0.5 * (0.2 + 0.204) = 0.5 * 0.404 = 0.202 m. Provides a third independent (z_i, z_h_im1, z_ip1) triple in the typical CLM road-column range, complementing `nonzero_upper_interface` and `deep_subgrade`.",
      "parameter_overrides": {
        "z_i": 0.3,
        "z_h_im1": 0.1,
        "z_ip1": 0.7
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Δz_star",
          "time": 0.0,
          "expected": 0.202
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "delta_z_star_vs_z_ip1",
      "description": "Sweep the node depth of layer i+1 across a typical CLM road-column range (0.05 m to 1.0 m) at fixed z_i = 0.05 m, z_h_im1 = 0.0 m, c_a = 0.34. Δz_star = 0.5 * (z_i + c_a * z_ip1) is a line of slope 0.5 * c_a = 0.17 above the intercept 0.5 * z_i = 0.025 m, surfacing the linear sensitivity of the adjusted thickness to the spacing of the second-from-top layer per Eq. 4.30.",
      "initial_state": {},
      "parameters": {
        "z_i": 0.05,
        "z_h_im1": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "z_ip1",
            "range": {
              "start": 0.05,
              "stop": 1.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "delta_z_star_curve",
          "type": "line",
          "description": "Δz_star vs z_ip1: linear rise of slope 0.5*c_a above the 0.5*z_i baseline per Eq. 4.30.",
          "x": {
            "variable": "z_ip1",
            "label": "z_{i+1} (m)"
          },
          "y": {
            "variable": "Δz_star",
            "label": "Δz_star (m)"
          }
        }
      ]
    },
    {
      "id": "two_d_sweep_zi_zip1",
      "description": "Joint sweep over z_i and z_ip1 at fixed z_h_im1 = 0.0 m and c_a = 0.34. Δz_star = 0.5 * (z_i + c_a * z_ip1) is a plane in (z_i, z_ip1) with slope 0.5 along z_i and slope 0.5 * c_a = 0.17 along z_ip1, so iso-Δz_star contours are straight lines z_i + 0.34 * z_ip1 = const. Maps the adjusted thickness across the CLM road-layer geometry plane.",
      "initial_state": {},
      "parameters": {
        "z_h_im1": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "z_i",
            "range": {
              "start": 0.02,
              "stop": 0.5,
              "count": 11,
              "scale": "linear"
            }
          },
          {
            "parameter": "z_ip1",
            "range": {
              "start": 0.05,
              "stop": 1.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "delta_z_star_heatmap",
          "type": "heatmap",
          "description": "Δz_star as a function of top-layer node depth z_i and next-layer node depth z_ip1: linear plane with straight iso-Δz_star contours per Eq. 4.30.",
          "x": {
            "variable": "z_i",
            "label": "z_i (m)"
          },
          "y": {
            "variable": "z_ip1",
            "label": "z_{i+1} (m)"
          },
          "value": {
            "variable": "Δz_star",
            "reduce": "final"
          }
        }
      ]
    },
    {
      "id": "c_a_sensitivity",
      "description": "Sensitivity of the adjusted thickness to the Yang (1998) tuning coefficient c_a, swept from 0 (drops the Yang term) to 1 (full symmetric midpoint thickness) at fixed road-surface geometry (z_i = 0.05, z_h_im1 = 0.0, z_ip1 = 0.15). Δz_star = 0.5 * (z_i + c_a * z_ip1) traces a line from 0.025 m at c_a = 0 up to 0.10 m at c_a = 1, with the upstream default c_a = 0.34 landing at 0.0505 m (matching the `upstream_equation_verification` test).",
      "initial_state": {},
      "parameters": {
        "z_i": 0.05,
        "z_h_im1": 0.0,
        "z_ip1": 0.15
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "c_a",
            "range": {
              "start": 0.0,
              "stop": 1.0,
              "count": 11,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "c_a_sensitivity_curve",
          "type": "line",
          "description": "Δz_star vs c_a: linear ramp from 0.5*z_i at c_a=0 up to the symmetric midpoint 0.5*(z_i + z_ip1) at c_a=1 per Eq. 4.30.",
          "x": {
            "variable": "c_a",
            "label": "c_a (dimensionless)"
          },
          "y": {
            "variable": "Δz_star",
            "label": "Δz_star (m)"
          }
        }
      ]
    }
  ]
}