Specs and spaces

A spec is a Spec or CompositeSpec that describes the shape, dtype, device, bounds and column names of the values in one batch row. Every environment has four, for its state, action, frame and variation, and its variation comes from a tree of space classes in stable_envs.spaces.

import numpy as np
import stable_envs as snv

env = snv.TwoRoom(num_envs=4, device="cpu")
print(env.action_spec)                          # Spec(shape=(2,), dtype=float32, bounds=[-1, 1])
print(env.frame_spec.batch_shape(env.num_envs)) # (4, 224, 224, 3)
print(env.state_spec.keys(nested=True))         # [('navigation', 'float32')]
print(env.state_spec["navigation", "float32"].shape)  # (4,)

actions = env.action_spec.sample(env.num_envs, rng=np.random.default_rng(0))
print(actions.shape, actions.dtype)               # torch.Size([4, 2]) torch.float32
print(env.action_spec.contains(actions * 3))      # False, outside [-1, 1]
print(env.state_spec.contains(env.reset(seed=0))) # True
env.close()

Specs

Spec Shape Describes
env.state_spec a CompositeSpec with one leaf for each state leaf The state that reset, get_state and step return, with the dtype of each leaf and, where the family declares them, bounds and names. On a folded state, each leaf is a group of fields (see Read a State field).
env.action_spec (action_dim,) One action. A discrete action has discrete_n set and an integer dtype.
env.frame_spec (H, W, 3), uint8, bounds [0, 255] One frame at the environment's size.
env.variation_spec (variation_dim,) One compiled variation row, with one name per column, such as agent.color[0].

A spec's shape leaves out the batch axis: action_spec.shape == (2,) means step takes (B, 2) or (B, T, 2) actions. batch_shape(B), zeros(B) and sample(B) add it back. validate checks the trailing shape, casts to the spec's dtype, and refuses NaN, infinity and values outside the bounds or the discrete values, and contains returns False where validate would raise. Spec.sample needs bounds or discrete_n. For state fields without bounds, draw states with env.sample_states(n) instead.

CompositeSpec nests specs by key path, the way state nests tensors: spec["navigation", "float32"] is the leaf for state["navigation", "float32"]. Its zeros and sample return a TensorDict with batch size (B,), and its validate also refuses missing and unexpected keys.

Spec dataclass

Spec(shape: tuple[int, ...], dtype: dtype = float32, low: Any = None, high: Any = None, device: device | None = None, names: tuple[str, ...] = (), discrete_n: int | None = None)

One environment's tensor shape, dtype, optional bounds and column names.

Attributes:

  • shape (tuple[int, ...]) –

    Shape without the batch axis, such as (2,) or (H, W, 3).

  • dtype (dtype) –

    Torch dtype of the values.

  • low (Any) –

    Inclusive lower bound that broadcasts to shape (unbounded if None).

  • high (Any) –

    Inclusive upper bound, like low.

  • device (device | None) –

    Device the values live on.

  • names (tuple[str, ...]) –

    One label per element of a one-dimensional spec.

  • discrete_n (int | None) –

    Number of integer values, 0 to discrete_n - 1, of a discrete spec.

Raises:

  • ValueError –

    If names is given and doesn't label each element of a one-dimensional spec.

Methods:

  • batch_shape –

    Return (num_envs, *shape).

  • to –

    Return a copy of this spec on device.

  • zeros –

    Return zeros of shape (num_envs, *shape).

  • sample –

    Sample (num_envs, *shape) values uniformly from the bounds or the discrete values.

  • validate –

    Check (N, *shape) input and return it cast to dtype on its own device.

  • contains –

    Return whether validate accepts x.

numel property

numel: int

Number of elements per environment.

bounded property

bounded: bool

Whether the spec is discrete or has both bounds.

batch_shape

batch_shape(num_envs: int) -> tuple[int, ...]

Return (num_envs, *shape).

Parameters:

  • num_envs (int) –

    Size of the batch axis.

to

to(device) -> Spec

Return a copy of this spec on device.

Parameters:

  • device –

    Target device.

zeros

zeros(num_envs: int, device=None) -> Tensor

Return zeros of shape (num_envs, *shape).

