Skip to content

Fratres-X-AI/SHEAR

Repository files navigation

Project SHEAR

Program: HYPERLINK (Hypersonic Intercept Performance Evaluation — Relay Navigation, Engagement, Kinematics & Link)

Codename: Project SHEAR (Sensor-degraded Hypersonic Engagement And Reachability)
Working title: Boost-to-Glide Transition Uncertainty & Feasible-Set Prediction under Degradation and Adversarial Maneuvering

Technical Focus

Project SHEAR develops real-time, physics-constrained tracking, uncertainty quantification, and feasible-set prediction for hypersonic threats during boost through early atmospheric glide initiation, under sensor degradation, sparse/noisy measurements, and adversarial maneuvering within physical limits.

What SHEAR enables that existing methods don't: a single auditable intercept disk $R_{\text{shear}}$ combining feasible maneuver tubes, scenario UQ, adversarial stress, and conformal calibration—rather than optimistic filter covariance or unfeasible black-box ML envelopes.

See docs/what-this-enables.md for the one-page reviewer brief.

Scope: Boost ascent → MECO → coast → pull-up → ~30–60 s early glide. Handoff to sibling project BOUND at equilibrium glide entry.

Current Status

Phase Status
Foundation (Phase 0) Detailed Design / Implemented — problem definition, architecture, UQ approach
Boost ROM (Phase 1) Implemented & Tested (synthetic) — ParametricSample, V&V report, pytest coverage
Transition + Glide (Phase 2) MVPglide_rom.py, aero.py, transition.py, event log
UQ + Pipeline (Phase 3) MVP (synthetic V&V) — conformal, latency tiers, adversarial stress
Plasma observation (Phase 3b) MVP surrogate — live pipeline + PlasmaGapSpec on RevisitConfig; not CEM-calibrated
Hybrid estimator (Phase 4) MVP foundation — opt-in estimator_enabled
Phase branches (COAST/PULLUP) MVPphase_propagation.py, opt-in
Truth-in-Tube evidence (Phase 6) Implemented & Tested (synthetic, n=500) — conformal 0.902 · Wilson [0.873, 0.925] · defense suite PASS · RunPod final pass 2026-05-28; not Validated
Adversarial stress grid (Phase 7) Implemented & Tested (synthetic, 36-cell) — REQ-ADV-001 closure 36/36 · baseline closure 24/36 · P3 nominal truth 36/36 (revisit-centroid; prior 2/36 was x_hat proxy bug) · plasma on · not Validated
BOUND handoff (Phase 8) Implemented & Tested (synthetic) — schema + emitter; REQ-HDO-001 smoke PASS 2026-05-28; CI handoff step wired (not Validated)
Audit records (REQ-AUD-001) Schema + emitteraudit.py, pipeline validation, optional emit_audit_path

Maturity legend

Stage Meaning
Concept Problem/architecture only
Detailed Design Spec + interfaces, limited code
Implemented Code exists, minimal tests
Implemented & Tested Unit/integration tests pass (scope noted: synthetic, schema, E2E pending)
Validated Independent or flight-truth evidence

Status table rows use scoped labels — e.g. Integrated MVP (synthetic V&V) — not operational Validated unless explicitly stated.

Defense readiness

SHEAR is a research prototype, not operationally accredited. Gate G1 (partner outreach) evidence is packaged for government partnership discussions — not production deployment or DoD accreditation:

python validation/vv/run_defense_readiness_suite.py

Relationship to BOUND

Project Regime Primary output
SHEAR Boost → early glide $\mathcal{R}{\text{honest}}(\tau)$, $R{\text{shear}}(\tau)$, handoff packet
BOUND Equilibrium glide $\mathcal{R}(\tau)$, $R_{\text{bound}}(\tau)$

SHEAR addresses the upstream hard problem BOUND explicitly excludes. See references/bound-sibling.md.

Quick Start

cd implementation
pip install -e ".[dev]"
pytest tests/ -v

How to Navigate the Project

If you want to… Start here
One-page technical summary docs/shear-technical-summary-one-page.md
"We Need That" recovery evidence index validation/reports/we-need-that-evidence-index.md
Recovery progress log (Phases 0–6) progress_recovery.md
Validation roadmap (L0–L6) validation/validation-strategy.md
Phase 5 evidence build plan docs/phase-5-evidence-build-plan.md
Phase 5 evidence report validation/reports/shear-9-recovery-evidence-report.md — Phase 6 Truth-in-Tube · n=500 conformal 0.902 (synthetic)
Read the locked problem statement research/problem-definition.md
Understand literature gaps research/literature-gaps.md
Read the concept note docs/shear-boost-transition-concept-note.md
See system architecture modeling/architecture.md
Understand honest UQ + adversarial design modeling/uncertainty-adversarial-approach.md
Reference equations research/key-models-and-equations.md
Open technical questions research/open-technical-questions.md
Read boost-phase equations modeling/boost-dynamics.md
Read glide-phase equations modeling/glide-dynamics.md
See build order docs/prototyping-order.md
External review packet certification/external-review-packet/
15-min reviewer start docs/quick-start-for-reviewers.md
What SHEAR enables (one-pager) docs/what-this-enables.md
Pass 6 coverage report validation/reports/pass6-coverage-interpretation.md
Boost ROM V&V report validation/vv/boost_rom_vv_report.md
Glide / transition / UQ V&V validation/vv/
Latency optimization report validation/latency/latency_optimization_report.md
Physics fidelity memo validation/reports/physics-fidelity-memo.md
Validation acceptance criteria validation/acceptance-criteria.md
BOUND sibling reference references/bound-sibling.md

