Class Space
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
-
Space<T>
- 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
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
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
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
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
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
xobjectThe candidate.
Returns
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
generatorGeneratorThe 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)
protected virtual void Dispose(bool disposing)
Parameters
FromJsonable(object)
Converts JSON-friendly data back to a batch of samples (Gymnasium's from_jsonable), untyped.
public IList<object?> FromJsonable(object jsonable)
Parameters
jsonableobjectData ToJsonable(IEnumerable<object?>) produced.
Returns
Exceptions
- ArgumentException
Thrown when the data is not in the form this space's
to_jsonableproduces.
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
maskobjectA space-specific mask (an int8 array for Discrete), or null.
probabilityobjectA 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
seedsIReadOnlyDictionary<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
Dictfor 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
seedsIReadOnlyList<object>The seeds;
OneOf,SequenceandGraphtake 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
seedBigInteger?Any non-negative integer (Gymnasium's seeds are unbounded Python ints), or null.
Returns
- object
The seed used:
seeditself, or the 128-bit entropy of an unseeded call, which reproduces it. Composite spaces return one seed per subspace (a list, or a dict forDict), as Gymnasium's do.
Remarks
Reference: gymnasium/spaces/space.py.
Exceptions
- Error
Thrown when
seedis 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
seedBigInteger?The seed, or null for entropy.
Returns
- object
The seed(s) used.
Exceptions
- Error
Thrown when
seedis 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
seedsIReadOnlyDictionary<string, object>The seeds.
Returns
- object
The seeds used.
Exceptions
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
seedsIReadOnlyList<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
seedobjectThe refused seed, for its Python type in the message.
Returns
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
seedobjectThe 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
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
samplesIEnumerable<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.