Language

unisim.backend.genesis.backend.GenesisBackend¶

class unisim.backend.genesis.backend.GenesisBackend[source]¶

Bases: SimBackend

Independent Genesis backend exposed through the host NumPy profile.

Construction performs dependency loading, the MJCF cold-path scan, the process-wide gs.init (once), and scene/entity/sensor creation; materialize() builds the batched solver state and binds all runtime caches. Terrain, geom-name contracts, and site Jacobians fail closed. Native interactive/offscreen rendering attaches lazily post-build (see the play contract section). Call close() to end the process-wide Genesis session; re-initialization afterwards fails closed by design.

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (str | None)
push_body_name (str | None)
device_id (int | None)
integrator (str | None)
constraint_solver (str | None)
friction_cone (str | None)
solver_iterations (int | None)
unexpected_kwargs (Any)

Methods

`__init__`(scene, num_envs, sim_dt, *[, ...])
`apply_body_force`(body_ids, force[, torque])	Apply a world-frame force per body through the solver-level API.
`apply_init_randomization`(plan)	Apply cold-path model/materialization randomization.
`apply_interval_randomization`(plan)	Apply a scheduled interval randomization plan.
`bind_mocap_pose`(body_name)	Resolve a mocap body once; unavailable capabilities fail at binding.
`bind_sensor_data`(names)	Materialize a validated view over named sensors on the cold path.
`capture_video_frame`()	Capture one offscreen RGB frame (self-initializes headless+capture).
`cleanup_scene_assets`()	Release cold-path scene artifacts owned by the backend.
`close`()	End the process-wide Genesis session; re-init afterwards fails closed.
`copy_body_state_w`(body_ids, out_pos, ...)	Copy selected world-frame body state into caller-owned buffers.
`create_hfield_scanner`(*, hfield_geom_id, ...)	Create a reusable height-field scanner on the init/cold path.
`get_actuator_ctrl_range`()	MJCF `ctrlrange` metadata; Genesis does not enforce it in-engine.
`get_actuator_gains`()	Return per-joint (kp, kd) arrays from the backend model.
`get_actuator_joint_names`()	Return each actuator's target single-DoF joint in control-vector order.
`get_actuator_names`()	Return actuator names in control-vector order on the cold path.
`get_base_ang_vel`()	Return base angular velocity in the world frame.
`get_base_lin_vel`()	Return base linear velocity in the world frame.
`get_base_pos`()	Return base position in the world frame.
`get_base_quat`()	Return base quaternion in the world frame as `wxyz`.
`get_body_ang_vel_b`(body_ids)	Return selected body angular velocities expressed in each body's own frame.
`get_body_ang_vel_w`(body_ids)	Return selected body angular velocities in the world frame.
`get_body_ang_vel_w_rows`(env_ids, body_ids)	Get selected env rows of world-frame body angular velocity.
`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`()	Return the backend body inertial-position table.
`get_body_lin_vel_b`(body_ids)	Return selected body linear velocities expressed in each body's own frame.
`get_body_lin_vel_w`(body_ids)	Return selected body linear velocities in the world frame.
`get_body_lin_vel_w_rows`(env_ids, body_ids)	Get selected env rows of world-frame body linear velocity.
`get_body_mass`()	Return the backend body-mass table.
`get_body_pos_b`(body_ids)	Return selected body positions in the baselink frame.
`get_body_pos_w`(body_ids)	Return selected body positions in the world frame.
`get_body_pose_w`(body_ids)	Return selected body positions and quaternions in the world frame.
`get_body_pose_w_rows`(env_ids, body_ids)	Get selected env rows of world-frame body position and quaternion.
`get_body_quat_b`(body_ids)	Return selected body quaternions in the baselink frame as `wxyz`.
`get_body_quat_w`(body_ids)	Return selected body quaternions in the world frame as `wxyz`.
`get_body_state_w`(body_ids)	Get selected body position, quaternion, linear velocity, and angular velocity.
`get_body_subtree_ids`(root_body_id)	Return body ids in the subtree rooted at `root_body_id`.
`get_body_vel_w`(body_ids)	Return selected body linear and angular velocities in the world frame.
`get_default_dof_pos`()	Return default joint positions in the same column order as `get_dof_pos`.
`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_dof_pos`()	Return joint positions, excluding the base.
`get_dof_vel`()	Return joint velocities, excluding the base.
`get_dr_capabilities`()	Declare only the per-env round-trip-measured DR items (REPORT §5.7).
`get_geom_body_ids`()	Return the owning body id for each geom.
`get_geom_contact_masks`()	Genesis-native recoded contype/conaffinity of collision geoms.
`get_geom_friction`()	Return the backend geom-friction table.
`get_geom_id`(name)	Resolve one geom name through the backend contract.
`get_geom_names`()	Return backend geom names in backend id order.
`get_geom_size`(name)	Return one geom size vector through the backend contract.
`get_geom_sizes`()	Return default geometry sizes, shape (ngeom, 3).
`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_init_qvel`()	Return a zero-initialized qvel vector compatible with `set_state`.
`get_joint_dof_indices`(names)	Resolve joint names to DoF indices in velocity space (qvel).
`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 DoF indices in velocity space (qvel).
`get_joint_range`()	Return joint position limits, excluding the floating base.
`get_joint_state_qpos_indices`(names)	Resolve single-DoF joints to full `set_state` qpos columns.
`get_joint_state_qvel_indices`(names)	Resolve single-DoF joints to full `set_state` qvel columns.
`get_keyframe_qpos`(name)	Return the full qpos for a named keyframe, including the floating base.
`get_motion_body_ids`(names)	Resolve backend-native body IDs used by motion datasets.
`get_physics_state`()	Return a physics snapshot suitable for offline playback/video export.
`get_play_capabilities`()	Return backend-native play/render capabilities.
`get_playback_model`([env_index])	Return the playback model for a specific env when variants exist.
`get_root_state_layout`(root_body_name)	Resolve one body's floating-root columns on the cold path.
`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_data`(name)	Return sensor data.
`get_sensor_data_batch`(names)	Fetch multiple sensors and concatenate their flattened values.
`get_sensor_data_rows`(name, env_ids)	Get selected env rows of a sensor array.
`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`([fields])	Return a detached, backend-neutral state snapshot.
`get_terrain_spawn_data`()	Return backend-materialized terrain metadata on the cold path.
`init_renderer`([spacing, offset_mode, ...])	Lazily attach the Genesis viewer and/or an offscreen camera.
`materialize`()	Build the batched scene, cross-check the import, and bind caches.
`render`()	Draw one interactive viewer frame (self-initializes interactive).
`reset`([env_ids])	Reset selected environments to the backend's default state.
`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_physics_state`(state)	Restore a snapshot produced by `get_physics_state`.
`set_pre_step_control`(fn)	Register an env-owned policy-control to physics-control converter.
`set_state`(env_indices, qpos, qvel[, ...])	Set physics state for selected environments.
`step`(ctrl[, nsteps])	Advance physics.

Attributes

`capabilities`	Coarse capability labels for clients that need a cheap feature check.
`model`	Return the backend-owned Genesis rigid entity.
`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, *, base_name=None, push_body_name=None, device_id=None, integrator=None, constraint_solver=None, friction_cone=None, solver_iterations=None, **unexpected_kwargs)[source]¶

