pluvium 0.1.0__py3-none-any.whl

pluvium/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Pluvium: hour-by-hour rain forecasts for every Caribbean town, on the NatureV1 / iHELIX engine.
+
+``pluvium forecast`` makes the live forecast with a published model; ``pluvium program`` trains one on a single GPU.
+See :mod:`pluvium.model` for the architecture and its experimental components.
+"""
+
+__version__ = "0.1.0"
+
+from .domain import Gazetteer, Geography, PointSet  # noqa: E402
+from .model import PluviumConfig, PluviumModel  # noqa: E402
+from .schedule import DEFAULT, Schedule  # noqa: E402
+
+__all__ = ["DEFAULT", "Gazetteer", "Geography", "PluviumConfig", "PluviumModel", "PointSet", "Schedule", "__version__"]

pluvium/advection.py

@@ -0,0 +1,70 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Rain already falling, carried forward (experimental as an input to a neural forecaster of this kind).
+
+For the first hours of a forecast nothing beats extrapolation: the shower over the sea east of Port Antonio at
+2 pm is over Port Antonio at 3 pm if the steering wind is 25 km/h from the east. Radar nowcasting systems (pySTEPS,
+DGMR, NowcastNet's evolution network) are built on this. The Caribbean has little open radar, so here the rain field
+of the last hour (CMORPH in training, GOES-East live) is advected semi-Lagrangian-wise along the steering wind (the
+mean of the driving model's 850 and 700 hPa winds at the issue time): each point's value for forecast hour L is the
+observed rain at the point the wind will carry to it in L + 1 hours. The network gets that as one more input per
+point and hour for the first 12 hours, with a flag for whether the rain field was observed, and learns how fast
+such rain decays or grows.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .domain import KM_PER_DEG
+
+HOURS = 12            # advected rain is given for forecast hours 0-11
+
+
+def _xyz(lat, lon) -> np.ndarray:
+    la, lo = np.radians(np.asarray(lat, np.float64)), np.radians(np.asarray(lon, np.float64))
+    return np.stack([np.cos(la) * np.cos(lo), np.cos(la) * np.sin(lo), np.sin(la)], -1)
+
+
+class Advector:
+    """Observed rain at scattered points (``obs_lat``, ``obs_lon``) read at upstream positions."""
+
+    def __init__(self, obs_lat: np.ndarray, obs_lon: np.ndarray, neighbours: int = 4, max_km: float = 45.0) -> None:
+        self.xyz = _xyz(obs_lat, obs_lon)
+        self.k, self.max_km = neighbours, max_km
+
+    def read(self, values: np.ndarray, lat: np.ndarray, lon: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """Inverse-distance mean of the ``k`` nearest observed values within ``max_km`` of each point, and whether
+        any was found."""
+        from scipy.spatial import cKDTree
+
+        ok = np.isfinite(values)
+        if not ok.any():
+            return np.zeros(np.shape(lat), np.float32), np.zeros(np.shape(lat), bool)
+        tree = cKDTree(self.xyz[ok])
+        dist, idx = tree.query(_xyz(lat, lon).reshape(-1, 3), k=min(self.k, int(ok.sum())))
+        dist, idx = np.atleast_2d(dist.T).T if dist.ndim == 1 else dist, np.atleast_2d(idx.T).T if idx.ndim == 1 else idx
+        km = dist * 6371.0
+        w = np.where(km <= self.max_km, 1.0 / (km + 2.0), 0.0)
+        vals = values[ok][idx]
+        found = w.sum(-1) > 0
+        out = (w * vals).sum(-1) / np.maximum(w.sum(-1), 1e-12)
+        return out.reshape(np.shape(lat)).astype(np.float32), found.reshape(np.shape(lat))
+
+    def extrapolate(self, values: np.ndarray, lat: np.ndarray, lon: np.ndarray, u: np.ndarray, v: np.ndarray,
+                    leads: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """``(len(leads), N)`` advected rain (mm/h) and found-flags for forecast hours ``leads`` at points, with the
+        steering wind ``u``/``v`` (m/s, ``(N,)``)."""
+        lat, lon = np.asarray(lat, np.float64), np.asarray(lon, np.float64)
+        out = np.zeros((len(leads), lat.size), np.float32)
+        found = np.zeros((len(leads), lat.size), bool)
+        coslat = np.cos(np.radians(lat))
+        for i, lead in enumerate(leads):
+            dt = float(lead) + 1.0                                # last observed hour's middle -> this hour's middle
+            up_lat = lat - v * 3.6 * dt / KM_PER_DEG
+            up_lon = lon - u * 3.6 * dt / (KM_PER_DEG * np.maximum(coslat, 0.2))
+            out[i], found[i] = self.read(values, up_lat, up_lon)
+        return out, found
+
+
+__all__ = ["Advector", "HOURS"]

pluvium/atmos/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Theoretical atmospheric physics computed from the driving fields and given to the network as inputs.
+
+Each module targets a known weakness of data-driven rain forecasting in the tropics:
+
+* :mod:`.thermo`      -- exact moist thermodynamics (Bolton 1980) and parcel CAPE/CIN, instead of crude indices;
+* :mod:`.moisture`    -- column relative humidity and its exponential control of tropical rain (Bretherton et al.
+  2004), and the vertically integrated moisture-flux convergence;
+* :mod:`.saharan`     -- the Saharan air layer, which suppresses Caribbean summer showers;
+* :mod:`.waves`       -- tropical waves: trough axes at 700 hPa, their westward motion and arrival times;
+* :mod:`.cyclones`    -- tropical cyclones: vortex detection and a parametric rain field (R-CLIPER-style), because
+  cyclones are too rare in any training period for a network to learn their rain from data alone;
+* :mod:`.sea_breeze`  -- the sea-breeze front: when it reaches each inland point, from gravity-current theory;
+* :mod:`.diurnal`     -- the heating clock: insolation since sunrise, and the nocturnal maritime rain maximum;
+* :mod:`.upslope`     -- wind meeting terrain at every point: forced ascent at two scales, and blocking (Froude);
+* :mod:`.assemble`    -- all of it as the extra coarse channels and per-point inputs of version 3.
+"""
+
+from .assemble import CHANNELS as ATMOS_CHANNELS
+from .assemble import POINT_FEATURES, atmos_channels, point_physics
+from .cyclones import cyclone_features, find_cyclones, parametric_rain
+from .diurnal import diurnal_features
+from .moisture import column_relative_humidity, moisture_channels
+from .saharan import saharan_index
+from .sea_breeze import sea_breeze_arrival
+from .thermo import cape_cin, lcl, mixing_ratio, saturation_vapour_pressure, theta_e_bolton
+from .upslope import upslope_features
+from .waves import wave_channels
+
+__all__ = ["ATMOS_CHANNELS", "POINT_FEATURES", "atmos_channels", "cape_cin", "point_physics", "upslope_features", "column_relative_humidity", "cyclone_features", "diurnal_features",
+           "find_cyclones", "lcl", "mixing_ratio", "moisture_channels", "parametric_rain", "saharan_index",
+           "saturation_vapour_pressure", "sea_breeze_arrival", "theta_e_bolton", "wave_channels"]

