Table of Contents

Class Box

Namespace
Gym.Spaces
Assembly
Gym.dll

A possibly unbounded box in R^n: every element is an array of Shape and DType whose entries lie within Low and High (each interval closed, or open to infinity). It describes continuous observations and actions, such as CartPole's observation; an integer dtype makes it a discrete grid.

public class Box : Space<NDArray>, IDisposable, IEquatable<Box>
Inheritance
Box
Implements
Inherited Members
Extension Methods

Remarks

The box owns Low, High, BoundedBelow and BoundedAbove and releases them in Dispose(). They are exposed as they are, so writing into them changes the space, as writing into Gymnasium's space.low does.

Reference: gymnasium/spaces/box.py.

Constructors

Box(NDArray, NDArray, DType, SpaceSeed?)

0.2's new Box(lowArray, highArray, np.float32), the dtype third, kept so 0.2 code compiles until 2.0 (DR-58): the same box as new Box(low, high, dtype: dtype), of the bounds' shape.

[Obsolete("0.2's argument order: write new Box(low, high, dtype: dtype); the third positional argument is the shape. Removed in 2.0 with Gym.Legacy.")]
public Box(NDArray low, NDArray high, DType dType, SpaceSeed? seed = null)

Parameters

low NDArray

The lower bounds; read, never kept.

high NDArray

The upper bounds; read, never kept.

dType DType

The dtype. Named as 0.2 named it, so 1.0's dtype: calls never bind here: with the same name, a named dtype: argument would prefer this overload (DType over DType?) or turn ambiguous.

seed SpaceSeed?

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

Remarks

Footgun: next to it, new Box(low, high, null) is ambiguous (a Shape or a dtype); name the argument.

Exceptions

ValueError

Thrown as the shape-taking constructor throws, with Gymnasium's messages.

Error

Thrown when an integer seed is negative.

Box(NDArray, NDArray, Shape?, DType?, SpaceSeed?)

A box with per-entry bounds: the shape is the arrays' (they must agree), or shape when given.

public Box(NDArray low, NDArray high, Shape? shape = null, DType? dtype = null, SpaceSeed? seed = null)

Parameters

low NDArray

The lower bounds; read, never kept (the box stores a copy in its dtype).

high NDArray

The upper bounds; read, never kept.

shape Shape?

The shape, or null to take the bounds'.

dtype DType

The dtype; null is float32.

seed SpaceSeed?

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

Exceptions

ValueError

Thrown for shapes that differ, a NaN bound, a bound outside the dtype, an infinite bound of an unsigned or bool dtype, or low > high.

Error

Thrown when an integer seed is negative.

Box(NDArray, double, Shape?, DType?, SpaceSeed?)

A box with per-entry lower bounds and a scalar upper bound.

public Box(NDArray low, double high, Shape? shape = null, DType? dtype = null, SpaceSeed? seed = null)

Parameters

low NDArray

The lower bounds; read, never kept.

high double

The upper bound of every entry.

shape Shape?

The shape, or null to take low's.

dtype DType

The dtype; null is float32.

seed SpaceSeed?

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

Exceptions

ValueError

Thrown as for the other constructors.

Error

Thrown when an integer seed is negative.

Box(double, NDArray, Shape?, DType?, SpaceSeed?)

A box with a scalar lower bound and per-entry upper bounds.

public Box(double low, NDArray high, Shape? shape = null, DType? dtype = null, SpaceSeed? seed = null)

Parameters

low double

The lower bound of every entry.

high NDArray

The upper bounds; read, never kept.

shape Shape?

The shape, or null to take high's.

dtype DType

The dtype; null is float32.

seed SpaceSeed?

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

Exceptions

ValueError

Thrown as for the other constructors.

Error

Thrown when an integer seed is negative.

Box(double, double, DType, SpaceSeed?)

0.2's new Box(low, high, np.float32), the dtype third, kept so 0.2 code compiles until 2.0 (DR-58): the same box as new Box(low, high, dtype: dtype), of shape (1,), Gymnasium's for scalar bounds.

