Table of Contents

Class Gymnasium

Namespace
Gym
Assembly
Gym.dll

Gymnasium's top-level module, import gymnasium as gym: Make(string, object?, long?, bool?), Spec(string), Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?), Registry, PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool) and RegisterEnvs(object?), re-exported from EnvRegistry as Python re-exports them from gymnasium.envs.registration, plus the app-wide human-mode viewer (DR-20).

public static class Gymnasium
Inheritance
Gymnasium
Inherited Members

Remarks

The built-in envs register their ids before Main runs: the Gym.NET.Environments package compiles a module initializer into a C# app that calls its Register() (DR-17). F# and Visual Basic apps call GymEnvironments.Register() themselves; setting the environment variable GYMNET_DISABLE_ENV_REGISTRATION turns the automatic registration off (DR-14).

In Gym.NET's own unit tests the namespace Gym.Tests.Gymnasium hides this class, so they import it with global using static Gym.Gymnasium; and call Make("CartPole-v1"), as from gymnasium import make reads.

Reference: gymnasium/__init__.py.

Properties

HumanViewerFactory

The viewer every env renders render_mode="human" into unless it was given its own viewer_factory (DR-20): set it once at start-up (Gymnasium.HumanViewerFactory = AvaloniaEnvViewer.Factory;). Left null, a human render raises DependencyNotInstalled, where Gymnasium raises it for a missing pygame; nothing falls back to a headless viewer silently.

public static EnvViewerFactory? HumanViewerFactory { get; set; }

Property Value

EnvViewerFactory

Remarks

Read when an env first renders in human mode, so setting it after an env was built still applies to that env.

Registry

The global registry (gymnasium.registry): every id Make(string, object?, long?, bool?) knows.

public static EnvSpecRegistry Registry { get; }

Property Value

EnvSpecRegistry

Methods

Make(EnvSpec, RenderMode, EnvViewerFactory?, object?, long?, bool?)

Builds the env a spec describes in a render mode, with its viewer (DR-84, DR-89); see Make(string, RenderMode, EnvViewerFactory?, object?, long?, bool?).

