embodichain.lab.sim.atomic_actions

embodichain.lab.sim.atomic_actions#

Atomic action abstraction layer for embodied AI motion generation.

This module provides a unified interface for the atomic motion primitives (move_end_effector, move_joints, pick_up, move_held_object, place, press, coordinated_pickment, coordinated_placement), with typed targets, a WorldState threaded across sequenced actions, and extensible custom action registration.

Classes

`Affordance`	Base class for affordance data.
`AntipodalAffordance`	Antipodal grasp affordance for parallel-jaw grippers.
`InteractionPoints`	Batch of 3D interaction points on an object surface.
`ObjectSemantics`	Semantic information about an interaction target.
`EndEffectorPoseTarget`	End-effector pose target.
`JointPositionTarget`	Joint-space target for a configured robot control part.
`NamedJointPositionTarget`	Named joint-space target resolved from `MoveJointsCfg`.
`GraspTarget`	Pickup target with an affordance-selected or explicitly supplied grasp pose.
`HeldObjectPoseTarget`	Move the currently-held object to a desired object pose.
`CoordinatedPickmentTarget`	Object-centric target for picking and moving one object with two hands.
`CoordinatedPlacementTarget`	Object-centric target for dual-arm coordinated placement.
`Target`	Represent a PEP 604 union type
`HeldObjectState`	State of an object currently held by the robot.
`CoordinatedHeldObjectState`	State of a single object jointly held by two robot hands.
`WorldState`	State the engine threads through a sequence of actions.
`ActionResult`	Return value of every AtomicAction.execute call.
`ActionCfg`	Configuration shared by all atomic actions.
`AtomicAction`	Abstract base for atomic actions.
`TrajectoryBuilder`	Stateless trajectory utilities shared by every atomic action.
`MoveEndEffectorCfg`	MoveEndEffectorCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>)
`MoveEndEffector`	Plan a free-space end-effector move to a target pose.
`MoveJointsCfg`	MoveJointsCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>, named_joint_positions: 'dict[str, torch.Tensor] \| None' = <factory>)
`MoveJoints`	Plan a joint-space move for the configured control part.
`PickUpCfg`	PickUpCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>, hand_interp_steps: 'int' = <factory>, hand_control_part: 'str' = <factory>, hand_open_qpos: 'torch.Tensor \| None' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>, lift_height: 'float' = <factory>, pre_grasp_distance: 'float' = <factory>, approach_direction: 'torch.Tensor' = <factory>, approach_alignment_max_angle: 'float \| None' = <factory>, downstream_object_target_poses: 'tuple[torch.Tensor, ...]' = <factory>, obj_upright_direction: 'torch.Tensor \| None' = <factory>, rotate_upright: 'float \| None' = <factory>)
`PickUp`	Approach a grasp pose, close the gripper, lift.
`MoveHeldObjectCfg`	MoveHeldObjectCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>, hand_control_part: 'str' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>, obj_upright_direction: 'torch.Tensor \| None' = <factory>, pick_rotate_upright: 'float \| None' = <factory>)
`MoveHeldObject`	Move the held object to a target object pose; keep the gripper closed.
`PlaceCfg`	PlaceCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>, hand_interp_steps: 'int' = <factory>, hand_control_part: 'str' = <factory>, hand_open_qpos: 'torch.Tensor \| None' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>, lift_height: 'float' = <factory>, max_approach_retract_z: 'float \| None' = <factory>, cartesian_waypoint_count: 'int' = <factory>)
`Place`	Lower the held object to a place pose, open the gripper, retract.
`PressCfg`	PressCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, sample_interval: 'int' = <factory>, hand_interp_steps: 'int' = <factory>, hand_control_part: 'str' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>)
`Press`	Close the gripper, press down to a target pose, then return.
`CoordinatedPickmentCfg`	CoordinatedPickmentCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, left_arm_control_part: 'str' = <factory>, right_arm_control_part: 'str' = <factory>, left_hand_control_part: 'str' = <factory>, right_hand_control_part: 'str' = <factory>, left_hand_open_qpos: 'torch.Tensor \| None' = <factory>, left_hand_close_qpos: 'torch.Tensor \| None' = <factory>, right_hand_open_qpos: 'torch.Tensor \| None' = <factory>, right_hand_close_qpos: 'torch.Tensor \| None' = <factory>, object_motion_keyframes: 'int' = <factory>, pre_grasp_distance: 'float' = <factory>, lift_height: 'float' = <factory>, sample_interval: 'int' = <factory>, hand_interp_steps: 'int' = <factory>, hold_steps: 'int' = <factory>)
`CoordinatedPickment`	Pick and move a single object pinched by two hands.
`CoordinatedPlacementCfg`	CoordinatedPlacementCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'float \| None' = <factory>, acceleration_limit: 'float \| None' = <factory>, motion_source: 'str' = <factory>, planner_type: 'str \| None' = <factory>, placing_arm_control_part: 'str' = <factory>, support_arm_control_part: 'str' = <factory>, placing_hand_control_part: 'str' = <factory>, support_hand_control_part: 'str' = <factory>, placing_hand_open_qpos: 'torch.Tensor \| None' = <factory>, placing_hand_close_qpos: 'torch.Tensor \| None' = <factory>, support_hand_close_qpos: 'torch.Tensor \| None' = <factory>, release: 'bool' = <factory>, placing_height_offset: 'float' = <factory>, support_height_offset: 'float' = <factory>, lift_height: 'float' = <factory>, sample_interval: 'int' = <factory>, hand_interp_steps: 'int' = <factory>, hold_steps: 'int' = <factory>, retreat_steps: 'int' = <factory>)
`CoordinatedPlacement`	Coordinate two held objects: support object below, placing object above.
`AtomicActionEngine`	Sequences typed atomic actions while threading WorldState through them.

Layout#

The public API is exported from embodichain.lab.sim.atomic_actions. Built-in primitive implementations live under embodichain.lab.sim.atomic_actions.primitives and embodichain.lab.sim.atomic_actions.actions remains a compatibility re-export for existing imports.

Core#

class embodichain.lab.sim.atomic_actions.Affordance[source]#

