Macros
#define	_DEFAULT_SOURCE
	strcasecmp() feature macro starting glibc 2.20 (2014-09-08)

Functions
short	make_cat_entry (const char restrict star_name, const char restrict catalog, long cat_num, double ra, double dec, double pm_ra, double pm_dec, double parallax, double rad_vel, cat_entry *star)

int	make_cat_object (const cat_entry star, object source)

int	make_cat_object_sys (const cat_entry star, const char restrict system, object *source)

int	make_ephem_object (const char name, long num, object body)

short	make_object (enum novas_object_type type, long number, const char name, const cat_entry star, object *source)

int	make_orbital_object (const char name, long num, const novas_orbital orbit, object *body)

int	make_planet (enum novas_planet num, object *restrict planet)

int	make_redshifted_cat_entry (const char name, double ra, double dec, double z, cat_entry source)

int	make_redshifted_object (const char name, double ra, double dec, double z, object source)

int	make_redshifted_object_sys (const char name, double ra, double dec, const char restrict system, double z, object *source)

void	novas_case_sensitive (int value)

double	novas_helio_dist (double jd_tdb, const object restrict source, double restrict rate)

enum novas_planet	novas_planet_for_name (const char *restrict name)

double	novas_solar_power (double jd_tdb, const object *restrict source)

int	proper_motion (double jd_tdb_in, const double pos, const double restrict vel, double jd_tdb_out, double *out)

int	starvectors (const cat_entry restrict star, double restrict pos, double *restrict motion)

short	transform_cat (enum novas_transform_type option, double jd_tt_in, const cat_entry in, double jd_tt_out, const char out_id, cat_entry *out)

int	transform_hip (const cat_entry hipparcos, cat_entry hip_2000)

Detailed Description

Date: Created on Mar 6, 2025

Author: G. Kaplan and Attila Kovacs

Functions that define an observing target.

Function Documentation

◆ make_cat_entry()

short make_cat_entry	(	const char *restrict	star_name,
		const char *restrict	catalog,
		long	cat_num,
		double	ra,
		double	dec,
		double	pm_ra,
		double	pm_dec,
		double	parallax,
		double	rad_vel,
		cat_entry *	star
	)

Populates the data structure for a 'catalog' source, such as a star.

Parameters

	star_name	Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL if not relevant.
	catalog	Catalog identifier (less than SIZE_OF_CAT_NAME in length). E.g. 'HIP' = Hipparcos, 'TY2' = Tycho-2. It may be NULL if not relevant.
	cat_num	Object number in the catalog.
	ra	[h] Right ascension of the object (hours).
	dec	[deg] Declination of the object (degrees).
	pm_ra	[mas/yr] Proper motion in right ascension (milliarcseconds/year).
	pm_dec	[mas/yr] Proper motion in declination (milliarcseconds/year).
	parallax	[mas] Parallax (milliarcseconds).
	rad_vel	[km/s] Radial velocity relative to the Solar-System Barycenter (SSB) To convert velocities defined against the Local Standard of Rest (LSR), you may use `novas_lsr_to_ssb_vel()` to convert appropriately.
[out]	star	Pointer to data structure to populate.

Returns: 0 if successful, or -1 if the output argument is NULL, 1 if the 'star_name' is too long or 2 if the 'catalog' name is too long.

See also: novas_lsr_to_ssb_vel(); make_redshifted_cat_entry(); make_cat_object_sys(); transform_cat()

References cat_entry::catalog, cat_entry::dec, cat_entry::parallax, cat_entry::promodec, cat_entry::promora, cat_entry::ra, rad_vel(), cat_entry::radialvelocity, SIZE_OF_CAT_NAME, SIZE_OF_OBJ_NAME, cat_entry::starname, and cat_entry::starnumber.

◆ make_cat_object()

int make_cat_object	(	const cat_entry *	star,
		object *	source
	)

Populates and object data structure with the data for a catalog source. The input source must be defined with ICRS coordinates. To create objects with other types of coordiantes use make_cat_object_epoch() instead.

Parameters

	star	Pointer to structure to populate with the catalog data for a celestial object located outside the solar system, specified with ICRS coordinates.
[out]	source	Pointer to the celestial object data structure to be populated.

Returns: 0 if successful, or -1 if either argument is NULL, or else 5 if 'name' is too long.

See also: make_cat_object_sys(); make_cat_entry(); make_planet(); make_ephem_object(); novas_geom_posvel(); place()

Since: 1.1

Author: Attila Kovacs

References make_object(), NOVAS_CATALOG_OBJECT, cat_entry::starname, and cat_entry::starnumber.

◆ make_cat_object_sys()

int make_cat_object_sys	(	const cat_entry *	star,
		const char *restrict	system,
		object *	source
	)

Populates and object data structure with the data for a catalog source for a given system of catalog coordinates.

Parameters

	star	Pointer to structure to populate with the catalog data for a celestial object located outside the solar system.
	system	Input catalog coordinate system epoch, e.g. "ICRS", "B1950.0", "J2000.0", "FK4", "FK5", or "HIP". In general, any Besselian or Julian year epoch can be used by year (e.g. "B1933.193" or "J2022.033"), or else the fixed value listed. If 'B' or 'J' is ommitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0.
[out]	source	Pointer to the celestial object data structure to be populated with the corresponding ICRS catalog coordinates, after appying proper-motion and precession corrections as appropriate.

Returns: 0 if successful, or -1 if any argument is NULL or if the input 'system' is invalid, or else 5 if 'name' is too long.

See also: make_cat_object(); make_redshifted_object_sys(); novas_jd_for_epoch(); make_cat_entry(); place(); NOVAS_SYSTEM_ICRS; NOVAS_SYSTEM_HIP; NOVAS_SYSTEM_J2000; NOVAS_SYSTEM_B1950

Since: 1.3

Author: Attila Kovacs

References make_cat_object(), and object::star.

◆ make_ephem_object()

int make_ephem_object	(	const char *	name,
		long	num,
		object *	body
	)

Sets a celestial object to be a Solar-system ephemeris body. Typically this would be used to define minor planets, asteroids, comets and planetary satellites.

Parameters

	name	Name of object. By default converted to upper-case, unless novas_case_sensitive() was called with a non-zero argument. Max. SIZE_OF_OBJ_NAME long, including termination. If the ephemeris provider uses names, then the name should match those of the ephemeris provider – otherwise it is not important.
	num	Solar-system body ID number (e.g. NAIF). The number should match the needs of the ephemeris provider used with NOVAS. (If the ephemeris provider is by name and not ID number, then the number here is not important).
[out]	body	Pointer to structure to populate.

Returns: 0 if successful, or else -1 if the 'body' pointer is NULL or the name is too long.

See also: set_ephem_provider(); make_planet(); make_cat_entry(); novas_geom_posvel(); place()

Since: 1.0

Author: Attila Kovacs

References make_object(), and NOVAS_EPHEM_OBJECT.

◆ make_object()

short make_object	(	enum novas_object_type	type,
		long	number,
		const char *	name,
		const cat_entry *	star,
		object *	source
	)

Populates an object data structure using the parameters provided. By default (for compatibility with NOVAS C) source names are converted to upper-case internally. You can however enable case-sensitive processing by calling novas_case_sensitive() before.

NOTES:

This call does not initialize the orbit field (added in v1.2) with zeroes to remain ABI compatible with versions <1.2, and to avoid the possiblity of segfaulting if used to initialize a legacy object variable.

Parameters

	type	The type of object. NOVAS_PLANET (0), NOVAS_EPHEM_OBJECT (1) or NOVAS_CATALOG_OBJECT (2), or NOVAS_ORBITAL_OBJECT (3).
	number	The novas ID number (for solar-system bodies only, otherwise ignored)
	name	The name of the object (case insensitive). It should be shorter than SIZE_OF_OBJ_NAME or else an error will be returned. The name is converted to upper internally unless novas_case_sensitive() was called before to change that.
	star	Pointer to structure to populate with the catalog data for a celestial object located outside the solar system. Used only if type is NOVAS_CATALOG_OBJECT, otherwise ignored and can be NULL.
