across.tools.ephemeris

Submodules

Classes

`Ephemeris`	A base class for calculating ephemerides of Astronomical Observatories both
`GroundEphemeris`	Ground-based ephemeris calculator.
`JPLEphemeris`	JPL Horizons-based ephemeris calculation.
`SPICEEphemeris`	SPICEEphemeris class for calculating spacecraft ephemeris using SPICE
`TLEEphemeris`	TLE (Two-Line Element) based satellite ephemeris calculator.

Functions

`compute_ground_ephemeris`(begin, end, step_size, ...)	Compute ground-based ephemeris for a given time range and location.
`compute_jpl_ephemeris`(begin, end, step_size, naif_id)	Compute space ephemeris data using JPL Horizons system.
`compute_spice_ephemeris`(begin, end, step_size, ...)	Compute space ephemeris data using SPICE kernels.
`compute_tle_ephemeris`(begin, end, step_size, tle)	Compute the ephemeris for a space object using TLE data.

Package Contents

class Ephemeris(begin, end, step_size=60)[source]

Bases: abc.ABC

A base class for calculating ephemerides of Astronomical Observatories both ground and space-based. This abstract class provides the core functionality for computing positions and angular sizes of celestial bodies (Sun, Moon, Earth) relative to a spacecraft or observation point. It handles time series calculations with specified time intervals and step sizes.

Parameters:

begin (datetime or Time) – Start time of ephemeris calculation
end (datetime or Time) – End time of ephemeris calculation
step_size (int, TimeDelta, or timedelta, optional) – Time step between calculations in seconds, by default 60

begin

Start time of ephemeris calculation

Type:: Time

end

End time of ephemeris calculation

Type:: Time

step_size

Step size of ephemeris calculation

Type:: TimeDelta

timestamp

Array of calculation timestamps

Type:: Time

gcrs

Spacecraft position in Geocentric Celestial Reference System (GCRS) coordinates

Type:: SkyCoord

earth_location

Spacecraft position relative to Earth

Type:: EarthLocation

moon

Moon position relative to spacecraft

Type:: SkyCoord

sun

Sun position relative to spacecraft

Type:: SkyCoord

earth

Earth position relative to spacecraft

Type:: SkyCoord

longitude

Spacecraft longitude

Type:: Longitude, optional

latitude

Spacecraft latitude

Type:: Latitude, optional

height

Spacecraft height above Earth’s surface

Type:: Quantity, optional

earth_radius_angle

Angular radius of Earth as seen from spacecraft

Type:: Angle

moon_radius_angle

Angular radius of Moon as seen from spacecraft

Type:: Angle

sun_radius_angle

Angular radius of Sun as seen from spacecraft

Type:: Angle

distance

Distance from spacecraft to Earth center

Type:: Quantity

Notes

This is an abstract base class that must be subclassed. Subclasses must implement the prepare_data() method to set up the spacecraft position before ephemeris calculations can be performed.

begin: astropy.time.Time

end: astropy.time.Time

step_size: astropy.time.TimeDelta

timestamp: astropy.time.Time

gcrs: astropy.coordinates.SkyCoord

earth_location: astropy.coordinates.EarthLocation

moon: astropy.coordinates.SkyCoord

sun: astropy.coordinates.SkyCoord

earth: astropy.coordinates.SkyCoord

longitude: astropy.coordinates.Longitude | None = None

latitude: astropy.coordinates.Latitude | None = None

height: astropy.units.Quantity | None = None

earth_radius_angle: astropy.coordinates.Angle

moon_radius_angle: astropy.coordinates.Angle

sun_radius_angle: astropy.coordinates.Angle

distance: astropy.units.Quantity

_start_unix: float

_step_seconds: float

__len__()[source]

index(t)[source]

For a given time, return an index for the nearest time in the ephemeris. Note that internally converting from Time to unix makes this run way faster.

Parameters:: t (Time) – The time to find the nearest index for.
Returns:: The index of the nearest time in the ephemeris.
Return type:: int

_compute_timestamp()[source]

Get array of timestamps based on time interval and step size.

Returns:: If begin equals end, returns single timestamp. Otherwise returns array of timestamps from begin to end with specified step_size.
Return type:: astropy.time.Time

_calc()[source]

Calculate ephemeris data based on the coordinates computed by prepare_data().

abstract prepare_data()[source]

Prepare data for ephemeris calculation. Abstract method, to be implemented by subclasses.

compute()[source]

Compute ephemeris data.

This method orchestrates the computation of ephemeris data by first preparing the necessary data and then performing the core ephemeris calculations. It is intended to be called after initializing the Ephemeris object with the desired time range and step size.

class GroundEphemeris(begin, end, step_size=60, latitude=None, longitude=None, height=None)[source]

