Macros
#define	DE405_AU 1.4959787069098932e+11
	[m] Astronomical unit (AU).

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)
	Function to obtain ephemeris data for minor planets, which are not handled by the solarsystem() type calls.

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

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

Enumerations
enum	novas_origin { NOVAS_BARYCENTER = 0 , NOVAS_HELIOCENTER }
	The origin of the ICRS system for referencing positions and velocities for solar-system bodies. More...

enum	novas_reference_plane { NOVAS_ECLIPTIC_PLANE = 0 , NOVAS_EQUATORIAL_PLANE }
	The plane in which values, such as orbital parameters are referenced. More...

Functions
int	cspice_add_kernel (const char *filename)
	Adds a SPICE kernel to the currently managed open kernels.

int	cspice_remove_kernel (const char *filename)
	Removes a SPICE kernel from the currently managed open kernels.

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.

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 earth_sun_calc(), if enable_earth_sun_hp() is set to true (non-zero).

void	enable_earth_sun_hp (int value)
	Specify whether the high-precision call is allowed to return a low-precision result.

novas_ephem_provider	get_ephem_provider ()
	Returns the user-defined ephemeris accessor function.

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	novas_calceph_is_thread_safe ()
	Checks if the CALCEPH plugin is thread safe.

int	novas_calceph_use_ids (enum novas_id_type idtype)
	Sets the type of Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types.

int	novas_cspice_is_thread_safe ()
	Checks if the CSPICE plugin is thread safe.

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.

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.

int	novas_use_calceph (t_calcephbin *eph)
	Sets a ephemeris provider for Solar-system objects using the CALCEPH C library and the specified set of ephemeris files.

int	novas_use_calceph_planets (t_calcephbin *eph)
	Sets the CALCEPH C library and the specified ephemeris data as the ephemeris provider for the major planets (and Sun, Moon, SSB...).

int	novas_use_cspice ()
	Sets CSPICE as the default ephemeris provider for all types of Solar-system objects (both NOVAS_PLANET and NOVAS_EPHEM_OBJECT types).

int	novas_use_cspice_ephem ()
	Sets a ephemeris provider for NOVAS_EPHEM_OBJECT types using the NAIF CSPICE library.

int	novas_use_cspice_planets ()
	Sets CSPICE as the ephemeris provider for the major planets (and Sun, Moon, SSB...) using the NAIF CSPICE library.

int	obs_planets (double jd_tdb, enum novas_accuracy accuracy, const double restrict pos_obs, int pl_mask, novas_planet_bundle restrict planets)
	Calculates the positions and velocities for the Solar-system bodies, e.g.

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.

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.

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_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

Macro Definition Documentation

◆ DE405_AU

#define DE405_AU 1.4959787069098932e+11

[m] Astronomical unit (AU).

based on DE-405. (old definition)

See also: NOVAS_AU

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; make_ephem_object(), novas_sky_pos(), novas_geom_posvel()

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; make_planet(), novas_sky_pos(), novas_geom_posvel()

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(); make_planet(), novas_sky_pos(), novas_geom_posvel(), grav_planets(), grav_undo_planets()

Since: 1.0

Author: Attila Kovacs

Enumeration Type Documentation

◆ novas_origin

enum novas_origin

The origin of the ICRS system for referencing positions and velocities for solar-system bodies.

See also: ephemeris(), NOVAS_ORIGIN_TYPES

Enumerator
NOVAS_BARYCENTER	Origin at the Solar-system baricenter (i.e. BCRS)
NOVAS_HELIOCENTER	Origin at the center of the Sun.

◆ novas_reference_plane

enum novas_reference_plane

The plane in which values, such as orbital parameters are referenced.

Author: Attila Kovacs

Since: 1.2

See also: novas_orbital_system

Enumerator
NOVAS_ECLIPTIC_PLANE	the plane of the ecliptic
NOVAS_EQUATORIAL_PLANE	The plane of the equator.

Function Documentation

◆ cspice_add_kernel()

int cspice_add_kernel ( const char * filename )

Adds a SPICE kernel to the currently managed open kernels.

