Data Structures
struct	cat_entry

struct	in_space

struct	novas_delaunay_args

struct	novas_frame

struct	novas_matrix

struct	novas_observable

struct	novas_orbital

struct	novas_orbital_system

struct	novas_planet_bundle

struct	novas_timespec

struct	novas_track

struct	novas_transform

struct	object

struct	observer

struct	on_surface

struct	ra_of_cio

struct	sky_pos

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

#define	CAT_ENTRY_INIT { {'\0'}, {'\0'}, 0L, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

#define	DE405_AU 1.4959787069098932e+11

#define	DEFAULT_CIO_LOCATOR_FILE "/usr/share/novas/cio_ra.bin"

#define	DEFAULT_GRAV_BODIES_FULL_ACCURACY ( DEFAULT_GRAV_BODIES_REDUCED_ACCURACY \| (1 << NOVAS_JUPITER) \| (1 << NOVAS_SATURN) )

#define	DEFAULT_GRAV_BODIES_REDUCED_ACCURACY ( (1 << NOVAS_SUN) )

#define	DEG2RAD (M_PI / 180.0)
	[rad/deg] 1 degree in radians

#define	HELIOC NOVAS_HELIOCENTER

#define	IN_SPACE_INIT {{0.0}, {0.0}}

#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

#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_C 299792458.0
	[m/s] Speed of light in meters/second is a defining physical constant.

#define	NOVAS_C_AU_PER_DAY ( NOVAS_DAY / AU_SEC )
	[AU/day] Speed of light in units of AU/day.

#define	NOVAS_CIO_CACHE_SIZE 1024
	[pts] cache size for GCRS CIO locator data (16 bytes per point).

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

#define	NOVAS_DEGREE (M_PI / 180.0)
	[rad] A degree expressed in radians.

#define	NOVAS_EARTH_ANGVEL 7.2921150e-5
	[rad/s] Rotational angular velocity of Earth from IERS Conventions (2003).

#define	NOVAS_EARTH_FLATTENING (1.0 / 298.25642)
	Earth ellipsoid flattening from IERS Conventions (2003). Value is 1 / 298.25642.

#define	NOVAS_EARTH_INIT NOVAS_PLANET_INIT(NOVAS_EARTH, "Earth")

#define	NOVAS_EARTH_RADIUS 6378136.6
	[m] Radius of Earth in meters from IERS Conventions (2003).

#define	NOVAS_EMB_INIT NOVAS_PLANET_INIT(NOVAS_EMB, "EMB")

#define	NOVAS_EQUATOR_TYPES (NOVAS_GCRS_EQUATOR + 1)

#define	NOVAS_G_EARTH 3.98600433e+14
	[m³/s²] Geocentric gravitational constant, from DE-405.

#define	NOVAS_G_SUN 1.32712440017987e+20
	[m³/s²] Heliocentric gravitational constant, from DE-405.

#define	NOVAS_GPS_TO_TAI 19.0
	[s] TAI - GPS time offset

#define	NOVAS_HOURANGLE (M_PI / 12.0)
	[rad] An hour of angle expressed in radians.

#define	NOVAS_JD_B1900 15019.81352
	[day] Julian date at B1900

#define	NOVAS_JD_B1950 2433282.42345905
	[day] Julian date at B1950

#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

#define	NOVAS_JUPITER_INIT NOVAS_PLANET_INIT(NOVAS_JUPITER, "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_MAJOR_VERSION 3
	Major version of NOVAS on which this library is based.

#define	NOVAS_MARS_INIT NOVAS_PLANET_INIT(NOVAS_MERCURY, "Mars")

#define	NOVAS_MERCURY_INIT NOVAS_PLANET_INIT(NOVAS_MERCURY, "Mercury")

#define	NOVAS_MINOR_VERSION 1
	Minor version of NOVAS on which this library is based.

#define	NOVAS_MOON_INIT NOVAS_PLANET_INIT(NOVAS_MOON, "Moon")

#define	NOVAS_NEPTUNE_INIT NOVAS_PLANET_INIT(NOVAS_NEPTUNE, "Neptune")

#define	NOVAS_OBJECT_TYPES (NOVAS_ORBITAL_OBJECT + 1)

#define	NOVAS_OBSERVER_PLACES (NOVAS_SOLAR_SYSTEM_OBSERVER + 1)

#define	NOVAS_ORBIT_INIT { NOVAS_ORBITAL_SYSTEM_INIT, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

#define	NOVAS_ORBITAL_SYSTEM_INIT { NOVAS_SUN, NOVAS_ECLIPTIC_PLANE, NOVAS_GCRS, 0.0, 0.0 }

#define	NOVAS_ORIGIN_TYPES (NOVAS_HELIOCENTER + 1)

#define	NOVAS_PLANET_GRAV_Z_INIT

#define	NOVAS_PLANET_INIT(num, name) { NOVAS_PLANET, num, name, CAT_ENTRY_INIT, NOVAS_ORBIT_INIT }

#define	NOVAS_PLANET_NAMES_INIT

#define	NOVAS_PLANETS (NOVAS_PLUTO_BARYCENTER + 1)

#define	NOVAS_PLUTO_BARYCENTER_INIT NOVAS_PLANET_INIT(NOVAS_PLUTO_BARYCENTER, "Pluto-Barycenter")

#define	NOVAS_PLUTO_INIT NOVAS_PLANET_INIT(NOVAS_PLUTO, "Pluto")

#define	NOVAS_REFERENCE_SYSTEMS (NOVAS_MOD + 1)

#define	NOVAS_RMASS_INIT

#define	NOVAS_SATURN_INIT NOVAS_PLANET_INIT(NOVAS_SATURN, "Saturn")

#define	NOVAS_SOLAR_CONSTANT 1367.0

#define	NOVAS_SOLAR_RADIUS 696340000.0

#define	NOVAS_SSB_INIT NOVAS_PLANET_INIT(NOVAS_SSB, "SSB")

#define	NOVAS_SUN_INIT NOVAS_PLANET_INIT(NOVAS_SUN, "Sun")

#define	NOVAS_SYSTEM_B1950 "B1950"

#define	NOVAS_SYSTEM_FK4 "FK4"

#define	NOVAS_SYSTEM_FK5 "FK5"

#define	NOVAS_SYSTEM_HIP "HIP"

#define	NOVAS_SYSTEM_ICRS "ICRS"

#define	NOVAS_SYSTEM_J2000 "J2000"

#define	NOVAS_TAI_TO_TT 32.184
	[s] TT - TAI time offset

#define	NOVAS_TIMESCALES (NOVAS_UT1 + 1)

#define	NOVAS_TRANSFORM_TYPES (ICRS_TO_J2000 + 1)

#define	NOVAS_URANUS_INIT NOVAS_PLANET_INIT(NOVAS_URANUS, "Uranus")

#define	NOVAS_VENUS_INIT NOVAS_PLANET_INIT(NOVAS_VENUS, "Venus")

#define	NOVAS_VERSION_STRING #NOVAS_MAJOR_VERSION "." NOVAS_MINOR_VERSION
	The version string of the upstream NOVAS library on which this library is based.

#define	ON_SURFACE_INIT { 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

#define	ON_SURFACE_LOC(lon, lat, alt) { lon, lat, alt, 0.0, 0.0, 0.0 }

#define	RAD2DEG (1.0 / DEG2RAD)
	[deg/rad] 1 radian in degrees

#define	SIZE_OF_CAT_NAME 6
	Maximum bytes in catalog IDs including string termination.

#define	SIZE_OF_OBJ_NAME 50
	Maximum bytes in object names including string termination.

#define	SKY_POS_INIT { {0.0}, 0.0, 0.0, 0.0, 0.0 }

#define	SUPERNOVAS_MAJOR_VERSION 1
	API major version.

#define	SUPERNOVAS_MINOR_VERSION 3
	API minor version.

#define	SUPERNOVAS_PATCHLEVEL 0
	Integer sub version of the release.

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

#define	SUPERNOVAS_VERSION_STRING

#define	TWOPI (2.0 * M_PI)
	2π

Typedefs
typedef double(*	RefractionModel) (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)

Enumerations
enum	novas_accuracy { NOVAS_FULL_ACCURACY = 0 , NOVAS_REDUCED_ACCURACY }

enum	novas_calendar_type { NOVAS_ROMAN_CALENDAR = -1 , NOVAS_ASTRONOMICAL_CALENDAR , NOVAS_GREGORIAN_CALENDAR }

enum	novas_cio_location_type { CIO_VS_GCRS = 1 , CIO_VS_EQUINOX }

enum	novas_date_format { NOVAS_YMD = 0 , NOVAS_DMY , NOVAS_MDY }

enum	novas_debug_mode { NOVAS_DEBUG_OFF = 0 , NOVAS_DEBUG_ON , NOVAS_DEBUG_EXTRA }

enum	novas_dynamical_type { NOVAS_DYNAMICAL_MOD = 0 , NOVAS_DYNAMICAL_TOD , NOVAS_DYNAMICAL_CIRS }

enum	novas_earth_rotation_measure { EROT_ERA = 0 , EROT_GST }

enum	novas_equator_type { NOVAS_MEAN_EQUATOR = 0 , NOVAS_TRUE_EQUATOR , NOVAS_GCRS_EQUATOR }

enum	novas_equatorial_class { NOVAS_REFERENCE_CLASS = 0 , NOVAS_DYNAMICAL_CLASS }

enum	novas_equinox_type { NOVAS_MEAN_EQUINOX = 0 , NOVAS_TRUE_EQUINOX }

enum	novas_frametie_direction { J2000_TO_ICRS = -1 , ICRS_TO_J2000 }

enum	novas_nutation_direction { NUTATE_TRUE_TO_MEAN = -1 , NUTATE_MEAN_TO_TRUE }

enum	novas_object_type { NOVAS_PLANET = 0 , NOVAS_EPHEM_OBJECT , NOVAS_CATALOG_OBJECT , NOVAS_ORBITAL_OBJECT }

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 }

enum	novas_origin { NOVAS_BARYCENTER = 0 , NOVAS_HELIOCENTER }

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 }

enum	novas_pole_offset_type { POLE_OFFSETS_DPSI_DEPS = 1 , POLE_OFFSETS_X_Y }

enum	novas_reference_plane { NOVAS_ECLIPTIC_PLANE = 0 , NOVAS_EQUATORIAL_PLANE }

enum	novas_reference_system { NOVAS_GCRS = 0 , NOVAS_TOD , NOVAS_CIRS , NOVAS_ICRS , NOVAS_J2000 , NOVAS_MOD }

enum	novas_refraction_model { NOVAS_NO_ATMOSPHERE = 0 , NOVAS_STANDARD_ATMOSPHERE , NOVAS_WEATHER_AT_LOCATION }

enum	novas_refraction_type { NOVAS_REFRACT_OBSERVED = -1 , NOVAS_REFRACT_ASTROMETRIC }

enum	novas_timescale { NOVAS_TCB = 0 , NOVAS_TDB , NOVAS_TCG , NOVAS_TT , NOVAS_TAI , NOVAS_GPS , NOVAS_UTC , NOVAS_UT1 }

enum	novas_transform_type { PROPER_MOTION = 1 , PRECESSION , CHANGE_EPOCH , CHANGE_J2000_TO_ICRS , CHANGE_ICRS_TO_J2000 }

enum	novas_wobble_direction { WOBBLE_ITRS_TO_PEF = 0 , WOBBLE_PEF_TO_ITRS }

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

double	accum_prec (double t)

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

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

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

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

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

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

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

short	cel2ter (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class class, double xp, double yp, const double in, double out)

short	cel_pole (double jd_tt, enum novas_pole_offset_type type, double dpole1, double dpole2)

short	cio_array (double jd_tdb, long n_pts, ra_of_cio *restrict cio)

short	cio_basis (double jd_tdb, double ra_cio, enum novas_cio_location_type loc_type, enum novas_accuracy accuracy, double restrict x, double restrict y, double *restrict z)

short	cio_location (double jd_tdb, enum novas_accuracy accuracy, double restrict ra_cio, short restrict loc_type)

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

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

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

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)

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

double	d_light (const double pos_src, const double pos_body)

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)

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)

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

double	ee_ct (double jd_tt_high, double jd_tt_low, enum novas_accuracy accuracy)

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)

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)

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

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

int	equ2hor (double jd_ut1, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const on_surface restrict location, double ra, double dec, enum novas_refraction_model ref_option, double restrict zd, double restrict az, double restrict rar, double *restrict decr)

double	era (double jd_ut1_high, double jd_ut1_low)

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

int	fund_args (double t, novas_delaunay_args *restrict a)

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

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

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

int	gcrs_to_j2000 (const double in, double out)

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

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

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

novas_nutation_provider	get_nutation_lp_provider ()

double	get_ut1_to_tt (int leap_seconds, double dut1)

double	get_utc_to_tt (int leap_seconds)

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)

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

double	grav_redshift (double M_kg, double r_m)

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

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

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

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

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

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)

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

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)

int	j2000_to_gcrs (const double in, double out)

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

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

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)

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)

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

short	local_planet (double jd_tt, const object restrict ss_body, double ut1_to_tt, const on_surface restrict position, enum novas_accuracy accuracy, double restrict ra, double restrict dec, double *restrict dis)

short	local_star (double jd_tt, double ut1_to_tt, const cat_entry restrict star, const on_surface restrict position, enum novas_accuracy accuracy, double restrict ra, double restrict dec)

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

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

int	make_cat_object (const cat_entry star, object source)

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

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

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

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

short	make_observer (enum novas_observer_place, const on_surface loc_surface, const in_space loc_space, observer *obs)

int	make_observer_at_geocenter (observer *restrict obs)

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

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

int	make_on_surface (double latitude, double longitude, double height, double temperature, double pressure, on_surface *restrict loc)

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

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

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

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

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

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

double	mean_obliq (double jd_tdb)

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

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

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)

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)

void	novas_case_sensitive (int value)

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

double	novas_date (const char *restrict date)

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

void	novas_debug (enum novas_debug_mode mode)
	==========================================================================

double	novas_diff_tcb (const novas_timespec t1, const novas_timespec t2)

double	novas_diff_tcg (const novas_timespec t1, const novas_timespec t2)

double	novas_diff_time (const novas_timespec t1, const novas_timespec t2)

double	novas_dms_degrees (const char *restrict dms)

int	novas_e2h_offset (double dra, double ddec, double pa, double restrict daz, double restrict del)

double	novas_epa (double ha, double dec, double lat)

double	novas_epoch (const char *restrict system)

double	novas_equ_sep (double ra1, double dec1, double ra2, double dec2)

int	novas_equ_track (const object restrict source, const novas_frame restrict frame, double dt, novas_track *restrict track)

double	novas_frame_lst (const novas_frame *restrict frame)

int	novas_geom_posvel (const object restrict source, const novas_frame restrict frame, enum novas_reference_system sys, double restrict pos, double restrict vel)

int	novas_geom_to_app (const novas_frame restrict frame, const double restrict pos, enum novas_reference_system sys, sky_pos *restrict out)

enum novas_debug_mode	novas_get_debug_mode ()

double	novas_get_split_time (const novas_timespec restrict time, enum novas_timescale timescale, long restrict ijd)

double	novas_get_time (const novas_timespec *restrict time, enum novas_timescale timescale)

time_t	novas_get_unix_time (const novas_timespec restrict time, long restrict nanos)

int	novas_h2e_offset (double daz, double del, double pa, double restrict dra, double restrict ddec)

double	novas_hms_hours (const char *restrict hms)

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)

int	novas_hor_track (const object restrict source, const novas_frame restrict frame, RefractionModel ref_model, novas_track *restrict track)

double	novas_hpa (double az, double el, double lat)

double	novas_inv_refract (RefractionModel model, double jd_tt, const on_surface *restrict loc, enum novas_refraction_type type, double el0)

int	novas_invert_transform (const novas_transform transform, novas_transform inverse)

int	novas_iso_timestamp (const novas_timespec restrict time, char restrict dst, int maxlen)

double	novas_jd_from_date (enum novas_calendar_type calendar, int year, int month, int day, double hour)

int	novas_jd_to_date (double tjd, enum novas_calendar_type calendar, int restrict year, int restrict month, int restrict day, double restrict hour)

int	novas_los_to_xyz (const double los, double lon, double lat, double xyz)

double	novas_lsr_to_ssb_vel (double epoch, double ra, double dec, double vLSR)

int	novas_make_frame (enum novas_accuracy accuracy, const observer obs, const novas_timespec time, double dx, double dy, novas_frame *frame)

int	novas_make_transform (const novas_frame frame, enum novas_reference_system from_system, enum novas_reference_system to_system, novas_transform transform)

double	novas_moon_angle (const object restrict source, const novas_frame restrict frame)

double	novas_norm_ang (double angle)

double	novas_object_sep (const object source1, const object source2, const novas_frame *restrict frame)

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

double	novas_optical_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)

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

double	novas_parse_date (const char restrict date, char *restrict tail)

double	novas_parse_date_format (enum novas_calendar_type calendar, enum novas_date_format format, const char restrict date, char *restrict tail)

double	novas_parse_degrees (const char restrict str, char *restrict tail)

double	novas_parse_dms (const char restrict str, char *restrict tail)

double	novas_parse_hms (const char restrict str, char *restrict tail)

double	novas_parse_hours (const char restrict str, char *restrict tail)

enum novas_timescale	novas_parse_timescale (const char restrict str, char *restrict tail)

enum novas_planet	novas_planet_for_name (const char *restrict name)

int	novas_print_timescale (enum novas_timescale scale, char *restrict buf)

double	novas_radio_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)

double	novas_rises_above (double el, const object restrict source, const novas_frame restrict frame, RefractionModel ref_model)

