astra.conjunction module

ASTRA Core conjunction detection module. Detects close-approach events between pairs of orbital objects. Implements an advanced 3-phase optimization algorithm including: 1. Sweep-and-Prune Radial Bounding Shell filter 2. Trajectory AABB volume filter 3. Cubicspline Curvilinear Interpolation for exact sub-second TCA 4. Realistic Encounter-Plane Covariance Probability

astra.conjunction.distance_3d(pos_a, pos_b)[source]

Compute Euclidean distance between two position arrays.

astra.conjunction.load_spacebook_covariance(norad_id)[source]

Fetch and parse Spacebook Synthetic Covariance for a given satellite. Extracts the first 6x6 positional/velocity covariance matrix from the satellite’s SynCoPate STK ephemeris. DATA-03 Fix: Validates that the covariance units header specifies km/km/s. STK files can declare either m/m/s or km/km/s units; accepting the wrong unit silently would produce Pc values off by a factor of ~10^6. Undeclared units default to km per STK spec §5.3.6. :param norad_id: NORAD Catalog ID.

Returns:

(6, 6) covariance matrix in TEME Of Date (km, km/s), or None if download fails, parsing fails, unit mismatch is detected, or Spacebook is disabled.

astra.conjunction.closest_approach(trajectory_a, trajectory_b, times_jd, spline_A=None, spline_B=None)[source]

Find the exact minimum separation using cubic splines. Accepts pre-computed splines to allow amortised O(1) evaluation time in tight loops where re-building O(N log N) is prohibitive.

astra.conjunction.find_conjunctions(trajectories, times_jd, elements_map, threshold_km=5.0, coarse_threshold_km=50.0, cov_map=None, vel_map=None, max_workers=None)[source]

Find highly precise conjunction events using cubic spline interpolation. Data formats: ✓ SatelliteTLE ✓ SatelliteOMM :param trajectories: TrajectoryMap of NORAD-ID → (T, 3) position array (km, TEME). :param times_jd: 1-D array of T Julian Dates matching the trajectory rows. :param elements_map: NORAD-ID → DebrisObject (used for epoch, radius, covariance). :param threshold_km: Fine-filter miss-distance threshold (km). :param coarse_threshold_km: KD-tree pre-filter radius (km). :param cov_map: Optional NORAD-ID → (3, 3) or (6, 6) ECI covariance in km². :param vel_map: Optional NORAD-ID → (T, 3) SGP4 velocity array (km/s, TEME).

When supplied the SGP4 velocities are interpolated at TCA, which is significantly more accurate than the position-spline derivative for eccentric orbits near perigee.

Returns:

List of ConjunctionEvent objects, sorted by miss_distance_km.

Note

TCA refinement uses a CubicSpline + Brent scalar minimization (scipy.optimize.minimize_scalar, method=’bounded’) for sub-millisecond TCA precision. Falls back to 100-point dense scan if Brent fails. max_workers caps the thread-pool size. Defaults to min(cpu_count, 16) to prevent thread storms on large catalogs (>10,000 NORAD IDs generate O(N²) candidate pairs). Set explicitly when running in a containerised or resource-constrained environment.

astra.conjunction.run_conjunction_sweep(catalog, t_start_jd, t_end_jd, step_minutes=5.0, threshold_km=5.0, coarse_threshold_km=50.0, cov_map=None, max_workers=None)[source]

High-level conjunction sweep pipeline: catalog → ConjunctionEvent list. Replaces the 5-step manual orchestration (fetch → map → propagate → index → screen) with a single call. Internally handles: 1. Converting catalog entries (SatelliteTLE or SatelliteOMM) to

DebrisObject instances via make_debris_object().

  1. Building the Julian-Date time grid between t_start_jd and t_end_jd at step_minutes resolution.

  2. Batch-propagating all satellites over the grid via propagate_many().

  3. Dropping any satellite whose trajectory contains NaN values (SGP4 error; typically very decayed TLEs).

  4. Running find_conjunctions() with the 3-phase KD-tree + spline + Pc pipeline on the resulting trajectory map.

Parameters:

  • catalog – List of SatelliteTLE or SatelliteOMM objects. Obtain via fetch_celestrak_group, fetch_spacetrack_group, or any other ingestion function.

  • t_start_jd – Window start as Julian Date (UTC).

  • t_end_jd – Window end as Julian Date (UTC). Must be > t_start_jd.

  • step_minutes – Propagation step size in minutes (default 5.0). Smaller values improve TCA precision at the cost of memory.

  • threshold_km – Fine-filter conjunction threshold in km (default 5.0).

  • coarse_threshold_km – KD-tree pre-filter radius in km (default 50.0).

  • cov_map – Optional NORAD-ID → (3,3) or (6,6) covariance in km². When omitted, synthetic covariance estimation is used.

  • max_workers – Maximum thread-pool size for concurrent pair evaluation. Defaults to min(cpu_count, 16).

Returns:

List of ConjunctionEvent objects sorted by miss distance, ready for downstream Pc ranking or CDM generation.

Raises:

  • AstraError – If t_end_jd <= t_start_jd or catalog is empty.

  • PropagationError – Propagation failure for any object in STRICT_MODE.

Example::

import astra import math catalog = astra.fetch_celestrak_group(“starlink”) t0 = astra.datetime_utc_to_jd(datetime(2026, 5, 1, tzinfo=timezone.utc)) t1 = t0 + 1.0 # 24-hour window events = astra.run_conjunction_sweep(catalog, t0, t1, threshold_km=5.0) for ev in events[:10]:

print(f”{ev.object_a_id} vs {ev.object_b_id} “

f”miss={ev.miss_distance_km:.3f} km Pc={ev.collision_probability:.2e}”)

class astra.conjunction.ConjunctionWindow(object_a_id, object_b_id, entry_jd, exit_jd, tca_jd, min_distance_km)[source]

Bases: object

Time interval during which two objects are within a distance threshold.

Unlike ConjunctionEvent (a point-event at TCA), a ConjunctionWindow defines the entry and exit epochs of the close-approach interval. Use ConjunctionWindow for interval-based monitoring (e.g. CDM 7-day look-ahead, communication blackout windows, or maneuver-avoidance window computation). Use ConjunctionEvent for point-event TCA analysis and Pc computation.

Relationship:

A ConjunctionEvent.tca_jd always falls within the corresponding ConjunctionWindow.entry_jd to ConjunctionWindow.exit_jd interval for the same object pair.

object_a_id

NORAD ID of object A.

Type:

str

object_b_id

NORAD ID of object B.

Type:

str

entry_jd

Julian Date when distance first drops below threshold.

Type:

float

exit_jd

Julian Date when distance first rises above threshold.

Type:

float

tca_jd

Julian Date of closest approach within the window.

Type:

float

min_distance_km

Minimum separation within the window (km).

Type:

float

duration_s

Window duration in seconds (computed property).

object_a_id
object_b_id
entry_jd
exit_jd
tca_jd
min_distance_km
property duration_s

Duration of the conjunction window in seconds.

astra.conjunction.find_conjunction_windows(trajectories, times_jd, threshold_km=10.0, objects=None)[source]

Find time windows during which pairs of objects are within a distance threshold.

Unlike find_conjunctions() which returns point-events at TCA, this function returns intervals [entry_jd, exit_jd] during which two objects remain within threshold_km. Each window also includes the TCA and minimum distance within that interval.

Uses cubic spline interpolation for sub-sample-step resolution on both the entry/exit bracket edges and the TCA within each window.

Parameters:

  • trajectories – TrajectoryMap of NORAD-ID → (T, 3) position array (km, TEME).

  • times_jd – 1-D array of T Julian Dates matching trajectory rows.

  • threshold_km – Distance threshold in km (default 10.0). Windows are defined as intervals where distance < threshold_km.

  • objects – Optional dict for future extension (currently unused).

Returns:

List of ConjunctionWindow objects, sorted by entry_jd.

Raises:

AstraError – If times_jd has fewer than 3 elements or trajectories are inconsistent.

Example:

import astra
windows = astra.find_conjunction_windows(
    trajectories=traj_map,
    times_jd=times,
    threshold_km=5.0,
)
for w in windows:
    print(f"{w.object_a_id} vs {w.object_b_id}: "
          f"window={w.duration_s:.1f}s, min_dist={w.min_distance_km:.3f}km")