# Optical Link Reliability Emulator — User Guide

## What this tool does

The Optical Link Reliability Emulator estimates the probability that a deep-space optical link closes under declared input uncertainty, identifies the dominant failure mode across Monte Carlo samples, and recommends when a problem is hard enough that a high-fidelity simulator is the right next step. It is a public, browser-based engineering surrogate built around publicly documented anchor scenarios (e.g. the NASA Psyche DSOC December 14 2023 first-light press-release figures), with every formula, constant, source, and validation case exposed in JSON registries so a third party can re-derive the numbers by hand.

## When to use it

Use the emulator **after** you have built a nominal deterministic link budget and you want to ask the next question: not "what is my single-margin number?" but "across the range of input values I can justify, what fraction of cases close?" If your range, transmit aperture, atmospheric transmission, pointing jitter, detector efficiency, or coding gain has any meaningful uncertainty — and in early-design optical comms they always do — a single nominal margin badly under-represents reality. The emulator turns those input distributions into a closure probability $P_\text{close}$ and a full margin distribution.

Use it **before** committing compute to high-fidelity Monte Carlo or full wave-optics propagation. A 4000-sample browser-side run takes a minute or two; a turbulent wave-optics campaign over the same input space takes hours or days. The surrogate is designed to filter: when its escalation logic flags your scenario as boundary, fragile, false-safe, or out-of-domain, that is the signal to escalate. When it returns a clean high or clean low $P_\text{close}$ with no escalation flags, you have a defensible engineering screen.

It is **not** the right tool when you need a flight-certified deliverable, when you need to reproduce internal NASA or JPL mission pipelines, or when the physics has moved far enough out of the declared admissibility envelope that the surrogate refuses to emit a verdict. In those cases the tool itself will tell you to escalate.

## Tab-by-tab walkthrough

The page exposes eleven tabs. The top bar carries a **Scenario** picker, a **Run reliability emulator** button, and a **Re-run with new seed** button. The default run uses seed = 42 and N = 4000 Monte Carlo samples.

**1. Summary.** Headline numbers under the selected scenario anchor: $P_\text{close}$ gauge, table of $P_\text{close}$ / $P_\text{outage}$ / median margin $M_{50}$ / 5th-percentile $M_{05}$, dominant failure-mode label, escalation verdict with reasons. Read this tab first; the rest of the tabs unpack each row. *Pitfall:* if every row reads "—", press **Run** in the top bar.

**2. Scenario Inputs.** Sixteen-field form covering transmit power, transmit aperture, receive aperture, wavelength, range, pointing-loss budget, atmospheric transmission, detector efficiency, coding gain, photons-per-bit requirement, implementation loss, and more. Defaults come from the selected scenario anchor. Changing a value here shifts the mean of that input; changing its distribution on tab 3 changes how uncertain you are about it. Both matter.

**3. Uncertainty Model.** Per-input distribution picker: **fixed**, **normal**, **lognormal**, **uniform**, **triangular**, **empirical**. This is where you encode "I know the wavelength exactly, but I only know atmospheric transmission to within ±0.05 with a triangular distribution centred on 0.70." A **Correlations** card records correlations into the certificate but the MVP draws **independent** samples — a known surrogate limitation that the escalation logic accounts for. *Pitfall:* leaving every input as **fixed** and then asking why $P_\text{close}$ is either 0 or 1. With no uncertainty, the emulator collapses to deterministic arithmetic.

**4. Margin Distribution.** Histogram (about 50 bins, first 1000 samples) and CDF of margin in dB, plus a sample-statistics table (mean, std, $p_{05}/p_{25}/p_{50}/p_{75}/p_{95}$, and "valid samples / total"). Invalid samples were refused by the fail-closed admissibility boundary. Tight-and-unimodal-above-zero is the easy case; wide-and-straddling-zero is the dangerous case — read the next tab.

