Language

unisim.backend.isaacsim.backend.IsaacSimBackend¶

class unisim.backend.isaacsim.backend.IsaacSimBackend[source]¶

Bases: MjcfSubprocessBackend

Thin host client for the IsaacLab/PhysX worker.

The shared client owns pipe framing, shared-memory slot allocation, timeout/crash diagnostics, XML cold-path metadata, and all NumPy state views. Physics remains the default (render_mode=None). Eval/play profiles pass a concrete render intent through the cold INIT payload so Kit selects the correct experience before simulation materialization. The worker owns all camera/viewport operations; this class validates the NumPy-facing frame contract.

Parameters:

scene (Any)
num_envs (int)
sim_dt (float)
render_mode (str | None)
render_width (int)
render_height (int)
solver_position_iteration_count (int | None)
solver_velocity_iteration_count (int | None)
bounce_threshold_velocity (float | None)
contact_offset (float | None)
rest_offset (float | None)
max_depenetration_velocity (float | None)
gpu_max_rigid_contact_count (int | None)
gpu_max_rigid_patch_count (int | None)
tensor_cuda_ipc (bool)
share_friction_materials (bool)
env_spacing (float | None)
kwargs (Any)

Methods

`__init__`(scene, num_envs, sim_dt, *[, ...])
`apply_body_force`(body_ids, force[, torque])	Stage a world-frame wrench for the next mapped-scene step.
`apply_interval_randomization`(plan)	Apply a scheduled interval randomization plan.
`bind_height_scanner`(*, hfield_geom_id, ...)	Create a reusable height-field scanner on the init/cold path.
`bind_host_bridge_io`(spec)	Compile a persistent transfer plan for a declared host bridge.
`bind_mocap_pose`(body_name)	Resolve a mocap body once; unavailable capabilities fail at binding.
`bind_packed_reset`(*[, device])	Begin a packed transaction over the external CUDA IPC reset boundary.
`bind_renderer`([spacing, offset_mode, ...])	Initialize the worker-side viewer and/or capture camera.
`bind_sensor_data`(names)	Materialize a validated view over named tensor sensors.
`capture_video_frame`()	Capture one RGB frame from the worker's camera sensor.
`cleanup_scene_assets`()	Release all backend-owned resources, including the worker process.
`close`()	Shut down the worker and release shared memory.
`get_actuator_ctrl_range`()	Position-target clamp per dof, from the MJCF `ctrlrange` attributes.
`get_actuator_gains`()	Per-dof (kp, kd) from the MJCF `<position>` actuators (pure XML).
`get_actuator_joint_names`()	The shared position-control profile drives one actuator per DoF.
`get_actuator_names`()	Return actuator names in control-vector order on the cold path.
`get_body_id`(name)	Resolve one body/link name through the backend contract.
`get_body_ids`(names)	Resolve body/link names to backend integer IDs.
`get_body_ipos`([env_ids])	Return canonical defaults or native selected materialization COM offsets.
`get_body_mass`()	Return native per-environment body masses in public body-id order.
`get_body_subtree_ids`(root_body_id)	Return body ids in the subtree rooted at `root_body_id`.
`get_capabilities`(*[, profile])	Query semantic declarations plus authoritative DR/play/variant support.
`get_default_dof_pos`()	Return default joint positions in canonical non-root qpos order.
`get_default_geom_sizes`()	Return default geometry sizes, shape (ngeom, 3).
`get_default_qpos`()	Return the backend/model default qpos through a stable contract.
`get_dof_armature`()	Return the backend dof-armature table.
`get_dof_damping`()	Return default joint damping, shape (nv,).
`get_dof_frictionloss`()	Return default joint friction loss, shape (nv,).
`get_dr_capabilities`()	Advertise only reset and wrench terms implemented by mapped scenes.
`get_entity_default_state`(entity[, env_ids])	Detached construction/keyframe defaults in selected environment order.
`get_entity_names`()	Return materialized physical entity names in the frozen public order.
`get_entity_state`(entity)	Return detached root_pose/root_velocity/joint_positions/joint_velocities.
`get_geom_body_ids`()	Return owning public body IDs in frozen geometry order.
`get_geom_contact_masks`()	Return normalized native collision state in public geometry order.
`get_geom_friction`()	Return native effective per-environment friction in public order.
`get_geom_id`(name)	Resolve one geom name through the backend contract.
`get_geom_names`()	Return qualified geometry names in frozen public geometry order.
`get_geom_size`(name)	Return one geom size vector in backend geom-name order.
`get_geom_solimp`()	Return default contact impedance parameters, shape (ngeom, 5).
`get_geom_solref`()	Return default contact reference parameters, shape (ngeom, 2).
`get_gravity`()	Return the backend gravity vector.
`get_import_report`()	Return a detached construction/materialization configuration snapshot.
`get_init_qvel`()	Return a zero-initialized qvel vector compatible with `set_state_tensor`.
`get_joint_dof_indices`(names)	Resolve named joints to absolute qvel indices (root 6 columns first).
`get_joint_dof_pos_indices`(names)	Resolve joint names to DoF indices in position space (qpos).
`get_joint_dof_vel_indices`(names)	Resolve joint names to joint-section DoF indices in velocity space.
`get_joint_range`(*[, names])	Per-joint `range` from the MJCF (pure XML, available pre-materialize).
`get_joint_state_qpos_indices`(names)	Resolve single-DoF joints to full `set_state_tensor` qpos columns.
`get_joint_state_qvel_indices`(names)	Resolve single-DoF joints to full `set_state_tensor` qvel columns.
`get_keyframe_qpos`(name)	Return the full qpos for a named keyframe, including the floating base.
`get_motion_body_ids`(names)	Resolve body IDs used by motion datasets.
`get_physics_state`()	Assemble contract `[time, qpos, qvel]` rows from the public slots.
`get_physics_state_layout`()	Return the `[time, qpos, qvel]` snapshot layout (no mocap tail yet).
`get_play_capabilities`()	Return the Kit viewer/camera plus physics-state playback capabilities.
`get_playback_mocap_state`([env_index])	Return copied `(mocap_pos, mocap_quat)` arrays for detached playback.
`get_playback_model`([env_index])	Return the MJCF playback source for detached MuJoCo replay.
`get_public_state_widths`()	Return the mapped public qpos/qvel arena widths.
`get_reset_term_default`(term)	Return per-environment variant-assigned mapped reset defaults.
`get_root_state_layout`(root_body_name)	Resolve one body's floating-root columns on the cold path.
`get_scene_layout`()	Return the immutable materialized public addresses, never native handles.
`get_scene_model_file`()	Return the materialized scene path for diagnostics, when available.
`get_scene_visual_model_file`()	Return the scene visual model file on the cold path, when available.
`get_sensor_inventory`()	Return the complete CUDA IPC tensor-sensor namespace without host slots.
`get_sensor_names`()	Return the complete public named-sensor namespace.
`get_sensor_view`(name[, device])	Return one named sensor view on the declared tensor lifecycle.
`get_site_ids`(names)	Resolve site names to integer ID arrays.
`get_site_jacobian_w`(site_id, dof_indices)	Compute world-frame Jacobians for one site and selected DoF columns.
`get_state_views`([fields, device])	Return backend-owned state through the declared tensor lifecycle.
`get_tensor_capabilities`()	Return fail-closed tensor methods and negotiable state fields.
`get_tensor_execution`()	Declare the optional tensor lifecycle without discovering SDKs.
`get_tensor_runtime_diagnostics`()	Return runtime-selected diagnostics for optional tensor optimizations.
`get_terrain_spawn_data`()	Return backend-materialized terrain metadata on the cold path.
`get_tracked_body_views`([body_names, device])	Return four ordered tracked-body blocks from one public IPC read.
`materialize`()	Spawn the worker, run the handshake, and bind shared-memory slots.
`render`()	Draw one interactive viewer frame through the worker.
`reset_entities`(request)	Validate the complete selected-entity request, then commit it once.
`resolve_play_render_plan`(*, ...)	Resolve high-level playback mode into backend-owned render parameters.
`run_playback`(*, env, initialize, step, num_steps)	Execute backend-owned playback for an env wrapper.
`set_mocap_pose_tensor`(body_name, ...)	Write selected mocap poses through the declared tensor lifecycle.
`set_physics_state`(state)	Restore a `get_physics_state` snapshot through the set_state path.
`set_pre_step_control`(fn)	Register a callback for mapped scenes; model-file callbacks stay rejected.
`set_state_tensor`(env_indices, qpos, qvel[, ...])	Set selected state through the adapter-declared tensor lifecycle.
`set_state_tensor_mask`(reset_mask, qpos, qvel)	Commit full-width state through a backend-owned mask projection.
`step_tensor`(ctrl[, nsteps])	Advance physics from a backend-declared accelerator control tensor.

