v1.0.1 bug fix release (#13)

* Add cirs_to_app_ra() and app_to_cirs_ra() for convenience.

* Use IAU definition of AU. (legacy definition of AU, based on DE405 ephemeris, as DE405_AU.)

* Fixes to example.c

* Minor tweak to example.yml workflow

* Updated and edited documentation

.github/workflows/dox.yml

@@ -1,6 +1,9 @@
 name: API documentation
 
 on:
+  release:
+    types: [published]
+
   push:
     paths:
       - 'src/**'
@@ -75,3 +78,36 @@ jobs:
         git add -A
         git commit -m "[automated site update]" && git push || true
         
+        
+  changelog-update:
+    name: Update CHANGELOG on github pages
+    if: github.repository_owner == 'Smithsonian' && contains(github.event.head_commit.message, 'changelog update')
+
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout source
+      uses: actions/checkout@v4
+
+    - name: Checkout gh-pages
+      uses: actions/checkout@v4
+      with:
+        ref: 'gh-pages'
+        path: site
+
+    - name: Assert site/doc/
+      run: mkdir -p site/doc 
+
+    - name: Copy CHANGELOG
+      run: cp CHANGELOG.md site/doc/
+
+    - name: Push to pages
+      run: |
+        cd site
+        git config --global user.email "$GITHUB_JOB+github-actions[bot]@users.noreply.github.com"
+        git config --global user.name "github-actions"
+        git add -A
+        git commit -m "[automated site update]" && git push || true
+    
+
+

.github/workflows/example.yml

@@ -0,0 +1,24 @@
+name: Example
+
+on: 
+  push:
+    paths:
+      - 'examples/**'
+      - '.github/workflows/example.yml'
+
+jobs:
+
+  build:
+    name: Check examples
+
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Compile example.c
+      run: |
+        cd examples
+        gcc -c -Wall -Werror -I ../include example.c 
+
+      
+   

.github/workflows/indexnow.yml

@@ -15,6 +15,6 @@ jobs:
         with:
           sitemap-location: 'https://smithsonian.github.io/SuperNOVAS/sitemap.xml'
           key: ${{ secrets.INDEXNOW_KEY }}
-          since-unit: week
+          key-location: 'https://smithsonian.github.io/SuperNOVAS/${{ secrets.INDEXNOW_KEY }}.txt'
           limit: 200
 

.settings/language.settings.xml

@@ -5,7 +5,7 @@
 			<provider copy-of="extension" id="org.eclipse.cdt.ui.UserLanguageSettingsProvider"/>
 			<provider-reference id="org.eclipse.cdt.core.ReferencedProjectsLanguageSettingsProvider" ref="shared-provider"/>
 			<provider class="org.eclipse.cdt.managedbuilder.language.settings.providers.GCCBuildCommandParser" id="org.eclipse.cdt.managedbuilder.core.GCCBuildCommandParser" keep-relative-paths="false" name="CDT GCC Build Output Parser" parameter="([^/\\\\]*)((g?cc)|([gc]\+\+)|(clang))" prefer-non-shared="true"/>
-			<provider class="org.eclipse.cdt.managedbuilder.language.settings.providers.GCCBuiltinSpecsDetector" console="false" env-hash="532750541605884254" id="org.eclipse.cdt.managedbuilder.core.GCCBuiltinSpecsDetector" keep-relative-paths="false" name="CDT GCC Built-in Compiler Settings" parameter="${COMMAND} ${FLAGS} -E -P -v -dD &quot;${INPUTS}&quot;" prefer-non-shared="true">
+			<provider class="org.eclipse.cdt.managedbuilder.language.settings.providers.GCCBuiltinSpecsDetector" console="false" env-hash="533149516069884254" id="org.eclipse.cdt.managedbuilder.core.GCCBuiltinSpecsDetector" keep-relative-paths="false" name="CDT GCC Built-in Compiler Settings" parameter="${COMMAND} ${FLAGS} -E -P -v -dD &quot;${INPUTS}&quot;" prefer-non-shared="true">
 				<language-scope id="org.eclipse.cdt.core.gcc"/>
 				<language-scope id="org.eclipse.cdt.core.g++"/>
 			</provider>

CHANGELOG.md

@@ -1,9 +1,39 @@
 # Changelog
 
+All notable changes to the SuperNOVAS library will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to 
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [1.0.1] -- 2024-05-13
+
+Bug fix release with minor changes.
+
+### Fixed
+
+ - `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.
+
+ - Fixed errors in `example.c` [by hannorein].
+
+### 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.
+
+### Changes
+
+ - Changed definition of `NOVAS_AU` to the IAU definition of exactly 1.495978707e+11 m. The old definition is also
+   available as `DE405_AU`.
+ - Various corrections and changes to documentation.
+
+
 
 ## [1.0.0] - 2024-03-01
 
-This is the initial release of the SuperNOVAS library.
+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.
 
 ### Fixed
 
@@ -32,13 +62,13 @@ This is the initial release of the SuperNOVAS library.
  - Fixes multiple NOVAS C 3.1 bugs related to using cached values in `cio_basis()` with alternating CIO location 
    reference systems. This affected many CIRS-based position calculations downstream.
 
- - Fixes NOVAS C 3.1 buga in `equ2ecl_vec()` and `ecl2equ_vec()` whereby a query with `coord_sys = 2` (GCRS) has 
+ - Fixes NOVAS C 3.1 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 NOVAS C 3.1 `aberration()` returning NaN vectors if the `ve` argument is 0. It now returns the unmodified 
-   input vector  appropriately instead.
+   input vector appropriately instead.
 
  - Fixes unpopulated `az` output value in `equ2hor()` at zenith in NOVAS C 3.1. While any azimuth is acceptable 
    really, it results in unpredictable behavior. Hence, we set `az` to 0.0 for zenith to be consistent.
@@ -76,7 +106,7 @@ This is the initial release of the SuperNOVAS library.
      `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
+   * If CIO locations vs GCRS 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. 
 
@@ -119,7 +149,7 @@ This is the initial release of the SuperNOVAS library.
    `planet_eph_manager` vs `planet_ephem_provider()`.
 
  - New `novas_case_sensitive(int)` to enable (or disable) case-sensitive processing of object names. (By default NOVAS 
-   `object` names were converted to upper-case, making them effectively case-insensitive.)
+   `object` names are converted to upper-case, making them effectively case-insensitive.)
 
  - New `make_planet()` and `make_ephem_object()` to make it simpler to configure Solar-system objects.
 
@@ -172,6 +202,9 @@ This is the initial release of the SuperNOVAS library.
 
  - Object ID numbers are `long` instead of `short` (in NOVAS C 3.1) to accommodate NAIF IDs, which require minimum 
    32-bit integers.
+
+ - `precession()` can now take arbitrary input and output epochs. Unlike NOVAS C 3.1, it is not required that either 
+   of those epochs be J2000.
 
  - `cel2ter()` and `ter2cel()` can now process 'option'/'class' = 1 (`NOVAS_REFERENCE_CLASS`) regardless of the
    methodology (`EROT_ERA` or `EROT_GST`) used to input or output coordinates in GCRS (unlike in NOVAS C 3.1).
@@ -195,7 +228,7 @@ This is the initial release of the SuperNOVAS library.
 
  - IAU 2000 nutation made a bit faster vs NOVAS C 3.1, via reducing the the number of floating-point multiplications 
    necessary by skipping terms that do not contribute. Its coefficients are also packed more frugally in memory, 
-   resulting in a smaller foortprint than in NOVAS C 3.1.
+   resulting in a smaller footprint than in NOVAS C 3.1.
 
  - More efficient paging (cache management) for `cio_array()` vs NOVAS C 3.1, including I/O error checking.
 

README.md

@@ -139,9 +139,13 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
 ## Compatibility with NOVAS C 3.1
 
 SuperNOVAS strives to maintain API compatibility with the upstream NOVAS C 3.1 library, but not binary compatibility. 
-In practical terms it means that you cannot simply drop-in replace your compiled objects (e.g. `novas.o`), or the 
-static (e.g. `novas.a`) or shared (e.g. `novas.so`) libraries, from NOVAS C 3.1 with that from SuperNOVAS. Instead, 
-you will need to (re)build your application with the SuperNOVAS versions of these. 
+
+If you have code that was written for NOVAS C 3.1, it should work with SuperNOVAS as is, without modifications. Simply 
+(re)build your application against SuperNOVAS, and you are good to go. 
+
+The lack of binary compatibility just means that you cannot drop-in replace your compiled objects (e.g. `novas.o`, or 
+the static `novas.a`, or the shared `novas.so`) libraries, from NOVAS C 3.1 with those from SuperNOVAS. Instead, you 
+will have to build (compile) your application referencing the SuperNOVAS headers and/or libraries from the start.
 
 This is because some function signatures have changed, e.g. to use an `enum` argument instead of the nondescript 
 `short int` argument of NOVAS C 3.1, or because we added a return value to a function that was declared `void` in 
@@ -405,14 +409,7 @@ above), you have one more step to go still. The CIRS equator is the true equator
 not the true equinox of date. Thus, we must correct for the difference of the origins to get the true apparent R.A.:
 
 ```c
-  double ra_cio;  // [h] R.A. of the CIO (from the true equinox) we'll calculate
-
-  // Obtain the R.A. [h] of the CIO at the given date
-  cio_ra(jd_tt, NOVAS_FULL_ACCURACY, &ra_cio);
-  
-  // Convert CIRS R.A. to true apparent R.A., keeping the result in the [0:24] h range
-  ra = remainder(ra + ra_cio, 24.0);
-  if(ra < 0.0) ra += 24.0;
+  ra = cirs_to_app_ra(jd_tt, NOVAS_FULL_ACCURACY, ra);
 ```
 
 #### B. Azimuth and elevation angles at the observing location
@@ -852,6 +849,7 @@ And, when you are done using the ephemeris file, you should close it with
 Note, that at any given time `eph_manager` can have only one ephemeris data file opened. You cannot use it to 
 retrieve data from multiple ephemeris input files at the same time. (But you can with the CSPICE toolkit, which you 
 can integrate as discussed further above!)
+
 That's all, except the warning that this method will not work with newer JPL ephemeris data, beyond DE421.
 
 
