Manual page

Table of contents

1. Definitions and Uniformity
   1.1 Convention about the semimajor axis and period
2. Functions packs
   2.1 rv2oe functions
   2.2 oe2rv functions
   2.3 Polar and perifocal frame of reference
   2.4 time/position conversions
   2.5 Available constants and auxiliary math functions

Definitions and Uniformity

[top]

The function names and their arguments agree with the following convention:

  p  = semilatus rectum
  a  = semimajor axis* ( a=p case e==1 )
  e  = eccentricity
  I  = inclination
  O  = longitude of the ascending node
  w  = argument of periapsis
  f  = true anomaly
  M  = mean anomaly
  E  = eccentric anomaly
  n  = mean motion
  T  = period** ( 2*pi/n case e>=1 )
  t  = flight time since periapsis
  C3 = specific mechanical energy
  mu = mass parameter (G*mass)

Convention about the semimajor axis and period

[top]

* By convention, semimajor axis is the half of the range between the periapsis and the apoapsis. Thus, its is not fairly defined for the conics of type circle (e=0) and parabola (e=1). For these cases, the library agrees with the following convention:

• semimajor axis is equivalent to the radius of the circumference, when eccentricity is equal zero;
• semimajor axis is equivalent to the semilatus recturm of the parabola, when eccentricity is equal to the unity.

** Analogously, period by definition is the time interval that a physical phenomenon takes to repeat. Thus, the period has not a fair meaning for unbound orbits: parabolic (e = 1) and hyperbolic ( e > 1 ). For these cases, the period is equivalent to 2*pi/n, where the mean motion (n) is evaluated from the mass parameter (mu) and the specific angular momentum.

Functions packs

[top]

The library is subdivided into 5 packs:

1. rv2{oe} are the functions that convert position (r) and velocity (v) vectors into orbital elements
2. os2{rv} are the functions that convert the orbital elements into position (r) and velocity (v) vectors
3. Functions of the polar and perifocal frames are suitable to deal with 2D issues
4. time/position correlation functions are those to evaluate the anomalies in function of the flight time and vice-versa
5. Set of auxiliary math functions and useful constants

1. rv2oe functions

[top]

All of these functions must be feed with the following 7 arguments:

rv2??( mu , x , y , z , vx , vy , vz )

such that the unities must be

• [uL]³/[uT]² for mu
• [uL] for x, y and z; and
• [uL]/[uT] for vx, vy and vz;

and the ?? stands for the output quantity, which may be any of the following:

• p, a, e, I, O, w, f, n, T, C3

Evidently, the unities of the output values agree with the input unities, i.e.:

• p and a in [uL]
• T in [uT]
• n in [rad]/[uT]
• C3 in [uL]²/[uT]²
• and all of the angles I, O, w and f in radians

Note that for some types of output, not all the 7 input parameters are necessary. The mass parameter is not necessary to evaluate the positional angles, I, O and w, for instance. However, in order to avoid the user having to guess/memorize what are the needed input parameters, this set of functions keeps the uniformity of the 7 input parameters.

2. oe2rv functions

[top]

All of these functions must be feed with the following 7 arguments:

oe2??( mu , a , e , I , O , w , f )

such that the unities must be

• [uL]³/[uT]² for mu
• [uL] for a
• radians for all of the angles I, O, w and f

and the ?? stands for the output quantity, which may be any of the following:

• x, y, z, vx, vy, vz, n or T

Note that, analogously to the rv2oe, not all the 7 input parameters are necessary, but these functions keep the uniformity of the 7 input parameters.

3. Polar and perifocal frame of reference

[top]

  - polp(a,e)      returns semilatus rectum     given a and e
  - polr(a,e,f)    returns range from focus     given a, e and f
  - poldrdf(a,e,f) returns the derivative dr/dr given a, e and f


  - x_pq(a,e,w,f)     returns the x coordinate within the perifocal frame
  - y_pq(a,e,w,f)     returns the y coordinate within the perifocal frame
  - vr(mu,a,e,f)      returns the radial      component of the velocity
  - vt(mu,a,e,f)      returns the transversal component of the velocity
  - vx_pq(mu,a,e,w,f) returns the x           component of the velocity
  - vy_pq(mu,a,e,w,f) returns the y           component of the velocity
  - flightangle(e,f)  returns the flight path angle (gamma = atan(vr/vt) )

4. time/position conversions

[top]

These functions were labelled in agreement of the A2B logic, i.e., returns B as function of A:

f2E(e,f)    returns eccentric anomaly            given e and f
E2M(e,E)    returns mean      anomaly            given e and E
f2M(e,f)    returns mean      anomaly            given e and f
M2E(e,M)    returns eccentric anomaly            given e and M
E2f(e,E)    returns true      anomaly            given e and E
M2f(e,M)    returns true      anomay             given e and M
t2E(n,e,t)  returns eccentric anomaly            given n, e and t
t2f(n,e,t)  returns true      anomaly            given n, e and t
M2t(n,M)    returns the flight time since periapsis given n and M
f2t(n,e,f)  returns the flight time since periapsis given n, e and f
t2M(n,t)    returns the flight time since periapsis given n and t

You may also want to know more about the accuracy on [Newton-Raphson iterations] on solving the Kepler equations for the eccentric anomalies

5. Available constants and auxiliary math functions

[top]

The following constants were taken from GNU Units version 2.16{:target="_blank"}, and are available for convenience.
Observe that they may diverge from those values gotten from JPL Horizons{:target="_blank"}.

  liborb_zero  stands for the nominal zero for iterations, eccentricity and inclination
  liborb_deg   is one degree in radians
  liborb_hpi   is half pi
  liborb_dpi   is double pi
  deg, hpi, dpi are alias for the three prior ones.
  liborb_au    is one astronomical units in [m]
  liborb_G     is the gravitational constant in [m]³/kg s²
  liborb_musun is the mass parameter for the Sun in [m]³/s²
  analogous quantities are available for:
  liborb_mumer  Mercury
  liborb_muven  Venus
  liborb_muear  Earth
  liborb_mumoon Earth's Moon
  liborb_mumar  Mars
  liborb_mujup  Jupiter
  liborb_musat  Saturn
  liborb_muura  Uranus, and
  liborb_munep  Neptune

The following math functions are also available:

• mag2( x , y , z ) = x² + y² + z²
• mag( x , y , z ) = sqrt( x² + y² + z² )
• lin(a,b,u) is a linear interpolation of the points (0,a) (1,b) very useful for parametric mode. See [parametric mode examples]
• wrap( x , xmin , xmax ) sets x within the range [xmin:xmax]. Examples:

wrap(-30 , 0 , 360 ) returns 330
wrap( 7.853982 , 0 , 2*pi ) returns 1.570796