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

The public data namespace exposes dataset resolution, legacy database locations, and resource metadata. Its asset namespace loads on first access so extension asset definitions can import the dataset base without circular initialization.

assets	Preset configuration objects for scene assets (robots, end-effectors, objects, materials, sensors, planners, solvers, demo scenes) ready to reference from task configs.
EMBODICHAIN_DEFAULT_DATABASE_ROOT	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
database_dir	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
database_2d_dir	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
database_agent_prompt_dir	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
database_demo_dir	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
EmbodiChainDataset
DEFAULT_DATA_MODULES	Built-in mutable sequence.
get_data_class(dataset_name[, extra_modules])	Resolve a dataset class from the shared asset catalog or extra modules.
get_data_path(data_path_in_config)	Get the absolute path of the data file.
list_default_materials()	List the 24 public presets without downloading assets or creating a World.
get_default_material_info(name)	Read independent metadata for a public preset or auxiliary resource.

embodichain.data.assets.demo_assets

Downloadable bundles used by standalone manipulation and deformable-body demos. Each class resolves one versioned archive into the configured EmbodiChain data cache.

CoordinatedPlacementAndPickment	Downloadable meshes for coordinated placement and pickment tutorials.
DeformableDemoData	Shared cloth-twist and W1 T-shirt-folding demo assets.
MultiW1Data	Downloadable scene assets for multi-W1 manipulation demos.
RubiksCube	Downloadable articulated Rubik's-cube asset for manipulation demos.
ScoopIceNewEnv	Downloadable meshes and robot assets for the scoop-ice demo.
TabletopFourBases	Portable tabletop scene for grouped and intra-group layout demos.

embodichain.data.assets.materials

Material, environment-map and background bundles use the shared asset cache. DefaultMaterials downloads the pinned 18-preset collection and its auxiliary soap-film layer; it does not create a simulator World.

SimResources
EnvMapHDR
CocoBackground
BackgroundTexture	Download the bundled background-texture collection.
DefaultMaterials	Lazily download the pinned default-material collection.

class embodichain.data.assets.materials.DefaultMaterials

Lazily download the pinned default-material collection.

Parameters:

data_root (str | None) – Optional data cache root. Each resource revision has its own locked cache entry. EMBODICHAIN_DOWNLOAD_PREFIX selects a mirror containing the catalog’s versioned archive path; otherwise the original DexSim resource server is used (requires network access).

Methods:

__init__([data_root])
__new__(**kwargs)
get_material_path(name)	Get an authored preset directory in this verified resource revision.

__init__(data_root=None)

__new__(**kwargs)

get_material_path(name)

Get an authored preset directory in this verified resource revision.

Parameters:

name (str) – Downloadable resource preset or SoapBubbleInterior.

Return type:

str

Returns:

Absolute path suitable for DexSim’s native material loader.

Raises:

ValueError – The name is unknown or denotes a built-in parameter preset, which has no directory in this archive.

embodichain.data.assets.planner_assets

download_neural_planner_checkpoint([...])

Download a neural planner checkpoint from HuggingFace.

embodichain.data.assets.policy_assets

Resolve one official model ID to a pinned repository snapshot and materialize its native RUN files inside the model cache. The returned provenance records the exact repository and revision used for evaluation.

download_pretrained_policy(model_id, *[, ...])

Download one official native policy and identify its repository snapshot.

embodichain.data.assets.policy_assets.download_pretrained_policy(model_id, *, revision=None, cache_dir=None)

Download one official native policy and identify its repository snapshot.

Files are materialized inside one revision-specific directory so relative RunManifest paths stay within the downloaded run. Robot assets continue to use the task’s normal asset resolver. Bundles contain checkpoint.pt, run-manifest.json, configs/train.yaml, configs/env.yaml and evaluation.json. Commit-pinned files reuse the Hub’s local cache. Requests use the canonical endpoint regardless of HF_ENDPOINT; standard HTTP proxy environment variables still apply.

Parameters:

• model_id (str) – Model directory name from the official repository’s index.

• revision (str | None) – Hub commit, tag or branch; defaults to a tested commit.

• cache_dir (str | Path | None) – Model cache root; defaults to ~/.cache/embodichain/policies.

Return type:

tuple[Path, dict[str, str]]

Returns:

Local RUN directory and source fields (repo_id, revision, model_id).

Raises:

• ValueError – The model ID, index schema or policy format is unsupported.

• ImportError – The model’s task package is not installed.

• RuntimeError – The model files cannot be downloaded.

embodichain.data.assets.solver_assets

download_neural_ik_checkpoint([repo_id, ...])

Download a neural IK solver checkpoint from HuggingFace.

embodichain.data.assets.w1_assets

Versioned W1 URDF archives use the shared data-root and download cache. V021 provides separate body components; V022 and V025 bundle the full robot and components. V030 packages the standard 20-DOF body without detachable grippers or wrist-camera attachments. Its component visuals and inertials match the corrected full-body definition.

DexforceW1V021	Dataset class for the Dexforce W1 V021.
DexforceW1V022	Dataset class for the unified Dexforce W1 V022 release archive.
DexforceW1V025	Dataset class for the unified Dexforce W1 V025 release archive.
DexforceW1V030	Standard V030 body archive, excluding detachable end effectors.
DexforceW1ChassisV021
DexforceW1TorsoV021
DexforceW1EyesV021
DexforceW1HeadV021
DexforceW1LeftArmV021
DexforceW1RightArmV021

class embodichain.data.assets.w1_assets.DexforceW1V021

Dataset class for the Dexforce W1 V021.

Directory structure:

DexforceW1V021/DexforceW1V021.urdf

Example usage:

>>> from embodichain.data import get_data_path
>>> print(get_data_path("DexforceW1V021/DexforceW1_v02_1.urdf"))

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1V022

Dataset class for the unified Dexforce W1 V022 release archive.

Expected Hugging Face path and archive layout:

dexforce_w1/v022/w1.zip
w1/robot.urdf
w1/chassis.urdf
w1/torso.urdf
w1/head.urdf
w1/left_arm.urdf
w1/right_arm.urdf

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1V025

Dataset class for the unified Dexforce W1 V025 release archive.

Expected Hugging Face path and archive layout:

dexforce_w1/v025/w1.zip
w1/robot.urdf
w1/chassis.urdf
w1/torso.urdf
w1/head.urdf
w1/left_arm.urdf
w1/right_arm.urdf

The same archive supports both direct full-robot loading and component assembly, so runtime code does not download duplicate component archives.

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1V030

Standard V030 body archive, excluding detachable end effectors.

The archive is published at dexforce_w1/v030/w1.zip with w1/robot.urdf and the five component URDFs. Component visuals and inertials match the corrected full body. Its yellow and dark plastic materials match V021. Wrist camera and gripper assets belong to independently assembled attachments.

Parameters:

data_root (str | None) – Download and extraction cache root. Defaults to the configured EmbodiChain asset cache.

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1ChassisV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1TorsoV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1EyesV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1HeadV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1LeftArmV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

class embodichain.data.assets.w1_assets.DexforceW1RightArmV021

Methods:

__init__([data_root])
__new__(**kwargs)

__init__(data_root=None)

__new__(**kwargs)

embodichain.data.default_materials

The wheel includes catalog metadata so these functions work offline without asset downloads. Both functions are also available from embodichain.data. The 24-preset catalog combines six built-in parameter definitions and 18 downloadable resources; metadata identifies their source and download requirement. Metadata includes compatible renderer names, source revision, dependencies, auxiliary resources and suggested physical texture dimensions. Dimensions do not change geometry or UVs.

list_default_materials()	List the 24 public presets without downloading assets or creating a World.
get_default_material_info(name)	Read independent metadata for a public preset or auxiliary resource.

embodichain.data.default_materials.list_default_materials()

List the 24 public presets without downloading assets or creating a World.

Return type:

list[str]

Returns:

Preset names in catalog order. Auxiliary resources are omitted.

embodichain.data.default_materials.get_default_material_info(name)

Read independent metadata for a public preset or auxiliary resource.

Parameters:

name (str) – Case-sensitive catalog name, including SoapBubbleInterior.

Return type:

dict[str, Any]

Returns:

Description, source, download requirement, supported renderers, dependencies, geometry guidance and source revision. Built-in presets also include their native parameter defaults and have no texture size. Suggested resource sizes do not change UVs.

Raises:

ValueError – The name is not in the built-in catalog.

embodichain.data.list_default_materials()

List the 24 public presets without downloading assets or creating a World.

Return type:

list[str]

Returns:

Preset names in catalog order. Auxiliary resources are omitted.

embodichain.data.get_default_material_info(name)

Read independent metadata for a public preset or auxiliary resource.

Parameters:

name (str) – Case-sensitive catalog name, including SoapBubbleInterior.

Return type:

dict[str, Any]

Returns:

Description, source, download requirement, supported renderers, dependencies, geometry guidance and source revision. Built-in presets also include their native parameter defaults and have no texture size. Suggested resource sizes do not change UVs.

Raises:

ValueError – The name is not in the built-in catalog.

embodichain.data_pipeline

The configuration submodule derives bounded pipeline settings without starting an online worker. Importing the data-pipeline package remains lazy.

configuration

Derive bounded ODS consumption and cache settings from measured capacities.

embodichain.data_pipeline.configuration

Configure ODS from measured generation and training capacities. A versioned profile bounds selections per trajectory; the planner never promotes provisional bounds to qualified ones. Runtime metadata constrains cache storage, refill latency and short-window consumption. The online engine and consumer must enforce the returned quota and pacing targets. Measurement helpers preserve the units, common monotonic window and difference between active and wall-clock rates.

ODSReuseProfileCfg	Explicit task/model/sampler qualification and selection-budget bounds.
ODSRuntimeCfg	Measured runtime settings and optional total cache-storage allowance.
ODSConfiguration	Derived settings and their qualifications; no runtime state is changed.
configure_ods(accepted_episodes_per_second, ...)	Plan quota-protected ODS settings from two concurrent capacity estimates.
ODSRateMeasurementCfg	Count and active duration within an explicit absolute monotonic window.
ODSThroughputMeasurement	Active capacities and realized wall rates, kept distinct by unit.
measure_ods_throughput(production, training)	Calculate rates for matching monotonic windows with explicit count units.

class embodichain.data_pipeline.configuration.ODSReuseProfileCfg

Explicit task/model/sampler qualification and selection-budget bounds.

scope identifies task, model, history/horizon and trajectory-length assumptions. qualified=False is a supported provisional profile, not a claim that its recommended bounds are scientifically safe.

Methods:

__init__([profile_id, scope, qualified, ...])
copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

__init__(profile_id=<factory>, scope=<factory>, qualified=<factory>, min_chunks_per_episode=<factory>, max_chunks_per_episode=<factory>, hard_max_chunks_per_episode=<factory>, latency_safety_factor=<factory>)

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

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

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

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

class embodichain.data_pipeline.configuration.ODSRuntimeCfg

Measured runtime settings and optional total cache-storage allowance.

cache_memory_bytes and bytes_per_episode must be supplied together. The allowance is for episode storage only; the caller must reserve worker, model and allocator memory separately. B and P are preserved unchanged.

Methods:

__init__([batch_size, producer_envs, ...])
copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

__init__(batch_size=<factory>, producer_envs=<factory>, first_publication_p95_seconds=<factory>, cache_memory_bytes=<factory>, bytes_per_episode=<factory>, min_cache_episodes=<factory>, measurement_scope=<factory>)

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

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

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

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

class embodichain.data_pipeline.configuration.ODSConfiguration

Derived settings and their qualifications; no runtime state is changed.

Methods:

__init__(episode_sample_budget, ...[, ...])

__init__(episode_sample_budget, episode_sample_hard_limit, balance_chunks_per_episode, batch_size, producer_envs, buffer_size, cache_bytes, initial_chunk_budget, initial_max_updates, initial_remainder_chunks, refill_remaining_chunks, active_chunks_per_second_cap, training_chunks_per_second_target, training_updates_per_second_target, publication_episodes_per_second_target, training_duty_fraction, producer_duty_fraction, expected_training_throttle_fraction, expected_producer_throttle_fraction, profile_id, profile_scope, profile_qualified, measurement_scope, reasons, end_of_supply_rule='Stop when remaining unlocked per-episode quota cannot fund one full batch.')

embodichain.data_pipeline.configuration.configure_ods(accepted_episodes_per_second, training_chunks_per_second, *, profile, runtime)

Plan quota-protected ODS settings from two concurrent capacity estimates.

Parameters:

• accepted_episodes_per_second (float) – Published successful trajectories per production second, including retry cost; not an idle whole-run rate.

• training_chunks_per_second (float) – Completed chunk selections per active learner second, including sampling, transfers and optimization.

• profile (ODSReuseProfileCfg) – Explicit qualified or provisional selection-budget policy.

• runtime (ODSRuntimeCfg) – Batch, writer parallelism, latency and storage metadata.

Return type:

ODSConfiguration

Returns:

Budget, active and average pacing targets, cache and refill controls. The cache heuristic assumes one writer batch is unavailable. Its active cap must be enforced over short windows, not as post-burst average sleep.

Raises:

• ValueError – Invalid metadata, unrepresentable derived values, or memory too small for the writer, diversity and a full unlocked batch.

• TypeError – Profile or runtime has the wrong configuration type.

class embodichain.data_pipeline.configuration.ODSRateMeasurementCfg

Count and active duration within an explicit absolute monotonic window.

Methods:

__init__([unit, count, ...])
copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

__init__(unit=<factory>, count=<factory>, start_monotonic_seconds=<factory>, end_monotonic_seconds=<factory>, active_seconds=<factory>)

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

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

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

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

class embodichain.data_pipeline.configuration.ODSThroughputMeasurement

Active capacities and realized wall rates, kept distinct by unit.

Methods:

__init__(...)

__init__(accepted_episodes_per_active_second, accepted_episodes_per_wall_second, training_chunks_per_active_second, training_chunks_per_wall_second, window_seconds)

embodichain.data_pipeline.configuration.measure_ods_throughput(production, training)

Calculate rates for matching monotonic windows with explicit count units.

Counts may be zero; active durations must be positive and no longer than the window. A shared window alone does not prove simultaneous saturation: callers must record production/learner overlap and measurement scope separately.

Return type:

ODSThroughputMeasurement

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.cli.randomization

Command-line entry point for grouped layout generation from an existing Scene Engine workspace. Validates the YAML policy, prepares a reusable baseline and saves successful candidates with a completion manifest.

main([argv])

Prepare a baseline, generate layouts and save a new run directory.

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.scene_engine.pipeline.utils.usd_scene

Entity metadata and deterministic UID indexing for schema-v2 USD scene stages.

USD_SCENE_SCHEMA	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
UsdEntityBinding	One USD entity paired with its simulator facade.
UsdEntityDesc	One EmbodiChain entity authored on a USD prim.
UsdSceneBinding	Map one USD entity index to DexSim/EmbodiChain runtime objects.
UsdSceneIndex	Index EmbodiChain entity metadata from one USD stage.

embodichain.gen_sim.scene_engine.randomization.adapter

scene_layout_input_from_export(output_root, *)	Read scaled local Z-up geometry without modifying its source export.
randomize_scene_export(output_root, config)	Generate a v4 run after the final Scene Engine export.
convert_layouts(layout_dir, output_dir, *[, ...])	Convert validated legacy layouts without resampling or changing identity.

embodichain.gen_sim.scene_engine.randomization.baseline

Extracts one table work area, group AABBs and root-relative member poses from rigid GLB exports. A group contains a direct table child and all descendants. The baseline cache is reused only when source identity, extraction version, structure and checksum match; preparation leaves the source export untouched.

PreparedSceneBaseline	Result of preparing a persisted scene randomization baseline.
prepare_scene_baseline(cfg, *[, rebuild])	Validate a portable scene and persist its reusable grouped baseline.

embodichain.gen_sim.scene_engine.randomization.cfg

Loads a closed, versioned YAML policy and resolves the workspace’s scene_export/ input and scene_randomization_base.yaml baseline path. The workspace is supplied separately through output_root. For example:

schema_version: 1
seed: 42
candidate_count: 10
max_attempts: 1000
collision_margin_m: 0.02