[out]	source	Pointer to the celestial object data structure to be populated.

Returns: 0 if successful, or -1 if 'cel_obj' is NULL or when type is NOVAS_CATALOG_OBJECT and 'star' is NULL, or else 1 if 'type' is invalid, 2 if 'number' is out of legal range or 5 if 'name' is too long.

See also: novas_case_sensitive(); make_cat_object(); make_redshifted_object(); make_planet(); make_ephem_object(); make_orbital_object(); novas_geom_posvel(); place()

References object::name, NOVAS_CATALOG_OBJECT, NOVAS_OBJECT_TYPES, NOVAS_ORBITAL_OBJECT, NOVAS_PLANET, NOVAS_PLANETS, object::number, object::star, and object::type.

◆ make_orbital_object()

int make_orbital_object	(	const char *	name,
		long	num,
		const novas_orbital *	orbit,
		object *	body
	)

Sets a celestial object to be a Solar-system orbital body. Typically this would be used to define minor planets, asteroids, comets, or even planetary satellites.

Parameters

	name	Name of object. It may be NULL if not relevant.
	num	Solar-system body ID number (e.g. NAIF). It is not required and can be set e.g. to -1 if not relevant to the caller.
	orbit	The orbital parameters to adopt. The data will be copied, not referenced.
[out]	body	Pointer to structure to populate.

Returns: 0 if successful, or else -1 if the 'orbit' or 'body' pointer is NULL or the name is too long.

See also: novas_orbit_posvel(); make_planet(); make_ephem_object(); novas_geom_posvel(); place()

Since: 1.2

Author: Attila Kovacs

References make_object(), NOVAS_ORBITAL_OBJECT, and object::orbit.

◆ make_planet()

int make_planet	(	enum novas_planet	num,
		object *restrict	planet
	)

Sets a celestial object to be a major planet, or the Sun, Moon, Solar-system Barycenter, etc.

Parameters

	num	Planet ID number (NOVAS convention)
[out]	planet	Pointer to structure to populate.

Returns: 0 if successful, or else -1 if the 'planet' pointer is NULL.

See also: make_ephem_object(); make_cat_entry(); place()

Since: 1.0

Author: Attila Kovacs

References make_object(), NOVAS_PLANET, NOVAS_PLANET_NAMES_INIT, and NOVAS_PLANETS.

◆ make_redshifted_cat_entry()

int make_redshifted_cat_entry	(	const char *	name,
		double	ra,
		double	dec,
		double	z,
		cat_entry *	source
	)

Populates a celestial object data structure with the parameters for a redhifted catalog source, such as a distant quasar or galaxy. It is similar to make_cat_object() except that it takes a Doppler-shift (z) instead of radial velocity and it assumes no parallax and no proper motion (appropriately for a distant redshifted source). The catalog name is set to EXT to indicate an extragalactic source, and the catalog number defaults to 0. The user may change these default field values as appropriate afterwards, if necessary.

Parameters

	name	Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL.
	ra	[h] Right ascension of the object (hours).
	dec	[deg] Declination of the object (degrees).
	z	Redhift value (λ_obs / λ_rest - 1 = f_rest / f_obs - 1).
[out]	source	Pointer to structure to populate.

Returns: 0 if successful, or 5 if 'name' is too long, else -1 if the 'source' pointer is NULL.

See also: make_redshifted_object_sys(); novas_v2z()

Since: 1.2

Author: Attila Kovacs

References make_cat_entry(), and novas_z2v().

◆ make_redshifted_object()

int make_redshifted_object	(	const char *	name,
		double	ra,
		double	dec,
		double	z,
		object *	source
	)

