# hannorein/rebound architecture

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

- Interactive diagram: https://gitdiagram.com/hannorein/rebound
- Repository: https://github.com/hannorein/rebound

## Overview

##### Project Type and Purpose
- REBOUND is an open-source N-body integrator library written in ISO C99 with a Python wrapper and browser/WebGL/emscripten support.
- It provides multiple integration schemes (symplectic, hybrid, high-order, adaptive), collision and gravity modules, and supports MPI/OpenMP/SIMD.

##### File Structure
- Top-Level Build & Config:
– Makefile, pyproject.toml, setup.py, requirements.txt – orchestrate C builds, Python packaging, CI (GitHub Actions), docs generation (mkdocs/Sphinx).
– .github/workflows – automated C builds, Python package tests, coverage, emscripten builds.
- Core Library (C):
– src/ – modular C code: simulation core (simulation.c), integrator implementations (integrator_*.c), gravity (gravity.c), collisions (collision.c), communication (MPI), I/O (simulationarchive.c, output.c), server.c (Python/C API entry points), tools.c.
- Python Package:
– rebound/ – Python wrapper modules binding to the C core via C‐extension (rebound.c in src plus rebound/__init__.py).
– rebound/integrators – Python interface mirrors C integrators for high‐level use.
– rebound/tests – pytest suite covering both Python and C functionality.
- Examples & Tutorials:
– examples/, python_examples/, ipython_examples/ – demonstration code for C, Python, and Jupyter notebooks.
– web_client/ – emscripten‐compiled C for in-browser examples (HTML + JavaScript).
- Documentation:
– docs/, mkdocs.yml, .readthedocs.yaml – source for online documentation and tutorial pages.

##### README Insights
- Core features highlighted: no external dependencies, multiple integrators, real-time 3D visualization, hybrid and parallel methods.
- Usage modes:
– C API (compile & link against librebound)
– Python API (`import rebound`)
– Browser examples via emscripten

a. Main Components
1. Build & CI Layer
- Makefiles / setup.py / pyproject.toml
- GitHub Actions workflows
- Emscripten toolchain
2. Core C Library
- Simulation Core
- Integrator Modules (WHFast, IAS15, MERCURIUS, …)
- Gravity & Collision Engines
- I/O & Archive (simulationarchive)
- Communication (MPI/OpenMP)
- C-Extension Entry Points (server.c)
3. Python Wrapper Layer
- rebound Python package (bindings)
- Python integrator interfaces
- Utilities (plotting, data, units, horizons)
4. User Interfaces
- Command-line/examples (C executables)
- Python scripts & REPL
- Jupyter notebooks
- Web client (HTML + WebGL)
5. Supporting Artifacts
- Tests (C tests, pytest suite)
- Documentation (mkdocs/Sphinx)
- Examples & Tutorials

b. Relationships and Data Flow
- User calls Python API → rebound module forwards calls to the C shared library via C‐extension.
- C shared library orchestrates simulation core → invokes integrator modules, gravity, collisions → updates particle state → I/O writing or returns data to Python.
- Web client: emscripten‐compiled C library is invoked by JavaScript UI to run simulations in browser.
- CI triggers builds/tests across layers (C build → Python wheel → docs build → example compilation).

c. Architectural Patterns
- Layered Architecture: clear separation of Core Library, Binding Layer, and UI/Examples.
- Plugin/Strategy: each integrator is a pluggable module conforming to a common integrator interface.
- Modularization: gravity, collisions, communication, and I/O are separate modules.
- Polyglot Interfaces: same core used via C API, Python API, and WebAssembly.

