place.c File Reference

Functions
short	app_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
short	app_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
short	astro_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
short	astro_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
short	ephemeris (const double *restrict jd_tdb, const object *restrict body, enum novas_origin origin, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
short	local_planet (double jd_tt, const object *restrict ss_body, double ut1_to_tt, const on_surface *restrict position, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
short	local_star (double jd_tt, double ut1_to_tt, const cat_entry *restrict star, const on_surface *restrict position, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
short	mean_star (double jd_tt, double tra, double tdec, enum novas_accuracy accuracy, double *restrict ira, double *restrict idec)
short	place (double jd_tt, const object *restrict source, const observer *restrict location, double ut1_to_tt, enum novas_reference_system coord_sys, enum novas_accuracy accuracy, sky_pos *restrict output)
int	place_cirs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_gcrs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_icrs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_j2000 (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_mod (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_star (double jd_tt, const cat_entry *restrict star, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system system, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	place_tod (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
int	radec_planet (double jd_tt, const object *restrict ss_body, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system sys, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis, double *restrict rv)
int	radec_star (double jd_tt, const cat_entry *restrict star, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system sys, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict rv)
short	topo_planet (double jd_tt, const object *restrict ss_body, double ut1_to_tt, const on_surface *restrict position, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
short	topo_star (double jd_tt, double ut1_to_tt, const cat_entry *restrict star, const on_surface *restrict position, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
short	virtual_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
short	virtual_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)

Detailed Description

Date

Created on Mar 5, 2025

Author

Attila Kovacs and G. Kaplan

Various convenience variants of the NOVAS C place() function. Using place() or one of its variants is disfavored in SuperNOVAS. Instead, the new frame-based approach is recommended, via novas_sky_pos() (for apparent positions, including aberration and gravitational deflection) or `novas_geom_posvel() (for geometric positions).

Many of the functions here are now deprecated, since the new frame-based approach, introduced in v1.2 offers more versatile and transparent ways of calculated the same quantities.

Nevertheless, if you insist on using these older methods, here's a primer on the differences among the place() variants:

reference system: The coordinate reference system in which the output position is expressed. Often it is ICRS / GCRS, or True of Date (TOD), but occasionally something else.

observer location: If the observer is not one of the call parameters than a fictitious observer located at the geocenter is assumed (e.g. for astro_star(),astro_planet()or place_icrs()`).

position type: The positions calculated can be geometric or apparent. Both include light-time correction (for Solar-system sources), but geometric positions do not correct for the aberration due to observer movement, and gravitational deflections around the major Solar-system bodies. Apparent positions, however, do include such corrections. The contract of the place() function is that if the coord_sys call parameter is NOVAS_ICRS, then it calculates a geometric place, while for all other reference systems it returns an apparent place.

For example, the following place() variants may be used for a geocentric observer place and a sidereal (non-Solar-system) source, depending on the reference system and the type of position to be calculated:

system \ type	geocentric / geometric	geocentric / apparent	topocentric / apparent
ICRS / GCRS	astro_star()	virtual_star()	local_star()
TOD		app_star()	topo_star()

For Solar-system sources you have a matching set of functions but with planet in their name instead of star, e.g. astro_planet() instead of astro_star().

And for geocentric observer locations, the functions below can be used to support further reference systems and can be used with both Solar-system and sidereal sources:

system \ type	geocentric / geometric	geocentric / apparent
ICRS / GCRS	place_icrs()	place_gcrs()
J2000		place_j2000()
MOD		place_mod()
TOD		place_tod()
CIRS		place_cirs()

As you can see it's a little scattered and the nomenclature is not so telling either. Thus, the preferred way is to use a universal recipe and specify the (a) reference system; (b) observer location; and (c) whether to calculate geometric or apparent positions explcitly. Even if it means a few more lines of code. In the new frame based approach this boils down to the following steps:

1. Specify the observer location, (ground-based, airborne, on Earth-orbit, geocentric or heliocentric orbit). See observer for options.
2. Create an observing frame for the type of observer and time of observation using novas_make_frame().
3. Calculate geometric positions using novas_geom_posvel(), or apparent positions using novas_sky_pos(). Set the reference system as one of the call parameters, e.g. NOVAS_ICRS for ICRS, NOVAS_TOD for TOD etc.
4. If needed convert between position 3-vectors and RA/Dec coordinates using vector2radec() / radec2vector() as necessary.

See also

frames.c

Function Documentation

app_planet()

short app_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis )

reference_system: TOD
observer location: geocenter
position_type: apparent

Computes the True-of-Date (TOD) apparent place of a solar system body as would be seen by an observer at the geocenter. This is the same as calling place() for the body with NOVAS_TOD as the system and a geocentric observer, except the different set of return values used.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Apparent (TOD) right ascension for a fictitous geocentric observer, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)
[out]	dec	[deg] Apparent (TOD) declination for a fictitous geocentric observer, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)
[out]	dis	[AU] Apparent distance from Earth to the body at 'jd_tt' (it may be NULL if not needed).

Returns

0 if successful, or -1 if the object argument is NULL, or else 1 if the value of 'type' in structure 'ss_body' is invalid, or 10 + the error from place().

See also

place_tod(), astro_planet(), local_planet(), topo_planet(), virtual_planet(), app_star()

novas_sky_pos(), make_observer_at_geocenter(), NOVAS_TOD

References NOVAS_TOD, and radec_planet().

app_star()

short app_star	(	double	jd_tt,
		const cat_entry *restrict	star,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec )

reference_system: TOD
observer location: geocenter
position_type: apparent

Computes the True-of-Date (TOD) apparent place of a star, as would be seen by an observer at the geocenter, referenced to the dynamical equator of date, given its catalog mean place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with a NULL observer location and NOVAS_TOD as the system for an object that specifies the star.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Apparent (TOD) right ascension for a fictitous geocentric observer, referred to true equator and equinox of date 'jd_tt' (it may be NULL if not required).
[out]	dec	[deg] Apparent (TOD) declination in degrees for a fictitous geocentric observer, referred to true equator and equinox of date 'jd_tt' (it may be NULL if not required).

Returns

0 if successful, -1 if a required pointer argument is NULL, or else an the error from make_object(), or 20 + the error from place().

See also

place_tod(), novas_sky_pos(), place_star(), astro_star(), local_star(), topo_star(), virtual_star(), app_planet()

novas_sky_pos(), make_observer_at_geocenter(), NOVAS_TOD

References NOVAS_TOD, and radec_star().

astro_planet()

short astro_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis )

reference_system: ICRS / GCRS
observer location: geocenter
position_type: geometric

Computes the astrometric place of a solar system body, as would be seen by a non-moving observer located at the current position of the geocenter, referenced to the ICRS without light deflection or aberration. This is the same as calling place_icrs() for the body, except the different set of return values used.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Astrometric (geometric) right ascension for a fictitous geocentric observer, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dec	[deg] Astrometric (geometric) declination, for a fictitous geocentric observer, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dis	[AU] Apparent distance from Earth to the body at 'jd_tt' (it may be NULL if not needed).

Returns

0 if successful, or -1 if the object is NULL, or else 1 if the value of 'type' in structure 'ss_body' is invalid, or 10 + the error from place().

See also

place_icrs(), app_planet(), local_planet(), topo_planet(), virtual_planet(), astro_star()

novas_geom_posvel(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_ICRS, and radec_planet().

astro_star()

short astro_star	(	double	jd_tt,
		const cat_entry *restrict	star,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec )

reference_system: ICRS / GCRS
observer location: geocenter
position_type: geometric

Computes the astrometric place of a star, as would be seen by a non-moving observer at the current location of the geocenter, referred to the ICRS without light deflection or aberration, at date 'jd_tt', given its catalog mean place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with a NULL observer location and NOVAS_ICRS as the system, or place_icrs() for an object that specifies the star.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Astrometric (geometric) right ascension for a fictitous geocentric observer, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dec	[deg] Astrometric (geometric) declination for a fictitous geocentric observer, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)

Returns

0 if successful, or -1 if a required pointer argument is NULL, or 20 + the error from place().

See also

place_star(), place_icrs(), app_star(), local_star(), topo_star(), virtual_star(), astro_planet()

novas_geom_posvel(), make_observer_at_geocenter(), NOVAS_ICRS

References NOVAS_ICRS, and radec_star().

ephemeris()

short ephemeris	(	const double *restrict	jd_tdb,
		const object *restrict	body,
		enum novas_origin	origin,
		enum novas_accuracy	accuracy,
		double *restrict	pos,
		double *restrict	vel )

Retrieves the position and velocity of a solar system body from a fundamental ephemeris.

It is recommended that the input structure 'cel_obj' be created using make_object()

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	body	Pointer to structure containing the designation of the body of interest
	origin	NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1)
	accuracy	NOCAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	[AU] Pointer to structure containing the designation of the body of interest
[out]	vel	[AU/day] Velocity vector of the body at 'jd_tdb'; equatorial rectangular coordinates in AU/day referred to the ICRS.

Returns

0 if successful, -1 if the 'jd_tdb' or input object argument is NULL, or else 1 if 'origin' is invalid, 2 if cel_obj->type is invalid, 10 + the error code from solarsystem(), or 20 + the error code from readeph().

See also

set_planet_provider(), set_planet_provider_hp(), set_ephem_provider()

make_planet(), make_ephem_object()

References ephemeris(), get_ephem_provider(), make_planet(), NOVAS_BARYCENTER, NOVAS_EPHEM_OBJECT, NOVAS_FULL_ACCURACY, NOVAS_HELIOCENTER, novas_orbit_posvel(), NOVAS_ORBITAL_OBJECT, NOVAS_ORIGIN_TYPES, NOVAS_PLANET, NOVAS_SSB, NOVAS_SUN, and readeph().

local_planet()

short local_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		double	ut1_to_tt,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis )

Deprecated

Using the frame-based novas_sky_pos() with NOVAS_ICRS or NOVARS_GCRS as the reference system is now preferred for the equivalent calculations.

reference_system: ICRS/GCRS
observer location: topocentric (on Earth)
position_type: apparent

Computes the local apparent place of a solar system body, in the GCRS. This is the same as calling place() for the body for the same observer location and NOVAS_GCRS as the reference system, except the different set of return values used.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Local apparent right ascension, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Local apparent right ascension, referred to the GCRS (it may be NULL if not required).
[out]	dis	[AU] Apparent distance from Earth to the body at 'jd_tt' (it may be NULL if not required).

Returns

0 if successful, or -1 if the object argument is NULL, or else 1 if the value of 'where' in structure 'location' is invalid, or 10 + the error code from place().

See also

astro_planet(), topo_planet(), virtual_planet(), app_star()

novas_sky_pos(), make_observer_at_site(), NOVAS_GCRS, get_ut1_to_tt()

References make_observer_at_site(), NOVAS_GCRS, and radec_planet().

local_star()

short local_star	(	double	jd_tt,
		double	ut1_to_tt,
		const cat_entry *restrict	star,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec )

Deprecated

Using the frame-based novas_sky_pos() with NOVAS_ICRS or NOVARS_GCRS as the reference system is now preferred for the equivalent calculations.

reference_system: ICRS / GCRS
observer location: topocentric (on Earth)
position_type: apparent

Computes the local apparent place of a star at date 'jd_tt', in the GCRS, given its catalog mean place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with the same observer location NOVAS_GCRS for an object that specifies the star.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Local apparent right ascension, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Local apparent right ascension, referred to the GCRS (it may be NULL if not required).

Returns

0 if successful, or -1 if any of the required pointer arguments is NULL, or else 20 + the error from place().

See also

place_star(), app_star(), astro_star(), topo_star(), virtual_star(), astro_planet()

novas_sky_pos(), make_observer_at_site(), NOVAS_GCRS, get_ut1_to_tt()

References make_observer_at_site(), NOVAS_GCRS, and radec_star().

mean_star()

short mean_star	(	double	jd_tt,
		double	tra,
		double	tdec,
		enum novas_accuracy	accuracy,
		double *restrict	ira,
		double *restrict	idec )

reference system: TOD → ICRS
__observer location: geocenter → SSB
position_type: apparent → geometric

Computes the barycentric ICRS position of a star, given its True of Date (TOD) apparent place, as seen by an observer at the geocenter, at date 'jd_tt'. Proper motion, parallax and radial velocity are assumed to be zero.

Equivalently, in the new frame-based approach, you might use novas_app_to_geom() with NOVAS_TOD as the reference system, and distance set to 0, and then convert the geometric position to the output ira, idec coordinates using vector2radec(). The advantage of using novas_app_to_geom() is that you are not restricted to using TOD input coordinates, but rather the apparent RA/Dec may be specified in any reference system.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
[in]	tra	[h] Geocentric apparent (TOD) right ascension, referred to true equator and equinox of date.
[in]	tdec	[deg] Geocentric apparent (TOD) declination, referred to true equator and equinox of date.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ira	[h] Barycentric geometric ICRS right ascension, or NAN if returning with an error code. It may be a pointer to the input value.
[out]	idec	[deg] Barycentric geometric ICRS declination, or NAN if returning with an error code. It may be a pointer to the input value.

Returns

0 if successful; -1 if the supplied output pointers are NULL, 1 if the iterative process did not converge after 30 iterations, or an error from vector2radec(), or else > 10 + an error from app_star().

See also

novas_app_to_geom(), NOVAS_TOD, make_observer_at_geocenter(), vector2radec()

References app_star(), CAT_ENTRY_INIT, cat_entry::dec, novas_inv_max_iter, precession(), cat_entry::ra, starvectors(), and vector2radec().

place()

short place	(	double	jd_tt,
		const object *restrict	source,
		const observer *restrict	location,
		double	ut1_to_tt,
		enum novas_reference_system	coord_sys,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	output )

Computes the apparent direction of a celestial object at a specified time and in a specified coordinate system and for a given observer location.

While coord_sys defines the coordinate referfence system, it is location->where sets the origin of the reference place relative to which positions and velocities are reported.

For all but ICRS coordinate outputs, the calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

In case of a dynamical equatorial system (such as CIRS or TOD) and an Earth-based observer, the polar wobble parameters set via a prior call to cel_pole() together with he ut1_to_tt argument decide whether the resulting 'topocentric' output frame is Pseudo Earth Fixed (PEF; if cel_pole() was not set and DUT1 is 0) or ITRS (actual rotating Earth; if cel_pole() was set and ut1_to_tt includes the DUT1 component).

NOTES:

1. This version fixes a NOVAS C 3.1 issue that velocities and solar-system distances were not antedated for light-travel time.
2. 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.
3. As of SuperNOVAS v1.3, the returned radial velocity component is a proper observer-based spectroscopic measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with pseudo LSR-based measures being returned for catalog sources.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Klioner, S. (2003), Astronomical Journal 125, 1580-1597.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	source	Pointer to a celestrial object data structure. Catalog objects musy have ICRS coordinates. You can use transform_cat() to convert other catalog systems to ICRS as necessary.
	location	The observer location, relative to which the output positions and velocities are to be calculated
	ut1_to_tt	[s] TT - UT1 time difference. Used only when 'location->where' is NOVAS_OBSERVER_ON_EARTH (1) or NOVAS_OBSERVER_IN_EARTH_ORBIT (2).
	coord_sys	The coordinate system that defines the orientation of the celestial pole. If it is NOVAS_ICRS (3), a geometric position and radial velocity is returned. For all other systems, the returned position is the apparent position including aberration and gravitational deflection corrections, and the radial velocity is in the direction the eflected light was emitted from the source.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	output	Data structure to populate with the result.

Returns

0 if successful,
1 if 'coord_sys' is invalid,
2 if 'accuracy' is invalid,
3 if the observer is at or very near (within ~1.5m of) the observed location,
10–40: error is 10 + the error ephemeris(),
40–50: error is 40 + the error from geo_posvel(),
50–70: error is 50 + error from light_time2(),
70–80: error is 70 + error from grav_def(),
80–90: error is 80 + error from cio_location(),
90–100: error is 90 + error from cio_basis().

See also

place_star(), place_icrs(), place_gcrs(), place_cirs(), radec_star(), radec_planet()

novas_sky_pos(), novas_geom_posvel(), get_ut1_to_tt()

References aberration(), bary2obs(), d_light(), ephemeris(), era(), gcrs_to_cirs(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_planets(), light_time2(), make_observer_at_geocenter(), NOVAS_BARYCENTER, NOVAS_CATALOG_OBJECT, NOVAS_CIRS, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_TIRS, NOVAS_TOD, novas_vlen(), obs_planets(), obs_posvel(), proper_motion(), rad_vel2(), spin(), starvectors(), tt2tdb(), and vector2radec().

place_cirs()

int place_cirs	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: CIRS
observer location: geocenter
position_type: apparent

Computes the Celestial Intermediate Reference System (CIRS) dynamical position position of a source as 'seen' from the geocenter at the given time of observation. See place() for more information.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent CIRS position data for a fictitous geocentric observer.

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.0

Author

Attila Kovacs

See also

place_tod(), place_gcrs()

novas_sky_pos(), NOVAS_CIRS, make_observer_at_geocenter()

References NOVAS_CIRS, and place().

place_gcrs()

int place_gcrs	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: ICRS/GCRS
observer location: geocenter
position_type: apparent

Computes the Geocentric Celestial Reference System (GCRS) position of a source (as 'seen' from the geocenter) at the given time of observation. Unlike place_icrs(), this includes aberration for the moving frame of the geocenter as well as gravitational deflections calculated for a virtual observer located at the geocenter. See place() for more information.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent GCRS position data for a fictitous geocentric observer.

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.0

Author

Attila Kovacs

See also

place_icrs(), place_cirs(), place_tod(), virtual_star(), virtual_planet()

novas_sky_pos(), NOVAS_GCRS, make_observer_at_geocenter(),

References NOVAS_GCRS, and place().

place_icrs()

int place_icrs	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: ICRS / GCRS
observer location: geocenter
position_type: geometric

Computes the International Celestial Reference System (ICRS) position of a source. (from the geocenter). Unlike place_gcrs(), this version does not include aberration or gravitational deflection corrections.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated geometric ICRS position data for a fictitous geocentric observer. (Unlike place_gcrs(), the calculated coordinates do not account for aberration or gravitational deflection).

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.0

Author

Attila Kovacs

See also

place_gcrs(), place_cirs(), place_tod(), mean_star()

novas_geom_posvel(), NOVAS_GCRS, make_observer_at_geocenter()

References NOVAS_ICRS, and place().

place_j2000()

int place_j2000	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: J2000
observer location: geocenter
position_type: apparent

Computes the J2000 dynamical position position of a source as 'seen' from the geocenter at the given time of observation. See place() for more information.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent J2000 position data for a fictitous geocentric observer.

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.1

Author

Attila Kovacs

See also

place_cirs(), place_gcrs(), app_star(), app_planet()

novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_J2000, and place().

place_mod()

int place_mod	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: MOD
observer location: geocenter
position_type: apparent

Computes the Mean of Date (MOD) dynamical position position of a source as 'seen' from the geocenter at the given time of observation. See place() for more information.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent Mean-of-Date (MOD) position data for a fictitous geocentric observer.

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.1

Author

Attila Kovacs

See also

place_cirs(), place_gcrs(), app_star(), app_planet()

novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_MOD, and place().

place_star()

int place_star	(	double	jd_tt,
		const cat_entry *restrict	star,
		const observer *restrict	obs,
		double	ut1_to_tt,
		enum novas_reference_system	system,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

Computes the apparent place of a star at the specified date, given its catalog mean place, proper motion, parallax, and radial velocity. See place() for more information.

It is effectively the same as calling place(), except for the cat_entry type target argument.

For all but ICRS coordinate outputs, the calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	obs	Observer location (NULL defaults to geocentric)
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	system	The type of coordinate reference system in which coordinates are to be returned.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	The position and radial velocity of of the catalog source in the specified coordinate system and relative to the specified observer location (if applicable)

Returns

0 if successful, or -1 if one of the required arguments is NULL, or else 1 if the observer location is invalid, or an error code from place().

Author

Attila Kovacs

Since

1.0

See also

novas_sky_pos(), novas_geom_posvel(), get_ut1_to_tt()

References NOVAS_CATALOG_OBJECT, place(), object::star, and object::type.

place_tod()

int place_tod	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos )

reference_system: TOD
observer location: geocenter
position_type: apparent

Computes the True of Date (TOD) dynamical position position of a source as 'seen' from the geocenter at the given time of observation. See place() for more information.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent True-of-Date (TOD) position data for a fictitous geocentric observer.

Returns

0 if successful, or -1 if any of the input pointer arguments is NULL, or else an error from place().

Since

1.0

Author

Attila Kovacs

See also

place_cirs(), place_gcrs(), app_star(), app_planet()

novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_TOD, and place().

radec_planet()

int radec_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		const observer *restrict	obs,
		double	ut1_to_tt,
		enum novas_reference_system	sys,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis,
		double *restrict	rv )

Computes the place of a solar system body at the specified time for an observer in the specified coordinate system. This is the same as calling place() with the same arguments, except the different set of return values used.

Notwithstanding the different set of return values, this is the same as calling place_planet() with the same arguments.

For all but ICRS coordinate outputs, the calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	obs	Observer location. It may be NULL if not relevant.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	sys	Coordinate reference system in which to produce output values
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Topocentric apparent right ascension in hours, referred to the true equator and equinox of date, or NAN when returning with an error code. (It may be NULL if not required)
[out]	dec	[deg] Topocentric apparent declination in degrees referred to the true equator and equinox of date, or NAN when returning with an error code. (It may be NULL if not required)
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU, or NAN when returning with an error code. (It may be NULL if not needed).
[out]	rv	[AU/day] radial velocity relative ot observer, or NAN when returning with an error code. (It may be NULL if not required)

Returns

0 if successful, or -1 if the object argument is NULL or if the value of 'where' in structure 'location' is invalid, or 10 + the error code from place().

Since

1.0

Author

Attila Kovacs

See also

radec_star()

novas_sky_pos(), novas_geom_posvel()

References sky_pos::dec, sky_pos::dis, NOVAS_EPHEM_OBJECT, NOVAS_ORBITAL_OBJECT, NOVAS_PLANET, place(), sky_pos::ra, sky_pos::rv, and SKY_POS_INIT.

radec_star()

int radec_star	(	double	jd_tt,
		const cat_entry *restrict	star,
		const observer *restrict	obs,
		double	ut1_to_tt,
		enum novas_reference_system	sys,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	rv )

Computes the place of a star at date 'jd_tt', for an observer in the specified coordinate system, given the star's ICRS catalog place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with the same arguments.

For all but ICRS coordinate outputs, the calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	obs	Observer location. It may be NULL if not relevant.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	sys	Coordinate reference system in which to produce output values
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Topocentric right ascension in hours, referred to true equator and equinox of date 'jd_tt' or NAN when returning with an error code. (It may be NULL if not required)
[out]	dec	[deg] Topocentric declination in degrees, referred to true equator and equinox of date 'jd_tt' or NAN when returning with an error code. (It may be NULL if not required)
[out]	rv	[AU/day] radial velocity relative ot observer, or NAN when returning with an error code. (It may be NULL if not required)

Returns

0 if successful, -1 if a required pointer argument is NULL, or else 20 + the error from place_star().

Since

1.0

Author

Attila Kovacs

See also

radec_planet()

novas_sky_pos(), novas_geom_posvel()

References sky_pos::dec, place_star(), sky_pos::ra, sky_pos::rv, and SKY_POS_INIT.

topo_planet()

short topo_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		double	ut1_to_tt,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis )

Deprecated

Using the frame-based novas_sky_pos() with NOVAS_TOD as the reference system is now preferred for topocentric calculations.

reference_system: TOD
observer location: topocentric (on Earth)
position_type: apparent

Computes the topocentric apparent place of a solar system body at the specified time. This is the same as calling place() for the body for the same observer location and NOVAS_TOD as the reference system, except the different set of return values used.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Topocentric apparent right ascension, referred to the true equator and equinox of date. (It may be NULL if not required)
[out]	dec	[deg] Topocentric apparent declination, referred to the true equator and equinox of date. (It may be NULL if not required)
[out]	dis	[AU] Apparent distance from Earth to the body at 'jd_tt' (may be NULL if not needed).

Returns

0 if successful, or -1 if the object argument is NULL, or else 1 if the value of 'where' in structure 'location' is invalid, or 10 + the error from place().

See also

app_planet(), local_planet(), topo_planet(), virtual_planet(), astro_star()

novas_sky_pos(), make_observer_at_site(), NOVAS_TOD, get_ut1_to_tt()

References make_observer_at_site(), NOVAS_TOD, and radec_planet().

topo_star()

short topo_star	(	double	jd_tt,
		double	ut1_to_tt,
		const cat_entry *restrict	star,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec )

Deprecated

