Language Language English 简体中文

unilab.base — Core Contracts

The shared substrate everything else stands on. If you only read one module in this reference, read this one.

Symbol	Role
NpEnv / NpEnvState	The env contract every task implements
SimBackend	Abstract backend interface (MuJoCo / Motrix implement it)
Registry	Task / backend / algorithm registration and lookup
Scene	Cold-path scene materialization
observations, final_observation	Observation builders & terminal handling
augmentation	Symmetry / mirror augmentation utilities
curriculum	Curriculum schedule primitives

unilab.base

Environment registry and base classes.

Selected detail

class unilab.base.np_env.NpEnv

Bases: ABEnv

统一的 numpy 环境基类（backend-agnostic）

Parameters:

• cfg (EnvCfg)

• backend (SimBackend)

• num_envs (int)

__init__(cfg, backend, num_envs)

Parameters:

• cfg (EnvCfg)

• backend (SimBackend)

• num_envs (int)

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

build_symmetry_augmentation(*, device)

Return an env-owned runtime symmetry adapter when the task/backend supports it.

Parameters:

device (str)

Return type:

SymmetryAugmentation | None

init_state()

Initialize environment and return initial state

Return type:

NpEnvState

step(actions)

Step the environment with given actions, return new state

Parameters:

actions (ndarray)

Return type:

NpEnvState

reset(env_indices)

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)

Initialize backend-native playback rendering when available.

Parameters:

• render_spacing (float | None)

• render_offset_mode (str | None)

• headless (bool)

• capture (bool)

• width (int)

• height (int)

• camera_kwargs (dict[str, Any] | None)

Return type:

None

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)

Resolve high-level playback mode through the concrete backend.

Parameters:

• play_render_mode (str | None)

• play_steps (int | None)

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

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, extra_data_getter=None)

Execute playback through the concrete backend.

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[[], ndarray] | None)

• camera_kwargs (dict[str, Any] | None)

• extra_data_getter (Callable[[], ndarray | None] | None)

Return type:

str | None

render_play_frame()

Render one interactive playback frame through the env contract.

Return type:

None

capture_play_video_frame()

Capture one detached RGB video frame through the env contract.

Return type:

ndarray

get_physics_state_snapshot()

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

Return type:

ndarray

abstract apply_action(actions, state)

子类实现：action → ctrl

Parameters:

• actions (ndarray)

• state (NpEnvState)

Return type:

ndarray

abstract update_state(state)

子类实现：计算 obs/reward/terminated

Parameters:

state (NpEnvState)

Return type:

NpEnvState

property play_capabilities: EnvPlayCapabilities

Return env-facing play/render capabilities.

get_playback_model(env_index=None)

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.

set_nan_guard(guard)

Parameters:

guard (NanGuard)

Return type:

None

set_autoreset(enabled)

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

close()

关闭环境

Return type:

None

class unilab.base.backend.base.SimBackend

Bases: ABC

仿真后端统一接口

backend_type: str

abstract property num_envs: int

环境数量

abstract property model

底层物理模型

abstract property num_actuators: int

执行器数量

abstract property num_dof_vel: int

关节速度自由度数量（不含浮动基座）

abstract get_actuator_ctrl_range()

获取执行器控制范围

Return type:

ndarray

Returns:

(num_actuators, 2) 数组，列为 [low, high]

abstract get_keyframe_qpos(name)

获取指定关键帧的完整 qpos（含浮动基座）

Parameters:

name (str) – 关键帧名称（如 “stand”、”home”）

Return type:

ndarray

Returns:

(nq,) 数组

get_default_qpos()

Return the backend/model default qpos through a stable contract.

Return type:

ndarray

abstract get_init_qvel()

获取零初始化的 qvel 向量，维度与 set_state 期望一致

Return type:

ndarray

Returns:

全零数组

abstract get_body_ids(names)

将 body/link 名称解析为后端整数 ID

Parameters:

names (Sequence[str]) – body/link 名称序列

Return type:

ndarray

Returns:

(len(names),) int32 数组

Raises:

ValueError – 若名称未找到

get_body_id(name)

Resolve one body/link name through the backend contract.

Parameters:

name (str)

Return type:

int

get_geom_id(name)

Resolve one geom name through the backend contract.

Parameters:

name (str)

Return type:

int

get_geom_size(name)

Return one geom size vector through the backend contract.

Parameters:

name (str)

Return type:

ndarray

create_hfield_scanner(*, hfield_geom_id, offsets, frame_body_id, alignment='yaw', output='height')

Create a reusable height-field scanner on the init/cold path.

Backends that support height-field terrain scan must override this method.

Parameters:

• hfield_geom_id (int)

• offsets (ndarray)

• frame_body_id (int)

• alignment (str)

• output (str)

Return type:

BackendHeightScanner

get_body_subtree_ids(root_body_id)

Return body ids in the subtree rooted at root_body_id.

Parameters:

root_body_id (int)

Return type:

ndarray

get_geom_names()

Return backend geom names in backend id order.

Return type:

tuple[str, ...]

get_geom_body_ids()

Return the owning body id for each geom.

Return type:

ndarray

get_geom_contact_masks()

Return per-geom contact type and affinity masks.

Return type:

tuple[ndarray, ndarray]

get_geom_friction()

Return the backend geom-friction table.

Return type:

ndarray

get_gravity()

Return the backend gravity vector.

Return type:

ndarray

get_body_mass()

Return the backend body-mass table.

Return type:

ndarray

get_body_ipos()

Return the backend body inertial-position table.

Return type:

ndarray

get_dof_armature()

Return the backend dof-armature table.

Return type:

ndarray

get_motion_body_ids(names)

Resolve MuJoCo-style body IDs used by motion datasets.

Parameters:

names (Sequence[str])

Return type:

ndarray

cleanup_scene_assets()

Release cold-path scene artifacts owned by the backend.

Return type:

None

abstract get_joint_range()

获取关节位置限制（不含浮动基座）

Return type:

ndarray | None

Returns:

(num_dof, 2) 数组，列为 [low, high]；若后端不支持则返回 None

abstract step(ctrl, nsteps=1)

执行物理步进

Parameters:

• ctrl (ndarray) – 控制输入 (num_envs, nu)

• nsteps (int) – 步进次数

Return type:

dict | None

Returns:

可选的 dict，可包含 “timing” key 记录各阶段耗时（ms）

set_pre_step_control(fn)

Register an env-owned policy-control to physics-control converter.

The callback receives (backend, ctrl) so owner code can read the backend’s freshly-updated sensor contract before every physics substep. It must return backend-native actuator control with the same shape. Position-actuator envs leave this unset and keep the direct control path.

Parameters:

fn (Callable[[Any, ndarray], ndarray] | None)

Return type:

None

abstract set_state(env_indices, qpos, qvel, randomization=None)

设置指定环境的物理状态

Parameters:

• env_indices (ndarray) – 环境索引

• qpos (ndarray) – 位置状态

• qvel (ndarray) – 速度状态

• randomization (ResetRandomizationPayload | None) – 可选的后端随机化 payload

Return type:

None

abstract get_dr_capabilities()

Return supported domain-randomization capabilities for this backend.

Return type:

DomainRandomizationCapabilities

apply_init_randomization(plan)

Apply cold-path model/materialization randomization.

Parameters:

plan (InitRandomizationPlan)

Return type:

None

materialize()

Finalize cold-path backend resources before reset/step.

Return type:

None

abstract apply_interval_randomization(plan)

Apply a scheduled interval randomization plan.

Parameters:

plan (IntervalRandomizationPlan)

Return type:

None

apply_body_linear_velocity_delta(body_ids, velocity_delta)

Apply a world-frame linear-velocity delta to specific bodies.

Parameters:

• body_ids (ndarray) – Body ids whose linear velocities should be perturbed.

• velocity_delta (ndarray) – Velocity delta with shape (num_envs, len(body_ids), 3).

Return type:

None

Returns:

None. Backends that support this mutate their pending simulation state.

apply_body_force(body_ids, force)

Apply a world-frame force to specific bodies for the upcoming step.

Parameters:

• body_ids (ndarray) – Body ids whose external forces should be perturbed.

• force (ndarray) – Force values with shape (num_envs, len(body_ids), 3).

Return type:

None

Returns:

None. Backends that support this mutate their pending simulation state.

get_play_capabilities()

Return backend-native play/render capabilities.

Return type:

BackendPlayCapabilities

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)

Resolve high-level playback mode into backend-owned render parameters.

Parameters:

• play_render_mode (str | None)

• play_steps (int | None)

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

Return type:

BackendPlayRenderPlan

run_playback(*, env, 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, extra_data_getter=None)

Execute backend-owned playback for an env wrapper.

Parameters:

• env (Any)

• 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[[], ndarray] | None)

• camera_kwargs (dict[str, Any] | None)

• extra_data_getter (Callable[[], ndarray | None] | None)

Return type:

str | None

init_renderer(spacing=1.0, *, offset_mode='grid', headless=False, capture=False, width=1280, height=720, camera_kwargs=None)

Initialize a backend-native renderer.

headless controls whether a native window is opened. capture controls whether capture_video_frame is valid for the renderer.

Parameters:

• spacing (float)

• offset_mode (str)

• headless (bool)

• capture (bool)

• width (int)

• height (int)

• camera_kwargs (dict[str, Any] | None)

Return type:

None

render()

Render one frame through a backend-native interactive renderer.

Return type:

None

capture_video_frame()

Capture one RGB frame through a backend-native renderer.

Return type:

ndarray

get_physics_state()

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

Return type:

ndarray

get_playback_model(env_index=None)

Return the playback model for a specific env when variants exist.