Populates a celestial object data structure with the parameters for a redhifted catalog source, such as a distant quasar or galaxy. It is similar to make_cat_object() except that it takes a Doppler-shift (z) instead of radial velocity and it assumes no parallax and no proper motion (appropriately for a distant redshifted source). The catalog name is set to EXT to indicate an extragalactic source, and the catalog number defaults to 0. The user may change these default field values as appropriate afterwards, if necessary.

Parameters

	name	Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL.
	ra	[h] ICRS Right ascension of the object (hours).
	dec	[deg] ICRS Declination of the object (degrees).
	z	Redhift value (λ_obs / λ_rest - 1 = f_rest / f_obs - 1).
[out]	source	Pointer to structure to populate.

Returns: 0 if successful, or 5 if 'name' is too long, else -1 if the 'source' pointer is NULL.

See also: make_redshifted_object_sys(); make_cat_object(); novas_v2z()

Since: 1.2

Author: Attila Kovacs

References make_cat_object(), and make_redshifted_cat_entry().

◆ make_redshifted_object_sys()

int make_redshifted_object_sys	(	const char *	name,
		double	ra,
		double	dec,
		const char *restrict	system,
		double	z,
		object *	source
	)

Populates a celestial object data structure with the parameters for a redhifted catalog source, such as a distant quasar or galaxy, for a given system of catalog coordinates.

Parameters

	name	Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL.
	ra	[h] ICRS Right ascension of the object (hours).
	dec	[deg] ICRS Declination of the object (degrees).
	system	Input catalog coordinate system epoch, e.g. "ICRS", "B1950.0", "J2000.0", "FK4", "FK5", or "HIP". In general, any Besselian or Julian year epoch can be used by year (e.g. "B1933.193" or "J2022.033"), or else the fixed value listed. If 'B' or 'J' is ommitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0.
	z	Redhift value (λ_obs / λ_rest - 1 = f_rest / f_obs - 1).
[out]	source	Pointer to the celestial object data structure to be populated with the corresponding ICRS catalog coordinates.

Returns: 0 if successful, or -1 if any of the pointer arguments is NULL or the 'system' is invalid, or else 1 if 'type' is invalid, 2 if 'number' is out of legal range or 5 if 'name' is too long.

See also: make_redshifted_object(); make_cat_object_sys(); novas_jd_for_epoch(); place(); NOVAS_SYSTEM_ICRS; NOVAS_SYSTEM_HIP; NOVAS_SYSTEM_J2000; NOVAS_SYSTEM_B1950

Since: 1.3

Author: Attila Kovacs

References make_redshifted_object(), and object::star.

◆ novas_case_sensitive()

void novas_case_sensitive ( int value )

Enables or disables case-sensitive processing of the object name. The effect is not retroactive. The setting will only affect the celestial objects that are defined after the call. Note, that catalog names, set via make_cat_entry() are always case sensitive regardless of this setting.

Parameters

value (boolean) TRUE (non-zero) to enable case-sensitive object names, or else FALSE (0) to convert names to upper case only (NOVAS C compatible behavior).

See also: make_object()

Since: 1.0

Author: Attila Kovacs

◆ novas_helio_dist()

double novas_helio_dist	(	double	jd_tdb,
		const object *restrict	source,
		double *restrict	rate
	)

Returns a Solar-system body's distance from the Sun, and optionally also the rate of recession. It may be useful, e.g. to calculate the body's heating from the Sun.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated from the source.
	source	Observed Solar-system source
[out]	rate	[AU/day] (optional) Returned rate of recession from Sun

Returns: [AU] Distance from the Sun, or NAN if not a Solar-system source.

Since: 1.3

Author: Attila Kovacs

See also: novas_solar_power(); novas_solar_illum()

References ephemeris(), NOVAS_CATALOG_OBJECT, NOVAS_HELIOCENTER, NOVAS_REDUCED_ACCURACY, and novas_vlen().

◆ novas_planet_for_name()

