MultiDiscrete

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

Bases: MultiDiscrete

Extended multi-discrete space with state tracking and constraint support.

This class extends gymnasium.spaces.MultiDiscrete to add state management and optional constraint validation. It represents multiple discrete variables with potentially different ranges (nvec), where each variable maintains its own value and can be constrained.

Variables:

  • init_value (np.ndarray) – The initial values for all discrete variables.

  • value (np.ndarray) – The current values of all discrete variables.

  • constrain_fn (callable) – Optional function that returns True if the entire value array satisfies custom constraints.

Example

Create a multi-discrete space for game difficulty settings:

import numpy as np

space = MultiDiscrete(
    nvec=[5, 3, 10],  # [enemy_count, speed_level, spawn_rate]
    init_value=np.array([2, 1, 5]),
)
settings = space.sample()  # Random difficulty configuration
space.reset()  # Resets to [2, 1, 5] (medium difficulty)

Note

Constraints are applied to the entire array, not individual elements. Use a constraint function that validates the complete state.

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

Initialize a MultiDiscrete space with state tracking.

Parameters:

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

  • init_value (np.ndarray, optional) – Initial values for the space. Must match the shape defined by nvec. Defaults to None.

  • constrain_fn (callable, optional) – Function that takes a numpy array and returns True if the values satisfy custom constraints. Defaults to None.

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

check()[source]

Validate the current space values.

Checks if the current values are within the space bounds and satisfy the constraint function. Logs a warning if the constraint fails.

Returns:

True if the current values are valid, False otherwise.

Return type:

bool

contains(x)[source]

Check if values are valid and satisfy constraints.

Parameters:

x (np.ndarray) – The array of values to check.

Returns:

True if x is within bounds for all elements and satisfies

the constraint function, False otherwise.

Return type:

bool

property init_value

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

Type:

np.ndarray

reset()[source]

Reset the space values to their initial values.

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

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

Sample random values using rejection sampling for constraints.

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

Parameters:

  • *args – Positional arguments passed to gymnasium.spaces.MultiDiscrete.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 values with the sampled values. Defaults to True.

  • **kwargs – Keyword arguments passed to gymnasium.spaces.MultiDiscrete.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 values of the space.

Type:

np.ndarray