# Design-Space Dominance Map — User Guide

> Public engineering-surrogate decision-support tool. Not mission-certified.
> Does not reproduce internal NASA/JPL pipelines.

## What this tool does

The Design-Space Dominance Map estimates **which optical-link constraint is
binding** across a high-dimensional engineering design space and flags the
scenarios most worth following up with a high-fidelity simulation. It
compresses the search across range, wavelength, apertures, power, rate,
pointing, atmosphere, detector, background, and coding into ten dimensionless
burden ratios, ten named limiter classes, and a single dB closure margin
G(z), all computed in the browser from public formulas and public constants.

## When to use it

Use this tool **before** committing to expensive full-wave-optics or
atmospheric-channel Monte Carlo. The point is to triage: identify the
active constraint, the dominant failure mode, and the regions of design
space within a dB or two of the closure boundary so high-fidelity compute
goes where it changes the answer.

It is the right tool when a design has many free parameters and you need
to know which one is gating. Scanning aperture, power, and pointing for an
Earth-Mars optical link, the dominance map tells you whether you are
diffraction-limited, pointing-limited, or sitting on the boundary — much
cheaper than running a full physical-optics propagation on every grid
point.

It is also the right tool when preparing an SBIR/STTR/Phase I review and
you need to defend "where is the high-fidelity compute budget going?" with
a reproducible artifact. The Dominance Map + Closure Probability +
High-Fidelity Recommendations tabs produce a ranked, hashed, exportable
scenario list a reviewer can verify by re-running the same seed. It is
**not** a replacement for high-fidelity follow-up — it is the screening
layer that decides which runs to fund.

## Tab-by-tab walkthrough

The page has nine tabs plus a scenario picker bar at the top with four
chips ("DSOC public", "Earth-Mars optical", "GEO-LEO downlink", "Custom").
Selecting a chip loads its defaults into the Design Space form; "Custom"
keeps whatever you have entered.

### Tab — Design Space

A 16-field SI-engineering input form: range R (m), wavelength lambda (m),
Tx and Rx apertures D_t / D_r (m), Tx power P_t (W), data rate R_b
(bits/s), pointing jitter sigma_p (rad), atmospheric transmission T_atm,
detector efficiency eta_det, background rate B_sky (counts/s), coding
gain G_c (dB), transverse velocity v_perp (m/s), required photons/bit,
implementation loss L_impl (dB), potential difference dU, carrier
frequency f_0 (auto-derived). Each sweepable field has a `sweep this
input` checkbox that reveals a `min` / `max` row used by the Dominance
Map. **Evaluate point** runs the projection x -> z, the ten limiter
margins, the closure margin, the dominant-limiter classification, and
the regime chamber; the status pill shows G in dB, the dominant
limiter, the regime, and a **VALID** / **CHECK** marker. Pitfalls:
range is in **metres** (1 AU ~ 1.5e11 m); pointing jitter is in
**radians** (1 microrad = 1e-6 rad); T_atm is a fraction in [0, 1],
not dB.

### Tab — Reduced Invariants

Shows the ten dimensionless burden ratios rho_R, rho_diff, rho_point,
rho_atm, rho_det, rho_bg, rho_code, rho_phase, rho_rel, rho_safety. Each
rho_* is a ratio to its engineering threshold — rho ~ 1 sits on the
boundary, rho << 1 is comfortable margin, rho >> 1 has crossed threshold.
Each invariant is tagged with its engineering-facing layer ("optical
field layer", "detector/noise layer", "threshold layer", "safety layer",
"spacetime geometry", "angular geometry", "phase/clock geometry"). The
**Layer contributions** cards group invariants by layer; the **radar
chart** plots z on ten log-clipped axes. A spiky radar means a
bottlenecked design; a circular radar means burden is spread. Read the
table for numbers, the radar for shape.

### Tab — Dominance Map

The headline visualisation. Pick two sweep axes (X / Y dropdowns); set
`min`, `max`, N_x, N_y (defaults 14 x 14, capped at 40 x 40). Other
inputs hold at their Design-Space-tab values. **Run sweep** renders two
heatmaps side by side: the **dominance heatmap** (each cell coloured by
the dominant limiter; legend maps colour to label) and the
**closure-margin heatmap** (continuous G(z) in dB on a divergent scale).
`Export CSV` dumps the full grid; `Export SVG` dumps the dominance
heatmap. Pitfall: each cell is a single deterministic evaluation — for
input uncertainty, switch to Closure Probability.

