Loading...
Searching...
No Matches
novas.h File Reference

SuperNOVAS types, definitions, and function prototypes. More...

## Classes

struct | novas_cat_entry
| Basic astrometric data for any sidereal object located outside the solar system. More...
struct | novas_delaunay_args
| Fundamental Delaunay arguments of the Sun and Moon, from Simon section 3.4(b.3). More...
struct | novas_eop
| Earth Orienation Parameters (EOP), such as obtained from IERS. More...
struct | novas_frame
| A set of parameters that uniquely define the place and time of observation. More...
struct | novas_in_space
| data for an observer's location on Earth orbit More...
struct | novas_matrix
| A 3x3 matrix for coordinate transformations. More...
struct | novas_object
| Celestial object of interest. More...
struct | novas_observable
| Spherical and spectral coordinate set. More...
struct | novas_observer
| Observer location. More...
struct | novas_on_surface
| Data for an observer's location on the surface of the Earth, and optional local weather data for refraction calculations only. 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...
struct | novas_planet_bundle
| Position and velocity data for a set of major planets (which may include the Sun and the Moon also). More...
struct | novas_sky_pos
| Celestial object's place on the sky; contains the output from place(). More...
struct | novas_timespec
| A structure, which defines a precise instant of time that can be expressed in any of the astronomical timescales. More...
struct | novas_track
| The spherical and spectral tracking position of a source, and its first and second time derivatives. More...
struct | novas_transform
| A transformation between two astronomical coordinate systems for the same observer location and time. More...

## Macros

#define | ASEC2RAD (DEG2RAD / 3600.0)
| [rad/arcsec] 1 arcsecond in radians
#define | ASEC360 (360 * 60 * 60)
| [arcsec] Number of arcseconds in 360 degrees.
#define | CAT_ENTRY_INIT
| Initializer for a NOVAS cat_entry structure.
#define | DE405_AU 1.4959787069098932e+11
| [m] Astronomical unit (AU).
#define | DEFAULT_GRAV_BODIES_FULL_ACCURACY ( DEFAULT_GRAV_BODIES_REDUCED_ACCURACY | (1 << NOVAS_JUPITER) | (1 << NOVAS_SATURN) )
| Bitwise mask defining a default set of gravitating bodies to use for deflection calculations in full accuracy mode.
#define | DEFAULT_GRAV_BODIES_REDUCED_ACCURACY ( (1 << NOVAS_SUN) )
| Bitwise mask defining a default set of gravitating bodies to use for deflection calculations in reduced accuracy mode.
#define | DEG2RAD (M_PI / 180.0)
| [rad/deg] 1 degree in radians
#define | IN_SPACE_INIT
| Initializer for a NOVAS in_space structure.
#define | M_PI 3.14159265358979323846
| Definition of π in case it's not defined in math.h.
#define | NOVAS_ARCMIN (NOVAS_DEGREE / 60.0)
| [rad] An arc minute expressed in radians.
#define | NOVAS_ARCSEC (NOVAS_ARCMIN / 60.0)
| [rad] An arc second expressed in radians.
#define | NOVAS_AU 1.495978707e+11
| [m] Astronomical unit (AU).
#define | NOVAS_AU_KM ( 1e-3 * NOVAS_AU )
| [km] Astronomical Unit (AU) in kilometers.
#define | NOVAS_AU_PER_DAY ( NOVAS_AU / NOVAS_DAY )
| [m/s] 1 AU / day
#define | NOVAS_AU_SEC ( NOVAS_AU / NOVAS_C )
| [s] Light-time for one astronomical unit (AU) in seconds.
#define | NOVAS_BESSELIAN_YEAR_DAYS 365.242198781
| [day] The length of a Besselian year in days.
#define | NOVAS_C 299792458.0
| [m/s] Speed of light in meters/second is a defining physical constant.
#define | NOVAS_C_AU_PER_DAY ( NOVAS_C * NOVAS_DAY / NOVAS_AU )
| [AU/day] Speed of light in units of AU/day.
#define | NOVAS_DAY 86400.0
| [s] The length of a synodic day, that is 24 hours exactly.
#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_DEFAULT_WAVELENGTH 0.55
| [μm] Default wavelength, for wavelength-dependent refraction models.
#define | NOVAS_DEGREE (M_PI / 180.0)
| [rad] A degree expressed in radians.
#define | NOVAS_DELAUNAY_ARGS_INIT
| Empty initializer for novas_delaunay_args.
#define | NOVAS_EARTH_ANGVEL 7.2921150e-5
| [rad/s] Rotational angular velocity of Earth from IERS Conventions (2003).
#define | NOVAS_EARTH_FLATTENING NOVAS_GRS80_FLATTENING
| [m] Earth ellipsoid flattening (ITRF / GRS80_MODEL)
#define | NOVAS_EARTH_INIT
| object initializer for the planet Earth
#define | NOVAS_EARTH_RADIUS NOVAS_GRS80_RADIUS
| [m] Equatorial radius of Earth (ITRF / GRS80 model)
#define | NOVAS_EMB_INIT
| object initializer for the Earth-Moon Barycenter (EMB)
#define | NOVAS_EQUATOR_TYPES
| The number of equator types defined in enum novas_equator_type.
#define | NOVAS_FRAME_INIT
| Empty initializer for novas_frame.
#define | NOVAS_G_EARTH 3.98600435507e14
| [m3/s2] Geocentric gravitational constant (GMearth) from DE440, see Park et al., AJ, 161, 105 (2021)
#define | NOVAS_G_SUN 1.32712440041279419e20
| [m3/s2] Heliocentric gravitational constant (GMsun) from DE440, see Park et al., AJ, 161, 105 (2021)
#define | NOVAS_GPS_TO_TAI 19.0
| [s] TAI - GPS time offset
#define | NOVAS_GRS80_FLATTENING (1.0 / 298.257222101)
| [m] GRS80 Earth flattening
#define | NOVAS_GRS80_RADIUS 6378137.0
| [m] Equatorial radius of the WGS84 reference ellipsoid.
#define | NOVAS_HOURANGLE (M_PI / 12.0)
| [rad] An hour of angle expressed in radians.
#define | NOVAS_ID_TYPES
| Number of different Solar-system body ID types enumerated.
#define | NOVAS_IERS_EARTH_FLATTENING (1.0 / 298.25642)
| [m] Earth ellipsoid flattening from IERS Conventions (2003).
#define | NOVAS_IERS_EARTH_RADIUS 6378136.6
| [m] Equatorial radius of Earth in meters from IERS Conventions (2003).
#define | NOVAS_INVALID_LEAP
| Leap seconds value to indicate invalid data.
#define | NOVAS_JD_B1900 2415020.31352
| [day] Julian date at B1900 (NASA / NAIF SPICE definition) precession(), transform_cat()
#define | NOVAS_JD_B1950 2433282.42345905
| [day] Julian date at B1950 (NASA / NAIF SPICE definition) precession(), transform_cat()
#define | NOVAS_JD_HIP 2448349.0625
| [day] Julian date for J1991.25, which the Hipparcos catalog is referred to.
#define | NOVAS_JD_J2000 2451545.0
| [day] Julian date at J2000
#define | NOVAS_JD_MJD0 2400000.5
| [day] Julian date at which the Modified Julian Date (MJD) is zero
#define | NOVAS_JD_START_GREGORIAN 2299160.5
| [day] The Julian day the Gregorian calendar was introduced in 15 October 1582.
#define | NOVAS_JULIAN_YEAR_DAYS 365.25
| [day] The length of a Julian year (at J2000) in days.
#define | NOVAS_JUPITER_INIT
| object initializer for the planet Jupiter
#define | NOVAS_KM 1000.0
| [m] A kilometer (km) in meters.
#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_MAJOR_VERSION 3
| Major version of NOVAS on which this library is based.
#define | NOVAS_MARS_INIT
| object initializer for the planet Mars
#define | NOVAS_MATRIX_IDENTITY
| novas_matrix initializer for an identity matrix.
#define | NOVAS_MATRIX_INIT
| Empty initializer for novas_matrix.
#define | NOVAS_MERCURY_INIT
| object initializer for the planet Mercury
#define | NOVAS_MINOR_VERSION 1
| Minor version of NOVAS on which this library is based.
#define | NOVAS_MOON_INIT
| object initializer for the Moon
#define | NOVAS_NEPTUNE_INIT
| object initializer for the planet Neptune
#define | NOVAS_NUM_EOP_SERIES
| Number of Earth Orientation Parameter Data series handled by SuperNOVAS.
#define | NOVAS_OBJECT_INIT
| Empty object initializer.
#define | NOVAS_OBJECT_TYPES
| The number of object types distinguished by NOVAS.
#define | NOVAS_OBSERVABLE_INIT
| Empty initializer for novas_observable.
#define | NOVAS_OBSERVER_PLACES
| The number of observer place types supported.
#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_ORIGIN_TYPES
| The number of different origins for Solar-system ephemeris data available in NOVAS.
#define | NOVAS_PARSEC ( NOVAS_AU / NOVAS_ARCSEC )
| [m] A parsec in meters.
#define | NOVAS_PLANET_BUNDLE_INIT
| Empty initializer for novas_planet_bundle.
#define | NOVAS_PLANET_GRAV_Z_INIT
| Gravitational redshifts for major planets (and Moon and Sun) for light emitted at surface and detected at a large distance away.
#define | NOVAS_PLANET_INIT(num, name)
| object initializer macro for major planets, the Sun, Moon, and barycenters.
#define | NOVAS_PLANET_NAMES_INIT
| String array initializer for Major planet names, matching the enum novas_planet.
#define | NOVAS_PLANET_RADII_INIT
| Array initializer for mean planet radii in meters, matching the enum novas_planet.
#define | NOVAS_PLANETS
| The number of major planets defined in NOVAS.
#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_ELLIPSOIDS
| The total number of reference ellipsoid types known to SuperNOVAS.
#define | NOVAS_REFERENCE_PLANES
| Number of entries in enum novas_reference_plane.
#define | NOVAS_REFERENCE_SYSTEMS
| The number of basic coordinate reference systems in NOVAS.
#define | NOVAS_REFRACTION_MODELS
| The number of built-in refraction models available in SuperNOVAS.
#define | NOVAS_RMASS_INIT
| Reciprocal masses of solar system bodies, from DE-405 (Sun mass / body mass).
#define | NOVAS_SATURN_INIT
| object initializer for the planet Saturn
#define | NOVAS_SOLAR_CONSTANT 1367.0
| [W/m2] The Solar Constant i.e., typical incident Solar power on Earth.
#define | NOVAS_SOLAR_RADIUS 696340000.0
| [m] Solar radius (photosphere)
#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_TAI_TO_TT 32.184
| [s] TT - TAI time offset
#define | NOVAS_TIMESCALES
| The number of astronomical time scales supported.
#define | NOVAS_TIMESPEC_INIT
| Empty initializer for novas_timespec.
#define | NOVAS_TIMESTAMP_LEN 28
| Minimum number of bytes for a timestamp.
#define | NOVAS_TRACK_INIT
| Empty initializer for novas_track.
#define | NOVAS_TRANSFORM_INIT
| Empty initializer for NOVAS_TRANSFORM.
#define | NOVAS_TRANSFORM_TYPES
| The number of coordinate transfor types in NOVAS.
#define | NOVAS_TROPICAL_YEAR_DAYS 365.2421897
| [day] The length of a tropical year (at J2000) in days.
#define | NOVAS_URANUS_INIT
| object initializer for the planet Uranus
#define | NOVAS_VENUS_INIT
| object initializer for the planet Venus
#define | NOVAS_VERSION_STRING str_2(NOVAS_MAJOR_VERSION) "." str_2(NOVAS_MINOR_VERSION)
| The version string of the upstream NOVAS library on which this library is based.
#define | NOVAS_WGS84_FLATTENING (1.0 / 298.257223563)
| [m] WGS84 Earth flattening
#define | NOVAS_WGS84_RADIUS 6378137.0
| [m] Equatorial radius of the WGS84 reference ellipsoid.
#define | NOVAS_WOBBLE_DIRECTIONS
| Number of values in enum novas_wobble_direction.
#define | OBSERVER_INIT
| Empty initializer for observer.
#define | ON_SURFACE_INIT
| Initializer for a NOVAS on_surface data structure.
#define | ON_SURFACE_LOC(lon, lat, alt)
| Initializer for a NOVAS on_surface data structure at a specified geodetic location.
#define | RAD2DEG (1.0 / DEG2RAD)
| [deg/rad] 1 radian in degrees
#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.
#define | SKY_POS_INIT
| Initializer for a NOVAS sky_pos structure.
#define | SUPERNOVAS_MAJOR_VERSION 1
| API major version.
#define | SUPERNOVAS_MINOR_VERSION 7
| API minor version.
#define | SUPERNOVAS_PATCHLEVEL 2
| Integer sub version of the release.
#define | SUPERNOVAS_RELEASE_STRING ""
| Additional release information in version, e.g. "-1", or "-rc1", or empty string "" for releases.
#define | SUPERNOVAS_VERSION_STRING
| The version string for this library.
#define | TWOPI (2.0 * M_PI)
| 2π
#define | UNIX_SECONDS_0UTC_1JAN2000 946684800L
| [s] UNIX time at 0 UTC, 1 Jan 2000.0

## Typedefs

