Utils#

Visualization#

Save Rendering Videos#

Old to New Step API Compatibility#

gym.utils.step_api_compatibility.convert_to_terminated_truncated_step_api(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]]], is_vector_env=False) → Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]]#

Function to transform step returns to new step API irrespective of input API.

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

gym.utils.step_api_compatibility.convert_to_done_step_api(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]], is_vector_env: bool = False) → Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]#

Function to transform step returns to old step API irrespective of input API.

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

gym.utils.step_api_compatibility.step_api_compatibility(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]], output_truncation_bool: bool = True, is_vector_env: bool = False) → Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]]#

Function to transform step returns to the API specified by output_truncation_bool bool.

Done (old) step API refers to step() method returning (observation, reward, done, info) Terminated Truncated (new) step API refers to step() method returning (observation, reward, terminated, truncated, info) (Refer to docs for details on the API change)

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • output_truncation_bool (bool) – Whether the output should return two booleans (new API) or one (old) (True by default)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

Returns:

step_returns (tuple) – Depending on output_truncation_bool bool, it can return (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

Examples

This function can be used to ensure compatibility in step interfaces with conflicting API. Eg. if env is written in old API,

wrapper is written in new API, and the final step output is desired to be in old API.

>>> obs, rew, done, info = step_api_compatibility(env.step(action), output_truncation_bool=False)
>>> obs, rew, terminated, truncated, info = step_api_compatibility(env.step(action), output_truncation_bool=True)
>>> observations, rewards, dones, infos = step_api_compatibility(vec_env.step(action), is_vector_env=True)

Seeding#

gym.utils.seeding.np_random(seed: Optional[int] = None) → Tuple[Generator, Any]#

Generates a random number generator from the seed and returns the Generator and seed.

Parameters:

seed – The seed used to create the generator

Returns:

The generator and resulting seed

Raises:

Error – Seed must be a non-negative integer or omitted

Environment Checking#

Invasive#

gym.utils.env_checker.data_equivalence(data_1, data_2) → bool#

Assert equality between data 1 and 2, i.e observations, actions, info.

Parameters:

  • data_1 – data structure 1

  • data_2 – data structure 2

Returns:

If observation 1 and 2 are equivalent

gym.utils.env_checker.check_reset_seed(env: Env)#

Check that the environment can be reset with a seed.

Parameters:

env – The environment to check

Raises:

AssertionError – The environment cannot be reset with a random seed, even though seed or kwargs appear in the signature.

gym.utils.env_checker.check_reset_options(env: Env)#

Check that the environment can be reset with options.

Parameters:

env – The environment to check

Raises:

AssertionError – The environment cannot be reset with options, even though options or kwargs appear in the signature.

gym.utils.env_checker.check_reset_return_info_deprecation(env: Env)#

Makes sure support for deprecated return_info argument is dropped.

Parameters:

env – The environment to check

Raises:

UserWarning –

gym.utils.env_checker.check_seed_deprecation(env: Env)#

Makes sure support for deprecated function seed is dropped.

Parameters:

env – The environment to check

Raises:

UserWarning –

gym.utils.env_checker.check_reset_return_type(env: Env)#

Checks that reset() correctly returns a tuple of the form (obs , info).

Parameters:

env – The environment to check

Raises:

AssertionError depending on spec violation –

gym.utils.env_checker.check_space_limit(space, space_type: str)#

Check the space limit for only the Box space as a test that only runs as part of check_env.

gym.utils.env_checker.check_env(env: Env, warn: Optional[bool] = None, skip_render_check: bool = False)#

Check that an environment follows Gym API.

This is an invasive function that calls the environment’s reset and step.

This is particularly useful when using a custom environment. Please take a look at https://www.gymlibrary.dev/content/environment_creation/ for more information about the API.

Parameters:

  • env – The Gym environment that will be checked

  • warn – Ignored

  • skip_render_check – Whether to skip the checks for the render method. True by default (useful for the CI)

Passive#

gym.utils.passive_env_checker.check_space(space: Space, space_type: str, check_box_space_fn: Callable[[Box], None])#

A passive check of the environment action space that should not affect the environment.

gym.utils.passive_env_checker.check_obs(obs, observation_space: Space, method_name: str)#

Check that the observation returned by the environment correspond to the declared one.

Parameters:

  • obs – The observation to check

  • observation_space – The observation space of the observation

  • method_name – The method name that generated the observation

gym.utils.passive_env_checker.env_reset_passive_checker(env, **kwargs)#

A passive check of the Env.reset function investigating the returning reset information and returning the data unchanged.

gym.utils.passive_env_checker.env_step_passive_checker(env, action)#

A passive check for the environment step, investigating the returning data then returning the data unchanged.

gym.utils.passive_env_checker.env_render_passive_checker(env, *args, **kwargs)#

A passive check of the Env.render that the declared render modes/fps in the metadata of the environment is declared.