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,
0todiscrete_n - 1, of a discrete spec.
Raises:
-
ValueError–If
namesis 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 todtypeon its own device. -
contains–Return whether
validateacceptsx.
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.
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=specentries, merged overspecs.
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.sampleinto a TensorDict with batch size(num_envs,). -
validate–Check that
xhas exactly these keys and valid leaves, and returnxunchanged. -
contains–Return whether
validateacceptsx.
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
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
xhas nokeys. -
ValueError–If keys are missing or unexpected, or a leaf is invalid.
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()andordered_names()follow this order, and an unknown key insampling_orderraisesValueError.Box(..., exact=True)keeps values as given: a Python float stays float64. Without it, the leaf casts values to itsdtypeand shape.set_init_value(value, reset_value=True)replaces a leaf's default. Withreset_value=Falsethe 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 asseedandstart.
Methods:
-
sample–Draw an int that satisfies
constrain_fn, store it ifset_value, and return it. -
contains–Return whether
xlies in the space and satisfiesconstrain_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_fnwithinmax_tries.
set_value
¶
set_value(value) -> None
Replace the current value.
Parameters:
-
value–The new value.
Raises:
-
ValueError–If
valueis not in the space.constrain_fnis 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
valueis not in the space.constrain_fnis not checked.
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
lowandhighif 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 asseed.
Methods:
-
sample–Draw a value that satisfies
constrain_fn, store it ifset_value, and return it. -
contains–Return whether
x, cast todtype, lies in the bounds and satisfiesconstrain_fn. -
set_value–Replace the current value, cast to
dtypeandshapeunlessexact. -
set_init_value–Replace the default value, cast to
dtypeandshapeunlessexact.
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_fnwithinmax_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.
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)
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 anotherDict. -
sampling_order(Sequence[str] | None, default:None) –Top-level keys that
sampleandupdatedraw first, in this order. -
**kw–Forwarded to
gymnasium.spaces.Dict, such asseed.
Raises:
-
ValueError–If
sampling_ordernames a key that is not inspaces_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 ifreset_value. -
reset–Restore every leaf's current value to its default.
-
check–Return whether every current value lies in its space;
debuglogs 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
valueswhere 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.
init_value
property
¶
init_value: dict
Default values, nested like the space; a child without a default gives None.
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.
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:
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.
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
optionshas 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_fnafter the overrides.