unilab.base.entity.Entity

class unilab.base.entity.Entity[source]

Bases: object

Logical entity with cached local-to-backend mappings.

Parameters:

Methods

__init__(name, cfg, backend[, ...])

apply_body_wrench_to_sim(forces, torques, ...)

Dispatch world-frame body forces/torques through the formal interval plan.

apply_root_linear_velocity_delta_to_sim(values)

Dispatch a cached root linear-velocity delta through the formal interval plan.

apply_root_velocity_delta_to_sim(...[, ...])

Dispatch world-frame root linear/angular velocity deltas in one interval plan.

bind_actuator_gain_write([actuator_ids])

Bind selected actuator columns and immutable gain defaults on the cold path.

bind_body_inertia_write([body_ids])

Bind entity-local body columns and authoritative default inertias.

bind_body_ipos_write([body_ids])

Bind entity-local body columns and immutable inertial positions.

bind_body_mass_write([body_ids])

Bind entity-local body columns and immutable default masses.

bind_body_state_copy([body_ids])

Bind entity-local body columns to the public tracked-view contract.

bind_body_wrench([body_ids])

Resolve entity-local and backend body columns for interval wrench writes.

bind_geom_friction_write([geom_ids])

Bind entity-local geoms and immutable default friction vectors.

bind_geom_size_write([geom_ids])

Bind entity-local geom_size columns and immutable defaults.

bind_geom_solimp_write([geom_ids])

Bind entity-local geom_solimp columns and immutable defaults.

bind_geom_solref_write([geom_ids])

Bind entity-local geom_solref columns and immutable defaults.

bind_joint_armature_write([joint_ids])

Bind entity-local joints and immutable default DOF armatures.

bind_joint_damping_write([joint_ids])

Bind entity-local joint_damping columns and immutable defaults.

bind_joint_frictionloss_write([joint_ids])

Bind entity-local joint_frictionloss columns and immutable defaults.

bind_mocap_pose_write(body_name, *, term_name)

Bind an explicitly named mocap body, independently of the floating root.

bind_root_angular_velocity_delta(*, term_name)

Validate the interval root angular-velocity capability on the cold path.

bind_root_linear_velocity_delta(*, term_name)

Validate the interval root-velocity capability on the cold path.

body_tensor_view(device[, body_names])

Read explicit entity bodies as validated world-frame Torch state.

find_actuators(keys[, preserve_order])

find_bodies(keys[, preserve_order])

find_cameras(keys[, preserve_order])

find_geoms(keys[, preserve_order])

find_joints(keys[, preserve_order])

find_joints_by_actuator_names(keys)

Resolve actuator-target joint patterns in natural entity joint order.

find_lights(keys[, preserve_order])

find_materials(keys[, preserve_order])

find_pairs(keys[, preserve_order])

find_sites(keys[, preserve_order])

find_tendons(keys[, preserve_order])

find_textures(keys[, preserve_order])

joint_tensor_view(device)

Read entity joint state as validated Torch tensors on device.

read_mocap_pose()

Read full-batch mocap poses, including pending reset writes.

read_reset_root_pose([env_ids])

Read the world position and wxyz root orientation staged in the reset.

record_startup_body_ipos_to_sim(values[, ...])

Stage a startup body-CoM write and promote its committed baseline.

record_startup_body_mass_to_sim(values[, ...])

Stage a startup body-mass write and promote its committed baseline.

sensor_tensor_views(device, names)

Read explicit named backend sensors as validated Torch tensors.

set_full_width_joint_position_target(target)

Fuse the canonical all-joints/all-rows position target publication.

set_joint_effort_target(target[, joint_ids, ...])

Map joint effort (torque) targets to the actuator control buffer.

set_joint_position_target(target[, ...])

Map entity-local joint targets to the env-owned actuator control buffer.

set_joint_velocity_target(target[, ...])

Map joint velocity targets to the entity actuator control buffer.

write_actuator_gains_tensor_mask(reset_mask, ...)

Stage full-width actuator gains selected by the transaction mask.

write_actuator_gains_to_sim(kp, kd[, ...])

Stage entity-local actuator gains in the active reset transaction.

write_body_inertia_to_sim(values[, ...])

Stage selected entity body principal inertias in the reset transaction.

write_body_ipos_to_sim(values[, body_ids, ...])

Stage selected entity body inertial positions in the reset transaction.

write_body_mass_to_sim(values[, body_ids, ...])

Stage selected entity body masses in the active reset transaction.

write_geom_friction_to_sim(values[, ...])

Stage selected entity geom friction in the active reset transaction.

write_geom_size_to_sim(values[, geom_ids, ...])

Stage geom_size values through the reset transaction.

