Public API Supplement

This page lists module exports declared through __all__ that are not covered by a more focused API-reference page. Prefer curated pages for APIs that need deeper explanations or examples. Sphinx obtains signatures and summaries here from the canonical Python docstrings.

embodichain.agents.mllm.task_program

Strict MLLM entry points that inject host-owned integration settings before decoding and compiling the constrained Task Program schema surface.

compile_mllm_task_program(response, *, ...)	Decode and compile a model response through the existing environment path.
decode_mllm_task_program(response, *, ...[, ...])	Decode one untrusted model response into the canonical program config.

embodichain.data.assets.planner_assets

download_neural_planner_checkpoint([...])

Download a neural planner checkpoint from HuggingFace.

embodichain.data.assets.solver_assets

download_neural_ik_checkpoint([repo_id, ...])

Download a neural IK solver checkpoint from HuggingFace.

embodichain.data_pipeline.depth_video

DEFAULT_DEPTH_MIN	Convert a string or number to a floating point number, if possible.
DEFAULT_DEPTH_MAX	Convert a string or number to a floating point number, if possible.
DEFAULT_DEPTH_SHIFT	Convert a string or number to a floating point number, if possible.
DEFAULT_DEPTH_USE_LOG	bool(x) -> bool
DEFAULT_DEPTH_PIX_FMT	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
DEPTH_METER_UNIT	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
DEPTH_MILLIMETER_UNIT	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
DEPTH_QMAX	int([x]) -> integer int(x, base=10) -> integer

embodichain.gen_sim.env

find_gen_sim_env_file()	Return the configured shared .env file path.
get_embodichain_root()	Return the repository containing the installed GenSim source tree.
load_gen_sim_env([env])	Load missing variables from the shared GenSim .env file.

embodichain.gen_sim.gradio_ui.app_articraft

embodichain.gen_sim.gradio_ui.app_asset_engine

embodichain.gen_sim.gradio_ui.app_commands

embodichain.gen_sim.gradio_ui.app_env

ACTION_ENGINE_VISER_PORT	int([x]) -> integer int(x, base=10) -> integer
ARTICULATION_SERVER_BASE_URL	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICULATION_SERVER_POLL_INTERVAL_S	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICULATION_SERVER_TASK_TIMEOUT_S	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICULATION_SERVER_TIMEOUT_S	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICRAFT_CONDA_ENV	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICRAFT_OUTPUT_ROOT	Path subclass for non-Windows systems.
ARTICRAFT_REPOSITORY_URL	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ARTICRAFT_ROOT	Path subclass for non-Windows systems.
DIRECT_NO_PROXY_VALUE	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
EMBODICHAIN_ROOT	Path subclass for non-Windows systems.
GRADIO_AUTH_PASSWORD	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
GRADIO_AUTH_USERNAME	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
PROXY_ENV_KEYS	Built-in immutable sequence.
SCENE_ENGINE_VISER_PORT	int([x]) -> integer int(x, base=10) -> integer
SERVER_NAME	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
SERVER_PORT	int([x]) -> integer int(x, base=10) -> integer
SIMREADY_OPENAI_API_KEY	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
SIMREADY_OPENAI_BASE_URL	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
SIMREADY_OPENAI_MODEL	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
build_gradio_allowed_paths(*roots)	Resolve the explicit static and generated roots Gradio may serve.
build_gradio_blocked_paths(env_path)	Resolve repository metadata and dotenv paths Gradio must never serve.
configure_direct_network_env([env])	Disable proxy inheritance for local pipeline and Gradio processes.
configure_simready_llm_env([env])	Map app-level SimReady settings to the upstream CLI's environment.
get_inherited_network_env()	Return the network environment captured before Gradio forces direct access.
get_gradio_auth([server_name, username, ...])	Validate deployment exposure and return Gradio credentials.
validate_gradio_artifact_root(root)	Reject an artifact setting broad enough to expose the repository.

embodichain.gen_sim.gradio_ui.app_media

embodichain.gen_sim.gradio_ui.app_processes

embodichain.gen_sim.gradio_ui.app_services

embodichain.gen_sim.gradio_ui.app_state

embodichain.gen_sim.gradio_ui.app_ui

embodichain.gen_sim.gradio_ui.app_workflows

embodichain.gen_sim.gradio_ui.gradio_app

embodichain.gen_sim.scene_engine.core.scene_edit_plan

SceneEditOperation	One normalized edit operation produced from an LLM edit draft.
SceneEditPlan	Validated operations against one immutable pre-edit scene state.

embodichain.gen_sim.scene_engine.pipeline.editing.scene_edit_asset_preparation

prepare_scene_edit_assets(*, ...[, vlm_client])

Prepare and return SimReady assets required by add operations.

embodichain.gen_sim.simready_pipeline.cli.start

cli_ingest_single(input_dir, output_dir, ...)	Ingest one asset directory.
main([argv])	Run the SimReady asset pipeline CLI.

embodichain.lab.gym.envs.base_env

BaseEnv	Base environment for robot learning.
EnvCfg	Configuration for an Robot Learning Environment.

embodichain.lab.gym.envs.demo

DEMO_ANNOTATION_KEYS	Per-frame annotation keys stored in expert rollout buffers.
DEMO_SCHEMA_VERSION	Current version of the segment-aware demonstration metadata schema.
DemoExecutionCfg	Collector-owned settings for demonstration persistence.
DemoEpisodeResult	Result of executing all planned segments for one batched episode.
DemoOutputMode	Supported persistence layouts for one demonstration execution.
DemoSegment	One semantic subtask inside a demonstration episode.
DemoSegmentOutcomeKind	Stable, first-failure-phase outcome for one program segment row.
DemoSegmentResult	Execution result and half-open frame range for one segment.
execute_demo_episode(env, *[, ...])	Plan and execute every segment in one environment episode.
resolve_demo_segments(env, **kwargs)	Resolve a task's segment plan with legacy single-action-list fallback.

embodichain.lab.gym.envs.embodied_env

EmbodiedEnvCfg	Configuration for Embodied AI environments.
EmbodiedEnv	Embodied AI environment that is used to simulate the Embodied AI tasks.

embodichain.lab.task_program.integrations.simulation.handover

ConfiguredHandOverPoseProvider

Resolve a hand-over delivery target from immutable configuration.

embodichain.lab.gym.envs.managers.action_manager

ActionTerm	Base class for action terms.
ActionManager	Manager for processing actions sent to the environment.

embodichain.lab.gym.envs.managers.actions

DeltaQposTerm	Delta joint position action: current_qpos + scale * action -> qpos.
QposTerm	Absolute joint position action: scale * action -> qpos.
QposDenormalizedTerm	Normalized action in [range[0], range[1]] -> denormalize to joint limits -> qpos.
QposNormalizedTerm	Normalize action from qpos limits -> [range[0], range[1]].
EefPoseTerm	End-effector pose (6D or 7D) -> IK -> qpos.
QvelTerm	Joint velocity action: scale * action -> qvel.
QfTerm	Joint force/torque action: scale * action -> qf.

embodichain.lab.gym.envs.wrapper.replay

ReplayWrapper

Replay a recorded environment trajectory.

embodichain.lab.gym.utils

EnvProfiler	alias of Profiler
EnvProfilerCfg	alias of ProfilerCfg
capture_trajectory_state(env, states, env_ids)	Capture restorable simulation state into a trajectory state view.
restore_trajectory_state(env, states)	Restore one trajectory timestep into an environment scene.

embodichain.lab.gym.utils.gym_utils

DEFAULT_MANAGER_MODULES	Built-in mutable sequence.
add_env_launcher_args_to_parser(parser, *[, ...])	Add common environment launcher arguments to an existing argparse parser.
assign_data_to_dict(data_dict, name, value)	Assign data to a TensorDict using a '/' separated key.
batch(*args)	Adds one dimension in front of everything.
build_env_cfg_from_args(args[, ...])	Build environment configuration from command-line arguments.
cat_tensor_with_ids(tensors, ids, dim)	Concatenate tensors along a new dimension specified by dim, using the provided ids to index into the tensors.
clip_and_scale_action(action, low, high)	Clip action to [-1, 1] and scale according to a range [low, high].
config_to_cfg(config[, manager_modules, ...])	Parser configuration file into cfgs for env initialization.
convert_observation_to_space(observation[, ...])	Convert observation to OpenAI gym observation space (recursively).
dict_array_to_torch_inplace(data[, device])	Convert arrays in a dictionary to torch tensors in-place.
fetch_data_from_dict(data_dict, name)	Fetch data from a nested dictionary using a '/' separated key.
flatten_state_dict(state_dict[, use_torch, ...])	Flatten a dictionary containing states recursively.
get_dtype_bounds(dtype)	Gets the min and max values of a given numpy type
get_manager_modules()	Get all registered manager modules (built-in + extensions).
init_rollout_buffer_from_config(config, ...)	Initialize a rollout buffer based on the environment configuration.
init_rollout_buffer_from_gym_space(...[, device])	Initialize a rollout buffer based on the observation and action spaces.
map_qpos_to_eef_pose(robot, qpos, control_parts)	Map qpos to end-effector pose.
merge_args_with_gym_config(args, gym_config)	Merge command-line arguments with gym configuration.
register_manager_modules(modules)	Register additional manager modules for functor resolution.
to_cpu_tensor(array)	Maps any given sequence to a torch tensor on the CPU.
to_tensor(array[, device])	Maps any given sequence to a torch tensor on the CPU/GPU.

embodichain.lab.gym.utils.profiler

EnvProfilerCfg	alias of ProfilerCfg
EnvProfiler	alias of Profiler

embodichain.lab.gym.utils.trajectory_state

capture_trajectory_state(env, states, env_ids)	Capture restorable simulation state into a trajectory state view.
restore_trajectory_state(env, states)	Restore one trajectory timestep into an environment scene.

embodichain.lab.scripts.analyze_workspace

build_sim_cfg(args)	Build a SimulationManagerCfg from CLI arguments.
build_robot_cfg(args)	Build a RobotCfg from either a URDF/USD asset or a predefined robot.
build_preset_robot_cfg(args)	Build a RobotCfg from a predefined EmbodiChain robot preset.
build_analyzer_config(args, control_part_name)	Build a WorkspaceAnalyzerConfig from CLI arguments.
preview_cache(args, analyzer)	Visualize cached workspace data beside its robot in EmbodiChain.
parse_args([argv])	Parse workspace-analysis CLI arguments.
main(args)	Run the workspace analysis end-to-end.
cli([argv])	Command-line interface for workspace analysis.

embodichain.lab.scripts.preview_asset

build_sim_cfg(args)	Build a SimulationManagerCfg from CLI arguments.
cli([argv])	Command-line interface for asset preview.
load_assets(sim, args)	Load one or more assets into the simulation.
main(args)	Orchestrate: create simulation, load asset, optionally preview, destroy.
preview(sim, assets[, joint_controller])	Enter interactive preview mode.

embodichain.lab.scripts.preview_joint_control

ArticulationPreviewController

Expose scalar articulation joints and hold commanded preview poses.

embodichain.lab.scripts.preview_lerobot_data

EpisodePreview	Human-readable episode summary and validation result.
SegmentPreview	Summary of one contiguous demonstration segment.
build_episode_preview(*, dataset_root, info, ...)	Build and validate a preview from already loaded LeRobot samples.
cli([argv])	Run the preview through the unified embodichain CLI.
inspect_dataset(dataset_root, *[, ...])	Load one episode through LeRobot and return its validated preview.
main([argv])	Run the preview CLI and return a process exit code.
resolve_dataset_root(path, *[, latest])	Resolve a dataset root, optionally selecting the newest child dataset.

embodichain.lab.scripts.run_env

cli([argv])	Command-line interface for environment runner.
generate_and_execute_action_list(env, idx, ...)	Execute one legacy planner result through the common episode executor.
generate_function(env[, num_traj, time_id, ...])	Generate, execute, and commit one demonstration collection batch.
main(args, env, gym_config)	Run the selected workflow without taking ownership of env.
preview(env)	Run the following code to create a demonstration and perform env steps.

embodichain.lab.sim

VisualMaterialCfg	Configuration for visual material with PBR properties for rasterization and ray tracing.
VisualMaterial	Visual material definition in the simulation environment.
VisualMaterialInst	Instance of a visual material in the simulation environment.
ReuseSegmentState	Reuse state for one render-body segment of a parsed object.
BatchEntity	Abstract base class for batch entity in the simulation engine.
SimulationManager	Global Embodied AI simulation manager.
SimulationManagerCfg	Global robot simulation configuration.
SIM_CACHE_DIR	Path subclass for non-Windows systems.
MATERIAL_CACHE_DIR	Path subclass for non-Windows systems.
CONVEX_DECOMP_DIR	Path subclass for non-Windows systems.
REACHABLE_XPOS_DIR	Path subclass for non-Windows systems.

embodichain.lab.sim.atomic_actions

ActionPlanningServices	Engine-scoped registry of planning services used by atomic actions.
Affordance	Base class for affordance data.
AntipodalAffordance	Antipodal grasp affordance for parallel-jaw grippers.
AssembleAffordance	Affordance describing how an assemble object fits onto a base object.
BUILTIN_ACTION_TYPES	Built-in immutable sequence.
CoordinatedPickmentOptions	Per-invocation coordinated pickup behavior.
CoordinatedPlacementOptions	Per-invocation coordinated placement behavior.
DynamicCollisionMode	Policy for consuming a live dynamic collision world.
EntityState	Scene entity state addressable by a stable entity identifier.
EffectVerifier	alias of Callable[[PlanningContext, EffectVerificationRequest], EffectVerificationResult]
GRASP_COMMAND	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
HandOverOptions	Per-invocation pick-up, handover, and placement behavior.
InteractionPoints	Batch of 3D interaction points on an object surface.
MoveEndEffectorOptions	Per-invocation behavior for MoveEndEffector.
MoveHeldObjectOptions	Per-invocation held-object transport behavior.
MoveJointsOptions	Per-invocation behavior for MoveJoints.
ObjectActionGoal	Shared semantic-object goal contract for object-centric skills.
OPEN_COMMAND	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
PickUpOptions	Per-invocation pickup behavior.
PlaceOptions	Per-invocation placement behavior.
PoseGoalValue	Represent a PEP 604 union type
PushObject	Close the end effector, contact a rigid object, and push it in-plane.
PushObjectGoal	Push one rigid object toward a target pose on the target support plane.
PushObjectOptions	Per-invocation planar pushing behavior.
PushObjectToolCalibration	End-effector calibration selected by a bound motion control part.
RigidObjectSceneProvider	Observe simulation rigid objects and maintain scene revisions.
RigidObjectSceneProviderCfg	Material-pose thresholds used to advance scene revisions.
RunnerStepCallback	alias of Callable[[RunnerStep], None]
SceneProvider	Produce scene snapshots correlated with execution environments.
SceneSnapshotSupplier	alias of Callable[[float], SceneSnapshot]

embodichain.lab.sim.atomic_actions.affordance

Affordance	Base class for affordance data.
AntipodalAffordance	Antipodal grasp affordance for parallel-jaw grippers.
AxisAlignAffordance	Antipodal grasp affordance with an object-local alignment axis.
SlideAffordance	Target-local antipodal grasp and parent-joint translation geometry.
PressAffordance	Target-local contact point and parent-joint pressing geometry.
TwistAffordance	Target-local grasp point and parent-joint rotation geometry.
InteractionPoints	Batch of 3D interaction points on an object surface.
AssembleAffordance	Affordance describing how an assemble object fits onto a base object.

Classes:

Affordance	Base class for affordance data.
AntipodalAffordance	Antipodal grasp affordance for parallel-jaw grippers.
AssembleAffordance	Affordance describing how an assemble object fits onto a base object.
AxisAlignAffordance	Antipodal grasp affordance with an object-local alignment axis.
InteractionPoints	Batch of 3D interaction points on an object surface.
OpenDoorAffordance	Target-local handle geometry and a resolved hinge axis.
PressAffordance	Target-local contact point and parent-joint pressing geometry.
SlideAffordance	Target-local antipodal grasp and parent-joint translation geometry.
TwistAffordance	Target-local grasp point and parent-joint rotation geometry.

class embodichain.lab.sim.atomic_actions.affordance.Affordance

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.
resolve_from_object_geometry(geometry)	Resolve geometry-derived fields after object semantics are assembled.
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()

Return the batch size of this affordance data.

Return type:

int

get_custom_config(key, default=None)

Get a custom affordance configuration value.

Return type:

Any

object_label: str = ''

Label of the object this affordance belongs to.

resolve_from_object_geometry(geometry)

Resolve geometry-derived fields after object semantics are assembled.

Subclasses may override this hook when their derived semantic values require metadata owned by ObjectSemantics.geometry.

Parameters:

geometry (Mapping[str, Any]) – Non-affordance object geometry metadata.

Return type:

None

set_custom_config(key, value)

Set a custom affordance configuration value.

Return type:

None

class embodichain.lab.sim.atomic_actions.affordance.AntipodalAffordance

Antipodal grasp affordance for parallel-jaw grippers.

The affordance owns only target-local triangle-mesh data. Simulator entity handles and live poses belong to scene grounding, not semantic geometry.

Attributes:

MAX_SURFACE_POINT_COUNT	Maximum point-cloud size used for geometry-distribution analysis.
custom_config	User-defined configuration payload.
mesh_triangles	Object mesh triangle indices, shape [M, 3].
mesh_vertices	Object mesh vertices, shape [N, 3].

Methods:

__init__([object_label, custom_config, ...])
get_object_longest_axis(obj_poses, *[, ...])	Return the widest surface-point distribution axis in world space.
sample_surface_points([max_points])	Deterministically sample target-local mesh-surface points.

MAX_SURFACE_POINT_COUNT: ClassVar[int] = 1000

Maximum point-cloud size used for geometry-distribution analysis.

__init__(object_label='', custom_config=<factory>, mesh_vertices=None, mesh_triangles=None)

custom_config: dict[str, Any]

User-defined configuration payload.

get_object_longest_axis(obj_poses, *, max_points=1000)

Return the widest surface-point distribution axis in world space.

Return type:

Tensor

mesh_triangles: Tensor | None = None

Object mesh triangle indices, shape [M, 3].

mesh_vertices: Tensor | None = None

Object mesh vertices, shape [N, 3].

sample_surface_points(max_points=1000)

Deterministically sample target-local mesh-surface points.

Parameters:

max_points (int) – Requested point cap in [1, 1000].

Return type:

Tensor

Returns:

Target-local surface points with shape (N, 3).

class embodichain.lab.sim.atomic_actions.affordance.AssembleAffordance

Affordance describing how an assemble object fits onto a base object.

The affordance stores the relative assembly relation. Planning supplies the base object’s snapshot pose through AssembleGoal.base_pose. The assemble object’s target pose is base_pose @ assemble_to_base_pose.

Methods:

__init__([object_label, custom_config, ...])
get_assemble_object_pose(base_pose)	Return the assemble-object target pose for a given base-object pose.

Attributes:

assemble_to_base_pose	Pose of the assemble object relative to the base object frame, shape (4, 4) or (num_envs, 4, 4).
custom_config	User-defined configuration payload.

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

assemble_to_base_pose: Tensor

Pose of the assemble object relative to the base object frame, shape (4, 4) or (num_envs, 4, 4).

custom_config: dict[str, Any]

User-defined configuration payload.

get_assemble_object_pose(base_pose)

Return the assemble-object target pose for a given base-object pose.

The assemble object is placed at base_pose @ assemble_to_base_pose.

Parameters:

base_pose (Tensor) – Base-object pose with shape (4, 4) or (num_envs, 4, 4).

Return type:

Tensor

Returns:

Assemble-object target pose with shape (num_envs, 4, 4).

Raises:

• TypeError – If either pose value is not a tensor.

• ValueError – If either pose has an unsupported shape or batch size.

class embodichain.lab.sim.atomic_actions.affordance.AxisAlignAffordance

Antipodal grasp affordance with an object-local alignment axis.

Methods:

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

Attributes:

custom_config	User-defined configuration payload.
internal_axis	Axis expressed in the target object's local frame.

__init__(object_label='', custom_config=<factory>, mesh_vertices=None, mesh_triangles=None, internal_axis=<factory>)

custom_config: dict[str, Any]

User-defined configuration payload.

internal_axis: Tensor

Axis expressed in the target object’s local frame.

class embodichain.lab.sim.atomic_actions.affordance.InteractionPoints

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:

custom_config	User-defined configuration payload.
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)

Get recommended approach direction for a given point.

Return type:

Tensor

get_batch_size()

Return the number of interaction points in this affordance.

Return type:

int

get_points_by_type(point_type)

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.affordance.OpenDoorAffordance

Target-local handle geometry and a resolved hinge axis.

Use from_articulation() to start from a graspable handle link. The factory consumes the articulation’s public parent-joint chain, skips only fixed joints, and automatically accepts one unambiguous active revolute ancestor. Ambiguous mechanisms require an explicit hinge joint name. The resulting affordance owns no simulator entity or live pose.

Methods:

__init__([object_label, custom_config, ...])
from_articulation(articulation, link_name, *)	Build handle semantics from a parent revolute joint.

Attributes:

axis_origin	Resolved point on the hinge axis in the handle-link frame.
custom_config	User-defined configuration payload.
joint_limits	Optional lower and upper hinge limits in radians.
joint_name	Stable name of the resolved parent revolute joint.
opening_direction	Joint-coordinate direction from the closed limit toward the open limit.
rotation_axis	Resolved hinge axis expressed in the handle-link frame.

__init__(object_label='', custom_config=<factory>, joint_limits=None, opening_direction=1, *, mesh_vertices, mesh_triangles, rotation_axis, axis_origin, joint_name)

axis_origin: tuple[float, float, float]

Resolved point on the hinge axis in the handle-link frame.

custom_config: dict[str, Any]

User-defined configuration payload.

classmethod from_articulation(articulation, link_name, *, hinge_joint_name=None, opening_direction=1)

Build handle semantics from a parent revolute joint.

Automatic resolution skips only fixed joints. It succeeds when the handle chain contains exactly one active ancestor and that joint is revolute. A chain with multiple active ancestors can represent a latch, handle joint, or another mechanism and therefore requires an explicit hinge_joint_name. Hinge geometry is converted from the joint frame into the requested handle-link frame using current public link poses.

Parameters:

• articulation (Articulation) – Articulation containing the graspable handle link.

• link_name (str) – Graspable handle link from which to start the traversal.

• hinge_joint_name (str | None) – Optional explicit revolute ancestor. Required when more than one active ancestor makes automatic resolution ambiguous.

• opening_direction (int) – Joint-coordinate direction from the closed legal endpoint toward the open endpoint. Defaults to increasing qpos.

Return type:

OpenDoorAffordance

Returns:

Pure target-local handle and hinge semantics.

Raises:

• TypeError – If a supplied name is not a string.

• ValueError – If the link or explicit joint is unknown, automatic resolution is ambiguous, the selected joint is not revolute, or the resolved joint geometry is invalid.

joint_limits: tuple[float, float] | None = None

Optional lower and upper hinge limits in radians.

joint_name: str

Stable name of the resolved parent revolute joint.

opening_direction: int = 1

Joint-coordinate direction from the closed limit toward the open limit.

rotation_axis: Tensor

Resolved hinge axis expressed in the handle-link frame.

class embodichain.lab.sim.atomic_actions.affordance.PressAffordance

Target-local contact point and parent-joint pressing geometry.

Methods:

__init__([object_label, custom_config, ...])
get_press_pose(target_pose[, press_position])	Construct a press pose at the configured surface point.
resolve_from_object_geometry(geometry)	Resolve the target-local prismatic axis, sign, and contact point.

Attributes:

custom_config	User-defined configuration payload.
press_axis	Parent prismatic-joint axis, signed toward articulation geometry.
press_position	Local contact point; inferred from articulation geometry when omitted.

__init__(object_label='', custom_config=<factory>, press_axis=<factory>, *, press_position=None)

custom_config: dict[str, Any]

User-defined configuration payload.

get_press_pose(target_pose, press_position=None)

Construct a press pose at the configured surface point.

The end-effector z-axis follows press_axis in world space. An adaptive reference produces an orthonormal, right-handed frame.

Parameters:

• target_pose (Tensor) – Current target world pose with shape (B, 4, 4).

• press_position (tuple[float, float, float] | None) – Optional per-call exact local-frame press position. It overrides press_position.

Return type:

Tensor

Returns:

Batched world-frame press poses with shape (B, 4, 4).

Raises:

ValueError – If an input has an invalid shape or value.

press_axis: Tensor

Parent prismatic-joint axis, signed toward articulation geometry.

press_position: tuple[float, float, float] | None = None

Local contact point; inferred from articulation geometry when omitted.

resolve_from_object_geometry(geometry)

Resolve the target-local prismatic axis, sign, and contact point.

Return type:

None

class embodichain.lab.sim.atomic_actions.affordance.SlideAffordance

Target-local antipodal grasp and parent-joint translation geometry.

The positive translation-axis direction denotes approaching and pushing the articulated part closed. Pulling moves in the opposite direction. The mesh describes the actual graspable contact surface. The target pose is supplied separately by SceneEntityPose or a pose snapshot.

Methods:

__init__([object_label, custom_config, ...])
resolve_from_object_geometry(geometry)	Resolve the target-local prismatic axis and neighborhood sign.

Attributes:

custom_config	User-defined configuration payload.
joint_limits	Optional lower and upper translation limits in metres.
joint_name	Optional stable prismatic-joint name associated with the link.
translation_axis	Parent prismatic-joint axis, signed toward articulation geometry.

__init__(object_label='', custom_config=<factory>, translation_axis=<factory>, joint_name=None, joint_limits=None, *, mesh_vertices, mesh_triangles)

custom_config: dict[str, Any]

User-defined configuration payload.

joint_limits: tuple[float, float] | None = None

Optional lower and upper translation limits in metres.

joint_name: str | None = None

Optional stable prismatic-joint name associated with the link.

resolve_from_object_geometry(geometry)

Resolve the target-local prismatic axis and neighborhood sign.

Return type:

None

translation_axis: Tensor

Parent prismatic-joint axis, signed toward articulation geometry.

class embodichain.lab.sim.atomic_actions.affordance.TwistAffordance

Target-local grasp point and parent-joint rotation geometry.

Methods:

__init__([object_label, custom_config, ...])
get_grasp_pose(target_pose)	Construct a deterministic world grasp pose from local geometry.
require_axis_origin()	Return the explicit or geometry-derived local rotation-axis point.
resolve_from_object_geometry(geometry)	Resolve the target-local revolute axis, sign, and joint origin.

Attributes:

axis_origin	Fallback axis point, overridden by revolute-joint origin metadata.
custom_config	User-defined configuration payload.
grasp_position	Explicit target-local center of the gripper contact region.
joint_limits	Optional lower and upper angular limits in radians.
joint_name	Optional stable articulation-joint name associated with the axis.
twist_axis	Parent revolute-joint axis, signed toward articulation geometry.

__init__(object_label='', custom_config=<factory>, twist_axis=<factory>, joint_name=None, joint_limits=None, *, grasp_position, axis_origin=None)

axis_origin: tuple[float, float, float] | None = None

Fallback axis point, overridden by revolute-joint origin metadata.

custom_config: dict[str, Any]

User-defined configuration payload.

get_grasp_pose(target_pose)

Construct a deterministic world grasp pose from local geometry.

The pose z-axis follows twist_axis. The remaining axes are formed with an adaptive reference so the result is always in SO(3).

Return type:

Tensor

Returns:

Batched world-frame grasp poses with shape (B, 4, 4).

Raises:

ValueError – If target_pose is not a batched pose tensor.

grasp_position: tuple[float, float, float]

Explicit target-local center of the gripper contact region.

joint_limits: tuple[float, float] | None = None

Optional lower and upper angular limits in radians.

joint_name: str | None = None

Optional stable articulation-joint name associated with the axis.

require_axis_origin()

Return the explicit or geometry-derived local rotation-axis point.

Return type:

tuple[float, float, float]

Returns:

Resolved target-local rotation-axis origin.

Raises:

ValueError – If neither a fallback nor articulation geometry supplied the rotation-axis origin.

resolve_from_object_geometry(geometry)

Resolve the target-local revolute axis, sign, and joint origin.

Return type:

None

twist_axis: Tensor

Parent revolute-joint axis, signed toward articulation geometry.

embodichain.lab.sim.atomic_actions.bindings

ActionBinding	Engine-owned generic endpoint bindings for one atomic action call.
EndpointBinding	One action-local endpoint resolved to a runtime controller target.
JointPositionTarget	Joint-position destination backed by one robot control part.
RuntimeEndpointTarget	Stable controller destination produced by an endpoint adapter.

embodichain.lab.sim.atomic_actions.control

ActionControlOverrides	Per-invocation semantic commands keyed by slot and endpoint.
ControlCommand	Immutable-by-ownership command associated with one control part.
ControlPartCommandProfile	Reusable semantic commands for one named robot control part.
GRASP_COMMAND	Conventional semantic command for an object-holding end effector.
JointPositionCommand	A semantic command represented by one or batched joint positions.
OPEN_COMMAND	Conventional semantic command for an open end effector.

embodichain.lab.sim.atomic_actions.core

AtomicAction	Side-effect-free planner for one semantically meaningful robot skill.
ObjectSemantics	Shallow-frozen semantic information about an interaction object.
SkillDescriptor	Machine-readable metadata for one registered atomic skill.
resolve_runtime_device(device)	Resolve an indexless CUDA device to the active concrete GPU index.

embodichain.lab.sim.atomic_actions.effects

StateDelta

Expected task-state changes that require post-execution verification.

embodichain.lab.sim.atomic_actions.engine

AtomicActionEngine

Own planning resources and coordinate side-effect-free atomic actions.

embodichain.lab.sim.atomic_actions.execution

ExecutionEvent	One timestamped execution or recovery event.
ExecutionEventKind	Structured event categories emitted by ExecutionSession.tick().
ExecutionPlanAttempt	Owned inspection snapshot for one installed action plan.
ExecutionSession	Execute grounded invocations incrementally with bounded local recovery.
ExecutionStatus	Lifecycle status of an execution session.
ExecutionTick	Result returned after one closed-loop execution update.

embodichain.lab.sim.atomic_actions.verification

EffectExpectationResult	Current-observation outcome for one physical state expectation.
EffectVerificationRequest	Typed boundary describing a physical effect awaiting verification.
EffectVerificationResult	Correlated per-environment update for one effect boundary.
HeldObjectGuardRequest	Describe the next in-flight command boundary for held-object checks.
HeldObjectGuardResult	Correlated in-flight held-object loss and recovery decision.
PhaseEffectGateRequest	Correlate a blocking physical-effect check with a segment entry.
PhaseEffectGateResult	Current-observation decision for one blocking segment-entry gate.

embodichain.lab.sim.atomic_actions.goals

ObjectActionGoal	Shared semantic-object goal contract for object-centric skills.
PoseGoalValue	Explicit pose tensor or a pose resolved from the latest scene snapshot.
SceneEntityPose	Late-bound pose derived from a versioned scene entity.
collect_scene_dependencies(value)	Collect stable scene entity identifiers referenced by a goal value.
resolve_pose_goal(value, context, *, name)	Resolve a pose goal against a planning context.
validate_pose_goal(value, name, *, ...)	Validate an explicit or late-bound pose goal.
validate_pose_tensor(value, name, *, ...)	Validate the environment-independent part of a pose goal.

Goal contracts shared by atomic actions.

Classes:

ObjectActionGoal	Shared semantic-object goal contract for object-centric skills.
SceneEntityPose	Late-bound pose derived from a versioned scene entity.

Data:

PoseGoalValue

Explicit pose tensor or a pose resolved from the latest scene snapshot.

Functions:

collect_scene_dependencies(value)	Collect stable scene entity identifiers referenced by a goal value.
resolve_pose_goal(value, context, *, name)	Resolve a pose goal against a planning context.
validate_pose_goal(value, name, *, ...)	Validate an explicit or late-bound pose goal.
validate_pose_tensor(value, name, *, ...)	Validate the environment-independent part of a pose goal.

class embodichain.lab.sim.atomic_actions.goals.ObjectActionGoal

Shared semantic-object goal contract for object-centric skills.

Methods:

__init__(semantics)

Attributes:

semantics

Semantic and geometric description of the object.

__init__(semantics)

semantics: ObjectSemantics

Semantic and geometric description of the object.

embodichain.lab.sim.atomic_actions.goals.PoseGoalValue = torch.Tensor | embodichain.lab.sim.atomic_actions.goals.SceneEntityPose

Explicit pose tensor or a pose resolved from the latest scene snapshot.

class embodichain.lab.sim.atomic_actions.goals.SceneEntityPose

Late-bound pose derived from a versioned scene entity.

The semantic request remains stable while each call to AtomicAction.plan() resolves the latest scene pose. This is the bridge used by an execution session to replan moving goals.

Methods:

__init__(entity_id[, relative_pose, ...])
snapshot()	Return an independently owned late-bound pose value.

Attributes:

entity_id	Stable scene entity identifier.
minimum_confidence	Minimum accepted perception confidence.
relative_pose	Optional transform applied as entity_pose @ relative_pose.

__init__(entity_id, relative_pose=None, minimum_confidence=0.0)

entity_id: str

Stable scene entity identifier.

minimum_confidence: float

Minimum accepted perception confidence.

relative_pose: Tensor | None

Optional transform applied as entity_pose @ relative_pose.

snapshot()

Return an independently owned late-bound pose value.

Return type:

SceneEntityPose

Returns:

Exact scene reference with an owned relative-pose tensor.

embodichain.lab.sim.atomic_actions.goals.collect_scene_dependencies(value)

Collect stable scene entity identifiers referenced by a goal value.

Return type:

tuple[str, ...]

embodichain.lab.sim.atomic_actions.goals.resolve_pose_goal(value, context, *, name)

Resolve a pose goal against a planning context.

Parameters:

• value (Tensor | SceneEntityPose) – Explicit tensor or scene-entity reference.

• context (PlanningContext) – Latest observed planning context.

• name (str) – Field name used in validation errors.

Return type:

Tensor

Returns:

Explicit pose tensor. Scene references always return shape (B, 4, 4).

embodichain.lab.sim.atomic_actions.goals.validate_pose_goal(value, name, *, allow_waypoints)

Validate an explicit or late-bound pose goal.

Return type:

None

embodichain.lab.sim.atomic_actions.goals.validate_pose_tensor(value, name, *, allow_waypoints)

Validate the environment-independent part of a pose goal.

Parameters:

• value (Tensor) – Pose tensor to validate.

• name (str) – Field name used in validation errors.

• allow_waypoints (bool) – Whether a batched waypoint dimension is accepted.

Raises:

• TypeError – If value is not a tensor.

• ValueError – If the tensor shape is not a supported pose shape.

Return type:

None

embodichain.lab.sim.atomic_actions.invocation

ActionInvocation	One fully typed and endpoint-bound atomic skill request.
ActionOptions	Marker base for immutable, skill-specific runtime options.
GoalT	Type variable.
OptionsT	Type variable.
PhaseEffectGateRequirement	Require physical-effect evidence before one trajectory segment starts.
ResolvedActionRequest	Engine-owned immutable planning snapshot for one invocation revision.

embodichain.lab.sim.atomic_actions.plans

ActionPlan	Scene-bound planning result for one grounded atomic action invocation.
CompiledTrajectory	Offline compilation result for a sequence of action invocations.
EffectVerificationRequirement	Explicit physical-effect verification independent of symbolic state.
PlannerDiagnostics	Planner metadata retained for debugging and recovery decisions.
PlanningFailure	Stable planning-failure classification used by recovery policy.
TimedTrajectory	Full-robot joint trajectory with per-environment timing metadata.
TrajectorySegment	Named half-open waypoint range inside an action trajectory.
normalize_success_mask(success, *, num_envs, ...)	Normalize a scalar or batched success value to (num_envs,).

embodichain.lab.sim.atomic_actions.policies

DynamicCollisionMode	Policy for consuming a live dynamic collision world.
MotionPolicy	Immutable motion-generation policy for one action invocation.
RecoveryPolicy	Bounded local recovery policy used by the execution runtime.

embodichain.lab.sim.atomic_actions.primitives

BUILTIN_ACTION_TYPES

Built-in action implementations instantiated once per action engine.

embodichain.lab.sim.atomic_actions.requirements

BATCH_INVERSE_KINEMATICS_CAPABILITY	Capability for resolving batched inverse kinematics for an endpoint.
CARTESIAN_POSE_CAPABILITY	Capability for planning and executing Cartesian-pose motion.
DisjointResourceSlots	Require selected slots to have pairwise-disjoint physical claims.
DisjointSlotEndpoints	Require selected endpoints within one participant to be disjoint.
FORWARD_KINEMATICS_CAPABILITY	Capability for resolving forward kinematics for an endpoint.
GRASP_CAPABILITY	Capability for commanding a grasping end effector.
INVERSE_KINEMATICS_CAPABILITY	Capability for resolving inverse kinematics for an endpoint.
JOINT_POSITION_CAPABILITY	Capability for planning and executing joint-position motion.
SkillBindingContract	Complete robot-independent binding contract for one atomic skill.
SkillEndpointRequirement	Capabilities and commands required from one slot-local endpoint.
SkillResourceSlot	One skill-local participant selected as an indivisible resource unit.

embodichain.lab.sim.atomic_actions.runner