pluvium/atmos/assemble.py

@@ -0,0 +1,63 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Putting the atmospheric physics together: the extra coarse channels and the extra per-point inputs of version 3.
+
+Coarse channels (on the 1-degree grid, per frame): CAPE, CIN and LCL height of an 850 hPa parcel; column relative
+humidity and the Bretherton rain rate it implies; vertically integrated moisture-flux convergence; the Saharan air
+layer index; tropical-wave trough strength and arrival time; parametric cyclone rain and closeness to a cyclone.
+
+Per-point inputs (per frame): forced ascent at two terrain scales and the Froude number; the sea-breeze pulse and the
+hours since the front passed; insolation since sunrise and the land and sea rain clocks.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .cyclones import cyclone_features
+from .diurnal import diurnal_features
+from .moisture import moisture_channels
+from .saharan import saharan_index
+from .sea_breeze import sea_breeze_arrival
+from .thermo import cape_cin
+from .upslope import upslope_features
+from .waves import wave_channels
+
+CHANNELS = ("cape", "cin", "lcl_height", "crh", "bretherton_rate", "vimfc", "saharan", "wave_trough", "wave_eta",
+            "tc_rain", "tc_distance")
+POINT_FEATURES = ("upslope_5km", "upslope_20km", "froude", "sea_breeze_pulse", "sea_breeze_since", "insolation",
+                  "land_clock", "sea_clock")
+NEEDS = tuple(f"{v}{p}" for v in ("t", "q", "u", "v") for p in (850, 700, 500, 200))
+
+
+def atmos_channels(fields: dict, upper: dict, lat: np.ndarray, lon: np.ndarray, hours: np.ndarray) -> np.ndarray:
+    """``(F, len(CHANNELS), H, W)`` from raw fields and upper-air fields already on the hourly grid."""
+    t = {p: upper[f"t{p}"] for p in (850, 700, 500, 200)}
+    q = {p: upper[f"q{p}"] for p in (850, 700, 500, 200)}
+    cape, cin, lcl_m = cape_cin(t, q)
+    moist = moisture_channels(upper, lat, lon)
+    sal = saharan_index(upper, hours)
+    waves = wave_channels(upper, lat, lon, hours)
+    tc = cyclone_features(fields, upper, lat, lon)
+    out = np.concatenate([np.stack([np.log1p(cape) / 7.0, cin / 100.0, lcl_m / 1000.0], 1), moist, sal[:, None],
+                          waves, tc], 1)
+    return np.nan_to_num(out).astype(np.float32)
+
+
+def point_physics(terrain, statics: np.ndarray, lat: np.ndarray, lon: np.ndarray, u10: np.ndarray, v10: np.ndarray,
+                  hours: np.ndarray, kind: np.ndarray | None = None) -> np.ndarray:
+    """``(F, N, len(POINT_FEATURES))`` from the points' static descriptors and the frame winds at them."""
+    from ..domain import STATIC_FEATURES
+
+    col = {name: k for k, name in enumerate(STATIC_FEATURES)}
+    relief = statics[:, col["elev_max"]] * 1000.0
+    up = upslope_features(terrain, lat, lon, u10, v10, relief)
+    land = statics[:, col["land_5km"]] > 0.5 if kind is None else np.asarray(kind) == 0
+    coast_km = statics[:, col["coast_km"]] * 100.0
+    pulse, since = sea_breeze_arrival(coast_km, statics[:, col["sea_dir_x"]], statics[:, col["sea_dir_y"]], u10, v10,
+                                      lon, hours, land)
+    di = diurnal_features(lat, lon, hours, statics[:, col["land_15km"]])
+    return np.concatenate([up, pulse[..., None], (since / 12.0)[..., None], di], -1).astype(np.float32)
+
+
+__all__ = ["CHANNELS", "NEEDS", "POINT_FEATURES", "atmos_channels", "point_physics"]

