![]() |
SuperNOVAS v1.5
The NOVAS C library, made better
|
Macros | |
#define | DE405_AU 1.4959787069098932e+11 |
[m] Astronomical unit (AU). | |
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_origin { NOVAS_BARYCENTER = 0 , NOVAS_HELIOCENTER } |
The origin of the ICRS system for referencing positions and velocities for solar-system bodies. More... | |
enum | novas_reference_plane { NOVAS_ECLIPTIC_PLANE = 0 , NOVAS_EQUATORIAL_PLANE } |
The plane in which values, such as orbital parameters are referenced. More... | |
Functions | |
int | cspice_add_kernel (const char *filename) |
Adds a SPICE kernel to the currently managed open kernels. | |
int | cspice_remove_kernel (const char *filename) |
Removes a SPICE kernel from the currently managed open kernels. | |
short | earth_sun_calc (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
Provides the position and velocity of the Earth and Sun only at epoch 'jd_tdb' by evaluating a closed-form theory without reference to an external file. | |
short | earth_sun_calc_hp (const double jd_tdb[restrict 2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
It may provide the position and velocity of the Earth and Sun, the same as earth_sun_calc(), if enable_earth_sun_hp() is set to true (non-zero). | |
void | enable_earth_sun_hp (int value) |
Specify whether the high-precision call is allowed to return a low-precision result. | |
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_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. | |
double | novas_helio_dist (double jd_tdb, const object *restrict source, double *restrict rate) |
Returns a Solar-system body's distance from the Sun, and optionally also the rate of recession. | |
double | novas_solar_power (double jd_tdb, const object *restrict source) |
Returns the typical incident Solar power on a Solar-system body at the time of observation. | |
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 | obs_planets (double jd_tdb, enum novas_accuracy accuracy, const double *restrict pos_obs, int pl_mask, novas_planet_bundle *restrict planets) |
Calculates the positions and velocities for the Solar-system bodies, e.g. | |
short | planet_ephem_provider (double jd_tdb, enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine. | |
short | planet_ephem_provider_hp (const double jd_tdb[restrict 2], enum novas_planet body, enum novas_origin origin, double *restrict position, double *restrict velocity) |
Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine. | |
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. | |
#define DE405_AU 1.4959787069098932e+11 |
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_origin |
The origin of the ICRS system for referencing positions and velocities for solar-system bodies.
Enumerator | |
---|---|
NOVAS_BARYCENTER | Origin at the Solar-system baricenter (i.e. BCRS) |
NOVAS_HELIOCENTER | Origin at the center of the Sun. |
The plane in which values, such as orbital parameters are referenced.
Enumerator | |
---|---|
NOVAS_ECLIPTIC_PLANE | the plane of the ecliptic |
NOVAS_EQUATORIAL_PLANE | The plane of the equator. |
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_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") |
short earth_sun_calc | ( | double | jd_tdb, |
enum novas_planet | body, | ||
enum novas_origin | origin, | ||
double *restrict | position, | ||
double *restrict | velocity ) |
Provides the position and velocity of the Earth and Sun only at epoch 'jd_tdb' by evaluating a closed-form theory without reference to an external file.
This function can also provide the position and velocity of the Sun.
REFERENCES:
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date | |
body | NOVAS_EARTH (3) or NOVAS_SUN (10) only. | |
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. |
References NOVAS_BARYCENTER, NOVAS_EARTH, NOVAS_PLANETS, NOVAS_SSB, NOVAS_SUN, precession(), radec2vector(), sun_eph(), and TWOPI.
short earth_sun_calc_hp | ( | const double | jd_tdb[restrict 2], |
enum novas_planet | body, | ||
enum novas_origin | origin, | ||
double *restrict | position, | ||
double *restrict | velocity ) |
It may provide the position and velocity of the Earth and Sun, the same as earth_sun_calc(), if enable_earth_sun_hp() is set to true (non-zero).
Otherwise, it will return with an error code of 3, indicating that high-precision calculations are not provided by this implementation.
NOTES:
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date | |
body | NOVAS_EARTH (3) or NOVAS_SUN (10) only. | |
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. |
References earth_sun_calc().
void enable_earth_sun_hp | ( | int | value | ) |
Specify whether the high-precision call is allowed to return a low-precision result.
If set to 0 (false) solarsystem_earth_sun_hp() will return with an error code 3 indicating that a high-precision calculation is not possible. Otherise, a non-zero value (true) will let the function to be used without errors, returning the low-precison result of solarsystem_earth_sun() instead.
value | (boolean) A non-zero value enables the error-free use of the earth_sun_calc_hp() by allowing to return the low-precision result. Otherwise, earth_sun_calc_hp() will return an error code 3 indicating that the high-precision result is not available (this latter is the default behavior). |
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_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.
double novas_helio_dist | ( | double | jd_tdb, |
const object *restrict | source, | ||
double *restrict | rate ) |
Returns a Solar-system body's distance from the Sun, and optionally also the rate of recession.
It may be useful, e.g. to calculate the body's heating from the Sun.
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated from the source. | |
source | Observed Solar-system source | |
[out] | rate | [AU/day] (optional) Returned rate of recession from Sun |
References ephemeris(), NOVAS_CATALOG_OBJECT, NOVAS_HELIOCENTER, NOVAS_REDUCED_ACCURACY, and novas_vlen().
double novas_solar_power | ( | double | jd_tdb, |
const object *restrict | source ) |
Returns the typical incident Solar power on a Solar-system body at the time of observation.
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date. You may want to use a time that is antedated to when the observed light originated ( was reflected) from the source. |
source | Observed Solar-system source |
References novas_helio_dist(), and NOVAS_SOLAR_CONSTANT.
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().
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().
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().
int obs_planets | ( | double | jd_tdb, |
enum novas_accuracy | accuracy, | ||
const double *restrict | pos_obs, | ||
int | pl_mask, | ||
novas_planet_bundle *restrict | planets ) |
Calculates the positions and velocities for the Solar-system bodies, e.g.
for use for gravitational deflection calculations. The planet positions are calculated relative to the observer location, while velocities are w.r.t. the SSB. Both positions and velocities are antedated for light travel time, so they accurately reflect the apparent position (and barycentric motion) of the bodies from the observer's perspective.
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date | |
accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1). In full accuracy mode, it will calculate the deflection due to the Sun, Jupiter, Saturn and Earth. In reduced accuracy mode, only the deflection due to the Sun is calculated. | |
pos_obs | [AU] Position 3-vector of observer (or the geocenter), with respect to origin at solar system barycenter, referred to ICRS axes. | |
pl_mask | Bitwise (1 << planet-number) mask indicating which planets to request data for. See enum novas_planet for the enumeration of planet numbers. | |
[out] | planets | Pointer to apparent planet data to populate. The planets with non-zero mask bits will have have positions and velocities calculated. See enum novas_planet for the enumeration of planet numbers. |
References light_time2(), make_planet(), novas_debug(), NOVAS_DEBUG_EXTRA, NOVAS_DEBUG_OFF, novas_get_debug_mode(), NOVAS_PLANETS, and NOVAS_SUN.
short planet_ephem_provider | ( | double | jd_tdb, |
enum novas_planet | body, | ||
enum novas_origin | origin, | ||
double *restrict | position, | ||
double *restrict | velocity ) |
Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.
This is the regular (reduced) precision version, but in reality it's exactly the same as the high-precision version, except for the way the TDB-based Julian date is specified.
jd_tdb | [day] Barycentric Dynamical Time (TDB) based Julian date. | |
body | Major planet number (or that for Sun, Moon, SSB...) | |
origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities. | |
[out] | position | [AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS. |
[out] | velocity | [AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day. |
References planet_ephem_provider_hp().
short planet_ephem_provider_hp | ( | const double | jd_tdb[restrict 2], |
enum novas_planet | body, | ||
enum novas_origin | origin, | ||
double *restrict | position, | ||
double *restrict | velocity ) |
Major planet ephemeris data via the same generic ephemeris provider that is configured by set_ephem_provider() prior to calling this routine.
This is the highest precision version.
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. | |
body | Major planet number (or that for Sun, Moon, SSB...) | |
origin | NOVAS_BARYCENTER (0) or NOVAS_HELIOCENTER (1) relative to which to report positions and velocities. | |
[out] | position | [AU] Position vector of 'body' at jd_tdb; equatorial rectangular coordinates in AU referred to the ICRS. |
[out] | velocity | [AU/day] Velocity vector of 'body' at jd_tdb; equatorial rectangular system referred to the ICRS, in AU/day. |
References get_ephem_provider(), NOVAS_BARYCENTER, NOVAS_HELIOCENTER, NOVAS_PLANET_NAMES_INIT, NOVAS_PLANETS, NOVAS_SSB, and NOVAS_SUN.
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. |
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. |
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. |