Main REBOUND Structures

group MainRebStructs

These are the main REBOUND structures

struct reb_particle
#include <rebound.h>

Structure representing one REBOUND particle.

This structure is used to represent one particle. If this structure is changed, the corresponding python structure needs to be changes as well. Also update the equivalent declaration for MPI in communications_mpi.c.

Public Members

double x

x-position of the particle.

double y

y-position of the particle.

double z

z-position of the particle.

double vx

x-velocity of the particle.

double vy

y-velocity of the particle.

double vz

z-velocity of the particle.

double ax

x-acceleration of the particle.

double ay

y-acceleration of the particle.

double az

z-acceleration of the particle.

double m

Mass of the particle.

double r

Radius of the particle.

double lastcollision

Last time the particle had a physical collision.

struct reb_treecell *c

Pointer to the cell the particle is currently in.

uint32_t hash

hash to identify particle.

void *ap

Functionality for externally adding additional properties to particles.

struct reb_simulation *sim

Pointer to the parent simulation.

struct reb_orbit
#include <rebound.h>

Structure representing a Keplerian orbit.

This structure is returned when calculating a Keplerian orbit from Cartesian coordinates.

Public Members

double d

Radial distance from central object.

double v

velocity relative to central object’s velocity

double h

Angular momentum.

double P

Orbital period.

double n

Mean motion.

double a

Semi-major axis.

double e


double inc


double Omega

Longitude of ascending node.

double omega

Argument of pericenter.

double pomega

Longitude of pericenter.

double f

True anomaly.

double M

Mean anomaly.

double l

Mean Longitude.

double theta

True Longitude.

double T

Time of pericenter passage.

struct reb_simulation
#include <rebound.h>

Main struct encapsulating one entire REBOUND simulation.

This structure contains all variables, status flags and pointers of one REBOUND simulation. To create a REBOUND simulation use the reb_create_simulation() function. This will ensure that all variables and pointers are initialized correctly.

Variables related to time, current number of particles and simulation status/control

double t

Current simulation time.

double G

Gravitational constant. Default: 1.

double softening

Gravitational softening parameter. Default: 0.

double dt

Current timestep.

double dt_last_done

Last dt used by integrator.

int N

Current number of particles on this node.

int N_var

Total number of variational particles. Default: 0.

int var_config_N

Number of variational configuration structs. Default: 0.

struct reb_variational_configuration *var_config

These configuration structs contain details on variational particles.

int N_active

Number of massive particles included in force calculation (default: N). Particles with index >= N_active are considered testparticles.

int testparticle_type

Type of the particles with an index>=N_active. 0 means particle does not influence any other particle (default), 1 means particles with index < N_active feel testparticles (similar to MERCURY’s small particles). Testparticles never feel each other.

struct reb_hash_pointer_pair *particle_lookup_table

Array of pairs that map particles’ hashes to their index in the particles array.

int hash_ctr

Counter for number of assigned hashes to assign unique values.

int N_lookup

Number of entries in the particle lookup table.

int allocatedN_lookup

Number of lookup table entries allocated.

int allocatedN

Current maximum space allocated in the particles array on this node.

struct reb_particle *particles

Main particle array. This contains all particles on this node.

struct reb_vec3d *gravity_cs

Vector containing the information for compensated gravity summation.

int gravity_cs_allocatedN

Current number of allocated space for cs array.

struct reb_treecell **tree_root

Pointer to the roots of the trees.

int tree_needs_update

Flag to force a tree update (after boundary check)

double opening_angle2

Square of the cell opening angle \( \theta \).


Set to 1 to exit the simulation at the end of the next timestep.

int exact_finish_time

Set to 1 to finish the integration exactly at tmax. Set to 0 to finish at the next dt. Default is 1.

unsigned int force_is_velocity_dependent

Set to 1 if integrator needs to consider velocity dependent forces.

unsigned int gravity_ignore_terms

Ignore the gravity form the central object (1 for WHFast, 2 for WHFastHelio, 0 otherwise)

double output_timing_last

Time when reb_output_timing() was called the last time.

unsigned long display_clock

Display clock, internal variable for timing refreshs.

int save_messages

Set to 1 to ignore messages (used in python interface).

char **messages

Array of strings containing last messages (only used if save_messages==1).

double exit_max_distance

Exit simulation if distance from origin larger than this value.

double exit_min_distance

Exit simulation if distance from another particle smaller than this value.

double usleep

Wait this number of microseconds after each timestep, useful for slowing down visualization.

int track_energy_offset

< Datastructure stores visualization related data. Does not have to be modified by the user.

Track energy change during collisions and ejections (default: 0).

double energy_offset

Energy offset due to collisions and ejections (only calculated if track_energy_offset=1).

Variables related to ghost/root boxes

struct reb_vec3d boxsize

Size of the entire box, root_x*boxsize.

double boxsize_max

Maximum size of the entire box in any direction. Set in box_init().

double root_size

Size of a root box.

int root_n

Total number of root boxes in all directions, root_nx*root_ny*root_nz. Default: 1. Set in box_init().

int root_nx

Number of root boxes in x direction. Default: 1.

int root_ny

Number of root boxes in y direction. Default: 1.

int root_nz

Number of root boxes in z direction. Default: 1.

int nghostx

Number of ghostboxes in x direction.

int nghosty

Number of ghostboxes in y direction.

int nghostz

Number of ghostboxes in z direction.

Variables related to collision search and detection

