基本空间¶

class gymnasium.spaces.Box(low: SupportsFloat | ndarray[tuple[Any, ...], dtype[Any]], high: SupportsFloat | ndarray[tuple[Any, ...], dtype[Any]], shape: Sequence[int] | None = None, dtype: type[floating[Any]] | type[integer[Any]] = np.float32, seed: int | Generator | None = None)[source]¶

一个 \(\mathbb{R}^n\) 中的（可能无界的）盒子。

具体来说，Box 表示 n 个闭区间的笛卡尔积。每个区间具有 \([a, b]\)、\((-\infty, b]\)、\([a, \infty)\) 或 \((-\infty, \infty)\) 的形式。

有两种常见的使用情况

每个维度相同的边界

>>> Box(low=-1.0, high=2.0, shape=(3, 4), dtype=np.float32)
Box(-1.0, 2.0, (3, 4), float32)

每个维度独立的边界

>>> 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)

参数:

low (SupportsFloat | np.ndarray) – 区间的下界。如果是整数，必须至少为 -2**63。
high (SupportsFloat | np.ndarray]) – 区间的上界。如果是整数，必须至多为 2**63 - 2。
shape (Optional[Sequence[int]]) – 形状从 low 或 high np.ndarray`s 的形状推断，其中 `low 和 high 标量默认为形状 (1,)
dtype – 空间元素的 dtype。如果这是整数类型，则 Box 本质上是一个离散空间。
seed – 可选参数，您可以使用此参数为用于从空间中采样的 RNG 设定种子。

抛出:

ValueError – 如果未提供形状信息（形状为 None，low 为 None，high 为 None），则抛出 ValueError。

sample(mask: None = None, probability: None = None) → ndarray[tuple[Any, ...], dtype[Any]][source]¶

在 Box 内部生成一个随机样本。

在创建 Box 样本时，每个坐标都根据区间的形式从选定的分布中独立采样。

\([a, b]\) : 均匀分布
\([a, \infty)\) : 移位指数分布
\((-\infty, b]\) : 移位负指数分布
\((-\infty, \infty)\) : 正态分布

参数:

mask – 用于从 Box 空间中采样值的掩码，当前不支持。
probability – 用于从 Box 空间中采样值的概率掩码，当前不支持。

返回:

从 Box 中采样的值

seed(seed: int | None = None) → int | list[int] | dict[str, int]¶

为此空间及其（如果适用）子空间的伪随机数生成器 (PRNG) 设定种子。

参数:: seed – 空间的种子值。对于复合空间，此参数会扩展以接受多个值。有关更多详细信息，请参阅空间的文档。
返回:: 用于所有 PRNG 的种子值，对于复合空间，这可以是值元组或字典。

is_bounded(manner: str = 'both') → bool[source]¶

检查 Box 是否在某种意义上是有界的。

参数:: manner (str) – "both"、"below" 或 "above" 之一。
返回:: 如果空间有界
抛出:: ValueError – 如果 manner 既不是 "both" 也不是 "below" 或 "above"

class gymnasium.spaces.Discrete(n: int | integer[Any], seed: int | Generator | None = None, start: int | integer[Any] = 0)[source]¶

由有限多个元素组成的空间。

此类别表示整数的有限子集，更具体地说，是形如 \(\{ a, a+1, \dots, a+n-1 \}\) 的集合。

示例

>>> 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)
>>> observation_space.sample(mask=np.array([0,0,1], dtype=np.int8))
np.int64(1)
>>> observation_space.sample(probability=np.array([0,0,1], dtype=np.float64))
np.int64(1)
>>> observation_space.sample(probability=np.array([0,0.3,0.7], dtype=np.float64))
np.int64(1)

参数:

n (int) – 此空间的元素数量。
seed – 可选参数，您可以使用此参数为用于从 Dict 空间中采样的 RNG 设定种子。
start (int) – 此空间的最小元素。

