Language

unisim.backend.motrix.backend¶

Classes

MotrixBackend

MotrixSim backend implementation.

class unisim.backend.motrix.backend.MotrixBackend[source]¶

Bases: SimBackend

MotrixSim backend implementation.

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (str)
add_body_sensors (bool)
max_iterations (int | None)
push_body_name (str | None)

__init__(scene, num_envs, sim_dt, base_name='base', np_dtype=<class 'numpy.float32'>, add_body_sensors=False, max_iterations=3, push_body_name=None)[source]¶

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (str)
add_body_sensors (bool)
max_iterations (int | None)
push_body_name (str | None)

get_motion_body_ids(names)[source]¶

Resolve backend-native body IDs used by motion datasets.

Parameters:: names (Sequence[str])
Return type:: ndarray

property num_envs: int¶: Number of vectorized environments.

property model¶: Underlying physics model.

property data¶

property num_actuators: int¶: Number of actuators.

property num_dof_vel: int¶: Number of joint velocity DoFs, excluding the floating base.

get_actuator_ctrl_range()[source]¶

Return actuator control ranges.

Return type:: ndarray
Returns:: Array with shape (num_actuators, 2) and columns [low, high].

get_actuator_names()[source]¶

Return actuator names in control-vector order on the cold path.

Return type:: tuple[str, ...]

get_actuator_joint_names()[source]¶

Return each actuator’s target single-DoF joint in control-vector order.

Backends must fail closed when an actuator does not target exactly one hinge/slide joint. Manager action terms use this cold-path metadata to map community joint selectors onto the backend control vector without inspecting backend-private model objects.

Return type:: tuple[str, ...]

get_terrain_spawn_data()[source]¶

Return backend-materialized terrain metadata on the cold path.

Backends without generated terrain support return None. Callers should resolve this once during env initialization and cache the returned height-sampling callable for reset/reward hot paths.

Return type:: BackendTerrainSpawnData | None

get_keyframe_qpos(name)[source]¶

Return the full qpos for a named keyframe, including the floating base.

Parameters:: name (str) – Keyframe name such as "stand" or "home".
Return type:: ndarray
Returns:: Array with shape (nq,).

get_default_qpos()[source]¶

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

Return type:: ndarray

get_default_dof_pos()[source]¶

Return default joint positions in the same column order as get_dof_pos.

The returned array is detached, one-dimensional, and excludes floating root coordinates. Backends whose DoF view is actuator-indexed must use that same actuator-target order here.

Return type:: ndarray

get_init_qvel()[source]¶

Return a zero-initialized qvel vector compatible with set_state.

Return type:: ndarray
Returns:: Zero-filled qvel array.

get_root_state_layout(root_body_name)[source]¶

Resolve one body’s floating-root columns on the cold path.

Backends must verify that root_body_name owns a free/floating joint; fixed bodies and runtimes without body-to-root metadata fail closed. Name/model lookup is forbidden on reset and step hot paths, so callers cache either the returned layout or the unsupported result during scene materialization.

Parameters:: root_body_name (str)
Return type:: BackendRootStateLayout

get_body_ids(names)[source]¶

Resolve body/link names to backend integer IDs.

Parameters:: names (Sequence[str]) – Body/link names.
Return type:: ndarray
Returns:: int32 array with shape (len(names),).
Raises:: ValueError – If any name is not found.

get_site_ids(names)[source]¶

Resolve site names to integer ID arrays.

Parameters:: names (Sequence[str]) – Site names.
Return type:: ndarray
Returns:: int32 ID array with shape (len(names),).

get_joint_dof_indices(names)[source]¶

Resolve joint names to DoF indices in velocity space (qvel).

Parameters:: names (Sequence[str]) – Joint names.
Return type:: ndarray
Returns:: int32 index array with shape (len(names),) relative to the qvel start.

get_joint_dof_pos_indices(names)[source]¶

Resolve joint names to DoF indices in position space (qpos).

Only single-DoF joints are supported; free joints are excluded.

Parameters:: names (Sequence[str]) – Joint names.
Return type:: ndarray
Returns:: int32 index array with shape (len(names),) relative to the joint section of qpos.

get_joint_dof_vel_indices(names)[source]¶

Resolve joint names to DoF indices in velocity space (qvel).

Parameters:: names (Sequence[str]) – Joint names.
Return type:: ndarray
Returns:: int32 index array with shape (len(names),) relative to the joint section start.

get_joint_state_qpos_indices(names)[source]¶

Resolve single-DoF joints to full set_state qpos columns.

Unlike get_joint_dof_pos_indices(), these indices address the complete qpos vector accepted by set_state(), including any root coordinates. Manager reset transactions resolve them on the cold path.

Parameters:: names (Sequence[str])
Return type:: ndarray

get_joint_state_qvel_indices(names)[source]¶

Resolve single-DoF joints to full set_state qvel columns.

Parameters:: names (Sequence[str])
Return type:: ndarray