Using the frame-based novas_sky_pos() with NOVAS_TOD as the reference system is now preferred for topocentric calculations.

reference_system: TOD
observer location: topocentric (on Earth)
position_type: apparent

Computes the topocentric (True of Date; TOD) apparent place of a star at date 'jd_tt', given its ICRS catalog place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with the same observer location and NOVAS_TOD for an object that specifies the star.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Topocentric appatent right ascension, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)
[out]	dec	[deg] Topocentric apparent declination, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)

Returns

0 if successful, -1 if a required pointer argument is NULL, or else 20 + the error from place_star().

See also

place_star(), app_star(), local_star(), topo_star(), virtual_star(), astro_planet()

novas_sky_pos(), make_observer_at_site(), NOVAS_TOD, get_ut1_to_tt()

References make_observer_at_site(), NOVAS_TOD, and radec_star().

virtual_planet()

short virtual_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis )

reference_system: ICRS / GCRS
observer location: geocenter
position_type: apparent

Computes the virtual place of a solar system body, as would be seen by an observer at the geocenter, referenced to the GCRS. This is the same as calling place_gcrs() for the body, except the different set of return values used.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992),Chapter 3.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Virtual apparent right ascension for a fictitous geocentric observer, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Virtual apparent declination, for a fictitous geocentric observer, referred to the GCRS (it may be NULL if not required).
[out]	dis	[AU] Apparent distance from Earth to the body at 'jd_tt' (it may be NULL if not needed).

