horizons¶

This module contains a wrapper for the JPL Horizons interface of the astroquery package

Classes¶

HorizonsQuery(query_id, location[, ...])

This class provides an interface to JPL's Horizon System.

HorizonsBatch(query_id_list, location[, ...])

class HorizonsQuery(query_id: str, location: str, query_type: str = 'default', epoch_start: datetime | float | None = None, epoch_end: datetime | float | None = None, epoch_step: str | None = None, epoch_list: list | None = None, extended_query: bool = False)[source]¶

This class provides an interface to JPL’s Horizon System. JPL Horizons provides access to highly accurate ephemerides for many solar system objects, including asteroids, comets, planets, moons and select spacecraft. The class extends astroquery’s to cater to the needs of Tudat users, while maintaining compatibility with all of astroquery’s features.

There are some notable differences:

Time input has been simplified to reduce ambiguities: - List of times are given in seconds since J2000 TDB. - Start can be given in datetime format or seconds since J2000 TDB. - Timesteps like months and years are not permitted.

And some additional features: - Extended query allows data retrieval limits to be broken by automatically splitting up a query into multiple subqueries and combining the data. - Ephemeris settings can automatically be generated using Vectors API.

cartesian(frame_orientation: str = 'ECLIPJ2000', aberations: str = 'geometric') → ndarray[source]¶

Retrieve the cartesian state using the Horizons Vector API.

Parameters:

  • frame_orientation (str, optional) –

    Reference Frame Orientation, equivalent to the astroquery refplane parameter. Options are ‘J2000’/’earth’, ‘ECLIPJ2000’/’ecliptic’ and ‘body’ , by default “ECLIPJ2000”. See astroquery documentation for information about the ‘body’ option:

    https://astroquery.readthedocs.io/en/latest/jplhorizons/jplhorizons.html

  • aberations (str, optional) –

    Aberations to be accounted for. Options are: ‘geometric’, ‘astrometric’ and ‘apparent’, by default “geometric”.

    See the Horizons System Manual for more info:

    https://ssd.jpl.nasa.gov/horizons/manual.html#output

Returns:

returns an n by 7 array with the time in seconds since J2000 TDB, and the cartesian position and velocities.

Return type:

np.ndarray

create_ephemeris_tabulated(frame_origin: str, frame_orientation: str = 'ECLIPJ2000', aberations: str = 'geometric') → EphemerisSettings[source]¶

Create ephemeris settings for a body using Horizons Vector API.

Parameters:

  • frame_origin (str) – Global frame origin, should match the queries’ location parameter.

  • frame_orientation (str, optional) – Reference Frame Orientation, equivalent to the astroquery refplane parameter. Options are ‘J2000’ and ‘ECLIPJ2000’, by default “ECLIPJ2000”.

  • aberations (str, optional) –

    Aberations to be accounted for. Options are: ‘geometric’, ‘astrometric’ and ‘apparent’, by default “geometric”.

    See the Horizons System Manual for more info:

    https://ssd.jpl.nasa.gov/horizons/manual.html#output

Returns:

Ephemeris settings for the query’s body.

Return type:

environment_setup.ephemeris.EphemerisSettings

Examples

Add Ephemerides of JUICE to the body_settings

>>> body_settings.add_empty_settings("JUICE")
>>> body_settings.get("JUICE").ephemeris_settings = query.create_ephemeris_tabulated(
        frame_origin=global_frame_origin,
        frame_orientation=global_frame_orientation,
    )
ephemerides(reference_system: str = 'J2000', extra_precision: bool = False, *args, **kwargs) → Table[source]¶

Implements the JPL Horizons ephemerides API and returns it in raw Astropy table format. Ephemerides API provides time-interpolated observer parameters such as right ascension and declination. Note that this means that values provided are not actual observations.

A number of quantities are retrieved, their definitions can be found here: https://ssd.jpl.nasa.gov/horizons/manual.html#obsquan. By default all available quantities are retrieved.

More parameters can be passed directly to the astroquery call. These can be passed as kwargs: kwargs=(“refraction”:True). Check the astroquery documentation for an overview: https://astroquery.readthedocs.io/en/latest/api/astroquery.jplhorizons.HorizonsClass.html#astroquery.jplhorizons.HorizonsClass.ephemerides

Parameters:

  • reference_system (str, optional) – Coordinate reference system, value must be one of ICRF/J2000 or B1950, by default “J2000”

  • extra_precision (bool, optional) – Enables extra precision in right ascension and declination values, by default False

Returns:

Unprocessed output in astropy table format.

Return type:

astropy.table.Table

Raises:

ValueError – If time query has incorrect format or an incorrect reference system is chosen

interpolated_observations(degrees: bool = False, reference_system: str = 'J2000', extra_precision: bool = True, *args, **kwargs) → ndarray[source]¶