Attributes

`capability_flags`	Coarse capability labels for clients that need a cheap feature check.
`model`	Return backend-owned model metadata; never a live physics object.
`num_actuators`	Number of actuators.
`num_dof_vel`	Number of joint velocity DoFs, excluding the floating base.
`num_envs`	Number of vectorized environments.
`backend_type`

__init__(scene, num_envs, sim_dt, *, render_mode=None, render_width=1280, render_height=720, solver_position_iteration_count=None, solver_velocity_iteration_count=None, bounce_threshold_velocity=None, contact_offset=None, rest_offset=None, max_depenetration_velocity=None, gpu_max_rigid_contact_count=None, gpu_max_rigid_patch_count=None, tensor_cuda_ipc=False, share_friction_materials=False, env_spacing=None, **kwargs)[source]¶

Parameters:

scene (Any)
num_envs (int)
sim_dt (float)
render_mode (str | None)
render_width (int)
render_height (int)
solver_position_iteration_count (int | None)
solver_velocity_iteration_count (int | None)
bounce_threshold_velocity (float | None)
contact_offset (float | None)
rest_offset (float | None)
max_depenetration_velocity (float | None)
gpu_max_rigid_contact_count (int | None)
gpu_max_rigid_patch_count (int | None)
tensor_cuda_ipc (bool)
share_friction_materials (bool)
env_spacing (float | None)
kwargs (Any)