typedef struct novas_cat_entry | cat_entry
| Basic astrometric data for any sidereal object located outside the solar system.
typedef struct novas_in_space | in_space
| data for an observer's location on Earth orbit
typedef struct novas_delaunay_args | novas_delaunay_args
| Fundamental Delaunay arguments of the Sun and Moon, from Simon section 3.4(b.3).
typedef int(* | novas_ephem_provider) (const char *name, long id, double jd_tdb_high, double jd_tdb_low, enum novas_origin *restrict origin, double *restrict pos, double *restrict vel)
| Function to obtain ephemeris data for minor planets, which are not handled by the solarsystem() type calls.
typedef void(* | novas_error_handler) (const char *fmt, va_list args)
| Callback type for the trace / error message handler.
typedef struct novas_frame | novas_frame
| A set of parameters that uniquely define the place and time of observation.
typedef struct novas_matrix | novas_matrix
| A 3x3 matrix for coordinate transformations.
typedef int(* | novas_nutation_provider) (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)
| Function type definition for the IAU 2000 nutation series calculation.
typedef struct novas_observable | novas_observable
| Spherical and spectral coordinate set.
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_planet_bundle | novas_planet_bundle
| Position and velocity data for a set of major planets (which may include the Sun and the Moon also).
typedef short(* | novas_planet_provider) (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters).
typedef short(* | novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters).
typedef struct novas_timespec | novas_timespec
| A structure, which defines a precise instant of time that can be expressed in any of the astronomical timescales.
typedef struct novas_track | novas_track
| The spherical and spectral tracking position of a source, and its first and second time derivatives.
typedef struct novas_transform | novas_transform
| A transformation between two astronomical coordinate systems for the same observer location and time.
typedef struct novas_object | object
| Celestial object of interest.
typedef struct novas_observer | observer
| Observer location.
typedef struct novas_on_surface | on_surface
| Data for an observer's location on the surface of the Earth, and optional local weather data for refraction calculations only.
typedef double(* | RefractionModel) (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
| A function that returns a refraction correction for a given date/time of observation at the given site on earth, and for a given astrometric source elevation.
typedef struct novas_sky_pos | sky_pos
| Celestial object's place on the sky; contains the output from place().

## Enumerations

enum | novas_accuracy { NOVAS_FULL_ACCURACY = 0 , NOVAS_REDUCED_ACCURACY }
| Constants to control the precision of NOVAS nutation calculations. More...
enum | novas_calendar_type { NOVAS_ROMAN_CALENDAR = -1 , NOVAS_ASTRONOMICAL_CALENDAR , NOVAS_GREGORIAN_CALENDAR }
| Constants to disambiguate which type of calendar yo use for interpreting calendar dates. More...
enum | novas_date_format { NOVAS_YMD = 0 , NOVAS_DMY , NOVAS_MDY }
| The general order of date components for parsing. More...
enum | novas_debug_mode { NOVAS_DEBUG_OFF = 0 , NOVAS_DEBUG_ON , NOVAS_DEBUG_EXTRA }
| Settings for 'novas_debug()'. More...
enum | novas_dynamical_type { NOVAS_DYNAMICAL_MOD = 0 , NOVAS_DYNAMICAL_TOD , NOVAS_DYNAMICAL_CIRS }
| Constants that determine the type of dynamical system. More...
enum | novas_eop_series { EOP_LEAP_LIST = 0 , EOP_RAPID_IAU2000 , EOP_C04_IAU2000_0UTC , EOP_C01_IAU2000 }
| Identifier of the IERS EOP series used (or to use). More...
enum | novas_equator_type { NOVAS_MEAN_EQUATOR = 0 , NOVAS_TRUE_EQUATOR , NOVAS_GCRS_EQUATOR }
| Constants that determine the type of equator to be used for the coordinate system. More...
enum | novas_equinox_type { NOVAS_MEAN_EQUINOX = 0 , NOVAS_TRUE_EQUINOX }
| The type of equinox used in the pre IAU 2006 (old) methodology. More...
enum | novas_frametie_direction { J2000_TO_ICRS = -1 , ICRS_TO_J2000 }
| Direction constant to use for frame_tie(), to determine the direction of transformation between J2000 and ICRS coordinates. More...
enum | novas_id_type { NOVAS_ID_NAIF = 0 , NOVAS_ID_CALCEPH }
| Solar-system body IDs to use as object.number with ephemeris source types. More...
enum | novas_nutation_direction { NUTATE_TRUE_TO_MEAN = -1 , NUTATE_MEAN_TO_TRUE }
| Direction constant for nutation(), between mean and true equatorial coordinates. More...
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_observer_place { NOVAS_OBSERVER_AT_GEOCENTER = 0 , NOVAS_OBSERVER_ON_EARTH , NOVAS_OBSERVER_IN_EARTH_ORBIT , NOVAS_AIRBORNE_OBSERVER , NOVAS_SOLAR_SYSTEM_OBSERVER }
| Types of places on and around Earth that may serve as a reference position for the observation. More...
enum | novas_origin { NOVAS_BARYCENTER = 0 , NOVAS_HELIOCENTER }
| The origin of the ICRS system for referencing positions and velocities for solar-system bodies. 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_ellipsoid { NOVAS_GRS80_ELLIPSOID = 0 , NOVAS_WGS84_ELLIPSOID , NOVAS_IERS_1989_ELLIPSOID , NOVAS_IERS_2003_ELLIPSOID }
| Type of Earth reference ellipsoid. 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_reference_system { NOVAS_GCRS = 0 , NOVAS_TOD , NOVAS_CIRS , NOVAS_ICRS , NOVAS_J2000 , NOVAS_MOD , NOVAS_TIRS , NOVAS_ITRS }
| The basic types of positional coordinate reference systems supported by SuperNOVAS. More...
enum | novas_refraction_model { NOVAS_NO_ATMOSPHERE = 0 , NOVAS_STANDARD_ATMOSPHERE , NOVAS_WEATHER_AT_LOCATION , NOVAS_RADIO_REFRACTION , NOVAS_WAVE_REFRACTION }
| Constants that determine whether what model (if any) to use for implicit refraction calculations. More...
enum | novas_refraction_type { NOVAS_REFRACT_OBSERVED = -1 , NOVAS_REFRACT_ASTROMETRIC }
| The type of elevation value for which to calculate a refraction. More...
enum | novas_separator_type { NOVAS_SEP_COLONS = 0 , NOVAS_SEP_SPACES , NOVAS_SEP_UNITS , NOVAS_SEP_UNITS_AND_SPACES }
| Separator type to use for broken-down time/angle string representations in HMS/DMS formats. More...
enum | novas_timescale { NOVAS_TCB = 0 , NOVAS_TDB , NOVAS_TCG , NOVAS_TT , NOVAS_TAI , NOVAS_GPS , NOVAS_UTC , NOVAS_UT1 }
| Constants to reference various astronomical timescales used. 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...
enum | novas_wobble_direction { WOBBLE_ITRS_TO_TIRS = 0 , WOBBLE_TIRS_TO_ITRS , WOBBLE_ITRS_TO_PEF , WOBBLE_PEF_TO_ITRS }
| Direction constants for polar wobble corrections via the wobble() function. More...

## Functions

int | aberration (const double *pos, const double *vobs, double lighttime, double *out)
| Corrects position vector for aberration of light.
double | accum_prec (double t)
| Returns the general precession in longitude (Simon et al.
short | app_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
| reference_system: TOD observer location: geocenter position_type: apparent
short | app_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
| reference_system: TOD observer location: geocenter position_type: apparent
double | app_to_cirs_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
| Converts an apparent right ascension coordinate (measured from the true equinox of date) to a CIRS R.A., measured from the CIO.
short | astro_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
| reference_system: ICRS / GCRS observer location: geocenter position_type: geometric
short | astro_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
| reference_system: ICRS / GCRS observer location: geocenter position_type: geometric
int | bary2obs (const double *pos, const double *pos_obs, double *out, double *restrict lighttime)
| Moves the origin of coordinates from the barycenter of the solar system to the observer (or the geocenter); i.e., this function accounts for parallax (annual+geocentric or just annual).
int | cal_date (double tjd, short *restrict year, short *restrict month, short *restrict day, double *restrict hour)
| This function will compute a broken down date on the astronomical calendar given the Julian day input.
short | cio_ra (double jd_tt, enum novas_accuracy accuracy, double *restrict ra_cio)
| Computes the true right ascension of the celestial intermediate origin (CIO) vs the equinox of date on the true equator of date for a given TT Julian date.
double | cirs_to_app_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
| Converts a CIRS right ascension coordinate (measured from the CIO) to an apparent R.A.
int | cirs_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) frame at the given epoch to the ICRS / GCRS.
int | cirs_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the dynamical CIRS frame of date to the Earth-fixed ITRS frame (IAU 2000 standard method).
int | cirs_to_tod (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) at the given epoch to the True of Date (TOD) reference system.
double | d_light (const double *pos_src, const double *pos_body)
| Returns the difference in light-time, for a star, between the barycenter of the solar system and the observer (or the geocenter) (Usage A).
int | e_tilt (double jd_tdb, enum novas_accuracy accuracy, double *restrict mobl, double *restrict tobl, double *restrict ee, double *restrict dpsi, double *restrict deps)
| (primarily for internal use) Computes quantities related to the orientation of the Earth's rotation axis at the specified Julian date.
short | earth_sun_calc (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| Provides the position and velocity of the Earth and Sun only at epoch 'jd_tdb' by evaluating a closed-form theory without reference to an external file.
short | earth_sun_calc_hp (const double jd_tdb[restrict 2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| It may provide the position and velocity of the Earth and Sun, the same as earth_sun_calc(), if enable_earth_sun_hp() is set to true (non-zero).
int | ecl2equ (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, double elon, double elat, double *restrict ra, double *restrict dec)
| Convert ecliptic longitude and latitude to right ascension and declination.
short | ecl2equ_vec (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, const double *in, double *out)
| Converts an ecliptic position vector to an equatorial position vector.
void | enable_earth_sun_hp (int value)
| Specify whether the high-precision call is allowed to return a low-precision result.
short | ephemeris (const double *restrict jd_tdb, const object *restrict body, enum novas_origin origin, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
| Retrieves the position and velocity of a solar system body using the currently configured plugins that provide them.
short | equ2ecl (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, double ra, double dec, double *restrict elon, double *restrict elat)
| Convert right ascension and declination to ecliptic longitude and latitude.
short | equ2ecl_vec (double jd_tt, enum novas_equator_type coord_sys, enum novas_accuracy accuracy, const double *in, double *out)
| Converts an equatorial position vector to an ecliptic position vector.
int | equ2gal (double ra, double dec, double *restrict glon, double *restrict glat)
| Converts ICRS right ascension and declination to galactic longitude and latitude.
double | era (double jd_ut1_high, double jd_ut1_low)
| Returns the value of the Earth Rotation Angle (θ) for a given UT1 Julian date.
int | frame_tie (const double *in, enum novas_frametie_direction direction, double *out)
| Transforms a vector from the dynamical reference system to the International Celestial Reference System (ICRS), or vice versa.
int | fund_args (double t, novas_delaunay_args *restrict a)
| Compute the fundamental (a.k.a.
int | gal2equ (double glon, double glat, double *restrict ra, double *restrict dec)
| Converts galactic longitude and latitude to ICRS right ascension and declination.
short | gcrs2equ (double jd_tt, enum novas_dynamical_type sys, enum novas_accuracy accuracy, double rag, double decg, double *restrict ra, double *restrict dec)
| Converts GCRS right ascension and declination to coordinates with respect to the equator of date (mean or true).
int | gcrs_to_cirs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Celestial Intermediate Reference System (CIRS) frame at the given epoch.
int | gcrs_to_j2000 (const double *in, double *out)
| Changes ICRS / GCRS coordinates to J2000 coordinates.
int | gcrs_to_mod (double jd_tdb, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Mean of Date (MOD) reference frame at the given epoch.
int | gcrs_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the True of Date (TOD) reference frame at the given epoch.
short | geo_posvel (double jd_tt, double ut1_to_tt, enum novas_accuracy accuracy, const observer *restrict obs, double *restrict pos, double *restrict vel)
| Computes the geocentric GCRS position and velocity of an observer.
novas_ephem_provider | get_ephem_provider ()
| Returns the user-defined ephemeris accessor function.
novas_nutation_provider | get_nutation_lp_provider ()
| Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().
novas_planet_provider | get_planet_provider ()
| Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.
novas_planet_provider_hp | get_planet_provider_hp ()
| Returns the custom high-precision ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.
double | get_ut1_to_tt (int leap_seconds, double dut1)
| Returns the TT - UT1 time difference given the leap seconds and the actual UT1 - UTC time difference as measured and published by IERS.
double | get_utc_to_tt (int leap_seconds)
| Returns the difference between Terrestrial Time (TT) and Universal Coordinated Time (UTC).
short | grav_def (double jd_tdb, enum novas_observer_place unused, enum novas_accuracy accuracy, const double *pos_src, const double *pos_obs, double *out)
| (primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the major gravitating bodies in the solar system.
int | grav_planets (const double *pos_src, const double *pos_obs, const novas_planet_bundle *restrict planets, double *out)
| (primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the specified gravitating bodies in the solar system.
double | grav_redshift (double M_kg, double r_m)
| Returns the gravitational redshift (z) for light emitted near a massive spherical body at some distance from its center, and observed at some very large (infinite) distance away.
int | grav_undef (double jd_tdb, enum novas_accuracy accuracy, const double *pos_app, const double *pos_obs, double *out)
| (primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the major gravitating bodies in the solar system.
int | grav_undo_planets (const double *pos_app, const double *pos_obs, const novas_planet_bundle *restrict planets, double *out)
| (primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.
int | grav_vec (const double *pos_src, const double *pos_obs, const double *pos_body, double rmass, double *out)
| (primarily for internal use) Corrects position vector for the deflection of light in the gravitational field of anarbitrary body.
int | hor_to_itrs (const on_surface *restrict location, double az, double za, double *restrict itrs)
| Converts astrometric (unrefracted) azimuth and zenith angles at the specified observer location to a unit position vector in the Earth-fixed ITRS frame.
int | iau2000a (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)
| Computes the IAU 2000A high-precision nutation series for the specified date, to 0.1 μas accuracy.
int | iau2000b (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)
| Computes the forced nutation of the non-rigid Earth based at reduced precision.
double | ira_equinox (double jd_tdb, enum novas_equinox_type equinox, enum novas_accuracy accuracy)
| Compute the intermediate right ascension of the equinox at the input Julian date, using an analytical expression for the accumulated precession in right ascension.
int | itrs_to_cirs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the Earth-fixed ITRS frame to the dynamical CIRS frame of date (IAU 2000 standard method).
int | itrs_to_hor (const on_surface *restrict location, const double *restrict itrs, double *restrict az, double *restrict za)
| Converts a position vector in the Earth-fixed ITRS frame to astrometric (unrefracted) azimuth and zenith angles at the specified observer location.
int | itrs_to_tod (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the Earth-fixed ITRS frame to the dynamical True of Date (TOD) frame of date (pre IAU 2000 method).
int | j2000_to_gcrs (const double *in, double *out)
| Change J2000 coordinates to ICRS / GCRS coordinates.
int | j2000_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from J2000 coordinates to the True of Date (TOD) reference frame at the given epoch.
double | julian_date (short year, short month, short day, double hour)
| Returns the Julian day for a given astronomical calendar date.
short | light_time (double jd_tdb, const object *restrict body, const double *pos_obs, double tlight0, enum novas_accuracy accuracy, double *pos_src_obs, double *restrict tlight)
| Computes the geocentric position of a solar system body, as antedated for light-time.
int | light_time2 (double jd_tdb, const object *restrict body, const double *restrict pos_obs, double tlight0, enum novas_accuracy accuracy, double *p_src_obs, double *restrict v_ssb, double *restrict tlight)
| Computes the geocentric position and velocity of a solar system body, as antedated for light-time.
int | limb_angle (const double *pos_src, const double *pos_obs, double *restrict limb_ang, double *restrict nadir_ang)
| Determines the angle of an object above or below the Earth's limb (horizon).
int | make_airborne_observer (const on_surface *location, const double *vel, observer *obs)
| Populates an 'observer' data structure for an observer moving relative to the surface of Earth, such as an airborne observer.
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_gps_observer (double latitude, double longitude, double height, observer *obs)
| Initializes an observer data structure for a ground-based observer with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.
int | make_gps_site (double latitude, double longitude, double height, on_surface *site)
| Initializes an observing site with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.
int | make_in_space (const double *sc_pos, const double *sc_vel, in_space *loc)
| Populates an 'in_space' data structure, for an observer situated on a near-Earth spacecraft, with the provided position and velocity components.
int | make_itrf_observer (double latitude, double longitude, double height, observer *obs)
| Initializes an observer data structure for a ground-based observer with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.
int | make_itrf_site (double latitude, double longitude, double height, on_surface *site)
| Initializes an observing site with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.
int | make_observer_at_geocenter (observer *restrict obs)
| Populates an 'observer' data structure for a hypothetical observer located at Earth's geocenter.
int | make_observer_at_site (const on_surface *restrict site, observer *restrict obs)
| Initializes an observer data structure for a ground-based observer at the specified observing site, and sets mean (annual) weather parameters based on that location.
int | make_observer_in_space (const double *sc_pos, const double *sc_vel, observer *obs)
| Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.
int | make_observer_on_surface (double latitude, double longitude, double height, double temperature, double pressure, observer *restrict obs)
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.
int | make_solar_system_observer (const double *sc_pos, const double *sc_vel, observer *obs)
| Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.
int | make_xyz_site (const double *restrict xyz, on_surface *restrict site)
| Initializes an observing site with the specified Cartesian geocentric xyz location, and sets mean (annual) weather parameters based on that location.
double | mean_obliq (double jd_tdb)
| Computes the mean obliquity of the ecliptic.
short | mean_star (double jd_tt, double tra, double tdec, enum novas_accuracy accuracy, double *restrict ira, double *restrict idec)
| reference system: TOD → ICRS observer location: geocenter → SSB position_type: apparent → geometric
int | mod_to_gcrs (double jd_tdb, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from Mean of Date (MOD) reference frame at the given epoch to the ICRS / GCRS.
enum novas_planet | naif_to_novas_planet (long id)
| Converts a NAIF ID to a NOVAS major planet ID.
int | novas_app_to_geom (const novas_frame *restrict frame, enum novas_reference_system sys, double ra, double dec, double dist, double *restrict geom_icrs)
| Converts an observed apparent sky position of a source to an ICRS geometric position, by undoing the gravitational deflection and aberration corrections.
int | novas_app_to_hor (const novas_frame *restrict frame, enum novas_reference_system sys, double ra, double dec, RefractionModel ref_model, double *restrict az, double *restrict el)
| Converts an observed apparent position vector in the specified coordinate system to local horizontal coordinates in the specified observer frame.
int | novas_approx_heliocentric (enum novas_planet id, double jd_tdb, double *restrict pos, double *restrict vel)
| Returns the approximate geometric heliocentric orbital positions and velocities for the major planets, Sun, or Earth-Moon Barycenter (EMB).
int | novas_approx_sky_pos (enum novas_planet id, const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict out)
| Calculates an approximate apparent location on sky for a major planet, Sun, Moon, Earth-Moon Barycenter (EMB) – typically to arcmin level accuracy – using Keplerian orbital elements.
int | novas_cartesian_to_geodetic (const double *restrict xyz, enum novas_reference_ellipsoid ellipsoid, double *restrict lon, double *restrict lat, double *restrict alt)
| Converts geocentric Cartesian site coordinates to geodetic coordinates on the given reference ellipsoid.
void | novas_case_sensitive (int value)
| Enables or disables case-sensitive processing of the object name.
int | novas_change_observer (const novas_frame *orig, const observer *obs, novas_frame *out)
| Change the observer location for an observing frame.
double | novas_clock_skew (const novas_frame *frame, enum novas_timescale timescale)
| Returns the instantaneous incremental rate at which the observer's clock (i.e.
double | novas_date (const char *restrict date)
| Returns a Julian date (in non-specific timescale) corresponding the specified input string date / time.
double | novas_date_scale (const char *restrict date, enum novas_timescale *restrict scale)
| Returns a Julian date and the timescale corresponding the specified input string date/time and timescale marker.
int | novas_day_of_week (double tjd)
| Returns the one-based ISO 8601 day-of-week index of a given Julian Date.
int | novas_day_of_year (double tjd, enum novas_calendar_type calendar, int *restrict year)
| Returns the one-based day index in the calendar year for a given Julian Date.
void | novas_debug (enum novas_debug_mode mode)
| Enables or disables reporting errors and traces to the standard error stream.
double | novas_diff_tcb (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Barycentric Coordinate Time (TCB) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_tcg (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Geocentric Coordinate Time (TCG) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_time (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Terrestrial Time (TT) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_time_scale (const novas_timespec *t1, const novas_timespec *t2, enum novas_timescale scale)
| Returns the UT1 based time difference (t1 - t2) in days between two astronomical time specifications.
int | novas_diurnal_eop (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict xp, double *restrict yp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides.
int | novas_diurnal_eop_at_time (const novas_timespec *restrict time, double *restrict dxp, double *restrict dyp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides at a given astromtric time.
int | novas_diurnal_libration (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict xp, double *restrict yp, double *restrict dut1)
| Calculate diurnal and semi-diurnal libration corrections to the Earth orientation parameters (EOP) for the non-rigid Earth.
int | novas_diurnal_ocean_tides (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict xp, double *restrict yp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to the ocean tides.
double | novas_dms_degrees (const char *restrict dms)
| Returns the decimal degrees for a DMS string specification.
int | novas_e2h_offset (double dra, double ddec, double pa, double *restrict daz, double *restrict del)
| Converts coordinate offsets, from the local equatorial system to local horizontal offsets.
int | novas_enu_to_itrs (const double *enu, double lon, double lat, double *itrf)
| Converts an East-North-Up (ENU) vector at the specified site to an ITRS vector.
double | novas_epa (double ha, double dec, double lat)
| Returns the Parallactic Angle (PA) calculated for an RA/Dec location of the sky at a given sidereal time.
double | novas_epoch (const char *restrict system)
| Returns the Julian day corresponding to an astronomical coordinate epoch.
int | novas_equ_offset_by (double ra, double dec, double direction, double distance, double *restrict out_ra, double *restrict out_dec)
| Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.
double | novas_equ_sep (double ra1, double dec1, double ra2, double dec2)
| Returns the angular separation of two equatorial locations on a sphere.
int | novas_equ_track (const object *restrict source, const novas_frame *restrict frame, double dt, novas_track *restrict track)
| Calculates true-of-date equatorial tracking position and motion (first and second time derivatives) for the specified source in the given observing frame.
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_frame (const novas_frame *a, const novas_frame *b)
| Checks if two observing frames are essentially the same, within typical tolerances.
int | novas_equals_near_earth (const in_space *a, const in_space *b)
| Checks if two near-Earth locations and motions match within 1 mm and 1 mm/s, respectively.
int | novas_equals_object (const object *a, const object *b)
| Checks if two astronomical targets are the same within typical tolerances.
int | novas_equals_observer (const observer *a, const observer *b)
| Checks if two observers are essentially the same within the tolerances associated to their defining components.
int | novas_equals_on_surface (const on_surface *a, const on_surface *b)
| Checks if two geodetic locations, and the weather parameters defined for them, match.
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_equals_planet_bundle (const novas_planet_bundle *a, const novas_planet_bundle *b)
| Checks if two bundles containing Solar-system baricentric planet positions and velocities are effectively the same.
int | novas_equals_sky_pos (const sky_pos *a, const sky_pos *b)
| Checks if two apparent positions on the observer's sky are the same within typical tolerances.
int | novas_equals_ssb_posvel (const in_space *a, const in_space *b)
| Checks if two Solar-system locations and motions match within 1 m and ~1 mm/s, respectively.
int | novas_equals_timespec (const novas_timespec *a, const novas_timespec *b)
| Checks if two time specifications are the same within 10-7 days (~100 μs).
int | novas_equals_vector (const double *a, const double *b, double tol)
| Checks if two 3D vectors are effectively the same, within the specified absolute tolerance.
int | novas_fetch_eop (double jd, long timeout_millis, novas_eop *eop)
| Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS).
int | novas_fetch_eop_unix (time_t t, long timeout_millis, novas_eop *eop)
| Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS) around the current system time, using the rapid service data (finals.all).
double | novas_frame_lst (const novas_frame *restrict frame)
| Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.
double | novas_gast (double jd_ut1, double ut1_to_tt, enum novas_accuracy accuracy)
| Returns the Greenwich Apparent Sidereal Time (GAST) for a given UT1 date.
int | novas_geodetic_to_cartesian (double lon, double lat, double alt, enum novas_reference_ellipsoid ellipsoid, double *xyz)
| Converts geodetic site coordinates to geocentric Cartesian coordinates, using the specified reference ellipsoid.
int | novas_geodetic_transform_site (enum novas_reference_ellipsoid from_ellipsoid, const on_surface *in, enum novas_reference_ellipsoid to_ellipsoid, on_surface *out)
| Transforms a geodetic location from one reference ellipsoid to another.
int | novas_geom_posvel (const object *restrict source, const novas_frame *restrict frame, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Calculates the geometric position and velocity vectors, relative to the observer, for a source in the given observing frame, in the specified coordinate system of choice.
int | novas_geom_to_app (const novas_frame *restrict frame, const double *restrict pos, enum novas_reference_system sys, sky_pos *restrict out)
| Converts an geometric position in ICRS to an apparent position on sky, by applying appropriate corrections for aberration and gravitational deflection for the observer's frame.
enum novas_debug_mode | novas_get_debug_mode ()
| Returns the current, thread-local, mode for reporting errors encountered (and traces).
int | novas_get_eop_itrf_year (enum novas_eop_series series)
| Returns the ITRF realization year for a given IERS Earth Orientation Parameter (EOP) series.
const char * | novas_get_eop_url (enum novas_eop_series series)
| Returns the URL currently configured for a given IERS Earth Orientation Parameter (EOP) series.
double | novas_get_split_time (const novas_timespec *restrict time, enum novas_timescale timescale, long *restrict ijd)
| Returns the fractional Julian date of an astronomical time in the specified timescale, as an integer and fractional part.
double | novas_get_time (const novas_timespec *restrict time, enum novas_timescale timescale)
| Returns the fractional Julian date of an astronomical time in the specified timescale.
time_t | novas_get_unix_time (const novas_timespec *restrict time, long *restrict nanos)
| Returns the UNIX time for an astronomical time instant.
double | novas_gmst (double jd_ut1, double ut1_to_tt)
| Returns the Greenwich Mean Sidereal Time (GMST) for a given UT1 date, using eq.
int | novas_h2e_offset (double daz, double del, double pa, double *restrict dra, double *restrict ddec)
| Converts coordinate offsets, from the local horizontal system to local equatorial offsets.
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.
double | novas_hms_hours (const char *restrict hms)
| Returns the decimal hours for a HMS string specification.
int | novas_hor_to_app (const novas_frame *restrict frame, double az, double el, RefractionModel ref_model, enum novas_reference_system sys, double *restrict ra, double *restrict dec)
| Converts an observed azimuth and elevation coordinate to right ascension (R.A.) and declination coordinates expressed in the coordinate system of choice.
int | novas_hor_track (const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model, novas_track *restrict track)
| Calculates horizontal tracking position and motion (first and second time derivatives) for the specified source in the given observing frame.
double | novas_hpa (double az, double el, double lat)
| Returns the Parallactic Angle (PA) calculated for a horizontal Az/El location of the sky.
int | novas_icrs_to_sys (const double *in, double jd_tdb, enum novas_accuracy accuracy, enum novas_reference_system sys, double *out)
| Converts a rectangular equatorial vector from the International Coordinate Reference System (ICRS) or equivalent, such as GCRS, to the desired output equatorial coordinate reference system of choice.
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.
double | novas_inv_refract (RefractionModel model, double jd_tt, const on_surface *restrict loc, enum novas_refraction_type type, double el0)
| Computes the reverse atmospheric refraction for a given refraction model.
int | novas_invert_transform (const novas_transform *transform, novas_transform *inverse)
| Inverts a novas coordinate transformation matrix.
int | novas_is_auto_fetch_eop ()
| Checks if automatic fetching of Earth Orientation Parameter values from IERS is allowed.
int | novas_iso_timestamp (const novas_timespec *restrict time, char *restrict dst, int maxlen)
| Prints a UTC-based ISO timestamp to millisecond precision to the specified string buffer.
int | novas_itrf_transform (int from_year, const double *restrict from_coords, const double *restrict from_rates, int to_year, double *to_coords, double *to_rates)
| Converts ITRF coordinates between different realizations of the ITRF coordinate system.
int | novas_itrf_transform_eop (int from_year, double from_xp, double from_yp, double from_dut1, int to_year, double *restrict to_xp, double *restrict to_yp, double *restrict to_dut1)
| Transforms Earth orientation parameters (xp, yp, dUT1) from one ITRF realization to another.
int | novas_itrf_transform_site (int from_year, const on_surface *in, int to_year, on_surface *out)
| Transforms a geodetic location between two International Terrestrial Reference Frame (ITRF) realizations.
int | novas_itrs_to_enu (const double *itrf, double lon, double lat, double *enu)
| Converts an ITRS position vector to a local East-North-Up (ENU) vector at the specified site.
double | novas_jd_from_date (enum novas_calendar_type calendar, int year, int month, int day, double hour)
| Returns the Julian day for a given calendar date.
int | novas_jd_to_date (double tjd, enum novas_calendar_type calendar, int *restrict year, int *restrict month, int *restrict day, double *restrict hour)
| This function will compute a broken down date on the specified calendar for given the Julian day input.
int | novas_lookup_leap (time_t t)
| Returns the leap seconds for the given UNIX timestamp, based either on a locally supplied leap seconds list (see novas_set_leap_list()), or else from data obtained as needed from IERS (provided that fetching it is allowed).
int | novas_los_to_xyz (const double *los, double lon, double lat, double *xyz)
| Converts a 3D line-of-sight vector (δφ, δθ, δr) to a rectangular equatorial (δx, δy, δz) vector.
double | novas_lsr_to_ssb_vel (double epoch, double ra, double dec, double vLSR)
| Returns a Solar System Baricentric (SSB) radial velocity for a radial velocity that is referenced to the Local Standard of Rest (LSR).
int | novas_make_frame (enum novas_accuracy accuracy, const observer *obs, const novas_timespec *time, double xp, double yp, novas_frame *frame)
| Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.
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_make_transform (const novas_frame *frame, enum novas_reference_system from_system, enum novas_reference_system to_system, novas_transform *transform)
| Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.
double | novas_mean_clock_skew (const novas_frame *frame, enum novas_timescale timescale)
| Returns the averaged incremental rate at which the observer's clock (i.e.
double | novas_moon_angle (const object *restrict source, const novas_frame *restrict frame)
| Returns the apparent angular distance of a source from the Moon from the observer's point of view.
int | novas_moon_elp_ecl_pos (double jd_tdb, double limit, double *pos)
| Calculates the Moon's geocentric position using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.
int | novas_moon_elp_ecl_vel (double jd_tdb, double limit, double *vel)
| Calculates the Moon's geocentric velocity using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.
int | novas_moon_elp_posvel (const novas_frame *restrict frame, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_posvel_fp (const novas_frame *restrict frame, double limit, enum novas_reference_system sys, double *restrict pos, double *restrict vel)
| Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_sky_pos (const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict pos)
| Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
int | novas_moon_elp_sky_pos_fp (const novas_frame *restrict frame, double limit, enum novas_reference_system sys, sky_pos *restrict pos)
| Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).
double | novas_moon_phase (double jd_tdb)
| Calculates the Moon's phase at a given time.
double | novas_next_moon_phase (double phase, double jd_tdb)
| Calculates the date / time at which the Moon will reach the specified phase next, after the specified time.
double | novas_norm_ang (double angle)
| Returns the normalized angle in the [0:2π) range.
double | novas_object_sep (const object *source1, const object *source2, const novas_frame *restrict frame)
| Returns the angular separation of two objects from the observer's point of view.
int | novas_offset_by (double lon, double lat, double direction, double distance, double *restrict out_lon, double *restrict out_lat)
| Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.
int | novas_offset_time (const novas_timespec *time, double seconds, novas_timespec *out)
| Increments the astrometric time by a given amount.
double | novas_optical_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
| Returns an optical refraction correction using the weather parameters defined for the observer location.
int | novas_orbit_native_posvel (double jd_tdb, const novas_orbital *restrict orbit, 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, in the native coordinate system in which the orbital is defined (e.g.
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.
double | novas_parse_date (const char *restrict date, char **restrict tail)
| Parses an astronomical date/time string into a Julian date specification.
double | novas_parse_date_format (enum novas_calendar_type calendar, enum novas_date_format format, const char *restrict date, char **restrict tail)
| Parses a calendar date/time string, expressed in the specified type of calendar, into a Julian day (JD).
double | novas_parse_degrees (const char *restrict str, char **restrict tail)
| Parses an angle in degrees from a string that contains either a decimal degrees or else a broken-down DMS representation.
double | novas_parse_dms (const char *restrict str, char **restrict tail)
| Parses the decimal degrees for a DMS string specification.
double | novas_parse_hms (const char *restrict str, char **restrict tail)
| Parses the decimal hours for a HMS string specification.
double | novas_parse_hours (const char *restrict str, char **restrict tail)
| Parses a time or time-like angle from a string that contains either a decimal hours or else a broken-down HMS representation.
double | novas_parse_iso_date (const char *restrict date, char **restrict tail)
| Parses an ISO 8601 timestamp, converting it to a Julian day.
enum novas_timescale | novas_parse_timescale (const char *restrict str, char **restrict tail)
| Parses the timescale from a string containing a standard abbreviation (case insensitive), and returns the updated parse position after the timescale specification (if any).
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_print_dms (double degrees, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
int | novas_print_hms (double hours, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
int | novas_print_timescale (enum novas_timescale scale, char *restrict buf)
| Prints the standard string representation of the timescale to the specified buffer.
double | novas_radio_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
| Atmospheric refraction model for radio wavelengths (Berman & Rockwell 1976).
int | novas_refract_wavelength (double microns)
| Sets the observing wavelength for which refraction is to be calculated when using a wavelength-depenendent model, such as novas_wave_refraction().
void | novas_reset_eop ()
| Releases resources used by URL handles used for obtaining Earth Orientation Parameter (EOP) data from the International Earth Rotation and Reference Systems Service (IERS), including the leap seconds list supplied earlier or obtained from IERS.
double | novas_rises_above (double el, const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model)
| Returns the UTC date at which a distant source appears to rise above the specified elevation angle.
double | novas_sep (double lon1, double lat1, double lon2, double lat2)
| Returns the angular separation of two locations on a sphere.
int | novas_set_auto_fetch_eop (int enabled)
| Disable or Re-enabled the automatic fetching of Earth Orientation Parameter values from IERS, when these are left undefined (NAN) when initializing astrometric time or observing frame instances.
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_current_time (int leap, double dut1, novas_timespec *restrict time)
| Sets the time with the UNIX time obtained from the system clock.
int | novas_set_default_weather (on_surface *site)
| Sets default weather parameters based on an approximate global model to the mean annualized temperatures, based on Feulner et al.
int | novas_set_distance (cat_entry *source, double parsecs)
| Sets the distance for a catalog source.
int | novas_set_eop_url (enum novas_eop_series series, int itrf_year, const char *url)
| Specify a URL to use for a given IERS Earth Orientation Parameter (EOP) series.
novas_error_handler | novas_set_error_handler (novas_error_handler handler)
| Replaces the trace / error message handler.
int | novas_set_leap_list (const char *filename)
| Specifies a local file containing the official leap seconds list, i.e.
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_split_time (enum novas_timescale timescale, long ijd, double fjd, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to the split Julian Date value, defined in the specified timescale.
int | novas_set_ssb_vel (cat_entry *source, double v_kms)
| Sets a radial velocity for a catalog source, defined w.r.t.
int | novas_set_str_time (enum novas_timescale timescale, const char *restrict str, int leap, double dut1, novas_timespec *restrict time)
| Sets astronomical time in a specific timescale using a string specification.
int | novas_set_time (enum novas_timescale timescale, double jd, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to the fractional Julian Date value, defined in the specified timescale.
int | novas_set_unix_time (time_t unix_time, long nanos, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to a UNIX time value.
double | novas_sets_below (double el, const object *restrict source, const novas_frame *restrict frame, RefractionModel ref_model)
| Returns the UTC date at which a distant source appears to set below the specified elevation angle.
int | novas_site_gcrs_posvel (const novas_timespec *restrict ts, const on_surface *restrict site, const double *restrict v_itrs, double xp, double yp, enum novas_accuracy accuracy, double *restrict pos, double *restrict vel)
| Returns precise GCRS position and velocity vectors for an observer located on or near Earth's surface.
int | novas_site_uvw (const novas_timespec *restrict ts, const on_surface *restrict station, const double *restrict geocentric_source, double xp, double yp, enum novas_accuracy accuracy, double *restrict uvw)
| Returns geocentric u,v,w coordinates for a ground-based interferometer station.
int | novas_sky_pos (const object *restrict object, const novas_frame *restrict frame, enum novas_reference_system sys, sky_pos *restrict out)
| Calculates an apparent location on sky for the source.
double | novas_solar_illum (const object *restrict source, const novas_frame *restrict frame)
| Returns the Solar illumination fraction of a source, assuming a spherical geometry for the observed body.
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.
double | novas_ssb_to_lsr_vel (double epoch, double ra, double dec, double vLSR)
| Returns a radial-velocity referenced to the Local Standard of Rest (LSR) for a given Solar-System Barycentric (SSB) radial velocity.
double | novas_standard_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
| Returns an optical refraction correction for a standard atmosphere.
double | novas_str_degrees (const char *restrict dms)
| Returns an angle parsed from a string that contains either a decimal degrees or else a broken-down DMS representation.
double | novas_str_hours (const char *restrict hms)
| Returns a time or time-like angleparsed from a string that contains either a decimal hours or else a broken-down HMS representation.
double | novas_sun_angle (const object *restrict source, const novas_frame *restrict frame)
| Returns the apparent angular distance of a source from the Sun from the observer's point of view.
int | novas_sys_to_icrs (enum novas_reference_system sys, const double *in, double jd_tdb, enum novas_accuracy accuracy, double *out)
| Converts a rectangular equatorial vector from the specified equatorial coordinate reference system of choice to the International Coordinate Reference System (ICRS) or equivalent, such as GCRS.
double | novas_time_gst (const novas_timespec *restrict time, enum novas_accuracy accuracy)
| Returns the Greenwich (apparent) Sidereal Time (GST/GaST) for a given astronomical time specification.
int | novas_time_leap (const novas_timespec *time)
| Returns the leap seconds component of an astronomical time specification.
double | novas_time_lst (const novas_timespec *restrict time, double lon, enum novas_accuracy accuracy)
| Returns the Local (apparent) Sidereal Time (LST/LaST) for a given astronomical time specification and observer location.
enum novas_timescale | novas_timescale_for_string (const char *restrict str)
| Returns the timescale constant for a string that denotes the timescale in with a standard abbreviation (case insensitive).
double | novas_timescale_offset (const novas_timespec *ts, enum novas_timescale timescale, enum novas_timescale ref_scale)
| Returns the time difference between two different timescales at a specific astrometric time instance.
int | novas_timestamp (const novas_timespec *restrict time, enum novas_timescale scale, char *restrict dst, int maxlen)
| Prints an astronomical timestamp to millisecond precision in the specified timescale to the specified string buffer.
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 | novas_track_pos (const novas_track *track, const novas_timespec *time, double *restrict lon, double *restrict lat, double *restrict dist, double *restrict z)
| Calculates a projected position, distance, and redshift for a source, given its near-term trajectory on sky, in the system for which the track was calculated.
int | novas_transform_sky_pos (const sky_pos *in, const novas_transform *restrict transform, sky_pos *out)
| Transforms a position or velocity 3-vector from one coordinate reference system to another.
int | novas_transform_vector (const double *in, const novas_transform *restrict transform, double *out)
| Transforms a position or velocity 3-vector from one coordinate reference system to another.
double | novas_transit_time (const object *restrict source, const novas_frame *restrict frame)
| Returns the UTC date at which a source transits the local meridian.
int | novas_uvw (const double *restrict station_pos, const double *restrict station_vel, const double *restrict phase_center, double *restrict uvw)
| Returns u,v,w coordinates for a space-based interferometer station.
int | novas_uvw_to_xyz (const double *uvw, double ha, double dec, double *xyz)
| Converts equatorial u,v,w projected (absolute or relative) coordinates to rectangular telescope x,y,z coordinates (in PEF) to for a specified line of sight.
double | novas_v2z (double vel)
| Converts a radial recession velocity to a redshift value (z = Δλ / λrest).
double | novas_wave_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
| The wavelength-dependent IAU atmospheric refraction model, based on the SOFA iauRefco() function, in compliance to the 'SOFA Software License' terms of the original source.
int | novas_xyz_to_los (const double *xyz, double lon, double lat, double *los)
| Converts a 3D rectangular equatorial (δx, δy, δz) vector to a polar (δφ, δθ, δr) vector along a line-of-sight.
int | novas_xyz_to_uvw (const double *xyz, double ha, double dec, double *uvw)
| Converts rectangular telescope x,y,z (absolute or relative) coordinates (in PEF) to an equatorial u,v,w projection for a specified line of sight.
double | novas_z2v (double z)
| Converts a redshift value (z = Δλ / λrest) to a radial velocity (i.e.
double | novas_z_add (double z1, double z2)
| Compounds two redshift corrections, e.g.
double | novas_z_inv (double z)
| Returns the inverse of a redshift value, that is the redshift for a body moving with the same velocity as the original but in the opposite direction.
int | nu2000k (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)
int | nutation (double jd_tdb, enum novas_nutation_direction direction, enum novas_accuracy accuracy, const double *in, double *out)
| Nutates equatorial rectangular coordinates from mean equator and equinox of epoch to true equator and equinox of epoch.
int | nutation_angles (double t, enum novas_accuracy accuracy, double *restrict dpsi, double *restrict deps)
| Returns the IAU2000 / 2006 values for nutation in longitude and nutation in obliquity for a given TDB Julian date and the desired level of accuracy.
int | obs_planets (double jd_tdb, enum novas_accuracy accuracy, const double *restrict pos_obs, int pl_mask, novas_planet_bundle *restrict planets)
| Calculates the positions and velocities for the Solar-system bodies, e.g.
int | obs_posvel (double jd_tdb, double ut1_to_tt, enum novas_accuracy accuracy, const observer *restrict obs, const double *restrict geo_pos, const double *restrict geo_vel, double *restrict pos, double *restrict vel)
| Calculates the ICRS position and velocity of the observer relative to the Solar System Barycenter (SSB).
short | place (double jd_tt, const object *restrict source, const observer *restrict location, double ut1_to_tt, enum novas_reference_system coord_sys, enum novas_accuracy accuracy, sky_pos *restrict output)
| Computes the apparent direction of a celestial object at a specified time and in a specified coordinate system and for a given observer location.
int | place_cirs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: CIRS observer location: geocenter position_type: apparent
int | place_gcrs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: ICRS/GCRS observer location: geocenter position_type: apparent
int | place_icrs (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: ICRS / GCRS observer location: geocenter position_type: geometric
int | place_j2000 (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: J2000 observer location: geocenter position_type: apparent
int | place_mod (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: MOD observer location: geocenter position_type: apparent
int | place_star (double jd_tt, const cat_entry *restrict star, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system system, enum novas_accuracy accuracy, sky_pos *restrict pos)
| Computes the apparent place of a star at the specified date, given its catalog mean place, proper motion, parallax, and radial velocity.
int | place_tod (double jd_tt, const object *restrict source, enum novas_accuracy accuracy, sky_pos *restrict pos)
| reference_system: TOD observer location: geocenter position_type: apparent
short | planet_ephem_provider (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.
short | planet_ephem_provider_hp (const double jd_tdb[restrict 2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity)
| Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.
double | planet_lon (double t, enum novas_planet planet)
| Returns the planetary longitude, for Mercury through Neptune, w.r.t.
short | precession (double jd_tdb_in, const double *in, double jd_tdb_out, double *out)
| Precesses equatorial rectangular coordinates from one epoch to another using the IAU2006 (P03) precession model of Capitaine et al.
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 | rad_vel (const object *restrict source, const double *restrict pos_src, const double *vel_src, const double *vel_obs, double d_obs_geo, double d_obs_sun, double d_src_sun, double *restrict rv)
| Predicts the radial velocity of the observed object as it would be measured by spectroscopic means.
double | rad_vel2 (const object *restrict source, const double *pos_emit, const double *vel_src, const double *pos_det, const double *vel_obs, double d_obs_geo, double d_obs_sun, double d_src_sun)
| Predicts the radial velocity of the observed object as it would be measured by spectroscopic means.
int | radec2vector (double ra, double dec, double dist, double *restrict pos)
| Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).
int | radec_planet (double jd_tt, const object *restrict ss_body, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system sys, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis, double *restrict rv)
| Computes the place of a solar system body at the specified time for an observer in the specified coordinate system.
int | radec_star (double jd_tt, const cat_entry *restrict star, const observer *restrict obs, double ut1_to_tt, enum novas_reference_system sys, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict rv)
| Computes the place of a star at date 'jd_tt', for an observer in the specified coordinate system, given the star's ICRS catalog place, proper motion, parallax, and radial velocity.
double | redshift_vrad (double vrad, double z)
| Applies an incremental redshift correction to a radial velocity.
double | refract (const on_surface *restrict location, enum novas_refraction_model model, double zd_obs)
| Computes atmospheric optical refraction for an observed (already refracted!) zenith distance through the atmosphere.
double | refract_astro (const on_surface *restrict location, enum novas_refraction_model model, double zd_astro)
| Computes atmospheric optical refraction for a source at an astrometric zenith distance (e.g.
int | set_ephem_provider (novas_ephem_provider func)
| Sets the function to use for obtaining position / velocity information for minor planets, or satellites.
int | set_nutation_lp_provider (novas_nutation_provider func)
| Set the function to use for low-precision IAU 2000 nutation calculations instead of the default nu2000k().
int | set_planet_provider (novas_planet_provider func)
| Set a custom function to use for regular precision (see NOVAS_REDUCED_ACCURACY) ephemeris calculations instead of the default solarsystem() routine.
int | set_planet_provider_hp (novas_planet_provider_hp func)
| Set a custom function to use for high precision (see NOVAS_FULL_ACCURACY) ephemeris calculations instead of the default solarsystem_hp() routine.
int | spin (double angle, const double *in, double *out)
| Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.
int | starvectors (const cat_entry *restrict star, double *restrict pos, double *restrict motion)
| Converts angular quantities for stars to vectors.
int | tdb2tt (double jd_tdb, double *restrict jd_tt, double *restrict secdiff)
| Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (TDB) Julian date, and returns the TDB-TT time difference also.
int | terra (const on_surface *restrict location, double gast, double *restrict pos, double *restrict vel)
int | tod_to_cirs (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from the True of Date (TOD) reference system to the Celestial Intermediate Reference System (CIRS) at the given epoch to the .
int | tod_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the ICRS / GCRS.
int | tod_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
| Rotates a position vector from the dynamical True of Date (TOD) frame of date the Earth-fixed ITRS frame (pre IAU 2000 method).
int | tod_to_j2000 (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
| Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the J2000 coordinates.
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.
double | tt2tdb (double jd_tt)
| Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 10 μs for dates between 1600 and 2200.
double | tt2tdb_fp (double jd_tt, double limit)
| Returns the TDB-TT time difference with flexible precision.
double | tt2tdb_hp (double jd_tt)
| Returns the TDB-TT time difference with high precision.
double | unredshift_vrad (double vrad, double z)
| Undoes an incremental redshift correction that was applied to radial velocity.
short | vector2radec (const double *restrict pos, double *restrict ra, double *restrict dec)
| Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.
short | virtual_planet (double jd_tt, const object *restrict ss_body, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec, double *restrict dis)
| reference_system: ICRS / GCRS observer location: geocenter position_type: apparent
short | virtual_star (double jd_tt, const cat_entry *restrict star, enum novas_accuracy accuracy, double *restrict ra, double *restrict dec)
| reference_system: ICRS / GCRS observer location: geocenter position_type: apparent
int | wobble (double jd_tt, enum novas_wobble_direction direction, double xp, double yp, const double *in, double *out)
| Corrects a vector in the ITRS (rotating Earth-fixed system) for polar motion, and also corrects the longitude origin (by a tiny amount) to the Terrestrial Intermediate Origin (TIO).

## Variables

int | grav_bodies_full_accuracy
| Current set of gravitating bodies to use for deflection calculations in full accuracy mode.
int | grav_bodies_reduced_accuracy
| Current set of gravitating bodies to use for deflection calculations in reduced accuracy mode.

## Detailed Description

SuperNOVAS types, definitions, and function prototypes.

SuperNOVAS astrometry software based on the Naval Observatory Vector Astrometry Software (NOVAS). It has been modified to fix outstanding issues, make it easier to use, and provide a ton of new features.

Based on the NOVAS C Edition, Version 3.1:

U. S. Naval Observatory
Astronomical Applications Dept.
Washington, DC
http://www.usno.navy.mil/USNO/astronomical-applications

Author
  G. Kaplan and Attila Kovacs

Version
  1.7.2

## Macro Definition Documentation

## ASEC2RAD

#define ASEC2RAD (DEG2RAD / 3600.0)

[rad/arcsec] 1 arcsecond in radians

## ASEC360

#define ASEC360 (360 * 60 * 60)

[arcsec] Number of arcseconds in 360 degrees.

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

## DE405_AU

#define DE405_AU 1.4959787069098932e+11

[m] Astronomical unit (AU).

based on DE-405. (old definition)

See also
  NOVAS_AU

## DEG2RAD

#define DEG2RAD (M_PI / 180.0)

[rad/deg] 1 degree in radians

## IN_SPACE_INIT

#define IN_SPACE_INIT

Initializer for a NOVAS in_space structure.

Since
  1.1.1

Author
  Attila Kovacs

See also
  in_space

Referenced by make_airborne_observer().

## M_PI

#define M_PI 3.14159265358979323846

Definition of π in case it's not defined in math.h.

Referenced by limb_angle(), and novas_cartesian_to_geodetic().

## NOVAS_ARCMIN

#define NOVAS_ARCMIN (NOVAS_DEGREE / 60.0)

[rad] An arc minute expressed in radians.

Since
  1.2

## NOVAS_ARCSEC

#define NOVAS_ARCSEC (NOVAS_ARCMIN / 60.0)

[rad] An arc second expressed in radians.

Since
  1.2

Referenced by cio_array().

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

#define NOVAS_AU_KM ( 1e-3 * NOVAS_AU )

[km] Astronomical Unit (AU) in kilometers.

## NOVAS_AU_PER_DAY

#define NOVAS_AU_PER_DAY ( NOVAS_AU / NOVAS_DAY )

[m/s] 1 AU / day

Since
  1.6

Referenced by novas_moon_elp_sky_pos_fp(), novas_site_gcrs_posvel(), and starvectors().

## NOVAS_AU_SEC

#define NOVAS_AU_SEC ( NOVAS_AU / NOVAS_C )

[s] Light-time for one astronomical unit (AU) in seconds.

## NOVAS_BESSELIAN_YEAR_DAYS

#define NOVAS_BESSELIAN_YEAR_DAYS 365.242198781

[day] The length of a Besselian year in days.

Since
  1.5

Referenced by novas_epoch().

## NOVAS_C

#define NOVAS_C 299792458.0

[m/s] Speed of light in meters/second is a defining physical constant.

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

## NOVAS_C_AU_PER_DAY

#define NOVAS_C_AU_PER_DAY ( NOVAS_C * NOVAS_DAY / NOVAS_AU )

[AU/day] Speed of light in units of AU/day.

Referenced by novas_clock_skew().

## NOVAS_DAY

#define NOVAS_DAY 86400.0

[s] The length of a synodic day, that is 24 hours exactly.

Since
  1.2

Referenced by novas_itrf_transform_eop().

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

#define NOVAS_DEGREE (M_PI / 180.0)

[rad] A degree expressed in radians.

Since
  1.2

## NOVAS_DELAUNAY_ARGS_INIT

#define NOVAS_DELAUNAY_ARGS_INIT

Empty initializer for novas_delaunay_args.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_delaunay_args

## NOVAS_EARTH_ANGVEL

#define NOVAS_EARTH_ANGVEL 7.2921150e-5

[rad/s] Rotational angular velocity of Earth from IERS Conventions (2003).

## NOVAS_EARTH_FLATTENING

#define NOVAS_EARTH_FLATTENING NOVAS_GRS80_FLATTENING

[m] Earth ellipsoid flattening (ITRF / GRS80_MODEL)

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

Referenced by novas_itrf_transform_eop().

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

#define NOVAS_EARTH_RADIUS NOVAS_GRS80_RADIUS

[m] Equatorial radius of Earth (ITRF / GRS80 model)

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

Referenced by rad_vel2().

## NOVAS_EMB_INIT

#define NOVAS_EMB_INIT

object initializer for the Earth-Moon Barycenter (EMB)

Since
  1.2

See also
  object

## NOVAS_EQUATOR_TYPES

#define NOVAS_EQUATOR_TYPES

The number of equator types defined in enum novas_equator_type.

See also
  enum novas_equator_type

Since
  1.2

## NOVAS_FRAME_INIT

#define NOVAS_FRAME_INIT

Empty initializer for novas_frame.

Since
  1.3

See also
  novas_frame

## NOVAS_G_EARTH

#define NOVAS_G_EARTH 3.98600435507e14

[m3/s2] Geocentric gravitational constant (GMearth) from DE440, see Park et al., AJ, 161, 105 (2021)

## NOVAS_G_SUN

#define NOVAS_G_SUN 1.32712440041279419e20

[m3/s2] Heliocentric gravitational constant (GMsun) from DE440, see Park et al., AJ, 161, 105 (2021)

## NOVAS_GPS_TO_TAI

#define NOVAS_GPS_TO_TAI 19.0

[s] TAI - GPS time offset

## NOVAS_GRS80_FLATTENING

#define NOVAS_GRS80_FLATTENING (1.0 / 298.257222101)

[m] GRS80 Earth flattening

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

Referenced by novas_cartesian_to_geodetic(), and novas_geodetic_to_cartesian().

## NOVAS_GRS80_RADIUS

#define NOVAS_GRS80_RADIUS 6378137.0

[m] Equatorial radius of the WGS84 reference ellipsoid.

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

Referenced by novas_cartesian_to_geodetic(), and novas_geodetic_to_cartesian().

## NOVAS_HOURANGLE

#define NOVAS_HOURANGLE (M_PI / 12.0)

[rad] An hour of angle expressed in radians.

Since
  1.2

Referenced by cio_array().

## NOVAS_ID_TYPES

#define NOVAS_ID_TYPES

Number of different Solar-system body ID types enumerated.

Author
  Attila Kovacs

Since
  1.2

See also
  enum novas_id_type

## NOVAS_IERS_EARTH_FLATTENING

#define NOVAS_IERS_EARTH_FLATTENING (1.0 / 298.25642)

[m] Earth ellipsoid flattening from IERS Conventions (2003).

Value is 1 / 298.25642.

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_IERS_EARTH_RADIUS

#define NOVAS_IERS_EARTH_RADIUS 6378136.6

[m] Equatorial radius of Earth in meters from IERS Conventions (2003).

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_INVALID_LEAP

#define NOVAS_INVALID_LEAP

Leap seconds value to indicate invalid data.

Since
  1.7

See also
  novas_lookup_leap(), novas_fetch_eop()

Referenced by novas_lookup_leap().

## NOVAS_JD_B1900

#define NOVAS_JD_B1900 2415020.31352

[day] Julian date at B1900 (NASA / NAIF SPICE definition) precession(), transform_cat()

Referenced by supernovas::Time::b1900().

## NOVAS_JD_B1950

#define NOVAS_JD_B1950 2433282.42345905

[day] Julian date at B1950 (NASA / NAIF SPICE definition) precession(), transform_cat()

Referenced by supernovas::Time::b1950(), supernovas::Equinox::from_string(), supernovas::Equinox::mod_at_besselian_epoch(), and novas_epoch().

## NOVAS_JD_HIP

#define NOVAS_JD_HIP 2448349.0625

[day] Julian date for J1991.25, which the Hipparcos catalog is referred to.

See also
  precession(), transform_cat()

Referenced by supernovas::Equinox::hip(), supernovas::Time::hip(), novas_epoch(), and transform_hip().

## NOVAS_JD_J2000

#define NOVAS_JD_J2000 2451545.0

[day] Julian date at J2000

Referenced by supernovas::Calendar::date(), supernovas::Time::epoch(), supernovas::EOP::fetch_for(), supernovas::Equinox::from_string(), gcrs_to_mod(), supernovas::Equinox::icrs(), supernovas::Equinox::j2000(), supernovas::Time::j2000(), mod_to_gcrs(), novas_day_of_week(), novas_diurnal_eop_at_time(), novas_epoch(), novas_fetch_eop_unix(), novas_geom_posvel(), novas_lsr_to_ssb_vel(), novas_make_frame(), novas_make_moon_mean_orbit(), novas_make_moon_orbit(), novas_make_planet_orbit(), novas_moon_elp_ecl_pos(), novas_moon_elp_posvel_fp(), novas_next_moon_phase(), novas_ssb_to_lsr_vel(), nutation_angles(), supernovas::Ecliptic::system(), tdb2tt(), supernovas::Ecliptic::to_j2000(), transform_cat(), tt2tdb_fp(), and supernovas::CalendarDate::unix_time().

## NOVAS_JD_MJD0

#define NOVAS_JD_MJD0 2400000.5

[day] Julian date at which the Modified Julian Date (MJD) is zero

Referenced by supernovas::EOP::fetch_for_mjd(), supernovas::Time::from_mjd(), supernovas::CalendarDate::mjd(), supernovas::Ecliptic::mjd(), supernovas::Equinox::mjd(), and supernovas::Time::mjd().

## NOVAS_JD_START_GREGORIAN

#define NOVAS_JD_START_GREGORIAN 2299160.5

[day] The Julian day the Gregorian calendar was introduced in 15 October 1582.

The day prior to that was 4 October 1582 in the Julian Calendar.

Referenced by novas_day_of_year(), novas_jd_from_date(), and novas_jd_to_date().

## NOVAS_JULIAN_YEAR_DAYS

#define NOVAS_JULIAN_YEAR_DAYS 365.25

[day] The length of a Julian year (at J2000) in days.

Since
  1.5

Referenced by supernovas::Time::epoch(), novas_epoch(), novas_lsr_to_ssb_vel(), and novas_ssb_to_lsr_vel().

## NOVAS_JUPITER_INIT

#define NOVAS_JUPITER_INIT

object initializer for the planet Jupiter

Since
  1.2

See also
  object

## NOVAS_KM

#define NOVAS_KM 1000.0

[m] A kilometer (km) in meters.

Since
  1.2

Referenced by novas_make_moon_orbit(), novas_moon_elp_ecl_pos(), and terra().

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

#define NOVAS_MAJOR_VERSION 3

Major version of NOVAS on which this library is based.

## NOVAS_MARS_INIT

#define NOVAS_MARS_INIT

object initializer for the planet Mars

Since
  1.2

See also
  object

## NOVAS_MATRIX_IDENTITY

#define NOVAS_MATRIX_IDENTITY

novas_matrix initializer for an identity matrix.

Since
  1.3

See also
  novas_matrix, NOVAS_MATRIX_INIT

## NOVAS_MATRIX_INIT

#define NOVAS_MATRIX_INIT

Empty initializer for novas_matrix.

Since
  1.3

See also
  novas_matrix, NOVAS_MATRIX_IDENTITY

## NOVAS_MERCURY_INIT

#define NOVAS_MERCURY_INIT

object initializer for the planet Mercury

Since
  1.2

See also
  object

## NOVAS_MINOR_VERSION

#define NOVAS_MINOR_VERSION 1

Minor version of NOVAS on which this library is based.

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

#define NOVAS_NUM_EOP_SERIES

Number of Earth Orientation Parameter Data series handled by SuperNOVAS.

Since
  1.7

See also
  enum novas_eop_series

Referenced by novas_get_eop_itrf_year(), and novas_get_eop_url().

## NOVAS_OBJECT_INIT

#define NOVAS_OBJECT_INIT

Empty object initializer.

Since
  1.3

Author
  Attila Kovacs

See also
  object

## NOVAS_OBJECT_TYPES

#define NOVAS_OBJECT_TYPES

The number of object types distinguished by NOVAS.

See also
  enum novas_object_type

Referenced by make_object().

## NOVAS_OBSERVABLE_INIT

#define NOVAS_OBSERVABLE_INIT

Empty initializer for novas_observable.

Since
  1.3

See also
  novas_observable

## NOVAS_OBSERVER_PLACES

#define NOVAS_OBSERVER_PLACES

The number of observer place types supported.

See also
  enum novas_observer_place

Referenced by novas_make_frame(), and obs_posvel().

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

#define NOVAS_ORIGIN_TYPES

The number of different origins for Solar-system ephemeris data available in NOVAS.

See also
  enum novas_origin

Referenced by ephemeris().

## NOVAS_PARSEC

#define NOVAS_PARSEC ( NOVAS_AU / NOVAS_ARCSEC )

[m] A parsec in meters.

Since
  1.5

## NOVAS_PLANET_BUNDLE_INIT

#define NOVAS_PLANET_BUNDLE_INIT

Empty initializer for novas_planet_bundle.

Since
  1.3

See also
  novas_planet_bundle

## NOVAS_PLANET_GRAV_Z_INIT

#define NOVAS_PLANET_GRAV_Z_INIT

Gravitational redshifts for major planets (and Moon and Sun) for light emitted at surface and detected at a large distance away.

Barycenters are not considered, and for Pluto the redshift for the Pluto system is assumed for distant observers.

See also
  enum novas_planet
  NOVAS_PLANETS

Since
  1.1.1

Author
  Attila Kovacs

Referenced by rad_vel2().

## NOVAS_PLANET_INIT

#define NOVAS_PLANET_INIT | ( |  | num,
|  |  | name )

object initializer macro for major planets, the Sun, Moon, and barycenters.

Parameters

  num | An enum novas_planet number
  name | The designated planet name

Since
  1.2

See also
  object, make_planet()

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

#define NOVAS_PLANET_RADII_INIT

Array initializer for mean planet radii in meters, matching the enum novas_planet.

E.g.

const double *planet_radii[] = NOVAS_PLANET_RADII_INIT;
NOVAS_PLANET_RADII_INIT
#define NOVAS_PLANET_RADII_INIT
Array initializer for mean planet radii in meters, matching the enum novas_planet.
Definition novas.h:684

REFERENCES:

1. https://orbital-mechanics.space/reference/planetary-parameters.html, Table 3.
2. B. A. Archinal, et al., Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements:
   1. Celestial Mechanics and Dynamical Astronomy, 130(3):22, March 2018. doi:10.1007/s10569-017-9805-5.

Since
  1.5

Author
  Attila Kovacs

See also
  enum novas_planet, NOVAS_PLANET_NAMES_INIT, NOVAS_RMASS_INIT

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

## NOVAS_PLANETS

#define NOVAS_PLANETS

The number of major planets defined in NOVAS.

See also
  enum novas_planet

Referenced by earth_sun_calc(), supernovas::Planet::for_naif_id(), supernovas::Planet::for_name(), grav_planets(), make_object(), make_planet(), novas_equals_planet_bundle(), novas_planet_for_name(), obs_planets(), supernovas::OrbitalSystem::orientation(), planet_ephem_provider_hp(), and rad_vel2().

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

#define NOVAS_REFERENCE_ELLIPSOIDS

The total number of reference ellipsoid types known to SuperNOVAS.

Since
  1.5

See also
  enum novas_reference_ellipsoid

Referenced by supernovas::Site::Site().

## NOVAS_REFERENCE_PLANES

#define NOVAS_REFERENCE_PLANES

Number of entries in enum novas_reference_plane.

Since
  1.6

## NOVAS_REFERENCE_SYSTEMS

#define NOVAS_REFERENCE_SYSTEMS

The number of basic coordinate reference systems in NOVAS.

See also
  enum novas_reference_system

Referenced by supernovas::Geometric::Geometric(), novas_app_to_geom(), novas_make_transform(), and supernovas::Observer::to_interferometric().

## NOVAS_REFRACTION_MODELS

#define NOVAS_REFRACTION_MODELS

The number of built-in refraction models available in SuperNOVAS.

See also
  enum novas_refraction_model

Referenced by refract().

## NOVAS_RMASS_INIT

#define NOVAS_RMASS_INIT

Reciprocal masses of solar system bodies, from DE-405 (Sun mass / body mass).

[0]: Earth/Moon barycenter (legacy from NOVAS C), MASS[1] = Mercury, ...,

Barycentric reciprocal masses (index 12, 13) are not set.

NOTES:

1. The values have been updated to used DE440 data (Park et al. 2021) in 1.4.

REFERENCES:

1. Ryan S. Park et al 2021 AJ 161 105, DOI 10.3847/1538-3881/abd414
2. IERS Conventions, Chapter 3, Table 3.1

Since
  1.2

Author
  Attila Kovacs

See also
  enum novas_planet, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANET_RAII_INIT, NOVAS_PLANETS_GRAV_Z_INIT

Referenced by grav_planets(), and supernovas::Planet::mass().

## NOVAS_SATURN_INIT

#define NOVAS_SATURN_INIT

object initializer for the planet Saturn

Since
  1.2

See also
  object

## NOVAS_SOLAR_CONSTANT

#define NOVAS_SOLAR_CONSTANT 1367.0

[W/m2] The Solar Constant i.e., typical incident Solar power on Earth.

The value of 1367 Wm−2 was adopted by the World Radiation Center (Gueymard, 2004).

Since
  1.3

See also
  novas_solar_power()

Referenced by novas_solar_power().

## NOVAS_SOLAR_RADIUS

#define NOVAS_SOLAR_RADIUS 696340000.0

[m] Solar radius (photosphere)

Since
  1.1

Referenced by rad_vel2().

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

#define NOVAS_TAI_TO_TT 32.184

[s] TT - TAI time offset

Referenced by get_utc_to_tt().

## NOVAS_TIMESCALES

#define NOVAS_TIMESCALES

The number of astronomical time scales supported.

Since
  1.1

See also
  novas_timescale

Referenced by supernovas::Interval::Interval(), supernovas::Frame::clock_skew(), supernovas::Time::jd(), supernovas::Time::jd_day(), supernovas::Time::jd_frac(), supernovas::Time::mjd(), supernovas::Time::mjd_day(), supernovas::Time::mjd_frac(), novas_diff_time_scale(), novas_get_split_time(), novas_set_split_time(), and novas_timescale_offset().

## NOVAS_TIMESPEC_INIT

#define NOVAS_TIMESPEC_INIT

Empty initializer for novas_timespec.

Since
  1.3

See also
  novas_timespec

## NOVAS_TIMESTAMP_LEN

#define NOVAS_TIMESTAMP_LEN 28

Minimum number of bytes for a timestamp.

Since
  1.6

## NOVAS_TRACK_INIT

#define NOVAS_TRACK_INIT

Empty initializer for novas_track.

Since
  1.3

See also
  novas_track

## NOVAS_TRANSFORM_INIT

#define NOVAS_TRANSFORM_INIT

Empty initializer for NOVAS_TRANSFORM.

Since
  1.3

See also
  novas_transform

## NOVAS_TRANSFORM_TYPES

#define NOVAS_TRANSFORM_TYPES

The number of coordinate transfor types in NOVAS.

Note, that transform types start at 1, so the value of this constant matches the value of the last transform in the enum.

See also
  enum novas_transform_type

## NOVAS_TROPICAL_YEAR_DAYS

#define NOVAS_TROPICAL_YEAR_DAYS 365.2421897

[day] The length of a tropical year (at J2000) in days.

Since
  1.5

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

## NOVAS_VERSION_STRING

#define NOVAS_VERSION_STRING str_2(NOVAS_MAJOR_VERSION) "." str_2(NOVAS_MINOR_VERSION)

The version string of the upstream NOVAS library on which this library is based.

## NOVAS_WGS84_FLATTENING

#define NOVAS_WGS84_FLATTENING (1.0 / 298.257223563)

[m] WGS84 Earth flattening

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_WGS84_RADIUS

#define NOVAS_WGS84_RADIUS 6378137.0

[m] Equatorial radius of the WGS84 reference ellipsoid.

Since
  1.5

See also
  novas_geodetic_to_cartesian(), novas_cartesian_to_geodetic()

## NOVAS_WOBBLE_DIRECTIONS

#define NOVAS_WOBBLE_DIRECTIONS

Number of values in enum novas_wobble_direction.

Since
  1.4

See also
  novas_wobble_direction

Referenced by wobble().

## OBSERVER_INIT

#define OBSERVER_INIT

Empty initializer for observer.

Since
  1.3

Author
  Attila Kovacs

See also
  observer

## ON_SURFACE_INIT

#define ON_SURFACE_INIT

Initializer for a NOVAS on_surface data structure.

Since
  1.2

Author
  Attila Kovacs

See also
  on_surface, ON_SURFACE_LOC

## ON_SURFACE_LOC

#define ON_SURFACE_LOC | ( |  | lon,
|  |  | lat,
|  |  | alt )

Initializer for a NOVAS on_surface data structure at a specified geodetic location.

Parameters

  lon | [deg] Geodetic longitude of observer (East is positive)
  lat | [deg] Geodetic latitude of observer (North is positive)
  alt | [m] Observer altitude above sea level.

Since
  1.2

Author
  Attila Kovacs

See also
  on_surface, make_itrf_site(), make_gps_site(), make_xyz_site(), ON_SURFACE_INIT

## RAD2DEG

#define RAD2DEG (1.0 / DEG2RAD)

[deg/rad] 1 radian in degrees

## SKY_POS_INIT

#define SKY_POS_INIT

Initializer for a NOVAS sky_pos structure.

Since
  1.1.1

Author
  Attila Kovacs

See also
  sky_pos

Referenced by novas_equ_track(), novas_hor_track(), novas_object_sep(), radec_planet(), and radec_star().

## SUPERNOVAS_MAJOR_VERSION

#define SUPERNOVAS_MAJOR_VERSION 1

API major version.

## SUPERNOVAS_MINOR_VERSION

#define SUPERNOVAS_MINOR_VERSION 7

API minor version.

## SUPERNOVAS_PATCHLEVEL

#define SUPERNOVAS_PATCHLEVEL 2

Integer sub version of the release.

## SUPERNOVAS_RELEASE_STRING

#define SUPERNOVAS_RELEASE_STRING ""

Additional release information in version, e.g. "-1", or "-rc1", or empty string "" for releases.

## SUPERNOVAS_VERSION_STRING

#define SUPERNOVAS_VERSION_STRING

The version string for this library.

## TWOPI

#define TWOPI (2.0 * M_PI)

2π

Referenced by supernovas::TimeAngle::TimeAngle(), accum_prec(), earth_sun_calc(), novas_itrf_transform_eop(), novas_make_moon_mean_orbit(), novas_make_planet_orbit(), novas_norm_ang(), novas_orbit_native_posvel(), planet_lon(), spin(), sun_eph(), and supernovas::Time::time_of_day().

## UNIX_SECONDS_0UTC_1JAN2000

#define UNIX_SECONDS_0UTC_1JAN2000 946684800L

[s] UNIX time at 0 UTC, 1 Jan 2000.0

Since
  1.7

Referenced by supernovas::EOP::fetch_for(), and novas_fetch_eop_unix().

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

## in_space

typedef struct novas_in_space in_space

data for an observer's location on Earth orbit

See also
  make_in_space(), IN_SPACE_INIT
  make_observer_in_space()

## novas_delaunay_args

typedef struct novas_delaunay_args novas_delaunay_args

Fundamental Delaunay arguments of the Sun and Moon, from Simon section 3.4(b.3).

Since
  1.0

Author
  Attila Kovacs

See also
  fund_args(), NOVAS_DELAUNAY_ARGS_INIT

## novas_frame

typedef struct novas_frame novas_frame

A set of parameters that uniquely define the place and time of observation.

The user may initialize the frame with novas_make_frame(). Once the observer frame is set up, it can be used repeatedly to perform efficient calculations of multiple objects in the coordinate system of choice, much faster than what place() can do. Frames also allow for transforming coordinates calculated for one coordinate syste, into another coordinate system with little effort.

You should never set or change fields in this structure manually. Instead the structure should always be initialized by an appropriate call to novas_make_frame(). After that you may change the observer location, if need be, with novas_change_observer().

The structure may expand with additional field in the future. Thus neither its size nor its particular layout should be assumed fixed over SuperNOVAS releases.

Since
  1.1

See also
  novas_make_frame(), novas_change_observer(), novas_make_transform(), NOVAS_FRAME_INIT
  novas_sky_pos(), novas_geom_posvel(), novas_geom_to_app(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), novas_rises_above(), novas_sets_below(), novas_transit_time()

## novas_matrix

typedef struct novas_matrix novas_matrix

A 3x3 matrix for coordinate transformations.

Since
  1.1

See also
  novas_transform, NOVAS_MATRIX_INIT, NOVAS_MATRIX_IDENTITY

## novas_observable

typedef struct novas_observable novas_observable

Spherical and spectral coordinate set.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_track, NOVAS_OBSERVABLE_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

## novas_planet_bundle

typedef struct novas_planet_bundle novas_planet_bundle

Position and velocity data for a set of major planets (which may include the Sun and the Moon also).

Since
  1.1

See also
  enum novas_planet, NOVAS_PLANET_BUNDLE_INIT, grav_planets()

## novas_timespec

typedef struct novas_timespec novas_timespec

A structure, which defines a precise instant of time that can be expressed in any of the astronomical timescales.

Precisions to picosecond accuracy are supported, which ought to be plenty accurate for any real astronomical application.

Since
  1.1

See also
  novas_set_time(), novas_get_time(), NOVAS_TIMESPEC_INIT, enum novas_timescale, timescale.c
  novas_make_frame()

## novas_track

typedef struct novas_track novas_track

The spherical and spectral tracking position of a source, and its first and second time derivatives.

As such, it may be useful for telescope drive control (position, velocity, and acceleration), or else for fast extrapolation of momentary positions without a full, and costly, recalculation of the positions at high rate over a suitable short period.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_hor_track(), novas_equ_track(), novas_track_pos(), NOVAS_TRACK_INIT

## novas_transform

typedef struct novas_transform novas_transform

A transformation between two astronomical coordinate systems for the same observer location and time.

This allows for more elegant, generic, and efficient coordinate transformations than the low-level NOVAS functions.

The transformation can be (should be) initialized via novas_make_transform(), or via novas_invert_transform().

Since
  1.1

See also
  novas_make_transform(), novas_invert_transform(), NOVAS_TRANSFORM_INIT
  novas_transform_vector(), novas_transform_sky_pos()

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

## observer

typedef struct novas_observer observer

Observer location.

See also
  make_itrf_observer(), make_gps_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_at_geocenter(), make_observer_in_space(), make_solar_system_observer(), OBSERVER_INIT
  novas_make_frame()

## on_surface

typedef struct novas_on_surface on_surface

Data for an observer's location on the surface of the Earth, and optional local weather data for refraction calculations only.

See also
  make_itrf_site(), make_gps_site(), make_xyz_site(), make_observer_at_site(), ON_SURFACE_INIT
  make_observer_at_site(), make_airborne_observer()

## sky_pos

typedef struct novas_sky_pos sky_pos

Celestial object's place on the sky; contains the output from place().

See also
  novas_sky_pos(), novas_transform_sky_pos(), SKY_POS_INIT

## Enumeration Type Documentation

## novas_calendar_type

enum novas_calendar_type

Constants to disambiguate which type of calendar yo use for interpreting calendar dates.

Roman/Julian or Gregorian/

Since
  1.3

Author
  Attila Kovacs

See also
  novas_jd_from_date(), novas_jd_to_date()

Enumerator
NOVAS_ROMAN_CALENDAR | The Roman (a.k.a. Julian) calendar by Julius Caesar, introduced in -45 B.C.
NOVAS_ASTRONOMICAL_CALENDAR | Roman (a.k.a. Julian) calendar until the Gregorian calendar reform of 1582, after which it is the Gregorian calendar
NOVAS_GREGORIAN_CALENDAR | The Gregorian calendar introduced on 15 October 1582, the day after 4 October. 1582 in the Roman (a.k.a. Julian) calendar.

## novas_date_format

enum novas_date_format

The general order of date components for parsing.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_date_format()

Enumerator
NOVAS_YMD | year, then month, then day.
NOVAS_DMY | day, then month, then year
NOVAS_MDY | month, then day, then year

## novas_dynamical_type

enum novas_dynamical_type

Constants that determine the type of dynamical system.

I.e., the 'current' equatorial coordinate system used for a given epoch of observation.

See also
  gcrs2equ()

Enumerator
NOVAS_DYNAMICAL_MOD | Mean Of Date (TOD): dynamical system that include precession but not including nutation, such as commonly used for older catalogs like FK4, KF5, B1950, or HIP. NOVAS_DYNAMICAL_MOD
NOVAS_DYNAMICAL_TOD | True Of Date (TOD): dynamical system of the 'true' equator of date, with its origin at the true equinox of date. In the IAU 2000 methodology, it includes precession and nutation, but not the sub-arcsecond level Earth Orientation Parameters (EOP). The latter are used only when converting to the Earth-fixed TIRS system. NOVAS_DYNAMICAL_TOD
NOVAS_DYNAMICAL_CIRS | Celestial Intermediate Reference System (CIRS): dynamical system of the true equator, with its origin at the CIO (preferred since IAU 2006). NOVAS_DYNAMICAL_CIRS

## novas_eop_series

enum novas_eop_series

Identifier of the IERS EOP series used (or to use).

Since
  1.7

Author
  Attila Kovacs

See also
  novas_eop, novas_set_eop_url()

Enumerator
EOP_LEAP_LIST | List of leap seconds, since their introduction in 1972 (leap-seconds.list).
EOP_RAPID_IAU2000 | IERS Rapid Service data for IAU2000, starting in 1973 (finals.all.iau2000.txt).
EOP_C04_IAU2000_0UTC | IERS C04 Long-term data (ITRF 2020) from 2 Jan 1962 to now, daily at 0 UTC (EOP_20u24_C04_one_file_1962-now.txt).
EOP_C01_IAU2000 | IERS C01 Long-term data from 1846 to now (EOP_C01_IAU2000_1846-now.txt).

## novas_equator_type

enum novas_equator_type

Constants that determine the type of equator to be used for the coordinate system.

See also
  NOVAS_EQUATOR_TYPES
  equ2ecl(), ecl2equ()

Enumerator
NOVAS_MEAN_EQUATOR | Mean celestial equator of date without nutation (pre IAU 2006 system).
NOVAS_TRUE_EQUATOR | True celestial equator of date.
NOVAS_GCRS_EQUATOR | International / Geocentric Celestial Reference System (ICRS / GCRS) equator.

## novas_equinox_type

enum novas_equinox_type

The type of equinox used in the pre IAU 2006 (old) methodology.

See also
  ira_equinox()

Enumerator
NOVAS_MEAN_EQUINOX |
NOVAS_TRUE_EQUINOX | Mean equinox: includes precession but not nutation. True apparent equinox: includes both precession and nutation

## novas_frametie_direction

enum novas_frametie_direction

Direction constant to use for frame_tie(), to determine the direction of transformation between J2000 and ICRS coordinates.

See also
  frame_tie(), gcrs_to_j2000(), j2000_to_gcrs(), J2000_TO_ICRS

Enumerator

J2000_TO_ICRS

Change coordinates from ICRS to the J2000 (dynamical) frame.

(You can also use any negative value for the same effect).

See also
  j2000_to_gcrs()

ICRS_TO_J2000

Change coordinates from J2000 (dynamical) frame to the ICRS.

(You can use any value >=0 for the same effect).

See also
  gcrs_to_j2000()

## novas_nutation_direction

enum novas_nutation_direction

Direction constant for nutation(), between mean and true equatorial coordinates.

See also
  nutation()

Enumerator
NUTATE_TRUE_TO_MEAN | Change from true equator to mean equator (i.e. undo wobble corrections). You may use any non-zero value as well.
NUTATE_MEAN_TO_TRUE | Change from mean equator to true equator (i.e. apply wobble corrections).

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

enum novas_observer_place

Types of places on and around Earth that may serve as a reference position for the observation.

See also
  observer, NOVAS_OBSERVER_PLACES

Enumerator

NOVAS_OBSERVER_AT_GEOCENTER

Calculate coordinates as if observing from the geocenter for location and Earth rotation independent coordinates.

See also
  make_observer_at_geocenter()

NOVAS_OBSERVER_ON_EARTH

Stationary observer in the corotating frame of Earth.

See also
  make_gps_observer(), make_itrf_observer(), make_site_observer()

NOVAS_OBSERVER_IN_EARTH_ORBIT

Observer is on Earth orbit, with a position and velocity vector relative to geocenter.

This may also be appropriate for observatories at the L2 or other Earth-based Lagrange points.

See also
  make_observer_in_space()

NOVAS_AIRBORNE_OBSERVER

Observer airborne, moving relative to the surface of Earth.

Since
  1.1

See also
  make_airborne_observer()

NOVAS_SOLAR_SYSTEM_OBSERVER

Observer is orbiting the Sun.

Since
  1.1

See also
  make_solar_system_observer()

## novas_origin

enum novas_origin

The origin of the ICRS system for referencing positions and velocities for solar-system bodies.

See also
  ephemeris(), NOVAS_ORIGIN_TYPES

Enumerator
NOVAS_BARYCENTER | Origin at the Solar-system barycenter (i.e. BCRS).
NOVAS_HELIOCENTER | Origin at the center of the Sun.

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

enum novas_reference_ellipsoid

Type of Earth reference ellipsoid.

Only ellipsoids commonly in use today are listed, ommitting many obsoleted historical variants.

Since
  1.5

See also
  novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), novas_geodetic_transform_site()

Enumerator
NOVAS_GRS80_ELLIPSOID | GRS80 reference ellipsoid, used for the International Terrestrial Reference System (ITRS).
NOVAS_WGS84_ELLIPSOID | WGS84 reference ellipsoid, used for GPS navigation.
NOVAS_IERS_1989_ELLIPSOID | IERS (1989) reference ellipsoid, formerly used by the IERS conventions (but not for ITRS, which uses the GRS80 model).
NOVAS_IERS_2003_ELLIPSOID | IERS (2003) reference ellipsoid, used by the IERS conventions (but not for ITRS, which uses the GRS80 model).

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

enum novas_refraction_model

Constants that determine whether what model (if any) to use for implicit refraction calculations.

See also
  on_surface, novas_app_to_hor(), novas_hor_to_app(), refract(), refract_astro()

Enumerator
NOVAS_NO_ATMOSPHERE | Do not apply atmospheric refraction correction.

NOVAS_STANDARD_ATMOSPHERE

Uses a standard atmospheric model, ignoring any weather values defined for the specific observing location.

See also
  novas_standard_refraction(), novas_set_default_weather()

NOVAS_WEATHER_AT_LOCATION

Uses the weather parameters that are specified together with the observing location.

See also
  novas_optical_refraction()

NOVAS_RADIO_REFRACTION

Uses the Berman & Rockwell 1976 refraction model for Radio wavelengths with the weather parameters specified together with the observing location.

Since
  1.4

See also
  novas_radio_refraction()

NOVAS_WAVE_REFRACTION

Uses the IAU / SOFA wavelength-depended refraction model with the weather parameters specified together with the observing location.

The wavelength can be specified via novas_refract_wavelength() or else it is assumed to be 550 nm (visible light).

Since
  1.4

See also
  novas_wave_refraction(), novas_refract_wavelength()

## novas_refraction_type

enum novas_refraction_type

The type of elevation value for which to calculate a refraction.

See also
  RefractionModel, novas_app_to_hor(), novas_hor_to_app()

Since
  1.1

Enumerator
NOVAS_REFRACT_OBSERVED | Refract observed elevation value.
NOVAS_REFRACT_ASTROMETRIC | Refract astrometric elevation value.

## novas_separator_type

enum novas_separator_type

Separator type to use for broken-down time/angle string representations in HMS/DMS formats.

Since
  1.3

See also
  novas_print_hms(), novas_print_dms()

Enumerator
NOVAS_SEP_COLONS | Use colons between components, e.g. '12:34:56'.
NOVAS_SEP_SPACES | Use spaces between components, e.g. '12 34 56'.
NOVAS_SEP_UNITS | Use unit markers after each component, e.g. '12h34m56s'.
NOVAS_SEP_UNITS_AND_SPACES | Useunit markers after each compoent, plus spaces between components, e.g. '12h 34m 56s'.

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

## novas_wobble_direction

enum novas_wobble_direction

Direction constants for polar wobble corrections via the wobble() function.

See also
  novas_app_to_hor(), novas_hor_to_app(), wobble(), NOVAS_WOBBLE_DIRECTIONS

Enumerator

WOBBLE_ITRS_TO_TIRS

use for wobble() to change from ITRS (Earth-fixed) to TIRS (pseudo Earth-fixed).

It includes TIO longitude correction.

Since
  1.4

WOBBLE_TIRS_TO_ITRS

use for wobble() to change from TIRS (pseudo Earth-fixed) to ITRS (Earth-fixed).

It includes TIO longitude correction.

Since
  1.4

WOBBLE_ITRS_TO_PEF | use for wobble() to change from ITRS (Earth-fixed) Pseudo Earth Fixed (PEF). It does not include TIO longitude correction. Otherwise, it's the same as WOBBLE_ITRS_TO_TIRS
WOBBLE_PEF_TO_ITRS | use for wobble() to change from Pseudo Earth Fixed (PEF) to ITRS (Earth-fixed). It does not include TIO longitude correction. Otherwise, it's the same as WOBBLE_TIRS_TO_ITRS

## Function Documentation

## aberration()

int aberration | ( | const double * | pos,
|  | const double * | vobs,
|  | double | lighttime,
|  | double * | out )

Corrects position vector for aberration of light.

Algorithm includes relativistic terms.

NOTES:

1. This function is called by place() to account for aberration when calculating the position of the source.

REFERENCES:

1. Murray, C. A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
2. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | pos | [AU] Position vector of source relative to observer
  | vobs | [AU/day] Velocity vector of observer, relative to the solar system barycenter.
  | lighttime | [day] Light time from object to Earth (if known). Or set to 0, and this function will compute it as needed.
  [out] | out | [AU] Position vector, referred to origin at center of mass of the Earth, corrected for aberration. It can be the same vector as one of the inputs.

Returns
  0 if successful, or -1 if any of the vector arguments are NULL.

See also
  frame_aberration()

References novas_vlen().

Referenced by novas_moon_elp_sky_pos_fp(), novas_uvw(), and place().

## accum_prec()

double accum_prec | ( | double | t | ) |

Returns the general precession in longitude (Simon et al.

1994), equivalent to 5028.8200 arcsec/cy at J2000.

Parameters

  t | [cy] Julian centuries since J2000

Returns
  [rad] the approximate precession angle [-π:π].

See also
  planet_lon(), nutation_angles(), e_tilt(), NOVAS_JD_J2000

Since
  1.0

Author
  Attila Kovacs

References TWOPI.

Referenced by nu2000k().

## app_planet()

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

reference_system: TOD
observer location: geocenter
position_type: apparent

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_tod(), astro_planet(), local_planet(), topo_planet(), virtual_planet(), app_star()
  novas_sky_pos(), make_observer_at_geocenter(), NOVAS_TOD

References NOVAS_TOD, and radec_planet().

## app_star()

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

reference_system: TOD
observer location: geocenter
position_type: apparent

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_tod(), novas_sky_pos(), place_star(), astro_star(), local_star(), topo_star(), virtual_star(), app_planet()
  novas_sky_pos(), make_observer_at_geocenter(), NOVAS_TOD

References NOVAS_TOD, and radec_star().

Referenced by mean_star().

## app_to_cirs_ra()

double app_to_cirs_ra | ( | double | jd_tt,
|  | enum novas_accuracy | accuracy,
|  | double | ra )

Converts an apparent right ascension coordinate (measured from the true equinox of date) to a CIRS R.A., measured from the CIO.

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  ra | [h] the apparent R.A. coordinate measured from the true equinox of date.

Returns
  [h] The CIRS right ascension coordinate, measured from the CIO [0:24], or NAN if the accuracy is invalid, or if there was an error from cio_ra().

Since
  1.0.1

Author
  Attila Kovacs

See also
  cirs_to_app_ra(), tod_to_cirs()

References cio_ra().

## astro_planet()

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_icrs(), app_planet(), local_planet(), topo_planet(), virtual_planet(), astro_star()
  novas_geom_posvel(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_ICRS, and radec_planet().

## astro_star()

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

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_star(), place_icrs(), app_star(), local_star(), topo_star(), virtual_star(), astro_planet()
  novas_geom_posvel(), make_observer_at_geocenter(), NOVAS_ICRS

References NOVAS_ICRS, and radec_star().

## bary2obs()

int bary2obs | ( | const double * | pos,
|  | const double * | pos_obs,
|  | double * | out,
|  | double *restrict | lighttime )

Moves the origin of coordinates from the barycenter of the solar system to the observer (or the geocenter); i.e., this function accounts for parallax (annual+geocentric or just annual).

REFERENCES:

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

Parameters

  | pos | [AU] Position vector, referred to origin at solar system barycenter.
  | pos_obs | [AU] Position vector of observer (or the geocenter), with respect to origin at solar system barycenter.
  [out] | out | [AU] Position vector, referred to origin at center of mass of the Earth. It may be NULL if not required, or be the same vector as either of the inputs.
  [out] | lighttime | [day] Light time from object to Earth. It may be NULL if not required.

Returns
  0 if successful, or -1 if any of the essential pointer arguments is NULL.

See also
  novas_make_frame(), light_time2()

References novas_vlen().

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

## cal_date()

int cal_date | ( | double | tjd,
|  | short *restrict | year,
|  | short *restrict | month,
|  | short *restrict | day,
|  | double *restrict | hour )

This function will compute a broken down date on the astronomical calendar given the Julian day input.

Input Julian day can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

1. The Gregorian calendar was introduced on 15 October 1582 only (corresponding to 5 October of the previously used Julian calendar). Prior to it this function returns Julian / Roman calendar dates, e.g. the day before the reform is 1582 October 4. You can use novas_jd_to_date() instead to convert JD days to dates in specific calendars.
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

  | tjd | [day] Julian date
  [out] | year | [yr] Astronomical calendar year. It may be NULL if not required. B.C. years are represented as <=0, i.e. 1 B.C. as 0 and X B.C. as (1 - X)
  [out] | month | [month] Astronomical calendar month [1:12]. It may be NULL if not required.
  [out] | day | [day] Day of the month [1:31]. It may be NULL if not required.
  [out] | hour | [h] Hour of day [0:24]. It may be NULL if not required.

Returns
  0

See also
  novas_jd_to_date()
  novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_to_date().

## cio_ra()

short cio_ra | ( | double | jd_tt,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | ra_cio )

Computes the true right ascension of the celestial intermediate origin (CIO) vs the equinox of date on the true equator of date for a given TT Julian date.

This is simply the negated return value ofira_equinox() for the true equator of date.

REFERENCES:

1. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | ra_cio | [h] Right ascension of the CIO, with respect to the true equinox of date (+ or -), or NAN when returning with an error code.

Returns
  0 if successful, -1 if the output pointer argument is NULL, 1 if 'accuracy' is invalid, 10–20: 10 + error code from cio_location(), or else 20 + error from cio_basis()

See also
  ira_equinox()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

Referenced by app_to_cirs_ra(), and cirs_to_app_ra().

## cirs_to_app_ra()

double cirs_to_app_ra | ( | double | jd_tt,
|  | enum novas_accuracy | accuracy,
|  | double | ra )

Converts a CIRS right ascension coordinate (measured from the CIO) to an apparent R.A.

measured from the true equinox of date.

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  ra | [h] The CIRS right ascension coordinate, measured from the CIO.

Returns
  [h] the apparent R.A. coordinate measured from the true equinox of date [0:24], or NAN if the accuracy is invalid, or if there was an error from cio_ra().

Since
  1.0.1

Author
  Attila Kovacs

See also
  app_to_cirs_ra(), cirs_to_tod()

References cio_ra().

## cirs_to_gcrs()

int cirs_to_gcrs | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) frame at the given epoch to the ICRS / GCRS.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

This function uses Method 2 of the IERS Conventions 2010 (Chapter 5, Section 5.9), converting CIRS to TOD first via a rotation by the equation of origins, then using the IAU 2006 precession-nutation model (P03; Capitaine et al. 2003) to convert to J2000, and finally correcting for the frame bias to arrive at GCRS.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, especially Section 5.9
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the ICRS / GCRS coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or else 10 + the error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  tod_to_gcrs(), gcrs_to_cirs(), cirs_to_itrs(), cirs_to_tod(), novas_sys_to_icrs()

References cirs_to_tod(), and tod_to_gcrs().

Referenced by novas_sys_to_icrs(), and ter2cel().

## cirs_to_itrs()

int cirs_to_itrs | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Rotates a position vector from the dynamical CIRS frame of date to the Earth-fixed ITRS frame (IAU 2000 standard method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  tod_to_itrs(), itrs_to_cirs(), gcrs_to_cirs(), cirs_to_gcrs(), cirs_to_tod()

References cel2ter().

## cirs_to_tod()

int cirs_to_tod | ( | double | jd_tt,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) at the given epoch to the True of Date (TOD) reference system.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or else 20 + the error from cio_basis().

Since
  1.1

Author
  Attila Kovacs

See also
  tod_to_cirs(), cirs_to_app_ra(), cirs_to_gcrs(), cirs_to_itrs()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and spin().

Referenced by cirs_to_gcrs().

## d_light()

double d_light | ( | const double * | pos_src,
|  | const double * | pos_body )

Returns the difference in light-time, for a star, between the barycenter of the solar system and the observer (or the geocenter) (Usage A).

Alternatively (Usage B), this function returns the light-time from the observer (or the geocenter) to a point on a light ray that is closest to a specific solar system body. For this purpose, 'pos_src' is the position vector toward observed object, with respect to origin at observer (or the geocenter); 'pos_body' is the position vector of solar system body, with respect to origin at observer (or the geocenter), components in AU; and the returned value is the light time to point on line defined by 'pos' that is closest to solar system body (positive if light passes body before hitting observer, i.e., if 'pos_body' is within 90 degrees of 'pos_src').

NOTES:

1. This function is called by novas_geom_posvel(), novas_sky_pos(), or place()

Parameters

  pos_src | Position vector towards observed object, with respect to the SSB (Usage A), or relative to the observer / geocenter (Usage B).
  pos_body | [AU] Position of observer relative to SSB (Usage A), or position of intermediate solar-system body with respect to the observer / geocenter (Usage B).

Returns
  [day] Difference in light time to observer, either relative to SSB (Usage A) or relative intermediate solar-system body (Usage B); or else NAN if either of the input arguments is NULL.

See also
  novas_sky_pos(), novas_geom_posvel()

References novas_vlen().

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

## e_tilt()

int e_tilt | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | mobl,
|  | double *restrict | tobl,
|  | double *restrict | ee,
|  | double *restrict | dpsi,
|  | double *restrict | deps )

(primarily for internal use) Computes quantities related to the orientation of the Earth's rotation axis at the specified Julian date.

In the pre-IAU2000 method, unmodelled corrections to earth orientation can be defined via cel_pole() prior to this call. However, we strongly recommend against that approach, and suggest you apply Earth orientation corrections only in novas_make_frame() or wobble().

NOTES:

1. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | mobl | [deg] Mean obliquity of the ecliptic. It may be NULL if not required.
  [out] | tobl | [deg] True obliquity of the ecliptic. It may be NULL if not required.
  [out] | ee | [s] Equation of the equinoxes in seconds of time. It may be NULL if not required.
  [out] | dpsi | [arcsec] Nutation in longitude. It may be NULL if not required.
  [out] | deps | [arcsec] Nutation in obliquity. It may be NULL if not required.

Returns
  0 if successful, or -1 if the accuracy argument is invalid

See also
  novas_gast(), nutation(), ira_equinox(), equ2ecl(), ecl2equ()

References mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, and nutation_angles().

Referenced by ecl2equ_vec(), equ2ecl_vec(), ira_equinox(), novas_gast(), and nutation().

## earth_sun_calc()

short earth_sun_calc | ( | double | jd_tdb,
|  | enum novas_planet | body,
|  | enum novas_origin | origin,
|  | double *restrict | position,
|  | double *restrict | velocity )

Provides the position and velocity of the Earth and Sun only at epoch 'jd_tdb' by evaluating a closed-form theory without reference to an external file.

This function can also provide the position and velocity of the Sun.

REFERENCES:

1. Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry Subroutines"; USNO internal document dated 20 Oct 1988; revised 15 Mar 1990.
2. Explanatory Supplement to The Astronomical Almanac (1992).

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | NOVAS_EARTH (3) or NOVAS_SUN (10) only.
  | origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
  [out] | position | [AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
  [out] | velocity | [AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns
  0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS) or if one of the output pointer arguments is NULL (errno set to EINVAL). 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid.

See also
  earth_sun_calc_hp(), set_planet_provider(), novas_planet_provider

References NOVAS_BARYCENTER, NOVAS_EARTH, NOVAS_PLANETS, NOVAS_SSB, NOVAS_SUN, precession(), radec2vector(), sun_eph(), and TWOPI.

Referenced by earth_sun_calc_hp().

## earth_sun_calc_hp()

short earth_sun_calc_hp | ( | const double | jd_tdb[restrict 2],
|  | enum novas_planet | body,
|  | enum novas_origin | origin,
|  | double *restrict | position,
|  | double *restrict | velocity )

It may provide the position and velocity of the Earth and Sun, the same as earth_sun_calc(), if enable_earth_sun_hp() is set to true (non-zero).

Otherwise, it will return with an error code of 3, indicating that high-precision calculations are not provided by this implementation.

NOTES:

1. This implementation will always propulate the output position and velocity vectors with the low-precision result, regardless of the return error code, in order to reduce the chance of unpredictable behavior, even if the user does not check the returned error status (which of course they should).

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | NOVAS_EARTH (3) or NOVAS_SUN (10) only.
  | origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here).
  [out] | position | [AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0.
  [out] | velocity | [AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day.

Returns
  0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), or if one of the output pointer arguments is NULL (errno set to EINVAL). 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the high-precision orbital data cannot be produced (default return value).

See also
  enable_earth_sun_hp(), earth_sun_calc(), set_planet_provider_hp()

References earth_sun_calc().

## ecl2equ()

int ecl2equ | ( | double | jd_tt,
|  | enum novas_equator_type | coord_sys,
|  | enum novas_accuracy | accuracy,
|  | double | elon,
|  | double | elat,
|  | double *restrict | ra,
|  | double *restrict | dec )

Convert ecliptic longitude and latitude to right ascension and declination.

To convert GCRS ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at'jd_tt'.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
  | coord_sys | The astrometric reference system of the coordinates. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | elon | [deg] Ecliptic longitude in degrees, referred to the specified ecliptic and equinox of date.
  | elat | [deg] Ecliptic latitude in degrees, referred to the specified ecliptic and equinox of date.
  [out] | ra | [h] Right ascension in hours, referred to specified equator and equinox of date.
  [out] | dec | [deg] Declination in degrees, referred to specified equator and equinox of date.

Returns
  0 if successful, or else 1 if the value of 'coord_sys' is invalid.

Since
  1.0

Author
  Attila Kovacs

See also
  ecl2equ_vec(), equ2ecl()

References ecl2equ_vec().

Referenced by supernovas::Ecliptic::to_equatorial().

## ecl2equ_vec()

short ecl2equ_vec | ( | double | jd_tt,
|  | enum novas_equator_type | coord_sys,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Converts an ecliptic position vector to an equatorial position vector.

To convert ecliptic coordinates (mean ecliptic and equinox of J2000.0) to GCRS RA and dec to, set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
  | coord_sys | The astrometric reference system type of the coordinates
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Position vector, referred to the specified ecliptic and equinox of date.
  [out] | out | Position vector, referred to the specified equator and equinox of date. It can be the same vector as the input.

Returns
  0 if successful, -1 if either vector argument is NULL or the accuracy is invalid, or else 1 if the value of 'coord_sys' is invalid.

See also
  ecl2equ(), equ2ecl_vec()

References e_tilt(), frame_tie(), J2000_TO_ICRS, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_GCRS_EQUATOR, NOVAS_MEAN_EQUATOR, NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUATOR.

Referenced by ecl2equ(), and novas_moon_elp_posvel_fp().

## enable_earth_sun_hp()

void enable_earth_sun_hp | ( | int | value | ) |

Specify whether the high-precision call is allowed to return a low-precision result.

If set to 0 (false) solarsystem_earth_sun_hp() will return with an error code 3 indicating that a high-precision calculation is not possible. Otherise, a non-zero value (true) will let the function to be used without errors, returning the low-precision result of solarsystem_earth_sun() instead.

Parameters

  value | (boolean) A non-zero value enables the error-free use of the earth_sun_calc_hp() by allowing to return the low-precision result. Otherwise, earth_sun_calc_hp() will return an error code 3 indicating that the high-precision result is not available (this latter is the default behavior).

See also
  earth_sun_calc_hp()

## ephemeris()

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

Retrieves the position and velocity of a solar system body using the currently configured plugins that provide them.

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

Parameters

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

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

See also
  set_planet_provider(), set_planet_provider_hp(), set_ephem_provider()
  make_planet(), make_ephem_object()

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

Referenced by supernovas::SolarSystemSource::barycentric_at(), ephemeris(), geo_posvel(), light_time2(), novas_helio_dist(), novas_make_frame(), obs_posvel(), and place().

## equ2ecl()

short equ2ecl | ( | double | jd_tt,
|  | enum novas_equator_type | coord_sys,
|  | enum novas_accuracy | accuracy,
|  | double | ra,
|  | double | dec,
|  | double *restrict | elon,
|  | double *restrict | elat )

Convert right ascension and declination to ecliptic longitude and latitude.

To convert GCRS RA and dec to ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
  | coord_sys | The astrometric reference system of the coordinates. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | ra | [h] Right ascension in hours, referred to the specified equator and equinox of date.
  | dec | [deg] Declination in degrees, referred to the specified equator and equinox of date.
  [out] | elon | [deg] Ecliptic longitude in degrees, referred to specified ecliptic and equinox of date.
  [out] | elat | [deg] Ecliptic latitude in degrees, referred to specified ecliptic and equinox of date.

Returns
  0 if successful, or else 1 if the value of 'coord_sys' is invalid.

See also
  equ2ecl_vec(), ecl2equ()

References equ2ecl_vec().

Referenced by supernovas::Equatorial::to_ecliptic().

## equ2ecl_vec()

short equ2ecl_vec | ( | double | jd_tt,
|  | enum novas_equator_type | coord_sys,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Converts an equatorial position vector to an ecliptic position vector.

To convert ICRS RA and dec to ecliptic coordinates (mean ecliptic and equinox of J2000.0), set 'coord_sys' to NOVAS_GCRS_EQUATOR(2); in this case the value of 'jd_tt' can be set to anything, since J2000.0 is assumed. Otherwise, all input coordinates are dynamical at 'jd_tt'.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_GCRS_EQUATOR[2])
  | coord_sys | The astrometric reference system type of the coordinates.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Position vector, referred to the specified equator and equinox of date.
  [out] | out | Position vector, referred to the specified ecliptic and equinox of date. It can be the same vector as the input. If 'coord_sys' is NOVAS_GCRS_EQUATOR(2), the input GCRS coordinates are converted to J2000 ecliptic coordinates.

Returns
  0 if successful, -1 if either vector argument is NULL or the accuracy is invalid, or else 1 if the value of 'coord_sys' is invalid.

See also
  equ2ecl(), ecl2equ_vec()

References e_tilt(), frame_tie(), ICRS_TO_J2000, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_GCRS_EQUATOR, NOVAS_MEAN_EQUATOR, NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUATOR.

Referenced by equ2ecl().

## equ2gal()

int equ2gal | ( | double | ra,
|  | double | dec,
|  | double *restrict | glon,
|  | double *restrict | glat )

Converts ICRS right ascension and declination to galactic longitude and latitude.

REFERENCES:

1. J.-C. Liu, Z. Zhu, and H. Zhang, A&A, 526, A16 (2011), Eq. 18
2. Hipparcos and Tycho Catalogues, Vol. 1, Section 1.5.3.

Parameters

  | ra | [h] ICRS right ascension in hours.
  | dec | [deg] ICRS declination in degrees.
  [out] | glon | [deg] Galactic longitude in degrees.
  [out] | glat | [deg] Galactic latitude in degrees.

Returns
  0 if successful, or -1 if either of the output pointer arguments are NULL.

See also
  gal2equ()

Referenced by supernovas::Equatorial::to_galactic().

## era()

double era | ( | double | jd_ut1_high,
|  | double | jd_ut1_low )

Returns the value of the Earth Rotation Angle (θ) for a given UT1 Julian date.

The expression used is taken from the note to IAU Resolution B1.8 of 2000. The input Julian date can be split into an into high and low order parts (e.g. integer and fractional parts) for improved accuracy, or else one of the components (e.g. the low part) can be set to zero if no split is desired.

The algorithm used here is equivalent to the canonical θ = 0.7790572732640 + 1.00273781191135448 * t, where t is the time in days from J2000 (t = jd_high + jd_low - JD_J2000), but it avoids many two-PI 'wraps' that decrease precision (adopted from SOFA Fortran routine iau_era00).

REFERENCES:

1. IERS Conventions 2010, Chapter 5, Eq. 5.15
2. IAU Resolution B1.8, adopted at the 2000 IAU General Assembly, Manchester, UK.
3. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  jd_ut1_high | [day] High-order part of UT1 Julian date.
  jd_ut1_low | [day] Low-order part of UT1 Julian date.

Returns
  [deg] The Earth Rotation Angle (theta) in degrees [0:360].

See also
  novas_gast(), novas_time_gst()
  cirs_to_itrs(), itrs_to_cirs()

Referenced by cel2ter(), novas_gmst(), novas_make_frame(), place(), and ter2cel().

## frame_tie()

int frame_tie | ( | const double * | in,
|  | enum novas_frametie_direction | direction,
|  | double * | out )

Transforms a vector from the dynamical reference system to the International Celestial Reference System (ICRS), or vice versa.

The dynamical reference system is based on the dynamical mean equator and equinox of J2000.0. The ICRS is based on the space-fixed ICRS axes defined by the radio catalog positions of several hundred extragalactic objects.

For geocentric coordinates, the same transformation is used between the dynamical reference system and the GCRS.

NOTES:

1. More efficient 3D rotation implementation for small angles by A. Kovacs

REFERENCES:

1. Hilton, J. and Hohenkerk, C. (2004), Astronomy and Astrophysics 413, 765-770, eq. (6) and (8).
2. IERS (2003) Conventions, Chapter 5.

Parameters

  | in | Position vector, equatorial rectangular coordinates.
  | direction | <0 for dynamical to ICRS transformation, or else >=0 for ICRS to dynamical transformation. Alternatively you may use the constants J2000_TO_ICRS (-1; or negative) or ICRS_TO_J2000 (0; or positive).
  [out] | out | Position vector, equatorial rectangular coordinates. It can be the same vector as the input.

Returns
  0 if successfor or -1 if either of the vector arguments is NULL.

See also
  j2000_to_gcrs(), gcrs_to_j2000()

Referenced by ecl2equ_vec(), equ2ecl_vec(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), j2000_to_gcrs(), mod_to_gcrs(), tod_to_gcrs(), and transform_cat().

## fund_args()

int fund_args | ( | double | t,
|  | novas_delaunay_args *restrict | a )

Compute the fundamental (a.k.a.

Delaunay) arguments (mean elements) of the Sun and Moon.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, Eq. 5.43.
2. Simon et al. (1994) Astronomy and Astrophysics 282, 663-683, esp. Sections 3.4-3.5.

Parameters

  | t | [cy] TDB time in Julian centuries since J2000.0
  [out] | a | [rad] Fundamental arguments data to populate (5 doubles) [0:2π]

Returns
  0 if successful, or -1 if the output pointer argument is NULL.

See also
  nutation_angles(), e_tilt(), NOVAS_JD_J2000

References novas_norm_ang().

Referenced by novas_diurnal_eop_at_time(), and nu2000k().

## gal2equ()

int gal2equ | ( | double | glon,
|  | double | glat,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts galactic longitude and latitude to ICRS right ascension and declination.

REFERENCES:

1. J.-C. Liu, Z. Zhu, and H. Zhang, A&A, 526, A16 (2011), Eq. 18
2. Hipparcos and Tycho Catalogues, Vol. 1, Section 1.5.3.

Parameters

  | glon | [deg] Galactic longitude in degrees.
  | glat | [deg] Galactic latitude in degrees.
  [out] | ra | [h] ICRS right ascension in hours.
  [out] | dec | [deg] ICRS declination in degrees.

Returns
  0 if successful, or -1 if either of the output pointer arguments are NULL.

Since
  1.0

Author
  Attila Kovacs

See also
  equ2gal()

Referenced by supernovas::Galactic::to_equatorial().

## gcrs2equ()

short gcrs2equ | ( | double | jd_tt,
|  | enum novas_dynamical_type | sys,
|  | enum novas_accuracy | accuracy,
|  | double | rag,
|  | double | decg,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts GCRS right ascension and declination to coordinates with respect to the equator of date (mean or true).

For coordinates with respect to the true equator of date, the origin of right ascension can be either the true equinox or the celestial intermediate origin (CIO). This function only supports the CIO-based method.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_ICRS_EQUATOR)
  | sys | Dynamical equatorial system type
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1) (unused if 'coord_sys' is not NOVAS_ICRS [3])
  | rag | [h] GCRS right ascension in hours.
  | decg | [deg] GCRS declination in degrees.
  [out] | ra | [h] Right ascension in hours, referred to specified equator and right ascension origin of date.
  [out] | dec | [deg] Declination in degrees, referred to specified equator of date.

Returns
  0 if successful, or -1 with errno set to EINVAL if the output pointers are NULL, or sys and/or accuracy is invalid; otherwise <0 if an error from vector2radec(); 10–20 error is 10 + error cio_location(); or else 20 + error from cio_basis()

See also
  gcrs_to_tod(), gcrs_to_mod(), gcrs_to_cirs(), novas_transform_sky_pos()

References gcrs_to_cirs(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_DYNAMICAL_CIRS, NOVAS_DYNAMICAL_MOD, NOVAS_DYNAMICAL_TOD, radec2vector(), and vector2radec().

## gcrs_to_cirs()

int gcrs_to_cirs | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Celestial Intermediate Reference System (CIRS) frame at the given epoch.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

This function uses Method 2 of the IERS Conventions 2010 (Chapter 5, Section 5.9), first applying the frame bias to convert GCRS to J2000, then using the IAU 2006 precession-nutation model (P03; Capitaine et al. 2003) to convert to TOD, and finally to CIRS via a rotation by the equation of origins.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, especially Section 5.9
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or else 10 + the error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  gcrs_to_j2000(), cirs_to_gcrs(), novas_icrs_to_sys()

References gcrs_to_tod(), and tod_to_cirs().

Referenced by cel2ter(), gcrs2equ(), novas_icrs_to_sys(), and place().

## gcrs_to_j2000()

int gcrs_to_j2000 | ( | const double * | in,
|  | double * | out )

Changes ICRS / GCRS coordinates to J2000 coordinates.

Same as frame_tie() called with ICRS_TO_J2000. (We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | in | ICRS / GCRS input 3-vector
  [out] | out | J2000 output 3-vector

Returns
  0 if successful, or else an error from frame_tie()

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_gcrs(), tod_to_j2000(), novas_icrs_to_sys()

References frame_tie(), and ICRS_TO_J2000.

Referenced by novas_icrs_to_sys().

## gcrs_to_mod()

int gcrs_to_mod | ( | double | jd_tdb,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the Mean of Date (MOD) reference frame at the given epoch.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the Mean wquinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  mod_to_gcrs(), gcrs_to_tod(), novas_icrs_to_sys()

References frame_tie(), ICRS_TO_J2000, NOVAS_JD_J2000, and precession().

Referenced by gcrs2equ(), and novas_icrs_to_sys().

## gcrs_to_tod()

int gcrs_to_tod | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the ICRS / GCRS to the True of Date (TOD) reference frame at the given epoch.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | ICRS / GCRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL, or if the accuracy argument is invalid.

Since
  1.2

Author
  Attila Kovacs

See also
  gcrs_to_cirs(), tod_to_gcrs(), j2000_to_tod(), novas_icrs_to_sys()

References frame_tie(), ICRS_TO_J2000, and j2000_to_tod().

Referenced by cel2ter(), gcrs2equ(), gcrs_to_cirs(), and novas_icrs_to_sys().

## geo_posvel()

short geo_posvel | ( | double | jd_tt,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | const observer *restrict | obs,
|  | double *restrict | pos,
|  | double *restrict | vel )

Computes the geocentric GCRS position and velocity of an observer.

NOTES:

- For Earth-based observers, this function does not include polar wobble corrections, so the returned GCRS positions are accurate at the tens of meters level only. You might use novas_site_gcrs_posvel() instead if higher accuracy is required for Earth-based observers.

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | obs | observer location.
  [out] | pos | [AU] Position 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU. (It may be NULL if not required.)
  [out] | vel | [AU/day] Velocity 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU/day. (It must be distinct from the pos output vector, and may be NULL if not required)

Returns
  0 if successful, -1 if the 'obs' is NULL or the two output vectors are the same, or else 1 if 'accuracy' is invalid, or 2 if 'obserrver->where' is invalid.

See also
  novas_site_gcrs_posvel(), novas_make_frame(), make_observer(), get_ut1_to_tt()

References ephemeris(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_DEBUG_EXTRA, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, novas_gast(), novas_get_debug_mode(), NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_REDUCED_ACCURACY, NOVAS_SOLAR_SYSTEM_OBSERVER, terra(), tod_to_gcrs(), and tt2tdb().

Referenced by supernovas::Observer::gcrs_position_at(), supernovas::Observer::gcrs_velocity_at(), and obs_posvel().

## get_ut1_to_tt()

double get_ut1_to_tt | ( | int | leap_seconds,
|  | double | dut1 )

Returns the TT - UT1 time difference given the leap seconds and the actual UT1 - UTC time difference as measured and published by IERS.

NOTES:

1. The current UT1 - UTC time difference, and polar offsets, historical data and near-term projections are published in the IERS Bulletins

Parameters

  leap_seconds | [s] Leap seconds at the time of observations
  dut1 | [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent.

Returns
  [s] The TT - UT1 time difference that is suitable for use with all calls in this library that require a ut1_to_tt argument. It includes diurnal corrections for libration and ocean tides.

Since
  1.0

Author
  Attila Kovacs

See also
  get_utc_to_tt(), novas_set_time(), novas_gast(), novas_time_gst(), novas_time_lst()

References get_utc_to_tt().

## get_utc_to_tt()

double get_utc_to_tt | ( | int | leap_seconds | ) |

Returns the difference between Terrestrial Time (TT) and Universal Coordinated Time (UTC).

Parameters

  leap_seconds | [s] The current leap seconds (see IERS Bulletins)

Returns
  [s] The TT - UTC time difference

Since
  1.0

Author
  Attila Kovacs

See also
  get_ut1_to_tt()

References NOVAS_TAI_TO_TT.

Referenced by get_ut1_to_tt().

## grav_def()

short grav_def | ( | double | jd_tdb,
|  | enum novas_observer_place | unused,
|  | enum novas_accuracy | accuracy,
|  | const double * | pos_src,
|  | const double * | pos_obs,
|  | double * | out )

(primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the major gravitating bodies in the solar system.

This function valid for an observed body within the solar system as well as for a star.

If 'accuracy' is NOVAS_FULL_ACCURACY (0), the deflections due to the Sun, Jupiter, Saturn, and Earth are calculated. Otherwise, only the deflection due to the Sun is calculated. In either case, deflection for a given body is ignored if the observer is within ~1500 km of the center of the gravitating body.

The number of bodies used at full and reduced accuracy can be set by changing the grav_bodies_reduced_accuracy, and grav_bodies_full_accuracy lobal variables.

NOTES:

1. This function is called by novas_sky_pos(), novas_app_to_geom(), novas_geom_to_app() and place() to calculate gravitational deflections as appropriate for positioning sources precisely. The gravitational deflection due to planets requires a planet calculator function to be configured, e.g. via set_planet_provider_hp().

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | unused | The type of observer frame (no longer used)
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated.
  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  [out] | out | [AU] Position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, corrected for gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs, or the error from obs_planets().

See also
  grav_undef()
  novas_sky_pos(), novas_geom_to_app(), novas_app_to_geom(), set_planet_provider_hp(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy

References grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_planets(), NOVAS_FULL_ACCURACY, and obs_planets().

## grav_planets()

int grav_planets | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | const novas_planet_bundle *restrict | planets,
|  | double * | out )

(primarily for internal use) Computes the total gravitational deflection of light for the observed object due to the specified gravitating bodies in the solar system.

This function is valid for an observed body within the solar system as well as for a star.

NOTES:

1. The gravitational deflection due to planets requires a planet calculator function to be configured, e.g. via set_planet_provider_hp().

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  | planets | Apparent planet data containing positions and velocities for the major gravitating bodies in the solar-system.
  [out] | out | [AU] Position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, corrected for gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs.

See also
  grav_def(), grav_undo_planets()
  novas_sky_pos(), novas_geom_to_app(), obs_planets()

Since
  1.1

Author
  Attila Kovacs

References d_light(), grav_vec(), NOVAS_PLANETS, NOVAS_RMASS_INIT, and novas_vlen().

Referenced by grav_def(), grav_undo_planets(), novas_geom_to_app(), novas_sky_pos(), and place().

## grav_redshift()

double grav_redshift | ( | double | M_kg,
|  | double | r_m )

Returns the gravitational redshift (z) for light emitted near a massive spherical body at some distance from its center, and observed at some very large (infinite) distance away.

Parameters

  M_kg | [kg] Mass of gravitating body that is contained inside the emitting radius.
  r_m | [m] Radius at which light is emitted.

Returns
  The gravitational redshift (z) for an observer at very large (infinite) distance from the gravitating body.

See also
  redshift_vrad(), unredshift_vrad(), novas_z_add()

Since
  1.2

Author
  Attila Kovacs

## grav_undef()

int grav_undef | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | pos_app,
|  | const double * | pos_obs,
|  | double * | out )

(primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the major gravitating bodies in the solar system.

This function is valid for an observed body within the solar system as well as for a star.

If 'accuracy' is set to zero (full accuracy), three bodies (Sun, Jupiter, and Saturn) are used in the calculation. If the reduced-accuracy option is set, only the Sun is used in the calculation. In both cases, if the observer is not at the geocenter, the deflection due to the Earth is included.

he number of bodies used at full and reduced accuracy can be set by changing the grav_bodies_reduced_accuracy, and grav_bodies_full_accuracy global variables.

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | pos_app | [AU] Apparent position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  [out] | out | [AU] Nominal position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, without gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL (errno = EINVAL) or if the result did not converge (errno = ECANCELED), or else an error from obs_planets().

See also
  grav_def()
  novas_app_to_geom(), set_planet_provider_hp(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy

Since
  1.1

Author
  Attila Kovacs

References grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_undo_planets(), NOVAS_FULL_ACCURACY, and obs_planets().

## grav_undo_planets()

int grav_undo_planets | ( | const double * | pos_app,
|  | const double * | pos_obs,
|  | const novas_planet_bundle *restrict | planets,
|  | double * | out )

(primarily for internal use) Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.

REFERENCES:

1. Klioner, S. (2003), Astronomical Journal 125, 1580-1597, Section 6.

Parameters

  | pos_app | [AU] Apparent position 3-vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, components in AU.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes, components in AU.
  | planets | Apparent planet data containing positions and velocities for the major gravitating bodies in the solar-system.
  [out] | out | [AU] Nominal position vector of observed object, with respect to origin at observer (or the geocenter), referred to ICRS axes, without gravitational deflection, components in AU. It can be the same vector as the input, but not the same as pos_obs.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL.

See also
  grav_planets(), grav_undef()
  novas_app_to_geom(), obs_planets()

Since
  1.1

Author
  Attila Kovacs

References grav_planets(), novas_inv_max_iter, and novas_vlen().

Referenced by grav_undef(), and novas_app_to_geom().

## grav_vec()

int grav_vec | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | const double * | pos_body,
|  | double | rmass,
|  | double * | out )

(primarily for internal use) Corrects position vector for the deflection of light in the gravitational field of anarbitrary body.

This function valid for an observed body within the solar system as well as for a star.

NOTES:

1. This function is called by grav_def() to calculate appropriate gravitational deflections around the massive Solar-system objects.

REFERENCES:

1. Murray, C.A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
2. See also formulae in Section B of the Astronomical Almanac, or
3. Kaplan, G. et al. (1989) Astronomical Journal 97, 1197-1210, section iii f.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), components in AU.
  | pos_obs | [AU] Position vector of gravitating body, with respect to origin at solar system barycenter, components in AU.
  | pos_body | [AU] Position 3-vector of gravitating body, with respect to origin at solar system barycenter, components in AU.
  | rmass | [1/Msun] Reciprocal mass of gravitating body in solar mass units, that is, Sun mass / body mass.
  [out] | out | [AU] Position 3-vector of observed object, with respect to origin at observer (or the geocenter), corrected for gravitational deflection, components in AU. It can the same vector as the input.

Returns
  0 if successful, or -1 if any of the input vectors is NULL.

See also
  grav_def()

References NOVAS_AU, and novas_vlen().

Referenced by grav_planets().

## hor_to_itrs()

int hor_to_itrs | ( | const on_surface *restrict | location,
|  | double | az,
|  | double | za,
|  | double *restrict | itrs )

Converts astrometric (unrefracted) azimuth and zenith angles at the specified observer location to a unit position vector in the Earth-fixed ITRS frame.

Parameters

  | location | Geodetic (ITRF / GRS80) observer location on Earth
  | az | [deg] astrometric (unrefracted) azimuth angle at observer location [0:360]. It may be NULL if not required.
  | za | [deg] astrometric (unrefracted) zenith angle at observer location [0:180]. It may be NULL if not required.
  [out] | itrs | Unit 3-vector direction in Earth-fixed ITRS frame

Returns
  0 if successful, or else -1 if the location or the input vector is NULL.

Since
  1.0

Author
  Attila Kovacs

See also
  itrs_to_hor(), itrs_to_cirs(), itrs_to_tod(), refract()

Referenced by novas_hor_to_app().

## iau2000a()

int iau2000a | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double *restrict | dpsi,
|  | double *restrict | deps )

Computes the IAU 2000A high-precision nutation series for the specified date, to 0.1 μas accuracy.

It is rather expensive computationally.

NOTES:

1. As of SuperNOVAS v1.4.2, this function has been modified to replace the original IAU2000A model coefficients with the IAU2006 (a.k.a. IAU2000A R06) model coefficients, to provide an updated nutation model, which is dynamically consistent with the IAU2006 (P03) precession model of Capitaine et al. 2003. This is now the same model with respect to which the IERS Earth orientation parameters are computed and published.

REFERENCES:

1. IERS Conventions (2003), Chapter 5.
2. Simon et al. (1994) Astronomy and Astrophysics 282, 663-683, esp. Sections 3.4-3.5.
3. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.
4. https://hpiers.obspm.fr/eop-pc/models/nutations/nut.html

Parameters

  | jd_tt_high | [day] High-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the integer part of a split date for the highest precision, or the full date for normal (reduced) precision.
  | jd_tt_low | [day] Low-order part of the Terrestrial Time (TT) based Julian date. Typically, it may be the fractional part of a split date for the highest precision, or 0.0 for normal (reduced) precision.
  [out] | dpsi | [rad] δψ Nutation (luni-solar + planetary) in longitude. It may be NULL if not required.
  [out] | deps | [rad] δε Nutation (luni-solar + planetary) in obliquity. It may be NULL if not required.

Returns
  0

See also
  iau2000b(), nu2000k(), nutation_angles(), nutation()

Referenced by nutation_angles().

## iau2000b()

int iau2000b | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double *restrict | dpsi,
|  | double *restrict | deps )

Computes the forced nutation of the non-rigid Earth based at reduced precision.

It reproduces the IAU 2000A (R06) model to a precision of 1 milliarcsecond in the interval 1995-2020, while being about 15x faster than iau2000a().

NOTES

1. Originally this was the IAU2000B series of McCarthy & Luzum (2003), consistent with the original IAU2000 precession model
2. As of SuperNOVAS v1.4.2, this function has been modified to use a truncated series for the IAU2006 (a.k.a. IAU 2000A R06) nutation model, whereby terms with amplitudes larger than 100 μas are omitted, resulting in 102 terms for the longitude and 57 terms the obliquity. This results in similar, or slightly better, precision than the original IAU2000B series of McCarthy & Luzum (2003), and it is now dynamically consistent with the IAU2006 (P03) precession model (Capitaine et al. 2005).

REFERENCES:

1. McCarthy, D. and Luzum, B. (2003). "An Abridged Model of the Precession &amp; Nutation of the Celestial Pole," Celestial Mechanics and Dynamical Astronomy, Volume 85, Issue 1, Jan. 2003, p. 37. (IAU 2000B) IERS Conventions (2003), Chapter 5.
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.

Parameters

  | jd_tt_high | [day] High-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the integer part of a split date for the highest precision, or the full date for normal (reduced) precision.
  | jd_tt_low | [day] Low-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the fractional part of a split date for the highest precision, or 0.0 for normal (reduced) precision.
  [out] | dpsi | [rad] δψ Nutation (luni-solar + planetary) in longitude, It may be NULL if not required.
  [out] | deps | [rad] δε Nutation (luni-solar + planetary) in obliquity. It may be NULL if not required.

Returns
  0

See also
  iau2000a(), nu2000k(), nutation_angles(), set_nutation_lp_provider(), nutation()

## ira_equinox()

double ira_equinox | ( | double | jd_tdb,
|  | enum novas_equinox_type | equinox,
|  | enum novas_accuracy | accuracy )

Compute the intermediate right ascension of the equinox at the input Julian date, using an analytical expression for the accumulated precession in right ascension.

For the true equinox, the result is the equation of the origins.

NOTES:

1. Fixes bug in NOVAS C 3.1, which returned the value for the wrong 'equinox' if 'equinox = 1' was requested for the same 'jd_tbd' and 'accuracy' as a the preceding call with 'equinox = 0'. As a result, the caller ended up with the mean instead of the expected true equinox R.A. value.

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).

Parameters

  jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date
  equinox | NOVAS_MEAN_EQUINOX (0) or NOVAS_TRUE_EQUINOX (1, or non-zero)
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1, or non-zero)

Returns
  [h] Intermediate right ascension of the equinox, in hours (+ or -). If 'equinox' = 1 (i.e true equinox), then the returned value is the equation of the origins.

See also
  cio_ra()
  gcrs_to_cirs(), cirs_to_gcrs()

References e_tilt(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

Referenced by cio_location(), cio_ra(), cirs_to_tod(), novas_hor_track(), supernovas::Equatorial::to_ecliptic(), and tod_to_cirs().

## itrs_to_cirs()

int itrs_to_cirs | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Rotates a position vector from the Earth-fixed ITRS frame to the dynamical CIRS frame of date (IAU 2000 standard method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  itrs_to_tod(), cirs_to_itrs(), cirs_to_gcrs()

References ter2cel().

## itrs_to_hor()

int itrs_to_hor | ( | const on_surface *restrict | location,
|  | const double *restrict | itrs,
|  | double *restrict | az,
|  | double *restrict | za )

Converts a position vector in the Earth-fixed ITRS frame to astrometric (unrefracted) azimuth and zenith angles at the specified observer location.

Parameters

  | location | Geodetic (ITRF / GRS80) observer location on Earth.
  | itrs | 3-vector position in Earth-fixed ITRS frame
  [out] | az | [deg] astrometric (unrefracted) azimuth angle at observer location [0:360]. It may be NULL if not required.
  [out] | za | [deg] astrometric (unrefracted) zenith angle at observer location [0:180]. It may be NULL if not required.

Returns
  0 if successful, or else -1 if the location or the input vector is NULL.

Since
  1.0

Author
  Attila Kovacs

See also
  hor_to_itrs(), cirs_to_itrs(), tod_to_itrs(), refract_astro()

Referenced by novas_app_to_hor().

## itrs_to_tod()

int itrs_to_tod | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Rotates a position vector from the Earth-fixed ITRS frame to the dynamical True of Date (TOD) frame of date (pre IAU 2000 method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system)

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  itrs_to_cirs(), tod_to_itrs(), tod_to_j2000()

References ter2cel().

Referenced by novas_site_gcrs_posvel().

## j2000_to_gcrs()

int j2000_to_gcrs | ( | const double * | in,
|  | double * | out )

Change J2000 coordinates to ICRS / GCRS coordinates.

Same as frame_tie() called with J2000_TO_ICRS. (We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | in | J2000 input 3-vector
  [out] | out | ICRS / GCRS output 3-vector

Returns
  0 if successful, or else an error from frame_tie()

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_tod(), gcrs_to_j2000(), novas_sys_to_icrs()

References frame_tie(), and J2000_TO_ICRS.

Referenced by novas_sys_to_icrs().

## j2000_to_tod()

int j2000_to_tod | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from J2000 coordinates to the True of Date (TOD) reference frame at the given epoch.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity vector in rectangular equatorial coordinates at J2000
  [out] | out | Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid.

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_gcrs(), tod_to_j2000(), gcrs_to_j2000()

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_MEAN_TO_TRUE, nutation(), and precession().

Referenced by gcrs_to_tod().

## julian_date()

double julian_date | ( | short | year,
|  | short | month,
|  | short | day,
|  | double | hour )

Returns the Julian day for a given astronomical calendar date.

Input time value can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output Julian day will have the same basis.

NOTES:

1. The Gregorian calendar was introduced on 1582 October 15 only. Prior to that, astronomical dates are Julian/Roman dates, so the day before the reform was 1582 October 4. You can also use novas_jd_from_date() to convert dates with more flexibility.
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.
3. Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

  year | [yr] Astronomical calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
  month | [month] Astronomical calendar month [1:12]
  day | [day] Astronomical day of month [1:31]
  hour | [hr] Hour of day [0:24]

Returns
  [day] the fractional Julian date for the input calendar date, ot NAN if the month or day components are out of range.

See also
  novas_jd_from_date()
  get_utc_to_tt(), get_ut1_to_tt(), tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_from_date().

## light_time()

short light_time | ( | double | jd_tdb,
|  | const object *restrict | body,
|  | const double * | pos_obs,
|  | double | tlight0,
|  | enum novas_accuracy | accuracy,
|  | double * | pos_src_obs,
|  | double *restrict | tlight )

Computes the geocentric position of a solar system body, as antedated for light-time.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | Pointer to structure containing the designation for the solar system body
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | tlight0 | [day] First approximation to light-time (can be set to 0.0 if not readily available – it will then be computed as needed).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | pos_src_obs | [AU] Position 3-vector of body, with respect to origin at observer (or the geocenter), referred to ICRS axes. It can be the same vector as either of the inputs.
  [out] | tlight | [day] Calculated light time

Returns
  0 if successful, -1 if any of the pointer arguments is NULL, 1 if the algorithm failed to converge after 10 iterations, or 10 + the error from ephemeris().

See also
  light_time2(), novas_make_frame()

References light_time2().

## light_time2()

int light_time2 | ( | double | jd_tdb,
|  | const object *restrict | body,
|  | const double *restrict | pos_obs,
|  | double | tlight0,
|  | enum novas_accuracy | accuracy,
|  | double * | p_src_obs,
|  | double *restrict | v_ssb,
|  | double *restrict | tlight )

Computes the geocentric position and velocity of a solar system body, as antedated for light-time.

It is effectively the same as the original NOVAS C light_time(), except that this returns the antedated source velocity vector also.

NOTES:

1. This function is called by novas_geom_posvel() or place() to calculate observed positions, radial velocity, and distance for the time when the observed light originated from the source.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | body | Pointer to structure containing the designation for the solar system body
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | tlight0 | [day] First approximation to light-time (can be set to 0.0 if not readily available – so it will be calculated as needed).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | p_src_obs | [AU] Position 3-vector of body, relative to observer, referred to ICRS axes, components in AU.
  [out] | v_ssb | [AU/day] Velocity 3-vector of body, with respect to the Solar-system barycenter, referred to ICRS axes.
  [out] | tlight | [day] Calculated light time, or NAN when returning with an error code.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vectors are the same or if they are the same as pos_obs, 1 if the algorithm failed to converge after 10 iterations, or 10 + the error from ephemeris().

See also
  light_time()
  novas_sky_pos()

Since
  1.0

Author
  Attila Kovacs

References bary2obs(), ephemeris(), NOVAS_BARYCENTER, NOVAS_FULL_ACCURACY, and novas_inv_max_iter.

Referenced by light_time(), novas_geom_posvel(), obs_planets(), and place().

## limb_angle()

int limb_angle | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | double *restrict | limb_ang,
|  | double *restrict | nadir_ang )

Determines the angle of an object above or below the Earth's limb (horizon).

The geometric limb is computed, assuming the Earth to be an airless sphere (no refraction or oblateness is included). The observer can be on or above the Earth. For an observer on the surface of the Earth, this function returns the approximate unrefracted elevation.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at geocenter, components in AU.
  | pos_obs | [AU] Position 3-vector of observer, with respect to origin at geocenter, components in AU.
  [out] | limb_ang | [deg] Angle of observed object above (+) or below (-) limb in degrees, or NAN if reurning with an error. It may be NULL if not required.
  [out] | nadir_ang | Nadir angle of observed object as a fraction of apparent radius of limb: lt;1.0 if below the limb; 1.0 on the limb; or >1.0 if above the limb. Returns NAN in case of an error return. It may be NULL if not required.

Returns
  0 if successful, or -1 if either of the input vectors is NULL or if either input position is a null vector (at the geocenter).

References M_PI, and novas_vlen().

## make_airborne_observer()

int make_airborne_observer | ( | const on_surface * | location,
|  | const double * | itrs_vel,
|  | observer * | obs )

Populates an 'observer' data structure for an observer moving relative to the surface of Earth, such as an airborne observer.

Airborne observers have an earth fixed momentary location, defined by longitude, latitude, and altitude, the same was as for a stationary observer on Earth, but are moving relative to the surface, such as in an aircraft or balloon observatory.

Parameters

  | location | Current geodetic location, e.g. as populated with make_gps_site() or similar.
  | itrs_vel | [km/s] Surface velocity (in ITRS).
  [out] | obs | Pointer to data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_itrf_site(), make_gps_site(), make_xyz_site()
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_observer_in_space(), make_solar_system_observer(), make_observer_at_geocenter(), novas_make_frame()

Since
  1.1

Author
  Attila Kovacs

See also
  novas_enu_to_itrs()

References IN_SPACE_INIT, make_observer(), NOVAS_AIRBORNE_OBSERVER, and novas_in_space::sc_vel.

Referenced by supernovas::GeodeticObserver::GeodeticObserver().

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

int make_gps_observer | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | observer * | obs )

Initializes an observer data structure for a ground-based observer with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.

For the highest (μas / mm level) precision, you probably should use an ITRF location instead of a GPS based location.

Parameters

  | latitude | [deg] Geodetic (GPS / WGS84) latitude north positive.
  | longitude | [deg] Geodetic (GPS / WGS84) longitude east positive.
  | height | [m] Geodetic (GPS / WGS84) altitude above sea level of the observer.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_gps_site(), novas_set_default_weather(), novas_make_frame(), novas_geodetic_transform_site()

References make_gps_site(), and make_observer_at_site().

## make_gps_site()

int make_gps_site | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | on_surface * | site )

Initializes an observing site with the specified GPS / WGS84 location, and sets mean (annual) weather parameters based on that location.

For the highest (μas / mm level) precision, you probably should use an ITRF location instead of a GPS based location.

Parameters

  | latitude | [deg] Geodetic (GPS / WGS84) latitude; north positive.
  | longitude | [deg] Geodetic (GPS / WGS84) longitude; east positive.
  | height | [m] Geodetic (GPS / WGS84) altitude above sea level of the observer.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_xyz_site()
  make_itrf_observer(), make_observer_at_site(), novas_set_default_weather()

References make_itrf_site(), novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, and NOVAS_WGS84_ELLIPSOID.

Referenced by make_gps_observer().

## make_in_space()

int make_in_space | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | in_space * | loc )

Populates an 'in_space' data structure, for an observer situated on a near-Earth spacecraft, with the provided position and velocity components.

Both input vectors are assumed with respect to true equator and equinox of date.

Parameters

  | sc_pos | [km] Geocentric (x, y, z) position vector. NULL defaults to the origin
  | sc_vel | [km/s] Geocentric (x, y, z) velocity vector. NULL defaults to zero speed.
  [out] | loc | Pointer to earth-orbit location data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_observer_in_space(), IN_SPACE_INIT

References novas_in_space::sc_pos, and novas_in_space::sc_vel.

Referenced by make_observer_in_space(), and make_solar_system_observer().

## make_itrf_observer()

int make_itrf_observer | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | observer * | obs )

Initializes an observer data structure for a ground-based observer with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the location provided here and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform_eop() to change the ITRF realization for the EOP values, if necessary.

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_itrf_site(), novas_itrf_transform_site(), novas_set_default_weather(), novas_make_frame()

References make_itrf_site(), and make_observer_at_site().

## make_itrf_site()

int make_itrf_site | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | on_surface * | site )

Initializes an observing site with the specified International Terrestrial Reference Frame (ITRF) / GRS80 location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the location provided here and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform_eop() to change the ITRF realization for the EOP values, if necessary.

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_xyz_site()
  make_itrf_observer(), make_observer_at_site(), novas_set_default_weather(), novas_itrf_transform_site(), novas_itrf_transform_eop()

References novas_on_surface::height, novas_on_surface::latitude, novas_on_surface::longitude, and novas_set_default_weather().

Referenced by supernovas::Site::Site(), make_gps_site(), make_itrf_observer(), make_on_surface(), and make_xyz_site().

## make_observer_at_geocenter()

int make_observer_at_geocenter | ( | observer *restrict | obs | ) |

Populates an 'observer' data structure for a hypothetical observer located at Earth's geocenter.

The output data structure may be used as the inputs to NOVAS-C functions, such as make_frame() or place().

Parameters

  [out] | obs | Pointer to data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_solar_system_observer()
  novas_make_frame()

References make_observer(), and NOVAS_OBSERVER_AT_GEOCENTER.

Referenced by place().

## make_observer_at_site()

int make_observer_at_site | ( | const on_surface *restrict | site,
|  | observer *restrict | obs )

Initializes an observer data structure for a ground-based observer at the specified observing site, and sets mean (annual) weather parameters based on that location.

Parameters

  | site | Pointer to observing site data structure.
  [out] | obs | Pointer to the data structure to populate.

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

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_observer(), make_gps_observer(), make_airborne_observer(), make_observer_in_space(), make_observer_at_geocenter(), make_solar_system_observer()
  make_itrf_site(), make_gps_site(), make_xyz_site(), novas_make_frame()

References NOVAS_OBSERVER_ON_EARTH.

Referenced by local_planet(), local_star(), make_gps_observer(), make_itrf_observer(), topo_planet(), and topo_star().

## make_observer_in_space()

int make_observer_in_space | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | observer * | obs )

Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.

Both input vectors are with respect to true equator and equinox of date. The output data structure may be used as the inputs to NOVAS-C functions, such as make_frame() or place().

Parameters

  | sc_pos | [km] Geocentric (x, y, z) position vector.
  | sc_vel | [km/s] Geocentric (x, y, z) velocity vector.
  [out] | obs | Pointer to the data structure to populate

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_at_geocenter(), make_solar_system_observer()
  novas_make_frame()

References make_in_space(), make_observer(), and NOVAS_OBSERVER_IN_EARTH_ORBIT.

## make_observer_on_surface()

int make_observer_on_surface | ( | double | latitude,
|  | double | longitude,
|  | double | height,
|  | double | temperature,
|  | double | pressure,
|  | observer *restrict | obs )

Deprecated
  This old NOVAS C function has a few too many caveats. It is recommended that you use make_itrf_observer(), make_gps_observer(), or make_observer_at_site() instead (all of which set default mean annual weather parameters for approximate refraction correction), and optionally set actual weather data afterwards, based on the measurements available. This function will be available for the foreseeable future also.

Initializes an observer data structure with the specified ITRF / GRS80 location, and he specified local pressure and temperature. This old NOVAS C function does not set humidity. Thus, if humidity is needed for refraction correction, then you should set it explicitly after this call.

NOTES:

1. You can convert coordinates among ITRF realization using novas_itrf_transform(), possibly after novas_geodetic_to_cartesian() with NOVAS_GRS80_ELLIPSOID as necessary for polar ITRF coordinates.
2. You can convert ITRF Cartesian xyz locations to geodetic locations by using novas_cartesian_to_geodetic() with NOVAS_GRS80_ELLIPSOID as the reference ellipsoid parameter.
3. If you have longitude, latitude, and height defined as GPS (WGS84) values, you might want to use make_gps_observer() intead

Parameters

  | latitude | [deg] Geodetic (ITRF / GRS80) latitude; north positive.
  | longitude | [deg] Geodetic (ITRF / GRS80) longitude; east positive.
  | height | [m] Geodetic (ITRF / GRS80) altitude above sea level of the observer.
  | temperature | [C] Temperature (degrees Celsius).
  | pressure | [mbar] Atmospheric pressure.
  [out] | obs | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if the output argument is NULL, or if the latitude is outside of the [-90:90] range, or if the temperature or pressure values are impossible for an Earth based observer (errno set to ERANGE).

See also
  make_itrf_observer(), make_gps_observer(), make_observer_at_site()
  novas_set_weather(), novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, novas_make_frame()

References make_observer(), make_on_surface(), and NOVAS_OBSERVER_ON_EARTH.

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

## make_solar_system_observer()

int make_solar_system_observer | ( | const double * | sc_pos,
|  | const double * | sc_vel,
|  | observer * | obs )

Populates an 'observer' data structure, for an observer situated on a near-Earth spacecraft, with the specified geocentric position and velocity vectors.

Solar-system observers are similar to observers in Earth-orbit but their momentary position and velocity is defined relative to the Solar System Barycenter, instead of the geocenter.

Parameters

  | sc_pos | [AU] Solar-system barycentric (x, y, z) position vector in ICRS.
  | sc_vel | [AU/day] Solar-system barycentric (x, y, z) velocity vector in ICRS.
  [out] | obs | Pointer to the data structure to populate

Returns
  0 if successful, or -1 if the output argument is NULL.

See also
  make_gps_observer(), make_itrf_observer(), make_observer_at_site(), make_airborne_observer(), make_observer_in_space(), make_solar_system_observer()
  novas_make_frame()

Since
  1.1

Author
  Attila Kovacs

References make_in_space(), make_observer(), and NOVAS_SOLAR_SYSTEM_OBSERVER.

Referenced by supernovas::SolarSystemObserver::SolarSystemObserver(), and supernovas::SolarSystemObserver::SolarSystemObserver().

## make_xyz_site()

int make_xyz_site | ( | const double *restrict | xyz,
|  | on_surface *restrict | site )

Initializes an observing site with the specified Cartesian geocentric xyz location, and sets mean (annual) weather parameters based on that location.

For the highest precision (μas level) applications you should make sure that the site coordinates and the Earth-orientation parameters (EOP) used (in setting novas_timescale and in novas_make_frame()) are provided in the same ITRF realization. You can use novas_itrf_transform() or novas_itrf_transform_eop() to change the ITRF realization for the site coordinates and/or the EOP values, if necessary.

Parameters

  | xyz | [m] Cartesian geocentric position.
  [out] | site | Pointer to the data structure to populate.

Returns
  0 if successful, or -1 if either of the arguments is NULL (errno set to EINVAL), or if the latitude is outside of the [-90:90] range (errno set to ERANGE).

Since
  1.5

Author
  Attila Kovacs

See also
  make_gps_site(), make_itrf_site(), make_xyz_site()
  make_observer_at_site(), novas_itrf_transform(), novas_itrf_transform_eop(), novas_set_default_weather()

References make_itrf_site(), novas_cartesian_to_geodetic(), and NOVAS_GRS80_ELLIPSOID.

## mean_obliq()

double mean_obliq | ( | double | jd_tdb | ) |

Computes the mean obliquity of the ecliptic.

REFERENCES:

1. Capitaine et al. (2003), Astronomy and Astrophysics 412, 567-586.

Parameters

  jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date

Returns
  [arcsec] Mean obliquity of the ecliptic in arcseconds.

See also
  e_tilt(), equ2ecl(), ecl2equ(), tt2tdb(), novas_get_time()

Referenced by e_tilt(), ecl2equ_vec(), equ2ecl_vec(), and novas_make_frame().

## mean_star()

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

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  novas_app_to_geom(), NOVAS_TOD, make_observer_at_geocenter(), vector2radec()

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

## mod_to_gcrs()

int mod_to_gcrs | ( | double | jd_tdb,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from Mean of Date (MOD) reference frame at the given epoch to the ICRS / GCRS.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | in | Input (x, y, z) position or velocity 3-vector in the Mean equinox of Date coordinate frame.
  [out] | out | Output ICRS / GCRS position or velocity vector. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  gcrs_to_mod(), tod_to_gcrs(), novas_sys_to_icrs()

References frame_tie(), J2000_TO_ICRS, NOVAS_JD_J2000, and precession().

Referenced by novas_sys_to_icrs().

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

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

## novas_app_to_geom()

int novas_app_to_geom | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | double | ra,
|  | double | dec,
|  | double | dist,
|  | double *restrict | geom_icrs )

Converts an observed apparent sky position of a source to an ICRS geometric position, by undoing the gravitational deflection and aberration corrections.

Parameters

  | frame | The observer frame, defining the location and time of observation
  | sys | The reference system in which the observed position is specified.
  | ra | [h] Observed ICRS right-ascension of the source
  | dec | [deg] Observed ICRS declination of the source
  | dist | [AU] Observed distance from observer. A value of <=0 will translate to 1015 AU (around 5 Gpc).
  [out] | geom_icrs | [AU] The corresponding geometric position for the source, in ICRS.

Returns
  0 if successful, or else an error from grav_undef2(), or -1 (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_geom_to_app(), novas_app_to_hor(), novas_transform_vector()

References grav_undo_planets(), NOVAS_CIRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TIRS, NOVAS_TOD, radec2vector(), spin(), wobble(), and WOBBLE_ITRS_TO_TIRS.

Referenced by supernovas::Apparent::astrometric_position().

## novas_app_to_hor()

int novas_app_to_hor | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | double | ra,
|  | double | dec,
|  | RefractionModel | ref_model,
|  | double *restrict | az,
|  | double *restrict | el )

Converts an observed apparent position vector in the specified coordinate system to local horizontal coordinates in the specified observer frame.

The observer must be located on the surface of Earth, or else the call will return with an error. The caller may optionally supply a refraction model of choice to calculate an appropriate elevation angle that includes a refraction correction for Earth's atmosphere. If no such model is provided the calculated elevation will be the astrometric elevation without a refraction correction.

Parameters

  | frame | Observer frame, defining the time and place of observation (on Earth).
  | sys | Astronomical coordinate system in which the observed position is given.
  | ra | [h] Observed apparent right ascension (R.A.) coordinate
  | dec | [deg] Observed apparent declination coordinate
  | ref_model | An appropriate refraction model, or NULL to calculate unrefracted elevation. Depending on the refraction model, you might want to make sure that the weather parameters were set when the observing frame was defined.
  [out] | az | [deg] Calculated azimuth angle. It may be NULL if not required.
  [out] | el | [deg] Calculated elevation angle. It may be NULL if not required.

Returns
  0 if successful, or else an error from tod_to_itrs() or cirs_to_itrs(), or -1 (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_hor_to_app()
  novas_app_to_geom(), novas_standard_refraction(), novas_optical_refraction(), novas_radio_refraction(), novas_wave_refraction()

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, itrs_to_hor(), NOVAS_AIRBORNE_OBSERVER, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_OBSERVER_ON_EARTH, NOVAS_REFRACT_ASTROMETRIC, NOVAS_TIRS, NOVAS_TOD, radec2vector(), spin(), wobble(), WOBBLE_PEF_TO_ITRS, and WOBBLE_TIRS_TO_ITRS.

Referenced by novas_hor_track(), and supernovas::Apparent::to_horizontal().

## novas_approx_heliocentric()

int novas_approx_heliocentric | ( | enum novas_planet | id,
|  | double | jd_tdb,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns the approximate geometric heliocentric orbital positions and velocities for the major planets, Sun, or Earth-Moon Barycenter (EMB).

The returned positions and velocities are not suitable for precise calculations. However, they may be used to provide rough guidance about the approximate locations of the planets, e.g. for determining approximate rise or set times or the approximate azimuth / elevation angles from an observing site.

The 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 top two references below.

For accurate positions, you should use planetary ephemerides (such as the JPL ephemerides via the CALCEPH or CSPICE plugins) and novas_geom_posvel() instead.

While this function is generally similar to creating an orbital object with an orbit initialized with novas_make_planet_orbit() or novas_make_moon_orbit(), and then calling novas_geom_posvel(), there are a few important differences:

- This function returns geometric positions referenced to the Sun (i.e., heliocentric), whereas novas_geom_posvel() references the calculated positions to the Solar-system Barycenter (SSB).
- This function calculates Earth and Moon positions about the Keplerian orbital position of the Earth-Moon Barycenter (EMB). In constrast, novas_make_planet_orbit() does not provide orbitals for the Earth directly, and make_moot_orbit() references the Moon's orbital to the Earth position returned by the currently configured planet calculator function (see set_planet_provider()).

NOTES:

1. The Sun's position w.r.t. the Solar-system Barycenter is calculated using earth_sun_calc(). All other orbitals are also referenced to the Sun's position calculated that way.

REFERENCES:

1. E.M. Standish and J.G. Williams 1992.
2. https://ssd.jpl.nasa.gov/planets/approx_pos.html
3. Chapront, J. et al., 2002, A&A 387, 700–709
4. Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

  | id | NOVAS major planet ID. All major planets, plus the Sun, Moon, Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported. (For Pluto, the Pluto System Barycenter value are returned.)
  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian Date. Dates between 3000 BC and 3000 AD are supported. For dates between 1800 AD and 2050 AD the returned positions are somewhat more accurate.
  [out] | pos | [AU] Output Heliocentric ICRS position vector, or NULL if not required.
  [out] | vel | [AU/day] Output Heliocentric ICRS velocity vector, or NULL if not required.

Returns
  0 if successful, or if the JD date is outside of the range with valid parameters, or else -1 if the planet ID is not supported or if both output vectors are NULL. In case of errors errno will be set to indicate the type of error.

Since
  1.4

Author
  Attila Kovacs

See also
  novas_approx_sky_pos(), earth_sun_calc(), novas_geom_posvel()
  novas_use_calceph(), novas_use_cspice()

References NOVAS_EARTH, NOVAS_EMB, novas_make_moon_orbit(), novas_make_planet_orbit(), NOVAS_MOON, NOVAS_ORBIT_INIT, novas_orbit_posvel(), NOVAS_REDUCED_ACCURACY, and NOVAS_SUN.

Referenced by supernovas::Planet::approx_geometric_in(), and novas_approx_sky_pos().

## novas_approx_sky_pos()

int novas_approx_sky_pos | ( | enum novas_planet | id,
|  | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | out )

Calculates an approximate apparent location on sky for a major planet, Sun, Moon, Earth-Moon Barycenter (EMB) – typically to arcmin level accuracy – using Keplerian orbital elements.

The returned position is antedated for light-travel time (for Solar-System bodies). It also applies an appropriate aberration correction (but not gravitational deflection).

The 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 top two references below.

For accurate positions, you should use planetary ephemerides (such as the JPL ephemerides via the CALCEPH or CSPICE plugins) and novas_sky_pos() instead.

While this function is generally similar to creating an orbital object with an orbit initialized with novas_make_planet_orbit() or novas_make_moon_orbit(), and then calling novas_sky_pos(), there are a few important differences to note:

- This function calculates Earth and Moon positions about the Keplerian orbital position of the Earth-Moon Barycenter (EMB). In constrast, novas_make_planet_orbit() does not provide orbitals for the Earth directly, and make_moot_orbit() references the Moon's orbital to the Earth position returned by the currently configured planet calculator function (see set_planet_provider()).
- This function ignores gravitational deflection. It makes little sense to bother about corrections that are orders of magnitude below the accuracy of the orbital positions obtained.

REFERENCES:

1. E.M. Standish and J.G. Williams 1992.
2. https://ssd.jpl.nasa.gov/planets/approx_pos.html
3. Chapront, J. et al., 2002, A&A 387, 700–709
4. Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

  | id | NOVAS major planet ID. All major planets, plus the Sun, Moon, Earth-Moon Barycenter (EMB), and Pluto system Barycenter are supported. (For Pluto, the Pluto System Barycenter values are returned.)
  | frame | The observer frame, defining the location and time of observation.
  | sys | The coordinate system in which to return the apparent sky location.
  [out] | out | Pointer to the data structure which is populated with the calculated approximate apparent location in the designated coordinate system.

Returns
  0 if successful, or else -1 in case of an error (errno will indicate the type of error).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_sky_pos(), novas_app_to_hor()
  novas_make_frame()

References make_planet(), novas_approx_heliocentric(), novas_geom_to_app(), novas_get_time(), NOVAS_TDB, novas_vlen(), and rad_vel2().

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

## novas_cartesian_to_geodetic()

int novas_cartesian_to_geodetic | ( | const double *restrict | xyz,
|  | enum novas_reference_ellipsoid | ellipsoid,
|  | double *restrict | lon,
|  | double *restrict | lat,
|  | double *restrict | alt )

Converts geocentric Cartesian site coordinates to geodetic coordinates on the given reference ellipsoid.

NOTES:

1. Adapted from the IERS GCONV2.F source code, see https://iers-conventions.obspm.fr/content/chapter4/software/GCONV2.F.

REFERENCES:

1. Fukushima, T., "Transformation from Cartesian to geodetic coordinates accelerated by Halley's method", J. Geodesy (2006), 79(12): 689-693
2. Petit, G. and Luzum, B. (eds.), IERS Conventions (2010), IERS Technical Note No. 36, BKG (2010)

Parameters

  [in] | xyz | [m] Input geocentric Cartesian coordinates (x, y, z) 3-vector.
  | ellipsoid | Reference ellipsoid to use. For ITRF use NOVAS_GRS80_ELLIPSOID, for GPS related applications use NOVAS_WGS84_ELLIPSOID.
  [out] | lon | [deg] Geodetic longitude. It may be NULL if not required.
  [out] | lat | [deg] Geodetic latitude. It may be NULL if not required.
  [out] | alt | [m] Geodetic altitude (i.e. above sea level). It may be NULL if not required.

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

Since
  1.5

Author
  Attila Kovacs

See also
  novas_geodetic_to_cartesian()
  novas_itrf_transform(), novas_itrf_transform_site()

References M_PI, NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.

Referenced by supernovas::Site::Site(), make_gps_site(), make_xyz_site(), novas_geodetic_transform_site(), and novas_itrf_transform_site().

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

int novas_change_observer | ( | const novas_frame * | orig,
|  | const observer * | obs,
|  | novas_frame * | out )

Change the observer location for an observing frame.

Parameters

  | orig | Pointer to original observing frame
  | obs | New observer location
  [out] | out | Observing frame to populate with a original frame data and new observer location. It can be the same as the input.

Returns
  0 if successful or else an error code from geo_posvel() (errno will also indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_make_frame()

References novas_frame::accuracy, grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_TDB, obs_planets(), novas_frame::obs_pos, novas_frame::observer, novas_frame::planets, novas_frame::state, and novas_frame::time.

Referenced by novas_make_frame().

## novas_clock_skew()

double novas_clock_skew | ( | const novas_frame * | frame,
|  | enum novas_timescale | timescale )

Returns the instantaneous incremental rate at which the observer's clock (i.e.

proper time τ) ticks faster than a clock in the specified timescale. I.e., it returns D, which is defined by:

dτobs / dttimescale = (1 + D)

The instantaneous difference in clock rate includes tiny diurnal or orbital variationd for Earth-bound observers as the they cycle through the tidal potential around the geocenter (mainly due to the Sun and Moon). For a closer match to Earth-based timescales (TCG, TT, TAI, GPS, or UTC) you may want to exclude the periodic tidal effects and calculate the averaged observer clock rate over the geocentric cycle (see Eqs. 10.6 and 10.8 of the IERS Conventions 2010), which is provided by novas_mean_clock_skew() instead.

For reduced accuracy frames, the result will be approximate, because the gravitational effect of the Sun and Earth alone may be accounted for.

NOTES:

1. Based on the IERS Conventions 2010, Chapter 10, Eqa. 10.6 / 10.8 but also including the near-Earth tidal effects, and modified for relativistic observer motion.
2. The potential for an observer inside 0.9 planet radii of a major Solar-system body's center will not include the term for that body in the calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 10, see at https://iers-conventions.obspm.fr/content/chapter10/tn36_c10.pdf

Parameters

  frame | The observing frame, defining the observer position as well as the positions of the major solar-system bodies at the time of observation.
  timescale | Reference timescale for the comparison. All timescales except NOVAS_UT1 are supported. (UT1 advances at an irregular rate).

Returns
  The incremental rate at which the observer's proper time clock ticks faster than the specified timescale, or else NAN if the input frame is NULL or uninitialized, or if the timescale is not supported (errno set to EINVAL), or if the frame is configured for full accuracy but it does not have sufficient planet position information to evaluate the local gravitational potential with precision (errno set to EAGAIN).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_mean_clock_skew(), novas_timescale_offset()

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_C_AU_PER_DAY, novas_clock_skew(), NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UTC, novas_vlen(), novas_frame::obs_pos, novas_frame::obs_vel, novas_frame::time, and tt2tdb().

Referenced by supernovas::Frame::clock_skew(), novas_clock_skew(), and novas_mean_clock_skew().

## novas_date()

double novas_date | ( | const char *restrict | date | ) |

Returns a Julian date (in non-specific timescale) corresponding the specified input string date / time.

E.g. for "2025-02-28T09:41:12.041+0200", with some flexibility on how the date is represented as long as it's YMD date followed by HMS time. For other date formats (MDY or DMY) you can use novas_parse_date_format() instead.

Parameters

  date | The date specification, possibly including time and timezone, in a standard format. See novas_parse_date() on more information on acceptable date/time formats.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_date_scale(), novas_parse_date(), novas_parse_date_format(), novas_iso_timestamp()

References novas_parse_date().

## novas_date_scale()

double novas_date_scale | ( | const char *restrict | date,
|  | enum novas_timescale *restrict | scale )

Returns a Julian date and the timescale corresponding the specified input string date/time and timescale marker.

E.g. for "2025-02-28T09:41:12.041+0200 TAI", with some flexibility on how the date is represented as long as it's YMD date followed by HMS time. For other date formats (MDY or DMY) you can use novas_parse_date_format() instead.

Parameters

  | date | The date specification, possibly including time and timezone, in a standard format. See novas_parse_date() on more information on acceptable date/time formats.
  [out] | scale | The timescale constant, or else -1 if the string could not be parsed into a date and timescale. If the string is a bare timestamp without a hint of a timescale marker, then NOVAS_UTC will be assumed.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_date(), novas_timestamp()

References novas_parse_date(), and novas_parse_timescale().

## novas_day_of_week()

int novas_day_of_week | ( | double | tjd | ) |

Returns the one-based ISO 8601 day-of-week index of a given Julian Date.

The ISO 8601 week begins on Monday, thus index 1 corresponds to Monday, while index 7 is a Sunday.

Parameters

  tjd | [day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).

Returns
  The day-of-week index [1:7] in the same timescale as the input date. 1:Monday ... 7:Sunday, or else -1 if the input Julian Date is NAN.

Since
  1.4

Author
  Attila Kovacs

See also
  novas_day_of_year(), novas_jd_to_date()

References NOVAS_JD_J2000.

Referenced by supernovas::CalendarDate::day_of_week(), and supernovas::Time::day_of_week().

## novas_day_of_year()

int novas_day_of_year | ( | double | tjd,
|  | enum novas_calendar_type | calendar,
|  | int *restrict | year )

Returns the one-based day index in the calendar year for a given Julian Date.

Parameters

  | tjd | [day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).
  | calendar | The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
  [out] | year | [yr] Optional pointer to which to return the calendar year. It may be NULL if not required.

Returns
  [1:366] The day-of-year index in the same timescale as the input date.

Since
  1.4

Author
  Attila Kovacs

See also
  novas_day_of_week(), novas_jd_to_date()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_JD_START_GREGORIAN, novas_jd_to_date(), and NOVAS_ROMAN_CALENDAR.

Referenced by supernovas::CalendarDate::day_of_year().

## novas_diff_tcb()

double novas_diff_tcb | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Barycentric Coordinate Time (TCB) based time difference (t1 - t2) in days between two astronomical time specifications.

TCB progresses slightly faster than time on Earth, at a rate about 1.6&times10-8 higher, due to the lack of gravitational time dilation by the Earth or Sun.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise TCB time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcg(), novas_diff_time()

References novas_diff_time().

## novas_diff_tcg()

double novas_diff_tcg | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Geocentric Coordinate Time (TCG) based time difference (t1 - t2) in days between two astronomical time specifications.

TCG progresses slightly faster than time on Earth, at a rate about 7&times10-10 higher, due to the lack of gravitational time dilation by Earth. TCG is an appropriate time measure for a spacecraft that is in the proximity of the orbit of Earth, but far enough from Earth such that the relativistic effects of Earth's gravity can be ignored.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise TCG time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcb(), novas_diff_time()

References novas_diff_time().

## novas_diff_time()

double novas_diff_time | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Terrestrial Time (TT) based time difference (t1 - t2) in days between two astronomical time specifications.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcb(), novas_diff_tcg(), novas_set_time(), novas_offset_time()

References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.

Referenced by supernovas::Time::equals(), novas_diff_tcb(), novas_diff_tcg(), novas_track_pos(), supernovas::Time::operator<(), and supernovas::Time::operator<=().

## novas_diff_time_scale()

double novas_diff_time_scale | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2,
|  | enum novas_timescale | timescale )

Returns the UT1 based time difference (t1 - t2) in days between two astronomical time specifications.

Parameters

  t1 | First time
  t2 | Second time
  timescale | Astronomical timescale in which to return the difference.

Returns
  [s] Precise UT1 time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.6

Author
  Attila Kovacs

See also
  novas_diff_time(), novas_diff_tcg(), novas_diff_time()

References novas_get_split_time(), and NOVAS_TIMESCALES.

Referenced by supernovas::Time::offset_from().

## novas_diurnal_eop()

int novas_diurnal_eop | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides.

See Chapters 5 and 8 of the IERS Conventions. This one is faster than novas_diurnal_eop_at_time() if the GMST and/or fundamental arguments are readily avaialbe, e.g. from a previous calculation.

These corrections are typically at the sub-milliarcsecond level in polar offsets x and y and sub-millisecond level in UT1. Thus, these diurnal and semi-diurnal variations are important for the highest precision astrometry only, when converting between ITRS and TIRS frames.

NOTES:

1. These diurnal corrections are automatically added to the mean Earth Orinetation parameters used when defining astronomical times and observing frames. I.e., you should pass mean values to the likes of novas_set_time() and novas_make_frame(), which will then add the diurnal corrections as appropriate automatically.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
2. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction for libration and ocean tides, or NULL if not required.
  [out] | dyp | [arcsec] y-pole corrections for libration and ocean tides, or NULL if not required.
  [out] | dut1 | [s] UT1 correction for libration and ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop_at_time()
  novas_diurnal_libration(), novas_diurnal_ocean_tides()

Referenced by novas_diurnal_eop_at_time().

## novas_diurnal_eop_at_time()

int novas_diurnal_eop_at_time | ( | const novas_timespec *restrict | time,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides at a given astromtric time.

See Chapters 5 and 8 of the IERS Conventions.

NOTES:

1. These diurnal corrections are automatically added to the mean Earth Orinetation parameters used when defining astronomical times and observing frames. I.e., you should pass mean values to the likes of novas_set_time() and novas_make_frame(), which will then add the diurnal corrections as appropriate automatically.
2. This function caches the result of the last calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
2. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  time | Astrometric time specification
  dxp | [arcsec] x-pole correction for libration and ocean tides, or NULL if not required.
  dyp | [arcsec] y-pole corrections for libration and ocean tides, or NULL if not required.
  dut1 | [s] UT1 correction for libration and ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop()

References fund_args(), novas_diurnal_eop(), novas_get_time(), novas_gmst(), NOVAS_JD_J2000, and NOVAS_UT1.

Referenced by supernovas::GeodeticObserver::eop_at(), novas_make_frame(), and novas_set_split_time().

## novas_diurnal_libration()

int novas_diurnal_libration | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate diurnal and semi-diurnal libration corrections to the Earth orientation parameters (EOP) for the non-rigid Earth.

Only terms with periods less than 2 days are considered, since the longer period terms are included in the IAU2000A nutation model. See Chapter 5 of the IERS Conventions 2010. The typical amplitude of librations is tens of micro-arcseconds (μas) in polar offsets x and y and tens of micro-seconds in UT1.

Normally, you would need the combined effect from librations and ocean tides together to apply diurnal corrections to the Earth orientation parameters (EOP) published by IERS. For that, novas_diurnal_eop() or novas_diurnal_eop_at_time() is more directly suited.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, Tablea 5.1a and 5.1b, see https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction due to librations, or NULL if not required.
  [out] | dyp | [arcsec] y-pole correction due to librations, or NULL if not required.
  [out] | dut1 | [s] UT1 correction due to librations, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop(), novas_diurnal_ocean_tides()

## novas_diurnal_ocean_tides()

int novas_diurnal_ocean_tides | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to the ocean tides.

See Chapter 8 of the IERS Conventions 2010. Ocean tides manifest at the sub-milliarcsecond level in polar offsets x and y and sub-millisecond level in UT1.

Normally, you would need the combined effect from librations and ocean tides together to apply diurnal corrections to the Earth orientation parameters (EOP) published by IERS. For that, novas_diurnal_eop() or novas_diurnal_eop_at_time() is more directly suited.

REFERENCES:

1. IERS Conventions 2010, Chapter 8, Tables 8.2a, 8.2b, 8.3a, and 8.3b, see https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction due to ocean tides, or NULL if not required.
  [out] | dyp | [arcsec] y-pole correction due to ocean tides, or NULL if not required.
  [out] | dut1 | [s] UT1 correction due to ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop(), novas_diurnal_libration()

## novas_dms_degrees()

double novas_dms_degrees | ( | const char *restrict | dms | ) |

Returns the decimal degrees for a DMS string specification.

The degree, (arc)minute, and (arc)second components may be separated by spaces, tabs, colons :, or a combination thereof. Additionally, the degree and minutes may be separated by the letter d, and the minutes and seconds may be separated by m or a single quote '. The seconds may be followed by 's' or double quote ". Finally, the leading or trailing component may additionally be a standalone upper-case letter 'N', 'E', 'S', or 'W' or the words 'North', 'East', 'South', or 'West' (case insensitive), signifying a compass direction.

There is no enforcement on the range of angles that can be represented in this way. Any finite angle is parseable, even if it is outside its conventional range, such as +- 90 degrees N/S.

For example, all of the lines below are valid specifications:

-179:59:59.999
-179d 59m 59.999s
-179 59' 59.999
179:59:59.999S
179 59 59.999 W
179 59 59.999 west
179_59_59.999__S
W 179 59 59
North 179d 59m

At least the leading two components (degrees and arcminutes) are required. If the arcseconds are ommitted, they will be assumed zero, i.e. 179:59 is the same as 179:59:00.000.

NOTES:

1. To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  dms | String specifying degrees, minutes, and seconds, which correspond to an angle. Angles in any range are permitted, but the minutes and seconds must be >=0 and <60.

Returns
  [deg] Corresponding decimal angle value, or else NAN if there was an error parsing the string (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_str_degrees(), novas_parse_dms(), novas_hms_hours()

References novas_parse_dms().

## novas_enu_to_itrs()

int novas_enu_to_itrs | ( | const double * | enu,
|  | double | lon,
|  | double | lat,
|  | double * | itrf )

Converts an East-North-Up (ENU) vector at the specified site to an ITRS vector.

Parameters

  | enu | input East-North-Up (ENU) vector.
  | lon | [deg] ITRS longitude of site.
  | lat | [deg] ITRS latitude of site.
  [out] | itrf | output ITRS vector. It may be the same vector as the input.

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

Since
  1.6

Author
  Attila Kovacs

See also
  novas_itrs_to_enu()

Referenced by supernovas::GeodeticObserver::GeodeticObserver(), supernovas::Site::enu_to_itrs(), and supernovas::Site::enu_to_itrs().

## novas_epoch()

double novas_epoch | ( | const char *restrict | system | ) |

Returns the Julian day corresponding to an astronomical coordinate epoch.

Parameters

  system | Coordinate system, e.g. "ICRS", "B1950.0", "J2000.0", "FK4", "FK5", "1950", "2000", 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 values listed. If 'B' or 'J' is ommitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0, and Julian epochs after.

Returns
  [day] The Julian day corresponding to the given coordinate epoch, or else NAN if the input string is NULL or the input is not recognised as a coordinate epoch specification (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  make_cat_object_sys(), make_redshifted_object_sys(), transform_cat(), precession()
  NOVAS_SYSTEM_ICRS, NOVAS_SYSTEM_B1950, NOVAS_SYSTEM_J2000, NOVAS_SYSTEM_HIP

References NOVAS_BESSELIAN_YEAR_DAYS, NOVAS_JD_B1950, NOVAS_JD_HIP, NOVAS_JD_J2000, NOVAS_JULIAN_YEAR_DAYS, NOVAS_SYSTEM_FK4, NOVAS_SYSTEM_FK5, NOVAS_SYSTEM_FK6, and NOVAS_SYSTEM_HIP.

Referenced by supernovas::Equinox::from_string().

## novas_equ_offset_by()

int novas_equ_offset_by | ( | double | ra,
|  | double | dec,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_ra,
|  | double *restrict | out_dec )

Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.

Parameters

  | ra | [h] reference point right ascension (R.A.)
  | dec | [deg] reference point declination
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_ra | [h] right ascension (R.A.) at offset position in [0:24) range. It may be NULL if not needed.
  [out] | out_dec | [deg] declination at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and right ascension (R.A.) at the offset position is requested, or if the input declination is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_offset_by(), novas_equ_sep()

References novas_offset_by().

## novas_equ_sep()

double novas_equ_sep | ( | double | ra1,
|  | double | dec1,
|  | double | ra2,
|  | double | dec2 )

Returns the angular separation of two equatorial locations on a sphere.

Parameters

  ra1 | [h] right ascension of first location
  dec1 | [deg] declination of first location
  ra2 | [h] right ascension of second location
  dec2 | [deg] declination of second location

Returns
  [deg] the angular separation of the two locations.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_sep(), novas_sun_angle(), novas_moon_angle()
  novas_equ_offset_by()

References novas_sep().

Referenced by novas_object_sep().

## novas_equ_track()

int novas_equ_track | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame,
|  | double | dt,
|  | novas_track *restrict | track )

Calculates true-of-date equatorial tracking position and motion (first and second time derivatives) for the specified source in the given observing frame.

The position and its derivatives are calculated via the more precise IAU2006 method, and CIRS.

Parameters

  | source | Observed source
  | frame | Observing frame, defining the observer location and astronomical time of observation.
  | dt | [s] Time step used for calculating derivatives.
  [out] | track | Output tracking parameters to populate

Returns
  0 if successful, or else -1 if any of the pointer arguments are NULL, or else an error code from novas_sky_pos().

Since
  1.3

Author
  Attila Kovacs

See also
  novas_hor_track(), novas_track_pos()

References novas_sky_pos::dec, novas_sky_pos::dis, novas_timespec::fjd_tt, novas_make_frame(), novas_sky_pos(), NOVAS_TOD, novas_v2z(), novas_sky_pos::ra, novas_sky_pos::rv, and SKY_POS_INIT.

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

## 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 supernovas::CatalogEntry::equals(), and novas_equals_object().

## novas_equals_frame()

int novas_equals_frame | ( | const novas_frame * | a,
|  | const novas_frame * | b )

Checks if two observing frames are essentially the same, within typical tolerances.

Two frames are considered equal, if they are both:

- initialized,
- represent the same accuracy,
- for the same observer,
- at the same time,
- same polar offsets (for geodetic observers or if defined),
- and contain the same planetary ephemeris data

all within the typical tolerances associated to these. For non-geodetic observers two frames are considered equal also if both have all NAN (undefined) polar offsets – since polar offsets are not generally required for non-geodetic observing frames.

NOTES:

- this function does not check the calculated fields of the observing frames, which are assumed to have been left untouched after the called to novas_make_frame(). If the user modifies the calculated fields, they may need additional checks to ensure 'equality' accordingly.
- Two NULL (undefined) observing frames are considered not equal.
- An observing frame may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | an observing frame
  b | another observing frame

Returns
  TRUE (1) if the two observing frames are effectively the same, given the tolerances, or else false.

Since
  1.7

Author
  Attila Kovacs

References novas_frame::accuracy, novas_frame::dx, novas_frame::dy, novas_equals_observer(), novas_equals_planet_bundle(), novas_equals_timespec(), novas_frame::observer, novas_frame::planets, and novas_frame::time.

Referenced by supernovas::Frame::equals().

## novas_equals_near_earth()

int novas_equals_near_earth | ( | const in_space * | a,
|  | const in_space * | b )

Checks if two near-Earth locations and motions match within 1 mm and 1 mm/s, respectively.

Such near-Earth data structures are used by airborne observers or observers in Earth orbit.

NOTES:

- Two NULL (undefined) structures are considered not equal.
- A near-Earth position/velocity structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one near-Earth position/velocity data structure
  b | another near-Earth position/velocity data structure

Returns
  TRUE (1) if the two near-Earth positions and velocities match within 1 mm and 1 mm/s, respectively.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_ssb_posvel(), novas_equals_observer()

References novas_equals_vector(), novas_in_space::sc_pos, and novas_in_space::sc_vel.

Referenced by novas_equals_observer().

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

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

## novas_equals_observer()

int novas_equals_observer | ( | const observer * | a,
|  | const observer * | b )

Checks if two observers are essentially the same within the tolerances associated to their defining components.

NOTES:

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

Parameters

  a | an observer data structure
  b | another observer data structure

Returns
  TRUE (1) if the two data structures describe effectively the same observer location, within the typical tolerances associated to them, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

References novas_observer::near_earth, NOVAS_AIRBORNE_OBSERVER, novas_equals_near_earth(), novas_equals_on_surface(), novas_equals_ssb_posvel(), NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_SOLAR_SYSTEM_OBSERVER, novas_observer::on_surf, and novas_observer::where.

Referenced by supernovas::Observer::equals(), and novas_equals_frame().

## novas_equals_on_surface()

int novas_equals_on_surface | ( | const on_surface * | a,
|  | const on_surface * | b )

Checks if two geodetic locations, and the weather parameters defined for them, match.

For two on_surface structures to be equal, they must have matching:

- longitude and latitude angles to within 1 μas.
- altitudes within 1 mm.
- temperatures within 1 mK.
- pressures within 1 μbar
- humidities within 0.001 %

NOTES:

- Two NULL (undefined) structures are considered not equal.
- A geodetic location + local weather structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one geodetic location (with weather)
  b | another geodetic location (with weather)

Returns
  TRUE (1) if the two locations and their weather parameters match within the described tolerances, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_observer()

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::longitude, novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by novas_equals_observer().

## 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 supernovas::Orbital::equals(), and 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 supernovas::OrbitalSystem::equals(), and novas_equals_orbital().

## novas_equals_planet_bundle()

int novas_equals_planet_bundle | ( | const novas_planet_bundle * | a,
|  | const novas_planet_bundle * | b )

Checks if two bundles containing Solar-system baricentric planet positions and velocities are effectively the same.

The two bundles are considered equals if:

- they contain data for the same set of planets.
- the planets with data have positions matching within 1 m.
- the planets with data have velocities matching within 1 mm/s.

NOTES:

- Two NULL (undefined) planet bundles are considered not equal.
- A planet bundle may not equal itself if it contains NAN or infinite components for the planets they are supposed to have data for, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | a planet position / velocity bundle
  b | another planet position / velocity bundle

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

Since
  1.7

Author
  Attila Kovacs

References novas_planet_bundle::mask, NOVAS_AU, novas_equals_vector(), NOVAS_PLANETS, novas_planet_bundle::pos, and novas_planet_bundle::vel.

Referenced by novas_equals_frame().

## novas_equals_sky_pos()

int novas_equals_sky_pos | ( | const sky_pos * | a,
|  | const sky_pos * | b )

Checks if two apparent positions on the observer's sky are the same within typical tolerances.

Two sky positions are considered to be equal if their:

- coordinates match within 1 μas,
- distances match within 1 ppm.
- radial velocities match within 1 mm/s.
- unit vectors match to 10-12 (~1 μas).

NOTES:

- Two NULL (undefined) sky positions are considered not equal.
- A sky position may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | a position on the observer's sky
  b | another sky position

Returns
  TRUE (1) if the two positions are essentially the same within typical tolerances, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

References novas_sky_pos::dec, novas_sky_pos::dis, novas_equals_vector(), novas_sky_pos::r_hat, novas_sky_pos::ra, and novas_sky_pos::rv.

## novas_equals_ssb_posvel()

int novas_equals_ssb_posvel | ( | const in_space * | a,
|  | const in_space * | b )

Checks if two Solar-system locations and motions match within 1 m and ~1 mm/s, respectively.

Such near-Earth data structures are used by observers defined relative to the Solar-System Barycenter (SSB).

NOTES:

- Two NULL (undefined) structures are considered not equal.
- A Solar-system position / velocity structure may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one Solar-system position/velocity data structure
  b | another Solar-system position/velocity data structure

Returns
  TRUE (1) if the two SSB positions and velocities match within 1 m and ~1 mm/s, respectively.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equals_near_earth(), novas_equals_observer()

References NOVAS_AU, novas_equals_vector(), novas_in_space::sc_pos, and novas_in_space::sc_vel.

Referenced by novas_equals_observer().

## novas_equals_timespec()

int novas_equals_timespec | ( | const novas_timespec * | a,
|  | const novas_timespec * | b )

Checks if two time specifications are the same within 10-7 days (~100 μs).

NOTES:

- Two NULL (undefined) time specifications are considered not equal.
- A time specification may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one of the time specs
  b | the other time spec

Returns
  TRUE (1) if the two time specifications match to within 100 μs, or else FALSE (0).

Since
  1.7

Author
  Attila Kovacs

References novas_timespec::dut1, novas_timespec::fjd_tt, novas_timespec::ijd_tt, novas_timespec::tt2tdb, and novas_timespec::ut1_to_tt.

Referenced by novas_equals_frame().

## novas_equals_vector()

int novas_equals_vector | ( | const double * | a,
|  | const double * | b,
|  | double | tol )

Checks if two 3D vectors are effectively the same, within the specified absolute tolerance.

Two vectors are equal if the distance between them is less than or equal to the magnitude of the specified tolerance.

NOTES:

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

Parameters

  a | one of the vectors
  b | the other vector
  tol | absolute tolerance (sign is ignored).

Returns
  TRUE (1) if all the two vectors match within the specified tolerance, or else FALSE (0)

Since
  1.7

Author
  Attila Kovacs

Referenced by supernovas::Vector::equals(), novas_equals_near_earth(), novas_equals_planet_bundle(), novas_equals_sky_pos(), and novas_equals_ssb_posvel().

## novas_fetch_eop()

int novas_fetch_eop | ( | double | jd,
|  | long | timeout_millis,
|  | novas_eop * | eop )

Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS).

For dates since 1972 or for prediction for up to a year ahead, the rapid service data is used (finals.all), otherwise for dates after 1962 the C04 series is used, and for dates all the way back to 1846, the C01 series is used. All of the mentioned data are retrieved relative to the IAU2000 precession-nutation model.

You should always check the return status when using this function, since the fetching of EOP values may fail for a host of different reasons.

NOTES:

1. You must have built SuperNOVAS with cURL support. Otherwise, this function will return -1, with errno set to ENOSYS.
2. You will need an internet connection and the IERS server must be online and accessible, unless you have changed the necessary URLs to use local copies instead (see novas_set_eop_url()).
3. Obtaining values from IERS can have arbitrary latencies, and can impact the performance severely. For performance critical applications, you should consider specifying the EOP values more directly, or using local files instead (see also novas_set_eop_url()).
4. This function assumes that the files served from IERS remain accessible and their format does not change over time. As such what works today, may not work the same in the future. The IERS website also encounters outages occasionally (see novas_set_eop_url() for alternative sources.).
5. This function caches EOP data from the last query. As such repeated calls within the same date bracket (typically the same MJD day) will return fast and will interpolate from the data last obtained from the IERS.
6. This function uses cubic spline interpolation around the published data points. As such, it needs at least two data points at the same time or before, and two points after, the date for which interpolated values are requested.
7. Prior to 1 Jan 1956, the UT1-UTC time difference, and length-of-day (LOD) are not provided by IERS, as they were not measured prior to the age of atomic clocks. Hence, for dates prior to 1956 the returned EOP will have dut1 and lod (and their uncertainties) set to NAN. (However, the polar the offsets xp and yp can be provided all the way back to 1846, with some precision.)
8. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

Parameters

  | jd | Julian Date (in any timescale, with a preference for UTC)
  | timeout_millis | [ms] HTTP connection timeout, or <=0 to leave unchanged.
  [out] | eop | Output EOP data structure to populate

Returns
  0 if successful or else -1 (errno will indicate the type of error).

Since
  1.7

Author
  Attila Kovacs

See also
  https://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop
  novas_fetch_current_eop(), novas_set_eop_url(), novas_reset_eop()
  novas_make_frame(), novas_set_time(), novas_set_auto_fetch_eop(), Earth orientation

Referenced by supernovas::GeodeticObserver::eop_at(), supernovas::EOP::fetch_for_jd(), novas_fetch_eop_unix(), novas_make_frame(), and novas_set_split_time().

## novas_fetch_eop_unix()

int novas_fetch_eop_unix | ( | time_t | t,
|  | long | timeout_millis,
|  | novas_eop * | eop )

Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS) around the current system time, using the rapid service data (finals.all).

You should always check the return status when using this function, since the fetching of EOP values may fail for a host of different reasons.

NOTES:

1. You must have access to the curl library and built SuperNOVAS with CURL support. Otherwise this function will return -1, with errno set to ENOSYS.
2. You will need an internet connection and the IERS server must be online and accessible (at least for the initial call).
3. Obtaining values from IERS can have arbitrary latencies, and can impact performance severely. For performance critical applications, you should consider specifying the EOP values more directly, e.g. from a local file instead.
4. This function assumes that the files served from IERS remain accessible and their format does not change over time. As such what works today, may not work the same in the future. The IERS website also encounters outages occasionally (see novas_set_eop_url() for alternative sources.).
5. This function caches EOP data from the last online query. As such repeated calls within the same data bracket (typically the same MJD day) will return fast and will reuse the last data obtained from the IERS.
6. This function uses cubic spline interpolation of the published data points.
7. The returned EOP values are assumed to be ITRF 2020 values, which is appropriate at the time this SuperNOVAS module was written or last updated. If IERS later publishes data in some other future ITRF realization, this module may need to be updated, accordingly. However, the ITRF realization is unlikely to matter significantly.
8. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

Parameters

  | t | [s] UNIX time (seconds since 0 UTC 1 Jan 1970).
  | timeout_millis | [ms] HTTP connection timeout, or <=0 to leave unchanged.
  [out] | eop | Output EOP data structure to populate

Returns
  0 if successful or else -1 (errno will indicate the type of error).

Since
  1.7

Author
  Attila Kovacs

See also
  https://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop
  novas_set_eop_url()
  novas_make_frame(), novas_set_time(), novas_set_auto_fetch_eop(), Earth orientation

References novas_fetch_eop(), NOVAS_JD_J2000, and UNIX_SECONDS_0UTC_1JAN2000.

## novas_frame_lst()

double novas_frame_lst | ( | const novas_frame *restrict | frame | ) |

Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.

Parameters

  frame | Observer frame, defining the location and time of observation

Returns
  [h] The LST for an Earth-bound observer [0.0–24.0), or NAN otherwise. If NAN is returned errno will indicate the type of error.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_time_lst()

References NOVAS_AIRBORNE_OBSERVER, and NOVAS_OBSERVER_ON_EARTH.

## novas_gast()

double novas_gast | ( | double | jd_ut1,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy )

Returns the Greenwich Apparent Sidereal Time (GAST) for a given UT1 date.

NOTES:

1. This function caches the result of the last calculation.

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).
2. Kaplan, G. (2005), US Naval Observatory Circular 179.
3. IERS Conventions 2010, Chapter 5, Eq. 5.30 and Table 5.2e, see at https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf and https://iers-conventions.obspm.fr/content/chapter5/additional_info/tab5.2e.txt

Parameters

  jd_ut1 | [day] UT1-based Julian Date.
  ut1_to_tt | [s] UT1 - UTC time difference.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)

Returns
  [h] The Greenwich Apparent Sidereal Time (GAST) in the 0-24 range.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_gmst()

References e_tilt(), and novas_gmst().

Referenced by cel2ter(), geo_posvel(), novas_time_gst(), sidereal_time(), and ter2cel().

## novas_geodetic_to_cartesian()

int novas_geodetic_to_cartesian | ( | double | lon,
|  | double | lat,
|  | double | alt,
|  | enum novas_reference_ellipsoid | ellipsoid,
|  | double * | xyz )

Converts geodetic site coordinates to geocentric Cartesian coordinates, using the specified reference ellipsoid.

Parameters

  [in] | lon | [deg] Geodetic longitude
  [in] | lat | [deg] Geodetic latitude
  [in] | alt | [m] Geodetic altitude (i.e. above sea level).
  | ellipsoid | Reference ellipsoid to use. For ITRF use NOVAS_GRS80_ELLIPSOID, for GPS related applications use NOVAS_WGS84_ELLIPSOID.
  [out] | xyz | [m] Corresponding geocentric Cartesian coordinates (x, y, z) 3-vector.

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

Since
  1.5

Author
  Attila Kovacs

See also
  novas_cartesian_to_geodetic()
  novas_itrf_transform_site(), novas_itrf_transform()

References NOVAS_GRS80_FLATTENING, and NOVAS_GRS80_RADIUS.

Referenced by make_gps_site(), novas_geodetic_transform_site(), novas_itrf_transform_site(), and supernovas::Site::xyz().

## novas_geodetic_transform_site()

int novas_geodetic_transform_site | ( | enum novas_reference_ellipsoid | from_ellipsoid,
|  | const on_surface * | in,
|  | enum novas_reference_ellipsoid | to_ellipsoid,
|  | on_surface * | out )

Transforms a geodetic location from one reference ellipsoid to another.

For example to transform a GPS location (defined on the WGS84 ellipsoid) to an International Terrestrial Reference Frame (ITRF) location (defined on the GRS80 ellipsoid), or vice versa.

Parameters

  | from_ellipsoid | Reference ellipsoid of the input coordinates.
  [in] | in | Input site, defined on the original reference ellipsoid.
  | to_ellipsoid | Reference ellipsoid for which to calculate output coordinates.
  [out] | out | Output site, calculated for the final reference ellipsoid. It may be the same as the input.

Returns
  0 if successful, or else -1 if either site pointer is NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform_site(), make_gps_site(), make_itrf_site()

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::longitude, novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::Site().

## novas_geom_posvel()

int novas_geom_posvel | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | double *restrict | pos,
|  | double *restrict | vel )

Calculates the geometric position and velocity vectors, relative to the observer, for a source in the given observing frame, in the specified coordinate system of choice.

The geometric position includes proper motion, and for solar-system bodies it is antedated for light travel time, so it effectively represents the geometric position as seen by the observer. However, the geometric does not include aberration correction, nor gravitational deflection.

If you want apparent positions, which account for aberration and gravitational deflection, use novas_skypos() instead.

You can also use novas_transform_vector() to convert the output position and velocity vectors to a dfferent coordinate system of choice afterwards if you want the results expressed in more than one coordinate system.

It implements the same geometric transformations as place() but at a reduced computational cost. See place() for references.

NOTES:

1. As of SuperNOVAS v1.3, the returned velocity vector is a proper observer-based velocity measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with pseudo LSR-based measures being returned for catalog sources.

Parameters

  | source | Pointer to a celestial source data structure that is observed. Catalog sources should have coordinates and properties in ICRS. You can use transform_cat() to convert catalog entries to ICRS as necessary.
  | frame | Observer frame, defining the location and time of observation
  | sys | The coordinate system in which to return positions and velocities.
  [out] | pos | [AU] Calculated geometric position vector of the source relative to the observer location, in the designated coordinate system. It may be NULL if not required.
  [out] | vel | [AU/day] The calculated velocity vector of the source relative to the observer in the designated coordinate system. It must be distinct from the pos output vector, and may be NULL if not required.

Returns
  0 if successful, or else -1 if any of the arguments is invalid, 50–70 error is 50 + error from light_time2().

Since
  1.1

Author
  Attila Kovacs

See also
  novas_geom_to_app(), novas_sky_pos(),
  novas_transform_vector(), novas_make_frame()

References bary2obs(), d_light(), light_time2(), NOVAS_CATALOG_OBJECT, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_JD_J2000, NOVAS_PLANET, NOVAS_REDUCED_ACCURACY, NOVAS_TDB, proper_motion(), and starvectors().

Referenced by supernovas::Source::geometric_in(), novas_sky_pos(), and novas_solar_illum().

## novas_geom_to_app()

int novas_geom_to_app | ( | const novas_frame *restrict | frame,
|  | const double *restrict | pos,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | out )

Converts an geometric position in ICRS to an apparent position on sky, by applying appropriate corrections for aberration and gravitational deflection for the observer's frame.

Unlike place() the output reports the distance calculated from the parallax for sidereal sources. The radial velocity of the output is set to NAN (if needed use novas_sky_pos() instead).

Parameters

  | frame | The observer frame, defining the location and time of observation
  | pos | [AU] Geometric position of source in ICRS coordinates
  | sys | The coordinate system in which to return the apparent sky location
  [out] | out | Pointer to the data structure which is populated with the calculated apparent location in the designated coordinate system. It may be the same pounter as the input position.

Returns
  0 if successful, or an error from grav_def2(), or else -1 (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_app_to_geom()
  novas_app_to_hor(), novas_sky_pos(), novas_geom_posvel()

References grav_planets(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, novas_vlen(), and vector2radec().

Referenced by novas_approx_sky_pos(), and novas_sky_pos().

## novas_get_split_time()

double novas_get_split_time | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | timescale,
|  | long *restrict | ijd )

Returns the fractional Julian date of an astronomical time in the specified timescale, as an integer and fractional part.

The two-component split of the time allows for absolute precisions at the picosecond level, as opposed to novas_set_time(), whose precision is limited to a few microseconds typically.

The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of the tdb2tt() implementation, to around 10 μs.

REFERENCES:

1. IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
2. IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
3. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
4. Kaplan, G. (2005), US Naval Observatory Circular 179.
5. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
6. https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

  | time | Pointer to the astronomical time specification data structure.
  | timescale | The astronomical time scale in which the returned Julian Date is to be provided
  [out] | ijd | [day] The integer part of the Julian date in the requested timescale. It may be NULL if not required.

Returns
  [day] The fractional part of the Julian date in the requested timescale or NAN if the time argument is NULL (ijd will be set to -1 also).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_split_time(), novas_get_time()

References NOVAS_TIMESCALES.

Referenced by supernovas::Time::jd_day(), supernovas::Time::jd_frac(), supernovas::Time::mjd(), supernovas::Time::mjd_day(), novas_diff_time_scale(), novas_get_time(), novas_get_unix_time(), novas_iso_timestamp(), novas_make_frame(), novas_timestamp(), and supernovas::Time::shifted().

## novas_get_time()

double novas_get_time | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | timescale )

Returns the fractional Julian date of an astronomical time in the specified timescale.

The returned time is accurate to a few μs (microsecond) due to the inherent precision of the double-precision result. For higher precision applications you may use novas_get_split_time() instead, which has an inherent accuracy at the picosecond level.

Parameters

  time | Pointer to the astronomical time specification data structure.
  timescale | The astronomical time scale in which the returned Julian Date is to be provided

Returns
  [day] The Julian date in the requested timescale.

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_get_split_time()

References novas_get_split_time().

Referenced by supernovas::Time::gmst(), supernovas::Time::jd(), novas_approx_sky_pos(), novas_change_observer(), novas_diurnal_eop_at_time(), novas_geom_posvel(), novas_make_frame(), novas_moon_elp_posvel_fp(), novas_site_gcrs_posvel(), novas_site_uvw(), and novas_time_gst().

## novas_get_unix_time()

time_t novas_get_unix_time | ( | const novas_timespec *restrict | time,
|  | long *restrict | nanos )

Returns the UNIX time for an astronomical time instant.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  [out] | nanos | [ns] UTC sub-second component. It may be NULL if not required.

Returns
  [s] The integer UNIX time, or -1 if the input time is NULL.

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_unix_time(), novas_get_time()

References novas_get_split_time(), and NOVAS_UTC.

Referenced by supernovas::Time::unix_time().

## novas_gmst()

double novas_gmst | ( | double | jd_ut1,
|  | double | ut1_to_tt )

Returns the Greenwich Mean Sidereal Time (GMST) for a given UT1 date, using eq.

42 from Capitaine et al. (2003).

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).
2. IERS Conventions 2010, Chapter 5, Eq. 5.32, see at https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf

Parameters

  jd_ut1 | [day] UT1-based Julian Date.
  ut1_to_tt | [s] UT1 - UTC time difference.

Returns
  [h] The Greenwich Mean Sidereal Time (GMST) in the 0-24 range.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_gast(), novas_time_gst()

References era().

Referenced by supernovas::Time::gmst(), novas_diurnal_eop_at_time(), novas_gast(), and sidereal_time().

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

double novas_hms_hours | ( | const char *restrict | hms | ) |

Returns the decimal hours for a HMS string specification.

The hour, minute, and second components may be separated by spaces, tabs, colons :, or a combination thereof. Additionally, the hours and minutes may be separated by the letter h, and the minutes and seconds may be separated by m or a single quote '. The seconds may be followed by 's' or double quote ".

There is no enforcement on the range of hours that can be represented in this way. Any finite angle is parseable, even if it is outside its conventional range of 0-24h.

For example, all of the lines below specify the same time:

23:59:59.999
23h 59m 59.999s
23h59'59.999
23 59 59.999
23 59
23h

At least the leading two components (hours and minutes) are required. If the seconds are ommitted, they will be assumed zero, i.e. 23:59 is the same as 23:59:00.000.

NOTES:

1. To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  hms | String specifying hours, minutes, and seconds, which correspond to a time between 0 and 24 h. Time in any range is permitted, but the minutes and seconds must be >=0 and <60.

Returns
  [hours] Corresponding decimal time value, or else NAN if there was an error parsing the string (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_str_hours(), novas_parse_hms(), novas_dms_degrees()

References novas_parse_hms().

## novas_hor_to_app()

int novas_hor_to_app | ( | const novas_frame *restrict | frame,
|  | double | az,
|  | double | el,
|  | RefractionModel | ref_model,
|  | enum novas_reference_system | sys,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts an observed azimuth and elevation coordinate to right ascension (R.A.) and declination coordinates expressed in the coordinate system of choice.

The observer must be located on the surface of Earth, or else the call will return with an error. The caller may optionally supply a refraction model of choice to calculate an appropriate elevation angle that includes a refraction correction for Earth's atmosphere. If no such model is provided, the provided elevation value will be assumed to be an astrometric elevation without a refraction correction.

Parameters

  | frame | Observer frame, defining the time and place of observation (on Earth).
  | az | [deg] Observed azimuth angle. It may be NULL if not required.
  | el | [deg] Observed elevation angle. It may be NULL if not required.
  | ref_model | An appropriate refraction model, or NULL to assume unrefracted elevation. Depending on the refraction model, you might want to make sure that the weather parameters were set when the observing frame was defined.
  | sys | Astronomical coordinate system in which the output is R.A. and declination values are to be calculated.
  [out] | ra | [h] Calculated apparent right ascension (R.A.) coordinate
  [out] | dec | [deg] Calculated apparent declination coordinate

Returns
  0 if successful, or else an error from itrs_to_tod() or itrs_to_cirs(), or -1 (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_app_to_hor()
  novas_app_to_geom(), novas_standard_refraction(), novas_optical_refraction(), novas_radio_refraction(), novas_wave_refraction()

References novas_timespec::fjd_tt, hor_to_itrs(), novas_timespec::ijd_tt, NOVAS_AIRBORNE_OBSERVER, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_OBSERVER_ON_EARTH, NOVAS_REFRACT_OBSERVED, NOVAS_TIRS, NOVAS_TOD, spin(), vector2radec(), wobble(), WOBBLE_ITRS_TO_PEF, and WOBBLE_ITRS_TO_TIRS.

Referenced by supernovas::Horizontal::to_apparent().

## novas_hor_track()

int novas_hor_track | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame,
|  | RefractionModel | ref_model,
|  | novas_track *restrict | track )

Calculates horizontal tracking position and motion (first and second time derivatives) for the specified source in the given observing frame.

The position and its derivatives are calculated via the more precise IAU2006 method, and CIRS, and then converted to local horizontal coordinates using the specified refraction model (if any).

Parameters

  | source | Observed source
  | frame | Observing frame, defining the observer location and astronomical time of observation.
  | ref_model | Refraction model to use, or NULL for an unrefracted track.
  [out] | track | Output tracking parameters to populate

Returns
  0 if successful, or else -1 if any of the pointer arguments are NULL, or else an error code from novas_sky_pos(), or from novas_app_hor().

Since
  1.3

Author
  Attila Kovacs

See also
  novas_equ_track(), novas_track_pos()

References novas_sky_pos::dec, novas_sky_pos::dis, novas_timespec::fjd_tt, ira_equinox(), NOVAS_AIRBORNE_OBSERVER, novas_app_to_hor(), NOVAS_CIRS, novas_make_frame(), NOVAS_OBSERVER_ON_EARTH, novas_sky_pos(), NOVAS_TOD, NOVAS_TRUE_EQUINOX, novas_v2z(), novas_sky_pos::ra, novas_sky_pos::rv, and SKY_POS_INIT.

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

## novas_icrs_to_sys()

int novas_icrs_to_sys | ( | const double * | in,
|  | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | enum novas_reference_system | sys,
|  | double * | out )

Converts a rectangular equatorial vector from the International Coordinate Reference System (ICRS) or equivalent, such as GCRS, to the desired output equatorial coordinate reference system of choice.

Note, that this function does not support conversion to an Earth rotating system, such as TIRS or ITRS.

Parameters

  | in | Input ICRS / GCRS vector (double[3]).
  | jd_tdb | Barycentric Dynamical Time (TDB) based Julian Date. (Unused if output system is ICRS / GCRS or J2000). TT-based Julian Dates may be used also without loss of precision.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
  | sys | Iutput coordinate system. It cannot be NOVAS_TIRS or NOVAS_ITRS, or else the function will return an error (-1 / ENOSYS).
  [out] | out | Output vector (double[3]) to be populated. It may be the same vector as the input.

Returns
  0 if successful or else -1 if any of the vectors is NULL or (errno set to EINVAL), or the coordinate system is unsupported (errno set to ENOSYS) or out of range (errno set to ERANGE).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_sys_to_icrs()

References gcrs_to_cirs(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_TIRS, and NOVAS_TOD.

Referenced by place(), and supernovas::Equatorial::to_system().

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

double novas_inv_refract | ( | RefractionModel | model,
|  | double | jd_tt,
|  | const on_surface *restrict | loc,
|  | enum novas_refraction_type | type,
|  | double | el0 )

Computes the reverse atmospheric refraction for a given refraction model.

Thus if a refraction model takes observed elevation as an input, the reverse refraction takes astrometric elevation as its input, and vice versa.

Parameters

  model | The original refraction model
  jd_tt | [day] Terrestrial Time (TT) based Julian data of observation
  loc | Pointer to structure defining the observer's location on earth, and local weather
  type | Refraction type to use for the original model: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
  el0 | [deg] input elevation for the inverse refraction model.

Returns
  [deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).

See also
  refract_astro(), itrs_to_hor()

Since
  1.1

Author
  Attila Kovacs

References novas_inv_max_iter, and NOVAS_REFRACT_OBSERVED.

Referenced by novas_radio_refraction(), and novas_wave_refraction().

## novas_invert_transform()

int novas_invert_transform | ( | const novas_transform * | transform,
|  | novas_transform * | inverse )

Inverts a novas coordinate transformation matrix.

Parameters

  | transform | Pointer to a coordinate transformation matrix.
  [out] | inverse | Pointer to a coordinate transformation matrix to populate with the inverse transform. It may be the same as the input.

Returns
  0 if successful, or else -1 if the was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_make_transform()

References novas_transform::matrix.

## novas_iso_timestamp()

int novas_iso_timestamp | ( | const novas_timespec *restrict | time,
|  | char *restrict | dst,
|  | int | maxlen )

Prints a UTC-based ISO timestamp to millisecond precision to the specified string buffer.

E.g.:

2025-01-26T21:32:49.701Z

NOTES:

1. As per the ISO 8601 specification, the timestamp uses the Gregorian date, even for dates prior to the Gregorian calendar reform of 15 October 1582 (i.e. proleptic Gregorian dates).
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  [out] | dst | Output string buffer. At least 25 bytes are required for a complete timestamp with termination.
  | maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen, then it will be truncated to fit in the allotted space, including a termination character.

Returns
  the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_timestamp(), novas_parse_iso_date()

References novas_get_split_time(), NOVAS_GREGORIAN_CALENDAR, and NOVAS_UTC.

Referenced by supernovas::Time::to_iso_string().

## novas_itrf_transform()

int novas_itrf_transform | ( | int | from_year,
|  | const double *restrict | from_coords,
|  | const double *restrict | from_rates,
|  | int | to_year,
|  | double * | to_coords,
|  | double * | to_rates )

Converts ITRF coordinates between different realizations of the ITRF coordinate system.

It does not account for station motions, which the user should apply separately. For example, consider the use case when input coordinates are given in ITRF88, for measurement in the epoch 1994.36, and output is expected in ITRF2000 for measurements at 2006.78. This function simply translates the input, measured in epoch 1994.36, to ITRF2000. Proper motion between the epochs (2006.78 and 1994.36) can be calculated with the input rates before conversion, e.g.:

// Apply station motion in ITRF88
for(i = 0; i < 3; i++)
from_coords[i] += from_rates[i] * (2006.78 - 1994.36)
// Convert ITRF88 coordinates to ITRF2000
novas_itrf_transform(1988, from_coords, from_rates, 2000, ...);
novas_itrf_transform
int novas_itrf_transform(int from_year, const double *restrict from_coords, const double *restrict from_rates, int to_year, double *to_coords, double *to_rates)
Converts ITRF coordinates between different realizations of the ITRF coordinate system.
Definition itrf.c:222

or equivalently, after the transformation to ITRF2000, as:

// Convert ITRF88 coordinates to ITRF2000
novas_itrf_transform(1988, from_coords, from_rates, 2000, to_coords, to_rates);
// Apply station motion in ITRF2000
for(i = 0; i < 3; i++)
to_coords[i] += to_rates[i] * (2006.78 - 1994.36)

REFERENCES:

1. IERS Conventions, Chapter 4, Eq. 4.13 and Table 4.1. See https://iers-conventions.obspm.fr/content/chapter4/icc4.pdf

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | from_coords | [m] input ITRF coordinates.
  [in] | from_rates | [m/yr] input ITRF coordinate rates, or NULL if not known or needed.
  | to_year | [yr] ITRF realization year of output coordinates / rates. E.g. 2014 for ITRF2014.
  [out] | to_coords | [m] ITRF coordinates at final year, or NULL if not required. It may be the same as either of the inputs.
  [out] | to_rates | [m/yr] ITRF coordinate rates at final year, or NULL if not known or needed. It may be the same as either of the inputs.

Returns
  0 if successful, or else -1 (errno set to EINVAL) if the input coordinates are NULL, or if input rates are NULL but output_rates are not NULL.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform_site(), novas_itrf_transform_eop()
  novas_geodetic_to_cartesian()

Referenced by novas_itrf_transform_site().

## novas_itrf_transform_eop()

int novas_itrf_transform_eop | ( | int | from_year,
|  | double | from_xp,
|  | double | from_yp,
|  | double | from_dut1,
|  | int | to_year,
|  | double *restrict | to_xp,
|  | double *restrict | to_yp,
|  | double *restrict | to_dut1 )

Transforms Earth orientation parameters (xp, yp, dUT1) from one ITRF realization to another.

For the highest precision applications, observing sites should be defined in the same ITRF realization as the IERS Earth orientation parameters (EOP). To reconcile you may transform either the site location or the EOP between different realizations to match.

REFERENCES:

1. IERS Conventions, Chapter 4, Eq. 4.14 and Table 4.1. See https://iers-conventions.obspm.fr/content/chapter4/icc4.pdf

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | from_xp | [arcsec] x-pole Earth orientation parameter (angle) in the input ITRF realization.
  [in] | from_yp | [arcsec] y-pole Earth orientation parameter (angle) in the input ITRF realization.
  [in] | from_dut1 | [s] UT1-UTC time difference in the input ITRF realization.
  | to_year | [yr] ITRF realization year of input coordinates / rates. E.g. 2000 for ITRF2000.
  [out] | to_xp | [arcsec] x-pole Earth orientation parameter (angle) in the output ITRF realization, or NULL if not required.
  [out] | to_yp | [arcsec] y-pole Earth orientation parameter (angle) in the output ITRF realization, or NULL if not required.
  [out] | to_dut1 | [s] UT1-UTC time difference in the output ITRF realization, or NULL if not required.

Returns
  0

Since
  1.5

Author
  Attila Kovacs

See also
  novas_itrf_transform(), novas_itrf_transform_site(), novas_get_eop_itrf_year()
  novas_make_frame(), novas_timespec, wobble()

References NOVAS_DAY, NOVAS_EARTH_FLATTENING, and TWOPI.

Referenced by supernovas::EOP::itrf_transformed().

## novas_itrf_transform_site()

int novas_itrf_transform_site | ( | int | from_year,
|  | const on_surface * | in,
|  | int | to_year,
|  | on_surface * | out )

Transforms a geodetic location between two International Terrestrial Reference Frame (ITRF) realizations.

ITRF realizations differ at the mm / μas level. Thus for the highest accuracy astrometry, from e.g. VLBI sites, it may be desirable to ensure that the site coordinates are defined for the same ITRF realization, as the one in which Earth-orientation parameters (EOP) are provided for novas_make_frame(), novas_timespec, or wobble().

Parameters

  | from_year | [yr] ITRF realization year of input coordinates / rates. E.g. 1992 for ITRF92.
  [in] | in | Input site, defined in the original ITRF realization.
  | to_year | [yr] ITRF realization year of input coordinates / rates. E.g. 2000 for ITRF2000.
  [out] | out | Output site, calculated for the final ITRF realization. It may be the same as the input.

Returns
  0 if successful, or else -1 if either site pointer is NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_geodetic_transform_site(), novas_itrf_transform_eop(), novas_itrf_transform(), make_itrf_site(), make_itrf_observer()

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::longitude, novas_cartesian_to_geodetic(), novas_geodetic_to_cartesian(), NOVAS_GRS80_ELLIPSOID, novas_itrf_transform(), novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::itrf_transformed().

## novas_itrs_to_enu()

int novas_itrs_to_enu | ( | const double * | itrf,
|  | double | lon,
|  | double | lat,
|  | double * | enu )

Converts an ITRS position vector to a local East-North-Up (ENU) vector at the specified site.

Parameters

  | itrf | xyz position vector in ITRS.
  | lon | [deg] ITRS longitude of site.
  | lat | [deg] ITRS latitude of site.
  [out] | enu | output East-North-Up (ENU) vector. It may be the same vector as the input.

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

Since
  1.6

Author
  Attila Kovacs

See also
  novas_enu_to_itrs()

Referenced by supernovas::GeodeticObserver::enu_velocity(), supernovas::Site::itrs_to_enu(), and supernovas::Site::itrs_to_enu().

## novas_jd_from_date()

double novas_jd_from_date | ( | enum novas_calendar_type | calendar,
|  | int | year,
|  | int | month,
|  | int | day,
|  | double | hour )

Returns the Julian day for a given calendar date.

Input time value can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output Julian date will have the same basis.

The input date is the conventional calendar date, affected by the Gregorian calendar reform of

1. Thus, the input date is for the Gregorian calendar for dates starting 15 October 1582, and for the Julian (Roman) calendar (introduced in 45 B.C.) for dates prior to that.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.
2. Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

  calendar | The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
  year | [yr] Calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
  month | [month] Calendar month [1:12]
  day | [day] Day of month [1:31]
  hour | [hr] Hour of day [0:24]

Returns
  [day] the fractional Julian day for the input calendar date, or NAN if the calendar is invalid or the month or day components are out of range.

Author
  Attila Kovacs

Since
  1.3

See also
  novas_jd_to_date(), novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

Referenced by supernovas::CalendarDate::CalendarDate(), julian_date(), and novas_parse_date_format().

## novas_jd_to_date()

int novas_jd_to_date | ( | double | tjd,
|  | enum novas_calendar_type | calendar,
|  | int *restrict | year,
|  | int *restrict | month,
|  | int *restrict | day,
|  | double *restrict | hour )

This function will compute a broken down date on the specified calendar for given the Julian day input.

Input Julian day can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

  | tjd | [day] Julian day.
  | calendar | The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
  [out] | year | [yr] Calendar year. B.C. years are represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X). It may be NULL if not required.
  [out] | month | [month] Calendar month [1:12]. It may be NULL if not required.
  [out] | day | [day] Day of the month [1:31]. It may be NULL if not required.
  [out] | hour | [h] Hour of day [0:24]. It may be NULL if not required.

Returns
  0 if successful, or else -1 if the calendar is invalid (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_jd_from_date(), novas_set_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

Referenced by supernovas::CalendarDate::CalendarDate(), cal_date(), and novas_day_of_year().

## novas_los_to_xyz()

int novas_los_to_xyz | ( | const double * | los,
|  | double | lon,
|  | double | lat,
|  | double * | xyz )

Converts a 3D line-of-sight vector (δφ, δθ, δr) to a rectangular equatorial (δx, δy, δz) vector.

Parameters

  | los | [arb.u.] Line-of-sight 3-vector (δφ, δθ, δr).
  | lon | [deg] Line-of-sight longitude.
  | lat | [deg] Line-of-sight latitude.
  [out] | xyz | [arb.u.] Output rectangular equatorial 3-vector (δx, δy, δz), in the same units as the input. It may be the same vector as the input.

Returns
  0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_xyz_to_los(), novas_uvw_to_xyz()

Referenced by novas_uvw_to_xyz(), starvectors(), and transform_cat().

## novas_lsr_to_ssb_vel()

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

Returns a Solar System Baricentric (SSB) radial velocity for a radial velocity that is referenced to the Local Standard of Rest (LSR).

Internally, NOVAS always uses barycentric radial velocities, but it is just as common to have catalogs define radial velocities referenced to the LSR.

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

REFERENCES:

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

Parameters

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

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

Since
  1.3

Author
  Attila Kovacs

See also
  novas_ssb_to_lsr_vel(), make_cat_entry()
  novas_str_hours(), novas_str_degrees()

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

Referenced by novas_set_lsr_vel().

## novas_make_frame()

int novas_make_frame | ( | enum novas_accuracy | accuracy,
|  | const observer * | obs,
|  | const novas_timespec * | time,
|  | double | xp,
|  | double | yp,
|  | novas_frame * | frame )

Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.

The frame is initialized using the currently configured planet ephemeris provider function (see set_planet_provider() and set_planet_provider_hp()), and in case of reduced accuracy mode, the currently configured IAU nutation model provider (see set_nutation_lp_provider()).

Note, that to construct full accuracy frames, you will need a high-precision ephemeris provider for the major planets (not just the default Earth/Sun), as without it, gravitational bending around massive plannets cannot be accounted for, and therefore μas accuracy cannot be ensured, in general. Attempting to construct a high-accuracy frame without a high-precision ephemeris provider for the major planets will result in an error in the 10–40 range from the required ephemeris() call.

NOTES:

1. This function expects the Earth polar wobble parameters to be defined on a per-frame basis and will not use the legacy global (undated) orientation parameters set via cel_pole().
2. The Earth orientation parameters xp, yp should be provided in the same ITRF realization as the observer location for an Earth-based observer. You can use novas_itrf_transform_eop() to convert the EOP values as necessary.
3. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the polar offsets is not possible. You must set xp and yp appropriately explicitly.

Parameters

  | accuracy | Accuracy requirement, NOVAS_FULL_ACCURACY (0) for the utmost precision or NOVAS_REDUCED_ACCURACY (1) if ~1 mas accuracy is sufficient.
  | obs | Observer location
  | time | Time of observation
  | xp | [mas] Earth orientation parameter, mean polar offset in x, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (The global, undated, value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
  | yp | [mas] Earth orientation parameter, mean polar offset in y, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (The global, undated, value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
  [out] | frame | Pointer to the observing frame to configure.

Returns
  0 if successful, 10–40: error is 10 + the error from ephemeris(), 40–50: error is 40 + the error from geo_posvel(), or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_change_observer(), novas_sky_pos(), novas_geom_posvel(), novas_make_transform()
  set_planet_provider(), set_planet_provider_hp(), set_nutation_lp_provider(), novas_itrf_transform_eop(), novas_set_auto_fetch_eop()

References novas_frame::accuracy, novas_frame::deps0, novas_frame::dpsi0, novas_frame::dx, novas_frame::dy, novas_frame::earth_pos, novas_frame::earth_vel, novas_frame::ee, ephemeris(), era(), novas_frame::era, novas_timespec::fjd_tt, novas_frame::gst, novas_timespec::ijd_tt, mean_obliq(), novas_frame::mobl, NOVAS_BARYCENTER, novas_change_observer(), novas_diurnal_eop_at_time(), NOVAS_EARTH_INIT, novas_fetch_eop(), NOVAS_FULL_ACCURACY, novas_get_split_time(), novas_get_time(), novas_is_auto_fetch_eop(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_UT1, NOVAS_UTC, nutation_angles(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, novas_timespec::tt2tdb, novas_observer::where, novas_eop::xp, and novas_eop::yp.

Referenced by supernovas::Frame::Frame(), novas_equ_track(), and novas_hor_track().

## 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 supernovas::Orbital::moon_mean_orbit_at(), and 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 supernovas::Orbital::moon_orbit_at(), and 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(), novas_moon_phase(), and supernovas::Planet::orbit().

## novas_make_transform()

int novas_make_transform | ( | const novas_frame * | frame,
|  | enum novas_reference_system | from_system,
|  | enum novas_reference_system | to_system,
|  | novas_transform * | transform )

Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

Parameters

  | frame | Observer frame, defining the location and time of observation
  | from_system | Original coordinate reference system
  | to_system | New coordinate reference system
  [out] | transform | Pointer to the transform data structure to populate.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_transform_vector(), novas_transform_sky_pos(), novas_invert_transform()
  novas_geom_posvel(), novas_app_to_geom()

References novas_frame::era, novas_transform::frame, novas_transform::from_system, novas_frame::gcrs_to_cirs, novas_frame::icrs_to_j2000, novas_matrix::M, novas_transform::matrix, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TIRS, NOVAS_TOD, novas_frame::nutation, novas_frame::precession, and novas_transform::to_system.

Referenced by novas_moon_elp_posvel_fp(), novas_moon_elp_sky_pos_fp(), and supernovas::Geometric::to_system().

## novas_mean_clock_skew()

double novas_mean_clock_skew | ( | const novas_frame * | frame,
|  | enum novas_timescale | timescale )

Returns the averaged incremental rate at which the observer's clock (i.e.

proper time τ) ticks faster than a clock in the specified timescale. I.e., it returns D, which is defined by:

dτobs / dttimescale = (1 + D)

For a non-Earth-bound observer, this is the same as the instantaneous rate returned by novas_clock_skew(). For an Earth-bound observer however, this function returns the averaged value over the observer's rotation around the geocenter. As such it filters out the tiny diurnal or orbital tidal variations as the observer moves through the tidal potential around the geocenter (mainly due to the Sun and Moon). Thus, for Earth-bound observers it returns Eqs. 10.6 and 10.8 of the IERS Conventions.

For reduced accuracy frames, the result will be approximate, because the gravitational effect of the Sun and Earth alone may be accounted for.

NOTES:

1. Based on the IERS Conventions 2010, Chapter 10, Eqs. 10.6 / 10.8, but modified for relativistic observer motion.
2. The potential for an observer inside 0.9 planet radii of a major Solar-system body's center will not include the term for that body in the calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 10, see at https://iers-conventions.obspm.fr/content/chapter10/tn36_c10.pdf

Parameters

  frame | The observing frame, defining the observer position as well as the positions of the major solar-system bodies at the time of observation.
  timescale | Reference timescale for the comparison. All timescales are supported, except NOVAS_UT1 (since UT1 advances at an irregular rate).

Returns
  The average incremental rate over a geocentric rotation, at which the observer's proper time clock ticks faster than the specified timescale, or else NAN if the input frame is NULL or uninitialized, or if the timescale is not supported (errno set to EINVAL), or if the frame is configured for full accuracy but it does not have sufficient planet position information to evaluate of the local gravitational potential with precision (errno set to EAGAIN).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_clock_skew()

References novas_clock_skew().

## novas_moon_angle()

double novas_moon_angle | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame )

Returns the apparent angular distance of a source from the Moon from the observer's point of view.

Parameters

  source | An observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.

Returns
  [deg] Apparent angular distance between the source and the Moon, from the observer's point of view.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_sun_angle()

References NOVAS_MOON_INIT, and novas_object_sep().

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

## novas_moon_elp_ecl_pos()

int novas_moon_elp_ecl_pos | ( | double | jd_tdb,
|  | double | limit,
|  | double * | pos )

Calculates the Moon's geocentric position using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.

the inertial ecliptic and equinox of J2000), down to the specified limiting term amplitude.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below 1 km level (and less than 100 meter error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | limit | [arcsec|km] Sum only the harmonic terms with amplitudes larger than this limit.
  [out] | pos | [AU] Output geocentric position vector w.r.t. the intertial ecliptic and equinox of J2000.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

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

References NOVAS_AU, NOVAS_EARTH, NOVAS_JD_J2000, NOVAS_KM, NOVAS_NEPTUNE, NOVAS_SATURN, NOVAS_VENUS, and planet_lon().

Referenced by novas_moon_elp_ecl_vel(), novas_moon_elp_posvel_fp(), and novas_moon_phase().

## novas_moon_elp_ecl_vel()

int novas_moon_elp_ecl_vel | ( | double | jd_tdb,
|  | double | limit,
|  | double * | vel )

Calculates the Moon's geocentric velocity using the ELP/MPP02 model by Chapront & Francou (2003), in the ELP2000 reference plane (i.e.

the inertial ecliptic and equinox of J2000), down to the specified limiting term amplitude.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | limit | [arcsec|km] Sum only the harmonic terms with amplitudes larger than this limit.
  [out] | vel | [AU/day] Output geocentric velocity vector w.r.t. the intertial ecliptic and equinox of J2000.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

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

References novas_moon_elp_ecl_pos().

Referenced by novas_moon_elp_posvel_fp().

## novas_moon_elp_posvel()

int novas_moon_elp_posvel | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 km level (and less than 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | [AU] The Moon's position vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.
  [out] | vel | [AU/day] The Moon's ICRS velocity vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel_fp(), novas_moon_elp_sky_pos()
  novas_make_moon_orbit(), novas_geom_posvel()

References novas_moon_elp_posvel_fp().

## novas_moon_elp_posvel_fp()

int novas_moon_elp_posvel_fp | ( | const novas_frame *restrict | frame,
|  | double | limit,
|  | enum novas_reference_system | sys,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns the Moon's geometric position and velocity, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

Only terms larger than the specified limit are used to provide a result with the desired precision.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 km level (and less than 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | limit | [arcsec|km] Sum only terms with amplitudes larger than this limit. The resulting accuracy is typically an order-of-magnitude above the set limiting amplitude.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | [AU] The Moon's position vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.
  [out] | vel | [AU/day] The Moon's ICRS velocity vector relative to the observer (or geocenter), in the specified coordinate reference system, or NULL if not required.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_posvel(), novas_moon_elp_sky_pos_fp()
  novas_make_moon_orbit(), novas_geom_posvel()

References ecl2equ_vec(), NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_J2000, NOVAS_JD_J2000, novas_make_transform(), NOVAS_MEAN_EQUATOR, novas_moon_elp_ecl_pos(), novas_moon_elp_ecl_vel(), NOVAS_REDUCED_ACCURACY, NOVAS_TDB, and novas_transform_vector().

Referenced by supernovas::Frame::geometric_moon_elp2000(), novas_moon_elp_posvel(), and novas_moon_elp_sky_pos_fp().

## novas_moon_elp_sky_pos()

int novas_moon_elp_sky_pos | ( | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | pos )

Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 arcsec level (and less than 0.1 arcsec or 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | The Moon's position, relative to the true equator and equinox of date.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_sky_pos_fp(), novas_moon_elp_posvel()
  novas_make_moon_orbit(), novas_sky_pos()

References novas_moon_elp_sky_pos_fp().

## novas_moon_elp_sky_pos_fp()

int novas_moon_elp_sky_pos_fp | ( | const novas_frame *restrict | frame,
|  | double | limit,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | pos )

Returns the Moon's apparent place, relative to an Earth-based observer (or the geocenter), using the ELP/MPP02 model by Chapront & Francou (2003).

Only terms larger than the specified limit are used to provide a result with the desired precision.

NOTES:

1. The initial implementation (in v1.6) truncates the full series, keeping only terms with amplitudes larger than 1 mas (around 3400 harmonic terms in total), resulting in a limiting accuracy below the 1 arcsec level (and less than 0.1 arcsec or 100 m error typically for 1900 – 2100).

REFERENCES:

1. Chapront-Touze, M., & Chapront, J., A&A, 190, 342 (1988)
2. Chapront, J., Francou G., 2003, A&A, 404, 735
3. Chapront, J., & Francou, G., "LUNAR SOLUTION ELP version ELP/MPP02", (October 2002), https://cyrano-se.obspm.fr/pub/2_lunar_solutions/2_elpmpp02/

Parameters

  | frame | Earth-based observing frame
  | limit | [arcsec|km] Sum only terms with amplitudes larger than this limit. The resulting accuracy is typically an order-of-magnitude above the set limiting amplitude.
  | sys | The celestial coordinate reference system in which to return the result. (It may not be Earth-based TIRS or ITRS).
  [out] | pos | The Moon's position, relative to the true equator and equinox of date.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_moon_elp_sky_pos(), novas_moon_elp_posvel()
  novas_make_moon_orbit(), novas_sky_pos()

References aberration(), NOVAS_AU_PER_DAY, NOVAS_ICRS, NOVAS_KMS, novas_make_transform(), novas_moon_elp_posvel_fp(), novas_transform_vector(), novas_vlen(), and vector2radec().

Referenced by supernovas::Frame::apparent_moon_elp2000(), and novas_moon_elp_sky_pos().

## novas_moon_phase()

double novas_moon_phase | ( | double | jd_tdb | ) |

Calculates the Moon's phase at a given time.

It uses orbital models for Earth (E.M. Standish and J.G. Williams 1992), and the ELP2000/MPP02 semi-analytical model for the Moon (Chapront & Francou, 2002, 2003), and takes into account the slightly eccentric nature of both orbits.

NOTES:

1. The Moon's phase here follows the definition by the Astronomical Almanac, as the excess ecliptic longitude of the Moon over that of the Sun seen from the geocenter.
2. There are other definitions of the phase too, depending on which you might find slightly different answers, but regardless of the details most phase calculations should match to within a few degrees.
3. As of version 1.6, this function relies on the ELP2000/MM02 semi-analytical model of the Moon by Chapront & Francou (2003).
4. This function caches the result of the last calculation.

REFERENCES:

1. The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
2. E.M. Standish and J.G. Williams 1992.
3. https://ssd.jpl.nasa.gov/planets/approx_pos.html
4. Chapront, J. et al., 2002, A&A 387, 700–709
5. Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.
6. Chapront J., & Francou G., 2003, A&A, 404, 735<

Parameters

  jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian Date.

Returns
  [deg] The Moon's phase, or more precisely the ecliptic longitude difference between the Sun and the Moon, as seen from the geocenter. 0: New Moon, 90: 1st quarter, +/- 180 Full Moon, -90: 3rd quarter or NAN if the solution failed to converge (errno will be set to ECANCELED), or if the JD date is outside the range of the orbital model (errno set to EINVAL).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_next_moon_phase(), novas_make_moon_orbit(), novas_solar_illum()

References NOVAS_EMB, novas_make_planet_orbit(), novas_moon_elp_ecl_pos(), NOVAS_ORBIT_INIT, novas_orbit_native_posvel(), and vector2radec().

Referenced by supernovas::Time::moon_phase(), and novas_next_moon_phase().

## novas_next_moon_phase()

double novas_next_moon_phase | ( | double | phase,
|  | double | jd_tdb )

Calculates the date / time at which the Moon will reach the specified phase next, after the specified time.

It uses orbital models for Earth (E.M. Standish and J.G. Williams 1992), and the ELP2000/MPP02 semi-analytical model for the Moon (Chapront & Francou, 2002, 2003), and takes into account the slightly eccentric nature of both orbits.

NOTES:

1. The Moon's phase here follows the definition by the Astronomical Almanac, as the excess ecliptic longitude of the Moon over that of the Sun seen from the geocenter.
2. There are other definitions of the phase too, depending on which you might find slightly different answers, but regardless of the details most phase calculations should match give or take a few hours.
3. As of version 1.6, this function relies on the ELP2000/MM02 semi-analytical model of the Moon by Chapront & Francou (2003).

REFERENCES:

1. The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
2. E.M. Standish and J.G. Williams 1992.
3. https://ssd.jpl.nasa.gov/planets/approx_pos.html
4. Chapront, J., & Francou, G., 2002, A&A 387, 700–709
5. Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

  phase | [deg] The Moon's phase, or more precisely the ecliptic longitude difference between the Sun and the Moon, as seen from the geocenter. 0: New Moon, 90: 1st quarter, +/- 180 Full Moon, -90: 3rd quarter.
  jd_tdb | [day] The lower bound date for the phase, as a Barycentric Dynamical Time (TDB) based Julian Date.

Returns
  [day] The Barycentric Dynamical Time (TDB) based Julian Date when the Moon will be in the desired phase next after the input date; or NAN if the solution failed to converge (errno will be set to ECANCELED).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_moon_phase(), novas_make_moon_orbit()

References novas_inv_max_iter, NOVAS_JD_J2000, and novas_moon_phase().

Referenced by supernovas::Time::next_moon_phase().

## novas_norm_ang()

double novas_norm_ang | ( | double | angle | ) |

Returns the normalized angle in the [0:2π) range.

Parameters

  angle | [rad] an angle in radians.

Returns
  [rad] the normalized angle in the [0:2π) range.

Since
  1.0

Author
  Attila Kovacs

References TWOPI.

Referenced by fund_args().

## novas_object_sep()

double novas_object_sep | ( | const object * | source1,
|  | const object * | source2,
|  | const novas_frame *restrict | frame )

Returns the angular separation of two objects from the observer's point of view.

The calculated separation includes light-time corrections, aberration and gravitational deflection for both sources, and thus represents a precise observed separation between the two sources.

Parameters

  source1 | An observed source
  source2 | Another observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.

Returns
  [deg] Apparent angular separation between the two observed source from the observer's point-of-view.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_sep(), novas_sun_angle(), novas_moon_angle()

References novas_sky_pos::dec, novas_sky_pos::dis, novas_equ_sep(), NOVAS_GCRS, novas_sky_pos(), novas_sky_pos::ra, and SKY_POS_INIT.

Referenced by supernovas::Source::angle_to(), novas_moon_angle(), and novas_sun_angle().

## novas_offset_by()

int novas_offset_by | ( | double | lon,
|  | double | lat,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_lon,
|  | double *restrict | out_lat )

Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.

Based on the astropy offset_by() implementation.

Parameters

  | lon | [deg] reference point longitude
  | lat | [deg] reference point latitude
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_lon | [deg] longitude at offset position in [-π:π) range. It may be NULL if not needed.
  [out] | out_lat | [deg] latitude at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and longitude at the offset position is requested, or if the input latitude is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equ_offset_by(), novas_sep()
  https://docs.astropy.org/en/stable/_modules/astropy/coordinates/angles/utils.html#offset_at

Referenced by novas_equ_offset_by(), supernovas::Ecliptic::offset(), supernovas::Equatorial::offset(), supernovas::Galactic::offset(), and supernovas::Horizontal::offset().

## novas_offset_time()

int novas_offset_time | ( | const novas_timespec * | time,
|  | double | seconds,
|  | novas_timespec * | out )

Increments the astrometric time by a given amount.

Parameters

  | time | Original time specification
  | seconds | [s] Seconds to add to the original
  [out] | out | New incremented time specification. It may be the same as the input.

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

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_diff_time()

References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.

## novas_orbit_native_posvel()

int novas_orbit_native_posvel | ( | double | jd_tdb,
|  | const novas_orbital *restrict | orbit,
|  | 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, in the native coordinate system in which the orbital is defined (e.g.

ecliptic for heliocentric orbitals).

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
  [out] | pos | [AU] Output ICRS equatorial position vector around orbital center, or NULL if not required.
  [out] | vel | [AU/day] Output ICRS velocity vector rel. to orbital center, in the native system of the orbital, or NULL if not required. 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.4

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

References TWOPI.

Referenced by novas_moon_phase(), and novas_orbit_posvel().

## 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(), novas_approx_heliocentric(), supernovas::Orbital::position(), and supernovas::Orbital::velocity().

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

int novas_print_dms | ( | double | degrees,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

The degrees component is always printed as 4 characters (up to 3 digits plus optional negative sign), so the output is always aligned. If positive values are expected to be explicitly signed also, the caller may simply put the '+' sign into the leading byte.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | degrees | [deg] angle value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print DMS string, represented in the [-180:180) degree range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_dms(), novas_print_hms()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

Referenced by supernovas::Angle::to_string().

## novas_print_hms()

int novas_print_hms | ( | double | hours,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | hours | [h] time value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print HMS string, represented in the [0:24) hour range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_hms(), novas_print_dms(), novas_timestamp()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

Referenced by supernovas::TimeAngle::to_string().

## novas_print_timescale()

int novas_print_timescale | ( | enum novas_timescale | scale,
|  | char *restrict | buf )

Prints the standard string representation of the timescale to the specified buffer.

The string is terminated after. E.g. "UTC", or "TAI". It will print dates in the Gregorian calendar, which was introduced on 15 October 1582 only.

Parameters

  scale | The timescale
  buf | String in which to print. It should have at least 4-bytes of available storage.

Returns
  the number of characters printed, not including termination, or else -1 if the timescale is invalid or the output buffer is NULL.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_timestamp(), novas_timescale_for_string()

References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

Referenced by novas_timestamp().

## novas_reset_eop()

void novas_reset_eop | ( |  | ) |

Releases resources used by URL handles used for obtaining Earth Orientation Parameter (EOP) data from the International Earth Rotation and Reference Systems Service (IERS), including the leap seconds list supplied earlier or obtained from IERS.

It also discards any custom URLs that may have been set previously, and restores the default IERS URLs for obtaining leap seconds and EOP from IERS. The cleanup performed by this function is automatic at normal program exit, but users may call it explicitly restore the initial state at any point.

NOTES:

- This call does not affect or destroy any thread-local data currently cached. As such, novas_fetch_eop() may continue to return EOP using the previously cached values, if the requested date falls within the same data bracket as the last call.
- This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_set_leap_list(), novas_fetch_eop()

## novas_rises_above()

double novas_rises_above | ( | double | el,
|  | const object *restrict | source,
|  | const novas_frame *restrict | frame,
|  | RefractionModel | ref_model )

Returns the UTC date at which a distant source appears to rise above the specified elevation angle.

The calculated time will account for the (slow) motion for Solar-system bodies, and optionally for atmospheric refraction also.

NOTES:

1. The current implementation is not suitable for calculating the nearest successive rise times for near-Earth objects, at or within the geostationary orbit.
2. This function calculates the time when the center (not the limb!) of the source rises above the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

  el | [deg] Elevation angle.
  source | Observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.
  ref_model | Refraction model, or NULL to calculate unrefracted rise time.

Returns
  [day] UTC-based Julian date at which the object rises above the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour period.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_sets_below(), novas_transit_time()

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

## novas_sep()

double novas_sep | ( | double | lon1,
|  | double | lat1,
|  | double | lon2,
|  | double | lat2 )

Returns the angular separation of two locations on a sphere.

It uses the Vincenty formula for accurate results across all locations on the sphere.

NOTES:

1. Prior to version 1.5, this function used the law of cosines, which is imprecise for nearby locations
2. In version 1.5, this function used the haversine formula, albeit with an error in the implementation. The haversine formula is accurate for nearby locations, but has rounding errors for antipodal locations.
3. From version 1.5.1, this function uses the Vincenty formula, which is accurate for all locations on the sphere.

REFERENCES:

1. Vincenty, Thaddeus. "Direct and Inverse Solutions of Geodesics on the Ellipsoid with Application of Nested Equations", Survey Review. 23 (176), Directorate of Overseas Surveys, doi:10.1179/sre.1975.23.176.88.

Parameters

  lon1 | [deg] longitude of first location
  lat1 | [deg] latitude of first location
  lon2 | [deg] longitude of second location
  lat2 | [deg] latitude of second location

Returns
  [deg] the angular separation of the two locations.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_equ_sep(), novas_sun_angle(), novas_moon_angle()
  novas_offset_by()

Referenced by supernovas::Spherical::distance_to(), and novas_equ_sep().

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

int novas_set_current_time | ( | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets the time with the UNIX time obtained from the system clock.

This is only as precise as the system clock is. You should generally make sure the sytem clock is synchronized to a time reference e.g. via ntp, preferably to a local time reference.

NOTES:

1. With MSC, this function uses the C11 standard timespec_get() function, which is portable. For older C standard, the POSIX only clock_gettime() function is used.
2. If SuperNOVAS was built with the WITHOUT_SYSTEM_CLOCK preprocessor flag (or with the WITHOUT_LIBC build configuration option), then this function will always return an error (errno set to ENOSYS). You may want to set the time explicitly with one of the other functions instead.
3. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC difference is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.5

Author
  Attila Kovacs, Kiran Shila

See also
  novas_set_unix_time()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_unix_time().

Referenced by supernovas::Time::now().

## novas_set_default_weather()

int novas_set_default_weather | ( | on_surface * | site | ) |

Sets default weather parameters based on an approximate global model to the mean annualized temperatures, based on Feulner et al.

(2013), and scaling relations with altitude (up to 12 km).

Humidity is set to 70% at sea level (which is a typical value globally), and adjusted to decrease with altitude linearly at a rate of 7.5% per km up to 8000 meters. Above that a quadratic model is assumed, peaking at 45% at 14 km – based on the measured distribution by Mendez-Astudillo et al. (2021). Finally above 20.8 km, zero humidity is assumed.

These parameters are all very approximate, but in the absence of measured data, they represent a best guess default model of sorts.

REFERENCES:

1. Feulner, G., Rahmstorf, S., Levermann, A., and Volkwardt, S. (2013), Journal of Climate 26, 7136
2. Mendez-Astudillo, J., et al. (2021), Urban Heat Island (UHI) Mitigation (pp.43-59), DOI:10.1007/978-981-33-4050-3_3

Parameters

  [in,out] | site | Site containing geodetic loation as input, and poulated with typical mean weather parameters for the output.

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

Since
  1.5

Author
  Attila Kovacs

See also
  make_itrf_site(), make_gps_site(), make_xyz_site(), make_itrf_observer(), make_gps_observer(), NOVAS_STANDARD_ATMOSPHERE

References novas_on_surface::height, novas_on_surface::humidity, novas_on_surface::latitude, novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by supernovas::Site::average_weather(), make_itrf_site(), and refract().

## 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_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 NOVAS_EQUATORIAL_PLANE, and NOVAS_TIRS.

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

int novas_set_split_time | ( | enum novas_timescale | timescale,
|  | long | ijd,
|  | double | fjd,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to the split Julian Date value, defined in the specified timescale.

The split into the integer and fractional parts can be done in any convenient way. The highest precision is reached if the fractional part is ≤ 1 day. In that case, the time may be specified to picosecond accuracy, if needed.

The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of tdb2tt() implementation, to around 10 μs.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC difference is not possible. You must set leap and dut1 appropriately explicitly.

REFERENCES:

1. IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
2. IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
3. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
4. Kaplan, G. (2005), US Naval Observatory Circular 179.
5. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
6. https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | ijd | [day] integer part of the Julian day in the specified timescale
  | fjd | [day] fractional part Julian day value in the specified timescale
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN and novas_is_auto_fetch_eop() is TRUE, then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_set_unix_time(), novas_get_split_time(), novas_timescale_for_string(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_eop::dut1, novas_eop::leap, novas_diurnal_eop_at_time(), novas_fetch_eop(), novas_is_auto_fetch_eop(), NOVAS_TCB, NOVAS_TDB, NOVAS_TIMESCALES, and tt2tdb_hp().

Referenced by supernovas::Time::Time(), novas_set_time(), novas_set_unix_time(), and supernovas::Time::shifted().

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

int novas_set_str_time | ( | enum novas_timescale | timescale,
|  | const char *restrict | str,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets astronomical time in a specific timescale using a string specification.

It is effectively just a shorthand for using novas_parse_date() followed by novas_set_time() and the error checking in-between.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC difference is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | str | The astronomical date specification, possibly including time and timezone, in a standard format. The date is assumed to be in the astronomical calendar of date, which differs from ISO 8601 timestamps for dates prior to the Gregorian calendar reform of 1582 October 15 (otherwise, the two are identical). See novas_parse_date() for more on acceptable formats.
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides). If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_time(), novas_parse_date()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_parse_date(), and novas_set_time().

Referenced by supernovas::Time::Time().

## novas_set_time()

int novas_set_time | ( | enum novas_timescale | timescale,
|  | double | jd,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to the fractional Julian Date value, defined in the specified timescale.

The time set this way is accurate to a few μs (microseconds) due to the inherent precision of the double-precision argument. For higher precision applications you may use novas_set_split_time() instead, which has an inherent accuracy at the picosecond level.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC difference is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | jd | [day] Julian day value in the specified timescale
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides). If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_split_time(), novas_set_unix_time(), novas_set_str_time(), novas_set_current_time(), novas_get_time(), novas_timescale_for_string(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_split_time().

Referenced by supernovas::Time::Time(), and novas_set_str_time().

## novas_set_unix_time()

int novas_set_unix_time | ( | time_t | unix_time,
|  | long | nanos,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to a UNIX time value.

UNIX time is defined as UTC seconds measured since 0 UTC, 1 Jan 1970 (the start of the UNIX era). Specifying time this way supports precisions to the nanoseconds level by construct. Specifying UNIX time in split seconds and nanoseconds is a common way CLIB handles precision time, e.g. with struct timespec and functions like clock_gettime() or the C11 timespec_get (see time.h).

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC difference is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | unix_time | [s] UNIX time (UTC) seconds
  | nanos | [ns] UTC sub-second component
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_current_time(), novas_set_time(), novas_get_unix_time(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_split_time(), and NOVAS_UTC.

Referenced by supernovas::Time::Time(), and novas_set_current_time().

## novas_sets_below()

double novas_sets_below | ( | double | el,
|  | const object *restrict | source,
|  | const novas_frame *restrict | frame,
|  | RefractionModel | ref_model )

Returns the UTC date at which a distant source appears to set below the specified elevation angle.

The calculated time will account for the (slow) motion of Solar-system bodies, and optionally for atmopsheric refraction also.

NOTES:

1. The current implementation is not suitable for calculating the nearest successive set times for near-Earth objects, at or within the geostationary orbit.
2. This function calculates the time when the center (not the limb!) of the source sets below the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

  el | [deg] Elevation angle.
  source | Observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.
  ref_model | Refraction model, or NULL to calculate unrefracted setting time.

Returns
  [day] UTC-based Julian date at which the object sets below the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour day..

Since
  1.3

Author
  Attila Kovacs

See also
  novas_rises_above(), novas_transit_time()

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

## novas_site_gcrs_posvel()

int novas_site_gcrs_posvel | ( | const novas_timespec *restrict | ts,
|  | const on_surface *restrict | site,
|  | const double *restrict | v_itrs,
|  | double | xp,
|  | double | yp,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | pos,
|  | double *restrict | vel )

Returns precise GCRS position and velocity vectors for an observer located on or near Earth's surface.

NOTES:

1. unlike the original NOVAS geo_posvel(), this implementation takes the polar offsets into account.

Parameters

  | ts | Astrometric time of oservation
  | site | ITRF / GRS80 geodetic location on Earth
  | v_itrs | [km/s] surface velocity vector in ITRS, or NULL if observing from a fixed Earth location.
  | xp | [arcsec] Earth orientation parameter, polar offset in x, e.g. from the IERS Bulletins, and including diurnal libration and ocean tides. You can use 0.0 if sub-arcsecond accuracy is not required.
  | yp | [arcsec] Earth orientation parameter, polar offset in y, e.g. from the IERS Bulletins, and including diurnal libration and ocean tides. You can use 0.0 if sub-arcsecond accuracy is not required.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | pos | GCRS position vector of observer. It may be NULL if not required.
  [out] | vel | GCRS velocity vector of observer. It may be NULL if not required.

Returns
  0 if successful, or else -1 if any of the input pointers is NULL or if both output pointers are NULL (errno will be set to EINVAL).

Author
  Attila Kovacs

Since
  1.6

See also
  geo_posvel()

References itrs_to_tod(), NOVAS_AU_PER_DAY, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_KMS, NOVAS_REDUCED_ACCURACY, NOVAS_TDB, terra(), and tod_to_gcrs().

Referenced by supernovas::GeodeticObserver::gcrs_position_at(), supernovas::GeodeticObserver::gcrs_velocity_at(), and novas_site_uvw().

## novas_site_uvw()

int novas_site_uvw | ( | const novas_timespec *restrict | ts,
|  | const on_surface *restrict | station,
|  | const double *restrict | geocentric_source,
|  | double | xp,
|  | double | yp,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | uvw )

Returns geocentric u,v,w coordinates for a ground-based interferometer station.

That is, it returns u,v,w coordinates, for a geodetic station, relative to the geocenter, for a given apparent line-of-sight on the sky, observed at the specified time. The u and v coordinates are the projections of the site in the GCRS direction of the local East and North respectively, as seen from the source, relative to the geocenter, while w is the distance (inverse delay) from the geocenter along the line of sight.

For interferometers, each station is its own specific site, and the array is usually referenced to one of the stations, or to some other reference location (a virtual site). As such, one is typically interested in uvw coordinates relative to the reference position, which can be obtained from the geocentric uvw provided by this method, via simple vector differencing.

NOTES:

1. This method supports down to nanometer precision for sites on Earth or in Low Earth Orbit (LEO), and sub-micron (<μm) precision even at the distance of the Moon. However, because its calculations are based on geocentric positions, the precision degrades with increasing distance from Earth, and may not be suitable for interferometers far from Earth. When precision is a concern, you might use the more generic novas_uvw() instead, with positions (and velocities) of the stations defined relative to the array center – enabling higher precision projections than this function.

Parameters

  | ts | Astrometric time of observation.
  | station | Interferometric station site.
  | geocentric_source | [AU] Apparent true-of-date (TOD) position of a source, as seen from the geocenter at the time of observation.
  | xp | [arcsec] IERS polar offset xp, such as obtained from the IERS bulletins or online service.
  | yp | [arcsec] IERS polar offset yp, such as obtained from the IERS bulletins or online service.
  | accuracy | NOVAS_FULL_ACCYRACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | uvw | [m] output u, v, w coordinates, relative to geocenter, the u, and v coordinates are aligned with the local East and North directions in the GCRS.

Returns
  0 if successful or else -1 if any of the pointer arguments are NULL or if the accuracy is invalid (errno will be set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_uvw()

References novas_get_time(), novas_site_gcrs_posvel(), NOVAS_TDB, novas_uvw(), and tod_to_gcrs().

## novas_sky_pos()

int novas_sky_pos | ( | const object *restrict | object,
|  | const novas_frame *restrict | frame,
|  | enum novas_reference_system | sys,
|  | sky_pos *restrict | out )

Calculates an apparent location on sky for the source.

The position takes into account the proper motion (for sidereal source), or is antedated for light-travel time (for Solar-System bodies). It also applies an appropriate aberration correction and gravitational deflection of the light.

To calculate corresponding local horizontal coordinates, you can pass the output RA/Dec coordinates to novas_app_to_hor(). Or to calculate apparent coordinates in other systems, you may pass the result to novas_transform_sy_pos() after.

And if you want geometric positions instead (not corrected for aberration or gravitational deflection), you may want to use novas_geom_posvel() instead.

The approximate 'inverse' of this function is novas_app_to_geom().

This function implements the same aberration and gravitational deflection corrections as place(), but at reduced computational cost. See place() for references. Unlike place(), however, the output always reports the distance calculated from the parallax for sidereal sources. Note also, that while place() does not apply aberration and gravitational deflection corrections when sys is NOVAS_ICRS (3), this routine will apply those corrections consistently for all coordinate systems (and you can use novas_geom_posvel() instead to get positions without aberration or deflection in any system).

NOTES:

1. As of SuperNOVAS v1.3, the returned radial velocity component is a proper observer-based spectroscopic measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with LSR-based measures being returned for catalog sources.

Parameters

  | object | Pointer to a celestial object data structure that is observed. Catalog sources should have coordinates and properties in ICRS. You can use transform_cat() to convert catalog entries to ICRS as necessary.
  | frame | The observer frame, defining the location and time of observation.
  | sys | The coordinate system in which to return the apparent sky location.
  [out] | out | Pointer to the data structure which is populated with the calculated apparent location in the designated coordinate system.

Returns
  0 if successful, 50–70 error is 50 + error from light_time2(), 70–80 error is 70 + error from grav_def(), or else -1 (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_geom_to_app(), novas_app_to_hor(), novas_make_frame()

References grav_planets(), NOVAS_CATALOG_OBJECT, NOVAS_FULL_ACCURACY, novas_geom_posvel(), novas_geom_to_app(), NOVAS_ICRS, NOVAS_REDUCED_ACCURACY, novas_vlen(), and rad_vel2().

Referenced by supernovas::Source::apparent_in(), novas_equ_track(), novas_hor_track(), and novas_object_sep().

## novas_solar_illum()

double novas_solar_illum | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame )

Returns the Solar illumination fraction of a source, assuming a spherical geometry for the observed body.

Parameters

  source | Observed source. Usually a Solar-system source. (For other source types, 1.0 is returned by default.)
  frame | Observing frame, defining the observer location and astronomical time of observation.

Returns
  Solar illumination fraction [0.0:1.0] of a spherical body observed at the source location from the given observer location, or NAN if there was an error (errno will indicate the type of error).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_solar_power()

References NOVAS_CATALOG_OBJECT, novas_geom_posvel(), NOVAS_ICRS, and novas_vlen().

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

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

## novas_ssb_to_lsr_vel()

double novas_ssb_to_lsr_vel | ( | double | epoch,
|  | double | ra,
|  | double | dec,
|  | double | v_SSB )

Returns a radial-velocity referenced to the Local Standard of Rest (LSR) for a given Solar-System Barycentric (SSB) radial velocity.

Internally, NOVAS always uses barycentric radial velocities, but it is just as common to have catalogs define radial velocities referenced to the LSR.

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

REFERENCES:

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

Parameters

  epoch | [yr] Coordinate epoch in which the coordinates and velocities are defined. E.g. 2000.0.
  ra | [h] Right-ascenscion of source at given epoch.
  dec | [deg] Declination of source at given epoch.
  v_SSB | [km/s] radial velocity defined against the Solar System Barycenter (SSB), at given epoch.

Returns
  [km/s] Equivalent radial velocity defined against the Local Standard of Rest (LSR).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_lsr_to_ssb_vel(), make_cat_entry()
  novas_str_hours(), novas_str_degrees()

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

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

## novas_str_degrees()

double novas_str_degrees | ( | const char *restrict | str | ) |

Returns an angle parsed from a string that contains either a decimal degrees or else a broken-down DMS representation.

See novas_parse_degrees() to see what string representations may be used.

To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace and punctuation characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  str | The input string that specified an angle either as decimal degrees or as a broken down DMS speficication. The decimal value may be immediately followed by a letter 'd'. See more in novas_parse_degrees() on acceptable input specifications.

Returns
  [deg] The angle represented by the string, or else NAN if the string could not be parsed into an angle value (errno will indicate the type of error).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_degrees(), novas_parse_dms(), novas_print_dms(), novas_str_hours()

References novas_parse_degrees().

Referenced by supernovas::Angle::Angle().

## novas_str_hours()

double novas_str_hours | ( | const char *restrict | str | ) |

Returns a time or time-like angleparsed from a string that contains either a decimal hours or else a broken-down HMS representation.

See novas_parse_hours() to see what string representations may be used.

To check if the string was fully parsed when returning a valid (non-NAN) value you can check errno: it should be zero (0) if all non-whitespace and punctuation characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  str | The input string that specified an angle either as decimal hours or as a broken down HMS speficication. The decimal value may be immediately followed by a letter 'h'. See more in novas_parse_hours() on acceptable input specifications.

Returns
  [h] The time-like value represented by the string, or else NAN if the string could not be parsed into a time-like value (errno will indicate the type of error).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_hours(), novas_parse_hms(), novas_print_hms(), novas_str_degrees()

References novas_parse_hours().

Referenced by supernovas::TimeAngle::TimeAngle().

## novas_sun_angle()

double novas_sun_angle | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame )

Returns the apparent angular distance of a source from the Sun from the observer's point of view.

Parameters

  source | An observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.

Returns
  [deg] the apparent angular distance between the source and the Sun, from the observer's point of view.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_moon_angle()

References novas_object_sep(), and NOVAS_SUN_INIT.

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

## novas_sys_to_icrs()

int novas_sys_to_icrs | ( | enum novas_reference_system | sys,
|  | const double * | in,
|  | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | double * | out )

Converts a rectangular equatorial vector from the specified equatorial coordinate reference system of choice to the International Coordinate Reference System (ICRS) or equivalent, such as GCRS.

Note, that this function does not support conversion from an Earth rotating system, such as TIRS or ITRS.

Parameters

  sys | Input coordinate system. It cannot be NOVAS_TIRS or NOVAS_ITRS, or else the function will return an error (-1 / ENOSYS).
  in | Input vector in system (double[3]).
  jd_tdb | Barycentric Dynamical Time (TDB) based Julian Date. (Unused if input system is ICRS / GCRS or J2000). TT-based Julian Dates may be used also without loss of precision.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).
  out | Output ICRS / GCRS vector (double[3]) to be populated. It may be the same vector as the input.

Returns
  0 if successful or else -1 if any of the vectors is NULL or (errno set to EINVAL), or the coordinate system is unsupported (errno set to ENOSYS) or out of range (errno set to ERANGE).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_icrs_to_sys()

References cirs_to_gcrs(), j2000_to_gcrs(), mod_to_gcrs(), NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_TIRS, NOVAS_TOD, and tod_to_gcrs().

Referenced by supernovas::Equatorial::to_system().

## novas_time_gst()

double novas_time_gst | ( | const novas_timespec *restrict | time,
|  | enum novas_accuracy | accuracy )

Returns the Greenwich (apparent) Sidereal Time (GST/GaST) for a given astronomical time specification.

If you need mean sidereal time (GMST), you should use sidereal_time() instead.

Parameters

  time | The astronomical time specification.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).

Returns
  [h] The Greenwich apparent Sidereal Time (GST / GaST) in the [0:24) hour range, or else NAN if there was an error (errno will indicate the type of error).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_time_lst(), novas_set_time()

References novas_gast(), novas_get_time(), and NOVAS_UT1.

Referenced by supernovas::Time::gst(), and novas_time_lst().

## novas_time_leap()

int novas_time_leap | ( | const novas_timespec * | time | ) |

Returns the leap seconds component of an astronomical time specification.

Parameters

  time | The astronomical time specification.

Returns
  [s] The leap seconds that was used to initialize the time specification, or -1 if the input pointer is NULL (errno is set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

References novas_timespec::dut1, and novas_timespec::ut1_to_tt.

Referenced by supernovas::Frame::eop(), and supernovas::Time::leap_seconds().

## novas_time_lst()

double novas_time_lst | ( | const novas_timespec *restrict | time,
|  | double | lon,
|  | enum novas_accuracy | accuracy )

Returns the Local (apparent) Sidereal Time (LST/LaST) for a given astronomical time specification and observer location.

Parameters

  time | The astronomical time specification.
  lon | [deg] The geodetic longitude of the observer.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).

Returns
  [h] The Local apparent Sidereal Time (LST / LaST) in the [0:24) hour range, or else NAN if there was an error (errno will indicate the type of error).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_frame_lst(), novas_set_time()

References novas_time_gst().

Referenced by supernovas::Time::lst().

## novas_timescale_offset()

double novas_timescale_offset | ( | const novas_timespec * | ts,
|  | enum novas_timescale | timescale,
|  | enum novas_timescale | ref_scale )

Returns the time difference between two different timescales at a specific astrometric time instance.

Parameters

  ts | astrometric time
  timescale | a timescale
  ref_scale | the reference timescale

Returns
  [s] the time difference between the time expressed in the first timescale vs that in the reference timescale, or else NAN if either timescale parameter is invalid.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_clock_skew()

References NOVAS_TIMESCALES.

Referenced by supernovas::Time::timescale_offset().

## novas_timestamp()

int novas_timestamp | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | scale,
|  | char *restrict | dst,
|  | int | maxlen )

Prints an astronomical timestamp to millisecond precision in the specified timescale to the specified string buffer.

It differs from ISO 8601 timestamps for dates prior to the Gregorian calendar reform of 1582 October 15 (otherwise two are identical). E.g.:

2025-01-26T21:32:49.701 TAI

NOTES:

1. The timestamp uses the astronomical date. That is Gregorian dates after the Gregorian calendar reform of 15 October 1582, and Julian/Roman dates prior to that. This is in contrast to ISO 8601 timestamps, which use Gregorian dates even for dates the precede the calendar reform that introduced them.
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  | scale | The timescale to use.
  [out] | dst | Output string buffer. At least 28 bytes are required for a complete timestamp with termination.
  | maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen, then it will be truncated to fit in the allotted space, including a termination character.

Returns
  the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_iso_timestamp(), novas_parse_date()

References NOVAS_ASTRONOMICAL_CALENDAR, novas_get_split_time(), and novas_print_timescale().

Referenced by supernovas::Time::to_string().

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

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

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

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

## novas_track_pos()

int novas_track_pos | ( | const novas_track * | track,
|  | const novas_timespec * | time,
|  | double *restrict | lon,
|  | double *restrict | lat,
|  | double *restrict | dist,
|  | double *restrict | z )

Calculates a projected position, distance, and redshift for a source, given its near-term trajectory on sky, in the system for which the track was calculated.

Thus if the input track was obtained with novas_hor_track() it will calculate momentary azimuth and elevation (Az/El) for the specified proximate time. And, if you used novas_equ_track() then it will give you theinstantaneous R.A. and declination for that time.

Using the quadratic trajectories via a novas_track to project positions can be much faster than the repeated full recalculation of the source position, but still quite accurate over a suffciently brief period.

In SuperNOVAS terminology a 'track' is a 2nd order Taylor series expansion of the observed position and redshift in time. For most but the fastest moving sources, horizontal (Az/El) tracks are sufficiently precise for telescope positioning on minute timescales, whereas depending on the type of source, equatorial tracks can be precise for up to days, especially for sidereal (non-Solar-system) sources.

Parameters

  | track | Tracking position and motion (first and second derivatives), obtained e.g. in horizontal (Az/El) coordinates with novas_hor_track() or in equatorial coordinates with novas_equ_track().
  | time | Astrometric time of observation for which to calculate projected positions, around the time for which the track was obtained.
  [out] | lon | [deg] projected observed Eastward longitude in the tracking coordinate system. Thus, if the track was calculated with novas_hor_track() it will return the projected azimuth coordinate for the given time. And, if you used novas_equ_track(), then this will be R.A. (in degrees, nevertheless).
  [out] | lat | [deg] projected observed latitude in the tracking coordinate system. Thus, if the track was calculated with novas_hor_track() it will return the projected elevation angle for the given time. And, if you used novas_equ_track(), then this will be declination.
  [out] | dist | [AU] projected apparent distance to source from observer.
  [out] | z | projected observed redshift (z = Δλ / λrest, e.g. for spectroscopy).

Returns
  0 if successful, or else -1 if either input pointer is NULL (errno is set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_equ_track(), novas_hor_track()
  novas_z2v()

References novas_track::accel, novas_observable::dist, novas_observable::lat, novas_observable::lon, novas_diff_time(), novas_track::pos, novas_track::rate, novas_track::time, and novas_observable::z.

## novas_transform_sky_pos()

int novas_transform_sky_pos | ( | const sky_pos * | in,
|  | const novas_transform *restrict | transform,
|  | sky_pos * | out )

Transforms a position or velocity 3-vector from one coordinate reference system to another.

Parameters

  | in | Input apparent position on sky in the original coordinate reference system
  | transform | Pointer to a coordinate transformation matrix
  [out] | out | Output apparent position on sky in the new coordinate reference system. It may be the same as the input.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_sky_pos(), novas_make_transform(), novas_transform_vector()

References novas_sky_pos::dec, novas_sky_pos::r_hat, novas_sky_pos::ra, and vector2radec().

## novas_transform_vector()

int novas_transform_vector | ( | const double * | in,
|  | const novas_transform *restrict | transform,
|  | double * | out )

Transforms a position or velocity 3-vector from one coordinate reference system to another.

Parameters

  | in | Input 3-vector in the original coordinate reference system
  | transform | Pointer to a coordinate transformation matrix
  [out] | out | Output 3-vector in the new coordinate reference system. It may be the same as the input.

Returns
  0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_make_transform(), novas_transform_sky_pos()

Referenced by novas_moon_elp_posvel_fp(), novas_moon_elp_sky_pos_fp(), and supernovas::Geometric::to_system().

## novas_transit_time()

double novas_transit_time | ( | const object *restrict | source,
|  | const novas_frame *restrict | frame )

Returns the UTC date at which a source transits the local meridian.

The calculated time will account for the (slow) motion of Solar-system bodies.

NOTES:

1. The current implementation is not suitable for calculating the nearest successive transit times for near-Earth objects, at or within the geostationary orbit.

Parameters

  source | Observed source
  frame | Observing frame, defining the observer location and astronomical time of observation.

Returns
  [day] UTC-based Julian date at which the object transits the local meridian next after the specified date, or NAN if either input pointer is NULL.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_rises_above(), novas_sets_below()

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

## novas_uvw()

int novas_uvw | ( | const double *restrict | station_pos,
|  | const double *restrict | station_vel,
|  | const double *restrict | phase_center,
|  | double *restrict | uvw )

Returns u,v,w coordinates for a space-based interferometer station.

That is, it returns the u,v,w coordinates of this astrometric place (of a station), measured relative to a reference point (array reference), for a given apparent line-of-sight on the sky (source) at the same time as when the station location is defined. The u and v coordinates are the projections of the site in the direction of the local East and North respectively, as seen from the source, relative to the array reference, while w is the distance (inverse delay) from the array reference along the line of sight.

For space-based interferometers, this astrometric place can represent the momentary position of a station, relative to the array reference. As such, the returned uvw coordinates are relative to the array reference.

Parameters

  | station_pos | [AU] 3D position vector of interferometric station, relative to the array reference. It can be defined in any system, as long as the phase center is defined in the same coordinate reference system.
  | station_vel | [AU/day] 3D position vector of interferometric station, relative to the array reference, in the same coordinate reference system as the position. It may be NULL for a station that is not moving relative to the array reference.
  | phase_center | [AU] Apparent position vector of the interferometric phase center (observed source), as seen from the reference location at the time of observation, in the same coordinate reference system, in which the station vectors are defined.
  [out] | uvw | [m] output u, v, w coordinates, relative to reference place. The u, and v coordinates are aligned with the local East and North directions in the system, in which the coordinates were specified.

Returns
  0 if successful or else -1 if the station position or phase center is NULL (errno will be set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

See also
  novas_site_uvw()

References aberration(), NOVAS_AU, novas_xyz_to_los(), and vector2radec().

Referenced by novas_site_uvw(), supernovas::AstrometricPosition::to_interferometric(), and supernovas::Observer::to_interferometric().

## novas_uvw_to_xyz()

int novas_uvw_to_xyz | ( | const double * | uvw,
|  | double | ha,
|  | double | dec,
|  | double * | xyz )

Converts equatorial u,v,w projected (absolute or relative) coordinates to rectangular telescope x,y,z coordinates (in PEF) to for a specified line of sight.

u,v,w are Cartesian coordinates, with (u,v) along the local East (R.A.) and North (declination) directions as seen from a direction on the sky (w). As such, they are effectively line-of-sight (LOS) coordinates.

x,y,z are Cartesian coordinates w.r.t the Greenwich meridian in the rotating Pseudo Earth Frame (PEF). The directions are x: long=0, lat=0; y: long=90, lat=0; z: lat=90. To convert thse to ITRS, use wobble() after calling this function. Or, for arcsecond-level precision you might use PEF and ITRS positions interchangeably.

Parameters

  | uvw | [arb.u.] Absolute or relative line of sight coordinates (double[3]).
  | ha | [h] Hourangle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
  | dec | [deg] Apparent (true-of-date) declination of source.
  [out] | xyz | [arb.u.] Converted x,y,z coordinates (double[3]) in the same unit as uvw, in the Pseudo Earth Frame (PEF). It may be the same vector as the input.

Returns
  0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL)

Since
  1.3

Author
  Attila Kovacs

See also
  novas_xyz_to_uvw(), wobble()

References novas_los_to_xyz().

## novas_v2z()

double novas_v2z | ( | double | vel | ) |

Converts a radial recession velocity to a redshift value (z = Δλ / λrest).

It is based on the relativistic formula:

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

where β = vrad / c.

Parameters

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

Returns
  the corresponding redshift value (z = Δλ / λrest), or NAN if the input velocity is invalid (i.e., it exceeds the speed of light).

Author
  Attila Kovacs

Since
  1.2

See also
  novas_z2v(), novas_z_add()

References NOVAS_C, and NOVAS_KMS.

Referenced by novas_equ_track(), novas_hor_track(), supernovas::Apparent::redshift(), supernovas::CatalogEntry::redshift(), supernovas::ScalarVelocity::redshift(), redshift_vrad(), and unredshift_vrad().

## novas_xyz_to_los()

int novas_xyz_to_los | ( | const double * | xyz,
|  | double | lon,
|  | double | lat,
|  | double * | los )

Converts a 3D rectangular equatorial (δx, δy, δz) vector to a polar (δφ, δθ, δr) vector along a line-of-sight.

Parameters

  | xyz | [arb.u.] Rectangular equatorial 3-vector (δx, δy, δz).
  | lon | [deg] Line-of-sight longitude.
  | lat | [deg] Line-of-sight latitude.
  [out] | los | [arb.u.] Output line-of-sight 3-vector (δφ, δθ, δr), in the same units as the input. It may be the same vector as the input.

Returns
  0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_los_to_xyz(), novas_xyz_to_uvw()

Referenced by novas_uvw(), novas_xyz_to_uvw(), and transform_cat().

## novas_xyz_to_uvw()

int novas_xyz_to_uvw | ( | const double * | xyz,
|  | double | ha,
|  | double | dec,
|  | double * | uvw )

Converts rectangular telescope x,y,z (absolute or relative) coordinates (in PEF) to an equatorial u,v,w projection for a specified line of sight.

x,y,z are Cartesian coordinates w.r.t the Greenwich meridian, in the PEF frame. The directions are x: long=0, lat=0; y: long=90, lat=0; z: lat=90. To calculate PEF from ITRS, use wobble() first, before calling this function. Or, for arcsecond-level precision you might use PEF and ITRS positions interchangeably.

u,v,w are Cartesian coordinates, with (u,v) along the local East (R.A.) and North (declination) directions as seen from a direction on the sky (w). As such, they are effectively ITRS-based line-of-sight (LOS) coordinates.

Alternatively, use novas_site_uvw() instead to convert a geodetic (ITRS) site location more directly to a u, v, w projection.

Parameters

  | xyz | [arb.u.] Absolute or relative x,y,z coordinates (double[3]) in the Pseudo Earth Frame (PEF).
  | ha | [h] Hourangle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source, from the input location.
  | dec | [deg] Apparent (true-of-date) declination of source at the input location
  [out] | uvw | [arb.u.] Converted u,v,w coordinates (double[3]), in same units as the input xyz. It may be the same vector as the input.

Returns
  0 if successful, or else -1 if either vector argument is NULL (errno will be set to EINVAL)

Since
  1.3

Author
  Attila Kovacs

See also
  novas_site_uvw(), novas_uvw_to_xyz(), wobble()

References novas_xyz_to_los().

## novas_z2v()

double novas_z2v | ( | double | z | ) |

Converts a redshift value (z = Δλ / λrest) to a radial velocity (i.e.

rate) of recession. It is based on the relativistic formula:

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

where β = vrad / c.

Parameters

  z | the redshift value (z = Δλ / λrest).

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

Author
  Attila Kovacs

Since
  1.2

See also
  novas_v2z(), redshift_vrad()

References NOVAS_C, and NOVAS_KMS.

Referenced by supernovas::ScalarVelocity::from_redshift(), novas_set_redshift(), rad_vel2(), supernovas::Track< CoordType >::radial_velocity_at(), redshift_vrad(), and unredshift_vrad().

## novas_z_add()

double novas_z_add | ( | double | z1,
|  | double | z2 )

Compounds two redshift corrections, e.g.

to apply (or undo) a series gravitational redshift corrections and/or corrections for a moving observer. It's effectively using

(1 + z) = (1 + z1) * (1 + z2).

Parameters

  z1 | One of the redshift values
  z2 | The other redshift value

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

Since
  1.2

Author
  Attila Kovacs

See also
  grav_redshift(), redshift_vrad(), unredshift_vrad()

## novas_z_inv()

double novas_z_inv | ( | double | z | ) |

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

Parameters

  z | A redhift value

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

Since
  1.2

Author
  Attila Kovacs

See also
  novas_z_add()

## nu2000k()

int nu2000k | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double *restrict | dpsi,
|  | double *restrict | deps )

Deprecated
  This intermediate precision non-standard, NOVAS specific, nutation model is outdated. It has not been fully adjusted for the R06 update, except for a coarse rescaling. You probably should prefer using the faster and more standard iau2000b() instead for reduced precision nutation, or else the somewhat slower iau2000a() series if full precision at the μas level is preferred.

Computes the forced nutation of the non-rigid Earth: Model NU2000K. This model is a modified version of the original IAU 2000A, which has been truncated for speed of execution. NU2000K agrees with IAU 2000A at the 0.1 milliarcsecond level from 1700 to 2300, while being about 5x faster than the more precise iau2000a().

NU2000K was compared to IAU 2000A over six centuries (1700-2300). The average error in dψ is 20 microarcseconds, with 98% of the errors < 60 microarcseconds; the average error in dεis 8 microarcseconds, with 100% of the errors < 60 microarcseconds.

NU2000K was developed by G. Kaplan (USNO) in March 2004

NOTES:

1. As of SuperNOVAS v1.4.2, this function has been modified to include a rescaling of the original IAU2000 nutation compatible values to 'IAU2006' (i.e. IAU2000A R06) compatible values, according to Coppola, Seago, and Vallado (2009). The rescaling makes this model more dynamically consistent with the IAU2006 (P03) precession model of Capitaine et al. (2003).

REFERENCES:

1. IERS Conventions (2003), Chapter 5.
2. Simon et al. (1994) Astronomy and Astrophysics 282, 663-683, esp. Sections 3.4-3.5.
3. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.
4. Coppola, V., Seago, G.H., & Vallado, D.A. (2009), AAS 09-159

Parameters

  | jd_tt_high | [day] High-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the integer part of a split date for the highest precision, or the full date for normal (reduced) precision.
  | jd_tt_low | [day] Low-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the fractional part of a split date for the highest precision, or 0.0 for normal (reduced) precision.
  [out] | dpsi | [rad] δψ Nutation (luni-solar + planetary) in longitude, It may be NULL if not required.
  [out] | deps | [rad] δε Nutation (luni-solar + planetary) in obliquity. It may be NULL if not required.

Returns
  0

See also
  iau2000a(), iau2000b(), nutation_angles(), set_nutation_lp_provider(), nutation()

References accum_prec(), novas_delaunay_args::D, novas_delaunay_args::F, fund_args(), novas_delaunay_args::l, novas_delaunay_args::l1, NOVAS_EARTH, NOVAS_JUPITER, NOVAS_MARS, NOVAS_SATURN, NOVAS_VENUS, novas_delaunay_args::Omega, and planet_lon().

## nutation()

int nutation | ( | double | jd_tdb,
|  | enum novas_nutation_direction | direction,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Nutates equatorial rectangular coordinates from mean equator and equinox of epoch to true equator and equinox of epoch.

Inverse transformation may be applied by setting flag 'direction'.

This is the old (pre IAU 2006) method of nutation calculation. If you follow the now standard IAU 2000 / 2006 methodology you will want to use nutation_angles() instead.

REFERENCES:

1. Explanatory Supplement To The Astronomical Almanac, pp. 114-115.

Parameters

  | jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date
  | direction | NUTATE_MEAN_TO_TRUE (0) or NUTATE_TRUE_TO_MEAN (-1; or non-zero)
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean equator and equinox of epoch.
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to true equator and equinox of epoch. It can be the same as the input position.

Returns
  0 if successful, or -1 if one of the vector arguments is NULL.

See also
  nutation_angles()
  tt2tdb(), novas_get_time(), NOVAS_MOD, NOVAS_TOD

References e_tilt(), and NUTATE_MEAN_TO_TRUE.

Referenced by j2000_to_tod(), and tod_to_j2000().

## nutation_angles()

int nutation_angles | ( | double | t,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | dpsi,
|  | double *restrict | deps )

Returns the IAU2000 / 2006 values for nutation in longitude and nutation in obliquity for a given TDB Julian date and the desired level of accuracy.

For NOVAS_FULL_ACCURACY (0), the IAU 2000A R06 nutation model is used. Otherwise, the model set by set_nutation_lp_provider() is used, or else the iau2000b() by default.

REFERENCES:

1. Kaplan, G. (2005), US Naval Observatory Circular 179.
2. Capitaine, N., P.T. Wallace and J. Chapront (2005), “Improvement of the IAU 2000 precession model.” Astronomy & Astrophysics, Vol. 432, pp. 355–67.
3. Coppola, V., Seago, G.H., & Vallado, D.A. (2009), AAS 09-159

Parameters

  | t | [cy] TDB time in Julian centuries since J2000.0
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | dpsi | [arcsec] Nutation in longitude in arcseconds.
  [out] | deps | [arcsec] Nutation in obliquity in arcseconds.

Returns
  0 if successful, or -1 if the output pointer arguments are NULL

See also
  nutation(), set_nutation_lp_provider()
  iau2000a(), iau2000b(), nu2000k()
  NOVAS_JD_J2000

References get_nutation_lp_provider(), iau2000a(), NOVAS_FULL_ACCURACY, and NOVAS_JD_J2000.

Referenced by e_tilt(), and novas_make_frame().

## obs_planets()

int obs_planets | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double *restrict | pos_obs,
|  | int | pl_mask,
|  | novas_planet_bundle *restrict | planets )

Calculates the positions and velocities for the Solar-system bodies, e.g.

for use for gravitational deflection calculations. The planet positions are calculated relative to the observer location, while velocities are w.r.t. the SSB. Both positions and velocities are antedated for light travel time, so they accurately reflect the apparent position (and barycentric motion) of the bodies from the observer's perspective.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated.
  | pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes.
  | pl_mask | Bitwise (1 << planet-number) mask indicating which planets to request data for. See enum novas_planet for the enumeration of planet numbers.
  [out] | planets | Pointer to apparent planet data to populate. The planets with non-zero mask bits will have have positions and velocities calculated. See enum novas_planet for the enumeration of planet numbers.

Returns
  0 if successful, -1 if any of the pointer arguments is NULL or if the output vector is the same as pos_obs, or the error from ephemeris().

See also
  enum novas_planet, grav_planets(), grav_undo_planets(), set_planet_provider(), set_planet_provider_hp()

Since
  1.1

Author
  Attila Kovacs

References light_time2(), make_planet(), novas_debug(), NOVAS_DEBUG_EXTRA, NOVAS_DEBUG_OFF, novas_get_debug_mode(), NOVAS_PLANETS, and NOVAS_SUN.

Referenced by grav_def(), grav_undef(), novas_change_observer(), and place().

## obs_posvel()

int obs_posvel | ( | double | jd_tdb,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | const observer *restrict | obs,
|  | const double *restrict | geo_pos,
|  | const double *restrict | geo_vel,
|  | double *restrict | pos,
|  | double *restrict | vel )

Calculates the ICRS position and velocity of the observer relative to the Solar System Barycenter (SSB).

NOTES:

1. This implementation does not take polar wobble corrections into account for Earth-based (ITRS) observing locations. For those, it provides position vectors at the tens of meters level only.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | ut1_to_tt | [s] TT - UT1 time difference. Used only when 'location->where' is NOVAS_OBSERVER_ON_EARTH (1) or NOVAS_OBSERVER_IN_EARTH_ORBIT (2), or NOVAS_AIRBORNE_OBSERVER (3).
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | obs | The observer location, relative to which the output positions and velocities are to be calculated
  | geo_pos | [AU] ICRS position vector of the geocenter w.r.t. the Solar System Barycenter (SSB). If either geo_pos or geo_vel is NULL, it will be calculated when needed.
  | geo_vel | [AU/day] ICRS velocity vector of the geocenter w.r.t. the Solar System Barycenter (SSB). If either geo_pos or geo_vel is NULL, it will be calculated when needed.
  [out] | pos | [AU] Position 3-vector of the observer w.r.t. the Solar System Barycenter (SSB). It may be NULL if not required.
  [out] | vel | [AU/day] Velocity 3-vector of the observer w.r.t. the Solar System Barycenter (SSB). It must be distinct from the pos output vector, and may be NULL if not required.

Returns
  0 if successful, or the error from geo_posvel(), or else -1 (with errno indicating the type of error).

Author
  Attila Kovacs

Since
  1.3

See also
  novas_make_frame()

References ephemeris(), geo_posvel(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_OBSERVER_PLACES, NOVAS_SOLAR_SYSTEM_OBSERVER, and tt2tdb().

Referenced by place().

## place()

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

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

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

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

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

NOTES:

1. This version fixes a NOVAS C 3.1 issue that velocities and solar-system distances were not antedated for light-travel time.
2. In a departure from the original NOVAS C, the radial velocity for major planets (and Sun and Moon) includes gravitational redshift corrections for light originating at the surface, assuming it's observed from near Earth or else from a large distance away.
3. As of SuperNOVAS v1.3, the returned radial velocity component is a proper observer-based spectroscopic measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with pseudo LSR-based measures being returned for catalog sources.

REFERENCES:

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

Parameters

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

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

See also
  place_star(), place_icrs(), place_gcrs(), place_cirs(), radec_star(), radec_planet()
  novas_sky_pos(), novas_geom_posvel(), get_ut1_to_tt()

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

Referenced by place_cirs(), place_gcrs(), place_icrs(), place_j2000(), place_mod(), place_star(), place_tod(), and radec_planet().

## place_cirs()

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

reference_system: CIRS
observer location: geocenter
position_type: apparent

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

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  place_tod(), place_gcrs()
  novas_sky_pos(), NOVAS_CIRS, make_observer_at_geocenter()

References NOVAS_CIRS, and place().

## place_gcrs()

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

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

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  place_icrs(), place_cirs(), place_tod(), virtual_star(), virtual_planet()
  novas_sky_pos(), NOVAS_GCRS, make_observer_at_geocenter(),

References NOVAS_GCRS, and place().

## place_icrs()

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

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

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  place_gcrs(), place_cirs(), place_tod(), mean_star()
  novas_geom_posvel(), NOVAS_GCRS, make_observer_at_geocenter()

References NOVAS_ICRS, and place().

## place_j2000()

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

reference_system: J2000
observer location: geocenter
position_type: apparent

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

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

Parameters

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

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

Since
  1.1

Author
  Attila Kovacs

See also
  place_cirs(), place_gcrs(), app_star(), app_planet()
  novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_J2000, and place().

## place_mod()

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

reference_system: MOD
observer location: geocenter
position_type: apparent

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

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

Parameters

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

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

Since
  1.1

Author
  Attila Kovacs

See also
  place_cirs(), place_gcrs(), app_star(), app_planet()
  novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_MOD, and place().

## place_star()

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

Computes the apparent place of a star at the specified date, given its catalog mean place, proper motion, parallax, and radial velocity.

See place() for more information.

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

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

REFERENCES:

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

Parameters

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

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

Author
  Attila Kovacs

Since
  1.0

See also
  novas_sky_pos(), novas_geom_posvel(), get_ut1_to_tt()

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

Referenced by radec_star().

## place_tod()

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

reference_system: TOD
observer location: geocenter
position_type: apparent

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

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  place_cirs(), place_gcrs(), app_star(), app_planet()
  novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_TOD, and place().

## planet_ephem_provider()

short planet_ephem_provider | ( | double | jd_tdb,
|  | enum novas_planet | body,
|  | enum novas_origin | origin,
|  | double *restrict | position,
|  | double *restrict | velocity )

Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.

This is the regular (reduced) precision version, but in reality it's exactly the same as the high-precision version, except for the way the TDB-based Julian date is specified.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date.
  | body | Major planet number (or that for Sun, Moon, SSB...)
  | origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities.
  [out] | position | [AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
  [out] | velocity | [AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns
  0 if successful, or else an error code defined by novas_planet_provider.

Since
  1.0

Author
  Attila Kovacs

See also
  planet_ephem_provider_hp(), set_ephem_provider()

References planet_ephem_provider_hp().

## planet_ephem_provider_hp()

short planet_ephem_provider_hp | ( | const double | jd_tdb[restrict 2],
|  | enum novas_planet | body,
|  | enum novas_origin | origin,
|  | double *restrict | position,
|  | double *restrict | velocity )

Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.

This is the highest precision version.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date, split into high and low order components (e.g. integer and fractional parts) for high-precision calculations.
  | body | Major planet number (or that for Sun, Moon, SSB...)
  | origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities.
  [out] | position | [AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS.
  [out] | velocity | [AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day.

Returns
  0 if successful, or else an error code of solarsystem_hp().

Since
  1.0

Author
  Attila Kovacs

See also
  planet_ephem_provider(), set_ephem_provider()
  solarsystem_hp()

References get_ephem_provider(), NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, NOVAS_SSB, and NOVAS_SUN.

Referenced by planet_ephem_provider().

## planet_lon()

double planet_lon | ( | double | t,
|  | enum novas_planet | planet )

Returns the planetary longitude, for Mercury through Neptune, w.r.t.

mean dynamical ecliptic and equinox of J2000, with high order terms omitted (Simon et al. 1994, 5.8.1-5.8.8).

REFERENCES:

1. IERS Conventions Chapter 5, Eq. 5.44.

Parameters

  t | [cy] Julian centuries since J2000
  planet | Novas planet id, e.g. NOVAS_MARS.

Returns
  [rad] The approximate longitude of the planet in radians [-π:π], or NAN if the planet id is out of range.

See also
  accum_prec(), nutation_angles(), NOVAS_JD_J2000

Since
  1.0

Author
  Attila Kovacs

References NOVAS_NEPTUNE, and TWOPI.

Referenced by novas_moon_elp_ecl_pos(), and nu2000k().

## precession()

short precession | ( | double | jd_tdb_in,
|  | const double * | in,
|  | double | jd_tdb_out,
|  | double * | out )

Precesses equatorial rectangular coordinates from one epoch to another using the IAU2006 (P03) precession model of Capitaine et al.

2003.

NOTES:

1. Unlike the original NOVAS C 3.1 version, this one does not require that one of the time arguments must be J2000. You can precess from any date to any other date, and the intermediate epoch of J2000 will be handled internally as needed.
2. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.

REFERENCES:

1. Explanatory Supplement To The Astronomical Almanac, pp. 103-104.
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.
3. Hilton, J. L. et al. (2006), IAU WG report, Celest. Mech., 94, pp. 351-367.
4. Capitaine, N., P.T. Wallace and J. Chapront (2005), “Improvement of the IAU 2000 precession model.” Astronomy & Astrophysics, Vol. 432, pp. 355–67. 5.Liu, J.-C., & Capitaine, N. (2017), A&A 597, A83.

Parameters

  | jd_tdb_in | [day] Barycentric Dynamic Time (TDB) based Julian date of the input epoch
  | in | Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean dynamical equator and equinox of the initial epoch.
  | jd_tdb_out | [day] Barycentric Dynamic Time (TDB) based Julian date of the output epoch
  [out] | out | Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean dynamical equator and equinox of the final epoch. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the position vectors is NULL.

See also
  nutation()
  tt2tdb(), novas_get_time(), frame_tie(), novas_epoch(), NOVAS_MOD, NOVAS_JD_J2000, NOVAS_JD_B1950, NOVAS_JD_B1900

References precession().

Referenced by earth_sun_calc(), gcrs_to_mod(), j2000_to_tod(), mean_star(), mod_to_gcrs(), novas_lsr_to_ssb_vel(), novas_ssb_to_lsr_vel(), precession(), tod_to_j2000(), and transform_cat().

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

## rad_vel()

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

Predicts the radial velocity of the observed object as it would be measured by spectroscopic means.

Radial velocity is defined here as a spectroscopic measure, defined by the relation:

λobs / λrest = (1 + z) = sqrt((1 + β) / (1 - β)),

where β = vrad / c.

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

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

The input velocities are barycentric, expressed with respect to the ICRS axes. vel_src and vel_obs are kinematic velocities - derived from geometry or dynamics, not spectroscopy.

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

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

NOTES:

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

REFERENCES:

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

Parameters

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

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

See also
  rad_vel2()

References rad_vel2().

## rad_vel2()

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

Predicts the radial velocity of the observed object as it would be measured by spectroscopic means.

This is a modified version of the original NOVAS C 3.1 rad_vel(), to account for the slightly different directions in which light is emitted vs in which it is detected, e.g. when it is gravitationally deflected.

Radial velocity is defined here as a spectroscopic measure, defined by the relation:

λobs / λrest = (1 + z) = sqrt((1 + β) / (1 - β)),

where β = vrad / c.

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

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

The input velocities are barycentric, expressed with respect to the ICRS axes. vel_src and vel_obs are kinematic velocities - derived from geometry or dynamics, not spectroscopy.

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

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

NOTES:

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

REFERENCES:

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

Parameters

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

Returns
  [km/s] The spectroscopic radial velocity measure from the observer's point of view, or NAN if there was an error (errno will be set to EINVAL if any of the arguments are NULL, or to some other value to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  rad_vel()
  novas_sky_pos(), novas_v2z()

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

Referenced by novas_approx_sky_pos(), novas_sky_pos(), place(), and rad_vel().

## radec2vector()

int radec2vector | ( | double | ra,
|  | double | dec,
|  | double | dist,
|  | double *restrict | pos )

Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).

Parameters

  | ra | [h] Right ascension (hours).
  | dec | [deg] Declination (degrees).
  | dist | [AU] Distance (AU)
  [out] | pos | [AU] Position 3-vector, equatorial rectangular coordinates (AU).

Returns
  0 if successful, or -1 if the vector argument is NULL.

See also
  vector2radec(), starvectors()

Referenced by earth_sun_calc(), gcrs2equ(), novas_app_to_geom(), novas_app_to_hor(), novas_lsr_to_ssb_vel(), novas_ssb_to_lsr_vel(), starvectors(), supernovas::Horizontal::to_apparent(), supernovas::Equatorial::to_system(), and transform_cat().

## radec_planet()

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

Computes the place of a solar system body at the specified time for an observer in the specified coordinate system.

This is the same as calling place() with the same arguments, except the different set of return values used.

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

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

REFERENCES:

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  radec_star()
  novas_sky_pos(), novas_geom_posvel()

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

Referenced by app_planet(), astro_planet(), local_planet(), topo_planet(), and virtual_planet().

## radec_star()

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

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

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

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

REFERENCES:

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

Parameters

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

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

Since
  1.0

Author
  Attila Kovacs

See also
  radec_planet()
  novas_sky_pos(), novas_geom_posvel()

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

Referenced by app_star(), astro_star(), local_star(), topo_star(), and virtual_star().

## redshift_vrad()

double redshift_vrad | ( | double | vrad,
|  | double | z )

Applies an incremental redshift correction to a radial velocity.

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

Parameters

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

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

Since
  1.2

Author
  Attila Kovacs

See also
  unredshift_vrad(), grav_redshift(), novas_z_add()

References novas_v2z(), and novas_z2v().

## refract()

double refract | ( | const on_surface *restrict | location,
|  | enum novas_refraction_model | model,
|  | double | zd_obs )

Computes atmospheric optical refraction for an observed (already refracted!) zenith distance through the atmosphere.

In other words this is suitable to convert refracted zenith angles to astrometric (unrefracted) zenith angles. For the reverse, see refract_astro().

The returned value is the approximate refraction for optical wavelengths. This function can be used for planning observations or telescope pointing, but should not be used for precise positioning.

NOTES:

1. The standard temeperature model includes a very rough estimate of the mean annual temperature for the ovserver's latitude and elevation, rather than the 10 C everywhere assumption in NOVAS C 3.1.

REFERENCES:

1. Explanatory Supplement to the Astronomical Almanac, p. 144.
2. Bennett, G. (1982), Journal of Navigation (Royal Institute) 35, pp. 255-259.

Parameters

  location | Pointer to structure containing observer's location. It may also contains weather data (optional) for the observer's location. Some, but not all, refraction models will use location-based (e.g. weather) information. For models that do not need it, it may be NULL.
  model | The built in refraction model to use. E.g. NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2)...
  zd_obs | [deg] Observed (already refracted!) zenith distance through the atmosphere.

Returns
  [deg] the calculated optical refraction or 0.0 if the location is NULL or the option is invalid or the 'zd_obs' is invalid (<90°).

See also
  refract_astro(), hor_to_itrs()

References NOVAS_NO_ATMOSPHERE, NOVAS_RADIO_REFRACTION, novas_radio_refraction(), NOVAS_REFRACT_OBSERVED, NOVAS_REFRACTION_MODELS, novas_set_default_weather(), NOVAS_WAVE_REFRACTION, novas_wave_refraction(), NOVAS_WEATHER_AT_LOCATION, novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by refract_astro().

## refract_astro()

double refract_astro | ( | const on_surface *restrict | location,
|  | enum novas_refraction_model | model,
|  | double | zd_astro )

Computes atmospheric optical refraction for a source at an astrometric zenith distance (e.g.

calculated without accounting for an atmosphere). This is suitable for converting astrometric (unrefracted) zenith angles to observed (refracted) zenith angles. See refract() for the reverse correction.

The returned value is the approximate refraction for optical wavelengths. This function can be used for planning observations or telescope pointing, but should not be used for precise positioning.

REFERENCES:

1. Explanatory Supplement to the Astronomical Almanac, p. 144.
2. Bennett, G. (1982), Journal of Navigation (Royal Institute) 35, pp. 255-259.

Parameters

  location | Pointer to structure containing observer's location. It may also contains weather data (optional) for the observer's location. Some, but not all, refraction models will use location-based (e.g. weather) information. For models that do not need it, it may be NULL.
  model | The built in refraction model to use. E.g. NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2)...
  zd_astro | [deg] Astrometric (unrefracted) zenith distance angle of the source.

Returns
  [deg] the calculated optical refraction. (to ~0.1 arcsec accuracy), or 0.0 if the location is NULL or the option is invalid.

See also
  refract(), itrs_to_hor()

Since
  1.0

Author
  Attila Kovacs

References novas_inv_max_iter, NOVAS_RADIO_REFRACTION, novas_radio_refraction(), NOVAS_REFRACT_ASTROMETRIC, and refract().

Referenced by equ2hor().

## spin()

int spin | ( | double | angle,
|  | const double * | in,
|  | double * | out )

Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.

REFERENCES:

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

Parameters

  | angle | [deg] Angle of coordinate system rotation, positive counterclockwise when viewed from +z, in degrees.
  | in | Input position vector.
  [out] | out | Position vector expressed in new coordinate system rotated about z by 'angle'. It can be the same vector as the input.

Returns
  0 if successful, or -1 if the output vector is NULL.

References TWOPI.

Referenced by cel2ter(), cirs_to_tod(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), place(), ter2cel(), and tod_to_cirs().

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

## tdb2tt()

int tdb2tt | ( | double | jd_tdb,
|  | double *restrict | jd_tt,
|  | double *restrict | secdiff )

Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (TDB) Julian date, and returns the TDB-TT time difference also.

It has a maximum error of 10 μs between 1600 and 2200.

This function is wrapped by tt2tdb(), which is typically a lot easier to use as it returns the time difference directly, which can then be used to convert time in both directions with greater ease. For example, to convert a TT-based date to a TDB-based date:

double TDB = TT + tt2tdb(TT) / 86400.0;
tt2tdb
double tt2tdb(double jd_tt)
Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 1...
Definition timescale.c:167

is equivalent to:

double dt;
tdb2tt(TT, NULL, &dt); // Uses TT input so don't attempt to calculate TT here...
double TDB = TT + dt / 86400.0;
tdb2tt
int tdb2tt(double jd_tdb, double *restrict jd_tt, double *restrict secdiff)
Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (T...
Definition timescale.c:125

NOTES:

1. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.

REFERENCES:

1. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
2. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  | jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date.
  [out] | jd_tt | [day] Terrestrial Time (TT) based Julian date. (It may be NULL if not required)
  [out] | secdiff | [s] Difference 'tdb_jd'-'tt_jd', in seconds. (It may be NULL if not required)

Returns
  0

See also
  tt2tdb()

References NOVAS_JD_J2000.

Referenced by tt2tdb().

## terra()

int terra | ( | const on_surface *restrict | location,
|  | double | gast,
|  | double *restrict | pos,
|  | double *restrict | vel )

Deprecated
  This NOVAS C function does not account for polar wobble, so the geodetic ITRS / GRS80 locations on Earth are not converted into a proper equatorial system, such as a true-of-date (TOD) coordinate system. Use novas_site_gcrs_posvel() instead, which you can follow by a coordinate transformation, such as tod_to_gcrs() if you need geocentric observer coordinates in e.g. the true-of-date (TOD) equatorial system.

Computes the position and velocity vectors of a terrestrial observer with respect to the center of the Earth, based on the GRS80 reference ellipsoid, used for the International Terrestrial Reference Frame (ITRF) and its realizations.

This function ignores polar motion, unless the observer's longitude and latitude have been corrected for it, and variation in the length of day (angular velocity of earth).

The true equator and equinox of date do not form an inertial system. Therefore, with respect to an inertial system, the very small velocity component (several meters/day) due to the precession and nutation of the Earth's axis is not accounted for here.

REFERENCES:

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

Parameters

  | location | ITRF / GRS80 geodetic location of observer in Earth's rotating frame.
  | gast | [h] Greenwich apparent sidereal time (GAST). If set to 0, it returns positions and velocities w.r.t. the ITRS.
  [out] | pos | [AU] Position vector of observer with respect to center of Earth, equatorial rectangular coordinates, referred to true equator and equinox of date, components in AU. If reference meridian is Greenwich and 'lst' = 0, 'pos' is effectively referred to equator and Greenwich. (It may be NULL if no position data is required).
  [out] | vel | [AU/day] Velocity vector of observer with respect to center of Earth, equatorial rectangular coordinates, referred to true equator and equinox of date, components in AU/day. (It must be distinct from the pos output vector, and may be NULL if no velocity data is required).

Returns
  0 if successful, or -1 if location is NULL or if the pos and vel output arguments are identical pointers.

See also
  novas_site_gcrs_posvel(), geo_posvel()
  make_gps_site(), make_itrf_site(), make_xyz_site(), novas_gast(), novas_time_gst()

References NOVAS_KM.

Referenced by geo_posvel(), and novas_site_gcrs_posvel().

## tod_to_cirs()

int tod_to_cirs | ( | double | jd_tt,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from the True of Date (TOD) reference system to the Celestial Intermediate Reference System (CIRS) at the given epoch to the .

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | CIRS Input (x, y, z) position or velocity vector
  [out] | out | Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or 10 + the error from cio_ra(), or else 20 + the error from cio_basis().

Since
  1.1

Author
  Attila Kovacs

See also
  cirs_to_tod(), app_to_cirs_ra(), tod_to_gcrs(), tod_to_j2000(), tod_to_itrs()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and spin().

Referenced by gcrs_to_cirs().

## tod_to_gcrs()

int tod_to_gcrs | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the ICRS / GCRS.

(We treat ICRS and GCRS the same, since they only define the orientation of the equator, and not the origin. The origin is defined by the observer location separately.)

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
  [out] | out | Output ICRS / GCRS position or velocity vector. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL.

Since
  1.2

Author
  Attila Kovacs

See also
  j2000_to_tod(), tod_to_cirs(), tod_to_j2000(), tod_to_itrs(), novas_sys_to_icrs()

References frame_tie(), J2000_TO_ICRS, and tod_to_j2000().

Referenced by cio_basis(), cirs_to_gcrs(), geo_posvel(), novas_site_gcrs_posvel(), novas_site_uvw(), novas_sys_to_icrs(), and ter2cel().

## tod_to_itrs()

int tod_to_itrs | ( | double | jd_tt_high,
|  | double | jd_tt_low,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Rotates a position vector from the dynamical True of Date (TOD) frame of date the Earth-fixed ITRS frame (pre IAU 2000 method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

  | jd_tt_high | [day] High-order part of Terrestrial Time (TT) based Julian date.
  | jd_tt_low | [day] Low-order part of Terrestrial Time (TT) based Julian date.
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | xp | [arcsec] Conventionally-defined X coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | yp | [arcsec] Conventionally-defined Y coordinate of celestial intermediate pole with respect to ITRS pole, in arcseconds.
  | in | Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system).
  [out] | out | Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

Returns
  0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

Since
  1.0

Author
  Attila Kovacs

See also
  cirs_to_itrs(), itrs_to_tod(), j2000_to_tod(), tod_to_gcrs(), tod_to_j2000(), tod_to_cirs()

References cel2ter().

## tod_to_j2000()

int tod_to_j2000 | ( | double | jd_tdb,
|  | enum novas_accuracy | accuracy,
|  | const double * | in,
|  | double * | out )

Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the J2000 coordinates.

Parameters

  | jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  | in | Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
  [out] | out | Output position or velocity vector in rectangular equatorial coordinates at J2000. It can be the same vector as the input.

Returns
  0 if successful, or -1 if either of the vector arguments is NULL or the 'accuracy' is invalid.

Since
  1.0

Author
  Attila Kovacs

See also
  j2000_to_tod(), j2000_to_gcrs(), tod_to_gcrs(), tod_to_cirs(), tod_to_itrs()

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_TRUE_TO_MEAN, nutation(), and precession().

Referenced by tod_to_gcrs().

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

## tt2tdb()

double tt2tdb | ( | double | jd_tt | ) |

Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 10 μs for dates between 1600 and 2200.

REFERENCES

1. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
2. Kaplan, G. (2005), US Naval Observatory Circular 179.
3. Moyer, T.D. (1981), Celestial mechanics, Volume 23, Issue 1, pp. 57-68

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date, but Barycentric Dynamical Time (TDB) can also be used here without any loss of precision on the result.

Returns
  [s] TDB - TT time difference.

Since
  1.0

Author
  Attila Kovacs

See also
  tt2tdb_hp(), tt2tdb_fp(), tdb2tt()

References tdb2tt().

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

## tt2tdb_hp()

double tt2tdb_hp | ( | double | jd_tt | ) |

Returns the TDB-TT time difference with high precision.

This implementation uses the full series expansion by Fairhead & Bretagnon 1990, resulting in an accuracy below 100 ns.

NOTES:

1. This function caches the result of the last calculation.

REFERENCES:

1. Fairhead, L., & Bretagnon, P. (1990) A&A, 229, 240

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date, but Barycentric Dynamical Time (TDB)

Returns
  [s] TDB - TT time difference.

Since
  1.4

Author
  Attila Kovacs

See also
  tt2tdb_fp(), tt2tdb()

References tt2tdb_fp().

Referenced by novas_set_split_time().

## unredshift_vrad()

double unredshift_vrad | ( | double | vrad,
|  | double | z )

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

Parameters

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

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

Since
  1.2

Author
  Attila Kovacs

See also
  redshift_vrad(), grav_redshift()

References novas_v2z(), and novas_z2v().

## vector2radec()

short vector2radec | ( | const double *restrict | pos,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.

REFERENCES:

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

Parameters

  | pos | Position 3-vector, equatorial rectangular coordinates.
  [out] | ra | [h] Right ascension in hours [0:24] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.
  [out] | dec | [deg] Declination in degrees [-90:90] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.

Returns
  0 if successful, -1 of any of the arguments are NULL, or 1 if all input components are 0 so 'ra' and 'dec' are indeterminate, or else 2 if both x and y are zero, but z is nonzero, and so 'ra' is indeterminate.

See also
  radec2vector()

Referenced by gcrs2equ(), mean_star(), novas_geom_to_app(), novas_hor_to_app(), novas_moon_elp_sky_pos_fp(), novas_moon_phase(), novas_transform_sky_pos(), novas_uvw(), place(), supernovas::AstrometricPosition::to_equatorial(), supernovas::Apparent::to_horizontal(), and supernovas::Equatorial::to_system().

## virtual_planet()

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

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_gcrs(), app_planet(), astro_planet(), local_planet(), topo_planet(), app_star()
  novas_sky_pos(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_GCRS, and radec_planet().

## virtual_star()

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

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

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

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

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

REFERENCES:

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

Parameters

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

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

See also
  place_star(), place_gcrs(), app_star(), astro_star(), local_star(), topo_star(), virtual_planet()
  novas_sky_pos(), make_observer_at_geocenter(), NOVAS_GCRS

References NOVAS_GCRS, and radec_star().

## wobble()

int wobble | ( | double | jd_tt,
|  | enum novas_wobble_direction | direction,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Corrects a vector in the ITRS (rotating Earth-fixed system) for polar motion, and also corrects the longitude origin (by a tiny amount) to the Terrestrial Intermediate Origin (TIO).

The ITRS vector is thereby transformed to the Terrestrial Intermediate Reference System (TIRS), or equivalently the Pseudo Earth Fixed (PEF), based on the true (rotational) equator and TIO; or vice versa. Because the true equator is the plane orthogonal to the direction of the Celestial Intermediate Pole (CIP), the components of the output vector are referred to z and x axes toward the CIP and TIO, respectively.

NOTES:

1. You may obtain Earth orientation parameters from the IERS site and Bulletins. For sub-mas accuracy you should augment the (interpolated) published values for diurnal and semi-diurnal librations and the effect of ocean tides, e.g. by using novas_diurnal_eop() or novas_diurnal_eop_at_time().
2. Generally, this function should not be called if global pole offsets were set via cel_pole() and then used via place() or one of its variants to calculate Earth orientation corrected (TOD or CIRS) apparent coordinates. In such cases, calling wobble() would apply duplicate corrections. It is generally best to forgo using cel_pole() going forward, and instead apply Earth orinetation corrections with wobble() only when converting vectors between the Earth-fixed ITRS and TIRS frames.
3. The Earth orientation parameters xp, yp should be provided in the same ITRF realization as the observer location for an Earth-based observer. You can use novas_itrf_transform_eop() to convert the EOP values as necessary.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Lambert & Bizouard (2002), Astronomy and Astrophysics 394, 317-321.
3. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
4. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date.
  | direction | WOBBLE_ITRS_TO_TIRS (0) or WOBBLE_TIRS_TO_ITRS (1) to include corrections for the TIO's longitude (IAU 2006 method); or else WOBBLE_ITRS_TO_PEF (2) or WOBBLE_PEF_TO_ITRS (3) to correct for dx, dy but not for the TIO's longitude (old, pre IAU 2006 method). Negative values default to WOBBLE_TIRS_TO_ITRS.
  | xp | [arcsec] Conventionally-defined X coordinate of Celestial Intermediate Pole with respect to ITRS pole. As measured or else the interpolated published value from IERS, possibly augmented for diurnal variations caused by librations ocean tides if precision below the milliarcsecond level is required.
  | yp | [arcsec] Conventionally-defined Y coordinate of Celestial Intermediate Pole with respect to ITRS pole, in arcseconds. As measured or else the interpolated published value from IERS, possibly augmented for diurnal variations caused by librations ocean tides if precision below the milliarcsecond level is required.
  | in | Input position vector, geocentric equatorial rectangular coordinates, in the original system defined by 'direction'
  [out] | out | Output Position vector, geocentric equatorial rectangular coordinates, in the final system defined by 'direction'. It can be the same vector as the input.

Returns
  0 if successful, or -1 if the direction is invalid output vector argument is NULL.

See also
  novas_diurnal_eop(), novas_diurnal_eop_at_time(), novas_itrf_transform_eop()

References NOVAS_WOBBLE_DIRECTIONS, WOBBLE_ITRS_TO_PEF, WOBBLE_ITRS_TO_TIRS, and WOBBLE_TIRS_TO_ITRS.

Referenced by cel2ter(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), and ter2cel().