satkit/

lib.rs

//! # SatKit: Satellite Toolkit
//!
//! A comprehensive, high-performance satellite astrodynamics library combining the speed of Rust
//! with the convenience of Python. SatKit provides industrial-grade satellite orbital mechanics
//! calculations with a clean, intuitive API. Built from the ground up in Rust for maximum performance
//! and memory safety, it offers complete Python bindings for all functionality, making advanced orbital
//! mechanics accessible to both systems programmers and data scientists.
//!
//! ## Core Features
//!
//! ### Time Systems
//! - Comprehensive timescale transformations (UTC, GPS, UT1, TDB, TT, TAI)
//! - Leap second handling
//! - High-precision time arithmetic and conversions
//!
//! ### Coordinate Frame Transformations
//! High-precision coordinate transforms between multiple reference frames:
//! - **International Terrestrial Reference Frame (ITRF)**: Earth-fixed frame
//! - **Geocentric Celestial Reference Frame (GCRF)**: Inertial frame using IERS 2010 reduction
//! - **True Equinox Mean Equator (TEME)**: Frame used in SGP4 propagation
//! - **Celestial Intermediate Reference Frame (CIRF)**: IERS 2010 intermediate frame
//! - **Terrestrial Intermediate Reference Frame (TIRF)**: Earth-rotation intermediate frame
//! - **RTN / NTW / LVLH**: Satellite-local frames for maneuvers, thrust, and
//!   covariance (`RTN` is the CCSDS OEM canonical name; `RIC` and `RSW` are aliases)
//! - **Geodetic Coordinates**: Latitude, longitude, altitude conversions
//!
//! Unified API: [`frametransform::rotation`] / [`frametransform::transform_state`]
//! dispatch any Earth-chain frame pair, [`frametransform::rotation_with_state`]
//! additionally covers the orbit-local frames (RTN / NTW / LVLH), and
//! [`frametransform::to_gcrf`] / [`frametransform::from_gcrf`] give the
//! orbit-local direction-cosine matrices directly — together they replace the
//! per-frame helper explosion.
//!
//! ### Orbit Propagation
//! Multiple propagation methods for various accuracy requirements:
//! - **SGP4**: Simplified General Perturbations for Two-Line Element (TLE) sets with fitting capability
//! - **Numerical Integration**: High-precision propagation using adaptive
//!   Runge-Kutta (9(8), 8(7), 6(5), 5(4)), RODAS4 (stiff), or **Gauss-Jackson 8**
//!   (fixed-step multistep predictor-corrector specialised for long-duration
//!   orbit propagation, with per-step dense output)
//! - **Keplerian**: Simplified two-body propagation
//! - **State Transition Matrix**: Support for covariance propagation
//! - **Configurable `max_steps`**: [`PropSettings::max_steps`] bounds runaway propagation
//!
//! ### Orbit Maneuvers
//! - **Impulsive maneuvers**: Instantaneous delta-v at scheduled times in GCRF,
//!   RTN (= RIC / RSW), NTW, or LVLH frames. Ergonomic helpers (`prograde`,
//!   `retrograde`, `radial_out`, `normal`) cover the common scalar-magnitude burns.
//! - **Continuous thrust**: Constant-acceleration arcs integrated into the force model
//! - Automatic propagation segmentation through maneuver sequences, including
//!   backward propagation
//!
//! ### Force Models
//! Comprehensive perturbation modeling:
//! - High-order Earth gravity (JGM2, JGM3, EGM96, ITU GRACE16)
//! - Solar and lunar gravity perturbations
//! - Atmospheric drag using NRLMSISE-00 density model with space weather data
//! - Solar radiation pressure
//! - Continuous thrust acceleration
//!
//! ### Ephemerides
//! - **JPL Ephemerides**: High-precision planetary and lunar positions
//! - **Low-Precision Ephemerides**: Fast analytical models for sun and moon
//!
//! ### Additional Capabilities
//! - Keplerian orbital elements and conversions
//! - Geodesic distance calculations
//! - TLE parsing, generation, and orbit fitting
//!
//! ## Language Bindings
//!
//! - **Rust**: Native library available on [crates.io](https://crates.io/crates/satkit)
//! - **Python**: Complete Python bindings via PyO3, available on [PyPI](https://pypi.org/project/satkit/)
//!   - Binary wheels for Windows, macOS (Intel & ARM), and Linux (x86_64 & ARM64)
//!   - Python versions 3.10 through 3.14
//!   - Documentation at <https://satkit.dev/>
//!
//! ## Linear Algebra
//!
//! SatKit uses the [`numeris`](https://crates.io/crates/numeris) crate for all linear algebra
//! (vectors, matrices, quaternions, ODE solvers). Types are re-exported via [`mathtypes`].
//! If you need nalgebra types for interoperability with other crates, enable the `nalgebra`
//! feature on `numeris` for zero-cost `From`/`Into` conversions:
//!
//! ```toml
//! numeris = { version = "0.5.7", features = ["nalgebra"] }
//! ```
//!
//! ## Optional Features
//!
//! - **chrono**: Enables interoperability with `chrono::DateTime` by implementing the `TimeLike` trait.
//!   Activate with Cargo feature `chrono`.
//!
//! ## Getting Started
//!
//! ### Data Files
//!
//! The library requires external data files for many calculations:
//!
//! - [JPL Planetary Ephemerides](https://ssd.jpl.nasa.gov/ephem.html) - High-precision planetary positions
//! - [Earth Gravity Models](http://icgem.gfz-potsdam.de/) - Spherical harmonic coefficients
//! - [Space Weather Data](https://celestrak.org/SpaceData/) - Solar flux and geomagnetic indices
//! - [Earth Orientation Parameters](https://celestrak.org/SpaceData/) - Polar motion and UT1-UTC
//! - [IERS Conventions Tables](https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html) - Nutation coefficients
//!
//! Data files need to be downloaded once. Space weather and Earth orientation parameter files are
//! updated daily and should be refreshed periodically for optimal accuracy.
//!
//! ### Downloading Data Files
//!
//! Requires building with the `download` Cargo feature.
//!
//! ```no_run
//! // Print the directory where data will be stored
//! println!("Data directory: {:?}", satkit::utils::datadir());
//!
//! // Download required data files
//! // - Downloads missing files
//! // - Updates space weather and Earth orientation parameters
//! // - Skips files that already exist
//! # #[cfg(feature = "download")]
//! satkit::utils::update_datafiles(None, false);
//! ```
//!
//! ## Example Usage
//!
//! ```no_run
//! use satkit::prelude::*;
//!
//! // Create a time instant
//! let time = Instant::from_datetime(2024, 1, 1, 12, 0, 0.0).unwrap();
//!
//! // Coordinate frame transformations
//! let itrf_pos = ITRFCoord::from_geodetic_deg(42.0, -71.0, 100.0);
//!
//! // Get planetary ephemeris
//! let (moon_pos, moon_vel) = satkit::jplephem::geocentric_state(
//!     SolarSystem::Moon,
//!     &time
//! ).unwrap();
//! ```
//!
//! ## Running Tests
//!
//! Tests require external data files and test vectors. Download them with the provided scripts:
//!
//! ```bash
//! pip install requests
//! python python/test/download_testvecs.py
//! ```
//!
//! Then run with the environment variables set:
//!
//! ```bash
//! SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs cargo test
//! ```
//!
//! ## References
//!
//! This implementation relies heavily on the following excellent references:
//!
//! - **"Fundamentals of Astrodynamics and Applications, Fourth Edition"**
//!   by D. Vallado, Microcosm Press and Springer, 2013
//! - **"Satellite Orbits: Models, Methods, Applications"**
//!   by O. Montenbruck and E. Gill, Springer, 2000
//!
//! ## License
//!
//! MIT License - See LICENSE file for details

