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

Various functions to deal with gravitational effects of the major Solar-system bodies on the astrometry. More...

## Functions

short | grav_def (double jd_tdb, enum novas_observer_place unused, enum novas_accuracy accuracy, const double *pos_src, const double *pos_obs, double *out)
| (primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the major gravitating bodies in the solar system.
int | grav_planets (const double *pos_src, const double *pos_obs, const novas_planet_bundle *restrict planets, double *out)
| (primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the specified gravitating bodies in the solar system.
double | grav_redshift (double M_kg, double r_m)
| Returns the gravitational redshift (z) for light emitted near a massive spherical body at some distance from its center, and observed at some very large (infinite) distance away.
int | grav_undef (double jd_tdb, enum novas_accuracy accuracy, const double *pos_app, const double *pos_obs, double *out)
| (primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the major gravitating bodies in the solar system.
int | grav_undo_planets (const double *pos_app, const double *pos_obs, const novas_planet_bundle *restrict planets, double *out)
| (primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.
int | grav_vec (const double *pos_src, const double *pos_obs, const double *pos_body, double rmass, double *out)
| (primarily for internal use) Corrects position vector for the deflection of light in the gravitational field of anarbitrary body.

## Variables

int | grav_bodies_full_accuracy = DEFAULT_GRAV_BODIES_FULL_ACCURACY
| Current set of gravitating bodies to use for deflection calculations in full accuracy mode.
int | grav_bodies_reduced_accuracy = DEFAULT_GRAV_BODIES_REDUCED_ACCURACY
| Current set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

## Detailed Description

Various functions to deal with gravitational effects of the major Solar-system bodies on the astrometry.

Date
  Created on Mar 6, 2025

Author
  Attila Kovacs and G. Kaplan

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

## Function Documentation

## grav_def()

short grav_def | ( | double | jd_tdb,
|  | enum novas_observer_place | unused,
|  | enum novas_accuracy | accuracy,
|  | const double * | pos_src,
|  | const double * | pos_obs,
|  | double * | out )

(primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the major gravitating bodies in the solar system.

This function valid for an observed body within the solar system as well as for a star.

If 'accuracy' is NOVAS_FULL_ACCURACY (0), the deflections due to the Sun, Jupiter, Saturn, and Earth are calculated. Otherwise, only the deflection due to the Sun is calculated. In either case, deflection for a given body is ignored if the observer is within ~1500 km of the center of the gravitating body.

The number of bodies used at full and reduced accuracy can be set by changing the grav_bodies_reduced_accuracy, and grav_bodies_full_accuracy lobal variables.

NOTES:

1. This function is called by novas_sky_pos(), novas_app_to_geom(), novas_geom_to_app() and place() to calculate gravitational deflections as appropriate for positioning sources precisely. The gravitational deflection due to planets requires a planet calculator function to be configured, e.g. via set_planet_provider_hp().

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | unused | The type of observer frame (no longer used)
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated.
  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  [out] | out | [AU] Position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, corrected for gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

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

See also
  grav_undef()
  novas_sky_pos(), novas_geom_to_app(), novas_app_to_geom(), set_planet_provider_hp(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy

References grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_planets(), NOVAS_FULL_ACCURACY, and obs_planets().

## grav_planets()

int grav_planets | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | const novas_planet_bundle *restrict | planets,
|  | double * | out )

(primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the specified gravitating bodies in the solar system.

This function is valid for an observed body within the solar system as well as for a star.

NOTES:

1. The gravitational deflection due to planets requires a planet calculator function to be configured, e.g. via set_planet_provider_hp().

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  | planets | Apparent planet data containing positions and velocities for the major gravitating bodies in the solar-system.
  [out] | out | [AU] Position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, corrected for gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs.

See also
  grav_def(), grav_undo_planets()
  novas_sky_pos(), novas_geom_to_app(), obs_planets()

Since
  1.1

Author
  Attila Kovacs

References d_light(), grav_vec(), NOVAS_PLANETS, NOVAS_RMASS_INIT, and novas_vlen().

## grav_undef()

int grav_undef | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | pos_app,
|  | const double * | pos_obs,
|  | double * | out )

(primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the major gravitating bodies in the solar system.

This function is valid for an observed body within the solar system as well as for a star.

If 'accuracy' is set to zero (full accuracy), three bodies (Sun, Jupiter, and Saturn) are used in the calculation. If the reduced-accuracy option is set, only the Sun is used in the calculation. In both cases, if the observer is not at the geocenter, the deflection due to the Earth is included.

he number of bodies used at full and reduced accuracy can be set by changing the grav_bodies_reduced_accuracy, and grav_bodies_full_accuracy global variables.

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | pos_app | [AU] Apparent position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  [out] | out | [AU] Nominal position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, without gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL (errno = EINVAL) or if the result did not converge (errno = ECANCELED), or else an error from obs_planets().

See also
  grav_def()
  novas_app_to_geom(), set_planet_provider_hp(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy

Since
  1.1

Author
  Attila Kovacs

References grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_undo_planets(), NOVAS_FULL_ACCURACY, and obs_planets().

## grav_undo_planets()

int grav_undo_planets | ( | const double * | pos_app,
|  | const double * | pos_obs,
|  | const novas_planet_bundle *restrict | planets,
|  | double * | out )

(primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | pos_app | [AU] Apparent position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  | planets | Apparent planet data containing positions and velocities for the major gravitating bodies in the solar-system.
  [out] | out | [AU] Nominal position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, without gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL.

See also
  grav_planets(), grav_undef()
  novas_app_to_geom(), obs_planets()

Since
  1.1

Author
  Attila Kovacs

References grav_planets(), novas_inv_max_iter, and novas_vlen().

## grav_vec()

int grav_vec | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | const double * | pos_body,
|  | double | rmass,
|  | double * | out )

(primarily for internal use) Corrects position vector for the deflection of light in the gravitational field of anarbitrary body.

This function valid for an observed body within the solar system as well as for a star.

NOTES:

1. This function is called by grav_def() to calculate appropriate gravitational deflections around the massive Solar-system objects.

REFERENCES:

1. Murray, C.A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
2. See also formulae in Section B of the Astronomical Almanac, or
3. Kaplan, G. et al. (1989) Astronomical Journal 97, 1197-1210, section iii f.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), components in AU.
  | pos_obs | [AU] Position vector of gravitating body, with respect to origin at solar system barycenter, components in AU.
  | pos_body | [AU] Position 3-vector of gravitating body, with respect to origin at solar system barycenter, components in AU.
  | rmass | [1/Msun] Reciprocal mass of gravitating body in solar mass units, that is, Sun mass / body mass.
  [out] | out | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), corrected for gravitational deflection, components in AU. It can the same vector as the input.

Returns
  0 if successful, or -1 if any of the input vectors is NULL.

See also
  grav_def()

References NOVAS_AU, and novas_vlen().