@ -1,32 +1,5 @@
# Test Refactoring Optimization Strategy
## Tooling
- `scripts/sim_engine.py` — Generic orbital mechanics simulator (Python, TOML 1.0 configs)
- Replicates C++ physics: Kepler propagation, orbital↔Cartesian transforms, drift detection
- Multi-body hierarchical propagation with global/local coordinate tracking
- Use for precalculating expected values (transition times, final states, energy conservation)
- TOML configs in `tests/` must use TOML 1.0 inline table syntax (single-line `{}` )
- Old configs in `old_tests/` use multiline inline tables (toml-c17 style) — keep for reference
- Python's `tomllib` requires single-line inline tables
## Sim Engine Capabilities
### Implemented
- Body propagation (elliptical + parabolic via Barker's equation)
- Orbital↔Cartesian transforms (full z-x-z Euler rotation)
- Velocity drift detection and element reconstruction
- Global coordinate computation (hierarchical parent→child)
- Spacecraft struct, loading, propagation
- Impulsive burns (prograde, retrograde, normal, antinormal, radial_in, radial_out, custom)
- TOML 1.0 config parsing
### NOT Implemented (notify the user before beginning to refactor)
- SOI transitions
- Maneuver trigger system (TRIGGER_TIME, TRIGGER_TRUE_ANOMALY)
- Hohmann transfer calculations
- Rendezvous planning
- OrbitTracker
- Energy functions (KE, PE, total)
- Hyperbolic propagation
## Refactoring Rules
### 1. Structure
@ -66,6 +39,7 @@
- **Always output local-frame values** (distances from parent, not global from origin).
- C++ tests typically use local coordinates (e.g., `vec3_distance(craft->local_position, (Vec3){0,0,0})` ).
- Global distances are dominated by parent body positions (e.g., Earth-Sun distance swamps LEO orbit).
- **Always output SI units** (meters, m/s, seconds) — C++ tests use SI internally.
- Output C++-style comments with precalculated constants for embedding in the test.
- Run with: `python3 scripts/precalc_<test_name>.py`
- If sim_engine.py lacks a feature, use analytical formulas instead (**but notify the user what feature was missing**)
@ -75,7 +49,7 @@
### Step 1: Refactor
- Verify the test file has a TOML config in `old_tests/` . If it doesn't, skip — it's likely hardcoded.
- Check if the test is already in `tests/` (already refactored). Skip if so.
- Check the capability matrix — if the test needs SOI, maneuvers, rendezvous, etc., flag this before starting.
- Check the capability matrix in Section 5 — if the test needs SOI, maneuvers, rendezvous, etc., flag this before starting.
- Process **one test file at a time** .
- Create `scripts/precalc_<test_name>.py` and run it to get expected values.
- Copy from `old_tests/` to `tests/` , rewrite using the pattern from `test_true_anomaly_roundtrip.cpp` .
@ -102,6 +76,36 @@
- **Always ask for review** before moving to the next file.
- **Only commit when asked.**
## Tooling & Sim Engine Capabilities
### Tooling
- `scripts/sim_engine.py` — Generic orbital mechanics simulator (Python, TOML 1.0 configs)
- Replicates C++ physics: Kepler propagation, orbital↔Cartesian transforms, drift detection
- Multi-body hierarchical propagation with global/local coordinate tracking
- Use for precalculating expected values (transition times, final states, energy conservation)
- TOML configs in `tests/` must use TOML 1.0 inline table syntax (single-line `{}` )
- Old configs in `old_tests/` use multiline inline tables (toml-c17 style) — keep for reference
- Python's `tomllib` requires single-line inline tables
### Sim Engine Capabilities
#### Implemented
- Body propagation (elliptical + parabolic via Barker's equation)
- Orbital↔Cartesian transforms (full z-x-z Euler rotation)
- Velocity drift detection and element reconstruction
- Global coordinate computation (hierarchical parent→child)
- Spacecraft struct, loading, propagation
- Impulsive burns (prograde, retrograde, normal, antinormal, radial_in, radial_out, custom)
- TOML 1.0 config parsing
#### NOT Implemented (notify the user before beginning to refactor)
- SOI transitions
- Maneuver trigger system (TRIGGER_TIME, TRIGGER_TRUE_ANOMALY)
- Hohmann transfer calculations
- Rendezvous planning
- OrbitTracker
- Energy functions (KE, PE, total)
- Hyperbolic propagation
## Test Refactoring Status
### Completed
@ -110,9 +114,6 @@
- `test_cartesian_to_elements_basic` ✅ — Element round-trip conversion (semi-major axis, eccentricity, true anomaly, inclination, radius, velocity)
- `test_parabolic_orbit` ✅ — Parabolic orbit energy conservation + escape trajectory + initial conditions
### Sim Engine Fix Applied
- Added `semi_latus_rectum` → `OrbitalElements.p` mapping in `bodies_from_config()` and `spacecraft_from_config()` (needed for parabolic orbit configs)
### Can Refactor Now (sim_engine.py supports all features needed)
- `test_extreme_eccentricity` — high-eccentricity orbits
- `test_extreme_orientation_mixed` — extreme inclinations/eccentricities