Million-Particle GPU Physics Engine — High-performance N-body simulation with CUDA acceleration, real-time OpenGL visualization, and three force calculation algorithms.

GitHub Pages · Getting Started · Examples · OpenSpec

This project combines three force-computation strategies with a single simulation/runtime API:

• Direct N² for exact pairwise reference results
• Barnes-Hut for scalable long-range approximation
• Spatial Hash for efficient short-range interaction
• Velocity Verlet for stable symplectic integration
• CUDA/OpenGL interop for zero-copy visualization

The goal is not just to render particles quickly, but to keep the simulation architecture understandable, testable, and easy to compare across algorithms.

Benchmarks on NVIDIA RTX 3080

graph TB
    subgraph CPU["CPU (Host)"]
        Config[SimulationConfig]
        PS[ParticleSystem]
        RL[Render Loop]
    end
    
    subgraph GPU["GPU (Device)"]
        FK[Force Kernel<br/>N²/Barnes-Hut/Hash]
        INT[Integration<br/>Velocity Verlet]
        GL[OpenGL<br/>Zero-Copy]
    end
    
    Config --> PS
    PS --> FK
    FK --> INT
    INT --> GL
    GL --> RL

• NVIDIA GPU with CUDA support
• CUDA Toolkit 11+
• CMake 3.18+
• OpenGL, GLFW, GLEW, GLM
• For a headless core-only validation path, disable CUDA/rendering; headless observability tests and benchmarks still work.

./scripts/build.sh

When CUDA is unavailable, the script now falls back to a headless core-only build and still produces the core library, headless observability tests, and the benchmark executable. Rendered app surfaces and examples remain disabled.

Manual path:

mkdir -p build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j"$(nproc)"

./build/nbody_sim
./build/nbody_sim 100000

./scripts/test.sh

./scripts/benchmark.sh
./scripts/benchmark.sh serialization.round_trip build/benchmark-results.json

• Getting Started
• Architecture
• Algorithms
• API Reference
• Performance
• Contributing

• example_basic.cpp
• example_force_methods.cpp
• example_custom_distribution.cpp
• example_energy_conservation.cpp

• Canonical build path: CMake + scripts/build.sh
• Canonical LSP baseline: clangd + compile_commands.json
• Canonical assistant guidance: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md

If you use this project in your research, please cite:

@software{nbody2026,
  title = {N-Body: Million-Particle GPU Physics Engine},
  author = {AICL-Lab},
  year = {2026},
  url = {https://github.com/AICL-Lab/n-body},
  version = {2.1.0},
  note = {CUDA-accelerated N-body simulation with real-time visualization}
}

MIT