diff --git a/docs/test_verification.md b/docs/test_verification.md new file mode 100644 index 0000000..ebcab7d --- /dev/null +++ b/docs/test_verification.md @@ -0,0 +1,142 @@ +# Test Case Verification Guide + +This document explains how to verify the orbital simulation using the `test_simple.txt` configuration. + +## Running the Test + +```bash +# Build the simulation +make + +# Run the simple test case with human-readable output +./orbit_sim configs/test_simple.txt --headless --readable --days 365 +``` + +## Test Configuration + +The `configs/test_simple.txt` file contains: +- **Sun**: At the origin (0, 0, 0), mass 1.989e30 kg +- **Earth**: Starts at 1.0 AU on the +X axis, mass 5.972e24 kg +- **Mars**: Starts at 1.5 AU on the +X axis, mass 6.39e23 kg + +Both planets orbit in circular paths in the XY plane (counter-clockwise when viewed from +Z). + +## Expected Orbital Periods + +Using Kepler's third law: T² ∝ a³ (where T is period, a is semi-major axis) + +- **Earth**: T = 365.25 days (by definition) +- **Mars**: T = 686.98 days (approximately 687 days) + +## Expected Velocities + +Circular orbit velocity: v = sqrt(G * M_sun / r) + +- **Earth**: v = 29.789 km/s +- **Mars**: v = 24.323 km/s + +## Verification Points + +### Initial State (Day 0) +``` +Earth: + Position: (1.0, 0.0, 0.0) AU + Velocity: (0.0, -29.789, 0.0) km/s + +Mars: + Position: (1.5, 0.0, 0.0) AU + Velocity: (0.0, -24.323, 0.0) km/s +``` + +### Quarter Orbit (Day ~91) +After approximately 1/4 of Earth's year: + +``` +Earth: + Expected Position: (~0.0, -1.0, 0.0) AU + Expected Velocity: (~-29.789, 0.0, 0.0) km/s + Distance: ~1.0 AU (circular orbit) + +Mars: + Expected Position: (~0.987, -1.129, 0.0) AU (only traveled ~57 degrees) + Distance: ~1.5 AU (circular orbit) +``` + +### Half Orbit (Day ~183) +After approximately 1/2 of Earth's year: + +``` +Earth: + Expected Position: (~-1.0, 0.0, 0.0) AU + Expected Velocity: (0.0, 29.789, 0.0) km/s + Distance: ~1.0 AU + +Mars: + Expected Position: (~0.72, -1.30, 0.0) AU (traveled ~114 degrees) + Distance: ~1.5 AU +``` + +### Full Orbit (Day ~365) +After approximately 1 full Earth year: + +``` +Earth: + Expected Position: (~1.0, 0.0, 0.0) AU (back to start) + Expected Velocity: (0.0, -29.789, 0.0) km/s + Distance: ~1.0 AU + +Mars: + Expected Position: (~-0.87, -1.23, 0.0) AU (traveled ~228 degrees) + Distance: ~1.5 AU +``` + +## How to Verify + +1. **Check orbital stability**: The distance from the Sun should remain constant + - Earth should stay at ~1.0 AU + - Mars should stay at ~1.5 AU + +2. **Check velocity magnitude**: Speed should remain constant in circular orbits + - Earth: always ~29.789 km/s + - Mars: always ~24.323 km/s + +3. **Check orbital period**: Run for 365 days + - Earth should return to near its starting position + - Mars should complete about half its orbit (687 day period) + +4. **Check direction**: Both planets orbit counter-clockwise + - Starting at +X axis + - Moving in -Y direction + - Position angle increases over time + +## Quick Test Commands + +```bash +# Run for a quarter year (91 days) +./orbit_sim configs/test_simple.txt --headless --readable --days 91 + +# Run for a half year (183 days) +./orbit_sim configs/test_simple.txt --headless --readable --days 183 + +# Run for a full year (365 days) +./orbit_sim configs/test_simple.txt --headless --readable --days 365 + +# Run for Mars' full orbit (687 days) +./orbit_sim configs/test_simple.txt --headless --readable --days 687 +``` + +## Acceptable Tolerances + +Due to numerical integration with discrete time steps: +- Distance variation: ±0.001 AU (~150,000 km) is acceptable +- Velocity variation: ±0.1 km/s is acceptable +- Position after full orbit: Within 0.01 AU of starting position + +## Understanding the Output + +The `--readable` flag converts output to human-friendly units: +- **Positions**: Shown in AU (Astronomical Units, ~150 million km) +- **Velocities**: Shown in km/s +- **Distances**: Shown in both AU and km + +Without `--readable`, all values are in SI units (meters, m/s) with scientific notation.