unilab.base.reset_selectors

Reset row-selector conversion between the public env_ids and mask forms.

The task/manager reset contract speaks IsaacLab/mjlab-style env_ids row indices. Backend transactions keep consuming fixed-width bool masks (SimBackend.apply_reset/packed reset). These helpers are the single, deliberately simple conversion point between the two forms.

Hot reset paths must not allocate a fresh mask per conversion (roadmap #2461): each conversion site owns a ResetMaskBuffer whose storage is allocated once on the env/manager/term and rewritten in place per call. The module-level helpers keep allocating and remain the owned-copy form for callers without a stable owner (tests, fixtures).

Functions

reset_env_ids_mask(env_ids, *, num_envs, device)

Scatter row indices into a freshly allocated fixed-width bool mask.

resolve_reset_env_ids(selector, *, num_envs, ...)

Normalize a public reset selector to an int64 row-index tensor.

resolve_reset_mask(selector, *, num_envs, ...)

Resolve a public reset selector to the internal fixed-width bool mask.

Classes

ResetMaskBuffer

Reusable fixed-width bool reset mask owned by one conversion site.
class unilab.base.reset_selectors.ResetMaskBuffer[source]

Bases: object

Reusable fixed-width bool reset mask owned by one conversion site.

scatter/resolve rewrite the internal storage in place and return it; the returned tensor aliases that storage and stays valid only until the next call on the same buffer. Every site whose masks may be live at the same time owns a separate instance: the env reset-transaction entry, the env-owned event-term scratch, each manager, and each class-based term. Buffer lifetime follows its owner (the env or manager instance), so separate env instances never share storage.

Parameters:
__init__(num_envs, device)[source]
Parameters:
property num_envs: int
property device: device
scatter(env_ids)[source]

Rewrite the buffer from row indices and return the aliased mask.

Parameters:

env_ids (Tensor)

Return type:

Tensor

resolve(selector, *, owner)[source]

Resolve a public reset selector like resolve_reset_mask.

Every selector is normalized to env_ids and scattered into this buffer.

Parameters:
Return type:

Tensor

unilab.base.reset_selectors.reset_env_ids_mask(env_ids, *, num_envs, device)[source]

Scatter row indices into a freshly allocated fixed-width bool mask.

Parameters:
Return type:

Tensor

unilab.base.reset_selectors.resolve_reset_env_ids(selector, *, num_envs, device, owner)[source]

Normalize a public reset selector to an int64 row-index tensor.

None selects every row; a slice selects arange(num_envs)[slice]; an integer tensor is validated and moved onto device. Fixed-width bool masks are rejected: the v1.4 mask form was removed in v1.5.

Parameters:
Return type:

Tensor

unilab.base.reset_selectors.resolve_reset_mask(selector, *, num_envs, device, owner)[source]

Resolve a public reset selector to the internal fixed-width bool mask.

The selector is normalized to env_ids and scattered into a freshly allocated mask.

Parameters:
Return type:

Tensor