**5. Closure Probability.** $P_\text{close}$ gauge plus two parametric sweeps: closure probability vs range and vs transmit aperture (20 grid points each, other inputs held at scenario values). A **convergence** card reports batch-to-batch $P_\text{close}$ standard deviation — the diagnostic for "did I run enough samples?" Two CSV-export buttons pull the sweeps out for downstream plotting. The sweeps reveal whether you sit on a flat region of the design space or on a knee where small perturbations swing $P_\text{close}$ from 0.95 to 0.20.

**6. Failure Modes.** Bar chart of failure-mode probability across valid Monte Carlo samples — pointing-dominated, atmosphere-dominated, photon-budget-dominated, implementation-loss-dominated, coding-margin-dominated, and so on. Bars sum to 1. The **dominant failure mode** card labels the highest bar. *Mixed-boundary regime:* when the top two limiters are within 0.5 dB, the classification is fragile, the bars look flat, and the `mixed_boundary` escalation rule fires. Treat the label as a tie between two mechanisms in that regime, not as categorical.

**7. Sensitivity.** Tornado chart of linear sensitivity ($\Delta$ margin per fractional input change). Bars sorted by magnitude; longest bars are the most-load-bearing inputs. A **dominant uncertainty contributor** card calls out the single largest. Use it to focus measurement campaigns: if atmospheric transmission tops the tornado, that is where to spend ground-station calibration time.

**8. High-Fidelity Escalation.** ESCALATE / NO ESCALATION NEEDED verdict, firing reasons, false-safe risk surrogate, top-N escalation candidates across your saved scenarios, and a recommended high-fidelity model card (wave-optics propagator, full APD/SPAD detector model, mixed-boundary coupled model, internal mission pipeline). See the dedicated section below on the seven rules.

**9. Validation.** Sanity tests for the reliability emulator (deterministic vs Monte-Carlo median margin agreement, $P_\text{close} \in [0,1]$ check, convergence check). A link drops you into the lab-wide Validation page for the full report and registry-level cross-checks. Start here if a number looks wrong.

**10. Certificate.** Type an optional scenario note, press **Build certificate**, download as JSON, Markdown, or PDF, or download the full review packet (certificate + sweep CSVs + validation receipt). See the **Reading the certificate** section below.

**11. Research geometry mapping.** Optional advanced view mapping the public engineering names (reliability constraint manifold, reliability-regime chamber, threshold layer, safety layer) back to the research-paper identifiers ($K_6$, $F^+$, $L_\text{threshold}$, $L_\text{safety}$, $x, \oplus, \otimes$). Ignorable for most users; useful for readers coming from the manuscript.

## How to read the margin distribution

Three views of the same Monte Carlo output:

- **Histogram (about 50 bins, first 1000 samples)** — shape and modality of the margin distribution in dB. Unimodal-and-narrow is easy; bimodal or long-tailed is a warning.
- **CDF** — cumulative fraction of samples at or below a given margin. Read $P_\text{close}$ off the CDF as 1 minus CDF(0 dB).
- **Percentile cards (p05/p50/p95)** — robust summary statistics. $p_{50}$ is the median (half the samples lie above), $p_{05}$ is the conservative low tail (only 5% lie below), $p_{95}$ is the optimistic high tail.

Physically, the "margin distribution" is the distribution of received signal power minus the threshold required for the chosen bit-error rate at the chosen coding gain, in dB. A positive draw closes the link; a negative draw does not. Width encodes how much your inputs jitter the link; location encodes how comfortable the nominal design is.

## How to read closure probability

$P_\text{close}$ is the fraction of valid Monte Carlo samples with positive dB margin.

- $P_\text{close} \approx 0.99$ — under the declared input distributions, the link closes in essentially all draws. Caveat: surrogate estimate, not a flight-grade reliability number.
- $P_\text{close} \approx 0.50$ — coin-flip regime. The design sits on the closure boundary; small input shifts swing the outcome. Automatically fires the `boundary_p_close` escalation rule.
- $P_\text{close} \approx 0.01$ — almost no sampled scenario closes. Revisit transmit power, aperture, coding gain, or range.