CommandAckStatus	Outcome reported by a command transport or controller.
CommandAcknowledgement	Synchronous acknowledgement returned by a CommandSink.
CommandDispatch	Auditable record of one controller operation and acknowledgement.
CommandOperation	Command-sink operation recorded by an execution runner.
CommandSink	Controller boundary used by ExecutionRunner.
EffectVerifier	Synchronous verifier called on a fresh due-cycle observation.
ExecutionClock	Clock abstraction used for deterministic and simulation scheduling.
ExecutionRunner	Connect an execution session to observation, controller, and time ports.
ExecutionRunnerCfg	Transport and scheduling policy for an ExecutionRunner.
HeldObjectGuardVerifier	Synchronous phase-aware held-object verifier for one due command cycle.
MonotonicExecutionClock	Wall-clock implementation backed by time.
ObservationProvider	Source of fresh planning contexts for feedback-driven execution.
PhaseEffectGateVerifier	Synchronous verifier for one blocking trajectory-segment entry gate.
RunnerStatus	Lifecycle status owned by an ExecutionRunner.
RunnerStep	Result of one non-blocking execution-runner update.
RunnerStepCallback	Optional observer called after every blocking runner-loop iteration.

embodichain.lab.sim.atomic_actions.runtime

ActionPlanningServices

Engine-scoped registry of planning services used by atomic actions.

embodichain.lab.sim.atomic_actions.runtime_commands

EndpointCommand	One transport-compatible payload addressed to one runtime target.
JointPositionPayload	Batched joint-position targets for the built-in robot transport.
RuntimeCommandFrame	Synchronized endpoint commands for one batched runtime instant.
RuntimeCommandPayload	Immutable-by-ownership payload submitted to one runtime transport.
TimedCommandSequence	Ordered runtime command frames for one stable environment batch.

embodichain.lab.sim.atomic_actions.scene

SceneProvider

Produce scene snapshots correlated with execution environments.

embodichain.lab.sim.atomic_actions.sim_adapter

create_simulation_atomic_action_engine(...)	Create an engine whose initial context observes selected rigid objects.
RigidObjectSceneProvider	Observe simulation rigid objects and maintain scene revisions.
RigidObjectSceneProviderCfg	Material-pose thresholds used to advance scene revisions.
SceneSnapshotSupplier	Callback that returns the latest scene snapshot for a simulation timestamp.
SimulationExecutionAdapter	Adapt a simulation robot to observation, command, and clock protocols.

embodichain.lab.sim.atomic_actions.state

EntityState	Scene entity state addressable by a stable entity identifier.
HeldObjectState	Observed or projected relation between an object and one manipulator.
PlanningContext	Complete side-effect-free input to AtomicAction.plan().
RobotObservation	Measured robot state used as the start of planning or replanning.
SceneSnapshot	Versioned scene state used to ground dynamic goals and obstacles.
TaskState	Symbolic task state, separate from measured robot state.

Observed robot state, symbolic task state, and scene snapshots.

Classes:

ArticulationJointState	Verified symbolic state for one named articulation joint.
CoordinatedHeldObjectState	Observed or projected relation for an object held by two manipulators.
EntityState	Scene entity state addressable by a stable entity identifier.
HeldObjectState	Observed or projected relation between an object and one manipulator.
ObservedArticulationJointState	Live measured state for one scene articulation joint.
PlanningContext	Complete side-effect-free input to AtomicAction.plan().
RobotObservation	Measured robot state used as the start of planning or replanning.
SceneSnapshot	Versioned scene state used to ground dynamic goals and obstacles.
TaskState	Symbolic task state, separate from measured robot state.

class embodichain.lab.sim.atomic_actions.state.ArticulationJointState

Verified symbolic state for one named articulation joint.

Methods:

__init__(position[, env_mask])

Attributes:

env_mask	Rows for which the verified state is present.
position	Joint positions with shape (J,) or (B, J).

__init__(position, env_mask=None)

env_mask: Tensor | None

Rows for which the verified state is present.

position: Tensor

Joint positions with shape (J,) or (B, J).

class embodichain.lab.sim.atomic_actions.state.CoordinatedHeldObjectState

Observed or projected relation for an object held by two manipulators.

Methods:

__init__(semantics, left_object_to_eef, ...)

__init__(semantics, left_object_to_eef, right_object_to_eef, left_grasp_xpos, right_grasp_xpos, env_mask=None)

class embodichain.lab.sim.atomic_actions.state.EntityState

Scene entity state addressable by a stable entity identifier.

Methods:

__init__(pose[, confidence])

__init__(pose, confidence=1.0)

class embodichain.lab.sim.atomic_actions.state.HeldObjectState

Observed or projected relation between an object and one manipulator.

Methods:

__init__(semantics, object_to_eef, grasp_xpos)

Attributes:

env_mask	Environments in which the relation is active.
grasp_xpos	End-effector grasp pose.
object_to_eef	Object-to-end-effector transform.
semantics	Semantics of the held object.

__init__(semantics, object_to_eef, grasp_xpos, env_mask=None)

env_mask: Tensor | None

Environments in which the relation is active.

grasp_xpos: Tensor

End-effector grasp pose.

object_to_eef: Tensor

Object-to-end-effector transform.

semantics: ObjectSemantics

Semantics of the held object.

class embodichain.lab.sim.atomic_actions.state.ObservedArticulationJointState

Live measured state for one scene articulation joint.

Methods:

__init__(position[, valid_mask])
snapshot()	Return an independently owned observation value.

Attributes:

position	Measured joint position with shape (J,) or (B, J).
valid_mask	Optional row-validity mask for a batched observation.

__init__(position, valid_mask=None)

position: Tensor

Measured joint position with shape (J,) or (B, J).

snapshot()

Return an independently owned observation value.

Return type:

ObservedArticulationJointState

valid_mask: Tensor | None

Optional row-validity mask for a batched observation.

class embodichain.lab.sim.atomic_actions.state.PlanningContext

Complete side-effect-free input to AtomicAction.plan().

Methods:

__init__(robot, task, scene, env_ids[, ...])
get_articulation_joint_state(...)	Return verified state for one canonical articulation joint.
get_coordinated_held_object(first_resource, ...)	Return a coordinated held-object relation, if any.
get_held_object(resource)	Return the object held by resource, if any.
project(*, qpos, task)	Create the hypothetical context used to compile a following action.
require_control_dt()	Return the explicit command period required for interpolation.

Attributes:

articulation_joints	Verified articulation-joint states.
batch_size	Number of environments in this planning request.
control_dt	Explicit command period used by action-owned interpolation.
coordinated_held_objects	Coordinated held-object relations.
held_objects	Single-resource held-object relations.
last_qpos	Measured joint positions used as the planning start state.

__init__(robot, task, scene, env_ids, control_dt=None)

property articulation_joints: Mapping[tuple[str, str], ArticulationJointState]

Verified articulation-joint states.

property batch_size: int

Number of environments in this planning request.

control_dt: float | None

Explicit command period used by action-owned interpolation.

property coordinated_held_objects: Mapping[tuple[str, str], CoordinatedHeldObjectState]

Coordinated held-object relations.

get_articulation_joint_state(articulation_id, joint_id)

Return verified state for one canonical articulation joint.

Return type:

ArticulationJointState | None

get_coordinated_held_object(first_resource, second_resource)

Return a coordinated held-object relation, if any.

Return type:

CoordinatedHeldObjectState | None

get_held_object(resource)

Return the object held by resource, if any.

Return type:

HeldObjectState | None

property held_objects: Mapping[str, HeldObjectState]

Single-resource held-object relations.

property last_qpos: Tensor

Measured joint positions used as the planning start state.

project(*, qpos, task)

Create the hypothetical context used to compile a following action.

Parameters:

• qpos (Tensor) – Projected terminal joint positions.

• task (TaskState) – Task state after applying expected effects.

Return type:

PlanningContext

Returns:

New context. No measured state or simulator state is mutated.

require_control_dt()

Return the explicit command period required for interpolation.

Raises:

ValueError – If the caller did not provide control_dt.

Return type:

float

class embodichain.lab.sim.atomic_actions.state.RobotObservation

Measured robot state used as the start of planning or replanning.

Methods:

__init__(timestamp, qpos, qvel[, qeffort, ...])
with_qpos(qpos)	Create a projected observation with a new position and zero velocity.

Attributes:

batch_size	Number of represented vectorized environments.
robot_dof	Number of robot joint-position columns.

__init__(timestamp, qpos, qvel, qeffort=None, root_pose=None, root_twist=None)

property batch_size: int

Number of represented vectorized environments.

property robot_dof: int

Number of robot joint-position columns.

with_qpos(qpos)

Create a projected observation with a new position and zero velocity.

Parameters:

qpos (Tensor) – Projected joint positions with the same shape as this observation.

Return type:

RobotObservation

Returns:

New observation suitable for compiling the next action.

class embodichain.lab.sim.atomic_actions.state.SceneSnapshot

Versioned scene state used to ground dynamic goals and obstacles.

Methods:

__init__(timestamp, version[, entities, ...])
collision_obstacle_poses(*, batch_size, ...)	Return collision obstacle poses in planning batch order.
collision_world_revisions(batch_size)	Expand the collision revision to one value per environment.
empty()	Create an empty initial scene snapshot.
get_articulation_joint_state(...)	Return an owned live joint observation for a canonical address.

Attributes:

articulation_joints	Live physical joint observations keyed by articulation and joint ID.
collision_entity_ids	Entity IDs whose poses update a planner's dynamic collision world.
collision_world_revision	Global or per-environment collision-world revision.

__init__(timestamp, version, entities=<factory>, collision_world_revision=0, collision_entity_ids=(), articulation_joints=<factory>)

articulation_joints: Mapping[tuple[str, str], ObservedArticulationJointState]

Live physical joint observations keyed by articulation and joint ID.

collision_entity_ids: tuple[str, ...]

Entity IDs whose poses update a planner’s dynamic collision world.

collision_obstacle_poses(*, batch_size, device, dtype)

Return collision obstacle poses in planning batch order.

Parameters:

• batch_size (int) – Number of planning environments.

• device (device) – Planner tensor device.

• dtype (dtype) – Planner tensor dtype.

Return type:

Mapping[str, Tensor]

Returns:

Mapping from configured collision entity ID to (B, 4, 4) pose.

collision_world_revision: int | tuple[int, ...]

Global or per-environment collision-world revision.

collision_world_revisions(batch_size)

Expand the collision revision to one value per environment.

Parameters:

batch_size (int) – Number of environments represented by the planning context.

Return type:

tuple[int, ...]

Returns:

Per-environment monotonic revision tuple.

Raises:

ValueError – If an explicit revision tuple does not match the batch.

classmethod empty()

Create an empty initial scene snapshot.

Return type:

SceneSnapshot

get_articulation_joint_state(articulation_id, joint_id)

Return an owned live joint observation for a canonical address.

Return type:

ObservedArticulationJointState | None

class embodichain.lab.sim.atomic_actions.state.TaskState

Symbolic task state, separate from measured robot state.

Methods:

__init__(batch_size, device[, held_objects, ...])
empty(batch_size, device)	Create an empty symbolic state.
exclusive_held_object_mask(resource)	Return environments where only resource holds its object.
get_articulation_joint_state(...)	Return verified state for one canonical articulation joint.
get_coordinated_held_object(first_resource, ...)	Return the relation for an ordered resource pair, if any.
get_held_object(resource)	Return the object held by resource, if any.
held_object_mask(resource)	Return environments where resource holds an object.

Attributes:

articulation_joints	Verified articulation states keyed by canonical articulation and joint IDs.
batch_size	Number of vectorized environments represented by the state.
coordinated_held_objects	Coordinated relations keyed by ordered logical task-state resource pairs.
device	Device used by per-environment masks and relation tensors.
held_objects	Single-manipulator held-object relations keyed by control resource.

__init__(batch_size, device, held_objects=<factory>, coordinated_held_objects=<factory>, articulation_joints=<factory>)

articulation_joints: Mapping[tuple[str, str], ArticulationJointState]

Verified articulation states keyed by canonical articulation and joint IDs.

batch_size: int

Number of vectorized environments represented by the state.

coordinated_held_objects: Mapping[tuple[str, str], CoordinatedHeldObjectState]

Coordinated relations keyed by ordered logical task-state resource pairs.

device: device | str

Device used by per-environment masks and relation tensors.

classmethod empty(batch_size, device)

Create an empty symbolic state.

Parameters:

• batch_size (int) – Number of represented environments.

• device (device | str) – Tensor device used by the state.

Return type:

TaskState

Returns:

Empty task state with explicit batch metadata.

exclusive_held_object_mask(resource)

Return environments where only resource holds its object.

Object identity is established by the exact semantic record or by a shared non-null simulation entity. Labels and structural equality are deliberately ignored because distinct physical objects may look alike.

Parameters:

resource (str) – Manipulator control-resource name.

Return type:

Tensor

Returns:

Owned boolean mask with shape (batch_size,).

get_articulation_joint_state(articulation_id, joint_id)

Return verified state for one canonical articulation joint.

Return type:

ArticulationJointState | None

get_coordinated_held_object(first_resource, second_resource)

Return the relation for an ordered resource pair, if any.

Return type:

CoordinatedHeldObjectState | None

get_held_object(resource)

Return the object held by resource, if any.

Return type:

HeldObjectState | None

held_object_mask(resource)

Return environments where resource holds an object.

Parameters:

resource (str) – Manipulator control-resource name.

Return type:

Tensor

Returns:

Owned boolean mask with shape (batch_size,). Missing resources produce an all-false mask.

held_objects: Mapping[str, HeldObjectState]

Single-manipulator held-object relations keyed by control resource.

embodichain.lab.sim.atomic_actions.trajectory_ops

axis_translation_keyframes(start_pose, ...)	Build exact Cartesian translation targets along one world-space axis.
build_joint_plan_states(target_qpos)	Convert batched joint targets into the planner's waypoint representation.
build_pose_plan_states(target_poses)	Convert batched pose targets into the planner's waypoint representation.
interpolate_hand_qpos(start_hand_qpos, ...)	Interpolate hand joint positions between two semantic commands.
interpolate_joint_trajectory(start_qpos, ...)	Interpolate a joint path through one or more exact target waypoints.
resolve_joint_target(target_qpos, *, ...)	Validate and copy a joint target onto the planning device.
resolve_pose_target(target, *, num_envs, device)	Validate and copy an end-effector target onto the planning device.
split_three_segments(sample_count, ...[, ...])	Split a sample budget into motion, hand, and motion segments.
to_full_robot_trajectory(result, *, ...)	Embed a controlled-joint plan into a timed full-robot trajectory.
translate_pose_world(pose, offset)	Translate batched poses by a world-frame offset.

embodichain.lab.sim.atomic_actions.transports

EndpointCommandRouter	Route generic endpoint operations to exact registered transports.
EndpointCommandTransport	Backend that owns one kind of runtime endpoint command.

embodichain.lab.sim.objects.articulation

ArticulationData	GPU data manager for articulation.
Articulation	Articulation represents a batch of articulations in the simulation.
ArticulationJointKinematics	Backend-neutral kinematic description of one articulation joint.

embodichain.lab.sim.objects.cloth_object

ClothBodyData	Data manager for cloth.
ClothObject	ClothObject represents a batch of cloth body in the simulation.
ClothObjectCfg	Configuration for a cloth body asset in the simulation.

embodichain.lab.sim.objects.constraint

RigidConstraint

Batch of fixed constraints linking two RigidObject instances.

embodichain.lab.sim.objects.gizmo

Native robot targets use DexSim’s controller with Newton IK by default. Set GizmoCfg.ik_solver="embodichain" to reuse the robot control part’s configured solver, including PinkSolver; Viser uses the same solver adapter.

Gizmo	Manage native robot IK or Viser control for one simulation target.
GizmoCfg	Configure Gizmo appearance and native or Viser robot IK behavior.
create_robot_ik_gizmo_controller(robot[, ...])	Create DexSim's native IK controller for one EmbodiChain control part.

embodichain.lab.sim.objects.rigid_object

RigidBodyData	Data manager for rigid body with body type of dynamic or kinematic.
RigidObject	RigidObject represents a batch of rigid body in the simulation.
RigidObjectCfg	Configuration for a rigid body asset in the simulation.

embodichain.lab.sim.objects.rigid_object_group

RigidBodyGroupData	Data manager for rigid body group with body type of dynamic or kinematic.
RigidObjectGroup	RigidObjectGroup represents a batch of rigid bodies in the simulation.
RigidObjectGroupCfg	Configuration for a rigid object group asset in the simulation.

embodichain.lab.sim.objects.robot

ControlGroup	Represents a group of controllable joints in a robot.
Robot	A class representing a batch of robots in the simulation environment.

embodichain.lab.sim.objects.soft_object

SoftBodyData	Data manager for soft body
SoftObject	SoftObject represents a batch of soft body in the simulation.
SoftObjectCfg	Configuration for a soft body asset in the simulation.

embodichain.lab.sim.motion.planners.base_planner

BasePlannerCfg	BasePlannerCfg(robot_uid: 'str' = <factory>, planner_type: 'str' = <factory>)
CollisionWorldInfo	Describe one planner's collision-world integration contract.
PlanOptions	PlanOptions()
BasePlanner	Base class for trajectory planners.
validate_plan_options([_func, options_cls])	Decorator (factory) that validates the options argument is a PlanOptions instance.

embodichain.lab.sim.motion.planners.curobo.curobo_planner

CuroboAutoGenCfg	Auto-generation of the cuRobo robot YAML from the robot's URDF.
CuroboPlanOptions	Per-plan options for CuroboPlanner.
CuroboPlanner	cuRobo V2 collision-aware motion-planning backend.
CuroboPlannerCfg	Configuration for the cuRobo V2 planner backend.
CuroboWorldCfg	Static collision-world configuration for the cuRobo backend.

embodichain.lab.sim.motion.planners.curobo.curobo_yaml

generate_curobo_robot_yaml(robot, ...[, ...])	Fit collision spheres to each robot link's mesh and write a cuRobo robot YAML.
generate_curobo_world_yaml(rigid_objects, ...)	Generate a cuRobo V2 scene (world) YAML from live RigidObject handles.

embodichain.lab.sim.motion.planners.neural_planner

NeuralPlanner	Neural motion planner based on an APG waypoint transformer policy.
NeuralPlannerCfg	NeuralPlannerCfg(robot_uid: 'str' = <factory>, planner_type: 'str' = <factory>, checkpoint_path: 'str' = <factory>, control_part: 'str | None' = <factory>, max_steps: 'int | None' = <factory>, action_scale: 'float' = <factory>, num_arm_joints: 'int' = <factory>, pos_eps: 'float | None' = <factory>, rot_eps: 'float | None' = <factory>, dt: 'float' = <factory>)
NeuralPlanOptions	NeuralPlanOptions(control_part: 'str | None' = <factory>, start_qpos: 'torch.Tensor | None' = <factory>, max_steps: 'int | None' = <factory>)

embodichain.lab.sim.motion.planners.toppra_planner

ToppraPlanner	Time-optimal joint-space planner backed by TOPPRA.
ToppraPlannerCfg	ToppraPlannerCfg(robot_uid: 'str' = <factory>, planner_type: 'str' = <factory>, max_workers: 'int | None' = <factory>, mp_context: 'str | None' = <factory>)
ToppraPlanOptions	ToppraPlanOptions(constraints: 'dict' = <factory>, sample_method: 'TrajectorySampleMethod' = <factory>, sample_interval: 'float | int' = <factory>)

