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 quick-start guide (Quick Start Guide) or C quick-start 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

Kajtazi et al 2022.

Based on

Pichierri et al 2018.

C example

Inner disk edge.

Python example

InnerDiskEdge.ipynb.

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 Ali-Dib

Implementation Paper

Ali-Dib et al., 2021 AJ.

Based on

Hahn & Malhotra 2005.

C Example

Exponential Migration

Python Example

ExponentialMigration.ipynb.

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

  1. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Lee & Peale 2002.

C Example

Migration and other orbit modifications

Python Example

Migration.ipynb, EccAndIncDamping.ipynb.

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., two-body) 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

Kajtazi et al 2022.

Based on

Cresswell & Nelson 2008, and Pichierri et al 2018.

C example

Type I migration.

Python example

TypeIMigration.ipynb.

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

  1. Tamayo, H. Rein

Implementation Paper

Kostov et al., 2016.

Based on

Papaloizou & Larwood 2000.

C Example

Migration and other orbit modifications

Python Example

Migration.ipynb EccAndIncDamping.ipynb.

This applies physical forces that orbit-average 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

  1. Rein, D. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Nobili and Roxburgh 1986.

C Example

Post-Newtonian correction from general relativity

Python Example

GeneralRelativity.ipynb.

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 velocity-dependent, it automatically keeps WHFast symplectic. Nice if you have a single-star 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

  1. Shi, H. Rein, D. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Newhall et al. 1983.

C Example

Post-Newtonian correction from general relativity

Python Example

GeneralRelativity.ipynb.

This algorithm incorporates the first-order post-newtonian 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

  1. Akmal

Implementation Paper

None

Based on

Park et al..

C Example

Adding Lense-Thirring effect

Python Example

LenseThirring.ipynb.

Adds Lense-Thirring 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

  1. Shi, D. Tamayo, H. Rein

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Anderson et al. 1975.

C Example

Post-Newtonian correction from general relativity

Python Example

GeneralRelativity.ipynb.

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

Veras et al., 2015, Veras et al., 2019.

C Example

Yarkovsky effect on a small body.

Python Example

YarkovskyEffect.ipynb.

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

Stefan-Boltzmann 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

  1. Rein, D. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Burns et al. 1979.

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 Poynting-Robertson 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

  1. Rein

Based on

Rein and Papaloizou 2009.

Implementation Paper

Rein and Choksi 2022.

C Example

Stochastic forces on a single planet

Python Example

StochasticForces.ipynb, StochasticForcesCartesian.ipynb,

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

Auto-correlation 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

  1. Tamayo

Implementation Paper

Kostov et al., 2016.

Based on

None

C Example

Exponential mass loss/gain

Python Example

ModifyMass.ipynb.

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

e-folding 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

Lu et al., 2023.

Based on

Eggleton et al. 1998.

C Example

Pseudo-Synchronization (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 constant-time 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/(1-Q) 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

Baronett et al., 2022.

Based on

Hut 1981, Bolmont et al., 2015.

C Example

Constant time lag model for tides (Hut 1981).

Python Example

TidesConstantTimeLag.ipynb.

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

  1. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

None

C Example

General central force.

Python Example

CentralForce.ipynb.

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

  1. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

None

C Example

Adding gravitational harmonics (J2, J4) to particles

Python Example

J2.ipynb.

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

  1. Generozov, H. Perets

Implementation Paper

Generozov and Perets 2022

Based on

Ostriker 1999 (with simplifications), Just et al 2012.

C Example

Gas dynamical friction

Python Example

gas_dynamical_friction.ipynb

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

Power-law slope of the power-law density profile.

cs (double)

Yes

Normalization of the sound speed. Sound speed has profile cs*r^alpha_cs

alpha_cs (double)

Yes

Power-law 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

  1. Tamayo, H. Rein

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

Rein and Liu, 2012.

C Example

None

Python Example

CustomSplittingIntegrationSchemes.ipynb.

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 machine-independent 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

Baronett et al., 2022.

Based on

Press et al., 1992.

C Example

Stellar evolution with interpolated mass data

Python Example

ParameterInterpolation.ipynb.

Effect Parameters

Not applicable. See examples.

Particle Parameters

Not applicable. See examples.

1.12. Miscellaneous Utilities

1.12.1. track_min_distance

Authors

  1. Tamayo

Implementation Paper

Tamayo, Rein, Shi and Hernandez, 2019.

Based on

None

C Example

Tracking a particle’s minimum distance from the central star.

Python Example

TrackMinDistance.ipynb.

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)