Initial commit: UpdraftForcing Dash app

python/updraft_forcing/app.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import math
 import numpy as np
 from dash import Dash, Input, Output, State, ctx, dcc, html, no_update
 import plotly.graph_objects as go
@@ -63,7 +62,6 @@ def _build_env_winds(u_pts, v_pts):
 
 def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
     """Full model run: sounding → updraft → pressure → diagnostics."""
-    # Map UI parameter keys to wk_sounding keyword names
     snd_kw = dict(
         theta_ml   = snd_params.get("theta_ml",   SND_DEFAULTS["theta_ml"]),
         qv_ml_gkg  = snd_params.get("qv_ml",      SND_DEFAULTS["qv_ml"]),
@@ -74,16 +72,13 @@ def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
     )
     snd = wk_sounding(Z_GRID, **snd_kw)
 
-    # 1-D parcel and diagnosed w profile
     wp = diagnose_w_profile(
         Z_GRID, snd["T_K"], snd["qv"], snd["p_hPa"],
         delta_T_K=upd_params["delta_T"],
     )
 
-    # Environmental wind on the full grid
     env_u, env_v, dudz_env, dvdz_env = _build_env_winds(u_pts, v_pts)
 
-    # 3-D updraft fields
     fields = build_updraft_fields(
         X2, Y2, Z_GRID,
         r0=upd_params["r0"],
@@ -96,16 +91,15 @@ def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
         theta_parcel=wp["T_parcel"] * (snd["p_hPa"] / 1000.0) ** 0.2854,
     )
 
-    # Pressure forcing and solve
-    rho0 = snd["rho"]
+    rho0   = snd["rho"]
     theta0 = snd["theta"]
 
-    F_lin = forcing_linear(rho0, dudz_env, dvdz_env, fields["w3d"], DX)
-    F_spin = forcing_spin(rho0, fields["u3d"], fields["v3d"], fields["w3d"],
-                          env_u, env_v, DX, DZ)
+    F_lin   = forcing_linear(rho0, dudz_env, dvdz_env, fields["w3d"], DX)
+    F_spin  = forcing_spin(rho0, fields["u3d"], fields["v3d"], fields["w3d"],
+                           env_u, env_v, DX, DZ)
     F_splat = forcing_splat(rho0, fields["u3d"], fields["v3d"], fields["w3d"],
                             env_u, env_v, DX, DZ)
-    F_buoy = forcing_buoyancy(rho0, theta0, fields["theta_prime3d"], DZ)
+    F_buoy  = forcing_buoyancy(rho0, theta0, fields["theta_prime3d"], DZ)
 
     p_lin   = solve_poisson_3d(F_lin,   DX, DZ)
     p_spin  = solve_poisson_3d(F_spin,  DX, DZ)
@@ -115,7 +109,6 @@ def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
 
     accels = pressure_accelerations(p_lin, p_spin, p_splat, p_buoy, rho0, DZ)
 
-    # Diagnostics
     parcel_diag = {
         "CAPE": wp["CAPE"], "CIN": wp["CIN"],
         "LCL_m": wp["LCL_m"], "LFC_m": wp["LFC_m"],
@@ -127,7 +120,6 @@ def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
         fields["w3d"], fields["zeta3d"],
     )
 
