1. Implemented Effects¶
Below are descriptions for each of the effects included in REBOUNDx. Different implementations for the same effect are grouped together. All effects follow the same recipes for usage, see the Python quickstart guide (Quick Start Guide) or C quickstart guide (Quick Start Guide). Probably the quickest way to get up and running is to edit one of the linked examples for the effect you’re interested in.
1.1. Orbit Modifications¶
REBOUNDx offers two ways of modifying orbital elements (semimajor axis/eccentricity/inclination damping, precession, etc.) In both cases, each particle is assigned evolution timescales for each orbital element. Positive timescales correspond to growth / progression, negative timescales correspond to damping / regression. Semimajor axes, eccentricities and inclinations grow / damp exponentially. Pericenters and nodes progress/regress linearly.
1.1.1. inner_disk_edge¶
Authors 
Kajtazi, Kaltrina and D. Petit, C. Antoine 
Implementation Paper 

Based on 

C example 

Python example 
This applies an inner disk edge that functions as a planet trap. Within its width the planet’s migration is reversed by an opposite and roughly equal magnitude torque. Thus, stopping further migration and trapping the planet within the width of the trap. The functions here provide a way to modify the tau_a timescale in modify_orbits_forces, modify_orbit_direct, and type_I_migration. Note that the present prescription is very useful for simple simulations when an inner trap is needed during the migration but it shouldn’t be considered as a realistic model of the inner edge of a disk.
Effect Parameters
Field (C type) 
Required 
Description 

ide_position (double) 
Yes 
The position of the inner disk edge in code units 
ide_width (double) 
Yes 
The disk edge width (planet will stop within ide_width of ide_position) 
1.1.2. exponential_migration¶
Author 
Mohamad AliDib 
Implementation Paper 

Based on 

C Example 

Python Example 
Continuous velocity kicks leading to exponential change in the object’s semimajor axis. One of the standard prescriptions often used in Neptune migration & Kuiper Belt formation models. Does not directly affect the eccentricity or inclination of the object.
Particle Parameters
Field (C type) 
Required 
Description 