Generate and save layouts, then cycle the original scene and saved candidates:

embodichain scene-randomization --output_root ./workspace --config policy.yaml
python -m embodichain.gen_sim.scene_engine.randomization.loading \
    --layout-dir ./workspace/scene_layouts/run_001/layouts --interval 3

Version 3 adds hierarchical member XY/yaw sampling on CPU or CUDA:

schema_version: 3
backend: batched
device: cuda:0
randomize_groups: true
intra_group:
  targets:
    mug_001:
      xy_offset_bounds_m: null
      yaw_delta_range_deg: [-180, 180]

randomize_groups: false holds group roots fixed. Unselected members retain parent-relative poses and follow moved ancestors. XY bounds, when supplied as [[min_x, min_y], [max_x, max_y]], bound the original entity origin’s offset in its parent support frame. A null bound uses the complete feasible region. Yaw increments rotate around the support normal while retaining authored tilt. Defaults are 2 mm boundary and sibling margins, 1 mm support gap and 1 mm grid resolution. intra_group.support_overrides accepts parent UID entries with a proper rigid parent_from_support matrix and GeoJSON polygon; overrides must have mesh support evidence. Invalid polygons are rejected during policy loading before scene preparation. Ambiguous automatic layers raise an error. The positive height deviation of the selected near-planar layer is included in its conservative support height, retaining the configured minimum gap over shallow raised geometry.

Content-addressed geometry caches leave the original baseline unchanged. Hierarchical layouts save v3 root XY translations and full selected member poses relative to their parents, using JSON or packed storage. Replay validates source, cache, policy, geometry and identity before exposing lazy variants and does not sample again. The existing v1/v2 group layouts and earlier v3 hierarchical layouts remain readable. New hierarchical proposals use algorithm version 2: dynamic group centers are sampled from the remaining free rectangular area without nested retries. Support caches use extraction version 2 and include a conservative layer height ceiling; older caches retain their recorded height semantics on replay. Saving compares the on-disk cache against the generated snapshot before publishing a completed run.

MemberRandomizationCfg	One non-root member's displacement bounds in its parent support frame.
SupportOverrideCfg	Explicit parent-local support frame and GeoJSON Polygon/MultiPolygon.
IntraGroupRandomizationCfg	Explicit member selection and conservative support geometry settings.
SceneRandomizationCfg	Resolved scene paths and grouped layout generation parameters.
load_randomization_config(path, *, output_root)	Load a closed version-1, version-2 or hierarchical version-3 policy.

embodichain.gen_sim.scene_engine.randomization.generation

Uses the shared seeded procedural generator and XY layout solver, then expands every group from the same baseline. Successful candidates contain a full SceneFragment and a SceneVariant. Group-only sampling preserves authored orientation and height. Hierarchical sampling changes selected members’ support XY/yaw, aligns their geometric bottom to the support gap and propagates subtrees. Scale and exported collision hull budgets are preserved. Acceptance checks conservative support coverage, sibling/group AABBs and table bounds; it does not establish physical stability or task success.

budget_exhausted is a normal result that retains any successful candidates. The result records actual parameters, proposal attempts and solver outcomes; generation does not save candidates until save_layouts is called.

SceneRandomizationResult	In-memory grouped scene candidates and their generation accounting.
randomize_scene(cfg, *[, seed, ...])	Randomize every support group using shared seeded XY layout generation.

embodichain.gen_sim.scene_engine.randomization.loading

Validates a completed run’s candidate files against its manifest, policy, baseline and unchanged source export, then reconstructs every group member’s absolute pose without generating layouts or rewriting caches. Playback loads assets once and cycles original and candidate poses without advancing physics. Runs with no successful candidates cannot be previewed.

LoadedLayouts	Validated source workspace, original poses and ordered saved variants.
load_layouts(layout_dir)	Read every saved candidate once and reconstruct all group member poses.
preview_layouts(layout_dir, *[, interval, ...])	Cycle original and saved layouts in the existing scene preview window.
main([argv])	Parse standalone saved-layout preview arguments.

embodichain.gen_sim.scene_engine.randomization.persistence

Saves each result in a distinct scene_layouts/run_NNN/ directory containing the resolved policy and candidate group centers. Relative references identify the existing source export and baseline, so those files must remain available and unchanged. The completion manifest is published last, including for a run with zero candidates; interrupted writes may leave a run without that manifest.

save_layouts(result, *, output_root[, ...])

Save successful grouped layouts and generation accounting in a new run.

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.sim.scene.expansion.layout

SceneLayoutInput	Own scaled local mesh geometry and a rooted physical support tree.
PreparedSceneRandomization	Own reusable numeric geometry, policy, permissions and source identity.
SceneRandomizationBatch	Owned lazy proposals and exact bounded generation accounting.
SceneVariantApplicationResult	Selected-row pose publication and host-owned cache invalidations.
scene_layout_input_from_sim(sim, *, ...[, ...])	Snapshot prepared rigid entities through public simulation interfaces.
prepare_scene_randomization(source, policy, *)	Prepare source-independent hierarchy and conservative support geometry.
generate_scene_variants(prepared, *[, seed, ...])	Generate a batch without loading meshes or constructing simulation objects.
apply_scene_variants(sim, variants, *, ...)	Preflight all rows, then batch rigid pose writes without physics steps.

embodichain.lab.sim.scene.expansion.persistence

LoadedSceneVariants	Fully validated source, prepared geometry and lazy saved proposals.
save_scene_variants(result, output_dir, *[, ...])	Publish a v4 layout package, writing the completion manifest last.
load_scene_variants(path, *[, scene_input])	Validate every file, source, geometry and identity before exposing layouts.

embodichain.lab.task_program.integrations.simulation.handover

ConfiguredHandOverPoseProvider

Resolve a hand-over delivery target from immutable configuration.

embodichain.lab.gym.envs.episode_context

Row-local recording eligibility follows the buffered episode, independently of replaceable demo annotations. Synchronous checks retain pending and rejected state across internal resets, and snapshots own their JSON provenance.

EpisodeContext

Keep recording eligibility attached to buffers rather than annotations.

class embodichain.lab.gym.envs.episode_context.EpisodeContext

Keep recording eligibility attached to buffers rather than annotations.

Parameters:

• num_envs (int) – Number of independently reset environment rows.

• device (str | device) – Device used by row masks and returned environment IDs.

A successful reset must initialize a row before it can be recorded. Checks block publication until their synchronous scope closes. Rejection is sticky until the host consumes the old buffers and starts another episode. Context updates and snapshots belong to the creating thread; background writers consume owned snapshots instead of accessing this object.

Methods:

__init__(num_envs[, device])
check(source[, env_ids])	Block selected buffers while a component performs a synchronous check.
filter_recordable([env_ids])	Return owned eligible row IDs in the caller's requested order.
snapshot([env_ids])	Copy JSON provenance and eligibility without advancing any state.

__init__(num_envs, device='cpu')

check(source, env_ids=None)

Block selected buffers while a component performs a synchronous check.

Parameters:

• source (str) – Stable component name, e.g. events/scene_layout.

• env_ids (Sequence[int] | Tensor | None) – Selected rows, or all rows when omitted.

Yields:

A callable that must be invoked exactly once as finish(accepted=bool_or_row_mask, metadata=..., reasons=...). Metadata may be one shared JSON mapping or a mapping from selected integer row IDs to JSON mappings. Reasons may be one string or a row-keyed mapping. Inputs are validated and copied before publication.

Raises:

RuntimeError – For overlapping scopes of the same source, a missing report, or a report attempted after closing the scope.

Return type:

Iterator[Callable[..., None]]

Scopes survive internal resets. Exceptions, including cancellation, reject all selected current buffers even after a successful report. A later check cannot clear an earlier rejection in those buffers.

filter_recordable(env_ids=None)

Return owned eligible row IDs in the caller’s requested order.

Parameters:

env_ids (Sequence[int] | Tensor | None) – Requested rows, or all rows when omitted.

Return type:

Tensor

Returns:

Long tensor on the context device. Pending, uninitialized and previously rejected buffers are excluded independently of task success.

snapshot(env_ids=None)

Copy JSON provenance and eligibility without advancing any state.

