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)

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

double	grav_redshift (double M_kg, double r_m)

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

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

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

Variables
int	grav_bodies_full_accuracy = DEFAULT_GRAV_BODIES_FULL_ACCURACY

int	grav_bodies_reduced_accuracy = DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

Detailed Description

Date: Created on Mar 6, 2025

Author: Attila Kovacs and G. Kaplan

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

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
	)

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.

NOTES:

This function is called by 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().

REFERENCES:

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(); place(); novas_geom_to_app(); set_planet_provider(); 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
	)

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:

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

REFERENCES:

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: obs_planets(); grav_undo_planets(); grav_def(); novas_geom_to_app(); grav_bodies_full_accuracy; grav_bodies_reduced_accuracy

Since: 1.1

Author: Attila Kovacs

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

◆ grav_redshift()

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.

Parameters

M_kg	[kg] Mass of gravitating body that is contained inside the emitting radius.
r_m	[m] Radius at which light is emitted.

Returns: The gravitational redshift (z) for an observer at very large (infinite) distance from the gravitating body.

See also: redshift_vrad(); unredshift_vrad(); novas_z_add()

Since: 1.2

Author: Attila Kovacs

◆ grav_undef()

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

Computes the gravitationally undeflected position of an observed source position 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 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.

The number of bodies used at full and reduced accuracy can be set by making a change to the code in this function as indicated in the comments.

REFERENCES:

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

Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.

REFERENCES:

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: obs_planets(); grav_planets(); novas_app_to_geom()

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
	)

Corrects position vector for the deflection of light in the gravitational field of an arbitrary body. This function valid for an observed body within the solar system as well as for a star.

NOTES:

This function is called by grav_def() to calculate appropriate gravitational deflections for sources.

REFERENCES:

Murray, C.A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
See also formulae in Section B of the Astronomical Almanac, or
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: place(); grav_def()

References novas_vlen().

Variable Documentation

◆ grav_bodies_full_accuracy

int grav_bodies_full_accuracy = DEFAULT_GRAV_BODIES_FULL_ACCURACY

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.

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

Since: 1.1

◆ grav_bodies_reduced_accuracy

int grav_bodies_reduced_accuracy = DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

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.

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

Since: 1.1

Functions

Variables

Detailed Description

Function Documentation

◆ grav_def()

◆ grav_planets()

◆ grav_redshift()

◆ grav_undef()

◆ grav_undo_planets()

◆ grav_vec()

Variable Documentation

◆ grav_bodies_full_accuracy

◆ grav_bodies_reduced_accuracy