-    # Cache
     _C.update({
         "w":        fields["w3d"],
         "u":        fields["u3d"],
@@ -155,12 +147,21 @@ def _run_model(snd_params, upd_params, u_pts, v_pts, zeta_cpts):
 # UI helpers
 # ---------------------------------------------------------------------------
 
-def _slider(id_, label, mn, mx, step, value, unit=""):
+def _help(tip: str) -> html.Span:
+    """Inline ? icon that shows a CSS tooltip on hover."""
+    return html.Span("?", className="uf-help", **{"data-tip": tip})
+
+
+def _slider(id_, label, mn, mx, step, value, unit="", tip=""):
+    label_group = [html.Span(label, className="uf-slider-label")]
+    if tip:
+        label_group.append(_help(tip))
     return html.Div(
         className="uf-slider-row",
         children=[
             html.Div(
-                [html.Span(label, className="uf-slider-label"),
+                [html.Div(label_group,
+                          style={"display": "flex", "alignItems": "center", "gap": "4px"}),
                  html.Span(f"{value}{unit}", id=f"{id_}-val", className="uf-slider-value")],
                 className="uf-slider-header",
             ),
@@ -171,15 +172,14 @@ def _slider(id_, label, mn, mx, step, value, unit=""):
 
 
 def _profile_editor(fig_id, title, values, z_km, xunit, xrange):
-    """Draggable profile graph identical to Mountain Waves pattern."""
+    """Draggable profile graph (Mountain Waves pattern)."""
     values = np.asarray(values, dtype=float)
-    z_km = np.asarray(z_km, dtype=float)
+    z_km   = np.asarray(z_km,   dtype=float)
     vlo, vhi = xrange
 
     fig = go.Figure()
     fig.add_trace(go.Scatter(
-        x=values, y=z_km,
-        mode="lines+markers",
+        x=values, y=z_km, mode="lines+markers",
         line=dict(color="#6ecbff", width=2),
         marker=dict(size=7, color="#6ecbff"),
         hoverinfo="skip", showlegend=False,
@@ -200,8 +200,7 @@ def _profile_editor(fig_id, title, values, z_km, xunit, xrange):
         xaxis_title=xunit, yaxis_title="height (km)",
         template="plotly_dark",
         margin=dict(l=50, r=10, t=40, b=40),
-        height=300,
-        dragmode=False,
+        height=300, dragmode=False,
         xaxis=dict(range=[vlo, vhi], fixedrange=True),
         yaxis=dict(range=[0, z_km[-1] + 0.5], fixedrange=True),
         shapes=shapes,
@@ -214,28 +213,22 @@ def _profile_editor(fig_id, title, values, z_km, xunit, xrange):
 
 def _hodo_figure(u_pts, v_pts, storm_u=None, storm_v=None,
                  lm_u=None, lm_v=None, mean_u=None, mean_v=None):
-    """Build the interactive hodograph figure with draggable level markers."""
     u_pts = np.asarray(u_pts, dtype=float)
     v_pts = np.asarray(v_pts, dtype=float)
-    levels_km = HODO_LEVELS_KM
 
     fig = go.Figure()
-
-    # Colored hodograph segments: 0-3 km = warm, 3-6 km = mid, 6+ = cool
     seg_colors = ["#e06c6c", "#e09c4a", "#c8d44a", "#5ac85a", "#4ab8e0", "#7070e0",
                   "#a060d0", "#808080", "#606060"]
     for i in range(len(u_pts) - 1):
         fig.add_trace(go.Scatter(
-            x=u_pts[i:i+2], y=v_pts[i:i+2],
-            mode="lines",
+            x=u_pts[i:i+2], y=v_pts[i:i+2], mode="lines",
             line=dict(color=seg_colors[min(i, len(seg_colors)-1)], width=2.5),
             hoverinfo="skip", showlegend=False,
         ))
 
-    # Draggable level markers as Plotly shapes (circles)
     radius_px = 9
     shapes = []
-    for i, (u, v) in enumerate(zip(u_pts, v_pts)):
+    for u, v in zip(u_pts, v_pts):
         shapes.append(dict(
             type="circle", xref="x", yref="y",
             xsizemode="pixel", ysizemode="pixel",
@@ -245,53 +238,39 @@ def _hodo_figure(u_pts, v_pts, storm_u=None, storm_v=None,
             editable=True, layer="above",
         ))
 
-    # Level annotations
-    for i, (u, v, lkm) in enumerate(zip(u_pts, v_pts, levels_km)):
-        fig.add_annotation(
-            x=float(u), y=float(v),
-            text=f"{lkm}",
-            font=dict(size=9, color="#dfe3ea"),
-            showarrow=False, xshift=12, yshift=6,
-        )
+    for u, v, lkm in zip(u_pts, v_pts, HODO_LEVELS_KM):
+        fig.add_annotation(x=float(u), y=float(v), text=f"{lkm}",
+                           font=dict(size=9, color="#dfe3ea"),
+                           showarrow=False, xshift=12, yshift=6)
 
-    # Storm motion markers
     if storm_u is not None:
-        fig.add_trace(go.Scatter(
-            x=[storm_u], y=[storm_v], mode="markers+text",
+        fig.add_trace(go.Scatter(x=[storm_u], y=[storm_v], mode="markers+text",
             marker=dict(symbol="star", size=14, color="#ff8c00"),
             text=["RM"], textposition="top right", textfont=dict(size=9, color="#ff8c00"),
-            hoverinfo="skip", showlegend=False,
-        ))
+            hoverinfo="skip", showlegend=False))
     if lm_u is not None:
-        fig.add_trace(go.Scatter(
-            x=[lm_u], y=[lm_v], mode="markers+text",
+        fig.add_trace(go.Scatter(x=[lm_u], y=[lm_v], mode="markers+text",
             marker=dict(symbol="star", size=14, color="#aaaaff"),
             text=["LM"], textposition="top right", textfont=dict(size=9, color="#aaaaff"),
-            hoverinfo="skip", showlegend=False,
-        ))
+            hoverinfo="skip", showlegend=False))
     if mean_u is not None:
-        fig.add_trace(go.Scatter(
-            x=[mean_u], y=[mean_v], mode="markers",
+        fig.add_trace(go.Scatter(x=[mean_u], y=[mean_v], mode="markers",
             marker=dict(symbol="x", size=11, color="#80ff80"),
-            hoverinfo="skip", showlegend=False,
-        ))
+            hoverinfo="skip", showlegend=False))
 
-    # Axis cross-hairs
     all_u = list(u_pts) + ([storm_u] if storm_u else []) + ([lm_u] if lm_u else [])
     all_v = list(v_pts) + ([storm_v] if storm_v else []) + ([lm_v] if lm_v else [])
     pad = 5
-    ulo, uhi = min(all_u) - pad, max(all_u) + pad
-    vlo, vhi = min(all_v) - pad, max(all_v) + pad
-
     fig.update_layout(
         title=dict(text="Hodograph (drag to edit)", font=dict(size=12)),
         xaxis_title="U (m s⁻¹)", yaxis_title="V (m s⁻¹)",
         template="plotly_dark",
         margin=dict(l=50, r=10, t=40, b=40),
-        height=300,
-        dragmode=False,
-        xaxis=dict(range=[ulo, uhi], zeroline=True, zerolinecolor="#555", fixedrange=True),
-        yaxis=dict(range=[vlo, vhi], zeroline=True, zerolinecolor="#555", fixedrange=True,
+        height=300, dragmode=False,
+        xaxis=dict(range=[min(all_u)-pad, max(all_u)+pad],
+                   zeroline=True, zerolinecolor="#555", fixedrange=True),
+        yaxis=dict(range=[min(all_v)-pad, max(all_v)+pad],
+                   zeroline=True, zerolinecolor="#555", fixedrange=True,
                    scaleanchor="x", scaleratio=1),
         shapes=shapes,
     )
@@ -299,10 +278,7 @@ def _hodo_figure(u_pts, v_pts, storm_u=None, storm_v=None,
 
 
 def _field_heatmap(arr2d, x_axis, y_axis, x_label, y_label, title, field):
-    """Return a Plotly Figure of a 2-D slice."""
-    colorscale, symmetric, label, unit = FIELD_META.get(
-        field, ("Viridis", False, field, "")
-    )
+    colorscale, symmetric, label, unit = FIELD_META.get(field, ("Viridis", False, field, ""))
     zmin, zmax = clim(arr2d, symmetric)
     fig = go.Figure(data=go.Heatmap(
         x=x_axis, y=y_axis, z=arr2d.T,
@@ -323,8 +299,7 @@ def _field_heatmap(arr2d, x_axis, y_axis, x_label, y_label, title, field):
 def _profile_fig(y_vals, z_km, title, color, xunit):
     fig = go.Figure()
     fig.add_trace(go.Scatter(
-        x=y_vals, y=z_km,
-        mode="lines", line=dict(color=color, width=2),
+        x=y_vals, y=z_km, mode="lines", line=dict(color=color, width=2),
         hovertemplate=f"%{{x:.2g}} {xunit}<br>%{{y:.1f}} km<extra></extra>",
         showlegend=False,
     ))
@@ -347,86 +322,470 @@ def _diag_row(label, value, unit=""):
     ])
 
 
+# ---------------------------------------------------------------------------
+# Static page content
+# ---------------------------------------------------------------------------
+
+def _getting_started_content():
+    def _step(n, title, body):
+        return html.Div([
+            html.Div(f"Step {n} — {title}", className="gs-step-title"),
+            html.Div(body, className="gs-step-body"),
+        ], className="gs-step")
+
+    def _row(label, desc):
+        return html.Tr([
+            html.Td(label, className="gs-ctrl-label"),
+            html.Td(desc,  className="gs-ctrl-desc"),
+        ])
+
+    return html.Div(className="uf-page-content", children=[
+        html.H2("Getting Started", className="page-h2"),
+        html.P(
+            "UpdraftForcing is a diagnostic kinematic model for convective storms. "
+            "It prescribes an idealized updraft in a sheared environment and instantly "
+            "diagnoses the resulting pressure perturbation field decomposed into physical "
+            "forcing mechanisms. No time-stepping — every slider move reruns the full "
+            "3-D Poisson solve (~1.5 s).",
+            className="gs-intro",
+        ),
+
+        _step(1, "Set up the sounding", html.Table(className="gs-table", children=[
+            html.Tbody([
+                _row("θ_ml (K)",
+                     "Mixed-layer potential temperature. The surface parcel is lifted from this θ. "
+                     "Higher values give a warmer boundary layer and more buoyancy."),
+                _row("qv_ml (g/kg)",
+                     "Boundary-layer water vapor mixing ratio. More moisture raises the dew point, "
+                     "lowering the LCL and increasing CAPE."),
+                _row("BL depth (m)",
+                     "Depth of the well-mixed layer. The constant-θ / qv layer extends to this height."),
+                _row("Tropopause ht. (m)",
+                     "Height of the tropopause. Controls the depth of the unstable layer. "
+                     "A higher tropopause allows a deeper updraft and more CAPE."),
+                _row("Tropopause T (K)",
+                     "Temperature at the tropopause. Colder tropopause → larger CAPE."),
+                _row("Lapse rate exp.",
+                     "Power-law exponent γ shaping the free-troposphere θ profile. "
+                     "γ = 1 is linear; γ < 1 concentrates instability near the surface; γ > 1 near the tropopause."),
+                _row("Presets",
+                     "WK Supercell loads the Weisman-Klemp (1982) default environment. "
+                     "Weak shear loads a straight unidirectional hodograph. Reset returns all controls to defaults."),
+            ]),
+        ])),
+
+        _step(2, "Draw the hodograph (Hodograph tab)", [
+            html.P("The hodograph shows the environmental wind vector at 9 levels: "
+                   "surface, 1, 2, 3, 4, 5, 6, 8, and 10 km. Each gold circle is draggable. "
+                   "Drag left/right to change U; drag up/down to change V."),
+            html.P("The app automatically computes:"),
+            html.Table(className="gs-table", children=[html.Tbody([
+                _row("RM / LM (stars)", "Bunkers et al. (2000) right- and left-mover storm motions "
+                     "— mean 0–6 km wind ± 7.5 m/s perpendicular to the 0–6 km shear vector."),
+                _row("Mean wind (×)",   "Simple 0–6 km mass-weighted mean wind."),
+                _row("SRH 0–2 / 2–5 km", "Storm-relative helicity relative to the right-mover, "
+                     "shown in the diagnostics table."),
+            ])]),
+        ]),
+
+        _step(3, "Configure the updraft (Updraft tab)", html.Table(className="gs-table", children=[
+            html.Tbody([
+                _row("ΔT surface (K)",
+                     "Temperature excess of the surface parcel above the environment. "
+                     "Drives the diagnosed w(z) profile via w²(z) = max(0, 2·∫B dz). "
+                     "Larger ΔT → more kinetic energy to overcome CIN → stronger updraft."),
+                _row("Radius (m)",
+                     "Radial extent of the updraft core. "
+                     "The shape function tapers w and ζ to zero at this distance from center."),
+                _row("ζ(z) profile",
+                     "Prescribed vertical vorticity representing accumulated storm rotation. "
+                     "Drag the gold circles rightward for cyclonic (positive) rotation, "
+                     "leftward for anticyclonic. The vorticity drives the spin pressure term "
+                     "and updraft helicity. Default is zero (no rotation)."),
+                _row("Core shape — Top-hat",
+                     "Uniform w and ζ inside r₀·0.9 with a cosine taper in the outer 10%. "
+                     "Good for representing a solid rotating mesocyclone."),
+                _row("Core shape — Cosine",
+                     "w(r) = cos(π·r / 2r₀). Smooth bell with no flat core. "
+                     "More realistic radial gradient of w."),
+            ]),
+        ])),
+
+        _step(4, "Explore the output fields", [
+            html.P("Use the field dropdown and view tabs (Plan view / X cross-sec / Y cross-sec) "
+                   "in the center panel. The slice slider moves through the atmosphere."),
+            html.Table(className="gs-table", children=[html.Tbody([
+                _row("w",              "Vertical velocity (m/s). Blue = updraft, red = downdraft."),
+                _row("u, v",           "Total wind components including environmental flow and core rotation."),
+                _row("Vertical ζ_z",   "Prescribed vorticity within the core (s⁻¹)."),
+                _row("p' total",       "Sum of all four pressure perturbation components (Pa)."),
+                _row("p' linear",      "Shear-interaction term. Produces high p' on the upshear side, "
+                                       "low p' downshear — causes updraft propagation toward high pressure."),
+                _row("p' spin",        "Nonlinear rotation term. Produces low p' inside the rotating core "
+                                       "(dynamic pipe effect) — upward acceleration within the mesocyclone."),
+                _row("p' splat",       "Nonlinear deformation term. Produces high p' where air is being "
+                                       "strained (e.g., at the updraft base)."),
+                _row("p' buoyancy",    "Buoyancy-induced term. Low p' above warm anomalies "
+                                       "adds to the upward acceleration."),
+                _row("Accel. terms",   "Vertical acceleration −(1/ρ₀)·∂p'/∂z from each component, "
+                                       "plotted as profiles in the right panel."),
+            ])]),
+        ]),
+
+        _step(5, "Read the diagnostics panel", [
+            html.P("The right panel updates after every model run:"),
+            html.Table(className="gs-table", children=[html.Tbody([
+                _row("CAPE / CIN",        "Convective available potential energy and convective inhibition (J/kg)."),
+                _row("LCL / LFC / EL",    "Lifting condensation level, level of free convection, "
+                                          "and equilibrium level (km)."),
+                _row("Overshoot top",     "Height where w → 0 above the EL. Diagnosed from the parcel model."),
+                _row("SRH 0–2 / 2–5 km", "Storm-relative helicity layers (m²/s²). "
+                                          "Values > 150 are supportive of supercell tornadoes."),
+                _row("UH 0–2 / 2–5 km",  "Updraft helicity (m²/s²). Nonzero only when ζ is prescribed."),
+                _row("0–6 km shear",      "Bulk wind shear magnitude (m/s). > 15 m/s favors supercells."),
+                _row("w_max",             "Peak vertical velocity at the updraft core center (m/s)."),
+            ])]),
+        ]),
+    ])
+
+
+def _theory_content():
+    def _eq(latex):
+        return dcc.Markdown(f"$$\n{latex}\n$$", mathjax=True, className="theory-eq-md")
+
+    def _h3(text):
+        return html.H3(text, className="theory-h3")
+
+    def _p(text):
+        return dcc.Markdown(text, mathjax=True, className="theory-p-md")
+
+    def _ref(authors, year, title, journal):
+        return html.Li([
+            html.Span(f"{authors} ({year}). ", style={"color": "#dfe3ea"}),
+            html.Em(title, style={"color": "#c7ced6"}),
+            html.Span(f". {journal}", style={"color": "#8d97a2"}),
+        ], className="theory-ref")
+
+    def _assume(text, note=""):
+        children = [html.Td("✓", className="assume-check"),
+                    html.Td(text, className="assume-text")]
+        if note:
+            children.append(html.Td(note, className="assume-note"))
+        else:
+            children.append(html.Td("", className="assume-note"))
+        return html.Tr(children)
+
+    return html.Div(className="uf-page-content", children=[
+        html.H2("Theory", className="page-h2"),
+
+        # ---- Model assumptions ----
+        _h3("Model Assumptions"),
+        _p(
+            "UpdraftForcing is a **kinematic diagnostic model** — it does not time-step. "
+            "The table below lists the key assumptions required for reproducibility."
+        ),
+        html.Table(className="assume-table", children=[html.Tbody([
+            _assume("Anelastic approximation",
+                    "Acoustic modes filtered; ∇·(ρ₀**u**) = 0. "
+                    "Base-state density ρ₀(z) from the WK sounding."),
+            _assume("Horizontally homogeneous environment",
+                    "U(z), V(z) vary only with height; no mesoscale gradients."),
+            _assume("Kinematically prescribed updraft",
+                    "w(x,y,z) is imposed; there is no momentum equation or "
+                    "feedback from the diagnosed pressure on the flow."),
+            _assume("1-D pseudoadiabatic parcel model",
+                    "Condensate is removed immediately (no liquid-water loading). "
+                    "Virtual temperature correction applied throughout."),
+            _assume("Solid-body rotation within core radius r₀",
+                    "v_θ(r) = ζ(z)·r/2 for r ≤ r₀; w and ζ taper to zero at r₀."),
+            _assume("Prescribed accumulated vorticity ζ(z)",
+                    "Represents the rotation a mature storm has built up via tilting "
+                    "and stretching; not diagnosed from the tendency equation."),
+            _assume("Poisson BCs: Neumann top and bottom",
+                    "∂p'/∂z = 0 at z = 0 m and z = 16 000 m. "
+                    "Periodic in x and y (implicit via FFT)."),
+            _assume("Grid: 100 × 100 × 161 points, Δx = Δy = Δz = 100 m",
+                    "Domain 10 km × 10 km × 16 km AGL. "
+                    "Updraft centered at (5 km, 5 km)."),
+            _assume("Single updraft cell; no downdraft, anvil, or cold pool", ""),
+            _assume("No surface fluxes, radiation, or Coriolis force", ""),
+        ])]),
+
+        # ---- Sounding ----
+        _h3("Weisman-Klemp Analytic Sounding"),
+        _p(
+            "The environmental profile follows Weisman and Klemp (1982). "
+            r"Potential temperature $\theta$ is prescribed in three layers:"
+        ),
+        _eq(
+            r"\theta(z) = \begin{cases}"
+            r"  \theta_{ml} & z \leq z_{ml} \\"
+            r"  \theta_{ml} + (\theta_{trop} - \theta_{ml})\!\left(\dfrac{z - z_{ml}}{z_{trop} - z_{ml}}\right)^{\!\gamma} & z_{ml} < z \leq z_{trop} \\"
+            r"  \theta_{trop}\,\exp\!\left(\dfrac{N^2\,(z - z_{trop})}{g}\right) & z > z_{trop}"
+            r"\end{cases}"
+        ),
+        _p(
+            r"Pressure is integrated hydrostatically from the surface. "
+            r"Free-troposphere moisture is set to 45% RH; above the tropopause "
+            r"$N^2 = 4 \times 10^{-4}\ \mathrm{s}^{-2}$. "
+            r"Boundary-layer $q_v$ is constant at $q_{v,ml}$."
+        ),
+
+        # ---- Parcel model ----
+        _h3("1-D Parcel Model and Diagnosed w(z)"),
+        _p(
+            r"A surface parcel with temperature excess $\Delta T$ is lifted "
+            r"dry-adiabatically below the LCL and moist-adiabatically above. "
+            r"Virtual temperature correction is applied throughout. Buoyancy:"
+        ),
+        _eq(
+            r"B(z) = g \cdot \frac{T_{v,\mathrm{parcel}}(z) - T_{v,\mathrm{env}}(z)}{T_{v,\mathrm{env}}(z)}"
+        ),
+        _p(r"Vertical velocity is diagnosed by integrating $B$ upward from the surface:"),
+        _eq(
+            r"w^2(z) = \max\!\left(0,\; 2\int_0^z B(z')\,dz'\right)"
+        ),
+        _p(
+            r"Above the equilibrium level the parcel is negatively buoyant; $w$ continues to "
+            r"decelerate until $w \to 0$ at the overshooting top $z_{top}$."
+        ),
+
+        # ---- Pressure decomposition ----
+        _h3("Pressure Perturbation Decomposition  (Trapp 2013)"),
+        _p(r"For an anelastic atmosphere the pressure perturbation satisfies:"),
+        _eq(
+            r"\nabla^2 p' = F_{\mathrm{lin}} + F_{\mathrm{spin}} + F_{\mathrm{splat}} + F_{\mathrm{buoy}}"
+        ),
+        _p("Each component is solved independently so their spatial structures can be compared directly."),
+
+        html.Div(className="theory-grid", children=[
+            html.Div([
+                html.Div("Linear (shear interaction)", className="theory-term-title"),
+                _eq(
+                    r"F_{\mathrm{lin}} = -2\rho_0 \left["
+                    r"\frac{\partial U}{\partial z}\frac{\partial w'}{\partial x}"
+                    r"+ \frac{\partial V}{\partial z}\frac{\partial w'}{\partial y}\right]"
+                ),
+                _p(
+                    r"Interaction of the environmental shear with horizontal gradients of the "
+                    r"updraft. Produces high $p'$ on the upshear flank and low $p'$ downshear, "
+                    r"deflecting the updraft toward high pressure."
+                ),
+            ], className="theory-term"),
+            html.Div([
+                html.Div("Nonlinear spin", className="theory-term-title"),
+                _eq(
+                    r"\begin{aligned}"
+                    r"F_{\mathrm{spin}} &= +\rho_0 \sum_{i,j} R_{ij}^2 \\"
+                    r"R_{ij} &= \tfrac{1}{2}\!\left(\frac{\partial u_i'}{\partial x_j}"
+                    r"- \frac{\partial u_j'}{\partial x_i}\right)"
+                    r"\end{aligned}"
+                ),
+                _p(
+                    r"Rotation-rate tensor squared. Always produces low $p'$ — "
+                    r"the dynamic pipe effect. Drives upward acceleration inside "
+                    r"a rotating mesocyclone."
+                ),
+            ], className="theory-term"),
+            html.Div([
+                html.Div("Nonlinear splat", className="theory-term-title"),
+                _eq(
+                    r"\begin{aligned}"
+                    r"F_{\mathrm{splat}} &= -\rho_0 \sum_{i,j} S_{ij}^2 \\"
+                    r"S_{ij} &= \tfrac{1}{2}\!\left(\frac{\partial u_i'}{\partial x_j}"
+                    r"+ \frac{\partial u_j'}{\partial x_i}\right)"
+                    r"\end{aligned}"
+                ),
+                _p(
+                    r"Strain-rate tensor squared. Produces high $p'$ wherever the flow "
+                    r"is being deformed — typically at the updraft base and flanks."
+                ),
+            ], className="theory-term"),
+            html.Div([
+                html.Div("Buoyancy", className="theory-term-title"),
+                _eq(
+                    r"F_{\mathrm{buoy}} = -\rho_0 \frac{g}{\theta_0}\frac{\partial \theta'}{\partial z}"
+                ),
+                _p(
+                    r"Vertical gradient of the potential temperature perturbation. "
+                    r"Produces low $p'$ above warm anomalies, reinforcing buoyant acceleration."
+                ),
+            ], className="theory-term"),
+        ]),
+
+        # ---- Poisson solver ----
+        _h3("Poisson Solver — 2-D FFT + Tridiagonal"),
+        _p(
+            r"Each forcing component $F(x,y,z)$ is transformed via 2-D real FFT in $x,y$. "
+            r"For each horizontal wavenumber pair $(k_x,\,k_y)$ the following vertical ODE is solved:"
+        ),
+        _eq(
+            r"-(k_x^2 + k_y^2)\,\hat{P}(k_x,k_y,z) + \frac{d^2\hat{P}}{dz^2} = \hat{F}(k_x,k_y,z)"
+        ),
+        _p(
+            r"Neumann boundary conditions $\partial p'/\partial z = 0$ are applied at "
+            r"$z = 0$ and $z = z_{top}$. The tridiagonal systems for all $(k_x,k_y)$ pairs "
+            r"are solved simultaneously with a vectorized Thomas algorithm "
+            r"(~0.08 s per forcing component). An inverse 2-D real FFT recovers $p'(x,y,z)$."
+        ),
+
+        # ---- Diagnostics ----
+        _h3("Storm Diagnostics"),
+        _p(r"Storm motion from Bunkers et al. (2000):"),
+        _eq(
+            r"\mathbf{c}_{\mathrm{RM}} = \bar{\mathbf{u}}_{0\text{–}6\,\mathrm{km}} + \mathbf{D}_\perp,"
+            r"\qquad |\mathbf{D}_\perp| = 7.5\ \mathrm{m\,s^{-1}}\ \perp\ \text{0–6 km shear}"
+        ),
+        _p(r"Storm-relative helicity:"),
+        _eq(
+            r"\mathrm{SRH} = \sum_{n} \bigl[(u_{n+1} - c_u)(v_n - c_v)"
+            r"- (u_n - c_u)(v_{n+1} - c_v)\bigr]"
+        ),
+        _p(r"Updraft helicity (nonzero only when $\zeta$ is prescribed):"),
+        _eq(
+            r"\mathrm{UH} = \int_{z_{\mathrm{bot}}}^{z_{\mathrm{top}}}"
+            r"w(0,0,z)\;\zeta_z(0,0,z)\;dz"
+        ),
+
+        # ---- References ----
+        html.H3("References", className="theory-h3", style={"marginTop": "30px"}),
+        html.Ol(className="theory-refs", children=[
+            _ref("Trapp, R. J.", 2013,
+                 "Mesoscale-Convective Processes in the Atmosphere",
+                 "Cambridge University Press"),
+            _ref("Weisman, M. L. and Klemp, J. B.", 1982,
+                 "The dependence of numerically simulated convective storms on vertical wind "
+                 "shear and buoyancy",
+                 "Mon. Wea. Rev., 110, 504–520"),
+            _ref("Bunkers, M. J., Klimowski, B. A., Zeitler, J. W., Thompson, R. L., "
+                 "and Hjelmfelt, M. R.", 2000,
+                 "Predicting supercell motion using a new hodograph technique",
+                 "Wea. Forecasting, 15, 61–79"),
+            _ref("Bolton, D.", 1980,
+                 "The computation of equivalent potential temperature",
+                 "Mon. Wea. Rev., 108, 1046–1053"),
+        ]),
+    ])
+
+
 # ---------------------------------------------------------------------------
 # Layout
 # ---------------------------------------------------------------------------
 
 def _build_layout():
-    # Initial computation with defaults
     diag = _run_model(SND_DEFAULTS, UPD_DEFAULTS, WK_U, WK_V, ZETA_DEFAULTS)
 
+    # ---- Left panel ----
     left = html.Div(className="uf-left", children=[
         dcc.Tabs(id="ctrl-tabs", value="sounding", className="uf-tabs", children=[
 
-            # --- Sounding tab ---
             dcc.Tab(label="Sounding", value="sounding", className="uf-tab",
                     selected_className="uf-tab-sel", children=html.Div([
                 html.Div("Weisman-Klemp Sounding", className="uf-section-title"),
-                _slider("snd-theta-ml", "θ_ml (K)", 295, 315, 0.5, SND_DEFAULTS["theta_ml"]),
-                _slider("snd-qv-ml", "qv_ml (g/kg)", 8, 20, 0.5, SND_DEFAULTS["qv_ml"]),
-                _slider("snd-z-ml", "BL depth (m)", 500, 2000, 100, SND_DEFAULTS["z_ml"], " m"),
-                _slider("snd-z-trop", "Tropopause ht. (m)", 9000, 14000, 250, SND_DEFAULTS["z_trop"], " m"),
-                _slider("snd-T-trop", "Tropopause T (K)", 195, 220, 1, SND_DEFAULTS["T_trop"], " K"),
-                _slider("snd-gamma", "Lapse rate exp.", 0.8, 1.8, 0.05, SND_DEFAULTS["gamma_ft"]),
+                _slider("snd-theta-ml", "θ_ml (K)", 295, 315, 0.5, SND_DEFAULTS["theta_ml"],
+                        tip="Mixed-layer potential temperature. Higher values give a warmer "
+                            "boundary layer and more buoyancy."),
+                _slider("snd-qv-ml", "qv_ml (g/kg)", 8, 20, 0.5, SND_DEFAULTS["qv_ml"],
+                        tip="Boundary-layer water vapor mixing ratio. More moisture lowers "
+                            "the LCL and increases CAPE."),
+                _slider("snd-z-ml", "BL depth (m)", 500, 2000, 100, SND_DEFAULTS["z_ml"], " m",
+                        tip="Depth of the well-mixed layer. The constant-θ and qv profile "
+                            "extends to this height."),
+                _slider("snd-z-trop", "Tropopause ht. (m)", 9000, 14000, 250,
+                        SND_DEFAULTS["z_trop"], " m",
+                        tip="Height of the tropopause. A higher tropopause allows a deeper "
+                            "updraft and more CAPE."),
+                _slider("snd-T-trop", "Tropopause T (K)", 195, 220, 1,
+                        SND_DEFAULTS["T_trop"], " K",
+                        tip="Temperature at the tropopause. Colder tropopause → larger "
+                            "temperature difference from the surface → more CAPE."),
+                _slider("snd-gamma", "Lapse rate exp.", 0.8, 1.8, 0.05,
+                        SND_DEFAULTS["gamma_ft"],
+                        tip="Shape exponent γ for the free-troposphere θ profile: "
+                            "θ = θ_ml + (θ_trop−θ_ml)·((z−z_ml)/(z_trop−z_ml))^γ. "
+                            "γ=1 linear; γ<1 more unstable near surface; γ>1 near tropopause."),
                 html.Div(className="uf-preset-row", children=[
-                    html.Button("WK Supercell", id="preset-wk",  className="uf-btn"),
+                    html.Button("WK Supercell", id="preset-wk",   className="uf-btn"),
                     html.Button("Weak shear",   id="preset-weak", className="uf-btn"),
                     html.Button("Reset",        id="preset-reset", className="uf-btn"),
                 ]),
             ])),
 
-            # --- Updraft tab ---
             dcc.Tab(label="Updraft", value="updraft", className="uf-tab",
                     selected_className="uf-tab-sel", children=html.Div([
                 html.Div("Updraft Core", className="uf-section-title"),
                 html.Div([
                     html.Span("ΔT surface (K)", className="uf-slider-label"),
+                    _help("Temperature excess of the surface parcel above the environment. "
+                          "Drives the diagnosed w(z): w²(z) = max(0, 2·∫B dz). "
+                          "Larger ΔT → more KE to overcome CIN → stronger updraft."),
                     dcc.Input(id="upd-delta-T", type="number", value=UPD_DEFAULTS["delta_T"],
                               step=0.1, min=0.1, max=10.0,
                               style={"width": "80px", "marginLeft": "8px",
                                      "background": "#0f1520", "border": "1px solid #2d3a4b",
-                                     "color": "#dfe3ea", "padding": "4px 8px", "borderRadius": "4px"}),
+                                     "color": "#dfe3ea", "padding": "4px 8px",
+                                     "borderRadius": "4px"}),
                 ], style={"display": "flex", "alignItems": "center", "marginBottom": "10px"}),
-                _slider("upd-r0", "Radius (m)", 500, 5000, 100, UPD_DEFAULTS["r0"], " m"),
-                html.Div("Prescribed ζ(z) — accumulated storm rotation",
-                         className="uf-section-title", style={"marginTop": "12px"}),
+                _slider("upd-r0", "Radius (m)", 500, 5000, 100, UPD_DEFAULTS["r0"], " m",
+                        tip="Updraft core radius. The radial shape function tapers w and ζ "
+                            "to zero at this distance from center."),
+                html.Div([
+                    html.Div("Prescribed ζ(z) — accumulated storm rotation",
+                             className="uf-section-title", style={"marginTop": "12px"}),
+                    _help("Vertical vorticity profile representing rotation that the storm "
+                          "has built up via tilting and stretching over its lifetime. "
+                          "Drag circles rightward for cyclonic (positive) rotation. "
+                          "This drives p'_spin and updraft helicity."),
+                ], style={"display": "flex", "alignItems": "center", "gap": "6px"}),
                 _profile_editor("zeta-profile", "ζ(z) (s⁻¹)",
                                 ZETA_DEFAULTS, ZETA_Z_KM, "s⁻¹", (-0.05, 0.05)),
-                html.Div("Core shape", className="uf-slider-label", style={"marginTop": "10px"}),
+                html.Div([
+                    html.Span("Core shape", className="uf-slider-label"),
+                    _help("Top-hat: uniform w inside 90% of r₀ with cosine taper in the outer 10%. "
+                          "Cosine bell: w(r) = cos(π·r/2r₀), smooth with no flat core."),
+                ], style={"display": "flex", "alignItems": "center", "gap": "6px",
+                          "marginTop": "10px"}),
                 dcc.RadioItems(
                     id="upd-shape",
                     options=[{"label": "  Top-hat", "value": "tophat"},
-                             {"label": "  Cosine", "value": "cosine"}],
+                             {"label": "  Cosine",  "value": "cosine"}],
                     value=UPD_DEFAULTS["shape"],
                     labelStyle={"marginRight": "14px", "color": "#dfe3ea", "fontSize": "13px"},
                     style={"marginBottom": "10px"},
                 ),
             ])),
 
-            # --- Hodograph tab ---
             dcc.Tab(label="Hodograph", value="hodograph", className="uf-tab",
                     selected_className="uf-tab-sel", children=html.Div([
                 html.Div("Environmental hodograph", className="uf-section-title"),
                 dcc.Graph(id="hodograph",
                           figure=_hodo_figure(WK_U, WK_V,
                                               storm_u=diag["storm_u"], storm_v=diag["storm_v"],
-                                              lm_u=diag["lm_u"], lm_v=diag["lm_v"],
-                                              mean_u=diag["mean_u"], mean_v=diag["mean_v"]),
+                                              lm_u=diag["lm_u"],       lm_v=diag["lm_v"],
+                                              mean_u=diag["mean_u"],   mean_v=diag["mean_v"]),
                           config={"edits": {"shapePosition": True},
                                   "displayModeBar": False, "scrollZoom": False}),
-                html.Div("Drag the gold circles to edit the wind at each level.",
-                         style={"color": "#8f98a3", "fontSize": "11px", "marginTop": "6px"}),
+                html.Div([
+                    html.Span("Drag the gold circles to edit the wind at each level (km label). "
+                              "RM = Bunkers right-mover, LM = left-mover, × = mean wind.",
+                              style={"color": "#8f98a3", "fontSize": "11px"}),
+                    _help("Wind levels: 0, 1, 2, 3, 4, 5, 6, 8, 10 km. "
+                          "Storm motion (RM/LM) is computed using Bunkers et al. (2000): "
+                          "mean 0–6 km wind ± 7.5 m/s perpendicular to the 0–6 km shear vector. "
+                          "SRH is computed relative to the right-mover."),
+                ], style={"display": "flex", "alignItems": "flex-start", "gap": "6px",
+                          "marginTop": "6px"}),
             ])),
         ]),
     ])
 
+    # ---- Center panel ----
     center = html.Div(className="uf-center", children=[
         html.Div(className="uf-field-controls", children=[
             dcc.Dropdown(
                 id="field-select",
                 options=[{"label": v, "value": k} for k, v in FIELD_LABELS.items()],
-                value="w",
-                clearable=False,
+                value="w", clearable=False,
                 style={"width": "240px", "fontSize": "13px"},
             ),
             dcc.Tabs(id="view-tabs", value="plan", className="uf-view-tabs", children=[
@@ -444,12 +803,12 @@ def _build_layout():
                       style={"color": "#6ecbff", "fontSize": "12px", "minWidth": "80px"}),
         ]),
         dcc.Graph(id="main-heatmap", config={"displayModeBar": False}),
-        # Diagnosed w(z) profile
         html.Div(className="uf-section-title", style={"marginTop": "14px"},
                  children="Diagnosed w(z) from parcel model"),
         dcc.Graph(id="w-profile-graph", config={"displayModeBar": False}),
     ])
 
+    # ---- Right panel ----
     right = html.Div(className="uf-right", children=[
         html.Div("Sounding Parameters", className="uf-section-title"),
         html.Table(id="diag-table", style={"width": "100%", "borderCollapse": "collapse"}),
@@ -459,17 +818,25 @@ def _build_layout():
         dcc.Graph(id="accel-profile", config={"displayModeBar": False}),
     ])
 
+    model_layout = html.Div(className="uf-main", children=[left, center, right])
+
     return html.Div(className="uf-root", children=[
         html.Div(className="uf-header", children=[
             html.H1("UpdraftForcing", style={"margin": "0 0 4px 0", "fontSize": "22px"}),
-            html.Div("Convective updraft wind shear diagnostics — Trapp (2013)",
+            html.Div("Convective updraft wind shear diagnostics",
                      style={"color": "#9aa3ad", "fontSize": "12px"}),
         ]),
-        # Hidden stores
-        dcc.Store(id="hodo-store",  data={"u": WK_U, "v": WK_V}),
-        dcc.Store(id="zeta-store",  data={"zeta": ZETA_DEFAULTS}),
-        dcc.Store(id="model-rev",   data=0),
-        html.Div(className="uf-main", children=[left, center, right]),
+        dcc.Tabs(id="page-tabs", value="model", className="uf-page-tabs", children=[
+            dcc.Tab(label="Model",           value="model",   className="uf-ptab", selected_className="uf-ptab-sel",
+                    children=model_layout),
+            dcc.Tab(label="Getting Started", value="help",    className="uf-ptab", selected_className="uf-ptab-sel",
+                    children=_getting_started_content()),
+            dcc.Tab(label="Theory",          value="theory",  className="uf-ptab", selected_className="uf-ptab-sel",
+                    children=_theory_content()),
+        ]),
+        dcc.Store(id="hodo-store", data={"u": WK_U, "v": WK_V}),
+        dcc.Store(id="zeta-store", data={"zeta": ZETA_DEFAULTS}),
+        dcc.Store(id="model-rev",  data=0),
     ])
 
 
@@ -479,9 +846,6 @@ def _build_layout():
 
 def _register_callbacks(app):
 
-    # ------------------------------------------------------------------
-    # 1. Sounding slider value labels
-    # ------------------------------------------------------------------
     for sid, unit in [("snd-theta-ml", " K"), ("snd-qv-ml", " g/kg"),
                       ("snd-z-ml", " m"), ("snd-z-trop", " m"),
                       ("snd-T-trop", " K"), ("snd-gamma", ""),
@@ -491,9 +855,6 @@ def _register_callbacks(app):
         def _upd_label(v, _unit=unit):
             return f"{v}{_unit}"
 
-    # ------------------------------------------------------------------
-    # 2. Preset buttons → sounding + updraft sliders
-    # ------------------------------------------------------------------
     @app.callback(
         [Output("snd-theta-ml", "value"), Output("snd-qv-ml", "value"),
          Output("snd-z-ml", "value"),     Output("snd-z-trop", "value"),
@@ -507,23 +868,16 @@ def _register_callbacks(app):
         prevent_initial_call=True,
     )
     def _preset(wk, weak, reset):
-        trig = ctx.triggered_id
-        if trig == "preset-weak":
+        if ctx.triggered_id == "preset-weak":
             u = [0, 5, 10, 15, 20, 22, 23, 24, 25]
             v = [0, 0,  0,  0,  0,  0,  0,  0,  0]
-            return (300, 12, 1000, 11000, 215, 1.2, 2.0, 2500, "tophat",
-                    {"u": u, "v": v})
-        # WK supercell or reset
+            return (300, 12, 1000, 11000, 215, 1.2, 2.0, 2500, "tophat", {"u": u, "v": v})
         return (SND_DEFAULTS["theta_ml"], SND_DEFAULTS["qv_ml"],
                 SND_DEFAULTS["z_ml"],     SND_DEFAULTS["z_trop"],
                 SND_DEFAULTS["T_trop"],   SND_DEFAULTS["gamma_ft"],
                 UPD_DEFAULTS["delta_T"],  UPD_DEFAULTS["r0"],
-                UPD_DEFAULTS["shape"],
-                {"u": WK_U, "v": WK_V})
+                UPD_DEFAULTS["shape"],    {"u": WK_U, "v": WK_V})
 
-    # ------------------------------------------------------------------
-    # 3. Hodograph drag → update hodo-store
-    # ------------------------------------------------------------------
     @app.callback(
         Output("hodo-store", "data"),
         Input("hodograph", "relayoutData"),
@@ -533,31 +887,16 @@ def _register_callbacks(app):
     def _hodo_drag(relay, store):
         if not relay:
             return no_update
-        u = list(store["u"])
-        v = list(store["v"])
-        changed = False
+        u = list(store["u"]); v = list(store["v"]); changed = False
         for i in range(len(u)):
-            kxa = f"shapes[{i}].xanchor"
-            kya = f"shapes[{i}].yanchor"
-            if kxa in relay:
-                try:
-                    u[i] = max(-60.0, min(60.0, float(relay[kxa])))
-                    changed = True
-                except (TypeError, ValueError):
-                    pass
-            if kya in relay:
-                try:
-                    v[i] = max(-60.0, min(60.0, float(relay[kya])))
-                    changed = True
-                except (TypeError, ValueError):
-                    pass
-        if not changed:
-            return no_update
-        return {"u": u, "v": v}
+            for key, lst in [(f"shapes[{i}].xanchor", u), (f"shapes[{i}].yanchor", v)]:
+                if key in relay:
+                    try:
+                        lst[i] = max(-60.0, min(60.0, float(relay[key]))); changed = True
+                    except (TypeError, ValueError):
+                        pass
+        return {"u": u, "v": v} if changed else no_update
 
-    # ------------------------------------------------------------------
-    # 4. ζ(z) profile drag → update zeta-store
-    # ------------------------------------------------------------------
     @app.callback(
         Output("zeta-store", "data"),
         Input("zeta-profile", "relayoutData"),
@@ -567,39 +906,27 @@ def _register_callbacks(app):
     def _zeta_drag(relay, store):
         if not relay:
             return no_update
-        zeta = list(store["zeta"])
-        changed = False
+        zeta = list(store["zeta"]); changed = False
         for i in range(len(zeta)):
             kxa = f"shapes[{i}].xanchor"
             if kxa in relay:
                 try:
-                    zeta[i] = max(-0.10, min(0.10, float(relay[kxa])))
-                    changed = True
+                    zeta[i] = max(-0.10, min(0.10, float(relay[kxa]))); changed = True
                 except (TypeError, ValueError):
                     pass
-        if not changed:
-            return no_update
-        return {"zeta": zeta}
+        return {"zeta": zeta} if changed else no_update
 
-    # ------------------------------------------------------------------
-    # 5. Redraw hodograph when hodo-store changes
-    # ------------------------------------------------------------------
     @app.callback(
         Output("hodograph", "figure"),
         [Input("hodo-store", "data"), Input("model-rev", "data")],
     )
     def _redraw_hodo(store, _rev):
-        diag = _C.get("diag", {})
-        return _hodo_figure(
-            store["u"], store["v"],
-            storm_u=diag.get("storm_u"), storm_v=diag.get("storm_v"),
-            lm_u=diag.get("lm_u"),     lm_v=diag.get("lm_v"),
-            mean_u=diag.get("mean_u"), mean_v=diag.get("mean_v"),
-        )
+        d = _C.get("diag", {})
+        return _hodo_figure(store["u"], store["v"],
+                            storm_u=d.get("storm_u"), storm_v=d.get("storm_v"),
+                            lm_u=d.get("lm_u"),       lm_v=d.get("lm_v"),
+                            mean_u=d.get("mean_u"),    mean_v=d.get("mean_v"))
 
-    # ------------------------------------------------------------------
-    # 6. Main model compute → model-rev increment
-    # ------------------------------------------------------------------
     @app.callback(
         Output("model-rev", "data"),
         [Input("snd-theta-ml", "value"), Input("snd-qv-ml", "value"),
@@ -615,29 +942,24 @@ def _register_callbacks(app):
                  delta_T, r0, shape, hodo, zeta_data, rev):
         snd_p = dict(
             theta_ml=theta_ml or SND_DEFAULTS["theta_ml"],
-            qv_ml=qv_ml or SND_DEFAULTS["qv_ml"],
-            z_ml=z_ml or SND_DEFAULTS["z_ml"],
-            z_trop=z_trop or SND_DEFAULTS["z_trop"],
-            T_trop=T_trop or SND_DEFAULTS["T_trop"],
+            qv_ml=qv_ml    or SND_DEFAULTS["qv_ml"],
+            z_ml=z_ml      or SND_DEFAULTS["z_ml"],
+            z_trop=z_trop  or SND_DEFAULTS["z_trop"],
+            T_trop=T_trop  or SND_DEFAULTS["T_trop"],
             gamma_ft=gamma or SND_DEFAULTS["gamma_ft"],
         )
         upd_p = dict(
             delta_T=delta_T or UPD_DEFAULTS["delta_T"],
-            r0=r0 or UPD_DEFAULTS["r0"],
+            r0=r0    or UPD_DEFAULTS["r0"],
             shape=shape or UPD_DEFAULTS["shape"],
         )
         try:
-            _run_model(snd_p, upd_p,
-                       hodo["u"], hodo["v"],
-                       zeta_data["zeta"])
+            _run_model(snd_p, upd_p, hodo["u"], hodo["v"], zeta_data["zeta"])
         except Exception as exc:
             import traceback; traceback.print_exc()
             print(f"[UpdraftForcing] compute error: {exc!r}", flush=True)
         return (rev or 0) + 1
 
-    # ------------------------------------------------------------------
-    # 7. Slice-slider label update
-    # ------------------------------------------------------------------
     @app.callback(
         Output("slice-label", "children"),
         [Input("slice-slider", "value"), Input("view-tabs", "value")],
@@ -653,92 +975,63 @@ def _register_callbacks(app):
         else:
             return f"x = {X_KM[idx % NX]:.1f} km"
 
-    # ------------------------------------------------------------------
-    # 8. Slice-slider range update when view changes
-    # ------------------------------------------------------------------
     @app.callback(
         [Output("slice-slider", "max"), Output("slice-slider", "value")],
         Input("view-tabs", "value"),
     )
     def _slice_range(view):
-        if view == "plan":
-            return NZ - 1, NZ // 4
-        elif view == "xcross":
-            return NY - 1, NY // 2
-        else:
-            return NX - 1, NX // 2
+        if view == "plan":   return NZ - 1, NZ // 4
+        if view == "xcross": return NY - 1, NY // 2
+        return NX - 1, NX // 2
 
-    # ------------------------------------------------------------------
-    # 9. Main heatmap display
-    # ------------------------------------------------------------------
     @app.callback(
         Output("main-heatmap", "figure"),
-        [Input("field-select", "value"),
-         Input("view-tabs", "value"),
-         Input("slice-slider", "value"),
-         Input("model-rev", "data")],
+        [Input("field-select", "value"), Input("view-tabs", "value"),
+         Input("slice-slider", "value"), Input("model-rev", "data")],
     )
     def _display(field, view, idx, _rev):
         arr = _C.get(field)
         if arr is None:
             return go.Figure()
-
         if view == "plan":
             k = min(idx, NZ - 1)
-            slice2d = arr[:, :, k]
-            title = f"{FIELD_LABELS.get(field, field)} — z = {Z_GRID[k]/1000:.1f} km"
-            return _field_heatmap(slice2d, X_KM, Y_KM, "x (km)", "y (km)", title, field)
+            return _field_heatmap(arr[:, :, k], X_KM, Y_KM, "x (km)", "y (km)",
+                                  f"{FIELD_LABELS.get(field, field)} — z = {Z_GRID[k]/1000:.1f} km", field)
         elif view == "xcross":
             j = min(idx, NY - 1)
-            slice2d = arr[:, j, :]   # (Nx, Nz)
-            z_km = Z_GRID / 1000.0
-            title = f"{FIELD_LABELS.get(field, field)} — y = {Y_KM[j]:.1f} km"
-            return _field_heatmap(slice2d, X_KM, z_km, "x (km)", "z (km)", title, field)
+            return _field_heatmap(arr[:, j, :], X_KM, Z_GRID/1000.0, "x (km)", "z (km)",
+                                  f"{FIELD_LABELS.get(field, field)} — y = {Y_KM[j]:.1f} km", field)
         else:
             i = min(idx, NX - 1)
-            slice2d = arr[i, :, :]   # (Ny, Nz)
-            z_km = Z_GRID / 1000.0
-            title = f"{FIELD_LABELS.get(field, field)} — x = {X_KM[i]:.1f} km"
-            return _field_heatmap(slice2d, Y_KM, z_km, "y (km)", "z (km)", title, field)
-
-    # ------------------------------------------------------------------
-    # 10. Diagnosed w(z) profile display
-    # ------------------------------------------------------------------
+            return _field_heatmap(arr[i, :, :], Y_KM, Z_GRID/1000.0, "y (km)", "z (km)",
+                                  f"{FIELD_LABELS.get(field, field)} — x = {X_KM[i]:.1f} km", field)
+
     @app.callback(
         Output("w-profile-graph", "figure"),
         Input("model-rev", "data"),
     )
     def _w_profile_fig(_rev):
-        w_z = _C.get("w_z", np.zeros(NZ))
-        EL = _C.get("EL_m", 12000.0)
+        w_z   = _C.get("w_z",   np.zeros(NZ))
+        EL    = _C.get("EL_m",    12000.0)
         z_top = _C.get("z_top_m", 13000.0)
-        z_km = Z_GRID / 1000.0
-
+        z_km  = Z_GRID / 1000.0
         fig = go.Figure()
-        fig.add_trace(go.Scatter(
-            x=w_z, y=z_km,
-            mode="lines", line=dict(color="#4ab8e0", width=2),
-            name="w_diagnosed", showlegend=False,
-            hovertemplate="%{x:.1f} m/s @ %{y:.2f} km<extra></extra>",
-        ))
-        fig.add_hline(y=EL / 1000.0, line=dict(color="#ffd685", dash="dash", width=1.5),
+        fig.add_trace(go.Scatter(x=w_z, y=z_km, mode="lines",
+                                 line=dict(color="#4ab8e0", width=2),
+                                 hovertemplate="%{x:.1f} m/s @ %{y:.2f} km<extra></extra>",
+                                 showlegend=False))
+        fig.add_hline(y=EL/1000.0, line=dict(color="#ffd685", dash="dash", width=1.5),
                       annotation_text="EL", annotation_font_color="#ffd685",
                       annotation_position="top right")
-        fig.add_hline(y=z_top / 1000.0, line=dict(color="#ff8c00", dash="dash", width=1.5),
+        fig.add_hline(y=z_top/1000.0, line=dict(color="#ff8c00", dash="dash", width=1.5),
                       annotation_text="Overshoot top", annotation_font_color="#ff8c00",
                       annotation_position="top right")
-        fig.update_layout(
-            xaxis_title="w (m s⁻¹)", yaxis_title="z (km)",
-            template="plotly_dark",
-            margin=dict(l=50, r=10, t=10, b=35),
-            height=200,
-            xaxis=dict(rangemode="tozero"),
-        )
+        fig.update_layout(xaxis_title="w (m s⁻¹)", yaxis_title="z (km)",
+                          template="plotly_dark",
+                          margin=dict(l=50, r=10, t=10, b=35), height=200,
+                          xaxis=dict(rangemode="tozero"))
         return fig
 
-    # ------------------------------------------------------------------
-    # 11. Diagnostics table
-    # ------------------------------------------------------------------
     @app.callback(
         Output("diag-table", "children"),
         Input("model-rev", "data"),
@@ -761,9 +1054,6 @@ def _register_callbacks(app):
         ]
         return html.Tbody(rows)
 
-    # ------------------------------------------------------------------
-    # 12. Buoyancy and acceleration profiles
-    # ------------------------------------------------------------------
     @app.callback(
         [Output("buoy-profile", "figure"), Output("accel-profile", "figure")],
         Input("model-rev", "data"),
@@ -771,37 +1061,23 @@ def _register_callbacks(app):
     def _profiles(_rev):
         z_km = Z_GRID / 1000.0
         cx, cy = NX // 2, NY // 2
-
         B_z = _C.get("B_z", np.zeros(NZ))
         buoy_fig = _profile_fig(B_z, z_km, "Buoyancy B(z)", "#4ab8e0", "m s⁻²")
 
-        # Acceleration profiles at core center
-        a_lin   = _C.get("a_lin",   np.zeros((NX, NY, NZ)))
-        a_spin  = _C.get("a_spin",  np.zeros((NX, NY, NZ)))
-        a_splat = _C.get("a_splat", np.zeros((NX, NY, NZ)))
-        a_buoy  = _C.get("a_buoy",  np.zeros((NX, NY, NZ)))
-
         fig = go.Figure()
-        for arr, name, col in [
-            (a_lin,   "Linear",  "#e09c4a"),
-            (a_spin,  "Spin",    "#c8d44a"),
-            (a_splat, "Splat",   "#e06c6c"),
-            (a_buoy,  "Buoyancy","#4ab8e0"),
-        ]:
-            fig.add_trace(go.Scatter(
-                x=arr[cx, cy, :], y=z_km,
-                mode="lines", name=name,
-                line=dict(color=col, width=1.8),
-                hovertemplate=f"%{{x:.3g}} m/s²<br>%{{y:.1f}} km<extra>{name}</extra>",
-            ))
+        for key, name, col in [("a_lin",  "Linear",   "#e09c4a"),
+                                ("a_spin", "Spin",     "#c8d44a"),
+                                ("a_splat","Splat",    "#e06c6c"),
+                                ("a_buoy", "Buoyancy", "#4ab8e0")]:
+            arr = _C.get(key, np.zeros((NX, NY, NZ)))
+            fig.add_trace(go.Scatter(x=arr[cx, cy, :], y=z_km, mode="lines", name=name,
+                                     line=dict(color=col, width=1.8),
+                                     hovertemplate=f"%{{x:.3g}} m/s²<br>%{{y:.1f}} km<extra>{name}</extra>"))
         fig.add_vline(x=0, line=dict(color="#555", width=1))
-        fig.update_layout(
-            xaxis_title="acceleration (m s⁻²)", yaxis_title="z (km)",
-            template="plotly_dark",
-            margin=dict(l=50, r=10, t=10, b=35),
-            height=220,
-            legend=dict(font=dict(size=10), orientation="h", y=1.05),
-        )
+        fig.update_layout(xaxis_title="acceleration (m s⁻²)", yaxis_title="z (km)",
+                          template="plotly_dark",
+                          margin=dict(l=50, r=10, t=10, b=35), height=220,
+                          legend=dict(font=dict(size=10), orientation="h", y=1.05))
         return buoy_fig, fig
 
 
@@ -812,15 +1088,24 @@ def _register_callbacks(app):
 _CSS = """
 body { background: #0b0e14; color: #dfe3ea; font-family: -apple-system, system-ui, sans-serif; margin: 0; }
 .uf-root { max-width: 1600px; margin: 0 auto; padding: 16px; }
-.uf-header { margin-bottom: 14px; }
+.uf-header { margin-bottom: 6px; }
 .uf-header h1 { color: #6ecbff; }
+
+/* Page-level navigation tabs */
+.uf-page-tabs { margin-bottom: 0; }
+.uf-page-tabs > .tab-container { border-bottom: 1px solid #2d3a4b !important; margin-bottom: 14px; }
+.uf-ptab { background: transparent !important; border: none !important; color: #9aa3ad !important; font-size: 13px !important; padding: 7px 18px !important; }
+.uf-ptab-sel { color: #6ecbff !important; border-bottom: 2px solid #6ecbff !important; background: transparent !important; }
+
+/* Three-column model layout */
 .uf-main { display: grid; grid-template-columns: 320px 1fr 280px; gap: 16px; }
-.uf-left { background: #11161f; border-radius: 8px; padding: 12px; min-height: 600px; }
-.uf-center { background: #11161f; border-radius: 8px; padding: 12px; }
+.uf-left  { background: #11161f; border-radius: 8px; padding: 12px; min-height: 600px; }
+.uf-center{ background: #11161f; border-radius: 8px; padding: 12px; }
 .uf-right { background: #11161f; border-radius: 8px; padding: 12px; }
+
 .uf-section-title { font-size: 11px; font-weight: 600; color: #8d97a2; letter-spacing: 0.08em; text-transform: uppercase; margin-bottom: 8px; margin-top: 4px; }
 .uf-slider-row { margin-bottom: 10px; }
-.uf-slider-header { display: flex; justify-content: space-between; font-size: 12px; margin-bottom: 2px; }
+.uf-slider-header { display: flex; justify-content: space-between; align-items: center; font-size: 12px; margin-bottom: 2px; }
 .uf-slider-label { color: #c7ced6; }
 .uf-slider-value { color: #6ecbff; font-variant-numeric: tabular-nums; }
 .uf-tabs .tab { background: #161d29; border: none; color: #9aa3ad; font-size: 12px; padding: 6px 12px; }
@@ -836,6 +1121,58 @@ body { background: #0b0e14; color: #dfe3ea; font-family: -apple-system, system-u
 .uf-btn { background: #1e2835; border: 1px solid #2d3a4b; color: #dfe3ea; padding: 5px 10px; border-radius: 5px; cursor: pointer; font-size: 12px; }
 .uf-btn:hover { background: #2a3a4e; }
 table tr:nth-child(even) td { background: #161d29; }
+
+/* ? tooltip */
+.uf-help {
+    display: inline-flex; align-items: center; justify-content: center;
+    width: 15px; height: 15px; border-radius: 50%;
+    background: #253040; color: #6ecbff;
+    font-size: 9px; font-weight: 700; cursor: help;
+    position: relative; flex-shrink: 0; user-select: none;
+}
+.uf-help::after {
+    content: attr(data-tip);
+    position: absolute;
+    right: 0; top: 20px;
+    background: #1a2233; color: #dfe3ea;
+    padding: 8px 11px; border-radius: 6px;
+    border: 1px solid #3b4d63;
+    font-size: 11px; font-weight: 400; line-height: 1.55;
+    white-space: normal; width: 220px;
+    z-index: 2000; display: none;
+    box-shadow: 0 4px 16px rgba(0,0,0,0.5);
+    pointer-events: none;
+}
+.uf-help:hover::after { display: block; }
+
+/* Getting started & Theory pages */
+.uf-page-content { max-width: 900px; margin: 0 auto; padding: 8px 20px 40px 20px; }
+.page-h2 { color: #6ecbff; font-size: 20px; margin-bottom: 20px; }
+.gs-intro { color: #c7ced6; font-size: 13px; line-height: 1.7; margin-bottom: 24px; }
+.gs-step { margin-bottom: 28px; }
+.gs-step-title { font-size: 13px; font-weight: 700; color: #ffd685; margin-bottom: 10px; letter-spacing: 0.03em; }
+.gs-step-body { font-size: 13px; color: #c7ced6; line-height: 1.65; }
+.gs-step-body p { margin: 0 0 8px 0; }
+.gs-table { width: 100%; border-collapse: collapse; }
+.gs-table tr:nth-child(even) td { background: #161d29; }
+.gs-ctrl-label { color: #6ecbff; font-size: 12px; font-weight: 600; padding: 5px 12px 5px 8px; white-space: nowrap; vertical-align: top; width: 140px; }
+.gs-ctrl-desc  { color: #c7ced6; font-size: 12px; padding: 5px 8px; line-height: 1.55; }
+
+.theory-h3 { color: #ffd685; font-size: 14px; margin: 24px 0 8px 0; }
+.theory-p-md p { color: #c7ced6; font-size: 13px; line-height: 1.65; margin: 0 0 8px 0; }
+.theory-p-md strong { color: #dfe3ea; }
+.theory-eq-md { background: #0a0f1a; border-left: 3px solid #3b86e6; border-radius: 4px; padding: 4px 14px; margin: 8px 0 12px 0; text-align: center; overflow-x: auto; }
+.theory-eq-md .MathJax { color: #b0d8ff !important; font-size: 1.05em !important; }
+.theory-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 12px 0 20px 0; }
+.theory-term { background: #11161f; border-radius: 6px; padding: 12px; }
+.theory-term-title { font-size: 12px; font-weight: 700; color: #6ecbff; margin-bottom: 6px; text-transform: uppercase; letter-spacing: 0.06em; }
+.theory-refs { color: #c7ced6; font-size: 13px; line-height: 1.8; padding-left: 20px; }
+.theory-ref { margin-bottom: 6px; }
+.assume-table { width: 100%; border-collapse: collapse; margin: 10px 0 20px 0; font-size: 12px; }
+.assume-table tr:nth-child(even) td { background: #161d29; }
+.assume-check { color: #5ac87a; font-size: 13px; padding: 5px 10px 5px 6px; width: 18px; vertical-align: top; }
+.assume-text  { color: #dfe3ea; font-weight: 600; padding: 5px 12px 5px 4px; width: 310px; vertical-align: top; }
+.assume-note  { color: #8d97a2; padding: 5px 4px; line-height: 1.5; vertical-align: top; }
 """