Initial deploy: real-time weather forecast demo

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,14 +1,46 @@
 ---
-title: Weather Predict
-emoji: 🏢
-colorFrom: gray
-colorTo: red
+title: Tufts Jumbo Weather Forecast
+emoji: "\U0001F324"
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.11.0
+sdk_version: "4.44.1"
 app_file: app.py
 pinned: false
 license: mit
-short_description: A real time weather prediction system with CNN based model.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Tufts Jumbo — 24h Weather Forecast
+
+Real-time deep-learning weather prediction for the Jumbo Statue at Tufts University.
+
+## How It Works
+
+1. **Fetches** the latest HRRR 3 km analysis data from NOAA (42 atmospheric channels, 450x449 grid covering the US Northeast)
+2. **Runs** a trained CNN through the spatial snapshot
+3. **Predicts** 6 weather variables 24 hours ahead at a single target point (Jumbo Statue, Medford MA)
+
+## Models
+
+| Model | Parameters | Architecture |
+|-------|-----------|-------------|
+| CNN Baseline | 11.3M | 6 residual blocks, progressive spatial downsampling |
+| ResNet-18 | 11.2M | Modified torchvision ResNet-18 (42-channel input) |
+
+## Input Channels (42)
+
+Surface: 2m temperature, 2m humidity, 10m U/V wind, surface gust, solar radiation, 1hr precipitation.
+Atmospheric: CAPE, dew point (5 levels), geopotential height (5 levels), temperature (5 levels),
+U-wind (6 levels), V-wind (6 levels), cloud cover (4 layers), precipitable water, relative humidity, VIL.
+
+## Output Variables
+
+Temperature (K), Relative Humidity (%), U-Wind (m/s), V-Wind (m/s), Wind Gust (m/s), Precipitation (mm).
+
+## Data Source
+
+[HRRR (High-Resolution Rapid Refresh)](https://rapidrefresh.noaa.gov/hrrr/) — NOAA's 3 km hourly weather model, fetched in real-time from AWS S3 via [Herbie](https://herbie.readthedocs.io/).
+
+## Course
+
+Tufts CS 137 — Deep Neural Networks, Spring 2026

app.py

@@ -0,0 +1,356 @@
+"""
+Tufts Jumbo Weather Forecast — Deep Learning Demo
+
+Usage:
+    cd demo && python app.py
+"""
+
+import logging
+from datetime import timedelta
+
+import gradio as gr
+
+from hrrr_fetch import fetch_hrrr_input
+from model_utils import run_forecast, load_model, AVAILABLE_MODELS
+from visualization import (
+    get_static_maps,
+    plot_temperature,
+    plot_temperature_placeholder,
+)
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ── CSS ───────────────────────────────────────────────────────────────
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');
+
+:root {
+    --font: -apple-system, BlinkMacSystemFont, "SF Pro Display",
+            "SF Pro Text", Inter, "Helvetica Neue", Arial, sans-serif;
+    --bg: #F2F2F7;
+    --card: #FFFFFF;
+    --border: #E5E5EA;
+    --text: #1D1D1F;
+    --muted: #86868B;
+    --accent: #0A84FF;
+    --dark: #1C1C1E;
+}
+* { font-family: var(--font) !important; }
+
+.gradio-container {
+    max-width: 1320px !important;
+    margin: 0 auto !important;
+    background: var(--bg) !important;
+    padding-bottom: 24px !important;
+}
+
+/* ── Top bar ── */
+.top-bar {
+    background: linear-gradient(135deg, #1C1C1E 0%, #2C2C2E 100%);
+    border-radius: 16px;
+    padding: 28px 36px;
+    margin-bottom: 16px;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+.top-bar .title {
+    font-size: 24px; font-weight: 700;
+    color: #F5F5F7; letter-spacing: -0.3px;
+}
+.top-bar .subtitle {
+    font-size: 13px; color: #98989D;
+    margin-top: 2px;
+}
+.top-bar .location {
+    text-align: right;
+    font-size: 13px; color: #98989D;
+    line-height: 1.6;
+}
+.top-bar .location b {
+    color: #F5F5F7; font-weight: 600;
+}
+
+/* ── Hero card ── */
+.hero-card {
+    background: var(--card);
+    border-radius: 16px;
+    border: 1px solid var(--border);
+    box-shadow: 0 2px 8px rgba(0,0,0,0.04);
+    padding: 32px 36px 28px;
+    margin-bottom: 16px;
+}
+.hero-main {
+    display: flex;
+    align-items: baseline;
+    gap: 20px;
+    margin-bottom: 4px;
+}
+.hero-temp {
+    font-size: 64px; font-weight: 300;
+    color: var(--text); letter-spacing: -2px;
+    line-height: 1;
+}
+.hero-temp-unit {
+    font-size: 28px; font-weight: 400;
+    color: var(--muted); margin-left: 2px;
+}
+.hero-status {
+    font-size: 20px; font-weight: 500;
+    color: var(--text); padding-left: 8px;
+    border-left: 3px solid var(--accent);
+}
+.hero-metrics {
+    display: flex;
+    gap: 12px;
+    margin: 20px 0 18px;
+}
+.metric-tile {
+    flex: 1;
+    background: var(--bg);
+    border-radius: 12px;
+    padding: 14px 16px;
+    text-align: center;
+}
+.metric-value {
+    font-size: 22px; font-weight: 600;
+    color: var(--text); line-height: 1.2;
+}
+.metric-label {
+    font-size: 12px; font-weight: 500;
+    color: var(--muted);
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    margin-top: 4px;
+}
+.hero-meta {
+    font-size: 13px; color: var(--muted);
+    line-height: 1.6;
+}
+.hero-meta code {
+    background: var(--bg); padding: 2px 6px;
+    border-radius: 4px; font-size: 12px;
+}
+.hero-placeholder {
+    text-align: center;
+    padding: 36px 0;
+    color: var(--muted);
+    font-size: 16px; font-weight: 500;
+}
+
+/* ── Map section ── */
+.maps-heading {
+    font-size: 11px; font-weight: 600;
+    text-transform: uppercase; letter-spacing: 0.8px;
+    color: var(--muted);
+    margin: 8px 0 8px 4px;
+}
+
+.map-cell {
+    background: var(--card) !important;
+    border-radius: 14px !important;
+    border: 1px solid var(--border) !important;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.04) !important;
+    overflow: hidden !important;
+    min-height: 380px !important;
+}
+
+/* ── Controls inside hero ── */
+.controls-row {
+    display: flex; align-items: end; gap: 10px;
+    margin-top: 18px; padding-top: 16px;
+    border-top: 1px solid var(--border);
+}
+
+/* ── Status ── */
+.status-text p, .status-text em {
+    font-size: 12px !important; color: var(--muted) !important;
+}
+
+/* ── About ── */
+.about-section {
+    font-size: 13px !important; color: #6E6E73 !important;
+    line-height: 1.65 !important;
+}
+
+/* ── Button ── */
+button.primary {
+    background: var(--accent) !important;
+    border: none !important; border-radius: 10px !important;
+    font-weight: 600 !important; font-size: 15px !important;
+    padding: 10px 28px !important;
+}
+button.primary:hover { background: #0A74E0 !important; }
+"""
+
+# ── Helpers ────────────────────────────────────────────────────────────
+
+model_choices = [
+    f"{v['display_name']}  ({v['params']})" for v in AVAILABLE_MODELS.values()
+]
+model_keys = list(AVAILABLE_MODELS.keys())
+
+
+def _resolve_model(display: str) -> str:
+    return model_keys[model_choices.index(display)]
+
+
+def _hero_placeholder() -> str:
+    return (
+        '<div class="hero-card">'
+        '<div class="hero-placeholder">'
+        "Click <b>Run Forecast</b> to fetch real-time HRRR data and generate a 24-hour prediction."
+        "</div></div>"
+    )
+
+
+def _hero_html(r: dict, cycle_str: str, forecast_str: str, model_label: str) -> str:
+    return (
+        '<div class="hero-card">'
+        #  temperature + status
+        '<div class="hero-main">'
+        f'<div><span class="hero-temp">{r["temperature_c"]:.1f}</span>'
+        f'<span class="hero-temp-unit">°C</span></div>'
+        f'<div class="hero-status">{r["rain_status"]}</div>'
+        "</div>"
+        #  metric tiles
+        '<div class="hero-metrics">'
+        f'<div class="metric-tile"><div class="metric-value">{r["temperature_f"]:.0f}°F</div>'
+        '<div class="metric-label">Temperature</div></div>'
+        f'<div class="metric-tile"><div class="metric-value">{r["humidity_pct"]:.0f}%</div>'
+        '<div class="metric-label">Humidity</div></div>'
+        f'<div class="metric-tile"><div class="metric-value">{r["wind_speed_ms"]:.1f}</div>'
+        f'<div class="metric-label">Wind m/s {r["wind_dir_str"]}</div></div>'
+        f'<div class="metric-tile"><div class="metric-value">{r["gust_ms"]:.1f}</div>'
+        '<div class="metric-label">Gust m/s</div></div>'
+        f'<div class="metric-tile"><div class="metric-value">{r["precipitation_mm"]:.2f}</div>'
+        '<div class="metric-label">Precip mm</div></div>'
+        "</div>"
+        #  meta line
+        '<div class="hero-meta">'
+        f"Based on &ensp;<code>{cycle_str}</code> &ensp; "
+        f"Forecast valid &ensp;<b>{forecast_str}</b> &ensp; "
+        f"Model &ensp;<b>{model_label}</b>"
+        "</div>"
+        "</div>"
+    )
+
+
+# ── Main callback ──────────────────────────────────────────────────────
+
+def do_forecast(model_display: str, progress=gr.Progress()):
+    model_name = _resolve_model(model_display)
+
+    progress(0.02, desc="Finding latest HRRR cycle...")
+    try:
+        input_array, cycle_time = fetch_hrrr_input(
+            progress_callback=lambda f, m: progress(f, desc=m),
+        )
+    except Exception as e:
+        raise gr.Error(f"HRRR fetch failed: {e}")
+
+    cycle_str = cycle_time.strftime("%Y-%m-%d %H:%M UTC")
+    forecast_time = cycle_time + timedelta(hours=24)
+    forecast_str = forecast_time.strftime("%Y-%m-%d %H:%M UTC")
+
+    progress(0.95, desc="Running model inference...")
+    try:
+        r = run_forecast(model_name, input_array)
+    except Exception as e:
+        raise gr.Error(f"Inference failed: {e}")
+
+    model_label = model_display.split("(")[0].strip()
+    hero = _hero_html(r, cycle_str, forecast_str, model_label)
+    temp_fig = plot_temperature(input_array, r, cycle_str, forecast_str)
+    status = f"Forecast complete — HRRR cycle {cycle_str}"
+
+    return hero, temp_fig, status
+
+
+# ── Build UI ──────────────────────────────────────────────────────────
+
+# Pre-render static maps at import time
+logger.info("Rendering static basemaps...")
+_sat_fig, _street_fig = get_static_maps()
+_temp_placeholder = plot_temperature_placeholder()
+logger.info("Basemaps ready.")
+
+with gr.Blocks(title="Tufts Jumbo Weather Forecast") as demo:
+
+    # ── Top bar ───────────────────────────────────────────────────
+    gr.HTML(
+        '<div class="top-bar">'
+        '<div>'
+        '<div class="title">Tufts Jumbo Weather</div>'
+        '<div class="subtitle">Real-time deep-learning forecast</div>'
+        "</div>"
+        '<div class="location">'
+        "<b>Medford, MA</b><br>"
+        "42.41°N &ensp; 71.12°W"
+        "</div>"
+        "</div>"
+    )
+
+    # ── Hero card ─────────────────────────────────────────────────
+    hero_html = gr.HTML(_hero_placeholder())
+
+    # ── Controls ──────────────────────────────────────────────────
+    with gr.Row(elem_classes=["controls-row"]):
+        model_dd = gr.Dropdown(
+            choices=model_choices, value=model_choices[0],
+            label="Model", scale=3,
+        )
+        run_btn = gr.Button("Run Forecast", variant="primary", scale=1)
+
+    status_bar = gr.Markdown(
+        "_Ready — click **Run Forecast**._",
+        elem_classes=["status-text"],
+    )
+
+    # ── Maps ──────────────────────────────────────────────────────
+    gr.HTML('<div class="maps-heading">Coverage Maps — 1 350 km × 1 350 km &ensp; 3 km resolution</div>')
+
+    with gr.Row(equal_height=True):
+        sat_plot = gr.Plot(
+            value=_sat_fig, label="Satellite",
+            elem_classes=["map-cell"],
+        )
+        street_plot = gr.Plot(
+            value=_street_fig, label="Reference Map",
+            elem_classes=["map-cell"],
+        )
+        temp_plot = gr.Plot(
+            value=_temp_placeholder, label="Temperature",
+            elem_classes=["map-cell"],
+        )
+
+    # ── About ─────────────────────────────────────────────────────
+    with gr.Accordion("About this demo", open=False):
+        gr.Markdown(
+            "**Data** &ensp; HRRR 3 km analysis from NOAA (AWS S3, via Herbie). "
+            "42 atmospheric channels covering the US Northeast.\n\n"
+            "**Models** &ensp; CNN Baseline (11.3 M params) · ResNet-18 (11.2 M params) — "
+            "predict 6 weather variables 24 h ahead for a single target point.\n\n"
+            "**Course** &ensp; Tufts CS 137 — Deep Neural Networks, Spring 2026",
+            elem_classes=["about-section"],
+        )
+
+    # ── Callbacks ─────────────────────────────────────────────────
+    run_btn.click(
+        fn=do_forecast,
+        inputs=[model_dd],
+        outputs=[hero_html, temp_plot, status_bar],
+    )
+
+
+if __name__ == "__main__":
+    logger.info("Pre-loading default model...")
+    try:
+        load_model(model_keys[0])
+        logger.info("Model loaded.")
+    except Exception as e:
+        logger.warning(f"Pre-load failed: {e}")
+
+    demo.launch(share=False, css=CUSTOM_CSS)

checkpoints/cnn_baseline.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9978778103ca02974eec82bd676a58639b0e13fa893656bd622153a44ec68603
+size 45379961

checkpoints/resnet18.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9d74d4559da02319248276d3d616cda17766f422350dfce61de041c03b9cfff0
+size 45288199

hrrr_fetch.py

@@ -0,0 +1,142 @@
+"""
+Fetch real-time HRRR analysis data from NOAA AWS S3 via Herbie.
+
+Downloads 42 individual GRIB2 messages (one per input channel),
+extracts the New England subgrid (450x449), and stacks them into
+the model's expected input format.
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+import numpy as np
+
+from var_mapping import HRRR_MAPPING, NE_Y_SLICE, NE_X_SLICE
+
+logger = logging.getLogger(__name__)
+
+
+def find_latest_hrrr_cycle(max_lookback_hours: int = 6) -> datetime:
+    """
+    Find the most recent HRRR cycle that is available on AWS S3.
+    HRRR data typically becomes available ~45-90 minutes after valid time.
+
+    Returns a tz-naive datetime in UTC (Herbie requirement).
+    """
+    from herbie import Herbie
+
+    now = datetime.now(timezone.utc).replace(tzinfo=None)  # tz-naive UTC
+    for hours_ago in range(2, max_lookback_hours + 1):
+        cycle_time = (now - timedelta(hours=hours_ago)).replace(
+            minute=0, second=0, microsecond=0
+        )
+        try:
+            H = Herbie(
+                cycle_time,
+                model="hrrr",
+                product="sfc",
+                fxx=0,
+                verbose=False,
+            )
+            # Check if the index file exists (fast check without downloading data)
+            if H.idx is not None:
+                logger.info(f"Found HRRR cycle: {cycle_time:%Y-%m-%d %H:%M UTC}")
+                return cycle_time
+        except Exception:
+            continue
+
+    raise RuntimeError(
+        f"No HRRR data available in the last {max_lookback_hours} hours. "
+        "NOAA servers may be temporarily unavailable."
+    )
+
+
+def _fetch_single_variable(cycle_time: datetime, mapping: dict) -> np.ndarray:
+    """
+    Fetch one variable from HRRR and extract the NE subgrid.
+
+    Returns:
+        np.ndarray of shape (450, 449)
+    """
+    from herbie import Herbie
+
+    H = Herbie(
+        cycle_time,
+        model="hrrr",
+        product=mapping["product"],
+        fxx=mapping["fxx"],
+        verbose=False,
+    )
+
+    ds = H.xarray(mapping["search"], remove_grib=True)
+
+    # xarray dataset may have different variable names depending on the GRIB message.
+    # Get the first data variable (excluding coordinates).
+    data_vars = [v for v in ds.data_vars if v not in ("latitude", "longitude", "gribfile_projection")]
+    if not data_vars:
+        raise ValueError(f"No data variable found for {mapping['name']}")
+
+    field = ds[data_vars[0]].values  # Full CONUS grid
+
+    # Extract NE subgrid
+    subgrid = field[NE_Y_SLICE, NE_X_SLICE]
+
+    if subgrid.shape != (450, 449):
+        raise ValueError(
+            f"Unexpected shape {subgrid.shape} for {mapping['name']}, expected (450, 449)"
+        )
+
+    return subgrid.astype(np.float32)
+
+
+def fetch_hrrr_input(
+    cycle_time: datetime = None,
+    progress_callback=None,
+) -> tuple[np.ndarray, datetime]:
+    """
+    Fetch all 42 HRRR channels and stack into model input format.
+
+    Args:
+        cycle_time: Specific HRRR cycle to fetch. If None, finds the latest.
+        progress_callback: Optional callable(fraction, description) for progress updates.
+
+    Returns:
+        (input_array, cycle_time) where input_array is (450, 449, 42) float32.
+    """
+    if cycle_time is None:
+        if progress_callback:
+            progress_callback(0.05, "Finding latest HRRR cycle...")
+        cycle_time = find_latest_hrrr_cycle()
+
+    channels = []
+    n_channels = len(HRRR_MAPPING)
+    failed = []
+
+    for i, mapping in enumerate(HRRR_MAPPING):
+        if progress_callback:
+            frac = 0.1 + 0.85 * (i / n_channels)
+            progress_callback(frac, f"Fetching {mapping['name']} ({i+1}/{n_channels})...")
+
+        try:
+            field = _fetch_single_variable(cycle_time, mapping)
+            channels.append(field)
+        except Exception as e:
+            logger.warning(f"Failed to fetch {mapping['name']}: {e}")
+            failed.append(mapping["name"])
+            # Fill with zeros as fallback for individual missing channels
+            channels.append(np.zeros((450, 449), dtype=np.float32))
+
+    if failed:
+        logger.warning(f"Failed channels ({len(failed)}/{n_channels}): {failed}")
+        if len(failed) > n_channels // 2:
+            raise RuntimeError(
+                f"Too many channels failed ({len(failed)}/{n_channels}). "
+                "HRRR data may be unavailable."
+            )
+
+    input_array = np.stack(channels, axis=-1)  # (450, 449, 42)
+
+    if progress_callback:
+        progress_callback(1.0, "Data fetch complete!")
+
+    return input_array, cycle_time

model_utils.py

@@ -0,0 +1,180 @@
+"""
+Model loading and inference utilities for the weather forecast demo.
+
+Wraps the existing inference/predict.py logic, adding user-friendly
+post-processing (Celsius, wind speed/direction, rain likelihood).
+"""
+
+import math
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+
+# In HF Space, models/ is in the same directory as this file
+PROJECT_ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from models import create_model, get_model_defaults
+
+# ── Model cache (loaded once, reused across requests) ──────────────────
+_model_cache: dict = {}
+
+
+TARGET_VARS = [
+    ("TMP@2m_above_ground",       "Temperature (2m)",    "K"),
+    ("RH@2m_above_ground",        "Relative Humidity",   "%"),
+    ("UGRD@10m_above_ground",     "U-Wind (10m)",        "m/s"),
+    ("VGRD@10m_above_ground",     "V-Wind (10m)",        "m/s"),
+    ("GUST@surface",              "Wind Gust",           "m/s"),
+    ("APCP_1hr_acc_fcst@surface", "Precipitation (1hr)", "mm"),
+]
+
+# Available models with display info
+AVAILABLE_MODELS = {
+    "cnn_baseline": {
+        "display_name": "CNN Baseline",
+        "checkpoint": "checkpoints/cnn_baseline.pt",
+        "params": "11.3M",
+    },
+    "resnet18": {
+        "display_name": "ResNet-18",
+        "checkpoint": "checkpoints/resnet18.pt",
+        "params": "11.2M",
+    },
+}
+
+
+def load_model(model_name: str, device: str = "cpu"):
+    """
+    Load a trained model from checkpoint. Caches in memory for reuse.
+
+    Returns:
+        (model, norm_stats) tuple
+    """
+    if model_name in _model_cache:
+        return _model_cache[model_name]
+
+    ckpt_path = PROJECT_ROOT / AVAILABLE_MODELS[model_name]["checkpoint"]
+    if not ckpt_path.exists():
+        raise FileNotFoundError(f"Checkpoint not found: {ckpt_path}")
+
+    ckpt = torch.load(ckpt_path, map_location=device, weights_only=False)
+    args = ckpt["args"]
+    ckpt_model_name = args["model"]
+
+    defaults = get_model_defaults(ckpt_model_name)
+    n_frames = args.get("n_frames") or defaults["n_frames"]
+
+    model_kwargs = {
+        "n_input_channels": 42,
+        "n_targets": 6,
+        "base_channels": args.get("base_channels", 64),
+    }
+    if n_frames > 1:
+        model_kwargs["n_frames"] = n_frames
+
+    model = create_model(ckpt_model_name, **model_kwargs)
+    model.load_state_dict(ckpt["model"])
+    model.to(device).eval()
+
+    norm_stats = ckpt.get("norm_stats")
+
+    _model_cache[model_name] = (model, norm_stats)
+    return model, norm_stats
+
+
+def predict_raw(model, norm_stats, input_array: np.ndarray, device: str = "cpu") -> np.ndarray:
+    """
+    Run inference on a (450, 449, 42) input array.
+
+    Returns:
+        np.ndarray of shape (6,) with denormalized physical values.
+    """
+    x = torch.from_numpy(input_array).float()
+    x = x.permute(2, 0, 1).unsqueeze(0)  # (1, 42, 450, 449)
+
+    if norm_stats:
+        mean = norm_stats["input_mean"]
+        std = norm_stats["input_std"]
+        # Ensure correct device
+        if isinstance(mean, torch.Tensor):
+            mean = mean.float()
+            std = std.float()
+        x = (x - mean) / (std + 1e-7)
+
+    x = x.to(device)
+    with torch.no_grad():
+        pred = model(x).squeeze(0).cpu()  # (6,)
+
+    if norm_stats:
+        target_mean = norm_stats["target_mean"]
+        target_std = norm_stats["target_std"]
+        if isinstance(target_mean, torch.Tensor):
+            target_mean = target_mean.float()
+            target_std = target_std.float()
+        pred = pred * target_std + target_mean
+
+    return pred.numpy()
+
+
+def _wind_direction_str(degrees: float) -> str:
+    """Convert wind direction in degrees to compass string."""
+    dirs = ["N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE",
+            "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"]
+    idx = round(degrees / 22.5) % 16
+    return dirs[idx]
+
+
+def format_forecast(pred: np.ndarray) -> dict:
+    """
+    Convert raw model output (6 physical values) into a user-friendly forecast dict.
+    """
+    temp_k = float(pred[0])
+    rh = float(pred[1])
+    u_wind = float(pred[2])
+    v_wind = float(pred[3])
+    gust = float(pred[4])
+    apcp = float(pred[5])
+
+    # Derived quantities
+    temp_c = temp_k - 273.15
+    temp_f = temp_c * 9 / 5 + 32
+    wind_speed = math.sqrt(u_wind**2 + v_wind**2)
+    # Meteorological wind direction: direction FROM which wind blows
+    wind_dir_deg = (math.degrees(math.atan2(-u_wind, -v_wind)) + 360) % 360
+    wind_dir_str = _wind_direction_str(wind_dir_deg)
+
+    # Rain likelihood based on APCP threshold
+    apcp = max(apcp, 0.0)  # Clamp negative predictions
+    if apcp > 5.0:
+        rain_str = "Heavy Rain Likely"
+    elif apcp > 2.0:
+        rain_str = "Rain Likely"
+    elif apcp > 0.5:
+        rain_str = "Light Rain Possible"
+    else:
+        rain_str = "No Rain Expected"
+
+    return {
+        "temperature_k": temp_k,
+        "temperature_c": temp_c,
+        "temperature_f": temp_f,
+        "humidity_pct": max(0.0, min(100.0, rh)),
+        "u_wind_ms": u_wind,
+        "v_wind_ms": v_wind,
+        "wind_speed_ms": wind_speed,
+        "wind_dir_deg": wind_dir_deg,
+        "wind_dir_str": wind_dir_str,
+        "gust_ms": max(gust, 0.0),
+        "precipitation_mm": apcp,
+        "rain_status": rain_str,
+    }
+
+
+def run_forecast(model_name: str, input_array: np.ndarray, device: str = "cpu") -> dict:
+    """Full pipeline: load model → predict → format results."""
+    model, norm_stats = load_model(model_name, device)
+    pred = predict_raw(model, norm_stats, input_array, device)
+    return format_forecast(pred)

models/__init__.py

@@ -0,0 +1,45 @@
+"""
+Model registry for weather forecasting architectures.
+
+Usage:
+    from models import create_model, MODEL_REGISTRY
+    model = create_model("cnn_baseline", n_input_channels=42)
+"""
+
+from .cnn_baseline import BaselineCNN
+from .cnn_multi_frame import MultiFrameCNN
+from .cnn_3d import CNN3D
+from .vit import WeatherViT
+from .resnet_baseline import ResNet18Baseline
+from .convnext_baseline import ConvNeXtBaseline
+
+MODEL_REGISTRY = {
+    "cnn_baseline": BaselineCNN,
+    "cnn_multi_frame": MultiFrameCNN,
+    "cnn_3d": CNN3D,
+    "vit": WeatherViT,
+    "resnet18": ResNet18Baseline,
+    "convnext_tiny": ConvNeXtBaseline,
+}
+
+# Default model-specific settings
+MODEL_DEFAULTS = {
+    "cnn_baseline": {"n_frames": 1, "stack_mode": "channel"},
+    "cnn_multi_frame": {"n_frames": 4, "stack_mode": "channel"},
+    "cnn_3d": {"n_frames": 4, "stack_mode": "temporal"},
+    "vit": {"n_frames": 1, "stack_mode": "channel"},
+    "resnet18": {"n_frames": 1, "stack_mode": "channel"},
+    "convnext_tiny": {"n_frames": 1, "stack_mode": "channel"},
+}
+
+
+def create_model(name, **kwargs):
+    """Instantiate a model by name with given kwargs."""
+    if name not in MODEL_REGISTRY:
+        raise ValueError(f"Unknown model: {name}. Available: {list(MODEL_REGISTRY.keys())}")
+    return MODEL_REGISTRY[name](**kwargs)
+
+
+def get_model_defaults(name):
+    """Return default n_frames and stack_mode for a model."""
+    return MODEL_DEFAULTS.get(name, {"n_frames": 1, "stack_mode": "channel"})

models/cnn_3d.py

@@ -0,0 +1,99 @@
+"""
+3D CNN for spatiotemporal weather forecasting.
+
+Uses Conv3d to jointly model spatial and temporal patterns
+from multiple consecutive weather snapshots.
+
+Input:  (B, k, C, H, W) — k frames, each with C channels
+Output: (B, 6)
+"""
+
+import torch
+import torch.nn as nn
+
+
+class ResBlock3D(nn.Module):
+    """3D residual block with separate temporal and spatial convolutions."""
+
+    def __init__(self, in_ch, out_ch, stride_spatial=1, stride_temporal=1):
+        super().__init__()
+        stride = (stride_temporal, stride_spatial, stride_spatial)
+
+        self.conv1 = nn.Conv3d(in_ch, out_ch, 3, stride=stride, padding=1, bias=False)
+        self.bn1 = nn.BatchNorm3d(out_ch)
+        self.conv2 = nn.Conv3d(out_ch, out_ch, 3, stride=1, padding=1, bias=False)
+        self.bn2 = nn.BatchNorm3d(out_ch)
+        self.relu = nn.ReLU(inplace=True)
+
+        self.shortcut = nn.Identity()
+        if any(s != 1 for s in stride) or in_ch != out_ch:
+            self.shortcut = nn.Sequential(
+                nn.Conv3d(in_ch, out_ch, 1, stride=stride, bias=False),
+                nn.BatchNorm3d(out_ch),
+            )
+
+    def forward(self, x):
+        out = self.relu(self.bn1(self.conv1(x)))
+        out = self.bn2(self.conv2(out))
+        out = self.relu(out + self.shortcut(x))
+        return out
+
+
+class CNN3D(nn.Module):
+    """
+    3D CNN for spatiotemporal weather forecasting.
+
+    Input:  (B, k, C, H, W) where k=n_frames, C=n_input_channels
+    Output: (B, 6)
+
+    The temporal dimension is collapsed early (by stride-2 temporal convolutions
+    and pooling), while spatial dimensions are progressively downsampled.
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, n_frames=4, base_channels=64):
+        super().__init__()
+        ch = base_channels
+
+        # (B, k, C, H, W) -> (B, C, k, H, W) is done in forward()
+        self.stem = nn.Sequential(
+            nn.Conv3d(n_input_channels, ch, kernel_size=(3, 7, 7),
+                      stride=(1, 2, 2), padding=(1, 3, 3), bias=False),
+            nn.BatchNorm3d(ch),
+            nn.ReLU(inplace=True),
+        )
+        # spatial: 450x449 -> 225x225, temporal: k -> k
+
+        self.layer1 = ResBlock3D(ch, ch, stride_spatial=1, stride_temporal=1)
+        # Collapse temporal dimension
+        self.layer2 = ResBlock3D(ch, ch * 2, stride_spatial=2, stride_temporal=2)
+        # temporal: k -> k//2, spatial: 225 -> 113
+        self.layer3 = ResBlock3D(ch * 2, ch * 4, stride_spatial=2, stride_temporal=2)
+        # temporal: k//2 -> 1 (for k=4), spatial: 113 -> 57
+        self.layer4 = ResBlock3D(ch * 4, ch * 4, stride_spatial=2, stride_temporal=1)
+        # spatial: 57 -> 29
+        self.layer5 = ResBlock3D(ch * 4, ch * 8, stride_spatial=2, stride_temporal=1)
+        # spatial: 29 -> 15
+        self.layer6 = ResBlock3D(ch * 8, ch * 8, stride_spatial=2, stride_temporal=1)
+        # spatial: 15 -> 8
+
+        self.pool = nn.AdaptiveAvgPool3d(1)
+        self.head = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(ch * 8, ch * 2),
+            nn.ReLU(inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(ch * 2, n_targets),
+        )
+
+    def forward(self, x):
+        # x: (B, k, C, H, W) -> (B, C, k, H, W) for Conv3d
+        x = x.permute(0, 2, 1, 3, 4)
+        x = self.stem(x)
+        x = self.layer1(x)
+        x = self.layer2(x)
+        x = self.layer3(x)
+        x = self.layer4(x)
+        x = self.layer5(x)
+        x = self.layer6(x)
+        x = self.pool(x)
+        return self.head(x)

models/cnn_baseline.py

@@ -0,0 +1,81 @@
+"""
+Baseline 2D CNN for single-frame weather forecasting.
+
+Takes a single spatial snapshot (C, H, W) and predicts 6 weather variables 24h ahead.
+Architecture: progressive downsampling with residual blocks, global average pooling, FC head.
+"""
+
+import torch
+import torch.nn as nn
+
+
+class ResBlock(nn.Module):
+    """Residual block with two conv layers and optional downsampling."""
+
+    def __init__(self, in_ch, out_ch, stride=1):
+        super().__init__()
+        self.conv1 = nn.Conv2d(in_ch, out_ch, 3, stride=stride, padding=1, bias=False)
+        self.bn1 = nn.BatchNorm2d(out_ch)
+        self.conv2 = nn.Conv2d(out_ch, out_ch, 3, stride=1, padding=1, bias=False)
+        self.bn2 = nn.BatchNorm2d(out_ch)
+        self.relu = nn.ReLU(inplace=True)
+
+        self.shortcut = nn.Identity()
+        if stride != 1 or in_ch != out_ch:
+            self.shortcut = nn.Sequential(
+                nn.Conv2d(in_ch, out_ch, 1, stride=stride, bias=False),
+                nn.BatchNorm2d(out_ch),
+            )
+
+    def forward(self, x):
+        out = self.relu(self.bn1(self.conv1(x)))
+        out = self.bn2(self.conv2(out))
+        out = self.relu(out + self.shortcut(x))
+        return out
+
+
+class BaselineCNN(nn.Module):
+    """
+    Single-frame 2D CNN encoder for weather forecasting.
+
+    Input:  (B, C, 450, 449) where C = n_input_channels (42)
+    Output: (B, 6) — predicted weather variables
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, base_channels=64):
+        super().__init__()
+
+        ch = base_channels
+        self.stem = nn.Sequential(
+            nn.Conv2d(n_input_channels, ch, 7, stride=2, padding=3, bias=False),
+            nn.BatchNorm2d(ch),
+            nn.ReLU(inplace=True),
+        )
+        # 450x449 -> 225x225
+
+        self.layer1 = ResBlock(ch, ch, stride=1)          # 225x225
+        self.layer2 = ResBlock(ch, ch * 2, stride=2)      # 113x113
+        self.layer3 = ResBlock(ch * 2, ch * 4, stride=2)  # 57x57
+        self.layer4 = ResBlock(ch * 4, ch * 4, stride=2)  # 29x29
+        self.layer5 = ResBlock(ch * 4, ch * 8, stride=2)  # 15x15
+        self.layer6 = ResBlock(ch * 8, ch * 8, stride=2)  # 8x8
+
+        self.pool = nn.AdaptiveAvgPool2d(1)
+        self.head = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(ch * 8, ch * 2),
+            nn.ReLU(inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(ch * 2, n_targets),
+        )
+
+    def forward(self, x):
+        x = self.stem(x)
+        x = self.layer1(x)
+        x = self.layer2(x)
+        x = self.layer3(x)
+        x = self.layer4(x)
+        x = self.layer5(x)
+        x = self.layer6(x)
+        x = self.pool(x)
+        return self.head(x)

models/cnn_multi_frame.py

@@ -0,0 +1,64 @@
+"""
+Multi-frame 2D CNN for weather forecasting.
+
+Stacks k consecutive spatial snapshots along the channel dimension,
+allowing the model to learn temporal patterns with standard 2D convolutions.
+
+Input:  (B, k*C, H, W)
+Output: (B, 6)
+"""
+
+import torch
+import torch.nn as nn
+from .cnn_baseline import ResBlock
+
+
+class MultiFrameCNN(nn.Module):
+    """
+    Multi-frame 2D CNN that concatenates consecutive frames along channels.
+
+    Identical backbone to BaselineCNN but with an adapted stem for k*C input channels,
+    plus a temporal mixing layer after the stem.
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, n_frames=4, base_channels=64):
+        super().__init__()
+        self.n_frames = n_frames
+        in_ch = n_input_channels * n_frames
+        ch = base_channels
+
+        self.stem = nn.Sequential(
+            nn.Conv2d(in_ch, ch * 2, 7, stride=2, padding=3, bias=False),
+            nn.BatchNorm2d(ch * 2),
+            nn.ReLU(inplace=True),
+            nn.Conv2d(ch * 2, ch, 1, bias=False),
+            nn.BatchNorm2d(ch),
+            nn.ReLU(inplace=True),
+        )
+
+        self.layer1 = ResBlock(ch, ch, stride=1)
+        self.layer2 = ResBlock(ch, ch * 2, stride=2)
+        self.layer3 = ResBlock(ch * 2, ch * 4, stride=2)
+        self.layer4 = ResBlock(ch * 4, ch * 4, stride=2)
+        self.layer5 = ResBlock(ch * 4, ch * 8, stride=2)
+        self.layer6 = ResBlock(ch * 8, ch * 8, stride=2)
+
+        self.pool = nn.AdaptiveAvgPool2d(1)
+        self.head = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(ch * 8, ch * 2),
+            nn.ReLU(inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(ch * 2, n_targets),
+        )
+
+    def forward(self, x):
+        x = self.stem(x)
+        x = self.layer1(x)
+        x = self.layer2(x)
+        x = self.layer3(x)
+        x = self.layer4(x)
+        x = self.layer5(x)
+        x = self.layer6(x)
+        x = self.pool(x)
+        return self.head(x)

models/convnext_baseline.py

@@ -0,0 +1,43 @@
+"""
+ConvNeXt-Tiny baseline for weather forecasting.
+
+Uses torchvision's ConvNeXt-Tiny with modified input/output layers
+to accept 42-channel weather data and predict 6 target variables.
+Trained from scratch (no pretrained weights).
+
+Input:  (B, 42, 450, 449)
+Output: (B, 6)
+"""
+
+import torch.nn as nn
+from torchvision.models import convnext_tiny
+
+
+class ConvNeXtBaseline(nn.Module):
+    """
+    ConvNeXt-Tiny adapted for weather forecasting.
+
+    Modifications from ImageNet ConvNeXt-Tiny:
+    - Stem conv: 3 → 42 input channels
+    - Classifier head: 1000 → n_targets outputs
+    - No pretrained weights (trained from scratch)
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, **kwargs):
+        super().__init__()
+        model = convnext_tiny(weights=None)
+
+        # Replace stem conv: 3ch → 42ch
+        # ConvNeXt stem: features[0][0] is Conv2d(3, 96, 4, stride=4)
+        model.features[0][0] = nn.Conv2d(
+            n_input_channels, 96, kernel_size=4, stride=4
+        )
+
+        # Replace classifier head: 1000 → n_targets
+        # ConvNeXt head: classifier = Sequential(LayerNorm, Flatten, Linear(768, 1000))
+        model.classifier[2] = nn.Linear(768, n_targets)
+
+        self.model = model
+
+    def forward(self, x):
+        return self.model(x)

models/resnet_baseline.py

@@ -0,0 +1,41 @@
+"""
+ResNet-18 baseline for weather forecasting.
+
+Uses torchvision's ResNet-18 with modified input/output layers
+to accept 42-channel weather data and predict 6 target variables.
+Trained from scratch (no pretrained weights).
+
+Input:  (B, 42, 450, 449)
+Output: (B, 6)
+"""
+
+import torch.nn as nn
+from torchvision.models import resnet18
+
+
+class ResNet18Baseline(nn.Module):
+    """
+    Standard ResNet-18 adapted for weather forecasting.
+
+    Modifications from ImageNet ResNet-18:
+    - conv1: 3 → 42 input channels
+    - fc: 1000 → n_targets output classes
+    - No pretrained weights (trained from scratch)
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, **kwargs):
+        super().__init__()
+        model = resnet18(weights=None)
+
+        # Replace first conv: 3ch → 42ch
+        model.conv1 = nn.Conv2d(
+            n_input_channels, 64, kernel_size=7, stride=2, padding=3, bias=False
+        )
+
+        # Replace classifier head: 1000 → n_targets
+        model.fc = nn.Linear(512, n_targets)
+
+        self.model = model
+
+    def forward(self, x):
+        return self.model(x)

models/vit.py

@@ -0,0 +1,116 @@
+"""
+Vision Transformer (ViT) for weather forecasting.
+
+Splits the spatial input into non-overlapping patches, projects each patch
+into an embedding, and processes them through a Transformer encoder.
+
+Input:  (B, C, H, W) — single frame with C channels
+Output: (B, 6)
+"""
+
+import math
+import torch
+import torch.nn as nn
+
+
+class PatchEmbedding(nn.Module):
+    """Convert spatial input into a sequence of patch embeddings."""
+
+    def __init__(self, in_channels, embed_dim, patch_size, img_h, img_w):
+        super().__init__()
+        self.patch_size = patch_size
+        self.n_patches_h = img_h // patch_size
+        self.n_patches_w = img_w // patch_size
+        self.n_patches = self.n_patches_h * self.n_patches_w
+
+        self.proj = nn.Conv2d(in_channels, embed_dim,
+                              kernel_size=patch_size, stride=patch_size)
+
+    def forward(self, x):
+        # x: (B, C, H, W) -> (B, embed_dim, nH, nW) -> (B, n_patches, embed_dim)
+        x = self.proj(x)
+        x = x.flatten(2).transpose(1, 2)
+        return x
+
+
+class TransformerBlock(nn.Module):
+    """Standard Transformer encoder block with pre-norm."""
+
+    def __init__(self, embed_dim, n_heads, mlp_ratio=4.0, dropout=0.1):
+        super().__init__()
+        self.norm1 = nn.LayerNorm(embed_dim)
+        self.attn = nn.MultiheadAttention(embed_dim, n_heads,
+                                          dropout=dropout, batch_first=True)
+        self.norm2 = nn.LayerNorm(embed_dim)
+        self.mlp = nn.Sequential(
+            nn.Linear(embed_dim, int(embed_dim * mlp_ratio)),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(int(embed_dim * mlp_ratio), embed_dim),
+            nn.Dropout(dropout),
+        )
+
+    def forward(self, x):
+        h = self.norm1(x)
+        h, _ = self.attn(h, h, h)
+        x = x + h
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class WeatherViT(nn.Module):
+    """
+    Vision Transformer for weather forecasting.
+
+    Input:  (B, C, 450, 449) — pads width to 450 internally
+    Output: (B, 6)
+
+    Patches the input into 15x15 patches (30x30 = 900 tokens),
+    adds CLS token and positional embeddings, runs through Transformer,
+    and predicts from the CLS token.
+    """
+
+    def __init__(self, n_input_channels=42, n_targets=6, patch_size=15,
+                 embed_dim=256, n_layers=6, n_heads=8, mlp_ratio=4.0, dropout=0.1,
+                 **kwargs):
+        super().__init__()
+        self.patch_size = patch_size
+        img_h, img_w = 450, 450  # pad to square
+
+        self.patch_embed = PatchEmbedding(n_input_channels, embed_dim,
+                                          patch_size, img_h, img_w)
+        n_patches = self.patch_embed.n_patches
+
+        self.cls_token = nn.Parameter(torch.randn(1, 1, embed_dim) * 0.02)
+        self.pos_embed = nn.Parameter(torch.randn(1, n_patches + 1, embed_dim) * 0.02)
+        self.pos_drop = nn.Dropout(dropout)
+
+        self.blocks = nn.Sequential(*[
+            TransformerBlock(embed_dim, n_heads, mlp_ratio, dropout)
+            for _ in range(n_layers)
+        ])
+        self.norm = nn.LayerNorm(embed_dim)
+
+        self.head = nn.Sequential(
+            nn.Linear(embed_dim, embed_dim // 2),
+            nn.ReLU(inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(embed_dim // 2, n_targets),
+        )
+
+    def forward(self, x):
+        B, C, H, W = x.shape
+        # Pad width from 449 to 450 if needed
+        if W < 450:
+            x = nn.functional.pad(x, (0, 450 - W))
+
+        patches = self.patch_embed(x)                       # (B, n_patches, D)
+        cls = self.cls_token.expand(B, -1, -1)              # (B, 1, D)
+        x = torch.cat([cls, patches], dim=1)                # (B, n_patches+1, D)
+        x = self.pos_drop(x + self.pos_embed)
+
+        x = self.blocks(x)
+        x = self.norm(x)
+
+        cls_out = x[:, 0]                                   # (B, D)
+        return self.head(cls_out)

packages.txt

@@ -0,0 +1,2 @@
+libeccodes-dev
+libeccodes-tools

requirements.txt

@@ -0,0 +1,10 @@
+torch>=2.1.0
+torchvision
+numpy
+matplotlib
+gradio>=4.0
+herbie-data>=2024.1
+cfgrib
+xarray
+eccodes
+cartopy

var_mapping.py

@@ -0,0 +1,82 @@
+"""
+Mapping from 42-channel VAR_LEVELS to HRRR GRIB2 Herbie search strings.
+
+Each entry corresponds to one channel in the model input, following the exact
+order defined in data_preparation/data_spec.py (VAR_LEVELS = TARGET_VARS + ATMOS_VARS).
+"""
+
+# fmt: off
+HRRR_MAPPING = [
+    # ── Target / surface variables (channels 0-6) ──────────────────────
+    {"name": "TMP@2m_above_ground",         "search": ":TMP:2 m above ground",            "product": "sfc", "fxx": 0},
+    {"name": "RH@2m_above_ground",          "search": ":RH:2 m above ground",             "product": "sfc", "fxx": 0},
+    {"name": "UGRD@10m_above_ground",       "search": ":UGRD:10 m above ground",          "product": "sfc", "fxx": 0},
+    {"name": "VGRD@10m_above_ground",       "search": ":VGRD:10 m above ground",          "product": "sfc", "fxx": 0},
+    {"name": "GUST@surface",                "search": ":GUST:surface",                     "product": "sfc", "fxx": 0},
+    {"name": "DSWRF@surface",               "search": ":DSWRF:surface",                    "product": "sfc", "fxx": 0},
+    # APCP is accumulated; not in analysis (fxx=0). Use 1-hour forecast from same cycle.
+    {"name": "APCP_1hr_acc_fcst@surface",   "search": ":APCP:surface:0-1 hour acc fcst",   "product": "sfc", "fxx": 1},
+
+    # ── Atmospheric variables (channels 7-41) ──────────────────────────
+    # CAPE
+    {"name": "CAPE@surface",                "search": ":CAPE:surface",                     "product": "sfc", "fxx": 0},
+
+    # Dew point temperature at pressure levels
+    {"name": "DPT@1000mb",                  "search": ":DPT:1000 mb",                     "product": "prs", "fxx": 0},
+    {"name": "DPT@500mb",                   "search": ":DPT:500 mb",                      "product": "prs", "fxx": 0},
+    {"name": "DPT@700mb",                   "search": ":DPT:700 mb",                      "product": "prs", "fxx": 0},
+    {"name": "DPT@850mb",                   "search": ":DPT:850 mb",                      "product": "prs", "fxx": 0},
+    {"name": "DPT@925mb",                   "search": ":DPT:925 mb",                      "product": "prs", "fxx": 0},
+
+    # Geopotential height at pressure levels + surface
+    {"name": "HGT@1000mb",                  "search": ":HGT:1000 mb",                     "product": "prs", "fxx": 0},
+    {"name": "HGT@500mb",                   "search": ":HGT:500 mb",                      "product": "prs", "fxx": 0},
+    {"name": "HGT@700mb",                   "search": ":HGT:700 mb",                      "product": "prs", "fxx": 0},
+    {"name": "HGT@850mb",                   "search": ":HGT:850 mb",                      "product": "prs", "fxx": 0},
+    {"name": "HGT@surface",                 "search": ":HGT:surface",                     "product": "sfc", "fxx": 0},
+
+    # Temperature at pressure levels
+    {"name": "TMP@1000mb",                  "search": ":TMP:1000 mb",                     "product": "prs", "fxx": 0},
+    {"name": "TMP@500mb",                   "search": ":TMP:500 mb",                      "product": "prs", "fxx": 0},
+    {"name": "TMP@700mb",                   "search": ":TMP:700 mb",                      "product": "prs", "fxx": 0},
+    {"name": "TMP@850mb",                   "search": ":TMP:850 mb",                      "product": "prs", "fxx": 0},
+    {"name": "TMP@925mb",                   "search": ":TMP:925 mb",                      "product": "prs", "fxx": 0},
+
+    # U-component wind at pressure levels
+    {"name": "UGRD@1000mb",                 "search": ":UGRD:1000 mb",                    "product": "prs", "fxx": 0},
+    {"name": "UGRD@250mb",                  "search": ":UGRD:250 mb",                     "product": "prs", "fxx": 0},
+    {"name": "UGRD@500mb",                  "search": ":UGRD:500 mb",                     "product": "prs", "fxx": 0},
+    {"name": "UGRD@700mb",                  "search": ":UGRD:700 mb",                     "product": "prs", "fxx": 0},
+    {"name": "UGRD@850mb",                  "search": ":UGRD:850 mb",                     "product": "prs", "fxx": 0},
+    {"name": "UGRD@925mb",                  "search": ":UGRD:925 mb",                     "product": "prs", "fxx": 0},
+
+    # V-component wind at pressure levels
+    {"name": "VGRD@1000mb",                 "search": ":VGRD:1000 mb",                    "product": "prs", "fxx": 0},
+    {"name": "VGRD@250mb",                  "search": ":VGRD:250 mb",                     "product": "prs", "fxx": 0},
+    {"name": "VGRD@500mb",                  "search": ":VGRD:500 mb",                     "product": "prs", "fxx": 0},
+    {"name": "VGRD@700mb",                  "search": ":VGRD:700 mb",                     "product": "prs", "fxx": 0},
+    {"name": "VGRD@850mb",                  "search": ":VGRD:850 mb",                     "product": "prs", "fxx": 0},
+    {"name": "VGRD@925mb",                  "search": ":VGRD:925 mb",                     "product": "prs", "fxx": 0},
+
+    # Cloud cover
+    {"name": "TCDC@entire_atmosphere",      "search": ":TCDC:entire atmosphere",           "product": "sfc", "fxx": 0},
+    {"name": "HCDC@high_cloud_layer",       "search": ":HCDC:high cloud layer",            "product": "sfc", "fxx": 0},
+    {"name": "MCDC@middle_cloud_layer",     "search": ":MCDC:middle cloud layer",          "product": "sfc", "fxx": 0},
+    {"name": "LCDC@low_cloud_layer",        "search": ":LCDC:low cloud layer",             "product": "sfc", "fxx": 0},
+
+    # Moisture
+    {"name": "PWAT@entire_atmosphere_single_layer", "search": ":PWAT:entire atmosphere",   "product": "sfc", "fxx": 0},
+    {"name": "RHPW@entire_atmosphere",      "search": ":RHPW:entire atmosphere",           "product": "sfc", "fxx": 0},
+    {"name": "VIL@entire_atmosphere",       "search": ":VIL:entire atmosphere",            "product": "sfc", "fxx": 0},
+]
+# fmt: on
+
+assert len(HRRR_MAPPING) == 42, f"Expected 42 channels, got {len(HRRR_MAPPING)}"
+
+# New England subgrid slice in the full HRRR CONUS grid (from data_spec.py)
+NE_Y_SLICE = slice(600, 1050)   # 450 rows
+NE_X_SLICE = slice(1350, 1799)  # 449 columns
+
+# Jumbo Statue grid location within the NE subgrid
+JUMBO_ROW = 177
+JUMBO_COL = 263

visualization.py

@@ -0,0 +1,234 @@
+"""
+Forecast visualization — satellite, street, and temperature maps.
+
+Satellite and reference maps are static (rendered once at startup).
+Temperature map updates each time a forecast is run.
+"""
+
+import logging
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+import cartopy.io.img_tiles as cimgt
+
+from var_mapping import JUMBO_ROW, JUMBO_COL
+
+logger = logging.getLogger(__name__)
+
+# ── Projection & coordinates (from data_spec.py) ──────────────────────
+
+PROJ = ccrs.LambertConformal(
+    central_longitude=262.5,
+    central_latitude=38.5,
+    standard_parallels=(38.5, 38.5),
+    globe=ccrs.Globe(semimajor_axis=6371229, semiminor_axis=6371229),
+)
+
+_x = 1352479.8574780696 + np.arange(449) * 3000
+_y = 212693.8474433364 + np.arange(450) * 3000
+EXTENT = [_x[0], _x[-1], _y[0], _y[-1]]
+
+JUMBO_LON, JUMBO_LAT = -71.1204, 42.4078
+X_GRID, Y_GRID = np.meshgrid(_x, _y)
+
+CITIES = [
+    ("Boston",      42.36, -71.06),
+    ("Providence",  41.82, -71.41),
+    ("Hartford",    41.76, -72.68),
+    ("Portland",    43.66, -70.26),
+    ("Burlington",  44.48, -73.21),
+    ("Concord",     43.21, -71.54),
+    ("Albany",       42.65, -73.76),
+    ("New York",    40.71, -74.01),
+    ("Montreal",    45.50, -73.57),
+]
+
+
+# ── Tile sources ──────────────────────────────────────────────────────
+
+class _EsriSatellite(cimgt.GoogleWTS):
+    def _image_url(self, tile):
+        x, y, z = tile
+        return (
+            "https://server.arcgisonline.com/ArcGIS/rest/services/"
+            f"World_Imagery/MapServer/tile/{z}/{y}/{x}"
+        )
+
+
+class _EsriStreetMap(cimgt.GoogleWTS):
+    def _image_url(self, tile):
+        x, y, z = tile
+        return (
+            "https://server.arcgisonline.com/ArcGIS/rest/services/"
+            f"World_Street_Map/MapServer/tile/{z}/{y}/{x}"
+        )
+
+
+# ── Shared style ─────────────────────────────────────────────────────
+
+_MARKER = dict(
+    marker="*", color="#FF3B30", markersize=14,
+    markeredgecolor="white", markeredgewidth=1.0,
+    transform=ccrs.PlateCarree(), zorder=20,
+)
+
+_TAG = dict(
+    fontsize=8.5, fontweight="bold", fontfamily="sans-serif",
+    color="white", transform=ccrs.PlateCarree(), zorder=25,
+    bbox=dict(boxstyle="round,pad=0.25", fc="#1C1C1E", ec="none", alpha=0.80),
+)
+
+
+def _make_ax(fig_or_ax=None, figsize=(7.2, 6.8)):
+    """Create a single GeoAxes with consistent extent."""
+    if fig_or_ax is None:
+        fig, ax = plt.subplots(
+            figsize=figsize, subplot_kw={"projection": PROJ},
+        )
+    else:
+        fig, ax = fig_or_ax.figure, fig_or_ax
+    ax.set_extent(EXTENT, crs=PROJ)
+    return fig, ax
+
+
+# ── Individual map renderers ─────────────────────────────────────────
+
+def plot_satellite() -> Figure:
+    """Render satellite basemap (static, no weather data needed)."""
+    fig, ax = _make_ax()
+    try:
+        ax.add_image(_EsriSatellite(), 7)
+    except Exception:
+        ax.add_feature(cfeature.LAND, facecolor="#5C4A32")
+        ax.add_feature(cfeature.OCEAN, facecolor="#1B3A4B")
+        ax.add_feature(cfeature.COASTLINE, linewidth=0.6, color="white")
+        ax.add_feature(cfeature.STATES, linewidth=0.3, edgecolor="#aaa")
+    ax.plot(JUMBO_LON, JUMBO_LAT, **_MARKER)
+    ax.text(JUMBO_LON + 0.35, JUMBO_LAT + 0.25, "Jumbo", **_TAG)
+    ax.set_title(
+        "Satellite", fontsize=12, fontweight="600",
+        fontfamily="sans-serif", pad=8, color="#1D1D1F",
+    )
+    fig.subplots_adjust(left=0.02, right=0.98, bottom=0.02, top=0.93)
+    return fig
+
+
+def plot_street() -> Figure:
+    """Render street / reference basemap (static)."""
+    fig, ax = _make_ax()
+    try:
+        ax.add_image(_EsriStreetMap(), 7)
+    except Exception:
+        ax.add_feature(cfeature.LAND, facecolor="#E8E4D8")
+        ax.add_feature(cfeature.OCEAN, facecolor="#AAD3DF")
+        ax.add_feature(cfeature.LAKES, facecolor="#AAD3DF", edgecolor="#888", linewidth=0.3)
+        ax.add_feature(cfeature.RIVERS, edgecolor="#AAD3DF", linewidth=0.4)
+        ax.add_feature(cfeature.COASTLINE, linewidth=0.5)
+        ax.add_feature(cfeature.BORDERS, linewidth=0.5, linestyle="--")
+        ax.add_feature(cfeature.STATES, linewidth=0.3, edgecolor="#888")
+        pc = ccrs.PlateCarree()
+        for name, lat, lon in CITIES:
+            ax.text(
+                lon, lat, name,
+                fontsize=7, fontfamily="sans-serif", fontweight="500",
+                color="#333", transform=pc, zorder=15,
+                bbox=dict(boxstyle="round,pad=0.15", fc="white", ec="none", alpha=0.7),
+            )
+    ax.plot(JUMBO_LON, JUMBO_LAT, **_MARKER)
+    ax.text(JUMBO_LON + 0.35, JUMBO_LAT + 0.25, "Jumbo", **_TAG)
+    ax.set_title(
+        "Reference Map", fontsize=12, fontweight="600",
+        fontfamily="sans-serif", pad=8, color="#1D1D1F",
+    )
+    fig.subplots_adjust(left=0.02, right=0.98, bottom=0.02, top=0.93)
+    return fig
+
+
+def plot_temperature(
+    input_array: np.ndarray,
+    forecast: dict,
+    cycle_str: str,
+    forecast_str: str,
+) -> Figure:
+    """Render 2 m temperature map with forecast annotation."""
+    fig, ax = _make_ax()
+
+    temp_field = input_array[:, :, 0] - 273.15
+    masked = np.ma.masked_invalid(temp_field)
+
+    im = ax.pcolormesh(
+        X_GRID, Y_GRID, masked,
+        cmap="RdYlBu_r", shading="auto", transform=PROJ, zorder=5,
+    )
+    ax.add_feature(cfeature.COASTLINE, linewidth=0.5, color="#444", zorder=10)
+    ax.add_feature(cfeature.STATES, linewidth=0.3, edgecolor="#666", zorder=10)
+
+    cbar = fig.colorbar(im, ax=ax, shrink=0.72, pad=0.03, aspect=28)
+    cbar.set_label("°C", fontsize=10, fontfamily="sans-serif")
+    cbar.ax.tick_params(labelsize=8)
+
+    ax.plot(JUMBO_LON, JUMBO_LAT, **_MARKER)
+
+    temp_c = forecast["temperature_c"]
+    temp_f = forecast["temperature_f"]
+    label = f"Forecast {forecast_str}\n{temp_c:+.1f} °C  /  {temp_f:.0f} °F"
+    ax.text(
+        JUMBO_LON + 0.45, JUMBO_LAT + 0.35, label,
+        fontsize=8.5, fontweight="bold", fontfamily="sans-serif",
+        color="white", transform=ccrs.PlateCarree(), zorder=25,
+        bbox=dict(boxstyle="round,pad=0.35", fc="#1C1C1E", ec="white", alpha=0.88, lw=0.8),
+    )
+
+    ax.set_title(
+        f"2 m Temperature — {cycle_str}",
+        fontsize=12, fontweight="600",
+        fontfamily="sans-serif", pad=8, color="#1D1D1F",
+    )
+    fig.subplots_adjust(left=0.02, right=0.95, bottom=0.02, top=0.93)
+    return fig
+
+
+def plot_temperature_placeholder() -> Figure:
+    """Empty temperature panel shown before first forecast."""
+    fig, ax = _make_ax()
+    ax.add_feature(cfeature.LAND, facecolor="#E8E4D8", zorder=1)
+    ax.add_feature(cfeature.OCEAN, facecolor="#D6EAF0", zorder=1)
+    ax.add_feature(cfeature.COASTLINE, linewidth=0.5, color="#999", zorder=2)
+    ax.add_feature(cfeature.STATES, linewidth=0.3, edgecolor="#bbb", zorder=2)
+    ax.plot(JUMBO_LON, JUMBO_LAT, **_MARKER)
+    ax.text(
+        JUMBO_LON + 0.35, JUMBO_LAT + 0.25, "Jumbo", **_TAG,
+    )
+    ax.text(
+        0.5, 0.50, "Click  Run Forecast",
+        transform=ax.transAxes, ha="center", va="center",
+        fontsize=14, fontweight="600", fontfamily="sans-serif",
+        color="#86868B",
+    )
+    ax.set_title(
+        "2 m Temperature", fontsize=12, fontweight="600",
+        fontfamily="sans-serif", pad=8, color="#1D1D1F",
+    )
+    fig.subplots_adjust(left=0.02, right=0.98, bottom=0.02, top=0.93)
+    return fig
+
+
+# ── Startup cache ─────────────────────────────────────────────────────
+
+_cache = {}
+
+
+def get_static_maps() -> tuple[Figure, Figure]:
+    """Return cached satellite and street map figures (rendered once)."""
+    if "satellite" not in _cache:
+        logger.info("Rendering satellite basemap...")
+        _cache["satellite"] = plot_satellite()
+    if "street" not in _cache:
+        logger.info("Rendering reference basemap...")
+        _cache["street"] = plot_street()
+    return _cache["satellite"], _cache["street"]