v1.1.0

[attipaci]

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

Fixed

• Invalid results on some non-Intel platforms (e.g. ARM, PowerPC) #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.

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

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

• Bug in cel2ter() with CIRS input #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.

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

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

• d_light() bug when called with zero position #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 d_light() bug when called with zero position #28.

• Frame-based gravitational deflections #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.

• rad_vel() does not always include relativistic corrections for moving observer #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.

• rad_vel() Solar potential when observing the Sun in NOVAS C 3.1 #51: In the NOVAS C 3.1 implementation of rad_vel(), the Solar gravitational potential was ignored when calculating radial velocities for the Sun. Typically 'observing the Sun' means looking at its photosphere. As the light travels away from the Sun's photosphere towards the observer, it is redshifted. 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.

• Unaberrated radial velocities. #34: place() radial velocities were not quite correct in NOVAS C 3.1, and 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.

• SUPERNOVAS_VERSION_STRING ill defined in novas.h #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

• New high-level, elegant, and efficient observer frame approach #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().

• New high-level, elegant, and efficient observer frame approach #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).

• grav_undef() to gravitationally unbend observed light #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 Invalid results on some non-Intel platforms (e.g. ARM, PowerPC) #29, in the future.

Changed

• Process ASCII CIO locator data also. #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.

• 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(), fund_args(), and planet_lon() by being more careful about the order in which terms are accumulated and combined, resulting in a small improvement on the few uas (micro-arcsecond) level.

• vector2radec(): ra or dec arguments may now be NULL if not required.

• tt2tdb() Now uses the same, slightly more precise series as the original NOVAS C tdb2tt().

• rad_vel() You can use negative values for the distances to skip particular gravitational corrections to the radial velocity measure. The value 0.0 also continues to have the same effect as before, except if the observed source is the Sun. Then d_src_sun being 0.0 takes on a different meaning than before: rather than skipping gravitational redshift corrections for the Solar potential, we will now assume that 0.0 means observing the Sun, and will apply gravitational corrections for light originating at its photosphere.

• PSI_COR and EPS_COR made globally visible again, thus improving NOVAS C 3.1 compatibility.

• Convergent inverse calculations now use the novas_inv_max_iter variable declared in novas.c to specify the maximum number of iterations before inverse functions return with an error (with errno set to ECANCELED). Users may adjust this limit, if they prefer some other maximum value.

• Adjusted regression testing to treat nan and -nan effectively the same. They both represent an equally invalid result regardless of the sign.

• The default make target is now distro. It's similar to the deprecated api target from before except that it skips building static libraries and cio_ra.bin.

• make now generates .so shared libraries with SONAME set to lib<name>.so.1 where the .1 indicates that it is major version 1 of the ABI. All 1.x.x releases are expected to be ABI compatible with earlier releases.

• lib/*.so files are now just symlinks to the actual versioned libraries lib/*.so.1. This conforms more closely to what Linux distros expect.

• Default make skips local-dox target unless doxygen is available (either in the default PATH or else specified via the DOXYGEN variable, e.g. in config.mk). This way the default build does not have unexpected dependencies. (see Issue Default build 'dox' target conditional on doxygen being present #22, thanks to @teuben).

• make can be configured without editing config.mk simply by setting the appropriate shell variables (the same ones as in config.mk) prior to invoking make. Standard CC, CPPFLAGS, CFLAGS and LDFLAGS will also be used if defined externally.

• make shared now also builds lib/libsolsys1.so.1 and lib/libsolsys2.so.1 shared libraries that can be used by programs that need solsys1 (via eph_manager) or solsys2 (via jplint) functionality.

• make solsys now generates only the solarsystem() implementation objects that are external (not built in).

• Eliminate unchecked return value compiler warnings from cio_file (used typically at build time only to generate cio_ra.bin).

• jplint.f is moved to examples/ since it provides only a default implementation that typically needs to be tweaked for the particualr JPL PLEPH library one intends to use.

• Doxygen tag file renamed to supernovas.tag for consistency.

• Initialize test variables for reproducibility

---

This discussion was created from the release v1.1.0.