Subsequent ephemeris lookups through CSPICE will use the added kernel. It's simply a wrapper around the CSPICE furnsh_c() routine, with graceful error handling. You can of course add kernels using furnsh_c() directly to the same effect.

REFERENCES:

https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/furnsh_c.html

Parameters

filename The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp")

Returns: 0 if successful, or else -1 if there was an error (errno will be set to EINVAL).

Author: Attila Kovacs

Since: 1.2

See also: cspice_remove_kernel(), novas_use_cspice()

◆ cspice_remove_kernel()

int cspice_remove_kernel ( const char * filename )

Removes a SPICE kernel from the currently managed open kernels.

Subsequent ephemeris lookups through CSPICE will not use the removed kernel data. It's simply a wrapper around the CSPICE unload_c() routine, with graceful error handling. You can of course remove kernels using unload_c() directly to the same effect.

REFERENCES:

https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/unload_c.html

Parameters

filename The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp")

Returns: 0 if successful, or else -1 if there was an error (errno will be set to EINVAL).

Author: Attila Kovacs

Since: 1.2

See also: cspice_add_kernel()

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

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.

Since: 1.0

Author: Attila Kovacs

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

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

◆ novas_calceph_is_thread_safe()

int novas_calceph_is_thread_safe ( )

Checks if the CALCEPH plugin is thread safe.

Returns: TRUE (1) if the lugin is thread safe, or else FALSE (0).

Since: 1.5

◆ novas_calceph_use_ids()

int novas_calceph_use_ids ( enum novas_id_type idtype )

Sets the type of Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types.

CALCEPH supports the use of both NAIF and its own numbering system to identify Solar-system bodies. So, this function gives you the choice on which numbering system you want to use in object data structures. The choice does not affect major planets (which always use the NOVAS numbering scheme), or catalog objects.

Parameters

idtype NOVAS_ID_NAIF to use NAIF IDs (default) or else NOVAS_ID_CALCEPH to use the CALCEPH body numbering convention for object.

Returns: 0 if successful or else -1 (errno set to EINVAL) if the input value is invalid.

See also: make_planet(), make_ephem_object(), NOVAS_EPHEM_OBJECT

References NOVAS_ID_CALCEPH, and NOVAS_ID_NAIF.

◆ novas_cspice_is_thread_safe()

int novas_cspice_is_thread_safe ( )

Checks if the CSPICE plugin is thread safe.

Returns: TRUE (1) if the lugin is thread safe, or else FALSE (0).

Since: 1.5

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

int novas_use_calceph ( t_calcephbin * eph )

Sets a ephemeris provider for Solar-system objects using the CALCEPH C library and the specified set of ephemeris files.

If the supplied ephemeris files contain data for major planets also, they can be used by planet_calceph() / planet_calceph_hp() also, unless a separate CALCEPH ephemeris data is set via novas_use_calceph_planets().

The call also make CALCEPH the default ephemeris provider for all types of Solar-system objects. If you want to use another provider for major planets, you need to call set_planet_provider() / set_planet_provider_hp() afterwards to specify a different provider for the major planets (and Sun, Moon, SSB...).

Parameters

eph	Pointer to the CALCEPH ephemeris data that have been opened.

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

See also: novas_calceph_use_ids(), novas_use_calceph_planets(), set_ephem_provider()

Author: Attila Kovacs

Since: 1.2

References novas_use_calceph_planets(), and set_ephem_provider().

◆ novas_use_calceph_planets()

int novas_use_calceph_planets ( t_calcephbin * eph )

Sets the CALCEPH C library and the specified ephemeris data as the ephemeris provider for the major planets (and Sun, Moon, SSB...).

Parameters

eph	Pointer to the CALCEPH ephemeris data for the major planets (including Sun, Moon, SSB...) that have been opened.

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

Author: Attila Kovacs

Since: 1.2

See also: novas_use_calceph(), set_planet_provider(), set_planet_provider_hp()

References set_planet_provider(), and set_planet_provider_hp().

◆ novas_use_cspice()

int novas_use_cspice ( )

Sets CSPICE as the default ephemeris provider for all types of Solar-system objects (both NOVAS_PLANET and NOVAS_EPHEM_OBJECT types).

