 |
SuperNOVAS C++ API v1.6
High-precision C/C++ astrometry library
|
|
SuperNOVAS C++ API v1.6
High-precision C/C++ astrometry library
|
Defining how ephemeris positions for Solar-system objects are provided. More...
Typedefs | |
| typedef int(* | novas_ephem_provider) (const char *name, long id, double jd_tdb_high, double jd_tdb_low, enum novas_origin *restrict origin, double *restrict pos, double *restrict vel) |
| Function to obtain ephemeris data for minor planets, which are not handled by the solarsystem() type calls. | |
| typedef short(* | novas_planet_provider) (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
| Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters). | |
| typedef short(* | novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
| Provides the position and velocity of major planets (as well as the Sun, Moon, Solar-system Barycenter, and other barycenters). | |
Enumerations | |
| enum | novas_id_type { NOVAS_ID_NAIF = 0 , NOVAS_ID_CALCEPH } |
| Solar-system body IDs to use as object.number with ephemeris source types. More... | |
Functions | |
| int | cspice_add_kernel (const char *filename) |
| Adds a SPICE kernel to the currently managed open kernels. | |
| int | cspice_clear_kernels () |
| Closes and removes all SPICE kernels currently configured, freeing up the associated resources. | |
| int | cspice_remove_kernel (const char *filename) |
| Removes a SPICE kernel from the currently managed open kernels. | |
| novas_ephem_provider | get_ephem_provider () |
| Returns the user-defined ephemeris accessor function. | |
| novas_planet_provider | get_planet_provider () |
| Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any. | |
| novas_planet_provider_hp | get_planet_provider_hp () |
| Returns the custom high-precision ephemeris provider function for major planets (and Sun, Moon, SSB...), if any. | |
| int | novas_calceph_is_thread_safe () |
| Checks if the CALCEPH plugin is thread safe. | |
| int | novas_calceph_use_ids (enum novas_id_type idtype) |
| Sets the type of Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types. | |
| int | novas_cspice_is_thread_safe () |
| Checks if the CSPICE plugin is thread safe. | |
| int | novas_use_calceph (t_calcephbin *eph) |
| Sets a ephemeris provider for Solar-system objects using the CALCEPH C library and the specified set of ephemeris files. | |
| int | novas_use_calceph_planets (t_calcephbin *eph) |
| Sets the CALCEPH C library and the specified ephemeris data as the ephemeris provider for the major planets (and Sun, Moon, SSB...). | |
| int | novas_use_cspice () |
| Sets CSPICE as the default ephemeris provider for all types of Solar-system objects (both NOVAS_PLANET and NOVAS_EPHEM_OBJECT types). | |
| int | novas_use_cspice_ephem () |
| Sets a ephemeris provider for NOVAS_EPHEM_OBJECT types using the NAIF CSPICE library. | |
| int | novas_use_cspice_planets () |
| Sets CSPICE as the ephemeris provider for the major planets (and Sun, Moon, SSB...) using the NAIF CSPICE library. | |
| int | set_ephem_provider (novas_ephem_provider func) |
| Sets the function to use for obtaining position / velocity information for minor planets, or satellites. | |
| int | set_planet_provider (novas_planet_provider func) |
| Set a custom function to use for regular precision (see NOVAS_REDUCED_ACCURACY) ephemeris calculations instead of the default solarsystem() routine. | |
| int | set_planet_provider_hp (novas_planet_provider_hp func) |
| Set a custom function to use for high precision (see NOVAS_FULL_ACCURACY) ephemeris calculations instead of the default solarsystem_hp() routine. | |
Defining how ephemeris positions for Solar-system objects are provided.
SuperNOVAS does not have a integral way for handling Solar-system ephemerides. By default it can calculate approximate positions / velocities for the Sun and Earth only. Thus, to enable proper calculations involving Solar-system bodies you must interface to libraries like CALCEPH or CSPICE, or else to externally provided plugin functions.
| typedef int(* novas_ephem_provider) (const char *name, long id, double jd_tdb_high, double jd_tdb_low, enum novas_origin *restrict origin, double *restrict pos, double *restrict vel) |
Function to obtain ephemeris data for minor planets, which are not handled by the solarsystem() type calls.
The library does not provide a default implementation, but users can provide their own, either as a default statically compiled readeph() implementation, or else a dynamically defined one via ephemeris_set_reader().
Note, that implementations would typically use either the name or the ID argument to identify the object for which ephemeris data is requested. As such you only need to specify the one that is going to be used.
| name | The name of the solar-system body (in case the ephemeris provider supports lookup by name), or NULL to force ID based lookup. | |
| id | The ID number of the solar-system body for which the position in desired. (Typically a NAIF ID, or else an appropriate ID for the implementation – corresponding minor planet objects should be created with the same type of ID.). A value of -1 can be used to force name based lookups (provided the implementation supports it). | |
| jd_tdb_high | [day] The high-order part of Barycentric Dynamical Time (TDB) based Julian date for which to find the position and velocity. Typically this may be the integer part of the Julian date for high-precision calculations, or else the entire Julian date for reduced precision. | |
| jd_tdb_low | [day] The low-order part of Barycentric Dynamical Time (TDB) based Julian date for which to find the position and velocity. Typically this may be the fractional part of the Julian date for high-precision calculations, or else 0.0 if the date is defined entirely by the high-order component for reduced precision. | |
| [out] | origin | Set to NOVAS_BARYCENTER or NOVAS_HELIOCENTER to indicate relative to which the ephemeris positions/velocities are reported. |
| [out] | pos | [AU] position 3-vector to populate with rectangular equatorial coordinates in AU. It may be NULL if position is not required. |
| [out] | vel | [AU/day] velocity 3-vector to populate in rectangular equatorial coordinates in AU/day. It may be NULL if velocities are not required. |
| typedef short(* novas_planet_provider) (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
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).
| jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date | |
| 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). | |
| origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here). | |
| [out] | position | [AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0. |
| [out] | velocity | [AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day. |
| typedef short(* novas_planet_provider_hp) (const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
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 keep the original argument types for compatibility, hence 'short' instead of the more informative enums).
| 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. | |
| 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). | |
| origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to return positions and velocities. (For compatibility with existing NOVAS C compatible user implementations, we keep the original NOVAS C argument type here). | |
| [out] | position | [AU] Position vector of 'body' at 'tjd'; equatorial rectangular coordinates in AU referred to the mean equator and equinox of J2000.0. |
| [out] | velocity | [AU/day] Velocity vector of 'body' at 'tjd'; equatorial rectangular system referred to the mean equator and equinox of J2000.0, in AU/Day. |
| enum novas_id_type |
Solar-system body IDs to use as object.number with ephemeris source types.
JPL ephemerides use NAIF IDs to identify objects in the Solar-system, which is thus the most widely adopted convention for numbering Solar-system bodies. But other numbering systems also exists, for example the CALCEPH library uses its own convention for the numbering of asteroids.
| Enumerator | |
|---|---|
| NOVAS_ID_NAIF | If the ephemeris provider should use NAIF IDs. |
| NOVAS_ID_CALCEPH | If the ephemeris provider should use CALCEPH IDs. |
| int cspice_add_kernel | ( | const char * | filename | ) |
Adds a SPICE kernel to the currently managed open kernels.
Subsequent ephemeris lookups through CSPICE will use the added kernel. It's simply a wrapper around the CSPICE furnsh_c() routine, with graceful error handling. You can of course add kernels using furnsh_c() directly to the same effect.
REFERENCES:
| filename | The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp") |
| int cspice_clear_kernels | ( | ) |
Closes and removes all SPICE kernels currently configured, freeing up the associated resources.
However CSPICE will remain your ephemeris provider for planets and/or ephemeris type objects, as configured before.
| int cspice_remove_kernel | ( | const char * | filename | ) |
Removes a SPICE kernel from the currently managed open kernels.
Subsequent ephemeris lookups through CSPICE will not use the removed kernel data. It's simply a wrapper around the CSPICE unload_c() routine, with graceful error handling. You can of course remove kernels using unload_c() directly to the same effect.
REFERENCES:
| filename | The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp") |
| novas_ephem_provider get_ephem_provider | ( | ) |
Returns the user-defined ephemeris accessor function.
Referenced by ephemeris(), and planet_ephem_provider_hp().
| novas_planet_provider get_planet_provider | ( | ) |
Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.
| novas_planet_provider_hp get_planet_provider_hp | ( | ) |
Returns the custom high-precision ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.
| int novas_calceph_is_thread_safe | ( | ) |
Checks if the CALCEPH plugin is thread safe.
| int novas_calceph_use_ids | ( | enum novas_id_type | idtype | ) |
Sets the type of Solar-system body IDs to use as object.number with NOVAS_EPHEM_OBJECT types.
CALCEPH supports the use of both NAIF and its own numbering system to identify Solar-system bodies. So, this function gives you the choice on which numbering system you want to use in object data structures. The choice does not affect major planets (which always use the NOVAS numbering scheme), or catalog objects.
| idtype | NOVAS_ID_NAIF to use NAIF IDs (default) or else NOVAS_ID_CALCEPH to use the CALCEPH body numbering convention for object. |
References NOVAS_ID_CALCEPH, and NOVAS_ID_NAIF.
| int novas_cspice_is_thread_safe | ( | ) |
Checks if the CSPICE plugin is thread safe.
| int novas_use_calceph | ( | t_calcephbin * | eph | ) |
Sets a ephemeris provider for Solar-system objects using the CALCEPH C library and the specified set of ephemeris files.
If the supplied ephemeris files contain data for major planets also, they can be used by planet_calceph() / planet_calceph_hp() also, unless a separate CALCEPH ephemeris data is set via novas_use_calceph_planets().
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 the major planets (and Sun, Moon, SSB...).
| eph | Pointer to the CALCEPH ephemeris data that have been opened. |
References novas_use_calceph_planets(), and set_ephem_provider().
| int novas_use_calceph_planets | ( | t_calcephbin * | eph | ) |
Sets the CALCEPH C library and the specified ephemeris data as the ephemeris provider for the major planets (and Sun, Moon, SSB...).
| eph | Pointer to the CALCEPH ephemeris data for the major planets (including Sun, Moon, SSB...) that have been opened. |
References set_planet_provider(), and set_planet_provider_hp().
Referenced by novas_use_calceph().
| int novas_use_cspice | ( | ) |
Sets CSPICE as the default ephemeris provider for all types of Solar-system objects (both NOVAS_PLANET and NOVAS_EPHEM_OBJECT types).
CSPICE is configured to suppress error messages and to not exit on errors, since we will check errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.
References novas_use_cspice_ephem(), and novas_use_cspice_planets().
| int novas_use_cspice_ephem | ( | ) |
Sets a ephemeris provider for NOVAS_EPHEM_OBJECT types using the NAIF CSPICE library.
CSPICE is configured to suppress error messages and to not exit on errors, since we will check errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.
References set_ephem_provider().
Referenced by novas_use_cspice().
| int novas_use_cspice_planets | ( | ) |
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 errors and handle them ourselves. You can adjust the behavior after this call with the CSPICE errprt_c() and erract_c() functions, respectively.
References set_planet_provider(), and set_planet_provider_hp().
Referenced by novas_use_cspice().
| int set_ephem_provider | ( | novas_ephem_provider | func | ) |
Sets the function to use for obtaining position / velocity information for minor planets, or satellites.
| func | new function to use for accessing ephemeris data for minor planets or satellites. |
Referenced by novas_use_calceph(), and novas_use_cspice_ephem().
| int set_planet_provider | ( | novas_planet_provider | func | ) |
Set a custom function to use for regular precision (see NOVAS_REDUCED_ACCURACY) ephemeris calculations instead of the default solarsystem() routine.
| func | The function to use for solar system position/velocity calculations. See solarsystem() for further details on what is required of this function. |
Referenced by novas_use_calceph_planets(), and novas_use_cspice_planets().
| int set_planet_provider_hp | ( | novas_planet_provider_hp | func | ) |
Set a custom function to use for high precision (see NOVAS_FULL_ACCURACY) ephemeris calculations instead of the default solarsystem_hp() routine.
| func | The function to use for solar system position/velocity calculations. See solarsystem_hp() for further details on what is required of this function. |
Referenced by novas_use_calceph_planets(), and novas_use_cspice_planets().
1.16.1