get_site_jacobian_w(site_id, dof_indices)[source]¶

Compute world-frame Jacobians for one site and selected DoF columns.

Parameters:

site_id (int) – Integer site ID.
dof_indices (ndarray) – DoF column indices to extract, with shape (n_dof,).

Return type:

tuple[ndarray, ndarray]

Returns:

(jacp, jacr) translation/rotation Jacobians, each with shape (num_envs, 3, n_dof).

get_geom_id(name)[source]¶

Resolve one geom name through the backend contract.

Parameters:: name (str)
Return type:: int

get_geom_size(name)[source]¶

Return one geom size vector through the backend contract.

Parameters:: name (str)
Return type:: ndarray

get_body_mass()[source]¶

Return the backend body-mass table.

Return type:: ndarray

get_body_ipos()[source]¶

Return the backend body inertial-position table.

Return type:: ndarray

get_body_subtree_ids(root_body_id)[source]¶

Return body ids in the subtree rooted at root_body_id.

Parameters:: root_body_id (int)
Return type:: ndarray

get_geom_names()[source]¶

Return backend geom names in backend id order.

Return type:: tuple[str, ...]

get_geom_body_ids()[source]¶

Return the owning body id for each geom.

Return type:: ndarray

get_geom_contact_masks()[source]¶

Return per-geom contact type and affinity masks.

Return type:: tuple[ndarray, ndarray]

get_geom_friction()[source]¶

Return the backend geom-friction table.

Return type:: ndarray

get_gravity()[source]¶

Return the backend gravity vector.

Return type:: ndarray

get_joint_range()[source]¶

Return single-DoF joint limits in backend DOF order.

Motrix stores the model-wide limits as a (2, num_dof) table, whereas the UniLab backend contract exposes the MuJoCo-shaped (num_dof, 2) table. This is materialized once by Entity and never queried from a task hot path.

Return type:: ndarray | None

step(ctrl, nsteps=1)[source]¶

Advance physics.

Parameters:

ctrl (ndarray) – Control input with shape (num_envs, nu).
nsteps (int) – Number of physics substeps.

Return type:

dict | None

Returns:

Optional dictionary. Backends may include a "timing" key with per-phase timings in milliseconds.

set_state(env_indices, qpos, qvel, randomization=None)[source]¶

Set physics state for selected environments.

Parameters:

env_indices (ndarray) – Environment indices.
qpos (ndarray) – Position state. Free-root columns exposed by get_root_state_layout() use world xyz and wxyz quaternion.
qvel (ndarray) – Velocity state. Free-root columns exposed by get_root_state_layout() use world linear velocity and body-frame angular velocity.
randomization (ResetRandomizationPayload | None) – Optional backend randomization payload.

Return type:

dict | None

Returns:

Optional dictionary. Backends MAY include a "timing" key with per-substep timings in milliseconds (e.g. set_state_mask_ms, set_state_data_slice_ms, …). Callers MUST treat None or missing keys as “not reported” — the outer wall-clock measurement in DomainRandomizationManager.reset (dr_reset_set_state_ms) remains authoritative for total set_state time.

get_dr_capabilities()[source]¶

Return supported domain-randomization capabilities for this backend.

Return type:: DomainRandomizationCapabilities

apply_init_randomization(plan)[source]¶

Apply cold-path model/materialization randomization.

Parameters:: plan (InitRandomizationPlan)
Return type:: None

get_play_capabilities()[source]¶

Return backend-native play/render capabilities.

Return type:: BackendPlayCapabilities

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

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, debug_overlay_getter=None, on_frame=None)[source]¶

Execute backend-owned playback for an env wrapper.

camera_kwargs is normalized into CameraCfg at this boundary; unknown mapping keys fail closed with an error naming them.

debug_overlay_getter is an optional per-frame callback returning a sequence with one entry per environment (len == num_envs); each entry is that env’s sequence of DebugPrimitive (None or empty marks an env without overlay) and returning None disables overlays for the frame. Primitive poses are env-local; the renderer applies grid offsets when composing multiple envs. Backends whose get_play_capabilities().supports_debug_overlay is False fail closed with NotImplementedError when this is not None. On the interactive rendering path only backends whose supports_interactive_debug_overlay is True consume it; the others fail closed with NotImplementedError.

on_frame is an optional per-frame video hook called by offline render pipelines before encoding: it receives (frame_index, frame) with the frame an (H, W, 3) uint8 array, and returns a replacement frame of the same shape/dtype or None to keep the original. Backends rendering through a native (non-offline) renderer fail closed with NotImplementedError when this is not None.

Known boundary: env is the owning env wrapper, not a physics-layer concept. Current playback implementations read env-level configuration (e.g. cfg.scene, cfg.ctrl_dt, cfg.render_spacing) and env-owned playback helpers (get_playback_model, get_physics_state_snapshot) that have no backend-native equivalent yet. The parameter stays on this contract until playback asset/config resolution moves onto backend-owned metadata; backends must only use it on the cold playback path.