get_dr_capabilities()[source]¶

Advertise only reset and wrench terms implemented by mapped scenes.

Host-plane sets cover torch.cpu payloads; the device plane (torch.cuda) carries the CUDA IPC PD-gain lane only.

Return type:: DomainRandomizationCapabilities

get_reset_term_default(term)[source]¶

Return per-environment variant-assigned mapped reset defaults.

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

apply_interval_randomization(plan)[source]¶

Apply a scheduled interval randomization plan.

Generic dispatch: each op yielded by plan.iter_ops() is validated against the builtin term specs (custom terms pass through) and routed to the backend-owned handler table returned by _interval_term_handlers(). Op payloads are torch-first: Torch tensors or TensorIntervalPayload values produced by the caller; host adapters convert tensors at their private boundary through unisim.dr._host, and a missing producer-sampled payload fails closed. A term without a handler fails closed with NotImplementedError naming the backend class and the term. Backends that need per-plan prologue/epilogue semantics (for example clearing staged external forces before the ops accumulate) keep a thin override that calls this base implementation.

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

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

Stage a world-frame wrench for the next mapped-scene step.

The force acts at each target body’s center of mass and the optional torque is about that center. Repeated submissions accumulate until the next successful step consumes them.

Parameters:

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

Return type:

None

set_pre_step_control(fn)[source]¶

Parameters:: fn (Any | None)
Return type:: None

get_tensor_execution()[source]¶

Declare the optional tensor lifecycle without discovering SDKs.

Return type:: TensorExecution

get_tensor_capabilities()[source]¶

Return fail-closed tensor methods and negotiable state fields.

Return type:: TensorLifecycleCapabilities

get_public_state_widths()[source]¶

Return the mapped public qpos/qvel arena widths.

Return type:: PublicStateWidths

get_sensor_inventory()[source]¶

Return the complete CUDA IPC tensor-sensor namespace without host slots.

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

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

Return backend-owned state through the declared tensor lifecycle.