### Tab — Closure Probability

Seeded Monte Carlo over the Design-Space inputs with user-set per-input
fractional sigmas. Default seed `0xC0FFEE42 = 3232552386`, default N =
5000; sigma = 0 holds an input fixed. Output: **P_close** (fraction of
samples with G(z) >= 0), **sigma_G_dB**, the **percentile band** (P5 /
P50 / P95), and the **dominant-limiter share**. Same seed -> same
result.

### Tab — Boundary Cases

Grid points from the most recent sweep within 1 dB of G = 0 or in a
mixed-limiter window. These are the cells most worth a high-fidelity
follow-up — the surrogate is not confident enough to call them. Each
row shows sweep coordinates, dominant limiter (and any tied alternates),
G in dB, and a reason string (`near_closure_boundary`, `mixed_limiter`,
or both).

### Tab — High-Fidelity Recommendations

**Build recommendations** ranks the recent sweep into a
high-fidelity-runs table; each row carries a priority score in [0, 1]
and one or more escalation reasons (see below), plus a recommended
model class (wave-optics + AO, PPM coding Monte Carlo, pointing
dynamics, detector noise model, etc.). `Export CSV` dumps the ranked
list with reasons, priority scores, and the design vector verbatim.

### Tab — Validation

Local analytic sanity-check results for the projection, the limiter
margins, the closure-margin computation, and the regime classifier —
all run in-browser from public formulas and public constants. **Open
lab-wide Validation page** opens the full lab dashboard.

### Tab — Certificate

Builds a reproducible certificate. The optional `Scenario note` field
is sanitised against the public claim boundary before embedding.
**Build certificate** computes the hashes; export buttons download
JSON, Markdown, or print PDF. See "Reading the certificate" below.

### Tab — Research Geometry Mapping

Opt-in advanced view. The public UI uses engineering names everywhere;
this drawer shows the manuscript's research-id mapping (K_6 for the
constraint manifold, F^+ for the regime chamber, S_2 / S_1Y for the
geometry layers, E_threshold / E_safety for the operator layers).
Informational only — nothing here changes the result.

## How to interpret the dominance map

