claudes_game/continue.md

Test Refactoring Optimization Strategy

Refactoring Rules

1. Structure

• One SCENARIO("description") per logical test group, with [tag1][tag2] annotations
• Shared fixture: all constants, structs, and variables declared between SCENARIO opening and first SECTION
• Run scripts/precalc_*.py to generate expected values — these Python scripts are the authoritative source, providing an independent check against the C++ simulation. Embed the values directly in WithinAbs() calls (no need to declare named constants unless the value is reused).

2. Duplication Elimination

• Use lambdas that capture the fixture for repeated setup→call→assert patterns
• Reuse shared structs in-place (mutate fields rather than recreating)
• Single-line SECTIONs when body is one statement: SECTION("name") { helper(arg); }

3. Assertions

• Include src/test_utilities.h for tolerance constants and test utilities
• #include <catch2/matchers/catch_matchers_floating_point.hpp> (required for WithinAbs matcher)
• using Catch::Matchers::WithinAbs; after includes
• REQUIRE_THAT(value, WithinAbs(expected, tolerance)) — never Approx()
• Always use named tolerance constants — never hardcode raw numbers for tolerance in WithinAbs().

Tolerance Reference

All constants defined in src/test_utilities.h — use those, do not redefine locally.

Constant	Value	Use for
A_TOL	1e-6	Semi-major axis (meters), magnitude < 1e10
E_TOL	1e-12	Eccentricity, round-trip conversion
ANG_TOL	1e-12	Angles in radians (nu, inc, Ω, ω)
ANG_TOL_COARSE	1e-4	Angles, degenerate cases (polar/retrograde)
R_TOL	1e-6	Radius / distance magnitudes (meters)
V_TOL	1e-6	Velocity magnitudes (m/s)
M_TOL	1e-6	Time / period values (seconds)
REL_TOL	1e-8	Relative / percentage errors (dimensionless)
DRIFT_TOL	1e-12	Energy drift percent (parabolic orbit)

• Tighten aggressively: if observed error is 1e-8, use 1e-6 (two orders of margin)
• Replace qualitative checks (a > b) with quantitative (WithinAbs(expected, tol))
• INFO("label: " << value) for debugging context

4. Precalc Scripts

• For each test file, create scripts/precalc_<test_name>.py that computes expected values.
• Check the capability matrix first — only use sim_engine.py for implemented features.
• 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 expected values for embedding in the test. Tolerances are chosen separately by the test writer using the Tolerance Reference table — the precalc script should not output tolerance values.
• 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)

Refactoring Procedure

Step 1: Refactor

• Verify the test file has a TOML config in old_tests/. If it doesn't, skip the TOML rewrite step — the test is likely hardcoded.
• Check if the test is already in tests/ (already refactored). Skip if so.
• 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.
• Rewrite TOML configs to TOML 1.0 inline table syntax (single-line {}).
• Follow all rules in sections 1-4 above.

Step 2: Tighten Tolerances

• Build and verify: make test-build then ./build/orbit_test '[tag]' -s.
• Run full suite: make test.
• Review every tolerance against actual observed errors from -s output.
• If a constant's margin is too loose (e.g., 1e-6 when error is 1e-10), tighten to 1e-8.
• If a test fails due to a tolerance being too tight, report the observed error to the user and ask whether to loosen the constant or investigate the root cause. Never silently widen a tolerance.
• Refer to the tolerance reference table in Section 3 for constant names.

Step 3: Code Review

• Remove unused includes (only include what's actually used).
• Remove unused variables (e.g., const double mu = G * M_sun; if never referenced).
• Look for repeated initialization patterns — extract into helper lambdas (make_elements, convert_and_recover).
• Use const for all fixture data and recovered results.
• Replace C-style arrays with std::array where appropriate.
• Ensure consistent tolerance usage (no hardcoded 1e-4 when ANG_TOL_COARSE exists).
• Check for compare_vec3 availability in test_utilities instead of 6 individual REQUIRE_THAT calls.
• Run full suite again: make test.
• 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

• test_barkers_equation ✅ — Barker's equation unit tests + parabolic propagation
• test_cartesian_to_elements_advanced ✅ — Advanced conversion tests (eccentricity spectrum, inclination, true anomaly, 3D orientation)
• 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
• test_extreme_eccentricity ✅ — High-eccentricity orbits (single SCENARIO, precalculated values, REL_TOL)
• test_extreme_orientation_mixed ✅ — Extreme orientation conversions, rotation matrix properties, singularity handling
• test_extreme_timescales ✅ — 9 TEST_CASEs → 1 SCENARIO with 11 SECTIONs, all WithinAbs use named constants
• test_analytical_propagation ✅ — 5 SCENARIOs → 1 SCENARIO with 23 SECTIONs, precalculated values, all WithinAbs use named constants

Can Refactor Now (sim_engine.py supports all features needed)

• test_moon_orbits — multi-body propagation
• test_periapsis_burn — prograde burns
• test_hybrid_burns — impulse burns
• test_omega_debug — burn + element reconstruction

Blocked on Missing Features

• test_soi_transition — needs SOI transitions
• test_root_body_transitions — needs SOI transitions
• test_maneuver_planning — needs maneuver trigger system
• test_hybrid_energy_conservation — needs energy functions (KE, PE, total)
• test_hyperbolic_orbit — needs hyperbolic propagation
• test_rendezvous — needs Hohmann transfer calculations

Skip (Hardcoded / No TOML)

• test_integration — hardcoded vector tests, no TOML config