satkit 0.9.3

Satellite Orbital Dynamics Toolkit

Satellite Toolkit (satkit)

A comprehensive, high-performance satellite astrodynamics library combining the speed of Rust with the convenience of Python.

Satkit provides robust, high-performance 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.

---

---

Language Bindings

• Native Rust: Available as a crate on crates.io
• Python: Comprehensive Python bindings via PyO3, combining Rust performance with Python convenience
  • Install with pip install satkit
  • Binary packages available for Windows, macOS (Intel & ARM), and Linux (x86_64 & ARM64)
  • Python versions 3.8 through 3.14 supported
  • Full documentation at https://satellite-toolkit.readthedocs.io/latest/

Optional Features

• chrono: Enables interoperability with chrono::DateTime by implementing the TimeLike trait. Activate with Cargo feature chrono.

Key Capabilities

Coordinate Frame Transformations

High-precision conversions between multiple reference frames with full support for time-varying Earth orientation:

• ITRF - International Terrestrial Reference Frame (Earth-fixed)
• GCRF - Geocentric Celestial Reference Frame using IAU-2000/2006 reduction (inertial)
• TEME - True Equinox Mean Equator frame used in SGP4 propagation (almost inertial)
• CIRF - Celestial Intermediate Reference Frame (IAU-2006 intermediate)
• TIRF - Terrestrial Intermediate Reference Frame (Earth-rotation intermediate)
• Geodetic - Latitude, longitude, altitude with WGS-84 ellipsoid

Orbit Propagation

Multiple propagation methods optimized for different accuracy and performance requirements:

• Numerical Integration: High-precision propagation using adaptive Runge-Kutta 9(8) methods with dense output
  • Supports state transition matrix computation for covariance propagation
  • Configurable force models and integration tolerances
  • Efficient interpolation for arbitrary epoch queries
• SGP4: Industry-standard propagator for Two-Line Element (TLE) sets
  • Full AFSPC and improved mode support
  • TLE fitting from high-precision states with drag estimation
  • Batch processing for multiple satellites
  • Support TLE and Orbital Mean-Element Messages inputs
• Keplerian: Fast analytical two-body propagation for preliminary analysis

Numerical Integration Force Models

Comprehensive perturbation modeling for high-fidelity orbit propagation:

• Earth Gravity: Spherical harmonic models up to degree/order 360
  • Multiple models: JGM2, JGM3, EGM96, ITU GRACE16
  • Efficient computation with configurable truncation order
  • Gravity gradient support for state transition matrix
• Third-Body Gravity: Solar and lunar perturbations using JPL ephemerides
• Atmospheric Drag:
  • NRLMSISE-00 density model with space weather integration
  • Automatic space weather data updates (F10.7, Ap index)
  • Configurable ballistic coefficients
• Solar Radiation Pressure: Cannon-ball model with shadow function

Solar System Ephemerides

Access to high-precision solar system body positions:

• JPL DE440/DE441: State-of-the-art planetary ephemerides
  • Chebyshev polynomial interpolation for accuracy
  • Support for all major planets, sun, moon, and solar system barycenter
• Low-Precision Models: Fast analytical models for sun and moon when high precision isn't required

Time Systems

Comprehensive support for all standard astronomical time scales:

• UTC - Coordinated Universal Time with leap second handling
• TAI - International Atomic Time
• TT - Terrestrial Time
• TDB - Barycentric Dynamical Time
• UT1 - Universal Time with Earth orientation corrections
• GPS - GPS Time
• Automatic conversion between all time scales with microsecond precision

Geodetic Utilities

• Geodesic Calculations - Accurate distance and azimuth between ground locations using Vincenty's formulae
• Coordinate Conversions - ITRF ↔ Geodetic ↔ East-North-Up ↔ North-East-Down
• Elevation/Azimuth - Topocentric coordinate transformations for ground station analysis

Sun / Moon Calculations

• Sun rise / set - Compute sun rise / set times as function of day & location
• Moon Phase - Phase of moon and fraction illuminated
• Ephemeris - Fast low-precision ephemeris for sun & moon

Technical Details

ODE Solvers

The numerical orbit propagation engine employs adaptive Runge-Kutta methods for integration of ordinary differential equations. The pure-Rust ODE solver features:

• Adaptive Step Size Control: Automatically adjusts step size based on error tolerance
• Dense Output: Efficient interpolation for state queries at arbitrary times without re-integration
• High-Order Methods: Runge-Kutta 9(8) pairs for optimal accuracy and stability
• State Transition Matrix: Optional computation for covariance propagation and sensitivity analysis

Integration coefficients are based on the work of Jim Verner: https://www.sfu.ca/~jverner/

Performance Characteristics

• Zero-Cost Abstractions: Rust's ownership model enables safe code without runtime overhead
• SIMD-Friendly: Designed to take advantage of modern CPU vector instructions
• Memory Efficient: Static typing and stack allocation minimize heap pressure
• Parallel Processing: Thread-safe APIs enable concurrent propagation of multiple satellites
• Python Integration: Near-native performance in Python via PyO3 bindings with minimal overhead

References, Models, and External Data

Theoretical Foundation

The equations and many unit tests are based on the following authoritative sources:

• "Fundamentals of Astrodynamics and Applications, Fourth Edition", D. Vallado, Microcosm Press and Springer, 2013.
  https://celestrak.org/software/vallado-sw.php
• "Satellite Orbits: Models, Methods, Applications", O. Montenbruck and E. Gill, Springer, 2000.
  https://doi.org/10.1007/978-3-642-58351-3

Data Dependencies

The library requires external data files for various calculations. These are automatically downloaded by the update_datafiles() function:

Core Data Files (One-Time Download)

• JPL Ephemerides (JPL Solar System Dynamics)

  • DE440/DE441 planetary ephemerides (~100 MB)
  • Provides positions of sun, moon, planets, and solar system barycenter
  • Valid for years 1550-2650 CE

• Gravity Models (ICGEM)

  • JGM2, JGM3, EGM96, ITU GRACE16 spherical harmonic coefficients
  • International Centre for Global Earth Models standardized format
  • Up to degree/order 360 for high-fidelity propagation

• IERS Nutation Tables (IERS Conventions)

  • IAU-2006 nutation series coefficients
  • Required for GCRF ↔ ITRF transformations
  • Technical Note 36 reference tables

Regularly Updated Data Files (Daily Updates Recommended)

• Space Weather Indices (Celestrak)

  • F10.7 solar flux (past and predicted)
  • Ap geomagnetic index
  • Critical for atmospheric density modeling and drag calculations
  • Updated daily by NOAA Space Weather Prediction Center

• Earth Orientation Parameters (Celestrak)

  • Polar motion (x, y)
  • UT1-UTC time difference
  • Length of day variations
  • Essential for high-precision GCRF ↔ ITRF conversions
  • Updated daily by IERS

The update_datafiles() function intelligently manages these files:

• Downloads missing files
• Always refreshes space weather and EOP data
• Skips existing files to save bandwidth
• Stores files in a platform-specific data directory

Verification and Testing

The library includes comprehensive test suites ensuring correctness of calculations:

Test Coverage

• JPL Ephemerides: Validated against JPL-provided test vectors for Chebyshev polynomial interpolation

  • Over 10,000 test cases covering all planets and time ranges
  • Accuracy verified to within JPL's published tolerances (sub-meter precision)

• SGP4: Verified using official test vectors from the original C++ distribution

  • All test cases from Vallado's SGP4 implementation
  • Includes edge cases and error conditions

• Coordinate Transformations: Cross-validated against multiple reference implementations

  • SOFA library comparisons for IAU-2006 transformations
  • Vallado test cases for GCRF ↔ ITRF conversions

• Numerical Propagation: Validated against high-precision commercial tools

  • Orbit fits to GPS SP3 ephemerides
  • Multi-day propagations with sub-meter accuracy

Continuous Integration

• Automated testing on multiple platforms (Linux, macOS, Windows)
• Python versions 3.8-3.14 tested on each platform
• Clippy linting for code quality
• Documentation build verification

Getting Started

Installation

Rust

Add satkit to your Cargo.toml:

[dependencies]
satkit = "0.8"

Or use cargo add:

cargo add satkit

Python

Install from PyPI using pip:

pip install satkit

Pre-built binary wheels are available for:

• Windows: AMD64
• macOS: Intel (x86_64) and Apple Silicon (ARM64)
• Linux: x86_64 and ARM64 (aarch64)
• Python versions: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14

