From b6c010b53bfcff9db500e02b67dbf48543b51c0c Mon Sep 17 00:00:00 2001 From: Attila Kovacs Date: Thu, 14 Nov 2024 12:53:13 +0100 Subject: [PATCH] Update API docs for added barycenters --- include/solarsystem.h | 33 +++++++++++++++++---------------- src/naif.c | 10 +++++----- src/novas.c | 6 +++--- src/solsys-calceph.c | 11 ++++++----- src/solsys-cspice.c | 6 +++--- src/solsys-ephem.c | 4 ++-- src/solsys1.c | 4 ++-- src/solsys2.c | 4 ++-- 8 files changed, 40 insertions(+), 38 deletions(-) diff --git a/include/solarsystem.h b/include/solarsystem.h index 0d434854..f73a8cea 100644 --- 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,8 +67,8 @@ 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 @@ -75,8 +76,8 @@ enum novas_id_type { * 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). diff --git a/src/naif.c b/src/naif.c index 1f29498a..b22fdebf 100644 --- 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 n99 (e.g. 399 for Earth), are mapped to the corresponding NOVAS planet number - * n. 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 + * n99 (e.g. 399 for Earth) are mapped to the corresponding NOVAS planet number n. 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 @@ -62,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. diff --git a/src/novas.c b/src/novas.c index 0f90cd2d..efea8e62 100644 --- 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 index c8d05bda..0f416bf6 100644 --- 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). * diff --git a/src/solsys-cspice.c b/src/solsys-cspice.c index 8e7b138e..6320af3b 100644 --- a/src/solsys-cspice.c +++ b/src/solsys-cspice.c @@ -221,7 +221,7 @@ int cspice_remove_kernel(const char *filename) { * 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 @@ -327,7 +327,7 @@ static short planet_cspice_hp(const double jd_tdb[2], enum novas_planet body, en * 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 @@ -490,7 +490,7 @@ int novas_use_cspice_ephem() { } /** - * Sets CSPICE as the ephemeris provider for the major planets (and Sun, Moon, and SSB) using the + * Sets CSPICE as the ephemeris provider for the major planets (and Sun, Moon, SSB...) using the * NAIF CSPICE library. * * CSPICE is configured to suppress error messages and to not exit on errors, since we will check diff --git a/src/solsys-ephem.c b/src/solsys-ephem.c index 710cb411..8cb7d6a7 100644 --- a/src/solsys-ephem.c +++ b/src/solsys-ephem.c @@ -27,7 +27,7 @@ * @param jd_tdb [day] Barycentric Dynamical Time (TDB) based Julian date, split into * high and low order components (e.g. integer and fractional parts) for * high-precision calculations. - * @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 @@ -86,7 +86,7 @@ short planet_ephem_provider_hp(const double jd_tdb[2], enum novas_planet body, e * version. * * @param jd_tdb [day] Barycentric Dynamical Time (TDB) based Julian date. - * @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 diff --git a/src/solsys1.c b/src/solsys1.c index 33af5c75..5792471e 100644 --- a/src/solsys1.c +++ b/src/solsys1.c @@ -59,7 +59,7 @@ * 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 @@ -151,7 +151,7 @@ short planet_eph_manager_hp(const double jd_tdb[2], enum novas_planet body, enum * 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 diff --git a/src/solsys2.c b/src/solsys2.c index aac00c0b..3c9e4082 100644 --- a/src/solsys2.c +++ b/src/solsys2.c @@ -67,7 +67,7 @@ extern void jplihp_(const double *jd_tdb, long *targ, long *cent, double *posvel * 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 @@ -159,7 +159,7 @@ short planet_jplint(double jd_tdb, enum novas_planet body, enum novas_origin ori * 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