pluvium/atmos/cyclones.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Tropical cyclones: too rare to learn from data, too important to miss.
+
+Even six training years hold only a handful of hurricanes passing near any one island, so a network cannot learn
+from data alone how rain is arranged around a storm. Theory and climatology give the shape:
+
+* **finding the storm** -- a minimum of sea-level pressure below 1006 hPa with strong cyclonic 850 hPa vorticity;
+  its strength from the pressure deficit (the Atkinson-Holliday wind-pressure relation, ``V = 6.7 (1010 - p)^0.644``
+  knots);
+* **its rain** -- an R-CLIPER-shaped radial profile (Marks and DeMaria 2003; Tuleya et al. 2007): rain rises
+  linearly from the centre to a maximum at the radius of maximum rain, then decays exponentially, the maximum and the
+  radii growing with intensity (azimuthal-mean peaks of about 5-15 mm/h, Lonfat et al. 2004);
+* **its asymmetry** -- with vertical wind shear the rain concentrates down-shear and to the left (Chen et al. 2006),
+  a cosine weighting by the angle to the down-shear-left direction.
+
+The parametric field and the distance to the nearest storm are inputs; the network learns how much to trust them.
+The coefficients here are chosen to match published magnitudes; they are a prior, not a fitted model.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..features import _grad
+from ..util import great_circle_km
+
+
+def find_cyclones(msl: np.ndarray, u850: np.ndarray, v850: np.ndarray, lat: np.ndarray, lon: np.ndarray,
+                  p_max_hpa: float = 1006.0, vort_min: float = 4.0) -> list[list[tuple]]:
+    """Per frame, ``[(lat, lon, p_min hPa, v_max m/s), ...]`` of cyclone centres on the grid."""
+    from scipy import ndimage
+
+    vx, _ = _grad(v850, lat, lon)
+    _, uy = _grad(u850, lat, lon)
+    vort = vx - uy                                                    # 1e-5 per second
+    out = []
+    for f in range(msl.shape[0]):
+        p = msl[f] / 100.0
+        minima = (p == ndimage.minimum_filter(p, size=5, mode="nearest")) & (p < p_max_hpa)
+        found = []
+        for i, j in zip(*np.nonzero(minima)):
+            if ndimage.maximum_filter(vort[f], size=3)[i, j] < vort_min:
+                continue
+            v_kt = 6.7 * max(1010.0 - p[i, j], 0.0) ** 0.644
+            found.append((float(lat[i]), float(lon[j]), float(p[i, j]), v_kt * 0.5144))
+        out.append(found)
+    return out
+
+
+def parametric_rain(dist_km: np.ndarray, vmax: float, shear_u: float = 0.0, shear_v: float = 0.0,
+                    bearing: np.ndarray | None = None) -> np.ndarray:
+    """Rain rate (mm/h) at distances from a storm of maximum wind ``vmax`` (m/s), with shear asymmetry."""
+    u = np.clip(vmax / 33.0, 0.3, 2.5)                       # 1 = a minimal hurricane
+    t_max = 4.0 + 5.0 * u                                     # mm/h at the radius of maximum rain
+    r_m = np.clip(70.0 - 15.0 * u, 25.0, 70.0)                # km
+    r_e = 120.0 + 60.0 * u                                    # e-folding km
+    d = np.asarray(dist_km, np.float64)
+    inner = 0.3 * t_max + 0.7 * t_max * d / r_m
+    rate = np.where(d < r_m, inner, t_max * np.exp(-(d - r_m) / r_e))
+    if bearing is not None:
+        shear = np.hypot(shear_u, shear_v)
+        if shear > 1.0:
+            down = np.degrees(np.arctan2(shear_u, shear_v))           # direction the shear points to
+            left = (down - 45.0) % 360.0                              # down-shear-left
+            a = np.clip(shear / 10.0, 0, 1) * 0.6
+            rate = rate * (1 + a * np.cos(np.radians(bearing - left)))
+    return np.clip(rate, 0, 60).astype(np.float32)
+
+
+def _bearing(lat0, lon0, lat, lon):
+    la0, la = np.radians(lat0), np.radians(lat)
+    dlon = np.radians(lon - lon0)
+    x = np.sin(dlon) * np.cos(la)
+    y = np.cos(la0) * np.sin(la) - np.sin(la0) * np.cos(la) * np.cos(dlon)
+    return (np.degrees(np.arctan2(x, y)) + 360.0) % 360.0
+
+
+def cyclone_features(fields: dict, upper: dict, lat: np.ndarray, lon: np.ndarray) -> np.ndarray:
+    """``(F, 2, H, W)``: parametric storm rain (log1p mm/h) and closeness to the nearest storm (exp(-d / 300 km))."""
+    la, lo = np.meshgrid(lat, lon, indexing="ij")
+    storms = find_cyclones(fields["msl"], upper["u850"], upper["v850"], lat, lon)
+    f = fields["msl"].shape[0]
+    rain = np.zeros((f,) + la.shape, np.float32)
+    close = np.zeros((f,) + la.shape, np.float32)
+    for k, found in enumerate(storms):
+        for s_lat, s_lon, _, vmax in found:
+            d = great_circle_km(la, lo, s_lat, s_lon)
+            su = float(np.nanmean(upper["u200"][k] - upper["u850"][k]))
+            sv = float(np.nanmean(upper["v200"][k] - upper["v850"][k]))
+            rain[k] = np.maximum(rain[k], parametric_rain(d, vmax, su, sv, _bearing(s_lat, s_lon, la, lo)))
+            close[k] = np.maximum(close[k], np.exp(-d / 300.0))
+    return np.stack([np.log1p(rain), close], 1)
+
+
+__all__ = ["cyclone_features", "find_cyclones", "parametric_rain"]

