Env

snv.Env is the base class of every environment. snv.TwoRoom, snv.CartPole and the rest share its shape and step-output conventions and the methods on this page. An environment runs num_envs batch rows on one device: you reset and step it, save and restore its state, set its variation, and render frames from any state you kept.

import torch
import stable_envs as snv

env = snv.TwoRoom(num_envs=4, device="cpu")
state = env.reset(seed=0)
out = env.step(torch.zeros(4, 8, 2), frames=slice(None))  # 8 steps, every state and frame
print(out["reward"].shape)      # torch.Size([4, 8])
print(out["frames"].shape)      # torch.Size([4, 8, 224, 224, 3])
print(env.render(state).shape)  # torch.Size([4, 224, 224, 3]), a saved state, no stepping
env.set_variation({"agent.color": [255, 0, 0]})  # a red agent from now on
print(env.get_variation().shape)                 # torch.Size([4, 23])
rows = torch.as_tensor(env.sample_variation(4))  # one sampled row per batch row
print(env.render(state, variation=rows).shape)   # torch.Size([4, 224, 224, 3])
env.close()

Shapes

Call Takes Returns
reset(seed) an int or None State, a TensorDict with batch size (B,)
step(actions) (B, *A) or (B, T, *A) a step result with batch size (B,), see Step outputs
get_state(), state nothing State with batch size (B,)
set_state(state) State with batch size (B,) None
render(x) None for the live state, a state with batch size (N,), or (N, state_dim) compact rows (N, H, W, 3) uint8 frames
get_variation() nothing (B, variation_dim) float32
set_variation(v) a dict of leaf values, or a (variation_dim,) or (B, variation_dim) row (B, variation_dim) float32
sample_variation(n) a row count (n, variation_dim) float32 NumPy array

snv.State and snv.StepResult are both tensordict.TensorDict. snv.VariationLike is what set_variation and render(variation=...) accept: a mapping of leaf paths to values, or a tensor or NumPy row.

Step outputs

step(actions, *, states=slice(None), frames=slice(-1, None))

actions is (B, A) for one action per batch row or (B, T, A) for a sequence, with T at least 1. Discrete actions use A = 1, and a single discrete action can also be an integer tensor of shape (B,). step keeps the dtype you pass. states and frames are keyword-only Python slices over the states after each action, independent of each other, and None turns that history off. The first output is the state after the first action, not the state you started from.

You want states frames
all states, final frame (default) slice(None) slice(-1, None)
final state and frame only None slice(-1, None)
outputs only, no state and no frame (fastest; pass state=False) None None
all states, no rendering slice(None) None
all states and frames slice(None) slice(None)
States at 0, 4, 8... and frames at 3, 7, 11... slice(None, None, 4) slice(3, None, 4)

Slices follow Python's rules for clipping, negative indices and negative strides. A reverse slice changes the order of the outputs, not the order the simulation runs in. A selector must be a slice or None, and an integer raises TypeError. step checks selectors, strides and action shapes before it moves the simulation. A bad call leaves the environment where it was.

Key Shape Notes
state batch (B,) the state after the last action; missing with state=False
states batch (B, S) the S selected states, missing when states=None
frames (B, F, H, W, 3) uint8 the F selected frames, missing when frames=None
valid (B, T) whether each action ran
state_valid, frame_valid (B, S) and (B, F) whether each selected state or frame is real, in output order

A single action counts as a sequence of length one: frames is (B, 1, H, W, 3) even then, and frames[:, 0] is the default final frame. An empty frames slice gives F = 0 and renders nothing. Task outputs such as reward and terminated keep the names and dtypes of the upstream library, and gain a time axis for a sequence. Classes without RGB output need frames=None.

Each batch row stops at its first termination or truncation and skips the rest of its actions. The transition that ended it is valid, and its later task outputs are zero. Its later selected states and frames repeat the final one with state_valid and frame_valid set to false. step never resets a batch row. The next step call steps every batch row again, and a single action after the end behaves as it does in the upstream library.

Returned states and frames own their memory, and later calls leave them unchanged. A few classes return the same task output tensor at every step, such as info.goal of SimplePointMaze; treat it as read-only. Selecting fewer frames skips rendering, while physics still runs for every action. Calling get_state() right after step() copies result["state"] again. state=False (keyword-only, default True) skips building the final state, which lowers the cost of each call for classes with a large state such as PushT; call get_state() when you need it. Send a sequence only when you already know every action in it. To branch from a state, use a second environment with set_state.

Construction

num_envs is fixed at construction, and len(env) equals it. Families add their own keywords, such as simulation_backend, which their environment pages describe.

device decides where the environment runs and where every returned tensor lives. Its default depends on the class:

Default device Classes
the global default_device, which is "auto" unless you change it with snv.set classic control, navigation, PushT, Craftax, Miniworld, MS-Human, Roadster
"cuda" DM Control, OGBench mazes
"cpu" Fetch, OGBCube, OGBScene, PyFlytRocketLanding

"auto" picks CUDA when torch can see a GPU, and the CPU otherwise.

Base class for a batch of simulators with restorable state and state-driven rendering.

One instance runs num_envs environments, one per batch row, and the tensors it returns live on device. Use it as a context manager, or call close, to release workers and GPU buffers.

Families add their own keywords, such as simulation_backend.

Parameters:

  • num_envs (int, default: 1 ) –

    Batch size B.

  • size (int | None, default: None ) –

    Frame height and width in pixels (default_size if None). Some families draw a fixed frame, so frame_spec has the exact shape.

  • supersample (int, default: 1 ) –

    Samples per pixel along each axis.

  • device (str | None, default: None ) –

    Output device (the global default_device if None); "auto" picks CUDA when available. Where physics runs depends on the family.

  • backend (str, default: 'auto' ) –

    Renderer backend; "auto" lets the family choose.

  • seed (int, default: 0 ) –

    Seed of the environment's sampler.

Raises:

  • ValueError –

    If the class requires CUDA and device is not a CUDA device.

These class attributes are what snv.info reads without building anything:

Attribute Meaning
family, domain The family ID and the task group inside it, which snv.list_envs filters on
name The environment slug that env.id returns, such as "two-room"
reference_id The upstream library's id this class is compared with, such as "CartPole-v1", or None
default_size Frame size in pixels when size is omitted
native_size The only size that the class draws, or None when the class draws any size
requires_cuda True when the class has no CPU path

Lifecycle

Closing releases only what that environment owns. Rendering contexts that several environments share in one process stay alive for the life of the process, and the other environments keep working. After close, reset, step, get_state, set_state and render raise RuntimeError.

reset

reset(seed: int | None = None) -> TensorDict

Start a new episode in every environment and return the full state.

Most families also accept options; see draw_reset_values.

Parameters:

  • seed (int | None, default: None ) –

    Restarts the sampler, so the same seed gives the same state. With None, seeding follows the upstream library.

Raises:

step

step(actions, *, states=slice(None), frames=slice(-1, None), state: bool = True) -> TensorDict

Advance one action or a sequence of actions per environment.

An environment that finishes mid-sequence holds its last state, and its later task outputs are zero.

Parameters:

  • actions –

    (B, *action_shape) for one step or (B, T, *action_shape) for T steps. Discrete (1,) actions also accept (B,).

  • states –

    Slice over the steps that selects which states to return, or None.

  • frames –

    Slice over the steps that selects which frames to render, or None.

  • state (bool, default: True ) –

    Return the final state; False skips building it, and get_state() builds it on demand.

Returns:

  • TensorDict –

    A TensorDict with batch size (B,): state (the final state, unless state=False), the family's task outputs such as reward ((B, T, ...) for a sequence), the (B, T) valid mask, and the selected (B, S) states and (B, F, H, W, 3) uint8 frames with their state_valid and frame_valid masks.

Raises:

  • RuntimeError –

    If the environment is closed.

  • NotImplementedError –

    If the environment has no dynamics.

  • ValueError –

    If actions has the wrong shape, or frames is set without RGB output.

  • TypeError –

    If states or frames is neither a slice nor None, or state is not a bool.

close

close() -> None

Release worker processes and GPU buffers; repeated calls do nothing.

Leaving a with block calls this. Afterward, reset, step, get_state, set_state and render raise RuntimeError.

closed property

closed: bool

Whether close has been called.

State

get_state and the state property return a copy of the live state that later steps leave unchanged. set_state needs a full state with exactly num_envs batch rows, refuses anything else, and returns None. The environment has to use a variation compatible with the one the state came from: a state carries only part of the configuration.

get_state

get_state() -> State

Return an independent copy of the full simulator state, laid out as state_spec.

It includes hidden fields an agent shouldn't see, so it isn't an observation.

Raises:

state property

state: State

Independent full state snapshot, the same as get_state().

set_state

set_state(state: State) -> None

Restore a full state with num_envs rows under the current variation.

The state is copied in, so later changes to state don't reach the environment.

Parameters:

  • state (State) –

    A full state from get_state, reset or step, with batch size (num_envs,).

Raises:

  • RuntimeError –

    If the environment is closed.

  • NotImplementedError –

    If the environment has no dynamics.

  • TypeError –

    If state is not a TensorDict, such as compact renderer rows.

  • ValueError –

    If the batch size is not (num_envs,) or a field is missing, misshaped or non-finite.

Specs

Each spec describes one batch row, without the batch axis, using the spec classes.

state_spec property

state_spec: CompositeSpec

Specs of the state fields, without the batch axis.

A (num_envs, 2) field has a spec of shape (2,).

action_spec property

action_spec: Spec

Spec of one environment's action.

step takes (B, *shape) or (B, T, *shape) actions. Raises NotImplementedError when the environment declares no action.

frame_spec property

frame_spec: Spec

Spec of one (H, W, 3) uint8 RGB frame.

variation_spec property

variation_spec: Spec

Spec of a compiled variation row, with one name per column such as "agent.color[0]".

Variation

set_variation installs a variation that stays until you change it. Every later reset restores the values you set for each leaf its options skip. Reset options sample or set leaves for one episode only. variation_space is the instance's stable_envs.spaces.Dict of leaves, and get_variation() is the compiled form that rendering and physics read. Randomize appearance and physics walks through both.

variation_dim property

variation_dim: int

Number of columns in a compiled variation row.

variation_names property

variation_names: list[str]

Dotted leaf paths in compiled-row order; a vector leaf spans several columns.

default_variation

default_variation() -> ndarray

Return the declared default variation as a (variation_dim,) float32 NumPy row.

get_variation

get_variation() -> Tensor

Return the installed variation, one float32 row per environment.

This is the live buffer, so clone it before you change it.

set_variation

set_variation(variation: VariationLike | None = None, **overrides) -> Tensor

Install a variation and return it as get_variation does.

Later reset calls restore it for every leaf their options don't name.

Parameters:

  • variation (VariationLike | None, default: None ) –

    A {dotted leaf path: value} dict, a compiled (variation_dim,) row for every environment or (num_envs, variation_dim) rows, or None for the defaults.

  • **overrides –

    More {leaf path: value} entries, applied last.

Returns:

  • Tensor –

    The installed (num_envs, variation_dim) float32 rows.

Raises:

  • KeyError –

    If a leaf path is unknown.

  • ValueError –

    If a row or value has the wrong width or number of rows.

sample_variation

sample_variation(batch: int | None = None, paths=None, rng: Generator | None = None) -> ndarray

Sample (batch, variation_dim) float32 variation rows without installing them.

Box leaves are uniform between their bounds and Discrete leaves uniform over start to start + n - 1.

