# Configuration File Assumptions and Issues

## Recent Updates:
- ✅ **FIXED**: Eccentric orbit support added via eccentricity and semi_major_axis parameters
- ✅ **FIXED**: Binary star barycenter calculation
- ✅ **FIXED**: Refactored main.cpp into focused functions (parse args, run_headless, run_gui)
- ✅ **FIXED**: Added initial state capture in headless mode for comparison with final state
- ⚠️ **TODO**: Update configs/solar_system.txt to new 12-field format
- ⚠️ **TODO**: Update configs/example_binary_star.txt to new 12-field format
- ⚠️ **TODO**: Fix Moon and Jupiter's moons positions in solar_system.txt

## Key Assumptions Found:

### **1. Format Assumptions (from config_loader.cpp)**
- Line buffer limited to 256 characters (config_loader.cpp:39)
- Name limited to 64 characters (config_loader.cpp:40)
- All 12 fields must be present: `name mass radius x y z parent_index r g b eccentricity semi_major_axis` (config_loader.cpp:16-20)
- File format is space-delimited

### **2. Solar System Configuration Issues:**

**Problem 1: Moon position is incorrect**
- Earth is at: `(1.496e11, 0, 0)` m
- Moon is at: `(1.500e11, 0, 0)` m
- Distance: ~4 million km, but Earth-Moon distance should be ~384,400 km (~3.844e8 m)
- The Moon should be at approximately `(1.496e11 + 3.844e8, 0, 0)` or similar

**Problem 2: Jupiter's moons positions**
- Jupiter is at: `(7.785e11, 0, 0)` m
- Io is at: `(8.207e11, 0, 0)` m - **422 million km from Jupiter** (should be ~422,000 km = 4.22e8 m)
- Europa is at: `(8.456e11, 0, 0)` m - **671 million km from Jupiter** (should be ~671,000 km = 6.71e8 m)
- Ganymede/Callisto have similar issues

The moon positions appear to use **absolute coordinates** matching their orbital radii around the Sun, not relative positions around their parent bodies!

### **3. Binary Star Configuration Issues:**

**~~Problem 1: Both stars have parent_index = -1~~ - FIXED**
- StarA: `parent_index = -1`
- StarB: `parent_index = -1`
- ~~This means both are treated as root bodies with zero velocity (config_loader.cpp:69)~~
- ~~They won't orbit each other!~~
- **FIXED**: System now detects multiple root bodies, calculates barycenter, and sets appropriate orbital velocities (config_loader.cpp:64-146, bodies.cpp:101-124)

**Problem 2: Planet positions**
- PlanetA1 is at `(3.5e11, 0, 0)` while StarA is at `(3.0e11, 0, 0)` - only 50 million km apart
- PlanetB1 is at `(-4.2e11, 0, 0)` while StarB is at `(-3.7e11, 0, 0)` - only 50 million km apart
- These seem reasonable as absolute positions (now supports both circular and eccentric orbits)

### **4. Velocity Calculation Assumptions (config_loader.cpp:78-245):**
- ~~All orbits are assumed to be **circular**~~ - **FIXED**: Now supports both circular (e=0) and eccentric (e>0) orbits
- Velocities calculated using **vis-viva equation**: `v = sqrt(G*M*(2/r - 1/a))`
  - For circular orbits: e=0, a=orbital_radius
  - For eccentric orbits: e>0, a=semi_major_axis
- Orbits are calculated in the XY plane perpendicular to Z-axis (config_loader.cpp:219-226)
- Root bodies (parent_index = -1) get zero velocity (or orbit barycenter if multiple roots)
- Velocities are calculated relative to parent, then parent's velocity is added

### **5. Critical Assumption:**
The code assumes **positions are absolute (heliocentric)**, but for child bodies like moons, the **positions in the config should be relative to their parent**. This is not clearly documented and appears inconsistent!

## Recommended Actions:

### High Priority:
1. **Update config files to new format** - All config files need to be updated to 12-field format
   - ⚠️ `configs/solar_system.txt` - Still uses old 10-field format
   - ⚠️ `configs/example_binary_star.txt` - Still uses old 10-field format
   - ✅ `configs/test_simple.txt` - Already updated

2. **Fix moon positions** - Moon and Jupiter's moons use incorrect absolute coordinates
   - Moon should be at ~(1.496e11 + 3.844e8, 0, 0) not (1.500e11, 0, 0)
   - Jupiter's moons should be relative to Jupiter's position

### Medium Priority:
3. **Add config file validation** - Warn when child bodies seem incorrectly positioned
4. **Document coordinate system** - Clarify that positions are absolute (heliocentric)

### Low Priority:
5. **Consider relative coordinate option** - Allow specifying child positions relative to parent
6. **Add 3D orbit support** - Currently all orbits are in XY plane

---

## Session Notes (2026-01-03):

### Changes Made:
1. **Refactored main.cpp** - Broke 215-line main() into focused functions:
   - `parse_command_line_args()` - Parse command line arguments into ProgramArgs struct
   - `print_startup_info()` - Print simulation configuration
   - `run_headless_simulation()` - Terminal-based simulation with initial/final state capture
   - `run_gui_simulation()` - 3D visualization mode
   - Main function now ~25 lines of setup and dispatch

2. **Added eccentric orbit support**:
   - Extended config format from 10 to 12 fields (added eccentricity, semi_major_axis)
   - Implemented vis-viva equation: `v = sqrt(G*M*(2/r - 1/a))`
   - Circular orbits: e=0, a=orbital_radius
   - Elliptical orbits: e>0, a=semi_major_axis
   - Renamed `calculate_initial_velocities_with_params()` → `calculate_velocities()`

3. **Updated test_simple.txt**:
   - Added Comet with highly eccentric orbit (e=0.7, a=2.5 AU)
   - Perihelion: 0.75 AU, Aphelion: 4.25 AU
   - Successfully tested - comet swings from 0.75 AU to ~3.8 AU

4. **Documentation updates**:
   - Updated README.md with new 12-field format and examples
   - Updated this file with fixed issues and TODOs
   - Added eccentric orbit feature to feature list

### Known Issues:
- **Old config files** still use 10-field format and need updating
- **Moon positions** in solar_system.txt are physically incorrect
- **No validation** for unrealistic body positions