[Obsolete("0.2's argument order: write new Box(low, high, dtype: dtype); the third positional argument is the shape. Removed in 2.0 with Gym.Legacy.")]
public Box(double low, double high, DType dType, SpaceSeed? seed = null)

Parameters

low double

The lower bound of every entry.

high double

The upper bound of every entry.

dType DType

The dtype. Named as 0.2 named it, so 1.0's dtype: calls never bind here: with the same name, a named dtype: argument would prefer this overload (DType over DType?) or turn ambiguous.

seed SpaceSeed?

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

Remarks

Footgun: next to it, new Box(low, high, null) is ambiguous (a Shape or a dtype); name the argument.

Exceptions

ValueError

Thrown as the shape-taking constructor throws, with Gymnasium's messages.

Error

Thrown when an integer seed is negative.

Box(double, double, Shape?, DType?, SpaceSeed?)

A box whose every entry lies in [low, high] (scalar bounds).

public Box(double low, double high, Shape? shape = null, DType? dtype = null, SpaceSeed? seed = null)

Parameters

low double

The lower bound of every entry; double.NegativeInfinity for none (a signed integer dtype stores its minimum).

high double

The upper bound of every entry; double.PositiveInfinity for none.

shape Shape?

The shape; null is (1,), as for Gymnasium's scalar bounds.

dtype DType

The dtype: integer, floating or bool; null is float32, Gymnasium's default.

seed SpaceSeed?

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

Exceptions

ValueError

Thrown for a NaN bound, a bound outside the dtype, an infinite bound of an unsigned or bool dtype, low > high, or a dtype that is not integer, floating or bool, with Gymnasium's messages.

Error

Thrown when an integer seed is negative.

Properties

BoundedAbove

