Metadata-Version: 2.4
Name: satkit
Version: 0.24.1
Summary: Satellite Orbital Dynamics Toolkit
Author-email: Steven Michael <ssmichael@gmail.com>
Maintainer-email: Steven Michael <ssmichael@gmail.com>
License-Expression: MIT OR Apache-2.0
Keywords: satellite,orbit,astrodynamics,SGP4,TLE,JPL,Ephemeris
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
License-File: THIRDPARTY-DATA.md
Requires-Dist: numpy>=1.0.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: mypy; extra == "test"
Requires-Dist: scipy; extra == "test"
Requires-Dist: pyerfa; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Dynamic: license-file

# satkit

**Satellite astrodynamics in Rust, with full Python bindings.**

![Build](https://github.com/ssmichael1/satkit/actions/workflows/build.yml/badge.svg)
![Release](https://github.com/ssmichael1/satkit/actions/workflows/release.yml/badge.svg)
![License: MIT OR Apache-2.0](https://img.shields.io/github/license/ssmichael1/satkit)

[![Crates.io](https://img.shields.io/crates/v/satkit)](https://crates.io/crates/satkit)
[![Crates.io Downloads](https://img.shields.io/crates/dr/satkit)](https://crates.io/crates/satkit)
[![PyPI](https://img.shields.io/pypi/v/satkit)](https://pypi.org/project/satkit/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/satkit)](https://pypi.org/project/satkit/)
[![Python](https://img.shields.io/pypi/pyversions/satkit)](https://pypi.org/project/satkit/)
[![conda-forge](https://img.shields.io/conda/vn/conda-forge/satkit)](https://anaconda.org/conda-forge/satkit)
[![conda-forge Downloads](https://img.shields.io/conda/dn/conda-forge/satkit)](https://anaconda.org/conda-forge/satkit)

---

Satkit is a high-performance orbital mechanics library written in Rust with complete Python bindings via PyO3. It handles coordinate transforms, orbit propagation, time systems, gravity models, atmospheric density, and JPL ephemerides -- everything needed for satellite astrodynamics work.

**[Documentation and tutorials](https://satkit.dev/)** (Python examples, but the concepts and API apply equally to Rust) | **[Rust API reference](https://docs.rs/satkit/)** | **[Changelog](CHANGELOG.md)**

## Installation

**Rust:**
```bash
cargo add satkit
```

**Python:**
```bash
pip install satkit
```

Pre-built wheels are available for Linux (x86_64, aarch64), macOS (Apple silicon), and Windows (x86_64) on Python 3.11--3.15; Intel Macs build from source (`pip install --no-binary satkit satkit`) or use conda-forge.

The IERS nutation tables and gravity models are compiled in, so frames, gravity, SGP4 and time work with no data files. The JPL ephemeris downloads on first use, and Earth orientation and space weather are fetched on first use and refreshed with `satkit.utils.update_datafiles()`. See [Data Files](https://satkit.dev/getting-started/datafiles/) for directories and offline use.

## Quick Examples

### SGP4 propagation (Python)

```python
import satkit as sk

tle = sk.TLE.from_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"
])[0]

pos, vel = sk.sgp4(tle, sk.time(2024, 1, 2))
```

### High-precision propagation (Python)

```python
import satkit as sk
import numpy as np

r0 = 6378e3 + 500e3  # 500 km altitude
v0 = np.sqrt(sk.consts.mu_earth / r0)

settings = sk.propsettings(
    gravity_model=sk.gravmodel.egm2008,  # default; also egm96, jgm3, jgm2, itugrace16
    gravity_degree=8,
    integrator=sk.integrator.rkv98,    # default; also rkv87, rkv65, rkts54,
                                       # gauss_jackson8 (fixed-step multistep)
)

result = sk.propagate(
    np.array([r0, 0, 0, 0, v0, 0]),
    sk.time(2024, 1, 1),
    end=sk.time(2024, 1, 1) + sk.duration.from_days(1),
    propsettings=settings,
)

state = result.interp(sk.time(2024, 1, 1) + sk.duration.from_hours(6))
```

### Coordinate transforms (Python)

```python
import satkit as sk

time = sk.time(2024, 1, 1, 12, 0, 0)
coord = sk.itrfcoord(latitude_deg=42.0, longitude_deg=-71.0, altitude=100.0)

q = sk.frametransform.qitrf2gcrf(time)
gcrf_pos = q * coord.vector
```

### Planetary ephemerides (Rust)

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

let time = Instant::from_datetime(2024, 1, 1, 0, 0, 0.0)?;
let (pos, vel) = jplephem::geocentric_state(SolarSystem::Moon, &time)?;
```

## Features

### Coordinate Frames

Full IERS 2010 Conventions reduction (IAU 2006/2000A precession-nutation) with Earth orientation parameters:

| Frame | Description |
|-------|-------------|
| ITRF | International Terrestrial Reference Frame (Earth-fixed) |
| GCRF | Geocentric Celestial Reference Frame (inertial) |
| TEME | True Equator Mean Equinox (SGP4 output frame) |
| CIRS | Celestial Intermediate Reference System |
| TIRS | Terrestrial Intermediate Reference System |
| EME2000 / ICRF | J2000 mean equator and the International Celestial Reference Frame |
| Geodetic | Latitude / longitude / altitude (WGS-84) |

Plus satellite-local RTN, NTW, and LVLH frames (maneuvers, covariance), and ENU, NED, and geodesic distance (Vincenty) utilities.

### Orbit Propagation

- **Numerical** -- Selectable adaptive Runge-Kutta integrators (9(8), 8(7), 6(5), 5(4)) plus RODAS4 (stiff) and Gauss-Jackson 8 (fixed-step multistep for high-precision long-duration propagation), with dense output, state transition matrix, and configurable force models. With matched force models it agrees with NASA GMAT to a few centimetres over 7 days in LEO, MEO, and GEO (see [Testing and Validation](#testing-and-validation))
- **SGP4** -- Standard TLE/OMM propagator with TLE fitting from precision states
- **Keplerian** -- Analytical two-body propagation

### Orbit Maneuvers

- **Impulsive maneuvers** -- Instantaneous delta-v applied at a scheduled time during propagation. Supported frames: GCRF (inertial), RTN (radial/tangential/normal — the CCSDS OEM convention, also exposed as `RSW` and `RIC` aliases), NTW (velocity-aligned — natural for prograde burns on eccentric orbits, where a pure +T delta-v adds exactly Δv to |v|), and LVLH (Local Vertical / Local Horizontal). Ergonomic helpers `add_prograde` / `add_retrograde` / `add_radial` / `add_normal` for common scalar-magnitude burns.
- **Continuous thrust** -- Constant-acceleration thrust arcs over time windows in any of the frames above, integrated directly into the force model
- **Automatic segmentation** -- Propagation through maneuver sequences is handled transparently, including backward propagation

### Force Models

- **Earth gravity**: EGM96, EGM2008, JGM2, JGM3, ITU GRACE16 (spherical harmonics up to degree/order 70; Montenbruck & Gill 2000, §3.2), with tide-system-aware solid tides
- **Solid Earth tides**: IERS Conventions 2010 §6.2.1 Step-1 corrections to the gravity field
- **Third-body gravity**: Sun and Moon via JPL DE440/441 ephemerides
- **Atmospheric drag**: NRLMSISE-00 (Picone et al. 2002) fed automatically from the GFZ Potsdam observed record (observed F10.7 / centred F10.7A and the 7-element 3-hourly geomagnetic ap history, so density responds to storms within hours), then the NOAA/SWPC 45-day and NASA MSAFE monthly forecasts, which carry a climatological Ap years ahead; validated against GMAT (below)
- **Solar radiation pressure**: Cannonball model with shadow function and inverse-square Sun-distance scaling
- **Relativity**: IERS 2010 Eq. 10.12 — Schwarzschild, geodesic (de Sitter) precession, and Lense–Thirring

### Time Systems

Seamless conversion between UTC, TAI, TT, TDB, UT1, and GPS time scales with full leap-second handling.

### Solar System

- JPL DE440/DE441 ephemerides for all planets, Sun, Moon, and barycenters
- Fast analytical Sun/Moon models for lower-precision work
- Sunrise/sunset and Moon phase calculations

### Linear Algebra

SatKit uses [numeris](https://crates.io/crates/numeris) for all linear algebra (vectors, matrices, quaternions, ODE integration). If you also use nalgebra in your project, enable the `nalgebra` feature on numeris for zero-cost `From`/`Into` conversions between types:

```toml
numeris = { version = "0.5.18", features = ["nalgebra"] }
```

### Cargo Features

| Feature | Default | Description |
|---------|---------|-------------|
| `omm-xml` | yes | XML OMM deserialization via `quick-xml` |
| `download` | yes | Data-file downloader (`update_datafiles`) via `ureq` |
| `chrono` | no | `TimeLike` impl for `chrono::DateTime` |

## Testing and Validation

The library is validated against:

- **Vallado** test cases for SGP4, coordinate transforms, and Keplerian elements
- **JPL** test vectors for DE440/441 ephemeris interpolation (10,000+ cases)
- **NASA GMAT** reference trajectories for the high-precision propagator (see below)
- **ICGEM** reference values for gravity field calculations
- **GPS SP3** precise ephemerides for multi-day numerical propagation

The Rust and Python test suites run in CI on Linux, macOS and Windows.

### GMAT comparison

The numerical propagator is regression-tested against 25 reference trajectories from NASA's General Mission Analysis Tool (GMAT R2026A), checked in under `tests/gmat/`: seven-day gravity / third-body / tides / relativity cases from LEO to cislunar distance, and three-day drag cases. With matched force models the two agree to 2–13 cm over 7 days (LEO to GEO), and with drag to 1–2 × 10⁻⁴ of the drag-induced displacement. Details and tolerances: the [GMAT validation page](https://satkit.dev/guide/gmat_validation/) and `tests/gmat/README.md`.

To run the tests locally (data and test-vector downloads, environment variables), see [CONTRIBUTING.md](CONTRIBUTING.md#running-tests).

## Documentation

- **Rust**: [docs.rs/satkit](https://docs.rs/satkit/)
- **Python**: [satkit.dev](https://satkit.dev/) -- tutorials, Jupyter notebooks, and API reference

## References

The primary sources for every model and algorithm — IERS Conventions (2010), Vallado (2013), Montenbruck & Gill (2000), Vallado et al. (2006) for SGP4, Picone et al. (2002) for NRLMSISE-00, Park et al. (2021) for DE440, Verner (2010) and Berry & Healy (2004) for the integrators, Izzo (2015) for Lambert, and the gravity-model reports — are collected with DOIs on the documentation site's [References](https://satkit.dev/guide/references/) page.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

The gravity models and IERS tables compiled into the library are third-party
data (US Government works and IERS tables, all freely redistributable) — see
[THIRDPARTY-DATA.md](THIRDPARTY-DATA.md). The optional ITU_GRACE16 model
(CC BY 4.0) is not part of the library; it is downloaded only when selected.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