Bases: across.tools.ephemeris.base.Ephemeris

Ground-based ephemeris calculator.

This class extends the base Ephemeris class to calculate ephemeris data for ground-based observations from a specific location on Earth’s surface.

Parameters:

begin (Union[datetime, Time]) – Start time of the ephemeris calculation
end (Union[datetime, Time]) – End time of the ephemeris calculation
step_size (Union[int, TimeDelta, timedelta], optional) – Time step between ephemeris points in seconds, by default 60
latitude (Optional[Latitude], optional) – Latitude of the observatory, by default None
longitude (Optional[Longitude], optional) – Longitude of the observatory, by default None
height (Optional[u.Quantity], optional) – Height of the observatory above sea level, by default None

latitude

Latitude of the observatory

Type:: Optional[Latitude]

longitude

Longitude of the observatory

Type:: Optional[Longitude]

height

Height of the observatory

Type:: Optional[u.Quantity]

earth_location

Location of the observatory on the Earth in astropy’s EarthLocation class.

Type:: EarthLocation

gcrs

Observatory position in Geocentric Celestial Reference System (GCRS) coordinates

Type:: SkyCoord

Raises:: ValueError – If observatory location (latitude, longitude, or height) is not set

Notes

The class calculates the position of a ground-based observatory in GCRS coordinates, which is necessary for various astronomical calculations.

longitude: astropy.coordinates.Longitude | None

latitude: astropy.coordinates.Latitude | None

height: astropy.units.Quantity | None

prepare_data()[source]

Calculate ground-based ephemeris

compute_ground_ephemeris(begin, end, step_size, latitude, longitude, height)[source]

Compute ground-based ephemeris for a given time range and location.

Parameters:

begin (Union[datetime, Time]) – The start time of the ephemeris computation.
end (Union[datetime, Time]) – The end time of the ephemeris computation.
step_size (int) – The step size in seconds for the ephemeris computation.
latitude (Latitude) – The latitude of the ground-based observatory.
longitude (Longitude) – The longitude of the ground-based observatory.
height (u.Quantity) – The height of the ground-based observatory above sea level.

Returns:

An Ephemeris object containing the computed ephemeris data.

Return type:

Ephemeris

class JPLEphemeris(begin, end, step_size=60, naif_id=None)[source]

Bases: across.tools.ephemeris.base.Ephemeris

JPL Horizons-based ephemeris calculation.

This class provides functionality to calculate ephemeris data using JPL Horizons system. It requires a Navigation and Ancillary Information Facility (NAIF) ID to identify the celestial object of interest.

Parameters:

begin (datetime or Time) – Start time of the ephemeris calculation
end (datetime or Time) – End time of the ephemeris calculation
step_size (int or TimeDelta or timedelta, default=60) – Time step between ephemeris points in seconds
naif_id (int, optional) – NAIF ID of the celestial object for JPL Horizons query

naif_id

NAIF ID of object for JPL Horizons or Spice Kernel

Type:: int

gcrs

Geocentric celestial reference system coordinates

Type:: SkyCoord

earth_location

Earth-fixed coordinates of the object

Type:: EarthLocation

prepare_data()[source]

Calculate ephemeris based on JPL Horizons data

Notes

The class uses the JPL Horizons API to fetch vector data for the specified celestial object and converts it to both GCRS and ITRS coordinate frames.

Raises:: ValueError – If no NAIF ID is provided when preparing the data

naif_id: int | None = None

prepare_data()[source]

Calculate ephemeris based on JPL Horizons data.

compute_jpl_ephemeris(begin, end, step_size, naif_id)[source]

Compute space ephemeris data using JPL Horizons system.

Parameters:

begin (Union[datetime, Time]) – Start date and time for ephemeris computation
end (Union[datetime, Time]) – End date and time for ephemeris computation
step_size (Union[int, timedelta, TimeDelta]) – Time step size between ephemeris points, in seconds if int
naif_id (int) – Navigation and Ancillary Information Facility (NAIF) object identifier (e.g., 301 for Moon. -48 for HST)

Returns:

An Ephemeris object containing the computed ephemeris data

Return type:

Ephemeris

Notes

This function uses the JPL Horizons system to compute high-precision ephemeris data for celestial bodies in space-based reference frame.

Examples

>>> from datetime import datetime
>>> begin = datetime(2023, 1, 1)
>>> end = datetime(2023, 1, 2)
>>> moon_ephemeris = compute_jpl_ephemeris(begin, end, 60, 301)

class SPICEEphemeris(begin, end, step_size=60, spice_kernel_url=None, naif_id=None)[source]

Bases: across.tools.ephemeris.base.Ephemeris

SPICEEphemeris class for calculating spacecraft ephemeris using SPICE (Spacecraft Planet Instrument C-matrix Events) kernels.