#![warn(clippy::all, clippy::use_self, clippy::cargo)]
#![allow(clippy::multiple_crate_versions)]

// Math type definitions using the numeris crate
pub mod mathtypes;

/// Universal constants
pub mod consts;
/// Earth orientation parameters (polar motion, delta-UT1, length of day)
pub mod earth_orientation_params;
/// Zonal gravity model for Earth gravity
pub mod earthgravity;
/// Conversion between coordinate frames
pub mod frametransform;
/// International Terrestrial Reference Frame coordinates &
/// transformations to Geodetic, East-North-Up, North-East-Down
pub mod itrfcoord;
/// Solar system body ephemerides, as published by the Jet Propulsion Laboratory (JPL)
pub mod jplephem;
/// Keplerian orbital elements
pub mod kepler;
/// Lambert's problem solver for orbital targeting
pub mod lambert;
/// Low-precision ephemeris for sun and moon
pub mod lpephem;
/// NRLMSISE-00 Density model
pub mod nrlmsise;
/// High-Precision Orbit Propagation using numeris ODE solvers
pub mod orbitprop;
/// SGP-4 Orbit Propagator
pub mod sgp4;
/// Solar Cycle Forecast (NOAA/SWPC predicted F10.7)
pub mod solar_cycle_forecast;
/// Solar system bodies
mod solarsystem;
/// Space Weather
pub mod spaceweather;
/// Two-line Element Set
pub mod tle;
/// Utility functions
pub mod utils;

/// Coordinate frames (re-exported as `Frame` at crate root)
pub mod frames;

// Orbital Mean-Element Messages
pub mod omm;

// Time and duration
mod time;
pub use time::{
    Duration, Instant, InstantError, InvalidTimeScale, InvalidWeekday, TimeLike, TimeScale, Weekday,
};

// Top-level façade error type (deprecated 0.17.0; re-exported for source compat).
mod error;
#[allow(deprecated)]
pub use error::{Error, Result};

// Core types available at crate level
pub use frames::Frame;
pub use itrfcoord::{Geodetic, ITRFCoord};
pub use kepler::Kepler;
pub use mathtypes::{Quaternion, Vector3};
pub use orbitprop::{propagate, PropSettings, SatState};
pub use solarsystem::SolarSystem;
pub use tle::TLE;

/// Prelude for convenient wildcard import.
///
/// Brings the most commonly used types, traits, and functions into scope.
///
/// ```
/// use satkit::prelude::*;
/// ```
pub mod prelude {
    // Math types
    pub use crate::mathtypes::{Matrix3, Matrix6, Quaternion, Vector3, Vector6};

    // Time
    pub use crate::time::{Duration, Instant, TimeLike, TimeScale, Weekday};

    // Core types
    pub use crate::frames::Frame;
    pub use crate::itrfcoord::{Geodetic, ITRFCoord};
    pub use crate::kepler::{Anomaly, Kepler};
    pub use crate::lambert::lambert;
    pub use crate::omm::OMM;
    pub use crate::solarsystem::SolarSystem;
    pub use crate::tle::TLE;

    // Propagation
    pub use crate::orbitprop::{
        propagate, CovState, PropSettings, PropagationResult, SatProperties, SatPropertiesSimple,
        SatState, SimpleState, StateCov,
    };

    // SGP4
    pub use crate::sgp4::{sgp4, GravConst, OpsMode, SGP4State};

    // Frame transforms
    pub use crate::frametransform::{qgcrf2itrf, qitrf2gcrf, qteme2gcrf, qteme2itrf};

    // Gravity
    pub use crate::earthgravity::GravityModel;
}