Loading...
Searching...
No Matches
Solar-system ephemeris providers

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.

## Detailed Description

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 Documentation

## novas_ephem_provider

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.

Parameters

  | 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.

Returns
  0 if successful, -1 if any of the pointer arguments are NULL, or some non-zero value if the was an error s.t. the position and velocity vector should not be used.

See also
  set_ephem_provider(), ephemeris(), NOVAS_EPHEM_OBJECT, solsys-ephem.c
  make_ephem_object(), novas_sky_pos(), novas_geom_posvel()

Since
  1.0

Author
  Attila Kovacs

## novas_planet_provider

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).

Parameters

  | 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.

Returns
  0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the ephemeris data cannot be produced for other reasons.

See also
  set_planet_provider(), ephemeris(), novas_planet_provider_hp
  make_planet(), novas_sky_pos(), novas_geom_posvel()

Since
  1.0

Author
  Attila Kovacs

## novas_planet_provider_hp

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).

Parameters

  | 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.

Returns
  0 if successful, -1 if there is a required function is not provided (errno set to ENOSYS), 1 if the input Julian date ('tjd') is out of range, 2 if 'body' is invalid, or 3 if the ephemeris data cannot be produced for other reasons.

See also
  set_planet_provider_hp(), novas_planet_provider, ephemeris()
  make_planet(), novas_sky_pos(), novas_geom_posvel(), grav_planets(), grav_undo_planets()

Since
  1.0

Author
  Attila Kovacs

## Enumeration Type Documentation

## novas_id_type

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.

Author
  Attila Kovacs

Since
  1.2

Enumerator
NOVAS_ID_NAIF | If the ephemeris provider should use NAIF IDs.
NOVAS_ID_CALCEPH | If the ephemeris provider should use CALCEPH IDs.

## Function Documentation

## cspice_add_kernel()

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:

1. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/furnsh_c.html

Parameters

  filename | The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp")

Returns
  0 if successful, or else -1 if there was an error (errno will be set to EINVAL).

Author
  Attila Kovacs

Since
  1.2

See also
  cspice_remove_kernel(), cspice_clear_kernels(), novas_use_cspice()

## cspice_clear_kernels()

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.

Returns
  0 if successful, or else -1 (errno will be set to EAGAIN).

Author
  Attila Kovacs

Since
  1.6

See also
  cspice_remove_kernel(), cspice_add_kernel()

## cspice_remove_kernel()

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:

1. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/unload_c.html

Parameters

  filename | The fully qualified path to the ephemeris kernel data (e.g. "/data/ephem/de440s.bsp")

Returns
  0 if successful, or else -1 if there was an error (errno will be set to EINVAL).

Author
  Attila Kovacs

Since
  1.2

See also
  cspice_add_kernel(), cspice_clear_kernels()

## get_ephem_provider()

novas_ephem_provider get_ephem_provider | ( |  | ) |

Returns the user-defined ephemeris accessor function.

Returns
  the currently defined function for accessing ephemeris data for minor planets or satellites, ot NULL if no function was set via set_ephem_provider() previously.

Since
  1.0

Author
  Attila Kovacs

See also
  set_ephem_provider(), get_planet_provider(), get_planet_provider_hp(), ephemeris()

Referenced by ephemeris(), and planet_ephem_provider_hp().

## get_planet_provider()

novas_planet_provider get_planet_provider | ( |  | ) |

Returns the custom (low-precision) ephemeris provider function for major planets (and Sun, Moon, SSB...), if any.

Returns
  the custom (low-precision) planet ephemeris provider function.

Author
  Attila Kovacs

Since
  1.2

See also
  set_planet_provider(), get_planet_provider_hp(), get_ephem_provider()

## get_planet_provider_hp()

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.

Returns
  the custom high-precision planet ephemeris provider function.

Author
  Attila Kovacs

Since
  1.2

See also
  set_planet_provider_hp(), get_planet_provider(), get_ephem_provider()

## novas_calceph_is_thread_safe()

int novas_calceph_is_thread_safe | ( |  | ) |

Checks if the CALCEPH plugin is thread safe.

Returns
  TRUE (1) if the lugin is thread safe, or else FALSE (0).

