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
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
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
specEnvSpecThe spec.
renderModeRenderModeThe render mode.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Exceptions
- TypeError
Thrown when
specis null,kwargsalso holdsrender_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
ClassMetadatais 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
specEnvSpecThe spec.
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?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
ClassMetadatais 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
specEnvSpecThe spec.
renderModestringThe render mode's string, or null for none given.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Exceptions
- TypeError
Thrown when
specis null,kwargsalso holdsrender_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
ClassMetadatais 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
idstringThe id:
"CartPole-v1", an unversioned"CartPole", or"Assembly:Id".renderModeRenderModeThe render mode.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory, then to DependencyNotInstalled at the first human render, as DR-20 resolves it.
kwargsobjectThe env's other constructor arguments by Python name: a dictionary, an options record, or an anonymous object.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Exceptions
- TypeError
Thrown when
kwargsalso holdsrender_mode(make() got multiple values for keyword argument 'render_mode'), or the env cannot be built from the kwargs (an env without aviewer_factoryparameter 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
ClassMetadatais 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
idstringThe id:
"CartPole-v1", an unversioned"CartPole", or"Assembly:Id".kwargsobjectThe env's constructor arguments by Python name: a dictionary, an options record, or an anonymous object.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?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
ClassMetadatais 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
idstringThe id.
renderModestringThe render mode's string (
"rgb_array", RenderModes), or null for none given.viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Exceptions
- TypeError
Thrown when
kwargsalso holdsrender_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
ClassMetadatais 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
specEnvSpecThe spec.
numEnvsintThe number of sub-envs.
vectorizationModeVectorizeModeThe vectorization mode.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
viewerFactoryEnvViewerFactoryThe 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
specis 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
specEnvSpecThe spec: a registered one, or one a previous
MakeVecrecorded.numEnvsintThe number of sub-envs.
renderModeRenderModeThe sub-envs' render mode.
viewerFactoryEnvViewerFactoryThe factory each sub-env's human window opens from; null falls back to HumanViewerFactory.
vectorizationModeVectorizeMode?The vectorization mode, or null for the spec's default.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's other constructor arguments by Python name.
Returns
- IVectorEnv
The vector env, untyped; the caller owns it.
Exceptions
- TypeError
Thrown when
specis 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
specEnvSpecThe spec: a registered one, or one a previous
MakeVecrecorded.numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe 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
idstringThe id.
numEnvsintThe number of sub-envs.
vectorizationModeVectorizeModeThe vectorization mode.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default (NEXT_STEP).vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env, innermost first.
kwargsobjectThe env's constructor arguments by Python name.
viewerFactoryEnvViewerFactoryThe 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
vectorKwargsalso holdsautoreset_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
idstringThe id.
numEnvsintThe number of sub-envs.
renderModeRenderModeThe sub-envs' render mode.
viewerFactoryEnvViewerFactoryThe factory each sub-env's human window opens from; null falls back to HumanViewerFactory.
vectorizationModeVectorizeMode?The vectorization mode, or null for the spec's default (its vector entry point, else sync).
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default (NEXT_STEP).vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env, innermost first.
kwargsobjectThe env's other constructor arguments by Python name.
Returns
- IVectorEnv
The vector env, untyped; the caller owns it.
Exceptions
- TypeError
Thrown when
kwargsalso holdsrender_modeorvectorKwargsalso holdsautoreset_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
idstringThe id.
numEnvsintThe number of sub-envs.
vectorizationModeobjectA VectorizeMode or its value (
"sync","async","vector_entry_point"), or null for the spec's default.vectorKwargsobjectThe vector env's constructor arguments by Python name (
autoreset_mode,copy,observation_mode).wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env, innermost first.
kwargsobjectThe 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
specEnvSpecThe spec.
numEnvsintThe number of sub-envs.
vectorizationModeVectorizeModeThe vectorization mode.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
viewerFactoryEnvViewerFactoryThe 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
TObsThe batched observation type.
TActThe batched action type.
Exceptions
- TypeError
Thrown when
specis 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
specEnvSpecThe spec.
numEnvsintThe number of sub-envs.
renderModeRenderModeThe sub-envs' render mode.
viewerFactoryEnvViewerFactoryThe factory each sub-env's human window opens from; null falls back to HumanViewerFactory.
vectorizationModeVectorizeMode?The vectorization mode, or null for the spec's default.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's other constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type.
TActThe batched action type.
Exceptions
- TypeError
Thrown when
specis 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?)
Builds a vector env from a spec, typed (DR-21); see 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
specEnvSpecThe spec.
numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type.
TActThe 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
idstringThe id.
numEnvsintThe number of sub-envs.
vectorizationModeVectorizeModeThe vectorization mode.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
viewerFactoryEnvViewerFactoryThe 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
TObsThe batched observation type.
TActThe 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
idstringThe id.
numEnvsintThe number of sub-envs.
renderModeRenderModeThe sub-envs' render mode.
viewerFactoryEnvViewerFactoryThe factory each sub-env's human window opens from; null falls back to HumanViewerFactory.
vectorizationModeVectorizeMode?The vectorization mode, or null for the spec's default.
autoresetModeAutoresetMode?The vector env's
autoreset_mode, or null for its default.vectorKwargsobjectThe vector env's other constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's other constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type (
NDArrayfor array spaces).TActThe 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
idstringThe id.
numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type (
NDArrayfor array spaces).TActThe 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
specEnvSpecThe spec.
renderModeRenderModeThe render mode.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when
specis null, the env is not anEnv<TObs, TAct>,kwargsalso holdsrender_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
ClassMetadatais 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
specEnvSpecThe spec.
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe 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
ClassMetadatais 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
specEnvSpecThe spec.
renderModestringThe render mode's string, or null for none given.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when
specis null, the env is not anEnv<TObs, TAct>,kwargsalso holdsrender_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
ClassMetadatais 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
idstringThe id.
renderModeRenderModeThe render mode.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when the env is not an
Env<TObs, TAct>,kwargsalso holdsrender_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
ClassMetadatais 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
idstringThe id.
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe 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
ClassMetadatais 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
idstringThe id.
renderModestringThe render mode's string, or null for none given.
viewerFactoryEnvViewerFactoryThe factory the human window opens from; null falls back to HumanViewerFactory.
kwargsobjectThe env's other constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when the env is not an
Env<TObs, TAct>,kwargsalso holdsrender_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
ClassMetadatais 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
printRegistryIReadOnlyDictionary<string, EnvSpec>numColsintHow many ids per line.
excludeNamespacesIEnumerable<string>Namespaces to leave out, or null.
disablePrintboolReturn the text instead of writing it to the console.
Returns
Exceptions
- ZeroDivisionError
Thrown when
numColsis 0.
Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?)
Registers an env for Make(string, object?, long?, bool?) (gymnasium.register); see 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
idstringThe id,
namespace/[-v(version)].entryPointobjectThe env's class, an EnvCreator, or a
"Namespace:Class"string.rewardThresholddouble?The return at which the task counts as solved.
nondeterministicboolWhether the same seed and actions can still give different observations.
maxEpisodeStepslong?The step limit
make'sTimeLimitenforces.orderEnforceboolWhether
makeaddsOrderEnforcing.disableEnvCheckerboolWhether
makeleaves outPassiveEnvChecker.additionalWrappersIEnumerable<WrapperSpec>Wrappers
makeapplies on top, in order.vectorEntryPointobjectWhat builds a vectorized version.
kwargsobjectThe 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
kwargsis 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
envModuleobjectAnything; 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
viewerFactoryEnvViewerFactoryThe env's
viewer_factoryargument, 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 toAvaloniaEnvViewer.Factoryof the Gym.NET.Rendering.Avalonia package) or passviewer_factoryto the environment
Spec(string)
The spec registered under an id exactly (gymnasium.spec); see Spec(string).
public static EnvSpec Spec(string envId)
Parameters
envIdstringThe id.
Returns
- EnvSpec
The registered spec itself.
Exceptions
- ArgumentNullException
Thrown when
envIdis 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.