Class Env<TObs, TAct>
The base class of every environment: an MDP driven through Step(TAct) and Reset(BigInteger?, IReadOnlyDictionary<string, object?>?), with spaces, metadata, a render mode, a lazily created generator and the attribute protocol (GetWrapperAttr(string), ...).
public abstract class Env<TObs, TAct> : IEnv, IDisposable, IDynamicAttributes
Type Parameters
TObsThe observation type: NDArray for array spaces,
Discreteincluded (its elements are 0-d int64 arrays, DR-08); a tuple type for a composite space (Blackjack'sobject?[], DR-13).TActThe action type, likewise: every built-in env takes NDArray actions.
- Inheritance
-
Env<TObs, TAct>
- Implements
- Derived
- Inherited Members
- Extension Methods
Remarks
Implementing an env: set ActionSpace, ObservationSpace and, when it renders,
Metadata and RenderMode in the constructor; begin Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) with
SeedNpRandom(BigInteger?) (Gymnasium's super().reset(seed=seed)), and draw every random number from
NpRandom. Skipping the seeding call breaks reproducibility, which every parity test relies on.
Python attributes map to properties (port plan ยง3.8), which Gymnasium's attribute functions reach by their Python
names through PyAttributes: np_random_seed is NpRandomSeed, and non-public
state carries PyNameAttribute (_np_random). Like a Python instance, an env also holds
attributes created at run time (set_wrapper_attr(name, value, force=True), env.x = 1 through
SetAttr(object, string, object?)).
A deviation that follows from C#: Metadata is per instance (Python's class attribute is shared by
every instance of the class, so mutating one env's changed all of them). The spaces are typed by the env's element
types, Space<T> of TAct and TObs (DR-07).
Reference: gymnasium/core.py.
Properties
ActionSpace
The space every action must belong to (action_space), typed by the action type (DR-07): a
Discrete or Box for NDArray actions. The env sets it in its constructor
and owns it: Dispose() disposes it, so a space must not be shared between envs, and the setter
refuses one that another env not yet disposed owns (DR-40). Replacing it lets the old space go undisposed, as in
Python, where whoever still holds it keeps using it.
public virtual Space<TAct> ActionSpace { get; set; }
Property Value
- Space<TAct>
Exceptions
- AttributeError
Thrown by the getter while unset, as reading Python's annotated-only attribute does (
'GenericTestEnv' object has no attribute 'action_space').- InvalidOperationException
Thrown by the setter for a space another env not yet disposed owns; the message names the fix (a new space, or
DeepCopy()).
ClassMetadata
The class-level metadata, Python's class attribute metadata that make reads before the env exists
to decide on HumanRendering or RenderCollection: {"render_modes": []} here, as on
gymnasium.Env. An env class that renders declares its own with new
(public new static Metadata ClassMetadata => ...) and sets its instance Metadata from it.
public static Metadata ClassMetadata { get; }
Property Value
Remarks
A new dict on every read: Python shares one dict between the class and its instances, so editing it there edits every env; here each reader gets its own.
Metadata
The metadata (metadata), with Python key spelling: {"render_modes": ["human", "rgb_array"],
"render_fps": 50}. Defaults to {"render_modes": []}, as Env.metadata does.
public virtual Metadata Metadata { get; set; }
Property Value
Exceptions
- ArgumentNullException
Thrown when assigning null.
NpRandom
The env's generator (np_random). The first read creates one from OS entropy, as Gymnasium does, which is
why an unseeded env still draws reproducibly within itself; a seeded Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) replaces it. Assigning a
generator shares it deliberately and makes NpRandomSeed -1, because a generator's seed cannot be
recovered.
public virtual Generator NpRandom { get; set; }
Property Value
NpRandomSeed
The seed of NpRandom (np_random_seed): the seed of the last seeded reset, the 128-bit
entropy of an entropy-seeded generator (created by this read if none exists yet), or -1 after a generator was
assigned. Read-only: Python raises AttributeError on assignment, and
SetAttr(object, string, object?) does too.
public virtual BigInteger NpRandomSeed { get; }
Property Value
ObservationSpace
The space every observation belongs to (observation_space), typed by the observation type. The env sets it
in its constructor and owns it, like ActionSpace, the same refusal included.
public virtual Space<TObs> ObservationSpace { get; set; }
Property Value
- Space<TObs>
Exceptions
- AttributeError
Thrown by the getter while unset.
- InvalidOperationException
Thrown by the setter for a space another env not yet disposed owns.
PythonClassName
The class name Python prints for this instance in messages: the class's own name (PyTypeName(Type))
unless an env whose Python class depends on the instance says otherwise (the merged MountainCar's
Continuous_MountainCarEnv, DR-32). PyAttributes names it in its AttributeErrors.
protected virtual string PythonClassName { get; }
Property Value
RawNpRandom
Python's _np_random: the generator as it is, null before first use, without creating one.
Gymnasium's tests read it to check laziness; a wrapper raises AttributeError instead.
[PyName("_np_random")]
protected virtual Generator? RawNpRandom { get; set; }
Property Value
RawNpRandomSeed
Python's _np_random_seed: the recorded seed as it is, null before first use.
[PyName("_np_random_seed")]
protected virtual BigInteger? RawNpRandomSeed { get; set; }
Property Value
RenderMode
The render mode given to the constructor (render_mode), null (the default) when the env
should not render. Fixed for the env's life: rendering another way means building another env.
public virtual string? RenderMode { get; protected set; }
Property Value
Spec
The spec make attached (spec), or null (the default) for an env built with its constructor.
public virtual EnvSpec? Spec { get; set; }
Property Value
Unwrapped
The innermost env (unwrapped): the env itself; wrappers override it to walk down their stack.
public virtual IEnv Unwrapped { get; }
Property Value
Methods
Close()
Releases what the env holds (close()): windows, native handles, connections. Calling it on a closed env
does nothing more. The base holds nothing.
public virtual void Close()
CloseEnvironment()
0.2's name for Close(), kept so 0.2's teardown line compiles until 2.0 (DR-58): it calls Close(), the env's own override included.
[Obsolete("Close() is Gymnasium's name (or Dispose(), through using); CloseEnvironment is 0.2's. Removed in 2.0 with Gym.Legacy.")]
public void CloseEnvironment()
ConvertAction(object?)
Converts an action given to the untyped Step(object?) to TAct: an instance of it
as is; for an integer or enum action type, any .NET integer, bool, enum member or 0-d integer
array (what Discrete.Sample() returns); for a floating-point action type, any number or 0-d array; for an
NDArray action type, what np.asarray makes of it: a .NET integer (or bool,
Python's int subclass) a 0-d int64 array, a double or float a 0-d float64
or float32 array, a .NET array an array of its element type.
protected virtual TAct ConvertAction(object? action)
Parameters
actionobjectThe action as given.
Returns
- TAct
The typed action.
Remarks
Python has no such step: an env receives whatever it is given and validates it itself. Envs whose Python source
asserts on the action override this to assert first, so an unconvertible action fails with the source's message
(CartPole: 'x' (<class 'str'>) invalid) rather than this one.
Exceptions
- TypeError
Thrown when the action cannot denote a
TAct.- OverflowException
Thrown when an integer does not fit an integer action type.
Dispose()
Calls Close(), so using plays the role of Python's with statement (exit), then
releases the spaces this env owns (D19). Idempotent in effect: a second call closes again, which every env's
Close() tolerates, and finds the spaces already released.
public void Dispose()
Dispose(bool)
What Dispose() does: Close(), then the env's own action and observation spaces. A wrapper overrides it to release its own spaces and the env it wraps.
protected virtual void Dispose(bool disposing)
Parameters
GetKeysToAction()
The keyboard mapping play uses when the caller gives none (get_keys_to_action()): key combinations
to the actions they trigger, MountainCar's {(): 1, (276,): 0, (275,): 2, (275, 276): 1}. Absent until an
env overrides it (DR-45): this base raises Python's AttributeError, as calling a method the class
lacks does, and PyAttributes reports the attribute only on an env that overrides it.
[PyName("get_keys_to_action")]
public virtual IReadOnlyDictionary<KeyCombination, TAct> GetKeysToAction()
Returns
- IReadOnlyDictionary<KeyCombination, TAct>
A new mapping the caller owns, its actions included: an override builds fresh actions on every call.
Remarks
Wrappers inherit this absent base: Gymnasium 1.x's wrappers forward no attributes, and play asks the layers
beneath through has_wrapper_attr. An override whose presence depends on the instance also overrides
HasPythonAttribute(string), so hasattr answers as Python's would for that state.
Reference: gymnasium/utils/play.py.
Exceptions
- AttributeError
Thrown by this base (
'CartPoleEnv' object has no attribute 'get_keys_to_action'), and by an override in a state that has no mapping (MountainCar's continuous mode).
GetWrapperAttr(string)
The Python attribute name of this env, as Python's getattr(self, name) reads it.
public virtual object? GetWrapperAttr(string name)
Parameters
namestringThe attribute, in Python spelling.
Returns
- object
The value, boxed.
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- AttributeError
Thrown when the env has no such attribute (
'CartPoleEnv' object has no attribute 'x').
HasPythonAttribute(string)
Whether this instance has the Python attribute name, for attributes whose presence varies by
instance (DR-45): PyAttributes asks it before reporting a PyNameAttribute method that
the env overrides. The default leaves the answer to that override check.
protected virtual bool HasPythonAttribute(string name)
Parameters
namestringThe attribute, in Python spelling (
get_keys_to_action).
Returns
HasWrapperAttr(string)
Whether this env has the Python attribute name (Python's hasattr: declared members by
Python name, then run-time attributes).
public virtual bool HasWrapperAttr(string name)
Parameters
namestringThe attribute, in Python spelling.
Returns
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis null.
Render()
Renders as RenderMode says (render()): rgb_array returns a frame, ansi text,
human draws to a window during Step(TAct) and returns None. The base
raises NotImplementedError, as Env.render does.
public virtual RenderResult Render()
Returns
- RenderResult
The rendering.
Exceptions
- NotImplementedError
Thrown unless the env overrides it.
Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)
Starts an episode (reset(seed=seed, options=options)). Implementations call SeedNpRandom(BigInteger?)
first, then draw the initial state from NpRandom.
public abstract ResetResult<TObs> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)
Parameters
seedBigInteger?Reseeds NpRandom with Gymnasium's
Generator(PCG64(SeedSequence(seed)))when given (any non-negative integer); null keeps the current generator. Seed once, right after construction, then reset without a seed.optionsIReadOnlyDictionary<string, object>Env-specific reset options, or null.
Returns
- ResetResult<TObs>
The first observation and the info.
Remarks
As with Step(TAct), the observation and info must be new objects, not a buffer a previous call returned and this one mutated in place. Reference: gymnasium/core.py.
Exceptions
- Error
Thrown for a negative seed, with Gymnasium's message.
SeedNpRandom(BigInteger?)
The first line of every Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) (Gymnasium's super().reset(seed=seed)): reseeds
NpRandom and records NpRandomSeed when a seed is given; without one, the generator,
and with it the random stream, carries on.
protected void SeedNpRandom(BigInteger? seed)
Parameters
seedBigInteger?The seed passed to Reset(BigInteger?, IReadOnlyDictionary<string, object?>?), or null.
Remarks
Reference: gymnasium/core.py.
Exceptions
- Error
Thrown for a negative seed:
Seed must be greater or equal to zero, actual value: -1.
SetWrapperAttr(string, object?, bool)
Assigns the Python attribute name when force is set or the env has it,
creating a run-time attribute for a new name.
public virtual bool SetWrapperAttr(string name, object? value, bool force = true)
Parameters
namestringThe attribute, in Python spelling.
valueobjectThe value; numbers convert to a numeric attribute's type.
forceboolAssign even when the env does not have the attribute yet.
Returns
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- AttributeError
Thrown for a read-only attribute (
property 'np_random_seed' of 'CartPoleEnv' object has no setter).- TypeError
Thrown when the value does not fit the attribute's type.
Step(TAct)
Runs one timestep of the dynamics with action (step(action)). Once the result is
terminated or truncated, call Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) before stepping again.
public abstract StepResult<TObs> Step(TAct action)
Parameters
actionTActAn element of ActionSpace.
Returns
- StepResult<TObs>
The observation, reward,
terminated,truncatedand info.
Remarks
Every call must return a new observation and a new info, never a buffer an earlier call returned and this one
mutated: callers commonly keep every timestep (a replay or rollout buffer), and a reused buffer silently
rewrites the history they kept. Gymnasium's check_env and PassiveEnvChecker enforce this
since v1.4.0. Reference: gymnasium/core.py.
Exceptions
- AssertionError
Thrown by Gym's envs for an invalid action or a step before the first reset, where Gymnasium's envs fail an
assert.
StepAsync(TAct, CancellationToken)
Steps asynchronously: completes with what Step(TAct) returns. The default runs Step(TAct) on the calling thread and completes synchronously, with no thread-pool hop and no allocation; an env whose dynamics are genuinely asynchronous (a remote simulator, a batched GPU step) overrides it.
public virtual ValueTask<StepResult<TObs>> StepAsync(TAct action, CancellationToken cancellationToken = default)
Parameters
actionTActAn element of ActionSpace.
cancellationTokenCancellationTokenChecked before the step starts; a step that has started runs to completion.
Returns
- ValueTask<StepResult<TObs>>
A value task that completes with the transition, is faulted with what Step(TAct) threw, or is canceled when
cancellationTokenwas already canceled.
Remarks
Exceptions surface when the task is awaited, never from this call, as for any asynchronous method. Wrappers
inherit this default, so awaiting a wrapper runs the wrapper's own Step(TAct) (and, through it, the env
beneath, synchronously); a wrapper that must keep an asynchronous env asynchronous overrides StepAsync as
well. Not thread-safe, like Step(TAct): await each call before issuing the next on the same env.
ToString()
The env's description: <CartPoleEnv instance> without a spec, <CartPoleEnv<CartPole-v1>>
with one; wrapper descriptions embed it.
public override string ToString()
Returns
- string
The text, the same as Gymnasium prints for the env.
Remarks
Reference: gymnasium/core.py.