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_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 extpressed 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 sefault 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_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 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] WGS84 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_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_matric initializer for an indentity matrix
#define	NOVAS_MATRIX_INIT
	Empty initializer for novas_matrix.
#define	NOVAS_MERCURY_INIT
	object initializer for the planet Venus
#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_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 ICSR origins 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   (NOVAS_IERS_2003_ELLIPSOID + 1)
	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 coordiante 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 syste, as a string.
#define	NOVAS_TAI_TO_TT   32.184
	[s] TT - TAI time offset
#define	NOVAS_TIMESCALES
	The number of asronomical 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 Mercury
#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   6
	API minor version.
#define	SUPERNOVAS_PATCHLEVEL   0
	Integer sub version of the release.
#define	SUPERNOVAS_RELEASE_STRING   "-rc2"
	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π

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 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 extpressed 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_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 distinguied 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 a 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 NOVAS. 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 tranform_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 rad_vel, 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 ITRF 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.
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.
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).
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_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_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 ITRF 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_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_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().
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_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 eith 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_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 redhift 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_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.
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).
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_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 ITRS) 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 ITRS) to equatorial u,v,w projected coordinates 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)
	Computes the forced nutation of the non-rigid Earth: Model NU2000K.
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 retuns th TDB-TT time difference also.
int	terra (const on_surface *restrict location, double gast, double *restrict pos, double *restrict vel)
	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.
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 an 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.5.0

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_clock_skew(), novas_make_moon_mean_orbit(), novas_make_moon_orbit(), novas_moon_elp_ecl_pos(), novas_moon_elp_sky_pos_fp(), rad_vel2(), and starvectors().

NOVAS_AU_KM

#define NOVAS_AU_KM   ( 1e-3 * NOVAS_AU )

[km] Astronomical Unit (AU) in kilometers.

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

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

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

[m³/s²] Geocentric gravitational constant (GM_earth) from DE440, see Park et al., AJ, 161, 105 (2021)

NOVAS_G_SUN

#define NOVAS_G_SUN   1.32712440041279419e20

[m³/s²] Heliocentric gravitational constant (GM_sun) from DE440, see Park et al., AJ, 161, 105 (2021)

NOVAS_GRS80_FLATTENING

#define NOVAS_GRS80_FLATTENING   (1.0 / 298.257222101)

[m] WGS84 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_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::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_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(), supernovas::Ecliptic::system(), tdb2tt(), supernovas::Ecliptic::to_j2000(), transform_cat(), tt2tdb_fp(), and supernovas::CalendarDate::unix_time().

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(), novas_moon_elp_sky_pos_fp(), and terra().

NOVAS_KMS

#define NOVAS_KMS   (NOVAS_KM)

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

Since

1.3

Referenced by 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_matric initializer for an indentity 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 Venus

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_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 ICSR origins 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;

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;

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.
3. 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_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   (NOVAS_IERS_2003_ELLIPSOID + 1)

The total number of reference ellipsoid types known to SuperNOVAS.

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

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/m²] The Solar Constant i.e., typical incident Solar power on Earth.

The value of 1367 Wm⁻² 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 coordiante 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 syste, as a string.

Since

1.3

See also

novas_set_catalog(), make_cat_object_sys(), make_redshifted_object_sys()

NOVAS_TIMESCALES

#define NOVAS_TIMESCALES

The number of asronomical time scales supported.

Since

1.1

See also

novas_timescale

Referenced by supernovas::Interval::Interval(), supernovas::Time::jd_day(), supernovas::Time::jd_frac(), supernovas::Time::mjd(), supernovas::Time::mjd_day(), supernovas::Time::mjd_frac(), and novas_diff_time_scale().

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.

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 Mercury

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   6

API minor version.

SUPERNOVAS_PATCHLEVEL

#define SUPERNOVAS_PATCHLEVEL   0

Integer sub version of the release.

SUPERNOVAS_RELEASE_STRING

