0
# Spaces
1
2
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.
3
4
## Capabilities
5
6
### Fundamental Spaces
7
8
Basic space types for common use cases.
9
10
```python { .api }
11
class Box(Space):
12
"""
13
Continuous multi-dimensional space with bounds.
14
15
Args:
16
low: Lower bounds (scalar or array)
17
high: Upper bounds (scalar or array)
18
shape: Shape of the space (optional if low/high are arrays)
19
dtype: Data type (default: np.float32)
20
"""
21
22
def __init__(self, low: SupportsFloat | NDArray[Any], high: SupportsFloat | NDArray[Any],
23
shape: Sequence[int] | None = None,
24
dtype: type[np.floating[Any]] | type[np.integer[Any]] = np.float32,
25
seed: int | np.random.Generator | None = None):
26
pass
27
28
class Discrete(Space):
29
"""
30
Discrete space with n possible integer values from 0 to n-1.
31
32
Args:
33
n: Number of possible values (positive integer)
34
start: Starting value (default: 0)
35
"""
36
37
def __init__(self, n: int | np.integer[Any],
38
seed: int | np.random.Generator | None = None,
39
start: int | np.integer[Any] = 0):
40
pass
41
42
class MultiDiscrete(Space):
43
"""
44
Multiple discrete spaces, each with different number of actions.
45
46
Args:
47
nvec: Array of integers specifying number of actions for each discrete space
48
dtype: Data type (default: np.int64)
49
seed: Random number generator seed
50
start: Starting values for each discrete space (default: 0)
51
"""
52
53
def __init__(self, nvec: NDArray[np.integer[Any]] | list[int],
54
dtype: str | type[np.integer[Any]] = np.int64,
55
seed: int | np.random.Generator | None = None,
56
start: NDArray[np.integer[Any]] | list[int] | None = None):
57
pass
58
59
class MultiBinary(Space):
60
"""
61
Multiple binary choices (0 or 1 for each element).
62
63
Args:
64
n: Number of binary elements (int or array-like for shape)
65
seed: Random number generator seed
66
"""
67
68
def __init__(self, n: NDArray[np.integer[Any]] | Sequence[int] | int,
69
seed: int | np.random.Generator | None = None):
70
pass
71
72
class Text(Space):
73
"""
74
Space of text strings with character set and length constraints.
75
76
Args:
77
max_length: Maximum length of text strings
78
min_length: Minimum length of text strings (default: 1, keyword-only)
79
charset: Set of allowed characters (default: alphanumeric)
80
seed: Random number generator seed
81
"""
82
83
def __init__(self, max_length: int, *, min_length: int = 1,
84
charset: frozenset[str] | str = alphanumeric,
85
seed: int | np.random.Generator | None = None):
86
pass
87
```
88
89
### Composite Spaces
90
91
Spaces that combine multiple sub-spaces.
92
93
```python { .api }
94
class Dict(Space):
95
"""
96
Dictionary of named spaces.
97
98
Args:
99
spaces: Dictionary mapping names to Space objects or None
100
seed: Random number generator seed
101
**spaces_kwargs: Spaces as keyword arguments
102
"""
103
104
def __init__(self, spaces: None | dict[str, Space] | Sequence[tuple[str, Space]] = None,
105
seed: dict | int | np.random.Generator | None = None,
106
**spaces_kwargs: Space):
107
pass
108
109
class Tuple(Space):
110
"""
111
Tuple of spaces.
112
113
Args:
114
spaces: Tuple or list of Space objects
115
seed: Random number generator seed
116
"""
117
118
def __init__(self, spaces: Sequence[Space[Any]],
119
seed: int | np.random.Generator | None = None):
120
pass
121
122
class Sequence(Space):
123
"""
124
Variable-length sequence of elements from the same space.
125
126
Args:
127
space: The space of individual elements
128
seed: Random number generator seed
129
"""
130
131
def __init__(self, space: Space[Any],
132
seed: int | np.random.Generator | None = None):
133
pass
134
135
class OneOf(Space):
136
"""
137
One of multiple possible spaces (union type).
138
139
Args:
140
spaces: Sequence of Space objects
141
seed: Random number generator seed
142
"""
143
144
def __init__(self, spaces: Sequence[Space[Any]],
145
seed: int | np.random.Generator | None = None):
146
pass
147
```
148
149
### Graph Space
150
151
Specialized space for graph-structured data.
152
153
```python { .api }
154
class Graph(Space):
155
"""
156
Graph space with nodes and edges.
157
158
Args:
159
node_space: Space for node features (Box or Discrete)
160
edge_space: Space for edge features (Box, Discrete, or None)
161
seed: Random number generator seed
162
"""
163
164
def __init__(self, node_space: Box | Discrete, edge_space: None | Box | Discrete,
165
seed: int | np.random.Generator | None = None):
166
pass
167
168
class GraphInstance:
169
"""
170
Instance of a graph space containing nodes and edges.
171
172
Attributes:
173
nodes: Node feature array
174
edges: Edge feature array
175
edge_links: Edge connectivity array
176
"""
177
178
nodes: NDArray[Any]
179
edges: NDArray[Any] | None
180
edge_links: NDArray[Any] | None
181
pass
182
```
183
184
### Space Utilities
185
186
Utility functions for working with spaces.
187
188
```python { .api }
189
def flatdim(space: Space[Any]) -> int:
190
"""
191
Get the flattened dimension of a space.
192
193
Args:
194
space: The space to flatten
195
196
Returns:
197
Total number of dimensions when flattened
198
"""
199
200
def flatten_space(space: Space[Any]) -> Box | Dict | Sequence | Tuple | Graph:
201
"""
202
Flatten a composite space into a Box space.
203
204
Args:
205
space: The space to flatten
206
207
Returns:
208
Flattened Box space
209
"""
210
211
def flatten(space: Space[T], x: T) -> FlatType:
212
"""
213
Flatten a sample from a space.
214
215
Args:
216
space: The space the sample belongs to
217
x: Sample to flatten
218
219
Returns:
220
Flattened sample as numpy array
221
"""
222
223
def unflatten(space: Space[T], x: FlatType) -> T:
224
"""
225
Unflatten a sample back to its original space structure.
226
227
Args:
228
space: The original space structure
229
x: Flattened sample
230
231
Returns:
232
Sample in original space format
233
"""
234
```
235
236
## Usage Examples
237
238
### Creating and Using Basic Spaces
239
240
```python
241
import gymnasium.spaces as spaces
242
import numpy as np
243
244
# Continuous space for positions
245
position_space = spaces.Box(low=-10.0, high=10.0, shape=(3,), dtype=np.float32)
246
position = position_space.sample() # Random 3D position
247
print(position_space.contains([0.0, 5.0, -2.0])) # True
248
249
# Discrete action space
250
action_space = spaces.Discrete(4) # 4 possible actions: 0, 1, 2, 3
251
action = action_space.sample() # Random action
252
253
# Multiple discrete choices
254
multi_discrete = spaces.MultiDiscrete([3, 2, 4]) # 3×2×4 = 24 combinations
255
sample = multi_discrete.sample() # e.g., [1, 0, 2]
256
257
# Binary choices
258
binary_space = spaces.MultiBinary(5) # 5 binary choices
259
binary_sample = binary_space.sample() # e.g., [0, 1, 1, 0, 1]
260
```
261
262
### Composite Spaces
263
264
```python
265
# Dictionary space for complex observations
266
observation_space = spaces.Dict({
267
'image': spaces.Box(low=0, high=255, shape=(64, 64, 3), dtype=np.uint8),
268
'position': spaces.Box(low=-1.0, high=1.0, shape=(2,), dtype=np.float32),
269
'inventory': spaces.MultiDiscrete([10, 5, 3]) # item counts
270
})
271
272
obs = observation_space.sample()
273
# obs = {
274
# 'image': array of shape (64, 64, 3),
275
# 'position': array of shape (2,),
276
# 'inventory': array of shape (3,)
277
# }
278
279
# Tuple space
280
tuple_space = spaces.Tuple((
281
spaces.Discrete(4),
282
spaces.Box(low=0, high=1, shape=(2,))
283
))
284
285
sample = tuple_space.sample() # (int, array)
286
```
287
288
### Working with Graph Spaces
289
290
```python
291
# Graph space for network environments
292
node_space = spaces.Box(low=0, high=1, shape=(4,)) # 4 features per node
293
edge_space = spaces.Box(low=0, high=1, shape=(2,)) # 2 features per edge
294
295
graph_space = spaces.Graph(node_space, edge_space)
296
graph_sample = graph_space.sample()
297
298
# Access graph components
299
nodes = graph_sample.nodes # Node feature matrix
300
edges = graph_sample.edges # Edge feature matrix
301
links = graph_sample.edge_links # Edge connectivity matrix
302
```
303
304
### Space Flattening
305
306
```python
307
from gymnasium.spaces.utils import flatten_space, flatten, unflatten
308
309
# Complex composite space
310
complex_space = spaces.Dict({
311
'vector': spaces.Box(low=0, high=1, shape=(3,)),
312
'discrete': spaces.Discrete(4)
313
})
314
315
# Flatten for ML algorithms that expect vectors
316
flat_space = flatten_space(complex_space) # Box space
317
print(flat_space.shape) # (4,) - 3 continuous + 1 discrete
318
319
# Flatten samples
320
sample = complex_space.sample()
321
flat_sample = flatten(complex_space, sample) # 1D numpy array
322
323
# Restore original structure
324
restored = unflatten(complex_space, flat_sample)
325
```