Operational limitations
=========================

ASTRA-Core implements standard models used in research, education, and software
integration. It is **not**, by itself, a certified conjunction or
mission-closure product. Understand these boundaries before using outputs for
operations.

Ephemeris and time
------------------

* Default Sun/Moon positions use **JPL DE421** (bundled via Skyfield), nominally
  **~1900–2050**. Simulations or studies beyond that range should use **DE440**
  (1549–2650, ~100 MB) or another appropriate kernel and validation.
* **UT1−UTC** and Earth orientation come from Skyfield's IERS
  ``finals2000A`` loaders when available. **Strict mode** raises
  ``EphemerisError`` if required data are missing; relaxed mode may warn and
  fall back to an analytical approximation (Meeus / Brown).

Atmosphere and drag
-------------------

* Empirical **NRLMSISE-00** density (calibrated to 3.7 × 10\ :sup:`−12` kg/m³
  at 400 km under moderate solar activity). Density above 1 500 km and below
  100 km is returned as 0. Very low LEO and re-entry analysis may still need
  deeper configuration or specialized tools outside general orbital propagation.
* Space weather (F10.7, Ap) is sourced from Spacebook (primary) or CelesTrak
  ``SW-All.csv`` (fallback). Missing data returns synthetic defaults
  (F10.7 = 150, Ap = 15) in relaxed mode; raises ``SpaceWeatherError`` in
  strict mode.

Solar radiation pressure
------------------------

* **Cannonball SRP** with flux scaled from 1 AU. Features a high-fidelity
  **conical Earth umbra/penumbra** model (``_srp_illumination_factor_njit``)
  that scales fractional solar illumination continuously via a
  circle-circle intersection formula. The model uses planar rather than exact
  spherical-cap geometry; the resulting error in time-averaged ν is a few
  percent in LEO—acceptable for mission-planning fidelity but not for
  ultra-precise SRP-limited precision orbit determination.
* The canonical ``DragConfig`` field is ``srp_conical_shadow`` (default
  ``True``). The old alias ``srp_cylindrical_shadow`` is **deprecated** and
  emits a ``DeprecationWarning``; update callers to ``srp_conical_shadow``.

Collision probability
---------------------

* **P_c** quality follows **covariance quality**. Heuristic
  ``estimate_covariance()`` is not orbit-determination grade; prefer **CDM**
  covariances or Spacebook synthetic covariances for decision support.
  **Strict mode** can reject heuristic covariance paths.
* **Monte Carlo P_c** uses a **linear** relative-motion model per sample; very
  slow co-orbital encounters may need smaller time steps and careful
  interpretation.
* **STM covariance propagation** includes analytical :math:`J_2` partials but
  not the full non-linear force model—accuracy degrades for very long
  propagation arcs.

Network and data providers
--------------------------

* **CelesTrak** and **Space-Track** impose rate limits and terms of use. Cache
  catalogs locally for repeated runs.
* **Spacebook / COMSPOC** endpoints are unauthenticated but subject to their
  own availability and rate policies.
* The space-weather CSV payload is capped at **10 MB** as a security measure;
  abnormally large responses are rejected.

Numba JIT
---------

* JIT kernels use ``@njit(fastmath=True)`` which allows IEEE-754 reordering
  and fused operations. Bitwise-identical results between the JIT and
  pure-Python paths are **not** guaranteed; compare integrated trajectories
  or segment-level energy, not individual acceleration samples.
* First call to a JIT function incurs compilation latency. Use
  ``astra.warmup()`` at worker startup to eliminate this.

Validation
----------

* The repository ships **regression and unit tests** (38 test modules), not a
  bundled GMAT/STK/CARA benchmark suite. Perform independent validation if
  your process requires it.

Strict vs relaxed mode
----------------------

**As of v3.6.1, strict mode is enabled by default.** ``astra.config.ASTRA_STRICT_MODE``
ensures missing ephemeris, stale space weather, NaN trajectories, or policy violations
**fail fast** with typed exceptions instead of silent fallbacks:

* EOP fetch failures → ``EphemerisError``
* Covariance dimension mismatches → ``ValueError``
* Monte Carlo Pc failures → ``ValueError``
* Invalid space weather → ``SpaceWeatherError``
* Missing ephemeris data → ``EphemerisError``

To disable strict mode for development or backwards compatibility:

.. code-block:: python

    astra.config.ASTRA_STRICT_MODE = False

See :doc:`installation` for the full list of strict mode exceptions.