Installation¶

ASTRA-Core is published on PyPI as astra-core-engine and supports Python 3.10, 3.11, 3.12, and 3.13 on Windows, macOS, and Linux.

Core install¶

pip install astra-core-engine

This installs runtime dependencies:

numpy (>=1.23.5, <2.3.0) — arrays and vectorized operations
scipy (>=1.11.0) — ODE integration, spatial indexing, quadrature
skyfield (>=1.46) — DE421 ephemeris loader, IERS timescales, frame transforms
sgp4 (>=2.23) — SGP4/SDP4 propagation
requests (>=2.31.0) — HTTP for CelesTrak, Space-Track, and Spacebook
numba (>=0.59.0) — JIT for Cowell acceleration kernels
defusedxml (>=0.7.1) — hardened CDM XML parsing

Optional: visualization (Plotly)¶

3D trajectory plotting lives in astra.plot. Plotly is not required for core physics. Install it with the viz extra:

pip install "astra-core-engine[viz]"

The top-level names plot_trajectories and plot_ground_track are lightweight wrappers, so from astra import * works in a core install. Calling either function without Plotly installed raises a clear ImportError pointing to the viz extra.

Development and tests¶

git clone https://github.com/ISHANTARE/ASTRA.git
cd ASTRA
pip install -e ".[test]"

The test extra includes pytest >=8.0, plotly >=5.18, and type-stub packages (scipy-stubs, types-requests, types-defusedxml), plus mypy so the full test suite and type checks run in CI.

Pytest is configured in pyproject.toml with strict marker/config validation. Test-time data, Numba, pytest cache files, and temporary files default to ASTRA_TEST_CACHE_DIR or, if unset, a deterministic directory under the test tree (tests/.astra-test-cache). Set ASTRA_TEST_CACHE_DIR in CI or local shells when you need an explicitly controlled cache root outside the workspace.

Verifying the install¶

import astra
print(astra.__version__)   # Should print e.g. "3.6.2"

Optional: pre-fetch IERS / cache data before long runs:

from astra import time as astra_time
astra_time.prefetch_iers_data_async()

Override the data directory with the environment variable ASTRA_DATA_DIR if you need a fixed cache location for air-gapped systems. The default cache is ~/.astra/data/.

JIT warm-up¶

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

import astra

astra.warmup()   # pre-compiles Numba kernels — call once per process

Strict mode (default ON)¶

As of v3.6.1, strict mode is enabled by default. This is the recommended setting for production systems. When strict mode is enabled, the library raises typed exceptions instead of silently continuing with degraded data:

Strict mode exceptions¶
Condition	Exception
EOP fetch failure	`EphemerisError`
Covariance dimension mismatch	`ValueError`
Monte Carlo Pc failure	`ValueError`
Invalid space weather	`SpaceWeatherError`
Missing ephemeris data	`EphemerisError`

To disable strict mode for development or backwards compatibility:

import astra
astra.config.ASTRA_STRICT_MODE = False

Type hints (PEP 561)¶

The package ships py.typed for static analysis tools (mypy, pyright) that consume inline annotations. mypy is pre-configured in pyproject.toml as a CI baseline; the current configuration is intentionally non-strict while the numerical array-heavy APIs are incrementally typed.