enum novas_planet novas_planet_for_name ( const char *restrict name )

Returns the NOVAS planet ID for a given name (case insensitive), or -1 if no match is found.

Parameters

name	The planet name, or that for the "Sun", "Moon" or "SSB" (case insensitive). The spelled out "Solar System Barycenter" is also recognized with either spaces, hyphens ('-') or underscores ('_') separating the case insensitive words.

Returns: The NOVAS major planet ID, or -1 (errno set to EINVAL) if the input name is NULL or if there is no match for the name provided.

Author: Attila Kovacs

Since: 1.2

See also: make_planet()

References NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, and NOVAS_SSB.

◆ novas_solar_power()

double novas_solar_power	(	double	jd_tdb,
		const object *restrict	source
	)

Returns the typical incident Solar power on a Solar-system body at the time of observation.

Parameters

jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated ( was reflected) from the source.
source	Observed Solar-system source

Returns: [W/m²] Incident Solar power on the illuminated side of the object, or NAN if not a Solar-system source or if the source is the Sun itself.

Since: 1.3

Author: Attila Kovacs

See also: novas_solar_illum()

References novas_helio_dist(), and NOVAS_SOLAR_CONSTANT.

◆ proper_motion()

int proper_motion	(	double	jd_tdb_in,
		const double *	pos,
		const double *restrict	vel,
		double	jd_tdb_out,
		double *	out
	)

Applies proper motion, including foreshortening effects, to a star's position.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

	jd_tdb_in	[day] Barycentric Dynamical Time (TDB) based Julian date of the first epoch.
	pos	[AU] Position vector at first epoch.
	vel	[AU/day] Velocity vector at first epoch.
	jd_tdb_out	[day] Barycentric Dynamical Time (TDB) based Julian date of the second epoch.
[out]	out	Position vector at second epoch. It can be the same vector as the input.

Returns: 0 if successful, or -1 if any of the vector areguments is NULL.

See also: transform_cat()

◆ starvectors()

int starvectors	(	const cat_entry *restrict	star,
		double *restrict	pos,
		double *restrict	motion
	)

Converts angular quantities for stars to vectors.

NOTES:

The velocity returned should not be used for deriving spectroscopic radial velocity. It is a measure of the perceived change of the stars position, not a true physical velocity.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

	star	Pointer to catalog entry structure containing ICRS catalog
[out]	pos	[AU] Position vector, equatorial rectangular coordinates, components in AU. It may be NULL if not required.
[out]	motion	[AU/day] Perceived motion of star, in equatorial rectangular coordinates, components in AU/Day. It must be distinct from the pos output vector, and may be NULL if not required. Note, that it is suitable only for calculating the apparent 3D location of the star at a different time, and should not be used as a measure of physical velocity, e.g. for spectroscopic radial velocity determination.

Returns: 0 if successful, or -1 if the star argument is NULL or the output vectors are the same pointer.

See also: make_cat_entry()

References NOVAS_KMS, novas_los_to_xyz(), and radec2vector().

◆ transform_cat()

short transform_cat	(	enum novas_transform_type	option,
		double	jd_tt_in,
		const cat_entry *	in,
		double	jd_tt_out,
		const char *	out_id,
		cat_entry *	out
	)

Transform a star's catalog quantities for a change the coordinate system and/or the date for which the positions are calculated. Also used to rotate catalog quantities on the dynamical equator and equinox of J2000.0 to the ICRS or vice versa.

'date_incat' and 'date_newcat' may be specified either as a Julian date (e.g., 2433282.5 or NOVAS_JD_B1950) or a fractional Julian year and fraction (e.g., 1950.0). Values less than 10000 are assumed to be years. You can also use the supplied constants NOVAS_JD_J2000 or NOVAS_JD_B1950. The date arguments are ignored for the ICRS frame conversion options.

