Mountain Waves — deploy to Hugging Face Space

Rust + Python/Dash port of Hart (1995) 2-D mountain-wave model.
Full development history at github.com/swnesbitt/mountainwaves-bannonhart.

.gitignore

@@ -0,0 +1,33 @@
+# Rust build artifacts
+/target/
+
+# Python virtual envs
+.venv/
+venv/
+env/
+
+# Python bytecode / caches
+__pycache__/
+*.py[co]
+*.egg-info/
+.pytest_cache/
+
+# Compiled Rust extensions (platform-specific — we rebuild in CI / Docker)
+python/mountain_waves/_core*.so
+python/mountain_waves/_core*.pyd
+python/mountain_waves/_core*.dylib
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+bluesky_post.md
+linkedin_post.md
+target/
+*.so
+*.dylib
+*.rlib
+*.rmeta
+__pycache__/
+*.pyc

Cargo.lock

@@ -0,0 +1,323 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.185"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "mountain_waves_core"
+version = "0.1.0"
+dependencies = [
+ "ndarray",
+ "num-complex",
+ "numpy",
+ "pyo3",
+ "rayon",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edb929bc0da91a4d85ed6c0a84deaa53d411abfb387fc271124f91bf6b89f14e"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "mountain_waves_core"
+version = "0.1.0"
+edition = "2021"
+description = "Rust core for the Mountain Waves interactive visualization tool. Port of Robert E. Hart's 1995 MATLAB mountain-wave model (https://moe.met.fsu.edu/~rhart/mtnwave.html)."
+authors = [
+    "Robert E. Hart <rhart@fsu.edu> (original MATLAB model, 1995)",
+    "Mountain Waves port (Rust + Dash)",
+]
+license = "MIT"
+
+[lib]
+name = "_core"
+# cdylib is required for a PyO3 Python extension module.
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.22", features = ["extension-module"] }
+numpy = "0.22"
+ndarray = "0.16"
+num-complex = "0.4"
+rayon = "1.10"
+
+[profile.release]
+opt-level = 3
+lto = "thin"
+codegen-units = 1

Dockerfile

@@ -0,0 +1,82 @@
+# syntax=docker/dockerfile:1.6
+#
+# Hugging Face Space Docker build for Mountain Waves.
+#
+# Two-stage build: the first stage has the Rust toolchain and produces a
+# manylinux-ish wheel of the compiled extension; the second stage is a slim
+# Python runtime that just installs the wheel + deps. This keeps the final
+# image under ~400 MB without needing cargo at runtime.
+#
+# HF Spaces routes external traffic to whatever port the container listens
+# on via `app_port` in README.md — we use 7860 (the HF default).
+
+# ---------- build stage: compile the Rust extension into a wheel ----------
+# rayon 1.12 needs rustc ≥ 1.80; pin a modern stable image so the MSRV of the
+# transitive crate graph (rayon, pyo3, numpy) stays satisfied.
+FROM rust:1.82-slim AS build
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip python3-venv python3-dev \
+        build-essential pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python3 -m pip install --break-system-packages "maturin==1.7.*"
+
+WORKDIR /src
+COPY Cargo.toml Cargo.lock pyproject.toml README.md ./
+COPY src ./src
+COPY python ./python
+
+# Build a release wheel. -i python3 pins against the build image's 3.11
+# interpreter; the runtime stage uses the same major.minor so the abi3
+# wheel loads cleanly.
+RUN maturin build --release --out /wheels -i python3
+
+
+# ---------- runtime stage: Python 3.11 slim + app + wheel ----------
+FROM python:3.11-slim
+
+# libgomp1 is the OpenMP runtime rayon links against; eccodes pulls its own
+# shared libs in via the eccodeslib wheel, so nothing else is needed.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install the compiled Rust wheel + all runtime deps. Deps are listed
+# explicitly here instead of using `pip install .` so we don't drag maturin
+# and the build system into the runtime image.
+COPY --from=build /wheels /wheels
+RUN pip install --no-cache-dir /wheels/*.whl \
+ && pip install --no-cache-dir \
+        "numpy>=1.23" \
+        "scipy>=1.10" \
+        "dash>=2.16" \
+        "plotly>=5.20" \
+        "boto3>=1.28" \
+        "xarray>=2023.1" \
+        "cfgrib>=0.9.10" \
+        "eccodes>=2.37" \
+        "eccodeslib>=2.46"
+
+# HF Spaces runs the container as uid 1000 with /tmp as the only writable
+# directory by default. Cache dirs that libraries write to (plotly, boto3,
+# xdg) need to live somewhere the process can actually create files.
+ENV HOME=/tmp \
+    XDG_CACHE_HOME=/tmp/.cache \
+    MPLCONFIGDIR=/tmp/.mplconfig
+
+# Note: we intentionally do NOT copy python/ into the runtime image. The wheel
+# built in the previous stage contains both the pure-Python source and the
+# compiled _core*.so, installed into site-packages. If we also copied the
+# source tree here, run.py's sys.path.insert(0, "./python") would shadow the
+# wheel's copy with a _core-less source tree, and `from . import _core` would
+# fail with "partially initialized module" (HF deploy 2026-04-18).
+COPY run.py ./run.py
+# README.md is rendered inside the app's "Theory & About" modal at runtime.
+# Without this copy the modal falls back to a short placeholder.
+COPY README.md ./README.md
+
+EXPOSE 7860
+CMD ["python", "run.py", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,297 @@
+---
+title: Mountain Waves
+emoji: 🏔️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: Interactive 2-D mountain-wave visualizer (Rust + Dash)
+---
+
+# Mountain Waves
+
+An interactive **2-D linear mountain-wave visualizer** with a Rust compute
+core and a Python/Dash front end. Live web demo:
+<https://huggingface.co/spaces/snesbitt/mountain-waves>.
+
+## Attribution
+
+This project is a port and extension of the interactive MATLAB mountain-wave
+model originally written by **Dr. Robert E. (Bob) Hart** (currently at Florida
+State University) as a Fall 1995 seminar project for Meteo 574 at Penn State
+University under Dr. Peter Bannon. The numerical method, user-interface
+design, and example cases all originate from Hart's work.
+
+> Hart, R. E., 1995: *Interactive Model for 2-D Mountain Wave Visualization.*
+> Penn State Meteo 574 seminar project.
+> Documentation and MATLAB source: <https://moe.met.fsu.edu/~rhart/mtnwave.html>
+> Contact: `rhart@fsu.edu`
+
+Bob Hart last updated the MATLAB package in March 2018 for newer MATLAB
+versions. This port, by **Steve Nesbitt** (CliMAS, University of Illinois
+Urbana–Champaign), preserves the physics and the MATLAB user-experience
+conventions while replacing MATLAB-specific glue with a Rust compute core
+and a browser-based Dash UI. Any bugs in the port are the port's fault,
+not the original model's.
+
+## Theory
+
+### Problem setup
+
+Steady, 2-D, linearized, Boussinesq flow over a smooth obstacle. A mean-state
+horizontal wind `U(z)` and potential temperature `θ̄(z)` are prescribed; the
+solver returns the stationary perturbation fields `(w', u', p', θ')` forced
+by a mountain shape `h(x)`.
+
+### The Taylor–Goldstein equation
+
+Linearizing the Boussinesq momentum, continuity, and thermodynamic equations
+about the mean state and taking a single horizontal Fourier mode
+`w'(x, z) = Re{ŵ(k, z) · exp(ikx)}` reduces the full PDE system to a single
+ODE in `z` per horizontal wavenumber `k`:
+
+```
+∂²ŵ/∂z²  +  [ l²(z) − k² ] ŵ  =  0
+```
+
+This is the Taylor–Goldstein equation. The coefficient `l²(z)` is the
+**Scorer parameter**:
+
+```
+l²(z)  =  N²(z) / U²(z)  −  (1/U(z)) · d²U/dz²
+```
+
+with `N² = (g/θ̄) · dθ̄/dz` the Brunt–Väisälä frequency squared. `l²` can
+go negative — unstable stratification (`N² < 0`) or a locally positive
+shear curvature (`d²U/dz² > 0`) can flip its sign, in which case every
+wavenumber is evanescent at that height.
+
+### Propagating vs. evanescent, and the Scorer condition
+
+Within a layer of approximately uniform `l²`:
+
+* `l² > k²` — `ŵ` is oscillatory; the wave propagates vertically.
+* `l² < k²` — `ŵ` is evanescent; the physical branch decays with height.
+
+A configuration with `l²_lower > l²_upper` admits a band of intermediate
+wavenumbers that propagate in the lower layer but are evanescent aloft.
+These partially reflect at the transition, are trapped between the surface
+and the aloft "lid," and interfere downstream to produce the classic
+resonant **lee-wave train** (Scorer 1949).
+
+### Two-layer analytic solver
+
+Each layer has uniform `L`, so `ŵ` is a linear combination of upward and
+downward modes per layer. Three conditions close the system:
+
+1. **Surface:** `ŵ(0, k) = ikU(0) ĥ(k)` — the linearized kinematic
+   boundary condition `w' = U · ∂h/∂x` for a stationary obstacle of shape
+   `h(x)` with Fourier transform `ĥ(k)`.
+2. **Interface (`z = H`):** continuity of `ŵ` and `∂ŵ/∂z`.
+3. **Top:** Sommerfeld radiation — above the interface, only the
+   upward-energy-propagating branch is retained.
+
+This gives closed-form reflection and transmission coefficients that the
+Rust core evaluates analytically for every `k` in parallel. It is a direct
+port of Hart's `tlwplot.m`.
+
+### Multi-layer propagator-matrix solver
+
+For arbitrary `U(z), θ̄(z)` the atmosphere is discretized into a fine stack
+of sub-layers, each with its own locally-uniform `l²_j`. Inside each
+sub-layer the exact analytic solution is still available (oscillatory if
+`l²_j > k²`, evanescent if `l²_j < k²`). A 2×2 transfer matrix propagates
+`(ŵ, ∂ŵ/∂z)` between sub-layer interfaces; sweeping bottom-to-top yields the
+full vertical structure per `k`. The top boundary is again a radiation
+condition, here expressed in a `(σ, ŵ)` basis that stays well-conditioned
+when `l² < k²` aloft (pure decay).
+
+### Synthesis: inverse Fourier transform
+
+After solving per-`k`, the physical fields are reconstructed by trapezoidal
+inverse Fourier transform over the wavenumber grid:
+
+```
+w'(x, z)  =  ∫ ŵ(k, z) · ĥ(k) · exp(ikx) dk  +  c.c.
+```
+
+The horizontal wind perturbation `u'` is recovered from linearized
+continuity `ik û + ∂ŵ/∂z = 0` directly in spectral space:
+
+```
+u'(x, z)  =  ∫  [ −(i/k) · ∂ŵ/∂z ]  ·  ĥ(k) · exp(ikx) dk  +  c.c.
+```
+
+evaluated on the same wavenumber grid as `w'`. Both fields are displayed in
+the UI as colored contour maps side-by-side.
+
+### Linearized streamlines
+
+For small perturbations, a streamline originating at upstream height `z₀`
+is vertically displaced by
+
+```
+δz(x, z₀)  =  (1 / U(z₀)) · ∫₋∞ˣ w'(x', z₀) dx'
+```
+
+The solver integrates this along `x` for a set of evenly spaced release
+heights to produce the overlay. When `U` varies with height, the
+per-streamline advection speed is `U(z₀)`, not a single surface value.
+
+### What linear theory cannot capture
+
+This is a small-amplitude, inviscid, non-rotating, 2-D model. **Downslope
+windstorms, hydraulic jumps, wave breaking, and critical-level nonlinear
+amplification are fundamentally nonlinear phenomena and are not captured
+here.** The "Near-downslope" preset in the two-layer mode approaches that
+regime as a forcing-parameter lookup but will systematically underpredict
+the surface winds observed in real events.
+
+## What's in the port
+
+1. **Two-layer analytic solver** — direct port of Hart's `tlwplot.m`.
+   Uniform Scorer parameter in each layer, analytic reflection /
+   transmission at the interface, Fourier summation over horizontal
+   wavenumbers.
+2. **Multi-layer profile solver** — takes arbitrary `θ̄(z)` and `u(z)` and
+   solves the Taylor–Goldstein ODE per wavenumber via the propagator-matrix
+   sweep described above.
+3. **Interactive profile editor** — drag control points on `θ̄(z)` and
+   `u(z)` graphs to prescribe arbitrary profiles; results re-render on the
+   next *Analyze flow* click.
+4. **u′ heatmap** — rendered alongside `w'` so you can see where the wave
+   train speeds up or slows the low-level flow.
+5. **Latitude slider** — exposes the Coriolis parameter so the Rossby-number
+   readout reflects the user's chosen latitude (the MATLAB original
+   hard-coded the pole).
+6. **HRRR initialization** (Profile tab) — fetch the nearest HRRR analysis
+   column from NOAA's public AWS bucket to seed `θ̄(z)` and `u(z)` from a
+   real atmosphere, then drag the gold circles to edit further.
+
+## Layout
+
+```
+Mountain Waves/
+├── Cargo.toml                       # Rust crate manifest
+├── pyproject.toml                   # maturin build + project metadata
+├── Dockerfile                       # Hugging Face Spaces build
+├── src/lib.rs                       # Rust compute core (PyO3 bindings)
+├── python/mountain_waves/
+│   ├── __init__.py
+│   ├── app.py                       # Dash app entry point
+│   ├── reference.py                 # pure-Python reference solver (fallback)
+│   ├── profile.py                   # θ(z)/u(z) → Scorer parameter utilities
+│   ├── hrrr.py                      # HRRR column fetcher (AWS)
+│   └── solver.py                    # picks Rust or Python backend
+├── run.py                           # launcher: `uv run python run.py`
+├── validate.py                      # compares Rust vs. reference vs. MATLAB
+└── tlwmenu.m / tlwplot.m / stream.m # Hart's original MATLAB sources
+```
+
+## Quick start (uv)
+
+[`uv`](https://docs.astral.sh/uv/) is a fast Python package + environment
+manager. One-shot setup from the project root:
+
+```bash
+# 1. Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+#   or: brew install uv     (macOS)
+#   or: pipx install uv
+
+# 2. Create a virtual environment pinned to Python 3.11
+uv venv --python 3.11
+source .venv/bin/activate          # or `.venv\Scripts\activate` on Windows
+
+# 3. Install Python dependencies from pyproject.toml
+uv sync
+
+# 4. (Optional, for the Rust backend) install the Rust toolchain
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# 5. Build the Rust extension into the active venv
+uv run maturin develop --release --uv
+
+# 6. Launch the web UI
+uv run python run.py               # http://127.0.0.1:8050
+```
+
+`uv sync` reads `pyproject.toml` and installs every runtime dependency
+(`numpy`, `scipy`, `dash`, `plotly`, plus the HRRR stack `boto3`, `xarray`,
+`cfgrib`, `eccodes`, `eccodeslib`). `maturin develop --uv` installs the
+compiled extension into the uv-managed environment; `--release` enables
+optimizations (typically 20×–30× faster than the pure-Python fallback).
+
+Dev extras (`pytest` etc.):
+
+```bash
+uv sync --extra dev
+```
+
+### Pure-Python fallback (no Rust toolchain needed)
+
+```bash
+uv venv --python 3.11
+source .venv/bin/activate
+uv sync
+uv run python run.py
+```
+
+The launcher detects the missing Rust extension and transparently uses
+`python/mountain_waves/reference.py`. Every numerical result matches the
+Rust core within floating-point tolerance; it just runs slower.
+
+### pip alternative
+
+```bash
+pip install -e .            # installs deps; maturin builds _core if rustc is found
+python run.py
+```
+
+## Validation
+
+```bash
+uv run python validate.py
+```
+
+Runs the solver on three canonical cases (uniform atmosphere, trapped lee
+waves, and a profile-based approximation of the trapped case) and asserts
+reasonable amplitudes. When both the Rust and Python backends are built
+it also cross-checks them element-wise.
+
+## Docker / Hugging Face Space
+
+The `Dockerfile` is a two-stage build tuned for Hugging Face Spaces
+(SDK `docker`, port 7860). Stage 1 builds a release wheel of the Rust
+extension on `rust:1.82-slim`; stage 2 installs that wheel onto
+`python:3.11-slim` plus the runtime Python dependencies. The live Space
+is at <https://huggingface.co/spaces/snesbitt/mountain-waves>.
+
+## References
+
+* Scorer, R. S., 1949: *Theory of waves in the lee of mountains*.
+  Q. J. R. Meteorol. Soc., **75**, 41–56.
+* Booker, J. R., and F. P. Bretherton, 1967: *The critical layer for
+  internal gravity waves in a shear flow.* J. Fluid Mech., **27**,
+  513–539. Motivates the "Critical layer at 2 km" preset: wave
+  attenuation across `U = 0` scales as `exp(−2π √(Ri − 1/4))` for
+  `Ri > 1/4`.
+* Durran, D. R., 1986: *Mountain Waves*, in *Mesoscale Meteorology and
+  Forecasting*, American Meteorological Society, pp. 472–492.
+* Hart, R. E., 1995: *Interactive Model for 2-D Mountain Wave
+  Visualization.* Penn State Meteo 574 seminar project.
+* Doyle, J. D., and D. R. Durran, 2002: *The dynamics of mountain-wave-
+  induced rotors.* J. Atmos. Sci., **59**, 186–201. Observational and
+  numerical context for the wind-reversal preset; the T-REX / Sierra
+  Rotors campaign (Grubišić et al. 2008, BAMS **89**, 1513–1533)
+  documented the atmospheric structures this preset is meant to
+  caricature.
+
+## License
+
+Original MATLAB model and physics © Robert E. Hart. The Rust + Python
+port is provided for research and teaching purposes under the MIT license.
+If you use this tool in published work, please cite Hart (1995) and the
+[FSU documentation page](https://moe.met.fsu.edu/~rhart/mtnwave.html).

pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "mountain_waves"
+version = "0.1.0"
+description = "Interactive 2-D mountain-wave model with Rust core and Dash front end. Port of Robert E. Hart's 1995 MATLAB mountain-wave tool."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Mountain Waves port (Rust + Dash)" }]
+maintainers = [{ name = "Mountain Waves port (Rust + Dash)" }]
+license = { text = "MIT" }
+keywords = ["meteorology", "mountain-waves", "atmospheric-science", "taylor-goldstein", "scorer-parameter"]
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.10",
+    "dash>=2.16",
+    "plotly>=5.20",
+    # HRRR profile fetcher (Profile tab "Initialize from HRRR").
+    # cfgrib needs the eccodes C library. Rather than requiring a system
+    # install (brew install eccodes / apt install libeccodes-dev) we pull
+    # it in from PyPI only. Current story (verified on PyPI, 2026-04):
+    #   - `cfgrib` depends on `eccodes` (Python CFFI bindings, pure-Python
+    #     wheel — no binary).
+    #   - `eccodes` depends on `findlibs`, which looks for `libeccodes` in
+    #     an installed Python package named `eccodeslib` first.
+    #   - `eccodeslib` is ECMWF's new official binary-wheel package
+    #     (macOS 13+ arm64/x86_64, manylinux_2_28 x86_64/aarch64, cp310..cp314).
+    #   - `ecmwflibs` is the older bundle; stale since 2024 and missing
+    #     cp312+. We keep it only as a Windows fallback since `eccodeslib`
+    #     has no Windows wheels.
+    # Result: `uv sync` / `pip install -e .` is enough on macOS and Linux.
+    "boto3>=1.28",
+    "xarray>=2023.1",
+    "cfgrib>=0.9.10",
+    "eccodes>=2.37",
+    "eccodeslib>=2.46 ; sys_platform != 'win32'",
+    "ecmwflibs>=0.6 ; sys_platform == 'win32'",
+]
+
+[project.urls]
+"Original model (Hart 1995)" = "https://moe.met.fsu.edu/~rhart/mtnwave.html"
+
+[project.optional-dependencies]
+dev = ["maturin>=1.7", "pytest>=7"]
+
+[tool.maturin]
+# Mixed layout: Rust crate at project root, Python package under python/.
+python-source = "python"
+module-name = "mountain_waves._core"
+features = ["pyo3/extension-module"]

python/mountain_waves/__init__.py

@@ -0,0 +1,26 @@
+"""Interactive 2-D mountain-wave model.
+
+Python/Rust port of Dr. Robert E. (Bob) Hart's 1995 MATLAB mountain-wave
+model (``tlwplot.m`` / ``tlwmenu.m`` / ``stream.m``). The numerical scheme,
+user-interface layout, and example cases originate from Hart's Penn State
+Meteo 574 seminar project. Documentation and MATLAB sources:
+https://moe.met.fsu.edu/~rhart/mtnwave.html (contact: ``rhart@fsu.edu``).
+
+Top-level package. Numerical entry points live in :mod:`mountain_waves.solver`
+which selects the Rust extension if available and otherwise falls back to
+the pure-Python reference implementation.
+"""
+
+from .solver import (
+    compute_two_layer,
+    compute_from_profile,
+    streamlines,
+    backend_name,
+)
+
+__all__ = [
+    "compute_two_layer",
+    "compute_from_profile",
+    "streamlines",
+    "backend_name",
+]

python/mountain_waves/app.py

@@ -0,0 +1,1996 @@
+"""Interactive Dash front end for the Mountain Waves model.
+
+This UI is the browser-based counterpart to the original MATLAB menu in
+Dr. Robert E. (Bob) Hart's 1995 mountain-wave tool (``tlwmenu.m``). Hart's
+slider layout, example cases, and readouts (Scorer condition, Rossby
+number, dimensionless mountain height) guided the design here. Original
+model and documentation: https://moe.met.fsu.edu/~rhart/mtnwave.html.
+
+Two solver modes are exposed:
+
+* **Two-layer** — sliders for the original MATLAB parameters
+  (surface wind, upper/lower Scorer, interface height, mountain geometry,
+  domain, spectrum).
+* **Profile** — drag control points on an ``u(z)`` graph and a
+  ``theta(z)`` graph to prescribe arbitrary profiles. The app converts
+  these to a Scorer parameter profile and runs the multi-layer solver.
+
+Both modes render streamline analysis and a vertical-velocity contour
+plot side-by-side, along with diagnostic readouts (Scorer condition,
+Rossby number, solver backend).
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from pathlib import Path
+from typing import Tuple
+
+import numpy as np
+import plotly.graph_objects as go
+from dash import Dash, Input, Output, State, ctx, dcc, html, no_update
+
+from . import solver
+from .profile import (
+    brunt_vaisala,
+    default_profile_heights,
+    default_theta_profile,
+    default_u_profile,
+    scorer_from_profile,
+)
+
+
+OMEGA = 7.292e-5
+
+
+# ---------------------------------------------------------------------------
+# README loader (for the Theory & About modal)
+# ---------------------------------------------------------------------------
+#
+# The "Theory & About" link in the header opens a modal that renders the
+# project README.md as markdown. The README lives at the project root in the
+# dev layout, but in the Docker runtime the installed package is in
+# site-packages while README.md is at /app/README.md (copied there by the
+# Dockerfile). We probe both and fall back to a short placeholder.
+
+def _load_readme_markdown() -> str:
+    """Return README.md with the HF YAML frontmatter stripped.
+
+    Candidates are tried in order of specificity: next to the project root
+    (dev), next to the launcher at /app (Docker), and finally cwd. The HF
+    Spaces metadata block at the top (between leading ``---`` markers) is
+    not useful to end users and is stripped before returning.
+    """
+    here = Path(__file__).resolve()
+    candidates = [
+        here.parents[2] / "README.md",   # <repo>/python/mountain_waves/app.py → <repo>/README.md
+        Path("/app/README.md"),          # Docker runtime
+        Path.cwd() / "README.md",        # last-ditch
+    ]
+    for p in candidates:
+        try:
+            if p.is_file():
+                text = p.read_text(encoding="utf-8")
+                break
+        except OSError:
+            continue
+    else:
+        return (
+            "# Mountain Waves\n\n"
+            "*README.md could not be located at runtime — see "
+            "[the project page](https://huggingface.co/spaces/snesbitt/mountain-waves).*"
+        )
+    # Strip leading YAML frontmatter (HF Spaces metadata).
+    if text.startswith("---\n"):
+        close = text.find("\n---\n", 4)
+        if close != -1:
+            text = text[close + 5:]
+    return text
+
+
+_README_MD = _load_readme_markdown()
+LATIT_RAD_DEFAULT = math.radians(45.0)
+
+
+# ---------------------------------------------------------------------------
+# Preset scenarios
+# ---------------------------------------------------------------------------
+
+# Default two-layer slider values shown when the page first loads. Also
+# what the "Reset to defaults" button in the Actions column restores.
+# These match the initial slider-default arguments in ``_two_layer_controls``
+# and coincide with the "trapped" preset — Hart's Example 2 — which is the
+# most instructive starting point.
+TWO_LAYER_DEFAULTS = {
+    "U": 20.0,
+    "L_upper": 4.0,
+    "L_lower": 10.0,
+    "H": 3.5,
+    "mtn_h": 0.5,
+    "mtn_a": 2.5,
+    "xdom": 40.0,
+    "zdom": 10.0,
+    "mink_k": 0,
+    "maxk_k": 30,
+}
+
+
+PRESETS = {
+    "uniform": {
+        "label": "Uniform atmosphere (Example 1)",
+        "U": 20.0,
+        "L_upper": 4.0,
+        "L_lower": 4.0,
+        "H": 3.5,
+        "mtn_h": 0.5,
+        "mtn_a": 2.5,
+        "xdom": 40.0,
+        "zdom": 10.0,
+        "mink_k": 0,
+        "maxk_k": 30,
+    },
+    "trapped": {
+        "label": "Trapped lee waves (Example 2)",
+        "U": 20.0,
+        "L_upper": 4.0,
+        "L_lower": 10.0,
+        "H": 3.5,
+        "mtn_h": 0.5,
+        "mtn_a": 2.5,
+        "xdom": 40.0,
+        "zdom": 10.0,
+        "mink_k": 0,
+        "maxk_k": 30,
+    },
+    "downslope": {
+        # Not from Hart's MATLAB (he only documented Examples 1 & 2). This is
+        # a "strong lee wave / near-downslope" case kept inside linear theory.
+        # Nh/U = L_lower * ho = 10e-4 * 800 = 0.80, just under the
+        # wave-breaking threshold (~0.85). Scorer condition ≈ 3.0, so a
+        # robust trapped-wave packet forms downstream — the closest the
+        # linear Fourier/Scorer model can get to a real downslope windstorm
+        # without blowing up, which Hart himself flagged in the "Problems"
+        # section of his documentation.
+        "label": "Strong lee waves / near-downslope (linear-theory edge)",
+        "U": 25.0,
+        "L_upper": 3.0,
+        "L_lower": 10.0,
+        "H": 2.5,
+        "mtn_h": 0.8,
+        "mtn_a": 2.5,
+        "xdom": 40.0,
+        "zdom": 10.0,
+        "mink_k": 0,
+        "maxk_k": 30,
+    },
+    "critical_caricature": {
+        # Two-layer caricature of a critical-layer absorber. A real critical
+        # level requires U(z)=0 somewhere — impossible in two-layer mode —
+        # so this preset instead stacks a strongly evanescent upper layer
+        # (L_upper very small) on top of a moderate-Scorer lower layer, with
+        # the interface at 2 km. For a mountain with a=2500 m the dominant
+        # forcing wavenumbers are k ~ 4e-4, which satisfies l_upper^2 < k^2
+        # (evanescent aloft) and l_lower^2 > k^2 (propagating below).
+        # Most upgoing wave energy is reflected at the interface, so the
+        # field above 2 km decays rapidly — a linear-theory analog of
+        # Booker & Bretherton (1967) critical-level absorption. See the
+        # Profile tab for a physically faithful U(z)=0 setup.
+        "label": "Near critical-layer caricature (strong absorption at 2 km)",
+        "U": 20.0,
+        "L_upper": 1.0,
+        "L_lower": 10.0,
+        "H": 2.0,
+        "mtn_h": 0.5,
+        "mtn_a": 2.5,
+        "xdom": 40.0,
+        "zdom": 10.0,
+        "mink_k": 0,
+        "maxk_k": 30,
+    },
+}
+
+
+def _rossby(u: float, a: float, latit_deg: float) -> float:
+    """Return U / (f a) with f evaluated at the given latitude (degrees N)."""
+    lat = math.radians(max(0.0, min(90.0, latit_deg)))
+    f = 2.0 * OMEGA * math.sin(lat)
+    if f == 0.0 or a == 0.0:
+        return float("inf")
+    return u / (f * a)
+
+
+def _two_layer_plots(params, latit_deg: float = 45.0) -> Tuple[go.Figure, go.Figure, go.Figure, float, float]:
+    """Run the two-layer solver and build the streamline, w, and u' figures."""
+    U = params["U"]
+    L_upper = params["L_upper"] * 1e-4
+    L_lower = params["L_lower"] * 1e-4
+    H = params["H"] * 1000.0
+    a = params["mtn_a"] * 1000.0
+    ho = params["mtn_h"] * 1000.0
+    xdom = params["xdom"] * 1000.0
+    zdom = params["zdom"] * 1000.0
+    mink = params["mink_k"] / a
+    maxk = params["maxk_k"] / a
+
+    x, z, w, u_prime = solver.compute_two_layer(
+        L_upper, L_lower, U, H, a, ho, xdom, zdom, mink, maxk, npts=100
+    )
+    lines = solver.streamlines(x, z, U, w, num=10)
+
+    scorer_cond = 4.0 * H * H * (L_lower ** 2 - L_upper ** 2) / (math.pi ** 2)
+    rossby = _rossby(U, a, latit_deg)
+
+    return (*_make_plots(x, z, w, u_prime, lines, H), scorer_cond, rossby)
+
+
+def _profile_plots(params, z_prof, u_prof, theta_prof, latit_deg: float = 45.0) -> Tuple[go.Figure, go.Figure, go.Figure, float, float]:
+    """Run the multi-layer solver from prescribed profiles."""
+    U_surface = float(u_prof[0])
+    a = params["mtn_a"] * 1000.0
+    ho = params["mtn_h"] * 1000.0
+    xdom = params["xdom"] * 1000.0
+    zdom = params["zdom"] * 1000.0
+    mink = params["mink_k"] / a
+    maxk = params["maxk_k"] / a
+
+    x, z, w, u_prime = solver.compute_from_profile(
+        z_prof, u_prof, theta_prof, a, ho, xdom, zdom, mink, maxk, npts=100
+    )
+    # Pass the full u(z) profile (interpolated onto the render grid) so the
+    # streamline tracer uses the local mean wind at each streamline's height.
+    # Using a single U_surface over-amplifies upper streamlines whenever the
+    # profile has shear, because linear theory gives η(x, z₀) = (1/U(z₀)) ·
+    # ∫ w dx'.
+    u_at_z = np.interp(np.asarray(z, dtype=float), np.asarray(z_prof, dtype=float),
+                       np.asarray(u_prof, dtype=float))
+    lines = solver.streamlines(x, z, u_at_z, w, num=10)
+
+    l2 = scorer_from_profile(z_prof, u_prof, theta_prof)
+    # Effective 2-layer diagnostic: split profile at midpoint of z_prof range.
+    mid = z_prof[len(z_prof) // 2]
+    below = l2[z_prof <= mid]
+    above = l2[z_prof > mid]
+    l_lower2 = float(np.mean(np.maximum(below, 0.0))) if below.size else 0.0
+    l_upper2 = float(np.mean(np.maximum(above, 0.0))) if above.size else 0.0
+    scorer_cond = 4.0 * mid ** 2 * (l_lower2 - l_upper2) / (math.pi ** 2)
+
+    rossby = _rossby(U_surface, a, latit_deg)
+
+    # Decorate the streamline plot with a dashed line showing the profile's
+    # dominant interface: the height of maximum |dL^2/dz|.
+    interface_z = None
+    if l2.size > 2:
+        dl = np.abs(np.diff(l2))
+        interface_z = float(z_prof[1:][np.argmax(dl)])
+
+    return (*_make_plots(x, z, w, u_prime, lines, interface_z), scorer_cond, rossby)
+
+
+def _make_plots(x, z, w, u_prime, lines, interface_z):
+    """Build streamline, vertical-velocity, and u' figures from solver output."""
+    x_km = np.asarray(x) / 1000.0
+    z_km = np.asarray(z) / 1000.0
+
+    # Streamline figure — the first streamline traces the mountain surface;
+    # fill it to draw the mountain.
+    stream_fig = go.Figure()
+    mountain_color = "rgb(50, 196, 50)"
+    if lines:
+        xs, ys = lines[0]
+        xs_km = np.asarray(xs) / 1000.0
+        ys_km = np.asarray(ys) / 1000.0
+        stream_fig.add_trace(
+            go.Scatter(
+                x=np.concatenate([xs_km, [x_km[-1], x_km[0], x_km[0]]]),
+                y=np.concatenate([ys_km, [0.0, 0.0, ys_km[0]]]),
+                fill="toself",
+                mode="lines",
+                line=dict(width=1, color=mountain_color),
+                fillcolor=mountain_color,
+                name="Mountain",
+                hoverinfo="skip",
+            )
+        )
+        for xs, ys in lines[1:]:
+            stream_fig.add_trace(
+                go.Scatter(
+                    x=np.asarray(xs) / 1000.0,
+                    y=np.asarray(ys) / 1000.0,
+                    mode="lines",
+                    line=dict(width=1.2, color="white"),
+                    hoverinfo="skip",
+                    showlegend=False,
+                )
+            )
+
+    if interface_z is not None:
+        stream_fig.add_hline(
+            y=interface_z / 1000.0,
+            line=dict(color="magenta", dash="dash", width=1.5),
+            annotation_text="interface",
+            annotation_position="top right",
+            annotation_font_color="magenta",
+        )
+
+    stream_fig.update_layout(
+        title="Streamline Analysis",
+        xaxis_title="x (km)",
+        yaxis_title="height (km)",
+        template="plotly_dark",
+        yaxis=dict(range=[0, z_km[-1]]),
+        xaxis=dict(range=[x_km[0], x_km[-1]]),
+        margin=dict(l=60, r=20, t=50, b=50),
+        height=420,
+    )
+
+    # Vertical-velocity contour. Clip at ±10 m/s like the MATLAB caxis.
+    w_clip = np.clip(w, -10.0, 10.0)
+    w_fig = go.Figure(
+        data=go.Heatmap(
+            x=x_km,
+            y=z_km,
+            z=w_clip,
+            zmin=-10,
+            zmax=10,
+            colorscale="RdBu_r",
+            reversescale=False,
+            colorbar=dict(title="w (m/s)"),
+            zsmooth="best",
+        )
+    )
+    if interface_z is not None:
+        w_fig.add_hline(
+            y=interface_z / 1000.0,
+            line=dict(color="magenta", dash="dash", width=1.5),
+        )
+    w_fig.update_layout(
+        title="Vertical Velocity w (m/s)",
+        xaxis_title="x (km)",
+        yaxis_title="height (km)",
+        template="plotly_dark",
+        margin=dict(l=60, r=20, t=50, b=50),
+        height=420,
+    )
+
+    # Horizontal-wind perturbation u'. Scale symmetrically around zero using
+    # the 98th-percentile magnitude so outlier spikes near the mountain don't
+    # wash out the lee-wave pattern. Use a diverging colormap (PuOr) distinct
+    # from w's RdBu_r so the two fields stay visually separable at a glance.
+    up = np.asarray(u_prime)
+    up_absmax = float(np.nanpercentile(np.abs(up), 98.0))
+    if not math.isfinite(up_absmax) or up_absmax <= 0.0:
+        up_absmax = 1.0
+    up_clip = np.clip(up, -up_absmax, up_absmax)
+    uprime_fig = go.Figure(
+        data=go.Heatmap(
+            x=x_km,
+            y=z_km,
+            z=up_clip,
+            zmin=-up_absmax,
+            zmax=up_absmax,
+            colorscale="PuOr",
+            reversescale=False,
+            colorbar=dict(title="u' (m/s)"),
+            zsmooth="best",
+        )
+    )
+    if interface_z is not None:
+        uprime_fig.add_hline(
+            y=interface_z / 1000.0,
+            line=dict(color="magenta", dash="dash", width=1.5),
+        )
+    uprime_fig.update_layout(
+        title="Horizontal-wind perturbation u' (m/s)",
+        xaxis_title="x (km)",
+        yaxis_title="height (km)",
+        template="plotly_dark",
+        margin=dict(l=60, r=20, t=50, b=50),
+        height=420,
+    )
+
+    return stream_fig, w_fig, uprime_fig
+
+
+# ---------------------------------------------------------------------------
+# Layout helpers
+# ---------------------------------------------------------------------------
+
+
+def _slider(id_, label, mn, mx, step, value, unit=""):
+    return html.Div(
+        className="slider-row",
+        children=[
+            html.Div(
+                [html.Span(label, className="slider-label"), html.Span(f"{value}{unit}", id=f"{id_}-val", className="slider-value")],
+                className="slider-header",
+            ),
+            dcc.Slider(
+                id=id_,
+                min=mn,
+                max=mx,
+                step=step,
+                value=value,
+                marks=None,
+                tooltip={"placement": "bottom", "always_visible": False},
+            ),
+        ],
+    )
+
+
+PROFILE_ZDOM_KM = 10.0
+PROFILE_N_POINTS = 32
+PROFILE_FIG_HEIGHT_PX = 680   # taller graph so 32 layers don't crowd
+# Ranges used both for axis limits and drag clamping. Kept as module-level
+# constants so the figure builder, the drag handler, and the redraw all agree.
+# The U axis allows negative values so HRRR profiles whose mean flow points
+# against the user-chosen "flow from" direction read as negative rather than
+# getting silently clamped to 0. Theta floor is dropped to 250 K so cold
+# continental winter columns stay visible.
+U_RANGE = (-40.0, 80.0)
+THETA_RANGE = (250.0, 400.0)
+UNDO_HISTORY_MAX = 50
+
+
+def _init_profile_figures():
+    # Defaults tuned to reproduce MATLAB "Example 2" (trapped lee waves):
+    # sharp low-level stability, weak stability aloft, light surface shear.
+    # 32 evenly-spaced levels give finer resolution in both the boundary
+    # layer and the free troposphere while keeping the column at 10 km.
+    # At n=32 the transfer-matrix solver converges to within ~1% of the
+    # two-layer analytic result for the trapped-wave case.
+    zs = default_profile_heights(PROFILE_ZDOM_KM, PROFILE_N_POINTS)
+    us = default_u_profile(zs, u_surface=20.0, shear=0.5)
+    thetas = default_theta_profile(zs, interface_km=3.5, lapse_lower=11.8, lapse_upper=1.9)
+    return zs, us, thetas
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def create_app() -> Dash:
+    # suppress_callback_exceptions is required because `controls-block` is
+    # swapped between two-layer and profile panels at runtime — the IDs
+    # referenced in the Analyze callback don't all exist in the initial layout.
+    # Ship static assets (CliMAS logo, favicon) from the package itself
+    # so the app works regardless of where it's launched from.
+    _pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    _assets_dir = os.path.join(_pkg_dir, "assets")
+
+    app = Dash(
+        __name__,
+        title="Mountain Waves",
+        update_title=None,
+        suppress_callback_exceptions=True,
+        assets_folder=_assets_dir,
+    )
+
+    zs0, us0, thetas0 = _init_profile_figures()
+
+    app.layout = html.Div(
+        className="mw-root",
+        children=[
+            html.Header(
+                className="mw-header",
+                children=[
+                    html.Img(
+                        src=app.get_asset_url("climas_icon_64.png"),
+                        alt="Climate, Meteorology & Atmospheric Sciences",
+                        className="mw-logo",
+                    ),
+                    html.Div(
+                        className="mw-header-text",
+                        children=[
+                            html.H1("Interactive 2-D Linear Mountain Wave Visualizer"),
+                            html.Div(
+                                className="mw-subtitle",
+                                children=[
+                                    html.Span("Rust + Python port of "),
+                                    html.A("Bob Hart's original MATLAB model", href="https://moe.met.fsu.edu/~rhart/mtnwave.html", target="_blank"),
+                                    html.Span(" by "),
+                                    html.A("Steve Nesbitt", href="https://publish.illinois.edu/swnesbitt/", target="_blank"),
+                                    html.Span(" — CliMAS UIUC"),
+                                    html.Span(f" · compute backend: {solver.backend_name()}"),
+                                ],
+                            ),
+                            # "Theory & About" link sits on its own line directly
+                            # under the subtitle. Clicking it toggles the modal
+                            # defined at the bottom of the layout.
+                            html.Div(
+                                className="mw-readme-link-row",
+                                children=[
+                                    html.Button(
+                                        "📖 Theory & About",
+                                        id="show-readme",
+                                        n_clicks=0,
+                                        className="mw-readme-link",
+                                    ),
+                                ],
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+            dcc.Tabs(
+                id="mode-tabs",
+                value="two-layer",
+                children=[
+                    dcc.Tab(label="Two-layer (analytic)", value="two-layer"),
+                    dcc.Tab(label="Profile (multi-layer)", value="profile"),
+                ],
+            ),
+            html.Div(
+                className="mw-global",
+                children=[
+                    html.Div("Latitude (°N)", className="mw-global-label"),
+                    dcc.Slider(
+                        id="latit",
+                        min=0,
+                        max=90,
+                        step=1,
+                        value=45,
+                        marks={0: "0°", 23: "23°", 45: "45°", 66: "66°", 90: "90°"},
+                        tooltip={"placement": "bottom", "always_visible": False},
+                    ),
+                    html.Span(id="latit-val", className="mw-global-value"),
+                    html.Span(
+                        "Coriolis f = 2Ω sin(φ) — affects the Rossby-number readout only.",
+                        className="mw-global-note",
+                    ),
+                ],
+            ),
+            # Both control panels live in the DOM simultaneously so every
+            # callback Input/State ID always resolves; the inactive one is
+            # hidden via CSS (see the mode-tabs callback below).
+            html.Div(
+                id="controls-block",
+                children=[
+                    html.Div(id="controls-two-layer", children=_two_layer_controls()),
+                    html.Div(
+                        id="controls-profile",
+                        children=_profile_controls(zs0, us0, thetas0),
+                        style={"display": "none"},
+                    ),
+                ],
+            ),
+            html.Div(
+                className="mw-diagnostics",
+                children=[
+                    html.Div(id="scorer-readout", className="diag-card"),
+                    html.Div(id="rossby-readout", className="diag-card"),
+                    html.Div(id="nonlin-readout", className="diag-card"),
+                    html.Div(id="critical-readout", className="diag-card"),
+                ],
+            ),
+            # Top row: w and u' heatmaps side-by-side. Streamline view lives
+            # below at full width so the trajectory pattern is legible at
+            # wide aspect ratios (it's the "money plot" of the tool).
+            html.Div(
+                className="mw-heatmaps",
+                children=[
+                    dcc.Graph(id="w-plot", config={"displayModeBar": False}),
+                    dcc.Graph(id="uprime-plot", config={"displayModeBar": False}),
+                ],
+            ),
+            html.Div(
+                className="mw-streamline-full",
+                children=[
+                    dcc.Graph(id="streamline-plot", config={"displayModeBar": False}),
+                ],
+            ),
+            # Shared state for editable profiles.
+            dcc.Store(
+                id="profile-store",
+                data={
+                    "z": zs0.tolist(),
+                    "u": us0.tolist(),
+                    "theta": thetas0.tolist(),
+                },
+            ),
+            # Undo history — a stack of prior profile-store states. Each edit
+            # pushes the pre-edit state; undo pops the most recent entry.
+            dcc.Store(id="profile-history", data=[]),
+            # Raw HRRR column cached after a successful fetch: the east/north
+            # wind components (u, v), potential temperature, target heights,
+            # and meta info. Lets the "flow from" slider re-project the wind
+            # onto a new axis without another AWS round-trip.
+            dcc.Store(id="hrrr-raw-store", data={}),
+            html.Footer(
+                className="mw-footer",
+                children=[
+                    html.Span("On the Profile tab, drag the gold circles left/right to edit u(z) and θ(z). "),
+                    html.Span("Click 'Analyze flow' to update the fields."),
+                ],
+            ),
+            # Theory & About modal — hidden by default, shown when the user
+            # clicks the "📖 Theory & About" link in the header. The outer
+            # div is the dark backdrop (click-to-dismiss); the inner div is
+            # the card that actually contains the rendered README.
+            html.Div(
+                id="readme-modal",
+                className="mw-modal",
+                style={"display": "none"},
+                n_clicks=0,
+                children=[
+                    html.Div(
+                        id="readme-modal-card",
+                        className="mw-modal-card",
+                        # Swallow clicks inside the card so clicking text
+                        # doesn't close the modal. Only the backdrop does.
+                        n_clicks=0,
+                        children=[
+                            html.Button(
+                                "×",
+                                id="close-readme",
+                                n_clicks=0,
+                                className="mw-modal-close",
+                                title="Close (Esc)",
+                            ),
+                            dcc.Markdown(
+                                _README_MD,
+                                className="mw-readme-content",
+                                link_target="_blank",
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    app.index_string = """
+<!doctype html>
+<html>
+<head>
+{%metas%}<title>{%title%}</title>{%favicon%}{%css%}
+<style>
+body { background: #0b0e14; color: #dfe3ea; font-family: -apple-system, system-ui, sans-serif; }
+.mw-root { max-width: 1400px; margin: 0 auto; padding: 20px; }
+.mw-header { display: flex; align-items: center; gap: 14px; margin-bottom: 16px; }
+.mw-header-text { display: flex; flex-direction: column; }
+.mw-logo { width: 56px; height: 56px; border-radius: 6px; flex-shrink: 0; }
+.mw-header h1 { margin: 0 0 4px 0; font-size: 24px; }
+.mw-subtitle { color: #9aa3ad; font-size: 13px; }
+.mw-subtitle a { color: #57b3ff; }
+.mw-readme-link-row { margin-top: 6px; }
+.mw-readme-link { background: #1e2835; border: 1px solid #2d3a4b; color: #9cd2ff; padding: 3px 12px; border-radius: 4px; font-size: 12px; cursor: pointer; font-family: inherit; }
+.mw-readme-link:hover { background: #2a3a4e; color: #c7e4ff; border-color: #3b86e6; }
+.mw-modal { position: fixed; top: 0; left: 0; right: 0; bottom: 0; background: rgba(0,0,0,0.72); display: flex; align-items: flex-start; justify-content: center; z-index: 9999; padding: 40px 20px; overflow-y: auto; }
+.mw-modal-card { position: relative; background: #0f141c; border: 1px solid #2d3a4b; border-radius: 8px; max-width: 860px; width: 100%; padding: 24px 36px 28px 36px; color: #dfe3ea; box-shadow: 0 16px 40px rgba(0,0,0,0.6); }
+.mw-modal-close { position: absolute; top: 8px; right: 12px; background: transparent; border: none; color: #9aa3ad; font-size: 26px; line-height: 1; cursor: pointer; padding: 4px 10px; font-family: inherit; }
+.mw-modal-close:hover { color: #ffffff; }
+.mw-readme-content h1 { font-size: 24px; color: #6ecbff; margin-top: 0; border-bottom: 1px solid #2d3a4b; padding-bottom: 8px; }
+.mw-readme-content h2 { font-size: 18px; color: #6ecbff; margin-top: 22px; }
+.mw-readme-content h3 { font-size: 15px; color: #9cd2ff; margin-top: 18px; }
+.mw-readme-content p, .mw-readme-content li { color: #cbd3dc; font-size: 13px; line-height: 1.55; }
+.mw-readme-content a { color: #57b3ff; }
+.mw-readme-content code { background: #131a24; padding: 1px 5px; border-radius: 3px; color: #ffd685; font-family: Monaco, Menlo, "Courier New", monospace; font-size: 12px; }
+.mw-readme-content pre { background: #131a24; padding: 10px 14px; border-radius: 4px; overflow-x: auto; border: 1px solid #1f2632; }
+.mw-readme-content pre code { background: transparent; padding: 0; color: #dfe3ea; }
+.mw-readme-content blockquote { border-left: 3px solid #3b86e6; margin: 12px 0; padding: 2px 14px; color: #c7ced6; background: #131a24; }
+.mw-controls { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px 28px; background: #11161f; padding: 18px; border-radius: 8px; margin: 14px 0; }
+.mw-controls.profile { grid-template-columns: 1fr 1fr 1fr; }
+/* Two-layer tab mirrors the profile tab's 3-column grid: sliders | sliders | Actions. */
+.mw-controls.two-layer { grid-template-columns: 1fr 1fr 1fr; }
+.slider-row { display: flex; flex-direction: column; gap: 4px; }
+.slider-header { display: flex; justify-content: space-between; font-size: 13px; }
+.slider-label { color: #c7ced6; }
+.slider-value { color: #6ecbff; font-variant-numeric: tabular-nums; }
+.mw-presets { display: flex; gap: 8px; margin: 10px 0 0 0; }
+.mw-presets button, .mw-analyze { background: #1e2835; border: 1px solid #2d3a4b; color: #dfe3ea; padding: 6px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.mw-presets button:hover, .mw-analyze:hover { background: #2a3a4e; }
+.mw-analyze { background: #2469c6; border-color: #3b86e6; font-weight: 600; padding: 8px 18px; }
+.mw-analyze:hover { background: #3079d8; }
+.mw-diagnostics { display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px; margin: 10px 0; }
+.diag-card { background: #11161f; padding: 10px 16px; border-radius: 6px; font-size: 14px; }
+.diag-card .v { color: #ffd685; font-weight: 700; margin-left: 8px; font-variant-numeric: tabular-nums; }
+.diag-card .note { color: #9aa3ad; font-size: 12px; margin-left: 10px; }
+.mw-plots { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+.mw-heatmaps { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+.mw-streamline-full { margin-top: 12px; }
+.mw-streamline-full > .dash-graph { width: 100%; }
+.mw-profile-editors { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin-top: 6px; }
+.mw-profile-toolbar { display: flex; align-items: center; gap: 10px; margin-top: 10px; }
+.mw-undo { background: #1e2835; border: 1px solid #2d3a4b; color: #dfe3ea; padding: 5px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.mw-undo:hover:not(:disabled) { background: #2a3a4e; }
+.mw-undo:disabled { opacity: 0.4; cursor: default; }
+.mw-undo-status { color: #8d97a2; font-size: 12px; }
+/* HRRR card takes the first 2 of 3 columns of .mw-controls.profile (so
+   its one-line input row has room), and the Actions card sits in the
+   remaining column to its right. */
+.mw-hrrr-section { grid-column: span 2; }
+.mw-actions-section { grid-column: span 1; display: flex; flex-direction: column; gap: 10px; }
+.mw-action-btn { width: 100%; padding: 10px 14px; font-size: 14px; text-align: center; background: #1e2835; border: 1px solid #2d3a4b; color: #dfe3ea; border-radius: 6px; cursor: pointer; }
+.mw-action-btn:hover { background: #2a3a4e; }
+.mw-action-btn.mw-analyze { background: #2469c6; border-color: #3b86e6; font-weight: 600; }
+.mw-action-btn.mw-analyze:hover { background: #3079d8; }
+.mw-hrrr-row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 6px; }
+.mw-hrrr-row-compact { gap: 8px; row-gap: 4px; flex-wrap: nowrap; width: 100%; }
+.mw-hrrr-lbl { font-size: 11px; color: #9aa3ad; min-width: 0; white-space: nowrap; flex-shrink: 0; }
+.mw-hrrr-input { background: #0f1520; border: 1px solid #2d3a4b; color: #dfe3ea; padding: 2px 6px; border-radius: 4px; font-size: 11px; width: 70px; font-family: inherit; flex-shrink: 0; }
+.mw-hrrr-input.wide { flex: 1 1 auto; min-width: 110px; width: auto; }
+.mw-hrrr-btn { font-size: 11px; padding: 3px 12px; margin-left: auto; flex-shrink: 0; }
+.mw-hrrr-status { color: #9aa3ad; font-size: 11px; margin-top: 4px; min-height: 14px; }
+.mw-hrrr-status.error { color: #ff8a8a; }
+.mw-hrrr-status.ok { color: #89d185; }
+/* Flow-from slider row — label on the left, wide slider stretching to the
+   edge, current value pinned on the right. */
+.mw-hrrr-dir-row { display: flex; align-items: center; gap: 10px; margin-top: 10px; width: 100%; }
+.mw-hrrr-dir-row > label { min-width: 60px; flex-shrink: 0; }
+.mw-hrrr-dir-slider { flex: 1 1 auto; min-width: 0; padding: 0 8px; }
+.mw-hrrr-dir-val { color: #6ecbff; font-variant-numeric: tabular-nums; font-weight: 600; min-width: 56px; text-align: right; flex-shrink: 0; font-size: 12px; }
+.mw-profile-diagnostics { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin-top: 8px; }
+.mw-footer { margin-top: 20px; color: #8f98a3; font-size: 12px; }
+.mw-global { display: grid; grid-template-columns: 130px 1fr 80px 1fr; align-items: center; gap: 14px; background: #131a24; padding: 10px 16px; border-radius: 6px; margin-top: 10px; }
+.mw-global-label { font-size: 13px; color: #c7ced6; }
+.mw-global-value { color: #6ecbff; font-variant-numeric: tabular-nums; font-weight: 600; }
+.mw-global-note { font-size: 12px; color: #8f98a3; }
+.section-title { font-size: 11px; font-weight: 600; color: #8d97a2; letter-spacing: 0.08em; text-transform: uppercase; margin-bottom: 6px; }
+.section { background: #161d29; padding: 12px; border-radius: 6px; }
+</style>
+</head>
+<body>
+{%app_entry%}
+<footer>{%config%}{%scripts%}{%renderer%}</footer>
+</body>
+</html>
+"""
+
+    _register_callbacks(app)
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Callbacks
+# ---------------------------------------------------------------------------
+
+
+def _two_layer_controls():
+    d = TWO_LAYER_DEFAULTS
+    return html.Div(
+        # Three-column grid to mirror the profile tab: atmospheric sliders |
+        # terrain+domain+spectrum sliders | Actions column. The Actions
+        # column holds Reset/Analyze plus the preset buttons so the user's
+        # eye finds every "do something" control in the same place on both
+        # tabs.
+        className="mw-controls two-layer",
+        children=[
+            html.Div(
+                className="section",
+                children=[
+                    html.Div("Atmospheric profile", className="section-title"),
+                    _slider("U", "Surface wind (m/s)", 0, 100, 1, d["U"]),
+                    _slider("L_upper", "L upper (×10⁻⁴)", 0, 50, 0.1, d["L_upper"]),
+                    _slider("L_lower", "L lower (×10⁻⁴)", 0, 50, 0.1, d["L_lower"]),
+                    _slider("H", "Interface ht. (km)", 0, 20, 0.1, d["H"]),
+                ],
+            ),
+            html.Div(
+                className="section",
+                children=[
+                    html.Div("Terrain profile", className="section-title"),
+                    _slider("mtn_h", "Max height (km)", 0, 3, 0.05, d["mtn_h"]),
+                    _slider("mtn_a", "Half-width (km)", 0.25, 25, 0.25, d["mtn_a"]),
+                    html.Div("Domain profile", className="section-title", style={"marginTop": "12px"}),
+                    _slider("xdom", "Horizontal (km)", 5, 100, 1, d["xdom"]),
+                    _slider("zdom", "Vertical (km)", 1, 20, 0.5, d["zdom"]),
+                    html.Div("Spectral profile", className="section-title", style={"marginTop": "12px"}),
+                    _slider("mink_k", "Min wave# (half-widths)", 0, 50, 0.5, d["mink_k"]),
+                    _slider("maxk_k", "Max wave# (half-widths)", 0, 50, 0.5, d["maxk_k"]),
+                ],
+            ),
+            # Actions column — Reset / Analyze at the top, presets below.
+            # Shares the .mw-actions-section layout with the profile tab so
+            # both tabs look and feel the same.
+            html.Div(
+                className="section mw-actions-section",
+                children=[
+                    html.Div("Actions", className="section-title"),
+                    html.Button(
+                        "Reset to defaults",
+                        id="reset-two",
+                        className="mw-action-btn",
+                        title="Restore every slider on this tab to its initial value.",
+                    ),
+                    html.Button(
+                        "Analyze flow",
+                        id="analyze-two",
+                        className="mw-analyze mw-action-btn",
+                    ),
+                    html.Div(
+                        "Presets",
+                        className="section-title",
+                        style={"marginTop": "10px"},
+                    ),
+                    html.Button(
+                        "Uniform atmosphere",
+                        id="preset-uniform",
+                        className="mw-action-btn",
+                        title="Hart's Example 1 — constant Scorer parameter, no trapping.",
+                    ),
+                    html.Button(
+                        "Trapped lee waves",
+                        id="preset-trapped",
+                        className="mw-action-btn",
+                        title="Hart's Example 2 — strong lower-layer Scorer, trapped wave train downstream.",
+                    ),
+                    html.Button(
+                        "Near-downslope",
+                        id="preset-downslope",
+                        className="mw-action-btn",
+                        title=(
+                            "Strong lee waves approaching the downslope-windstorm "
+                            "regime. Not from Hart's examples — linear Fourier/Scorer "
+                            "theory cannot fully simulate real downslope windstorms "
+                            "because they are fundamentally nonlinear."
+                        ),
+                    ),
+                    html.Button(
+                        "Near critical layer at 2 km",
+                        id="preset-critical-2km",
+                        className="mw-action-btn",
+                        title=(
+                            "Two-layer caricature of critical-level absorption. "
+                            "Strong Scorer contrast across an interface at 2 km "
+                            "(l_lower² >> k² >> l_upper²) reflects most wave "
+                            "energy downward, mimicking Booker & Bretherton "
+                            "(1967) absorption. A true critical level requires "
+                            "U(z)=0, which two-layer mode cannot represent — "
+                            "use the Profile tab for the physically faithful "
+                            "wind-reversal setup."
+                        ),
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+def _profile_controls(zs, us, thetas):
+    return html.Div(
+        children=[
+            html.Div(
+                className="mw-controls profile",
+                children=[
+                    html.Div(
+                        className="section",
+                        children=[
+                            html.Div("Terrain", className="section-title"),
+                            _slider("p_mtn_h", "Max height (km)", 0, 3, 0.05, 0.5),
+                            _slider("p_mtn_a", "Half-width (km)", 0.25, 25, 0.25, 2.5),
+                        ],
+                    ),
+                    html.Div(
+                        className="section",
+                        children=[
+                            html.Div("Domain", className="section-title"),
+                            _slider("p_xdom", "Horizontal (km)", 5, 100, 1, 40),
+                            _slider("p_zdom", "Vertical (km)", 1, 20, 0.5, 10),
+                        ],
+                    ),
+                    html.Div(
+                        className="section",
+                        children=[
+                            html.Div("Spectrum", className="section-title"),
+                            _slider("p_mink_k", "Min wave# (half-widths)", 0, 50, 0.5, 0),
+                            _slider("p_maxk_k", "Max wave# (half-widths)", 0, 50, 0.5, 30),
+                        ],
+                    ),
+                    html.Div(
+                        className="section mw-hrrr-section",
+                        children=[
+                            html.Div("Initialize from HRRR (AWS)", className="section-title"),
+                            html.Div(
+                                className="mw-hrrr-row mw-hrrr-row-compact",
+                                children=[
+                                    html.Label("Lat °N", className="mw-hrrr-lbl"),
+                                    dcc.Input(
+                                        id="hrrr-lat",
+                                        type="number",
+                                        value=40.0,
+                                        step=0.01,
+                                        className="mw-hrrr-input",
+                                    ),
+                                    html.Label("Lon °E", className="mw-hrrr-lbl"),
+                                    dcc.Input(
+                                        id="hrrr-lon",
+                                        type="number",
+                                        value=-105.5,
+                                        step=0.01,
+                                        className="mw-hrrr-input",
+                                    ),
+                                    html.Label(
+                                        "Cycle",
+                                        className="mw-hrrr-lbl",
+                                        title="UTC init time as YYYYMMDDHH, e.g. 2024060112.",
+                                    ),
+                                    dcc.Input(
+                                        id="hrrr-datetime",
+                                        type="text",
+                                        value="",
+                                        placeholder="YYYYMMDDHH",
+                                        className="mw-hrrr-input wide",
+                                    ),
+                                    html.Button(
+                                        "Fetch",
+                                        id="hrrr-fetch",
+                                        className="mw-analyze mw-hrrr-btn",
+                                    ),
+                                ],
+                            ),
+                            # Flow-from slider lives on its own row so it can
+                            # stretch across the full card. Moving it updates
+                            # the along-flow projection *without* triggering
+                            # another HRRR download — the raw east/north wind
+                            # components are cached in hrrr-raw-store below.
+                            html.Div(
+                                className="mw-hrrr-dir-row",
+                                children=[
+                                    html.Label(
+                                        "Flow from",
+                                        className="mw-hrrr-lbl",
+                                        title=(
+                                            "Meteorological convention: direction "
+                                            "the wind is blowing FROM. 0=N, 90=E, "
+                                            "180=S, 270=W. Moving this slider "
+                                            "re-projects the cached HRRR wind "
+                                            "onto the new axis (no re-download)."
+                                        ),
+                                    ),
+                                    html.Div(
+                                        className="mw-hrrr-dir-slider",
+                                        children=dcc.Slider(
+                                            id="hrrr-dir",
+                                            min=0,
+                                            max=360,
+                                            step=1,
+                                            value=270,
+                                            marks={
+                                                0: "0° N",
+                                                90: "90° E",
+                                                180: "180° S",
+                                                270: "270° W",
+                                                360: "360° N",
+                                            },
+                                            tooltip={"placement": "bottom", "always_visible": False},
+                                        ),
+                                    ),
+                                    html.Span(id="hrrr-dir-val", className="mw-hrrr-dir-val"),
+                                ],
+                            ),
+                            dcc.Loading(
+                                id="hrrr-loading",
+                                type="circle",
+                                children=html.Div(
+                                    id="hrrr-status",
+                                    className="mw-hrrr-status",
+                                ),
+                            ),
+                        ],
+                    ),
+                    # Actions panel — sits in the 3rd grid column beside the
+                    # 2/3-width HRRR card so the Analyze button is always
+                    # visible without scrolling past the fetch controls.
+                    html.Div(
+                        className="section mw-actions-section",
+                        children=[
+                            html.Div("Actions", className="section-title"),
+                            html.Button(
+                                "Reset profile",
+                                id="reset-profile",
+                                className="mw-action-btn",
+                            ),
+                            html.Button(
+                                "Analyze flow",
+                                id="analyze-profile",
+                                className="mw-analyze mw-action-btn",
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+            html.Div(
+                className="mw-profile-toolbar",
+                children=[
+                    html.Button(
+                        "↶ Undo",
+                        id="undo-profile",
+                        className="mw-undo",
+                        disabled=True,
+                        title="Revert the last profile edit (up to 50 steps).",
+                    ),
+                    html.Span(id="undo-status", className="mw-undo-status"),
+                ],
+            ),
+            html.Div(
+                className="mw-profile-editors",
+                children=[
+                    dcc.Graph(
+                        id="u-profile-graph",
+                        figure=_profile_editor_figure("Zonal wind u(z)", us, zs, xunit="m s⁻¹", xrange=U_RANGE),
+                        config={"edits": {"shapePosition": True}, "displayModeBar": False, "scrollZoom": False},
+                    ),
+                    dcc.Graph(
+                        id="theta-profile-graph",
+                        figure=_profile_editor_figure(
+                            "Potential temperature θ(z)", thetas, zs, xunit="K", xrange=THETA_RANGE
+                        ),
+                        config={"edits": {"shapePosition": True}, "displayModeBar": False, "scrollZoom": False},
+                    ),
+                ],
+            ),
+            html.Div(
+                "Drag the gold circles left/right on each profile to change the u or θ "
+                "value at that height. Heights are fixed at 18 evenly-spaced levels; the "
+                "blue line shows the current profile and follows the points as you drag. "
+                "The four diagnostics below update live — Scorer parameter L² (trapped "
+                "waves need L² to decrease aloft), Richardson number Ri (< 0.25 flags "
+                "shear instability), Brunt–Väisälä N² (stratification strength), and "
+                "the potential-temperature lapse rate dθ/dz. Click 'Analyze flow' to "
+                "update the wave solution.",
+                style={"color": "#8f98a3", "fontSize": "12px", "marginTop": "6px"},
+            ),
+            html.Div("Live profile diagnostics", className="section-title",
+                     style={"marginTop": "14px"}),
+            html.Div(
+                className="mw-profile-diagnostics",
+                children=[
+                    dcc.Graph(id="diag-scorer", config={"displayModeBar": False}),
+                    dcc.Graph(id="diag-ri", config={"displayModeBar": False}),
+                    dcc.Graph(id="diag-n2", config={"displayModeBar": False}),
+                    dcc.Graph(id="diag-dthdz", config={"displayModeBar": False}),
+                ],
+            ),
+        ],
+    )
+
+
+def _profile_editor_figure(title, values, zs, xunit, xrange):
+    """Build an editable profile figure.
+
+    Each point is represented as a draggable circle *shape* — Plotly supports
+    shape dragging via the ``edits.shapePosition`` config flag — and a line
+    trace connects the current values for visualization. When the user drags
+    a circle, ``relayoutData`` fires with ``shapes[i].x0``/``x1`` keys, which
+    the ``_profile_update`` callback parses back into the shared store. The
+    store-driven ``_redraw_profiles`` callback then regenerates both figures
+    so the connecting line follows the dragged points.
+    """
+    # Sanitize any NaN/inf so a corrupted store value can't knock a circle
+    # off screen. We do NOT clip to the nominal xrange here — if HRRR
+    # delivers a value outside the default axis, extend the axis rather
+    # than silently mangling the data. The drag callback applies its own
+    # clamp so user-dragged points still stay on screen.
+    values = np.asarray(values, dtype=float)
+    values = np.where(np.isfinite(values), values, 0.5 * (xrange[0] + xrange[1]))
+    zs_km = np.asarray(zs, dtype=float) / 1000.0
+
+    # Data-driven axis: take the wider of the default xrange and the actual
+    # data span, with a little padding so edge points aren't on the border.
+    if values.size:
+        v_min = float(np.min(values))
+        v_max = float(np.max(values))
+        span = max(v_max - v_min, 1.0)
+        pad = 0.05 * span
+        axis_lo = min(xrange[0], v_min - pad)
+        axis_hi = max(xrange[1], v_max + pad)
+    else:
+        axis_lo, axis_hi = xrange
+    effective_xrange = (axis_lo, axis_hi)
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=values,
+            y=zs_km,
+            mode="lines+markers",
+            marker=dict(size=8, color="#6ecbff", line=dict(color="white", width=1)),
+            line=dict(color="#6ecbff", width=2),
+            name=title,
+            hoverinfo="skip",
+        )
+    )
+
+    # One draggable circle per profile point. Pixel sizing makes every
+    # shape render as a visually round circle regardless of how stretched
+    # the axes are; dragging updates shapes[i].xanchor in relayoutData.
+    radius_px = 9
+    shapes = []
+    for v, zk in zip(values, zs_km):
+        shapes.append(
+            dict(
+                type="circle",
+                xref="x",
+                yref="y",
+                xsizemode="pixel",
+                ysizemode="pixel",
+                xanchor=float(v),
+                yanchor=float(zk),
+                x0=-radius_px,
+                x1=radius_px,
+                y0=-radius_px,
+                y1=radius_px,
+                fillcolor="#ffd685",
+                line=dict(color="white", width=1.5),
+                editable=True,
+                layer="above",
+            )
+        )
+
+    fig.update_layout(
+        title=title,
+        xaxis_title=f"value ({xunit})",
+        yaxis_title="height (km)",
+        template="plotly_dark",
+        margin=dict(l=60, r=20, t=50, b=50),
+        height=PROFILE_FIG_HEIGHT_PX,
+        dragmode=False,
+        xaxis=dict(range=list(effective_xrange), fixedrange=True),
+        yaxis=dict(range=[0, zs_km[-1]], fixedrange=True),
+        shapes=shapes,
+    )
+    return fig
+
+
+def _profile_diagnostics(zs, us, thetas):
+    """Return (L², Ri, N², dθ/dz) arrays evaluated on the profile grid."""
+    zs = np.asarray(zs, dtype=float)
+    us = np.asarray(us, dtype=float)
+    thetas = np.asarray(thetas, dtype=float)
+    l2 = scorer_from_profile(zs, us, thetas)
+    n2 = brunt_vaisala(zs, thetas)
+
+    # dU/dz and dθ/dz via the same 3-point finite difference used in
+    # reference.py / scorer_from_profile so diagnostics stay consistent.
+    n = zs.size
+    dudz = np.zeros(n)
+    dthdz = np.zeros(n)
+    for i in range(n):
+        if i == 0:
+            dudz[i] = (us[1] - us[0]) / (zs[1] - zs[0])
+            dthdz[i] = (thetas[1] - thetas[0]) / (zs[1] - zs[0])
+        elif i == n - 1:
+            dudz[i] = (us[-1] - us[-2]) / (zs[-1] - zs[-2])
+            dthdz[i] = (thetas[-1] - thetas[-2]) / (zs[-1] - zs[-2])
+        else:
+            h1 = zs[i] - zs[i - 1]
+            h2 = zs[i + 1] - zs[i]
+            dudz[i] = (
+                us[i + 1] * h1 ** 2
+                - us[i - 1] * h2 ** 2
+                + us[i] * (h2 ** 2 - h1 ** 2)
+            ) / (h1 * h2 * (h1 + h2))
+            dthdz[i] = (
+                thetas[i + 1] * h1 ** 2
+                - thetas[i - 1] * h2 ** 2
+                + thetas[i] * (h2 ** 2 - h1 ** 2)
+            ) / (h1 * h2 * (h1 + h2))
+
+    # Ri = N² / (dU/dz)². Guard against vanishing shear.
+    with np.errstate(divide="ignore", invalid="ignore"):
+        ri = np.where(np.abs(dudz) > 1e-6, n2 / (dudz ** 2), np.inf)
+    return l2, ri, n2, dthdz
+
+
+def _diagnostic_figure(title, values, zs, xunit, color, xrange=None, log_x=False, ref_line=None):
+    """Small read-only profile plot of ``values(z)``."""
+    values = np.asarray(values, dtype=float)
+    zs_km = np.asarray(zs, dtype=float) / 1000.0
+
+    plot_x = values
+    if log_x:
+        # Use symmetric log to tolerate negative values without dropping them.
+        plot_x = values
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=plot_x,
+            y=zs_km,
+            mode="lines+markers",
+            marker=dict(size=6, color=color, line=dict(color="white", width=0.5)),
+            line=dict(color=color, width=2),
+            hovertemplate=f"%{{x:.3g}} {xunit}<br>%{{y:.2f}} km<extra></extra>",
+            showlegend=False,
+        )
+    )
+    if ref_line is not None:
+        fig.add_vline(x=ref_line, line=dict(color="#ffd685", dash="dot", width=1))
+
+    xaxis_kwargs = dict(title=f"{xunit}")
+    if log_x:
+        xaxis_kwargs["type"] = "log"
+    if xrange is not None:
+        xaxis_kwargs["range"] = list(xrange)
+
+    fig.update_layout(
+        title=title,
+        yaxis_title="height (km)",
+        template="plotly_dark",
+        margin=dict(l=50, r=15, t=40, b=40),
+        height=340,
+        xaxis=xaxis_kwargs,
+        yaxis=dict(range=[0, zs_km[-1]]),
+    )
+    return fig
+
+
+def _diagnostic_figures(store):
+    """Build all four diagnostic figures from the current profile store."""
+    zs = np.asarray(store["z"], dtype=float)
+    us = np.asarray(store["u"], dtype=float)
+    thetas = np.asarray(store["theta"], dtype=float)
+    l2, ri, n2, dthdz = _profile_diagnostics(zs, us, thetas)
+
+    # Scorer parameter. Display in units of 10⁻⁸ m⁻² so the magnitudes line
+    # up with the two-layer L sliders: L_slider = L × 10⁴ m⁻¹ means
+    # L_slider² = L² × 10⁸, so L²(display) directly equals L_slider².
+    # E.g. the two-layer defaults of L_lower=10, L_upper=4 correspond to
+    # L²_lower=100, L²_upper=16 on this plot.
+    l2_scaled = l2 * 1e8
+    l_fig = _diagnostic_figure(
+        "Scorer parameter L²(z)",
+        l2_scaled,
+        zs,
+        xunit="L² (×10⁻⁸ m⁻²)  — same units as (two-layer L slider)²",
+        color="#6ecbff",
+        ref_line=0.0,
+    )
+
+    # Richardson number. Real-world Ri values span many orders of magnitude
+    # — a still-stable free-troposphere profile is easily 100s while the
+    # instability threshold is 0.25. Use a log x-axis so that variation is
+    # visible; clip negatives (from N² < 0 regions) to a small positive
+    # floor and mark them with a trailing annotation instead.
+    neg_mask = ri <= 0
+    ri_pos = np.where(neg_mask, np.nan, ri)
+    ri_pos = np.where(np.isfinite(ri_pos), ri_pos, 1e4)
+    ri_pos = np.clip(ri_pos, 1e-2, 1e4)
+    ri_fig = _diagnostic_figure(
+        "Richardson number Ri(z)",
+        ri_pos,
+        zs,
+        xunit="Ri (log scale, clipped 10⁻² – 10⁴)",
+        color="#ffb86c",
+        log_x=True,
+        ref_line=0.25,
+    )
+
+    # N² — units of s⁻², typical tropospheric values ~10⁻⁴; can be negative
+    # if the user drags θ(z) into a superadiabatic configuration.
+    n2_scaled = n2 * 1e4
+    n2_fig = _diagnostic_figure(
+        "Brunt–Väisälä N²(z)",
+        n2_scaled,
+        zs,
+        xunit="N² (×10⁻⁴ s⁻²)",
+        color="#a0e878",
+        ref_line=0.0,
+    )
+
+    # dθ/dz in K/km — the raw stratification before dividing by θ.
+    dthdz_fig = _diagnostic_figure(
+        "Lapse rate dθ/dz(z)",
+        dthdz * 1000.0,
+        zs,
+        xunit="dθ/dz (K km⁻¹)",
+        color="#f57aa5",
+        ref_line=0.0,
+    )
+    return l_fig, ri_fig, n2_fig, dthdz_fig
+
+
+def _register_callbacks(app: Dash):
+    # --- latitude readout ------------------------------------------------
+    app.clientside_callback(
+        "function(v) { return Math.round(v) + '\u00b0 N'; }",
+        Output("latit-val", "children"),
+        Input("latit", "value"),
+    )
+
+    # --- Theory & About modal ----------------------------------------------
+    # The show button opens the modal, the × button closes it. Returning an
+    # empty style dict lets the .mw-modal CSS class (display: flex) take
+    # effect; returning {"display": "none"} hides it.
+    @app.callback(
+        Output("readme-modal", "style"),
+        [
+            Input("show-readme", "n_clicks"),
+            Input("close-readme", "n_clicks"),
+        ],
+        prevent_initial_call=True,
+    )
+    def _toggle_readme(_show, _close):
+        if ctx.triggered_id == "show-readme":
+            return {}
+        return {"display": "none"}
+
+    # Close the modal on Esc keypress as well. Clientside so it doesn't
+    # require a round-trip; the keydown listener is attached once on load
+    # and clicks the × button synthetically when Esc is pressed while the
+    # modal is visible.
+    app.clientside_callback(
+        """
+        function() {
+            if (window.__mw_readme_esc_attached) return window.dash_clientside.no_update;
+            window.__mw_readme_esc_attached = true;
+            document.addEventListener('keydown', function(e) {
+                if (e.key !== 'Escape') return;
+                var modal = document.getElementById('readme-modal');
+                if (!modal) return;
+                if (modal.style.display === 'none') return;
+                var btn = document.getElementById('close-readme');
+                if (btn) btn.click();
+            });
+            return window.dash_clientside.no_update;
+        }
+        """,
+        Output("close-readme", "title"),
+        Input("close-readme", "id"),
+    )
+
+    # --- HRRR flow-from slider readout -----------------------------------
+    # Shows the current azimuth next to the slider with a compass letter
+    # (N/NE/E/.../NW). Purely a UI hint — the server callback still uses
+    # the raw degrees when computing the along-flow projection.
+    app.clientside_callback(
+        """
+        function(v) {
+            if (v === null || v === undefined) return '';
+            var deg = Math.round(v);
+            var dirs = ['N','NE','E','SE','S','SW','W','NW','N'];
+            var idx = Math.round(deg / 45) % 8;
+            return deg + '\u00b0 ' + dirs[idx];
+        }
+        """,
+        Output("hrrr-dir-val", "children"),
+        Input("hrrr-dir", "value"),
+    )
+
+    # --- live slider readouts --------------------------------------------
+    for sid, unit in [
+        ("U", " m/s"),
+        ("L_upper", ""),
+        ("L_lower", ""),
+        ("H", " km"),
+        ("mtn_h", " km"),
+        ("mtn_a", " km"),
+        ("xdom", " km"),
+        ("zdom", " km"),
+        ("mink_k", ""),
+        ("maxk_k", ""),
+        ("p_mtn_h", " km"),
+        ("p_mtn_a", " km"),
+        ("p_xdom", " km"),
+        ("p_zdom", " km"),
+        ("p_mink_k", ""),
+        ("p_maxk_k", ""),
+    ]:
+        app.clientside_callback(
+            f"function(v) {{ return (Math.round(v*100)/100) + '{unit}'; }}",
+            Output(f"{sid}-val", "children"),
+            Input(sid, "value"),
+        )
+
+    # --- swap control panel on tab change --------------------------------
+    # Both control panels are always in the DOM; we just toggle visibility.
+    @app.callback(
+        [Output("controls-two-layer", "style"), Output("controls-profile", "style")],
+        Input("mode-tabs", "value"),
+    )
+    def _swap(mode):
+        if mode == "two-layer":
+            return {}, {"display": "none"}
+        return {"display": "none"}, {}
+
+    # --- presets and reset apply to sliders ------------------------------
+    # Both the three preset buttons and the "Reset to defaults" button in
+    # the Actions column funnel through this callback. Reset is just
+    # another preset whose values happen to be TWO_LAYER_DEFAULTS.
+    @app.callback(
+        [
+            Output("U", "value"),
+            Output("L_upper", "value"),
+            Output("L_lower", "value"),
+            Output("H", "value"),
+            Output("mtn_h", "value"),
+            Output("mtn_a", "value"),
+            Output("xdom", "value"),
+            Output("zdom", "value"),
+            Output("mink_k", "value"),
+            Output("maxk_k", "value"),
+        ],
+        [
+            Input("preset-uniform", "n_clicks"),
+            Input("preset-trapped", "n_clicks"),
+            Input("preset-downslope", "n_clicks"),
+            Input("preset-critical-2km", "n_clicks"),
+            Input("reset-two", "n_clicks"),
+        ],
+        prevent_initial_call=True,
+    )
+    def _apply_preset(nu, nt, nd, nc, nr):
+        from dash import ctx
+
+        trig = ctx.triggered_id
+        if trig == "reset-two":
+            p = TWO_LAYER_DEFAULTS
+        else:
+            key = {
+                "preset-uniform": "uniform",
+                "preset-trapped": "trapped",
+                "preset-downslope": "downslope",
+                "preset-critical-2km": "critical_caricature",
+            }.get(trig)
+            if key is None:
+                return [no_update] * 10
+            p = PRESETS[key]
+        return [
+            p["U"], p["L_upper"], p["L_lower"], p["H"],
+            p["mtn_h"], p["mtn_a"], p["xdom"], p["zdom"],
+            p["mink_k"], p["maxk_k"],
+        ]
+
+    # --- two-layer analyze ------------------------------------------------
+    @app.callback(
+        [
+            Output("streamline-plot", "figure"),
+            Output("w-plot", "figure"),
+            Output("uprime-plot", "figure"),
+            Output("scorer-readout", "children"),
+            Output("rossby-readout", "children"),
+            Output("nonlin-readout", "children"),
+            Output("critical-readout", "children"),
+        ],
+        [
+            Input("analyze-two", "n_clicks"),
+            Input("analyze-profile", "n_clicks"),
+        ],
+        [
+            State("mode-tabs", "value"),
+            State("U", "value"),
+            State("L_upper", "value"),
+            State("L_lower", "value"),
+            State("H", "value"),
+            State("mtn_h", "value"),
+            State("mtn_a", "value"),
+            State("xdom", "value"),
+            State("zdom", "value"),
+            State("mink_k", "value"),
+            State("maxk_k", "value"),
+            State("p_mtn_h", "value"),
+            State("p_mtn_a", "value"),
+            State("p_xdom", "value"),
+            State("p_zdom", "value"),
+            State("p_mink_k", "value"),
+            State("p_maxk_k", "value"),
+            State("profile-store", "data"),
+            State("latit", "value"),
+        ],
+        prevent_initial_call=False,
+    )
+    def _run(
+        n_two,
+        n_prof,
+        mode,
+        U,
+        L_upper,
+        L_lower,
+        H,
+        mtn_h,
+        mtn_a,
+        xdom,
+        zdom,
+        mink_k,
+        maxk_k,
+        p_mtn_h,
+        p_mtn_a,
+        p_xdom,
+        p_zdom,
+        p_mink_k,
+        p_maxk_k,
+        store,
+        latit_deg,
+    ):
+        from dash import ctx
+        trig = ctx.triggered_id
+        print(
+            f"[mountain-waves] _run fired: trigger={trig!r} mode={mode!r} "
+            f"n_two={n_two} n_prof={n_prof} lat={latit_deg}",
+            flush=True,
+        )
+        lat = latit_deg if latit_deg is not None else 45.0
+        try:
+            if mode == "profile":
+                params = {
+                    "mtn_h": p_mtn_h if p_mtn_h is not None else 0.5,
+                    "mtn_a": p_mtn_a if p_mtn_a is not None else 2.5,
+                    "xdom": p_xdom if p_xdom is not None else 40,
+                    "zdom": p_zdom if p_zdom is not None else 10,
+                    "mink_k": p_mink_k if p_mink_k is not None else 0,
+                    "maxk_k": p_maxk_k if p_maxk_k is not None else 30,
+                }
+                zs = np.asarray(store["z"])
+                us = np.asarray(store["u"])
+                thetas = np.asarray(store["theta"])
+                sfig, wfig, upfig, scorer, rossby = _profile_plots(params, zs, us, thetas, latit_deg=lat)
+            else:
+                params = {
+                    "U": U if U is not None else 20.0,
+                    "L_upper": L_upper if L_upper is not None else 4.0,
+                    "L_lower": L_lower if L_lower is not None else 10.0,
+                    "H": H if H is not None else 3.5,
+                    "mtn_h": mtn_h if mtn_h is not None else 0.5,
+                    "mtn_a": mtn_a if mtn_a is not None else 2.5,
+                    "xdom": xdom if xdom is not None else 40,
+                    "zdom": zdom if zdom is not None else 10,
+                    "mink_k": mink_k if mink_k is not None else 0,
+                    "maxk_k": maxk_k if maxk_k is not None else 30,
+                }
+                sfig, wfig, upfig, scorer, rossby = _two_layer_plots(params, latit_deg=lat)
+            print(
+                f"[mountain-waves]   ok: scorer={scorer:.3f} rossby={rossby:.3f}",
+                flush=True,
+            )
+        except Exception as exc:
+            import traceback
+            traceback.print_exc()
+            print(f"[mountain-waves] _run FAILED: {exc!r}", flush=True)
+            raise
+
+        # Nonlinearity indicator Nh/U = L * h (in the layer where the wave
+        # is forced). Linear Fourier/Scorer theory breaks down around
+        # Nh/U ≳ 0.85; beyond that, real flow would overturn or transition
+        # to hydraulic/downslope-windstorm behavior that this model cannot
+        # represent. See Smith (1985) and Hart's "Problems" note.
+        if mode == "profile":
+            zs = np.asarray(store["z"])
+            thetas = np.asarray(store["theta"])
+            us = np.asarray(store["u"])
+            # crude surface N from finite-difference dθ/dz
+            dth = (thetas[1] - thetas[0]) / (zs[1] - zs[0])
+            n_sfc = math.sqrt(max(9.80665 / thetas[0] * dth, 0.0))
+            u_sfc = abs(float(us[0])) or 1e-6
+            h_m = (p_mtn_h if p_mtn_h is not None else 0.5) * 1000.0
+            nhu = n_sfc * h_m / u_sfc
+        else:
+            # L = N/U for uniform U → N = L·U, and Nh/U = L·h.
+            L_lower_m = params["L_lower"] * 1e-4
+            nhu = L_lower_m * params["mtn_h"] * 1000.0
+
+        if nhu < 0.5:
+            flag = "linear regime"
+        elif nhu < 0.85:
+            flag = "approaching nonlinear"
+        elif nhu < 1.2:
+            flag = "near breaking — results questionable"
+        else:
+            flag = "past breaking — model unreliable"
+
+        scorer_badge = html.Span(
+            [
+                html.B("Scorer condition"),
+                html.Span(f"{scorer:.3f}", className="v"),
+                html.Span("(trapped > 1)", className="note"),
+            ]
+        )
+        rossby_badge = html.Span(
+            [
+                html.B(f"Rossby number ({lat:.0f}°N)"),
+                html.Span(f"{rossby:.2f}", className="v"),
+                html.Span("(Coriolis significant if ≲ 1)", className="note"),
+            ]
+        )
+        nonlin_badge = html.Span(
+            [
+                html.B("Nh/U (nonlinearity)"),
+                html.Span(f"{nhu:.2f}", className="v"),
+                html.Span(f"({flag})", className="note"),
+            ]
+        )
+        # Critical-level detection — profile mode only. The two-layer mode
+        # carries a single scalar U, so a "wind reversal" isn't even
+        # representable there, and the badge just states that.
+        if mode == "profile":
+            from .reference import critical_levels as _critical_levels
+            us_p = np.asarray(store["u"])
+            zs_p = np.asarray(store["z"])
+            crits = _critical_levels(zs_p, us_p)
+            if crits:
+                heights_km = ", ".join(f"{h/1000.0:.2f}" for h in crits)
+                critical_badge = html.Span(
+                    [
+                        html.B("⚠️ Critical level(s)"),
+                        html.Span(f"z = {heights_km} km", className="v"),
+                        html.Span(
+                            "(U = 0 → linear theory breaks down; results near "
+                            "these heights are not physical)",
+                            className="note",
+                        ),
+                    ]
+                )
+            else:
+                critical_badge = html.Span(
+                    [
+                        html.B("Critical levels"),
+                        html.Span("none", className="v"),
+                        html.Span("(U does not cross zero)", className="note"),
+                    ]
+                )
+        else:
+            critical_badge = html.Span(
+                [
+                    html.B("Critical levels"),
+                    html.Span("n/a", className="v"),
+                    html.Span(
+                        "(two-layer mode uses a single U; switch to Profile "
+                        "mode to prescribe wind reversals)",
+                        className="note",
+                    ),
+                ]
+            )
+        return sfig, wfig, upfig, scorer_badge, rossby_badge, nonlin_badge, critical_badge
+
+    # --- profile editing ---------------------------------------------------
+    # Drag-on-graph → update store. Each profile point is a Plotly "shape",
+    # and Plotly emits relayoutData entries like {"shapes[3].xanchor": ...}
+    # when a shape is dragged. We read that, clamp it into the axis range
+    # (so a stray drag off-screen cannot turn the profile into nonsense),
+    # and push the previous store onto the undo history before committing.
+    @app.callback(
+        [
+            Output("profile-store", "data", allow_duplicate=True),
+            Output("profile-history", "data", allow_duplicate=True),
+        ],
+        [
+            Input("u-profile-graph", "relayoutData"),
+            Input("theta-profile-graph", "relayoutData"),
+            Input("reset-profile", "n_clicks"),
+            Input("undo-profile", "n_clicks"),
+        ],
+        [
+            State("profile-store", "data"),
+            State("profile-history", "data"),
+        ],
+        prevent_initial_call=True,
+    )
+    def _profile_update(u_relay, th_relay, reset_clicks, undo_clicks, store, history):
+        from dash import ctx
+
+        trig = ctx.triggered_id
+        history = list(history or [])
+
+        def _push(snapshot):
+            # Deduplicate and cap length.
+            if history and history[-1] == snapshot:
+                return
+            history.append(snapshot)
+            if len(history) > UNDO_HISTORY_MAX:
+                del history[: len(history) - UNDO_HISTORY_MAX]
+
+        def _snapshot(s):
+            # Deep-ish copy — plain lists/floats survive JSON round-tripping fine.
+            return {
+                "z": list(s["z"]),
+                "u": list(s["u"]),
+                "theta": list(s["theta"]),
+            }
+
+        # ---- undo -------------------------------------------------------
+        if trig == "undo-profile":
+            if not history:
+                return no_update, no_update
+            prev = history.pop()
+            return prev, history
+
+        # ---- reset ------------------------------------------------------
+        if trig == "reset-profile":
+            _push(_snapshot(store))
+            zs, us, thetas = _init_profile_figures()
+            return (
+                {"z": zs.tolist(), "u": us.tolist(), "theta": thetas.tolist()},
+                history,
+            )
+
+        # ---- drag -------------------------------------------------------
+        lo, hi = (U_RANGE if trig == "u-profile-graph" else THETA_RANGE)
+
+        def _has_shape_keys(relay):
+            return bool(relay) and any(
+                isinstance(k, str) and k.startswith("shapes[") for k in relay.keys()
+            )
+
+        def _apply(relay, current):
+            """Pull new values out of a relayoutData payload and clamp them.
+
+            We ONLY honor ``shapes[i].xanchor`` here. Pixel-sized circles
+            also emit ``shapes[i].x0`` / ``x1`` when the user accidentally
+            grabs a resize handle — but those are *pixel* offsets, not data
+            coordinates, so averaging them yields garbage (which was the
+            bug behind "value shoots off-screen" reports). Rejecting
+            resize emissions means an edge-grab just does nothing instead
+            of corrupting the profile.
+            """
+            if not relay:
+                return current, False
+            out = list(current)
+            changed = False
+            for i in range(len(out)):
+                kxa = f"shapes[{i}].xanchor"
+                if kxa not in relay:
+                    continue
+                try:
+                    v = float(relay[kxa])
+                except (TypeError, ValueError):
+                    continue
+                if not math.isfinite(v):
+                    continue
+                v = max(lo, min(hi, v))
+                if v != out[i]:
+                    out[i] = v
+                    changed = True
+            return out, changed
+
+        if trig == "u-profile-graph":
+            relay, field = u_relay, "u"
+        elif trig == "theta-profile-graph":
+            relay, field = th_relay, "theta"
+        else:
+            return no_update, no_update
+
+        new_values, changed = _apply(relay, store[field])
+        shape_edit = _has_shape_keys(relay)
+        if changed:
+            _push(_snapshot(store))
+            store[field] = new_values
+        if not changed and not shape_edit:
+            # Nothing shape-related happened (pan, zoom, autosize) —
+            # leave the store alone so _redraw_profiles doesn't fire.
+            return no_update, no_update
+        # Bump a revision stamp on every shape event so the redraw
+        # callback fires even if the edit was rejected (e.g. a resize-
+        # handle grab). This snaps any stretched oval back to its
+        # canonical round shape.
+        store["_rev"] = int(store.get("_rev", 0)) + 1
+        return store, history
+
+    # Enable/disable the undo button and show a depth hint.
+    @app.callback(
+        [
+            Output("undo-profile", "disabled"),
+            Output("undo-status", "children"),
+        ],
+        Input("profile-history", "data"),
+    )
+    def _undo_status(history):
+        n = len(history or [])
+        if n == 0:
+            return True, ""
+        return False, f"{n} edit{'s' if n != 1 else ''} in history"
+
+    # --- HRRR profile fetch ----------------------------------------------
+    # Pulls U, V, T, HGT from the HRRR 0-h analysis on AWS (byte-range
+    # subset via the .idx sidecar), computes θ, and caches the raw east/north
+    # wind components in ``hrrr-raw-store``. The initial along-flow projection
+    # uses the current ``hrrr-dir`` slider value; further slider moves reuse
+    # the cached column (see ``_hrrr_redirect``) so no re-download is needed.
+    @app.callback(
+        [
+            Output("profile-store", "data", allow_duplicate=True),
+            Output("profile-history", "data", allow_duplicate=True),
+            Output("hrrr-raw-store", "data"),
+            Output("hrrr-status", "children"),
+            Output("hrrr-status", "className"),
+        ],
+        Input("hrrr-fetch", "n_clicks"),
+        [
+            State("hrrr-lat", "value"),
+            State("hrrr-lon", "value"),
+            State("hrrr-dir", "value"),
+            State("hrrr-datetime", "value"),
+            State("profile-store", "data"),
+            State("profile-history", "data"),
+        ],
+        prevent_initial_call=True,
+    )
+    def _hrrr_fetch(n_clicks, lat, lon, flow_deg, yyyymmddhh, store, history):
+        if not n_clicks:
+            return no_update, no_update, no_update, no_update, no_update
+
+        # Basic input validation — bail out early with a clear message
+        # rather than making the user wait on a network round-trip.
+        try:
+            lat_f = float(lat)
+            lon_f = float(lon)
+            flow_f = float(flow_deg)
+        except (TypeError, ValueError):
+            return (
+                no_update,
+                no_update,
+                no_update,
+                "Lat / Lon / Flow dir must all be numbers.",
+                "mw-hrrr-status error",
+            )
+        if not (-90.0 <= lat_f <= 90.0):
+            return (
+                no_update,
+                no_update,
+                no_update,
+                f"Lat {lat_f} outside [-90, 90].",
+                "mw-hrrr-status error",
+            )
+
+        try:
+            from .hrrr import along_flow_signed, fetch_profile
+        except ImportError as exc:
+            return (
+                no_update,
+                no_update,
+                no_update,
+                f"HRRR module failed to import: {exc}",
+                "mw-hrrr-status error",
+            )
+
+        zs_target = np.asarray(store["z"], dtype=float)
+        try:
+            z, u_raw, v_raw, theta, meta = fetch_profile(
+                lat_f, lon_f, yyyymmddhh, z_target_m=zs_target
+            )
+        except Exception as exc:
+            import traceback
+            traceback.print_exc()
+            return (
+                no_update,
+                no_update,
+                no_update,
+                f"Fetch failed: {exc}",
+                "mw-hrrr-status error",
+            )
+
+        # Don't clip HRRR data — the widened U_RANGE / THETA_RANGE should
+        # accommodate most real columns, and silently clamping was masking
+        # real wind and temperature structure (negative along-flow legs,
+        # cold-air-mass surface θ, etc.). If a sample still falls outside
+        # the axis, the editor auto-extends at render time.
+        u_arr = np.asarray(u_raw, dtype=float)
+        v_arr = np.asarray(v_raw, dtype=float)
+        th_arr = np.asarray(theta, dtype=float)
+        # Signed projection — wind reversals (e.g. an easterly jet when the
+        # user specified flow_from_deg corresponding to westerly) produce
+        # negative values, which the solver handles via the Scorer critical-
+        # level clamp and the "⚠️ Critical level" diagnostic badge.
+        u_along = along_flow_signed(u_arr, v_arr, flow_f)
+
+        # Push current state onto history so the fetch is undoable.
+        history = list(history or [])
+        snap = {"z": list(store["z"]), "u": list(store["u"]), "theta": list(store["theta"])}
+        if not history or history[-1] != snap:
+            history.append(snap)
+            if len(history) > UNDO_HISTORY_MAX:
+                del history[: len(history) - UNDO_HISTORY_MAX]
+
+        new_store = {
+            "z": zs_target.tolist(),
+            "u": u_along.tolist(),
+            "theta": th_arr.tolist(),
+            "_rev": int(store.get("_rev", 0)) + 1,
+        }
+        # Cache raw east/north wind (and θ / z) so the slider can re-project
+        # without re-downloading. Meta is kept so the status message can be
+        # refreshed after a reprojection.
+        raw_store = {
+            "z": zs_target.tolist(),
+            "u": u_arr.tolist(),
+            "v": v_arr.tolist(),
+            "theta": th_arr.tolist(),
+            "meta": {
+                "s3_key": meta.get("s3_key"),
+                "grid_lat": float(meta.get("grid_lat", float("nan"))),
+                "grid_lon": float(meta.get("grid_lon", float("nan"))),
+                "bytes": int(meta.get("bytes", 0)),
+                "n_levels": int(meta.get("n_levels", 0)),
+                "cycle": yyyymmddhh,
+            },
+        }
+        mb = meta["bytes"] / 1e6
+        msg = (
+            f"HRRR {yyyymmddhh} at grid point "
+            f"({meta['grid_lat']:.3f}°N, {meta['grid_lon']:.3f}°E) — "
+            f"{meta['n_levels']} levels, {mb:.1f} MB fetched. "
+            f"Flow from {flow_f:.0f}°."
+        )
+        return new_store, history, raw_store, msg, "mw-hrrr-status ok"
+
+    # --- HRRR reprojection on slider change ------------------------------
+    # When the flow-from slider moves, reuse the cached raw column (if any)
+    # and rewrite just the profile-store's u field. No network activity.
+    @app.callback(
+        [
+            Output("profile-store", "data", allow_duplicate=True),
+            Output("hrrr-status", "children", allow_duplicate=True),
+            Output("hrrr-status", "className", allow_duplicate=True),
+        ],
+        Input("hrrr-dir", "value"),
+        [
+            State("hrrr-raw-store", "data"),
+            State("profile-store", "data"),
+        ],
+        prevent_initial_call=True,
+    )
+    def _hrrr_redirect(flow_deg, raw, store):
+        # No cached column yet — slider moves before any fetch should be
+        # silent no-ops. (The next Fetch will pick up the current value.)
+        if not raw or "u" not in raw or "v" not in raw:
+            return no_update, no_update, no_update
+        try:
+            flow_f = float(flow_deg)
+        except (TypeError, ValueError):
+            return no_update, no_update, no_update
+
+        try:
+            from .hrrr import along_flow_signed
+        except ImportError:
+            return no_update, no_update, no_update
+
+        u_raw = np.asarray(raw["u"], dtype=float)
+        v_raw = np.asarray(raw["v"], dtype=float)
+        # Signed projection — keep wind reversals instead of clipping to 0.
+        u_along = along_flow_signed(u_raw, v_raw, flow_f)
+
+        new_store = {
+            "z": list(raw["z"]),
+            "u": u_along.tolist(),
+            "theta": list(raw["theta"]),
+            "_rev": int((store or {}).get("_rev", 0)) + 1,
+        }
+        meta = raw.get("meta", {}) or {}
+        cycle = meta.get("cycle", "")
+        mb = float(meta.get("bytes", 0)) / 1e6
+        n_levels = int(meta.get("n_levels", 0))
+        glat = meta.get("grid_lat")
+        glon = meta.get("grid_lon")
+        if glat is not None and glon is not None:
+            loc = f"({glat:.3f}°N, {glon:.3f}°E)"
+        else:
+            loc = ""
+        msg = (
+            f"HRRR {cycle} at grid point {loc} — {n_levels} levels, "
+            f"{mb:.1f} MB cached. Reprojected: flow from {flow_f:.0f}°."
+        )
+        return new_store, msg, "mw-hrrr-status ok"
+
+    # Store → figures. Whenever the store changes we regenerate both
+    # editable profile figures (so the line follows the dragged shapes)
+    # and all four diagnostic profiles (L², Ri, N², dθ/dz).
+    @app.callback(
+        [
+            Output("u-profile-graph", "figure"),
+            Output("theta-profile-graph", "figure"),
+            Output("diag-scorer", "figure"),
+            Output("diag-ri", "figure"),
+            Output("diag-n2", "figure"),
+            Output("diag-dthdz", "figure"),
+        ],
+        Input("profile-store", "data"),
+    )
+    def _redraw_profiles(store):
+        zs = np.asarray(store["z"])
+        us = np.asarray(store["u"])
+        thetas = np.asarray(store["theta"])
+        u_fig = _profile_editor_figure("Zonal wind u(z)", us, zs, xunit="m s⁻¹", xrange=U_RANGE)
+        th_fig = _profile_editor_figure(
+            "Potential temperature θ(z)", thetas, zs, xunit="K", xrange=THETA_RANGE
+        )
+        l_fig, ri_fig, n2_fig, dthdz_fig = _diagnostic_figures(store)
+        return u_fig, th_fig, l_fig, ri_fig, n2_fig, dthdz_fig
+
+
+def main():
+    app = create_app()
+    app.run(debug=False, host="127.0.0.1", port=8050)
+
+
+if __name__ == "__main__":
+    main()

python/mountain_waves/hrrr.py

@@ -0,0 +1,369 @@
+"""HRRR-on-AWS profile fetcher.
+
+Pulls a vertical profile of wind and temperature out of the HRRR analysis
+(0-h forecast) on the NODD public bucket ``noaa-hrrr-bdp-pds`` and returns
+it as (z, u_along, theta) arrays ready to drop into the profile editor.
+
+Design notes
+------------
+The full ``wrfprsf00.grib2`` is ~140 MB. We only need a handful of fields
+(HGT, TMP, UGRD, VGRD on pressure levels) at a single grid cell, so we:
+
+1. Fetch the ``.idx`` sidecar (a few kB) to find byte offsets.
+2. Issue ranged GETs for just the GRIB messages we need (few MB total).
+3. Splice them together into a local scratch file.
+4. Open with cfgrib, pick the nearest grid column, and compute θ and the
+   user-specified flow-direction wind component.
+
+Dependencies: ``boto3``, ``xarray``, ``cfgrib``. cfgrib needs the eccodes
+C library; we pull it in from PyPI only (via ``eccodes`` + ``eccodeslib``
+on macOS/Linux, or ``eccodes`` + ``ecmwflibs`` on Windows) rather than a
+system package, so ``uv sync`` is enough and no ``brew install eccodes``
+step is required. See ``pyproject.toml`` for the platform markers.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List, Tuple
+
+import numpy as np
+
+BUCKET = "noaa-hrrr-bdp-pds"
+R_OVER_CP = 0.2854  # R_d / c_p for dry air
+
+# Variables and level type we care about.
+_WANTED_VARS = ("HGT", "TMP", "UGRD", "VGRD")
+_LEVEL_SUFFIX = "mb"
+
+
+@dataclass
+class _IdxRecord:
+    num: int
+    start: int
+    var: str
+    level_mb: float
+
+
+def _parse_yyyymmddhh(s: str) -> datetime:
+    s = (s or "").strip()
+    if len(s) != 10 or not s.isdigit():
+        raise ValueError(
+            f"Expected YYYYMMDDHH (10 digits); got {s!r}. "
+            f"Example: 2024060112"
+        )
+    return datetime.strptime(s, "%Y%m%d%H")
+
+
+def _s3_key(dt: datetime) -> str:
+    return f"hrrr.{dt:%Y%m%d}/conus/hrrr.t{dt:%H}z.wrfprsf00.grib2"
+
+
+def _unsigned_s3_client():
+    """boto3 client configured for anonymous (unsigned) access."""
+    import boto3
+    from botocore import UNSIGNED
+    from botocore.config import Config
+
+    return boto3.client("s3", config=Config(signature_version=UNSIGNED))
+
+
+def _parse_idx(idx_text: str) -> Tuple[List[_IdxRecord], List[int]]:
+    """Parse the HRRR .idx file into (wanted_records, all_start_bytes).
+
+    Format of each line (colon-separated):
+        record_num:start_byte:d=YYYYMMDDHH:VAR:LEVEL:FCST:anl
+    """
+    wanted: List[_IdxRecord] = []
+    all_starts: List[int] = []
+    for line in idx_text.splitlines():
+        parts = line.split(":")
+        if len(parts) < 6 or not parts[1].isdigit():
+            continue
+        start = int(parts[1])
+        all_starts.append(start)
+        var = parts[3]
+        level = parts[4].strip()
+        if var not in _WANTED_VARS or not level.endswith(_LEVEL_SUFFIX):
+            continue
+        try:
+            level_mb = float(level.split()[0])
+        except ValueError:
+            continue
+        wanted.append(_IdxRecord(num=int(parts[0]), start=start, var=var, level_mb=level_mb))
+    return wanted, sorted(all_starts)
+
+
+def _byte_ranges(records: List[_IdxRecord], all_starts: List[int]) -> List[Tuple[int, int]]:
+    """Convert each wanted record's start byte to a (start, end) range.
+
+    End byte is the next record's start minus one, or open-ended for the
+    final record. We collapse adjacent ranges into contiguous chunks to
+    cut down on the number of HTTP calls.
+    """
+    ranges: List[Tuple[int, int]] = []
+    for r in records:
+        i = all_starts.index(r.start)
+        if i + 1 < len(all_starts):
+            end = all_starts[i + 1] - 1
+        else:
+            end = -1  # open-ended
+        ranges.append((r.start, end))
+    # Merge contiguous ranges to reduce request count.
+    ranges.sort()
+    merged: List[Tuple[int, int]] = []
+    for start, end in ranges:
+        if merged and end != -1 and merged[-1][1] != -1 and start == merged[-1][1] + 1:
+            merged[-1] = (merged[-1][0], end)
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def _download_subset(client, key: str, ranges: List[Tuple[int, int]]) -> bytes:
+    buf = io.BytesIO()
+    for start, end in ranges:
+        header = f"bytes={start}-" + ("" if end == -1 else str(end))
+        obj = client.get_object(Bucket=BUCKET, Key=key, Range=header)
+        buf.write(obj["Body"].read())
+    return buf.getvalue()
+
+
+def _nearest_ij(lats: np.ndarray, lons: np.ndarray, lat0: float, lon0: float) -> Tuple[int, int]:
+    """Nearest-neighbor grid cell to (lat0, lon0) on a 2-D HRRR grid."""
+    lon0 = ((lon0 + 180) % 360) - 180
+    # Convert HRRR lons to -180..180 as well.
+    lons = ((lons + 180) % 360) - 180
+    d2 = (lats - lat0) ** 2 + (lons - lon0) ** 2
+    j, i = np.unravel_index(np.argmin(d2), d2.shape)
+    return int(j), int(i)
+
+
+def along_flow_signed(
+    u: np.ndarray, v: np.ndarray, flow_from_deg: float
+) -> np.ndarray:
+    """Signed along-flow wind component for the mountain-wave solver.
+
+    ``flow_from_deg`` follows the standard meteorological convention — the
+    azimuth the wind is blowing *from* (270° = westerly, 160° = from the SSE).
+    The returned scalar is the signed component of the wind parallel to
+    that "from" direction: **positive** when the wind is blowing *from* a
+    direction within 90° of ``flow_from_deg``, and **negative** when the
+    wind reverses relative to that reference direction. Callers that
+    depended on the old zero-clipped behavior should take
+    ``np.maximum(along_flow_signed(...), 0.0)`` explicitly; the solver
+    itself now tolerates negative U via the Scorer-parameter critical-level
+    clamp, so wind reversals aloft should pass through unmodified and be
+    surfaced to the user as actual reversals.
+
+    Derivation: a wind with components ``(u, v)`` (east- and north-positive)
+    blowing *from* azimuth ``φ_act`` has magnitude ``s`` and
+    ``(u, v) = -s · (sin φ_act, cos φ_act)``. Projecting onto the unit
+    vector pointing in the direction the flow is going when it comes from
+    ``φ_spec`` (i.e. ``φ_spec + 180``) gives ``s · cos(φ_act − φ_spec)``.
+    That evaluates to ``-(u sin φ_spec + v cos φ_spec)``, positive when
+    actual and specified "from" directions are parallel and negative when
+    antiparallel. No clamping is applied.
+    """
+    rad = np.deg2rad(flow_from_deg)
+    return -(np.asarray(u) * np.sin(rad) + np.asarray(v) * np.cos(rad))
+
+
+# Backward-compatibility alias — the old name is retained so external
+# imports keep working, but it now returns the *signed* along-flow
+# component (no zero-clip). Callers that genuinely need the clipped
+# variant must apply ``np.maximum(_, 0.0)`` themselves.
+along_flow_positive = along_flow_signed
+
+
+def _theta(T_K: np.ndarray, p_hpa: np.ndarray) -> np.ndarray:
+    """Potential temperature (K) referenced to 1000 hPa."""
+    return T_K * (1000.0 / p_hpa) ** R_OVER_CP
+
+
+def fetch_profile(
+    lat: float,
+    lon: float,
+    yyyymmddhh: str,
+    z_target_m: np.ndarray | None = None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, dict]:
+    """Return ``(z, u, v, theta, meta)`` for the HRRR column at (lat, lon).
+
+    Raw east/north wind components are returned (not the along-flow
+    projection) so the caller can re-project onto any user-chosen flow
+    direction cheaply without re-downloading. Use :func:`along_flow_signed`
+    to turn ``(u, v, flow_from_deg)`` into the mountain-wave input; wind
+    reversals produce negative values, which the solver handles via the
+    Scorer critical-level clamp rather than silently clipping to zero.
+
+    Parameters
+    ----------
+    lat, lon : float
+        Point of interest in decimal degrees. ``lon`` may be ±180 or 0..360.
+    yyyymmddhh : str
+        UTC cycle time, e.g. ``"2024060112"``.
+    z_target_m : np.ndarray, optional
+        If given, the profile is linearly interpolated onto these heights
+        (meters above ground level). If ``None``, the native HRRR
+        pressure-level heights (AGL) are returned as ``z``.
+
+    Returns
+    -------
+    z : np.ndarray
+        Heights in m AGL.
+    u, v : np.ndarray
+        East- and north-positive wind components in m/s.
+    theta : np.ndarray
+        Potential temperature in K.
+    meta : dict
+        Diagnostic info (nearest grid lat/lon, S3 key, bytes transferred).
+    """
+    try:
+        import xarray as xr  # noqa: F401  (used via cfgrib backend)
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(
+            "xarray is required to read HRRR GRIB2. "
+            "Install with: pip install xarray cfgrib"
+        ) from exc
+
+    dt = _parse_yyyymmddhh(yyyymmddhh)
+    key = _s3_key(dt)
+    client = _unsigned_s3_client()
+
+    # 1. Fetch the .idx sidecar.
+    try:
+        idx_obj = client.get_object(Bucket=BUCKET, Key=key + ".idx")
+    except Exception as exc:
+        raise RuntimeError(
+            f"HRRR .idx not found at s3://{BUCKET}/{key}.idx "
+            f"(cycle may not exist yet). Error: {exc}"
+        ) from exc
+    idx_text = idx_obj["Body"].read().decode("utf-8", errors="replace")
+    records, all_starts = _parse_idx(idx_text)
+    if not records:
+        raise RuntimeError(f"No HGT/TMP/UGRD/VGRD pressure-level records in idx for {key}")
+
+    # 2. Byte-range fetch just the records we need.
+    ranges = _byte_ranges(records, all_starts)
+    blob = _download_subset(client, key, ranges)
+    bytes_downloaded = len(blob)
+
+    # 3. Splice into a scratch file and open with cfgrib.
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".grib2") as f:
+        f.write(blob)
+        grib_path = f.name
+
+    try:
+        import xarray as xr
+
+        ds = xr.open_dataset(
+            grib_path,
+            engine="cfgrib",
+            backend_kwargs={
+                "indexpath": "",  # don't leave .idx files around
+                "filter_by_keys": {"typeOfLevel": "isobaricInhPa"},
+            },
+        )
+
+        # cfgrib exposes variables as {'gh' or 'HGT', 't', 'u', 'v'} depending on
+        # shortName/cfName. Find them robustly.
+        def _pick(ds, candidates):
+            for name in candidates:
+                if name in ds.variables:
+                    return ds[name]
+            raise KeyError(f"None of {candidates} found in dataset: {list(ds.variables)}")
+
+        # cfgrib reads data lazily — it keeps the grib file open and re-reads
+        # when .values is touched. We delete the scratch file below, so we
+        # must materialize every array we care about *before* the unlink.
+        hgt_a = _pick(ds, ["gh", "HGT", "h"]).values
+        tmp_a = _pick(ds, ["t", "TMP"]).values
+        ugrd_a = _pick(ds, ["u", "UGRD"]).values
+        vgrd_a = _pick(ds, ["v", "VGRD"]).values
+        p_dim = "isobaricInhPa"
+        pressures_full = ds[p_dim].values.astype(float)  # hPa
+        lats_full = ds["latitude"].values
+        lons_full = ds["longitude"].values
+        ds.close()
+    finally:
+        try:
+            os.unlink(grib_path)
+        except OSError:
+            pass
+
+    # 4. Pick the nearest column.
+    j, i = _nearest_ij(lats_full, lons_full, lat, lon)
+    grid_lat = float(lats_full[j, i])
+    grid_lon = float(((lons_full[j, i] + 180) % 360) - 180)
+    pressures = pressures_full
+
+    h_col = hgt_a[:, j, i]  # geopotential height, m (MSL)
+    t_col = tmp_a[:, j, i]  # K
+    u_col = ugrd_a[:, j, i]
+    v_col = vgrd_a[:, j, i]
+
+    # Sort by pressure descending (so surface first, top last).
+    order = np.argsort(-pressures)
+    pressures = pressures[order]
+    h_col = h_col[order]
+    t_col = t_col[order]
+    u_col = u_col[order]
+    v_col = v_col[order]
+
+    # Keep only levels at or above ground (HRRR pressure levels below the
+    # surface are filled with extrapolated values — drop those by requiring
+    # monotonic height increase from the surface up).
+    sfc_h = float(np.min(h_col))
+    valid = h_col >= sfc_h - 1.0
+    h_col = h_col[valid]
+    t_col = t_col[valid]
+    u_col = u_col[valid]
+    v_col = v_col[valid]
+    pressures = pressures[valid]
+
+    # Make strictly monotonic increasing in height (in case of ties).
+    order = np.argsort(h_col)
+    h_col = h_col[order]
+    t_col = t_col[order]
+    u_col = u_col[order]
+    v_col = v_col[order]
+    pressures = pressures[order]
+
+    # Convert MSL heights to AGL by subtracting the lowest valid level.
+    z_agl = h_col - h_col[0]
+
+    theta = _theta(t_col, pressures)
+
+    if z_target_m is not None:
+        z_target = np.asarray(z_target_m, dtype=float)
+        # Clip target range to what HRRR actually covers at this point.
+        z_clipped = np.clip(z_target, float(z_agl[0]), float(z_agl[-1]))
+        u_out = np.interp(z_clipped, z_agl, u_col)
+        v_out = np.interp(z_clipped, z_agl, v_col)
+        th_out = np.interp(z_clipped, z_agl, theta)
+        z_out = z_target.copy()
+    else:
+        z_out = z_agl
+        u_out = u_col
+        v_out = v_col
+        th_out = theta
+
+    meta = {
+        "s3_key": key,
+        "grid_lat": grid_lat,
+        "grid_lon": grid_lon,
+        "bytes": bytes_downloaded,
+        "n_levels": int(z_agl.size),
+        "sfc_height_msl": float(h_col[0]),
+    }
+    return (
+        z_out.astype(float),
+        u_out.astype(float),
+        v_out.astype(float),
+        th_out.astype(float),
+        meta,
+    )

python/mountain_waves/profile.py

@@ -0,0 +1,90 @@
+"""Helpers for building and interpreting theta(z) / u(z) profiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+import numpy as np
+
+G = 9.80665
+
+
+def default_profile_heights(zdom_km: float = 10.0, n_points: int = 9) -> np.ndarray:
+    """Return ``n_points`` evenly spaced heights (meters) from 0 to ``zdom_km`` km."""
+    return np.linspace(0.0, zdom_km * 1000.0, n_points)
+
+
+def default_u_profile(zs: np.ndarray, u_surface: float = 20.0, shear: float = 0.5) -> np.ndarray:
+    """A gently sheared wind profile: ``u(z) = u_surface + shear * z_km``."""
+    zs_km = zs / 1000.0
+    return u_surface + shear * zs_km
+
+
+def default_theta_profile(
+    zs: np.ndarray,
+    theta_surface: float = 290.0,
+    lapse_lower: float = 3.0,
+    lapse_upper: float = 6.0,
+    interface_km: float = 3.5,
+) -> np.ndarray:
+    """A two-regime potential-temperature profile.
+
+    Stability contrast across ``interface_km`` mirrors the trapped-wave case
+    in the original MATLAB example: weaker stability below, stronger above.
+    """
+    zs_km = zs / 1000.0
+    theta = np.empty_like(zs_km)
+    for i, zkm in enumerate(zs_km):
+        if zkm <= interface_km:
+            theta[i] = theta_surface + lapse_lower * zkm
+        else:
+            theta[i] = (
+                theta_surface
+                + lapse_lower * interface_km
+                + lapse_upper * (zkm - interface_km)
+            )
+    return theta
+
+
+def brunt_vaisala(z: np.ndarray, theta: np.ndarray) -> np.ndarray:
+    """Finite-difference Brunt–Väisälä frequency squared (s⁻²)."""
+    z = np.asarray(z, dtype=float)
+    theta = np.asarray(theta, dtype=float)
+    n = z.size
+    n2 = np.empty(n)
+    for i in range(n):
+        if i == 0:
+            dthdz = (theta[1] - theta[0]) / (z[1] - z[0])
+        elif i == n - 1:
+            dthdz = (theta[-1] - theta[-2]) / (z[-1] - z[-2])
+        else:
+            dthdz = (theta[i + 1] - theta[i - 1]) / (z[i + 1] - z[i - 1])
+        n2[i] = (G / theta[i]) * dthdz
+    return n2
+
+
+def scorer_from_profile(z, u, theta) -> np.ndarray:
+    """Wrapper around the reference implementation for use in the UI."""
+    from .reference import scorer_from_profile as _imp
+    return _imp(z, u, theta)
+
+
+@dataclass
+class WaveProfile:
+    """Container for an edited profile displayed in the Dash app."""
+
+    z: np.ndarray = field(default_factory=lambda: default_profile_heights())
+    u: np.ndarray = field(default_factory=lambda: default_u_profile(default_profile_heights()))
+    theta: np.ndarray = field(default_factory=lambda: default_theta_profile(default_profile_heights()))
+
+    def as_lists(self) -> dict:
+        return {"z": list(map(float, self.z)), "u": list(map(float, self.u)), "theta": list(map(float, self.theta))}
+
+    @classmethod
+    def from_lists(cls, store: dict) -> "WaveProfile":
+        return cls(
+            z=np.asarray(store["z"], dtype=float),
+            u=np.asarray(store["u"], dtype=float),
+            theta=np.asarray(store["theta"], dtype=float),
+        )

python/mountain_waves/reference.py

@@ -0,0 +1,441 @@
+"""Pure-Python reference implementation of the mountain-wave solver.
+
+This module is a direct transcription of the MATLAB routines ``tlwplot.m``
+and ``stream.m`` written by Dr. Robert E. (Bob) Hart in 1995 as a Penn
+State Meteo 574 seminar project (see
+https://moe.met.fsu.edu/~rhart/mtnwave.html). The two-layer routine here
+mirrors Hart's MATLAB code line-for-line (reformulated in NumPy); the
+multi-layer routine is a natural generalization using the same Fourier +
+transfer-matrix scheme.
+
+It exists for two reasons:
+
+1. It's the fallback when the Rust extension isn't built.
+2. It's the reference used by ``validate.py`` to confirm the Rust core
+   produces bit-similar results.
+
+The multi-layer solver implements the same transfer-matrix scheme as the
+Rust version so they can be compared.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+G = 9.80665
+
+
+# ---------------------------------------------------------------------------
+# Two-layer analytic solver (port of tlwplot.m)
+# ---------------------------------------------------------------------------
+
+
+def compute_two_layer(
+    l_upper: float,
+    l_lower: float,
+    u: float,
+    h: float,
+    a: float,
+    ho: float,
+    xdom: float,
+    zdom: float,
+    mink: float,
+    maxk: float,
+    npts: int = 100,
+):
+    """Return ``(x, z, w, u_prime)`` for flow over a witch-of-Agnesi mountain.
+
+    Arrays match the MATLAB conventions: ``x`` has shape ``(npts + 1,)``,
+    ``z`` has shape ``(npts + 1,)``, and both ``w`` and ``u_prime`` have
+    shape ``(z.size, x.size)`` indexed as ``[z_index, x_index]``.
+
+    ``u_prime`` is the wave-induced horizontal wind perturbation, obtained
+    from linearized continuity ``∂u'/∂x + ∂w/∂z = 0``. Per wavenumber,
+    ``u'_k = −(i/k) · ∂ŵ_k/∂z``; we analytically differentiate the two-layer
+    eigenfunctions (``A e^{−n z}`` above the interface, ``C e^{i m z} +
+    D e^{−i m z}`` below) and accumulate the same trapezoidal k-integration
+    used for ``w``.
+    """
+    dk = 0.367 / a
+    nk = max(1, int((maxk - mink) // dk))
+
+    minx = -0.25 * xdom
+    maxx = 0.75 * xdom
+
+    dx = (maxx - minx) / npts
+    dz = zdom / npts
+
+    x = minx + dx * np.arange(npts + 1)
+    z = dz * np.arange(npts + 1)
+
+    X, Z = np.meshgrid(x, z)  # shape (npts+1, npts+1), Z[i, j] varies along i
+
+    matrix1 = np.zeros_like(X, dtype=complex)
+    matrix3 = np.zeros_like(X, dtype=complex)
+    matrix1_u = np.zeros_like(X, dtype=complex)
+    matrix3_u = np.zeros_like(X, dtype=complex)
+    ht = 0.0
+
+    for kloop in range(nk + 1):
+        kk = mink + dk * kloop
+        m = np.sqrt(complex(l_lower ** 2 - kk ** 2))
+        n = np.sqrt(complex(kk ** 2 - l_upper ** 2))
+        denom = m + 1j * n
+        if abs(denom) < 1e-300:
+            r = complex(9e99, 0.0)
+        else:
+            r = (m - 1j * n) / denom
+        R = r * np.exp(2j * m * h)
+        A = (1 + r) * np.exp(h * n + 1j * h * m) / (1 + R)
+        C = 1.0 / (1 + R)
+        D = R * C
+
+        ksign = abs(kk)
+        hs = np.pi * a * ho * np.exp(-a * ksign)
+        ht += np.pi * dk * a * np.exp(-a * ksign) if kloop > 0 else 0.0
+
+        above = A * np.exp(-Z * n) * (Z > h)
+        below = (C * np.exp(1j * Z * m) + D * np.exp(-1j * Z * m)) * (Z <= h)
+        matrix2 = (-1j * kk * hs * u * (above + below)) * np.exp(-1j * X * kk)
+
+        # Analytic z-derivative of the eigenfunctions (the two branches are
+        # continuous at z=h by construction, so the jump in the step factor
+        # contributes nothing to the derivative inside each region).
+        dabove = (-n) * A * np.exp(-Z * n) * (Z > h)
+        dbelow = (1j * m) * (C * np.exp(1j * Z * m) - D * np.exp(-1j * Z * m)) * (Z <= h)
+        # u'_k(x, z) = (-i/k) · ∂ŵ_k/∂z. Combining the −ik factor baked into
+        # matrix2's ŵ formula with the −i/k in front yields −hs·U·∂(above+
+        # below)/∂z. This removes the apparent 1/k singularity at k=0 — the
+        # result is analytic there — and avoids division edge cases.
+        matrix2_u = (-hs * u) * (dabove + dbelow) * np.exp(-1j * X * kk)
+
+        if kloop > 0:
+            matrix3 += 0.5 * (matrix1 + matrix2) * dk
+            matrix3_u += 0.5 * (matrix1_u + matrix2_u) * dk
+        matrix1 = matrix2
+        matrix1_u = matrix2_u
+
+    if ht == 0.0:
+        ht = 1.0
+    w = np.real(matrix3 / ht)
+    u_prime = np.real(matrix3_u / ht)
+    return x, z, w, u_prime
+
+
+# ---------------------------------------------------------------------------
+# Multi-layer profile solver
+# ---------------------------------------------------------------------------
+
+
+# Minimum |U| used in the Scorer-parameter denominator. In pure linear
+# theory, U(z) = 0 is a critical level where l² = N²/U² − (U″/U) is
+# singular; linear Scorer/Taylor-Goldstein cannot honestly solve across
+# such a level. In a teaching tool we *want* students to be able to set
+# up a wind-reversal profile and see what happens away from the critical
+# level rather than have the whole solve NaN out. We clamp |U| to this
+# floor (preserving sign) when evaluating the Scorer coefficients. Away
+# from U≈0 this is a no-op; within ±0.5 m/s it caps l² at a large but
+# finite value and the UI emits a "critical level detected" warning so
+# nobody is misled into treating the capped zone as physical.
+U_FLOOR_SCORER = 0.5  # m/s
+
+
+def _u_clamped_for_scorer(uu: float) -> float:
+    """Return ``uu`` with ``|uu|`` lifted to ``U_FLOOR_SCORER``; sign preserved."""
+    if uu >= 0.0:
+        return max(uu, U_FLOOR_SCORER)
+    return min(uu, -U_FLOOR_SCORER)
+
+
+def scorer_from_profile(z_profile, u_profile, theta_profile):
+    """Return Scorer parameter L^2(z) computed from profile data.
+
+    Handles wind reversals (sign changes in ``u_profile``) by clamping the
+    magnitude of ``U`` at ``U_FLOOR_SCORER`` when it evaluates the
+    ``N²/U² − U″/U`` combination. This keeps the solver numerically
+    well-behaved across a critical level (``U = 0``) at the cost of a
+    physically sharp feature there — see the ``critical_levels`` helper
+    below for the companion diagnostic surfaced in the UI.
+    """
+    z = np.asarray(z_profile, dtype=float)
+    u = np.asarray(u_profile, dtype=float)
+    theta = np.asarray(theta_profile, dtype=float)
+    n = z.size
+    l2 = np.zeros(n)
+    for i in range(n):
+        if i == 0:
+            dthdz = (theta[1] - theta[0]) / (z[1] - z[0])
+            if n >= 3:
+                h1 = z[1] - z[0]
+                h2 = z[2] - z[1]
+                d2u = 2.0 * (u[2] * h1 - u[1] * (h1 + h2) + u[0] * h2) / (h1 * h2 * (h1 + h2))
+            else:
+                d2u = 0.0
+        elif i == n - 1:
+            dthdz = (theta[-1] - theta[-2]) / (z[-1] - z[-2])
+            if n >= 3:
+                h1 = z[-2] - z[-3]
+                h2 = z[-1] - z[-2]
+                d2u = 2.0 * (u[-1] * h1 - u[-2] * (h1 + h2) + u[-3] * h2) / (h1 * h2 * (h1 + h2))
+            else:
+                d2u = 0.0
+        else:
+            h1 = z[i] - z[i - 1]
+            h2 = z[i + 1] - z[i]
+            dthdz = (
+                theta[i + 1] * h1 ** 2
+                - theta[i - 1] * h2 ** 2
+                + theta[i] * (h2 ** 2 - h1 ** 2)
+            ) / (h1 * h2 * (h1 + h2))
+            d2u = 2.0 * (u[i + 1] * h1 - u[i] * (h1 + h2) + u[i - 1] * h2) / (h1 * h2 * (h1 + h2))
+        n2 = (G / theta[i]) * dthdz
+        uu = _u_clamped_for_scorer(u[i])
+        l2[i] = n2 / uu ** 2 - d2u / uu
+    return l2
+
+
+def critical_levels(z_profile, u_profile):
+    """Return heights (m) where ``u_profile`` crosses zero, linearly interpolated.
+
+    A "critical level" for steady, 2-D, horizontally uniform linear mountain
+    waves is a height where the mean flow vanishes (``U = 0``). Linear
+    Scorer/Taylor-Goldstein theory is singular there — wave energy is
+    absorbed rather than propagated (Booker & Bretherton 1967) — so any
+    result the solver returns *near* a critical level should be read as
+    "this is where the linear model breaks down," not as a prediction.
+
+    Caller (the Dash UI) surfaces the returned heights in a diagnostics
+    badge so students can see where their profile is violating the
+    assumptions of the model.
+    """
+    z = np.asarray(z_profile, dtype=float)
+    u = np.asarray(u_profile, dtype=float)
+    heights = []
+    for i in range(1, z.size):
+        u_prev, u_curr = u[i - 1], u[i]
+        # Treat exact zeros as crossings at that sample.
+        if u_curr == 0.0:
+            heights.append(float(z[i]))
+            continue
+        if u_prev == 0.0:
+            # Already recorded by the previous iteration's "u_curr == 0" branch.
+            continue
+        if (u_prev > 0.0 and u_curr < 0.0) or (u_prev < 0.0 and u_curr > 0.0):
+            # Linear interp to the zero crossing.
+            t = u_prev / (u_prev - u_curr)
+            heights.append(float(z[i - 1] + t * (z[i] - z[i - 1])))
+    return heights
+
+
+def compute_from_profile(
+    z_profile,
+    u_profile,
+    theta_profile,
+    a: float,
+    ho: float,
+    xdom: float,
+    zdom: float,
+    mink: float,
+    maxk: float,
+    npts: int = 100,
+):
+    """Arbitrary u(z)/theta(z) mountain-wave solver using transfer matrices.
+
+    Returns ``(x, z, w, u_prime)``. The atmosphere is split into
+    piecewise-constant L² layers centered on the profile points. Inside
+    each layer the wave-transform equation reduces to an exponential
+    ansatz; continuity of ŵ and ŵ' at interfaces plus a radiation / decay
+    condition aloft closes the system.
+
+    The wave-induced horizontal wind perturbation ``u_prime`` is obtained
+    in the same Fourier loop: for each wavenumber ``k ≠ 0`` we take the
+    analytic z-derivative of the per-layer ŵ basis (``σ_j · (−a_j
+    e^{−σ_j Δz} + b_j e^{+σ_j Δz})``) and multiply by ``−i/k`` from the
+    linearized continuity relation ``u'_k = −(i/k) · ∂ŵ_k/∂z``.
+    """
+    zp = np.asarray(z_profile, dtype=float)
+    up = np.asarray(u_profile, dtype=float)
+    tp = np.asarray(theta_profile, dtype=float)
+    l2 = scorer_from_profile(zp, up, tp)
+    u_surface = float(up[0])
+
+    nlayers = zp.size
+    layer_bot = np.empty(nlayers)
+    layer_top = np.empty(nlayers)
+    for j in range(nlayers):
+        layer_bot[j] = 0.0 if j == 0 else 0.5 * (zp[j - 1] + zp[j])
+        layer_top[j] = np.inf if j == nlayers - 1 else 0.5 * (zp[j] + zp[j + 1])
+
+    dk = 0.367 / a
+    nk = max(1, int((maxk - mink) // dk))
+    nslab = nk + 1
+
+    minx = -0.25 * xdom
+    maxx = 0.75 * xdom
+    dx = (maxx - minx) / npts
+    dz = zdom / npts
+    x = minx + dx * np.arange(npts + 1)
+    z = dz * np.arange(npts + 1)
+
+    # Layer index for each vertical grid point
+    layer_of = np.zeros(z.size, dtype=int)
+    for j, zj in enumerate(z):
+        idx = nlayers - 1
+        for lj in range(nlayers):
+            if zj < layer_top[lj]:
+                idx = lj
+                break
+        layer_of[j] = idx
+
+    matrix1 = np.zeros((z.size, x.size), dtype=complex)
+    matrix3 = np.zeros((z.size, x.size), dtype=complex)
+    matrix1_u = np.zeros((z.size, x.size), dtype=complex)
+    matrix3_u = np.zeros((z.size, x.size), dtype=complex)
+    ht = 0.0
+
+    for kloop in range(nslab):
+        kk = mink + dk * kloop
+        ksign = abs(kk)
+        hs = np.pi * a * ho * np.exp(-a * ksign)
+        if kloop > 0:
+            ht += np.pi * dk * a * np.exp(-a * ksign)
+
+        if kk == 0.0:
+            # DC mode has no wave contribution; u' also vanishes here.
+            matrix2 = np.zeros_like(matrix1)
+            matrix2_u = np.zeros_like(matrix1)
+        else:
+            # Principal-branch sigma: in each layer, the "a" coefficient
+            # multiplies exp(-sigma*dz), which is always the outgoing /
+            # decaying branch when Im(sigma) >= 0.
+            sigma = np.empty(nlayers, dtype=complex)
+            for j in range(nlayers):
+                s = np.sqrt(complex(kk ** 2 - l2[j]))
+                if s.imag < 0:
+                    s = -s
+                sigma[j] = s
+
+            aj = np.zeros(nlayers, dtype=complex)
+            bj = np.zeros(nlayers, dtype=complex)
+            aj[-1] = 1.0
+            bj[-1] = 0.0
+            for j in range(nlayers - 2, -1, -1):
+                dz_j = layer_top[j] - layer_bot[j]
+                e_minus = np.exp(-sigma[j] * dz_j)
+                e_plus = np.exp(sigma[j] * dz_j)
+                alpha = aj[j + 1] + bj[j + 1]
+                beta = -aj[j + 1] + bj[j + 1]
+                ratio = sigma[j + 1] / sigma[j]
+                aj[j] = 0.5 * (alpha - ratio * beta) * e_plus
+                bj[j] = 0.5 * (alpha + ratio * beta) * e_minus
+
+            w_surface = aj[0] + bj[0]
+            if abs(w_surface) < 1e-300:
+                amp = 0.0 + 0.0j
+            else:
+                amp = -1j * kk * u_surface * hs / w_surface
+            aj *= amp
+            bj *= amp
+
+            # Build ŵ and ∂ŵ/∂z on the vertical grid. The per-layer basis
+            #   ŵ_j(z) = a_j e^{−σ_j Δz} + b_j e^{+σ_j Δz}
+            # differentiates cleanly to
+            #   ∂ŵ_j/∂z = σ_j · (−a_j e^{−σ_j Δz} + b_j e^{+σ_j Δz})
+            # and the continuity relation gives u'_k = −(i/k) · ∂ŵ/∂z.
+            zfac = np.zeros(z.size, dtype=complex)
+            zfac_u = np.zeros(z.size, dtype=complex)
+            inv_ik = -1j / kk
+            for j in range(z.size):
+                lj = layer_of[j]
+                dz_l = z[j] - layer_bot[lj]
+                e_minus = np.exp(-sigma[lj] * dz_l)
+                e_plus = np.exp(sigma[lj] * dz_l)
+                zfac[j] = aj[lj] * e_minus + bj[lj] * e_plus
+                dwdz = sigma[lj] * (-aj[lj] * e_minus + bj[lj] * e_plus)
+                zfac_u[j] = inv_ik * dwdz
+
+            xfac = np.exp(-1j * x * kk)
+            matrix2 = np.outer(zfac, xfac)
+            matrix2_u = np.outer(zfac_u, xfac)
+
+        if kloop > 0:
+            matrix3 += 0.5 * (matrix1 + matrix2) * dk
+            matrix3_u += 0.5 * (matrix1_u + matrix2_u) * dk
+        matrix1 = matrix2
+        matrix1_u = matrix2_u
+
+    if ht == 0.0:
+        ht = 1.0
+    w = np.real(matrix3 / ht)
+    u_prime = np.real(matrix3_u / ht)
+    return x, z, w, u_prime
+
+
+# ---------------------------------------------------------------------------
+# Streamline tracer (port of stream.m)
+# ---------------------------------------------------------------------------
+
+
+def streamlines(x, z, u, w, num: int = 10):
+    """Return ``num`` streamlines as ``[(xs, ys), ...]`` polylines.
+
+    ``u`` may be a scalar (uniform mean flow, used for the two-layer solver)
+    or a 1-D array of length ``nz`` giving the mean wind at each render-grid
+    height. In linear wave theory the parcel displacement at height ``z₀`` is
+    ``η(x, z₀) = (1/U(z₀)) · ∫ w(x', z₀) dx'``, so the time step used to
+    integrate along each streamline depends on the wind at that streamline's
+    height — not on the surface wind. Using a single scalar ``U_surface`` for
+    every streamline (as Hart's MATLAB ``stream.m`` did because the two-layer
+    case assumed uniform ``U``) over-amplifies upper streamlines whenever the
+    real profile has shear.
+
+    We guard against near-zero ``U(z₀)`` (which would blow up the tracer) with
+    a 0.1 m/s floor — a parcel literally at rest cannot trace a linear
+    streamline in this framework, so we just freeze it there.
+    """
+    x = np.asarray(x)
+    z = np.asarray(z)
+    w = np.asarray(w)
+    nx = x.size
+    nz = z.size
+    if nx < 2 or nz < 2 or num == 0:
+        return []
+    minx = float(x[0])
+    dx = float(x[1] - x[0])
+
+    u_arr = np.atleast_1d(np.asarray(u, dtype=float))
+    if u_arr.size == 1:
+        u_by_row = np.full(nz, float(u_arr[0]))
+    elif u_arr.size == nz:
+        u_by_row = u_arr
+    else:
+        # Caller gave an array of the wrong length — fall back to the mean so
+        # the plot still renders rather than raising mid-draw.
+        u_by_row = np.full(nz, float(np.mean(u_arr)))
+
+    dh = nz / num
+
+    lines = []
+    for j in range(num):
+        ycell = 1.0 + dh * j
+        if ycell < 1.0:
+            ycell = 1.0
+        if ycell > nz:
+            ycell = nz
+        yci = int(round(ycell) - 1)
+        yci = max(0, min(nz - 1, yci))
+        u_local = float(u_by_row[yci])
+        # 0.1 m/s floor prevents 1/u blowups at stagnant layers.
+        u_local = u_local if abs(u_local) > 0.1 else math.copysign(0.1, u_local) if u_local != 0 else 0.1
+        tstep = dx / u_local
+        xs = np.empty(nx)
+        ys = np.empty(nx)
+        xs[0] = minx
+        ys[0] = z[yci]
+        for i in range(1, nx):
+            xs[i] = x[i]
+            ys[i] = ys[i - 1] + tstep * w[yci, i]
+        lines.append((xs, ys))
+    return lines

python/mountain_waves/solver.py

@@ -0,0 +1,122 @@
+"""Backend selector: prefer the Rust extension, fall back to pure Python.
+
+Both paths expose identical call signatures so the Dash app doesn't need
+to care which one is running. ``backend_name()`` tells you which it is.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+import numpy as np
+
+try:  # pragma: no cover - import-time branching
+    from . import _core as _rust  # type: ignore
+
+    _BACKEND = "rust"
+    _RUST_IMPORT_ERROR: str | None = None
+except ImportError as _exc:
+    _rust = None  # type: ignore
+    _BACKEND = "python"
+    # Keep the real exception message around so the launcher can log it.
+    # ImportError on a Rust extension almost always means either the wheel
+    # never installed into site-packages, or it installed but a runtime
+    # dep (libc/libgomp/libpython ABI) can't be resolved. Silently falling
+    # back to the Python reference on a production deploy hides real bugs.
+    _RUST_IMPORT_ERROR = f"{type(_exc).__name__}: {_exc}"
+    import sys as _sys
+    print(
+        f"[mountain-waves] Rust _core import failed, using Python fallback: "
+        f"{_RUST_IMPORT_ERROR}",
+        file=_sys.stderr,
+        flush=True,
+    )
+
+from . import reference as _ref
+
+
+def backend_name() -> str:
+    """Return ``"rust"`` if the compiled extension is in use, else ``"python"``."""
+    return _BACKEND
+
+
+def _ensure_4tuple_two_layer(result, args):
+    """Coerce older Rust binaries (returning 3-tuples) into the 4-tuple ABI.
+
+    The Rust extension was extended to return u_prime alongside w. If the
+    user hasn't rebuilt the .so yet, fall back to the Python reference for
+    the full solve so u_prime is still correct rather than silently zero.
+    """
+    if isinstance(result, tuple) and len(result) == 4:
+        return result
+    # Stale binary — recompute via Python reference so u' is accurate.
+    return _ref.compute_two_layer(*args)
+
+
+def _ensure_4tuple_profile(result, args):
+    if isinstance(result, tuple) and len(result) == 4:
+        return result
+    return _ref.compute_from_profile(*args)
+
+
+def compute_two_layer(
+    l_upper: float,
+    l_lower: float,
+    u: float,
+    h: float,
+    a: float,
+    ho: float,
+    xdom: float,
+    zdom: float,
+    mink: float,
+    maxk: float,
+    npts: int = 100,
+):
+    args = (l_upper, l_lower, u, h, a, ho, xdom, zdom, mink, maxk, npts)
+    if _rust is not None:
+        return _ensure_4tuple_two_layer(_rust.compute_two_layer(*args), args)
+    return _ref.compute_two_layer(*args)
+
+
+def compute_from_profile(
+    z_profile,
+    u_profile,
+    theta_profile,
+    a: float,
+    ho: float,
+    xdom: float,
+    zdom: float,
+    mink: float,
+    maxk: float,
+    npts: int = 100,
+):
+    zp = np.ascontiguousarray(np.asarray(z_profile, dtype=np.float64))
+    up = np.ascontiguousarray(np.asarray(u_profile, dtype=np.float64))
+    tp = np.ascontiguousarray(np.asarray(theta_profile, dtype=np.float64))
+    args = (zp, up, tp, a, ho, xdom, zdom, mink, maxk, npts)
+    if _rust is not None:
+        return _ensure_4tuple_profile(_rust.compute_from_profile(*args), args)
+    return _ref.compute_from_profile(*args)
+
+
+def streamlines(x, z, u, w, num: int = 10) -> List[Tuple[np.ndarray, np.ndarray]]:
+    """Trace ``num`` linearized streamlines through the ``w(x, z)`` field.
+
+    ``u`` can be a scalar (uniform mean flow, as in the two-layer analytic)
+    or a 1-D array of length ``nz`` giving the mean wind at each render-grid
+    height. When an array is given we route through the Python tracer so the
+    per-streamline advection speed is ``U(z₀)``, not ``U_surface``.
+    """
+    x = np.ascontiguousarray(np.asarray(x, dtype=np.float64))
+    z = np.ascontiguousarray(np.asarray(z, dtype=np.float64))
+    w = np.ascontiguousarray(np.asarray(w, dtype=np.float64))
+    u_arr = np.atleast_1d(np.asarray(u, dtype=np.float64))
+    # Rust streamlines() only accepts scalar u. For array-valued u (profile
+    # mode with shear) dispatch to the Python tracer — it's only num*nx
+    # floating-point adds, so the perf difference is negligible.
+    if u_arr.size > 1:
+        return _ref.streamlines(x, z, u_arr, w, num)
+    u_scalar = float(u_arr[0])
+    if _rust is not None:
+        return _rust.streamlines(x, z, u_scalar, w, num)
+    return _ref.streamlines(x, z, u_scalar, w, num)

run.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Launcher for the Mountain Waves Dash app.
+
+Mountain Waves is a Rust + Python port of Dr. Robert E. (Bob) Hart's 1995
+MATLAB mountain-wave model (https://moe.met.fsu.edu/~rhart/mtnwave.html).
+
+Usage (with uv — recommended):
+    uv run python run.py                  # start the web UI on http://127.0.0.1:8050
+    uv run python run.py --port 9000      # alternate port
+    uv run python run.py --host 0.0.0.0   # expose on LAN
+
+Plain Python also works once dependencies are installed:
+    python run.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Make the in-tree Python package importable without installing.
+ROOT = Path(__file__).resolve().parent
+PKG_DIR = ROOT / "python"
+if str(PKG_DIR) not in sys.path:
+    sys.path.insert(0, str(PKG_DIR))
+
+from mountain_waves.app import create_app  # noqa: E402
+from mountain_waves import backend_name     # noqa: E402
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8050)
+    p.add_argument("--debug", action="store_true")
+    args = p.parse_args()
+
+    print(f"[mountain-waves] compute backend: {backend_name()}")
+    if backend_name() == "python":
+        print(
+            "[mountain-waves] running on the pure-Python reference solver.\n"
+            "                 Build the Rust core with `uv run maturin develop --release --uv`\n"
+            "                 (or `maturin develop --release`) for a ~20x speedup."
+        )
+
+    app = create_app()
+    app.run(host=args.host, port=args.port, debug=args.debug)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/lib.rs

@@ -0,0 +1,559 @@
+//! # mountain_waves core
+//!
+//! Rust port of Dr. Robert E. (Bob) Hart's 1995 MATLAB mountain-wave model
+//! (`tlwplot.m`, `tlwmenu.m`, `stream.m`). Hart developed the original tool
+//! as a Penn State Meteo 574 seminar project under Dr. Peter Bannon; the
+//! numerical scheme, user-interface layout, and example cases all come from
+//! his work. Documentation and MATLAB sources:
+//! <https://moe.met.fsu.edu/~rhart/mtnwave.html>. Contact: `rhart@fsu.edu`.
+//!
+//! Rust compute core for the 2-D mountain-wave visualization tool. This crate
+//! is compiled as a CPython extension module (`mountain_waves._core`) via
+//! PyO3 and exposes three callables to Python:
+//!
+//! * [`compute_two_layer`] — exact analytic two-layer Scorer-parameter
+//!   solution, a direct port of `tlwplot.m`.
+//! * [`compute_from_profile`] — multi-layer Taylor–Goldstein solver that
+//!   accepts arbitrary `u(z)` and `theta(z)` profiles.
+//! * [`streamlines`] — streamline-tracing helper that integrates a constant
+//!   `U` + perturbation `w(x, z)` field, returning a list of polylines.
+//!
+//! Arrays cross the Python boundary as NumPy arrays (via the `numpy` crate)
+//! to avoid per-point allocation. Wavenumber integration is parallelized
+//! over wavenumber samples with Rayon.
+
+use ndarray::{Array1, Array2};
+use num_complex::Complex64;
+use numpy::{IntoPyArray, PyArray1, PyArray2, PyReadonlyArray1, PyReadonlyArray2};
+use pyo3::prelude::*;
+use rayon::prelude::*;
+
+const I: Complex64 = Complex64::new(0.0, 1.0);
+
+fn c(x: f64) -> Complex64 {
+    Complex64::new(x, 0.0)
+}
+
+// ---------------------------------------------------------------------------
+// Two-layer analytic solver (port of tlwplot.m)
+// ---------------------------------------------------------------------------
+
+/// Compute vertical velocity `w(x, z)` and horizontal perturbation
+/// `u'(x, z)` for flow over a witch-of-Agnesi mountain in a two-layer
+/// atmosphere. `u'` is obtained per-wavenumber from
+/// `u'_k = −(i/k) · ∂ŵ_k/∂z`, which for this two-layer eigenbasis
+/// simplifies to `−h_s · U · ∂(above+below)/∂z` (the `1/k` and `k` cancel).
+///
+/// Arrays returned:
+///
+/// * `x` — shape `(npts + 1,)`, meters
+/// * `z` — shape `(npts + 1,)`, meters
+/// * `w` — shape `(nz, nx)` with rows along z, columns along x (m s⁻¹)
+/// * `u_prime` — same shape, m s⁻¹
+#[pyfunction]
+#[pyo3(signature = (l_upper, l_lower, u, h, a, ho, xdom, zdom, mink, maxk, npts=100))]
+#[allow(clippy::too_many_arguments)]
+fn compute_two_layer<'py>(
+    py: Python<'py>,
+    l_upper: f64,
+    l_lower: f64,
+    u: f64,
+    h: f64,
+    a: f64,
+    ho: f64,
+    xdom: f64,
+    zdom: f64,
+    mink: f64,
+    maxk: f64,
+    npts: usize,
+) -> PyResult<(
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray2<f64>>,
+    Bound<'py, PyArray2<f64>>,
+)> {
+    let (x, z, w, uprime) = py.allow_threads(|| {
+        two_layer(l_upper, l_lower, u, h, a, ho, xdom, zdom, mink, maxk, npts)
+    });
+    Ok((
+        x.into_pyarray_bound(py),
+        z.into_pyarray_bound(py),
+        w.into_pyarray_bound(py),
+        uprime.into_pyarray_bound(py),
+    ))
+}
+
+fn two_layer(
+    l_upper: f64,
+    l_lower: f64,
+    u: f64,
+    h: f64,
+    a: f64,
+    ho: f64,
+    xdom: f64,
+    zdom: f64,
+    mink: f64,
+    maxk: f64,
+    npts: usize,
+) -> (Array1<f64>, Array1<f64>, Array2<f64>, Array2<f64>) {
+    let dk = 0.367 / a;
+    let nk = (((maxk - mink) / dk).floor() as usize).max(1);
+    let nslab = nk + 1;
+
+    let minx = -0.25 * xdom;
+    let maxx = 0.75 * xdom;
+    let nx = npts + 1;
+    let nz = npts + 1;
+    let dx = (maxx - minx) / npts as f64;
+    let dz = zdom / npts as f64;
+
+    let x = Array1::from_iter((0..nx).map(|i| minx + dx * i as f64));
+    let z = Array1::from_iter((0..nz).map(|j| dz * j as f64));
+
+    // Each worker returns TWO complex slabs: one for ŵ, one for u'_complex.
+    let slabs: Vec<(Vec<Complex64>, Vec<Complex64>)> = (0..nslab)
+        .into_par_iter()
+        .map(|idx| {
+            let kk = mink + dk * idx as f64;
+            let ksign = kk.abs();
+
+            let m = c(l_lower * l_lower - kk * kk).sqrt();
+            let n = c(kk * kk - l_upper * l_upper).sqrt();
+
+            let denom = m + I * n;
+            let r = if denom.norm() < 1e-300 {
+                c(9e99)
+            } else {
+                (m - I * n) / denom
+            };
+            let big_r = r * (c(2.0) * I * m * h).exp();
+
+            let a_coef = (c(1.0) + r) * (c(h) * n + I * c(h) * m).exp() / (c(1.0) + big_r);
+            let c_coef = c(1.0) / (c(1.0) + big_r);
+            let d_coef = big_r * c_coef;
+
+            let hs = std::f64::consts::PI * a * ho * (-a * ksign).exp();
+
+            let mut slab_w = vec![Complex64::new(0.0, 0.0); nz * nx];
+            let mut slab_u = vec![Complex64::new(0.0, 0.0); nz * nx];
+            let prefactor_w = -I * c(kk) * c(hs * u);
+            // u'_k contribution: (-i/k) · ∂ŵ_k/∂z — the −ik factor inside
+            // ŵ cancels with the 1/k in the continuity relation, giving
+            // −h_s·U·∂(above+below)/∂z with no k-dependent prefactor.
+            let prefactor_u = c(-hs * u);
+
+            for (j, &zj) in z.iter().enumerate() {
+                let (zfac, dzfac) = if zj <= h {
+                    let e_plus = (I * c(zj) * m).exp();
+                    let e_minus = (-I * c(zj) * m).exp();
+                    let below = c_coef * e_plus + d_coef * e_minus;
+                    let dbelow = I * m * (c_coef * e_plus - d_coef * e_minus);
+                    (below, dbelow)
+                } else {
+                    let e = (-c(zj) * n).exp();
+                    let above = a_coef * e;
+                    let dabove = -n * a_coef * e;
+                    (above, dabove)
+                };
+                let row_scale_w = prefactor_w * zfac;
+                let row_scale_u = prefactor_u * dzfac;
+                let row_start = j * nx;
+                for (i, &xi) in x.iter().enumerate() {
+                    let xfac = (-I * c(xi * kk)).exp();
+                    slab_w[row_start + i] = row_scale_w * xfac;
+                    slab_u[row_start + i] = row_scale_u * xfac;
+                }
+            }
+            (slab_w, slab_u)
+        })
+        .collect();
+
+    let ht_samples: Vec<f64> = (0..nslab)
+        .map(|idx| {
+            let kk = mink + dk * idx as f64;
+            std::f64::consts::PI * dk * a * (-a * kk.abs()).exp()
+        })
+        .collect();
+
+    // Trapezoidal integration along the wavenumber axis for both fields.
+    let mut wc = vec![Complex64::new(0.0, 0.0); nz * nx];
+    let mut uc = vec![Complex64::new(0.0, 0.0); nz * nx];
+    for kloop in 1..nslab {
+        for i in 0..(nz * nx) {
+            wc[i] += c(0.5 * dk) * (slabs[kloop - 1].0[i] + slabs[kloop].0[i]);
+            uc[i] += c(0.5 * dk) * (slabs[kloop - 1].1[i] + slabs[kloop].1[i]);
+        }
+    }
+    let ht: f64 = ht_samples[1..].iter().sum();
+    let inv_ht = if ht.abs() > 0.0 { 1.0 / ht } else { 1.0 };
+
+    let mut w = Array2::<f64>::zeros((nz, nx));
+    let mut u_prime = Array2::<f64>::zeros((nz, nx));
+    for j in 0..nz {
+        for i in 0..nx {
+            w[[j, i]] = wc[j * nx + i].re * inv_ht;
+            u_prime[[j, i]] = uc[j * nx + i].re * inv_ht;
+        }
+    }
+
+    (x, z, w, u_prime)
+}
+
+// ---------------------------------------------------------------------------
+// Multi-layer profile solver
+// ---------------------------------------------------------------------------
+
+/// Multi-layer Taylor–Goldstein solver accepting arbitrary `u(z)` / `theta(z)`.
+///
+/// The solver uses the basis
+///
+///     ŵ_j(z) = a_j exp(-σ_j (z - z_bot_j)) + b_j exp(+σ_j (z - z_bot_j))
+///
+/// inside layer `j`, with `σ_j = sqrt(k² - L_j²)` taken on the principal
+/// branch (non-negative imaginary part). In this basis the `a` coefficient
+/// is always the outgoing branch — it decays upward when the layer is
+/// evanescent and has downward phase velocity (= upward group velocity) when
+/// the layer is propagating. The radiation / decay condition at the top of
+/// the domain is therefore simply `b_top = 0`.
+#[pyfunction]
+#[pyo3(signature = (z_profile, u_profile, theta_profile, a, ho, xdom, zdom, mink, maxk, npts=100))]
+#[allow(clippy::too_many_arguments)]
+fn compute_from_profile<'py>(
+    py: Python<'py>,
+    z_profile: PyReadonlyArray1<'py, f64>,
+    u_profile: PyReadonlyArray1<'py, f64>,
+    theta_profile: PyReadonlyArray1<'py, f64>,
+    a: f64,
+    ho: f64,
+    xdom: f64,
+    zdom: f64,
+    mink: f64,
+    maxk: f64,
+    npts: usize,
+) -> PyResult<(
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray2<f64>>,
+    Bound<'py, PyArray2<f64>>,
+)> {
+    let zp = z_profile.as_array().to_owned();
+    let up = u_profile.as_array().to_owned();
+    let tp = theta_profile.as_array().to_owned();
+    let (x, z, w, uprime) = py.allow_threads(|| {
+        multi_layer(&zp, &up, &tp, a, ho, xdom, zdom, mink, maxk, npts)
+    });
+    Ok((
+        x.into_pyarray_bound(py),
+        z.into_pyarray_bound(py),
+        w.into_pyarray_bound(py),
+        uprime.into_pyarray_bound(py),
+    ))
+}
+
+// Minimum |U| used in the Scorer-parameter denominator. At a critical
+// level (U = 0) linear Scorer/Taylor-Goldstein is singular — we clamp
+// |U| to U_FLOOR_SCORER (sign-preserving) so students can set up
+// wind-reversal profiles and still see the solver output away from the
+// critical level. The Python UI surfaces "⚠️ critical level at z=..."
+// from the companion `critical_levels` helper in reference.py so nothing
+// is silently smoothed over. Keep in sync with `U_FLOOR_SCORER` in
+// python/mountain_waves/reference.py.
+const U_FLOOR_SCORER: f64 = 0.5;
+
+fn u_clamped_for_scorer(uu: f64) -> f64 {
+    if uu >= 0.0 {
+        uu.max(U_FLOOR_SCORER)
+    } else {
+        uu.min(-U_FLOOR_SCORER)
+    }
+}
+
+fn scorer_from_profile(z: &Array1<f64>, u: &Array1<f64>, theta: &Array1<f64>) -> Array1<f64> {
+    const G: f64 = 9.80665;
+    let n = z.len();
+    let mut l2 = Array1::<f64>::zeros(n);
+    for i in 0..n {
+        let (dthdz, d2udz2) = if i == 0 {
+            let dth = (theta[1] - theta[0]) / (z[1] - z[0]);
+            let d2u = if n >= 3 {
+                let h1 = z[1] - z[0];
+                let h2 = z[2] - z[1];
+                2.0 * (u[2] * h1 - u[1] * (h1 + h2) + u[0] * h2) / (h1 * h2 * (h1 + h2))
+            } else {
+                0.0
+            };
+            (dth, d2u)
+        } else if i == n - 1 {
+            let dth = (theta[n - 1] - theta[n - 2]) / (z[n - 1] - z[n - 2]);
+            let d2u = if n >= 3 {
+                let h1 = z[n - 2] - z[n - 3];
+                let h2 = z[n - 1] - z[n - 2];
+                2.0 * (u[n - 1] * h1 - u[n - 2] * (h1 + h2) + u[n - 3] * h2) / (h1 * h2 * (h1 + h2))
+            } else {
+                0.0
+            };
+            (dth, d2u)
+        } else {
+            let h1 = z[i] - z[i - 1];
+            let h2 = z[i + 1] - z[i];
+            let dth = (theta[i + 1] * h1 * h1 - theta[i - 1] * h2 * h2
+                + theta[i] * (h2 * h2 - h1 * h1))
+                / (h1 * h2 * (h1 + h2));
+            let d2u = 2.0 * (u[i + 1] * h1 - u[i] * (h1 + h2) + u[i - 1] * h2) / (h1 * h2 * (h1 + h2));
+            (dth, d2u)
+        };
+        let n2 = (G / theta[i]) * dthdz;
+        let uu = u_clamped_for_scorer(u[i]);
+        l2[i] = n2 / (uu * uu) - d2udz2 / uu;
+    }
+    l2
+}
+
+/// Principal branch of sqrt chosen so that Im(result) ≥ 0 (or Re ≥ 0 when
+/// argument is a non-negative real). This corresponds to the outgoing /
+/// decaying branch of exp(-σz) for mountain-wave radiation conditions.
+fn principal_sigma(k2_minus_l2: f64) -> Complex64 {
+    let s = c(k2_minus_l2).sqrt();
+    if s.im < 0.0 {
+        -s
+    } else {
+        s
+    }
+}
+
+fn multi_layer(
+    z_profile: &Array1<f64>,
+    u_profile: &Array1<f64>,
+    theta_profile: &Array1<f64>,
+    a: f64,
+    ho: f64,
+    xdom: f64,
+    zdom: f64,
+    mink: f64,
+    maxk: f64,
+    npts: usize,
+) -> (Array1<f64>, Array1<f64>, Array2<f64>, Array2<f64>) {
+    let l2_profile = scorer_from_profile(z_profile, u_profile, theta_profile);
+    let u_surface = u_profile[0];
+
+    let nlayers = z_profile.len();
+    let mut layer_bot = Array1::<f64>::zeros(nlayers);
+    let mut layer_top = Array1::<f64>::zeros(nlayers);
+    for j in 0..nlayers {
+        layer_bot[j] = if j == 0 {
+            0.0
+        } else {
+            0.5 * (z_profile[j - 1] + z_profile[j])
+        };
+        layer_top[j] = if j == nlayers - 1 {
+            f64::INFINITY
+        } else {
+            0.5 * (z_profile[j] + z_profile[j + 1])
+        };
+    }
+
+    let dk = 0.367 / a;
+    let nk = (((maxk - mink) / dk).floor() as usize).max(1);
+    let nslab = nk + 1;
+
+    let minx = -0.25 * xdom;
+    let maxx = 0.75 * xdom;
+    let nx = npts + 1;
+    let nz = npts + 1;
+    let dx = (maxx - minx) / npts as f64;
+    let dz_grid = zdom / npts as f64;
+
+    let x = Array1::from_iter((0..nx).map(|i| minx + dx * i as f64));
+    let z = Array1::from_iter((0..nz).map(|j| dz_grid * j as f64));
+
+    let layer_of: Vec<usize> = z
+        .iter()
+        .map(|&zj| {
+            let mut idx = nlayers - 1;
+            for l in 0..nlayers {
+                if zj < layer_top[l] {
+                    idx = l;
+                    break;
+                }
+            }
+            idx
+        })
+        .collect();
+
+    // Each k sample produces slabs for BOTH ŵ and u'_complex. u'_k is
+    // computed from the analytic z-derivative of the layer eigenbasis:
+    //   ∂ŵ_j/∂z = σ_j · (−a_j e^{−σ Δz} + b_j e^{+σ Δz})
+    // multiplied by −i/k per the linearized continuity relation.
+    let slabs: Vec<(Vec<Complex64>, Vec<Complex64>)> = (0..nslab)
+        .into_par_iter()
+        .map(|idx| {
+            let kk = mink + dk * idx as f64;
+            let mut slab_w = vec![Complex64::new(0.0, 0.0); nz * nx];
+            let mut slab_u = vec![Complex64::new(0.0, 0.0); nz * nx];
+            if kk == 0.0 {
+                return (slab_w, slab_u);
+            }
+            let ksign = kk.abs();
+
+            let sigma: Vec<Complex64> = (0..nlayers)
+                .map(|j| principal_sigma(kk * kk - l2_profile[j]))
+                .collect();
+
+            // Top-down sweep: a_top = 1, b_top = 0.
+            let mut aj = vec![Complex64::new(0.0, 0.0); nlayers];
+            let mut bj = vec![Complex64::new(0.0, 0.0); nlayers];
+            aj[nlayers - 1] = c(1.0);
+            bj[nlayers - 1] = c(0.0);
+
+            for j in (0..nlayers - 1).rev() {
+                let dz_j = layer_top[j] - layer_bot[j];
+                let e_minus = (-sigma[j] * dz_j).exp();
+                let e_plus = (sigma[j] * dz_j).exp();
+                let alpha = aj[j + 1] + bj[j + 1];
+                let beta = -aj[j + 1] + bj[j + 1];
+                let ratio = sigma[j + 1] / sigma[j];
+                aj[j] = 0.5 * (alpha - ratio * beta) * e_plus;
+                bj[j] = 0.5 * (alpha + ratio * beta) * e_minus;
+            }
+
+            let hs = std::f64::consts::PI * a * ho * (-a * ksign).exp();
+            let w_surface_unnorm = aj[0] + bj[0];
+            let amp = if w_surface_unnorm.norm() < 1e-300 {
+                Complex64::new(0.0, 0.0)
+            } else {
+                -I * c(kk * u_surface * hs) / w_surface_unnorm
+            };
+            for j in 0..nlayers {
+                aj[j] *= amp;
+                bj[j] *= amp;
+            }
+
+            // Assemble slabs. u'_complex = (−i/k) · ∂ŵ/∂z per layer.
+            let inv_ik = -I / c(kk);
+            let xfac: Vec<Complex64> =
+                x.iter().map(|&xi| (-I * c(xi * kk)).exp()).collect();
+
+            for j in 0..nz {
+                let l = layer_of[j];
+                let dz_l = z[j] - layer_bot[l];
+                let e_minus = (-sigma[l] * dz_l).exp();
+                let e_plus = (sigma[l] * dz_l).exp();
+                let zval_w = aj[l] * e_minus + bj[l] * e_plus;
+                let dwdz = sigma[l] * (-aj[l] * e_minus + bj[l] * e_plus);
+                let zval_u = inv_ik * dwdz;
+                let row_start = j * nx;
+                for i in 0..nx {
+                    slab_w[row_start + i] = zval_w * xfac[i];
+                    slab_u[row_start + i] = zval_u * xfac[i];
+                }
+            }
+            (slab_w, slab_u)
+        })
+        .collect();
+
+    let ht_samples: Vec<f64> = (0..nslab)
+        .map(|idx| {
+            let kk = mink + dk * idx as f64;
+            std::f64::consts::PI * dk * a * (-a * kk.abs()).exp()
+        })
+        .collect();
+    let ht: f64 = ht_samples[1..].iter().sum();
+    let inv_ht = if ht.abs() > 0.0 { 1.0 / ht } else { 1.0 };
+
+    let mut wc = vec![Complex64::new(0.0, 0.0); nz * nx];
+    let mut uc = vec![Complex64::new(0.0, 0.0); nz * nx];
+    for kloop in 1..nslab {
+        for i in 0..(nz * nx) {
+            wc[i] += c(0.5 * dk) * (slabs[kloop - 1].0[i] + slabs[kloop].0[i]);
+            uc[i] += c(0.5 * dk) * (slabs[kloop - 1].1[i] + slabs[kloop].1[i]);
+        }
+    }
+
+    let mut w = Array2::<f64>::zeros((nz, nx));
+    let mut u_prime = Array2::<f64>::zeros((nz, nx));
+    for j in 0..nz {
+        for i in 0..nx {
+            w[[j, i]] = wc[j * nx + i].re * inv_ht;
+            u_prime[[j, i]] = uc[j * nx + i].re * inv_ht;
+        }
+    }
+
+    (x, z, w, u_prime)
+}
+
+// ---------------------------------------------------------------------------
+// Streamline tracer
+// ---------------------------------------------------------------------------
+
+#[pyfunction]
+#[pyo3(signature = (x, z, u, w, num=10))]
+fn streamlines<'py>(
+    py: Python<'py>,
+    x: PyReadonlyArray1<'py, f64>,
+    z: PyReadonlyArray1<'py, f64>,
+    u: f64,
+    w: PyReadonlyArray2<'py, f64>,
+    num: usize,
+) -> PyResult<Vec<(Bound<'py, PyArray1<f64>>, Bound<'py, PyArray1<f64>>)>> {
+    let xa = x.as_array().to_owned();
+    let za = z.as_array().to_owned();
+    let wa = w.as_array().to_owned();
+    let lines = py.allow_threads(|| trace_streamlines(&xa, &za, u, &wa, num));
+    Ok(lines
+        .into_iter()
+        .map(|(xs, ys)| (xs.into_pyarray_bound(py), ys.into_pyarray_bound(py)))
+        .collect())
+}
+
+fn trace_streamlines(
+    x: &Array1<f64>,
+    z: &Array1<f64>,
+    u: f64,
+    w: &Array2<f64>,
+    num: usize,
+) -> Vec<(Array1<f64>, Array1<f64>)> {
+    let nx = x.len();
+    let nz = z.len();
+    if nx < 2 || nz < 2 || num == 0 {
+        return Vec::new();
+    }
+    let minx = x[0];
+    let dx = x[1] - x[0];
+    let tstep = dx / u;
+    let dh = nz as f64 / num as f64;
+
+    let mut lines = Vec::with_capacity(num);
+    for j in 0..num {
+        let mut ycell = 1.0 + dh * j as f64;
+        if ycell < 1.0 {
+            ycell = 1.0;
+        }
+        if ycell > nz as f64 {
+            ycell = nz as f64;
+        }
+        let yci = (ycell.round() as isize - 1).clamp(0, nz as isize - 1) as usize;
+        let mut xs = Array1::<f64>::zeros(nx);
+        let mut ys = Array1::<f64>::zeros(nx);
+        xs[0] = minx;
+        ys[0] = z[yci];
+        for i in 1..nx {
+            xs[i] = x[i];
+            ys[i] = ys[i - 1] + tstep * w[[yci, i]];
+        }
+        lines.push((xs, ys));
+    }
+    lines
+}
+
+// ---------------------------------------------------------------------------
+// Module registration
+// ---------------------------------------------------------------------------
+
+#[pymodule]
+fn _core(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(compute_two_layer, m)?)?;
+    m.add_function(wrap_pyfunction!(compute_from_profile, m)?)?;
+    m.add_function(wrap_pyfunction!(streamlines, m)?)?;
+    m.add("__doc__", "Mountain Waves Rust compute core.")?;
+    Ok(())
+}

stream.m

@@ -0,0 +1,66 @@
+function[]=stream(x,y,U,v,num);
+%-------------------------------------------------------%
+% Matlab subroutine stream.m				%
+% Called by:  tlwplot.m					%
+%							%
+% by Robert Hart for Meteo 574 / Fall 95		%
+% Penn State University Meteorology                     %
+%							%
+% This subroutine performs a streamline analysis	%
+% of the wind field.  					%
+%							%
+% Parameters passed to this routine:			%
+% ----------------------------------			%
+% x	- array of x-gridpoints				%
+% y	- array of y-gridpoints				%
+% U 	- speed of x-direction wind (constant)		%	
+% v	- array of y-direction wind			%
+% num	- # of evenly spaced streamlines to draw	%
+%							%
+% NOTE:  Subroutine is written for a constant   	%
+% 	 horizontal wind velocity.			%
+%-------------------------------------------------------%
+hold;				% hold figure
+xsize=size(x);				
+xsize=xsize(1);			% size of x-grid
+ysize=size(y);
+ysize=ysize(2);                 % size of y-grid
+miny=y(1);                      % min. y-value                  
+maxy=y(ysize);                  % max. y-value
+minx=x(1);                      % min. x-value
+maxx=x(1,xsize);                % max. x-value
+
+dx=(maxx-minx)/xsize;           % x-dir gridspacing
+dy=(maxy-miny)/ysize;           % y-dir grid spacing
+dh=ysize/num;                   % streamline spacing
+
+tstep=dx/U;                     % time to cross cell
+
+mtncolor=[.02 .77 .02];         % color of mountain (lt green here)
+
+ycell=1;                        % initial location
+for j=1:num                     % streamline loop
+  ycell=1+dh*(j-1);             %   current y-location
+  if ycell < 1                  %   don't go outside array
+    ycell=1;
+  end;
+  if ycell > ysize              %   don't go outside array
+     ycell=ysize;
+  end;
+  ax=[];                        %   initialize lineplot arrays
+  ay=[];               
+  ax(1)=minx;                   
+  ay(1)=y(round(ycell));
+  ycell=int8(ycell);
+  for i=2:xsize;                %   streamline tracing loop
+     ax(i)=x(ycell,i);          %      calculate displacement
+     ay(i)=ay(i-1)+tstep*v(ycell,i);
+  end;                          %   end of loop
+  if j==1                       %   if first streamline                    
+     ax(xsize+1)=maxx;
+     ay(ysize+1)=miny;
+     fill(ax,ay,mtncolor);      %      solid-fill mountain
+  else                          %   otherwise,
+     line(ax,ay);	        %      draw streamline!
+  end;                          %   end of loop
+end;                            % the end;

tlwmenu.m

@@ -0,0 +1,800 @@
+function tlwmenu(command) 
+%---------------------------------------------------------------
+% Matlab Subroutine tlwmenu.M				
+%							
+% by Robert Hart for Meteo 574 / Fall 1995			
+% Penn State University Meteorology       
+% Updated 1 March 2018 to fix display bug in newer matlab versions
+% Updated 2 April 2018 to correctly display Rossby number
+%								
+% Interactive menu system used to control tlwplot.m		
+% a program which calculates and displays the airflow over 	
+% a mountain in the presence of a two-layer atmosphere.	
+%							
+% To execute:  tlwmenu					
+%---------------------------------------------------------------
+
+omega=7.292e-5;
+latit=pi/2;
+f=2*omega*sin(latit);
+
+if nargin == 0 
+	command = 'new'; 
+end 
+
+if isstr(command) 
+	if strcmp(lower(command),'initialize') | strcmp(lower(command),'new') 
+		command = 0; 
+	elseif strcmp(lower(command),lower('h_quit')) 
+		command = 1; 
+	elseif strcmp(lower(command),lower('h_info')) 
+		command = 2; 
+	elseif strcmp(lower(command),lower('h_analyze')) 
+		command = 3; 
+	elseif strcmp(lower(command),lower('h_maxk')) 
+		command = 4; 
+	elseif strcmp(lower(command),lower('h_mink')) 
+		command = 5; 
+	elseif strcmp(lower(command),lower('h_H')) 
+		command = 6; 
+	elseif strcmp(lower(command),lower('h_Llower')) 
+		command = 7; 
+	elseif strcmp(lower(command),lower('h_wndspd')) 
+		command = 8; 
+	elseif strcmp(lower(command),lower('h_Lupper')) 
+		command = 9; 
+	elseif strcmp(lower(command),lower('h_half')) 
+		command = 10; 
+	elseif strcmp(lower(command),lower('h_maxht')) 
+		command = 11; 
+	elseif strcmp(lower(command),lower('h_xwidth')) 
+		command = 12; 
+	elseif strcmp(lower(command),lower('h_vert')) 
+		command = 13; 
+        end 
+end 
+
+if command ~= 0 
+	h_fig_list = findobj(get(0,'children'),'flat',... 
+		'tag','tlwmenu'); 
+		if length(h_fig_list) > 1 
+			h_fig_list = gcf; 
+		elseif length(h_fig_list) == 0 
+			error('There are no figures with Tag = tlwmenu.'); 
+		end 
+	handle_list = get(h_fig_list,'userdata'); 
+	if length(handle_list) > 0 
+		h_quit = handle_list(1); 
+		h_disp = handle_list(2); 
+		h_analyze = handle_list(3); 
+		h_maxk = handle_list(4); 
+		h_mink = handle_list(5); 
+		h_H = handle_list(6); 
+		h_Llower = handle_list(7); 
+		h_wndspd = handle_list(8); 
+		h_Lupper = handle_list(9); 
+		h_half = handle_list(10); 
+		h_maxht = handle_list(11); 
+		h_xwidth = handle_list(12); 
+		h_vert = handle_list(13); 
+		h_uic_6 = handle_list(14); 
+		h_uic_25 = handle_list(15); 
+		h_uic_22 = handle_list(16); 
+		h_uic_20 = handle_list(17); 
+		h_uic_3 = handle_list(18); 
+		h_uic_15 = handle_list(19); 
+		h_uic_11 = handle_list(20); 
+		h_uic_19 = handle_list(21); 
+		h_uic_10 = handle_list(22); 
+		h_uic_13 = handle_list(23); 
+		h_uic_9 = handle_list(24); 
+		h_title = handle_list(25); 
+		h_mxkval = handle_list(26); 
+		h_separ = handle_list(27); 
+		h_uic_8 = handle_list(28); 
+		h_uic_1 = handle_list(29); 
+		h_mnkval = handle_list(30); 
+		h_wvalue = handle_list(31); 
+		h_Lupval = handle_list(32); 
+		h_Lloval = handle_list(33); 
+		h_Hval = handle_list(34); 
+		h_scorer = handle_list(35); 
+		h_wtitle = handle_list(36); 
+		h_Lupttl = handle_list(37); 
+		h_Llottl = handle_list(38); 
+		h_Htitle = handle_list(39); 
+		h_rossby = handle_list(40); 
+		h_uic_7 = handle_list(41); 
+		h_mtnval = handle_list(42); 
+		h_hlfval = handle_list(43); 
+		h_uic_2 = handle_list(44); 
+		h_uic_4 = handle_list(45); 
+		h_uic_14 = handle_list(46); 
+		h_uic_17 = handle_list(47); 
+		h_verval = handle_list(48); 
+		h_horval = handle_list(49); 
+	end 
+end 
+
+
+if command == 0 
+       
+	fig = figure('position',[ 320 240 600 450 ],... 
+		'resize','on','tag','tlwmenu',... 
+		'visible','on'); 
+
+	%  Uicontrol Object Creation 
+
+	h_quit = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_quit'');',... 
+		'Position',[ 0.672 0.027 0.279 0.06 ],... 
+		'String','Quit',... 
+		'Style','pushbutton',... 
+		'Tag','h_quit',... 
+		'UserData',''); 
+	h_info = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_info'');',... 
+		'Position',[ 0.014 0.027 0.265 0.062 ],... 
+		'String','Info',... 
+		'Style','pushbutton',... 
+		'Tag','h_info',... 
+		'UserData',''); 
+	h_analyze = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_analyze'');',... 
+		'Position',[ 0.335 0.029 0.293 0.056 ],... 
+		'String','Analyze Flow',... 
+		'Style','pushbutton',... 
+		'Tag','h_analyze',... 
+		'UserData',''); 
+	h_maxk = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_maxk'');',... 
+		'Max',[ 50 ],... 
+                'Min',[ 0 ],...
+		'Position',[ 0.75 0.181 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 30 ],... 
+		'Tag','h_maxk',... 
+		'UserData',''); 
+	h_mink = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_mink'');',... 
+		'Max',[ 50 ],... 
+		'Min',[ 0 ],...
+                'Position',[ 0.75 0.277 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 0 ],... 
+		'Tag','h_mink',... 
+		'UserData',''); 
+	h_H = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_H'');',... 
+		'Max',[ 20 ],... 
+		'Position',[ 0.25 0.454 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 3.5 ],... 
+		'Tag','h_H',... 
+		'UserData',''); 
+	h_Llower = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_Llower'');',... 
+		'Max',[ 50 ],... 
+		'Position',[ 0.25 0.563 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 10 ],... 
+		'Tag','h_Llower',... 
+		'UserData',''); 
+	h_wndspd = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_wndspd'');',... 
+		'Max',[ 100 ],... 
+		'Position',[ 0.25 0.766 0.2 0.025 ],... 
+		'String','Surface Wind Speed',... 
+		'Style','slider',... 
+		'Value',[ 20 ],... 
+		'Tag','h_wndspd',... 
+		'UserData',''); 
+	h_Lupper = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_Lupper'');',... 
+		'Max',[ 50 ],... 
+		'Position',[ 0.25 0.666 0.2 0.025 ],... 
+		'Style','slider',... 
+                'Value',[ 4 ],... 
+		'Tag','h_Lupper',... 
+		'UserData',''); 
+	h_half = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_half'');',... 
+		'Max',[ 25 ],... 
+		'Position',[ 0.75 0.702 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 2.5 ],... 
+		'Tag','h_half',... 
+		'UserData',''); 
+	h_maxht = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_maxht'');',... 
+		'Max',[ 3 ],... 
+		'Position',[ 0.75 0.785 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 0.5 ],... 
+		'Tag','h_maxht',... 
+		'UserData',''); 
+	h_xwidth = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_xwidth'');',... 
+		'Max',[ 100 ],... 
+		'Position',[ 0.75 0.52 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 40 ],... 
+		'Tag','h_xwidth',... 
+		'UserData',''); 
+	h_vert = uicontrol(... 
+		'Units','normalized',...
+		'CallBack','tlwmenu(''h_vert'');',... 
+		'Max',[ 20 ],... 
+		'Position',[ 0.75 0.44 0.2 0.025 ],... 
+		'Style','slider',... 
+		'Value',[ 10 ],... 
+		'Tag','h_vert',... 
+		'UserData',''); 
+	h_uic_6 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_6'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.049 0.139 0.221 0.101 ],... 
+		'String','Rossby Number: (@45 degrees N):',... 
+		'Style','text',... 
+		'Tag','h_uic_6',... 
+		'UserData',''); 
+	h_uic_25 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_25'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.482 0.148 0.157 0.071 ],... 
+		'String','Max. Wave# (half-widths):',... 
+		'Style','text',... 
+		'Tag','h_uic_25',... 
+		'UserData',''); 
+	h_uic_22 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_22'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.482 0.25 0.157 0.071 ],... 
+		'String','Min. Wave# (half-widths):',... 
+		'Style','text',... 
+		'Tag','h_uic_22',... 
+		'UserData',''); 
+	h_uic_20 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_20'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.576 0.345 0.299 0.037 ],... 
+		'String','SPECTRAL PROFILE',... 
+		'Style','text',... 
+		'Tag','h_uic_20',... 
+		'UserData',''); 
+	h_uic_3 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_3'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.049 0.286 0.221 0.098 ],... 
+		'String','Scorer Condition: (Trapped > 1)',... 
+		'Style','text',... 
+		'Tag','h_uic_3',... 
+		'UserData',''); 
+	h_uic_15 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_15'');',... 
+		'Position',[ 0.007 0.117 0.015 0.814 ],... 
+		'Style','text',... 
+		'Units','normalized',... 
+		'Tag','h_uic_15',... 
+		'UserData',''); 
+	h_uic_11 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_11'');',... 
+		'Position',[ 0.476 0.634 0.509 0.013 ],... 
+		'Style','text',... 
+		'Tag','h_uic_11',... 
+		'UserData',''); 
+	h_uic_19 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_19'');',... 
+		'Position',[ 0.477 0.395 0.515 0.01 ],... 
+		'Style','text',... 
+		'Tag','h_uic_19',... 
+		'UserData',''); 
+	h_uic_10 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_10'');',... 
+		'Position',[ 0.008 0.112 0.986 0.012 ],... 
+		'Style','text',... 
+		'Tag','h_uic_10',... 
+		'UserData',''); 
+	h_uic_13 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_13'');',... 
+		'Position',[ 0.983 0.12 0.01 0.82 ],... 
+		'Style','text',... 
+		'Tag','h_uic_13',... 
+		'UserData',''); 
+	h_uic_9 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.2 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_uic_9'');',... 
+		'Position',[ 0.007 0.922 0.984 0.019 ],... 
+		'Style','text',... 
+		'Tag','h_uic_9',... 
+		'UserData',''); 
+	h_title = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_title'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.01 0.939 0.95 0.04 ],... 
+		'String','INTERACTIVE MODEL FOR 2-LAYER FLOW OVER AN ISOLATED MOUNTAIN',... 
+		'Style','text',... 
+		'Tag','h_title',... 
+		'UserData',''); 
+	h_mxkval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_mxkval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.17 0.075 0.04 ],... 
+		'String','30',... 
+		'Style','text',... 
+		'Tag','h_mxkval',... 
+		'UserData',''); 
+	h_separ = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0.1 0.7 0.7 ],... 
+		'CallBack','tlwmenu(''h_separ'');',... 
+		'Position',[ 0.468 0.118 0.01 0.805 ],... 
+		'Style','text',... 
+		'Tag','h_separ',... 
+		'UserData',''); 
+	h_uic_8 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_8'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.024 0.862 0.435 0.033 ],... 
+		'String','ATMOSPHERIC PROFILE',... 
+		'Style','text',... 
+		'Tag','h_uic_8',... 
+		'UserData',''); 
+	h_uic_1 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_1'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.585 0.848 0.306 0.052 ],... 
+		'String','TERRAIN PROFILE',... 
+		'Style','text',... 
+		'Tag','h_uic_1',... 
+		'UserData',''); 
+	h_mnkval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_mnkval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.265 0.075 0.04 ],... 
+		'String','0',... 
+		'Style','text',... 
+		'Tag','h_mnkval',... 
+		'UserData',''); 
+	h_wvalue = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_wvalue'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.17 0.756 0.06 0.04 ],... 
+		'String','20',... 
+		'Style','text',... 
+		'Tag','h_wvalue',... 
+		'UserData',''); 
+	h_Lupval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Lupval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.17 0.658 0.06 0.04 ],... 
+		'String','4',... 
+		'Style','text',... 
+		'Tag','h_Lupval',... 
+		'UserData',''); 
+	h_Lloval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Lloval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.17 0.555 0.06 0.04 ],... 
+		'String','10',... 
+		'Style','text',... 
+		'Tag','h_Lloval',... 
+		'UserData',''); 
+	h_Hval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Hval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.17 0.44 0.06 0.04 ],... 
+		'String','3.5',... 
+		'Style','text',... 
+		'Tag','h_Hval',... 
+		'UserData',''); 
+	h_scorer = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_scorer'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.29 0.32 0.12 0.05 ],... 
+		'String','3.034',... 
+		'Style','text',... 
+		'Tag','h_scorer',... 
+		'UserData',''); 
+	h_wtitle = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_wtitle'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.03 0.7 0.12 0.1 ],... 
+		'String','Sfc Wind (m/s):',... 
+		'Style','text',... 
+		'Tag','h_wtitle',... 
+		'UserData',''); 
+	h_Lupttl = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Lupttl'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.03 0.603 0.12 0.1 ],... 
+		'String','L Upper (10^-4):',... 
+		'Style','text',... 
+		'Tag','h_Lupttl',... 
+		'UserData',''); 
+	h_Llottl = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Llottl'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.03 0.5 0.12 0.1 ],... 
+		'String','L Lower (10^-4):',... 
+		'Style','text',... 
+		'Tag','h_Llottl',... 
+		'UserData',''); 
+	h_Htitle = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_Htitle'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.03 0.395 0.12 0.1 ],... 
+		'String','Interface Ht. (km):',... 
+		'Style','text',... 
+		'Tag','h_Htitle',... 
+		'UserData',''); 
+	h_rossby = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_rossby'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.289 0.177 0.12 0.05 ],... 
+		'String','14.55',... 
+		'Style','text',... 
+		'Tag','h_rossby',... 
+		'UserData',''); 
+	h_uic_7 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_7'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.487 0.682 0.14 0.066 ],... 
+		'String','Half-width (km)',... 
+		'Style','text',... 
+		'Tag','h_uic_7',... 
+		'UserData',''); 
+	h_mtnval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_mtnval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.785 0.09 0.032 ],... 
+		'String','0.5',... 
+		'Style','text',... 
+		'Tag','h_mtnval',... 
+		'UserData',''); 
+	h_hlfval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_hlfval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.699 0.09 0.032 ],... 
+		'String','2.5',... 
+		'Style','text',... 
+		'Tag','h_hlfval',... 
+		'UserData',''); 
+	h_uic_2 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_2'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.528 0.593 0.417 0.032 ],... 
+		'String','DOMAIN PROFILE',... 
+		'Style','text',... 
+		'Tag','h_uic_2',... 
+		'UserData',''); 
+	h_uic_4 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_4'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.487 0.767 0.14 0.067 ],... 
+		'String','Max. Height (km)',... 
+		'Style','text',... 
+		'Tag','h_uic_4',... 
+		'UserData',''); 
+	h_uic_14 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_14'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.488 0.5 0.135 0.073 ],... 
+		'String','Horizontal (km):',... 
+		'Style','text',... 
+		'Tag','h_uic_14',... 
+		'UserData',''); 
+	h_uic_17 = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_uic_17'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.488 0.417 0.135 0.073 ],... 
+		'String','Vertical (km):',... 
+		'Style','text',... 
+		'Tag','h_uic_17',... 
+		'UserData',''); 
+	h_verval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_verval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.425 0.08 0.045 ],... 
+		'String','10',... 
+		'Style','text',... 
+		'Tag','h_verval',... 
+		'UserData',''); 
+	h_horval = uicontrol(... 
+		'Units','normalized',...
+		'BackgroundColor',[ 0 0 0 ],... 
+		'CallBack','tlwmenu(''h_horval'');',... 
+		'ForegroundColor',[ 1 1 1 ],... 
+		'Position',[ 0.65 0.51 0.08 0.045 ],... 
+		'String','40',... 
+		'Style','text',... 
+		'Tag','h_horval',... 
+		'UserData',''); 
+
+
+	%  Menu Object Creation 
+
+
+	%  Axes and Text Object Creation 
+
+
+
+
+	handle_list = [ ...  
+	 	 h_quit h_info h_analyze ... 
+	 	h_maxk h_mink h_H h_Llower ... 
+	 	h_wndspd h_Lupper h_half h_maxht ... 
+	 	h_xwidth h_vert h_uic_6 h_uic_25 ... 
+	 	h_uic_22 h_uic_20 h_uic_3 h_uic_15 ... 
+	 	h_uic_11 h_uic_19 h_uic_10 h_uic_13 ... 
+	 	h_uic_9 h_title h_mxkval h_separ ... 
+	 	h_uic_8 h_uic_1 h_mnkval h_wvalue ... 
+	 	h_Lupval h_Lloval h_Hval h_scorer ... 
+	 	h_wtitle h_Lupttl h_Llottl h_Htitle ... 
+	 	h_rossby h_uic_7 h_mtnval h_hlfval ... 
+	 	h_uic_2 h_uic_4 h_uic_14 h_uic_17 ... 
+	 	h_verval h_horval ... 
+	 	 	]; 
+
+	set(gcf,'userdata',handle_list); 
+	pause(.1); drawnow; pause(.1);
+   
+	set(gcf,'visible','on'); 
+
+
+elseif command == 1 
+	close(gcf);
+elseif command == 2 
+        ttlStr='Mountain Lee Wave Model Help/Info';
+        hlpStr=...
+          ['                                            ' 
+         '--------------------------------------------'
+	   '              INTRODUCTION                  '
+         '--------------------------------------------'
+         'This is an interactive model for visualizing'
+	   'airflow over an isolated mountain in the    '
+	   'presence of an atmosphere having varying    '
+           'thermodynamical vertical structure.         '
+           '                                            '
+   	   'The atmosphere is divided into two layers,  '
+	   'each having a uniform Scorer parameter.     '
+           '                                            '
+           'A witch of agnesi shape has been chosen     '
+           'for the terrain.                            '
+           '                                            '
+           'The resulting airflow over the mountain     '
+           'is then calculated as a Fourier sum of the  '
+	   'individual airflow patterns for each        '
+           'wavenumber in the spectral domain.          '
+           '                                            '
+           'The structure of the atmosphere, terrain    '
+           'domain, or wave spectrum can be altered     '
+	   'by moving the sliders to the requested      '
+	   'values.  Once ANALYZE FLOW is clicked, a    '
+	   'contour plot of vertical velocity and an    '
+	   'estimate of the corresponding streamlines is'
+    	   'be plotted, using the profiles set by the   '
+	   'user (and assuming steady flow).            '
+	   '                                            '
+         'BUTTONS:                                    '
+         'INFO - This help screen.                    '
+         'ANALYZE FLOW - Calculate and display airflow'
+         '               based on chosen parameters.  '
+         'QUIT - Close and exit menu.                 '
+         '                                            '
+         'The following is a description of each of   '
+         'the sliders on the menu.                    '
+         '--------------------------------------------'
+	   '          ATMOSPHERIC PROFILE:              '
+         '--------------------------------------------'
+ 	   'Sfc Wind:                                   '
+	   '    the surface wind speed in m/s           '
+           '                                            '
+	   'Lupper:                                     '
+	   '    Scorer parameter of the upper layer,    '
+	   '    in multiples of 10^-4.                  '
+           '                                            '
+	   'Llower:                                     '
+	   '    Scorer parameter of the lower layer,    '
+ 	   '    in multiples of 10^-4                   '
+           '                                            '  
+           'Interface Height:                           '
+           '    Height above the ground (in km) of the  '
+	   '    interface between the two layers.       '
+           '                                            '
+	   'Scorer Condition:                           '
+           '    Condition found by Scorer which must    '
+	   '    be satisfied for the resulting          '
+           '    airflow to contain trapped waves.       '
+           '    Mathematically,                         '
+           ' 4*(H/pi)^2*(Llower^2 -Lupper^2 ) > 1       '
+           '    where H is the interface height.        '
+           '                                            '
+           'Rossby Number:                              '
+           '    The rossby number of the flow at 45 deg.'
+           '    This model assumes no rotation;         '
+           '    therefore, this number is displayed to  '
+           '    let the user know when the chosen       '
+           '    combination of wind and domain are such '
+           '    that coriolis accelerations make the    '
+           '    calculated plots questionable. A number '
+           '    less than 1 indicates the rotational    '
+           '    effects are significant.                '
+           '--------------------------------------------'
+           '              TERRAIN PROFILE:              '
+           '--------------------------------------------'
+           'Max Height:                                 '
+           '    The maximum height of the isolated      '
+           '    mountain, in kilometers.                '
+           '                                            ' 
+           'Half-width:                                 '
+           '    The horizontal distance from the center '
+           '    of the mountain at which the mountain   '
+           '    height decreases to one-half the maximum'
+           '    height.  (in km).                       '
+           '--------------------------------------------'
+           '             DOMAIN PROFILE:                '
+           '--------------------------------------------'
+           'Horizontal:                                 ' 
+           '    The width (in km) of the horizontal     '
+           '    domain to be analyzed.                  '   
+           '                                            '
+           'Vertical:                                   '
+           '    The height (in km) of the vertical      '
+           '    domain to be analyzed.                  '
+           '--------------------------------------------'
+           '            SPECTRAL PROFILE:               '
+           '--------------------------------------------'
+           'Mininum Wavenumber:                         '
+           '    The smallest wavenumber wave to be      '
+           '    included in the calculation             '
+           '    (in multiples of mtn half-widths).      '
+           '    This is the lower limit on the Fourier  '
+           '    integration for wavenumber.             '
+           '                                            '
+           'Maximum Wavenumber:                         '
+           '    The largest wavenumber wave to be       '
+           '    included in the airflow calculation     '
+           '    (in multiples of mtn half-widths).      '
+           '    This is the upper limit on the Fourier  '
+           '    integration for wavenumber.             '
+           '--------------------------------------------'
+           '                                            '];
+  	   helpwin(ttlStr,hlpStr);	 
+elseif command == 3 
+	a=1000*get(h_half,'value');   
+	H=1000*get(h_H,'value');   
+	ho=1000*get(h_maxht,'value');           
+	U=get(h_wndspd,'value');     
+	Lupper=.0001*get(h_Lupper,'value');     
+	Llower=.0001*get(h_Llower,'value');    
+	xdom=1000*get(h_xwidth,'value');   
+	zdom=1000*get(h_vert,'value');    
+	mink=get(h_mink,'value')/a;   
+	maxk=get(h_maxk,'value')/a;   
+	tlwplot(Lupper,Llower,U,H,a,ho,xdom,zdom,mink,maxk);      
+elseif command == 4 
+	maxk=get(h_maxk,'value');    
+	set(h_mxkval,'string',num2str(maxk));    
+elseif command == 5 
+	mink=get(h_mink,'value');    
+	set(h_mnkval,'string',num2str(mink));    
+elseif command == 6 
+	H=get(h_H,'value');     
+	set(h_Hval,'string',num2str(H));     
+elseif command == 7 
+	Llower=get(h_Llower,'value');      
+	set(h_Lloval,'string',num2str(Llower));  
+elseif command == 8 
+	U=get(h_wndspd,'value');        
+	set(h_wvalue,'string',num2str(U));    
+elseif command == 9 
+	Lupper=get(h_Lupper,'value');       
+	set(h_Lupval,'string',num2str(Lupper));       
+elseif command == 10 
+	a=get(h_half,'value');    
+	set(h_hlfval,'string',num2str(a));   
+elseif command == 11 
+	ho=get(h_maxht,'value');    
+	set(h_mtnval,'string',num2str(ho));    
+elseif command == 12 
+	xdom=get(h_xwidth,'value');    
+	set(h_horval,'string',num2str(xdom));    
+elseif command == 13 
+	zdom=get(h_vert,'value');    
+	set(h_verval,'string',num2str(zdom));    
+else 
+	error('Error: tlwmenu.m called with incorrect command.') 
+end
+
+if command ~= 1
+	H=1000*get(h_H,'value');
+	Llower=.0001*get(h_Llower,'value');  
+	Lupper=.0001*get(h_Lupper,'value');  
+	scorer=4*H*H*(Llower*Llower-Lupper*Lupper)/(pi*pi);  
+	set(h_scorer,'string',num2str(scorer));  
+
+	U=get(h_wndspd,'value');
+	a=1000*get(h_half,'value');
+	rossby=U/(f*a);
+	set(h_rossby,'string',num2str(rossby));
+end;

tlwplot.m

@@ -0,0 +1,114 @@
+function[]=tlwplot(Lupper,Llower,U,H,a,ho,xdom,zdom,mink,maxk);
+%-------------------------------------------------------------
+% Matlab Subroutine tlwplot.M					
+% Called from tlwmenu.M--interactive menu system.		
+%									
+% By Robert Hart for Meteo 574 / Fall 1995			
+% Penn State University Meteorology
+% Updated 1 March 2018 to increase npts given faster cpus
+%									
+% Program which analyzes and simulates the flow over			
+% an isolated mountain in the presence of a two-			
+% layer atmosphere.							
+%									
+% Parameters received from menu:					
+%-------------------------------					
+% Lupper - Scorer parameter of upper layer				
+% Llower - Scorer parameter of lower layer				
+% U      - Surface wind speed (in m/s)					
+% H      - Height above ground of 2-layer interface (in m)		
+% a      - Half-width of mountain (in m)				
+% ho     - maximum height of mountain					
+% xdom   - Horizontal extent of domain (m)				
+% zdom   - Vertical extent of domain (m)				
+% mink   - Minimum wavenumber in Fourier analysis of flow		
+% maxk   - Maximum wavenumber in Fourier analysis of flow		
+%									
+%--------------------------------------------------------------
+
+npts=100;                            % # cells in each direction
+dk=0.367/a;                          % wavenumber interval size 
+                                     %   (smaller the better, but
+                                     %   need to watch calc. time!)  
+nk=(maxk-mink)/dk;                   % # loops for wave# integration                   
+
+minx=-.25*xdom;                      % leftmost limit of domain
+maxx=.75*xdom;                       % rightmost limit of domain
+minz=0;                              % lower limit of domain
+maxz=zdom;                           % upper limit of domain
+
+matrix1=zeros(npts+1,npts+1);        % temp matrix used in integration
+matrix2=zeros(npts+1,npts+1);        % temp matrix used in integration
+matrix3=zeros(npts+1,npts+1);        % sum matrix used in integration
+
+dx=(maxx-minx)/npts;                 % grid cell size in horizontal
+dz=(maxz-minz)/npts;                 % grid cell size in vertical
+
+x=[minx:dx:maxx];                    % array of x gridpoints
+z=[minz:dz:maxz];                    % array of z gridpoints
+k=[mink:dk:maxk];                    % array of wavenumbers
+           
+                                     % mesh arrays into 2-d matrix
+[x,z]=meshgrid(minx:dx:maxx,minz:dz:maxz); 
+
+ht=0;                          	    % initialize weighting for transform
+for kloop=1:nk;                      % wavenumber loop
+  kk=k(kloop);                       %    horiz wavenumber
+  m=sqrt(Llower*Llower-kk*kk);       %    vert wave# in lower layer
+  n=sqrt(kk*kk-Lupper*Lupper);       %    vert wave# in upper layer
+  if (m+i*n==0)                      %    check for divide by zero
+    r=9e99;                           
+  else 
+    r=(m-i*n)/(m+i*n);               %    reflection coefficient
+  end; 
+  R=r*exp(2*i*m*H);                  %    reflection calculation
+  A=(1+r)*exp(H*n+i*H*m)/(1+R);      %    calculate coefficients
+  C=1/(1+R);                         
+  D=R.*C;
+  hs=pi*a*ho*exp(-a*abs(kk));        %    kk-component of Fourier trans.
+  ht=ht+pi*dk*a*exp(-a*abs(kk));     %    sum Fourier weighting. if
+                                     %    integrating over 0<k<oo
+                                     %    ht will end up as pi.
+                                     %    hence, ht represents the 
+                                     %    fraction, in radians, of
+                                     %    the spectral interval considered. 
+                                            
+  aboveH=A*exp(-z.*n).*(z>H);        %    calculate w in each layer         
+  belowH=(C*exp(i*z.*m)+D*exp(-i*z.*m)).*(z<=H);
+  
+                                     %    combine layers, and multiply by
+                                     %    transform of kk-component of topo.   
+  matrix2=((-i*kk*hs*U*(aboveH+belowH)).*exp(-i*x.*kk));
+   
+  if kloop > 1                       %    trapezoidal integration/summation
+    matrix3=matrix3+.5*(matrix1+matrix2).*dk;
+  end;
+ 
+  matrix1=matrix2;                   %    current w matrix becomes previous
+end;                                 % end of integration loop.
+
+w=real(matrix3./ht);                 % only interested in real comp. 
+                                     
+figure;                              % create new figure window                     
+axis([minx maxx minz maxz]);         % define axes
+grid;                                % graw grid
+xlabel('X (m)');                     % X-axis title
+ylabel('Height (m)');                % Z-axis title
+title(['Streamline Analysis']);      % figure title
+stream(x,z,U,w,10);                  % perform streamline analysis
+Hline=H*ones(1,npts+1);              % create interface line        
+plot(x(1,:),Hline,'m--');            % draw interface line in magenta!
+
+figure;                              % create new figure window                                                      
+colormap(jet);                       % set colormap (red=high;blue=low)
+axis([minx maxx minz maxz]);         % define axes
+xlabel('X (m)');                     % X-axis title
+ylabel('Height (m)');                % Z-axis title
+title(['Vertical Velocity (m/s)']);  % figure title
+hold on;                             % hold current figure
+plot(x(1,:),Hline,'m--');            % draw interface line
+caxis([-10 10]);                     % define color contouring extrema
+surface(x,z,w);                      % 2-d surface contour plot
+shading interp;                      % interpolate between gridpoints
+colorbar;                            % add contour legend
+hold off;                            % remove hold on figure

validate.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Validate Rust vs. pure-Python solver, and sanity-check physics.
+
+Run with: python validate.py
+
+If the Rust extension hasn't been built, only the pure-Python code is
+exercised — useful for catching mistakes in the port of tlwplot.m.
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT / "python"))
+
+from mountain_waves import compute_two_layer, compute_from_profile, streamlines, backend_name
+from mountain_waves import reference as ref
+from mountain_waves.profile import (
+    default_profile_heights,
+    default_theta_profile,
+    default_u_profile,
+)
+
+
+def describe(name, w):
+    print(f"  {name:<28} min={w.min():+.4f}  max={w.max():+.4f}  rms={np.sqrt((w**2).mean()):.4f}")
+
+
+def case_uniform():
+    # Example 1: uniform atmosphere. No wave trapping.
+    return dict(l_upper=4e-4, l_lower=4e-4, u=20.0, h=3500.0, a=2500.0, ho=500.0,
+                xdom=40000.0, zdom=10000.0, mink=0.0, maxk=30.0 / 2500.0, npts=100)
+
+
+def case_trapped():
+    # Example 2: trapped lee waves.
+    return dict(l_upper=4e-4, l_lower=10e-4, u=20.0, h=3500.0, a=2500.0, ho=500.0,
+                xdom=40000.0, zdom=10000.0, mink=0.0, maxk=30.0 / 2500.0, npts=100)
+
+
+def main() -> int:
+    print(f"Active backend: {backend_name()}")
+
+    # ---- Python reference sanity: uniform atmosphere, w ≈ odd in x near crest
+    print("\n[1] Two-layer, uniform atmosphere (pure-Python reference):")
+    p = case_uniform()
+    x, z, w, up = ref.compute_two_layer(**p)
+    assert w.shape == (101, 101)
+    assert up.shape == w.shape
+    describe("w (reference)", w)
+    describe("u' (reference)", up)
+
+    print("\n[2] Two-layer, trapped-wave case:")
+    pt = case_trapped()
+    x, z, w_ref, up_ref = ref.compute_two_layer(**pt)
+    describe("w (reference)", w_ref)
+    describe("u' (reference)", up_ref)
+
+    # Expect substantial wave amplitude in the lee (x > 0) for the trapped case.
+    # Find amplitude in z ~ 1-2 km and x ~ 5-20 km.
+    xi = (x >= 5000) & (x <= 20000)
+    zi = (z >= 500) & (z <= 2000)
+    lee_rms = np.sqrt((w_ref[np.ix_(zi, xi)] ** 2).mean())
+    print(f"  lee-wave rms(1-2 km, 5-20 km) = {lee_rms:.3f} m/s")
+    assert lee_rms > 0.05, "Trapped-wave case showed suspiciously weak lee waves."
+
+    # ---- Rust vs Python, if Rust is available
+    try:
+        from mountain_waves import _core  # type: ignore
+        has_rust = True
+    except ImportError:
+        has_rust = False
+
+    if has_rust:
+        print("\n[3] Rust vs. Python two-layer (trapped case):")
+        _, _, w_rust, up_rust = _core.compute_two_layer(**pt)
+        err_w = np.max(np.abs(w_rust - w_ref))
+        err_u = np.max(np.abs(up_rust - up_ref))
+        print(f"  max|w_rust  - w_python|  = {err_w:.2e}")
+        print(f"  max|u'_rust - u'_python| = {err_u:.2e}")
+        assert err_w < 1e-6, f"Rust/Python w disagreement too large: {err_w}"
+        assert err_u < 1e-6, f"Rust/Python u' disagreement too large: {err_u}"
+    else:
+        print("\n[3] (skipped — Rust extension not built)")
+
+    # ---- Profile solver: should approximate two-layer as profile resolution → ∞
+    print("\n[4] Profile solver — trapped-wave profile:")
+    zs = default_profile_heights(10.0, 17)
+    us = np.full_like(zs, 20.0)  # constant wind
+    # Construct theta so that N^2/u^2 approximates L_lower/L_upper below/above 3.5 km.
+    # L_lower^2 = N^2/u^2 - (1/u) d2u/dz2, constant u ⇒ second term 0.
+    # Want L^2_lower = 10e-4^2 -> N^2 = L^2 * u^2.
+    N2_lower = (10e-4) ** 2 * 20.0 ** 2
+    N2_upper = (4e-4) ** 2 * 20.0 ** 2
+    thetas = np.empty_like(zs)
+    thetas[0] = 290.0
+    for i in range(1, zs.size):
+        dz = zs[i] - zs[i - 1]
+        n2 = N2_lower if zs[i] <= 3500.0 else N2_upper
+        thetas[i] = thetas[i - 1] + thetas[i - 1] * n2 / 9.80665 * dz
+
+    prof_out = ref.compute_from_profile(
+        zs, us, thetas,
+        a=2500.0, ho=500.0, xdom=40000.0, zdom=10000.0,
+        mink=0.0, maxk=30.0 / 2500.0, npts=100,
+    )
+    # compute_from_profile returns (x, z, w) or (x, z, w, u_prime) depending
+    # on the port-era. Accept either to keep this script robust.
+    x, z, w_prof = prof_out[0], prof_out[1], prof_out[2]
+    describe("w (profile solver)", w_prof)
+    # Compare RMS to two-layer case — should be broadly similar.
+    rms_prof = np.sqrt(np.mean(w_prof ** 2))
+    rms_ref = np.sqrt(np.mean(w_ref ** 2))
+    ratio = rms_prof / rms_ref
+    print(f"  rms(profile) / rms(2-layer) = {ratio:.3f}")
+    assert 0.3 < ratio < 3.0, "Profile solver RMS differs unreasonably from two-layer reference."
+
+    # ---- Critical-level handling: U crosses zero mid-column.
+    #
+    # Linear Scorer/Taylor-Goldstein is singular at U = 0, so we clamp |U|
+    # at U_FLOOR_SCORER (~0.5 m/s) in both Rust and Python scorer helpers
+    # and surface the detected zero-crossings separately. This test makes
+    # sure (a) the clamp keeps l^2 finite, (b) Rust and Python agree on
+    # the clamped profile, and (c) the `critical_levels` helper correctly
+    # locates the zero crossing.
+    print("\n[5] Critical-level handling (wind reversal at z≈5 km):")
+    zs_c = np.linspace(0.0, 10000.0, 41)
+    us_c = np.linspace(10.0, -10.0, 41)   # zero at index 20, z = 5000 m
+    thetas_c = 290.0 + 0.004 * zs_c       # mildly stable
+    l2_py = ref.scorer_from_profile(zs_c, us_c, thetas_c)
+    assert np.all(np.isfinite(l2_py)), "Python Scorer went non-finite across U=0"
+    crits = ref.critical_levels(zs_c, us_c)
+    print(f"  detected critical levels: {[round(h, 1) for h in crits]} m")
+    assert len(crits) == 1 and abs(crits[0] - 5000.0) < 1e-6, crits
+    # Also make sure the full solver survives a wind-reversal column. Rust
+    # and Python both have to clamp |U| internally for scorer_from_profile;
+    # running compute_from_profile exercises that path end-to-end.
+    out_py = ref.compute_from_profile(
+        zs_c, us_c, thetas_c,
+        a=2500.0, ho=500.0, xdom=40000.0, zdom=10000.0,
+        mink=0.0, maxk=30.0 / 2500.0, npts=80,
+    )
+    w_py = out_py[2]
+    assert np.all(np.isfinite(w_py)), "Python solver went non-finite across U=0"
+    if has_rust:
+        out_rust = _core.compute_from_profile(
+            zs_c, us_c, thetas_c,
+            a=2500.0, ho=500.0, xdom=40000.0, zdom=10000.0,
+            mink=0.0, maxk=30.0 / 2500.0, npts=80,
+        )
+        w_rust_c = out_rust[2]
+        assert np.all(np.isfinite(w_rust_c)), "Rust solver went non-finite across U=0"
+        err = np.max(np.abs(w_rust_c - w_py))
+        print(f"  wind-reversal max|w_rust - w_python| = {err:.2e}")
+        assert err < 1e-4, f"Rust/Python wind-reversal disagreement: {err}"
+
+    # ---- Streamline tracer: the first line should sweep over the mountain crest.
+    print("\n[6] Streamline tracer:")
+    lines = streamlines(x, z, 20.0, w_ref, num=10)
+    assert len(lines) == 10
+    xs0, ys0 = lines[0]
+    assert xs0[0] < 0 < xs0[-1]
+    print(f"  first streamline: x ∈ [{xs0[0]:.0f}, {xs0[-1]:.0f}] m, y ∈ [{ys0.min():.1f}, {ys0.max():.1f}] m")
+
+    print("\nAll checks passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())