Skip to content

Audit Findings

Jump to bottom
Test User edited this page May 30, 2026 · 8 revisions

Pre-Release Audit Findings — astrodyn vs JEOD v5.4

Audit anchor: this gap list was originally generated against commit 587e2e7 (April 27, 2026) and refreshed against 7619f2f (May 10, 2026). When the tree advances, regenerate from the matrix.

Prioritized gap list derived from JEOD-Capability-Matrix. Every non-covered, non-derived, non-n/a matrix row is reflected here, sorted into three buckets:

  1. Release blockers — capabilities a downstream mission crate could reasonably reach for and find missing or numerically wrong.
  2. Documentation/discoverability blockers — capability is in code but not surfaced through a recipe, example, or doc.
  3. Nice-to-have / accepted divergence — gaps where the cost of closing exceeds the value, or where the JEOD capability is niche.

Each bucket-1 entry has a one-line "what's required to close" note that can be copy-pasted as a GitHub issue title.

The original audit at 587e2e7 listed 10 release blockers and 4 documentation blockers. Five of those have closed:

  • B1.1 / B1.9 — frame-attached body integration and SIM_ref_attach parity (DB.13–DB.21) closed by #309.
  • B1.2 — dynamic body-action lifecycle (SIM_removable_body_action) closed by #311.
  • B1.8 — GroundFacet contact geometry (SIM_ground_contact) closed by #261.
  • B2.3 — per-integrator-group time-step coordination is documented in the Integration-Groups wiki page and the astrodyn_bevy::sets rustdoc.

The page below tracks only the items that remain open.

Bucket 1 — Release blockers (6 open)

These should either be closed before tagging a release or have an explicit "accepted divergence with rationale" decision recorded.

