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

librebound-sys is a -sys crate exposing the C ABI of 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 (adds ASSIST's force model) and assist-rs (adds the high-level API).

Crate hierarchy

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

[dependencies]
librebound-sys = "1.2"

Requires a C compiler. clang is preferred (enables LLVM ThinLTO, see Building); gcc also works.

Usage

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.

git clone --recursive <repo-url>
cargo build --release

For maximum performance use clang, which honours the -flto=thin flag set in build.rs:

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

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.

librebound-sys	REBOUND
4.6.x	4.6.0

License

GPL-3.0 — required by the vendored REBOUND source. See LICENSE and vendor/rebound/LICENSE.

References

Rein & Liu 2012, "REBOUND: An open-source multi-purpose N-body code for collisional dynamics", A&A 537 A128
Rein & Spiegel 2015, "IAS15: a fast, adaptive, high-order integrator for gravitational dynamics", MNRAS 446 1424

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/ with original LICENSE preserved at vendor/rebound/LICENSE. If you use this crate in published work, please cite the REBOUND papers listed in References — not this crate.

The Rust wrapper layer is developed by the Asteroid Institute, a program of the B612 Foundation.

librebound-sys 4.6.0