public static IEnv Make(EnvSpec spec, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

renderMode RenderMode

The render mode.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, kwargs also holds render_mode, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(EnvSpec, object?, long?, bool?)

Builds the env a spec describes (gymnasium.make(env_spec)); see Make(EnvSpec, object?, long?, bool?).

public static IEnv Make(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when the env cannot be built from the kwargs.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(EnvSpec, string?, EnvViewerFactory?, object?, long?, bool?)

Builds the env a spec describes in a render mode given as Gymnasium's string, with its viewer (DR-84, DR-89).

public static IEnv Make(EnvSpec spec, string? renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

renderMode string

The render mode's string, or null for none given.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, kwargs also holds render_mode, or the env cannot be built.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(string, RenderMode, EnvViewerFactory?, object?, long?, bool?)

Builds a registered env in a render mode, with the viewer its human window opens from (DR-84, DR-89): Make("CartPole-v1", RenderMode.Human, AvaloniaEnvViewer.Factory) is make("CartPole-v1", render_mode="human") with that window. The mode joins the kwargs as Gymnasium's string, so the spec records render_mode="human"; the factory is passed to the env, or to the HumanRendering wrapper make applies to an env that only renders images, and is never recorded in the spec.

public static IEnv Make(string id, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id: "CartPole-v1", an unversioned "CartPole", or "Assembly:Id".

renderMode RenderMode

The render mode.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory, then to DependencyNotInstalled at the first human render, as DR-20 resolves it.

kwargs object

The env's other constructor arguments by Python name: a dictionary, an options record, or an anonymous object.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when kwargs also holds render_mode (make() got multiple values for keyword argument 'render_mode'), or the env cannot be built from the kwargs (an env without a viewer_factory parameter refuses a factory).

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(string, object?, long?, bool?)

Builds a registered env with make's wrappers (gymnasium.make); see Make(string, object?, long?, bool?).

public static IEnv Make(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id: "CartPole-v1", an unversioned "CartPole", or "Assembly:Id".

kwargs object

The env's constructor arguments by Python name: a dictionary, an options record, or an anonymous object.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when the env cannot be built from the kwargs.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(string, string?, EnvViewerFactory?, object?, long?, bool?)

Make(string, RenderMode, EnvViewerFactory?, object?, long?, bool?) with Gymnasium's string for the mode (DR-84): any string Gymnasium accepts, a custom env's own modes included (DR-93); null leaves the spec's mode as it is.

public static IEnv Make(string id, string? renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id.

renderMode string

The render mode's string ("rgb_array", RenderModes), or null for none given.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when kwargs also holds render_mode, or the env cannot be built from the kwargs.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

MakeVec(EnvSpec, int, VectorizeMode, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?, EnvViewerFactory?)

Builds a vector env from a spec with the vectorization and autoreset modes as enums (DR-84).

public static IVectorEnv MakeVec(EnvSpec spec, int numEnvs, VectorizeMode vectorizationMode, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null, EnvViewerFactory? viewerFactory = null)

Parameters

spec EnvSpec

The spec.

numEnvs int

The number of sub-envs.

vectorizationMode VectorizeMode

The vectorization mode.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, the autoreset mode is given twice, or the env cannot be built.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(EnvSpec, int, RenderMode, EnvViewerFactory?, VectorizeMode?, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env from a spec in a render mode, with the sub-envs' viewer (DR-84, DR-89); see MakeVec(string, int, RenderMode, EnvViewerFactory?, VectorizeMode?, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static IVectorEnv MakeVec(EnvSpec spec, int numEnvs, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, VectorizeMode? vectorizationMode = null, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec: a registered one, or one a previous MakeVec recorded.

numEnvs int

The number of sub-envs.

renderMode RenderMode

The sub-envs' render mode.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

vectorizationMode VectorizeMode?

The vectorization mode, or null for the spec's default.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's other constructor arguments by Python name.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, a mode is given twice, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env from a spec (gymnasium.make_vec(env_spec)); see MakeVec(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static IVectorEnv MakeVec(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec: a registered one, or one a previous MakeVec recorded.

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when the env cannot be built.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(string, int, VectorizeMode, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?, EnvViewerFactory?)

Builds a vector env of copies of a registered env with the vectorization and autoreset modes as enums (DR-84): MakeVec("CartPole-v1", 4, VectorizeMode.Async, AutoresetMode.SameStep) is make_vec("CartPole-v1", 4, "async", vector_kwargs={"autoreset_mode": AutoresetMode.SAME_STEP}).

public static IVectorEnv MakeVec(string id, int numEnvs, VectorizeMode vectorizationMode, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null, EnvViewerFactory? viewerFactory = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

vectorizationMode VectorizeMode

The vectorization mode.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default (NEXT_STEP).

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env, innermost first.

kwargs object

The env's constructor arguments by Python name.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when vectorKwargs also holds autoreset_mode, or the env cannot be built.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the id is not registered, has no (vector) entry point, or the vector entry point is asked for with vector kwargs (an autoreset mode included) or wrappers.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(string, int, RenderMode, EnvViewerFactory?, VectorizeMode?, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env of copies of a registered env in a render mode, with the viewer every sub-env's human window opens from (DR-84, DR-89): the mode joins the env kwargs as Gymnasium's string, the vectorization and autoreset modes are the enums, and every sub-env's make gets the factory (the vector entry point's constructor does, as viewer_factory, in that mode). Strings for the other modes go through MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static IVectorEnv MakeVec(string id, int numEnvs, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, VectorizeMode? vectorizationMode = null, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

renderMode RenderMode

The sub-envs' render mode.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

vectorizationMode VectorizeMode?

The vectorization mode, or null for the spec's default (its vector entry point, else sync).

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default (NEXT_STEP).

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env, innermost first.

kwargs object

The env's other constructor arguments by Python name.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when kwargs also holds render_mode or vectorKwargs also holds autoreset_mode (make_vec() got multiple values for keyword argument '...'), or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the id is not registered, has no (vector) entry point, or the vector entry point is asked for with vector kwargs (an autoreset mode included) or wrappers.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env of copies of a registered env (gymnasium.make_vec): its own vectorized class when the spec has one, else a SyncVectorEnv; see MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static IVectorEnv MakeVec(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

vectorizationMode object

A VectorizeMode or its value ("sync", "async", "vector_entry_point"), or null for the spec's default.

vectorKwargs object

The vector env's constructor arguments by Python name (autoreset_mode, copy, observation_mode).

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env, innermost first.

kwargs object

The env's constructor arguments by Python name.

Returns

IVectorEnv

The vector env, untyped; the caller owns it.

Exceptions

TypeError

Thrown when the env cannot be built from the kwargs.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the id is not registered, has no (vector) entry point, or the vector entry point is asked for with vector kwargs or wrappers.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(EnvSpec, int, VectorizeMode, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?, EnvViewerFactory?)

Builds a vector env from a spec, typed (DR-21), with the vectorization and autoreset modes as enums (DR-84).

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(EnvSpec spec, int numEnvs, VectorizeMode vectorizationMode, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null, EnvViewerFactory? viewerFactory = null)

Parameters

spec EnvSpec

The spec.

numEnvs int

The number of sub-envs.

vectorizationMode VectorizeMode

The vectorization mode.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type.

TAct

The batched action type.

Exceptions

TypeError

Thrown when spec is null, the batched types differ, the autoreset mode is given twice, or the env cannot be built.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(EnvSpec, int, RenderMode, EnvViewerFactory?, VectorizeMode?, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env from a spec, typed (DR-21), in a render mode, with the sub-envs' viewer (DR-84, DR-89).

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(EnvSpec spec, int numEnvs, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, VectorizeMode? vectorizationMode = null, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec.

numEnvs int

The number of sub-envs.

renderMode RenderMode

The sub-envs' render mode.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

vectorizationMode VectorizeMode?

The vectorization mode, or null for the spec's default.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's other constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type.

TAct

The batched action type.

Exceptions

TypeError

Thrown when spec is null, the batched types differ, a mode is given twice, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec.

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type.

TAct

The batched action type.

Exceptions

TypeError

Thrown when the batched types differ or the env cannot be built.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(string, int, VectorizeMode, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?, EnvViewerFactory?)

Builds a vector env typed by its batched types (DR-21), with the vectorization and autoreset modes as enums (DR-84).

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(string id, int numEnvs, VectorizeMode vectorizationMode, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null, EnvViewerFactory? viewerFactory = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

vectorizationMode VectorizeMode

The vectorization mode.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type.

TAct

The batched action type.

Exceptions

TypeError

Thrown when the batched types are not the ones asked for, the autoreset mode is given twice, or the env cannot be built.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the id is not registered or has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(string, int, RenderMode, EnvViewerFactory?, VectorizeMode?, AutoresetMode?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env typed by its batched types (DR-21), in a render mode, with the sub-envs' viewer (DR-84, DR-89).

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(string id, int numEnvs, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, VectorizeMode? vectorizationMode = null, AutoresetMode? autoresetMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

renderMode RenderMode

The sub-envs' render mode.

viewerFactory EnvViewerFactory

The factory each sub-env's human window opens from; null falls back to HumanViewerFactory.

vectorizationMode VectorizeMode?

The vectorization mode, or null for the spec's default.

autoresetMode AutoresetMode?

The vector env's autoreset_mode, or null for its default.

vectorKwargs object

The vector env's other constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's other constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type (NDArray for array spaces).

TAct

The batched action type.

Exceptions

TypeError

Thrown when the batched types are not the ones asked for, a mode is given twice, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

ValueError

Thrown for a vectorization mode the enum does not declare.

Error

Thrown when the id is not registered or has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env typed by its batched types (DR-21); see MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type (NDArray for array spaces).

TAct

The batched action type.

Exceptions

TypeError

Thrown when the batched types are not the ones asked for, or the env cannot be built.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the id is not registered or has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

Make<TObs, TAct>(EnvSpec, RenderMode, EnvViewerFactory?, object?, long?, bool?)

Builds the env a spec describes, typed (DR-10), in a render mode, with its viewer (DR-84, DR-89).

public static Env<TObs, TAct> Make<TObs, TAct>(EnvSpec spec, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

renderMode RenderMode

The render mode.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when spec is null, the env is not an Env<TObs, TAct>, kwargs also holds render_mode, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(EnvSpec, object?, long?, bool?)

Builds the env a spec describes, typed (DR-10); see Make<TObs, TAct>(EnvSpec, object?, long?, bool?).

public static Env<TObs, TAct> Make<TObs, TAct>(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct> or cannot be built from the kwargs.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(EnvSpec, string?, EnvViewerFactory?, object?, long?, bool?)

Builds the env a spec describes, typed (DR-10), in a render mode given as Gymnasium's string, with its viewer (DR-84, DR-89).

public static Env<TObs, TAct> Make<TObs, TAct>(EnvSpec spec, string? renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

renderMode string

The render mode's string, or null for none given.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when spec is null, the env is not an Env<TObs, TAct>, kwargs also holds render_mode, or the env cannot be built.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(string, RenderMode, EnvViewerFactory?, object?, long?, bool?)

Builds a registered env typed (DR-10), in a render mode, with its viewer (DR-84, DR-89); see Make(string, RenderMode, EnvViewerFactory?, object?, long?, bool?).

public static Env<TObs, TAct> Make<TObs, TAct>(string id, RenderMode renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id.

renderMode RenderMode

The render mode.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct>, kwargs also holds render_mode, or the env cannot be built.

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(string, object?, long?, bool?)

Builds a registered env typed (DR-10); see Make<TObs, TAct>(string, object?, long?, bool?).

public static Env<TObs, TAct> Make<TObs, TAct>(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id.

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct> or cannot be built from the kwargs.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(string, string?, EnvViewerFactory?, object?, long?, bool?)

Builds a registered env typed (DR-10), in a render mode given as Gymnasium's string, with its viewer (DR-84, DR-89).

public static Env<TObs, TAct> Make<TObs, TAct>(string id, string? renderMode, EnvViewerFactory? viewerFactory = null, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id.

renderMode string

The render mode's string, or null for none given.

viewerFactory EnvViewerFactory

The factory the human window opens from; null falls back to HumanViewerFactory.

kwargs object

The env's other constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct>, kwargs also holds render_mode, or the env cannot be built.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool)

Prints (or returns) every registered id grouped by namespace (gymnasium.pprint_registry); see PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool).

public static string? PprintRegistry(IReadOnlyDictionary<string, EnvSpec>? printRegistry = null, int numCols = 3, IEnumerable<string?>? excludeNamespaces = null, bool disablePrint = false)

Parameters

printRegistry IReadOnlyDictionary<string, EnvSpec>

The registry to print; null is Registry.

numCols int

How many ids per line.

excludeNamespaces IEnumerable<string>

Namespaces to leave out, or null.

disablePrint bool

Return the text instead of writing it to the console.

Returns

string

The text when disablePrint is set, otherwise null.

Exceptions

ZeroDivisionError

Thrown when numCols is 0.

Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?)

public static void Register(string id, object? entryPoint = null, double? rewardThreshold = null, bool nondeterministic = false, long? maxEpisodeSteps = null, bool orderEnforce = true, bool disableEnvChecker = false, IEnumerable<WrapperSpec>? additionalWrappers = null, object? vectorEntryPoint = null, object? kwargs = null)

Parameters

id string

The id, namespace/[-v(version)].

entryPoint object

The env's class, an EnvCreator, or a "Namespace:Class" string.

rewardThreshold double?

The return at which the task counts as solved.

nondeterministic bool

Whether the same seed and actions can still give different observations.

maxEpisodeSteps long?

The step limit make's TimeLimit enforces.

orderEnforce bool

Whether make adds OrderEnforcing.

disableEnvChecker bool

Whether make leaves out PassiveEnvChecker.

additionalWrappers IEnumerable<WrapperSpec>

Wrappers make applies on top, in order.

vectorEntryPoint object

What builds a vectorized version.

kwargs object

The env's constructor arguments by Python name.

Exceptions

ValueError

Thrown when neither entry point is given.

Error

Thrown for a malformed id.

RegistrationError

Thrown when a versioned and an unversioned id of the same name would both be registered.

TypeError

Thrown when kwargs is not a mapping.

RegisterEnvs(object?)

A no-op that marks a module as used (gymnasium.register_envs); registration is the env assembly's own (DR-12).

public static void RegisterEnvs(object? envModule)

Parameters

envModule object

Anything; ignored.

ResolveHumanViewerFactory(EnvViewerFactory?)

The viewer factory an env uses for human mode (DR-20): its own viewerFactory, else HumanViewerFactory, else Gymnasium's missing-dependency error. Envs call it on their first human render.

public static EnvViewerFactory ResolveHumanViewerFactory(EnvViewerFactory? viewerFactory)

Parameters

viewerFactory EnvViewerFactory

The env's viewer_factory argument, or null.

Returns

EnvViewerFactory

The factory to create the window with.

Exceptions

DependencyNotInstalled

Thrown when neither is set: No human-mode viewer is set, set Gymnasium.HumanViewerFactory (for example to AvaloniaEnvViewer.Factory of the Gym.NET.Rendering.Avalonia package) or pass viewer_factory to the environment.

Spec(string)

The spec registered under an id exactly (gymnasium.spec); see Spec(string).

public static EnvSpec Spec(string envId)

Parameters

envId string

The id.

Returns

EnvSpec

The registered spec itself.

Exceptions

ArgumentNullException

Thrown when envId is null.

Error

Thrown for a malformed or unregistered id.

NamespaceNotFound

Thrown when the namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.