unilab.base.entity

Base-owned NumPy scene/entity facade for manager terms.

The facade deliberately describes partitions of an already materialized UniLab scene. It is not a second scene composer: all name resolution and state reads go through the public SimBackend contract.

Classes

Entity

Logical entity with cached local-to-backend mappings.

EntityCfg

Declare one logical entity inside an existing backend scene.

EntityData

Backend host adapter plus Torch cold tables owned by the entity facade.

EntityScene

Read-only name-addressable collection of backend-bound entities.

EntityTensorBodyStateView

Entity-ordered world-frame Torch body state for one read phase.

EntityTensorSensorViews

Validated named tensor sensors in the declared request order.

EntityTensorStateView

Entity-scoped Torch qpos/qvel-derived joint state for one read phase.

SceneTensorReadPlan

Phase-scoped packed tensor reads for one EntityScene.

SceneTensorReadSpec

Declare one entity's named state reads for the scene tensor phase.
class unilab.base.entity.Entity[source]

Bases: object

Logical entity with cached local-to-backend mappings.

Parameters:
__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]]

class unilab.base.entity.EntityCfg[source]

Bases: object

Declare one logical entity inside an existing backend scene.

Names are explicit because UniLab keeps scene composition in task-owned XML and backend adapters. None means that the namespace is not exposed by this entity; an empty sequence means that it is exposed but contains no elements.

Parameters:
root_body_name: str | None = None
joint_names: tuple[str, ...] | list[str] | None = None
body_names: tuple[str, ...] | list[str] | None = None
geom_names: tuple[str, ...] | list[str] | None = None
site_names: tuple[str, ...] | list[str] | None = None
actuator_names: tuple[str, ...] | list[str] | None = None
physical_entity: str | None = None
__init__(root_body_name=None, joint_names=None, body_names=None, geom_names=None, site_names=None, actuator_names=None, physical_entity=None)
Parameters:
class unilab.base.entity.EntityData[source]

Bases: object

Backend host adapter plus Torch cold tables owned by the entity facade.

The remaining host getters and default arrays are explicit adapter internals; Manager runtime reads use packed Torch views or cached tensor tables. Control writes publish into the same actuator layout without touching backend-private state.

Parameters:
__init__(backend, *, root_body_ids, joint_pos_ids, joint_qpos_ids, joint_vel_ids, default_root_state, default_root_state_error, default_joint_pos, default_joint_vel, soft_joint_pos_limits, gravity_vec_w, body_ids, root_body_name, body_names, actuator_ids, actuator_ctrl_range, control_buffer, entity_name, backend_type, state_read_cache)[source]
Parameters:
gravity_vec_w(device)[source]

Return the immutable world-frame gravity vector as a cached tensor table.

Parameters:

device (str | device)

Return type:

Tensor

default_root_state(device)[source]

Return the immutable default root state as a cached tensor table.

Parameters:

device (str | device)

Return type:

Tensor

default_joint_pos(device)[source]

Return the cold-path default joint positions as a cached tensor.

Parameters:

device (str | device)

Return type:

Tensor

default_joint_vel(device)[source]

Return the cold-path default joint velocities as a cached tensor.

Parameters:

device (str | device)

Return type:

Tensor

soft_joint_pos_limits(device)[source]

Return the cold-path joint position limits as a cached tensor.

Parameters:

device (str | device)

Return type:

Tensor

property encoder_bias: ndarray

Mutable per-environment joint encoder bias used by position actions.

property encoder_bias_tensor: Tensor

Return the mutable encoder bias as a same-storage Torch view.

set_encoder_bias_tensor(values)[source]

Publish a device-resident encoder-bias transaction.

The tensor becomes the authoritative same-storage carrier. This is an explicit public tensor boundary for DEVICE_RESIDENT owners; CPU/HOST bridge owners retain the existing NumPy carrier.

Parameters:

values (Tensor)

Return type:

None

update_encoder_bias_tensor_mask(reset_mask, columns, values)[source]

Merge full-width authoritative encoder-bias values by mask.

Parameters:
Return type:

None

property control_buffer: ndarray | Tensor | None

Return the authoritative actuator control buffer without copying.

write_ctrl(values, env_ids=None, *, actuator_ids=None)[source]

Write entity-local actuator controls into the env-owned control buffer.

This is an in-memory scene write, analogous to the pinned manager runtime’s entity target buffers. Physics remains owned by TorchEnv/SimBackend; this method never steps or calls a backend-private API.

Parameters:
Return type:

None

class unilab.base.entity.EntityScene[source]

Bases: Mapping[str, Entity]

Read-only name-addressable collection of backend-bound entities.

Parameters:
__init__(entities, backend, control_buffer=None, *, reset_state=None, default_qpos=None)[source]
Parameters:
classmethod from_scene_cfg(cfg, backend, control_buffer=None, *, reset_state=None, default_qpos=None)[source]
Parameters:
Return type:

EntityScene

property entities: Mapping[str, Entity]

