EMB and Pluto Barycenter (#97)

* Add NOVAS_EMB and NOVAS_PLUTO_BARYCENTER to novas_planets etc. * Update API docs for added barycenters * Doc update
Smithsonian · Nov 14, 2024 · 1e3d54e · 1e3d54e
1 parent ebd169d
commit 1e3d54e
Show file tree

Hide file tree

Showing 13 changed files with 99 additions and 63 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -60,6 +60,14 @@ Changes expected for the next feature release, expected around 1 February 2025.
  - SuperNOVAS headers now include each other as system-headers, not local headers. This is unlikely to affect anything
    really but it is more proper for an installation of the library, and works with our own `Makefile` too.
 
+ - #97: Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish
+   from the planet center in calculations.
+
+### Changed
+
+ - #97: Updated `NOVAS_PLANETS`, `NOVAS_PLANET_NAMES_INIT` and `NOVAS_RMASS_INIT` macros to include the added planet 
+   constants.
+
 
 ## [1.1.1] - 2024-10-28
 

diff --git a/README.md b/README.md
@@ -887,13 +887,16 @@ before that level of accuracy is reached.
    `NOVAS_EPHEM_OBJECTS` should use NAIF IDs with CSPICE (or else -1 for name-based lookup). Also provides
    `cspice_add_kernel()` and `cspice_remove_kernel()`.
    
- - NAIF/NOVAS ID conversions for major planets (and Sun, Moon, SSB): `novas_to_naif_planet()`, 
+ - NAIF/NOVAS ID conversions for major planets (and Sun, Moon, SSB...): `novas_to_naif_planet()`, 
    `novas_to_dexxx_planet()`, and `naif_to_novas_planet()`.
    
  - Access to custom ephemeris provider functions: `get_planet_provider()` and `get_planet_provider_hp()`.
 
  - Added `novas_planet_for_name()` function to return the NOVAS planet ID for a given (case insensitive) name.
 
+ - Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish
+   from the corresponding planet centers in calculations.
+   
 
 <a name="api-changes"></a>
 ### Refinements to the NOVAS C API
@@ -985,7 +988,7 @@ SuperNOVAS flexibility in this area, you have several options on doing that. The
 NASA/JPL provides [generic ephemerides](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/) for the major 
 planets, satellites thereof, the 300 largest asteroids, the Lagrange points, and some Earth orbiting stations. For 
 example, [DE440](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de440.bsp) covers the major planets, 
-and the Sun, Moon, and the Solar-System Barycenter (SSB) for times between 1550 AD and 2650 AD. Or, you can use the 
+and the Sun, Moon, and barycenters for times between 1550 AD and 2650 AD. Or, you can use the 
 [JPL HORIZONS](https://ssd.jpl.nasa.gov/horizons/app.html#/) system to generate custom ephemeris data for pretty much
 all known solar systems bodies, down to the tiniest rocks. 
 
@@ -1118,7 +1121,7 @@ Once you have your adapter function, you can set it as your ephemeris service vi
 ```
 
 By default, your custom `my_ephem_reader` function will be used for 'minor planets' only (i.e. anything other than the 
-major planets, the Sun, Moon, and the Solar System Barycenter). But, you can use the same function for the mentioned 
+major planets, the Sun, Moon, Solar-system Barycenter...). But, you can use the same function for the mentioned 
 'major planets' also via:
 
 ```c

diff --git a/include/novas.h b/include/novas.h
@@ -171,18 +171,20 @@
 
 
 /// Reciprocal masses of solar system bodies, from DE-405 (Sun mass / body mass).
-/// [0]: Earth/Moon barycenter, MASS[1] = Mercury, ...,
-/// [9]: Pluto, [10]: Sun, [11]: Moon.
+/// [0]: Earth/Moon barycenter (legacy from NOVAS C), MASS[1] = Mercury, ...,
+/// [9]: Pluto (barycenter), [10]: Sun, [11]: Moon.
+/// Barycentric reciprocal masses (index 12, 13) are not set.
 #define NOVAS_RMASS_INIT  { \
       328900.561400, 6023600.0, 408523.71, 332946.050895, 3098708.0, 1047.3486, 3497.898, \
-      22902.98, 19412.24, 135200000.0, 1.0, 27068700.387534 }
+      22902.98, 19412.24, 135200000.0, 1.0, 27068700.387534, 0.0, 0.0 }
 
 /// Gravitational redshifts for major planets (and Moon and Sun) for light emitted at surface
-/// and detected at a large distance away.
+/// and detected at a large distance away. Barycenters are not considered, and for Pluto the
+/// redshift for the Pluto system is assumed for distant observers.
 /// @since 1.1.1
 #define NOVAS_PLANET_GRAV_Z_INIT { \
   0.0, 1.0047e-10, 5.9724e-10, 7.3050e-10, 1.4058e-10, 2.0166e-8, 7.2491e-9, 2.5420e-9, \
-  3.0893e-9, 9.1338e-12, 2.120483e-6, 3.1397e-11 }
+  3.0893e-9, 9.1338e-12, 2.120483e-6, 3.1397e-11, 0.0, 0.0 }
 
 #if !COMPAT
 // If we are not in the strict compatibility mode, where constants are defined
@@ -258,22 +260,24 @@ enum novas_object_type {
  * @sa NOVAS_PLANET_NAMES_INIT
  */
 enum novas_planet {
-  NOVAS_SSB = 0,        ///< Solar-system barycenter position ID
-  NOVAS_MERCURY,        ///< Major planet number for the Mercury in NOVAS.
-  NOVAS_VENUS,          ///< Major planet number for the Venus in NOVAS.
-  NOVAS_EARTH,          ///< Major planet number for the Earth in NOVAS.
-  NOVAS_MARS,           ///< Major planet number for the Mars in NOVAS.
-  NOVAS_JUPITER,        ///< Major planet number for the Jupiter in NOVAS.
-  NOVAS_SATURN,         ///< Major planet number for the Saturn in NOVAS.
-  NOVAS_URANUS,         ///< Major planet number for the Uranus in NOVAS.
-  NOVAS_NEPTUNE,        ///< Major planet number for the Neptune in NOVAS.
-  NOVAS_PLUTO,          ///< Major planet number for the Pluto in NOVAS.
-  NOVAS_SUN,            ///< Numerical ID for the Sun in NOVAS.
-  NOVAS_MOON            ///< Numerical ID for the Moon in NOVAS.
+  NOVAS_SSB = 0,          ///< Solar-system barycenter position ID
+  NOVAS_MERCURY,          ///< Major planet number for the Mercury in NOVAS.
+  NOVAS_VENUS,            ///< Major planet number for the Venus in NOVAS.
+  NOVAS_EARTH,            ///< Major planet number for the Earth in NOVAS.
+  NOVAS_MARS,             ///< Major planet number for the Mars in NOVAS.
+  NOVAS_JUPITER,          ///< Major planet number for the Jupiter in NOVAS.
+  NOVAS_SATURN,           ///< Major planet number for the Saturn in NOVAS.
+  NOVAS_URANUS,           ///< Major planet number for the Uranus in NOVAS.
+  NOVAS_NEPTUNE,          ///< Major planet number for the Neptune in NOVAS.
+  NOVAS_PLUTO,            ///< Major planet number for the Pluto in NOVAS.
+  NOVAS_SUN,              ///< Numerical ID for the Sun in NOVAS.
+  NOVAS_MOON,             ///< Numerical ID for the Moon in NOVAS.
+  NOVAS_EMB,              ///< NOVAS ID for the Earth-Moon Barycenter (EMB). @since 1.2
+  NOVAS_PLUTO_BARYCENTER  ///< NOVAS ID for the barycenter of the Pluto System. @since 1.2
 };
 
 /// The number of major planets defined in NOVAS.
-#define NOVAS_PLANETS             (NOVAS_MOON + 1)
+#define NOVAS_PLANETS             (NOVAS_PLUTO_BARYCENTER + 1)
 
 /**
  * String array initializer for Major planet names, matching the enum novas_planet. E.g.
@@ -284,7 +288,9 @@ enum novas_planet {
  *
  * @sa novas_majot_planet
  */
-#define NOVAS_PLANET_NAMES_INIT { "SSB", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Sun", "Moon" }
+#define NOVAS_PLANET_NAMES_INIT { \
+  "SSB", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", \
+  "Sun", "Moon", "EMB", "Pluto-Barycenter" };
 
 /**
  * Types of places on and around Earth that may serve a a reference position for the observation.

diff --git a/include/solarsystem.h b/include/solarsystem.h
@@ -4,7 +4,8 @@
  * @author G. Kaplan and A. Kovacs
  *
  *  SuperNOVAS header for custom solar-system ephemeris calculations for major planets plus
- *  the Sun, Moon, and the Solar-system barycenter.
+ *  the Sun, Moon, and the Solar-system barycenter (and as of v1.2 also the Earth-Moon
+ *  Barycenter and the barycenter of the Pluto system).
  *
  *  The source files solsys-calceph.c and solsys-cspice.c provide implementations that
  *  interface with the CALCEPH C library and the NAIF CSPICE Toolkit, respectively. CSPICE is
@@ -66,17 +67,17 @@ enum novas_id_type {
 #define NOVAS_ID_TYPES      (NOVAS_ID_CALCEPH + 1)
 
 /**
- * Provides the position and velocity of major planets (as well as the Sun, Moon, and
- * Solar-system Barycenter position. This version provides positions and velocities at regular
+ * Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system
+ * Barycenter, and other barycenters). This version provides positions and velocities at regular
  * precision (see NOVAS_REDUCED_PRECISION).
  *
  * Since this is a function that may be provided by existing custom user implementations, we
  * keep the original argument types for compatibility, hence 'short' instead of the more
  * informative enums).
  *
  * @param jd_tdb        [day] Barycentric Dynamical Time (TDB) based Julian date
- * @param body          Major planet number (or that for the Sun, Moon, or Solar-system
- *                      Barycenter position), as defined by enum novas_planet, e.g. NOVAS_MARS
+ * @param body          Major planet number (or that for the Sun, Moon, or an appropriate
+ *                      barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS
  *                      (4), NOVAS_SUN (10) or NOVAS_SSB (0).
  * @param origin        NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to
  *                      return positions and velocities. (For compatibility with existing NOVAS
@@ -99,8 +100,8 @@ typedef short (*novas_planet_provider)(double jd_tdb, enum novas_planet body, en
 
 
 /**
- * Provides the position and velocity of major planets (as well as the Sun, Moon, and
- * Solar-system Barycenter position. This version provides positions and velocities at high
+ * Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system
+ * Barycenter, and other barycenters). This version provides positions and velocities at high
  * precision (see NOVAS_FULL_PRECISION).
  *
  * Since this is a function that may be provided by existing custom user implementations, we
@@ -110,8 +111,8 @@ typedef short (*novas_planet_provider)(double jd_tdb, enum novas_planet body, en
  * @param jd_tdb        [day] Barycentric Dynamical Time (TDB) based Julian date, broken into
  *                      high and low order components, respectively. Typically, as the integer
  *                      and fractional parts for the highest precision.
- * @param body          Major planet number (or that for the Sun, Moon, or Solar-system
- *                      Barycenter position), as defined by enum novas_planet, e.g. NOVAS_MARS
+ * @param body          Major planet number (or that for the Sun, Moon, or an appropriate
+ *                      barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS
  *                      (4), NOVAS_SUN (10) or NOVAS_SSB (0).
  * @param origin        NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to
  *                      return positions and velocities. (For compatibility with existing NOVAS
@@ -242,8 +243,8 @@ novas_ephem_provider get_ephem_provider();
  * informative enums).
  *
  * @param jd_tdb        [day] Barycentric Dynamical Time (TDB) based Julian date
- * @param body          Major planet number (or that for the Sun, Moon, or Solar-system
- *                      Barycenter position), as defined by enum novas_planet, e.g. NOVAS_MARS
+ * @param body          Major planet number (or that for the Sun, Moon, or an appropriate
+ *                      barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS
  *                      (4), NOVAS_SUN (10) or NOVAS_SSB (0). (For compatibility
  *                      with existing NOVAS C compatible user implementations, we keep the
  *                      original NOVAS C argument type here).
@@ -271,9 +272,9 @@ short solarsystem(double jd_tdb, short body, short origin, double *position, dou
 
 /**
  * A default implementation for high precision handling of major planets, Sun, Moon and the
- * Solar-system barycenter. See DEFAULT_SOLSYS in Makefile to choose the implementation that
- * is built into the library as a default. Applications can define their own preferred
- * implementations at runtime via set_planet_provider_hp().
+ * Solar-system barycenter (and other barycenters). See DEFAULT_SOLSYS in Makefile to choose
+ * the implementation that is built into the library as a default. Applications can define their
+ * own preferred implementations at runtime via set_planet_provider_hp().
  *
  * Since this is a function that may be provided by existing custom user implementations, we
  * keep the original argument types for compatibility, hence 'short' instead of the more
@@ -283,8 +284,8 @@ short solarsystem(double jd_tdb, short body, short origin, double *position, dou
  * @param jd_tdb        [day] Barycentric Dynamical Time (TDB) based Julian date, broken into
  *                      high and low order components, respectively. Typically, as the integer
  *                      and fractional parts for the highest precision.
- * @param body          Major planet number (or that for the Sun, Moon, or Solar-system
- *                      Barycenter position), as defined by enum novas_planet, e.g. NOVAS_MARS
+ * @param body          Major planet number (or that for the Sun, Moon, or an appropriate
+ *                      barycenter), as defined by enum novas_planet, e.g. NOVAS_MARS
  *                      (4), NOVAS_SUN (10) or NOVAS_SSB (0). (For compatibility with
  *                      existing NOVAS C compatible user implementations, we keep the original
  *                      NOVAS C argument type here).
@@ -362,6 +363,8 @@ long novas_to_dexxx_planet(enum novas_planet id);
 /// NAIF ID for the Earth-Moon Barycenter (EMB)
 #define NAIF_EMB        3
 
+/// NAIF ID for the barycenter of the Pluto system
+#define NAIF_PLUTO_BARYCENTER   9
 
 /**
  * The function to use to provide planet ephemeris data.

diff --git a/src/naif.c b/src/naif.c
@@ -21,10 +21,10 @@
 #include "novas.h"
 
 /**
- * Converts a NAIF ID to a NOVAS major planet ID. It account for the different IDs used for Sun, Moon and SSB.
- * Otherwise NAIF planet barycenters are mapped to the corresponding bodies, except EMB (3), which will return
- * -1. NAIF body centers <i>n</i>99 (e.g. 399 for Earth), are mapped to the corresponding NOVAS planet number
- * <i>n</i>. All other NAIF IDs will return -1, indicating no match to a NOVAS planet ID.
+ * Converts a NAIF ID to a NOVAS major planet ID. It account for the different IDs used for Sun, Moon, SSB, EMB
+ * and the Pluto system. Otherwise NAIF planet barycenters are mapped to the corresponding bodies. NAIF body centers
+ * <i>n</i>99 (e.g. 399 for Earth) are mapped to the corresponding NOVAS planet number <i>n</i>. All other NAIF IDs
+ * will return -1, indicating no match to a NOVAS planet ID.
  *
  *
  * @param id      The NAIF ID of the major planet of interest
@@ -46,7 +46,9 @@ enum novas_planet naif_to_novas_planet(long id) {
     case NAIF_SSB:
       return NOVAS_SSB;
     case NAIF_EMB:
-      return novas_error(-1, EINVAL, "naif_to_novas_planet", "No NOVAS ID for EMB (NAIF=%ld)", NAIF_EMB);
+      return NOVAS_EMB;
+    case NAIF_PLUTO_BARYCENTER:
+      return NOVAS_PLUTO_BARYCENTER;
   }
 
   // Major planets
@@ -60,7 +62,7 @@ enum novas_planet naif_to_novas_planet(long id) {
 
 /**
  * Converts a NOVAS Solar-system body ID to a NAIF Solar-system body ID. NOVAS and NAIF use slightly different IDs for
- * major planets, the Moon, and the Solar-system Barycenter (SSB). In NOVAS, major planets are have IDs ranging from
+ * major planets, the Moon, SSB, EMB, and the Pluto system. In NOVAS, major planets are have IDs ranging from
  * 1 through 9, but for NAIF 1--9 are the planetary barycenters and the planet centers have numbers in the hundreds
  * ending with 99 (e.g. the center of Earth is NAIF 399; 3 is the NOVAS ID for Earth and the NAIF ID for the Earth-Moon
  * Barycenter [EMB]). The Sun and Moon also have distinct IDs in NAIF vs NOVAS.
@@ -85,6 +87,10 @@ long novas_to_naif_planet(enum novas_planet id) {
       return NAIF_MOON;
     case NOVAS_SSB:
       return NAIF_SSB;
+    case NOVAS_EMB:
+      return NAIF_EMB;
+    case NOVAS_PLUTO_BARYCENTER:
+      return NAIF_PLUTO_BARYCENTER;
     default:
       return novas_error(-1, EINVAL, "novas_to_naif_planet", "Invalid NOVAS major planet no: %d", id);
   }
@@ -117,6 +123,10 @@ long novas_to_dexxx_planet(enum novas_planet id) {
       return NAIF_MOON;
     case NOVAS_SSB:
       return NAIF_SSB;
+    case NOVAS_EMB:
+      return NAIF_EMB;
+    case NOVAS_PLUTO_BARYCENTER:
+      return NAIF_PLUTO_BARYCENTER;
     default:
       return (id >= NOVAS_MERCURY && id <= NOVAS_PLUTO) ?
               (long) id :

diff --git a/src/novas.c b/src/novas.c
@@ -648,7 +648,7 @@ int set_planet_provider(novas_planet_provider func) {
 
 /**
  * Returns the custom (low-precision) ephemeris provider function for major planets
- * (and Sun, Moon, SSB), if any.
+ * (and Sun, Moon, SSB...), if any.
  *
  * @return    the custom (low-precision) planet ephemeris provider function.
  *
@@ -689,7 +689,7 @@ int set_planet_provider_hp(novas_planet_provider_hp func) {
 
 /**
  * Returns the custom high-precision ephemeris provider function for major planets
- * (and Sun, Moon, SSB), if any.
+ * (and Sun, Moon, SSB...), if any.
  *
  * @return    the custom high-precision planet ephemeris provider function.
  *
@@ -6478,7 +6478,7 @@ short make_object(enum novas_object_type type, long number, const char *name, co
 }
 
 /**
- * Sets a celestial object to be a major planet, or the Sun, Moon or Solar-system Barycenter.
+ * Sets a celestial object to be a major planet, or the Sun, Moon, Solar-system Barycenter, etc.
  *
  * @param num           Planet ID number (NOVAS convention)
  * @param[out] planet   Pointer to structure to populate.

diff --git a/src/solsys-calceph.c b/src/solsys-calceph.c
@@ -143,7 +143,7 @@ int novas_calceph_use_ids(enum novas_id_type idtype) {
  *                       split any way (although the first element is usually the
  *                       "integer" part, and the second element is the "fractional"
  *                       part).  Julian date is on the TDB or "T_eph" time scale.
- * @param body           Major planet number (or that for Sun, Moon, or Solar-system barycenter)
+ * @param body           Major planet number (or that for Sun, Moon, SSB...)
  * @param origin         NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1)
  *                       -- relative to which to report positions and velocities.
  * @param[out] position  [AU] Position vector of 'body' at jd_tdb; equatorial rectangular
@@ -242,7 +242,7 @@ static short planet_calceph_hp(const double jd_tdb[2], enum novas_planet body, e
  *                       split any way (although the first element is usually the
  *                       "integer" part, and the second element is the "fractional"
  *                       part).  Julian date is on the TDB or "T_eph" time scale.
- * @param body           Major planet number (or that for Sun, Moon, or Solar-system barycenter)
+ * @param body           Major planet number (or that for Sun, Moon, SSB...)
  * @param origin         NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1), or 2 for Earth geocenter
  *                       -- relative to which to report positions and velocities.
  * @param[out] position  [AU] Position vector of 'body' at jd_tdb; equatorial rectangular
@@ -363,7 +363,8 @@ static int novas_calceph(const char *name, long id, double jd_tdb_high, double j
  *
  * The call also make CALCEPH the default ephemeris provider for all types of Solar-system objects. If you
  * want to use another provider for major planets, you need to call set_planet_provider() /
- * set_planet_provider_hp() afterwards to specify a different provider for major planets (and Sun, Moon, SSB).
+ * set_planet_provider_hp() afterwards to specify a different provider for major planets (and Sun, Moon,
+ * SSB...).
  *
  * @param eph   Pointer to the CALCEPH ephemeris data that have been opened.
  * @return  0 if successful, or else -1 (errno will indicate the type of error).
@@ -403,9 +404,9 @@ int novas_use_calceph(t_calcephbin *eph) {
 
 /**
  * Sets the CALCEPH C library and the specified ephemeris data as the ephemeris provider for the major planets
- * (and Sun, Moon, and SSB).
+ * (and Sun, Moon, SSB...).
  *
- * @param eph   Pointer to the CALCEPH ephemeris data for the major planets (including Sun, Moon, and SSB) that
+ * @param eph   Pointer to the CALCEPH ephemeris data for the major planets (including Sun, Moon, SSB...) that
  *              have been opened.
  * @return  0 if successful, or else -1 (errno will indicate the type of error).
  *