Parameters:

  • batch (int | None, default: None ) –

    Number of rows (num_envs if None).

  • paths –

    Dotted leaf paths to sample (all if None); other leaves keep their defaults.

  • rng (Generator | None, default: None ) –

    NumPy generator (the environment's own if None).

Returns:

  • ndarray –

    A (batch, variation_dim) float32 array; pass it to set_variation or render.

Raises:

  • KeyError –

    If paths names an unknown leaf.

variation_values

variation_values() -> dict

Return the values the variation space holds, as a nested dict.

These are the defaults the family declares for each leaf, and only an edit of variation_space itself changes them. The variation that frames are drawn with is per environment; read it with get_variation.

draw_reset_values

draw_reset_values(seed: int | None = None, options: Mapping | None = None) -> dict[str, ndarray]

Resolve stable-worldmodel-style reset options into {path: (num_envs, ...)} arrays.

Every reset calls this. Leaves the options don't name return to their defaults (the registered values, or the last set_variation); named leaves are sampled or set for this episode.

Parameters:

  • seed (int | None, default: None ) –

    Seed of this reset; each environment derives its own from it and its index.

  • options (Mapping | None, default: None ) –

    "variation", the dotted paths to sample (the family's default reset leaves if absent), and "variation_values", {dotted path: value} for the batch or per row.

Returns:

  • dict[str, ndarray] –

    {dotted path: (num_envs, ...) array} for every reset leaf.

Raises:

  • ValueError –

    If options["variation"] is not a list or tuple, or a value has the wrong shape.

  • NotImplementedError –

    If options names a leaf the family can't set at reset.

dynamics_variation_leaves is a frozenset of the variation leaves that change dynamics, such as physics.gravity on CartPole, and every other leaf changes only the picture. physics_variation_leaves is narrower: the leaves the DM Control and Roadster simulators read as physics parameters. It's empty for the other families.

physics_variation_leaves property

physics_variation_leaves: tuple[str, ...]

Variation leaves the simulator reads as physics parameters; empty without a physics layout.

Rendering

render(x) is the one public way to draw frames. It does not change the live simulation. x is one of these forms:

  • None: the frames of the live batch rows.
  • A full state from reset, step or get_state, with any batch size N. PyFlytRocketLanding is the exception: it needs exactly num_envs batch rows.
  • Compact rows (N, state_dim), NumPy or Torch, as sample_states returns them.
  • A RenderState from to_render_state, for OGBCube, OGBScene, PushT, PushTDiscrete and PyFlytRocketLanding.

A state draws with its own variation. Compact rows draw with the current variation, or with variation= for this call only. render(state) checks only the state fields that the frame reads: their presence, shape and finite values. set_state checks the full state.

Some classes do not draw compact rows. Classes with state_dim 0, such as PushT, MiniWorldMovingBlockWorld and the Craftax classes, refuse them. PyFlytRocketLanding draws rows on CUDA only. OGBCube, OGBScene and the Roadster classes draw rows on each device. A form that the class does not draw raises TypeError, and the message gives the forms that the class accepts.

native_size is the only size that a class draws, or None when the class draws any size. Classic control, navigation and Craftax set it, because their upstream libraries draw each primitive in fixed pixels. Another size raises ValueError.

render

render(x=None, **kwargs) -> Tensor

Draw uint8 RGB frames without advancing the simulation.

A full state draws with its own appearance. Compact rows draw with the current variation, or with variation= for this call only. A form that the family cannot draw raises an error that names the forms it accepts.

Parameters:

  • x –

    None for the frames of the live environments; a full state from get_state, reset or step, with batch size (N,); compact rows (N, state_dim), NumPy or Torch, as sample_states returns them; or a RenderState from to_render_state, for families that have it.

  • **kwargs –

    Renderer options. Most families accept size, supersample, variation and out, a contiguous (N, H, W, 3) uint8 buffer to fill.

Returns:

  • Tensor –

    (N, H, W, 3) uint8 frames on device; (H, W) follows frame_spec unless

  • Tensor –

    size is passed.

Raises:

  • RuntimeError –

    If the environment is closed.

  • NotImplementedError –

    If x is None and the environment has no dynamics.

  • TypeError –

    If the family cannot draw the form of x.

  • ValueError –

    If a state field or row is missing, misshaped or non-finite, or out is not a contiguous uint8 buffer.

sample_states

sample_states(batch: int, rng: Generator | None = None) -> ndarray

Sample (batch, state_dim) compact renderer rows as a NumPy array.

The rows feed renderer tests and benchmarks. They aren't full state, so set_state rejects them.

Parameters:

  • batch (int) –

    Number of rows.

  • rng (Generator | None, default: None ) –

    NumPy generator (the environment's own if None).

describe

describe() -> dict[str, Any]

Return a JSON-friendly dict of the environment's specs and its comparison with the upstream library.

state_fields maps each /-joined state key to its shape and dtype. simulation_backend and execution_mode name the physics this instance selected; with simulation_backend="auto" they can differ between machines. visual_fidelity, visual_note and reference_versions appear only when the class declares them.

Metadata

num_envs property

num_envs: int

Number of environments in the batch, B.

has_dynamics property

has_dynamics: bool

Whether this environment implements step; render-only environments do not.

class_name property

class_name: str

Python class name, which is also the registry key.

id property

id: str

Stable environment slug, distinct from its Python class name.

resolve_device staticmethod

resolve_device(device: str | None) -> str

Resolve None to the global default device and "auto" to "cuda" or "cpu".

Parameters:

  • device (str | None) –

    A device string, "auto", or None for the global default_device.

Returns:

  • str –

    The device string to use, such as "cpu" or "cuda:0".

state_names_of

state_names_of(key) -> list[str]

Return the renderer column names of a state key or key path (empty for hidden fields).

Parameters:

  • key –

    A top-level state key or a key path such as ("agent", "position").

Raises:

  • KeyError –

    If key is not a state field.

render_state_dim property

render_state_dim: int

Width of the private float32 renderer projection, which may omit simulator fields.

render_state_names property

render_state_names: tuple[str, ...]

Column labels of the private renderer projection.

Family hooks

A family implements these hooks; see Adding an environment.

make_variation_space

make_variation_space() -> Dict

Return the family's spaces.Dict of variation leaves; the constructor calls this hook once.

scene

scene(states: Tensor, variation: VariationLike | None = None, style=None) -> Scene2D

Build a Scene2D from (B, render_state_dim) compact rows.

Primitive renderers implement this hook; other backends override _render.

Parameters:

  • states (Tensor) –

    Compact float32 rows.

  • variation (VariationLike | None, default: None ) –

    Leaf overrides or a compiled variation row for this call.

  • style –

    Internal form of a compiled row; pass variation instead.