Class Discrete
The integers {Start, ..., Start + N - 1}: a categorical action or observation, such as CartPole's two
pushes or FrozenLake's 16 cells. An element is a 0-d array of DType (int64 by default), Gym.NET's
stand-in for NumPy's np.int64 scalar (DR-08).
public class Discrete : Space<NDArray>, IDisposable, IEquatable<Discrete>
- Inheritance
-
Discrete
- Implements
- Inherited Members
- Extension Methods
Remarks
The shape is (), as in Gymnasium. Code that read the number of actions from Shape.Size must read
N instead (B-03).
Reference: gymnasium/spaces/discrete.py.
Constructors
Discrete(long, SpaceSeed?, long, DType?)
The space {start, ..., start + n - 1} (Gymnasium's Discrete(n, seed, start, dtype)).
public Discrete(long n, SpaceSeed? seed = null, long start = 0, DType? dtype = null)
Parameters
nlongThe number of elements; must be positive.
seedSpaceSeed?An integer seed for the space's own generator (it then samples what Gymnasium's
Discrete(n, seed=seed)samples), a generator to share, or null for one drawn from OS entropy on first use.startlongThe smallest element.
dtypeDTypeThe integer dtype of the elements and of N and Start; null is int64, Gymnasium's default. Samples are drawn in this dtype, so another dtype draws other values.
Exceptions
- ValueError
Thrown when
nis not positive:n (counts) have to be positive, actual value: 0.- TypeError
Thrown when
dtypeis not an integer dtype.- OverflowError
Thrown when
norstartdoes not fitdtype, as NumPy'sOverflowError.- Error
Thrown when an integer
seedis negative.
Properties
DType
The element dtype; never null for a discrete space (int64 by default).
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
N
The number of elements (Gymnasium's n, a scalar of the space's dtype).
public long N { get; }
Property Value
Shape
The shape of every element, ().
public Shape Shape { get; }
Property Value
Start
The smallest element (Gymnasium's start, a scalar of the space's dtype).
public long Start { get; }
Property Value
Methods
Contains(long)
Whether x lies in [Start, Start + N), as a Python int of the dtype's range.
public bool Contains(long x)
Parameters
xlongThe candidate element.
Returns
Contains(object?)
Whether x is an element (Gymnasium's contains): a .NET integer, bool or
enum member (a Python int: it must fit the dtype), or a 0-d integer array whose dtype casts safely to the
space's, with a value in [Start, Start + N).
public override bool Contains(object? x)
Parameters
xobjectThe candidate.
Returns
Remarks
Reference: gymnasium/spaces/discrete.py.
Equals(Discrete?)
public bool Equals(Discrete? other)
Parameters
otherDiscreteThe 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 integers back to 0-d arrays of the space's dtype (Gymnasium's from_jsonable).
public override IList<NDArray> FromJsonable(object jsonable)
Parameters
jsonableobjectIntegers, as ToJsonable(IEnumerable<NDArray>) made them.
Returns
Exceptions
- ArgumentException
Thrown for a value that is not an integer.
GetHashCode()
Serves as the default hash function.
public override int GetHashCode()
Returns
- int
A hash code for the current object.
Sample(NDArray?, NDArray?)
Draws one element, typed (DR-86, DR-97): Gymnasium's sample(mask, probability) with both masks as arrays.
A call on a Discrete reference binds this overload unless an argument is typed
object; it draws exactly what Sample(object?, object?) draws.
public NDArray Sample(NDArray? mask = null, NDArray? probability = null)
Parameters
maskNDArraynull, or an int8 array of shape
(n,)with 1 for the elements that may be drawn (all 0: the start).probabilityNDArraynull, or a float64 array of shape
(n,)with values in[0, 1]summing to 1.
Returns
- NDArray
A new 0-d array of the space's dtype, owned by the caller.
Exceptions
- ValueError
Thrown when both masks are given.
- AssertionError
Thrown for a mask or probability of the wrong dtype, shape or values, with Gymnasium's messages.
Sample(object?, object?)
Draws one element (Gymnasium's sample): uniformly, uniformly among the elements a mask allows, or by the
probabilities of a probability mask.
public override NDArray Sample(object? mask = null, object? probability = null)
Parameters
maskobjectnull, or an int8 array of shape
(n,)whose1s mark the allowed elements and0s the others; when nothing is allowed, Start is returned.probabilityobjectnull, or a float64 array of shape
(n,)with values in[0, 1]summing to 1 (withinnp.isclose).
Returns
- NDArray
A new 0-d array of the space's dtype, owned by the caller.
Remarks
The three branches make Gymnasium's generator calls, choice(np.where(mask == 1)[0]),
choice(np.arange(n, dtype=dtype), p=probability) and integers(n, dtype=dtype), so a space seeded
like Gymnasium's draws the same values. Reference: gymnasium/spaces/discrete.py.
Exceptions
- ValueError
Thrown when both masks are given.
- AssertionError
Thrown for a mask or probability of the wrong type, dtype, shape or values, with Gymnasium's assertion 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.
ToInt64(object)
Converts an action given to Env.Step(object) to the integer it denotes; envs call this rather than casting,
because (int)action unboxes exactly and throws for a long or a 0-d array.
public static long ToInt64(object action)
Parameters
Returns
- long
The integer.
Exceptions
- ArgumentException
Thrown when the action is null, not an integer, or an array that is not 0-d.
- OverflowException
Thrown when an unsigned 64-bit action exceeds MaxValue.
ToJsonable(IEnumerable<NDArray>)
Converts samples to Python ints (Gymnasium's to_jsonable: [int(x) for x in sample_n]), as
longs.
public override object ToJsonable(IEnumerable<NDArray> samples)
Parameters
samplesIEnumerable<NDArray>Samples of this space.
Returns
- object
One integer per sample.
Exceptions
- ArgumentException
Thrown for a sample that is not a 0-d integer array.
ToString()
Gymnasium's repr: Discrete(2), with start=… when it is not 0 and dtype=… when it is
not int64.
public override string ToString()
Returns
- string
The text.
TryToInt64(object?, out long)
The non-throwing form of ToInt64(object), for membership tests and action conversion.
public static bool TryToInt64(object? action, out long value)
Parameters
Returns
Remarks
Accepts what Gymnasium's envs accept as a discrete action: Python ints (a bool is one, as
Python's bool subclasses int) and 0-d arrays of an integer dtype. A 0-d boolean array is rejected,
because np.bool_ is not an np.integer.
Exceptions
- OverflowException
Thrown when an unsigned 64-bit value exceeds MaxValue.