Parameters:

env_ids (Sequence[int] | Tensor | None) – Selected rows, or all rows when omitted.

Return type:

list[dict[str, Any]]

Returns:

Owned row dictionaries suitable for info, episode sidecars and asynchronous persistence. Their eligibility does not prove task success.

embodichain.lab.gym.envs.managers.action_manager

ActionTerm	Base class for one independently processed and applied action slice.
ActionManager	Split one flat policy action across independently applied terms.

embodichain.lab.gym.envs.managers.actions

DefaultJointPositionAction	Map normalized actions around a configured default joint pose.
EefPoseAction	Convert an absolute EEF pose into selected-arm joint targets.
JointEffortAction	Apply scaled effort actions to selected joints.
JointPositionAction	Apply absolute position actions to selected joints.
JointPositionToLimitsAction	Map normalized selected-joint actions to position limits.
JointVelocityAction	Apply scaled velocity actions to selected joints.
ParallelGripperAction	Map one scalar policy action to explicit parallel-gripper joints.
RelativeEefPoseAction	Convert normalized arena-frame pose deltas into selected-arm targets.
RelativeJointPositionAction	Add scaled relative actions to current selected positions.

embodichain.lab.gym.envs.managers.action_types

ActionDescriptor	Bind one action-term descriptor to a manager-owned flat slice.
ActionTermDescriptor	Describe one term's raw policy-action representation.
ActionTrace	Capture one policy request and its controller-side action stages.

embodichain.lab.gym.envs.objectives

Optional measured objectives observe ordered stable placement regions independently of Task Program completion, segment acceptance and dataset persistence. Progress advances once per control step; snapshots are pure and partial resets are isolated per environment. Stable region occupancy does not establish gripper detachment.

GoalRegionCfg	Inclusive axis-aligned bounds in environment-local metres.
OrderedPlacementObjectiveCfg	Ordered stable-region observations; these do not prove gripper release.
MeasuredRigidObjectState	Environment-local position and measured velocities, each shaped (N, 3).
OrderedPlacementObjective	Observe ordered stable regions without changing termination or acceptance.

embodichain.lab.gym.envs.objectives.config

Strict declaration decoding resolves a deployment’s objective component relative to its owning configuration and rejects unknown fields and invalid thresholds.

GoalRegionCfg	Inclusive axis-aligned bounds in environment-local metres.
OrderedPlacementObjectiveCfg	Ordered stable-region observations; these do not prove gripper release.
decode_objective(value)	Decode and validate the minimal ordered stable-region declaration.
load_objective_component(selection, *, base_dir)	Load a strict objective: {component: path} relative to its deployment.

embodichain.lab.gym.envs.objectives.ordered_placement

The evaluator consumes measured positions and velocities. Historical milestone progress remains recorded when final-region truth becomes false; returning to the final region requires the configured stable hold duration again.

MeasuredRigidObjectState	Environment-local position and measured velocities, each shaped (N, 3).
OrderedPlacementObjective	Observe ordered stable regions without changing termination or acceptance.

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.preview_material

Query the default catalog without loading simulation dependencies, or render presets and parameter variants with fixed preview settings and managed cleanup.

main(args)	Query or preview default materials using the production preset resolver.
cli([argv])	Run the material-preview command.

embodichain.lab.scripts.preview_material.main(args)

Query or preview default materials using the production preset resolver.

Parameters:

args (Namespace) – Parsed material-preview arguments. Batch mode always exports without a window; single previews use one unless headless is set.

Raises:

• ValueError – Selection, override or renderer requirements are invalid.

• OSError – A supplied model or output directory cannot be accessed.

• RuntimeError – Native rendering or window creation fails.

• AssertionError – A requested direct-native comparison fails.

Return type:

None

embodichain.lab.scripts.preview_material.cli(argv=None)

Run the material-preview command.

Parameters:

argv (Sequence[str] | None) – Arguments excluding the command name, or None for sys.argv.

Return type:

None

embodichain.lab.scripts.preview_robot

Load a catalog robot or a standalone configuration and run a native or Viser preview with managed control-part Gizmos and optional joint controls.

build_robot_cfg(args)	Decode a catalog or standalone robot configuration.
cli([argv])	Run the robot-preview command.
main(args)	Load and preview a robot, releasing the owned simulation before returning.

embodichain.lab.scripts.preview_robot.build_robot_cfg(args)

Decode a catalog or standalone robot configuration.

Parameters:

args (Namespace) – Parsed preview arguments. File fields and JSON overrides take precedence over catalog and explicitly selected variant defaults.

Return type:

RobotCfg

Returns:

A validated robot configuration with local file assets resolved.

Raises:

• ValueError – If selection is invalid or no robot asset is configured.

• TypeError – If the file root is not a mapping.

• OSError – If the configuration file cannot be read.

embodichain.lab.scripts.preview_robot.cli(argv=None)

Run the robot-preview command.

Parameters:

argv (Sequence[str] | None) – Arguments excluding the command name, or None for sys.argv.

Return type:

None

embodichain.lab.scripts.preview_robot.main(args)

Load and preview a robot, releasing the owned simulation before returning.

Parameters:

args (Namespace) – Parsed robot-preview arguments.

Raises:

Exception – The original configuration, loading, or runtime failure.

Return type:

None

embodichain.lab.scripts.run_task

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	Manual PBR properties or explicit overrides of a default material preset.
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.
AffordancePoseCandidates	Batched pose candidates with cost and explicit validity.
AffordanceSample	Owned result of one batched Affordance sampling operation.
AffordanceSamplingContext	Immutable identity for reproducible parallel Affordance sampling.
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.
sample_candidates(candidates, *, sampling, ...)	Select poses from a legal candidate set for each logical branch.
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

sample_candidates(candidates, *, sampling, env_ids, key, reference_poses=None)

Select poses from a legal candidate set for each logical branch.

Parameters:

• candidates (AffordancePoseCandidates) – Batched world poses, costs, and validity produced by geometry.

• sampling (AffordanceSamplingContext | None) – Optional reproducible branch stream. None selects the lowest-cost candidate in every row.

• env_ids (Tensor) – Stable environment identities matching candidate rows.

• key (str) – Sampling operation identity.

• reference_poses (Tensor | None) – Optional world poses of frames used to compare candidate geometry and recorded in the sampling provenance.

Return type:

AffordanceSample

Returns:

Per-row success, selected poses, and selection metadata.

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. Its mesh may describe either the whole object or one selected articulation link; operations that infer whole-object geometry reject the latter. Simulator entity handles and live poses belong to scene grounding.

Attributes:

MAX_SURFACE_POINT_COUNT	Maximum point-cloud size used for geometry-distribution analysis.
custom_config	User-defined configuration payload.
mesh_scope	Whether the mesh describes the whole object or one selected link.
mesh_triangles	Target-local mesh triangle indices, shape [M, 3].
mesh_vertices	Target-local mesh vertices, shape [N, 3].

Methods:

__init__([object_label, custom_config, ...])
get_grasp_candidates(generator, ...[, ...])	Generate constrained candidates using an externally owned service.
get_object_longest_axis(obj_poses, *[, ...])	Return the widest surface-point distribution axis in world space.
require_whole_object_mesh()	Reject a link-only grasp mesh where whole-object geometry is required.
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, mesh_scope='object')

custom_config: dict[str, Any]

User-defined configuration payload.

get_grasp_candidates(generator, object_poses, approach_direction, *, obj_longest_axis=None, is_positive_part=True)

Generate constrained candidates using an externally owned service.

Parameters:

• generator (GraspPoseGenerator) – Grasp-pose service configured for the actual gripper.

• object_poses (Tensor) – Live-grounded world poses with shape (B, 4, 4).

• approach_direction (Tensor) – Shared or per-row approach direction.

• obj_longest_axis (Tensor | None) – Optional axis restricting the graspable region.

• is_positive_part (bool | Tensor) – Which end of the optional axis is graspable.

Return type:

AffordancePoseCandidates

Returns:

Padded candidates with explicit validity.

get_object_longest_axis(obj_poses, *, max_points=1000)

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

Return type:

Tensor

mesh_scope: Literal['object', 'link'] = 'object'

