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 estimated test files: 11 (reduced from 14 after overlap analysis)

Current Progress (2026-01-31)

Completed Tests (8/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)

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()

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 93 tests passing (239,872 assertions) - includes 11 Barker's equation tests

Remaining Tests (5 files)

1. ⬜ test_hybrid_impulse_burns.cpp + .toml

• Purpose: Impulsive burn handling
• Config: Spacecraft with pre-configured maneuvers
• Tests:
  • Hohmann transfer (2 burns)
  • Plane change at nodes (inclination change only)
  • Impulsive burns at apsides (perigee/apogee)
  • Minimal burns (Δv < 1 m/s)
  • Large burns (Δv > orbital velocity)

10. ⬜ test_hybrid_continuous_thrust.cpp + .toml

• Purpose: Continuous thrust integration
• Config: Spacecraft with finite-duration burns
• Tests:
  • Continuous low-thrust burns (ion engines)
  • Multi-burn sequences
  • Numerical vs. analytical mode transitions
  • Energy conservation during burns

11. ⬜ test_hybrid_energy_conservation.cpp + .toml

• Purpose: Compare analytical vs. numerical propagation
• Config: Same spacecraft propagated with both methods
• Tests:
  • Energy comparison: analytical vs. RK4
  • Pre/post burn energy validation
  • Long-term energy drift comparison

12. ⬜ test_extreme_orientation_mixed.cpp + .toml

• Purpose: Combined high inclination + high eccentricity
• Config:
  • High inclination (i>π/3) + high eccentricity (e>0.8)
• Tests:
  • Rotation matrix behavior at extreme combinations
  • Ω and ω singularity handling
  • Velocity vector orientation
  • NOTE: Removed duplicate polar/retrograde tests (covered by test_precision_boundaries)

13. ⬜ test_extreme_timescales.cpp + .toml

• Purpose: Orbital period extremes
• Config:
  • Mercury-like orbiter (period ~88 days)
  • Very long period orbit (period > 10 years)
  • Very low perigee (altitude < 100 km)
  • Super-synchronous orbit
• Tests:
  • Fast orbits: numerical precision challenges
  • Slow orbits: mean anomaly accumulation
  • Low altitude: atmospheric boundary (if applicable)
  • Long-duration propagation (10+ periods)

Phase 1: Core Math Functions

Cartesian to Orbital Elements (3 files)

1. ✅ test_cartesian_to_elements_basic.cpp + .toml: Basic round-trip conversion accuracy

7. ✅ test_cartesian_to_elements_extreme.cpp + .toml: Parabolic test fixed and tolerances tightened

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

Newton-Raphson Solver (1 file)

2. ✅ test_newton_raphson_convergence.cpp (NO CONFIG): Convergence behavior across eccentricity ranges

Analytical Propagation (2 files)

3. ✅ test_analytical_propagation_apsides.cpp + .toml: Propagation through orbital apsides

4. ✅ test_analytical_propagation_timesteps.cpp + .toml: Timestep size validation

Phase 2: Hybrid Integration

1. ⬜ test_hybrid_impulse_burns.cpp + .toml: Impulsive burn handling

2. ⬜ test_hybrid_continuous_thrust.cpp + .toml: Continuous thrust integration

3. ⬜ test_hybrid_energy_conservation.cpp + .toml: Analytical vs. numerical propagation comparison

Extreme Orbits (3 files)

5. ✅ test_extreme_eccentricity.cpp + .toml: Near-parabolic boundary behavior

4. ⬜ test_extreme_orientation_mixed.cpp + .toml: Combined high inclination + high eccentricity

5. ⬜ test_extreme_timescales.cpp + .toml: Orbital period extremes

Numerical Precision (1 file)

6. ✅ test_precision_boundaries.cpp + .toml: Exact boundary value handling

Implementation Priority

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

• Config files are shared with existing tests where possible
• Each .cpp file requires corresponding .toml config
• Some test categories can share configs if parameters align
• SOI transition tests deferred per user requirements
• Test count: 10/14 files fully passing (8/14 previously plus 2 new cartesian_to_elements tests)
• Additional test added: test_barkers_equation.cpp (parabolic propagation, 11 tests)