int collision_resolve_keep_sorted

Keep particles sorted if collision_resolve removes particles during a collision.

struct reb_collision *collisions

Array of all collisions.

int collisions_allocatedN

Size allocated for collisions.

double minimum_collision_velocity

Used for hard sphere collision model.

double collisions_plog

Keep track of momentum exchange (used to calculate collisional viscosity in ring systems.

double max_radius[2]

Two largest particle radii, set automatically, needed for collision search.

long collisions_Nlog

Keep track of number of collisions.

Variables related to the chaos indicator MEGNO

int calculate_megno

Internal flag that determines if megno is calculated (default=0, but megno_init() sets it to the index of variational particles used for megno)

double megno_Ys

Running megno sum (internal use)

double megno_Yss

Running megno sum (internal use)

double megno_cov_Yt

covariance of MEGNO Y and t

double megno_var_t

variance of t

double megno_mean_t

mean of t

double megno_mean_Y

mean of MEGNO Y

long megno_n

number of covariance updates

Variables related to SimulationArchive

long simulationarchive_size_first

Size of the initial binary file in a SA.

long simulationarchive_size_snapshot

Size of a snapshot in a SA (other than 1st), in bytes.

double simulationarchive_interval

Current sampling cadence, in code units.

double simulationarchive_interval_walltime

Current sampling cadence, in wall time.

double simulationarchive_next

Next output time.

char *simulationarchive_filename

Name of output file.

double simulationarchive_walltime

Current walltime since beginning of simulation.

struct timeval simulationarchive_time

Time of last output.

Variables describing the current module selection

enum [anonymous]

Available collision routines.



No visualization (default if OPENGL compiler flag is turned off)


OpenGL visualization (default if OPENGL compiler flag is turned on)


WebGL visualization, only usable from Jupyter notebook widget.

enum [anonymous]

Available collision routines.



Do not search for collisions (default)


Direct collision search O(N^2)


Tree based collision search O(N log(N))

enum [anonymous]

Available integrators.



IAS15 integrator, 15th order, non-symplectic (default)


WHFast integrator, symplectic, 2nd order, up to 11th order correctors.


SEI integrator for shearing sheet simulations, symplectic, needs OMEGA variable.


LEAPFROG integrator, simple, 2nd order, symplectic.


HERMES Integrator for close encounters (experimental)


WHFastHelio integrator, symplectic, 2nd order, in democratic heliocentric coordinates.


Do not integrate anything.

enum [anonymous]

Available boundary conditions.



Do not check for anything (default)


Open boundary conditions. Removes particles if they leave the box.


Periodic boundary conditions.


Shear periodic boundary conditions, needs OMEGA variable.

enum [anonymous]

Available gravity routines.



Do not calculate graviational forces.


Basic O(N^2) direct summation algorithm, choose this for shearing sheet and periodic boundary conditions.


Direct summation algorithm O(N^2) but with compensated summation, slightly slower than BASIC but more accurate.


Use the tree to calculate gravity, O(N log(N)), set opening_angle2 to adjust accuracy.

reb_simulation::@0 reb_simulation::visualization

Available collision routines.

reb_simulation::@1 reb_simulation::collision

Available collision routines.

reb_simulation::@2 reb_simulation::integrator

Available integrators.

reb_simulation::@3 reb_simulation::boundary

Available boundary conditions.

reb_simulation::@4 reb_simulation::gravity

Available gravity routines.

Integrator structs (the contain integrator specific variables and temporary data structures)

struct reb_simulation_integrator_sei ri_sei

The SEI struct.

struct reb_simulation_integrator_whfast ri_whfast

The WHFast struct.

struct reb_simulation_integrator_ias15 ri_ias15

The IAS15 struct.

struct reb_simulation_integrator_hermes ri_hermes

The HERMES struct.

struct reb_simulation_integrator_whfasthelio ri_whfasthelio

The WHFastDemocratic struct.

Callback functions

void(* reb_simulation::additional_forces) (struct reb_simulation *const r)

This function allows the user to add additional (non-gravitational) forces.

void(* reb_simulation::pre_timestep_modifications) (struct reb_simulation *const r)

This function allows the user to make changes before each timestep.

void(* reb_simulation::post_timestep_modifications) (struct reb_simulation *const r)

This function allows the user to make changes after each timestep.

void(* reb_simulation::heartbeat) (struct reb_simulation *r)

This function is called at the beginning of the simulation and at the end of each timestep.

void(* reb_simulation::display_heartbeat) (struct reb_simulation *r)

This function is called at the beginning of the simulation and at the end of each timestep.

double(* reb_simulation::coefficient_of_restitution) (const struct reb_simulation *const r, double v)

Return the coefficient of restitution. By default it is NULL, assuming a coefficient of 1.

The velocity of the collision is given to allow for velocity dependent coefficients of restitution.

int(* reb_simulation::collision_resolve) (struct reb_simulation *const r, struct reb_collision)

Resolve collision within this function. By default it is NULL, assuming hard sphere model.

A return value of 0 indicates that both particles remain in the simulation. A return value of 1 (2) indicates that particle 1 (2) should be removed from the simulation. A return value of 3 indicates that both particles should be removed from the simulation.

void(* reb_simulation::free_particle_ap) (struct reb_particle *p)

Free particle’s ap pointer. Called in reb_remove function.

Hooks for external libraries

void *extras

Pointer to connect additional (optional) libraries, e.g., reboundx.