# Wave-Optics / Atmosphere / AO Surrogate — User Guide

> Public engineering-surrogate propagation emulator. Estimates atmosphere/AO/coupling penalties under declared assumptions and validation limits. Not mission-certified, does not reproduce internal NASA/JPL pipelines, does not replace high-fidelity wave-optics simulation.

---

## What this tool does

The Wave-Optics / Atmosphere / AO Surrogate is a browser-based, seed-reproducible emulator that estimates the propagation penalty distribution for a ground-to-space or ground-to-ground optical link. It combines a deterministic per-channel penalty model (turbulence, AO residual, pointing jitter, fiber coupling, scintillation, airmass attenuation, background) with a seeded Monte Carlo over input uncertainties.

The headline outputs are: the propagation-penalty distribution $L_{\text{prop,dB}}$ (with percentiles and a fade-probability gauge), the Strehl ratio $S$ distribution, the single-mode-fibre coupling efficiency $\eta_{\text{coup}}$ distribution, the dominant impairment class, and a high-fidelity escalation verdict. All outputs land in a reproducible certificate with a `result_hash` over inputs + constants + formulas + outputs.

## When to use it

Use the surrogate for a fast first cut at link-budget penalties before committing engineering hours to a full phase-screen wave-optics campaign. Good moments:

- **Site comparison.** Sweep zenith, Fried parameter, and aerosol attenuation across candidate ground-station sites before commissioning an on-site $C_n^2(h)$ measurement campaign.
- **AO system sizing.** See how the penalty distribution shifts as you tighten residual WFE or tilt residual — i.e., whether dollars are better spent on more DM actuators or on a better fast-steering mirror.
- **Mission-concept screening.** Rank a basket of link scenarios by fade probability and figure out which deserve a high-fidelity pass and which are comfortably inside the validated envelope.
- **Education and cross-checking.** Teach the dominant-impairment channels by example, or sanity-check another tool's atmospheric / pointing primitives against an independent surrogate.

The surrogate is intentionally not the right tool for: a real flight-software qualification decision; a procurement-binding link-availability number; a substitute for a Kolmogorov phase-screen propagator on a mixed-boundary scenario; or anything where a site-specific $C_n^2(h)$ profile is load-bearing.

## Tab-by-tab walkthrough

The page has a scenario picker and a **Run propagation emulator** button at the top. Pick a public scenario anchor (excellent seeing, poor-seeing turbulence-limited, AO-residual-limited, pointing-limited, mixed boundary), hit **Run**, and every tab populates. **Re-run with new seed** keeps inputs fixed and re-rolls the Monte Carlo.

1. **Summary.** Headline numbers. Fade-probability gauge, p50 / p95 penalty in dB, median Strehl $S_{50}$, median coupling $\eta_{50}$, dominant impairment, and the high-fidelity escalation verdict with a one-line reason.
2. **Scenario Inputs.** Nested form for optical, atmosphere, AO, and receiver blocks. Defaults inherit from the scenario picker. Out-of-domain values get warning chips.
3. **Atmosphere / AO Model.** Regime presets (one-click overwrite of the atmosphere + AO blocks) and a deterministic-quantities table: airmass $X = \sec(\theta_z)$, Fried $r_0$ at the operating wavelength, $D_r / r_0$, atmospheric loss (dB, single-pass), aerosol attenuation, nominal Strehl from residual WFE, nominal coupling, and the total deterministic penalty. A $C_n^2(h)$ hint card appears when an outer-scale profile is supplied; otherwise the single-layer $r_0$ model is in use.
4. **Uncertainty Model.** Per-input distribution picker (fixed, normal, lognormal, uniform, triangular, empirical) and a correlations list. Correlations are recorded in the certificate but not yet sampled by the MVP — independence is assumed.
5. **Penalty Distribution.** Histogram and cumulative distribution of $L_{\text{prop,dB}}$, plus eight percentile / summary cards (p05, p25, p50, p75, p95, mean, std, valid/total). Export-CSV button for the raw penalty samples.
6. **Strehl / Coupling.** Two histograms: the Strehl $S$ and the coupling $\eta_{\text{coup}}$. Two scatter plots: penalty vs. $r_0$ and penalty vs. zenith angle. Both scatters have export-CSV buttons.
7. **Dominant Impairments.** Bar chart of the per-class probability mass, plus a 2-D $r_0$ vs. pointing-jitter heatmap of mean penalty (dB). The dominant-impairment card names the mechanism that was active most often.
8. **Sensitivity.** Tornado chart of $\Delta L$ per fractional change in each input — the largest bars are the most load-bearing inputs. A dominant-uncertainty-contributor card names the input that drives most of the output spread.
9. **High-Fidelity Escalation.** The escalation verdict card (escalate / inside-envelope / refused), a top-N escalation-candidates table, and a recommended high-fidelity model card that names the simulator class to reach for next.
10. **Validation.** Inherits the lab-wide validation page. Surrogate sanity checks render inline; the full lab validation page is one click away. A benchmark-summary card surfaces the benchmark generator status.
11. **Certificate.** Free-text scenario note, build/download/print buttons (JSON, Markdown, PDF, full review packet), the `result_hash` and `receipt_hash`, and the populated certificate body once built.
12. **Research Geometry Mapping.** Optional advanced view. A research-id → public-engineering-name table for readers who want the constraint-compression framing behind the engineering names.