double	novas_sep (double lon1, double lat1, double lon2, double lat2)

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

int	novas_set_split_time (enum novas_timescale timescale, long ijd, double fjd, int leap, double dut1, novas_timespec *restrict time)

int	novas_set_time (enum novas_timescale timescale, double jd, int leap, double dut1, novas_timespec *restrict time)

int	novas_set_unix_time (time_t unix_time, long nanos, int leap, double dut1, novas_timespec *restrict time)

double	novas_sets_below (double el, const object restrict source, const novas_frame restrict frame, RefractionModel ref_model)

int	novas_sky_pos (const object restrict object, const novas_frame restrict frame, enum novas_reference_system sys, sky_pos *restrict out)

double	novas_ssb_to_lsr_vel (double epoch, double ra, double dec, double vLSR)

double	novas_standard_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)

double	novas_str_degrees (const char *restrict dms)

double	novas_str_hours (const char *restrict hms)

double	novas_sun_angle (const object restrict source, const novas_frame restrict frame)

enum novas_timescale	novas_timescale_for_string (const char *restrict str)

int	novas_timestamp (const novas_timespec restrict time, enum novas_timescale scale, char restrict dst, int maxlen)

int	novas_track_pos (const novas_track track, const novas_timespec time, double restrict lon, double restrict lat, double restrict dist, double restrict z)

int	novas_transform_sky_pos (const sky_pos in, const novas_transform restrict transform, sky_pos *out)

int	novas_transform_vector (const double in, const novas_transform restrict transform, double *out)

double	novas_transit_time (const object restrict source, const novas_frame restrict frame)

double	novas_v2z (double vel)

int	novas_xyz_to_los (const double xyz, double lon, double lat, double los)

int	novas_xyz_to_uvw (const double xyz, double ha, double dec, double uvw)

double	novas_z2v (double z)
	==========================================================================

double	novas_z_add (double z1, double z2)

double	novas_z_inv (double z)

int	nutation (double jd_tdb, enum novas_nutation_direction direction, enum novas_accuracy accuracy, const double in, double out)

int	nutation_angles (double t, enum novas_accuracy accuracy, double restrict dpsi, double restrict deps)

int	obs_planets (double jd_tdb, enum novas_accuracy accuracy, const double restrict pos_obs, int pl_mask, novas_planet_bundle restrict planets)

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)

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)

int	place_cirs (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

int	place_gcrs (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

int	place_icrs (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

int	place_j2000 (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

int	place_mod (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

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)

int	place_tod (double jd_tt, const object restrict source, enum novas_accuracy accuracy, sky_pos restrict pos)

double	planet_lon (double t, enum novas_planet planet)

short	precession (double jd_tdb_in, const double in, double jd_tdb_out, double out)

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

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)

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)

int	radec2vector (double ra, double dec, double dist, double *restrict pos)

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)

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)

double	redshift_vrad (double vrad, double z)

double	refract (const on_surface *restrict location, enum novas_refraction_model option, double zd_obs)

double	refract_astro (const on_surface *restrict location, enum novas_refraction_model option, double zd_astro)

int	set_cio_locator_file (const char *restrict filename)

int	set_nutation_lp_provider (novas_nutation_provider func)

short	sidereal_time (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_equinox_type gst_type, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, double *restrict gst)

int	spin (double angle, const double in, double out)

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

int	tdb2tt (double jd_tdb, double restrict jd_tt, double restrict secdiff)

short	ter2cel (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class class, double xp, double yp, const double in, double out)

int	terra (const on_surface restrict location, double lst, double restrict pos, double *restrict vel)
	==========================================================================

int	tod_to_cirs (double jd_tt, enum novas_accuracy accuracy, const double in, double out)

int	tod_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double in, double out)

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)

int	tod_to_j2000 (double jd_tdb, enum novas_accuracy accuracy, const double in, double out)

short	topo_planet (double jd_tt, const object restrict ss_body, double ut1_to_tt, const on_surface restrict position, enum novas_accuracy accuracy, double restrict ra, double restrict dec, double *restrict dis)

short	topo_star (double jd_tt, double ut1_to_tt, const cat_entry restrict star, const on_surface restrict position, enum novas_accuracy accuracy, double restrict ra, double restrict dec)

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)

int	transform_hip (const cat_entry hipparcos, cat_entry hip_2000)

double	tt2tdb (double jd_tt)

double	unredshift_vrad (double vrad, double z)

short	vector2radec (const double restrict pos, double restrict ra, double *restrict dec)

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

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

int	wobble (double jd_tt, enum novas_wobble_direction direction, double xp, double yp, const double in, double out)

Variables
int	grav_bodies_full_accuracy

int	grav_bodies_reduced_accuracy

Detailed Description

Author: G. Kaplan and A. Kovacs

Version: 1.3.0

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

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

Macro Definition Documentation

◆ BARYC

#define BARYC NOVAS_BARYCENTER

Deprecated:: Old definition of the Barycenter origin. NOVAS_BARYCENTER is preferred.

◆ CAT_ENTRY_INIT

#define CAT_ENTRY_INIT { {'\0'}, {'\0'}, 0L, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

Initializer for a NOVAS cat_entry structure.

See also: cat_entry

Author: Attila Kovacs

Since: 1.1.1

◆ DE405_AU

#define DE405_AU 1.4959787069098932e+11

[m] Astronomical unit (AU). based on DE-405. (old definition)

See also: NOVAS_AU

◆ DEFAULT_CIO_LOCATOR_FILE

#define DEFAULT_CIO_LOCATOR_FILE "/usr/share/novas/cio_ra.bin"

Path / name of file to use for interpolating the CIO location relative to GCRS This file can be generated with the cio_file.c tool using the CIO_RA.TXT data (both are included in the distribution)

◆ DEFAULT_GRAV_BODIES_FULL_ACCURACY

#define DEFAULT_GRAV_BODIES_FULL_ACCURACY ( DEFAULT_GRAV_BODIES_REDUCED_ACCURACY | (1 << NOVAS_JUPITER) | (1 << NOVAS_SATURN) )

Default set of gravitating bodies to use for deflection calculations in full accuracy mode.

See also: grav_bodies_full_accuracy

Since: 1.1

Author: Attila Kovacs

◆ DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

#define DEFAULT_GRAV_BODIES_REDUCED_ACCURACY ( (1 << NOVAS_SUN) )

Default set of gravitating bodies to use for deflection calculations in reduced accuracy mode. (only apply gravitational deflection for the Sun.)

See also: grav_bodies_reduced_accuracy

Since: 1.1

Author: Attila Kovacs

◆ HELIOC

#define HELIOC NOVAS_HELIOCENTER

Deprecated:: Old definition of the Center of Sun as the origin. NOVAS_HELIOCENTER is preferred.

◆ IN_SPACE_INIT

#define IN_SPACE_INIT {{0.0}, {0.0}}

Initializer for a NOVAS in_space structure.

See also: in_space

Since: 1.1.1

◆ 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

◆ NOVAS_AU

#define NOVAS_AU 1.495978707e+11

[m] Astronomical unit (AU). IAU definition. See IAU 2012 Resolution B2.

See also: DE405_AU

◆ NOVAS_DAY

#define NOVAS_DAY 86400.0

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

Since: 1.2

◆ NOVAS_DEGREE

#define NOVAS_DEGREE (M_PI / 180.0)

[rad] A degree expressed in radians.

Since: 1.2

◆ NOVAS_EARTH_INIT

#define NOVAS_EARTH_INIT NOVAS_PLANET_INIT(NOVAS_EARTH, "Earth")

object initializer for the planet Earth

Since: 1.2

See also: object

◆ NOVAS_EMB_INIT

#define NOVAS_EMB_INIT NOVAS_PLANET_INIT(NOVAS_EMB, "EMB")

object initializer for the the Earth-Moon Barycenter (EMB)

Since: 1.2

See also: object

◆ NOVAS_EQUATOR_TYPES

#define NOVAS_EQUATOR_TYPES (NOVAS_GCRS_EQUATOR + 1)

The number of equator types defined in enum novas_equator_type.

See also: enum novas_equator_type

Author: Attila Kovacs

Since: 1.2

◆ NOVAS_HOURANGLE

#define NOVAS_HOURANGLE (M_PI / 12.0)

[rad] An hour of angle expressed in radians.

Since: 1.2

◆ NOVAS_JD_START_GREGORIAN

#define NOVAS_JD_START_GREGORIAN 2299160.5

[day] The Julian day the Gregorian calendar was introduced in 15 October 1582. The day prior to that was 4 October 1582 in the Julian Calendar.

◆ NOVAS_JUPITER_INIT

#define NOVAS_JUPITER_INIT NOVAS_PLANET_INIT(NOVAS_JUPITER, "Jupiter")

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

◆ NOVAS_KMS

#define NOVAS_KMS (NOVAS_KM)

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

Since: 1.3

◆ NOVAS_MARS_INIT

#define NOVAS_MARS_INIT NOVAS_PLANET_INIT(NOVAS_MERCURY, "Mars")

object initializer for the planet Mars

Since: 1.2

See also: object

◆ NOVAS_MERCURY_INIT

#define NOVAS_MERCURY_INIT NOVAS_PLANET_INIT(NOVAS_MERCURY, "Mercury")

object initializer for the planet Venus

Since: 1.2

See also: object

◆ NOVAS_MOON_INIT

#define NOVAS_MOON_INIT NOVAS_PLANET_INIT(NOVAS_MOON, "Moon")

object initializer for the Moon

Since: 1.2

See also: object

◆ NOVAS_NEPTUNE_INIT

#define NOVAS_NEPTUNE_INIT NOVAS_PLANET_INIT(NOVAS_NEPTUNE, "Neptune")

object initializer for the planet Neptune

Since: 1.2

See also: object

◆ NOVAS_OBJECT_TYPES

#define NOVAS_OBJECT_TYPES (NOVAS_ORBITAL_OBJECT + 1)

The number of object types distinguished by NOVAS.

See also: enum novas_object_type

◆ NOVAS_OBSERVER_PLACES

#define NOVAS_OBSERVER_PLACES (NOVAS_SOLAR_SYSTEM_OBSERVER + 1)

The number of observer place types supported

See also: enum novas_observer_place

◆ NOVAS_ORBIT_INIT

#define NOVAS_ORBIT_INIT { NOVAS_ORBITAL_SYSTEM_INIT, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

Initializer for novas_orbital for heliocentric orbits using GCRS ecliptic pqrametrization.

See also: novas_orbital

Author: Attila Kovacs

Since: 1.2

◆ NOVAS_ORBITAL_SYSTEM_INIT

#define NOVAS_ORBITAL_SYSTEM_INIT { NOVAS_SUN, NOVAS_ECLIPTIC_PLANE, NOVAS_GCRS, 0.0, 0.0 }

Default orbital system initializer for heliocentric GCRS ecliptic orbits.

See also: novas_orbital_system

Author: Attila Kovacs

Since: 1.2

◆ NOVAS_ORIGIN_TYPES

#define NOVAS_ORIGIN_TYPES (NOVAS_HELIOCENTER + 1)

The number of different ICSR origins available in NOVAS.

See also: enum novas_origin

◆ NOVAS_PLANET_GRAV_Z_INIT

#define NOVAS_PLANET_GRAV_Z_INIT

Value:

  { \
  0.0, 1.0047e-10, 5.9724e-10, 7.3050e-10, 1.4058e-10, 2.0166e-8, 7.2491e-9, 2.5420e-9, \
  3.0893e-9, 9.1338e-12, 2.120483e-6, 3.1397e-11, 0.0, 0.0 }

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

◆ NOVAS_PLANET_INIT

#define NOVAS_PLANET_INIT	(	num,
		name
	)	{ NOVAS_PLANET, num, name, CAT_ENTRY_INIT, NOVAS_ORBIT_INIT }

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

◆ NOVAS_PLANET_NAMES_INIT

#define NOVAS_PLANET_NAMES_INIT

Value:

  { \
  "SSB", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", \
  "Sun", "Moon", "EMB", "Pluto-Barycenter" }

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

const char *planet_names[] = NOVAS_PLANET_NAMES_INIT;

NOVAS_PLANET_NAMES_INIT

#define NOVAS_PLANET_NAMES_INIT

Definition novas.h:339

See also: novas_majot_planet

◆ NOVAS_PLANETS

#define NOVAS_PLANETS (NOVAS_PLUTO_BARYCENTER + 1)

The number of major planets defined in NOVAS.

See also: enum novas_planet

◆ NOVAS_PLUTO_BARYCENTER_INIT

#define NOVAS_PLUTO_BARYCENTER_INIT NOVAS_PLANET_INIT(NOVAS_PLUTO_BARYCENTER, "Pluto-Barycenter")

object initializer for the Pluto system barycenter

Since: 1.2

See also: object

◆ NOVAS_PLUTO_INIT

#define NOVAS_PLUTO_INIT NOVAS_PLANET_INIT(NOVAS_PLUTO, "Pluto")

object initializer for the minor planet Pluto

Since: 1.2

See also: object

◆ NOVAS_REFERENCE_SYSTEMS

#define NOVAS_REFERENCE_SYSTEMS (NOVAS_MOD + 1)

The number of basic coordinate reference systems in NOVAS.

See also: enum novas_reference_system

◆ NOVAS_RMASS_INIT

#define NOVAS_RMASS_INIT

Value:

      { \
      328900.561400, 6023600.0, 408523.71, 332946.050895, 3098708.0, 1047.3486, 3497.898, \
      22902.98, 19412.24, 135200000.0, 1.0, 27068700.387534, 0.0, 0.0 }

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.

See also: enum novas_planet; NOVAS_PLANETS

◆ NOVAS_SATURN_INIT

#define NOVAS_SATURN_INIT NOVAS_PLANET_INIT(NOVAS_SATURN, "Saturn")

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

◆ NOVAS_SOLAR_RADIUS

#define NOVAS_SOLAR_RADIUS 696340000.0

[m] Solar radius (photosphere)

Since: 1.1

◆ NOVAS_SSB_INIT

#define NOVAS_SSB_INIT NOVAS_PLANET_INIT(NOVAS_SSB, "SSB")

object initializer for the Solar System Barycenter (SSB)

Since: 1.2

See also: object

◆ NOVAS_SUN_INIT

#define NOVAS_SUN_INIT NOVAS_PLANET_INIT(NOVAS_SUN, "Sun")

object initializer for the Sun

Since: 1.2

See also: object

◆ NOVAS_SYSTEM_B1950

#define NOVAS_SYSTEM_B1950 "B1950"

The B1950 coordiante system as a string

Since: 1.3

◆ NOVAS_SYSTEM_FK4

#define NOVAS_SYSTEM_FK4 "FK4"

The 4th catalog (FK4) coordinate system as a string

Since: 1.3

◆ NOVAS_SYSTEM_FK5

#define NOVAS_SYSTEM_FK5 "FK5"

The 5th catalog (FK5) coordinate system as a string

Since: 1.3

◆ NOVAS_SYSTEM_HIP

#define NOVAS_SYSTEM_HIP "HIP"

The Hipparcos dataset coordinate system as a string

Since: 1.3

◆ NOVAS_SYSTEM_ICRS

#define NOVAS_SYSTEM_ICRS "ICRS"

The ICRS system as a string

Since: 1.3

◆ NOVAS_SYSTEM_J2000

#define NOVAS_SYSTEM_J2000 "J2000"

The J2000 coordinate syste, as a string

Since: 1.3

◆ NOVAS_TIMESCALES

#define NOVAS_TIMESCALES (NOVAS_UT1 + 1)

The number of asronomical time scales supported.

See also: novas_timescale

Since: 1.1

◆ NOVAS_TRANSFORM_TYPES

#define NOVAS_TRANSFORM_TYPES (ICRS_TO_J2000 + 1)

The number of coordinate transfor types in NOVAS.

See also: enum novas_transform_type

◆ NOVAS_URANUS_INIT

#define NOVAS_URANUS_INIT NOVAS_PLANET_INIT(NOVAS_URANUS, "Uranus")

object initializer for the planet Uranus

Since: 1.2

See also: object

◆ NOVAS_VENUS_INIT

#define NOVAS_VENUS_INIT NOVAS_PLANET_INIT(NOVAS_VENUS, "Venus")

object initializer for the planet Mercury

Since: 1.2

See also: object

◆ ON_SURFACE_INIT

#define ON_SURFACE_INIT { 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }

Initializer for a NOVAS on_surface data structure.

See also: on_surface; ON_SURFACE_INIT_LOC

Since: 1.2

◆ ON_SURFACE_LOC

#define ON_SURFACE_LOC	(	lon,
		lat,
		alt
	)	{ lon, lat, alt, 0.0, 0.0, 0.0 }

Initializer for a NOVAS on_surface data structure, for 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.

See also: on_surface; ON_SURFACE_INIT

Since: 1.2

◆ SKY_POS_INIT

#define SKY_POS_INIT { {0.0}, 0.0, 0.0, 0.0, 0.0 }

Initializer for a NOVAS sky_pos structure.

See also: sky_pos

Since: 1.1.1

◆ SUPERNOVAS_VERSION_STRING

#define SUPERNOVAS_VERSION_STRING

The version string for this library

Typedef Documentation

◆ RefractionModel

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

Parameters

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	Whether the input elevation is observed or astrometric: REFRACT_OBSERVED (-1) or REFRACT_ASTROMETRIC (0).
el	[deg] Astrometric (unrefracted) source elevation

Returns: [arcsec] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).

Since: 1.1

Enumeration Type Documentation

◆ novas_accuracy

enum novas_accuracy

Constants to control the precision of NOVAS nutation calculations.

