v1.1.1-rc2

This is the 2nd release candidate for the upcoming v1.1.1 bug fix release, expected around 1 November 2024.

Fixed

• #55: Relativistic corrections to radial velocity were still not applied correctly. The revised calculation now uses
  the actual relativistic velocity differential between the source and observer to apply the appropriate time
  dilation factor, and applies graviational corrections for Sun and Earth consistently at source and observer alike.

• #64: NOVAS_TAI_TO_TT definition had wrong decimal in last place, thus was 3 ms off from what it should have been.
  (thanks to @kiranshila)

• #68: readeph_dummy() dummy implenetation in readeph0.c called non existing error handler function.

Changed

• #59: For major planets (and Sun and Moon) rad_vel(), rad_vel2(), place(), and novas_sky_pos() will include
  gravitational corrections to radial velocity for light originating at the surface, and observed near Earth or else
  at a large distance away. The corrections can be skipped for rad_vel() / rad_vel2() by setting d_src_sun
  negative.

• #55: Use relativistic formulae to add/difference velocities (i.e. change velocity reference frame).

• #60: Moved SuperNOVAS-only functions to a separate super.c module to alleviate the bloating of novas.c, which
  can still be used as a self-contained, standalone, NOVAS C replacement for legacy applications if need be.

• #62: Improve debug mode error tracing when NAN values are returned, so the trace indicates NAN rather than a bogus
  integer before.

• #66: Various tweaks for C/C++ best practices (by @kiranshila)

• #67: Use accuracy argument in tod_to_cirs(). (thanks to @kiranshila)

• #68: Various improvements to debug error tracing.

• Slight tweakes to Makefile, and .mk snipplets, with added make configurability.

v1.1.0

Feature release. Introducing a more efficient and elegant approach to position and velocity calculations using observer frames; versatile handling of astronomical timescales; and support for further observer locations, coordinate reference systems, and atmospheric refraction models. The release also fixes a number of bugs, of varying severity, which affected prior SuperNOVAS (and NOVAS C) releases.

Fixed

• #29: Fix portability to non-Intel platforms. Previously, SuperNOVAS used char for storing small integer coefficients, assuming char was signed. However, on some platforms like ARM and PowerPC char is unsigned, which broke calculations badly. As of now, we use the explicit platform independent signed int8_t storage type for these coefficients.

• #38: gcrs_to_j2000() transformed in the wrong direction in v1.0.

• #39: tod_to_itrs() used wrong Earth rotation measure (NOVAS_ERA instead of NOVAS_GST) in v1.0.

• #45: cel2ter() invalid output in v1.0 with CIRS input coordinates (erot = EROT_ERA and class = NOVAS_DYNAMICAL_CLASS) if output vector was distinct from input vector. Affects cirs_to_itrs() also.

• #36: tt2tdb() Had a wrong scaling in sinusoidal period in v1.0, resulting in an error of up to +/- 1.7 ms.

• #37: gcrs_to_cirs() did not handle well if input and output vectors were the same in v1.0.

• #28: Division by zero bug in d_light() (since NOVAS C 3.1) if the first position argument is the ephemeris reference position (e.g. the Sun for solsys3.c). The bug affects for example grav_def(), where it effectively results in the gravitational deflection due to the Sun being skipped. See Issue #28.

• #41: grav_def() gravitating body position antedated somewhat incorrectly (in v1.0) when observed source is a Solar-system object between the observer and the gravitating body. The resulting positional error is typically small at below 10 uas.

• #50: The NOVAS C 3.1 implementation of rad_vel() applied relativistic corrections for a moving observer conditional on applying relativistic gravitational corrections (for Sun and/or Earth potential) for the observer. However, it seems more reasonable that the corrections for a moving observer should be applied always and independently of the (optional) gravitational corrections.