pluvium/atmos/diurnal.py

@@ -0,0 +1,40 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+The daily clock of tropical rain, written down instead of learned.
+
+Global AI models are known to put the tropical daily rain maximum at the wrong hour (GraphCast concentrates it too
+close to local noon). Two physical clocks set it:
+
+* over **land**, rain follows heating: storms need several hours of sunshine to build the boundary layer, so the
+  maximum is mid to late afternoon. The integral of insolation since sunrise (normalised by its daily total) is the
+  "fuel gauge";
+* over the **sea**, rain peaks before dawn: the cloud tops cool by radiation overnight while the sea stays warm, so
+  the column destabilises at night (the nocturnal maritime maximum), strongest near 05-07 local time.
+
+Inputs per point and frame: the insolation fraction since sunrise, hours to sunset, and the two clocks weighted by
+how much land surrounds the point.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..features import cos_zenith, local_solar_hour
+
+
+def diurnal_features(lat: np.ndarray, lon: np.ndarray, hours: np.ndarray, land_fraction: np.ndarray) -> np.ndarray:
+    """``(F, N, 3)``: insolation since sunrise (0-1), the land clock and the sea clock (each -1..1, land-weighted)."""
+    hours = np.asarray(hours, np.float64)
+    lst = local_solar_hour(lon[None, :], hours[:, None])
+    # insolation since local sunrise, integrated over the preceding hours (cos zenith is clipped at night)
+    steps = np.arange(0, 13)
+    past = hours[:, None] - steps[None, :]                                                  # (F, 13)
+    cz = cos_zenith(lat[None, None, :], lon[None, None, :], past[..., None])                # (F, 13, N)
+    so_far = cz.sum(1) / 7.6                                     # about 1 by sunset in the Caribbean (sum of cos z)
+    land = np.clip(np.asarray(land_fraction, np.float64), 0, 1)[None]
+    land_clock = np.cos(2 * np.pi * (lst - 15.5) / 24.0)
+    sea_clock = np.cos(2 * np.pi * (lst - 5.5) / 24.0)
+    return np.stack([np.clip(so_far, 0, 1.5), land_clock * land, sea_clock * (1 - land)], -1).astype(np.float32)
+
+
+__all__ = ["diurnal_features"]

