Input/Setup Functions¶

group SetupRebFunctions

List of the built-in setup helper functions

Derivative functions

This function calculates the first/second derivative of a Keplerian orbit.

Derivatives of Keplerian orbits are required for variational equations, in particular for optimization problems. The derivative is calculated with respect to the variables that appear in the function name. One variable implies that a first derivative is returned, two variables implies that a second derivate is returned. Classical orbital parameters and those introduced by Pal (2009) are supported. Pal coordinates have the advantage of being analytical (i.e. infinite differentiable). Classical orbital parameters may have singularities, for example when e is close to 0. Note that derivatives with respect to Cartesian coordinates are trivial and therefore not implemented as seperate functions. The following variables are supported: a, e, inc, f, omega, Omega, h, k, ix, iy and m (mass).

Return
The derivative as a particle structre. Each structure element is a derivative.
Parameters
• G: The gravitational constant
• primary: The primary of the Keplerian orbit
• po: The original partical for which the derivative is to be calculated.

struct reb_particle reb_derivatives_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_h(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k_k(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_h_h(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_lambda_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_h_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k_h(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_a(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_ix_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_iy_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_h_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_lambda_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_lambda_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_h_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_k_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_ix_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_h(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_k(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_a(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_lambda(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_h(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_k(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_ix(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_iy(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_m(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e_e(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_inc(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_inc_inc(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_Omega_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_omega_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_f_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_e(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_inc(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_a_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e_inc(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_e_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_e(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_inc_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_inc_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_inc_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_inc(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_omega_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_Omega_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_Omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_omega_f(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_omega(double G, struct reb_particle primary, struct reb_particle po)
struct reb_particle reb_derivatives_m_f(double G, struct reb_particle primary, struct reb_particle po)

Enums

enum reb_input_binary_messages

Enum describing possible errors that might occur during binary file reading.

Values:

REB_INPUT_BINARY_WARNING_NONE = 0
REB_INPUT_BINARY_ERROR_NOFILE = 1
REB_INPUT_BINARY_WARNING_VERSION = 2
REB_INPUT_BINARY_WARNING_POINTERS = 4
REB_INPUT_BINARY_WARNING_PARTICLES = 8
REB_INPUT_BINARY_ERROR_FILENOTOPEN = 16
REB_INPUT_BINARY_ERROR_OUTOFRANGE = 32
REB_INPUT_BINARY_ERROR_SEEK = 64
REB_INPUT_BINARY_WARNING_FIELD_UNKOWN = 128
REB_INPUT_BINARY_ERROR_INTEGRATOR = 256

Functions

double reb_tools_M_to_f(double e, double M)

returns the true anomaly for a given eccentricity and mean anomaly

Return
True anomaly
Parameters
• e: Eccentricity
• M: Mean anomaly

struct reb_particle reb_tools_orbit2d_to_particle(double G, struct reb_particle primary, double m, double a, double e, double omega, double f)

Initialize a particle on an orbit in the xy plane.

Return
Returns a particle structure with the given orbital parameters.
Parameters
• G: Gravitational constant.
• primary: Particle structure for the orbit’s reference body.
• m: Mass of the particle.
• a: Semi-major axis of the particle.
• e: Eccentricity of the particle.
• omega: Pericenter of the particle.
• f: true anomaly of the particle.

struct reb_particle reb_tools_orbit_to_particle_err(double G, struct reb_particle primary, double m, double a, double e, double i, double Omega, double omega, double f, int *err)

Initialize a particle on a 3D orbit, passing an error variable to flag why particle is set to nan. See Fig. 2.13 of Murray & Dermott Solar System Dynamics for diagram.

Error codes:

1. Can’t set e exactly to 1.
2. Eccentricity can never be less than zero.
3. Bound orbit (a>0) can’t have e>1.
4. Unbound orbit (a<0) can’t have e<1.
5. Unbound orbit can’t have f set beyond the asymptotes defining the particle.
Return
Returns a particle structure with the given orbital parameters.
Parameters
• G: Gravitational constant.
• primary: Particle structure for the orbit’s reference body.
• m: Mass of the particle.
• a: Semi-major axis of the particle.
• e: Eccentricity of the particle.
• i: inclination of the particle to the reference plane..
• Omega: Longitude of the ascending node of the particle.
• omega: argument of pericenter of the particle.
• f: true anomaly of the particle.
• err: Pointer to error code that wil be set by this function. Used for checking why particle was set to nans.

struct reb_particle reb_tools_orbit_to_particle(double G, struct reb_particle primary, double m, double a, double e, double i, double Omega, double omega, double f)

Initialize a particle on a 3D orbit. See Fig. 2.13 of Murray & Dermott Solar System Dynamics for diagram.

Return
Returns a particle structure with the given orbital parameters.
Parameters
• G: Gravitational constant.
• primary: Particle structure for the orbit’s reference body.
• m: Mass of the particle.
• a: Semi-major axis of the particle.
• e: Eccentricity of the particle.
• i: inclination of the particle to the reference plane.
• Omega: Longitude of the ascending node of the particle.
• omega: argument of pericenter of the particle.
• f: true anomaly of the particle.

struct reb_orbit reb_tools_particle_to_orbit_err(double G, struct reb_particle p, struct reb_particle primary, int *err)

This function calculates orbital elements for a given particle, passing an error variable to flag why orbit is set to nan.

Error codes:

1. Primary has no mass.
2. Particle and primary positions are the same.
Return
reb_orbit struct with orbital parameters.
Parameters
• G: The gravitational constant.
• p: reb_particle for which the orbit is calculated.
• primary: Particle structure for the orbit’s reference body.
• err: error code for checking why orbit was set to nans.

struct reb_orbit reb_tools_particle_to_orbit(double G, struct reb_particle p, struct reb_particle primary)

This function calculates orbital elements for a given particle.

Return
reb_orbit struct with orbital parameters.
Parameters
• G: The gravitational constant.
• p: reb_particle for which the orbit is calculated.
• primary: Particle structure for the orbit’s reference body.

struct reb_particle reb_tools_pal_to_particle(double G, struct reb_particle primary, double m, double a, double lambda, double k, double h, double ix, double iy)

Initialize a particle on a 3D orbit. See Pal 2009 for a definition of these coordinates. Pal describes a coordinate system for Keplerian Orbits that is analytical (i.e. infinitely differentiable) between spatial coordinates and orbital elements. See http://adsabs.harvard.edu/abs/2009MNRAS.396.1737P.

Return
Returns a particle structure with the given orbital parameters.
Parameters
• G: Gravitational constant.
• primary: Particle structure for the orbit’s reference body.
• m: Mass of the particle.
• a: Semi-major axis of the particle.
• lambda: longitude.
• k: Eccentricity/pericenter k = e*cos(w).
• h: Eccentricity/pericenter h = e*sin(w).
• ix: Inclination, x component.
• iy: Inclination, y component.

struct reb_simulation *reb_create_simulation_from_binary(char *filename)

Also initialises the particles array with data form the binary file. This can be used to restart a simualtion.

Return
Returns a pointer to a REBOUND simulation.
Parameters
• filename: Filename to be read.

void reb_create_simulation_from_binary_with_messages(struct reb_simulation *r, char *filename, enum reb_input_binary_messages *messages)

Similar to reb_create_simulation_from_binary() but allows takes simulation as an argument (will be overwritten) and allows for manual message handling.

void reb_tools_init_plummer(struct reb_simulation *r, int _N, double M, double R)

This function sets up a Plummer sphere.

Parameters
• r: The rebound simulation to be considered
• _N: Number of particles in the plummer sphere.
• M: Total mass of the cluster.
• R: Characteristic radius of the cluster.

char *reb_read_char(int argc, char **argv, const char *argument)

Reads arguments from the command line.

Return
Returns NULL if argument was not given. Return the argument otherwise.
Parameters
• argc: Number of command line arguments.
• argv: Array of command line arguments.
• argument: Argument to look for.

double reb_read_double(int argc, char **argv, const char *argument, double _default)

Reads arguments as a double value from the command line.

Return
Returns _default if argument was not given. Return the argument converted to double otherwise.
Parameters
• argc: Number of command line arguments.
• argv: Array of command line arguments.
• argument: Argument to look for.
• _default: Default value.

int reb_read_int(int argc, char **argv, const char *argument, int _default)

Reads arguments as a int value from the command line.

Return
Returns _default if argument was not given. Return the argument converted to int otherwise.
Parameters
• argc: Number of command line arguments.
• argv: Array of command line arguments.
• argument: Argument to look for.
• _default: Default value.