#define SUPERNOVAS_RELEASE_STRING   "-rc2"

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

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° - Dec_pole (in radians), and phi is RA_pole (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 extpressed 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_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 (pre IAU 2006 system).
NOVAS_GCRS_EQUATOR	Geocentric Celestial Reference System (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(), gsrs_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 distinguied 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 a 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 Langrange 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 baricenter (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_reference_system

enum novas_reference_system

The basic types of positional coordinate reference systems supported by NOVAS.

These determine only how the celestial pole is to be located, but not how velocities are to be referenced. specific pos-vel coordinates are referenced to an 'astro_frame', which must specify one of the values defined here.

See also

novas_frame, NOVAS_REFERENCE_SYSTEMS

novas_sky_pos(), novas_geom_posvel(), novas_geom_to_app(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), novas_make_transform()

Enumerator
NOVAS_GCRS	Geocentric Celestial Reference system. Essentially the same as ICRS but includes aberration and gravitational deflection for an observer around Earth.
NOVAS_TOD	True equinox Of Date: dynamical system of the 'true' equator, with its origin at the 'true' equinox (pre IAU 2006 system).
NOVAS_CIRS	Celestial Intermediate Reference System: dynamical system of the true equator, with its origin at the CIO (preferred since IAU 2006).
NOVAS_ICRS	International Celestial Reference system. The equatorial system fixed to the frame of distant quasars.
NOVAS_J2000	The J2000 dynamical reference system. Since 1.1
NOVAS_MOD	Mean of date: dynamical system of the 'mean' equator, with its origin at the 'mean' equinox (pre IAU 2006 system). It includes precession (Lieske et. al. 1977), but not nutation. For example, FK4 or B1950 are MOD coordinate systems. Since 1.1
NOVAS_TIRS	Terrestrial Intermediate Reference System. It is the IAU 2006 standard pseudo Earth-fixed (PEF) coordinate system, which co-rotates with Earth, but does not include Earth polar wobble corrections. Since 1.4
NOVAS_ITRS	International Terrestrial Reference System. This is the IAU 2006 Earth-fixed reference system, and includes small measured corrections for the unmodelled polar motion, as published by the IERS Bulletins. Since 1.4

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 tranform_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(), 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 wan 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 wan 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()

References cirs_to_tod(), and tod_to_gcrs().

Referenced by ter2cel(), and supernovas::Equatorial::to_system().

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

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

Returns

0 if successful, -1 if the 'jd_tdb' or input object argument is NULL, or else 1 if 'origin' is invalid, 2 if cel_obj->type is invalid, 10 + the error code from 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 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 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()

References gcrs_to_tod(), and tod_to_cirs().

Referenced by cel2ter(), gcrs2equ(), place(), and supernovas::Equatorial::to_system().

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

References frame_tie(), and ICRS_TO_J2000.

Referenced by place(), and supernovas::Equatorial::to_system().

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

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

Referenced by gcrs2equ(), place(), and supernovas::Equatorial::to_system().

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

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

Referenced by cel2ter(), gcrs2equ(), gcrs_to_cirs(), place(), and supernovas::Equatorial::to_system().

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.

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	ITRF / GRS80 geodetic 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_make_frame(), make_observer(), get_ut1_to_tt()

References ephemeris(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, novas_gast(), 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 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 <a href="https://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html>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) precesion model of Capitaine et al. 2003. This is now the same model with respect to which the IERS Earth orinetation 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().

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

References frame_tie(), and J2000_TO_ICRS.

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

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 poiinter 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 avasilable – 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	rad_vel,
		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, icluding 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.
	rad_vel	[km/s] Radial velocity relative to the Solar-System Barycenter (SSB). To convert velocities defined against the Local Standard of Rest (LSR), you may use novas_lsr_to_ssb_vel() to convert appropriately. Or, to convert from a redshift value, you might use novas_z2v().
[out]	Astronomical object of interest	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(), novas_set_ssb_vel(), and rad_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.

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]	Astronomical object of interest	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 ommitted 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]	Astronomical object of interest	Pointer to the celestial object data structure to be populated with the corresponding ICRS catalog coordinates, after appying proper-motion and precession corrections as appropriate.

Returns

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

See also

make_cat_object(), make_redshifted_object_sys(), novas_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(), 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.

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 an the 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 an the 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.

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]	Astronomical object of interest	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]	Astronomical object of interest	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(), and make_redshifted_cat_entry().

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 ommitted 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]	Astronomical object of interest	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(), 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()

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

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

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 n99 (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

	Observing frames	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_hor_to_app(), novas_geom_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

	Observing frames	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:

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

1. 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()).
2. 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.)
	Observing frames	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 successfule or else an 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 / dt_timescale = (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

Observing frames	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()

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_AU, NOVAS_C, 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_tdb(), 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_librations(), 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 of observation and astronomical timescales	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 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_librations()

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 ITRF vector.

Parameters

	enu	input East-North-Up (ENU) vector.
	lon	[deg] ITRF longitude of site.
	lat	[deg] ITRF latitude of site.
[out]	itrf	output ITRF 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_itrf_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_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()

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

	Astronomical object of interest	Observed source
	Observing frames	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_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

Observing frames

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

	Astronomical object of interest	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.
	Observing frames	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

	Observing frames	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 tbd2tt() implemenation, 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 of observation and astronomical timescales	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 is 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_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

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 of observation and astronomical timescales	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_moon_elp_posvel_fp(), 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 of observation and astronomical timescales	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 E9, novas_get_split_time(), NOVAS_UTC, and UNIX_UTC_J2000.

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.
	Astronomical object of interest	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

	Observing frames	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

	Astronomical object of interest	Observed source
	Observing frames	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_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 (parcsec) 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]	Astronomical object of interest	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 in 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(), novas_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 of observation and astronomical timescales	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, ...);

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_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_itrf_transform_eop(), novas_itrf_transform(), make_itrf_site(), make_itrf_observer()

