From 76b6dbee557504f41fee1340bd17ae861b70a342 Mon Sep 17 00:00:00 2001 From: Attila Kovacs Date: Thu, 14 Nov 2024 13:37:42 +0100 Subject: [PATCH] doc updates --- CHANGELOG.md | 16 +++++++++++++--- README.md | 26 ++++++++++++++++++++++++++ include/novas.h | 23 ++++++++++++----------- 3 files changed, 51 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b0c835c..0f2c0982 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,15 +56,25 @@ Changes expected for the next feature release, expected around 1 February 2025. You can also set other standard directory variables, as prescribed in the [GNU standard](https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) to further customize the install locations. - - - 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. + + - #95: Added support for using orbital elements. `object.type` can now be set to `NOVAS_ORBITAL_OBJECT`, whose orbit + can be defined by the set of `novas_orbital_elements`, within a `novas_orbital_system`. You can initialize an + `object` with a set of orbital elements using `make_orbital_object()`. For such objects, `ephemeris()` will now + call on the new `novas_orbit_posvel()` to calculate positions. While orbital elements do not always yield precise + positions, they can for shorter periods, provided that the orbital elements are up-to-date. For example, the Minor + Planer Center (MPC) publishes orbital elements for all known asteroids and comets regularly. For newly discovered + objects, this may be the only and/or most accurate information available anywhere. - #97: Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish from the planet center in calculations. + - 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. + ### Changed + - #96: Changed `object` structure to include `novas_orbital_elements` for `NOVAS_ORBITAL_OBJECT` types. + - #97: Updated `NOVAS_PLANETS`, `NOVAS_PLANET_NAMES_INIT` and `NOVAS_RMASS_INIT` macros to include the added planet constants. diff --git a/README.md b/README.md index e728c219..7d6dbeca 100644 --- a/README.md +++ b/README.md @@ -596,6 +596,24 @@ more generic ephemeris handling via a user-provided `novas_ephem_provider`. E.g. make_ephem_object("Ceres", 2000001, &ceres); ``` +As of version 1.2 you can also define solar system sources with orbital elements (such as the most up-to-date ones +provided by the [Minor Planet Center](https://minorplanetcenter.net/data) for asteroids, comets, etc.): + +```c + object NEA; // e.g. a Near-Earth Asteroid + + // Fill in the orbital parameters (pay attention to units!) + novas_orbital_elements orbit = NOVAS_ORBIT_INIT; + orbit.a = ...; + ... + + // Create an object for that orbit + make_orbital_object("NEAxxx", -1, &orbit, object); +``` + +Note, that even with orbital elements, you will, in general, require a planet calculator, to provide precise +positions for the Sun or planet, around which the orbit is defined. + Other than that, it's the same spiel as before, e.g.: ```c @@ -894,6 +912,14 @@ before that level of accuracy is reached. - Added `novas_planet_for_name()` function to return the NOVAS planet ID for a given (case insensitive) name. + - Added support for using orbital elements. `object.type` can now be set to `NOVAS_ORBITAL_OBJECT`, whose orbit + can be defined by the set of `novas_orbital_elements`, within a `novas_orbital_system`. You can initialize an + `object` with a set of orbital elements using `make_orbital_object()`. For such objects, `ephemeris()` will now + call on the new `novas_orbit_posvel()` to calculate positions. While orbital elements do not always yield precise + positions, they can for shorter periods, provided that the orbital elements are up-to-date. For example, the Minor + Planer Center (MPC) publishes orbital elements for all known asteroids and comets regularly. For newly discovered + objects, this may be the only and/or most accurate information available anywhere. + - Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish from the corresponding planet centers in calculations. diff --git a/include/novas.h b/include/novas.h index 4c1eb611..101c6472 100644 --- a/include/novas.h +++ b/include/novas.h @@ -640,8 +640,8 @@ typedef struct { /** * Specification of an orbital system, in which orbital elements are defined. Systems can be defined around - * all major planets (and Sun, Moon, SSB). They may be referenced to the GCRS, mean, or true equator or ecliptic - * of date, or to a plane that is tilted relative to that. + * all major planets and barycenters (and Sun, Moon, SSB..). They may be referenced to the GCRS, mean, or true equator + * or ecliptic of date, or to a plane that is tilted relative to that. * * For example, The Minor Planet Center (MPC) publishes up-to-date orbital elements for asteroids and comets, * which are heliocentric and referenced to the GCRS ecliptic. Hence 'center' for these is `NOVAS_SUN`, the `plane` @@ -649,10 +649,11 @@ typedef struct { * * The orbits of planetary satellites may be parametrized in their local Laplace planes, which are typically close * to the host planet's equatorial planes. You can, for example, obtain the RA/Dec orientation of the planetary - * North poles of planets from JPL Horizons, and use them as a proxy for the Laplace planes of their satellite orbits. + * North poles of planets from JPL Horizons, and use them as a proxy for the Laplace planes for their satellite orbits. * In this case you would set the `center` to the host planet (e.g. `NOVAS_SATURN`), the reference plane to - * `NOVAS_EQUATORIAL_PLANE` and the `type` to `NOVAS_GCRS_EQUATOR` (since the equator's orientation is defined in - * GCRS equatorial RA/Dec). The obliquity is then 90° - Dec (in radians), and `phi` is RA (in radians). + * `NOVAS_EQUATORIAL_PLANE` and the `type` to `NOVAS_GCRS_EQUATOR` (since the plane is defined by the North pole + * orientation in GCRS equatorial RA/Dec). The obliquity is then 90° - Decpole (in radians), and `phi` + * is RApole (in radians). * * @author Attila Kovacs * @since 1.2 @@ -660,11 +661,11 @@ typedef struct { * @sa novas_orbital_elements */ typedef struct { - enum novas_planet center; ///< major body at the center of the orbit (default is NOVAS_SUN). + enum novas_planet center; ///< major planet or barycenter at the center of the orbit (default is NOVAS_SUN). enum novas_reference_plane plane; ///< reference plane NOVAS_ECLIPTIC_PLANE (default) or NOVAS_EQUATORIAL_PLANE enum novas_equator_type type; ///< the type of equator in which orientation is referenced (true, mean, or GCRS [default]). - double obl; ///< [rad] obliquity of orbital reference plane (e.g. 90° - Decpole) - double Omega; ///< [rad] argument of ascending node of the orbital reference plane (e.g. RApole) + double obl; ///< [rad] relative obliquity of orbital reference plane (e.g. 90° - Decpole) + double Omega; ///< [rad] relative argument of ascending node of the orbital reference plane (e.g. RApole) } novas_orbital_system; @@ -702,8 +703,8 @@ typedef struct { * @sa enum NOVAS_ORBITAL_OBJECT */ typedef struct { - novas_orbital_system system; ///< orbital reference system assumed for the paramtetrization - double jd_tdb; ///< [day] Barycentri Dynamical Time (TDB) based Julian date of parameters. + novas_orbital_system system; ///< orbital reference system assumed for the parametrization + double jd_tdb; ///< [day] Barycentri Dynamical Time (TDB) based Julian date of the parameters. double a; ///< [AU] semi-major axis double e; ///< eccentricity double omega; ///< [rad] argument of periapsis / perihelion @@ -714,7 +715,7 @@ typedef struct { } novas_orbital_elements; /** - * Initializer for novas_orbital_elements for heliocentric orbits + * Initializer for novas_orbital_elements for heliocentric orbits using GCRS ecliptic pqrametrization. * * @author Attila Kovacs * @since 1.2