Initial myPSD — FastAPI + React port of bokeh-myPSD on rustmatrix

- backend/app: FastAPI /api/compute + /api/health over rustmatrix, 11 polarimetric metrics + N(D) curve
- backend/tests: 12 pytest cases (smoke + sanity) across S/C/X × rain/hail + canting
- frontend: React 18 + Vite + TypeScript + Plotly (basic bundle), debounced slider inputs
- assets/: Minecraft-block icon with gamma PSD in light blocks + snowflake accent; BioRhyme-bold 'myPSD' wordmark with thick white stroke
- Dockerfile: 3-stage build (node SPA → maturin rustmatrix wheel → python runtime) for HF Spaces
- .github/workflows/hf-sync.yml: mirror main to HF Space on push

.dockerignore

@@ -0,0 +1,13 @@
+**/__pycache__
+**/.pytest_cache
+**/.venv
+**/.mypy_cache
+**/.ruff_cache
+**/node_modules
+**/dist
+backend/app/static
+.git
+.github
+.DS_Store
+*.md
+!README.md

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/hf-sync.yml

@@ -0,0 +1,26 @@
+name: Sync to Hugging Face Space
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USER: snesbitt
+          HF_SPACE: myPSD
+        run: |
+          git config --global user.email "actions@github.com"
+          git config --global user.name "GitHub Actions"
+          git remote add hf "https://${HF_USER}:${HF_TOKEN}@huggingface.co/spaces/${HF_USER}/${HF_SPACE}"
+          git push --force hf main

.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node / Vite
+node_modules/
+dist/
+frontend/dist/
+backend/app/static/
+*.tsbuildinfo
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Local env
+.env
+.env.local
+
+# Hugging Face cache
+.cache/

Dockerfile

