Quickstart¶

This guide uses APIs that match the current astra-core-engine package. Adjust NORAD IDs and time windows for your own data.

0. JIT warm-up (production)¶

In production worker processes, call warmup() once at startup to pre-compile all Numba kernels and eliminate first-call latency:

import astra

astra.warmup()   # call once per process before any propagation

1. Parse a TLE¶

Build a astra.models.SatelliteTLE from two lines (checksums should be valid for production use):

from astra.models import SatelliteTLE

line1 = "1 25544U 98067A   21001.00000000  .00001480  00000-0  34282-4 0  9990"
line2 = "2 25544  51.6442 284.1199 0001364 338.5498  21.5664 15.48922536 12341"

iss = SatelliteTLE.from_strings(line1, line2, name="ISS (ZARYA)")
print(f"Epoch JD: {iss.epoch_jd}")

2. Propagate with SGP4¶

import numpy as np
from astra import propagate_many

dt_min = np.arange(0.0, 120.0, 5.0)
times_jd = iss.epoch_jd + dt_min / 1440.0

traj, velocities = propagate_many([iss], times_jd)
positions = traj[iss.norad_id]   # (T, 3) km, TEME

3. Screen for conjunctions¶

from astra import find_conjunctions, make_debris_object

elements_map = {iss.norad_id: make_debris_object(iss)}

events = find_conjunctions(
    traj,
    times_jd,
    elements_map,
    threshold_km=5.0,
)

for ev in events:
    print(ev)

4. Load a live CelesTrak catalog¶

from astra import fetch_celestrak_active, load_tle_catalog

# Recommended: live fetch (requires network)
catalog = fetch_celestrak_active()

# Or parse lines you already have:
# catalog = load_tle_catalog(open("catalog.txt").read().splitlines())

print(f"Objects: {len(catalog)}")

5. Ground-station passes¶

from datetime import datetime, timezone

from astra import Observer, passes_over_location, convert_time

observer = Observer(
    name="Los Angeles",
    latitude_deg=34.0522,
    longitude_deg=-118.2437,
    elevation_m=71.0,
    min_elevation_deg=10.0,
)

now = datetime.now(timezone.utc)
t0_jd = float(convert_time(now, "jd"))

passes = passes_over_location(
    satellite=iss,
    observer=observer,
    t_start_jd=t0_jd,
    t_end_jd=t0_jd + 1.0,
    step_minutes=1.0,
)

for p in passes:
    print(f"Max elevation (deg): {p.max_elevation_deg:.1f}")
    print(f"Duration (s): {p.duration_seconds:.0f}")

6. High-fidelity Cowell propagation¶

from astra import propagate_cowell, NumericalState, DragConfig
import numpy as np

state = NumericalState(
    t_jd=2460000.5,
    position_km=np.array([7000.0, 0.0, 0.0]),
    velocity_km_s=np.array([0.0, 7.5, 0.0]),
)
drag = DragConfig(
    cd=2.2, area_m2=10.0, mass_kg=1000.0,
    srp_conical_shadow=True,   # high-fidelity penumbra (default)
)

trajectory = propagate_cowell(state, duration_s=3600.0, dt_out=60.0, drag_config=drag)
print(f"Final altitude: {np.linalg.norm(trajectory[-1].position_km) - 6378.137:.2f} km")

7. Parse a CDM (Conjunction Data Message)¶

from astra import parse_cdm_xml

with open("conjunction.cdm.xml") as f:
    cdm = parse_cdm_xml(f.read())

print(f"Miss distance: {cdm.miss_distance_m / 1000.0} km")
print(f"P_c: {cdm.collision_probability}")

Next steps¶

OMM workflows: fetch_celestrak_active_omm, parse_omm_json, load_omm_file, xptle_to_satellite_omm for converting a list[SatelliteTLE] XP-TLE catalog to list[SatelliteOMM]
Spacebook: fetch_xp_tle_catalog, fetch_synthetic_covariance_stk, load_spacebook_covariance, refresh_satcat_cache, get_space_weather_sb, get_eop_sb
High-fidelity propagation: propagate_cowell with astra.propagator.DragConfig and astra.models.FiniteBurn
STM covariance: propagate_covariance_stm, rotate_covariance_rtn_to_eci
Read Operational limitations and the repository KNOWMORE.md for physics scope