Functions
double	novas_lsr_to_ssb_vel (double epoch, double ra, double dec, double vLSR)

double	novas_ssb_to_lsr_vel (double epoch, double ra, double dec, double vLSR)

double	novas_v2z (double vel)

double	novas_z2v (double z)
	==========================================================================

double	novas_z_add (double z1, double z2)

double	novas_z_inv (double z)

int	rad_vel (const object restrict source, const double restrict pos_src, const double vel_src, const double vel_obs, double d_obs_geo, double d_obs_sun, double d_src_sun, double *restrict rv)

double	rad_vel2 (const object restrict source, const double pos_emit, const double vel_src, const double pos_det, const double *vel_obs, double d_obs_geo, double d_obs_sun, double d_src_sun)

double	redshift_vrad (double vrad, double z)

double	unredshift_vrad (double vrad, double z)

Detailed Description

Date: Created on Mar 5, 2025

Author: Attila Kovacs

Various spectral / velocity related extensions to novas.c

Function Documentation

◆ novas_lsr_to_ssb_vel()

double novas_lsr_to_ssb_vel	(	double	epoch,
		double	ra,
		double	dec,
		double	vLSR
	)

Returns a Solar System Baricentric (SSB) radial velocity for a radial velocity that is referenced to the Local Standard of Rest (LSR). Internally, NOVAS always uses barycentric radial velocities, but it is just as common to have catalogs define radial velocities referenced to the LSR.

The SSB motion w.r.t. the barycenter is assumed to be (11.1, 12.24, 7.25) km/s in ICRS (Shoenrich et al. 2010).

REFERENCES:

Ralph Schoenrich, James Binney, Walter Dehnen, Monthly Notices of the Royal Astronomical Society, Volume 403, Issue 4, April 2010, Pages 1829–1833, https://doi.org/10.1111/j.1365-2966.2010.16253.x

Parameters

epoch	[yr] Coordinate epoch in which the coordinates and velocities are defined. E.g. 2000.0.
ra	[h] Right-ascenscion of source at given epoch.
dec	[deg] Declination of source at given epoch.
vLSR	[km/s] radial velocity defined against the Local Standard of Rest (LSR), at given epoch.

Returns: [km/s] Equivalent Solar-System Barycentric radial velocity.

Since: 1.3

Author: Attila Kovacs

See also: make_cat_entry(); novas_ssb_to_lsr_vel()

References NOVAS_JD_J2000, precession(), and radec2vector().

◆ novas_ssb_to_lsr_vel()

double novas_ssb_to_lsr_vel	(	double	epoch,
		double	ra,
		double	dec,
		double	vLSR
	)

Returns a radial-velocity referenced to the Local Standard of Rest (LSR) for a given Solar-System Barycentric (SSB) radial velocity. Internally, NOVAS always uses barycentric radial velocities, but it is just as common to have catalogs define radial velocities referenced to the LSR.

The SSB motion w.r.t. the barycenter is assumed to be (11.1, 12.24, 7.25) km/s in ICRS (Shoenrich et al. 2010).

REFERENCES:

Ralph Schoenrich, James Binney, Walter Dehnen, Monthly Notices of the Royal Astronomical Society, Volume 403, Issue 4, April 2010, Pages 1829–1833, https://doi.org/10.1111/j.1365-2966.2010.16253.x

Parameters

epoch	[yr] Coordinate epoch in which the coordinates and velocities are defined. E.g. 2000.0.
ra	[h] Right-ascenscion of source at given epoch.
dec	[deg] Declination of source at given epoch.
vLSR	[km/s] radial velocity defined against the Local Standard of Rest (LSR), at given epoch.

Returns: [km/s] Equivalent Solar-System Barycentric radial velocity.

Since: 1.3

Author: Attila Kovacs

See also: make_cat_entry(); novas_lsr_to_ssb_vel()

References NOVAS_JD_J2000, precession(), and radec2vector().

◆ novas_v2z()

double novas_v2z ( double vel )

Converts a radial recession velocity to a redshift value (z = δf / f_rest). It is based on the relativistic formula:

 1 + z = sqrt((1 + β) / (1 - β))

