Table of Contents

Class VectorEnv<TObs, TAct>

Namespace
Gym.Vector
Assembly
Gym.dll

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

TObs

The batched observation type, an element of ObservationSpace.

TAct

The 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

bool

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

Metadata

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

Generator

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

BigInteger

NumEnvs

The number of sub-envs (num_envs).

public virtual int NumEnvs { get; protected set; }

Property Value

int

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

Generator

RawNpRandomSeed

Python's _np_random_seed, read without creating a generator.

[PyName("_np_random_seed")]
protected virtual BigInteger? RawNpRandomSeed { get; set; }

Property Value

BigInteger?

RenderMode

The render mode (render_mode), the sub-envs' for SyncVectorEnv<TObs, TAct>.

public virtual string? RenderMode { get; protected set; }

Property Value

string

SingleActionSpace

One sub-env's action space (single_action_space).

public virtual Space SingleActionSpace { get; set; }

Property Value

Space

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

Space

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

EnvSpec

Unwrapped

This vector env: the innermost one under its wrappers (unwrapped).

public virtual IVectorEnv Unwrapped { get; }

Property Value

IVectorEnv

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

vectorInfos Info

The infos merged so far; updated in place and returned.

envInfo Info

The sub-env's info.

envNum int

The 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 vectorInfos or envInfo is 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

actions object

The 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

disposing bool

true from Dispose().

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

seeds IReadOnlyList<BigInteger?>

One seed per sub-env.

options IReadOnlyDictionary<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

seed BigInteger?

The seed, or null to keep the generators.

options IReadOnlyDictionary<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

seed BigInteger?

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

actions TAct

One 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.