Tensor views are Torch tensors. Returned values are logically read-only and mutation is undefined.

DEVICE_RESIDENT adapters return stable live views on the backend’s exact accelerator device; device=None selects that device and any other device is rejected. HOST_BRIDGE adapters return explicit copies from authoritative host state; device=None selects host CPU and callers pass an explicit accelerator device for H2D copies. Unlike the removed 1.x NumPy snapshot API, successful tensor adapters do not return NumPy arrays. Consume the declared tensor execution mode rather than probing the array implementation.

Parameters:

fields (tuple[str, ...] | str | None)
device (Any | None)

Return type:

Mapping[str, Any]

get_sensor_view(name, device=None)[source]¶

Return one named sensor view on the declared tensor lifecycle.

Parameters:

name (str)
device (Any | None)

Return type:

Any

get_tracked_body_views(body_names=None, device=None)[source]¶

Return four ordered tracked-body blocks from one public IPC read.

Parameters:

body_names (Sequence[str] | None)
device (Any | None)

Return type:

TrackedBodyStateViews

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

Advance physics from a backend-declared accelerator control tensor.

ctrl is a contiguous float32 Torch tensor with shape (num_envs, num_actuators), lives on the adapter-required device, and must be finite. The method consumes it before synchronizing and returning.

Parameters:

ctrl (Any)
nsteps (int)

Return type:

dict | None

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

Set selected state through the adapter-declared tensor lifecycle.

env_indices is a contiguous one-dimensional int64 Torch tensor with unique values in [0, num_envs); qpos and qvel are contiguous float32 tensors with shapes (len(env_indices), nq) and (len(env_indices), nv). All three share one adapter-accepted device and must be finite. Adapters may use a bounded synchronization for fail-closed row validation. DEVICE_RESIDENT adapters otherwise avoid a host detour; HOST_BRIDGE adapters make their explicit accelerator-to-host boundary measurable before CPU state is updated. Inputs are consumed before return.

randomization is the unified torch-first TensorResetRandomizationPayload: every populated field is a dense selected-row Torch tensor table. Tensors on torch.cpu form the host plane, checked against DomainRandomizationCapabilities.supported_reset_terms; tensors on any other device form the device plane, checked against supported_device_reset_terms (empty by default, so undeclared device support fails closed naming the term). Non-delta terms hold final absolute values applied as selected-row in-place scatters; base_mass_delta and base_com_offset hold deltas merged with the adapter baseline. Host adapters convert tensors at their private NumPy boundary through unisim.dr._host.

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 state through a backend-owned mask projection.

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 packed transaction over the external CUDA IPC reset boundary.

Parameters:: device (Any | None)
Return type:: Any

close()[source]¶

Shut down the worker and release shared memory. Idempotent.

Return type:: None

get_body_mass()[source]¶

Return native per-environment body masses in public body-id order.

Return type:: ndarray

get_body_ipos(env_ids=None)[source]¶

Return canonical defaults or native selected materialization COM offsets.

Parameters:: env_ids (Sequence[int] | ndarray | None)
Return type:: ndarray

get_geom_names()[source]¶

Return qualified geometry names in frozen public geometry order.

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

get_geom_body_ids()[source]¶

Return owning public body IDs in frozen geometry order.

Return type:: ndarray

get_geom_contact_masks()[source]¶

Return normalized native collision state in public geometry order.

Return type:: tuple[ndarray, ndarray]

get_geom_friction()[source]¶

Return native effective per-environment friction in public order.

Columns are IsaacSim [static_friction, dynamic_friction, 0]. PhysX has no native equivalent for MuJoCo’s torsional/rolling coefficients.

Return type:: ndarray

get_play_capabilities()[source]¶

Return the Kit viewer/camera plus physics-state playback capabilities.

Both scene profiles implement the playback contract. The mapped entity scene serves worker-maintained public qpos/qvel rows; the model-file whole-model profile assembles the same snapshot from its root/dof wire slots once the construction-time joint-order validation passes. Model-file scenes whose MJCF topology the synthetic 7/6-root wire cannot replay (fixed base, ball joints, reordered freejoints) keep failing closed here.

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 from the public slots.

