unilab.base.backend_factory¶
UniLab owner-layer assembly for UniSim physics backends.
This module owns only UniLab concerns: resolving hosted robot assets and
translating EnvCfg backend options into the public unisim
factory. Physics implementations and their public contract live in the
unisim-core distribution.
Functions
|
Prepare UniLab-owned assets and construct a UniSim backend. |
|
Translate |
- class unilab.base.backend_factory.SimBackend[source]¶
Bases:
ABCUnified simulation backend contract.
- property capabilities¶
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.
- get_state(fields=None)[source]¶
Return a detached, backend-neutral state snapshot.
qposandqvelare assembled from the public kinematic getters; adapters may override this to expose native fields such asctrl. This convenience API keeps benchmark clients independent from private model/data objects while the full reset contract remainsset_state.
- abstract property model¶
Underlying physics model.
- abstract get_actuator_ctrl_range()[source]¶
Return actuator control ranges.
- Return type:
- Returns:
Array with shape
(num_actuators, 2)and columns[low, high].
- 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.
- get_scene_visual_model_file()[source]¶
Return the scene visual model file on the cold path, when available.
Backends without a separate visual scene model return
None.
- 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
- abstract get_keyframe_qpos(name)[source]¶
Return the full qpos for a named keyframe, including the floating base.
- get_default_qpos()[source]¶
Return the backend/model default qpos through a stable contract.
- Return type:
- 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:
- abstract get_init_qvel()[source]¶
Return a zero-initialized qvel vector compatible with
set_state.- Return type:
- 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_nameowns 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
- abstract get_body_ids(names)[source]¶
Resolve body/link names to backend integer IDs.
- Parameters:
- Return type:
- Returns:
int32array with shape(len(names),).- Raises:
ValueError – If any name is not found.
- get_geom_solref()[source]¶
Return default contact reference parameters, shape (ngeom, 2).
- Return type:
- get_geom_solimp()[source]¶
Return default contact impedance parameters, shape (ngeom, 5).
- Return type:
- bind_mocap_pose(body_name)[source]¶
Resolve a mocap body once; unavailable capabilities fail at binding.
- Parameters:
body_name (
str)- Return type:
BackendMocapPoseBinding
- 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.
- cleanup_scene_assets()[source]¶
Release cold-path scene artifacts owned by the backend.
- Return type:
- set_pre_step_control(fn)[source]¶
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.
- abstract 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 byget_root_state_layout()use world xyz and wxyz quaternion.qvel (
ndarray) – Velocity state. Free-root columns exposed byget_root_state_layout()use world linear velocity and body-frame angular velocity.randomization (
ResetRandomizationPayload|None) – Optional backend randomization payload.
- Return type:
- 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 treatNoneor missing keys as “not reported” — the outer wall-clock measurement inDomainRandomizationManager.reset(dr_reset_set_state_ms) remains authoritative for total set_state time.
- abstract get_dr_capabilities()[source]¶
Return supported domain-randomization capabilities for this backend.
- Return type:
- apply_init_randomization(plan)[source]¶
Apply cold-path model/materialization randomization.
- Parameters:
plan (
InitRandomizationPlan)- Return type:
- 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(). A term without a handler fails closed withNotImplementedErrornaming 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:
- apply_body_force(body_ids, force, torque=None)[source]¶
Apply a world-frame force (and optional torque) to 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).torque (
ndarray|None) – Optional world-frame torque values with the same shape. Backends without a torque channel must fail closed when this is notNone.
- Return type:
- Returns:
None. Backends that support this mutate their pending simulation state.
- 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.
- 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_kwargsis normalized intoCameraCfgat this boundary; unknown mapping keys fail closed with an error naming them.debug_overlay_getteris an optional per-frame callback returning a sequence with one entry per environment (len == num_envs); each entry is that env’s sequence ofDebugPrimitive(Noneor empty marks an env without overlay) and returningNonedisables overlays for the frame. Primitive poses are env-local; the renderer applies grid offsets when composing multiple envs. Backends whoseget_play_capabilities().supports_debug_overlayis False fail closed withNotImplementedErrorwhen this is notNone. On the interactive rendering path only backends whosesupports_interactive_debug_overlayis True consume it; the others fail closed withNotImplementedError.on_frameis 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 orNoneto keep the original. Backends rendering through a native (non-offline) renderer fail closed withNotImplementedErrorwhen this is notNone.Known boundary:
envis 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.
- init_renderer(spacing=1.0, *, offset_mode='grid', headless=False, capture=False, width=1280, height=720, camera_kwargs=None)[source]¶
Initialize a backend-native renderer.
headlesscontrols whether a native window is opened.capturecontrols whethercapture_video_frameis valid for the renderer.camera_kwargsis normalized intoCameraCfgat this boundary; unknown mapping keys fail closed with an error naming them.
- render()[source]¶
Render one frame through a backend-native interactive renderer.
- Raises:
RenderClosedError – If the user closed the render window.
- Return type:
- capture_video_frame()[source]¶
Capture one RGB frame through a backend-native renderer.
- Raises:
RenderClosedError – If the user closed the render window.
- Return type:
- get_physics_state()[source]¶
Return a physics snapshot suitable for offline playback/video export.
Rows use the
[time, qpos, qvel]layout; backends whose model has mocap bodies append[mocap_pos(nmocap*3), mocap_quat(nmocap*4)]so offline rendering can replay mocap-driven geometry at its recorded pose.- Return type:
- set_physics_state(state)[source]¶
Restore a snapshot produced by
get_physics_state.Backends implementing this must refresh their host caches so state and sensor getters stay consistent with the restored physics state.
- get_playback_model(env_index=None)[source]¶
Return the playback model for a specific env when variants exist.
- abstract get_base_pos()[source]¶
Return base position in the world frame.
- Return type:
- Returns:
(num_envs, 3)
- abstract get_base_quat()[source]¶
Return base quaternion in the world frame as
wxyz.- Return type:
- Returns:
(num_envs, 4)
- abstract 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:
- Returns:
(num_envs, 3)
- abstract 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:
- Returns:
(num_envs, 3)
- abstract get_dof_pos()[source]¶
Return joint positions, excluding the base.
- Return type:
- Returns:
(num_envs, num_dof)
- abstract get_dof_vel()[source]¶
Return joint velocities, excluding the base.
- Return type:
- Returns:
(num_envs, num_dof)
- abstract get_body_quat_w(body_ids)[source]¶
Return selected body quaternions in the world frame as
wxyz.
- get_body_pose_w(body_ids)[source]¶
Return selected body positions and quaternions in the world frame.
- abstract get_body_lin_vel_w(body_ids)[source]¶
Return selected body linear velocities in the world frame.
- get_body_vel_w(body_ids)[source]¶
Return selected body linear and angular velocities in the world frame.
- abstract get_body_ang_vel_w(body_ids)[source]¶
Return selected body angular velocities in the world frame.
- get_body_state_w(body_ids)[source]¶
Get selected body position, quaternion, linear velocity, and angular velocity.
- 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.
- get_body_pose_w_rows(env_ids, body_ids)[source]¶
Get selected env rows of world-frame body position and quaternion.
- get_body_lin_vel_w_rows(env_ids, body_ids)[source]¶
Get selected env rows of world-frame body linear velocity.
- get_body_ang_vel_w_rows(env_ids, body_ids)[source]¶
Get selected env rows of world-frame body angular velocity.
- abstract get_body_quat_b(body_ids)[source]¶
Return selected body quaternions in the baselink frame as
wxyz.
- abstract 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).
- abstract 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).
- 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.
- get_joint_dof_vel_indices(names)[source]¶
Resolve joint names to DoF indices in velocity space (qvel).
- get_joint_state_qpos_indices(names)[source]¶
Resolve single-DoF joints to full
set_stateqpos columns.Unlike
get_joint_dof_pos_indices(), these indices address the complete qpos vector accepted byset_state(), including any root coordinates. Manager reset transactions resolve them on the cold path.
- get_joint_state_qvel_indices(names)[source]¶
Resolve single-DoF joints to full
set_stateqvel columns.
- get_site_jacobian_w(site_id, dof_indices)[source]¶
Compute world-frame Jacobians for one site and selected DoF columns.
- get_sensor_data_batch(names)[source]¶
Fetch multiple sensors and concatenate their flattened values.
- bind_sensor_data(names)[source]¶
Materialize a validated view over named sensors on the cold path.
The existing sensor getters remain the sole backend adapter surface. This method validates each requested sensor once, records its flattened width, and returns a stable view for manager terms. Backends override the protected reader hook when numeric slots or stable cache slices are available; callers do not depend on that implementation detail.