Returns

0 if successful, or -1 if the object argument is NULL, or else 1 if the value of 'type' in structure 'ss_body' is invalid, or 10 + the error from place().

See also

place_gcrs(), app_planet(), astro_planet(), local_planet(), topo_planet(), app_star()

novas_sky_pos(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_GCRS, and radec_planet().

virtual_star()

short virtual_star	(	double	jd_tt,
		const cat_entry *restrict	star,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec )

reference_system: ICRS / GCRS
observer location: geocenter
position_type: apparent

Computes the virtual place of a star, as would be seen by an observer at the geocenter, referenced to GCRS, at date 'jd_tt', given its catalog mean place, proper motion, parallax, and radial velocity.

Notwithstanding the different set of return values, this is the same as calling place_star() with a NULL observer location and NOVAS_GCRS as the system, or place_gcrs() for an object that specifies the star.

The calculated positions and velocities include aberration corrections for the moving frame of the observer as well as gravitational deflection due to the Sun and Earth and other major gravitating bodies in the Solar system, provided planet positions are available via a novas_planet_provider function.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Explanatory Supplement to the Astronomical Almanac (1992), Chapter 3.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Virtual apparent right ascension for a fictitous geocentric observer, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Virtual apparent declination for a fictitous geocentric observer, referred to the GCRS (it may be NULL if not required).

Returns

0 if successful, or -1 if a required pointer argument is NULL, or 20 + the error from place().

See also

place_star(), place_gcrs(), app_star(), astro_star(), local_star(), topo_star(), virtual_planet()

novas_sky_pos(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_GCRS, and radec_star().