Bases: object

Base class for affordance data.

Represents an object’s interaction possibilities. Subclasses carry whatever typed fields they need (mesh tensors, interaction points, etc.); the base class only carries an object label and a free-form custom_config dict.

Methods:

`__init__`([object_label, custom_config])
`get_batch_size`()	Return the batch size of this affordance data.
`get_custom_config`(key[, default])	Get a custom affordance configuration value.
`set_custom_config`(key, value)	Set a custom affordance configuration value.

Attributes:

`custom_config`	User-defined configuration payload.
`object_label`	Label of the object this affordance belongs to.

__init__(object_label='', custom_config=<factory>)#

custom_config: dict[str, Any]#: User-defined configuration payload.

get_batch_size()[source]#

Return the batch size of this affordance data.

Return type:: int

get_custom_config(key, default=None)[source]#

Get a custom affordance configuration value.

Return type:: Any

object_label: str = ''#: Label of the object this affordance belongs to.

set_custom_config(key, value)[source]#

Set a custom affordance configuration value.

Return type:: None

class embodichain.lab.sim.atomic_actions.AntipodalAffordance[source]#

Bases: Affordance

Antipodal grasp affordance for parallel-jaw grippers.

Methods:

__init__([object_label, custom_config, ...])

Attributes:

`force_reannotate`	If True, recompute the grasp annotation on each access.
`generator_cfg`	Optional grasp-generator configuration.
`gripper_collision_cfg`	Optional gripper-collision configuration.
`mesh_triangles`	Object mesh triangle indices, shape [M, 3].
`mesh_vertices`	Object mesh vertices, shape [N, 3].

__init__(object_label='', custom_config=<factory>, mesh_vertices=None, mesh_triangles=None, generator_cfg=None, gripper_collision_cfg=None, force_reannotate=False)#

custom_config: dict[str, Any]#: User-defined configuration payload.

force_reannotate: bool = False#: If True, recompute the grasp annotation on each access.

generator_cfg: GraspGeneratorCfg | None = None#: Optional grasp-generator configuration.

gripper_collision_cfg: GripperCollisionCfg | None = None#: Optional gripper-collision configuration.

mesh_triangles: Tensor | None = None#: Object mesh triangle indices, shape [M, 3].

mesh_vertices: Tensor | None = None#: Object mesh vertices, shape [N, 3].

class embodichain.lab.sim.atomic_actions.InteractionPoints[source]#

Bases: Affordance

Batch of 3D interaction points on an object surface.

Methods:

`__init__`([object_label, custom_config, ...])
`get_approach_direction`(point_idx)	Get recommended approach direction for a given point.
`get_batch_size`()	Return the number of interaction points in this affordance.
`get_points_by_type`(point_type)	Get points by their interaction type.

Attributes:

`normals`	Optional surface normals at each interaction point with shape [B, 3].
`point_types`	Optional labels for each point's interaction type.
`points`	Batch of 3D interaction points with shape [B, 3].

__init__(object_label='', custom_config=<factory>, points=<factory>, normals=None, point_types=<factory>)#

custom_config: dict[str, Any]#: User-defined configuration payload.

get_approach_direction(point_idx)[source]#

Get recommended approach direction for a given point.

Return type:: Tensor

get_batch_size()[source]#

Return the number of interaction points in this affordance.

Return type:: int

get_points_by_type(point_type)[source]#

Get points by their interaction type.

Return type:: Tensor | None

normals: Tensor | None = None#: Optional surface normals at each interaction point with shape [B, 3].

point_types: list[str]#: Optional labels for each point’s interaction type.

points: Tensor#: Batch of 3D interaction points with shape [B, 3].

class embodichain.lab.sim.atomic_actions.ObjectSemantics[source]#

Bases: object

Semantic information about an interaction target.

Methods:

__init__(affordance, geometry[, properties, ...])

Attributes:

`affordance`	Affordance data describing how the object can be interacted with.
`entity`	Optional reference to the simulation entity for this object.
`geometry`	Non-affordance geometric metadata (e.g., bounding_box).
`label`	Object category label (e.g., 'mug', 'apple').
`properties`	mass, friction, etc.

__init__(affordance, geometry, properties=<factory>, label='none', entity=None)#

affordance: Affordance#: Affordance data describing how the object can be interacted with.

entity: BatchEntity | None = None#: Optional reference to the simulation entity for this object.

geometry: dict[str, Any]#: Non-affordance geometric metadata (e.g., bounding_box). Mesh tensors live on AntipodalAffordance, not here.

label: str = 'none'#: Object category label (e.g., ‘mug’, ‘apple’).

properties: dict[str, Any]#

mass, friction, etc.

Type:: Physical properties

class embodichain.lab.sim.atomic_actions.EndEffectorPoseTarget[source]#

Bases: object

End-effector pose target. Used by MoveEndEffector, Place, and Press.

Methods:

__init__(xpos[, tcp_symmetry])

Attributes:

`tcp_symmetry`	Optional TCP-frame symmetry allowed by the target semantics.
`xpos`	Target end-effector homogeneous transform.

__init__(xpos, tcp_symmetry='none')#

tcp_symmetry: Literal['none', 'z_roll_180'] = 'none'#

Optional TCP-frame symmetry allowed by the target semantics.

"none" preserves the pose exactly. "z_roll_180" lets supporting actions choose between the pose and its TCP z-roll 180 equivalent, which flips TCP x/y while preserving TCP z and translation.

xpos: Tensor#

Target end-effector homogeneous transform.

Accepts:

(4, 4) or (n_envs, 4, 4) — a single waypoint.
(n_envs, n_waypoint, 4, 4) — a multi-waypoint trajectory; waypoints are visited in order. (Consumed as multi-waypoint by MoveEndEffector and Place.)

class embodichain.lab.sim.atomic_actions.JointPositionTarget[source]#

Bases: object

Joint-space target for a configured robot control part.

Methods:

__init__(qpos)

Attributes:

qpos

Target joint positions.

__init__(qpos)#

qpos: Tensor#

Target joint positions.

Accepts:

(control_dof,) or (n_envs, control_dof) — a single waypoint.
(n_envs, n_waypoint, control_dof) — a multi-waypoint trajectory; waypoints are visited in order.

class embodichain.lab.sim.atomic_actions.NamedJointPositionTarget[source]#

Bases: object

Named joint-space target resolved from MoveJointsCfg.

Methods:

__init__(name)

Attributes:

name

Name of a joint-position target in MoveJointsCfg.named_joint_positions.

__init__(name)#

name: str#: Name of a joint-position target in MoveJointsCfg.named_joint_positions.

class embodichain.lab.sim.atomic_actions.GraspTarget[source]#

Bases: object

Pickup target with an affordance-selected or explicitly supplied grasp pose.

Methods:

__init__(semantics[, grasp_xpos])

Attributes:

grasp_xpos

Optional end-effector grasp pose.

__init__(semantics, grasp_xpos=None)#

grasp_xpos: Tensor | None = None#

Optional end-effector grasp pose.

When omitted, PickUp selects a grasp from the target affordance. Supplying a pose with shape (4, 4) or (n_envs, 4, 4) skips grasp sampling, which is useful when perception or task geometry has already selected a grasp.

class embodichain.lab.sim.atomic_actions.HeldObjectPoseTarget[source]#

Bases: object

Move the currently-held object to a desired object pose.

Methods:

__init__(object_target_pose)

Attributes:

object_target_pose

(4, 4) or (n_envs, 4, 4) target pose for the held object.

__init__(object_target_pose)#

object_target_pose: Tensor#: (4, 4) or (n_envs, 4, 4) target pose for the held object.

class embodichain.lab.sim.atomic_actions.CoordinatedPickmentTarget[source]#

Bases: object

Object-centric target for picking and moving one object with two hands.

Methods:

__init__(object_target_pose, ...[, ...])

Attributes:

`left_object_to_eef`	Transform from object frame to left end-effector frame.
`object_initial_pose`	Optional initial object pose.
`object_semantics`	Semantic description of the shared object.
`object_target_pose`	Target pose for the shared object, shape `(4, 4)` or `(n_envs, 4, 4)`.
`right_object_to_eef`	Transform from object frame to right end-effector frame.

__init__(object_target_pose, object_semantics, left_object_to_eef, right_object_to_eef, object_initial_pose=None)#

left_object_to_eef: Tensor#: Transform from object frame to left end-effector frame.

object_initial_pose: Tensor | None = None#: Optional initial object pose. Defaults to object_semantics.entity pose.

object_semantics: ObjectSemantics#: Semantic description of the shared object.

object_target_pose: Tensor#: Target pose for the shared object, shape (4, 4) or (n_envs, 4, 4).

right_object_to_eef: Tensor#: Transform from object frame to right end-effector frame.

class embodichain.lab.sim.atomic_actions.CoordinatedPlacementTarget[source]#

Bases: object

Object-centric target for dual-arm coordinated placement.

Methods:

__init__(placing_object_target_pose, ...[, ...])

Attributes:

`placing_height_offset`	World-Z offset above the placing object target pose.
`placing_held_object`	Held-object state for the placing arm.
`placing_object_target_pose`	Target pose for the object released by the placing arm.
`release`	Whether the placing hand releases.
`support_height_offset`	World-Z offset above the support object target pose.
`support_held_object`	Held-object state for the support arm.
`support_object_target_pose`	Target pose for the object held by the support arm.

__init__(placing_object_target_pose, support_object_target_pose, placing_held_object, support_held_object, placing_height_offset=None, support_height_offset=None, release=None)#

placing_height_offset: float | None = None#: World-Z offset above the placing object target pose.

placing_held_object: HeldObjectState#: Held-object state for the placing arm.

placing_object_target_pose: Tensor#: Target pose for the object released by the placing arm.

release: bool | None = None#: Whether the placing hand releases. None uses the action config.

support_height_offset: float | None = None#: World-Z offset above the support object target pose.

support_held_object: HeldObjectState#: Held-object state for the support arm.

support_object_target_pose: Tensor#: Target pose for the object held by the support arm.

embodichain.lab.sim.atomic_actions.Target = embodichain.lab.sim.atomic_actions.core.EndEffectorPoseTarget | embodichain.lab.sim.atomic_actions.core.JointPositionTarget | embodichain.lab.sim.atomic_actions.core.NamedJointPositionTarget | embodichain.lab.sim.atomic_actions.core.GraspTarget | embodichain.lab.sim.atomic_actions.core.HeldObjectPoseTarget | embodichain.lab.sim.atomic_actions.core.CoordinatedPickmentTarget | embodichain.lab.sim.atomic_actions.core.CoordinatedPlacementTarget#

Represent a PEP 604 union type

E.g. for int | str

class embodichain.lab.sim.atomic_actions.HeldObjectState[source]#

Bases: object

State of an object currently held by the robot.

Methods:

__init__(semantics, object_to_eef, grasp_xpos)

Attributes:

`grasp_xpos`	Batched end-effector pose used to grasp the object, shape [n_envs, 4, 4].
`object_to_eef`	Batched transform from object frame to end-effector frame, shape [n_envs, 4, 4].
`semantics`	Semantics of the held object.

__init__(semantics, object_to_eef, grasp_xpos)#

grasp_xpos: Tensor#: Batched end-effector pose used to grasp the object, shape [n_envs, 4, 4].

object_to_eef: Tensor#: Batched transform from object frame to end-effector frame, shape [n_envs, 4, 4].

semantics: ObjectSemantics#: Semantics of the held object.

class embodichain.lab.sim.atomic_actions.CoordinatedHeldObjectState[source]#

Bases: object

State of a single object jointly held by two robot hands.

Methods:

__init__(semantics, left_object_to_eef, ...)

Attributes:

`left_grasp_xpos`	Left end-effector grasp pose for the shared object, shape `[n_envs, 4, 4]`.
`left_object_to_eef`	Transform from object frame to left end-effector frame, shape `[n_envs, 4, 4]`.
`right_grasp_xpos`	Right end-effector grasp pose for the shared object, shape `[n_envs, 4, 4]`.
`right_object_to_eef`	Transform from object frame to right end-effector frame, shape `[n_envs, 4, 4]`.
`semantics`	Semantic object currently held by the two grippers.

__init__(semantics, left_object_to_eef, right_object_to_eef, left_grasp_xpos, right_grasp_xpos)#

left_grasp_xpos: Tensor#: Left end-effector grasp pose for the shared object, shape [n_envs, 4, 4].

left_object_to_eef: Tensor#: Transform from object frame to left end-effector frame, shape [n_envs, 4, 4].

right_grasp_xpos: Tensor#: Right end-effector grasp pose for the shared object, shape [n_envs, 4, 4].

right_object_to_eef: Tensor#: Transform from object frame to right end-effector frame, shape [n_envs, 4, 4].

semantics: ObjectSemantics#: Semantic object currently held by the two grippers.

class embodichain.lab.sim.atomic_actions.WorldState[source]#

Bases: object

State the engine threads through a sequence of actions.

Methods:

__init__(last_qpos[, held_object, ...])

Attributes:

`coordinated_held_object`	Object currently held by two grippers, or None.
`held_object`	Object currently held by the gripper, or None.
`last_qpos`	Robot joint positions at the start of the next action, shape [n_envs, robot.dof].

__init__(last_qpos, held_object=None, coordinated_held_object=None)#

coordinated_held_object: CoordinatedHeldObjectState | None = None#: Object currently held by two grippers, or None.

held_object: HeldObjectState | None = None#: Object currently held by the gripper, or None.

last_qpos: Tensor#: Robot joint positions at the start of the next action, shape [n_envs, robot.dof].

class embodichain.lab.sim.atomic_actions.ActionResult[source]#

Bases: object

Return value of every AtomicAction.execute call.

Methods:

__init__(success, trajectory, next_state)

Attributes:

`next_state`	World state to feed into the next action.
`success`	Whether the action produced a valid full-DoF trajectory.
`success_all`	True only if all environments succeeded.
`trajectory`	Full-robot trajectory, shape (n_envs, n_waypoints, robot.dof).

__init__(success, trajectory, next_state)#

next_state: WorldState#: World state to feed into the next action.

success: bool | Tensor#: Whether the action produced a valid full-DoF trajectory. Can be a bool or a per-environment boolean tensor of shape (n_envs,).

property success_all: bool#: True only if all environments succeeded.

trajectory: Tensor#: Full-robot trajectory, shape (n_envs, n_waypoints, robot.dof).

class embodichain.lab.sim.atomic_actions.ActionCfg[source]#

Configuration shared by all atomic actions.

Attributes:

`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`planner_type`	'toppra' \| 'neural'.

Methods:

validate([prefix])

Check the validity of configclass object.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.AtomicAction[source]#

Bases: ABC

Abstract base for atomic actions.

Subclasses declare TargetType to advertise the concrete target dataclass they accept. execute is the only required method; validate has been dropped from the contract in this redesign.

Attributes:

TargetType

Concrete target dataclass or dataclasses accepted by execute.

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType: ClassVar[type | tuple[type, ...]]#: Concrete target dataclass or dataclasses accepted by execute.

__init__(motion_generator, cfg=None)[source]#

abstractmethod execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (EndEffectorPoseTarget | JointPositionTarget | NamedJointPositionTarget | GraspTarget | HeldObjectPoseTarget | CoordinatedPickmentTarget | CoordinatedPlacementTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

Trajectory helpers#

class embodichain.lab.sim.atomic_actions.TrajectoryBuilder[source]#

Bases: object

Stateless trajectory utilities shared by every atomic action.

Holds a reference to the motion generator (and through it, the robot and device) so callers don’t have to thread those through each helper call. All methods are pure: no per-call state is kept on the builder.

Methods:

`__init__`(motion_generator)
`all_envs_success`(is_success)	Return true only when all environments report success.
`apply_local_offset`(pose, offset)	Apply a world-frame translational offset to a batched pose.
`broadcast_hand_qpos_to_waypoints`(hand_qpos, ...)	Expand hand qpos to (n_envs, n_waypoints, hand_dof) by broadcasting the per-env value across all waypoints.
`expand_hand_qpos`(hand_qpos, *, n_envs, hand_dof)	Resolve hand qpos to batched shape `(n_envs, hand_dof)`.
`fk_compute`(qpos, *, control_part)	Compute forward kinematics for a joint configuration.
`ik_solve`(target_pose, *, control_part[, ...])	Solve IK for a single (unbatched) target pose.
`interpolate_hand_qpos`(start_hand_qpos, ...)	Interpolate hand joint positions between two gripper states.
`plan_arm_traj`(target_states_list, ...[, cfg])	Plan batched arm trajectories for all environments.
`plan_joint_traj`(start_qpos, target_qpos, ...)	Interpolate a joint-space trajectory through one or more target waypoints.
`resolve_joint_target`(target_qpos, *, n_envs, ...)	Resolve a joint-space target into batched control-part joint positions.
`resolve_pose_target`(target, *, n_envs)	Resolve an end-effector pose target into batched homogeneous transforms.
`resolve_start_qpos`(start_qpos, *, n_envs, ...)	Resolve planning start joint positions into batched arm joint positions.
`split_three_phase`(sample_interval, ...[, ...])	Split total sample interval into motion, hand-interp, and motion phases.

__init__(motion_generator)[source]#

all_envs_success(is_success)[source]#

Return true only when all environments report success.

Return type:: bool

apply_local_offset(pose, offset)[source]#

Apply a world-frame translational offset to a batched pose.

Despite the historical method name, offset is added directly to the translation column and is not rotated by each pose’s orientation.

Return type:: Tensor

broadcast_hand_qpos_to_waypoints(hand_qpos, *, n_envs, hand_dof, n_waypoints)[source]#

Expand hand qpos to (n_envs, n_waypoints, hand_dof) by broadcasting the per-env value across all waypoints.

Return type:: Tensor

expand_hand_qpos(hand_qpos, *, n_envs, hand_dof)[source]#

Resolve hand qpos to batched shape (n_envs, hand_dof).

Return type:: Tensor

fk_compute(qpos, *, control_part)[source]#

Compute forward kinematics for a joint configuration.

Return type:: Tensor

ik_solve(target_pose, *, control_part, qpos_seed=None)[source]#

Solve IK for a single (unbatched) target pose.

Return type:: Tensor

interpolate_hand_qpos(start_hand_qpos, end_hand_qpos, *, n_waypoints)[source]#

Interpolate hand joint positions between two gripper states.

Return type:: Tensor

plan_arm_traj(target_states_list, start_qpos, n_waypoints, *, control_part, arm_dof, cfg=None)[source]#

Plan batched arm trajectories for all environments.

Returns (success:(B,), trajectory:(B, n_waypoints, arm_dof)). cfg.motion_source selects ‘ik_interp’ (default) or ‘motion_gen’.

Return type:: tuple[torch.Tensor, torch.Tensor]

plan_joint_traj(start_qpos, target_qpos, n_waypoints)[source]#

Interpolate a joint-space trajectory through one or more target waypoints.

start_qpos has shape (n_envs, joint_dof). target_qpos is either a single waypoint (n_envs, joint_dof) or a sequence of waypoints (n_envs, n_waypoint, joint_dof). The start configuration is prepended to the target waypoints to build the keyframe sequence (n_envs, 1 + n_waypoint, joint_dof), which is then resampled to n_waypoints output samples by cumulative-distance piecewise-linear interpolation — so each consecutive waypoint pair is traversed in turn.

Return type:: Tensor

resolve_joint_target(target_qpos, *, n_envs, joint_dof, control_part)[source]#

Resolve a joint-space target into batched control-part joint positions.

Accepts the following shapes for target_qpos:

(joint_dof,) — broadcast to (n_envs, joint_dof) (single waypoint).
(n_envs, joint_dof) — single waypoint, validated and passed through.
(n_envs, n_waypoint, joint_dof) — a multi-waypoint trajectory; each waypoint is visited in order. n_waypoint may be 1.

Returns a 2D tensor for single-waypoint inputs and a 3D tensor for multi-waypoint inputs, leaving downstream planners to treat the trailing axis as the joint dimension.

Return type:: Tensor

resolve_pose_target(target, *, n_envs)[source]#

Resolve an end-effector pose target into batched homogeneous transforms.

Accepts the following shapes for target:

(4, 4) — broadcast to (n_envs, 4, 4) (single waypoint).
(n_envs, 4, 4) — single waypoint, validated and passed through.
(n_envs, n_waypoint, 4, 4) — a multi-waypoint trajectory; each waypoint is visited in order. n_waypoint may be 1.

Returns a 3D tensor for single-waypoint inputs and a 4D tensor for multi-waypoint inputs.

Return type:: Tensor

resolve_start_qpos(start_qpos, *, n_envs, arm_dof, control_part)[source]#

Resolve planning start joint positions into batched arm joint positions.

Return type:: Tensor

split_three_phase(sample_interval, hand_interp_steps, *, first_phase_ratio=0.6, first_phase_name='first', third_phase_name='third')[source]#

Split total sample interval into motion, hand-interp, and motion phases.

Return type:: tuple[int, int, int]

Actions#

class embodichain.lab.sim.atomic_actions.MoveEndEffectorCfg[source]#

Bases: ActionCfg

MoveEndEffectorCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>)

Attributes:

`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`planner_type`	'toppra' \| 'neural'.
`sample_interval`	Number of waypoints in the planned trajectory.