embodichain.lab.sim.motion.planners.utils

TrajectorySampleMethod	Enumeration for different trajectory sampling methods.
MovePart	Enumeration for different robot parts to move.
MoveType	Enumeration for different types of movements.
PlanState	Data class representing the state for a motion plan (env-batched).
PlanResult	Data class representing the result of a motion plan (env-batched).
normalize_success_mask(success, *, num_envs, ...)	Normalize a scalar or batched success value to (num_envs,).
calculate_point_allocations(xpos_list[, ...])	Calculate interpolation points for each segment with vectorized tensor ops.
interpolate_xpos(current_xpos, target_xpos, ...)	Interpolate between two poses using vectorized Slerp + linear translation.
interpolate_xpos_batched(start_xpos, ...)	Batched pose interpolation.

embodichain.lab.sim.robots.cobotmagic

CobotMagicCfg

CobotMagicCfg(uid: 'str | None' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'np.ndarray | None' = <factory>, fpath: 'str' = <factory>, drive_pros: 'JointDrivePropertiesCfg' = <factory>, body_scale: 'tuple | list' = <factory>, attrs: 'RigidBodyAttributesCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, fix_base: 'bool' = <factory>, disable_self_collision: 'bool' = <factory>, enable_gravity: 'bool' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None' = <factory>, sleep_threshold: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>, build_pk_chain: 'bool' = <factory>, compute_uv: 'bool' = <factory>, use_usd_properties: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg' = <factory>, solver_cfg: "Dict[str, 'SolverCfg'] | None" = <factory>, workspace_cfg: 'Dict[str, RobotWorkspaceCfg] | None' = <factory>)

embodichain.lab.sim.robots.dexforce_w1.hand_specs

W1HandSideSpec	Side-specific asset metadata for one hand release.
W1HandSpec	A hand release independent of the W1 body/arm version.
get_default_w1_hand_version(brand)	Return the explicitly selected default release for a hand brand.
get_w1_hand_spec(brand, version)	Return an explicitly registered hand release.
normalize_w1_hand_mappings([hand_types, ...])	Normalize optional side-keyed hand configuration mappings.

embodichain.lab.sim.robots.dexforce_w1.specs

W1VersionSpec	Asset layout and calibrated defaults belonging to one W1 revision.
get_w1_version_spec(version)

embodichain.lab.sim.robots.dexforce_w1.types

DexforceW1Version	Released version of the W1 robot body and arms.
DexforceW1HandVersion	Released version of an external W1 hand or gripper asset.
DexforceW1ArmSide	Arm side for DexforceW1: left or right.
DexforceW1Type	Component type for DexforceW1.
DexforceW1HandBrand

embodichain.lab.sim.robots.dexforce_w1.utils

ChassisManager
TorsoManager
HeadManager
ArmManager
HandManager
EyesManager
build_dexforce_w1_assembly_urdf_cfg([...])	Assemble DexforceW1 robot urdf configuration.

embodichain.lab.sim.robots.dual_arm

DualArmRobotCfg	Configuration for a dual-manipulator composed from a single-arm robot.
build_dual_arm_cfg(base_cfg, mounts, *[, ...])	Build a dual-arm cfg from a single-arm robot cfg.
resolve_mounts(mount_cfg)	Resolve a mount config into left/right 4x4 transforms.

embodichain.lab.sim.robots.franka_panda

FrankaPandaCfg

Configuration for the Franka Emika Panda robot with Panda hand.

embodichain.lab.sim.robots.ur_robot

URRobotCfg

Configuration for the UR family of robots.

embodichain.lab.sim.sensors.camera

Camera	Base class for sensor abstraction in the simulation engine.
CameraCfg	Configuration class for Camera.

embodichain.lab.sim.sim_manager

SIM_CACHE_DIR	Path subclass for non-Windows systems.
MATERIAL_CACHE_DIR	Path subclass for non-Windows systems.
CONVEX_DECOMP_DIR	Path subclass for non-Windows systems.
REACHABLE_XPOS_DIR	Path subclass for non-Windows systems.

embodichain.lab.task_program.semantics.calls

DeclarativeValue	Represent a PEP 604 union type
HandOver	Pick up, transfer, and place an object with two robot resources.
Pick	Pick one registered object using an optional explicit grasp affordance.
Place	Place a held object at exactly one semantic destination.
PlaceRelationTarget	Represent a PEP 604 union type
RegisteredSemanticCall	Safe value payload for a catalog-registered semantic extension.
SemanticCallCatalog	Immutable discovery catalog separated from engine installation.
SemanticCallDescriptor	Static catalog metadata for one semantic call kind.
SemanticCallSpec	Base value contract shared by every declarative semantic call.
SemanticPose	Object-space pose expressed as position and a WXYZ quaternion.
builtin_semantic_call_catalog()	Build the curated catalog for installed manipulation primitives.

Immutable, robot-independent semantic call specifications.

Classes:

HandOver	Pick up, transfer, and place an object with two robot resources.
Pick	Pick one registered object using an optional explicit grasp affordance.
Place	Place a held object at exactly one semantic destination.
RegisteredSemanticCall	Safe value payload for a catalog-registered semantic extension.
SemanticCallCatalog	Immutable discovery catalog separated from engine installation.
SemanticCallDescriptor	Static catalog metadata for one semantic call kind.
SemanticCallSpec	Base value contract shared by every declarative semantic call.
SemanticPose	Object-space pose expressed as position and a WXYZ quaternion.

Functions:

builtin_semantic_call_catalog()

Build the curated catalog for installed manipulation primitives.

class embodichain.lab.task_program.semantics.calls.HandOver

Pick up, transfer, and place an object with two robot resources.

Parameters:

• object (SceneObjectRef) – Authoritative scene-object reference. The object must not already be held when the unified action starts.

• final_target (SemanticPose | None) – Optional final object-space delivery pose.

• resources (Mapping[str, str]) – Optional skill-local resource overrides. Select the second candidate with the destination slot when needed.

Methods:

__init__(object[, final_target, resources])

__init__(object, final_target=None, *, resources=<factory>)

class embodichain.lab.task_program.semantics.calls.Pick

Pick one registered object using an optional explicit grasp affordance.

Parameters:

• object (SceneObjectRef) – Authoritative semantic object reference.

• grasp (SceneAffordanceRef | None) – Optional explicit grasp affordance. Omission requests deterministic registry selection.

• resources (Mapping[str, str]) – Optional skill-local resource overrides.

Methods:

__init__(object[, grasp, resources])

__init__(object, grasp=None, *, resources=<factory>)

class embodichain.lab.task_program.semantics.calls.Place

Place a held object at exactly one semantic destination.

Parameters:

• object (SceneObjectRef) – Authoritative held-object reference.

• at (SemanticPose | None) – Absolute object-space pose.

• on (SceneObjectRef | SceneAffordanceRef | None) – Object or affordance supporting an on relation.

• inside (SceneObjectRef | SceneAffordanceRef | None) – Object or affordance supporting an inside relation.

• resources (Mapping[str, str]) – Optional skill-local resource overrides.

Methods:

__init__(object[, at, on, inside, resources])

__init__(object, at=None, on=None, inside=None, *, resources=<factory>)

class embodichain.lab.task_program.semantics.calls.RegisteredSemanticCall

Safe value payload for a catalog-registered semantic extension.

Parameters:

• call_id (str) – Stable extension identifier discovered in a semantic catalog.

• arguments (Mapping[str, None | bool | int | float | str | SceneEntityRef | SemanticPose | tuple[None | bool | int | float | str | SceneEntityRef | SemanticPose | tuple[DeclarativeValue, ...] | Mapping[str, DeclarativeValue], ...] | Mapping[str, None | bool | int | float | str | SceneEntityRef | SemanticPose | tuple[DeclarativeValue, ...] | Mapping[str, DeclarativeValue]]]) – Nested declarative data. Executable or live values are rejected at construction.

• resources (Mapping[str, str]) – Optional skill-local resource overrides.

Methods:

__init__(call_id[, arguments, resources])

Attributes:

semantic_id

Return the registered extension identifier.

__init__(call_id, arguments=<factory>, *, resources=<factory>)

property semantic_id: str

Return the registered extension identifier.

class embodichain.lab.task_program.semantics.calls.SemanticCallCatalog

Immutable discovery catalog separated from engine installation.

Methods:

__init__(descriptors)
discover(call)	Discover metadata without installing or executing an implementation.
with_descriptor(descriptor)	Return a new catalog containing one additional descriptor.

Attributes:

descriptors

Return immutable descriptors keyed by exact semantic ID.

__init__(descriptors)

property descriptors: Mapping[str, SemanticCallDescriptor]

Return immutable descriptors keyed by exact semantic ID.

discover(call)

Discover metadata without installing or executing an implementation.

Parameters:

call (str | SemanticCallSpec) – Exact semantic ID or a call value.

Return type:

SemanticCallDescriptor

Returns:

Matching immutable descriptor.

Raises:

• KeyError – If the exact call ID is unknown.

• TypeError – If the call type disagrees with its descriptor.

with_descriptor(descriptor)

Return a new catalog containing one additional descriptor.

Return type:

SemanticCallCatalog

class embodichain.lab.task_program.semantics.calls.SemanticCallDescriptor

Static catalog metadata for one semantic call kind.

Parameters:

• call_id (str) – Stable semantic call identifier.

• spec_type (type[SemanticCallSpec]) – Exact public call value type.

• target_descriptor (SkillDescriptor | None) – Exact atomic goal/options/resource contract. It is inferred and non-overridable for curated calls and required for registered extensions.

Methods:

__init__(call_id, spec_type[, target_descriptor])

Attributes:

binding_contract	Return the resource contract from the canonical target descriptor.
skill_id	Return the atomic skill ID from the canonical target descriptor.

__init__(call_id, spec_type, target_descriptor=None)

property binding_contract: SkillBindingContract

Return the resource contract from the canonical target descriptor.

property skill_id: str

Return the atomic skill ID from the canonical target descriptor.

class embodichain.lab.task_program.semantics.calls.SemanticCallSpec

Base value contract shared by every declarative semantic call.

Parameters:

resources (Mapping[str, str]) – Optional skill-local slot to robot-resource overrides.

Methods:

__init__(*[, resources])
to_metadata()	Return this semantic call as deterministic JSON-safe data.

Attributes:

semantic_id

Return the stable catalog identifier for this call.

__init__(*, resources=<factory>)

property semantic_id: str

Return the stable catalog identifier for this call.

to_metadata()

Return this semantic call as deterministic JSON-safe data.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.calls.SemanticPose

Object-space pose expressed as position and a WXYZ quaternion.

The value owns normalized tensor snapshots and never exposes its internal tensors directly. A single pose or an environment batch is accepted.

Parameters:

• position (Tensor | tuple[float, float, float] | list[float]) – Shape (3,) or (B, 3).

• quaternion_wxyz (Tensor | tuple[float, float, float, float] | list[float]) – Shape (4,) or (B, 4). Finite, non-zero quaternions are normalized at construction.

Methods:

__init__(position, quaternion_wxyz)
snapshot()	Return an independently owned pose value.
to_matrix()	Convert the semantic pose to a homogeneous transform.
to_metadata()	Return the pose as deterministic JSON-safe semantic data.

Attributes:

batch_size	Return the explicit batch size, or None for one broadcast pose.
position	Return an independent position tensor.
quaternion_wxyz	Return an independent normalized quaternion tensor.

__init__(position, quaternion_wxyz)

property batch_size: int | None

Return the explicit batch size, or None for one broadcast pose.

property position: Tensor

Return an independent position tensor.

property quaternion_wxyz: Tensor

Return an independent normalized quaternion tensor.

snapshot()

Return an independently owned pose value.

Return type:

SemanticPose

to_matrix()

Convert the semantic pose to a homogeneous transform.

Return type:

Tensor

Returns:

Shape (4, 4) for an unbatched pose or (B, 4, 4) for a batched pose.

to_metadata()

Return the pose as deterministic JSON-safe semantic data.

Return type:

dict[str, object]

embodichain.lab.task_program.semantics.calls.builtin_semantic_call_catalog()

Build the curated catalog for installed manipulation primitives.

Return type:

SemanticCallCatalog

Returns:

A fresh immutable catalog. Atomic implementations remain uninstalled; callers bind them to an engine through the separate runtime path.

embodichain.lab.task_program.semantics.integration

BoundSemanticCall	Factory-owned call linked to one installed engine/profile combination.
LinkedSemanticCall	Provider-free static link result for one semantic call.
PathPart	Represent a PEP 604 union type
SceneEntityManifest	Provider-free static scene declaration using canonical registry metadata.
SceneManifest	Immutable provider-free scene catalog used before simulation starts.
SemanticDiagnostic	Structured deterministic semantic-integration diagnostic.
SemanticIntegrationManifest	Static scene/profile/catalog declaration validated before execution.
SemanticValidationError	Raise one structured error at a static or live integration boundary.

Two-phase static and live semantic integration validation.

Classes:

BoundSemanticCall	Factory-owned call linked to one installed engine/profile combination.
BoundSemanticIntegration	Live-installed, still side-effect-free semantic integration link.
LinkedSemanticCall	Provider-free static link result for one semantic call.
SceneEntityManifest	Provider-free static scene declaration using canonical registry metadata.
SceneManifest	Immutable provider-free scene catalog used before simulation starts.
SemanticDiagnostic	Structured deterministic semantic-integration diagnostic.
SemanticIntegrationManifest	Static scene/profile/catalog declaration validated before execution.

Exceptions:

SemanticValidationError

Raise one structured error at a static or live integration boundary.

class embodichain.lab.task_program.semantics.integration.BoundSemanticCall

Factory-owned call linked to one installed engine/profile combination.

Methods:

__init__(*args, **kwargs)

Reject construction outside BoundSemanticIntegration.

Attributes:

robot_profile

Return the exact bound profile that produced this call.

__init__(*args, **kwargs)

Reject construction outside BoundSemanticIntegration.

property robot_profile: BoundRobotSkillProfile

Return the exact bound profile that produced this call.

class embodichain.lab.task_program.semantics.integration.BoundSemanticIntegration

Live-installed, still side-effect-free semantic integration link.

Methods:

__init__(*, manifest, scene_registry, ...)
link_call(call, *[, path])	Resolve one call against exact installed skills, resources, and preset.

Attributes:

engine	Return the engine whose used call targets are validated at link time.
manifest	Return the static integration declaration.
robot_profile	Return the validated live robot profile.
scene_registry	Return the validated live scene registry.

__init__(*, manifest, scene_registry, robot_profile, engine)

property engine: AtomicActionEngine

Return the engine whose used call targets are validated at link time.

link_call(call, *, path=('call',))

Resolve one call against exact installed skills, resources, and preset.

Return type:

BoundSemanticCall

property manifest: SemanticIntegrationManifest

Return the static integration declaration.

property robot_profile: BoundRobotSkillProfile

Return the validated live robot profile.

property scene_registry: SceneRegistry

Return the validated live scene registry.

class embodichain.lab.task_program.semantics.integration.LinkedSemanticCall

Provider-free static link result for one semantic call.

Methods:

__init__(call, descriptor, preset_id[, ...])

__init__(call, descriptor, preset_id, affordances=<factory>)

class embodichain.lab.task_program.semantics.integration.SceneEntityManifest

Provider-free static scene declaration using canonical registry metadata.

Methods:

__init__(ref[, aliases, parent, ...])
from_metadata(metadata)	Copy one canonical provider-free registry metadata value.

__init__(ref, aliases=(), parent=None, native_name=None, dynamics=SceneDynamics.UNKNOWN, collision_role=SceneCollisionRole.NONE, semantic_type=None, affordance_capabilities=frozenset({}), default_affordances=<factory>, affordance_payload_type=None, affordance_revision=None, relative_pose=None)

classmethod from_metadata(metadata)

Copy one canonical provider-free registry metadata value.

Return type:

SceneEntityManifest

class embodichain.lab.task_program.semantics.integration.SceneManifest

Immutable provider-free scene catalog used before simulation starts.

Methods:

__init__([entries, collision_world_mode])
from_registry(registry)	Project a live registry without observing any dynamic provider.
lookup(identifier, *[, expected_type, path])	Return one static entry after canonical typed resolution.
resolve(identifier, *[, expected_type, path])	Resolve one canonical or alias reference with pathful diagnostics.
resolve_affordance(parent, *, capability[, ...])	Resolve one affordance using the same strict rule as SceneRegistry.
validate_registry(registry, *[, path])	Require a live registry to match this provider-free declaration.

Attributes:

entries

Return immutable provider-free entries in declaration order.

__init__(entries=(), *, collision_world_mode=None)

property entries: tuple[SceneEntityManifest, ...]

Return immutable provider-free entries in declaration order.

classmethod from_registry(registry)

Project a live registry without observing any dynamic provider.

Return type:

SceneManifest

lookup(identifier, *, expected_type=<class 'embodichain.lab.task_program.semantics.scene.SceneEntityRef'>, path=())

Return one static entry after canonical typed resolution.

Return type:

SceneEntityManifest

resolve(identifier, *, expected_type=<class 'embodichain.lab.task_program.semantics.scene.SceneEntityRef'>, path=())

Resolve one canonical or alias reference with pathful diagnostics.

Return type:

TypeVar(RefT, bound= SceneEntityRef)

resolve_affordance(parent, *, capability, explicit=None, path=())

Resolve one affordance using the same strict rule as SceneRegistry.

Return type:

SceneAffordanceRef

validate_registry(registry, *, path=('integration', 'scene_registry'))

Require a live registry to match this provider-free declaration.

Return type:

None

class embodichain.lab.task_program.semantics.integration.SemanticDiagnostic

Structured deterministic semantic-integration diagnostic.

Parameters:

• code (str) – Stable machine-readable failure code.

• path (tuple[str | int, ...]) – Complete configuration or program path.

• message (str) – Human-readable explanation.

• candidates (tuple[str, ...]) – Canonical candidate IDs, sorted when applicable.

Methods:

__init__(code, path, message[, candidates])

Attributes:

rendered_path

Return the path in dotted/indexed notation.

__init__(code, path, message, candidates=())

property rendered_path: str

Return the path in dotted/indexed notation.

class embodichain.lab.task_program.semantics.integration.SemanticIntegrationManifest

Static scene/profile/catalog declaration validated before execution.

Parameters:

• scene (SceneManifest) – Provider-free scene manifest.

• robot_profile (RobotSkillProfile) – Declarative robot resource/profile snapshot.

• call_catalog (SemanticCallCatalog) – Discoverable semantic call descriptors.

• runtime_preset (str | None) – Optional integration-wide policy preset override.

Methods:

__init__(scene, robot_profile, call_catalog)
bind(scene_registry, engine, *[, ...])	Validate live scene and robot bindings without observing or planning.
link_call(call, *[, path])	Resolve static refs, affordances, and declared resource structure.

__init__(scene, robot_profile, call_catalog, runtime_preset=None)

bind(scene_registry, engine, *, endpoint_adapters=None)

Validate live scene and robot bindings without observing or planning.

Return type:

BoundSemanticIntegration

link_call(call, *, path=('call',))

Resolve static refs, affordances, and declared resource structure.

This method never observes scene providers, constructs an engine, samples a grasp, or runs a planner.

Return type:

LinkedSemanticCall

exception embodichain.lab.task_program.semantics.integration.SemanticValidationError

Raise one structured error at a static or live integration boundary.

Methods:

__init__(diagnostic)

__init__(diagnostic)

embodichain.lab.task_program.semantics.effects

Backend-neutral semantic-effect contracts, evidence, and monitors.

Classes:

ArticulationJointStateExpectation	Symbolic articulation-joint postcondition.
BinaryEffectClause	Raw contact or constraint-state condition.
BinaryEffectEvidenceBatch	Raw per-row contact or constraint-state observations.
BinaryEvidenceKind	Raw boolean evidence channel.
CompositeEffectMonitor	Stateful conjunction monitor over typed physical evidence clauses.
CompositeEffectMonitorCfg	Strict hysteresis policy for typed pose/binary/scalar/joint clauses.
CompositeEffectMonitorFactory	Factory for the built-in typed-clause monitor.
ControlPartEvidenceAddress	Provider-neutral robot control-part observation address.
CoordinatedHeldObjectCleanupExpectation	Typed removal of one coordinated held-object relation.
EffectEvidenceAddress	Immutable observation address, deliberately separate from command targets.
EffectEvidenceSourceRef	Versioned provider route plus one immutable observation address.
EffectExpectationDecision	Per-row outcome for one physical state expectation.
EffectMonitor	Stateful verifier owned by one grounded semantic call.
EffectMonitorDecision	Uncorrelated aggregate and per-expectation monitor decision.
EffectMonitorFactory	Versioned constructor for independent semantic-effect monitors.
EffectMonitorRef	Versioned, declarative reference to an effect-monitor factory.
EffectMonitorRegistry	Immutable exact-ID/revision registry of monitor factories.
HeldObjectRelation	Expected symbolic held-object state at an effect boundary.
HeldObjectStateExpectation	Typed individual held-object postcondition.
JointStateEffectClause	Raw articulation/robot joint-position target condition.
JointStateEvidenceBatch	Raw per-row joint position/velocity observations.
PoseRelationClause	Object-to-endpoint pose condition with monitor-owned tolerances.
PoseRelationEvidenceBatch	Raw object-to-endpoint transform observations.
PoseRelationExpectation	Expected relationship to a grounded pose baseline.
ScalarEffectClause	Raw force/wrench magnitude condition with monitor-owned thresholds.
ScalarEffectEvidenceBatch	Raw per-row force or wrench-magnitude observations.
ScalarEvidenceKind	Raw scalar physical evidence channel.
ScalarExpectation	Expected high/low magnitude band for scalar evidence.
SemanticEffectKind	Trace-level semantic effect category; clause types define behavior.
SemanticEffectSpec	Grounded typed physical clauses and symbolic postconditions for one call.
SymbolicStateDomain	Typed mapping domains owned by TaskState.
SymbolicStateKey	Provider-free key for one exact symbolic TaskState write.

Data:

COMPOSITE_EFFECT_MONITOR_ID	Stable ID of the built-in typed-clause monitor.
COMPOSITE_EFFECT_MONITOR_REVISION	Exact behavior/configuration revision of the built-in monitor.
CONTROL_PART_EVIDENCE_PROVIDER_ID	Stable provider ID used by generic control-part evidence addresses.
CONTROL_PART_EVIDENCE_PROVIDER_REVISION	Exact contract revision of control-part evidence addresses.
EffectMonitorParam	Recursively immutable, non-executable monitor configuration value.

class embodichain.lab.task_program.semantics.effects.ArticulationJointStateExpectation

Symbolic articulation-joint postcondition.

Methods:

__init__(expectation_id, articulation_id, ...)
snapshot()	Return an independently owned articulation expectation.

__init__(expectation_id, articulation_id, joint_id, target_position)

snapshot()

Return an independently owned articulation expectation.

Return type:

ArticulationJointStateExpectation

class embodichain.lab.task_program.semantics.effects.BinaryEffectClause

Raw contact or constraint-state condition.

Methods:

__init__(clause_id, expectation_id, source, ...)
snapshot()	Return an independently owned binary clause.

__init__(clause_id, expectation_id, source, evidence_kind, expected)

snapshot()

Return an independently owned binary clause.

Return type:

BinaryEffectClause

class embodichain.lab.task_program.semantics.effects.BinaryEffectEvidenceBatch

Raw per-row contact or constraint-state observations.

Methods:

__init__(evidence_id, evidence_kind, values, ...)
snapshot()	Return an independently owned evidence batch.
to_metadata()	Return raw binary evidence as JSON-safe trace metadata.

__init__(evidence_id, evidence_kind, values, valid, acquisition_errors, timestamp, env_ids, observation_revision)

snapshot()

Return an independently owned evidence batch.

Return type:

BinaryEffectEvidenceBatch

to_metadata()

Return raw binary evidence as JSON-safe trace metadata.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.BinaryEvidenceKind

Raw boolean evidence channel.

Methods:

__new__(value)

__new__(value)

embodichain.lab.task_program.semantics.effects.COMPOSITE_EFFECT_MONITOR_ID = 'builtin.composite_effect'

Stable ID of the built-in typed-clause monitor.

embodichain.lab.task_program.semantics.effects.COMPOSITE_EFFECT_MONITOR_REVISION = '1'

Exact behavior/configuration revision of the built-in monitor.

embodichain.lab.task_program.semantics.effects.CONTROL_PART_EVIDENCE_PROVIDER_ID = 'builtin.control_part'

Stable provider ID used by generic control-part evidence addresses.

embodichain.lab.task_program.semantics.effects.CONTROL_PART_EVIDENCE_PROVIDER_REVISION = '1'

Exact contract revision of control-part evidence addresses.

class embodichain.lab.task_program.semantics.effects.CompositeEffectMonitor

Stateful conjunction monitor over typed physical evidence clauses.

Methods:

__init__(spec, cfg)
observe(request, evidence)	Update typed-clause hysteresis and decide current request rows.

Attributes:

resolved_params	Return all effective typed-clause thresholds, including defaults.
spec	Return an independently owned effect contract.

__init__(spec, cfg)

observe(request, evidence)

Update typed-clause hysteresis and decide current request rows.

Return type:

EffectMonitorDecision

property resolved_params: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[EffectMonitorParam, ...] | Mapping[str, EffectMonitorParam], ...] | Mapping[str, None | bool | int | float | str | tuple[EffectMonitorParam, ...] | Mapping[str, EffectMonitorParam]]]