write_geom_solimp_to_sim(values[, geom_ids, ...])

Stage geom_solimp values through the reset transaction.

write_geom_solref_to_sim(values[, geom_ids, ...])

Stage geom_solref values through the reset transaction.

write_joint_armature_to_sim(values[, ...])

Stage selected entity joint armatures in the active reset transaction.

write_joint_damping_to_sim(values[, ...])

Stage joint_damping values through the reset transaction.

write_joint_frictionloss_to_sim(values[, ...])

Stage joint_frictionloss values through the reset transaction.

write_joint_state_to_sim(position, velocity)

Stage community-style joint state writes in the active reset transaction.

write_joint_state_to_sim_mask(position, ...)

Stage full-width joint values for the active reset mask.

write_mocap_pose_to_sim(poses[, env_ids, ...])

Stage poses to commit after the ordinary reset state upload.

write_motion_state_tensor_to_sim(root_state, ...)

Stage one full-width motion root and joint state.

write_root_link_pose_to_sim(root_pose[, env_ids])

Stage world position and wxyz root orientation during reset.

write_root_link_velocity_to_sim(root_velocity)

Stage world linear/angular root velocity during reset.

write_root_state_tensor_to_sim(root_state, ...)

Stage a full-width device-resident 13-D world-frame root state.

write_root_state_to_sim(root_state[, env_ids])

Stage a 13-D world-frame root state in the active reset transaction.

Attributes

actuator_names

body_names

camera_names

geom_names

joint_names

light_names

material_names

motion_body_ids

Motion-dataset body columns for the declared entity body order.

num_actuators

num_bodies

num_cameras

num_geoms

num_joints

num_lights

num_materials

num_pairs

num_sites

num_tendons

num_textures

pair_names

reset_state_tensor_active

Whether the active env-owned reset transaction composes device tensor rows.

site_names

tendon_names

texture_names

__init__(name, cfg, backend, control_buffer=None, reset_state=None, *, default_qpos=None, state_read_cache=None)[source]
Parameters:
property motion_body_ids: ndarray

Motion-dataset body columns for the declared entity body order.

joint_tensor_view(device)[source]

Read entity joint state as validated Torch tensors on device.

The backend owns the transfer topology: host bridges return packed copies and device-resident adapters return stable live views. This facade resolves entity joint columns and validates layout, dtype, device, and finite values without exposing the backend.

Parameters:

device (device)

Return type:

EntityTensorStateView

sensor_tensor_views(device, names)[source]

Read explicit named backend sensors as validated Torch tensors.

Requests are explicit strings (not patterns), so callers resolve regex selectors on their own cold path. This narrow direct path is for single-name diagnostic or device-resident reads. Host-bridge Manager execution must aggregate the same names into one packed read plan; it must not call this method per term.

Parameters:
Return type:

EntityTensorSensorViews

body_tensor_view(device, body_names=None)[source]

Read explicit entity bodies as validated world-frame Torch state.

Body tensor reads consume the canonical backend track_* sensor contract through the public SimBackend boundary. The direct API is available for device-resident adapters with stable live views. CPU host-bridge execution must aggregate the canonical names into one packed scene plan before Manager term use.

Parameters:
Return type:

EntityTensorBodyStateView

