Interface IEnv
The env contract over object: what code that holds envs of any observation and action type (wrappers over unknown envs, the registry, vector envs, the legacy adapter) programs against. Every env is an Env<TObs, TAct>, which implements it; its typed members are the ones to call when the types are known.
public interface IEnv : IDisposable
- Inherited Members
- Extension Methods
Remarks
Members follow Gymnasium's Env one to one with the port plan's naming (ยง3.8): step is
Step(object?), np_random_seed is NpRandomSeed, get_wrapper_attr is
GetWrapperAttr(string). Dispose() calls Close(), as leaving a Python
with block does.
Not thread-safe: step, reset and render an instance from one thread at a time.
Reference: gymnasium/core.py.
Properties
ActionSpace
The space every action must belong to.
Space ActionSpace { get; set; }
Property Value
Exceptions
- AttributeError
Thrown by the getter while the env has not set one, as reading the missing Python attribute does.
Metadata
The env's metadata, {"render_modes": [...], "render_fps": ...} with Python key spelling. A wrapper returns
its env's unless it was assigned its own.
Metadata Metadata { get; set; }
Property Value
NpRandom
The env's generator (np_random): created from OS entropy on first use, replaced by a seeded
Reset(BigInteger?, IReadOnlyDictionary<string, object?>?); assigning one makes NpRandomSeed -1. A wrapper forwards to the
innermost env.
Generator NpRandom { get; set; }
Property Value
NpRandomSeed
The seed NpRandom was built from (np_random_seed): the seed of the last seeded reset, the
entropy of an unseeded generator (creating it first if needed), or -1 after a generator was assigned.
Read-only, as in Gymnasium.
BigInteger NpRandomSeed { get; }
Property Value
ObservationSpace
The space every observation belongs to.
Space ObservationSpace { get; set; }
Property Value
Exceptions
- AttributeError
Thrown by the getter while the env has not set one.
RenderMode
The render mode fixed at construction ("human", "rgb_array", ...), or null when the env does not render.
string? RenderMode { get; }
Property Value
Spec
The spec make attached, or null for an env built with its constructor. A wrapper's is its
env's, extended with the wrapper (and read-only: assigning it raises AttributeError).
EnvSpec? Spec { get; set; }
Property Value
Unwrapped
The innermost env, beneath every wrapper (unwrapped); an env that is not a wrapper returns itself.
IEnv Unwrapped { get; }
Property Value
Methods
Close()
Releases what the env holds, windows included (close()); closing twice does nothing more.
void Close()
CloseEnvironment()
0.2's name for Close(), kept so 0.2 code holding an IEnv compiles until 2.0 (DR-58). The default calls Close(); Env<TObs, TAct>'s public method of the same name replaces it.
[Obsolete("Close() is Gymnasium's name (or Dispose(), through using); CloseEnvironment is 0.2's. Removed in 2.0 with Gym.Legacy.")]
void CloseEnvironment()
GetWrapperAttr(string)
Python's get_wrapper_attr(name): the attribute from the outermost layer that has it.
object? GetWrapperAttr(string name)
Parameters
namestringThe attribute, in Python spelling.
Returns
- object
The value, boxed.
Exceptions
- AttributeError
Thrown when no layer has it (
wrapper TimeLimit has no attribute 'x').
HasWrapperAttr(string)
Python's has_wrapper_attr(name): whether this env, or for a wrapper any env beneath it, has the Python
attribute name ("gravity", "_disable_render_order_enforcing").
bool HasWrapperAttr(string name)
Parameters
namestringThe attribute, in Python spelling.
Returns
Render()
Renders as RenderMode says (render()).
RenderResult Render()
Returns
- RenderResult
A frame, text, collected frames, or None (human mode, no render mode).
Exceptions
- NotImplementedError
Thrown by an env that does not render.
Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)
Starts an episode (reset(seed=seed, options=options)).
ResetResult<object?> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)
Parameters
seedBigInteger?Reseeds NpRandom first when given (any non-negative integer); null keeps the generator, so a stream seeded once runs on across episodes.
optionsIReadOnlyDictionary<string, object>Env-specific options (for example
"low"/"high"in classic_control), or null.
Returns
- ResetResult<object>
The first observation, boxed, and the info.
Exceptions
- Error
Thrown for a negative seed, with Gymnasium's message.
SetWrapperAttr(string, object?, bool)
Python's set_wrapper_attr(name, value, force=force): assigns the attribute on the outermost layer that has
it; when none has it, force creates it on this layer.
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.
forceboolCreate the attribute here when no layer has it (Gymnasium's default, true).
Returns
Exceptions
- AttributeError
Thrown when the attribute is read-only (
np_random_seed).- TypeError
Thrown when the value does not fit the attribute's type.
Step(object?)
Runs one timestep with an action of any type; the env converts it to its action type first (a typed env's
Step(TAct) takes it directly).
StepResult<object?> Step(object? action)
Parameters
actionobjectAn element of ActionSpace.
Returns
- StepResult<object>
The transition, its observation boxed.
Exceptions
- Exception
Whatever the env raises for the action: an AssertionError for an invalid one, a ResetNeeded from
OrderEnforcing, ....
StepAsync(object?, CancellationToken)
Steps asynchronously with an action of any type (see StepAsync(TAct, CancellationToken)): by default the step runs on the calling thread and the task completes synchronously; an action that cannot be converted, like any error of the step, faults the task.
ValueTask<StepResult<object?>> StepAsync(object? action, CancellationToken cancellationToken = default)
Parameters
actionobjectAn element of ActionSpace.
cancellationTokenCancellationTokenChecked before the step starts.
Returns
- ValueTask<StepResult<object>>
A value task that completes with the transition, its observation boxed.