novas_transform_ellipsoid()

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 ITRF position vector to a local East-North-Up (ENU) vector at the specified site.

Parameters

	itrf	xyz position vector in ITRF.
	lon	[deg] ITRF longitude of site.
	lat	[deg] ITRF 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_itrf()

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, ot 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_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.

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 of observation and astronomical timescales	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]	Observing frames	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()

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_FULL_ACCURACY, novas_get_split_time(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_UT1, nutation_angles(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, novas_timespec::tt2tdb, and novas_observer::where.

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:

• 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

	Observing frames	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 / dt_timescale = (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

Observing frames	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

Astronomical object of interest	An observed source
Observing frames	Observing frame, defining the observer location and astronomical time of observation.

Returns

[deg] Apparent angular distance between the source an 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:

• 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

	Observing frames	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:

• 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

	Observing frames	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:

• 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

	Observing frames	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:

• 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

	Observing frames	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_fp()

novas_moon_elp_posvel()

novas_make_moon_orbit()

novas_sky_pos()

References aberration(), NOVAS_AU, NOVAS_DAY, NOVAS_ICRS, NOVAS_KM, 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).

NOTES:

1. 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
Observing frames	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_time()

int novas_offset_time	(	const novas_timespec *	time,
		double	seconds,
		novas_timespec *	out )

Increments the astrometric time by a given amount.

Parameters

	Time of observation and astronomical timescales	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.

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 in was introduced on 15 October 1582 only. Thus the

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_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.
Astronomical object of interest	Observed source
Observing frames	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()

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]	Astronomical object of interest	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 in 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 eith 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.

NOTE:

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.

Parameters

	leap	[s] Leap seconds, e.g. as published by IERS Bulletin C.
	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.
[out]	Time of observation and astronomical timescales	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_unix_time()

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::Weather::guess(), 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]	Astronomical object of interest	Output structure to populate with the parameters.
	parsecs	[pc] distance

Returns

0 if successful, or else -1 in 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_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]	Astronomical object of interest	Output structure to populate with the parameters.
	v_kms	[km/s] Radial velocity of source w.r.t. the Local Standard of Rest (LSR).
	epoch	[yr] Coordinate epoch.

Returns

0 if successful, or else -1 in 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]	Astronomical object of interest	Output structure to populate with the parameters.
	mas	[mas] Parallax

Returns

0 if successful, or else -1 in 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]	Astronomical object of interest	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 in 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 redhift for a catalog source, as a relativistic measure of velocity.

Parameters

[out]	Astronomical object of interest	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 in 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 tbd2tt() 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

	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.
	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.
[out]	Time of observation and astronomical timescales	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()

References novas_diurnal_eop_at_time(), NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, 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]	Astronomical object of interest	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 in 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.

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.
	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.
[out]	Time of observation and astronomical timescales	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()

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.

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.
	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.
[out]	Time of observation and astronomical timescales	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()

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

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.
	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.
[out]	Time of observation and astronomical timescales	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()

References novas_set_split_time(), NOVAS_UTC, and UNIX_UTC_J2000.

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.
Astronomical object of interest	Observed source
Observing frames	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_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.
	Observing frames	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

Astronomical object of interest	Observed source. Usually a Solar-system source. (For other source types, 1.0 is returned by default.)
Observing frames	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.
Astronomical object of interest	Observed Solar-system source

Returns

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

Since

1.3

Author

Attila Kovacs

See also

novas_solar_illum()

References novas_helio_dist(), and NOVAS_SOLAR_CONSTANT.

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

novas_ssb_to_lsr_vel()

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.

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

Astronomical object of interest	An observed source
Observing frames	Observing frame, defining the observer location and astronomical time of observation.

Returns

[deg] the apparent angular distance between the source an 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_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 of observation and astronomical timescales	The astronomoical 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 of observation and astronomical timescales

The astronomoical 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 of observation and astronomical timescales	The astronomoical 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_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 of observation and astronomical timescales	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 of observation and astronomical timescales	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_skypos()

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