Repository Layout

SHEAR/
├── README.md
├── docs/                         # Concept note
├── research/                     # Problem definition, literature, equations, open questions
├── modeling/                     # Architecture, UQ approach, algorithm specs
├── implementation/               # Python package (shear)
│   ├── src/shear/
│   ├── tests/
│   └── data/config/
├── validation/                   # Acceptance criteria, V&V harnesses, runpod campaigns
├── certification/                # IUS, traceability, external review packet
├── operator/                     # CLI revisit loop
├── runpod/                       # Compute profiles and pod helpers
├── references/
└── export/

Core Outputs (Target)

At each sensor revisit:

Output Symbol Description
State estimate $\hat{\mathbf{x}}_k$ Phase-conditioned, physics-constrained
Honest reachable set $\mathcal{R}_{\text{honest}}(\tau)$ Decomposed param + phase + obs_gap + adversarial
Bounded radius $R_{\text{shear}}(\tau)$ Ground-plane disk at coverage $p_{\text{cov}}$
Validity mode FULL_TRACKINFEASIBLE_STATE Fail-closed gating
Handoff packet BOUND ingest At stable EARLY_GLIDE

What Impressive Progress Looks Like

On this problem, impressive ≠ low RMSE:

  1. Honest tubes through transition — n=500 stressed conformal pinned (overall 0.902, Wilson [0.873, 0.925], synthetic ROM); 36-cell adversarial grid: REQ-ADV-001 closure 36/36, P3 nominal truth 36/36 (revisit-centroid)
  2. No covariance collapse after pull-up vs. UKF-only baseline (partial synthetic evidence)
  3. Adversarial closure — DE worst-case endpoint inside inflated disk on cert grid; not the same as nominal truth coverage
  4. Physics beats kinematics when constrained; wider when degraded (synthetic V&V)
  5. Phase honestyPHASE_UNCERTAIN during transition, not false confidence
  6. BOUND handoff — pod E2E PASS; CI step wired; double-counting review not Validated
  7. Latency — fast tier adversarial P50 ~389 ms on elite pod (31 vCPU); tier- and config-dependent; REQ-LAT-001 500 ms target met on pinned prod preset only

Biggest Risks

  1. No classified ground truth — synthetic validation only
  2. Plasma surrogate may miss band-specific blackout — must stay conservative
  3. Phase detection latency → collapsed multi-modal posterior
  4. Scope creep into BOUND equilibrium glide territory
  5. Conformal calibration on nominal-only holdout → optimistic coverage under adversarial stress

Current Limitations

  • Research prototype only — no operational accreditation or flight-truth validation
  • Plasma model — phenomenological surrogate; not CEM/radar-calibrated
  • Adversarial stress — 36-cell expanded grid pinned (cbc808d): closure 36/36 (redteam) / 24/36 (baseline harness); P3 nominal truth 36/36 (revisit-centroid; prior 2/36 was post-process proxy bug) — not flight-validated
  • Conformal holdout — n=500 stressed conditional pinned (overall 0.902); prior n=100 in git history; calibration still calibrate_without_adversarial: true by default
  • BOUND handoff — pod smoke PASS; CI E2E wired; not operationally Validated
  • Hybrid estimator / phase branches — opt-in MVP; not default production path

Next Milestones

  • First green GitHub CI run with public BOUND + handoff artifact
  • Fix post-process P3 metrics export (store revisit centroid in grid CSV to avoid re-run)
  • Optional --with-adversarial conformal calibration pin (separate from n=100 stressed holdout)
  • Partner sanitized track ingest (G2)

Honestly Out of Reach (Near Term)

  • Fire-control-quality birth-to-death salvo tracking
  • Real-time full 6-DOF game-theoretic reachable sets for unknown adversary
  • Guaranteed intercept against arbitrary adversarial HGV
  • Single-modality radar through worst-case plasma blackout

Classification

Working materials are UNCLASSIFIED for portfolio and technical submission use.

Document Index

Document Version
research/problem-definition.md 1.0
research/literature-gaps.md 1.0
research/key-models-and-equations.md 1.0
research/open-technical-questions.md 1.0
modeling/boost-dynamics.md 1.1
modeling/glide-dynamics.md 1.0
docs/prototyping-order.md 1.0
modeling/architecture.md 1.0
modeling/uncertainty-adversarial-approach.md 1.0
docs/shear-boost-transition-concept-note.md 1.0
validation/acceptance-criteria.md 1.0

About

Project SHEAR

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors