建立和註冊

Gymnasium 允許使用者透過 gymnasium.make() 函式自動載入預先封裝了多個重要封裝器的環境。為此，環境必須事先使用 gymnasium.register() 進行註冊。要獲取已註冊環境的規範，請使用 gymnasium.spec()；要列印整個登錄檔，請使用 gymnasium.pprint_registry()。

gymnasium.make(id: str | EnvSpec, max_episode_steps: int | None = None, disable_env_checker: bool | None = None, **kwargs: Any) → Env[source]

建立一個之前已透過 gymnasium.register() 或 `EnvSpec` 註冊的環境。

要查詢所有可用的環境，請使用 gymnasium.envs.registry.keys() 獲取所有有效 ID。

引數：
返回：

一個應用了封裝器的環境例項。

丟擲：

Error – 如果 `id` 在 `registry` 中不存在。

更新日誌

v1.0.0 - autoreset 和 apply_api_compatibility 已移除。

gymnasium.make_vec(id: str | EnvSpec, num_envs: int = 1, vectorization_mode: VectorizeMode | str | None = None, vector_kwargs: dict[str, Any] | None = None, wrappers: Sequence[Callable[[Env], Wrapper]] | None = None, **kwargs) → VectorEnv[source]

根據給定 ID 建立一個向量化環境。

要查詢所有可用的環境，請使用 gymnasium.pprint_registry() 或 gymnasium.registry.keys() 獲取所有有效 ID。我們將向量環境稱為向量化器（vectorizor），而被向量化的環境稱為基礎環境或向量化環境（vectorizor(vectorized env)）。

引數：

  • id – 環境的名稱。可選地，可以包含要匯入的模組，例如 ‘module:Env-v0’

  • num_envs – 要建立的環境數量。

  • vectorization_mode – 所使用的向量化方法，預設為 None，這樣如果環境 ID 的 `spec` 具有 vector_entry_point（非 None），則首先使用它，否則預設為 sync 以使用 gymnasium.vector.SyncVectorEnv。有效模式為 "async"、"sync" 或 "vector_entry_point"。建議使用 VectorizeMode 列舉而不是字串。

  • vector_kwargs – 傳遞給向量化器環境建構函式的附加引數，例如 SyncVectorEnv(..., **vector_kwargs)。

  • wrappers – 應用於基礎環境的封裝器函式序列。只能在 "sync" 或 "async" 模式下使用。

  • **kwargs – 傳遞給基礎環境建構函式的附加引數。

返回：

環境例項。

丟擲：

Error – 如果 `id` 不存在，則丟擲錯誤。

gymnasium.register(id: str, entry_point: EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, disable_env_checker: bool = False, additional_wrappers: tuple[WrapperSpec, ...] = (), vector_entry_point: VectorEnvCreator | str | None = None, kwargs: dict | None = None)[source]

在 Gymnasium 中註冊一個環境，其 id 可與 gymnasium.make() 配合使用，其中 entry_point 是一個用於建立環境的字串或可呼叫物件。

的 `id` 引數對應於環境的名稱，語法如下：[namespace/](env_name)[-v(version)]，其中 namespace 和 -v(version) 是可選的。

它接受任意關鍵字引數，這些引數將傳遞給 `EnvSpec` 的 kwargs 引數。

引數：

  • id – 環境 ID

  • entry_point – 建立環境的入口點。

  • reward_threshold – 智慧體被認為已學習環境的獎勵閾值。

  • nondeterministic – 如果環境是非確定性的（即使知道初始種子和所有動作，也無法達到相同的狀態）。

  • max_episode_steps – 截斷前的最大 episode 步數。如果不是 None，則由 gymnasium.wrappers.TimeLimit 封裝器使用。

  • order_enforce – 是否啟用順序強制封裝器，以確保使用者以正確的順序執行函式。如果為 True，則 gymnasium.wrappers.OrderEnforcing 將應用於環境。

  • disable_env_checker – 是否對環境停用 gymnasium.wrappers.PassiveEnvChecker。

  • additional_wrappers – 應用於環境的附加封裝器。

  • vector_entry_point – 建立向量環境的入口點。

  • kwargs – 任意關鍵字引數，在初始化時傳遞給環境建構函式。

更新日誌

v1.0.0 - autoreset 和 apply_api_compatibility 引數已移除。

gymnasium.spec(env_id: str) → EnvSpec[source]

從 registry 中檢索環境 ID 的 `EnvSpec`。

引數：

env_id – 環境 ID，其預期格式為 [(namespace)/]id[-v(version)]。

返回：

環境規範（如果存在）