Whether the mesh describes the whole object or one selected link.

mesh_triangles: Tensor | None = None

Target-local mesh triangle indices, shape [M, 3].

mesh_vertices: Tensor | None = None

Target-local mesh vertices, shape [N, 3].

require_whole_object_mesh()

Reject a link-only grasp mesh where whole-object geometry is required.

Raises:

ValueError – If this affordance contains only a selected link mesh.

Return type:

None

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.
sample_assemble_object_pose(base_pose, *, ...)	Sample only explicitly declared assembly-equivalent rotations.

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.
symmetry_transforms	Assembly-equivalent object-local rotations with shape (K, 4, 4).

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

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.

sample_assemble_object_pose(base_pose, *, sampling, env_ids, key='assembly_symmetry')

Sample only explicitly declared assembly-equivalent rotations.

Parameters:

• base_pose (Tensor) – Base-object world poses.

• sampling (AffordanceSamplingContext | None) – Optional reproducible branch stream.

• env_ids (Tensor) – Stable environment identities matching base rows.

• key (str) – Sampling operation identity.

Return type:

AffordanceSample

Returns:

Assembly target poses with selection success and metadata.

symmetry_transforms: Tensor | None = None

Assembly-equivalent object-local rotations with shape (K, 4, 4).

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, mesh_scope='object', 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.
sample_poses(target_pose, *, sampling, env_ids)	Sample local contact points and their inward-facing frames.

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].

sample_poses(target_pose, *, sampling, env_ids, key='interaction_points', point_type=None)

Sample local contact points and their inward-facing frames.

Parameters:

• target_pose (Tensor) – Target world poses with shape (B, 4, 4).

• sampling (AffordanceSamplingContext | None) – Optional reproducible branch stream.

• env_ids (Tensor) – Stable environment identities matching target rows.

• key (str) – Sampling operation identity.

• point_type (str | None) – Optional exact interaction-point label.

Return type:

AffordanceSample

Returns:

Sampled contact frames with selection success and metadata.

Raises:

ValueError – If point geometry, normals, or the requested type is invalid.

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>, mesh_scope='object', 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.
sample_press_pose(target_pose[, ...])	Sample contact-frame roll while preserving point and forward axis.

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

sample_press_pose(target_pose, press_position=None, *, sampling, env_ids, key='press_roll')

Sample contact-frame roll while preserving point and forward axis.

Parameters:

• target_pose (Tensor) – Target world poses with shape (B, 4, 4).

• press_position (tuple[float, float, float] | None) – Optional exact local contact position.

• sampling (AffordanceSamplingContext | None) – Optional reproducible branch stream.

• env_ids (Tensor) – Stable environment identities matching target rows.

• key (str) – Sampling operation identity.

Return type:

AffordanceSample

Returns:

Sampled press poses and roll metadata.

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>, mesh_scope='object', 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.
sample_grasp_pose(target_pose, *, sampling, ...)	Sample explicitly declared roll symmetry around the grasp axis.

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.
grasp_roll	Nominal contact-frame rotation about the grasp z-axis, in radians.
grasp_roll_range	Allowed absolute grasp rolls containing grasp_roll.
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, grasp_roll=0.0, grasp_roll_range=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.

grasp_roll: float = 0.0

Nominal contact-frame rotation about the grasp z-axis, in radians.

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

Allowed absolute grasp rolls containing grasp_roll.

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

sample_grasp_pose(target_pose, *, sampling, env_ids, key='twist_grasp')

Sample explicitly declared roll symmetry around the grasp axis.

Parameters:

• target_pose (Tensor) – Target world poses with shape (B, 4, 4).

• sampling (AffordanceSamplingContext | None) – Optional reproducible branch stream.

• env_ids (Tensor) – Stable environment identities matching target rows.

• key (str) – Sampling operation identity.

Return type:

AffordanceSample

Returns:

Sampled grasp poses and roll metadata.

twist_axis: Tensor

Parent revolute-joint axis, signed toward articulation geometry.

embodichain.lab.sim.atomic_actions.affordance_sampling

AffordancePoseCandidates	Batched pose candidates with cost and explicit validity.
AffordanceSample	Owned result of one batched Affordance sampling operation.
AffordanceSamplingContext	Immutable identity for reproducible parallel Affordance sampling.

Reproducible pose sampling within Affordance-owned geometry.

Classes:

AffordancePoseCandidates	Batched pose candidates with cost and explicit validity.
AffordanceSample	Owned result of one batched Affordance sampling operation.
AffordanceSamplingContext	Immutable identity for reproducible parallel Affordance sampling.

class embodichain.lab.sim.atomic_actions.affordance_sampling.AffordancePoseCandidates

Batched pose candidates with cost and explicit validity.

Parameters:

• poses (Tensor) – World-frame homogeneous poses with shape (B, K, 4, 4).

• costs (Tensor) – Lower-is-better candidate costs with shape (B, K).

• valid (Tensor) – Real-candidate mask with shape (B, K).

Methods:

__init__(poses, costs, valid)
from_rows(rows, *, device)	Pad variable candidate rows without making padding selectable.

__init__(poses, costs, valid)

classmethod from_rows(rows, *, device)

Pad variable candidate rows without making padding selectable.

Parameters:

• rows (Sequence[tuple[Tensor, Tensor]]) – Per-row (poses, costs) values; rows may be empty.

• device (device | str) – Output device.

Return type:

AffordancePoseCandidates

Returns:

A rectangular candidate batch with explicit validity.

class embodichain.lab.sim.atomic_actions.affordance_sampling.AffordanceSample

Owned result of one batched Affordance sampling operation.

Parameters:

• success (Tensor) – Per-row legal-sample mask with shape (B,).

• poses (Tensor) – Selected poses with shape (B, 4, 4).

• metadata (dict[str, object]) – Sampling provenance and selection diagnostics. Affordance samplers record pose_frame="world", selected_poses, optional world-frame reference_poses, env_ids, and geometric success as JSON-compatible values. Row lists follow the input batch order. Failed rows retain identity placeholder poses and must be interpreted with success; this is not IK or execution success. Candidate IDs identify only each row’s candidate pool.

Methods:

__init__(success, poses, metadata)

__init__(success, poses, metadata)

class embodichain.lab.sim.atomic_actions.affordance_sampling.AffordanceSamplingContext

Immutable identity for reproducible parallel Affordance sampling.

Parameters:

• count (int) – Number of logical branches in each sampling group.

• seed (int) – Host-selected base seed.

• episode_id (int) – Host-selected episode or batch identity.

• attempt_id (int) – Explicit resampling attempt identity.

• branch_override (int | None) – Optional logical branch selected independently of the physical environment row.

Methods:

__init__([count, seed, episode_id, ...])
branch_for(env_id, *[, row_index])	Return the selected branch for one environment identity.
generator(key, *[, group])	Create a private CPU generator for a stable named stream.
metadata()	Return JSON-compatible sampling provenance.
sample_range(nominal, bounds, *, env_ids, key)	Stratify a legal scalar interval while retaining nominal branches.

Attributes:

enabled

Whether more than the nominal branch was requested.

__init__(count=1, seed=0, episode_id=0, attempt_id=0, branch_override=None, branch_overrides=None)

branch_for(env_id, *, row_index=None)

Return the selected branch for one environment identity.

Return type:

int

property enabled: bool

Whether more than the nominal branch was requested.

generator(key, *, group=0)

Create a private CPU generator for a stable named stream.

Parameters:

• key (str) – Non-empty sampling operation identity.

• group (int) – Non-negative logical branch-group identity.

Return type:

Generator

Returns:

A generator independent of PyTorch’s global random state.

metadata()

Return JSON-compatible sampling provenance.

Return type:

dict[str, int | None]

sample_range(nominal, bounds, *, env_ids, key)

Stratify a legal scalar interval while retaining nominal branches.

Parameters:

• nominal (float | Tensor) – Scalar or one value per environment row.

• bounds (tuple[float, float] | None) – Inclusive lower and upper bounds, or None for no freedom.

• env_ids (Tensor) – Stable non-negative environment identities, shape (B,).

• key (str) – Sampling operation identity.

Return type:

Tensor

Returns:

Sampled values with shape (B,) on the environment device.

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.
PARK_COMMAND	Conventional semantic command for an embodiment-defined parked posture.

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.
world_displacement	Optional world-frame translation applied after relative_pose.
world_orientation	Optional world-frame orientation applied before relative_pose.

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

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.

world_displacement: Tensor | None

Optional world-frame translation applied after relative_pose.

world_orientation: Tensor | None

Optional world-frame orientation applied before relative_pose.

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_rigidized_articulation_antipodal_semantics(...)	Describe a locked articulation as one antipodal-graspable rigid object.
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.
SceneEntity	Structural contract a scene provider requires of an observed entity.
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:

affordance_sampling	Optional immutable Affordance sampling stream supplied by the host.
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, affordance_sampling=None)

affordance_sampling: AffordanceSamplingContext | None

Optional immutable Affordance sampling stream supplied by the host.

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, *, ...)	Retime and embed a controlled-joint plan into a 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.diff

Public bridge from task-defined Newton kinematics and Warp tapes into PyTorch autograd. It does not advance the Newton dynamics solver.

NewtonStepFunc	Bridge one task-defined Newton kinematics step into PyTorch autograd.
tape_context(manager)	Open a Warp tape for expert Newton kinematics kernels.

embodichain.lab.sim.diff.bridge

NewtonStepFunc	Bridge one task-defined Newton kinematics step into PyTorch autograd.
tape_context(manager)	Open a Warp tape for expert Newton kinematics kernels.

embodichain.lab.sim.cfg.source

USD source configuration identifies a file and an optional exact prim inside that file. Source selection is independent of runtime identity, placement and parent/link attachment. Supply it through source on a visual, rigid-object or articulation configuration. Existing mesh and URDF file inputs remain available; each asset has one file owner.

UsdSourceCfg

Select a typed asset from a source USD stage.

class embodichain.lab.sim.cfg.source.UsdSourceCfg

Select a typed asset from a source USD stage.

Supply this as source on a visual-object, rigid-object or articulation configuration. Runtime identity and placement belong to the containing configuration. This source does not bind an already imported scene entity.

Methods:

__init__([file_path, source_prim_path])
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(data)	Decode a source mapping, rejecting unknown source options.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

Attributes:

file_path	Source USD, USDA, USDC or USDZ file.
source_prim_path	Exact absolute prim path in the source stage.

__init__(file_path=<factory>, source_prim_path=<factory>)

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

file_path: str

Source USD, USDA, USDC or USDZ file.

classmethod from_dict(data)

Decode a source mapping, rejecting unknown source options.

Parameters:

data (Mapping[str, object]) – Source file and optional exact source prim selector.

Return type:

UsdSourceCfg

Returns:

Source configuration; call validate() after assembly.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

source_prim_path: str | None

Exact absolute prim path in the source stage.

Omit only when the source contains a single candidate of the requested asset type. This is not a destination path, regex or parent/link binding.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

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

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

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

embodichain.lab.sim.cfg.visual_object

Render-only geometry or a USD source, and initial visual state.

VisualObjectCfg

Configure a render-only object, without a rigid body or colliders.

embodichain.lab.sim.diff.runtime

NewtonDifferentiableRuntime

Expose Newton model/state buffers required by kinematic environments.

embodichain.lab.sim.objects.articulation

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

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

CollisionShapeDesc	Planner-independent snapshot of one DexSim physical collision shape.
RigidBodyData	Scene-batch data manager for dynamic or kinematic rigid bodies.
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	Expose one flat Scene rigid-body batch as [env, object, ...] tensors.
RigidObjectGroup	A two-dimensional view over rigid objects owned by DexSim Spawn.
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.visual_object

Batched render-only objects provide pose, visibility and material-assignment operations without physical buffers or collision APIs.

VisualObject	A replicated visual asset with no rigid-body state or collision API.
VisualObjectCfg	Configure a render-only object, without a rigid body or colliders.

embodichain.lab.sim.physics

Manager-level physics backend selection and lifecycle contracts for the Default and Newton implementations integrated through DexSim.

PhysicsBackend	Abstract base class for a swappable physics backend.
DefaultPhysicsBackend	Default backend using DexSim's native GPU or CPU physics path.
NewtonPhysicsBackend	The Warp-based Newton physics backend integrated through DexSim.
make_physics_backend(physics_cfg, manager)	Construct the physics backend for physics_cfg.

embodichain.lab.sim.physics.base

PhysicsBackend

Abstract base class for a swappable physics backend.

embodichain.lab.sim.physics.default

DefaultPhysicsBackend

Default backend using DexSim's native GPU or CPU physics path.

embodichain.lab.sim.physics.newton

NewtonPhysicsBackend

The Warp-based Newton physics backend integrated through DexSim.

embodichain.lab.sim.motion.planners.base_planner

BasePlannerCfg	BasePlannerCfg(robot_uid: 'str' = <factory>, planner_type: 'str' = <factory>, sim_instance_id: 'int' = <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_scene(rigid_objects, *)	Build a mixed cuRobo scene from DexSim physical collision shapes.
visualize_curobo_collision_models(robot, ...)	Show robot and world collision models in DexSim until Enter is pressed.
visualize_curobo_robot_collision_model(...)	Visualize a robot's live link meshes and cached collision spheres.
visualize_curobo_world_collision_model(...)	Add a sampled cuRobo collision-world overlay to the DexSim scene.

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>, sim_instance_id: 'int' = <factory>, onnx_model_path: 'str' = <factory>, control_part: 'str | None' = <factory>, max_steps: 'int' = <factory>, action_scale: 'float' = <factory>, num_arm_joints: 'int' = <factory>, num_waypoints: 'int' = <factory>, use_relative_obs: 'bool' = <factory>, canonicalize_quat_obs: 'bool' = <factory>, joint_periodic_features: 'bool' = <factory>, intermediate_orientation: 'bool' = <factory>, pos_eps: 'float' = <factory>, rot_eps: 'float' = <factory>, joint_eps: 'float' = <factory>, onnx_providers: 'list[str] | None' = <factory>, policy_frame_from_world: 'list[list[float]] | None' = <factory>, runtime_tcp_from_policy_tcp: 'list[list[float]] | None' = <factory>, dt: 'float' = <factory>, constraints: 'dict[str, float | list[float]] | None' = <factory>)
NeuralPlanOptions	NeuralPlanOptions(control_part: 'str | None' = <factory>, start_qpos: 'torch.Tensor | None' = <factory>, max_steps: 'int | None' = <factory>, waypoint_modalities: 'list[str] | None' = <factory>)

embodichain.lab.sim.motion.planners.bezier

Differentiable quadratic and quintic Bézier geometry, including HolisticMotion-compatible waypoint blending and path-constraint projection. Use BezierPath.parameter_at_arc_length(distance) to convert a scalar time law’s geometric distances to polynomial parameters. Reuse those parameters for evaluate, arc_tangent, and arc_curvature; normalized arc length is generally different from the Bézier parameter. Lookup accuracy is controlled by table_count independently of the output sample count.

BezierPath	Euclidean quadratic or quintic Bézier path value object.
bezier_arc_length(control_points)	Integrate the Euclidean Bézier speed over [0, 1].
bezier_derivative(control_points, parameter)	Evaluate a Bézier derivative with respect to its normalized parameter.
bezier_evaluate(control_points, parameter)	Evaluate quadratic or quintic Bézier control points at parameter.
sample_bezier_path(control_points, ...[, ...])	Sample a Bézier path and return (points, cumulative_length).

BezierPath.parameter_at_arc_length(distance, *, table_count=4097)

Convert geometric arc lengths to normalized polynomial parameters.

Reuse the returned parameters for positions, tangents, and curvature so they refer to the same points on the curve. A polyline lookup table approximates cumulative length; its resolution is independent of the number of requested distances. The table is rebuilt on each call to reflect changes to the underlying control points.

Parameters:

• distance (Tensor) – Finite scalar, shared sample vector (N,), or per-path samples (…, N) whose batch dimensions broadcast with the control points. Values outside the path are clamped.

• table_count (int) – Number of uniformly spaced polynomial parameters in the lookup table, at least two. Higher values improve accuracy.

Return type:

Tensor

Returns:

Parameters in [0, 1] with broadcast batch and sample dimensions. A scalar distance omits the sample dimension. Stationary paths return zero parameters.

Raises:

ValueError – If distances are non-finite or table_count is invalid.

embodichain.lab.sim.motion.planners.toppra_planner

Time-optimal joint-path parameterization. The planner solves timing for waypoint input; retime_joint_paths() applies the same parameterization to paths another planner already produced, such as a closed-loop policy rollout whose samples carry only nominal timing.

ToppraPlanner	Rest-to-rest joint-path timing with differentiable CPU/CUDA Warp kernels.
ToppraPlannerCfg	Configure the shared CPU/CUDA Warp time parameterizer.
ToppraPlanOptions	ToppraPlanOptions(constraints: 'dict' = <factory>, sample_method: 'TrajectorySampleMethod' = <factory>, sample_interval: 'float | int' = <factory>, *, control_part: 'str | None' = None)
retime_joint_paths(positions, *, constraints)	Re-parameterize already-planned joint paths under dynamic limits.

embodichain.lab.sim.motion.planners.se3

SE(3) screw interpolation and constrained Cartesian line trajectories with explicit twist, acceleration, jerk, and timing outputs.

SE3LineResult	Samples from a time-parameterized Cartesian line trajectory.
plan_se3_line(start, end, velocity_limit, ...)	Plan a constrained time-parameterized Cartesian line trajectory.

embodichain.lab.sim.motion.planners.trapezoidal_planner

TrapezoidalPlanOptions	Configure trapezoidal or Double-S trajectory generation.
TrapezoidalPlanner	Plan batched linear joint paths with trapezoidal or Double-S timing.
TrapezoidalPlannerCfg	Configure the batched joint-space time-profile planner.

embodichain.utils.warp.kinematics.trapezoidal_warp

Warp-accelerated helpers construct scalar trapezoidal or Double-S motion profiles and compose their sampled path derivatives into batched joint-space trajectories.

build_profile_warp(*, profile, ...)	Construct all scalar segment profiles in one Warp launch.
compose_profile_samples_warp(*, times, ...)	Evaluate scalar profiles once per sample, then compose all joints.

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.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.sensors.camera

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

embodichain.lab.sim.sensors.contact_sensor

ArticulationContactFilterCfg	Configuration for filtering contacts from an articulation's links.
ContactSensor	Sensor to get contacts from rigid bodies and articulation links.
ContactSensorCfg	Configuration class for contact sensors.

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 an XYZW 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 an XYZW 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 an XYZW 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_xyzw (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_xyzw)
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_xyzw	Return an independent normalized quaternion tensor.

__init__(position, quaternion_xyzw)

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_xyzw: 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, pose_source_revision=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, ...])

Attributes:

custom_config

User-defined configuration payload.

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

custom_config: dict[str, Any]

User-defined configuration payload.

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.

• pose_source_revision (str | None) – Optional integrator-owned fingerprint of a provider-backed pose declaration, independent of affordance schema.

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, pose_source_revision=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.

• pose_source_revision (str | None) – Optional integrator-owned fingerprint of the explicit state provider’s pose declaration. Requires state_provider and stays separate from the affordance payload schema revision.

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.
pose_source_revision	Integrator-owned fingerprint of the provider-backed pose declaration.
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, pose_source_revision=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.

pose_source_revision: str | None

Integrator-owned fingerprint of the provider-backed pose declaration.

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, articulation_objects=None, articulations=None, collision_roles=None, geometry_providers=None, collision_world_mode=None)

Opt explicitly selected simulation entities into a registry.

rigid_objects, articulation_objects, and articulations map authoritative registry IDs to simulation UIDs. Articulation objects use a native articulation for root-pose observation while publishing a SceneObjectRef without joint state. 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.

• articulation_objects (Mapping[str, str] | None) – Canonical object IDs backed by articulation 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, ...])

Attributes:

custom_config

User-defined configuration payload.

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

custom_config: dict[str, Any]

User-defined configuration payload.

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

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

embodichain.lab.sim.motion.solvers.base_solver

Shared solver configuration and runtime contracts for IK, FK, joint limits, and optional continuous batch IK. Continuous selection defaults to unsupported; implementations opt in through supports_continuous_batch_ik and implement the protected _select_continuous_ik_path hook for batched candidates.

BaseSolver	Base interface shared by robot forward and inverse kinematics solvers.
SolverCfg	Configuration for the kinematic solver used in the robot simulation.

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.opw_solver

Configuration and runtime solver for analytic OPW forward and inverse kinematics of compatible six-axis manipulators.

OPWSolver	OPW inverse kinematics (IK) controller.
OPWSolverCfg	Configuration for OPW inverse kinematics controller.

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.spawn

Translation boundary from EmbodiChain object configs and singleton USD assets into DexSim Spawn descriptors.

articulation_desc_from_cfg(cfg, *[, ...])	Translate an articulation config into a DexSim Spawn descriptor.
articulation_desc_from_usd(cfg, *[, ...])	Select an articulation by exact prim path, or require a singleton stage.
rigid_desc_from_cfg(cfg, *[, per_env, ...])	Translate a rigid-object config into a DexSim Spawn descriptor.
visual_desc_from_cfg(cfg, *[, per_env])	Compile visual geometry without creating physics or collision descriptors.
rigid_desc_from_usd(cfg, *[, per_env, ...])	Select a rigid object by exact prim path, or require a singleton stage.
visual_desc_from_usd(cfg, *[, per_env])	Select a USD object's appearance, explicitly omitting its physics.
surface_deformable_desc_from_cfg(cfg, *[, ...])	Translate a surface deformable into a Newton particle-set descriptor.
volume_deformable_desc_from_cfg(cfg, *[, ...])	Translate a volume deformable into a Newton particle-set descriptor.

embodichain.lab.sim.spawn.descriptors

articulation_desc_from_cfg(cfg, *[, ...])	Translate an articulation config into a DexSim Spawn descriptor.
configure_articulation_desc(desc, cfg, *[, ...])	Apply one EmbodiChain config to exact source-resolved names.
rigid_desc_from_cfg(cfg, *[, per_env, ...])	Translate a rigid-object config into a DexSim Spawn descriptor.
visual_desc_from_cfg(cfg, *[, per_env])	Compile visual geometry without creating physics or collision descriptors.
surface_deformable_desc_from_cfg(cfg, *[, ...])	Translate a surface deformable into a Newton particle-set descriptor.
volume_deformable_desc_from_cfg(cfg, *[, ...])	Translate a volume deformable into a Newton particle-set descriptor.

embodichain.lab.sim.spawn.scene

SpawnScene

Map EmbodiChain asset declarations onto one DexSim Spawn scene.

embodichain.lab.sim.spawn.source

resolve_articulation_source(builder, desc)

Populate exact URDF metadata without building a Newton model.

embodichain.lab.sim.spawn.usd

articulation_desc_from_usd(cfg, *[, ...])	Select an articulation by exact prim path, or require a singleton stage.
rigid_desc_from_usd(cfg, *[, per_env, ...])	Select a rigid object by exact prim path, or require a singleton stage.
visual_desc_from_usd(cfg, *[, per_env])	Select a USD object's appearance, explicitly omitting its physics.

embodichain.lab.sim.utility.dynamic_pybind

Install the projective UV helper on DexSim render bodies. The helper projects vertices across mesh segments and adapts UV storage to the pinned DexSim 0.5.1rc1 binding before writing each segment.

set_projective_uv(self[, proj_direct])	Set projective uv mapping to render body.
init_dynamic_pybind()	Initialize dynamic pybind interface.

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

Scrambled Sobol sampling with a persistent stream for each dimension.

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.manipulability_visualizer

