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 restrict origin, double restrict pos, double restrict vel)

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

typedef short(*	novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double restrict position, double restrict 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 restrict position, double restrict velocity)

short	earth_sun_calc_hp (const double jd_tdb[restrict 2], enum novas_planet body, enum novas_origin origin, double restrict position, double restrict 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 ()

int	make_orbital_object (const char name, long num, const novas_orbital orbit, object *body)

enum novas_planet	naif_to_novas_planet (long id)

int	novas_approx_heliocentric (enum novas_planet id, double jd_tdb, double restrict pos, double restrict vel)

int	novas_approx_sky_pos (enum novas_planet id, const novas_frame restrict frame, enum novas_reference_system sys, sky_pos restrict out)

double	novas_helio_dist (double jd_tdb, const object restrict source, double restrict rate)

int	novas_make_moon_orbit (double jd_tdb, novas_orbital *restrict orbit)

int	novas_make_planet_orbit (enum novas_planet id, double jd_tdb, novas_orbital *restrict orbit)

double	novas_moon_angle (const object restrict source, const novas_frame restrict frame)

double	novas_moon_phase (double jd_tdb)

double	novas_next_moon_phase (double phase, double jd_tdb)

int	novas_orbit_native_posvel (double jd_tdb, const novas_orbital restrict orbit, double restrict pos, double *restrict vel)

int	novas_orbit_posvel (double jd_tdb, const novas_orbital restrict orbit, enum novas_accuracy accuracy, double restrict pos, double *restrict vel)

enum novas_planet	novas_planet_for_name (const char *restrict name)

int	novas_set_orbsys_pole (enum novas_reference_system type, double ra, double dec, novas_orbital_system *restrict sys)

double	novas_solar_illum (const object restrict source, const novas_frame restrict frame)

double	novas_solar_power (double jd_tdb, const object *restrict source)

double	novas_sun_angle (const object restrict source, const novas_frame restrict frame)

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 restrict position, double restrict velocity)

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

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

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

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

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

double *	readeph (int mp, const char restrict name, double jd_tdb, int restrict 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 restrict position, double restrict velocity)

