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