embodichain.lab.sim.motion.execution

Fixed-cadence execution of timed joint trajectories in simulation.

Standalone playback retimes planner output onto a fixed command period while leaving the simulation physics period unchanged. The command period must be an integer multiple of physics_dt; position-plus-velocity targets are opt-in and velocities are recomputed on the executed grid.

JointTrajectoryPlaybackCfg	Fixed-cadence standalone simulation playback settings.
play_joint_trajectory	Play a timed joint path without changing the simulation physics period.
InitialStatePort	Restore and verify one candidate's complete initial state.
MeasuredExecutor	Plan-check and execute one prepared candidate.
EpisodeSink	Persist one accepted episode and return its final receipt.
FixedSceneInitialStatePort	Adapt fixed-scene restore/verify methods to InitialStatePort.
SingleSlotOutcome	Result of one coordinator-driven physical candidate attempt.
SingleSlotRunner	Drive one candidate through host restore, execution, and persistence.
MultiSlotRunner	Assign queued candidates to compatible slots around a single host runner.

class embodichain.lab.sim.motion.execution.JointTrajectoryPlaybackCfg

Fixed-cadence standalone simulation playback settings.

Parameters:

• control_dt (float | None) – Command period, or None for one physics period.

• joint_command_mode (Literal['position', 'position_velocity']) – Whether to write qpos alone or qpos and qvel.

• preserve_source_grid (bool) – Preserve already aligned samples and their source indices instead of resampling; required for source callbacks and holds.

Attributes:

control_dt	Command period, or None to use the simulation physics period.
joint_command_mode	Whether playback writes qpos alone or qpos and qvel targets.
preserve_source_grid	Execute already aligned samples and zero-time joins without resampling.

control_dt: float | None

Command period, or None to use the simulation physics period.

joint_command_mode: Literal['position', 'position_velocity']

Whether playback writes qpos alone or qpos and qvel targets.

preserve_source_grid: bool

Execute already aligned samples and zero-time joins without resampling.

embodichain.lab.sim.motion.execution.play_joint_trajectory(sim, robot, *, positions, dt, joint_ids, cfg=None, on_step=None, hold_durations=None)

Play a timed joint path without changing the simulation physics period.

Planner timing is first quantized to the configured fixed command period. Every command interval advances an integer number of unchanged physics substeps. Velocity targets use that executed grid and preserve each row’s initial/terminal rest and explicit holds.

Parameters:

• sim (SimulationManager) – Simulation manager in explicit-update mode.

• robot (Robot) – Robot receiving joint targets.

• positions (Tensor) – Source positions with shape (B, N, D).

• dt (Tensor) – Source arrival intervals with shape (B, N).

• joint_ids (Sequence[int]) – Full-robot joint columns addressed by positions.

• cfg (JointTrajectoryPlaybackCfg | None) – Playback settings. Defaults to position-only at physics_dt.

• on_step (Optional[Callable[[int, int], None]]) – Callback after each source command and its following interval.

• hold_durations (Optional[Mapping[int, float]]) – Explicit additional holds after source command indices, in seconds. Each hold must align with the physics period. Source-index callbacks and holds require cfg.preserve_source_grid=True.

Return type:

PlanResult

Returns:

Executed positions, velocities and arrival intervals, including holds. The final hold, when present, appears as a repeated terminal sample.

Expansion host integration

The single-slot runner coordinates injected restore, measured-execution, and persistence ports. Candidate identity, budgets, coverage, and receipts remain owned by embodichain.lab.sim.motion.expansion.ExpansionSession. MultiSlotRunner adds generic compatible-slot reservation and exact release around the existing runner; its current drain policy is synchronous FIFO.

class embodichain.lab.sim.motion.execution.InitialStatePort

Restore and verify one candidate’s complete initial state.

Methods:

__init__(*args, **kwargs)
restore(item, *[, slot_id])	Restore a candidate and return an opaque prepared binding.

__init__(*args, **kwargs)

restore(item, *, slot_id=None)

Restore a candidate and return an opaque prepared binding.

Return type:

object

class embodichain.lab.sim.motion.execution.MeasuredExecutor

Plan-check and execute one prepared candidate.

Methods:

__init__(*args, **kwargs)
execute(item, prepared, *, episode_id, ...)	Execute and report the first actual command through the callback.
validate_plan(item)	Return host-owned planning/path validation evidence.

__init__(*args, **kwargs)

execute(item, prepared, *, episode_id, commit_id, on_rollout_started, slot_id=None)

Execute and report the first actual command through the callback.

Return type:

ExpertEpisode

validate_plan(item)

Return host-owned planning/path validation evidence.

Return type:

ValidationResult

class embodichain.lab.sim.motion.execution.EpisodeSink

Persist one accepted episode and return its final receipt.

Methods:

__init__(*args, **kwargs)
submit(episode, *, submission_id)	Persist and confirm one episode synchronously or through a bounded sink.

__init__(*args, **kwargs)

submit(episode, *, submission_id)

Persist and confirm one episode synchronously or through a bounded sink.

Return type:

CommitReceipt

class embodichain.lab.sim.motion.execution.FixedSceneInitialStatePort

Adapt fixed-scene restore/verify methods to InitialStatePort.

Methods:

__init__(host)
restore(item)	Restore and verify the host-owned fixed initial state.

__init__(host)

restore(item)

Restore and verify the host-owned fixed initial state.

Return type:

object

class embodichain.lab.sim.motion.execution.SingleSlotOutcome

Result of one coordinator-driven physical candidate attempt.

Methods:

__init__(status[, candidate_id, receipt, ...])

__init__(status, candidate_id=None, receipt=None, reason=None, episode_id=None, commit_id=None, submission_id=None)

class embodichain.lab.sim.motion.execution.SingleSlotRunner

Drive one candidate through host restore, execution, and persistence.

Methods:

__init__(coordinator, restorer, executor, ...)
run_next(*[, slot_id])	Execute the next FIFO candidate, or report an empty queue.
run_until_empty(*[, max_attempts])	Consume the current bounded queue through the same single slot.

Attributes:

coordinator

Return the coordinator owned by this runner.

__init__(coordinator, restorer, executor, sink, *, episode_byte_budget, slot_id=None)

property coordinator: CandidateCoordinator

Return the coordinator owned by this runner.

run_next(*, slot_id=None)

Execute the next FIFO candidate, or report an empty queue.

Return type:

SingleSlotOutcome

run_until_empty(*, max_attempts=None)

Consume the current bounded queue through the same single slot.

Return type:

tuple[SingleSlotOutcome, ...]

class embodichain.lab.sim.motion.execution.MultiSlotRunner

Assign queued candidates to compatible slots around a single host runner.

The current implementation drains FIFO synchronously; the slot pool and exact reservation lifecycle are independent of that execution policy, so a host can replace the inner runner with a concurrent implementation later.

Methods:

__init__(runner, slot_pool)
run_next()	Reserve a compatible slot, run one candidate, and release it.
run_until_empty(*[, max_attempts])	Drain FIFO candidates while respecting the optional attempt bound.

Attributes:

slot_pool

Return the host-owned physical slot pool.

__init__(runner, slot_pool)

run_next()

Reserve a compatible slot, run one candidate, and release it.

Return type:

SingleSlotOutcome

run_until_empty(*, max_attempts=None)

Drain FIFO candidates while respecting the optional attempt bound.

Return type:

tuple[SingleSlotOutcome, ...]

property slot_pool: PhysicalSlotPool

Return the host-owned physical slot pool.