This class extends the base Ephemeris class to provide specialized functionality for computing spacecraft trajectories using kernels.

Parameters:

begin (datetime or Time) – Start time of the ephemeris calculation
end (datetime or Time) – End time of the ephemeris calculation
step_size (int or TimeDelta or timedelta, default=60) – Time step between ephemeris points in seconds
spice_kernel_url (str, optional) – URL to download the spacecraft SPICE kernel
naif_id (int, optional) – Navigation and Ancillary Information Facility (NAIF) ID of the spacecraft/object in JPL Horizons or SPICE kernel

naif_id

NAIF ID of object for JPL Horizons or SPICE Kernel

Type:: int

spice_kernel_url

URL of spacecraft SPICE Kernel

Type:: str

gcrs

Calculated positions in GCRS frame

Type:: SkyCoord

earth_location

Calculated positions in ITRS frame

Type:: EarthLocation

prepare_data()[source]

Loads necessary SPICE kernels and calculates spacecraft trajectory

Notes

Requires SPICE kernels for: - Leap seconds - Planetary ephemeris - Earth orientation parameters - Spacecraft trajectory The class automatically handles downloading and caching of required SPICE kernels.

naif_id: int | None = None

spice_kernel_url: str | None = None

prepare_data()[source]

Loading SPICE kernels to calculate SPICE based ephemeris.

compute_spice_ephemeris(begin, end, step_size, spice_kernel_url, naif_id)[source]

Compute space ephemeris data using SPICE kernels.

Parameters:

begin (Union[datetime, Time]) – Start date and time for ephemeris computation
end (Union[datetime, Time]) – End date and time for ephemeris computation
step_size (Union[int, timedelta, TimeDelta]) – Time step size between ephemeris points, in seconds if int
spice_kernel_url (str) – URL to the SPICE kernel file
naif_id (int) – Navigation and Ancillary Information Facility (NAIF) object identifier (e.g., 301 for Moon, -48 for HST)

Returns:

An Ephemeris object containing the computed ephemeris data

Return type:

Ephemeris

Notes

This function uses the SPICE system to compute high-precision ephemeris data for celestial bodies in space-based reference frame.

Examples

>>> from datetime import datetime
>>> begin = datetime(2023, 1, 1)
>>> end = datetime(2023, 1, 2)
>>> moon_ephemeris = compute_spice_ephemeris(begin, end, 60, 'https://path/to/spice_kernel.bsp', 301)

class TLEEphemeris(begin, end, step_size=60, tle=None)[source]

Bases: across.tools.ephemeris.base.Ephemeris

TLE (Two-Line Element) based satellite ephemeris calculator.

This class implements satellite position and velocity calculations using TLE data through the SGP4 propagator. It converts TEME (True Equator Mean Equinox) coordinates to ITRS (International Terrestrial Reference System) and GCRS (Geocentric Celestial Reference System). ITRS coordinates are stored as astropy EarthLocation objects, while GCRS coordinates are stored as astropy SkyCoord objects.

Parameters:

begin (Union[datetime, Time]) – Start time for ephemeris calculations
end (Union[datetime, Time]) – End time for ephemeris calculations
step_size (Union[int, TimeDelta, timedelta], optional) – Time step between calculations, defaults to 60 seconds
tle (Optional[TLE], optional) – TLE data object containing orbital elements, defaults to None

tle

TLE data object used for calculations

Type:: Optional[TLE]

earth_location

Satellite positions in ITRS coordinates

Type:: EarthLocation

gcrs

Satellite positions in GCRS coordinates

Type:: SkyCoord

prepare_data()[source]

Calculates satellite ephemeris using TLE data and SGP4 propagator

Raises:: ValueError – If no TLE data is provided when preparing calculations

Notes

The calculation process involves: 1. Converting TLE to Satrec object 2. Calculating TEME positions using SGP4 3. Converting TEME to ITRS coordinates 4. Converting ITRS to GCRS coordinates

tle: across.tools.core.schemas.tle.TLE | None = None

prepare_data()[source]

Calculate ephemeris based on TLE data

_calc()[source]

Calculate ephemeris data based on the coordinates computed by prepare_data(). Overloads the base class method to as rust-ephem already computes all necessary data during prepare_data().

compute_tle_ephemeris(begin, end, step_size, tle)[source]

Compute the ephemeris for a space object using TLE data.

Parameters:

begin (Union[datetime, Time]) – The start time for the ephemeris computation.
end (Union[datetime, Time]) – The end time for the ephemeris computation.
step_size (Union[int, timedelta, TimeDelta]) – Time step size between ephemeris points, in seconds if int
tle (TLE) – The TLE data entry for the space object.

Returns:

The computed ephemeris object containing the position and velocity data.

Return type:

Ephemeris