**Seed reproducibility.** Identical scenario + identical seed + identical uncertainty model + identical constants registry + identical formula registry → bit-identical samples → bit-identical $P_\text{close}$, percentile margins, failure-mode bars, tornado, and result_hash. Default seed is 42. Press **Re-run with new seed** to roll a fresh seed (recorded in the certificate). Two people running the same scenario JSON with the same seed get the same result_hash — that is the cross-check.

## How to read failure-mode probabilities

The bar chart shows the fraction of valid samples in which each limiter on the reliability constraint manifold was active. Bars sum to 1.0 over valid samples; out-of-envelope samples do not contribute. The **dominant failure mode** card labels the highest bar and is the right starting point for "if this link fails, where will it fail first?"

**Mixed-boundary regime.** When the top two limiters are within 0.5 dB across the sample population, the dominant-mode label is fragile — small input shifts re-rank the bars. The bars look flatter and the `mixed_boundary` escalation rule fires. Treat the label as a tie between two physical mechanisms; both need higher-fidelity modelling before you commit to a design.

## How to read sensitivity / tornado

The tornado plots $\partial M / \partial(\text{input fractional change})$ in dB per unit fractional change, sorted by absolute magnitude. How to use it:

1. **Focus measurement campaigns.** The longest bar identifies the input where reducing uncertainty buys the most margin tightening.
2. **Cross-check intuition.** If a parameter you expected to matter is short and an unexpected one is long, that is information — your nominal design may be unintentionally limited by something other than what you thought.
3. **Pair with the failure-mode bars.** If pointing dominates the failure-mode bars but pointing-jitter is mid-pack on the tornado, the mechanism fires because the nominal value is too tight, not because the input is uncertain — the cure is to relax the spec, not to measure more carefully.

## When to escalate to high-fidelity simulation

The escalation logic is intentionally conservative: it would rather flag too many scenarios than too few, on the principle that the cheap surrogate must never silently pass a problem that needed full-physics modelling. Seven rules fire independently; any single one is sufficient to escalate.

1. **boundary_p_close** — $P_\text{close} \in [0.1, 0.9]$. Neither clearly safe nor clearly outage; the surrogate is least trustworthy in this band.
2. **boundary_margin** — $|M_{50}| < 1.5$ dB. The median sample sits within 1.5 dB of the closure threshold; small input shifts cross zero.
3. **uncertainty crossing zero** — the input uncertainty range straddles the threshold ($p_{05}$ negative and $p_{95}$ positive). The link's "does it close" answer changes inside your declared uncertainty.
4. **mixed_boundary** — top two failure-mode limiters within 0.5 dB. The dominant-mode classification is fragile; a coupled model is needed.
5. **false_safe_risk > 5%** — surrogate false-safe risk exceeds 0.05: more than a 5% probability that the surrogate would label "safe" a scenario that full physics would label "fails." The most cautious of the rules.
6. **sparse_assumptions** — fewer than 3 source IDs cited. The estimate is dominated by user-supplied assumptions rather than literature anchors; escalating buys provenance.
7. **mission_critical_flag** — user flagged the scenario as mission-critical. By policy, the surrogate is no longer the authority once that flag is set, regardless of how clean its numbers look.

The Escalation tab shows the fired rules and the recommended high-fidelity model.

## How to use a seeded RNG

The Monte Carlo engine uses a deterministic seedable PRNG. Default seed is 42. With a fixed seed: same scenario + same uncertainty model + same seed + same registries → **bit-identical** samples → bit-identical outputs and result_hash. This is what makes the certificate reproducible across browsers and across reviewers.

Press **Re-run with new seed** to draw a fresh seed (derived from the current timestamp); the new seed is written into the certificate. Right workflow when you want to confirm a number does not depend pathologically on a particular seed: run with seed = 42, then with a fresh seed, and confirm $P_\text{close}$ moves by less than the convergence-card's batch-to-batch standard deviation. If it moves by more, increase $N$.

## Reading the certificate

