astra.orbit module

ASTRA Core orbit propagation module. Responsible for SGP4-based orbit propagation. Generates position and velocity vectors at specified times. Uses sgp4 for actual propagation and skyfield for coordinate frame conversions. No manual orbital equations allowed. Supports both legacy SatelliteTLE objects (via Satrec.twoline2rv) and modern SatelliteOMM objects (via Satrec.sgp4init). Use the _build_satrec() helper which dispatches automatically based on type.

astra.orbit.propagate_orbit(satellite, epoch_jd, t_since_minutes)

Propagate a single satellite to a single point in time using SGP4. Data formats: ✓ SatelliteTLE ✓ SatelliteOMM :param satellite: Parsed SatelliteTLE or SatelliteOMM object to propagate. :param epoch_jd: Reference epoch as Julian Date (typically satellite.epoch_jd). :param t_since_minutes: Minutes elapsed since epoch.

Returns:

OrbitalState containing position (km) and velocity (km/s).

Frame:

TEME (True Equator, Mean Equinox) — raw SGP4 output frame. Do NOT feed directly into ECEF-expecting functions without conversion.

astra.orbit.propagate_many(satellites, times_jd)

Vectorized batch propagation of multiple satellites across a time array. Data formats: ✓ SatelliteTLE ✓ SatelliteOMM :param satellites: List of SatelliteState objects to propagate. :param times_jd: 1D NumPy array of T absolute Julian Dates. (Shape: (T,), dtype: float64)

Returns:

Tuple (traj_map, vel_map). Each value is a dict keyed by NORAD ID with arrays of shape (T, 3) in TEME: positions in km and velocities in km/s. Satellites with propagation errors at any timestep store nan in that row.

Frame: TEME (True Equator, Mean Equinox), i.e. raw SGP4 output. Do not feed positions directly into ECEF-expecting functions without conversion. Note: Unpack as traj_map, vel_map = propagate_many(...).

astra.orbit.propagate_many_generator(satellites, times_jd, chunk_size=1440)

Memory-efficient batch propagation yielding time-chunked results. Data formats: ✓ SatelliteTLE ✓ SatelliteOMM Prevents Out-Of-Memory (OOM) fatal kills during massive all-vs-all STM queries by yielding rolling spatial windows.

astra.orbit.propagate_trajectory(satellite, t_start_jd, t_end_jd, step_minutes=5.0)

Propagate a single satellite over a defined time window at a fixed step. Data formats: ✓ SatelliteTLE ✓ SatelliteOMM :param satellite: Source SatelliteTLE or SatelliteOMM to propagate. :param t_start_jd: Window start as Julian Date. :param t_end_jd: Window end as Julian Date (must be strictly > t_start_jd). :param step_minutes: Step size in minutes (must be positive; default 5.0).

Returns:

time_array: shape (T,), Julian Dates for each step. position_array: shape (T, 3), TEME positions in km. velocity_array: shape (T, 3), TEME velocities in km/s.

Return type:

Tuple of (time_array, position_array, velocity_array)

Frame:

TEME (True Equator, Mean Equinox) — raw SGP4 output frame. Do NOT feed directly into ECEF-expecting functions without conversion.

Raises:

ValueError – If t_end_jd <= t_start_jd or step_minutes <= 0.

astra.orbit.ground_track(positions_teme, times_jd)

Convert TEME Cartesian positions into geodetic coordinates for ground track. :param positions_teme: TEME position array from propagation. Shape: (T, 3) :param times_jd: Corresponding Julian Date array. Shape: (T,)

Returns:

List of (latitude_deg, longitude_deg, altitude_km) tuples, length T.

Frame:

Input must be in TEME (True Equator, Mean Equinox) frame — the native SGP4 output. This function internally converts TEME → GCRS → WGS84.