How hannorein/rebound works
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