claudes_game/docs/planning/newton_raphson_test_plan.md

Newton-Raphson Test Plan

Overview

Test cases for Newton-Raphson analytical propagation implementation, organized by implementation phase and test category.

File Organization

Each test file requires a dedicated config file (1:1 mapping). Total test files: 13 main files + test_barkers_equation.cpp = 14 total ✅ COMPLETE

Current Progress (2026-02-02)

Completed Tests (13/14 files fully passing)

1. ✅ test_cartesian_to_elements_basic.cpp + .toml: Round-trip conversion with fixed true anomaly calculation (PASSING 12/12)

2. ✅ test_newton_raphson_convergence.cpp: Convergence across eccentricity ranges with separated solvers (PASSING 28/28)

3. ✅ test_analytical_propagation_apsides.cpp: Propagation through apsides with fixed velocity comparison (PASSING 5/5)

4. ✅ test_analytical_propagation_timesteps.cpp: Timestep validation with fixed test design bugs (PASSING 7/7)

5. ✅ test_extreme_eccentricity.cpp: Near-parabolic/hyperbolic boundaries with validation fixes (PASSING 28/28)

6. ✅ test_precision_boundaries.cpp: Boundary value handling with fixed circular orbit velocity (PASSING 15/15)

7. ✅ test_cartesian_to_elements_extreme.cpp + .toml: Parabolic test fixed and tolerances tightened (PASSING with 93 tests)

8. ✅ test_cartesian_to_elements_quadrature.cpp + .toml: Argument of periapsis fix with atan2() (PASSING with 93 tests)

9. ✅ test_hybrid_impulse_burns.cpp + .toml: Impulsive burn handling with full maneuver system (PASSING with 96 assertions)

• Hohmann transfers (2 burns)
• Plane changes at nodes
• Impulsive burns at apsides
• Minimal burns (Δv < 1 m/s) to large burns (Δv > orbital velocity)
• Multiple burn sequences
• Uses full maneuver system (execute_maneuver not just apply_impulsive_burn)

10. ✅ test_hybrid_continuous_thrust.cpp + .toml: Continuous thrust integration (PASSING with 40 assertions)

• Continuous low-thrust burns (ion engines)
• Multi-burn sequences with separate burn phases
• Mode transitions between analytical propagation and Cartesian burns
• Energy conservation during finite-duration burns
• Numerical stability during 120 burn/conversion cycles

11. ✅ test_hybrid_energy_conservation.cpp + .toml: Analytical vs numerical propagation comparison (PASSING with 89 assertions)

• Energy comparison for circular, elliptical, high eccentricity, inclined, fast, and slow orbits
• Pre/post burn energy validation (ΔE = v·Δv + 0.5Δv²)
• Long-term energy drift comparison (10 orbits)
• Analytical propagation: Zero energy drift (exact conservation)
• Numerical RK4: 1.7e-07 (circular) to 3.6e-03 (high eccentricity) relative drift

12. ✅ test_extreme_orientation_mixed.cpp + .toml: Combined high inclination + high eccentricity (PASSING with 157 assertions)

• Rotation matrix behavior at extreme inclination/eccentricity combinations
• Ω and ω singularity handling
• Velocity vector orientation at apsides
• Round-trip conversion for extreme orientation parameters
• Rotation matrix verification

13. ✅ test_extreme_timescales.cpp + .toml: Orbital period extremes (PASSING with 55 assertions)

• Fast orbits (LEO, Mercury-like) for numerical precision
• Slow orbits (Jupiter-like) for mean anomaly accumulation
• Low altitude (~100 km) and super-synchronous orbits
• Geosynchronous orbit period accuracy (23.9347 hours, sidereal day)
• Period consistency across different true anomalies
• Energy conservation across all timescales

Implementation Summary

Code Changes:

• Added functions to src/orbital_mechanics.h: Newton-Raphson solver, cartesian→elements conversion, modular API (elliptical/hyperbolic solvers), Barker's equation
• Implemented in src/orbital_mechanics.cpp: 1e-10 tolerance, max 50 iterations, series expansion initial guess, fixed true_anomaly calculation and circular orbit velocity, parabolic propagation with Barker's equation
• Removed propagate_orbital_elements() from src/test_utilities.h/.cpp
• Added validate_true_anomaly_ranges() to src/config_validator.cpp
• Standardized parabolic detection (PARABOLIC_TOLERANCE = 1e-3)
• Fixed argument_of_periapsis calculation using atan2()

Phase 2 Tests (Hybrid Integration) - Added 2026-02-02:

• test_hybrid_impulse_burns.cpp: Impulsive burn handling with full maneuver system (426 lines, 96 assertions)
• test_hybrid_continuous_thrust.cpp: Continuous thrust integration (565 lines, 40 assertions)
• test_hybrid_energy_conservation.cpp: Analytical vs numerical propagation comparison (810 lines, 89 assertions)

Phase 3 Tests (Edge Cases) - Added 2026-02-02:

• test_extreme_orientation_mixed.cpp: Combined high inclination + high eccentricity (392 lines, 157 assertions)
• test_extreme_timescales.cpp: Orbital period extremes (417 lines, 55 assertions)