Parameters:

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

Return type:

Any

Returns:

The backend model object used by playback tooling.

get_actuator_gains()

Return per-joint (kp, kd) arrays from the backend model.

Return type:

tuple[ndarray, ndarray]

abstract get_base_pos()

获取 base 在世界系下的位置

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_base_quat()

获取 base 在世界系下的四元数（wxyz）

Return type:

ndarray

Returns:

(num_envs, 4)

abstract get_base_lin_vel()

获取 base 在世界系下的线速度

即广义速度 qvel 的前 3 维，表达在世界坐标系中。

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_base_ang_vel()

获取 base 在世界系下的角速度

即广义速度 qvel 的第 3-5 维，表达在世界坐标系中。 注意与陀螺仪（gyro）读数的区别：陀螺仪返回的是角速度在 body/sensor 局部坐标系下的分量（即 body frame 表达），而本接口返回的是世界系表达。 若需要 body frame 下的角速度，请使用对应的传感器接口gyro。

Return type:

ndarray

Returns:

(num_envs, 3)

abstract get_dof_pos()

获取关节位置（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

abstract get_dof_vel()

获取关节速度（不含 base）

Return type:

ndarray

Returns:

(num_envs, num_dof)

abstract get_body_pos_w(body_ids)

获取指定 body 在世界系下的位置

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

abstract get_body_quat_w(body_ids)

获取指定 body 在世界系下的四元数（wxyz）

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 4)

get_body_pose_w(body_ids)

获取指定 body 在世界系下的位置和四元数（wxyz）

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_lin_vel_w(body_ids)

获取指定 body 在世界系下的线速度

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_body_vel_w(body_ids)

获取指定 body 在世界系下的线速度和角速度

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_ang_vel_w(body_ids)

获取指定 body 在世界系下的角速度

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_body_state_w(body_ids)

Get selected body position, quaternion, linear velocity, and angular velocity.

Parameters:

body_ids (ndarray)

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

copy_body_state_w(body_ids, out_pos, out_quat, out_lin_vel, out_ang_vel)

Copy selected world-frame body state into caller-owned buffers.

Parameters:

• body_ids (ndarray)

• out_pos (ndarray)

• out_quat (ndarray)

• out_lin_vel (ndarray)

• out_ang_vel (ndarray)

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

get_body_pose_w_rows(env_ids, body_ids)

Get selected env rows of world-frame body position and quaternion.

Parameters:

• env_ids (ndarray)

• body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

abstract get_body_pos_b(body_ids)

获取指定 body 在 baselink 系下的位置

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

abstract get_body_quat_b(body_ids)

获取指定 body 在 baselink 系下的四元数（wxyz）

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 4)

abstract get_body_lin_vel_b(body_ids)

获取指定 body 在 baselink 系下的线速度

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

abstract get_body_ang_vel_b(body_ids)

获取指定 body 在 baselink 系下的角速度

Parameters:

body_ids (ndarray) – body 索引数组

Return type:

ndarray

Returns:

(num_envs, len(body_ids), 3)

get_site_ids(names)

将 site 名称列表转换为整数 ID 数组。

Parameters:

names (Sequence[str]) – site 名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 ID 数组

get_joint_dof_indices(names)

将关节名称列表转换为速度空间（qvel）的 DoF 索引数组。

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组（相对于 qvel 起始位置）

get_joint_dof_pos_indices(names)

将关节名称列表转换为位置空间（qpos）的 DoF 索引数组。

仅支持单自由度关节（非 free joint）。

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组（相对于 qpos 中关节部分的起始位置）

get_joint_dof_vel_indices(names)

将关节名称列表转换为速度空间（qvel）的 DoF 索引数组（相对于关节部分起始）。

Parameters:

names (Sequence[str]) – 关节名称列表

Return type:

ndarray

Returns:

shape (len(names),) 的 int32 索引数组

get_site_jacobian_w(site_id, dof_indices)

批量计算指定 site 相对于指定 DoF 列的世界系 Jacobian。

Parameters:

• site_id (int) – site 整数 ID

• dof_indices (ndarray) – 要提取的 DoF 列索引，shape (n_dof,)

Return type:

tuple[ndarray, ndarray]

Returns:

(jacp, jacr)，各为 shape (num_envs, 3, n_dof) 的平移/旋转 Jacobian

abstract get_sensor_data(name)

获取传感器数据

Parameters:

name (str) – 传感器名称

Return type:

ndarray

Returns:

传感器数据数组

get_sensor_data_rows(name, env_ids)

Get selected env rows of a sensor array.

Parameters:

• name (str)

• env_ids (ndarray)

Return type:

ndarray

get_sensor_data_batch(names)

Fetch multiple sensors and concatenate their flattened values.

Parameters:

names (Sequence[str]) – Sensor names in output order.

Return type:

ndarray

Returns:

Array with shape (num_envs, total_sensor_values).