d. Key Technologies & Frameworks
- ISO C99, Makefiles, Emscripten, MPI, OpenMP, AVX512
- CPython C‐extension API, pip, setuptools
- pytest for testing, mkdocs/Sphinx for documentation
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI Layer"
        direction TB
        Makefile["Makefile"]:::buildCI
        SetupPy["setup.py"]:::buildCI
        Pyproject["pyproject.toml"]:::buildCI
        Requirements["requirements.txt"]:::buildCI
        Workflows["GitHub Actions Workflows"]:::buildCI
        Readthedocs[".readthedocs.yaml"]:::buildCI
        MkdocsYml["mkdocs.yml"]:::buildCI
    end

    %% Core C Library
    subgraph "Core C Library"
        direction TB
        CoreSrc["C Core Modules (src/)"]:::coreC
        Integrators["Integrator Modules"]:::coreC
        Gravity["Gravity Engine"]:::coreC
        Collision["Collision Engine"]:::coreC
        Comm["Communication (MPI/OpenMP)"]:::coreC
        IO["I/O & Archive"]:::coreC
        Server["C-Extension Entry (server.c)"]:::coreC
    end

    %% Python Wrapper Layer
    subgraph "Python Wrapper Layer"
        direction TB
        PyPackage["rebound Python Package"]:::python
        PyIntegrators["Python Integrator Interfaces"]:::python
        PyTests["pytest Suite"]:::python
    end

    %% User Interfaces & Examples
    subgraph "User Interfaces & Examples"
        direction TB
        CExamples["C Example Programs"]:::ui
        PyExamples["Python Example Scripts"]:::ui
        Notebooks["Jupyter Notebooks"]:::ui
        WebClient["Web Client (Emscripten)"]:::ui
    end

    %% Documentation & Tutorials
    subgraph "Documentation & Tutorials"
        direction TB
        DocsSource["Documentation Sources"]:::docs
        DocsScripts["Docs Generation Scripts"]:::docs
        APIRef["API Reference Config"]:::docs
    end

    %% Relationships
    CExamples -->|"compiles via Makefile"| CoreSrc
    PyExamples -->|"imports rebound"| PyPackage
    Notebooks -->|"uses rebound"| PyPackage
    WebClient -->|"WebAssembly build"| CoreSrc
    PyPackage -->|"binds to"| Server
    Server -->|"calls into"| CoreSrc
    CoreSrc --> Integrators
    CoreSrc --> Gravity
    CoreSrc --> Collision
    CoreSrc --> Comm
    CoreSrc --> IO
    PyIntegrators --> PyPackage
    PyTests --> PyPackage
    Workflows --> Makefile
    Workflows --> SetupPy
    Workflows --> DocsSource
    DocsScripts --> DocsSource

    %% Click Events
    click Makefile "https://github.com/hannorein/rebound/tree/main//Makefile"
    click SetupPy "https://github.com/hannorein/rebound/blob/main//setup.py"
    click Pyproject "https://github.com/hannorein/rebound/blob/main//pyproject.toml"
    click Requirements "https://github.com/hannorein/rebound/blob/main//requirements.txt"
    click Workflows "https://github.com/hannorein/rebound/tree/main//.github/workflows/"
    click Readthedocs "https://github.com/hannorein/rebound/blob/main//.readthedocs.yaml"
    click MkdocsYml "https://github.com/hannorein/rebound/blob/main//mkdocs.yml"
    click CoreSrc "https://github.com/hannorein/rebound/tree/main//src/"
    click Server "https://github.com/hannorein/rebound/blob/main//src/server.c"
    click PyPackage "https://github.com/hannorein/rebound/blob/main//rebound/__init__.py"
    click PyIntegrators "https://github.com/hannorein/rebound/tree/main//rebound/integrators/"
    click PyTests "https://github.com/hannorein/rebound/tree/main//rebound/tests/"
    click CExamples "https://github.com/hannorein/rebound/tree/main//examples/"
    click PyExamples "https://github.com/hannorein/rebound/tree/main//python_examples/"
    click Notebooks "https://github.com/hannorein/rebound/tree/main//ipython_examples/"
    click WebClient "https://github.com/hannorein/rebound/tree/main//web_client/"
    click DocsSource "https://github.com/hannorein/rebound/tree/main//docs/"
    click DocsScripts "https://github.com/hannorein/rebound/blob/main//docs/generate_python_docs.py"

    %% Styles
    classDef buildCI fill:#d3d3d3,stroke:#666,stroke-width:1px
    classDef coreC fill:#add8e6,stroke:#4682b4,stroke-width:1px
    classDef python fill:#98fb98,stroke:#228b22,stroke-width:1px
    classDef ui fill:#ffa500,stroke:#ff8c00,stroke-width:1px
    classDef docs fill:#dda0dd,stroke:#9370db,stroke-width:1px
```