sample(mask: ndarray[tuple[Any, ...], dtype[int8]] | None = None, probability: ndarray[tuple[Any, ...], dtype[int8]] | None = None) → int64[source]¶

从此空间生成一个随机样本。

如果提供了掩码，样本将从均匀随机选择；如果提供了概率掩码，样本将根据指定的概率分布选择。

参数:

mask – 一个可选掩码，用于指示是否可以选择某个动作。期望形状为 (n,) 且 dtype 为 np.int8 的 np.ndarray，其中 1 表示有效动作，0 表示无效/不可行动作。如果没有可能的动作（即 np.all(mask == 0)），则返回 space.start。
probability – 一个可选的概率掩码，描述每个动作被选择的概率。期望形状为 (n,) 且 dtype 为 np.float64 的 np.ndarray，其中每个值都在 [0, 1] 范围内，并且所有值的总和为 1。如果值的总和不为 1，则会抛出异常。

返回:

从空间中采样的整数

seed(seed: int | None = None) → int | list[int] | dict[str, int]¶

为此空间及其（如果适用）子空间的伪随机数生成器 (PRNG) 设定种子。

参数:: seed – 空间的种子值。对于复合空间，此参数会扩展以接受多个值。有关更多详细信息，请参阅空间的文档。
返回:: 用于所有 PRNG 的种子值，对于复合空间，这可以是值元组或字典。

class gymnasium.spaces.MultiBinary(n: ndarray[tuple[Any, ...], dtype[integer[Any]]] | Sequence[int] | int, seed: int | Generator | None = None)[source]¶

一个 n 形的二进制空间。

此空间的元素是二进制数组，其形状在构造时固定。

示例

>>> 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)

参数:

n – 这将固定空间元素的形状。如果空间是扁平的，它可以是整数；如果有多个轴，它可以是某种序列（元组、列表或 np.ndarray）。
seed – 可选参数，您可以使用此参数为用于从空间中采样的 RNG 设定种子。

sample(mask: ndarray[tuple[Any, ...], dtype[int8]] | None = None, probability: ndarray[tuple[Any, ...], dtype[int8]] | None = None) → ndarray[tuple[Any, ...], dtype[int8]][source]¶

从此空间生成一个随机样本。

样本通过独立、公平的掷硬币（空间中每个二进制变量一次）生成。

参数:

mask – 一个可选的 np.ndarray，用于掩盖样本，期望形状为 space.shape。当 mask == 0 时，样本将为 0；当 mask == 1 时，样本将为 1。对于随机样本，使用掩码值 2。期望的掩码形状是空间形状，掩码 dtype 是 np.int8。
probability – 一个可选的 np.ndarray，用于掩盖样本，期望形状为 space.shape，其中每个元素表示对应样本元素为 1 的概率。期望的掩码形状是空间形状，掩码 dtype 是 np.float64。

返回:

从空间中采样的值

seed(seed: int | None = None) → int | list[int] | dict[str, int]¶

为此空间及其（如果适用）子空间的伪随机数生成器 (PRNG) 设定种子。

参数:: seed – 空间的种子值。对于复合空间，此参数会扩展以接受多个值。有关更多详细信息，请参阅空间的文档。
返回:: 用于所有 PRNG 的种子值，对于复合空间，这可以是值元组或字典。

这表示任意 Discrete 空间的笛卡尔积。

它对于表示游戏控制器或键盘非常有用，其中每个按键都可以表示为一个离散动作空间。

注意

一些环境包装器假设值 0 始终表示 NOOP 动作（无操作动作）。

例如：任天堂游戏控制器 - 可以被概念化为 3 个离散动作空间

方向键：离散 5 - NOOP[0]（无操作），UP[1]（上），RIGHT[2]（右），DOWN[3]（下），LEFT[4]（左） - 参数：最小：0，最大：4
A键：离散 2 - NOOP[0]（无操作），Pressed[1]（按下） - 参数：最小：0，最大：1
B键：离散 2 - NOOP[0]（无操作），Pressed[1]（按下） - 参数：最小：0，最大：1

