Class VectorEnv<TObs, TAct>
The base of every vector env (DR-21): NumEnvs sub-envs stepped in lockstep, typed by the batched
observation and action types (NDArray for array spaces, object?[] for a
Tuple space, Info for a Dict space). Rewards are a float64 array and the flags bool
arrays, one element per sub-env; infos are merged by key with Gymnasium's _key masks (AddInfo(Info, Info, int)).
public abstract class VectorEnv<TObs, TAct> : IVectorEnv, IDisposable
Type Parameters
TObsThe batched observation type, an element of ObservationSpace.
TActThe batched action type, an element of ActionSpace.
- Inheritance
-
VectorEnv<TObs, TAct>
- Implements
- Derived
-
SyncVectorEnv<TObs, TAct>
- Inherited Members
- Extension Methods
Remarks
Implementing a vector env: set the four spaces, NumEnvs and Metadata (with its
autoreset_mode) in the constructor; begin Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)
with SeedNpRandom(BigInteger?) when the env draws itself (Gymnasium's super().reset(seed=seed)). Python
attributes map to properties by snake_case (num_envs, single_action_space).
Deviations that follow from C#: Metadata is per instance (Python's class attribute is shared), and
an integer seed and a list of seeds are two overloads of Reset where Python takes one argument.
Reference: gymnasium/vector/vector_env.py.
Properties
ActionSpace
The batched action space (action_space), typed by the batched action type; owned as ObservationSpace is.
public virtual Space<TAct> ActionSpace { get; set; }
Property Value
- Space<TAct>
Exceptions
- AttributeError
Thrown by the getter while unset.
- InvalidOperationException
Thrown by the setter for a space another env not yet disposed owns.
Closed
Whether Close() ran (closed).
public virtual bool Closed { get; set; }
Property Value
Metadata
The metadata (metadata); a vector env sets autoreset_mode in it, which MakeVec and the observation wrappers check.
public virtual Metadata Metadata { get; set; }
Property Value
Exceptions
- ArgumentNullException
Thrown when assigning null.
NpRandom
The vector env's own generator (np_random), created from OS entropy on first read as Gymnasium does; a
seeded Reset of a vector env that draws itself replaces it. Assigning one shares it and makes
NpRandomSeed -1.
public virtual Generator NpRandom { get; set; }
Property Value
NpRandomSeed
The seed of NpRandom (np_random_seed), creating the generator from entropy on first read; -1 after one was assigned.
public virtual BigInteger NpRandomSeed { get; }
Property Value
NumEnvs
The number of sub-envs (num_envs).
public virtual int NumEnvs { get; protected set; }
Property Value
Exceptions
- AttributeError
Thrown by the getter while unset, as Python's annotated-only attribute does.
ObservationSpace
The batched observation space (observation_space), typed by the batched observation type (DR-21). The vector
env owns and disposes it, so the setter refuses a space another env not yet disposed owns (DR-40).
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.
RawNpRandom
Python's _np_random, read without creating a generator.
[PyName("_np_random")]
protected virtual Generator? RawNpRandom { get; set; }
Property Value
RawNpRandomSeed
Python's _np_random_seed, read without creating a generator.
[PyName("_np_random_seed")]
protected virtual BigInteger? RawNpRandomSeed { get; set; }
Property Value
RenderMode
The render mode (render_mode), the sub-envs' for SyncVectorEnv<TObs, TAct>.
public virtual string? RenderMode { get; protected set; }
Property Value
SingleActionSpace
One sub-env's action space (single_action_space).
public virtual Space SingleActionSpace { get; set; }
Property Value
Exceptions
- AttributeError
Thrown by the getter while unset.
SingleObservationSpace
One sub-env's observation space (single_observation_space), untyped: its elements may be of another type than the batch's.
public virtual Space SingleObservationSpace { get; set; }
Property Value
Exceptions
- AttributeError
Thrown by the getter while unset.
Spec
The spec MakeVec attached (spec), which the vector env's repr names.
public virtual EnvSpec? Spec { get; set; }
Property Value
Unwrapped
This vector env: the innermost one under its wrappers (unwrapped).
public virtual IVectorEnv Unwrapped { get; }
Property Value
Methods
AddInfo(Info, Info, int)
Gymnasium's _add_info: merges one sub-env's info into the vector infos. Each key gets a batch of the
sub-envs' values and a _key mask of the sub-envs that reported it; a nested dict is merged recursively,
and final_obs collects the sub-envs' observations unbatched.
protected Info AddInfo(Info vectorInfos, Info envInfo, int envNum)
Parameters
vectorInfosInfoThe infos merged so far; updated in place and returned.
envInfoInfoThe sub-env's info.
envNumintThe sub-env's index.
Returns
- Info
vectorInfos.
Remarks
A key's batch is created from the first value seen, as NumPy does: a number makes a (num_envs,) array of
its type (a .NET integer is a Python int, so int64; a double float64; a
bool bool; a 0-d array, NumPy's scalar, its own dtype, except a bool one, which NumPy does not
count as a number), an array of one or more dimensions makes a (num_envs, *shape) array of its dtype,
and anything else an object?[] (NumPy's object array). Later values are cast into the batch
as NumPy's assignment casts them: a float into an integer batch truncates, so mixing a reset info's
prob=1 with steps' prob=0.33 in one call loses the fraction, exactly as in Gymnasium.
Reference: gymnasium/vector/vector_env.py.
Exceptions
- ArgumentNullException
Thrown when
vectorInfosorenvInfois null.
Close()
Closes the vector env once (close()): CloseExtras(), then Closed; a second call does nothing.
public virtual void Close()
CloseExtras()
What a vector env releases on close (close_extras): its sub-envs, its windows. Nothing here.
protected virtual void CloseExtras()
ConvertActions(object?)
The untyped step's action conversion: the actions as given when they are TAct (or the
batched type is object), a .NET array as an NDArray for an array batch.
protected virtual TAct ConvertActions(object? actions)
Parameters
actionsobjectThe actions as given.
Returns
- TAct
The typed actions: the ones given, or a new array the step releases.
Exceptions
- TypeError
Thrown for actions of another type, naming both.
Dispose()
Closes the vector env and disposes the batched spaces it owns.
public void Dispose()
Dispose(bool)
Closes the vector env and, when disposing, the batched spaces: a vector env builds them by batching, so it owns them; the single spaces belong to the sub-envs and are left to them.
protected virtual void Dispose(bool disposing)
Parameters
Render()
Renders every sub-env (render()). The base vector env does not render.
public virtual IReadOnlyList<RenderResult>? Render()
Returns
- IReadOnlyList<RenderResult>
One result per sub-env, or null.
Exceptions
- NotImplementedError
Thrown here:
<repr> render function is not implemented.
Reset(IReadOnlyList<BigInteger?>, IReadOnlyDictionary<string, object?>?)
Resets every sub-env with a seed each (reset(seed=[...])). The base vector env takes only an integer seed:
Gymnasium's passes the list to seeding.np_random, which refuses it, so this raises that error unless a
vector env (SyncVectorEnv<TObs, TAct>) seeds its sub-envs one by one.
public virtual VectorResetResult<TObs> Reset(IReadOnlyList<BigInteger?> seeds, IReadOnlyDictionary<string, object?>? options = null)
Parameters
seedsIReadOnlyList<BigInteger?>One seed per sub-env.
optionsIReadOnlyDictionary<string, object>The reset options.
Returns
- VectorResetResult<TObs>
The batched first observations and the merged infos.
Exceptions
- Error
Thrown here:
Seed must be a python integer, actual type: <class 'list'>.
Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)
Resets every sub-env (reset(seed=seed, options=options)).
public abstract VectorResetResult<TObs> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)
Parameters
seedBigInteger?The seed, or null to keep the generators.
optionsIReadOnlyDictionary<string, object>The reset options.
Returns
- VectorResetResult<TObs>
The batched first observations and the merged infos; the caller owns the arrays.
SeedNpRandom(BigInteger?)
Seeds NpRandom as Gymnasium's base reset does: only when a seed is given; without one the
generator keeps its stream.
protected void SeedNpRandom(BigInteger? seed)
Parameters
seedBigInteger?The seed, or null.
Exceptions
- Error
Thrown for a negative seed, with Gymnasium's message.
Step(TAct)
Steps every sub-env with its action (step(actions)).
public abstract VectorStepResult<TObs> Step(TAct actions)
Parameters
actionsTActOne action per sub-env.
Returns
- VectorStepResult<TObs>
The batched transition; the caller owns its arrays.
ToString()
Python's repr: SyncVectorEnv(num_envs=3), or with the spec's id, SyncVectorEnv(CartPole-v1,
num_envs=3).
public override string ToString()
Returns
- string
The text.