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

This module contains functions that define an observing target, or which are target related. More...

## Functions

short | make_cat_entry (const char *restrict name, const char *restrict catalog, long cat_num, double ra, double dec, double pm_ra, double pm_dec, double parallax, double rv, cat_entry *source)
| Fully populates the data structure for a catalog source, such as a star, with all parameters provided at once.
int | make_cat_object (const cat_entry *star, object *source)
| Populates and object data structure with the data for a catalog source.
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.
int | make_ephem_object (const char *name, long num, object *body)
| Sets a celestial object to be a Solar-system ephemeris 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)
| Sets a celestial object to be a Solar-system orbital body.
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.
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.
int | make_redshifted_object (const char *name, double ra, double dec, double z, object *source)
| Populates a celestial object data structure with the ICRS astrometric parameters for a redhifted catalog source, such as a distant quasar or galaxy.
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.
void | novas_case_sensitive (int value)
| Enables or disables case-sensitive processing of the object name.
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.
int | novas_init_cat_entry (cat_entry *restrict source, const char *restrict name, double ra, double dec)
| Initializes a catalog entry, such as a star or a distant galaxy, with a name and coordinates.
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.
int | novas_set_catalog (cat_entry *restrict source, const char *restrict catalog, long num)
| Sets the optional catalog information for a sidereal source.
int | novas_set_distance (cat_entry *source, double parsecs)
| Sets the distance for a catalog source.
int | novas_set_lsr_vel (cat_entry *source, double epoch, double v_kms)
| Sets a radial velocity for a catalog source, defined w.r.t.
int | novas_set_parallax (cat_entry *source, double mas)
| Sets the parallax (a measure of distance) for a catalog source.
int | novas_set_proper_motion (cat_entry *source, double pm_ra, double pm_dec)
| Sets the proper-motion for a (Galactic) catalog source.
int | novas_set_redshift (cat_entry *source, double z)
| Sets a redshift for a catalog source, as a relativistic measure of velocity.
int | novas_set_ssb_vel (cat_entry *source, double v_kms)
| Sets a radial velocity for a catalog source, defined w.r.t.
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.
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.
int | starvectors (const cat_entry *restrict star, double *restrict pos, double *restrict motion)
| Converts angular quantities for stars to vectors.
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.
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.

## Detailed Description

This module contains functions that define an observing target, or which are target related.

## Function Documentation

## make_cat_entry()

short make_cat_entry | ( | const char *restrict | name,
|  | const char *restrict | catalog,
|  | long | cat_num,
|  | double | ra,
|  | double | dec,
|  | double | pm_ra,
|  | double | pm_dec,
|  | double | parallax,
|  | double | rv,
|  | cat_entry * | source )

Fully populates the data structure for a catalog source, such as a star, with all parameters provided at once.

Alternatively, you may use novas_init_cat_entry() to initialize just with the name and R.A./Dec coordinates, and then add further information step-by-step as needed, including using alternative parameters (SSB vs. LSR velocity, vs. redshift; parallax vs. distance). The latter approach provides more flexibility, and will result in more readable code, which is also easier to debug.