em_tau_a (double) 
Yes 
Semimajor axis exponential growth/damping timescale 
em_aini (double) 
Yes 
Object’s initial semimajor axis 
em_afin (double) 
Yes 
Object’s final semimajor axis 
1.1.3. modify_orbits_direct¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
This updates particles’ positions and velocities between timesteps to achieve the desired changes to the osculating orbital elements (exponential growth/decay for a, e, inc, linear progression/regression for Omega/omega. This nicely isolates changes to particular osculating elements, making it easier to interpret the resulting dynamics. One can also adjust the coupling parameter p between eccentricity and semimajor axis evolution, as well as whether the damping is done on Jacobi, barycentric or heliocentric elements. Since this method changes osculating (i.e., twobody) elements, it can give unphysical results in highly perturbed systems.
Effect Parameters
If p is not set, it defaults to 0. If coordinates not set, defaults to using Jacobi coordinates.
Field (C type) 
Required 
Description 

p (double) 
No 
Coupling parameter between eccentricity and semimajor axis evolution (see Deck & Batygin 2015). p=0 corresponds to no coupling, p=1 to eccentricity evolution at constant angular momentum. 
coordinates (enum) 
No 
Type of elements to use for modification (Jacobi, barycentric or particle). See the examples for usage. 
Particle Parameters
One can pick and choose which particles have which parameters set. For each particle, any unset parameter is ignored.
Field (C type) 
Required 
Description 

tau_a (double) 
No 
Semimajor axis exponential growth/damping timescale 
tau_e (double) 
No 
Eccentricity exponential growth/damping timescale 
tau_inc (double) 
No 
Inclination axis exponential growth/damping timescale 
tau_Omega (double) 
No 
Period of linear nodal precession/regression 
tau_omega (double) 
No 
Period of linear apsidal precession/regression 
1.1.4. type_I_migration¶
Authors 
Kajtazi, Kaltrina and D. Petit, C. Antoine 
Implementation Paper 

Based on 

C example 

Python example 
This applies Type I migration, damping eccentricity, angular momentum and inclination. The base of the code is the same as the modified orbital forces one written by D. Tamayo, H. Rein. It also allows for parameters describing an inner disc edge, modeled using the implementation in inner_disk_edge.c. Note that this code is not machine independent since power laws were not possible to avoid all together.
Effect Parameters
Field (C type) 
Required 
Description 

ide_position (double) 
No 
The position of the inner disk edge in code units 
ide_width (double) 
No 
The disk edge width (planet will stop within ide_width of ide_position) 
tIm_surface_density_1 (double) 
Yes 
Disk surface density at one code unit from the star; used to find the surface density at any distance from the star 
tIm_scale_height_1 (double) 
Yes 
The scale height at one code unit from the star; used to find the aspect ratio at any distance from the star 
tIm_surface_density_exponent (double) 
Yes 
Exponent of disk surface density, indicative of the surface density profile of the disk 
tIm_flaring_index (double) 
Yes 
The flaring index; 1 means disk is irradiated by only the stellar flux 
1.1.5. modify_orbits_forces¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
This applies physical forces that orbitaverage to give exponential growth/decay of the semimajor axis, eccentricity and inclination. The eccentricity damping keeps the angular momentum constant (corresponding to p=1 in modify_orbits_direct), which means that eccentricity damping will induce some semimajor axis evolution. Additionally, eccentricity/inclination damping will induce pericenter/nodal precession. Both these effects are physical, and the method is more robust for strongly perturbed systems.
Effect Parameters
If coordinates not, defaults to using Jacobi coordinates.
Field (C type) 
Required 
Description 

coordinates (enum) 
No 
Type of elements to use for modification (Jacobi, barycentric or particle). See the examples for usage. 
Particle Parameters
One can pick and choose which particles have which parameters set. For each particle, any unset parameter is ignored.
Field (C type) 
Required 
Description 

tau_a (double) 
No 
Semimajor axis exponential growth/damping timescale 
tau_e (double) 
No 
Eccentricity exponential growth/damping timescale 
tau_inc (double) 
No 
Inclination axis exponential growth/damping timescale 
1.2. General Relativity¶
1.2.1. gr_potential¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
This is the simplest potential you can use for general relativity. It assumes that the masses are dominated by a single central body. It gets the precession right, but gets the mean motion wrong by \(\mathcal{O}(GM/ac^2)\). It’s the fastest option, and because it’s not velocitydependent, it automatically keeps WHFast symplectic. Nice if you have a singlestar system, don’t need to get GR exactly right, and want speed.
Effect Parameters
Field (C type) 
Required 
Description 

c (double) 
Yes 
Speed of light, needs to be specified in the units used for the simulation. 
1.2.2. gr_full¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
This algorithm incorporates the firstorder postnewtonian effects from all bodies in the system, and is necessary for multiple massive bodies like stellar binaries.
Effect Parameters
Field (C type) 
Required 
Description 

c (double) 
Yes 
Speed of light, needs to be specified in the units used for the simulation. 
Particle Parameters
None
1.2.3. lense_thirring¶
Authors 

Implementation Paper 
None 
Based on 

C Example 

Python Example 
Adds LenseThirring effect due to rotating central body in the simulation. Assumes the source body is particles[0]
Effect Parameters
Field (C type) 
Required 
Description 

lt_c (double) 
Yes 
Speed of light in the units used for the simulation. 
Particle Parameters
Field (C type) 
Required 
Description 

I (double) 
Yes 
Moment of Inertia of source body 
Omega (reb_vec3d) 
Yes 
Angular rotation frequency (Omega_x, Omega_y, Omega_z) 
1.2.4. gr¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
This assumes that the masses are dominated by a single central body, and should be good enough for most applications with planets orbiting single stars. It ignores terms that are smaller by of order the mass ratio with the central body. It gets both the mean motion and precession correct, and will be significantly faster than gr_full, particularly with several bodies. Adding this effect to several bodies is NOT equivalent to using gr_full.
Effect Parameters
Field (C type) 
Required 
Description 

c (double) 
Yes 
Speed of light, needs to be specified in the units used for the simulation. 
1.3. Radiation Forces¶
1.3.1. yarkovsky_effect¶
Authors 
Noah Ferich, D. Tamayo 
Implementation Paper 
Ferich et al., in prep. 
Based on 

C Example 

Python Example 
Adds the accelerations and orbital perturbations created by the Yarkovsky effect onto one or more bodies in the simulation. There are two distinct versions of this effect that can be used: the ‘full version’ and the ‘simple version’. The full version uses the full equations found in Veras et al. (2015) to accurately calculate the Yarkovsky effect on a particle. However, this version slows down simulations and requies a large amount of parameters. For these reasons, the simple version of the effect (based on Veras et al. (2019)) is available. While the magnitude of the acceleration created by the effect will be the same, this version places constant values in a crucial rotation matrix to simplify the push from the Yarkovsky effect on a body. This version is faster and requires less parameters and can be used to get an upper bound on how much the Yarkovsky effect can push an object’s orbit inwards or outwards. The lists below describes which parameters are needed for one or both versions of this effect. For more information, please visit the papers and examples linked above.
Effect Parameters
Field (C type) 
Required 
Description 

ye_lstar (float) 
Yes 
Luminosity of sim’s star (Required for both versions). 
ye_c (float) 
Yes 
Speed of light (Required for both versions). 
ye_stef_boltz (float) 
No 
StefanBoltzmann constant (Required for full version). 
Particle Parameters
Field (C type) 
Required 
Description 

particles[i].r (float) 
Yes 
Physical radius of a body (Required for both versions). 
ye_flag (int) 
Yes 
0 sets full version of effect. 1 uses simple version with outward migration. 1 uses the simple version with inward migration (see examples and paper). 
ye_body_density (float) 
Yes 
Density of an object (Required for both versions) 
ye_rotation_period (float) 
No 
Rotation period of a spinning object (Required for full version) 
ye_albedo (float) 
Yes 
Albedo of an object (Reuired for both versions) 
ye_emissivity (float) 
No 
Emissivity of an object (Required for full version) 
ye_thermal_inertia (float) 
No 
Thermal inertia of an object (Required for full version) 
ye_k (float) 
No 
A constant that gets a value between 0 and 1/4 based on the object’s rotation  see Veras et al. (2015) for more information on it (Required for full version) 
ye_spin_axis_x (float) 
No 
The x value for the spin axis vector of an object (Required for full version) 
ye_spin_axis_y (float) 
No 
The y value for the spin axis vector of an object (Required for full version) 
ye_spin_axis_z (float) 
No 
The z value for the spin axis vector of an object (Required for full version) 
1.3.2. radiation_forces¶
Authors 

Implementation Paper 

Based on 

C Example 
Radiation forces on a debris disk, Radiation forces on circumplanetary dust. 
Python Example 
Radiation_Forces_Debris_Disk.ipynb, Radiation_Forces_Circumplanetary_Dust.ipynb. 
This applies radiation forces to particles in the simulation. It incorporates both radiation pressure and PoyntingRobertson drag. Only particles whose beta parameter is set will feel the radiation.
Effect Parameters
Field (C type) 
Required 
Description 

c (double) 
Yes 
Speed of light in the units used for the simulation. 
Particle Parameters
If no particles have radiation_source set, effect will assume the particle at index 0 in the particles array is the source.
Field (C type) 
Required 
Description 

radiation_source (int) 
No 
Flag identifying the particle as the source of radiation. 
beta (float) 
Yes 
Ratio of radiation pressure force to gravitational force. Particles without beta set feel no radiation forces. 
1.4. Stochastic Forces¶
1.4.1. stochastic_forces¶
Authors 

Based on 

Implementation Paper 

C Example 

Python Example 
This applies stochastic forces to particles in the simulation.
Effect Parameters
None
Particle Parameters
All particles which have the field kappa set, will experience stochastic forces. The particle with index 0 cannot experience stochastic forces.
Field (C type) 
Required 
Description 

kappa (double) 
Yes 
Strength of stochastic forces relative to gravity from central object 
tau_kappa (double) 
No 
Autocorrelation time of stochastic forces. Defaults to orbital period if not set. The units are relative to the current orbital period. 
1.5. Mass Modifications¶
1.5.1. modify_mass¶
Authors 

Implementation Paper 

Based on 
None 
C Example 

Python Example 
This adds exponential mass growth/loss to individual particles every timestep.
Set particles’ tau_mass
parameter to a negative value for mass loss, positive for mass growth.
Effect Parameters
None
Particle Parameters
Only particles with their tau_mass
parameter set will have their masses affected.
Name (C type) 
Required 
Description 

tau_mass (double) 
Yes 
efolding mass loss (<0) or growth (>0) timescale 
1.6. Tides¶
1.6.1. tides_spin¶
Authors 
Tiger Lu, Hanno Rein, D. Tamayo, Sam Hadden, Rosemary Mardling, Sarah Millholland, Gregory Laughlin 
Implementation Paper 

Based on 

C Example 
PseudoSynchronization (Hut 1981), Obliquity Sculpting of Kepler Multis (Millholland & Laughlin 2019), Kozai cycles. 
Python Example 
SpinsIntro.ipynb, TidesSpinPseudoSynchronization.ipynb, TidesSpinEarthMoon.ipynb. 
This effect consistently tracks both the spin and orbital evolution of bodies under constanttime lag tides raised on both the primary and on the orbiting bodies. In all cases, we need to set masses for all the particles that will feel these tidal forces. Particles with only mass are point particles.
Particles are assumed to have structure (i.e  physical extent & distortion from spin) if the following parameters are set: physical radius particles[i].r, potential Love number of degree 2 k2 (Q/(1Q) in Eggleton 1998), and the spin angular rotation frequency vector Omega. If we wish to evolve a body’s spin components, the fully dimensional moment of inertia I must be set as well. If this parameter is not set, the spin components will be stationary. Note that if the body is a test particle, this is assumed to be the specific moment of inertia. Finally, if we wish to consider the effects of tides raised on a specific body, we must set the constant time lag tau as well.
For spins that are synchronized with a circular orbit, the constant time lag can be related to the tidal quality factor Q as tau = 1/(2*n*tau), with n the orbital mean motion. See Lu et. al (in review) and Eggleton et. al (1998) above for discussion.
Effect Parameters
None
Particle Parameters
Field (C type) 
Required 
Description 

particles[i].r (float) 
Yes 
Physical radius (required for contribution from tides raised on the body). 
k2 (float) 
Yes 
Potential Love number of degree 2. 
Omega (reb_vec3d) 
Yes 
Angular rotation frequency (Omega_x, Omega_y, Omega_z) 
I (float) 
No 
Moment of inertia (for test particles, assumed to be the specific MoI I/m) 
tau (float) 
No 
Constant time lag. If not set, defaults to 0 
1.6.2. tides_constant_time_lag¶
Authors 
Stanley A. Baronett, D. Tamayo, Noah Ferich 
Implementation Paper 

Based on 

C Example 

Python Example 
This adds constant time lag tidal interactions between orbiting bodies in the simulation and the primary, both from tides raised on the primary and on the other bodies. In all cases, we need to set masses for all the particles that will feel these tidal forces. After that, we can choose to include tides raised on the primary, on the “planets”, or both, by setting the respective bodies’ physical radius particles[i].r, k2 (potential Love number of degree 2), constant time lag tau, and rotation rate Omega. See Baronett et al. (2021), Hut (1981), and Bolmont et al. 2015 above.
If tau is not set, it will default to zero and yield the conservative piece of the tidal potential.
Effect Parameters
None
Particle Parameters
Field (C type) 
Required 
Description 

particles[i].r (float) 
Yes 
Physical radius (required for contribution from tides raised on the body). 
tctl_k2 (float) 
Yes 
Potential Love number of degree 2. 
tctl_tau (float) 
No 
Constant time lag. If not set will default to 0 and give conservative tidal potential. 
OmegaMag (float) 
No 
Angular rotation frequency. If not set will default to 0. 
1.7. Central Force¶
1.7.1. central_force¶
Authors 

Implementation Paper 

Based on 
None 
C Example 

Python Example 
Adds a general central acceleration of the form a=Acentral*r^gammacentral, outward along the direction from a central particle to the body. Effect is turned on by adding Acentral and gammacentral parameters to a particle, which will act as the central body for the effect, and will act on all other particles.
Effect Parameters
None
Particle Parameters
Field (C type) 
Required 
Description 

Acentral (double) 
Yes 
Normalization for central acceleration. 
gammacentral (double) 
Yes 
Power index for central acceleration. 
1.8. Gravity Fields¶
1.8.1. gravitational_harmonics¶
Authors 

Implementation Paper 

Based on 
None 
C Example 

Python Example 
Adds azimuthally symmetric gravitational harmonics (J2, J4) to bodies in the simulation. Current implementation assumes everything is planar, i.e. spin pole of body aligned with z axis of simulation.
Effect Parameters
None
Particle Parameters
Field (C type) 
Required 
Description 

J2 (double) 
No 
J2 coefficient 
J4 (double) 
No 
J4 coefficient 
R_eq (double) 
No 
Equatorial radius of nonspherical body used for calculating Jn harmonics 
1.9. Gas Effects¶
1.9.1. gas_dynamical_friction¶
Authors 

Implementation Paper 

Based on 

C Example 

Python Example 
Effect Parameters
Field (C type) 
Required 
Description 

rhog (double) 
Yes 
Normalization of density. Density in the disk midplane is rhog*r^alpha_rhog 
alpha_rhog (double) 
Yes 
Powerlaw slope of the powerlaw density profile. 
cs (double) 
Yes 
Normalization of the sound speed. Sound speed has profile cs*r^alpha_cs 
alpha_cs (double) 
Yes 
Powerlaw slope of the sound speed 
xmin (double) 
Yes 
Dimensionless parameter that determines the Coulomb logarithm (ln(L) =log (1/xmin)) 
hr (double) 
Yes 
Aspect ratio of the disk 
Qd (double) 
Yes 
Prefactor for geometric drag 
Particle Parameters
None.
1.10. Integration Steppers¶
These are wrapper functions to taking steps with several of REBOUND’s integrators in order to build custom splitting schemes.
1.10.1. steppers¶
Authors 

Implementation Paper 

Based on 

C Example 
None 
Python Example 
These are wrapper functions to taking steps with several of REBOUND’s integrators in order to build custom splitting schemes.
Effect Parameters
None
Particle Parameters
None
1.11. Parameter Interpolation¶
This isn’t an effect that’s loaded like the others, but an object that facilitates machineindependent interpolation of parameters that can be shared by both the C and Python versions. See the examples below for how to use them.
1.11.1. interpolation¶
Authors 
S.A. Baronett, D. Tamayo, N. Ferich 
Implementation Paper 

Based on 

C Example 

Python Example 
Effect Parameters
Not applicable. See examples.
Particle Parameters
Not applicable. See examples.
1.12. Miscellaneous Utilities¶
1.12.1. track_min_distance¶
Authors 

Implementation Paper 

Based on 
None 
C Example 
Tracking a particle’s minimum distance from the central star. 
Python Example 
For a given particle, this keeps track of that particle’s minimum distance from another body in the simulation. User should add parameters to the particular particle whose distance should be tracked.
Effect Parameters
None
Particle Parameters
Only particles with their min_distance
parameter set initially will track their minimum distance. The effect will
update this parameter when the particle gets closer than the value of min_distance
, so the user has to set it
initially. By default, distance is measured from sim>particles[0], but you can specify a different particle by setting
the min_distance_from
parameter to the hash of the target particle.
Name (C type) 
Required 
Description 

min_distance (double) 
Yes 
Particle’s mininimum distance. 
min_distance_from (uint32) 
No 
Hash for particle from which to measure distance 
min_distance_orbit (reb_orbit) 
No 
Parameter to store orbital elements at moment corresponding to min_distance (heliocentric) 