Table of Contents

Class Discrete

Namespace
Gym.Spaces
Assembly
Gym.dll

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

n long

The number of elements; must be positive.

seed SpaceSeed?

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.

start long

The smallest element.

dtype DType

The 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 n is not positive: n (counts) have to be positive, actual value: 0.

TypeError

Thrown when dtype is not an integer dtype.

OverflowError

Thrown when n or start does not fit dtype, as NumPy's OverflowError.

Error

Thrown when an integer seed is negative.

Properties

DType

The element dtype; never null for a discrete space (int64 by default).

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

N

The number of elements (Gymnasium's n, a scalar of the space's dtype).

public long N { get; }

Property Value

long

Shape

The shape of every element, ().

public Shape Shape { get; }

Property Value

Shape

Start

The smallest element (Gymnasium's start, a scalar of the space's dtype).

public long Start { get; }

Property Value

long

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

x long

The candidate element.

Returns

bool

true when it is an element.

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

x object

The candidate.

Returns

bool

true for an element; anything else, a 0-d boolean or floating array included, is false.

Remarks

Equals(Discrete?)

Gymnasium's ==: the same N, Start and dtype.

public bool Equals(Discrete? other)

Parameters

other Discrete

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 integers back to 0-d arrays of the space's dtype (Gymnasium's from_jsonable).

public override IList<NDArray> FromJsonable(object jsonable)

Parameters

jsonable object

Integers, as ToJsonable(IEnumerable<NDArray>) made them.

Returns

IList<NDArray>

New 0-d arrays, owned by the caller.

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

mask NDArray

null, or an int8 array of shape (n,) with 1 for the elements that may be drawn (all 0: the start).

probability NDArray

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

mask object

null, or an int8 array of shape (n,) whose 1s mark the allowed elements and 0s the others; when nothing is allowed, Start is returned.

probability object

null, or a float64 array of shape (n,) with values in [0, 1] summing to 1 (within np.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

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.

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

action object

A boxed integer of any width, a bool, an enum member, or a 0-d integer array.

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

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

action object

The candidate.

value long

The integer when true is returned; otherwise 0.

Returns

bool

true when the candidate denotes an integer.

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.