Copyright
Introduction
Files
Functions
Structs
Enums

Copyright

Documentation for the kepler library
Copyright (C) 2010 Shiva Iyer {shiva.iyer AT g m a i l DOT c o m}

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.

Introduction

The kepler library provides a set of routines for astronomical calculations.
The library is implemented in ANSI C and the optional pykepler package provides
support for programs written in Python.

The intent is to provide the basic building blocks necessary for more advanced
applications. Consequently, no attempt has been made to provide an user interface
or to write programs that meet various needs (observation, historical research etc.).

Files

aberration.c
aberration.h
Implementation of the Ron-Vondrak theory of aberration
coordinates.c
coordinates.h
Coordinate transformations and rotations
delta-t.c
delta-t.h
Approximation of Delta-T (TT - UT1)
earth_figure.c
earth_figure.h
Values related to the oblateness of the Earth
elp82b.c
elp82b.h
Implementation of the ELP2000-82B theory for lunar coordinates
fund_args.c
fund_args.h
Values of fundamental lunisolar, planetary and precession arguments
iau2000a_nutation.c
iau2000a_nutation.h
Nutation calculations using the IAU 2000A model
iau2006_precession.c
iau2006_precession.h
Precession calculations using the IAU 2006 model
julian_date.c
julian_date.h
Julian date conversions
kepler.h Constants, macros and utility functions
magnitude.c
magnitude.h
Apparent magnitudes of minor planets and comets
mpc_file.c
mpc_file.h
Minor Planet Center orbit database parser
orbital_elements.c
orbital_elements.h
Reduction of orbital elements to ephemeris
parallax.c
parallax.h
Values for the geocentric parallax of celestial bodies
pluto.c
pluto.h
Implementation of the PLUTO95 theory for Pluto's coordinates
sidereal_time.c
sidereal_time.h
Sidereal time calculations using the IERS 2003 conventions
vsop87.c
vsop87.h
Implementation of the VSOP87 theory for the coordinates of the Sun and planets

Functions

aberration.c

void aberration_earth_velocity(struct julian_date *tdb, struct rectangular_coordinates *vel)

Calculates the components of the earth's velocity.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
vel: The Earth's velocity components in 10**(-8) AU/day. The reference frame is the equinox & equator of J2000.

void annual_aberration(struct julian_date *tdb, struct equatorial_coordinates *e,double *d_ra, double *d_dec)

Calculates the annual aberration in right ascension and declination.

tdb: TDB to be used for calculations.
e: Equatorial coordinates of the celestial body.
d_ra: Aberration in right ascension.
d_dec: Aberration in declination.

coordinates.c

void rectangular_to_spherical(struct rectangular_coordinates *pla, struct rectangular_coordinates *ear, double *lon, double *lat, double *rad)

Converts the heliocentric rectangular coordinates of a celestial body to geocentric spherical coordinates.
Since no rotation is involved, the resulting coordinates will be in the same reference frame (xy plane) as the
original coordinates.

pla: The body's heliocentric rectangular coordinates. Must be in the same reference frame and units as ear.
ear: The Earth's heliocentric rectangular coordinates. Must be in the same reference frame and units as pla.
lon: The body's geocentric longitude in radians.
lat: The body's geocentric latitude in radians.
rad: The body's geocentric distance in the units of pla and ear.

void spherical_to_rectangular(double lon, double lat, double rad, struct rectangular_coordinates *rec)

Converts the spherical coordinates of a celestial body to rectangular coordinates with the same origin and
reference frame (xy plane).

lon: The body's longitude in radians.
lat: The body's latitude in radians.
rad: The body's distance from the central body.
rec: The body's rectangular coordinates in the same units as rad.

double phase_angle(struct rectangular_coordinates *obj, struct rectangular_coordinates *ear)

Calculates the Sun-body-Earth phase angle.

obj: The body's heliocentric rectangular coordinates. Must be in the same reference frame and units as ear.
ear: The Earth's heliocentric rectangular coordinates. Must be in the same reference frame and units as obj.

Return: The Sun-body-Earth phase angle in radians.

void equatorial_to_ecliptic(struct equatorial_coordinates *equ, double obl, struct ecliptic_coordinates *ecl)

Converts the geocentric equatorial coordinates of a celestial body to geocentric ecliptic coordinates.

equ: The body's geocentric equatorial coordinates.
obl: The obliquity of the ecliptic in radians.
ecl: The body's geocentric ecliptic coordinates.

void ecliptic_to_equatorial(struct ecliptic_coordinates *ecl, double obl, struct equatorial_coordinates *equ)