Since
  1.5

## novas_calceph_use_ids()

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.

Parameters

  idtype | NOVAS_ID_NAIF to use NAIF IDs (default) or else NOVAS_ID_CALCEPH to use the CALCEPH body numbering convention for object.

Returns
  0 if successful or else -1 (errno set to EINVAL) if the input value is invalid.

See also
  make_planet(), make_ephem_object(), NOVAS_EPHEM_OBJECT

References NOVAS_ID_CALCEPH, and NOVAS_ID_NAIF.

## novas_cspice_is_thread_safe()

int novas_cspice_is_thread_safe | ( |  | ) |

Checks if the CSPICE plugin is thread safe.

Returns
  TRUE (1) if the lugin is thread safe, or else FALSE (0).

Since
  1.5

## novas_use_calceph()

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...).

Parameters

  eph | Pointer to the CALCEPH ephemeris data that have been opened.

Returns
  0 if successful, or else -1 (errno will indicate the type of error).

See also
  novas_calceph_use_ids(), novas_use_calceph_planets(), set_ephem_provider()

Author
  Attila Kovacs

Since
  1.2

References novas_use_calceph_planets(), and set_ephem_provider().

## novas_use_calceph_planets()

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...).

Parameters

  eph | Pointer to the CALCEPH ephemeris data for the major planets (including Sun, Moon, SSB...) that have been opened.

Returns
  0 if successful, or else -1 (errno will indicate the type of error).

Author
  Attila Kovacs

Since
  1.2

See also
  novas_use_calceph(), set_planet_provider(), set_planet_provider_hp()

References set_planet_provider(), and set_planet_provider_hp().

Referenced by novas_use_calceph().

## novas_use_cspice()

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.

Returns
  0

Author
  Attila Kovacs

Since
  1.2

See also
  novas_use_cspice_planets(), novas_use_cspice_ephem(), cspice_add_kernel()

References novas_use_cspice_ephem(), and novas_use_cspice_planets().

## novas_use_cspice_ephem()

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.

Returns
  0

Author
  Attila Kovacs

Since
  1.2

See also
  novas_use_cspice_planets(), novas_use_cspice(), cspice_add_kernel()
  set_ephem_provider()

References set_ephem_provider().

Referenced by novas_use_cspice().

## novas_use_cspice_planets()

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.

Returns
  0

Author
  Attila Kovacs

Since
  1.2

See also
  novas_use_cspice_ephem(), novas_use_cspice(), cspice_add_kernel()
  set_planet_provider(), set_planet_provider_hp()

References set_planet_provider(), and set_planet_provider_hp().

Referenced by novas_use_cspice().

## set_ephem_provider()

int set_ephem_provider | ( | novas_ephem_provider | func | ) |

Sets the function to use for obtaining position / velocity information for minor planets, or satellites.

Parameters

  func | new function to use for accessing ephemeris data for minor planets or satellites.

Returns
  0 if successful, or else -1 if the function argument is NULL.

Since
  1.0

Author
  Attila Kovacs

See also
  get_ephem_provider(), set_planet_provider(), set_planet_provider_hp()
  novas_use_calceph(), novas_use_cspice()

Referenced by novas_use_calceph(), and novas_use_cspice_ephem().

## set_planet_provider()

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.

Parameters

  func | The function to use for solar system position/velocity calculations. See solarsystem() for further details on what is required of this function.

Author
  Attila Kovacs

Since
  1.0

See also
  get_planet_provider(), set_planet_provider_hp(), NOVAS_REDUCED_ACCURACY
  novas_use_calceph(), novas_use_cspice()

Referenced by novas_use_calceph_planets(), and novas_use_cspice_planets().

## set_planet_provider_hp()

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.

Parameters

  func | The function to use for solar system position/velocity calculations. See solarsystem_hp() for further details on what is required of this function.

Author
  Attila Kovacs

Since
  1.0

See also
  get_planet_provider_hp(), set_planet_provider(), NOVAS_FULL_ACCURACY
  novas_use_calceph(), novas_use_cspice()

Referenced by novas_use_calceph_planets(), and novas_use_cspice_planets().