# Product Specification: Wave-Optics / Atmosphere / Adaptive-Optics Surrogate
## NASA/JPL-Style $300k Build Package for a Reduced-Order Optical Propagation Emulator

> **Source document.** This is the original NASA/JPL-style specification package the lab used to build the **Wave-Optics / Atmosphere / AO Surrogate** at `/gut/nasa/wave-optics-atmosphere-ao-surrogate/`. It is reproduced here verbatim so a reviewer can see the requirements the implementation was traced to. The tool itself is a public engineering-surrogate, not mission-certified software.

**Version:** 1.0
**Target buyer / evaluator:** NASA/JPL-style optical communications, optical ground systems, adaptive optics, mission design, atmospheric propagation, mission assurance
**Target deployment:** `https://physics.magflowmeters.com/gut/nasa/wave-optics-atmosphere-ao-surrogate/`
**Product class:** Public engineering-surrogate / reduced-order wave-optics reliability and penalty emulator
**Target funding level:** ~$300k feasibility + validated prototype package
**Core value proposition:** Estimate atmosphere / turbulence / adaptive-optics / coupling penalties quickly enough to triage optical-link designs before expensive high-fidelity wave-optics Monte Carlo is run.

---

## 0. Executive Summary

A full high-fidelity wave-optics simulation campaign can require many phase-screen realizations, propagation steps, seeing conditions, telescope parameters, pointing states, AO residuals, background cases, and detector/coupling assumptions.

The surrogate does **not** replace high-fidelity wave-optics simulation. It answers a narrower and fundable question:

> Given declared assumptions, what atmosphere/AO/coupling penalty should we expect, what uncertainty range applies, and does this scenario require high-fidelity simulation?

A $300k NASA-style build should deliver a validated prototype with deterministic atmosphere/AO penalty estimates, Monte Carlo uncertainty propagation, a trained reduced-order surrogate calibrated on synthetic high-fidelity benchmark data, validity-domain warnings, false-safe metrics, high-fidelity escalation rules, reproducible certificates and review packets, NASA-style requirements traceability and validation reports.

> The strongest funding claim: This tool reduces high-fidelity simulation waste by identifying safe, impossible, and boundary cases before full wave-optics runs.

---

## 1. Claim Boundary

### 1.1 What this tool may claim

The Wave-Optics / Atmosphere / AO Surrogate estimates atmospheric, turbulence, adaptive-optics, pointing, and coupling penalties for optical-link scenarios inside a declared validated domain.

### 1.2 What this tool must not claim

- to be NASA/JPL software;
- to reproduce internal DSOC or mission link budgets;
- to replace mission-certified wave-optics propagation simulations;
- to replace adaptive-optics design tools;
- to replace atmospheric measurement campaigns;
- to provide flight-qualified optical-link closure;
- to model proprietary ground-station, detector, coding, or AO control systems unless supplied;
- to validate new physics.

---

## 6. Raw Input Model

### 6.1 Optical / link inputs

$$x_{\rm optical} = (\lambda, D_t, D_r, R, P_t, R_b, \theta_{\rm zenith}, \theta_{\rm sun}, \sigma_{\rm pointing}, v_\perp)$$

### 6.2 Atmospheric inputs

$$x_{\rm atm} = (r_0, L_0, l_0, C_n^2(h), \tau_0, \theta_0, T_{\rm atm}, A_{\rm aerosol}, w_{\rm wind}, \text{cloud flag})$$

### 6.3 AO / receiver inputs

$$x_{\rm AO} = (N_{\rm act}, f_{\rm loop}, \sigma_{\rm WFE}, S_{\rm AO}, D_r/r_0, \eta_{\rm coupling,0}, B_{\rm sky}, \eta_{\rm det})$$

### 6.4 Uncertainty model

Each input supports fixed, normal, lognormal, uniform, triangular, empirical CDF, site-weather percentile, user-uploaded samples.

---

## 8. Physics / Engineering Model

### 8.1 Core outputs

| Output | Meaning |
|---|---|
| Strehl ratio $S$ | wavefront-quality / peak-intensity proxy |
| Coupling efficiency $\eta_{\rm coup}$ | fraction coupled into detector/fiber |
| Turbulence penalty $L_{\rm turb,dB}$ | dB penalty from turbulence |
| AO residual penalty $L_{\rm AO,dB}$ | dB penalty after AO correction |
| Pointing/coupling penalty $L_{\rm point,dB}$ | dB penalty from jitter/beam wander |
| Scintillation penalty $L_{\rm scint,dB}$ | intensity-fading penalty |
| Total propagation penalty $L_{\rm prop,dB}$ | aggregate penalty |
| Fade probability | probability penalty exceeds threshold |
| Validity status | valid / warning / out of domain |