where β = v / c.

Parameters

vel	[km/s] velocity (i.e. rate) of recession.

Returns: the corresponding redshift value (δλ / λ_rest), or NAN if the input velocity is invalid (i.e., it exceeds the speed of light).

See also: novas_z2v(); novas_z_add()

Author: Attila Kovacs

Since: 1.2

References NOVAS_KMS.

◆ novas_z2v()

double novas_z2v ( double z )

==========================================================================

Converts a redshift value (z = δf / f_rest) to a radial velocity (i.e. rate) of recession. It is based on the relativistic formula:

 1 + z = sqrt((1 + β) / (1 - β))

where β = v / c.

Parameters

z	the redshift value (δλ / λ_rest).

Returns: [km/s] Corresponding velocity of recession, or NAN if the input redshift is invalid, i.e. z <= -1).

See also: novas_v2z(); redshift_vrad()

Author: Attila Kovacs

Since: 1.2

References NOVAS_KMS.

◆ novas_z_add()

double novas_z_add	(	double	z1,
		double	z2
	)

Compounds two redshift corrections, e.g. to apply (or undo) a series gravitational redshift corrections and/or corrections for a moving observer. It's effectively using (1 + z) = (1 + z1) * (1 + z2).

Parameters

z1	One of the redshift values
z2	The other redshift value

Returns: The compound redshift value, ot NAN if either input redshift is invalid (errno will be set to EINVAL).

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

Since: 1.2

Author: Attila Kovacs

◆ novas_z_inv()

double novas_z_inv ( double z )

Returns the inverse of a redshift value, that is the redshift for a body moving with the same velocity as the original but in the opposite direction.

Parameters

z	A redhift value

Returns: The redshift value for a body moving in the opposite direction with the same speed, or NAN if the input redshift is invalid.

See also: novas_z_add()

Since: 1.2

Author: Attila Kovacs

◆ rad_vel()

int rad_vel	(	const object *restrict	source,
		const double *restrict	pos_src,
		const double *	vel_src,
		const double *	vel_obs,
		double	d_obs_geo,
		double	d_obs_sun,
		double	d_src_sun,
		double *restrict	rv
	)

Predicts the radial velocity of the observed object as it would be measured by spectroscopic means. Radial velocity is here defined as the radial velocity measure (z) times the speed of light. For major planets (and Sun and Moon), it includes gravitational corrections for light originating at the surface and observed from near Earth or else from a large distance away. For other solar system bodies, it applies to a fictitious emitter at the center of the observed object, assumed massless (no gravitational red shift). The corrections do not in general apply to reflected light. For stars, it includes all effects, such as gravitational redshift, contained in the catalog barycentric radial velocity measure, a scalar derived from spectroscopy. Nearby stars with a known kinematic velocity vector (obtained independently of spectroscopy) can be treated like solar system objects.

Gravitational blueshift corrections for the Solar and Earth potential for observers are included. However, the result does not include a blueshift correction for observers (e.g. spacecraft) orbiting other major Solar-system bodies. You may adjust the amount of gravitational redshift correction applied to the radial velocity via redshift_vrad(), unredshift_vrad() and grav_redshift() if necessary.

All the input arguments are BCRS quantities, expressed with respect to the ICRS axes. 'vel_src' and 'vel_obs' are kinematic velocities - derived from geometry or dynamics, not spectroscopy.

If the object is outside the solar system, the algorithm used will be consistent with the IAU definition of stellar radial velocity, specifically, the barycentric radial velocity measure, which is derived from spectroscopy. In that case, the vector 'vel_src' can be very approximate – or, for distant stars or galaxies, zero – as it will be used only for a small geometric correction that is proportional to proper motion.

Any of the distances (last three input arguments) can be set to zero (0.0) or negative if the corresponding general relativistic gravitational potential term is not to be evaluated. These terms generally are important at the meter/second level only. If 'd_obs_geo' and 'd_obs_sun' are both zero, an average value will be used for the relativistic term for the observer, appropriate for an observer on the surface of the Earth. 'd_src_sun', if given, is used only for solar system objects.

NOTES:

This function does not accont for the gravitational deflection of Solar-system sources. For that purpose, the rad_vel2() function, introduced in v1.1, is more appropriate.
The NOVAS C implementation did not include relatistic corrections for a moving observer if both d_obs_geo and d_obs_sun were zero. As of SuperNOVAS v1.1, the relatistic corrections for a moving observer will be included in the radial velocity measure always.
In a departure from the original NOVAS C, the radial velocity for major planets (and Sun and Moon) includes gravitational redshift corrections for light originating at the surface, assuming it's observed from near Earth or else from a large distance away.

REFERENCES:

Lindegren & Dravins (2003), Astronomy & Astrophysics 401, 1185-1201.
Unlike NOVAS C, this function will return a radial velocity for the Sun that is gravitationally referenced to the Sun's photosphere. (NOVAS C returns the radial velocity for a massless Sun)

Parameters

	source	Celestial object observed
	pos_src	[AU\|*] Geometric position vector of object with respect to observer. For solar system sources it should be corrected for light-time. For non-solar-system objects, the position vector defines a direction only, with arbitrary magnitude.
	vel_src	[AU/day] Velocity vector of object with respect to solar system barycenter.
	vel_obs	[AU/day] Velocity vector of observer with respect to solar system barycenter.
	d_obs_geo	[AU] Distance from observer to geocenter, or <=0.0 if gravitational blueshifting due to Earth potential around observer can be ignored.
	d_obs_sun	[AU] Distance from observer to Sun, or <=0.0 if gravitational bluehifting due to Solar potential around observer can be ignored.
	d_src_sun	[AU] Distance from object to Sun, or <=0.0 if gravitational redshifting due to Solar potential around source can be ignored.
[out]	rv	[km/s] The observed radial velocity measure times the speed of light, or NAN if there was an error.

Returns: 0 if successfule, or else -1 if there was an error (errno will be set to EINVAL if any of the arguments are NULL, or to some other value to indicate the type of error).

See also: rad_vel2()

References rad_vel2().

◆ rad_vel2()

double rad_vel2	(	const object *restrict	source,
		const double *	pos_emit,
		const double *	vel_src,
		const double *	pos_det,
		const double *	vel_obs,
		double	d_obs_geo,
		double	d_obs_sun,
		double	d_src_sun
	)

Predicts the radial velocity of the observed object as it would be measured by spectroscopic means. This is a modified version of the original NOVAS C 3.1 rad_vel(), to account for the different directions in which light is emitted vs in which it detected, e.g. when it is gravitationally deflected.

Radial velocity is here defined as the radial velocity measure (z) times the speed of light. For major planets (and Sun and Moon), it includes gravitational corrections for light originating at the surface and observed from near Earth or else from a large distance away. For other solar system bodies, it applies to a fictitious emitter at the center of the observed object, assumed massless (no gravitational red shift). The corrections do not in general apply to reflected light. For stars, it includes all effects, such as gravitational redshift, contained in the catalog barycentric radial velocity measure, a scalar derived from spectroscopy. Nearby stars with a known kinematic velocity vector (obtained independently of spectroscopy) can be treated like solar system objects.

Gravitational blueshift corrections for the Solar and Earth potential for observers are included. However, the result does not include a blueshift correction for observers (e.g. spacecraft) orbiting other major Solar-system bodies. You may adjust the amount of gravitational redshift correction applied to the radial velocity via redshift_vrad(), unredshift_vrad() and grav_redshift() if necessary.

All the input arguments are BCRS quantities, expressed with respect to the ICRS axes. 'vel_src' and 'vel_obs' are kinematic velocities - derived from geometry or dynamics, not spectroscopy.

If the object is outside the solar system, the algorithm used will be consistent with the IAU definition of stellar radial velocity, specifically, the barycentric radial velocity measure, which is derived from spectroscopy. In that case, the vector 'vel_src' can be very approximate – or, for distant stars or galaxies, zero – as it will be used only for a small geometric and relativistic (time dilation) correction, including the proper motion.

Any of the distances (last three input arguments) can be set to a negative value if the corresponding general relativistic gravitational potential term is not to be evaluated. These terms generally are important only at the meter/second level. If 'd_obs_geo' and 'd_obs_sun' are both zero, an average value will be used for the relativistic term for the observer, appropriate for an observer on the surface of the Earth. 'd_src_sun', if given, is used only for solar system objects.

