solarsystem.h File Reference

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/m2] 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:

1. 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.
2. 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.
3. 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

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

REFERENCES:

1. https://orbital-mechanics.space/reference/planetary-parameters.html, Table 3.
2. 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.
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.

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:

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

REFERENCES:

1. Ryan S. Park et al 2021 AJ 161 105, DOI 10.3847/1538-3881/abd414
2. 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()

Function Documentation

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

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