unisim.backend.motrix.backend

Classes

MotrixBackend

MotrixSim backend implementation.
class unisim.backend.motrix.backend.MotrixBackend[source]

Bases: SimBackend

MotrixSim backend implementation.

Parameters:
__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, cpu_ids=None)[source]
Parameters:
get_motion_body_ids(names)[source]

Resolve body IDs used by motion datasets.

Motion datasets are generated from MuJoCo, so the returned ids follow the MJCF body order with worldbody as id 0, regardless of the backend-native indexing used by get_body_ids.

Parameters:

names (Sequence[str])

Return type:

ndarray

property num_envs: int

Number of vectorized environments.

property model

Underlying physics model.

property data
property cpu_ids: tuple[int, ...] | None

CPU block requested for MotrixSim workers, or None for the default policy.

Worker i is pinned to cpu_ids[i % len(cpu_ids)]. The value is the validated construction request; a pool already initialized by an earlier MotrixSim user in this process keeps its own mapping (a construction-time warning reports that conflict).

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:

TerrainSpawnData | 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 default public qpos row (base block plus selected DoFs).

The width matches get_public_state_widths().nq so the row is directly compatible with set_state_tensor; portable scenes report the env-0 canonical row of the composed layout.

Return type:

ndarray

get_default_dof_pos()[source]

Return default joint positions in canonical non-root qpos order.

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 public qvel row matching get_public_state_widths().nv.

Return type:

ndarray

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:

RootStateLayout

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 absolute DoF indices in velocity space.

Parameters:

names (Sequence[str]) – Joint names.

Return type:

ndarray

Returns:

int32 index array with shape (len(names),) addressing the complete qvel vector, including any root coordinates.

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 joint-section DoF indices in velocity space.

Unlike get_joint_dof_indices(), the returned indices exclude any root/free-joint velocity columns. They address the same joint section used by get_joint_dof_pos_indices().

Parameters:

names (Sequence[str])

Return type:

ndarray

get_joint_state_qpos_indices(names)[source]

Resolve single-DoF joints to full set_state_tensor qpos columns.

Unlike get_joint_dof_pos_indices(), these indices address the complete qpos vector accepted by set_state_tensor(), 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_tensor 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 in backend geom-name order.

get_default_geom_sizes returns the complete table of default sizes, while this selector resolves one geom by name.

Parameters:

name (str)

Return type:

ndarray

get_body_mass()[source]

Return the backend body-mass table.

Return type:

ndarray

get_body_ipos(env_ids=None)[source]

Return body center-of-mass offsets in each body’s local frame, in meters.

body_ipos[b] is the position of body b’s center of mass in that body’s own local coordinate frame; it is neither an inertia tensor nor a whole-subtree COM.

Without env_ids the canonical model default table is returned with shape (nbody, 3) in backend body-id order. It never changes with reset randomization; fixed-variant backends expose their per-environment default baselines through get_reset_term_default() instead.

With env_ids the current effective per-environment values are returned with shape (len(env_ids), nbody, 3), in env_ids order. The values reflect every reset randomization applied so far, including composition with base_com_offset; an environment untouched by a partial reset keeps its previous values. Backends that do not track per-environment inertial offsets fail closed with NotImplementedError for this form.

Parameters:

env_ids (Sequence[int] | ndarray | None)

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(*, names=None)[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.

Parameters:

names (Sequence[str] | None)

Return type:

ndarray | None

get_scene_layout()[source]

Return the immutable materialized public addresses, never native handles.

Return type:

CompiledSceneLayout

get_entity_names()[source]

Return materialized physical entity names in the frozen public order.

Return type:

tuple[str, ...]

get_entity_default_state(entity, env_ids=None)[source]

Detached construction/keyframe defaults in selected environment order.

Fields and frames match get_entity_state. Defaults follow immutable variant assignment and never reflect current reset-time randomization. This query does not reset, step or reparse the scene.

Parameters:
Return type:

Mapping[str, ndarray]

get_entity_state(entity)[source]

Return detached root_pose/root_velocity/joint_positions/joint_velocities.

Root fields follow EntityStatePatch’s link-origin/world-frame contract. Non-root joint fields use the frozen entity joint order and native generalized widths. Unavailable fields must fail, never return old data as if current. State freshness follows the adapter’s declared profile.

Parameters:

entity (str)

Return type:

Mapping[str, ndarray]

get_play_capabilities()[source]

Return backend-native play/render capabilities.

Return type:

PlayCapabilities

get_physics_state_layout()[source]

Return the [time, qpos, qvel] snapshot layout (no mocap tail yet).

Return type:

PhysicsStateLayout

get_physics_state()[source]

Assemble contract [time, qpos, qvel] rows in MuJoCo order.

SceneData has no time field, so the leading column comes from the backend-side clock advanced on every public step path. Free-base quaternions are converted to wxyz through the same _motrix_qpos_to_mujoco() path as the public state getters.

Return type:

ndarray

set_physics_state(state)[source]

Restore a get_physics_state snapshot through the set_state path.

Parameters:

state (ndarray)

Return type:

None

get_playback_model(env_index=None)[source]

Return the MJCF file path used by detached MuJoCo playback.

Motrix has no MJCF export API and none is needed: whole-MJCF scenes replay through their construction source and portable scenes through the composed MJCF. Portable fixed-variant scenes with more than one materialized source follow the Drake contract: an explicit env_index is required and the row’s assigned variant source is returned.

Parameters:

env_index (int | None)

Return type:

str

get_scene_model_file()[source]

Return the materialized scene path for diagnostics, when available.

Return type:

str | None

close()[source]
Return type:

None

reset_entities(request)[source]

Validate the complete selected-entity request, then commit it once.

Validation failure leaves all state unchanged. A native partial commit failure must fault the backend unless the adapter can actually roll back. Unselected entities/environments and fixed identity remain unchanged.

Parameters:

request (Any)

Return type:

None

get_dr_capabilities()[source]

Return supported domain-randomization capabilities for this backend.

Return type:

DomainRandomizationCapabilities

get_reset_term_default(term)[source]

Return the committed per-environment table for a curated reset term.

Reset-term defaults serve as packed-reset baselines, so they track committed randomization: values are read back live from the native override state (unmapped portable columns keep their construction defaults). Delta terms keep zero baselines.

Parameters:

term (str)

Return type:

ndarray

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

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

Parameters:
Return type:

PlayRenderPlan

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:
Return type:

str | None

copy_body_state_w_rows(env_ids, body_ids, out_pos, out_quat, out_lin_vel, out_ang_vel)[source]

Read selected rows/bodies into caller-owned float32 buffers.

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

get_tensor_execution()[source]

Declare MotrixSim’s CPU-authoritative tensor execution profile.

Return type:

TensorExecution

get_tensor_capabilities()[source]

Return the MotrixSim packed host-bridge capability matrix.

Return type:

TensorLifecycleCapabilities

get_public_state_widths()[source]

Return the canonical public qpos/qvel tensor reset widths.

Return type:

PublicStateWidths

bind_host_bridge_io(spec)[source]

Compile persistent MotrixSim staging and packed device layouts.

Parameters:

spec (TensorIOSpec)

Return type:

HostBridgeTransferPlan

get_state_views(fields=None, device=None)[source]

Copy authoritative CPU state to an explicitly selected Torch device.

Parameters:
Return type:

Mapping[str, Any]

get_sensor_view(name, device=None)[source]

Copy one authoritative CPU sensor block to a Torch device.

Parameters:
Return type:

Any

step_tensor(ctrl, nsteps=1)[source]

Bridge one accelerator control tensor to CPU MotrixSim physics.

Parameters:
Return type:

dict | None

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

Bridge selected accelerator reset state to CPU MotrixSim physics.

Parameters:

  • env_indices (Any)

  • qpos (Any)

  • qvel (Any)

  • randomization (TensorResetRandomizationPayload | None)

Return type:

dict | None

set_state_tensor_mask(reset_mask, qpos, qvel, randomization=None, *, full_refresh=False)[source]

Commit full-width accelerator reset state selected by a bool mask.

Parameters:

  • reset_mask (Any)

  • qpos (Any)

  • qvel (Any)

  • randomization (TensorResetRandomizationPayload | None)

  • full_refresh (bool)

Return type:

dict | None

bind_packed_reset(*, device=None)[source]

Begin a host-bridge transaction with one packed reset commit boundary.

Parameters:

device (Any | None)

Return type:

Any

push_robots(push)[source]

Apply producer-sampled push forces through the Motrix Link API.

The producer owns random generation. push is a full-width (num_envs, 3) Torch tensor or a TensorIntervalPayload whose push_force carries that table; this host bridge converts it to NumPy at the boundary and a missing payload fails closed.

Parameters:

push (Any)

Return type:

None

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

Apply absolute world-frame external wrenches through Motrix Link APIs.

Parameters:
Return type:

None

bind_height_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:
Return type:

HeightScanner

bind_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:
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]