基礎空間¶

在 \(\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` 的形狀推斷出來的，其中 `low` 和 `high` 標量預設為形狀 (1,)
dtype – 空間元素的 dtype。如果這是整數類型，則 Box 本質上是一個離散空間。
seed – （可選）您可以使用此參數為用於從空間中採樣的 RNG 設定種子。

引發：

ValueError – 如果未提供任何形狀資訊（shape 為 None，low 為 None 且 high 為 None），則會引發 ValueError。

sample(mask: None = None, probability: None = None) → ndarray[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) 以及（如果適用）子空間的 PRNG 設定種子。

參數：: seed – 空間的種子值。這會針對複合空間擴展，以接受多個值。如需更多詳細資訊，請參閱空間的文件。
返回：: 用於所有 PRNG 的種子值，對於複合空間，這可以是值組或字典。

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

檢查盒狀空間在某種意義上是否是有界的。

參數：: manner (*str*) – “both”、“below”、“above” 之一。
返回：: 如果空間是有界的
引發：: ValueError – 如果 `manner` 既不是 “both” 也不是 “below” 或 “above”

class gymnasium.spaces.Discrete(n: int | np.integer[Any], seed: int | np.random.Generator | None = None, start: int | np.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: MaskNDArray | None = None, probability: MaskNDArray | None = None) → np.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) 以及（如果適用）子空間的 PRNG 設定種子。

參數：: seed – 空間的種子值。這會針對複合空間擴展，以接受多個值。如需更多詳細資訊，請參閱空間的文件。
返回：: 用於所有 PRNG 的種子值，對於複合空間，這可以是值組或字典。

class gymnasium.spaces.MultiBinary(n: NDArray[np.integer[Any]] | Sequence[int] | int, seed: int | np.random.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: MaskNDArray | None = None, probability: MaskNDArray | None = None) → NDArray[np.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) 以及（如果適用）子空間的 PRNG 設定種子。

參數：: seed – 空間的種子值。這會針對複合空間擴展，以接受多個值。如需更多詳細資訊，請參閱空間的文件。
返回：: 用於所有 PRNG 的種子值，對於複合空間，這可以是值組或字典。

這代表任意 Discrete 空間的笛卡爾積。

它可用於表示遊戲控制器或鍵盤，其中每個按鍵都可以表示為離散動作空間。

注意

某些環境封裝器假設值 0 始終代表 NOOP 動作。

例如，任天堂遊戲控制器 – 可以概念化為 3 個離散動作空間

方向鍵：離散 5 – NOOP[0]、上[1]、右[2]、下[3]、左[4] – 參數：最小值：0，最大值：4
按鈕 A：離散 2 – NOOP[0]、按下[1] – 參數：最小值：0，最大值：1
按鈕 B：離散 2 – NOOP[0]、按下[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[MaskNDArray, ...] | None = None, probability: tuple[MaskNDArray, ...] | None = None) → NDArray[np.integer[Any]][source]¶

從此空間生成單個隨機樣本。

參數：

mask – 多重離散的可選遮罩，預期元組在每個動作的位置都有一個 np.ndarray 遮罩，形狀為 (n,)，其中 n 是動作的數量，且 dtype=np.int8。只有 mask values == 1 才有可能採樣，除非動作的所有遮罩值均為 0，否則將採樣預設動作 self.start（最小元素）。
probability – 多重離散的可選機率遮罩，預期元組在每個動作的位置都有一個 np.ndarray 機率遮罩，形狀為 (n,)，其中 n 是動作的數量，且 dtype=np.float64。只有 [0,1] 範圍內的機率遮罩值才有可能採樣，前提是所有值的總和為 1。

返回：

`:meth:`Space.shape` 的 ``np.ndarray``

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

為此空間的偽隨機數生成器 (PRNG) 以及（如果適用）子空間的 PRNG 設定種子。

參數：: seed – 空間的種子值。這會針對複合空間擴展，以接受多個值。如需更多詳細資訊，請參閱空間的文件。
返回：: 用於所有 PRNG 的種子值，對於複合空間，這可以是值組或字典。

class gymnasium.spaces.Text(max_length: int, *, min_length: int = 1, charset: frozenset[str] | str = alphanumeric, seed: int | np.random.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 陣列，其長度為傳遞的 charset 長度，且 dtype == np.int8。如果字元列表遮罩全為零，則無論 min_length 為何，都會返回空字串。
probability – 文本的可選長度和概率遮罩元組。長度預期介於 min_length 和 max_length 之間。否則，將選擇介於 min_length 和 max_length 之間的隨機整數。對於概率遮罩，我們預期一個 numpy 陣列，其長度為傳遞的 charset 長度，且 dtype == np.float64。概率遮罩的總和應為 1，否則會引發例外。

返回：

從空間採樣的字串

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

為此空間的偽隨機數生成器 (PRNG) 以及（如果適用）子空間的 PRNG 設定種子。

參數：: seed – 空間的種子值。這會針對複合空間擴展，以接受多個值。如需更多詳細資訊，請參閱空間的文件。
返回：: 用於所有 PRNG 的種子值，對於複合空間，這可以是值組或字典。