Parameters

  | name | Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL if not relevant.
  | catalog | Catalog identifier or epoch (less than SIZE_OF_CAT_NAME in length). E.g. 'HIP' for Hipparcos, 'TY2' for Tycho-2; or 'ICRS', 'B1950', 'J2000'. It may be NULL if not relevant.
  | cat_num | Object number in the catalog. It is not used internally, so you may set it to anything that is meaningful to you, or set it to 0 as a default.
  | ra | [h] Right ascension of the object.
  | dec | [deg] Declination of the object.
  | pm_ra | [mas/yr] Proper motion in right ascension.
  | pm_dec | [mas/yr] Proper motion in declination.
  | parallax | [mas] Parallax.
  | rv | [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. Or, to convert from a redshift value, you might use novas_z2v().
  [out] | source | 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_init_cat_entry(), make_redshifted_cat_entry(), make_cat_object_sys()
  novas_lsr_to_ssb_vel(), transform_cat()

References novas_init_cat_entry(), novas_set_catalog(), novas_set_parallax(), novas_set_proper_motion(), and novas_set_ssb_vel().

## 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 astrometric parameters must be defined with ICRS. To create objects in other reference systems, use make_cat_object_sys() instead.

NOTES:

1. This call does not initialize the orbit field (added in v1.2) with zeroes to remain ABI compatible with versions <1.2.

Parameters

  | star | Pointer to structure to populate with the catalog data for a celestial object located outside the solar system, specified with ICRS astrometric parameters.
  [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_redshifted_object(), make_planet(), make_ephem_object(), make_orbital_object()
  novas_init_cat_entry(), novas_case_sensitive(), novas_make_frame()

Since
  1.1

Author
  Attila Kovacs

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

Referenced by make_cat_object_sys(), and make_redshifted_object().

## 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 omitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0, and Julian epochs after. (See novas_epoch() for more).

  [out] | source | Pointer to the celestial object data structure to be populated with the corresponding ICRS catalog coordinates, after applying 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_case_sensitive(), novas_make_frame()
  novas_epoch(), NOVAS_SYSTEM_ICRS, NOVAS_SYSTEM_HIP, NOVAS_SYSTEM_J2000, NOVAS_SYSTEM_B1950

Since
  1.3

Author
  Attila Kovacs

References make_cat_object(), novas_object::orbit, and novas_object::star.

Referenced by supernovas::CatalogSource::CatalogSource().

## 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.

NOTES:

1. This call does not initialize the orbit field (added in v1.2) with zeroes to remain ABI compatible with versions <1.2.

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
  make_planet(), make_orbital_object(), make_cat_object(), make_redshifted_object()
  set_ephem_provider(), novas_case_sensitive(), novas_make_frame()

Since
  1.0

Author
  Attila Kovacs

References make_object(), and NOVAS_EPHEM_OBJECT.

Referenced by supernovas::EphemerisSource::EphemerisSource().

## make_object()

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

Deprecated
  More functionality and more readable, code results from using one of the specific alternatives: make_cat_object(), make_redshifted_object(), make_planet(), make_ephem_object(), or make_orbital_object().

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:

1. This call does not initialize the orbit field (added in v1.2) with zeroes to remain ABI compatible with versions <1.2.

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
  make_cat_object(), make_redshifted_object(), make_planet(), make_ephem_object(), make_orbital_object()
  novas_case_sensitive(), novas_make_frame()

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

Referenced by make_cat_object(), make_ephem_object(), make_orbital_object(), and make_planet().

## 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
  make_planet(), make_ephem_object(), make_cat_object(), make_redshifted_object()
  novas_case_sensitive(), novas_orbit_posvel(), novas_make_frame()

Since
  1.2

Author
  Attila Kovacs

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

Referenced by supernovas::OrbitalSource::OrbitalSource().

## 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.

NOTES:

1. This call does not initialize the orbit field (added in v1.2) with zeroes to remain ABI compatible with versions <1.2.

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_orbital_object(), make_cat_object(), make_redshifted_object()
  novas_case_sensitive(), novas_make_frame()

Since
  1.0

Author
  Attila Kovacs

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

Referenced by supernovas::Planet::Planet(), ephemeris(), novas_approx_sky_pos(), and obs_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 = frest / fobs - 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_set_catalog(), novas_v2z()

Since
  1.2

Author
  Attila Kovacs

References novas_init_cat_entry(), novas_set_catalog(), and novas_set_redshift().

Referenced by make_redshifted_object().

## 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 ICRS astrometric parameters for a redhifted catalog source, such as a distant quasar or galaxy.

To create redshifted objects with in other reference systems, use make_redshifted_object_sys() instead.

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 = frest / fobs - 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()
  novas_str_hours(), novas_str_degrees()

Since
  1.2

Author
  Attila Kovacs

References make_cat_object(), make_redshifted_cat_entry(), and novas_object::orbit.

Referenced by make_redshifted_object_sys().

## 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 omitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0.
  | z | Redhift value (λobs / λrest - 1 = frest / fobs - 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_epoch(), novas_case_sensitive(), novas_make_frame()
  novas_str_hours(), novas_str_degrees(), NOVAS_SYSTEM_ICRS, NOVAS_SYSTEM_HIP, NOVAS_SYSTEM_J2000, NOVAS_SYSTEM_B1950

Since
  1.3

Author
  Attila Kovacs

References make_redshifted_object(), novas_object::orbit, and novas_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

Referenced by supernovas::Source::set_case_sensitive().

## 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().

Referenced by supernovas::SolarSystemSource::helio_distance(), supernovas::SolarSystemSource::helio_rate(), and novas_solar_power().

## novas_init_cat_entry()

int novas_init_cat_entry | ( | cat_entry *restrict | source,
|  | const char *restrict | name,
|  | double | ra,
|  | double | dec )

Initializes a catalog entry, such as a star or a distant galaxy, with a name and coordinates.

All other fields of the cat_entry structure will be initialized with zeroes. After the initialization, you may set further properties, such as:

- a radial velocity, LSR velocity, or redshift.
- a parallax or distance
- proper motion
- optional catalog name an number

The typical process for setting up a catalog source is captured by the following steps:

1. Initialize the cat_entry with source name and RA / Dec coordinates using novas_init_cat_entry().
2. (optional) Set radial velocity, as needed, via either:
   - radial velocity (km/s) w.r.t SSB using novas_set_ssb_vel(), or
   - LSR velocity (km/s) using novas_set_lsr_vel(), or
   - redshift using novas_set_redshift().
3. (optional) Set proper motions (mas/yr), as needed, using novas_set_proper_motion().
4. (optional) Set parallax, as needed, via either:
   - parallax (mas) using novas_set_parallax(), or
   - distance (parsec) using novas_set_distance().
5. (optional) Assign catalog info if desired via novas_set_catalog().

After the initialization (Step 1), order does not matter.

Parameters

  [out] | source | Output structure to populate.
  | name | Object name (less than SIZE_OF_OBJ_NAME in length). It may be NULL if not relevant.
  | ra | [h] Right ascension of the object.
  | dec | [deg] Declination of the object.

Returns
  0 if successful, or else -1 if the source is NULL (errno set to EINVAL) or 1 if the name is too long (errno is set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_ssb_vel(), novas_set_lsr_vel(), novas_set_redshift(), novas_set_proper_motion(), novas_set_parallax(), novas_set_distance(), novas_set_catalog(), make_cat_entry()
  novas_str_hours(), novas_str_degrees()

References SIZE_OF_OBJ_NAME.

Referenced by supernovas::CatalogEntry::CatalogEntry(), make_cat_entry(), and make_redshifted_cat_entry().

## 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. Only up to 63 characters (not including termination) of the input are processed.

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.

Referenced by supernovas::Planet::for_name().

## novas_set_catalog()

int novas_set_catalog | ( | cat_entry *restrict | source,
|  | const char *restrict | catalog,
|  | long | num )

Sets the optional catalog information for a sidereal source.

SuperNOVAS does not use the catalog information internally. It is entirely for the convenience of the user to set these values if it is useful to them.

Parameters

  [out] | source | Output structure to populate with the parameters.
  | catalog | Catalog identifier or epoch (less than SIZE_OF_CAT_NAME in length). E.g. 'HIP' for Hipparcos, 'TY2' for Tycho-2; or 'ICRS', 'B1950', 'J2000'. It may be NULL if not relevant.
  | num | Object's number in catalog.

Returns
  0 if successful, or else -1 if the source is NULL (errno set to EINVAL), or 2 if the catalog name is too long (errno is set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_init_cat_entry()

References SIZE_OF_CAT_NAME.

Referenced by make_cat_entry(), and make_redshifted_cat_entry().

## novas_set_distance()

int novas_set_distance | ( | cat_entry * | source,
|  | double | parsecs )

Sets the distance for a catalog source.

Parameters

  [out] | source | Output structure to populate with the parameters.
  | parsecs | [pc] distance

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_parallax(), novas_init_cat_entry()

References novas_set_parallax().

Referenced by supernovas::CatalogEntry::distance().

## novas_set_lsr_vel()

int novas_set_lsr_vel | ( | cat_entry * | source,
|  | double | epoch,
|  | double | v_kms )

Sets a radial velocity for a catalog source, defined w.r.t.

the Local Standard of Rest (LSR).

Parameters

  [out] | source | Output structure to populate with the parameters.
  | epoch | [yr] Coordinate epoch.
  | v_kms | [km/s] Radial velocity of source w.r.t. the Local Standard of Rest (LSR).

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL) or if the velocity exceeds the speed of light (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_ssb_vel(), novas_lsr_to_ssb_vel(), novas_set_redshift(), novas_init_cat_entry()

References novas_cat_entry::dec, novas_lsr_to_ssb_vel(), novas_set_ssb_vel(), and novas_cat_entry::ra.

Referenced by supernovas::CatalogEntry::v_lsr().

## novas_set_parallax()

int novas_set_parallax | ( | cat_entry * | source,
|  | double | mas )

Sets the parallax (a measure of distance) for a catalog source.

Parameters

  [out] | source | Output structure to populate with the parameters.
  | mas | [mas] Parallax

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_distance(), novas_init_cat_entry()

References novas_cat_entry::parallax.

Referenced by make_cat_entry(), novas_set_distance(), and supernovas::CatalogEntry::parallax().

## novas_set_proper_motion()

int novas_set_proper_motion | ( | cat_entry * | source,
|  | double | pm_ra,
|  | double | pm_dec )

Sets the proper-motion for a (Galactic) catalog source.

Parameters

  [out] | source | Output structure to populate with the parameters.
  | pm_ra | [mas/yr] Proper motion in right ascension.
  | pm_dec | [mas/yr] Proper motion in declination.

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_parallax(), novas_set_distance(), novas_init_cat_entry()

References novas_cat_entry::promodec, and novas_cat_entry::promora.

Referenced by make_cat_entry(), and supernovas::CatalogEntry::proper_motion().

## novas_set_redshift()

int novas_set_redshift | ( | cat_entry * | source,
|  | double | z )

Sets a redshift for a catalog source, as a relativistic measure of velocity.

Parameters

  [out] | source | Output structure to populate with the parameters.
  | z | [-1:inf] The redshift measure z, defined as (1 + z) = sqrt((1 + v/_c_) / (1 - v/_c_))

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL) or if the redshift is invalid (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_ssb_vel(), novas_init_cat_entry()

References novas_set_ssb_vel(), and novas_z2v().

Referenced by make_redshifted_cat_entry(), and supernovas::CatalogEntry::redshift().

## novas_set_ssb_vel()

int novas_set_ssb_vel | ( | cat_entry * | source,
|  | double | v_kms )

Sets a radial velocity for a catalog source, defined w.r.t.

the Solar-System Barycenter (SSB).

Parameters

  [out] | source | Output structure to populate with the parameters.
  | v_kms | [km/s] Radial velocity of source w.r.t. the Solar-System Barycenter (SSB).

Returns
  0 if successful, or else -1 if the source is NULL (errno is set to EINVAL) or if the velocity exceeds the speed of light (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_lsr_vel(), novas_set_redshift(), novas_init_cat_entry()

References NOVAS_C, and novas_cat_entry::radialvelocity.

Referenced by make_cat_entry(), novas_set_lsr_vel(), novas_set_redshift(), and supernovas::CatalogEntry::radial_velocity().

## 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/m2] 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.

Referenced by supernovas::SolarSystemSource::solar_power().

## 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:

1. 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 arguments is NULL.

See also
  transform_cat()

Referenced by novas_geom_posvel(), and place().

## starvectors()

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

Converts angular quantities for stars to vectors.

NOTES:

1. 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:

1. 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, It may be NULL if not required.
  [out] | motion | [AU/day] Perceived motion of star, in equatorial rectangular coordinates. 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(), novas_init_cat_entry()

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

Referenced by mean_star(), novas_geom_posvel(), and place().

## 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 (if >=10000), or else year (if <10000), 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 (if >= 10000), or else year (if <10000) 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_object_sys(), novas_set_catalog()
  novas_epoch(), NOVAS_JD_J2000, NOVAS_JD_B1950, NOVAS_JD_HIP

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

Referenced by transform_hip().

## 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 novas_cat_entry::catalog, NOVAS_JD_HIP, PROPER_MOTION, novas_cat_entry::ra, and transform_cat().