CSPICE is configured to suppress error messages and to not exit on errors, since we will check errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.

Returns: 0

Author: Attila Kovacs

Since: 1.2

See also: novas_use_cspice_planets(), novas_use_cspice_ephem(), cspice_add_kernel()

References novas_use_cspice_ephem(), and novas_use_cspice_planets().

◆ novas_use_cspice_ephem()

int novas_use_cspice_ephem ( )

Sets a ephemeris provider for NOVAS_EPHEM_OBJECT types using the NAIF CSPICE library.

CSPICE is configured to suppress error messages and to not exit on errors, since we will check errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.

Returns: 0

Author: Attila Kovacs

Since: 1.2

See also: novas_use_cspice_planets(), novas_use_cspice(), cspice_add_kernel(); set_ephem_provider()

References set_ephem_provider().

◆ novas_use_cspice_planets()

int novas_use_cspice_planets ( )

Sets CSPICE as the ephemeris provider for the major planets (and Sun, Moon, SSB...) using the NAIF CSPICE library.

CSPICE is configured to suppress error messages and to not exit on errors, since we will check errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.

Returns: 0

Author: Attila Kovacs

Since: 1.2

See also: novas_use_cspice_ephem(), novas_use_cspice(), cspice_add_kernel(); set_planet_provider(), set_planet_provider_hp()

References set_planet_provider(), and set_planet_provider_hp().

◆ obs_planets()

int obs_planets	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *restrict	pos_obs,
		int	pl_mask,
		novas_planet_bundle *restrict	planets )

Calculates the positions and velocities for the Solar-system bodies, e.g.

for use for gravitational deflection calculations. The planet positions are calculated relative to the observer location, while velocities are w.r.t. the SSB. Both positions and velocities are antedated for light travel time, so they accurately reflect the apparent position (and barycentric motion) of the bodies from the observer's perspective.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated.
	pos_obs	[AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
	pl_mask	Bitwise `(1 << planet-number)` mask indicating which planets to request data for. See enum novas_planet for the enumeration of planet numbers.
[out]	planets	Pointer to apparent planet data to populate. The planets with non-zero mask bits will have have positions and velocities calculated. See enum novas_planet for the enumeration of planet numbers.

Returns: 0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs, or the error from ephemeris().

See also: enum novas_planet, grav_planets(), grav_undo_planets(), set_planet_provider(), set_planet_provider_hp()

Since: 1.1

Author: Attila Kovacs

References light_time2(), make_planet(), novas_debug(), NOVAS_DEBUG_EXTRA, NOVAS_DEBUG_OFF, novas_get_debug_mode(), NOVAS_PLANETS, and NOVAS_SUN.

◆ 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, but in reality it's exactly the same as the high-precision version, except for the way the TDB-based Julian date is specified.

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 defined by novas_planet_provider.

Since: 1.0

Author: Attila Kovacs

See also: planet_ephem_provider_hp(), set_ephem_provider()

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

Since: 1.0

Author: Attila Kovacs

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

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

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

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DE405_AU

Typedef Documentation

◆ novas_ephem_provider

◆ novas_planet_provider

◆ novas_planet_provider_hp

Enumeration Type Documentation

◆ novas_origin

◆ novas_reference_plane

Function Documentation

◆ cspice_add_kernel()

◆ cspice_remove_kernel()

◆ earth_sun_calc()

◆ earth_sun_calc_hp()

◆ enable_earth_sun_hp()

◆ get_ephem_provider()

◆ get_planet_provider()

◆ get_planet_provider_hp()

◆ novas_calceph_is_thread_safe()

◆ novas_calceph_use_ids()

◆ novas_cspice_is_thread_safe()

◆ novas_helio_dist()

◆ novas_solar_power()

◆ novas_use_calceph()

◆ novas_use_calceph_planets()

◆ novas_use_cspice()

◆ novas_use_cspice_ephem()

◆ novas_use_cspice_planets()

◆ obs_planets()

◆ planet_ephem_provider()

◆ planet_ephem_provider_hp()

◆ set_ephem_provider()

◆ set_planet_provider()

◆ set_planet_provider_hp()