tessl/pypi-gymnasium
A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym).
—
Pending
spaces.mddocs/
Spaces
Spaces define the structure and constraints of action and observation spaces in Gymnasium environments. They specify what types of data are valid and provide sampling methods for generating valid examples.
Capabilities
Fundamental Spaces
Basic space types for common use cases.
class Box(Space):
"""
Continuous multi-dimensional space with bounds.
Args:
low: Lower bounds (scalar or array)
high: Upper bounds (scalar or array)
shape: Shape of the space (optional if low/high are arrays)
dtype: Data type (default: np.float32)
"""
def __init__(self, low: SupportsFloat | NDArray[Any], high: SupportsFloat | NDArray[Any],
shape: Sequence[int] | None = None,
dtype: type[np.floating[Any]] | type[np.integer[Any]] = np.float32,
seed: int | np.random.Generator | None = None):
pass
class Discrete(Space):
"""
Discrete space with n possible integer values from 0 to n-1.
Args:
n: Number of possible values (positive integer)
start: Starting value (default: 0)
"""
def __init__(self, n: int | np.integer[Any],
seed: int | np.random.Generator | None = None,
start: int | np.integer[Any] = 0):
pass
class MultiDiscrete(Space):
"""
Multiple discrete spaces, each with different number of actions.
Args:
nvec: Array of integers specifying number of actions for each discrete space
dtype: Data type (default: np.int64)
seed: Random number generator seed
start: Starting values for each discrete space (default: 0)
"""
def __init__(self, nvec: NDArray[np.integer[Any]] | list[int],
dtype: str | type[np.integer[Any]] = np.int64,
seed: int | np.random.Generator | None = None,
start: NDArray[np.integer[Any]] | list[int] | None = None):
pass
class MultiBinary(Space):
"""
Multiple binary choices (0 or 1 for each element).
Args:
n: Number of binary elements (int or array-like for shape)
seed: Random number generator seed
"""
def __init__(self, n: NDArray[np.integer[Any]] | Sequence[int] | int,
seed: int | np.random.Generator | None = None):
pass
class Text(Space):
"""
Space of text strings with character set and length constraints.
Args:
max_length: Maximum length of text strings
min_length: Minimum length of text strings (default: 1, keyword-only)
charset: Set of allowed characters (default: alphanumeric)
seed: Random number generator seed
"""
def __init__(self, max_length: int, *, min_length: int = 1,
charset: frozenset[str] | str = alphanumeric,
seed: int | np.random.Generator | None = None):
passComposite Spaces
Spaces that combine multiple sub-spaces.
class Dict(Space):
"""
Dictionary of named spaces.
Args:
spaces: Dictionary mapping names to Space objects or None
seed: Random number generator seed
**spaces_kwargs: Spaces as keyword arguments
"""
def __init__(self, spaces: None | dict[str, Space] | Sequence[tuple[str, Space]] = None,
seed: dict | int | np.random.Generator | None = None,
**spaces_kwargs: Space):
pass
class Tuple(Space):
"""
Tuple of spaces.
Args:
spaces: Tuple or list of Space objects
seed: Random number generator seed
"""
def __init__(self, spaces: Sequence[Space[Any]],
seed: int | np.random.Generator | None = None):
pass
class Sequence(Space):
"""
Variable-length sequence of elements from the same space.
Args:
space: The space of individual elements
seed: Random number generator seed
"""
def __init__(self, space: Space[Any],
seed: int | np.random.Generator | None = None):
pass
class OneOf(Space):
"""
One of multiple possible spaces (union type).
Args:
spaces: Sequence of Space objects
seed: Random number generator seed
"""
def __init__(self, spaces: Sequence[Space[Any]],
seed: int | np.random.Generator | None = None):
passGraph Space
Specialized space for graph-structured data.
class Graph(Space):
"""
Graph space with nodes and edges.
Args:
node_space: Space for node features (Box or Discrete)
edge_space: Space for edge features (Box, Discrete, or None)
seed: Random number generator seed
"""
def __init__(self, node_space: Box | Discrete, edge_space: None | Box | Discrete,
seed: int | np.random.Generator | None = None):
pass
class GraphInstance:
"""
Instance of a graph space containing nodes and edges.
Attributes:
nodes: Node feature array
edges: Edge feature array
edge_links: Edge connectivity array
"""
nodes: NDArray[Any]
edges: NDArray[Any] | None
edge_links: NDArray[Any] | None
passSpace Utilities
Utility functions for working with spaces.
def flatdim(space: Space[Any]) -> int:
"""
Get the flattened dimension of a space.
Args:
space: The space to flatten
Returns:
Total number of dimensions when flattened
"""
def flatten_space(space: Space[Any]) -> Box | Dict | Sequence | Tuple | Graph:
"""
Flatten a composite space into a Box space.
Args:
space: The space to flatten
Returns:
Flattened Box space
"""
def flatten(space: Space[T], x: T) -> FlatType:
"""
Flatten a sample from a space.
Args:
space: The space the sample belongs to
x: Sample to flatten
Returns:
Flattened sample as numpy array
"""
def unflatten(space: Space[T], x: FlatType) -> T:
"""
Unflatten a sample back to its original space structure.
Args:
space: The original space structure
x: Flattened sample
Returns:
Sample in original space format
"""Usage Examples
Creating and Using Basic Spaces
import gymnasium.spaces as spaces
import numpy as np
# Continuous space for positions
position_space = spaces.Box(low=-10.0, high=10.0, shape=(3,), dtype=np.float32)
position = position_space.sample() # Random 3D position
print(position_space.contains([0.0, 5.0, -2.0])) # True
# Discrete action space
action_space = spaces.Discrete(4) # 4 possible actions: 0, 1, 2, 3
action = action_space.sample() # Random action
# Multiple discrete choices
multi_discrete = spaces.MultiDiscrete([3, 2, 4]) # 3×2×4 = 24 combinations
sample = multi_discrete.sample() # e.g., [1, 0, 2]
# Binary choices
binary_space = spaces.MultiBinary(5) # 5 binary choices
binary_sample = binary_space.sample() # e.g., [0, 1, 1, 0, 1]Composite Spaces
# Dictionary space for complex observations
observation_space = spaces.Dict({
'image': spaces.Box(low=0, high=255, shape=(64, 64, 3), dtype=np.uint8),
'position': spaces.Box(low=-1.0, high=1.0, shape=(2,), dtype=np.float32),
'inventory': spaces.MultiDiscrete([10, 5, 3]) # item counts
})
obs = observation_space.sample()
# obs = {
# 'image': array of shape (64, 64, 3),
# 'position': array of shape (2,),
# 'inventory': array of shape (3,)
# }
# Tuple space
tuple_space = spaces.Tuple((
spaces.Discrete(4),
spaces.Box(low=0, high=1, shape=(2,))
))
sample = tuple_space.sample() # (int, array)Working with Graph Spaces
# Graph space for network environments
node_space = spaces.Box(low=0, high=1, shape=(4,)) # 4 features per node
edge_space = spaces.Box(low=0, high=1, shape=(2,)) # 2 features per edge
graph_space = spaces.Graph(node_space, edge_space)
graph_sample = graph_space.sample()
# Access graph components
nodes = graph_sample.nodes # Node feature matrix
edges = graph_sample.edges # Edge feature matrix
links = graph_sample.edge_links # Edge connectivity matrixSpace Flattening
from gymnasium.spaces.utils import flatten_space, flatten, unflatten
# Complex composite space
complex_space = spaces.Dict({
'vector': spaces.Box(low=0, high=1, shape=(3,)),
'discrete': spaces.Discrete(4)
})
# Flatten for ML algorithms that expect vectors
flat_space = flatten_space(complex_space) # Box space
print(flat_space.shape) # (4,) - 3 continuous + 1 discrete
# Flatten samples
sample = complex_space.sample()
flat_sample = flatten(complex_space, sample) # 1D numpy array
# Restore original structure
restored = unflatten(complex_space, flat_sample)Install with Tessl CLI
npx tessl i tessl/pypi-gymnasium