The certificate is the reproducibility receipt. Build it on the Certificate tab; download as JSON, Markdown, PDF, or the full review packet (certificate + sweep CSVs + validation receipt). Key fields:

- **result_hash** — deterministic hash over inputs + constants + formula_ids + outputs. Two reviewers compare this to confirm they reproduced each other's numbers.
- **receipt_hash** — result_hash plus the export timestamp; lets you tell two otherwise-identical certificates apart.
- **model_mode** — `monte_carlo` for the default workflow (a `deterministic` fallback exists when the Monte Carlo module is unavailable).
- **formula_ids** — the full set of formula identifiers the reliability path used, drawn from the lab-wide formula registry. Lets reviewers audit which equations contributed.
- **source_ids** — deduplicated source identifiers from scenario + public-literature anchors. Fewer than 3 fires the `sparse_assumptions` escalation rule.
- **validity** — `valid` if scenario validity is clean and the Monte Carlo converged; downgraded to `warning` (or worse) if either is in question.
- **outputs** — $P_\text{close}$, $P_\text{outage}$, $M_{50}$, $M_{05}$, sample_count, valid_count, seed, convergence status.
- **assumptions** — the optional scenario note plus the recorded uncertainty model and correlation list.
- **claim_boundary** — verbatim public engineering surrogate language (below).

Markdown is the right artefact to attach to a design review; JSON is the right artefact to commit to a project repo for diff-able provenance.

## Common pitfalls

1. **Treating $P_\text{close}$ as a flight-grade reliability number.** It is not. $P_\text{close}$ is a surrogate estimate under the declared input distributions and the public scenario anchor. Real mission reliability requires hardware qualification, full-physics pipelines, redundancy analysis, and operational margin policy — none of which this tool provides. Use $P_\text{close}$ to compare designs and to focus high-fidelity work, not as a flight-clearance number.
2. **Ignoring out-of-domain warnings.** When you push inputs beyond the declared admissibility envelope the tool refuses to emit a "safe" verdict and instead returns a labelled refusal or a high-fidelity-escalation flag. That is the fail-closed behaviour doing its job — do not paper over it.
3. **Running too few samples.** N = 4000 is fine for headline numbers in the easy regime but marginal near the escalation boundary. If the convergence card reports a batch-to-batch $P_\text{close}$ standard deviation comparable to your decision threshold, you need more samples.
4. **Assuming independence when correlations matter.** The MVP records correlations but draws independent samples. If atmospheric transmission and pointing variance both worsen in bad seeing, the independent-sample $P_\text{close}$ will be slightly optimistic relative to the truly-correlated answer. Treat as an additional reason to escalate.
5. **Reading the dominant failure mode in the mixed-boundary regime.** When the top two limiters are within 0.5 dB, the label is fragile. Always check whether the `mixed_boundary` escalation rule fired before quoting a single dominant mode in a review.

## What this tool is and is not

Verbatim claim boundary from `CLAIM_BOUNDARY.md`:

> Public engineering-surrogate reliability emulator. Estimates closure probability under declared assumptions. Not mission-certified, does not reproduce internal NASA/JPL pipelines.

That sentence is the authoritative positioning. Every certificate, every validation receipt, every public landing page carries it. It is also the answer to the most common question reviewers ask about this tool: "what is this for, and what is it not for?"

## See also

- [Sample NASA Spec](SAMPLE_NASA_SPEC.md) — the original NASA-style requirements package the lab built this tool from.
- [Requirements traceability matrix](NASA_STYLE_REQUIREMENTS_TRACEABILITY_MATRIX.md) — requirement-to-implementation mapping.
- [Demo scenarios](DEMO_SCENARIOS.md) — worked example scenarios, including the DSOC public scenario anchor.
- [Reproducibility README](REPRODUCIBILITY_README.md) — how to reproduce the published numbers locally and how the result_hash chain works.
- Other advanced calculators: [Dominance Map](../design-space-dominance-map/USER_GUIDE.md), [Wave/AO Surrogate](../wave-optics-atmosphere-ao-surrogate/USER_GUIDE.md)