Input/Setup Functions¶

group
SetupRebFunctions
List of the builtin 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 constantprimary
: The primary of the Keplerian orbitpo
: 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
: EccentricityM
: 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
: Semimajor 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:
 Can’t set e exactly to 1.
 Eccentricity can never be less than zero.
 Bound orbit (a>0) can’t have e>1.
 Unbound orbit (a<0) can’t have e<1.
 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
: Semimajor 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
: Semimajor 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:
 Primary has no mass.
 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
: Semimajor 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)¶ Reads a binary file.
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.