@@ -869,10 +867,11 @@ your application should set your planetary ephemeris provider at runtime via:
 ```
 
 Integrating JPL ephemeris data this way can be arduous. You will need to compile and link FORTRAN with C (not the end
-of the world), but you may also have to modify `jplint.f` (providing the intermediate FORTRAN `jplint_` / `jplihp_()`
-interfaces to `pleph`) to work with the version of `pleph.f` that you will be using. Unless you already have code that 
-relies on this method, you are probably better off choosing one of the other ways for integrating planetary ephemeris 
-data with SuperNOVAS.
+of the world), but you may also have to modify `jplint.f` (providing the intermediate FORTRAN `jplint_()` / 
+`jplihp_()` interfaces to `pleph`) to work with the version of `pleph.f` that you will be using. Unless you already 
+have code that relies on this method, you are probably better off choosing one of the other ways for integrating 
+planetary ephemeris data with SuperNOVAS.
+
 
 <a name="explicit-ephem-linking"></a>
 ### 3. Explicit linking of custom ephemeris functions

examples/example.c

@@ -15,7 +15,6 @@
 #include <math.h>
 
 #include "novas.h"
-#include "novascon.h"
 #include "eph_manager.h"  // For solsys1.c
 
 int main(void) {
@@ -104,6 +103,7 @@ int main(void) {
 
   // Establish time arguments.
   jd_utc = julian_date(2008, 4, 24, 10.605);
+  jd_tt = jd_utc + ((double) leap_secs + 32.184) / 86400.0;
   jd_ut1 = jd_utc + ut1_utc / 86400.0;
   delta_t = get_ut1_to_tt(leap_secs, ut1_utc);
 
@@ -195,7 +195,7 @@ int main(void) {
     return (error);
   }
 
-  error = equ2ecl_vec(T0, NOVAS_MEAN_EQUATOR, NOVAS_FULL_ACCURACY, pos, pose);
+  error = equ2ecl_vec(NOVAS_JD_J2000, NOVAS_MEAN_EQUATOR, NOVAS_FULL_ACCURACY, pos, pose);
   if(error != 0) {
     printf("Error %d from equ2ecl_vec.", error);
     return (error);

include/novas.h

@@ -2,7 +2,7 @@
  * @file
  *
  * @author G. Kaplan and A. Kovacs
- * @version 1.0.0
+ * @version 1.0.1
  *
  *  SuperNOVAS astrometry softwate based on the Naval Observatory Vector Astrometry Software (NOVAS).
  *  It has been modified to fix outstanding issues and to make it easier to use.
@@ -53,7 +53,7 @@
 #define SUPERNOVAS_MAJOR_VERSION  1             ///< API major version
 #define SUPERNOVAS_MINOR_VERSION  0             ///< API minor version
 #define SUPERNOVAS_PATCHLEVEL     1             ///< Integer sub version of the release
-#define SUPERNOVAS_RELEASE_STRING "-devel"      ///< Additional release information in version, e.g. "-1", or "-rc1".
+#define SUPERNOVAS_RELEASE_STRING ""            ///< Additional release information in version, e.g. "-1", or "-rc1".
 
 /// The version string for this library
 #define SUPERNOVAS_VERSION_STRING #SUPERNOVAS_MAJOR_VERSION "." #SUPERNOVAS_MINOR_VERSION \
@@ -85,10 +85,16 @@
 /// [m/s] Speed of light in meters/second is a defining physical constant.
 #define NOVAS_C                   299792458.0
 
-/// [m] Astronomical unit in meters.  Value is AU_SEC * C.
-#define NOVAS_AU                  1.4959787069098932e+11
+/// [m] Astronomical unit. IAU definition.
+/// See <a href="https://www.iau.org/static/resolutions/IAU2012_English.pdf">IAU 2012 Resolution B2</a>.
+/// @sa DE405_AU
+#define NOVAS_AU                  1.495978707e+11
 
-/// [AU] Light-time for one astronomical unit (AU) in seconds, from DE-405.
+/// [m] Astronomical unit. based on DE-405. (old definition)
+/// @sa NOVAS_AU
+#define DE405_AU                  1.4959787069098932e+11
+
+/// [AU] Light-time for one astronomical unit (AU) in seconds.
 #define NOVAS_AU_SEC              ( NOVAS_AU / NOVAS_C )
 
 /// [AU/day] Speed of light in AU/day.  Value is 86400 / AU_SEC.
@@ -869,8 +875,19 @@ int itrs_to_hor(const on_surface *location, const double *itrs, double *az, doub
 
 int hor_to_itrs(const on_surface *location, double az, double za, double *itrs);
 
+// ---------------------- Added in 1.0.1 -------------------------
+double cirs_to_app_ra(double jd_tt, enum novas_accuracy accuracy, double ra);
+
+double app_to_cirs_ra(double jd_tt, enum novas_accuracy accuracy, double ra);
+
+
+// <================= END of SuperNOVAS API =====================>
+
 #include "solarsystem.h"
 
+
+// <================= SuperNOVAS internals ======================>
+
 /// \cond PRIVATE
 #ifdef __NOVAS_INTERNAL_API__
 

resources/header.html

@@ -14,7 +14,7 @@
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
 <meta charset="utf-8"/>
-<meta name="description" content="The NOVAS C library, made better. SuperNOVAS is a light-weight, high-precision astrometry library for the C programming language."/>
+<meta name="description" content="SuperNOVAS C/C++ astrometry library"/>
 <meta name="keywords" content="astronomy, astrometry, C, C++, library, NOVAS"/>
 <meta name="author" content="Attila Kovacs"/>
 <meta name="copyright" content="(C)2024 Attila Kovacs" />
@@ -29,10 +29,10 @@
 
   gtag('config', 'G-HLFWKSM8V9');
 </script>
-<link rel="shortcut icon" type="image/x-icon" href="/SuperNOVAS/favicon.ico" />
-<link rel="icon" type="image/png" sizes="192x192" href="/SuperNOVAS/android-chrome-192x192.png" />
-<link rel="icon" type="image/png" sizes="512x512" href="/SuperNOVAS/android-chrome-512x512.png" />
-<link rel="apple-touch-icon" type="image/png" href="/SuperNOVAS/apple-touch-icon.png" />
+<link rel="shortcut icon" type="image/x-icon" href="/SuperNOVAS/resources/favicon.ico" />
+<link rel="icon" type="image/png" sizes="192x192" href="/SuperNOVAS/resources/android-chrome-192x192.png" />
+<link rel="icon" type="image/png" sizes="512x512" href="/SuperNOVAS/resources/android-chrome-512x512.png" />
+<link rel="apple-touch-icon" type="image/png" href="/SuperNOVAS/resources/apple-touch-icon.png" />
 <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
 <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
 <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>