Loading...
Searching...
No Matches
Astronomical object of interest

Defining the astronomical source of interest, or accessing properties thereof. More...

## Classes

struct | novas_cat_entry
| Basic astrometric data for any sidereal object located outside the solar system. More...
struct | novas_object
| Celestial object of interest. More...
struct | novas_orbital
| Keplerian orbital elements for NOVAS_ORBITAL_OBJECT type. More...
struct | novas_orbital_system
| Specification of an orbital system, in which orbital elements are defined. More...

## Macros

#define | CAT_ENTRY_INIT
| Initializer for a NOVAS cat_entry structure.
#define | NOVAS_AU 1.495978707e+11
| [m] Astronomical unit (AU).
#define | NOVAS_DEFAULT_DISTANCE (1e9 * NOVAS_PARSEC)
| [m] Default distance at which sidereal sources are assumed when not specified otherwise Historically NOVAS placed sources with no parallax at 1 Gpc distance, and so we follow.
#define | NOVAS_EARTH_INIT
| object initializer for the planet Earth
#define | NOVAS_EMB_INIT
| object initializer for the Earth-Moon Barycenter (EMB)
#define | NOVAS_JUPITER_INIT
| object initializer for the planet Jupiter
#define | NOVAS_KMS (NOVAS_KM)
| [m] One km/s in m/s.
#define | NOVAS_LIGHT_YEAR ( NOVAS_C * NOVAS_TROPICAL_YEAR_DAYS * NOVAS_DAY )
| [m] A light-year in meters.
#define | NOVAS_MARS_INIT
| object initializer for the planet Mars
#define | NOVAS_MERCURY_INIT
| object initializer for the planet Mercury
#define | NOVAS_MOON_INIT
| object initializer for the Moon
#define | NOVAS_NEPTUNE_INIT
| object initializer for the planet Neptune
#define | NOVAS_OBJECT_INIT
| Empty object initializer.
#define | NOVAS_ORBIT_INIT
| Initializer for novas_orbital for heliocentric orbits using GCRS ecliptic parametrization.
#define | NOVAS_ORBITAL_SYSTEM_INIT
| Default orbital system initializer for heliocentric GCRS ecliptic orbits.
#define | NOVAS_PARSEC ( NOVAS_AU / NOVAS_ARCSEC )
| [m] A parsec in meters.
#define | NOVAS_PLANET_NAMES_INIT
| String array initializer for Major planet names, matching the enum novas_planet.
#define | NOVAS_PLUTO_BARYCENTER_INIT
| object initializer for the Pluto system barycenter
#define | NOVAS_PLUTO_INIT
| object initializer for the minor planet Pluto
#define | NOVAS_REFERENCE_PLANES
| Number of entries in enum novas_reference_plane.
#define | NOVAS_SATURN_INIT
| object initializer for the planet Saturn
#define | NOVAS_SSB_INIT
| object initializer for the Solar System Barycenter (SSB)
#define | NOVAS_SUN_INIT
| object initializer for the Sun
#define | NOVAS_SYSTEM_B1950 "B1950"
| The B1950 coordinate system as a string.
#define | NOVAS_SYSTEM_FK4 "FK4"
| The 4th catalog of fundamental stars (FK4) coordinate system as a string.
#define | NOVAS_SYSTEM_FK5 "FK5"
| The 5th catalog of fundamental stars (FK5) coordinate system as a string.
#define | NOVAS_SYSTEM_FK6 "FK6"
| The 6th catalog of fundamental stars (FK6) coordinate system as a string.
#define | NOVAS_SYSTEM_HIP "HIP"
| The Hipparcos dataset coordinate system as a string.
#define | NOVAS_SYSTEM_ICRS "ICRS"
| The ICRS system as a string.
#define | NOVAS_SYSTEM_J2000 "J2000"
| The J2000 coordinate system, as a string.
#define | NOVAS_URANUS_INIT
| object initializer for the planet Uranus
#define | NOVAS_VENUS_INIT
| object initializer for the planet Venus
#define | SIZE_OF_CAT_NAME 6
| Maximum maximum bytes stored for catalog IDs including string termination.
#define | SIZE_OF_OBJ_NAME 50
| Maximum number of bytes stored for object names including string termination.

## Typedefs

typedef struct novas_cat_entry | cat_entry
| Basic astrometric data for any sidereal object located outside the solar system.
typedef struct novas_orbital | novas_orbital
| Keplerian orbital elements for NOVAS_ORBITAL_OBJECT type.
typedef struct novas_orbital_system | novas_orbital_system
| Specification of an orbital system, in which orbital elements are defined.
typedef struct novas_object | object
| Celestial object of interest.

## Enumerations

