Navigation¶
A point agent moves through a flat arena to a target, past walls, doors or motion-bias zones depending on the task. The five classes reimplement the 2D navigation tasks of stable-worldmodel in Torch, Numba and JAX, and the tests check that resets, state and step outputs equal those of a pinned stable-worldmodel.
import stable_envs as snv
with snv.TwoRoom(num_envs=8, device="cpu") as env:
state = env.reset(seed=0)
print(env.render().shape) # torch.Size([8, 224, 224, 3])
Install¶
TwoRoom, TwoRoomTarget, Piecewise and PiecewiseZones run with the core install. SimplePointMaze needs the navigation extra for Matplotlib, and so does Piecewise's rendering.render_bias_field leaf. The extra also installs Numba for the CPU kernels, and TwoRoom on CUDA needs the navigation-gpu extra. When a JAX TwoRoom is built, stable-envs turns off JAX's GPU memory preallocation, so that Torch keeps its GPU memory. See JAX GPU memory.
Task¶
The agent moves to a target. TwoRoom, Piecewise and SimplePointMaze terminate the episode when it reaches the target, and TwoRoomTarget and PiecewiseZones return only the state, with no reward or episode flags. Each class in Classes gives its arena and its success condition.
State¶
The state is folded. The fields of one dtype are in one leaf:
| Class | Leaf | Fields |
|---|---|---|
| TwoRoom, TwoRoomTarget, Piecewise | navigation/float32 |
agent/position, target/position |
| PiecewiseZones | navigation/float32 |
agent/position |
| SimplePointMaze | simple_point_maze/float64 |
agent/position |
simple_point_maze/float32 |
goal/position, task/cached_goal_agent_position |
|
simple_point_maze/bool |
task/state_is_float64 |
Read a field by name:
with snv.TwoRoom(num_envs=8, device="cpu") as env:
state = env.reset(seed=0)
print(snv.get_field(state, "target.position").shape) # torch.Size([8, 2])
Simulation¶
TwoRoomTarget, Piecewise and PiecewiseZones take simulation_backend. "auto" (the default) steps CPU batches with the Numba kernel when Numba imports and uses Torch otherwise, and "torch" and "numba" select one implementation. Both give the same state and task outputs.
TwoRoom backends¶
TwoRoom runs on CPU or CUDA and takes and returns Torch tensors. On CPU, one call of a Numba kernel moves every agent in the batch and computes the state, the observation, the reward and the termination flags. On CUDA, JAX steps the batch on the GPU. JAX comes with the core install, but CUDA also needs stable-envs[navigation-gpu]:
# needs the navigation-gpu extra; CUDA only
import torch
import stable_envs as snv
with snv.TwoRoom(num_envs=1024, device="cuda") as env:
env.reset(seed=0)
actions = torch.zeros(1024, 2, device="cuda")
result = env.step(actions, states=None, frames=None)
The first step compiles the physics kernel and, on supported CUDA installs, the shared Torch task outputs. Run a few warm-up steps before you measure throughput. A new batch shape can compile again. Torch and JAX exchange tensors through DLPack on the selected device, without copying them to CPU while stepping. If the JAX CUDA runtime is missing, the error names the extra to install.
simulation_backend="auto" uses the Numba kernel on CPU when Numba imports, and JAX without Numba. On CUDA, a batch of large_backend_min_envs or more environments steps in JAX, and a smaller batch steps in Numba (Torch without Numba). When the setting is not set, the switch point comes from the tuning cache that stable-envs tune writes, else from the value the class ships, so without tuning the same batch size selects the same backend on every machine (Physics backends). On CUDA, TwoRoom and TwoRoomTarget draw a batch of fewer than large_renderer_min_rows frames with the Numba compositor on the CPU, and move the frames to CUDA in one copy (Renderers).
The choice is fixed at construction. Set simulation_backend="torch", "jax" or "numba" to choose yourself at any batch size. Torch and JAX use the requested device. On CUDA, TwoRoom's Numba kernel steps a host copy of the batch rows that it keeps between steps: each step copies the actions to the host, then moves the new rows, the state and the outputs to the device in one copy. A reset, restore or other change of the rows on the device refreshes the host copy. TwoRoomTarget, Piecewise and PiecewiseZones run Numba on CPU only. env.simulation_backend reports the selected implementation, and all three give the same state and task outputs.
Rendering¶
TwoRoom, TwoRoomTarget, Piecewise and PiecewiseZones draw each dot as a normalized Gaussian over a base image. On CUDA a Triton kernel draws the dots, and on CPU a Numba kernel draws them with one frame per thread. The navigation extra installs Numba. Both kernels give the same bytes as the Torch path, and backend="torch" selects the Torch path on CPU.
SimplePointMaze draws a Scene2D that reproduces its Matplotlib figure in each frame. Only the info.goal image comes from Matplotlib.
Variation¶
Every class has agent.color, agent.radius, agent.speed and background.color variation leaves. The other leaves set the layout: the wall and doors of TwoRoom, the zone biases of Piecewise and the walls of SimplePointMaze. env.dynamics_variation_leaves lists the leaves that change the dynamics.
Classes¶
TwoRoom¶
A wall with doors splits the arena into two rooms, and the agent moves through a door to a target in the other room. The target is invisible in the frame. The state keeps its position, and a restored state keeps the task.
Success: the episode terminates when the agent is less than 16 px from the target.
| Property | Value |
|---|---|
| Reference | none |
| Physics | native Numba on CPU |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | Numba dot compositor |
| Renderer on CUDA | Triton dot compositor |
| Default frame | 224 × 224 × 3, uint8 |
| Native size | 224 px, the only size |
| Action | float32 (2,), [-1, 1] |
| Clips | rendered on CUDA at 224 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
navigation |
1 leaves, 4 values | float32 |
Variation space (11 leaves)
| Path | Type | Bounds or choices | Default | Sampled at reset |
|---|---|---|---|---|
agent.color |
RGBBox (3,) | [0, 255] | [255, 0, 0] | |
agent.radius |
Box (1,) | [7, 14] | 7 | |
agent.speed |
Box (1,) | [0.1, 50] | 5 | |
background.color |
RGBBox (3,) | [0, 255] | 255 | |
door.color |
RGBBox (3,) | [0, 255] | 255 | |
door.number |
Discrete | 3 choices from 1 | 1 | |
door.position |
Box (3,) | [0, 223] | 49 | |
door.size |
Box (3,) | [1, 21] | 14 | |
wall.axis |
Discrete | 2 choices from 0 | 1 | |
wall.color |
RGBBox (3,) | [0, 255] | 0 | |
wall.thickness |
Discrete | 35 choices from 7 | 10 |
TwoRoomTarget¶
This class draws the TwoRoom arena with a visible target, and the target position is part of the renderer input.
| Property | Value |
|---|---|
| Reference | none |
| Physics | native Numba on CPU |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | Numba dot compositor |
| Renderer on CUDA | Triton dot compositor |
| Default frame | 224 × 224 × 3, uint8 |
| Native size | 224 px, the only size |
| Action | float32 (2,), [-1, 1] |
| Clips | rendered on CUDA at 224 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
navigation |
1 leaves, 4 values | float32 |
Variation space (13 leaves)
| Path | Type | Bounds or choices | Default | Sampled at reset |
|---|---|---|---|---|
agent.color |
RGBBox (3,) | [0, 255] | [255, 0, 0] | |
agent.radius |
Box (1,) | [7, 14] | 7 | |
agent.speed |
Box (1,) | [0.1, 50] | 5 | |
background.color |
RGBBox (3,) | [0, 255] | 255 | |
door.color |
RGBBox (3,) | [0, 255] | 255 | |
door.number |
Discrete | 3 choices from 1 | 1 | |
door.position |
Box (3,) | [0, 223] | 49 | |
door.size |
Box (3,) | [1, 21] | 14 | |
target.color |
RGBBox (3,) | [0, 255] | [0, 255, 0] | |
target.radius |
Box (1,) | [7, 14] | 7 | |
wall.axis |
Discrete | 2 choices from 0 | 1 | |
wall.color |
RGBBox (3,) | [0, 255] | 0 | |
wall.thickness |
Discrete | 35 choices from 7 | 10 |
Piecewise¶
The arena is one open room with four zones, and each zone adds a motion bias to the agent. By default the zones and the target are invisible in the frame, and the rendering.render_bias_field and rendering.render_target leaves draw them.
Success: the episode terminates when the agent is less than 16 px from the target.
| Property | Value |
|---|---|
| Reference | none |
| Physics | native Numba on CPU |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | Numba dot compositor |
| Renderer on CUDA | Triton dot compositor |
| Default frame | 224 × 224 × 3, uint8 |
| Native size | 224 px, the only size |
| Action | float32 (2,), [-1, 1] |
| Clips | rendered on CUDA at 224 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
navigation |
1 leaves, 4 values | float32 |
Variation space (13 leaves)
| Path | Type | Bounds or choices | Default | Sampled at reset |
|---|---|---|---|---|
agent.color |
RGBBox (3,) | [0, 255] | [255, 0, 0] | |
agent.radius |
Box (1,) | [7, 14] | 7 | |
agent.speed |
Box (1,) | [0.1, 50] | 5 | |
background.color |
RGBBox (3,) | [0, 255] | 255 | |
border.color |
RGBBox (3,) | [0, 255] | 0 | |
rendering.render_bias_field |
Discrete | 2 choices from 0 | 0 | |
rendering.render_target |
Discrete | 2 choices from 0 | 0 | |
target.color |
RGBBox (3,) | [0, 255] | [0, 255, 0] | |
target.radius |
Box (1,) | [7, 14] | 7 | |
zones.bias_0 |
Box (2,) | [-10, 10] | [2, 0] | |
zones.bias_1 |
Box (2,) | [-10, 10] | [0, 2] | |
zones.bias_2 |
Box (2,) | [-10, 10] | [-2, 0] | |
zones.bias_3 |
Box (2,) | [-10, 10] | [0, -2] |
PiecewiseZones¶
This class draws the Piecewise arena with a different color for each zone.
| Property | Value |
|---|---|
| Reference | none |
| Physics | native Numba on CPU |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | Numba dot compositor |
| Renderer on CUDA | Triton dot compositor |
| Default frame | 224 × 224 × 3, uint8 |
| Native size | 224 px, the only size |
| Action | float32 (2,), [-1, 1] |
| Clips | rendered on CUDA at 224 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
navigation |
1 leaves, 2 values | float32 |
Variation space (14 leaves)
| Path | Type | Bounds or choices | Default | Sampled at reset |
|---|---|---|---|---|
agent.color |
RGBBox (3,) | [0, 255] | [255, 0, 0] | |
agent.radius |
Box (1,) | [7, 14] | 7 | |
agent.speed |
Box (1,) | [0.1, 50] | 5 | |
background.color |
RGBBox (3,) | [0, 255] | 255 | |
border.color |
RGBBox (3,) | [0, 255] | 0 | |
rendering.render_bias_field |
Discrete | 2 choices from 0 | 0 | |
zones.bias_0 |
Box (2,) | [-10, 10] | [2, 0] | |
zones.bias_1 |
Box (2,) | [-10, 10] | [0, 2] | |
zones.bias_2 |
Box (2,) | [-10, 10] | [-2, 0] | |
zones.bias_3 |
Box (2,) | [-10, 10] | [0, -2] | |
zones.color_0 |
RGBBox (3,) | [0, 255] | [255, 191, 191] | |
zones.color_1 |
RGBBox (3,) | [0, 255] | [223, 255, 191] | |
zones.color_2 |
RGBBox (3,) | [0, 255] | [191, 255, 255] | |
zones.color_3 |
RGBBox (3,) | [0, 255] | [223, 191, 255] |
SimplePointMaze¶
A point moves in a 5 × 5 arena with rectangular walls toward a visible goal. The frame is 500 × 500 px, as in the source's Matplotlib figure.
Success: the episode terminates when the agent is inside the goal radius. The reward is 1 at the goal and -0.01 for every other step.
Goal image: info.goal is the Matplotlib figure of the goal that reset and set_state draw, and every step returns the same image tensor. Don't write into it. For (B, T) actions, info.goal is a view of this image along the time axis. When an environment's episode ends inside the sequence, info.goal is a copy with zeros after the end.
| Property | Value |
|---|---|
| Reference | none |
| Physics | native torch on the env device |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | raster2d (torch) |
| Renderer on CUDA | raster2d (torch) with the Triton dot compositor |
| Default frame | 500 × 500 × 3, uint8 |
| Native size | 500 px, the only size |
| Action | float32 (2,), [-0.2, 0.2] |
| Clips | rendered on CUDA at 500 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
simple_point_maze |
3 leaves, 7 values | bool, float32, float64 |
Variation space (10 leaves)
| Path | Type | Bounds or choices | Default | Sampled at reset |
|---|---|---|---|---|
agent.color |
RGBBox (3,) | [0, 255] | [255, 0, 0] | |
agent.radius |
Box (1,) | [0.05, 0.5] | 0.1 | |
agent.speed |
Box (1,) | [0.05, 8] | 1 | |
background.color |
RGBBox (3,) | [0, 255] | 255 | |
goal.color |
RGBBox (3,) | [0, 255] | [0, 255, 0] | |
goal.radius |
Box (1,) | [0.05, 0.5] | 0.2 | |
walls.color |
RGBBox (3,) | [0, 255] | 0 | |
walls.number |
Discrete | 3 choices from 4 | 5 | |
walls.positions |
Box (6, 2) | [0, 5] | 12 values | |
walls.shape |
Box (6, 2) | [0.5, 1.5] | 12 values |
Limitations¶
Each class renders only at its fixed native size. Resize the output for a smaller frame.