unilab.base.reset_state.ResetStateTransaction

class unilab.base.reset_state.ResetStateTransaction[source]

Bases: object

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

Parameters:

Methods

__init__(backend, *[, default_qpos, ...])

abort()

Discard staged rows without touching the backend.

begin(env_ids)

Open a transaction for the concrete reset environment IDs.

begin_tensor(reset_mask, *[, owner_subset])

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

bind_actuator_gain_write(actuator_ids, *, ...)

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

bind_body_inertia_write(body_ids, *, term_name)

Bind body-inertia columns and authoritative backend defaults.

bind_body_ipos_write(body_ids, *, term_name)

Bind body inertial-position columns and immutable backend defaults.

bind_body_mass_write(body_ids, *, term_name)

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

bind_dof_armature_write(dof_ids, *, term_name)

Bind DOF-armature columns and immutable backend defaults.

bind_dof_damping_write(column_ids, *, term_name)

Bind immutable dof_damping defaults through the declared backend capability.

bind_dof_frictionloss_write(column_ids, *, ...)

Bind immutable dof_frictionloss defaults through the declared backend capability.

bind_geom_friction_write(geom_ids, *, term_name)

Bind geom-friction rows and immutable backend defaults.

bind_geom_size_write(column_ids, *, term_name)

Bind immutable geom_size defaults through the declared backend capability.

bind_geom_solimp_write(column_ids, *, term_name)

Bind immutable geom_solimp defaults through the declared backend capability.

bind_geom_solref_write(column_ids, *, term_name)

Bind immutable geom_solref defaults through the declared backend capability.

bind_gravity_write(*, term_name)

Bind the immutable backend gravity vector on the cold path.

bind_gravity_write_tensor(*, term_name, device)

Bind the immutable backend gravity vector as a tensor table.

bind_mocap_pose(body_name)

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

commit()

Commit all staged rows through the packed composer boundary.

commit_tensor()

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

declare_packed_reset_device(device)

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

read_entity_root_pose(entity, env_ids)

Read staged root pose or a detached current public snapshot.

read_mocap_pose(body_name)

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

read_root_pose(env_ids, layout, *, term_name)

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

record_startup_randomization(field, env_ids, ...)

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

reset_to_default(reset_mask, *, term_name)

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

scoped_device_event_tensor(reset_mask)

Begin a fixed-width owner reset and commit it.

scoped_device_owner_tensor(reset_mask)

Begin a full-width step-owner tensor transaction.

scoped_startup(env_ids)

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

write_actuator_gains(env_ids, actuator_ids, ...)

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

write_body_inertia(env_ids, body_ids, ...)

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

write_body_ipos(env_ids, body_ids, values, ...)

Stage selected body inertial positions in the reset payload.

write_body_mass(env_ids, body_ids, values, ...)

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

write_dof_armature(env_ids, dof_ids, values, ...)

Stage selected DOF armatures in the reset payload.

write_dof_damping(env_ids, column_ids, ...)

Stage selected dof_damping values in the active reset.

write_dof_frictionloss(env_ids, column_ids, ...)

Stage selected dof_frictionloss values in the active reset.

write_entity_state(entity, env_ids, *, term_name)

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

write_geom_friction(env_ids, geom_ids, ...)

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

write_geom_size(env_ids, column_ids, values, ...)

Stage selected geom_size values in the active reset.

write_geom_solimp(env_ids, column_ids, ...)

Stage selected geom_solimp values in the active reset.

write_geom_solref(env_ids, column_ids, ...)

Stage selected geom_solref values in the active reset.

write_gravity(env_ids, values, *, term_name)

Stage per-environment gravity vectors in the reset payload.

write_joint_state(env_ids, qpos_indices, ...)

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

write_joint_state_mask(reset_mask, ...)

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

write_mocap_pose(body_name, env_ids, poses, ...)

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

write_motion_state_tensor(reset_mask, ...)

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

write_randomization_tensor_mask(field, ...)

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

write_root_pose(env_ids, layout, pose, *, ...)

Stage world position and wxyz orientation for one floating root.

write_root_state(env_ids, layout, ...)

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

write_root_state_tensor(reset_mask, layout, ...)

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

write_root_velocity(env_ids, layout, ...)

Stage world-frame root velocity in generalized qvel columns.

Attributes

active

Whether a reset lifecycle currently owns the transaction.

last_commit_had_writes

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

last_set_state_timing_ms

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

tensor_active

Whether the active reset composes device tensor rows without host staging.
__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