Astronomical object of interest	Observed source
Observing frames	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_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 β = v_rad / 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_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 β = v_rad / 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 + z₁) * (1 + z₂).

Parameters

z1	One of the redshift values
z2	The other redshift value

Returns

The compound redshift value, ot 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 )

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 is 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(), and NOVAS_FULL_ACCURACY.

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

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 he ut1_to_tt argument decide whether the resulting 'topocentric' output frame is Pseudo Earth Fixed (PEF; if cel_pole() was not set and DUT1 is 0) or ITRS (actual rotating Earth; if cel_pole() was set and ut1_to_tt includes the DUT1 component).

NOTES:

1. This version fixes a NOVAS C 3.1 issue that velocities and solar-system distances were not antedated for light-travel time.
2. In a departure from the original NOVAS C, the radial velocity for major planets (and Sun and Moon) includes gravitational redshift corrections for light originating at the surface, assuming it's observed from near Earth or else from a large distance away.
3. As of SuperNOVAS v1.3, the returned radial velocity component is a proper observer-based spectroscopic measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with pseudo LSR-based measures being returned for catalog sources.

REFERENCES:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	Astronomical object of interest	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(), gcrs_to_j2000(), gcrs_to_mod(), gcrs_to_tod(), grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, grav_planets(), light_time2(), make_observer_at_geocenter(), NOVAS_BARYCENTER, NOVAS_CATALOG_OBJECT, NOVAS_CIRS, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_TIRS, NOVAS_TOD, novas_vlen(), obs_planets(), obs_posvel(), proper_motion(), rad_vel2(), spin(), starvectors(), tt2tdb(), and vector2radec().

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.
	Astronomical object of interest	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.
	Astronomical object of interest	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.
	Astronomical object of interest	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.
	Astronomical object of interest	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.
	Astronomical object of interest	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated apparent Mean-of-Date (MOD) position data for a fictitous geocentric observer.

Returns

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

Since

1.1

Author

Attila Kovacs

See also

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

novas_sky_pos(), NOVAS_TOD, make_observer_at_geocenter()

References NOVAS_MOD, and place().

place_star()

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

Computes the apparent place of a star at the specified date, given its catalog mean place, proper motion, parallax, and radial velocity.

See place() for more information.

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

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

REFERENCES:

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

Parameters

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

Returns

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

Author

Attila Kovacs

Since

1.0

See also

novas_sky_pos(), novas_geom_posvel(), get_ut1_to_tt()

References NOVAS_CATALOG_OBJECT, place(), 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.
	Astronomical object of interest	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.

NOTE:

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 areguments 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 β = v_rad / 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 accont 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

	Astronomical object of interest	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 successfule, 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().

Referenced by make_cat_entry().

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 β = v_rad / 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

Astronomical object of interest	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	[AU/day] radial velocity relative ot observer, or NAN when returning with an error code. (It may be NULL if not required)

Returns

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

Since

1.0

Author

Attila Kovacs

See also

radec_star()

novas_sky_pos(), novas_geom_posvel()

References 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	[AU/day] radial velocity relative ot observer, or NAN when returning with an error code. (It may be NULL if not required)

Returns

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

Since

1.0

Author

Attila Kovacs

See also

radec_planet()

novas_sky_pos(), novas_geom_posvel()

References 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 temeprature for the ovserver's latitude and elevation, rather than the 10 C everywhere assumption in NOVAS C 3.1.<.li>

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, 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 retuns th TDB-TT time difference also.

It has a maximum error of 10 μs between for dates 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 exable to convert a TT-based date to a TDB-based date:

double TDB = TT + tt2tdb(TT) / 86400.0;

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;

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 )

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

geo_posvel()

make_gps_site(), make_itrf_site(), make_xyz_site(), novas_gast(), novas_time_gst()

References NOVAS_KM.

Referenced by geo_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()

References frame_tie(), J2000_TO_ICRS, and tod_to_j2000().

Referenced by cio_basis(), cirs_to_gcrs(), geo_posvel(), ter2cel(), and supernovas::Equatorial::to_system().

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

Returns

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

See also

transform_hip(), make_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<.li>

Parameters

jd_tt

[day] Terrestrial Time (TT) based Julian date, but Barycentri 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 an 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 notrequired.
[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 supernovas::AstrometricPosition::as_equatorial(), gcrs2equ(), mean_star(), novas_geom_to_app(), novas_hor_to_app(), novas_moon_elp_sky_pos_fp(), novas_moon_phase(), novas_transform_sky_pos(), place(), 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_transfor_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().