From af1b54bdac7cb19b7788923511fb47f4e0728cf5 Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Sun, 4 Jan 2026 11:33:50 -0500 Subject: [PATCH] Condense and deduplicate project documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reduced redundancy across documentation files: - Condensed implementation_plan.md (236→112 lines) - Condensed test_verification.md (143→62 lines), updated for 4-body test - Condensed config_assumptions.md (115→44 lines), focused on active issues - Removed architecture duplication from CLAUDE.md - Removed common commands from verbose_project_overview.md - Added 'make test' target to Makefile Each file now has a clear, distinct purpose with minimal overlap. 🤖 Generated with Claude Code --- CLAUDE.md | 4 +- Makefile | 6 +- docs/config_assumptions.md | 129 ++++------------ docs/implementation_plan.md | 245 ++++++++----------------------- docs/test_verification.md | 153 +++++-------------- docs/verbose_project_overview.md | 5 - 6 files changed, 132 insertions(+), 410 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 52ea319..ec7425a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,8 @@ ## Architecture - C-style C++ (structs/functions, NO classes/templates) - Raylib (git submodule) for 3D - chose over SFML (no 3D support) -- See docs/implementation_plan.md for full technical design +- See docs/verbose_project_overview.md for detailed technical architecture +- See docs/implementation_plan.md for data structures reference ## Coding Rules - Use .cpp extensions (for future C++ features if needed) @@ -31,5 +32,6 @@ ## Common Commands - Build: make - Run: ./orbit_sim [config_file] +- Test: make test - See README.md for full build instructions diff --git a/Makefile b/Makefile index d2e75b3..95775e8 100644 --- a/Makefile +++ b/Makefile @@ -56,4 +56,8 @@ rebuild: clean all run: $(TARGET) ./$(TARGET) -.PHONY: all clean clean-all rebuild run raylib +# Run test configuration +test: $(TARGET) + ./$(TARGET) configs/test_simple.txt --headless --readable --days 365 + +.PHONY: all clean clean-all rebuild run test raylib diff --git a/docs/config_assumptions.md b/docs/config_assumptions.md index 8d7a868..b558f3e 100644 --- a/docs/config_assumptions.md +++ b/docs/config_assumptions.md @@ -1,114 +1,43 @@ -# Configuration File Assumptions and Issues +# Configuration Issues & Known Bugs -## 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 +## Active TODOs: - ⚠️ **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: +## Fixed Issues: +- ✅ Eccentric orbit support added +- ✅ Binary star barycenter calculation +- ✅ Refactored main.cpp into focused functions +- ✅ Initial state capture in headless mode -### **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 +## Known Issues: -### **2. Solar System Configuration Issues:** +### 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 +**Moon position is incorrect (configs/solar_system.txt)** +- Earth at: `(1.496e11, 0, 0)` m +- Moon at: `(1.500e11, 0, 0)` m +- Distance: ~4M km, should be ~384,400 km (~3.844e8 m) +- Should be at: `(1.496e11 + 3.844e8, 0, 0)` approximately -**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 +**Jupiter's moons positions (configs/solar_system.txt)** +- Io, Europa, Ganymede, Callisto all positioned incorrectly +- Currently use absolute coordinates, should be relative to Jupiter +- Example: Io at `(8.207e11, 0, 0)` - 422M km from Jupiter (should be ~422,000 km) -The moon positions appear to use **absolute coordinates** matching their orbital radii around the Sun, not relative positions around their parent bodies! +### Implementation Notes: -### **3. Binary Star Configuration Issues:** +**Coordinate system**: All positions are absolute (heliocentric), not relative to parent +**Velocity calculation**: Uses vis-viva equation: `v = sqrt(G*M*(2/r - 1/a))` +**Orbit plane**: All orbits calculated in XY plane (Z-axis perpendicular) -**~~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) +## Future Improvements: -**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) +### Validation: +- Add config file validation to warn about incorrectly positioned child bodies +- Check for unrealistic orbital parameters -### **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 +### Features: +- Consider relative coordinate option for child bodies +- Add 3D orbit support (currently all orbits in XY plane) diff --git a/docs/implementation_plan.md b/docs/implementation_plan.md index 725e485..73d18f7 100644 --- a/docs/implementation_plan.md +++ b/docs/implementation_plan.md @@ -1,36 +1,14 @@ -# Orbital Mechanics Simulation - Implementation Plan +# Orbital Mechanics Simulation - Technical Reference -## Project Overview -A 3D orbital mechanics simulation using 2-body gravitational model with sphere of influence (SOI) transitions. Real-time visualization of the solar system (Sun, planets, moons) using raylib with C-style C++. +## Overview +3D orbital mechanics simulation using 2-body gravitational model with sphere of influence (SOI) transitions. Built with C-style C++ and raylib. ## Technical Constraints - C-style C++ only: structs and functions, no classes or templates -- Small, focused functions -- Simple rotations (Euler angles / axis-angle) - quaternions deferred for later - Euler integration for physics +- Simple rotations (quaternions deferred) - raylib for 3D visualization -## Project Structure - -``` -claudes_game/ -├── src/ -│ ├── main.cpp -│ ├── physics.cpp -│ ├── physics.h -│ ├── bodies.cpp -│ ├── bodies.h -│ ├── renderer.cpp -│ ├── renderer.h -│ ├── config_loader.cpp -│ └── config_loader.h -├── configs/ -│ ├── solar_system.txt -│ └── example_binary_star.txt -├── Makefile -└── README.md -``` - ## Core Data Structures ### Vec3 (physics.h) @@ -46,11 +24,13 @@ struct CelestialBody { char name[64]; double mass; // kg double radius; // meters - Vec3 position; // meters from solar system origin + Vec3 position; // meters from origin Vec3 velocity; // m/s double soi_radius; // sphere of influence radius (meters) - int parent_index; // index of gravitational parent (-1 for Sun) + int parent_index; // index of gravitational parent (-1 for root) float color[3]; // RGB for rendering + double eccentricity; // orbital eccentricity (0 = circular) + double semi_major_axis; // meters }; ``` @@ -59,177 +39,70 @@ struct CelestialBody { struct SimulationState { CelestialBody* bodies; int body_count; + int max_bodies; double time; // simulation time (seconds) double dt; // time step (seconds) }; ``` -## Key Components - -### 1. Physics Module (physics.c/h) -**Functions:** -- `Vec3 vec3_add(Vec3 a, Vec3 b)` - vector addition -- `Vec3 vec3_sub(Vec3 a, Vec3 b)` - vector subtraction -- `Vec3 vec3_scale(Vec3 v, double s)` - scalar multiplication -- `double vec3_magnitude(Vec3 v)` - vector length -- `double vec3_distance(Vec3 a, Vec3 b)` - distance between points -- `Vec3 vec3_normalize(Vec3 v)` - unit vector -- `Vec3 calculate_gravity_force(CelestialBody* body, CelestialBody* parent)` - 2-body force -- `Vec3 calculate_acceleration(Vec3 force, double mass)` - F = ma -- `void euler_step(CelestialBody* body, Vec3 acceleration, double dt)` - Euler integration - -### 2. Bodies Module (bodies.c/h) -**Functions:** -- `SimulationState* create_simulation(int max_bodies)` - allocate simulation -- `void destroy_simulation(SimulationState* sim)` - cleanup -- `void add_body(SimulationState* sim, const char* name, double mass, double radius, Vec3 pos, Vec3 vel, float r, float g, float b)` - add celestial body -- `int find_dominant_body(SimulationState* sim, int body_index)` - determine which body has gravitational dominance -- `void update_soi(CelestialBody* body, CelestialBody* parent)` - calculate sphere of influence radius -- `void update_simulation(SimulationState* sim)` - single time step update - -**SOI Calculation:** -Using Hill sphere approximation: `r_soi = a * (m/M)^(2/5)` -where a = semi-major axis, m = body mass, M = parent mass - -### 3. Config Loader Module (config_loader.cpp/h) -**Functions:** -- `bool load_system_config(SimulationState* sim, const char* filepath)` - load bodies from config file -- `bool parse_body_line(const char* line, CelestialBody* body)` - parse single body definition -- `void calculate_initial_velocities(SimulationState* sim)` - compute circular orbit velocities from positions - -**Config File Format (simple text):** -``` -# Comment lines start with # -# Format: name mass(kg) radius(m) x(m) y(m) z(m) parent_index r g b -Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0 -Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0 -Moon 7.342e22 1.737e6 1.4996e11 0 0 1 0.7 0.7 0.7 -# Velocity is calculated automatically for circular orbits -``` - -**Example configs to provide:** -- `configs/solar_system.txt` - Our solar system with Sun, 8 planets, major moons -- `configs/example_binary_star.txt` - Binary star system with planets - -### 4. Renderer Module (renderer.c/h) -**Functions:** -- `void init_renderer(int width, int height, const char* title)` - initialize raylib window -- `void setup_camera(Camera3D* camera)` - configure 3D camera -- `void render_body(CelestialBody* body, double scale)` - draw sphere for body -- `void render_simulation(SimulationState* sim, Camera3D* camera)` - render all bodies -- `void draw_orbit_trail(Vec3* positions, int count, Color color)` - draw orbit path (future enhancement) -- `void close_renderer()` - cleanup raylib - -**Rendering approach:** -- Use logarithmic scaling for distances (solar system is huge) -- Use exponential scaling for body sizes (make small bodies visible) -- Simple camera controls (rotate around Sun, zoom in/out) -- Display FPS and simulation time - -### 5. Main Loop (main.cpp) +### RenderState (renderer.h) ```cpp -1. Parse command line arguments (config file path, default to configs/solar_system.txt) -2. Initialize raylib window and camera -3. Create simulation and load system from config file -4. Main loop: - a. Handle input (camera controls, pause/resume, speed adjustment) - b. Update physics (multiple sub-steps per frame for stability) - c. Check for SOI transitions - d. Render scene - e. Update camera -5. Cleanup and exit +struct RenderState { + Camera3D camera; + double distance_scale; // Scale factor for distances + double size_scale; // Scale factor for body sizes + bool show_info; // Display simulation info +}; ``` -## Implementation Steps - -### Phase 1: Foundation -1. Create project structure and Makefile -2. Implement Vec3 and basic vector math functions (physics.c/h) -3. Define CelestialBody and SimulationState structs (bodies.h) -4. Create basic simulation functions (create, destroy, add_body) - -### Phase 2: Physics Core -5. Implement 2-body gravity calculation -6. Implement Euler integration step -7. Implement SOI detection and parent switching logic -8. Create update_simulation() function - -### Phase 3: Config Loading System -9. Implement config file parser (parse_body_line, skip comments/empty lines) -10. Implement load_system_config() to read and populate simulation -11. Create configs/solar_system.txt with our solar system data -12. Implement calculate_initial_velocities() for circular orbits -13. Calculate SOI radii for all bodies after loading - -### Phase 4: Visualization -14. Initialize raylib window and 3D camera -15. Implement render_body() with scaling -16. Implement render_simulation() to draw all bodies -17. Add basic camera controls (orbital rotation, zoom) - -### Phase 5: Integration and Refinement -18. Integrate rendering with physics loop in main.cpp -19. Add command line argument parsing for config file selection -20. Add time scaling controls (speed up/slow down simulation) -21. Add pause/resume functionality -22. Display simulation info (time, FPS, body count, current config) -23. Create example_binary_star.txt config for testing -24. Test and tune time step for stability - -## Technical Notes +## Module Overview -### Config File System Benefits -- **Flexibility**: Easily create any star system without recompiling -- **Testing**: Quickly test different scenarios (binary stars, close encounters, etc.) -- **Sharing**: Users can share interesting system configurations -- **Debugging**: Simplified test cases with just 2-3 bodies -- **Education**: Learn about different orbital configurations by experimenting +### Physics (physics.cpp/h) +Vector math and gravity calculations. Euler integration with `euler_step()`. -### Scaling for Visualization -- **Distance scale**: Use logarithmic or power-law scaling (e.g., `display_pos = sign(pos) * pow(abs(pos), 0.3)`) -- **Size scale**: Make minimum visible radius (e.g., max(actual_radius * scale, min_visible_radius)) -- Keep Sun at origin for simplicity +### Bodies (bodies.cpp/h) +Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)` -### Time Step Considerations -- Solar system scale requires small time steps (try dt = 60 seconds initially) -- May need multiple physics updates per render frame -- Allow user to adjust simulation speed multiplier +### Config Loader (config_loader.cpp/h) +Text-based config parser. Auto-calculates circular orbit velocities and SOI radii. -### SOI Transition Logic +**Config format:** ``` -For each body (except Sun): - 1. Calculate distance to current parent - 2. Calculate distance to all other potential parents - 3. Check if body is within SOI of a different parent - 4. If yes, switch parent_index and recalculate relative state +# name mass(kg) radius(m) x(m) y(m) z(m) parent_index r g b +Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0 +Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0 ``` -### Initial Conditions -- Use Keplerian orbital elements or simplified circular orbits -- Ensure velocity is perpendicular to position vector for circular orbits -- Circular orbit velocity: v = sqrt(G * M / r) - -## Files to Create -1. `src/physics.h` - Vector math and physics declarations -2. `src/physics.cpp` - Vector math and physics implementations -3. `src/bodies.h` - Body and simulation data structures -4. `src/bodies.cpp` - Body management and simulation update -5. `src/config_loader.h` - Config file parsing declarations -6. `src/config_loader.cpp` - Config file loading implementation -7. `src/renderer.h` - Rendering declarations -8. `src/renderer.cpp` - raylib rendering implementation -9. `src/main.cpp` - Main loop and program entry -10. `configs/solar_system.txt` - Our solar system configuration -11. `configs/example_binary_star.txt` - Example binary star system -12. `Makefile` - Build configuration -13. `README.md` - Project documentation and config format docs - -## Future Enhancements (Not in Initial Implementation) -- Quaternion-based rotations -- Orbit trail rendering -- N-body simulation mode -- Patched conic approximation -- More accurate integration (RK4, Verlet) -- Save/load simulation state -- Interactive body selection and info display +### Renderer (renderer.cpp/h) +Raylib 3D visualization with logarithmic distance scaling and size scaling for visibility. + +## Implementation Status + +### ✅ Completed +- Phase 1-4: Core physics, simulation, config loading, and rendering +- Raylib integration with 3D camera +- Distance and size scaling for visualization +- Config file system with solar_system.txt + +### 🔨 Remaining/Future Work +- Time scaling controls (speed up/slow down) +- Pause/resume functionality +- Additional config files (binary star, etc.) +- Time step tuning for stability + +## Technical Notes + +### Scaling for Visualization +- Distance: logarithmic/power-law scaling for solar system scale +- Size: minimum visible radius to prevent tiny bodies from disappearing +- Origin at Sun for simplicity + +### Physics Considerations +- Timestep: ~60 seconds for solar system scale +- Circular orbit velocity: `v = sqrt(G * M / r)` +- May need multiple physics sub-steps per render frame + +## Future Enhancements +- More accurate integration (RK4, Verlet), NOTE: try Newton-Raphson propagation method with testing first +- Interactive body selection - Reference frame switching diff --git a/docs/test_verification.md b/docs/test_verification.md index ebcab7d..9a53f67 100644 --- a/docs/test_verification.md +++ b/docs/test_verification.md @@ -1,142 +1,61 @@ -# Test Case Verification Guide +# Test Verification Guide -This document explains how to verify the orbital simulation using the `test_simple.txt` configuration. +Quick reference for testing orbital mechanics using `configs/test_simple.txt`. -## Running the Test +## Test Command ```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: +## Test Bodies -``` -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 -``` +- **Sun**: Origin (0, 0, 0) +- **Earth**: 1.0 AU, circular orbit (e=0), period ~365 days +- **Mars**: 1.5 AU, circular orbit (e=0), period ~687 days +- **Comet**: 2.5 AU semi-major axis, eccentric orbit (e=0.7), period ~1444 days + - Starts at perihelion (0.75 AU) + - Aphelion at 4.25 AU -### Full Orbit (Day ~365) -After approximately 1 full Earth year: +All orbit counter-clockwise (viewed from +Z). -``` -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 -``` +## Expected Behavior -## How to Verify +**Circular orbits (Earth, Mars):** +- Distance from Sun remains constant +- Velocity magnitude remains constant + - Earth: ~29.8 km/s + - Mars: ~24.3 km/s +- Return to starting position after full period -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 +**Eccentric orbit (Comet):** +- Distance varies: 0.75 AU (perihelion) to 4.25 AU (aphelion) +- Velocity varies: faster at perihelion, slower at aphelion +- Period ~1444 days -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 +## Quick Tests ```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) +# Earth full orbit ./orbit_sim configs/test_simple.txt --headless --readable --days 365 -# Run for Mars' full orbit (687 days) +# Mars full orbit ./orbit_sim configs/test_simple.txt --headless --readable --days 687 + +# Comet full orbit (eccentric) +./orbit_sim configs/test_simple.txt --headless --readable --days 1444 ``` ## 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 +Due to Euler integration with dt=60s: +- Distance variation: ±0.001 AU +- Velocity variation: ±0.1 km/s +- Position after full orbit: Within 0.01 AU of start -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 +## Output Flags -Without `--readable`, all values are in SI units (meters, m/s) with scientific notation. +- `--headless`: Terminal output only (no GUI) +- `--readable`: Human-friendly units (AU, km/s) instead of SI (m, m/s) +- `--days N`: Simulation duration in days diff --git a/docs/verbose_project_overview.md b/docs/verbose_project_overview.md index 6617230..c7b31fd 100644 --- a/docs/verbose_project_overview.md +++ b/docs/verbose_project_overview.md @@ -6,11 +6,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co A 3D orbital mechanics simulation using a 2-body gravitational model with sphere of influence (SOI) transitions. The simulation features real-time visualization using raylib and supports configurable star systems via text files. -## Common Commands - - Build: make - - Run: ./orbit_sim [config_file] - - See README.md for full build instructions - ## Architecture ### Code Style