Register and Make
Gymnasium allows users to automatically load environments, pre-wrapped with several important wrappers through the gymnasium.make() function. To do this, the environment must be registered prior with gymnasium.register(). To get the environment specifications for a registered environment, use gymnasium.spec() and to print the whole registry, use gymnasium.pprint_registry().Gymnasium允许用户自动加载环境,通过Gymnasim.make()函数用几个重要的包装器进行预包装
gymnasium.make(id: str | EnvSpec, max_episode_steps: int | None = None, autoreset: bool | None = None, apply_api_compatibility: bool | None = None, disable_env_checker: bool | None = None, **kwargs: Any) → Env
Creates an environment previously registered with gymnasium.register() or a EnvSpec
.
To find all available environments use gymnasium.envs.registry.keys()
for all valid ids.
PARAMETERS:
-
id – A string for the environment id or a
EnvSpec
. Optionally if using a string, a module to import can be included, e.g.'module:Env-v0'
. This is equivalent to importing the module first to register the environment followed by making the environment.环境id或环境规范的字符串。(可选)如果使用字符串,则可以包括要导入的模块,例如“module:Env-v0”。这相当于先导入模块以注册环境,然后创建环境 -
max_episode_steps – Maximum length of an episode, can override the registered
EnvSpec
max_episode_steps
. The value is used by gymnasium.wrappers.TimeLimit. -
autoreset – Whether to automatically reset the environment after each episode (gymnasium.wrappers.AutoResetWrapper).
-
apply_api_compatibility – Whether to wrap the environment with the gymnasium.wrappers.StepAPICompatibility wrapper that converts the environment step from a done bool to return termination and truncation bools. By default, the argument is None in which the
EnvSpec
apply_api_compatibility
is used, otherwise this variable is used in favor. -
disable_env_checker – If to add gymnasium.wrappers.PassiveEnvChecker,
None
will default to theEnvSpec
disable_env_checker
value otherwise use this value will be used. -
kwargs – Additional arguments to pass to the environment constructor.
RETURNS:
An instance of the environment with wrappers applied.应用了包装器的环境实例。
RAISES:
Error – If the id
doesn’t exist in the registry
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, autoreset: bool = False, disable_env_checker: bool = False, apply_api_compatibility: bool = False, additional_wrappers: tuple[WrapperSpec, ...] = (), vector_entry_point: VectorEnvCreator | str | None = None, **kwargs: Any)
Registers an environment in gymnasium with an id
to use with gymnasium.make() with the entry_point
being a string or callable for creating the environment.
在gym中注册一个带有id的环境,以便与体育馆.make()一起使用,entry_point是一个字符串或可调用以创建环境。
The id
parameter corresponds to the name of the environment, with the syntax as follows: [namespace/](env_name)[-v(version)]
where namespace
and -v(version)
is optional.
It takes arbitrary keyword arguments, which are passed to the EnvSpec
kwargs
parameter.
PARAMETERS:
-
id – The environment id
-
entry_point – The entry point for creating the environment
-
reward_threshold – The reward threshold considered for an agent to have learnt the environment
-
nondeterministic – If the environment is nondeterministic (even with knowledge of the initial seed and all actions, the same state cannot be reached)如果环境是不确定的(即使知道初始种子和所有操作,也无法达到相同的状态)
-
max_episode_steps – The maximum number of episodes steps before truncation. Used by the gymnasium.wrappers.TimeLimit wrapper if not
None
. -
order_enforce – If to enable the order enforcer wrapper to ensure users run functions in the correct order. If
True
, then the gymnasium.wrappers.OrderEnforcing is applied to the environment. -
autoreset – If to add the gymnasium.wrappers.AutoResetWrapper such that on
(terminated or truncated) is True
, gymnasium.Env.reset() is called. -
disable_env_checker – If to disable the gymnasium.wrappers.PassiveEnvChecker to the environment.
-
apply_api_compatibility – If to apply the gymnasium.wrappers.StepAPICompatibility wrapper to the environment. Use if the environment is implemented in the gym v0.21 environment API.
-
additional_wrappers – Additional wrappers to apply the environment.
-
vector_entry_point – The entry point for creating the vector environment
-
**kwargs – arbitrary keyword arguments which are passed to the environment constructor on initialisation.
gymnasium.spec(env_id: str) → EnvSpec
Retrieve the EnvSpec
for the environment id from the registry
.
PARAMETERS:
env_id – The environment id with the expected format of [(namespace)/]id[-v(version)]
RETURNS:
The environment spec if it exists
RAISES:
Error – If the environment id doesn’t exist
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
Pretty prints all environments in the registry
.
Note
All arguments are keyword only
PARAMETERS:
-
print_registry – Environment registry to be printed. By default,
registry
-
num_cols – Number of columns to arrange environments in, for display.
-
exclude_namespaces – A list of namespaces to be excluded from printing. Helpful if only ALE environments are wanted.
-
disable_print – Whether to return a string of all the namespaces and environment IDs or to print the string to console.
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, autoreset: bool = False, disable_env_checker: bool = False, apply_api_compatibility: bool = False, kwargs: dict = <factory>, additional_wrappers: tuple[WrapperSpec, ...] = <factory>, vector_entry_point: VectorEnvCreator | str | None = None)
A specification for creating environments with gymnasium.make().
-
id: The string used to create the environment with gymnasium.make()
-
entry_point: A string for the environment location,
(import path):(environment name)
or a function that creates the environment. -
reward_threshold: The reward threshold for completing the environment.
-
nondeterministic: If the observation of an environment cannot be repeated with the same initial state, random number generator state and actions.
-
max_episode_steps: The max number of steps that the environment can take before truncation
-
order_enforce: If to enforce the order of gymnasium.Env.reset() before gymnasium.Env.step() and gymnasium.Env.render() functions
-
autoreset: If to automatically reset the environment on episode end
-
disable_env_checker: If to disable the environment checker wrapper in gymnasium.make(), by default False (runs the environment checker)
-
kwargs: Additional keyword arguments passed to the environment during initialisation
-
additional_wrappers: A tuple of additional wrappers applied to the environment (WrapperSpec)
-
vector_entry_point: The location of the vectorized environment to create from
gymnasium.envs.registration.registry
The Global registry for gymnasium which is where environment specifications are stored by gymnasium.register() and from which gymnasium.make() is used to create environments.
gymnasium.envs.registration.current_namespace
The current namespace when creating or registering environments. This is by default None
by with namespace() this can be modified to automatically set the environment id namespace.
Additional functions
gymnasium.envs.registration.get_env_id(ns: str | None, name: str, version: int | None) → str
Get the full env ID given a name and (optional) version and namespace. Inverse of parse_env_id().
PARAMETERS:
-
ns – The environment namespace
-
name – The environment name
-
version – The environment version
RETURNS:
The environment id
gymnasium.envs.registration.parse_env_id(env_id: str) → tuple[str | None, str, int | None]
Parse environment ID string format - [namespace/](env-name)[-v(version)]
where the namespace and version are optional.
PARAMETERS:
env_id – The environment id to parse
RETURNS:
A tuple of environment namespace, environment name and version number
RAISES:
Error – If the environment id is not valid environment regex
gymnasium.envs.registration.find_highest_version(ns: str | None, name: str) → int | None
Finds the highest registered version of the environment given the namespace and name in the registry.
PARAMETERS:
-
ns – The environment namespace
-
name – The environment name (id)
RETURNS:
The highest version of an environment with matching namespace and name, otherwise ``None`` is returned.
gymnasium.envs.registration.namespace(ns: str)
Context manager for modifying the current namespace.
gymnasium.envs.registration.load_env_creator(name: str) → EnvCreator | VectorEnvCreator
Loads an environment with name of style "(import path):(environment name)"
and returns the environment creation function, normally the environment class type.
PARAMETERS:
name – The environment name
RETURNS:
The environment constructor for the given environment name.
gymnasium.envs.registration.load_plugin_envs(entry_point: str = 'gymnasium.envs')
Load modules (plugins) using the gymnasium entry points in order to register external module’s environments on import gymnasium
.
PARAMETERS:
entry_point – The string for the entry point.