### 8.2 Baseline analytic approximations

- Fried parameter scaling: $r_0(\lambda) = r_0(\lambda_0) (\lambda/\lambda_0)^{6/5}$
- Seeing angle: $\theta_{\rm seeing} \approx 0.98 \lambda / r_0$
- Diffraction angle: $\theta_{\rm diff} \approx 1.22 \lambda / D_r$
- Maréchal Strehl: $S \approx \exp[-(2\pi\sigma_{\rm WFE}/\lambda)^2]$
- Pointing loss: $L_{\rm point} \approx \exp(-\sigma_{\rm pointing}^2 / (2 \sigma_{\rm mode}^2))$
- Total propagation efficiency: $\eta_{\rm prop} = T_{\rm atm} \cdot S \cdot \eta_{\rm coup} \cdot L_{\rm point} \cdot L_{\rm scint}$
- Propagation penalty: $L_{\rm prop,dB} = -10 \log_{10}(\eta_{\rm prop})$

---

## 9. Functional Requirements (Summary)

| ID | Requirement |
|---|---|
| FR-1 | Scenario setup |
| FR-2 | Atmosphere/AO input model |
| FR-3 | Deterministic penalty estimate |
| FR-4 | Monte Carlo propagation penalty |
| FR-5 | Trained surrogate mode (polynomial / GP / RF / GB / explainable-neural) |
| FR-6 | Dominant impairment classification (10 classes) |
| FR-7 | High-fidelity escalation |
| FR-8 | Visualization (10 required plots) |
| FR-9 | Certificate + review packet export |

---

## 11. Validation and Verification Plan

### 11.3 Synthetic high-fidelity benchmark (4 tiers)

- Tier 1 — Analytic synthetic cases (known scaling laws)
- Tier 2 — Phase-screen surrogate benchmark
- Tier 3 — Coupling benchmark (WFE + pointing + turbulence)
- Tier 4 — Out-of-domain adversarial cases

### 11.4 Benchmark metrics ($300k prototype targets)

| Metric | Target |
|---|---:|
| Strehl relative error | ≤ 15–20% |
| Coupling penalty error | ≤ 1.5–2.0 dB |
| Total propagation penalty median error | ≤ 2.0 dB |
| 95th-percentile penalty error | ≤ 2.5–3.0 dB |
| Dominant impairment accuracy | ≥ 80% |
| False-safe rate | ≤ 5% |
| High-fidelity escalation recall | ≥ 90% |
| Surrogate speedup | ≥ 1,000× evaluation speed vs benchmark generator |

### 11.5 False-safe definition

False-safe means: surrogate says "acceptable / no high-fidelity needed", but benchmark says "penalty exceeds threshold or scenario is boundary/out-of-domain". This is the most important safety metric.

---

## 14. $300k Delivery Plan

### Timeline (6 months)

| Month | Deliverables |
|---:|---|
| 1 | Claim-safe skeleton, scenario schema, deterministic penalty formulas |
| 2 | Uncertainty model, Monte Carlo engine, plots |
| 3 | Synthetic benchmark generator, validation suite |
| 4 | Trained surrogate mode, domain warnings, impairment classifier |
| 5 | Certificates, review packets, requirements traceability, demo scenarios |
| 6 | Benchmark report, false-safe report, funding package, public deployment |

### Budget allocation

| Workstream | Budget |
|---|---:|
| Product / systems requirements | $35k |
| Deterministic + Monte Carlo model | $55k |
| Synthetic benchmark generator | $55k |
| Surrogate model + validation domain | $60k |
| UI / visualization / export | $35k |
| Certificates / traceability / V&V | $35k |
| Deployment / docs / review package | $25k |
| **Total** | **$300k** |

---

## 15. Demo Scenarios

1. **Excellent seeing / high margin** — high Strehl, low penalty, no escalation
2. **Poor seeing / turbulence-limited** — high p95, escalation likely
3. **AO-residual-limited** — Strehl penalty dominates
4. **Pointing-limited** — coupling penalty dominates
5. **Mixed boundary** — multiple impairments close, escalation required

---

## 18. Final Editorial Rule

The tool should say:

> "We estimate atmosphere/AO/coupling penalties quickly and tell engineers when full wave-optics simulation is required."

The $300k funding case succeeds only if the prototype demonstrates:

> speed + bounded error + low false-safe rate + clear validity domain + reproducible audit packet.

---

*Original spec preserved verbatim. See `USER_GUIDE.md` in this directory for a walk-through of how to use the deployed tool, and the supporting engineering docs (`BENCHMARK_DATASET_MANIFEST.md`, `SURROGATE_MODEL_CARD.md`, `FALSE_SAFE_REPORT.md`, `RISK_REGISTER.md`) for the rest of the package.*