制作与注册¶

Gymnasium 允许用户通过 :meth:gymnasium.make 函数自动加载预先包装了几个重要包装器的环境。为此，环境必须先通过 :meth:gymnasium.register 注册。要获取已注册环境的规范，请使用 :meth:gymnasium.spec，要打印整个注册表，请使用 :meth:gymnasium.pprint_registry。

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

创建一个先前通过 :meth:gymnasium.register 注册的环境或一个 :class:EnvSpec。

要查找所有可用的环境，请使用 gymnasium.envs.registry.keys() 获取所有有效的ID。

参数:

id – 环境ID的字符串或一个 :class:EnvSpec。如果使用字符串，可以选择包含一个要导入的模块，例如 'module:Env-v0'。这相当于首先导入模块以注册环境，然后创建环境。
max_episode_steps – 一个回合的最大长度，可以用传递给 :class:gymnasium.wrappers.TimeLimit 的值覆盖已注册的 :class:EnvSpec max_episode_steps。使用 max_episode_steps=-1 将不会对环境应用该包装器。
disable_env_checker – 如果添加 :class:gymnasium.wrappers.PassiveEnvChecker，None 将默认使用 :class:EnvSpec 的 disable_env_checker 值，否则将使用此值。
kwargs – 传递给环境构造函数的额外参数。

返回:

应用了包装的环境实例。

抛出:

Error – 如果 id 在 :attr:注册表 中不存在

变更日志：: v1.0.0 - autoreset 和 apply_api_compatibility 已被移除

根据给定的ID创建一个向量环境。

要查找所有可用的环境，请使用 :func:gymnasium.pprint_registry 或 gymnasium.registry.keys() 获取所有有效的ID。我们将向量化环境称为向量化器，而被向量化的环境称为基础或向量化环境（vectorizor(vectorized env)）。

参数:

id – 环境的名称。可选地，可以包含一个要导入的模块，例如 ‘module:Env-v0’
num_envs – 要创建的环境数量
vectorization_mode – 使用的向量化方法，默认为 None，以便如果环境ID的规范中有一个 vector_entry_point（非 None），则首先使用它，否则默认使用 sync 以使用 :class:gymnasium.vector.SyncVectorEnv。有效模式为 "async"、"sync" 或 "vector_entry_point"。建议使用 :class: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 与 :meth:gymnasium.make 一起使用，其中 entry_point 是一个用于创建环境的字符串或可调用对象。

id 参数对应于环境的名称，语法如下：[namespace/](env_name)[-v(version)]，其中 namespace 和 -v(version) 是可选的。

它接受任意的关键字参数，这些参数会被传递给 :class:EnvSpec 的 kwargs 参数。

参数:

id – 环境 ID
entry_point – 创建环境的入口点
reward_threshold – 对于一个智能体来说，被认为已经学会环境的奖励阈值
nondeterministic – 如果环境是非确定性的（即使知道初始种子和所有动作，也无法达到相同的状态）
max_episode_steps – 在截断之前最大的回合步数。如果值不为 None，则由 :class:gymnasium.wrappers.TimeLimit 包装器使用。
order_enforce – 如果启用顺序执行包装器以确保用户按正确顺序运行函数。如果 True，则将 :class:gymnasium.wrappers.OrderEnforcing 应用于环境。
disable_env_checker – 如果禁用 :class:gymnasium.wrappers.PassiveEnvChecker 到环境中。
additional_wrappers – 应用环境的附加包装器。
vector_entry_point – 创建向量环境的入口点
kwargs – 在初始化时传递给环境构造函数的任意关键字参数。

变更日志：: v1.0.0 - autoreset 和 apply_api_compatibility 参数已被移除

gymnasium.spec(env_id: str) → EnvSpec[源代码]¶

从 :attr:registry 中获取环境 id 的 :class:EnvSpec。

参数:: env_id – 环境id的预期格式为 [(命名空间)/]id[-v(版本)]
返回:: 如果存在的环境规范
抛出:: 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[源代码]¶

打印 :attr:注册表 中的所有环境。

备注

所有参数均为仅关键字参数

参数:

print_registry – 要打印的环境注册表。默认情况下，:attr:注册表
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)[源代码]¶

用于创建环境的规范 :meth:gymnasium.make。

id：用于通过 :meth:gymnasium.make 创建环境的字符串
entry_point：环境位置的字符串，(导入路径):(环境名称) 或一个创建环境的函数。
reward_threshold: 完成环境所需的奖励阈值。
不确定性：如果一个环境的观察不能在相同的初始状态、随机数生成器状态和动作下重复。
max_episode_steps: 环境在被截断前可以采取的最大步数
order_enforce: 是否在 :meth:gymnasium.Env.step 和 :meth:gymnasium.Env.render 函数之前强制执行 :meth:gymnasium.Env.reset 的顺序
disable_env_checker: 是否在 :meth:gymnasium.make 中禁用环境检查器包装，默认为 False（运行环境检查器）
kwargs: 在初始化期间传递给环境的额外关键字参数
additional_wrappers: 应用于环境的额外包装器元组 (WrapperSpec)
vector_entry_point：要创建的向量化环境的位置

变更日志：: v1.0.0 - 自动重置属性已移除

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 的全局注册表，环境规范通过 :meth:gymnasium.register 存储在此处，并且 :meth:gymnasium.make 用于从此处创建环境。

gymnasium.envs.registration.current_namespace¶: 在创建或注册环境时的当前命名空间。默认情况下这是 None ，但通过 :meth:namespace 可以修改为自动设置环境ID的命名空间。

附加功能¶

gymnasium.envs.registration.get_env_id(ns: str | None, name: str, version: int | None) → str[源代码]¶

给定名称和（可选的）版本和命名空间，获取完整的env ID。这是 :meth: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[源代码]¶

加载一个环境，其名称格式为 "(导入路径):(环境名称)"，并返回环境创建函数，通常是环境类类型。

参数:: name – 环境名称
返回:: 给定环境名称的环境构造函数。