Astrocubes

Orbital trajectory calculator for Earth-Moon transfers

Astrocubes (Astro²s) is a Python library and CLI tool for calculating Earth-Moon orbital trajectories using patched conic approximation. It helps you plan lunar missions, find optimal launch windows, and visualize transfer orbits.

Features

• 🚀 Trajectory Calculation: Calculate complete Earth-Moon transfer trajectories
• 🪟 Launch Window Finder: Find optimal launch times with minimal delta-v
• 📊 Visualization: Generate 2D and 3D plots of trajectories and launch windows
• 💻 CLI Interface: Easy-to-use command-line tools
• 📚 Python API: Full library access for custom applications
• ⚡ Modern Stack: Built with Astropy, Scipy, and Matplotlib on Python 3.14+

Requirements

Input Parameters

• Launch Configuration:
  • Current orbital trajectory (altitude, inclination) OR
  • Launch site coordinates (latitude, longitude, altitude)
• Target:
  • Lunar trajectory OR landing site coordinates
• Mission Parameters:
  • Time of launch
  • Spacecraft mass

Output

• Liftoff trajectory (if launching from surface):
  • Launch azimuth
  • Parking orbit parameters
  • Delta-v to orbit
• Transfer trajectory:
  • Position and velocity data points
  • Sphere of influence transition time
• Mission metrics:
  • Total delta-v budget (TLI + LOI)
  • Trip time
  • Fuel mass requirements

Installation

Using uv (recommended):

uv pip install astrocubes

Or with pip:

pip install astrocubes

Quick Start

CLI Usage

Calculate a trajectory from LEO:

astrocubes calculate \
  --orbit-alt 300 \
  --launch-time "2026-01-15T12:00:00" \
  --mass 30000 \
  --plot trajectory.png

Find launch windows:

astrocubes find-windows \
  --orbit-alt 300 \
  --start-time "2026-01-01T00:00:00" \
  --end-time "2026-01-31T00:00:00" \
  --mass 30000 \
  --max-windows 10 \
  --plot windows.png

Launch from surface (e.g., Cape Canaveral):

astrocubes calculate \
  --launch-lat 28.5 \
  --launch-lon -80.5 \
  --launch-alt 0.0 \
  --lunar-lat 0.67 \
  --lunar-lon 23.47 \
  --launch-time "2026-07-16T13:32:00" \
  --mass 45000 \
  --isp 450

Python API Usage

from astropy.time import Time
from astrocubes import calculate_transfer, find_launch_windows, plot_trajectory

# Calculate a single trajectory
result = calculate_transfer(
    orbit_altitude=300.0,  # km
    orbit_inclination=28.5,  # degrees
    lunar_lat=0.0,
    lunar_lon=0.0,
    launch_time=Time("2026-01-15T12:00:00", scale="utc"),
    mass=30000.0,  # kg (dry mass)
    specific_impulse=450.0,  # seconds
)

print(f"Delta-v required: {result.delta_v_total:.2f} km/s")
print(f"Trip time: {result.trip_time:.2f} days")
print(f"Fuel needed: {result.fuel_mass:,.0f} kg")

# Visualize the trajectory
fig = plot_trajectory(result.transfer_trajectory, projection="3d")
fig.savefig("trajectory.png")

# Find optimal launch windows
windows = find_launch_windows(
    orbit_altitude=300.0,
    lunar_lat=0.0,
    lunar_lon=0.0,
    start_time=Time("2026-01-01T00:00:00", scale="utc"),
    end_time=Time("2026-01-31T00:00:00", scale="utc"),
    mass=30000.0,
    max_windows=10,
)

for i, window in enumerate(windows[:3], 1):
    print(f"\nWindow {i}:")
    print(f"  Launch: {window.launch_time.iso}")
    print(f"  Delta-V: {window.delta_v:.2f} km/s")
    print(f"  Trip Time: {window.trip_time:.2f} days")

Examples

Apollo 11-style Mission

from astropy.time import Time
from astrocubes import calculate_transfer

# Apollo 11 launch parameters
result = calculate_transfer(
    launch_lat=28.5,  # Cape Canaveral
    launch_lon=-80.5,
    launch_alt=0.0,
    lunar_lat=0.67,  # Mare Tranquillitatis
    lunar_lon=23.47,
    launch_time=Time("1969-07-16T13:32:00", scale="utc"),
    mass=45000.0,  # Combined CSM+LM mass
)

