Epic: Ensemble variation, swing quiet zones, and sensitivity attribution

[dieterolson]

Parent and scope

Child epic of #4135. This extends the Rate of Closure Modern Workbench and the reusable variation capability consumed by UpstreamDrift.

Deliver production-grade, reproducible ensemble analysis that can perturb one or many parameters, preserve every trial including no-impact outcomes, quantify where a swing is geometrically stable or noise-responsive, attribute downstream variation to perturbation sources, and provide matched PyQt6/React visualizations and exports.

Canonical ownership and boundaries

• Canonical cross-application perturbation, ensemble, geometry-dispersion, and sensitivity contracts live in src/shared/python/swing_sim/variation/ when Tools is the reusable owner.
• Rate orchestration and presentation live in src/rate_of_closure/; UI must not duplicate numerical analysis.
• The React port follows the same serialized contracts and parity fixtures; cross-language differences must be pinned by tests.
• UpstreamDrift consumes the merged, immutable Tools implementation through its established vendor/ud-tools ownership boundary or a thin documented adapter; do not fork the physics or analysis.
• Apply RED -> GREEN -> REFACTOR TDD, Design by Contract, DRY, and Law of Demeter throughout.

R10 — Flexible perturbation plans

• R10.1 Users can vary any registered compatible model/input parameter individually or vary multiple parameters simultaneously.
• R10.2 Plans support independent distributions and explicit grouped/correlated perturbations with validated covariance/correlation semantics.
• R10.3 Perturbations can target a whole run or a documented time/spatial window where the underlying model exposes a time/location-varying input.
• R10.4 Every plan records schema version, units, base state, distribution parameters, correlation/group definition, seed/stream identity, model compatibility, and provenance.
• R10.5 Seeded plans replay deterministically independent of worker count and remain subset-stable for one-at-a-time studies.
• R10.6 Invalid, non-finite, dimensionally incompatible, duplicate, or non-positive-semidefinite plans fail at the contract boundary with actionable messages.

R11 — Complete ensemble dataset and typed outcomes

• R11.1 Every trial retains sampled inputs, run status, typed hit/no-impact/failure outcome, reason, event times, impact state when present, shot result when present, and complete pre-impact model traces.
• R11.2 No-impact is valid scientific data, never silently dropped and never converted into a fabricated impact/shot result.
• R11.3 Trial traces use stable modeled-point identifiers, explicit coordinate frame, common/resampled time or phase grid, and documented interpolation rules.
• R11.4 Exports round-trip losslessly with schema migration/error handling and enough provenance to reproduce the ensemble.
• R11.5 Large studies support bounded memory, progress, cancellation, deterministic chunking, and measured performance budgets.

R12 — Geometric scatter and low-variability regions

• R12.1 For every registered modeled point and sample/phase, calculate sample count, centroid, covariance, principal axes/eigenvalues, RMS radius, and configurable confidence ellipse/ellipsoid.
• R12.2 Detect and rank contiguous low-variability regions (quiet zones) using explicit user-selectable metrics/thresholds and minimum-duration criteria.
• R12.3 Quantify responsiveness to input noise separately from absolute geometric scatter; do not label correlation as causation.
• R12.4 All swing arcs can be overlaid in one graphic, colored/grouped by trial outcome and point, with median/reference arc, envelope/density, quiet-zone emphasis, selection, and scalable rendering.
• R12.5 Coordinate frame, units, alignment basis, sample count, and missing-data treatment are visible in every relevant view/export.

R13 — Sensitivity and attribution

• R13.1 Support one-at-a-time local attribution and full-study rank/correlation analysis for all compatible scalar outputs.
• R13.2 Provide a validated global method suitable for simultaneous nonlinear/interacting inputs (for example Morris screening and/or variance-based Sobol where sampling assumptions are satisfied).
• R13.3 Attribute perturbation source parameter plus optional source time/location window to downstream state-point/time metrics, impact variables, and shot outcomes.
• R13.4 Report interaction/uncertainty information, sample adequacy, method assumptions, and unavailable/not-applicable results honestly.
• R13.5 Users can inspect global attribution or isolate a selected input, modeled point, time/phase, impact variable, or shot metric without recomputing unrelated presentation logic.

R14 — Multi-trial visualization and UX parity

• R14.1 Every multi-trial simulation exposes impact-variable scatter plots and shot-outcome scatter plots; misses remain visible as a separate typed cohort.
• R14.2 Provide input-vs-output scatter/matrix, distributions, correlations/sensitivity heatmaps, and selectable trial brushing linked to swing arcs.
• R14.3 PyQt6 and React provide equivalent plan creation, run/progress/cancel, quiet-zone, arc-overlay, scatter, attribution, persistence, and export capabilities.
• R14.4 Controls are keyboard accessible, visibly interactive, responsive, and explain frames, units, methods, limitations, disabled states, and no-impact behavior.
• R14.5 Visual regression/Playwright and PyQt interaction tests cover individual and simultaneous variation, hits plus misses, all-arc overlays, scatter views, persistence, and export.
• R14.6 Complete Epic: Visual-first tab visibility and visualization-led React/PyQt UX #4433 for visual-first tab visibility: every React/PyQt visualization-bearing tab exposes its primary visual in the initial viewport, with matched empty/result/error states and protected visibility audits.

R15 — UpstreamDrift integration and evidence

• R15.1 Create and cross-link an UpstreamDrift integration issue that names its consuming surfaces and exact Tools pin/adapter path.
• R15.2 UpstreamDrift uses the canonical schemas/results without duplicating perturbation, dispersion, or sensitivity algorithms.
• R15.3 Cross-repository parity tests pin representative seeded ensembles, no-impact cohorts, geometric metrics, and attribution outputs.
• R15.4 Publish theory, assumptions, limitations, quick-start, schema, performance, and reproducibility documentation suitable for public technical discussion.

Dependency-ordered workstreams

1. Versioned perturbation and ensemble contracts (R10-R11)
2. Stable-point trace capture and geometric analysis (R12)
3. Sensitivity/attribution methods and adequacy reporting (R13)
4. React/PyQt linked visualizations and persistence/export (R14)
5. UpstreamDrift pin/adapter/parity integration (R15)
6. Full tests, profiling, rendered review, docs, CI, and protected merge

Completion evidence

This epic closes only after linked protected PRs are merged, every requirement is tied to test evidence, representative seeded results match across supported runtimes, both UI artifacts pass interaction and rendered review, UpstreamDrift consumes the merged immutable Tools revision, and queued/skipped/zero-job workflows are not counted as passing. Completion also requires #4433 to be closed with the visual-first tab inventory, first-viewport checks, and matched rendered evidence passing.

[linear]

D-7546

[dieterolson]

Cross-repository consumption is now tracked in UpstreamDrift#8358. That issue preserves Tools as the canonical owner, waits for an immutable Tools-main merge before repinning, and scopes UpstreamDrift to thin engine/trace adapters, cross-engine orchestration, parity tests, launcher capabilities, and the vendor gitlink update.