New set of example files

Smithsonian · Jan 9, 2025 · 3f40c9d · 3f40c9d
1 parent 60c8a55
commit 3f40c9d
Show file tree

Hide file tree

Showing 11 changed files with 845 additions and 240 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [1.2.0-rc5] - 2025-01-01
+## [Unreleased]
 
 Release candidate for the next feature release, expected around 1 February 2025.
 
@@ -80,6 +80,9 @@ Release candidate for the next feature release, expected around 1 February 2025.
 
  - #98: Added `gcrs_to_tod()` / `tod_to_gcrs()` and `gcrs_to_mod()` / `mod_to_gcrs()` vector conversion functions for
    convenience.
+
+ - #106: New example files under `examples/` demonstrating the recommended approach for using SuperNOVAS to calculate
+   positions for various types of object.
 
  - Added various `object` initializer macros in `novas.h` for the major planets, Sun, Moon, and barycenters, e.g. 
    `NOVAS_EARTH_INIT` or `NOVAS_SSB_INIT`. These wrap the parametric `NOVAS_PLANET_INIT(num, name)` macro, and can be
@@ -112,6 +115,9 @@ Release candidate for the next feature release, expected around 1 February 2025.
  - #97: Updated `NOVAS_PLANETS`, `NOVAS_PLANET_NAMES_INIT`, and `NOVAS_RMASS_INIT` macros to include the added planet 
    constants.
 
+ - #106: The old (legacy) NOVAS C example has been removed. Instead a new set of examples are provided, which are 
+   better suited for SuperNOVAS.
+
  - `make check` now runs both static analysis by cppcheck (new `analysis` target) and regression tests (`test` 
    target), in closer conformance to GNU Makefile standards.
 

diff --git a/examples/example-calceph b/examples/example-calceph
diff --git a/examples/example-calceph.c b/examples/example-calceph.c
@@ -0,0 +1,179 @@
+/**
+ * @file
+ *
+ * @date Created  on Jan 9, 2025
+ * @author Attila Kovacs
+ *
+ *  Example file for using the SuperNOVAS C/C++ library for determining positions for
+ *  Solary-system sources, with the CALCEPH C library providing access to ephemeris
+ *  files.
+ *
+ *  You will need access to the CALCEPH library (unversioned `libcalceph.so` or else
+ *  `libcalceph.a`) and C headers (`calceph.h`), and the SuperNOVAS
+ *  `libsolsys-calceph.so` (or `libsoslsys-calceph.a`) module.
+ *
+ *  Link with:
+ *
+ *  ```
+ *   -lsupernovas -lsolsys-calceph -lcalceph
+ *  ```
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+#include <novas.h>            ///< SuperNOVAS functions and definitions
+#include <novas-calceph.h>    ///< CALCEPH adapter functions to SuperNOVAS
+
+
+// Below are some Earth orientation values. Here we define them as constants, but they may
+// of course be variables. They should be set to the appropriate values for the time
+// of observation based on the IERS Bulletins...
+
+#define  LEAP_SECONDS     37        ///< [s] current leap seconds
+#define  DUT1             0.114     ///< [s] current UT1 - UTC time difference from IERS Bulletin A
+#define  POLAR_DX         230.0     ///< [mas] Earth polar offset x, e.g. from IERS Bulletin A.
+#define  POLAR_DY         -62.0     ///< [mas] Earth polar offset y, e.g. from IERS Bulletin A.
+
+int main() {
+  // SuperNOVAS aariables used for the calculations ------------------------->
+  cat_entry star = CAT_ENTRY_INIT;  // catalog information about a sidereal source
+  object source;                    // observed source
+  observer obs;                     // observer location
+  novas_timespec obs_time;          // astrometric time of observation
+  novas_frame obs_frame;            // observing frame defined for observing time and location
+  enum novas_accuracy accuracy;     // NOVAS_FULL_ACCURACY or NOVAS_REDUCED_ACCURACY
+  sky_pos apparent;                 // calculated precise observed (apparent) position of source
+
+  // Calculated quantities ------------------------------------------------->
+  double az, el;                    // calculated azimuth and elevation at observing site
+
+  // Intermediate variables we'll use -------------------------------------->
+  t_calcephbin *de440;              // CALCEPH ephemeris binary
+  struct timespec unix_time;        // Standard precision UNIX time structure
+
+
+  // We'll print debugging messages and error traces...
+  novas_debug(NOVAS_DEBUG_ON);
+
+  // -------------------------------------------------------------------------
+  // We'll use the CALCEPH library to provide ephemeris data
+
+  // First open one or more ephemeris files with CALCEPH to use
+  // E.g. the DE440 (short-term) ephemeris data from JPL.
+  de440 = calceph_open("path/to/de440s.bsp");
+  if(!de440) {
+    fprintf(stderr, "ERROR! could not open ephemeris data\n");
+    return 1;
+  }
+
+  // Make de440 provide ephemeris data for the major planets.
+  novas_use_calceph_planets(de440);
+
+  // We could specify to use a calceph ephemeris binary for generic
+  // Solar-systems sources also (including planets too if
+  // novas_use_calceph_planets() is not called separately
+  //
+  // E.g. Jovian satellites:
+  // t_calcephbin jovian = calceph_open("/path/to/jup365.bsp");
+  // novas_use_calceph(jovian);
+
+  // Since we have an ephemeris provider for major planets, we can unlock the
+  // ultimate accuracy of SuperNOVAS.
+  accuracy = NOVAS_FULL_ACCURACY;      // sub-uas precision
+
+
+  // -------------------------------------------------------------------------
+  // Define a Solar-system source
+
+  // To define a major planet (or Sun, Moon, SSB, or EMB):
+  if(make_planet(NOVAS_MARS, &source) != 0) {
+    fprintf(stderr, "ERROR! defining planet.\n");
+    return 1;
+  }
+
+  // ... Or, to define a minor body, such as an asteroid or satellite
+  // with a name and ID number.
+  /*
+  if(make_ephem_object("Io", 501, &source) != 0) {
+    fprintf(stderr, "ERROR! defining ephemeris body.\n");
+    return 1;
+  }
+  */
+
+  /*
+  // If the object uses CALCEPH IDs instead of NAIF, then
+  novas_calceph_use_ids(NOVAS_ID_CALCEPH);
+  */
+
+
+  // -------------------------------------------------------------------------
+  // Define observer somewhere on Earth (we can also define observers in Earth
+  // or Sun orbit, at the geocenter or at the Solary-system barycenter...)
+
+  // Specify the location we are observing from
+  // 50.7374 deg N, 7.0982 deg E, 60m elevation
+  if(make_observer_on_surface(50.7374, 7.0982, 60.0, 0.0, 0.0, &obs) != 0) {
+    fprintf(stderr, "ERROR! defining Earth-based observer location.\n");
+    return 1;
+  }
+
+
+  // -------------------------------------------------------------------------
+  // Set the astrometric time of observation...
+
+  // Get the current system time, with up to nanosecond resolution...
+  clock_gettime(CLOCK_REALTIME, &unix_time);
+
+  // Set the time of observation to the precise UTC-based UNIX time
+  if(novas_set_unix_time(unix_time.tv_sec, unix_time.tv_nsec, LEAP_SECONDS, DUT1, &obs_time) != 0) {
+    fprintf(stderr, "ERROR! failed to set time of observation.\n");
+    return 1;
+  }
+
+  // ... Or you could set a time explicily in any known timescale.
+  /*
+  // Let's set a TDB-based time for the start of the J2000 epoch exactly...
+  if(novas_set_time(NOVAS_TDB, NOVAS_JD_J2000, LEAP_SECONDS, DUT1, &obs_time) != 0) {
+    fprintf(stderr, "ERROR! failed to set time of observation.\n");
+    return 1;
+  }
+  */
+
+  // -------------------------------------------------------------------------
+  // Initialize the observing frame with the given observing and Earth
+  // orientation patameters.
+  //
+  if(novas_make_frame(accuracy, &obs, &obs_time, POLAR_DX, POLAR_DY, &obs_frame) != 0) {
+    fprintf(stderr, "ERROR! failed to define observing frame.\n");
+    return 1;
+  }
+
+
+  // -------------------------------------------------------------------------
+  // Calculate the precise apparent position (here in CIRS coordinates)
+  if(novas_sky_pos(&source, &obs_frame, NOVAS_CIRS, &apparent) != 0) {
+    fprintf(stderr, "ERROR! failed to calculate apparent position.\n");
+    return 1;
+  }
+
+  // Let's print the apparent position
+  printf(" RA = %.9f h, Dec = %.9f deg, rad_vel = %.6f km/s\n", apparent.ra, apparent.dec, apparent.rv);
+
+
+  // -------------------------------------------------------------------------
+  // Convert the apparent position in CIRS on sky to horizontal coordinates
+  // We'll use a standard (fixed) atmospheric model to estimate an optical refraction
+  // (You might use other refraction models, or NULL to ignore refraction corrections)
+  if(novas_app_to_hor(&obs_frame, NOVAS_CIRS, apparent.ra, apparent.dec, novas_standard_refraction, &az, &el) != 0) {
+    fprintf(stderr, "ERROR! failed to calculate azimuth / elevation.\n");
+    return 1;
+  }
+
+  // Let's print the calculated azimuth and elevation
+  printf(" Az = %.6f deg, El = %.6f deg\n", az, el);
+
+  return 0;
+}
+
diff --git a/examples/example-cspice b/examples/example-cspice
diff --git a/examples/example-cspice.c b/examples/example-cspice.c
@@ -0,0 +1,175 @@
+/**
+ * @file
+ *
+ * @date Created  on Jan 9, 2025
+ * @author Attila Kovacs
+ *
+ *  Example file for using the SuperNOVAS C/C++ library for determining positions for
+ *  Solary-system sources, with the NAIF CSPICE toolkit providing access to ephemeris
+ *  files.
+ *
+ *  You will need access to the NAIF CSPICE library (unversioned `libcspice.so` or else
+ *  `libcspice.a`) and C headers (`cspice/*.h`), and the SuperNOVAS `libsolsys-cspice.so`
+ *  (or `libsoslsys-cspice.a`) module.
+ *
+ *  To compile CSPICE as a shared (.so) library, you may want to check out the GitHub
+ *  repository:
+ *
+ *   - https://github.com/Smithsonian/cspice-sharedlib
+ *
+ *  Link with:
+ *
+ *  ```
+ *   -lsupernovas -lsolsys-cspice -lcspice
+ *  ```
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+#include <novas.h>            ///< SuperNOVAS functions and definitions
+#include <novas-cspice.h>     ///< CSPICE adapter functions to SuperNOVAS
+
+
+// Below are some Earth orientation values. Here we define them as constants, but they may
+// of course be variables. They should be set to the appropriate values for the time
+// of observation based on the IERS Bulletins...
+
+#define  LEAP_SECONDS     37        ///< [s] current leap seconds
+#define  DUT1             0.114     ///< [s] current UT1 - UTC time difference from IERS Bulletin A
+#define  POLAR_DX         230.0     ///< [mas] Earth polar offset x, e.g. from IERS Bulletin A.
+#define  POLAR_DY         -62.0     ///< [mas] Earth polar offset y, e.g. from IERS Bulletin A.
+
+int main() {
+  // SuperNOVAS aariables used for the calculations ------------------------->
+  cat_entry star = CAT_ENTRY_INIT;  // catalog information about a sidereal source
+  object source;                    // observed source
+  observer obs;                     // observer location
+  novas_timespec obs_time;          // astrometric time of observation
+  novas_frame obs_frame;            // observing frame defined for observing time and location
+  enum novas_accuracy accuracy;     // NOVAS_FULL_ACCURACY or NOVAS_REDUCED_ACCURACY
+  sky_pos apparent;                 // calculated precise observed (apparent) position of source
+
+  // Calculated quantities ------------------------------------------------->
+  double az, el;                    // calculated azimuth and elevation at observing site
+
+  // Intermediate variables we'll use -------------------------------------->
+  struct timespec unix_time;        // Standard precision UNIX time structure
+
+
+  // We'll print debugging messages and error traces...
+  novas_debug(NOVAS_DEBUG_ON);
+
+
+  // -------------------------------------------------------------------------
+  // We'll use the NAIF CSPICE Toolkit to provide ephemeris data
+
+  // Open one or more ephemeris files to use...'
+  // E.g. the DE440 (short-term) ephemeris data from JPL.
+  if(cspice_add_kernel("path/to/de440s.bsp") != 0) {
+    fprintf(stderr, "ERROR! could not open ephemeris data\n");
+    return 1;
+  }
+
+  // ... You can open multiple NAIF kernels
+  // E.g. add Jovian satellites...
+  // cspice_add_kernel("path/to/jup365.bsp");
+
+  // Now we can use the loaded ephemeris files for Solar-system objects.
+  // (major planets and minor bodies alike).
+  novas_use_cspice();
+
+  // And, since we have an ephemeris provider for major planets, we can unlock
+  // the ultimate accuracy of SuperNOVAS.
+  accuracy = NOVAS_FULL_ACCURACY;      // sub-uas precision
+
+
+  // -------------------------------------------------------------------------
+  // Define a Solar-system source
+
+  // To define a major planet (or Sun, Moon, SSB, or EMB):
+  if(make_planet(NOVAS_MARS, &source) != 0) {
+    fprintf(stderr, "ERROR! defining planet.\n");
+    return 1;
+  }
+
+  // ... Or, to define a minor body, such as an asteroid or satellite
+  // with a name and NAIF ID.
+  /*
+  if(make_ephem_object("Io", 501, &source) != 0) {
+    fprintf(stderr, "ERROR! defining ephemeris body.\n");
+    return 1;
+  }
+  */
+
+
+  // -------------------------------------------------------------------------
+  // Define observer somewhere on Earth (we can also define observers in Earth
+  // or Sun orbit, at the geocenter or at the Solary-system barycenter...)
+
+  // Specify the location we are observing from
+  // 50.7374 deg N, 7.0982 deg E, 60m elevation
+  if(make_observer_on_surface(50.7374, 7.0982, 60.0, 0.0, 0.0, &obs) != 0) {
+    fprintf(stderr, "ERROR! defining Earth-based observer location.\n");
+    return 1;
+  }
+
+
+  // -------------------------------------------------------------------------
+  // Set the astrometric time of observation...
+
+  // Get the current system time, with up to nanosecond resolution...
+  clock_gettime(CLOCK_REALTIME, &unix_time);
+
+  // Set the time of observation to the precise UTC-based UNIX time
+  if(novas_set_unix_time(unix_time.tv_sec, unix_time.tv_nsec, LEAP_SECONDS, DUT1, &obs_time) != 0) {
+    fprintf(stderr, "ERROR! failed to set time of observation.\n");
+    return 1;
+  }
+
+  // ... Or you could set a time explicily in any known timescale.
+  /*
+  // Let's set a TDB-based time for the start of the J2000 epoch exactly...
+  if(novas_set_time(NOVAS_TDB, NOVAS_JD_J2000, LEAP_SECONDS, DUT1, &obs_time) != 0) {
+    fprintf(stderr, "ERROR! failed to set time of observation.\n");
+    return 1;
+  }
+  */
+
+  // -------------------------------------------------------------------------
+  // Initialize the observing frame with the given observing and Earth
+  // orientation patameters.
+  //
+  if(novas_make_frame(accuracy, &obs, &obs_time, POLAR_DX, POLAR_DY, &obs_frame) != 0) {
+    fprintf(stderr, "ERROR! failed to define observing frame.\n");
+    return 1;
+  }
+
+
+  // -------------------------------------------------------------------------
+  // Calculate the precise apparent position (here in CIRS coordinates)
+  if(novas_sky_pos(&source, &obs_frame, NOVAS_CIRS, &apparent) != 0) {
+    fprintf(stderr, "ERROR! failed to calculate apparent position.\n");
+    return 1;
+  }
+
+  // Let's print the apparent position
+  printf(" RA = %.9f h, Dec = %.9f deg, rad_vel = %.6f km/s\n", apparent.ra, apparent.dec, apparent.rv);
+
+
+  // -------------------------------------------------------------------------
+  // Convert the apparent position in CIRS on sky to horizontal coordinates
+  // We'll use a standard (fixed) atmospheric model to estimate an optical refraction
+  // (You might use other refraction models, or NULL to ignore refraction corrections)
+  if(novas_app_to_hor(&obs_frame, NOVAS_CIRS, apparent.ra, apparent.dec, novas_standard_refraction, &az, &el) != 0) {
+    fprintf(stderr, "ERROR! failed to calculate azimuth / elevation.\n");
+    return 1;
+  }
+
+  // Let's print the calculated azimuth and elevation
+  printf(" Az = %.6f deg, El = %.6f deg\n", az, el);
+
+  return 0;
+}
+
diff --git a/examples/example-high-z b/examples/example-high-z