Pinned community-style read-only entity mapping.

env_origins(device)[source]

Return immutable per-environment origins as a cached tensor table.

Parameters:

device (str | device)

Return type:

Tensor

compile_tensor_reads(device, specs)[source]

Compile the scene’s only packed tensor read layout for one device.

HOST_BRIDGE execution aggregates every entity’s sensors and canonical body views into one public TensorIOSpec, so a read phase performs one H2D transfer. DEVICE_RESIDENT execution keeps stable backend views but exposes the same phase API; manager terms therefore do not branch on the backend topology.

Parameters:
Return type:

SceneTensorReadPlan

reset_to_default(reset_mask, *, term_name)[source]

Stage a full-scene default state in the active mask transaction.

Parameters:
Return type:

None

bind_gravity_write(*, term_name)[source]

Bind immutable backend gravity for a reset event on the cold path.

Parameters:

term_name (str)

Return type:

ndarray

bind_gravity_write_tensor(*, term_name, device)[source]

Bind immutable backend gravity as a tensor table for tensor events.

Parameters:
Return type:

Tensor

write_gravity_to_sim(values, env_ids, *, term_name)[source]

Stage gravity values in the exactly-once reset transaction.

Parameters:
Return type:

None

bind_sensor_data(names)[source]

Bind existing backend sensors for a manager term on the cold path.

The returned view owns the backend-specific reader. Terms retain that view and only call SensorView.read() while stepping, so the scene facade never exposes a backend model, data object, or native handle.

Parameters:

names (Sequence[str])

Return type:

SensorView

class unilab.base.entity.EntityTensorBodyStateView[source]

Bases: object

Entity-ordered world-frame Torch body state for one read phase.

Parameters:
body_names: tuple[str, ...]
pos_w: Tensor
quat_w: Tensor
lin_vel_w: Tensor
ang_vel_w: Tensor
__init__(body_names, pos_w, quat_w, lin_vel_w, ang_vel_w)
Parameters:
class unilab.base.entity.EntityTensorSensorViews[source]

Bases: object

Validated named tensor sensors in the declared request order.

Parameters:
names: tuple[str, ...]
values: Mapping[str, Tensor]
__init__(names, values)
Parameters:
class unilab.base.entity.EntityTensorStateView[source]

Bases: object

Entity-scoped Torch qpos/qvel-derived joint state for one read phase.

Parameters:
joint_pos: Tensor
joint_vel: Tensor
__init__(joint_pos, joint_vel)
Parameters:
class unilab.base.entity.SceneTensorReadPlan[source]

Bases: object

Phase-scoped packed tensor reads for one EntityScene.

The plan is the Manager read boundary. A phase calls refresh() (or refresh_selected() after a mask reset) once and then slices entity views from the resulting packet. Host-bridge execution therefore performs one packed H2D transfer per read phase regardless of the number of terms, entities, sensors, or bodies.

Parameters:
__init__(*, scene, device, entities, sensor_names, body_names, host_plan)[source]
Parameters:
property scene: EntityScene
property device: device
property entities: Mapping[str, Entity]
property sensor_names: Mapping[str, tuple[str, ...]]
property body_names: Mapping[str, tuple[str, ...]]
property host_plan: HostBridgeTransferPlan | None
property ready: bool

Return whether the current packet is available to phase readers.

property packet_names: tuple[str, ...]

Return the immutable backend sensor names compiled into this plan.

refresh()[source]

Publish one full-batch packet for the current read phase.

Return type:

None

refresh_selected()[source]

Publish the post-selected-reset packet for the current read phase.

Host bridges use the backend’s selected-row boundary so reset rebuild does not trigger a second full read. Device-resident backends refresh their stable public views through the same normal read path.

Return type:

None

invalidate()[source]

Drop phase values after an in-phase simulation mutation.

Return type:

None

joint_tensor_view(entity)[source]

Return one entity’s validated joint state from the phase packet.

Parameters:

entity (str | Entity)

Return type:

EntityTensorStateView

sensor_tensor_views(entity, names)[source]

Return explicit named sensors from the phase packet.

Parameters:
Return type:

EntityTensorSensorViews

body_tensor_view(entity, body_names=None)[source]

Return entity-local body state from canonical phase sensors.

Parameters:
Return type:

EntityTensorBodyStateView

property transfer_stats: dict[str, int]
property last_timing: dict[str, float]
close()[source]

Release the backend-owned packed read plan.

Return type:

None

class unilab.base.entity.SceneTensorReadSpec[source]

Bases: object

Declare one entity’s named state reads for the scene tensor phase.

sensor_names are explicit backend names. body_names are entity-local names; the scene owner expands them into the canonical track_* sensor contract. Requests are explicit so the packed packet never grows from an implicit EntityCfg namespace that is only needed by a cold-path consumer.

Parameters:
entity: str
sensor_names: tuple[str, ...] = ()
body_names: tuple[str, ...] = ()
__init__(entity, sensor_names=(), body_names=())
Parameters: