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: 13-14

Current Progress (2026-01-31)

Completed Tests (6/14 files fully passing)

1. ✅ test_cartesian_to_elements_basic.cpp + .toml

• Status: PASSING (12/12 assertions) - FIXED
• Issue: NaN values in reconstructed radius/velocity
• Fix: Corrected true_anomaly calculation (line 122 in orbital_mechanics.cpp)
  • Changed: r_dot_e / mu → r_dot_e / (r_mag * e_mag)
  • Added: cos(ν) clamping to [-1, 1] before acos()
• Config: Moderate eccentricity (e=0.5), zero inclination
• Tests:
  • Round-trip conversion: orbital elements → state vectors → orbital elements
  • Position/velocity magnitude preservation
  • Semi-major axis, eccentricity accuracy

2. ✅ test_newton_raphson_convergence.cpp (NO CONFIG)

• Status: PASSING (28/28 assertions) - FIXED
• Issue: Low eccentricity (e=0.001) test had incorrect expectations
• Fix: Changed test to verify Kepler's equation satisfaction instead of first-order approximation
  • Verify: |E - e·sin(E) - M| < 1.0e-10
  • Verify: |E - (M + e·sin(M))| < 0.01 (first-order approximation)
• Code changes: Refactored orbital_mechanics.cpp to separate elliptical/hyperbolic solvers
  • Added: solve_kepler_elliptical(), solve_kepler_hyperbolic()
  • Added: eccentric_to_true_anomaly(), hyperbolic_to_true_anomaly()
  • Added: mean_anomaly_to_true_anomaly() unified wrapper
• Config: Programmatically varied parameters
• Tests:
  • Very low eccentricity (e < 0.01): convergence rate verification
  • High eccentricity (0.9 < e < 0.99): iteration count limits
  • Mean anomaly near π: worst-case convergence
  • Large mean anomaly values (M > 1000): periodicity handling
  • Eccentricity at boundaries (e = 0.9999, 1.0001)

3. ✅ test_analytical_propagation_apsides.cpp + .toml

• Status: PASSING (5/5 assertions) - FIXED
• Issue: Test measured velocity at same orbital anomaly (both at ν=0)
• Fix: Changed to measure velocity at ν=π/4, then compare to perigee velocity
  • Before: Both measurements at ν=0 (perigee)
  • After: Measure at ν=π/4, compare to ν=0
• Config: Elliptical orbit (e=0.6, a=2e7)
• Tests:
  • Propagation through perigee (velocity maximum)
  • Propagation through apogee (velocity minimum)
  • At exact orbital period: should return to initial state
  • True anomaly accuracy after full orbit
  • Vis-viva equation holds at multiple points

4. ✅ test_analytical_propagation_timesteps.cpp + .toml

• Status: PASSING (7/7 assertions) - FIXED
• Issues: 3 test design bugs (tolerance, division by zero, 2π wrapping)
• Fixes:
  • Small timestep: Changed to check position error (difference from expected v·dt) instead of absolute position change
  • Division by zero: Added check for expected_pos_error > 1e-6 before calculating relative error
  • 2π wrapping: Added circular angular error calculation using fmin(raw_error, 2π - raw_error)
• Config: Standard orbit (e=0.4, a=1.5e7)
• Tests:
  • Large timesteps: dt > 1 orbit period
  • Very small timesteps: dt < 1 second
  • Accuracy vs. timestep size relationship
  • Mean anomaly accumulation over long propagation

3. ✅ test_extreme_eccentricity.cpp + .toml

• Status: PASSING (28/28 assertions) - FIXED
• Issue: Config validation failing for spacecraft too close to parent
• Fix:
  • Config: Fixed "Near_Parabolic" (e=0.99, a=7.0e8) and "Slightly_Hyperbolic" (e=1.05, a=-1.3e8)
  • Test: Added validation to skip testing ν outside valid range for e>1
    • For e>1: valid ν must satisfy |ν| < arccos(-1/e)
    • For e=1.05: max |ν| ≈ 2.83 rad (162°)
• Code changes: Added validate_true_anomaly_ranges() to config_validator.cpp
  • Checks hyperbolic orbits for true anomaly validity
  • Validates ν is within asymptote boundaries for e>1
• Config: Multiple spacecraft (e=0.99, e=0.95, e=1.05)
• Tests:
  • Numerical stability near e=1.0
  • Hyperbolic solver switching
  • Velocity magnitude accuracy
  • Period calculation (or lack thereof for e≥1)

5. ✅ test_precision_boundaries.cpp + .toml

• Status: PASSING (15/15 assertions) - FIXED
• Issues: 2 bugs (1 test bug, 1 implementation bug)
• Fixes:
  • Test bug: Removed incorrect Z-coordinate check for polar orbit
    • Test expected Z = r·sin(i), which assumes motion along Z-axis
    • Actual position at perigee is on X-axis, so Z=0 is correct
  • Implementation bug: Fixed circular orbit velocity calculation in orbital_elements_to_cartesian()
    • Changed from constant velocity vx=0, vy=v_mag
    • To correct rotating velocity vx=-v·sin(ν), vy=v·cos(ν)
    • Angular momentum now properly conserved (error: 1.2e-14% instead of 41.4%)
• Code changes: Refactored orbital_elements_to_cartesian()
  • Added inline comments for each orbit type (circular/elliptical/parabolic/hyperbolic)
  • Consolidated calculation of semi-latus rectum p before velocity section
  • Reduced velocity calculation from 16 lines to 10 lines
  • Eliminated duplicate p = a·(1-e²) calculation
• Config: Multiple boundary cases (e=0, i=π/2, i=π)
• Tests:
  • Eccentricity at exactly 0
  • Inclination at 0°, 90°, 180°
  • Semi-major axis sign change
  • Angular momentum conservation

Implementation Summary

Code Changes:

• Added to src/orbital_mechanics.h: Function declarations for

  • cartesian_to_orbital_elements(Vec3, Vec3, double)
  • solve_kepler_equation(double, double)
  • get_initial_trial_value(double, double)
  • propagate_orbital_elements(const OrbitalElements&, double, double)
  • Modular API (refactored):
    • solve_kepler_elliptical(double, double)
    • solve_kepler_hyperbolic(double, double)
    • eccentric_to_true_anomaly(double, double)
    • hyperbolic_to_true_anomaly(double, double)
    • mean_anomaly_to_true_anomaly(double, double)

• Added to src/orbital_mechanics.cpp: Full implementations

  • Newton-Raphson solver with 1e-10 tolerance, max 50 iterations
  • Series expansion initial guess: M + e*sin(M) + (e²/2)*sin(2M)
  • Cartesian to orbital elements conversion algorithm
  • Fixed: true_anomaly calculation with proper clamping (line 122)
  • Fixed: circular orbit velocity calculation (line 40-42)
  • Refactored: Separated elliptical/hyperbolic Kepler solvers
  • Refactored: Added inline comments to orbital_elements_to_cartesian()

• Removed from src/test_utilities.h/.cpp: propagate_orbital_elements()

• Added to src/config_validator.cpp:

  • validate_true_anomaly_ranges() - checks hyperbolic anomaly limits
  • TODO comment about parabolic tolerance (0.005 too broad)

Bug Fixes:

1. cartesian_to_orbital_elements() (line 122): Fixed true_anomaly calculation

   • Corrected formula: r_dot_e / (r_mag * e_mag) instead of r_dot_e / mu
   • Added clamping: cos(ν) clamped to [-1, 1] before acos()

2. test_extreme_eccentricity.toml: Fixed spacecraft parameters

   • "Near_Parabolic": e=0.99, a=7.0e8
   • "Slightly_Hyperbolic": e=1.05, a=-1.3e8

3. test_extreme_eccentricity.cpp: Added hyperbolic anomaly validation

   • Skips testing ν=π and 3π/2 for e>1 (outside asymptote boundaries)

4. test_newton_raphson_convergence.cpp: Fixed test expectations

   • Verifies Kepler's equation: |E - e·sin(E) - M| < 1.0e-10
   • Verifies first-order approximation: |E - (M + e·sin(M))| < 0.01

5. test_analytical_propagation_apsides.cpp: Fixed velocity comparison logic

   • Changed: Measure velocity at ν=π/4, compare to perigee velocity at ν=0
   • Before: Both measurements at ν=0 (same anomaly, meaningless comparison)

6. test_analytical_propagation_timesteps.cpp: Fixed 3 test design issues

   • Small timestep: Check position error instead of absolute position change
   • Division by zero: Check expected_pos_error > 1e-6 before calculating relative error
   • 2π wrapping: Use fmin(raw_error, 2π - raw_error) for angular error

7. test_precision_boundaries.cpp: Removed incorrect Z-coordinate check

   • Test expected Z = r·sin(i), which assumes motion along Z-axis
   • Actual position at perigee is on X-axis, so Z=0 is correct

8. orbital_elements_to_cartesian() (line 40-42): Fixed circular orbit velocity

   • Changed from constant velocity vx=0, vy=v_mag
   • To correct rotating velocity vx=-v·sin(ν), vy=v·cos(ν)
   • Angular momentum now properly conserved (1.2e-14% error instead of 41.4%)

Test Results: All 80 tests passing (239,555 assertions)

Recent Commits:

• 9d97934 Fix true anomaly calculation in cartesian_to_orbital_elements()
• a46291a Fix test_extreme_eccentricity to skip invalid hyperbolic true anomalies
• 47f156b Add true anomaly validation for hyperbolic orbits in config validator
• 01e5492 Refactor orbital_mechanics: separate elliptical and hyperbolic Kepler solvers
• 5fc7348 Fix test_analytical_propagation_apsides: measure velocity at different anomaly
• 7471d06 Fix test_analytical_propagation_timesteps: tolerance, division by zero, and 2π wrapping
• acfb47a Fix test_precision_boundaries: remove incorrect Z-coordinate check for polar orbit
• 849a212 Fix orbital_elements_to_cartesian: circular orbit velocity and refactor for clarity
• 986a94e Update test plan: document progress on 3 fixed test files

Remaining Tests (8 files)

7. ⬜ test_cartesian_to_elements_extreme.cpp + .toml

• Purpose: Edge cases in orbital parameters
• Config: Multiple spacecraft in same config
  • Near-circular (e=0.001)
  • Highly eccentric (e=0.99)
  • Equatorial (i<0.001)
  • Polar (i≈π/2)
  • Retrograde (i>π/2)
• Tests:
  • Numerical precision at boundary values
  • Degenerate Ω calculation for equatorial
  • Rotation singularities for polar

8. ⬜ test_cartesian_to_elements_quadrature.cpp + .toml

• Purpose: Test calculations at orbital quadrature points
• Config: Spacecraft at true anomalies: 0, π/2, π, 3π/2
• Tests:
  • Cross product calculations at quadrants
  • Eccentricity vector accuracy
  • Position/velocity vector relationships

9. ⬜ 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.cpp + .toml

• Purpose: 3D orientation edge cases
• Config:
  • Polar orbit (i=90°)
  • Retrograde orbit (i=180°)
  • Mixed: high inclination + high eccentricity
• Tests:
  • Rotation matrix behavior at i=π/2
  • Ω and ω singularity handling
  • Z-coordinate preservation for polar
  • Velocity vector orientation

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)

14. ⬜ test_energy_conservation_analytical.cpp + .toml (OPTIONAL)

• Purpose: Long-term energy conservation validation
• Config: Standard circular/elliptical orbit
• Tests:
  • Energy drift over 10+ orbital periods
  • Kinetic/potential energy consistency
  • Vis-viva equation verification at all anomalies

Phase 1: Core Math Functions

Cartesian to Orbital Elements (3 files)

1. test_cartesian_to_elements_basic.cpp + .toml

• Purpose: Basic round-trip conversion accuracy
• Config: Moderate eccentricity, zero inclination orbit
• Tests:
  • Round-trip conversion: orbital elements → state vectors → orbital elements
  • Position/velocity magnitude preservation
  • Semi-major axis, eccentricity accuracy

2. test_cartesian_to_elements_extreme.cpp + .toml

• Purpose: Edge cases in orbital parameters
• Config: Multiple spacecraft in same config
  • Near-circular (e=0.001)
  • Highly eccentric (e=0.99)
  • Equatorial (i<0.001)
  • Polar (i≈π/2)
  • Retrograde (i>π/2)
• Tests:
  • Numerical precision at boundary values
  • Degenerate Ω calculation for equatorial
  • Rotation singularities for polar

3. test_cartesian_to_elements_quadrature.cpp + .toml

• Purpose: Test calculations at orbital quadrature points
• Config: Spacecraft at true anomalies: 0, π/2, π, 3π/2
• Tests:
  • Cross product calculations at quadrants
  • Eccentricity vector accuracy
  • Position/velocity vector relationships

Newton-Raphson Solver (1-2 files)

4. test_newton_raphson_convergence.cpp + .toml

• Purpose: Verify convergence behavior across eccentricity ranges
• Config: Spacecraft with programmatically varied parameters
• Tests:
  • Very low eccentricity (e < 0.01): convergence rate verification
  • High eccentricity (0.9 < e < 0.99): iteration count limits
  • Mean anomaly near π: worst-case convergence
  • Large mean anomaly values (M > 1000): periodicity handling
  • Eccentricity at boundaries (e = 0.9999, 1.0001)
• Note: Could split to separate config if boundary cases need dedicated config

Analytical Propagation (2 files)

5. test_analytical_propagation_apsides.cpp + .toml

• Purpose: Propagation through orbital apsides
• Config: Elliptical orbit
• Tests:
  • Propagation through perigee (velocity maximum)
  • Propagation through apogee (velocity minimum)
  • At exact orbital period: should return to initial state
  • True anomaly accuracy after full orbit

6. test_analytical_propagation_timesteps.cpp + .toml

• Purpose: Timestep size validation
• Config: Standard orbit
• Tests:
  • Large timesteps: dt > 1 orbit period
  • Very small timesteps: dt < 1 second
  • Accuracy vs. timestep size relationship
  • Mean anomaly accumulation over long propagation

Phase 2: Hybrid Integration

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

8. 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

9. 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

Extreme Orbits (3 files)

10. test_extreme_eccentricity.cpp + .toml

• Purpose: Near-parabolic boundary behavior
• Config:
  • Highly eccentric (e=0.99)
  • Near parabolic (e=0.9999, e=1.0001)
• Tests:
  • Numerical stability near e=1.0
  • Hyperbolic solver switching
  • Velocity magnitude accuracy
  • Period calculation (or lack thereof for e≥1)

11. test_extreme_orientation.cpp + .toml

• Purpose: 3D orientation edge cases
• Config:
  • Polar orbit (i=90°)
  • Retrograde orbit (i=180°)
  • Mixed: high inclination + high eccentricity
• Tests:
  • Rotation matrix behavior at i=π/2
  • Ω and ω singularity handling
  • Z-coordinate preservation for polar
  • Velocity vector orientation

12. 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)

Numerical Precision (1-2 files)

13. test_precision_boundaries.cpp + .toml

• Purpose: Exact boundary value handling
• Config:
  • Perfect circle (e=0)
  • Polar orbit (i=π/2)
  • Retrograde orbit (i=π)
  • Zero/very small radius or velocity
• Tests:
  • Eccentricity at exactly 0
  • Eccentricity at exactly 1 (parabolic)
  • Inclination at 0°, 90°, 180°
  • Semi-major axis sign change
  • Angular momentum conservation
• Note: If energy conservation needs separate config, this becomes 2 files

14. (Optional) test_energy_conservation_analytical.cpp + .toml

• Purpose: Long-term energy conservation validation
• Config: Standard circular/elliptical orbit
• Tests:
  • Energy drift over 10+ orbital periods
  • Kinetic/potential energy consistency
  • Vis-viva equation verification at all anomalies

Overlap Analysis with Existing Tests

Existing Test Coverage Summary

Orbital Parameters Currently Tested:

• Eccentricity: e=0.0 (circular), 0.74 (Molniya), 1.0 (parabolic), 1.5 (hyperbolic)
• Inclination: i=0.0 (equatorial), 1.107 rad (63.4°, Molniya)
• Orbital Periods: 1 day, 10 days, 15.95 days (Titan), 27.3 days (Moon), 60 days, 365 days (Earth), 687 days (Mars), 300-2000 days

Test Scenarios Currently Tested:

• Energy conservation (RK4 only)
• Orbital period measurement
• Prograde/retrograde/normal impulsive burns
• Time-based and true anomaly triggers
• Inclined orbits (Molniya)
• Parabolic and hyperbolic orbits
• Moon orbital stability
• SOI transitions (deferred)
• Root body transitions (deferred)

Overlaps Identified:

test_inclined_orbits.cpp (Molniya: e=0.74, i=63.4°)

• Overlaps: Extreme eccentricity, Extreme orientation
• Gap: Need e=0.99+, retrograde (i>π/2), polar (i=π/2 exactly)

test_moon_orbits.cpp (Moon ~27 day period)

• Overlaps: Extreme timescales
• Gap: Need Mercury-like (~88 days), very slow (>10 years)

test_energy.cpp (circular orbit energy)

• Overlaps: Energy conservation tests
• Gap: Need analytical propagation validation, method comparison

test_orbital_period.cpp (Earth 365 days, Mars 687 days)

• Overlaps: Extreme timescales
• Gap: Need <10 days, ~88 days, >3650 days

test_parabolic_orbit.cpp (e=1.0)

• Overlaps: Extreme eccentricity
• Gap: Need e=0.99, e=0.9999, e=1.0001

test_hyperbolic_orbit.cpp (e=1.5)

• Overlaps: Extreme eccentricity
• Gap: Need e=0.9999 near-parabolic boundary

test_maneuvers.cpp (prograde/retrograde/normal burns)

• Overlaps: Hybrid impulse burns
• Gap: Need continuous thrust, Hohmann sequence, apsides burns

test_maneuver_planning.cpp (time/true anomaly triggers)

• Overlaps: Hybrid impulse burns
• Gap: Need burns at apsides, Hohmann transfer

Config Sharing Opportunities

Can Share Configs (Partial Overlap):

1. test_extreme_eccentricity ↔ test_parabolic_orbit/hyperbolic_orbit

   • Existing: e=1.0, 1.5
   • New: e=0.99, 0.9999, 1.0001
   • May need new config for e=0.99, 0.9999 cases

2. test_hybrid_impulse_burns ↔ test_maneuvers

   • Can reuse burn infrastructure
   • New scenarios require separate config (Hohmann, apsides burns)

3. test_hybrid_energy_conservation ↔ test_energy

   • Different objectives (comparison vs. drift)
   • Could share circular orbit config

Cannot Share Configs (Different Parameters):

1. test_extreme_orientation vs test_inclined_orbits

   • Existing: i=1.107 (63.4°)
   • New: i=π/2 (90°), i>π/2 (retrograde)

2. test_cartesian_to_elements_extreme vs all existing

   • New test category (no existing tests)

Unique New Test Categories

Entirely New Functionality:

1. Cartesian to orbital elements conversion (Phase 1.1) - 3 tests
2. Newton-Raphson solver convergence (Phase 1.2) - 1 test
3. Analytical propagation accuracy (Phase 1.3) - 2 tests
4. Hybrid continuous thrust integration (Phase 2.2) - 1 test
5. Energy comparison: analytical vs. RK4 (Phase 2.3) - 1 test
6. Propagation through apsides - 1 test

New Orbital Regimes: 7. Retrograde orbits (i > 90°) - 1 test 8. Extremely fast orbits (Mercury-like, <100 days) - 1 test 9. Extremely slow orbits (>10 years) - 1 test 10. Boundary values (e=0, i=π/2, i=π) - 1 test

Minimal File Count with Sharing

Current estimate: 13-14 files

Optimization opportunities:

• Combine e=0.99 with parabolic/hyperbolic configs → -1 file
• Share energy config between test_energy and test_hybrid_energy_conservation → -1 file
• Use existing Molniya config for some extreme orientation tests → -1 file

Optimized estimate: ~11 files

Recommended: Keep 13-14 files

• Each test has self-documenting config
• Easier to debug isolated failures
• Config reuse doesn't save much (configs are small)
• Clear separation of concerns

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.cpp (polar/retrograde)
9. test_extreme_timescales.cpp (fast/slow periods)
10. test_precision_boundaries.cpp (exact values)
11. test_cartesian_to_elements_extreme.cpp (edge cases)
12. test_cartesian_to_elements_quadrature.cpp (quadrants)
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