The worker refreshes the public shared-memory rows after every step and reset, so the snapshot is a host-side copy of those rows plus the leading time column; no new IPC frame or worker-side asset access is involved. The worker protocol carries no simulation clock, so time comes from the per-env host accumulator advanced on every public step path and zeroed on full state resets, mirroring the mujoco backend’s time semantics.

The mapped profile copies the MJCF-order qpos/qvel rows verbatim. The model-file profile projects its wire slots: root_state carries the synthetic floating root as [pos, quat wxyz, world lin vel (link origin), world ang vel] and dof_state the scalar joints in MJCF document order, so the snapshot’s MuJoCo-convention qvel angular block is the world angular velocity rotated into the body frame — exactly the convention the model-file set_state path consumes, which keeps snapshot restore a lossless round trip.

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 playback source for detached MuJoCo replay.

The mapped profile keeps the shared implementation (fixed-variant scenes require an explicit env_index). The model-file profile replays through its whole-MJCF construction source; the adapter rejects model-file fixed-variant plans at construction, so one source serves every row.

Parameters:: env_index (int | None)
Return type:: Any

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:

PlayRenderPlan

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

HeightScanner

bind_host_bridge_io(spec)¶

Compile a persistent transfer plan for a declared host bridge.

Parameters:: spec (TensorIOSpec)
Return type:: HostBridgeTransferPlan

bind_mocap_pose(body_name)¶

Resolve a mocap body once; unavailable capabilities fail at binding.

Parameters:: body_name (str)
Return type:: MocapPoseBinding

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

Initialize the worker-side viewer and/or capture camera.

spacing/offset_mode are accepted for contract parity and ignored: envs are already laid out on the worker sim’s grid.

Parameters:

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

Return type:

None

bind_sensor_data(names)¶

Materialize a validated view over named tensor sensors.

This cold-path binding records the flattened public view width and delegates execution to the backend-owned tensor sensor reader. It never falls back to a NumPy named-sensor getter.

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

property capability_flags¶

Coarse capability labels for clients that need a cheap feature check.

The detailed contract is expressed by the methods on this class. The labels remain useful for benchmark/conformance metadata and are derived from the mandatory lifecycle methods rather than maintained separately by every adapter.

cleanup_scene_assets()¶

Release all backend-owned resources, including the worker process.

NpEnv.close() deliberately depends on the base cleanup_scene_assets hook rather than a backend-specific close method. A subprocess backend must therefore bridge that lifecycle hook explicitly; otherwise closing a manager environment would leave the Python 3.8/3.11 worker and its shared-memory segments alive until interpreter teardown.

Return type:: None

get_actuator_ctrl_range()¶

Position-target clamp per dof, from the MJCF ctrlrange attributes.

Pure XML metadata (available pre-materialize). Undeclared ctrlranges report (0, 0), matching the MuJoCo backend which returns the raw actuator_ctrlrange (ctrllimited=false → 0 0).

Return type:: ndarray

get_actuator_gains()¶

Per-dof (kp, kd) from the MJCF <position> actuators (pure XML).

Passive joints (no actuator) report zero gains. Returned in MJCF joint document order, which the INIT handshake pins to the worker’s dof order.

Return type:: tuple[ndarray, ndarray]

get_actuator_joint_names()¶

The shared position-control profile drives one actuator per DoF.

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

get_actuator_names()¶

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

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

get_body_id(name)¶

Resolve one body/link name through the backend contract.

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

get_body_ids(names)¶

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_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_capabilities(*, profile='default')¶

Query semantic declarations plus authoritative DR/play/variant support.

This cold-path query does not discover SDKs or verify runtime behavior. Materialized configuration readback is exposed by get_import_report.

Parameters:: profile (str)
Return type:: CapabilityReport

get_default_dof_pos()¶

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_default_geom_sizes()¶

Return default geometry sizes, shape (ngeom, 3).

Return type:: ndarray

get_default_qpos()¶

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

Return type:: ndarray

get_dof_armature()¶

Return the backend dof-armature table.

Return type:: ndarray

get_dof_damping()¶

Return default joint damping, shape (nv,).

