v1.5.0

[attipaci]

Feature release. Some new functions, enhanced precision, improved portability (including Windows and Android), C++ compatibility, and documentation.

Fixed

• Tracking through the poles. #259: Fix novas_track_pos() tracking across / near the poles.

• NOVAS_JD_B1900 definition was MJD date instead of JD date.

• Fix the length of a Besselian year (used for parsing Besselian epochs).

• gcrs2equ(): propagate error if converting to TOD and the accuracy is invalid.

• NOVAS_VERSION_STRING definition in novas.h.

• Pedantic enum type casting for function parameters and enums, to improve C++ compatibility.

• Small fixes to error tracing in frames.c.

Added

• Clean up sidereal time calculations. #209: Added novas_gmst() and novas_gast() functions to calculate Greenwich Mean and Apparent (respectively) Sidereal Times for a given UT1 date. The new functions are meant to provide a cleaner, simpler alternative the old NOVAS C sidereal_time().

• Diurnal EOP corrections for ocean tides and librations #215: New functions novas_diurnal_eop(), novas_diurnal_ocean_tides() and novas_diurnal_libration() to calculate corrections to the Earth orientation parameters published by IERS, to include the effect of libration and ocean tides. Such corrections are necessary if needing or using ITRS / TIRS coordinates with accuracy below the milli-arcsecond (mas) level.

• ITRF realizations / transformations. #217: New functions novas_itrf_transform() and novas_itrf_transform_eop() to enable transforming gecocentric xyz station coordinates, or Earth orientation parameters (EOP), between different ITRF realizations (e.g. ITRF2000 to ITRF2014). The implementation is based on Chapter 4 of the IERS Conventions 2010.

• ITRF realizations / transformations. #217: New functions novas_geodetic_to_cartesian() and novas_cartesian_to_geodetic() to convert between geocentric xyz station coordinates and geodetic (longitude, latitude, altitude) coordinates on the reference ellipsoid of choice, and vice versa. The latter function is adapted from the IERS GCONV2.F routine.

• Expand Makefile build to support MacOS #221: Now supporting Mac OS X builds, which are different from the standard UNIX build, via GNU make also (in collaboration with @kiranshila).

• Add CMake build tooling #222: CMake build support, e.g for Mac OS X or Windows builds also, with further tweaks in Improved CMake build support #228, CMake Runtime and Development components #229, Simpler CMake shared vs static libs build  #230, CMake support for legacy solsys plugins #234, cmake: No additional compiler options by default #235... (in collaboration with @kiranshila).

• Differential clock rate of observer #223: New functions novas_clock_skew() / novas_mean_clock_skew() to calculate the instantaneous or averaged (for Earth-bound observers) incremental rate, respectively, at which an observer's clock ticks faster than an astronomical timescale. All reference timescales, except UT1, are supported (see also Consolidate novas_clock_skew() #232 and Mean vs instantaneous clock skews #233).

• Define catalog sources step-by-step #239: New step-by-step approach to populate astrometric data for catalog sources, complementing the one-step make_cat_entry(). Start with novas_init_cat_entry() specifying the name and the R.A. / Dec coordinates, and then add more information as needed: set radial velocities with novas_set_ssb_vel() / novas_set_lsr_vel() / novas_set_redshift(); set parallax or distance (if any) with novas_set_parallax() or novas_set_distance(); set proper motion (if any) with novas_set_proper_motion(); or add catalog information with novas_set_catalog().

• Add novas_set_current_time() #243: Added novas_set_current_time() to set astrometric time based on the current system clock UNIX time. The new function makes a common use case more accessible, but you should make sure the system clock is well synchronized to a time reference (preferably a local one) for accuracy.

• Add novas_set_str_time() for convenience. #244: Added novas_set_str_time() for convenience. It is the same as using novas_parse_date() followed by novas_set_time() with error propagation in-between.

• New site/observer initializers with default mean weather parameters. #245: New make_itrf_site(), make_gps_site(), make_xyz_site(), make_itrf_observer(), make_gps_observer(), make_observer_at_site() to facilitate the creation of sites / observers with GPS, ITRF or geocentric Cartesian (xyz) site coordinates. All of the above will also initialize default weather parameters for the location, based on simple global models of pressure scale height, annualized mean temperatures, and typical humidity values for the altitude.

• New site/observer initializers with default mean weather parameters. #245: New novas_set_default_weather() to initialize default weather parameters for the location, based on simple global models of pressure scale height, annualized mean temperatures, and typical humidity values for the altitude.