Methods:

validate([prefix])

Check the validity of configclass object.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

sample_interval: int#: Number of waypoints in the planned trajectory.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.MoveEndEffector[source]#

Bases: AtomicAction

Plan a free-space end-effector move to a target pose.

The EndEffectorPoseTarget may carry either a single waypoint (n_envs, 4, 4) (or a broadcastable (4, 4)) or a multi-waypoint trajectory (n_envs, n_waypoint, 4, 4). In the multi-waypoint case the action plans a single trajectory that visits every waypoint in order, starting from the inherited WorldState.last_qpos; IK is solved for each waypoint with the previous waypoint’s solution as the seed.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of EndEffectorPoseTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (EndEffectorPoseTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.MoveJointsCfg[source]#

Bases: ActionCfg

MoveJointsCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>, named_joint_positions: ‘dict[str, torch.Tensor] | None’ = <factory>)

Attributes:

`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`named_joint_positions`	Optional named joint targets resolved by `NamedJointPositionTarget`.
`planner_type`	'toppra' \| 'neural'.
`sample_interval`	Number of waypoints in the interpolated joint-space trajectory.

Methods:

validate([prefix])

Check the validity of configclass object.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

named_joint_positions: dict[str, Tensor] | None#: Optional named joint targets resolved by NamedJointPositionTarget.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

sample_interval: int#: Number of waypoints in the interpolated joint-space trajectory.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.MoveJoints[source]#

Bases: AtomicAction

Plan a joint-space move for the configured control part.

The JointPositionTarget may carry either a single waypoint (n_envs, control_dof) or a multi-waypoint trajectory (n_envs, n_waypoint, control_dof). In the multi-waypoint case the action plans a single trajectory that visits every waypoint in order, starting from the inherited WorldState.last_qpos.

Attributes:

TargetType

Concrete target dataclass or dataclasses accepted by execute.

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType: ClassVar[tuple[type, ...]] = (<class 'embodichain.lab.sim.atomic_actions.core.JointPositionTarget'>, <class 'embodichain.lab.sim.atomic_actions.core.NamedJointPositionTarget'>)#: Concrete target dataclass or dataclasses accepted by execute.

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (JointPositionTarget | NamedJointPositionTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.PickUpCfg[source]#

Bases: ActionCfg

PickUpCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>, hand_interp_steps: ‘int’ = <factory>, hand_control_part: ‘str’ = <factory>, hand_open_qpos: ‘torch.Tensor | None’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>, lift_height: ‘float’ = <factory>, pre_grasp_distance: ‘float’ = <factory>, approach_direction: ‘torch.Tensor’ = <factory>, approach_alignment_max_angle: ‘float | None’ = <factory>, downstream_object_target_poses: ‘tuple[torch.Tensor, …]’ = <factory>, obj_upright_direction: ‘torch.Tensor | None’ = <factory>, rotate_upright: ‘float | None’ = <factory>)

Attributes:

`approach_alignment_max_angle`	Optional maximum TCP z-axis deviation from the approach direction.
`approach_direction`	World-frame direction from the pre-grasp pose to the grasp pose.
`downstream_object_target_poses`	Future object poses that must be reachable with the selected grasp.
`hand_close_qpos`	Joint positions for the closed hand state, shape `[hand_dof,]`.
`hand_control_part`	Name of the robot part that controls the hand joints.
`hand_interp_steps`	Number of waypoints for the gripper close interpolation phase.
`hand_open_qpos`	Joint positions for the open hand state, shape `[hand_dof,]`.
`lift_height`	Height (m) to lift the end-effector after closing the gripper.
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`obj_upright_direction`	Optional object local direction used to choose the upright grasp rotation.
`planner_type`	'toppra' \| 'neural'.
`pre_grasp_distance`	Distance to offset back from the grasp pose along the approach direction.
`rotate_upright`	Optional rotation (radians) about the grasp x-axis to apply after grasp selection.
`sample_interval`	Number of waypoints for the full trajectory (approach + hand + lift).

Methods:

validate([prefix])

Check the validity of configclass object.

approach_alignment_max_angle: float | None#: Optional maximum TCP z-axis deviation from the approach direction.

approach_direction: Tensor#: World-frame direction from the pre-grasp pose to the grasp pose.

downstream_object_target_poses: tuple[Tensor, ...]#: Future object poses that must be reachable with the selected grasp.

hand_close_qpos: Tensor | None#: Joint positions for the closed hand state, shape [hand_dof,].

hand_control_part: str#: Name of the robot part that controls the hand joints.

hand_interp_steps: int#: Number of waypoints for the gripper close interpolation phase.

hand_open_qpos: Tensor | None#: Joint positions for the open hand state, shape [hand_dof,].

lift_height: float#: Height (m) to lift the end-effector after closing the gripper.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

obj_upright_direction: Tensor | None#: Optional object local direction used to choose the upright grasp rotation.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

pre_grasp_distance: float#: Distance to offset back from the grasp pose along the approach direction.

rotate_upright: float | None#: Optional rotation (radians) about the grasp x-axis to apply after grasp selection.

sample_interval: int#: Number of waypoints for the full trajectory (approach + hand + lift).

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.PickUp[source]#

Bases: AtomicAction

Approach a grasp pose, close the gripper, lift.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of GraspTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (GraspTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.MoveHeldObjectCfg[source]#

Bases: ActionCfg

MoveHeldObjectCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>, hand_control_part: ‘str’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>, obj_upright_direction: ‘torch.Tensor | None’ = <factory>, pick_rotate_upright: ‘float | None’ = <factory>)

Attributes:

`hand_close_qpos`	Joint positions for the closed hand state, shape `[hand_dof,]`.
`hand_control_part`	Name of the robot part that controls the hand joints.
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`obj_upright_direction`	Optional object-local direction to align with world up while moving.
`pick_rotate_upright`	Optional rotation in radians used by the legacy upright transport mode.
`planner_type`	'toppra' \| 'neural'.
`sample_interval`	Number of waypoints in the planned trajectory.

Methods:

validate([prefix])

Check the validity of configclass object.

hand_close_qpos: Tensor | None#: Joint positions for the closed hand state, shape [hand_dof,].

hand_control_part: str#: Name of the robot part that controls the hand joints.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

obj_upright_direction: Tensor | None#: Optional object-local direction to align with world up while moving.

pick_rotate_upright: float | None#: Optional rotation in radians used by the legacy upright transport mode.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

sample_interval: int#: Number of waypoints in the planned trajectory.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.MoveHeldObject[source]#

Bases: AtomicAction

Move the held object to a target object pose; keep the gripper closed.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of HeldObjectPoseTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (HeldObjectPoseTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.PlaceCfg[source]#

Bases: ActionCfg

PlaceCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>, hand_interp_steps: ‘int’ = <factory>, hand_control_part: ‘str’ = <factory>, hand_open_qpos: ‘torch.Tensor | None’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>, lift_height: ‘float’ = <factory>, max_approach_retract_z: ‘float | None’ = <factory>, cartesian_waypoint_count: ‘int’ = <factory>)

Attributes:

`cartesian_waypoint_count`	Number of fixed-orientation Cartesian keyframes per translation segment.
`hand_close_qpos`	Joint positions for the closed hand state, shape `[hand_dof,]`.
`hand_control_part`	Name of the robot part that controls the hand joints.
`hand_interp_steps`	Number of waypoints for the gripper open interpolation phase.
`hand_open_qpos`	Joint positions for the open hand state, shape `[hand_dof,]`.
`lift_height`	Height (m) to retract the end-effector after opening the gripper.
`max_approach_retract_z`	Optional maximum world-frame TCP z for approach and retract poses (m).
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`planner_type`	'toppra' \| 'neural'.
`sample_interval`	Number of waypoints for the full trajectory (down + hand + back).

Methods:

validate([prefix])

Check the validity of configclass object.

cartesian_waypoint_count: int#: Number of fixed-orientation Cartesian keyframes per translation segment.

hand_close_qpos: Tensor | None#: Joint positions for the closed hand state, shape [hand_dof,].

hand_control_part: str#: Name of the robot part that controls the hand joints.

hand_interp_steps: int#: Number of waypoints for the gripper open interpolation phase.

hand_open_qpos: Tensor | None#: Joint positions for the open hand state, shape [hand_dof,].

lift_height: float#: Height (m) to retract the end-effector after opening the gripper.

max_approach_retract_z: float | None#: Optional maximum world-frame TCP z for approach and retract poses (m).

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

sample_interval: int#: Number of waypoints for the full trajectory (down + hand + back).

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.Place[source]#

Bases: AtomicAction

Lower the held object to a place pose, open the gripper, retract.

The EndEffectorPoseTarget may carry either a single waypoint (n_envs, 4, 4) (or a broadcastable (4, 4)) or a multi-waypoint trajectory (n_envs, n_waypoint, 4, 4). In the multi-waypoint case the down phase visits every waypoint in order; approaching from above the first waypoint, descending through each waypoint, then opening the gripper at the final waypoint and retracting to above the last waypoint. Starting joint positions are inherited from WorldState.last_qpos.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of EndEffectorPoseTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (EndEffectorPoseTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.PressCfg[source]#

Bases: ActionCfg

PressCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, sample_interval: ‘int’ = <factory>, hand_interp_steps: ‘int’ = <factory>, hand_control_part: ‘str’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>)

Attributes:

`hand_close_qpos`	Joint positions for the closed hand state, shape `[hand_dof,]`.
`hand_control_part`	Name of the robot part that controls the hand joints.
`hand_interp_steps`	Number of waypoints for closing the gripper before pressing.
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`planner_type`	'toppra' \| 'neural'.
`sample_interval`	Number of waypoints for the full trajectory (hand close + down + back).

Methods:

validate([prefix])

Check the validity of configclass object.

hand_close_qpos: Tensor | None#: Joint positions for the closed hand state, shape [hand_dof,].

hand_control_part: str#: Name of the robot part that controls the hand joints.

hand_interp_steps: int#: Number of waypoints for closing the gripper before pressing.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

sample_interval: int#: Number of waypoints for the full trajectory (hand close + down + back).

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.Press[source]#

Bases: AtomicAction

Close the gripper, press down to a target pose, then return.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of EndEffectorPoseTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (EndEffectorPoseTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.CoordinatedPickmentCfg[source]#

Bases: ActionCfg

CoordinatedPickmentCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, left_arm_control_part: ‘str’ = <factory>, right_arm_control_part: ‘str’ = <factory>, left_hand_control_part: ‘str’ = <factory>, right_hand_control_part: ‘str’ = <factory>, left_hand_open_qpos: ‘torch.Tensor | None’ = <factory>, left_hand_close_qpos: ‘torch.Tensor | None’ = <factory>, right_hand_open_qpos: ‘torch.Tensor | None’ = <factory>, right_hand_close_qpos: ‘torch.Tensor | None’ = <factory>, object_motion_keyframes: ‘int’ = <factory>, pre_grasp_distance: ‘float’ = <factory>, lift_height: ‘float’ = <factory>, sample_interval: ‘int’ = <factory>, hand_interp_steps: ‘int’ = <factory>, hold_steps: ‘int’ = <factory>)

Attributes:

`control_part`	Combined control part containing left and right arm joints.
`hand_interp_steps`	Number of waypoints used for the simultaneous hand close phase.
`hold_steps`	Number of waypoints to hold the final object target pose.
`left_arm_control_part`	Left arm control part used to grasp one end of the object.
`left_hand_close_qpos`	Left hand qpos for the closed state.
`left_hand_control_part`	Hand attached to the left arm.
`left_hand_open_qpos`	Left hand qpos for the open state.
`lift_height`	World-Z lift distance before moving to the object target pose.
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`object_motion_keyframes`	Number of object-pose keyframes solved by IK before joint-space interpolation.
`planner_type`	'toppra' \| 'neural'.
`pre_grasp_distance`	World distance to retreat from each grasp pose along negative TCP z.
`right_arm_control_part`	Right arm control part used to grasp the other end of the object.
`right_hand_close_qpos`	Right hand qpos for the closed state.
`right_hand_control_part`	Hand attached to the right arm.
`right_hand_open_qpos`	Right hand qpos for the open state.
`sample_interval`	Number of waypoints for the full coordinated pickment trajectory.

Methods:

validate([prefix])

Check the validity of configclass object.

control_part: str#: Combined control part containing left and right arm joints.

hand_interp_steps: int#: Number of waypoints used for the simultaneous hand close phase.

hold_steps: int#: Number of waypoints to hold the final object target pose.

left_arm_control_part: str#: Left arm control part used to grasp one end of the object.

left_hand_close_qpos: Tensor | None#: Left hand qpos for the closed state.

left_hand_control_part: str#: Hand attached to the left arm.

left_hand_open_qpos: Tensor | None#: Left hand qpos for the open state.

lift_height: float#: World-Z lift distance before moving to the object target pose.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

object_motion_keyframes: int#: Number of object-pose keyframes solved by IK before joint-space interpolation.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

pre_grasp_distance: float#: World distance to retreat from each grasp pose along negative TCP z.

right_arm_control_part: str#: Right arm control part used to grasp the other end of the object.

right_hand_close_qpos: Tensor | None#: Right hand qpos for the closed state.

right_hand_control_part: str#: Hand attached to the right arm.

right_hand_open_qpos: Tensor | None#: Right hand qpos for the open state.

sample_interval: int#: Number of waypoints for the full coordinated pickment trajectory.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.CoordinatedPickment[source]#

Bases: AtomicAction

Pick and move a single object pinched by two hands.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of CoordinatedPickmentTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (CoordinatedPickmentTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

class embodichain.lab.sim.atomic_actions.CoordinatedPlacementCfg[source]#

Bases: ActionCfg

CoordinatedPlacementCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, motion_source: ‘str’ = <factory>, planner_type: ‘str | None’ = <factory>, placing_arm_control_part: ‘str’ = <factory>, support_arm_control_part: ‘str’ = <factory>, placing_hand_control_part: ‘str’ = <factory>, support_hand_control_part: ‘str’ = <factory>, placing_hand_open_qpos: ‘torch.Tensor | None’ = <factory>, placing_hand_close_qpos: ‘torch.Tensor | None’ = <factory>, support_hand_close_qpos: ‘torch.Tensor | None’ = <factory>, release: ‘bool’ = <factory>, placing_height_offset: ‘float’ = <factory>, support_height_offset: ‘float’ = <factory>, lift_height: ‘float’ = <factory>, sample_interval: ‘int’ = <factory>, hand_interp_steps: ‘int’ = <factory>, hold_steps: ‘int’ = <factory>, retreat_steps: ‘int’ = <factory>)

Attributes:

`control_part`	Robot control part containing both placing and support arms.
`hand_interp_steps`	Number of waypoints for the placing-hand release interpolation.
`hold_steps`	Number of waypoints to hold alignment before releasing.
`lift_height`	World-Z lift distance for the placing arm after release.
`motion_source`	'ik_interp' (default, batched IK + linear interp) or 'motion_gen' (batched MotionGenerator).
`name`	Name of the action, used for identification and logging.
`placing_arm_control_part`	Arm that places and releases its held object.
`placing_hand_close_qpos`	Placing-hand qpos for the closed state, shape `[hand_dof,]`.
`placing_hand_control_part`	Hand attached to the placing arm.
`placing_hand_open_qpos`	Placing-hand qpos for the open state, shape `[hand_dof,]`.
`placing_height_offset`	Default World-Z offset above the placing object target pose.
`planner_type`	'toppra' \| 'neural'.
`release`	Whether to open the placing hand at the aligned placement pose.
`retreat_steps`	Number of waypoints used for the placing-arm lift retreat.
`sample_interval`	Number of waypoints for the full coordinated placement trajectory.
`support_arm_control_part`	Arm that moves the support object and keeps holding it.
`support_hand_close_qpos`	Support-hand qpos for the closed state, shape `[hand_dof,]`.
`support_hand_control_part`	Hand attached to the support arm.
`support_height_offset`	Default World-Z offset above the support object target pose.

Methods:

validate([prefix])

Check the validity of configclass object.

control_part: str#: Robot control part containing both placing and support arms.

hand_interp_steps: int#: Number of waypoints for the placing-hand release interpolation.

hold_steps: int#: Number of waypoints to hold alignment before releasing.

lift_height: float#: World-Z lift distance for the placing arm after release.

motion_source: str#

‘ik_interp’ (default, batched IK + linear interp) or ‘motion_gen’ (batched MotionGenerator).

Type:: Trajectory source

name: str#: Name of the action, used for identification and logging.

placing_arm_control_part: str#: Arm that places and releases its held object.

placing_hand_close_qpos: Tensor | None#: Placing-hand qpos for the closed state, shape [hand_dof,].

placing_hand_control_part: str#: Hand attached to the placing arm.

placing_hand_open_qpos: Tensor | None#: Placing-hand qpos for the open state, shape [hand_dof,].

placing_height_offset: float#: Default World-Z offset above the placing object target pose.

planner_type: str | None#

‘toppra’ | ‘neural’. Required when motion_source=’motion_gen’.

Type:: Planner type for motion_source=’motion_gen’

release: bool#: Whether to open the placing hand at the aligned placement pose.

retreat_steps: int#: Number of waypoints used for the placing-arm lift retreat.

sample_interval: int#: Number of waypoints for the full coordinated placement trajectory.

support_arm_control_part: str#: Arm that moves the support object and keeps holding it.

support_hand_close_qpos: Tensor | None#: Support-hand qpos for the closed state, shape [hand_dof,].

support_hand_control_part: str#: Hand attached to the support arm.

support_height_offset: float#: Default World-Z offset above the support object target pose.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.sim.atomic_actions.CoordinatedPlacement[source]#

Bases: AtomicAction

Coordinate two held objects: support object below, placing object above.

Classes:

TargetType

Methods:

`__init__`(motion_generator[, cfg])
`execute`(target, state)	Plan and return a full-DoF trajectory for this action.

TargetType#: alias of CoordinatedPlacementTarget

__init__(motion_generator, cfg=None)[source]#

execute(target, state)[source]#

Plan and return a full-DoF trajectory for this action.

Parameters:

target (CoordinatedPlacementTarget) – Typed target dataclass; must be an instance of self.TargetType.
state (WorldState) – World state inherited from the previous action (or the engine seed).

Return type:

ActionResult

Returns:

ActionResult with the planned trajectory and the successor world state.

Engine & Registry#

class embodichain.lab.sim.atomic_actions.AtomicActionEngine[source]#

Bases: object

Sequences typed atomic actions while threading WorldState through them.

Methods:

`__init__`(motion_generator)
`register`(action, *[, name])	Register an action instance under `name` or its `cfg.name`.
`run`(steps[, state])	Run a sequence of named actions, threading WorldState through.

Attributes:

actions

Registered actions keyed by name (read-only copy).

__init__(motion_generator)[source]#

property actions: dict[str, AtomicAction]#: Registered actions keyed by name (read-only copy).

register(action, *, name=None)[source]#

Register an action instance under name or its cfg.name.

Return type:: None

run(steps, state=None)[source]#

Run a sequence of named actions, threading WorldState through.

Parameters:

steps (Iterable[tuple[str, EndEffectorPoseTarget | JointPositionTarget | NamedJointPositionTarget | GraspTarget | HeldObjectPoseTarget | CoordinatedPickmentTarget | CoordinatedPlacementTarget]]) – Iterable of (action_name, typed_target) pairs.
state (WorldState | None) – Initial world state. If None, seeded from robot.get_qpos().

Return type:

tuple[Tensor, Tensor, WorldState]

Returns:

(success, concatenated_full_dof_trajectory, final_state).

success is a (B,) boolean tensor indicating which environments completed every step. Failed environments hold their last successful joint position in both full_traj and final_state.last_qpos for the remainder of the sequence.

An empty steps iterable is a successful no-op returning an empty trajectory and the seed state.

embodichain.lab.sim.atomic_actions.register_action(name, action_class)[source]#

Register a custom AtomicAction subclass globally under name.

Return type:: None

embodichain.lab.sim.atomic_actions.unregister_action(name)[source]#

Remove a previously-registered action class. No-op if absent.

Return type:: None

embodichain.lab.sim.atomic_actions.get_registered_actions()[source]#

Return a copy of the global action-class registry.

Return type:: dict[str, type[AtomicAction]]

embodichain.lab.sim.atomic_actions

Contents

embodichain.lab.sim.atomic_actions#

Layout#

Core#

Trajectory helpers#

Actions#

Engine & Registry#