embodichain.lab.sim.robots

embodichain.lab.sim.robots#

Generic dual-arm composition; concrete presets live in embodichain_robots.

Overview#

Generic dual-arm composition built from compatible single-arm configurations. build_dual_arm_cfg() assembles two single-arm configs into a synchronized dual-arm robot. Concrete presets are imported from embodichain_robots; see Robot catalogs and configurations for those configuration classes and Robot Catalog for discovery and variant selection.

Classes

DualArmRobotCfg

Configuration for a dual-manipulator composed from a single-arm robot.

Functions

build_dual_arm_cfg(base_cfg, mounts, *[, ...])

Build a dual-arm cfg from a single-arm robot cfg.

class embodichain.lab.sim.robots.DualArmRobotCfg[source]#

Bases: RobotCfg

Configuration for a dual-manipulator composed from a single-arm robot.

Two identical arms (the base_robot) are mounted on a shared synthetic base_link. The left/right control_parts, per-arm solver_cfg and mirrored joint_drive_props are derived automatically by build_dual_arm_cfg().

Example

cfg = DualArmRobotCfg.from_dict(

{“base_robot”: “ur5”,: “mount”: {“preset”: “side_by_side”, “separation”: 0.6}}

) robot = sim.add_robot(cfg=cfg)

Classes:

SolverCfg

Configuration for the kinematic solver used in the robot simulation.

Attributes:

`arm_part`	Name of the base robot's manipulator control part.
`asset_physics_mode`	Apply configured robot physics on top of source-authored values.
`attrs`	Physical attributes for all links.
`base_robot`	Registry key (e.g. `"ur5"`) or `{"type": ..., "init": {...}}`.
`body_scale`	Scale of the articulation in the simulation world frame.
`build_pk_chain`	Build a pytorch-kinematics chain for FK and Jacobian computation.
`compute_uv`	Whether to compute the UV mapping for the articulation link.
`control_parts`	Control parts is the mapping from part name to joint names.
`dual_part`	Whether to emit a `"dual_arm"` composite control part.
`enable_sensor`	Initialize mounted sensors when adding the robot.
`fpath`	Path to the articulation asset file.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_qpos`	Initial joint positions of the articulation.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`joint_drive_props`	Joint drive, limit, friction, and armature properties.
`link_attrs`	Named per-link physics override groups keyed by regex on link names.
`mount`	Mount configuration consumed by `resolve_mounts()`.
`qpos_limits`	Override joint position limits of the articulation.
`root_props`	Grouped articulation-root properties.
`sensors`	Mounted camera configurations with robot-local parent link names.
`solver_cfg`	Solver is used to compute forward and inverse kinematics for the robot.
`source`	USD source asset; mutually exclusive with `fpath`.
`urdf_cfg`	URDF assembly configuration which allows for assembling a robot from multiple URDF components.
`workspace_cfg`	Runtime workspace cache configuration keyed by control-part name.

Methods:

`build_pk_serial_chain`([device])	Build the per-arm pytorch-kinematics serial chains.
`from_dict`(init_dict)	Initialize from a dictionary.
`resolve_asset_physics_mode`()	Return the effective file-backed physics policy.
`save_to_file`(filepath)	Save config to a local file as JSON.
`to_string`()	Return config as a JSON string.

class SolverCfg#

Bases: object

Configuration for the kinematic solver used in the robot simulation.

Attributes:

`class_type`	The class type of the solver to be used.
`end_link_name`	The name of the end-effector link for the solver.
`ik_nearest_weight`	Weights for the inverse kinematics nearest calculation.
`joint_names`	List of joint names for the solver.
`root_link_name`	The name of the root/base link for the solver.
`tcp`	The tool center point (TCP) position as a 4x4 homogeneous matrix.
`urdf_path`	The file path to the URDF model of the robot.
`user_qpos_limits`	User defined Joint position limits [2, DOF] for the solver.

Methods:

from_dict(init_dict)

Initialize the concrete solver configuration from a dictionary.

class_type: str#: The class type of the solver to be used.

end_link_name: str#

The name of the end-effector link for the solver.

This defines the target link for forward/inverse kinematics calculations. Must match a link name in the URDF file.

classmethod from_dict(init_dict)#

Initialize the concrete solver configuration from a dictionary.

The concrete config receives all recognized dataclass init fields in its constructor so initialization and __post_init__ observe the final inputs exactly once. Legacy unannotated config attributes are applied afterward. Unknown fields preserve the historical behavior: they are ignored with a warning.

Return type:: SolverCfg

ik_nearest_weight: Optional[List[float]]#

Weights for the inverse kinematics nearest calculation.

The weights influence how the solver prioritizes closeness to the seed position when multiple solutions are available.

joint_names: list[str] | None#

List of joint names for the solver.

If None, all joints in the URDF will be used. If specified, only these named joints will be included in the kinematic chain.

root_link_name: str#

The name of the root/base link for the solver.

This defines the starting point of the kinematic chain. Must match a link name in the URDF file.

tcp: Tensor | ndarray#

The tool center point (TCP) position as a 4x4 homogeneous matrix.

This represents the position and orientation of the tool in the robot’s end-effector frame. It must be a finite SE(3) rigid transform; affine transforms are not supported.

urdf_path: str | None#: The file path to the URDF model of the robot.

user_qpos_limits: Optional[List[float]]#: User defined Joint position limits [2, DOF] for the solver. If not provided (None), this value will replace by joint limits defined in urdf when solver init from robot. If provided, the solver will use the intersection of user defined limits and urdf limits as the final joint limits.

arm_part: str#: Name of the base robot’s manipulator control part.

asset_physics_mode: AssetPhysicsMode#: Apply configured robot physics on top of source-authored values.

attrs: RigidBodyPhysicsCfg#: Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

base_robot: str | dict#: Registry key (e.g. "ur5") or {"type": ..., "init": {...}}.

body_scale: tuple | list#: Scale of the articulation in the simulation world frame.

build_pk_chain: bool#

Build a pytorch-kinematics chain for FK and Jacobian computation.

USD assets use resolved simulation joint descriptors after preparation; URDF assets use their source kinematic tree. USD kinematics supports trees of fixed, revolute, and prismatic joints, including child-side joint frames. Set False to load other joint topologies for simulation without FK.

build_pk_serial_chain(device=device(type='cpu'), **kwargs)[source]#

Build the per-arm pytorch-kinematics serial chains.

Each chain uses its own solver root and end frames. Assembled frame names are mapped back to the single-arm URDF names using the component prefix and link case policy; already arm-local names are preserved. Joint names and transforms remain local to the arm URDF.

Parameters:

device (device) – The device to move the chains to. Defaults to CPU.
**kwargs – Additional arguments for building the serial chains.

Return type:

Dict[str, SerialChain]

Returns:

A {"left_arm": chain, "right_arm": chain} mapping.

compute_uv: bool#

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: Dict[str, List[str]] | None#

Control parts is the mapping from part name to joint names.

For example, {‘left_arm’: [‘joint1’, ‘joint2’], ‘right_arm’: [‘joint3’, ‘joint4’]} If no control part is specified, the robot will use all joints as a single control part.

Official defaults use arm / eef for single-arm robots and left_arm, right_arm, left_eef, right_eef for dual-arm robots. These are naming conventions only: caller-defined part names are preserved without reserved names, automatic aliases, or inferred capabilities.

Note

if control_parts is specified, solver_cfg must be a dict with part names as
keys corresponding to the control parts name.
The joint names in the control parts support regular expressions, e.g., ‘joint[1-6]’.
After initialization of robot, the names will be expanded to a list of full joint names.
Robot is a derived class of Articulation, with control parts support. So the joint_drive_props
in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

dual_part: bool#: Whether to emit a "dual_arm" composite control part.

enable_sensor: bool#: Initialize mounted sensors when adding the robot. Gym overrides this with its environment-wide acquisition switch, which defaults to True.

fpath: str#: Path to the articulation asset file.

classmethod from_dict(init_dict)[source]#

Initialize from a dictionary.

Parameters:: init_dict (dict) – Configuration dict. base_robot, mount, arm_part and dual_part drive the dual-arm derivation; all other recognized RobotCfg keys are merged on top via merge_robot_cfg().
Return type:: DualArmRobotCfg
Returns:: A DualArmRobotCfg instance.

init_local_pose: np.ndarray | None#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: torch.Tensor | np.ndarray | Sequence[float]#

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be an array of shape (num_dofs,).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

joint_drive_props: JointDrivePropertiesCfg#: Joint drive, limit, friction, and armature properties.

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None#

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

mount: dict#: Mount configuration consumed by resolve_mounts().

qpos_limits: torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None#

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_dofs, 2), it is applied in flattened source-resolved DOF order before the backend model is built. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

resolve_asset_physics_mode()#

Return the effective file-backed physics policy.

Return type:: Literal['preserve', 'overlay']

root_props: ArticulationRootPropertiesCfg#

Grouped articulation-root properties.

Fixed-base and self-collision intent is portable. Root sleep and solver iterations are Default-only fields and are ignored by Newton. The portable fields default to a fixed base with self-collision disabled. Set either field to None to preserve an authored USD/backend value; URDF imports then use the established fixed-base, self-collision-off defaults.

save_to_file(filepath)#: Save config to a local file as JSON.

sensors: list[SensorCfg]#

Mounted camera configurations with robot-local parent link names.

An explicit list replaces the robot’s default suite; an empty list clears it. Sensor UIDs must be unique in the simulation. Runtime parent binding uses a copy, preserving these local calibration declarations.

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None#: Solver is used to compute forward and inverse kinematics for the robot.

source: UsdSourceCfg | None = None#: USD source asset; mutually exclusive with fpath.

to_string()#: Return config as a JSON string.

urdf_cfg: URDFCfg | None#: URDF assembly configuration which allows for assembling a robot from multiple URDF components.

workspace_cfg: Dict[str, RobotWorkspaceCfg] | None#: Runtime workspace cache configuration keyed by control-part name.

embodichain.lab.sim.robots.build_dual_arm_cfg(base_cfg, mounts, *, dual_part=True, arm_part='arm')[source]#