Return type:: ndarray

get_dof_frictionloss()¶

Return default joint friction loss, shape (nv,).

Return type:: ndarray

get_entity_default_state(entity, env_ids=None)¶

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:

entity (str)
env_ids (Sequence[int] | ndarray | None)

Return type:

Mapping[str, ndarray]

get_entity_names()¶

Return materialized physical entity names in the frozen public order.

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

get_entity_state(entity)¶

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_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 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_geom_solimp()¶

Return default contact impedance parameters, shape (ngeom, 5).

Return type:: ndarray

get_geom_solref()¶

Return default contact reference parameters, shape (ngeom, 2).

Return type:: ndarray

get_gravity()¶

Return the backend gravity vector.

Return type:: ndarray

get_import_report()¶

Return a detached construction/materialization configuration snapshot.

This cached report never parses assets, starts workers, or reflects reset-time randomization. Use current-property queries for live values.

Return type:: ImportReport

get_init_qvel()¶

Return a zero-initialized qvel vector compatible with set_state_tensor.

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

get_joint_dof_indices(names)¶

Resolve named joints to absolute qvel indices (root 6 columns first).

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

get_joint_dof_pos_indices(names)¶

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

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_range(*, names=None)¶

Per-joint range from the MJCF (pure XML, available pre-materialize).

The XML is the cross-runtime source of truth for this contract. Joints without a range attribute report (-inf, inf).

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

get_joint_state_qpos_indices(names)¶

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

Resolve single-DoF joints to full set_state_tensor qvel columns.

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

get_keyframe_qpos(name)¶

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_motion_body_ids(names)¶

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

get_playback_mocap_state(env_index=0)¶

Return copied (mocap_pos, mocap_quat) arrays for detached playback.

Shapes are (nmocap, 3) and (nmocap, 4) for the selected environment. Backends exposing this declare get_play_capabilities().supports_mocap_playback.

Parameters:: env_index (int)
Return type:: tuple[ndarray, ndarray]

get_root_state_layout(root_body_name)¶

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_scene_layout()¶

Return the immutable materialized public addresses, never native handles.

Return type:: CompiledSceneLayout

get_scene_model_file()¶

Return the materialized scene path for diagnostics, when available.

Return type:: str | None

get_scene_visual_model_file()¶

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

Backends without a separate visual scene model return None.

Return type:: str | None

get_sensor_names()¶

Return the complete public named-sensor namespace.

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

get_site_ids(names)¶

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_site_jacobian_w(site_id, dof_indices)¶

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_tensor_runtime_diagnostics()¶

Return runtime-selected diagnostics for optional tensor optimizations.

Unlike capability negotiation, these values describe actual cold-path initialization results and may change when a backend falls back or closes. The default empty mapping means the backend declares no optional tensor-runtime optimization.

Return type:: Mapping[str, TensorRuntimeDiagnostic]

get_terrain_spawn_data()¶

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

materialize()¶

Spawn the worker, run the handshake, and bind shared-memory slots.

Idempotent. Called lazily by the first state/metadata access, so env constructors that read shapes before the explicit lifecycle point work like they do on the MuJoCo backend. A closed backend cannot be materialized again.

Return type:: None

property model: SubprocessModelInfo¶: Return backend-owned model metadata; never a live physics object.

property num_actuators: int¶: Number of actuators.

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

property num_envs: int¶: Number of vectorized environments.

render()¶

Draw one interactive viewer frame through the worker.

Return type:: None

reset_entities(request)¶

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 (SceneResetRequest)
Return type:: None

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

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)
initialize (Any)
step (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 (Any)
camera_kwargs (CameraCfg | Mapping[str, Any] | None)
debug_overlay_getter (Any)
on_frame (Any)

Return type:

str | None

set_mocap_pose_tensor(body_name, env_indices, poses)¶

Write selected mocap poses through the declared tensor lifecycle.

Parameters:

body_name (str)
env_indices (Any)
poses (Any)

Return type:

None

backend_type: str¶

capture_video_frame()[source]¶

Capture one RGB frame from the worker’s camera sensor.

Return type:: ndarray