enum | novas_object_type { NOVAS_PLANET = 0 , NOVAS_EPHEM_OBJECT , NOVAS_CATALOG_OBJECT , NOVAS_ORBITAL_OBJECT }
| The type of astronomical objects distinguished by the NOVAS library. More...
enum | novas_planet { NOVAS_SSB = 0 , NOVAS_MERCURY , NOVAS_VENUS , NOVAS_EARTH , NOVAS_MARS , NOVAS_JUPITER , NOVAS_SATURN , NOVAS_URANUS , NOVAS_NEPTUNE , NOVAS_PLUTO , NOVAS_SUN , NOVAS_MOON , NOVAS_EMB , NOVAS_PLUTO_BARYCENTER }
| Enumeration for the 'major planet' numbers in NOVAS to use as the solar-system body number whenever the object type is NOVAS_PLANET. More...
enum | novas_reference_plane { NOVAS_ECLIPTIC_PLANE = 0 , NOVAS_EQUATORIAL_PLANE }
| The plane in which values, such as orbital parameters are referenced. More...
enum | novas_transform_type { PROPER_MOTION = 1 , PRECESSION , CHANGE_EPOCH , CHANGE_J2000_TO_ICRS , CHANGE_ICRS_TO_J2000 }
| The types of coordinate transformations available for transform_cat(). 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.
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.
enum novas_planet | naif_to_novas_planet (long id)
| Converts a NAIF ID to a NOVAS major planet ID.
void | novas_case_sensitive (int value)
| Enables or disables case-sensitive processing of the object name.
int | novas_equals_cat_entry (const cat_entry *a, const cat_entry *b)
| Checks if two catalog entries define the same parameters, within the typical tolerances associated to these.
int | novas_equals_object (const object *a, const object *b)
| Checks if two astronomical targets are the same within typical tolerances.
int | novas_equals_orbital (const novas_orbital *a, const novas_orbital *b)
| Checks if two Keplerian orbitals match, within typical tolerances.
int | novas_equals_orbsys (const novas_orbital_system *a, const novas_orbital_system *b)
| Checks if two orbital systems match within typical tolerances.
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.
int | novas_make_moon_mean_orbit (double jd_tdb, novas_orbital *restrict orbit)
| Gets mean orbital elements for the Moon relative to the geocenter for the specified epoch of observation.
int | novas_make_moon_orbit (double jd_tdb, novas_orbital *restrict orbit)
| Gets an approximation of the current Keplerian orbital elements for the Moon relative to the geocenter for the specified epoch of observation.
int | novas_make_planet_orbit (enum novas_planet id, double jd_tdb, novas_orbital *restrict orbit)
| Get approximate current heliocentric orbital elements for the major planets.
int | novas_orbit_posvel (double jd_tdb, const novas_orbital *restrict orbit, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
| Calculates a rectangular equatorial position and velocity vector for the given orbital elements for the specified time of observation.
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_orbsys_pole (enum novas_reference_system type, double ra, double dec, novas_orbital_system *restrict sys)
| Sets the orientation of an orbital system using the RA and DEC coordinates of the pole of the Laplace (or else equatorial) plane relative to which the orbital elements are defined.
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.
long | novas_to_dexxx_planet (enum novas_planet id)
| Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID for DExxx ephemeris files.
long | novas_to_naif_planet (enum novas_planet id)
| Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID.
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, 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

Defining the astronomical source of interest, or accessing properties thereof.

A source may be a sidereal catalog source, such as as star, molecular cloud or a distant galaxy, or else it may be a Solar-system body, such as planets, moons, asteroids, comets or near-Earth objects (NEOs). Solar-system sources may have positions and velocities provided through ephemeris data (such as the NASA JPL planetary on other ephemeris files), or else via orbital models (such as published by the IAU Minor Planet Center [MPC]).

## Macro Definition Documentation

## CAT_ENTRY_INIT

#define CAT_ENTRY_INIT

Initializer for a NOVAS cat_entry structure.

Author
  Attila Kovacs

Since
  1.1.1

See also
  cat_entry

Referenced by mean_star().

## NOVAS_AU

#define NOVAS_AU 1.495978707e+11

[m] Astronomical unit (AU).

IAU definition. See IAU 2012 Resolution B2.

See also
  DE405_AU

Referenced by grav_vec(), novas_equals_orbital(), novas_equals_planet_bundle(), novas_equals_ssb_posvel(), novas_make_moon_mean_orbit(), novas_make_moon_orbit(), novas_moon_elp_ecl_pos(), novas_uvw(), and rad_vel2().

## NOVAS_DEFAULT_DISTANCE

#define NOVAS_DEFAULT_DISTANCE (1e9 * NOVAS_PARSEC)

[m] Default distance at which sidereal sources are assumed when not specified otherwise Historically NOVAS placed sources with no parallax at 1 Gpc distance, and so we follow.

Since
  1.5

## NOVAS_EARTH_INIT

#define NOVAS_EARTH_INIT

object initializer for the planet Earth

Since
  1.2

See also
  object

Referenced by geo_posvel(), novas_make_frame(), obs_posvel(), and place().

## NOVAS_EMB_INIT

#define NOVAS_EMB_INIT

object initializer for the Earth-Moon Barycenter (EMB)

Since
  1.2

See also
  object

## NOVAS_JUPITER_INIT

#define NOVAS_JUPITER_INIT

object initializer for the planet Jupiter

Since
  1.2

See also
  object

## NOVAS_KMS

#define NOVAS_KMS (NOVAS_KM)

[m] One km/s in m/s.

Since
  1.3

Referenced by novas_moon_elp_sky_pos_fp(), novas_site_gcrs_posvel(), novas_v2z(), novas_z2v(), rad_vel2(), starvectors(), and transform_cat().

## NOVAS_LIGHT_YEAR

#define NOVAS_LIGHT_YEAR ( NOVAS_C * NOVAS_TROPICAL_YEAR_DAYS * NOVAS_DAY )

[m] A light-year in meters.

Since
  1.5

## NOVAS_MARS_INIT

#define NOVAS_MARS_INIT

object initializer for the planet Mars

Since
  1.2

See also
  object

## NOVAS_MERCURY_INIT

#define NOVAS_MERCURY_INIT

object initializer for the planet Mercury

Since
  1.2

See also
  object

## NOVAS_MOON_INIT

#define NOVAS_MOON_INIT

object initializer for the Moon

Since
  1.2

See also
  object

Referenced by novas_moon_angle().

## NOVAS_NEPTUNE_INIT

#define NOVAS_NEPTUNE_INIT

object initializer for the planet Neptune

Since
  1.2

See also
  object

## NOVAS_OBJECT_INIT

#define NOVAS_OBJECT_INIT

Empty object initializer.

Since
  1.3

Author
  Attila Kovacs

See also
  object

## NOVAS_ORBIT_INIT

#define NOVAS_ORBIT_INIT

Initializer for novas_orbital for heliocentric orbits using GCRS ecliptic parametrization.

Author
  Attila Kovacs

Since
  1.2

See also
  novas_orbital

Referenced by novas_approx_heliocentric(), novas_make_moon_mean_orbit(), novas_make_planet_orbit(), and novas_moon_phase().

## NOVAS_ORBITAL_SYSTEM_INIT

#define NOVAS_ORBITAL_SYSTEM_INIT

Default orbital system initializer for heliocentric GCRS ecliptic orbits.

Author
  Attila Kovacs

Since
  1.2

See also
  novas_orbital_system

## NOVAS_PARSEC

#define NOVAS_PARSEC ( NOVAS_AU / NOVAS_ARCSEC )

[m] A parsec in meters.

Since
  1.5

## NOVAS_PLANET_NAMES_INIT

#define NOVAS_PLANET_NAMES_INIT

String array initializer for Major planet names, matching the enum novas_planet.

E.g.

const char *planet_names[] = NOVAS_PLANET_NAMES_INIT;
NOVAS_PLANET_NAMES_INIT
#define NOVAS_PLANET_NAMES_INIT
String array initializer for Major planet names, matching the enum novas_planet.
Definition novas.h:659

Since
  1.2

Author
  Attila Kovacs

See also
  enum novas_planet

Referenced by make_planet(), novas_planet_for_name(), and planet_ephem_provider_hp().

## NOVAS_PLUTO_BARYCENTER_INIT

#define NOVAS_PLUTO_BARYCENTER_INIT

object initializer for the Pluto system barycenter

Since
  1.2

See also
  object

## NOVAS_PLUTO_INIT

#define NOVAS_PLUTO_INIT

object initializer for the minor planet Pluto

Since
  1.2

See also
  object

## NOVAS_REFERENCE_PLANES

#define NOVAS_REFERENCE_PLANES

Number of entries in enum novas_reference_plane.

Since
  1.6

## NOVAS_SATURN_INIT

#define NOVAS_SATURN_INIT

object initializer for the planet Saturn

Since
  1.2

See also
  object

## NOVAS_SSB_INIT

#define NOVAS_SSB_INIT

object initializer for the Solar System Barycenter (SSB)

Since
  1.2

See also
  object

## NOVAS_SUN_INIT

#define NOVAS_SUN_INIT

object initializer for the Sun

Since
  1.2

See also
  object

Referenced by novas_make_frame(), novas_sun_angle(), and place().

## NOVAS_SYSTEM_B1950

#define NOVAS_SYSTEM_B1950 "B1950"

The B1950 coordinate system as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys(), make_redshifted_object_sys()

## NOVAS_SYSTEM_FK4

#define NOVAS_SYSTEM_FK4 "FK4"

The 4th catalog of fundamental stars (FK4) coordinate system as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys()

Referenced by novas_epoch().

## NOVAS_SYSTEM_FK5

#define NOVAS_SYSTEM_FK5 "FK5"

The 5th catalog of fundamental stars (FK5) coordinate system as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys()

Referenced by novas_epoch().

## NOVAS_SYSTEM_FK6

#define NOVAS_SYSTEM_FK6 "FK6"

The 6th catalog of fundamental stars (FK6) coordinate system as a string.

Since
  1.5

See also
  novas_set_catalog(), make_cat_object_sys()

Referenced by novas_epoch().

## NOVAS_SYSTEM_HIP

#define NOVAS_SYSTEM_HIP "HIP"

The Hipparcos dataset coordinate system as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys()

Referenced by novas_epoch().

## NOVAS_SYSTEM_ICRS

#define NOVAS_SYSTEM_ICRS "ICRS"

The ICRS system as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys(), make_redshifted_object_sys()

## NOVAS_SYSTEM_J2000

#define NOVAS_SYSTEM_J2000 "J2000"

The J2000 coordinate system, as a string.

Since
  1.3

See also
  novas_set_catalog(), make_cat_object_sys(), make_redshifted_object_sys()

## NOVAS_URANUS_INIT

#define NOVAS_URANUS_INIT

object initializer for the planet Uranus

Since
  1.2

See also
  object

## NOVAS_VENUS_INIT

#define NOVAS_VENUS_INIT

object initializer for the planet Venus

Since
  1.2

See also
  object

## SIZE_OF_CAT_NAME

#define SIZE_OF_CAT_NAME 6

Maximum maximum bytes stored for catalog IDs including string termination.

See also
  cat_entry

Referenced by novas_equals_cat_entry(), novas_set_catalog(), and transform_cat().

## SIZE_OF_OBJ_NAME

#define SIZE_OF_OBJ_NAME 50

Maximum number of bytes stored for object names including string termination.

See also
  cat_entry

Referenced by novas_equals_cat_entry(), novas_equals_object(), novas_init_cat_entry(), and transform_cat().

## Typedef Documentation

## cat_entry

typedef struct novas_cat_entry cat_entry

Basic astrometric data for any sidereal object located outside the solar system.

Note, that despite the slightly expanded catalog name, this has the same memory footprint as the original NOVAS C version, allowing for cross-compatible binary exchange (I/O) of these structures.

See also
  novas_init_cat_entry(), make_cat_entry(), make_cat_object()
  CAT_ENTRY_INIT

## novas_orbital

typedef struct novas_orbital novas_orbital

Keplerian orbital elements for NOVAS_ORBITAL_OBJECT type.

Orbital elements can be used to provide approximate positions for various Solar-system bodies. JPL publishes orbital elements (and their evolution) for the major planets and their satellites. However, these are suitable only for very approximate calculations, with up to degree scale errors for the gas giants for the time range between 1850 AD and 2050 AD. Accurate positions and velocities for planets and their satellites should generally require the use of precise ephemeris data instead, such as obtained from the JPL Horizons system.

Orbital elements describe motion from a purely Keplerian perspective. However, for short periods, for which the perturbing bodies can be ignored, this description can be quite accurate provided that an up-to-date set of values are used. The Minor Planet Center (MPC) thus regularly publishes orbital elements for all known asteroids and comets. For such objects, orbital elements can offer precise, and the most up-to-date positions and velocities.

REFERENCES:

1. Up-to-date orbital elements for asteroids, comets, etc from the Minor Planet Center (MPC): https://minorplanetcenter.net/data
2. Mean elements for planetary satellites from JPL Horizons: https://ssd.jpl.nasa.gov/sats/elem/
3. Low accuracy mean elements for planets from JPL Horizons: https://ssd.jpl.nasa.gov/planets/approx_pos.html

Author
  Attila Kovacs

Since
  1.2

See also
  make_orbital_object(), NOVAS_ORBIT_INIT, enum NOVAS_ORBITAL_OBJECT

## novas_orbital_system

typedef struct novas_orbital_system novas_orbital_system

Specification of an orbital system, in which orbital elements are defined.

Systems can be defined around all major planets and barycenters (and Sun, Moon, SSB..). They may be referenced to the GCRS, mean, or true equator or ecliptic of date, or to a plane that is tilted relative to that.

For example, The Minor Planet Center (MPC) publishes up-to-date orbital elements for asteroids and comets, which are heliocentric and referenced to the GCRS ecliptic. Hence 'center' for these is NOVAS_SUN, the plane is NOVAS_ECLIPTIC_PLANE and the type is NOVAS_GCRS_EQUATOR.

The orbits of planetary satellites may be parametrized in their local Laplace planes, which are typically close to the host planet's equatorial planes. You can, for example, obtain the RA/Dec orientation of the planetary North poles of planets from JPL Horizons, and use them as a proxy for the Laplace planes for their satellite orbits. In this case you would set the center to the host planet (e.g. NOVAS_SATURN), the reference plane to NOVAS_EQUATORIAL_PLANE and the type to NOVAS_GCRS_EQUATOR (since the plane is defined by the North pole orientation in GCRS equatorial RA/Dec). The obliquity is then 90° - Decpole (in radians), and phi is RApole (in radians).

Author
  Attila Kovacs

Since
  1.2

See also
  novas_orbital, novas_set_orbsys_pole(), NOVAS_ORBITAL_SYSTEM_INIT

## object

typedef struct novas_object object

Celestial object of interest.

Note, the memory footprint is different from NOVAS C due to the use of the enum vs short 'type' and the long vs. short 'number' values – hence it is not cross-compatible for binary data exchange with NOVAS C 3.1.

See also
  make_cat_object(), make_redshifted_object(), make_planet(), make_ephem_object(), make_orbital_object()
  NOVAS_OBJECT_INIT, NOVAS_MERCURY_INIT, NOVAS_VENUS_INIT, NOVAS_EARTH_INIT, NOVAS_MARS_INIT, NOVAS_JUPITER_INIT, NOVAS_SATURN_INIT, NOVAS_URANUS_INIT, NOVAS_NEPTUNE_INIT, NOVAS_PLUTO_INIT, NOVAS_PLUTO_BARYCENTER_INIT, NOVAS_SUN_INIT, NOVAS_SSB_INIT, NOVAS_MOON_INIT, NOVAS_EMB_INIT
  novas_sky_pos(), novas_geom_posvel(), novas_rises_above(), novas_transit_time(), novas_sets_below() novas_sun_angle(), novas_moon_angle(), novas_object_sep()

## Enumeration Type Documentation

## novas_object_type

enum novas_object_type

The type of astronomical objects distinguished by the NOVAS library.

See also
  object, NOVAS_OBJECT_TYPES

Enumerator

NOVAS_PLANET

A major planet, or else the Sun, the Moon, or the Solar-System Barycenter (SSB).

See also
  make_planet(), enum novas_planet, novas_planet_provider, novas_planet_provider_hp

NOVAS_EPHEM_OBJECT

A Solar-system body that does not fit the major planet type, and requires specific user-provided novas_ephem_provider implementation.

See also
  make_ephem_object(), novas_ephem_provider

NOVAS_CATALOG_OBJECT

Any non-solar system object that may be handled via 'catalog' coordinates, such as a star or a quasar.

See also
  make_cat_object_sys(), make_redshifted_object_sys(), cat_entry

NOVAS_ORBITAL_OBJECT

Any Solar-system body, whose position is determined by a set of orbital elements.

Since
  1.2

See also
  make_orbital_object(), novas_orbital

## novas_planet

enum novas_planet

Enumeration for the 'major planet' numbers in NOVAS to use as the solar-system body number whenever the object type is NOVAS_PLANET.

See also
  make_planet(), NOVAS_PLANET, NOVAS_PLANETS, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANET_RADII_INIT

Enumerator
NOVAS_SSB | Solar-system barycenter position ID.
NOVAS_MERCURY | Major planet number for Mercury in NOVAS.
NOVAS_VENUS | Major planet number for Venus in NOVAS.
NOVAS_EARTH | Major planet number for Earth in NOVAS.
NOVAS_MARS | Major planet number for Mars in NOVAS.
NOVAS_JUPITER | Major planet number for Jupiter in NOVAS.
NOVAS_SATURN | Major planet number for Saturn in NOVAS.
NOVAS_URANUS | Major planet number for Uranus in NOVAS.
NOVAS_NEPTUNE | Major planet number for Neptune in NOVAS.
NOVAS_PLUTO | Major planet number for Pluto in NOVAS.
NOVAS_SUN | Numerical ID for the Sun in NOVAS.
NOVAS_MOON | Numerical ID for the Moon in NOVAS.

NOVAS_EMB

NOVAS ID for the Earth-Moon Barycenter (EMB).

Since
  1.2

NOVAS_PLUTO_BARYCENTER

NOVAS ID for the barycenter of the Pluto System.

Since
  1.2

## novas_reference_plane

enum novas_reference_plane

The plane in which values, such as orbital parameters are referenced.

Author
  Attila Kovacs

Since
  1.2

See also
  novas_orbital_system

Enumerator
NOVAS_ECLIPTIC_PLANE | the plane of the ecliptic
NOVAS_EQUATORIAL_PLANE | the plane of the equator

## novas_transform_type

enum novas_transform_type

The types of coordinate transformations available for transform_cat().

See also
  transform_cat(), make_cat_object_sys(), make_redshifted_object_sys(), NOVAS_TRANSFORM_TYPES

Enumerator
PROPER_MOTION | Updates the star's data to account for the star's space motion between the first and second dates, within a fixed reference frame.
PRECESSION | applies a rotation of the reference frame corresponding to precession between the first and second dates, but leaves the star fixed in space.
CHANGE_EPOCH | The combined equivalent of PROPER_MOTION and PRECESSION together.
CHANGE_J2000_TO_ICRS | A fixed rotation about very small angles (<0.1 arcsecond) to take data from the dynamical system of J2000.0 to the ICRS.
CHANGE_ICRS_TO_J2000 | The inverse transformation of J2000_TO_ICRS.

## 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 dec, novas_init_cat_entry(), novas_set_catalog(), novas_set_parallax(), novas_set_proper_motion(), novas_set_ssb_vel(), and ra.

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

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

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

## 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 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 dec, novas_init_cat_entry(), novas_set_catalog(), novas_set_redshift(), and ra.

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 dec, make_cat_object(), make_redshifted_cat_entry(), novas_object::orbit, and ra.

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 dec, make_redshifted_object(), novas_object::orbit, ra, and novas_object::star.

## naif_to_novas_planet()

enum novas_planet naif_to_novas_planet | ( | long | id | ) |

Converts a NAIF ID to a NOVAS major planet ID.

It account for the different IDs used for Sun, Moon, SSB, EMB and the Pluto system. Otherwise NAIF planet barycenters are mapped to the corresponding bodies. NAIF body centers n_99 (e.g. 399 for Earth) are mapped to the corresponding NOVAS planet number _n. All other NAIF IDs will return -1, indicating no match to a NOVAS planet ID.

Parameters

  id | The NAIF ID of the major planet of interest

Returns
  the NOVAS ID for the same object (which may or may not be different from the input), or -1 if the NAIF ID cannot be matched to a NOVAS major planet.

Author
  Attila Kovacs

Since
  1.2

See also
  novas_to_naif_planet(), novas_to_dexxx_planet()

References NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

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

int novas_equals_cat_entry | ( | const cat_entry * | a,
|  | const cat_entry * | b )

Checks if two catalog entries define the same parameters, within the typical tolerances associated to these.

For two catalog entries to be equals, they must have matching

- names (case sensitive)
- catalog IDs (case sensitive)
- numerical IDs
- coordinates within 1 μas.
- proper motions to within 1 μas / century.
- parallaxes to within 1 ppm of their geometric mean.
- radial velocities to withing 1 mm/s.

NOTES:

- Two NULL (undefined) catalog entries are considered not equal.
- A catalog entry structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one of the catalog entries
  b | another catalog entry

Returns
  TRUE (1) if the two catalog entries define the same sidereal source effectively, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_object()

References novas_cat_entry::catalog, novas_cat_entry::dec, novas_cat_entry::parallax, novas_cat_entry::promodec, novas_cat_entry::promora, novas_cat_entry::ra, novas_cat_entry::radialvelocity, SIZE_OF_CAT_NAME, SIZE_OF_OBJ_NAME, novas_cat_entry::starname, and novas_cat_entry::starnumber.

Referenced by novas_equals_object().

## novas_equals_object()

int novas_equals_object | ( | const object * | a,
|  | const object * | b )

Checks if two astronomical targets are the same within typical tolerances.

Two targets are considered equals only if their types, names (case sensitive), numerical IDs, and defining parameters match within typical tolerances.

NOTES:

- Two NULL (undefined) objects are considered not equal.
- An astronomical target structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | an astronomical target
  b | another astronomical target

Returns
  TRUE (1) if the two targets are effectively the same, within tolerances, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

References novas_object::name, NOVAS_CATALOG_OBJECT, NOVAS_EPHEM_OBJECT, novas_equals_cat_entry(), novas_equals_orbital(), NOVAS_ORBITAL_OBJECT, NOVAS_PLANET, novas_object::number, novas_object::orbit, SIZE_OF_OBJ_NAME, novas_object::star, and novas_object::type.

## novas_equals_orbital()

int novas_equals_orbital | ( | const novas_orbital * | a,
|  | const novas_orbital * | b )

Checks if two Keplerian orbitals match, within typical tolerances.

For two orbitals to be considered equal, they must have matching orbital systems, have the same reference dates to within ~10 ms (see novas_time_equals()), and:

- angular parameters must match to within 1 μas.
- semi-major axis must match to within 1 m.
- eccentricity must match to within 10-12 time the geometric mean of the two semi-major axes.
- mean motion must match to within 1 μas / cy.
- apsis and node periods must match to within ~10 ms (see novas_time_equals())

NOTES:

- Two NULL (undefined) orbitals are considered not equal.
- Sn orbital elements structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one set of Keplerian orbital parameters
  b | another set of Keplerian orbital parameters

Returns
  TRUE (1) if the two Keplerian orbitals are effectively the same, within tolerances, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_object()

References novas_orbital::a, novas_orbital::apsis_period, novas_orbital::e, novas_orbital::i, novas_orbital::jd_tdb, novas_orbital::M0, novas_orbital::n, novas_orbital::node_period, NOVAS_AU, novas_equals_orbsys(), novas_orbital::Omega, novas_orbital::omega, and novas_orbital::system.

Referenced by novas_equals_object().

## novas_equals_orbsys()

int novas_equals_orbsys | ( | const novas_orbital_system * | a,
|  | const novas_orbital_system * | b )

Checks if two orbital systems match within typical tolerances.

Two orbital system are considered equal, if they are defined with respect to the same reference plane, around the same major planet (or Solar-system position), and have the obliquity and ascending node (if obliquity is non-zero) to within 1 μas.

NOTES:

- Two NULL (undefined) orbital systems are considered not equal.
- An orbital system structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one of the orbital systems
  b | another orbital system

Returns
  TRUE (1) if the two systems are effectively the same, within tolerances, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_orbital(), novas_equals_object()

References novas_orbital_system::center, novas_orbital_system::obl, novas_orbital_system::Omega, novas_orbital_system::plane, and novas_orbital_system::type.

Referenced by novas_equals_orbital().

## 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 dec, ra, and SIZE_OF_OBJ_NAME.

Referenced by make_cat_entry(), and make_redshifted_cat_entry().

## novas_make_moon_mean_orbit()

int novas_make_moon_mean_orbit | ( | double | jd_tdb,
|  | novas_orbital *restrict | orbit )

Gets mean orbital elements for the Moon relative to the geocenter for the specified epoch of observation.

It is based on the secular parameters of the ELP2000-85 model, not including the harmonic series the perturbation terms. As such it has accuracy at the few degrees level only, however it is 'valid' for long-term projections (i.e. for years around the orbit's reference epoch) at that coarse level.

For the short-term , novas_make_moon_orbit() can provide somewhat more accurate predictions for up to a day or so around the reference epoch of the orbit.

NOTES:

1. The Moon's orbit is strongly non Keplerian due to the tidal distortions (esp. by the Sun), hence any attempt to describe it it purely Keplerian terms is inherently flawed. If you want to calculate the Moon's position (and/or velocity) with some precision, without using ephemerides, you should probably use the ELP2000/MPP02 model provided by novas_moon_elp_posvel() and novas_moon_elp_sky_pos().

REFERENCES:

1. Chapront, J. et al., 2002, A&A 387, 700–709
2. Chapront-Touze, M, and Chapront, J. 1988, Astronomy and Astrophysics, vol. 190, p. 342-352.
3. Chapront J., & Francou G., 2003, A&A, 404, 735
4. Laskar J., 1986, A&A, 157, 59

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian Date.
  [out] | orbit | Orbital elements data structure to populate.

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

Since
  1.4

Author
  Attila Kovacs

See also
  novas_make_moon_orbit(), novas_make_planet_orbit(), make_orbital_object()
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()

References NOVAS_AU, NOVAS_EARTH, NOVAS_ECLIPTIC_PLANE, NOVAS_J2000, NOVAS_JD_J2000, NOVAS_ORBIT_INIT, and TWOPI.

Referenced by novas_make_moon_orbit().

## novas_make_moon_orbit()

int novas_make_moon_orbit | ( | double | jd_tdb,
|  | novas_orbital *restrict | orbit )

Gets an approximation of the current Keplerian orbital elements for the Moon relative to the geocenter for the specified epoch of observation.

The orbit includes the most dominant Solar perturbation terms to produce results with an accuracy at the few arcmin level near (+- 0.5 days) the reference time argument of the orbit. The perturbed orbit is based on the ELP/MPP02 model.

While, the ELP/MPP02 model itself can be highly precise, the Moon's orbit is strongly non-Keplerian, and so any attempt to describe it in purely Keplerian terms is inherently flawed, which is the reason for the generally poor accuracy of this model.

REFERENCES:

1. Chapront, J. et al., 2002, A&A 387, 700–709
2. Chapront-Touze, M, and Chapront, J. 1988, Astronomy and Astrophysics, vol. 190, p. 342-352.
3. Chapront J., Francou G., 2003, A&A, 404, 735

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian Date.
  [out] | orbit | Orbital elements data structure to populate.

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

Since
  1.5.1

Author
  Attila Kovacs

See also
  novas_make_moon_mean_orbit(), novas_make_planet_orbit(), make_orbital_object()
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos()

References novas_delaunay_args::D, novas_delaunay_args::F, novas_delaunay_args::l, novas_delaunay_args::l1, NOVAS_AU, NOVAS_JD_J2000, NOVAS_KM, and novas_make_moon_mean_orbit().

Referenced by novas_approx_heliocentric().

## novas_make_planet_orbit()

int novas_make_planet_orbit | ( | enum novas_planet | id,
|  | double | jd_tdb,
|  | novas_orbital *restrict | orbit )

Get approximate current heliocentric orbital elements for the major planets.

These orbital elements are not suitable for precise position velocity calculations, but they may be useful to obtain approximate positions for the major planets, e.g. to estimate rise or set times, or apparent elevation angles from an observing site.

These orbitals can provide planet positions to arcmin-level precision for the rocky inner planets, and to a fraction of a degree precision for the gas and ice giants and Pluto. The accuracies for Uranus, Neptune, and Pluto are significantly improved (to the arcmin level) if used in the time range of 1800 AD to 2050 AD. For a more detailed summary of the typical accuracies, see either of the references below.

NOTES:

1. The Earth-Moon system is treated as a single orbital of the Earth-Moon Barycenter (EMB). That is, the EMB orbital is returned for both Earth and the Moon also.
2. For Pluto, the Pluto system barycenter orbit is returned.

REFERENCES:

1. E.M. Standish and J.G. Williams 1992.
2. https://ssd.jpl.nasa.gov/planets/approx_pos.html

Parameters

  | id | NOVAS major planet ID. All major planets, except Earth, are supported. The Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported also. (For Pluto, the Pluto System Barycenter values are returned.)
  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian Date.
  [out] | orbit | Orbital elements data structure to populate.

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

Since
  1.4

Author
  Attila Kovacs

See also
  novas_make_moon_orbit(), novas_approx_sky_pos(), novas_approx_heliocentric(), make_orbital_object()

Keplerian orbital elements at J2000 from Table 8.10.2 of E.M. Standish and J.G. Williams 1992, valid for 1800 AD to 2050 AD.

Temporal evolution of the Keplerian orbital elements from Table 8.10.2 of E.M. Standish and J.G. Williams 1992, valid for 1800 AD to 2050 AD.

Keplerian orbital elements at J2000 from Table 8.10.3 of E.M. Standish and J.G. Williams 1992, valid for 3000 BC to 3000 AD.

Temporal evolution of the Keplerian orbital elements from Table 8.10.3 of E.M. Standish and J.G. Williams 1992, vaid for 3000 BC to 3000 AD.

Additional terms for computing M for the outer planets (Jupiter and beyond) from Table 8.10.4 of E.M. Standish and J.G. Williams 1992.

References NOVAS_EARTH, NOVAS_EMB, NOVAS_JD_J2000, NOVAS_JUPITER, NOVAS_ORBIT_INIT, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, and TWOPI.

Referenced by novas_approx_heliocentric(), and novas_moon_phase().

## novas_orbit_posvel()

int novas_orbit_posvel | ( | double | jd_tdb,
|  | const novas_orbital *restrict | orbit,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | pos,
|  | double *restrict | vel )

Calculates a rectangular equatorial position and velocity vector for the given orbital elements for the specified time of observation.

REFERENCES:

1. E.M. Standish and J.G. Williams 1992.
2. https://ssd.jpl.nasa.gov/planets/approx_pos.html
3. https://en.wikipedia.org/wiki/Orbital_elements
4. https://orbitalofficial.com/
5. https://downloads.rene-schwarz.com/download/M001-Keplerian_Orbit_Elements_to_Cartesian_State_Vectors.pdf

Parameters

  | jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date
  | orbit | Orbital parameters
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
  [out] | pos | [AU] Output ICRS equatorial position vector around orbital center, or NULL if not required.
  [out] | vel | [AU/day] Output ICRS equatorial velocity vector rel. to orbital center, or NULL if not required.

Returns
  0 if successful, or else -1 if the orbital parameters are NULL, or if the position and velocity output vectors are the same or the orbital system is ill defined (errno set to EINVAL), or if the calculation did not converge (errno set to ECANCELED).

Author
  Attila Kovacs

Since
  1.2

See also
  novas_geom_posvel(), ephemeris(), make_orbital_object()

References novas_orbit_native_posvel().

Referenced by ephemeris(), and novas_approx_heliocentric().

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

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

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

## novas_set_orbsys_pole()

int novas_set_orbsys_pole | ( | enum novas_reference_system | type,
|  | double | ra,
|  | double | dec,
|  | novas_orbital_system *restrict | sys )

Sets the orientation of an orbital system using the RA and DEC coordinates of the pole of the Laplace (or else equatorial) plane relative to which the orbital elements are defined.

Orbital parameters of planetary satellites normally include the R.A. and declination of the pole of the local Laplace plane in which the Keplerian orbital elements are referenced.

The system will become referenced to the equatorial plane, the relative obliquity is set to (90° - dec), while the argument of the ascending node ('Omega') is set to (90° + ra).

NOTES:

1. You should not expect much precision from the long-range orbital approximations for planetary satellites. For applications that require precision at any level, you should rely on appropriate ephemerides, or else on up-to-date short-term orbital elements.

Parameters

  | type | Coordinate reference system in which ra and dec are defined (e.g. NOVAS_GCRS).
  | ra | [h] the R.A. of the pole of the orbital reference plane.
  | dec | [deg] the declination of the pole of the oribtal reference plane.
  [out] | sys | Orbital system

Returns
  0 if successful, or else -1 (errno will be set to EINVAL) if the output sys pointer is NULL.

Author
  Attila Kovacs

Since
  1.2

See also
  make_orbital_object()

References dec, NOVAS_EQUATORIAL_PLANE, NOVAS_TIRS, and ra.

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

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

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

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

## novas_to_dexxx_planet()

long novas_to_dexxx_planet | ( | enum novas_planet | id | ) |

Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID for DExxx ephemeris files.

The DExxx (e.g. DE440) ephemeris files use NAIF IDs, but for most planets contain barycentric data only rather than that of the planet center. For Earth-based observations, it only really makes a difference whether the 3 is used for the Earth-Moon Barycenter (EMB) or 399 for the geocenter.

Parameters

  id | The NOVAS ID of the major planet of interest

Returns
  the NAIF ID for the same object (which may or may not be different from the input), as appropriate for use in the DExxx ephemeris files.

Author
  Attila Kovacs

Since
  1.2

See also
  novas_to_naif_planet(), naif_to_novas_planet()

References NOVAS_EARTH, NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

## novas_to_naif_planet()

long novas_to_naif_planet | ( | enum novas_planet | id | ) |

Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID.

NOVAS and NAIF use slightly different IDs for major planets, the Moon, SSB, EMB, and the Pluto system. In NOVAS, major planets are have IDs ranging from 1 through 9, but for NAIF 1–9 are the planetary barycenters and the planet centers have numbers in the hundreds ending with 99 (e.g. the center of Earth is NAIF 399; 3 is the NOVAS ID for Earth and the NAIF ID for the Earth-Moon Barycenter [EMB]). The Sun and Moon also have distinct IDs in NAIF vs NOVAS.

Parameters

  id | The NOVAS ID of the major planet of interest

Returns
  the NAIF ID for the same object or planet center (which may or may not be different from the input)

Author
  Attila Kovacs

Since
  1.2

See also
  naif_to_novas_planet()

References NOVAS_EMB, NOVAS_MERCURY, NOVAS_MOON, NOVAS_PLUTO, NOVAS_PLUTO_BARYCENTER, NOVAS_SSB, and NOVAS_SUN.

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

References out.

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 CHANGE_EPOCH, CHANGE_ICRS_TO_J2000, CHANGE_J2000_TO_ICRS, frame_tie(), ICRS_TO_J2000, in, J2000_TO_ICRS, NOVAS_C, NOVAS_JD_J2000, NOVAS_KMS, novas_los_to_xyz(), novas_vlen(), novas_xyz_to_los(), out, PRECESSION, precession(), PROPER_MOTION, radec2vector(), SIZE_OF_CAT_NAME, and SIZE_OF_OBJ_NAME.

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