Table of Contents

Class MultiDiscrete

Namespace
Gym.Spaces
Assembly
Gym.dll

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

nvec NDArray

The counts, any shape; read, never kept (the space stores a copy in its dtype).

dtype DType

The integer dtype; null is int64.

seed SpaceSeed?

An integer seed, a generator to share, or null.

start NDArray

The 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 nvec is null.

Error

Thrown when an integer seed is 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

nvec long[]

The number of values of each entry; every one must be positive.

dtype DType

The integer dtype of the elements; null is int64, Gymnasium's default.

seed SpaceSeed?

An integer seed, a generator to share, or null for a lazy entropy-seeded one.

start long[]

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 nvec is null.

Error

Thrown when an integer seed is 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

long

DType

The element dtype; never null for this space.

public DType DType { get; }

Property Value

DType

IsNpFlattenable

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

public override bool IsNpFlattenable { get; }

Property Value

bool

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

index int

The index; negative counts from the end, as in Python.

Property Value

Space<NDArray>

A new space, owned by the caller.

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

index int[]

One index per leading axis.

Property Value

Space<NDArray>

A new space, owned by the caller.

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

index string

The 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 index is 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

NDArray

Shape

The element shape, Nvec's.

public Shape Shape { get; }

Property Value

Shape

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

NDArray

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

x object

The candidate.

Returns

bool

true for an element.

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)

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

protected override void Dispose(bool disposing)

Parameters

disposing bool

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

Equals(MultiDiscrete?)

Gymnasium's ==: the same dtype, shape, counts and starts.

public bool Equals(MultiDiscrete? other)

Parameters

other MultiDiscrete

The other space.

Returns

bool

true when equal.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

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

jsonable object

A list of nested lists.

Returns

IList<NDArray>

New arrays, owned by the caller.

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

mask IReadOnlyList<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).

probability IReadOnlyList<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

mask object

null, 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.

probability object

null, 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

seed BigInteger?

Any non-negative integer, or null for a fresh generator from OS entropy.

Returns

BigInteger

The seed used: seed itself, 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 seed is 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

samples IEnumerable<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.