Parameters:

  • num_envs (int) –

    Size of the batch axis.

  • device –

    Output device (the spec's device if None).

sample

sample(num_envs: int, rng: Generator | None = None, device=None) -> Tensor

Sample (num_envs, *shape) values uniformly from the bounds or the discrete values.

Parameters:

  • num_envs (int) –

    Size of the batch axis.

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

    NumPy generator (a fresh unseeded one if None).

  • device –

    Output device (the spec's device if None).

Raises:

  • ValueError –

    If the spec is neither discrete nor bounded on both sides.

validate

validate(x, owner: str = 'value') -> Tensor

Check (N, *shape) input and return it cast to dtype on its own device.

Array input becomes a CPU tensor.

Parameters:

  • x –

    A tensor or array with a leading batch axis.

  • owner (str, default: 'value' ) –

    Name of the value in error messages.

Raises:

  • ValueError –

    If the trailing shape is not shape, a value is NaN or infinite, or a value is outside the bounds or the discrete values.

contains

contains(x) -> bool

Return whether validate accepts x.

Parameters:

  • x –

    The value to check.

CompositeSpec dataclass

CompositeSpec(specs: dict | None = None, device=None, **kw)

Nested specs addressed by key paths, such as spec["agent", "position"].

Parameters:

  • specs (dict | None, default: None ) –

    {key: Spec, CompositeSpec or dict}; dicts become nested composites.

  • device –

    Device of the composite.

  • **kw –

    More key=spec entries, merged over specs.

Methods:

  • keys –

    Return the top-level keys, or the leaf key paths such as ("agent", "position").

  • items –

    Return the top-level items, or (key path, Spec) leaf pairs.

  • to –

    Return a copy with every leaf on device.

  • zeros –

    Return a TensorDict of zeros with this structure and batch size (num_envs,).

  • sample –

    Sample every leaf with Spec.sample into a TensorDict with batch size (num_envs,).

  • validate –

    Check that x has exactly these keys and valid leaves, and return x unchanged.

  • contains –

    Return whether validate accepts x.

keys

keys(nested: bool = False)

Return the top-level keys, or the leaf key paths such as ("agent", "position").

Parameters:

  • nested (bool, default: False ) –

    Return leaf key paths instead of top-level keys.

items

items(nested: bool = False)

Return the top-level items, or (key path, Spec) leaf pairs.

Parameters:

  • nested (bool, default: False ) –

    Return leaf pairs instead of top-level items.

to

to(device) -> CompositeSpec

Return a copy with every leaf on device.

Parameters:

  • device –

    Target device.

zeros

zeros(num_envs: int, device=None) -> TensorDict

Return a TensorDict of zeros with this structure and batch size (num_envs,).

Parameters:

  • num_envs (int) –

    Size of the batch axis.

  • device –

    Output device (the spec's device if None).

sample

sample(num_envs: int, rng: Generator | None = None, device=None) -> TensorDict

Sample every leaf with Spec.sample into a TensorDict with batch size (num_envs,).

Parameters:

  • num_envs (int) –

    Size of the batch axis.

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

    NumPy generator (a fresh unseeded one if None).

  • device –

    Output device (the spec's device if None).

validate

validate(x, owner: str = 'value') -> TensorDict

Check that x has exactly these keys and valid leaves, and return x unchanged.

Parameters:

  • x –

    A TensorDict or mapping with a leading batch axis.

  • owner (str, default: 'value' ) –

    Name of the value in error messages.

Raises:

  • TypeError –

    If x has no keys.

  • ValueError –

    If keys are missing or unexpected, or a leaf is invalid.

contains

contains(x) -> bool

Return whether validate accepts x.

Parameters:

  • x –

    The value to check.

Spaces

stable_envs.spaces holds Gymnasium Discrete, Box and Dict spaces that also keep a default and a current value. A family builds one tree of them in make_variation_space, and env.variation_space is that tree for the instance:

from stable_envs import spaces

space = spaces.Dict({
    "agent": spaces.Dict({
        "color": spaces.RGBBox(init_value=(255, 0, 0)),
        "radius": spaces.Box(0.05, 0.2, shape=(1,), init_value=[0.1]),
    }),
    "door": spaces.Dict({"number": spaces.Discrete(3, init_value=1)}),
}, seed=0)

print(space.names())                  # ['agent.color', 'agent.radius', 'door.number']
print(space.value["agent"]["color"])  # [255   0   0]
space.update(["agent.radius"])        # resample one leaf
print(space.check())                  # True
space.reset()                         # back to the defaults
print(space.flat_dim)                 # 5

Leaves are addressed by dotted paths such as "agent.color", the same names that env.set_variation and reset options take. flat_layout, pack and unpack convert between the tree and the flat float32 row that env.get_variation() returns for each batch row. In most code you set variation through the environment rather than the space.

  • Dict(spaces, sampling_order=[...]) draws the listed keys first, then the others in insertion order. sample(), update() and ordered_names() follow this order, and an unknown key in sampling_order raises ValueError.
  • Box(..., exact=True) keeps values as given: a Python float stays float64. Without it, the leaf casts values to its dtype and shape.
  • set_init_value(value, reset_value=True) replaces a leaf's default. With reset_value=False the leaf keeps its current value.

Discrete

Discrete(n: int, init_value: int | None = None, constrain_fn=None, **kw)

Bases: _Valued, Discrete

Gymnasium Discrete with a default and current value.

Parameters:

  • n (int) –

    Number of values.

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

    Default value (0 if None).

  • constrain_fn –

    Extra test a value must pass.

  • **kw –

    Forwarded to gymnasium.spaces.Discrete, such as seed and start.

Methods:

  • sample –

    Draw an int that satisfies constrain_fn, store it if set_value, and return it.

  • contains –

    Return whether x lies in the space and satisfies constrain_fn.

sample

sample(mask=None, max_tries: int = 1000, set_value: bool = True, **kw)

Draw an int that satisfies constrain_fn, store it if set_value, and return it.

Parameters:

  • mask –

    Gymnasium's action mask, or None.

  • max_tries (int, default: 1000 ) –

    Draws to attempt before giving up.

  • set_value (bool, default: True ) –

    Store the draw as the current value.

  • **kw –

    Ignored.

Raises:

  • RuntimeError –

    If no draw satisfies constrain_fn within max_tries.

contains

contains(x) -> bool

Return whether x lies in the space and satisfies constrain_fn.

value property

value

The current value.

init_value property

init_value

The default value that reset restores.

set_value

set_value(value) -> None

Replace the current value.

Parameters:

  • value –

    The new value.

Raises:

  • ValueError –

    If value is not in the space. constrain_fn is not checked.

set_init_value

set_init_value(value, reset_value: bool = True) -> None

Replace the default value, and the current value too if reset_value.

Parameters:

  • value –

    The new default.

  • reset_value (bool, default: True ) –

    Also replace the current value.

Raises:

  • ValueError –

    If value is not in the space. constrain_fn is not checked.

reset

reset() -> None

Set the current value back to the default.

check

check() -> bool

Return whether the current value lies in the space and satisfies constrain_fn.

Box

Box(low, high, shape=None, dtype=float32, init_value=None, constrain_fn=None, exact=False, **kw)

Bases: _Valued, Box

Gymnasium Box with a default and current value.

Parameters:

  • low –

    Inclusive lower bound, a scalar or an array of shape.

  • high –

    Inclusive upper bound, like low.

  • shape –

    Value shape (taken from low and high if None).

  • dtype –

    NumPy dtype of the values.

  • init_value –

    Default value (zeros clipped into the bounds if None).

  • constrain_fn –

    Extra test a value must pass.

  • exact –

    Keep values as given, so Python floats stay float64, instead of casting to dtype.

  • **kw –

    Forwarded to gymnasium.spaces.Box, such as seed.

Methods:

  • sample –

    Draw a value that satisfies constrain_fn, store it if set_value, and return it.

  • contains –

    Return whether x, cast to dtype, lies in the bounds and satisfies constrain_fn.

  • set_value –

    Replace the current value, cast to dtype and shape unless exact.

  • set_init_value –

    Replace the default value, cast to dtype and shape unless exact.

sample

sample(mask=None, max_tries: int = 1000, set_value: bool = True, **kw)

Draw a value that satisfies constrain_fn, store it if set_value, and return it.

Parameters:

  • mask –

    Ignored.

  • max_tries (int, default: 1000 ) –

    Draws to attempt before giving up.

  • set_value (bool, default: True ) –

    Store the draw as the current value.

  • **kw –

    Ignored.

Raises:

  • RuntimeError –

    If no draw satisfies constrain_fn within max_tries.

contains

contains(x) -> bool

Return whether x, cast to dtype, lies in the bounds and satisfies constrain_fn.

set_value

set_value(value) -> None

Replace the current value, cast to dtype and shape unless exact.

set_init_value

set_init_value(value, reset_value: bool = True) -> None

Replace the default value, cast to dtype and shape unless exact.

value property

value

The current value.

init_value property

init_value

The default value that reset restores.

reset

reset() -> None

Set the current value back to the default.

check

check() -> bool

Return whether the current value lies in the space and satisfies constrain_fn.

RGBBox

RGBBox(init_value=(0, 0, 0), low=0, high=255, **kw)

Bases: Box

Box of three uint8 color channels, with a default (r, g, b) init_value.

Dict

Dict(spaces_dict: dict, sampling_order: Sequence[str] | None = None, **kw)

Bases: Dict

Nested variation spaces with current values and dotted leaf paths.

Parameters:

  • spaces_dict (dict) –

    {name: space}; a value can be another Dict.

  • sampling_order (Sequence[str] | None, default: None ) –

    Top-level keys that sample and update draw first, in this order.

  • **kw –

    Forwarded to gymnasium.spaces.Dict, such as seed.

Raises:

  • ValueError –

    If sampling_order names a key that is not in spaces_dict.

Methods:

  • sample –

    Sample every child in sampling order and return the values as a nested dict.

  • set_value –

    Set current values from {dotted path: value}.

  • set_init_value –

    Set defaults from {dotted path: value}, and the current values too if reset_value.

  • reset –

    Restore every leaf's current value to its default.

  • check –

    Return whether every current value lies in its space; debug logs the failing leaves.

  • update –

    Resample the named leaves or subtrees, leaving other values unchanged.

  • names –

    Return all dotted leaf paths, such as "agent.color", in key order.

  • ordered_names –

    Yield every dotted path in sampling order, each subtree before its children.

  • flat_layout –

    Return one (dotted path, column offset, width) entry per leaf, sorted by path.

  • pack –

    Pack the current values, or values where given, into a (flat_dim,) float32 row.

  • unpack –

    Split a (flat_dim,) row into {dotted path: value}; vector values may share its storage.

Attributes:

  • value (dict) –

    Current values, nested like the space.

  • init_value (dict) –

    Default values, nested like the space; a child without a default gives None.

  • flat_dim (int) –

    Width of a packed row.

value property

value: dict

Current values, nested like the space.

init_value property

init_value: dict

Default values, nested like the space; a child without a default gives None.

flat_dim property

flat_dim: int

Width of a packed row.

sample

sample(mask=None, set_value: bool = True, **kw) -> dict

Sample every child in sampling order and return the values as a nested dict.

Parameters:

  • mask –

    A {key: mask} dict for the children, or None.

  • set_value (bool, default: True ) –

    Store the draws as the current values.

  • **kw –

    Ignored.

set_value

set_value(values: dict) -> None

Set current values from {dotted path: value}.

Parameters:

  • values (dict) –

    The values to set.

Raises:

  • KeyError –

    If a path is not in the space.

set_init_value

set_init_value(values: dict, reset_value: bool = True) -> None

Set defaults from {dotted path: value}, and the current values too if reset_value.

Parameters:

  • values (dict) –

    The new defaults.

  • reset_value (bool, default: True ) –

    Also replace the current values.

Raises:

  • KeyError –

    If a path is not in the space.

reset

reset() -> None

Restore every leaf's current value to its default.

check

check(debug: bool = False) -> bool

Return whether every current value lies in its space; debug logs the failing leaves.

update

update(keys: Iterable[str]) -> None

Resample the named leaves or subtrees, leaving other values unchanged.

With sampling_order, ["all"] resamples everything and unknown names are ignored.

Parameters:

  • keys (Iterable[str]) –

    Dotted paths of leaves or subtrees.

Raises:

  • KeyError –

    If a path is not in the space and the space has no sampling_order.

names

names(prefix: str = '') -> list[str]

Return all dotted leaf paths, such as "agent.color", in key order.

ordered_names

ordered_names(prefix: str = '')

Yield every dotted path in sampling order, each subtree before its children.

flat_layout

flat_layout() -> list[tuple[str, int, int]]

Return one (dotted path, column offset, width) entry per leaf, sorted by path.

pack

pack(values: dict | None = None) -> ndarray

Pack the current values, or values where given, into a (flat_dim,) float32 row.

Parameters:

  • values (dict | None, default: None ) –

    {dotted path: value} entries that replace the current values in the row.

unpack

unpack(vec) -> dict

Split a (flat_dim,) row into {dotted path: value}; vector values may share its storage.

Parameters:

  • vec –

    A row from pack.

reset_variation_space

reset_variation_space(variation_space: Dict, seed: int | None = None, options: dict | None = None, default_variations: Sequence[str] | None = None) -> None

Seed and reset variation_space, resample selected leaves, then apply explicit values.

Parameters:

  • variation_space (Dict) –

    The space to reset in place.

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

    Seed of the space's generators.

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

    "variation", the dotted paths to resample, and "variation_values", {dotted path: value}.

  • default_variations (Sequence[str] | None, default: None ) –

    Paths to resample when options has no "variation".

Raises:

  • ValueError –

    If "variation" is a string or not a sequence, or a value is outside its space.

  • KeyError –

    If a path is not in the space (resample paths are checked only without sampling_order).

  • AssertionError –

    If a value fails its constrain_fn after the overrides.