• Add novas_itrf_transform_site() and novas_geodetic_transform_site() #246: New novas_geodetic_transform_site() and novas_itrf_transform_site() convenience functions to make it simpler to change the reference ellipsoid or the ITRF realization of an on_surface data structure, respectively.

Removed

• Generate CIO locator data as needed. #250: No longer including CIO_RA.TXT (now unused) in the distribution.

• Don't build legacy solsys going forward #252: Some build configuration options have been removed, such as the GNU make BUILTIN_SOLSYS1, BUILTIN_SOLSYS2, BUILTIN_SOLSYS3, BUILTIN_SOLSYS_EPHEM, DEFAULT_SOLSYS, and DEFAULT_READEPH configuration options, or the CMake BUILD_SOLSYS1 / BUILD_SOLSYS2 options.

Changed

• Wean off CIO locator file internally. #208: cio_location() now always returns the CIO's right ascension relative to the true equinox of date (on the same true equator of date).

• Clean up sidereal time calculations. #209: novas_make_frame() calculates gst and gcrs_to_cirs fields faster, using the already available frame quantities and thus eliminating duplicate calculations.

• Faster nutations #210: Speed up iau2000a() and iau2000b() nutations by restricting the range of multiples that are iterated over.

• Faster, simpler ee_ct() #212: Speed up ee_ct() by restricting the range of multiples that are iterated over. Also reduced accuracy now uses the same series, only with fewer terms.

• Pending changes for v1.5.0 #213: Rename a couple of source modules (system.c to transform.c, and coords.c to system.c).

• Deprecate cio_basis() #214: Reworked GCRS-CIRS transforms without cio_basis() (IERS method 2).

• ITRF realizations / transformations. #217: Changed terra() to use GRS80 reference ellipsoid insread of the IERS 2003 ellipsoid. ITRF uses the GRS80 ellipsoid. The change restores the original NOVAS C behaviour.

• Expand Makefile build to support MacOS #221: GitHub Actions CI now includes Makefile builds and tests for Mac OS X. (by @kiranshila)

• Add CMake build tooling #222: GitHub Actions CI now checks CMake build, for Linux, Mac OS X, FreeBSD, and Windows. (by @kiranshila)

• GNU make build check on FreeBSD #225: GNU Makefile fixes for non-Linux builds, and FreeBSD build check in GitHub Actions CI.

• Non-UNIX builds / functionality #231: The source code (including tests and examples) now uses platform-dependent file separator for improved portability to Windows.

• Non-UNIX builds / functionality #231: Changed documentation build to wean off the likes of sed or tail, thus allowing to build documentation in a more platform-independent way.

• Install more documentation #237: Both CMake and GNU make now install more developer docs into $(docdir)/supernovas, such as examples/, legacy/, source code, and markdown files.

• Overhaul document generation #241: Overhauled document generation. Non-GitHub markdown files are now in doc/, which has its own Makefile and CMake sub-configuration.

• README collapsibe details, notes, etc. #242: README edits and collapsible sections, as well as Github style highlighting of notes, warnings etc.

• Option to exclude deprecated definitions from novas.h #249: Option to exclude deprecated API from novas.h definitions for your application. Simply compile your application with -D_EXCLUDE_DEPRECATED or else define _EXCLUDE_DEPRECATED in your source before including novas.h.

• Generate CIO locator data as needed. #250: cio_array() is changed to calculate CIO locations vs GCRS on the fly. With the change SuperNOVAS does not use a CIO locator data file any more, for any purpose. The change also ensures complete internal consistency with the implemented standards, such as the precession-nutation model.

• build-cmake.yml: check more build configs #251: Added further CI checks via Github Actions.

• Don't build legacy solsys going forward #252: Overhauled how legacy solarsystem() / solarsystem_hp() and readeph() functions can be added to the build if needed, e.g. via externally provided sources at build time. If a solarsystem() / solarsystem_hp() module is not explicitly defined for the build, solsys3.c will provide a default implementation for these. (No more undefined symbols that need to be resolved at runtime.)

• Improved portability beyond UNIX (e.g. MSVC) #255: More platform-independent code, by eliminating some UNIX specific calls. Windows builds with the Microsoft Visual C compiler are now possible also (with CMake).

• pthread mutexes instead of POSIX semaphores in plugins #263: Use pthread mutexes instead of POSIX semaphores to provide thread-safe access to CALCEPH / CSPICE ephemeris data. POSIX semaphores are not supported on Windows and MacOS, whereas pthread is available on all (via wrapper library on Windows -- something that CMake is aware of).

• Automatically correct for diurnal EOP variations #264: The likes of novas_set_time() and full accuracy novas_make_frame() will automatically apply diurnal corrections for libration and ocean tides to the input EOP values. As such, users should supply mean (interpolated) UT1-UTC time differences and x_p, y_p pole offsets, e.g. directly from the IERS Bulletins.

• Automatically correct for diurnal EOP variations #264: novas_timespec now stores the TT-TDB conversion to the full (100 ns) precision. It's slightly slower than the less precise original NOVAS tdb2tt(), but it's worth it not having to worry about the precision.

• Use portable mutex code in plugins. #265: CALCEPH and CSPICE plugins to use portable mutex code.

• Add caching to new functions in v1.5 #266: Add caching to tt2tdb_hp() and novas_moon_phase() functions.

• Both CMake and GNU make now install only the headers for the components that were built. E.g. novas-calceph.h is installed only if the library is built with the CALCEPH support option enabled.

• Renamed equinox.c to equator.c, since the functions therein concern the equator of date more than the equinox of date specifically.

• Moved a few functions around among the source modules to make the organization more consistent. It also helps when browsing the HTML documentation topically by source modules.

• solarsystem.h is moved to legacy with non-legacy definitions and prototypes migrated to novas.h. This has no downstream effect as all content of solarsystem.h was already included in novas.h, and it relied on definitions in novas.h, s.t. it could not be included prior to novas.h anyway. Effectively it has always been an integral part of novas.h even if it was a separate file before.

• Fully revised API and user documentation. The HTML API docs now have automatic brief descriptions when listed (except for the deprecated entitites, which do not).

Deprecated

• Wean off CIO locator file internally. #208: Deprecated cio_array() and cio_location(). Going forward, SuperNOVAS no longer uses the CIO locator data files (CIO_RA.TXT or cio_ra.bin) internally, and so cio_location() becomes redundant with cio_ra() and also with ira_equinox() (which returns the negative of the same value).

• Clean up sidereal time calculations. #209: Deprecated sidereal_time(). It is messy and one of its arguments (erot) is now unused. Instead, you should use novas_gmst() or novas_gast() to get the same results simpler.

• Deprecate cio_basis() #214: Deprecated cio_basis(). It is no longer used internally by the library, and users are recommended against using it themselves, since SuperNOVAS provides cleaner ways to convert between GCRS and CIRS using frames and transforms, or else via the gcrs_to_cirs() / cirs_to_gcrs() functions.

• New site/observer initializers with default mean weather parameters. #245: Deprecated make_on_surface(), make_observer_on_surface(), and make_observer() functions. The first two did not disambiguate between GPS and ITRF locations, and also required to set some weather parameters, while did not set humidity. There are a new set of functions (see further above) which provide more flexibility. And, make_observer() no longer supports all SuperNOVAS observer types, hence it's less relevant now than the targeted set of SuperNOVAS functions available for every type of observer.

• Generate CIO locator data as needed. #250: Deprecated set_cio_locator_file(). It has no function any more, and does exactly nothing beyond providing API compatibility.

• Deprecated the functions in solsys2.c. This NOVAS C module is half-baked at best, requiring a custom Fortran interface to the PLEPH library. You probably should stay away from it for your own good, and use instead the provided CALCEPH or CSPICE plugins for a more up-to-date and modern JPL ephemeris support.

• Deprecated the internal variables and functions of eph_manager.c. They should never have been exposed to users in the first place. The definitions can also be hidden from eph_manager.h by setting -D_EXCLUDE_DEPRECATED compiler flag, or adding #define _EXCLUDE_DEPRECATED in your application source code before including eph_manager.h.

• Deprecated the functions of solsys1.c and eph_manager.c. These provide built-in support for older JPL planetary ephemerides DE200 -- DE405 only. Given its lack of support for more recent ephemeris data, users should probably stay away from this NOVAS C legacy module, and instead opt for one the built-in CALCEPH and/or CSPICE plugins to allow accessing a wider variety, and more up-to-date, ephemeris data -- with a lot more flexibility also.

• Moved nutation.h to legacy/. Its functions are now integral to novas.h instead. It is unlikely that any one would use it as a separate header, and not via novas.h. But, in case someone does want it, they can find it it the installation folder of the supernovas documentation, under the legacy/ folder.