Converts the geocentric ecliptic coordinates of a celestial body to geocentric equatorial coordinates.

ecl: The body's geocentric ecliptic coordinates.
obl: The obliquity of the ecliptic in radians.
equ: The body's geocentric equatorial coordinates.

void equatorial_to_horizontal(double ha, double decl, double lat, struct horizontal_coordinates *hor)

Converts the geocentric equatorial coordinates of a celestial body to horizontal coordinates.

ha: The body's local hour angle in radians.
decl: The body's declination in radians.
lat: The observer's geographic latitude in radians.
hor: The body's horizontal coordinates.

void horizontal_to_equatorial(struct horizontal_coordinates *hor, double lat, double *ha, double *decl)

Converts the horizontal coordinates of a celestial body to geocentric equatorial coordinates.

hor: The body's horizontal coordinates.
lat: The observer's geographic latitude in radians.
ha: The body's local hour angle in radians.
decl: The body's declination in radians.

void rotate_rectangular(double mat[3][3], struct rectangular_coordinates *pos)

Applies a rotation matrix to a body's rectangular coordinates.

mat: The rotation matrix.
pos: The coordinates to be rotated in-place.

void rotate_equatorial(double mat[3][3], struct equatorial_coordinates *pos)

Applies a rotation matrix to a body's geocentric equatorial coordinates. This function can be used to apply the
IAU2006/2000A precession/nutation matrices.

mat: The rotation matrix.
pos: The coordinates to be rotated in-place.

void rotate_ecliptic_to_equator(double obl, struct rectangular_coordinates *pos)

Rotates rectangular coordinates in the ecliptic frame to the equatorial frame.

obl: The obliquity of the ecliptic in radians.
pos: The coordinates to be rotated in-place.

delta-t.c

int delta_t(int year, int month, double *delta_t, double *correction)

Returns an approximate value for Delta-T (TT - UT1) valid for a limited historical period.

year: Astronomical year number between 2000BC and 3000AD inclusive.
month: Month of the year.
delta_t: An approximate value for Delta-T in seconds.
correction: A correction, in seconds, to be added to Delta-T for years before 1955AD or after 2005AD
and when used in conjunction with NASA's publication "Five millennium canon of solar eclipses".

Return: SUCCESS: Delta-T calculated successfully.
ERR_INVALID_DATE: Invalid year or month specified.

earth_figure.c

void earth_figure_values(double geog_lat, double height_msl, double *gc_lat, double *gc_radius)

Calculates various values related to the oblateness of the Earth.

geog_lat: The observer's geographic latitude in radians.
height_msl: The observer's height above mean sea level in meters.
gc_lat: The observer's geocentric latitude in radians.
gc_radius: The observer's geocentric radius as a fraction of the Earth's equatorial radius.

elp82b.c

void elp82b_coordinates(struct julian_date *tdb,struct ecliptic_coordinates *ecl, double *radius)

Calculates the Moon's geocentric ecliptic coordinates and distance using the ELP 2000-82B lunar theory in its entirety.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
ecl: The Moon's geocentric ecliptic coordinates. The reference frame is the equinox & ecliptic of J2000.
radius: The Moon's distance from the Earth in KM.

fund_args.c

double fundamental_argument(enum fund_argument arg, double t)

Calculates values for the various fundamental arguments used in the planetary, lunar, precession and nutation models.

arg: One of the values from the fund_argument enumeration.
t: Number of Julian centuries of TDB since 2000-01-01 12h TDB. TT may be used for all but the most exacting applications.

Return: -1 if the arg parameter is invalid. The value of the fundamental argument in radians otherwise.

iau2000a_nutation.c

double iau2000a_mean_obliquity(struct julian_date *tdb)

Calculates the mean obliquity of the ecliptic using the IAU 2000 formula.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.

Return: The mean obliquity of the ecliptic in radians.

void iau2000a_nutation(struct julian_date *tdb, double *d_psi, double *d_epsilon)

Calculates the nutation in longitude and obliquity using the IAU 2000A nutation model in its entirety.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
d_psi: The nutation in longitude expressed in radians.
d_epsilon: The nutation in obliquity expressed in radians.

void iau2000a_nutation_matrix(struct julian_date *tdb, double nut_matrix[3][3])

Calculates the nutation matrix using the IAU 2000A nutation model in its entirety. The resulting matrix may
be used in the rotation of coordinates.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
nut_matrix: The nutation matrix.

iau2006_precession.c

void iau2006_precession_matrix(struct julian_date *tdb, int toJ2000, double prec_matrix[3][3])

