Loading...
Searching...
No Matches
moon.c File Reference

## Functions

int | novas_make_moon_mean_orbit (double jd_tdb, novas_orbital *restrict orbit)
| Gets mean orbital elements for the Moon relative to the geocenter for the specified epoch of observation.
int | novas_make_moon_orbit (double jd_tdb, novas_orbital *restrict orbit)
| Gets an approximation of the current Keplerian orbital elements for the Moon relative to the geocenter for the specified epoch of observation.
int | novas_moon_elp_ecl_pos (double jd_tdb, double limit, double *pos)
| Calculates the Moon's geocentric position using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.
int | novas_moon_elp_ecl_vel (double jd_tdb, double limit, double *vel)
| Calculates the Moon's geocentric velocity using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.
int | novas_moon_elp_posvel (const novas_frame *restrict frame, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_posvel_fp (const novas_frame *restrict frame, double limit, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_sky_pos (const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict pos)
| Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_sky_pos_fp (const novas_frame *restrict frame, double limit, enum novas_reference_system sys, sky_pos *restrict pos)
| Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
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.

## Detailed Description

Date
  Created on Dec 11, 2025

Author
  Attila Kovacs

This module implements self-contained calculations for the Moon's position, such as via Keplerian orbital approximation, and through a semi-analytical model by Chapront-Touze & Chapront 1988 / Chapront & Francou 2002, 2003.

In principle, the latter can predict the Moon's position to the 10-m level precision, but is quite expensive to calculate with around 35,000 sinusoidal terms. In SuperNOVAS we offer only a truncated version, with 100-m level precision (typically), using up to 3408 terms. And, one may opt to truncate further to obtain less precises results faster if needed.

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

See also
  solsys-calceph.c, solsys-cspice.c, ephemeris.c

## Function Documentation

## novas_make_moon_mean_orbit()

int novas_make_moon_mean_orbit | ( | double | jd_tdb,
|  | novas_orbital *restrict | orbit )

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

It is based on the secular parameters of the ELP2000-85 model, not including the harmonic series the perturbation terms. As such it has accuracy at the few degrees level only, however it is 'valid' for long-term projections (i.e. for years around the orbit's reference epoch) at that coarse level.

For the short-term , novas_make_moon_orbit() can provide somewhat more accurate predictions for up to a day or so around the reference epoch of the orbit.

NOTES:

1. The Moon's orbit is strongly non Keplerian due to the tidal distortions (esp. by the Sun), hence any attempt to describe it it purely Keplerian terms is inherently flawed. If you want to calculate the Moon's position (and/or velocity) with some precision, without using ephemerides, you should probably use the ELP2000/MPP02 model provided by novas_moon_elp_posvel() and novas_moon_elp_sky_pos().

REFERENCES:

1. Chapront, J. et al., 2002, A&A 387, 700–709
2. Chapront-Touze, M, and Chapront, J. 1988, Astronomy and Astrophysics, vol. 190, p. 342-352.
3. Chapront J., & Francou G., 2003, A&A, 404, 735
4. Laskar J., 1986, A&A, 157, 59

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_moon_orbit(), novas_make_planet_orbit(), make_orbital_object()
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()

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

Referenced by supernovas::Orbital::moon_mean_orbit_at(), and novas_make_moon_orbit().

## novas_make_moon_orbit()

int novas_make_moon_orbit | ( | double | jd_tdb,
|  | novas_orbital *restrict | orbit )

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

The orbit includes the most dominant Solar perturbation terms to produce results with an accuracy at the few arcmin level near (+- 0.5 days) the reference time argument of the orbit. The perturbed orbit is based on the ELP/MPP02 model.

While, the ELP/MPP02 model itself can be highly precise, the Moon's orbit is strongly non-Keplerian, and so any attempt to describe it in purely Keplerian terms is inherently flawed, which is the reason for the generally poor accuracy of this model.

REFERENCES:

1. Chapront, J. et al., 2002, A&A 387, 700–709
2. Chapront-Touze, M, and Chapront, J. 1988, Astronomy and Astrophysics, vol. 190, p. 342-352.
3. Chapront J., Francou G., 2003, A&A, 404, 735

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

Author
  Attila Kovacs

See also
  novas_make_moon_mean_orbit(), novas_make_planet_orbit(), make_orbital_object()
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()

References novas_delaunay_args::D, novas_delaunay_args::F, novas_delaunay_args::l, novas_delaunay_args::l1, NOVAS_AU, NOVAS_JD_J2000, NOVAS_KM, and novas_make_moon_mean_orbit().

Referenced by supernovas::Orbital::moon_orbit_at(), and novas_approx_heliocentric().

## novas_moon_elp_ecl_pos()

int novas_moon_elp_ecl_pos | ( | double | jd_tdb,
|  | double | limit,
|  | double * | pos )

Calculates the Moon's geocentric position using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.

the inertial ecliptic and equinox of J2000), down to the specified limiting term amplitude.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below 1 km level (and less than 100 meter error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | limit | [arcsec|km] Sum only the harmonic terms with amplitudes larger than this limit.
  [out] | pos | [AU] Output geocentric position vector w.r.t. the intertial ecliptic and equinox of J2000.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()
  novas_make_moon_orbit()

References NOVAS_AU, NOVAS_EARTH, NOVAS_JD_J2000, NOVAS_KM, NOVAS_NEPTUNE, NOVAS_SATURN, NOVAS_VENUS, and planet_lon().

Referenced by novas_moon_elp_ecl_vel(), novas_moon_elp_posvel_fp(), and novas_moon_phase().

## novas_moon_elp_ecl_vel()

int novas_moon_elp_ecl_vel | ( | double | jd_tdb,
|  | double | limit,
|  | double * | vel )

Calculates the Moon's geocentric velocity using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.

the inertial ecliptic and equinox of J2000), down to the specified limiting term amplitude.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | limit | [arcsec|km] Sum only the harmonic terms with amplitudes larger than this limit.
  [out] | vel | [AU/day] Output geocentric velocity vector w.r.t. the intertial ecliptic and equinox of J2000.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()
  novas_make_moon_orbit()

References novas_moon_elp_ecl_pos().

Referenced by novas_moon_elp_posvel_fp().

## novas_moon_elp_posvel()

int novas_moon_elp_posvel | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 km level (and less than 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | [AU] The Moon's position vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.
  [out] | vel | [AU/day] The Moon's ICRS velocity vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.

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

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel_fp(), novas_moon_elp_sky_pos()
  novas_make_moon_orbit(), novas_geom_posvel()

References novas_moon_elp_posvel_fp().

## novas_moon_elp_posvel_fp()

int novas_moon_elp_posvel_fp | ( | const novas_frame *restrict | frame,
|  | double | limit,
|  | enum novas_reference_system | sys,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

Only terms larger than the specified limit are used to provide a result with the desired precision.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 km level (and less than 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | limit | [arcsec|km] Sum only terms with amplitudes larger than this limit. The resulting accuracy is typically an order-of-magnitude above the set limiting amplitude.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | [AU] The Moon's position vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.
  [out] | vel | [AU/day] The Moon's ICRS velocity vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos_fp()
  novas_make_moon_orbit(), novas_geom_posvel()

References ecl2equ_vec(), NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_J2000, NOVAS_JD_J2000, novas_make_transform(), NOVAS_MEAN_EQUATOR, novas_moon_elp_ecl_pos(), novas_moon_elp_ecl_vel(), NOVAS_REDUCED_ACCURACY, NOVAS_TDB, and novas_transform_vector().

Referenced by supernovas::Frame::geometric_moon_elp2000(), novas_moon_elp_posvel(), and novas_moon_elp_sky_pos_fp().

## novas_moon_elp_sky_pos()

int novas_moon_elp_sky_pos | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | pos )

Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 arcsec level (and less than 0.1 arcsec or 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | The Moon's position, relative to the true equator and equinox of date.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_sky_pos_fp(), novas_moon_elp_posvel()
  novas_make_moon_orbit(), novas_sky_pos()

References novas_moon_elp_sky_pos_fp().

## novas_moon_elp_sky_pos_fp()

int novas_moon_elp_sky_pos_fp | ( | const novas_frame *restrict | frame,
|  | double | limit,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | pos )

Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

Only terms larger than the specified limit are used to provide a result with the desired precision.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 arcsec level (and less than 0.1 arcsec or 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | limit | [arcsec|km] Sum only terms with amplitudes larger than this limit. The resulting accuracy is typically an order-of-magnitude above the set limiting amplitude.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | The Moon's position, relative to the true equator and equinox of date.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_sky_pos(), novas_moon_elp_posvel()
  novas_make_moon_orbit(), novas_sky_pos()

References aberration(), NOVAS_AU_PER_DAY, NOVAS_ICRS, NOVAS_KMS, novas_make_transform(), novas_moon_elp_posvel_fp(), novas_transform_vector(), novas_vlen(), and vector2radec().

Referenced by supernovas::Frame::apparent_moon_elp2000(), and novas_moon_elp_sky_pos().

## 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 the ELP2000/MPP02 semi-analytical model for the Moon (Chapront & Francou, 2002, 2003), 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.
3. As of version 1.6, this function relies on the ELP2000/MM02 semi-analytical model of the Moon by Chapront & Francou (2003).
4. This function caches the result of the last calculation.

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.
6. Chapront J., & Francou G., 2003, A&A, 404, 735<

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_planet_orbit(), novas_moon_elp_ecl_pos(), NOVAS_ORBIT_INIT, novas_orbit_native_posvel(), and vector2radec().

Referenced by supernovas::Time::moon_phase(), and novas_next_moon_phase().

## 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 the ELP2000/MPP02 semi-analytical model for the Moon (Chapront & Francou, 2002, 2003), 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.
3. As of version 1.6, this function relies on the ELP2000/MM02 semi-analytical model of the Moon by Chapront & Francou (2003).

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., & Francou, G., 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().

Referenced by supernovas::Time::next_moon_phase().