Each cell is one of: **a single limiter colour** (the limiter with the
smallest weighted margin g_i at that point), **mixed** / hatched (two or
more limiters within 0.5 dB — the surrogate declines to pick because a
small input change would flip which one binds), or **out_of_domain** (the
approximation-domain check rejected the cell because one or more inputs
sit outside the validated regime — diffraction, paraxial, weak-turbulence
— so the surrogate refuses to extrapolate). The closure-margin heatmap is
divergent: green above 1.5 dB ("comfortable closure"), yellow 0 to 1.5 dB
(closes with thin margin, escalation recommended), red below 0 ("does not
close"). Dominance tells you the cause; closure margin tells you the
severity.

## How to interpret closure probability

P_close is the surrogate's estimate of P(G >= 0) under the declared
per-input sigmas, computed by N seeded Monte Carlo draws (standard error
scales as 1/sqrt(N)).

- **P_close >= 0.95** with a P5 margin above ~1 dB: estimates
  comfortable closure under the declared uncertainty.
- **P_close near 0.5** ("boundary"): closure roughly half the time.
  The most informative regime for triage — these are the scenarios
  where a high-fidelity simulation will most likely change your
  decision.
- **P_close <= 0.05**: essentially never closes. Still worth confirming
  on one or two representative cases.

The **percentile band** (P5 / P50 / P95) gives the shape of the G
distribution — a symmetric band around a high median is comfortable; a
skewed band with a long lower tail signals tail risk. The
**dominant-limiter share** tells you which limiter was binding in each
draw: 80% pointing-limited is robustly pointing-dominated; a 40/40/20
split sits on a three-way mixed boundary.

## How to read the high-fidelity recommendations

Each row carries a priority score in [0, 1] and one or more reasons
from the seven escalation rules:

1. `near_closure_boundary` — |G| < 1 dB
2. `mixed_limiter` — top two limiters within 0.5 dB
3. `high_uncertainty` — closure-margin std-dev > 1.5 dB
4. `outside_domain` — approximation-domain check emitted a warning
5. `public_scenario_mismatch` — predicted rate disagrees with a public
   scenario anchor by more than 3x
6. `nonneg_false_safe_risk` — surrogate false-safe risk > 5%
7. `mission_critical_flag` — user-flagged scenario

The priority score is `max(severity_i)` over fired rules, scaled by how
far past threshold each violation sits. Reading guide: **priority >=
0.7** — take seriously, almost always worth a high-fidelity run; **0.3
to 0.7** — useful but not urgent; **< 0.3** — nothing specific to
escalate, but not "guaranteed safe" either. The rules are conservative
by design: the surrogate is built to **never silently call a scenario
closed when a high-fidelity model would disagree**.

## Reading the certificate

- **`result_hash`** — SHA-256 over the canonical-ordered (inputs +
  version + constants + formulas + result vector). **Deterministic**:
  same inputs + same lab version + same constants + same formulas ->
  same `result_hash`.
- **`receipt_hash`** — SHA-256 over (`result_hash` + export
  timestamp). **Unique per export event**.

Other fields: `tool_version`; `scenario_id` and `scenario_anchor`
(active chip and source label, `nasa_dsoc_public` or `user_assumption`);
`inputs.x`; `result.z`, `result.margins`, `result.closure`,
`result.regime`; `geometry_method.active_branch` (research ids, for
traceability) and `geometry_method.public_mapping` (engineering-facing
names); `escalation` (fired rules + priority + recommended model
class); `constants_hash`, `formulas_hash`.

**To verify reproducibility.** Load the same lab build, select the same
scenario chip, enter the `inputs.x` values, **Evaluate point**, then
**Build certificate**, and confirm `result_hash` matches. If not, diff
`inputs.x`, compare `constants_hash` / `formulas_hash`, or check the
`tool_version`.

## Common pitfalls

1. **Unit confusion: m vs km vs AU.** Range is in metres. 1 AU is
   1.496e11 m; the Moon is ~3.84e8 m. Entering "0.1" gives a 10 cm
   link, not 0.1 AU.
2. **Pointing jitter in arcseconds.** Pointing jitter is in radians
   (1 microrad = 1e-6 rad, 1 arcsec ~ 4.85e-6 rad). Entering "1.0"
   gives a one-radian jitter.
3. **Treating P_close = 0.95 as "guaranteed".** P_close is a Monte
   Carlo estimate **conditional on the declared per-input sigmas**.
   If those sigmas are uncertain, the P_close estimate inherits that
   uncertainty — it is a triage signal, not a closure guarantee.
4. **Forgetting the surrogate is reduced-order.** The constraint
   surfaces are dB margin approximations on reduced invariants, not
   full physical-optics propagations. Best for ranking and boundary
   detection; for the closure decision on a funded link, run a
   high-fidelity simulation on the recommended list.
5. **Extrapolating outside the declared regime.** `out_of_domain`
   cells are the surrogate refusing to extrapolate — go to the
   high-fidelity tool, do not just widen the input range.

## What this tool is and is not

**Public engineering-surrogate decision-support tool. Not mission-certified.
Does not reproduce internal NASA/JPL pipelines.**

The dominance map is built from public formulas, public constants, and
public scenario anchors. It estimates which constraint dominates and
which scenarios deserve high-fidelity follow-up; it does not certify a
link budget, does not replace SPICE / Horizons / OD pipelines, does not
model proprietary detector / coding / pointing systems, and does not
provide flight-qualified decisions. Its purpose is to **decide which
full simulations are worth running**, not to replace them.

## 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)
- [Verification & Validation plan](VERIFICATION_AND_VALIDATION_PLAN.md)
- [Risk register](RISK_REGISTER.md)
- Other advanced calculators: [Reliability Emulator](../optical-link-reliability-emulator/USER_GUIDE.md), [Wave/AO Surrogate](../wave-optics-atmosphere-ao-surrogate/USER_GUIDE.md)