If 'option' is PROPER_MOTION (1), input data can be in any reference system. If 'option' is PRECESSION (2) or CHANGE_EPOCH (3), input data is assume to be in the dynamical system of 'date_incat' and produces output in the dynamical system of 'date_outcat'. If 'option' is CHANGE_J2000_TO_ICRS (4), the input data should be in the J2000.0 dynamical frame. And if 'option' is CHANGE_ICRS_TO_J2000 (5), the input data must be in the ICRS, and the output will be in the J2000 dynamical frame.

This function cannot be properly used to bring data from old star catalogs into the modern system, because old catalogs were compiled using a set of constants that are incompatible with modern values. In particular, it should not be used for catalogs whose positions and proper motions were derived by assuming a precession constant significantly different from the value implicit in function precession().

Parameters

	option	Type of transformation
	jd_tt_in	[day\|yr] Terrestrial Time (TT) based Julian date, or year, of input catalog data. Not used if option is CHANGE_J2000_TO_ICRS (4) or CHANGE_ICRS_TO_J2000 (5).
	in	An entry from the input catalog, with units as given in the struct definition
	jd_tt_out	[day\|yr] Terrestrial Time (TT) based Julian date, or year, of output catalog data. Not used if option is CHANGE_J2000_TO_ICRS (4) or CHANGE_ICRS_TO_J2000 (5).
	out_id	Catalog identifier (0 terminated). It may also be NULL in which case the catalog name is inherited from the input.
[out]	out	The transformed catalog entry, with units as given in the struct definition. It may be the same as the input.

Returns: 0 if successful, -1 if either vector argument is NULL or if the 'option' is invalid, or else 2 if 'out_id' is too long.

See also: transform_hip(); make_cat_entry(); novas_epoch(); NOVAS_JD_J2000; NOVAS_JD_B1950; NOVAS_JD_HIP

References cat_entry::catalog, CHANGE_EPOCH, CHANGE_ICRS_TO_J2000, CHANGE_J2000_TO_ICRS, cat_entry::dec, frame_tie(), ICRS_TO_J2000, J2000_TO_ICRS, NOVAS_JD_J2000, NOVAS_KMS, novas_los_to_xyz(), novas_vlen(), novas_xyz_to_los(), cat_entry::parallax, PRECESSION, precession(), cat_entry::promodec, cat_entry::promora, PROPER_MOTION, cat_entry::ra, radec2vector(), cat_entry::radialvelocity, SIZE_OF_CAT_NAME, SIZE_OF_OBJ_NAME, cat_entry::starname, and cat_entry::starnumber.

◆ transform_hip()

int transform_hip	(	const cat_entry *	hipparcos,
		cat_entry *	hip_2000
	)

Convert Hipparcos catalog data at epoch J1991.25 to epoch J2000.0, for use within NOVAS. To be used only for Hipparcos or Tycho stars with linear space motion. Both input and output data is in the ICRS.

Parameters

	hipparcos	An entry from the Hipparcos catalog, at epoch J1991.25, with 'ra' in degrees(!) as per Hipparcos catalog units.
[out]	hip_2000	The transformed input entry, at epoch J2000.0, with 'ra' in hours(!) as per the NOVAS convention. It may be the same as the input.

Returns: 0 if successful, or -1 if either of the input pointer arguments is NULL.

See also: make_cat_entry(); NOVAS_JD_HIP

References cat_entry::catalog, NOVAS_JD_HIP, cat_entry::ra, and transform_cat().

Macros

Functions

Detailed Description

Function Documentation

◆ make_cat_entry()

◆ make_cat_object()

◆ make_cat_object_sys()

◆ make_ephem_object()

◆ make_object()

◆ make_orbital_object()

◆ make_planet()

◆ make_redshifted_cat_entry()

◆ make_redshifted_object()

◆ make_redshifted_object_sys()

◆ novas_case_sensitive()

◆ novas_helio_dist()

◆ novas_planet_for_name()

◆ novas_solar_power()

◆ proper_motion()

◆ starvectors()

◆ transform_cat()

◆ transform_hip()