planets.c File Reference

Functions
int	novas_approx_heliocentric (enum novas_planet id, double jd_tdb, double *restrict pos, double *restrict vel)
int	novas_approx_sky_pos (enum novas_planet id, const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict out)
int	novas_make_moon_orbit (double jd_tdb, novas_orbital *restrict orbit)
int	novas_make_planet_orbit (enum novas_planet id, double jd_tdb, novas_orbital *restrict orbit)
double	novas_moon_phase (double jd_tdb)
double	novas_next_moon_phase (double phase, double jd_tdb)

Detailed Description

Date

Created on Apr 27, 2025

Author

Attila Kovacs

Calculate approximate positions and velocities for the major planets, Sun, Moon, Earth-Moon Barycenter (EMB), and the Solar-system Barycenter (SSB), mainly by using Keplerian orbital elements.

Function Documentation

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:

1. 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).
2. 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:

1. 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:

1. E.M. Standish and J.G. Williams 1992.
2. https://ssd.jpl.nasa.gov/planets/approx_pos.html
3. Chapront, J. et al., 2002, A&A 387, 700–709
4. 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:

1. 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()).
2. 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:

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

Parameters

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

Returns

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

Since

1.4

Author

Attila Kovacs

See also

novas_sky_pos()

novas_app_to_hor()

make_frame()

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

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

1. Chapront, J. et al., 2002, A&A 387, 700–709
2. 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:

1. 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.
2. For Pluto, the Pluto system barycenter orbit is returned.

REFERENCES:

1. E.M. Standish and J.G. Williams 1992.
2. 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_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:

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

1. The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
2. E.M. Standish and J.G. Williams 1992.
3. https://ssd.jpl.nasa.gov/planets/approx_pos.html
4. Chapront, J. et al., 2002, A&A 387, 700–709
5. 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:

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

1. The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
2. E.M. Standish and J.G. Williams 1992.
3. https://ssd.jpl.nasa.gov/planets/approx_pos.html
4. Chapront, J. et al., 2002, A&A 387, 700–709
5. 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().