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.

Random actions
Sampled variation (top left: default)
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.

Random actions
Sampled variation (top left: default)
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.

Random actions
Sampled variation (top left: default)
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.

Random actions
Sampled variation (top left: default)
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.

Random actions
Sampled variation (top left: default)
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.