astrora_core 0.1.1

Astrora - Rust-backed astrodynamics library - core computational components
Documentation

Astrora - Rust-Backed Astrodynamics Library

Python 3.8+ Rust 1.90+ License: MIT

A modern, high-performance orbital mechanics library combining Python's ease of use with Rust's computational performance.

Overview

Astrora is a ground-up modernization of astrodynamics computing, delivering 10-100x performance improvements over pure Python implementations while maintaining an intuitive Python API.

Background

The original poliastro library was archived on October 14, 2023. While active forks like hapsira continue development, Astrora represents a new approach that:

  • Leverages the mature Rust astrodynamics ecosystem (2024-2025)
  • Implements cutting-edge Python-Rust integration patterns
  • Provides 10-100x performance improvements over pure Python
  • Maintains API compatibility with poliastro where practical

Features

Core Capabilities

  • High-performance orbit propagators

    • Keplerian propagation (analytical)
    • Cowell's method with perturbations
    • Numerical integrators (RK4, DOPRI5, DOP853)
    • 10-50x faster than pure Python

  • Perturbation models

    • Earth oblateness (J2, J3, J4)
    • Atmospheric drag (exponential model)
    • Third-body effects (Sun, Moon)
    • Solar radiation pressure

  • Coordinate transformations

    • GCRS ↔ ITRS ↔ TEME
    • Batch transformations with 20-80x speedup
    • Full time-dependent rotations

  • Lambert solvers

    • Universal variable formulation
    • Izzo's algorithm
    • Batch processing with 50-100x speedup

  • Orbital mechanics

    • Classical orbital elements ↔ Cartesian state vectors
    • Anomaly conversions (true, eccentric, mean)
    • Orbit classification and analysis

  • Maneuvers

    • Hohmann transfers
    • Bi-elliptic transfers
    • Impulsive burns (Δv calculations)

  • Visualization

    • 2D/3D static plots
    • Interactive 3D visualizations (Plotly)
    • Ground track plotting
    • Porkchop plots for transfer analysis
    • Orbit animations (GIF, MP4, HTML)

  • Satellite operations

    • TLE/OMM parsing and propagation
    • Lifetime estimation
    • Ground station visibility
    • Eclipse predictions

Installation

Quick Start (Recommended)

Install using uv for the fastest experience:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Astrora
uv pip install astrora

Traditional Installation

pip install astrora

From Source

For development or latest features:

git clone https://github.com/cachemcclure/astrora.git
cd astrora
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"
maturin develop --release

Complete Installation Guide - Detailed instructions for all platforms and use cases

Quick Start

import numpy as np
from astrora import Orbit, bodies
from astrora._core import hohmann_transfer

# Create an orbit from state vectors
orbit = Orbit.from_vectors(
    bodies.Earth,
    r=np.array([7000e3, 0.0, 0.0]),  # Position (m)
    v=np.array([0.0, 7546.0, 0.0])   # Velocity (m/s)
)

print(f"Semi-major axis: {orbit.a/1e3:.1f} km")
print(f"Period: {orbit.period/3600:.2f} hours")
print(f"Eccentricity: {orbit.ecc:.6f}")

# Propagate the orbit forward in time
orbit_after_1hr = orbit.propagate(3600.0)  # 1 hour later
print(f"True anomaly after 1 hour: {orbit_after_1hr.nu:.2f} rad")

# Calculate a Hohmann transfer from LEO to GEO
result = hohmann_transfer(7000e3, 42164e3, bodies.Earth.mu)
print(f"Total Δv: {result['delta_v_total']/1000:.2f} km/s")
print(f"Transfer time: {result['transfer_time']/3600:.2f} hours")

# Visualize (requires matplotlib)
from astrora.plotting import plot_orbit
plot_orbit(orbit)

Performance

Real-world benchmarks on Apple M2 Pro:

  • Numerical propagation: 10-50x faster than pure Python
  • Lambert problem (batch): 50-100x faster with Rayon parallelization
  • Coordinate transformations (batch): 20-80x faster with SIMD
  • Overall workflows: 5-10x typical improvement

Technical Stack

  • Python 3.8+: High-level API and user interface
  • Rust 1.90+: Performance-critical computations
  • PyO3 0.22: Seamless Rust-Python bindings with stable ABI
  • maturin: Build system for Rust-backed Python packages
  • uv: Ultra-fast package management (10-100x faster than pip)

Scientific Libraries:

  • nalgebra: Linear algebra operations
  • hifitime: Nanosecond-precision time handling
  • rayon: Data parallelism for batch operations
  • astropy: Astronomical calculations and units
  • numpy: Array operations

Documentation

Examples

Check the examples/ directory for comprehensive usage examples:

  • Basic orbit creation and propagation
  • Coordinate transformations
  • Lambert problem solving
  • Porkchop plots for mission planning
  • Ground track visualization
  • Orbit animations
  • Satellite operations

Contributing

Contributions are welcome! This project is in active development.

Development Setup

# Clone the repository
git clone https://github.com/cachemcclure/astrora.git
cd astrora

# Set up development environment
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev,docs,test]"

# Build Rust extension
maturin develop --release

# Run tests
pytest tests/ -v

# Check coverage
pytest --cov=astrora --cov-report=html

Code Quality

We maintain high code quality standards:

  • Rust: All public APIs documented, >90% test coverage target
  • Python: NumPy-style docstrings, >85% test coverage target
  • Testing: 636+ tests (Rust + Python), comprehensive integration tests
  • Benchmarking: Continuous performance tracking via GitHub Actions
  • Linting: rustfmt, clippy, black, ruff
  • Type checking: mypy for Python

Areas for Contribution

  • Additional perturbation models (Harris-Priester atmosphere, NRLMSISE-00)
  • More Lambert solver algorithms
  • GPU acceleration for batch operations
  • Advanced maneuver optimization
  • Documentation and tutorials
  • Performance improvements

Roadmap

  • PyPI release with pre-built wheels (Linux, macOS, Windows)
  • Complete user guide and tutorials
  • Jupyter notebook examples
  • Advanced gravity models (EGM2008)
  • Constellation design tools
  • Low-thrust trajectory optimization
  • Integration with mission analysis tools

Project Status

Current Version: 0.1.0 (Alpha)

Test Status:

  • 636+ tests passing (473 Rust, 163+ Python)
  • 73.96% overall Rust coverage (~87% excluding PyO3 bindings)
  • Comprehensive benchmark suite
  • Continuous integration via GitHub Actions

Phase Completion:

  • Phase 1-8: Core functionality (propagators, coordinates, plotting)
  • Phase 9-10: Advanced features (SIMD optimization, satellite operations)
  • Phase 11: Documentation (in progress)
  • Phase 12: Testing and quality assurance (14/17 complete)

Performance Benchmarks

Measured on Apple M2 Pro (10-core, 16GB RAM):

Operation Astrora (Rust) Pure Python Speedup
RK4 propagation (1000 steps) 5.0 μs 12.6 μs 2.5x
Lambert solver (single) 8.2 μs 45 μs 5.5x
Lambert batch (1000) 2.1 ms 45 ms 21x
Coordinate transform (single) 1.8 μs 8.5 μs 4.7x
Coordinate batch (1000) 1.2 ms 8.5 ms 7.1x
Cross product 2.75 μs 75.5 μs 27.5x

Note: Actual speedups depend on CPU, problem size, and operation type. Batch operations see higher speedups due to Rayon parallelization.

License

MIT License - See LICENSE for details

Citation

If you use Astrora in your research, please cite:

@software{astrora2025,
  author = {McClure, Cache},
  title = {Astrora: A Rust-Backed Astrodynamics Library for Python},
  year = {2025},
  url = {https://github.com/cachemcclure/astrora},
  version = {0.1.0}
}

Acknowledgments

Support

Made by the Astrora team. Powered by Rust and Python.