• #34: place() radial velocities were not quite correct in prior SuperNOVAS releases. The radial velocity calculation now precedes aberration, since the radial velocity that is observed is in the geometric direction towards the source (unaffected by aberration). As for gravitational deflection, the geometric direction is the correct direction in which light was emitted from the source for sidereal objects. For Solar system sources we now reverse trace the deflected light to calculate the direction in which it was emitted from the source. As such, the radial velocities calculated should now be precise under all conditions. The typical errors of the old calculations were up to tens of m/s because of aberration, and a few m/s due to the wrong gravitational deflection calculation.

• #24: Bungled definition of SUPERNOVAS_VERSION_STRING in novas.h in v1.0.

• Bungled definition of NOVAS_OBSERVER_PLACES in novas.h in v1.0.

Added

• #33: New observing-frame based approach for calculations (frames.c). A novas_frame object uniquely defines both the place and time of observation, with a set of pre-calculated transformations and constants. Once the frame is defined it can be used very efficiently to calculate positions for multiple celestial objects with minimum additional computational cost. The frames API is also more elegant and more versatile than the low-level NOVAS C approach for performing the same kind of calculations. And, frames are inherently thread-safe since post-creation their internal state is never modified during the calculations. The following new functions were added: novas_make_frame(), novas_change_observer(), novas_geom_posvel(), novas_geom_to_app(), novas_sky_pos(), novas_app_to_hor(), novas_app_to_geom(), novas_hor_to_app(), novas_make_transform(), novas_invert_transform(), novas_transform_vector(), and novas_transform_sky_pos().

• #33: New novas_timespec structure for the self-contained definition of precise astronomical time (timescale.c). You can set the time via novas_set_time() or novas_set_split_time() to a JD date in the timescale of choice (UTC, UT1, GPS, TAI, TT, TCG, TDB, or TCB), or to a UNIX time with novas_set_unix_time(). Once set, you can obtain an expression of that time in any timescale of choice via novas_get_time(), novas_get_split_time() or novas_get_unix_time(). And, you can create a new time specification by incrementing an existing one, using novas_increment_time(), or measure time differences via novas_diff_time(), novas_diff_tcg(), or novas_diff_tcb().

• Added novas_planet_bundle structure to handle planet positions and velocities more elegantly (e.g. for gravitational deflection calculations).

• #32: Added grav_undef() to undo gravitational bending of the observed light to obtain geometric positions from observed ones.

• Added obs_posvel() to calculate the observer position and velocity relative to the Solar System Barycenter (SSB).

• Added obs_planets() to calculate apparent planet positions (relative to observer) and velocities (w.r.t. SSB).

• Added new observer locations NOVAS_AIRBORNE_OBSERVER for an observer moving relative to the surface of Earth e.g. in an aircraft or balloon based telescope platform, and NOVAS_SOLAR_SYSTEM_OBSERVER for spacecraft orbiting the Sun. Both of these use the observer.near_earth strcture to define (positions and) velocities as appropriate. Hence the 'near_earth name is a bit misleading, but sticks for back compatibility.

• Added coordinate reference systems NOVAS_MOD (Mean of Date) which includes precession by not nutation and NOVAS_J2000 for the J2000 dynamical reference system.

• New observer locations NOVAS_AIRBORNE_OBSERVER and NOVAS_SOLAR_SYSTEM_OBSERVER, and corresponding make_airborne_observer() and make_solar_system_observer() functions. Airborne observers have an Earth-fixed momentary location, defined by longitude, latitude, and altitude, the same way as for a stationary observer on Earth, but are moving relative to the surface, such as in an aircraft or balloon based observatory. Solar-system observers are similar to observers in Earth-orbit but their momentary position and velocity is defined relative to the Solar System Barycenter (SSB), instead of the geocenter.

• Added humidity field to on_surface structure, e.g. for refraction calculations at radio wavelengths. The make_on_surface() function will set humidity to 0.0, but the user can set the field appropriately afterwards.