@@ -0,0 +1,68 @@
+# syntax=docker/dockerfile:1.6
+#
+# Hugging Face Space Docker build for myPSD.
+#
+# Three stages:
+#   1. node:20-alpine      → compile the Vite React SPA
+#   2. rust:1.82-slim      → clone rustmatrix at v1.0.1 and build a Python wheel
+#   3. python:3.11-slim    → install the wheel + FastAPI, copy the SPA, run uvicorn
+#
+# HF Spaces routes external traffic to whatever port the container listens
+# on via `app_port` in README.md — we use 7860 (the HF default).
+
+# ---------- stage 1: build the SPA ----------
+FROM node:20-alpine AS spa
+WORKDIR /spa
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --no-audit --no-fund
+COPY frontend/ ./
+# Vite outDir in our config points to ../backend/app/static — we don't want
+# that path layout inside this stage, so override to /spa/dist here.
+RUN npx vite build --outDir dist --emptyOutDir
+
+
+# ---------- stage 2: build the rustmatrix wheel ----------
+FROM rust:1.82-slim AS rustbuild
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip python3-venv python3-dev \
+        build-essential pkg-config git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python3 -m pip install --break-system-packages "maturin==1.7.*"
+
+WORKDIR /src
+# Pin to the stable release so HF deploys are reproducible.
+ARG RUSTMATRIX_REF=v1.0.1
+RUN git clone --depth 1 --branch ${RUSTMATRIX_REF} \
+        https://github.com/swnesbitt/rustmatrix.git .
+RUN maturin build --release --out /wheels -i python3
+
+
+# ---------- stage 3: runtime ----------
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY --from=rustbuild /wheels /wheels
+RUN pip install --no-cache-dir /wheels/*.whl \
+ && pip install --no-cache-dir \
+        "fastapi>=0.110" \
+        "uvicorn[standard]>=0.27" \
+        "pydantic>=2.6" \
+        "numpy>=1.23" \
+        "scipy>=1.10" \
+ && rm -rf /wheels
+
+# HF Spaces runs the container as uid 1000 with /tmp as the only writable
+# directory by default.
+ENV HOME=/tmp \
+    XDG_CACHE_HOME=/tmp/.cache
+
+COPY backend/app /app/app
+COPY --from=spa /spa/dist /app/app/static
+# Also make the repo-level assets discoverable (logo/icon) for non-bundled use.
+COPY assets /app/app/static/assets
+
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,70 @@
+---
+title: myPSD
+emoji: 🌧️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+<p align="center">
+  <img src="assets/logo.svg" alt="myPSD" width="640" />
+</p>
+
+# myPSD
+
+Interactive explorer for polarimetric radar observables derived from a
+normalized-gamma particle-size distribution (Testud et al. 2001). Drag the
+sliders to vary `Dm`, `log₁₀Nw`, and `μ`; pick a radar wavelength (S / C / X),
+canting-angle standard deviation, and precipitation type (rain or hail) to see
+the resulting N(D) curve and 11-metric polarimetric table update live.
+
+This is a port of [`swnesbitt/bokeh-myPSD`](https://github.com/swnesbitt/bokeh-myPSD)
+rebuilt on:
+
+- **[rustmatrix](https://github.com/swnesbitt/rustmatrix)** — Rust-backed
+  T-matrix scattering (drop-in `pytmatrix` replacement)
+- **FastAPI** — thin JSON API over the scatterer
+- **React + Vite + Plotly.js** — interactive single-page frontend
+- **Docker on Hugging Face Spaces** — deployment
+
+Branded with the [CLIMAS](https://climas.illinois.edu/) group icon.
+
+## Local development
+
+### Backend
+
+```bash
+cd backend
+uv venv
+uv pip install -e .
+uv run uvicorn app.main:app --reload --port 8000
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm ci
+npm run dev
+```
+
+The Vite dev server proxies `/api` to `localhost:8000`. Production builds
+output to `backend/app/static/`, which FastAPI serves from the same origin.
+
+### Docker (simulates HF Spaces)
+
+```bash
+docker build -t mypsd .
+docker run --rm -p 7860:7860 -e HOME=/tmp mypsd
+# open http://localhost:7860
+```
+
+## Attribution
+
+- **myPSD** concept & original Bokeh app: Steve Nesbitt, University of
+  Illinois Urbana-Champaign.
+- **pytmatrix** (the original T-matrix Python wrapper): Jussi Leinonen,
+  MeteoSwiss.
+- **rustmatrix**: Rust port of the pytmatrix numerical core.

backend/app/main.py

@@ -0,0 +1,58 @@
+"""FastAPI entry point for myPSD.
+
+In production the compiled React SPA is baked into `app/static/` by the
+Dockerfile, and this process serves both `/api/*` and the SPA. In local
+dev, Vite serves the SPA from its own port and proxies `/api/*` here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from . import scatter
+from .models import ComputeRequest, ComputeResponse
+
+
+app = FastAPI(title="myPSD", version="0.1.0")
+
+# Dev proxy hits us cross-origin; production is same-origin. Permissive CORS
+# is fine for a stateless teaching tool with no auth.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/api/health")
+def health() -> dict[str, str]:
+    try:
+        import rustmatrix
+
+        return {"status": "ok", "rustmatrix": rustmatrix.__version__}
+    except Exception as exc:  # pragma: no cover
+        return {"status": "degraded", "error": str(exc)}
+
+
+@app.post("/api/compute", response_model=ComputeResponse)
+def compute(req: ComputeRequest) -> ComputeResponse:
+    return scatter.compute(
+        dm=req.dm,
+        log_nw=req.log_nw,
+        mu=req.mu,
+        band=req.band,
+        canting_std_deg=req.canting_std_deg,
+        precip=req.precip,
+    )
+
+
+# Mount the built SPA if present. Using `html=True` makes unknown paths fall
+# back to index.html so client-side routing works.
+_STATIC_DIR = Path(__file__).parent / "static"
+if _STATIC_DIR.exists():
+    app.mount("/", StaticFiles(directory=_STATIC_DIR, html=True), name="static")

backend/app/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+Band = Literal["S", "C", "X"]
+Precip = Literal["rain", "hail"]
+
+
+class ComputeRequest(BaseModel):
+    dm: float = Field(ge=0.1, le=8.0, description="Mass-weighted mean diameter [mm]")
+    log_nw: float = Field(ge=0.5, le=6.0, description="log10(Nw) [mm^-1 m^-3]")
+    mu: float = Field(ge=-3.0, le=80.0, description="Gamma shape parameter")
+    band: Band = "S"
+    canting_std_deg: float = Field(default=0.0, ge=0.0, le=40.0)
+    precip: Precip = "rain"
+
+
+class Metrics(BaseModel):
+    zh_dbz: float
+    zv_dbz: float
+    zdr_db: float
+    ldr_db: float
+    rho_hv: float
+    delta_deg: float
+    kdp_deg_per_km: float
+    ah_db_per_km: float
+    adr_db_per_km: float
+    nt_per_m3: float
+    lwc_g_per_m3: float
+
+
+class NDCurve(BaseModel):
+    d_mm: list[float]
+    n_d: list[float]
+
+
+class ComputeResponse(BaseModel):
+    metrics: Metrics
+    nd: NDCurve

backend/app/scatter.py

@@ -0,0 +1,151 @@
+"""PSD-integrated polarimetric radar metrics via rustmatrix.
+
+Mirrors the scatter path from bokeh-myPSD's bokeh-app/main.py, ported to
+rustmatrix. The scatter table is the expensive step; cache it keyed by
+(band, precip, canting_std) so that Dm / log_Nw / mu sweeps are cheap.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from scipy.special import gamma as gamma_fn
+
+from rustmatrix import orientation, radar, refractive, tmatrix_aux
+from rustmatrix.psd import GammaPSD, PSDIntegrator
+from rustmatrix.scatter import ldr as scatter_ldr
+from rustmatrix.scatterer import Scatterer
+
+from .models import Band, ComputeResponse, Metrics, NDCurve, Precip
+
+
+_BAND_WL = {"S": tmatrix_aux.wl_S, "C": tmatrix_aux.wl_C, "X": tmatrix_aux.wl_X}
+
+_HAIL_M = complex(1.78, 7.9e-4)
+
+_D_PLOT = np.arange(0.1, 20.0, 0.1)  # mm
+
+
+def _drop_ar(d_eq: float) -> float:
+    """Beard-Chuang-style axis ratio for raindrops (from pytmatrix examples)."""
+    if d_eq < 0.7:
+        return 1.0
+    if d_eq < 1.5:
+        return (
+            1.173
+            - 0.5165 * d_eq
+            + 0.4698 * d_eq**2
+            - 0.1317 * d_eq**3
+            - 8.5e-3 * d_eq**4
+        )
+    return (
+        1.065
+        - 6.25e-2 * d_eq
+        - 3.99e-3 * d_eq**2
+        + 7.66e-4 * d_eq**3
+        - 4.095e-5 * d_eq**4
+    )
+
+
+def _rain_axis_ratio(d: float) -> float:
+    return 1.0 / _drop_ar(d)
+
+
+def _hail_axis_ratio(d: float) -> float:
+    return 0.99
+
+
+@lru_cache(maxsize=24)
+def _build_scatterer(band: Band, precip: Precip, canting_std_deg: float) -> Scatterer:
+    """Build a scatterer and pre-compute its PSD scatter table.
+
+    Result is cached across requests because the table build dominates latency.
+    A Scatterer holds mutable PSD state, but we rewrite `scatterer.psd` on
+    every compute() call, so reuse is safe as long as geometry / canting /
+    refractive index don't change — which is exactly what this key covers.
+    """
+    wavelength = _BAND_WL[band]
+    m = _HAIL_M if precip == "hail" else refractive.m_w_10C[wavelength]
+
+    scatterer = Scatterer(wavelength=wavelength, m=m)
+    scatterer.psd_integrator = PSDIntegrator()
+    scatterer.psd_integrator.axis_ratio_func = (
+        _rain_axis_ratio if precip == "rain" else _hail_axis_ratio
+    )
+    scatterer.psd_integrator.D_max = 10.0
+    scatterer.psd_integrator.geometries = (
+        tmatrix_aux.geom_horiz_back,
+        tmatrix_aux.geom_horiz_forw,
+    )
+
+    if canting_std_deg > 0.0:
+        scatterer.or_pdf = orientation.gaussian_pdf(canting_std_deg)
+    scatterer.orient = orientation.orient_averaged_fixed
+
+    scatterer.psd_integrator.init_scatter_table(scatterer)
+    return scatterer
+
+
+def _nd(d_mm: np.ndarray, dm: float, log_nw: float, mu: float) -> np.ndarray:
+    """Normalized gamma PSD, Testud et al. 2001 convention."""
+    f_u = (6.0 / 4.0**4) * ((4.0 + mu) ** (mu + 4.0)) / gamma_fn(mu + 4.0)
+    return (
+        10.0**log_nw
+        * f_u
+        * (d_mm / dm) ** mu
+        * np.exp(-(4.0 + mu) * (d_mm / dm))
+    )
+
+
+def compute(
+    dm: float,
+    log_nw: float,
+    mu: float,
+    band: Band,
+    canting_std_deg: float,
+    precip: Precip,
+) -> ComputeResponse:
+    scatterer = _build_scatterer(band, precip, float(canting_std_deg))
+
+    d0 = (3.67 + mu) / (4.0 + mu) * dm
+    nw = 10.0**log_nw
+    scatterer.psd = GammaPSD(D0=d0, Nw=nw, mu=mu)
+
+    scatterer.set_geometry(tmatrix_aux.geom_horiz_back)
+    zh = 10.0 * np.log10(radar.refl(scatterer))
+    zv = 10.0 * np.log10(radar.refl(scatterer, False))
+    zdr = 10.0 * np.log10(radar.Zdr(scatterer))
+    ldr_db = 10.0 * np.log10(scatter_ldr(scatterer))
+    rho_hv = float(radar.rho_hv(scatterer))
+    delta = float(radar.delta_hv(scatterer))
+
+    scatterer.set_geometry(tmatrix_aux.geom_horiz_forw)
+    kdp = float(radar.Kdp(scatterer))
+    ah = float(radar.Ai(scatterer))
+    av = float(radar.Ai(scatterer, h_pol=False))
+    adr = ah - av
+
+    f_u = (6.0 / 4.0**4) * ((4.0 + mu) ** (mu + 4.0)) / gamma_fn(mu + 4.0)
+    nt = nw * f_u * gamma_fn(mu + 1.0) * dm / ((4.0 + mu) ** (mu + 1.0))
+    density = 1000.0 if precip == "rain" else 917.0
+    lwc = (np.pi * nw * dm**4) / (4.0**4 * density)
+
+    metrics = Metrics(
+        zh_dbz=float(zh),
+        zv_dbz=float(zv),
+        zdr_db=float(zdr),
+        ldr_db=float(ldr_db),
+        rho_hv=rho_hv,
+        delta_deg=delta,
+        kdp_deg_per_km=kdp,
+        ah_db_per_km=ah,
+        adr_db_per_km=adr,
+        nt_per_m3=float(nt),
+        lwc_g_per_m3=float(lwc),
+    )
+
+    n_d = _nd(_D_PLOT, dm, log_nw, mu)
+    nd = NDCurve(d_mm=_D_PLOT.tolist(), n_d=n_d.tolist())
+
+    return ComputeResponse(metrics=metrics, nd=nd)

backend/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "mypsd-backend"
+version = "0.1.0"
+description = "FastAPI backend for myPSD — polarimetric radar PSD explorer"
+requires-python = ">=3.10"
+dependencies = [
+    "rustmatrix>=1.0.1",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.6",
+    "numpy>=1.23",
+    "scipy>=1.10",
+]
+
+[tool.uv.sources]
+# rustmatrix is not on PyPI yet — build from the sibling checkout.
+# The Dockerfile builds a wheel directly and installs that instead.
+rustmatrix = { path = "../../Radar/rustmatrix", editable = true }
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]

backend/tests/test_scatter.py

@@ -0,0 +1,93 @@
+"""Smoke + sanity tests for the scatter path.
+
+These don't pin values to bokeh-myPSD screenshots (those aren't captured yet),
+but they exercise every branch — rain/hail × S/C/X × canted/uncanted — and
+assert physical sanity: finite, in-range, monotonic where expected.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.scatter import compute
+
+
+@pytest.fixture(scope="module")
+def client():
+    return TestClient(app)
+
+
+@pytest.mark.parametrize("band", ["S", "C", "X"])
+@pytest.mark.parametrize("precip", ["rain", "hail"])
+def test_compute_smoke(band, precip):
+    r = compute(dm=2.0, log_nw=3.0, mu=0.0, band=band, canting_std_deg=0.0, precip=precip)
+    m = r.metrics
+
+    assert all(math.isfinite(v) for v in (
+        m.zh_dbz, m.zv_dbz, m.zdr_db, m.ldr_db, m.rho_hv, m.delta_deg,
+        m.kdp_deg_per_km, m.ah_db_per_km, m.adr_db_per_km, m.nt_per_m3, m.lwc_g_per_m3,
+    ))
+    # ρ_hv in physical range
+    assert 0.0 < m.rho_hv <= 1.0
+    # reasonable reflectivity for Dm=2mm, Nw=10^3
+    assert 15.0 < m.zh_dbz < 60.0
+    # Zh vs Zv: rain is oblate (Zh > Zv); hail at 0.99 is near-spherical so
+    # |Zh - Zv| should at least be small.
+    if precip == "rain":
+        assert m.zh_dbz > m.zv_dbz
+    else:
+        assert abs(m.zh_dbz - m.zv_dbz) < 0.3
+    # PSD curve shape
+    assert len(r.nd.d_mm) == len(r.nd.n_d) == 199
+
+
+def test_hail_is_near_isotropic():
+    """Hail at axis_ratio 0.99 should give near-zero Zdr."""
+    r = compute(dm=3.0, log_nw=3.0, mu=0.0, band="S", canting_std_deg=0.0, precip="hail")
+    assert abs(r.metrics.zdr_db) < 0.2
+
+
+def test_rain_has_positive_zdr():
+    """Rain drops are oblate → Zdr > 0."""
+    r = compute(dm=3.0, log_nw=3.0, mu=0.0, band="S", canting_std_deg=0.0, precip="rain")
+    assert r.metrics.zdr_db > 0.5
+
+
+def test_api_health(client):
+    resp = client.get("/api/health")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["status"] == "ok"
+    assert "rustmatrix" in body
+
+
+def test_api_compute(client):
+    resp = client.post(
+        "/api/compute",
+        json={"dm": 2.0, "log_nw": 3.0, "mu": 0.0, "band": "S",
+              "canting_std_deg": 0.0, "precip": "rain"},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+    assert "metrics" in body and "nd" in body
+    assert len(body["nd"]["d_mm"]) == 199
+
+
+def test_api_rejects_out_of_range(client):
+    resp = client.post(
+        "/api/compute",
+        json={"dm": 99.0, "log_nw": 3.0, "mu": 0.0, "band": "S",
+              "canting_std_deg": 0.0, "precip": "rain"},
+    )
+    assert resp.status_code == 422
+
+
+def test_canting_reduces_zdr():
+    """Wider canting PDF should reduce |Zdr| toward zero."""
+    r0 = compute(dm=3.0, log_nw=3.0, mu=0.0, band="S", canting_std_deg=0.0, precip="rain")
+    r1 = compute(dm=3.0, log_nw=3.0, mu=0.0, band="S", canting_std_deg=20.0, precip="rain")
+    assert r1.metrics.zdr_db < r0.metrics.zdr_db

frontend/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/icon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Interactive polarimetric radar PSD explorer — rustmatrix + CLIMAS" />
+    <title>myPSD — polarimetric radar PSD explorer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "mypsd-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "plotly.js-basic-dist-min": "^2.35.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-plotly.js": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@types/react-plotly.js": "^2.6.3",
+    "@vitejs/plugin-react": "^4.3.3",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10"
+  }
+}

frontend/src/App.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useRef, useState } from 'react'
+import { Controls, type ControlsState } from './components/Controls'
+import { PSDPlot } from './components/PSDPlot'
+import { MetricsTable } from './components/MetricsTable'
+import { compute } from './api'
+import type { ComputeResponse } from './types'
+
+const INITIAL: ControlsState = {
+  dm: 2.0,
+  logNw: 3.0,
+  mu: 0,
+  band: 'S',
+  cantingStd: 0,
+  precip: 'rain',
+}
+
+export default function App() {
+  const [state, setState] = useState<ControlsState>(INITIAL)
+  const [result, setResult] = useState<ComputeResponse | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+
+  useEffect(() => {
+    // Debounce + abort-in-flight so slider drags don't flood the backend.
+    const controller = new AbortController()
+    abortRef.current?.abort()
+    abortRef.current = controller
+    const id = setTimeout(() => {
+      compute(
+        {
+          dm: state.dm,
+          log_nw: state.logNw,
+          mu: state.mu,
+          band: state.band,
+          canting_std_deg: state.cantingStd,
+          precip: state.precip,
+        },
+        controller.signal,
+      )
+        .then((r) => {
+          setResult(r)
+          setError(null)
+        })
+        .catch((err: unknown) => {
+          if (err instanceof Error && err.name !== 'AbortError') {
+            setError(err.message)
+          }
+        })
+    }, 150)
+    return () => {
+      clearTimeout(id)
+      controller.abort()
+    }
+  }, [state])
+
+  return (
+    <div className="app">
+      <header className="header">
+        <img src="/logo.svg" alt="myPSD" className="brand" />
+        <div className="subtitle">
+          Normalized gamma PSD · T-matrix via rustmatrix
+        </div>
+        <img src="/climas-icon.png" alt="CLIMAS — University of Illinois" className="climas" />
+      </header>
+
+      <main className="main">
+        <Controls value={state} onChange={setState} />
+        <div className="right">
+          {error && <div className="error">{error}</div>}
+          <PSDPlot nd={result?.nd ?? null} />
+          <MetricsTable metrics={result?.metrics ?? null} />
+        </div>
+      </main>
+
+      <footer className="footer">
+        Based on{' '}
+        <a href="https://github.com/swnesbitt/bokeh-myPSD">bokeh-myPSD</a> ·
+        Scattering by{' '}
+        <a href="https://github.com/swnesbitt/rustmatrix">rustmatrix</a> ·
+        Source at <a href="https://github.com/swnesbitt/myPSD">swnesbitt/myPSD</a>
+      </footer>
+    </div>
+  )
+}

frontend/src/api.ts

@@ -0,0 +1,15 @@
+import type { ComputeRequest, ComputeResponse } from './types'
+
+export async function compute(req: ComputeRequest, signal?: AbortSignal): Promise<ComputeResponse> {
+  const resp = await fetch('/api/compute', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(req),
+    signal,
+  })
+  if (!resp.ok) {
+    const text = await resp.text()
+    throw new Error(`compute failed: ${resp.status} ${text}`)
+  }
+  return resp.json() as Promise<ComputeResponse>
+}

frontend/src/components/Controls.tsx

@@ -0,0 +1,107 @@
+import type { Band, Precip } from '../types'
+
+export interface ControlsState {
+  dm: number
+  logNw: number
+  mu: number
+  band: Band
+  cantingStd: number
+  precip: Precip
+}
+
+interface Props {
+  value: ControlsState
+  onChange: (next: ControlsState) => void
+}
+
+export function Controls({ value, onChange }: Props) {
+  const set = <K extends keyof ControlsState>(k: K, v: ControlsState[K]) =>
+    onChange({ ...value, [k]: v })
+
+  return (
+    <div className="panel controls">
+      <div className="field">
+        <label>
+          Precip type
+        </label>
+        <select
+          value={value.precip}
+          onChange={(e) => set('precip', e.target.value as Precip)}
+        >
+          <option value="rain">rain</option>
+          <option value="hail">hail</option>
+        </select>
+      </div>
+
+      <div className="field">
+        <label>
+          Wavelength
+        </label>
+        <select
+          value={value.band}
+          onChange={(e) => set('band', e.target.value as Band)}
+        >
+          <option value="S">S band (10 cm)</option>
+          <option value="C">C band (5 cm)</option>
+          <option value="X">X band (3 cm)</option>
+        </select>
+      </div>
+
+      <div className="field">
+        <label>
+          Dm (mm) <span className="value">{value.dm.toFixed(1)}</span>
+        </label>
+        <input
+          type="range"
+          min={0.5}
+          max={8.0}
+          step={0.1}
+          value={value.dm}
+          onChange={(e) => set('dm', parseFloat(e.target.value))}
+        />
+      </div>
+
+      <div className="field">
+        <label>
+          log₁₀ Nw (mm⁻¹ m⁻³) <span className="value">{value.logNw.toFixed(2)}</span>
+        </label>
+        <input
+          type="range"
+          min={0.5}
+          max={6.0}
+          step={0.1}
+          value={value.logNw}
+          onChange={(e) => set('logNw', parseFloat(e.target.value))}
+        />
+      </div>
+
+      <div className="field">
+        <label>
+          μ (shape) <span className="value">{value.mu.toFixed(0)}</span>
+        </label>
+        <input
+          type="range"
+          min={-3}
+          max={80}
+          step={1}
+          value={value.mu}
+          onChange={(e) => set('mu', parseFloat(e.target.value))}
+        />
+      </div>
+
+      <div className="field">
+        <label>
+          Canting σ (deg) <span className="value">{value.cantingStd.toFixed(0)}</span>
+        </label>
+        <input
+          type="range"
+          min={0}
+          max={40}
+          step={4}
+          value={value.cantingStd}
+          onChange={(e) => set('cantingStd', parseFloat(e.target.value))}
+        />
+      </div>
+    </div>
+  )
+}

frontend/src/components/MetricsTable.tsx

@@ -0,0 +1,51 @@
+import type { Metrics } from '../types'
+
+interface Props {
+  metrics: Metrics | null
+}
+
+function fmt(v: number, digits = 3): string {
+  if (!Number.isFinite(v)) return '—'
+  if (Math.abs(v) !== 0 && (Math.abs(v) < 1e-2 || Math.abs(v) >= 1e4)) {
+    return v.toExponential(2)
+  }
+  return v.toFixed(digits)
+}
+
+export function MetricsTable({ metrics }: Props) {
+  const rows: Array<[string, string]> = metrics
+    ? [
+        ['Zh (dBZ)', fmt(metrics.zh_dbz, 2)],
+        ['Zv (dBZ)', fmt(metrics.zv_dbz, 2)],
+        ['Zdr (dB)', fmt(metrics.zdr_db, 3)],
+        ['LDR (dB)', fmt(metrics.ldr_db, 2)],
+        ['ρ_hv', fmt(metrics.rho_hv, 5)],
+        ['δ_hv (deg)', fmt(metrics.delta_deg, 3)],
+        ['Kdp (° km⁻¹)', fmt(metrics.kdp_deg_per_km, 4)],
+        ['Ah (dB km⁻¹)', fmt(metrics.ah_db_per_km, 4)],
+        ['Adr (dB km⁻¹)', fmt(metrics.adr_db_per_km, 5)],
+        ['NT (m⁻³)', fmt(metrics.nt_per_m3, 2)],
+        ['LWC (g m⁻³)', fmt(metrics.lwc_g_per_m3, 4)],
+      ]
+    : []
+
+  return (
+    <div className="panel">
+      <h3 style={{ margin: '0 0 10px', fontSize: 16 }}>Polarimetric metrics</h3>
+      {metrics ? (
+        <table className="table">
+          <tbody>
+            {rows.map(([label, v]) => (
+              <tr key={label}>
+                <th>{label}</th>
+                <td>{v}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      ) : (
+        <div style={{ color: '#5a6578' }}>Computing…</div>
+      )}
+    </div>
+  )
+}

frontend/src/components/PSDPlot.tsx

@@ -0,0 +1,51 @@
+// Use the lean 'basic' Plotly bundle (~1 MB instead of ~3 MB) — a line plot
+// doesn't need 3D, maps, or statistical chart types.
+import createPlotlyComponent from 'react-plotly.js/factory'
+// @ts-expect-error plotly.js-basic-dist-min has no types
+import Plotly from 'plotly.js-basic-dist-min'
+import type { NDCurve } from '../types'
+
+const Plot = createPlotlyComponent(Plotly)
+
+interface Props {
+  nd: NDCurve | null
+}
+
+export function PSDPlot({ nd }: Props) {
+  const data = nd
+    ? [{
+        x: nd.d_mm,
+        y: nd.n_d,
+        type: 'scatter' as const,
+        mode: 'lines' as const,
+        line: { color: '#1f4e79', width: 3 },
+        name: 'N(D)',
+        hovertemplate: 'D = %{x:.2f} mm<br>N(D) = %{y:.3e} mm⁻¹ m⁻³<extra></extra>',
+      }]
+    : []
+
+  return (
+    <div className="panel">
+      <Plot
+        data={data}
+        layout={{
+          title: { text: 'Particle size distribution' },
+          xaxis: { title: { text: 'Particle diameter (mm)' }, range: [0, 10] },
+          yaxis: {
+            title: { text: 'N(D) (mm⁻¹ m⁻³)' },
+            type: 'log',
+            range: [-1, 6],
+          },
+          margin: { t: 40, b: 50, l: 70, r: 20 },
+          height: 380,
+          plot_bgcolor: '#f7f9fc',
+          paper_bgcolor: '#ffffff',
+          font: { family: 'system-ui, sans-serif' },
+        }}
+        config={{ displaylogo: false, responsive: true }}
+        style={{ width: '100%' }}
+        useResizeHandler
+      />
+    </div>
+  )
+}

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import './styles.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

frontend/src/styles.css

@@ -0,0 +1,123 @@
+:root {
+  --climas-blue: #1f4e79;
+  --climas-accent: #4ea8dc;
+  --bg: #f7f9fc;
+  --panel: #ffffff;
+  --border: #d9dfe9;
+  --text: #1c2230;
+  --muted: #5a6578;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  color: var(--text);
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); }
+
+.app {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  padding: 14px 24px;
+  background: #eef2f8;
+  color: var(--text);
+  border-bottom: 3px solid var(--climas-accent);
+}
+.header .brand { height: 52px; width: auto; }
+.header .subtitle {
+  font-size: 13px;
+  color: var(--muted);
+  flex: 1;
+  border-left: 1px solid #cfd6e2;
+  padding-left: 16px;
+  line-height: 1.4;
+}
+.header .climas { height: 42px; width: auto; }
+
+.main {
+  display: grid;
+  grid-template-columns: 300px 1fr;
+  gap: 20px;
+  padding: 20px;
+  align-items: start;
+}
+@media (max-width: 900px) {
+  .main { grid-template-columns: 1fr; }
+}
+
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.controls label {
+  display: block;
+  font-size: 13px;
+  font-weight: 500;
+  margin-bottom: 4px;
+  color: var(--muted);
+}
+.controls .field { margin-bottom: 14px; }
+.controls input[type="range"] { width: 100%; }
+.controls select {
+  width: 100%;
+  padding: 6px 8px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: #fff;
+}
+.controls .value {
+  display: inline-block;
+  float: right;
+  font-variant-numeric: tabular-nums;
+  color: var(--text);
+  font-weight: 600;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 14px;
+}
+.table th, .table td {
+  padding: 6px 10px;
+  text-align: left;
+  border-bottom: 1px solid var(--border);
+  font-variant-numeric: tabular-nums;
+}
+.table th {
+  background: #eef2f8;
+  font-weight: 600;
+  width: 55%;
+}
+
+.right {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.footer {
+  margin-top: auto;
+  padding: 10px 24px;
+  font-size: 12px;
+  color: var(--muted);
+  border-top: 1px solid var(--border);
+}
+.footer a { color: var(--climas-blue); }
+
+.error {
+  color: #b3261e;
+  background: #fde7e7;
+  border: 1px solid #f5b5b5;
+  padding: 8px 12px;
+  border-radius: 4px;
+  font-size: 13px;
+}

frontend/src/types.ts

@@ -0,0 +1,35 @@
+export type Band = 'S' | 'C' | 'X'
+export type Precip = 'rain' | 'hail'
+
+export interface ComputeRequest {
+  dm: number
+  log_nw: number
+  mu: number
+  band: Band
+  canting_std_deg: number
+  precip: Precip
+}
+
+export interface Metrics {
+  zh_dbz: number
+  zv_dbz: number
+  zdr_db: number
+  ldr_db: number
+  rho_hv: number
+  delta_deg: number
+  kdp_deg_per_km: number
+  ah_db_per_km: number
+  adr_db_per_km: number
+  nt_per_m3: number
+  lwc_g_per_m3: number
+}
+
+export interface NDCurve {
+  d_mm: number[]
+  n_d: number[]
+}
+
+export interface ComputeResponse {
+  metrics: Metrics
+  nd: NDCurve
+}

frontend/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

frontend/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  // Production build lands directly inside FastAPI's static/ dir so uvicorn
+  // serves the SPA at the same origin as /api.
+  build: {
+    outDir: '../backend/app/static',
+    emptyOutDir: true,
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': 'http://localhost:8000',
+    },
+  },
+})