astra.models module

ASTRA Core data models. All persistent data structures used across the library are defined here as frozen dataclasses. This is the single source of truth for all inter-module data types — no other module defines dataclasses. Every dataclass uses frozen=True to enforce immutability.

astra.models.projected_area_m2(dimensions_m, attitude_quaternion, rel_vel_direction)

Compute projected cross-sectional area of a box onto the B-plane. Models the satellite as a rectangular cuboid with given dimensions, rotated by the attitude quaternion. Projects the 3 face normals onto the relative velocity direction and sums visible face areas. This replaces the isotropic sphere assumption for collision geometry. :param dimensions_m: (length, width, height) in meters. :param attitude_quaternion: (w, x, y, z) unit quaternion. :param rel_vel_direction: (3,) unit vector along relative velocity.

Returns:

Projected area in m².

class astra.models.ManeuverFrame(value)

Bases: Enum

Reference frame for specifying maneuver thrust direction. VNB (Velocity-Normal-Binormal) - V: Along the instantaneous velocity vector. - N: Along the orbital angular momentum (R × V). - B: Completes the right-handed triad (V × N). Preferred for orbit-raising and lowering burns: thrust stays aligned with velocity even on eccentric orbits. RTN (Radial-Transverse-Normal) / RIC (Radial-Intrack-Crosstrack) - R: Along the geocentric radial (position) vector. - T: Perpendicular to R in the orbital plane, roughly along-track. - N: Along the orbital angular momentum (R × V). Preferred for station-keeping and relative navigation.

VNB = 'VNB'

RTN = 'RTN'

class astra.models.FiniteBurn(epoch_ignition_jd, duration_s, thrust_N, isp_s, direction, frame)

Bases: object

Finite-duration thrust maneuver for the 7-DOF Cowell propagator. Models a continuous engine burn with dynamically steered thrust (re-computed at every integration sub-step) and Tsiolkovsky-coupled mass depletion. All epochs are Julian Dates. Thrust direction is given as a unit vector in the chosen ManeuverFrame; the engine magnitude is set by thrust_N.

epoch_ignition_jd

duration_s

thrust_N

isp_s

direction

frame

property epoch_cutoff_jd

Julian Date of engine cutoff.

property mass_flow_rate_kg_s

Propellant mass flow rate dm/dt (kg/s, positive value). Derived from the Tsiolkovsky relation:

dm/dt = F / (Isp * g₀)

class astra.models.SatelliteTLE(norad_id, name, line1, line2, epoch_jd, object_type, classification_flag='U', bstar=0.0, rcs_m2=None, radius_m=None, dimensions_m=None, attitude_quaternion=None, attitude_mode='TUMBLING')

Bases: object

Parsed Two-Line Element set for a single orbital object. This is the entry point for all computations. Any satellite, debris, or rocket body that can be analysed in ASTRA Core must first exist as a SatelliteTLE.

norad_id

name

line1

line2

epoch_jd

object_type

classification_flag = 'U'

bstar = 0.0

rcs_m2 = None

radius_m = None

dimensions_m = None

attitude_quaternion = None

attitude_mode = 'TUMBLING'

classmethod from_strings(line1, line2, name='')

Create a SatelliteTLE directly from two raw lines, auto-calculating epoch. If name is omitted, a synthetic name NORAD-{id} is generated from the NORAD catalog number embedded in line 1, matching load_tle_catalog(). :param line1: Valid TLE line 1. :param line2: Valid TLE line 2. :param name: Optional name for the satellite. If empty, auto-generated.

Returns:

A fully initialized SatelliteTLE object.

class astra.models.SatelliteOMM(norad_id, name, epoch_jd, object_type, inclination_rad, raan_rad, argpo_rad, mo_rad, eccentricity, mean_motion_rad_min, bstar, mean_motion_dot=0.0, mean_motion_ddot=0.0, rcs_m2=None, mass_kg=None, cd_area_over_mass=None)

Bases: object

Parsed CCSDS Orbit Mean-Elements Message (OMM) for a single orbital object. Represents the modern, high-fidelity successor to the legacy TLE format. OMM JSON payloads are published by Space-Track.org and CelesTrak and contain additional physical metadata (mass, RCS) that TLEs structurally cannot carry. All angular fields are stored in radians (already converted by the OMM parser from the source’s degree representation) to allow direct injection into Satrec.sgp4init() without further transformation.

norad_id

name

epoch_jd

object_type

inclination_rad

raan_rad

argpo_rad

mo_rad

eccentricity

mean_motion_rad_min

bstar

mean_motion_dot = 0.0

mean_motion_ddot = 0.0

rcs_m2 = None

mass_kg = None

cd_area_over_mass = None

classmethod from_dict(record)

Construct a SatelliteOMM from a raw OMM JSON dictionary. Convenience factory — delegates to astra.omm.parse_omm_record() so the caller does not need to import the parser module explicitly. :param record: A single OMM record dictionary (as from json.loads()).

Returns:

Fully populated SatelliteOMM instance.

Example::

import json, astra records = json.loads(open(“catalog.json”).read()) sats = [astra.SatelliteOMM.from_dict(r) for r in records]

astra.models.SatelliteState

Type alias accepted by all ASTRA-Core physics functions. Any function receiving a SatelliteState correctly handles both legacy TLE and modern OMM objects without modification.

alias of SatelliteTLE | SatelliteOMM

class astra.models.OrbitalState(norad_id, t_jd, position_km, velocity_km_s, error_code)

Bases: object

Complete kinematic state of a single object at one instant. Produced by SGP4 propagation for a single satellite at a single time step.

norad_id

t_jd

position_km

velocity_km_s

error_code

class astra.models.DebrisObject(source, altitude_km, inclination_deg, period_minutes, raan_deg, eccentricity, apogee_km, perigee_km, object_class, rcs_m2=None, radius_m=None)

Bases: object

Cataloged orbital object with pre-derived parameters for filtering. Contains the authoritative orbital source (either SatelliteTLE or SatelliteOMM) plus derived orbital metrics that enable fast filtering without propagation.

source

altitude_km

inclination_deg

period_minutes

raan_deg

eccentricity

apogee_km

perigee_km

object_class

rcs_m2 = None

radius_m = None

property tle

Legacy accessor for TLE source. Raises if source is OMM. .. deprecated:

Use ``.source`` instead, which handles both TLE and OMM.

class astra.models.ConjunctionEvent(object_a_id, object_b_id, tca_jd, miss_distance_km, relative_velocity_km_s, collision_probability, risk_level, position_a_km, position_b_km, covariance_source='SYNTHETIC')

Bases: object

Detected close-approach event between two orbital objects. Primary output of conjunction analysis. Use collision_probability_nan for threshold checks without TypeError when Pc is unknown (None becomes float('nan')).

object_a_id

object_b_id

tca_jd

miss_distance_km

relative_velocity_km_s

collision_probability

risk_level

position_a_km

position_b_km

covariance_source = 'SYNTHETIC'

property collision_probability_nan

Collision probability as a float, with None mapped to float('nan'). Allows safe threshold comparisons without TypeError:

pc = event.collision_probability_nan
if not math.isnan(pc) and pc > 1e-4:
    alert(event)

Returns:

Pc in [0.0, 1.0] when covariance data was available, or float('nan') when collision_probability is None.

class astra.models.Observer(name, latitude_deg, longitude_deg, elevation_m, min_elevation_deg=10.0)

Bases: object

Ground-based observation station. Required by all visibility functions.

name

latitude_deg

longitude_deg

elevation_m

min_elevation_deg = 10.0

class astra.models.PassEvent(norad_id, observer_name, aos_jd, tca_jd, los_jd, max_elevation_deg, azimuth_at_aos_deg, azimuth_at_tca_deg, azimuth_at_los_deg, duration_seconds, satellite_illuminated=True, observer_in_darkness=False)

Bases: object

Satellite pass over a ground observer. A time interval during which the satellite’s elevation angle exceeds the observer’s minimum elevation threshold. .. attribute:: norad_id

NORAD catalog ID of the satellite.

type:

str

observer_name

Name of the ground observer/station.

Type:

str

aos_jd

Acquisition of Signal time (Julian Date) - satellite rises above horizon.

Type:

float

tca_jd

Time of Closest Approach (Julian Date) - maximum elevation.

Type:

float

los_jd

Loss of Signal time (Julian Date) - satellite drops below horizon.

Type:

float

max_elevation_deg

Maximum elevation angle during pass (degrees).

Type:

float

azimuth_at_aos_deg

Azimuth at AOS (degrees, 0-360, N=0, E=90).

Type:

float

azimuth_at_tca_deg

Azimuth at TCA (degrees, 0-360, N=0, E=90).

Type:

float

azimuth_at_los_deg

Azimuth at LOS (degrees, 0-360, N=0, E=90).

Type:

float

duration_seconds

Pass duration in seconds.

Type:

float

satellite_illuminated

True if satellite is sunlit at TCA (for visual passes).

Type:

bool

observer_in_darkness

True if observer is in Earth’s shadow at TCA.

Type:

bool

norad_id

observer_name

aos_jd

tca_jd

los_jd

max_elevation_deg

azimuth_at_aos_deg

azimuth_at_tca_deg

azimuth_at_los_deg

duration_seconds

satellite_illuminated = True

observer_in_darkness = False

class astra.models.FilterConfig(min_altitude_km=None, max_altitude_km=None, lat_min_deg=None, lat_max_deg=None, lon_min_deg=None, lon_max_deg=None, t_start_jd=None, t_end_jd=None, object_types=None, max_objects=None)

Bases: object

Filter parameters for the multi-stage debris filtering pipeline. Passed as a single configuration object to apply_filters(). None fields are treated as “no constraint” for that dimension.

min_altitude_km = None

max_altitude_km = None

lat_min_deg = None

lat_max_deg = None

lon_min_deg = None

lon_max_deg = None

t_start_jd = None

t_end_jd = None

object_types = None

max_objects = None