pluvium/atmos/moisture.py

@@ -0,0 +1,66 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+The column's water, and the most robust law of tropical rain.
+
+Over tropical oceans, rain rate rises roughly *exponentially* with column relative humidity -- the precipitable
+water divided by its saturated value (Bretherton, Peters and Back 2004: ``P = exp(a (r - b))`` with ``a = 15.6``,
+``b = 0.603``, in mm/day). A coarse driving model can put the right amount of water in the column and still rain
+in the wrong place; giving the network this law as an input lets it place rain where the column is near saturation.
+
+Also here: the vertically integrated moisture-flux convergence from the 850/700/500 hPa winds and humidities (where
+water is being imported faster than it rains out), and the precipitation efficiency the driving model implies.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .thermo import saturation_vapour_pressure
+
+G = 9.80665
+#: layer thicknesses (hPa) the three levels stand for in column integrals
+WEIGHTS = {850: 225.0, 700: 175.0, 500: 250.0}
+
+
+def saturated_q(t_k: np.ndarray, p_hpa: float) -> np.ndarray:
+    es = saturation_vapour_pressure(t_k)
+    return 0.622 * es / np.maximum(p_hpa - 0.378 * es, 1.0)
+
+
+def column_relative_humidity(t: dict, q: dict) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """``(precipitable water mm, saturated precipitable water mm, their ratio)`` from 850/700/500 hPa."""
+    pw = sum(WEIGHTS[p] * 100.0 * np.clip(q[p], 0, 0.04) for p in WEIGHTS) / G
+    pws = sum(WEIGHTS[p] * 100.0 * saturated_q(t[p], float(p)) for p in WEIGHTS) / G
+    return pw, pws, np.clip(pw / np.maximum(pws, 1e-3), 0, 1.2)
+
+
+def bretherton_rate(crh: np.ndarray) -> np.ndarray:
+    """Expected rain (mm/h) at a column relative humidity (Bretherton et al. 2004, converted from mm/day)."""
+    return np.exp(15.6 * (np.asarray(crh) - 0.603)) / 24.0
+
+
+def vimfc(u: dict, v: dict, q: dict, lat: np.ndarray, lon: np.ndarray) -> np.ndarray:
+    """Vertically integrated moisture-flux convergence (mm/day) from the three lower levels."""
+    from ..features import _grad
+
+    total = 0.0
+    for p, w in WEIGHTS.items():
+        qu, qv = q[p] * u[p], q[p] * v[p]
+        gx, _ = _grad(qu, lat, lon)
+        _, gy = _grad(qv, lat, lon)
+        total = total - (gx + gy) * 1e-5 * w * 100.0 / G             # per 100 km -> per metre; kg m-2 s-1
+    return total * 86400.0
+
+
+def moisture_channels(upper: dict, lat: np.ndarray, lon: np.ndarray) -> np.ndarray:
+    """``(F, 3, H, W)``: column relative humidity, the Bretherton rain rate (log1p), and VIMFC (normalised)."""
+    t = {p: upper[f"t{p}"] for p in WEIGHTS}
+    q = {p: upper[f"q{p}"] for p in WEIGHTS}
+    u = {p: upper[f"u{p}"] for p in WEIGHTS}
+    v = {p: upper[f"v{p}"] for p in WEIGHTS}
+    _, _, crh = column_relative_humidity(t, q)
+    conv = vimfc(u, v, q, lat, lon)
+    return np.stack([(crh - 0.7) / 0.15, np.log1p(bretherton_rate(crh)), np.clip(conv / 20.0, -5, 5)], 1).astype(np.float32)
+
+
+__all__ = ["bretherton_rate", "column_relative_humidity", "moisture_channels", "saturated_q", "vimfc"]

