unilab.base.reset_state

Base-owned reset-state transaction for Manager-Based event terms.

The transaction composes every reset-mode state and model-field write inside the backend-owned packed transaction (SimBackend.bind_packed_reset → unisim.backend.packed_reset.PackedResetTransaction) and commits through that composer exactly once per lifecycle. It deliberately knows nothing about task configuration, IPC, runners, or backend-private state.

Classes

ResetStateTransaction

Reusable, fail-closed transaction for reset-mode state mutation.
class unilab.base.reset_state.ResetStateTransaction[source]

Bases: object

Reusable, fail-closed transaction for reset-mode state mutation.

Parameters:
__init__(backend, *, default_qpos=None, scene_layout=None)[source]
Parameters:
property active: bool

Whether a reset lifecycle currently owns the transaction.

property tensor_active: bool

Whether the active reset composes device tensor rows without host staging.

property last_commit_had_writes: bool

Whether the most recent scoped commit submitted rows to the backend.

property last_set_state_timing_ms: dict[str, float]

Sub-timings from the most recent commit’s set_state call.

Always includes dr_reset_set_state_ms (outer wall-clock around the backend call); backend-reported set_state_*_ms and packed-composer packed_reset_*_ms sub-keys are merged in when present. Empty when the last commit had no staged writes.

scoped_startup(env_ids)[source]

Begin the all-row startup transaction and commit after all terms succeed.

Parameters:

env_ids (Tensor)

Return type:

Iterator[ResetStateTransaction]

declare_packed_reset_device(device)[source]

Declare the packed reset device and fail closed without the capability.

Parameters:

device (device)

Return type:

None

scoped_device_event_tensor(reset_mask)[source]

Begin a fixed-width owner reset and commit it.

Parameters:

reset_mask (Tensor)

Return type:

Iterator[ResetStateTransaction]

scoped_device_owner_tensor(reset_mask)[source]

Begin a full-width step-owner tensor transaction.

Parameters:

reset_mask (Tensor)

Return type:

Iterator[ResetStateTransaction]

begin(env_ids)[source]

Open a transaction for the concrete reset environment IDs.

Parameters:

env_ids (Tensor)

Return type:

None

begin_tensor(reset_mask, *, owner_subset=False)[source]

Open a fixed-width packed reset transaction selected by a bool mask.

Parameters:
Return type:

None

write_entity_state(entity, env_ids, *, term_name, root_pose=None, root_velocity=None, joint_positions=None, joint_velocities=None, joint_names=())[source]

Stage one public physical-entity patch in the current manager transaction.

Parameters:
Return type:

None

read_entity_root_pose(entity, env_ids)[source]

Read staged root pose or a detached current public snapshot.

Parameters:
Return type:

ndarray

bind_geom_size_write(column_ids, *, term_name)[source]

Bind immutable geom_size defaults through the declared backend capability.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_size(env_ids, column_ids, values, *, term_name)[source]

Stage selected geom_size values in the active reset.

Parameters:
Return type:

None

bind_geom_solref_write(column_ids, *, term_name)[source]

Bind immutable geom_solref defaults through the declared backend capability.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_solref(env_ids, column_ids, values, *, term_name)[source]

Stage selected geom_solref values in the active reset.

Parameters:
Return type:

None

bind_geom_solimp_write(column_ids, *, term_name)[source]

Bind immutable geom_solimp defaults through the declared backend capability.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_geom_solimp(env_ids, column_ids, values, *, term_name)[source]

Stage selected geom_solimp values in the active reset.

Parameters:
Return type:

None

bind_dof_damping_write(column_ids, *, term_name)[source]

Bind immutable dof_damping defaults through the declared backend capability.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_dof_damping(env_ids, column_ids, values, *, term_name)[source]

Stage selected dof_damping values in the active reset.

Parameters:
Return type:

None

bind_dof_frictionloss_write(column_ids, *, term_name)[source]

Bind immutable dof_frictionloss defaults through the declared backend capability.

Parameters:
Return type:

tuple[ndarray, ndarray]

write_dof_frictionloss(env_ids, column_ids, values, *, term_name)[source]

Stage selected dof_frictionloss values in the active reset.

Parameters:
Return type:

None

bind_body_mass_write(body_ids, *, term_name)[source]

Bind body-mass columns and immutable backend defaults on the cold path.

Parameters:
Return type:

tuple[ndarray, Tensor]

bind_body_ipos_write(body_ids, *, term_name)[source]

Bind body inertial-position columns and immutable backend defaults.

Parameters:
Return type:

tuple[ndarray, Tensor]

bind_body_inertia_write(body_ids, *, term_name)[source]

Bind body-inertia columns and authoritative backend defaults.

UniSim returns either a canonical (nbody, 3) table or a per-world (num_envs, nbody, 3) table. No caller-side model compilation or body-order cross-check is needed.

Parameters:
Return type:

tuple[ndarray, Tensor]

bind_gravity_write(*, term_name)[source]

Bind the immutable backend gravity vector on the cold path.

Parameters:

term_name (str)

Return type:

ndarray

bind_gravity_write_tensor(*, term_name, device)[source]

Bind the immutable backend gravity vector as a tensor table.

Parameters:
Return type:

Tensor

bind_dof_armature_write(dof_ids, *, term_name)[source]

Bind DOF-armature columns and immutable backend defaults.

