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:

.. code-block:: python

    import astra

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

1. Parse a TLE
----------------

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

.. code-block:: python

    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
------------------------

.. code-block:: python

    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
--------------------------

.. code-block:: python

    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
----------------------------------

.. code-block:: python

    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
--------------------------

.. code-block:: python

    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
--------------------------------------

.. code-block:: python

    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)
-------------------------------------------

.. code-block:: python

    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
  :class:`astra.propagator.DragConfig` and :class:`astra.models.FiniteBurn`
* STM covariance: ``propagate_covariance_stm``, ``rotate_covariance_rtn_to_eci``
* Read :doc:`limitations` and the repository **KNOWMORE.md** for physics scope