Macros
#define	NOVAS_ID_TYPES (NOVAS_ID_CALCEPH + 1)

Typedefs
typedef int(*	novas_ephem_provider) (const char name, long id, double jd_tdb_high, double jd_tdb_low, enum novas_origin origin, double pos, double vel)

typedef short(*	novas_planet_provider) (double jd_tdb, enum novas_planet body, enum novas_origin origin, double position, double velocity)

typedef short(*	novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double position, double velocity)

Enumerations
enum	novas_id_type { NOVAS_ID_NAIF = 0 , NOVAS_ID_CALCEPH }

Functions
short	earth_sun_calc (double jd_tdb, enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	earth_sun_calc_hp (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double position, double velocity)

void	enable_earth_sun_hp (int value)

novas_ephem_provider	get_ephem_provider ()

novas_planet_provider	get_planet_provider ()

novas_planet_provider_hp	get_planet_provider_hp ()

enum novas_planet	naif_to_novas_planet (long id)

long	novas_to_dexxx_planet (enum novas_planet id)

long	novas_to_naif_planet (enum novas_planet id)

short	planet_eph_manager (double jd_tdb, enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	planet_eph_manager_hp (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	planet_ephem_provider (double jd_tdb, enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	planet_ephem_provider_hp (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	planet_jplint (double jd_tdb, enum novas_planet body, enum novas_origin origin, double position, double velocity)

short	planet_jplint_hp (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double position, double velocity)

double *	readeph (int mp, const char name, double jd_tdb, int error)

int	set_ephem_provider (novas_ephem_provider func)

int	set_planet_provider (novas_planet_provider func)

int	set_planet_provider_hp (novas_planet_provider_hp func)

short	solarsystem (double jd_tdb, short body, short origin, double position, double velocity)

short	solarsystem_hp (const double jd_tdb[2], short body, short origin, double position, double velocity)

Detailed Description

Author: G. Kaplan and A. Kovacs

SuperNOVAS header for custom solar-system ephemeris calculations for major planets plus the Sun, Moon, and the Solar-system barycenter (and as of v1.2 also the Earth-Moon Barycenter and the barycenter of the Pluto system).

The source files solsys-calceph.c and solsys-cspice.c provide implementations that interface with the CALCEPH C library and the NAIF CSPICE Toolkit, respectively. CSPICE is the canocical library for handling JPL (SPK) ephemeris data, while CALCEPH is a more modern tool, which allows handling most types of JPL ephemerides, as well INPOP 2.0/3.0 format data files.

The source files solsys1.c, solsys2.c, solsys3.c and solsys-ephem.c provide various legacy implementations that users may use (some require additional sources, or user-specific implementations).

If the standard implementations are compiled with the DEFAULT_SOLSYS option set (see config.mk), then the library is compiled with that version providing a built-in default implementation (the default is to use solsys3.c, which is a self-contained orbital calculation for the Sun and Earth only).

Additionally, users may set their custom choice of major planet ephemeris handler at runtime via the set_planet_provider() and/or set_planet_provider_hp() functions. They may also define custom handlers for all other types of Solar-system objects (i.e. NOVAS_EPHEM_OBJECT types) via set_ephem_provider().

Based on the NOVAS C Edition, Version 3.1:

U. S. Naval Observatory
Astronomical Applications Dept.
Washington, DC
http://www.usno.navy.mil/USNO/astronomical-applications

See also: solsys-calceph.c; solsys-cspice.c; solsys1.c; solsys2.c; solsys3.c; solsys-ephem.c

Macro Definition Documentation

◆ NOVAS_ID_TYPES

#define NOVAS_ID_TYPES (NOVAS_ID_CALCEPH + 1)

Number of different Solar-system body ID types enumerated

See also: enum novas_id_type

Author: Attila Kovacs

Since: 1.2

Typedef Documentation

◆ novas_ephem_provider

typedef int(* novas_ephem_provider) (const char *name, long id, double jd_tdb_high, double jd_tdb_low, enum novas_origin *origin, double *pos, double *vel)

Function to obtain ephemeris data for minor planets, which are not handled by the solarsystem() type calls. The library does not provide a default implementation, but users can provide their own, either as a default statically compiled readeph() implementation, or else a dynamically defined one via ephemeris_set_reader().

Note, that implementations would typically use either the name or the ID argument to identify the object for which ephemeris data is requested. As such you only need to specify the one that is going to be used.

Parameters

	name	The name of the solar-system body (in case the ephemeris provider supports lookup by name), or NULL to force ID based lookup.
	id	The ID number of the solar-system body for which the position in desired. (Typically a NAIF ID, or else an appropriate ID for the implementation – corresponding minor planet objects should be created with the same type of ID.). A value of -1 can be used to force name based lookups (provided the implementation supports it).
	jd_tdb_high	[day] The high-order part of Barycentric Dynamical Time (TDB) based Julian date for which to find the position and velocity. Typically this may be the integer part of the Julian date for high-precision calculations, or else the entire Julian date for reduced precision.
	jd_tdb_low	[day] The low-order part of Barycentric Dynamical Time (TDB) based Julian date for which to find the position and velocity. Typically this may be the fractional part of the Julian date for high-precision calculations, or else 0.0 if the date is defined entirely by the high-order component for reduced precision.
[out]	origin	Set to NOVAS_BARYCENTER or NOVAS_HELIOCENTER to indicate relative to which the ephemeris positions/velocities are reported.
[out]	pos	[AU] position 3-vector to populate with rectangular equatorial coordinates in AU. It may be NULL if position is not required.
[out]	vel	[AU/day] velocity 3-vector to populate in rectangular equatorial coordinates in AU/day. It may be NULL if velocities are not required.

Returns: 0 if successful, -1 if any of the pointer arguments are NULL, or some non-zero value if the was an error s.t. the position and velocity vector should not be used.

See also: set_ephem_provider(); ephemeris(); NOVAS_EPHEM_OBJECT; solsys-ephem.c

Since: 1.0

Author: Attila Kovacs

◆ novas_planet_provider

typedef short(* novas_planet_provider) (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *position, double *velocity)

Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters). This version provides positions and velocities at regular precision (see NOVAS_REDUCED_PRECISION).

Since this is a function that may be provided by existing custom user implementations, we keep the original argument types for compatibility, hence 'short' instead of the more informative enums).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date
	body	Major planet number (or that for the Sun, Moon, or an appropriate barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS (4), NOVAS_SUN (10) or NOVAS_SSB (0).
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the ephemeris data cannot be produced for other reasons.

See also: set_planet_provider(); ephemeris(); novas_solarsystem_hp_func

Since: 1.0

Author: Attila Kovacs

◆ novas_planet_provider_hp

typedef short(* novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double *position, double *velocity)

Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters). This version provides positions and velocities at high precision (see NOVAS_FULL_PRECISION).

Since this is a function that may be provided by existing custom user implementations, we keep the original argument types for compatibility, hence 'short' instead of the more informative enums).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date, broken into high and low order components, respectively. Typically, as the integer and fractional parts for the highest precision.
	body	Major planet number (or that for the Sun, Moon, or an appropriate barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS (4), NOVAS_SUN (10) or NOVAS_SSB (0).
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the ephemeris data cannot be produced for other reasons.

See also: set_planet_provider_hp(); novas_solarsystem_func; ephemeris()

Since: 1.0

Author: Attila Kovacs

Enumeration Type Documentation

◆ novas_id_type

enum novas_id_type

Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types. JPL ephemerides use NAIF IDs to identify objects in the Solar-system, which is thus the most widely adopted convention for numbering Solar-system bodies. But other numbering systems also exists, for example the CALCEPH library uses its own convention for the numbering of asteroids.

See also: object; NOVAS_EPHEM_OBJECT; NOVAS_ID_TYPES

Author: Attila Kovacs

Since: 1.2

Enumerator
NOVAS_ID_NAIF	If the ephemeris provider should use NAIF IDs.
NOVAS_ID_CALCEPH	If the ephemeris provider should use CALCEPH IDs.

Function Documentation

◆ earth_sun_calc()

short earth_sun_calc	(	double	jd_tdb,
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Provides the position and velocity of the Earth and Sun only at epoch 'jd_tdb' by evaluating a closed-form theory without reference to an external file. This function can also provide the position and velocity of the Sun.

REFERENCES:

Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.
Explanatory Supplement to The Astronomical Almanac (1992).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date
	body	NOVAS_EARTH (3) or NOVAS_SUN (10) only.
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS) or if one of the output pointer arguments is NULL (errno set to EINVAL). 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid.

See also: earth_sun_calc_hp(); set_planet_provider(); solarsystem(); novas_planet_provider

References NOVAS_BARYCENTER, NOVAS_EARTH, NOVAS_PLANETS, NOVAS_SSB, NOVAS_SUN, precession(), radec2vector(), sun_eph(), T0, and TWOPI.

◆ earth_sun_calc_hp()

short earth_sun_calc_hp	(	const double	jd_tdb[2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

It may provide the position and velocity of the Earth and Sun, the same as solarsystem_earth_sun(), if enable_earth_sun_hp() is set to true (non-zero). Otherwise, it will return with an error code of 3, indicating that high-precision calculations are not provided by this implementation.

NOTES:

This implementation will always propulate the output position and velocity vectors with the low-precision result, regardless of the return error code, in order to reduce the chance of unpredictable behavior, even if the user does not check the returned error status (which of course they should).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date
	body	NOVAS_EARTH (3) or NOVAS_SUN (10) only.
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), or if one of the output pointer arguments is NULL (errno set to EINVAL). 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the high-precision orbital data cannot be produced (default return value).

See also: enable_earth_sun_hp(); earth_sun_calc(); set_planet_provider(); solarsystem_hp(); novas_planet_provider_hp

References earth_sun_calc().

◆ enable_earth_sun_hp()

void enable_earth_sun_hp ( int value )

Specify whether the high-precision call is allowed to return a low-precision result. If set to 0 (false) solarsystem_earth_sun_hp() will return with an error code 3 indicating that a high-precision calculation is not possible. Otherise, a non-zero value (true) will let the function to be used without errors, returning the low-precison result of solarsystem_earth_sun() instead.

Parameters

value (boolean) A non-zero value enables the error-free use of the earth_sun_calc_hp() by allowing to return the low-precision result. Otherwise, earth_sun_calc_hp() will return an error code 3 indicating that the high-precision result is not available (this latter is the default behavior).

See also: earth_sun_calc_hp()

◆ get_ephem_provider()

novas_ephem_provider get_ephem_provider ( )

Returns the user-defined ephemeris accessor function.

Returns: the currently defined function for accessing ephemeris data for minor planets or satellites, ot NULL if no function was set via set_ephem_provider() previously.

See also: set_ephem_provider(); get_planet_provider(); get_planet_provider_hp(); ephemeris()

Since: 1.0

Author: Attila Kovacs

◆ get_planet_provider()

novas_planet_provider get_planet_provider ( )

Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.

Returns: the custom (low-precision) planet ephemeris provider function.

Author: Attila Kovacs

Since: 1.2

See also: set_planet_provider(); get_planet_provider_hp(); get_ephem_provider()

◆ get_planet_provider_hp()

novas_planet_provider_hp get_planet_provider_hp ( )

Returns the custom high-precision ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.

Returns: the custom high-precision planet ephemeris provider function.

Author: Attila Kovacs

Since: 1.2

See also: set_planet_provider_hp(); get_planet_provider(); get_ephem_provider()

◆ naif_to_novas_planet()

enum novas_planet naif_to_novas_planet ( long id )

Converts a NAIF ID to a NOVAS major planet ID. It account for the different IDs used for Sun, Moon, SSB, EMB and the Pluto system. Otherwise NAIF planet barycenters are mapped to the corresponding bodies. NAIF body centers n99 (e.g. 399 for Earth) are mapped to the corresponding NOVAS planet number n. All other NAIF IDs will return -1, indicating no match to a NOVAS planet ID.

Parameters

id	The NAIF ID of the major planet of interest

Returns: the NOVAS ID for the same object (which may or may not be different from the input), or -1 if the NAIF ID cannot be matched to a NOVAS major planet.

See also: novas_to_naif_planet(); novas_to_dexxx_planet()

Author: Attila Kovacs

Since: 1.2

References NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

◆ novas_to_dexxx_planet()

long novas_to_dexxx_planet ( enum novas_planet id )

Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID for DExxx ephemeris files. The DExxx (e.g. DE440) ephemeris files use NAIF IDs, but for most planets contain barycentric data only rather than that of the planet center. For Earth-based observations, it only really makes a difference whether the 3 is used for the Earth-Moon Barycenter (EMB) or 399 for the geocenter.

Parameters

id	The NOVAS ID of the major planet of interest

Returns: the NAIF ID for the same object (which may or may not be different from the input), as appropriate for use in the DExxx ephemeris files.

See also: novas_to_naif_planet(); naif_to_novas_planet()

Author: Attila Kovacs

Since: 1.2

References NOVAS_EARTH, NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

◆ novas_to_naif_planet()

long novas_to_naif_planet ( enum novas_planet id )

Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID. NOVAS and NAIF use slightly different IDs for major planets, the Moon, SSB, EMB, and the Pluto system. In NOVAS, major planets are have IDs ranging from 1 through 9, but for NAIF 1–9 are the planetary barycenters and the planet centers have numbers in the hundreds ending with 99 (e.g. the center of Earth is NAIF 399; 3 is the NOVAS ID for Earth and the NAIF ID for the Earth-Moon Barycenter [EMB]). The Sun and Moon also have distinct IDs in NAIF vs NOVAS.

Parameters

id	The NOVAS ID of the major planet of interest

Returns: the NAIF ID for the same object or planet center (which may or may not be different from the input)

See also: naif_to_novas_planet()

Author: Attila Kovacs

Since: 1.2

References NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

◆ planet_eph_manager()

short planet_eph_manager	(	double	jd_tdb,
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Provides an interface between the JPL direct-access solar system ephemerides and NOVAS-C for regular (reduced) precision applications.

This function and planet_eph_manager_hp() were designed to work with the 1997 version of the JPL ephemerides, as noted in the references.

The user must create the binary ephemeris files using software from JPL, and open the file using function ephem_open(), prior to calling this function.

REFERENCES:

JPL. 2007, "JPL Planetary and Lunar Ephemerides: Export Information," (Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.

Parameters

	jd_tdb	[day] Two-element array containing the Julian date, which may be split any way (although the first element is usually the "integer" part, and the second element is the "fractional" part). Julian date is on the TDB or "T_eph" time scale.
	body	Major planet number (or that for Sun, Moon, SSB...)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1), or 2 for Earth geocenter – relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else an error code of solarsystem().

See also: planet_eph_manager_hp(); planet_ephem_provider(); ephem_open(); set_planet_provider(); solarsystem()

Since: 1.0

References planet_eph_manager_hp().

◆ planet_eph_manager_hp()

short planet_eph_manager_hp	(	const double	jd_tdb[2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Provides an interface between the JPL direct-access solar system ephemerides and NOVAS-C for highest precision applications.

This function and planet_eph_manager() were designed to work with the 1997 version of the JPL ephemerides, as noted in the references.

The user must create the binary ephemeris files using software from JPL, and open the file using function ephem_open(), prior to calling this function.

REFERENCES:

JPL. 2007, "JPL Planetary and Lunar Ephemerides: Export Information," (Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.

Parameters

	jd_tdb	[day] Two-element array containing the Julian date, which may be split any way (although the first element is usually the "integer" part, and the second element is the "fractional" part). Julian date is on the TDB or "T_eph" time scale.
	body	Major planet number (or that for Sun, Moon, SSB...)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1), or 2 for Earth geocenter – relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else 1 if the 'body' is invalid, or 2 if the 'origin' is invalid, or 3 if there was an error providing ephemeris data.

See also: planet_eph_manager; planet_ephem_provider_hp(); ephem_open(); set_planet_provider_hp()

Since: 1.0

References NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_MOON, NOVAS_PLANETS, NOVAS_SUN, and planet_ephemeris().

◆ planet_ephem_provider()

short planet_ephem_provider	(	double	jd_tdb,
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine. This is the regular (reduced) precision version.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date.
	body	Major planet number (or that for Sun, Moon, SSB...)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else an error code of solarsystem().

See also: planet_ephem_provider_hp(); set_ephem_provider(); solarsystem()

Since: 1.0

Author: Attila Kovacs

References planet_ephem_provider_hp().

◆ planet_ephem_provider_hp()

short planet_ephem_provider_hp	(	const double	jd_tdb[2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine. This is the highest precision version.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date, split into high and low order components (e.g. integer and fractional parts) for high-precision calculations.
	body	Major planet number (or that for Sun, Moon, SSB...)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else an error code of solarsystem_hp().

See also: planet_ephem_provider(); set_ephem_provider(); solarsystem_hp()

Since: 1.0

Author: Attila Kovacs

References get_ephem_provider(), NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, NOVAS_SSB, and NOVAS_SUN.

◆ planet_jplint()

short planet_jplint	(	double	jd_tdb,
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Obtains planet positions via the JPL direct-access solar system ephemerides, wtih normal (reduced) precision – typically good to the milliarcsecond level.

It generalizes access to the JPL software by calling a Fortran interface subroutine, 'jplint', instead of making a direct call to the JPL subroutine 'pleph', whose arguments have changed several times throughout the years. This way, any future change to the arguments can be accommodated in 'jplint' rather than in this function.

For supporting JPL ephemerides more generally, including for satellites, asteroids, and comets, you are probably better off using planet_ephem_provider(), and provide an interface, e.g. to the CSPICE library, via novas_ephem_provider instead, which you can then activate dynamically with set_planet_provider().

REFERENCES:

JPL. 2007, JPL Planetary and Lunar Ephemerides: Export Information, (Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.

Parameters

	jd_tdb	[day] Two-element array containing the Julian date, which may be split any way (although the first element is usually the "integer" part, and the second element is the "fractional" part). Julian date is on the TDB or "T_eph" time scale.
	body	Major planet number (or that for Sun, Moon, SSB..)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1), or 2 for Earth geocenter – relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else 1 if the 'body' or 'origin' argument is invalid, or else 2 if the 'jplint_()' call failed.

See also: planet_jplint_hp(); planet_ephem_provider(); set_planet_provider(); solarsystem()

Since: 1.0

References jplint_(), NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_MERCURY, NOVAS_MOON, and NOVAS_SUN.

◆ planet_jplint_hp()

short planet_jplint_hp	(	const double	jd_tdb[2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *	position,
		double *	velocity
	)

Obtains planet positions via the JPL direct-access solar system ephemerides, wtih high precision – typically good to below the microarcsecond level.

It generalizes access to the JPL software by calling a Fortran interface subroutine, 'jplint', instead of making a direct call to the JPL subroutine 'pleph', whose arguments have changed several times throughout the years. This way, any future change to the arguments can be accommodated in 'jplint' rather than in this function.

For supporting JPL ephemerides more generally, including for satellites, asteroids, and comets, you are probably better off using planet_ephem_provider(), and provide an interface, e.g. to the CSPICE library, via novas_ephem_provider instead, which you can then activate dynamically with set_planet_provider().

REFERENCES:

JPL. 2007, JPL Planetary and Lunar Ephemerides: Export Information, (Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.

Parameters

	jd_tdb	[day] Two-element array containing the Julian date, which may be split any way (although the first element is usually the "integer" part, and the second element is the "fractional" part). Julian date is on the TDB or "T_eph" time scale.
	body	Major planet number (or that for Sun, Moon, SSB...)
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1), or 2 for Earth geocenter – relative to which to report positions and velocities.
[out]	position	[AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
[out]	velocity	[AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns: 0 if successful, or else an error code of solarsystem().

See also: planet_jplint(); planet_ephem_provider_hp(); set_planet_provider_hp(); solarsystem_hp()

Since: 1.0

References jplihp_(), NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_MERCURY, NOVAS_MOON, and NOVAS_SUN.

◆ readeph()

double * readeph	(	int	mp,
		const char *	name,
		double	jd_tdb,
		int *	error
	)

Provides a default ephemeris implementation to handle position and velocity calculations for minor planets, which are not handled by the solarsystem() type calls. The library does not provide a default implementation, but users can provide their own, either as a default statically compiled readeph() implementation, or else a dynamically defined one via ephemeris_set_reader().

You can set the built-in implementation for the library by setting the DEFAULT_READEPH variable in the Makefile.

Deprecated:: This old ephemeris reader is prone to memory leaks, and lacks some useful functionality. Users are strongly encouraged to use the new novas_ephem_provider instead, which can provide dynamically configured implementations at runtime.

Parameters

	mp	The ID number of the solar-system body for which the position are desired.
	name	The name of the solar-system body (usually upper-case)
	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date for which to find the position and velocity.
[out]	error	Pointer to integer to populate with the error status: 0 if successful, -1 if any of the pointer arguments are NULL, or some non-zero value if the was an error s.t. the position and velocity vector should not be used.

Returns: [AU, AU/day] A newly allocated 6-vector in rectangular equatorial coordinates, containing the heliocentric position coordinates in AU, followed by hte heliocentric velocity components in AU/day. The caller is responsible for calling free() on the returned value when it is no longer needed.

See also: novas_ephem_provider; ephemeris(); NOVAS_EPHEM_OBJECT

Since: 1.0

Author: Attila Kovacs

◆ set_ephem_provider()

int set_ephem_provider ( novas_ephem_provider func )

Sets the function to use for obtaining position / velocity information for minor planets, or sattelites.

Parameters

func	new function to use for accessing ephemeris data for minor planets or satellites.

Returns: 0 if successful, or else -1 if the function argument is NULL.

Since: 1.0

Author: Attila Kovacs

See also: get_ephem_provider(); set_planet_provider(); set_planet_provider_hp(); ephemeris(); solsys-ephem.c

◆ set_planet_provider()

int set_planet_provider ( novas_planet_provider func )

Set a custom function to use for regular precision (see NOVAS_REDUCED_ACCURACY) ephemeris calculations instead of the default solarsystem() routine.

Parameters

func	The function to use for solar system position/velocity calculations. See solarsystem() for further details on what is required of this function.

Author: Attila Kovacs

Since: 1.0

See also: get_planet_provider(); set_planet_provider_hp(); solarsystem(); NOVAS_REDUCED_ACCURACY

◆ set_planet_provider_hp()

int set_planet_provider_hp ( novas_planet_provider_hp func )

Set a custom function to use for high precision (see NOVAS_FULL_ACCURACY) ephemeris calculations instead of the default solarsystem_hp() routine.

Parameters

func	The function to use for solar system position/velocity calculations. See solarsystem_hp() for further details on what is required of this function.

Author: Attila Kovacs

Since: 1.0

See also: get_planet_provider_hp(); set_planet_provider(); solarsystem_hp(); NOVAS_FULL_ACCURACY

◆ solarsystem()

short solarsystem	(	double	jd_tdb,
		short	body,
		short	origin,
		double *	position,
		double *	velocity
	)

A default implementation for regular (reduced) precision handling of major planets, Sun, Moon and the Solar-system barycenter. See DEFAULT_SOLSYS in Makefile to choose the implementation that is built into with the library as a default. Applications can define their own preferred implementations at runtime via set_planet_provider().

Since this is a function that may be provided by existing custom user implementations, we keep the original argument types for compatibility, hence 'short' instead of the more informative enums).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date
	body	Major planet number (or that for the Sun, Moon, or an appropriate barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS (4), NOVAS_SUN (10) or NOVAS_SSB (0). (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the ephemeris data cannot be produced for other reasons.

See also: novas_planet; solarsystem_hp(); set_planet_provider(); place(); ephemeris()

References earth_sun_calc(), planet_eph_manager(), planet_ephem_provider(), and planet_jplint().

◆ solarsystem_hp()

short solarsystem_hp	(	const double	jd_tdb[2],
		short	body,
		short	origin,
		double *	position,
		double *	velocity
	)

A default implementation for high precision handling of major planets, Sun, Moon and the Solar-system barycenter (and other barycenters). See DEFAULT_SOLSYS in Makefile to choose the implementation that is built into the library as a default. Applications can define their own preferred implementations at runtime via set_planet_provider_hp().

Since this is a function that may be provided by existing custom user implementations, we keep the original argument types for compatibility, hence 'short' instead of the more informative enums).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date, broken into high and low order components, respectively. Typically, as the integer and fractional parts for the highest precision.
	body	Major planet number (or that for the Sun, Moon, or an appropriate barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS (4), NOVAS_SUN (10) or NOVAS_SSB (0). (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
[out]	position	[AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
[out]	velocity	[AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns: 0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), or some other error code (NOVAS C was not very consistent here...)

See also: solarsystem(); set_planet_provider_hp(); place(); ephemeris()

References earth_sun_calc_hp(), planet_eph_manager_hp(), planet_ephem_provider_hp(), and planet_jplint_hp().

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NOVAS_ID_TYPES

Typedef Documentation

◆ novas_ephem_provider

◆ novas_planet_provider

◆ novas_planet_provider_hp

Enumeration Type Documentation

◆ novas_id_type

Function Documentation

◆ earth_sun_calc()

◆ earth_sun_calc_hp()

◆ enable_earth_sun_hp()

◆ get_ephem_provider()

◆ get_planet_provider()

◆ get_planet_provider_hp()

◆ naif_to_novas_planet()

◆ novas_to_dexxx_planet()

◆ novas_to_naif_planet()

◆ planet_eph_manager()

◆ planet_eph_manager_hp()

◆ planet_ephem_provider()

◆ planet_ephem_provider_hp()

◆ planet_jplint()

◆ planet_jplint_hp()

◆ readeph()

◆ set_ephem_provider()

◆ set_planet_provider()

◆ set_planet_provider_hp()

◆ solarsystem()

◆ solarsystem_hp()