Enumerator
NOVAS_FULL_ACCURACY	Use full precision calculations to micro-arcsecond accuracy. It can be computationally intensive when using the dynamical equator.
NOVAS_REDUCED_ACCURACY	Calculate with truncated terms. It can be significantly faster if a few milliarcsecond accuracy is sufficient.

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

enum novas_cio_location_type

System in which CIO location is calculated.

Enumerator
CIO_VS_GCRS	The location of the CIO relative to the GCRS frame.
CIO_VS_EQUINOX	The location of the CIO relative to the true equinox in the dynamical frame.

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

enum novas_debug_mode

Settings for 'novas_debug()'

See also: novas_debug

Enumerator
NOVAS_DEBUG_OFF	Do not print errors and traces to the standard error (default).
NOVAS_DEBUG_ON	Print errors and traces to the standard error.
NOVAS_DEBUG_EXTRA	Print all errors and traces to the standard error, even if they may be acceptable behavior.

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

Enumerator
NOVAS_DYNAMICAL_MOD	Mean equinox Of Date (TOD): dynamical system not including nutation (pre IAU 2006 system).
NOVAS_DYNAMICAL_TOD	True equinox Of Date (TOD): dynamical system of the 'true' equator, with its origin at the true equinox (pre IAU 2006 system; Lieske et. al. 1977).
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_earth_rotation_measure

enum novas_earth_rotation_measure

Constants that determine the type of rotation measure to use.

Enumerator
EROT_ERA	Use Earth Rotation Angle (ERA) as the rotation measure, relative to the CIO (new IAU 2006 standard)
EROT_GST	Use GST as the rotation measure, relative to the true equinox (pre IAU 20006 standard)

◆ 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

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

◆ novas_equatorial_class

enum novas_equatorial_class

The class of celestial coordinates used as parameters for ter2cel() and cel2ter().

Enumerator
NOVAS_REFERENCE_CLASS	Celestial coordinates are in GCRS.
NOVAS_DYNAMICAL_CLASS	Celestial coordinates are apparent values (CIRS or TOD)

◆ novas_equinox_type

enum novas_equinox_type

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

Enumerator

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(); 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).
ICRS_TO_J2000	Change coordinates from J2000 (dynamical) frame to the ICRS. (You can use any value >=0 for the same effect).

◆ novas_nutation_direction

enum novas_nutation_direction

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

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

Enumerator
NOVAS_PLANET	A major planet, or else the Sun, the Moon, or the Solar-System Barycenter (SSB). See also 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 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 cat_entry
NOVAS_ORBITAL_OBJECT	Any Solar-system body, whose position is determined by a set of orbital elements Since 1.2 See also 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: NOVAS_OBSERVER_PLACES

Enumerator
NOVAS_OBSERVER_AT_GEOCENTER	Calculate coordinates as if observing from the geocenter for location and Earth rotation independent coordinates.
NOVAS_OBSERVER_ON_EARTH	Stationary observer in the corotating frame of Earth.
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.
NOVAS_AIRBORNE_OBSERVER	Observer airborne, moving relative to the surface of Earth. Since 1.1
NOVAS_SOLAR_SYSTEM_OBSERVER	Observer is orbiting the Sun. Since 1.1

◆ novas_origin

enum novas_origin

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

See also: 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: NOVAS_PLANET; NOVAS_PLANETS; NOVAS_PLANET_NAMES_INIT

Enumerator
NOVAS_SSB	Solar-system barycenter position ID.
NOVAS_MERCURY	Major planet number for the Mercury in NOVAS.
NOVAS_VENUS	Major planet number for the Venus in NOVAS.
NOVAS_EARTH	Major planet number for the Earth in NOVAS.
NOVAS_MARS	Major planet number for the Mars in NOVAS.
NOVAS_JUPITER	Major planet number for the Jupiter in NOVAS.
NOVAS_SATURN	Major planet number for the Saturn in NOVAS.
NOVAS_URANUS	Major planet number for the Uranus in NOVAS.
NOVAS_NEPTUNE	Major planet number for the Neptune in NOVAS.
NOVAS_PLUTO	Major planet number for the 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_pole_offset_type

enum novas_pole_offset_type

The convention in which the celestial pole offsets are defined for polar wobble.

Enumerator
POLE_OFFSETS_DPSI_DEPS	Offsets are Δdψ, Δdε pairs (pre IAU 2006 precession-nutation model).
POLE_OFFSETS_X_Y	Offsets are dx, dy pairs (IAU 2006 precession-nutation model)

◆ novas_reference_plane

enum novas_reference_plane

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

Author: Attila Kovacs

Since: 1.2

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

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). It is inherently less precise than the new standard CIRS because mainly because it is based on separate, and less-precise, precession and nutation models (Lieske et. al. 1977).
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 equinox 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 no nutation. Since 1.1

◆ novas_refraction_model

enum novas_refraction_model

Constants that determine whether refraction calculations should use a standard atmospheric model, or whatever weather parameters have been been specified for the observing location.

See also: on_surface; refract()

Enumerator
NOVAS_NO_ATMOSPHERE	Do not apply atmospheric refraction correction.
NOVAS_STANDARD_ATMOSPHERE	Uses a standard atmospheric model, ignoring all weather values defined for the specific observing location
NOVAS_WEATHER_AT_LOCATION	Uses the weather parameters that are specified together with the observing location.

◆ novas_refraction_type

enum novas_refraction_type

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

See also: RefractionModel

Since: 1.1

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

◆ novas_timescale

enum novas_timescale

Constants to reference various astrnomical timescales used

See also: NOVAS_TIMESCALES; timescale.c

Since: 1.1

Enumerator
NOVAS_TCB	Barycentric Coordinate Time (TCB)
NOVAS_TDB	Barycentric Dynamical Time (TDB)
NOVAS_TCG	Geocentric Coordinate Time (TCG)
NOVAS_TT	Terrestrial Time (TT)
NOVAS_TAI	Innternational Atomic Time (TAI)
NOVAS_GPS	GPS Time.
NOVAS_UTC	Universal Coordinated Time (UTC)
NOVAS_UT1	UT1 earth rotation time, based on the measured Earth orientation parameters published in IERS Bulletin A.

◆ novas_transform_type

enum novas_transform_type

The types of coordinate transformations available for tranform_cat().

See also: transform_cat(); 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: wobble(); WOBBLE_ITRS_TO_TIRS

Enumerator
WOBBLE_ITRS_TO_PEF	use for wobble() to change from ITRS (actual rotating Earth) to Pseudo Earth Fixed (PEF) / TIRS.
WOBBLE_PEF_TO_ITRS	use for wobble() to change from Pseudo Earth Fixed (PEF) / TIRS to ITRS (actual rotating Earth).

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:

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

REFERENCES:

Murray, C. A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
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, components in AU/day.
	lighttime	[day] Light time from object to Earth in days (if known). Or set to 0, and this function will compute it.
[out]	out	[AU] Position vector, referred to origin at center of mass of the Earth, corrected for aberration, components in AU. 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: place()

References novas_vlen().

◆ 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(); ee_ct(); NOVAS_JD_J2000

Since: 1.0

Author: Attila Kovacs

References TWOPI.

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

Computes the apparent place of a solar system body. This is the same as calling place() for the body with NOVAS_TOD as the system, except the different set of return values used.

NOTES:

This call uses the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C function.

REFERENCES:

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

Deprecated:: Use place_cirs() is now preferred, especially for high accuracy calculations.

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 right ascension in hours, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)
[out]	dec	[deg] Apparent declination in degrees, referred to true equator and equinox of date 'jd_tt'. (It may be NULL if not required)
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU (can 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 code from place().

See also: place_tod(); astro_planet(); local_planet(); topo_planet(); virtual_planet(); app_star()

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
	)

Computes the apparent place of a star, referenced to dynamical equator 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_TOD as the system for an object that specifies the star.

NOTES:

This call uses the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C function.

REFERENCES:

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

Deprecated:: Use place_cirs() is now preferred, especially for high accuracy calculations.

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 right ascension in hours, referred to true equator and equinox of date 'jd_tt' (it may be NULL if not required).
[out]	dec	[deg] Apparent declination in degrees, 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(); place_star(); astro_star(); local_star(); topo_star(); virtual_star(); app_planet()

References NOVAS_TOD, and radec_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().

See also: cirs_to_app_ra(); tod_to_cirs()

Since: 1.0.1

Author: Attila Kovacs

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
	)

Computes the astrometric place of a solar system body, 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:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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 right ascension in hours, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dec	[deg] Astrometric declination in degrees, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU (can 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 code from place().

See also: place_icrs(); app_planet(); local_planet(); topo_planet(); virtual_planet(); astro_star()

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
	)

Computes the astrometric place of a star, 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:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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 right ascension in hours, referred to the ICRS, without light deflection or aberration. (It may be NULL if not required)
[out]	dec	[deg] Astrometric declination in degrees, 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()

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:

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

Parameters

	pos	[AU] Position vector, referred to origin at solar system barycenter, components in AU.
	pos_obs	[AU] Position vector of observer (or the geocenter), with respect to origin at solar system barycenter, components in AU.
[out]	out	[AU] Position vector, referred to origin at center of mass of the Earth, components in AU. 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 in days. It may be NULL if not required.

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

See also: place(); light_time2()

References novas_vlen().

◆ 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 for 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:

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_id_to_calendar() instead to convert JD days to dates in specific calendars.
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:

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

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_jd_from_date(); get_utc_to_tt(); get_ut1_to_tt(); tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_to_date().

◆ cel2ter()

short cel2ter	(	double	jd_ut1_high,
		double	jd_ut1_low,
		double	ut1_to_tt,
		enum novas_earth_rotation_measure	erot,
		enum novas_accuracy	accuracy,
		enum novas_equatorial_class	class,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a vector from the celestial to the terrestrial system. Specifically, it transforms a vector in the GCRS, or the dynamcal CIRS or TOD frames to the ITRS (a rotating earth-fixed system) by applying rotations for the GCRS-to-dynamical frame tie, precession, nutation, Earth rotation, and polar motion.

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

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

Deprecated:: This function can be confusing to use due to the input coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

REFERENCES:

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

Parameters

	jd_ut1_high	[day] High-order part of UT1 Julian date.
	jd_ut1_low	[day] Low-order part of UT1 Julian date.
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	erot	EROT_ERA (0) or EROT_GST (1), depending on whether to use GST relative to equinox of date (pre IAU 2006) or ERA relative to the CIO (IAU 2006 standard) as the Earth rotation measure. The main effect of this option is that it specifies the input coordinate system as CIRS or TOD when the input coordinate class is NOVAS_DYNAMICAL_CLASS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	class	Input coordinate class, NOVAS_REFERENCE_CLASS (0) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the input coordinates are in the GCRS, and the latter if they are CIRS or TOD (the 'erot' parameter selects which dynamical system the input is specified in.)
	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	Input position vector, geocentric equatorial rectangular coordinates in the specified input coordinate system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST).
[out]	out	ITRS position vector, geocentric equatorial rectangular coordinates (terrestrial system). It can be the same vector as the input.

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

See also: gcrs_to_cirs(); cirs_to_itrs(); frame_tie(); j2000_to_tod(); tod_to_itrs(); ter2cel()

References era(), EROT_ERA, EROT_GST, gcrs_to_cirs(), gcrs_to_tod(), NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, sidereal_time(), spin(), tt2tdb(), wobble(), and WOBBLE_PEF_TO_ITRS.

◆ cel_pole()

short cel_pole	(	double	jd_tt,
		enum novas_pole_offset_type	type,
		double	dpole1,
		double	dpole2
	)

specifies the celestial pole offsets for high-precision applications. Each set of offsets is a correction to the modeled position of the pole for a specific date, derived from observations and published by the IERS.

The variables 'PSI_COR' and 'EPS_COR' are used only in NOVAS function e_tilt().

This function, if used, should be called before any other NOVAS functions for a given date. Values of the pole offsets specified via a call to this function will be used until explicitly changed.

'tjd' is used only if 'type' is POLE_OFFSETS_X_Y (2), to transform dx and dy to the equivalent Δδψ and Δδε values.

If 'type' is POLE_OFFSETS_X_Y (2), dx and dy are unit vector component corrections, but are expressed in milliarcseconds simply by multiplying by 206264806, the number of milliarcseconds in one radian.

NOTES:

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

REFERENCES:

Kaplan, G. (2005), US Naval Observatory Circular 179.
Kaplan, G. (2003), USNO/AA Technical Note 2003-03.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian date.
type	POLE_OFFSETS_DPSI_DEPS (1) or POLE_OFFSETS_X_Y (2)
dpole1	[mas] Value of celestial pole offset in first coordinate, (Δδψ or dx) in milliarcseconds.
dpole2	[mas] Value of celestial pole offset in second coordinate, (Δδε or dy) in milliarcseconds.

Returns: 0 if successful, or else 1 if 'type' is invalid.

See also: cirs_to_itrs(); tod_to_itrs(); e_tilt(); place(); get_ut1_to_tt(); sidereal_time(); NOVAS_FULL_ACCURACY

References EPS_COR, POLE_OFFSETS_DPSI_DEPS, POLE_OFFSETS_X_Y, and PSI_COR.

◆ cio_array()

short cio_array	(	double	jd_tdb,
		long	n_pts,
		ra_of_cio *restrict	cio
	)

Given an input TDB Julian date and the number of data points desired, this function returns a set of Julian dates and corresponding values of the GCRS right ascension of the celestial intermediate origin (CIO). The range of dates is centered (at least approximately) on the requested date. The function obtains the data from an external data file.

This function assumes that a CIO locator file (CIO_RA.TXT or cio_ra.bin) exists in the default location (configured at build time), or else was specified via set_cio_locator_file() prior to calling this function.

NOTES:

This function has been completely re-written by A. Kovacs to provide much more efficient caching and I/O.

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	n_pts	Number of Julian dates and right ascension values requested (not less than 2 or more than NOVAS_CIO_CACHE_SIZE).
[out]	cio	A time series (array) of the right ascension of the Celestial Intermediate Origin (CIO) with respect to the GCRS.

Returns: 0 if successful, -1 if the output array is NULL or there was an I/O error accessing the CIO location data file. Or else 1 if no locator data file is available, 2 if 'jd_tdb' not in the range of the CIO file, 3 if 'n_pts' out of range, or 6 if 'jd_tdb' is too close to either end of the CIO file do we are unable to put 'n_pts' data points into the output

See also: set_cio_locator_file(); cio_location()

References DEFAULT_CIO_LOCATOR_FILE, NOVAS_CIO_CACHE_SIZE, and set_cio_locator_file().

◆ cio_basis()

short cio_basis	(	double	jd_tdb,
		double	ra_cio,
		enum novas_cio_location_type	loc_type,
		enum novas_accuracy	accuracy,
		double *restrict	x,
		double *restrict	y,
		double *restrict	z
	)

Computes the orthonormal basis vectors, with respect to the GCRS (geocentric ICRS), of the celestial intermediate system defined by the celestial intermediate pole (CIP) (in the z direction) and the celestial intermediate origin (CIO) (in the x direction). A TDB Julian date and the right ascension of the CIO at that date is required as input. The right ascension of the CIO can be with respect to either the GCRS origin or the true equinox of date – different algorithms are used in the two cases.

This function effectively constructs the matrix C in eq. (3) of the reference.

REFERENCES:

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

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	ra_cio	[h] Right ascension of the CIO at epoch (hours).
	loc_type	CIO_VS_GCRS (1) if the cio location is relative to the GCRS or else CIO_VS_EQUINOX (2) if relative to the true equinox of date.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	x	Unit 3-vector toward the CIO, equatorial rectangular coordinates, referred to the GCRS.
[out]	y	Unit 3-vector toward the y-direction, equatorial rectangular coordinates, referred to the GCRS.
[out]	z	Unit 3-vector toward north celestial pole (CIP), equatorial rectangular coordinates, referred to the GCRS.

Returns: 0 if successful, or -1 if any of the output vector arguments are NULL or if the accuracy is invalid, or else 1 if 'ref-sys' is invalid.

See also: cio_location(); gcrs_to_cirs()

References CIO_VS_EQUINOX, CIO_VS_GCRS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, novas_vlen(), and tod_to_gcrs().

◆ cio_location()

short cio_location	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		double *restrict	ra_cio,
		short *restrict	loc_type
	)

Returns the location of the celestial intermediate origin (CIO) for a given Julian date, as a right ascension with respect to either the GCRS (geocentric ICRS) origin or the true equinox of date. The CIO is always located on the true equator (= intermediate equator) of date.

The user may specify an interpolation file to use via set_cio_locator_file() prior to calling this function. In that case the call will return CIO location relative to GCRS. In the absence of the table, it will calculate the CIO location relative to the true equinox. In either case the type of the location is returned alongside the corresponding CIO location value.

NOTES:

Unlike the NOVAS C version of this function, this version will always return a CIO location as long as the pointer arguments are not NULL. The returned values will be interpolated from the locator file if possible, otherwise it falls back to calculating an equinox-based location per default.

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra_cio	[h] Right ascension of the CIO, in hours, or NAN if returning with an error.
[out]	loc_type	Pointer in which to return the reference system in which right ascension is given, which is either CIO_VS_GCRS (1) if the location was obtained via interpolation of the available data file, or else CIO_VS_EQUINOX (2) if it was calculated locally. It is set to -1 if returning with an error.

Returns: 0 if successful, -1 if one of the pointer arguments is NULL or the accuracy is invalid.

See also: set_cio_locator_file(); cio_ra(); gcrs_to_cirs()

References cio_array(), CIO_VS_EQUINOX, CIO_VS_GCRS, ira_equinox(), novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DEBUG_ON, NOVAS_FULL_ACCURACY, novas_get_debug_mode(), NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