Parameters:
Return type:

tuple[ndarray, Tensor]

bind_geom_friction_write(geom_ids, *, term_name)[source]

Bind geom-friction rows and immutable backend defaults.

Parameters:
Return type:

tuple[ndarray, Tensor]

write_body_mass(env_ids, body_ids, values, *, term_name)[source]

Stage selected body masses in the exactly-once reset payload.

Parameters:
Return type:

None

write_body_ipos(env_ids, body_ids, values, *, term_name)[source]

Stage selected body inertial positions in the reset payload.

Parameters:
Return type:

None

write_body_inertia(env_ids, body_ids, values, *, term_name)[source]

Stage selected body principal-inertia diagonals in the reset payload.

Parameters:
Return type:

None

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

Stage per-environment gravity vectors in the reset payload.

Parameters:
Return type:

None

write_dof_armature(env_ids, dof_ids, values, *, term_name)[source]

Stage selected DOF armatures in the reset payload.

Parameters:
Return type:

None

write_geom_friction(env_ids, geom_ids, values, *, term_name)[source]

Stage selected three-axis geom friction in the reset payload.

Parameters:
Return type:

None

bind_actuator_gain_write(actuator_ids, *, term_name)[source]

Resolve gain mutation capability and immutable defaults on the cold path.

Parameters:
Return type:

tuple[ndarray, Tensor, Tensor]

write_actuator_gains(env_ids, actuator_ids, kp, kd, *, term_name)[source]

Stage selected per-environment actuator gains in the reset transaction.

Parameters:
Return type:

None

write_randomization_tensor_mask(field, reset_mask, columns, values, *, term_name)[source]

Stage a packed transaction’s full-width final DR table by mask.

Parameters:
Return type:

None

reset_to_default(reset_mask, *, term_name)[source]

Stage backend default qpos/qvel for the active full-width mask.

Parameters:
Return type:

None

write_joint_state(env_ids, qpos_indices, qvel_indices, position, velocity, *, term_name)[source]

Stage selected joint position and velocity columns in the reset batch.

Parameters:
Return type:

None

write_joint_state_mask(reset_mask, qpos_indices, qvel_indices, position, velocity, *, term_name)[source]

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

Parameters:
Return type:

None

write_root_state(env_ids, layout, root_state, *, term_name)[source]

Stage a community 13-D world-frame root state.

Parameters:

  • env_ids (Tensor)

  • layout (RootStateLayout)

  • root_state (Tensor)

  • term_name (str)

Return type:

None

write_root_state_tensor(reset_mask, layout, root_state, *, term_name)[source]

Stage a full-width root-state payload selected by a bool mask.

Parameters:

  • reset_mask (Tensor)

  • layout (RootStateLayout)

  • root_state (Tensor)

  • term_name (str)

Return type:

None

write_motion_state_tensor(reset_mask, layout, qpos_indices, qvel_indices, root_state, joint_position, joint_velocity, *, term_name)[source]

Stage one full-width motion root and joint payload by bool mask.

Parameters:
Return type:

None

write_root_pose(env_ids, layout, pose, *, term_name)[source]

Stage world position and wxyz orientation for one floating root.

Parameters:
Return type:

None

write_root_velocity(env_ids, layout, velocity_w, *, term_name)[source]

Stage world-frame root velocity in generalized qvel columns.

The public generalized-state contract stores free-root linear velocity in world coordinates and angular velocity in root-body coordinates. The conversion uses the pose already staged in this transaction.

Parameters:

  • env_ids (Tensor)

  • layout (RootStateLayout)

  • velocity_w (Tensor)

  • term_name (str)

Return type:

None

read_root_pose(env_ids, layout, *, term_name)[source]

Read the world position and wxyz orientation staged for one floating root.

Returns a detached (len(env_ids), 7) copy of the pose currently staged in this transaction. Rows no term has written yet hold the backend default pose, so a later reset term can build on an earlier term’s root placement without re-deriving it.

Parameters:

  • env_ids (Tensor)

  • layout (RootStateLayout)

  • term_name (str)

Return type:

ndarray

bind_mocap_pose(body_name)[source]

Resolve a mocap body once, without exposing a native backend handle.

Parameters:

body_name (str)

Return type:

MocapPoseBinding

read_mocap_pose(body_name)[source]

Read current poses with this transaction’s pending rows overlaid.

Parameters:

body_name (str)

Return type:

ndarray

write_mocap_pose(body_name, env_ids, poses, *, term_name)[source]

Stage poses; upload only after the ordinary reset state has committed.

Parameters:
Return type:

None

commit()[source]

Commit all staged rows through the packed composer boundary.

Return type:

dict | None

commit_tensor()[source]

Commit the fixed-width reset through the packed composer boundary.

Return type:

dict | None

abort()[source]

Discard staged rows without touching the backend.

Return type:

None

record_startup_randomization(field, env_ids, column_ids, values, *, term_name)[source]

Re-stage full-width startup rows so the commit promotes the baseline.

The backend remains authoritative for committed state. The packed composer promotes every staged field’s committed rows into its reset baseline when the public backend commit succeeds, so a later mask reset rebuilds unwritten model columns from the startup values instead of the immutable construction defaults. The promotion is deferred until the commit succeeds, preserving the reset transaction’s all-or-nothing contract.

Parameters:
Return type:

None