Calculates the precession matrix using the IAU 2006 precession model in its entirety. The resulting matrix may
be used in the rotation of coordinates.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
toJ2000: If 0, the resulting matrix is for precessing from J2000 to another epoch. Otherwise, the precession
is from another epoch to J2000.
prec_matrix: The precession matrix.

julian_date.c

int calendar_to_julian_date(int year, int month, int day, struct julian_date *jd)

Calculates the Julian Day Number for a date in the proleptic Gregorian calendar. The Gregorian calendar reform is
ignored and dates prior to Jan. 1, 4800BC are not supported.

year: Year number using astronomical reckoning and after 4800BC.
month: Month of the year.
day: Day of the month.
jd: The calculated Julian Day Number.

Return: SUCCESS: Julian date calculated successfully.
ERR_INVALID_DATE: Gregorian date specified is invalid or out of range.

int julian_to_calendar_date(struct julian_date *jd, int *year, int *month, int *day, double *day_fraction)

Calculates the date in the proleptic Gregorian calendar that corresponds to the given Julian Day Number. The Gregorian
calendar reform is ignored.

jd: The Julian Day Number. Must correspond to a date on or after Jan. 1, 4800BC in the proleptic Gregorian calendar.
year: Year number using astronomical reckoning.
month: Month of the year.
day: Day of the month.
day_fraction: Fractional part of day (0 = midnight, 0.5 = noon).

Return: SUCCESS: Gregorian date calculated successfully.
ERR_INVALID_DATE: Julian Day Number specified is out of range.

kepler.h

static __inline__ double reduce_angle(double angle, double limit)

Returns an angle that is between 0 and limit.

angle: The angle to be reduced.
limit: The maximum value for the angle.

Return: An angle that is between 0 and limit.

static __inline__ void degrees_to_dms(double d, struct deg_min_sec *out)

Converts an angle in decimal degrees to degrees/minutes/seconds form.

d: The angle to convert.
out: Converted value. If d is negative, the members of out will be negative.

magnitude.c

double minor_planet_magnitude(struct rectangular_coordinates *obj,struct rectangular_coordinates *ear, double abs_mag, double slope)

Calculates the apparent magnitude of a minor planet.

obj: The minor planet's heliocentric rectangular coordinates. Must be in the same reference frame and units as ear (AU).
ear: The Earth's heliocentric rectangular coordinates. Must be in the same reference frame and units as obj (AU).
abs_mag: The mean absolute visual magnitude of the minor planet, H.
slope: The magnitude slope parameter of the minor planet, G.

Return: The minor planet's apparent magnitude.

double comet_magnitude(struct rectangular_coordinates *obj, struct rectangular_coordinates *ear, double abs_mag, double slope)

Calculates the apparent magnitude of a comet.

obj: The comet's heliocentric rectangular coordinates. Must be in the same reference frame and units as ear (AU).
ear: The Earth's heliocentric rectangular coordinates. Must be in the same reference frame and units as obj (AU).
abs_mag: The mean absolute visual magnitude of the comet, H.
slope: The magnitude slope parameter of the comet, G.

Return: The comet's apparent magnitude.

mpc_file.c

int minor_planet_info(char *data, struct julian_date *tt, struct mpc_body *info)

Parses data in the MPC's Orbit Database for minor planets. For details on the format, see http://www.cfa.harvard.edu/iau/info/MPOrbitFormat.html.
Download the database from http://www.cfa.harvard.edu/iau/MPCORB.html.

data: A line of data from the MPCORB minor planet database file.
tt: TT to be used for calculations.
info: The minor planet's details and heliocentric coordinates. The reference frame is the equinox & ecliptic of J2000.

Return: SUCCESS: The data was parsed and the coordinates were calculated.
ERR_INVALID_DATA: The data was in an unrecognized format.
ERR_CONVERGENCE: The solution to Kepler's equation didn't converge
to the required precision within the specified number of iterations.

int comet_info(char *data, struct julian_date *tt, struct mpc_body *info)

Parses data in the MPC's Orbit Database for comets. For details on the format, see http://www.cfa.harvard.edu/iau/info/CometOrbitFormat.html.
Download the database from http://www.cfa.harvard.edu/iau/MPCORB.html.

data: A line of data from the MPCORB comet database file.
tt: TT to be used for calculations.
info: The comet's details and heliocentric coordinates. The reference frame is the equinox & ecliptic of J2000.

Return: SUCCESS: The data was parsed and the coordinates were calculated.
ERR_INVALID_DATA: The data was in an unrecognized format.
ERR_CONVERGENCE: The solution to Kepler's equation didn't converge to the required precision within the specified number of iterations.

orbital_elements.c

