claudes_game/docs/test_verification.md

Test Case Verification Guide

This document explains how to verify the orbital simulation using the test_simple.txt configuration.

Running the Test

# 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

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