gomd 2.1.0__py3-none-any.whl

gomd/ocean.py

@@ -0,0 +1,1646 @@
+"""
+gomd.ocean — Physical Oceanography, Seawater Thermodynamics, Carbonate Chemistry,
+Eutrophication (TRIX / TSI), Mucilage Hazard, and Marine Heatwave (MHW) Analytics
+=================================================================================
+Implements peer-reviewed oceanographic algorithms for the GOMD Python SDK:
+  1. UNESCO EOS-80 Seawater Equation of State: density rho(S, T, p) & sigma_t
+  2. Garcia & Gordon (1992) Dissolved Oxygen Solubility (DO_sat) & AOU
+  3. Surface Ocean Carbonate Equilibrium Solver (pCO2, DIC, HCO3-, CO32-, Omega_arag, Omega_calc)
+  4. Hobday et al. (2016, 2018) Marine Heatwave (MHW) Detection & Categorization (Cat I-IV)
+  5. Vollenweider et al. (1998) TRIX Coastal Eutrophication & Carlson (1977) TSI
+  6. Multi-Factor Marine Mucilage Hazard Index (Marmara / Mediterranean calibration)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+
+def seawater_density_eos80(
+    salinity_psu: float,
+    temp_c: float,
+    pressure_dbar: float = 0.0,
+) -> Dict[str, float]:
+    """
+    Compute in-situ seawater density (kg/m^3), sigma_t (kg/m^3), and specific volume
+    anomaly using the UNESCO 1983 (EOS-80) International Equation of State of Seawater
+    (Fofonoff & Millard, 1983).
+
+    Parameters
+    ----------
+    salinity_psu : float
+        Practical Salinity (PSU, 0 to 42).
+    temp_c : float
+        In-situ temperature in degrees Celsius (-2 to 40).
+    pressure_dbar : float, default 0.0
+        Sea pressure in decibars (1 dbar ~ 1 m depth; converted to bars internally).
+
+    Returns
+    -------
+    dict
+        {'rho_kg_m3', 'sigma_0_kg_m3', 'rho_pure_water_kg_m3', 'secant_bulk_modulus_bar'}
+    """
+    S = float(salinity_psu)
+    T = float(temp_c)
+    P = float(pressure_dbar) / 10.0  # dbar -> bar
+
+    # Pure water density rho_w(T) (Bigg, 1967 / UNESCO 1983)
+    rho_w = (
+        999.842594
+        + 6.793952e-2 * T
+        - 9.095290e-3 * (T ** 2)
+        + 1.001685e-4 * (T ** 3)
+        - 1.120083e-6 * (T ** 4)
+        + 6.536332e-9 * (T ** 5)
+    )
+
+    # One-atmosphere density rho(S, T, 0)
+    A = (
+        8.24493e-1
+        - 4.0899e-3 * T
+        + 7.6438e-5 * (T ** 2)
+        - 8.2467e-7 * (T ** 3)
+        + 5.3875e-9 * (T ** 4)
+    )
+    B = -5.72466e-3 + 1.0227e-4 * T - 1.6546e-6 * (T ** 2)
+    C = 4.8314e-4
+
+    rho_0 = rho_w + A * S + B * (S ** 1.5) + C * (S ** 2)
+    sigma_0 = rho_0 - 1000.0
+
+    # Secant bulk modulus K(S, T, P) for high-pressure correction
+    Kw = (
+        19652.21
+        + 148.4206 * T
+        - 2.327105 * (T ** 2)
+        + 1.360477e-2 * (T ** 3)
+        - 5.155288e-5 * (T ** 4)
+    )
+    Aw = 3.239908 + 1.43713e-3 * T + 1.16092e-4 * (T ** 2) - 5.77905e-7 * (T ** 3)
+    Bw = 8.50935e-5 - 6.12293e-6 * T + 5.2787e-8 * (T ** 2)
+
+    K0 = (
+        Kw
+        + (54.6746 - 0.603459 * T + 1.09987e-2 * (T ** 2) - 6.1670e-5 * (T ** 3)) * S
+        + (7.944e-2 + 1.6483e-2 * T - 5.3009e-4 * (T ** 2)) * (S ** 1.5)
+    )
+    A_p = Aw + (2.2838e-3 - 1.0981e-5 * T - 1.6078e-6 * (T ** 2)) * S + 1.91075e-4 * (S ** 1.5)
+    B_p = Bw + (-9.9348e-7 + 2.0816e-8 * T + 9.1697e-10 * (T ** 2)) * S
+
+    K = K0 + A_p * P + B_p * (P ** 2)
+    rho_p = rho_0 / (1.0 - P / K) if P > 0 else rho_0
+
+    return {
+        "rho_kg_m3": round(rho_p, 4),
+        "density_kg_m3": round(rho_p, 4),
+        "sigma_0_kg_m3": round(sigma_0, 4),
+        "sigma_t_kg_m3": round(sigma_0, 4),
+        "rho_pure_water_kg_m3": round(rho_w, 4),
+        "secant_bulk_modulus_bar": round(K, 2),
+    }
+
+
+def oxygen_solubility(
+    temp_c: float,
+    salinity_psu: float,
+    observed_do_umol_kg: Optional[float] = None,
+) -> Dict[str, Optional[float]]:
+    """
+    Compute Dissolved Oxygen saturation concentration (DO_sat) in seawater using the
+    Garcia & Gordon (1992) Benson-Krause refit, plus Apparent Oxygen Utilization (AOU)
+    and hypoxia status if `observed_do_umol_kg` is supplied.
+
+    Reference: Garcia, H. E., & Gordon, L. I. (1992). Oxygen solubility in seawater:
+    Better fitting equations. Limnology and Oceanography, 37(6), 1307-1312.
+    """
+    T = float(temp_c)
+    S = float(salinity_psu)
+    T_s = math.log((298.15 - T) / (273.15 + T))
+
+    # Garcia & Gordon (1992) Table 1 constants for umol/kg
+    A0, A1, A2, A3, A4, A5 = 5.80871, 3.20291, 4.17887, 5.10006, -9.86643e-2, 3.80369
+    B0, B1, B2, B3 = -7.01577e-3, -7.70028e-3, -1.13864e-2, -9.51519e-3
+    C0 = -2.75915e-7
+
+    ln_C = (
+        A0
+        + A1 * T_s
+        + A2 * (T_s ** 2)
+        + A3 * (T_s ** 3)
+        + A4 * (T_s ** 4)
+        + A5 * (T_s ** 5)
+        + S * (B0 + B1 * T_s + B2 * (T_s ** 2) + B3 * (T_s ** 3))
+        + C0 * (S ** 2)
+    )
+    do_sat_umol_kg = math.exp(ln_C)
+    # Approximate conversion: 1 mg/L ~ 31.25 umol/L, adjusted by seawater density
+    rho_kg_l = seawater_density_eos80(S, T, 0.0)["rho_kg_m3"] / 1000.0
+    do_sat_mg_l = (do_sat_umol_kg * rho_kg_l * 31.9988) / 1000.0
+
+    aou = None
+    pct_sat = None
+    hypoxia_class = None
+    if observed_do_umol_kg is not None:
+        obs = float(observed_do_umol_kg)
+        aou = round(do_sat_umol_kg - obs, 3)
+        pct_sat = round((obs / do_sat_umol_kg) * 100.0, 2)
+        obs_mg_l = (obs * rho_kg_l * 31.9988) / 1000.0
+        if obs_mg_l < 0.2:
+            hypoxia_class = "anoxic (<0.2 mg/L)"
+        elif obs_mg_l < 2.0:
+            hypoxia_class = "hypoxic (<2.0 mg/L)"
+        elif obs_mg_l < 4.0:
+            hypoxia_class = "suboxic_stress (2.0-4.0 mg/L)"
+        else:
+            hypoxia_class = "normoxic (>=4.0 mg/L)"
+
+    return {
+        "do_sat_umol_kg": round(do_sat_umol_kg, 3),
+        "do_sat_mg_l": round(do_sat_mg_l, 3),
+        "aou_umol_kg": aou,
+        "oxygen_saturation_pct": pct_sat,
+        "hypoxia_status": hypoxia_class,
+    }
+
+
+def carbonate_system(
+    ph_total: float,
+    temp_c: float,
+    salinity_psu: float = 35.0,
+    ta_umol_kg: float = 2320.0,
+) -> Dict[str, Any]:
+    """
+    Solve the surface ocean carbonate chemistry system given Total-scale pH,
+    temperature (C), salinity (PSU), and Total Alkalinity (TA, umol/kg).
+
+    Uses Mehrbach et al. (1973) refit by Dickson & Millero (1987) for K1 and K2,
+    Weiss (1974) for CO2 solubility K0, and Mucci (1983) for Ksp(aragonite/calcite).
+
+    Returns
+    -------
+    dict
+        {'pCO2_uatm', 'dic_umol_kg', 'hco3_umol_kg', 'co3_umol_kg',
+         'omega_aragonite', 'omega_calcite', 'ecological_status'}
+    """
+    T_k = float(temp_c) + 273.15
+    S = float(salinity_psu)
+    ph = float(ph_total)
+    ta = float(ta_umol_kg) * 1e-6  # mol/kg
+
+    # Weiss (1974) CO2 solubility K0 (mol / (kg * atm))
+    ln_K0 = (
+        -60.2409
+        + 93.4517 * (100.0 / T_k)
+        + 23.3585 * math.log(T_k / 100.0)
+        + S * (0.023517 - 0.023656 * (T_k / 100.0) + 0.0047036 * ((T_k / 100.0) ** 2))
+    )
+    K0 = math.exp(ln_K0)
+
+    # Lueker et al. (2000) / Dickson & Millero (1987) pK1 and pK2
+    pK1 = 3633.86 / T_k - 61.2172 + 9.67770 * math.log(T_k) - 0.011555 * S + 0.0001152 * (S ** 2)
+    pK2 = 471.78 / T_k + 25.9290 - 3.16967 * math.log(T_k) - 0.01781 * S + 0.0001122 * (S ** 2)
+    K1 = 10.0 ** (-pK1)
+    K2 = 10.0 ** (-pK2)
+
+    # Borate alkalinity correction (Dickson, 1990)
+    B_total = 0.0004157 * (S / 35.0)
+    ln_KB = (
+        (-8966.90 - 2890.53 * (S ** 0.5) - 77.942 * S + 1.728 * (S ** 1.5) - 0.0996 * (S ** 2)) / T_k
+        + (148.0248 + 137.1942 * (S ** 0.5) + 1.62142 * S)
+        + (-24.4344 - 25.085 * (S ** 0.5) - 0.2474 * S) * math.log(T_k)
+        + 0.053105 * (S ** 0.5) * T_k
+    )
+    KB = math.exp(ln_KB)
+
+    H = 10.0 ** (-ph)
+    b_alk = B_total * KB / (H + KB)
+    carb_alk = max(ta - b_alk, 1e-6)
+
+    # Carbonate species (mol/kg)
+    co3 = carb_alk / (H / K2 + 2.0)
+    hco3 = (co3 * H) / K2
+    co2_aq = (hco3 * H) / K1
+    dic = co2_aq + hco3 + co3
+    pco2_uatm = (co2_aq / K0) * 1e6
+
+    # Calcium concentration [Ca2+] (Riley & Tongudai, 1967) and Mucci (1983) Ksp
+    ca_mol_kg = 0.01028 * (S / 35.0)
+    log_Ksp_arag = (
+        -171.945
+        - 0.077993 * T_k
+        + 2903.293 / T_k
+        + 71.595 * math.log10(T_k)
+        + (-0.068393 + 0.0017276 * T_k + 88.135 / T_k) * (S ** 0.5)
+        - 0.10018 * S
+        + 0.0059415 * (S ** 1.5)
+    )
+    log_Ksp_calc = (
+        -171.9065
+        - 0.077993 * T_k
+        + 2839.319 / T_k
+        + 71.595 * math.log10(T_k)
+        + (-0.77712 + 0.0028426 * T_k + 178.34 / T_k) * (S ** 0.5)
+        - 0.07711 * S
+        + 0.0041249 * (S ** 1.5)
+    )
+    omega_arag = (ca_mol_kg * co3) / (10.0 ** log_Ksp_arag)
+    omega_calc = (ca_mol_kg * co3) / (10.0 ** log_Ksp_calc)
+
+    if omega_arag < 1.0:
+        status = "corrosive_undersaturated (Omega_arag < 1.0)"
+    elif omega_arag < 3.0:
+        status = "marginal_calcification_stress (1.0 <= Omega_arag < 3.0)"
+    else:
+        status = "optimal_calcification (Omega_arag >= 3.0)"
+
+    return {
+        "pCO2_uatm": round(pco2_uatm, 2),
+        "dic_umol_kg": round(dic * 1e6, 2),
+        "hco3_umol_kg": round(hco3 * 1e6, 2),
+        "co3_umol_kg": round(co3 * 1e6, 2),
+        "omega_aragonite": round(omega_arag, 3),
+        "omega_calcite": round(omega_calc, 3),
+        "ecological_status": status,
+        "calcification_regime": status,
+    }
+
+
+def marine_heatwave_detect(
+    sst_series: Sequence[float],
+    dates_or_steps: Optional[Sequence[Any]] = None,
+    pct_threshold: float = 90.0,
+    min_duration: int = 5,
+    max_gap: int = 2,
+) -> Dict[str, Any]:
+    """
+    Detect and categorize Marine Heatwave (MHW) events following the hierarchical
+    framework of Hobday et al. (2016, Progress in Oceanography) and Hobday et al.
+    (2018, Oceanography, Categories I–IV: Moderate, Strong, Severe, Extreme).
+
+    Parameters
+    ----------
+    sst_series : Sequence[float]
+        Chronological sea surface temperature observations.
+    dates_or_steps : Sequence[Any], optional
+        Corresponding date labels or time indices.
+    pct_threshold : float, default 90.0
+        Percentile threshold for MHW exceedance (default 90th percentile).
+    min_duration : int, default 5
+        Minimum consecutive steps above threshold to qualify as an MHW event.
+    max_gap : int, default 2
+        Maximum gap (in steps) between two consecutive exceedances to merge them.
+    """
+    vals = [float(v) for v in sst_series if v is not None]
+    n = len(vals)
+    if n == 0:
+        return {"events": [], "event_count": 0}
+
+    labels = list(dates_or_steps) if dates_or_steps is not None and len(dates_or_steps) == n else list(range(n))
+    sorted_vals = sorted(vals)
+    clim_mean = sum(vals) / n
+    k_idx = min(max(int(math.floor((pct_threshold / 100.0) * (n - 1))), 0), n - 1)
+    thresh_val = sorted_vals[k_idx]
+    delta_unit = max(thresh_val - clim_mean, 0.25)
+
+    # Identify contiguous exceedance spans
+    raw_spans: List[Tuple[int, int]] = []
+    start: Optional[int] = None
+    for i, val in enumerate(vals):
+        if val > thresh_val:
+            if start is None:
+                start = i
+        else:
+            if start is not None:
+                if (i - start) >= min_duration:
+                    raw_spans.append((start, i - 1))
+                start = None
+    if start is not None and (n - start) >= min_duration:
+        raw_spans.append((start, n - 1))
+
+    # Merge spans separated by <= max_gap
+    merged_spans: List[Tuple[int, int]] = []
+    for sp in raw_spans:
+        if merged_spans and (sp[0] - merged_spans[-1][1] - 1) <= max_gap:
+            merged_spans[-1] = (merged_spans[-1][0], sp[1])
+        else:
+            merged_spans.append(sp)
+
+    events: List[Dict[str, Any]] = []
+    for idx, (s_i, e_i) in enumerate(merged_spans, 1):
+        segment = vals[s_i : e_i + 1]
+        anomalies = [v - clim_mean for v in segment]
+        max_anom = max(anomalies)
+        mean_anom = sum(anomalies) / len(anomalies)
+        cum_anom = sum(anomalies)
+        severity_mult = max_anom / delta_unit
+        if severity_mult >= 4.0:
+            category = "IV (Extreme)"
+        elif severity_mult >= 3.0:
+            category = "III (Severe)"
+        elif severity_mult >= 2.0:
+            category = "II (Strong)"
+        else:
+            category = "I (Moderate)"
+
+        events.append(
+            {
+                "event_id": idx,
+                "start_step": labels[s_i],
+                "end_step": labels[e_i],
+                "duration_steps": e_i - s_i + 1,
+                "max_sst_c": round(max(segment), 3),
+                "max_intensity_c": round(max_anom, 3),
+                "mean_intensity_c": round(mean_anom, 3),
+                "cumulative_intensity_c_steps": round(cum_anom, 3),
+                "hobday_category": category,
+            }
+        )
+
+    return {
+        "climatology_mean_c": round(clim_mean, 3),
+        "threshold_pct": pct_threshold,
+        "threshold_sst_c": round(thresh_val, 3),
+        "event_count": len(events),
+        "events": events,
+    }
+
+
+def trophic_state_index(
+    chl_a_ug_l: float,
+    din_ug_l: Optional[float] = None,
+    tp_ug_l: Optional[float] = None,
+    do_saturation_pct: Optional[float] = None,
+    secchi_m: Optional[float] = None,
+) -> Dict[str, Any]:
+    """
+    Compute Carlson (1977) Trophic State Index (TSI) and Vollenweider et al. (1998)
+    TRIX Coastal Eutrophication Index (used by UN SDG 14.1.1 & UNEP/MAP MedPol).
+
+    Formula (Vollenweider et al., 1998):
+        TRIX = (log10(Chl-a * |100 - %DO| * DIN * TP) + 1.5) / 1.2
+    """
+    chla = max(float(chl_a_ug_l), 0.01)
+    tsi_chla = 9.81 * math.log(chla) + 30.6
+    tsi_sd = 60.0 - 14.41 * math.log(max(float(secchi_m), 0.05)) if secchi_m is not None else None
+    tsi_tp = 14.42 * math.log(max(float(tp_ug_l), 0.1)) + 4.15 if tp_ug_l is not None else None
+
+    trix_val = None
+    trix_status = None
+    if din_ug_l is not None and tp_ug_l is not None and do_saturation_pct is not None:
+        dev_o2 = max(abs(100.0 - float(do_saturation_pct)), 1.0)
+        prod = max(chla * dev_o2 * max(float(din_ug_l), 0.1) * max(float(tp_ug_l), 0.1), 1e-6)
+        trix_val = round((math.log10(prod) + 1.5) / 1.2, 3)
+        if trix_val < 4.0:
+            trix_status = "oligotrophic_high_quality (TRIX < 4)"
+        elif trix_val < 5.0:
+            trix_status = "mesotrophic_good (4 <= TRIX < 5)"
+        elif trix_val < 6.0:
+            trix_status = "eutrophic_poor (5 <= TRIX < 6)"
+        else:
+            trix_status = "hypertrophic_degraded (TRIX >= 6)"
+
+    return {
+        "carlson_tsi_chla": round(tsi_chla, 2),
+        "carlson_tsi_secchi": round(tsi_sd, 2) if tsi_sd is not None else None,
+        "carlson_tsi_tp": round(tsi_tp, 2) if tsi_tp is not None else None,
+        "vollenweider_trix": trix_val,
+        "trix_water_quality": trix_status,
+    }
+
+
+def mucilage_risk_index(
+    sst_anomaly_c: float,
+    n_p_molar_ratio: float,
+    wind_speed_ms: float,
+    residence_time_days: float = 30.0,
+    chl_a_ug_l: float = 2.5,
+) -> Dict[str, Any]:
+    """
+    Calculate the composite Marine Mucilage Hazard Index (0-100) calibrated for
+    stratified semi-enclosed basins (e.g., Sea of Marmara, Northern Adriatic).
+
+    Captures the 4 drivers of phytoplankton extracellular polymeric substance (EPS)
+    hyper-production and aggregation:
+      1. Thermal stratification & positive SST anomaly
+      2. Nutrient stoichiometry imbalance (elevated N:P Redfield deviation > 16:1)
+      3. Low wind mixing / water-column stagnation
+      4. Phytoplankton biomass precursor (Chl-a)
+    """
+    thermal_score = min(max((float(sst_anomaly_c) + 0.5) / 3.5, 0.0), 1.0) * 30.0
+    np_dev = abs(float(n_p_molar_ratio) - 16.0)
+    nutrient_score = min(np_dev / 24.0, 1.0) * 25.0
+    stagnation_score = (
+        min(max((8.0 - float(wind_speed_ms)) / 7.0, 0.0), 1.0) * 15.0
+        + min(float(residence_time_days) / 60.0, 1.0) * 10.0
+    )
+    biomass_score = min(math.log1p(max(float(chl_a_ug_l), 0.0)) / math.log1p(15.0), 1.0) * 20.0
+
+    total = round(thermal_score + nutrient_score + stagnation_score + biomass_score, 2)
+    if total >= 75.0:
+        level = "CRITICAL (Imminent Mucilage Aggregation Risk)"
+    elif total >= 50.0:
+        level = "HIGH (Elevated EPS & Stratification Alert)"
+    elif total >= 25.0:
+        level = "MODERATE (Seasonal Monitoring Required)"
+    else:
+        level = "LOW (Well-Mixed / Baseline Conditions)"
+
+    return {
+        "mucilage_risk_score": total,
+        "mucilage_risk_index_0_100": total,
+        "risk_level": level,
+        "alert_level": level,
+        "components": {
+            "thermal_stratification": round(thermal_score, 2),
+            "nutrient_stoichiometry": round(nutrient_score, 2),
+            "hydrodynamic_stagnation": round(stagnation_score, 2),
+            "phytoplankton_biomass": round(biomass_score, 2),
+        },
+    }
+
+
+def compound_mhw_oax_event(
+    sst_series: Sequence[float],
+    ph_series: Sequence[float],
+    do_mg_l_series: Sequence[float],
+    labels: Optional[Sequence[Any]] = None,
+    sst_pct: float = 85.0,
+    ph_pct: float = 15.0,
+    do_pct: float = 15.0,
+    sst_percentile: Optional[float] = None,
+    ph_percentile: Optional[float] = None,
+    do_percentile: Optional[float] = None,
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """
+    Detect Triple-Threat Compound Marine Extremes (MHW + Ocean Acidification Extreme [OAX]
+    + Low-Oxygen Extreme [LOX]) and compute the Metabolic Habitat Compression / Aerobic
+    Growth Index (AGI).
+
+    Post-2020 Scientific References:
+      - Gruber, N., Boyd, P. W., Frölicher, T. L., & Vogt, M. (2021). Biogeochemical
+        extremes and compound events in the ocean. Science, 374(6566), eabc9852.
+      - Burger, F. A., Terhaar, J., & Frölicher, T. L. (2022). Compound marine heatwaves
+        and ocean acidity extremes. Nature, 608, 327-332.
+      - Clarke, T. M., Wabnitz, C. C., Striegel, S., Frölicher, T. L., Reygondeau, G.,
+        & Cheung, W. W. (2021). Aerobic growth index (AGI): An index to understand the
+        impacts of ocean warming and deoxygenation on marine ectotherms. Progress in
+        Oceanography / Science Advances.
+    """
+    if sst_percentile is not None:
+        sst_pct = float(sst_percentile)
+    if ph_percentile is not None:
+        ph_pct = float(ph_percentile)
+    if do_percentile is not None:
+        do_pct = float(do_percentile)
+
+    sst = [float(v) for v in sst_series]
+    ph = [float(v) for v in ph_series]
+    do_vals = [float(v) for v in do_mg_l_series]
+    n = min(len(sst), len(ph), len(do_vals))
+    if n < 4:
+        raise ValueError("compound_mhw_oax_event requires at least 4 paired observations.")
+
+    lbls = [str(labels[i]) for i in range(n)] if labels is not None else [str(i + 1) for i in range(n)]
+    # Convert pH to hydrogen ion concentration [H+] in nmol/kg for linear extreme quantile evaluation
+    h_nmol = [(10.0 ** (-ph[i])) * 1e9 for i in range(n)]
+
+    def _pct(arr: List[float], q: float) -> float:
+        s = sorted(arr)
+        pos = (q / 100.0) * (len(s) - 1)
+        lo = int(math.floor(pos))
+        hi = int(math.ceil(pos))
+        return s[lo] + (pos - lo) * (s[hi] - s[lo])
+
+    sst_thresh = _pct(sst[:n], sst_pct)
+    h_thresh = _pct(h_nmol, 100.0 - ph_pct)  # High [H+] = low pH extreme
+    do_thresh = _pct(do_vals[:n], do_pct)
+
+    steps_out: List[Dict[str, Any]] = []
+    double_count = 0
+    triple_count = 0
+    agi_values: List[float] = []
+
+    for i in range(n):
+        is_mhw = sst[i] >= sst_thresh
+        is_oax = h_nmol[i] >= h_thresh
+        is_lox = do_vals[i] <= do_thresh
+        multiplicity = int(is_mhw) + int(is_oax) + int(is_lox)
+        if multiplicity == 2:
+            double_count += 1
+        elif multiplicity == 3:
+            triple_count += 1
+
+        # Clarke et al. (2021) Aerobic Growth Index (AGI = pO2_supply / pO2_demand_maintenance)
+        # Metabolic O2 demand increases exponentially with temperature via Arrhenius factor exp(-j / T_K)
+        t_k = sst[i] + 273.15
+        metabolic_demand = math.exp(18.2 - 5400.0 / t_k)
+        o2_supply = max(do_vals[i], 0.05) / 8.0
+        agi = o2_supply / max(metabolic_demand, 0.05)
+        agi_values.append(agi)
+
+        if multiplicity >= 2:
+            steps_out.append(
+                {
+                    "step": lbls[i],
+                    "sst_c": round(sst[i], 3),
+                    "ph_total": round(ph[i], 4),
+                    "do_mg_l": round(do_vals[i], 3),
+                    "mhw_active": is_mhw,
+                    "oax_active": is_oax,
+                    "lox_active": is_lox,
+                    "multiplicity": multiplicity,
+                    "compound_class": "Triple Compound (MHW+OAX+LOX)" if multiplicity == 3 else "Dual Compound Extreme",
+                    "aerobic_growth_index_agi": round(agi, 3),
+                }
+            )
+
+    # Expected independent triple probability vs observed empirical frequency
+    p_ind_triple = ((100.0 - sst_pct) / 100.0) * (ph_pct / 100.0) * (do_pct / 100.0)
+    p_obs_triple = triple_count / float(n)
+    likelihood_mult = (p_obs_triple / p_ind_triple) if p_ind_triple > 0 else 0.0
+
+    return {
+        "n_steps": n,
+        "thresholds": {
+            "sst_c_high": round(sst_thresh, 3),
+            "h_plus_nmol_kg_high": round(h_thresh, 3),
+            "do_mg_l_low": round(do_thresh, 3),
+        },
+        "dual_compound_steps": double_count,
+        "dual_compound_days": double_count,
+        "triple_compound_steps": triple_count,
+        "triple_compound_days": triple_count,
+        "compound_frequency_pct": round(((double_count + triple_count) / float(n)) * 100.0, 2),
+        "triple_likelihood_multiplier": round(likelihood_mult, 2),
+        "mean_aerobic_growth_index": round(sum(agi_values) / len(agi_values), 3),
+        "critical_habitat_compression_steps": sum(1 for a in agi_values if a < 1.0),
+        "compound_events": steps_out,
+        "reference": "Gruber et al. (Science, 2021); Burger et al. (Nature, 2022); Clarke et al. (2021)",
+    }
+
+
+def teos10_gsw_stratification(
+    salinity_psu: float,
+    temp_c: float,
+    pressure_dbar: float = 100.0,
+    lat: float = 36.0,
+    surface_salinity_psu: Optional[float] = None,
+    surface_temp_c: Optional[float] = None,
+) -> Dict[str, Any]:
+    """
+    Compute TEOS-10 Gibbs Seawater (IOC-SCOR-IAPSO) Absolute Salinity (S_A, g/kg),
+    Conservative Temperature (Theta, deg C), Brunt-Vaisala Buoyancy Frequency Squared
+    (N^2, s^-2), and Sallée et al. (Nature, 2021) Pycnocline Stratification Barrier Index.
+
+    Post-2020 Scientific References:
+      - Sallée, J.-B., Pellichero, V., Akhoudas, C., Pauthenet, E., Vignes, L.,
+        Schmidtko, S., ... & Kuusela, M. (2021). Summertime velocity of the upper-ocean
+        stratification over the past half-century. Nature, 591(7851), 592-598.
+      - IOC, SCOR and IAPSO (2010 / CMIP6 Standard). The international thermodynamic
+        equation of seawater - 2010 (TEOS-10).
+    """
+    sp = float(salinity_psu)
+    t = float(temp_c)
+    p = max(float(pressure_dbar), 1.0)
+    # Reference Composition Salinity Scale factor (35.16504 / 35.0) + biogeochemical anomaly delta_SA
+    sa = sp * (35.16504 / 35.0) + 0.008 * (p / 1000.0)
+    # Potential temperature & TEOS-10 Conservative Temperature polynomial approximation
+    theta0 = t - 1.5e-4 * p * (1.0 + 0.02 * (t - 10.0))
+    ct = theta0 + 0.0045 * (35.16504 - sa) / 35.16504 * theta0
+
+    s_surf = float(surface_salinity_psu) if surface_salinity_psu is not None else max(sp - 0.35, 0.0)
+    t_surf = float(surface_temp_c) if surface_temp_c is not None else (t + 4.5)
+
+    rho_deep = seawater_density_eos80(sp, t, p)["density_kg_m3"]
+    rho_surf = seawater_density_eos80(s_surf, t_surf, 0.0)["density_kg_m3"]
+    sigma_diff = max(rho_deep - rho_surf, 0.0)
+
+    # Local gravitational acceleration g(lat)
+    rad = math.radians(float(lat))
+    g_lat = 9.780327 * (1.0 + 5.3024e-3 * (math.sin(rad) ** 2))
+    dz = max(p, 1.0)  # 1 dbar approx 1 m
+    n2 = (g_lat / rho_deep) * (sigma_diff / dz)
+    cph = (math.sqrt(max(n2, 0.0)) * 3600.0) / (2.0 * math.pi)
+
+    if n2 >= 4.0e-4:
+        barrier = "STRONG PYCNOCLINE BARRIER (Severe Vertical Ventilation Suppression)"
+    elif n2 >= 1.0e-4:
+        barrier = "MODERATE STRATIFICATION (Seasonal Thermocline Active)"
+    else:
+        barrier = "WEAK / CONVECTIVELY MIXED WATER COLUMN"
+
+    return {
+        "practical_salinity_sp": round(sp, 4),
+        "absolute_salinity_sa_g_kg": round(sa, 4),
+        "conservative_temperature_ct_c": round(ct, 4),
+        "delta_sigma_kg_m3": round(sigma_diff, 4),
+        "brunt_vaisala_n2_s2": round(n2, 7),
+        "buoyancy_frequency_cph": round(cph, 3),
+        "stratification_regime": barrier,
+        "reference": "TEOS-10 (IOC/SCOR/IAPSO) & Sallée et al. (Nature, 2021)",
+    }
+
+
+def blue_carbon_sequestration_valuation(
+    seagrass_ha: float = 0.0,
+    saltmarsh_ha: float = 0.0,
+    mangrove_ha: float = 0.0,
+    degradation_risk_pct: float = 10.0,
+    horizon_years: int = 30,
+    discount_rate: float = 0.02,
+    scc_usd_per_tco2: float = 185.0,
+    vcm_price_usd: float = 28.5,
+) -> Dict[str, Any]:
+    """
+    Quantify Coastal Blue Carbon Sequestration, Sedimentary Carbon Stock Vulnerability,
+    Social Cost of Carbon (SCC) Natural Capital Wealth, and Paris Agreement Article 6
+    Voluntary Carbon Market (VCM) Revenue.
+
+    Post-2020 Scientific References:
+      - Bertram, C., Quaas, M., Reusch, T. B., Vafeidis, A. T., Wolff, C., & Rickels, W.
+        (2021). The blue carbon wealth of nations. Nature Climate Change, 11(8), 704-709.
+      - Macreadie, P. I., Costa, M. D., Atwood, T. B., Friess, D. A., Kelleway, J. J.,
+        Kennedy, H., ... & Duarte, C. M. (2021). Blue carbon as a natural climate
+        solution. Nature Reviews Earth & Environment, 2(12), 826-839.
+      - Rennert, K., Errickson, F., Prest, B. C., Rennels, L., Newell, R. G., Pizer, W.,
+        ... & Anthoff, D. (2022). Comprehensive evidence implies a higher social cost
+        of CO2 ($185/tCO2). Nature, 610(7933), 687-692.
+    """
+    # Annual burial rates (tCO2e / ha / yr) & top-1m soil carbon stock (tCO2e / ha)
+    # from Macreadie et al. (2021) & IPCC Wetlands Supplement
+    rates = {
+        "seagrass_posidonia": {"seq_tco2_ha_yr": 5.06, "stock_tco2_ha": 513.0},
+        "saltmarsh": {"seq_tco2_ha_yr": 7.99, "stock_tco2_ha": 917.0},
+        "mangrove": {"seq_tco2_ha_yr": 8.29, "stock_tco2_ha": 1415.0},
+    }
+
+    sg = max(float(seagrass_ha), 0.0)
+    sm = max(float(saltmarsh_ha), 0.0)
+    mg = max(float(mangrove_ha), 0.0)
+
+    annual_seq = (
+        sg * rates["seagrass_posidonia"]["seq_tco2_ha_yr"]
+        + sm * rates["saltmarsh"]["seq_tco2_ha_yr"]
+        + mg * rates["mangrove"]["seq_tco2_ha_yr"]
+    )
+    total_stock = (
+        sg * rates["seagrass_posidonia"]["stock_tco2_ha"]
+        + sm * rates["saltmarsh"]["stock_tco2_ha"]
+        + mg * rates["mangrove"]["stock_tco2_ha"]
+    )
+
+    # Avoided emissions from protecting top-1m sediment stock against remineralization
+    deg_frac = min(max(float(degradation_risk_pct) / 100.0, 0.0), 1.0)
+    avoided_stock_loss = total_stock * deg_frac * 0.50  # 50% oxidized upon habitat destruction
+
+    # Discounted Present Value of sequestration stream over horizon_years (Ramsey r = 2.0% per Rennert et al. 2022)
+    r = max(float(discount_rate), 0.0001)
+    pv_factor = sum(1.0 / ((1.0 + r) ** t) for t in range(1, int(horizon_years) + 1))
+    cum_seq_tco2 = annual_seq * int(horizon_years) + avoided_stock_loss
+    npv_scc_usd = (annual_seq * pv_factor + avoided_stock_loss) * float(scc_usd_per_tco2)
+    annual_vcm_usd = annual_seq * float(vcm_price_usd)
+
+    return {
+        "total_habitat_area_ha": round(sg + sm + mg, 2),
+        "annual_sequestration_tco2e_yr": round(annual_seq, 2),
+        "top_1m_sediment_stock_tco2e": round(total_stock, 2),
+        "avoided_remineralization_tco2e": round(avoided_stock_loss, 2),
+        "cumulative_mitigation_tco2e": round(cum_seq_tco2, 2),
+        "natural_capital_npv_scc_usd": round(npv_scc_usd, 2),
+        "annual_article6_vcm_revenue_usd": round(annual_vcm_usd, 2),
+        "scc_benchmark_usd_tco2": float(scc_usd_per_tco2),
+        "reference": "Bertram et al. (Nat. Clim. Change, 2021); Macreadie et al. (2021); Rennert et al. (Nature, 2022)",
+    }
+
+
+def sustainable_insurance_cat_var(
+    coastal_exposed_value_usd: float = 500_000_000.0,
+    reef_mangrove_seagrass_ha: float = 1200.0,
+    observed_wave_hs_m: float = 5.4,
+    parametric_trigger_hs_m: float = 4.8,
+    storm_return_period_yr: float = 50.0,
+    annual_restoration_cost_usd: float = 1_800_000.0,
+) -> Dict[str, Any]:
+    """
+    UNEP FI Principles for Sustainable Insurance (PSI) & Parametric Coastal Ecosystem
+    Catastrophe Risk-Transfer Model (Coral Reef, Mangrove & Seagrass Wave Attenuation).
+
+    Post-2020 Scientific & Actuarial References:
+      - Reguero, B. G., Beck, M. W., Schmid, D., Stadmueller, D., Raepple, J., Schüssele, S.,
+        & Pfliegner, K. (2020). Financing coastal resilience by combining nature-based risk
+        reduction with insurance. Ecological Economics / Nature Communications Framework.
+      - Beck, M. W., Heck, N., Narayan, S., Menéndez, P., Torres-Ortega, S., Losada, I. J.,
+        ... & Reguero, B. G. (2022). Return on investment for mangrove and reef flood
+        protection. Nature Sustainability, 5(7), 618-626.
+      - UNEP Finance Initiative (UNEP FI, 2023). Principles for Sustainable Insurance (PSI):
+        Insuring Nature-Positive & Climate-Resilient Coastal Infrastructure.
+    """
+    exp_val = max(float(coastal_exposed_value_usd), 100_000.0)
+    hab_ha = max(float(reef_mangrove_seagrass_ha), 0.0)
+    hs_obs = max(float(observed_wave_hs_m), 0.1)
+    hs_trig = max(float(parametric_trigger_hs_m), 0.5)
+    ret_yr = max(float(storm_return_period_yr), 2.0)
+    rest_cost = max(float(annual_restoration_cost_usd), 1.0)
+
+    # Baseline Expected Annual Damage (EAD) without nature-based coastal protection (~0.85% of exposed value)
+    ead_unprotected_usd = exp_val * 0.0085
+
+    # Wave energy attenuation from coral reefs / mangroves / Posidonia seagrass (up to 62% flood damage reduction per Beck et al. 2022)
+    attenuation_frac = min(0.62, 0.62 * (1.0 - math.exp(-hab_ha / 1500.0)))
+    avoided_annual_loss_usd = ead_unprotected_usd * attenuation_frac
+    ead_protected_usd = ead_unprotected_usd - avoided_annual_loss_usd
+
+    # Probable Maximum Loss at 100-year and 250-year return periods (PML_100, PML_250)
+    pml_100_usd = exp_val * 0.095 * (1.0 - 0.75 * attenuation_frac)
+    pml_250_usd = exp_val * 0.165 * (1.0 - 0.70 * attenuation_frac)
+
+    # Actuarial technical premium (Pure Risk Premium + 28% risk/capital loading)
+    technical_premium_unprotected_usd = ead_unprotected_usd * 1.28
+    technical_premium_protected_usd = ead_protected_usd * 1.28
+    annual_premium_savings_usd = technical_premium_unprotected_usd - technical_premium_protected_usd
+
+    # Parametric payout trigger evaluation (stepped payout based on Hs exceedance above trigger)
+    triggered = hs_obs >= hs_trig
+    if triggered:
+        exceed_ratio = min((hs_obs - hs_trig) / max(hs_trig * 0.6, 0.5), 1.0)
+        payout_tier_pct = min(100.0, round(40.0 + 60.0 * exceed_ratio, 1))
+        parametric_payout_usd = pml_100_usd * (payout_tier_pct / 100.0)
+    else:
+        payout_tier_pct = 0.0
+        parametric_payout_usd = 0.0
+
+    resilience_bcr = (avoided_annual_loss_usd + annual_premium_savings_usd * 0.5) / rest_cost
+
+    return {
+        "coastal_exposed_value_usd": round(exp_val, 2),
+        "wave_attenuation_reduction_pct": round(attenuation_frac * 100.0, 2),
+        "ead_unprotected_usd": round(ead_unprotected_usd, 2),
+        "ead_nature_protected_usd": round(ead_protected_usd, 2),
+        "avoided_annual_damage_usd": round(avoided_annual_loss_usd, 2),
+        "pml_100yr_usd": round(pml_100_usd, 2),
+        "pml_250yr_usd": round(pml_250_usd, 2),
+        "annual_insurance_premium_protected_usd": round(technical_premium_protected_usd, 2),
+        "annual_insurance_premium_savings_usd": round(annual_premium_savings_usd, 2),
+        "parametric_trigger_activated": triggered,
+        "parametric_payout_tier_pct": payout_tier_pct,
+        "parametric_payout_usd": round(parametric_payout_usd, 2),
+        "nature_resilience_benefit_cost_ratio": round(resilience_bcr, 2),
+        "reference": "UNEP FI PSI (2023); Reguero et al. (2020); Beck et al. (Nature Sustainability, 2022)",
+    }
+
+
+def cwon_wealth_accounting(
+    gni_usd: float = 1_150_000_000_000.0,
+    gross_national_savings_usd: float = 295_000_000_000.0,
+    consumption_fixed_capital_usd: float = 135_000_000_000.0,
+    education_expenditure_usd: float = 42_000_000_000.0,
+    energy_depletion_usd: float = 4_800_000_000.0,
+    mineral_depletion_usd: float = 2_900_000_000.0,
+    net_forest_depletion_usd: float = 650_000_000.0,
+    co2_damage_usd: float = 24_500_000_000.0,
+    pm25_damage_usd: float = 6_200_000_000.0,
+    blue_natural_capital_net_change_usd: float = 1_450_000_000.0,
+) -> Dict[str, Any]:
+    """
+    World Bank Changing Wealth of Nations (CWON 2021/2024), Dasgupta Review (2021) &
+    UN SEEA Ecosystem Accounting: Adjusted Net Savings (ANS / Genuine Savings) and
+    Blue-Adjusted Inclusive Wealth Accounting.
+
+    Formula:
+        NNS = GNS - CFC
+        ANS_CWON = NNS + Edu_Exp - (D_energy + D_mineral + D_forest) - (Damage_CO2 + Damage_PM2.5)
+        ANS_Blue_Inclusive = ANS_CWON + Delta_Blue_Natural_Capital
+    """
+    gni = max(float(gni_usd), 1.0)
+    gns = float(gross_national_savings_usd)
+    cfc = float(consumption_fixed_capital_usd)
+    edu = float(education_expenditure_usd)
+    d_res = float(energy_depletion_usd) + float(mineral_depletion_usd) + float(net_forest_depletion_usd)
+    d_poll = float(co2_damage_usd) + float(pm25_damage_usd)
+    blue_adj = float(blue_natural_capital_net_change_usd)
+
+    nns_usd = gns - cfc
+    ans_cwon_usd = nns_usd + edu - d_res - d_poll
+    ans_blue_inclusive_usd = ans_cwon_usd + blue_adj
+
+    ans_gni_pct = (ans_cwon_usd / gni) * 100.0
+    ans_blue_gni_pct = (ans_blue_inclusive_usd / gni) * 100.0
+    depletion_gni_pct = (d_res / gni) * 100.0
+    co2_damage_gni_pct = (float(co2_damage_usd) / gni) * 100.0
+
+    if ans_blue_gni_pct >= 8.0:
+        regime = "STRONG INCLUSIVE WEALTH ACCUMULATION (Dasgupta-Sustainable Trajectory)"
+    elif ans_blue_gni_pct >= 0.0:
+        regime = "MODERATE GENUINE SAVINGS (Positive Net Wealth, High Carbon Drag)"
+    else:
+        regime = "NATURAL CAPITAL LIQUIDATION ALERT (Negative Genuine Savings)"
+
+    return {
+        "net_national_savings_usd": round(nns_usd, 2),
+        "cwon_adjusted_net_savings_usd": round(ans_cwon_usd, 2),
+        "blue_inclusive_adjusted_net_savings_usd": round(ans_blue_inclusive_usd, 2),
+        "cwon_ans_pct_gni": round(ans_gni_pct, 3),
+        "blue_inclusive_ans_pct_gni": round(ans_blue_gni_pct, 3),
+        "natural_resource_depletion_pct_gni": round(depletion_gni_pct, 3),
+        "co2_damage_pct_gni": round(co2_damage_gni_pct, 3),
+        "wealth_sustainability_regime": regime,
+        "reference": "World Bank Changing Wealth of Nations (CWON, 2021/2024); Dasgupta Review (2021); UN SEEA (2021)",
+    }
+
+
+def sst_warming_velocity_profile(
+    sst_series: Sequence[float],
+    dt_days: Any = 1.0,
+    mixed_layer_depth_m: float = 25.0,
+    seawater_density_kg_m3: float = 1025.0,
+    specific_heat_j_kg_k: float = 3985.0,
+    baseline_window: Optional[int] = None,
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """
+    SST Rate-of-Change (dSST/dt), Marine Heatwave Onset/Decline Velocity (R_onset, R_decline),
+    and Mixed-Layer Heat Budget Net Surface Flux (Q_net) Model.
+
+    Follows Hobday et al. (2016, Progress in Oceanography), Oliver et al. (2021, Annual Review
+    of Marine Science), and Schlegel et al. (2021) for MHW onset/decline rates and upper-ocean
+    mixed-layer heat content rate of change:
+        Q_net(t) = rho_0 * c_p * h_MLD * (dSST / dt)   [W/m^2]
+
+    Parameters
+    ----------
+    sst_series : Sequence[float]
+        Chronological sea surface temperature observations (deg C).
+    dt_days : float or Sequence[float], default 1.0
+        Time step between consecutive observations in days (1.0 for daily OISST), or a sequence
+        of chronological years (e.g., `[2005, ..., 2026]`) from which `dt_days` is inferred.
+    mixed_layer_depth_m : float, default 25.0
+        Effective upper-ocean mixed layer depth h_MLD in meters.
+    """
+    vals = [float(v) for v in sst_series if v is not None and math.isfinite(float(v))]
+    n = len(vals)
+    if n < 3:
+        return {"error": "At least 3 valid SST observations are required.", "n": n}
+
+    if isinstance(dt_days, (list, tuple)):
+        if len(dt_days) >= 2:
+            try:
+                yr_step = (float(dt_days[-1]) - float(dt_days[0])) / max(len(dt_days) - 1, 1)
+                dt = max(yr_step * 365.25 if yr_step <= 10.0 else yr_step, 1e-6)
+            except (TypeError, ValueError):
+                dt = 365.25
+        else:
+            dt = 365.25
+    else:
+        dt = max(float(dt_days), 1e-6)
+    dt_sec = dt * 86400.0
+    heat_cap_area = float(seawater_density_kg_m3) * float(specific_heat_j_kg_k) * float(mixed_layer_depth_m)
+
+    # Centered finite-difference dSST/dt (deg C / day) and interior second derivative d2SST/dt2
+    dsst_dt: List[float] = []
+    d2sst_dt2: List[float] = []
+    for i in range(n):
+        if i == 0:
+            rate = (vals[1] - vals[0]) / dt
+        elif i == n - 1:
+            rate = (vals[-1] - vals[-2]) / dt
+        else:
+            rate = (vals[i + 1] - vals[i - 1]) / (2.0 * dt)
+            acc = (vals[i + 1] - 2.0 * vals[i] + vals[i - 1]) / (dt * dt)
+            d2sst_dt2.append(acc)
+        dsst_dt.append(rate)
+
+    q_net_wm2 = [(r / 86400.0) * heat_cap_area for r in dsst_dt]
+    pos_rates = [r for r in dsst_dt if r > 0.0]
+    neg_rates = [abs(r) for r in dsst_dt if r < 0.0]
+
+    # Peak warming event onset & decline velocity (Hobday et al., 2016)
+    peak_idx = max(range(n), key=lambda k: vals[k])
+    start_idx = min(range(peak_idx + 1), key=lambda k: vals[k])
+    end_idx = min(range(peak_idx, n), key=lambda k: vals[k])
+
+    onset_days = max((peak_idx - start_idx) * dt, dt)
+    decline_days = max((end_idx - peak_idx) * dt, dt)
+    r_onset = (vals[peak_idx] - vals[start_idx]) / onset_days
+    r_decline = (vals[peak_idx] - vals[end_idx]) / decline_days
+
+    # OLS linear warming rate (deg C / day -> deg C / decade)
+    t_mean = (n - 1) * dt / 2.0
+    v_mean = sum(vals) / n
+    num = sum(((i * dt - t_mean) * (vals[i] - v_mean)) for i in range(n))
+    den = sum(((i * dt - t_mean) ** 2) for i in range(n))
+    slope_per_day = num / max(den, 1e-12)
+    warming_per_decade = slope_per_day * 3652.5
+
+    # Compare second half vs first half decadal trend for decadal acceleration
+    half = max(n // 2, 2)
+    slope1 = (vals[half - 1] - vals[0]) / max((half - 1) * dt, 1e-6) * 3652.5
+    slope2 = (vals[-1] - vals[n - half]) / max((half - 1) * dt, 1e-6) * 3652.5
+    acc_dec2 = slope2 - slope1
+
+    max_warming_rate = max(dsst_dt)
+    max_cooling_rate = min(dsst_dt)
+    mean_acc_day2 = sum(d2sst_dt2) / max(len(d2sst_dt2), 1)
+
+    return {
+        "n_observations": n,
+        "dt_days": round(dt, 4),
+        "mean_dsst_dt_c_per_day": round(sum(dsst_dt) / n, 5),
+        "max_warming_rate_c_per_day": round(max_warming_rate, 4),
+        "max_cooling_rate_c_per_day": round(max_cooling_rate, 4),
+        "mean_warming_phase_rate_c_per_day": round(sum(pos_rates) / max(len(pos_rates), 1), 4),
+        "mean_cooling_phase_rate_c_per_day": round(sum(neg_rates) / max(len(neg_rates), 1), 4),
+        "mhw_onset_rate_c_per_day": round(r_onset, 4),
+        "mhw_decline_rate_c_per_day": round(r_decline, 4),
+        "onset_to_decline_asymmetry_ratio": round(r_onset / max(r_decline, 1e-6), 3),
+        "decadal_trend_c_per_decade": round(warming_per_decade, 4),
+        "mean_thermal_acceleration_c_per_day2": round(mean_acc_day2, 6),
+        "warming_acceleration_c_per_decade2": round(acc_dec2, 4),
+        "peak_mixed_layer_heat_flux_wm2": round(max(q_net_wm2), 2),
+        "min_mixed_layer_heat_flux_wm2": round(min(q_net_wm2), 2),
+        "reference": "Hobday et al. (2016, Prog. Oceanogr.); Oliver et al. (2021, Annu. Rev. Mar. Sci.); Schlegel et al. (2021)",
+    }
+
+
+def ocean_climate_velocity(
+    temporal_trend_c_per_year: float = 0.045,
+    meridional_grad_c_per_km: float = -0.0042,
+    zonal_grad_c_per_km: float = 0.0015,
+    species_max_dispersal_km_per_year: float = 8.5,
+) -> Dict[str, Any]:
+    """
+    Ocean Isotherm Migration & Climate Velocity Vector Model (V_SST).
+
+    Implements Loarie et al. (2009, Nature), Burrows et al. (2011, Science),
+    Molinos et al. (2016, Nature Climate Change), and Brito-Morales et al. (2020,
+    Nature Climate Change):
+        ||grad_h(SST)|| = sqrt((dSST/dx)^2 + (dSST/dy)^2)   [deg C / km]
+        V_SST = (dSST/dt) / ||grad_h(SST)||                 [km / year]
+
+    Parameters
+    ----------
+    temporal_trend_c_per_year : float, default 0.045
+        Local temporal warming rate dSST/dt in deg C / year (e.g., 0.045 C/yr = 0.45 C/decade).
+    meridional_grad_c_per_km : float, default -0.0042
+        Northward spatial SST gradient dSST/dy in deg C / km.
+    zonal_grad_c_per_km : float, default 0.0015
+        Eastward spatial SST gradient dSST/dx in deg C / km.
+    species_max_dispersal_km_per_year : float, default 8.5
+        Maximum autonomous biogeographic range shift speed of target marine taxon (km/year).
+    """
+    dsst_dt = float(temporal_trend_c_per_year)
+    gx = float(zonal_grad_c_per_km)
+    gy = float(meridional_grad_c_per_km)
+    v_disp = max(float(species_max_dispersal_km_per_year), 0.01)
+
+    grad_mag = math.hypot(gx, gy)
+    grad_safe = max(grad_mag, 1e-6)
+    velocity_km_yr = dsst_dt / grad_safe
+    velocity_km_decade = velocity_km_yr * 10.0
+
+    # Isotherm migration bearing (direction toward cooler water when warming)
+    bearing_rad = math.atan2(-gx * math.copysign(1.0, dsst_dt), -gy * math.copysign(1.0, dsst_dt))
+    bearing_deg = (math.degrees(bearing_rad) + 360.0) % 360.0
+
+    dispersal_lag_ratio = abs(velocity_km_yr) / v_disp
+    if dispersal_lag_ratio > 1.5:
+        ecological_regime = "HIGH EXTIRPATION / THERMAL ESCAPE DEFICIT (V_SST > 1.5x Dispersal Capacity)"
+    elif dispersal_lag_ratio > 1.0:
+        ecological_regime = "BIOGEOGRAPHIC TRACKING STRESS (Isotherm Velocity Exceeds Species Dispersal)"
+    else:
+        ecological_regime = "CLIMATE REFUGIA / TRACKABLE ISOTHERM SHIFT (V_SST <= Dispersal Capacity)"
+
+    return {
+        "temporal_warming_c_per_year": round(dsst_dt, 5),
+        "temporal_warming_c_per_decade": round(dsst_dt * 10.0, 4),
+        "spatial_gradient_c_per_km": round(grad_mag, 6),
+        "spatial_gradient_c_per_100km": round(grad_mag * 100.0, 4),
+        "climate_velocity_km_per_year": round(velocity_km_yr, 3),
+        "climate_velocity_km_per_decade": round(velocity_km_decade, 2),
+        "isotherm_migration_bearing_deg": round(bearing_deg, 2),
+        "species_dispersal_lag_ratio": round(dispersal_lag_ratio, 3),
+        "biogeographic_regime": ecological_regime,
+        "reference": "Loarie et al. (2009, Nature); Burrows et al. (2011, Science); Brito-Morales et al. (2020, Nat. Clim. Chang.)",
+    }
+
+
+def ectotherm_thermal_shock_index(
+    sst_series: Sequence[float],
+    acclimation_tau_days: float = 14.0,
+    q10_coefficient: float = 2.3,
+    critical_onset_rate_c_per_day: float = 0.18,
+    dt_days: float = 1.0,
+) -> Dict[str, Any]:
+    """
+    Marine Ectotherm Physiological Acclimation Lag & Rapid-Onset Thermal Shock Index (TSI).
+
+    Models dynamic thermal acclimation lag and metabolic oxygen-demand shock triggered by
+    rapid SST rate of change (dSST/dt), following Genin et al. (2020, PNAS, 'Rapid onsets
+    of warming events trigger mass mortality of coral-reef fish') and Pörtner (2021, J. Exp.
+    Biol., Oxygen- and Capacity-Limited Thermal Tolerance — OCLTT):
+        dT_acclim / dt = (SST(t) - T_acclim(t)) / tau_acclim
+        ThermalLag(t)  = SST(t) - T_acclim(t)
+        TSI(t)         = max(0, dSST/dt) * max(0, ThermalLag(t)) * Q10^(ThermalLag(t)/10)
+
+    Parameters
+    ----------
+    sst_series : Sequence[float]
+        Daily or regular SST observations (deg C).
+    acclimation_tau_days : float, default 14.0
+        Physiological thermal acclimation e-folding timescale tau_acclim in days.
+    q10_coefficient : float, default 2.3
+        Van 't Hoff Q10 temperature sensitivity of routine metabolic oxygen demand.
+    critical_onset_rate_c_per_day : float, default 0.18
+        Empirical rapid-warming mortality threshold in deg C / day (Genin et al., 2020).
+    """
+    vals = [float(v) for v in sst_series if v is not None and math.isfinite(float(v))]
+    n = len(vals)
+    if n < 2:
+        return {"error": "At least 2 valid SST observations are required.", "n": n}
+
+    tau = max(float(acclimation_tau_days), 0.5)
+    q10 = max(float(q10_coefficient), 1.0)
+    dt = max(float(dt_days), 1e-6)
+    alpha = 1.0 - math.exp(-dt / tau)
+
+    t_acclim = vals[0]
+    max_lag = 0.0
+    max_tsi = 0.0
+    max_metabolic_surge = 1.0
+    rapid_shock_days = 0
+
+    for i in range(1, n):
+        rate = (vals[i] - vals[i - 1]) / dt
+        t_acclim = t_acclim + alpha * (vals[i] - t_acclim)
+        lag = max(0.0, vals[i] - t_acclim)
+        q10_factor = q10 ** (lag / 10.0)
+        tsi = max(0.0, rate) * lag * q10_factor
+        if lag > max_lag:
+            max_lag = lag
+        if tsi > max_tsi:
+            max_tsi = tsi
+        if q10_factor > max_metabolic_surge:
+            max_metabolic_surge = q10_factor
+        if rate >= float(critical_onset_rate_c_per_day) and lag >= 0.5:
+            rapid_shock_days += 1
+
+    if max_tsi >= 0.45 or rapid_shock_days >= 3:
+        status = "CRITICAL THERMAL SHOCK (High Mass-Mortality & Hypoxic Scope Collapse Risk)"
+    elif max_tsi >= 0.18 or rapid_shock_days >= 1:
+        status = "MODERATE PHYSIOLOGICAL ACCLIMATION STRESS (Sublethal OCLTT Aerobic Compression)"
+    else:
+        status = "WITHIN ACCLIMATION CAPACITY (Gradual Warming Tracked by Physiology)"
+
+    return {
+        "n_observations": n,
+        "acclimation_tau_days": tau,
+        "q10_coefficient": q10,
+        "max_acclimation_lag_c": round(max_lag, 4),
+        "max_q10_metabolic_demand_multiplier": round(max_metabolic_surge, 4),
+        "max_thermal_shock_index": round(max_tsi, 4),
+        "rapid_onset_shock_days": rapid_shock_days,
+        "physiological_risk_status": status,
+        "reference": "Genin et al. (2020, PNAS); Pörtner (2021, J. Exp. Biol.); Morley et al. (2019)",
+    }
+
+
+def stochastic_sst_memory_ou(
+    sst_anomaly_series: Sequence[float],
+    dt_days: float = 1.0,
+    mixed_layer_depth_m: float = 25.0,
+) -> Dict[str, Any]:
+    """
+    Hasselmann (1976) / Martinez-Villalobos et al. (2022) Stochastic Ornstein-Uhlenbeck (OU)
+    SST Rate-of-Change Damping & Ocean Thermal Memory Model.
+
+    Estimates the stochastic climate feedback damping rate lambda (day^-1), thermal memory
+    e-folding timescale tau_mem = 1 / lambda (days), air-sea turbulent heat feedback
+    alpha_fb (W m^-2 K^-1), and stochastic weather-noise amplitude sigma_xi from an SST
+    anomaly trajectory SST'(t) and its finite-difference rate of change dSST'/dt:
+        dSST'/dt = -lambda * SST'(t) + sigma_xi * xi(t)
+
+    Parameters
+    ----------
+    sst_anomaly_series : Sequence[float]
+        Daily or regular SST anomaly series (deg C). If raw SST is passed, the sample mean
+        is automatically removed.
+    dt_days : float, default 1.0
+        Time step in days.
+    mixed_layer_depth_m : float, default 25.0
+        Mixed-layer depth in meters used to convert lambda into air-sea feedback (W m^-2 K^-1).
+    """
+    raw = [float(v) for v in sst_anomaly_series if v is not None and math.isfinite(float(v))]
+    n = len(raw)
+    if n < 5:
+        return {"error": "At least 5 valid observations are required.", "n": n}
+
+    dt = max(float(dt_days), 1e-6)
+    mean_v = sum(raw) / n
+    anom = [v - mean_v for v in raw]
+
+    # Forward rate dSST'/dt = (SST'_{t+1} - SST'_t) / dt regressed on SST'_t
+    x_vals = anom[:-1]
+    rates = [(anom[i + 1] - anom[i]) / dt for i in range(n - 1)]
+    var_x = sum(x * x for x in x_vals) / max(len(x_vals), 1)
+    cov_xr = sum(x_vals[i] * rates[i] for i in range(len(x_vals))) / max(len(x_vals), 1)
+
+    # Damping rate lambda > 0
+    lambda_day = max(0.002, min(1.5, -cov_xr / max(var_x, 1e-8)))
+    tau_memory_days = 1.0 / lambda_day
+    lag1_autocorr = math.exp(-lambda_day * dt)
+
+    # Residual stochastic forcing standard deviation sigma_xi (deg C / sqrt(day))
+    residuals = [rates[i] + lambda_day * x_vals[i] for i in range(len(x_vals))]
+    sigma_xi = math.sqrt(sum(r * r for r in residuals) / max(len(residuals), 1)) * math.sqrt(dt)
+
+    # Air-sea heat feedback coefficient alpha_fb = rho * c_p * h_MLD * lambda (W m^-2 K^-1)
+    heat_cap = 1025.0 * 3985.0 * float(mixed_layer_depth_m)
+    alpha_feedback_wm2_k = (lambda_day / 86400.0) * heat_cap
+
+    return {
+        "n_observations": n,
+        "damping_rate_lambda_per_day": round(lambda_day, 5),
+        "thermal_memory_tau_days": round(tau_memory_days, 2),
+        "implied_lag1_autocorrelation": round(lag1_autocorr, 4),
+        "stochastic_forcing_sigma_c_sqrt_day": round(sigma_xi, 4),
+        "air_sea_feedback_wm2_per_k": round(alpha_feedback_wm2_k, 2),
+        "predictability_horizon_days_95pct": round(tau_memory_days * math.log(20.0), 1),
+        "reference": "Hasselmann (1976, Tellus); Frankignoul & Hasselmann (1977); Martinez-Villalobos et al. (2022, J. Clim.)",
+    }
+
+
+def global_hypoxia_deadzone_index(
+    subpycnocline_do_mg_l: float,
+    chlorophyll_a_ug_l: float = 4.5,
+    secchi_depth_m: float = 4.0,
+    din_dip_molar_ratio: float = 20.0,
+    basin_code: str = "OCN_GULF_MEXICO",
+) -> Dict[str, Any]:
+    """
+    Compute the Global Coastal Hypoxia, Dead-Zone Severity & Eutrophication Risk Index
+    following Breitburg et al. (Science 2018, IOC-UNESCO GO2NE), Diaz & Rosenberg
+    (Science 2008), and Redfield (1958) stoichiometric imbalance diagnostics.
+
+    Parameters
+    ----------
+    subpycnocline_do_mg_l : float
+        Sub-pycnocline / bottom-water dissolved oxygen concentration in mg/L
+        (severe hypoxia threshold = 2.0 mg/L ~ 62.5 umol/L; suboxia = 0.5 mg/L).
+    chlorophyll_a_ug_l : float, default 4.5
+        Surface chlorophyll-a concentration in ug/L.
+    secchi_depth_m : float, default 4.0
+        Secchi disk water transparency depth in meters.
+    din_dip_molar_ratio : float, default 20.0
+        Dissolved inorganic nitrogen to phosphorus molar ratio (Redfield = 16:1).
+    basin_code : str, default 'OCN_GULF_MEXICO'
+        GOMD marine basin code (e.g., 'OCN_GULF_MEXICO', 'SEA_BALTIC', 'OCN_MARMARA').
+    """
+    do_val = max(0.0, float(subpycnocline_do_mg_l))
+    chla = max(0.01, float(chlorophyll_a_ug_l))
+    secchi = max(0.1, float(secchi_depth_m))
+    np_ratio = max(0.1, float(din_dip_molar_ratio))
+
+    # Oxygen deficit relative to biological hypoxia threshold (2.0 mg/L) and normoxia (6.0 mg/L)
+    hypoxia_deficit_mg_l = max(0.0, 2.0 - do_val)
+    do_stress = max(0.0, min(100.0, ((6.0 - do_val) / 5.5) * 100.0))
+    chla_stress = max(0.0, min(100.0, (math.log10(chla + 1.0) / math.log10(16.0)) * 100.0))
+    turbidity_stress = max(0.0, min(100.0, ((10.0 - min(secchi, 10.0)) / 9.0) * 100.0))
+    redfield_imbalance = abs(math.log2(np_ratio / 16.0))
+    stoich_stress = min(100.0, redfield_imbalance * 45.0)
+
+    composite_score = 0.45 * do_stress + 0.25 * chla_stress + 0.15 * turbidity_stress + 0.15 * stoich_stress
+
+    if do_val < 0.5:
+        regime = "ANOMALOUS_SUBOXIA_DEAD_ZONE"
+    elif do_val < 2.0:
+        regime = "SEVERE_HYPOXIA_DEAD_ZONE"
+    elif do_val < 4.0:
+        regime = "SEASONAL_HYPOXIA_VULNERABLE"
+    else:
+        regime = "NORMOXIC_OXIC"
+
+    return {
+        "basin_code": str(basin_code).upper(),
+        "subpycnocline_do_mg_l": round(do_val, 3),
+        "subpycnocline_do_umol_l": round(do_val * 31.25, 2),
+        "hypoxia_deficit_below_2mgl": round(hypoxia_deficit_mg_l, 3),
+        "chlorophyll_a_ug_l": round(chla, 3),
+        "secchi_depth_m": round(secchi, 2),
+        "din_dip_molar_ratio": round(np_ratio, 2),
+        "redfield_log2_imbalance": round(redfield_imbalance, 3),
+        "composite_deadzone_severity_0_100": round(composite_score, 2),
+        "oxygen_regime": regime,
+        "reference": "Breitburg et al. (Science 2018, IOC-UNESCO GO2NE); Diaz & Rosenberg (Science 2008)",
+    }
+
+
+def offshore_wind_marine_energy_lcoe(
+    capacity_mw: float = 1000.0,
+    capex_usd_per_kw: float = 3150.0,
+    opex_usd_per_kw_yr: float = 78.0,
+    net_capacity_factor: float = 0.48,
+    wacc: float = 0.065,
+    lifetime_years: int = 25,
+    grid_emission_factor_tco2_mwh: float = 0.42,
+) -> Dict[str, Any]:
+    """
+    Compute Offshore Wind & Marine Renewable Energy Levelized Cost of Electricity (LCOE),
+    Capital Recovery Factor (CRF), Annual Net Generation (GWh), Avoided CO2 Emissions,
+    and Co-Located Green Hydrogen / E-Ammonia Production Potential following IRENA
+    (2024, Renewable Power Generation Costs) and GWEC (2024, Global Offshore Wind Report).
+    """
+    cap_mw = max(0.1, float(capacity_mw))
+    capex_kw = max(100.0, float(capex_usd_per_kw))
+    opex_kw = max(1.0, float(opex_usd_per_kw_yr))
+    cf = max(0.05, min(0.95, float(net_capacity_factor)))
+    r = max(0.001, float(wacc))
+    n = max(5, int(lifetime_years))
+    ef = max(0.0, float(grid_emission_factor_tco2_mwh))
+
+    crf = (r * ((1.0 + r) ** n)) / (((1.0 + r) ** n) - 1.0)
+    annual_mwh_per_kw = 8.76 * cf
+    lcoe_usd_mwh = ((capex_kw * crf) + opex_kw) / annual_mwh_per_kw
+    annual_gwh = cap_mw * 8.76 * cf
+    avoided_tco2_yr = annual_gwh * 1000.0 * ef
+    # PEM / Alkaline electrolyzer specific consumption ~ 52 MWh / tonne H2
+    green_h2_tonnes_yr = (annual_gwh * 1000.0) / 52.0
+    green_ammonia_tonnes_yr = green_h2_tonnes_yr * 5.5
+
+    return {
+        "installed_capacity_mw": round(cap_mw, 2),
+        "net_capacity_factor": round(cf, 4),
+        "capital_recovery_factor": round(crf, 5),
+        "lcoe_usd_per_mwh": round(lcoe_usd_mwh, 2),
+        "annual_generation_gwh": round(annual_gwh, 2),
+        "annual_avoided_co2_tonnes": round(avoided_tco2_yr, 1),
+        "potential_green_hydrogen_tonnes_yr": round(green_h2_tonnes_yr, 1),
+        "potential_green_ammonia_tonnes_yr": round(green_ammonia_tonnes_yr, 1),
+        "reference": "IRENA (2024, Renewable Power Generation Costs); GWEC (2024, Global Offshore Wind Report)",
+    }
+
+
+def marine_plastic_ghost_gear_risk(
+    plastic_leakage_kt_yr: float = 108.0,
+    beach_litter_items_100m: float = 435.0,
+    aldfg_ghost_gear_share_pct: float = 19.8,
+    coastline_km: float = 8333.0,
+) -> Dict[str, Any]:
+    """
+    Compute the Global Marine Macro-Plastic Leakage, Coastal Debris Density &
+    Abandoned/Lost Fishing Gear (ALDFG / Ghost Gear) Ecological Risk Index (0–100)
+    following Jambeck et al. (Science 2015), Meijer et al. (Science Advances 2021),
+    Richardson et al. (Science Advances 2022), and UNEP GPML / OECD (2024).
+    """
+    leak = max(0.0, float(plastic_leakage_kt_yr))
+    beach = max(0.0, float(beach_litter_items_100m))
+    ghost = max(0.0, min(100.0, float(aldfg_ghost_gear_share_pct)))
+    coast = max(1.0, float(coastline_km))
+
+    leak_per_km_t = (leak * 1000.0) / coast
+    s_leak = min(100.0, (math.log1p(leak) / math.log1p(1800.0)) * 100.0)
+    s_beach = min(100.0, (beach / 1000.0) * 100.0)
+    s_ghost = min(100.0, (ghost / 45.0) * 100.0)
+    composite_risk = 0.45 * s_leak + 0.30 * s_beach + 0.25 * s_ghost
+
+    if beach <= 20.0:
+        msfd_status = "GES_ACHIEVED (<=20 items/100m — EU MSFD D10 Benchmark)"
+    elif beach <= 200.0:
+        msfd_status = "MODERATE_POLLUTION (20-200 items/100m)"
+    else:
+        msfd_status = "HIGH_MACRO_LITTER_EXCEEDANCE (>200 items/100m)"
+
+    return {
+        "plastic_leakage_kt_yr": round(leak, 2),
+        "specific_coastal_flux_tonnes_per_km": round(leak_per_km_t, 2),
+        "beach_macro_litter_items_100m": round(beach, 1),
+        "aldfg_ghost_gear_share_pct": round(ghost, 2),
+        "estimated_aldfg_leakage_kt_yr": round(leak * (ghost / 100.0), 3),
+        "composite_plastic_risk_index_0_100": round(composite_risk, 2),
+        "msfd_descriptor10_status": msfd_status,
+        "reference": "UNEP GPML (2024); Meijer et al. (2021, Sci. Adv.); Richardson et al. (2022, Sci. Adv.)",
+    }
+
+
+def coastal_storm_surge_offshore_wind_nexus(
+    tide_high_water_m_msl: float = 1.45,
+    wind_50m_ms: float = 13.8,
+    wind_10m_max_ms: float = 21.4,
+    sea_level_pressure_kpa: float = 99.4,
+    turbine_rated_mw: float = 15.0,
+) -> Dict[str, Any]:
+    """
+    Compute the Coastal Storm-Surge Inverse Barometer Effect, Wind-Stress Setup &
+    50m Offshore Wind Turbine Power Curve / Cut-Out Curtailment Nexus (Vousdoukas
+    et al., Nature Climate Change 2018 & Nature Communications 2020; Muis et al.,
+    Nature Communications 2020; NASA POWER MERRA-2 & NOAA CO-OPS/GLOSS).
+    """
+    hw_m = float(tide_high_water_m_msl)
+    v50 = max(0.0, float(wind_50m_ms))
+    v10_max = max(0.0, float(wind_10m_max_ms))
+    p_kpa = max(85.0, min(108.0, float(sea_level_pressure_kpa)))
+    rated_mw = max(0.1, float(turbine_rated_mw))
+
+    # Inverse barometer surge: ~ +1 cm (+0.01 m) per 1 hPa (0.1 kPa) below 101.325 kPa
+    ib_surge_m = max(0.0, (101.325 - p_kpa) * 10.0 * 0.01)
+    # Wind-driven shallow coastal setup approximation
+    wind_setup_m = 0.0018 * (v10_max ** 2)
+    total_extreme_water_m = hw_m + ib_surge_m + wind_setup_m
+
+    # Standard IEC Class I 15 MW offshore wind turbine cubic power curve (cut-in 3 m/s, rated 11 m/s, cut-out 25 m/s)
+    if v50 < 3.0 or v50 >= 25.0:
+        cf_instant = 0.0
+    elif v50 >= 11.0:
+        cf_instant = 1.0
+    else:
+        cf_instant = ((v50 - 3.0) / (11.0 - 3.0)) ** 3
+    instant_power_mw = rated_mw * cf_instant
+    storm_curtailment = v50 >= 25.0 or v10_max >= 25.0
+
+    surge_risk_score = min(100.0, max(0.0, (total_extreme_water_m / 3.5) * 100.0))
+    return {
+        "observed_high_water_m_msl": round(hw_m, 3),
+        "inverse_barometer_surge_m": round(ib_surge_m, 3),
+        "wind_stress_setup_m": round(wind_setup_m, 3),
+        "total_storm_tide_elevation_m": round(total_extreme_water_m, 3),
+        "offshore_wind_50m_ms": round(v50, 2),
+        "instantaneous_capacity_factor": round(cf_instant, 4),
+        "turbine_output_mw": round(instant_power_mw, 3),
+        "storm_cutout_curtailment_active": bool(storm_curtailment),
+        "coastal_surge_hazard_index_0_100": round(surge_risk_score, 2),
+        "reference": "Vousdoukas et al. (2020, Nat. Commun.); Muis et al. (2020, Nat. Commun.); NASA POWER MERRA-2 & NOAA CO-OPS",
+    }
+
+
+def climate_teleconnection_regime(
+    enso_oni_c: float = 1.15,
+    iod_dmi_c: float = 0.48,
+    pdo_index: float = -0.85,
+    amo_index_c: float = 0.34,
+    nao_index: float = 0.62,
+    sam_index: float = 0.95,
+    amoc_26n_sv: float = 16.4,
+) -> Dict[str, Any]:
+    """
+    Evaluate Coupled Ocean-Atmosphere Teleconnection Regimes (ENSO ONI, IOD DMI,
+    PDO, AMO, NAO, SAM) and Atlantic Meridional Overturning Circulation (AMOC 26.5N
+    RAPID-MOCHA transport in Sverdrups) following McPhaden et al. (Science 2006),
+    Saji et al. (Nature 1999), and Caesar et al. (Nature Geoscience 2021).
+    """
+    oni = float(enso_oni_c)
+    dmi = float(iod_dmi_c)
+    pdo = float(pdo_index)
+    amo = float(amo_index_c)
+    nao = float(nao_index)
+    sam = float(sam_index)
+    amoc = max(0.0, float(amoc_26n_sv))
+
+    if oni >= 1.5:
+        enso_phase = "STRONG_EL_NINO (ONI >= +1.5 C)"
+    elif oni >= 0.5:
+        enso_phase = "EL_NINO (+0.5 <= ONI < +1.5 C)"
+    elif oni <= -1.5:
+        enso_phase = "STRONG_LA_NINA (ONI <= -1.5 C)"
+    elif oni <= -0.5:
+        enso_phase = "LA_NINA (-1.5 < ONI <= -0.5 C)"
+    else:
+        enso_phase = "ENSO_NEUTRAL (-0.5 < ONI < +0.5 C)"
+
+    iod_phase = "POSITIVE_IOD" if dmi >= 0.4 else ("NEGATIVE_IOD" if dmi <= -0.4 else "NEUTRAL_IOD")
+    amoc_deficit_pct = max(0.0, ((18.5 - amoc) / 18.5) * 100.0)
+    amoc_status = "WEAKENED_OVERTURNING_WARNING (<15 Sv)" if amoc < 15.0 else "NORMAL_RANGE (15-20 Sv)"
+
+    compound_forcing = min(
+        100.0,
+        28.0 * min(abs(oni) / 2.0, 1.5)
+        + 18.0 * min(abs(dmi) / 1.0, 1.5)
+        + 16.0 * min(abs(amo) / 0.5, 1.5)
+        + 18.0 * min(amoc_deficit_pct / 20.0, 1.5)
+        + 10.0 * min(abs(nao) / 2.0, 1.5)
+        + 10.0 * min(abs(sam) / 2.0, 1.5),
+    )
+
+    return {
+        "enso_oni_c": round(oni, 3),
+        "enso_phase": enso_phase,
+        "iod_dmi_c": round(dmi, 3),
+        "iod_phase": iod_phase,
+        "pdo_index": round(pdo, 3),
+        "amo_index_c": round(amo, 3),
+        "nao_index": round(nao, 3),
+        "sam_index": round(sam, 3),
+        "amoc_rapid_26n_sv": round(amoc, 2),
+        "amoc_historical_deficit_pct": round(amoc_deficit_pct, 2),
+        "amoc_regime_status": amoc_status,
+        "compound_teleconnection_forcing_index_0_100": round(compound_forcing, 2),
+        "reference": "McPhaden et al. (2006, Science); Saji et al. (1999, Nature); Caesar et al. (2021, Nat. Geosci.)",
+    }
+
+
+def coral_bleaching_dhw_risk(
+    dhw_c_weeks: float = 8.6,
+    hotspot_sst_anomaly_c: float = 1.45,
+    omega_aragonite: float = 3.15,
+    live_coral_cover_pct: float = 28.5,
+) -> Dict[str, Any]:
+    """
+    Compute NOAA Coral Reef Watch (CRW v3.1) Bleaching Alert Level (0 to Alert Level 5),
+    Aragonite Calcification Impedance, and Reef Ecological Collapse Probability
+    (Liu et al., Remote Sensing 2014; Hughes et al., Nature 2017/2018; Kleypas et al., Science 1999).
+    """
+    dhw = max(0.0, float(dhw_c_weeks))
+    hs = float(hotspot_sst_anomaly_c)
+    omega = max(0.5, float(omega_aragonite))
+    cover = max(0.0, min(100.0, float(live_coral_cover_pct)))
+
+    if hs <= 0.0:
+        alert_level = "NO_STRESS (HotSpot <= 0 C)"
+    elif hs < 1.0:
+        alert_level = "BLEACHING_WATCH (0 < HotSpot < 1 C)"
+    elif dhw < 4.0:
+        alert_level = "BLEACHING_WARNING (HotSpot >= 1 C, 0 < DHW < 4)"
+    elif dhw < 8.0:
+        alert_level = "ALERT_LEVEL_1_SIGNIFICANT_BLEACHING (4 <= DHW < 8 C-weeks)"
+    elif dhw < 12.0:
+        alert_level = "ALERT_LEVEL_2_SEVERE_MORTALITY (8 <= DHW < 12 C-weeks)"
+    elif dhw < 16.0:
+        alert_level = "ALERT_LEVEL_3_MULTI_SPECIES_MORTALITY (12 <= DHW < 16 C-weeks)"
+    elif dhw < 20.0:
+        alert_level = "ALERT_LEVEL_4_SEVERE_MULTI_SPECIES_MORTALITY (16 <= DHW < 20 C-weeks)"
+    else:
+        alert_level = "ALERT_LEVEL_5_NEAR_COMPLETE_MORTALITY (DHW >= 20 C-weeks)"
+
+    calcification_penalty_pct = max(0.0, min(100.0, ((3.5 - omega) / 2.5) * 100.0))
+    mortality_risk = min(100.0, 0.60 * min(100.0, (dhw / 16.0) * 100.0) + 0.25 * calcification_penalty_pct + 0.15 * max(0.0, (40.0 - cover) * 2.0))
+
+    return {
+        "dhw_c_weeks": round(dhw, 2),
+        "hotspot_sst_anomaly_c": round(hs, 2),
+        "omega_aragonite": round(omega, 3),
+        "live_coral_cover_pct": round(cover, 2),
+        "noaa_crw_alert_status": alert_level,
+        "calcification_depression_pct": round(calcification_penalty_pct, 2),
+        "reef_mortality_risk_index_0_100": round(mortality_risk, 2),
+        "reference": "Liu et al. (2014, Remote Sens.); Hughes et al. (2018, Nature); NOAA Coral Reef Watch v3.1",
+    }
+
+
+def lme_trophic_hypoxia_stress(
+    primary_productivity_mgc_m2_d: float = 680.0,
+    fish_landings_mt_yr: float = 1.45,
+    mean_trophic_level: float = 3.24,
+    hypoxic_shelf_area_km2: float = 14500.0,
+    sst_anomaly_c: float = 0.92,
+) -> Dict[str, Any]:
+    """
+    Evaluate UN Large Marine Ecosystem (LME) Trophic Exploitation, Pauly & Christensen
+    (1995) Primary Production Required (PPR), Fishing-down-Marine-Food-Webs status,
+    and Shelf Deoxygenation Stress across the 66 global LMEs (Pauly et al., Science 1998;
+    Sherman & Hempel, UNDP/GEF/NOAA 2008; Breitburg et al., Science 2018).
+    """
+    pp = max(50.0, float(primary_productivity_mgc_m2_d))
+    catch_mt = max(0.001, float(fish_landings_mt_yr))
+    mtl = max(2.0, min(5.0, float(mean_trophic_level)))
+    hyp_km2 = max(0.0, float(hypoxic_shelf_area_km2))
+    sst_a = float(sst_anomaly_c)
+
+    # Pauly & Christensen (1995): PPR = Catch * (1/9) * 10^(MTL - 1) (with 10% trophic transfer efficiency)
+    ppr_mt_c = (catch_mt / 9.0) * (10.0 ** (mtl - 1.0))
+    trophic_depletion_score = max(0.0, min(100.0, ((3.65 - mtl) / 1.15) * 100.0))
+    hypoxia_score = min(100.0, (math.log1p(hyp_km2) / math.log1p(80000.0)) * 100.0)
+    thermal_score = min(100.0, max(0.0, (sst_a / 2.2) * 100.0))
+    composite_lme_stress = 0.40 * trophic_depletion_score + 0.35 * hypoxia_score + 0.25 * thermal_score
+
+    return {
+        "primary_productivity_mgc_m2_d": round(pp, 2),
+        "fish_landings_mt_yr": round(catch_mt, 3),
+        "mean_trophic_level_mtl": round(mtl, 3),
+        "primary_production_required_mt_c_yr": round(ppr_mt_c, 3),
+        "hypoxic_shelf_area_km2": round(hyp_km2, 1),
+        "trophic_web_erosion_score_0_100": round(trophic_depletion_score, 2),
+        "shelf_hypoxia_score_0_100": round(hypoxia_score, 2),
+        "composite_lme_ecosystem_stress_0_100": round(composite_lme_stress, 2),
+        "reference": "Pauly et al. (1998, Science); Sherman & Hempel (2008, UN LME Report); Breitburg et al. (2018, Science)",
+    }
+
+
+def river_delta_plastic_nutrient_export(
+    discharge_km3_yr: float = 420.0,
+    plastic_export_tonnes_yr: float = 28500.0,
+    din_export_kt_n_yr: float = 540.0,
+    dip_export_kt_p_yr: float = 48.0,
+    relative_subsidence_mm_yr: float = 8.4,
+) -> Dict[str, Any]:
+    """
+    Compute Global River-Delta Macro-Plastic Emission Density, GLOBAL NEWS-2
+    Dissolved Inorganic N:P Molar Stoichiometry Deviation from Redfield (16:1),
+    and Deltaic Subsidence-Drowning Risk across the top 50 river basins (Meijer et al.,
+    Sci. Adv. 2021; Mayorga et al., Environ. Model. Softw. 2010; Syvitski et al., Nat. Geosci. 2009).
+    """
+    q_km3 = max(0.1, float(discharge_km3_yr))
+    plast_t = max(0.0, float(plastic_export_tonnes_yr))
+    din_kt = max(0.01, float(din_export_kt_n_yr))
+    dip_kt = max(0.001, float(dip_export_kt_p_yr))
+    sub_mm = max(0.0, float(relative_subsidence_mm_yr))
+
+    # Molar N:P ratio = (mass_N / 14.007) / (mass_P / 30.974)
+    np_molar = (din_kt / 14.007) / (dip_kt / 30.974)
+    redfield_excess_ratio = np_molar / 16.0
+    plastic_conc_g_m3 = (plast_t * 1e6) / (q_km3 * 1e9)
+
+    s_plast = min(100.0, (math.log1p(plast_t) / math.log1p(120000.0)) * 100.0)
+    s_eutro = min(100.0, (abs(np_molar - 16.0) / 48.0) * 100.0)
+    s_subs = min(100.0, (sub_mm / 25.0) * 100.0)
+    delta_vulnerability = 0.40 * s_plast + 0.35 * s_eutro + 0.25 * s_subs
+
+    return {
+        "discharge_km3_yr": round(q_km3, 2),
+        "plastic_export_tonnes_yr": round(plast_t, 1),
+        "mean_plastic_concentration_g_m3": round(plastic_conc_g_m3, 6),
+        "din_export_kt_n_yr": round(din_kt, 2),
+        "dip_export_kt_p_yr": round(dip_kt, 2),
+        "estuarine_din_dip_molar_ratio": round(np_molar, 2),
+        "redfield_16_1_deviation_multiple": round(redfield_excess_ratio, 2),
+        "relative_subsidence_mm_yr": round(sub_mm, 2),
+        "delta_anthropogenic_pressure_index_0_100": round(delta_vulnerability, 2),
+        "reference": "Meijer et al. (2021, Sci. Adv.); Mayorga et al. (2010, GLOBAL NEWS-2); Syvitski et al. (2009, Nat. Geosci.)",
+    }
+
+
+def sids_slr_cyclone_vulnerability(
+    coastal_pop_below_5m_pct: float = 64.0,
+    annual_cyclone_damage_gdp_pct: float = 3.2,
+    eez_to_land_ratio: float = 3080.0,
+    blue_economy_gdp_share_pct: float = 48.5,
+    adaptation_finance_usd_capita: float = 185.0,
+) -> Dict[str, Any]:
+    """
+    Compute the UN-OHRLLS / AOSIS Small Island Developing States (SIDS) Multidimensional
+    Climate-Ocean Vulnerability & Blue Economy Resilience Index across 38 UN SIDS nations
+    (IPCC AR6 WGII Ch. 15 Small Islands 2022; UN SIDS4 Antigua and Barbuda Agenda 2024).
+    """
+    pop5m = max(0.0, min(100.0, float(coastal_pop_below_5m_pct)))
+    cyc_loss = max(0.0, float(annual_cyclone_damage_gdp_pct))
+    eez_ratio = max(1.0, float(eez_to_land_ratio))
+    blue_gdp = max(0.0, min(100.0, float(blue_economy_gdp_share_pct)))
+    fin_cap = max(0.0, float(adaptation_finance_usd_capita))
+
+    exposure_score = min(100.0, 0.55 * pop5m + 0.45 * min(100.0, cyc_loss * 12.5))
+    ocean_stewardship_leverage = min(100.0, (math.log10(eez_ratio) / 4.5) * 60.0 + 0.40 * blue_gdp)
+    adaptation_buffer = min(100.0, (math.log1p(fin_cap) / math.log1p(500.0)) * 100.0)
+    net_sids_vulnerability = max(0.0, min(100.0, 0.65 * exposure_score + 0.20 * (100.0 - adaptation_buffer) + 0.15 * (100.0 - ocean_stewardship_leverage)))
+
+    return {
+        "coastal_pop_below_5m_pct": round(pop5m, 2),
+        "annual_cyclone_damage_gdp_pct": round(cyc_loss, 2),
+        "eez_to_land_ratio": round(eez_ratio, 1),
+        "blue_economy_gdp_share_pct": round(blue_gdp, 2),
+        "adaptation_finance_usd_capita": round(fin_cap, 2),
+        "slr_cyclone_exposure_score_0_100": round(exposure_score, 2),
+        "ocean_stewardship_leverage_0_100": round(ocean_stewardship_leverage, 2),
+        "net_sids_vulnerability_index_0_100": round(net_sids_vulnerability, 2),
+        "reference": "IPCC AR6 WGII Ch. 15 (Mycoo et al., 2022); UN SIDS4 ABAS Agenda (2024); Sachs et al. (UN MVI, 2024)",
+    }
+
+
+def polar_cryosphere_basal_melt_albedo(
+    sea_ice_extent_mkm2: float = 0.72,
+    ice_thickness_m: float = 1.65,
+    basal_melt_rate_m_yr: float = 14.5,
+    albedo_radiative_forcing_wm2: float = 3.85,
+) -> Dict[str, Any]:
+    """
+    Evaluate Polar Cryosphere Sea-Ice Volume Anomaly, Ice-Shelf Basal Melt Freshwater Flux
+    (Gt/yr), and Ice-Albedo Radiative Amplification across 20 Arctic & Antarctic basins
+    (Rignot et al., PNAS 2019; Paolo et al., Science 2015; NSIDC / CryoSat-2 / ICESat-2 2026).
+    """
+    ext = max(0.01, float(sea_ice_extent_mkm2))
+    thick = max(0.05, float(ice_thickness_m))
+    melt_m = max(0.0, float(basal_melt_rate_m_yr))
+    forcing = max(0.0, float(albedo_radiative_forcing_wm2))
+
+    # Sea-ice volume in thousand km3: extent (10^6 km2) * thickness (m / 1000 km) * 1000
+    ice_volume_kkm3 = ext * thick
+    # Effective ice-shelf fringe area ~ 6% of basin extent -> basal freshwater flux in Gt/yr (rho_ice = 0.917 Gt/km3)
+    basal_melt_flux_gt_yr = ext * 0.06 * melt_m * 0.917
+    cryo_instability_score = min(100.0, 0.45 * min(100.0, (melt_m / 35.0) * 100.0) + 0.35 * min(100.0, (forcing / 6.5) * 100.0) + 0.20 * max(0.0, (3.0 - thick) / 3.0 * 100.0))
+
+    return {
+        "sea_ice_extent_mkm2": round(ext, 3),
+        "mean_ice_thickness_m": round(thick, 3),
+        "estimated_sea_ice_volume_kkm3": round(ice_volume_kkm3, 3),
+        "basal_melt_rate_m_yr": round(melt_m, 2),
+        "estimated_basal_freshwater_flux_gt_yr": round(basal_melt_flux_gt_yr, 2),
+        "albedo_radiative_forcing_wm2": round(forcing, 2),
+        "cryosphere_instability_index_0_100": round(cryo_instability_score, 2),
+        "reference": "Rignot et al. (2019, PNAS); Kacimi & Kwok (2022, Cryosphere); NSIDC / CryoSat-2 / ICESat-2 (2026)",
+    }
+
+
+
+
+
+
+
+
+