Metadata-Version: 2.4
Name: stable-envs
Version: 0.1.0
Summary: Fast and Reproducible Environments with Controllable Variations
Author: Randall Balestriero, Sami BuGhanem
License-Expression: MIT AND LGPL-2.1-or-later
Project-URL: Homepage, https://github.com/galilai-group/stable-envs
Project-URL: Documentation, https://galilai-group.github.io/stable-envs/
Project-URL: Issues, https://github.com/galilai-group/stable-envs/issues
Project-URL: Source, https://github.com/galilai-group/stable-envs
Keywords: reinforcement-learning,environments,rendering,pytorch,gpu
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/APACHE-2.0.txt
License-File: licenses/Bullet-zlib.txt
License-File: licenses/Gymnasium-MIT.txt
License-File: licenses/Gymnasium-Robotics-MIT.txt
License-File: licenses/LGPL-2.1.txt
License-File: licenses/Munk2D-MIT.txt
License-File: licenses/NumPy-BSD-3-Clause.txt
License-File: licenses/NumPy-random-NCSA-BSD-3-Clause.txt
License-File: licenses/OGBench-MIT.txt
License-File: licenses/PyFlyt-MIT.txt
Requires-Dist: gymnasium>=1.0
Requires-Dist: jax>=0.4.35
Requires-Dist: loguru>=0.7
Requires-Dist: numpy>=1.24
Requires-Dist: tensordict>=0.6
Requires-Dist: torch>=2.2
Provides-Extra: classic
Requires-Dist: pygame>=2.5; extra == "classic"
Requires-Dist: numba>=0.60; extra == "classic"
Provides-Extra: pusht
Requires-Dist: pygame>=2.5; extra == "pusht"
Requires-Dist: pymunk==7.2.0; extra == "pusht"
Requires-Dist: opencv-python-headless; extra == "pusht"
Requires-Dist: shapely; extra == "pusht"
Requires-Dist: numba>=0.60; extra == "pusht"
Provides-Extra: pusht-gpu
Requires-Dist: pygame>=2.5; extra == "pusht-gpu"
Requires-Dist: pymunk==7.2.0; extra == "pusht-gpu"
Requires-Dist: opencv-python-headless; extra == "pusht-gpu"
Requires-Dist: shapely; extra == "pusht-gpu"
Requires-Dist: numba>=0.60; extra == "pusht-gpu"
Requires-Dist: jax[cuda12]>=0.4.35; sys_platform == "linux" and extra == "pusht-gpu"
Provides-Extra: pusht-reference
Requires-Dist: gym-pusht; extra == "pusht-reference"
Provides-Extra: navigation
Requires-Dist: matplotlib>=3.10; extra == "navigation"
Requires-Dist: numba>=0.60; extra == "navigation"
Provides-Extra: navigation-gpu
Requires-Dist: jax[cuda12]>=0.4.35; sys_platform == "linux" and extra == "navigation-gpu"
Provides-Extra: ogbench
Requires-Dist: mujoco<3.18,>=3.11; extra == "ogbench"
Requires-Dist: ogbench<1.3,>=1.2.1; extra == "ogbench"
Requires-Dist: numba>=0.60; extra == "ogbench"
Provides-Extra: ogbench-manipulation
Requires-Dist: ogbench==1.2.1; extra == "ogbench-manipulation"
Requires-Dist: mujoco==3.17.0; extra == "ogbench-manipulation"
Requires-Dist: dm-control>=1.0.50; extra == "ogbench-manipulation"
Requires-Dist: numba>=0.60; extra == "ogbench-manipulation"
Provides-Extra: ogbench-manipulation-gpu
Requires-Dist: ogbench==1.2.1; extra == "ogbench-manipulation-gpu"
Requires-Dist: mujoco==3.17.0; extra == "ogbench-manipulation-gpu"
Requires-Dist: dm-control>=1.0.50; extra == "ogbench-manipulation-gpu"
Requires-Dist: numba>=0.60; extra == "ogbench-manipulation-gpu"
Requires-Dist: mujoco-warp==3.17.0; extra == "ogbench-manipulation-gpu"
Requires-Dist: warp-lang==1.17.0; extra == "ogbench-manipulation-gpu"
Provides-Extra: dmcontrol
Requires-Dist: dm-control>=1.0.50; extra == "dmcontrol"
Requires-Dist: mujoco<3.18,>=3.17; extra == "dmcontrol"
Requires-Dist: numba>=0.60; extra == "dmcontrol"
Provides-Extra: dmcontrol-gpu
Requires-Dist: dm-control>=1.0.50; extra == "dmcontrol-gpu"
Requires-Dist: mujoco<3.18,>=3.17; extra == "dmcontrol-gpu"
Requires-Dist: mujoco-warp<3.18,>=3.17; extra == "dmcontrol-gpu"
Requires-Dist: warp-lang>=1.16; extra == "dmcontrol-gpu"
Requires-Dist: mujoco-mjx<3.18,>=3.17; extra == "dmcontrol-gpu"
Requires-Dist: jax[cuda12]>=0.4.35; sys_platform == "linux" and extra == "dmcontrol-gpu"
Provides-Extra: robotics
Requires-Dist: gymnasium-robotics<1.5,>=1.4.2; extra == "robotics"
Requires-Dist: mujoco<3.12,>=3.11; extra == "robotics"
Requires-Dist: opencv-python-headless; extra == "robotics"
Requires-Dist: numba>=0.60; extra == "robotics"
Provides-Extra: mjwarp
Requires-Dist: mujoco<3.18,>=3.11; extra == "mjwarp"
Requires-Dist: mujoco-warp<3.18,>=3.11; extra == "mjwarp"
Requires-Dist: warp-lang>=1.16; extra == "mjwarp"
Provides-Extra: mshuman
Requires-Dist: filelock>=3.0; extra == "mshuman"
Requires-Dist: mujoco<3.18,>=3.17; extra == "mshuman"
Requires-Dist: mujoco-warp<3.18,>=3.17; extra == "mshuman"
Requires-Dist: warp-lang>=1.16; extra == "mshuman"
Provides-Extra: rocket
Requires-Dist: pillow; extra == "rocket"
Requires-Dist: scipy; extra == "rocket"
Requires-Dist: PyFlyt==0.29.0; extra == "rocket"
Requires-Dist: pybullet==3.2.7; extra == "rocket"
Requires-Dist: numba>=0.60; extra == "rocket"
Provides-Extra: craftax
Requires-Dist: craftax>=1.6.1; extra == "craftax"
Requires-Dist: jax>=0.4.30; extra == "craftax"
Provides-Extra: roadster
Requires-Dist: mujoco<3.18,>=3.17; extra == "roadster"
Requires-Dist: pillow; extra == "roadster"
Provides-Extra: roadster-gpu
Requires-Dist: mujoco<3.18,>=3.17; extra == "roadster-gpu"
Requires-Dist: mujoco-warp<3.18,>=3.17; extra == "roadster-gpu"
Requires-Dist: warp-lang>=1.16; extra == "roadster-gpu"
Requires-Dist: pillow; extra == "roadster-gpu"
Provides-Extra: craftax-gpu
Requires-Dist: craftax>=1.6.1; extra == "craftax-gpu"
Requires-Dist: jax[cuda12]>=0.4.30; sys_platform == "linux" and extra == "craftax-gpu"
Provides-Extra: miniworld
Requires-Dist: miniworld>=2.1; extra == "miniworld"
Requires-Dist: pyglet<2,>=1.5.27; extra == "miniworld"
Requires-Dist: numba>=0.60; extra == "miniworld"
Provides-Extra: hf
Requires-Dist: datasets>=2.14; extra == "hf"
Provides-Extra: examples
Requires-Dist: imageio; extra == "examples"
Requires-Dist: imageio-ffmpeg; extra == "examples"
Requires-Dist: opencv-python-headless; extra == "examples"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.7; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: pygame; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.6; extra == "dev"
Requires-Dist: pyyaml>=6; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: mypy>=1.15; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/galilai-group/stable-envs/main/docs/assets/brand/banner.jpg" alt="stable-envs: frames from ten environment families" width="100%">

<p align="center"><i>Fast and Reproducible Environments with Controllable Variations</i></p>

<p align="center">
  <a href="https://galilai-group.github.io/stable-envs/"><img alt="Docs" src="https://img.shields.io/badge/docs-galilai--group.github.io-black.svg"/></a>
  <a href="https://pypi.org/project/stable-envs/"><img alt="PyPI" src="https://img.shields.io/pypi/v/stable-envs.svg?color=black"/></a>
  <a href="https://github.com/galilai-group/stable-envs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/galilai-group/stable-envs/actions/workflows/ci.yml/badge.svg?branch=main"/></a>
  <a href="https://github.com/galilai-group/stable-envs/blob/main/pyproject.toml"><img alt="Python 3.10 to 3.12" src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-black.svg"/></a>
  <a href="https://github.com/galilai-group/stable-envs/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT%20%2B%20LGPL--2.1-black.svg"/></a>
</p>

<p align="center">
  <a href="#installation"><b>Installation</b></a> ·
  <a href="#quick-start"><b>Quick Start</b></a> ·
  <a href="#environments"><b>Environments</b></a> ·
  <a href="https://galilai-group.github.io/stable-envs/"><b>Documentation</b></a>
</p>

---

stable-envs is a library of batched simulation environments that keep the full simulator state, so you can restore any step exactly and render images from it later, on CPU or GPU.

Store states instead of pixels, replay or branch from any step, and render frames from a stored state as many times as you like. 80 environment classes in 11 families share the same API.

## Installation

```bash
pip install stable-envs                       # or: uv add stable-envs
pip install "stable-envs[pusht]"              # PushT simulation and CPU rendering
pip install "stable-envs[dmcontrol,ogbench]"  # add family extras as needed
stable-envs doctor                            # check what works on this machine
```

Install the `robotics` extra (Fetch) in its own environment, because it needs MuJoCo below 3.12, while `dmcontrol`, `mshuman`, `roadster` and `ogbench-manipulation` need 3.17. [Install](https://galilai-group.github.io/stable-envs/install/) lists every extra and the OpenGL setup.

## Quick Start

```python
import torch
import stable_envs as snv

with snv.CartPole(num_envs=8, device="cpu") as env:
    env.reset(seed=0)
    actions = torch.randint(0, 2, (8, 10, 1))  # (B, T, A): ten steps for each environment
    out = env.step(actions, frames=None)  # step without rendering
    print(out["states"].batch_size)  # torch.Size([8, 10])
    frames = env.render(out["states"][:, 4])  # render the state after five steps
    print(frames.shape, frames.dtype)  # torch.Size([8, 400, 600, 3]) torch.uint8
```

`step` returns the state after every step, and `render` draws a batch of frames from any of them.

The [Quickstart](https://galilai-group.github.io/stable-envs/quickstart/) covers state, frames, steps, save and restore, and variation. For policies, datasets and training, see [stable-worldmodel](https://github.com/galilai-group/stable-worldmodel).

## Environments

| Family | Classes | Extra |
|---|---:|---|
| [`classic_control`](https://galilai-group.github.io/stable-envs/environments/classic-control/) | 5 | none (`classic` for MountainCar, MountainCarContinuous and Pendulum) |
| [`craftax`](https://galilai-group.github.io/stable-envs/environments/craftax/) | 4 | `craftax` |
| [`dmcontrol`](https://galilai-group.github.io/stable-envs/environments/dmcontrol/) | 17 | `dmcontrol` |
| [`fetch`](https://galilai-group.github.io/stable-envs/environments/fetch/) | 12 | `robotics` |
| [`miniworld`](https://galilai-group.github.io/stable-envs/environments/miniworld/) | 1 | `miniworld` |
| [`mshuman`](https://galilai-group.github.io/stable-envs/environments/mshuman/) | 1 | `mshuman` |
| [`navigation`](https://galilai-group.github.io/stable-envs/environments/navigation/) | 5 | none (`navigation` for SimplePointMaze) |
| [`ogbench`](https://galilai-group.github.io/stable-envs/environments/ogbench/) | 27 | `ogbench`, or `ogbench-manipulation` for Cube and Scene |
| [`pusht`](https://galilai-group.github.io/stable-envs/environments/pusht/) | 2 | `pusht` |
| [`pyflyt`](https://galilai-group.github.io/stable-envs/environments/pyflyt/) | 1 | `rocket` |
| [`roadster`](https://galilai-group.github.io/stable-envs/environments/roadster/) | 5 | `roadster` |
| **Total** | **80** | |

## Examples

- [`examples/`](https://github.com/galilai-group/stable-envs/blob/main/examples/README.md): short scripts for rendering, batching, action sequences and domain randomization.
- [`examples/lewm/`](https://github.com/galilai-group/stable-envs/blob/main/examples/lewm/README.md): train and evaluate stable-worldmodel's LeWM world model on PushT, with frames that `env.render` draws on the training device from stored states.

## Documentation

The full documentation is at [galilai-group.github.io/stable-envs](https://galilai-group.github.io/stable-envs/).

## Questions

Open an [issue](https://github.com/galilai-group/stable-envs/issues) on GitHub.

## License

MIT, except the three PushT rasterizer files that port pygame's drawing routines, which are LGPL-2.1-or-later. See [LICENSE](https://github.com/galilai-group/stable-envs/blob/main/LICENSE) and [THIRD_PARTY_NOTICES.md](https://github.com/galilai-group/stable-envs/blob/main/THIRD_PARTY_NOTICES.md).