## How to read the penalty distribution

The penalty tab is the workhorse output. The histogram (≈ 50 bins) shows the shape of $L_{\text{prop,dB}}$ over the Monte Carlo draws; the CDF tells you the probability of being below any chosen penalty value.

The eight percentile cards give the standard summary:

- **p05 / p50 / p95** — optimistic / median / pessimistic tails. Most link-availability budgets are written against the p95 or p99 line.
- **mean / std** — a large gap between mean and median is a tell that the penalty distribution is skewed (heavy-tailed turbulence or scintillation).
- **valid / total** — how many draws produced a numerically usable penalty. A non-trivial gap means some draws hit the admissibility envelope.

The **fade probability** $P_{\text{fade}}$ is $\Pr[L_{\text{prop,dB}} > \tau]$ for the displayed threshold $\tau$ (default 6.0 dB; configurable). A low fade probability under one threshold does not mean the link is safe under a stricter threshold — always read the threshold note under the gauge.

## How to read Strehl and coupling

Strehl and coupling are two distinct quantities and the page renders them as separate distributions.

- **Strehl $S$** measures wavefront quality: how peaked the focal-plane PSF is relative to the diffraction limit. The MVP uses the Maréchal approximation, $S \approx \exp(-\sigma_\phi^2)$, which is faithful for small residual WFE (roughly $\sigma_\phi \lesssim \lambda/8$ rms) and degrades as a smooth overestimate for larger WFE — escalate to high-fidelity if you live in the high-WFE regime.
- **Coupling $\eta_{\text{coup}}$** measures what fraction of the captured field couples into a single-mode fibre (or lands on the detector mode). Coupling is gated by Strehl, tip/tilt residual, aperture matching, and tracking jitter. High $S$ with low $\eta_{\text{coup}}$ means the tracking loop is the bottleneck, not the AO loop.

Reading the two side by side diagnoses fast: high $S$, low $\eta_{\text{coup}}$ → pointing-limited; low $S$, low $\eta_{\text{coup}}$ → AO-residual-limited. The penalty-vs-$r_0$ and penalty-vs-zenith scatters underneath confirm which atmospheric axis is driving the spread.

## How to read dominant impairments

The page tracks **10 canonical impairment classes** and emits a probability mass that sums to 1.0 over the Monte Carlo run:

1. **seeing** — large-scale ground-level turbulence in the atmospheric boundary layer.
2. **turbulence** — Kolmogorov free-atmosphere turbulence dominating $D_r / r_0$.
3. **scintillation** — aperture-averaged log-amplitude variance limiting the link.
4. **AO-residual** — uncorrected high-order wavefront error after the AO loop.
5. **pointing** — tip/tilt and tracking-loop residual dominating coupling loss.
6. **coupling** — single-mode-fibre coupling penalty (mode mismatch, aperture matching).
7. **background** — sky/Sun background dominating the SNR.
8. **airmass / attenuation** — molecular + aerosol transmission dominating the link.
9. **mixed-boundary** — no single channel dominates; multiple comparable penalties.
10. **out-of-domain** — at least one input fell outside the declared admissibility envelope.

The dominant-impairment card names the modal class. The bar chart shows the full distribution — if probabilities are spread across three or more classes, that is itself a finding and usually triggers the "mixed boundary" escalation path.

## When to escalate to high-fidelity wave-optics simulation

The Escalation tab applies a **9-rule escalation logic**. The verdict card flags a recommendation when any of the following hold:

1. **Out-of-validated-domain** — at least one input exceeds the admissibility envelope declared in `CLAIM_BOUNDARY.md` and the V&V plan.
2. **Fade probability $P_{\text{fade}} > 0.10$** — link-availability is too marginal for a public surrogate to be load-bearing.
3. **p95 exceeds mission penalty threshold** — the pessimistic tail overruns the user-supplied budget.
4. **Mixed-impairment boundary** — no single impairment class accounts for more than ~ 40 % of the probability mass; per-channel decomposition is unreliable here.
5. **False-safe risk** — adversarial-input sentinel fires and the surrogate refuses to emit a "safe" verdict (conservative-bias rule from the safety layer).
6. **Sparse AO model fields** — required AO-loop fields (residual WFE, tilt residual, control bandwidth) are missing or marked unknown.
7. **Sparse atmosphere fields** — $C_n^2(h)$ profile, outer scale, or zenith-angle range under-specified for the regime in play.
8. **Strehl outside Maréchal validity** — residual WFE is large enough that the Maréchal approximation degrades.
9. **Aperture/range outside surrogate scaling** — geometry falls outside the polynomial response-surface's calibration window.

If any rule fires, run a high-fidelity wave-optics simulation before drawing a flight-relevant conclusion. The certificate records which rule fired and why.