ManipulabilityColorCfg	Colors and normalization for manipulability visualization.
ManipulabilityPointSet	Per-point scores aligned with the points of an analysis result.
ManipulabilityNormalization	Outcome of robust manipulability normalization.
ManipulabilityColorMapping	Colors, sizes and normalization metadata for a point set.
InspectionSelection	Indices chosen for detailed (ellipsoid) inspection.
PointInspection	Detail record for a single inspected workspace point.
ManipulabilityVisualizer	Render workspace points colored by manipulability.
align_manipulability_scores(results[, ...])	Align a manipulability score vector with the points of an analysis result.
normalize_manipulability(scores, *[, ...])	Normalize manipulability scores to [0, 1] with percentile clipping.
map_manipulability_colors(scores, *[, ...])	Map manipulability scores to RGBA colors and marker sizes.
select_inspection_indices(scores, *[, ...])	Choose the few points that deserve a detailed inspection.
inspect_points(selection, *, points, scores)	Build detail records for the selected points only.
translational_manipulability_ellipsoid(jacobian)	Derive translational manipulability ellipsoids from spatial Jacobians.
ellipsoid_surface(radii, axes[, center, ...])	Tessellate one ellipsoid for surface plotting.

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.
complete_discounted_return(rollout, gamma)	Compute per-environment returns up to the first terminal transition.
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.gradients

Row-wise action-adjoint clipping and its rollout-level diagnostics.

BatchedGradientNormStats	Accumulate row-wise adjoint norm and clipping statistics on-device.
clip_batched_gradient_norm(gradient, max_norm)	Clip each batch row without shortening the differentiable time horizon.

embodichain.learning.rl.policies.actor_critic

ActorCritic

TensorDict actor-critic with a learnable Gaussian action distribution.

embodichain.learning.rl.policies.actor_only

ActorOnly

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

embodichain.learning.rl.policies.policy

Policy

Abstract base class that all RL policies must implement.

embodichain.learning.rl.normalization

RunningObservationNormalizer

Normalize continuous observation fields with running Welford statistics.

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.repeated_pick_place

RLinf-facing repeated pick-and-place task registrations with explicit EEF and joint-position action variants.

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.stack_cups

StackCupsEnv

embodichain_tasks.special.franka_reach_apg

Differentiable Franka FR3 reach environment that demonstrates the explicit kinematics route used by analytic policy-gradient experiments.

FrankaReachApgEnv

Differentiable Franka FR3 reach task for analytic policy gradients.

embodichain_tasks.utils.importer

import_packages(package_name[, blacklist])

Recursively import all modules below package_name.

Standalone simulation command-line options

embodichain.cli.sim builds simulation arguments without importing the simulation runtime. Gym launchers compose these options with configuration and recording flags. Seed options are opt-in: resolve_seed resolves -1 to an effective 32-bit seed without changing random streams or deterministic kernel policy; callers log and apply that seed to their own generators.

add_sim_args_to_parser(parser)	Register standalone simulation and visualization options.
add_seed_arg_to_parser(parser, *[, default, ...])	Register one seed option for a caller that actually consumes it.
resolve_seed(seed)	Resolve the random-run sentinel without changing global RNG state.

embodichain.cli.sim.add_sim_args_to_parser(parser)

Register standalone simulation and visualization options.

Parameters:

parser (ArgumentParser) – Parser receiving the options. Device omission preserves the backend default; the other standalone defaults are concrete.

Return type:

None

embodichain.cli.sim.add_seed_arg_to_parser(parser, *, default=0, scope='random sampling')

Register one seed option for a caller that actually consumes it.

Parameters:

• parser (ArgumentParser) – Parser receiving the seed option.

• default (int | None) – Seed when omitted; None preserves a Gym config’s seed.

• scope (str) – User-facing description of the random streams controlled.

Return type:

None

embodichain.cli.sim.resolve_seed(seed)

Resolve the random-run sentinel without changing global RNG state.

Parameters:

seed (int) – A non-negative 32-bit seed, or -1 to generate a fresh seed.

Return type:

int

Returns:

Effective seed to log and pass to the caller’s random generators.

Raises:

ValueError – If seed is outside the portable 32-bit range.

embodichain.lab.sim.cfg.robot

Robot construction and complete backend alternatives

Robot configurations include optional mounted camera declarations. Standalone simulation initializes them only when enable_sensor is true; Gym uses its environment-wide sensor switch, which defaults to enabled.

RobotCfg

RobotCfg(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>, body_scale: 'tuple | list' = <factory>, compute_uv: 'bool' = <factory>, asset_physics_mode: 'AssetPhysicsMode' = <factory>, attrs: 'RigidBodyPhysicsCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, root_props: 'ArticulationRootPropertiesCfg' = <factory>, joint_drive_props: 'JointDrivePropertiesCfg' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None' = <factory>, build_pk_chain: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg | None' = <factory>, solver_cfg: 'SolverCfg | Dict[str, SolverCfg] | None' = <factory>, workspace_cfg: 'Dict[str, RobotWorkspaceCfg] | None' = <factory>, sensors: 'list[SensorCfg]' = <factory>, enable_sensor: 'bool' = <factory>, *, source: 'UsdSourceCfg | None' = None)

RobotPresetCfg

Base class for replace-only robot configurations across physics backends.

class embodichain.lab.sim.cfg.robot.RobotCfg

RobotCfg(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>, body_scale: ‘tuple | list’ = <factory>, compute_uv: ‘bool’ = <factory>, asset_physics_mode: ‘AssetPhysicsMode’ = <factory>, attrs: ‘RigidBodyPhysicsCfg’ = <factory>, link_attrs: ‘dict[str, LinkPhysicsOverrideCfg] | None’ = <factory>, root_props: ‘ArticulationRootPropertiesCfg’ = <factory>, joint_drive_props: ‘JointDrivePropertiesCfg’ = <factory>, init_qpos: ‘torch.Tensor | np.ndarray | Sequence[float]’ = <factory>, qpos_limits: ‘torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None’ = <factory>, build_pk_chain: ‘bool’ = <factory>, control_parts: ‘Dict[str, List[str]] | None’ = <factory>, urdf_cfg: ‘URDFCfg | None’ = <factory>, solver_cfg: ‘SolverCfg | Dict[str, SolverCfg] | None’ = <factory>, workspace_cfg: ‘Dict[str, RobotWorkspaceCfg] | None’ = <factory>, sensors: ‘list[SensorCfg]’ = <factory>, enable_sensor: ‘bool’ = <factory>, *, source: ‘UsdSourceCfg | None’ = None)

Methods:

__init__([uid, init_pos, init_rot, ...])
__new__(**kwargs)

Attributes:

enable_sensor	Initialize mounted sensors when adding the robot.
sensors	Mounted camera configurations with robot-local parent link names.

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, body_scale=<factory>, compute_uv=<factory>, asset_physics_mode=<factory>, attrs=<factory>, link_attrs=<factory>, root_props=<factory>, joint_drive_props=<factory>, init_qpos=<factory>, qpos_limits=<factory>, build_pk_chain=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>, workspace_cfg=<factory>, sensors=<factory>, enable_sensor=<factory>, *, source=None)

__new__(**kwargs)

enable_sensor: bool

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

sensors: list[SensorCfg]

Mounted camera configurations with robot-local parent link names.

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

class embodichain.lab.sim.cfg.robot.RobotPresetCfg

Base class for replace-only robot configurations across physics backends.

Subclasses declare complete RobotCfg alternatives as fields. A default field is required; optional fields use Newton backend or solver profile names such as newton, newton_mujoco_warp, or newton_mjwarp. The active PhysicsBackendCfg selects one complete alternative at SimulationManager.add_robot(); alternatives are never field-merged.

Portable robot properties should remain on one ordinary RobotCfg. Use this wrapper only when an asset, actuator model, or native physics value genuinely requires a different complete robot definition.

Example:

@configclass
class MyRobotPresetCfg(RobotPresetCfg):
    default: RobotCfg = MyRobotCfg()
    newton_mujoco_warp: RobotCfg = MyNewtonRobotCfg()

Methods:

__init__()
__new__(**kwargs)

__init__()

__new__(**kwargs)

Asset generalization contracts

• Asset generalization
  • embodichain.data.asset_catalog
  • embodichain.data.asset_catalog.contracts
  • embodichain.lab.task_program.semantics.asset_requirements
  • embodichain.data.asset_catalog additions
  • embodichain.data.asset_catalog.local additions
  • embodichain.lab.task_program.semantics.asset_matching additions
  • embodichain.lab.task_program.integrations.asset_materialization additions
  • embodichain.lab.gym.envs.asset_generalization additions
  • Calibrated pouring and measured acceptance