SuperNOVAS Solar-system related types, definitions, and functions (included in novas.h). More...

Macros
#define	DEFAULT_GRAV_BODIES_FULL_ACCURACY ( DEFAULT_GRAV_BODIES_REDUCED_ACCURACY \| (1 << NOVAS_JUPITER) \| (1 << NOVAS_SATURN) )
	Default set of gravitating bodies to use for deflection calculations in full accuracy mode.

#define	DEFAULT_GRAV_BODIES_REDUCED_ACCURACY ( (1 << NOVAS_SUN) )
	Default set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

#define	NOVAS_ID_TYPES
	Number of different Solar-system body ID types enumerated.

#define	NOVAS_PLANET_GRAV_Z_INIT
	Gravitational redshifts for major planets (and Moon and Sun) for light emitted at surface and detected at a large distance away.

#define	NOVAS_PLANET_NAMES_INIT
	String array initializer for Major planet names, matching the enum novas_planet.

#define	NOVAS_PLANET_RADII_INIT
	Array initializer for mean planet radii in meters, matching the enum novas_planet.

#define	NOVAS_RMASS_INIT
	Reciprocal masses of solar system bodies, from DE-405 (Sun mass / body mass).

#define	NOVAS_SOLAR_CONSTANT 1367.0
	[W/m²] The Solar Constant i.e., typical incident Solar power on Earth.

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_id_type { NOVAS_ID_NAIF = 0 , NOVAS_ID_CALCEPH }
	Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types. More...

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

short	ephemeris (const double restrict jd_tdb, const object restrict body, enum novas_origin origin, enum novas_accuracy accuracy, double restrict pos, double restrict vel)
	Retrieves the position and velocity of a solar system body using the currently configured plugins that provide them.

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

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

enum novas_planet	naif_to_novas_planet (long id)
	Converts a NAIF ID to a NOVAS major planet ID.

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

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.

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.

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.

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.

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.

double	novas_moon_phase (double jd_tdb)
	Calculates the Moon's phase at a given time.

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.

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.

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.

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.

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.

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.

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.

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.

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.

long	novas_to_naif_planet (enum novas_planet id)
	Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID.

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.

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

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.

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)

Variables
int	grav_bodies_full_accuracy
	Current set of gravitating bodies to use for deflection calculations in full accuracy mode.

int	grav_bodies_reduced_accuracy
	Current set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

Detailed Description

SuperNOVAS Solar-system related types, definitions, and functions (included in novas.h).

Solar-system objects come in multiple varieties from the perspective of SuperNOVAS:

Major planets, plus the Sun, Moon, Solar-system Barycenter (SSB), and since v1.2 also the Earth-Moon Barycenter (EMB), and the Pluto system barycenter.
Ephemeris objects, which historically have been all sources other than the major planets above. NOVAS treated these apart from the major planets, and so we follow.
Keplerian orbital elements (since v1.2), which can be used as an alternative to ephemerides. With short term projections, using up-to-date orbital elements, such as published by the IAU Minor Planet Center, one may calculate positions for asteroids, comets, and near-Earth objects (NEOs) with similar accuracy as with ephemerides. However, long-term application, orbital elements are typically much less accurate.

Accordingly, this header defines various functions for the above types of Solar-system objects.

High-precision calculations of Solar-system sources typically require access to precise ephemeris data. Users may configure SuperNOVAS with different ephemeris provider functions for the major planets and other ephemeris object, respectively (see novas_planet_provider, novas_planet_provider_hp, and novas_ephem_provider types). These providers may be selected and changed at runtime, including custom user supplied implementations. One may also select a default provider at build time, if needded, for better legacy support for old NOVAS C applications without runtime selection (our default is to rely on the self-contained solsys3.c, which calculates approximate positions for the Earth and Sun only). We however recommend you stick to runtime configuration only, if possible.

Besides the high-precision position and velocity calculations, you can do a lot more with Solar-system sources also. For example, you can calculate the Moon's phase, or the angle between an observed source and the Sun or Moon (often a consideration in deciding whether to observe a source), or calculate the solar illumination fraction for planets (especially the inner ones), or the typical incident solar power on the illuminated side. And, even without a high-precison ephemeris provider, you may still calculate the position of the major planets with arcminute level accuracy also.

Author: Attila Kovacs and G. Kaplan

Macro Definition Documentation

◆ DEFAULT_GRAV_BODIES_FULL_ACCURACY

#define DEFAULT_GRAV_BODIES_FULL_ACCURACY ( DEFAULT_GRAV_BODIES_REDUCED_ACCURACY | (1 << NOVAS_JUPITER) | (1 << NOVAS_SATURN) )

Default set of gravitating bodies to use for deflection calculations in full accuracy mode.

Since: 1.1