property joint_names: tuple[str, ...]
property body_names: tuple[str, ...]
property geom_names: tuple[str, ...]
property site_names: tuple[str, ...]
property actuator_names: tuple[str, ...]
property tendon_names: tuple[str, ...]
property camera_names: tuple[str, ...]
property light_names: tuple[str, ...]
property material_names: tuple[str, ...]
property texture_names: tuple[str, ...]
property pair_names: tuple[str, ...]
property num_joints: int
property num_bodies: int
property num_geoms: int
property num_sites: int
property num_actuators: int
property num_tendons: int
property num_cameras: int
property num_lights: int
property num_materials: int
property num_textures: int
property num_pairs: int
find_joints(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_joints_by_actuator_names(keys)[source]

Resolve actuator-target joint patterns in natural entity joint order.

Parameters:

keys (str | Sequence[str])

Return type:

tuple[list[int], list[str]]

set_joint_position_target(target, joint_ids=None, env_ids=None)[source]

Map entity-local joint targets to the env-owned actuator control buffer.

Parameters:
Return type:

None

set_full_width_joint_position_target(target)[source]

Fuse the canonical all-joints/all-rows position target publication.

target is in the entity’s natural joint order. This method resolves the immutable joint-to-actuator mapping once on the cold path and writes directly into the full Torch control plane, avoiding separate index selection and control scatter kernels. Partial/reordered targets use set_joint_position_target.

Parameters:

target (Tensor)

Return type:

None

set_joint_velocity_target(target, joint_ids=None, env_ids=None)[source]

Map joint velocity targets to the entity actuator control buffer.

Parameters:
Return type:

None

set_joint_effort_target(target, joint_ids=None, env_ids=None)[source]

Map joint effort (torque) targets to the actuator control buffer.

Parameters:
Return type:

None

bind_body_state_copy(body_ids=None)[source]

Bind entity-local body columns to the public tracked-view contract.

Parameters:

body_ids (ndarray | Sequence[int] | slice | None)

Return type:

Callable[[ndarray, ndarray, ndarray, ndarray], tuple[ndarray, ndarray, ndarray, ndarray]]

write_root_state_to_sim(root_state, env_ids=None)[source]

Stage a 13-D world-frame root state in the active reset transaction.

Parameters:
Return type:

None

write_root_state_tensor_to_sim(root_state, reset_mask)[source]

Stage a full-width device-resident 13-D world-frame root state.

Parameters:
Return type:

None

write_motion_state_tensor_to_sim(root_state, position, velocity, reset_mask)[source]

Stage one full-width motion root and joint state.

Parameters:
Return type:

None

property reset_state_tensor_active: bool

Whether the active env-owned reset transaction composes device tensor rows.

Manager terms probe this before choosing the device-resident DR staging path: a host-composed reset (including the packed host bridge and the NumPy scoped_device_tensor commit) must keep the NumPy write path.

bind_actuator_gain_write(actuator_ids=None, *, term_name)[source]

Bind selected actuator columns and immutable gain defaults on the cold path.

Parameters:
Return type:

tuple[ndarray, Tensor, Tensor]

write_actuator_gains_to_sim(kp, kd, actuator_ids=None, env_ids=None, *, term_name='pd_gains')[source]

Stage entity-local actuator gains in the active reset transaction.

Parameters:
Return type:

None

write_actuator_gains_tensor_mask(reset_mask, kp, kd, actuator_ids=None, *, term_name='pd_gains')[source]

Stage full-width actuator gains selected by the transaction mask.

Parameters:
Return type:

None

bind_geom_size_write(geom_ids=None, *, term_name)[source]

Bind entity-local geom_size columns and immutable defaults.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_size_to_sim(values, geom_ids=None, env_ids=None, *, term_name='geom_size')[source]

Stage geom_size values through the reset transaction.

Parameters:
Return type:

None

bind_geom_solref_write(geom_ids=None, *, term_name)[source]

Bind entity-local geom_solref columns and immutable defaults.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_solref_to_sim(values, geom_ids=None, env_ids=None, *, term_name='geom_solref')[source]

Stage geom_solref values through the reset transaction.

Parameters:
Return type:

None

bind_geom_solimp_write(geom_ids=None, *, term_name)[source]

Bind entity-local geom_solimp columns and immutable defaults.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_solimp_to_sim(values, geom_ids=None, env_ids=None, *, term_name='geom_solimp')[source]

Stage geom_solimp values through the reset transaction.

Parameters:
Return type:

None

bind_joint_damping_write(joint_ids=None, *, term_name)[source]

Bind entity-local joint_damping columns and immutable defaults.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_joint_damping_to_sim(values, joint_ids=None, env_ids=None, *, term_name='joint_damping')[source]

Stage joint_damping values through the reset transaction.

Parameters:
Return type:

None

bind_joint_frictionloss_write(joint_ids=None, *, term_name)[source]

Bind entity-local joint_frictionloss columns and immutable defaults.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_joint_frictionloss_to_sim(values, joint_ids=None, env_ids=None, *, term_name='joint_frictionloss')[source]

Stage joint_frictionloss values through the reset transaction.

Parameters:
Return type:

None

bind_mocap_pose_write(body_name, *, term_name)[source]

Bind an explicitly named mocap body, independently of the floating root.

Parameters:

  • body_name (str)

  • term_name (str)

Return type:

ndarray

read_mocap_pose()[source]

Read full-batch mocap poses, including pending reset writes.

Return type:

ndarray

write_mocap_pose_to_sim(poses, env_ids=None, *, term_name='mocap_pose')[source]

Stage poses to commit after the ordinary reset state upload.

Parameters:
Return type:

None

bind_joint_armature_write(joint_ids=None, *, term_name)[source]

Bind entity-local joints and immutable default DOF armatures.

Parameters:
Return type:

tuple[Tensor, Tensor]

write_joint_armature_to_sim(values, joint_ids=None, env_ids=None, *, term_name='joint_armature')[source]

Stage selected entity joint armatures in the active reset transaction.

Parameters:
Return type:

None

bind_geom_friction_write(geom_ids=None, *, term_name)[source]

Bind entity-local geoms and immutable default friction vectors.

Parameters:
Return type:

tuple[Tensor, Tensor]

write_geom_friction_to_sim(values, geom_ids=None, env_ids=None, *, term_name='geom_friction')[source]

Stage selected entity geom friction in the active reset transaction.

Parameters:
Return type:

None

bind_body_mass_write(body_ids=None, *, term_name)[source]

Bind entity-local body columns and immutable default masses.

Parameters:
Return type:

tuple[ndarray, Tensor]

write_body_mass_to_sim(values, body_ids=None, env_ids=None, *, term_name='randomize_rigid_body_mass')[source]

Stage selected entity body masses in the active reset transaction.

Parameters:
Return type:

None

record_startup_body_mass_to_sim(values, body_ids=None, env_ids=None, *, term_name='randomize_rigid_body_mass')[source]

Stage a startup body-mass write and promote its committed baseline.

Parameters:
Return type:

None

bind_body_ipos_write(body_ids=None, *, term_name)[source]

Bind entity-local body columns and immutable inertial positions.

Parameters:
Return type:

tuple[ndarray, Tensor]

write_body_ipos_to_sim(values, body_ids=None, env_ids=None, *, term_name='randomize_rigid_body_com')[source]

Stage selected entity body inertial positions in the reset transaction.

Parameters:
Return type:

None

record_startup_body_ipos_to_sim(values, body_ids=None, env_ids=None, *, term_name='randomize_rigid_body_com')[source]

Stage a startup body-CoM write and promote its committed baseline.

Parameters:
Return type:

None

bind_body_inertia_write(body_ids=None, *, term_name)[source]

Bind entity-local body columns and authoritative default inertias.

The backend returns either canonical or per-environment default rows; entity-local columns are selected without compiling a model in UniLab.

Parameters:
Return type:

tuple[ndarray, Tensor]

write_body_inertia_to_sim(values, body_ids=None, env_ids=None, *, term_name='randomize_body_mass_inertia')[source]

Stage selected entity body principal inertias in the reset transaction.

Parameters:
Return type:

None

bind_root_linear_velocity_delta(*, term_name)[source]

Validate the interval root-velocity capability on the cold path.

Parameters:

term_name (str)

Return type:

None

bind_root_angular_velocity_delta(*, term_name)[source]

Validate the interval root angular-velocity capability on the cold path.

Parameters:

term_name (str)

Return type:

None

apply_root_linear_velocity_delta_to_sim(values, env_ids=None, *, term_name='push_by_setting_velocity')[source]

Dispatch a cached root linear-velocity delta through the formal interval plan.

Parameters:
Return type:

None

apply_root_velocity_delta_to_sim(linear_delta, angular_delta, env_ids=None, *, term_name='push_by_setting_velocity')[source]

Dispatch world-frame root linear/angular velocity deltas in one interval plan.

Parameters:
Return type:

None

bind_body_wrench(body_ids=None, *, torque, term_name)[source]

Resolve entity-local and backend body columns for interval wrench writes.

Returns readonly (local_ids, backend_ids); local_ids index the entity’s declared body order and backend_ids are the columns accepted by apply_body_wrench_to_sim().

Parameters:
Return type:

tuple[Tensor, ndarray]

apply_body_wrench_to_sim(forces, torques, body_ids, env_ids=None, *, term_name)[source]

Dispatch world-frame body forces/torques through the formal interval plan.

body_ids are the immutable backend columns returned by bind_body_wrench(); forces/torques are world-frame rows for env_ids staged for the upcoming step.

Parameters:
Return type:

None

Stage world position and wxyz root orientation during reset.

Parameters:
Return type:

None

Stage world linear/angular root velocity during reset.

Parameters:
Return type:

None

read_reset_root_pose(env_ids=None)[source]

Read the world position and wxyz root orientation staged in the reset.

Returns a detached (len(env_ids), 7) copy of the pose currently staged in the active reset transaction (backend default for rows no term has written yet), so a later reset term can build on an earlier term’s root placement.

Parameters:

env_ids (Tensor | slice | None)

Return type:

ndarray

write_joint_state_to_sim(position, velocity, joint_ids=None, env_ids=None)[source]

Stage community-style joint state writes in the active reset transaction.

Parameters:
Return type:

None

write_joint_state_to_sim_mask(position, velocity, reset_mask, joint_ids=None)[source]

Stage full-width joint values for the active reset mask.

Parameters:
Return type:

None

find_bodies(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_geoms(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_sites(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_actuators(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_tendons(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_cameras(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_lights(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_materials(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_textures(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]

find_pairs(keys, preserve_order=False)[source]
Parameters:
Return type:

tuple[list[int], list[str]]