丟擲：

Error – 如果環境 ID 不存在。

gymnasium.pprint_registry(print_registry: dict[str, EnvSpec] = registry, *, num_cols: int = 3, exclude_namespaces: list[str] | None = None, disable_print: bool = False) → str | None[source]

美觀地列印 registry 中的所有環境。

注意

所有引數都只接受關鍵字引數。

引數：

  • print_registry – 要列印的環境登錄檔。預設為 `registry`。

  • num_cols – 排列環境的列數，用於顯示。

  • exclude_namespaces – 要從列印中排除的名稱空間列表。如果只需要 ALE 環境，這會很有用。

  • disable_print – 是返回所有名稱空間和環境 ID 的字串，還是將字串列印到控制檯。

核心變數

class gymnasium.envs.registration.EnvSpec(id: str, entry_point: ~gymnasium.envs.registration.EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, disable_env_checker: bool = False, kwargs: dict = <factory>, additional_wrappers: tuple[~gymnasium.envs.registration.WrapperSpec, ...] = <factory>, vector_entry_point: ~gymnasium.envs.registration.VectorEnvCreator | str | None = None)[source]

使用 gymnasium.make() 建立環境的規範。

  • id：用於透過 gymnasium.make() 建立環境的字串。

  • entry_point：環境位置的字串，格式為 (import path):(environment name)，或一個建立環境的函式。

  • reward_threshold：完成環境的獎勵閾值。

  • nondeterministic：如果環境的觀測無法在相同的初始狀態、隨機數生成器狀態和動作下重複。

  • max_episode_steps：環境在截斷前可以採取的最大步數。

  • order_enforce：是否強制執行 gymnasium.Env.reset() 在 gymnasium.Env.step() 和 gymnasium.Env.render() 函式之前執行的順序。

  • disable_env_checker：是否在 gymnasium.make() 中停用環境檢查器封裝器，預設為 False（執行環境檢查器）。

  • kwargs：在初始化期間傳遞給環境的附加關鍵字引數。

  • additional_wrappers：應用於環境的附加封裝器（WrapperSpec）元組。

  • vector_entry_point：要建立向量化環境的位置。

更新日誌

v1.0.0 - Autoreset 屬性已移除。

class gymnasium.envs.registration.WrapperSpec(name: str, entry_point: str, kwargs: dict[str, Any] | None)[source]

用於記錄封裝器配置的規範。

  • name：封裝器的名稱。

  • entry_point：建立封裝器的位置。

  • kwargs：傳遞給封裝器的附加關鍵字引數。如果封裝器不繼承自 `EzPickle`，則此值為 None。

gymnasium.envs.registration.registry

Gymnasium 的全域性登錄檔，`gymnasium.register()` 在此儲存環境規範，並且 `gymnasium.make()` 用於從此登錄檔建立環境。

gymnasium.envs.registration.current_namespace

建立或註冊環境時的當前名稱空間。預設情況下為 None，但透過 namespace() 可以修改此值以自動設定環境 ID 名稱空間。

附加函式

gymnasium.envs.registration.get_env_id(ns: str | None, name: str, version: int | None) → str[source]

給定名稱和（可選）版本及名稱空間，獲取完整的環境 ID。它是 parse_env_id() 的逆操作。

引數：

  • ns – 環境名稱空間

  • name – 環境名稱

  • version – 環境版本

返回：

環境 ID

gymnasium.envs.registration.parse_env_id(env_id: str) → tuple[str | None, str, int | None][source]

解析環境 ID 字串格式 - [namespace/](env-name)[-v(version)]，其中名稱空間和版本是可選的。

引數：

env_id – 要解析的環境 ID

返回：

一個包含環境名稱空間、環境名稱和版本號的元組。

丟擲：

Error – 如果環境 ID 不是有效的環境正則表示式。

gymnasium.envs.registration.find_highest_version(ns: str | None, name: str) → int | None[source]

在登錄檔中，根據給定的名稱空間和名稱，查詢環境的最高註冊版本。

引數：

  • ns – 環境名稱空間

  • name – 環境名稱 (id)

返回：

具有匹配名稱空間和名稱的環境的最高版本，否則 ``None`` 將返回。

gymnasium.envs.registration.namespace(ns: str)[source]

用於修改當前名稱空間的上下文管理器。

gymnasium.envs.registration.load_env_creator(name: str) → EnvCreator | VectorEnvCreator[source]

載入一個名稱風格為 "(import path):(environment name)" 的環境，並返回環境建立函式，通常是環境類型別。

引數：

name – 環境名稱

返回：

給定環境名稱的環境建構函式。