Fundamental Spaces¶
- class gymnasium.spaces.Box(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)[source]¶
A (possibly unbounded) box in \(\mathbb{R}^n\).
Specifically, a Box represents the Cartesian product of n closed intervals. Each interval has the form of one of \([a, b]\), \((-\infty, b]\), \([a, \infty)\), or \((-\infty, \infty)\).
There are two common use cases:
Identical bound for each dimension:
>>> Box(low=-1.0, high=2.0, shape=(3, 4), dtype=np.float32) Box(-1.0, 2.0, (3, 4), float32)
Independent bound for each dimension:
>>> Box(low=np.array([-1.0, -2.0]), high=np.array([2.0, 4.0]), dtype=np.float32) Box([-1. -2.], [2. 4.], (2,), float32)
- Parameters:
low (SupportsFloat | np.ndarray) – Lower bounds of the intervals. If integer, must be at least
-2**63
.high (SupportsFloat | np.ndarray]) – Upper bounds of the intervals. If integer, must be at most
2**63 - 2
.shape (Optional[Sequence[int]]) – The shape is inferred from the shape of low or high np.ndarray`s with `low and high scalars defaulting to a shape of (1,)
dtype – The dtype of the elements of the space. If this is an integer type, the
Box
is essentially a discrete space.seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.
- Raises:
ValueError – If no shape information is provided (shape is None, low is None and high is None) then a value error is raised.
- sample(mask: None = None) ndarray[Any, dtype[Any]] [source]¶
Generates a single random sample inside the Box.
In creating a sample of the box, each coordinate is sampled (independently) from a distribution that is chosen according to the form of the interval:
\([a, b]\) : uniform distribution
\([a, \infty)\) : shifted exponential distribution
\((-\infty, b]\) : shifted negative exponential distribution
\((-\infty, \infty)\) : normal distribution
- Parameters:
mask – A mask for sampling values from the Box space, currently unsupported.
- Returns:
A sampled value from the Box
- seed(seed: int | None = None) int | list[int] | dict[str, int] ¶
Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.
- Parameters:
seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.
- Returns:
The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.
- class gymnasium.spaces.Discrete(n: int | np.integer[Any], seed: int | np.random.Generator | None = None, start: int | np.integer[Any] = 0)[source]¶
A space consisting of finitely many elements.
This class represents a finite subset of integers, more specifically a set of the form \(\{ a, a+1, \dots, a+n-1 \}\).
Example
>>> from gymnasium.spaces import Discrete >>> observation_space = Discrete(2, seed=42) # {0, 1} >>> observation_space.sample() np.int64(0) >>> observation_space = Discrete(3, start=-1, seed=42) # {-1, 0, 1} >>> observation_space.sample() np.int64(-1)
- Parameters:
n (int) – The number of elements of this space.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the
Dict
space.start (int) – The smallest element of this space.
- sample(mask: MaskNDArray | None = None) np.int64 [source]¶
Generates a single random sample from this space.
A sample will be chosen uniformly at random with the mask if provided
- Parameters:
mask – An optional mask for if an action can be selected. Expected np.ndarray of shape
(n,)
and dtypenp.int8
where1
represents valid actions and0
invalid / infeasible actions. If there are no possible actions (i.e.np.all(mask == 0)
) thenspace.start
will be returned.- Returns:
A sampled integer from the space
- seed(seed: int | None = None) int | list[int] | dict[str, int] ¶
Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.
- Parameters:
seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.
- Returns:
The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.
- class gymnasium.spaces.MultiBinary(n: NDArray[np.integer[Any]] | Sequence[int] | int, seed: int | np.random.Generator | None = None)[source]¶
An n-shape binary space.
Elements of this space are binary arrays of a shape that is fixed during construction.
Example
>>> from gymnasium.spaces import MultiBinary >>> observation_space = MultiBinary(5, seed=42) >>> observation_space.sample() array([1, 0, 1, 0, 1], dtype=int8) >>> observation_space = MultiBinary([3, 2], seed=42) >>> observation_space.sample() array([[1, 0], [1, 0], [1, 1]], dtype=int8)
- Parameters:
n – This will fix the shape of elements of the space. It can either be an integer (if the space is flat) or some sort of sequence (tuple, list or np.ndarray) if there are multiple axes.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.
- sample(mask: MaskNDArray | None = None) NDArray[np.int8] [source]¶
Generates a single random sample from this space.
A sample is drawn by independent, fair coin tosses (one toss per binary variable of the space).
- Parameters:
mask – An optional np.ndarray to mask samples with expected shape of
space.shape
. Formask == 0
then the samples will be0
andmask == 1` then random samples will be generated. The expected mask shape is the space shape and mask dtype is ``np.int8
.- Returns:
Sampled values from space
- seed(seed: int | None = None) int | list[int] | dict[str, int] ¶
Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.
- Parameters:
seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.
- Returns:
The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.
- class gymnasium.spaces.MultiDiscrete(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)[source]¶
This represents the cartesian product of arbitrary
Discrete
spaces.It is useful to represent game controllers or keyboards where each key can be represented as a discrete action space.
Note
Some environment wrappers assume a value of 0 always represents the NOOP action.
e.g. Nintendo Game Controller - Can be conceptualized as 3 discrete action spaces:
Arrow Keys: Discrete 5 - NOOP[0], UP[1], RIGHT[2], DOWN[3], LEFT[4] - params: min: 0, max: 4
Button A: Discrete 2 - NOOP[0], Pressed[1] - params: min: 0, max: 1
Button B: Discrete 2 - NOOP[0], Pressed[1] - params: min: 0, max: 1
It can be initialized as
MultiDiscrete([ 5, 2, 2 ])
such that a sample might bearray([3, 1, 0])
.Although this feature is rarely used,
MultiDiscrete
spaces may also have several axes ifnvec
has several axes:Example
>>> from gymnasium.spaces import MultiDiscrete >>> import numpy as np >>> observation_space = MultiDiscrete(np.array([[1, 2], [3, 4]]), seed=42) >>> observation_space.sample() array([[0, 0], [2, 2]])
- Parameters:
nvec – vector of counts of each categorical variable. This will usually be a list of integers. However, you may also pass a more complicated numpy array if you’d like the space to have several axes.
dtype – This should be some kind of integer type.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.
start – Optionally, the starting value the element of each class will take (defaults to 0).
- sample(mask: tuple[MaskNDArray, ...] | None = None) NDArray[np.integer[Any]] [source]¶
Generates a single random sample this space.
- Parameters:
mask – An optional mask for multi-discrete, expects tuples with a
np.ndarray
mask in the position of each action with shape(n,)
wheren
is the number of actions anddtype=np.int8
. Onlymask values == 1
are possible to sample unless all mask values for an action are0
then the default actionself.start
(the smallest element) is sampled.- Returns:
An ``np.ndarray`` of :meth:`Space.shape`
- seed(seed: int | None = None) int | list[int] | dict[str, int] ¶
Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.
- Parameters:
seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.
- Returns:
The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.
- class gymnasium.spaces.Text(max_length: int, *, min_length: int = 1, charset: frozenset[str] | str = alphanumeric, seed: int | np.random.Generator | None = None)[source]¶
A space representing a string comprised of characters from a given charset.
Example
>>> from gymnasium.spaces import Text >>> # {"", "B5", "hello", ...} >>> Text(5) Text(1, 5, charset=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz) >>> # {"0", "42", "0123456789", ...} >>> import string >>> Text(min_length = 1, ... max_length = 10, ... charset = string.digits) Text(1, 10, charset=0123456789)
- Parameters:
min_length (int) – Minimum text length (in characters). Defaults to 1 to prevent empty strings.
max_length (int) – Maximum text length (in characters).
charset (Union[set], str) – Character set, defaults to the lower and upper english alphabet plus latin digits.
seed – The seed for sampling from the space.
- sample(mask: None | tuple[int | None, NDArray[np.int8] | None] = None) str [source]¶
Generates a single random sample from this space with by default a random length between
min_length
andmax_length
and sampled from thecharset
.- Parameters:
mask – An optional tuples of length and mask for the text. The length is expected to be between the
min_length
andmax_length
otherwise a random integer betweenmin_length
andmax_length
is selected. For the mask, we expect a numpy array of length of the charset passed withdtype == np.int8
. If the charlist mask is all zero then an empty string is returned no matter themin_length
- Returns:
A sampled string from the space
- seed(seed: int | None = None) int | list[int] | dict[str, int] ¶
Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.
- Parameters:
seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.
- Returns:
The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.