short	solarsystem_hp (const double jd_tdb[restrict 2], short body, short origin, double restrict position, double restrict 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 *restrict origin, double *restrict pos, double *restrict 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 *restrict position, double *restrict 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 *restrict position, double *restrict 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 *restrict	position,
		double *restrict	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(), and TWOPI.

◆ earth_sun_calc_hp()

short earth_sun_calc_hp	(	const double	jd_tdb[restrict 2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *restrict	position,
		double *restrict	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()

◆ make_orbital_object()

int make_orbital_object	(	const char *	name,
		long	num,
		const novas_orbital *	orbit,
		object *	body
	)

Sets a celestial object to be a Solar-system orbital body. Typically this would be used to define minor planets, asteroids, comets, or even planetary satellites.

Parameters

	name	Name of object. It may be NULL if not relevant.
	num	Solar-system body ID number (e.g. NAIF). It is not required and can be set e.g. to -1 if not relevant to the caller.
	orbit	The orbital parameters to adopt. The data will be copied, not referenced.
[out]	body	Pointer to structure to populate.

Returns: 0 if successful, or else -1 if the 'orbit' or 'body' pointer is NULL or the name is too long.

See also: novas_orbit_posvel(); make_planet(); make_ephem_object(); novas_geom_posvel(); place()

Since: 1.2

Author: Attila Kovacs

References make_object(), NOVAS_ORBITAL_OBJECT, and object::orbit.

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

int novas_approx_heliocentric	(	enum novas_planet	id,
		double	jd_tdb,
		double *restrict	pos,
		double *restrict	vel
	)

Returns the approximate geometric heliocentric orbital positions and velocities for the major planets, Sun, or Earth-Moon Barycenter (EMB). The returned positions and velocities are not suitable for precise calculations. However, they may be used to provide rough guidance about the approximate locations of the planets, e.g. for determining approximate rise or set times or the approximate azimuth / elevation angles from an observing site.

The orbitals can provide planet positions to arcmin-level precision for the rocky inner planets, and to a fraction of a degree precision for the gas and ice giants and Pluto. The accuracies for Uranus, Neptune, and Pluto are significantly improved (to the arcmin level) if used in the time range of 1800 AD to 2050 AD. For a more detailed summary of the typical accuracies, see either of the top two references below.

For accurate positions, you should use planetary ephemerides (such as the JPL ephemerides via the CALCEPH or CSPICE plugins) and novas_geom_posvel() instead.

While this function is generally similar to creating an orbital object with an orbit initialized with novas_make_planet_orbit() or novas_make_moon_orbit(), and then calling novas_geom_posvel(), there are a few important differences:

This function returns geometric positions referenced to the Sun (i.e., heliocentric), whereas novas_geom_posvel() references the calculated positions to the Solar-system Barycenter (SSB).
This function calculates Earth and Moon positions about the Keplerian orbital position of the Earth-Moon Barycenter (EMB). In constrast, novas_make_planet_orbit() does not provide orbitals for the Earth directly, and make_moot_orbit() references the Moon's orbital to the Earth position returned by the currently configured planet calculator function (see set_planet_provider()).

NOTES:

The Sun's position w.r.t. the Solar-system Barycenter is calculated using earth_sun_calc(). All other orbitals are also referenced to the Sun's position calculated that way.

REFERENCES:

E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

	id	NOVAS major planet ID. All major planets, plus the Sun, Moon, Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported. (For Pluto, the Pluto System Barycenter value are returned.)
	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian Date. Dates between 3000 BC and 3000 AD are supported. For dates between 1800 AD and 2050 AD the returned positions are somewhat more accurate.
[out]	pos	[AU] Output Heliocentric ICRS position vector, or NULL if not required.
[out]	vel	[AU/day] Output Heliocentric ICRS velocity vector, or NULL if not required.

Returns: 0 if successful, or if the JD date is outside of the range with valid parameters, or else -1 if the planet ID is not supported or if both output vectors are NULL. In case of errors errno will be set to indicate the type of error.

Since: 1.4

Author: Attila Kovacs

See also: novas_approx_sky_pos(); earth_sun_calc(); novas_geom_posvel(); novas_use_calceph(); novas_use_cspice()

References NOVAS_EARTH, NOVAS_EMB, novas_make_moon_orbit(), novas_make_planet_orbit(), NOVAS_MOON, NOVAS_ORBIT_INIT, novas_orbit_posvel(), NOVAS_REDUCED_ACCURACY, and NOVAS_SUN.

◆ novas_approx_sky_pos()

int novas_approx_sky_pos	(	enum novas_planet	id,
		const novas_frame *restrict	frame,
		enum novas_reference_system	sys,
		sky_pos *restrict	out
	)

Calculates an approximate apparent location on sky for a major planet, Sun, Moon, Earth-Moon Barycenter (EMB) – typically to arcmin level accuracy – using Keplerian orbital elements. The returned position is antedated for light-travel time (for Solar-System bodies). It also applies an appropriate aberration correction (but not gravitational deflection).

The orbitals can provide planet positions to arcmin-level precision for the rocky inner planets, and to a fraction of a degree precision for the gas and ice giants and Pluto. The accuracies for Uranus, Neptune, and Pluto are significantly improved (to the arcmin level) if used in the time range of 1800 AD to 2050 AD. For a more detailed summary of the typical accuracies, see either of the top two references below.

For accurate positions, you should use planetary ephemerides (such as the JPL ephemerides via the CALCEPH or CSPICE plugins) and novas_sky_pos() instead.

While this function is generally similar to creating an orbital object with an orbit initialized with novas_make_planet_orbit() or novas_make_moon_orbit(), and then calling novas_sky_pos(), there are a few important differences to note:

This function calculates Earth and Moon positions about the Keplerian orbital position of the Earth-Moon Barycenter (EMB). In constrast, novas_make_planet_orbit() does not provide orbitals for the Earth directly, and make_moot_orbit() references the Moon's orbital to the Earth position returned by the currently configured planet calculator function (see set_planet_provider()).
This function ignores gravitational deflection. It makes little sense to bother about corrections that are orders of magnitude below the accuracy of the orbital positions obtained.

REFERENCES:

E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

	id	NOVAS major planet ID. All major planets, plus the Sun, Moon, Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported. (For Pluto, the Pluto System Barycenter values are returned.)
	frame	The observer frame, defining the location and time of observation.
	sys	The coordinate system in which to return the apparent sky location.
[out]	out	Pointer to the data structure which is populated with the calculated approximate apparent location in the designated coordinate system.

Returns: 0 if successful, or else -1 in case of an error (errno will indicate the type of error).

Since: 1.4

Author: Attila Kovacs

See also: novas_sky_pos(); novas_app_to_hor(); make_frame()

References make_planet(), novas_approx_heliocentric(), novas_geom_to_app(), novas_get_time(), NOVAS_TDB, novas_vlen(), and rad_vel2().

◆ novas_helio_dist()

double novas_helio_dist	(	double	jd_tdb,
		const object *restrict	source,
		double *restrict	rate
	)

Returns a Solar-system body's distance from the Sun, and optionally also the rate of recession. It may be useful, e.g. to calculate the body's heating from the Sun.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated from the source.
	source	Observed Solar-system source
[out]	rate	[AU/day] (optional) Returned rate of recession from Sun

Returns: [AU] Distance from the Sun, or NAN if not a Solar-system source.

Since: 1.3

Author: Attila Kovacs

See also: novas_solar_power(); novas_solar_illum()

References ephemeris(), NOVAS_CATALOG_OBJECT, NOVAS_HELIOCENTER, NOVAS_REDUCED_ACCURACY, and novas_vlen().

◆ novas_make_moon_orbit()

int novas_make_moon_orbit	(	double	jd_tdb,
		novas_orbital *restrict	orbit
	)

Gets the current orbital elements for the Moon relative to the geocenter for the specified epoch of observation.

REFERENCES:

Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian Date.
[out]	orbit	Orbital elements data structure to populate.

Returns: 0 if successful, or else -1 (errno set to EINVAL).

Since: 1.4

Author: Attila Kovacs

See also: novas_make_planet_orbit(); make_orbital_object()

References NOVAS_AU, NOVAS_EARTH, NOVAS_JD_J2000, NOVAS_ORBIT_INIT, and TWOPI.

◆ novas_make_planet_orbit()

int novas_make_planet_orbit	(	enum novas_planet	id,
		double	jd_tdb,
		novas_orbital *restrict	orbit
	)

Get approximate current heliocentric orbital elements for the major planets. These orbital elements are not suitable for precise position velocity calculations, but they may be useful to obtain approximate positions for the major planets, e.g. to estimate rise or set times, or apparent elevation angles from an observing site.

These orbitals can provide planet positions to arcmin-level precision for the rocky inner planets, and to a fraction of a degree precision for the gas and ice giants and Pluto. The accuracies for Uranus, Neptune, and Pluto are significantly improved (to the arcmin level) if used in the time range of 1800 AD to 2050 AD. For a more detailed summary of the typical accuracies, see either of the references below.

NOTES:

The Earth-Moon system is treated as a single orbital of the Earth-Moon Barycenter (EMB). That is, the EMB orbital is returned for both Earth and the Moon also.
For Pluto, the Pluto system barycenter orbit is returned.

REFERENCES:

E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html

Parameters

	id	NOVAS major planet ID. All major planets, except Earth, are supported. The Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported also. (For Pluto, the Pluto System Barycenter values are returned.)
	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian Date.
[out]	orbit	Orbital elements data structure to populate.

Returns: 0 if successful, or else -1 (errno set to EINVAL).

Since: 1.4

Author: Attila Kovacs

See also: novas_make_moon_orbit(); novas_approx_sky_pos(); novas_approx_heliocentric(); make_orbital_object()

Keplerian orbital elements at J2000 from Table 8.10.2 of E.M. Standish and J.G. Williams 1992, valid for 1800 AD to 2050 AD.

Temporal evolution of the Keplerian orbital elements from Table 8.10.2 of E.M. Standish and J.G. Williams 1992, valid for 1800 AD to 2050 AD.

Keplerian orbital elements at J2000 from Table 8.10.3 of E.M. Standish and J.G. Williams 1992, valid for 3000 BC to 3000 AD.

Temporal evolution of the Keplerian orbital elements from Table 8.10.3 of E.M. Standish and J.G. Williams 1992, vaid for 3000 BC to 3000 AD.

Additional terms for computing M for the outer planets (Jupiter and beyond) from Table 8.10.4 of E.M. Standish and J.G. Williams 1992.

References NOVAS_EARTH, NOVAS_EMB, NOVAS_JD_J2000, NOVAS_JUPITER, NOVAS_ORBIT_INIT, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, and TWOPI.

◆ novas_moon_angle()

double novas_moon_angle	(	const object *restrict	source,
		const novas_frame *restrict	frame
	)

Returns the apparent angular distance of a source from the Moon from the observer's point of view.

Parameters

source	An observed source
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: [deg] Apparent angular distance between the source an the Moon, from the observer's point of view

Since: 1.3

Author: Attila Kovacs

See also: novas_sun_angle()

References NOVAS_MOON_INIT, and novas_object_sep().

◆ novas_moon_phase()

double novas_moon_phase ( double jd_tdb )

Calculates the Moon's phase at a given time. It uses orbital models for Earth (E.M. Standish and J.G. Williams 1992), and for the Moon (Chapront, J. et al., 2002), and takes into account the slightly eccentric nature of both orbits.

NOTES:

The Moon's phase here follows the definition by the Astronomical Almanac, as the excess ecliptic longitude of the Moon over that of the Sun seen from the geocenter.
There are other definitions of the phase too, depending on which you might find slightly different answers, but regardless of the details most phase calculations should match to within a few degrees.

REFERENCES:

The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

jd_tdb [day] Barycentric Dynamical Time (TDB) based Julian Date.

Returns: [deg] The Moon's phase, or more precisely the ecliptic longitude difference between the Sun and the Moon, as seen from the geocenter. 0: New Moon, 90: 1st quarter, +/- 180 Full Moon, -90: 3rd quarter or NAN if the solution failed to converge (errno will be set to ECANCELED), or if the JD date is outside the range of the orbital model (errno set to EINVAL).

Since: 1.4

Author: Attila Kovacs

See also: novas_next_moon_phase(); novas_make_moon_orbit(); novas_solar_illum()

References NOVAS_EMB, novas_make_moon_orbit(), novas_make_planet_orbit(), NOVAS_ORBIT_INIT, novas_orbit_native_posvel(), and vector2radec().

◆ novas_next_moon_phase()

double novas_next_moon_phase	(	double	phase,
		double	jd_tdb
	)

Calculates the date / time at which the Moon will reach the specified phase next, after the specified time. It uses orbital models for Earth (E.M. Standish and J.G. Williams 1992), and for the Moon (Chapront, J. et al., 2002), and takes into account the slightly eccentric nature of both orbits.

NOTES:

The Moon's phase here follows the definition by the Astronomical Almanac, as the excess ecliptic longitude of the Moon over that of the Sun seen from the geocenter.
There are other definitions of the phase too, depending on which you might find slightly different answers, but regardless of the details most phase calculations should match give or take a few hours.

REFERENCES:

The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

phase	[deg] The Moon's phase, or more precisely the ecliptic longitude difference between the Sun and the Moon, as seen from the geocenter. 0: New Moon, 90: 1st quarter, +/- 180 Full Moon, -90: 3rd quarter.
jd_tdb	[day] The lower bound date for the phase, as a Barycentric Dynamical Time (TDB) based Julian Date.

Returns: [day] The Barycentric Dynamical Time (TDB) based Julian Date when the Moon will be in the desired phase next after the input date; or NAN if the solution failed to converge (errno will be set to ECANCELED).

Since: 1.4

Author: Attila Kovacs

See also: novas_moon_phase(); novas_make_moon_orbit()

References novas_inv_max_iter, NOVAS_JD_J2000, and novas_moon_phase().

◆ novas_orbit_native_posvel()

int novas_orbit_native_posvel	(	double	jd_tdb,
		const novas_orbital *restrict	orbit,
		double *restrict	pos,
		double *restrict	vel
	)

Calculates a rectangular equatorial position and velocity vector for the given orbital elements for the specified time of observation, in the native coordinate system in which the orbital is defined (e.g. ecliptic for heliocentric orbitals).

REFERENCES:

E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
https://en.wikipedia.org/wiki/Orbital_elements
https://orbitalofficial.com/
https://downloads.rene-schwarz.com/download/M001-Keplerian_Orbit_Elements_to_Cartesian_State_Vectors.pdf

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	orbit	Orbital parameters
[out]	pos	[AU] Output ICRS equatorial position vector around orbital center, or NULL if not required.
[out]	vel	[AU/day] Output ICRS velocity vector rel. to orbital center, in the native system of the orbital, or NULL if not required. 0 if successful, or else -1 if the orbital parameters are NULL, or if the position and velocity output vectors are the same or the orbital system is ill defined (errno set to EINVAL), or if the calculation did not converge (errno set to ECANCELED), or

See also: ephemeris(); novas_geom_posvel(); place(); make_orbital_object()

Author: Attila Kovacs

Since: 1.4

References TWOPI.

◆ novas_orbit_posvel()

int novas_orbit_posvel	(	double	jd_tdb,
		const novas_orbital *restrict	orbit,
		enum novas_accuracy	accuracy,
		double *restrict	pos,
		double *restrict	vel
	)

Calculates a rectangular equatorial position and velocity vector for the given orbital elements for the specified time of observation.

REFERENCES:

E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
https://en.wikipedia.org/wiki/Orbital_elements
https://orbitalofficial.com/
https://downloads.rene-schwarz.com/download/M001-Keplerian_Orbit_Elements_to_Cartesian_State_Vectors.pdf

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	orbit	Orbital parameters
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
[out]	pos	[AU] Output ICRS equatorial position vector around orbital center, or NULL if not required.
[out]	vel	[AU/day] Output ICRS equatorial velocity vector rel. to orbital center, or NULL if not required.

Returns: 0 if successful, or else -1 if the orbital parameters are NULL, or if the position and velocity output vectors are the same or the orbital system is ill defined (errno set to EINVAL), or if the calculation did not converge (errno set to ECANCELED), or

See also: ephemeris(); novas_geom_posvel(); place(); make_orbital_object()

Author: Attila Kovacs

Since: 1.2

References novas_orbit_native_posvel().

◆ novas_planet_for_name()

enum novas_planet novas_planet_for_name ( const char *restrict name )

Returns the NOVAS planet ID for a given name (case insensitive), or -1 if no match is found.

Parameters

name	The planet name, or that for the "Sun", "Moon" or "SSB" (case insensitive). The spelled out "Solar System Barycenter" is also recognized with either spaces, hyphens ('-') or underscores ('_') separating the case insensitive words.

Returns: The NOVAS major planet ID, or -1 (errno set to EINVAL) if the input name is NULL or if there is no match for the name provided.

Author: Attila Kovacs

Since: 1.2

See also: make_planet()

References NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, and NOVAS_SSB.

◆ novas_set_orbsys_pole()

int novas_set_orbsys_pole	(	enum novas_reference_system	type,
		double	ra,
		double	dec,
		novas_orbital_system *restrict	sys
	)

Sets the orientation of an orbital system using the RA and DEC coordinates of the pole of the Laplace (or else equatorial) plane relative to which the orbital elements are defined. Orbital parameters of planetary satellites normally include the R.A. and declination of the pole of the local Laplace plane in which the Keplerian orbital elements are referenced.

The system will become referenced to the equatorial plane, the relative obliquity is set to (90° - dec), while the argument of the ascending node ('Omega') is set to (90° + ra).

NOTES:

You should not expect much precision from the long-range orbital approximations for planetary satellites. For applications that require precision at any level, you should rely on appropriate ephemerides, or else on up-to-date short-term orbital elements.

Parameters

	type	Coordinate reference system in which `ra` and `dec` are defined (e.g. NOVAS_GCRS).
	ra	[h] the R.A. of the pole of the oribtal reference plane.
	dec	[deg] the declination of the pole of the oribtal reference plane.
[out]	sys	Orbital system

Returns: 0 if successful, or else -1 (errno will be set to EINVAL) if the output sys pointer is NULL.

Author: Attila Kovacs

Since: 1.2

See also: make_orbital_object()

References NOVAS_EQUATORIAL_PLANE, and NOVAS_TIRS.

◆ novas_solar_illum()

double novas_solar_illum	(	const object *restrict	source,
		const novas_frame *restrict	frame
	)

Returns the Solar illumination fraction of a source, assuming a spherical geometry for the observed body.

Parameters

source	Observed source. Usually a Solar-system source. (For other source types, 1.0 is returned by default.)
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: Solar illumination fraction [0.0:1.0] of a spherical body observed at the source location from the given observer location, or NAN if there was an error (errno will indicate the type of error).

Since: 1.3

Author: Attila Kovacs

References NOVAS_CATALOG_OBJECT, novas_geom_posvel(), NOVAS_ICRS, and novas_vlen().

◆ novas_solar_power()

double novas_solar_power	(	double	jd_tdb,
		const object *restrict	source
	)

Returns the typical incident Solar power on a Solar-system body at the time of observation.

Parameters

jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated ( was reflected) from the source.
source	Observed Solar-system source

Returns: [W/m²] Incident Solar power on the illuminated side of the object, or NAN if not a Solar-system source or if the source is the Sun itself.

Since: 1.3

Author: Attila Kovacs

See also: novas_solar_illum()

References novas_helio_dist(), and NOVAS_SOLAR_CONSTANT.

◆ novas_sun_angle()

double novas_sun_angle	(	const object *restrict	source,
		const novas_frame *restrict	frame
	)

Returns the apparent angular distance of a source from the Sun from the observer's point of view.

Parameters

source	An observed source
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: [deg] the apparent angular distance between the source an the Sun, from the observer's point of view

Since: 1.3

Author: Attila Kovacs

See also: novas_moon_angle()

References novas_object_sep(), and NOVAS_SUN_INIT.

◆ 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 *restrict	position,
		double *restrict	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[restrict 2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *restrict	position,
		double *restrict	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 *restrict	position,
		double *restrict	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[restrict 2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *restrict	position,
		double *restrict	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 *restrict	position,
		double *restrict	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[restrict 2],
		enum novas_planet	body,
		enum novas_origin	origin,
		double *restrict	position,
		double *restrict	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 *restrict	name,
		double	jd_tdb,
		int *restrict	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 at build time by setting the DEFAULT_READEPH variable in the config.mk.

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. An actual implementation might use this and/or the name to identify the object.
	name	The name of the solar-system body (usually upper-case). An actual implementation might use this and/or `mp` to identify the object.
	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.

Deprecated:: (legacy function) Use set_ephem_provider() instead to specify what function should be used to calculate ephemeris positions for Solar-system objects. This prototype is provided to extend support for legacy NOVAS C applications only. In NOVAS, the function had to be user defined, as a custom implementation.

See also: set_ephem_provider(); novas_ephem_provider; ephemeris(); NOVAS_EPHEM_OBJECT

◆ 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 *restrict	position,
		double *restrict	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.

Deprecated:: (legacy function) Use set_planet_provider() instead to specify what function should be used to calculate ephemeris positions for major planets. This function is provided to extend support for legacy NOVAS C applications only. In NOVAS, the function had to be user defined, either by linking against a solsys[1-3].c module, or by providing a custom user implementation.

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

References planet_eph_manager(), and planet_jplint().

◆ solarsystem_hp()

short solarsystem_hp	(	const double	jd_tdb[restrict 2],
		short	body,
		short	origin,
		double *restrict	position,
		double *restrict	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...)

Deprecated:: (legacy function) Use set_planet_provider_hp() instead to specify what function should be used to calculate high-precision ephemeris positions for major planets. This function is provided to extend support for legacy NOVAS C applications only. In NOVAS, the function had to be user defined, either by linking against a solsys[1-3].c module, or by providing a custom user implementation.

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

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

◆ make_orbital_object()

◆ naif_to_novas_planet()

◆ novas_approx_heliocentric()

◆ novas_approx_sky_pos()

◆ novas_helio_dist()

◆ novas_make_moon_orbit()

◆ novas_make_planet_orbit()

◆ novas_moon_angle()

◆ novas_moon_phase()

◆ novas_next_moon_phase()

◆ novas_orbit_native_posvel()

◆ novas_orbit_posvel()

◆ novas_planet_for_name()

◆ novas_set_orbsys_pole()

◆ novas_solar_illum()

◆ novas_solar_power()

◆ novas_sun_angle()

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