◆ 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) at a given TT Julian date. This is the negative value for the equation of the origins.

REFERENCES:

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, in hours (+ 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()

References cio_basis(), cio_location(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, tod_to_gcrs(), and tt2tdb().

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

See also: app_to_cirs_ra(); cirs_to_tod()

Since: 1.0.1

Author: Attila Kovacs

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 Geocentric Celestial Reference System (GCRS).

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 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 an error from cio_location(), or else 10 + the error from cio_basis().

See also: tod_to_gcrs(); gcrs_to_cirs(); cirs_to_itrs(); cirs_to_tod()

Since: 1.0

Author: Attila Kovacs

References cio_basis(), and cio_location().

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

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: tod_to_itrs(); itrs_to_cirs(); gcrs_to_cirs(); cirs_to_gcrs(); cirs_to_tod()

Since: 1.0

Author: Attila Kovacs

References cel2ter(), EROT_ERA, and NOVAS_DYNAMICAL_CLASS.

◆ 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 10 + the error from cio_location(), or else 20 + the error from cio_basis().

See also: tod_to_cirs(); cirs_to_app_ra(); cirs_to_gcrs(); cirs_to_itrs()

Since: 1.1

Author: Attila Kovacs

References cio_ra(), and spin().

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

This function is called by 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: place()

References novas_vlen().

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

Computes quantities related to the orientation of the Earth's rotation axis at Julian date 'jd_tdb'.

Values of the celestial pole offsets 'PSI_COR' and 'EPS_COR' are set using function 'cel_pole', if desired. See the prolog of cel_pole() for details.

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 in degrees. It may be NULL if not required.
[out]	tobl	[deg] True obliquity of the ecliptic in degrees. It may be NULL if not required.
[out]	ee	[deg] Equation of the equinoxes in seconds of time. It may be NULL if not required.
[out]	dpsi	[arcsec] Nutation in longitude in arcseconds. It may be NULL if not required.
[out]	deps	[arcsec] Nutation in obliquity in arcseconds. It may be NULL if not required.

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

See also: cel_pole(); place(); equ2ecl(); ecl2equ()

References ee_ct(), EPS_COR, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, nutation_angles(), and PSI_COR.

◆ 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 specified ecliptic and equinox of date.
	elat	[deg] Ecliptic latitude in degrees, referred to 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.

See also: ecl2equ_vec(); equ2ecl()

Since: 1.0

Author: Attila Kovacs

References ecl2equ_vec().

◆ 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 specified ecliptic and equinox of date.
[out]	out	Position vector, referred to 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, NOVAS_TRUE_EQUATOR, and tt2tdb().

◆ ee_ct()

double ee_ct	(	double	jd_tt_high,
		double	jd_tt_low,
		enum novas_accuracy	accuracy
	)

Computes the "complementary terms" of the equation of the equinoxes. The input Julian date can be split into high and low order parts for improved accuracy. Typically, the split is into integer and fractiona parts. If the precision of a single part is sufficient, you may set the low order part to 0.

The series used in this function was derived from the first reference. This same series was also adopted for use in the IAU's Standards of Fundamental Astronomy (SOFA) software (i.e., subroutine eect00.for and function eect00.c).

The low-accuracy series used in this function is a simple implementation derived from the first reference, in which terms smaller than 2 microarcseconds have been omitted.

REFERENCES:

Capitaine, N., Wallace, P.T., and McCarthy, D.D. (2003). Astron. & Astrophys. 406, p. 1135-1149. Table 3.
IERS Conventions (2010), Chapter 5, p. 60, Table 5.2e.
(Table 5.2e presented in the printed publication is a truncated series. The full series, which is used in NOVAS, is available on the IERS Conventions Center website: ftp://tai.bipm.org/iers/conv2010/chapter5/tab5.2e.txt)

Parameters

jd_tt_high	[day] High-order part of TT based Julian date.
jd_tt_low	[day] Low-order part of TT based Julian date.
accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)

Returns: [rad] Complementary terms, in radians.

See also: e_tilt(); cel_pole(); nutation(); sidereal_time()

References accum_prec(), novas_delaunay_args::D, novas_delaunay_args::F, fund_args(), NOVAS_FULL_ACCURACY, NOVAS_MERCURY, NOVAS_NEPTUNE, novas_delaunay_args::Omega, and planet_lon().

◆ 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 from a fundamental ephemeris.

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 solarsystem(), or 20 + the error code from readeph().

See also: set_planet_provider(); set_planet_provider_hp(); set_ephem_provider(); ephem_open(); 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, NOVAS_SUN, and readeph().

◆ 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 specified equator and equinox of date.
	dec	[deg] Declination in degrees, referred to 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().

◆ 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 specified equator and equinox of date.
[out]	out	Position vector, referred to 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, NOVAS_TRUE_EQUATOR, and tt2tdb().

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

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

◆ equ2hor()

int equ2hor	(	double	jd_ut1,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const on_surface *restrict	location,
		double	ra,
		double	dec,
		enum novas_refraction_model	ref_option,
		double *restrict	zd,
		double *restrict	az,
		double *restrict	rar,
		double *restrict	decr
	)

Transforms topocentric (TOD) right ascension and declination to zenith distance and azimuth. This method should not be used to convert CIRS apparent coordinates (IAU 2000 standard) – for those you should use cirs_to_itrs() followed by itrs_to_hor() instead.

It uses a method that properly accounts for polar motion, which is significant at the sub-arcsecond level. This function can also adjust coordinates for atmospheric refraction.

Deprecated:: The name of this function does not reveal what type of equatorial coordinates it requires. To make it less ambiguous, you should use tod_to_itrs() followed by itrs_to_hor() instead, possibly following it with refract_astro() if you also want to apply optical refraction.

NOTES:

'xp' and 'yp' can be set to zero if sub-arcsecond accuracy is not needed.
The directions 'zd'= 0 (zenith) and 'az'= 0 (north) are here considered fixed in the terrestrial system. Specifically, the zenith is along the geodetic normal, and north is toward the ITRS pole.
If 'ref_option' is NOVAS_STANDARD_ATMOSPHERE (1), then 'rar'='ra' and 'decr'='dec'.

REFERENCES:

Kaplan, G. (2008). USNO/AA Technical Note of 28 Apr 2008, "Refraction as a Vector."

Parameters

	jd_ut1	[day] UT1 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 reference pole, in arcseconds.
	yp	[arcsec] Conventionally-defined y coordinate of celestial intermediate pole with respect to ITRS reference pole, in arcseconds.
	location	The observer location
	ra	[h] Topocentric right ascension of object of interest, in hours, referred to true equator and equinox of date.
	dec	[deg] Topocentric declination of object of interest, in degrees, referred to true equator and equinox of date.
	ref_option	NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2) if to use the weather
[out]	zd	[deg] Topocentric zenith distance in degrees (unrefracted).
[out]	az	[deg] Topocentric azimuth (measured east from north) in degrees.
[out]	rar	[h] Topocentric right ascension of object of interest, in hours, referred to true equator and equinox of date, affected by refraction if 'ref_option' is non-zero. (It may be NULL if not required)
[out]	decr	[deg] Topocentric declination of object of interest, in degrees, referred to true equator and equinox of date. (It may be NULL if not required)

Returns: 0 if successful, or -1 if one of the 'zd' or 'az' output pointers are NULL.

See also: itrs_to_hor(); tod_to_itrs(); NOVAS_TOD

References EROT_GST, NOVAS_DYNAMICAL_CLASS, refract_astro(), and ter2cel().

◆ era()

double era	(	double	jd_ut1_high,
		double	jd_ut1_low
	)

Returns the value of the Earth Rotation Angle (theta) 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 cane 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 theta = 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; see also expression at top of page 35 of IERS Conventions (1996)).

REFERENCES:

IAU Resolution B1.8, adopted at the 2000 IAU General Assembly, Manchester, UK.
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: sidereal_time(); cirs_to_itrs(); itrs_to_cirs()

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

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

REFERENCES:

Hilton, J. and Hohenkerk, C. (2004), Astronomy and Astrophysics 413, 765-770, eq. (6) and (8).
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(); tod_to_j2000(); j2000_to_tod(); j2000_to_gcrs()

◆ fund_args()

int fund_args	(	double	t,
		novas_delaunay_args *restrict	a
	)

Compute the fundamental arguments (mean elements) of the Sun and Moon.

REFERENCES:

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(); ee_ct(); NOVAS_JD_J2000

References novas_norm_ang().

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

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.

See also: equ2gal()

Since: 1.0

Author: Attila Kovacs

◆ 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 the coord_sys is invalid, otherwise <0 if an error from vector2radec(), 10–20 error is 10 + error cio_location(); or else 20 + error from cio_basis()

References DEG2RAD, gcrs_to_cirs(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_DYNAMICAL_CIRS, NOVAS_DYNAMICAL_MOD, NOVAS_DYNAMICAL_TOD, tt2tdb(), 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 Geocentric Celestial Reference System (GCRS) to the Celestial Intermediate Reference System (CIRS) 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	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 an error from cio_location(), or else 10 + the error from cio_basis().

See also: gcrs_to_j2000(); cirs_to_gcrs()

Since: 1.0

Author: Attila Kovacs

References cio_basis(), and cio_location().

◆ gcrs_to_j2000()

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

Change GCRS coordinates to J2000 coordinates. Same as frame_tie() called with ICRS_TO_J2000

Parameters

	in	GCRS input 3-vector
[out]	out	J2000 output 3-vector

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

See also: j2000_to_gcrs(); tod_to_j2000()

Since: 1.0

Author: Attila Kovacs

References frame_tie(), and ICRS_TO_J2000.

◆ 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 Geocentric Celestial Reference System (GCRS) to the Mean of Date (MOD) reference frame at the given epoch

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

See also: mod_to_gcrs(); gcrs_to_tod()

Since: 1.2

Author: Attila Kovacs

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

◆ 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 Geocentric Celestial Reference System (GCRS) to the True of Date (TOD) reference frame at the given epoch

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

See also: gcrs_to_cirs(); tod_to_gcrs(); j2000_to_tod()

Since: 1.2

Author: Attila Kovacs

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

◆ 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 position and velocity of an observer. The final vectors are expressed in the GCRS.

Parameters

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

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

See also: place(); make_observer(); get_ut1_to_tt(); cel_pole()

References e_tilt(), ephemeris(), EROT_ERA, geo_posvel(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_REDUCED_ACCURACY, NOVAS_SOLAR_SYSTEM_OBSERVER, sidereal_time(), terra(), tod_to_gcrs(), tt2tdb(), and observer::where.

◆ get_nutation_lp_provider()

novas_nutation_provider get_nutation_lp_provider ( )

Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Returns: the function to use for low-precision IAU 2000 nutation calculations

See also: set_nutation_lp_provider(); nutation_angles()

Since: 1.3

Author: Attila Kovacs

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

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] UT1 - UTC time difference [-0.5:0.5]

Returns: [s] The TT - UT1 time difference that is suitable for used with all calls in this library that require a ut1_to_tt argument.

See also: get_utc_to_tt(); place(); cel_pole()

Since: 1.0

Author: Attila Kovacs

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

See also: get_ut1_to_tt(); julian_date()

Since: 1.0

Author: Attila Kovacs

References NOVAS_TAI_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
	)

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.

NOTES:

This function is called by 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().

REFERENCES:

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(); place(); novas_geom_to_app(); set_planet_provider(); 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
	)

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:

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

REFERENCES:

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: obs_planets(); grav_undo_planets(); grav_def(); novas_geom_to_app(); grav_bodies_full_accuracy; grav_bodies_reduced_accuracy

Since: 1.1

Author: Attila Kovacs

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

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

Computes the gravitationally undeflected position of an observed source position 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 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.

The number of bodies used at full and reduced accuracy can be set by making a change to the code in this function as indicated in the comments.

REFERENCES:

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

Computes the gravitationally undeflected position of an observed source position due to the specified Solar-system bodies.

REFERENCES:

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: obs_planets(); grav_planets(); novas_app_to_geom()

Since: 1.1

Author: Attila Kovacs

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

◆ grav_vec()

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

Corrects position vector for the deflection of light in the gravitational field of an arbitrary body. This function valid for an observed body within the solar system as well as for a star.

NOTES:

This function is called by grav_def() to calculate appropriate gravitational deflections for sources.

REFERENCES:

Murray, C.A. (1981) Mon. Notices Royal Ast. Society 195, 639-648.
See also formulae in Section B of the Astronomical Almanac, or
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: place(); grav_def()

References novas_vlen().

◆ 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	Observer location on Earth
	az	[deg] astrometric azimuth angle at observer location [0:360]. It may be NULL if not required.
	za	[deg] astrometric 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.

See also: itrs_to_hor(); itrs_to_cirs(); itrs_to_tod(); refract()

Since: 1.0

Author: Attila Kovacs

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

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:

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)

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_location(); gcrs_to_cirs()

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

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

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: itrs_to_tod(); cirs_to_itrs(); cirs_to_gcrs()

Since: 1.0

Author: Attila Kovacs

References EROT_ERA, NOVAS_DYNAMICAL_CLASS, and 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	Observer location on Earth
	itrs	3-vector position in Earth-fixed ITRS frame
[out]	az	[deg] astrometric azimuth angle at observer location [0:360]. It may be NULL if not required.
[out]	za	[deg] astrometric 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.

See also: hor_to_itrs(); cirs_to_itrs(); tod_to_itrs(); refract_astro()

Since: 1.0

Author: Attila Kovacs

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

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: itrs_to_cirs(); tod_to_itrs(); tod_to_j2000()

Since: 1.0

Author: Attila Kovacs

References EROT_GST, NOVAS_DYNAMICAL_CLASS, and ter2cel().

◆ j2000_to_gcrs()

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

Change J2000 coordinates to GCRS coordinates. Same as frame_tie() called with J2000_TO_ICRS

Parameters

	in	J2000 input 3-vector
[out]	out	GCRS output 3-vector

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

See also: j2000_to_tod(); gcrs_to_j2000()

Since: 1.0

Author: Attila Kovacs

References frame_tie(), and J2000_TO_ICRS.

◆ j2000_to_tod()

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

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

Parameters

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

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

See also: j2000_to_gcrs(); tod_to_j2000(); gcrs_to_j2000()

Since: 1.0

Author: Attila Kovacs

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

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

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

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 month or day components are out of range.

See also: novas_jd_from_date(); novas_jd_to_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, components in AU.
	tlight0	[day] First approximation to light-time, in days (can be set to 0.0 if unknown).
	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, components in AU. 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(); place()

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:

This function is called by 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, components in AU.
	tlight0	[day] First approximation to light-time, in days (can be set to 0.0 if unknown).
	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, components in AU/day.
[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(); place()

Since: 1.0

Author: Attila Kovacs

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

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

See also: place()

References M_PI, and novas_vlen().

◆ local_planet()

short local_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		double	ut1_to_tt,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis
	)

Computes the local apparent place of a solar system body, in the GCRS. This is the same as calling place() for the body for the same observer location and NOVAS_GCRS as the reference system, except the different set of return values used.

REFERENCES:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Local right ascension in hours, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Local right ascension in hours, referred to the GCRS (it may be NULL if not required).
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU (it may be NULL if not required).

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

See also: astro_planet(); topo_planet(); virtual_planet(); app_star(); get_ut1_to_tt()

References make_observer(), NOVAS_GCRS, NOVAS_OBSERVER_ON_EARTH, and radec_planet().

◆ local_star()

short local_star	(	double	jd_tt,
		double	ut1_to_tt,
		const cat_entry *restrict	star,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec
	)

Computes the local apparent place of a star at date 'jd_tt', in the GCRS, 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 the same observer location NOVAS_GCRS for an object that specifies the star.

REFERENCES:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	position	Position of the observer
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra	[h] Local right ascension in hours, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Local right ascension in hours, referred to the GCRS (it may be NULL if not required).

Returns: 0 if successful, or -1 if any of the required pointer arguments is NULL, or else 20 + the error from place().

See also: place_star(); app_star(); astro_star(); topo_star(); virtual_star(); astro_planet(); get_ut1_to_tt()

References make_observer(), NOVAS_GCRS, NOVAS_OBSERVER_ON_EARTH, and radec_star().

◆ make_airborne_observer()

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. 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 longitude, latitude and altitude, and local weather (temperature and pressure)
	vel	[km/s] Surface velocity.
[out]	obs	Pointer to data structure to populate.

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

See also: make_observer_at geocenter(); make_observer_in_space(); make_observer_on_surface(); make_solar_system_observer(); novas_calc_geometric_position(); place()

Since: 1.1

Author: Attila Kovacs

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

◆ make_cat_entry()

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

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

Parameters

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

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

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

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

◆ make_cat_object()

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

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

Parameters

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

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

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

Since: 1.1

Author: Attila Kovacs

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

◆ make_cat_object_sys()

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

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

Parameters

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

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

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

Since: 1.3

Author: Attila Kovacs

References make_cat_object(), and object::star.

◆ make_ephem_object()

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

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

Parameters

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

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

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

Since: 1.0

Author: Attila Kovacs

References make_object(), and NOVAS_EPHEM_OBJECT.

◆ make_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 in km. NULL defaults to the origin
	sc_vel	[km/s] Geocentric (x, y, z) velocity vector in km/s. 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(); make_on_surface(); IN_SPACE_INIT

References in_space::sc_pos, and in_space::sc_vel.

◆ make_object()

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

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

NOTES:

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

Parameters

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

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

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

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

◆ make_observer()

short make_observer	(	enum novas_observer_place	where,
		const on_surface *	loc_surface,
		const in_space *	loc_space,
		observer *	obs
	)