int elements_to_ephemeris(struct julian_date *tt, struct orbital_elements *elt, struct rectangular_coordinates *eph)

Calculates the heliocentric rectangular coordinates of a celestial body given its osculating orbital elements.

tt: TT to be used for calculations.
elt: The body's osculating orbital elements.
eph: The body's heliocentric rectangular coordinates in AU. The reference frame is the equinox & ecliptic of J2000.

Return: SUCCESS: If the coordinates were calculated successfully.
ERR_INVALID_ECCENTRICITY: If the body's eccentricity is negative.
ERR_CONVERGENCE: If Kepler's equation didn't converge to the required precision within the specified number of iterations.

int eccentric_anomaly(double mean_ano, double ecc, double *ecc_ano)

Solves Kepler's equation for elliptic orbits and returns the resulting value of the eccentric anomaly.

mean_ano: The celestial body's mean anomaly in radians.
ecc: The eccentricity of the orbit.
ecc_ano: On success, the body's eccentric anomaly in radians.

Return: SUCCESS: If Kepler's equation was solved successfully.
ERR_CONVERGENCE: If Kepler's equation didn't converge to the required precision within the specified number of iterations.

int hyperbolic_anomaly(double mean_ano, double ecc, double *hyp_ano)

Solves Kepler's equation for hyperbolic orbits and returns the resulting value of the hyperbolic anomaly.

mean_ano: The celestial body's mean anomaly in radians.
ecc: The eccentricity of the orbit.
hyp_ano: On success, the body's hyperbolic anomaly in radians.

Return: SUCCESS: If Kepler's equation was solved successfully.
ERR_CONVERGENCE: If Kepler's equation didn't converge to the required precision within the specified number of iterations.

parallax.c

void geocentric_parallax(double hr_ang, double decl, double distance, double geog_lat, double height_msl, double *d_ra, double *d_decl)

Calculates the geocentric parallax in the equatorial coordinates of a celestial body.

hr_ang: The body's local hour angle in radians.
decl: The body's declination in radians.
distance: The body's distance from the Earth in AU.
geog_lat: The observer's geographic latitude in radians.
height_msl: The observer's height above mean sea level in meters.
d_ra: The parallax in right ascension expressed in radians.
d_decl: The parallax in declination expressed in radians.

pluto.c

int pluto_coordinates(struct julian_date *tdb, struct rectangular_coordinates *pos)

Calculates the heliocentric rectangular coordinates of Pluto using an analytical model developed at the Bureau des Longitudes (Pluto95).
This theory is valid only between Jan 01, 1700 (inclusive) and Jan 24, 2100 (exclusive).

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications. Must be between 1700-01-01 and 2100-01-24.
pos: On success, the heliocentric rectangular coordinates of Pluto in AU. The reference frame is the equinox and equator of J2000.

Return: SUCCESS: If the coordinates were calculated successfully.
ERR_INVALID_DATE: If tdb was out of range for the theory.

sidereal_time.c

double mean_sidereal_time(struct julian_date *ut1, struct julian_date *tdb, double longitude)

Calculates the local mean sidereal time using the latest IAU/IERS conventions.

ut1: UT1 for calculating the Earth Rotation Angle.
tdb: TDB to be used for calculating the LMST. TT may be used for all but the most exacting applications.
longitude: The observer's longitude in radians, positive east of Greenwich.

Return: The local mean sidereal time in radians, between 0 and 2*PI.

double apparent_sidereal_time(struct julian_date *ut1, struct julian_date *tdb, double longitude)

Calculates the local apparent sidereal time using the latest IAU/IERS conventions. Apparent sidereal time takes
into account the motion of the equinox due to nutation.

ut1: UT1 for calculating the Earth Rotation Angle.
tdb: TDB to be used for calculating the LAST. TT may be used for all but the most exacting applications.
longitude: The observer's longitude in radians, positive east of Greenwich.

Return: The local apparent sidereal time in radians, between 0 and 2*PI.

double equation_of_the_equinoxes(struct julian_date *tdb)

Calculates the value of the equation of the equinoxes. This accounts for the motion of the equinox due to nutation.

tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.

Return: The value of the equation of the equinoxes, in radians.

vsop87.c

int vsop87_coordinates(enum solar_system_planets planet, struct julian_date *tdb, struct rectangular_coordinates *pos)

Calculates a major planet's heliocentric rectangular coordinates using the VSOP87 (version A) theory in its entirety.

planet: Enumeration that identifies the planet for calculations.
tdb: TDB to be used for calculations. TT may be used for all but the most exacting applications.
pos: The planet's heliocentric rectangular coordinates in AU. The reference frame is the equinox & ecliptic of J2000.

