Overview¶
stable-envs ships 80 environment classes in 11 families. Each family has a page, and each class on it shows a clip of random actions and, for most classes, a clip of sampled variation, the action, the state keys and the variation leaves.
import stable_envs as snv
print(snv.list_envs(family="classic_control")) # ['Acrobot', 'CartPole', 'MountainCar', 'MountainCarContinuous', 'Pendulum']
print(snv.list_envs(family="ogbench", domain="pointmaze")[:2]) # ['PointMazeGiantNavigate', 'PointMazeGiantStitch']
with (
snv.CartPole(num_envs=8, device="cpu") as cartpole,
snv.TwoRoom(num_envs=8, device="cpu") as tworoom,
):
print(cartpole.action_spec.shape, tworoom.action_spec.shape) # (1,) (2,)
snv.list_envs() lists the classes registered on this interpreter, and the extras you installed decide which ones those are. Missing extras says what the core install registers and runs.
| Family | Classes | Examples |
|---|---|---|
classic_control |
5 | CartPole, Pendulum |
craftax |
4 | CraftaxClassicPixels, CraftaxSymbolic |
dmcontrol |
17 | DMCReacher, DMCCheetahRun (domain="reacher", "cheetah", ...) |
fetch |
12 | FetchReach, FetchPush, ... |
miniworld |
1 | MiniWorldMovingBlockWorld |
mshuman |
1 | MSHumanLocomotion |
navigation |
5 | TwoRoom, Piecewise, SimplePointMaze |
ogbench |
27 | PointMazeLargeNavigate, OGBCube (domain="pointmaze", "cube", ...) |
pusht |
2 | PushT, PushTDiscrete |
pyflyt |
1 | PyFlytRocketLanding |
roadster |
5 | RoadsterTrafficJam, RoadsterCarHop (domain="traffic", "carhop", ...) |
| Total | 80 |
Comparison with the upstream library¶
reference_id names the environment in the upstream library that the tests compare a class with, such as CartPole-v1 or dm_control/reacher-hard. Each class table on a family page has "Renderer on CPU" and "Renderer on CUDA" rows that name the code drawing the frames. PushT on CPU, for example, reproduces the pygame drawing of gym-pusht in Numba and gives the same bytes, and PyFlytRocketLanding on CPU draws with a Numba port of PyFlyt's TinyRenderer. The renderers follow the kind of family: 2D families build a Scene2D and rasterize it, OGBench mazes ray-cast analytic primitives, and MuJoCo families use MuJoCo's OpenGL renderer, MJWarp, the stable-envs MuJoCo rasterizer, or a stable-envs ray caster on CPU.
The tests measure the per-frame mean squared error (MSE) between each class's frames and the frames it declares as its comparison target. They compare it with a recorded value in the frame regression checks.
Classes that declare a fidelity record report it in env.describe()["visual_fidelity"]: the measured MSE as mse_mean, mse_p95 and mse_max on the 0-255 scale, with the measurement setup. env.describe()["visual_note"] says where the frames differ. These classes draw with a different rasterizer from the upstream library:
- Fetch with the default backend: the Fetch Numba rasterizer on CPU and MJWarp on CUDA.
OGBCubeandOGBScenewith the default backend on CPU: the stable-envs MuJoCo rasterizer (backend="numba").- The DM Control body-tracking classes. They declare a fidelity record.
PyFlytRocketLandingon CUDA, which nvdiffrast draws. It declares a fidelity record for these frames.
backend="opengl" draws Fetch, OGBCube and OGBScene with MuJoCo OpenGL, the renderer of the upstream library. On CPU, these frames are bit-exact and repeatable. On CUDA, the NVIDIA OpenGL driver can change a pixel by 1 or 2 levels (of 255) between two draws of the same state, on a few pixels of a few frames in each pass; the comparison renderer shows the same variation. For OGBCube and OGBScene, the OpenGL fidelity record compares two OpenGL instances with the same compiled appearance. It is not a comparison with the default OGBench appearance. At supersample=2 or more, MJWarp is measured against that same stable-envs OpenGL path. See OGBench.
Frame size¶
native_size is the only size that a class draws, or None when the class draws any size. When it is set, it is the size that the upstream library draws, and it is also default_size. The classic control, navigation and Craftax classes set it, because their upstream libraries draw each primitive in fixed pixels. Another size raises ValueError. snv.info(name)["native_size"] reads it without building the class.
Page data
The family pages read their tables from docs/environments/_data/<Class>.json and their clips from docs/assets/media/envs/<Class>/. scripts/gen_env_docs.py writes both. To refresh one class, run the script in an interpreter that registers it:
python scripts/gen_env_docs.py PushT --meta --devices --media
--metawrites the metadata of a one-environment batch built on CPU.--devicesbuilds the class on each available device and records the result.--mediarenders the two clips on the default device of the class. It needsimageio-ffmpegor anffmpegexecutable.
tests/unit/test_env_docs_snapshot.py checks each snapshot against the live class.