Class Box
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
lowNDArrayThe lower bounds; read, never kept.
highNDArrayThe upper bounds; read, never kept.
dTypeDTypeThe dtype. Named as 0.2 named it, so 1.0's
dtype:calls never bind here: with the same name, a nameddtype:argument would prefer this overload (DTypeoverDType?) or turn ambiguous.seedSpaceSeed?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
seedis 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
lowNDArrayThe lower bounds; read, never kept (the box stores a copy in its dtype).
highNDArrayThe upper bounds; read, never kept.
shapeShape?The shape, or null to take the bounds'.
dtypeDTypeThe dtype; null is float32.
seedSpaceSeed?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
seedis 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
lowNDArrayThe lower bounds; read, never kept.
highdoubleThe upper bound of every entry.
shapeShape?The shape, or null to take
low's.dtypeDTypeThe dtype; null is float32.
seedSpaceSeed?An integer seed, a generator to share, or null.
Exceptions
- ValueError
Thrown as for the other constructors.
- Error
Thrown when an integer
seedis 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
lowdoubleThe lower bound of every entry.
highNDArrayThe upper bounds; read, never kept.
shapeShape?The shape, or null to take
high's.dtypeDTypeThe dtype; null is float32.
seedSpaceSeed?An integer seed, a generator to share, or null.
Exceptions
- ValueError
Thrown as for the other constructors.
- Error
Thrown when an integer
seedis 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
lowdoubleThe lower bound of every entry.
highdoubleThe upper bound of every entry.
dTypeDTypeThe dtype. Named as 0.2 named it, so 1.0's
dtype:calls never bind here: with the same name, a nameddtype:argument would prefer this overload (DTypeoverDType?) or turn ambiguous.seedSpaceSeed?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
seedis 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
lowdoubleThe lower bound of every entry;
double.NegativeInfinityfor none (a signed integer dtype stores its minimum).highdoubleThe upper bound of every entry;
double.PositiveInfinityfor none.shapeShape?The shape; null is
(1,), as for Gymnasium's scalar bounds.dtypeDTypeThe dtype: integer, floating or bool; null is float32, Gymnasium's default.
seedSpaceSeed?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
seedis negative.
Properties
BoundedAbove
Where the box is bounded above (Gymnasium's bounded_above, high < inf).
public NDArray BoundedAbove { get; }
Property Value
BoundedBelow
Where the box is bounded below: a bool array of Shape (Gymnasium's bounded_below, -inf < low).
public NDArray BoundedBelow { get; }
Property Value
DType
The element dtype; never null for a box.
public DType DType { get; }
Property Value
High
The upper bounds (Gymnasium's high).
public NDArray High { get; }
Property Value
IsNpFlattenable
Whether this space flattens to a Box (Gymnasium's is_np_flattenable).
public override bool IsNpFlattenable { get; }
Property Value
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
Shape
The shape of every element; never null for a box.
public Shape Shape { get; }
Property Value
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
arrayNDArrayThe 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
arrayis 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
Returns
Remarks
Reference: gymnasium/spaces/box.py.
Dispose(bool)
protected override void Dispose(bool disposing)
Parameters
Equals(Box?)
Gymnasium's ==: the same shape and dtype, and bounds equal within np.allclose.
public bool Equals(Box? other)
Parameters
otherBoxThe other box.
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 box's dtype (Gymnasium's from_jsonable, np.asarray(sample, dtype)).
public override IList<NDArray> FromJsonable(object jsonable)
Parameters
jsonableobjectValues ToJsonable(IEnumerable<NDArray>) produced, or numbers.
Returns
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
mannerBoundedMannerEnumThe side to check.
Returns
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
mannerstring"both","below"or"above".
Returns
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
varobjectThe value.
Returns
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
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
Returns
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
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 to_jsonable, sample.tolist()).
public override object ToJsonable(IEnumerable<NDArray> samples)
Parameters
samplesIEnumerable<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
Returns
operator !=(Box?, Box?)
Value inequality.
public static bool operator !=(Box? left, Box? right)