它可以被初始化为 MultiDiscrete([ 5, 2, 2 ])，这样样本可能就是 array([3, 1, 0])。

尽管这个特性很少使用，但如果 nvec 包含多个轴，MultiDiscrete 空间也可能具有多个轴。

示例

>>> 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]])

参数:

nvec – 每个分类变量的计数向量。这通常是一个整数列表。但是，如果您希望空间具有多个轴，您也可以传递一个更复杂的 numpy 数组。
dtype – 这应该是一种整数类型。
seed – 可选参数，您可以使用此参数为用于从空间中采样的 RNG 设定种子。
start – 可选参数，每个类别的元素将采用的起始值（默认为 0）。

sample(mask: tuple[ndarray[tuple[Any, ...], dtype[int8]], ...] | None = None, probability: tuple[ndarray[tuple[Any, ...], dtype[int8]], ...] | None = None) → ndarray[tuple[Any, ...], dtype[integer[Any]]][source]¶

从此空间生成一个随机样本。

参数:

mask – 多离散空间的可选掩码，期望一个元组，其中每个动作位置都带有一个形状为 (n,) 的 np.ndarray 掩码，其中 n 是动作的数量，dtype=np.int8。只有 mask values == 1 的值才可能被采样，除非某个动作的所有掩码值都为 0，在这种情况下会采样默认动作 self.start（最小元素）。
probability – 多离散空间的可选概率掩码，期望一个元组，其中每个动作位置都带有一个形状为 (n,) 的 np.ndarray 概率掩码，其中 n 是动作的数量，dtype=np.float64。只要所有值的总和为 1，就只有 [0,1] 范围内的概率掩码值才可能被采样。

返回:

一个 np.ndarray 类型的 :meth:`Space.shape`

seed(seed: int | None = None) → int | list[int] | dict[str, int]¶

为此空间及其（如果适用）子空间的伪随机数生成器 (PRNG) 设定种子。

参数:: seed – 空间的种子值。对于复合空间，此参数会扩展以接受多个值。有关更多详细信息，请参阅空间的文档。
返回:: 用于所有 PRNG 的种子值，对于复合空间，这可以是值元组或字典。

class gymnasium.spaces.Text(max_length: int, *, min_length: int = 1, charset: frozenset[str] | str = alphanumeric, seed: int | Generator | None = None)[source]¶

一个表示由给定字符集中的字符组成的字符串的空间。

示例

>>> 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)

参数:

min_length (int) – 最小文本长度（字符数）。默认为 1，以防止空字符串。
max_length (int) – 最大文本长度（字符数）。
charset (Union[set], str) – 字符集，默认为英文字母大小写和拉丁数字。
seed – 从空间中采样时使用的种子。

从此空间生成一个随机样本，默认情况下长度在 min_length 和 max_length 之间随机选择，并从 charset 中采样字符。

参数:

mask – 文本长度和掩码的可选元组。长度期望介于 min_length 和 max_length 之间。否则，将选择 min_length 和 max_length 之间的随机整数。对于掩码，我们期望一个与传入字符集长度相同的 numpy 数组，且 dtype == np.int8。如果字符列表掩码全为零，则无论 min_length 是多少，都返回空字符串。
probability – 文本长度和概率掩码的可选元组。长度期望介于 min_length 和 max_length 之间。否则，将选择 min_length 和 max_length 之间的随机整数。对于概率掩码，我们期望一个与传入字符集长度相同的 numpy 数组，且 dtype == np.float64。概率掩码的总和应为 1，否则会抛出异常。

返回:

从空间中采样的字符串

seed(seed: int | None = None) → int | list[int] | dict[str, int]¶

为此空间及其（如果适用）子空间的伪随机数生成器 (PRNG) 设定种子。

参数:: seed – 空间的种子值。对于复合空间，此参数会扩展以接受多个值。有关更多详细信息，请参阅空间的文档。
返回:: 用于所有 PRNG 的种子值，对于复合空间，这可以是值元组或字典。