Table of Contents

Class Space

Namespace
Gym.Spaces
Assembly
Gym.dll

The untyped view of every space: the set an env's actions or observations belong to. It records their Shape and DType (when its elements are arrays), tests membership (Contains(object?)) and draws random members (Sample(object?, object?)) from a generator of its own, so seeding a space never disturbs the env's stream. Code that knows the element type uses Space<T>, which every space derives from.

public abstract class Space : IDisposable
Inheritance
Space
Implements
Derived
Inherited Members
Extension Methods

Remarks

A space owns the arrays it holds (a Box's bounds) and releases them in Dispose(); an env disposes its spaces when it is disposed (D19). Samples are new arrays the caller owns.

Not thread-safe: the generator is not synchronized, so sample a space from one thread at a time, as Gymnasium's single-threaded envs do. Reference: gymnasium/spaces/space.py.

Properties

DType

The element type of every element, as NumSharp's DType (Gymnasium's dtype), or null for spaces whose elements are not arrays. Compare it with ==, which also accepts a Type, an NPTypeCode or a NumPy dtype string.

public DType? DType { get; }

Property Value

DType

Remarks

Beware np.@byte: it is int8 (NumPy's C char), not uint8; uint8 is np.uint8.

IsNpFlattenable

Whether this space flattens to a Box (Gymnasium's is_np_flattenable).

public abstract bool IsNpFlattenable { get; }

Property Value

bool

NpRandom

The generator this space samples from (Gymnasium's np_random), created from OS entropy on first use when none was seeded or shared. Assigning one shares it, as Gymnasium's space._np_random = rng does.

public virtual Generator NpRandom { get; set; }

Property Value

Generator

Remarks

Lazily created because seeding costs a SeedSequence, which a space that is never sampled should not pay; reading it is therefore not free the first time, and it draws OS entropy.

NpRandomOrNull

The generator if one exists, without creating it (Gymnasium's _np_random); for code that must not draw OS entropy just to look, such as a parity check of an unseeded space.

public virtual Generator? NpRandomOrNull { get; }

Property Value

Generator

Shape

The shape of every element (Gymnasium's shape), or null for spaces whose elements are not arrays (Tuple, Dict, Text, ...).

public Shape? Shape { get; }

Property Value

Shape?

Methods

Clone()

A deep copy of this space, .NET's name for DeepCopy() (DR-81): the same parameters, copies of every array, subspace and generator, so drawing from the copy never moves the original.

public Space Clone()

Returns

Space

The copy; the caller owns it, and it belongs to no env until one takes it (DR-40).

Remarks

The two names are one copy: a space that overrides DeepCopyCore() changes both. It is deep, unlike .NET's usual shallow Clone convention and unlike 0.2's Dict.Clone, because a space shares nothing safely: a shallow copy would draw from, and dispose, the original's arrays and generator.

Contains(object?)

Whether x is an element of this space (Gymnasium's contains and x in space). Values of the wrong kind return false rather than throwing, as in Gymnasium.

public abstract bool Contains(object? x)

Parameters

x object

The candidate.

Returns

bool

true for an element.

CopyGenerator(Generator)

A generator with the same state as generator and no link to it (Python's deepcopy(np_random)): both draw the same next values, then go their own ways.

public static Generator CopyGenerator(Generator generator)

Parameters

generator Generator

The generator to copy.

Returns

Generator

The copy.

Exceptions

ValueError

Thrown for a generator whose bit generator is not a PCG64, which Gym.NET never creates.

DeepCopy()

A deep copy of this space (Python's copy.deepcopy(space), which Gymnasium's batching relies on): the same parameters, copies of every array, subspace and generator, so drawing from the copy never moves the original.

public Space DeepCopy()

Returns

Space

The copy; the caller owns it.

Remarks

The default copies member by member (MemberwiseClone) and then replaces every array (a new buffer), generator (the same state, independent), subspace (deep-copied) and collection of those in the copy's fields, so a custom space gets a correct deep copy without code of its own. A custom field type it does not know is shared, like any other object PyCopy cannot copy; override DeepCopyCore() for such a space.

DeepCopyCore()

The copying behind DeepCopy(); see its remarks.

protected virtual Space DeepCopyCore()

Returns

Space

The copy.

Dispose()

Releases the arrays this space owns; idempotent. The space must not be used afterwards.

public void Dispose()

Remarks

Ownership ends with it (DR-40): a disposed space belongs to no env, though no env can use it either.

Dispose(bool)

Releases what a derived space owns (a Box's bounds); called once, by Dispose().

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true from Dispose(); no space has a finalizer.

FromJsonable(object)

Converts JSON-friendly data back to a batch of samples (Gymnasium's from_jsonable), untyped.

public IList<object?> FromJsonable(object jsonable)

Parameters

jsonable object

Data ToJsonable(IEnumerable<object?>) produced.

Returns

IList<object>

The samples, boxed.

Exceptions

ArgumentException

Thrown when the data is not in the form this space's to_jsonable produces.

Sample(object?, object?)

Draws a random element, untyped: what Sample(object?, object?) returns, boxed. A mask restricts which elements are drawn and a probability mask weights them; each space documents the forms it accepts.

public object? Sample(object? mask = null, object? probability = null)

Parameters

mask object

A space-specific mask (an int8 array for Discrete), or null.

probability object

A space-specific probability mask (a float64 array for Discrete), or null.

Returns

object

The element; arrays are new and owned by the caller.

Seed(IReadOnlyDictionary<string, object?>)

Seeds a Dict space's subspaces by key (Gymnasium's seed({"a": 1, ...})); the keys must be the space's.

public object Seed(IReadOnlyDictionary<string, object?> seeds)

Parameters

seeds IReadOnlyDictionary<string, object>

One seed per key.

Returns

object

The seeds used, by key.

Exceptions

Error

Thrown for a space that is not a Dict, with Gymnasium's message.

ValueError

Thrown by a Dict for keys that are not its own.

Seed(IReadOnlyList<object?>)

Seeds a composite space's subspaces one by one (Gymnasium's seed([s0, s1, ...])): one seed per subspace, each an integer, null, or itself a list or dictionary for a composite subspace.

public object Seed(IReadOnlyList<object?> seeds)

Parameters

seeds IReadOnlyList<object>

The seeds; OneOf, Sequence and Graph take their own seed first.

Returns

object

The seeds used, one per subspace, as Gymnasium's tuple.

Exceptions

Error

Thrown for a space that is not a composite, with Gymnasium's message.

ValueError

Thrown by a composite for a list of the wrong length.

Seed(BigInteger?)

Reseeds the generator (Gymnasium's seed): with a value, a fresh Generator(PCG64(SeedSequence(seed))) that draws what Gymnasium's space draws after space.seed(seed); without one, a fresh generator from OS entropy. A generator the space shared is replaced, never reseeded, so the env's stream is left untouched.

public object Seed(BigInteger? seed = null)

Parameters

seed BigInteger?

Any non-negative integer (Gymnasium's seeds are unbounded Python ints), or null.

Returns

object

The seed used: seed itself, or the 128-bit entropy of an unseeded call, which reproduces it. Composite spaces return one seed per subspace (a list, or a dict for Dict), as Gymnasium's do.

Remarks

Exceptions

Error

Thrown when seed is negative, with Gymnasium's message.

SeedCore(BigInteger?)

The seeding behind Seed(BigInteger?); composite spaces override it to seed their subspaces. Called from the constructor for an integer seed, so an override must not rely on state its own constructor sets after the base call (composites pass null to the base and seed in their own constructor for this reason).

protected virtual object SeedCore(BigInteger? seed)

Parameters

seed BigInteger?

The seed, or null for entropy.

Returns

object

The seed(s) used.

Exceptions

Error

Thrown when seed is negative.

SeedDictCore(IReadOnlyDictionary<string, object?>)

The dictionary seeding behind Seed(IReadOnlyDictionary<string, object?>); the base refuses through SeedTypeError(object?), so only Dict overrides it.

protected virtual object SeedDictCore(IReadOnlyDictionary<string, object?> seeds)

Parameters

seeds IReadOnlyDictionary<string, object>

The seeds.

Returns

object

The seeds used.

Exceptions

Error

Always, for a simple space.

TypeError

Always, for a composite that is not a Dict.

SeedListCore(IReadOnlyList<object?>)

The list seeding behind Seed(IReadOnlyList<object?>). The base refuses, as Gymnasium's seeding.np_random refuses a list given to a simple space.

protected virtual object SeedListCore(IReadOnlyList<object?> seeds)

Parameters

seeds IReadOnlyList<object>

The seeds.

Returns

object

The seeds used.

Exceptions

Error

Always, for a simple space: Seed must be a python integer, actual type: <class 'list'>.

TypeError

Always, for a composite that takes no list (a Dict), through SeedTypeError(object?).

SeedTypeError(object?)

The error for a seed of a form this space does not take, which the caller throws. The base gives what Gymnasium's seeding.np_random raises for a simple space; each composite overrides it with the TypeError its own seed raises (the texts differ per space).

protected virtual Exception SeedTypeError(object? seed)

Parameters

seed object

The refused seed, for its Python type in the message.

Returns

Exception

The exception to throw; never null.

SeedWith(object?)

Seeds with a value of any form, as Python's dynamically typed space.seed(seed) receives it: an integer (any width, or a BigInteger; a bool is Python's int too), null, a list or tuple, or a string-keyed dictionary. Composite spaces use it for nested seeds.

public object SeedWith(object? seed)

Parameters

seed object

The seed.

Returns

object

The seed(s) used.

Remarks

A 0-d array (a NumPy scalar such as np.int64(5)) is refused like any other non-int, because Gymnasium's seeding checks isinstance(seed, int), which a NumPy scalar fails; convert it first.

Exceptions

Error

Thrown for a negative seed, or by a simple space for a form it does not take, with Gymnasium's message.

TypeError

Thrown by a composite for a form it does not take (SeedTypeError(object?)).

SetNpRandom(Generator?)

Replaces the generator with one the caller made, for composite spaces seeding themselves; never shares by accident.

protected void SetNpRandom(Generator? generator)

Parameters

generator Generator

The generator; null forgets it, so the next use draws entropy.

ToJsonable(IEnumerable<object?>)

Converts a batch of samples to JSON-friendly data (Gymnasium's to_jsonable), untyped: usually one value per sample (a list), but a composite may arrange the batch otherwise, as Dict's dict of per-key lists does, which is why the result is an object.

public object ToJsonable(IEnumerable<object?> samples)

Parameters

samples IEnumerable<object>

Samples of this space.

Returns

object

The JSON-friendly data: lists, numbers, strings and string-keyed dictionaries.

Exceptions

InvalidCastException

Thrown when a sample is not of this space's element type.