B1.3 — UTL.07: LSODE integrator not ported (tracking: #200)

Gap: JEOD's LSODE (variable-order Adams/BDF, stiff/non-stiff) is the primary integrator for missions with stiff dynamics (e.g. very low-altitude drag-dominated, or high-eccentricity perigee passes). astrodyn has RK4, RKF45, ABM4, Gauss-Jackson — no stiff integrator. tier3_sim_lsode exercises ABM4 as a placeholder.

Close with: port LSODE proper, or document as accepted divergence and recommend RKF45 with tight error tolerance for stiff cases.

Issue title: Port LSODE integrator or document accepted divergence

B1.4 — VRF.dyncomp.12 / VRF.dyncomp.13: SIM_dyncomp RUN_6C / RUN_6D drag-maneuver scenarios not covered (tracking: #201)

Gap: RUN_6A is derived; RUN_6B is covered (Bevy parity wrapper reinstated in #416); RUN_6C and RUN_6D have no direct cross-validation. These exercise drag + impulsive maneuver combinations.

Close with: regenerate JEOD reference CSVs for RUN_6C/RUN_6D and add two new tier3_simulation_run6c/run6d tests.

Issue title: Add Tier 3 cross-validation for SIM_dyncomp RUN_6C/RUN_6D

B1.5 — VRF.dyncomp.21 / VRF.dyncomp.25: SIM_dyncomp RUN_9B / RUN_10B not covered (tracking: #202)

Gap: rotational-state edge cases (RUN_9B = combined torques scenario, RUN_10B = circular orbit + zero rate). The 9-series and 10-series are otherwise covered.

Close with: regenerate references, add tier3_simulation_run9b and tier3_simulation_run10b.

Issue title: Add Tier 3 coverage for SIM_dyncomp RUN_9B and RUN_10B

B1.6 — BCH.02: Rosetta hyperbolic Earth swing-by mission benchmark (tracking: #203)

Gap: JEOD's Integrated_Validation/SIM_Earth_Moon includes a Rosetta swing-by case. astrodyn has hyperbolic-orbit unit coverage (tier3_orbinit_hyperbolic) but no full mission scenario. This is a real-data benchmark — the kind of case downstream users are most likely to point at.

Close with: build crates/astrodyn/src/recipes/scenarios/rosetta.rs and tier3_simulation_rosetta_swingby. Reference data is in JEOD.

Issue title: Add Rosetta swing-by mission benchmark (BCH.02)

B1.7 — BCH.04 / VRF.mars.02 / VRF.mars.03: Phobos mission scenarios (tracking: #204)

Gap: Mars-Phobos system not modeled. Requires Phobos ephemeris (available in DE) and small-body gravity treatment (we have point-mass for moons, which is fine for Phobos at Mars-orbit altitudes). The RUN_orb_init_phobos tests orbital initialization around a small body.

Close with: add Phobos to crates/astrodyn/src/recipes/mars.rs, build tier3_phobos_orbit and tier3_phobos_orbit_init.

Issue title: Add Phobos mission scenarios (BCH.04, VRF.mars.02–03)

B1.10 — ENV.20 / VRF.gv.02: SIM_csr_compare (CSR vs GGM gravity-model cross-check) not ported (tracking: #207)

Gap: JEOD verifies that switching between gravity coefficient sets (CSR and GGM) preserves expected differences. We support GGM05C/GGM02C only and have no CSR data. This is a gravity-model breadth gap.

Close with: either (a) ingest a CSR coefficient set and add a cross-check, or (b) document as accepted divergence and recommend GGM05C as the production default.

Issue title: Decide on CSR gravity coefficient support (ENV.20)

Bucket 2 — Documentation/discoverability blockers (3 open)

These capabilities exist in code but are not visible to a downstream user unless they read the source. A release that hides them is worse than one that doesn't ship them.

B2.1 — DYN.14 / VRF.ba.02: LVLH-frame body initialization needs a recipe (tracking: #208)

Gap: SIM_lvlh_init exercises spawning a vehicle at a LVLH-relative position. We support this via vehicle_builder but no recipes::* example or doc shows it. Users who want "spawn this satellite 50 km behind that station" will not find the path.

Close with: add recipes::orbital_elements::iss_relative_lvlh() or similar; add a tier3_sim_lvlh_init direct cross-validation.

B2.2 — INT.04: Aero-thermal coupling has no end-to-end example (tracking: #209)

Gap: thermal_rider.rs covers the SRP side (tier3_sim_srp_rk4_thermal) but the aero side (drag coefficient varying with surface temperature) has no Tier 3. Users who want temperature-dependent drag will not know we support it.

Close with: add tier3_sim_aero_thermal exercising a heating/cooling cycle with drag-coefficient variation.

B2.4 — UTL.19: Surface-model primitives beyond FlatPlate (tracking: #211)

Gap: JEOD's surface model has FlatPlate, FlatPlateCircular, Cylinder. We have FlatPlate only. FlatPlateCircular is used for solar panel + dish geometry; Cylinder is used for tank/body modeling. Users who want non-flat geometry will write their own.

Close with: add FlatPlateCircular and Cylinder facet types to crates/astrodyn_interactions/src/surface_model.rs, plus aero+SRP coverage.

Bucket 3 — Nice-to-have / accepted divergences (35 items)

These are gaps where the cost of closing exceeds the value. Each is paired with a one-line rationale for accepting the divergence.

Deferred invariants (visible structurally, not at runtime)

  • DYN.01 / DYN.08 / DYN.12 / DYN.17 / DYN.27 — three-frame model (structure / composite_body / core_body) is partially modeled. The separation matters for high-fidelity attitude sims with offset CoM and structural thermal flexure; for typical orbital missions the composite-body integration is sufficient. Tracked under JEOD_invariants.md (DB.04, DB.12–DB.17, DB.21, MA.11–MA.20).

  • DYN.14 / VRF.ba.02 / DYN.17 — body attachment edge cases (180° yaw attach-by-point) — JEOD_INV: MA.16 deferred. Affects only a narrow attachment geometry; flagged in invariant catalog.

Niche JEOD features unlikely to be reached for

  • ENV.23 / VRF.ep.02 — propagated-planet ephemeris — pattern where planets are propagated under sim physics rather than read from ephemeris. Useful in orbit-determination research, not mission ops. We require ANISE-loaded ephemeris.

  • ENV.24 — simple analytical ephemeris fallback — low-fidelity fallback for sims without DE files. We require ANISE.

  • ENV.34 — generic per-planet RNP — Earth, Moon, Mars covered; arbitrary planet RNP (e.g. Venus, Mercury rotation) not exposed. Mercury sims use inertial-frame integration.

  • INT.13 — spring-pair contact interaction — primarily for joint/cable models. Not used in typical orbital missions.

  • INT.14 / VRF.sm.01 — articulated surface model — moving panels (e.g. solar-array tracking, antenna pointing). Static surfaces only.

  • UTL.13 — Gauss quadrature — used in JEOD only for legacy surface-model integration; unused in main pipeline.

  • VRF.db.04 — SIM_verif_shutdown — JEOD shutdown sequence. Rust Drop handles resource cleanup; no equivalent test needed.

  • DAT.03 — Earth GEMT1 (legacy gravity model) — loader works; no trajectory test. Modern users prefer GGM05C.

  • DAT.07 — Moon LP150Q (Lunar Prospector 150) — loader works; no trajectory test. GRAIL150 is the modern default.

  • VRF.ba.01 — SIM_orbinit per-RUN coverage — 5 of 46 JEOD RUNs are CSV-validated via Docker; the other 41 are exercised analytically through family invariants (energy/angular-momentum conservation, Cartesian↔element round-trip). The 5 covered RUNs (ISS inertial, STS inertial, ISS pfix, STS pfix, STS trans-state) are representative across orbit-IC types. Closing the remaining 41 would require Docker regeneration of all 46 CSVs and a corresponding Tier 3 per RUN.

  • VRF.ba.04 — SIM_verif_attach_mass per-RUN coverage — 8 of 21 JEOD RUNs (RUN_01, 02, 03, 04, 10, 11, 101, 102) are covered. The 8 covered RUNs span the basic attach geometries; the remaining 13 are advanced attach/reattach permutations (e.g. 180° yaw, multi-stage chains) that exercise the same code paths through different inputs.

JEOD/Trick infrastructure replaced by Rust/Bevy idioms

These 16 rows are explicitly n/a in the matrix with a documented Rust equivalent. Listed here for completeness so the audit's "did we consider this?" answer is yes:

  • ENV.21 (DE4xx parser) → ANISE
  • ENV.29 (exponential atmosphere) → astrodyn addition for analytical tests
  • ENV.36 (SPICE) → ANISE
  • UTL.03 (frame subscription) → Bevy schedule
  • UTL.09 (integration loop) → Bevy FixedUpdate
  • UTL.20 (containers) → Rust collections + Bevy reflection
  • UTL.21 (memory manager) → Rust ownership
  • UTL.22 (message handler) → panic! + tracing
  • UTL.23 (named item) → Bevy Entity + Name
  • UTL.24 (Trick sim interface) → Bevy ECS
  • UTL.25 (Trick CSV) → CSV via csv crate in tests
  • UTL.26 (model template) → idiomatic Rust crate structure
  • EXP.03 (experimental message) → tracing
  • VRF.dyncomp.29–30 (checkpoint create/restore) → Bevy reflection covers state, not active integrator state — accepted divergence
  • VRF.na.01–05 (SIM_container, SIM_memory, SIM_message_handler_verif, SIM_integ_loop, SIM_simulation_interface) → all subsumed by the language/runtime equivalents above
  • DAT.17 (DE4xx binary) → .bsp SPK kernels via ANISE

Summary

Bucket Open items Action
1 — Release blockers 6 Close before release, or record explicit accepted-divergence decision
2 — Doc/discoverability 3 Close in docs/recipes layer
3 — Nice-to-have / accepted 35 No action needed; documented above for future reference

Five originally bucket-1/bucket-2 items closed since the audit anchored at 587e2e7: B1.1 / B1.9 (#309), B1.2 (#311), B1.8 (#261), B2.3 (Integration-Groups wiki page). Bucket 1 is the actionable list. Bucket 3 is the audit's record that we considered each gap and accepted it.

Triage process for the next audit cycle

When JEOD is upgraded or new astrodyn capability is added:

  1. Re-walk the matrix; any row whose status changes gets a dated note.
  2. Re-derive this gap list. Bucket 3 items don't move unless their rationale changes (e.g. a user request elevates a niche feature).
  3. Bucket 1 items either close (delete the entry) or graduate to bucket 3 with an "accepted divergence" rationale.

The matrix and this gap list are intentionally a snapshot, not an auto-derived view. Treat them as living documents updated when capability status changes — same cadence as JEOD_invariants.md.

Clone this wiki locally