# librebound-sys: Raw FFI bindings and safe RAII wrappers for the REBOUND N-body integrator
#### A Rust crate by the Asteroid Institute, a program of the B612 Foundation
[](https://github.com/hannorein/rebound)<br/>
[](https://github.com/B612-Asteroid-Institute/librebound-sys/actions/workflows/rust.yml)
[](https://crates.io/crates/librebound-sys)
[](https://docs.rs/librebound-sys)
[](LICENSE)<br/>
[](https://github.com/B612-Asteroid-Institute)
[](https://asteroid.institute/)
`librebound-sys` is a `-sys` crate exposing the C ABI of [REBOUND](https://github.com/hannorein/rebound), an open-source N-body integration library. It vendors REBOUND as a git submodule, compiles it via the `cc` crate, and provides:
- `ffi` — raw `extern "C"` bindings to REBOUND functions and types.
- `Simulation` — allocation-owning RAII wrapper around `reb_simulation`.
- `IntegratorConfig` + `Ias15AdaptiveMode` — ergonomic types for IAS15 timestep + adaptive-mode configuration.
- `Error` — typed integration-exit conditions (`NoParticles`, `CloseEncounter`, `Escape`, `Collision`, `IntegrationFailed`).
No domain logic — no ephemerides, no orbital elements, no observatories. Layer those on top via [`libassist-sys`](https://crates.io/crates/libassist-sys) (adds ASSIST's force model) and [`assist-rs`](https://crates.io/crates/assist-rs) (adds the high-level API).
## Crate hierarchy
```text
assist-rs ← domain types: Orbit, Origin, Observer, DataManager
└── libassist-sys ← raw ASSIST FFI + AssistSim/Ephemeris RAII
└── librebound-sys ← raw REBOUND FFI + Simulation RAII (this crate)
```
## Installation
```toml
[dependencies]
librebound-sys = "1.2"
```
Requires a C compiler. `clang` is preferred (enables LLVM ThinLTO, see [Building](#building)); `gcc` also works.
## Usage
```rust
use librebound_sys::{IntegratorConfig, Simulation};
let mut sim = Simulation::new()?;
IntegratorConfig::default().apply(&mut sim);
sim.set_t(0.0);
// Two-body Kepler orbit: Sun + test particle on a circular AU orbit.
sim.add_particle_with_mass(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0);
sim.add_test_particle(1.0, 0.0, 0.0, 0.0, 0.017_202_098_95, 0.0);
sim.integrate(365.25)?;
let particles = sim.particles();
assert!(particles.len() == 2);
# Ok::<(), librebound_sys::Error>(())
```
`Simulation` owns the underlying `reb_simulation` pointer and frees it on drop. The struct is `Send` — passing across threads is sound — but **not** `Sync`; one mutable simulation per thread.
## Building
The crate vendors REBOUND under `vendor/rebound/` (git submodule). `build.rs` compiles `vendor/rebound/src/*.c` via the `cc` crate.
```bash
git clone --recursive <repo-url>
cargo build --release
```
For maximum performance use `clang`, which honours the `-flto=thin` flag set in `build.rs`:
```bash
CC=clang cargo build --release
```
This enables LLVM ThinLTO across all REBOUND translation units. GCC silently ignores the flag — builds are still correct but ~5–7 % slower on hot integration loops.
## Testing
```bash
cargo test
```
No external data files needed; the test suite drives REBOUND directly with synthetic particle setups.
## Versioning
The crate's `major.minor` mirrors the vendored REBOUND release: **librebound-sys 4.6.x wraps REBOUND 4.6.0**. The patch component is reserved for Rust-side fixes that don't change the underlying C library. A REBOUND 4.7 release would become librebound-sys 4.7.0; a REBOUND 5.0 release would become librebound-sys 5.0.0.
### Why this scheme
`-sys` crates are thin wrappers around a single upstream library. Mirroring upstream's `major.minor` makes the dependency obvious from the version alone — no need to consult a mapping table or `[package.metadata.vendored]`. The Rust side gets the patch slot for wrapper fixes (e.g. tightening Send/Sync bounds, fixing a leak in a wrapper, adding a typed Error variant), which is where ~all non-upstream changes land in practice.
This is **not** standard Rust semver — bumping the crate's major version isn't an intrinsic Rust-API break; it tracks the C ABI break in the upstream library. Callers depending on `librebound-sys = "4"` get any 4.x.y; callers needing strict pinning should pin to `4.6` or `=4.6.0`.
| 4.6.x | [4.6.0](https://github.com/hannorein/rebound/releases/tag/4.6.0) |
## License
GPL-3.0 — required by the vendored REBOUND source. See [LICENSE](LICENSE) and [`vendor/rebound/LICENSE`](vendor/rebound/LICENSE).
## References
- Rein & Liu 2012, "REBOUND: An open-source multi-purpose N-body code for collisional dynamics", [A&A 537 A128](https://doi.org/10.1051/0004-6361/201118085)
- Rein & Spiegel 2015, "IAS15: a fast, adaptive, high-order integrator for gravitational dynamics", [MNRAS 446 1424](https://doi.org/10.1093/mnras/stu2164)
## Acknowledgments
This crate is a thin Rust wrapper. All credit for the underlying physics and integrator implementation belongs to the upstream REBOUND project:
- **REBOUND** — Hanno Rein and contributors. Source: <https://github.com/hannorein/rebound>. Vendored under [`vendor/rebound/`](vendor/rebound/) with original LICENSE preserved at [`vendor/rebound/LICENSE`](vendor/rebound/LICENSE). If you use this crate in published work, please cite the REBOUND papers listed in [References](#references) — not this crate.
The Rust wrapper layer is developed by the [Asteroid Institute](https://asteroid.institute/), a program of the [B612 Foundation](https://b612foundation.org/).