Spaces¶

Utilities to operate on Gymnasium spaces.

Overview¶

The utilities described in this section supports the following Gymnasium spaces:

Type	Supported spaces
Fundamental	`Box`, `Discrete`, and `MultiDiscrete`
Composite	`Dict` and `Tuple`

The following table provides a snapshot of the space sample conversion functions:

Input	Function	Output
Space (NumPy / int)	`tensorize_space()`	Space (PyTorch / JAX)
Space (PyTorch / JAX)	`untensorize_space()`	Space (NumPy / int)
Space (PyTorch / JAX)	`flatten_tensorized_space()`	PyTorch tensor / JAX array
PyTorch tensor / JAX array	`unflatten_tensorized_space()`	Space (PyTorch / JAX)

API¶

PyTorch¶

`compute_space_limits`	Get the low and high limits of a space.
`compute_space_size`	Get the size (number of elements) of a space.
`convert_gym_space`	Converts a gym space to a gymnasium space.
`flatten_tensorized_space`	Flatten a tensorized space.
`sample_space`	Generates a random sample from the specified space.
`tensorize_space`	Convert the sample/value items of a given gymnasium space to PyTorch tensors.
`unflatten_tensorized_space`	Unflatten a tensor to create a tensorized space.
`untensorize_space`	Convert a tensorized space to a gymnasium space with expected sample/value item types.

Get the low and high limits of a space.

Note

Only the Box space has low and high limits. Other spaces are not bounded (low is -inf and high is inf).

Parameters:

space – Gymnasium space.
occupied_size – Whether the limits are returned for the number of elements occupied by the space. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).
device – Device on which a tensor/array is or will be allocated.
none_if_unbounded – Whether to return None if the space is unbounded. If "both", low and high limits will be None if the space is unbounded in both directions. If "below", low limit will be None if the space is unbounded below. If "above", high limit will be None if the space is unbounded above. If "any", low or high limit will be None if the space is unbounded below or above, respectively. If not specified, low and high limits will be defined using -inf and inf, respectively, when the space is unbounded.

Returns:

Low and high limits of the space, or None if the given space is None or unbounded (and none_if_unbounded is specified).

skrl.utils.spaces.torch.compute_space_size(space: spaces.Space | list[int] | int | None, *, occupied_size: bool = False) → int[source]¶

Get the size (number of elements) of a space.

Parameters:

space – Gymnasium space.
occupied_size – Whether the number of elements occupied by the space is returned. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).

Returns:

Size of the space (number of elements), or 0 if the given space is None.

skrl.utils.spaces.torch.convert_gym_space(space: 'gym.Space' | None, *, squeeze_batch_dimension: bool = False) → gymnasium.Space | None[source]¶

Converts a gym space to a gymnasium space.

Parameters:

space – Gym space to convert to.
squeeze_batch_dimension – Whether to remove fundamental spaces’ first dimension. It currently affects Box space only.

Returns:

Converted space, or None if the given space is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.torch.flatten_tensorized_space(x: Any) → torch.Tensor | None[source]¶

Flatten a tensorized space.

Parameters:: x – Tensorized space sample/value.
Returns:: A tensor. The returned tensor will have shape (batch, space size), or None if the given tensorized sample/value is None.
Raises:: ValueError – The given sample/value type is not supported.

skrl.utils.spaces.torch.sample_space(space: spaces.Space | None, *, batch_size: int = 1, backend: Literal['numpy', 'native'] = 'numpy', device: str | torch.device | None = None) → Any[source]¶

Generates a random sample from the specified space.

Parameters:

space – Gymnasium space.
batch_size – Size of the sampled batch.
backend – Whether backend will be used to construct the fundamental spaces.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the backend is "native" (PyTorch).

Returns:

Sample of the space, or None if the given space is None.

Raises:

ValueError – The given space or backend is not supported.

skrl.utils.spaces.torch.tensorize_space(space: spaces.Space | None, x: Any, *, device: str | torch.device | None = None) → Any[source]¶

Convert the sample/value items of a given gymnasium space to PyTorch tensors.

Parameters:

space – Gymnasium space.
x – Sample/value of the given space to tensorize to.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the space value is not a PyTorch tensor (e.g.: NumPy array, number).

Returns:

Sample/value space with items converted to tensors, or None if the given space or the sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.

skrl.utils.spaces.torch.unflatten_tensorized_space(space: spaces.Space | None, x: torch.Tensor | None) → Any[source]¶

Unflatten a tensor to create a tensorized space.

Parameters:

space – Gymnasium space.
x – A tensor with shape (batch, space size).

Returns:

Tensorized space value, or None if the given space or the tensor is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.torch.untensorize_space(space: spaces.Space | None, x: Any, *, squeeze_batch_dimension: bool = True) → Any[source]¶

