astra.data_pipeline module

ASTRA Core High-Fidelity Data Pipeline. Provides automated, cached access to the real-world physical data required by the operations-grade force model:

1. JPL DE421 Ephemeris — precise Sun and Moon positions via Skyfield. (DE421 covers 1900–2050 at ~17 MB. For 1549–2650, replace with DE440.)

2. IERS Earth-Orientation Parameters — polar motion, UT1-UTC via Skyfield’s finals2000A.all loader.

3. CelesTrak Space-Weather — daily F10.7 solar flux and Kp/Ap geomagnetic indices for empirical atmospheric density models.

All heavy files are downloaded once and cached to a user-configurable directory (default ~/.astra/data/). Subsequent calls use the local cache. The cache can be explicitly refreshed. .. rubric:: References

Park et al. (2021). JPL Planetary and Lunar Ephemerides DE440/DE441. IERS Conventions (2010), Technical Note No. 36. Vallado & Finkleman (2008). A Critical Assessment of Satellite Drag …

astra.data_pipeline.get_skyfield_timescale(data_dir=None)

Return the managed Skyfield Timescale (IERS finals2000A), after ensuring cache load. Use this instead of ad-hoc load.timescale(builtin=True) so UT1-UTC and conversions share one current-EOP source.

astra.data_pipeline.sun_position_de(t_jd, data_dir=None)

Geocentric Sun position from JPL DE421 ephemeris. Returns the GCRS (≈ J2000 ECI) position of the Sun at Julian Date t_jd, in kilometres. This replaces the Meeus analytical approximation with sub-arcsecond accuracy. :param t_jd: Julian Date (TDB scale is ideal; TT or UTC are acceptable

for the force-model level of accuracy).

Parameters:

data_dir – Optional override for the data cache directory.

Returns:

Shape (3,) numpy array [x, y, z] in km, GCRS frame.

astra.data_pipeline.sun_position_teme(t_jd, data_dir=None)

Geocentric Sun position in TEME frame (km). Used by the propagator. Converts the DE421 GCRS output to TEME so the propagation kernel can subtract satellite and body positions without a frame mismatch. The rotation is TEME.rotation_at(t).T (transpose = inverse for orthogonal matrix). :param t_jd: Julian Date. :param data_dir: Optional override for the data cache directory.

Returns:

Shape (3,) numpy array [x, y, z] in km, TEME frame.

astra.data_pipeline.moon_position_de(t_jd, data_dir=None)

Geocentric Moon position from JPL DE421 ephemeris. Returns the GCRS (≈ J2000 ECI) position of the Moon at Julian Date t_jd, in kilometres. This replaces the Brown lunar theory approximation with sub-arcsecond accuracy. :param t_jd: Julian Date. :param data_dir: Optional override for the data cache directory.

Returns:

Shape (3,) numpy array [x, y, z] in km, GCRS frame.

astra.data_pipeline.moon_position_teme(t_jd, data_dir=None)

Geocentric Moon position in TEME frame (km). Used by the propagator. Converts the DE421 GCRS output to TEME so the propagation kernel can subtract satellite and body positions without a frame mismatch. :param t_jd: Julian Date. :param data_dir: Optional override for the data cache directory.

Returns:

Shape (3,) numpy array [x, y, z] in km, TEME frame.

astra.data_pipeline.get_ut1_utc_correction(t_jd_utc)

Return UT1-UTC offset in seconds for given UTC Julian Date(s). Interprets the input Julian Date as UTC (not TT). Builds Skyfield Time via calendar UTC, then uses Time.dut1 (UT1−UTC in seconds). :param t_jd_utc: Julian Date in UTC (scalar or array).

Returns:

UT1-UTC time offset in seconds.

astra.data_pipeline.load_space_weather(data_dir=None, force_download=False)

Ensure space-weather data is available in memory. Downloads the CSV from CelesTrak on first call (or if the local cache is older than 24 hours), then parses into memory. If local file exists but is stale, spins a background thread to update it without blocking physics loops. Thread-safe via double-checked locking. A fast check under _SW_LOCK provides the common O(1) exit. The slow path acquires _SW_DOWNLOAD_LOCK so only one thread downloads + parses; the rest re-check under that lock and exit cleanly once the winner finishes. :param data_dir: Override data directory. :param force_download: If True, re-download even if a cached file exists.

astra.data_pipeline.get_space_weather(t_jd, data_dir=None)

Retrieve F10.7 solar flux and Ap index for a given Julian Date. Priority hierarchy: 1. Spacebook: Defaults to Spacebook (higher precision, COMSPOC-verified)

if ASTRA_SPACEBOOK_ENABLED=true.

2. CelesTrak: Falls back to legacy CelesTrak CSV if Spacebook fails or is disabled.

3. Synthetic Defaults: Returns (150, 150, 15) if no data is found and ASTRA_STRICT_MODE=False.

Parameters:

• t_jd – Julian Date.

• data_dir – Override data directory.

Returns:

Tuple (F10.7_obs, F10.7_adj, Ap_daily).

astra.data_pipeline.nrlmsise00_density(altitude_km, f107_obs, f107_adj, ap_daily)

Compute atmospheric density using a simplified NRLMSISE-00-inspired Bates profile.

Note

This is not a full NRLMSISE-00 implementation (Picone et al. 2002). It uses a single-species Bates exospheric temperature profile calibrated against NRLMSISE-00 output at 400 km. Accuracy is +/-15% for 150-600 km altitude at moderate solar activity (F10.7 100-200). Below 150 km or above 600 km, or during extreme geomagnetic storms (Ap > 100), errors may exceed 30%. For mission-critical drag modelling, consider interfacing with the full NRLMSISE-00 C implementation via pynrlmsise00.

This function delegates to the canonical Numba implementation in propagator.py to guarantee identical physics across the codebase.

astra.data_pipeline.atmospheric_density_empirical(altitude_km, f107_obs, f107_adj, ap_daily)

Compute atmospheric density using an empirical model. In v3.6.0, this function defaults to the High-Fidelity NRLMSISE-00 implementation for improved accuracy across all solar regimes.