Return all effective typed-clause thresholds, including defaults.

property spec: SemanticEffectSpec

Return an independently owned effect contract.

class embodichain.lab.task_program.semantics.effects.CompositeEffectMonitorCfg

Strict hysteresis policy for typed pose/binary/scalar/joint clauses.

Methods:

__init__([attached_translation_threshold, ...])
from_params(params)	Decode strict declarative factory parameters.
to_metadata()	Return every resolved hysteresis threshold as JSON-safe data.

__init__(attached_translation_threshold=0.02, attached_rotation_threshold=0.2, detached_translation_threshold=0.05, detached_rotation_threshold=0.5, force_absent_threshold=0.2, force_present_threshold=1.0, joint_success_tolerance=0.02, joint_failure_tolerance=0.1, consecutive_samples=2)

classmethod from_params(params)

Decode strict declarative factory parameters.

Return type:

CompositeEffectMonitorCfg

to_metadata()

Return every resolved hysteresis threshold as JSON-safe data.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.CompositeEffectMonitorFactory

Factory for the built-in typed-clause monitor.

Methods:

create(spec, ref)	Create one independently stateful typed-clause monitor.
validate_ref(ref)	Validate exact built-in selection and typed thresholds.

create(spec, ref)

Create one independently stateful typed-clause monitor.

Return type:

CompositeEffectMonitor

validate_ref(ref)

Validate exact built-in selection and typed thresholds.

Return type:

None

class embodichain.lab.task_program.semantics.effects.ControlPartEvidenceAddress

Provider-neutral robot control-part observation address.

Methods:

__init__(control_part, channel)

Attributes:

address_fingerprint

Return the channel-scoped control-part observation address.

__init__(control_part, channel)

property address_fingerprint: Hashable

Return the channel-scoped control-part observation address.

class embodichain.lab.task_program.semantics.effects.CoordinatedHeldObjectCleanupExpectation

Typed removal of one coordinated held-object relation.

Methods:

__init__(expectation_id, task_state_keys)
snapshot()	Return an independently constructed cleanup expectation.

__init__(expectation_id, task_state_keys)

snapshot()

Return an independently constructed cleanup expectation.

Return type:

CoordinatedHeldObjectCleanupExpectation

class embodichain.lab.task_program.semantics.effects.EffectEvidenceAddress

Immutable observation address, deliberately separate from command targets.

Attributes:

address_fingerprint

Return a stable, hashable physical observation address.

Methods:

snapshot()

Return an independently owned address of the exact same type.

abstract property address_fingerprint: Hashable

Return a stable, hashable physical observation address.

snapshot()

Return an independently owned address of the exact same type.

Return type:

EffectEvidenceAddress

class embodichain.lab.task_program.semantics.effects.EffectEvidenceSourceRef

Versioned provider route plus one immutable observation address.

Methods:

__init__(provider_id, revision, address)
snapshot()	Return an independently owned source reference.
to_metadata()	Return the versioned physical observation address as JSON-safe data.

Attributes:

source_fingerprint

Return the provider-scoped source address fingerprint.

__init__(provider_id, revision, address)

snapshot()

Return an independently owned source reference.

Return type:

EffectEvidenceSourceRef

property source_fingerprint: Hashable

Return the provider-scoped source address fingerprint.

to_metadata()

Return the versioned physical observation address as JSON-safe data.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.EffectExpectationDecision

Per-row outcome for one physical state expectation.

Rows absent from both satisfied_mask and contradicted_mask remain unresolved. inverse_satisfied_mask is deliberately stronger than contradiction: it requires every clause in the expectation group to have reached its explicit inverse band for the configured consecutive-sample window. This distinction lets failure reconciliation retain a relation only from complete inverse evidence rather than from one contradictory clause.

Methods:

__init__(expectation_id, satisfied_mask, ...)
snapshot()	Return an independently owned expectation outcome.

__init__(expectation_id, satisfied_mask, contradicted_mask, inverse_satisfied_mask)

snapshot()

Return an independently owned expectation outcome.

Return type:

EffectExpectationDecision

class embodichain.lab.task_program.semantics.effects.EffectMonitor

Stateful verifier owned by one grounded semantic call.

Methods:

observe(request, evidence)

Consume one synchronized raw observation and decide requested rows.

Attributes:

resolved_params	Return all resolved monitor thresholds for trace metadata.
spec	Return an independently owned effect contract.

abstract observe(request, evidence)

Consume one synchronized raw observation and decide requested rows.

Return type:

EffectMonitorDecision

abstract property resolved_params: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[EffectMonitorParam, ...] | Mapping[str, EffectMonitorParam], ...] | Mapping[str, None | bool | int | float | str | tuple[EffectMonitorParam, ...] | Mapping[str, EffectMonitorParam]]]

Return all resolved monitor thresholds for trace metadata.

abstract property spec: SemanticEffectSpec

Return an independently owned effect contract.

class embodichain.lab.task_program.semantics.effects.EffectMonitorDecision

Uncorrelated aggregate and per-expectation monitor decision.

When expectation_decisions is non-empty, the aggregate masks are authoritative reductions of that current observation: success is the conjunction of every satisfied mask and failure is the union of every contradicted mask. This prevents callers from combining expectation outcomes observed on different ticks.

Methods:

__init__(success_mask, failure_mask[, ...])

__init__(success_mask, failure_mask, expectation_decisions=())

class embodichain.lab.task_program.semantics.effects.EffectMonitorFactory

Versioned constructor for independent semantic-effect monitors.

Methods:

create(spec, ref)	Create one independent monitor for spec and ref.
validate_ref(ref)	Validate one reference without providers or state creation.

abstract create(spec, ref)

Create one independent monitor for spec and ref.

Return type:

EffectMonitor

abstract validate_ref(ref)

Validate one reference without providers or state creation.

Return type:

None

embodichain.lab.task_program.semantics.effects.EffectMonitorParam: TypeAlias = None | bool | int | float | str | tuple['EffectMonitorParam', ...] | collections.abc.Mapping[str, 'EffectMonitorParam']

Recursively immutable, non-executable monitor configuration value.

class embodichain.lab.task_program.semantics.effects.EffectMonitorRef

Versioned, declarative reference to an effect-monitor factory.

Methods:

__init__(monitor_id, revision[, params])
snapshot()	Return an independently owned declarative reference.
to_metadata()	Return a deterministic JSON-safe monitor selection.

__init__(monitor_id, revision, params=<factory>)

snapshot()

Return an independently owned declarative reference.

Return type:

EffectMonitorRef

to_metadata()

Return a deterministic JSON-safe monitor selection.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.EffectMonitorRegistry

Immutable exact-ID/revision registry of monitor factories.

Methods:

__init__([factories])
create(spec, ref)	Create one independent monitor through exact factory lookup.
resolve(ref)	Resolve the exact factory named by a declarative reference.
validate_ref(ref)	Validate a reference provider-free through its exact factory.

Attributes:

factories

Return the immutable exact-key factory mapping.

__init__(factories=())

create(spec, ref)

Create one independent monitor through exact factory lookup.

Return type:

EffectMonitor

property factories: Mapping[tuple[str, str], EffectMonitorFactory]

Return the immutable exact-key factory mapping.

resolve(ref)

Resolve the exact factory named by a declarative reference.

Return type:

EffectMonitorFactory

validate_ref(ref)

Validate a reference provider-free through its exact factory.

Return type:

None

class embodichain.lab.task_program.semantics.effects.HeldObjectRelation

Expected symbolic held-object state at an effect boundary.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.HeldObjectStateExpectation

Typed individual held-object postcondition.

Methods:

__init__(expectation_id, relation, ...)
snapshot()	Return an independently constructed state expectation.

__init__(expectation_id, relation, object_id, slot_id, resource_id, task_state_key)

snapshot()

Return an independently constructed state expectation.

Return type:

HeldObjectStateExpectation

class embodichain.lab.task_program.semantics.effects.JointStateEffectClause

Raw articulation/robot joint-position target condition.

Methods:

__init__(clause_id, expectation_id, source, ...)
snapshot()	Return an independently owned joint-state clause.

__init__(clause_id, expectation_id, source, target_position)

snapshot()

Return an independently owned joint-state clause.

Return type:

JointStateEffectClause

class embodichain.lab.task_program.semantics.effects.JointStateEvidenceBatch

Raw per-row joint position/velocity observations.

Methods:

__init__(evidence_id, positions, velocities, ...)
snapshot()	Return an independently owned evidence batch.
to_metadata()	Return raw joint-state evidence as JSON-safe trace metadata.

__init__(evidence_id, positions, velocities, valid, acquisition_errors, timestamp, env_ids, observation_revision)

snapshot()

Return an independently owned evidence batch.

Return type:

JointStateEvidenceBatch

to_metadata()

Return raw joint-state evidence as JSON-safe trace metadata.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.PoseRelationClause

Object-to-endpoint pose condition with monitor-owned tolerances.

Methods:

__init__(clause_id, expectation_id, source, ...)
snapshot()	Return an independently owned pose clause.

__init__(clause_id, expectation_id, source, expectation, baseline_object_to_endpoint=None)

snapshot()

Return an independently owned pose clause.

Return type:

PoseRelationClause

class embodichain.lab.task_program.semantics.effects.PoseRelationEvidenceBatch

Raw object-to-endpoint transform observations.

Methods:

__init__(evidence_id, object_to_endpoint, ...)
snapshot()	Return an independently owned evidence batch.
to_metadata()	Return raw pose evidence as JSON-safe trace metadata.

__init__(evidence_id, object_to_endpoint, valid, acquisition_errors, timestamp, env_ids, observation_revision)

snapshot()

Return an independently owned evidence batch.

Return type:

PoseRelationEvidenceBatch

to_metadata()

Return raw pose evidence as JSON-safe trace metadata.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.PoseRelationExpectation

Expected relationship to a grounded pose baseline.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.ScalarEffectClause

Raw force/wrench magnitude condition with monitor-owned thresholds.

Methods:

__init__(clause_id, expectation_id, source, ...)
snapshot()	Return an independently owned scalar clause.

__init__(clause_id, expectation_id, source, evidence_kind, expectation)

snapshot()

Return an independently owned scalar clause.

Return type:

ScalarEffectClause

class embodichain.lab.task_program.semantics.effects.ScalarEffectEvidenceBatch

Raw per-row force or wrench-magnitude observations.

Methods:

__init__(evidence_id, evidence_kind, values, ...)
snapshot()	Return an independently owned evidence batch.
to_metadata()	Return raw scalar evidence as JSON-safe trace metadata.

__init__(evidence_id, evidence_kind, values, valid, acquisition_errors, timestamp, env_ids, observation_revision)

snapshot()

Return an independently owned evidence batch.

Return type:

ScalarEffectEvidenceBatch

to_metadata()

Return raw scalar evidence as JSON-safe trace metadata.

Return type:

dict[str, object]

class embodichain.lab.task_program.semantics.effects.ScalarEvidenceKind

Raw scalar physical evidence channel.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.ScalarExpectation

Expected high/low magnitude band for scalar evidence.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.SemanticEffectKind

Trace-level semantic effect category; clause types define behavior.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.SemanticEffectSpec

Grounded typed physical clauses and symbolic postconditions for one call.

Methods:

__init__(semantic_id, effect_kind, skill_id, ...)
snapshot()	Return an independently owned grounded effect contract.
state_expectation(expectation_id)	Return an owned state expectation by effect-local ID.
to_metadata()	Return this grounded effect contract as deterministic JSON-safe data.
validate_request(request)	Validate execution identity and typed symbolic postconditions.

__init__(semantic_id, effect_kind, skill_id, invocation_id, invocation_revision, env_ids, state_expectations, clauses)

snapshot()

Return an independently owned grounded effect contract.

Return type:

SemanticEffectSpec

state_expectation(expectation_id)

Return an owned state expectation by effect-local ID.

Return type:

HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

to_metadata()

Return this grounded effect contract as deterministic JSON-safe data.

Return type:

dict[str, object]

validate_request(request)

Validate execution identity and typed symbolic postconditions.

Return type:

None

class embodichain.lab.task_program.semantics.effects.SymbolicStateDomain

Typed mapping domains owned by TaskState.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.effects.SymbolicStateKey

Provider-free key for one exact symbolic TaskState write.

The domain makes otherwise similar string and pair addresses impossible to conflate during static parallel analysis. This contract intentionally describes only exact keys; dynamic or opaque effects must not manufacture a guessed key.

Methods:

__init__(domain, address)
articulation_joint(articulation_id, joint_id)	Build one articulation-joint mapping key.
coordinated_held_object(...)	Build one ordered coordinated-held-object mapping key.
held_object(task_state_key)	Build one held-object mapping key.

Attributes:

rendered

Return a deterministic domain-qualified diagnostic form.

__init__(domain, address)

classmethod articulation_joint(articulation_id, joint_id)

Build one articulation-joint mapping key.

Return type:

SymbolicStateKey

classmethod coordinated_held_object(first_task_state_key, second_task_state_key)

Build one ordered coordinated-held-object mapping key.

Return type:

SymbolicStateKey

classmethod held_object(task_state_key)

Build one held-object mapping key.

Return type:

SymbolicStateKey

property rendered: str

Return a deterministic domain-qualified diagnostic form.

embodichain.lab.task_program.semantics.evidence

Backend-neutral acquisition ports for typed semantic-effect evidence.

Classes:

BinaryEffectEvidenceQuery	Query for one raw contact or constraint boolean.
BinaryEffectObservation	Callback-owned raw binary values with explicit row validity.
ControlPartRobotEvidenceSource	Minimal simulation robot API used by the built-in provider.
ControlPartSimulationEvidenceProvider	Built-in simulation acquisition for control-part evidence addresses.
EffectEvidenceCollectionContext	One synchronized acquisition tick shared by all effect clauses.
EffectEvidenceCollector	Dispatch and normalize a synchronized observation for one effect spec.
EffectEvidenceProvider	Versioned backend port that acquires a group of exact-source queries.
EffectEvidenceProviderRegistry	Immutable exact-ID/revision registry of live evidence providers.
EffectEvidenceQuery	Typed request for the raw evidence of exactly one effect clause.
JointStateEvidenceQuery	Query for current joint positions and optional velocities.
JointStateObservation	Callback-owned raw joint state with explicit row validity.
PoseRelationEvidenceQuery	Query for an object's pose relative to a resource endpoint.
ScalarEffectEvidenceQuery	Query for one raw force or wrench magnitude.
ScalarEffectObservation	Callback-owned raw scalar values with explicit row validity.
SceneArticulationEvidenceProvider	Typed adapter for scene-articulation joint-state observations.

Data:

EffectEvidenceQueryValue

Closed set of typed clause queries accepted by evidence providers.

Functions:

build_effect_evidence_queries(spec)

Build one independently owned typed query per effect clause.

class embodichain.lab.task_program.semantics.evidence.BinaryEffectEvidenceQuery

Query for one raw contact or constraint boolean.

Methods:

__init__(clause, _expectation)
snapshot()	Return an independently owned binary query.

Attributes:

evidence_id	Return the source clause ID.
expectation	Return an owned correlated expectation.
source	Return an owned source route.

__init__(clause, _expectation)

property evidence_id: str

Return the source clause ID.

property expectation: HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

Return an owned correlated expectation.

snapshot()

Return an independently owned binary query.

Return type:

BinaryEffectEvidenceQuery

property source: EffectEvidenceSourceRef

Return an owned source route.

class embodichain.lab.task_program.semantics.evidence.BinaryEffectObservation

Callback-owned raw binary values with explicit row validity.

Methods:

__init__(values[, valid, acquisition_errors])

__init__(values, valid=None, acquisition_errors=())

class embodichain.lab.task_program.semantics.evidence.ControlPartRobotEvidenceSource

Minimal simulation robot API used by the built-in provider.

Methods:

__init__(*args, **kwargs)
compute_fk(qpos[, name, env_ids, to_matrix])	Return the selected endpoint pose for current joint positions.
get_qpos([name, target])	Return current robot or control-part joint positions.
get_qvel([name, target])	Return current robot or control-part joint velocities.

__init__(*args, **kwargs)

compute_fk(qpos, name=None, env_ids=None, to_matrix=False)

Return the selected endpoint pose for current joint positions.

Return type:

Tensor

get_qpos(name=None, target=False)

Return current robot or control-part joint positions.

Return type:

Tensor

get_qvel(name=None, target=False)

Return current robot or control-part joint velocities.

Return type:

Tensor

class embodichain.lab.task_program.semantics.evidence.ControlPartSimulationEvidenceProvider

Built-in simulation acquisition for control-part evidence addresses.

Pose evidence is computed as inverse(object_pose) @ endpoint_pose from one scene snapshot and Robot.compute_fk(). Joint evidence reads the control part’s measured positions and velocities. Contact, constraint, force, and wrench signals are backend-specific, so callers inject raw observation callbacks. An omitted callback yields explicit invalid rows; the effect monitor can then retry until its normal deadline.

Methods:

__init__(robot, *[, scene_provider, ...])
collect(queries, context)	Acquire all supplied control-part queries at one observation tick.

__init__(robot, *, scene_provider=None, contact_observer=None, constraint_observer=None, force_observer=None, wrench_observer=None)

collect(queries, context)

Acquire all supplied control-part queries at one observation tick.

Return type:

Mapping[str, PoseRelationEvidenceBatch | BinaryEffectEvidenceBatch | ScalarEffectEvidenceBatch | JointStateEvidenceBatch]

class embodichain.lab.task_program.semantics.evidence.EffectEvidenceCollectionContext

One synchronized acquisition tick shared by all effect clauses.

Parameters:

• timestamp (float) – Non-negative backend observation time.

• observation_revision (int) – Monotonic revision chosen by the runtime port.

• env_ids (Tensor) – Ordered environment correlation IDs to observe.

Methods:

__init__(timestamp, observation_revision, ...)
snapshot()	Return an independently owned acquisition context.

__init__(timestamp, observation_revision, env_ids)

snapshot()

Return an independently owned acquisition context.

Return type:

EffectEvidenceCollectionContext

class embodichain.lab.task_program.semantics.evidence.EffectEvidenceCollector

Dispatch and normalize a synchronized observation for one effect spec.

Methods:

__init__(registry)
collect(spec, *, timestamp, observation_revision)	Acquire and strictly synchronize evidence for every effect clause.

Attributes:

registry

Return the immutable provider registry.

__init__(registry)

collect(spec, *, timestamp, observation_revision, env_ids=None)

Acquire and strictly synchronize evidence for every effect clause.

Parameters:

• spec (SemanticEffectSpec) – Grounded semantic effect contract.

• timestamp (float) – Backend observation time for this acquisition tick.

• observation_revision (int) – Runtime-owned observation revision.

• env_ids (Tensor | None) – Optional ordered subset of spec.env_ids. Acquisition failures must remain present as rows with valid=False.

Return type:

Mapping[str, PoseRelationEvidenceBatch | BinaryEffectEvidenceBatch | ScalarEffectEvidenceBatch | JointStateEvidenceBatch]

Returns:

Immutable mapping keyed exactly by effect clause ID.

property registry: EffectEvidenceProviderRegistry

Return the immutable provider registry.

class embodichain.lab.task_program.semantics.evidence.EffectEvidenceProvider

Versioned backend port that acquires a group of exact-source queries.

Methods:

collect(queries, context)

Acquire one synchronized batch for every supplied query.

abstract collect(queries, context)

Acquire one synchronized batch for every supplied query.

Return type:

Mapping[str, PoseRelationEvidenceBatch | BinaryEffectEvidenceBatch | ScalarEffectEvidenceBatch | JointStateEvidenceBatch]

class embodichain.lab.task_program.semantics.evidence.EffectEvidenceProviderRegistry

Immutable exact-ID/revision registry of live evidence providers.

Methods:

__init__([providers])
resolve(source)	Resolve the exact provider selected by source.

Attributes:

providers

Return the immutable exact-key provider mapping.

__init__(providers=())

property providers: Mapping[tuple[str, str], EffectEvidenceProvider]

Return the immutable exact-key provider mapping.

resolve(source)

Resolve the exact provider selected by source.

Parameters:

source (EffectEvidenceSourceRef) – Versioned evidence route from one effect clause.

Return type:

EffectEvidenceProvider

Returns:

Registered provider with the exact ID and revision.

Raises:

KeyError – If no exact provider version is installed.

class embodichain.lab.task_program.semantics.evidence.EffectEvidenceQuery

Typed request for the raw evidence of exactly one effect clause.

Attributes:

evidence_id	Return the clause-local evidence identifier.
expectation	Return an owned symbolic expectation related to this query.
source	Return an owned exact provider route and physical address.

Methods:

snapshot()

Return an independently owned query of the exact same type.

abstract property evidence_id: str

Return the clause-local evidence identifier.

abstract property expectation: HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

Return an owned symbolic expectation related to this query.

abstract snapshot()

Return an independently owned query of the exact same type.

Return type:

EffectEvidenceQuery

abstract property source: EffectEvidenceSourceRef

Return an owned exact provider route and physical address.

embodichain.lab.task_program.semantics.evidence.EffectEvidenceQueryValue: TypeAlias = embodichain.lab.task_program.semantics.evidence.PoseRelationEvidenceQuery | embodichain.lab.task_program.semantics.evidence.BinaryEffectEvidenceQuery | embodichain.lab.task_program.semantics.evidence.ScalarEffectEvidenceQuery | embodichain.lab.task_program.semantics.evidence.JointStateEvidenceQuery

Closed set of typed clause queries accepted by evidence providers.

class embodichain.lab.task_program.semantics.evidence.JointStateEvidenceQuery

Query for current joint positions and optional velocities.

Methods:

__init__(clause, _expectation)
snapshot()	Return an independently owned joint-state query.

Attributes:

evidence_id	Return the source clause ID.
expectation	Return an owned correlated expectation.
source	Return an owned source route.

__init__(clause, _expectation)

property evidence_id: str

Return the source clause ID.

property expectation: HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

Return an owned correlated expectation.

snapshot()

Return an independently owned joint-state query.

Return type:

JointStateEvidenceQuery

property source: EffectEvidenceSourceRef

Return an owned source route.

class embodichain.lab.task_program.semantics.evidence.JointStateObservation

Callback-owned raw joint state with explicit row validity.

Methods:

__init__(positions[, velocities, valid, ...])

__init__(positions, velocities=None, valid=None, acquisition_errors=())

class embodichain.lab.task_program.semantics.evidence.PoseRelationEvidenceQuery

Query for an object’s pose relative to a resource endpoint.

Methods:

__init__(clause, _expectation)
snapshot()	Return an independently owned pose query.

Attributes:

evidence_id	Return the source clause ID.
expectation	Return an owned correlated expectation.
source	Return an owned source route.

__init__(clause, _expectation)

property evidence_id: str

Return the source clause ID.

property expectation: HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

Return an owned correlated expectation.

snapshot()

Return an independently owned pose query.

Return type:

PoseRelationEvidenceQuery

property source: EffectEvidenceSourceRef

Return an owned source route.

class embodichain.lab.task_program.semantics.evidence.ScalarEffectEvidenceQuery

Query for one raw force or wrench magnitude.

Methods:

__init__(clause, _expectation)
snapshot()	Return an independently owned scalar query.

Attributes:

evidence_id	Return the source clause ID.
expectation	Return an owned correlated expectation.
source	Return an owned source route.

__init__(clause, _expectation)

property evidence_id: str

Return the source clause ID.

property expectation: HeldObjectStateExpectation | CoordinatedHeldObjectCleanupExpectation | ArticulationJointStateExpectation

Return an owned correlated expectation.

snapshot()

Return an independently owned scalar query.

Return type:

ScalarEffectEvidenceQuery

property source: EffectEvidenceSourceRef

Return an owned source route.

class embodichain.lab.task_program.semantics.evidence.ScalarEffectObservation

Callback-owned raw scalar values with explicit row validity.

Methods:

__init__(values[, valid, acquisition_errors])

__init__(values, valid=None, acquisition_errors=())

class embodichain.lab.task_program.semantics.evidence.SceneArticulationEvidenceProvider

Typed adapter for scene-articulation joint-state observations.

Integrations inject either a direct observer or a SceneProvider whose snapshot contains ObservedArticulationJointState values. The adapter never discovers live simulator objects from an environment. Repeated clauses share one synchronized snapshot and one sample per exact physical address.

Methods:

__init__([observer, scene_provider])
collect(queries, context)	Collect synchronized joint state for exact scene addresses.

__init__(observer=None, *, scene_provider=None)

collect(queries, context)

Collect synchronized joint state for exact scene addresses.

Return type:

Mapping[str, PoseRelationEvidenceBatch | BinaryEffectEvidenceBatch | ScalarEffectEvidenceBatch | JointStateEvidenceBatch]

embodichain.lab.task_program.semantics.evidence.build_effect_evidence_queries(spec)

Build one independently owned typed query per effect clause.

Parameters:

spec (SemanticEffectSpec) – Grounded semantic effect contract.

Return type:

tuple[PoseRelationEvidenceQuery | BinaryEffectEvidenceQuery | ScalarEffectEvidenceQuery | JointStateEvidenceQuery, ...]

Returns:

Queries in the contract’s deterministic clause order.

embodichain.lab.task_program.semantics.profiles

AmbiguousSkillBindingError	Raised when multiple assignments remain without a complete default.
BoundRobotSkillProfile	Robot- and engine-validated view of a RobotSkillProfile.
ControlPartEndpoint	One named execution endpoint backed by a robot control part.
ControlPartEndpointAdapter	Resolve joint-backed ControlPartEndpoint declarations.
EffectAssurance	Authority used to advance semantic state after command completion.
EndpointResolution	Adapter-produced runtime destination and claim metadata for one endpoint.
ProfileValidationError	Raised when a robot skill profile disagrees with its engine or robot.
ResourceEndpoint	Extensible execution endpoint in a robot resource graph.
ResourceEndpointAdapter	Resolve one endpoint kind without coupling profiles to its controller.
ResolvedRobotResource	Robot-validated resource with concrete endpoint joint IDs and claim.
ResolvedResourceEndpoint	Endpoint declaration resolved by one registered adapter.
ResolvedSkillBinding	One generic resource assignment lowered for the current action core.
ResourceBinding	Generic mapping from skill-local slots to robot resource IDs.
ResourceClaim	Physical leaf and joint claim used for deterministic conflict checks.
RobotResource	Generic leaf or composite resource in one robot's resource DAG.
RobotSkillProfile	Reusable declarative skill integration for one robot embodiment.
SkillPolicyPreset	Policies and typed semantic-call option templates.
UnsupportedSkillError	Raised when no robot-resource assignment can satisfy a skill.
WorkflowRecoveryPolicy	Bound workflow-level recovery for curated semantic effect failures.

embodichain.lab.task_program.semantics.scene

AmbiguousSceneAffordanceError	Raised when compatible affordances lack one explicitly scoped default.
GRASP_AFFORDANCE_CAPABILITY	Capability for an affordance usable by object pickup or handover.
PLACE_IN_AFFORDANCE_CAPABILITY	Capability for an affordance that defines an inside placement relation.
PLACE_ON_AFFORDANCE_CAPABILITY	Capability for an affordance that defines an on placement relation.
RegistrySceneProvider	Stateful scene provider derived from an immutable registry.
SceneAffordanceRef	Reference to one registered interaction affordance.
SceneArticulationRef	Reference to one articulation registered in the semantic scene.
SceneCollisionRole	How an entity participates in the planner collision world.
SceneCollisionWorldMode	Batch-sharing policy for a dynamic planner collision world.
SceneDynamics	Physical mobility classification owned by a scene registration.
SceneEntityRef	Typed reference to one authoritative scene-registry entity.
SceneEntityMetadata	Provider-free semantic metadata projected from one registration.
SceneEntityRegistration	Immutable integration metadata for one authoritative scene entity.
SceneEntityStateProvider	Observe one registered entity for an ordered environment batch.
SceneGeometryProvider	Provide one entity's planner-facing collision geometry descriptor.
SceneLinkRef	Reference to one registered articulation link.
SceneObjectRef	Reference to one object registered in the semantic scene.
SceneRegistry	Immutable authoritative catalog of semantic scene entities.
UnsupportedSceneAffordanceError	Raised when a parent has no affordance for a required capability.

Authoritative scene identity and registration value contracts.

Exceptions:

AmbiguousSceneAffordanceError	Raised when compatible affordances lack one explicitly scoped default.
UnsupportedSceneAffordanceError	Raised when a parent has no affordance for a required capability.

Classes:

ArticulationJointEvidenceAddress	Canonical scene articulation and joint observation address.
ContainerAffordance	Typed target frame for placing an object's origin inside a container.
RegistrySceneProvider	Stateful scene provider derived from an immutable registry.
SceneAffordanceRef	Reference to one registered interaction affordance.
SceneArticulationJointStateProvider	Observe canonical joints for one registered scene articulation.
SceneArticulationRef	Reference to one articulation registered in the semantic scene.
SceneCollisionRole	How an entity participates in the planner collision world.
SceneCollisionWorldMode	Batch-sharing policy for a dynamic planner collision world.
SceneDynamics	Physical mobility classification owned by a scene registration.
SceneEntityMetadata	Provider-free semantic metadata projected from one registration.
SceneEntityRef	Typed reference to one authoritative scene-registry entity.
SceneEntityRegistration	Immutable integration metadata for one authoritative scene entity.
SceneEntityStateProvider	Observe one registered entity for an ordered environment batch.
SceneGeometryProvider	Provide one entity's planner-facing collision geometry descriptor.
SceneLinkRef	Reference to one registered articulation link.
SceneObjectRef	Reference to one object registered in the semantic scene.
SceneRegistry	Immutable authoritative catalog of semantic scene entities.
SupportSurfaceAffordance	Typed target frame for placing an object's origin on a support surface.

Data:

GRASP_AFFORDANCE_CAPABILITY	Capability for an affordance usable by object pickup or handover.
PLACEMENT_TARGET_AFFORDANCE_REVISION	Schema revision for built-in support/container object-target frames.
PLACE_IN_AFFORDANCE_CAPABILITY	Capability for an affordance that defines an inside placement relation.
PLACE_ON_AFFORDANCE_CAPABILITY	Capability for an affordance that defines an on placement relation.
SCENE_ARTICULATION_EVIDENCE_PROVIDER_ID	Stable route for explicitly injected articulation-joint observations.
SCENE_ARTICULATION_EVIDENCE_PROVIDER_REVISION	Exact contract revision for articulation-joint evidence addresses.

exception embodichain.lab.task_program.semantics.scene.AmbiguousSceneAffordanceError

Raised when compatible affordances lack one explicitly scoped default.

class embodichain.lab.task_program.semantics.scene.ArticulationJointEvidenceAddress

Canonical scene articulation and joint observation address.

Methods:

__init__(articulation_id, joint_id)

Attributes:

address_fingerprint

Return the exact provider-independent joint address.

__init__(articulation_id, joint_id)

property address_fingerprint: Hashable

Return the exact provider-independent joint address.

class embodichain.lab.task_program.semantics.scene.ContainerAffordance

Typed target frame for placing an object’s origin inside a container.

The registered affordance pose is the desired object pose, expressed relative to its parent scene entity. The optional confidence threshold is enforced whenever that late-bound target pose is resolved.

Parameters:

minimum_confidence (float) – Minimum confidence accepted while resolving the late-bound target pose.

Methods:

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

__init__(object_label='', custom_config=<factory>, minimum_confidence=0.0)

embodichain.lab.task_program.semantics.scene.GRASP_AFFORDANCE_CAPABILITY = 'affordance.grasp'

Capability for an affordance usable by object pickup or handover.

embodichain.lab.task_program.semantics.scene.PLACEMENT_TARGET_AFFORDANCE_REVISION = '1'

Schema revision for built-in support/container object-target frames.

embodichain.lab.task_program.semantics.scene.PLACE_IN_AFFORDANCE_CAPABILITY = 'affordance.place.in'

Capability for an affordance that defines an inside placement relation.

embodichain.lab.task_program.semantics.scene.PLACE_ON_AFFORDANCE_CAPABILITY = 'affordance.place.on'

Capability for an affordance that defines an on placement relation.

class embodichain.lab.task_program.semantics.scene.RegistrySceneProvider

Stateful scene provider derived from an immutable registry.

Instances are created by SceneRegistry.make_scene_provider(); each instance owns its revision counters and material-pose baselines.

Parameters:

• registry (SceneRegistry) – Immutable catalog that owns entity registrations.

• translation_threshold (float) – Accumulated translation needed to publish a material scene change.

• rotation_threshold (float) – Accumulated rotation needed to publish a material scene change.

• batch_size (int | None) – Optional fixed execution batch size. Factory-created planning providers bind this value before their first observation.

Methods:

__init__(registry, *, translation_threshold, ...)
snapshot(*, timestamp, env_ids)	Observe all canonical entities and advance material revisions.

Attributes:

collision_world_mode

Return the configured or first-snapshot-resolved collision mode.

__init__(registry, *, translation_threshold, rotation_threshold, batch_size=None)

property collision_world_mode: SceneCollisionWorldMode | None

Return the configured or first-snapshot-resolved collision mode.

snapshot(*, timestamp, env_ids)

Observe all canonical entities and advance material revisions.

Parameters:

• timestamp (float) – Non-negative monotonic observation timestamp.

• env_ids (Tensor) – Stable ordered correlation IDs for every environment row.

Return type:

SceneSnapshot

Returns:

An immutable snapshot keyed only by canonical registry IDs.

embodichain.lab.task_program.semantics.scene.SCENE_ARTICULATION_EVIDENCE_PROVIDER_ID = 'builtin.scene_articulation'

Stable route for explicitly injected articulation-joint observations.

embodichain.lab.task_program.semantics.scene.SCENE_ARTICULATION_EVIDENCE_PROVIDER_REVISION = '1'

Exact contract revision for articulation-joint evidence addresses.

class embodichain.lab.task_program.semantics.scene.SceneAffordanceRef

Reference to one registered interaction affordance.

Methods:

__init__(entity_id)

__init__(entity_id)

class embodichain.lab.task_program.semantics.scene.SceneArticulationJointStateProvider

Observe canonical joints for one registered scene articulation.

Methods:

__init__(*args, **kwargs)
observe_joints(*, timestamp, env_ids)	Return live joint observations whose rows follow env_ids.

__init__(*args, **kwargs)

observe_joints(*, timestamp, env_ids)

Return live joint observations whose rows follow env_ids.

Return type:

Mapping[str, ObservedArticulationJointState]

class embodichain.lab.task_program.semantics.scene.SceneArticulationRef

Reference to one articulation registered in the semantic scene.

Methods:

__init__(entity_id)

__init__(entity_id)

class embodichain.lab.task_program.semantics.scene.SceneCollisionRole

How an entity participates in the planner collision world.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.scene.SceneCollisionWorldMode

Batch-sharing policy for a dynamic planner collision world.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.scene.SceneDynamics

Physical mobility classification owned by a scene registration.

Methods:

__new__(value)

__new__(value)

class embodichain.lab.task_program.semantics.scene.SceneEntityMetadata

Provider-free semantic metadata projected from one registration.

Parameters:

• ref (SceneEntityRef) – Canonical typed entity reference.

• aliases (tuple[str, ...]) – Boundary aliases, compared as an order-independent set.

• parent (SceneEntityRef | None) – Canonical parent for links and affordances.

• native_name (str | None) – Backend-local child name.

• dynamics (SceneDynamics) – Physical mobility classification.

• collision_role (SceneCollisionRole) – Planner collision classification.

• semantic_type (str | None) – Optional application semantic type.

• affordance_capabilities (frozenset[str]) – Open capabilities of an affordance.

• default_affordances (Mapping[str, SceneAffordanceRef]) – Capability-scoped direct-child defaults.

• affordance_payload_type (type[Affordance] | None) – Exact registered affordance value type.

• affordance_revision (str | None) – Integrator-owned payload revision or fingerprint.

• relative_pose (tuple[float, ...] | None) – Flattened parent-relative 4x4 pose, when declared.

Methods:

__init__(ref[, aliases, parent, ...])
from_registration(registration)	Project semantic metadata without copying a live payload/provider.

__init__(ref, aliases=(), parent=None, native_name=None, dynamics=SceneDynamics.UNKNOWN, collision_role=SceneCollisionRole.NONE, semantic_type=None, affordance_capabilities=frozenset({}), default_affordances=<factory>, affordance_payload_type=None, affordance_revision=None, relative_pose=None)

classmethod from_registration(registration)

Project semantic metadata without copying a live payload/provider.

Return type:

SceneEntityMetadata

class embodichain.lab.task_program.semantics.scene.SceneEntityRef

Typed reference to one authoritative scene-registry entity.

Parameters:

entity_id (str) – Globally stable canonical registry identifier.

Methods:

__init__(entity_id)

Attributes:

entity_id

Globally stable authoritative registry identifier.

__init__(entity_id)

entity_id: str

Globally stable authoritative registry identifier.

class embodichain.lab.task_program.semantics.scene.SceneEntityRegistration

Immutable integration metadata for one authoritative scene entity.

Parent relationships, simulator-native names, pose sources, geometry, and affordances belong to the registry registration rather than the lightweight reference copied into semantic calls.

Parameters:

• ref (SceneEntityRef) – Canonical typed reference.

• state_provider (SceneEntityStateProvider | None) – Optional dynamic pose/confidence source.

• joint_state_provider (SceneArticulationJointStateProvider | None) – Optional live articulation-joint source.

• aliases (tuple[str, ...]) – External names normalized at the registry boundary.

• parent (SceneEntityRef | None) – Canonical parent for a link or affordance.

• native_name (str | None) – Backend-local member name under parent.

• dynamics (SceneDynamics) – Physical mobility classification.

• geometry_provider (SceneGeometryProvider | None) – Planner-facing collision geometry source.

• collision_role (SceneCollisionRole) – Static, dynamic, or no planner collision role.

• semantic_type (str | None) – Optional application semantic type.

• affordance (Affordance | None) – Affordance value for an affordance registration.

• affordance_capabilities (frozenset[str]) – Open semantic operations supported by an affordance registration.

• default_affordances (Mapping[str, SceneAffordanceRef]) – Capability-to-child mapping owned by a parent object, articulation, or link registration.

• affordance_revision (str | None) – Stable integrator-owned revision or fingerprint for capability-bearing affordance payload data.

• relative_pose (Tensor | None) – Optional parent-relative affordance transform.

Methods:

__init__(ref[, state_provider, aliases, ...])

Attributes:

affordance	Affordance value owned by a SceneAffordanceRef registration.
affordance_capabilities	Open semantic capabilities declared by an affordance registration.
affordance_revision	Stable payload revision required by capability-bearing affordances.
aliases	External names normalized once at the registry boundary.
collision_role	Static/dynamic planner-obstacle role, or none.
default_affordances	Capability-scoped child affordances selected when multiple are valid.
dynamics	Static, kinematic, dynamic, or unknown mobility classification.
geometry_provider	Collision geometry source required for planner collision roles.
joint_state_provider	Explicit live joint source for an articulation registration.
native_name	Backend-local link or affordance name under parent.
parent	Canonical parent reference for a link or affordance.
ref	Canonical typed reference owned by the registry.
relative_pose	Optional parent-relative pose when no explicit state provider exists.
semantic_type	Optional application semantic type such as container or tool.
state_provider	Explicit dynamic pose/confidence source.

__init__(ref, state_provider=None, aliases=(), parent=None, native_name=None, dynamics=SceneDynamics.UNKNOWN, geometry_provider=None, collision_role=SceneCollisionRole.NONE, semantic_type=None, affordance=None, affordance_capabilities=frozenset({}), default_affordances=<factory>, affordance_revision=None, relative_pose=None, joint_state_provider=None)

affordance: Affordance | None

Affordance value owned by a SceneAffordanceRef registration.

affordance_capabilities: frozenset[str]

Open semantic capabilities declared by an affordance registration.

affordance_revision: str | None

Stable payload revision required by capability-bearing affordances.

aliases: tuple[str, ...]

External names normalized once at the registry boundary.

collision_role: SceneCollisionRole

Static/dynamic planner-obstacle role, or none.

default_affordances: Mapping[str, SceneAffordanceRef]

Capability-scoped child affordances selected when multiple are valid.

dynamics: SceneDynamics

Static, kinematic, dynamic, or unknown mobility classification.

geometry_provider: SceneGeometryProvider | None

Collision geometry source required for planner collision roles.

joint_state_provider: SceneArticulationJointStateProvider | None

Explicit live joint source for an articulation registration.

native_name: str | None

Backend-local link or affordance name under parent.

parent: SceneEntityRef | None

Canonical parent reference for a link or affordance.

ref: SceneEntityRef

Canonical typed reference owned by the registry.

relative_pose: Tensor | None

Optional parent-relative pose when no explicit state provider exists.

semantic_type: str | None

Optional application semantic type such as container or tool.

state_provider: SceneEntityStateProvider | None

Explicit dynamic pose/confidence source.

class embodichain.lab.task_program.semantics.scene.SceneEntityStateProvider

Observe one registered entity for an ordered environment batch.

Methods:

__init__(*args, **kwargs)
observe(*, timestamp, env_ids)	Return the entity state whose rows follow env_ids.

__init__(*args, **kwargs)

observe(*, timestamp, env_ids)

Return the entity state whose rows follow env_ids.

Parameters:

• timestamp (float) – Observation timestamp supplied by the integration.

• env_ids (Tensor) – Stable ordered environment correlation IDs.

Return type:

EntityState

Returns:

Current pose and confidence for the registered entity.

class embodichain.lab.task_program.semantics.scene.SceneGeometryProvider

Provide one entity’s planner-facing collision geometry descriptor.

Methods:

__init__(*args, **kwargs)
get_geometry()	Return the planner-facing geometry descriptor.

__init__(*args, **kwargs)

get_geometry()

Return the planner-facing geometry descriptor.

Return type:

object

Returns:

Backend-consumable geometry or a live simulation entity.

class embodichain.lab.task_program.semantics.scene.SceneLinkRef

Reference to one registered articulation link.

Methods:

__init__(entity_id)

__init__(entity_id)

class embodichain.lab.task_program.semantics.scene.SceneObjectRef

Reference to one object registered in the semantic scene.

Methods:

__init__(entity_id)

__init__(entity_id)

class embodichain.lab.task_program.semantics.scene.SceneRegistry

Immutable authoritative catalog of semantic scene entities.

Canonical identifiers occupy one flat, globally unique namespace. Aliases are accepted only at lookup and integration boundaries and always resolve to a canonical typed reference before they leave the registry.

Parameters:

• registrations (Iterable[SceneEntityRegistration]) – Complete scene registrations. The iterable is copied and cannot be extended after construction.

• collision_world_mode (SceneCollisionWorldMode | None) – Explicit dynamic-collision batch policy. It may be omitted for a single environment, which resolves to shared. A multi-environment dynamic world must select a mode explicitly.

Methods:

__init__([registrations, collision_world_mode])
affordances(parent, *, capability)	Return compatible direct-child affordances without selecting one.
collision_geometry_by_id([role])	Materialize planner geometry under canonical registry IDs.
from_simulation(simulation, *[, ...])	Opt explicitly selected simulation entities into a registry.
lookup(identifier, *[, expected_type])	Return an owned registration after canonical typed resolution.
make_planning_scene_provider(...[, ...])	Create a provider after complete planner/registry validation.
make_scene_provider(*[, ...])	Create an independent provider without planner cross-validation.
object_semantics(object_ref, *, affordance)	Build one owned atomic-action semantic snapshot.
resolve(identifier, *[, expected_type])	Resolve a canonical ID or alias to a typed canonical reference.
resolve_affordance(parent, *, capability[, ...])	Select one compatible affordance with strict scoped-default rules.
resolve_collision_world_mode(*, batch_size)	Resolve the configured collision mode for an execution batch.
validate_collision_integration(...[, ...])	Validate registry/planner agreement before dynamic planning.

Attributes:

aliases	Return the immutable alias-to-canonical-ID index.
collision_world_entity_ids	Return every canonical ID represented in the planner world.
dynamic_collision_entity_ids	Return canonical IDs whose planner poses update dynamically.
entity_metadata	Return provider-free metadata without copying affordance payloads.
entity_refs	Return canonical typed references in registration order.
registrations	Return structurally independent registration values.
static_collision_entity_ids	Return canonical IDs baked into the static planner world.

__init__(registrations=(), *, collision_world_mode=None)

affordances(parent, *, capability)

Return compatible direct-child affordances without selecting one.

Parameters:

• parent (str | SceneEntityRef) – Canonical ID, alias, or typed parent reference.

• capability (str) – Required open affordance capability.

Return type:

tuple[SceneAffordanceRef, ...]

Returns:

Compatible canonical references sorted by canonical ID.

property aliases: Mapping[str, str]

Return the immutable alias-to-canonical-ID index.

collision_geometry_by_id(role=None)

Materialize planner geometry under canonical registry IDs.

Parameters:

role (SceneCollisionRole | None) – Optional exact collision-role filter. Without a filter, all static and dynamic collision registrations are included. Registrations whose role is SceneCollisionRole.NONE never enter the planner collision world.

Return type:

Mapping[str, object]

Returns:

Fresh immutable canonical-ID-to-geometry mapping.

property collision_world_entity_ids: tuple[str, ...]

Return every canonical ID represented in the planner world.

property dynamic_collision_entity_ids: tuple[str, ...]

Return canonical IDs whose planner poses update dynamically.

property entity_metadata: tuple[SceneEntityMetadata, ...]

Return provider-free metadata without copying affordance payloads.

property entity_refs: tuple[SceneEntityRef, ...]

Return canonical typed references in registration order.

classmethod from_simulation(simulation, *, rigid_objects=None, articulations=None, collision_roles=None, geometry_providers=None, collision_world_mode=None)

Opt explicitly selected simulation entities into a registry.

rigid_objects and articulations map authoritative registry IDs to simulation UIDs. UIDs become aliases automatically; unlisted simulation entities are never imported. Collision participation defaults to SceneCollisionRole.NONE.

Parameters:

• simulation (SimulationManager) – Simulation manager used only for explicit UID lookup.

• rigid_objects (Mapping[str, str] | None) – Canonical object IDs mapped to simulation UIDs.

• articulations (Mapping[str, str] | None) – Canonical articulation IDs mapped to simulation UIDs.

• collision_roles (Mapping[str, SceneCollisionRole] | None) – Optional collision roles keyed by canonical ID.

• geometry_providers (Mapping[str, SceneGeometryProvider] | None) – Optional geometry overrides keyed by canonical ID. Selected rigid objects otherwise expose their live handles.

• collision_world_mode (SceneCollisionWorldMode | None) – Optional dynamic collision batch-sharing mode.

Return type:

SceneRegistry

Returns:

Immutable registry containing only the explicitly selected entities.

lookup(identifier, *, expected_type=<class 'embodichain.lab.task_program.semantics.scene.SceneEntityRef'>)

Return an owned registration after canonical typed resolution.

Parameters:

• identifier (str | SceneEntityRef) – Canonical ID, alias, or typed canonical reference.

• expected_type (type[TypeVar(RefT, bound= SceneEntityRef)]) – Required reference class.

Return type:

SceneEntityRegistration

Returns:

A structurally independent copy of the matching registration.

make_planning_scene_provider(motion_generator, *, batch_size, translation_threshold=0.0001, rotation_threshold=0.001)

Create a provider after complete planner/registry validation.

Parameters:

• motion_generator (MotionGenerator) – Motion generator that will consume dynamic poses.

• batch_size (int) – Number of execution environments.

• translation_threshold (float) – Accumulated translation needed to publish a material scene change.

• rotation_threshold (float) – Accumulated rotation needed to publish a material scene change.

Return type:

RegistrySceneProvider

Returns:

A new independently stateful, planner-validated scene provider.

make_scene_provider(*, translation_threshold=0.0001, rotation_threshold=0.001, batch_size=None)

Create an independent provider without planner cross-validation.

This factory is intended for perception and direct-core consumers. The canonical planning path must use make_planning_scene_provider() so planner IDs, capabilities, and collision-world mode cannot drift.

Parameters:

• translation_threshold (float) – Accumulated translation needed to publish a material scene change.

• rotation_threshold (float) – Accumulated rotation needed to publish a material scene change.

• batch_size (int | None) – Optional fixed integration batch size. Supplying it validates the collision-world mode immediately and binds the provider to that row count.

Return type:

RegistrySceneProvider

Returns:

A new provider with independent revisions and published baselines.

object_semantics(object_ref, *, affordance)

Build one owned atomic-action semantic snapshot.

Parameters:

• object_ref (str | SceneObjectRef) – Canonical object ID, alias, or typed reference.

• affordance (str | SceneAffordanceRef) – Registered direct-child affordance for the object.

Return type:

ObjectSemantics

Returns:

Object semantics with an owned affordance payload and canonical ID.

Raises:

ValueError – If the affordance does not belong to the object.

property registrations: tuple[SceneEntityRegistration, ...]

Return structurally independent registration values.

resolve(identifier, *, expected_type=<class 'embodichain.lab.task_program.semantics.scene.SceneEntityRef'>)

Resolve a canonical ID or alias to a typed canonical reference.

Parameters:

• identifier (str | SceneEntityRef) – Canonical ID, alias, or already typed canonical ref.

• expected_type (type[TypeVar(RefT, bound= SceneEntityRef)]) – Required reference class for typed lookup.

Return type:

TypeVar(RefT, bound= SceneEntityRef)

Returns:

Registry-owned canonical reference.

Raises:

• KeyError – If the canonical ID or alias is unknown.

• TypeError – If the supplied or resolved reference has the wrong type.

resolve_affordance(parent, *, capability, explicit=None)

Select one compatible affordance with strict scoped-default rules.

Parameters:

• parent (str | SceneEntityRef) – Entity that directly owns the affordance.

• capability (str) – Required semantic affordance capability.

• explicit (str | SceneAffordanceRef | None) – Optional explicit affordance ID or typed reference.

Return type:

SceneAffordanceRef

Returns:

One canonical compatible affordance reference.

Raises:

• UnsupportedSceneAffordanceError – If no compatible affordance exists or an explicit affordance has the wrong parent/capability.

• AmbiguousSceneAffordanceError – If multiple candidates exist without a scoped default.

resolve_collision_world_mode(*, batch_size)

Resolve the configured collision mode for an execution batch.

Parameters:

batch_size (int) – Number of execution environments.

Return type:

SceneCollisionWorldMode | None

Returns:

The effective mode, or None when no dynamic collision entity is registered.

property static_collision_entity_ids: tuple[str, ...]

Return canonical IDs baked into the static planner world.

validate_collision_integration(motion_generator, *, batch_size, scene_provider=None)

Validate registry/planner agreement before dynamic planning.

Parameters:

• motion_generator (MotionGenerator) – Motion generator whose planner consumes obstacles.

• batch_size (int) – Number of execution environments.

• scene_provider (SceneProvider | None) – Optional external perception or hardware provider. Its concrete collision_entity_ids must agree exactly with the registry and planner declarations.

Return type:

SceneCollisionWorldMode | None

Returns:

Effective dynamic collision mode, or None without dynamic IDs.

class embodichain.lab.task_program.semantics.scene.SupportSurfaceAffordance

Typed target frame for placing an object’s origin on a support surface.

The registered affordance pose is the desired object pose, expressed relative to its parent scene entity. The optional confidence threshold is enforced whenever that late-bound target pose is resolved.

Parameters:

minimum_confidence (float) – Minimum confidence accepted while resolving the late-bound target pose.

Methods:

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

__init__(object_label='', custom_config=<factory>, minimum_confidence=0.0)

exception embodichain.lab.task_program.semantics.scene.UnsupportedSceneAffordanceError

Raised when a parent has no affordance for a required capability.

embodichain.lab.sim.motion.solvers.neural_ik_solver

NeuralIKSolverCfg	Configuration for the neural network IK solver.
NeuralIKSolver	IK solver using a trained neural network policy.

embodichain.lab.sim.motion.solvers.null_space_posture_task

NullSpacePostureTask

Pink-based task that adds a posture objective that is in the null space projection of other tasks.

embodichain.lab.sim.motion.solvers.pink_solver

PinkSolver	Iterative task-space IK with adaptive damping and convergence checks.
PinkSolverCfg	Configure the Pink task-space IK solver.

embodichain.lab.sim.motion.solvers.srs_solver

SRSSolver	SRS inverse kinematics (IK) controller.
SRSSolverCfg	Configuration for SRS inverse kinematics controller.

embodichain.lab.sim.utility.render_utils

select_default_renderer([gpu_id])

Select the default renderer backend based on the detected GPU.

embodichain.lab.sim.motion.workspace.caches.cache_utils

clean_all_sessions()	Clean all cache sessions.
clean_session(session_name)	Clean a specific cache session.
format_size(bytes_size)	Format bytes to human-readable size.
get_cache_root()	Get the root cache directory.
get_dir_size(path)	Calculate total size of a directory in bytes.
list_sessions()	List all cache sessions.
main([argv])	Run the backward-compatible workspace analyzer cache CLI.
show_session_info(session_name)	Show detailed information about a cache session.
show_total_size()	Show total cache size.

embodichain.lab.sim.motion.workspace.caches.results_cache

DEFAULT_RESULTS_CACHE_DIR	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
ResultsCache	Disk cache for workspace results, keyed by robot and parameters.
compute_cache_key(metadata)	Compute a stable, readable key for analysis inputs.
serialize_results(results)	Split an analysis results dict into array and meta parts.
deserialize_results(arrays, meta)	Reconstruct an analysis results dict from arrays and metadata.

embodichain.lab.sim.motion.workspace.constraints.base_constraint

IConstraintChecker	Interface for constraint checkers.
BaseConstraintChecker	Abstract base class for workspace constraint checkers.

embodichain.lab.sim.motion.workspace.constraints.workspace_constraint

WorkspaceConstraintChecker

Workspace constraint checker for robotic workspace analysis.

embodichain.lab.sim.motion.workspace.samplers.base_sampler

ISampler	Interface for all samplers.
BaseSampler	Abstract base class for all samplers.

embodichain.lab.sim.motion.workspace.samplers.gaussian_sampler

GaussianSampler

Gaussian (Normal distribution) sampler.

embodichain.lab.sim.motion.workspace.samplers.halton_sampler

HaltonSampler

Halton sequence sampler using quasi-random low-discrepancy sequences.

embodichain.lab.sim.motion.workspace.samplers.importance_sampler

ImportanceSampler

Importance sampler using weighted distribution.

embodichain.lab.sim.motion.workspace.samplers.iniform_sampler

UniformSampler

Uniform grid sampler.

embodichain.lab.sim.motion.workspace.samplers.lhs_sampler

LatinHypercubeSampler

Latin Hypercube Sampler (LHS) for stratified sampling.

embodichain.lab.sim.motion.workspace.samplers.random_sampler

RandomSampler

Random sampler using uniform distribution.

embodichain.lab.sim.motion.workspace.samplers.sobol_sampler

SobolSampler

Sobol sequence sampler using quasi-random low-discrepancy sequences.

embodichain.lab.sim.motion.workspace.visualizers.axis_visualizer

AxisVisualizer

Visualizer for coordinate axes/frames at specified poses.

embodichain.lab.sim.motion.workspace.visualizers.base_visualizer

IVisualizer	Interface for all visualizers.
BaseVisualizer	Abstract base class for all visualizers.

embodichain.lab.sim.motion.workspace.visualizers.point_cloud_visualizer

PointCloudVisualizer

Point cloud visualizer using SimulationManager, Viser, or local tools.

embodichain.lab.sim.motion.workspace.visualizers.sphere_visualizer

SphereVisualizer

Sphere-based visualizer using Open3D or matplotlib.

embodichain.lab.sim.motion.workspace.visualizers.visualizer_factory

VisualizerFactory	Factory class for creating visualizers (Singleton pattern).
create_visualizer([viz_type])	Convenience function to create a visualizer.

embodichain.lab.sim.motion.workspace.visualizers.voxel_visualizer

VoxelVisualizer

Voxel grid visualizer using Open3D or matplotlib.

embodichain.lab.visualization.backends

VisualizationBackend	Lifecycle and publishing contract for live visualization backends.
ViserBackend	Map backend-neutral scene snapshots onto a Viser server.

embodichain.lab.visualization.backends.base

VisualizationBackend

Lifecycle and publishing contract for live visualization backends.

embodichain.lab.visualization.backends.viser

ViserBackend

Map backend-neutral scene snapshots onto a Viser server.

embodichain.lab.visualization.cfg

VisualizationCfg	Configure live scene visualization.
ViserServerCfg	Configure the local Viser HTTP/WebSocket server.

embodichain.lab.visualization.cli

add_viser_args_to_parser(parser)	Add the standard EmbodiChain Viser command-line options.
visualization_cfg_from_args(args)	Build visualization configuration from parsed CLI arguments.

embodichain.lab.visualization.picker

Browser picking caches triangle geometry and returns the closest node hit by a world-space ray. The Viser worker pairs this geometry with poses from the same scene revision before producing a pick command.

ScenePicker

Resolve a world-space ray to the closest hit scene node.

class embodichain.lab.visualization.picker.ScenePicker

Resolve a world-space ray to the closest hit scene node.

Geometry is cached per geometry_id in local coordinates. Each pick transforms the ray into every instance’s local frame (so cached triangle data is reused across instances and across frames) and runs a vectorized Möller-Trumbore test, keeping the smallest positive ray parameter.

Parameters:

epsilon (float) – Lower bound for accepted ray parameters, in world length units.

Methods:

__init__([epsilon])
clear()	Drop all cached geometry.
pick(ray_origin, ray_direction, instances)	Return the node id of the closest instance hit by the ray.
remove_geometry(geometry_id)	Drop one cached geometry.
set_geometry(geometry_id, vertices, faces)	Cache one geometry's triangle data in local coordinates.

__init__(epsilon=1e-09)

clear()

Drop all cached geometry.

Return type:

None

pick(ray_origin, ray_direction, instances)

Return the node id of the closest instance hit by the ray.

Each instance is a (node_id, geometry_id, position, wxyz) tuple, where position is the world-space translation and wxyz is the normalized [w, x, y, z] quaternion. The ray is transformed into each instance’s local frame so the cached local geometry can be reused.

Parameters:

• ray_origin (ndarray) – World-space ray origin with shape (3,).

• ray_direction (ndarray) – World-space ray direction with shape (3,). It is normalized internally so the returned hit distance is in world length units.

• instances (Iterable[tuple[str, str, ndarray, ndarray]]) – Iterable of scene instances to test.

Return type:

str | None

Returns:

The closest hit node_id, or None if the ray misses every instance.

remove_geometry(geometry_id)

Drop one cached geometry.

Return type:

None

set_geometry(geometry_id, vertices, faces)

Cache one geometry’s triangle data in local coordinates.

Parameters:

• geometry_id (str) – Stable geometry identifier from the scene manifest.

• vertices (ndarray) – Triangle mesh vertices with shape (V, 3).

• faces (ndarray) – Triangle indices into vertices with shape (F, 3).

Return type:

None

embodichain.lab.visualization.protocol

SCHEMA_VERSION	int([x]) -> integer int(x, base=10) -> integer
CameraImage	One detached RGB image associated with a manifest camera.
CameraImageFrame	Low-frequency RGB images captured at one simulation timestamp.
CameraSpec	Static pinhole-camera parameters for one environment instance.
DynamicMeshUpdate	Detached vertex positions for one deformable scene node.
FrameOverlay	Coordinate frame overlay.
GizmoCommand	Immutable browser drag command consumed on the simulation thread.
GizmoSpec	Static description of one simulation Gizmo exposed by a backend.
GizmoState	Authoritative world pose and visibility of one simulation Gizmo.
JointControlCommand	Immutable browser joint command consumed on the simulation thread.
JointControlProvider	Simulation-thread source of optional articulation joint controls.
JointControlSpec	Static description of one scalar articulation joint control.
JointControlState	Authoritative value and command acknowledgement for one joint control.
MeshGeometry	Backend-neutral triangle mesh stored in local coordinates.
PickCommand	Immutable browser click-pick command consumed on the simulation thread.
PointCloudOverlay	Point cloud overlay with per-cloud or per-point RGB colors.
SceneFrame	Dynamic poses and overlays for one simulation sample.
SceneManifest	Static scene topology and geometry for one scene revision.
SceneNode	One mesh-bearing logical node in a scene manifest.
SceneOverlays	All optional overlays attached to a dynamic frame.
TargetOverlay	Target pose overlay rendered as a coordinate frame.
TrajectoryOverlay	Polyline trajectory overlay.
estimate_camera_image_frame_bytes(frame)	Estimate NumPy image bytes retained by a camera image frame.
estimate_frame_bytes(frame)	Estimate NumPy payload bytes retained by a frame.
estimate_manifest_bytes(manifest)	Estimate binary geometry bytes retained by a manifest.
pose_to_position_wxyz(pose)	Split pose arrays into positions and normalized wxyz quaternions.

embodichain.lab.visualization.runtime

GizmoCommandQueue	Bounded command queue that coalesces high-rate drag updates.
JointControlCommandQueue	Bounded queue that keeps only the newest value for each joint control.
LatestFrameQueue	A one-slot queue where producers replace an unconsumed old frame.
RuntimeHealth	Current visualization runtime health and connection state.
RuntimeStats	Snapshot of scene and camera-image capture/upload telemetry.
VisualizationRuntime	Run scene capture and a visualization backend without blocking simulation.

embodichain.lab.visualization.scene_exporter

CameraImageCaptureResult	Captured RGB images and the time spent rendering and copying them.
CaptureResult	A captured frame and the time spent copying scene data.
SceneExporter	Capture backend-neutral scene data from a SimulationManager.
mesh_geometry_id(vertices, faces[, color])	Compute a stable content identifier for local mesh geometry and color.
safe_path_component(value)	Encode an arbitrary identifier as one stable Viser path component.

embodichain.learning.rl.algo.apg

APG	Optimize policy parameters through differentiable rollout rewards.
APGCfg	Analytic policy-gradient config.
segmented_discounted_return(rollout, gamma)	Compute one discounted return per environment within a rollout segment.

embodichain.learning.rl.algo.base

BaseAlgorithm	Base class for RL algorithms.
RolloutKind	Rollout semantics required by an algorithm.

embodichain.learning.rl.algo.common

compute_gae(rollout, gamma, gae_lambda)

Compute GAE over a rollout stored as [num_envs, time + 1].

embodichain.learning.rl.algo.grpo

GRPO	Group Relative Policy Optimization on top of TensorDict rollouts.
GRPOCfg	Configuration for GRPO.

embodichain.learning.rl.algo.ppo

PPO	PPO algorithm consuming TensorDict rollouts.
PPOCfg	Configuration for the PPO algorithm.

embodichain.learning.rl.collector.base

BaseCollector

Base class for rollout collectors.

embodichain.learning.rl.collector.differentiable

DifferentiableCollector	Collect graph-preserving rollouts without a preallocated buffer.
DifferentiableRollout	An immutable sequence of graph-preserving transitions.
DifferentiableTransition	One graph-preserving environment transition.

embodichain.learning.rl.collector.sync_collector

SyncCollector

Synchronously collect rollouts from a vectorized environment.

embodichain.learning.rl.experimental.newton

NewtonPlanarReachEnv	Batched differentiable two-link reach environment using Newton FK.
NewtonPlanarReachEnvCfg	Configuration for the temporary two-link Newton reach environment.

embodichain.learning.rl.experimental.newton.planar_reach

NewtonPlanarReachEnv	Batched differentiable two-link reach environment using Newton FK.
NewtonPlanarReachEnvCfg	Configuration for the temporary two-link Newton reach environment.

embodichain.learning.rl.experimental.newton.train_planar_reach

NewtonPlanarReachTrainingCfg	Configuration for random-target Newton APG training.
train_planar_reach([cfg])	Train on random reaches and evaluate on held-out samples.

embodichain.learning.rl.models.actor_critic

ActorCritic

Actor-Critic with learnable log_std for Gaussian policy.

embodichain.learning.rl.models.actor_only

ActorOnly

Actor-only policy for algorithms that do not use a value function (e.g., GRPO).

embodichain.learning.rl.models.policy

Policy

Abstract base class that all RL policies must implement.

embodichain.learning.rl.utils.optimizer

bind_scheduler_horizon(cfg, total_updates)	Fill total_iters / T_max from the training update budget.
build_lr_scheduler(optimizer, cfg)	Build a scheduler, or None when name is unset.
build_optimizer(parameters[, cfg])
coerce_lr_scheduler_cfg(value)
coerce_optimizer_cfg(value)
get_registered_lr_scheduler_names()
get_registered_optimizer_names()
scheduler_needs_horizon(cfg)

embodichain.toolkits.acd

generate_urdf_collision_convexes(urdf_path, ...)

embodichain.toolkits.acd.cli

main([argv])

Generate convex collision meshes and an updated URDF.

embodichain.toolkits.acd.urdf_modifider

URDFModifider

embodichain.toolkits.graspkit.pg_grasp.antipodal_sampler

AntipodalSamplerCfg	Configuration for AntipodalSampler.
AntipodalSampler	AntipodalSampler samples antipodal point pairs on a given mesh.

embodichain.toolkits.graspkit.pg_grasp.collision_checker

ConvexCollisionCheckerCfg	Configuration for ConvexCollisionChecker.
ConvexCollisionChecker	ConvexCollisionChecker performs efficient collision checking between a batch of query point clouds and a convex decomposition of a mesh.

embodichain.toolkits.graspkit.pg_grasp.gripper_collision_checker

GripperCollisionCfg	Configuration for the GripperCollisionChecker.
GripperCollisionChecker
box_surface_grid(size, dense[, device])	Generate grid-sampled points on the surface of an axis-aligned box.

embodichain.toolkits.graspkit.scripts.annotate_grasp

cli([argv])

Command-line interface for grasp pose annotation.

embodichain.toolkits.urdf_assembly.component

ComponentRegistry	Registry for storing and retrieving URDFComponent objects.
URDFComponent	Represents a URDF component with its configuration and transformation.
URDFComponentManager	Responsible for loading, renaming, and processing meshes for a single component.

embodichain.toolkits.urdf_assembly.connection

URDFConnectionManager

Responsible for managing connection rules between components and sensor attachments.

embodichain.toolkits.urdf_assembly.file_writer

URDFFileWriter

Responsible for formatting XML and writing URDF files with proper headers.

embodichain.toolkits.urdf_assembly.logging_utils

URDFAssemblyLogger

URDF Assembly module-specific logger manager

embodichain.toolkits.urdf_assembly.mesh

URDFMeshManager

Responsible for copying, renaming, and handling dependencies of mesh files.

embodichain.toolkits.urdf_assembly.sensor

SensorRegistry	Registry for storing and retrieving SensorAttachment objects.
SensorAttachment	Represents a sensor attachment configuration to a robot component.
URDFSensorManager	Responsible for loading, processing, and managing sensor attachments.

embodichain.toolkits.urdf_assembly.signature

URDFAssemblySignatureManager

Simple MD5-based signature manager for URDF assemblies without persistent cache.

embodichain.toolkits.urdf_assembly.urdf_assembly_manager

URDFAssemblyManager

A class to manage the assembly of URDF files and their components.

embodichain_tasks.classic_control.cart_pole

Cart-pole environment registration under the task-first import path.

CartPoleEnv

CartPole balancing task for reinforcement learning.

embodichain_tasks.classic_control.point_mass

Differentiable lightweight point-mass task and learning-environment registration.

PointMassEnv

Navigate a damped point mass to a goal while avoiding two obstacles.

embodichain_tasks.configs

get_config_path([relative_path])

Return an installed official-task config path.

embodichain_tasks.manipulation.push_cube

PushCubeEnv

Push cube task for reinforcement learning.

embodichain_tasks.manipulation.tableware.blocks_ranking_rgb

BlocksRankingRGBEnv

Arrange the red and blue blocks around the stationary green block.

embodichain_tasks.manipulation.tableware.blocks_ranking_size

BlocksRankingSizeEnv

embodichain_tasks.manipulation.tableware.match_object_container

MatchObjectContainerEnv

embodichain_tasks.manipulation.tableware.place_object_drawer

PlaceObjectDrawerEnv

embodichain_tasks.manipulation.tableware.scoop_ice

ScoopIce

Scoop-ice expert task restricted to one simulation environment.

embodichain_tasks.manipulation.tableware.stack_blocks_two

StackBlocksTwoEnv

Pick up block_2 and place it on block_1 as one segment.

embodichain_tasks.manipulation.tableware.stack_cups

StackCupsEnv

embodichain_tasks.special.simple_task

SimpleTaskEnv

A demo environment with sinusoidal trajectory

embodichain_tasks.special.stay_still_save

StayStillSaveEnv

Robot holds still for 100 steps while a camera records.

embodichain_tasks.utils.importer

import_packages(package_name[, blacklist])

Recursively import all modules below package_name.