Populates an 'observer' data structure given the parameters. The output data structure may be used an the the inputs to NOVAS-C function 'place()'.

Parameters

	where	The location type of the observer
	loc_surface	Pointer to data structure that defines a location on Earth's surface. Used only if 'where' is NOVAS_OBSERVER_ON_EARTH, otherwise can be NULL.
	loc_space	Pointer to data structure that defines a near-Earth location in space. Used only if 'where' is NOVAS_OBSERVER_IN_EARTH_ORBIT, otherwise can be NULL.
[out]	obs	Pointer to observer data structure to populate.

Returns: 0 if successful, -1 if a required argument is NULL, or 1 if the 'where' argument is invalid.

See also: make_observer_at_geocenter(); make_observer_on_surface(); make_observer_in_space(); make_solar_system_observer()

References observer::near_earth, NOVAS_AIRBORNE_OBSERVER, NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_SOLAR_SYSTEM_OBSERVER, observer::on_surf, in_space::sc_vel, and observer::where.

◆ 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 function '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_observer_in_space(); make_observer_on_surface(); place()

References make_observer(), and NOVAS_OBSERVER_AT_GEOCENTER.

◆ 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 function 'place()'.

Parameters

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

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

See also: make_observer_on_surface(); make_observer_at_geocenter(); place()

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
	)

Populates and 'on_surface' data structure with the specified location defining parameters of the observer. The output data structure may be used an the the inputs to NOVAS-C function 'place()'.

Parameters

	latitude	[deg] Geodetic (ITRS) latitude in degrees; north positive.
	longitude	[deg] Geodetic (ITRS) longitude in degrees; east positive.
	height	[m] Altitude over se level of the observer (meters).
	temperature	[C] Temperature (degrees Celsius).
	pressure	[mbar] Atmospheric pressure (millibars).
[out]	obs	Pointer to the data structure to populate.

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

See also: make_observer_in_space(); make_observer_at_geocenter(); place()

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

◆ make_on_surface()

int make_on_surface	(	double	latitude,
		double	longitude,
		double	height,
		double	temperature,
		double	pressure,
		on_surface *restrict	loc
	)

Populates an 'on_surface' data structure, for an observer on the surface of the Earth, with the given parameters.

Note, that because this is an original NOVAS C routine, it does not have an argument to set a humidity value (e.g. for radio refraction). As such, the humidity value remains undefined after this call. To set the humidity, set the output structure's field after calling this funcion. Its unit is [%], and so the range is 0.0–100.0.

NOTES

This implementation breaks strict v1.0 ABI compatibility since it writes to (initializes) a field (humidity) that was not yet part of the on_surface structure in v1.0. As such, linking SuperNOVAS v1.1 or later with application code compiled for SuperNOVAS v1.0 can result in memory corruption or segmentation fault when this function is called. To be safe, make sure your application has been (re)compiled against SuperNOVAS v1.1 or later.

Parameters

	latitude	[deg] Geodetic (ITRS) latitude in degrees; north positive.
	longitude	[deg] Geodetic (ITRS) longitude in degrees; east positive.
	height	[m] Altitude over se level of the observer (meters).
	temperature	[C] Temperature (degrees Celsius).
	pressure	[mbar] Atmospheric pressure (millibars).
[out]	loc	Pointer to Earth location data structure to populate.

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

See also: make_observer_on_surface(); make_in_space(); ON_SURFACE_INIT; ON_SURFACE_LOC

◆ make_orbital_object()

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

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

Parameters

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

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

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

Since: 1.2

Author: Attila Kovacs

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

◆ make_planet()

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

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

Parameters

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

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

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

Since: 1.0

Author: Attila Kovacs

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

◆ make_redshifted_cat_entry()

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

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

Parameters

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

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

See also: make_redshifted_object_sys(); novas_v2z()

Since: 1.2

Author: Attila Kovacs

References make_cat_entry(), and novas_z2v().

◆ make_redshifted_object()

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

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

Parameters

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

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

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

Since: 1.2

Author: Attila Kovacs

References make_cat_object(), and make_redshifted_cat_entry().

◆ make_redshifted_object_sys()

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

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

Parameters

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

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

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

Since: 1.3

Author: Attila Kovacs

References make_redshifted_object(), and object::star.

◆ 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_observer_in_space(); make_observer_on_surface(); make_observer_at_geocenter(); make_airborne_observer(); novas_calc_geometric_position(); place()

Since: 1.1

Author: Attila Kovacs

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

◆ mean_obliq()

double mean_obliq ( double jd_tdb )

Computes the mean obliquity of the ecliptic.

REFERENCES:

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

◆ mean_star()

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

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

REFERENCES:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	tra	[h] Apparent (TOD) right ascension in hours, referred to true equator and equinox of date.
	tdec	[deg] Apparent (TOD) declination in degrees, referred to true equator and equinox of date.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ira	[h] ICRS right ascension in hours, or NAN when returning with an error code.
[out]	idec	[deg] ICRS declination in degrees, or NAN when returning with an error code.

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: make_cat_entry(); proper_motion(); precession()

References app_star(), CAT_ENTRY_INIT, cat_entry::dec, novas_inv_max_iter, precession(), 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 Geocentric Celestial Reference System(GCRS)

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

See also: gcrs_to_mod(); tod_to_gcrs()

Since: 1.2

Author: Attila Kovacs

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

◆ novas_app_to_geom()

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

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

Parameters

	frame	The observer frame, defining the location and time of observation
	sys	The reference system in which the observed position is specified.
	ra	[h] Observed ICRS right-ascension of the source
	dec	[deg] Observed ICRS declination of the source
	dist	[AU] Observed distance from observer. A value of <=0 will translate to 10¹⁵ 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).

See also: novas_geom_to_app(); novas_hor_to_app(); novas_geom_to_hor(); novas_transform_vector()

Since: 1.1

Author: Attila Kovacs

References grav_undo_planets(), NOVAS_CIRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TOD, and radec2vector().

◆ novas_app_to_hor()

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

Converts an observed apparent position vector in the specified coordinate system to local horizontal coordinates in the specified observer frame. The observer must be located on the surface of Earth, or else the call will return with an error. The caller may optionally supply a refraction model of choice to calculate an appropriate elevation angle that includes a refraction correction for Earth's atmosphere. If no such model is provided the calculated elevation will be the astrometric elevation without a refraction correction.

Parameters

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

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

See also: novas_hor_to_app(); novas_app_to_geom(); novas_standard_refraction(); novas_optical_refraction(); novas_radio_refraction()

Since: 1.1

Author: Attila Kovacs

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

◆ novas_case_sensitive()

void novas_case_sensitive ( int value )

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

Parameters

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

See also: make_object()

Since: 1.0

Author: Attila Kovacs

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

See also: novas_make_frame()

Since: 1.1

Author: Attila Kovacs

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.

◆ 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 an 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_debug()

void novas_debug ( enum novas_debug_mode mode )

==========================================================================

Enables or disables reporting errors and traces to the standard error stream.

Parameters

mode	NOVAS_DEBUG_OFF (0; or <0), NOVAS_DEBUG_ON (1), or NOVAS_DEBUG_EXTRA (2; or >2).

Since: 1.0

Author: Attila Kovacs

See also: novas_get_debug_mode()

References NOVAS_DEBUG_EXTRA.

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

See also: novas_diff_tcg(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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)

See also: novas_diff_tcb(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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)

See also: novas_set_time(); novas_offset_time(); novas_diff_tcb(); novas_diff_tcg()

Since: 1.1

Author: Attila Kovacs

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

◆ 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 last component may additionally be followed by a standalone upper-case letter 'N', 'E', 'S', or 'W' signifying a compass direction.

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__S

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:

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

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. Converting between local flat projections and spherical coordinates usually requires a WCS projection.

REFERENCES:

Calabretta, M.R., & Greisen, E.W., (2002), Astronomy & Astrophysics, 395, 1077-1122.

Parameters

	dra	[arcsec] Projected ffset position in the apparent true-of-date R.A. direction. E.g. The projected offset between two RA coordinates at a same reference declination, is δRA = (RA2 - RA1) * cos(Dec₀)
	ddec	[arcsec] Projected offset position in the apparent true-of-date declination direction.
	pa	[deg] Parallactic Angle
[out]	daz	[arcsec] Output offset position in the local azimuth direction. It can be a pointer to one of the input coordinates, or NULL if not required.
[out]	del	[arcsec] Output offset position in the local elevation direction. It can be a pointer to one of the input coordinates, or NULL if not required.

Returns: 0

Since: 1.3

Author: Attila Kovacs

See also: novas_h2e_offset(); novas_epa()

References novas_h2e_offset().

◆ novas_epa()

double novas_epa	(	double	ha,
		double	dec,
		double	lat
	)

Returns the equatorial Parallactic Angle (PA) calculated for an R.A./Dec location of the sky at a given sidereal time. The PA is the angle between the local horizontal coordinate directions and the local true-of-date equatorial coordinate directions, at the given location and time. The polar wobble is not included in the calculation.

The Parallactic Angle is sometimes referrred to as the Vertical Position Angle (VPA). Both define the same quantity.

Parameters

ha	[h] Hour angle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
dec	[deg] Apparent (true-of-date) declination of observed source
lat	[deg] Geodetic latitude of observer

Returns: [deg] Parallactic Angle (PA). I.e., the clockwise position angle of the elevation direction w.r.t. the declination axis in the equatorial system. Same as the clockwise position angle of the declination direction w.r.t. the elevation axis, in the horizontal system.

Since: 1.3

Author: Attila Kovacs

See also: novas_hpa(); novas_lst(); novas_e2h_offset()

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

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_JD_B1950, NOVAS_JD_HIP, NOVAS_JD_J2000, NOVAS_SYSTEM_FK4, NOVAS_SYSTEM_FK5, NOVAS_SYSTEM_HIP, and NOVAS_SYSTEM_ICRS.

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

◆ novas_equ_track()

int novas_equ_track	(	const object *restrict	source,
		const novas_frame *restrict	frame,
		double	dt,
		novas_track *restrict	track
	)

Calculates equatorial tracking position and motion (first and second time derivatives) for the specified source in the given observing frame. The position and its derivatives are calculated via the more precise IAU2006 method, and CIRS.

Parameters

	source	Observed source
	frame	Observing frame, defining the observer location and astronomical time of observation.
	dt	[s] Time step used for calculating derivatives.
[out]	track	Output tracking parameters to populate

Returns: 0 if successful, or else -1 if any of the pointer arguments are NULL, or else an error code from cio_ra() or from novas_sky_pos().

Since: 1.3

Author: Attila Kovacs

See also: novas_hor_track(); novas_track_pos()

References cio_ra(), sky_pos::dec, sky_pos::dis, novas_timespec::fjd_tt, NOVAS_CIRS, novas_make_frame(), novas_sky_pos(), novas_v2z(), sky_pos::ra, and sky_pos::rv.

◆ novas_frame_lst()

double novas_frame_lst ( const novas_frame *restrict frame )

Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.

Parameters

frame Observer frame, defining the location and time of observation

Returns: [h] The LST for an Earth-bound observer [0.0–24.0), or NAN otherwise. If NAN is returned errno will indicate the type of error.

Since: 1.3

Author: Attila Kovacs

References NOVAS_AIRBORNE_OBSERVER, and NOVAS_OBSERVER_ON_EARTH.

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

If sys is NOVAS_TOD (true equator and equinox of date), the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C place() for that system. To obtain more precise TOD coordinates, set sys to NOVAS_CIRS here, and follow with cirs_to_tod() after.
As of SuperNOVAS v1.3, the returned velocity vector is a proper observer-based velocity measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with pseudo LSR-based measures being returned for catalog sources.

Parameters

	source	Pointer to a celestial source data structure that is observed. Catalog sources should have coordinates and properties in ICRS. You can use `transform_cat()` to convert catalog entries to ICRS as necessary.
	frame	Observer frame, defining the location and time of observation
	sys	The coordinate system in which to return positions and velocities.
[out]	pos	[AU] Calculated geometric position vector of the source relative to the observer location, in the designated coordinate system. It may be NULL if not required.
[out]	vel	[AU/day] The calculated velocity vector of the source relative to the observer in the designated coordinate system. It must be distinct from the pos output vector, and may be NULL if not required.

Returns: 0 if successful, or else -1 if any of the arguments is invalid, 50–70 error is 50 + error from light_time2().

See also: novas_geom_to_app(); novas_sky_pos(); novas_transform_vector(); place(); cirs_to_tod()

Since: 1.1

Author: Attila Kovacs

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

◆ novas_geom_to_app()

int novas_geom_to_app	(	const novas_frame *restrict	frame,
		const double *restrict	pos,
		enum novas_reference_system	sys,
		sky_pos *restrict	out
	)

Converts an geometric position in ICRS to an apparent position on sky, by applying appropriate corrections for aberration and gravitational deflection for the observer's frame. Unlike place() the output reports the distance calculated from the parallax for sidereal sources. The radial velocity of the output is set to NAN (if needed use novas_sky_pos() instead).

Parameters

	frame	The observer frame, defining the location and time of observation
	pos	[AU] Geometric position of source in ICRS coordinates
	sys	The coordinate system in which to return the apparent sky location
[out]	out	Pointer to the data structure which is populated with the calculated apparent location in the designated coordinate system. It may be the same pounter as the input position.

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

See also: novas_sky_pos(); novas_app_to_geom(); novas_app_to_hor(); novas_geom_posvel()

Since: 1.1

Author: Attila Kovacs

