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

Hot-path NumPy state surface backed by cached backend IDs.

EntityScene

Read-only name-addressable collection of backend-bound entities.
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.

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_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 backend copy contract on the cold path.

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

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, ndarray, ndarray]

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

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[ndarray, ndarray]

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[ndarray, ndarray]

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, ndarray]

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

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

Bind entity-local body columns and immutable inertial positions.

Parameters:
Return type:

tuple[ndarray, ndarray]

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

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

Bind entity-local body columns and caller-compiled default inertias.

default / default_mass are the full backend-width inertial tables compiled from the scene model on the cold path; the transaction cross-validates default_mass against the backend’s authoritative body-mass table before trusting the inertia rows.

Parameters:
Return type:

tuple[ndarray, ndarray]

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 body-state views (e.g. data.body_link_quat_w) and backend_ids are the columns accepted by apply_body_wrench_to_sim().

Parameters:
Return type:

tuple[ndarray, 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 (ndarray | 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

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
__init__(root_body_name=None, joint_names=None, body_names=None, geom_names=None, site_names=None, actuator_names=None)
Parameters:
class unilab.base.entity.EntityData[source]

Bases: object

Hot-path NumPy state surface backed by cached backend IDs.

Parameters:
__init__(backend, *, root_body_ids, joint_pos_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, actuator_ids, actuator_ctrl_range, control_buffer, entity_name, backend_type, state_read_cache)[source]
Parameters:
property heading_w: ndarray

Root yaw in the world frame, derived from the backend quaternion view.

property projected_gravity_b: ndarray

Unit gravity vector projected into the root link frame.

property gravity_vec_w: ndarray

Read-only world-frame unit gravity vector for every environment.

property default_root_state: ndarray

Read-only 13-D community root state for every environment.

property joint_pos: ndarray
property joint_vel: ndarray
property joint_pos_biased: ndarray

Joint positions with the manager-owned encoder bias applied.

property default_joint_pos: ndarray

Read-only per-environment default joint positions.

property default_joint_vel: ndarray

Read-only zero default velocities from the UniLab reset contract.

property soft_joint_pos_limits: ndarray

Read-only joint position limits in the declared entity joint order.

property encoder_bias: ndarray

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

Row-scoped variant of body_link_pos_w for partial-reset rebuilds.

Parameters:

env_ids (ndarray)

Return type:

ndarray

Row-scoped variant of body_link_quat_w for partial-reset rebuilds.

Parameters:

env_ids (ndarray)

Return type:

ndarray

Row-scoped variant of body_link_lin_vel_w for partial-reset rebuilds.

Parameters:

env_ids (ndarray)

Return type:

ndarray

Row-scoped variant of body_link_ang_vel_w for partial-reset rebuilds.

Parameters:

env_ids (ndarray)

Return type:

ndarray

property actuator_ctrl_range: ndarray
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 NpEnv/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.

property env_origins: ndarray

Read-only per-environment origins; flat UniLab scenes default to zero.

reset_to_default(env_ids, *, term_name)[source]

Stage a full-scene default state in the active reset 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

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 BackendSensorView.read() while stepping, so the scene facade never exposes a backend model, data object, or native handle.

Parameters:

names (Sequence[str])

Return type:

BackendSensorView