orbitalgym 0.1.0

OrbitalGym — JAX-native decision-making for orbital scenarios

OrbitalGym is a JAX-native framework for two-side decision-making in orbital scenarios. The goal is to provide a high-performance research and education framework for orbital decision-making. It is built on top of JAX and astrojax for differentiable dynamics, and is intended as a starting point for further development and research.

OrbitalGym models any two-side decision making problem where two sides compete to complete an objective. Five scenarios ship in the box: Lady-Bandit-Guard, Pursuit-Evasion, Get-Off-My-Lawn, Sun-Blocking, and Observation-Blocking.

The same core drives single-agent (Gymnasium-shaped), multi-agent (PettingZoo-shaped), and POMDP-shaped views of the same underlying game to enable integration with the rich ecosystem of tools built around those interfaces. The core is also designed to be easily extended with new scenarios, new dynamics, and new interfaces.

Install

pip install orbitalgym
# or
uv add orbitalgym

If you want JAX accelerated on GPU or Apple Silicon, install the matching extra:

# NVIDIA CUDA 12
pip install orbitalgym[cuda12]
# NVIDIA CUDA 13
pip install orbitalgym[cuda13]
# Apple Silicon Metal (via jax-mps)
pip install orbitalgym[mps]

Quickstart

This project uses just as a command runner and uv for Python package management.

# Install just (macOS)
brew install just

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

# Clone and install everything (dev deps + adapter extras)
just install

See the Getting started guide to walk from a fresh checkout to a rendered trajectory plot.

Papers

papers/2027_ieee_aeroconf holds the experiments, figures, and quoted statistics of "Where Planning Changes the Outcome of Orbital Games" (IEEE Aerospace Conference, 2027), one runnable script per experiment.

Development

Every recipe has an equivalent raw command you can run directly.

License

The code in this repository is licensed under the MIT License. See LICENSE.md for details.