Initial Setup

After installation, download the required data files needed for calculations. This is a one-time operation, though space weather and Earth orientation parameters should be updated periodically (daily updates available).

Rust:

use satkit::utils;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Download data files to default location
    utils::update_datafiles(None, false)?;
    Ok(())
}

Python:

import satkit as sk

# Download data files to default location
sk.utils.update_datafiles()

Quick Start Examples

Coordinate Transformations (Python)

import satkit as sk
from datetime import datetime, timezone

# Create a time instant
time = sk.time(2024, 1, 1, 12, 0, 0)

# Define position in ITRF (Earth-fixed) frame
itrf_pos = sk.itrfcoord(latitude_deg=42.0, longitude_deg=-71.0, altitude=100.0)

# Get the ITRF to GCRF (inertial) rotation quaternion
q = sk.frametransform.qitrf2gcrf(time)

# Transform to GCRF
gcrf_pos = q * itrf_pos.vector
print(f"GCRF position: {gcrf_pos}")

Orbit Propagation (Python)

import satkit as sk
import numpy as np

# Initial state vector [x, y, z, vx, vy, vz] in GCRF frame
r0 = 6378e3 + 500e3  # 500 km altitude
v0 = np.sqrt(sk.consts.mu_earth / r0)
state0 = np.array([r0, 0, 0, 0, v0, 0])

# Start time
time0 = sk.time(2024, 1, 1)

# Propagation settings
settings = sk.propsettings()
settings.gravity_model = sk.gravmodel.JGM3
settings.gravity_order = 8

# Propagate for 1 day
result = sk.propagate(
    state0,
    time0,
    end=time0 + sk.duration.from_days(1),
    propsettings=settings
)

# Query state at any time
query_time = time0 + sk.duration.from_hours(6)
state = result.interp(query_time)
print(f"State after 6 hours: {state}")

SGP4 Propagation (Python)

import satkit as sk

# Load TLE
lines = [
    "ISS (ZARYA)",
    "1 25544U 98067A   24001.50000000  .00016717  00000-0  10270-3 0  9003",
    "2 25544  51.6432 351.4697 0007417 130.5364 329.6482 15.48915330299357"
]
tle = sk.TLE.from_lines(lines)

# Propagate TLE
time = sk.time(2024, 1, 2)
pos, vel = sk.sgp4(tle, time)
print(f"ISS position: {pos}")

Planetary Ephemerides (Rust)

use satkit::{Instant, SolarSystem, jplephem};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create time instant
    let time = Instant::from_datetime(2024, 1, 1, 0, 0, 0.0)?;

    // Get Moon position and velocity in GCRF
    let (pos, vel) = jplephem::geocentric_state(SolarSystem::Moon, &time)?;

    println!("Moon position: {:?}", pos);
    println!("Moon velocity: {:?}", vel);

    Ok(())
}

Documentation

• Rust API Documentation: Available on docs.rs
• Python Documentation: Comprehensive guide at satellite-toolkit.readthedocs.io
  • Getting started tutorials
  • API reference with examples
  • Theory and implementation notes
  • Data file management guide

Use Cases

Satkit is suitable for a wide range of applications:

• Satellite Operations: Real-time tracking and orbit determination
• Mission Planning: Trajectory design and optimization
• Space Situational Awareness: Conjunction assessment and collision avoidance
• Ground Station Management: Visibility predictions and pass planning
• Research and Education: Orbital mechanics analysis and experimentation
• Simulation: High-fidelity orbit propagation for testing and validation

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for:

• Bug fixes and improvements
• New features and capabilities
• Documentation enhancements
• Additional test cases
• Performance optimizations

See the GitHub repository for contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Steven Michael - [e-mail]

For questions, bug reports, or feature requests, please open an issue on GitHub or contact the author directly.

Acknowledgments

This work builds upon the theoretical foundations established by:

• Dr. David Vallado - "Fundamentals of Astrodynamics and Applications"
• Dr. Oliver Montenbruck & Dr. Eberhard Gill - "Satellite Orbits: Models, Methods, Applications"
• Dr. Jim Verner - Runge-Kutta integration coefficients
• The international space community for maintaining critical data products (IERS, JPL, NOAA, ICGEM)