• New set of built-in refraction models to use with the frame-based novas_app_to_hor() / novas_hor_to_app() functions. The models novas_standard_refraction() and novas_optical_refraction() implement the same refraction model as refract() in NOVAS C 3.1, with NOVAS_STANDARD_ATMOSPHERE and NOVAS_WEATHER_AT_LOCATION respectively, including the reversed direction provided by refract_astro(). The user may supply their own custom refraction also, and may make use of the generic reversal function novas_inv_refract() to calculate refraction in the reverse direction (observer vs astrometric elevations) as needed.

• Added radio refraction model novas_radio_refraction() based on the formulae by Berman & Rockwell 1976.

• Added cirs_to_tod() and tod_to_cirs() functions for efficient tranformation between True of Date (TOD) and Celestial Intermediate Reference System (CIRS), and vice versa.

• Added make_cat_object() function to create a NOVAS celestial object structure from existing cat_entry data.

• Added rad_vel2() to calculate radial velocities precisely in the presense of gravitational deflection i.e., when the direction in which light was emitted is different from the direction it is detected by the observer. This new function is now used by both place() and novas_sky_pos().

• make help to provide a brief list and explanation of the available build targets. (Thanks to @teuben for suggesting this.)

• Added GitHub CI regression testing for non-x86 platforms: armv7, aarch64, riscv64, ppc64le. Thus, we should avoid misphaps, like the platform specific bug Issue #29, in the future.

Changed

• #42: cio_array() can now parse the original ASCII CIO locator data file (data/CIO_RA.TXT) efficiently also, thus no longer requiring a platform-specific binary translation via the cio_file tool.

• #51: The NOVAS C implementation of rad_vel() has ignored this redshifting when the Sun was being observed. From now on, we shall gravitationally reference radial velocities when observing the Sun to its photosphere.

• cio_file tool parses interval from header rather than the less precise differencing of the first two record timestamps. This leads to cio_array() being more accurately centered on matching date entries, e.g. J2000.

• grav_def() estimation of light time to where light passes nearest to gravitating body is improved by starting with the body position already antedated for light-time for the gravitating mass. The change typically improves the grativational deflection calculations at the few uas level.

• grav_def() is simplified. It no longer uses the location type argument. Instead it will skip deflections due to any body, if the observer is within ~1500 km of its center.

• place() now returns an error 3 if and only if the observer is at (or very close, to within ~1.5m) of the observed Solar-system object.

