unilab.base.np_env

Classes

NpEnv

Backend-agnostic numpy environment base class.

NpEnvState

NpEnvState(obs: 'dict[str, np.ndarray]', reward: 'np.ndarray', terminated: 'np.ndarray', truncated: 'np.ndarray', info: 'dict[str, Any]', final_observation: 'dict[str, np.ndarray] | None' = None)
class unilab.base.np_env.NpEnvState[source]

Bases: object

NpEnvState(obs: ‘dict[str, np.ndarray]’, reward: ‘np.ndarray’, terminated: ‘np.ndarray’, truncated: ‘np.ndarray’, info: ‘dict[str, Any]’, final_observation: ‘dict[str, np.ndarray] | None’ = None)

Parameters:
obs: dict[str, ndarray]
reward: ndarray
terminated: ndarray
truncated: ndarray
info: dict[str, Any]
final_observation: dict[str, ndarray] | None = None
replace(**updates)[source]
Parameters:

updates (Any)

Return type:

NpEnvState

__init__(obs, reward, terminated, truncated, info, final_observation=None)
Parameters:
class unilab.base.np_env.NpEnv[source]

Bases: ABEnv

Backend-agnostic numpy environment base class.

Parameters:
__init__(cfg, backend, num_envs)[source]
Parameters:
property cfg: EnvCfg

The configuration of the environment

property num_envs: int

return the size of the env if it is vectorized

property state: NpEnvState | None

Current environment state (None before first reset)

property obs_groups_spec: dict[str, int]

101}.

Subclasses MUST override this property.

Type:

Return observation group dimensions, e.g. {“obs”

Type:

98, “critic”

property observation_space: Space

Observation space

init_state()[source]

Initialize environment and return initial state

Return type:

NpEnvState

step(actions)[source]

Step the environment with given actions, return new state

Parameters:

actions (ndarray)

Return type:

NpEnvState

reset(env_indices)[source]
Parameters:

env_indices (ndarray)

Return type:

Tuple[dict[str, ndarray], dict]

init_play_renderer(render_spacing=None, render_offset_mode=None, *, headless=False, capture=False, width=1280, height=720, camera_kwargs=None)[source]

Initialize backend-native playback rendering when available.

Parameters:
Return type:

None

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)[source]

Resolve high-level playback mode through the concrete backend.

Parameters:
Return type:

BackendPlayRenderPlan

run_playback(*, initialize, step, num_steps, output_video=None, render_spacing=None, render_offset_mode=None, headless=None, record_video=None, frame_state_getter=None, camera_kwargs=None, debug_overlay_getter=None, on_frame=None)[source]

Execute playback through the concrete backend.

on_frame is declared on the env contract but the unisim SimBackend.run_playback boundary does not accept it yet; passing a callback fails closed until the upstream contract lands. Use unilab.visualization.playback_session.SnapshotPlaybackSession for deferred rendering with per-frame callbacks today.

Parameters:

  • initialize (Callable[[], Any])

  • step (Callable[[Any], Any])

  • num_steps (int | None)

  • output_video (str | PathLike[str] | None)

  • render_spacing (float | None)

  • render_offset_mode (str | None)

  • headless (bool | None)

  • record_video (bool | None)

  • frame_state_getter (Callable[[], np.ndarray] | None)

  • camera_kwargs (CameraCfg | Mapping[str, Any] | None)

  • debug_overlay_getter (DebugOverlayGetter | None)

  • on_frame (Callable[[int, np.ndarray], np.ndarray | None] | None)

Return type:

str | None

render_play_frame()[source]

Render one interactive playback frame through the env contract.

Return type:

None

render(mode='rgb_array')[source]

Render the current state to an RGB array through the play renderer.

Lazily initializes a headless capture renderer on first use and returns one detached (H, W, 3) uint8 frame per call. Backends without native video capture fail closed with a class-named error.

Parameters:

mode (str)

Return type:

ndarray

capture_play_video_frame()[source]

Capture one detached RGB video frame through the env contract.

Return type:

ndarray

get_physics_state_snapshot()[source]

Return a detached physics snapshot for offline playback/video export.

Return type:

ndarray

abstract apply_action(actions, state)[source]

Subclasses implement the action-to-control conversion.

Parameters:
Return type:

ndarray

abstract update_state(state)[source]

Subclasses compute observation, reward, and termination state.

Parameters:

state (NpEnvState)

Return type:

NpEnvState

property play_capabilities: EnvPlayCapabilities

Return env-facing play/render capabilities.

get_playback_model(env_index=None)[source]

Return the backend playback model for one env in a vectorized batch.

Parameters:

env_index (int | None) – Optional vectorized environment index.

Return type:

Any

Returns:

The backend-specific playback model.

get_scene_visual_model_file()[source]

Return the backend scene visual model file on the cold path, when available.

Return type:

str | None

set_nan_guard(guard)[source]
Parameters:

guard (NanGuard)

Return type:

None

set_autoreset(enabled)[source]

Toggle automatic reset of done envs at the end of step.

Defaults to True (standard RL autoreset). Interactive playback can disable it so a terminated robot stays put until a manual reset.

Parameters:

enabled (bool)

Return type:

None

export_training_state()[source]

Export cumulative training progress, independently of episode/physics state.

Task-specific curriculum state belongs to the task’s explicit provider; this payload deliberately does not inspect manager or environment internals.

Return type:

dict[str, Any]

import_training_state(state)[source]

Validate and restore cumulative progress before the next control step.

Parameters:

state (Mapping[str, Any])

Return type:

None

close()[source]

Close the environment and release backend-owned scene assets.

Return type:

None