ephemeris.c File Reference

Functions that allow to define or access Solar-system ephemeris data. More...

Functions
short	ephemeris (const double *restrict jd_tdb, const object *restrict body, enum novas_origin origin, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
	Retrieves the position and velocity of a solar system body using the currently configured plugins that provide them.
novas_ephem_provider	get_ephem_provider ()
	Returns the user-defined ephemeris accessor function.
novas_nutation_provider	get_nutation_lp_provider ()
	Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().
novas_planet_provider	get_planet_provider ()
	Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.
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.
int	set_ephem_provider (novas_ephem_provider func)
	Sets the function to use for obtaining position / velocity information for minor planets, or satellites.
int	set_nutation_lp_provider (novas_nutation_provider func)
	Set the function to use for low-precision IAU 2000 nutation calculations instead of the default nu2000k().
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.
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.

Detailed Description

Functions that allow to define or access Solar-system ephemeris data.

SuperNOVAS cannot, by itself, provide accurate positions for Solar-system sources. While it has a built-in calculator (see solsys3.c) for the Earth and the Sun, it is suitable for obtaining approximate positions for the Sun and Earth only, and is limited to around 10 arcsec accuracy, typically.

To do astrometry right for Solar-system sources (major planets, and minor bodies like asteroids, comets, or moons), you will have to interface SuperNOVAS with ephemeris data, through a library or service. For example, NASA JPL provides short and long-term ephemeris data for all known Solar-system sources.

Besides providing accurate astrometric positions for Solar-system sources, planetary ephemeris data are also necessary for high-precision position calculations for sidereal (non-Solar-system) sources if one is to account for gravitational deflections around the major planets as light traverses the Solar-system on its way to the observer.

You may download various ephemeris data files (SPICE kernels) made available by NASA from the JPL NAIF site or from the JPL Horizons system, and them access them via appropriate C libraries, such as JPL's own NAIF CSPICE Toolkit, or the more modern CALCEPH library by IMCCE. SuperNOVAS provides interfaces to both (see solsys-cspice.c and solsys-calceph.c), making it very easy to incorporate ephemeris data into SuperNOVAS that way.

Alternatively, you might use some other library or your own code to access ephemeris data, e.g. by interfacing directly to the JPL Horizons system, or to the IAU Minor Planet Center (MPC). You can always write your own novas_ephem_provider function and activate it for SuperNOVAS with set_ephem_provider(), and also configure it to use for planets with:

set_planet_provider(planet_ephem_provider);
set_planet_provider_hp(planet_ephem_provider_hp);

(Alternatively, you might define separate low and high-precision ephemeris provider functions for the major planets ,by writing your own novas_ephem_provider and novas_ephem_provider_hp interface functions, respectively, and activating these with set_ephem_provider() and set_ephem_provider_hp().)

Date

Created on Mar 6, 2025

Author

Attila Kovacs and G. Kaplan

See also

solsys-calceph.c, solsys-cspice.c, solsys3.c, orbital.c

Function Documentation

ephemeris()

short ephemeris	(	const double *restrict	jd_tdb,
		const object *restrict	body,
		enum novas_origin	origin,
		enum novas_accuracy	accuracy,
		double *restrict	pos,
		double *restrict	vel )

Retrieves the position and velocity of a solar system body using the currently configured plugins that provide them.

It is recommended that the input structure 'cel_obj' be created using make_object()

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	body	Pointer to structure containing the designation of the body of interest
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1)
	accuracy	NOCAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	[AU] Pointer to structure containing the designation of the body of interest
[out]	vel	[AU/day] Velocity vector of the body at 'jd_tdb'; equatorial rectangular coordinates in AU/day referred to the ICRS.

Returns

0 if successful, -1 if the 'jd_tdb' or input object argument is NULL, or else 1 if 'origin' is invalid, 2 if cel_obj->type is invalid, 10 + the error code from the currently configured novas_planet_provider_hp call, or 20 + the error code from readeph().

See also

set_planet_provider(), set_planet_provider_hp(), set_ephem_provider()

make_planet(), make_ephem_object()

References ephemeris(), get_ephem_provider(), make_planet(), NOVAS_BARYCENTER, NOVAS_EPHEM_OBJECT, NOVAS_FULL_ACCURACY, NOVAS_HELIOCENTER, novas_orbit_posvel(), NOVAS_ORBITAL_OBJECT, NOVAS_ORIGIN_TYPES, NOVAS_PLANET, NOVAS_SSB, NOVAS_SUN, and readeph().

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.

Since

1.0

Author

Attila Kovacs

See also

set_ephem_provider(), get_planet_provider(), get_planet_provider_hp(), ephemeris()

get_nutation_lp_provider()

novas_nutation_provider get_nutation_lp_provider

(

)

Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Returns

the function to use for low-precision IAU 2000 nutation calculations

Since

1.3

Author

Attila Kovacs

See also

set_nutation_lp_provider(), nutation_angles(), nutation()

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()

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 satellites.

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()

novas_use_calceph(), novas_use_cspice()

set_nutation_lp_provider()

int set_nutation_lp_provider

(

novas_nutation_provider

func

)

Set the function to use for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Parameters

func	the new function to use for low-precision IAU 2000 nutation calculations

Returns

0 if successful, or -1 if the input argument is NULL

Since

1.0

Author

Attila Kovacs

See also

get_nutation_lp_provider(), nutation_angles(), nutation()

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(), NOVAS_REDUCED_ACCURACY

novas_use_calceph(), novas_use_cspice()

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

novas_use_calceph(), novas_use_cspice()