pluvium/atmos/saharan.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+The Saharan air layer (SAL): why a moist-looking summer forecast stays dry.
+
+From June to September, outbreaks of hot, dry, dusty air from the Sahara cross the Atlantic between about 850 and
+500 hPa (Dunion and Velden 2004). Over the Caribbean they cap the trade-wind cumulus, dry the mid-levels and come
+with a mid-level easterly jet; showers that the low-level moisture would otherwise allow do not happen. Coarse
+driving models carry the dryness but a network sees it only as one humidity among many. The index here combines the
+three signatures (mid-level dryness, warmth of the 850-700 hPa layer relative to normal, and the easterly jet at 700
+hPa), so "SAL overhead" is one clear input.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..util import calendar
+from .thermo import saturation_vapour_pressure, vapour_pressure_from_q
+
+SEASON = (5, 6, 7, 8, 9, 10)
+NORMAL_T700 = 283.5          # K, a typical Caribbean summer 700 hPa temperature
+
+
+def saharan_index(upper: dict, hours: np.ndarray) -> np.ndarray:
+    """``(F, H, W)`` in [0, 1]: 0 no SAL, 1 a strong outbreak overhead (zero outside May-October)."""
+    rh700 = vapour_pressure_from_q(upper["q700"], 700.0) / saturation_vapour_pressure(upper["t700"])
+    rh500 = vapour_pressure_from_q(upper["q500"], 500.0) / saturation_vapour_pressure(upper["t500"])
+    dry = np.clip((0.55 - 0.5 * (rh700 + rh500)) / 0.25, 0, 1)
+    warm = np.clip((upper["t700"] - NORMAL_T700) / 2.0, 0, 1)
+    jet = np.clip((-upper["u700"] - 8.0) / 6.0, 0, 1)
+    month = calendar(np.asarray(hours).astype(np.int64))["month"]
+    season = np.isin(month, SEASON).astype(np.float64)[:, None, None]
+    return (dry * (0.5 + 0.5 * warm) * (0.7 + 0.3 * jet) * season).astype(np.float32)
+
+
+__all__ = ["saharan_index"]

pluvium/atmos/sea_breeze.py