Parameters:

env (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)
camera_kwargs (CameraCfg | Mapping[str, Any] | None)

Return type:

str | None

get_base_pos()[source]¶

Return base position in the world frame.

Return type:: ndarray
Returns:: (num_envs, 3)

get_base_quat()[source]¶

Return base quaternion in the world frame as wxyz.

Return type:: ndarray
Returns:: (num_envs, 4)

get_base_lin_vel()[source]¶

Return base linear velocity in the world frame.

This is the first three dimensions of generalized velocity qvel, expressed in world coordinates.

Return type:: ndarray
Returns:: (num_envs, 3)

get_base_ang_vel()[source]¶

Return base angular velocity in the world frame.

This is dimensions 3-5 of generalized velocity qvel, expressed in world coordinates. It differs from gyro readings: gyro sensors report angular velocity components in the body/sensor local frame, while this contract returns world-frame values. Use the matching sensor contract when body-frame angular velocity is required.

Return type:: ndarray
Returns:: (num_envs, 3)

get_dof_pos()[source]¶

Return joint positions, excluding the base.

Return type:: ndarray
Returns:: (num_envs, num_dof)

get_dof_vel()[source]¶

Return joint velocities, excluding the base.

Return type:: ndarray
Returns:: (num_envs, num_dof)

get_body_pos_w(body_ids)[source]¶

Return selected body positions in the world frame.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_quat_w(body_ids)[source]¶

Return selected body quaternions in the world frame as wxyz.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 4)

get_body_pose_w_rows(env_ids, body_ids)[source]¶

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

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

tuple[ndarray, ndarray]

get_body_pose_w(body_ids)[source]¶

Return selected body positions and quaternions in the world frame.

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, ndarray]

get_body_lin_vel_w(body_ids)[source]¶

Return selected body linear velocities in the world frame.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_ang_vel_w(body_ids)[source]¶

Return selected body angular velocities in the world frame.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_state_w(body_ids)[source]¶

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)[source]¶

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_vel_w(body_ids)[source]¶

Return selected body linear and angular velocities in the world frame.

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, ndarray]

get_body_lin_vel_w_rows(env_ids, body_ids)[source]¶

Get selected env rows of world-frame body linear velocity.

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

ndarray

get_body_ang_vel_w_rows(env_ids, body_ids)[source]¶

Get selected env rows of world-frame body angular velocity.

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

ndarray

get_body_pos_b(body_ids)[source]¶

Return selected body positions in the baselink frame.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_quat_b(body_ids)[source]¶

Return selected body quaternions in the baselink frame as wxyz.

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 4)

get_body_lin_vel_b(body_ids)[source]¶

Return selected body linear velocities expressed in each body’s own frame.

The value is the body’s world-frame velocity rotated by the inverse of the body’s world-frame orientation, i.e. quat_apply_inverse(quat_w, lin_vel_w) (mjlab/Isaac-style analytical definition). It is well-defined for every body — including the root body — and must NOT be implemented as the motion relative to the baselink frame (which degenerates to zero for the root body).

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_body_ang_vel_b(body_ids)[source]¶

Return selected body angular velocities expressed in each body’s own frame.

The value is the body’s world-frame angular velocity rotated by the inverse of the body’s world-frame orientation, i.e. quat_apply_inverse(quat_w, ang_vel_w) (mjlab/Isaac-style analytical definition). It is well-defined for every body — including the root body — and must NOT be implemented as the motion relative to the baselink frame (which degenerates to zero for the root body).

Parameters:: body_ids (ndarray) – Body ID array.
Return type:: ndarray
Returns:: (num_envs, len(body_ids), 3)

get_sensor_data(name)[source]¶

Return sensor data.

Parameters:: name (str) – Sensor name.
Return type:: ndarray
Returns:: Sensor data array.

get_sensor_data_rows(name, env_ids)[source]¶

Get selected env rows of a sensor array.

Parameters:

name (str)
env_ids (ndarray)

Return type:

ndarray

get_sensor_data_batch(names)[source]¶

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).

push_robots(force_range)[source]¶

apply_body_force(body_ids, force, torque=None)[source]¶

Apply absolute world-frame external forces through Motrix Link API.

Parameters:

body_ids (ndarray)
force (ndarray)
torque (ndarray | None)

Return type:

None

create_hfield_scanner(*, hfield_geom_id, offsets, frame_body_id, alignment='yaw', output='height')[source]¶

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

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

Initialize a Motrix renderer, optionally enabling system-camera capture.

Parameters:

spacing (float)
offset_mode (str)
headless (bool)
capture (bool)
width (int)
height (int)
camera_kwargs (CameraCfg | Mapping[str, Any] | None)

Return type:

None

render()[source]¶: Render current state (interactive visualization)

capture_video_frame()[source]¶

Capture one RGB frame from Motrix’s system camera.

Return type:: ndarray

get_actuator_gains()[source]¶

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

Return type:: tuple[ndarray, ndarray]