Return: SUCCESS: If the coordinates have been calculated successfully.
ERR_INVALID_PLANET: If the planet's identifier is invalid.

void vsop87_ecliptic_to_equator(struct rectangular_coordinates *pos)

Rotates a body's coordinates from the dynamical ecliptic frame of J2000 to the equatorial frame of J2000/FK5.

pos: The coordinates to be rotated in-place

Structs

coordinates.h

Used for rectangular coordinates. The origin and orientation of the xy axes are application specific.
The xy plane could be the ecliptic or the Earth's equator.

struct rectangular_coordinates {
double x; /* x-coordinate. The unit is application specific. */
double y; /* y-coordinate. The unit is application specific. */
double z; /* z-coordinate. The unit is application specific. */
};

Used for coordinates in the Earth's equatorial frame.

struct equatorial_coordinates {
double right_ascension; /* Right ascension in radians. */
double declination; /* Declination in radians. */
};

Used for ecliptic coordinates. The origin is application specific.

struct ecliptic_coordinates {
double longitude; /* Longitude in radians. */
double latitude; /* Latitude in radians. */
};

Used for horizontal coordinates.

struct horizontal_coordinates {
double azimuth; /* Azimuth in radians. Clockwise from the South. */
double altitude; /* Altitude in radians. */
};

julian_date.h

This structure is used wherever a Julian Day Number (JDN) is expected or returned. Two doubles are used to preserve precision.
A given JDN may be partitioned between date1 & date2 in any convenient manner. The JDN that corresponds to this structure is date1 + date2.

struct julian_date {
double date1;
double date2;
};

kepler.h

Used in conversions from decimal degrees to degree/minute/second form.

struct deg_min_sec {
int degrees;
int minutes;
double seconds;
};

mpc_file.h

Used to store the details of a celestial body in the MPCORB Database.

struct mpc_body {
char id[12]; /* The body's ID or unpacked provisional designation. */
char name[36]; /* The body's name, if it is included in the file. */
enum mpc_body_types type; /* The type of body. */

double magnitude; /* The body's absolute magnitude, H. */
double slope; /* Slope parameter, G. */

struct orbital_elements elements; /* The body's orbital elements. */

/*
* The body's coordinates at the desired epoch. For minor planets and
* comets, the origin is the Sun and the reference frame is the equinox
* and ecliptic of J2000.
*/
struct rectangular_coordinates position;
};

orbital_elements.h

Used wherever the osculating orbital elements of a celestial body are expected or returned.
These values may be obtained from the circulars of the Minor Planet Center, the Astronomical Almanac
or other publications. See mpc_file.c for some ways in which this structure is used.

struct orbital_elements {
struct julian_date epoch; /* Epoch of osculation. */

double mean_anomaly; /* Mean anomaly in radians at epoch. */
double daily_motion; /* Daily motion in radians/day. */

double perihelion; /* Perihelion distance in AU. */
double eccentricity; /* Eccentricity of the orbit. */
/* The values for the orbit's orientation must be referred to J2000. */
double arg_perihelion; /* Argument of the perihelion in radians. */
double lon_asc_node; /* Longitude of the ascending node in radians. */
double inclination; /* Inclination of the orbit in radians. */
};

Enums

fund_args.h

Enum for the various fundamental arguments used throughout the program. These values are parameters to fundamental_argument().

enum fund_argument {
ARG_LONGITUDE_MERCURY = 0,
ARG_LONGITUDE_VENUS,
ARG_LONGITUDE_EARTH,
ARG_LONGITUDE_MARS,
ARG_LONGITUDE_JUPITER,
ARG_LONGITUDE_SATURN,
ARG_LONGITUDE_URANUS,
ARG_LONGITUDE_NEPTUNE,
ARG_PRECESSION,
ARG_ANOMALY_MOON,
ARG_ANOMALY_SUN,
ARG_LATITUDE_MOON,
ARG_ELONGATION_MOON,
ARG_LONGITUDE_NODE,
ARG_LONGITUDE_MOON
};

kepler.h

Identifiers for the planets in the solar system. Following the IAU's resolutions of 2006, Pluto is not considered a planet.

enum solar_system_planets {
MERCURY,
VENUS,
EARTH,
MARS,
JUPITER,
SATURN,
URANUS,
NEPTUNE
};

mpc_file.h

The types of celestial bodies included in the MPCORB Database.

enum mpc_body_types {
MINOR_PLANET,
LONG_PERIOD_COMET,
SHORT_PERIOD_COMET,
DEFUNCT_COMET,
UNCERTAIN_COMET
};