Convert a tensorized space to a gymnasium space with expected sample/value item types.

Parameters:

space – Gymnasium space.
x – Tensorized space (sample/value space where items are tensors).
squeeze_batch_dimension – Whether to remove the batch dimension. If True, only the sample/value with a batch dimension of size 1 will be affected.

Returns:

Sample/value space with expected item types, or None if the given space or the tensorized sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.

JAX¶

`compute_space_limits`	Get the low and high limits of a space.
`compute_space_size`	Get the size (number of elements) of a space.
`convert_gym_space`	Converts a gym space to a gymnasium space.
`flatten_tensorized_space`	Flatten a tensorized space.
`sample_space`	Generates a random sample from the specified space.
`tensorize_space`	Convert the sample/value items of a given gymnasium space to JAX or NumPy array.
`unflatten_tensorized_space`	Unflatten a tensor to create a tensorized space.
`untensorize_space`	Convert a tensorized space to a gymnasium space with expected sample/value item types.

Get the low and high limits of a space.

Note

Only the Box space has low and high limits. Other spaces are not bounded (low is -inf and high is inf).

Parameters:

space – Gymnasium space.
occupied_size – Whether the limits are returned for the number of elements occupied by the space. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).
device – Device on which a tensor/array is or will be allocated.
none_if_unbounded – Whether to return None if the space is unbounded. If "both", low and high limits will be None if the space is unbounded in both directions. If "below", low limit will be None if the space is unbounded below. If "above", high limit will be None if the space is unbounded above. If "any", low or high limit will be None if the space is unbounded below or above, respectively. If not specified, low and high limits will be defined using -inf and inf, respectively, when the space is unbounded.

Returns:

Low and high limits of the space, or None if the given space is None or unbounded (and none_if_unbounded is specified).

skrl.utils.spaces.jax.compute_space_size(space: spaces.Space | list[int] | int | None, *, occupied_size: bool = False) → int[source]¶

Get the size (number of elements) of a space.

Parameters:

space – Gymnasium space.
occupied_size – Whether the number of elements occupied by the space is returned. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).

Returns:

Size of the space (number of elements), or 0 if the given space is None.

skrl.utils.spaces.jax.convert_gym_space(space: 'gym.Space' | None, *, squeeze_batch_dimension: bool = False) → gymnasium.Space | None[source]¶

Converts a gym space to a gymnasium space.

Parameters:

space – Gym space to convert to.
squeeze_batch_dimension – Whether to remove fundamental spaces’ first dimension. It currently affects Box space only.

Returns:

Converted space, or None if the given space is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.jax.flatten_tensorized_space(x: Any) → jax.Array | np.ndarray | None[source]¶

Flatten a tensorized space.

Parameters:: x – Tensorized space sample/value.
Returns:: A tensor. The returned tensor will have shape (batch, space size), or None if the given tensorized sample/value is None.
Raises:: ValueError – The given sample/value type is not supported.

skrl.utils.spaces.jax.sample_space(space: spaces.Space | None, *, batch_size: int = 1, backend: Literal['numpy', 'native'] = 'numpy', device: str | jax.Device | None = None) → Any[source]¶

Generates a random sample from the specified space.

Parameters:

space – Gymnasium space.
batch_size – Size of the sampled batch.
backend – Whether backend will be used to construct the fundamental spaces.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the backend is "native" (JAX).

Returns:

Sample of the space, or None if the given space is None.

Raises:

ValueError – The given space or backend is not supported.

skrl.utils.spaces.jax.tensorize_space(space: spaces.Space | None, x: Any, *, device: str | jax.Device | None = None) → Any[source]¶

Convert the sample/value items of a given gymnasium space to JAX or NumPy array.

Parameters:

space – Gymnasium space.
x – Sample/value of the given space to tensorize to.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the space value is not a JAX array (e.g.: NumPy array, number).

Returns:

Sample/value space with items converted to tensors, or None if the given space or the sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.

skrl.utils.spaces.jax.unflatten_tensorized_space(space: spaces.Space | None, x: jax.Array | np.ndarray | None) → Any[source]¶

Unflatten a tensor to create a tensorized space.

Parameters:

space – Gymnasium space.
x – A tensor with shape (batch, space size).

Returns:

Tensorized space value, or None if the given space or the tensor is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.jax.untensorize_space(space: spaces.Space | None, x: Any, *, squeeze_batch_dimension: bool = True) → Any[source]¶

Convert a tensorized space to a gymnasium space with expected sample/value item types.

Parameters:

space – Gymnasium space.
x – Tensorized space (sample/value space where items are tensors).
squeeze_batch_dimension – Whether to remove the batch dimension. If True, only the sample/value with a batch dimension of size 1 will be affected.

Returns:

Sample/value space with expected item types, or None if the given space or the tensorized sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.

Warp¶

`compute_space_limits`	Get the low and high limits of a space.
`compute_space_size`	Get the size (number of elements) of a space.
`convert_gym_space`	Converts a gym space to a gymnasium space.
`flatten_tensorized_space`	Flatten a tensorized space.
`sample_space`	Generates a random sample from the specified space.
`tensorize_space`	Convert the sample/value items of a given gymnasium space to Warp arrays.
`unflatten_tensorized_space`	Unflatten a tensor to create a tensorized space.
`untensorize_space`	Convert a tensorized space to a gymnasium space with expected sample/value item types.

Get the low and high limits of a space.

Note

Only the Box space has low and high limits. Other spaces are not bounded (low is -inf and high is inf).

Parameters:

space – Gymnasium space.
occupied_size – Whether the limits are returned for the number of elements occupied by the space. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).
device – Device on which a tensor/array is or will be allocated.
none_if_unbounded – Whether to return None if the space is unbounded. If "both", low and high limits will be None if the space is unbounded in both directions. If "below", low limit will be None if the space is unbounded below. If "above", high limit will be None if the space is unbounded above. If "any", low or high limit will be None if the space is unbounded below or above, respectively. If not specified, low and high limits will be defined using -inf and inf, respectively, when the space is unbounded.

Returns:

Low and high limits of the space, or None if the given space is None or unbounded (and none_if_unbounded is specified).

skrl.utils.spaces.warp.compute_space_size(space: spaces.Space | list[int] | int | None, *, occupied_size: bool = False) → int[source]¶

Get the size (number of elements) of a space.

Parameters:

space – Gymnasium space.
occupied_size – Whether the number of elements occupied by the space is returned. It only affects Discrete (occupied space is 1), and MultiDiscrete (occupied space is the number of discrete spaces).

Returns:

Size of the space (number of elements), or 0 if the given space is None.

skrl.utils.spaces.warp.convert_gym_space(space: 'gym.Space' | None, *, squeeze_batch_dimension: bool = False) → gymnasium.Space | None[source]¶

Converts a gym space to a gymnasium space.

Parameters:

space – Gym space to convert to.
squeeze_batch_dimension – Whether to remove fundamental spaces’ first dimension. It currently affects Box space only.

Returns:

Converted space, or None if the given space is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.warp.flatten_tensorized_space(x: Any) → wp.array | None[source]¶

Flatten a tensorized space.

Parameters:: x – Tensorized space sample/value.
Returns:: A tensor. The returned tensor will have shape (batch, space size), or None if the given tensorized sample/value is None.
Raises:: ValueError – The given sample/value type is not supported.

skrl.utils.spaces.warp.sample_space(space: spaces.Space | None, *, batch_size: int = 1, backend: Literal['numpy', 'native'] = 'numpy', device: str | wp.Device | None = None) → Any[source]¶

Generates a random sample from the specified space.

Parameters:

space – Gymnasium space.
batch_size – Size of the sampled batch.
backend – Whether backend will be used to construct the fundamental spaces.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the backend is "native" (Warp).

Returns:

Sample of the space, or None if the given space is None.

Raises:

ValueError – The given space or backend is not supported.

skrl.utils.spaces.warp.tensorize_space(space: spaces.Space | None, x: Any, *, device: str | wp.Device | None = None) → Any[source]¶

Convert the sample/value items of a given gymnasium space to Warp arrays.

Parameters:

space – Gymnasium space.
x – Sample/value of the given space to tensorize to.
device – Device on which a tensor/array is or will be allocated. This parameter is used when the space value is not a Warp array (e.g.: NumPy array, number).

Returns:

Sample/value space with items converted to tensors, or None if the given space or the sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.

skrl.utils.spaces.warp.unflatten_tensorized_space(space: spaces.Space | None, x: wp.array | None) → Any[source]¶

Unflatten a tensor to create a tensorized space.

Parameters:

space – Gymnasium space.
x – A tensor with shape (batch, space size).

Returns:

Tensorized space value, or None if the given space or the tensor is None.

Raises:

ValueError – The given space is not supported.

skrl.utils.spaces.warp.untensorize_space(space: spaces.Space | None, x: Any, *, squeeze_batch_dimension: bool = True) → Any[source]¶

Convert a tensorized space to a gymnasium space with expected sample/value item types.

Parameters:

space – Gymnasium space.
x – Tensorized space (sample/value space where items are tensors).
squeeze_batch_dimension – Whether to remove the batch dimension. If True, only the sample/value with a batch dimension of size 1 will be affected.

Returns:

Sample/value space with expected item types, or None if the given space or the tensorized sample/value is None.

Raises:

ValueError – The given space or the sample/value type is not supported.