Where the box is bounded above (Gymnasium's bounded_above, high < inf).

public NDArray BoundedAbove { get; }

Property Value

NDArray

BoundedBelow

Where the box is bounded below: a bool array of Shape (Gymnasium's bounded_below, -inf < low).

public NDArray BoundedBelow { get; }

Property Value

NDArray

DType

The element dtype; never null for a box.

public DType DType { get; }

Property Value

DType

High

The upper bounds (Gymnasium's high).

public NDArray High { get; }

Property Value

NDArray

IsNpFlattenable

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

public override bool IsNpFlattenable { get; }

Property Value

bool

Low

The lower bounds, an array of Shape and DType (Gymnasium's low); a signed integer box stores its dtype's minimum where the bound was -inf.

public NDArray Low { get; }

Property Value

NDArray

Shape

The shape of every element; never null for a box.

public Shape Shape { get; }

Property Value

Shape

Methods

ArrayShortRepr(NDArray)

A short text for an array (Gymnasium's array_short_repr), what a box's repr prints for each bound: the single value when every entry is the same (-1.0), else the whole array ([-1. -2.]).

public static string ArrayShortRepr(NDArray array)

Parameters

array NDArray

The array; an empty one prints as [].

Returns

string

The text.

Remarks

Reads every element twice (a min and a max), so it costs two passes over a large array. Reference: gymnasium/spaces/box.py (array_short_repr).

Exceptions

ArgumentNullException

Thrown when array is null.

Contains(object?)

Whether x is an element (Gymnasium's contains): an array whose dtype casts safely to the box's, of the box's shape, inside the bounds. Anything else is converted to an array of the box's dtype first, with Gymnasium's warning, and is not an element when it cannot be.

public override bool Contains(object? x)

Parameters

x object

The candidate: an NDArray, a .NET array or list, or a number.

Returns

bool

true for an element.

Remarks

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(Box?)

Gymnasium's ==: the same shape and dtype, and bounds equal within np.allclose.

public bool Equals(Box? other)

Parameters

other Box

The other box.

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 box's dtype (Gymnasium's from_jsonable, np.asarray(sample, dtype)).

public override IList<NDArray> FromJsonable(object jsonable)

Parameters

jsonable object

Values ToJsonable(IEnumerable<NDArray>) produced, or numbers.

Returns

IList<NDArray>

New arrays, owned by the caller.

Exceptions

ArgumentException

Thrown for a value that cannot become an array.

GetHashCode()

A hash over the shape and dtype, which equal boxes share (their bounds only need to be close).

public override int GetHashCode()

Returns

int

The hash.

IsBounded(BoundedMannerEnum)

The enum spelling of IsBounded(string), kept from Gym.NET's earlier API.

public bool IsBounded(BoundedMannerEnum manner)

Parameters

manner BoundedMannerEnum

The side to check.

Returns

bool

true when bounded in that manner.

Exceptions

ArgumentOutOfRangeException

Thrown for a value outside the enum.

IsBounded(string)

Whether the box is bounded (Gymnasium's is_bounded): on both sides, below or above, in every entry.

public bool IsBounded(string manner = "both")

Parameters

manner string

"both", "below" or "above".

Returns

bool

true when bounded in that manner.

Exceptions

ValueError

Thrown for another manner: manner is not in {'below', 'above', 'both'}, actual value: ….

IsFloatInteger(object?)

Whether a value is a number Gymnasium takes as a scalar bound (its is_float_integer): a Python int or float (any .NET integer, an enum, a BigInteger, double), a NumPy integer or floating scalar (float, Half, a 0-d integer or float array), but never a bool, which Python counts as an int and Gymnasium excludes by hand.

public static bool IsFloatInteger(object? var)

Parameters

var object

The value.

Returns

bool

true for an integer or floating scalar that is not a boolean.

Remarks

decimal has no Python or NumPy counterpart Gymnasium accepts and is refused. Reference: gymnasium/spaces/box.py (is_float_integer).

Sample()

Draws one element, typed (DR-86, DR-97): Gymnasium's box takes no mask or probability (it raises for either), so its typed form takes nothing. A call box.Sample() on a Box reference binds this overload; it draws exactly what Sample(object?, object?) draws without masks.

public NDArray Sample()

Returns

NDArray

A new array of Shape and DType, owned by the caller.

Sample(object?, object?)

Draws one element (Gymnasium's sample), each entry from the distribution its interval calls for: uniform on [a, b], a shifted exponential on [a, inf), a shifted negative exponential on (-inf, b], a standard normal on (-inf, inf). Integer boxes floor the draw (from [a, b + 1)) and clip it to the dtype.

public override NDArray Sample(object? mask = null, object? probability = null)

Parameters

mask object

Must be null: a box takes no mask.

probability object

Must be null.

Returns

NDArray

A new array of Shape and DType, owned by the caller.

Remarks

The generator calls are Gymnasium's, in its order and sizes (one normal, two exponential and one uniform call over the entries of each category in C order), and the arithmetic is its float64 arithmetic, so a box seeded like Gymnasium's draws the same bits. Reference: gymnasium/spaces/box.py.

Exceptions

Error

Thrown when a mask or a probability mask is given, with Gymnasium's message.

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 to_jsonable, sample.tolist()).

public override object ToJsonable(IEnumerable<NDArray> samples)

Parameters

samples IEnumerable<NDArray>

Samples of this box.

Returns

object

One nested list per sample.

ToString()

Gymnasium's repr: Box(low, high, shape, dtype), each bound shortened to its value when it is the same for every entry: Box(-1.0, 2.0, (3, 4), float32), Box([-1. -2.], [2. 4.], (2,), float32).

public override string ToString()

Returns

string

The text.

Operators

operator ==(Box?, Box?)

Value equality, as Equals(Box?).

public static bool operator ==(Box? left, Box? right)

Parameters

left Box

A box.

right Box

A box.

Returns

bool

true when equal.

operator !=(Box?, Box?)

Value inequality.

public static bool operator !=(Box? left, Box? right)

Parameters

left Box

A box.

right Box

A box.

Returns

bool

true when not equal.