References grav_planets(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, novas_vlen(), and vector2radec().

◆ novas_get_debug_mode()

enum novas_debug_mode novas_get_debug_mode ( )

Returns the current, thread-local, mode for reporting errors encountered (and traces).

Returns: The current debug mode in the calling thread.

Since: 1.0

Author: Attila Kovacs

See also: novas_debug()

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

IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

	time	Pointer to the astronomical time specification data structure.
	timescale	The astronomical time scale in which the returned Julian Date is to be provided
[out]	ijd	[day] The integer part of the Julian date in the requested timescale. It may be NULL if not required.

Returns: [day] The fractional part of the Julian date in the requested timescale or NAN is the time argument is NULL (ijd will be set to -1 also).

See also: novas_set_split_time(); novas_get_time()

Since: 1.1

Author: Attila Kovacs

References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

◆ novas_get_time()

double novas_get_time	(	const novas_timespec *restrict	time,
		enum novas_timescale	timescale
	)

Returns the fractional Julian date of an astronomical time in the specified timescale. The returned time is accurate to a few μs (microsecond) due to the inherent precision of the double-precision result. For higher precision applications you may use novas_get_split_time() instead, which has an inherent accuracy at the picosecond level.

Parameters

time	Pointer to the astronomical time specification data structure.
timescale	The astronomical time scale in which the returned Julian Date is to be provided

Returns: [day] The Julian date in the requested timescale.

See also: novas_set_time(); novas_get_split_time()

Since: 1.1

Author: Attila Kovacs

References novas_get_split_time().

◆ novas_get_unix_time()

time_t novas_get_unix_time	(	const novas_timespec *restrict	time,
		long *restrict	nanos
	)

Returns the UNIX time for an astronomical time instant.

Parameters

	time	Pointer to the astronomical time specification data structure.
[out]	nanos	[ns] UTC sub-second component. It may be NULL if not required.

Returns: [s] The integer UNIX time, or -1 if the input time is NULL.

See also: novas_set_unix_time(); novas_get_time()

Since: 1.1

Author: Attila Kovacs

References novas_get_split_time(), and NOVAS_UTC.

◆ novas_h2e_offset()

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. Converting between local flat projections and spherical coordinates usually requires a WCS projection.

REFERENCES:

Calabretta, M.R., & Greisen, E.W., (2002), Astronomy & Astrophysics, 395, 1077-1122.

Parameters

	daz	[arcsec] Projected offset position in the azimuth direction. The projected offset between two azimuth positions at the same reference elevation is δAz = (Az2 - Az1) * cos(El₀).
	del	[arcsec] projected offset position in the elevation direction
	pa	[deg] Parallactic Angle
[out]	dra	[arcsec] Output offset position in the local true-of-date R.A. direction. It can be a pointer to one of the input coordinates, or NULL if not required.
[out]	ddec	[arcsec] Output offset position in the local true-of-date declination direction. It can be a pointer to one of the input coordinates, or NULL if not required.

Returns: 0

Since: 1.3

Author: Attila Kovacs

See also: novas_e2h_offset(); novas_hpa()

◆ 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 ".

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:

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

Parameters

hms	String specifying hours, minutes, and seconds, which correspond to a time between 0 and 24 h. Time in any range is permitted, but the minutes and seconds must be >=0 and <60.

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

Since: 1.3

Author: Attila Kovacs

See also: novas_str_hours(); novas_parse_hms(); novas_dms_degrees()

References novas_parse_hms().

◆ novas_hor_to_app()

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

Converts an observed azimuth and elevation coordinate to right ascension (R.A.) and declination coordinates expressed in the coordinate system of choice. The observer must be located on the surface of Earth, or else the call will return with an error. The caller may optionally supply a refraction model of choice to calculate an appropriate elevation angle that includes a refraction correction for Earth's atmosphere. If no such model is provided, the provided elevation value will be assumed to be an astrometric elevation without a refraction correction.

Parameters

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

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

See also: novas_app_to_hor(); novas_app_to_geom(); novas_standard_refraction(); novas_optical_refraction(); novas_radio_refraction()

Since: 1.1

Author: Attila Kovacs

References novas_timespec::fjd_tt, hor_to_itrs(), novas_timespec::ijd_tt, NOVAS_AIRBORNE_OBSERVER, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_J2000, NOVAS_MOD, NOVAS_OBSERVER_ON_EARTH, NOVAS_REFRACT_OBSERVED, NOVAS_TOD, spin(), and vector2radec().

◆ novas_hor_track()

int novas_hor_track	(	const object *restrict	source,
		const novas_frame *restrict	frame,
		RefractionModel	ref_model,
		novas_track *restrict	track
	)

Calculates horizontal tracking position and motion (first and second time derivatives) for the specified source in the given observing frame. The position and its derivatives are calculated via the more precise IAU2006 method, and CIRS, and then converted to local horizontal coordinates using the specified refraction model (if any).

Parameters

	source	Observed source
	frame	Observing frame, defining the observer location and astronomical time of observation.
	ref_model	Refraction model to use, or NULL for an unrefracted track.
[out]	track	Output tracking parameters to populate

Returns: 0 if successful, or else -1 if any of the pointer arguments are NULL, or else an error code from cio_ra() or from novas_sky_pos(), or from novas_app_hor().

Since: 1.3

Author: Attila Kovacs

See also: novas_equ_track(); novas_track_pos()

References cio_ra(), sky_pos::dec, sky_pos::dis, novas_timespec::fjd_tt, NOVAS_AIRBORNE_OBSERVER, novas_app_to_hor(), NOVAS_CIRS, novas_make_frame(), NOVAS_OBSERVER_ON_EARTH, novas_sky_pos(), NOVAS_TOD, novas_v2z(), sky_pos::ra, and sky_pos::rv.

◆ novas_hpa()

double novas_hpa	(	double	az,
		double	el,
		double	lat
	)

Returns the horizontal Parallactic Angle (PA) calculated for a gorizontal Az/El location of the sky. The PA is the angle between the local horizontal coordinate directions and the local true-of-date equatorial coordinate directions at the given location. The polar wobble is not included in the calculation.

The Parallactic Angle is sometimes referrred to as the Vertical Position Angle (VPA). Both define the same quantity.

Parameters

az	[deg] Azimuth angle
el	[deg] Elevation angle
lat	[deg] Geodetic latitude of observer

Returns: [deg] Parallactic Angle (PA). I.e., the clockwise position angle of the declination direction w.r.t. the elevation axis in the horizontal system. Same as the the clockwise position angle of the elevation direction w.r.t. the declination axis in the equatorial system.

Since: 1.3

Author: Attila Kovacs

See also: novas_epa(); novas_h2e_offset()

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

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

See also: novas_make_transform()

Since: 1.1

Author: Attila Kovacs

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:

The timestamp uses the conventional date of the time. That is Gregorian dates after the Gregorian calendar reform of 15 October 1582, and Julian/Roman dates prior to that.
B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

	time	Pointer to the astronomical time specification data structure.
[out]	dst	Output string buffer. At least 25 bytes are required for a complete timestamp with termination.
	maxlen	The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than `maxlen`, then it will be truncated to fit in the allotted space, including a termination character.

Returns: the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since: 1.3

Author: Attila Kovacs

See also: novas_timestamp(); novas_parse_time()

References novas_get_split_time(), and NOVAS_UTC.

◆ 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 1582. 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:

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

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 negative years, e.g. 1 B.C. as -1.
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 month or day components are out of range.

Since: 1.3

Author: Attila Kovacs

See also: novas_jd_to_date(); get_utc_to_tt(); get_ut1_to_tt(); tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

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

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:

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 negative values, e.g. -1 corresponds to 1 B.C. 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

Since: 1.3

Author: Attila Kovacs

See also: novas_jd_from_date(); get_utc_to_tt(); get_ut1_to_tt(); tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

◆ novas_los_to_xyz()

int novas_los_to_xyz	(	const double *	los,
		double	lon,
		double	lat,
		double *	xyz
	)

Converts a 3D line-of-sight vector (δφ, δθ δr) to a rectangular equatorial (δx, δy, δz) vector.

Parameters

	los	[arb.u.] Line-of-sight 3-vector (δφ, δθ δr).
	lon	[deg] Line-of-sight longitude.
	lat	[deg] Line-of-sight latitude.
[out]	xyz	[arb.u.] Output rectangular equatorial 3-vector (δx, δy, δz), in the same units as the input. It may be the same vector as the input.

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

Since: 1.3

Author: Attila Kovacs

See also: novas_xyz_to_los()

◆ novas_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:

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: make_cat_entry(); novas_ssb_to_lsr_vel()

References NOVAS_JD_J2000, precession(), and radec2vector().

◆ novas_make_frame()

int novas_make_frame	(	enum novas_accuracy	accuracy,
		const observer *	obs,
		const novas_timespec *	time,
		double	dx,
		double	dy,
		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.

Parameters

	accuracy	Accuracy requirement, NOVAS_FULL_ACCURACY (0) for the utmost precision or NOVAS_REDUCED_ACCURACY (1) if ~1 mas accuracy is sufficient.
	obs	Observer location
	time	Time of observation
	dx	[mas] Earth orientation parameter, polar offset in x.
	dy	[mas] Earth orientation parameter, polar offset in y.
[out]	frame	Pointer to the observing frame to configure.

Returns: 0 if successful, 10–40: error is 10 + the error from ephemeris(), 40–50: error is 40 + the error from geo_posvel(), 50–80: error is 50 + the error from sidereal_time(), 80–90 error is 80 + error from cio_location(), 90–100 error is 90 + error from cio_basis(). or else -1 if there was an error (errno will indicate the type of error).

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

Since: 1.1

Author: Attila Kovacs

References novas_frame::accuracy, novas_frame::deps0, novas_frame::dpsi0, novas_frame::dx, novas_frame::dy, e_tilt(), novas_frame::earth_pos, novas_frame::earth_vel, novas_frame::ee, ephemeris(), novas_frame::era, era(), EROT_GST, novas_timespec::fjd_tt, novas_frame::gst, novas_timespec::ijd_tt, novas_frame::mobl, NOVAS_BARYCENTER, novas_change_observer(), NOVAS_EARTH_INIT, novas_get_split_time(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_TRUE_EQUINOX, NOVAS_UT1, nutation_angles(), sidereal_time(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, tt2tdb(), novas_timespec::ut1_to_tt, and observer::where.

◆ novas_make_transform()

int novas_make_transform	(	const novas_frame *	frame,
		enum novas_reference_system	from_system,
		enum novas_reference_system	to_system,
		novas_transform *	transform
	)

Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

Parameters

	frame	Observer frame, defining the location and time of observation
	from_system	Original coordinate reference system
	to_system	New coordinate reference system
[out]	transform	Pointer to the transform data structure to populate.

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

See also: novas_transform_vector(); novas_transform_sky_pos(); novas_invert_transform(); novas_geom_posvel(); novas_app_to_geom()

Since: 1.1

Author: Attila Kovacs

References 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_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TOD, novas_frame::nutation, novas_frame::precession, and novas_transform::to_system.

◆ novas_moon_angle()

double novas_moon_angle	(	const object *restrict	source,
		const novas_frame *restrict	frame
	)

Returns the apparent angular distance of a source from the Moon from the observer's point of view.

Parameters

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

Returns: [deg] Apparent angular distance between the source 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().

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

◆ novas_object_sep()

double novas_object_sep	(	const object *	source1,
		const object *	source2,
		const novas_frame *restrict	frame
	)

Returns the angular separation of two objects from the observer's point of view. The calculated separation includes light-time corrections, aberration and gravitational deflection for both sources, and thus represents a precise observed separation between the two sources.

Parameters

source1	An observed source
source2	Another observed source
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: [deg] Apparent angular separation between the two observed sources from the observer's point-of-view.

Since: 1.3

Author: Attila Kovacs

See also: novas_sun_angle(); novas_moon_angle(); novas_sep()

References sky_pos::dec, sky_pos::dis, novas_equ_sep(), NOVAS_GCRS, novas_sky_pos(), and sky_pos::ra.

◆ novas_offset_time()

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

Increments the astrometric time by a given amount.

Parameters

	time	Original time specification
	seconds	[s] Seconds to add to the original
[out]	out	New incremented time specification. It may be the same as the input.

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

See also: novas_set_time(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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

◆ novas_optical_refraction()

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.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
loc	Pointer to structure defining the observer's location on earth, and local weather
type	Whether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el	[deg] Astrometric (unrefracted) source elevation

Returns: [arcsec] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).

See also: novas_app_to_hor(); novas_optical_refraction(); NOVAS_STANDARD_ATMOSPHERE(); refract(); refract_astro()

References NOVAS_WEATHER_AT_LOCATION.

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

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, or NULL if not required
[out]	vel	[AU/day] Output ICRS equatorial velocity vector, 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), or

See also: ephemeris(); novas_geom_posvel(); place(); make_orbital_object()

Author: Attila Kovacs

Since: 1.2

References novas_inv_max_iter, and TWOPI.

◆ novas_parse_date()

double novas_parse_date	(	const char *restrict	date,
		char **restrict	tail
	)

Parses a date/time string into a Julian date specification. Typically the date may be an ISO date specification, but with some added flexibility. The date must be YMD-type with full year, followed the month (numerical or name or 3-letter abbreviation), and the day. The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ;, or underscore _ or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else {+/-}HH[:[MM]] time zone specification.

For example:

 2025-01-26
 2025 January 26
 2025_Jan_26
 2025-01-26T19:33:08Z
 2025.01.26T19:33:08
 2025 1 26 19h33m28.113
 2025/1/26 19:33:28+02
 2025-01-26T19:33:28-0600
 2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

NOTES:

This function uses Gregorian dates since their introduction on 1582 October 15, and Julian/Roman datew before that, as was the convention of the time. I.e., the day before of the introduction of the Gregorian calendar reform is 1582 October 4.
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

	date	The date specification, possibly including time and timezone, in a standard format.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed time.

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_date_scale(); novas_parse_date_format(); novas_timescale_for_string(); novas_iso_timestamp(); novas_timestamp()

References NOVAS_ASTRONOMICAL_CALENDAR, novas_parse_date_format(), and NOVAS_YMD.

◆ novas_parse_date_format()

double novas_parse_date_format	(	enum novas_calendar_type	calendar,
		enum novas_date_format	format,
		const char *restrict	date,
		char **restrict	tail
	)

Parses a calndar date/time string, expressed in the specified type of calendar, into a Julian day (JD). The date must be composed of a full year (e.g. 2025), a month (numerical or name or 3-letter abbreviation, e.g. "01", "1", "January", or "Jan"), and a day (e.g. "08" or "8"). The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The components will be parsed in the specified order.

The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ; or underscore '_', or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else by a {+/-}HH[:[MM]] time zone specification.

For example, for format NOVAS_YMD, all of the following strings may specify the date:

 2025-01-26
 2025 January 26
 2025_Jan_26
 2025-01-26T19:33:08Z
 2025.01.26T19:33:08
 2025 1 26 19h33m28.113
 2025/1/26 19:33:28+02
 2025-01-26T19:33:28-0600
 2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

If your date format cannot be parsed with this function, you may parse it with your own function into year, month, day, and decimal hour-of-day components, and use julian_date() with those.

NOTES:

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

	calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
	format	Expected order of date components: NOVAS_YMD, NOVAS_DMY, or NOVAS_MDY.
	date	The date specification, possibly including time and timezone, in the specified standard format.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed time.

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_parse_date(); novas_timescale_for_string(); novas_iso_timestamp(); julian_date()

References novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DMY, novas_get_debug_mode(), novas_jd_from_date(), NOVAS_MDY, novas_parse_hms(), and NOVAS_YMD.

◆ novas_parse_degrees()

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.

The decimal representation may be followed by a unit designator: "d", "dg", "deg", "degree", or "degrees", which will be parsed case-insensitively also, if present.

Both DMS and decimal values may end with a compass direction: N, E, S, or W.

A few examples of angles that may be parsed:

 -179:59:59.999
 -179d 59m 59.999s
 179 59 59.999 S
 179 59 S
 -179.99999d
 -179.99999
 179.99999W
 179.99999 deg S

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 followed by the letter `d` immediately. And both the decimal and DMS representation may be ended with a compass direction marker, `N`, `E`, `S`, or `W`. See more in `novas_parse_dms()` on acceptable DMS specifications.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed angle.

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_str_degrees(); novas_parse_dms(); novas_parse_hours()

trailing E compass, handled below

Punctuation after first character

References novas_debug(), NOVAS_DEBUG_OFF, novas_get_debug_mode(), and novas_parse_dms().

◆ novas_parse_dms()

double novas_parse_dms	(	const char *restrict	dms,
		char **restrict	tail
	)

Parses the decimal degrees for a DMS string specification. The degree, (arc)minute, and (arc)second components may be separated by spaces, tabs, colons :, underscore _, 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 a double quote ". Finally, the last component may additionally be followed by a standalone upper-case letter 'N', 'E', 'S', or 'W' signifying a compass direction.

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__S
 179 59 S

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.

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.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed time.

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_dms_degrees(); novas_parse_degrees(); novas_parse_hms()

◆ novas_parse_hms()

double novas_parse_hms	(	const char *restrict	hms,
		char **restrict	tail
	)

Parses the decimal hours for a HMS string specification. The hour, minute, and second components may be separated by spaces, tabs, colons :, underscore _, 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 ".

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

 23:59:59.999
 23h 59m 59.999
 23h59'59.999
 23 59 59.999
 23 59

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.

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.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed time.

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_hms_hours(); novas_parse_hours(); novas_parse_dms()

◆ novas_parse_hours()

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.

The decimal representation may be followed by a unit designator: "h", "hr", "hrs", "hour", or "hours", which will be parsed case-insensitively also, if present.

A few examples of angles that may be parsed:

 23:59:59.999
 23h 59m 59.999s
 23h59'59.999
 23 59 59.999
 23.999999h
 23.999999 hours
 23.999999

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_hms()` on acceptable HMS input specifications.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed angle.

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_str_hours(); novas_parse_hms(); novas_parse_degrees()

References novas_debug(), NOVAS_DEBUG_OFF, novas_get_debug_mode(), and novas_parse_hms().

◆ novas_parse_timescale()

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). The following timescale values are recognised: "UTC", "UT", "UT0", "UT1", "GMT", "TAI", "GPS", "TT", "ET", "TCG", "TCB", "TDB".

Parameters

	str	String specifying an astronomical timescale. Leading white spaces will be skipped over.
[out]	tail	(optional) If not NULL it will be set to the next character in the string after the parsed timescale specification.

Returns: The SuperNOVAS timescale constant (<=0), or else -1 if the string was NULL, empty, or could not be matched to a timescale value (errno will be set to EINVAL also).

Since: 1.3

Author: Attila Kovacs

See also: novas_timescale_for_string(); novas_set_time(); novas_set_split_time(); novas_print_timescale()

References novas_timescale_for_string(), and NOVAS_UTC.

◆ novas_planet_for_name()

enum novas_planet novas_planet_for_name ( const char *restrict name )

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

Parameters

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

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

Author: Attila Kovacs

Since: 1.2

See also: make_planet()

References NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, and NOVAS_SSB.

◆ novas_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.

◆ novas_radio_refraction()

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). It uses the weather parameters defined for the location, including humidity. As such make sure the weather data is fully defined, and that the humidity was explicitly set after calling make_on_surface().

Adapted from FORTAN code provided by Berman & Rockwell 1976.

REFERENCES:

Berman, Allan L., and Rockwell, Stephen T. (1976), NASA JPL Technical Report 32-1601

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
loc	Pointer to structure defining the observer's location on earth, and local weather. Make sure all weather values, including humidity (added in v1.1), are fully populated.
type	Whether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el	[deg] source elevation of the specified type.

Returns: [deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).

See also: novas_optical_refraction(); make_on_surface(); on_surface

References on_surface::humidity, novas_inv_refract(), novas_radio_refraction(), NOVAS_REFRACT_ASTROMETRIC, NOVAS_REFRACT_OBSERVED, on_surface::pressure, and on_surface::temperature.

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

The current implementation is not suitable for calculating the nearest successive rise times for near-Earth objects, at or within the geostationary orbit.
This function calculates the time when the center (not the limb!) of the source rises above the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

el	[deg] Elevation angle.
source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.
ref_model	Refraction model, or NULL to calculate unrefracted rise time.

Returns: [day] UTC-based Julian date at which the object rises above the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour period.

Since: 1.3

Author: Attila Kovacs

See also: novas_sets_below(); novas_transit_time()

◆ novas_sep()

double novas_sep	(	double	lon1,
		double	lat1,
		double	lon2,
		double	lat2
	)

Returns the angular separation of two locations on a sphere.

Parameters

lon1	[deg] longitude of first location
lat1	[deg] latitude of first location
lon2	[deg] longitude of second location
lat2	[deg] latitude of second location

Returns: [deg] the angular separation of the two locations.

Since: 1.3

Author: Attila Kovacs

See also: novas_equ_sep(); novas_sun_angle(); novas_moon_angle()

◆ novas_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:

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

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

IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[out]	time	Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns: 0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

See also: novas_set_time(); novas_set_unix_time(); novas_get_split_time(); novas_timescale_for_string()

Since: 1.1

Author: Attila Kovacs

References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, and tt2tdb().

◆ 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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[out]	time	Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns: 0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

See also: novas_set_split_time(); novas_set_unix_time(); novas_get_time(); novas_timescale_for_string()

Since: 1.1

Author: Attila Kovacs

References novas_set_split_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() (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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[out]	time	Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns: 0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

See also: novas_set_time(); novas_get_unix_time(); clock_gettime(); struct timespec

Since: 1.1

Author: Attila Kovacs

References novas_set_split_time(), and NOVAS_UTC.

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

The current implementation is not suitable for calculating the nearest successive set times for near-Earth objects, at or within the geostationary orbit.
This function calculates the time when the center (not the limb!) of the source sets below the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

el	[deg] Elevation angle.
source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.
ref_model	Refraction model, or NULL to calculate unrefracted setting time.

Returns: [day] UTC-based Julian date at which the object sets below the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour day..

Since: 1.3

Author: Attila Kovacs

See also: novas_rises_above(); novas_transit_time()

◆ 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 soure), 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:

If sys is NOVAS_TOD (true equator and equinox of date), the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C place() for that system. To obtain more precise TOD coordinates, set sys to NOVAS_CIRS here, and follow with cirs_to_tod() / cirs_to_app_ra() on the out->r_hat / out->ra respectively after (or you can use just convert one of the quantities, and use radec2vector() or vector2radec() to get the other even faster).
As of SuperNOVAS v1.3, the returned radial velocity component is a proper observer-based spectroscopic measure. In prior releases, and in NOVAS C 3.1, this was inconsistent, with LSR-based measures being returned for catalog sources.

Parameters

	object	Pointer to a celestial object data structure that is observed. Catalog sources should have coordinates and properties in ICRS. You can use `transform_cat()` to convert catalog entries to ICRS as necessary.
	frame	The observer frame, defining the location and time of observation
	sys	The coordinate system in which to return the apparent sky location
[out]	out	Pointer to the data structure which is populated with the calculated apparent location in the designated coordinate system.

Returns: 0 if successful, 50–70 error is 50 + error from light_time2(), 70–80 error is 70 + error from grav_def(), or else -1 (errno will indicate the type of error).

See also: novas_geom_to_app(); novas_app_to_hor(); place(); cirs_to_tod(); cirs_to_app_ra()

Since: 1.1

Author: Attila Kovacs

References grav_planets(), NOVAS_CATALOG_OBJECT, NOVAS_FULL_ACCURACY, novas_geom_posvel(), novas_geom_to_app(), NOVAS_ICRS, NOVAS_REDUCED_ACCURACY, novas_vlen(), rad_vel2(), and object::type.

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

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: make_cat_entry(); novas_lsr_to_ssb_vel()

References NOVAS_JD_J2000, precession(), and radec2vector().

◆ novas_standard_refraction()

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.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
loc	Pointer to structure defining the observer's location on earth, and local weather
type	Whether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el	[deg] Astrometric (unrefracted) source elevation

Returns: [deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).

See also: novas_app_to_hor(); novas_optical_refraction(); NOVAS_STANDARD_ATMOSPHERE(); refract(); refract_astro()

References NOVAS_STANDARD_ATMOSPHERE.

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

References novas_parse_degrees().

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

References novas_parse_hours().

◆ novas_sun_angle()

double novas_sun_angle	(	const object *restrict	source,
		const novas_frame *restrict	frame
	)

Returns the apparent angular distance of a source from the Sun from the observer's point of view.

Parameters

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

Returns: [deg] the apparent angular distance between the source 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.

◆ novas_timescale_for_string()

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). The following values are recognised: "UTC", "UT", "UT0", "UT1", "GMT", "TAI", "GPS", "TT", "ET", "TCG", "TCB", "TDB".

Parameters

str	String specifying an astronomical timescale

Returns: The SuperNOVAS timescale constant (<=0), or else -1 if the string was NULL, empty, or could not be matched to a timescale value (errno will be set to EINVAL also).

Since: 1.3

Author: Attila Kovacs

See also: novas_parse_timescale(); novas_set_time(); novas_set_split_time(); novas_print_timescale()

References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

◆ novas_timestamp()

int novas_timestamp	(	const novas_timespec *restrict	time,
		enum novas_timescale	scale,
		char *restrict	dst,
		int	maxlen
	)

Prints a timestamp to millisecond precision in the specified timescale to the specified string buffer. E.g.:

 2025-01-26T21:32:49.701 TAI

NOTES:

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.
B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

	time	Pointer to the astronomical time specification data structure.
	scale	The timescale to use.
[out]	dst	Output string buffer. At least 28 bytes are required for a complete timestamp with termination.
	maxlen	The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than `maxlen`, then it will be truncated to fit in the allotted space, including a termination character.

Returns: the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since: 1.3

Author: Attila Kovacs

See also: novas_iso_timestamp()

References novas_get_split_time(), and novas_print_timescale().

◆ 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 and redshift for a source, given the available tracking position and derivatives. Using 'tracks' to project positions can be much faster than the repeated full recalculation of the source position over some short 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 on minute timescales, whereas depending on the type of source equatorial tracks can be precise for up to days.

Parameters

	track	Tracking position and motion (first and second derivatives)
	time	Astrometric time of observation
[out]	lon	[deg] projected observed Eastward longitude in tracking coordinate system
[out]	lat	[deg] projected observed latitude in tracking coordinate system
[out]	dist	[AU] projected apparent distance to source from observer
[out]	z	projected observed redshift

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

See also: novas_make_transform(); novas_transform_vector()

Since: 1.1

Author: Attila Kovacs

References sky_pos::dec, sky_pos::r_hat, 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).

See also: novas_make_transform(); novas_transform_skypos()

Since: 1.1

Author: Attila Kovacs

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

The current implementation is not suitable for calculating the nearest successive transit times for near-Earth objects, at or within the geostationary orbit.

Parameters

source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: [day] UTC-based Julian date at which the object transits the local meridian next after the specified date, or NAN if either input pointer is NULL.

Since: 1.3

Author: Attila Kovacs

See also: novas_rises_above(); novas_sets_below()

◆ novas_v2z()

double novas_v2z ( double vel )

Converts a radial recession velocity to a redshift value (z = δf / f_rest). It is based on the relativistic formula:

 1 + z = sqrt((1 + β) / (1 - β))

where β = v / c.

Parameters

vel	[km/s] velocity (i.e. rate) of recession.

Returns: the corresponding redshift value (δλ / λ_rest), or NAN if the input velocity is invalid (i.e., it exceeds the speed of light).

See also: novas_z2v(); novas_z_add()

Author: Attila Kovacs

Since: 1.2

References NOVAS_KMS.

◆ novas_xyz_to_los()

int novas_xyz_to_los	(	const double *	xyz,
		double	lon,
		double	lat,
		double *	los
	)

Converts a 3D rectangular equatorial (δx, δy, δz) vector to a polar (δφ, δθ δr) vector along a line-of-sight.

Parameters

	xyz	[arb.u.] Rectangular equatorial 3-vector (δx, δy, δz).
	lon	[deg] Line-of-sight longitude.
	lat	[deg] Line-of-sight latitude.
[out]	los	[arb.u.] Output line-of-sight 3-vector (δφ, δθ δr), in the same units as the input. It may be the same vector as the input.

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

Since: 1.3

Author: Attila Kovacs

See also: novas_los_to_xyz()

◆ novas_xyz_to_uvw()

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.

x,y,z are Cartesian coordinates w.r.t the Greenwich meridian. The directions are x: long=0, lat=0; y: long=90, lat=0; z: lat=90.

u,v,w are Cartesian coordinates (u,v) along the local equatorial R.A. and declination directions as seen from a direction on the sky (w).

Parameters

	xyz	[arb.u.] Absolute or relative x,y,z coordinates (double[3]).
	ha	[h] Hourangle (LST - RA) i.e., the difference between the Local (apparent) Sidereal Time and the apparent (true-of-date) Right Ascension of observed source.
	dec	[deg] Apparent (true-of-date) declination of source
[out]	uvw	[arb.u.] Converted u,v,w coordinates (double[3]) in same units as xyz. It may be the same vector as the input.

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

Since: 1.3

Author: Attila Kovacs

References novas_xyz_to_los().

◆ novas_z2v()

double novas_z2v ( double z )

==========================================================================

Converts a redshift value (z = δf / f_rest) to a radial velocity (i.e. rate) of recession. It is based on the relativistic formula:

 1 + z = sqrt((1 + β) / (1 - β))

where β = v / c.

Parameters

z	the redshift value (δλ / λ_rest).

Returns: [km/s] Corresponding velocity of recession, or NAN if the input redshift is invalid, i.e. z <= -1).

See also: novas_v2z(); redshift_vrad()

Author: Attila Kovacs

Since: 1.2

References NOVAS_KMS.

◆ novas_z_add()

double novas_z_add	(	double	z1,
		double	z2
	)

Compounds two redshift corrections, e.g. to apply (or undo) a series gravitational redshift corrections and/or corrections for a moving observer. It's effectively using (1 + z) = (1 + z1) * (1 + z2).

Parameters

z1	One of the redshift values
z2	The other redshift value

Returns: The compound redshift value, ot NAN if either input redshift is invalid (errno will be set to EINVAL).

See also: grav_redshift(); redshift_vrad(); unredshift_vrad()

Since: 1.2

Author: Attila Kovacs

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

See also: novas_z_add()

Since: 1.2

Author: Attila Kovacs

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

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_TOD

References e_tilt(), and NUTATE_MEAN_TO_TRUE.

◆ nutation_angles()

int nutation_angles	(	double	t,
		enum novas_accuracy	accuracy,
		double *restrict	dpsi,
		double *restrict	deps
	)

Returns the values for nutation in longitude and nutation in obliquity for a given TDB Julian date. The nutation model selected depends upon the input value of 'accuracy'. See notes below for important details.

This function selects the nutation model depending first upon the input value of 'accuracy'. If 'accuracy' is NOVAS_FULL_ACCURACY (0), the IAU 2000A nutation model is used. Otherwise the model set by set_nutation_lp_provider() is used, or else the default nu2000k().

See the prologs of the nutation functions in file 'nutation.c' for details concerning the models.

REFERENCES:

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

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: set_nutation_lp_provider(); nutation(); iau2000b(); nu2000k(); cio_basis(); NOVAS_CIRS; NOVAS_JD_J2000

References get_nutation_lp_provider(), iau2000a(), and NOVAS_FULL_ACCURACY.

◆ 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 graviational 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, components in AU.
	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. have positions and velocities calculated successfully. 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.

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

See also: place()

References ephemeris(), geo_posvel(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_OBSERVER_PLACES, and NOVAS_SOLAR_SYSTEM_OBSERVER.

◆ 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 a specific near-Earth origin.

While coord_sys defines the celestial pole (i.e. equator) orientation of the coordinate system, 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:

This version fixes a NOVAS C 3.1 issue that velocities and solar-system distances were not antedated for light-travel time.
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.
If sys is NOVAS_TOD (true equator and equinox of date), the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C place() for that system. To obtain more precise TOD coordinates, set sys to NOVAS_CIRS here, and follow with cirs_to_tod() after.
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:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	source	Pointer to a celestrial object data structure. Catalog objects musy have ICRS coordinates. You can use `transform_cat()` to convert other catalog systems to ICRS as necessary.
	location	The observer location, relative to which the output positions and velocities are to be calculated
	ut1_to_tt	[s] TT - UT1 time difference. Used only when 'location->where' is NOVAS_OBSERVER_ON_EARTH (1) or NOVAS_OBSERVER_IN_EARTH_ORBIT (2).
	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: novas_geom_posvel(); novas_sky_pos(); place_star(); place_icrs(); place_gcrs(); place_cirs(); radec_star(); radec_planet(); cel_pole(); get_ut1_to_tt()

References aberration(), bary2obs(), d_light(), ephemeris(), 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_J2000, NOVAS_MOD, NOVAS_REDUCED_ACCURACY, NOVAS_REFERENCE_SYSTEMS, NOVAS_SUN_INIT, NOVAS_TOD, novas_vlen(), obs_planets(), obs_posvel(), proper_motion(), rad_vel2(), starvectors(), tt2tdb(), and vector2radec().

◆ place_cirs()

int place_cirs	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos
	)

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.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated CIRS position data

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

See also: place_tod(); place_gcrs()

Since: 1.0

Author: Attila Kovacs

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
	)

Computes the Geocentric Celestial Reference System (GCRS) position of a source (as 'seen' from the geocenter) at the given time of observation. Unlike place_icrs(), this includes aberration for the moving frame of the geocenter as well as gravitational deflections calculated for a virtual observer located at the geocenter. See place() for more information.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated GCRS position data

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

See also: place_icrs(); place_cirs(); place_tod(); virtual_star(); virtual_planet()

Since: 1.0

Author: Attila Kovacs

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
	)

Computes the International Celestial Reference System (ICRS) position of a source. (from the geocenter). Unlike place_gcrs(), this version does not include aberration or gravitational deflection corrections.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated geocentric ICRS position data (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().

See also: place_gcrs(); place_cirs(); place_tod(); mean_star()

Since: 1.0

Author: Attila Kovacs

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
	)

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.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated CIRS position data

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

See also: place_cirs(); place_gcrs(); app_star(); app_planet()

Since: 1.1

Author: Attila Kovacs

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
	)

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.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated CIRS position data

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

See also: place_cirs(); place_gcrs(); app_star(); app_planet()

Since: 1.1

Author: Attila Kovacs

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, referenced to dynamical equator at date 'jd_tt', given its catalog mean place, proper motion, parallax, and radial velocity. See place() for more information.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: get_ut1_to_tt()

Author: Attila Kovacs

Since: 1.0

References NOVAS_CATALOG_OBJECT, place(), object::star, and object::type.

◆ place_tod()

int place_tod	(	double	jd_tt,
		const object *restrict	source,
		enum novas_accuracy	accuracy,
		sky_pos *restrict	pos
	)

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.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date of observation.
	source	Catalog source or solar_system body.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	pos	Structure to populate with the calculated CIRS position data

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

See also: place_cirs(); place_gcrs(); app_star(); app_planet()

Since: 1.0

Author: Attila Kovacs

References NOVAS_TOD, and place().

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

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(); ee_ct(); NOVAS_JD_J2000

Since: 1.0

Author: Attila Kovacs

References NOVAS_EARTH, NOVAS_JUPITER, NOVAS_MARS, NOVAS_MERCURY, NOVAS_NEPTUNE, NOVAS_SATURN, NOVAS_URANUS, NOVAS_VENUS, and TWOPI.

◆ 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. Unlike the original NOVAS routine, this routine works for any pairing of the time arguments.

This function calculates precession for the old (pre IAU 2000) methodology. Its main use for NOVAS users is to allow converting older catalog coordinates e.g. to J2000 coordinates, which then can be converted to the now standard ICRS system via frame_tie().

NOTE:

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.

REFERENCES:

Explanatory Supplement To The Astronomical Almanac, pp. 103-104.
Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.
Hilton, J. L. et al. (2006), IAU WG report, Celest. Mech., 94, pp. 351-367.

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(); frame_tie(); novas_epoch(); tt2tdb(); cio_basis(); NOVAS_TOD; NOVAS_JD_J2000; NOVAS_JD_B1950; NOVAS_JD_B1900

References precession().

◆ proper_motion()

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

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

REFERENCES:

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

Parameters

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

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

See also: transform_cat()

◆ 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 here defined as the radial velocity measure (z) times the speed of light. For 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.

All the input arguments are BCRS quantities, 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:

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

Lindegren & Dravins (2003), Astronomy & Astrophysics 401, 1185-1201.
Unlike NOVAS C, this function will return a radial velocity for the Sun that is gravitationally referenced to the Sun's photosphere. (NOVAS C returns the radial velocity for a massless Sun)

Parameters

	source	Celestial object observed
	pos_src	[AU\|*] Geometric position vector of object with respect to observer. For solar system sources it should be corrected for light-time. For non-solar-system objects, the position vector defines a direction only, with arbitrary magnitude.
	vel_src	[AU/day] Velocity vector of object with respect to solar system barycenter.
	vel_obs	[AU/day] Velocity vector of observer with respect to solar system barycenter.
	d_obs_geo	[AU] Distance from observer to geocenter, or <=0.0 if gravitational blueshifting due to Earth potential around observer can be ignored.
	d_obs_sun	[AU] Distance from observer to Sun, or <=0.0 if gravitational bluehifting due to Solar potential around observer can be ignored.
	d_src_sun	[AU] Distance from object to Sun, or <=0.0 if gravitational redshifting due to Solar potential around source can be ignored.
[out]	rv	[km/s] The observed radial velocity measure times the speed of light, 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().

◆ 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 different directions in which light is emitted vs in which it detected, e.g. when it is gravitationally deflected.

Radial velocity is here defined as the radial velocity measure (z) times the speed of light. For 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.

All the input arguments are BCRS quantities, 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:

This function is called by place() and novas_sky_pos() to calculate radial velocities along with the apparent position of the source.
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:

Lindegren & Dravins (2003), Astronomy & Astrophysics 401, 1185-1201.

Parameters

source	Celestial object observed
pos_emit	[AU\|*] position vector of object with respect to observer in the direction that light was emitted from the source. For solar system sources it should be corrected for light-time. For non-solar-system objects, the position vector defines a direction only, with arbitrary magnitude.
vel_src	[AU/day] Velocity vector of object with respect to solar system barycenter.
pos_det	[AU\|*] apparent position vector of source, as seen by the observer. It may be the same vector as `pos_emit`, in which case the routine behaves like the original NOVAS_C rad_vel().
vel_obs	[AU/day] Velocity vector of observer with respect to solar system barycenter.
d_obs_geo	[AU] Distance from observer to geocenter, or <=0.0 if gravitational blueshifting due to Earth potential around observer can be ignored.
d_obs_sun	[AU] Distance from observer to Sun, or <=0.0 if gravitational bluehifting due to Solar potential around observer can be ignored.
d_src_sun	[AU] Distance from object to Sun, or <=0.0 if gravitational redshifting due to Solar potential around source can be ignored. Additionally, a value <0 will also skip corrections for light originating at the surface of the observed major solar-system body.

Returns: [km/s] The observed radial velocity measure times the speed of light, 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).

See also: rad_vel(); place(); novas_sky_pos(); novas_v2z()

Since: 1.1

Author: Attila Kovacs

References cat_entry::dec, 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(), cat_entry::parallax, cat_entry::ra, and cat_entry::radialvelocity.

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

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

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: radec_star()

Since: 1.0

Author: Attila Kovacs

References sky_pos::dec, sky_pos::dis, NOVAS_EPHEM_OBJECT, NOVAS_ORBITAL_OBJECT, NOVAS_PLANET, place(), sky_pos::ra, sky_pos::rv, and SKY_POS_INIT.

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

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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 code from place_star().

See also: radec_planet()

Since: 1.0

Author: Attila Kovacs

References sky_pos::dec, place_star(), sky_pos::ra, sky_pos::rv, and SKY_POS_INIT.

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

See also: unredshift_vrad(); grav_redshift(); novas_z_add()

Since: 1.2

Author: Attila Kovacs

References novas_v2z(), and novas_z2v().

◆ refract()

double refract	(	const on_surface *restrict	location,
		enum novas_refraction_model	option,
		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:

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:

Explanatory Supplement to the Astronomical Almanac, p. 144.
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.
option	NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2) if to use the weather values contained in the 'location' data structure.
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_STANDARD_ATMOSPHERE, and NOVAS_WEATHER_AT_LOCATION.

◆ refract_astro()

double refract_astro	(	const on_surface *restrict	location,
		enum novas_refraction_model	option,
		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:

Explanatory Supplement to the Astronomical Almanac, p. 144.
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.
option	NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2) if to use the weather values contained in the 'location' data structure.
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, and refract().

◆ set_cio_locator_file()

int set_cio_locator_file ( const char *restrict filename )

Sets the CIO interpolaton data file to use to interpolate CIO locations vs the GCRS. You can specify either the original CIO_RA.TXT file included in the distribution (preferred since v1.1), or else a platform-specific binary data file compiled from it via the cio_file utility (the old way).

Parameters

filename Path (preferably absolute path) CIO_RA.TXT or else to the binary cio_ra.bin data.

Returns: 0 if successful, or else -1 if the specified file does not exists or we have no permission to read it.

See also: cio_location(); gcrs_to_cirs()

Since: 1.0

Author: Attila Kovacs

◆ set_nutation_lp_provider()

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

Parameters

func	the new function to use for low-precision IAU 2000 nutation calculations

Returns: 0 if successful, or -1 if the input argument is NULL

See also: get_nutation_lp_provider(); nutation_angles()

Since: 1.0

Author: Attila Kovacs

◆ sidereal_time()

short sidereal_time	(	double	jd_ut1_high,
		double	jd_ut1_low,
		double	ut1_to_tt,
		enum novas_equinox_type	gst_type,
		enum novas_earth_rotation_measure	erot,
		enum novas_accuracy	accuracy,
		double *restrict	gst
	)

Computes the Greenwich sidereal time, either mean or apparent, at the specified Julian date. The Julian date can be broken into two parts if convenient, but for the highest precision, set 'jd_high' to be the integral part of the Julian date, and set 'jd_low' to be the fractional part.

NOTES:

Contains fix for known sidereal time units bug.

REFERENCES:

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. (You can leave it at zero if 'jd_high' specified the date with sufficient precision)
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	gst_type	NOVAS_MEAN_EQUINOX (0) or NOVAS_TRUE_EQUINOX (1), depending on whether wanting mean or apparent GST, respectively.
	erot	EROT_ERA (0) or EROT_GST (1), depending on whether to use GST relative to equinox of date (pre IAU 2006) or ERA relative to the CIO (IAU 2006 standard).
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	gst	[h] Greenwich (mean or apparent) sidereal time, in hours [0:24]. (In case the returned error code is >1 the gst value will be set to NAN.)

Returns: 0 if successful, or -1 if the 'gst' argument is NULL, 1 if 'accuracy' is invalid 2 if 'method' is invalid, or else 10–30 with 10 + the error from cio_location().

See also: era(); tod_to_itrs(); itrs_to_tod(); cel_pole(); get_ut1_to_tt()

References cio_basis(), cio_location(), e_tilt(), era(), EROT_ERA, EROT_GST, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, tod_to_gcrs(), and tt2tdb().

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

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.

◆ starvectors()

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

Converts angular quantities for stars to vectors.

NOTES:

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

REFERENCES:

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

Parameters

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

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

See also: make_cat_entry()

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

◆ tdb2tt()

int tdb2tt	(	double	jd_tdb,
		double *restrict	jd_tt,
		double *restrict	secdiff
	)

Computes the Terrestrial Time (TT) or Terrestrial Dynamical Time (TDT) Julian date corresponding to a Barycentric Dynamical Time (TDB) Julian date.

Expression used in this function is a truncated form of a longer and more precise series given in the first reference. The result is good to about 10 microseconds.

Deprecated:: Use the less computationally intensive an more accurate tt2tdb() routine instead.

REFERENCES:

Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

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 if successful, or -1 if the tt_jd pointer argument is NULL.

See also: tt2tdb()

◆ ter2cel()

short ter2cel	(	double	jd_ut1_high,
		double	jd_ut1_low,
		double	ut1_to_tt,
		enum novas_earth_rotation_measure	erot,
		enum novas_accuracy	accuracy,
		enum novas_equatorial_class	class,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a vector from the terrestrial to the celestial system. Specifically, it transforms a vector in the ITRS (rotating earth-fixed system) to the True of Date (TOD), CIRS, or GCRS (a local space-fixed system) by applying rotations for polar motion, Earth rotation (for TOD); and nutation, precession, and the dynamical-to-GCRS frame tie (for GCRS).

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

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

Deprecated:: This function can be confusing to use due to the output coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

REFERENCES:

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

Parameters

	jd_ut1_high	[day] High-order part of UT1 Julian date.
	jd_ut1_low	[day] Low-order part of UT1 Julian date.
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	erot	EROT_ERA (0) or EROT_GST (1), depending on whether to use GST relative to equinox of date (pre IAU 2006) or ERA relative to the CIO (IAU 2006 standard) as the Earth rotation measure. The main effect of this option is that it selects the output coordinate system as CIRS or TOD if the output coordinate class is NOVAS_DYNAMICAL_CLASS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	class	Output coordinate class NOVAS_REFERENCE_CLASS (0, or any value other than 1) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the output coordinates are to be in the GCRS, and the latter if they are to be in CIRS or TOD (the 'erot' parameter selects which dynamical system to use for the output.)
	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) in the normal case where 'option' is NOVAS_GCRS (0).
[out]	out	Position vector, equatorial rectangular coordinates in the specified output system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST). It may be the same vector as the input.

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, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also: itrs_to_cirs(); cirs_to_gcrs(); itrs_to_tod(); tod_to_j2000(); frame_tie(); cel2ter()

References cirs_to_gcrs(), era(), EROT_ERA, EROT_GST, NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, sidereal_time(), spin(), tod_to_gcrs(), tt2tdb(), wobble(), and WOBBLE_ITRS_TO_PEF.

◆ terra()

int terra	(	const on_surface *restrict	location,
		double	lst,
		double *restrict	pos,
		double *restrict	vel
	)

==========================================================================

Computes the position and velocity vectors of a terrestrial observer with respect to the center of the Earth.

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:

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

Parameters

	location	Location of observer in Earth's rotating frame
	lst	[h] Local apparent sidereal time at reference meridian in hours.
[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: make_on_surface(); geo_posvel(); sidereal_time()

References NOVAS_KM.

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

NOTES:

The accuracy of the output CIRS coordinates depends on how the input TOD coordinates were obtained. If TOD was calculated via the old (pre IAU 2006) method, using the Lieske et al. 1997 nutation model, then the limited accuracy of that model will affect the resulting coordinates. This is the case for the SuperNOVAS functions novas_geom_posvel() and novas_sky_pos() also, when called with NOVAS_TOD as the system, as well as all legacy NOVAS C functions that produce TOD coordinates.

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_location(), or else 20 + the error from cio_basis().

See also: cirs_to_tod(); app_to_cirs_ra(); tod_to_gcrs(); tod_to_j2000(); tod_to_itrs()

Since: 1.1

Author: Attila Kovacs

References cio_ra(), and spin().

◆ 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 Geocentric Celestial Reference System(GCRS)

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

See also: j2000_to_tod(); tod_to_cirs(); tod_to_j2000(); tod_to_itrs()

Since: 1.2

Author: Attila Kovacs

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

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

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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().

See also: cirs_to_itrs(); itrs_to_tod(); j2000_to_tod(); tod_to_gcrs(); tod_to_j2000(); tod_to_cirs()

Since: 1.0

Author: Attila Kovacs

References cel2ter(), EROT_GST, and NOVAS_DYNAMICAL_CLASS.

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

See also: j2000_to_tod(); j2000_to_gcrs(); tod_to_gcrs(); tod_to_cirs(); tod_to_itrs()

Since: 1.0

Author: Attila Kovacs

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

◆ topo_planet()

short topo_planet	(	double	jd_tt,
		const object *restrict	ss_body,
		double	ut1_to_tt,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec,
		double *restrict	dis
	)

Computes the topocentric apparent place of a solar system body at the specified time. This is the same as calling place() for the body for the same observer location and NOVAS_TOD as the reference system, except the different set of return values used.

NOTES:

This call uses the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C function.

REFERENCES:

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

Deprecated:: Using place() with system NOVAS_CIRS is now preferred for topocentric calculations, especially when high precision is required. However, you will have to follow the IAU 2000 method consistently to produce equivalent calculations throughout.

Parameters

	jd_tt	[day] Terretrial Time (TT) based Julian date.
	ss_body	Pointer to structure containing the body designation for the solar system body.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	position	Position of the observer
	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. (It may be NULL if not required)
[out]	dec	[deg] Topocentric apparent declination in degrees referred to the true equator and equinox of date. (It may be NULL if not required)
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU (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 'where' in structure 'location' is invalid, or 10 + the error code from place().

See also: app_planet(); local_planet(); topo_planet(); virtual_planet(); astro_star(); get_ut1_to_tt()

References make_observer(), NOVAS_OBSERVER_ON_EARTH, NOVAS_TOD, and radec_planet().

◆ topo_star()

short topo_star	(	double	jd_tt,
		double	ut1_to_tt,
		const cat_entry *restrict	star,
		const on_surface *restrict	position,
		enum novas_accuracy	accuracy,
		double *restrict	ra,
		double *restrict	dec
	)

Computes the topocentric (True of Date; TOD) apparent place of a star at date 'jd_tt', given its 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 observer location and NOVAS_TOD for an object that specifies the star.

NOTES:

This call uses the less precise old (pre IAU 2006) method is used, with the Lieske et al. 1977 nutation model, matching the behavior of the original NOVAS C function.

REFERENCES:

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

Deprecated:: Using place() with system NOVAS_CIRS is now preferred for topocentric calculations, especially when high precision is required. However, you will have to follow the IAU 2000 method consistently to produce equivalent calculations throughout.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ut1_to_tt	[s] Difference TT-UT1 at 'jd_tt', in seconds of time.
	star	Pointer to catalog entry structure containing catalog data for the object in the ICRS.
	position	Position of the observer
	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'. (It may be NULL if not required)
[out]	dec	[deg] Topocentric declination in degrees, 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 20 + the error code from place_star().

See also: place_star(); app_star(); local_star(); topo_star(); virtual_star(); astro_planet(); get_ut1_to_tt()

References make_observer(), NOVAS_OBSERVER_ON_EARTH, NOVAS_TOD, and radec_star().

◆ transform_cat()

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

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

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

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

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

Parameters

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

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

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

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

◆ transform_hip()

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

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

Parameters

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

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

See also: make_cat_entry(); NOVAS_JD_HIP

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

◆ tt2tdb()

double tt2tdb ( double jd_tt )

Returns the TDB - TT time difference in seconds for a given TT date.

Note, as of version 1.1, it uses the same calculation as the more precise original tdb2tt(). It thus has an acuracy of about 10 μs vs around 30 μs with the simpler formula from the references below.

REFERENCES

Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

jd_tt [day] Terrestrial Time (TT) based Julian date

Returns: [s] TDB - TT time difference.

See also: tdb2tt()

Since: 1.0

Author: Attila Kovacs

References tdb2tt().

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

See also: redshift_vrad(); grav_redshift()

Since: 1.2

Author: Attila Kovacs

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:

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

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

Computes the virtual place of a solar system body, referenced to the GCRS. This is the same as calling place_gcrs() for the body, except the different set of return values used.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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 right ascension in hours, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Virtual declination in degrees, referred to the GCRS (it may be NULL if not required).
[out]	dis	[AU] True distance from Earth to the body at 'jd_tt' in AU (can 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 code from place().

See also: place_gcrs(); app_planet(); astro_planet(); local_planet(); topo_planet(); app_star()

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
	)

Computes the virtual place of a star, 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.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
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 right ascension in hours, referred to the GCRS (it may be NULL if not required).
[out]	dec	[deg] Virtual declination in degrees, 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()

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

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Lambert & Bizouard (2002), Astronomy and Astrophysics 394, 317-321.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	direction	WOBBLE_ITRS_TO_PEF (0) or WOBBLE_PEF_TO_ITRS (nonzero)
	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	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 output vector argument is NULL.

See also: cel_pole(); cirs_to_itrs(); tod_to_itrs(); place(); sidereal_time(); e_tilt(); NOVAS_FULL_ACCURACY

References WOBBLE_ITRS_TO_PEF.

Variable Documentation

◆ grav_bodies_full_accuracy

int grav_bodies_full_accuracy

extern

Current set of gravitating bodies to use for deflection calculations in full accuracy mode. Each bit signifies whether a given body is to be accounted for as a gravitating body that bends light, such as the bit (1 << NOVAS_JUPITER) indicates whether or not Jupiter is considered as a deflecting body. You should also be sure that you provide ephemeris data for bodies that are designated for the deflection calculation.

See also: grav_def(); grav_planets(); DEFAULT_GRAV_BODIES_FULL_ACCURACY; set_ephem_provider_hp()

Since: 1.1

◆ grav_bodies_reduced_accuracy

int grav_bodies_reduced_accuracy

extern

Current set of gravitating bodies to use for deflection calculations in reduced accuracy mode. Each bit signifies whether a given body is to be accounted for as a gravitating body that bends light, such as the bit (1 << NOVAS_JUPITER) indicates whether or not Jupiter is considered as a deflecting body. You should also be sure that you provide ephemeris data for bodies that are designated for the deflection calculation.

See also: grav_def(); grav_planets(); DEFAULT_GRAV_BODIES_REDUCED_ACCURACY; set_ephem_provider()

Since: 1.1

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BARYC

◆ CAT_ENTRY_INIT

◆ DE405_AU

◆ DEFAULT_CIO_LOCATOR_FILE

◆ DEFAULT_GRAV_BODIES_FULL_ACCURACY

◆ DEFAULT_GRAV_BODIES_REDUCED_ACCURACY

◆ HELIOC

◆ IN_SPACE_INIT

◆ NOVAS_ARCMIN

◆ NOVAS_ARCSEC

◆ NOVAS_AU

◆ NOVAS_DAY

◆ NOVAS_DEGREE

◆ NOVAS_EARTH_INIT

◆ NOVAS_EMB_INIT

◆ NOVAS_EQUATOR_TYPES

◆ NOVAS_HOURANGLE

◆ NOVAS_JD_START_GREGORIAN

◆ NOVAS_JUPITER_INIT

◆ NOVAS_KM

◆ NOVAS_KMS

◆ NOVAS_MARS_INIT

◆ NOVAS_MERCURY_INIT

◆ NOVAS_MOON_INIT

◆ NOVAS_NEPTUNE_INIT

◆ NOVAS_OBJECT_TYPES

◆ NOVAS_OBSERVER_PLACES

◆ NOVAS_ORBIT_INIT

◆ NOVAS_ORBITAL_SYSTEM_INIT

◆ NOVAS_ORIGIN_TYPES

◆ NOVAS_PLANET_GRAV_Z_INIT

◆ NOVAS_PLANET_INIT

◆ NOVAS_PLANET_NAMES_INIT

◆ NOVAS_PLANETS

◆ NOVAS_PLUTO_BARYCENTER_INIT

◆ NOVAS_PLUTO_INIT

◆ NOVAS_REFERENCE_SYSTEMS

◆ NOVAS_RMASS_INIT

◆ NOVAS_SATURN_INIT

◆ NOVAS_SOLAR_CONSTANT

◆ NOVAS_SOLAR_RADIUS

◆ NOVAS_SSB_INIT

◆ NOVAS_SUN_INIT

◆ NOVAS_SYSTEM_B1950

◆ NOVAS_SYSTEM_FK4

◆ NOVAS_SYSTEM_FK5

◆ NOVAS_SYSTEM_HIP

◆ NOVAS_SYSTEM_ICRS

◆ NOVAS_SYSTEM_J2000

◆ NOVAS_TIMESCALES

◆ NOVAS_TRANSFORM_TYPES

◆ NOVAS_URANUS_INIT

◆ NOVAS_VENUS_INIT

◆ ON_SURFACE_INIT

◆ ON_SURFACE_LOC

◆ SKY_POS_INIT

◆ SUPERNOVAS_VERSION_STRING

Typedef Documentation

◆ RefractionModel

Enumeration Type Documentation

◆ novas_accuracy

◆ novas_calendar_type

◆ novas_cio_location_type

◆ novas_date_format

◆ novas_debug_mode

◆ novas_dynamical_type

◆ novas_earth_rotation_measure

◆ novas_equator_type

◆ novas_equatorial_class

◆ novas_equinox_type

◆ novas_frametie_direction

◆ novas_nutation_direction