Bug Fixes:

• Fixed true_anomaly calculation: corrected formula and added clamping
• Fixed test_extreme_eccentricity config and validation
• Fixed test_newton_raphson_convergence expectations
• Fixed test_analytical_propagation_apsides velocity comparison
• Fixed 3 test design issues in test_analytical_propagation_timesteps
• Fixed test_precision_boundaries Z-coordinate check
• Fixed orbital_elements_to_cartesian circular orbit velocity
• Standardized parabolic detection across codebase
• Fixed near-parabolic numerical instability in eccentric_to_true_anomaly()
• Fixed argument_of_periapsis quadrature ambiguity with atan2()
• Fixed true_anomaly normalization to handle negative values
• Fixed parabolic test design in test_cartesian_to_elements_extreme.cpp

Test Results: All 134 test cases passing (240,299 assertions) - includes all Newton-Raphson validation tests

Remaining Tests (1 file)

14. ✅ test_barkers_equation.cpp: Parabolic propagation (PASSING with 11 tests)

• Purpose: Validate Barker's equation for parabolic orbits (e≈1.0)
• Tests: Parabolic propagation accuracy
• Status: Previously completed, integrated into main test suite

Implementation Priority

Phase 1 (Foundation) ✅ COMPLETE

1. ✅ test_cartesian_to_elements_basic.cpp (round-trip conversion)
2. ✅ test_newton_raphson_convergence.cpp (solver validation)
3. ✅ test_analytical_propagation_apsides.cpp (basic propagation)

Phase 2 (Hybrid Integration) ✅ COMPLETE

4. ✅ test_hybrid_impulse_burns.cpp (impulsive burns)
5. ✅ test_hybrid_continuous_thrust.cpp (continuous burns)
6. ✅ test_hybrid_energy_conservation.cpp (method comparison)

Phase 3 (Edge Cases) ✅ COMPLETE

7. ✅ test_extreme_eccentricity.cpp (e≈1.0)
8. ✅ test_extreme_orientation_mixed.cpp (high inclination + high eccentricity)
9. ✅ test_extreme_timescales.cpp (fast/slow periods)
10. ✅ test_precision_boundaries.cpp (exact values)
11. ✅ test_cartesian_to_elements_extreme.cpp (parabolic test fixed and tolerances tightened)
12. ✅ test_cartesian_to_elements_quadrature.cpp (argument of periapsis fix)
13. ✅ test_analytical_propagation_timesteps.cpp (large/small dt)

Ready for Production Switch

All validation tests are complete and passing. The simulation is ready to switch from RK4 numerical integration to analytical propagation using propagate_orbital_elements().

Burn Handling Workflow Validated ✅

1. Spacecraft starts with orbital elements
2. Convert to Cartesian (orbital_elements_to_cartesian)
3. Apply impulsive burn (modify velocity)
4. Convert back to orbital elements (cartesian_to_orbital_elements)
5. New orbital elements ready for analytical propagation

Key Validation Results

• Burn handling: All burn types, orbit types, and magnitudes validated
• Continuous thrust: Up to 120 burn/conversion cycles without error accumulation
• Energy conservation:
  • Analytical propagation: Zero energy drift (exact conservation)
  • Numerical RK4: 1.7e-07 to 3.6e-03 relative drift depending on orbit type

Next Steps

1. Switch simulation to analytical propagation in src/simulation.cpp
2. Add orbital element conversion after burns in src/maneuver.cpp
3. Test with real-world scenarios (multiple spacecraft, SOI transitions, burns)

Phase 1 (Foundation)

1. ✅ test_cartesian_to_elements_basic.cpp (round-trip conversion)
2. ✅ test_newton_raphson_convergence.cpp (solver validation)
3. ✅ test_analytical_propagation_apsides.cpp (basic propagation)

Phase 2 (Hybrid Integration)

4. ⬜ test_hybrid_impulse_burns.cpp (impulsive burns)
5. ⬜ test_hybrid_continuous_thrust.cpp (continuous burns)
6. ⬜ test_hybrid_energy_conservation.cpp (method comparison)

Phase 3 (Edge Cases)

7. ✅ test_extreme_eccentricity.cpp (e≈1.0)
8. ✅ test_extreme_orientation_mixed.cpp (high inclination + high eccentricity)
9. ✅ test_extreme_timescales.cpp (fast/slow periods)
10. ✅ test_precision_boundaries.cpp (exact values)
11. ✅ test_cartesian_to_elements_extreme.cpp (parabolic test fixed and tolerances tightened)
12. ✅ test_cartesian_to_elements_quadrature.cpp (argument of periapsis fix)
13. ✅ test_analytical_propagation_timesteps.cpp (large/small dt)

Notes

• Each .cpp file requires corresponding .toml config when creating a 2 body system
• SOI transition tests deferred per user requirements
• Test count: 13/13 main test files fully passing ✅ COMPLETE
• Additional test: test_barkers_equation.cpp (parabolic propagation, 11 tests) ✅ COMPLETE
• All Phase 1, 2, and 3 tests complete and passing (240,299 assertions)
• Ready to switch simulation from RK4 to analytical propagation