Class MultiDiscrete
The cartesian product of discrete spaces: every element is an integer array whose entry i lies in
[Start[i], Start[i] + Nvec[i]), such as a game controller's several buttons each with its own options.
public class MultiDiscrete : Space<NDArray>, IDisposable, IEquatable<MultiDiscrete>
- Inheritance
-
MultiDiscrete
- Implements
- Inherited Members
- Extension Methods
Remarks
The space owns Nvec and Start and releases them in Dispose().
Reference: gymnasium/spaces/multi_discrete.py.
Constructors
MultiDiscrete(NDArray, DType?, SpaceSeed?, NDArray?)
A multi-dimensional space: nvec's shape is the elements' shape.
public MultiDiscrete(NDArray nvec, DType? dtype = null, SpaceSeed? seed = null, NDArray? start = null)
Parameters
nvecNDArrayThe counts, any shape; read, never kept (the space stores a copy in its dtype).
dtypeDTypeThe integer dtype; null is int64.
seedSpaceSeed?An integer seed, a generator to share, or null.
startNDArrayThe smallest values, of
nvec's shape, or null for zeros; read, never kept.
Exceptions
- ValueError
Thrown for a non-integer dtype, a start of another shape, or a count that is not positive.
- ArgumentNullException
Thrown when
nvecis null.- Error
Thrown when an integer
seedis negative.
MultiDiscrete(long[], DType?, SpaceSeed?, long[]?)
The flat space of len(nvec) discrete values (Gymnasium's MultiDiscrete([5, 2, 2])).
public MultiDiscrete(long[] nvec, DType? dtype = null, SpaceSeed? seed = null, long[]? start = null)
Parameters
nveclong[]The number of values of each entry; every one must be positive.
dtypeDTypeThe integer dtype of the elements; null is int64, Gymnasium's default.
seedSpaceSeed?An integer seed, a generator to share, or null for a lazy entropy-seeded one.
startlong[]Each entry's smallest value, or null for zeros.
Exceptions
- ValueError
Thrown for a non-integer dtype, a start of another shape, or a count that is not positive, with Gymnasium's messages.
- ArgumentNullException
Thrown when
nvecis null.- Error
Thrown when an integer
seedis negative.
Properties
Count
The number of entries along the first axis (Gymnasium's len(space)), with Gymnasium's warning for a
multi-dimensional space, whose rows are then counted.
public long Count { get; }
Property Value
DType
The element dtype; never null for this space.
public DType DType { get; }
Property Value
IsNpFlattenable
Whether this space flattens to a Box (Gymnasium's is_np_flattenable).
public override bool IsNpFlattenable { get; }
Property Value
this[int]
The subspace at index (Gymnasium's space[index]): a Discrete for one entry
of a flat space, a MultiDiscrete for a row of a multi-dimensional one. The subspace starts from a
copy of this space's generator state, as in Gymnasium.
public Space<NDArray> this[int index] { get; }
Parameters
indexintThe index; negative counts from the end, as in Python.
Property Value
Exceptions
- IndexError
Thrown for an index outside the first axis.
this[int[]]
The subspace at a multi-dimensional index (Gymnasium's space[i, j]).
public Space<NDArray> this[params int[] index] { get; }
Parameters
indexint[]One index per leading axis.
Property Value
Exceptions
- IndexError
Thrown for an index outside its axis.
this[string]
The subspace at a NumPy index written as NumSharp's index string (Gymnasium's space[0:2, :] is
space["0:2, :"]): an index that selects one entry gives a Discrete, any other a
MultiDiscrete of the selected counts and starts.
public Space<NDArray> this[string index] { get; }
Parameters
indexstringThe index: integers, slices (
"1:3",":","::2"), commas between axes.
Property Value
- Space<NDArray>
A new space (never this one, even for
":"), owned by the caller, starting from a copy of this space's generator state.
Exceptions
- IndexError
Thrown for an index outside its axis.
- ArgumentNullException
Thrown when
indexis null.
Nvec
The number of values of each entry (Gymnasium's nvec), an array of the space's dtype and shape.
public NDArray Nvec { get; }
Property Value
Shape
The element shape, Nvec's.
public Shape Shape { get; }
Property Value
Start
The smallest value of each entry (Gymnasium's start), an array of the space's dtype and shape.
public NDArray Start { get; }
Property Value
Methods
Contains(object?)
Whether x is an element (Gymnasium's contains): an array (a .NET array or list is
converted first) of the space's shape, a dtype that casts safely to the space's, and every entry between its start
and its largest value.
public override bool Contains(object? x)
Parameters
xobjectThe candidate.
Returns
Remarks
Compares against start + (nvec - 1) rather than subtracting the start from x, which could
overflow a narrow dtype, as Gymnasium's own comment explains.
Dispose(bool)
protected override void Dispose(bool disposing)
Parameters
Equals(MultiDiscrete?)
Gymnasium's ==: the same dtype, shape, counts and starts.
public bool Equals(MultiDiscrete? other)
Parameters
otherMultiDiscreteThe other space.
Returns
Equals(object?)
Determines whether the specified object is equal to the current object.
public override bool Equals(object? obj)
Parameters
objobjectThe object to compare with the current object.
Returns
FromJsonable(object)
Converts nested lists back to arrays of the space's dtype (Gymnasium's np.array(sample, dtype=dtype)).
public override IList<NDArray> FromJsonable(object jsonable)
Parameters
jsonableobjectA list of nested lists.
Returns
Exceptions
- ArgumentException
Thrown for a value no array can be made from.
GetHashCode()
Serves as the default hash function.
public override int GetHashCode()
Returns
- int
A hash code for the current object.
Sample(IReadOnlyList<NDArray>?, IReadOnlyList<NDArray>?)
Draws one element, typed (DR-86, DR-97): Gymnasium's sample(mask, probability) with one array per entry,
Gymnasium's tuple as a list. For a one-dimensional space the list is that tuple; for a multi-dimensional one it
holds the entries in C order (row by row), which this method groups into Gymnasium's nested tuples. A call on a
MultiDiscrete reference binds this overload unless an argument is typed object;
it draws exactly what Sample(object?, object?) draws with the tuples.
public NDArray Sample(IReadOnlyList<NDArray>? mask = null, IReadOnlyList<NDArray>? probability = null)
Parameters
maskIReadOnlyList<NDArray>null, or one int8 array per entry, of length
nvec[i], with 1 for the values that may be drawn (all 0: that entry's start).probabilityIReadOnlyList<NDArray>null, or one float64 array per entry, of length
nvec[i], summing to 1.
Returns
- NDArray
A new array of the space's dtype and shape, owned by the caller.
Exceptions
- ValueError
Thrown when both masks are given, or when a multi-dimensional space gets a list whose length is not its number of entries (one-dimensional spaces report a wrong length with Gymnasium's assertion).
- AssertionError
Thrown for a malformed array, with Gymnasium's messages.
Sample(object?, object?)
Draws one element (Gymnasium's sample): each entry uniformly, or under a per-entry mask or probability
mask given as nested tuples (object?[]) of 1-D arrays matching Nvec's structure.
public override NDArray Sample(object? mask = null, object? probability = null)
Parameters
maskobjectnull, or a tuple with one int8 array of length
nvec[i]per entry (nested tuples for a multi-dimensional space); an all-zero array draws that entry's start.probabilityobjectnull, or the same structure of float64 arrays, each summing to 1.
Returns
- NDArray
A new array of the space's dtype and shape, owned by the caller.
Remarks
Unmasked, (random(nvec.shape) * nvec).astype(dtype) + start, Gymnasium's draw and arithmetic; masked,
one choice per entry in C order. Reference: gymnasium/spaces/multi_discrete.py.
Exceptions
- ValueError
Thrown when both masks are given.
- AssertionError
Thrown for a malformed mask or probability, with Gymnasium's messages.
Seed(BigInteger?)
Reseeds the space's generator (Gymnasium's seed), typed (DR-86): a simple space's seed is one integer, so
it comes back as a BigInteger where Seed(BigInteger?) returns it boxed.
public BigInteger Seed(BigInteger? seed = null)
Parameters
seedBigInteger?Any non-negative integer, or null for a fresh generator from OS entropy.
Returns
- BigInteger
The seed used:
seeditself, or the 128-bit entropy of an unseeded call, which reproduces it.
Remarks
Footgun: a call through a Space reference binds the untyped base method, which returns the same seed as an object.
Exceptions
- Error
Thrown when
seedis negative, with Gymnasium's message.- InvalidCastException
Thrown by a subclass whose seeding returns something other than one integer.
ToJsonable(IEnumerable<NDArray>)
Converts samples to nested lists (Gymnasium's sample.tolist()).
public override object ToJsonable(IEnumerable<NDArray> samples)
Parameters
samplesIEnumerable<NDArray>Samples of this space.
Returns
- object
One nested list per sample.
ToString()
Gymnasium's repr: MultiDiscrete([2 3 4]), with start=… when any start is not 0.
public override string ToString()
Returns
- string
The text.