Parameters:

scene (SceneCfg)
num_envs (int)
sim_dt (float)
base_name (str | None)
push_body_name (str | None)
device_id (int | None)
integrator (str | None)
constraint_solver (str | None)
friction_cone (str | None)
solver_iterations (int | None)
unexpected_kwargs (Any)

backend_type: str¶

materialize()[source]¶

Build the batched scene, cross-check the import, and bind caches.

Idempotent, and called lazily by the first state access: env constructors that validate state shapes before the explicit lifecycle point (ManagerBasedRlEnv builds its EntityScene before calling materialize(), #1382) work like they do on the MuJoCo backend — the same pattern as the isaacgym backend’s lazy materialize. A closed backend cannot be materialized again.

Return type:: None

property num_envs: int¶: Number of vectorized environments.

property model: Any¶: Return the backend-owned Genesis rigid entity.

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

MJCF ctrlrange metadata; Genesis does not enforce it in-engine.

Return type:: ndarray

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

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

Return type:: tuple[ndarray, ndarray]

get_scene_model_file()[source]¶

Return the materialized scene path for diagnostics, when available.

Return type:: str | 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_geom_contact_masks()[source]¶

Genesis-native recoded contype/conaffinity of collision geoms.

Genesis re-synthesizes contype/conaffinity at import: the collision matrix semantics are preserved, but the integer values must NOT be compared against MuJoCo tables (REPORT #1372 §5.10).

Return type:: tuple[ndarray, ndarray]

get_gravity()[source]¶

Return the backend gravity vector.

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

Return the backend dof-armature table.

Return type:: ndarray

get_joint_range()[source]¶

Return joint position limits, excluding the floating base.

Return type:: ndarray | None
Returns:: Array with shape (num_dof, 2) and columns [low, high], or None when the backend does not expose limits.

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

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[str, dict[str, float]]

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[str, dict[str, float]]

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

Declare only the per-env round-trip-measured DR items (REPORT §5.7).

Measured: link inertial mass and dof kp/kv (require the materialize- time batch build flags), plus the solver-level external force API (call-verified; physical effect is a REPORT §8 follow-up). Measured- but-unmappable items stay undeclared: frictionloss/damping/armature have no SimBackend reset term, and geom friction only has a per-env ratio API, so absolute geom_friction randomization is unsupported.

Return type:: DomainRandomizationCapabilities

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

Apply a world-frame force per body through the solver-level API.

Parameters:

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

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

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

Lazily attach the Genesis viewer and/or an offscreen camera.

Both are post-build attachments (verified on 1.3.3): the interactive viewer is a genesis.vis.viewer.Viewer built on the visualizer’s shared context; capture uses a visualizer camera built on demand. spacing/offset_mode are accepted for contract parity and ignored: envs are laid out on the Genesis scene’s own grid. The first (headless, capture) pair is pinned, like the isaacgym backend.

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

Draw one interactive viewer frame (self-initializes interactive).

Return type:: None

capture_video_frame()[source]¶

Capture one offscreen RGB frame (self-initializes headless+capture).

Return type:: ndarray

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

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

close()[source]¶

End the process-wide Genesis session; re-init afterwards fails closed.

Return type:: None

apply_init_randomization(plan)¶

Apply cold-path model/materialization randomization.

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

bind_mocap_pose(body_name)¶

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

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

bind_sensor_data(names)¶

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.

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

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.

cleanup_scene_assets()¶

Release cold-path scene artifacts owned by the backend.

Return type:: None

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]

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_ang_vel_w_rows(env_ids, body_ids)¶

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

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

ndarray

get_body_id(name)¶

Resolve one body/link name through the backend contract.

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

get_body_lin_vel_w_rows(env_ids, body_ids)¶

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

Parameters:

env_ids (ndarray)
body_ids (ndarray)

Return type:

ndarray

get_body_pose_w(body_ids)¶

Return selected body positions and quaternions in the world frame.

Parameters:: body_ids (ndarray)
Return type:: tuple[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]

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]

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_body_vel_w(body_ids)¶

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

Parameters:: body_ids (ndarray)
Return type:: tuple[ndarray, 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_geom_body_ids()¶

Return the owning body id for each geom.

Return type:: ndarray

get_geom_friction()¶

Return the backend geom-friction table.

Return type:: ndarray

get_geom_id(name)¶

Resolve one geom name through the backend contract.

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

get_geom_names()¶

Return backend geom names in backend id order.

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

get_geom_size(name)¶

Return one geom size vector through the backend contract.

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

get_geom_sizes()¶

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

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

Resolve backend-native body IDs used by motion datasets.

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

get_physics_state()¶

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

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_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_state(fields=None)¶

Return a detached, backend-neutral state snapshot.

qpos and qvel are assembled from the public kinematic getters; adapters may override this to expose native fields such as ctrl. This convenience API keeps benchmark clients independent from private model/data objects while the full reset contract remains set_state.

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:: BackendTerrainSpawnData | None

reset(env_ids=None)¶

Reset selected environments to the backend’s default state.

Parameters:: env_ids (ndarray | None)
Return type:: None

set_physics_state(state)¶

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.

Parameters:: state (ndarray)
Return type:: None

set_pre_step_control(fn)¶

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