Author: Attila Kovacs

See also: grav_bodies_full_accuracy, grav_planets(), grav_undo_planets()

◆ DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

#define DEFAULT_GRAV_BODIES_REDUCED_ACCURACY ( (1 << NOVAS_SUN) )

Default set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

(only apply gravitational deflection for the Sun.)

Since: 1.1

Author: Attila Kovacs

See also: grav_bodies_reduced_accuracy, grav_planets(), grav_undo_planets()

◆ NOVAS_ID_TYPES

#define NOVAS_ID_TYPES

Number of different Solar-system body ID types enumerated.

Author: Attila Kovacs

Since: 1.2

See also: enum novas_id_type

◆ NOVAS_PLANET_GRAV_Z_INIT

#define NOVAS_PLANET_GRAV_Z_INIT

Gravitational redshifts for major planets (and Moon and Sun) for light emitted at surface and detected at a large distance away.

Barycenters are not considered, and for Pluto the redshift for the Pluto system is assumed for distant observers.

See also: enum novas_planet; NOVAS_PLANETS

Since: 1.1.1

Author: Attila Kovacs

◆ NOVAS_PLANET_NAMES_INIT

#define NOVAS_PLANET_NAMES_INIT

String array initializer for Major planet names, matching the enum novas_planet.

E.g.

const char *planet_names[] = NOVAS_PLANET_NAMES_INIT;

NOVAS_PLANET_NAMES_INIT

#define NOVAS_PLANET_NAMES_INIT

String array initializer for Major planet names, matching the enum novas_planet.

Definition solarsystem.h:73

Since: 1.2

Author: Attila Kovacs

See also: enum novas_planet

◆ NOVAS_PLANET_RADII_INIT

#define NOVAS_PLANET_RADII_INIT

Array initializer for mean planet radii in meters, matching the enum novas_planet.

E.g.

const double *planet_radii[] = NOVAS_PLANET_RADII_INIT;

NOVAS_PLANET_RADII_INIT

#define NOVAS_PLANET_RADII_INIT

Array initializer for mean planet radii in meters, matching the enum novas_planet.

Definition solarsystem.h:103

REFERENCES:

https://orbital-mechanics.space/reference/planetary-parameters.html, Table 3.
B. A. Archinal, et al., Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements:
1. Celestial Mechanics and Dynamical Astronomy, 130(3):22, March 2018. doi:10.1007/s10569-017-9805-5.
B. A. Archinal, et al., Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements:
1. Celestial Mechanics and Dynamical Astronomy, 130(3):22, March 2018. doi:10.1007/s10569-017-9805-5.

Since: 1.5

Author: Attila Kovacs

See also: enum novas_planet, NOVAS_PLANET_NAMES_INIT, NOVAS_RMASS_INIT

◆ NOVAS_RMASS_INIT

#define NOVAS_RMASS_INIT

Reciprocal masses of solar system bodies, from DE-405 (Sun mass / body mass).

[0]: Earth/Moon barycenter (legacy from NOVAS C), MASS[1] = Mercury, ...,

Barycentric reciprocal masses (index 12, 13) are not set.

NOTES:

The values have been updated to used DE440 data (Park et al. 2021) in 1.4.

REFERENCES:

Ryan S. Park et al 2021 AJ 161 105, DOI 10.3847/1538-3881/abd414
IERS Conventions, Chapter 3, Table 3.1

Since: 1.2

Author: Attila Kovacs

See also: enum novas_planet, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANET_RAII_INIT, NOVAS_PLANETS_GRAV_Z_INIT

◆ NOVAS_SOLAR_CONSTANT

#define NOVAS_SOLAR_CONSTANT 1367.0

[W/m²] The Solar Constant i.e., typical incident Solar power on Earth.

The value of 1367 Wm⁻² was adopted by the World Radiation Center (Gueymard, 2004).

Since: 1.3

See also: novas_solar_power()

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

◆ ephemeris()

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

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

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

Parameters

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

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

See also: set_planet_provider(), set_planet_provider_hp(), set_ephem_provider(); make_planet(), make_ephem_object()

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

◆ get_ephem_provider()

novas_ephem_provider get_ephem_provider ( )

Returns the user-defined ephemeris accessor function.

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

Since: 1.0

Author: Attila Kovacs

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

◆ get_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: make_planet(), make_ephem_object(), make_cat_object(), make_redshifted_object(); novas_case_sensitive(), novas_orbit_posvel(), novas_make_frame()

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.

Author: Attila Kovacs

Since: 1.2

See also: novas_to_naif_planet(), novas_to_dexxx_planet()

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

Author: Attila Kovacs

Since: 1.4

See also: novas_geom_posvel(), ephemeris(), make_orbital_object()

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

Author: Attila Kovacs