• Improved precision of some calculations, like era(), `...

v1.0.1

Bug fix release

Known Issues

This release is affected by many of the same issues as the original 1.0 release, except what is explicitly listed below as fixed for this version.

Fixed

• #15 -- cirs_to_itrs(), itrs_to_cirs(), tod_to_itrs(), and itrs_to_tod() all had a unit conversion bug in using the ut1_to_tt argument [s] when converting TT-based Julian date to UT1-based JD [day] internally. (thanks to @hannorein)
• #17 -- Fixes to included examples.c

Added

• Added cirs_to_app_ra() and app_to_cirs_ra() for convenience to convert between right ascensions measured from the CIO (for CIRS) vs measured from the true equinox of date, on the same true equator of date.

Changed

• #18 -- Changed definition of NOVAS_AU to the IAU definition of exactly 149597870.7 km (a <10 m change from the previously defined value, which has been renamed to DE405_AU). (thanks to @hannorein)
• Various corrections and changes to documentation.

v1.0

[1.0.0] - 2024-03-01

This is the initial release of the SuperNOVAS library. Changes are indicated w.r.t. the upstream NOVAS C 3.1 library
from which SuperNOVAS is forked from.

Known Issues

• #15 -- cirs_to_itrs(), itrs_to_cirs(), tod_to_itrs(), and itrs_to_tod() all have a unit conversion bug in using the ut1_to_tt argument [s] when converting TT-based Julian date to UT1-based JD [day] internally. A fix for this bug is included in the main branch and the v1.0.1 bug fix release.
• #28 -- d_light() divide by zero if called with pos argument is a zero vector (e.g. Sun or SSB, depending on the solar-system calculator type). Fix available on the main branch and will be included in the v1.0.2 bug fix release.
• #29 -- [CRITICAL] All calculations in this release involving the IAU2000 nutation or ee_ct() yield invalid results on non-Intel x86 platforms, such as ARMv7 or PowerPC, due to a different signedness of the char integer type on these platforms. Fix available on the main branch and will be included in the v1.0.2 bug fix release.
• #35 -- tt2tdb() had the wrong scaling in the period, resulting in an error up to ~3.4 ms. A fix will be included in the v1.1.0 release and is available on the main branch.
• #38 -- gcrs_to_j2000() applied transformation in the wrong direction, resulting in an error up to 44 mas when place() was called with NOVAS_TOD as the desired output system (1). A fix will be included in the v1.1.0 release and is available on the main branch.
• #39 -- tod_to_itrs() used the wrong Earth rotation measure (NOVAS_ERA instead of NOVAS_GST). A fix will be included in the v1.1.0 release and is available on the main branch.
• #41: grav_def() gravitating body position antedated somewhat incorrectly (in v1.0) when observed source is a Solar-system object between the observer and the gravitating body. The resulting positional error is typically small at below 10 uas. A fix will be included in the v1.1.0 release and is available on the main branch.
• #45: cel2ter() invalid output with CIRS input coordinates (erot = EROT_ERA and class = NOVAS_DYNAMICAL_CLASS) if output vector was distinct from input vector. Affects prior SuperNOVAS releases. A fix will be included in the v1.1.0 release and is available on the main branch.

Fixed

• Fixes the sidereal_time bug, whereby the sidereal_time() function had
  an incorrect unit cast. This is a known issue of NOVAS C 3.1.

• Some remainder calculations in NOVAS C 3.1 used the result from fmod() unchecked, which led to the wrong results
  when the numerator was negative. This affected the calculation of the mean anomaly in solsys3.c (line 261) and
  the fundamental arguments calculated in fund_args() and ee_ct() for dates prior to J2000. Less critically, it
  also was the reason cal_date() did not work for negative JD values.

• Fixes antedating velocities and distances for light travel time in ephemeris(). When getting positions and
  velocities for Solar-system sources, it is important to use the values from the time light originated from the
  observed body rather than at the time that light arrives to the observer. This correction was done properly for
  positions, but not for velocities or distances, resulting in incorrect observed radial velocities or apparent
  distances being reported for spectroscopic observations or for angular-physical size conversions.

• Fixes bug in ira_equinox() which may return the result for the wrong type of equinox (mean vs. true) if the the
  equinox argument was changing from 1 to 0, and back to 1 again with the date being held the same. This affected
  routines downstream also, such as sidereal_time().

• Fixes accuracy switching bug in cio_basis(), cio_location(), ecl2equ(), equ2ecl_vec(), ecl2equ_vec(),
  geo_posvel(), place(), and sidereal_time(). All these functions returned a cached value for the other
  accuracy if the other input parameters are the same as a prior call, except the accuracy.

• Fixes multiple bugs related to using cached values in cio_basis() with alternating CIO location reference
  systems.

• Fixes bug in equ2ecl_vec() and ecl2equ_vec() whereby a query with coord_sys = 2 (GCRS) has overwritten the
  cached mean obliquity value for coord_sys = 0 (mean equinox of date). As a result, a subsequent call with
  coord_sys = 0 and the same date as before would return the results GCRS coordinates instead of the requested mean
  equinox of date coordinates.

• Fixes aberration() returning NaN vectors if the ve argument is 0. It now returns the unmodified input vector
  appropriately instead.

• Fixes unpopulated az output value in equ2hor() at zenith. While any azimuth is acceptable really, it results in
  unpredictable behavior. Hence, we set az to 0.0 for zenith to be consistent.

• Fixes potential string overflows and eliminates associated compiler warnings.

• Fixes the ephem_close bug, whereby ephem_close() in
  eph_manager.c did not reset the EPHFILE pointer to NULL. This is a known issue of NOVAS C 3.1.

• Supports calculations in parallel threads by making cached results thread-local.

Added

• New debug mode and error traces. Simply call novas_debug(NOVAS_DEBUG_ON) or novas_debug(NOVAS_DEBUG_EXTRA)
  to enable. When enabled, any error conditions (such as NULL pointer arguments, or invalid input values etc.) will
  be reported to the standard error, complete with call tracing within the SuperNOVAS library, s.t. users can have
  a better idea of what exactly did not go to plan (and where). The debug messages can be disabled by passing
  NOVAS_DEBUF_OFF (0) as the argument to the same call.

• Added Doxygen markup of source code and header.

• Added Makefile for GNU make.

• Added continuous integration on GitHub, including regression testing, static analysis, and doxygen validation.

• Added an number of precompiler constants and enums in novas.h to promote consistent usage and easier to read
  code.

• New runtime configurability:

  • The planet position calculator function used by ephemeris() can be set at runtime via set_planet_provider(),
    and set_planet_provider_hp() (for high precision calculations). Similarly, if planet_ephem_provider() or
    planet_ephem_provider_hp() (defined in solsys-ephem.c) are set as the planet calculator functions, then
    set_ephem_provider() can set the user-specified function to use with these to actually read ephemeris data
    (e.g. from a JPL ephemeris file).

  • If CIO locations vs GSRS are important to the user, the user may call set_cio_locator_file() at runtime to
    specify the location of the binary CIO interpolation table (e.g. cio_ra.bin) to use, even if the library was
    compiled with the different default CIO locator path.

  • The default low-precision nutation calculator nu2000k() can be replaced by another suitable IAU 2006 nutation
    approximation via set_nutation_lp_provider(). For example, the user may want to use the iau2000b() model
    instead or some custom algorithm instead.

• New intutitive XYZ coordinate conversion functions:

  • for GCRS - CIRS - ITRS (IAU 2000 standard): gcrs_to_cirs(), cirs_to_itrs(), and itrs_to_cirs(),
    cirs_to_gcrs().
  • for GCRS - J2000 - TOD - ITRS (old methodology): gcrs_to_j2000(), j2000_to_tod(), tod_to_itrs(), and
    itrs_to_tod(), tod_to_j2000(), j2000_to_gcrs().

• New itrs_to_hor() and hor_to_itrs() functions to convert Earth-fixed ITRS coordinates to astrometric azimuth
  and elevation or back. Whereas tod_to_itrs() followed by itrs_to_hor() is effectively a just a more explicit
  2-step version of the existing equ2hor() for converting from TOD to to local horizontal (old methodology), the
  cirs_to_itrs() followed by itrs_to_hor() does the same from CIRS (new IAU standard methodology), and had no
  prior equivalent in NOVAS C 3.1.

• New ecl2equ() for converting ecliptic coordinates to equatorial, complementing existing equ2ecl().

• New gal2equ() for converting galactic coordinates to ICRS equatorial, complementing existing equ2gal().

• New refract_astro() complements the existing refract() but takes an unrefracted (astrometric) zenith angle as
  its argument.

• New convenience functions to wrap place() for simpler specific use: place_star(), place_icrs(),
  place_gcrs(), place_cirs(), and place_tod().

• New radec_star() and radec_planet() as the common point for existing functions such as astro_star()
local_star(), virtual_planet(), topo_planet() etc.

• New time conversion utilities tt2tdb(), get_utc_to_tt(), and get_ut1_to_tt() make it simpler to convert
  between UTC, UT1, TT, and TDB time scales, and to supply ut1_to_tt arguments to place() or topocentric
  calculations.

• Co-existing solarsystem() variants. It is possible to use the different solarsystem() implementations
  provided by solsys1.c, solsys2.c, solsys3.c and/or solsys-ephem.c side-by-side, as they define their
  functionalities with distinct, non-conflicting names, e.g. earth_sun_calc() vs planet_jplint() vs
  planet_eph_manager vs planet_ephem_provider(). See the section on
  Building and installation further above on including a selection of these in your library
  build.)

• New novas_case_sensitive(int) to enable (or disable) case-sensitive processing of object names. (By default NOVAS
  object names were converted t...