@@ -0,0 +1,50 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+The sea-breeze front: where island afternoon storms are born.
+
+On a sunny day the land heats, and by late morning cooler sea air pushes inland as a shallow gravity current. Its
+leading edge -- the sea-breeze front -- lifts the moist air ahead of it; on islands the fronts from opposite coasts
+meet inland in the afternoon, and that is where and when the storms go up. Gravity-current theory (Simpson 1994)
+gives the front's speed, ``c = k sqrt(g' h)`` with ``g' = g dtheta / theta``, ``h`` about 500 m and ``k`` about 0.6;
+the background wind adds its onshore component (an offshore wind stronger than ``c`` holds the front at the coast).
+
+For every point and frame this module gives the hours since the front passed it (negative: still to come), from
+the point's distance to the coast, the direction to the sea, the local wind, the time of day and a land-sea
+temperature contrast that grows with the sunshine since sunrise. The feature the network sees is a pulse that peaks
+as the front passes: the convergence line's moment.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..features import local_solar_hour
+
+G, H_M, K = 9.81, 500.0, 0.62
+
+
+def sea_breeze_arrival(coast_km: np.ndarray, sea_x: np.ndarray, sea_y: np.ndarray, u10: np.ndarray, v10: np.ndarray,
+                       lon: np.ndarray, hours: np.ndarray, land: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """
+    ``(pulse (F, N), hours since passage (F, N))``. ``coast_km`` (N,) distance inland (positive over land),
+    ``sea_x``/``sea_y`` (N,) unit vector towards the nearest sea, ``u10``/``v10`` (F, N), ``hours`` (F,) frame
+    hours (UTC since 1970), ``land`` (N,) bool.
+    """
+    lst = local_solar_hour(lon[None, :], np.asarray(hours, np.float64)[:, None])        # (F, N)
+    since_sunrise = np.clip(lst - 6.0, 0, 12)
+    contrast = 4.0 * np.clip(np.sin(np.pi * np.clip(lst - 6.0, 0, 12) / 12.0), 0, 1)     # K, peaks mid-afternoon
+    c = K * np.sqrt(G * np.maximum(contrast, 0.1) / 300.0 * H_M)                          # m/s
+    onshore = -(u10 * sea_x[None] + v10 * sea_y[None])                                   # wind from the sea
+    speed = np.maximum(c + onshore, 0.0)
+    onset = 3.0                                                                           # hours after sunrise
+    travelled_km = np.where(since_sunrise > onset, speed * 3.6 * (since_sunrise - onset), 0.0)
+    dist = np.maximum(np.asarray(coast_km, np.float64), 0.0)[None]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        passed_h = np.where(speed > 0.3, (travelled_km - dist) / np.maximum(speed * 3.6, 1e-6), -12.0)
+    held = c + onshore < 0.3                                                             # pinned at the coast
+    passed_h = np.where(held | ~land[None] | (lst < 6) | (lst > 19), -12.0, np.clip(passed_h, -12, 12))
+    pulse = np.exp(-0.5 * (passed_h / 1.5) ** 2) * (contrast > 1.0)
+    return pulse.astype(np.float32), passed_h.astype(np.float32)
+
+
+__all__ = ["sea_breeze_arrival"]

pluvium/atmos/thermo.py

@@ -0,0 +1,128 @@
+# Copyright 2026 Nathan. Apache-2.0.
+"""
+Moist thermodynamics, done properly.
+
+Version 2 used the textbook shortcut ``theta-e = (T + L q / c_p)(1000/p)^0.286`` and a lifted index from 850 hPa.
+Tropical convection lives in differences of a few kelvin, where the shortcut's error (1-3 K) is as large as the
+signal. Here:
+
+* saturation vapour pressure over water (Bolton 1980, eq. 10), mixing ratio, virtual temperature;
+* equivalent potential temperature by Bolton's eq. 39 (accurate to about 0.02 K);
+* the lifting condensation level by Bolton's eq. 21;
+* a pseudo-adiabatic parcel ascent integrated in log-pressure, and the convective available potential energy and
+  convective inhibition of a parcel lifted from 850 hPa through the 850/700/500/200 hPa profile (log-pressure
+  interpolation of the environment). Four levels cannot resolve every inversion; the numbers are indices of the
+  column's readiness, not soundings, and are clipped to physically sensible ranges.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+RD, RV, CP, G, LV = 287.04, 461.5, 1005.7, 9.80665, 2.501e6
+EPS = RD / RV
+LEVELS = (850.0, 700.0, 500.0, 200.0)
+
+
+def saturation_vapour_pressure(t_k: np.ndarray) -> np.ndarray:
+    """hPa, over liquid water (Bolton 1980, eq. 10)."""
+    tc = np.asarray(t_k, np.float64) - 273.15
+    return 6.112 * np.exp(17.67 * tc / (tc + 243.5))
+
+
+def mixing_ratio(e_hpa: np.ndarray, p_hpa) -> np.ndarray:
+    return EPS * e_hpa / np.maximum(np.asarray(p_hpa, np.float64) - e_hpa, 1e-3)
+
+
+def vapour_pressure_from_q(q: np.ndarray, p_hpa) -> np.ndarray:
+    q = np.clip(np.asarray(q, np.float64), 1e-7, 0.05)
+    return q * p_hpa / (EPS + (1 - EPS) * q)
+
+
+def dewpoint_k(e_hpa: np.ndarray) -> np.ndarray:
+    x = np.log(np.maximum(e_hpa, 1e-4) / 6.112)
+    return 243.5 * x / (17.67 - x) + 273.15
+
+
+def lcl(t_k: np.ndarray, td_k: np.ndarray) -> np.ndarray:
+    """Temperature (K) at the lifting condensation level (Bolton 1980, eq. 15)."""
+    t, td = np.asarray(t_k, np.float64), np.asarray(td_k, np.float64)
+    return 1.0 / (1.0 / (td - 56.0) + np.log(t / td) / 800.0) + 56.0
+
+
+def theta_e_bolton(t_k: np.ndarray, q: np.ndarray, p_hpa) -> np.ndarray:
+    """Equivalent potential temperature (K), Bolton 1980 eq. 39."""
+    t = np.asarray(t_k, np.float64)
+    e = vapour_pressure_from_q(q, p_hpa)
+    r = mixing_ratio(e, p_hpa)                                       # kg/kg
+    tl = lcl(t, dewpoint_k(e))
+    theta_l = t * (1000.0 / (p_hpa - e)) ** 0.2854 * (t / tl) ** (0.28e-3 * r * 1000.0)
+    return theta_l * np.exp((3.036 / tl - 0.00178) * r * 1000.0 * (1 + 0.448e-3 * r * 1000.0))
+
+
+def _moist_lapse(t: np.ndarray, p_hpa: np.ndarray) -> np.ndarray:
+    """dT/dlnp of a saturated parcel (pseudo-adiabatic), K per unit ln p."""
+    es = saturation_vapour_pressure(t)
+    rs = mixing_ratio(es, p_hpa)
+    num = (RD * t + LV * rs) / (CP + (LV**2 * rs * EPS) / (RD * t**2))
+    return num
+
+
+def parcel_profile(t0: np.ndarray, q0: np.ndarray, p0: float, levels) -> np.ndarray:
+    """Temperatures of a parcel lifted from ``p0`` (dry to its LCL, then moist), at ``levels`` (hPa, decreasing)."""
+    t0 = np.asarray(t0, np.float64)
+    e0 = vapour_pressure_from_q(q0, p0)
+    t_lcl = lcl(t0, dewpoint_k(e0))
+    p_lcl = p0 * (t_lcl / t0) ** (1 / 0.2854)
+    out = []
+    for p in levels:
+        dry = t0 * (p / p0) ** 0.2854
+        # moist ascent from the LCL to p in log-pressure steps
+        t = t_lcl.copy()
+        lp0, lp1 = np.log(np.minimum(p_lcl, p0)), np.log(p)
+        n = 12
+        for k in range(n):
+            lp = lp0 + (lp1 - lp0) * (k + 0.5) / n
+            t = t + _moist_lapse(t, np.exp(lp)) * (lp1 - lp0) / n
+        out.append(np.where(p >= p_lcl, dry, t))
+    return np.stack(out)
+
+
+def cape_cin(t: dict, q: dict, origin: float = 850.0) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    CAPE and CIN (J/kg) of a parcel from ``origin`` through the profile, and the LCL height (m), from temperatures
+    ``t[p]`` and specific humidities ``q[p]`` at 850/700/500/200 hPa (arrays of any shape). The integral is a
+    trapezoid in ln p on a 16-level grid between 850 and 200 hPa (environment interpolated linearly in ln p).
+    """
+    grid = np.exp(np.linspace(np.log(origin), np.log(200.0), 16))
+    lev = np.log(np.array(LEVELS))
+    env_t = np.stack([t[int(p)] for p in LEVELS]).astype(np.float64)
+    env_q = np.stack([q[int(p)] for p in LEVELS]).astype(np.float64)
+
+    def interp(field, lp):
+        k = np.clip(np.searchsorted(-lev, -lp) - 1, 0, len(LEVELS) - 2)
+        w = (lp - lev[k]) / (lev[k + 1] - lev[k])
+        return field[k] * (1 - w) + field[k + 1] * w
+
+    parcel = parcel_profile(t[int(origin)], q[int(origin)], origin, grid)
+    env = np.stack([interp(env_t, np.log(p)) for p in grid])
+    envq = np.stack([interp(env_q, np.log(p)) for p in grid])
+    tv_env = env * (1 + 0.61 * envq)
+    es = saturation_vapour_pressure(parcel)
+    qs = EPS * es / np.maximum(grid.reshape((-1,) + (1,) * (parcel.ndim - 1)) - (1 - EPS) * es, 1e-3)
+    tv_par = parcel * (1 + 0.61 * np.minimum(qs, q[int(origin)]))
+    buoy = RD * (tv_par - tv_env) / tv_env * tv_env                 # R_d (Tv_p - Tv_e)
+    dlnp = -np.diff(np.log(grid))
+    seg = 0.5 * (buoy[1:] + buoy[:-1]) * dlnp.reshape((-1,) + (1,) * (buoy.ndim - 1))
+    cape = np.clip(np.where(seg > 0, seg, 0).sum(0), 0, 6000)
+    # CIN: negative area below the first positive layer
+    positive = np.cumsum(seg > 0, axis=0) > 0
+    cin = np.clip(np.where((seg < 0) & ~positive, seg, 0).sum(0), -500, 0)
+    e0 = vapour_pressure_from_q(q[int(origin)], origin)
+    t_lcl = lcl(t[int(origin)], dewpoint_k(e0))
+    lcl_m = np.clip((t[int(origin)] - t_lcl) / 0.0098, 0, 4000)      # dry adiabatic metres above the origin level
+    return cape.astype(np.float32), cin.astype(np.float32), lcl_m.astype(np.float32)
+
+
+__all__ = ["cape_cin", "dewpoint_k", "lcl", "mixing_ratio", "parcel_profile", "saturation_vapour_pressure",
+           "theta_e_bolton", "vapour_pressure_from_q"]