Since: 1.2

See also: novas_geom_posvel(), ephemeris(), make_orbital_object()

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

See also: novas_solar_power()

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.

Author: Attila Kovacs

Since: 1.2

See also: novas_to_naif_planet(), naif_to_novas_planet()

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)

Author: Attila Kovacs

Since: 1.2

See also: naif_to_novas_planet()

References NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, 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.

◆ readeph()

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

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 / novas_set_ephem_provider() instead, for dynamically configured implementations at runtime. This prototype is provided only to extend support for legacy NOVAS applications only, where an inplementation had to be linked always.

Legacy NOVAS C function to handle position and velocity calculations for Solar-system sources, beyond the major planets. This function can be defined by an external module, as per the NOVAS C way, provided you compile SuperNOVAS with the READPH_SOURCE option set to specify the source(s) that implement it (in config.mk or the environment). If READEPH_SOURCE in not defined during the build of SuperNOVAS, then this function will not be used by SuperNOVAS, nor will be implemented by it.

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.

See also: novas_ephem_provider

◆ set_ephem_provider()

int set_ephem_provider ( novas_ephem_provider func )

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

Parameters

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

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

Since: 1.0

Author: Attila Kovacs

See also: get_ephem_provider(), set_planet_provider(), set_planet_provider_hp(); novas_use_calceph(), novas_use_cspice()

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

◆ solarsystem()

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

Deprecated: (legacy function) Use set_planet_provider() instead to specify what function should be used to calculate ephemeris positions for major planets.

Legacy NOVAS C function for obtaining planet position / velocity data. This function can be defined by external modules, as per the NOVAS C way, provided you compile SuperNOVAS with the SOLSYS_SOURCE option set to specify the source(s) that implement it (in config.mk or the environment). If SOLSYS_SOURCE in not defined during the build of SuperNOVAS, then this function will be provided by the currently configured novas_planet_provider function, such as earth_sun_calc() if not configured otherwise.

Parameters

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

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

See also: novas_planet, solarsystem_hp(), set_planet_provider(), ephemeris(); novas_sky_pos(), novas_geom_posvel()

◆ solarsystem_hp()

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

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.

Legacy NOVAS C function for obtaining high-precision planet position / velocity data. This function can be defined by external modules, as per the NOVAS C way, provided you compile SuperNOVAS with the SOLSYS_SOURCE option set to specify the source(s) that implement it (in config.mk or the environment). If SOLSYS_SOURCE in not defined during the build of SuperNOVAS, then this function will be provided by the currently configured novas_planet_provider_hp function, such as earth_sun_calc()_hp if not configured otherwise.

Parameters

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

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

See also: solarsystem(), set_planet_provider_hp(), ephemeris(); novas_sky_pos(), novas_geom_posvel(), grav_planets(), grav_undo_planets()

Variable Documentation

◆ grav_bodies_full_accuracy

int grav_bodies_full_accuracy

extern

Current set of gravitating bodies to use for deflection calculations in full accuracy mode.

Each bit signifies whether a given body is to be accounted for as a gravitating body that bends light, such as the bit (1 << NOVAS_JUPITER) indicates whether or not Jupiter is considered as a deflecting body. You should also be sure that you provide ephemeris data for bodies that are designated for the deflection calculation.

Since: 1.1

See also: grav_def(), grav_planets(), DEFAULT_GRAV_BODIES_FULL_ACCURACY; set_ephem_provider_hp()

◆ grav_bodies_reduced_accuracy

int grav_bodies_reduced_accuracy

extern

Current set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

Each bit signifies whether a given body is to be accounted for as a gravitating body that bends light, such as the bit (1 << NOVAS_JUPITER) indicates whether or not Jupiter is considered as a deflecting body. You should also be sure that you provide ephemeris data for bodies that are designated for the deflection calculation.

Since: 1.1

See also: grav_def(), grav_planets(), DEFAULT_GRAV_BODIES_REDUCED_ACCURACY; set_ephem_provider()

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEFAULT_GRAV_BODIES_FULL_ACCURACY

◆ DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

◆ NOVAS_ID_TYPES

◆ NOVAS_PLANET_GRAV_Z_INIT

◆ NOVAS_PLANET_NAMES_INIT

◆ NOVAS_PLANET_RADII_INIT

◆ NOVAS_RMASS_INIT

◆ NOVAS_SOLAR_CONSTANT

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

◆ ephemeris()

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

◆ planet_ephem_provider_hp()

◆ readeph()

◆ set_ephem_provider()

◆ set_planet_provider()

◆ set_planet_provider_hp()

◆ solarsystem()

◆ solarsystem_hp()

Variable Documentation

◆ grav_bodies_full_accuracy

◆ grav_bodies_reduced_accuracy