# joeeliang/3-body-problem architecture

> Architecture diagram of the GitHub repository joeeliang/3-body-problem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joeeliang/3-body-problem
- Repository: https://github.com/joeeliang/3-body-problem

## Overview

##### Project type and purpose
- This is a scientific simulation tool (three‐body gravitational problem) that combines Python for orchestration and C++ for high‐performance computation. It simulates trajectories, computes the Lyapunov (proximity) function, stores results, and generates visualizations.

##### File structure
- Top‐level scripts:
- main.py – entry point that triggers the overall workflow
- system.py – orchestrates data flow between modules
- visualization.py – produces plots or animations
- utils.py – helper functions for file I/O, parameter parsing, etc.
- logicCode/ (heavy computation):
- normalprocessing.cpp – core C++ routines for integration and proximity computation
- pythonVersion.py – pure‐Python fallback implementation or prototype
- long_double.cpp – extended‐precision C++ routines (possibly used by normalprocessing.cpp)
- data/ – static CSV inputs (initial positions, parameter scans) and outputs (cut_positions.csv, fullMap.csv, zoom.csv)
- app/ – packaging or execution scripts (could hold CLI wrappers or config templates)
- requirements.txt – Python dependencies

##### README for additional insights
- Confirms dual‐language approach (Python + C++) for speed and flexibility
- Periodic orbits and chaotic behavior via Lyapunov exponent

##### Components
a. Frontend/orchestration layer (Python scripts)
- main.py
- system.py
- utils.py
b. Compute engine
- C++ modules (normalprocessing.cpp + long_double.cpp)
- Python fallback (logicCode/pythonVersion.py)
c. Data layer
- Input CSVs in data/
- Output CSVs generated at runtime
d. Visualization layer
- visualization.py
e. External/Infrastructure
- Python interpreter + required libraries (from requirements.txt)
- C++ compiler toolchain
- File system (for reading/writing CSVs)

##### Relationships and data flow
- main.py loads configuration (from utils) → invokes system.py
- system.py reads input CSVs → passes parameters to the compute engine
- Compute engine (via a Python → C++ binding or subprocess) runs simulation and proximity calculations → writes results back to data/
- visualization.py reads computed CSVs → generates plots/animations → writes to disk or displays
- If C++ binaries are unavailable, system.py falls back to logicCode/pythonVersion.py

##### Architectural patterns and design principles
- Layered architecture: clear separation between orchestration, computation, data persistence, and visualization
- Polyglot strategy: high‐performance C++ core wrapped by a Python “glue” layer for ease of use
- Single responsibility: each module handles one concern (I/O, computation, plotting)
- Extensibility point: logicCode/pythonVersion.py can be extended for new algorithms; app/ can hold CLI or GUI frontends

- Enumerate all modules and their interfaces
- Python‐to‐C++ invocation mechanism (binding or subprocess)
- Data files directory as a persistent store
- External requirements (Python libs, compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        main["main.py"]:::python
        system["system.py"]:::python
        utils["utils.py"]:::python
    end

    %% Compute Engine
    subgraph "Compute Engine"
        subgraph "C++ Core"
            normal["normalprocessing.cpp"]:::cpp
            longdouble["long_double.cpp"]:::cpp
        end
        pythonFB["pythonVersion.py"]:::python
    end

    %% Data Layer
    subgraph "Data Layer"
        dataIn["positions.csv"]:::data
        cutPos["cut_positions.csv"]:::data
        fullMap["fullMap.csv"]:::data
        zoom["zoom.csv"]:::data
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        viz["visualization.py"]:::python
    end

    %% External Dependencies
    subgraph "External/Infrastructure"
        pyInterp["Python Interpreter & Libraries"]:::external
        cppTool["C++ Compiler Toolchain"]:::external
        fs["File System (CSV I/O)"]:::external
    end

    %% Data Flows
    pyInterp -->|"executes"| main
    main -->|"invokes"| system
    system -->|"reads parameters & CSVs"| dataIn
    system -->|"calls C++ core"| normal
    system -->|"calls extended precision"| longdouble
    system -->|"fallback to Python"| pythonFB
    normal -->|"writes results"| cutPos
    normal -->|"writes results"| fullMap
    normal -->|"writes results"| zoom
    pythonFB -->|"writes results"| cutPos
    pythonFB -->|"writes results"| fullMap
    pythonFB -->|"writes results"| zoom
    viz -->|"reads results"| cutPos
    viz -->|"reads results"| fullMap
    viz -->|"reads results"| zoom
    viz -->|"outputs plots"| fs
    cppTool -->|"builds"| normal
    cppTool -->|"builds"| longdouble

    system -->|"uses utilities"| utils

    %% Click Events
    click main "https://github.com/joeeliang/3-body-problem/blob/main/main.py"
    click system "https://github.com/joeeliang/3-body-problem/blob/main/system.py"
    click utils "https://github.com/joeeliang/3-body-problem/blob/main/utils.py"
    click viz "https://github.com/joeeliang/3-body-problem/blob/main/visualization.py"
    click normal "https://github.com/joeeliang/3-body-problem/blob/main/logicCode/normalprocessing.cpp"
    click longdouble "https://github.com/joeeliang/3-body-problem/blob/main/long_double.cpp"
    click pythonFB "https://github.com/joeeliang/3-body-problem/blob/main/logicCode/pythonVersion.py"
    click dataIn "https://github.com/joeeliang/3-body-problem/blob/main/data/positions.csv"
    click cutPos "https://github.com/joeeliang/3-body-problem/blob/main/data/cut_positions.csv"
    click fullMap "https://github.com/joeeliang/3-body-problem/blob/main/data/fullMap.csv"
    click zoom "https://github.com/joeeliang/3-body-problem/blob/main/data/zoom.csv"
    click app "https://github.com/joeeliang/3-body-problem/tree/main/app/"
    click req "https://github.com/joeeliang/3-body-problem/blob/main/requirements.txt"

    %% Styles
    classDef python fill:#D0E6FF,stroke:#0366D6,stroke-width:2px
    classDef cpp fill:#E6FFDD,stroke:#22863A,stroke-width:2px
    classDef data fill:#FFF5B1,stroke:#D4A72C,stroke-width:2px
    classDef external fill:#EDEDED,stroke:#949494,stroke-width:2px
```