NOTES:

This function is called by place() and novas_sky_pos() to calculate radial velocities along with the apparent position of the source.
For major planets (and Sun and Moon), the radial velocity includes gravitational redshift corrections for light originating at the surface, assuming it's observed from near Earth or else from a large distance away.

REFERENCES:

Lindegren & Dravins (2003), Astronomy & Astrophysics 401, 1185-1201.

Parameters

source	Celestial object observed
pos_emit	[AU\|*] position vector of object with respect to observer in the direction that light was emitted from the source. For solar system sources it should be corrected for light-time. For non-solar-system objects, the position vector defines a direction only, with arbitrary magnitude.
vel_src	[AU/day] Velocity vector of object with respect to solar system barycenter.
pos_det	[AU\|*] apparent position vector of source, as seen by the observer. It may be the same vector as `pos_emit`, in which case the routine behaves like the original NOVAS_C rad_vel().
vel_obs	[AU/day] Velocity vector of observer with respect to solar system barycenter.
d_obs_geo	[AU] Distance from observer to geocenter, or <=0.0 if gravitational blueshifting due to Earth potential around observer can be ignored.
d_obs_sun	[AU] Distance from observer to Sun, or <=0.0 if gravitational bluehifting due to Solar potential around observer can be ignored.
d_src_sun	[AU] Distance from object to Sun, or <=0.0 if gravitational redshifting due to Solar potential around source can be ignored. Additionally, a value <0 will also skip corrections for light originating at the surface of the observed major solar-system body.

Returns: [km/s] The observed radial velocity measure times the speed of light, or NAN if there was an error (errno will be set to EINVAL if any of the arguments are NULL, or to some other value to indicate the type of error).

See also: rad_vel(); place(); novas_sky_pos(); novas_v2z()

Since: 1.1

Author: Attila Kovacs

References cat_entry::dec, NOVAS_CATALOG_OBJECT, NOVAS_EARTH_RADIUS, NOVAS_EPHEM_OBJECT, NOVAS_KMS, NOVAS_ORBITAL_OBJECT, NOVAS_PLANET, NOVAS_PLANET_GRAV_Z_INIT, NOVAS_PLANETS, NOVAS_SOLAR_RADIUS, novas_vlen(), novas_z2v(), cat_entry::parallax, cat_entry::ra, and cat_entry::radialvelocity.

◆ redshift_vrad()

double redshift_vrad	(	double	vrad,
		double	z
	)

Applies an incremental redshift correction to a radial velocity. For example, you may use this function to correct a radial velocity calculated by rad_vel() or rad_vel2() for a Solar-system body to account for the gravitational redshift for light originating at a specific distance away from the body. For the Sun, you may want to undo the redshift correction applied for the photosphere using unredshift_vrad() first.

Parameters

vrad	[km/s] Radial velocity
z	Redshift correction to apply

Returns: [km/s] The redshift corrected radial velocity or NAN if the redshift value is invalid (errno will be set to EINVAL).

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

Since: 1.2

Author: Attila Kovacs

References novas_v2z(), and novas_z2v().

◆ unredshift_vrad()

double unredshift_vrad	(	double	vrad,
		double	z
	)

Undoes an incremental redshift correction that was applied to radial velocity.

Parameters

vrad	[km/s] Radial velocity
z	Redshift correction to apply

Returns: [km/s] The radial velocity without the redshift correction or NAN if the redshift value is invalid. (errno will be set to EINVAL)

See also: redshift_vrad(); grav_redshift()

Since: 1.2

Author: Attila Kovacs

References novas_v2z(), and novas_z2v().

Functions

Detailed Description

Function Documentation

◆ novas_lsr_to_ssb_vel()

◆ novas_ssb_to_lsr_vel()

◆ novas_v2z()

◆ novas_z2v()

◆ novas_z_add()

◆ novas_z_inv()

◆ rad_vel()

◆ rad_vel2()

◆ redshift_vrad()

◆ unredshift_vrad()