Retrieves interpolated Right Ascension and Declination from the Horizons ephemerides API. Note that these values are not real observations but instead interpolated values based on the Horizons ephemeris system.

Parameters:

  • degrees (bool, optional) – return values in degrees if True, radians if False, by default false

  • reference_system (str, optional) – Coordinate reference system, value must be one of ICRF/J2000 or B1950, by default “J2000”

  • extra_precision (bool, optional) – Enables extra precision in Right Ascension and Declination values, by default False

Returns:

Numpy array (N, 3) with time in seconds since J2000 TDB and the Right Ascension and Declination.

Return type:

np.ndarray

Raises:

ValueError – If time query has incorrect format or an incorrect reference system is chosen

interpolated_station_angles(degrees: bool = False, reference_system: str = 'J2000', extra_precision: bool = True, *args, **kwargs) → ndarray[source]¶

Retrieves interpolated Right Ascension and Declination from the Horizons ephemerides API. Note that these values are not real observations but instead interpolated values based on the Horizons ephemeris system.

Parameters:

  • degrees (bool, optional) – return values in degrees if True, radians if False, by default false

  • reference_system (str, optional) – Coordinate reference system, value must be one of ICRF/J2000 or B1950, by default “J2000”

  • extra_precision (bool, optional) – Enables extra precision in Right Ascension and Declination values, by default False

Returns:

Numpy array (N, 3) with time in seconds since J2000 TDB and the Right Ascension and Declination.

Return type:

np.ndarray

Raises:

ValueError – If time query has incorrect format or an incorrect reference system is chosen

vectors(frame_orientation: str = 'ECLIPJ2000', aberations: str = 'geometric') → Table[source]¶

Retrieve Horizons Vectors api data in raw astropy format. For general purposes, use the .cartesian() method instead.

Parameters:

  • frame_orientation (str, optional) –

    Reference Frame Orientation, equivalent to the astroquery refplane parameter. Options are ‘J2000’/’earth’, ‘ECLIPJ2000’/’ecliptic’ and ‘body’ , by default “ECLIPJ2000”. See astroquery documentation for information about the ‘body’ option:

    https://astroquery.readthedocs.io/en/latest/jplhorizons/jplhorizons.html

  • aberations (str, optional) –

    Aberations to be accounted for. Options are: ‘geometric’, ‘astrometric’ and ‘apparent’, by default “geometric”.

    See the Horizons System Manual for more info:

    https://ssd.jpl.nasa.gov/horizons/manual.html#output

Returns:

Unprocessed vectors API data in astropy Table format.

Return type:

astropy.table.Table

property MPC_number: str | None¶

Retrieve the MPC (Minor Planet Centre) number of the object. The MPC number is infered from data retrieved and will return none if data has not been retrieved yet. The MPC number is only relevant to minor planets such as asteroids, TNOs and Near-Earth Asteroids.

property designation: str | None¶

Retrieve the relevant designation of the query’s object. The designation is infered from the data retrieved and will return none if data has not been retrieved yet. Minor planets and Comets will return their provisional designation (1898 DQ for Eros, 1982 HG1 for Halley). A comets’ formal designation can often be retrieved using the name property Spacecraft and Major Planets/ Moons will return their JPL number (-28 for JUICE, 6 for Saturn Barycentre).

property name: str | None¶

Retrieve the name of the query’s object. The name is infered from the data retrieved and will return none if data has not been retrieved yet. Unnamed minor planets will use their designation instead. If a name can not be infered, the raw name from Horizons will be returned. Please consider raising an issue on the Tudat github in such cases.

class HorizonsBatch(query_id_list: List[str], location: str, epoch_list: list | None = None, epoch_start: datetime | float | None = None, epoch_end: datetime | float | None = None, epoch_step: str | None = None, extended_query: bool = False)[source]¶
add_batch_ephemerides(body_settings: BodyListSettings, frame_origin: str, frame_orientation: str = 'ECLIPJ2000', aberations: str = 'geometric') → None[source]¶

Uses the data queried to add ephemerides of the bodies querried to the body_settings. The names of the bodies added can be retrieved using the names property.

Parameters:

  • body_settings (environment_setup.BodyListSettings) – Tudat body settings object.

  • frame_origin (str) – Global frame origin, should match the queries’ location parameter.

  • frame_orientation (str, optional) – Reference Frame Orientation, equivalent to the astroquery refplane parameter. Options are ‘J2000’ and ‘ECLIPJ2000’, by default “ECLIPJ2000”.

  • aberations (str, optional) – Aberations to be accounted for. Options are: ‘geometric’, ‘astrometric’ and ‘apparent’, by default “geometric”. See the Horizons System Manual for more info: https://ssd.jpl.nasa.gov/horizons/manual.html#output

property names: None | List[str]¶

Retrieves a list of names of the query objects. Returns None if add_batch_ephemerides has not been run yet.