## Recommended high-fidelity models per impairment

Each dominant-impairment class points at a different next-step tool. The recommended-high-fidelity-model card uses this mapping:

| Dominant impairment | Recommended high-fidelity model |
|---|---|
| turbulence | Kolmogorov phase-screen wave-optics propagator (e.g. open-source phase-screen Monte Carlo stack) |
| AO-residual | Full closed-loop AO simulator with realistic deformable-mirror, wavefront-sensor, and control-loop models |
| pointing | Pointing-control / fast-steering-mirror simulator with platform-jitter spectrum |
| coupling | Single-mode-fibre coupling simulator with mode-mismatch and aperture-matching fidelity |
| scintillation | Aperture-averaged scintillation model with Cn²(h) profile and finite-outer-scale corrections |
| airmass / attenuation | Site-specific atmospheric radiative-transfer model (MODTRAN-class) |
| background | Sky-brightness model coupled with detector model (dark count, read noise, quantum efficiency) |
| seeing | Boundary-layer turbulence model with site-specific seeing time-series |
| mixed-boundary | Multi-effect end-to-end wave-optics simulation chain |
| out-of-domain | Refusal — restate scenario inside the declared admissibility envelope before re-running |

This mapping is a pointer, not a vendor list. The surrogate does not certify any particular simulator.

## How to read the validation tab

The validation tab inherits the lab-wide validation page. The surrogate ships **25 Phase I validation cases** across seven classes (exact analytic, regression, anchor, HF benchmark, adversarial, cross-tool, reproducibility). Pass rate at the declared tolerance is 25/25; false-safe verdicts on the analytic + adversarial subset are 0/15. The receipt hash mirrored on the public landing page's validation badge is the canonicalized JSON digest of the report.

The inline sanity checks render whether the deployed surrogate's static numbers still agree with a live re-derivation. If the static-vs-live consistency check fails, the page is showing a stale build and the certificate cannot be trusted — re-run before exporting.

## Reading the certificate

The Certificate tab builds a reproducible artifact. Two hashes matter:

- **`result_hash`** — deterministic digest over inputs + constants registry + formula registry + outputs. Identical seed + identical inputs reproduce this byte-for-byte across Chromium, Firefox, WebKit, and Node.
- **`receipt_hash`** — `result_hash` plus the export timestamp. Used by the lab-wide validation badge.

The certificate also records:

- **`model_mode`** — which surrogate algorithm class produced the numbers (Phase I MVP polynomial response surface vs. Phase II trained surrogate).
- **`surrogate_meta`** — model-card pointer, training-data note, and validation-class status (Phase II trained models only).
- **All 14 `formula_ids`** — references into the formula registry under `shared/`, so a third party can re-derive each output by hand.
- **Full schema** — every input, every output, every constant, every assumption, and the scenario note from the certificate tab.

The Markdown and JSON downloads are byte-for-byte reproducible; the PDF print and the review-packet bundle are signed by the same `result_hash`.

## Common pitfalls

- **Treating a low fade probability as flight-qualified.** A low $P_{\text{fade}}$ is a useful screening signal, not a procurement-binding number. Public engineering surrogate, not mission-certified.
- **Ignoring the "synthetic benchmark, not real wave-optics propagator" warning.** The Phase I HF benchmark is a declared-noise synthetic dataset. Side-by-side comparison against a real Kolmogorov phase-screen propagator is a Phase II milestone.
- **Assuming the surrogate is calibrated against your specific site.** Public scenario anchors come from open-literature regimes (Hardy, Andrews & Phillips, Born & Wolf, DESCANSO, Kasten-Young). Your site's $C_n^2(h)$, seasonal aerosol, and AO calibration are not in the surrogate. Real-site numbers require a real-site campaign.
- **Under-specifying AO model fields.** Leaving residual WFE, tilt residual, or AO bandwidth unset drops the result into the "sparse AO fields" escalation path. The certificate still builds, but the verdict will favour escalation.
- **Reading the dominant impairment without the bar chart.** If two or three classes are within a few percentage points of each other, the "dominant" label is not the whole story — the link is mixed-boundary and the escalation tab will say so.

## What this tool is and is not

> Public engineering-surrogate propagation emulator. Estimates atmosphere/AO/coupling penalties under declared assumptions and validation limits. Not mission-certified, does not reproduce internal NASA/JPL pipelines, does not replace high-fidelity wave-optics simulation.

## See also

- [Sample NASA Spec](SAMPLE_NASA_SPEC.md) — the original NASA-style requirements package the lab built this tool from.
- [Surrogate model card](SURROGATE_MODEL_CARD.md)
- [Benchmark dataset manifest](BENCHMARK_DATASET_MANIFEST.md)
- [False-safe report](FALSE_SAFE_REPORT.md)
- [Demo scenarios](DEMO_SCENARIOS.md)
- Other advanced calculators: [Dominance Map](../design-space-dominance-map/USER_GUIDE.md), [Reliability Emulator](../optical-link-reliability-emulator/USER_GUIDE.md)