建立與註冊

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

建立先前使用 gymnasium.register() 註冊的環境或 EnvSpec。

若要尋找所有可用的環境，請使用 gymnasium.envs.registry.keys() 取得所有有效的 ID。

參數:

• id – 環境 ID 的字串或 EnvSpec。選擇性地，如果使用字串，則可以包含要匯入的模組，例如 'module:Env-v0'。這相當於先匯入模組以註冊環境，然後建立環境。

• max_episode_steps – Episode 的最大長度，可以覆寫已註冊的 EnvSpec max_episode_steps，其值會傳遞至 gymnasium.wrappers.TimeLimit。使用 max_episode_steps=-1 將不會對環境套用封裝器。

• disable_env_checker – 是否新增 gymnasium.wrappers.PassiveEnvChecker，None 將預設為 EnvSpec disable_env_checker 值，否則將使用此值。

• kwargs – 傳遞至環境建構子的其他引數。

返回值:

已套用封裝器的環境實例。

拋出:

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) → gym.vector.VectorEnv

根據給定的 ID 建立向量環境。

若要尋找所有可用的環境，請使用 gymnasium.pprint_registry() 或 gymnasium.registry.keys() 取得所有有效的 ID。我們將向量環境稱為向量化器，而將被向量化的環境稱為基礎或向量化環境 (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)

在 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

從 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

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

注意

所有引數均為僅限關鍵字

參數:

• print_registry – 要列印的環境註冊表。預設為 registry

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

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

• disable_print – 是否傳回所有命名空間和環境 ID 的字串，或將字串列印到控制台。

核心變數

class gymnasium.envs.registration.EnvSpec(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, kwargs: dict = <factory>, additional_wrappers: tuple[WrapperSpec, ...] = <factory>, vector_entry_point: VectorEnvCreator | str | None = None)

用於使用 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)

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

• 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

根據名稱以及（可選的）版本和命名空間，取得完整的環境 ID。為 parse_env_id() 的反向操作。

參數:

• ns – 環境命名空間

• name – 環境名稱

• version – 環境版本

返回值:

環境 ID

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

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

參數:

env_id – 要解析的環境 ID

返回值:

環境命名空間、環境名稱和版本號碼的元組

拋出:

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

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

在註冊表中，根據命名空間和名稱尋找環境的最高註冊版本。

參數:

• ns – 環境命名空間

• name – 環境名稱 (ID)

返回值:

具有相符命名空間和名稱的環境的最高版本，否則返回 ``None``。

gymnasium.envs.registration.namespace(ns: str)

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

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

載入具有 "(import path):(environment name)" 樣式名稱的環境，並返回環境創建函數，通常為環境類別型別。

參數:

name – 環境名稱

返回值:

給定環境名稱的環境建構子。