print(f"Liftoff delta-v: {result.liftoff.delta_v:.2f} km/s")
print(f"TLI delta-v: {result.delta_v_tli:.2f} km/s")
print(f"Total mission delta-v: {result.delta_v_total:.2f} km/s")

Finding Minimum Delta-v Window

from astropy.time import Time
from astrocubes import find_launch_windows

windows = find_launch_windows(
    orbit_altitude=300.0,
    orbit_inclination=28.5,
    lunar_lat=0.0,
    lunar_lon=0.0,
    start_time=Time("2026-01-01T00:00:00", scale="utc"),
    end_time=Time("2026-03-01T00:00:00", scale="utc"),
    mass=30000.0,
    time_step_hours=1.0,  # Fine granularity
    max_windows=5,
    max_delta_v=15.0,  # Constraint
)

best = windows[0]
print(f"Best launch time: {best.launch_time.iso}")
print(f"Minimum delta-v: {best.delta_v:.2f} km/s")

Technical Details

Patched Conic Approximation

Astrocubes uses the patched conic approximation method for trajectory calculation:

1. Earth Phase: Two-body dynamics in Earth's gravity well
2. Transfer Phase: Hohmann-like transfer orbit
3. Lunar Phase: Two-body dynamics in Moon's gravity well

The sphere of influence (SOI) boundaries determine transitions between phases:

• Earth SOI: ~924,000 km
• Moon SOI: ~66,000 km

Physics Models

• Orbital mechanics: Kepler's laws and vis-viva equation
• Delta-v calculation: Tsiolkovsky rocket equation
• Liftoff: Simplified gravity turn model with realistic losses

Accuracy

This implementation provides preliminary trajectory estimates suitable for:

• Mission planning and feasibility studies
• Educational purposes
• Trade studies and delta-v budgeting

For operational missions, use high-fidelity tools that include:

• Full n-body dynamics
• Non-spherical gravity fields
• Solar radiation pressure
• Third-body perturbations

Development

Setup

# Clone repository
git clone https://github.com/astrorobotics/astrocubes.git
cd astrocubes

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=astrocubes --cov-report=html

Project Structure

astrocubes/
├── src/astrocubes/
│   ├── __init__.py
│   ├── trajectory.py       # Core trajectory calculations
│   ├── launch_window.py    # Launch window optimization
│   ├── visualization.py    # Plotting functions
│   └── cli.py             # Command-line interface
├── tests/
│   ├── test_trajectory.py
│   ├── test_launch_window.py
│   ├── test_visualization.py
│   └── test_integration.py
├── pyproject.toml
└── README.md

Running Tests

# All tests
uv run pytest

# Specific test file
uv run pytest tests/test_trajectory.py

# With verbose output
uv run pytest -v

# With coverage
uv run pytest --cov=astrocubes

API Reference

Core Functions

calculate_transfer(...)

Calculate a complete Earth-Moon transfer trajectory.

Parameters:

• launch_lat, launch_lon, launch_alt: Surface launch site (optional)
• orbit_altitude, orbit_inclination: Starting orbit (optional)
• lunar_lat, lunar_lon: Target lunar coordinates
• launch_time: Launch time (astropy Time object)
• mass: Spacecraft dry mass (kg)
• specific_impulse: Engine Isp (seconds, default: 450)

Returns: TransferResult with trajectory, delta-v, fuel mass, etc.

find_launch_windows(...)

Find optimal launch windows in a time range.

Parameters:

• All parameters from calculate_transfer
• start_time, end_time: Search window
• time_step_hours: Search granularity (default: 6.0)
• max_windows: Maximum results to return (default: 10)
• max_delta_v: Maximum acceptable delta-v constraint (optional)

Returns: List of LaunchWindow objects sorted by delta-v

plot_trajectory(trajectory, ...)

Create a visualization of a transfer trajectory.

Parameters:

• trajectory: TransferTrajectory object
• projection: "2d" or "3d" (default: "2d")
• save_path: Optional path to save figure
• show_bodies: Show Earth and Moon (default: True)

Returns: matplotlib Figure object

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with Astropy for astronomical calculations
• Uses Scipy for optimization
• Visualization powered by Matplotlib
• CLI built with Click

Citation

If you use Astrocubes in your research, please cite:

@software{astrocubes2026,
  title = {Astrocubes: Earth-Moon Orbital Trajectory Calculator},
  year = {2026},
  url = {https://github.com/astrorobotics/astrocubes}
}