Metadata-Version: 2.5
Name: orbitalgym
Version: 0.1.0
Summary: JAX-native framework for guard/bandit decision-making in orbital scenarios
Project-URL: Documentation, https://sisl.github.io/OrbitalGym/
Project-URL: Repository, https://github.com/sisl/OrbitalGym
Project-URL: Issues, https://github.com/sisl/OrbitalGym/issues
Author: Duncan Eddy
License-Expression: MIT
License-File: LICENSE.md
Requires-Python: >=3.12
Requires-Dist: astrojax>=0.7.2
Requires-Dist: brahe>=1.5.0
Requires-Dist: chex>=0.1.91
Requires-Dist: flax>=0.12.6
Requires-Dist: gymnasium>=1.2
Requires-Dist: gymnax>=0.0.9
Requires-Dist: h5py>=3.16
Requires-Dist: jax>=0.9.2
Requires-Dist: jaxlib>=0.9.2
Requires-Dist: matplotlib>=3.10
Requires-Dist: mctx>=0.0.6
Requires-Dist: pettingzoo>=1.26
Requires-Dist: scienceplots>=2.2
Requires-Dist: scipy>=1.16
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]>=0.9.2; extra == 'cuda12'
Provides-Extra: cuda13
Requires-Dist: jax[cuda13]>=0.9.2; extra == 'cuda13'
Provides-Extra: dev
Requires-Dist: ipykernel>=7.2; extra == 'dev'
Requires-Dist: ipympl>=0.9; extra == 'dev'
Requires-Dist: ipywidgets>=8.1; extra == 'dev'
Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'dev'
Requires-Dist: nbconvert>=7.17; extra == 'dev'
Requires-Dist: pre-commit>=4.6; extra == 'dev'
Requires-Dist: pyrefly>=0.61; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: zensical>=0.0.39; extra == 'dev'
Provides-Extra: extras
Requires-Dist: cvxpy>=1.8.2; extra == 'extras'
Requires-Dist: highspy>=1.14.0; extra == 'extras'
Provides-Extra: ground-stations
Provides-Extra: mps
Requires-Dist: jax-mps>=0.9.13; extra == 'mps'
Description-Content-Type: text/markdown

<p align="center">
    <em>OrbitalGym — JAX-native decision-making for orbital scenarios</em>
</p>

<p align="center">
  <!-- <a href="https://github.com/sisl/OrbitalGym/actions/workflows/ci.yml"><img src="https://github.com/sisl/OrbitalGym/actions/workflows/ci.yml/badge.svg" alt="CI"></a> -->
  <a href="https://sisl.github.io/OrbitalGym/"><img src="https://img.shields.io/badge/docs-latest-blue" alt="Documentation"></a>
</p>

---

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](https://github.com/duncaneddy/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

```bash
pip install orbitalgym
# or
uv add orbitalgym
```

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

```bash
# 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`](https://github.com/casey/just) as a command runner and [`uv`](https://docs.astral.sh/uv/) for Python package management.

```bash
# 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](https://sisl.github.io/OrbitalGym/getting-started/) to walk from a fresh checkout to a rendered trajectory plot.

## Papers

[`papers/2027_ieee_aeroconf`](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.

| Task | `just` recipe | Raw command |
|------|---------------|-------------|
| Install dev deps | `just install` | `uv sync --dev` |
| Run tests | `just test` | `uv run pytest tests/ -v` |
| Test with coverage | `just test-cov` | `uv run pytest --cov=orbitalgym --cov-report=term-missing` |
| Format code | `just fmt` | `uv run ruff format` |
| Lint (auto-fix) | `just lint` | `uv run ruff check --fix` |
| Type check | `just typecheck` | `uv run pyrefly check` |
| All quality checks | `just check` | Runs fmt + lint + typecheck |
| Build docs | `just docs-build` | `uv run zensical build --clean` |
| Serve docs | `just docs-serve` | `uv run zensical serve --clean` |

## License

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