Box

class Box(*args, init_value=None, constrain_fn=None, **kwargs)[source]

Bases: Box

Extended continuous box space with state tracking and constraint support.

This class extends gymnasium.spaces.Box to add state management and optional constraint validation. It represents bounded continuous values with configurable shape, dtype, and custom constraints.

Variables:

  • init_value (np.ndarray) – The initial value for the space.

  • value (np.ndarray) – The current value of the space.

  • constrain_fn (callable) – Optional function that returns True if a value satisfies custom constraints beyond the box boundaries.

Example

Create a 2D position space constrained to a circle:

import numpy as np


def in_circle(pos):
    return np.linalg.norm(pos) <= 1.0


space = Box(
    low=np.array([-1.0, -1.0]),
    high=np.array([1.0, 1.0]),
    init_value=np.array([0.0, 0.0]),
    constrain_fn=in_circle,
)
position = space.sample()  # Only samples within unit circle

Note

The constraint function enables complex geometric or relational constraints beyond simple box boundaries.

__init__(*args, init_value=None, constrain_fn=None, **kwargs)[source]

Initialize a Box space with state tracking.

Parameters:

  • *args – Positional arguments passed to gymnasium.spaces.Box.

  • init_value (np.ndarray, optional) – Initial value for the space. Must match the shape and dtype of the box. Defaults to None.

  • constrain_fn (callable, optional) – Function that takes a numpy array and returns True if the value satisfies custom constraints beyond the box boundaries. Defaults to None.

  • **kwargs – Keyword arguments passed to gymnasium.spaces.Box.

check()[source]

Validate the current space value.

Checks if the current value is within the box bounds and satisfies the constraint function. Logs a warning if the constraint fails.

Returns:

True if the current value is valid, False otherwise.

Return type:

bool

contains(x)[source]

Check if value is valid and satisfies constraints.

Parameters:

x (np.ndarray) – The value to check.

Returns:

True if x is within box bounds and satisfies the constraint

function, False otherwise.

Return type:

bool

property init_value

The initial value of the space, returned by reset().

Type:

np.ndarray

reset()[source]

Reset the space value to its initial value.

Sets the current value back to the init_value specified during initialization.

sample(*args, max_tries=1000, warn_after_s=5.0, set_value=True, **kwargs)[source]

Sample a random value using rejection sampling for constraints.

Repeatedly samples values until one satisfies the constraint function or max_tries is reached. Optionally updates the space’s current value.

Parameters:

  • *args – Positional arguments passed to gymnasium.spaces.Box.sample().

  • max_tries (int, optional) – Maximum number of sampling attempts before raising an error. Defaults to 1000.

  • warn_after_s (float, optional) – Time threshold in seconds after which to log a warning about slow sampling. Set to None to disable. Defaults to 5.0.

  • set_value (bool, optional) – Whether to update the space’s current value with the sampled value. Defaults to True.

  • **kwargs – Keyword arguments passed to gymnasium.spaces.Box.sample().

Returns:

A sampled array that satisfies the constraint function.

Return type:

np.ndarray

Raises:

RuntimeError – If no valid sample is found after max_tries attempts.

property value

The current value of the space.

Type:

np.ndarray