From 4de52af8c6f25ce6450cd5688a9fcba4b057f58f Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 14 Nov 2026 08:57:43 +0000 Subject: [PATCH 01/49] feat(expansion): add rolling single-world workload execution --- agent_context/MAP.yaml | 2 +- .../expansion-engine/expansion-engine.md | 24 +- .../topics/expansion-engine/workloads.md | 85 +++ .../topics/sensor-system/sensor-system.md | 8 + docs/source/api_reference/public_api.rst | 77 +++ .../geometry/_warp/batch_contact_query.py | 90 +++ .../geometry/_warp/contact_permissions.py | 98 +++ embodichain/lab/expansion/__init__.py | 14 + embodichain/lab/expansion/_gym_frames.py | 55 +- embodichain/lab/expansion/_motion_batches.py | 166 +++++ .../lab/expansion/_planning_batches.py | 342 +++++++++ embodichain/lab/expansion/_workload_cursor.py | 105 +++ embodichain/lab/expansion/collision.py | 76 +- embodichain/lab/expansion/contracts.py | 16 +- embodichain/lab/expansion/engine.py | 120 ++++ embodichain/lab/expansion/episode_export.py | 129 ++++ embodichain/lab/expansion/persistence.py | 45 ++ embodichain/lab/expansion/workloads.py | 648 ++++++++++++++++++ embodichain/lab/gym/envs/_json.py | 4 + .../lab/sim/atomic_skills/_command_batches.py | 188 +++++ .../lab/sim/atomic_skills/runtime_commands.py | 8 + embodichain/lab/sim/cfg/physics.py | 11 + .../lab/sim/motion/motion_generator.py | 7 + .../lab/sim/motion/planners/base_planner.py | 4 +- .../lab/sim/motion/solvers/base_solver.py | 6 + .../lab/sim/motion/solvers/opw_solver.py | 3 +- embodichain/lab/sim/objects/articulation.py | 2 +- embodichain/lab/sim/physics/default.py | 2 +- .../scene/feasibility/_collision_batches.py | 335 +++++++++ .../lab/sim/scene/feasibility/collision.py | 105 +++ embodichain/lab/sim/sensors/__init__.py | 3 + .../lab/sim/sensors/contact/__init__.py | 2 + .../lab/sim/sensors/contact/permissions.py | 204 ++++++ .../integrations/_measured_batch.py | 133 ++++ .../task_program/integrations/feasibility.py | 48 ++ .../integrations/simulation/policies.py | 11 +- embodichain/utils/_owned_json.py | 115 ++++ pyproject.toml | 1 + tests/lab/expansion/test_export.py | 55 ++ tests/lab/expansion/test_persistence.py | 33 +- tests/lab/expansion/test_workloads_sim.py | 364 ++++++++++ .../atomic_skills/test_runtime_commands.py | 34 + tests/sim/motion/solvers/test_base_solver.py | 32 + .../feasibility/test_collision_planning.py | 61 ++ tests/sim/sensors/test_contact_default_e2e.py | 60 +- 45 files changed, 3857 insertions(+), 74 deletions(-) create mode 100644 agent_context/topics/expansion-engine/workloads.md create mode 100644 embodichain/compute/geometry/_warp/batch_contact_query.py create mode 100644 embodichain/compute/geometry/_warp/contact_permissions.py create mode 100644 embodichain/lab/expansion/_motion_batches.py create mode 100644 embodichain/lab/expansion/_planning_batches.py create mode 100644 embodichain/lab/expansion/_workload_cursor.py create mode 100644 embodichain/lab/expansion/episode_export.py create mode 100644 embodichain/lab/expansion/workloads.py create mode 100644 embodichain/lab/sim/atomic_skills/_command_batches.py create mode 100644 embodichain/lab/sim/scene/feasibility/_collision_batches.py create mode 100644 embodichain/lab/sim/sensors/contact/permissions.py create mode 100644 embodichain/lab/task_program/integrations/_measured_batch.py create mode 100644 embodichain/utils/_owned_json.py create mode 100644 tests/lab/expansion/test_workloads_sim.py diff --git a/agent_context/MAP.yaml b/agent_context/MAP.yaml index e20bf4b69e..0e27617b7f 100644 --- a/agent_context/MAP.yaml +++ b/agent_context/MAP.yaml @@ -198,7 +198,7 @@ topics: - id: expansion-engine title: Expansion Engine aliases: [Expansion Engine, offline expansion, 扩增引擎, 批量专家采集] - keywords: [ExpansionEngine, ExpansionRunCfg, ExpansionJobCfg, ExpansionSession, ExpansionSessionCfg, ExpansionCoverage, EpisodeCoverage, GymExpansionHost, ArtifactEpisodeSink, MediaSpool, render_observation_variants] + keywords: [ExpansionEngine, ExpansionRunCfg, ExpansionJobCfg, ExpansionSession, ExpansionSessionCfg, ExpansionCoverage, EpisodeCoverage, GymExpansionHost, ArtifactEpisodeSink, MediaSpool, render_observation_variants, WorkloadProgramExecutor, WorkloadExecutionCfg, workload_count] paths: [topics/expansion-engine/expansion-engine.md] source_of_truth: - embodichain/lab/expansion/ diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index c5bd37a172..88c2794c38 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -10,6 +10,7 @@ algorithms stay in `sim.motion.expansion`; scene and workspace algorithms stay i | Closed configuration and preflight | `embodichain/lab/expansion/configured.py` | | Canonical in-memory session, lifecycle limits and coverage port | `embodichain/lab/expansion/session.py`, `session_cfg.py`, `coverage.py` | | Shared scheduling, admission and commit ports | `embodichain/lab/expansion/engine.py` | +| Rolling workload × B execution in one caller-owned World | `embodichain/lab/expansion/workloads.py` | | Job assembly, stage recovery and inspect | `embodichain/lab/expansion/workflow.py`, `stages.py` | | Native World ownership and compatibility facade | `embodichain/lab/expansion/host.py` | | Native recipes, cohort preparation, step observation and episode assembly | `embodichain/lab/expansion/_gym_recipe.py`, `_gym_prepare.py`, `_gym_execution.py`, `_gym_frames.py`, `_gym_episode.py` | @@ -17,6 +18,7 @@ algorithms stay in `sim.motion.expansion`; scene and workspace algorithms stay i | Task Program execution with native or prototype motion | `embodichain/lab/expansion/program.py`, `real2sim.py` | | Source-pinned sampling and joint scene candidates | `embodichain/lab/expansion/recipes.py`, `scene.py` | | Artifact staging, checks and dataset export | `embodichain/lab/expansion/persistence.py`, `export.py` | +| Portable one-episode dataset export | `embodichain/lab/expansion/episode_export.py` | | Native appearance and state rerender | `embodichain/lab/expansion/visual.py` | | Bounded media blocks | `embodichain/data_pipeline/recording/media.py` | @@ -82,7 +84,7 @@ journal/duplicate-submission behavior. Cohorts have fixed robot/joint topology, backend, clock, observation schema and World appearance. Native scene-atlas input retains the complete layout/installation candidate. Assets with different topology require separate deployment Worlds. -All rows reset and settle together. Only the owner steps physics, and row generators +The configured cohort path resets and settles its rows together. Only the owner steps physics, and row generators acknowledge commands only after successful steps. Early termination must drain the Task Program safe-stop handshake; completed rows stop contributing frames. Native vector rejection cancels the row across semantic lanes and masks retained @@ -91,6 +93,21 @@ post-policy observation clock. Expected Real2Sim acceptance rejection retains measured checks and rejects only that row; source corruption and runtime errors still stop collection. +`WorkloadProgramExecutor` is an optional rolling integration for custom native +sources. Its supplied environment must have exactly `workload_count * batch_size` +rows and be the sole live World in the process. Each workload owns quotas, local +candidate ordinals and admission budgets; its B-row lane is reused after that +group drains. Preparing rows settle through ordinary control steps while live +rows continue to record and validate every boundary. The source owns scene +proposals, bridge binding and all physical checks, using `ExpansionEngine.admit_row`, +`mark_row_started` and `complete_row` instead of editing private engine queues. +Only confirmed native receipts earn quota or permit reuse; duplicate identities +cannot earn credit twice. Clock spans must equal each trajectory's command count. +Compatible fixed-grid planning and pure solver requests can be cooperatively +merged on the owner thread. Scoped planning budgets retain per-row charges; +unsupported requests keep native execution. Export callbacks receive frozen +group evidence and never access the World. See [rolling execution](workloads.md). + Native numerical evidence has T submitted actions and T+1 measured states. It includes all represented dynamic scene entities, source/action semantics, physical parameters and call provenance. Position-velocity commands must use their ExpertActionSpec; @@ -102,6 +119,11 @@ has bounded transient copies; no per-candidate dense full-episode image array is Frame readers stream selected frames from stored blocks; full artifact audits still validate bounded blocks. LeRobot export streams confirmed parents and visual children through the existing recorder and checks the exact final journal identity set. ODS remains unchanged. +`export_expansion_episodes` additionally publishes one portable LeRobot dataset +per confirmed parent. Cached evidence reads still hash every file byte and +reconstruct checked, independently owned numerical tensors; source/receipt/media +inspection remains required. Immutable JSON nodes can be shared internally, while +public mutable projections own separate containers. Pure visual replay requires complete scene state and an explicit observation-independent expert contract. Physics is disabled across the entire World; render-state publication diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md new file mode 100644 index 0000000000..6dcdf270f1 --- /dev/null +++ b/agent_context/topics/expansion-engine/workloads.md @@ -0,0 +1,85 @@ +# Rolling workload execution + +The public owner is `embodichain.lab.expansion.workloads`. This optional port is +independent of task names and downstream operator configuration. Existing +`ExpansionEngine.from_job` and cohort callers retain their interfaces and defaults. + +## Capacity and ownership + +`WorkloadExecutionCfg` declares W active groups and B physical candidate rows +per group; the supplied environment must contain exactly W times B rows. The +executor creates no simulation World, process or planning thread. It runs once +on the thread that owns its World. `world_info` records actual process, World, +backend, state and solver devices; selecting a visible CUDA device or renderer +does not select the physics device. + +`ExpansionWorkloadCfg` declares a unique group, qualified target, attempt cap and +admission wall-time budget. Candidate ordinals and seeds belong to that group, +not its lane or physical row. Admission includes in-flight candidates in the +remaining quota, avoiding extra speculative trajectories credited beyond target. +Another queued group takes the lane when the previous group has drained. A +difficult group does not silently borrow another group's B-row allocation. + +## Source ports and native accounting + +`WorkloadSource.prepare` runs inside the selected-row `episode_prepare` reset +callback. It must not step physics, alter an active peer or mutate World-wide +appearance/resources. Incompatible topology or shared resources require a +different deployment, rather than pretending they are independent rows. + +After at least the declared physical settling substeps, `activate` captures the +initial measured boundary, performs the source's required preparation checks, +registers a native candidate and uses `ExpansionEngine.admit_row`. It returns a +fresh bridge bound exactly to that row and the environment's control cadence. +Rejected preparation returns None and never earns quota. + +`started` calls `mark_row_started` after the first actual command. `observe` +captures every active T+1 boundary and performs the original physical checks; +it returns only active rows needing native safe rejection. The executor retains +the bridge acknowledgement/hold handshake. Preparing and completed peers cannot +fabricate actions or observations for another trajectory. + +`complete` receives the canonical bridge result and exact first/last World +control indices. It assembles the original source evidence and calls +`ExpansionEngine.complete_row`. Only that confirmed receipt earns a qualified +count. None is a rejection, never a placeholder success. Unavailable or ambiguous +writes retain the ordinary native stage/reconciliation contract and stop the +rolling owner from issuing unsupported quota credit. + +Frozen groups can call `export_expansion_episodes` from bounded writer threads. +The callback must not retain mutable live state or operate on the World. +Partial quotas remain explicit failures even when some episodes were exported. + +## Planning and validation + +The optional cooperative planner merges compatible fixed-grid motion requests +and pure FK/IK/Jacobian calls. Budget-bearing whole-motion requests keep their +original execution so charge semantics are preserved. Context variables and +candidate random streams remain row-local; results are independently owned. +Semantic programs and some trajectory processing still run per row. Per-control +planning readiness is a barrier; this API does not claim complete vectorization +or universal throughput improvement. + +`NewtonCollisionChecker.check_batch` uses the same physical geometry, pair +exemptions, halfspace supports and precision/saturation rules as scalar checks. +It returns discrete row reports, without claiming continuous clearance. Its +query model is never stepped and is not another simulation World. +`MeasuredTaskMonitor.batch_scope` shares measured numeric inputs while preserving +each native event state machine and receipts. `ContactPermissionChecker` checks +all valid native contact slots with the original applied-impulse and loss gates; +hosts still own sampling at every required physics substep. + +Default GPU dynamics may use ordinary reporting with +`DefaultPhysicsCfg(direct_gpu_api=False)` when complete static contact identities +are needed. It retains GPU dynamics; the Direct GPU buffer initialization flag +alone is not a physics-device measurement. Physics devices and task qualification +must be reported separately. Existing CPU deployments do not switch devices. + +## Focused validation + +`tests/lab/expansion/test_workloads_sim.py` runs a real four-row task through +native session admission and artifact receipts. It covers rejected-row safe +holds, refill, queued groups, no missing control boundaries, scalar/batched task +predicates and compatible whole-motion result parity. Geometry and contact +coverage lives in the existing native feasibility/contact suites. Per-episode +export uses the real LeRobot SDK and checks portable T+1 evidence. diff --git a/agent_context/topics/sensor-system/sensor-system.md b/agent_context/topics/sensor-system/sensor-system.md index 4a8869963e..82e9440ed1 100644 --- a/agent_context/topics/sensor-system/sensor-system.md +++ b/agent_context/topics/sensor-system/sensor-system.md @@ -125,6 +125,14 @@ changing filtering, force assumptions, topology handling or actor metadata. Geometry-only contacts and multiple backend-emitted rows per actor pair are valid; sensor adaptation does not synthesize a common contact manifold. +`ContactPermissionChecker` consumes complete native samples with explicit +actor/frame permissions, returning owned per-row device summaries. It does not +choose the host's sampling frequency or relax unavailable-impulse/loss gates. +Global static actors retain their explicit row memberships. Rebind after query +topology changes. Default CUDA dynamics can select ordinary reporting through +`DefaultPhysicsCfg.direct_gpu_api=False` when static actor identity is required; +this is independent of the physics device and leaves CPU defaults unchanged. + The contact scatter kernel remains sensor-owned because its columns, IDs and quota are integration contracts. Generic image tiling belongs to `embodichain/compute/image/_warp/tiling.py`; compatibility exports under diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index f4b35c2d77..9620eac1cb 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1662,6 +1662,16 @@ and durable episode-boundary recovery. See the offline expansion example. ExpansionCoverage EpisodeCoverage +.. autosummary:: + + ExpansionWorkloadCfg + WorkloadExecutionCfg + WorkloadAssignment + WorkloadRowResult + WorkloadSource + WorkloadProgramExecutor + export_expansion_episodes + embodichain.lab.expansion.artifacts ----------------------------------- @@ -1766,6 +1776,21 @@ attempts at episode boundaries. Native failures invalidate the active host. ExpansionRecipeSource PreparingExpansionHost +embodichain.lab.expansion.episode_export +--------------------------------------- + +.. currentmodule:: embodichain.lab.expansion.episode_export + +Export each confirmed qualified trajectory to an independently readable LeRobot +dataset, retaining its portable T+1 evidence, source hashes and recording journal. +Export uses frozen evidence and opens no simulation World. + +.. autosummary:: + + export_expansion_episodes + +.. autofunction:: export_expansion_episodes + embodichain.lab.expansion.export -------------------------------- @@ -1920,6 +1945,32 @@ Apply one native visual profile per compatible World cohort. Render complete rec render_observation_variants inspect_observation_variants +embodichain.lab.expansion.workloads +---------------------------------- + +.. currentmodule:: embodichain.lab.expansion.workloads + +Rolling Task Program execution in one caller-owned World with capacity +``workload_count * batch_size``. Sources retain task-owned scene proposals and +required physical qualification; native session and sink receipts remain the +authority for admission and committed quotas. Preparing rows settle through +ordinary World steps while live trajectories retain every control boundary. + +.. autosummary:: + + ExpansionWorkloadCfg + WorkloadExecutionCfg + WorkloadAssignment + WorkloadRowResult + WorkloadSource + WorkloadProgramExecutor + +.. autoclass:: WorkloadProgramExecutor + :members: + +.. autoclass:: WorkloadSource + :members: + embodichain.lab.expansion.workflow ---------------------------------- @@ -3654,6 +3705,32 @@ embodichain.lab.sim.sensors.camera Camera CameraCfg +embodichain.lab.sim.sensors.contact +---------------------------------- + +.. currentmodule:: embodichain.lab.sim.sensors.contact + +.. autosummary:: + + ContactPermissionChecker + +embodichain.lab.sim.sensors.contact.permissions +---------------------------------------------- + +.. currentmodule:: embodichain.lab.sim.sensors.contact.permissions + +Check complete native contact buffers against explicit actor/frame permissions. +The host chooses the original physical sampling rate; unavailable impulse, +unknown actors and dropped evidence cannot pass. Results are owned device-side +row summaries, suitable for every-substep observers without Python contact lists. + +.. autosummary:: + + ContactPermissionChecker + +.. autoclass:: ContactPermissionChecker + :members: + embodichain.lab.sim.sensors.contact.sensor ------------------------------------------ diff --git a/embodichain/compute/geometry/_warp/batch_contact_query.py b/embodichain/compute/geometry/_warp/batch_contact_query.py new file mode 100644 index 0000000000..af31b4fa4f --- /dev/null +++ b/embodichain/compute/geometry/_warp/batch_contact_query.py @@ -0,0 +1,90 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Per-environment reduction of one independent batched Newton query.""" + +from __future__ import annotations + +import warp as wp + +__all__: list[str] = [] + + +@wp.kernel(enable_backward=False) +def contact_summary( + count: wp.array(dtype=wp.int32), + first: wp.array(dtype=wp.int32), + second: wp.array(dtype=wp.int32), + point0: wp.array(dtype=wp.vec3), + point1: wp.array(dtype=wp.vec3), + normal: wp.array(dtype=wp.vec3), + margin0: wp.array(dtype=float), + margin1: wp.array(dtype=float), + shape_body: wp.array(dtype=wp.int32), + poses: wp.array(dtype=wp.transform), + active: wp.array(dtype=wp.int32), + width: int, + batches: int, + required: float, + tolerance: wp.array(dtype=float), + capacity: int, + broad_count: wp.array(dtype=wp.int32), + broad_capacity: int, + gjk_count: wp.array(dtype=wp.int32), + gjk_capacity: int, + split_count: wp.array(dtype=wp.int32), + split_capacity: int, + manifold_count: wp.array(dtype=wp.int32), + manifold_capacity: int, + output: wp.array2d(dtype=float), +): + index = wp.tid() + if index == 0: + if ( + count[0] >= capacity + or broad_count[0] > broad_capacity + or gjk_count[0] > gjk_capacity + or split_count[0] > split_capacity + or manifold_count[0] > manifold_capacity + ): + for row in range(batches): + wp.atomic_min(output, row, 2, 0.0) + if index < count[0] and index < capacity: + a, b = first[index], second[index] + if a < 0 or b < 0 or a >= width * batches or b >= width * batches: + for row in range(batches): + wp.atomic_min(output, row, 2, 0.0) + elif a // width != b // width: + for row in range(batches): + wp.atomic_min(output, row, 2, 0.0) + else: + row = a // width + x, y = a % width, b % width + if active[x * width + y] != 0: + p0 = wp.transform_point(poses[shape_body[a]], point0[index]) + p1 = wp.transform_point(poses[shape_body[b]], point1[index]) + distance = ( + wp.dot(normal[index], p1 - p0) - margin0[index] - margin1[index] + ) + if not wp.isfinite(distance): + wp.atomic_min(output, row, 2, 0.0) + else: + wp.atomic_min(output, row, 0, distance) + if distance <= required + tolerance[row]: + wp.atomic_min( + output, row, 1, float(wp.min(x, y) * width + wp.max(x, y)) + ) diff --git a/embodichain/compute/geometry/_warp/contact_permissions.py b/embodichain/compute/geometry/_warp/contact_permissions.py new file mode 100644 index 0000000000..5ebe6bac71 --- /dev/null +++ b/embodichain/compute/geometry/_warp/contact_permissions.py @@ -0,0 +1,98 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Inspect every measured native contact without materializing Python pairs.""" + +from __future__ import annotations + +import warp as wp + +__all__: list[str] = [] + + +@wp.func +def actor_index(actors: wp.array(dtype=wp.int32), value: int): + lower = int(0) + upper = actors.shape[0] + while lower < upper: + middle = (lower + upper) // 2 + if actors[middle] < value: + lower = middle + 1 + else: + upper = middle + return lower + + +@wp.kernel(enable_backward=False) +def classify_contacts( + pairs: wp.array3d(dtype=wp.int32), + valid: wp.array2d(dtype=wp.bool), + impulse_valid: wp.array2d(dtype=wp.bool), + actors: wp.array(dtype=wp.int32), + memberships: wp.array2d(dtype=wp.bool), + codes: wp.array(dtype=wp.int64), + moving: wp.array(dtype=wp.bool), + allowed: wp.array2d(dtype=wp.bool), + dropped: wp.array(dtype=wp.bool), + first_error: wp.array(dtype=wp.int32), + any_drop: wp.array(dtype=wp.int32), +): + row, slot = wp.tid() + if slot == 0 and dropped[row]: + wp.atomic_max(any_drop, 0, 1) + if valid[row, slot]: + reason = int(0) + if not impulse_valid[row, slot]: + reason = 1 + else: + left, right = pairs[row, slot, 0], pairs[row, slot, 1] + a, b = actor_index(actors, left), actor_index(actors, right) + if a == actors.shape[0] or b == actors.shape[0]: + reason = 2 + elif actors[a] != left or actors[b] != right: + reason = 2 + elif not memberships[a, row] or not memberships[b, row]: + reason = 2 + else: + x, y = codes[a], codes[b] + if (moving[x] or moving[y]) and not allowed[x, y]: + reason = 3 + if reason != 0: + wp.atomic_min(first_error, row, slot * 8 + reason) + + +@wp.kernel(enable_backward=False) +def contact_failures( + pairs: wp.array3d(dtype=wp.int32), + first_error: wp.array(dtype=wp.int32), + any_drop: wp.array(dtype=wp.int32), + output: wp.array2d(dtype=wp.int32), +): + row = wp.tid() + if any_drop[0] != 0: + output[row, 0] = 4 + output[row, 1] = 0 + output[row, 2] = 0 + elif first_error[row] < pairs.shape[1] * 8: + slot = first_error[row] // 8 + output[row, 0] = first_error[row] % 8 + output[row, 1] = pairs[row, slot, 0] + output[row, 2] = pairs[row, slot, 1] + else: + output[row, 0] = 0 + output[row, 1] = 0 + output[row, 2] = 0 diff --git a/embodichain/lab/expansion/__init__.py b/embodichain/lab/expansion/__init__.py index ff136b8f58..5a32997b25 100644 --- a/embodichain/lab/expansion/__init__.py +++ b/embodichain/lab/expansion/__init__.py @@ -60,6 +60,13 @@ "load_expansion_episode", "resolve_expansion_job", "build_expansion_report", + "ExpansionWorkloadCfg", + "WorkloadExecutionCfg", + "WorkloadAssignment", + "WorkloadRowResult", + "WorkloadSource", + "WorkloadProgramExecutor", + "export_expansion_episodes", ] @@ -98,6 +105,13 @@ def __getattr__(name: str) -> object: "load_expansion_episode": "persistence", "resolve_expansion_job": "configured", "build_expansion_report": "reporting", + "ExpansionWorkloadCfg": "workloads", + "WorkloadExecutionCfg": "workloads", + "WorkloadAssignment": "workloads", + "WorkloadRowResult": "workloads", + "WorkloadSource": "workloads", + "WorkloadProgramExecutor": "workloads", + "export_expansion_episodes": "episode_export", }.get(name, "engine") module = f"{__name__}.{owner}" value = getattr(import_module(module), name) diff --git a/embodichain/lab/expansion/_gym_frames.py b/embodichain/lab/expansion/_gym_frames.py index aee59d96bd..26ee4357bc 100644 --- a/embodichain/lab/expansion/_gym_frames.py +++ b/embodichain/lab/expansion/_gym_frames.py @@ -98,6 +98,19 @@ def __init__(self, context: GymHostContext, assignments: dict) -> None: spools[row] = spool self.records, self.spools = records, spools + def add(self, assignments: dict) -> None: + """Capture newly settled rows without replacing live measured buffers.""" + if set(assignments) & self.records.keys(): + raise ValueError("cannot replace a live measured row") + initial = GymFrameCollector(self.context, assignments) + self.records.update(initial.records) + self.spools.update(initial.spools) + + def discard(self, row: int) -> None: + """Release a row after evidence assembly and persistence confirmation.""" + self.records.pop(row) + self.spools.pop(row, None) + def observe(self, ids, action, observation) -> None: ctx = self.context cfg, env, view, collision, timings = ( @@ -147,30 +160,26 @@ def observe(self, ids, action, observation) -> None: timings["sampled_validation"] = ( timings.get("sampled_validation", 0.0) + time.monotonic() - stamp ) - for row in ids: - record = records[row] - value = ( - {"qpos": action.value} - if isinstance(action.value, torch.Tensor) - else action.value - ) + value = ( + {"qpos": action.value} + if isinstance(action.value, torch.Tensor) + else action.value + ) - def active_command(name): - data = value[name][row] - if data.shape[-1] == env.robot.dof: - data = data[list(env.active_joint_ids)] - elif data.shape[-1] != len(env.active_joint_ids): - raise ValueError("submitted command joint layout differs") - return data.detach().cpu() + def active_command(name): + data = value[name] + if data.shape[-1] == env.robot.dof: + data = data[:, list(env.active_joint_ids)] + elif data.shape[-1] != len(env.active_joint_ids): + raise ValueError("submitted command joint layout differs") + return data - command = active_command("qpos") - if env.expert_action_spec.joint_command_mode == "position_velocity": - command = torch.cat( - ( - command, - active_command("qvel"), - ) - ) + commands = active_command("qpos") + if env.expert_action_spec.joint_command_mode == "position_velocity": + commands = torch.cat((commands, active_command("qvel")), dim=-1) + commands = commands.detach().cpu() + for row in ids: + record = records[row] entity_states = {entity.uid: entity for entity in frame_state.batches[row]} for (uid, field), values in record["scene"].items(): values.append( @@ -179,7 +188,7 @@ def active_command(name): dtype=torch.float32, ) ) - record["actions"].append(command.clone()) + record["actions"].append(commands[row].clone()) record["qpos"].append(measured_qpos[row].clone()) record["qvel"].append(measured_qvel[row].clone()) record["qf"].append(measured_qf[row].clone()) diff --git a/embodichain/lab/expansion/_motion_batches.py b/embodichain/lab/expansion/_motion_batches.py new file mode 100644 index 0000000000..5bb52f16f6 --- /dev/null +++ b/embodichain/lab/expansion/_motion_batches.py @@ -0,0 +1,166 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Fuse compatible fixed-grid native motion requests before scalar transforms.""" + +from __future__ import annotations + +from copy import copy +from dataclasses import fields, is_dataclass, replace +from enum import Enum +from functools import wraps + +__all__: list[str] = [] + + +class MotionBatches: + """Keep selected physical rows and native fixed-grid rejection semantics.""" + + def __init__(self, broker): + from greenlet import getcurrent + from embodichain.lab.sim.motion.motion_generator import MotionGenerator + + self.broker = broker + self.original = original = MotionGenerator.generate + + def direct(generator, targets, options, defer_recovery): + previous = broker.motion_passthrough + broker.motion_passthrough = True + try: + return original( + generator, targets, options, defer_recovery=defer_recovery + ) + finally: + broker.motion_passthrough = previous + + @wraps(original) + def generate(generator, target_states, options=None, *, defer_recovery=False): + from embodichain.lab.sim.motion._budget import _ACTIVE_BUDGET + + task = getcurrent() + if ( + task not in broker.tasks + or options is None + or options.strategy != "ik_interp" + or options.interpolation_mode != "fixed_grid" + or options.segment_sample_count_retries + or options.segment_continuous_ik_recovery + or options.cartesian_path_sampler is not None + or generator.collision_world_info is not None + or generator._env_ids is None + or _ACTIVE_BUDGET.get() is not None + ): + return direct(generator, target_states, options, defer_recovery) + tensors = {} + try: + structure = self._describe( + (target_states, options), tensors, len(generator._env_ids) + ) + except TypeError: + return direct(generator, target_states, options, defer_recovery) + tensors["rows"] = broker.torch.tensor( + generator._env_ids, dtype=broker.torch.long + ) + mode = ( + broker.torch.is_grad_enabled(), + broker.torch.is_inference_mode_enabled(), + ) + key = ( + "motion", + id(generator.robot), + type(generator.planner), + repr(generator.planner.cfg), + structure, + defer_recovery, + mode, + ) + + def invoke(merged): + targets, settings = self._restore((target_states, options), merged) + batched = copy(generator) + batched.planner = copy(generator.planner) + batched._env_ids = tuple(merged["rows"].tolist()) + batched.planner._planning_env_ids = batched._env_ids + return original( + batched, targets, settings, defer_recovery=defer_recovery + ) + + request = (key, invoke, None, None, tensors, len(generator._env_ids), mode) + broker.tasks[task] = broker._rng() + broker._restore_rng(broker.owner_rng) + return broker.owner.switch(request) + + self.generate = generate + + def _describe(self, value, tensors, count, path=""): + torch = self.broker.torch + if isinstance(value, torch.Tensor): + if value.ndim < 1 or value.shape[0] != count: + raise TypeError("Motion tensors must retain the selected batch") + tensors[path] = value + return ("tensor", tuple(value.shape[1:]), value.dtype, value.device) + if is_dataclass(value): + return ( + type(value), + tuple( + ( + f.name, + self._describe( + getattr(value, f.name), tensors, count, path + "/" + f.name + ), + ) + for f in fields(value) + ), + ) + if isinstance(value, (tuple, list)): + return ( + type(value), + tuple( + self._describe(v, tensors, count, path + "/" + str(i)) + for i, v in enumerate(value) + ), + ) + if ( + value is None + or type(value) in (bool, int, float, str) + or isinstance(value, Enum) + ): + return (type(value), value) + raise TypeError("Unsupported mutable motion option") + + def _restore(self, value, tensors, path=""): + if isinstance(value, self.broker.torch.Tensor): + return tensors[path] + if is_dataclass(value): + return replace( + value, + **{ + f.name: self._restore( + getattr(value, f.name), tensors, path + "/" + f.name + ) + for f in fields(value) + }, + ) + if isinstance(value, (tuple, list)): + return type(value)( + self._restore(v, tensors, path + "/" + str(i)) + for i, v in enumerate(value) + ) + return value + + def close(self): + return None diff --git a/embodichain/lab/expansion/_planning_batches.py b/embodichain/lab/expansion/_planning_batches.py new file mode 100644 index 0000000000..8d7e587b51 --- /dev/null +++ b/embodichain/lab/expansion/_planning_batches.py @@ -0,0 +1,342 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Cooperatively batch native kinematics on the sole World-owning thread.""" + +from __future__ import annotations + +from collections import defaultdict +from contextlib import contextmanager +from functools import wraps +from inspect import signature +from dataclasses import fields, is_dataclass, replace +from contextvars import ContextVar, copy_context + +__all__: list[str] = [] + +_ACTIVE: ContextVar[PlanningBatches | None] = ContextVar( + "expansion_planning", default=None +) + + +def _try_motion(generator, targets, options, defer_recovery): + active = _ACTIVE.get() + if active is None or active.motion_passthrough: + return False, None + from greenlet import getcurrent + + if getcurrent() not in active.tasks: + return False, None + return True, active.motions.generate( + generator, targets, options, defer_recovery=defer_recovery + ) + + +class PlanningBatches: + """Suspend scalar planners only at pure solver calls, then fuse their rows. + + Native Robot budget decorators, plan transforms and validation run inside + each original cursor. No World call runs on a worker thread. Results are + cloned into independent rows before any scalar planner resumes. + """ + + def __init__(self, robot, seed): + import numpy as np + import random + import torch + from greenlet import getcurrent + + self.torch, self.np, self.random = torch, np, random + self.owner = getcurrent() + self.tasks = {} + self.saved = [] + self.solo = False + self.direct_depth = 0 + self.motion_passthrough = False + self.devices = ( + [ + ( + robot.device.index + if robot.device.index is not None + else torch.cuda.current_device() + ) + ] + if robot.device.type == "cuda" + else [] + ) + self.stats = { + "solver_calls": 0, + "logical_calls": 0, + "merged_calls": 0, + "max_group": 0, + "motion_calls": 0, + "logical_motion_calls": 0, + "merged_motion_calls": 0, + "max_motion_group": 0, + } + previous = self._rng() + torch.manual_seed(seed) + np.random.seed(seed % 2**32) + random.seed(seed) + self.solve_rng = self._rng() + self._restore_rng(previous) + for solver in dict.fromkeys(robot._solvers.values()): + for name in ("get_fk", "get_ik", "get_jacobian"): + self._bind(solver, name) + from ._motion_batches import MotionBatches + + self.motions = MotionBatches(self) + + def _rng(self): + return ( + self.torch.get_rng_state(), + tuple(self.torch.cuda.get_rng_state(d) for d in self.devices), + self.np.random.get_state(), + self.random.getstate(), + self.torch.is_grad_enabled(), + self.torch.is_inference_mode_enabled(), + ) + + def _restore_rng(self, state): + self.torch.set_rng_state(state[0]) + for device, value in zip(self.devices, state[1]): + self.torch.cuda.set_rng_state(value, device) + self.np.random.set_state(state[2]) + self.random.setstate(state[3]) + + def _bind(self, solver, name): + from greenlet import getcurrent + + original = getattr(solver, name, None) + if original is None: + return + spec = signature(original) + missing = object() + before = solver.__dict__.get(name, missing) + + @wraps(original) + def query(*args, **kwargs): + task = getcurrent() + if task not in self.tasks: + counted = self.solo and self.direct_depth == 0 + if counted: + self.stats["solver_calls"] += 1 + self.stats["logical_calls"] += 1 + self.stats["max_group"] = max(self.stats["max_group"], 1) + self.direct_depth += 1 + try: + return original(*args, **kwargs) + finally: + self.direct_depth -= 1 + values = spec.bind(*args, **kwargs) + values.apply_defaults() + tensors, constants, count = {}, {}, None + for key, value in values.arguments.items(): + if isinstance(value, self.torch.Tensor): + if value.ndim < 2 or ( + count is not None and value.shape[0] != count + ): + return original(*args, **kwargs) + count = int(value.shape[0]) + tensors[key] = value + elif value is None or type(value) in (bool, int, float, str): + constants[key] = value + elif type(value) is dict and not value: + constants[key] = value + else: + return original(*args, **kwargs) + if count is None: + return original(*args, **kwargs) + mode = ( + self.torch.is_grad_enabled(), + self.torch.is_inference_mode_enabled(), + ) + key = ( + id(solver), + name, + mode, + tuple( + (key, tuple(value.shape[1:]), value.dtype, value.device) + for key, value in tensors.items() + ), + tuple((key, repr(value)) for key, value in constants.items()), + ) + request = (key, original, spec, values, tensors, count, mode) + self.tasks[task] = self._rng() + self._restore_rng(self.owner_rng) + return self.owner.switch(request) + + setattr(solver, name, query) + self.saved.append((solver, name, before, missing)) + + def _invoke(self, request, tensors): + _, original, spec, values, _, _, mode = request + if request[0][0] == "motion": + with ( + self.torch.inference_mode(mode[1]), + self.torch.set_grad_enabled(mode[0]), + ): + return original(tensors) + arguments = dict(values.arguments) + arguments.update(tensors) + # BoundArguments retains variadic **kwargs and keyword-only arguments. + bound = spec.bind_partial() + bound.arguments.update(arguments) + with self.torch.inference_mode(mode[1]), self.torch.set_grad_enabled(mode[0]): + return original(*bound.args, **bound.kwargs) + + def _part(self, result, start, stop, total=None): + if isinstance(result, self.torch.Tensor): + if result.ndim and (total is None or result.shape[0] == total): + return result[start:stop].clone() + return result.clone() + if isinstance(result, tuple): + return tuple(self._part(value, start, stop, total) for value in result) + if isinstance(result, dict): + return { + key: self._part(value, start, stop, total) + for key, value in result.items() + } + if is_dataclass(result): + return replace( + result, + **{ + f.name: self._part(getattr(result, f.name), start, stop, total) + for f in fields(result) + }, + ) + if result is None or type(result) in (bool, int, float, str): + return result + raise TypeError("Batched native solver returned an unsupported result") + + def gather(self, cursors): + """Advance every native cursor once, merging compatible pending solves.""" + from greenlet import greenlet + + if len(cursors) == 1: + row, cursor = next(iter(cursors.items())) + self.solo = True + try: + action = cursor.next() + return {} if action is None else {row: action} + finally: + self.solo = False + self.owner_rng = self._rng() + ready, waiting = {}, {} + + def advance(task, row, value=None, first=False): + state = self.owner_rng if first else self.tasks[task] + self._restore_rng(state) + try: + with ( + self.torch.inference_mode(state[5]), + self.torch.set_grad_enabled(state[4]), + ): + result = task.switch() if first else task.switch(value) + finally: + self._restore_rng(self.owner_rng) + if task.dead: + if result is not None: + ready[row] = result + else: + waiting[task] = (row, result) + + try: + for row, cursor in cursors.items(): + task = greenlet(cursor.next, parent=self.owner) + task.gr_context = copy_context() + self.tasks[task] = self.owner_rng + advance(task, row, first=True) + while waiting: + groups = defaultdict(list) + for task, (row, request) in waiting.items(): + groups[request[0]].append((task, row, request)) + waiting = {} + for group in groups.values(): + first = group[0][2] + tensors = { + key: self.torch.cat( + [entry[2][4][key] for entry in group], dim=0 + ) + for key in first[4] + } + self._restore_rng(self.solve_rng) + try: + result = self._invoke(first, tensors) + finally: + self.solve_rng = self._rng() + self._restore_rng(self.owner_rng) + if first[0][0] == "motion": + self.stats["motion_calls"] += 1 + self.stats["logical_motion_calls"] += len(group) + self.stats["merged_motion_calls"] += len(group) > 1 + self.stats["max_motion_group"] = max( + self.stats["max_motion_group"], len(group) + ) + else: + self.stats["solver_calls"] += 1 + self.stats["logical_calls"] += len(group) + self.stats["merged_calls"] += len(group) > 1 + self.stats["max_group"] = max( + self.stats["max_group"], len(group) + ) + start, parts = 0, [] + total = sum(entry[2][5] for entry in group) + for task, row, request in group: + stop = start + request[5] + parts.append(self._part(result, start, stop, total)) + start = stop + for (task, row, _), part in zip(group, parts): + advance(task, row, part) + return ready + finally: + for task in tuple(self.tasks): + if not task.dead: + self._restore_rng(self.tasks[task]) + try: + state = self.tasks[task] + with ( + self.torch.inference_mode(state[5]), + self.torch.set_grad_enabled(state[4]), + ): + task.throw() + finally: + self._restore_rng(self.owner_rng) + self.tasks.clear() + self._restore_rng(self.owner_rng) + + def close(self): + self.motions.close() + for solver, name, value, missing in reversed(self.saved): + if value is missing: + delattr(solver, name) + else: + setattr(solver, name, value) + self.saved.clear() + + +@contextmanager +def batched_planning(robot, seed): + batches = PlanningBatches(robot, seed) + token = _ACTIVE.set(batches) + try: + yield batches + finally: + try: + batches.close() + finally: + _ACTIVE.reset(token) diff --git a/embodichain/lab/expansion/_workload_cursor.py b/embodichain/lab/expansion/_workload_cursor.py new file mode 100644 index 0000000000..b61fe04fea --- /dev/null +++ b/embodichain/lab/expansion/_workload_cursor.py @@ -0,0 +1,105 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Candidate-owned RNG streams around the canonical command handshake.""" + +from __future__ import annotations + +import random +from typing import Any +import numpy as np +import torch +from tensordict import TensorDict + +from embodichain.lab.gym.envs.types import ControllerAction +from embodichain.lab.gym.envs.task_program.bridge import TaskProgramDemoBridge +from .program import _Cursor + +__all__: list[str] = [] + + +class _WorkloadCursor(_Cursor): + def __init__(self, bridge: TaskProgramDemoBridge, robot: Any, seed: int) -> None: + super().__init__(bridge) + self.robot = robot + self.rejection = None + self.last_command = None + self.devices = ( + [ + ( + robot.device.index + if robot.device.index is not None + else torch.cuda.current_device() + ) + ] + if robot.device.type == "cuda" + else [] + ) + self.cpu_rng = torch.Generator().manual_seed(seed).get_state() + self.gpu_rng = ( + torch.Generator(device=robot.device).manual_seed(seed).get_state() + if self.devices + else None + ) + self.numpy_rng = np.random.RandomState(seed % (2**32)).get_state() + self.python_rng = random.Random(seed).getstate() + + def next(self) -> ControllerAction | None: + before_numpy, before_python = np.random.get_state(), random.getstate() + with torch.random.fork_rng(devices=self.devices): + torch.set_rng_state(self.cpu_rng) + if self.devices: + torch.cuda.set_rng_state(self.gpu_rng, self.devices[0]) + np.random.set_state(self.numpy_rng) + random.setstate(self.python_rng) + try: + action = super().next() + if action is not None: + self.last_command = action + if self.finished and self.rejection is not None: + self.accepted, self.reason = False, self.rejection + return action + finally: + self.cpu_rng = torch.get_rng_state() + if self.devices: + self.gpu_rng = torch.cuda.get_rng_state(self.devices[0]) + self.numpy_rng, self.python_rng = ( + np.random.get_state(), + random.getstate(), + ) + np.random.set_state(before_numpy) + random.setstate(before_python) + + def abort(self, reason: str) -> None: + if self.finished or self.rejection is not None or self.emergency is not None: + return + if not self.pending_consumed: + # An unconsumed command must go through the original safe-stop + # iterator; acknowledging it here would manufacture a World step. + super().abort(reason) + return + ids = tuple(self.bridge.env_ids.tolist()) + hold = self.robot.get_qpos(target=True)[list(ids)].clone() + previous = self.last_command.value + if isinstance(previous, torch.Tensor): + value = hold + else: + fields = {"qpos": hold} + if "qvel" in previous: + fields["qvel"] = torch.zeros_like(hold) + value = TensorDict(fields, batch_size=[len(ids)]) + self.bridge.request_row_rejection(ids, ControllerAction(value), reason=reason) + self.rejection = reason diff --git a/embodichain/lab/expansion/collision.py b/embodichain/lab/expansion/collision.py index 966161bc50..99d9af01a0 100644 --- a/embodichain/lab/expansion/collision.py +++ b/embodichain/lab/expansion/collision.py @@ -64,6 +64,7 @@ def _measured_frame(env, snapshot, shapes): [state.qpos for state in entities[env.robot.uid]], dtype=torch.float32 ) return SimpleNamespace( + num_envs=env.num_envs, robot=SimpleNamespace(joint_names=env.robot.joint_names, get_qpos=lambda: qpos), sim=SimpleNamespace( get_rigid_object_uid_list=lambda: tuple(bodies), @@ -106,7 +107,7 @@ def __init__(self, env, profile: str, output: Path): ) self.results = {} - def prepare(self, snapshot=None): + def prepare(self, snapshot=None, *, env_ids=None): from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( collision_bodies_from_simulation, ) @@ -116,9 +117,17 @@ def prepare(self, snapshot=None): raise ValueError( "cohort collision geometry differs; create a compatible world" ) - self.results.clear() - self.initial.clear() - self.terminal.clear() + ids = tuple(self.monitors) if env_ids is None else tuple(env_ids) + if ( + not ids + or len(set(ids)) != len(ids) + or any(row not in self.monitors for row in ids) + ): + raise ValueError("prepare requires unique physical monitor rows") + for row in ids: + self.results.pop(row, None) + self.initial.pop(row, None) + self.terminal.pop(row, None) self.shapes = { uid: tuple( self.env.sim.get_rigid_object(uid).get_collision_shapes(env_id=row) @@ -131,25 +140,36 @@ def prepare(self, snapshot=None): if snapshot is None else _measured_frame(self.env, snapshot, self.shapes) ) - for row, monitor in self.monitors.items(): - monitor.reset(measured) - self.initial[row] = all( - monitor.predicate(measured, c) for c in self.initial_conditions - ) and not all(monitor.predicate(measured, c) for c in monitor.final_checks) + for row in ids: + self.monitors[row].reset(measured) + with MeasuredTaskMonitor.batch_scope( + measured, + tuple(self.monitors.values()), + extra_conditions=self.initial_conditions, + ): + for row in ids: + monitor = self.monitors[row] + self.initial[row] = all( + monitor.predicate(measured, c) for c in self.initial_conditions + ) and not all( + monitor.predicate(measured, c) for c in monitor.final_checks + ) def sample(self, ids, action, snapshot=None): env = self.env measured = ( env if snapshot is None else _measured_frame(env, snapshot, self.shapes) ) + poses = env.robot.body_data.body_link_pose + matrices = torch.eye(4, device=poses.device, dtype=poses.dtype).repeat( + env.num_envs, len(env.robot.link_names), 1, 1 + ) + matrices[..., :3, :3] = matrix_from_quat(poses[..., 3:]) + matrices[..., :3, 3] = poses[..., :3] + matrices = matrices.detach().cpu().numpy() frames = { - f"{env.robot.uid}/{name}": env.robot.get_link_pose( - link_name=name, to_matrix=True - ) - .detach() - .cpu() - .numpy() - for name in env.robot.link_names + f"{env.robot.uid}/{name}": matrices[:, index] + for index, name in enumerate(env.robot.link_names) } frames.update( { @@ -161,20 +181,26 @@ def sample(self, ids, action, snapshot=None): for uid in env.sim.get_rigid_object_uid_list() } ) + frames["default_plane"] = np.broadcast_to(np.eye(4), (env.num_envs, 4, 4)) + with MeasuredTaskMonitor.batch_scope(measured, tuple(self.monitors.values())): + for row in ids: + self.monitors[row].observe(measured, action) + self.terminal[row] = self.monitors[row].validation(measured) + groups = {} for row in ids: - self.monitors[row].observe(measured, action) - self.terminal[row] = self.monitors[row].validation(measured) metadata = action.metadata["row_actions"][str(row)] phase = self.phase(env, SimpleNamespace(metadata=metadata), None) - row_frames = {key: value[row] for key, value in frames.items()} - row_frames["default_plane"] = np.eye(4) - report, _ = self.checker.check( - row_frames, - allowed_contacts=phase.allowed_contacts, + groups.setdefault(tuple(phase.allowed_contacts), []).append(row) + for allowed, rows in groups.items(): + reports = self.checker.check_batch( + frames, + allowed_contacts=allowed, moving_objects=self.moving, + env_ids=rows, ) - if row not in self.results or report.status != "passed": - self.results[row] = report + for row, report in zip(rows, reports): + if row not in self.results or report.status != "passed": + self.results[row] = report def close(self): self.checker.close() diff --git a/embodichain/lab/expansion/contracts.py b/embodichain/lab/expansion/contracts.py index e0612291d2..81d3265b36 100644 --- a/embodichain/lab/expansion/contracts.py +++ b/embodichain/lab/expansion/contracts.py @@ -115,19 +115,9 @@ def _poses(values: Mapping[str, torch.Tensor], name: str) -> Mapping[str, torch. def _json(value: object) -> object: - if value is None or type(value) in (str, bool, int): - return value - if type(value) is float and math.isfinite(value): - return value - if isinstance(value, (list, tuple)): - return tuple(_json(item) for item in value) - if isinstance(value, Mapping): - result = {} - for key, item in value.items(): - _text(key, "metadata key") - result[key] = _json(item) - return MappingProxyType(result) - raise ValueError("metadata must contain only finite JSON values") + from embodichain.utils._owned_json import freeze_metadata + + return freeze_metadata(value) def _phases( diff --git a/embodichain/lab/expansion/engine.py b/embodichain/lab/expansion/engine.py index 7e2aa3543d..ef38064d6e 100644 --- a/embodichain/lab/expansion/engine.py +++ b/embodichain/lab/expansion/engine.py @@ -225,6 +225,8 @@ def __init__( self._write_failures: set[str] = set() self._resolved_receipts: dict[tuple[str, int], CommitReceipt] = {} self._failed = False + self._row_assignments: dict[int, ExpansionAssignment] = {} + self._started_rows: set[int] = set() self.timings: dict[str, float] = {} def _measure(self, name, operation, *args, **kwargs): @@ -327,6 +329,8 @@ def run(self) -> Mapping[str, object]: return self._drain() def _drain(self, *, one_batch: bool = False) -> Mapping[str, object]: + if self._row_assignments: + raise RuntimeError("finish active rolling rows before draining a cohort") if self._failed: raise RuntimeError( "host failed; construct a new host before further execution" @@ -476,6 +480,122 @@ def on_started(identity: CandidateIdentity) -> None: break return self._snapshot() + def admit_row(self, item: PreparedEpisodeWorkItem) -> ExpansionAssignment | None: + """Admit one independently prepared physical row through the native session. + + Args: + item: Host-owned candidate proposed in this session, bound to its + actual World row. Cohort collection remains unchanged. + + Returns: + Assigned episode/commit identity, or None for rejected preparation + or session backpressure. No rollout starts until + :meth:`mark_row_started` is called after a consumed command. + """ + if self._configured_cfg is not None or self._failed: + raise RuntimeError("row admission requires a healthy custom engine") + if not isinstance(item, PreparedEpisodeWorkItem): + raise TypeError("rolling admission requires PreparedEpisodeWorkItem") + if ( + not 0 <= item.env_id < self.cfg.batch_size + or item.env_id in self._row_assignments + ): + raise ValueError("physical row is outside capacity or already assigned") + self.flush() + self.enqueue((item,)) + identity = item.candidate.identity + try: + checked = self._measure("admission", self.host.validate_plan, item) + if not checked.accepted: + self.session.release(identity, reason="planning_validation_failed") + self._queue.remove(item) + return None + self.session.add_prepared_episode(item.candidate, checked) + self._admitted.add(identity.candidate_id) + ready = self.session.take_ready( + identity.scene_case_id, + identity.initial_state_id, + episode_byte_budget=self.cfg.episode_byte_budget, + candidate_id=identity.candidate_id, + ) + if ready is None: + self.session.release(identity, reason="row_admission_backpressure") + self._queue.remove(item) + return None + episode_id, commit_id = self.session.episode_ids(identity) + assignment = ExpansionAssignment(item, item.env_id, episode_id, commit_id) + self._row_assignments[item.env_id] = assignment + return assignment + except BaseException: + self._failed = True + self.session.release(identity, reason="row_admission_failed") + if item in self._queue: + self._queue.remove(item) + raise + + def mark_row_started(self, assignment: ExpansionAssignment) -> None: + """Count a rolling rollout after its first actual World command. + + Args: + assignment: Exact identity returned by :meth:`admit_row`. + """ + row = assignment.env_id + if self._row_assignments.get(row) != assignment or row in self._started_rows: + raise ValueError("unexpected or repeated rolling rollout start") + self.session.mark_rollout_started(assignment.item.spec.identity) + self._started_rows.add(row) + + def complete_row( + self, assignment: ExpansionAssignment, episode: ExpertEpisode | None + ) -> CommitReceipt | None: + """Qualify and persist a row using ordinary native receipt accounting. + + Args: + assignment: Exact active row identity returned by :meth:`admit_row`. + episode: Measured evidence for the consumed commands, or rejection. + + Returns: + Confirmed native receipt or None for rejected evidence. Unconfirmed + writes raise and retain pending evidence for the normal reconciliation + API; a physical slot cannot earn quota before persistence confirms. + """ + row = assignment.env_id + if self._row_assignments.get(row) != assignment: + raise ValueError("completion does not identify an active rolling row") + identity = assignment.item.spec.identity + if episode is not None and ( + not isinstance(episode, ExpertEpisode) + or episode.identity != identity + or row not in self._started_rows + or (episode.episode_id, episode.commit_id) + != (assignment.episode_id, assignment.commit_id) + ): + self._failed = True + self.session.release(identity, reason="invalid_measured_evidence") + raise ValueError("host returned mismatched or unstarted evidence") + receipt = None + if episode is None: + self.session.release(identity, reason="host_rejected") + else: + accepted = self.session.accept_episode(episode) + if accepted: + self._pending[episode.commit_id] = episode + callback = getattr(self.host, "on_acceptance", None) + if callback is not None: + callback(assignment, episode, accepted) + if accepted: + self.flush() + key = episode.commit_id, self._submission_ids.get(episode.commit_id, 0) + receipt = self._resolved_receipts.get(key) + if receipt is None or not receipt.confirmed: + raise RuntimeError( + "unconfirmed persistence cannot release a rolling row" + ) + self._queue.remove(assignment.item) + del self._row_assignments[row] + self._started_rows.discard(row) + return receipt + def run_source(self, source: ExpansionRecipeSource) -> Mapping[str, object]: """Drive bounded source batches through the same admission/execution/writer core. diff --git a/embodichain/lab/expansion/episode_export.py b/embodichain/lab/expansion/episode_export.py new file mode 100644 index 0000000000..8c578a251a --- /dev/null +++ b/embodichain/lab/expansion/episode_export.py @@ -0,0 +1,129 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""One independently readable LeRobot dataset per accepted expansion episode.""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path +import shutil +from tempfile import TemporaryDirectory +from uuid import NAMESPACE_URL, uuid5 + +from embodichain.data_pipeline.recording.media import ( + _digest as file_digest, + _atomic_json as atomic_json, +) + +__all__ = ["export_expansion_episodes"] + + +def _verify_dataset(dataset: Path, expected: dict) -> None: + from embodichain.data_pipeline.recording.journal import inspect_recording + from embodichain.lab.expansion import ArtifactEpisodeSink + + saved = json.loads((dataset / "expansion-episode.json").read_text()) + if saved != expected: + raise ValueError(f"LeRobot dataset belongs to different evidence: {dataset}") + info = json.loads((dataset / "meta/info.json").read_text()) + if (info["total_episodes"], info["total_frames"]) != (1, expected["steps"]): + raise ValueError(f"Expected exactly one complete LeRobot episode: {dataset}") + report = inspect_recording(dataset) + identity = str(uuid5(NAMESPACE_URL, expected["episode_id"])) + if not report["ok"] or [row["episode_uuid"] for row in report["commits"]] != [ + identity + ]: + raise ValueError(f"Incomplete LeRobot recording: {dataset}: {report}") + receipts = ArtifactEpisodeSink(dataset / "embodichain_artifacts").inspect() + if [(row.episode_id, row.commit_id) for row in receipts] != [ + (expected["episode_id"], expected["commit_id"]) + ]: + raise ValueError(f"LeRobot evidence bundle differs: {dataset}") + + +def export_expansion_episodes(directory: str | Path) -> dict: + """Save each accepted episode under its source-owned output directory. + + Each returned + ``dataset_path`` is relative to ``directory/lerobot`` and contains exactly + one LeRobot episode. The full T+1 evidence and media remain in the portable + ``embodichain_artifacts/`` bundle alongside the T action rows. + + Args: + directory: Source-owned ArtifactEpisodeSink directory with confirmed + native receipts. It is read and fully verified before exporting. + + Returns: + Manifest with the episode count, export directory and content-addressed + relative dataset paths. Each dataset contains exactly one accepted + episode and its complete portable source/media evidence. Existing exports + are verified rather than silently overwritten. No World is constructed. + """ + from embodichain.lab.expansion import ArtifactEpisodeSink, load_expansion_episode + from embodichain.lab.expansion.export import export_expansion_lerobot + + directory = Path(directory).resolve() + if not directory.is_dir(): + raise FileNotFoundError(f"Expansion directory does not exist: {directory}") + receipts = ArtifactEpisodeSink(directory).inspect() + output = directory / "lerobot" + output.mkdir(parents=True, exist_ok=True) + datasets = [] + for receipt in receipts: + episode = load_expansion_episode(receipt.storage_id) + # Content-addressed names cannot introduce path components from user IDs. + key = hashlib.sha256(receipt.commit_id.encode()).hexdigest() + destination = output / key + identity = { + "schema_version": 1, + "episode_id": episode.episode_id, + "commit_id": episode.commit_id, + "source_sha256": file_digest(Path(receipt.storage_id)), + "steps": len(episode.actions), + } + if destination.exists(): + _verify_dataset(destination, identity) + else: + # The native exporter accepts a complete job. Give it one frozen + # accepted episode, then publish only the self-contained dataset. + # No environment, physics replay or render window is constructed. + with TemporaryDirectory(prefix=".lerobot-", dir=output) as temporary: + isolated = Path(temporary) / "job" + source = Path(receipt.storage_id).parent + if (source / "artifacts.json").is_file(): + # Portable committed evidence is already frozen and fully + # verified above. Preserve its bytes and receipts instead + # of loading/freezing/compressing an identical new episode. + shutil.copytree(source, isolated / "episodes" / source.name) + else: + ArtifactEpisodeSink(isolated).submit(episode, submission_id=0) + result = export_expansion_lerobot(None, isolated) + dataset = Path(result["dataset_path"]) + atomic_json(dataset / "expansion-episode.json", identity) + _verify_dataset(dataset, identity) + dataset.rename(destination) + datasets.append({**identity, "dataset_path": key}) + manifest = { + "schema_version": 1, + "format": "lerobot", + "episodes": len(datasets), + "datasets": datasets, + } + atomic_json(output / "manifest.json", manifest) + return {**manifest, "directory": str(output)} diff --git a/embodichain/lab/expansion/persistence.py b/embodichain/lab/expansion/persistence.py index 5683a8033a..4d688b8841 100644 --- a/embodichain/lab/expansion/persistence.py +++ b/embodichain/lab/expansion/persistence.py @@ -18,12 +18,14 @@ from __future__ import annotations from dataclasses import asdict, replace +from collections import OrderedDict import hashlib import json import os from pathlib import Path import tempfile import shutil +from threading import RLock import numpy as np from embodichain.lab.gym.envs._json import json_safe_copy from .contracts import ExpertEpisode, CommitReceipt @@ -39,6 +41,10 @@ __all__ = ["ArtifactEpisodeSink", "load_expansion_episode"] +_EPISODE_CACHE = OrderedDict() +_EPISODE_CACHE_LOCK = RLock() +_EPISODE_CACHE_BYTES = 0 + def _source_references(metadata): references = [ @@ -65,6 +71,45 @@ def load_expansion_episode(path: str | Path) -> ExpertEpisode: Legacy staged episodes remain readable in place. New artifacts carry only relative references and can be moved without changing their frozen bytes. """ + global _EPISODE_CACHE_BYTES + path = Path(path).resolve() + # Re-read all evidence bytes on every call. Path/mtime keys alone could + # conceal tampering; this cache only avoids repeated parsing/JSON ownership. + with path.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").digest() + with _EPISODE_CACHE_LOCK: + cached = _EPISODE_CACHE.get(path) + if cached is not None and cached[0] == digest: + _EPISODE_CACHE.move_to_end(path) + # Construction retains every numeric check and owns fresh tensors. + return replace(cached[1]) + episode = _load_expansion_episode(path) + with path.open("rb") as stream: + if hashlib.file_digest(stream, "sha256").digest() != digest: + raise ValueError("Evidence changed while loading") + prototype = replace(episode) + size = sum( + value.numel() * value.element_size() + for value in ( + prototype.actions, + prototype.timestamps, + *prototype.observations.values(), + ) + ) + with _EPISODE_CACHE_LOCK: + previous = _EPISODE_CACHE.pop(path, None) + if previous is not None: + _EPISODE_CACHE_BYTES -= previous[2] + if size <= 64 * 1024 * 1024: + _EPISODE_CACHE[path] = digest, prototype, size + _EPISODE_CACHE_BYTES += size + while len(_EPISODE_CACHE) > 16 or _EPISODE_CACHE_BYTES > 128 * 1024 * 1024: + _, (_, _, released) = _EPISODE_CACHE.popitem(last=False) + _EPISODE_CACHE_BYTES -= released + return episode + + +def _load_expansion_episode(path: Path) -> ExpertEpisode: from embodichain.lab.gym.envs.managers.real2sim_collection import ( load_staged_real2sim_episode, ) diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py new file mode 100644 index 0000000000..3f575924ba --- /dev/null +++ b/embodichain/lab/expansion/workloads.py @@ -0,0 +1,648 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""One World, rolling physical rows and receipt-qualified workload quotas.""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from contextlib import nullcontext +from dataclasses import dataclass +import math +import os +from threading import get_ident +import time +from typing import Any, Protocol, TYPE_CHECKING + +from embodichain.utils import configclass +from .contracts import CommitReceipt + +if TYPE_CHECKING: + from embodichain.lab.gym.envs.task_program.bridge import TaskProgramDemoBridge + from embodichain.lab.gym.envs.types import ControllerAction + from .program import ProgramBatchResult + +__all__ = [ + "ExpansionWorkloadCfg", + "WorkloadExecutionCfg", + "WorkloadAssignment", + "WorkloadRowResult", + "WorkloadSource", + "WorkloadProgramExecutor", +] + + +@configclass +class ExpansionWorkloadCfg: + """Bound one logical source independently of its physical slot. + + Args: + workload_id: Unique source/recipe group identifier. + target_episodes: Confirmed qualified receipts required for this group. + max_attempts: Physical candidate budget, including rejected preparations. + max_wall_time_s: Admission budget starting with the first candidate. + Already active trajectories retain their ordinary safe-stop path. + """ + + workload_id: str = "default" + target_episodes: int = 1 + max_attempts: int = 8 + max_wall_time_s: float = 600.0 + + def __post_init__(self) -> None: + if ( + type(self.workload_id) is not str + or not self.workload_id + or self.workload_id.strip() != self.workload_id + ): + raise ValueError("workload_id must be a nonempty stripped string") + for name in ("target_episodes", "max_attempts"): + if type(getattr(self, name)) is not int or getattr(self, name) < 1: + raise ValueError(f"{name} must be a positive integer") + if self.max_attempts < self.target_episodes: + raise ValueError("max_attempts must cover target_episodes") + if ( + type(self.max_wall_time_s) not in (int, float) + or not math.isfinite(self.max_wall_time_s) + or self.max_wall_time_s <= 0 + ): + raise ValueError("max_wall_time_s must be finite and positive") + + +@configclass +class WorkloadExecutionCfg: + """Declare physical capacity without allocating processes or Worlds. + + Args: + workload_count: Maximum simultaneous independent source groups, W. + batch_size: Candidate rows reserved for each active group, B. + max_steps: Maximum ordinary controller commands per candidate. + settling_steps: Minimum physical substeps before a row becomes active. + seed: Base seed; each candidate owns a stream keyed by local ordinal. + batch_planning: Cooperatively merge compatible native motion/solver calls. + """ + + workload_count: int = 1 + batch_size: int = 1 + max_steps: int = 2000 + settling_steps: int = 5 + seed: int = 0 + batch_planning: bool = True + + def __post_init__(self) -> None: + for name in ("workload_count", "batch_size", "max_steps"): + if type(getattr(self, name)) is not int or getattr(self, name) < 1: + raise ValueError(f"{name} must be a positive integer") + for name in ("settling_steps", "seed"): + if type(getattr(self, name)) is not int or getattr(self, name) < 0: + raise ValueError(f"{name} must be a nonnegative integer") + if type(self.batch_planning) is not bool: + raise TypeError("batch_planning must be a bool") + + @property + def num_envs(self) -> int: + """Return the required single-World capacity, W multiplied by B.""" + return self.workload_count * self.batch_size + + +@dataclass(frozen=True) +class WorkloadAssignment: + """Logical candidate identity bound to a physical row for one attempt. + + Args: + workload_id: Source group, independent of lane/row allocation. + ordinal: Zero-based candidate index local to this workload. + env_id: Physical environment row in the sole World. + seed: Candidate-owned random stream seed. + """ + + workload_id: str + ordinal: int + env_id: int + seed: int + + +@dataclass(frozen=True) +class WorkloadRowResult: + """Canonical bridge outcome and exact World control-boundary span. + + Args: + assignment: Candidate whose bridge and measured buffer were consumed. + program: Original Task Program result for this one physical row. + world_control_start: First actually consumed command boundary, or None. + world_control_end: Last consumed command boundary, or None. + """ + + assignment: WorkloadAssignment + program: ProgramBatchResult + world_control_start: int | None + world_control_end: int | None + + +class WorkloadSource(Protocol): + """Task-owned scene/plan/evidence ports; the executor alone steps the World. + + Sources retain native ExpansionSession admission, required physical checks, + evidence assembly and sink receipts. ``complete`` may return a receipt only + after all required checks pass and native persistence confirms the write. + Callbacks must not advance physics or create another World. A completed + group's frozen evidence can be exported independently of the live World. + """ + + def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: + """Apply selected-row changes inside the trusted reset callback.""" + ... + + def activate( + self, assignment: WorkloadAssignment, observation: object + ) -> TaskProgramDemoBridge | None: + """Validate measured preparation, capture T+1 initial data and bind a row.""" + ... + + def started(self, assignment: WorkloadAssignment, world_control_step: int) -> None: + """Mark rollout started in the native session after its first actual step.""" + ... + + def observe( + self, + assignments: tuple[WorkloadAssignment, ...], + action: ControllerAction, + observation: object, + ) -> Sequence[int]: + """Record every active boundary; return rows requiring safe rejection.""" + ... + + def complete(self, result: WorkloadRowResult) -> CommitReceipt | None: + """Assemble native evidence and return its confirmed receipt or rejection.""" + ... + + +class WorkloadProgramExecutor: + """Refill independent rows while preserving native bridge acknowledgement. + + Args: + environment: One initialized environment with exactly W times B rows. + workloads: Ordered source groups with independent quotas and budgets. + source: Host-owned scene, Task Program, validation and persistence ports. + cfg: Capacity and control/settling budgets; creates no World itself. + checkpoint: Optional cooperative cancellation/window callback, called at + control boundaries on the owner thread. + on_workload_done: Optional frozen-group notification. It receives an + owned count mapping and must not advance or mutate the live World. + """ + + def __init__( + self, + environment: Any, + workloads: Sequence[ExpansionWorkloadCfg], + source: WorkloadSource, + cfg: WorkloadExecutionCfg, + *, + checkpoint: Callable[[], None] | None = None, + on_workload_done: Callable[[str, Mapping[str, object]], None] | None = None, + ) -> None: + import torch + + if not isinstance(cfg, WorkloadExecutionCfg): + raise TypeError("cfg must be WorkloadExecutionCfg") + cfg.__post_init__() + self.env = getattr(environment, "unwrapped", environment) + if self.env.num_envs != cfg.num_envs: + raise ValueError( + "the single World must contain workload_count * batch_size environments" + ) + events = getattr(self.env, "event_manager", None) + if events is not None and events.active_functors.get("interval"): + raise ValueError("rolling expansion requires fixed episode parameters") + if not workloads or any( + not isinstance(w, ExpansionWorkloadCfg) for w in workloads + ): + raise ValueError("workloads must contain ExpansionWorkloadCfg values") + for workload in workloads: + workload.__post_init__() + self.workloads = { + w.workload_id: ExpansionWorkloadCfg(**w.to_dict()) for w in workloads + } + if len(self.workloads) != len(workloads) or cfg.workload_count > len(workloads): + raise ValueError("workload IDs must be unique and cover every active lane") + self.cfg, self.source = WorkloadExecutionCfg(**cfg.to_dict()), source + self.checkpoint, self.on_workload_done = checkpoint, on_workload_done + self.owner = get_ident() + from embodichain.lab.sim import SimulationManager + + if len(SimulationManager._instances) != 1: + raise ValueError( + "rolling workload collection requires one live World in its process" + ) + state_device = self.env.robot.get_qpos().device + if state_device.type != self.env.sim.device.type: + raise RuntimeError("measured robot state and World devices disagree") + self._world_info = { + "process_id": os.getpid(), + "world_instance_id": self.env.sim.instance_id, + "world_object_id": id(self.env.sim.get_world()), + "world_count": len(SimulationManager._instances), + "physics_backend": self.env.sim.physics_backend, + "physics_device": str(self.env.sim.device), + "state_device": str(state_device), + "gpu_physics": bool(self.env.sim.is_use_gpu_physics), + "solvers": { + name: {"class": type(solver).__name__, "device": str(solver.device)} + for name, solver in self.env.robot._solvers.items() + }, + } + self._used = False + self.lanes: list[str | None] = [None] * cfg.workload_count + self.counts = { + name: {"attempts": 0, "rollouts": 0, "committed": 0} + for name in self.workloads + } + self.started_at: dict[str, float] = {} + self.warming: dict[int, dict[str, Any]] = {} + self.live: dict[int, dict[str, Any]] = {} + self.completed: set[str] = set() + self.receipts: set[tuple[str, str, str]] = set() + self.control_steps = self.active_control_steps = self.refills = 0 + self.hold = self.env.robot.get_qpos(target=True).clone() + self.observation = None + self.planning_stats: dict[str, int] = {} + self.torch = torch + + @property + def world_info(self) -> Mapping[str, object]: + """Return owned actual process, World, state and solver device identities.""" + from copy import deepcopy + + return deepcopy(self._world_info) + + def _eligible(self, name: str) -> bool: + workload, counts = self.workloads[name], self.counts[name] + return ( + counts["committed"] < workload.target_episodes + and counts["attempts"] < workload.max_attempts + and ( + name not in self.started_at + or time.monotonic() - self.started_at[name] < workload.max_wall_time_s + ) + ) + + def _inflight(self, name: str) -> int: + return sum( + state["assignment"].workload_id == name + for state in (*self.live.values(), *self.warming.values()) + ) + + def _group_done(self, name: str) -> None: + if name not in self.completed: + self.completed.add(name) + if self.on_workload_done is not None: + self.on_workload_done(name, dict(self.counts[name])) + + def _fill(self) -> None: + added = [] + occupied = self.live.keys() | self.warming.keys() + for lane, name in enumerate(self.lanes): + if ( + name is not None + and not self._inflight(name) + and not self._eligible(name) + ): + self._group_done(name) + name = None + if name is None: + name = next( + ( + key + for key in self.workloads + if key not in self.lanes and self._eligible(key) + ), + None, + ) + self.lanes[lane] = name + if name is None: + continue + for row in range( + lane * self.cfg.batch_size, (lane + 1) * self.cfg.batch_size + ): + if row in occupied or not self._eligible(name): + continue + counts, spec = self.counts[name], self.workloads[name] + if counts["committed"] + self._inflight(name) >= spec.target_episodes: + break + assignment = WorkloadAssignment( + name, counts["attempts"], row, self.cfg.seed + counts["attempts"] + ) + counts["attempts"] += 1 + self.started_at.setdefault(name, time.monotonic()) + self.warming[row] = {"assignment": assignment, "settled": 0} + added.append(assignment) + if not added: + return + self.refills += bool(self.live) + assignments = tuple(added) + result = self.env.reset( + seed=self.cfg.seed, + options={ + "save_data": False, + "reset_ids": [a.env_id for a in added], + "episode_prepare": lambda: self.source.prepare(assignments), + }, + ) + self.observation = result[0] + rows = [a.env_id for a in added] + self.hold[rows] = self.env.robot.get_qpos(target=True)[rows] + + def _activate(self) -> None: + from ._workload_cursor import _WorkloadCursor + from .program import ProgramBatchResult + + for row in tuple(self.warming): + state = self.warming[row] + if state["settled"] < self.cfg.settling_steps: + continue + assignment = state["assignment"] + self.env._elapsed_steps[row] = 0 + self.env._reset_physical_objective((row,)) + bridge = self.source.activate(assignment, self.observation) + del self.warming[row] + if bridge is None: + outcome = ProgramBatchResult( + (row,), (0,), (False,), ("preparation_rejected",), ((),) + ) + if ( + self.source.complete( + WorkloadRowResult(assignment, outcome, None, None) + ) + is not None + ): + raise ValueError( + "unstarted or rejected preparation cannot earn a receipt" + ) + continue + if ( + tuple(bridge.env_ids.tolist()) != (row,) + or bridge.clock.step_index != 0 + or not math.isclose( + bridge.clock.step_dt, self.env.step_dt, rel_tol=0, abs_tol=1e-12 + ) + ): + raise ValueError( + "bridge must freshly bind exactly the assigned physical row and clock" + ) + self.live[row] = { + **state, + "cursor": _WorkloadCursor(bridge, self.env.robot, assignment.seed), + "start": None, + } + + def _finish(self, row: int) -> None: + from .program import ProgramBatchResult + + state = self.live[row] + assignment, cursor = state["assignment"], state["cursor"] + end = self.control_steps if cursor.length else None + if cursor.length and end - state["start"] + 1 != cursor.length: + raise RuntimeError("an active trajectory missed a World control boundary") + result = ProgramBatchResult( + (row,), + (cursor.length,), + (cursor.accepted,), + (cursor.reason,), + (tuple(cursor.results),), + ) + receipt = self.source.complete( + WorkloadRowResult(assignment, result, state["start"], end) + ) + if receipt is not None: + if ( + not isinstance(receipt, CommitReceipt) + or not receipt.confirmed + or not cursor.accepted + or not cursor.length + ): + raise ValueError( + "only confirmed qualified native receipts earn workload quota" + ) + identity = receipt.episode_id, receipt.candidate_id, receipt.commit_id + if any( + identity[i] == known[i] for known in self.receipts for i in range(3) + ): + raise ValueError( + "a repeated episode/candidate/commit cannot earn quota twice" + ) + self.receipts.add(identity) + self.counts[assignment.workload_id]["committed"] += 1 + cursor.close() + del self.live[row] + + def run(self) -> Mapping[str, object]: + """Collect until every group meets quota or exhausts its original budget. + + Returns: + Owned counts, completeness and actual World control/planning stats. + Failed quotas remain explicit; partial results never imply success. + """ + if get_ident() != self.owner or self._used: + raise RuntimeError( + "a workload executor is single-use on its World owner thread" + ) + self._used = True + from tensordict import TensorDict + from embodichain.lab.gym.envs.types import ControllerAction + from ._planning_batches import batched_planning + + env, torch = self.env, self.torch + previous_auto = getattr(env, "_demo_no_auto_reset", False) + had_mask = hasattr(env, "_demo_active_mask") + previous_mask = getattr(env, "_demo_active_mask", None) + env._demo_no_auto_reset = True + primary = None + planning = ( + batched_planning(env.robot, self.cfg.seed) + if self.cfg.batch_planning + else nullcontext() + ) + try: + with planning as planner: + while True: + if self.checkpoint is not None: + self.checkpoint() + self._fill() + self._activate() + cursors = {row: state["cursor"] for row, state in self.live.items()} + commands = ( + planner.gather(cursors) + if planner is not None + else { + row: command + for row, cursor in cursors.items() + if (command := cursor.next()) is not None + } + ) + for row in tuple(self.live): + if row not in commands: + self._finish(row) + if not commands and not self.warming: + if any(self._eligible(name) for name in self.workloads): + continue + break + qpos, qvel = self.hold.clone(), torch.zeros_like(self.hold) + velocity = ( + env.expert_action_spec.joint_command_mode == "position_velocity" + ) + for row in tuple(commands): + cursor = self.live[row]["cursor"] + if ( + cursor.length >= self.cfg.max_steps + and cursor.emergency is None + ): + cursor.abort("step_budget_exhausted") + replacement = cursor.next() + if replacement is None: + del commands[row] + self._finish(row) + continue + commands[row] = replacement + value = commands[row].value + fields = ( + {"qpos": value} + if isinstance(value, torch.Tensor) + else value + ) + if "qpos" not in fields or set(fields) - {"qpos", "qvel"}: + raise ValueError( + "workload rows require explicit position controller commands" + ) + if velocity and "qvel" not in fields: + raise ValueError( + "position-velocity evidence requires explicit velocity commands" + ) + for name, target in (("qpos", qpos), ("qvel", qvel)): + if name not in fields: + continue + data = fields[name] + if data.ndim != 2 or data.shape[0] != 1: + raise ValueError( + "row commands must retain one physical batch row" + ) + columns = ( + list(env.active_joint_ids) + if data.shape[1] == len(env.active_joint_ids) + else list(range(env.robot.dof)) + ) + if data.shape[1] != len(columns): + raise ValueError("row command joint layout differs") + target[row, columns] = data[0] + velocity |= name == "qvel" + if not commands and not self.warming: + continue + payload = {"qpos": qpos} + if velocity: + payload["qvel"] = qvel + action = ControllerAction( + TensorDict(payload, batch_size=[env.num_envs]), + metadata={ + "row_actions": { + str(row): dict(command.metadata) + for row, command in commands.items() + } + }, + ) + mask = torch.zeros( + env.num_envs, dtype=torch.bool, device=env.device + ) + mask[list(commands)] = True + env._demo_active_mask = mask + before = env.sim.physics_step_index + self.observation, _, terminated, truncated, _ = env.step(action) + advanced = env.sim.physics_step_index - before + if advanced <= 0: + raise RuntimeError( + "the owning World did not advance physical time" + ) + self.control_steps += 1 + self.active_control_steps += len(commands) + self.hold = qpos + for state in self.warming.values(): + state["settled"] += advanced + for row in commands: + state, cursor = self.live[row], self.live[row]["cursor"] + if cursor.length == 0: + state["start"] = self.control_steps + self.counts[state["assignment"].workload_id][ + "rollouts" + ] += 1 + self.source.started(state["assignment"], self.control_steps) + cursor.length += 1 + cursor.pending_consumed = True + assignments = tuple( + self.live[row]["assignment"] for row in commands + ) + rejected = ( + tuple( + self.source.observe(assignments, action, self.observation) + ) + if commands + else () + ) + if ( + len(set(rejected)) != len(rejected) + or set(rejected) - commands.keys() + ): + raise ValueError( + "source rejection must select unique active physical rows" + ) + for row in commands: + if row in rejected: + self.live[row]["cursor"].abort("measured_validation_failed") + elif bool(terminated[row]) or bool(truncated[row]): + self.live[row]["cursor"].abort("environment_terminated") + if planner is not None: + self.planning_stats = dict(planner.stats) + for name in self.workloads: + self._group_done(name) + return { + "complete": all( + self.counts[name]["committed"] == spec.target_episodes + for name, spec in self.workloads.items() + ), + "num_envs": self.cfg.num_envs, + "workload_count": self.cfg.workload_count, + "batch_size": self.cfg.batch_size, + "counts": {name: dict(values) for name, values in self.counts.items()}, + "control_steps": self.control_steps, + "active_control_steps": self.active_control_steps, + "refills": self.refills, + "planning": dict(self.planning_stats), + "world": self.world_info, + } + except BaseException as error: + primary = error + raise + finally: + cleanup = None + for state in self.live.values(): + try: + state["cursor"].close() + except BaseException as error: + cleanup = error + env._demo_no_auto_reset = previous_auto + if had_mask: + env._demo_active_mask = previous_mask + elif hasattr(env, "_demo_active_mask"): + delattr(env, "_demo_active_mask") + if primary is None and cleanup is not None: + raise cleanup diff --git a/embodichain/lab/gym/envs/_json.py b/embodichain/lab/gym/envs/_json.py index 660c687214..90ed8e7487 100644 --- a/embodichain/lab/gym/envs/_json.py +++ b/embodichain/lab/gym/envs/_json.py @@ -27,6 +27,10 @@ def json_safe_copy(value: Any, *, field_name: str) -> Any: """Return an owned JSON value without implicit type coercion.""" + from embodichain.utils._owned_json import _FrozenMap + + if type(value) is _FrozenMap and value._strict: + return value.mutable_copy() if value is None or type(value) in {bool, int, str}: return value if type(value) is float: diff --git a/embodichain/lab/sim/atomic_skills/_command_batches.py b/embodichain/lab/sim/atomic_skills/_command_batches.py new file mode 100644 index 0000000000..5aa5d41d1c --- /dev/null +++ b/embodichain/lab/sim/atomic_skills/_command_batches.py @@ -0,0 +1,188 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Validate owned CUDA command snapshots in bounded CPU slabs.""" + +from __future__ import annotations + +from collections import defaultdict +import torch +from .bindings import JointPositionTarget +from .runtime_commands import ( + EndpointCommand, + JointPositionPayload, + RuntimeCommandFrame, + TimedCommandSequence, +) + +__all__: list[str] = [] + + +def _transfer(tensors, device): + """Own one slab per dtype; preserve bits, shapes and independent field spans.""" + import torch + + grouped = defaultdict(dict) + for tensor in tensors: + grouped[tensor.dtype][id(tensor)] = tensor + copied = {} + for group in grouped.values(): + values = tuple(group.values()) + packed = torch.cat([value.detach().reshape(-1) for value in values]).to(device) + for value, part in zip(values, packed.split([v.numel() for v in values])): + copied[id(value)] = part.reshape(value.shape) + return copied + + +def leaves(frame): + if type(frame) is not RuntimeCommandFrame or type(frame.commands) not in ( + list, + tuple, + ): + return None + tensors = [frame.active_mask, frame.env_ids, frame.hold_duration] + for command in frame.commands: + if ( + type(command) is not EndpointCommand + or type(command.target) is not JointPositionTarget + or type(command.payload) is not JointPositionPayload + ): + return None + tensors.append(command.payload.positions) + if command.payload.velocities is not None: + tensors.append(command.payload.velocities) + if any(type(value) is not torch.Tensor or value.requires_grad for value in tensors): + return None + if frame.env_ids.device.type != "cuda" or any( + value.device != frame.env_ids.device for value in tensors + ): + return None + return tensors + + +def cpu_frame(frame, copied): + commands = tuple( + EndpointCommand( + target=command.target, + payload=JointPositionPayload( + positions=copied[id(command.payload.positions)], + velocities=( + copied[id(command.payload.velocities)] + if command.payload.velocities is not None + else None + ), + ), + ) + for command in frame.commands + ) + return RuntimeCommandFrame( + commands=commands, + active_mask=copied[id(frame.active_mask)], + env_ids=copied[id(frame.env_ids)], + hold_duration=copied[id(frame.hold_duration)], + ) + + +def own(cls, **fields): + value = object.__new__(cls) + for name, field in fields.items(): + object.__setattr__(value, name, field) + return value + + +def lift_frame(frame, copied): + return own( + RuntimeCommandFrame, + commands=tuple( + own( + EndpointCommand, + target=command.target, + payload=own( + JointPositionPayload, + positions=copied[id(command.payload.positions)], + velocities=( + copied[id(command.payload.velocities)] + if command.payload.velocities is not None + else None + ), + ), + ) + for command in frame.commands + ), + active_mask=copied[id(frame.active_mask)], + env_ids=copied[id(frame.env_ids)], + hold_duration=copied[id(frame.hold_duration)], + ) + + +def numeric(frame): + # Already passed all native CPU checks; collect owned validated fields. + values = [frame.active_mask, frame.env_ids, frame.hold_duration] + for command in frame.commands: + values.append(command.payload.positions) + if command.payload.velocities is not None: + values.append(command.payload.velocities) + return values + + +def validate_frame(frame): + values = leaves(frame) + if values is None: + return False + checked = cpu_frame(frame, _transfer(values, "cpu")) + result = lift_frame(checked, _transfer(numeric(checked), frame.env_ids.device)) + for name in ("commands", "active_mask", "env_ids", "hold_duration"): + object.__setattr__(frame, name, getattr(result, name)) + return True + + +def validate_sequence(sequence): + if ( + type(sequence.frames) not in (list, tuple) + or type(sequence.env_ids) is not torch.Tensor + or sequence.env_ids.device.type != "cuda" + or sequence.env_ids.requires_grad + ): + return False + tensors = [sequence.env_ids] + for frame in sequence.frames: + values = leaves(frame) + if values is None or frame.env_ids.device != sequence.env_ids.device: + return False + tensors.extend(values) + copied = _transfer(tensors, "cpu") + # Preserve native sequence-before-frame rejection order, including + # malformed mutable IDs in an otherwise previously valid snapshot. + TimedCommandSequence(frames=(), env_ids=copied[id(sequence.env_ids)]) + for index, frame in enumerate(sequence.frames): + if not torch.equal(copied[id(frame.env_ids)], copied[id(sequence.env_ids)]): + raise ValueError(f"Frame {index} env_ids do not match the sequence.") + checked = TimedCommandSequence( + frames=tuple(cpu_frame(frame, copied) for frame in sequence.frames), + env_ids=copied[id(sequence.env_ids)], + ) + tensors = [checked.env_ids] + for frame in checked.frames: + tensors.extend(numeric(frame)) + copied = _transfer(tensors, sequence.env_ids.device) + object.__setattr__( + sequence, + "frames", + tuple(lift_frame(frame, copied) for frame in checked.frames), + ) + object.__setattr__(sequence, "env_ids", copied[id(checked.env_ids)]) + return True diff --git a/embodichain/lab/sim/atomic_skills/runtime_commands.py b/embodichain/lab/sim/atomic_skills/runtime_commands.py index 606438a584..de474be3f9 100644 --- a/embodichain/lab/sim/atomic_skills/runtime_commands.py +++ b/embodichain/lab/sim/atomic_skills/runtime_commands.py @@ -260,6 +260,10 @@ class RuntimeCommandFrame: hold_duration: torch.Tensor def __post_init__(self) -> None: + from ._command_batches import validate_frame + + if validate_frame(self): + return if isinstance(self.commands, (str, bytes)): raise TypeError("commands must be an iterable of EndpointCommand values.") try: @@ -410,6 +414,10 @@ class TimedCommandSequence: env_ids: torch.Tensor def __post_init__(self) -> None: + from ._command_batches import validate_sequence + + if validate_sequence(self): + return if not isinstance(self.env_ids, torch.Tensor): raise TypeError("env_ids must be a torch.Tensor.") if ( diff --git a/embodichain/lab/sim/cfg/physics.py b/embodichain/lab/sim/cfg/physics.py index c04440966d..c75ee86548 100644 --- a/embodichain/lab/sim/cfg/physics.py +++ b/embodichain/lab/sim/cfg/physics.py @@ -133,6 +133,15 @@ class PhysicsBackendCfg: class DefaultPhysicsCfg(PhysicsBackendCfg): """Configuration selector for the Default physics backend.""" + direct_gpu_api: bool = True + """Use Direct GPU state access when dynamics run on CUDA. + + False retains GPU dynamics with ordinary state/contact reporting. The + pinned Direct GPU contact API cannot identify static actors, so consumers + requiring complete contact identities must explicitly select False. + This option does not select the physics device or change contact sampling. + """ + cache_material: bool = False """Reuse identical physics materials across objects and environment clones. @@ -168,6 +177,8 @@ class DefaultPhysicsCfg(PhysicsBackendCfg): def __post_init__(self) -> None: """Decode mapping input for the nested GPU-memory configuration.""" + if type(self.direct_gpu_api) is not bool: + raise TypeError("direct_gpu_api must be a bool.") if isinstance(self.gpu_memory, Mapping): self.gpu_memory = GPUMemoryCfg(**self.gpu_memory) if not isinstance(self.gpu_memory, GPUMemoryCfg): diff --git a/embodichain/lab/sim/motion/motion_generator.py b/embodichain/lab/sim/motion/motion_generator.py index 88bae56c6a..e4c0b7d87c 100644 --- a/embodichain/lab/sim/motion/motion_generator.py +++ b/embodichain/lab/sim/motion/motion_generator.py @@ -761,6 +761,13 @@ def generate( Raises: ValueError: If targets or options violate the motion contract. """ + # The optional expansion scope collects requests on the World owner. + # It is inert for ordinary callers and preserves native budget scopes. + from embodichain.lab.expansion._planning_batches import _try_motion + + handled, result = _try_motion(self, target_states, options, defer_recovery) + if handled: + return result if not target_states: raise ValueError("target_states must contain at least one waypoint.") options = MotionGenOptions() if options is None else options diff --git a/embodichain/lab/sim/motion/planners/base_planner.py b/embodichain/lab/sim/motion/planners/base_planner.py index 99ff6a1d79..a0daf18f50 100644 --- a/embodichain/lab/sim/motion/planners/base_planner.py +++ b/embodichain/lab/sim/motion/planners/base_planner.py @@ -184,8 +184,10 @@ def wrapper(self, *args, **kwargs): target_states = kwargs.get("target_states", args[0] if args else None) if target_states is not None and hasattr(self, "robot"): robot_num = getattr(self.robot, "num_instances", None) + selected = getattr(self, "_planning_env_ids", None) + expected = len(selected) if selected is not None else robot_num _check_batch_consistency( - target_states, expected_b=robot_num, robot_num_instances=robot_num + target_states, expected_b=expected, robot_num_instances=expected ) return func(self, *args, **kwargs) diff --git a/embodichain/lab/sim/motion/solvers/base_solver.py b/embodichain/lab/sim/motion/solvers/base_solver.py index d80e0979cc..54e5cbe6e0 100644 --- a/embodichain/lab/sim/motion/solvers/base_solver.py +++ b/embodichain/lab/sim/motion/solvers/base_solver.py @@ -697,9 +697,15 @@ def get_jacobian( # Ensure locations is a tensor if provided if locations is not None: + from pytorch_kinematics import Transform3d + locations = torch.as_tensor( locations, dtype=torch.float32, device=self.device ) + # PK 0.10 constructs a CPU Transform3d for raw offset tensors. + # Supply its declared device instead of mixing CPU homogeneous + # padding with CUDA offsets inside the dependency. + locations = Transform3d(pos=locations, dtype=qpos.dtype, device=qpos.device) # Compute the Jacobian using the kinematics chain J = self.pk_serial_chain.jacobian(th=qpos, locations=locations) diff --git a/embodichain/lab/sim/motion/solvers/opw_solver.py b/embodichain/lab/sim/motion/solvers/opw_solver.py index 7d06e3e561..53e38a1ae1 100644 --- a/embodichain/lab/sim/motion/solvers/opw_solver.py +++ b/embodichain/lab/sim/motion/solvers/opw_solver.py @@ -186,7 +186,8 @@ def get_fk_warp(self, qpos: torch.tensor, **kwargs) -> torch.tensor: qpos_batch = qpos n_sample = qpos_batch.shape[0] # Retimed trajectories retain float64; the OPW kernel consumes float32. - qpos_wp = wp.from_torch(qpos_batch.to(dtype=torch.float32).reshape(-1)) + qpos_batch = qpos_batch.to(device=self.device, dtype=torch.float32).contiguous() + qpos_wp = wp.from_torch(qpos_batch.reshape(-1)) xpos_wp = wp.zeros( n_sample * 16, dtype=float, device=standardize_device_string(self.device) ) diff --git a/embodichain/lab/sim/objects/articulation.py b/embodichain/lab/sim/objects/articulation.py index 221bb22ea7..eccc9f96f6 100644 --- a/embodichain/lab/sim/objects/articulation.py +++ b/embodichain/lab/sim/objects/articulation.py @@ -2027,8 +2027,8 @@ def set_state( ) if ( (root_pose is not None or qpos is not None) - and self.device.type == "cpu" and not self._data.is_newton_backend + and not self._world.get_physics_scene().is_direct_gpu() ): # Direct root/joint writes update native kinematics, but CPU link # transforms are published by World.update. Do not advance physics diff --git a/embodichain/lab/sim/physics/default.py b/embodichain/lab/sim/physics/default.py index 22d29c8d27..078c82f00c 100644 --- a/embodichain/lab/sim/physics/default.py +++ b/embodichain/lab/sim/physics/default.py @@ -44,7 +44,7 @@ def configure_world(self, world_config, sim_config: "SimulationManagerCfg") -> N world_config.speed_tolerance = cfg.speed_tolerance if self._manager.device.type == "cuda": world_config.enable_gpu_sim = True - world_config.direct_gpu_api = True + world_config.direct_gpu_api = cfg.direct_gpu_api def activate(self, sim_config: "SimulationManagerCfg") -> None: cfg = sim_config.physics_cfg diff --git a/embodichain/lab/sim/scene/feasibility/_collision_batches.py b/embodichain/lab/sim/scene/feasibility/_collision_batches.py new file mode 100644 index 0000000000..6ffe907fc9 --- /dev/null +++ b/embodichain/lab/sim/scene/feasibility/_collision_batches.py @@ -0,0 +1,335 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Batch the pinned Newton convex query without touching the live World.""" + +from __future__ import annotations + +import math + +import numpy as np + +__all__: list[str] = [] + + +class _CollisionBatches: + """Keep native shapes, precision, pair exemptions and halfspace supports. + + The query owns one numerical model containing independent replicas. It is + never stepped and creates no simulation World. Explicit pairs prohibit + cross-environment contacts; only the small per-row summaries are read back. + """ + + def __init__(self, checker, count, allowed, moving, all_pairs=False): + import newton + import warp as wp + + self.checker, self.count, self.wp = checker, count, wp + self.graph = None + self.queries = 0 + self.mask, self.planes, self.has_native = checker._mask( + allowed, moving, all_pairs + ) + self.locals = np.asarray([body.local_pose for body in checker.bodies]) + self.indices = [ + checker._frame_uids.index(body.frame_uid) for body in checker.bodies + ] + self.model = self.state = self.pipeline = self.contacts = None + self.meshes = [] + if not self.has_native: + return + builder = newton.ModelBuilder() + cfg = newton.ModelBuilder.ShapeConfig( + gap=checker.detection_gap_m / 2, + margin=0.0, + density=0.0, + collision_filter_parent=False, + ) + for index in checker._native: + body = checker.bodies[index] + owner = builder.add_body( + mass=1.0, + inertia=wp.mat33(np.eye(3, dtype=np.float32)), + is_kinematic=True, + ) + options = {"body": owner, "cfg": cfg} + if body.kind == "box": + shape = builder.add_shape_box( + hx=body.dimensions[0] / 2, + hy=body.dimensions[1] / 2, + hz=body.dimensions[2] / 2, + **options, + ) + elif body.kind == "sphere": + shape = builder.add_shape_sphere(radius=body.dimensions[0], **options) + elif body.kind in ("capsule", "cylinder"): + shape = getattr(builder, "add_shape_" + body.kind)( + radius=body.dimensions[0], + half_height=body.dimensions[1] / 2, + **options, + ) + else: + mesh = newton.Mesh( + np.asarray(body.vertices, dtype=np.float32), + np.asarray(body.triangles, dtype=np.int32).reshape(-1), + compute_inertia=False, + maxhullvert=len(body.vertices), + ) + self.meshes.append(mesh) + shape = builder.add_shape_convex_hull(mesh=mesh, **options) + if shape != owner: + raise RuntimeError("Collision query requires one shape per owned body") + batch = newton.ModelBuilder() + batch.replicate(builder, count) + self.model = batch.finalize(device=checker.device) + self.state = self.model.state() + width = len(checker._native) + pairs = [ + (checker._native_lookup[i], checker._native_lookup[j]) + for i, j in checker._pairs + if i in checker._native_lookup and j in checker._native_lookup + ] + explicit = np.asarray( + [ + (a + row * width, b + row * width) + for row in range(count) + for a, b in pairs + ], + dtype=np.int32, + ) + self.explicit = wp.array(explicit, dtype=wp.vec2i, device=checker.device) + self.capacity = checker._capacity * count + self.pipeline = newton.CollisionPipeline( + self.model, + broad_phase="explicit", + shape_pairs_filtered=self.explicit, + include_static_kinematic_pairs=True, + rigid_contact_max=self.capacity, + soft_contact_max=0, + ) + if self.pipeline.narrow_phase.global_contact_reducer is not None: + raise RuntimeError("Unsupported batched Newton narrow-phase route") + self.contacts = self.pipeline.contacts() + self.active = wp.array(self.mask, dtype=wp.int32, device=checker.device) + self.tolerance = wp.empty(count, dtype=float, device=checker.device) + self.output = wp.empty((count, 3), dtype=float, device=checker.device) + self.empty_count = wp.zeros(1, dtype=wp.int32, device=checker.device) + self.stream = ( + wp.Stream(checker.device) if checker.device.startswith("cuda") else None + ) + if self.stream is not None: + wp.synchronize_device(checker.device) + + def _run(self): + from embodichain.compute.geometry._warp.batch_contact_query import ( + contact_summary, + ) + + checker, wp = self.checker, self.wp + self.output.fill_(math.inf) + self.pipeline.collide(self.state, self.contacts) + phase, contacts = self.pipeline.narrow_phase, self.contacts + counters = [] + for count_name, storage_name in ( + ("gjk_candidate_pairs_count", "gjk_candidate_pairs"), + ("split_gjk_work_count", "split_gjk_work_items"), + ("split_manifold_work_count", "split_manifold_work_items"), + ): + value, storage = getattr(phase, count_name), getattr(phase, storage_name) + counters.extend( + ( + value if value is not None else self.empty_count, + storage.shape[0] if storage is not None else 0, + ) + ) + wp.launch( + contact_summary, + self.capacity, + inputs=[ + contacts.rigid_contact_count, + contacts.rigid_contact_shape0, + contacts.rigid_contact_shape1, + contacts.rigid_contact_point0, + contacts.rigid_contact_point1, + contacts.rigid_contact_normal, + contacts.rigid_contact_margin0, + contacts.rigid_contact_margin1, + self.model.shape_body, + self.state.body_q, + self.active, + len(checker._native), + self.count, + checker.clearance_m, + self.tolerance, + self.capacity, + self.pipeline.broad_phase_pair_count, + len(self.explicit), + *counters, + self.output, + ], + device=checker.device, + ) + + def check(self, frame_poses, rows): + from scipy.spatial.transform import Rotation + from embodichain.lab.sim.scene.feasibility import UnsupportedFeasibilityError + from embodichain.lab.sim.scene.feasibility.contracts import FeasibilityCheck + from embodichain.lab.sim.scene.feasibility.collision import _query_float32 + + checker = self.checker + if checker._closed: + raise RuntimeError("collision checker is closed") + frames = np.stack([frame_poses[uid] for uid in checker._frame_uids], axis=1) + if frames.shape != (self.count, len(checker._frame_uids), 4, 4): + raise ValueError("Collision frames must preserve every physical row") + if frames.dtype.kind not in "fiu" or not np.isfinite(frames).all(): + raise ValueError("arena_pose must contain finite real numbers") + frames = frames.astype(np.float64) + rotation = frames[..., :3, :3] + if ( + np.any(np.abs(frames[..., 3, :] - (0, 0, 0, 1)) > 1e-6) + or np.any( + np.abs(np.swapaxes(rotation, -1, -2) @ rotation - np.eye(3)) > 1e-6 + ) + or np.any(np.abs(np.linalg.det(rotation) - 1) > 1e-6) + ): + raise ValueError("arena_pose must be a proper rigid transform") + frames[..., 3, :] = (0, 0, 0, 1) + frames[..., :3, 3] -= frames[:, :1, :3, 3].copy() + poses = frames[:, self.indices] @ self.locals + if not np.isfinite(poses).all(): + raise UnsupportedFeasibilityError( + "Nonfinite composed physical collision pose" + ) + failures = {} + for i, j in self.planes: + plane, shape = (i, j) if checker.bodies[i].kind == "halfspace" else (j, i) + a, b = checker.bodies[plane], checker.bodies[shape] + normal = poses[:, plane, :3, :3] @ np.asarray(a.dimensions[:3]) + local = np.einsum("bji,bj->bi", poses[:, shape, :3, :3], normal) + if b.kind == "convex": + support = (local @ np.asarray(b.vertices).T).min(axis=-1) + elif b.kind == "sphere": + support = -b.dimensions[0] + elif b.kind == "capsule": + support = -b.dimensions[0] - np.abs(local[:, 2]) * b.dimensions[1] / 2 + elif b.kind == "cylinder": + support = ( + -b.dimensions[0] * np.linalg.norm(local[:, :2], axis=-1) + - np.abs(local[:, 2]) * b.dimensions[1] / 2 + ) + elif b.kind == "box": + support = -np.abs(local) @ (np.asarray(b.dimensions) / 2) + else: + raise UnsupportedFeasibilityError("Unsupported analytic halfspace pair") + distance = (normal * (poses[:, shape, :3, 3] - poses[:, plane, :3, 3])).sum( + -1 + ) + distance += support - a.dimensions[3] + if not np.isfinite(distance).all(): + raise UnsupportedFeasibilityError( + "Nonfinite analytic halfspace separation" + ) + for row in rows: + if distance[row] < checker.clearance_m - 1e-8 and row not in failures: + failures[row] = (i, j) + if self.has_native: + matrices = poses[:, checker._native] + relative = matrices[..., :3, 3] - matrices[:, :1, :3, 3] + rotations = Rotation.from_matrix(matrices[..., :3, :3].reshape(-1, 3, 3)) + quaternions = rotations.as_quat().reshape(self.count, -1, 4) + packed = _query_float32( + np.concatenate((relative, quaternions), axis=-1), + "Packed physical collision pose", + ) + recovered = rotations.as_matrix().reshape(matrices[..., :3, :3].shape) + loss = np.linalg.norm(recovered - matrices[..., :3, :3], axis=(-2, -1)).max( + -1 + ) + tolerance = ( + checker.numeric_tolerance_m + + 2 * (checker._geometry_error + loss * checker._geometry_radius) + + 32 + * np.finfo(np.float32).eps + * (np.abs(relative).max(axis=(-2, -1)) + checker._geometry_radius) + ) + if not np.isfinite(tolerance).all() or np.any( + tolerance >= checker.detection_gap_m - checker.clearance_m + ): + raise UnsupportedFeasibilityError( + "Candidate exceeds the contact-band precision budget" + ) + checker._max_effective_tolerance = max( + checker._max_effective_tolerance, float(tolerance.max()) + ) + # Solvers may temporarily borrow external CUDA streams. Own this + # query's stream through assignment, capture, launch and readback. + # Inputs have already crossed a measured CPU boundary above. + with self.wp.ScopedStream(self.stream, sync_enter=False): + self.state.body_q.assign(packed.reshape(-1, 7)) + self.tolerance.assign(tolerance.astype(np.float32)) + if self.graph is None: + self._run() + if self.stream is not None and checker._use_cuda_graph: + self.wp.synchronize_stream(self.stream) + with self.wp.ScopedCapture(stream=self.stream) as capture: + self._run() + self.graph = capture.graph + self.wp.capture_launch(self.graph, stream=self.stream) + else: + self.wp.capture_launch(self.graph, stream=self.stream) + summary = self.output.numpy() + for row in rows: + if ( + math.isfinite(summary[row, 2]) + or math.isnan(summary[row, 0]) + or summary[row, 0] == -math.inf + ): + raise UnsupportedFeasibilityError( + "Batched Newton query overflowed or returned invalid evidence" + ) + if row not in failures and math.isfinite(summary[row, 1]): + a, b = divmod(int(summary[row, 1]), len(checker._native)) + failures[row] = (checker._native[a], checker._native[b]) + self.queries += 1 + result = [] + for row in rows: + if row in failures: + i, j = failures[row] + pair = checker.bodies[i].collision_id, checker.bodies[j].collision_id + report = FeasibilityCheck( + "collision", + "failed", + f"{pair[0]} / {pair[1]}: forbidden collision or insufficient clearance", + ) + else: + pair = None + report = FeasibilityCheck( + "collision", + "passed", + "Discrete Newton convex/physical-halfspace query; batched physical rows", + ) + result.append((row, report, pair)) + return result + + def close(self): + with self.wp.ScopedStream(getattr(self, "stream", None), sync_enter=False): + self.graph = self.contacts = self.pipeline = self.state = self.model = None + for name in ("explicit", "active", "tolerance", "output", "empty_count"): + setattr(self, name, None) + self.meshes.clear() + self.stream = None diff --git a/embodichain/lab/sim/scene/feasibility/collision.py b/embodichain/lab/sim/scene/feasibility/collision.py index 38159c4f20..f45478e3e0 100644 --- a/embodichain/lab/sim/scene/feasibility/collision.py +++ b/embodichain/lab/sim/scene/feasibility/collision.py @@ -296,6 +296,8 @@ def __init__( raise UnsupportedFeasibilityError("Physical collision pair budget exceeded") self._capacity = min(max_contacts, requested_capacity) self._mask_cache = OrderedDict() + self._batch_queries = OrderedDict() + self.last_batch_pairs: tuple[tuple[str, str] | None, ...] = () self._model = self._state = self._pipeline = self._contacts = None self._graph = self._active = self._output = self._empty_count = ( self._explicit @@ -703,6 +705,86 @@ def check( "Discrete Newton convex/physical-halfspace query; clearance is capped by the detection band", ), (0.0 if math.isinf(clearance) else min(self.detection_gap_m, clearance)) + def check_batch( + self, + frame_poses: Mapping[str, object], + *, + allowed_contacts: Sequence[tuple[str, str]] = (), + moving_objects: Sequence[str] = (), + all_pairs: bool = False, + env_ids: Sequence[int] | None = None, + ) -> tuple[FeasibilityCheck, ...]: + """Check independent measured rows with one bounded numerical query. + + Args: + frame_poses: Every declared frame with arena poses ``(B, 4, 4)``. + Tensor inputs are copied to the query-owned CPU boundary. + allowed_contacts: Shared explicit contact exemptions for these rows. + moving_objects: Dynamic frames requiring environment checks. + all_pairs: Also inspect static layout pairs. + env_ids: Ordered selected rows; None selects all B rows. + + Returns: + Discrete checks in selected-row order. ``last_batch_pairs`` records + each failure's physical IDs. This API does not report a distance or + overwrite the scalar check's clearance interval. It never advances + or changes the live simulation. Geometry, precision and saturation + rejection follow :meth:`check`. + """ + if self._closed: + raise RuntimeError("collision checker is closed") + from ._collision_batches import _CollisionBatches + + self.last_batch_pairs = () + frames = {} + size = None + for uid in self._frame_uids: + if uid not in frame_poses: + raise UnsupportedFeasibilityError( + f"Missing physical collision frame {uid}" + ) + value = frame_poses[uid] + if hasattr(value, "detach"): + value = value.detach().cpu().numpy() + array = np.asarray(value) + if array.ndim != 3 or array.shape[1:] != (4, 4) or not array.shape[0]: + raise ValueError("batched arena poses must have shape (B, 4, 4), B > 0") + if size is not None and size != len(array): + raise ValueError("batched collision frames must share their row count") + size = len(array) + frames[uid] = array + rows = tuple(range(size)) if env_ids is None else tuple(env_ids) + if ( + not rows + or len(set(rows)) != len(rows) + or any(type(row) is not int or not 0 <= row < size for row in rows) + ): + raise ValueError("env_ids must select unique physical rows") + if type(all_pairs) is not bool: + raise TypeError("all_pairs must be a bool") + # Resolve permissions with the same native validation before caching. + allowed = frozenset(self._expand_pairs(allowed_contacts)) + self._mask(allowed_contacts, moving_objects, all_pairs) + key = size, allowed, frozenset(moving_objects), all_pairs + query = self._batch_queries.get(key) + if query is None: + if size * self._capacity > 1048576: + raise UnsupportedFeasibilityError( + "Batched collision contact budget exceeded" + ) + query = _CollisionBatches( + self, size, allowed_contacts, moving_objects, all_pairs + ) + self._batch_queries[key] = query + while len(self._batch_queries) > 2: + _, old = self._batch_queries.popitem(last=False) + old.close() + else: + self._batch_queries.move_to_end(key) + result = query.check(frames, rows) + self.last_batch_pairs = tuple(pair for _, _, pair in result) + return tuple(report for _, report, _ in result) + def _failure(self, i: int, j: int) -> FeasibilityCheck: self.last_pair = self.bodies[i].collision_id, self.bodies[j].collision_id return FeasibilityCheck( @@ -713,6 +795,29 @@ def _failure(self, i: int, j: int) -> FeasibilityCheck: def close(self) -> None: """Release owned query arrays/graphs; repeated cleanup is harmless.""" + stream = next( + ( + query.stream + for query in self._batch_queries.values() + if getattr(query, "stream", None) is not None + ), + None, + ) + if stream is not None: + import warp as wp + + # A robot solver may have borrowed a temporary Warp stream. Keep + # query-owned arrays on a live stream through their final release. + with wp.ScopedStream(stream, sync_enter=False): + self._close_arrays() + else: + self._close_arrays() + + def _close_arrays(self) -> None: + for query in self._batch_queries.values(): + query.close() + self._batch_queries.clear() + self.last_batch_pairs = () self._graph = self._pipeline = self._contacts = self._state = self._model = None self._active = self._output = self._empty_count = None self._tolerance = None diff --git a/embodichain/lab/sim/sensors/__init__.py b/embodichain/lab/sim/sensors/__init__.py index 467fce2f80..6f87bb669b 100644 --- a/embodichain/lab/sim/sensors/__init__.py +++ b/embodichain/lab/sim/sensors/__init__.py @@ -19,6 +19,8 @@ ``Camera``, ``StereoCamera``, and ``ContactSensor`` all derive from ``BaseSensor`` and expose batched ``TensorDict`` data buffers. """ +from __future__ import annotations + from .base_sensor import BaseSensor, SensorCfg from .camera import Camera, CameraCfg from .stereo import StereoCamera, StereoCameraCfg @@ -26,4 +28,5 @@ ContactSensor, ContactSensorCfg, ArticulationContactFilterCfg, + ContactPermissionChecker, ) diff --git a/embodichain/lab/sim/sensors/contact/__init__.py b/embodichain/lab/sim/sensors/contact/__init__.py index 80a6e493ce..ed6121e479 100644 --- a/embodichain/lab/sim/sensors/contact/__init__.py +++ b/embodichain/lab/sim/sensors/contact/__init__.py @@ -48,10 +48,12 @@ from .history import ( ContactHistory, ) +from .permissions import ContactPermissionChecker __all__ = [ "ArticulationContactFilterCfg", "ContactSensor", + "ContactPermissionChecker", "ContactSensorCfg", "ContactSamplingObserver", "CONTACT_ACTOR_IDS", diff --git a/embodichain/lab/sim/sensors/contact/permissions.py b/embodichain/lab/sim/sensors/contact/permissions.py new file mode 100644 index 0000000000..831dc8f3b1 --- /dev/null +++ b/embodichain/lab/sim/sensors/contact/permissions.py @@ -0,0 +1,204 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Device-side permission checks over complete native contact samples.""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import TYPE_CHECKING +import torch + +if TYPE_CHECKING: + from .sensor import ContactSensor + +__all__ = ["ContactPermissionChecker"] + + +class ContactPermissionChecker: + """Classify every valid measured contact without constructing Python pairs. + + Args: + sensor: Initialized native sensor with applied-impulse validity flags. + actor_frames: Explicit actor ID to frame name mapping for every row. + A global static actor may appear in several rows with the same name. + allowed_contacts: Structural and task-owned unordered frame exemptions. + moving_frames: Robot and dynamic frames requiring permission checks. + + This checker does not infer adjacency, change filters, step physics or select + a sampling frequency. A host requiring substep validation must invoke it at + every original physical sample. Unknown actors and unavailable impulses fail + closed; cumulative native/scatter loss invalidates every row conservatively. + """ + + def __init__( + self, + sensor: ContactSensor, + actor_frames: Sequence[Mapping[int, str]], + *, + allowed_contacts: Sequence[tuple[str, str]], + moving_frames: Sequence[str], + ) -> None: + self.sensor = sensor + self.device = torch.device(sensor.device) + self.rows = sensor.num_instances + if len(actor_frames) != self.rows or any(not row for row in actor_frames): + raise ValueError("actor_frames must declare every nonempty sensor row") + if any( + type(actor) is not int + or actor < 0 + or type(name) is not str + or not name.strip() + for row in actor_frames + for actor, name in row.items() + ): + raise ValueError( + "contact actors require nonnegative IDs and explicit frame names" + ) + names = sorted({name for row in actor_frames for name in row.values()}) + if any( + len(pair) != 2 or any(name not in names for name in pair) + for pair in allowed_contacts + ): + raise ValueError("contact permissions reference an absent frame") + if set(moving_frames) - set(names): + raise ValueError("moving_frames references an absent contact frame") + codes = {name: index for index, name in enumerate(names)} + actors = {} + for row, frames in enumerate(actor_frames): + for actor, name in frames.items(): + code, rows = actors.setdefault(actor, (codes[name], set())) + if code != codes[name]: + raise ValueError("contact actor has ambiguous frame identities") + rows.add(row) + actors = sorted(actors.items()) + allowed = {frozenset(pair) for pair in allowed_contacts} + self._actors = torch.tensor( + [actor for actor, _ in actors], dtype=torch.int32, device=self.device + ) + self._memberships = torch.tensor( + [ + [row in members for row in range(self.rows)] + for _, (_, members) in actors + ], + dtype=torch.bool, + device=self.device, + ) + self._codes = torch.tensor( + [code for _, (code, _) in actors], dtype=torch.long, device=self.device + ) + self._moving = torch.tensor( + [name in moving_frames for name in names], + dtype=torch.bool, + device=self.device, + ) + self._allowed = torch.tensor( + [[frozenset((a, b)) in allowed for b in names] for a in names], + dtype=torch.bool, + device=self.device, + ) + self._first = torch.empty(self.rows, dtype=torch.int32, device=self.device) + self._drop = torch.zeros(1, dtype=torch.int32, device=self.device) + self._output = torch.empty( + (self.rows, 3), dtype=torch.int32, device=self.device + ) + self._ready = torch.cuda.Event() if self.device.type == "cuda" else None + if self._ready is not None: + self._ready.record(torch.cuda.current_stream(self.device)) + self._actors_token = id(sensor._query.actors) + + def check(self) -> torch.Tensor: + """Return owned per-row ``(reason, actor0, actor1)`` integer summaries. + + Returns: + Tensor ``(B, 3)`` on the sensor device. Reason zero passes; one means + unavailable applied impulse, two unknown/cross-row actor, three + forbidden moving contact, four dropped evidence. The earliest bad + buffer slot supplies actor IDs. No valid contact is subsampled. + + Raises: + RuntimeError: Sensor topology changed after permission binding. + """ + import warp as wp + from embodichain.compute.geometry._warp.contact_permissions import ( + classify_contacts, + contact_failures, + ) + + if self._ready is not None: + torch.cuda.current_stream(self.device).wait_event(self._ready) + data = self.sensor.get_data() + if id(self.sensor._query.actors) != self._actors_token: + raise RuntimeError( + "contact topology changed; bind a new permission checker" + ) + pairs = data["user_ids"] + self._first.fill_(pairs.shape[1] * 8) + self._drop.zero_() + # Use the current Torch stream on every call, rather than assuming that + # the stream used at construction is still the caller's producer. + stream = ( + wp.stream_from_torch(torch.cuda.current_stream(self.device)) + if self.device.type == "cuda" + else None + ) + wp.launch( + classify_contacts, + pairs.shape[:2], + inputs=[ + wp.from_torch(pairs), + wp.from_torch(data["is_valid"]), + wp.from_torch(data["impulse_valid"]), + wp.from_torch(self._actors), + wp.from_torch(self._memberships), + wp.from_torch(self._codes), + wp.from_torch(self._moving), + wp.from_torch(self._allowed), + wp.from_torch(self.sensor.dropped_contacts_mask), + wp.from_torch(self._first), + wp.from_torch(self._drop), + ], + device=str(self.device), + stream=stream, + ) + wp.launch( + contact_failures, + self.rows, + inputs=[ + wp.from_torch(pairs), + wp.from_torch(self._first), + wp.from_torch(self._drop), + wp.from_torch(self._output), + ], + device=str(self.device), + stream=stream, + ) + result = self._output.clone() + if self._ready is not None: + current = torch.cuda.current_stream(self.device) + self._ready.record(current) + for value in ( + self._actors, + self._memberships, + self._codes, + self._moving, + self._allowed, + self._first, + self._drop, + self._output, + ): + value.record_stream(current) + return result diff --git a/embodichain/lab/task_program/integrations/_measured_batch.py b/embodichain/lab/task_program/integrations/_measured_batch.py new file mode 100644 index 0000000000..a63057a10f --- /dev/null +++ b/embodichain/lab/task_program/integrations/_measured_batch.py @@ -0,0 +1,133 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Batch measured predicate inputs while retaining native event state machines.""" + +from __future__ import annotations + +from contextlib import contextmanager +import json + +import numpy as np + +__all__: list[str] = [] + + +class _MeasuredChecks: + """Read one packed physical boundary instead of synchronizing per predicate. + + Native monitors still own ordered events, consecutive counts, receipts and + terminal reports. Only their predicate arithmetic is shared across rows; + unsupported fast paths continue through the original native predicate. + The cache exists solely inside an explicit measured-boundary scope. + """ + + def __init__(self, env, configuration, monitors): + self.env, self.monitors = env, monitors + conditions = [*configuration["initial_checks"], *configuration["final_checks"]] + for event in configuration["events"]: + conditions.extend(event["conditions"]) + self.conditions = {self.key(c): c for c in conditions} + self.entities = tuple( + dict.fromkeys( + c[name] for c in conditions for name in ("entity", "other") if name in c + ) + ) + self.values = None + self.reads = 0 + + @staticmethod + def key(condition): + return json.dumps(condition, sort_keys=True, separators=(",", ":")) + + @contextmanager + def boundary(self): + import torch + + env = self.env + parts = [] + for uid in self.entities: + obj = env.sim.get_rigid_object(uid) + if obj is None: + raise ValueError("Predicate entity is absent from the physical scene") + parts.append( + torch.cat( + ( + obj.get_local_pose()[:, :3], + obj.body_state[:, 7:10].norm(dim=-1, keepdim=True), + obj.body_state[:, 10:13].norm(dim=-1, keepdim=True), + ), + dim=-1, + ) + ) + parts.append(env.robot.get_qpos()) + # One D2H boundary, independent of the number of predicates and rows. + packed = torch.cat(parts, dim=-1).detach().cpu().numpy() + self.reads += 1 + states = { + uid: packed[:, index * 5 : (index + 1) * 5] + for index, uid in enumerate(self.entities) + } + joints = packed[:, len(self.entities) * 5 :] + values = {} + for key, condition in self.conditions.items(): + kind = condition["kind"] + if kind == "joint_range": + index = env.robot.joint_names.index(condition["joint"]) + value = joints[:, index].astype(np.float64) + result = (value >= condition["lower"]) & (value <= condition["upper"]) + elif kind in ("pose_near", "lifted", "speed_below", "axis_relation"): + state = states[condition["entity"]] + position = state[:, :3].astype(np.float64) + if kind == "pose_near": + result = ( + np.linalg.norm(position - condition["position"], axis=-1) + <= condition["tolerance_m"] + ) + elif kind == "lifted": + initial = np.full(env.num_envs, np.nan) + for row, monitor in self.monitors.items(): + initial[row] = monitor.initial_heights.get( + condition["entity"], np.nan + ) + result = position[:, 2] - initial >= condition["height_m"] + elif kind == "axis_relation": + axis = condition["axis"] + delta = position[:, axis] - states[condition["other"]][:, axis] + result = (delta >= condition["lower"]) & ( + delta <= condition["upper"] + ) + else: + # Native scalar comparisons convert the float32 norms to + # Python floats before comparing authored thresholds. + result = ( + state[:, 3].astype(np.float64) <= condition["linear_m_s"] + ) & (state[:, 4].astype(np.float64) <= condition["angular_rad_s"]) + else: + continue + values[key] = ~result if condition.get("negate", False) else result + previous = { + row: getattr(monitor, "_batch_predicates", None) + for row, monitor in self.monitors.items() + } + for monitor in self.monitors.values(): + monitor._batch_predicates = values + try: + yield + finally: + for row, monitor in self.monitors.items(): + monitor._batch_predicates = previous[row] diff --git a/embodichain/lab/task_program/integrations/feasibility.py b/embodichain/lab/task_program/integrations/feasibility.py index f8887fe207..8f688a15da 100644 --- a/embodichain/lab/task_program/integrations/feasibility.py +++ b/embodichain/lab/task_program/integrations/feasibility.py @@ -176,6 +176,13 @@ def predicate(self, env: Any, condition: Mapping[str, object]) -> bool: Returns: Physical truth value; unknown entities/joints are configuration errors. """ + cached = getattr(self, "_batch_predicates", None) + if cached is not None: + from ._measured_batch import _MeasuredChecks + + key = _MeasuredChecks.key(condition) + if key in cached: + return bool(cached[key][self.env_id]) kind = condition["kind"] if kind == "joint_range": index = env.robot.joint_names.index(condition["joint"]) @@ -274,6 +281,47 @@ def predicate(self, env: Any, condition: Mapping[str, object]) -> bool: ) return bool(not passed if condition.get("negate", False) else passed) + @staticmethod + def batch_scope( + env: Any, + monitors: Sequence[MeasuredTaskMonitor], + *, + extra_conditions: Sequence[Mapping[str, object]] = (), + ) -> object: + """Share one measured numeric boundary across independent event monitors. + + Args: + env: Live environment or complete measured-state facade. + monitors: Distinct physical-row monitors, already reset for this episode. + extra_conditions: Additional validated initial checks to read in this scope. + + Returns: + Context manager. Inside it, predicate arithmetic uses one packed + readback; ordered events, counters and reports still belong to each + native monitor. Unsupported fast paths keep the scalar predicate. + No cached physical values survive the scope. + """ + from ._measured_batch import _MeasuredChecks + + selected = {monitor.env_id: monitor for monitor in monitors} + if not selected or len(selected) != len(monitors): + raise ValueError( + "batch_scope requires unique nonempty physical-row monitors" + ) + if any(not 0 <= row < env.num_envs for row in selected): + raise ValueError("monitor row is outside the measured environment") + first = next(iter(selected.values())) + conditions = [first._validate(c) for c in extra_conditions] + final, events = [], [] + for monitor in selected.values(): + final.extend(monitor.final_checks) + events.extend({"conditions": values} for _, values, _ in monitor.events) + return _MeasuredChecks( + env, + {"initial_checks": conditions, "final_checks": final, "events": events}, + selected, + ).boundary() + def observe(self, env: Any, action: Any) -> None: """Record consecutive event predicates at actual control boundaries.""" self._steps += 1 diff --git a/embodichain/lab/task_program/integrations/simulation/policies.py b/embodichain/lab/task_program/integrations/simulation/policies.py index 339d6185ba..6d23062c36 100644 --- a/embodichain/lab/task_program/integrations/simulation/policies.py +++ b/embodichain/lab/task_program/integrations/simulation/policies.py @@ -727,6 +727,7 @@ def _hold_actions(self, policy, *, segment, active_mask): context, attached, previous_target = self._hold_observer( cfg.object, accepted ) + attached = attached.to(device=active_mask.device) self.validate_observation_scope(clock) if clock.step_index != start + tick: raise ValueError("Hold observation changed its execution clock.") @@ -752,6 +753,7 @@ def _hold_actions(self, policy, *, segment, active_mask): name="hold.at", ) ) + target = target.to(device=active_mask.device) pose = context.scene.entities[cfg.object].pose.to(target) if pose.ndim == 2: pose = pose.unsqueeze(0).expand(active_mask.numel(), -1, -1) @@ -1883,7 +1885,14 @@ def _measure_pose_delta_settle_target( target.native_entity, entity_id=target.canonical_id, ) - pose = pose.index_select(0, row_indices.to(pose.device)) + # _read_pose already selects this port's bound physical rows. Convert + # the requested World IDs to local offsets instead of selecting twice + # with the original IDs (for example row 7 in a B=1 policy port). + matches = row_indices[:, None] == self._row_indices[None, :] + if not bool((matches.sum(dim=1) == 1).all()): + raise ValueError("Pose-delta settling requested an unbound physical row") + local = matches.long().argmax(dim=1).to(pose.device) + pose = pose.index_select(0, local) row_count = row_indices.numel() if previous_pose is None: speed = torch.full( diff --git a/embodichain/utils/_owned_json.py b/embodichain/utils/_owned_json.py new file mode 100644 index 0000000000..851a39a93d --- /dev/null +++ b/embodichain/utils/_owned_json.py @@ -0,0 +1,115 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Owned immutable finite JSON nodes and defensive mutable projections.""" + +from __future__ import annotations + +from collections.abc import Mapping +import json +import math +from types import MappingProxyType + +__all__: list[str] = [] + +_ATOMS = frozenset((str, bool, int, type(None))) + + +class _FrozenTuple(tuple): + __slots__ = () + + +class _FrozenMap(Mapping): + """Own validated immutable children; expose no mutable backing dictionary.""" + + __slots__ = ("_data", "_strict", "_encoded") + + def __init__(self, values, strict): + object.__setattr__(self, "_data", MappingProxyType(values)) + object.__setattr__(self, "_strict", strict) + object.__setattr__(self, "_encoded", None) + + def __setattr__(self, name, value): + raise TypeError("Frozen metadata cannot be modified") + + def __getitem__(self, key): + return self._data[key] + + def __iter__(self): + return iter(self._data) + + def __len__(self): + return len(self._data) + + def __deepcopy__(self, memo): + return self + + def __repr__(self): + return repr(self._data) + + def __str__(self): + return str(self._data) + + def mutable_copy(self): + if self._encoded is None: + encoded = json.dumps( + self._data, + default=dict, + ensure_ascii=False, + allow_nan=False, + ) + object.__setattr__(self, "_encoded", encoded) + # Every call returns new mutable containers. No caller can modify the + # validated immutable source through the returned tree. + return json.loads(self._encoded) + + +def _key_valid(key): + return type(key) is str and bool(key) and key == key.strip() + + +def _strict_keys(value): + if type(value) is _FrozenMap: + return value._strict + if type(value) is _FrozenTuple: + return all(_strict_keys(item) for item in value) + return True + + +def freeze_metadata(value: object) -> object: + kind = type(value) + if kind in _ATOMS or kind in (_FrozenMap, _FrozenTuple): + return value + if kind is float: + if not math.isfinite(value): + raise ValueError("metadata must contain only finite JSON values") + return value + if isinstance(value, (list, tuple)): + return _FrozenTuple(freeze_metadata(item) for item in value) + if isinstance(value, Mapping): + result = {} + strict = True + for key, item in value.items(): + # The expansion contract accepts whitespace around nonempty keys; + # the Gym JSON-copy contract is stricter. Retain both behaviours. + if not isinstance(key, str) or not key.strip(): + raise ValueError("metadata key must be a nonempty string") + owned = freeze_metadata(item) + result[key] = owned + strict &= _key_valid(key) and _strict_keys(owned) + return _FrozenMap(result, strict) + raise ValueError("metadata must contain only finite JSON values") diff --git a/pyproject.toml b/pyproject.toml index b20997c6df..8c6882821a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,7 @@ dependencies = [ "ortools", "prettytable", "psutil>=5.9", + "greenlet>=3.2,<4", "black==26.10.1", "fvcore", "h5py", diff --git a/tests/lab/expansion/test_export.py b/tests/lab/expansion/test_export.py index ce9b2e5046..eddf3b32e1 100644 --- a/tests/lab/expansion/test_export.py +++ b/tests/lab/expansion/test_export.py @@ -29,6 +29,61 @@ from embodichain.lab.expansion import export as module +def test_per_episode_export_uses_real_sdk_and_preserves_portable_boundaries(tmp_path): + from embodichain.lab.expansion import ( + export_expansion_episodes, + load_expansion_episode, + ) + from lerobot.datasets.lerobot_dataset import LeRobotDataset + + sink = ArtifactEpisodeSink(tmp_path) + for ordinal in range(2): + parent = episode() + parent = replace( + parent, + identity=replace( + parent.identity, + candidate_id=f"candidate-{ordinal}", + geometry_family_id=f"family-{ordinal}", + ), + episode_id=f"episode-{ordinal}", + commit_id=f"commit-{ordinal}", + observations={ + "joint_positions": torch.cat( + ( + parent.observations["joint_positions"], + parent.observations["joint_positions"] + 0.03, + ), + dim=1, + ), + "joint_velocities": torch.zeros(3, 2), + "joint_efforts": torch.zeros(3, 2), + }, + actions=torch.cat((parent.actions, parent.actions + 0.03), dim=1), + metadata={ + "expert_action_spec": { + "joint_names": ["joint_0", "joint_1"], + "joint_command_mode": "position", + "step_dt": 0.1, + }, + "source_episode_uuids": ["source"], + }, + ) + sink.submit(parent, submission_id=0) + result = export_expansion_episodes(tmp_path) + assert result["episodes"] == 2 + assert export_expansion_episodes(tmp_path) == result + for row in result["datasets"]: + path = Path(result["directory"]) / row["dataset_path"] + data = LeRobotDataset(path.name, root=path, download_videos=False) + assert data.num_episodes == 1 and len(data) == 2 + receipts = ArtifactEpisodeSink(path / "embodichain_artifacts").inspect() + assert len(receipts) == 1 and receipts[0].episode_id == row["episode_id"] + saved = load_expansion_episode(receipts[0].storage_id) + assert len(saved.timestamps) == len(saved.actions) + 1 == 3 + torch.testing.assert_close(data[0]["action"], saved.actions[0], rtol=0, atol=0) + + def test_export_includes_visual_children_without_new_physical_receipts( tmp_path, monkeypatch ): diff --git a/tests/lab/expansion/test_persistence.py b/tests/lab/expansion/test_persistence.py index 074f02cfa6..81bcd6d803 100644 --- a/tests/lab/expansion/test_persistence.py +++ b/tests/lab/expansion/test_persistence.py @@ -30,7 +30,10 @@ ValidationCheck, ValidationResult, ) -from embodichain.lab.expansion.persistence import ArtifactEpisodeSink +from embodichain.lab.expansion.persistence import ( + ArtifactEpisodeSink, + load_expansion_episode, +) from embodichain.data_pipeline.recording.media import MediaSpool @@ -63,6 +66,34 @@ def test_staging_has_no_credit_and_recovery_never_reruns_physics(tmp_path): assert len(sink.inspect()) == 1 +def test_verified_episode_reads_own_tensors_and_invalidate_changed_bytes(tmp_path): + sink = ArtifactEpisodeSink(tmp_path) + data = replace(episode(), metadata={"nested": {"values": [1, 2]}}) + receipt = sink.submit(data, submission_id=0) + first = load_expansion_episode(receipt.storage_id) + second = load_expansion_episode(receipt.storage_id) + first.actions.fill_(99) + first.observations["joint_positions"].fill_(88) + third = load_expansion_episode(receipt.storage_id) + torch.testing.assert_close(second.actions, data.actions, rtol=0, atol=0) + torch.testing.assert_close(third.actions, data.actions, rtol=0, atol=0) + torch.testing.assert_close( + third.observations["joint_positions"], + data.observations["joint_positions"], + rtol=0, + atol=0, + ) + from embodichain.lab.gym.envs._json import json_safe_copy + + projected = json_safe_copy(third.metadata, field_name="metadata") + projected["nested"]["values"][0] = 55 + assert third.metadata["nested"]["values"][0] == 1 + path = Path(receipt.storage_id) + path.write_bytes(b"invalid replaced evidence") + with pytest.raises((ValueError, OSError)): + load_expansion_episode(path) + + def test_media_alignment_is_required_before_receipt(tmp_path): sink = ArtifactEpisodeSink(tmp_path) data = episode() diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py new file mode 100644 index 0000000000..516f540eb1 --- /dev/null +++ b/tests/lab/expansion/test_workloads_sim.py @@ -0,0 +1,364 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +import pytest + + +def _probe(output: str) -> None: + import hashlib + import json + import torch + from embodichain.lab.expansion import ( + ArtifactEpisodeSink, + ExpansionEngine, + ExpansionJobCfg, + ExpansionSession, + ExpansionSessionCfg, + EpisodeCandidate, + PreparedEpisodeWorkItem, + ExpansionWorkloadCfg, + WorkloadExecutionCfg, + WorkloadProgramExecutor, + load_expansion_episode, + ) + from embodichain.lab.expansion.contracts import ( + ExpertEpisode, + SceneCase, + ValidationCheck, + ValidationResult, + ) + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.sim import SimulationManager + from embodichain.utils.utility import load_config + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + path = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml" + ) + discover_task_packages() + execute_init_hooks() + cfg = config_to_cfg(load_config(path), source_path=path) + cfg.num_envs = cfg.sim_cfg.num_envs = 4 + cfg.sim_cfg.device = "cpu" + cfg.sim_cfg.headless = True + cfg.sim_cfg.render_cfg.renderer = "no-render" + cfg.sensor, cfg.enable_sensor, cfg.dataset = [], False, None + cfg.init_rollout_buffer = cfg.record_trajectory = False + cfg.task_program.program.count = 1 + env = None + try: + env = REGISTERED_ENVS[load_config(path)["id"]].make(cfg=cfg) + env.reset(seed=0) + robot = env.robot + program = env.compile_task_program(cfg.task_program) + from embodichain.lab.sim.motion.motion_generator import ( + MotionGenerator, + MotionGenCfg, + MotionGenOptions, + ) + from embodichain.lab.sim.motion.planners.trapezoidal_planner import ( + TrapezoidalPlannerCfg, + ) + from embodichain.lab.sim.motion.planners.utils import PlanState + from embodichain.lab.expansion._planning_batches import batched_planning + + requests = {} + for row in (0, 3): + generator = MotionGenerator( + MotionGenCfg( + planner_cfg=TrapezoidalPlannerCfg( + robot_uid=robot.uid, sim_instance_id=env.sim.instance_id + ) + ), + env_ids=(row,), + ) + start = robot.get_qpos(name="arm")[row : row + 1].clone() + goal = start.clone() + goal[:, 0] += 0.01 * (row + 1) + states = [PlanState.from_qpos(goal)] + options = MotionGenOptions( + strategy="ik_interp", + interpolation_mode="fixed_grid", + ik_seed_mode="sequential", + sample_count=12, + interpolation_dt=0.04, + start_qpos=start, + control_part="arm", + ) + requests[row] = (generator, states, options) + reference = { + row: generator.generate(states, options) + for row, (generator, states, options) in requests.items() + } + + class Request: + def __init__(self, row): + self.row = row + + def next(self): + generator, states, options = requests[self.row] + return generator.generate(states, options) + + before = env.sim.physics_step_index + with batched_planning(robot, 0) as planning: + planned = planning.gather({row: Request(row) for row in requests}) + assert ( + planning.stats["motion_calls"] == 1 + and planning.stats["max_motion_group"] == 2 + ), planning.stats + for row, original in reference.items(): + torch.testing.assert_close( + planned[row].success, original.success, rtol=0, atol=0 + ) + torch.testing.assert_close( + planned[row].positions, original.positions, rtol=0, atol=1e-6 + ) + torch.testing.assert_close(planned[row].dt, original.dt, rtol=0, atol=0) + assert env.sim.physics_step_index == before + from embodichain.lab.expansion.collision import _MeasuredCollision + + checks = _MeasuredCollision( + env, + str(root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml"), + Path(output) / "checks", + ) + + class Host: + capacity = env.num_envs + + def preflight(self, items): + assert all(item.compatibility_key == "one-world" for item in items) + + def validate_plan(self, item): + assert torch.isfinite(robot.get_qpos()[item.env_id]).all() + return ValidationResult( + ( + ValidationCheck( + "initial_geometry", + "passed" if checks.initial[item.env_id] else "failed", + ), + ) + ) + + sink = ArtifactEpisodeSink(output) + session = ExpansionSession( + ExpansionSessionCfg.from_mapping( + { + "collection": { + "target_committed_episodes": 4, + "max_proposals": 8, + "max_rollout_attempts": 8, + }, + "execution": {"ready_high_watermark": 4, "ready_low_watermark": 0}, + "persistence": { + "pending_episode_limit": 4, + "pending_max_bytes": 32 * 1024 * 1024, + }, + } + ) + ) + engine = ExpansionEngine( + ExpansionJobCfg(batch_size=4), session=session, host=Host(), sink=sink + ) + + class Source: + def __init__(self): + self.buffers, self.assignments, self.adapters = {}, {}, [] + self.finished = [] + + def prepare(self, assignments): + assert len(SimulationManager._instances) == 1 + + def activate(self, assignment, observation): + row = assignment.env_id + checks.prepare(env_ids=(row,)) + from copy import deepcopy + + self.scalar_monitors = getattr(self, "scalar_monitors", {}) + self.scalar_monitors[row] = deepcopy(checks.monitors[row]) + key = f"{assignment.workload_id}-{assignment.ordinal}" + state = robot.get_qpos()[row].detach().cpu().clone() + initial = hashlib.sha256(state.numpy().tobytes()).hexdigest() + session.register_case( + SceneCase(key, initial, "scene", program.program_id, robot.uid), + robot.get_qpos_limits()[row].cpu(), + joint_names=tuple(robot.joint_names), + ) + identity, _ = session.propose( + key, + initial, + source_id=program.program_id, + source_revision="v1", + template_id=key, + operator_id="episode", + ) + item = PreparedEpisodeWorkItem( + EpisodeCandidate(identity, "{}"), "one-world", row + ) + native = engine.admit_row(item) + assert native is not None + self.assignments[row] = native + self.buffers[row] = {"actions": [], "states": [state]} + adapter = env.task_program_adapter.for_env_ids((row,)) + self.adapters.append(adapter) + return adapter.create_bridge(program, isolate_policy_sessions=True) + + def started(self, assignment, boundary): + engine.mark_row_started(self.assignments[assignment.env_id]) + + def observe(self, assignments, action, observation): + rejected = [] + checks.sample(tuple(a.env_id for a in assignments), action) + for assignment in assignments: + scalar = self.scalar_monitors[assignment.env_id] + scalar.observe(env, action) + assert scalar.validation(env) == checks.terminal[assignment.env_id] + for assignment in assignments: + row = assignment.env_id + buffer = self.buffers[row] + values = ( + action.value + if isinstance(action.value, torch.Tensor) + else action.value["qpos"] + ) + buffer["actions"].append(values[row].detach().cpu().clone()) + buffer["states"].append( + robot.get_qpos()[row].detach().cpu().clone() + ) + if ( + assignment.workload_id == "first" + and assignment.ordinal == 0 + and len(buffer["actions"]) == 12 + ): + rejected.append(row) + return rejected + + def complete(self, result): + row = result.assignment.env_id + native = self.assignments.pop(row) + data = self.buffers.pop(row) + count = result.program.lengths[0] + assert ( + len(data["actions"]) == count and len(data["states"]) == count + 1 + ) + assert ( + result.world_control_end - result.world_control_start + 1 == count + ) + self.finished.append( + ( + result.assignment.workload_id, + result.assignment.ordinal, + count, + result.program.accepted[0], + ) + ) + if not result.program.accepted[0]: + return engine.complete_row(native, None) + episode = ExpertEpisode( + native.item.candidate.identity, + {"joint_positions": torch.stack(data["states"])}, + torch.stack(data["actions"]), + torch.arange(count + 1, dtype=torch.float64) * env.step_dt, + "qpos", + ValidationResult( + ( + ValidationCheck("task_success", "passed"), + ValidationCheck( + "path_collision", checks.results[row].status + ), + *checks.terminal[row].checks, + ) + ), + native.episode_id, + native.commit_id, + ) + return engine.complete_row(native, episode) + + source = Source() + owner = id(env.sim.get_world()) + done = [] + executor = WorkloadProgramExecutor( + env, + [ + ExpansionWorkloadCfg("first", 2, 4), + ExpansionWorkloadCfg("second", 1, 2), + ExpansionWorkloadCfg("queued", 1, 2), + ], + source, + WorkloadExecutionCfg( + workload_count=2, batch_size=2, max_steps=2500, settling_steps=5 + ), + on_workload_done=lambda name, counts: done.append((name, counts)), + ) + result = executor.run() + assert result["complete"], (result, source.finished) + assert result["num_envs"] == 4 and result["refills"] > 0 + assert result["counts"]["first"] == { + "attempts": 3, + "rollouts": 3, + "committed": 2, + } + assert len(done) == 3 and len(sink.inspect()) == 4 + assert session.snapshot()["counts"]["committed"] == 4 + assert ( + id(env.sim.get_world()) == owner and len(SimulationManager._instances) == 1 + ) + assert next(entry for entry in source.finished if entry[:2] == ("first", 0))[ + 2: + ] == (13, False) + for receipt in sink.inspect(): + episode = load_expansion_episode(receipt.storage_id) + assert len(episode.timestamps) == len(episode.actions) + 1 + assert episode.validation.accepted + with pytest.raises(RuntimeError, match="single-use"): + executor.run() + for adapter in source.adapters: + adapter.close() + checks.close() + (Path(output) / "workload-result.json").write_text(json.dumps(result, indent=2)) + finally: + if env is not None: + env.close(exit_process=False) + SimulationManager.flush_cleanup_queue() + + +@pytest.mark.requires_sim +def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path): + result = subprocess.run( + [sys.executable, __file__, str(tmp_path)], + cwd=Path(__file__).resolve().parents[3], + env={**os.environ, "SDL_VIDEODRIVER": "offscreen", "OMP_NUM_THREADS": "1"}, + capture_output=True, + text=True, + timeout=300, + ) + assert result.returncode == 0, result.stdout[-4000:] + result.stderr[-5000:] + + +if __name__ == "__main__": + _probe(sys.argv[1]) diff --git a/tests/sim/atomic_skills/test_runtime_commands.py b/tests/sim/atomic_skills/test_runtime_commands.py index 6bb50b4768..14ad1a673c 100644 --- a/tests/sim/atomic_skills/test_runtime_commands.py +++ b/tests/sim/atomic_skills/test_runtime_commands.py @@ -141,6 +141,40 @@ def _frame( ) +@pytest.mark.gpu +def test_cuda_sequence_snapshots_keep_ownership_and_revalidate_mutated_values() -> None: + target = JointPositionTarget("arm", (0, 1)) + ids = torch.tensor([1, 5], device="cuda:0") + frames = tuple( + RuntimeCommandFrame( + commands=( + EndpointCommand( + target, + JointPositionPayload( + torch.full((2, 2), 0.1 * (i + 1), device="cuda:0") + ), + ), + ), + active_mask=torch.tensor([True, False], device="cuda:0"), + env_ids=ids, + hold_duration=torch.full((2,), 0.04, device="cuda:0"), + ) + for i in range(3) + ) + original = TimedCommandSequence(frames, ids) + copied = original.snapshot() + original.frames[0].commands[0].payload.positions.fill_(99) + assert copied.frames[0].commands[0].payload.positions[0, 0] == 0.1 + copied.frames[0].commands[0].payload.positions.fill_(55) + assert copied.frames[1].commands[0].payload.positions[0, 0] == 0.2 + original.frames[0].commands[0].payload.positions[0, 0] = float("nan") + with pytest.raises(ValueError, match="finite"): + original.snapshot() + copied.frames[0].hold_duration[0] = -0.1 + with pytest.raises(ValueError, match="non-negative"): + copied.snapshot() + + def test_runtime_command_payload_is_abstract() -> None: with pytest.raises(TypeError): RuntimeCommandPayload() # type: ignore[abstract] diff --git a/tests/sim/motion/solvers/test_base_solver.py b/tests/sim/motion/solvers/test_base_solver.py index c5f260493e..745cfde5f4 100644 --- a/tests/sim/motion/solvers/test_base_solver.py +++ b/tests/sim/motion/solvers/test_base_solver.py @@ -45,6 +45,38 @@ } +@pytest.mark.parametrize( + "device", ["cpu", pytest.param("cuda:0", marks=pytest.mark.gpu)] +) +def test_tcp_offset_jacobian_uses_the_solver_device(tmp_path, device): + path = tmp_path / "one_joint.urdf" + path.write_text(""" + + + + + + + + """) + solver = PytorchSolverCfg( + urdf_path=str(path), + root_link_name="base", + end_link_name="tool", + joint_names=["joint"], + ).init_solver(device=device) + expected = torch.tensor( + [[[-0.2], [1.0], [0.0], [0.0], [0.0], [1.0]]], device=device + ) + for locations in ( + torch.tensor([0.0, 0.2, 0.0]), + torch.tensor([[0.0, 0.2, 0.0]], device=device), + ): + actual = solver.get_jacobian(torch.zeros(1, 1), locations=locations) + torch.testing.assert_close(actual, expected, rtol=0, atol=1e-6) + assert actual.device.type == torch.device(device).type + + @pytest.mark.parametrize("dtype", [np.float16, np.float32, np.float64]) def test_nearest_weight_numpy_dtypes_update_tensor_in_place(dtype) -> None: solver = object.__new__(OPWSolver) diff --git a/tests/sim/scene/feasibility/test_collision_planning.py b/tests/sim/scene/feasibility/test_collision_planning.py index 899164d3aa..12b028b1ee 100644 --- a/tests/sim/scene/feasibility/test_collision_planning.py +++ b/tests/sim/scene/feasibility/test_collision_planning.py @@ -69,6 +69,67 @@ def pose(x): checker.check({"left": pose(0)}) +@pytest.mark.parametrize( + "device", ["cpu", pytest.param("cuda:0", marks=pytest.mark.gpu)] +) +def test_batched_geometry_matches_scalar_rows_and_rebinds_permissions(device): + bodies = ( + CollisionBody("arm", "arm", "box", (0.2, 0.2, 0.2), robot=True), + CollisionBody("payload", "payload", "sphere", (0.1,)), + CollisionBody("obstacle", "obstacle", "box", (0.2, 0.2, 0.2)), + CollisionBody("ground", "ground", "halfspace", (0, 0, 1, 0)), + ) + frames = { + name: np.repeat(np.eye(4)[None], 3, axis=0) + for name in ("arm", "payload", "obstacle", "ground") + } + for name, x in (("arm", 0.0), ("payload", 1.0), ("obstacle", 2.0)): + frames[name][:, 0, 3] = x + frames[name][:, 2, 3] = 0.5 + frames["payload"][1, 0, 3] = 0.1 + frames["payload"][2, 2, 3] = -0.1 + checker = NewtonCollisionChecker(bodies, device=device) + try: + for allowed in ((), (("arm", "payload"),)): + expected, pairs = [], [] + for row in range(3): + report, _ = checker.check( + {key: value[row] for key, value in frames.items()}, + allowed_contacts=allowed, + moving_objects=("payload",), + ) + expected.append(report.status) + pairs.append(checker.last_pair) + result = checker.check_batch( + frames, allowed_contacts=allowed, moving_objects=("payload",) + ) + assert [report.status for report in result] == expected + assert checker.last_batch_pairs == tuple(pairs) + selected = checker.check_batch( + frames, + allowed_contacts=allowed, + moving_objects=("payload",), + env_ids=(2, 0), + ) + assert [report.status for report in selected] == [expected[2], expected[0]] + assert expected == ["passed", "passed", "failed"] + # Changing permissions cannot reuse the previous mask, and invalid row + # IDs or malformed physical transforms fail before querying geometry. + assert ( + checker.check_batch(frames, moving_objects=("payload",))[1].status + == "failed" + ) + with pytest.raises(ValueError, match="unique"): + checker.check_batch(frames, env_ids=(1, 1)) + assert checker.last_batch_pairs == () + malformed = {key: value.copy() for key, value in frames.items()} + malformed["arm"][0, 3, 0] = 1 + with pytest.raises(ValueError, match="rigid"): + checker.check_batch(malformed) + finally: + checker.close() + + def test_phase_branches_must_connect_and_dual_targets_stay_synchronized(): identity = np.eye(4).tolist() mode = TaskOperationMode( diff --git a/tests/sim/sensors/test_contact_default_e2e.py b/tests/sim/sensors/test_contact_default_e2e.py index ba43dc0e80..69997e0e36 100644 --- a/tests/sim/sensors/test_contact_default_e2e.py +++ b/tests/sim/sensors/test_contact_default_e2e.py @@ -19,6 +19,7 @@ import pytest import warp as wp +import torch from embodichain.lab.sim.cfg import ( DefaultPhysicsCfg, @@ -26,7 +27,7 @@ RigidBodyPhysicsCfg, RigidObjectCfg, ) -from embodichain.lab.sim.sensors import ContactSensorCfg +from embodichain.lab.sim.sensors import ContactSensorCfg, ContactPermissionChecker from embodichain.lab.sim.shapes import CubeCfg from embodichain.lab.sim.sim_manager import SimulationManager, SimulationManagerCfg @@ -34,15 +35,19 @@ @pytest.mark.parametrize( - ("device", "expected_contacts_per_env"), + ("device", "expected_contacts_per_env", "direct_gpu_api"), [ - pytest.param("cpu", 4, id="cpu"), - pytest.param("cuda:0", 4, marks=pytest.mark.gpu, id="cuda"), + pytest.param("cpu", 4, True, id="cpu"), + pytest.param("cuda:0", 4, True, marks=pytest.mark.gpu, id="cuda"), + pytest.param( + "cuda:0", 4, False, marks=pytest.mark.gpu, id="cuda-native-reports" + ), ], ) def test_default_contact_sensor_preserves_contact_multiplicity( device: str, expected_contacts_per_env: int, + direct_gpu_api: bool, ) -> None: wp.init() if device.startswith("cuda") and not wp.is_cuda_available(): @@ -53,7 +58,7 @@ def test_default_contact_sensor_preserves_contact_multiplicity( headless=True, num_envs=2, arena_space=2.0, - physics_cfg=DefaultPhysicsCfg(device=device), + physics_cfg=DefaultPhysicsCfg(device=device, direct_gpu_api=direct_gpu_api), ) ) try: @@ -110,6 +115,51 @@ def test_default_contact_sensor_preserves_contact_multiplicity( sensor.get_actor_info(actor_id).path.endswith("/cube") for actor_id in cube_actor_ids ) + assert sim.is_use_gpu_physics == device.startswith("cuda") + assert sim.get_world().get_physics_scene().is_direct_gpu() == ( + device.startswith("cuda") and direct_gpu_api + ) + if device == "cpu" or not direct_gpu_api: + maps = [{} for _ in range(2)] + for uid in ("cube", "ground", "default_plane"): + values = sensor.get_actor_ids(uid)[:, 0].cpu().tolist() + for row, actor in enumerate(values): + maps[row][actor] = uid + checker = ContactPermissionChecker( + sensor, + maps, + allowed_contacts=(("cube", "ground"),), + moving_frames=("cube",), + ) + accepted = checker.check() + assert accepted[:, 0].cpu().tolist() == [0, 0] + refused = ContactPermissionChecker( + sensor, maps, allowed_contacts=(), moving_frames=("cube",) + ) + assert refused.check()[:, 0].cpu().tolist() == [3, 3] + assert accepted[:, 0].cpu().tolist() == [0, 0] + if device.startswith("cuda"): + other = torch.cuda.Stream() + with torch.cuda.stream(other): + repeated = checker.check() + other.synchronize() + assert repeated[:, 0].cpu().tolist() == [0, 0] + bounded = sim.add_sensor( + ContactSensorCfg( + uid="bounded", + rigid_uid_list=["cube"], + filter_need_both_actor=False, + max_contacts_per_env=1, + ) + ) + bounded.update() + overflow = ContactPermissionChecker( + bounded, + maps, + allowed_contacts=(("cube", "ground"),), + moving_frames=("cube",), + ) + assert overflow.check()[:, 0].cpu().tolist() == [4, 4] finally: sim.destroy(exit_process=False) SimulationManager.flush_cleanup_queue() From 2cbe6a59fac51685d29dcd61a4ae86459bfa6037 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 14 Nov 2026 09:12:02 +0000 Subject: [PATCH 02/49] fix(expansion): own validated metadata inputs --- docs/source/api_reference/public_api.rst | 8 +++--- embodichain/utils/_owned_json.py | 33 ++++++++++++++---------- tests/lab/expansion/test_persistence.py | 8 ++++++ 3 files changed, 31 insertions(+), 18 deletions(-) diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index 9620eac1cb..c1fd609325 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1777,7 +1777,7 @@ attempts at episode boundaries. Native failures invalidate the active host. PreparingExpansionHost embodichain.lab.expansion.episode_export ---------------------------------------- +---------------------------------------- .. currentmodule:: embodichain.lab.expansion.episode_export @@ -1946,7 +1946,7 @@ Apply one native visual profile per compatible World cohort. Render complete rec inspect_observation_variants embodichain.lab.expansion.workloads ----------------------------------- +----------------------------------- .. currentmodule:: embodichain.lab.expansion.workloads @@ -3706,7 +3706,7 @@ embodichain.lab.sim.sensors.camera CameraCfg embodichain.lab.sim.sensors.contact ----------------------------------- +----------------------------------- .. currentmodule:: embodichain.lab.sim.sensors.contact @@ -3715,7 +3715,7 @@ embodichain.lab.sim.sensors.contact ContactPermissionChecker embodichain.lab.sim.sensors.contact.permissions ----------------------------------------------- +----------------------------------------------- .. currentmodule:: embodichain.lab.sim.sensors.contact.permissions diff --git a/embodichain/utils/_owned_json.py b/embodichain/utils/_owned_json.py index 851a39a93d..12460f8477 100644 --- a/embodichain/utils/_owned_json.py +++ b/embodichain/utils/_owned_json.py @@ -32,14 +32,29 @@ class _FrozenTuple(tuple): __slots__ = () + def __new__(cls, values): + return super().__new__(cls, (freeze_metadata(value) for value in values)) + class _FrozenMap(Mapping): """Own validated immutable children; expose no mutable backing dictionary.""" __slots__ = ("_data", "_strict", "_encoded") - def __init__(self, values, strict): - object.__setattr__(self, "_data", MappingProxyType(values)) + def __init__(self, values): + if not isinstance(values, Mapping): + raise ValueError("metadata must contain only finite JSON values") + owned, strict = {}, True + for key, value in values.items(): + if not isinstance(key, str) or not key.strip(): + raise ValueError("metadata key must be a nonempty string") + item = freeze_metadata(value) + owned[key] = item + strict &= _key_valid(key) and _strict_keys(item) + # Validate and detach even direct construction of a node's public type. + # Reusing a supposedly immutable wrapper over a caller-owned dictionary + # would permit later mutation to invalidate its finite-JSON proof. + object.__setattr__(self, "_data", MappingProxyType(owned)) object.__setattr__(self, "_strict", strict) object.__setattr__(self, "_encoded", None) @@ -99,17 +114,7 @@ def freeze_metadata(value: object) -> object: raise ValueError("metadata must contain only finite JSON values") return value if isinstance(value, (list, tuple)): - return _FrozenTuple(freeze_metadata(item) for item in value) + return _FrozenTuple(value) if isinstance(value, Mapping): - result = {} - strict = True - for key, item in value.items(): - # The expansion contract accepts whitespace around nonempty keys; - # the Gym JSON-copy contract is stricter. Retain both behaviours. - if not isinstance(key, str) or not key.strip(): - raise ValueError("metadata key must be a nonempty string") - owned = freeze_metadata(item) - result[key] = owned - strict &= _key_valid(key) and _strict_keys(owned) - return _FrozenMap(result, strict) + return _FrozenMap(value) raise ValueError("metadata must contain only finite JSON values") diff --git a/tests/lab/expansion/test_persistence.py b/tests/lab/expansion/test_persistence.py index 81bcd6d803..cb8e043b04 100644 --- a/tests/lab/expansion/test_persistence.py +++ b/tests/lab/expansion/test_persistence.py @@ -88,6 +88,14 @@ def test_verified_episode_reads_own_tensors_and_invalidate_changed_bytes(tmp_pat projected = json_safe_copy(third.metadata, field_name="metadata") projected["nested"]["values"][0] = 55 assert third.metadata["nested"]["values"][0] == 1 + external = {"nested": [3]} + owned = type(third.metadata)(external) + external["nested"][0] = 99 + assert owned["nested"][0] == 3 + with pytest.raises(ValueError, match="finite"): + type(third.metadata)({"invalid": float("nan")}) + with pytest.raises(ValueError, match="finite"): + type(third.metadata["nested"]["values"])((float("inf"),)) path = Path(receipt.storage_id) path.write_bytes(b"invalid replaced evidence") with pytest.raises((ValueError, OSError)): From 61f922d38e6161ec3a7b19137f7f043f8fe8192e Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 14 Nov 2026 10:24:38 +0000 Subject: [PATCH 03/49] fix(sensors): wait for contact sample before permission checks Order permission queries after the latest sensor sample on the caller's CUDA stream without resampling or advancing histories. Cover pending forbidden contacts and dropped evidence in standalone and history sampling paths. Validation: 75 targeted tests passed; Black 26.10.1, public API documentation coverage and agent context checks passed. --- .../topics/sensor-system/sensor-system.md | 2 ++ .../lab/sim/sensors/contact/permissions.py | 5 +++ .../sim/sensors/test_contact_sensor_graph.py | 36 ++++++++++++++++--- 3 files changed, 38 insertions(+), 5 deletions(-) diff --git a/agent_context/topics/sensor-system/sensor-system.md b/agent_context/topics/sensor-system/sensor-system.md index 82e9440ed1..91601b5073 100644 --- a/agent_context/topics/sensor-system/sensor-system.md +++ b/agent_context/topics/sensor-system/sensor-system.md @@ -128,6 +128,8 @@ valid; sensor adaptation does not synthesize a common contact manifold. `ContactPermissionChecker` consumes complete native samples with explicit actor/frame permissions, returning owned per-row device summaries. It does not choose the host's sampling frequency or relax unavailable-impulse/loss gates. +Eager checks wait for the latest sensor sample on their CUDA stream without +refreshing contacts or advancing histories. Global static actors retain their explicit row memberships. Rebind after query topology changes. Default CUDA dynamics can select ordinary reporting through `DefaultPhysicsCfg.direct_gpu_api=False` when static actor identity is required; diff --git a/embodichain/lab/sim/sensors/contact/permissions.py b/embodichain/lab/sim/sensors/contact/permissions.py index 831dc8f3b1..5270daac22 100644 --- a/embodichain/lab/sim/sensors/contact/permissions.py +++ b/embodichain/lab/sim/sensors/contact/permissions.py @@ -123,6 +123,9 @@ def __init__( def check(self) -> torch.Tensor: """Return owned per-row ``(reason, actor0, actor1)`` integer summaries. + Eager CUDA checks wait for the latest sensor sample on the caller's + stream without refreshing contacts or advancing histories. + Returns: Tensor ``(B, 3)`` on the sensor device. Reason zero passes; one means unavailable applied impulse, two unknown/cross-row actor, three @@ -140,6 +143,8 @@ def check(self) -> torch.Tensor: if self._ready is not None: torch.cuda.current_stream(self.device).wait_event(self._ready) + # The checker event orders its own buffers, not the sensor's producer. + self.sensor._wait_for_sample() data = self.sensor.get_data() if id(self.sensor._query.actors) != self._actors_token: raise RuntimeError( diff --git a/tests/sim/sensors/test_contact_sensor_graph.py b/tests/sim/sensors/test_contact_sensor_graph.py index 2241692cbb..297039b4e0 100644 --- a/tests/sim/sensors/test_contact_sensor_graph.py +++ b/tests/sim/sensors/test_contact_sensor_graph.py @@ -23,7 +23,11 @@ import warp as wp from dexsim.scene import ContactActorInfo, ContactBuffer, ContactQueryCapabilities -from embodichain.lab.sim.sensors import ContactSensor, ContactSensorCfg +from embodichain.lab.sim.sensors import ( + ContactPermissionChecker, + ContactSensor, + ContactSensorCfg, +) pytestmark = [pytest.mark.gpu, pytest.mark.no_sim] @@ -209,8 +213,14 @@ def assert_air_time(value: float) -> None: @pytest.mark.parametrize("history_sample", [False, True]) -def test_cached_sample_is_ready_on_another_cuda_stream(history_sample: bool) -> None: - """A cached update must wait for the producer's outstanding device work.""" +@pytest.mark.parametrize( + "dropped_count", + [pytest.param(0, id="forbidden-contact"), pytest.param(3, id="dropped-evidence")], +) +def test_cached_sample_is_ready_on_another_cuda_stream( + history_sample: bool, dropped_count: int +) -> None: + """Permission checks and cached updates wait for the pending sensor sample.""" wp.init() device = torch.device("cuda:0") query = _CudaQuery(device) @@ -238,6 +248,12 @@ def test_cached_sample_is_ready_on_another_cuda_stream(history_sample: bool) -> if history_sample else None ) + checker = ContactPermissionChecker( + sensor, + ({0: "ground", 10: "cube"}, {0: "ground", 20: "cube"}), + allowed_contacts=(), + moving_frames=("cube",), + ) def sample() -> None: if history_sample: @@ -246,7 +262,10 @@ def sample() -> None: sensor.update() sample() # Compile kernels before arranging the delayed producer. + checker.check() sensor.reset() + query.buffer.device_counts[0] = 0 if dropped_count else 2 + query.buffer.device_counts[1] = dropped_count torch.cuda.synchronize(device) owner.physics_step_index += 1 producer = torch.cuda.Stream(device=device) @@ -255,14 +274,21 @@ def sample() -> None: torch.cuda._sleep(200_000_000) sample() with torch.cuda.stream(consumer): + # Check before a cached update can independently wait for the producer. + permissions = checker.check() sample() observed = sensor.get_data()["is_valid"].clone() force = history.force.clone() if history is not None else None consumer.synchronize() - assert observed.tolist() == [[True, False], [True, False]] + assert permissions.tolist() == ( + [[4, 0, 0], [4, 0, 0]] if dropped_count else [[3, 0, 10], [3, 0, 20]] + ) + assert observed.tolist() == [[not dropped_count, False]] * 2 if force is not None: torch.testing.assert_close( force, - torch.tensor([[[0.0, 0.0, 2.0]], [[0.0, 0.0, 2.0]]], device=device), + torch.tensor( + [[[0.0, 0.0, 0.0 if dropped_count else 2.0]]] * 2, device=device + ), ) producer.synchronize() From 4723cba69c505c3b33315efcbdee51a6b3c9d946 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 14 Nov 2026 14:02:08 +0000 Subject: [PATCH 04/49] feat(expansion): expose task ports and measured ghost comparison --- agent_context/MAP.yaml | 2 +- .../expansion-engine/expansion-engine.md | 20 + .../topics/motion-planning/motion-planning.md | 7 + .../sim-visualization/sim-visualization.md | 9 + .../embodichain.lab.task_program.rst | 4 + docs/source/api_reference/public_api.rst | 92 +++ embodichain/lab/expansion/__init__.py | 14 + embodichain/lab/expansion/_gym_context.py | 4 + embodichain/lab/expansion/_gym_execution.py | 83 +++ embodichain/lab/expansion/acceptance.py | 611 ++++++++++++++++ embodichain/lab/expansion/comparison.py | 681 ++++++++++++++++++ embodichain/lab/expansion/host.py | 32 +- embodichain/lab/expansion/host_extensions.py | 112 +++ embodichain/lab/sim/atomic_skills/policies.py | 27 +- .../sim/atomic_skills/primitives/pick_up.py | 7 + .../lab/sim/atomic_skills/primitives/place.py | 7 + embodichain/lab/sim/motion/_phase_paths.py | 110 +++ .../lab/sim/motion/motion_generator.py | 30 + .../integrations/_native_plan_expansion.py | 455 ++++++++++++ .../task_program/integrations/configured.py | 2 + .../task_program/integrations/expansion.py | 72 +- .../lab/task_program/runtime/results.py | 1 + .../lab/visualization/markers/__init__.py | 2 + .../lab/visualization/markers/_native.py | 43 +- .../lab/visualization/markers/frame.py | 86 +++ .../lab/visualization/markers/group.py | 6 +- tests/lab/expansion/test_comparison.py | 76 ++ .../lab/expansion/test_extension_ports_sim.py | 193 +++++ 28 files changed, 2775 insertions(+), 13 deletions(-) create mode 100644 embodichain/lab/expansion/acceptance.py create mode 100644 embodichain/lab/expansion/comparison.py create mode 100644 embodichain/lab/expansion/host_extensions.py create mode 100644 embodichain/lab/sim/motion/_phase_paths.py create mode 100644 embodichain/lab/task_program/integrations/_native_plan_expansion.py create mode 100644 embodichain/lab/visualization/markers/frame.py create mode 100644 tests/lab/expansion/test_comparison.py create mode 100644 tests/lab/expansion/test_extension_ports_sim.py diff --git a/agent_context/MAP.yaml b/agent_context/MAP.yaml index 0e27617b7f..c5b8dc0e3e 100644 --- a/agent_context/MAP.yaml +++ b/agent_context/MAP.yaml @@ -198,7 +198,7 @@ topics: - id: expansion-engine title: Expansion Engine aliases: [Expansion Engine, offline expansion, 扩增引擎, 批量专家采集] - keywords: [ExpansionEngine, ExpansionRunCfg, ExpansionJobCfg, ExpansionSession, ExpansionSessionCfg, ExpansionCoverage, EpisodeCoverage, GymExpansionHost, ArtifactEpisodeSink, MediaSpool, render_observation_variants, WorkloadProgramExecutor, WorkloadExecutionCfg, workload_count] + keywords: [ExpansionEngine, ExpansionRunCfg, ExpansionJobCfg, ExpansionSession, ExpansionSessionCfg, ExpansionCoverage, EpisodeCoverage, GymExpansionHost, ArtifactEpisodeSink, MediaSpool, render_observation_variants, WorkloadProgramExecutor, WorkloadExecutionCfg, workload_count, GymExpansionHostExtensions, MeasuredExpansionValidator, MeasuredTrajectory, preview_expansion_comparison, 扩增虚影] paths: [topics/expansion-engine/expansion-engine.md] source_of_truth: - embodichain/lab/expansion/ diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 88c2794c38..cb2fe4abab 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -13,6 +13,9 @@ algorithms stay in `sim.motion.expansion`; scene and workspace algorithms stay i | Rolling workload × B execution in one caller-owned World | `embodichain/lab/expansion/workloads.py` | | Job assembly, stage recovery and inspect | `embodichain/lab/expansion/workflow.py`, `stages.py` | | Native World ownership and compatibility facade | `embodichain/lab/expansion/host.py` | +| Task-owned render/source/transform/acceptance ports | `embodichain/lab/expansion/host_extensions.py` | +| Measured geometry, native substeps and sustained-contact acceptance | `embodichain/lab/expansion/acceptance.py` | +| Physics-free measured reference/ghost comparison | `embodichain/lab/expansion/comparison.py` | | Native recipes, cohort preparation, step observation and episode assembly | `embodichain/lab/expansion/_gym_recipe.py`, `_gym_prepare.py`, `_gym_execution.py`, `_gym_frames.py`, `_gym_episode.py` | | Durable recipes, attempts and invocation budgets | `embodichain/lab/expansion/journal.py` | | Task Program execution with native or prototype motion | `embodichain/lab/expansion/program.py`, `real2sim.py` | @@ -73,6 +76,23 @@ sampling, whole-cohort preparation, active-row frame buffering and measured epis assembly have separate owners. Preserve the host constructor, port methods and existing readout properties used by benchmark/showcase instrumentation. +`GymExpansionHostExtensions` supplies non-owning callbacks for collection renderer, +scene source, immutable recipe transformation, measured validator and row plan +factory. `ExpansionRowContext` carries pinned identity without exposing mutable +host buffers. Hosts retain preparation, control clocks, T+1 capture, attachment +archival and confirmed receipts. Do not replace configured nominal sources with +an extension transform. `MeasuredExpansionValidator` presents the same lifecycle +for independent geometry and native contacts, including task-declared sustained +finger contact and drift limits. Every original physical substep remains required; +missing impulses, unknown actors and dropped samples reject acceptance. + +`preview_expansion_comparison` consumes a caller-owned environment factory and +qualified measured episodes. Shared-time pause/switch controls retain the selected +time; physics stays disabled and render updates do not mutate saved evidence. +`MarkerFramePublisher` owns resident robot/object groups and publishes a coherent +cross-group frame through the public marker layer. Task assets and any collection +process orchestration remain outside the replay core. + `TaskProgramDemoBridge.program_id` and `env_ids` expose binding identity without runtime traversal. `EmbodiedEnv.task_program_bridge_scope()` restores the borrowed bridge even after failure. `Real2SimTabletopSource` and explicit diff --git a/agent_context/topics/motion-planning/motion-planning.md b/agent_context/topics/motion-planning/motion-planning.md index df16f69a42..527adf63f0 100644 --- a/agent_context/topics/motion-planning/motion-planning.md +++ b/agent_context/topics/motion-planning/motion-planning.md @@ -53,6 +53,13 @@ positions `(B, N, dof)`. Use `PlanState.single()` for one environment. duration is their sum. Failed results may omit positions. Planning timing never changes simulator `physics_dt`. +`MotionGenOptions.waypoint_modes` explicitly selects joint/Cartesian paths to +individual keyframes under fixed-grid sequential IK. Adjacent equal modes share +ordinary native requests; composition retains the total control grid and row +failure masks. No robot UID or waypoint count enables the behavior. Atomic +`MotionPolicy.phase_paths` names the PickUp/Place phases that opt into this path; +ordinary calls and other primitives retain their own planning semantics. + `motion_gen` delegates timing to its backend. `ik_interp` needs explicit start/count/dt, rejects backend-specific options and uses minimum-jerk segments when limits apply. Adaptive timing and batched IK remain defaults. Explicit diff --git a/agent_context/topics/sim-visualization/sim-visualization.md b/agent_context/topics/sim-visualization/sim-visualization.md index 2f5a29ad49..4abc6bcca5 100644 --- a/agent_context/topics/sim-visualization/sim-visualization.md +++ b/agent_context/topics/sim-visualization/sim-visualization.md @@ -80,6 +80,15 @@ with visual origins. URDF FK accepts all `joint_names`, including caller-resolve mimic joints. Multiple poses can be displayed in one environment. Tasks own motion loading, sampling and alignment. +`MarkerFramePublisher` stages caller-owned groups for one cross-group native +publication. Initial preload retains hidden resources; subsequent frames upload +visible instances and change real visibility without moving hidden geometry. +`MarkerGroup.snapshot(visible_only=True)` preserves original instance IDs while +omitting hidden meshes. Close the publisher before its World. The measured +reference/ghost timeline and keyboard playback live in +`lab/expansion/comparison.py`; task/environment and collection ownership stay +with the caller. + `RobotMarkersAppearanceCfg` selects source appearance or a base-color override, with adjustable opacity. Source textures and material parameters are preserved; opaque visuals use scene lighting. Transparent shading may differ by renderer. diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst index 6eeee2f284..97394708b1 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst @@ -404,6 +404,7 @@ template contract. TaskProgramMappedRetimeRecord TaskProgramSameGridExpansionFactory TaskProgramSameGridExpansionRecord + TaskProgramNativeExpansionRecord .. autoclass:: TaskProgramSourceAdapter :members: @@ -426,6 +427,9 @@ template contract. .. autoclass:: TaskProgramSameGridExpansionRecord :members: +.. autoclass:: TaskProgramNativeExpansionRecord + :members: + .. currentmodule:: embodichain.lab.task_program MLLM frontend diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index c1fd609325..15ba57ac10 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1672,6 +1672,33 @@ and durable episode-boundary recovery. See the offline expansion example. WorkloadProgramExecutor export_expansion_episodes +.. autosummary:: + + GymExpansionHostExtensions + ExpansionRowContext + ExpansionValidator + MeasuredExpansionValidator + MeasuredTrajectory + record_reference_trajectory + preview_expansion_comparison + +embodichain.lab.expansion.acceptance +------------------------------------ + +Measured task and physical acceptance share a host port. Geometry uses independent +Newton queries; native contacts inspect every physical sample and optionally +require sustained finger contact and bounded object drift. Tasks declare all +permissions and thresholds; missing or dropped evidence rejects the trajectory. + +.. currentmodule:: embodichain.lab.expansion.acceptance + +.. autosummary:: + + MeasuredExpansionValidator + +.. autoclass:: MeasuredExpansionValidator + :members: + embodichain.lab.expansion.artifacts ----------------------------------- @@ -1685,6 +1712,29 @@ Typed content-addressed numeric, media and source references. Paths remain conta EpisodeArtifactManifest resolve_artifact_path +embodichain.lab.expansion.comparison +------------------------------------ + +Reference and accepted expansion recordings share a measured timeline. The +native viewer retains robot/object ghost resources, supports pause and selection, +and publishes render states with physics disabled. Collection is an optional +caller-owned callback, and the environment factory retains task/asset ownership. + +.. currentmodule:: embodichain.lab.expansion.comparison + +.. autosummary:: + + MeasuredTrajectory + record_reference_trajectory + preview_expansion_comparison + +.. autoclass:: MeasuredTrajectory + :members: + +.. autofunction:: record_reference_trajectory + +.. autofunction:: preview_expansion_comparison + embodichain.lab.expansion.configured ------------------------------------ @@ -1813,6 +1863,30 @@ The native Gym adapter owns World preparation, parameter readback and Task Progr GymExpansionHost +embodichain.lab.expansion.host_extensions +----------------------------------------- + +Runtime extension callbacks select collection rendering, a scene source, measured +acceptance, immutable recipe transforms and per-row Task Program plan factories. +The native host continues to own preparation, clocks, state capture and receipts. + +.. currentmodule:: embodichain.lab.expansion.host_extensions + +.. autosummary:: + + ExpansionValidator + ExpansionRowContext + GymExpansionHostExtensions + +.. autoclass:: ExpansionValidator + :members: + +.. autoclass:: ExpansionRowContext + :members: + +.. autoclass:: GymExpansionHostExtensions + :members: + embodichain.lab.expansion.journal --------------------------------- @@ -4370,6 +4444,8 @@ native simulation windows and browser visualization. MarkerPrototypeCfg MarkerGroup + MarkerFramePublisher + embodichain.lab.visualization.markers.cfg ---------------------------------------- @@ -4380,6 +4456,22 @@ embodichain.lab.visualization.markers.cfg MarkerPrototypeCfg MarkerGroupCfg +embodichain.lab.visualization.markers.frame +------------------------------------------- + +The frame publisher stages multiple marker groups and submits one native visual +batch. Hidden instances retain their resources and actual visibility; later +frames transform only visible instances. Publishing never advances physics. + +.. currentmodule:: embodichain.lab.visualization.markers.frame + +.. autosummary:: + + MarkerFramePublisher + +.. autoclass:: MarkerFramePublisher + :members: + embodichain.lab.visualization.markers.group ------------------------------------------ diff --git a/embodichain/lab/expansion/__init__.py b/embodichain/lab/expansion/__init__.py index 5a32997b25..fd6dd78f38 100644 --- a/embodichain/lab/expansion/__init__.py +++ b/embodichain/lab/expansion/__init__.py @@ -67,6 +67,13 @@ "WorkloadSource", "WorkloadProgramExecutor", "export_expansion_episodes", + "GymExpansionHostExtensions", + "ExpansionRowContext", + "ExpansionValidator", + "MeasuredExpansionValidator", + "MeasuredTrajectory", + "record_reference_trajectory", + "preview_expansion_comparison", ] @@ -112,6 +119,13 @@ def __getattr__(name: str) -> object: "WorkloadSource": "workloads", "WorkloadProgramExecutor": "workloads", "export_expansion_episodes": "episode_export", + "GymExpansionHostExtensions": "host_extensions", + "ExpansionRowContext": "host_extensions", + "ExpansionValidator": "host_extensions", + "MeasuredExpansionValidator": "acceptance", + "MeasuredTrajectory": "comparison", + "record_reference_trajectory": "comparison", + "preview_expansion_comparison": "comparison", }.get(name, "engine") module = f"{__name__}.{owner}" value = getattr(import_module(module), name) diff --git a/embodichain/lab/expansion/_gym_context.py b/embodichain/lab/expansion/_gym_context.py index 1bfd210f86..0ae951c4af 100644 --- a/embodichain/lab/expansion/_gym_context.py +++ b/embodichain/lab/expansion/_gym_context.py @@ -27,6 +27,7 @@ from .journal import ExpansionJournal, RecipeAttempt from .recipes import BatchCompatibility, OperatorCapability, ExpansionRecipe from .contracts import CandidateIdentity, ValidationResult +from .host_extensions import GymExpansionHostExtensions if TYPE_CHECKING: from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv, EmbodiedEnvCfg @@ -90,3 +91,6 @@ class GymHostContext: services: dict[int, _EpisodeSource] = field(default_factory=dict) bridges: dict[int, TaskProgramDemoBridge] = field(default_factory=dict) recipe: Callable[[int], ExpansionRecipe] | None = None + extensions: GymExpansionHostExtensions = field( + default_factory=GymExpansionHostExtensions + ) diff --git a/embodichain/lab/expansion/_gym_execution.py b/embodichain/lab/expansion/_gym_execution.py index 8c45786af6..5ced90c201 100644 --- a/embodichain/lab/expansion/_gym_execution.py +++ b/embodichain/lab/expansion/_gym_execution.py @@ -18,10 +18,13 @@ from __future__ import annotations from collections.abc import Callable +from dataclasses import replace import time from embodichain.data_pipeline.recording.media import _atomic_json from embodichain.lab.expansion.program import TaskProgramBatchExecutor from .contracts import CandidateIdentity, ExpertEpisode +from .contracts import SceneCase +from .host_extensions import ExpansionRowContext from embodichain.lab.sim.scene.physics import capture_physics_properties from .engine import ExpansionAssignment @@ -65,6 +68,14 @@ def execute_batch( for assignment in assigned } bridges, services = {}, {} + factories, adapters = {}, [] + extension = ctx.extensions + if extension.plan_transform_factory is not None: + ctx.source_artifacts = { + key: value + for key, value in ctx.source_artifacts.items() + if not key.startswith("plan_") + } ctx.bridges, ctx.services = bridges, services phase_started = time.monotonic() prototype_profile = None @@ -84,6 +95,44 @@ def execute_batch( record, ) in assignments.items(): ordinal = ctx.requests[row].recipe.context.ordinal + if extension.plan_transform_factory is not None: + if ( + profile is not None + or env.task_program_adapter.configured_nominal_sources + or motion_profile is not None + ): + raise ValueError( + "an extension transform cannot replace a configured nominal/motion source" + ) + request = ctx.requests[row] + factory = extension.plan_transform_factory( + env, + ExpansionRowContext( + row, + identity, + ordinal, + request.attempt_id, + directory, + SceneCase(**record["case"]), + request.recipe, + ), + ) + if factory is None: + raise ValueError("plan_transform_factory returned no factory") + factories[row] = factory + adapter = ( + env.task_program_adapter + if cfg.batch_size == 1 + else env.task_program_adapter.for_env_ids((row,)) + ) + if cfg.batch_size != 1: + adapters.append(adapter) + bridges[row] = adapter.create_bridge( + program, + plan_transform_factory=factory, + isolate_policy_sessions=True, + ) + continue if profile is None: from embodichain.lab.task_program.integrations.demo_skill import ( _ConfiguredDemoSkillSource, @@ -168,9 +217,43 @@ def mark_started(row): ), ) timings["execute"] += time.monotonic() - phase_started + if factories: + expansions, accepted, reasons = ( + [], + list(result.accepted), + list(result.reasons), + ) + for index, row in enumerate(result.env_ids): + factory = factories[row] + records = tuple(factory.records) + assignments[row][4]["expansion"] = [ + record.to_metadata() for record in records + ] + portable = [] + for number, record in enumerate(records): + trace = record.to_metadata() + if "plan_artifact" in trace: + key = f"plan_{row}_{number}" + ctx.source_artifacts[key] = trace.pop("plan_artifact") + trace["plan_artifact_key"] = key + portable.append(trace) + expansions.append(tuple(portable)) + if extension.require_plan_transform and accepted[index] and not records: + accepted[index], reasons[index] = ( + False, + "requested_operator_not_applied", + ) + result = replace( + result, + expansion_records=tuple(expansions), + accepted=tuple(accepted), + reasons=tuple(reasons), + ) physics_after = capture_physics_properties(view) episodes = GymEpisodeAssembler(ctx).assemble( assignments, collector, services, result, physics_after ) ctx.services, ctx.bridges = services, bridges + for adapter in adapters: + adapter.close() return tuple(episodes[assignment.env_id] for assignment in assigned) diff --git a/embodichain/lab/expansion/acceptance.py b/embodichain/lab/expansion/acceptance.py new file mode 100644 index 0000000000..71e8220df4 --- /dev/null +++ b/embodichain/lab/expansion/acceptance.py @@ -0,0 +1,611 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Shared measured geometry/contact acceptance without task-owned World control.""" + +from __future__ import annotations + +from collections import deque +from pathlib import Path +from typing import Any, TYPE_CHECKING +from collections.abc import Mapping, Sequence +from types import SimpleNamespace +import xml.etree.ElementTree as ET +import numpy as np +import torch +from embodichain.data_pipeline.recording.media import _atomic_json as atomic_json + +if TYPE_CHECKING: + from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv + from embodichain.lab.gym.envs.types import ControllerAction + from embodichain.lab.sim.scene import SceneState + +__all__ = ["MeasuredExpansionValidator"] + + +class _GeometryRow: + """Independently check measured task predicates and complete physical geometry.""" + + def _initialize_task_checks(self, env, configuration, output): + from embodichain.lab.task_program.integrations.feasibility import ( + MeasuredTaskMonitor, + ) + + self.env, self.configuration, self.output = env, configuration, output + self.monitor = MeasuredTaskMonitor( + configuration["final_checks"], configuration["events"], env_id=self.env_id + ) + for condition in configuration["initial_checks"]: + self.monitor._validate(condition) + self.initial, self.terminal, self.results = {}, {}, {} + + @staticmethod + def contact_permissions(env, configuration, known): + """Resolve authored contacts and mechanically adjacent robot assemblies.""" + # Collapse fixed URDF assemblies before deciding mechanical adjacency. + model = ET.parse(env.robot.cfg.fpath).getroot() + joints = model.findall("joint") + links = {link.get("name") for link in model.findall("link")} + groups = {link: link for link in links} + + def group(link): + while groups[link] != link: + link = groups[link] + return link + + for joint in joints: + if joint.get("type") == "fixed": + parent, child = joint.find("parent").get("link"), joint.find( + "child" + ).get("link") + groups[group(child)] = group(parent) + adjacent = { + frozenset( + ( + group(j.find("parent").get("link")), + group(j.find("child").get("link")), + ) + ) + for j in joints + } + physical_links = sorted( + link for link in links if f"{env.robot.uid}/{link}" in known + ) + ignored = [ + (f"{env.robot.uid}/{left}", f"{env.robot.uid}/{right}") + for i, left in enumerate(physical_links) + for right in physical_links[i + 1 :] + if group(left) == group(right) + or frozenset((group(left), group(right))) in adjacent + ] + children = {j.get("name"): j.find("child").get("link") for j in joints} + root_groups = {group(link) for link in links - set(children.values())} + roots = {link for link in physical_links if group(link) in root_groups} + + def expand(name): + if name == "@root": + return [ + f"{env.robot.uid}/{link}" + for link in sorted(roots) + if f"{env.robot.uid}/{link}" in known + ] + if name.startswith("@"): + return [ + f"{env.robot.uid}/{children[joint]}" + for joint in env.robot.control_parts[name[1:]] + ] + return [name] + + def pairs(values): + return tuple( + (a, b) + for left, right in values + for a in expand(left) + for b in expand(right) + ) + + ignored.extend(pairs(configuration["mounting_contacts"])) + allowed = pairs(configuration["allowed_contacts"]) + if any(not set(pair) <= known for pair in (*ignored, *allowed)): + raise ValueError("Contact permissions reference an absent physical frame") + # Match the physical model's authored self-collision policy. Keeping + # robot/scene checks does not require all internal robot shape pairs. + if env.robot.cfg.root_props.self_collision_enabled is False: + robot_frames = sorted( + frame for frame in known if frame.startswith(env.robot.uid + "/") + ) + ignored.extend( + (a, b) + for i, a in enumerate(robot_frames) + for b in robot_frames[i + 1 :] + ) + return ignored, allowed + + def __init__( + self, env, configuration: dict, output: Path, *, device="cpu", env_id=0 + ): + self.env_id = env_id + from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( + collision_bodies_from_simulation, + ) + from embodichain.lab.sim.scene.feasibility import NewtonCollisionChecker + + self._initialize_task_checks(env, configuration, output) + bodies = collision_bodies_from_simulation(env, env_id=self.env_id) + known = {body.frame_uid for body in bodies} + ignored, self.allowed_contacts = self.contact_permissions( + env, configuration, known + ) + checker = NewtonCollisionChecker( + bodies, ignored_pairs=ignored, device=device, max_shapes=512 + ) + self.checkers = [(checker, self.allowed_contacts, known)] + atomic_json( + output / "collision-geometry.json", + { + "shape_count": len(bodies), + "frames": sorted(known), + "query_count": len(self.checkers), + "self_collision_enabled": env.robot.cfg.root_props.self_collision_enabled, + }, + ) + self.moving = tuple( + uid + for uid in env.sim.get_rigid_object_uid_list() + if env.sim.get_rigid_object(uid).body_type == "dynamic" + ) + + def prepare(self, snapshot=None): + self.monitor.reset(self.env) + self.initial = { + self.env_id: all( + self.monitor.predicate(self.env, c) + for c in self.configuration["initial_checks"] + ) + and not all( + self.monitor.predicate(self.env, c) + for c in self.configuration["final_checks"] + ) + } + self.terminal.clear() + self.results.clear() + + def sample(self, ids, action, snapshot=None): + from embodichain.utils.math import matrix_from_quat + + self.monitor.observe(self.env, action) + self.terminal[self.env_id] = self.monitor.validation(self.env) + # Read the measured link buffer once and convert the whole arm in one + # batch. get_link_pose() otherwise repeats these allocations and + # quaternion conversions separately for every physical/visual link. + robot = self.env.robot + poses = robot.body_data.body_link_pose[self.env_id] + matrices = torch.eye(4, dtype=poses.dtype, device=poses.device).repeat( + len(robot.link_names), 1, 1 + ) + matrices[:, :3, :3] = matrix_from_quat(poses[:, 3:]) + matrices[:, :3, 3] = poses[:, :3] + matrices = matrices.detach().cpu().numpy() + frames = { + f"{robot.uid}/{link}": matrix + for link, matrix in zip(robot.link_names, matrices) + } + frames.update( + { + uid: self.env.sim.get_rigid_object(uid) + .get_local_pose(to_matrix=True)[self.env_id] + .detach() + .cpu() + .numpy() + for uid in self.env.sim.get_rigid_object_uid_list() + } + ) + frames["default_plane"] = np.eye(4) + for checker, contacts, aliases in self.checkers: + report, _ = checker.check( + frames, + allowed_contacts=contacts, + moving_objects=tuple(uid for uid in self.moving if uid in aliases), + ) + if self.env_id not in self.results or report.status != "passed": + self.results[self.env_id] = SimpleNamespace( + status=report.status, + reason=f"{report.reason}; pair={checker.last_pair}", + ) + if report.status != "passed": + metadata = action.metadata.get("row_actions", {}).get( + str(self.env_id), action.metadata + ) + atomic_json( + self.output / "collision-failure.json", + { + "reason": self.results[self.env_id].reason, + "action": { + key: str(value) + for key, value in metadata.items() + if isinstance(value, (str, int, float, bool)) + }, + }, + ) + break + + def close(self): + for checker, _, _ in self.checkers: + checker.close() + self.checkers.clear() + + +class _ContactRow(_GeometryRow): + """Inspect actual physics contacts, including every control substep. + + Unlike the independent Newton query, this backend retains native triangle + meshes. Unknown actors, unavailable impulses and dropped rows fail closed. + The optional final hold audit additionally requires both physical fingers + throughout the final measured control samples and bounds object drift. + """ + + def __init__(self, env, configuration, output, *, sensor, env_id=0): + self.env_id = env_id + self._initialize_task_checks(env, configuration, output) + self.active, self._bad, self.substeps, self._interval_samples = ( + False, + None, + 0, + 0, + ) + self.hold = configuration.get("contact_hold") + count = ( + round(self.hold["duration_s"] * env.control_frequency) + 1 + if self.hold + else 1 + ) + self.samples = deque(maxlen=count) + self.sensor = sensor + self.frames = {} + for link, actor in zip( + env.robot.link_names, + self.sensor.get_actor_ids(env.robot.uid, env.robot.link_names)[ + self.env_id + ].tolist(), + ): + self.frames[actor] = f"{env.robot.uid}/{link}" + for uid in (*env.sim.get_rigid_object_uid_list(), "default_plane"): + self.frames[int(self.sensor.get_actor_ids(uid)[self.env_id, 0])] = uid + ignored, allowed = self.contact_permissions( + env, configuration, set(self.frames.values()) + ) + self.allowed = {frozenset(pair) for pair in (*ignored, *allowed)} + self.moving = {f"{env.robot.uid}/{link}" for link in env.robot.link_names} | { + uid + for uid in env.sim.get_rigid_object_uid_list() + if env.sim.get_rigid_object(uid).body_type == "dynamic" + } + atomic_json( + output / "collision-geometry.json", + { + "backend": "native_contacts", + "geometry": "native physical shapes, including triangle meshes", + "frames": sorted(self.frames.values()), + "substep_sampling": True, + "max_contacts_per_env": 8192, + "self_collision_enabled": env.robot.cfg.root_props.self_collision_enabled, + }, + ) + + def reset(self, env_ids=None): + self.active, self._bad, self.substeps, self._interval_samples = ( + False, + None, + 0, + 0, + ) + self.samples.clear() + + def prepare(self, snapshot=None): + super().prepare(snapshot) + self.reset() + self.active = True + + def begin_control_step(self): + self._bad = None + self._interval_samples = 0 + + def before_sample(self): + return None + + def _hold_report(self): + report = { + "samples": len(self.samples), + "required_samples": self.samples.maxlen, + "physics_substeps": self.substeps, + } + if len(self.samples) != self.samples.maxlen: + return {**report, "passed": False} + poses = np.asarray([sample[0] for sample in self.samples]) + from scipy.spatial.transform import Rotation + + rotations = Rotation.from_quat(poses[:, 3:]) + report.update( + both_fingers_samples=sum(all(sample[1]) for sample in self.samples), + max_translation_drift_m=float( + np.linalg.norm(poses[:, :3] - poses[0, :3], axis=1).max() + ), + max_rotation_drift_rad=float( + (rotations[0].inv() * rotations).magnitude().max() + ), + ) + report["passed"] = ( + report["both_fingers_samples"] == self.samples.maxlen + and report["max_translation_drift_m"] + <= self.hold["max_translation_drift_m"] + and report["max_rotation_drift_rad"] <= self.hold["max_rotation_drift_rad"] + ) + return report + + def sample(self, ids, action, snapshot=None): + from embodichain.lab.expansion.contracts import ( + ValidationCheck, + ValidationResult, + ) + + if not self._interval_samples: + self._bad = "native contact substeps were not sampled" + if self.env_id not in self.results or self._bad: + self.results[self.env_id] = SimpleNamespace( + status="failed" if self._bad else "passed", + reason=self._bad or "all measured native contacts are permitted", + ) + if self._bad: + atomic_json(self.output / "collision-failure.json", {"reason": self._bad}) + self.monitor.observe(self.env, action) + terminal = self.monitor.validation(self.env) + if self.hold: + data = self.sensor.get_data() + pairs = data["user_ids"][self.env_id][ + data["is_valid"][self.env_id] & data["impulse_valid"][self.env_id] + ] + book = int(self.sensor.get_actor_ids(self.hold["entity"])[self.env_id, 0]) + fingers = self.sensor.get_actor_ids(self.env.robot.uid, self.hold["links"])[ + self.env_id + ].tolist() + touching = [ + bool( + ((pairs == book).any(dim=-1) & (pairs == finger).any(dim=-1)).any() + ) + for finger in fingers + ] + pose = ( + self.env.sim.get_rigid_object(self.hold["entity"]) + .get_local_pose()[self.env_id] + .tolist() + ) + self.samples.append((pose, touching)) + report = ( + self._hold_report() + if terminal.accepted + else {"passed": False, "reason": "awaiting terminal hold"} + ) + terminal = ValidationResult( + ( + *terminal.checks, + ValidationCheck( + "task.contact_hold", + "passed" if report["passed"] else "failed", + str(report), + ), + ) + ) + if terminal.accepted: + atomic_json(self.output / "contact-hold.json", report) + self.terminal[self.env_id] = terminal + + def close(self): + if self.hold and self.samples: + obj = self.env.sim.get_rigid_object(self.hold["entity"]) + atomic_json( + self.output / "terminal-diagnostics.json", + { + "pose": obj.get_local_pose()[self.env_id].tolist(), + "body_state": obj.body_state[self.env_id].tolist(), + "predicates": [ + { + "condition": condition, + "passed": self.monitor.predicate(self.env, condition), + } + for condition in self.configuration["final_checks"] + ], + "hold": self._hold_report(), + "events": self.monitor.receipts, + }, + ) + self.active = False + + +class MeasuredExpansionValidator: + """Use one measured acceptance port for geometry or complete native contacts. + + Args: + environment: Caller-owned native Gym environment. + configuration: Task-owned initial_checks/final_checks/events, declared + allowed_contacts/mounting_contacts, and optional contact_hold with + entity, finger links, duration and translation/rotation drift limits. + output: Artifact directory for diagnostic and terminal evidence. + backend: geometry (independent Newton query) or native_contacts (actual + physical substeps including triangle meshes). Unavailable data rejects. + device: Numerical geometry-query device; never changes physics. + + The World, stepping and acceptance thresholds remain with the host/task. + Selected-row preparation leaves live peers' monitors and evidence intact. + """ + + def __init__( + self, + environment: EmbodiedEnv, + configuration: Mapping[str, Any], + output: str | Path, + *, + backend: str = "geometry", + device: str = "cpu", + ) -> None: + if backend not in ("geometry", "native_contacts"): + raise ValueError("backend must be geometry or native_contacts") + from embodichain.lab.gym.envs._json import json_safe_copy + + configuration = json_safe_copy( + configuration, field_name="measured acceptance configuration" + ) + self.env, self.rows, self.sensor = environment, {}, None + self._observer_registered = False + output = Path(output) + output.mkdir(parents=True, exist_ok=True) + self.initial, self.terminal, self.results = {}, {}, {} + self._closed = False + try: + if backend == "native_contacts": + from embodichain.lab.sim.sensors import ( + ContactSensorCfg, + ArticulationContactFilterCfg, + ContactPermissionChecker, + ) + + self.sensor_uid = "expansion_native_contacts" + if self.sensor_uid in environment.sensors: + raise ValueError( + "the measured contact validator already owns a sensor" + ) + self.sensor = environment.sim.add_sensor( + ContactSensorCfg( + uid=self.sensor_uid, + rigid_uid_list=environment.sim.get_rigid_object_uid_list(), + articulation_cfg_list=[ + ArticulationContactFilterCfg( + articulation_uid=environment.robot.uid + ) + ], + filter_need_both_actor=False, + max_contacts_per_env=8192, + ) + ) + environment.sensors[self.sensor_uid] = self.sensor + for row in range(environment.num_envs): + path = output if environment.num_envs == 1 else output / f"row-{row}" + path.mkdir(parents=True, exist_ok=True) + self.rows[row] = ( + _GeometryRow( + environment, configuration, path, device=device, env_id=row + ) + if self.sensor is None + else _ContactRow( + environment, configuration, path, sensor=self.sensor, env_id=row + ) + ) + if self.sensor is not None: + permissions = self.rows[0].allowed + self.checker = ContactPermissionChecker( + self.sensor, + [self.rows[row].frames for row in range(environment.num_envs)], + allowed_contacts=tuple( + ( + tuple(pair) + if len(pair) == 2 + else (next(iter(pair)), next(iter(pair))) + ) + for pair in permissions + ), + moving_frames=tuple(self.rows[0].moving), + ) + self.sensor.add_sampling_observer("expansion", self) + self._observer_registered = True + except BaseException: + self.close() + raise + + def reset(self, env_ids: Sequence[int] | None = None) -> None: + """Reset only the sensor-selected monitor rows.""" + ids = tuple(self.rows) if env_ids is None else tuple(int(i) for i in env_ids) + for row in ids: + self.rows[row].reset() if self.sensor is not None else None + + def prepare( + self, + snapshot: SceneState | None = None, + *, + env_ids: Sequence[int] | None = None, + ) -> None: + """Capture initial qualification after physical preparation/settling.""" + ids = tuple(self.rows) if env_ids is None else tuple(env_ids) + if ( + not ids + or len(set(ids)) != len(ids) + or any(type(row) is not int or row not in self.rows for row in ids) + ): + raise ValueError("prepare requires unique physical rows") + for row in ids: + check = self.rows[row] + check.prepare(snapshot) + self.initial[row] = check.initial[row] + self.terminal.pop(row, None) + self.results.pop(row, None) + + def before_sample(self): + return None + + def after_sample(self, dt: float, token: object) -> None: + """Inspect every physical sample once, reducing all rows together.""" + active = [check for check in self.rows.values() if check.active] + if not active: + return + summaries = self.checker.check().cpu().tolist() + for check in active: + check.substeps += 1 + check._interval_samples += 1 + code, actor_a, actor_b = summaries[check.env_id] + if code: + check._bad = f"native contact evidence rejected: code={code}; actors={actor_a},{actor_b}" + + def begin_control_step(self) -> None: + """Start a physical interval without discarding prior failure results.""" + for check in self.rows.values(): + if self.sensor is not None and check.active: + check.begin_control_step() + + def sample( + self, + ids: Sequence[int], + action: ControllerAction, + snapshot: SceneState | None = None, + ) -> None: + """Check measured task state and retain each row's first physical failure.""" + for row in ids: + check = self.rows[row] + check.sample((row,), action, snapshot) + self.terminal[row] = check.terminal[row] + self.results[row] = check.results[row] + if self.sensor is not None: + check._interval_samples = 0 + + def close(self) -> None: + """Detach owned observers before releasing resources; safe on failure.""" + if self._closed: + return + self._closed = True + for check in self.rows.values(): + check.close() + if self.sensor is not None: + if self._observer_registered: + self.sensor.remove_sampling_observer("expansion", expected=self) + self.env.sensors.pop(self.sensor_uid, None) + self.env.sim.remove_asset(self.sensor_uid) diff --git a/embodichain/lab/expansion/comparison.py b/embodichain/lab/expansion/comparison.py new file mode 100644 index 0000000000..e0c0540c52 --- /dev/null +++ b/embodichain/lab/expansion/comparison.py @@ -0,0 +1,681 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Measured reference/expansion comparison on a shared physics-free timeline.""" + +from __future__ import annotations + +from contextlib import ExitStack, AbstractContextManager +from collections.abc import Callable +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from types import MappingProxyType +import time +import numpy as np +from embodichain.data_pipeline.recording.media import _atomic_json as atomic_json +from embodichain.lab.expansion.persistence import _digest as file_digest +from embodichain.lab.visualization.markers import MarkerFramePublisher + +__all__ = [ + "MeasuredTrajectory", + "record_reference_trajectory", + "preview_expansion_comparison", +] + +GHOST_COLOR = (0.15, 0.8, 0.95, 0.35) + + +def _utc_now() -> str: + return datetime.now(timezone.utc).isoformat() + + +@dataclass(frozen=True) +class MeasuredTrajectory: + """One arena's measured poses; all frames include the initial boundary.""" + + name: str + robot_uid: str + joint_names: tuple[str, ...] + timestamps: np.ndarray + qpos: np.ndarray + root_poses: np.ndarray + object_poses: dict[str, np.ndarray] + + def __post_init__(self) -> None: + for name in ("timestamps", "qpos", "root_poses"): + object.__setattr__(self, name, np.array(getattr(self, name), copy=True)) + object.__setattr__( + self, + "object_poses", + MappingProxyType( + { + key: np.array(value, copy=True) + for key, value in self.object_poses.items() + } + ), + ) + count = len(self.timestamps) + if ( + count < 2 + or self.timestamps.shape != (count,) + or self.timestamps[0] != 0 + or not np.all(np.diff(self.timestamps) > 0) + or not self.joint_names + or len(set(self.joint_names)) != len(self.joint_names) + or self.qpos.shape != (count, len(self.joint_names)) + ): + raise ValueError("Preview requires a nonempty, ordered measured trajectory") + arrays = ( + self.timestamps, + self.qpos, + self.root_poses, + *self.object_poses.values(), + ) + if any(not np.isfinite(array).all() for array in arrays): + raise ValueError("Preview trajectory must contain finite measurements") + for poses in (self.root_poses, *self.object_poses.values()): + if poses.shape != (count, 7) or not np.allclose( + np.linalg.norm(poses[:, 3:], axis=1), 1, atol=1e-5, rtol=0 + ): + raise ValueError("Preview poses must be xyz + normalized xyzw") + for array in ( + self.timestamps, + self.qpos, + self.root_poses, + *self.object_poses.values(), + ): + array.flags.writeable = False + + def frame_at(self, elapsed: float) -> int: + """Select the latest measured boundary, holding the final pose at the end.""" + return int( + np.clip( + np.searchsorted(self.timestamps, elapsed, side="right") - 1, + 0, + len(self.timestamps) - 1, + ) + ) + + @classmethod + def load_reference(cls, path: Path) -> MeasuredTrajectory: + """Read a pickle-free reference captured by record_reference_trajectory.""" + with np.load(path, allow_pickle=False) as data: + return cls( + name="original", + robot_uid=str(data["robot_uid"]), + joint_names=tuple(data["joint_names"].tolist()), + timestamps=data["timestamps"].copy(), + qpos=data["qpos"].copy(), + root_poses=data["root_poses"].copy(), + object_poses={ + str(uid): data[f"object_{index}"].copy() + for index, uid in enumerate(data["object_uids"]) + }, + ) + + @classmethod + def load_episode(cls, storage_id: str, *, robot_uid: str) -> MeasuredTrajectory: + """Read only an accepted native episode, preserving full joint order.""" + from embodichain.lab.expansion import load_expansion_episode + + episode = load_expansion_episode(storage_id) + if not episode.validation.accepted: + raise ValueError("comparison requires a qualified native episode") + metadata, observations = episode.metadata, episode.observations + robot = next( + item for item in metadata["initial_state"] if item["uid"] == robot_uid + ) + root_key = next( + field["key"] + for field in metadata["scene_state_fields"] + if field["entity_uid"] == robot_uid and field["field"] == "pose" + ) + + def array(value): + return value.detach().cpu().numpy().copy() + + return cls( + name=episode.episode_id, + robot_uid=robot_uid, + joint_names=tuple(robot["joint_names"]), + timestamps=array(episode.timestamps), + qpos=array(observations["full_joint_positions"]), + root_poses=array(observations[root_key]), + object_poses={ + key[len("rigid/") : -len("/state")]: array(value)[:, :7] + for key, value in observations.items() + if key.startswith("rigid/") and key.endswith("/state") + }, + ) + + +def record_reference_trajectory(env: object, path: Path) -> None: + """Execute the unmodified expert once and archive its measured scene poses.""" + from embodichain.lab.gym.envs.demo import execute_demo_episode + from embodichain.lab.sim.scene import SceneView, capture_state + + view = SceneView(env.sim, env_ids=(0,)) + frames = [capture_state(view).batches[0]] + + def observe(*_args): + frames.append(capture_state(view).batches[0]) + + episode = execute_demo_episode(env, step_observer=observe) + atomic_json(path.with_suffix(".json"), episode.to_metadata()) + if not episode.completed or not episode.all_success: + raise RuntimeError(f"Nominal preview expert failed: {episode.terminal_reason}") + robot_index = next( + index for index, item in enumerate(frames[0]) if item.uid == env.robot.uid + ) + robot = frames[0][robot_index] + objects = [ + (index, item.uid) + for index, item in enumerate(frames[0]) + if item.kind == "rigid_object" + ] + arrays = { + "robot_uid": np.asarray(robot.uid), + "joint_names": np.asarray(robot.joint_names), + "timestamps": np.arange(len(frames), dtype=np.float64) * env.step_dt, + "qpos": np.asarray([frame[robot_index].qpos for frame in frames]), + "root_poses": np.asarray([frame[robot_index].pose for frame in frames]), + "object_uids": np.asarray([uid for _, uid in objects]), + } + arrays.update( + { + f"object_{ordinal}": np.asarray([frame[index].pose for frame in frames]) + for ordinal, (index, _) in enumerate(objects) + } + ) + np.savez_compressed(path, **arrays) + # Validate the exact archive before another World is created. + MeasuredTrajectory.load_reference(path) + + +def _object_prototype(obj): + """Use the physical object's actual visual shape and scale exactly once.""" + from embodichain.lab.visualization.markers import MarkerPrototypeCfg + from embodichain.lab.sim.shapes import CubeCfg, MeshCfg, SphereCfg + + shape, scale = obj.cfg.shape, np.asarray(obj.cfg.body_scale) + options = {"color": GHOST_COLOR, "scene_lighting": True, "unlit": False} + if isinstance(shape, CubeCfg): + return MarkerPrototypeCfg( + shape="box", scale=tuple(scale * shape.size), **options + ) + if isinstance(shape, SphereCfg): + return MarkerPrototypeCfg( + shape="sphere", scale=tuple(scale * 2 * shape.radius), **options + ) + if isinstance(shape, MeshCfg) or obj.cfg.source is not None: + # Use the simulator's materialized visual geometry: GLB loading may + # convert axes, while USD sources can author their own mesh transforms. + vertices = obj.get_vertices(env_ids=[0], scale=False)[0].cpu().numpy() + faces = obj.get_triangles(env_ids=[0])[0].cpu().numpy() + return MarkerPrototypeCfg( + shape="mesh", vertices=vertices, faces=faces, scale=tuple(scale), **options + ) + raise ValueError(f"Unsupported preview object shape for {obj.uid}") + + +def _precompute_link_poses(clip, robot, asset_path): + """Compute complete-arm FK once; browsing never runs FK or loads episodes.""" + import torch + import pytorch_kinematics as pk + from scipy.spatial.transform import Rotation + + chain = pk.build_chain_from_urdf(Path(asset_path).read_bytes()) + indices = [clip.joint_names.index(name) for name in robot.joint_names] + poses = [] + with torch.no_grad(): + for start in range(0, len(clip.timestamps), 256): + qpos = torch.as_tensor( + clip.qpos[start : start + 256, indices], dtype=torch.float32 + ) + fk = chain.forward_kinematics(qpos) + poses.append( + torch.stack( + [fk[name].get_matrix() for name in robot.link_names], dim=1 + ).numpy() + ) + roots = np.broadcast_to(np.eye(4), (len(clip.timestamps), 4, 4)).copy() + roots[:, :3, :3] = Rotation.from_quat(clip.root_poses[:, 3:]).as_matrix() + roots[:, :3, 3] = clip.root_poses[:, :3] + return roots[:, None] @ np.concatenate(poses) + + +class _ReferencePlayer: + """Publish measured entities through the native render-state owner.""" + + def __init__(self, env, reference): + from embodichain.lab.sim.scene import SceneView, capture_state + + if tuple(env.robot.joint_names) != reference.joint_names: + raise ValueError("Preview robot joint order differs from recording") + self.view = SceneView(env.sim, env_ids=(0,)) + self.initial = capture_state(self.view) + self.reference = reference + + def queue(self, frame): + from dataclasses import replace + from embodichain.lab.sim.scene import restore_render_state + + reference = self.reference + entities = [] + for state in self.initial.batches[0]: + if state.uid == reference.robot_uid: + state = replace( + state, + pose=tuple(map(float, reference.root_poses[frame])), + qpos=tuple(map(float, reference.qpos[frame])), + ) + elif state.uid in reference.object_poses: + state = replace( + state, + pose=tuple(map(float, reference.object_poses[state.uid][frame])), + ) + entities.append(state) + restore_render_state( + self.view, replace(self.initial, batches=(tuple(entities),)) + ) + + def close(self): + from embodichain.lab.sim.scene import restore_render_state + + restore_render_state(self.view, self.initial) + + +def _accepted_candidates(operators): + from embodichain.lab.expansion import ArtifactEpisodeSink + + return [ + { + "operator": name, + "storage_id": receipt.storage_id, + "episode_id": receipt.episode_id, + } + for name, report in operators.items() + if "directory" in report + for receipt in ArtifactEpisodeSink(report["directory"]).inspect() + ] + + +def preview_expansion_comparison( + environment_factory: Callable[[], AbstractContextManager], + reference_path: Path, + operators: dict[str, dict] | None, + *, + renderer: str, + scene_entities: tuple[str, ...], + output: Path, + collect: Callable | None = None, + max_frames: int | None = None, + frame_observer: Callable | None = None, + expected_trajectories: int | None = None, +) -> dict: + """Browse accepted trajectories; N advances, Space pauses and Q closes. + + With a collection callback, warm model resources before opening the window, + then delegate collection and load only its qualified measured trajectories. + Only the selected expansion is visible; N preserves playback time and + pause state. Rendering cannot alter episodes or advance physics. + + Args: + environment_factory: Context manager factory for the caller's native + environment. The viewer displays physical row zero; other rows are + retained with World-wide physics disabled during playback. + reference_path: Pickle-free measured reference produced by the recorder. + operators: Named artifact directories containing accepted native receipts. + renderer: Renderer label in viewer evidence; the factory configures it. + scene_entities: Recorded objects to display with the selected robot ghost. + output: Viewer manifest and interaction evidence directory. + collect: Optional callback receiving simulation, window, output and status; + returns named artifact directories. Collection ownership stays external. + max_frames: Optional display-frame budget for bounded playback. + frame_observer: Optional callback receiving environment, frame number, + selected index and shared elapsed time after publication. + expected_trajectories: Required preload count for early-window collection. + + Returns: + Playback outcome, selection/frame counts and actual physics-step delta. + """ + from collections import deque + from dexsim.engine import InputControl + from dexsim.types import InputKey + from embodichain.lab.visualization.markers import ( + RobotMarkers, + RobotMarkersAppearanceCfg, + RobotMarkersCfg, + VisualizationMarkers, + VisualizationMarkersCfg, + ) + import os + + output = Path(output) + output.mkdir(parents=True, exist_ok=True) + if max_frames is not None and (type(max_frames) is not int or max_frames < 1): + raise ValueError("max_frames must be a positive integer") + if collect is not None and ( + type(expected_trajectories) is not int or expected_trajectories < 1 + ): + raise ValueError("Early preview requires the expected trajectory count") + with environment_factory() as env: + sim = env.sim + physics_enabled = sim.physics_enabled + sim.enable_physics(False) + physics_steps_before = sim.physics_step_index + with ExitStack() as cleanup: + cleanup.callback(sim.enable_physics, physics_enabled) + players = cleanup.enter_context(ExitStack()) + markers = MarkerFramePublisher(sim, xray=True) + cleanup.callback(markers.close) + robot = RobotMarkers( + RobotMarkersCfg( + name="expansion_robot", + asset_path=env.robot.cfg.fpath, + coordinate_space="env", + appearance=RobotMarkersAppearanceCfg( + color=GHOST_COLOR[:3], opacity=GHOST_COLOR[3] + ), + ), + markers, + ) + objects = VisualizationMarkers( + VisualizationMarkersCfg( + prim_path="expansion_objects", + coordinate_space="env", + markers={ + uid: _object_prototype(sim.get_rigid_object(uid)) + for uid in scene_entities + }, + ), + markers, + ) + + def open_window(): + if not sim.open_window(): + raise RuntimeError( + "The requested native expansion preview did not open" + ) + cleanup.callback(sim.close_window) + window = sim.get_world().get_windows() + center = np.mean( + [env.robot.get_local_pose()[0, :3].detach().cpu().numpy()] + + [ + sim.get_rigid_object(uid) + .get_local_pose()[0, :3] + .detach() + .cpu() + .numpy() + for uid in scene_entities + ], + axis=0, + ) + center[2] += 0.2 + window.set_look_at( + center + [1.6, -1.8, 1.1], center, np.array([0.0, 0.0, 1.0]) + ) + return window + + window = None + window_opened_at = None + if collect is not None: + # Allocate all native mesh instances before the render loop. + # Their hidden placeholder poses require no recorded data/FK. + robot.visualize_link_poses( + np.broadcast_to( + np.eye(4), + (1, expected_trajectories, len(robot.link_names), 4, 4), + ), + env_ids=(0,), + ) + count = expected_trajectories * len(scene_entities) + objects.visualize( + translations=np.zeros((count, 3)), + orientations=np.tile([0.0, 0.0, 0.0, 1.0], (count, 1)), + marker_indices=np.tile( + np.arange(len(scene_entities)), expected_trajectories + ), + ) + for name, width in ( + ("expansion_robot", robot.num_visuals), + ("expansion_objects", len(scene_entities)), + ): + markers.groups[name].update( + visible=np.zeros(expected_trajectories * width, dtype=bool), + env_ids=(0,), + ) + markers.publish() + sim.sync_render_state() + window = open_window() + window_opened_at = _utc_now() + status = { + "state": "collecting", + "renderer": renderer, + "pid": os.getpid(), + "window_opened_at": window_opened_at, + "window_open": True, + "expected_trajectories": expected_trajectories, + "preloaded_robots": expected_trajectories, + } + atomic_json(output / "window.json", status) + window.set_window_title("Expansion preparing | reference | Q cancel") + operators = collect(sim, window, output, status) + atomic_json(output / "status.json", {**status, "state": "loading"}) + + reference = MeasuredTrajectory.load_reference(reference_path) + candidates = _accepted_candidates(operators) + atomic_json( + output / "manifest.json", + { + "reference": str(reference_path), + "reference_sha256": file_digest(reference_path), + "candidates": candidates, + }, + ) + if not candidates: + result = { + "state": "empty", + "trajectories": 0, + "reason": "no_accepted_episodes", + } + atomic_json(output / "status.json", result) + return result + clips = [ + MeasuredTrajectory.load_episode( + candidate["storage_id"], robot_uid=reference.robot_uid + ) + for candidate in candidates + ] + if any( + set(clip.joint_names) != set(reference.joint_names) for clip in clips + ): + raise ValueError("Preview expansion has incompatible robot joints") + duration = max(clip.timestamps[-1] for clip in [reference, *clips]) + 0.5 + player = _ReferencePlayer(env, reference) + players.callback(player.close) + selected = 0 + links = [ + _precompute_link_poses(clip, robot, env.robot.cfg.fpath) + for clip in clips + ] + last_frame = None + + def show_frame(elapsed): + nonlocal last_frame + original_frame = reference.frame_at(elapsed) + expanded_frames = [clip.frame_at(elapsed) for clip in clips] + current = (original_frame, *expanded_frames, selected) + if current == last_frame: + sim.get_world().update(0.0) + return original_frame, expanded_frames + player.queue(original_frame) + robot.visualize_link_poses( + np.stack( + [poses[frame] for poses, frame in zip(links, expanded_frames)] + )[None], + env_ids=(0,), + ) + poses = np.stack( + [ + clip.object_poses[uid][frame] + for clip, frame in zip(clips, expanded_frames) + for uid in scene_entities + ] + ) + objects.visualize( + translations=poses[:, :3], + orientations=poses[:, 3:], + marker_indices=np.tile(np.arange(len(scene_entities)), len(clips)), + ) + for name, width in ( + ("expansion_robot", robot.num_visuals), + ("expansion_objects", len(scene_entities)), + ): + markers.groups[name].update( + visible=np.repeat(np.arange(len(clips)) == selected, width), + env_ids=(0,), + ) + markers.publish() + # Publish once, after full-arm, object and reference state writes. + sim.sync_render_state() + # Publication only flushes render uploads in the pinned SDK; + # poll window input and present even when every frame changes. + sim.get_world().update(0.0) + last_frame = current + return original_frame, expanded_frames + + # Early windows reuse the warmed meshes; recorded-only previews + # create their first instances before starting the render loop. + show_frame(0) + if window is None: + window = open_window() + window_opened_at = _utc_now() + switches, frames, paused = 0, 0, False + elapsed, previous = 0.0, time.monotonic() + running = True + pressed, held, polled = deque(), set(), set() + preview_keys = { + key.value + for key in ( + InputKey.SCANCODE_Q, + InputKey.SCANCODE_ESCAPE, + InputKey.SCANCODE_N, + InputKey.SCANCODE_SPACE, + ) + } + + class PreviewInput(InputControl): + def on_key_down(self, key): + if key in preview_keys and key not in held: + held.add(key) + pressed.append(key) + + def on_key_up(self, key): + held.discard(key) + + control = PreviewInput() + window.add_input_control(control) + cleanup.callback(window.remove_input_control, control) + result = { + "state": "playing", + "trajectories": len(candidates), + "renderer": renderer, + "robot_layers": 1, + "object_instances": len(scene_entities), + "preloaded_robots": len(clips), + "preloaded_object_instances": len(clips) * len(scene_entities), + "marker_render_mode": "overlay", + "pid": os.getpid(), + "world_object_id": id(sim.get_world()), + "num_envs": sim.num_envs, + "window_opened_at": window_opened_at, + } + + def publish(): + result.update( + selected_index=selected, + operator=candidates[selected]["operator"], + episode_id=candidates[selected]["episode_id"], + switches=switches, + frames=frames, + state="paused" if paused else "playing", + original_frame=original_frame, + expanded_frame=expanded_frames[selected], + elapsed_s=elapsed, + expanded_frames=expanded_frames, + marker_publications=markers.publications, + solid_qpos=env.robot.get_qpos()[0].detach().cpu().tolist(), + ) + atomic_json(output / "status.json", result) + window.set_window_title( + f"Expansion {selected + 1}/{len(candidates)} | {candidates[selected]['operator']} | N next | Space pause | Q close" + ) + + while ( + running + and sim.get_world().is_window_initialized() + and (max_frames is None or frames < max_frames) + ): + started = time.monotonic() + changed = frames == 0 + # Queue native key edges so a short tap survives a slow render + # frame. A newly opened viewport may not dispatch control + # callbacks before its first click, so retain held-key edges too. + down = {key for key in preview_keys if sim.get_world().key_state(key)} + for key in down - polled: + if key not in held: + held.add(key) + pressed.append(key) + held.difference_update(polled - down) + polled = down + while pressed: + key = pressed.popleft() + if key in ( + InputKey.SCANCODE_Q.value, + InputKey.SCANCODE_ESCAPE.value, + ): + running = False + elif key == InputKey.SCANCODE_N.value: + selected = (selected + 1) % len(candidates) + switches += 1 + changed = True + elif key == InputKey.SCANCODE_SPACE.value: + paused, changed = not paused, True + if not running: + break + if not paused: + elapsed += started - previous + previous = started + elapsed %= duration + original_frame, expanded_frames = show_frame(elapsed) + frames += 1 + if frame_observer is not None: + frame_observer(env, frames, selected, elapsed) + if not sim.get_world().is_window_initialized(): + break + if changed: + publish() + time.sleep(max(0.0, 1 / 30 - (time.monotonic() - started))) + result.update( + state="closed", + frames=frames, + switches=switches, + physics_steps=sim.physics_step_index - physics_steps_before, + ) + atomic_json(output / "status.json", result) + return result diff --git a/embodichain/lab/expansion/host.py b/embodichain/lab/expansion/host.py index 7c705325c7..2bb2bcfd5b 100644 --- a/embodichain/lab/expansion/host.py +++ b/embodichain/lab/expansion/host.py @@ -48,6 +48,7 @@ from ._gym_recipe import GymRecipeBuilder from ._gym_prepare import GymCohortPreparer from ._gym_execution import GymCohortExecutor +from .host_extensions import GymExpansionHostExtensions __all__ = ["GymExpansionHost"] @@ -93,12 +94,17 @@ def __init__( root: Path, journal: ExpansionJournal, source_artifacts: Mapping[str, object], + *, + extensions: GymExpansionHostExtensions | None = None, ) -> None: self._context = GymHostContext( cfg, report, root, journal, source_artifacts, cfg.batch_size ) + self._context.extensions = extensions or GymExpansionHostExtensions() + if not isinstance(self._context.extensions, GymExpansionHostExtensions): + raise TypeError("extensions must be GymExpansionHostExtensions") self._recipe_builder = GymRecipeBuilder(self._context) - self._context.recipe = self._recipe_builder.recipe + self._context.recipe = self.recipe self._preparer = GymCohortPreparer(self._context) self._executor = GymCohortExecutor(self._context) try: @@ -123,6 +129,9 @@ def _open(self) -> None: environment_cfg.record_trajectory = False environment_cfg.sim_cfg.headless = True _configure_sensor_capture(environment_cfg, capture_media=cfg.capture_media) + extensions = self._context.extensions + if extensions.collection_renderer is not None: + environment_cfg.sim_cfg.render_cfg.renderer = extensions.collection_renderer from embodichain.lab.sim.profiler import ProfilerCfg environment_cfg.profiler = ProfilerCfg( @@ -170,6 +179,17 @@ def _open(self) -> None: env, cfg.collision_profile, root / "collision" ) self._context.collision = collision + if extensions.validator_factory is not None: + if collision is not None: + raise ValueError("choose a collision profile or an extension validator") + self._context.collision = collision = extensions.validator_factory( + env, root + ) + if collision is None or not all( + callable(getattr(collision, method, None)) + for method in ("prepare", "sample", "close") + ): + raise TypeError("validator_factory must return a measured validator") profile = None if cfg.source == "real2sim": from embodichain.lab.task_program.integrations.simulation.real2sim_collection import ( @@ -208,6 +228,12 @@ def _open(self) -> None: self._context.collision = collision self._context.profile = profile self._context.scene_source = scene_source + if extensions.scene_source_factory is not None: + if scene_source is not None: + raise ValueError("choose a scene atlas or an extension scene source") + self._context.scene_source = extensions.scene_source_factory(env) + if not callable(getattr(self._context.scene_source, "candidate", None)): + raise TypeError("scene_source_factory must return a candidate source") self._context.motion_profile = motion_profile self._context.motion_recipes = motion_recipes self._context.names = names @@ -448,7 +474,9 @@ def profile(self, value: Any) -> None: def recipe(self, ordinal: int) -> ExpansionRecipe: """Sample a pinned recipe without mutating the World.""" - return self._recipe_builder.recipe(ordinal) + recipe = self._recipe_builder.recipe(ordinal) + transform = self._context.extensions.recipe_transform + return recipe if transform is None else transform(recipe) def prepare_batch( self, requests: tuple[RecipeAttempt, ...], session: ExpansionSession diff --git a/embodichain/lab/expansion/host_extensions.py b/embodichain/lab/expansion/host_extensions.py new file mode 100644 index 0000000000..5f4e54a0c4 --- /dev/null +++ b/embodichain/lab/expansion/host_extensions.py @@ -0,0 +1,112 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Non-owning public extension ports for the native Gym expansion host.""" + +from __future__ import annotations + +from dataclasses import dataclass +from collections.abc import Callable, Mapping +from pathlib import Path +from typing import Any, Protocol +from .contracts import CandidateIdentity, SceneCase, ValidationResult +from .recipes import ExpansionRecipe + +__all__ = ["ExpansionValidator", "ExpansionRowContext", "GymExpansionHostExtensions"] + + +class ExpansionValidator(Protocol): + """Measured validation port shared by geometry and native-contact checks. + + Unavailable evidence must reject. Implementations never step/reset the World; + the host calls prepare after settling and sample on every measured boundary. + """ + + initial: Mapping[int, bool] + terminal: Mapping[int, ValidationResult] + results: Mapping[int, Any] + + def prepare(self, snapshot: Any = None) -> None: + """Reset measured evidence after the host has settled its cohort.""" + ... + + def sample(self, ids: tuple[int, ...], action: Any, snapshot: Any = None) -> None: + """Observe the original control boundary and its physical substeps.""" + ... + + def close(self) -> None: + """Release only owned observers/resources; the host retains its World.""" + ... + + +@dataclass(frozen=True) +class ExpansionRowContext: + """Immutable identity supplied to a per-row plan-transform factory.""" + + env_id: int + identity: CandidateIdentity + ordinal: int + attempt_id: int + directory: Path + scene_case: SceneCase + recipe: ExpansionRecipe + + +@dataclass(frozen=True) +class GymExpansionHostExtensions: + """Runtime callbacks; construction, collection and persistence stay native. + + Args: + collection_renderer: Explicit headless collection renderer, or None for + the native sensor/media default. + scene_source_factory: Receives the live environment and returns a source + exposing candidate(ordinal); it cannot own another World. + validator_factory: Receives environment and artifact root; returns the + same measured port for either physical geometry or native contacts. + recipe_transform: Receives the native immutable recipe and returns its + task-owned operations. Preparation verifies it again before mutation. + plan_transform_factory: Receives environment and immutable row identity; + returns an ordinary Task Program transform factory. Its record metadata + and hashed plan attachments are archived by the native episode owner. + require_plan_transform: Reject completed programs without transform records. + """ + + collection_renderer: str | None = None + scene_source_factory: Callable[[Any], Any] | None = None + validator_factory: Callable[[Any, Path], ExpansionValidator] | None = None + recipe_transform: Callable[[ExpansionRecipe], ExpansionRecipe] | None = None + plan_transform_factory: Callable[[Any, ExpansionRowContext], Any] | None = None + require_plan_transform: bool = False + + def __post_init__(self) -> None: + if self.collection_renderer is not None and ( + type(self.collection_renderer) is not str + or not self.collection_renderer.strip() + ): + raise ValueError("collection_renderer must be a nonempty renderer name") + for name in ( + "scene_source_factory", + "validator_factory", + "recipe_transform", + "plan_transform_factory", + ): + value = getattr(self, name) + if value is not None and not callable(value): + raise TypeError(f"{name} must be callable") + if type(self.require_plan_transform) is not bool or ( + self.require_plan_transform and self.plan_transform_factory is None + ): + raise ValueError("required plan transforms need an explicit factory") diff --git a/embodichain/lab/sim/atomic_skills/policies.py b/embodichain/lab/sim/atomic_skills/policies.py index 22fb610e65..1a8170108f 100644 --- a/embodichain/lab/sim/atomic_skills/policies.py +++ b/embodichain/lab/sim/atomic_skills/policies.py @@ -19,7 +19,7 @@ from __future__ import annotations import math -from collections.abc import Callable +from collections.abc import Callable, Mapping from copy import deepcopy from dataclasses import dataclass, field, fields, is_dataclass from enum import Enum @@ -63,6 +63,15 @@ class MotionPolicy: strategy: Literal["motion_gen", "ik_interp"] = "ik_interp" """Motion strategy: ``motion_gen`` or ``ik_interp``.""" + phase_paths: Mapping[str, Literal["joint", "cartesian"]] = field( + default_factory=dict, kw_only=True + ) + """Explicit primitive phase paths; empty preserves each skill's defaults. + + PickUp reads pre_grasp/grasp/lift (and optional initial_lift); Place reads + pre_place/place/retreat. Other primitives retain their own declared paths. + """ + sample_count: int = 50 """Minimum trajectory sample count when the backend does not preserve samples.""" @@ -143,6 +152,22 @@ class MotionPolicy: """ def __post_init__(self) -> None: + if not isinstance(self.phase_paths, Mapping) or any( + type(name) is not str + or not name.strip() + or mode not in ("joint", "cartesian") + for name, mode in self.phase_paths.items() + ): + raise ValueError("phase_paths must map phase names to joint/cartesian") + if self.phase_paths and ( + self.strategy != "ik_interp" + or self.interpolation_mode != "fixed_grid" + or self.ik_seed_mode != "sequential" + ): + raise ValueError("phase_paths requires fixed-grid sequential ik_interp") + from embodichain.utils._owned_json import freeze_metadata + + object.__setattr__(self, "phase_paths", freeze_metadata(self.phase_paths)) if self.final_velocity_rejection not in {"hold", "mask_only"}: raise ValueError("final_velocity_rejection must be hold or mask_only.") segment_retries = self.segment_sample_count_retries diff --git a/embodichain/lab/sim/atomic_skills/primitives/pick_up.py b/embodichain/lab/sim/atomic_skills/primitives/pick_up.py index d582f6acda..c4cacf8801 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/pick_up.py +++ b/embodichain/lab/sim/atomic_skills/primitives/pick_up.py @@ -404,6 +404,7 @@ def _get_full_pickup_trajectory( # planner options were supplied. motion_options.sample_count = None waypoints = [pre_grasp_xpos, grasp_xpos, lift_xpos] + phase_names = ["pre_grasp", "grasp", "lift"] if options.initial_lift_height > 0.0: start_xpos = self.robot.compute_fk( qpos=start_arm_qpos, @@ -420,6 +421,12 @@ def _get_full_pickup_trajectory( start_xpos.new_tensor([0.0, 0.0, options.initial_lift_height]), ) waypoints.insert(0, initial_lift) + phase_names.insert(0, "initial_lift") + + if any(name in motion_policy.phase_paths for name in phase_names): + motion_options.waypoint_modes = tuple( + motion_policy.phase_paths.get(name, "joint") for name in phase_names + ) motion_result = self.motion_generator.generate( build_pose_plan_states(torch.stack(waypoints, dim=1)), diff --git a/embodichain/lab/sim/atomic_skills/primitives/place.py b/embodichain/lab/sim/atomic_skills/primitives/place.py index 8780f9e473..5e86696a95 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/place.py +++ b/embodichain/lab/sim/atomic_skills/primitives/place.py @@ -307,6 +307,13 @@ def _plan( # motion generator resolves backend defaults when no explicit # planner options were supplied. motion_options.sample_count = None + paths = request.motion_policy.phase_paths + if any(name in paths for name in ("pre_place", "place", "retreat")): + motion_options.waypoint_modes = ( + paths.get("pre_place", "joint"), + *(paths.get("place", "joint"),) * (down_xpos.shape[1] - 1), + *(paths.get("retreat", "joint"),) * back_xpos.shape[1], + ) motion_result = self.motion_generator.generate( build_pose_plan_states(torch.cat([down_xpos, back_xpos], dim=1)), options=motion_options, diff --git a/embodichain/lab/sim/motion/_phase_paths.py b/embodichain/lab/sim/motion/_phase_paths.py new file mode 100644 index 0000000000..d675fcb710 --- /dev/null +++ b/embodichain/lab/sim/motion/_phase_paths.py @@ -0,0 +1,110 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Explicit waypoint phase paths composed through the ordinary motion facade.""" + +from __future__ import annotations + +from dataclasses import replace +from itertools import groupby +from typing import TYPE_CHECKING +import torch +from .planners.utils import MoveType, PlanResult, RejectedMotionCandidate + +if TYPE_CHECKING: + from .motion_generator import MotionGenerator, MotionGenOptions + from .planners.utils import PlanState + +__all__: list[str] = [] + + +def generate_phase_paths( + generator: MotionGenerator, + targets: list[PlanState], + options: MotionGenOptions, + *, + defer_recovery: bool, +) -> PlanResult: + """Retain one declared grid while grouping consecutive path modes.""" + modes = options.waypoint_modes + if len(modes) != len(targets) or not all( + t.move_type is MoveType.EEF_MOVE for t in targets + ): + raise ValueError( + f"waypoint_modes must describe every Cartesian waypoint: modes={modes}, target_types={[state.move_type for state in targets]}" + ) + if ( + options.start_qpos is None + or options.sample_count is None + or options.sample_count <= len(targets) + ): + raise ValueError( + "phase paths require a start and at least one interval per waypoint" + ) + if type(defer_recovery) is not bool or ( + defer_recovery and "cartesian" not in modes + ): + raise ValueError("deferred phase recovery requires a Cartesian phase") + pieces, start, offset = [], options.start_qpos, 0 + for mode, group in groupby(modes): + stop = offset + len(tuple(group)) + intervals = (options.sample_count - 1) * stop // len(targets) - ( + options.sample_count - 1 + ) * offset // len(targets) + result = generator.generate( + targets[offset:stop], + options=replace( + options, + waypoint_modes=(), + start_qpos=start, + sample_count=intervals + 1, + is_linear=mode == "cartesian", + ), + defer_recovery=defer_recovery and mode == "cartesian", + ) + if result.positions is None or result.dt is None: + raise ValueError("phase path returned no timed trajectory") + pieces.append(result) + start = result.positions[:, -1] + offset = stop + success = torch.stack([piece.success for piece in pieces]).all(dim=0) + positions = torch.cat( + [p.positions if i == 0 else p.positions[:, 1:] for i, p in enumerate(pieces)], + dim=1, + ) + dt = torch.cat( + [p.dt if i == 0 else p.dt[:, 1:] for i, p in enumerate(pieces)], dim=1 + ) + rejected = None + if any(p.rejected_candidate is not None for p in pieces): + mask = torch.zeros_like(success) + candidates = [] + for i, p in enumerate(pieces): + points = p.positions + if p.rejected_candidate is not None: + mask |= p.rejected_candidate.env_mask + points = p.rejected_candidate.positions + candidates.append(points if i == 0 else points[:, 1:]) + rejected = RejectedMotionCandidate(torch.cat(candidates, dim=1), dt, mask) + return PlanResult( + success=success, + positions=torch.where( + success[:, None, None], positions, options.start_qpos[:, None] + ), + dt=dt, + rejected_candidate=rejected, + recovery=pieces[-1].recovery, + ) diff --git a/embodichain/lab/sim/motion/motion_generator.py b/embodichain/lab/sim/motion/motion_generator.py index e4c0b7d87c..0da837274a 100644 --- a/embodichain/lab/sim/motion/motion_generator.py +++ b/embodichain/lab/sim/motion/motion_generator.py @@ -207,8 +207,32 @@ class MotionGenOptions: retains its own Torch-only fork; no outer action counter is reused. """ + waypoint_modes: tuple[Literal["joint", "cartesian"], ...] = field( + default=(), kw_only=True + ) + """Explicit path mode from the preceding pose to each supplied waypoint. + + Supported for fixed-grid sequential ``ik_interp``. Empty retains ordinary + planning. Consecutive equal modes share a native request; the total sample + count and interval remain unchanged. No robot or target-name inference occurs. + """ + def __post_init__(self) -> None: """Validate backend-neutral motion generation options.""" + if type(self.waypoint_modes) is not tuple or any( + mode not in ("joint", "cartesian") for mode in self.waypoint_modes + ): + raise ValueError("waypoint_modes must be a tuple of joint/cartesian modes") + if self.waypoint_modes and ( + self.strategy != "ik_interp" + or self.interpolation_mode != "fixed_grid" + or self.ik_seed_mode != "sequential" + or self.is_linear + or self.preserve_cartesian_samples + ): + raise ValueError( + "waypoint_modes requires unsampled fixed-grid sequential ik_interp" + ) segment_retries = self.segment_sample_count_retries if ( type(segment_retries) is not tuple @@ -773,6 +797,12 @@ def generate( options = MotionGenOptions() if options is None else options # Options are mutable config objects; revalidate at the call boundary. options.__post_init__() + if options.waypoint_modes: + from ._phase_paths import generate_phase_paths + + return generate_phase_paths( + self, target_states, options, defer_recovery=defer_recovery + ) if type(defer_recovery) is not bool: raise TypeError("defer_recovery must be a boolean.") linear_keyframes = ( diff --git a/embodichain/lab/task_program/integrations/_native_plan_expansion.py b/embodichain/lab/task_program/integrations/_native_plan_expansion.py new file mode 100644 index 0000000000..66e3a72e27 --- /dev/null +++ b/embodichain/lab/task_program/integrations/_native_plan_expansion.py @@ -0,0 +1,455 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Native measured-plan branch of the shared same-grid expansion factory.""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +import hashlib +from pathlib import Path +from typing import Any + +__all__: list[str] = [] + + +@dataclass(frozen=True) +class TaskProgramNativeExpansionRecord: + """Owned measured-plan expansion provenance and hashed numeric attachment.""" + + env_id: int + payload: dict[str, Any] + + def __post_init__(self) -> None: + from embodichain.utils._owned_json import freeze_metadata + + object.__setattr__(self, "payload", freeze_metadata(self.payload)) + + def to_metadata(self) -> dict[str, Any]: + from embodichain.lab.gym.envs._json import json_safe_copy + + return { + "env_id": self.env_id, + **json_safe_copy(self.payload, field_name="expansion record"), + } + + +class _NativePlanExpansion: + """Select native grasp branches or adapt explicitly editable free phases.""" + + def __init__( + self, + operator: str, + options: dict, + *, + seed: int, + scene_case, + revision: str, + output: Path | None = None, + episode_id: int = 0, + ): + if operator not in ( + "object_pose", + "affordance", + "joint_residual", + "via_points", + "nullspace_residual", + ): + raise ValueError("unsupported native-plan expansion operator") + self.operator = operator + from embodichain.lab.gym.envs._json import json_safe_copy + + self.options = json_safe_copy(options, field_name="same-grid options") + self.seed = seed + self.scene_case, self.revision = scene_case, revision + self.output = output + self.episode_id = episode_id + self._records: list[TaskProgramNativeExpansionRecord] = [] + + @property + def records(self) -> tuple[TaskProgramNativeExpansionRecord, ...]: + return tuple(self._records) + + def create_plan_transform(self, request, *, engine): + if self.operator == "object_pose": + return None + if self.operator == "affordance": + if ( + request.analysis_call_index + not in self.options["affordance"]["call_indices"] + ): + return None + + def record(resolved, context, plan): + return self._record_affordance(request, context, plan) + + return record + + calls = self.options.get("call_indices") + if calls is not None and request.analysis_call_index not in calls: + return None + + def transform(resolved, context, plan): + return self._transform(request, engine, resolved, context, plan) + + return transform + + def prepare_planning_context(self, request, context, *, engine): + """Select a non-nominal native Affordance branch before planning.""" + if self.operator != "affordance": + return context + settings = self.options["affordance"] + if request.analysis_call_index not in settings["call_indices"]: + return context + if context.batch_size != 1: + raise ValueError("Native affordance expansion requires batch_size=1") + from embodichain.lab.sim.atomic_actions.affordance_sampling import ( + AffordanceSamplingContext, + ) + + return replace( + context, + affordance_sampling=AffordanceSamplingContext( + count=settings["branches"], + seed=self.seed, + episode_id=self.episode_id, + branch_override=1 + self.episode_id % (settings["branches"] - 1), + ), + ) + + def _record_affordance(self, call, context, plan): + """Require distinct native grasp geometry, retaining physical validation.""" + if not bool(plan.plan_success.all()): + return plan + samples = plan.diagnostics.metadata.get("affordance_sample", {}) + sampling = context.affordance_sampling + branch = sampling.branch_override + distinct = any( + sample.get("success") == [True] + and sample.get("unique_candidate_counts", [0])[0] > branch + and sample.get("reused") == [False] + for sample in samples.values() + ) + if not distinct: + raise ValueError("affordance produced no distinct feasible grasp branch") + evidence = { + "operator": "affordance", + "skill": plan.skill_id, + "workflow_call_index": call.analysis_call_index, + "sampling": sampling.metadata(), + "samples": samples, + "mode": "native_affordance_replanning", + } + if self.output is not None: + import numpy as np + from embodichain.lab.expansion.persistence import _digest as file_digest + + self.output.mkdir(parents=True, exist_ok=True) + path = ( + self.output + / f"call-{call.analysis_call_index}-{len(self._records)}.npz" + ) + with path.open("wb") as stream: + np.savez_compressed( + stream, + candidate=plan.joint_trajectory.positions[0].detach().cpu().numpy(), + dt=plan.joint_trajectory.dt[0].detach().cpu().numpy(), + ) + evidence["plan_artifact"] = {"path": str(path), "sha256": file_digest(path)} + metadata = dict(plan.diagnostics.metadata, expansion=evidence) + self._records.append( + TaskProgramNativeExpansionRecord(int(context.env_ids[0]), evidence) + ) + return replace(plan, diagnostics=replace(plan.diagnostics, metadata=metadata)) + + def _transform(self, call, engine, request, context, plan): + import torch + from embodichain.lab.sim.atomic_actions.plans import TimedTrajectory + from embodichain.lab.sim.atomic_actions.trajectory_adapter import ( + ActionPlanTemplateAdapter, + ) + from embodichain.lab.sim.motion.expansion import SourceContext + from embodichain.lab.sim.motion.expansion.operators import ( + ProposalRejected, + joint_residual, + nullspace_residual, + validate_motion_samples, + via_points, + ) + + free = set(self.options["free_phases"].get(plan.skill_id, ())) + if ( + not free + or plan.joint_trajectory is None + or not bool(plan.plan_success.all()) + ): + return plan + if context.batch_size != 1: + raise ValueError("Native same-grid transforms require batch_size=1") + endpoints = tuple( + e for e in request.binding.endpoints if e.endpoint_id == "motion" + ) + motion_ids = tuple(dict.fromkeys(i for e in endpoints for i in e.joint_ids)) + permissions = { + segment.name: (self.operator,) if segment.name in free else () + for segment in plan.segments + } + adapter = ActionPlanTemplateAdapter( + tuple(engine.robot.joint_names), + permissions, + { + name: "free" if value else "contact" + for name, value in permissions.items() + }, + controlled_joint_indices=motion_ids, + ) + source = SourceContext( + self.scene_case.task_id, + self.revision, + f"{call.workflow_id}:{call.analysis_call_index}", + self.scene_case, + context.require_control_dt(), + ) + template = adapter.export_template(plan, context=source) + reference_phases = template.phases + # Keep the first/last two samples, including discrete derivative stencils. + phases = tuple( + ( + replace(p, start_index=p.start_index + 1, stop_index=p.stop_index - 1) + if p.allowed_operators and p.stop_index - p.start_index >= 5 + else replace(p, allowed_operators=()) + ) + for p in template.phases + ) + if not any(p.allowed_operators for p in phases): + return plan + template = replace(template, phases=phases) + limits = engine.robot.get_qpos_limits().detach().cpu() + if limits.ndim == 3: + limits = limits[int(context.env_ids[0])] + active = list(template.controlled_joint_indices) + velocity = engine.robot.get_qvel_limits().detach().cpu() + if velocity.ndim == 2: + velocity = velocity[int(context.env_ids[0])] + velocity = velocity[active].clamp(max=self.options["velocity_limit"]) + acceleration = torch.full_like(velocity, self.options["acceleration_limit"]) + seed = int.from_bytes( + hashlib.sha256( + f"{self.seed}/{source.unit_id}/{self.operator}".encode() + ).digest()[:8], + "little", + ) % (2**63) + generator = torch.Generator().manual_seed(seed) + jacobians, kinematics = self._kinematics(engine.robot, endpoints, template) + + def motion_checks(trajectory): + checks = [] + for phase in phases: + if not phase.allowed_operators: + continue + # Operators keep their endpoints exact. The narrowed phase + # leaves two original samples at each boundary, covering every + # second difference affected by an edit. + start, stop = max(0, phase.start_index - 1), min( + len(trajectory.dt), phase.stop_index + 1 + ) + intervals = trajectory.dt[start:stop].clone() + intervals[0] = 0 + checks.append( + validate_motion_samples( + trajectory.positions[start:stop, active], + intervals, + velocity_limits=velocity, + acceleration_limits=acceleration, + ) + ) + return checks + + reference_checks = motion_checks(template) + if any(not check.accepted for check in reference_checks): + raise ValueError( + f"Reference free phases already exceed sampled motion bounds: " + f"{reference_checks}" + ) + reason = "no distinct candidate" + for attempt in range(self.options["max_proposals"]): + arguments = dict( + joint_limits=limits, + normalized_scale=self.options["joint_offset_scale"], + generator=generator, + ) + try: + if self.operator == "joint_residual": + candidate = joint_residual(template, **arguments) + elif self.operator == "via_points": + candidate = via_points( + template, via_count=self.options["via_count"], **arguments + ) + elif self.operator == "nullspace_residual": + candidate = nullspace_residual( + template, task_jacobians=jacobians, **arguments + ) + else: + raise ValueError(f"Unsupported operator: {self.operator}") + except ProposalRejected as exc: + reason = str(exc) + continue + delta = float((candidate.positions - template.positions).abs().max()) + if delta < self.options["minimum_joint_delta"]: + continue + checks = motion_checks(candidate) + if any(not check.accepted for check in checks): + reason = f"edited-phase motion limits: {checks}" + continue + fk = self._check_fk(template, candidate, kinematics) + if self.operator == "nullspace_residual" and ( + fk["max_translation_m"] + > self.options["nullspace_translation_tolerance_m"] + or fk["max_rotation_rad"] + > self.options["nullspace_rotation_tolerance_rad"] + ): + reason = f"nullspace FK error: {fk}" + continue + positions = adapter.restore_positions(plan, candidate.positions).unsqueeze( + 0 + ) + metadata = dict(plan.diagnostics.metadata) + evidence = { + "operator": self.operator, + "skill": plan.skill_id, + "workflow_call_index": call.analysis_call_index, + "phases": [p.phase_id for p in phases if p.allowed_operators], + "reference_phases": [ + {"name": p.phase_id, "start": p.start_index, "stop": p.stop_index} + for p in reference_phases + ], + "controlled_joint_names": [template.joint_names[i] for i in active], + "task_rows": self.options["nullspace_task_rows"], + "max_joint_delta": delta, + "proposal": attempt, + "same_time_grid": True, + "motion_validation_scope": "edited_phases_and_boundary_stencils", + "motion": { + "reference": [ + dict(c.metrics) for r in reference_checks for c in r.checks + ], + "candidate": [dict(c.metrics) for r in checks for c in r.checks], + }, + "fk": fk, + } + if self.output is not None: + import numpy as np + from embodichain.lab.expansion.persistence import _digest as file_digest + + self.output.mkdir(parents=True, exist_ok=True) + path = ( + self.output + / f"call-{call.analysis_call_index}-{len(self._records)}.npz" + ) + editable = torch.zeros_like(template.positions, dtype=torch.bool) + for phase in phases: + if phase.allowed_operators: + editable[phase.start_index : phase.stop_index, active] = True + with path.open("wb") as stream: + np.savez_compressed( + stream, + reference=template.positions.numpy(), + candidate=candidate.positions.numpy(), + dt=template.dt.numpy(), + editable=editable.numpy(), + ) + evidence["plan_artifact"] = { + "path": str(path), + "sha256": file_digest(path), + } + metadata.update( + expansion=evidence, + collision_evidence="unverified", + collision_scope="not_checked", + ) + rebuilt = engine.rebuild_plan_from_trajectory( + request, + context, + replace(plan, diagnostics=replace(plan.diagnostics, metadata=metadata)), + TimedTrajectory.from_positions( + positions, + env_ids=context.env_ids, + dt=plan.joint_trajectory.dt.clone(), + ), + ) + self._records.append( + TaskProgramNativeExpansionRecord(int(context.env_ids[0]), evidence) + ) + return rebuilt + raise ValueError( + f"{self.operator} produced no qualified {plan.skill_id} variant: {reason}" + ) + + def _kinematics(self, robot, endpoints, template): + import torch + + active = list(template.controlled_joint_indices) + blocks, models = [], [] + for endpoint in endpoints: + indices = list(endpoint.joint_ids) + if not set(indices) & set(active): + continue + solver = robot.get_solver(endpoint.target.control_part) + if solver is None or solver.pk_serial_chain is None: + raise ValueError( + "Trajectory augmentation requires the actual robot kinematic chain" + ) + chain_ids = [ + robot.joint_names.index(n) + for n in solver.pk_serial_chain.get_joint_parameter_names() + ] + qpos = template.positions[:, chain_ids] + rows = self.options["nullspace_task_rows"] + jacobian = ( + solver.get_jacobian( + qpos, + locations=torch.as_tensor(solver.tcp_xpos)[:3, 3], + ) + .detach() + .cpu()[:, rows, :] + ) + block = torch.zeros(len(qpos), len(rows), len(active), dtype=jacobian.dtype) + for column, joint in enumerate(chain_ids): + if joint in active: + block[:, :, active.index(joint)] = jacobian[:, :, column] + blocks.append(block) + models.append((solver, chain_ids)) + if not blocks: + raise ValueError("No kinematic chain covers the edited motion joints") + return torch.cat(blocks, dim=1), models + + @staticmethod + def _check_fk(reference, candidate, models): + import torch + + translation, rotation = 0.0, 0.0 + for solver, indices in models: + a = solver.get_fk(reference.positions[:, indices]).detach().cpu().double() + b = solver.get_fk(candidate.positions[:, indices]).detach().cpu().double() + translation = max( + translation, float((a[:, :3, 3] - b[:, :3, 3]).norm(dim=-1).max()) + ) + relative = a[:, :3, :3].transpose(-1, -2) @ b[:, :3, :3] + cosine = ((relative.diagonal(dim1=-2, dim2=-1).sum(-1) - 1) / 2).clamp( + -1, 1 + ) + rotation = max(rotation, float(torch.acos(cosine).max())) + return {"max_translation_m": translation, "max_rotation_rad": rotation} diff --git a/embodichain/lab/task_program/integrations/configured.py b/embodichain/lab/task_program/integrations/configured.py index 9af6c9ecd6..a8b50a4376 100644 --- a/embodichain/lab/task_program/integrations/configured.py +++ b/embodichain/lab/task_program/integrations/configured.py @@ -1706,6 +1706,7 @@ def _decode_motion_policy(value: object, *, path: str) -> MotionPolicy: "plan_opts", "interpolation_mode", "ik_seed_mode", + "phase_paths", "sample_count_retries", "segment_sample_count_retries", "segment_continuous_ik_recovery", @@ -1718,6 +1719,7 @@ def _decode_motion_policy(value: object, *, path: str) -> MotionPolicy: config["sample_count"], path=f"{path}.sample_count", minimum=2 ) kwargs: dict[str, object] = { + "phase_paths": dict(config.get("phase_paths", {})), "strategy": _identifier( config.get("strategy", "ik_interp"), path=f"{path}.strategy", diff --git a/embodichain/lab/task_program/integrations/expansion.py b/embodichain/lab/task_program/integrations/expansion.py index 543c680ff6..7e296f757c 100644 --- a/embodichain/lab/task_program/integrations/expansion.py +++ b/embodichain/lab/task_program/integrations/expansion.py @@ -24,6 +24,7 @@ import hashlib from collections.abc import Callable, Mapping, Sequence import math +from pathlib import Path from typing import ClassVar import torch @@ -54,6 +55,7 @@ ) from embodichain.lab.sim.atomic_skills.state import PlanningContext from embodichain.lab.task_program.runtime.expansion import TaskProgramPlanRequest +from ._native_plan_expansion import TaskProgramNativeExpansionRecord __all__ = [ "TaskProgramSourceAdapter", @@ -63,6 +65,7 @@ "TaskProgramMappedRetimeRecord", "TaskProgramSameGridExpansionFactory", "TaskProgramSameGridExpansionRecord", + "TaskProgramNativeExpansionRecord", ] @@ -193,6 +196,63 @@ class TaskProgramSameGridExpansionFactory: still pass the unchanged full-path motion and collision checks. """ + @classmethod + def from_native_plan( + cls, + operator: str, + options: Mapping[str, object], + *, + seed: int, + scene_case: SceneCase, + revision: str, + output: Path | None = None, + episode_id: int = 0, + ) -> TaskProgramSameGridExpansionFactory: + """Expand live Atomic plans on their existing measured control grid. + + Args: + operator: object_pose, affordance, joint_residual, via_points or nullspace_residual. + options: Task-owned phase allowlists, call selection, native operator + magnitudes, sampled motion/FK limits and proposal budget. + seed: Logical candidate seed, independent of physical row. + scene_case: Measured scene and initial-state identity. + revision: Pinned task/source revision. + output: Optional directory for hashed reference/candidate attachments. + episode_id: Logical affordance branch identity. + + This source path retains native operators and Atomic reconstruction, + protects phase-boundary derivative stencils and never claims physical + success. The host must still perform measured collision/task acceptance. + """ + from ._native_plan_expansion import _NativePlanExpansion + + instance = object.__new__(cls) + instance._native_delegate = _NativePlanExpansion( + operator, + options, + seed=seed, + scene_case=scene_case, + revision=revision, + output=output, + episode_id=episode_id, + ) + return instance + + def prepare_planning_context( + self, + request: TaskProgramPlanRequest, + context: PlanningContext, + *, + engine: AtomicSkillEngine, + ) -> PlanningContext: + """Bind optional native affordance sampling before the ordinary planner.""" + delegate = getattr(self, "_native_delegate", None) + return ( + context + if delegate is None + else delegate.prepare_planning_context(request, context, engine=engine) + ) + def __init__( self, *, @@ -306,8 +366,15 @@ def __init__( self._records: list[TaskProgramSameGridExpansionRecord] = [] @property - def records(self) -> tuple[TaskProgramSameGridExpansionRecord, ...]: + def records( + self, + ) -> tuple[ + TaskProgramSameGridExpansionRecord | TaskProgramNativeExpansionRecord, ... + ]: """Return successfully rebuilt call-level candidates.""" + delegate = getattr(self, "_native_delegate", None) + if delegate is not None: + return delegate.records return tuple( replace(record, template=replace(record.template)) for record in self._records @@ -317,6 +384,9 @@ def create_plan_transform( self, request: TaskProgramPlanRequest, *, engine: AtomicSkillEngine ) -> PlanTransform | None: """Select the spatial transform for one compiled call occurrence.""" + delegate = getattr(self, "_native_delegate", None) + if delegate is not None: + return delegate.create_plan_transform(request, engine=engine) if not isinstance(request, TaskProgramPlanRequest) or not isinstance( engine, AtomicSkillEngine ): diff --git a/embodichain/lab/task_program/runtime/results.py b/embodichain/lab/task_program/runtime/results.py index 61d288c669..4851fc16b3 100644 --- a/embodichain/lab/task_program/runtime/results.py +++ b/embodichain/lab/task_program/runtime/results.py @@ -423,6 +423,7 @@ def _motion_policy_to_metadata(policy: MotionPolicy) -> dict[str, object]: "velocity_targets": policy.velocity_targets, "interpolation_mode": policy.interpolation_mode, "ik_seed_mode": policy.ik_seed_mode, + **({"phase_paths": dict(policy.phase_paths)} if policy.phase_paths else {}), "sample_count_retries": list(policy.sample_count_retries), "require_final_velocity": policy.require_final_velocity, "final_velocity_rejection": policy.final_velocity_rejection, diff --git a/embodichain/lab/visualization/markers/__init__.py b/embodichain/lab/visualization/markers/__init__.py index 2f65927085..4172846aaf 100644 --- a/embodichain/lab/visualization/markers/__init__.py +++ b/embodichain/lab/visualization/markers/__init__.py @@ -22,6 +22,7 @@ from .group import MarkerGroup from .visualization_markers import VisualizationMarkers, VisualizationMarkersCfg from .robot_markers import RobotMarkers, RobotMarkersCfg, RobotMarkersAppearanceCfg +from .frame import MarkerFramePublisher __all__ = [ "RobotMarkers", @@ -30,6 +31,7 @@ "MarkerGroupCfg", "MarkerPrototypeCfg", "MarkerGroup", + "MarkerFramePublisher", "VisualizationMarkers", "VisualizationMarkersCfg", ] diff --git a/embodichain/lab/visualization/markers/_native.py b/embodichain/lab/visualization/markers/_native.py index 49dfd66940..a5ff8df9c6 100644 --- a/embodichain/lab/visualization/markers/_native.py +++ b/embodichain/lab/visualization/markers/_native.py @@ -86,7 +86,9 @@ class NativeMarkerRenderer: isolate them with the camera's render-category filter. """ - def __init__(self, scene: Scene, *, use_scene_for_overlays: bool = False) -> None: + def __init__( + self, scene: Scene, *, use_scene_for_overlays: bool = False, xray: bool = False + ) -> None: try: spawn = import_module("dexsim.spawn") required = ( @@ -111,6 +113,7 @@ def __init__(self, scene: Scene, *, use_scene_for_overlays: bool = False) -> Non self._spawn = spawn self._scene = scene self._use_scene_for_overlays = use_scene_for_overlays + self._xray = xray self._groups: dict[str, dict[str, _Entry]] = {} self._texture_directory = TemporaryDirectory( prefix="embodichain-marker-textures-" @@ -124,7 +127,10 @@ def _create( """Declare one render-only object through its lifetime-owning Scene.""" name = f"__embodichain_marker_{uuid4().hex}" if template is not None and hasattr(self._scene, "clone_mesh_object"): - return self._scene.clone_mesh_object(template.handle.path, name) + handle = self._scene.clone_mesh_object(template.handle.path, name) + if self._xray: + handle.get_material().set_depth_culling(False) + return handle scene_lighting = self._scene_lit(marker) use_scene = scene_lighting or self._use_scene_for_overlays parameters = ( @@ -235,7 +241,10 @@ def _create( physics=None, per_env=False, ) - return self._scene.add_mesh_object(desc, arena_name="default") + handle = self._scene.add_mesh_object(desc, arena_name="default") + if self._xray: + handle.get_material().set_depth_culling(False) + return handle def _discard(self, handle: SpawnedRigidBody) -> None: # Scene.close() invalidates the selected handles. @@ -288,7 +297,13 @@ def _apply( if previous is None or previous.visible != marker.visible: handle.set_visible(marker.visible) - def publish(self, name: str, markers: tuple[MeshMarkerOverlay, ...]) -> None: + def publish( + self, + name: str, + markers: tuple[MeshMarkerOverlay, ...], + *, + retain_omitted: bool = False, + ) -> None: """Apply a complete group, staging replacements before releasing old meshes. Args: @@ -296,7 +311,7 @@ def publish(self, name: str, markers: tuple[MeshMarkerOverlay, ...]) -> None: markers: Complete detached group snapshots in world coordinates. """ previous = self._groups.get(name, {}) - pending: dict[str, _Entry] = {} + pending: dict[str, _Entry] = dict(previous) if retain_omitted else {} created = [] touched = [] batch_enabled = hasattr(self._scene, "create_visual_object_batch") @@ -304,6 +319,20 @@ def publish(self, name: str, markers: tuple[MeshMarkerOverlay, ...]) -> None: for entry in previous.values(): templates.setdefault(id(entry.snapshot.vertices), entry) try: + if retain_omitted: + selected = {marker.overlay_id for marker in markers} + for key, entry in previous.items(): + if key not in selected and entry.snapshot.visible: + touched.append(entry) + hidden = replace( + entry.snapshot, + visible=False, + _shared_geometry=entry.snapshot._geometry, + ) + self._apply( + entry.handle, hidden, entry.snapshot, transform=False + ) + pending[key] = _Entry(entry.handle, hidden) for marker in markers: entry = previous.get(marker.overlay_id) if entry is not None and self._same_geometry(entry.snapshot, marker): @@ -329,9 +358,9 @@ def publish(self, name: str, markers: tuple[MeshMarkerOverlay, ...]) -> None: ) pending[marker.overlay_id] = _Entry(handle, marker) templates.setdefault(id(marker.vertices), pending[marker.overlay_id]) - if batch_enabled and pending: + if batch_enabled and markers: transforms = _transforms(markers) - handles = tuple(entry.handle for entry in pending.values()) + handles = tuple(pending[marker.overlay_id].handle for marker in markers) cached = self._batches.get(name) if ( cached is None diff --git a/embodichain/lab/visualization/markers/frame.py b/embodichain/lab/visualization/markers/frame.py new file mode 100644 index 0000000000..95093135d4 --- /dev/null +++ b/embodichain/lab/visualization/markers/frame.py @@ -0,0 +1,86 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Resident marker resources and one cross-group native frame publication.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING +from .group import MarkerGroup +from .cfg import MarkerGroupCfg +from ._native import NativeMarkerRenderer + +if TYPE_CHECKING: + from embodichain.lab.sim import SimulationManager + +__all__ = ["MarkerFramePublisher"] + + +class MarkerFramePublisher: + """Stage robot/object groups and publish one coherent render-only frame. + + Args: + simulation: Prepared simulation owning the native render resources. + xray: Disable depth culling for translucent comparison overlays. + + Groups belong to this publisher, independently of automatic simulation + markers. Initial publication uploads all declared resources, including hidden + instances. Later publications transform only visible instances, retain hidden + resources, and use actual native visibility rather than moving/scaling objects. + Publishing neither prepares nor steps the simulation. Close before the World. + """ + + def __init__(self, simulation: SimulationManager, *, xray: bool = False) -> None: + self.sim = simulation + self.groups: dict[str, MarkerGroup] = {} + self.native = NativeMarkerRenderer(simulation.spawn_result, xray=xray) + self.publications = 0 + self._closed = False + + def add_marker_group(self, cfg: MarkerGroupCfg) -> MarkerGroup: + """Declare a group compatible with RobotMarkers/VisualizationMarkers.""" + if self._closed: + raise RuntimeError("marker frame publisher is closed") + if cfg.name in self.groups: + raise ValueError(f"duplicate marker group: {cfg.name}") + group = MarkerGroup( + cfg, num_envs=self.sim.num_envs, origins=self.sim.arena_offsets + ) + self.groups[group.name] = group + return group + + def publish(self, *, preload: bool = False) -> None: + """Submit all staged groups together, retaining hidden GPU resources.""" + if self._closed: + raise RuntimeError("marker frame publisher is closed") + initial = self.publications == 0 or preload + meshes = tuple( + mesh + for group in self.groups.values() + for mesh in group.snapshot(visible_only=not initial) + ) + self.native.publish("frame", meshes, retain_omitted=True) + self.publications += 1 + + def close(self) -> None: + """Release resident batches, meshes and groups; repeated close is safe.""" + if self._closed: + return + self._closed = True + self.native.close() + for group in self.groups.values(): + group.remove() + self.groups.clear() diff --git a/embodichain/lab/visualization/markers/group.py b/embodichain/lab/visualization/markers/group.py index c499d2d5be..03dbaa7033 100644 --- a/embodichain/lab/visualization/markers/group.py +++ b/embodichain/lab/visualization/markers/group.py @@ -391,7 +391,7 @@ def _poses(self, env_id: int) -> tuple[np.ndarray, np.ndarray]: xyzw = (rotation * Rotation.from_quat(xyzw)).as_quat() return xyz + self._origins[env_id], xyzw - def snapshot(self) -> tuple[MeshMarkerOverlay, ...]: + def snapshot(self, *, visible_only: bool = False) -> tuple[MeshMarkerOverlay, ...]: """Return detached world-space snapshots without querying parent assets. Returns: @@ -408,6 +408,10 @@ def snapshot(self) -> tuple[MeshMarkerOverlay, ...]: ): raise ValueError("World positions must be finite float32 values.") for index, prototype_index in enumerate(state["prototype_indices"]): + if visible_only and not ( + self._visible[env_id] and state["visible"][index] + ): + continue prototype = prototypes[prototype_index] rgba = ( prototype.color diff --git a/tests/lab/expansion/test_comparison.py b/tests/lab/expansion/test_comparison.py new file mode 100644 index 0000000000..016cd793c9 --- /dev/null +++ b/tests/lab/expansion/test_comparison.py @@ -0,0 +1,76 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +from __future__ import annotations + +import numpy as np +import pytest +from embodichain.lab.expansion import MeasuredTrajectory +from embodichain.lab.visualization.markers import ( + MarkerGroup, + MarkerGroupCfg, + MarkerPrototypeCfg, +) + + +def test_measured_comparison_owns_boundaries_and_preserves_marker_identity(): + times = np.array([0.0, 0.1, 0.3]) + poses = np.tile([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0], (3, 1)) + clip = MeasuredTrajectory( + "original", + "robot", + ("joint",), + times, + np.array([[1.0], [2.0], [3.0]]), + poses, + {"object": poses}, + ) + times[1] = 99 + poses[0, 0] = 99 + assert [clip.frame_at(t) for t in (-1.0, 0.0, 0.1, 0.2, 0.3, 5.0)] == [ + 0, + 0, + 1, + 1, + 2, + 2, + ] + assert clip.root_poses[0, 0] == clip.object_poses["object"][0, 0] == 0 + with pytest.raises(ValueError, match="ordered"): + MeasuredTrajectory( + "bad", + "robot", + ("joint",), + np.array([0.0, 0.0]), + np.zeros((2, 1)), + np.zeros((2, 7)), + {}, + ) + group = MarkerGroup( + MarkerGroupCfg( + name="ghost", prototypes={"box": MarkerPrototypeCfg(shape="box")} + ), + num_envs=1, + origins=np.zeros((1, 3)), + ) + group.update(translations=np.zeros((3, 3)), visible=np.array([False, True, False])) + complete = group.snapshot() + selected = group.snapshot(visible_only=True) + assert len(complete) == 3 and len(selected) == 1 + assert selected[0].overlay_id == complete[1].overlay_id + group.update(visible=np.array([False, False, True])) + assert group.snapshot(visible_only=True)[0].overlay_id == complete[2].overlay_id + group.remove() diff --git a/tests/lab/expansion/test_extension_ports_sim.py b/tests/lab/expansion/test_extension_ports_sim.py new file mode 100644 index 0000000000..2312257ab8 --- /dev/null +++ b/tests/lab/expansion/test_extension_ports_sim.py @@ -0,0 +1,193 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys +import pytest + + +def _probe(output): + import torch + from embodichain.lab.expansion import MeasuredExpansionValidator + from embodichain.lab.expansion.program import TaskProgramBatchExecutor + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.sim import SimulationManager + from embodichain.lab.sim.motion.motion_generator import ( + MotionGenerator, + MotionGenCfg, + MotionGenOptions, + ) + from embodichain.lab.sim.motion.planners.trapezoidal_planner import ( + TrapezoidalPlannerCfg, + ) + from embodichain.lab.sim.motion.planners.utils import PlanState + from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( + collision_bodies_from_simulation, + ) + from embodichain.utils.utility import load_config + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + path = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml" + ) + discover_task_packages() + execute_init_hooks() + cfg = config_to_cfg(load_config(path), source_path=path) + cfg.num_envs = cfg.sim_cfg.num_envs = 2 + cfg.sim_cfg.device, cfg.sim_cfg.headless = "cpu", True + cfg.sim_cfg.render_cfg.renderer = "no-render" + cfg.sensor, cfg.enable_sensor, cfg.dataset = [], False, None + cfg.init_rollout_buffer = cfg.record_trajectory = False + cfg.task_program.program.count = 1 + env = REGISTERED_ENVS[load_config(path)["id"]].make(cfg=cfg) + try: + env.reset(seed=0) + generator = MotionGenerator( + MotionGenCfg( + planner_cfg=TrapezoidalPlannerCfg( + robot_uid=env.robot.uid, sim_instance_id=env.sim.instance_id + ) + ), + env_ids=(0,), + ) + start = env.robot.get_qpos(name="arm")[0:1].clone() + states = [] + for index in range(3): + goal = start.clone() + goal[:, 0] += 0.001 * (index + 1) + pose = env.robot.compute_fk( + qpos=goal, name="arm", to_matrix=True, env_ids=(0,) + ) + states.append(PlanState.from_xpos(pose)) + base = dict( + strategy="ik_interp", + interpolation_mode="fixed_grid", + ik_seed_mode="sequential", + interpolation_dt=0.04, + start_qpos=start, + control_part="arm", + ) + ordinary = generator.generate(states, MotionGenOptions(sample_count=25, **base)) + first = generator.generate(states[:1], MotionGenOptions(sample_count=9, **base)) + tail = generator.generate( + states[1:], + MotionGenOptions( + sample_count=17, + **{**base, "start_qpos": first.positions[:, -1], "is_linear": True}, + ), + ) + before = env.sim.physics_step_index + mixed = generator.generate( + states, + MotionGenOptions( + sample_count=25, + waypoint_modes=("joint", "cartesian", "cartesian"), + **base, + ), + ) + assert mixed.success.all() and first.success.all() and tail.success.all() + torch.testing.assert_close( + mixed.positions, + torch.cat((first.positions, tail.positions[:, 1:]), dim=1), + rtol=0, + atol=1e-6, + ) + torch.testing.assert_close( + mixed.dt, torch.cat((first.dt, tail.dt[:, 1:]), dim=1), rtol=0, atol=0 + ) + after = generator.generate(states, MotionGenOptions(sample_count=25, **base)) + torch.testing.assert_close( + ordinary.positions, after.positions, rtol=0, atol=1e-6 + ) + assert env.sim.physics_step_index == before + program = env.compile_task_program(cfg.task_program) + frames = sorted({b.frame_uid for b in collision_bodies_from_simulation(env)}) + value = float(env.robot.get_qpos()[0, 0]) + name = env.robot.joint_names[0] + configuration = { + "initial_checks": [ + { + "kind": "joint_range", + "joint": name, + "lower": value - 0.1, + "upper": value + 0.1, + } + ], + "final_checks": [ + { + "kind": "joint_range", + "joint": name, + "lower": value + 1, + "upper": value + 2, + } + ], + "events": [], + "mounting_contacts": [], + "allowed_contacts": [ + (a, b) for i, a in enumerate(frames) for b in frames[i + 1 :] + ], + } + for backend in ("geometry", "native_contacts"): + check = MeasuredExpansionValidator( + env, configuration, Path(output) / backend, backend=backend + ) + try: + check.prepare() + TaskProgramBatchExecutor(env, program).run( + (0, 1), max_steps=3, observe_step=check.sample + ) + assert set(check.results) == set(check.terminal) == {0, 1} + assert all( + row.status == "passed" for row in check.results.values() + ), check.results + peer = check.terminal[1] + check.prepare(env_ids=(0,)) + assert check.terminal[1] is peer and 0 not in check.terminal + if backend == "native_contacts": + assert check.rows[1].substeps > 0 and check.rows[0].substeps == 0 + finally: + check.close() + finally: + env.close(exit_process=False) + SimulationManager.flush_cleanup_queue() + + +@pytest.mark.subprocess_sim +def test_explicit_phase_paths_and_selected_row_acceptance(tmp_path): + result = subprocess.run( + [sys.executable, __file__, str(tmp_path)], + cwd=Path(__file__).resolve().parents[3], + env={**os.environ, "SDL_VIDEODRIVER": "offscreen", "OMP_NUM_THREADS": "1"}, + capture_output=True, + text=True, + timeout=300, + ) + assert result.returncode == 0, result.stdout[-3000:] + result.stderr[-5000:] + + +if __name__ == "__main__": + _probe(sys.argv[1]) From ab04d972b5b75042434498db9a889b4edd03b6fe Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 14 Nov 2026 14:24:14 +0000 Subject: [PATCH 05/49] feat(graspkit): scope pose NMS memory budgets per task --- .../motion-planning/trajectory-expansion.md | 4 ++ embodichain/utils/nms.py | 40 ++++++++++++-- tests/utils/test_nms_scope.py | 52 +++++++++++++++++++ 3 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 tests/utils/test_nms_scope.py diff --git a/agent_context/topics/motion-planning/trajectory-expansion.md b/agent_context/topics/motion-planning/trajectory-expansion.md index 6a626491df..5d8dcb9fe5 100644 --- a/agent_context/topics/motion-planning/trajectory-expansion.md +++ b/agent_context/topics/motion-planning/trajectory-expansion.md @@ -65,6 +65,10 @@ position search reuses its pool; approach search draws one pool per direction. Each successful row freezes independently. Per-row resets or filtering before ranking/NMS change populations. Freeze grasp, direction and position before comparing planners and review population fingerprints after selection changes. +`utils.nms.pose_nms_scope` supplies a nested, task-local pairwise tile budget; +explicit call arguments override it. It preserves threshold arithmetic and +selection order without changing an imported backend function. Copied planning +contexts inherit the budget while independent threads keep their own default. Explicit goal-conditioned endpoint searches also change the population and retain rejected goals; they establish neither paths nor physical success. diff --git a/embodichain/utils/nms.py b/embodichain/utils/nms.py index a43a5be3c8..8befa8028d 100644 --- a/embodichain/utils/nms.py +++ b/embodichain/utils/nms.py @@ -17,6 +17,9 @@ from __future__ import annotations import math +from contextlib import contextmanager +from contextvars import ContextVar +from collections.abc import Iterator import numpy as np import torch @@ -24,9 +27,35 @@ from embodichain.utils import logger from embodichain.utils.math import quat_from_matrix -__all__ = ["pose_nms", "pose_nms_indices"] +__all__ = ["pose_nms", "pose_nms_indices", "pose_nms_scope"] _POSE_NMS_CHUNK_SIZE = 2048 +_POSE_NMS_SCOPE: ContextVar[int] = ContextVar( + "pose_nms_chunk_size", default=_POSE_NMS_CHUNK_SIZE +) + + +@contextmanager +def pose_nms_scope(*, chunk_size: int | None = None) -> Iterator[int]: + """Select a task-local NMS memory budget without replacing any function. + + Args: + chunk_size: Positive pairwise tile bound; None inherits the active scope + (2048 outside a scope). Explicit NMS call arguments take precedence. + + Yields: + Active tile bound. Nested scopes restore their parent on success/failure; + threads and copied cooperative contexts retain their own selection. + Threshold arithmetic, candidate ordering and output values are unchanged. + """ + size = _POSE_NMS_SCOPE.get() if chunk_size is None else chunk_size + if type(size) is not int or size < 1: + raise ValueError("NMS chunk_size must be a positive integer") + token = _POSE_NMS_SCOPE.set(size) + try: + yield size + finally: + _POSE_NMS_SCOPE.reset(token) def _poses_to_components(poses: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]: @@ -219,7 +248,7 @@ def pose_nms_indices( angle_th: float = np.pi / 36, dist_th: float = 0.003, preserve_order: bool = False, - chunk_size: int = _POSE_NMS_CHUNK_SIZE, + chunk_size: int | None = None, ) -> torch.Tensor: """Return pose indices after removing poses that are too close. @@ -237,7 +266,7 @@ def pose_nms_indices( ``False``, poses with fewer close neighbors are selected first. Defaults to ``False``. chunk_size: Maximum size of either dimension of a pairwise tile. - Defaults to 2048. + None uses the active pose_nms_scope, defaulting to 2048. Returns: Indices of selected poses. Shape is ``(M,)``, where ``M <= N``. @@ -246,6 +275,7 @@ def pose_nms_indices( ValueError: If ``poses`` is not shaped as ``(N, 4, 4)``, is not on a CPU or CUDA device, or ``chunk_size`` is not positive. """ + chunk_size = _POSE_NMS_SCOPE.get() if chunk_size is None else chunk_size if poses.ndim != 3 or poses.shape[-2:] != (4, 4): raise ValueError(f"Invalid input shape {poses.shape}, expected (N, 4, 4).") if poses.device.type not in {"cpu", "cuda"}: @@ -316,7 +346,7 @@ def pose_nms( poses: torch.Tensor, angle_th: float = np.pi / 36, dist_th: float = 0.003, - chunk_size: int = _POSE_NMS_CHUNK_SIZE, + chunk_size: int | None = None, ) -> tuple[torch.Tensor, torch.Tensor]: """Remove poses that are too close in translation and rotation. @@ -325,7 +355,7 @@ def pose_nms( angle_th: Rotation threshold in radians. Defaults to pi / 36. dist_th: Translation threshold. Defaults to 0.003. chunk_size: Maximum size of either dimension of a pairwise tile. - Defaults to 2048. + None uses the active pose_nms_scope, defaulting to 2048. Returns: A tuple containing the filtered pose matrices in input order and their diff --git a/tests/utils/test_nms_scope.py b/tests/utils/test_nms_scope.py new file mode 100644 index 0000000000..412b75cbef --- /dev/null +++ b/tests/utils/test_nms_scope.py @@ -0,0 +1,52 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +from __future__ import annotations + +from concurrent.futures import ThreadPoolExecutor +from contextvars import copy_context +import pytest +import torch +from embodichain.utils.nms import pose_nms, pose_nms_scope + + +def test_nms_memory_scope_is_owned_and_preserves_selection(): + def current(): + with pose_nms_scope() as size: + return size + + poses = torch.eye(4).repeat(8, 1, 1) + poses[:, 0, 3] = torch.tensor([0.0, 0.001, 0.002, 0.01, 0.012, 0.02, 0.021, 0.03]) + expected = pose_nms(poses, chunk_size=2) + with pose_nms_scope(chunk_size=2): + inherited = copy_context() + with pytest.raises(RuntimeError): + with pose_nms_scope(chunk_size=3): + assert current() == 3 + raise RuntimeError("scope interrupted") + assert current() == 2 + actual = pose_nms(poses) + assert torch.equal(actual[0], expected[0]) and torch.equal( + actual[1], expected[1] + ) + explicit = pose_nms(poses, chunk_size=1) + assert torch.equal(explicit[1], expected[1]) + with ThreadPoolExecutor(max_workers=1) as pool: + assert pool.submit(current).result() == 2048 + assert current() == 2048 and inherited.run(current) == 2 + with pytest.raises(ValueError): + with pose_nms_scope(chunk_size=0): + pass From bc5ae3f2ba53422a0c41f136b36ddbd6ee07df5a Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 06:52:59 +0000 Subject: [PATCH 06/49] perf: reduce single-world planning and row execution overhead Share Default CPU numeric observations within bounded command-gather scopes, reconstruct immutable standard targets, and transfer fresh internal command ownership while preserving public snapshots and validation. Keep native multi-chunk grasp geometry and reductions resident on CUDA within each query, preserving samples, thresholds, stream ordering and independent results. Add focused regression coverage and a reproducible runtime comparison driver. Validation: 201 focused tests including CUDA and 42 context tests passed; Black 26.10.1, API docs 4924/4924 and diff checks passed. Sources match the final benchmark manifest. Forward/reverse sensor-free UR5 execution versus main 0119171b (seconds): small main 10.34-10.45, off 9.07-9.31, on 8.31-9.08; medium main 49.24-57.12, off 47.19-50.90, on 48.66-49.57; large main 251.77-260.14, off 189.57-196.42, on 192.07-200.29. All 492 program attempts accepted. Default CPU physics retains legacy CUDA grasp classification; these shared-host single-seed results are not physical qualification. --- .../topics/expansion-engine/workloads.md | 10 + .../topics/motion-planning/motion-planning.md | 6 + embodichain/lab/expansion/workloads.py | 22 +- .../lab/sim/atomic_skills/_command_batches.py | 6 + embodichain/lab/sim/atomic_skills/bindings.py | 18 + embodichain/lab/sim/atomic_skills/core.py | 14 +- .../lab/sim/atomic_skills/runtime_commands.py | 113 ++++- .../objects/backends/_numeric_observations.py | 165 +++++++ embodichain/lab/sim/objects/backends/scene.py | 9 + embodichain/lab/sim/objects/rigid_object.py | 19 + .../pg_grasp/gripper_collision_checker.py | 147 ++++-- .../benchmark/expansion/runtime_comparison.py | 449 ++++++++++++++++++ tests/sim/atomic_skills/test_core.py | 38 +- .../atomic_skills/test_runtime_commands.py | 29 ++ tests/sim/objects/test_scene_backend.py | 102 ++++ tests/toolkits/test_fixed_gripper_geometry.py | 61 +++ 16 files changed, 1150 insertions(+), 58 deletions(-) create mode 100644 embodichain/lab/sim/objects/backends/_numeric_observations.py create mode 100644 scripts/benchmark/expansion/runtime_comparison.py diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 6dcdf270f1..6ca15ed63a 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -56,6 +56,16 @@ The optional cooperative planner merges compatible fixed-grid motion requests and pure FK/IK/Jacobian calls. Budget-bearing whole-motion requests keep their original execution so charge semantics are preserved. Context variables and candidate random streams remain row-local; results are independently owned. +Default CPU command gathering shares native numeric reads through a bounded +World-owner scope in `sim/objects/backends/_numeric_observations.py`. It ends +before completion callbacks and physical stepping, and starts after reset and +activation. Checked native writes, physics steps and binding topology changes +invalidate samples. Derived dynamic rigid poses share the same boundary and invalidation, with +separate CPU autocast representations. Consumers receive independent output +buffers; semantic +state, episode clocks and validation remain row-owned. CUDA and other backends +retain native reads. Raw SDK mutation or concurrent World writes inside the +read boundary are outside this internal side-effect-free planning contract. Semantic programs and some trajectory processing still run per row. Per-control planning readiness is a barrier; this API does not claim complete vectorization or universal throughput improvement. diff --git a/agent_context/topics/motion-planning/motion-planning.md b/agent_context/topics/motion-planning/motion-planning.md index 527adf63f0..fe98a0d836 100644 --- a/agent_context/topics/motion-planning/motion-planning.md +++ b/agent_context/topics/motion-planning/motion-planning.md @@ -93,6 +93,12 @@ unchanged physics substeps; Gym experts use their environment's command period. prepared actions without retiming again. See [retiming and playback](planner-details.md#retiming-and-playback). +Gripper surface queries with CPU inputs still classify convex distances on CUDA. +Native multi-chunk calls own one query-local geometry snapshot and bounded scratch, +retain CPU point/ground transforms and all samples, and return owned reduced CPU +results. This is distinct from the simulation physics device. Visualization, +custom point-query overrides and already-device-resident callers keep their paths. + GraspKit owns sampled/native geometric qualification from explicit hand inputs; Scene captures geometry and Robot adapters provide FK/calibration. GraspKit performs no hardware lookup. Sampling uses the contact frame and maps to runtime diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index 3f575924ba..dfbd37b65e 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -463,6 +463,9 @@ def run(self) -> Mapping[str, object]: from tensordict import TensorDict from embodichain.lab.gym.envs.types import ControllerAction from ._planning_batches import batched_planning + from embodichain.lab.sim.objects.backends._numeric_observations import ( + numeric_observation_scope, + ) env, torch = self.env, self.torch previous_auto = getattr(env, "_demo_no_auto_reset", False) @@ -483,15 +486,16 @@ def run(self) -> Mapping[str, object]: self._fill() self._activate() cursors = {row: state["cursor"] for row, state in self.live.items()} - commands = ( - planner.gather(cursors) - if planner is not None - else { - row: command - for row, cursor in cursors.items() - if (command := cursor.next()) is not None - } - ) + with numeric_observation_scope(env.sim, env.robot): + commands = ( + planner.gather(cursors) + if planner is not None + else { + row: command + for row, cursor in cursors.items() + if (command := cursor.next()) is not None + } + ) for row in tuple(self.live): if row not in commands: self._finish(row) diff --git a/embodichain/lab/sim/atomic_skills/_command_batches.py b/embodichain/lab/sim/atomic_skills/_command_batches.py index 5aa5d41d1c..492357f672 100644 --- a/embodichain/lab/sim/atomic_skills/_command_batches.py +++ b/embodichain/lab/sim/atomic_skills/_command_batches.py @@ -140,6 +140,12 @@ def numeric(frame): def validate_frame(frame): + if ( + type(frame) is not RuntimeCommandFrame + or type(frame.env_ids) is not torch.Tensor + or frame.env_ids.device.type != "cuda" + ): + return False values = leaves(frame) if values is None: return False diff --git a/embodichain/lab/sim/atomic_skills/bindings.py b/embodichain/lab/sim/atomic_skills/bindings.py index e2bd6cd1e1..3f57133224 100644 --- a/embodichain/lab/sim/atomic_skills/bindings.py +++ b/embodichain/lab/sim/atomic_skills/bindings.py @@ -203,6 +203,24 @@ def __post_init__(self) -> None: raise ValueError("JointPositionTarget.joint_ids must be unique.") object.__setattr__(self, "joint_ids", joint_ids) + def snapshot(self) -> JointPositionTarget: + """Return an independently owned target. + + Standard immutable fields are reconstructed and validated; subclasses + and extended scalar types retain generic deep-snapshot semantics. + + Returns: + A new target of the same concrete type. + """ + if ( + type(self) is not JointPositionTarget + or type(self.control_part) is not str + or type(self.joint_ids) is not tuple + or any(type(joint) is not int for joint in self.joint_ids) + ): + return deepcopy(self) + return JointPositionTarget(self.control_part, self.joint_ids) + @property def transport_id(self) -> str: """Return the built-in joint-position transport identifier.""" diff --git a/embodichain/lab/sim/atomic_skills/core.py b/embodichain/lab/sim/atomic_skills/core.py index 20587e026b..fcebdab5d4 100644 --- a/embodichain/lab/sim/atomic_skills/core.py +++ b/embodichain/lab/sim/atomic_skills/core.py @@ -61,6 +61,8 @@ ) from .requirements import GRASP_CAPABILITY, SkillBindingContract from .runtime_commands import ( + _sequence_from_fresh_frames, + _frame_from_fresh_commands, EndpointCommand, JointPositionPayload, RuntimeCommandFrame, @@ -1358,8 +1360,8 @@ def _authorize_command_targets( EndpointCommand(target=target, payload=command.payload) ) frames.append( - RuntimeCommandFrame( - commands=tuple(endpoint_commands), + _frame_from_fresh_commands( + endpoint_commands, active_mask=( frame.active_mask if active_mask is None @@ -1369,7 +1371,7 @@ def _authorize_command_targets( hold_duration=frame.hold_duration, ) ) - return TimedCommandSequence(frames=tuple(frames), env_ids=commands.env_ids) + return _sequence_from_fresh_frames(frames, commands.env_ids) def _joint_command_sequence( self, @@ -1420,14 +1422,14 @@ def _joint_command_sequence( # dispatching it, wait for the next arrival interval; the terminal # frame reuses its own interval as the action's settling window. frames.append( - RuntimeCommandFrame( - commands=tuple(endpoint_commands), + _frame_from_fresh_commands( + endpoint_commands, active_mask=active_mask, env_ids=trajectory.env_ids, hold_duration=trajectory.dt[:, next_waypoint_index], ) ) - return TimedCommandSequence(frames=tuple(frames), env_ids=trajectory.env_ids) + return _sequence_from_fresh_frames(frames, trajectory.env_ids) @staticmethod def _build_segments( diff --git a/embodichain/lab/sim/atomic_skills/runtime_commands.py b/embodichain/lab/sim/atomic_skills/runtime_commands.py index de474be3f9..2a05935f3f 100644 --- a/embodichain/lab/sim/atomic_skills/runtime_commands.py +++ b/embodichain/lab/sim/atomic_skills/runtime_commands.py @@ -70,6 +70,18 @@ def _snapshot_target(target: RuntimeEndpointTarget) -> RuntimeEndpointTarget: return snapshot +def _unique_env_ids(env_ids: torch.Tensor) -> bool: + """Avoid a data-dependent kernel for a provably unique dense CPU singleton.""" + if ( + type(env_ids) is torch.Tensor + and env_ids.device.type == "cpu" + and env_ids.layout == torch.strided + and env_ids.numel() == 1 + ): + return True + return torch.unique(env_ids).numel() == env_ids.numel() + + class RuntimeCommandPayload(ABC): """Immutable-by-ownership payload submitted to one runtime transport.""" @@ -264,6 +276,10 @@ def __post_init__(self) -> None: if validate_frame(self): return + RuntimeCommandFrame._initialize(self, owned_commands=False) + + def _initialize(self, *, owned_commands: bool) -> None: + """Validate every frame field, optionally transferring private commands.""" if isinstance(self.commands, (str, bytes)): raise TypeError("commands must be an iterable of EndpointCommand values.") try: @@ -284,7 +300,7 @@ def __post_init__(self) -> None: ): raise ValueError("env_ids must be int64 with shape (batch_size,).") batch_size = int(self.env_ids.shape[0]) - if torch.unique(self.env_ids).numel() != batch_size: + if not _unique_env_ids(self.env_ids): raise ValueError("env_ids must be unique.") if not isinstance(self.active_mask, torch.Tensor): raise TypeError("active_mask must be a torch.Tensor.") @@ -306,7 +322,11 @@ def __post_init__(self) -> None: if self.hold_duration.device != self.env_ids.device: raise ValueError("hold_duration and env_ids must share a device.") - snapshots = tuple(command.snapshot() for command in commands) + snapshots = ( + commands + if owned_commands + else tuple(command.snapshot() for command in commands) + ) destinations: set[tuple[str, str]] = set() joint_owners: dict[int, tuple[str, str]] = {} for command in snapshots: @@ -426,7 +446,7 @@ def __post_init__(self) -> None: or self.env_ids.shape[0] < 1 ): raise ValueError("env_ids must be int64 with shape (batch_size,).") - if torch.unique(self.env_ids).numel() != self.env_ids.numel(): + if not _unique_env_ids(self.env_ids): raise ValueError("env_ids must be unique.") if isinstance(self.frames, (str, bytes)): raise TypeError("frames must be an iterable of RuntimeCommandFrame values.") @@ -481,6 +501,93 @@ def snapshot(self) -> TimedCommandSequence: return TimedCommandSequence(frames=self.frames, env_ids=self.env_ids) +def _canonical_cpu_command(command: EndpointCommand) -> bool: + """Identify standard commands without user-defined snapshot callbacks.""" + return ( + type(command) is EndpointCommand + and type(command.target) is JointPositionTarget + and type(command.target.control_part) is str + and type(command.target.joint_ids) is tuple + and all(type(joint) is int for joint in command.target.joint_ids) + and not getattr(command.target, "__dict__", {}) + and type(command.payload) is JointPositionPayload + and type(command.payload.positions) is torch.Tensor + and command.payload.positions.device.type == "cpu" + and ( + command.payload.velocities is None + or type(command.payload.velocities) is torch.Tensor + ) + ) + + +def _frame_from_fresh_commands( + commands: list[EndpointCommand], + *, + active_mask: torch.Tensor, + env_ids: torch.Tensor, + hold_duration: torch.Tensor, +) -> RuntimeCommandFrame: + """Transfer unexposed engine-built commands while retaining frame checks. + + Only fresh commands from the two canonical engine builders may enter this + path. Extended targets, payloads and tensor types use public construction. + Public frame constructors and snapshots never transfer caller ownership. + """ + fields = dict( + commands=tuple(commands), + active_mask=active_mask, + env_ids=env_ids, + hold_duration=hold_duration, + ) + if any( + type(v) is not torch.Tensor or v.device.type != "cpu" + for v in (active_mask, env_ids, hold_duration) + ) or not all(_canonical_cpu_command(c) for c in commands): + return RuntimeCommandFrame(**fields) + frame = object.__new__(RuntimeCommandFrame) + for name, value in fields.items(): + object.__setattr__(frame, name, value) + RuntimeCommandFrame._initialize(frame, owned_commands=True) + commands.clear() + return frame + + +def _sequence_from_fresh_frames( + frames: list[RuntimeCommandFrame], env_ids: torch.Tensor +) -> TimedCommandSequence: + """Transfer private, freshly validated canonical frames into a sequence. + + Only engine builders may pass their newly constructed, unexposed CPU frames. + CUDA retains packed sequence validation rather than synchronizing each ID check. + Public constructors and snapshots always retain defensive revalidation and + copying. Custom targets/payloads retain that path as their callbacks may + carry aliases or side effects. The input list is consumed on transfer. + """ + if ( + type(env_ids) is not torch.Tensor + or env_ids.device.type != "cpu" + or any( + type(frame) is not RuntimeCommandFrame + or any( + type(value) is not torch.Tensor + for value in (frame.active_mask, frame.env_ids, frame.hold_duration) + ) + or not all(_canonical_cpu_command(command) for command in frame.commands) + for frame in frames + ) + ): + return TimedCommandSequence(frames=tuple(frames), env_ids=env_ids) + sequence = TimedCommandSequence(frames=(), env_ids=env_ids) + for index, frame in enumerate(frames): + if frame.device != sequence.device: + raise ValueError(f"Frame {index} must share the sequence device.") + if not torch.equal(frame.env_ids, sequence.env_ids): + raise ValueError(f"Frame {index} env_ids do not match the sequence.") + object.__setattr__(sequence, "frames", tuple(frames)) + frames.clear() + return sequence + + __all__ = [ "EndpointCommand", "JointPositionPayload", diff --git a/embodichain/lab/sim/objects/backends/_numeric_observations.py b/embodichain/lab/sim/objects/backends/_numeric_observations.py new file mode 100644 index 0000000000..2c9e3ab47c --- /dev/null +++ b/embodichain/lab/sim/objects/backends/_numeric_observations.py @@ -0,0 +1,165 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- +"""Bounded shared native reads during a single World-owner planning boundary. + +Only Default CPU full-batch numeric reads are shared. Each consumer still +receives its own output buffer. Checked native writes invalidate all samples; +physics/topology revisions and scope exit prevent reuse across boundaries. +Raw SDK mutations and concurrent World writers are outside this internal +read-boundary contract. +""" + +from __future__ import annotations + +from collections.abc import Callable +from contextlib import contextmanager +from contextvars import ContextVar +from threading import get_ident +from typing import Any, Iterator, TYPE_CHECKING +import torch + +if TYPE_CHECKING: + from embodichain.lab.sim.sim_manager import SimulationManager + from embodichain.lab.sim.objects.robot import Robot + +__all__: list[str] = [] +_READS = frozenset( + ( + "fetch_pose", + "fetch_root_pose", + "fetch_link_pose", + "fetch_joint_position", + "fetch_joint_velocity", + "fetch_joint_force", + "fetch_linear_velocity", + "fetch_angular_velocity", + "fetch_root_linear_velocity", + "fetch_root_angular_velocity", + ) +) +_ACTIVE: ContextVar[_NumericReads | None] = ContextVar( + "native_numeric_reads", default=None +) + + +class _NumericReads: + def __init__( + self, batches: tuple[object, ...], revision: Callable[[], object] + ) -> None: + self.batches = {id(batch): batch for batch in batches} + self.revision: Callable[[], object] | None = revision + self.stamp = revision() + self.owner = get_ident() + self.closed = False + self.values: dict[tuple, tuple[torch.Tensor, Any]] = {} + + def refresh(self) -> bool: + """Check the owner/revision before accessing protected samples.""" + if self.closed or self.owner != get_ident() or self.revision is None: + return False + stamp = self.revision() + if stamp != self.stamp: + self.values.clear() + self.stamp = stamp + return True + + def key( + self, batch: object, method: str, args: tuple, kwargs: dict + ) -> tuple | None: + if not self.refresh(): + return None + if not method.startswith("fetch_"): + # Invalidate before a write, including partially failing writes. + self.values.clear() + return None + if ( + method not in _READS + or id(batch) not in self.batches + or len(args) != 1 + or kwargs + ): + return None + out = args[0] + if ( + type(out) is not torch.Tensor + or out.device.type != "cpu" + or out.requires_grad + or not out.is_contiguous() + ): + return None + return (id(batch), method, out.shape, out.dtype) + + +def shared_pose( + batch: object, to_matrix: bool, read: Callable[[], torch.Tensor] +) -> torch.Tensor: + """Own one derived pose representation and clone it for every consumer.""" + reads = _ACTIVE.get() + if reads is None or not reads.refresh() or id(batch) not in reads.batches: + return read() + key = ( + id(batch), + "derived_pose", + to_matrix, + torch.is_autocast_enabled("cpu"), + torch.get_autocast_dtype("cpu"), + ) + cached = reads.values.get(key) + if cached is not None: + return cached[0].clone() + value = read() + if ( + type(value) is torch.Tensor + and value.device.type == "cpu" + and not value.requires_grad + ): + reads.values[key] = (value.detach().clone(), None) + return value + + +@contextmanager +def numeric_observation_scope(sim: SimulationManager, robot: Robot) -> Iterator[None]: + """Share numeric samples only while this owner is gathering row commands.""" + if sim.physics_backend != "default" or sim.device.type != "cpu": + yield + return + batches = [robot._data.articulation_view.batch] + for uid in sim.get_rigid_object_uid_list(): + data = sim.get_rigid_object(uid)._data + if data is not None: + batches.append(data.body_view.batch) + reads = _NumericReads( + tuple(batches), + lambda: ( + sim.physics_step_index, + id(robot._data.articulation_view.scene), + robot._data.articulation_view.scene.topology_revision, + ), + ) + previous = _ACTIVE.get() + if previous is not None: + previous.values.clear() + token = _ACTIVE.set(reads) + try: + yield + finally: + reads.values.clear() + reads.closed = True + reads.batches.clear() + reads.revision = None + _ACTIVE.reset(token) + if previous is not None: + previous.values.clear() diff --git a/embodichain/lab/sim/objects/backends/scene.py b/embodichain/lab/sim/objects/backends/scene.py index 1a7967773b..3ea1daf78c 100644 --- a/embodichain/lab/sim/objects/backends/scene.py +++ b/embodichain/lab/sim/objects/backends/scene.py @@ -34,6 +34,7 @@ import torch from .base import ArticulationViewBase, RigidBodyViewBase +from ._numeric_observations import _ACTIVE if TYPE_CHECKING: from dexsim.scene import ( @@ -57,12 +58,20 @@ def _checked_batch_call( **kwargs: Any, ) -> Any: """Call one Scene batch operation and reject native failure statuses.""" + reads = _ACTIVE.get() + key = None if reads is None else reads.key(batch, method_name, args, kwargs) + if key is not None and key in reads.values: + saved, status = reads.values[key] + args[0].copy_(saved) + return status status = getattr(batch, method_name)(*args, **kwargs) if isinstance(status, Integral) and status < 0: raise RuntimeError( f"DexSim Scene batch operation {method_name!r} failed with " f"status {status}." ) + if key is not None: + reads.values[key] = (args[0].detach().clone(), status) return status diff --git a/embodichain/lab/sim/objects/rigid_object.py b/embodichain/lab/sim/objects/rigid_object.py index edb21f9eb7..c38d10eebd 100644 --- a/embodichain/lab/sim/objects/rigid_object.py +++ b/embodichain/lab/sim/objects/rigid_object.py @@ -36,6 +36,10 @@ is_newton_scene, ) from embodichain.lab.sim.objects.backends.base import RigidBodyViewBase +from embodichain.lab.sim.objects.backends._numeric_observations import ( + _ACTIVE as _NUMERIC_READS, + shared_pose, +) from embodichain.lab.sim.objects.backends.rigid_physics import ( _set_default_spawn_friction, apply_legacy_physical_attr, @@ -853,6 +857,21 @@ def get_local_pose_cpu( if self.is_static: return get_local_pose_cpu(self._entities, to_matrix).to(self.device) + if ( + type(self) is RigidObject + and type(to_matrix) is bool + and self._data is not None + and _NUMERIC_READS.get() is not None + ): + return shared_pose( + self._data.body_view.batch, + to_matrix, + lambda: RigidObject._read_dynamic_local_pose(self, to_matrix), + ) + return RigidObject._read_dynamic_local_pose(self, to_matrix) + + def _read_dynamic_local_pose(self, to_matrix: bool) -> torch.Tensor: + """Convert the current native pose without sharing caller-owned storage.""" pose = self.body_data.pose.clone() if to_matrix: xyz = pose[:, :3] diff --git a/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py b/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py index 7c2f41a69a..2dd6230673 100644 --- a/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py +++ b/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py @@ -16,6 +16,9 @@ from __future__ import annotations +from contextlib import contextmanager, nullcontext +from collections.abc import Iterator, Callable + import numpy as np import open3d as o3d import torch @@ -28,6 +31,60 @@ __all__ = ["GripperCollisionCfg", "GripperCollisionChecker"] +_NATIVE_POINT_QUERY = ConvexCollisionChecker.query_batch_points + + +@contextmanager +def _cpu_query_device( + checker: ConvexCollisionChecker, +) -> Iterator[tuple[torch.device, Callable]]: + """Keep a query's existing CUDA computation resident with bounded scratch. + + CPU transforms, every surface sample and the signed-distance kernel are + unchanged. Inputs are copied afresh per query; no mutable geometry is cached + across calls. Scratch is released on its owning stream before scope exit. + """ + import warp as wp + from embodichain.compute.geometry._warp.convex_query import ( + convex_signed_distance_kernel, + ) + + device = torch.device("cuda", torch.cuda.current_device()) + planes = checker.plane_equations["plane_equations"].to(device).clone() + counts = checker.plane_equations["plane_equation_counts"].to(device).clone() + workspace = None + + def query( + points: torch.Tensor, *, collision_threshold: float + ) -> tuple[torch.Tensor, torch.Tensor]: + nonlocal workspace + gpu_points = points.to(device) + shape = (*points.shape[:2], planes.shape[0]) + if workspace is None or workspace.shape != shape: + workspace = None + workspace = wp.empty(shape, dtype=wp.float32, device=str(device)) + workspace.fill_(-float("inf")) + wp.launch( + convex_signed_distance_kernel, + dim=shape, + inputs=( + wp.from_torch(gpu_points), + wp.from_torch(planes), + wp.from_torch(counts), + ), + outputs=(workspace,), + device=str(device), + ) + distance = wp.to_torch(workspace).min(dim=-1).values + return distance <= collision_threshold, distance + + with wp.ScopedStream(wp.stream_from_torch(torch.cuda.current_stream(device))): + try: + yield device, query + finally: + workspace = None + + @configclass class GripperCollisionCfg: """Target-object decomposition settings, independent of gripper geometry.""" @@ -76,6 +133,10 @@ def query( ) -> tuple[torch.Tensor, torch.Tensor]: """Reduce finite mesh-surface queries at canonical grasp poses. + CPU inputs retain CPU transforms and the existing CUDA classification. + Native multi-chunk queries keep geometry and reductions on that device + for one call; every original sample and chunk bound is preserved. + Args: obj_pose: World pose of the target mesh, shape ``(4, 4)``. grasp_poses: World canonical contact poses, shape ``(B, 4, 4)``. @@ -111,44 +172,62 @@ def _query_chunks( """Reduce all samples with bounded candidate/point/hull intermediates.""" relative = torch.linalg.inv(obj_pose).unsqueeze(0) @ grasp_poses count = len(grasp_poses) - collided = torch.zeros(count, dtype=torch.bool, device=self.device) - distance = torch.full( - (count,), float("inf"), device=self.device, dtype=grasp_poses.dtype - ) ground = ( self.get_ground_height(obj_pose) if is_filter_ground_collision else None ) # Visualization holds at most one pose's surface and colors. batch_size = 1 if is_visual else candidate_chunk_size samples = self.surface_points.to(dtype=grasp_poses.dtype) - for start in range(0, count, batch_size): - end = min(start + batch_size, count) - display_points, display_flags = [], [] - for points in samples.split(point_chunk_size): - local = transform_points_mat(points, relative[start:end]) - flags, distances = self._checker.query_batch_points( - local, collision_threshold=collision_threshold - ) - if ground is not None: - world = transform_points_mat(points, grasp_poses[start:end]) - ground_distance = world[:, :, 2] - ground - flags = flags | (ground_distance < collision_threshold) - distances = torch.minimum(distances, ground_distance) - collided[start:end] |= flags.any(dim=1) - distance[start:end] = torch.minimum( - distance[start:end], distances.min(dim=1).values - ) + native_cpu = ( + count > 0 + and ( + count > candidate_chunk_size + or len(self.surface_points) > point_chunk_size + ) + and self.device.type == "cpu" + and not is_visual + and type(self._checker) is ConvexCollisionChecker + and getattr(self._checker.query_batch_points, "__func__", None) + is _NATIVE_POINT_QUERY + ) + scope = ( + _cpu_query_device(self._checker) + if native_cpu + else nullcontext((self.device, self._checker.query_batch_points)) + ) + with scope as (query_device, point_query): + collided = torch.zeros(count, dtype=torch.bool, device=query_device) + distance = torch.full( + (count,), float("inf"), device=query_device, dtype=grasp_poses.dtype + ) + for start in range(0, count, batch_size): + end = min(start + batch_size, count) + display_points, display_flags = [], [] + for points in samples.split(point_chunk_size): + local = transform_points_mat(points, relative[start:end]) + flags, distances = point_query( + local, collision_threshold=collision_threshold + ) + if ground is not None: + world = transform_points_mat(points, grasp_poses[start:end]) + ground_distance = (world[:, :, 2] - ground).to(query_device) + flags = flags | (ground_distance < collision_threshold) + distances = torch.minimum(distances, ground_distance) + collided[start:end] |= flags.any(dim=1) + distance[start:end] = torch.minimum( + distance[start:end], distances.min(dim=1).values + ) + if is_visual: + display_points.append(local[0].cpu().numpy()) + display_flags.append(flags[0].cpu().numpy()) if is_visual: - display_points.append(local[0].cpu().numpy()) - display_flags.append(flags[0].cpu().numpy()) - if is_visual: - cloud = o3d.geometry.PointCloud() - displayed = np.concatenate(display_points) - flags_np = np.concatenate(display_flags) - cloud.points = o3d.utility.Vector3dVector(displayed) - colors = np.zeros_like(displayed) - colors[flags_np, 0] = 1 - colors[~flags_np, 1] = 1 - cloud.colors = o3d.utility.Vector3dVector(colors) - o3d.visualization.draw_geometries([self._checker.mesh, cloud]) - return collided, distance + cloud = o3d.geometry.PointCloud() + displayed = np.concatenate(display_points) + flags_np = np.concatenate(display_flags) + cloud.points = o3d.utility.Vector3dVector(displayed) + colors = np.zeros_like(displayed) + colors[flags_np, 0] = 1 + colors[~flags_np, 1] = 1 + cloud.colors = o3d.utility.Vector3dVector(colors) + o3d.visualization.draw_geometries([self._checker.mesh, cloud]) + return collided.to(self.device), distance.to(self.device) diff --git a/scripts/benchmark/expansion/runtime_comparison.py b/scripts/benchmark/expansion/runtime_comparison.py new file mode 100644 index 0000000000..8d8c00d0cd --- /dev/null +++ b/scripts/benchmark/expansion/runtime_comparison.py @@ -0,0 +1,449 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Compare sensor-free Task Program execution on pinned source trees. + +Run with --help. Results measure execution, not qualified dataset production. +""" + +from __future__ import annotations +import argparse +import json +import os +from pathlib import Path +import sys +import time +import resource +import subprocess +import cProfile +import pstats + + +def write_report(path: Path, rows: list[dict]) -> None: + """Write three tables, explicitly separating program acceptance from quality.""" + text = [ + "# Sensor-free execution diagnostic", + "", + ( + "Profiler enabled: these times diagnose hotspots and must not be compared as benchmark latency." + if any(row.get("profiled") for row in rows) + else "Profiler disabled." + ), + "", + "Cold execution; CPU Default physics and solvers, with legacy CUDA grasp classification included. Program acceptance is not physical qualification. No sensors, recording, external collision checks or persistence. Process RSS peaks include startup; their sum is an upper bound, not a simultaneous sampled peak.", + "", + "## Time & Memory", + "", + "| Scale | Mode | cost_time_ms | Action rows/s | Sum env.step s | Sum sim.update s | Sum peak RSS MiB | cpu_delta_mb | gpu_delta_mb | peak_gpu_mb |", + "|---|---|---:|---:|---:|---:|---:|---|---|---|", + ] + for row in rows: + text.append( + f"| {row['scale']} | {row['mode']} | {row['execution_s']*1000:.3f} | {row['action_rows']/row['execution_s']:.1f} | {row['env_step_s']:.3f} | {row['sim_update_s']:.3f} | {row['peak_rss_mib']:.1f} | N/A | N/A | N/A |" + ) + text += [ + "", + "## Success & Other Metrics", + "", + "| Scale | Mode | Attempts | Program accepted | Action rows |", + "|---|---|---:|---:|---:|", + ] + for row in rows: + text.append( + f"| {row['scale']} | {row['mode']} | {row['attempts']} | {row['accepted']} | {row['action_rows']} |" + ) + text += [ + "", + "## Leaderboard", + "", + "Ranked by program acceptance fraction only; modes with different action counts are not equal-work latency comparisons.", + "", + "| Rank | Scale | Mode | Program acceptance |", + "|---:|---|---|---:|", + ] + for i, row in enumerate( + sorted(rows, key=lambda r: r["accepted"] / max(r["attempts"], 1), reverse=True), + 1, + ): + text.append( + f"| {i} | {row['scale']} | {row['mode']} | {row['accepted']/max(row['attempts'],1):.3f} |" + ) + path.write_text("\n".join(text) + "\n") + + +def matrix_main() -> None: + """Run variants sequentially, with concurrent main workers per scale.""" + p = argparse.ArgumentParser() + p.add_argument("--matrix", action="store_true") + p.add_argument("--baseline-root", type=Path, required=True) + p.add_argument("--pr-root", type=Path, required=True) + p.add_argument("--output-dir", type=Path, required=True) + p.add_argument("--waves", type=int, default=2) + p.add_argument("--seeds", default="7") + p.add_argument("--scales", default="small,medium,large") + p.add_argument("--order", choices=("forward", "reverse"), default="forward") + a = p.parse_args() + a.output_dir.mkdir(parents=True, exist_ok=False) + cpus = sorted(os.sched_getaffinity(0))[:8] + os.sched_setaffinity(0, cpus) + settings = {"small": (1, 1), "medium": (2, 4), "large": (4, 8)} + rows = [] + for seed_index, seed in enumerate(map(int, a.seeds.split(","))): + for scale in a.scales.split(","): + w, b = settings[scale] + modes = ["cohort", "rolling-off", "rolling-on"] + if (seed_index % 2) ^ (a.order == "reverse"): + modes.reverse() + for mode in modes: + processes = [] + for worker in range(w if mode == "cohort" else 1): + name = f"{scale}-{mode}-seed{seed}-worker{worker}" + output = a.output_dir / (name + ".json") + log = (a.output_dir / (name + ".log")).open("w") + command = [ + sys.executable, + str(Path(__file__).resolve()), + "--root", + str(a.baseline_root if mode == "cohort" else a.pr_root), + "--mode", + mode, + "--rows", + str(b if mode == "cohort" else w * b), + "--groups", + str(1 if mode == "cohort" else w), + "--episodes", + str(a.waves * b if mode == "cohort" else a.waves * w * b), + "--seed", + str(seed), + "--output", + str(output), + ] + process = subprocess.Popen( + command, + stdout=log, + stderr=subprocess.STDOUT, + env={ + **os.environ, + "OMP_NUM_THREADS": "1", + "MKL_NUM_THREADS": "1", + "PYTHONHASHSEED": "0", + "SDL_VIDEODRIVER": "offscreen", + }, + ) + processes.append((process, log, output)) + failed = [] + for process, log, output in processes: + code = process.wait() + log.close() + if code: + failed.append(str(output.with_suffix(".log"))) + if failed: + raise RuntimeError(f"Workers failed: {failed}") + reports = [json.loads(output.read_text()) for _, _, output in processes] + episodes = [e for report in reports for e in report["episodes"]] + row = { + "scale": scale, + "mode": mode, + "seed": seed, + "execution_s": max(r["execution_end"] for r in reports) + - min(r["execution_start"] for r in reports), + "env_step_s": sum(r["env_step_s"] for r in reports), + "sim_update_s": sum(r["sim_update_s"] for r in reports), + "peak_rss_mib": sum(r["peak_rss_mib"] for r in reports), + "attempts": len(episodes), + "accepted": sum(e["program_accepted"] for e in episodes), + "action_rows": sum(e["steps"] for e in episodes), + } + rows.append(row) + (a.output_dir / "results.json").write_text( + json.dumps( + { + "cpu_affinity": cpus, + "initial_order": a.order, + "waves": a.waves, + "baseline_root": str(a.baseline_root), + "pr_root": str(a.pr_root), + "rows": rows, + }, + indent=2, + ) + ) + write_report(a.output_dir / "report.md", rows) + print(json.dumps(row), flush=True) + + +def main() -> None: + """Execute a bounded real-physics diagnostic in one isolated process.""" + p = argparse.ArgumentParser(description=__doc__) + p.add_argument("--root", type=Path, required=True) + p.add_argument( + "--mode", choices=["cohort", "rolling-off", "rolling-on"], required=True + ) + p.add_argument("--rows", type=int, default=1) + p.add_argument("--groups", type=int, default=1) + p.add_argument("--episodes", type=int, default=1) + p.add_argument("--seed", type=int, default=7) + p.add_argument("--output", type=Path, required=True) + p.add_argument( + "--profile", + action="store_true", + help="Profile execution only; these times are not benchmark results.", + ) + a = p.parse_args() + root = a.root.resolve() + sys.path[:0] = [ + str(root), + str(root / "extensions/embodichain_tasks"), + str(root / "extensions/embodichain_robots"), + ] + import torch + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.sim import SimulationManager + from embodichain.utils.utility import load_config + from embodichain.lab.expansion.program import collect_program_batch + + torch.set_num_threads(1) + path = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml" + ) + discover_task_packages() + execute_init_hooks() + cfg = config_to_cfg(load_config(path), source_path=path) + cfg.num_envs = cfg.sim_cfg.num_envs = a.rows + cfg.sim_cfg.device = "cpu" + cfg.sim_cfg.headless = True + cfg.sim_cfg.render_cfg.renderer = "no-render" + cfg.sensor = [] + cfg.enable_sensor = False + cfg.dataset = None + cfg.init_rollout_buffer = cfg.record_trajectory = False + timings = {"env_step_s": 0.0, "reset_s": 0.0} + sim_time = [0.0] + episodes = [] + adapters = {} + env = None + start = time.perf_counter() + try: + env = REGISTERED_ENVS[load_config(path)["id"]].make(cfg=cfg) + assert env.sim.physics_backend == "default" + assert not env.sim.get_sensor_uid_list(), env.sim.get_sensor_uid_list() + env.reset(seed=a.seed) + program = env.compile_task_program(cfg.task_program) + step = env.step + reset = env.reset + + def timed_step(*args, **kwargs): + tick = time.perf_counter() + try: + return step(*args, **kwargs) + finally: + timings["env_step_s"] += time.perf_counter() - tick + + def timed_reset(*args, **kwargs): + tick = time.perf_counter() + try: + return reset(*args, **kwargs) + finally: + timings["reset_s"] += time.perf_counter() - tick + + env.step = timed_step + env.reset = timed_reset + update = env.sim.update + + def timed_update(*args, **kwargs): + tick = time.perf_counter() + try: + return update(*args, **kwargs) + finally: + sim_time[0] += time.perf_counter() - tick + + env.sim.update = timed_update + setup = time.perf_counter() - start + + def bridge(row): + adapter = env.task_program_adapter.for_env_ids((row,)) + adapters[row] = adapter + return adapter.create_bridge(program, isolate_policy_sessions=True) + + def completed(result): + for row, length, accepted, reason in zip( + result.env_ids, result.lengths, result.accepted, result.reasons + ): + episodes.append( + { + "row": row, + "steps": length, + "program_accepted": accepted, + "reason": reason, + } + ) + adapters.pop(row).close() + + profiler = cProfile.Profile() if a.profile else None + cpu_before = resource.getrusage(resource.RUSAGE_SELF) + if profiler is not None: + profiler.enable() + begin = time.perf_counter() + before = env.sim.physics_step_index + planning = {} + if a.mode == "cohort": + remaining = a.episodes + while remaining: + n = min(a.rows, remaining) + env.reset(seed=a.seed, options={"save_data": False}) + # Same minimum settling, at ordinary environment cadence. + from embodichain.lab.gym.envs.types import ControllerAction + + physical = env.sim.physics_step_index + while env.sim.physics_step_index - physical < 5: + env.step(ControllerAction(env.robot.get_qpos(target=True).clone())) + env._elapsed_steps[:] = 0 + env._reset_physical_objective(tuple(range(n))) + result = collect_program_batch( + env, + {r: bridge(r) for r in range(n)}, + max_steps=1200, + observe_step=lambda *args: None, + ) + completed(result) + remaining -= n + else: + from embodichain.lab.expansion.workloads import ( + WorkloadProgramExecutor, + WorkloadExecutionCfg, + ExpansionWorkloadCfg, + ) + + class Source: + def prepare(self, assignments): + pass + + def activate(self, assignment, observation): + return bridge(assignment.env_id) + + def started(self, assignment, boundary): + pass + + def observe(self, assignments, action, observation): + return () + + def complete(self, result): + completed(result.program) + # No persistence in this diagnostic: never fabricate receipts. + return None + + assert a.rows % a.groups == 0 and a.episodes % a.groups == 0 + count = a.episodes // a.groups + executor = WorkloadProgramExecutor( + env, + [ + ExpansionWorkloadCfg(f"g{i}", count, count, 3600) + for i in range(a.groups) + ], + Source(), + WorkloadExecutionCfg( + workload_count=a.groups, + batch_size=a.rows // a.groups, + max_steps=1200, + settling_steps=5, + seed=a.seed, + batch_planning=a.mode == "rolling-on", + ), + ) + outcome = executor.run() + planning = outcome["planning"] + elapsed = time.perf_counter() - begin + if profiler is not None: + profiler.disable() + cpu_after = resource.getrusage(resource.RUSAGE_SELF) + report = { + "mode": a.mode, + "rows": a.rows, + "seed": a.seed, + "setup_s": setup, + "execution_s": elapsed, + "profiled": a.profile, + "physics_backend": env.sim.physics_backend, + "physics_device": str(env.sim.device), + "solver_devices": { + name: str(solver.device) for name, solver in env.robot._solvers.items() + }, + "grasp_collision_device_policy": "legacy current CUDA device", + "cuda_visible_devices": os.environ.get("CUDA_VISIBLE_DEVICES"), + "cuda_device_after_execution": ( + torch.cuda.current_device() if torch.cuda.is_initialized() else None + ), + "process_cpu_s": cpu_after.ru_utime + + cpu_after.ru_stime + - cpu_before.ru_utime + - cpu_before.ru_stime, + "execution_start": begin, + "execution_end": begin + elapsed, + "sim_update_s": sim_time[0], + "peak_rss_mib": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024, + **timings, + "remaining_execution_s": elapsed - sum(timings.values()), + "physics_substeps": env.sim.physics_step_index - before, + "episodes": episodes, + "planning": planning, + "sensors": env.sim.get_sensor_uid_list(), + "scope": "cold execution including planning, preparation and env.step; no sensors, external collision qualification, media, artifact persistence or export; program acceptance is not physical qualification", + } + a.output.parent.mkdir(parents=True, exist_ok=True) + if profiler is not None: + profiler.dump_stats(str(a.output.with_suffix(".pstats"))) + with a.output.with_suffix(".profile.txt").open("w") as stream: + stream.write( + "Profiled execution only. Cumulative times overlap; greenlet switching can distort caller attribution. Use leaf self-times and call counts, not sums of cumulative times.\n" + ) + stats = pstats.Stats(profiler, stream=stream) + stats.sort_stats("tottime").print_stats(70) + stats.sort_stats("cumulative").print_stats(70) + a.output.write_text(json.dumps(report, indent=2)) + write_report( + a.output.with_suffix(".md"), + [ + { + **report, + "scale": str(a.rows), + "attempts": len(episodes), + "accepted": sum(e["program_accepted"] for e in episodes), + "action_rows": sum(e["steps"] for e in episodes), + } + ], + ) + print( + json.dumps( + {k: v for k, v in report.items() if k not in ("episodes", "planning")} + ), + flush=True, + ) + finally: + for adapter in adapters.values(): + adapter.close() + if env is not None: + env.close(exit_process=False) + SimulationManager.flush_cleanup_queue() + + +if __name__ == "__main__": + matrix_main() if "--matrix" in sys.argv else main() diff --git a/tests/sim/atomic_skills/test_core.py b/tests/sim/atomic_skills/test_core.py index 26cc228128..7c8f36ebc2 100644 --- a/tests/sim/atomic_skills/test_core.py +++ b/tests/sim/atomic_skills/test_core.py @@ -1039,8 +1039,12 @@ def test_public_plan_authorizes_raw_action_plan_destinations() -> None: action.plan(request, context) -def test_command_target_authorization_rejects_altered_joint_claims() -> None: +@pytest.mark.parametrize( + "device", ["cpu", pytest.param("cuda:0", marks=pytest.mark.gpu)] +) +def test_command_target_authorization_rejects_altered_joint_claims(device: str) -> None: context = _context() + env_ids = context.env_ids.to(device) request = ResolvedSkillRequest( skill_id="dependency_test", goal=EndEffectorPoseGoal(SceneEntityPose("tracked")), @@ -1065,20 +1069,42 @@ def test_command_target_authorization_rejects_altered_joint_claims() -> None: commands=( EndpointCommand( target=JointPositionTarget("arm", (2, 3)), - payload=JointPositionPayload(torch.ones(2, 2)), + payload=JointPositionPayload(torch.ones(2, 2, device=device)), ), ), - active_mask=torch.ones(2, dtype=torch.bool), - env_ids=context.env_ids, - hold_duration=torch.full((2,), 0.1), + active_mask=torch.ones(2, dtype=torch.bool, device=device), + env_ids=env_ids, + hold_duration=torch.full((2,), 0.1, device=device), ) with pytest.raises(ValueError, match="bound joint-position target"): _DependencyAction._authorize_command_targets( request, - TimedCommandSequence(frames=(frame,), env_ids=context.env_ids), + TimedCommandSequence(frames=(frame,), env_ids=env_ids), ) + commands = _command_sequence(env_ids=env_ids, frame_count=2) + owned = _DependencyAction._authorize_command_targets(request, commands) + commands.frames[0].commands[0].payload.positions.fill_(99) + torch.testing.assert_close( + owned.frames[0].commands[0].payload.positions, torch.ones(2, 2, device=device) + ) + owned.frames[0].commands[0].payload.positions.fill_(55) + torch.testing.assert_close( + owned.frames[1].commands[0].payload.positions, + torch.full((2, 2), 2.0, device=device), + ) + owned.frames[0].commands[0].payload.positions[0, 0] = float("nan") + with pytest.raises(ValueError, match="finite"): + owned.snapshot() + commands.frames[1].commands[0].payload.positions[0, 0] = float("nan") + with pytest.raises(ValueError, match="finite"): + _DependencyAction._authorize_command_targets(request, commands) + commands.frames[1].commands[0].payload.positions.fill_(2) + commands.frames[0].hold_duration.fill_(-1) + with pytest.raises(ValueError, match="non-negative"): + _DependencyAction._authorize_command_targets(request, commands) + def test_command_target_authorization_rejects_custom_claim_conflicts() -> None: context = _context() diff --git a/tests/sim/atomic_skills/test_runtime_commands.py b/tests/sim/atomic_skills/test_runtime_commands.py index 14ad1a673c..45c3ed4b95 100644 --- a/tests/sim/atomic_skills/test_runtime_commands.py +++ b/tests/sim/atomic_skills/test_runtime_commands.py @@ -411,3 +411,32 @@ def test_timed_command_sequence_requires_nonempty_int64_batch() -> None: TimedCommandSequence(frames=(), env_ids=torch.tensor([0.0])) with pytest.raises(ValueError, match="unique"): TimedCommandSequence(frames=(), env_ids=torch.tensor([2, 2])) + + +def test_joint_target_snapshot_revalidates_and_preserves_custom_ownership() -> None: + original = JointPositionTarget("arm", (0, 1)) + copied = original.snapshot() + assert copied == original and copied is not original + object.__setattr__(original, "joint_ids", (0, 0)) + with pytest.raises(ValueError, match="unique"): + original.snapshot() + + @dataclass(frozen=True, slots=True) + class ExtendedTarget(JointPositionTarget): + metadata: list[int] + + custom = ExtendedTarget("arm", (0, 1), [3]) + snapshot = custom.snapshot() + assert type(snapshot) is ExtendedTarget + snapshot.metadata[0] = 7 + assert custom.metadata == [3] + + class AnnotatedName(str): + pass + + name = AnnotatedName("arm") + name.annotations = [1] + named = JointPositionTarget(name, (0, 1)) + named_copy = named.snapshot() + named_copy.control_part.annotations.append(2) + assert named.control_part.annotations == [1] diff --git a/tests/sim/objects/test_scene_backend.py b/tests/sim/objects/test_scene_backend.py index ede7d95d4e..52697d00b4 100644 --- a/tests/sim/objects/test_scene_backend.py +++ b/tests/sim/objects/test_scene_backend.py @@ -1400,3 +1400,105 @@ class RebuiltScene: rigid.get_friction([0]) assert factory.call_count == 2 assert factory.call_args.args[0] is rebuilt + + +def test_numeric_boundary_owns_samples_and_invalidates_writes_and_revisions() -> None: + from contextvars import copy_context + from embodichain.lab.sim.objects.backends._numeric_observations import ( + numeric_observation_scope, + shared_pose, + ) + from embodichain.lab.sim.objects.backends.scene import _checked_batch_call + + class Batch: + def __init__(self): + self.value = torch.ones(2, 3) + self.reads = 0 + + def fetch_joint_position(self, out): + self.reads += 1 + out.copy_(self.value) + return 2 + + def apply_joint_position(self, value): + self.value.copy_(value) + return 2 + + def apply_failed(self): + self.value.fill_(9) + raise RuntimeError("partial native write") + + batch = Batch() + sim = SimpleNamespace( + physics_backend="default", + device=torch.device("cpu"), + physics_step_index=0, + _spawn_scene=SimpleNamespace(topology_revision=0), + get_rigid_object_uid_list=lambda: (), + ) + robot = SimpleNamespace( + _data=SimpleNamespace( + articulation_view=SimpleNamespace(batch=batch, scene=sim._spawn_scene) + ) + ) + + def read(): + out = torch.empty(2, 3) + assert _checked_batch_call(batch, "fetch_joint_position", out) == 2 + return out + + with numeric_observation_scope(sim, robot): + escaped = copy_context() + first = read() + first.fill_(77) + torch.testing.assert_close(copy_context().run(read), torch.ones(2, 3)) + assert batch.reads == 1 + derived_calls = [] + + def derive(): + derived_calls.append(True) + return batch.value @ torch.eye(3) + 10 + + derived = shared_pose(batch, True, derive) + derived.fill_(88) + torch.testing.assert_close( + shared_pose(batch, True, derive), torch.full((2, 3), 11.0) + ) + assert len(derived_calls) == 1 + torch.testing.assert_close( + shared_pose(batch, False, lambda: batch.value.clone()), torch.ones(2, 3) + ) + _checked_batch_call(batch, "apply_joint_position", torch.full((2, 3), 2.0)) + torch.testing.assert_close(read(), torch.full((2, 3), 2.0)) + assert batch.reads == 2 + torch.testing.assert_close( + shared_pose(batch, True, derive), torch.full((2, 3), 12.0) + ) + assert len(derived_calls) == 2 + with torch.autocast("cpu", dtype=torch.bfloat16): + torch.testing.assert_close( + shared_pose(batch, True, derive), + torch.full((2, 3), 12.0, dtype=torch.bfloat16), + ) + assert len(derived_calls) == 3 + sim.physics_step_index += 1 + batch.value.fill_(3) + assert read()[0, 0] == 3 and batch.reads == 3 + sim._spawn_scene.topology_revision += 1 + batch.value.fill_(4) + assert read()[0, 0] == 4 and batch.reads == 4 + with pytest.raises(RuntimeError, match="partial native"): + _checked_batch_call(batch, "apply_failed") + assert read()[0, 0] == 9 and batch.reads == 5 + with numeric_observation_scope(sim, robot): + _checked_batch_call(batch, "apply_joint_position", torch.full((2, 3), 6.0)) + assert read()[0, 0] == 6 + assert read()[0, 0] == 6 and batch.reads == 7 + # Same physics tick, new boundary: reset/prepare writes are never reused. + batch.value.fill_(8) + with numeric_observation_scope(sim, robot): + assert read()[0, 0] == 8 and batch.reads == 8 + batch.value.fill_(10) + assert escaped.run(read)[0, 0] == 10 and batch.reads == 9 + batch.value.fill_(11) + assert escaped.run(read)[0, 0] == 11 and batch.reads == 10 diff --git a/tests/toolkits/test_fixed_gripper_geometry.py b/tests/toolkits/test_fixed_gripper_geometry.py index 27f1d5b1c4..260da1014e 100644 --- a/tests/toolkits/test_fixed_gripper_geometry.py +++ b/tests/toolkits/test_fixed_gripper_geometry.py @@ -232,3 +232,64 @@ def test_authored_collision_box_preserves_physical_pad_dimensions( assert geometry.provenance["parts"][0]["geometry_kind"] == "urdf_box" assert geometry.provenance["parts"][0]["mesh_path"] is None assert len(geometry.provenance["files_sha256"]) == 1 + + +@pytest.mark.gpu +def test_native_cpu_chunks_keep_all_samples_and_owned_results_across_streams() -> None: + import warp as wp + + wp.init() + from types import SimpleNamespace + from embodichain.toolkits.graspkit.pg_grasp.collision_checker import ( + ConvexCollisionChecker, + ) + + convex = object.__new__(ConvexCollisionChecker) + convex.device = torch.device("cpu") + normals = torch.cat((torch.eye(3), -torch.eye(3))) + convex.plane_equations = { + "plane_equations": torch.cat((normals, torch.full((6, 1), -0.1)), dim=1)[None], + "plane_equation_counts": torch.tensor([6], dtype=torch.int32), + } + checker = object.__new__(GripperCollisionChecker) + checker.device = torch.device("cpu") + checker._checker = convex + checker.obj_mesh_verts = torch.zeros(1, 3, dtype=torch.float64) + x = torch.linspace(-0.3, 0.3, 1025) + checker.surface_points = torch.stack((x, x.flip(0), x * 0.5), dim=-1) + poses = torch.eye(4).repeat(258, 1, 1)[::2] + poses[:, 0, 3] = torch.linspace(0, 0.5, len(poses)) + stream = torch.cuda.Stream() + for ground in (False, True): + for threshold in (0.0, -0.02, 0.02): + checker._checker = SimpleNamespace( + query_batch_points=convex.query_batch_points + ) + expected = checker.query( + torch.eye(4), + poses, + collision_threshold=threshold, + is_filter_ground_collision=ground, + ) + checker._checker = convex + with torch.cuda.stream(stream): + actual = checker.query( + torch.eye(4), + poses, + collision_threshold=threshold, + is_filter_ground_collision=ground, + ) + for value, reference in zip(actual, expected): + assert value.device.type == "cpu" + torch.testing.assert_close(value, reference, rtol=0, atol=0) + # Each query observes new geometry, and later scratch reuse cannot alter + # already returned results. Expand the box to encompass a distant pose. + old = checker.query(torch.eye(4), poses, is_filter_ground_collision=False) + saved = tuple(value.clone() for value in old) + convex.plane_equations["plane_equations"][..., 3] = -1.0 + changed = checker.query(torch.eye(4), poses, is_filter_ground_collision=False) + assert changed[0].all() and not old[0].all() + for value, reference in zip(old, saved): + torch.testing.assert_close(value, reference, rtol=0, atol=0) + empty = checker.query(torch.eye(4), poses[:0], is_filter_ground_collision=False) + assert empty[0].numel() == empty[1].numel() == 0 From 504f44f7152cfdf67024f6f8cd2f6f6737e5f79f Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 08:45:13 +0000 Subject: [PATCH 07/49] docs(expansion): document native ghost preview and WebRTC follow-up --- examples/expansion/engine/README.md | 8 ++ examples/expansion/engine/ghost-preview.md | 122 +++++++++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 examples/expansion/engine/ghost-preview.md diff --git a/examples/expansion/engine/README.md b/examples/expansion/engine/README.md index 1a01cc0565..2b902ff70a 100644 --- a/examples/expansion/engine/README.md +++ b/examples/expansion/engine/README.md @@ -24,6 +24,14 @@ for measured 3D/RGB-D comparisons, per-capability checks, recovery diagnostics a portable dataset verification. `--mode quick` samples a smaller subset; unrun capabilities remain explicit. `--reuse` rebuilds the offline page without a World. +## Native ghost preview + +See [the native ghost-preview notes](ghost-preview.md) for the existing SDK +window comparison, the separately validated eight-result browser prototype, +linked spatial/affordance/trajectory filters, and the native WebRTC follow-up. +The prototype uses native offscreen rendering with HTTP JPEG transport; it is +not a WebRTC entry point or a released general-purpose viewer. + ## Run a configured job From the repository root, with the simulation dependencies installed: diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md new file mode 100644 index 0000000000..3d538376d0 --- /dev/null +++ b/examples/expansion/engine/ghost-preview.md @@ -0,0 +1,122 @@ +# 扩增分布的原生虚影预览 + +本文记录空间、affordance 与轨迹分布的交互预览方案,以及 2026-11-15 完成的 +小规模原型验收。它补充 [Expansion Engine](README.md) 的结果查看流程。 + +## 当前能力与边界 + +| 路径 | 渲染与交互 | 状态 | +| --- | --- | --- | +| SDK 原生窗口对照 | `preview_expansion_comparison` 加载已验收轨迹,显示参考与选中虚影;N 切换、Space 暂停、Q 关闭 | 仓库已有能力,见 [comparison.py](../../../embodichain/lab/expansion/comparison.py) | +| 独立浏览器原型 | EmbodiChain 原生离屏渲染完整模型;HTTP JPEG 传图,HTTP 控制筛选与回放 | 已完成本地验收,尚未整理为仓库通用入口 | +| 原生 WebRTC 推流 | 复用 EmbodiChain 的原生推流生命周期与控制接口 | TODO,尚未接入本预览 | + +“原生渲染”指场景由 `SimulationManager`、`RobotMarkers`、 +`VisualizationMarkers` 和 DexSim Hybrid 渲染器生成,**不表示采用 WebRTC**。 +浏览器原型没有自行绘制机器人骨架,也不使用 Viser 重建场景;它显示原生离屏 +相机输出的 JPEG。本次使用 OptiX 去噪。展示灯光、视角和透明材质与采集时可以不同, +不能把预览图片当作采集传感器的原始观测。 + +独立原型使用采集时冻结的源码 `ab04d972b5b75042434498db9a889b4edd03b6fe`。 +本文新增的是说明与验收记录,不把本地脚本、机器路径或录制产物包装成已发布 SDK API。 +[showcase](showcase/README.md) 的离线三维/RGB-D 页面也是另一条查看路径。 + +## 配方与真实结果 + +使用已有 `task.default.yaml` 的单轮 UR5 + DH PGI 抓取放置任务和 default 物理后端。 +原型关闭传感器媒体采集与数据集导出,保留原有 lift/place/release 等独立校验。 + +| 维度 | 小规模设置 | +| --- | --- | +| 参考 | 方块初始位置 `[-0.42, -0.08, 0.025]` m,1 条轨迹 | +| 空间 S-A | `[-0.435, -0.08, 0.025]` m | +| 空间 S-B | `[-0.405, -0.08, 0.025]` m | +| Affordance | 每个空间 2 个抓取配方分支;`max_proposals: 8` | +| 轨迹 | 每个分支 2 个变体:名义规划和 `joint_residual`,扰动尺度 `0.002` | +| 扩增总数 | 2 × 2 × 2 = 8 条,另加 1 条参考 | +| 执行 | 扩增批大小 2,参考批大小 1,随机种子 7 | + +两个空间位置通过分别冻结的环境配置定义;本次没有启用场景随机化算子, +也没有验证场景扩增引擎的分布采样。2 个位置不能代表连续空间覆盖率。 + +9 条轨迹均通过原有校验并确认回执,共保留 3642 个原始状态帧。 +该结果只代表这个固定小配方,不代表更大规模、其他任务或其他后端的资格结论。 + +## 数据到画面的运行逻辑 + +1. 读取 `ArtifactEpisodeSink` 的确认回执,并通过 `load_expansion_episode` + 加载已验收的真实结果;不重新规划或执行扩增。 +2. 核对 episode 身份、机器人模型、关节名称与顺序,以及动作和状态的 T+1 对齐。 + 加载逐帧完整关节位置、机器人根位姿、物体位姿和时间戳。 +3. 使用与记录匹配的 URDF 和实测关节计算 FK,驱动 `RobotMarkers` 的完整视觉网格。 + 选中样本显示原始模型外观,其余可见候选显示半透明虚影;参考单独开关。 +4. 用真实物体位姿驱动物体模型,并通过 `VisualizationMarkers` 显示初始位置、 + 抓取目标坐标轴和末端路径。 +5. 在仿真/渲染所有者线程应用筛选与回放状态,调用原生相机渲染。 + HTTP 线程只排队控制消息和读取已发布画面,不直接访问仿真对象。 +6. 页面读取 JPEG 并展示对应记录信息。关闭服务时释放相机、场景和监听端口; + 已提交轨迹与校验结果保持不变。 + +原型回放不调用物理推进,验收记录的物理步数为 0。回放不是新物理成功样本, +也不生成新的成功回执。 + +## 联动筛选与时间语义 + +空间、affordance、轨迹三个筛选器取交集,同时作用于候选列表、虚影、物体、 +初始位置、抓取目标和轨迹线。选中样本被筛掉时,选择交集内的一个有效样本。 +这个固定配方的组合完整,因此没有空交集;通用化时必须显式处理空结果。 +参考轨迹是独立对照,不计入 8 条候选数量,也不受候选筛选限制。 + +- **空间**:显示实际初始位置,不给样本添加人为排列偏移。 +- **Affordance**:A0/A1 是配方分支编号,不是底层候选 ID。读取规划诊断时按实际 + `env_id` 选择批内对应行,再取得抓取目标与候选 ID,不能默认使用第 0 行。 + 先用 `inverse(reference_pose) @ selected_pose` 得到物体局部抓取目标,再用 + 实际初始物体位姿转换到世界坐标。坐标轴展示规划目标,不是实测接触点; + 原型把它固定在初始抓取位置,不随搬运中的方块移动。 +- **轨迹**:V0/V1 来自执行元数据中的实际选择。末端路径由实测关节 FK 推导, + 原型轨迹线每 4 帧取点并保留末帧;机器人和物体回放仍可访问全部原始状态帧。 +- **时间**:支持公共真实时间或六个记录动作阶段的归一化对齐。每个样本取目标 + 时刻之前最近的已记录帧,不插值生成新姿态;短轨迹到末帧后保持。 + 阶段对齐只改变浏览进度映射,不改变原始时间戳。页面保留实际秒数和源帧号。 + +## 验收与当前限制 + +本地浏览器验收覆盖:筛选数量 8 → 4 → 2 → 1,筛选后原生画面改变, +时间拖动与播放、虚影开关、相机视角切换、窄屏布局和非法控制值拒绝。 +浏览器无脚本错误,回放全过程未推进物理。验收后服务已关闭,结果保留。 + +原型脚本及结果保存在本次实验的 `real-demo` 目录: + +| 文件 | 用途 | +| --- | --- | +| `recipe.yaml`、`configs/`、`results/` | 固定配方、环境设置、真实产物与回执 | +| `build_data.py`、`preview-data.json` | 从产物提取显示数据并验证对应关系 | +| `native_preview.py`、`native-preview.html` | 原生渲染服务和浏览器交互页面 | +| `native-assets/` | 对应采集模型的 URDF 与视觉资产副本 | +| `native-acceptance.json`、`native-preview-acceptance.png` | 浏览器验收结果和原生渲染截图 | + +这些文件不是仓库已安装入口。已有实验目录中可用兼容的 EmbodiChain/DexSim +Python 环境运行 `python native_preview.py --gpu GPU_ID --port PORT`,然后访问该机器的 +loopback 地址;远程访问需要端口转发。Ctrl+C 关闭服务。原型默认端口 8769, +默认渲染 GPU 4,设备编号需按部署环境调整;不要从仓库根目录直接执行此命令。 +原型仍依赖实验目录中的冻结源码、配置与产物路径,不是便携式数据查看器。 + +HTTP JPEG 轮询不提供 WebRTC 的编码、拥塞控制、连接恢复或低延迟保证。 +页面是单个服务的共享回放会话,多人操作会改变同一状态;尚未提供独立会话、 +认证、任意配方加载、大规模分页或通用资产恢复。当前不应对外公开监听。 + +## TODO:接入 EmbodiChain 原生 WebRTC 推流 + +后续直接复用 EmbodiChain 原生 WebRTC 能力,替换 HTTP JPEG 轮询;先核对实际 +推流入口、信令与关闭接口,不在本示例另建一套独立 WebRTC 栈。 +保留真实结果加载、原生场景、三类筛选联动、播放、时间轴及视角控制。 +控制通道的实现需按原生接口确定,不能预先宣称已经通过 DataChannel 接入。 + +验收条件: + +- 浏览器建立真实 WebRTC 连接并接收原生相机视频,确认画面不再依赖 JPEG 轮询。 +- 沿用这 8 条扩增结果和参考轨迹,复测筛选、拖动、暂停、切换视角及重新连接。 +- 控制状态、源帧和视频画面的对应关系可检查;显示延迟不冒充记录时间。 +- 回放物理步数仍为 0,不触发重采集、不修改原始证据或成功计数。 +- 关闭预览后释放推流、相机、端口及场景资源;记录端到端延迟与实际帧率, + 再据此报告改善,不能用传输协议名称推断性能。 From bddf4d72f821e3f0d68e615ee2e21669a5de436f Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 08:53:53 +0000 Subject: [PATCH 08/49] fix(physics): remove direct GPU API configuration override Restore the existing Default CUDA backend policy. Remove the newly introduced public selector and its ordinary-reporting test variant, retaining CPU contact permission coverage and documenting Direct GPU static-identity limits. Validation: 53 configuration/contact tests including CUDA and 42 context tests passed. Black 26.10.1, API docs and diff checks passed. --- .../topics/expansion-engine/workloads.md | 9 ++++----- .../topics/sensor-system/sensor-system.md | 5 ++--- embodichain/lab/sim/cfg/physics.py | 11 ----------- embodichain/lab/sim/physics/default.py | 2 +- tests/sim/sensors/test_contact_default_e2e.py | 16 ++++++---------- 5 files changed, 13 insertions(+), 30 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 6ca15ed63a..5c47c5d1a4 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -79,11 +79,10 @@ each native event state machine and receipts. `ContactPermissionChecker` checks all valid native contact slots with the original applied-impulse and loss gates; hosts still own sampling at every required physics substep. -Default GPU dynamics may use ordinary reporting with -`DefaultPhysicsCfg(direct_gpu_api=False)` when complete static contact identities -are needed. It retains GPU dynamics; the Direct GPU buffer initialization flag -alone is not a physics-device measurement. Physics devices and task qualification -must be reported separately. Existing CPU deployments do not switch devices. +Default GPU dynamics use Direct GPU reporting, whose static contact identity +limitations remain explicit admission constraints. Physics devices and task +qualification must be reported separately. Existing CPU deployments do not +switch devices. ## Focused validation diff --git a/agent_context/topics/sensor-system/sensor-system.md b/agent_context/topics/sensor-system/sensor-system.md index 91601b5073..f7ea125af8 100644 --- a/agent_context/topics/sensor-system/sensor-system.md +++ b/agent_context/topics/sensor-system/sensor-system.md @@ -131,9 +131,8 @@ choose the host's sampling frequency or relax unavailable-impulse/loss gates. Eager checks wait for the latest sensor sample on their CUDA stream without refreshing contacts or advancing histories. Global static actors retain their explicit row memberships. Rebind after query -topology changes. Default CUDA dynamics can select ordinary reporting through -`DefaultPhysicsCfg.direct_gpu_api=False` when static actor identity is required; -this is independent of the physics device and leaves CPU defaults unchanged. +topology changes. Default CUDA dynamics use Direct GPU reporting; its static +actor identity limitations remain explicit admission constraints. The contact scatter kernel remains sensor-owned because its columns, IDs and quota are integration contracts. Generic image tiling belongs to diff --git a/embodichain/lab/sim/cfg/physics.py b/embodichain/lab/sim/cfg/physics.py index c75ee86548..c04440966d 100644 --- a/embodichain/lab/sim/cfg/physics.py +++ b/embodichain/lab/sim/cfg/physics.py @@ -133,15 +133,6 @@ class PhysicsBackendCfg: class DefaultPhysicsCfg(PhysicsBackendCfg): """Configuration selector for the Default physics backend.""" - direct_gpu_api: bool = True - """Use Direct GPU state access when dynamics run on CUDA. - - False retains GPU dynamics with ordinary state/contact reporting. The - pinned Direct GPU contact API cannot identify static actors, so consumers - requiring complete contact identities must explicitly select False. - This option does not select the physics device or change contact sampling. - """ - cache_material: bool = False """Reuse identical physics materials across objects and environment clones. @@ -177,8 +168,6 @@ class DefaultPhysicsCfg(PhysicsBackendCfg): def __post_init__(self) -> None: """Decode mapping input for the nested GPU-memory configuration.""" - if type(self.direct_gpu_api) is not bool: - raise TypeError("direct_gpu_api must be a bool.") if isinstance(self.gpu_memory, Mapping): self.gpu_memory = GPUMemoryCfg(**self.gpu_memory) if not isinstance(self.gpu_memory, GPUMemoryCfg): diff --git a/embodichain/lab/sim/physics/default.py b/embodichain/lab/sim/physics/default.py index 078c82f00c..22d29c8d27 100644 --- a/embodichain/lab/sim/physics/default.py +++ b/embodichain/lab/sim/physics/default.py @@ -44,7 +44,7 @@ def configure_world(self, world_config, sim_config: "SimulationManagerCfg") -> N world_config.speed_tolerance = cfg.speed_tolerance if self._manager.device.type == "cuda": world_config.enable_gpu_sim = True - world_config.direct_gpu_api = cfg.direct_gpu_api + world_config.direct_gpu_api = True def activate(self, sim_config: "SimulationManagerCfg") -> None: cfg = sim_config.physics_cfg diff --git a/tests/sim/sensors/test_contact_default_e2e.py b/tests/sim/sensors/test_contact_default_e2e.py index 69997e0e36..9ba29a1d3c 100644 --- a/tests/sim/sensors/test_contact_default_e2e.py +++ b/tests/sim/sensors/test_contact_default_e2e.py @@ -35,19 +35,15 @@ @pytest.mark.parametrize( - ("device", "expected_contacts_per_env", "direct_gpu_api"), + ("device", "expected_contacts_per_env"), [ - pytest.param("cpu", 4, True, id="cpu"), - pytest.param("cuda:0", 4, True, marks=pytest.mark.gpu, id="cuda"), - pytest.param( - "cuda:0", 4, False, marks=pytest.mark.gpu, id="cuda-native-reports" - ), + pytest.param("cpu", 4, id="cpu"), + pytest.param("cuda:0", 4, marks=pytest.mark.gpu, id="cuda"), ], ) def test_default_contact_sensor_preserves_contact_multiplicity( device: str, expected_contacts_per_env: int, - direct_gpu_api: bool, ) -> None: wp.init() if device.startswith("cuda") and not wp.is_cuda_available(): @@ -58,7 +54,7 @@ def test_default_contact_sensor_preserves_contact_multiplicity( headless=True, num_envs=2, arena_space=2.0, - physics_cfg=DefaultPhysicsCfg(device=device, direct_gpu_api=direct_gpu_api), + physics_cfg=DefaultPhysicsCfg(device=device), ) ) try: @@ -117,9 +113,9 @@ def test_default_contact_sensor_preserves_contact_multiplicity( ) assert sim.is_use_gpu_physics == device.startswith("cuda") assert sim.get_world().get_physics_scene().is_direct_gpu() == ( - device.startswith("cuda") and direct_gpu_api + device.startswith("cuda") ) - if device == "cpu" or not direct_gpu_api: + if device == "cpu": maps = [{} for _ in range(2)] for uid in ("cube", "ground", "default_plane"): values = sensor.get_actor_ids(uid)[:, 0].cpu().tolist() From 24c21fbbdec3356e7d4f2fdbf53f0a5964df9552 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 09:01:37 +0000 Subject: [PATCH 09/49] feat(expansion): preview confirmed results with native ghost rendering --- .../expansion-engine/expansion-engine.md | 10 + embodichain/cli/expansion.py | 70 +++ embodichain/lab/expansion/_preview.html | 34 ++ embodichain/lab/expansion/_preview_data.py | 474 ++++++++++++++++++ embodichain/lab/expansion/_preview_render.py | 385 ++++++++++++++ embodichain/lab/expansion/_preview_server.py | 212 ++++++++ examples/expansion/engine/README.md | 16 +- examples/expansion/engine/ghost-preview.md | 79 ++- setup.py | 1 + tests/lab/expansion/test_preview.py | 316 ++++++++++++ 10 files changed, 1578 insertions(+), 19 deletions(-) create mode 100644 embodichain/lab/expansion/_preview.html create mode 100644 embodichain/lab/expansion/_preview_data.py create mode 100644 embodichain/lab/expansion/_preview_render.py create mode 100644 embodichain/lab/expansion/_preview_server.py create mode 100644 tests/lab/expansion/test_preview.py diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index cb2fe4abab..1155740b83 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -93,6 +93,16 @@ time; physics stays disabled and render updates do not mutate saved evidence. cross-group frame through the public marker layer. Task assets and any collection process orchestration remain outside the replay core. +`embodichain expansion preview` reads confirmed job outputs through `_preview_data.py`, +then replays full measured states using `_preview_render.py` and a loopback-only +`_preview_server.py`. Inputs retain their original evidence; no collection or +physics stepping occurs. The first version accepts one URDF robot and Cube rigid +objects with fixed layouts, and rejects unsupported geometry. Space filters group +input directories; missing motion annotations remain explicit. HTTP publishes a +single immutable image/state snapshot; WebRTC is follow-up work. FK and episode +budgets bound preload, controls are queued for the render owner, and native +resources/ports close on exit. See the example's `ghost-preview.md` for usage. + `TaskProgramDemoBridge.program_id` and `env_ids` expose binding identity without runtime traversal. `EmbodiedEnv.task_program_bridge_scope()` restores the borrowed bridge even after failure. `Real2SimTabletopSource` and explicit diff --git a/embodichain/cli/expansion.py b/embodichain/cli/expansion.py index 12166044e3..5c2ace7a7a 100644 --- a/embodichain/cli/expansion.py +++ b/embodichain/cli/expansion.py @@ -45,7 +45,77 @@ def main(argv: Sequence[str] | None = None) -> int: command.add_argument("--stage", choices=("all", "export"), default="all") command = commands.add_parser("inspect") command.add_argument("--output", required=True) + command = commands.add_parser( + "preview", help="Replay confirmed results with native ghost rendering" + ) + command.add_argument( + "--output", + action="append", + required=True, + help="Result directory with job.json; repeat for spatial groups", + ) + command.add_argument( + "--reference", + help="Optional result directory containing exactly one reference episode", + ) + command.add_argument( + "--robot-asset", help="Matching URDF override if recorded asset paths moved" + ) + command.add_argument( + "--eef-link", + help="URDF link used for measured FK paths; inferred from the solver when unique", + ) + command.add_argument("--gpu", type=int, default=0) + command.add_argument( + "--port", type=int, default=8769, help="Loopback port; 0 selects a free port" + ) + command.add_argument("--max-episodes", type=int, default=32) + command.add_argument( + "--duration", + type=float, + default=0, + help="Exit after these seconds; 0 waits for Ctrl+C", + ) + command.add_argument( + "--open", + action="store_true", + help="Open a browser after the first complete render", + ) args = parser.parse_args(argv) + if args.operation == "preview": + import math + from pathlib import Path + + if ( + not 0 <= args.port <= 65535 + or args.gpu < 0 + or not math.isfinite(args.duration) + or args.duration < 0 + ): + parser.error("invalid preview port, GPU or duration") + from embodichain.lab.expansion._preview_data import load_preview + from embodichain.lab.expansion._preview_server import serve_preview + + try: + data = load_preview( + [Path(p) for p in args.output], + Path(args.reference) if args.reference else None, + robot_asset=Path(args.robot_asset) if args.robot_asset else None, + eef_link=args.eef_link, + max_episodes=args.max_episodes, + ) + serve_preview( + data, + port=args.port, + gpu=args.gpu, + open_browser=args.open, + duration=args.duration, + ) + except KeyboardInterrupt: + return 0 + except (ValueError, OSError) as exc: + parser.error(str(exc)) + return 0 from embodichain.lab.expansion.configured import ( load_expansion_job, ) diff --git a/embodichain/lab/expansion/_preview.html b/embodichain/lab/expansion/_preview.html new file mode 100644 index 0000000000..ad53361468 --- /dev/null +++ b/embodichain/lab/expansion/_preview.html @@ -0,0 +1,34 @@ +EmbodiChain · 扩增结果回放 + +

EmbodiChain · 扩增结果回放

完整模型虚影 · 已确认的真实扩增结果

正在连接原生渲染器
+
拖动画面旋转 · 滚轮缩放
EmbodiChain 原生场景渲染画面
正在加载完整机器人模型…
——
+
+
EmbodiChain SimulationManager / RobotMarkers / VisualizationMarkers → DexSim Hybrid 原生渲染。仅回放,物理推进 0 步。机器人与物体使用逐帧记录;轨迹线每 4 帧取点并连接。视角、灯光与透明材质仅用于验收展示。
+ \ No newline at end of file diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py new file mode 100644 index 0000000000..0dfeb76d8c --- /dev/null +++ b/embodichain/lab/expansion/_preview_data.py @@ -0,0 +1,474 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Read-only inputs and controls for the native expansion-result browser.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Any +import json +import math +import numpy as np +from scipy.spatial.transform import Rotation + +from .comparison import MeasuredTrajectory +from .persistence import ArtifactEpisodeSink, load_expansion_episode + +__all__: list[str] = [] + + +def pose_matrix(pose: np.ndarray) -> np.ndarray: + result = np.eye(4) + result[:3, :3] = Rotation.from_quat(pose[3:]).as_matrix() + result[:3, 3] = pose[:3] + return result + + +@dataclass +class PreviewClip: + measured: MeasuredTrajectory + space: str + affordance: str + variant: str + targets: np.ndarray + phase_names: tuple[str, ...] + anchors: np.ndarray + candidate_ids: tuple[str, ...] + label: str = "" + links: np.ndarray | None = None + tips: np.ndarray | None = None + + +def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: + records = metadata.get("expansion", ()) + env_ids = {r["env_id"] for r in records if "env_id" in r} + if len(env_ids) > 1: + raise ValueError("Episode expansion annotations refer to multiple rows") + env_id = next(iter(env_ids), None) + branches, candidates, targets, phases = [], [], [], [] + for segment in metadata.get("program_segments", ()): + for call in segment.get("metadata", {}).get("runtime", {}).get("calls", ()): + for event in call.get("events", ()): + if event.get("kind") == "trajectory_segment_entered": + phases.append( + ( + str(call["call"]["call_kind"]) + + "/" + + str(event["segment_name"]), + float(event["timestamp"]), + ) + ) + # Only the successful final planning attempt describes the executed target. + attempts = call.get("plan_attempts", ()) + if not attempts: + continue + sample = ( + attempts[-1] + .get("planner_diagnostics", {}) + .get("metadata", {}) + .get("affordance_sample", {}) + .get("grasp") + ) + if not sample: + continue + rows = list(sample["env_ids"]) + row = ( + rows.index(env_id) + if env_id in rows + else 0 if env_id is None and len(rows) == 1 else None + ) + if row is None: + raise ValueError( + "Cannot bind grasp annotation to the recorded environment row" + ) + if not sample["success"][row]: + continue + sampling = sample.get("sampling") or {} + overrides = sampling.get("branch_overrides") + branch = overrides[row] if overrides else sampling.get("branch_override") + branches.append("unrecorded" if branch is None else str(branch)) + candidates.append(str(sample["candidate_ids"][row])) + uid = ( + call.get("call", {}) + .get("arguments", {}) + .get("object", {}) + .get("entity_id") + ) + if uid not in measured.object_poses: + continue + reference = np.asarray(sample["reference_poses"][row], dtype=float) + selected = np.asarray(sample["selected_poses"][row], dtype=float) + if ( + reference.shape != (4, 4) + or selected.shape != (4, 4) + or not np.isfinite([reference, selected]).all() + ): + raise ValueError("Invalid recorded grasp transform") + targets.append( + pose_matrix(measured.object_poses[uid][0]) + @ np.linalg.inv(reference) + @ selected + ) + phases = [v for i, v in enumerate(phases) if i == 0 or v != phases[i - 1]] + anchors = np.array([p[1] for p in phases] + [measured.timestamps[-1]]) + if ( + not phases + or anchors[0] < 0 + or not np.isfinite(anchors).all() + or not np.all(np.diff(anchors) > 0) + ): + phases = [] + anchors = np.empty(0) + variants = [ + str(r["trajectory_selected"]) + for r in records + if r.get("trajectory_requested") is not None + ] + return dict( + affordance="/".join(branches) or "unrecorded", + variant="/".join(variants) or "unrecorded", + targets=np.asarray(targets, dtype=float).reshape(-1, 4, 4), + phase_names=tuple(p[0] for p in phases), + anchors=anchors, + candidate_ids=tuple(candidates), + ) + + +def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...]]]: + cfg = job.get("resolved_deployment") + if not isinstance(cfg, dict) or not isinstance(cfg.get("robot"), dict): + raise ValueError( + "Preview requires job.json with a resolved single-robot deployment" + ) + unsupported = ( + "articulation", + "rigid_object_group", + "background", + "cable_object", + "fluid_object", + "soft_object", + "cloth_object", + "deformable_object", + ) + if any(cfg.get(k) for k in unsupported) or job.get("config", {}).get("scene_atlas"): + raise ValueError( + "Preview currently supports a fixed layout, one URDF robot and Cube rigid objects only" + ) + robot = cfg["robot"] + if robot.get("visuals") or robot.get("link_visuals"): + raise ValueError("Preview requires the URDF-owned robot visual geometry") + if not np.allclose(robot.get("body_scale", [1, 1, 1]), [1, 1, 1]): + raise ValueError("Scaled robot assets are not supported by this preview") + boxes = {} + for obj in cfg.get("rigid_object", []): + shape = obj.get("shape") or {} + if ( + shape.get("shape_type") != "Cube" + or obj.get("source") + or obj.get("visuals") + or obj.get("visual_shape") + ): + raise ValueError( + "Preview requires Cube rigid geometry; no asset substitution is performed" + ) + size = np.asarray(shape["size"], float) * np.asarray( + obj.get("body_scale", [1, 1, 1]), float + ) + if size.shape != (3,) or not np.isfinite(size).all() or np.any(size <= 0): + raise ValueError("Invalid recorded Cube dimensions") + boxes[obj["uid"]] = tuple(size) + return robot, boxes + + +@dataclass +class PreviewData: + clips: list[PreviewClip] + reference: PreviewClip | None + asset: Path + eef_link: str + boxes: dict[str, tuple[float, ...]] + ground_visible: bool = True + + @property + def all_clips(self) -> list[PreviewClip]: + return self.clips + ([self.reference] if self.reference is not None else []) + + @property + def phase_alignment(self) -> bool: + signature = self.clips[0].phase_names + return bool(signature) and all( + c.phase_names == signature for c in self.all_clips + ) + + +def load_preview( + outputs: list[Path], + reference: Path | None = None, + *, + robot_asset: Path | None = None, + eef_link: str | None = None, + max_episodes: int = 32, +) -> PreviewData: + if not outputs or not 1 <= max_episodes <= 64: + raise ValueError("Provide result directories and max_episodes in [1,64]") + paths = [Path(p).expanduser().resolve() for p in outputs] + if len(set(paths)) != len(paths): + raise ValueError("Duplicate output directory") + if reference is not None: + paths.append(Path(reference).expanduser().resolve()) + clips = [] + reference_clip = None + asset = None + boxes = None + robot_spec = None + end = None + ground = True + seen = set() + frames = 0 + for group, path in enumerate(paths): + job_path = path / "job.json" + if not job_path.is_file(): + raise ValueError(f"Not an expansion job output: {path} (missing job.json)") + job = json.loads(job_path.read_text()) + robot, shapes = _scene(job) + spec = {k: robot.get(k) for k in ("uid", "control_parts", "solver_cfg")} + if robot_spec is not None and (spec != robot_spec or shapes != boxes): + raise ValueError( + "Result directories must share robot/control topology and Cube geometry" + ) + robot_spec = spec + boxes = shapes + path_value = robot.get("fpath") or (robot.get("urdf_cfg") or {}).get("fpath") + resolved_asset = Path(robot_asset or path_value or "").expanduser().resolve() + if not resolved_asset.is_file() or resolved_asset.suffix.lower() != ".urdf": + raise ValueError( + "Recorded URDF is unavailable; supply --robot-asset with matching visuals" + ) + # URDF assembly comments may differ; compare the actual XML model. + import xml.etree.ElementTree as ET + + if asset is not None and ET.tostring(ET.parse(asset).getroot()) != ET.tostring( + ET.parse(resolved_asset).getroot() + ): + raise ValueError("Output directories reference different robot models") + asset = resolved_asset + ends = { + s.get("end_link_name") + for s in robot.get("solver_cfg", {}).values() + if s.get("end_link_name") + } + inferred = eef_link or (next(iter(ends)) if len(ends) == 1 else None) + if not inferred: + raise ValueError( + "Specify --eef-link when the recorded solver endpoint is ambiguous" + ) + end = inferred + if group == 0: + ground = job["resolved_deployment"].get("ground_plane_visible") is not False + elif ground != ( + job["resolved_deployment"].get("ground_plane_visible") is not False + ): + raise ValueError("Outputs disagree about ground visibility") + receipts = [r for r in ArtifactEpisodeSink(path).inspect() if r.confirmed] + is_reference = reference is not None and group == len(outputs) + if not receipts or (is_reference and len(receipts) != 1): + raise ValueError( + "Each output needs confirmed episodes; reference must contain exactly one" + ) + if len(clips) + len(receipts) > (max_episodes + int(is_reference)): + raise ValueError( + "Preview episode budget exceeded; select smaller output directories" + ) + for receipt in receipts: + episode = load_expansion_episode(receipt.storage_id) + if not episode.validation.accepted: + raise ValueError("Unqualified episode cannot be previewed") + if episode.episode_id in seen: + raise ValueError("Duplicate episode across inputs/reference") + seen.add(episode.episode_id) + measured = MeasuredTrajectory.load_episode( + receipt.storage_id, robot_uid=robot["uid"] + ) + if len(measured.timestamps) != len(episode.actions) + 1 or set( + measured.object_poses + ) != set(boxes): + raise ValueError( + "Incomplete T+1 scene state or unsupported scene entities" + ) + if ( + any( + x["kind"] not in ("robot", "rigid_object") + for x in episode.metadata["initial_state"] + ) + or sum(x["kind"] == "robot" for x in episode.metadata["initial_state"]) + != 1 + ): + raise ValueError( + "Preview supports one robot and recorded rigid objects only" + ) + frames += len(measured.timestamps) + if frames > 100_000: + raise ValueError("Preview exceeds the 100000 measured-state budget") + clip = PreviewClip( + measured=measured, + space=f"S{group+1} · {path.name}", + **annotations(episode.metadata, measured), + ) + if is_reference: + reference_clip = clip + clip.label = "Reference" + else: + clips.append(clip) + clip.label = f"C-{len(clips):03d}" + return PreviewData(clips, reference_clip, asset, end, boxes, ground) + + +class PreviewState: + def __init__(self, data: PreviewData) -> None: + self.data = data + self.values = dict( + space="all", + aff="all", + variant="all", + selected=0, + progress=0.0, + playing=False, + reference=data.reference is not None, + ghosts=True, + paths=True, + targets=True, + positions=True, + align="phase" if data.phase_alignment else "time", + yaw=-2.15, + elevation=0.55, + distance=1.65, + ) + self.options = { + "space": sorted({c.space for c in data.clips}), + "aff": sorted({c.affordance for c in data.clips}), + "variant": sorted({c.variant for c in data.clips}), + "align": ["time"] + (["phase"] if data.phase_alignment else []), + } + + def validate(self, update: Any) -> dict[str, Any]: + if ( + not isinstance(update, dict) + or not update + or set(update) - self.values.keys() + ): + raise ValueError("Invalid preview controls") + bounds = { + "selected": (0, len(self.data.clips) - 1), + "progress": (0, 1), + "yaw": (-20, 20), + "elevation": (0.1, 1.5), + "distance": (0.2, 20), + } + for key, value in update.items(): + if key in self.options: + if value not in self.options[key] + ([] if key == "align" else ["all"]): + raise ValueError(key) + elif key in bounds: + if ( + type(value) not in (float, int) + or not math.isfinite(value) + or not bounds[key][0] <= value <= bounds[key][1] + or (key == "selected" and type(value) is not int) + ): + raise ValueError(key) + elif type(value) is not bool: + raise ValueError(key) + return dict(update) + + def apply(self, update: dict[str, Any]) -> None: + self.values.update(self.validate(update)) + visible = self.visible() + if visible and self.values["selected"] not in visible: + self.values["selected"] = visible[0] + if not visible: + self.values["playing"] = False + + def visible(self) -> list[int]: + v = self.values + return [ + i + for i, c in enumerate(self.data.clips) + if all( + v[k] == "all" or v[k] == actual + for k, actual in [ + ("space", c.space), + ("aff", c.affordance), + ("variant", c.variant), + ] + ) + ] + + def frame_at(self, clip: PreviewClip) -> int: + p = self.values["progress"] + if self.values["align"] == "phase": + n = len(clip.anchors) - 1 + segment = min(n - 1, int(p * n)) + t = np.interp(p * n - segment, [0, 1], clip.anchors[segment : segment + 2]) + else: + t = p * self.duration + return clip.measured.frame_at(t) + + @property + def duration(self) -> float: + return max(float(c.measured.timestamps[-1]) for c in self.data.all_clips) + + def snapshot(self) -> dict[str, Any]: + visible = self.visible() + c = self.data.clips[self.values["selected"]] + f = self.frame_at(c) + return { + **self.values, + "visible": visible, + "count": len(visible), + "total": len(self.data.clips), + "options": self.options, + "has_reference": self.data.reference is not None, + "label": c.label if visible else "No matches", + "source_frame": f if visible else None, + "source_frames": len(c.measured.timestamps) if visible else 0, + "time": float(c.measured.timestamps[f]) if visible else None, + "episode": c.measured.name if visible else "", + "candidate": ", ".join(c.candidate_ids) or "unrecorded", + "phase": ( + next( + ( + name + for name, t in reversed(list(zip(c.phase_names, c.anchors))) + if t <= c.measured.timestamps[f] + ), + "unrecorded", + ) + if visible + else "" + ), + "clips": [ + dict( + index=i, + label=c.label, + space=c.space, + aff=c.affordance, + variant=c.variant, + ) + for i, c in enumerate(self.data.clips) + ], + } diff --git a/embodichain/lab/expansion/_preview_render.py b/embodichain/lab/expansion/_preview_render.py new file mode 100644 index 0000000000..eb75338930 --- /dev/null +++ b/embodichain/lab/expansion/_preview_render.py @@ -0,0 +1,385 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Bounded native mesh replay without constructing a task or advancing physics.""" + +from __future__ import annotations + +from contextlib import contextmanager +from collections.abc import Iterator +from typing import Any +import io +import math +import numpy as np +from scipy.spatial.transform import Rotation +from PIL import Image +from ._preview_data import PreviewData, PreviewState, pose_matrix + +__all__: list[str] = [] + + +def prepare_geometry(data: PreviewData) -> tuple[list[str], np.ndarray]: + import torch + import pytorch_kinematics as pk + + chain = pk.build_chain_from_urdf(data.asset.read_bytes()) + names = chain.get_link_names() + joints = chain.get_joint_parameter_names() + if data.eef_link not in names: + raise ValueError(f"Unknown end-effector link: {data.eef_link}") + total = ( + sum(len(c.measured.timestamps) for c in data.all_clips) * len(names) * 16 * 4 + ) + if total > 256 * 1024 * 1024: + raise ValueError( + "Preview FK exceeds the 256 MiB budget; select smaller result directories" + ) + for c in data.all_clips: + m = c.measured + if set(joints) != set(m.joint_names): + raise ValueError( + "Recorded joints do not match the supplied URDF (including mimic joints)" + ) + order = [m.joint_names.index(n) for n in joints] + c.links = np.empty((len(m.timestamps), len(names), 4, 4), np.float32) + for start in range(0, len(m.timestamps), 256): + stop = min(len(m.timestamps), start + 256) + q = torch.tensor(m.qpos[start:stop][:, order], dtype=torch.float32) + with torch.no_grad(): + fk = chain.forward_kinematics(q) + roots = np.stack([pose_matrix(p) for p in m.root_poses[start:stop]]) + c.links[start:stop] = roots[:, None] @ np.stack( + [fk[n].get_matrix().numpy() for n in names], axis=1 + ) + c.tips = c.links[:, names.index(data.eef_link), :3, 3] + if not np.isfinite(c.links).all(): + raise ValueError("FK produced nonfinite poses") + points = np.concatenate([c.links[0, :, :3, 3] for c in data.all_clips]) + center = (points.min(axis=0) + points.max(axis=0)) / 2 + return names, center + + +class NativeRenderer: + def __init__( + self, + data: PreviewData, + sim: Any, + publisher: Any, + names: list[str], + center: np.ndarray, + ) -> None: + from dexsim import spawn + from embodichain.lab.visualization.markers import ( + RobotMarkers, + RobotMarkersCfg, + RobotMarkersAppearanceCfg, + VisualizationMarkers, + VisualizationMarkersCfg, + MarkerPrototypeCfg, + ) + + self.data, self.sim, self.publisher, self.center = data, sim, publisher, center + scene = sim.spawn_result + self.step = sim.physics_step_index + self.previous = None + palette = [ + (0.18, 0.58, 1), + (0.15, 0.9, 0.5), + (0.9, 0.55, 0.2), + (0.7, 0.4, 0.95), + ] + variants = sorted({c.variant for c in data.clips}) + self.colors = {v: palette[i % len(palette)] for i, v in enumerate(variants)} + for name, pos, intensity in [ + ("preview_key", [-1, -2, 3], 35), + ("preview_fill", [1, 1, 2], 18), + ]: + pose = np.eye(4, dtype=np.float32) + pose[:3, 3] = np.asarray(pos) + center + scene.add_light( + spawn.LightDesc( + name=name, light_type="POINT", pose=pose, intensity=intensity + ) + ) + self.robots = [] + self.objects = [] + + def markers(name: str, shapes: dict) -> Any: + return VisualizationMarkers( + VisualizationMarkersCfg(prim_path=name, markers=shapes), publisher + ) + + for i, c in enumerate(data.all_clips): + color = ( + self.colors.get(c.variant, (0.65, 0.7, 0.75)) + if i < len(data.clips) + else (0.65, 0.7, 0.75) + ) + robot = RobotMarkers( + RobotMarkersCfg( + name=f"preview_robot_{i}", + asset_path=str(data.asset), + appearance=RobotMarkersAppearanceCfg(color=color, opacity=0.18), + ), + publisher, + ) + self.robots.append((robot, [names.index(n) for n in robot.link_names])) + objects = ( + markers( + f"preview_objects_{i}", + { + uid: MarkerPrototypeCfg( + shape="box", scale=size, color=(*color, 0.2) + ) + for uid, size in data.boxes.items() + }, + ) + if data.boxes + else None + ) + self.objects.append(objects) + robot.visualize_link_poses( + c.links[0, [names.index(n) for n in robot.link_names]][None] + ) + robot.set_visibility(False) + if objects: + p = np.array([c.measured.object_poses[uid][0] for uid in data.boxes]) + objects.visualize( + p[:, :3], p[:, 3:], marker_indices=np.arange(len(data.boxes)) + ) + objects.set_visibility(False) + self.selected = RobotMarkers( + RobotMarkersCfg( + name="selected_model", + asset_path=str(data.asset), + appearance=RobotMarkersAppearanceCfg(mode="asset", opacity=1), + ), + publisher, + ) + self.selected_order = [names.index(n) for n in self.selected.link_names] + self.selected.visualize_link_poses( + data.clips[0].links[0, self.selected_order][None] + ) + self.selected_objects = ( + markers( + "selected_objects", + { + uid: MarkerPrototypeCfg( + shape="box", + scale=size, + color=(0.9, 0.58, 0.2, 1), + scene_lighting=True, + unlit=False, + ) + for uid, size in data.boxes.items() + }, + ) + if data.boxes + else None + ) + self.paths = markers( + "measured_paths", + { + str(i): MarkerPrototypeCfg( + shape="cylinder", color=(*self.colors[v], 0.8) + ) + for i, v in enumerate(variants) + }, + ) + self.variant_ids = {v: i for i, v in enumerate(variants)} + self.targets = markers( + "recorded_grasp_targets", + {"target": MarkerPrototypeCfg(shape="frame", scale=(0.065, 0.065, 0.065))}, + ) + self.positions = markers( + "initial_positions", + { + "point": MarkerPrototypeCfg( + shape="sphere", scale=(0.014, 0.014, 0.014), color=(1, 0.7, 0.1, 1) + ) + }, + ) + self.camera = scene.add_camera( + spawn.CameraDesc(name="expansion_preview_camera", resolution=(1100, 760)) + ) + self.camera.open_camera() + self.camera.set_visual_overlay_enabled(True) + publisher.publish(preload=True) + + def draw(self, state: PreviewState) -> bytes: + v = state.values + visible = state.visible() + if tuple(visible) != self.previous: + positions = [] + rotations = [] + scales = [] + types = [] + for i in visible: + c = self.data.clips[i] + points = c.tips[ + np.unique(np.r_[np.arange(0, len(c.tips), 4), len(c.tips) - 1]) + ] + for a, b in zip(points[:-1], points[1:]): + delta = b - a + length = np.linalg.norm(delta) + if length < 1e-6: + continue + z = delta / length + axis = np.cross([0, 0, 1], z) + norm = np.linalg.norm(axis) + rotation = ( + Rotation.from_rotvec( + axis / norm * np.arccos(np.clip(z[2], -1, 1)) + ) + if norm > 1e-8 + else Rotation.from_rotvec([np.pi if z[2] < 0 else 0, 0, 0]) + ) + positions.append((a + b) / 2) + rotations.append(rotation.as_quat()) + scales.append([0.002, 0.002, length]) + types.append(self.variant_ids[c.variant]) + self.paths.visualize( + np.array(positions).reshape(-1, 3), + np.array(rotations).reshape(-1, 4), + np.array(scales).reshape(-1, 3), + np.asarray(types, dtype=int), + ) + targets = ( + np.concatenate([self.data.clips[i].targets for i in visible]) + if visible + else np.empty((0, 4, 4)) + ) + self.targets.visualize( + targets[:, :3, 3], + ( + Rotation.from_matrix(targets[:, :3, :3]).as_quat() + if len(targets) + else np.empty((0, 4)) + ), + ) + initial = [ + p[0, :3] + for i in visible + for p in self.data.clips[i].measured.object_poses.values() + ] + self.positions.visualize(np.asarray(initial).reshape(-1, 3)) + self.previous = tuple(visible) + self.selected.set_visibility(bool(visible)) + if self.selected_objects: + self.selected_objects.set_visibility(bool(visible)) + if visible: + c = self.data.clips[v["selected"]] + f = state.frame_at(c) + self.selected.visualize_link_poses(c.links[f, self.selected_order][None]) + if self.selected_objects: + p = np.array( + [c.measured.object_poses[uid][f] for uid in self.data.boxes] + ) + self.selected_objects.visualize( + p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) + ) + ghost_count = 0 + for i, (c, (robot, order), objects) in enumerate( + zip(self.data.all_clips, self.robots, self.objects) + ): + show = ( + v["reference"] + if i == len(self.data.clips) + else v["ghosts"] and i in visible and i != v["selected"] + ) + robot.set_visibility(show) + if objects: + objects.set_visibility(show) + if show: + ghost_count += 1 + f = state.frame_at(c) + robot.visualize_link_poses(c.links[f, order][None]) + if objects: + p = np.array( + [c.measured.object_poses[uid][f] for uid in self.data.boxes] + ) + objects.visualize( + p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) + ) + self.paths.set_visibility(v["paths"]) + self.targets.set_visibility(v["targets"]) + self.positions.set_visibility(v["positions"]) + self.publisher.publish() + yaw = v["yaw"] + e = v["elevation"] + d = v["distance"] + eye = self.center + d * np.array( + [math.cos(e) * math.cos(yaw), math.cos(e) * math.sin(yaw), math.sin(e)] + ) + self.camera.look_at(eye.tolist(), self.center.tolist(), [0, 0, 1]) + with self.sim.render_frame(capture_camera_images=False): + self.sim.sync_render_state() + self.camera.render() + if self.sim.physics_step_index != self.step: + raise RuntimeError("Preview unexpectedly advanced physics") + image = Image.fromarray( + np.ascontiguousarray(self.camera.get_rgb_map()[..., :3], dtype=np.uint8) + ) + buffer = io.BytesIO() + image.save(buffer, format="JPEG", quality=88) + self.stats = { + "physics_steps": self.sim.physics_step_index - self.step, + "ghost_count": ghost_count, + "path_segments": self.paths.count if v["paths"] else 0, + "grasp_targets": self.targets.count if v["targets"] else 0, + } + return buffer.getvalue() + + +@contextmanager +def native_renderer(data: PreviewData, gpu: int = 0) -> Iterator[NativeRenderer]: + import os + + os.environ.setdefault("SDL_VIDEODRIVER", "offscreen") + import torch + from embodichain.lab.sim import SimulationManager, SimulationManagerCfg + from embodichain.lab.sim.cfg import RenderCfg, DenoisingCfg + from embodichain.lab.visualization.markers import MarkerFramePublisher + + torch.set_num_threads(1) + names, center = prepare_geometry(data) + sim = SimulationManager( + SimulationManagerCfg( + headless=True, + device="cpu", + gpu_id=gpu, + num_envs=1, + enable_entity_gizmo=False, + startup_summary="off", + render_cfg=RenderCfg( + renderer="hybrid", + spp=4, + denoising=DenoisingCfg(window="off", offscreen="optix"), + ), + ) + ) + publisher = None + try: + sim.enable_physics(False) + sim.prepare() + sim.set_ground_plane_visibility(data.ground_visible) + publisher = MarkerFramePublisher(sim) + yield NativeRenderer(data, sim, publisher, names, center) + finally: + if publisher is not None: + publisher.close() + sim.destroy(exit_process=False) + SimulationManager.flush_cleanup_queue() diff --git a/embodichain/lab/expansion/_preview_server.py b/embodichain/lab/expansion/_preview_server.py new file mode 100644 index 0000000000..fa8392b292 --- /dev/null +++ b/embodichain/lab/expansion/_preview_server.py @@ -0,0 +1,212 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Loopback-only native preview transport. WebRTC integration remains a TODO.""" + +from __future__ import annotations + +import base64 +import json +import queue +import threading +import time +import webbrowser +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from typing import Any +from urllib.parse import urlsplit +from ._preview_data import PreviewData, PreviewState + +__all__: list[str] = [] + + +class PreviewTransport: + def __init__(self, state: PreviewState, port: int) -> None: + self.state = state + self.commands: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=64) + self.lock = threading.Lock() + self.status: dict[str, Any] = {} + self.jpeg = b"" + self.snapshot = b"{}" + html = Path(__file__).with_name("_preview.html").read_bytes() + owner = self + + class Handler(BaseHTTPRequestHandler): + def setup(self) -> None: + super().setup() + self.connection.settimeout(3) + + def log_message(self, *_: object) -> None: + pass + + def do_GET(self) -> None: + if urlsplit("//" + self.headers.get("Host", "")).hostname not in { + "127.0.0.1", + "localhost", + "::1", + }: + self.send_error(403) + return + route = self.path.split("?")[0] + with owner.lock: + if route == "/": + data, kind = html, "text/html; charset=utf-8" + elif route == "/state": + data, kind = ( + json.dumps(owner.status, allow_nan=False).encode(), + "application/json", + ) + elif route == "/snapshot": + data, kind = owner.snapshot, "application/json" + elif route == "/frame.jpg": + data, kind = owner.jpeg, "image/jpeg" + else: + self.send_error(404) + return + self.send_response(200) + self.send_header("Content-Type", kind) + self.send_header("Cache-Control", "no-store") + self.send_header("X-Content-Type-Options", "nosniff") + self.send_header("Content-Length", str(len(data))) + self.end_headers() + try: + self.wfile.write(data) + except (BrokenPipeError, ConnectionResetError): + pass + + def do_POST(self) -> None: + if self.path != "/control": + self.send_error(404) + return + origin = self.headers.get("Origin") + host = self.headers.get("Host", "") + # Same-origin loopback controls also work through a different forwarded port. + if ( + urlsplit("//" + host).hostname + not in {"127.0.0.1", "localhost", "::1"} + or self.headers.get("Content-Type") != "application/json" + or (origin and origin != "http://" + host) + ): + self.send_error(403) + return + try: + size = int(self.headers.get("Content-Length", "0")) + if not 0 < size <= 4096: + raise ValueError("control size") + update = owner.state.validate(json.loads(self.rfile.read(size))) + owner.commands.put_nowait(update) + except (ValueError, TypeError, queue.Full, TimeoutError): + self.send_error(400) + return + self.send_response(204) + self.end_headers() + + self.server = ThreadingHTTPServer(("127.0.0.1", port), Handler) + self.server.daemon_threads = True + self.url = f"http://127.0.0.1:{self.server.server_port}/" + + def publish(self, status: dict[str, Any], jpeg: bytes) -> None: + snapshot = json.dumps( + { + **status, + "image": "data:image/jpeg;base64," + base64.b64encode(jpeg).decode(), + }, + allow_nan=False, + ).encode() + with self.lock: + self.status = status + self.jpeg = jpeg + self.snapshot = snapshot + + +def serve_preview( + data: PreviewData, + *, + port: int = 8769, + gpu: int = 0, + open_browser: bool = False, + duration: float = 0, +) -> None: + from ._preview_render import native_renderer + + state = PreviewState(data) + transport = PreviewTransport(state, port) + thread = None + try: + with native_renderer(data, gpu) as renderer: + frame = 0 + + def publish() -> None: + nonlocal frame + jpeg = renderer.draw(state) + transport.publish( + { + **state.snapshot(), + **renderer.stats, + "frame": frame, + "renderer": "EmbodiChain / DexSim Hybrid + OptiX", + "transport": "HTTP JPEG", + }, + jpeg, + ) + frame += 1 + + publish() + thread = threading.Thread( + target=transport.server.serve_forever, daemon=True + ) + thread.start() + print( + json.dumps( + { + "state": "ready", + "url": transport.url, + "episodes": len(data.clips), + "physics_steps": 0, + "transport": "HTTP JPEG", + } + ), + flush=True, + ) + if open_browser: + webbrowser.open(transport.url) + start = last = time.monotonic() + while not duration or time.monotonic() - start < duration: + now = time.monotonic() + elapsed = now - last + last = now + dirty = False + while True: + try: + state.apply(transport.commands.get_nowait()) + dirty = True + except queue.Empty: + break + if state.values["playing"]: + state.values["progress"] = min( + 1.0, state.values["progress"] + elapsed / state.duration + ) + if state.values["progress"] >= 1: + state.values["playing"] = False + dirty = True + if dirty: + publish() + time.sleep(max(0.01, 0.1 - (time.monotonic() - now))) + finally: + if thread is not None: + transport.server.shutdown() + thread.join(timeout=5) + transport.server.server_close() diff --git a/examples/expansion/engine/README.md b/examples/expansion/engine/README.md index 2b902ff70a..61cc1c7383 100644 --- a/examples/expansion/engine/README.md +++ b/examples/expansion/engine/README.md @@ -26,11 +26,17 @@ capabilities remain explicit. `--reuse` rebuilds the offline page without a Worl ## Native ghost preview -See [the native ghost-preview notes](ghost-preview.md) for the existing SDK -window comparison, the separately validated eight-result browser prototype, -linked spatial/affordance/trajectory filters, and the native WebRTC follow-up. -The prototype uses native offscreen rendering with HTTP JPEG transport; it is -not a WebRTC entry point or a released general-purpose viewer. +Replay confirmed results directly, without recollection or physics stepping: + +```bash +embodichain expansion preview --output /path/to/job-output --gpu 0 --open +``` + +Repeat `--output` for spatial groups and optionally add `--reference` with one +confirmed reference episode. The [native preview guide](ghost-preview.md) covers +linked spatial/affordance/trajectory filters, asset recovery, supported scene +geometry, replay semantics and the WebRTC TODO. Rendering is native; browser +transport currently uses HTTP JPEG, not WebRTC. ## Run a configured job diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index 3d538376d0..dd6a49ddaa 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -1,26 +1,67 @@ # 扩增分布的原生虚影预览 本文记录空间、affordance 与轨迹分布的交互预览方案,以及 2026-11-15 完成的 -小规模原型验收。它补充 [Expansion Engine](README.md) 的结果查看流程。 +小规模原型验收,并说明基于已有结果启动的仓库入口。它补充 [Expansion Engine](README.md) 的结果查看流程。 ## 当前能力与边界 | 路径 | 渲染与交互 | 状态 | | --- | --- | --- | | SDK 原生窗口对照 | `preview_expansion_comparison` 加载已验收轨迹,显示参考与选中虚影;N 切换、Space 暂停、Q 关闭 | 仓库已有能力,见 [comparison.py](../../../embodichain/lab/expansion/comparison.py) | -| 独立浏览器原型 | EmbodiChain 原生离屏渲染完整模型;HTTP JPEG 传图,HTTP 控制筛选与回放 | 已完成本地验收,尚未整理为仓库通用入口 | +| 浏览器结果预览 | EmbodiChain 原生离屏渲染完整模型;HTTP JPEG 传图,HTTP 控制筛选与回放 | `embodichain expansion preview`,直接读取已确认结果 | | 原生 WebRTC 推流 | 复用 EmbodiChain 的原生推流生命周期与控制接口 | TODO,尚未接入本预览 | “原生渲染”指场景由 `SimulationManager`、`RobotMarkers`、 `VisualizationMarkers` 和 DexSim Hybrid 渲染器生成,**不表示采用 WebRTC**。 -浏览器原型没有自行绘制机器人骨架,也不使用 Viser 重建场景;它显示原生离屏 +浏览器预览没有自行绘制机器人骨架,也不使用 Viser 重建场景;它显示原生离屏 相机输出的 JPEG。本次使用 OptiX 去噪。展示灯光、视角和透明材质与采集时可以不同, 不能把预览图片当作采集传感器的原始观测。 -独立原型使用采集时冻结的源码 `ab04d972b5b75042434498db9a889b4edd03b6fe`。 -本文新增的是说明与验收记录,不把本地脚本、机器路径或录制产物包装成已发布 SDK API。 +最初实验使用采集时冻结的源码 `ab04d972b5b75042434498db9a889b4edd03b6fe`。 +仓库入口直接读取原始结果,不需要该源码快照、本地预处理 JSON 或实验脚本。 [showcase](showcase/README.md) 的离线三维/RGB-D 页面也是另一条查看路径。 +## 从已有结果启动 + +在安装了兼容 EmbodiChain、DexSim 原生渲染依赖的环境中运行: + +```bash +# 单个已完成或部分完成的作业:只加载已有确认回执,不继续采集。 +embodichain expansion preview --output /path/to/job-output --gpu 0 --open + +# 复用本次配方的两个空间组,叠加一条独立参考。 +embodichain expansion preview \ + --output /path/to/results/space-a \ + --output /path/to/results/space-b \ + --reference /path/to/results/reference \ + --gpu 0 --port 8769 --open +``` + +每个输入是含 `job.json` 和 `episodes/` 的原始作业输出目录;不是导出的 LeRobot +数据集或单个 NPZ。可重复传入 `--output`,空间筛选以输入结果目录分组。 +当前只支持固定布局,不把一个 scene-atlas 作业内部的不同布局合并成同一空间组。 +`--reference` 可省略;指定时必须恰好含一个已确认参考 episode,且不能与候选重复。 + +模型从 `job.json.resolved_deployment.robot` 的 URDF 路径恢复,场景方块尺寸从 +同一快照恢复,不加载原任务配置,也不重新实例化任务/规划器。原模型及引用的视觉 +文件必须仍可读;若资产移动,使用 `--robot-asset /new/path/robot.urdf` 显式提供 +匹配模型。入口检查完整关节名称集合和跨输入模型一致性,但旧结果没有完整视觉 +资产包,不能仅凭关节名证明替换模型几何完全一致;调用者负责提供原模型。 + +默认从唯一的 solver `end_link_name` 推导末端路径,存在多个端点时必须提供 +`--eef-link LINK_NAME`。这里的路径是该 URDF link 的 FK 原点,不隐式附加工具 TCP。 +缺失 affordance/trajectory 注释显示“未记录”,不猜测为名义分支;只有所有轨迹 +具有一致、有效的动作阶段时才提供阶段对齐。 + +服务默认仅监听 `127.0.0.1:8769`,打印就绪地址后才能访问;`--port 0` 自动选空闲端口。 +`--open` 在首帧完成后尝试打开服务所在机器的浏览器。远程服务器需要端口转发后 +在客户端打开对应地址。Ctrl+C 释放服务和渲染资源;`--duration 60` 在就绪后 +运行 60 秒自动关闭。启动端口冲突、资产缺失和不支持的场景会明确失败。 + +入口不会写入输入目录、更新成功计数或重新采集。它默认最多加载 32 条候选, +`--max-episodes` 可设为 1–64,超出则报错而非静默抽样。还限制总状态帧不超过 +100000、预计算 link FK 不超过 256 MiB;这些是显式的预览规模限制,不是性能保证。 + ## 配方与真实结果 使用已有 `task.default.yaml` 的单轮 UR5 + DH PGI 抓取放置任务和 default 物理后端。 @@ -52,9 +93,10 @@ 选中样本显示原始模型外观,其余可见候选显示半透明虚影;参考单独开关。 4. 用真实物体位姿驱动物体模型,并通过 `VisualizationMarkers` 显示初始位置、 抓取目标坐标轴和末端路径。 -5. 在仿真/渲染所有者线程应用筛选与回放状态,调用原生相机渲染。 +5. 启动时分块预计算 FK,使用 `MarkerFramePublisher` 发布一致的跨组帧; + 在仿真/渲染所有者线程应用筛选与回放状态,调用原生相机渲染。 HTTP 线程只排队控制消息和读取已发布画面,不直接访问仿真对象。 -6. 页面读取 JPEG 并展示对应记录信息。关闭服务时释放相机、场景和监听端口; +6. 页面轮询同一次发布中的 JPEG 与记录信息,避免分开读取图像和状态造成帧号错配。关闭服务时释放相机、场景和监听端口; 已提交轨迹与校验结果保持不变。 原型回放不调用物理推进,验收记录的物理步数为 0。回放不是新物理成功样本, @@ -64,7 +106,7 @@ 空间、affordance、轨迹三个筛选器取交集,同时作用于候选列表、虚影、物体、 初始位置、抓取目标和轨迹线。选中样本被筛掉时,选择交集内的一个有效样本。 -这个固定配方的组合完整,因此没有空交集;通用化时必须显式处理空结果。 +没有匹配候选时显示空结果、停止播放并隐藏候选图层;参考对照仍可独立显示。 参考轨迹是独立对照,不计入 8 条候选数量,也不受候选筛选限制。 - **空间**:显示实际初始位置,不给样本添加人为排列偏移。 @@ -85,6 +127,11 @@ 时间拖动与播放、虚影开关、相机视角切换、窄屏布局和非法控制值拒绝。 浏览器无脚本错误,回放全过程未推进物理。验收后服务已关闭,结果保留。 +仓库 CLI 已使用相同的 8 条候选和 1 条参考复测:筛选后的实际虚影/目标数量同步变化, +播放与拖动正常;无需 `--robot-asset` 即可从 `job.json` 恢复资产,`--duration` +结束后端口关闭。结果读取、批内目标绑定、空交集、时间对齐、HTTP 控制/快照、 +CLI 不触发采集和安装包页面资源由生产模块的聚焦测试覆盖。 + 原型脚本及结果保存在本次实验的 `real-demo` 目录: | 文件 | 用途 | @@ -95,15 +142,19 @@ | `native-assets/` | 对应采集模型的 URDF 与视觉资产副本 | | `native-acceptance.json`、`native-preview-acceptance.png` | 浏览器验收结果和原生渲染截图 | -这些文件不是仓库已安装入口。已有实验目录中可用兼容的 EmbodiChain/DexSim -Python 环境运行 `python native_preview.py --gpu GPU_ID --port PORT`,然后访问该机器的 -loopback 地址;远程访问需要端口转发。Ctrl+C 关闭服务。原型默认端口 8769, -默认渲染 GPU 4,设备编号需按部署环境调整;不要从仓库根目录直接执行此命令。 -原型仍依赖实验目录中的冻结源码、配置与产物路径,不是便携式数据查看器。 +上述文件是原型的历史实验产物;仓库入口不再依赖它们。结果读取与控制语义由 +`embodichain/lab/expansion/_preview_data.py` 负责,原生渲染与资源释放由 +`_preview_render.py` 负责,HTTP 服务与页面由 `_preview_server.py`、`_preview.html` +负责,CLI 由 `embodichain/cli/expansion.py` 分发。 + +当前明确支持单 URDF 机器人、单位机器人缩放和 Cube 刚体场景。其他 articulated +objects、软体、流体、线缆、mesh/source 物体、背景资产和 scene-atlas 输入会被拒绝; +不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,方块颜色和灯光是展示 +外观,不声称精确恢复采集时材质。新任务支持应扩展场景恢复契约并验证实测坐标。 HTTP JPEG 轮询不提供 WebRTC 的编码、拥塞控制、连接恢复或低延迟保证。 页面是单个服务的共享回放会话,多人操作会改变同一状态;尚未提供独立会话、 -认证、任意配方加载、大规模分页或通用资产恢复。当前不应对外公开监听。 +认证或通用资产包恢复。当前不应对外公开监听。 ## TODO:接入 EmbodiChain 原生 WebRTC 推流 diff --git a/setup.py b/setup.py index d2b5b24d76..a301c9939e 100644 --- a/setup.py +++ b/setup.py @@ -153,6 +153,7 @@ def get_package_data() -> dict[str, list[str]]: ] return { "embodichain": ["VERSION"], + "embodichain.lab.expansion": ["_preview.html"], "embodichain.data": ["default_materials.json"], "embodichain.compute.kinematics._warp": [ "ssik_LICENSE.txt", diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py new file mode 100644 index 0000000000..4de3f2c108 --- /dev/null +++ b/tests/lab/expansion/test_preview.py @@ -0,0 +1,316 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Result-only preview: provenance, row selection, controls and HTTP lifecycle.""" + +from __future__ import annotations + +import base64 +from dataclasses import replace +import hashlib +import json +from pathlib import Path +import threading +import urllib.error +import urllib.request +import numpy as np +import pytest +import torch + +from embodichain.lab.expansion.contracts import ( + CandidateIdentity, + ExpertEpisode, + ValidationResult, + ValidationCheck, +) +from embodichain.lab.expansion.persistence import ArtifactEpisodeSink +from embodichain.lab.expansion._preview_data import load_preview, PreviewState +from embodichain.lab.expansion._preview_render import prepare_geometry +from embodichain.lab.expansion._preview_server import PreviewTransport + + +@pytest.fixture +def recorded_job(tmp_path): + asset = tmp_path / "robot.urdf" + asset.write_text( + '' + '' + '' + '' + '' + ) + output = tmp_path / "result" + output.mkdir() + job = { + "resolved_deployment": { + "robot": { + "uid": "robot", + "fpath": str(asset), + "solver_cfg": {"arm": {"end_link_name": "tip"}}, + }, + "rigid_object": [ + { + "uid": "box", + "shape": {"shape_type": "Cube", "size": [0.05, 0.05, 0.05]}, + } + ], + } + } + (output / "job.json").write_text(json.dumps(job)) + poses = torch.tensor([[0.0, 0, 0, 0, 0, 0, 1]] * 3) + objects = poses.clone() + objects[:, :2] = torch.tensor([10.0, 20.0]) + transforms = np.tile(np.eye(4), (2, 1, 1)) + transforms[:, 0, 3] = [100, 200] + selected = transforms.copy() + selected[:, 0, 3] += [1, 2] + sample = { + "env_ids": [3, 7], + "success": [True, True], + "sampling": {"branch_overrides": [0, 1]}, + "candidate_ids": [23, 31], + "reference_poses": transforms.tolist(), + "selected_poses": selected.tolist(), + } + metadata = { + "initial_state": [ + {"kind": "robot", "uid": "robot", "joint_names": ["joint"]}, + {"kind": "rigid_object", "uid": "box"}, + ], + "scene_state_fields": [ + {"entity_uid": "robot", "field": "pose", "key": "robot_pose"} + ], + "expansion": [ + {"env_id": 7, "trajectory_requested": 1, "trajectory_selected": 1} + ], + "program_segments": [ + { + "metadata": { + "runtime": { + "calls": [ + { + "call": { + "call_kind": "pick", + "arguments": {"object": {"entity_id": "box"}}, + }, + "plan_attempts": [ + { + "planner_diagnostics": { + "metadata": { + "affordance_sample": {"grasp": sample} + } + } + } + ], + "events": [ + { + "kind": "trajectory_segment_entered", + "timestamp": 0.0, + "segment_name": "approach", + }, + { + "kind": "trajectory_segment_entered", + "timestamp": 0.4, + "segment_name": "lift", + }, + ], + } + ] + } + } + } + ], + } + episode = ExpertEpisode( + CandidateIdentity( + "scene", "initial", "candidate", "family", "source", "v1", "template" + ), + { + "full_joint_positions": torch.tensor([[0.0], [np.pi / 2], [np.pi]]), + "robot_pose": poses, + "rigid/box/state": objects, + }, + torch.zeros((2, 1)), + torch.tensor([0.0, 0.5, 1.0], dtype=torch.float64), + "qpos", + ValidationResult((ValidationCheck("task_success", "passed"),)), + "episode", + "commit", + metadata=metadata, + ) + ArtifactEpisodeSink(output).submit(episode, submission_id=0) + return output, job, episode + + +def test_result_loading_binds_grasp_row_and_fk_without_writing_results(recorded_job): + path, _, _ = recorded_job + before = { + p.relative_to(path): hashlib.sha256(p.read_bytes()).hexdigest() + for p in path.rglob("*") + if p.is_file() + } + data = load_preview([path]) + clip = data.clips[0] + assert ( + clip.affordance == "1" and clip.candidate_ids == ("31",) and clip.variant == "1" + ) + np.testing.assert_allclose(clip.targets[0, :3, 3], [12, 20, 0]) + names, _ = prepare_geometry(data) + np.testing.assert_allclose(clip.tips, [[1, 0, 0], [0, 1, 0], [-1, 0, 0]], atol=1e-6) + assert "tip" in names and clip.links.shape[0] == 3 + after = { + p.relative_to(path): hashlib.sha256(p.read_bytes()).hexdigest() + for p in path.rglob("*") + if p.is_file() + } + assert before == after + + +def test_result_loader_rejects_incomplete_scene_and_budget(recorded_job, tmp_path): + path, job, episode = recorded_job + with pytest.raises(ValueError, match="missing job.json"): + load_preview([tmp_path / "missing"]) + assert not (tmp_path / "missing").exists() + ArtifactEpisodeSink(path).submit( + replace(episode, episode_id="episode2", commit_id="commit2"), submission_id=1 + ) + with pytest.raises(ValueError, match="budget"): + load_preview([path], max_episodes=1) + with pytest.raises(ValueError, match="reference"): + load_preview([path], reference=path) + job["resolved_deployment"]["rigid_object"][0]["shape"]["shape_type"] = "Mesh" + (path / "job.json").write_text(json.dumps(job)) + with pytest.raises(ValueError, match="Cube"): + load_preview([path]) + + +def test_filter_empty_intersection_and_phase_alignment(recorded_job): + path, _, _ = recorded_job + data = load_preview([path]) + first = data.clips[0] + data.clips = [ + replace(first, space="A", affordance="0", variant="0"), + replace(first, space="B", affordance="1", variant="1"), + ] + state = PreviewState(data) + state.apply({"space": "B"}) + assert state.visible() == [1] and state.values["selected"] == 1 + state.apply({"aff": "0", "playing": True}) + assert state.visible() == [] and not state.values["playing"] + assert state.snapshot()["source_frame"] is None + state.apply({"space": "all", "aff": "all", "progress": 0.5}) + assert state.frame_at(first) == 0 # phase boundary .4 s -> recorded frame at 0 s + state.apply({"align": "time"}) + assert state.frame_at(first) == 1 # exactly .5 s + state.apply({"progress": 1}) + assert state.frame_at(first) == 2 + for update in ( + {"progress": float("nan")}, + {"selected": True}, + {"playing": "true"}, + {"unknown": 0}, + {"aff": "missing"}, + ): + before = dict(state.values) + with pytest.raises(ValueError): + state.apply(update) + assert state.values == before + + +def test_http_snapshot_control_and_shutdown(recorded_job): + path, _, _ = recorded_job + state = PreviewState(load_preview([path])) + transport = PreviewTransport(state, 0) + transport.publish({"frame": 7, "source_frame": 2}, b"jpeg-frame-7") + thread = threading.Thread(target=transport.server.serve_forever) + thread.start() + try: + snapshot = json.load(urllib.request.urlopen(transport.url + "snapshot")) + assert snapshot["frame"] == 7 and snapshot["source_frame"] == 2 + assert base64.b64decode(snapshot["image"].split(",")[1]) == b"jpeg-frame-7" + req = urllib.request.Request( + transport.url + "control", + data=b'{"progress":0.5}', + headers={"Content-Type": "application/json"}, + method="POST", + ) + assert urllib.request.urlopen(req).status == 204 + assert ( + state.values["progress"] == 0 + ) # only the render owner applies queued commands + state.apply(transport.commands.get_nowait()) + assert state.values["progress"] == 0.5 + req.add_header("Origin", "https://untrusted.example") + with pytest.raises(urllib.error.HTTPError) as error: + urllib.request.urlopen(req) + assert error.value.code == 403 + finally: + transport.server.shutdown() + thread.join(timeout=5) + transport.server.server_close() + assert not thread.is_alive() + + +def test_preview_cli_dispatch_does_not_collect(monkeypatch, recorded_job): + from embodichain.cli.expansion import main + import embodichain.lab.expansion._preview_server as server + from embodichain.lab.expansion import ExpansionEngine + + path, _, _ = recorded_job + called = [] + monkeypatch.setattr( + server, "serve_preview", lambda data, **kw: called.append((len(data.clips), kw)) + ) + monkeypatch.setattr( + ExpansionEngine, + "from_job", + lambda *a, **kw: pytest.fail("preview must not collect"), + ) + assert main(["preview", "--output", str(path), "--gpu", "2", "--open"]) == 0 + assert ( + called[0][0] == 1 and called[0][1]["gpu"] == 2 and called[0][1]["open_browser"] + ) + + +def test_viewer_html_is_in_package_data(tmp_path): + from setup import get_package_data + from setuptools import Distribution + from setuptools.command.build_py import build_py + import shutil + + package = "embodichain.lab.expansion" + source = tmp_path / "source" + source.mkdir() + original = ( + Path(__file__).resolve().parents[3] / "embodichain/lab/expansion/_preview.html" + ) + shutil.copyfile(original, source / "_preview.html") + (source / "__init__.py").write_text("") + distribution = Distribution( + { + "packages": [package], + "package_dir": {package: str(source)}, + "package_data": get_package_data(), + "include_package_data": False, + } + ) + distribution.script_name = "setup.py" + command = build_py(distribution) + command.build_lib = str(tmp_path / "build") + command.ensure_finalized() + command.run() + packaged = Path(command.build_lib) / "embodichain/lab/expansion/_preview.html" + assert packaged.read_bytes() == original.read_bytes() From 80d2d5175ff3aefe5301f1df219a0ff6fca17a80 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 09:48:56 +0000 Subject: [PATCH 10/49] feat(expansion): collect and preview bounded parameter distributions from jobs --- .../expansion-engine/expansion-engine.md | 13 +- .../motion-planning/trajectory-expansion.md | 10 + embodichain/cli/expansion.py | 102 +++- embodichain/lab/expansion/_gym_episode.py | 1 + embodichain/lab/expansion/_preview.html | 3 +- embodichain/lab/expansion/_preview_data.py | 49 +- embodichain/lab/expansion/_preview_job.py | 550 ++++++++++++++++++ embodichain/lab/expansion/_preview_render.py | 26 + embodichain/lab/expansion/session_cfg.py | 7 + .../lab/sim/motion/expansion/_samples.py | 43 ++ embodichain/lab/sim/motion/expansion/cfg.py | 8 + .../lab/sim/motion/expansion/combined.py | 10 + .../lab/sim/motion/expansion/operators.py | 58 +- .../lab/sim/motion/expansion/variants.py | 3 + .../task_program/integrations/expansion.py | 4 + examples/expansion/engine/README.md | 23 +- examples/expansion/engine/ghost-preview.md | 101 +++- examples/expansion/engine/job.preview.yaml | 20 + examples/expansion/engine/motion.preview.yaml | 55 ++ tests/lab/expansion/test_episode_assembly.py | 1 + tests/lab/expansion/test_preview.py | 73 ++- tests/lab/expansion/test_preview_job.py | 202 +++++++ tests/sim/motion/expansion/test_operators.py | 94 +++ 23 files changed, 1423 insertions(+), 33 deletions(-) create mode 100644 embodichain/lab/expansion/_preview_job.py create mode 100644 embodichain/lab/sim/motion/expansion/_samples.py create mode 100644 examples/expansion/engine/job.preview.yaml create mode 100644 examples/expansion/engine/motion.preview.yaml create mode 100644 tests/lab/expansion/test_preview_job.py diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 1155740b83..255bdcaa1e 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -93,7 +93,7 @@ time; physics stays disabled and render updates do not mutate saved evidence. cross-group frame through the public marker layer. Task assets and any collection process orchestration remain outside the replay core. -`embodichain expansion preview` reads confirmed job outputs through `_preview_data.py`, +`embodichain expansion preview --input` reads confirmed job outputs through `_preview_data.py`, then replays full measured states using `_preview_render.py` and a loopback-only `_preview_server.py`. Inputs retain their original evidence; no collection or physics stepping occurs. The first version accepts one URDF robot and Cube rigid @@ -103,6 +103,17 @@ single immutable image/state snapshot; WebRTC is follow-up work. FK and episode budgets bound preload, controls are queued for the render owner, and native resources/ports close on exit. See the example's `ghost-preview.md` for usage. +`preview --job` uses `_preview_job.py` to freeze lower/upper/center and stratified +interior parameter points, then invokes ordinary native collection in owned child +processes before opening the viewer. Physical ranges, atlas request domains and +explicit joint/via-point draws retain original validation. Each point enumerates +its configured motion/affordance recipes; exact-zero residuals collapse to the +unique nominal variant. Source semantics and aggregate attempts/time budgets are +checked, failed endpoints remain in the coverage manifest, and no replacement +sampling or success credit is allowed. Original job outputs remain untouched. Episodes archive `source_env_id` for +row-correct diagnostics even without a motion profile; ambiguous legacy grasp +annotations remain unavailable rather than selecting row zero. + `TaskProgramDemoBridge.program_id` and `env_ids` expose binding identity without runtime traversal. `EmbodiedEnv.task_program_bridge_scope()` restores the borrowed bridge even after failure. `Real2SimTabletopSource` and explicit diff --git a/agent_context/topics/motion-planning/trajectory-expansion.md b/agent_context/topics/motion-planning/trajectory-expansion.md index 5d8dcb9fe5..d6faa8a58f 100644 --- a/agent_context/topics/motion-planning/trajectory-expansion.md +++ b/agent_context/topics/motion-planning/trajectory-expansion.md @@ -93,3 +93,13 @@ separate from path, dynamic and task validation. Use `tests/sim/motion/expansion/` for algorithm/contracts coverage and host tests for stepping, acceptance and persistence. Examples are not production test APIs. + +## Explicit boundary draws + +Spatial profiles optionally carry `joint_samples` (named controlled-joint signed +fractions) and `knot_samples` (via-point magnitudes), each finite in [-1,1]. +The combined Task Program adapter forwards them to the ordinary operators; +absence retains local-RNG sampling. Explicit draws never bypass phase permissions, +endpoint protection, deduplication, joint limits or measured acceptance. One named +joint draw is reused across permitted phases. The Expansion Engine preview owns +parameter-domain sampling and coverage accounting, not the motion operators. diff --git a/embodichain/cli/expansion.py b/embodichain/cli/expansion.py index 5c2ace7a7a..d3774a65d8 100644 --- a/embodichain/cli/expansion.py +++ b/embodichain/cli/expansion.py @@ -48,11 +48,37 @@ def main(argv: Sequence[str] | None = None) -> int: command = commands.add_parser( "preview", help="Replay confirmed results with native ghost rendering" ) + source = command.add_mutually_exclusive_group(required=True) + source.add_argument( + "--input", + "--inpu", + dest="inputs", + action="append", + help="Existing job output or preview-plan directory; repeat for groups", + ) + source.add_argument( + "--job", + help="Compute an endpoint/interior preview from a Task Program expansion job", + ) command.add_argument( "--output", - action="append", - required=True, - help="Result directory with job.json; repeat for spatial groups", + help="New collection directory for --job; never an existing-result input", + ) + command.add_argument( + "--interior-samples", + type=int, + default=5, + help="Stratified interior parameter points, in addition to center and both extrema", + ) + command.add_argument( + "--plan-only", + action="store_true", + help="Freeze and validate the preview plan without collection/rendering", + ) + command.add_argument( + "--no-open", + action="store_true", + help="Do not open a browser after --job collection", ) command.add_argument( "--reference", @@ -97,8 +123,72 @@ def main(argv: Sequence[str] | None = None) -> int: from embodichain.lab.expansion._preview_server import serve_preview try: + if args.open and args.no_open: + parser.error("--open and --no-open are mutually exclusive") + coverage = None + if args.job: + if args.reference: + parser.error( + "--reference is only valid with existing --input results" + ) + from embodichain.lab.expansion._preview_job import ( + plan_preview, + collect_preview, + ) + + coverage = plan_preview( + Path(args.job), + Path(args.output) if args.output else None, + interior=args.interior_samples, + max_episodes=args.max_episodes, + ) + print( + json.dumps( + { + "preview_plan": str( + Path(coverage["output"]) / "preview-plan.json" + ), + "parameter_points": len(coverage["records"]), + "planned_attempts": coverage["planned_attempts"], + } + ), + flush=True, + ) + if args.plan_only: + return 0 + import torch + + if args.gpu >= torch.cuda.device_count(): + parser.error( + "preview GPU is outside CUDA_VISIBLE_DEVICES; use a visible device ordinal" + ) + coverage = collect_preview(coverage) + print( + json.dumps( + { + "confirmed": coverage["confirmed"], + "planned_attempts": coverage["planned_attempts"], + "coverage_complete": coverage["coverage_complete"], + "output": coverage["output"], + } + ), + flush=True, + ) + if not coverage["confirmed"]: + print( + "No qualified trajectories; inspect preview-plan.json and sample logs. No boundary was replaced.", + flush=True, + ) + return 2 + inputs = [Path(coverage["output"])] + else: + if args.output or args.plan_only: + parser.error( + "--output and --plan-only require --job; use --input for existing results" + ) + inputs = [Path(p) for p in args.inputs] data = load_preview( - [Path(p) for p in args.output], + inputs, Path(args.reference) if args.reference else None, robot_asset=Path(args.robot_asset) if args.robot_asset else None, eef_link=args.eef_link, @@ -108,14 +198,14 @@ def main(argv: Sequence[str] | None = None) -> int: data, port=args.port, gpu=args.gpu, - open_browser=args.open, + open_browser=(bool(args.job) or args.open) and not args.no_open, duration=args.duration, ) except KeyboardInterrupt: return 0 except (ValueError, OSError) as exc: parser.error(str(exc)) - return 0 + return 2 if coverage and not coverage["coverage_complete"] else 0 from embodichain.lab.expansion.configured import ( load_expansion_job, ) diff --git a/embodichain/lab/expansion/_gym_episode.py b/embodichain/lab/expansion/_gym_episode.py index 7d504163a7..fd686fc458 100644 --- a/embodichain/lab/expansion/_gym_episode.py +++ b/embodichain/lab/expansion/_gym_episode.py @@ -121,6 +121,7 @@ def assemble(self, assignments, collector, services, result, physics_after): observations[key] = torch.stack(values) scene_keys.append({"key": key, "entity_uid": uid, "field": field}) metadata = { + "source_env_id": row, "attempt_sequence": ctx.requests[row].sequence, "job_instance_id": ctx.journal.job_instance_id, "recipe_id": ctx.requests[row].recipe.recipe_id, diff --git a/embodichain/lab/expansion/_preview.html b/embodichain/lab/expansion/_preview.html index ad53361468..f1615652c9 100644 --- a/embodichain/lab/expansion/_preview.html +++ b/embodichain/lab/expansion/_preview.html @@ -4,7 +4,7 @@

EmbodiChain · 扩增结果回放

完整模型虚影 · 已确认的真实扩增结果

正在连接原生渲染器
拖动画面旋转 · 滚轮缩放
EmbodiChain 原生场景渲染画面
正在加载完整机器人模型…
——
-
EmbodiChain SimulationManager / RobotMarkers / VisualizationMarkers → DexSim Hybrid 原生渲染。仅回放,物理推进 0 步。机器人与物体使用逐帧记录;轨迹线每 4 帧取点并连接。视角、灯光与透明材质仅用于验收展示。
@@ -21,6 +21,7 @@ let pointer=null;$('frame').onpointerdown=e=>{if(!status)return;pointer={x:e.clientX,y:e.clientY,yaw:status.yaw,e:status.elevation};$('frame').setPointerCapture(e.pointerId)};$('frame').onpointermove=e=>{if(pointer)control({yaw:Math.max(-20,Math.min(20,pointer.yaw-(e.clientX-pointer.x)*.008)),elevation:Math.max(.1,Math.min(1.5,pointer.e+(e.clientY-pointer.y)*.006))})};$('frame').onpointerup=$('frame').onpointercancel=()=>pointer=null; $('frame').addEventListener('wheel',e=>{e.preventDefault();if(status)control({distance:Math.max(.2,Math.min(20,status.distance+e.deltaY*.001))})},{passive:false}); async function poll(){if(busy||document.hidden)return;busy=true;try{const r=await fetch('/snapshot');if(!r.ok)throw Error('连接失败');const s=await r.json();if(s.frame===undefined)return;status=s; +if(s.coverage){$('coverage-panel').hidden=false;const c=s.coverage;$('coverage-summary').textContent=`计划 ${c.planned_attempts} · 已尝试 ${c.records.reduce((n,r)=>n+r.attempts,0)} · 已确认 ${c.records.reduce((n,r)=>n+r.confirmed,0)}。${c.coverage_complete?'全部计划样本已确认':'包含未通过、回退或未执行点'}`;$('coverage-details').style.whiteSpace='pre-line';$('coverage-details').textContent='有限参数采样,不代表连续空间或全部边界组合穷举。\n'+c.axes.map(a=>`${a.name}: [${a.lower}, ${a.upper}]`).join('\n')+'\n\n'+c.records.map(r=>`#${r.index} ${r.role} · ${r.status} · ${r.confirmed}/${r.planned ?? c.recipes_per_point} 确认\n${Object.entries(r.values).map(([k,v])=>k+'='+Number(v).toPrecision(4)).join(', ')}`).join('\n\n')} if(!initialized){for(const key of ['space','aff','variant'])for(const value of s.options[key]){const o=document.createElement('option');o.value=value;o.textContent=value==='unrecorded'?'未记录':value;$(key).append(o)}if(!s.options.align.includes('phase'))$('align').querySelector('[value="phase"]').remove();$('reference').disabled=!s.has_reference;initialized=true} if(!sending){for(const k of ['space','aff','variant','align'])if(document.activeElement!==$(k))$(k).value=s[k];for(const k of ['ghosts','reference','paths','targets','positions'])$(k).checked=s[k];if(document.activeElement!==$('camera'))$('camera').value=Object.keys(cameras).find(k=>Object.keys(cameras[k]).every(p=>Math.abs(s[p]-cameras[k][p])<.001))||'custom'} $('connection').textContent='● 原生渲染 · HTTP JPEG';$('connection').classList.remove('error');$('count').textContent=s.count;$('total').textContent=` / ${s.total} 条符合筛选`;$('play').disabled=!s.count;$('play').textContent=s.playing?'暂停':'播放';if(!dragging)$('progress').value=Math.round(s.progress*1000); diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py index 0dfeb76d8c..adf91221d0 100644 --- a/embodichain/lab/expansion/_preview_data.py +++ b/embodichain/lab/expansion/_preview_data.py @@ -56,15 +56,35 @@ class PreviewClip: def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: records = metadata.get("expansion", ()) - env_ids = {r["env_id"] for r in records if "env_id" in r} + env_ids = {r["env_id"] for r in records if r.get("env_id") is not None} + if metadata.get("source_env_id") is not None: + source_row = metadata["source_env_id"] + if type(source_row) is not int or source_row < 0: + raise ValueError("source_env_id must be a nonnegative integer") + env_ids.add(source_row) if len(env_ids) > 1: raise ValueError("Episode expansion annotations refer to multiple rows") env_id = next(iter(env_ids), None) branches, candidates, targets, phases = [], [], [], [] + phase_safe = True for segment in metadata.get("program_segments", ()): for call in segment.get("metadata", {}).get("runtime", {}).get("calls", ()): for event in call.get("events", ()): if event.get("kind") == "trajectory_segment_entered": + mask = event.get("env_mask") + if mask: + if env_id is not None: + index = 0 if len(mask) == 1 else env_id + if index >= len(mask): + phase_safe = False + continue + if not mask[index]: + continue + elif len(set(mask)) > 1: + phase_safe = False + continue + elif not any(mask): + continue phases.append( ( str(call["call"]["call_kind"]) @@ -93,9 +113,8 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: else 0 if env_id is None and len(rows) == 1 else None ) if row is None: - raise ValueError( - "Cannot bind grasp annotation to the recorded environment row" - ) + # Legacy numeric evidence remains usable; never guess another row's grasp. + continue if not sample["success"][row]: continue sampling = sample.get("sampling") or {} @@ -127,7 +146,8 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: phases = [v for i, v in enumerate(phases) if i == 0 or v != phases[i - 1]] anchors = np.array([p[1] for p in phases] + [measured.timestamps[-1]]) if ( - not phases + not phase_safe + or not phases or anchors[0] < 0 or not np.isfinite(anchors).all() or not np.all(np.diff(anchors) > 0) @@ -203,6 +223,7 @@ class PreviewData: eef_link: str boxes: dict[str, tuple[float, ...]] ground_visible: bool = True + coverage: dict[str, Any] | None = None @property def all_clips(self) -> list[PreviewClip]: @@ -226,6 +247,21 @@ def load_preview( ) -> PreviewData: if not outputs or not 1 <= max_episodes <= 64: raise ValueError("Provide result directories and max_episodes in [1,64]") + coverage = None + if len(outputs) == 1 and (Path(outputs[0]) / "preview-plan.json").is_file(): + root = Path(outputs[0]).resolve() + coverage = json.loads((root / "preview-plan.json").read_text()) + outputs = [] + for record in coverage["records"]: + path = (root / record["result"]).resolve() + if not path.is_relative_to(root): + raise ValueError("Preview result path escapes the manifest directory") + if record["confirmed"] > 0: + outputs.append(path) + if not outputs: + raise ValueError( + "Preview plan has no qualified trajectories; inspect its rejection/unrun records" + ) paths = [Path(p).expanduser().resolve() for p in outputs] if len(set(paths)) != len(paths): raise ValueError("Duplicate output directory") @@ -335,7 +371,7 @@ def load_preview( else: clips.append(clip) clip.label = f"C-{len(clips):03d}" - return PreviewData(clips, reference_clip, asset, end, boxes, ground) + return PreviewData(clips, reference_clip, asset, end, boxes, ground, coverage) class PreviewState: @@ -443,6 +479,7 @@ def snapshot(self) -> dict[str, Any]: "total": len(self.data.clips), "options": self.options, "has_reference": self.data.reference is not None, + "coverage": self.data.coverage, "label": c.label if visible else "No matches", "source_frame": f if visible else None, "source_frames": len(c.measured.timestamps) if visible else 0, diff --git a/embodichain/lab/expansion/_preview_job.py b/embodichain/lab/expansion/_preview_job.py new file mode 100644 index 0000000000..55086e7306 --- /dev/null +++ b/embodichain/lab/expansion/_preview_job.py @@ -0,0 +1,550 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Freeze endpoint/interior experiments and collect them through the native CLI.""" + +from __future__ import annotations + +from copy import deepcopy +from datetime import datetime, timezone +from pathlib import Path +from typing import Any +import hashlib +import json +import os +import signal +import subprocess +import sys +import time +from uuid import uuid4 +import numpy as np +from scipy.spatial.transform import Rotation +import yaml + +from .configured import load_expansion_job, preflight_expansion_job +from .persistence import ArtifactEpisodeSink, load_expansion_episode + +__all__: list[str] = [] + + +def boundary_samples( + dimensions: int, interior: int, seed: int +) -> tuple[np.ndarray, list[str]]: + if ( + type(dimensions) is not int + or dimensions < 0 + or type(interior) is not int + or not 1 <= interior <= 61 + ): + raise ValueError("interior samples must be in [1,61]") + if not dimensions: + return np.empty((1, 0)), ["fixed"] + rng = np.random.default_rng(seed) + points = [np.full(dimensions, 0.5), np.zeros(dimensions), np.ones(dimensions)] + # Independent Latin-hypercube strata in every varying coordinate. + inside = np.stack( + [ + (rng.permutation(interior) + rng.uniform(0.05, 0.95, interior)) / interior + for _ in range(dimensions) + ], + axis=1, + ) + points.extend(inside) + return np.asarray(points), ["center", "lower", "upper"] + [ + f"interior-{i+1}" for i in range(interior) + ] + + +def _atomic(path: Path, value: Any) -> None: + temporary = path.with_suffix(".tmp") + temporary.write_text(json.dumps(value, indent=2, allow_nan=False)) + temporary.replace(path) + + +def plan_preview( + job: Path, output: Path | None, *, interior: int = 5, max_episodes: int = 32 +) -> dict[str, Any]: + from embodichain.lab.sim.motion.expansion.profile import load_expansion_profile + from embodichain.lab.sim.motion.expansion.combined import ( + enumerate_candidate_recipes, + ) + + if type(max_episodes) is not int or not 1 <= max_episodes <= 64: + raise ValueError("max_episodes must be in [1,64]") + cfg = load_expansion_job(job) + report = preflight_expansion_job(cfg) + if cfg.source != "task_program" or report.get("motion_source") != "native": + raise ValueError( + "preview --job currently requires native Task Program planning" + ) + if cfg.visual_profile or cfg.render_profiles or cfg.source_profile: + raise ValueError( + "Distribution preview does not sample visual or prototype profiles" + ) + axes = [] + + def axis(name: str, lower: float, upper: float, kind: str, **details: Any) -> None: + if lower != upper: + axes.append( + dict( + name=name, + lower=float(lower), + upper=float(upper), + kind=kind, + **details, + ) + ) + + for kind in ( + "mass_scale", + "friction", + "joint_stiffness_scale", + "joint_damping_scale", + ): + for uid, bounds in sorted(getattr(cfg, kind).items()): + axis(f"{kind}/{uid}", *bounds, kind, uid=uid) + for uid, ranges in sorted(cfg.center_of_mass.items()): + for i, bounds in enumerate(ranges): + axis( + f"center_of_mass/{uid}/{i}", *bounds, "center_of_mass", uid=uid, index=i + ) + profile = None + motion = None + recipe_count = 1 + if cfg.motion_profile: + profile = load_expansion_profile(cfg.motion_profile) + motion = yaml.safe_load(Path(cfg.motion_profile).read_text()) + recipe_count = len(enumerate_candidate_recipes(profile)) + if profile.scene_randomization.reference_family_count != 1: + raise ValueError( + "Use a scene atlas for spatial bounds, not implicit motion families" + ) + spatial = profile.trajectory.spatial + if spatial.enabled and profile.trajectory.variants_per_family > 1: + if profile.trajectory.variants_per_family < len(spatial.operators) + 1: + raise ValueError( + "Preview needs a nominal variant plus at least one variant per configured operator" + ) + if set(spatial.operators) - {"joint_residual", "via_points"}: + raise ValueError( + "Explicit boundary draws support joint_residual and via_points" + ) + robot = report["resolved_deployment"]["robot"] + groups = robot["control_parts"] + parts = robot.get("solver_cfg", {}).keys() + joints = sorted({name for part in parts for name in groups.get(part, [])}) + if not joints or any(not isinstance(j, str) for j in joints): + raise ValueError( + "Named solver control joints are required to bound motion draws" + ) + for name in joints: + if name not in spatial.joint_samples: + axis(f"joint_residual_fraction/{name}", -1, 1, "joint", uid=name) + if "via_points" in spatial.operators and not spatial.knot_samples: + for i in range(spatial.via_count): + axis(f"via_knot_fraction/{i}", -1, 1, "knot", index=i) + prepared = None + deployment = None + if cfg.scene_atlas: + from embodichain.lab.sim.scene.feasibility import load_feasibility_atlas + from embodichain.lab.sim.scene.feasibility.search import ( + PreparedFeasibilitySearch, + ) + from embodichain.lab.sim.scene.feasibility.cfg import SceneRobotFeasibilityCfg + from embodichain.lab.gym.utils.composition import resolve_gym_components + + atlas = load_feasibility_atlas(cfg.scene_atlas) + if len(atlas.request.modes) != 1: + raise ValueError("Preview requires one task mode per scene atlas") + prepared = PreparedFeasibilitySearch( + atlas.request, SceneRobotFeasibilityCfg(seed=cfg.seed) + ) + for i, var in enumerate(atlas.request.variables): + for j, (lo, hi) in enumerate(zip(var.lower, var.upper)): + axis( + f'scene/{var.name}/{("x","y","yaw")[j]}', + lo, + hi, + "scene", + index=i * 3 + j, + ) + raw = yaml.safe_load(Path(cfg.deployment).read_text()) + deployment = resolve_gym_components( + raw, base_dir=Path(cfg.deployment).parent + ).config + for key in ("program", "integration", "execution_policy"): + value = deployment.get("task_program", {}).get(key) + if isinstance(value, str): + deployment["task_program"][key] = str( + (Path(cfg.deployment).parent / value).resolve() + ) + elif isinstance(value, dict) and isinstance(value.get("component"), str): + value["component"] = str( + (Path(cfg.deployment).parent / value["component"]).resolve() + ) + if "embodiment" in raw: + deployment.pop("robot", None) + deployment.pop("sensor", None) + embodiment = deepcopy(raw["embodiment"]) + embodiment["component"] = str( + (Path(cfg.deployment).parent / embodiment["component"]).resolve() + ) + deployment["embodiment"] = embodiment + points, roles = boundary_samples(len(axes), interior, cfg.seed) + counts = [] + for unit in points: + samples = dict(profile.trajectory.spatial.joint_samples) if profile else {} + for a, u in zip(axes, unit): + if a["kind"] == "joint": + samples[a["uid"]] = a["lower"] + float(u) * (a["upper"] - a["lower"]) + counts.append( + profile.affordance.branches_per_family + if profile and samples and all(v == 0 for v in samples.values()) + else recipe_count + ) + total = sum(counts) + if total > max_episodes or total > 64 or total > cfg.max_attempts: + raise ValueError( + f"Preview needs {len(points)} parameter points and up to {recipe_count} motion/affordance recipes per point = {total} attempts; increase --max-episodes (up to 64) and the job max_attempts budget, reduce --interior-samples or use a smaller recipe. Nothing executed." + ) + root = ( + Path(output).expanduser().resolve() + if output + else Path(cfg.output_dir).parent + / ( + Path(cfg.output_dir).name + + "-preview-" + + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S") + + "-" + + uuid4().hex[:6] + ) + ) + if root.exists(): + raise FileExistsError( + f"Preview output must be new: {root}; use --input to replay" + ) + # Validate the renderer's supported scene before any costly collection. + from ._preview_data import _scene + + supported = deepcopy(report) + supported["config"] = dict(report.get("config", {}), scene_atlas=None) + _scene(supported) + root.mkdir(parents=True) + (root / "configs").mkdir() + (root / "logs").mkdir() + plan = { + "schema_version": 1, + "source_job": str(Path(job).resolve()), + "source_sha256": hashlib.sha256(Path(job).read_bytes()).hexdigest(), + "source_inputs": report["input_files"], + "source_atlas": cfg.scene_atlas, + "seed": cfg.seed, + "sampling": "lower + upper + center + stratified interior; not a Cartesian grid", + "axes": axes, + "planned_attempts": total, + "recipes_per_point": recipe_count, + "collection_budget_s": cfg.max_wall_time_s, + "output": str(root), + "records": [], + "complete": False, + "coverage_complete": False, + } + for index, (unit, role) in enumerate(zip(points, roles)): + values = { + a["name"]: a["lower"] + float(u) * (a["upper"] - a["lower"]) + for a, u in zip(axes, unit) + } + case = cfg.to_dict() + case.update( + output_dir=str(root / f"jobs/sample-{index:03d}"), + target_episodes=recipe_count, + max_attempts=recipe_count, + retry_interrupted=False, + ) + m = deepcopy(motion) + scene_unit = np.zeros(prepared.dimensions) if prepared else None + if m: + spatial = m["trajectory"]["spatial"] + spatial["joint_samples"] = dict(profile.trajectory.spatial.joint_samples) + knots = list( + profile.trajectory.spatial.knot_samples + or [0.0] * profile.trajectory.spatial.via_count + ) + for a, u in zip(axes, unit): + value = values[a["name"]] + kind = a["kind"] + if kind == "joint": + spatial["joint_samples"][a["uid"]] = value + elif kind == "knot": + knots[a["index"]] = value + elif kind == "scene": + scene_unit[a["index"]] = u + elif kind == "center_of_mass": + case[kind][a["uid"]] = [list(v) for v in case[kind][a["uid"]]] + case[kind][a["uid"]][a["index"]] = [value, value] + else: + case[kind][a["uid"]] = [value, value] + if m: + if "via_points" in profile.trajectory.spatial.operators: + spatial["knot_samples"] = knots + # Exact zero residuals are the nominal trajectory, not extra successes. + # Keep native deduplication intact by requesting only that unique variant. + if spatial.get("joint_samples") and all( + v == 0 for v in spatial["joint_samples"].values() + ): + m["trajectory"]["variants_per_family"] = 1 + case["target_episodes"] = case["max_attempts"] = ( + profile.affordance.branches_per_family + ) + motion_path = root / "configs" / f"motion-{index:03d}.yaml" + motion_path.write_text(yaml.safe_dump(m, sort_keys=False)) + case["motion_profile"] = str(motion_path) + requested_positions = { + obj["uid"]: obj.get("init_pos", [0, 0, 0]) + for obj in report["resolved_deployment"].get("rigid_object", []) + } + if prepared: + candidate = prepared.candidate( + scene_unit, mode_id=prepared.request.modes[0].mode_id, ordinal=index + ) + derived = deepcopy(deployment) + changes = { + p.entity_uid: np.asarray(p.arena_pose) + for p in candidate.scene.pose_changes + } + for obj in derived.get( + "rigid_object", derived.get("simulation", {}).get("rigid_object", []) + ): + if obj["uid"] in changes: + pose = changes.pop(obj["uid"]) + obj["init_pos"] = pose[:3, 3].tolist() + obj["init_rot"] = ( + Rotation.from_matrix(pose[:3, :3]) + .as_euler("xyz", degrees=True) + .tolist() + ) + requested_positions[obj["uid"]] = obj["init_pos"] + if changes: + raise ValueError( + f"Unsupported scene variable entities: {list(changes)}" + ) + robot_uid = report["resolved_deployment"]["robot"]["uid"] + for uid, pose in candidate.deployment.poses.items(): + if uid != robot_uid: + raise ValueError("Scene variable selects a different robot") + pose = np.asarray(pose) + target = ( + derived["embodiment"].setdefault("overrides", {}) + if "embodiment" in derived + else derived["robot"] + ) + target["init_pos"] = pose[:3, 3].tolist() + target["init_rot"] = ( + Rotation.from_matrix(pose[:3, :3]) + .as_euler("xyz", degrees=True) + .tolist() + ) + deployment_path = root / "configs" / f"task-{index:03d}.yaml" + deployment_path.write_text(yaml.safe_dump(derived, sort_keys=False)) + case["deployment"] = str(deployment_path) + case["scene_atlas"] = None + config_path = root / "configs" / f"job-{index:03d}.yaml" + config_path.write_text(yaml.safe_dump(case, sort_keys=False)) + # Same public preflight and acceptance configuration as ordinary collection. + pinned = preflight_expansion_job(load_expansion_job(config_path)) + plan["records"].append( + dict( + semantic_id=pinned["semantic_id"], + scene_candidate_id=candidate.candidate_id if prepared else None, + index=index, + role=role, + unit=unit.tolist(), + values=values, + requested_positions=requested_positions, + job=str(config_path.relative_to(root)), + result=str(Path(case["output_dir"]).relative_to(root)), + status="unrun", + confirmed=0, + attempts=0, + planned=case["target_episodes"], + ) + ) + plan["planned_attempts"] = sum(r["planned"] for r in plan["records"]) + _atomic(root / "preview-plan.json", plan) + return plan + + +def _exact_recipe(metadata: Any) -> bool: + records = metadata.get("expansion", ()) + if any( + r.get("fallback_count", 0) + or ( + r.get("trajectory_requested") is not None + and r.get("trajectory_requested") != r.get("trajectory_selected") + ) + for r in records + ): + return False + if not any(r.get("affordance_requested") is not None for r in records): + return True + rows = {r["env_id"] for r in records if r.get("env_id") is not None} + env_id = metadata.get("source_env_id", next(iter(rows)) if len(rows) == 1 else None) + found = False + for segment in metadata.get("program_segments", ()): + for call in segment.get("metadata", {}).get("runtime", {}).get("calls", ()): + attempts = call.get("plan_attempts", ()) + if not attempts: + continue + sample = ( + attempts[-1] + .get("planner_diagnostics", {}) + .get("metadata", {}) + .get("affordance_sample", {}) + .get("grasp") + ) + if sample is None: + continue + ids = list(sample["env_ids"]) + index = ( + ids.index(env_id) + if env_id in ids + else 0 if env_id is None and len(ids) == 1 else None + ) + if ( + index is None + or not sample["success"][index] + or sample.get("reused", [True] * len(ids))[index] + ): + return False + found = True + return found + + +def collect_preview(plan: dict[str, Any]) -> dict[str, Any]: + root = Path(plan["output"]) + started = time.monotonic() + for record in plan["records"]: + remaining = plan["collection_budget_s"] - (time.monotonic() - started) + if remaining <= 0: + record["status"] = "budget_exhausted" + continue + job = root / record["job"] + cfg = yaml.safe_load(job.read_text()) + cfg["max_wall_time_s"] = min(cfg["max_wall_time_s"], remaining) + job.write_text(yaml.safe_dump(cfg, sort_keys=False)) + current = preflight_expansion_job(load_expansion_job(job)) + if current["semantic_id"] != record["semantic_id"]: + record["status"] = "source_changed" + _atomic(root / "preview-plan.json", plan) + raise ValueError("Preview inputs changed after planning; create a new plan") + remaining = plan["collection_budget_s"] - (time.monotonic() - started) + if remaining <= 0: + record["status"] = "budget_exhausted" + _atomic(root / "preview-plan.json", plan) + continue + record["status"] = "running" + _atomic(root / "preview-plan.json", plan) + print( + f"Preview sample {record['index']+1}/{len(plan['records'])}: {record['role']}", + flush=True, + ) + env = dict(os.environ) + env.setdefault("OMP_NUM_THREADS", "1") + env.setdefault("SDL_VIDEODRIVER", "offscreen") + with (root / "logs" / f"sample-{record['index']:03d}.log").open("w") as log: + process = subprocess.Popen( + [ + sys.executable, + "-m", + "embodichain", + "expansion", + "run", + "--job", + str(job), + ], + stdout=log, + stderr=subprocess.STDOUT, + env=env, + ) + timed_out = False + try: + process.wait(timeout=remaining) + except (subprocess.TimeoutExpired, KeyboardInterrupt) as error: + process.send_signal(signal.SIGINT) + try: + process.wait(timeout=10) + except subprocess.TimeoutExpired: + process.kill() + process.wait() + record["status"] = ( + "interrupted" + if isinstance(error, KeyboardInterrupt) + else "budget_exhausted" + ) + _atomic(root / "preview-plan.json", plan) + if isinstance(error, KeyboardInterrupt): + raise + timed_out = True + result = root / record["result"] + receipts = ArtifactEpisodeSink(result).inspect() if result.is_dir() else () + attempts = [ + json.loads(p.read_text()) + for p in (result / "attempts").glob("*/attempt.json") + ] + record.update( + confirmed=sum(r.confirmed for r in receipts), + attempts=len(attempts), + returncode=process.returncode, + outcomes=[ + { + "ordinal": a.get("ordinal"), + "status": a["status"], + "reason": a.get("reason") or a.get("error"), + } + for a in attempts + ], + ) + exact = 0 + for receipt in receipts: + episode = load_expansion_episode(receipt.storage_id) + if _exact_recipe(episode.metadata): + exact += 1 + record["exact_recipes"] = exact + record["status"] = ( + "budget_exhausted" + if timed_out + else ( + "confirmed" + if record["confirmed"] == record["planned"] + and exact == record["planned"] + else ( + "partial" + if record["confirmed"] + else "rejected" if process.returncode in (0, 2) else "error" + ) + ) + ) + _atomic(root / "preview-plan.json", plan) + plan["complete"] = all( + r["attempts"] >= r["planned"] + and r["status"] in {"confirmed", "partial", "rejected"} + for r in plan["records"] + ) + plan["coverage_complete"] = all(r["status"] == "confirmed" for r in plan["records"]) + plan["confirmed"] = sum(r["confirmed"] for r in plan["records"]) + plan["elapsed_s"] = time.monotonic() - started + _atomic(root / "preview-plan.json", plan) + return plan diff --git a/embodichain/lab/expansion/_preview_render.py b/embodichain/lab/expansion/_preview_render.py index eb75338930..4bf154de4a 100644 --- a/embodichain/lab/expansion/_preview_render.py +++ b/embodichain/lab/expansion/_preview_render.py @@ -212,6 +212,31 @@ def markers(name: str, shapes: dict) -> Any: ) }, ) + self.planned = markers( + "planned_parameter_positions", + { + "confirmed": MarkerPrototypeCfg( + shape="sphere", + scale=(0.018, 0.018, 0.018), + color=(0.3, 0.8, 0.4, 0.4), + ), + "unqualified": MarkerPrototypeCfg( + shape="sphere", + scale=(0.022, 0.022, 0.022), + color=(1, 0.25, 0.15, 0.65), + ), + }, + ) + if data.coverage: + points, types = [], [] + for record in data.coverage["records"]: + for point in record.get("requested_positions", {}).values(): + points.append(point) + types.append(0 if record["status"] == "confirmed" else 1) + self.planned.visualize( + np.asarray(points).reshape(-1, 3), + marker_indices=np.asarray(types, dtype=int), + ) self.camera = scene.add_camera( spawn.CameraDesc(name="expansion_preview_camera", resolution=(1100, 760)) ) @@ -314,6 +339,7 @@ def draw(self, state: PreviewState) -> bytes: objects.visualize( p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) ) + self.planned.set_visibility(v["positions"] and v["space"] == "all") self.paths.set_visibility(v["paths"]) self.targets.set_visibility(v["targets"]) self.positions.set_visibility(v["positions"]) diff --git a/embodichain/lab/expansion/session_cfg.py b/embodichain/lab/expansion/session_cfg.py index a66a3851fb..7808c707ca 100644 --- a/embodichain/lab/expansion/session_cfg.py +++ b/embodichain/lab/expansion/session_cfg.py @@ -125,6 +125,13 @@ def _decode(cls: type, data: Mapping[str, Any], path: str = "") -> Any: ) for item_key, item_value in value.items() } + elif value_type is float: + if any( + type(v) not in (int, float) or not math.isfinite(v) + for v in value.values() + ): + raise ValueError(f"{name} must map strings to finite numbers") + decoded[key] = {k: float(v) for k, v in value.items()} elif value_type is str: if any(type(item_value) is not str for item_value in value.values()): raise ValueError(f"{name} must map strings to strings") diff --git a/embodichain/lab/sim/motion/expansion/_samples.py b/embodichain/lab/sim/motion/expansion/_samples.py new file mode 100644 index 0000000000..7011c2c35f --- /dev/null +++ b/embodichain/lab/sim/motion/expansion/_samples.py @@ -0,0 +1,43 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Validated, explicit spatial draws for reproducible boundary experiments.""" + +from __future__ import annotations +from collections.abc import Mapping +import math + +__all__: list[str] = [] + + +def validate_samples( + joints: object, knots: object, via_count: int +) -> tuple[dict[str, float], tuple[float, ...]]: + if not isinstance(joints, Mapping) or any( + not isinstance(k, str) or not k for k in joints + ): + raise ValueError("joint_samples must map joint names to signed fractions") + if not isinstance(knots, (tuple, list)): + raise ValueError("knot_samples must be a sequence") + values = tuple(joints.values()) + tuple(knots) + if any( + type(v) not in (int, float) or not math.isfinite(v) or not -1 <= v <= 1 + for v in values + ): + raise ValueError("explicit spatial samples must be finite and in [-1,1]") + if knots and len(knots) != via_count: + raise ValueError("knot_samples must match via_count") + return {k: float(v) for k, v in joints.items()}, tuple(float(v) for v in knots) diff --git a/embodichain/lab/sim/motion/expansion/cfg.py b/embodichain/lab/sim/motion/expansion/cfg.py index 1a56e362fe..6f4f74598b 100644 --- a/embodichain/lab/sim/motion/expansion/cfg.py +++ b/embodichain/lab/sim/motion/expansion/cfg.py @@ -93,8 +93,16 @@ class _SpatialCfg: method: tuple[str, ...] = ("joint_residual",) joint_offset_scale: float = 0.05 via_count: int = 1 + joint_samples: dict[str, float] = {} + knot_samples: tuple[float, ...] = () def __post_init__(self) -> None: + from ._samples import validate_samples + + self.joint_samples, self.knot_samples = validate_samples( + self.joint_samples, self.knot_samples, self.via_count + ) + _boolean(self.enabled, "spatial.enabled") methods = (self.method,) if isinstance(self.method, str) else tuple(self.method) if not methods: diff --git a/embodichain/lab/sim/motion/expansion/combined.py b/embodichain/lab/sim/motion/expansion/combined.py index 0acae6e3b6..5f526a97a2 100644 --- a/embodichain/lab/sim/motion/expansion/combined.py +++ b/embodichain/lab/sim/motion/expansion/combined.py @@ -236,8 +236,16 @@ class _SpatialCfg: joint_offset_scale: float = 0.05 dedup_tolerance: float | None = None via_count: int = 1 + joint_samples: dict[str, float] = {} + knot_samples: tuple[float, ...] = () def __post_init__(self) -> None: + from ._samples import validate_samples + + self.joint_samples, self.knot_samples = validate_samples( + self.joint_samples, self.knot_samples, self.via_count + ) + self.operators = _strings(self.operators, "trajectory.spatial.operators") if any(item not in ("joint_residual", "via_points") for item in self.operators): raise ValueError( @@ -520,6 +528,8 @@ def from_mapping(cls, data: Mapping[str, Any]) -> "CombinedExpansionProfile": "enabled", "operators", "joint_offset_scale", + "joint_samples", + "knot_samples", "dedup_tolerance", "via_count", }, diff --git a/embodichain/lab/sim/motion/expansion/operators.py b/embodichain/lab/sim/motion/expansion/operators.py index f87bceed64..5f9bd20d62 100644 --- a/embodichain/lab/sim/motion/expansion/operators.py +++ b/embodichain/lab/sim/motion/expansion/operators.py @@ -17,6 +17,7 @@ """Grasp-pose and constrained qpos operators requiring downstream validation.""" from __future__ import annotations +from collections.abc import Mapping, Sequence from dataclasses import replace import math @@ -312,6 +313,7 @@ def joint_residual( joint_limits: torch.Tensor, normalized_scale: float, generator: torch.Generator, + joint_samples: Mapping[str, float] | None = None, ) -> TrajectoryTemplate: """Add one smooth, endpoint-preserving residual per allowed free phase. @@ -324,6 +326,10 @@ def joint_residual( joint_limits: Finite lower/upper limits with shape ``(D, 2)``. normalized_scale: Maximum offset as a fraction of each joint range. generator: Explicit local generator; global RNG is never consumed. + joint_samples: Optional signed fractions in [-1,1], keyed by all + controlled joint names. Extra names must belong to the full template. + Uses the same draw in each permitted phase; endpoints and validation + remain unchanged. Omit to retain ordinary random sampling. Returns: A new template requiring path and physical validation. @@ -336,6 +342,14 @@ def joint_residual( q = template.positions.clone() limits = _resolve_joint_limits(q, joint_limits) indices = list(template.controlled_joint_indices) + from ._samples import validate_samples + + samples, _ = validate_samples({} if joint_samples is None else joint_samples, (), 1) + if samples and ( + set(samples) - set(template.joint_names) + or any(template.joint_names[i] not in samples for i in indices) + ): + raise ValueError("joint_samples must cover the controlled joint names") for phase in phases: length = phase.stop_index - phase.start_index if length < 3: @@ -344,7 +358,16 @@ def joint_residual( values = torch.rand( len(indices), generator=generator, device=generator.device, dtype=q.dtype ).to(q.device) - offsets = (2 * values - 1) * scale * (limits[indices, 1] - limits[indices, 0]) + direction = ( + torch.tensor( + [samples[template.joint_names[i]] for i in indices], + device=q.device, + dtype=q.dtype, + ) + if samples + else 2 * values - 1 + ) + offsets = direction * scale * (limits[indices, 1] - limits[indices, 0]) q[phase.start_index : phase.stop_index, indices] += envelope[:, None] * offsets _reject_limit_violations(q, limits, indices) return replace(template, positions=q) @@ -357,6 +380,8 @@ def via_points( via_count: int, normalized_scale: float, generator: torch.Generator, + joint_samples: Mapping[str, float] | None = None, + knot_samples: Sequence[float] = (), ) -> TrajectoryTemplate: """Route each allowed free phase through sampled interior joint knots. @@ -383,6 +408,11 @@ def via_points( via_count: Number of interior knots per phase, at least one. normalized_scale: Maximum knot offset as a fraction of each joint range. generator: Explicit local generator; global RNG is never consumed. + knot_samples: Optional signed knot magnitudes; length must match via_count. + joint_samples: Optional signed fractions in [-1,1], keyed by all + controlled joint names. Extra names must belong to the full template. + Uses the same draw in each permitted phase; endpoints and validation + remain unchanged. Omit to retain ordinary random sampling. Returns: A new template requiring path and physical validation. @@ -398,6 +428,16 @@ def via_points( limits = _resolve_joint_limits(q, joint_limits) indices = list(template.controlled_joint_indices) spans = limits[indices, 1] - limits[indices, 0] + from ._samples import validate_samples + + samples, knots_fixed = validate_samples( + {} if joint_samples is None else joint_samples, knot_samples, via_count + ) + if samples and ( + set(samples) - set(template.joint_names) + or any(template.joint_names[i] not in samples for i in indices) + ): + raise ValueError("joint_samples must cover the controlled joint names") for phase in phases: length = phase.stop_index - phase.start_index if length < via_count + 2: @@ -408,8 +448,20 @@ def via_points( device=generator.device, dtype=q.dtype, ).to(q.device) - magnitudes = 2 * values[:via_count] - 1 - direction = 2 * values[via_count:] - 1 + magnitudes = ( + torch.tensor(knots_fixed, device=q.device, dtype=q.dtype) + if knots_fixed + else 2 * values[:via_count] - 1 + ) + direction = ( + torch.tensor( + [samples[template.joint_names[i]] for i in indices], + device=q.device, + dtype=q.dtype, + ) + if samples + else 2 * values[via_count:] - 1 + ) knots = magnitudes[:, None] * (direction * scale * spans)[None, :] progress = torch.linspace(0, 1, length, device=q.device, dtype=q.dtype) q[phase.start_index : phase.stop_index, indices] += _clamped_hermite( diff --git a/embodichain/lab/sim/motion/expansion/variants.py b/embodichain/lab/sim/motion/expansion/variants.py index 475c8790f8..949ee76ef4 100644 --- a/embodichain/lab/sim/motion/expansion/variants.py +++ b/embodichain/lab/sim/motion/expansion/variants.py @@ -556,6 +556,7 @@ def _apply_variant_once( joint_limits=joint_limits, normalized_scale=spatial.joint_offset_scale, generator=generator, + joint_samples=spatial.joint_samples, ) elif variant.spatial_operator == "via_points": result = via_points( @@ -564,6 +565,8 @@ def _apply_variant_once( via_count=spatial.via_count, normalized_scale=spatial.joint_offset_scale, generator=generator, + joint_samples=spatial.joint_samples, + knot_samples=spatial.knot_samples, ) elif variant.spatial_operator == "nullspace_residual": if target is not None: diff --git a/embodichain/lab/task_program/integrations/expansion.py b/embodichain/lab/task_program/integrations/expansion.py index 7e296f757c..7c62629306 100644 --- a/embodichain/lab/task_program/integrations/expansion.py +++ b/embodichain/lab/task_program/integrations/expansion.py @@ -937,6 +937,10 @@ def _combined_augmentation_payload( } }, } + if spatial.joint_samples: + payload["factors"]["spatial"]["joint_samples"] = spatial.joint_samples + if spatial.knot_samples: + payload["factors"]["spatial"]["knot_samples"] = spatial.knot_samples if spatial.dedup_tolerance is not None: payload["coverage"] = { "joint_dedup_normalized_tol": spatial.dedup_tolerance, diff --git a/examples/expansion/engine/README.md b/examples/expansion/engine/README.md index 61cc1c7383..e1165c7648 100644 --- a/examples/expansion/engine/README.md +++ b/examples/expansion/engine/README.md @@ -26,17 +26,26 @@ capabilities remain explicit. `--reuse` rebuilds the offline page without a Worl ## Native ghost preview -Replay confirmed results directly, without recollection or physics stepping: +Compute Task Program expansion at both parameter bounds and stratified interior +points, validate the real results, then automatically open the native viewer: ```bash -embodichain expansion preview --output /path/to/job-output --gpu 0 --open +embodichain expansion preview --job examples/expansion/engine/job.preview.yaml ``` -Repeat `--output` for spatial groups and optionally add `--reference` with one -confirmed reference episode. The [native preview guide](ghost-preview.md) covers -linked spatial/affordance/trajectory filters, asset recovery, supported scene -geometry, replay semantics and the WebRTC TODO. Rendering is native; browser -transport currently uses HTTP JPEG, not WebRTC. +Preview existing results without any collection: + +```bash +embodichain expansion preview --input /path/to/job-output --gpu 0 --open +``` + +Repeat `--input` for groups, or point it at a generated preview-plan directory. +`--inpu` is an alias for `--input`. In job mode `--output` selects a **new** output +folder; it is no longer the existing-result input flag. `--plan-only` freezes and +validates samples without executing, and `--no-open` suppresses automatic opening. +The [preview guide](ghost-preview.md) explains budgets, failed-boundary evidence, +scene-atlas domains, finite-sampling limitations and the WebRTC TODO. Rendering is +native; browser transport remains HTTP JPEG, not WebRTC. ## Run a configured job diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index dd6a49ddaa..e31f38505b 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -21,25 +21,97 @@ 仓库入口直接读取原始结果,不需要该源码快照、本地预处理 JSON 或实验脚本。 [showcase](showcase/README.md) 的离线三维/RGB-D 页面也是另一条查看路径。 +## 基于 Task Program 重新计算并预览 + +```bash +# 一体化入口:检查配置 → 固定采样计划 → 实测扩增 → 验收 → 原生预览。 +embodichain expansion preview --job examples/expansion/engine/job.preview.yaml + +# 先查看计划。--output 必须是新目录,不会覆盖原 job 的数据。 +embodichain expansion preview --job examples/expansion/engine/job.preview.yaml \ + --output /tmp/preview-plan-check --plan-only + +# 减少区间内采样点,用于快速验证;仍包含中心和两个端点。 +embodichain expansion preview --job examples/expansion/engine/job.preview.yaml \ + --output /tmp/preview-run --interior-samples 1 --no-open --duration 10 + +# 重放整个结果分布及失败/未执行记录,不重新计算。 +embodichain expansion preview --input /tmp/preview-run --open +``` + +`--job` 使用原生 Task Program source、原始动作/物理时钟和验收配置;不支持把 +Real2Sim 或视觉 profile 静默转换为另一种扩增。计算结束后默认尝试打开浏览器, +`--no-open` 可关闭此行为。`--input` 是已有结果的只读入口,兼容别名 `--inpu`; +`--job` 与 `--input` 互斥。`--output` 只在 job 模式指定新产物目录,省略时在原 +job 输出目录旁创建唯一目录。原 job 文件和原产物不修改,也不隐式 resume。 + +### 参数空间与采样含义 + +- 连续物理轴取自 job 的质量、摩擦、关节刚度/阻尼倍率及 CoM 区间。 +- 若配置 `scene_atlas`,读取其原始 request 中物体布局与机器人安装 XY/yaw 的 + lower/upper,通过已有联合场景参数化转换为完整场景/安装姿态。保留组内关系, + 不拼接不同可行区域的边界。采样的是**原始声明范围**,不是历史成功区域证明; + 每个新点都必须重新执行并接受原来的实测验证。 +- 轨迹 `joint_residual` 的受控关节使用独立的有符号比例轴 `[-1,1]`,实际残差 + 幅值由原 `joint_offset_scale × joint range` 决定;`via_points` 另外包含节点 + 幅值轴。`joint_samples` / `knot_samples` 是可选的显式采样值,不设置时原随机 + 算法保持不变。受保护阶段、端点、非受控关节和关节限位检查均保留。 +- 每个参数点遍历配置的 affordance 分支和轨迹 recipe。全零关节残差在数学上 + 等于名义轨迹,因此该点只执行唯一名义变体,避免重复计成功或降低去重阈值。 + 轨迹数量不足以覆盖声明的全部算子时会提前拒绝,并要求补足配置。 +- 未声明范围的维度保持固定;不会把碰撞检查配置里的搜索范围自动当作启用的 + 场景扩增。需要空间扩增时,在 job 中显式设置已有 `scene_atlas`。 + +默认采样包含全下界、全上界、中心和 **5 个 Latin-hypercube 分层区间内点**。 +每个变化轴都包含其两个端点,区间内各轴独立分层。`--interior-samples N` 可调整 +区间内点数。它覆盖的是有限参数样本,**不是所有混合角点的 Cartesian 穷举**, +不是连续空间成功率估计;同一关节的显式偏移复用于各允许自由阶段,也不穷举 +独立分段方向组合。物理约束与 FK 非线性意味着参数端点不等于世界坐标轨迹包络端点。 + +示例 `job.preview.yaml` 声明 2 个抓取分支 × 2 个轨迹变体,默认 8 个参数点; +中心零残差折叠后计划 30 次实测,位于其 `max_attempts: 32` 预算内。 +所有点的总次数受原 job `max_attempts`、`--max-episodes` 和 64 条预览上限共同约束。 +超过预算在执行前报错,不静默截断端点或改窄范围;全部子作业共用原 job 的 +`max_wall_time_s` 总时间预算。`--duration` 仅控制之后的查看时长。 +每个参数点在独立子进程中运行原生 Engine,以明确释放 World;预览进程只在 +采集结束后创建渲染资源。`--gpu` 是当前 `CUDA_VISIBLE_DEVICES` 内的可见编号。 + +### 覆盖报告与失败处理 + +新目录包含 `preview-plan.json`、冻结的 `configs/`、逐点 `logs/` 和原生 `jobs/` +结果。计划记录源文件哈希、上下界、归一化坐标、请求值、目标 recipe 数和后续 +实测结果;执行前重新核对语义身份,源配置发生变化则停止。 + +不会为了填满预览而重新采样、替换失败端点、放宽验收或将轨迹回退算作边界覆盖。 +报告区分已确认、部分通过、拒绝、错误、预算耗尽和未执行。`complete` 表示计划 +尝试完成,`coverage_complete` 仅在全部唯一 recipe 被原样执行并确认时成立;抓取分支复用或轨迹回退不计作完整覆盖。 +存在有效结果时仍打开预览,最终返回 2 表示不完整覆盖;没有有效轨迹时返回 2, +保留报告和日志,不伪造成功回放。 + +页面显示所有计划点的参数和状态,候选虚影只来自确认结果;初始位置图层中, +红色计划点表示未完全确认的参数点,不代表一条失败轨迹。筛选后没有匹配样本时 +显示空结果,不用别的候选替代。WebRTC 接入仍为 TODO。 + ## 从已有结果启动 在安装了兼容 EmbodiChain、DexSim 原生渲染依赖的环境中运行: ```bash # 单个已完成或部分完成的作业:只加载已有确认回执,不继续采集。 -embodichain expansion preview --output /path/to/job-output --gpu 0 --open +embodichain expansion preview --input /path/to/job-output --gpu 0 --open # 复用本次配方的两个空间组,叠加一条独立参考。 embodichain expansion preview \ - --output /path/to/results/space-a \ - --output /path/to/results/space-b \ + --input /path/to/results/space-a \ + --input /path/to/results/space-b \ --reference /path/to/results/reference \ --gpu 0 --port 8769 --open ``` 每个输入是含 `job.json` 和 `episodes/` 的原始作业输出目录;不是导出的 LeRobot -数据集或单个 NPZ。可重复传入 `--output`,空间筛选以输入结果目录分组。 -当前只支持固定布局,不把一个 scene-atlas 作业内部的不同布局合并成同一空间组。 +数据集或单个 NPZ。可重复传入 `--input`,空间筛选以输入结果目录分组。 +已有结果直接读取仍要求固定布局;`--job` 会将 scene-atlas 的每个采样点冻结为 +独立布局子作业,再作为一个参数组加载。 `--reference` 可省略;指定时必须恰好含一个已确认参考 episode,且不能与候选重复。 模型从 `job.json.resolved_deployment.robot` 的 URDF 路径恢复,场景方块尺寸从 @@ -50,7 +122,8 @@ embodichain expansion preview \ 默认从唯一的 solver `end_link_name` 推导末端路径,存在多个端点时必须提供 `--eef-link LINK_NAME`。这里的路径是该 URDF link 的 FK 原点,不隐式附加工具 TCP。 -缺失 affordance/trajectory 注释显示“未记录”,不猜测为名义分支;只有所有轨迹 +缺失 affordance/trajectory 注释显示“未记录”,不猜测为名义分支;新记录保存 +`source_env_id`,旧批量记录无法绑定诊断行时省略抓取目标而不猜用第 0 行。只有所有轨迹 具有一致、有效的动作阶段时才提供阶段对齐。 服务默认仅监听 `127.0.0.1:8769`,打印就绪地址后才能访问;`--port 0` 自动选空闲端口。 @@ -116,7 +189,7 @@ embodichain expansion preview \ 实际初始物体位姿转换到世界坐标。坐标轴展示规划目标,不是实测接触点; 原型把它固定在初始抓取位置,不随搬运中的方块移动。 - **轨迹**:V0/V1 来自执行元数据中的实际选择。末端路径由实测关节 FK 推导, - 原型轨迹线每 4 帧取点并保留末帧;机器人和物体回放仍可访问全部原始状态帧。 + 轨迹线每 4 帧取点并保留末帧;机器人和物体回放仍可访问全部原始状态帧。 - **时间**:支持公共真实时间或六个记录动作阶段的归一化对齐。每个样本取目标 时刻之前最近的已记录帧,不插值生成新姿态;短轨迹到末帧后保持。 阶段对齐只改变浏览进度映射,不改变原始时间戳。页面保留实际秒数和源帧号。 @@ -147,7 +220,7 @@ CLI 不触发采集和安装包页面资源由生产模块的聚焦测试覆盖 `_preview_render.py` 负责,HTTP 服务与页面由 `_preview_server.py`、`_preview.html` 负责,CLI 由 `embodichain/cli/expansion.py` 分发。 -当前明确支持单 URDF 机器人、单位机器人缩放和 Cube 刚体场景。其他 articulated +当前渲染明确支持单 URDF 机器人、单位机器人缩放和 Cube 刚体场景。其他 articulated objects、软体、流体、线缆、mesh/source 物体、背景资产和 scene-atlas 输入会被拒绝; 不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,方块颜色和灯光是展示 外观,不声称精确恢复采集时材质。新任务支持应扩展场景恢复契约并验证实测坐标。 @@ -156,6 +229,18 @@ HTTP JPEG 轮询不提供 WebRTC 的编码、拥塞控制、连接恢复或低 页面是单个服务的共享回放会话,多人操作会改变同一状态;尚未提供独立会话、 认证或通用资产包恢复。当前不应对外公开监听。 +## 一体化入口的实测验收 + +使用已有 UR5 抓取放置任务、default 后端和已保存的联合场景 atlas,覆盖物体 +XY、安装 XY/yaw、质量、摩擦与六个受控关节残差,共 13 个变化轴。 +中心、全下界、全上界和一个区间内点共计划 14 条非重复轨迹(中心 2 条, +其余各 4 条);14 条均完成原有验收并确认,没有轨迹回退或抓取分支复用。 +这是固定小配置的实测结果,不是对任意参数范围或总体成功率的保证。 + +浏览器复测了覆盖报告和 14 → 4 → 2 → 1 → 0 的筛选,包括无结果时隐藏候选 +图层;回放物理推进为 0,自动关闭后端口释放。另行验证了无 motion profile 的 +普通 Task Program 作业也能重新计算并进入预览;批内诊断由来源行号绑定。 + ## TODO:接入 EmbodiChain 原生 WebRTC 推流 后续直接复用 EmbodiChain 原生 WebRTC 能力,替换 HTTP JPEG 轮询;先核对实际 diff --git a/examples/expansion/engine/job.preview.yaml b/examples/expansion/engine/job.preview.yaml new file mode 100644 index 0000000000..1e40c920d6 --- /dev/null +++ b/examples/expansion/engine/job.preview.yaml @@ -0,0 +1,20 @@ +deployment: task.default.yaml +source: task_program +collision_profile: ../scene_robot_feasibility/search.ur5.yaml +output_dir: /tmp/embodichain-expansion/distribution +batch_size: 2 +target_episodes: 4 +max_attempts: 32 +max_steps: 2000 +seed: 7 +settling_steps: 5 +mass_scale: + cube: + - 0.98 + - 1.02 +friction: + cube: + - 0.95 + - 1.0 +motion_profile: motion.preview.yaml +max_wall_time_s: 1800 diff --git a/examples/expansion/engine/motion.preview.yaml b/examples/expansion/engine/motion.preview.yaml new file mode 100644 index 0000000000..88e807158d --- /dev/null +++ b/examples/expansion/engine/motion.preview.yaml @@ -0,0 +1,55 @@ +schema_version: 1 +source: + kind: task_program + source_id: repeated_cube_pick_place + source_revision: one-cycle-v1 + unit_scope: episode + template_id: task_program_call + call_count: 2 + affordance_call_indices: + - 0 + trajectory_call_indices: + - 1 +scene_randomization: + enabled: false + reference_family_count: 1 + profile: none + change_scope: none + keep_drop_targets: true +affordance: + enabled: true + branches_per_family: 2 + max_proposals: 8 + fallback: next_surviving_branch +trajectory: + variants_per_family: 2 + spatial: + enabled: true + operators: + - joint_residual + joint_offset_scale: 0.002 + via_count: 1 + dedup_tolerance: 0.0001 + timing: + enabled: false +visual: + enabled: false + profile_file: extensions/embodichain_tasks/configs/components/randomization_profiles/rgb_visual.yaml + profiles: [] + apply_per_rollout: true + balance: round_robin + restore_before_next_candidate: true +observation: + profiles: [] + capture_rgb: false + capture_video: false +scheduling: + policy: round_robin_fifo + candidate_budget: 4 + reference_family_budget: 1 +execution: + max_inflight: 1 + compatibility: strict +persistence: + sink: lerobot + output_dir: /tmp/embodichain-expansion diff --git a/tests/lab/expansion/test_episode_assembly.py b/tests/lab/expansion/test_episode_assembly.py index d2ff7d3f23..15e65eaf8a 100644 --- a/tests/lab/expansion/test_episode_assembly.py +++ b/tests/lab/expansion/test_episode_assembly.py @@ -44,6 +44,7 @@ def test_source_rejection_preserves_successful_peer(tmp_path, failed_row): assert episodes[failed_row] is None peer = episodes[1 - failed_row] assert peer is not None and peer.validation.accepted + assert peer.metadata["source_env_id"] == 1 - failed_row assert len(peer.actions) == 1 and len(peer.timestamps) == 2 record = json.loads((tmp_path / str(failed_row) / "attempt.json").read_text()) assert ( diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 4de3f2c108..48b17ab489 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -279,7 +279,7 @@ def test_preview_cli_dispatch_does_not_collect(monkeypatch, recorded_job): "from_job", lambda *a, **kw: pytest.fail("preview must not collect"), ) - assert main(["preview", "--output", str(path), "--gpu", "2", "--open"]) == 0 + assert main(["preview", "--input", str(path), "--gpu", "2", "--open"]) == 0 assert ( called[0][0] == 1 and called[0][1]["gpu"] == 2 and called[0][1]["open_browser"] ) @@ -314,3 +314,74 @@ def test_viewer_html_is_in_package_data(tmp_path): command.run() packaged = Path(command.build_lib) / "embodichain/lab/expansion/_preview.html" assert packaged.read_bytes() == original.read_bytes() + + +def test_manifest_keeps_rejected_points_visible_in_coverage(recorded_job): + path, _, _ = recorded_job + root = path.parent + manifest = { + "records": [ + {"result": path.name, "confirmed": 1, "status": "confirmed"}, + {"result": "unqualified", "confirmed": 0, "status": "rejected"}, + ], + "coverage_complete": False, + } + (root / "preview-plan.json").write_text(json.dumps(manifest)) + data = load_preview([root]) + assert len(data.clips) == 1 + assert ( + PreviewState(data).snapshot()["coverage"]["records"][1]["status"] == "rejected" + ) + manifest["records"][1]["result"] = "../escape" + (root / "preview-plan.json").write_text(json.dumps(manifest)) + with pytest.raises(ValueError, match="escapes"): + load_preview([root]) + + +def test_job_preview_collects_then_opens_and_input_alias_stays_read_only( + monkeypatch, recorded_job +): + from embodichain.cli.expansion import main + import embodichain.lab.expansion._preview_job as job + import embodichain.lab.expansion._preview_server as server + import torch + + path, _, _ = recorded_job + calls = [] + monkeypatch.setattr( + job, + "plan_preview", + lambda *a, **kw: {"output": str(path), "records": [{}], "planned_attempts": 1}, + ) + + def collect(plan): + calls.append("collect") + return {**plan, "confirmed": 1, "coverage_complete": True} + + monkeypatch.setattr(job, "collect_preview", collect) + monkeypatch.setattr(torch.cuda, "device_count", lambda: 1) + monkeypatch.setattr( + server, + "serve_preview", + lambda data, **kw: calls.append(("serve", kw["open_browser"])), + ) + assert main(["preview", "--job", "job.yaml"]) == 0 + assert calls == ["collect", ("serve", True)] + calls.clear() + assert main(["preview", "--inpu", str(path)]) == 0 + assert calls == [("serve", False)] + + +def test_row_identity_without_motion_and_legacy_ambiguity(recorded_job): + from embodichain.lab.expansion._preview_data import annotations + from embodichain.lab.gym.envs._json import json_safe_copy + + path, _, episode = recorded_job + measured = load_preview([path]).clips[0].measured + metadata = json_safe_copy(episode.metadata, field_name="metadata") + metadata["expansion"] = [] + assert annotations(metadata, measured)["targets"].shape == (0, 4, 4) + metadata["source_env_id"] = 7 + result = annotations(metadata, measured) + np.testing.assert_allclose(result["targets"][0, :3, 3], [12, 20, 0]) + assert result["candidate_ids"] == ("31",) diff --git a/tests/lab/expansion/test_preview_job.py b/tests/lab/expansion/test_preview_job.py new file mode 100644 index 0000000000..fd995017b2 --- /dev/null +++ b/tests/lab/expansion/test_preview_job.py @@ -0,0 +1,202 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Boundary plans cover declared domains without resampling failed endpoints.""" + +from __future__ import annotations + +import json +from pathlib import Path +import numpy as np +import pytest +import yaml +from embodichain.lab.expansion._preview_job import ( + boundary_samples, + plan_preview, + collect_preview, +) + + +def test_endpoint_and_stratified_interior_sampling_is_deterministic(): + points, roles = boundary_samples(7, 5, 17) + assert roles[:3] == ["center", "lower", "upper"] + np.testing.assert_array_equal(points[1], np.zeros(7)) + np.testing.assert_array_equal(points[2], np.ones(7)) + assert np.all((points[3:] > 0) & (points[3:] < 1)) + for column in points[3:].T: + assert sorted((column * 5).astype(int)) == list(range(5)) + np.testing.assert_array_equal(points, boundary_samples(7, 5, 17)[0]) + assert boundary_samples(0, 5, 17)[0].shape == (1, 0) + + +def test_plan_keeps_job_bounds_and_produces_explicit_motion_draws(tmp_path): + from embodichain.lab.expansion.configured import load_expansion_job + + root = Path(__file__).resolve().parents[3] + original = root / "examples/expansion/engine/job.motion.yaml" + before = original.read_bytes() + plan = plan_preview(original, tmp_path / "preview", interior=1) + assert len(plan["records"]) == 4 + assert ( + plan["planned_attempts"] == 7 + ) # exact-zero center is one nominal, not two copies + low = yaml.safe_load((tmp_path / "preview" / plan["records"][1]["job"]).read_text()) + high = yaml.safe_load( + (tmp_path / "preview" / plan["records"][2]["job"]).read_text() + ) + assert low["mass_scale"]["cube"] == [0.98, 0.98] and high["mass_scale"]["cube"] == [ + 1.02, + 1.02, + ] + low_motion = yaml.safe_load(Path(low["motion_profile"]).read_text()) + assert set(low_motion["trajectory"]["spatial"]["joint_samples"].values()) == {-1.0} + assert low["collision_profile"] == load_expansion_job(original).collision_profile + assert original.read_bytes() == before + with pytest.raises(FileExistsError): + plan_preview(original, tmp_path / "preview", interior=1) + with pytest.raises(ValueError, match="Nothing executed"): + plan_preview(original, tmp_path / "too-large", max_episodes=1) + assert not (tmp_path / "too-large").exists() + + +def test_collection_retains_failed_and_unrun_points_without_retry( + monkeypatch, tmp_path +): + import embodichain.lab.expansion._preview_job as module + + (tmp_path / "configs").mkdir() + (tmp_path / "logs").mkdir() + for i in range(2): + (tmp_path / f"configs/{i}.yaml").write_text("max_wall_time_s: 10\n") + plan = dict( + output=str(tmp_path), + collection_budget_s=10, + recipes_per_point=1, + planned_attempts=2, + records=[ + dict( + semantic_id="test", + index=i, + role=role, + job=f"configs/{i}.yaml", + result=f"jobs/{i}", + confirmed=0, + attempts=0, + planned=1, + status="unrun", + ) + for i, role in enumerate(["lower", "upper"]) + ], + ) + monkeypatch.setattr(module, "load_expansion_job", lambda path: None) + monkeypatch.setattr( + module, "preflight_expansion_job", lambda cfg: {"semantic_id": "test"} + ) + calls = [] + + class FailedProcess: + returncode = 2 + + def __init__(self, args, **kw): + calls.append(args) + + def wait(self, timeout): + return 2 + + monkeypatch.setattr(module.subprocess, "Popen", FailedProcess) + result = collect_preview(plan) + assert len(calls) == 2 and all(r["status"] == "rejected" for r in result["records"]) + assert result["confirmed"] == 0 and not result["coverage_complete"] + assert ( + json.loads((tmp_path / "preview-plan.json").read_text())["records"][0]["role"] + == "lower" + ) + + +def test_source_change_stops_before_collecting(monkeypatch, tmp_path): + import embodichain.lab.expansion._preview_job as module + + (tmp_path / "configs").mkdir() + (tmp_path / "configs/job.yaml").write_text("max_wall_time_s: 10\n") + plan = { + "output": str(tmp_path), + "collection_budget_s": 10, + "records": [ + { + "index": 0, + "job": "configs/job.yaml", + "semantic_id": "pinned", + "status": "unrun", + } + ], + } + monkeypatch.setattr(module, "load_expansion_job", lambda path: None) + monkeypatch.setattr( + module, "preflight_expansion_job", lambda cfg: {"semantic_id": "changed"} + ) + monkeypatch.setattr( + module.subprocess, + "Popen", + lambda *a, **k: pytest.fail("changed source must not execute"), + ) + with pytest.raises(ValueError, match="changed after planning"): + collect_preview(plan) + assert ( + json.loads((tmp_path / "preview-plan.json").read_text())["records"][0]["status"] + == "source_changed" + ) + + +def test_reused_affordance_is_not_full_recipe_coverage(): + from embodichain.lab.expansion._preview_job import _exact_recipe + + sample = {"env_ids": [3, 7], "success": [True, True], "reused": [False, True]} + metadata = { + "expansion": [ + { + "env_id": 7, + "affordance_requested": 1, + "trajectory_requested": 1, + "trajectory_selected": 1, + } + ], + "program_segments": [ + { + "metadata": { + "runtime": { + "calls": [ + { + "plan_attempts": [ + { + "planner_diagnostics": { + "metadata": { + "affordance_sample": {"grasp": sample} + } + } + } + ] + } + ] + } + } + } + ], + } + assert not _exact_recipe(metadata) + sample["reused"][1] = False + assert _exact_recipe(metadata) + metadata["expansion"][0]["trajectory_selected"] = 0 + assert not _exact_recipe(metadata) diff --git a/tests/sim/motion/expansion/test_operators.py b/tests/sim/motion/expansion/test_operators.py index 814593d003..838c4d6e5f 100644 --- a/tests/sim/motion/expansion/test_operators.py +++ b/tests/sim/motion/expansion/test_operators.py @@ -616,3 +616,97 @@ def test_approach_cone_rejects_malformed_inputs() -> None: polar_angles=torch.tensor([0.0]), azimuth_angles=torch.tensor([0.0]), ) + + +@pytest.mark.parametrize("fraction, expected", [(-1.0, 0.05), (0.0, 0.25), (1.0, 0.45)]) +def test_explicit_residual_draws_reach_bounds_and_preserve_protected_rows( + fraction, expected +): + source = template() + result = joint_residual( + source, + joint_limits=torch.tensor([[-1.0, 1.0], [-1.0, 1.0]]), + normalized_scale=0.1, + generator=torch.Generator().manual_seed(17), + joint_samples={"arm": fraction}, + ) + assert float(result.positions[1, 0]) == pytest.approx(expected, abs=1e-6) + torch.testing.assert_close( + result.positions[[0, 2, 3, 4, 5]], source.positions[[0, 2, 3, 4, 5]] + ) + torch.testing.assert_close(result.positions[:, 1], source.positions[:, 1]) + torch.testing.assert_close(source.positions, template().positions) + + +def test_explicit_draws_do_not_bypass_joint_limits_and_require_named_controls(): + limits = torch.tensor([[-1.0, 1.0], [-1.0, 1.0]]) + with pytest.raises(ProposalRejected): + joint_residual( + template(), + joint_limits=limits, + normalized_scale=1.0, + generator=torch.Generator(), + joint_samples={"arm": 1.0}, + ) + for samples in ( + {"missing": 0.0}, + {"arm": float("nan")}, + {"arm": True}, + {"arm": 1.1}, + [], + ): + with pytest.raises(ValueError): + joint_residual( + template(), + joint_limits=limits, + normalized_scale=0.1, + generator=torch.Generator(), + joint_samples=samples, + ) + + +def test_explicit_via_knots_and_configured_payload_are_owned(): + from embodichain.lab.sim.motion.expansion.cfg import TrajectoryAugmentationCfg + + source = template() + source = replace( + source, + allowed_operators=("via_points",), + phases=( + replace(source.phases[0], allowed_operators=("via_points",)), + source.phases[1], + ), + ) + samples = {"arm": -1.0} + cfg = TrajectoryAugmentationCfg.from_mapping( + { + "factors": { + "spatial": { + "enabled": True, + "method": ["via_points"], + "joint_samples": samples, + "knot_samples": [1.0], + } + } + } + ) + samples["arm"] = 1.0 + result = via_points( + source, + joint_limits=torch.tensor([[-1.0, 1.0], [-1.0, 1.0]]), + via_count=1, + normalized_scale=0.1, + generator=torch.Generator(), + joint_samples=cfg.factors.spatial.joint_samples, + knot_samples=cfg.factors.spatial.knot_samples, + ) + assert float(result.positions[1, 0]) == pytest.approx(0.05, abs=1e-6) + + +def test_explicit_sample_mapping_rejects_nonfinite_config_values(): + from embodichain.lab.sim.motion.expansion.cfg import TrajectoryAugmentationCfg + + with pytest.raises(ValueError, match="finite"): + TrajectoryAugmentationCfg.from_mapping( + {"factors": {"spatial": {"joint_samples": {"arm": float("nan")}}}} + ) From 39201fe7901a0f15d310e8dd9fc92574d5dd8faf Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 09:35:35 +0000 Subject: [PATCH 11/49] fix(motion): preserve planning contexts and phase velocities --- embodichain/lab/expansion/_motion_batches.py | 5 +- .../lab/expansion/_planning_batches.py | 63 ++++++-- embodichain/lab/sim/motion/_phase_paths.py | 3 +- tests/lab/expansion/test_planning_batches.py | 149 ++++++++++++++++++ .../motion/test_motion_generator_batched.py | 55 +++++++ 5 files changed, 260 insertions(+), 15 deletions(-) create mode 100644 tests/lab/expansion/test_planning_batches.py diff --git a/embodichain/lab/expansion/_motion_batches.py b/embodichain/lab/expansion/_motion_batches.py index 5bb52f16f6..696756d6c2 100644 --- a/embodichain/lab/expansion/_motion_batches.py +++ b/embodichain/lab/expansion/_motion_batches.py @@ -75,10 +75,7 @@ def generate(generator, target_states, options=None, *, defer_recovery=False): tensors["rows"] = broker.torch.tensor( generator._env_ids, dtype=broker.torch.long ) - mode = ( - broker.torch.is_grad_enabled(), - broker.torch.is_inference_mode_enabled(), - ) + mode = broker._mode() key = ( "motion", id(generator.robot), diff --git a/embodichain/lab/expansion/_planning_batches.py b/embodichain/lab/expansion/_planning_batches.py index 8d7e587b51..552e434f2c 100644 --- a/embodichain/lab/expansion/_planning_batches.py +++ b/embodichain/lab/expansion/_planning_batches.py @@ -89,7 +89,10 @@ def __init__(self, robot, seed): "max_motion_group": 0, } previous = self._rng() - torch.manual_seed(seed) + torch.random.default_generator.manual_seed(seed) + for device in self.devices: + with torch.cuda.device(device): + torch.cuda.manual_seed(seed) np.random.seed(seed % 2**32) random.seed(seed) self.solve_rng = self._rng() @@ -109,6 +112,7 @@ def _rng(self): self.random.getstate(), self.torch.is_grad_enabled(), self.torch.is_inference_mode_enabled(), + self._autocast_state(), ) def _restore_rng(self, state): @@ -117,6 +121,51 @@ def _restore_rng(self, state): self.torch.cuda.set_rng_state(value, device) self.np.random.set_state(state[2]) self.random.setstate(state[3]) + self._restore_autocast(state[6]) + + def _autocast_state(self): + return ( + tuple( + ( + device, + self.torch.is_autocast_enabled(device), + self.torch.get_autocast_dtype(device), + ) + for device in ("cpu", "cuda") + ), + self.torch.is_autocast_cache_enabled(), + ) + + def _restore_autocast(self, state): + if state == self._autocast_state(): + return + # Greenlets share thread-local autocast state and its weight cache. + # A cache populated in another dtype must not cross a row boundary. + self.torch.clear_autocast_cache() + for device, enabled, dtype in state[0]: + self.torch.set_autocast_enabled(device, enabled) + self.torch.set_autocast_dtype(device, dtype) + self.torch.set_autocast_cache_enabled(state[1]) + + def _mode(self): + return ( + self.torch.is_grad_enabled(), + self.torch.is_inference_mode_enabled(), + self._autocast_state(), + ) + + @contextmanager + def _execution_mode(self, mode): + previous = self._autocast_state() + self._restore_autocast(mode[2]) + try: + with ( + self.torch.inference_mode(mode[1]), + self.torch.set_grad_enabled(mode[0]), + ): + yield + finally: + self._restore_autocast(previous) def _bind(self, solver, name): from greenlet import getcurrent @@ -161,10 +210,7 @@ def query(*args, **kwargs): return original(*args, **kwargs) if count is None: return original(*args, **kwargs) - mode = ( - self.torch.is_grad_enabled(), - self.torch.is_inference_mode_enabled(), - ) + mode = self._mode() key = ( id(solver), name, @@ -186,17 +232,14 @@ def query(*args, **kwargs): def _invoke(self, request, tensors): _, original, spec, values, _, _, mode = request if request[0][0] == "motion": - with ( - self.torch.inference_mode(mode[1]), - self.torch.set_grad_enabled(mode[0]), - ): + with self._execution_mode(mode): return original(tensors) arguments = dict(values.arguments) arguments.update(tensors) # BoundArguments retains variadic **kwargs and keyword-only arguments. bound = spec.bind_partial() bound.arguments.update(arguments) - with self.torch.inference_mode(mode[1]), self.torch.set_grad_enabled(mode[0]): + with self._execution_mode(mode): return original(*bound.args, **bound.kwargs) def _part(self, result, start, stop, total=None): diff --git a/embodichain/lab/sim/motion/_phase_paths.py b/embodichain/lab/sim/motion/_phase_paths.py index d675fcb710..0176d93024 100644 --- a/embodichain/lab/sim/motion/_phase_paths.py +++ b/embodichain/lab/sim/motion/_phase_paths.py @@ -99,7 +99,7 @@ def generate_phase_paths( points = p.rejected_candidate.positions candidates.append(points if i == 0 else points[:, 1:]) rejected = RejectedMotionCandidate(torch.cat(candidates, dim=1), dt, mask) - return PlanResult( + combined = PlanResult( success=success, positions=torch.where( success[:, None, None], positions, options.start_qpos[:, None] @@ -108,3 +108,4 @@ def generate_phase_paths( rejected_candidate=rejected, recovery=pieces[-1].recovery, ) + return generator._normalize_plan_result(combined, targets, options) diff --git a/tests/lab/expansion/test_planning_batches.py b/tests/lab/expansion/test_planning_batches.py new file mode 100644 index 0000000000..a1272f2fd0 --- /dev/null +++ b/tests/lab/expansion/test_planning_batches.py @@ -0,0 +1,149 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + + +"""Regression coverage for cooperative planning execution contexts.""" + +from __future__ import annotations + +from types import SimpleNamespace +import pytest +import torch +from embodichain.lab.expansion._planning_batches import batched_planning + + +@pytest.mark.parametrize("fail", [False, True]) +def test_autocast_rows_preserve_precision_and_restore_owner(fail): + class Solver: + def get_fk(self, qpos): + if fail and qpos[0, 0] < 0: + raise ValueError("solver failure") + return qpos @ torch.eye(2) + + solver = Solver() + robot = SimpleNamespace(device=torch.device("cpu"), _solvers={"arm": solver}) + inputs = torch.tensor([[1.1234, 2.3456]]) + + class Cursor: + def __init__(self, enabled, value): + self.enabled, self.value = enabled, value + + def next(self): + with torch.autocast("cpu", dtype=torch.bfloat16, enabled=self.enabled): + first = solver.get_fk(self.value) + # Resuming a row must restore the same context for subsequent calls. + second = solver.get_fk(self.value) + return first + second + + cursors = { + 0: Cursor(True, inputs), + 1: Cursor(False, inputs), + 2: Cursor(True, inputs), + } + expected = {row: cursor.next() for row, cursor in cursors.items()} + cpu_rng = torch.get_rng_state().clone() + with torch.autocast("cpu", enabled=False): + with batched_planning(robot, 7) as planner: + if fail: + cursors[1].value = -inputs + with pytest.raises(ValueError, match="solver failure"): + planner.gather(cursors) + else: + actual = planner.gather(cursors) + for row in actual: + torch.testing.assert_close( + actual[row], expected[row], rtol=0, atol=0 + ) + saved = actual[2].clone() + actual[0].zero_() + torch.testing.assert_close(actual[2], saved) + assert not torch.is_autocast_enabled("cpu") + assert not torch.is_autocast_enabled("cpu") + assert torch.equal(cpu_rng, torch.get_rng_state()) + assert "get_fk" not in solver.__dict__ + + +@pytest.mark.gpu +@pytest.mark.parametrize("robot_device", ["cpu", "cuda:0"]) +def test_planning_scope_leaves_external_rng_generators_unchanged(robot_device): + robot = SimpleNamespace(device=torch.device(robot_device), _solvers={}) + with torch.random.fork_rng(devices=list(range(torch.cuda.device_count()))): + torch.manual_seed(123) + cpu = torch.get_rng_state().clone() + cuda = [state.clone() for state in torch.cuda.get_rng_state_all()] + with batched_planning(robot, 7): + assert torch.equal(cpu, torch.get_rng_state()) + for before, after in zip(cuda, torch.cuda.get_rng_state_all()): + assert torch.equal(before, after) + assert torch.equal(cpu, torch.get_rng_state()) + for before, after in zip(cuda, torch.cuda.get_rng_state_all()): + assert torch.equal(before, after) + + +def test_full_motion_grouping_preserves_autocast(monkeypatch): + from embodichain.lab.sim.motion.motion_generator import ( + MotionGenerator, + MotionGenOptions, + ) + from embodichain.lab.sim.motion.planners.utils import PlanState, PlanResult + + robot = SimpleNamespace(device=torch.device("cpu"), _solvers={}) + + def plan(self, targets, options): + positions = (options.start_qpos @ torch.eye(2))[:, None] + return PlanResult( + success=torch.ones(len(positions), dtype=torch.bool), + positions=positions, + dt=torch.zeros(len(positions), 1), + ) + + monkeypatch.setattr(MotionGenerator, "_generate_once", plan) + + class Cursor: + def __init__(self, row, enabled): + self.enabled = enabled + self.generator = object.__new__(MotionGenerator) + self.generator.robot = robot + self.generator.planner = SimpleNamespace( + cfg=None, collision_world_info=None + ) + self.generator._env_ids = (row,) + + def next(self): + with torch.autocast("cpu", dtype=torch.bfloat16, enabled=self.enabled): + start = torch.tensor([[1.1234, 2.3456]]) + return self.generator.generate( + [PlanState.from_qpos(start)], + MotionGenOptions( + strategy="ik_interp", + interpolation_mode="fixed_grid", + sample_count=2, + interpolation_dt=0.1, + start_qpos=start, + ), + ) + + cursors = {0: Cursor(0, True), 1: Cursor(1, False), 2: Cursor(2, True)} + expected = {row: cursor.next() for row, cursor in cursors.items()} + with batched_planning(robot, 7) as planner: + actual = planner.gather(cursors) + for row in actual: + torch.testing.assert_close( + actual[row].positions, expected[row].positions, rtol=0, atol=0 + ) + saved = actual[2].positions.clone() + actual[0].positions.zero_() + torch.testing.assert_close(actual[2].positions, saved) diff --git a/tests/sim/motion/test_motion_generator_batched.py b/tests/sim/motion/test_motion_generator_batched.py index c4886a743d..e1bd0a66d1 100644 --- a/tests/sim/motion/test_motion_generator_batched.py +++ b/tests/sim/motion/test_motion_generator_batched.py @@ -2371,3 +2371,58 @@ def test_cartesian_timing_budget_exhaustion_returns_failed_safe_hold(monkeypatch ) assert success.tolist() == [False] assert torch.equal(positions, q[:, :1].repeat(1, 2, 1)) + + +@pytest.mark.parametrize("modes", [("joint",), ("joint", "cartesian")]) +def test_phase_paths_materialize_owned_velocity_and_hold_failed_rows( + modes, monkeypatch +): + generator = _mock_generator() + start = torch.zeros(BATCH_SIZE, CONTROLLED_DOF) + states = [PlanState.from_xpos(torch.eye(4).repeat(BATCH_SIZE, 1, 1)) for _ in modes] + pieces = [] + + def segment(_self, targets, options=None, *, defer_recovery=False): + positions = ( + options.start_qpos[:, None] + + torch.arange(options.sample_count, dtype=torch.float32)[ + None, :, None + ].expand(BATCH_SIZE, -1, CONTROLLED_DOF) + * 0.25 + ) + result = _timed_result( + positions, success=torch.tensor([True, False]), step_dt=0.25 + ) + pieces.append(result) + return result + + # Exercise the public composition and real normalization with deterministic + # segment outputs, independent of IK convergence or simulation resources. + original = MotionGenerator.generate + monkeypatch.setattr(MotionGenerator, "generate", segment) + result = original( + generator, + states, + MotionGenOptions( + strategy="ik_interp", + interpolation_mode="fixed_grid", + ik_seed_mode="sequential", + waypoint_modes=modes, + sample_count=5, + interpolation_dt=0.25, + start_qpos=start, + control_part="arm", + ), + ) + expected = torch.ones_like(result.positions) + expected[:, 0] = expected[:, -1] = 0 + expected[1] = 0 + torch.testing.assert_close(result.velocities, expected) + torch.testing.assert_close( + result.positions[1], torch.zeros_like(result.positions[1]) + ) + assert result.positions.shape[1] == 5 + assert result.dt.sum(dim=1).tolist() == [1.0, 1.0] + saved = result.positions.clone() + pieces[0].positions.fill_(99) + torch.testing.assert_close(result.positions, saved) From 85704e16a39402a29470935e22d311628964a198 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 11:53:16 +0000 Subject: [PATCH 12/49] fix(expansion): preview recorded mesh scenes and native runtime metadata --- .../expansion-engine/expansion-engine.md | 6 +- embodichain/lab/expansion/_preview_data.py | 98 ++++++++++++++---- embodichain/lab/expansion/_preview_render.py | 99 +++++++++++++++---- examples/expansion/engine/ghost-preview.md | 16 +-- tests/lab/expansion/test_preview.py | 31 +++++- 5 files changed, 202 insertions(+), 48 deletions(-) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 255bdcaa1e..b27024c8bd 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -96,8 +96,10 @@ process orchestration remain outside the replay core. `embodichain expansion preview --input` reads confirmed job outputs through `_preview_data.py`, then replays full measured states using `_preview_render.py` and a loopback-only `_preview_server.py`. Inputs retain their original evidence; no collection or -physics stepping occurs. The first version accepts one URDF robot and Cube rigid -objects with fixed layouts, and rejects unsupported geometry. Space filters group +physics stepping occurs. It accepts one URDF robot and recorded rigid visual +objects (including file Mesh/USD via native visual loading), with fixed layouts; +unsupported geometry is rejected. Constant static backgrounds remain single +instances. Space filters group input directories; missing motion annotations remain explicit. HTTP publishes a single immutable image/state snapshot; WebRTC is follow-up work. FK and episode budgets bound preload, controls are queued for the render owner, and native diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py index adf91221d0..06fda24abe 100644 --- a/embodichain/lab/expansion/_preview_data.py +++ b/embodichain/lab/expansion/_preview_data.py @@ -68,7 +68,8 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: branches, candidates, targets, phases = [], [], [], [] phase_safe = True for segment in metadata.get("program_segments", ()): - for call in segment.get("metadata", {}).get("runtime", {}).get("calls", ()): + runtime = segment.get("runtime", segment.get("metadata", {}).get("runtime", {})) + for call in runtime.get("calls", ()): for event in call.get("events", ()): if event.get("kind") == "trajectory_segment_entered": mask = event.get("env_mask") @@ -120,6 +121,8 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: sampling = sample.get("sampling") or {} overrides = sampling.get("branch_overrides") branch = overrides[row] if overrides else sampling.get("branch_override") + if branch is None and sampling.get("count") == 1: + branch = 0 branches.append("unrecorded" if branch is None else str(branch)) candidates.append(str(sample["candidate_ids"][row])) uid = ( @@ -159,6 +162,14 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: for r in records if r.get("trajectory_requested") is not None ] + if not variants: + variants = [ + str(r["operator"]) + for r in records + if r.get("operator") + in {"joint_residual", "via_points", "nullspace_residual"} + ] + variants = list(dict.fromkeys(variants)) return dict( affordance="/".join(branches) or "unrecorded", variant="/".join(variants) or "unrecorded", @@ -169,7 +180,53 @@ def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: ) -def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...]]]: +def _object_specs(cfg: dict[str, Any]) -> dict[str, dict[str, Any]]: + objects = {} + for obj in [*(cfg.get("rigid_object") or []), *(cfg.get("background") or [])]: + uid = obj.get("uid") + if not isinstance(uid, str) or not uid or uid in objects: + raise ValueError("Preview requires unique recorded rigid object IDs") + if obj.get("visuals") is not None or obj.get("visual_shape"): + raise ValueError( + "Preview does not yet support explicit rigid visual replacements" + ) + shape, source = obj.get("shape") or {}, obj.get("source") + if source: + if not isinstance(source, dict) or not source.get("file_path") or shape: + raise ValueError("Preview requires an unambiguous source object") + filename = source["file_path"] + elif shape.get("shape_type") == "Mesh": + filename = shape.get("fpath") + elif shape.get("shape_type") in { + "Cube", + "Sphere", + "Cylinder", + "Capsule", + "Cone", + }: + filename = None + else: + raise ValueError("Unsupported recorded rigid visual geometry") + if (source or shape.get("shape_type") == "Mesh") and ( + not filename or not Path(filename).expanduser().is_file() + ): + raise ValueError(f"Recorded object asset is unavailable: {filename}") + scale = obj.get("body_scale") + if scale is not None and ( + np.asarray(scale).shape != (3,) + or not np.isfinite(scale).all() + or np.any(np.asarray(scale) <= 0) + ): + raise ValueError("Invalid recorded object scale") + objects[uid] = { + key: obj[key] + for key in ("shape", "source", "body_scale", "body_type") + if key in obj + } + return objects + + +def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...] | None]]: cfg = job.get("resolved_deployment") if not isinstance(cfg, dict) or not isinstance(cfg.get("robot"), dict): raise ValueError( @@ -178,7 +235,6 @@ def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...]]]: unsupported = ( "articulation", "rigid_object_group", - "background", "cable_object", "fluid_object", "soft_object", @@ -187,7 +243,7 @@ def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...]]]: ) if any(cfg.get(k) for k in unsupported) or job.get("config", {}).get("scene_atlas"): raise ValueError( - "Preview currently supports a fixed layout, one URDF robot and Cube rigid objects only" + "Preview requires a fixed layout, one URDF robot and recorded rigid objects" ) robot = cfg["robot"] if robot.get("visuals") or robot.get("link_visuals"): @@ -195,23 +251,17 @@ def _scene(job: dict[str, Any]) -> tuple[dict, dict[str, tuple[float, ...]]]: if not np.allclose(robot.get("body_scale", [1, 1, 1]), [1, 1, 1]): raise ValueError("Scaled robot assets are not supported by this preview") boxes = {} - for obj in cfg.get("rigid_object", []): + for uid, obj in _object_specs(cfg).items(): shape = obj.get("shape") or {} - if ( - shape.get("shape_type") != "Cube" - or obj.get("source") - or obj.get("visuals") - or obj.get("visual_shape") - ): - raise ValueError( - "Preview requires Cube rigid geometry; no asset substitution is performed" - ) + if shape.get("shape_type") != "Cube": + boxes[uid] = None + continue size = np.asarray(shape["size"], float) * np.asarray( - obj.get("body_scale", [1, 1, 1]), float + obj.get("body_scale") or [1, 1, 1], float ) if size.shape != (3,) or not np.isfinite(size).all() or np.any(size <= 0): raise ValueError("Invalid recorded Cube dimensions") - boxes[obj["uid"]] = tuple(size) + boxes[uid] = tuple(size) return robot, boxes @@ -221,9 +271,10 @@ class PreviewData: reference: PreviewClip | None asset: Path eef_link: str - boxes: dict[str, tuple[float, ...]] + boxes: dict[str, tuple[float, ...] | None] ground_visible: bool = True coverage: dict[str, Any] | None = None + object_specs: dict[str, dict[str, Any]] | None = None @property def all_clips(self) -> list[PreviewClip]: @@ -272,6 +323,7 @@ def load_preview( asset = None boxes = None robot_spec = None + object_specs = None end = None ground = True seen = set() @@ -282,10 +334,16 @@ def load_preview( raise ValueError(f"Not an expansion job output: {path} (missing job.json)") job = json.loads(job_path.read_text()) robot, shapes = _scene(job) + recorded_specs = _object_specs(job["resolved_deployment"]) + if object_specs is not None and recorded_specs != object_specs: + raise ValueError( + "Result directories disagree about recorded object geometry" + ) + object_specs = recorded_specs spec = {k: robot.get(k) for k in ("uid", "control_parts", "solver_cfg")} if robot_spec is not None and (spec != robot_spec or shapes != boxes): raise ValueError( - "Result directories must share robot/control topology and Cube geometry" + "Result directories must share robot/control topology and object geometry" ) robot_spec = spec boxes = shapes @@ -371,7 +429,9 @@ def load_preview( else: clips.append(clip) clip.label = f"C-{len(clips):03d}" - return PreviewData(clips, reference_clip, asset, end, boxes, ground, coverage) + return PreviewData( + clips, reference_clip, asset, end, boxes, ground, coverage, object_specs + ) class PreviewState: diff --git a/embodichain/lab/expansion/_preview_render.py b/embodichain/lab/expansion/_preview_render.py index 4bf154de4a..4591772dee 100644 --- a/embodichain/lab/expansion/_preview_render.py +++ b/embodichain/lab/expansion/_preview_render.py @@ -80,6 +80,8 @@ def __init__( publisher: Any, names: list[str], center: np.ndarray, + models: dict[str, Any] | None = None, + geometry: dict[str, Any] | None = None, ) -> None: from dexsim import spawn from embodichain.lab.visualization.markers import ( @@ -95,6 +97,28 @@ def __init__( scene = sim.spawn_result self.step = sim.physics_step_index self.previous = None + self.models = models or {} + self.geometry = geometry or {} + self.backgrounds = { + uid + for uid, spec in (data.object_specs or {}).items() + if spec.get("body_type") in {"static", "kinematic"} + and all( + np.allclose( + c.measured.object_poses[uid], + data.clips[0].measured.object_poses[uid][0], + rtol=0, + atol=1e-7, + ) + for c in data.all_clips + ) + } + self.moving_objects = [uid for uid in data.boxes if uid not in self.backgrounds] + for uid in self.backgrounds: + self.models[uid].set_local_pose( + data.clips[0].measured.object_poses[uid][0:1] + ) + self.models[uid].set_visible(True) palette = [ (0.18, 0.58, 1), (0.15, 0.9, 0.5), @@ -141,13 +165,11 @@ def markers(name: str, shapes: dict) -> Any: markers( f"preview_objects_{i}", { - uid: MarkerPrototypeCfg( - shape="box", scale=size, color=(*color, 0.2) - ) - for uid, size in data.boxes.items() + uid: self._object_prototype(uid, color=(*color, 0.2)) + for uid in self.moving_objects }, ) - if data.boxes + if self.moving_objects else None ) self.objects.append(objects) @@ -156,10 +178,10 @@ def markers(name: str, shapes: dict) -> Any: ) robot.set_visibility(False) if objects: - p = np.array([c.measured.object_poses[uid][0] for uid in data.boxes]) - objects.visualize( - p[:, :3], p[:, 3:], marker_indices=np.arange(len(data.boxes)) + p = np.array( + [c.measured.object_poses[uid][0] for uid in self.moving_objects] ) + objects.visualize(p[:, :3], p[:, 3:], marker_indices=np.arange(len(p))) objects.set_visibility(False) self.selected = RobotMarkers( RobotMarkersCfg( @@ -177,17 +199,13 @@ def markers(name: str, shapes: dict) -> Any: markers( "selected_objects", { - uid: MarkerPrototypeCfg( - shape="box", - scale=size, - color=(0.9, 0.58, 0.2, 1), - scene_lighting=True, - unlit=False, + uid: self._object_prototype( + uid, color=(0.9, 0.58, 0.2, 1), scene_lighting=True, unlit=False ) - for uid, size in data.boxes.items() + for uid in self.moving_objects }, ) - if data.boxes + if self.moving_objects and not self.models else None ) self.paths = markers( @@ -244,6 +262,16 @@ def markers(name: str, shapes: dict) -> Any: self.camera.set_visual_overlay_enabled(True) publisher.publish(preload=True) + def _object_prototype(self, uid: str, **appearance: Any) -> Any: + from embodichain.lab.visualization.markers import MarkerPrototypeCfg + + if uid in self.geometry: + vertices, faces = self.geometry[uid] + return MarkerPrototypeCfg( + shape="mesh", vertices=vertices, faces=faces, **appearance + ) + return MarkerPrototypeCfg(shape="box", scale=self.data.boxes[uid], **appearance) + def draw(self, state: PreviewState) -> bytes: v = state.values visible = state.visible() @@ -298,20 +326,29 @@ def draw(self, state: PreviewState) -> bytes: initial = [ p[0, :3] for i in visible - for p in self.data.clips[i].measured.object_poses.values() + for uid, p in self.data.clips[i].measured.object_poses.items() + if uid not in self.backgrounds ] self.positions.visualize(np.asarray(initial).reshape(-1, 3)) self.previous = tuple(visible) self.selected.set_visibility(bool(visible)) if self.selected_objects: self.selected_objects.set_visibility(bool(visible)) + for uid, obj in self.models.items(): + if uid not in self.backgrounds: + obj.set_visible(bool(visible)) if visible: c = self.data.clips[v["selected"]] f = state.frame_at(c) self.selected.visualize_link_poses(c.links[f, self.selected_order][None]) + for uid in self.moving_objects: + if uid in self.models: + self.models[uid].set_local_pose( + c.measured.object_poses[uid][f : f + 1] + ) if self.selected_objects: p = np.array( - [c.measured.object_poses[uid][f] for uid in self.data.boxes] + [c.measured.object_poses[uid][f] for uid in self.moving_objects] ) self.selected_objects.visualize( p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) @@ -334,7 +371,7 @@ def draw(self, state: PreviewState) -> bytes: robot.visualize_link_poses(c.links[f, order][None]) if objects: p = np.array( - [c.measured.object_poses[uid][f] for uid in self.data.boxes] + [c.measured.object_poses[uid][f] for uid in self.moving_objects] ) objects.visualize( p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) @@ -366,6 +403,8 @@ def draw(self, state: PreviewState) -> bytes: "ghost_count": ghost_count, "path_segments": self.paths.count if v["paths"] else 0, "grasp_targets": self.targets.count if v["targets"] else 0, + "scene_objects": len(self.data.boxes), + "fixed_backgrounds": len(self.backgrounds), } return buffer.getvalue() @@ -400,10 +439,30 @@ def native_renderer(data: PreviewData, gpu: int = 0) -> Iterator[NativeRenderer] publisher = None try: sim.enable_physics(False) + models = {} + if data.object_specs is not None: + from embodichain.lab.sim.cfg import VisualObjectCfg + + for index, (uid, spec) in enumerate(data.object_specs.items()): + visual = { + key: value + for key, value in spec.items() + if key in {"shape", "source", "body_scale"} and value is not None + } + visual.update(uid=f"expansion_preview_asset_{index}", visible=False) + models[uid] = sim.add_visual_object(VisualObjectCfg.from_dict(visual)) sim.prepare() sim.set_ground_plane_visibility(data.ground_visible) + geometry = {} + for uid, obj in models.items(): + vertices = obj.get_vertices(env_ids=[0], scale=True)[0].cpu().numpy() + faces = obj.get_triangles(env_ids=[0])[0].cpu().numpy() + if not len(vertices) or not len(faces) or not np.isfinite(vertices).all(): + raise ValueError(f"Recorded object has no finite visual mesh: {uid}") + geometry[uid] = vertices, faces + data.boxes[uid] = tuple(np.ptp(vertices, axis=0)) publisher = MarkerFramePublisher(sim) - yield NativeRenderer(data, sim, publisher, names, center) + yield NativeRenderer(data, sim, publisher, names, center, models, geometry) finally: if publisher is not None: publisher.close() diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index e31f38505b..376d3ca9d8 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -114,8 +114,10 @@ embodichain expansion preview \ 独立布局子作业,再作为一个参数组加载。 `--reference` 可省略;指定时必须恰好含一个已确认参考 episode,且不能与候选重复。 -模型从 `job.json.resolved_deployment.robot` 的 URDF 路径恢复,场景方块尺寸从 -同一快照恢复,不加载原任务配置,也不重新实例化任务/规划器。原模型及引用的视觉 +模型从 `job.json.resolved_deployment.robot` 的 URDF 路径恢复,场景刚体几何从 +同一快照恢复。方块、球和文件 Mesh/USD 资产通过原生纯视觉对象加载,保留原生 +坐标轴转换与模型缩放;不会用方块替代网格。位置恒定的静态背景只显示一份。 +不加载原任务配置,也不重新实例化任务/规划器。原模型及引用的视觉 文件必须仍可读;若资产移动,使用 `--robot-asset /new/path/robot.urdf` 显式提供 匹配模型。入口检查完整关节名称集合和跨输入模型一致性,但旧结果没有完整视觉 资产包,不能仅凭关节名证明替换模型几何完全一致;调用者负责提供原模型。 @@ -220,10 +222,12 @@ CLI 不触发采集和安装包页面资源由生产模块的聚焦测试覆盖 `_preview_render.py` 负责,HTTP 服务与页面由 `_preview_server.py`、`_preview.html` 负责,CLI 由 `embodichain/cli/expansion.py` 分发。 -当前渲染明确支持单 URDF 机器人、单位机器人缩放和 Cube 刚体场景。其他 articulated -objects、软体、流体、线缆、mesh/source 物体、背景资产和 scene-atlas 输入会被拒绝; -不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,方块颜色和灯光是展示 -外观,不声称精确恢复采集时材质。新任务支持应扩展场景恢复契约并验证实测坐标。 +当前渲染支持单 URDF 机器人、单位机器人缩放,以及有完整实测位姿的刚体场景。 +文件 Mesh 和 USD 通过原生视觉资产加载,选中物体保留源模型外观,虚影复用实测几何。 +其他 articulated +objects、软体、流体、线缆、显式 visual replacement 和直接 scene-atlas 输入会被拒绝; +不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,虚影材质与灯光用于展示, +不声称精确恢复采集传感器的原始图像。新任务支持应扩展场景恢复契约并验证实测坐标。 HTTP JPEG 轮询不提供 WebRTC 的编码、拥塞控制、连接恢复或低延迟保证。 页面是单个服务的共享回放会话,多人操作会改变同一状态;尚未提供独立会话、 diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 48b17ab489..f5d450a0a6 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -193,10 +193,39 @@ def test_result_loader_rejects_incomplete_scene_and_budget(recorded_job, tmp_pat load_preview([path], reference=path) job["resolved_deployment"]["rigid_object"][0]["shape"]["shape_type"] = "Mesh" (path / "job.json").write_text(json.dumps(job)) - with pytest.raises(ValueError, match="Cube"): + with pytest.raises(ValueError, match="asset is unavailable"): load_preview([path]) +def test_result_loader_keeps_real_mesh_spec_and_native_operator_labels( + recorded_job, tmp_path +): + path, job, episode = recorded_job + mesh = tmp_path / "object.ply" + mesh.write_text( + "ply\nformat ascii 1.0\nelement vertex 3\nproperty float x\nproperty float y\nproperty float z\nelement face 1\nproperty list uchar int vertex_indices\nend_header\n0 0 0\n1 0 0\n0 1 0\n3 0 1 2\n" + ) + job["resolved_deployment"]["rigid_object"][0]["shape"] = { + "shape_type": "Mesh", + "fpath": str(mesh), + } + (path / "job.json").write_text(json.dumps(job)) + data = load_preview([path]) + assert data.boxes["box"] is None + assert data.object_specs["box"]["shape"]["fpath"] == str(mesh) + from embodichain.lab.expansion._preview_data import annotations + + result = annotations( + { + "source_env_id": 0, + "expansion": [{"env_id": 0, "operator": "joint_residual", "proposal": 3}], + }, + data.clips[0].measured, + ) + assert result["variant"] == "joint_residual" + assert result["affordance"] == "unrecorded" + + def test_filter_empty_intersection_and_phase_alignment(recorded_job): path, _, _ = recorded_job data = load_preview([path]) From 239a3d58d48cd8f8750fe9415b0d6261c3874a69 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 12:53:58 +0000 Subject: [PATCH 13/49] feat(expansion): compose native single-world workload collection --- .../expansion-engine/expansion-engine.md | 1 + .../topics/expansion-engine/workloads.md | 11 + docs/source/api_reference/public_api.rst | 22 + embodichain/lab/expansion/__init__.py | 4 + embodichain/lab/expansion/gym_workloads.py | 852 ++++++++++++++++++ embodichain/lab/expansion/host_extensions.py | 6 +- embodichain/lab/expansion/journal.py | 31 + tests/lab/expansion/test_journal.py | 15 + tests/lab/expansion/test_workloads_sim.py | 103 ++- 9 files changed, 1040 insertions(+), 5 deletions(-) create mode 100644 embodichain/lab/expansion/gym_workloads.py diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index b27024c8bd..71ff869d5b 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -11,6 +11,7 @@ algorithms stay in `sim.motion.expansion`; scene and workspace algorithms stay i | Canonical in-memory session, lifecycle limits and coverage port | `embodichain/lab/expansion/session.py`, `session_cfg.py`, `coverage.py` | | Shared scheduling, admission and commit ports | `embodichain/lab/expansion/engine.py` | | Rolling workload × B execution in one caller-owned World | `embodichain/lab/expansion/workloads.py` | +| Native workload World, source/evidence assembly and bounded export | `embodichain/lab/expansion/gym_workloads.py` | | Job assembly, stage recovery and inspect | `embodichain/lab/expansion/workflow.py`, `stages.py` | | Native World ownership and compatibility facade | `embodichain/lab/expansion/host.py` | | Task-owned render/source/transform/acceptance ports | `embodichain/lab/expansion/host_extensions.py` | diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 5c47c5d1a4..50e7c58c0d 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -22,6 +22,17 @@ difficult group does not silently borrow another group's B-row allocation. ## Source ports and native accounting +`run_gym_expansion_workloads` is the public native composition for Task Program +scene/plan workloads. `GymExpansionWorkload` supplies a pinned deployment, +independent collection budget, artifacts and row callbacks. The facade opens one +World, captures the original seeded nominal scene in row zero, and composes the +existing session, frame collector, episode assembler and confirmed artifact sink. +Different integration/grasp policies may share that World only when their +physical configuration, program and cadence agree. Physical/visual/prototype +operators remain on the cohort API; unsupported payloads fail explicitly. +Frozen groups export through one bounded writer thread without World access. +Fresh output is required; this facade does not resume interrupted collection. + `WorkloadSource.prepare` runs inside the selected-row `episode_prepare` reset callback. It must not step physics, alter an active peer or mutate World-wide appearance/resources. Incompatible topology or shared resources require a diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index 15ba57ac10..31ea4f6bfc 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1670,6 +1670,8 @@ and durable episode-boundary recovery. See the offline expansion example. WorkloadRowResult WorkloadSource WorkloadProgramExecutor + GymExpansionWorkload + run_gym_expansion_workloads export_expansion_episodes .. autosummary:: @@ -1852,6 +1854,26 @@ Stream confirmed numeric episodes and observation children through the existing export_expansion_lerobot +embodichain.lab.expansion.gym_workloads +-------------------------------------- + +The native workload facade owns one World containing W times B environments. +Task packages supply pinned source declarations and row-local scene/plan ports; +the facade retains native session admission, measured T+1 evidence, physical +acceptance, confirmed receipts and one bounded artifact export thread. +Integration policies may differ while physical topology and cadence must agree. + +.. currentmodule:: embodichain.lab.expansion.gym_workloads + +.. autosummary:: + + GymExpansionWorkload + run_gym_expansion_workloads + +.. autoclass:: GymExpansionWorkload + +.. autofunction:: run_gym_expansion_workloads + embodichain.lab.expansion.host ------------------------------ diff --git a/embodichain/lab/expansion/__init__.py b/embodichain/lab/expansion/__init__.py index fd6dd78f38..a954ea40c1 100644 --- a/embodichain/lab/expansion/__init__.py +++ b/embodichain/lab/expansion/__init__.py @@ -66,6 +66,8 @@ "WorkloadRowResult", "WorkloadSource", "WorkloadProgramExecutor", + "GymExpansionWorkload", + "run_gym_expansion_workloads", "export_expansion_episodes", "GymExpansionHostExtensions", "ExpansionRowContext", @@ -118,6 +120,8 @@ def __getattr__(name: str) -> object: "WorkloadRowResult": "workloads", "WorkloadSource": "workloads", "WorkloadProgramExecutor": "workloads", + "GymExpansionWorkload": "gym_workloads", + "run_gym_expansion_workloads": "gym_workloads", "export_expansion_episodes": "episode_export", "GymExpansionHostExtensions": "host_extensions", "ExpansionRowContext": "host_extensions", diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py new file mode 100644 index 0000000000..4109d677de --- /dev/null +++ b/embodichain/lab/expansion/gym_workloads.py @@ -0,0 +1,852 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Native single-World collection for independent Task Program workloads.""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from concurrent.futures import ThreadPoolExecutor +from copy import deepcopy +from dataclasses import asdict, dataclass, replace +from pathlib import Path +import json +import hashlib +import time +from typing import Any + +from embodichain.data_pipeline.recording.media import _atomic_json +from .configured import ExpansionRunCfg +from .host_extensions import ExpansionRowContext, GymExpansionHostExtensions +from .workloads import ( + ExpansionWorkloadCfg, + WorkloadAssignment, + WorkloadExecutionCfg, + WorkloadProgramExecutor, + WorkloadRowResult, +) + +__all__ = ["GymExpansionWorkload", "run_gym_expansion_workloads"] + + +@dataclass(frozen=True) +class GymExpansionWorkload: + """Task-owned declarations for one independently budgeted source group. + + Args: + workload_id: Unique logical source group, independent of its World row. + cfg: Deployment, output, evidence limits and original collection budget. + report: Pinned semantic/execution identities and runtime versions. + source_artifacts: Hashed configuration/source references for each episode. + extensions: Scene, recipe and plan callbacks; rendering and validation + belong to the common extensions passed to the collection function. + + Deployments may select different integration/grasp policies, but must share + exactly the same physical environment, robot, control cadence and program. + This facade supports native Task Programs with row-local scene/plan ports; + configured physical/visual/prototype operators use the cohort job API. + """ + + workload_id: str + cfg: ExpansionRunCfg + report: Mapping[str, object] + source_artifacts: Mapping[str, object] + extensions: GymExpansionHostExtensions = GymExpansionHostExtensions() + + +def _preview_snapshot(env: Any) -> dict[str, object]: + """Freeze actual resolved geometry, including finite JSON parameter encoding.""" + from enum import Enum + import math + + def encode(value: Any) -> Any: + if isinstance(value, Enum): + return encode(value.value) + if isinstance(value, Mapping): + return {str(key): encode(item) for key, item in value.items()} + if isinstance(value, (tuple, list)): + return [encode(item) for item in value] + if isinstance(value, float) and not math.isfinite(value): + if math.isnan(value): + raise ValueError("resolved preview configuration contains NaN") + return "+inf" if value > 0 else "-inf" + if value is None or isinstance(value, (bool, int, float, str)): + return value + if isinstance(value, Path): + return str(value) + if hasattr(value, "tolist"): + return encode(value.tolist()) + return str(value) + + return encode( + { + "robot": env.robot.cfg.to_dict(), + "rigid_object": [ + env.sim.get_rigid_object(uid).cfg.to_dict() + for uid in env.sim.get_rigid_object_uid_list() + ], + "ground_plane_visible": getattr(env.cfg, "ground_plane_visible", True), + } + ) + + +class _GymWorkloadSource: + """Compose existing native admission, frame assembly and persistence owners.""" + + def __init__(self, owner: Any, groups: Mapping[str, Any]) -> None: + from ._gym_frames import GymFrameCollector + + self.owner, self.groups, self.env = owner, groups, owner.env + self.collector = GymFrameCollector(owner._context, {}) + self.active: dict[int, dict[str, Any]] = {} + self.activation_snapshot = None + self.nominal = { + uid: self.env.sim.get_rigid_object(uid) + .get_local_pose(to_matrix=True)[0] + .detach() + .cpu() + .tolist() + for uid in self.env.sim.get_rigid_object_uid_list() + } + + def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: + from embodichain.lab.sim.scene import ( + SceneView, + SceneChangeSet, + apply_changes_batch, + ) + from .scene import apply_joint_scene_candidates + + stamp = time.monotonic() + self.activation_snapshot = None + ids = tuple(a.env_id for a in assignments) + view = SceneView(self.env.sim, env_ids=ids) + # Every candidate starts from the same seeded nominal reset. Original + # reset events may run, but cannot resample an unowned scene axis. + apply_changes_batch( + view, + {row: SceneChangeSet(self.nominal, tuple(self.nominal)) for row in ids}, + ) + candidates = {} + for assignment in assignments: + group = self.groups[assignment.workload_id] + if group["admitted_at"][0] is None: + group["admitted_at"][0] = time.monotonic() + ctx = group["host"]._context + request = ctx.journal.allocate_recipe(ctx.recipe(assignment.ordinal)) + request.recipe.validate_host(ctx.supported_operations, ctx.compatibility) + for operation in request.recipe.operations: + if operation.name not in { + "physical_parameters", + "joint_scene", + "motion", + }: + raise ValueError( + "rolling workloads only support row-local scene and motion operations" + ) + if operation.name == "physical_parameters" and any( + json.loads(operation.payload_json).values() + ): + raise ValueError( + "physical parameter changes require the cohort job API" + ) + ctx.requests[assignment.env_id] = request + if ctx.scene_source is not None: + candidates[assignment.env_id] = ctx.scene_source.candidate( + assignment.ordinal + ) + if candidates: + apply_joint_scene_candidates( + SceneView(self.env.sim, env_ids=tuple(candidates)), candidates + ) + self.owner.timings["prepare"] += time.monotonic() - stamp + + def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: + from embodichain.lab.sim.scene import capture_state + from embodichain.lab.sim.scene.physics import capture_physics_properties + from .contracts import ( + EpisodeCandidate, + SceneCase, + ValidationCheck, + ValidationResult, + ) + from .engine import PreparedEpisodeWorkItem + from ._gym_utils import _hash + + row = assignment.env_id + group = self.groups[assignment.workload_id] + host, engine = group["host"], group["engine"] + ctx = host._context + request = ctx.requests[row] + if self.activation_snapshot is None: + self.activation_snapshot = ( + capture_state(ctx.view), + capture_physics_properties(ctx.view), + ) + initial, physics = self.activation_snapshot + ctx.initial, ctx.initial_obs = initial, observation + ctx.physics_before = physics + collision = ctx.collision + if collision is not None: + collision.prepare(initial, env_ids=(row,)) + values = [asdict(entity) for entity in initial.batches[row]] + initial_id = _hash(values) + physical = json.loads( + next( + op.payload_json + for op in request.recipe.operations + if op.name == "physical_parameters" + ) + ) + parameters = { + "ordinal": assignment.ordinal, + "seed": ctx.cfg.seed, + "physics": physical, + "source": ctx.cfg.source, + "recipe_id": request.recipe.recipe_id, + } + for op in request.recipe.operations: + if op.name == "motion": + parameters["motion_recipe"] = json.loads(op.payload_json)[ + "recipe_index" + ] + elif op.name == "joint_scene": + parameters["scene_candidate_id"] = json.loads(op.payload_json)[ + "candidate_id" + ] + case = SceneCase( + _hash( + ( + ctx.compatibility.key, + physical, + parameters.get("scene_candidate_id"), + request.recipe.recipe_id, + ) + ), + initial_id, + ctx.report["semantic_id"], + ctx.program.program_id, + self.env.robot.uid, + ) + session = group["session"] + session.register_case(case, ctx.limits, joint_names=ctx.names) + identity, _ = session.propose( + case.scene_case_id, + initial_id, + source_id=ctx.program.program_id, + source_revision=ctx.report["recipe_revision"], + template_id=request.recipe.recipe_id, + operator_id="episode", + attempt_id=request.attempt_id, + ) + episode_id, commit_id = session.episode_ids(identity) + record = ctx.journal.update( + request, + status="prepared", + recipe=parameters, + case=asdict(case), + identity=asdict(identity), + episode_id=episode_id, + commit_id=commit_id, + joint_names=ctx.names, + initial_state=values, + ) + ctx.prepared[row] = identity, episode_id, commit_id, request.directory, record + valid = collision is None or collision.initial[row] + ctx.preparation_checks[row] = ValidationResult( + ( + ValidationCheck("preparation.source_configuration", "passed"), + ValidationCheck( + "preparation.initial_state", "passed" if valid else "failed" + ), + ValidationCheck( + "preparation.settling_steps", + "passed", + metrics={"steps": ctx.cfg.settling_steps}, + ), + ) + ) + item = PreparedEpisodeWorkItem( + EpisodeCandidate(identity, json.dumps(request.recipe.to_dict())), + ctx.compatibility.key, + row, + ) + native = engine.admit_row(item) + if native is None: + ctx.journal.update(request, status="initial_rejected") + return None + factory = None + if ctx.extensions.plan_transform_factory is not None: + factory = ctx.extensions.plan_transform_factory( + self.env, + ExpansionRowContext( + row, + identity, + assignment.ordinal, + request.attempt_id, + request.directory, + case, + request.recipe, + ), + ) + if factory is None: + raise ValueError("plan_transform_factory returned no factory") + adapter = group["adapter"].for_env_ids((row,)) + bridge = adapter.create_bridge( + ctx.program, plan_transform_factory=factory, isolate_policy_sessions=True + ) + # The frame owner is shared and observes all active rows once per step. + self.owner._context.initial, self.owner._context.initial_obs = ( + initial, + observation, + ) + self.collector.add({row: ctx.prepared[row]}) + self.active[row] = { + "group": group, + "native": native, + "adapter": adapter, + "factory": factory, + "physics_before": ctx.physics_before, + } + return bridge + + def started(self, assignment: WorkloadAssignment, world_control_step: int) -> None: + row = assignment.env_id + state = self.active[row] + ctx = state["group"]["host"]._context + state["group"]["engine"].mark_row_started(state["native"]) + ctx.prepared[row][4]["world_control_start"] = world_control_step + ctx.journal.update( + ctx.requests[row], status="running", world_control_start=world_control_step + ) + + def observe( + self, + assignments: tuple[WorkloadAssignment, ...], + action: Any, + observation: object, + ) -> Sequence[int]: + ids = tuple(a.env_id for a in assignments) + self.activation_snapshot = None + for name in {a.workload_id for a in assignments}: + self.groups[name]["host"]._context.journal.checkpoint() + self.collector.observe(ids, action, observation) + checks = self.owner.collision + return tuple( + row + for row in ids + if checks is not None + and row in checks.results + and checks.results[row].status != "passed" + ) + + def complete(self, result: WorkloadRowResult) -> Any: + from embodichain.lab.sim.scene.physics import capture_physics_properties + from ._gym_episode import GymEpisodeAssembler + + row = result.assignment.env_id + state = self.active.pop(row, None) + if state is None: + return None + group = state["group"] + ctx = group["host"]._context + outcome = result.program + factory = state["factory"] + if factory is not None: + records = tuple(factory.records) + ctx.prepared[row][4]["expansion"] = [r.to_metadata() for r in records] + portable = [] + ctx.source_artifacts = { + key: value + for key, value in ctx.source_artifacts.items() + if not key.startswith(f"plan_{row}_") + } + for index, record in enumerate(records): + trace = record.to_metadata() + if "plan_artifact" in trace: + key = f"plan_{row}_{index}" + ctx.source_artifacts[key] = trace.pop("plan_artifact") + trace["plan_artifact_key"] = key + portable.append(trace) + outcome = replace(outcome, expansion_records=(tuple(portable),)) + if ( + ctx.extensions.require_plan_transform + and outcome.accepted[0] + and not records + ): + outcome = replace( + outcome, + accepted=(False,), + reasons=("requested_operator_not_applied",), + ) + ctx.physics_before = state["physics_before"] + ctx.prepared[row][4].update( + world_control_start=result.world_control_start, + world_control_end=result.world_control_end, + ) + try: + episode = GymEpisodeAssembler(ctx).assemble( + {row: ctx.prepared[row]}, + self.collector, + {}, + outcome, + capture_physics_properties(ctx.view), + )[row] + if episode is not None: + episode = replace( + episode, + metadata={ + **episode.metadata, + "execution": { + **self.execution, + "workload_id": result.assignment.workload_id, + "world_control_start": result.world_control_start, + "world_control_end": result.world_control_end, + }, + }, + ) + return group["engine"].complete_row(state["native"], episode) + finally: + state["adapter"].close() + self.collector.discard(row) + + def close(self) -> None: + for state in self.active.values(): + state["adapter"].close() + self.active.clear() + + +def run_gym_expansion_workloads( + workloads: Sequence[GymExpansionWorkload], + execution: WorkloadExecutionCfg, + *, + extensions: GymExpansionHostExtensions | None = None, + output_dir: str | Path, +) -> Mapping[str, object]: + """Collect and export independent groups in one process and one owned World. + + The sole collector uses exactly ``workload_count * batch_size`` physical + environments. It captures the seeded nominal scene in this same World; + preparation never creates a reference World. Original per-group quotas, + attempts, measured acceptance and confirmed receipt accounting are retained. + One bounded writer thread exports frozen groups while other groups collect. + Writers receive only artifact paths and never access the live World. + + Args: + workloads: Nonempty unique source groups, each owning a fresh output. + execution: W, B, planning and original step/settling budgets. + extensions: Common collection renderer and measured validator. Per-group + scene/recipe/plan callbacks belong to each workload's extensions. + output_dir: Fresh root for execution/reference/progress diagnostics. + + Returns: + Owned per-workload results and actual process/World/planning evidence. + Partial quotas remain explicit even when qualified artifacts were saved. + """ + from .host import GymExpansionHost + from ._gym_recipe import GymRecipeBuilder + from ._gym_utils import _hash + from .engine import ExpansionEngine, ExpansionJobCfg + from .journal import ExpansionJournal + from .session import ExpansionSession + from .session_cfg import ExpansionSessionCfg + from .persistence import ArtifactEpisodeSink, load_expansion_episode + from .workflow import _RecordedSink + from .episode_export import export_expansion_episodes + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import REGISTERED_ENVS + from embodichain.utils.utility import load_config + from embodichain.lab.gym.envs._json import json_safe_copy + + if not workloads or len({w.workload_id for w in workloads}) != len(workloads): + raise ValueError("workloads must be nonempty with unique IDs") + execution.__post_init__() + if execution.workload_count > len(workloads): + raise ValueError("workload_count exceeds available groups") + common = extensions or GymExpansionHostExtensions() + if ( + common.scene_source_factory + or common.recipe_transform + or common.plan_transform_factory + ): + raise ValueError( + "common extensions may only select rendering and measured validation" + ) + root = Path(output_dir) + root.mkdir(parents=True, exist_ok=True) + configs = [] + for workload in workloads: + cfg = workload.cfg + cfg.__post_init__() + for field, digest in workload.report["input_files"].items(): + value = getattr(cfg, field, None) + if ( + value is None + or hashlib.sha256(Path(value).read_bytes()).hexdigest() != digest + ): + raise ValueError(f"workload input {field} differs from preflight") + if any( + getattr(cfg, field) != getattr(workloads[0].cfg, field) + for field in ( + "capture_media", + "episode_byte_budget", + "media_buffer_bytes", + ) + ): + raise ValueError("workloads must share media and evidence buffer limits") + if not workload.workload_id or not isinstance(workload.workload_id, str): + raise ValueError("workload IDs must be nonempty text") + if ( + any( + getattr(cfg, field) + for field in ( + "source_profile", + "collision_profile", + "prototype_validation_profile", + "motion_profile", + "scene_atlas", + "visual_profile", + "render_profiles", + "mass_scale", + "friction", + "center_of_mass", + "joint_stiffness_scale", + "joint_damping_scale", + ) + ) + or cfg.source != "task_program" + ): + raise ValueError( + "configured physical/visual/prototype operators require the cohort job API" + ) + if (cfg.seed, cfg.max_steps, cfg.settling_steps) != ( + execution.seed, + execution.max_steps, + execution.settling_steps, + ): + raise ValueError( + "workload and execution seeds/step/settling budgets must match" + ) + if ( + workload.extensions.validator_factory + or workload.extensions.collection_renderer + ): + raise ValueError("rendering and validation must use common extensions") + raw = load_config(cfg.deployment) + configs.append( + ( + raw, + config_to_cfg( + raw, + source_path=Path(cfg.deployment), + task_program_path_override=cfg.program, + ), + ) + ) + first = configs[0][1] + + def physical_key(cfg: Any) -> str: + return _hash( + { + name: ( + getattr(cfg, name).to_dict() + if hasattr(getattr(cfg, name), "to_dict") + else getattr(cfg, name) + ) + for name in ( + "robot", + "sim_cfg", + "rigid_object", + "background", + "target_control_frequency", + "sim_steps_per_control", + "events", + "sensor", + ) + if hasattr(cfg, name) + } + ) + + if any(physical_key(cfg) != physical_key(first) for _, cfg in configs[1:]): + raise ValueError( + "workloads must share physical environment, robot, sensors and cadence" + ) + + owner = source = None + groups: dict[str, Any] = {} + adapters: dict[int, Any] = {} + futures: dict[str, Any] = {} + started = time.monotonic() + writer = ThreadPoolExecutor(max_workers=1, thread_name_prefix="expansion-export") + try: + cfg = ExpansionRunCfg( + **{**workloads[0].cfg.to_dict(), "batch_size": execution.num_envs} + ) + owner = GymExpansionHost( + cfg, + workloads[0].report, + root, + ExpansionJournal(root), + workloads[0].source_artifacts, + extensions=common, + ) + env = owner.env + adapters[ + id(REGISTERED_ENVS[configs[0][0]["id"]].task_program_adapter_factory) + ] = env.task_program_adapter + # Sampling only row zero retains the original B=1 seeded reference + # regardless of the collection capacity. All rows use that same scene. + env.reset(seed=execution.seed, options={"save_data": False, "reset_ids": [0]}) + snapshot = _preview_snapshot(env) + nominal = { + uid: env.sim.get_rigid_object(uid) + .get_local_pose()[0] + .detach() + .cpu() + .tolist() + for uid in env.sim.get_rigid_object_uid_list() + } + _atomic_json( + root / "reference-scene.json", + {"seed": execution.seed, "poses_xyzw": nominal}, + ) + for workload, (raw, environment_cfg) in zip(workloads, configs, strict=True): + path = Path(workload.cfg.output_dir) + path.mkdir(parents=True, exist_ok=False) + cfg = ExpansionRunCfg( + **{**workload.cfg.to_dict(), "batch_size": execution.num_envs} + ) + report = { + **deepcopy(dict(workload.report)), + "resolved_deployment": snapshot, + } + journal = ExpansionJournal(path) + journal.open_run(report, cfg.to_dict(), resume=False) + _atomic_json(path / "preflight.json", report) + ctx = replace( + owner._context, + cfg=cfg, + report=report, + root=path, + journal=journal, + source_artifacts=deepcopy(dict(workload.source_artifacts)), + environment_cfg=environment_cfg, + requests={}, + prepared={}, + preparation_checks={}, + services={}, + bridges={}, + extensions=workload.extensions, + scene_source=None, + ) + if workload.extensions.scene_source_factory is not None: + ctx.scene_source = workload.extensions.scene_source_factory(env) + builder = GymRecipeBuilder(ctx) + transform = workload.extensions.recipe_transform + ctx.recipe = lambda ordinal, builder=builder, transform=transform: ( + builder.recipe(ordinal) + if transform is None + else transform(builder.recipe(ordinal)) + ) + # Non-owning facade delegates existing admission/acceptance methods; + # only owner above opens/closes the shared environment. + host = GymExpansionHost.__new__(GymExpansionHost) + host._context = ctx + factory = REGISTERED_ENVS[raw["id"]].task_program_adapter_factory + adapter = adapters.get(id(factory)) + if adapter is None: + adapter = factory.create_adapter(env) + adapters[id(factory)] = adapter + ctx.program = adapter.compile(environment_cfg.task_program) + if ( + workload.extensions.plan_transform_factory is not None + and adapter.configured_nominal_sources + ): + raise ValueError( + "a workload transform cannot replace configured nominal sources" + ) + if ( + groups + and ctx.program.program_id + != next(iter(groups.values()))["host"]._context.program.program_id + ): + raise ValueError("workloads must share the same Task Program") + admitted_at = [None] + + def admission_clock(admitted_at=admitted_at): + return ( + 0.0 if admitted_at[0] is None else time.monotonic() - admitted_at[0] + ) + + session = ExpansionSession( + ExpansionSessionCfg.from_mapping( + { + "collection": { + "target_committed_episodes": cfg.target_episodes, + "max_rollout_attempts": cfg.max_attempts, + "max_proposals": cfg.max_attempts, + "max_wall_time_s": cfg.max_wall_time_s, + }, + "execution": { + "ready_high_watermark": execution.num_envs, + "ready_low_watermark": 0, + }, + "persistence": { + "pending_episode_limit": execution.num_envs, + "pending_max_bytes": cfg.episode_byte_budget + * execution.num_envs, + }, + "validation": {"require_path_collision": True}, + } + ), + episode_namespace=journal.job_instance_id, + clock=admission_clock, + ) + sink = ArtifactEpisodeSink(path) + engine = ExpansionEngine( + ExpansionJobCfg( + batch_size=execution.num_envs, + candidate_budget=execution.num_envs, + episode_byte_budget=cfg.episode_byte_budget, + ), + session=session, + host=host, + sink=_RecordedSink(sink, journal), + ) + groups[workload.workload_id] = { + "host": host, + "session": session, + "sink": sink, + "engine": engine, + "adapter": adapter, + "admitted_at": admitted_at, + } + journal.stage("collection", "running") + source = _GymWorkloadSource(owner, groups) + specs = tuple( + ExpansionWorkloadCfg( + workload_id=w.workload_id, + target_episodes=w.cfg.target_episodes, + max_attempts=w.cfg.max_attempts, + max_wall_time_s=w.cfg.max_wall_time_s, + ) + for w in workloads + ) + + def export(name: str) -> dict[str, Any]: + group = groups[name] + journal = group["host"]._context.journal + stamp = time.monotonic() + journal.stage("export_lerobot", "running") + try: + exported = export_expansion_episodes(journal.root) + journal.stage("export_lerobot", "complete") + return {"lerobot": exported, "export_wall_s": time.monotonic() - stamp} + except Exception as error: + journal.stage("export_lerobot", "failed", error=str(error)) + raise + + def done(name: str, counts: Mapping[str, object]) -> None: + group = groups[name] + journal = group["host"]._context.journal + complete = counts["committed"] == group["host"].cfg.target_episodes + journal.stage("collection", "complete" if complete else "budget_exhausted") + journal.checkpoint(force=True) + futures[name] = writer.submit(export, name) + _atomic_json( + root / "workload-progress.json", + { + key: dict(value["session"].snapshot()["counts"]) + for key, value in groups.items() + }, + ) + + executor = WorkloadProgramExecutor( + env, specs, source, execution, on_workload_done=done + ) + source.execution = { + "mode": "single_process_single_world", + "workload_count": execution.workload_count, + "batch_size": execution.batch_size, + "num_envs": execution.num_envs, + "world": dict(executor.world_info), + } + _atomic_json(root / "execution.json", source.execution) + result = dict(executor.run()) + collection_wall = time.monotonic() - started + source.close() + for adapter in adapters.values(): + adapter.close() + owner.close() + owner = None + results = {} + for name, group in groups.items(): + exported = futures[name].result() + readback = [] + paths = { + item["episode_id"]: str( + Path(exported["lerobot"]["directory"]) / item["dataset_path"] + ) + for item in exported["lerobot"]["datasets"] + } + for receipt in group["sink"].inspect(): + episode = load_expansion_episode(receipt.storage_id) + readback.append( + { + "episode_id": episode.episode_id, + "steps": len(episode.actions), + "expansion": json_safe_copy( + episode.metadata.get("expansion", ()), + field_name="expansion readback", + ), + "lerobot": paths[episode.episode_id], + } + ) + counts = result["counts"][name] + results[name] = { + "complete": counts["committed"] == group["host"].cfg.target_episodes, + "target_episodes": group["host"].cfg.target_episodes, + "committed_episodes": counts["committed"], + "attempts": counts["attempts"], + "readback": readback, + "directory": str(group["host"].root), + **exported, + } + _atomic_json(group["host"].root / "adapter-readback.json", readback) + result.update( + workloads=results, + collection_wall_s=collection_wall, + wall_s=time.monotonic() - started, + ) + _atomic_json(root / "workload-execution.json", result) + return result + except BaseException as error: + for name, group in groups.items(): + if name not in futures: + group["host"]._context.journal.stage( + "collection", "failed", error=str(error) + ) + raise + finally: + writer.shutdown(wait=True, cancel_futures=True) + if source is not None: + source.close() + for adapter in adapters.values(): + adapter.close() + for group in groups.values(): + group["host"]._context.journal.checkpoint(force=True, state="finished") + if owner is not None: + owner.close() diff --git a/embodichain/lab/expansion/host_extensions.py b/embodichain/lab/expansion/host_extensions.py index 5f4e54a0c4..c7acc00d60 100644 --- a/embodichain/lab/expansion/host_extensions.py +++ b/embodichain/lab/expansion/host_extensions.py @@ -39,8 +39,10 @@ class ExpansionValidator(Protocol): terminal: Mapping[int, ValidationResult] results: Mapping[int, Any] - def prepare(self, snapshot: Any = None) -> None: - """Reset measured evidence after the host has settled its cohort.""" + def prepare( + self, snapshot: Any = None, *, env_ids: tuple[int, ...] | None = None + ) -> None: + """Reset evidence after settling; rolling callers select independent rows.""" ... def sample(self, ids: tuple[int, ...], action: Any, snapshot: Any = None) -> None: diff --git a/embodichain/lab/expansion/journal.py b/embodichain/lab/expansion/journal.py index 6573986161..3e717c013f 100644 --- a/embodichain/lab/expansion/journal.py +++ b/embodichain/lab/expansion/journal.py @@ -190,6 +190,37 @@ def update(self, attempt: RecipeAttempt | Path, **values: object) -> dict: _atomic_json(path, record) return record + def allocate_recipe(self, recipe: ExpansionRecipe) -> RecipeAttempt: + """Allocate one fresh rolling attempt while independent peers are active. + + The single writer supplies a unique, monotonically increasing ordinal. + This port does not resume interrupted attempts or change collection + budgets; native workload admission remains responsible for those limits. + """ + if self.run_id is None or self.operation != "all": + raise RuntimeError("rolling allocation requires an open collection run") + records = self.attempts() + if records and recipe.context.ordinal <= max(r["ordinal"] for r in records): + raise ValueError("rolling recipe ordinals must increase") + sequence = len(records) + directory = self.root / "attempts" / f"{sequence:08d}" + if directory.exists(): + raise FileExistsError("attempt sequence already exists") + _atomic_json( + directory / "attempt.json", + { + "sequence": sequence, + "ordinal": recipe.context.ordinal, + "recipe_id": recipe.recipe_id, + "recipe_spec": recipe.to_dict(), + "attempt_id": 0, + "run_id": self.run_id, + "status": "proposed", + "steps": 0, + }, + ) + return RecipeAttempt(recipe, 0, sequence, directory) + def reconcile(self, sink: object) -> None: """Repair frozen writes before admitting any physical retry.""" confirmed = {r.commit_id: r for r in sink.inspect()} diff --git a/tests/lab/expansion/test_journal.py b/tests/lab/expansion/test_journal.py index e50bd796b4..d2d67f3e91 100644 --- a/tests/lab/expansion/test_journal.py +++ b/tests/lab/expansion/test_journal.py @@ -91,6 +91,21 @@ def test_interrupted_recipe_retries_with_new_attempt_after_capacity_change(tmp_p next_run.checkpoint(force=True, state="closed") +def test_rolling_allocation_preserves_live_peers_and_ordinal_identity(tmp_path): + ledger = ExpansionJournal(tmp_path) + ledger.open_run( + {"job_id": "a", "semantic_id": "a", "execution_id": "r"}, {}, resume=False + ) + first = ledger.allocate_recipe(recipe(0)) + ledger.update(first, status="running") + second = ledger.allocate_recipe(recipe(1)) + assert [r["status"] for r in ledger.attempts()] == ["running", "proposed"] + assert (second.sequence, second.recipe.context.ordinal) == (1, 1) + with pytest.raises(ValueError, match="ordinals"): + ledger.allocate_recipe(recipe(1)) + ledger.checkpoint(force=True, state="finished") + + def test_changed_semantics_cannot_reuse_job(tmp_path): ledger = ExpansionJournal(tmp_path) ledger.open_run( diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index 516f540eb1..d631ae8d8a 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -347,10 +347,105 @@ def complete(self, result): SimulationManager.flush_cleanup_queue() +def _facade_probe(output: str) -> None: + import hashlib + import json + import torch + import yaml + from embodichain.lab.expansion import ( + ArtifactEpisodeSink, + ExpansionRunCfg, + GymExpansionHostExtensions, + GymExpansionWorkload, + WorkloadExecutionCfg, + run_gym_expansion_workloads, + load_expansion_episode, + ) + from embodichain.lab.expansion.collision import _MeasuredCollision + from embodichain.lab.gym.utils.registration import ( + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.sim import SimulationManager + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + task = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place" + ) + deployment = task / "task.ur5.yaml" + path = Path(output) + path.mkdir(exist_ok=True) + program = yaml.safe_load((task / "task_program/program.yaml").read_text()) + program["program"]["repeat"]["count"] = 1 + override = path / "program.yaml" + override.write_text(yaml.safe_dump(program)) + digest = hashlib.sha256(deployment.read_bytes()).hexdigest() + discover_task_packages() + execute_init_hooks() + workloads = [] + for name, target in (("pair", 2), ("queued", 1)): + cfg = ExpansionRunCfg( + deployment=str(deployment), + program=str(override), + output_dir=str(path / name), + target_episodes=target, + max_attempts=4, + max_steps=2500, + max_wall_time_s=240, + settling_steps=5, + ) + report = { + "job_id": name, + "semantic_id": name, + "execution_id": name, + "recipe_revision": name, + "input_files": {"deployment": digest}, + "runtime_versions": {}, + } + workloads.append(GymExpansionWorkload(name, cfg, report, {})) + result = run_gym_expansion_workloads( + workloads, + WorkloadExecutionCfg( + workload_count=1, batch_size=2, max_steps=2500, settling_steps=5 + ), + extensions=GymExpansionHostExtensions( + validator_factory=lambda env, output: _MeasuredCollision( + env, + str( + root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml" + ), + output, + ) + ), + output_dir=path / "execution", + ) + assert result["complete"], result + assert result["num_envs"] == 2 and result["world"]["world_count"] == 1 + assert not SimulationManager._instances + for name, expected in (("pair", 2), ("queued", 1)): + group = result["workloads"][name] + assert group["complete"] and group["committed_episodes"] == expected + receipts = ArtifactEpisodeSink(path / name).inspect() + assert len(receipts) == len(group["lerobot"]["datasets"]) == expected + for receipt in receipts: + episode = load_expansion_episode(receipt.storage_id) + assert episode.validation.accepted + assert len(episode.timestamps) == len(episode.actions) + 1 + execution = episode.metadata["execution"] + assert execution["world_control_end"] - execution[ + "world_control_start" + ] + 1 == len(episode.actions) + assert execution["world"] == result["world"] + (path / "facade-result.json").write_text(json.dumps(result, indent=2)) + + @pytest.mark.requires_sim -def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path): +@pytest.mark.parametrize("mode", ["executor", "facade"]) +def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path, mode): result = subprocess.run( - [sys.executable, __file__, str(tmp_path)], + [sys.executable, __file__, str(tmp_path), mode], cwd=Path(__file__).resolve().parents[3], env={**os.environ, "SDL_VIDEODRIVER": "offscreen", "OMP_NUM_THREADS": "1"}, capture_output=True, @@ -361,4 +456,6 @@ def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path): if __name__ == "__main__": - _probe(sys.argv[1]) + (_facade_probe if len(sys.argv) > 2 and sys.argv[2] == "facade" else _probe)( + sys.argv[1] + ) From 78dc36c41fa804d9de17761522499eecd2c8ad0b Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 13:09:23 +0000 Subject: [PATCH 14/49] fix(expansion): isolate workload grasp frames and reset settling --- .../topics/expansion-engine/workloads.md | 7 ++ embodichain/lab/expansion/gym_workloads.py | 52 ++++++++- embodichain/lab/expansion/workloads.py | 5 + .../integrations/_configured_services.py | 26 ++++- .../task_program/integrations/configured.py | 6 +- .../integrations/simulation/environment.py | 32 +++++- tests/lab/expansion/test_workloads_sim.py | 103 ++++++++++++++++-- 7 files changed, 209 insertions(+), 22 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 50e7c58c0d..d0ce0faadf 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -30,6 +30,13 @@ existing session, frame collector, episode assembler and confirmed artifact sink Different integration/grasp policies may share that World only when their physical configuration, program and cadence agree. Physical/visual/prototype operators remain on the cohort API; unsupported payloads fail explicitly. +Explicit contact sampling conventions may differ per integration through +`SimulationTaskProgramAdapterFactory.create_adapter(grasp_contact_frames=...)`; +the declared frame must match its grasp service, while TCP, hardware geometry +and drive/command bindings remain strict and the live robot is unchanged. +Only the initial nominal reset may run scene-settling events. The facade then +freezes reset events; rolling preparation is checked against the physical step +counter so another row cannot advance outside the World-owner loop. Frozen groups export through one bounded writer thread without World access. Fresh output is required; this facade does not resume interrupted collection. diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 4109d677de..f7e8e56708 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -135,7 +135,7 @@ def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: ids = tuple(a.env_id for a in assignments) view = SceneView(self.env.sim, env_ids=ids) # Every candidate starts from the same seeded nominal reset. Original - # reset events may run, but cannot resample an unowned scene axis. + # scene reset events were frozen before rolling admission began. apply_changes_batch( view, {row: SceneChangeSet(self.nominal, tuple(self.nominal)) for row in ids}, @@ -559,12 +559,21 @@ def run_gym_expansion_workloads( first = configs[0][1] def physical_key(cfg: Any) -> str: + robot = deepcopy(cfg.robot.to_dict()) + for binding in robot.get("gripper_bindings", {}).values(): + binding["declaration"].pop("root_from_contact_frame", None) + binding["defaults"].pop("root_from_contact_frame", None) + binding["defaults"].get("binding", {}).pop("root_from_contact_frame", None) return _hash( { name: ( - getattr(cfg, name).to_dict() - if hasattr(getattr(cfg, name), "to_dict") - else getattr(cfg, name) + robot + if name == "robot" + else ( + getattr(cfg, name).to_dict() + if hasattr(getattr(cfg, name), "to_dict") + else getattr(cfg, name) + ) ) for name in ( "robot", @@ -609,7 +618,30 @@ def physical_key(cfg: Any) -> str: ] = env.task_program_adapter # Sampling only row zero retains the original B=1 seeded reference # regardless of the collection capacity. All rows use that same scene. + import inspect + from embodichain.lab.gym.envs.managers.event_manager import EventManager + + events = getattr(env, "event_manager", None) + if events is not None: + for name in events.active_functors.get("reset", ()): + event = deepcopy(events.get_functor_cfg(name)) + if "allow_partial_envs" in inspect.signature(event.func).parameters: + # No trajectories are live during this one nominal reset. + event.params["allow_partial_envs"] = True + events.set_functor_cfg(name, event) env.reset(seed=execution.seed, options={"save_data": False, "reset_ids": [0]}) + # The reference now owns all reset-time scene randomization/settling. + # Re-running those functors during row refill could advance live peers + # outside the executor and lose measured control boundaries. + if events is not None: + frozen_events = { + name: deepcopy(events.get_functor_cfg(name)) + for mode, names in events.active_functors.items() + if mode != "reset" + for name in names + } + env.cfg.events = frozen_events + env.event_manager = EventManager(frozen_events, env) snapshot = _preview_snapshot(env) nominal = { uid: env.sim.get_rigid_object(uid) @@ -668,7 +700,17 @@ def physical_key(cfg: Any) -> str: factory = REGISTERED_ENVS[raw["id"]].task_program_adapter_factory adapter = adapters.get(id(factory)) if adapter is None: - adapter = factory.create_adapter(env) + contact_frames = {} + for instance, binding in environment_cfg.robot.gripper_bindings.items(): + actual = first.robot.gripper_bindings[instance] + frame = binding["defaults"].get("root_from_contact_frame") + if frame != actual["defaults"].get("root_from_contact_frame"): + contact_frames[binding["declaration"]["control_part"]] = frame + adapter = ( + factory.create_adapter(env, grasp_contact_frames=contact_frames) + if contact_frames + else factory.create_adapter(env) + ) adapters[id(factory)] = adapter ctx.program = adapter.compile(environment_cfg.task_program) if ( diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index dfbd37b65e..4ecdc9afcb 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -353,6 +353,7 @@ def _fill(self) -> None: return self.refills += bool(self.live) assignments = tuple(added) + before = self.env.sim.physics_step_index result = self.env.reset( seed=self.cfg.seed, options={ @@ -361,6 +362,10 @@ def _fill(self) -> None: "episode_prepare": lambda: self.source.prepare(assignments), }, ) + if self.env.sim.physics_step_index != before: + raise RuntimeError( + "rolling reset/preparation must not advance World physics" + ) self.observation = result[0] rows = [a.env_id for a in added] self.hold[rows] = self.env.robot.get_qpos(target=True)[rows] diff --git a/embodichain/lab/task_program/integrations/_configured_services.py b/embodichain/lab/task_program/integrations/_configured_services.py index f4a7ea3c3b..7b65a1b690 100644 --- a/embodichain/lab/task_program/integrations/_configured_services.py +++ b/embodichain/lab/task_program/integrations/_configured_services.py @@ -358,7 +358,9 @@ class _AntipodalGraspPoseGeneratorFactory: filter_ground_collision: bool | None = None force_refresh: bool | None = None - def validate_binding(self, robot: object, target_id: str) -> None: + def validate_binding( + self, robot: object, target_id: str, *, contact_frame_override: object = None + ) -> None: """Reject a static service snapshot bound to different physical hardware.""" import json @@ -376,7 +378,17 @@ def validate_binding(self, robot: object, target_id: str) -> None: expected_binding = { key: value for key, value in declaration.items() if key != "instance" } - if json.dumps(selected["declaration"], sort_keys=True) != json.dumps( + actual_binding = dict(selected["declaration"]) + if contact_frame_override is not None: + # Explicit workload-local sampling frames change the proposal + # convention, never the installed TCP, mesh or joint commands. + if json.dumps(contact_frame_override, sort_keys=True) != json.dumps( + expected.get("root_from_contact_frame"), sort_keys=True + ): + raise ValueError("Contact frame must match the declared grasp service.") + expected_binding.pop("root_from_contact_frame", None) + actual_binding.pop("root_from_contact_frame", None) + if json.dumps(actual_binding, sort_keys=True) != json.dumps( expected_binding, sort_keys=True ): raise ValueError( @@ -391,11 +403,19 @@ def validate_binding(self, robot: object, target_id: str) -> None: ) def physical_model(values): - return { + result = { key: value for key, value in values.items() if key not in {"min_opening_width", "max_opening_width"} } + if contact_frame_override is not None: + result.pop("root_from_contact_frame", None) + result["binding"] = { + key: value + for key, value in result.get("binding", {}).items() + if key != "root_from_contact_frame" + } + return result if json.dumps(physical_model(actual), sort_keys=True) != json.dumps( physical_model(expected), sort_keys=True diff --git a/embodichain/lab/task_program/integrations/configured.py b/embodichain/lab/task_program/integrations/configured.py index a8b50a4376..6cfbae41c1 100644 --- a/embodichain/lab/task_program/integrations/configured.py +++ b/embodichain/lab/task_program/integrations/configured.py @@ -3380,6 +3380,8 @@ def registration(self) -> SimulationTaskProgramRegistration: def create_adapter( self, environment: object, + *, + grasp_contact_frames: Mapping[str, object] | None = None, ) -> TaskProgramEnvironmentAdapter: """Create a live adapter for an initialized environment.""" from .demo_skill import _ConfiguredDemoSkillSource @@ -3390,7 +3392,9 @@ def create_adapter( ): if getattr(environment, "num_envs", None) != 1: raise ValueError("configured Demo Skills require num_envs == 1") - adapter = self.delegate.create_adapter(environment) + adapter = self.delegate.create_adapter( + environment, grasp_contact_frames=grasp_contact_frames + ) adapter._set_configured_nominal_sources(self.nominal_motion_sources) return adapter diff --git a/embodichain/lab/task_program/integrations/simulation/environment.py b/embodichain/lab/task_program/integrations/simulation/environment.py index dfee0f64d9..064b4e2b2d 100644 --- a/embodichain/lab/task_program/integrations/simulation/environment.py +++ b/embodichain/lab/task_program/integrations/simulation/environment.py @@ -1529,16 +1529,44 @@ def registration(self) -> SimulationTaskProgramRegistration: def create_adapter( self, environment: object, + *, + grasp_contact_frames: Mapping[str, object] | None = None, ) -> TaskProgramEnvironmentAdapter: - """Create fresh grasp services and bind the initialized environment.""" + """Create fresh grasp services and bind the initialized environment. + + Args: + environment: Sole owner of the actual robot and physical World. + grasp_contact_frames: Explicit per-control-part sampling conventions + matching this factory's declared grasp services. Only these + contact frames may differ from the installed binding; TCP, + physical meshes, joint commands and all other calibration stay + strictly checked. The live robot configuration is never mutated. + + Returns: + Fresh adapter with independent grasp and execution services. + """ from embodichain.toolkits.graspkit import GraspPoseGenerator self._registration.assert_unchanged() + frames = dict(grasp_contact_frames or {}) + if set(frames) - self._grasp_pose_generator_factories.keys(): + raise ValueError("Contact frame overrides require declared grasp services.") generators: dict[str, GraspPoseGenerator] = {} for target_id, factory in self._grasp_pose_generator_factories.items(): validator = getattr(factory, "validate_binding", None) if validator is not None: - validator(environment.robot, target_id) + if target_id in frames: + validator( + environment.robot, + target_id, + contact_frame_override=frames[target_id], + ) + else: + validator(environment.robot, target_id) + elif target_id in frames: + raise ValueError( + "Grasp service cannot validate a contact frame override." + ) generator = factory() if not isinstance(generator, GraspPoseGenerator): raise TypeError( diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index d631ae8d8a..fe877ba1fe 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -348,6 +348,7 @@ def complete(self, result): def _facade_probe(output: str) -> None: + from copy import deepcopy import hashlib import json import torch @@ -363,6 +364,7 @@ def _facade_probe(output: str) -> None: ) from embodichain.lab.expansion.collision import _MeasuredCollision from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, discover_task_packages, execute_init_hooks, ) @@ -381,13 +383,44 @@ def _facade_probe(output: str) -> None: program["program"]["repeat"]["count"] = 1 override = path / "program.yaml" override.write_text(yaml.safe_dump(program)) - digest = hashlib.sha256(deployment.read_bytes()).hexdigest() + + def absolute_paths(value, base): + if isinstance(value, dict): + return {key: absolute_paths(item, base) for key, item in value.items()} + if isinstance(value, list): + return [absolute_paths(item, base) for item in value] + if isinstance(value, str) and value.endswith((".yaml", ".yml", ".json")): + return str((base / value).resolve()) + return value + + raw = absolute_paths(yaml.safe_load(deployment.read_text()), deployment.parent) + component = Path(raw["embodiment"]["component"]) + embodiment = absolute_paths(yaml.safe_load(component.read_text()), component.parent) + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + + base_cfg = config_to_cfg( + yaml.safe_load(deployment.read_text()), source_path=deployment + ) + contact = deepcopy( + base_cfg.robot.gripper_bindings["eef"]["defaults"]["root_from_contact_frame"] + ) + contact[0][3] += 0.001 + embodiment["grippers"]["eef"]["root_from_contact_frame"] = contact + component_override = path / "embodiment.yaml" + component_override.write_text(yaml.safe_dump(embodiment)) + raw["id"] = "TaskProgramRepeatedPickPlace-ContactFrame-v1" + raw["embodiment"]["component"] = str(component_override) + policy_deployment = path / "contact-frame.yaml" + policy_deployment.write_text(yaml.safe_dump(raw)) + config_to_cfg(raw, source_path=policy_deployment) discover_task_packages() execute_init_hooks() workloads = [] for name, target in (("pair", 2), ("queued", 1)): + selected_deployment = deployment if name == "pair" else policy_deployment + digest = hashlib.sha256(selected_deployment.read_bytes()).hexdigest() cfg = ExpansionRunCfg( - deployment=str(deployment), + deployment=str(selected_deployment), program=str(override), output_dir=str(path / name), target_episodes=target, @@ -405,25 +438,34 @@ def _facade_probe(output: str) -> None: "runtime_versions": {}, } workloads.append(GymExpansionWorkload(name, cfg, report, {})) + + observed_bindings = [] + + def validator(env, output): + binding = deepcopy(env.robot.cfg.gripper_bindings) + observed_bindings.append((env.robot.cfg, binding)) + factory = REGISTERED_ENVS[raw["id"]].task_program_adapter_factory + with pytest.raises(ValueError, match="actual hand installation"): + factory.create_adapter(env) + assert env.robot.cfg.gripper_bindings == binding + return _MeasuredCollision( + env, + str(root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml"), + output, + ) + result = run_gym_expansion_workloads( workloads, WorkloadExecutionCfg( workload_count=1, batch_size=2, max_steps=2500, settling_steps=5 ), - extensions=GymExpansionHostExtensions( - validator_factory=lambda env, output: _MeasuredCollision( - env, - str( - root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml" - ), - output, - ) - ), + extensions=GymExpansionHostExtensions(validator_factory=validator), output_dir=path / "execution", ) assert result["complete"], result assert result["num_envs"] == 2 and result["world"]["world_count"] == 1 assert not SimulationManager._instances + assert all(cfg.gripper_bindings == binding for cfg, binding in observed_bindings) for name, expected in (("pair", 2), ("queued", 1)): group = result["workloads"][name] assert group["complete"] and group["committed_episodes"] == expected @@ -439,6 +481,45 @@ def _facade_probe(output: str) -> None: ] + 1 == len(episode.actions) assert execution["world"] == result["world"] (path / "facade-result.json").write_text(json.dumps(result, indent=2)) + # A real drive change remains incompatible even though contact conventions + # above are allowed. Reject before constructing another World. + embodiment["simulation"]["joint_drive_props"]["stiffness"][ + "gripper_finger1_joint_1" + ] += 1 + hardware_component = path / "different-hardware.yaml" + hardware_component.write_text(yaml.safe_dump(embodiment)) + raw["id"] += "-Hardware" + raw["embodiment"]["component"] = str(hardware_component) + hardware_deployment = path / "different-hardware-task.yaml" + hardware_deployment.write_text(yaml.safe_dump(raw)) + rejected = GymExpansionWorkload( + "different", + ExpansionRunCfg( + **{ + **workloads[-1].cfg.to_dict(), + "deployment": str(hardware_deployment), + "output_dir": str(path / "different"), + } + ), + { + **workloads[-1].report, + "input_files": { + "deployment": hashlib.sha256( + hardware_deployment.read_bytes() + ).hexdigest() + }, + }, + {}, + ) + with pytest.raises(ValueError, match="physical environment"): + run_gym_expansion_workloads( + [workloads[0], rejected], + WorkloadExecutionCfg( + workload_count=1, batch_size=2, max_steps=2500, settling_steps=5 + ), + output_dir=path / "rejected", + ) + assert not SimulationManager._instances @pytest.mark.requires_sim From 7f9706409c94da2eca6a393eb2f4c65cf7e48dc1 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sun, 15 Nov 2026 16:09:44 +0000 Subject: [PATCH 15/49] feat(expansion): expose declarative collection and preview entrypoints --- .../expansion-engine/expansion-engine.md | 2 + .../topics/expansion-engine/workloads.md | 14 + docs/source/api_reference/public_api.rst | 55 ++ embodichain/lab/expansion/__init__.py | 14 + embodichain/lab/expansion/_preview_data.py | 5 +- .../lab/expansion/_task_program_config.py | 365 ++++++++++++ embodichain/lab/expansion/preview.py | 310 +++++++++++ .../lab/expansion/task_program_jobs.py | 525 ++++++++++++++++++ .../expansion/fixtures/task_program_job.yaml | 48 ++ tests/lab/expansion/test_configured.py | 27 + tests/lab/expansion/test_workloads_sim.py | 38 +- 11 files changed, 1398 insertions(+), 5 deletions(-) create mode 100644 embodichain/lab/expansion/_task_program_config.py create mode 100644 embodichain/lab/expansion/preview.py create mode 100644 embodichain/lab/expansion/task_program_jobs.py create mode 100644 tests/lab/expansion/fixtures/task_program_job.yaml diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 71ff869d5b..f1fb5fd569 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -12,6 +12,8 @@ algorithms stay in `sim.motion.expansion`; scene and workspace algorithms stay i | Shared scheduling, admission and commit ports | `embodichain/lab/expansion/engine.py` | | Rolling workload × B execution in one caller-owned World | `embodichain/lab/expansion/workloads.py` | | Native workload World, source/evidence assembly and bounded export | `embodichain/lab/expansion/gym_workloads.py` | +| Declarative scene/motion jobs and pure configuration validation | `embodichain/lab/expansion/task_program_jobs.py`, `_task_program_config.py` | +| Owned result-preview launch, wait and stop | `embodichain/lab/expansion/preview.py` | | Job assembly, stage recovery and inspect | `embodichain/lab/expansion/workflow.py`, `stages.py` | | Native World ownership and compatibility facade | `embodichain/lab/expansion/host.py` | | Task-owned render/source/transform/acceptance ports | `embodichain/lab/expansion/host_extensions.py` | diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index d0ce0faadf..18664b4b9e 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -22,6 +22,20 @@ difficult group does not silently borrow another group's B-row allocation. ## Source ports and native accounting +`run_task_program_expansion` binds a deployment and a closed scene/motion +configuration to `run_gym_expansion_workloads`. It owns bounded pose/follower +proposals, grasp-policy snapshots, original-grid plan transforms, common measured +acceptance and aggregate results. Configuration/viewer loaders do not import the +simulator. Integrators retain task values and provenance inputs rather than +copying these binding components. `derive_grasp_expansion_deployment` exposes the +same immutable-source preparation for configuration preflight. + +`launch_expansion_preview`, `preview_expansion_results` and +`stop_expansion_preview` manage a bounded Linux native service with recorded PID +ownership. The preview reader accepts native aggregate results and derives path +endpoints from recorded motion; downstream workflow-root unwrapping stays with +the integrator. These APIs never recollect or advance physical time. + `run_gym_expansion_workloads` is the public native composition for Task Program scene/plan workloads. `GymExpansionWorkload` supplies a pinned deployment, independent collection budget, artifacts and row callbacks. The facade opens one diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index 31ea4f6bfc..54a0d8089f 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1672,6 +1672,13 @@ and durable episode-boundary recovery. See the offline expansion example. WorkloadProgramExecutor GymExpansionWorkload run_gym_expansion_workloads + load_task_program_expansion + load_expansion_viewer + run_task_program_expansion + derive_grasp_expansion_deployment + launch_expansion_preview + stop_expansion_preview + preview_expansion_results export_expansion_episodes .. autosummary:: @@ -1937,6 +1944,28 @@ Stage immutable numeric evidence and archived source attachments before publishi load_expansion_episode +embodichain.lab.expansion.preview +-------------------------------- + +Launch, wait for or stop a bounded native result-preview service. Status and logs +remain separate from saved episodes; PID ownership is checked before signalling. +Inputs may be native jobs, aggregate scene/motion results or preview plans. +Recorded motion supplies an endpoint when several robot solvers are present. + +.. currentmodule:: embodichain.lab.expansion.preview + +.. autosummary:: + + launch_expansion_preview + preview_expansion_results + stop_expansion_preview + +.. autofunction:: launch_expansion_preview + +.. autofunction:: preview_expansion_results + +.. autofunction:: stop_expansion_preview + embodichain.lab.expansion.program --------------------------------- @@ -2028,6 +2057,32 @@ Source-independent session limits. These settings are separate from deployment-o ExpansionCollectionCfg ExpansionPersistenceCfg +embodichain.lab.expansion.task_program_jobs +------------------------------------------ + +Load closed scene/motion declarations without simulator imports, derive local +grasp policy snapshots and collect through the existing single-World workload +engine. Caller-owned source hashes and runtime versions remain in confirmed +episode evidence. Physical thresholds and protected phase boundaries are retained; +the facade owns configuration binding, preparation, export and optional preview. + +.. currentmodule:: embodichain.lab.expansion.task_program_jobs + +.. autosummary:: + + load_task_program_expansion + load_expansion_viewer + run_task_program_expansion + derive_grasp_expansion_deployment + +.. autofunction:: load_task_program_expansion + +.. autofunction:: load_expansion_viewer + +.. autofunction:: run_task_program_expansion + +.. autofunction:: derive_grasp_expansion_deployment + embodichain.lab.expansion.visual -------------------------------- diff --git a/embodichain/lab/expansion/__init__.py b/embodichain/lab/expansion/__init__.py index a954ea40c1..97a515b7ed 100644 --- a/embodichain/lab/expansion/__init__.py +++ b/embodichain/lab/expansion/__init__.py @@ -68,6 +68,13 @@ "WorkloadProgramExecutor", "GymExpansionWorkload", "run_gym_expansion_workloads", + "load_task_program_expansion", + "load_expansion_viewer", + "run_task_program_expansion", + "derive_grasp_expansion_deployment", + "launch_expansion_preview", + "stop_expansion_preview", + "preview_expansion_results", "export_expansion_episodes", "GymExpansionHostExtensions", "ExpansionRowContext", @@ -122,6 +129,13 @@ def __getattr__(name: str) -> object: "WorkloadProgramExecutor": "workloads", "GymExpansionWorkload": "gym_workloads", "run_gym_expansion_workloads": "gym_workloads", + "load_task_program_expansion": "_task_program_config", + "load_expansion_viewer": "_task_program_config", + "run_task_program_expansion": "task_program_jobs", + "derive_grasp_expansion_deployment": "task_program_jobs", + "launch_expansion_preview": "preview", + "stop_expansion_preview": "preview", + "preview_expansion_results": "preview", "export_expansion_episodes": "episode_export", "GymExpansionHostExtensions": "host_extensions", "ExpansionRowContext": "host_extensions", diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py index 06fda24abe..1d65e19715 100644 --- a/embodichain/lab/expansion/_preview_data.py +++ b/embodichain/lab/expansion/_preview_data.py @@ -313,7 +313,10 @@ def load_preview( raise ValueError( "Preview plan has no qualified trajectories; inspect its rejection/unrun records" ) - paths = [Path(p).expanduser().resolve() for p in outputs] + from .preview import _inputs, _recorded_eef + + paths = _inputs([Path(p) for p in outputs]) + eef_link = eef_link or _recorded_eef(paths) if len(set(paths)) != len(paths): raise ValueError("Duplicate output directory") if reference is not None: diff --git a/embodichain/lab/expansion/_task_program_config.py b/embodichain/lab/expansion/_task_program_config.py new file mode 100644 index 0000000000..b092888ffc --- /dev/null +++ b/embodichain/lab/expansion/_task_program_config.py @@ -0,0 +1,365 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Closed scene/motion declarations for native Task Program workloads.""" + +from __future__ import annotations +from pathlib import Path +from typing import Any +import math +import json +import yaml + +__all__: list[str] = [] + + +def load_mapping(path: str | Path) -> dict[str, Any]: + """Read declarations without importing the simulator or its logging hooks.""" + path = Path(path) + text = path.read_text(encoding="utf-8") + value = json.loads(text) if path.suffix == ".json" else yaml.safe_load(text) + if not isinstance(value, dict): + raise ValueError(f"Expected a mapping in {path}") + return value + + +OPERATORS = ( + "object_pose", + "affordance", + "joint_residual", + "via_points", + "nullspace_residual", +) + + +def load_expansion_viewer(value: dict | None = None) -> dict: + """Resolve presentation options without importing the native simulator. + + Args: + value: Optional headless and renderer declarations. + Returns: + Owned normalized options; unsupported values reject. + """ + if value is None: + value = {} + if not isinstance(value, dict) or set(value) - {"headless", "renderer"}: + raise ValueError("Expansion viewer accepts only headless and renderer") + headless, renderer = value.get("headless", True), value.get("renderer", "rt") + if type(headless) is not bool: + raise ValueError("Expansion viewer.headless must be a boolean") + if renderer not in ("rt", "fast-rt", "hybrid"): + raise ValueError("Expansion viewer.renderer must be rt, fast-rt or hybrid") + return {"headless": headless, "renderer": renderer} + + +def load_task_program_expansion(path: str | Path) -> dict[str, Any]: + """Load bounded scene/motion declarations while retaining physical criteria. + + Args: + path: YAML/JSON engine, scene, trajectory and validation declarations. + Returns: + Owned normalized declaration, including workload capacity. + Raises: + ValueError: For invalid scopes, protected phases, budgets or criteria. + """ + path = Path(path) + value = load_mapping(path) + if ( + set(value) != {"schema_version", "engine", "scene", "trajectory", "validation"} + or value["schema_version"] != 1 + ): + raise ValueError("Invalid demo expansion configuration") + engine, motion = value["engine"], value["trajectory"] + required_engine = { + "episodes_per_operator", + "max_attempts", + "max_steps", + "max_wall_time_s", + "settling_steps", + "capture_media", + } + if required_engine - set(engine) or set(engine) - required_engine - { + "cpu_threads", + "operator_workers", + "workload_count", + "batch_size", + "collision_device", + "grasp_nms_chunk_size", + "collection_renderer", + "collision_backend", + }: + raise ValueError("Unknown or missing expansion engine settings") + engine.setdefault("cpu_threads", 1) + if "operator_workers" in engine: + if "workload_count" in engine: + raise ValueError( + "Use engine.workload_count without legacy operator_workers" + ) + # Compatibility is a capacity migration, never a process fallback. + engine["workload_count"] = engine.pop("operator_workers") + engine.setdefault("workload_count", 1) + engine.setdefault("batch_size", 1) + engine.setdefault("collision_device", "cpu") + engine.setdefault("grasp_nms_chunk_size", 2048) + engine.setdefault("collection_renderer", "auto") + engine.setdefault("collision_backend", "newton") + if engine["collection_renderer"] not in ("auto", "rt", "fast-rt", "hybrid"): + raise ValueError( + "engine.collection_renderer must be auto, rt, fast-rt or hybrid" + ) + if engine["collision_backend"] not in ("newton", "native_contacts"): + raise ValueError("engine.collision_backend must be newton or native_contacts") + for name in ( + "episodes_per_operator", + "max_attempts", + "max_steps", + "settling_steps", + "cpu_threads", + "workload_count", + "batch_size", + "grasp_nms_chunk_size", + ): + if type(engine[name]) is not int or engine[name] < 1: + raise ValueError(f"engine.{name} must be a positive integer") + device = engine["collision_device"] + if not isinstance(device, str) or not ( + device == "cpu" + or device == "cuda" + or (device.startswith("cuda:") and device[5:].isdigit()) + ): + raise ValueError("engine.collision_device must be cpu, cuda or cuda:") + if ( + engine["max_attempts"] < engine["episodes_per_operator"] + or type(engine["capture_media"]) is not bool + ): + raise ValueError("Invalid expansion attempt or media settings") + required = { + "operators", + "joint_offset_scale", + "via_count", + "max_proposals", + "minimum_joint_delta", + "velocity_limit", + "acceleration_limit", + "nullspace_task_rows", + "nullspace_translation_tolerance_m", + "nullspace_rotation_tolerance_rad", + "free_phases", + } + if required - set(motion) or set(motion) - required - { + "affordance", + "call_indices", + }: + raise ValueError("Unknown or missing trajectory settings") + calls = motion.get("call_indices") + if calls is not None and ( + not isinstance(calls, list) + or not calls + or any(type(index) is not int or index < 0 for index in calls) + or len(set(calls)) != len(calls) + ): + raise ValueError( + "Trajectory call_indices must be distinct non-negative integers" + ) + operators = motion["operators"] + if ( + not isinstance(operators, list) + or not operators + or len(set(operators)) != len(operators) + or set(operators) - set(OPERATORS) + ): + raise ValueError( + "trajectory.operators must contain distinct supported operators" + ) + affordance = motion.get("affordance") + if "affordance" in operators and affordance is None: + raise ValueError("trajectory.affordance is required for affordance expansion") + if affordance is not None: + required_affordance = {"branches", "call_indices", "action_options"} + if ( + not isinstance(affordance, dict) + or required_affordance - set(affordance) + or set(affordance) - required_affordance - {"grasp_generators"} + ): + raise ValueError("Invalid trajectory.affordance settings") + if type(affordance["branches"]) is not int or affordance["branches"] < 2: + raise ValueError("trajectory.affordance.branches must be at least two") + calls = affordance["call_indices"] + if ( + not isinstance(calls, list) + or not calls + or any(type(index) is not int or index < 0 for index in calls) + or len(set(calls)) != len(calls) + ): + raise ValueError( + "Affordance call_indices must be distinct non-negative integers" + ) + if not isinstance(affordance["action_options"], dict) or any( + not isinstance(name, str) or not isinstance(options, dict) + for name, options in affordance["action_options"].items() + ): + raise ValueError( + "Affordance action_options must map preset names to settings" + ) + generators = affordance.get("grasp_generators", {}) + if not isinstance(generators, dict): + raise ValueError("Affordance grasp_generators must be a mapping") + for name, settings in generators.items(): + if ( + not isinstance(name, str) + or not isinstance(settings, dict) + or not settings + or set(settings) + - { + "max_candidates", + "approach_deviation_angle", + "kind", + "gripper", + "root_from_contact_frame", + } + ): + raise ValueError("Invalid affordance grasp generator overrides") + if {"kind", "gripper"} & settings.keys() and ( + not {"kind", "gripper"} <= settings.keys() + or settings["kind"] != "antipodal_parallel_jaw" + or not isinstance(settings["gripper"], dict) + ): + raise ValueError( + "A new grasp generator requires its kind and physical gripper description" + ) + count = settings.get("max_candidates", 2) + angle = settings.get("approach_deviation_angle", 0.0) + if type(count) is not int or count < 1: + raise ValueError("Affordance max_candidates must be positive") + if type(angle) not in (int, float) or not math.isfinite(angle) or angle < 0: + raise ValueError( + "Affordance approach_deviation_angle must be finite and non-negative" + ) + for name in ("via_count", "max_proposals"): + if type(motion[name]) is not int or motion[name] < 1: + raise ValueError(f"trajectory.{name} must be a positive integer") + for name in required - { + "operators", + "via_count", + "max_proposals", + "nullspace_task_rows", + "free_phases", + }: + if ( + type(motion[name]) not in (float, int) + or not math.isfinite(motion[name]) + or motion[name] <= 0 + ): + raise ValueError(f"trajectory.{name} must be finite and positive") + if motion["nullspace_task_rows"] not in ([0, 1, 2], [0, 1, 2, 3, 4, 5]): + raise ValueError( + "Nullspace tasks must explicitly constrain position or full pose" + ) + # These are the upstream skills' conservative free phases, narrowed for these demos. + allowed = { + "hand_over": {"pickup_approach"}, + "pick_up": {"approach"}, + "place": {"retract"}, + } + if not isinstance(motion["free_phases"], dict) or not motion["free_phases"]: + raise ValueError("Explicit free_phases are required") + for skill, phases in motion["free_phases"].items(): + if ( + skill not in allowed + or not isinstance(phases, list) + or not phases + or set(phases) - allowed[skill] + ): + raise ValueError(f"Unsupported or protected free phase for {skill}") + scene = value["scene"] + if not isinstance(scene, dict) or not scene: + raise ValueError("Explicit scene pose ranges are required") + for uid, options in scene.items(): + if set(options) == {"follow"}: + if options["follow"] not in scene or "follow" in scene[options["follow"]]: + raise ValueError( + "Scene followers must reference an independent pose range" + ) + continue + if ( + set(options) != {"translation_m", "yaw_rad"} + or len(options["translation_m"]) != 3 + ): + raise ValueError(f"Invalid scene pose range for {uid}") + for limits in (*options["translation_m"], options["yaw_rad"]): + if ( + len(limits) != 2 + or any( + type(x) not in (float, int) or not math.isfinite(x) for x in limits + ) + or limits[0] > limits[1] + ): + raise ValueError(f"Invalid finite ordered pose range for {uid}") + if not math.isfinite(engine["max_wall_time_s"]) or engine["max_wall_time_s"] <= 0: + raise ValueError("engine.max_wall_time_s must be finite and positive") + required_validation = { + "initial_checks", + "final_checks", + "events", + "allowed_contacts", + "mounting_contacts", + } + if required_validation - set(value["validation"]) or set( + value["validation"] + ) - required_validation - {"contact_hold"}: + raise ValueError( + "Explicit measured validation and contact permissions are required" + ) + hold = value["validation"].get("contact_hold") + if hold is not None: + if ( + engine["collision_backend"] != "native_contacts" + or not isinstance(hold, dict) + or set(hold) + != { + "entity", + "links", + "duration_s", + "max_translation_drift_m", + "max_rotation_drift_rad", + } + ): + raise ValueError( + "contact_hold requires native_contacts and explicit hold settings" + ) + if ( + not isinstance(hold["entity"], str) + or not hold["entity"] + or not isinstance(hold["links"], list) + or len(hold["links"]) != 2 + or len(set(hold["links"])) != 2 + or any(not isinstance(link, str) or not link for link in hold["links"]) + ): + raise ValueError( + "contact_hold requires an entity and two distinct robot links" + ) + for field in ( + "duration_s", + "max_translation_drift_m", + "max_rotation_drift_rad", + ): + if ( + type(hold[field]) not in (float, int) + or not math.isfinite(hold[field]) + or hold[field] <= 0 + ): + raise ValueError(f"contact_hold.{field} must be finite and positive") + return value diff --git a/embodichain/lab/expansion/preview.py b/embodichain/lab/expansion/preview.py new file mode 100644 index 0000000000..b136d85869 --- /dev/null +++ b/embodichain/lab/expansion/preview.py @@ -0,0 +1,310 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Owned launch, wait and stop operations for native result-preview services.""" + +from __future__ import annotations + +import json +import math +import os +from pathlib import Path +import signal +import subprocess +import sys +import time +from uuid import uuid4 + +from ._task_program_config import load_mapping +from embodichain.data_pipeline.recording.media import _atomic_json as atomic_json +from datetime import datetime, timezone + + +def utc_now() -> str: + return datetime.now(timezone.utc).isoformat() + + +__all__ = [ + "launch_expansion_preview", + "preview_expansion_results", + "stop_expansion_preview", +] + + +def _process_command(pid: int) -> bytes: + try: + return Path(f"/proc/{pid}/cmdline").read_bytes() + except FileNotFoundError: + return b"" + + +def _inputs(paths: list[Path]) -> list[Path]: + result = [] + for supplied in paths: + path = supplied.expanduser().resolve() + if (path / "job.json").is_file() or (path / "preview-plan.json").is_file(): + result.append(path) + elif (path / "expansion.json").is_file(): + data = load_mapping(path / "expansion.json") + result.extend( + Path(row["directory"]).resolve() + for row in data.get("operators", {}).values() + if row.get("committed_episodes", 0) > 0 + ) + else: + raise ValueError( + f"Preview input must be an aggregate result or native job: {path}" + ) + if not result or len(set(result)) != len(result): + raise ValueError( + "Preview requires distinct job outputs with confirmed episodes" + ) + return result + + +def _recorded_eef(inputs: list[Path]) -> str | None: + """Resolve the first measured motion endpoint, without robot-name routing.""" + from embodichain.lab.expansion import ArtifactEpisodeSink, load_expansion_episode + + for path in inputs: + if not (path / "job.json").is_file(): + continue + job = load_mapping(path / "job.json") + robot = job.get("resolved_deployment", {}).get("robot", {}) + solvers = robot.get("solver_cfg", {}) + ends = { + item.get("end_link_name") + for item in solvers.values() + if item.get("end_link_name") + } + if len(ends) == 1: + return next(iter(ends)) + receipts = ArtifactEpisodeSink(path).inspect() + if not receipts: + continue + episode = load_expansion_episode(receipts[0].storage_id) + for record in episode.metadata.get("expansion", ()): + joints = set(record.get("controlled_joint_names", ())) + matches = [ + cfg.get("end_link_name") + for cfg in solvers.values() + if joints + and joints == set(cfg.get("joint_names") or ()) + and cfg.get("end_link_name") + ] + if len(set(matches)) == 1: + return matches[0] + for segment in episode.metadata.get("program_segments", ()): + runtime = segment.get( + "runtime", segment.get("metadata", {}).get("runtime", {}) + ) + for call in runtime.get("calls", ()): + for endpoint in call.get("resolved_core_policy", {}).get( + "endpoints", () + ): + if endpoint.get("endpoint_id") == "motion": + end = solvers.get(endpoint.get("target_id"), {}).get( + "end_link_name" + ) + if end: + return end + return None + + +def launch_expansion_preview( + paths: list[Path], + *, + output: Path | None = None, + port: int = 0, + gpu: int = 0, + duration: float = 900, + open_browser: bool = False, + eef_link: str | None = None, + startup_timeout: float = 240, + max_episodes: int = 32, +) -> dict: + """Start a bounded native preview service after collection/export completes. + + Logs/status are separate from immutable run artifacts. Inputs are read-only; + no trajectory is recollected, substituted or credited as another success. + + Args: + paths: Native job, aggregate result or preview-plan directories. + output: New directory for owned service status and logs. + port: Loopback port; zero allocates an available port. + gpu: Visible GPU index used by the read-only renderer. + duration: Service seconds after readiness; zero waits for interruption. + open_browser: Open a browser after native rendering is ready. + eef_link: Optional endpoint; recorded motion supplies it otherwise. + startup_timeout: Bounded wait for the first complete frame. + max_episodes: Maximum recorded episodes to preload, between one and 64. + Returns: + Owned service status, command identity and ready URL. Linux PID ownership + is checked before the stop/wait APIs signal the process. + """ + paths = [Path(path) for path in paths] + if ( + type(port) is not int + or not 0 <= port <= 65535 + or type(gpu) is not int + or gpu < 0 + ): + raise ValueError("Invalid preview port or GPU") + if ( + not math.isfinite(duration) + or duration < 0 + or not math.isfinite(startup_timeout) + or startup_timeout <= 0 + ): + raise ValueError("Invalid preview duration/startup timeout") + if type(max_episodes) is not int or not 1 <= max_episodes <= 64: + raise ValueError("Preview max_episodes must be in [1,64]") + inputs = _inputs(paths) + output = ( + output or (paths[0].resolve().parent / ".previews" / uuid4().hex) + ).resolve() + output.mkdir(parents=True, exist_ok=True) + status_path = output / "status.json" + if status_path.exists(): + raise FileExistsError(f"Preview status already exists: {status_path}") + command = [sys.executable, "-m", "embodichain", "expansion", "preview"] + for path in inputs: + command.extend(["--input", str(path)]) + command.extend( + [ + "--port", + str(port), + "--gpu", + str(gpu), + "--duration", + str(duration), + "--max-episodes", + str(max_episodes), + ] + ) + end = eef_link or _recorded_eef(inputs) + if end: + command.extend(["--eef-link", end]) + if open_browser: + command.append("--open") + log_path = output / "server.log" + with log_path.open("w") as log: + process = subprocess.Popen( + command, stdout=log, stderr=subprocess.STDOUT, start_new_session=True + ) + status = { + "state": "starting", + "pid": process.pid, + "command": command, + "inputs": [str(p) for p in inputs], + "started_at": utc_now(), + "status_file": str(status_path), + "log": str(log_path), + } + atomic_json(status_path, status) + deadline = time.monotonic() + startup_timeout + try: + while time.monotonic() < deadline: + for line in log_path.read_text(errors="replace").splitlines(): + try: + ready = json.loads(line) + except ValueError: + continue + if isinstance(ready, dict) and ready.get("state") == "ready": + status.update(ready, state="ready", eef_link=end) + atomic_json(status_path, status) + return status + if process.poll() is not None: + raise RuntimeError( + f"Native preview exited {process.returncode}: {log_path.read_text(errors='replace')[-3000:]}" + ) + time.sleep(0.1) + raise TimeoutError(f"Native preview startup timed out; see {log_path}") + except BaseException: + if process.poll() is None: + process.send_signal(signal.SIGINT) + try: + process.wait(timeout=30) + except subprocess.TimeoutExpired: + process.kill() + process.wait() + atomic_json( + status_path, {**status, "state": "failed", "returncode": process.returncode} + ) + raise + + +def stop_expansion_preview(path: str | Path) -> dict[str, object]: + """Stop only the native service whose recorded command still owns its PID. + + Args: + path: Service status JSON or its directory. + Returns: + Closed status after the owned process stops; changed ownership rejects. + """ + path = Path(path) + status_path = path / "status.json" if path.is_dir() else path + status = load_mapping(status_path) + pid = status["pid"] + command = _process_command(pid) + if command: + actual = command.rstrip(b"\0").split(b"\0") + if actual != [os.fsencode(arg) for arg in status["command"]]: + raise ValueError("Preview PID is no longer owned by the recorded command") + try: + os.kill(pid, signal.SIGINT) + except ProcessLookupError: + pass + deadline = time.monotonic() + 30 + while _process_command(pid) and time.monotonic() < deadline: + time.sleep(0.1) + if _process_command(pid): + raise TimeoutError("Preview has not stopped; inspect its log") + status.update(state="closed", closed_at=utc_now()) + atomic_json(status_path, status) + return status + + +def preview_expansion_results( + paths: list[Path], **options: object +) -> dict[str, object]: + """Run the native browser viewer until its duration ends or Ctrl+C stops it. + + Args: + paths: Confirmed native job or aggregate result directories. + **options: Launch options accepted by :func:`launch_expansion_preview`. + Returns: + Final service status after bounded playback or interruption. + """ + status = launch_expansion_preview(paths, **options) + sys.stdout.write(json.dumps(status, ensure_ascii=False) + "\n") + sys.stdout.flush() + try: + expected = [os.fsencode(arg) for arg in status["command"]] + while True: + command = _process_command(status["pid"]) + if not command or command.rstrip(b"\0").split(b"\0") != expected: + break + time.sleep(0.2) + except KeyboardInterrupt: + return stop_expansion_preview(Path(status["status_file"])) + try: + os.waitpid(status["pid"], os.WNOHANG) + except ChildProcessError: + pass + status.update(state="closed", closed_at=utc_now()) + atomic_json(Path(status["status_file"]), status) + return status diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py new file mode 100644 index 0000000000..d32682ad68 --- /dev/null +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -0,0 +1,525 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Declarative scene/motion jobs composed through the native workload engine.""" + +from __future__ import annotations +from collections.abc import Mapping, Sequence +from copy import deepcopy +from dataclasses import replace +from pathlib import Path +from typing import Any, TYPE_CHECKING +import hashlib +import json +import os +from embodichain.utils.utility import load_config as load_mapping +from embodichain.data_pipeline.recording.media import ( + _digest as file_digest, + _atomic_json as atomic_json, +) +from ._task_program_config import load_task_program_expansion, load_expansion_viewer + +if TYPE_CHECKING: + from embodichain.lab.sim.scene.feasibility import JointSceneCandidate + +__all__ = [ + "load_task_program_expansion", + "load_expansion_viewer", + "run_task_program_expansion", + "derive_grasp_expansion_deployment", +] + + +def _load_deployment(path: Path) -> None: + from embodichain.lab.gym.utils.registration import ( + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + + discover_task_packages() + execute_init_hooks() + config_to_cfg(load_mapping(path), source_path=path) + + +class _BoundedPoseSource: + """Sample bounded arena-frame changes with task-declared support followers.""" + + def __init__( + self, env: Any, configuration: Mapping[str, Any], *, seed: int, revision: str + ) -> None: + self.configuration, self.seed, self.request_id = configuration, seed, revision + self.poses = { + uid: env.sim.get_rigid_object(uid) + .get_local_pose(to_matrix=True)[0] + .detach() + .cpu() + .numpy() + .copy() + for uid in configuration + } + self.roots = { + env.robot.uid: env.robot.get_local_pose(to_matrix=True)[0] + .detach() + .cpu() + .tolist() + } + + def candidate(self, ordinal: int) -> JointSceneCandidate: + import numpy as np + from embodichain.lab.sim.scene.expansion import ScenePoseChange, SceneVariant + from embodichain.lab.sim.scene.feasibility import ( + JointSceneCandidate, + RobotDeploymentCandidate, + ) + + offsets = {} + for uid, options in self.configuration.items(): + if "follow" in options: + continue + seed = int.from_bytes( + hashlib.sha256(f"{self.seed}/{ordinal}/{uid}".encode()).digest()[:8], + "little", + ) + generator = np.random.default_rng(seed) + offsets[uid] = [ + generator.uniform(*bounds) + for bounds in (*options["translation_m"], options["yaw_rad"]) + ] + changes, parameters = [], [] + for uid, options in self.configuration.items(): + dx, dy, dz, yaw = offsets[options.get("follow", uid)] + pose = self.poses[uid].copy() + c, s = np.cos(yaw), np.sin(yaw) + pose[:3, :3] = np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]) @ pose[:3, :3] + pose[:3, 3] += (dx, dy, dz) + changes.append(ScenePoseChange(uid, tuple(map(tuple, pose)))) + parameters.extend((dx, dy, dz, yaw)) + scene = SceneVariant(self.request_id, self.seed, ordinal, tuple(changes)) + return JointSceneCandidate( + self.request_id, + scene, + RobotDeploymentCandidate(self.roots), + "object_pose", + tuple(parameters), + ) + + +def _task_expansion_extensions(*, options, operator, seed, report): + """Declare task proposals; upstream owns collection and persistence.""" + from .host_extensions import GymExpansionHostExtensions + + pose_source = None + + def source(env): + nonlocal pose_source + pose_source = _BoundedPoseSource( + env, options["scene"], seed=seed, revision=report["semantic_id"] + ) + return pose_source + + def recipe_transform(recipe): + operations = [] + for operation in recipe.operations: + payload = json.loads(operation.payload_json) + if operation.name == "motion": + payload.update(operator=operator, options=options["trajectory"]) + elif operation.name == "joint_scene": + candidate = pose_source.candidate(recipe.context.ordinal) + payload["pose_changes"] = { + change.entity_uid: change.arena_pose + for change in candidate.scene.pose_changes + } + operations.append(replace(operation, payload_json=json.dumps(payload))) + return replace(recipe, operations=tuple(operations)) + + def plans(env, row): + from embodichain.lab.task_program.integrations.expansion import ( + TaskProgramSameGridExpansionFactory, + ) + + return TaskProgramSameGridExpansionFactory.from_native_plan( + operator, + options["trajectory"], + seed=seed + row.ordinal, + scene_case=row.scene_case, + revision=report["recipe_revision"], + output=row.directory / "plans", + episode_id=row.ordinal, + ) + + return GymExpansionHostExtensions( + scene_source_factory=source, + recipe_transform=recipe_transform, + plan_transform_factory=plans, + require_plan_transform=operator != "object_pose", + ) + + +def _prepare_deployment(deployment: Path, output: Path) -> Path: + """Snapshot configuration without opening a reference simulation World.""" + from embodichain.utils.config_paths import resolve_config_path + import yaml + + original = load_mapping(deployment) + + def paths(value): + if isinstance(value, dict): + return {key: paths(item) for key, item in value.items()} + if isinstance(value, list): + return [paths(item) for item in value] + if isinstance(value, str) and value.endswith((".yaml", ".yml", ".json")): + return str(resolve_config_path(value, base_dir=deployment.parent).resolve()) + return value + + snapshot = paths(deepcopy(original)) + owner = "environment" if "environment" in snapshot else "scene" + if "component" in snapshot[owner]: + physical = load_mapping(Path(snapshot[owner]["component"])) + snapshot[owner] = {"component": str((output / "environment.yaml").resolve())} + else: + from embodichain.lab.gym.utils.composition import resolve_gym_components + + physical = resolve_gym_components( + {owner: snapshot[owner]}, base_dir=deployment.parent + ).config + (output / "environment.yaml").write_text(yaml.safe_dump(physical, sort_keys=False)) + snapshot["id"] += "-Expansion-v1" + path = output / "deployment.json" + atomic_json(path, snapshot) + atomic_json( + output / "source.json", + { + "deployment": str(deployment), + "sha256": file_digest(deployment), + "config": original, + }, + ) + return path + + +def derive_grasp_expansion_deployment( + deployment: str | Path, output: str | Path, settings: Mapping[str, Any] +) -> Path: + """Snapshot a native grasp policy without mutating the source deployment. + + Args: + deployment: Native deployment with integration and embodiment references. + output: Fresh directory for derived component files. + settings: Validated affordance action_options and grasp_generators. + + Returns: + Derived deployment path, usable by native configuration preflight or + ordinary task execution. Physical task criteria remain unchanged. + """ + deployment, output = Path(deployment), Path(output) + from embodichain.utils.config_paths import resolve_config_path + import yaml + + snapshot = load_mapping(deployment) + integration_path = resolve_config_path( + snapshot["task_program"]["integration"], base_dir=deployment.parent + ) + integration = load_mapping(integration_path) + profile = integration["profile"] + presets = profile.get("skill_options", profile.get("action_options", {})) + for name, changes in settings["action_options"].items(): + if name not in presets or "kind" in changes: + raise ValueError( + "Affordance options must retain existing skill preset kinds" + ) + for key, value in changes.items(): + if value is None: + presets[name].pop(key, None) + else: + presets[name][key] = value + output.mkdir(parents=True) + integration_path = output / "integration.yaml" + integration_path.write_text(yaml.safe_dump(integration, sort_keys=False)) + snapshot["task_program"]["integration"] = str(integration_path.resolve()) + generator_overrides = settings.get("grasp_generators", {}) + if generator_overrides: + embodiment_path = resolve_config_path( + snapshot["embodiment"]["component"], base_dir=deployment.parent + ) + embodiment = load_mapping(embodiment_path) + generators = ( + embodiment["skill_profile"] + .setdefault("runtime_services", {}) + .setdefault("grasp_pose_generators", {}) + ) + for name, changes in generator_overrides.items(): + changes = dict(changes) + if "root_from_contact_frame" in changes: + # Bound physical data belongs to the actual gripper declaration, + # not its generator policy. Keep both native views consistent. + bound = [ + item + for item in embodiment.get("grippers", {}).values() + if item.get("control_part") == name + ] + if len(bound) != 1: + raise ValueError( + "A contact frame override requires one bound gripper" + ) + bound[0]["root_from_contact_frame"] = changes.pop( + "root_from_contact_frame" + ) + if name not in generators: + if not {"kind", "gripper"} <= changes.keys(): + raise ValueError(f"Unknown embodiment grasp generator: {name}") + generators[name] = {} + generators[name].update(changes) + embodiment_path = output / "embodiment.yaml" + embodiment_path.write_text(yaml.safe_dump(embodiment, sort_keys=False)) + snapshot["embodiment"]["component"] = str(embodiment_path.resolve()) + snapshot["id"] += "-Affordance-v1" + path = output / "deployment.json" + atomic_json(path, snapshot) + return path + + +def _run_operators( + deployment, output, options, selected, *, seed, sources, viewer, runtime_versions +): + """Call the public upstream collector without operator processes.""" + from embodichain.lab.expansion import ( + ExpansionRunCfg, + GymExpansionHostExtensions, + GymExpansionWorkload, + MeasuredExpansionValidator, + WorkloadExecutionCfg, + run_gym_expansion_workloads, + ) + from embodichain.utils.nms import pose_nms_scope + import torch + + settings = options["engine"] + versions = dict(runtime_versions) + workloads = [] + for name in selected: + operator_deployment = deployment + artifacts = dict(sources) + affordance = options["trajectory"].get("affordance", {}) + if name == "affordance" and ( + affordance["action_options"] or affordance.get("grasp_generators") + ): + operator_deployment = derive_grasp_expansion_deployment( + deployment, output / "inputs" / "affordance", affordance + ) + for path in operator_deployment.parent.iterdir(): + if path.is_file(): + artifacts[f"affordance_{path.name}"] = { + "path": str(path), + "sha256": file_digest(path), + } + _load_deployment(operator_deployment) + identity = hashlib.sha256( + json.dumps( + { + "options": options, + "operator": name, + "seed": seed, + "source_hashes": sorted( + value["sha256"] for value in artifacts.values() + ), + }, + sort_keys=True, + ).encode() + ).hexdigest() + report = { + "job_id": identity, + "semantic_id": identity, + "execution_id": identity, + "recipe_revision": identity, + "input_files": {"deployment": file_digest(operator_deployment)}, + "operator": name, + "adapter": "embodichain.task-program-workloads-v1", + "runtime_versions": versions, + "viewer": viewer, + } + cfg = ExpansionRunCfg( + deployment=str(operator_deployment), + output_dir=str((output / "dataset" / name).resolve()), + batch_size=settings["batch_size"], + target_episodes=settings["episodes_per_operator"], + max_attempts=settings["max_attempts"], + max_steps=settings["max_steps"], + max_wall_time_s=settings["max_wall_time_s"], + settling_steps=settings["settling_steps"], + capture_media=settings["capture_media"], + seed=seed, + ) + workloads.append( + GymExpansionWorkload( + name, + cfg, + report, + artifacts, + _task_expansion_extensions( + options=options, operator=name, seed=seed, report=report + ), + ) + ) + renderer = settings["collection_renderer"] + if renderer == "auto": + renderer = viewer["renderer"] if settings["capture_media"] else None + common = GymExpansionHostExtensions( + collection_renderer=renderer, + validator_factory=lambda env, path: MeasuredExpansionValidator( + env, + options["validation"], + path, + backend=( + "native_contacts" + if settings["collision_backend"] == "native_contacts" + else "geometry" + ), + device=settings["collision_device"], + ), + ) + execution = WorkloadExecutionCfg( + workload_count=min(settings["workload_count"], len(selected)), + batch_size=settings["batch_size"], + max_steps=settings["max_steps"], + settling_steps=settings["settling_steps"], + seed=seed, + ) + chunks = settings["grasp_nms_chunk_size"] if torch.cuda.is_available() else 2048 + with pose_nms_scope(chunk_size=chunks): + result = run_gym_expansion_workloads( + workloads, execution, extensions=common, output_dir=output + ) + atomic_json(output / "workload-execution.json", result) + return result["workloads"] + + +def run_task_program_expansion( + deployment: str | Path, + configuration: str | Path, + output_dir: str | Path, + *, + seed: int = 0, + operators: Sequence[str] | None = None, + source_artifacts: Mapping[str, object] | None = None, + runtime_versions: Mapping[str, object] | None = None, + viewer: Mapping[str, object] | None = None, + preview_output: str | Path | None = None, +) -> Mapping[str, object]: + """Collect declared scene/motion operators through the single-World engine. + + Args: + deployment: Native Gym deployment; task discovery uses installed providers. + configuration: Closed YAML/JSON scene, trajectory and measured criteria. + output_dir: Fresh collection directory; aggregate results are saved here. + seed: Candidate seed, independent of physical row allocation. + operators: Optional enabled subset in its desired group order. + source_artifacts: Caller-owned hashed inputs retained in native evidence. + runtime_versions: Caller provenance; package versions are read when absent. + viewer: Headless/renderer declarations. A non-headless job opens the native + read-only preview after collection, qualification and export. + preview_output: Optional service status/log directory outside saved data. + + Returns: + Owned operator quotas, confirmed readback, native dataset paths and preview + status. Incomplete groups remain explicit and never earn success credit. + """ + from importlib import import_module, metadata + import torch + + deployment, configuration, output = ( + Path(deployment), + Path(configuration), + Path(output_dir), + ) + options = load_task_program_expansion(configuration) + view = load_expansion_viewer(None if viewer is None else dict(viewer)) + selected = list( + options["trajectory"]["operators"] if operators is None else operators + ) + if ( + not selected + or len(set(selected)) != len(selected) + or set(selected) - set(options["trajectory"]["operators"]) + ): + raise ValueError("Requested operators must be a distinct enabled subset") + import_module("lerobot.datasets.lerobot_dataset") + threads = options["engine"]["cpu_threads"] + for name in ("OMP_NUM_THREADS", "MKL_NUM_THREADS", "OPENBLAS_NUM_THREADS"): + os.environ[name] = str(threads) + torch.set_num_threads(threads) + if runtime_versions is None: + runtime_versions = {} + for name in ( + "embodichain", + "dexsim-engine", + "torch", + "torchvision", + "torchcodec", + "lerobot", + "numpy", + ): + try: + runtime_versions[name] = metadata.version(name) + except metadata.PackageNotFoundError: + runtime_versions[name] = None + output.mkdir(parents=True, exist_ok=True) + inputs = output / "inputs" + inputs.mkdir(exist_ok=True) + sources = dict(source_artifacts or {}) + derived = _prepare_deployment(deployment, inputs) + atomic_json(inputs / "expansion.json", options) + for path in (derived, inputs / "environment.yaml", inputs / "expansion.json"): + sources[f"derived_{path.name}"] = { + "path": str(path), + "sha256": file_digest(path), + } + groups = _run_operators( + derived, + output, + options, + selected, + seed=seed, + sources=sources, + viewer=view, + runtime_versions=runtime_versions, + ) + result = { + "complete": all(value.get("complete", False) for value in groups.values()), + "operators": groups, + "configuration_sha256": file_digest(configuration), + "viewer": view, + } + atomic_json(output / "expansion.json", result) + if not view["headless"]: + from .preview import launch_expansion_preview + + result["preview"] = launch_expansion_preview( + [ + Path(group["directory"]) + for group in groups.values() + if group.get("committed_episodes", 0) + ], + output=( + Path(preview_output) + if preview_output is not None + else output.parent / ".previews" / output.name + ), + open_browser=True, + max_episodes=64, + ) + atomic_json(output / "expansion.json", result) + return result diff --git a/tests/lab/expansion/fixtures/task_program_job.yaml b/tests/lab/expansion/fixtures/task_program_job.yaml new file mode 100644 index 0000000000..bd11a2db29 --- /dev/null +++ b/tests/lab/expansion/fixtures/task_program_job.yaml @@ -0,0 +1,48 @@ +schema_version: 1 +engine: + workload_count: 2 + batch_size: 1 + episodes_per_operator: 1 + max_attempts: 4 + max_steps: 3000 + max_wall_time_s: 240 + settling_steps: 5 + capture_media: false +scene: + cube: + translation_m: [[0.0, 0.0], [0.0, 0.0], [0.0, 0.0]] + yaw_rad: [0.0, 0.0] +trajectory: + operators: [object_pose, joint_residual] + joint_offset_scale: 0.0001 + via_count: 2 + max_proposals: 8 + minimum_joint_delta: 0.0000001 + velocity_limit: 10.0 + acceleration_limit: 100.0 + nullspace_task_rows: [0, 1, 2] + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: + pick_up: [approach] + place: [retract] +validation: + initial_checks: + - {kind: pose_near, entity: cube, position: [-0.42, -0.08, 0.025], tolerance_m: 0.08} + final_checks: &final + - {kind: pose_near, entity: cube, position: [-0.4, 0.48, 0.025], tolerance_m: 0.04} + - {kind: joint_range, joint: gripper_finger1_joint_1, lower: -0.001, upper: 0.005} + - {kind: speed_below, entity: cube, linear_m_s: 0.03, angular_rad_s: 0.2} + events: + - event_id: lift + conditions: + - {kind: lifted, entity: cube, height_m: 0.05} + - event_id: placed_and_released + conditions: *final + consecutive_steps: 3 + allowed_contacts: + - [cube, UR5/gripper_finger1_link_1] + - [cube, UR5/gripper_finger2_link_1] + - [cube, default_plane] + mounting_contacts: + - ['@root', default_plane] diff --git a/tests/lab/expansion/test_configured.py b/tests/lab/expansion/test_configured.py index fa77556963..332883b635 100644 --- a/tests/lab/expansion/test_configured.py +++ b/tests/lab/expansion/test_configured.py @@ -22,6 +22,33 @@ from embodichain.lab.expansion import ExpansionEngine, load_expansion_job +def test_task_program_declarations_are_pure_and_protect_contact_phases(tmp_path): + import json + import os + import subprocess + import sys + import yaml + from embodichain.lab.expansion import load_task_program_expansion + + path = Path(__file__).parent / "fixtures/task_program_job.yaml" + code = "from embodichain.lab.expansion import load_task_program_expansion; import json,sys; value=load_task_program_expansion(sys.argv[1]); assert not any(k=='dexsim' or k.startswith('dexsim.') for k in sys.modules); print(json.dumps(value))" + process = subprocess.run( + [sys.executable, "-c", code, str(path)], + capture_output=True, + text=True, + check=True, + env={**os.environ}, + ) + value = json.loads(process.stdout) + assert (value["engine"]["workload_count"], value["engine"]["batch_size"]) == (2, 1) + assert value["trajectory"]["operators"] == ["object_pose", "joint_residual"] + value["trajectory"]["free_phases"]["pick_up"] = ["approach", "lift"] + invalid = tmp_path / "protected.yaml" + invalid.write_text(yaml.safe_dump(value)) + with pytest.raises(ValueError, match="protected free phase"): + load_task_program_expansion(invalid) + + @pytest.mark.parametrize("name", ["default", "newton", "rgbd", "motion"]) def test_example_preflight_resolves_owned_backend_and_budget(name, tmp_path): path = ( diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index fe877ba1fe..b10b70d0ac 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -522,8 +522,38 @@ def validator(env, output): assert not SimulationManager._instances +def _declarative_probe(output: str) -> None: + import json + from embodichain.lab.expansion import ( + run_task_program_expansion, + ArtifactEpisodeSink, + load_expansion_episode, + ) + from embodichain.lab.sim import SimulationManager + + root = Path(__file__).resolve().parents[3] + result = run_task_program_expansion( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml", + Path(__file__).parent / "fixtures/task_program_job.yaml", + output, + ) + assert result["complete"], result + execution = json.loads((Path(output) / "workload-execution.json").read_text()) + assert execution["world"]["world_count"] == 1 and execution["num_envs"] == 2 + assert not SimulationManager._instances + for operator, group in result["operators"].items(): + receipts = ArtifactEpisodeSink(group["directory"]).inspect() + assert len(receipts) == len(group["lerobot"]["datasets"]) == 1 + episode = load_expansion_episode(receipts[0].storage_id) + assert episode.validation.accepted + assert len(episode.timestamps) == len(episode.actions) + 1 + if operator == "joint_residual": + assert episode.metadata["expansion"] + + @pytest.mark.requires_sim -@pytest.mark.parametrize("mode", ["executor", "facade"]) +@pytest.mark.parametrize("mode", ["executor", "facade", "declarative"]) def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path, mode): result = subprocess.run( [sys.executable, __file__, str(tmp_path), mode], @@ -537,6 +567,6 @@ def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path, m if __name__ == "__main__": - (_facade_probe if len(sys.argv) > 2 and sys.argv[2] == "facade" else _probe)( - sys.argv[1] - ) + {"executor": _probe, "facade": _facade_probe, "declarative": _declarative_probe}[ + sys.argv[2] if len(sys.argv) > 2 else "executor" + ](sys.argv[1]) From 722e385a0dfa7813cac92b6b61960939d887fa0c Mon Sep 17 00:00:00 2001 From: yuecideng Date: Mon, 16 Nov 2026 05:18:15 +0000 Subject: [PATCH 16/49] fix(sim): collect released native views before closing their scene Move the existing pre-Scene collection after clearing facade-owned data and entity references. Cyclic wrappers newly orphaned by those clears must finalize while their Scene and World parents are still alive, instead of being collected during a later teardown. Extend the existing deferred-destruction test with a cyclic view finalizer; both registry-ownership cases fail before the change. Keep backend synchronization, ownership checks, physical validation and GC count unchanged. Validation: 288 manager CPU tests passed; the full 149-node failed CI GPU shard passed 143 with 6 pre-existing capability skips on pinned DexSim 0.6.0rc2. Black 26.10.1, API docs 4963/4963, context and diff checks passed. Lifecycle context already requires child-before-parent cleanup and remains accurate. The reported native abort itself was not deterministic locally; this fixes the demonstrated lifetime gap at its cleanup boundary. --- embodichain/lab/sim/sim_manager.py | 11 +++++++---- tests/sim/test_sim_manager.py | 28 ++++++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/embodichain/lab/sim/sim_manager.py b/embodichain/lab/sim/sim_manager.py index bc6511173a..ad9948aafa 100644 --- a/embodichain/lab/sim/sim_manager.py +++ b/embodichain/lab/sim/sim_manager.py @@ -6558,10 +6558,6 @@ def _deferred_destroy(self) -> None: # Release backend-owned views before Scene closes the native # resources that back them. Newton also synchronizes its device here. self.physics.prepare_for_teardown() - # Run wrapper destructors while their World is still alive. The later - # collections continue to break cycles left by the native teardown. - gc.collect() - # Render-only cameras may be attached to Spawn articulation link # nodes. Remove their Arena views before closing Scene, which # releases those parent nodes, and before World.quit releases their @@ -6608,6 +6604,13 @@ def _deferred_destroy(self) -> None: asset._spawn_result = None if hasattr(asset, "_entities"): asset._entities = [] + + # Dropping facade references can make cyclic native views collectible. + # Run their finalizers now, while Scene/World parents are still alive; + # collecting before the clears would leave them for a later World. + gc.collect() + + if self._spawn_scene is not None: try: self._spawn_scene.close() finally: diff --git a/tests/sim/test_sim_manager.py b/tests/sim/test_sim_manager.py index bc0c8a8af3..6150778c92 100644 --- a/tests/sim/test_sim_manager.py +++ b/tests/sim/test_sim_manager.py @@ -20,6 +20,7 @@ import gc import queue import threading +import weakref from pathlib import Path @@ -606,7 +607,19 @@ def test_deferred_destroy_prepares_backend_before_releasing_world( ) sim._gizmos = {} sim._markers = {} - sim._rigid_objects = {} + + class CyclicView: + def __init__(self): + self.retained_view = self + + view = CyclicView() + released = weakref.finalize(view, events.append, "view_released") + sim._rigid_objects = { + "asset": SimpleNamespace( + _data=view, _entities=[view], _spawn_result=spawn_scene + ) + } + del view sim._constraints = {} sim._rigid_object_groups = {} sim._fluid_objects = {} @@ -638,10 +651,21 @@ def reset(instance_id): instances.pop(instance_id) monkeypatch.setattr(SimulationManager, "reset", reset) - monkeypatch.setattr(gc, "collect", lambda: events.append("gc_collect")) + collect = gc.collect + + def collect_views(): + events.append("gc_collect") + return collect() + + monkeypatch.setattr(gc, "collect", collect_views) sim._deferred_destroy() + # Clearing a facade can make its cyclic native views collectible. Their + # finalizers must run before the owning native Scene/World are closed. + assert not released.alive + assert events.index("backend_prepare") < events.index("view_released") + assert events.index("view_released") < events.index("spawn_close") assert events.index("backend_prepare") < events.index("gc_collect") assert events.index("backend_prepare") < events.index("spawn_close") assert events.index("backend_prepare") < events.index("world_quit") From f3e08ae6b6ea25e4f956ed15cbf0ae9148d7a684 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Mon, 16 Nov 2026 07:56:55 +0000 Subject: [PATCH 17/49] fix(expansion): address admission, acceptance and preview review findings Identify explicit references after aggregate expansion; round contact holds up to the control grid and verify measured elapsed time; resolve the default-plane actor only when enabled. Retire expired warming attempts without proposal/credit and allow active peers to drain and export, including expiry during initial validation. Reject incompatible expert command modes, ActionManager declarations and controlled-joint selections before constructing a World. Preserve component-owned resource paths when relocating deployment snapshots by reusing the component resolver's resource normalization. Add focused regressions and extend real workload integration with an expired group alongside a peer that commits and exports a receipt. Validation: 106 expansion unit tests, 4 native integration tests on pinned DexSim 0.6.0rc2, and 42 context tests passed. Regressions reproduce all six review findings against 722e385a0. Black 26.10.1, API docs 4963/4963 and diff checks passed. Update workload guidance for action-schema compatibility and admission expiry. --- .../topics/expansion-engine/workloads.md | 10 +- embodichain/lab/expansion/_preview_data.py | 3 +- embodichain/lab/expansion/acceptance.py | 22 +- embodichain/lab/expansion/gym_workloads.py | 56 +++- .../lab/expansion/task_program_jobs.py | 8 +- embodichain/lab/expansion/workloads.py | 23 +- tests/lab/expansion/test_acceptance.py | 142 ++++++++++ tests/lab/expansion/test_configured.py | 40 +++ tests/lab/expansion/test_gym_workloads.py | 245 ++++++++++++++++++ tests/lab/expansion/test_preview.py | 42 +++ tests/lab/expansion/test_workloads_sim.py | 53 ++++ 11 files changed, 620 insertions(+), 24 deletions(-) create mode 100644 tests/lab/expansion/test_acceptance.py create mode 100644 tests/lab/expansion/test_gym_workloads.py diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 18664b4b9e..dd2c4d1440 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -42,7 +42,9 @@ independent collection budget, artifacts and row callbacks. The facade opens one World, captures the original seeded nominal scene in row zero, and composes the existing session, frame collector, episode assembler and confirmed artifact sink. Different integration/grasp policies may share that World only when their -physical configuration, program and cadence agree. Physical/visual/prototype +physical configuration, program, cadence and expert action schema agree. +Command mode, ActionManager declarations and controlled-joint selections cannot +vary between workloads in one World. Physical/visual/prototype operators remain on the cohort API; unsupported payloads fail explicitly. Explicit contact sampling conventions may differ per integration through `SimulationTaskProgramAdapterFactory.create_adapter(grasp_contact_frames=...)`; @@ -63,7 +65,11 @@ After at least the declared physical settling substeps, `activate` captures the initial measured boundary, performs the source's required preparation checks, registers a native candidate and uses `ExpansionEngine.admit_row`. It returns a fresh bridge bound exactly to that row and the environment's control cadence. -Rejected preparation returns None and never earns quota. +Rejected preparation returns None and never earns quota. A warming row whose +admission time budget expires is retired without proposal or receipt; its group +can finish incomplete while already-admitted peers continue and export normally. +The native source also handles expiry during initial-state validation before +atomic session proposal. `started` calls `mark_row_started` after the first actual command. `observe` captures every active T+1 boundary and performs the original physical checks; diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py index 1d65e19715..2fa9ce66d0 100644 --- a/embodichain/lab/expansion/_preview_data.py +++ b/embodichain/lab/expansion/_preview_data.py @@ -331,6 +331,7 @@ def load_preview( ground = True seen = set() frames = 0 + reference_index = len(paths) - 1 if reference is not None else None for group, path in enumerate(paths): job_path = path / "job.json" if not job_path.is_file(): @@ -382,7 +383,7 @@ def load_preview( ): raise ValueError("Outputs disagree about ground visibility") receipts = [r for r in ArtifactEpisodeSink(path).inspect() if r.confirmed] - is_reference = reference is not None and group == len(outputs) + is_reference = group == reference_index if not receipts or (is_reference and len(receipts) != 1): raise ValueError( "Each output needs confirmed episodes; reference must contain exactly one" diff --git a/embodichain/lab/expansion/acceptance.py b/embodichain/lab/expansion/acceptance.py index 71e8220df4..805d05fd79 100644 --- a/embodichain/lab/expansion/acceptance.py +++ b/embodichain/lab/expansion/acceptance.py @@ -24,6 +24,7 @@ from collections.abc import Mapping, Sequence from types import SimpleNamespace import xml.etree.ElementTree as ET +import math import numpy as np import torch from embodichain.data_pipeline.recording.media import _atomic_json as atomic_json @@ -268,7 +269,7 @@ def __init__(self, env, configuration, output, *, sensor, env_id=0): ) self.hold = configuration.get("contact_hold") count = ( - round(self.hold["duration_s"] * env.control_frequency) + 1 + math.ceil(self.hold["duration_s"] * env.control_frequency) + 1 if self.hold else 1 ) @@ -282,7 +283,10 @@ def __init__(self, env, configuration, output, *, sensor, env_id=0): ].tolist(), ): self.frames[actor] = f"{env.robot.uid}/{link}" - for uid in (*env.sim.get_rigid_object_uid_list(), "default_plane"): + objects = list(env.sim.get_rigid_object_uid_list()) + if env.sim.sim_config.enable_ground_plane: + objects.append("default_plane") + for uid in objects: self.frames[int(self.sensor.get_actor_ids(uid)[self.env_id, 0])] = uid ignored, allowed = self.contact_permissions( env, configuration, set(self.frames.values()) @@ -334,6 +338,10 @@ def _hold_report(self): } if len(self.samples) != self.samples.maxlen: return {**report, "passed": False} + elapsed = self.samples[-1][2] - self.samples[0][2] + report.update( + elapsed_duration_s=elapsed, required_duration_s=self.hold["duration_s"] + ) poses = np.asarray([sample[0] for sample in self.samples]) from scipy.spatial.transform import Rotation @@ -348,7 +356,13 @@ def _hold_report(self): ), ) report["passed"] = ( - report["both_fingers_samples"] == self.samples.maxlen + ( + elapsed >= self.hold["duration_s"] + or math.isclose( + elapsed, self.hold["duration_s"], rel_tol=1e-12, abs_tol=1e-12 + ) + ) + and report["both_fingers_samples"] == self.samples.maxlen and report["max_translation_drift_m"] <= self.hold["max_translation_drift_m"] and report["max_rotation_drift_rad"] <= self.hold["max_rotation_drift_rad"] @@ -392,7 +406,7 @@ def sample(self, ids, action, snapshot=None): .get_local_pose()[self.env_id] .tolist() ) - self.samples.append((pose, touching)) + self.samples.append((pose, touching, self.env.sim.simulation_time)) report = ( self._hold_report() if terminal.accepted diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index f7e8e56708..f6690cbddd 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -191,6 +191,11 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: host, engine = group["host"], group["engine"] ctx = host._context request = ctx.requests[row] + if group["session"].stop_reason == "wall_time_exhausted": + ctx.journal.update( + request, status="initial_rejected", reason="wall_time_exhausted" + ) + return None if self.activation_snapshot is None: self.activation_snapshot = ( capture_state(ctx.view), @@ -243,15 +248,25 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: ) session = group["session"] session.register_case(case, ctx.limits, joint_names=ctx.names) - identity, _ = session.propose( - case.scene_case_id, - initial_id, - source_id=ctx.program.program_id, - source_revision=ctx.report["recipe_revision"], - template_id=request.recipe.recipe_id, - operator_id="episode", - attempt_id=request.attempt_id, - ) + try: + identity, _ = session.propose( + case.scene_case_id, + initial_id, + source_id=ctx.program.program_id, + source_revision=ctx.report["recipe_revision"], + template_id=request.recipe.recipe_id, + operator_id="episode", + attempt_id=request.attempt_id, + ) + except RuntimeError: + # The budget can expire during initial-state validation, including + # between the early check and the session's atomic proposal guard. + if session.stop_reason != "wall_time_exhausted": + raise + ctx.journal.update( + request, status="initial_rejected", reason="wall_time_exhausted" + ) + return None episode_id, commit_id = session.episode_ids(identity) record = ctx.journal.update( request, @@ -360,6 +375,13 @@ def complete(self, result: WorkloadRowResult) -> Any: row = result.assignment.env_id state = self.active.pop(row, None) if state is None: + ctx = self.groups[result.assignment.workload_id]["host"]._context + if result.program.reasons == ("wall_time_exhausted",): + ctx.journal.update( + ctx.requests[row], + status="initial_rejected", + reason="wall_time_exhausted", + ) return None group = state["group"] ctx = group["host"]._context @@ -584,6 +606,8 @@ def physical_key(cfg: Any) -> str: "sim_steps_per_control", "events", "sensor", + "expert_trajectory", + "actions", ) if hasattr(cfg, name) } @@ -591,9 +615,21 @@ def physical_key(cfg: Any) -> str: if any(physical_key(cfg) != physical_key(first) for _, cfg in configs[1:]): raise ValueError( - "workloads must share physical environment, robot, sensors and cadence" + "workloads must share physical environment, robot, sensors, cadence and expert action schema" ) + def control_schema(raw: Mapping[str, Any]) -> tuple: + cls = REGISTERED_ENVS[raw["id"]].cls + return ( + tuple(getattr(cls, "control_parts", None) or ()), + tuple(getattr(cls, "active_joint_ids", ())), + ) + + if any( + control_schema(raw) != control_schema(configs[0][0]) for raw, _ in configs[1:] + ): + raise ValueError("workloads must share the expert controlled-joint schema") + owner = source = None groups: dict[str, Any] = {} adapters: dict[int, Any] = {} diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index d32682ad68..4576457c4f 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -188,7 +188,13 @@ def paths(value): snapshot = paths(deepcopy(original)) owner = "environment" if "environment" in snapshot else "scene" if "component" in snapshot[owner]: - physical = load_mapping(Path(snapshot[owner]["component"])) + from embodichain.lab.gym.utils._component_composition import ( + _resolve_local_resource_paths, + ) + + component_path = Path(snapshot[owner]["component"]) + physical = load_mapping(component_path) + _resolve_local_resource_paths(physical, base_dir=component_path.parent) snapshot[owner] = {"component": str((output / "environment.yaml").resolve())} else: from embodichain.lab.gym.utils.composition import resolve_gym_components diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index 4ecdc9afcb..89fca5bd4c 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -376,16 +376,27 @@ def _activate(self) -> None: for row in tuple(self.warming): state = self.warming[row] - if state["settled"] < self.cfg.settling_steps: - continue assignment = state["assignment"] - self.env._elapsed_steps[row] = 0 - self.env._reset_physical_objective((row,)) - bridge = self.source.activate(assignment, self.observation) + expired = ( + time.monotonic() - self.started_at[assignment.workload_id] + >= self.workloads[assignment.workload_id].max_wall_time_s + ) + if state["settled"] < self.cfg.settling_steps and not expired: + continue + if expired: + bridge = None + else: + self.env._elapsed_steps[row] = 0 + self.env._reset_physical_objective((row,)) + bridge = self.source.activate(assignment, self.observation) del self.warming[row] if bridge is None: outcome = ProgramBatchResult( - (row,), (0,), (False,), ("preparation_rejected",), ((),) + (row,), + (0,), + (False,), + ("wall_time_exhausted" if expired else "preparation_rejected",), + ((),), ) if ( self.source.complete( diff --git a/tests/lab/expansion/test_acceptance.py b/tests/lab/expansion/test_acceptance.py new file mode 100644 index 0000000000..2653b21f21 --- /dev/null +++ b/tests/lab/expansion/test_acceptance.py @@ -0,0 +1,142 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Measured acceptance boundaries without native simulation resources.""" + +from __future__ import annotations + +from types import SimpleNamespace +import pytest +import torch +from embodichain.lab.expansion.acceptance import _ContactRow + +pytestmark = pytest.mark.no_sim + + +@pytest.fixture +def contact_row(tmp_path): + def build(duration=0.25, ground=False): + asset = tmp_path / "robot.urdf" + asset.write_text( + '' + ) + actors = {"table": 10, "book": 11} + if ground: + actors["default_plane"] = 12 + + def actor_ids(uid, links=None): + if uid == "robot": + ids = {"root": 1, "left": 2, "right": 3} + return torch.tensor([[ids[link] for link in links]]) + return torch.tensor([[actors[uid]]]) + + sensor = SimpleNamespace(get_actor_ids=actor_ids) + env = SimpleNamespace( + control_frequency=10, + robot=SimpleNamespace( + uid="robot", + link_names=["root", "left", "right"], + cfg=SimpleNamespace( + fpath=str(asset), + root_props=SimpleNamespace(self_collision_enabled=True), + ), + ), + sim=SimpleNamespace( + sim_config=SimpleNamespace(enable_ground_plane=ground), + get_rigid_object_uid_list=lambda: ["table", "book"], + get_rigid_object=lambda uid: SimpleNamespace( + body_type="dynamic" if uid == "book" else "static" + ), + ), + ) + cfg = { + "initial_checks": [], + "mounting_contacts": [], + "allowed_contacts": [], + "events": [], + "final_checks": [ + {"kind": "joint_range", "joint": "j", "lower": -1, "upper": 1} + ], + "contact_hold": { + "entity": "book", + "links": ["left", "right"], + "duration_s": duration, + "max_translation_drift_m": 0.001, + "max_rotation_drift_rad": 0.001, + }, + } + return _ContactRow(env, cfg, tmp_path, sensor=sensor) + + return build + + +@pytest.mark.parametrize("duration,required", [(0.25, 4), (0.025, 2), (0.3, 4)]) +def test_contact_hold_requires_full_duration_and_distinct_measured_times( + contact_row, duration, required +): + row = contact_row(duration, ground=True) + pose = [0, 0, 0, 0, 0, 0, 1] + for i in range(required - 1): + row.samples.append((pose.copy(), [True, True], i / 10)) + assert not row._hold_report()["passed"] + row.samples.append((pose.copy(), [True, True], (required - 1) / 10)) + report = row._hold_report() + assert report["passed"] + assert report["elapsed_duration_s"] >= duration + assert row.samples.maxlen == required + # Enough samples at one physical instant cannot establish a hold duration. + row.samples.clear() + row.samples.extend((pose.copy(), [True, True], 0.0) for _ in range(required)) + assert not row._hold_report()["passed"] + row.samples.clear() + row.samples.extend((pose.copy(), [True, True], i / 10) for i in range(required)) + row.samples[-1][1][0] = False + assert not row._hold_report()["passed"] + row.samples[-1][1][0] = True + row.samples[-1][0][0] = 0.1 + assert not row._hold_report()["passed"] + + +@pytest.mark.parametrize("ground", [False, True]) +def test_native_contacts_only_resolve_present_default_plane(contact_row, ground): + row = contact_row(ground=ground) + assert {"table", "book", "robot/root", "robot/left", "robot/right"} <= set( + row.frames.values() + ) + assert ("default_plane" in row.frames.values()) is ground + + +def test_contact_sampling_uses_measured_world_time(contact_row): + from unittest.mock import Mock + from embodichain.lab.expansion.contracts import ValidationCheck, ValidationResult + + row = contact_row(ground=True) + passed = ValidationResult((ValidationCheck("task.success", "passed"),)) + row.monitor = SimpleNamespace(observe=Mock(), validation=lambda env: passed) + row.env.sim.get_rigid_object = lambda uid: SimpleNamespace( + get_local_pose=lambda: torch.tensor([[0.0, 0, 0, 0, 0, 0, 1]]) + ) + row.sensor.get_data = lambda: { + "user_ids": torch.tensor([[[11, 2], [11, 3]]]), + "is_valid": torch.ones((1, 2), dtype=torch.bool), + "impulse_valid": torch.ones((1, 2), dtype=torch.bool), + } + for timestamp, accepted in ((0.0, False), (0.1, False), (0.2, False), (0.3, True)): + row.env.sim.simulation_time = timestamp + row._interval_samples = 1 + row.sample((0,), None) + assert row.terminal[0].accepted is accepted + assert row._hold_report()["elapsed_duration_s"] == 0.3 diff --git a/tests/lab/expansion/test_configured.py b/tests/lab/expansion/test_configured.py index 332883b635..94bb78c69f 100644 --- a/tests/lab/expansion/test_configured.py +++ b/tests/lab/expansion/test_configured.py @@ -96,3 +96,43 @@ def test_resource_changes_preserve_semantics_but_record_new_execution(tmp_path): assert a["execution_id"] != b["execution_id"] cfg.mass_scale = {"cube": (2.0, 3.0)} assert preflight_expansion_job(cfg)["semantic_id"] != a["semantic_id"] + + +@pytest.mark.parametrize("owner", ["environment", "scene"]) +def test_deployment_snapshot_preserves_component_relative_assets(tmp_path, owner): + import json + import yaml + from embodichain.lab.expansion.task_program_jobs import _prepare_deployment + from embodichain.lab.gym.utils.composition import resolve_gym_components + + source = tmp_path / "source" + source.mkdir() + mesh = source / "mesh.obj" + mesh.write_text("v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n") + simulation = { + "rigid_object": [ + {"uid": "mesh", "shape": {"shape_type": "Mesh", "fpath": "./mesh.obj"}} + ] + } + component = ( + { + "environment_id": "mesh-test", + "physics": "default", + "simulation": simulation, + "env": {}, + } + if owner == "environment" + else {"scene_id": "mesh-test", "simulation": simulation} + ) + (source / "component.yaml").write_text(yaml.safe_dump(component)) + declaration = {"id": "SnapshotTest-v1", owner: {"component": "component.yaml"}} + deployment = source / "deployment.yaml" + deployment.write_text(yaml.safe_dump(declaration)) + before = {p.name: p.read_bytes() for p in source.iterdir()} + output = tmp_path / "output" + output.mkdir() + derived = _prepare_deployment(deployment, output) + snapshot = json.loads(derived.read_text()) + resolved = resolve_gym_components(snapshot, base_dir=derived.parent).config + assert resolved["rigid_object"][0]["shape"]["fpath"] == str(mesh) + assert {p.name: p.read_bytes() for p in source.iterdir()} == before diff --git a/tests/lab/expansion/test_gym_workloads.py b/tests/lab/expansion/test_gym_workloads.py new file mode 100644 index 0000000000..44abf5ab6f --- /dev/null +++ b/tests/lab/expansion/test_gym_workloads.py @@ -0,0 +1,245 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Workload admission and action-schema compatibility boundaries.""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import Mock +import hashlib +import json +import pytest +import torch +from embodichain.lab.expansion.gym_workloads import ( + _GymWorkloadSource, + GymExpansionWorkload, + run_gym_expansion_workloads, +) +from embodichain.lab.expansion.workloads import ( + ExpansionWorkloadCfg, + WorkloadExecutionCfg, + WorkloadAssignment, + WorkloadProgramExecutor, +) + +pytestmark = pytest.mark.no_sim + + +@pytest.mark.parametrize("settled", [0, 5]) +def test_expired_warming_row_finishes_group_without_disturbing_live_peer( + monkeypatch, settled +): + monkeypatch.setattr( + "embodichain.lab.expansion.workloads.time.monotonic", lambda: 1.0 + ) + executor = object.__new__(WorkloadProgramExecutor) + executor.cfg = WorkloadExecutionCfg( + workload_count=2, batch_size=1, settling_steps=5 + ) + executor.workloads = { + name: ExpansionWorkloadCfg(name, 1, 1, budget) + for name, budget in (("expired", 0.01), ("peer", 10)) + } + executor.started_at = {"expired": 0.0, "peer": 0.0} + executor.counts = { + name: {"attempts": 1, "rollouts": 0, "committed": 0} + for name in executor.workloads + } + executor.warming = { + 0: {"assignment": WorkloadAssignment("expired", 0, 0, 0), "settled": settled} + } + peer = {"assignment": WorkloadAssignment("peer", 0, 1, 0)} + executor.live = {1: peer} + executor.lanes, executor.completed = ["expired", "peer"], set() + executor.on_workload_done = Mock() + executor.source = SimpleNamespace(activate=Mock(), complete=Mock(return_value=None)) + executor._activate() + assert executor.warming == {} + assert executor.live[1] is peer + executor.source.activate.assert_not_called() + result = executor.source.complete.call_args.args[0] + assert result.program.reasons == ("wall_time_exhausted",) + assert result.world_control_start is result.world_control_end is None + executor._fill() + executor.on_workload_done.assert_called_once_with( + "expired", executor.counts["expired"] + ) + assert executor.live[1] is peer + + +def test_native_source_retires_expired_attempt_before_reading_world(): + from embodichain.lab.expansion.session import ExpansionSession + from embodichain.lab.expansion.session_cfg import ExpansionSessionCfg + + clock = [0.0] + session = ExpansionSession( + ExpansionSessionCfg.from_mapping({"collection": {"max_wall_time_s": 0.01}}), + clock=lambda: clock[0], + ) + clock[0] = 1.0 + request = object() + journal = Mock() + ctx = SimpleNamespace(requests={0: request}, journal=journal) + source = object.__new__(_GymWorkloadSource) + source.groups = { + "expired": { + "host": SimpleNamespace(_context=ctx), + "engine": object(), + "session": session, + } + } + assert source.activate(WorkloadAssignment("expired", 0, 0, 0), None) is None + journal.update.assert_called_once_with( + request, status="initial_rejected", reason="wall_time_exhausted" + ) + assert session.snapshot()["counts"]["proposed"] == 0 + + +@pytest.mark.parametrize("stop", ["wall_time_exhausted", "unexpected"]) +def test_admission_expiry_race_only_suppresses_budget_exhaustion(stop): + session = SimpleNamespace(stop_reason=None, register_case=Mock()) + + def propose(*args, **kwargs): + session.stop_reason = stop + raise RuntimeError("proposal failed") + + session.propose = propose + request = SimpleNamespace( + recipe=SimpleNamespace( + recipe_id="recipe", + operations=[SimpleNamespace(name="physical_parameters", payload_json="{}")], + ), + attempt_id=0, + ) + ctx = SimpleNamespace( + requests={0: request}, + journal=Mock(), + collision=None, + report={"semantic_id": "semantic", "recipe_revision": "revision"}, + cfg=SimpleNamespace(seed=0, source="task_program"), + compatibility=SimpleNamespace(key="compatible"), + program=SimpleNamespace(program_id="program"), + limits=object(), + names=("joint",), + ) + source = object.__new__(_GymWorkloadSource) + source.groups = { + "group": { + "host": SimpleNamespace(_context=ctx), + "engine": object(), + "session": session, + } + } + source.activation_snapshot = (SimpleNamespace(batches={0: ()}), {}) + source.env = SimpleNamespace(robot=SimpleNamespace(uid="robot")) + assignment = WorkloadAssignment("group", 0, 0, 0) + if stop == "wall_time_exhausted": + assert source.activate(assignment, None) is None + assert ctx.journal.update.call_args.kwargs["reason"] == stop + else: + with pytest.raises(RuntimeError, match="proposal failed"): + source.activate(assignment, None) + ctx.journal.update.assert_not_called() + + +@pytest.mark.parametrize( + "difference", [None, "position_velocity", "use_action_manager", "joint_selection"] +) +def test_workload_action_schema_checked_before_constructing_world( + tmp_path, monkeypatch, difference +): + from embodichain.lab.expansion import ExpansionRunCfg + from embodichain.lab.gym.envs.expert_trajectory import ExpertTrajectoryCfg + from embodichain.lab.gym.utils.registration import REGISTERED_ENVS + import embodichain.lab.gym.utils.gym_utils as utils + import embodichain.lab.expansion.host as host + + class ReachedWorld(Exception): + pass + + factory = Mock(side_effect=ReachedWorld) + monkeypatch.setattr(host, "GymExpansionHost", factory) + workloads, configs = [], {} + for i, name in enumerate(("first", "second")): + deployment = tmp_path / f"{name}.json" + deployment.write_text(json.dumps({"id": name})) + expert = ExpertTrajectoryCfg( + joint_command_mode=( + "position_velocity" + if i and difference == "position_velocity" + else "position" + ), + use_action_manager=bool(i and difference == "use_action_manager"), + ) + configs[name] = SimpleNamespace( + robot=SimpleNamespace( + to_dict=lambda: { + "joint_names": ["a", "b"], + "control_parts": {"arm": [0, 1]}, + } + ), + expert_trajectory=expert, + ) + cls = type( + f"Env{i}", + (), + { + "control_parts": ["arm"], + "active_joint_ids": ( + [1] if i and difference == "joint_selection" else [0] + ), + }, + ) + monkeypatch.setitem(REGISTERED_ENVS, name, SimpleNamespace(cls=cls)) + cfg = ExpansionRunCfg( + deployment=str(deployment), + output_dir=str(tmp_path / name), + max_steps=20, + settling_steps=1, + ) + workloads.append( + GymExpansionWorkload( + name, + cfg, + { + "input_files": { + "deployment": hashlib.sha256( + deployment.read_bytes() + ).hexdigest() + } + }, + {}, + ) + ) + monkeypatch.setattr( + utils, "config_to_cfg", lambda raw, **kwargs: configs[raw["id"]] + ) + execution = WorkloadExecutionCfg( + workload_count=2, batch_size=1, max_steps=20, settling_steps=1 + ) + if difference is None: + with pytest.raises(ReachedWorld): + run_gym_expansion_workloads( + workloads, execution, output_dir=tmp_path / "run" + ) + factory.assert_called_once() + else: + with pytest.raises(ValueError, match="schema"): + run_gym_expansion_workloads( + workloads, execution, output_dir=tmp_path / "run" + ) + factory.assert_not_called() diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 32d58e9214..1c9054d10a 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -414,3 +414,45 @@ def test_row_identity_without_motion_and_legacy_ambiguity(recorded_job): result = annotations(metadata, measured) np.testing.assert_allclose(result["targets"][0, :3, 3], [12, 20, 0]) assert result["candidate_ids"] == ("31",) + + +@pytest.mark.parametrize("second_count", [1, 2]) +def test_aggregate_input_keeps_explicit_reference_separate(recorded_job, second_count): + path, job, episode = recorded_job + root = path.parent + directories = [] + for name, count in (("first", 1), ("second", second_count), ("reference", 1)): + directory = root / name + directory.mkdir() + (directory / "job.json").write_text(json.dumps(job)) + for index in range(count): + ArtifactEpisodeSink(directory).submit( + replace( + episode, + episode_id=f"{name}-{index}", + commit_id=f"{name}-commit-{index}", + ), + submission_id=index, + ) + directories.append(directory) + aggregate = root / "aggregate" + aggregate.mkdir() + (aggregate / "expansion.json").write_text( + json.dumps( + { + "operators": { + str(i): { + "directory": str(p), + "committed_episodes": 1 if i == 0 else second_count, + } + for i, p in enumerate(directories[:2]) + } + } + ) + ) + data = load_preview( + [aggregate], reference=directories[2], max_episodes=1 + second_count + ) + assert len(data.clips) == 1 + second_count + assert data.reference.space.endswith("reference") + assert all(not clip.space.endswith("reference") for clip in data.clips) diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index b10b70d0ac..eb457d8e5b 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -521,6 +521,59 @@ def validator(env, output): ) assert not SimulationManager._instances + # Expiry during settling retires only the unstarted group. A peer must + # still collect/export a real receipt, and the aggregate stays incomplete. + from dataclasses import replace + + budget_groups = [ + replace( + workloads[0], + workload_id=name, + cfg=ExpansionRunCfg( + **{ + **workloads[0].cfg.to_dict(), + "output_dir": str(path / name), + "target_episodes": 1, + "max_attempts": 1, + "max_wall_time_s": budget, + } + ), + ) + for name, budget in (("expired", 1e-9), ("peer", 240.0)) + ] + budget_result = run_gym_expansion_workloads( + budget_groups, + WorkloadExecutionCfg( + workload_count=2, batch_size=1, max_steps=2500, settling_steps=5 + ), + extensions=GymExpansionHostExtensions( + validator_factory=lambda env, output: _MeasuredCollision( + env, + str( + root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml" + ), + output, + ) + ), + output_dir=path / "budget-execution", + ) + assert not budget_result["complete"] + assert budget_result["counts"]["expired"] == { + "attempts": 1, + "rollouts": 0, + "committed": 0, + } + assert budget_result["workloads"]["peer"]["complete"] + assert len(ArtifactEpisodeSink(path / "peer").inspect()) == 1 + assert len(budget_result["workloads"]["peer"]["lerobot"]["datasets"]) == 1 + assert not ArtifactEpisodeSink(path / "expired").inspect() + records = list((path / "expired" / "attempts").glob("*/attempt.json")) + assert len(records) == 1 + expired_record = json.loads(records[0].read_text()) + assert expired_record["status"] == "initial_rejected" + assert expired_record["reason"] == "wall_time_exhausted" + assert not SimulationManager._instances + def _declarative_probe(output: str) -> None: import json From 2dfcbed03f614ec74bba7f84ef8d2e84e05c4cb7 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Mon, 16 Nov 2026 10:55:52 +0000 Subject: [PATCH 18/49] fix(expansion): stabilize hold timing and joint selection checks Normalize ULP-scale error in exact-grid hold durations before ceiling. Measure hold elapsed time with bounded fsum reductions of actual physics callback intervals instead of subtracting accumulated World clocks. Preserve distinct samples, upward rounding of real off-grid durations, both-finger contact and drift requirements. Compare control_parts and active_joint_ids from resolved environment configurations rather than their shared implementation class. Replace artificial-class coverage with real decoded configurations and a full deployment-file regression sharing ordinary EmbodiedEnv. Validation: 117 expansion unit tests, four native integration tests on pinned DexSim 0.6.0rc2 and 42 context tests passed. Regressions reproduce all three follow-up findings on 8c244cdc9, including 50 Hz/100 Hz boundary holds, 500k/5M-step clock accumulation, truly short windows and pre-World schema rejection. Black 26.10.1, API docs 5010/5010, context map and diff checks passed. Update context for measured hold timing and configuration-owned joint selections. --- .../expansion-engine/expansion-engine.md | 5 +- .../topics/expansion-engine/workloads.md | 3 +- embodichain/lab/expansion/acceptance.py | 41 ++++- embodichain/lab/expansion/gym_workloads.py | 14 +- tests/lab/expansion/test_acceptance.py | 171 +++++++++++++----- .../lab/expansion/test_extension_ports_sim.py | 18 +- tests/lab/expansion/test_gym_workloads.py | 120 +++++++++--- 7 files changed, 283 insertions(+), 89 deletions(-) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index f1fb5fd569..79a12efc97 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -46,7 +46,10 @@ configured jobs. `sampled_rigid_v1` collision profiles independently check all physical box/plane scene bodies and task predicates from measured states. Their robot-base transforms are rebound after each cohort's scene preparation. State-only jobs retain independent and robot-mounted ContactSensors while -omitting cameras; contact acquisition does not require media capture. +omitting cameras; contact acquisition does not require media capture. Sustained +contact windows round off-grid durations upward, allowing only ULP-scale grid +roundoff. Their elapsed time sums measured physics intervals within the bounded +window; it does not subtract accumulated World clocks. Immutable recipes declare source/backend/phase/scope and shared-resource compatibility; the host checks them before mutating the World. diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index dd2c4d1440..c22d2af281 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -44,7 +44,8 @@ existing session, frame collector, episode assembler and confirmed artifact sink Different integration/grasp policies may share that World only when their physical configuration, program, cadence and expert action schema agree. Command mode, ActionManager declarations and controlled-joint selections cannot -vary between workloads in one World. Physical/visual/prototype +vary between workloads in one World. Selections belong to the resolved environment +configurations, not the shared registered environment implementation class. Physical/visual/prototype operators remain on the cohort API; unsupported payloads fail explicitly. Explicit contact sampling conventions may differ per integration through `SimulationTaskProgramAdapterFactory.create_adapter(grasp_contact_frames=...)`; diff --git a/embodichain/lab/expansion/acceptance.py b/embodichain/lab/expansion/acceptance.py index 805d05fd79..03ec618bbe 100644 --- a/embodichain/lab/expansion/acceptance.py +++ b/embodichain/lab/expansion/acceptance.py @@ -19,6 +19,7 @@ from __future__ import annotations from collections import deque +from itertools import islice from pathlib import Path from typing import Any, TYPE_CHECKING from collections.abc import Mapping, Sequence @@ -268,12 +269,18 @@ def __init__(self, env, configuration, output, *, sensor, env_id=0): 0, ) self.hold = configuration.get("contact_hold") - count = ( - math.ceil(self.hold["duration_s"] * env.control_frequency) + 1 - if self.hold - else 1 - ) + count = 1 + if self.hold: + intervals = self.hold["duration_s"] * env.control_frequency + nearest = round(intervals) + # Multiplication can place an exact grid duration just above an + # integer (e.g. 0.14 * 50). Only normalize floating-point roundoff; + # genuinely off-grid holds still round upward. + if abs(intervals - nearest) <= 2 * math.ulp(intervals): + intervals = nearest + count = max(1, math.ceil(intervals)) + 1 self.samples = deque(maxlen=count) + self._interval_dts: list[float] = [] self.sensor = sensor self.frames = {} for link, actor in zip( @@ -317,6 +324,7 @@ def reset(self, env_ids=None): 0, ) self.samples.clear() + self._interval_dts.clear() def prepare(self, snapshot=None): super().prepare(snapshot) @@ -326,6 +334,7 @@ def prepare(self, snapshot=None): def begin_control_step(self): self._bad = None self._interval_samples = 0 + self._interval_dts.clear() def before_sample(self): return None @@ -338,7 +347,10 @@ def _hold_report(self): } if len(self.samples) != self.samples.maxlen: return {**report, "passed": False} - elapsed = self.samples[-1][2] - self.samples[0][2] + # The first pose starts the hold; count only subsequent measured + # physics intervals. Bounded-window fsum avoids subtracting accumulated + # World clocks, whose rounding error grows throughout a collection. + elapsed = math.fsum(sample[2] for sample in islice(self.samples, 1, None)) report.update( elapsed_duration_s=elapsed, required_duration_s=self.hold["duration_s"] ) @@ -357,9 +369,15 @@ def _hold_report(self): ) report["passed"] = ( ( - elapsed >= self.hold["duration_s"] - or math.isclose( - elapsed, self.hold["duration_s"], rel_tol=1e-12, abs_tol=1e-12 + elapsed > 0 + and ( + elapsed >= self.hold["duration_s"] + or math.isclose( + elapsed, + self.hold["duration_s"], + rel_tol=0, + abs_tol=2 * math.ulp(self.hold["duration_s"]), + ) ) ) and report["both_fingers_samples"] == self.samples.maxlen @@ -406,7 +424,8 @@ def sample(self, ids, action, snapshot=None): .get_local_pose()[self.env_id] .tolist() ) - self.samples.append((pose, touching, self.env.sim.simulation_time)) + self.samples.append((pose, touching, math.fsum(self._interval_dts))) + self._interval_dts.clear() report = ( self._hold_report() if terminal.accepted @@ -586,6 +605,8 @@ def after_sample(self, dt: float, token: object) -> None: for check in active: check.substeps += 1 check._interval_samples += 1 + if check.hold: + check._interval_dts.append(dt) code, actor_a, actor_b = summaries[check.env_id] if code: check._bad = f"native contact evidence rejected: code={code}; actors={actor_a},{actor_b}" diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index f6690cbddd..98616ebe46 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -608,6 +608,8 @@ def physical_key(cfg: Any) -> str: "sensor", "expert_trajectory", "actions", + "control_parts", + "active_joint_ids", ) if hasattr(cfg, name) } @@ -618,18 +620,6 @@ def physical_key(cfg: Any) -> str: "workloads must share physical environment, robot, sensors, cadence and expert action schema" ) - def control_schema(raw: Mapping[str, Any]) -> tuple: - cls = REGISTERED_ENVS[raw["id"]].cls - return ( - tuple(getattr(cls, "control_parts", None) or ()), - tuple(getattr(cls, "active_joint_ids", ())), - ) - - if any( - control_schema(raw) != control_schema(configs[0][0]) for raw, _ in configs[1:] - ): - raise ValueError("workloads must share the expert controlled-joint schema") - owner = source = None groups: dict[str, Any] = {} adapters: dict[int, Any] = {} diff --git a/tests/lab/expansion/test_acceptance.py b/tests/lab/expansion/test_acceptance.py index 2653b21f21..bfb1e65a73 100644 --- a/tests/lab/expansion/test_acceptance.py +++ b/tests/lab/expansion/test_acceptance.py @@ -28,7 +28,7 @@ @pytest.fixture def contact_row(tmp_path): - def build(duration=0.25, ground=False): + def build(duration=0.25, ground=False, frequency=10): asset = tmp_path / "robot.urdf" asset.write_text( '' @@ -45,7 +45,7 @@ def actor_ids(uid, links=None): sensor = SimpleNamespace(get_actor_ids=actor_ids) env = SimpleNamespace( - control_frequency=10, + control_frequency=frequency, robot=SimpleNamespace( uid="robot", link_names=["root", "left", "right"], @@ -83,31 +83,96 @@ def actor_ids(uid, links=None): return build -@pytest.mark.parametrize("duration,required", [(0.25, 4), (0.025, 2), (0.3, 4)]) +@pytest.fixture +def sample_contacts(): + """Feed the production observer/sample boundary using explicit physics intervals.""" + from unittest.mock import Mock + from embodichain.lab.expansion.acceptance import MeasuredExpansionValidator + from embodichain.lab.expansion.contracts import ValidationCheck, ValidationResult + + def build(row): + passed = ValidationResult((ValidationCheck("task.success", "passed"),)) + row.monitor = SimpleNamespace(observe=Mock(), validation=lambda env: passed) + row.active = True + state = SimpleNamespace( + pose=torch.tensor([[0.0, 0, 0, 0, 0, 0, 1]]), + contacts=torch.ones((1, 2), dtype=torch.bool), + ) + row.env.sim.get_rigid_object = lambda uid: SimpleNamespace( + get_local_pose=lambda: state.pose + ) + row.env.sim.simulation_time = 0.0 + row.env.sim.physics_step_index = 0 + row.sensor.get_data = lambda: { + "user_ids": torch.tensor([[[11, 2], [11, 3]]]), + "is_valid": state.contacts, + "impulse_valid": torch.ones((1, 2), dtype=torch.bool), + } + validator = object.__new__(MeasuredExpansionValidator) + validator.rows = {0: row} + validator.sensor = row.sensor + validator.checker = SimpleNamespace( + check=lambda: torch.zeros((1, 3), dtype=torch.int64) + ) + validator.terminal, validator.results = {}, {} + + def sample(dts=None): + validator.begin_control_step() + for dt in ((1 / row.env.control_frequency,) if dts is None else dts): + row.env.sim.simulation_time += dt + row.env.sim.physics_step_index += 1 + validator.after_sample(dt, None) + validator.sample((0,), None) + return row.terminal[0] + + return sample, state + + return build + + +@pytest.mark.parametrize( + "duration,frequency,required", + [ + (0.25, 10, 4), + (0.025, 10, 2), + (0.3, 10, 4), + (0.14, 50, 8), + (0.07, 100, 8), + (0.1400000001, 50, 9), + (0.0700000001, 100, 9), + ], +) def test_contact_hold_requires_full_duration_and_distinct_measured_times( - contact_row, duration, required + contact_row, sample_contacts, duration, frequency, required ): - row = contact_row(duration, ground=True) - pose = [0, 0, 0, 0, 0, 0, 1] - for i in range(required - 1): - row.samples.append((pose.copy(), [True, True], i / 10)) - assert not row._hold_report()["passed"] - row.samples.append((pose.copy(), [True, True], (required - 1) / 10)) + row = contact_row(duration, ground=True, frequency=frequency) + sample, state = sample_contacts(row) + for _ in range(required - 1): + assert not sample().accepted + assert sample().accepted report = row._hold_report() - assert report["passed"] - assert report["elapsed_duration_s"] >= duration - assert row.samples.maxlen == required - # Enough samples at one physical instant cannot establish a hold duration. - row.samples.clear() - row.samples.extend((pose.copy(), [True, True], 0.0) for _ in range(required)) - assert not row._hold_report()["passed"] - row.samples.clear() - row.samples.extend((pose.copy(), [True, True], i / 10) for i in range(required)) - row.samples[-1][1][0] = False - assert not row._hold_report()["passed"] - row.samples[-1][1][0] = True - row.samples[-1][0][0] = 0.1 + assert report["elapsed_duration_s"] >= duration - 1e-15 + assert report["required_samples"] == required + # Repeated observations without physics cannot establish a hold. + row.reset() + row.active = True + for _ in range(required): + assert not sample(()).accepted assert not row._hold_report()["passed"] + row.reset() + row.active = True + for _ in range(required - 1): + sample() + state.contacts[0, 0] = False + assert not sample().accepted + row.reset() + row.active = True + state.contacts.fill_(True) + for _ in range(required - 1): + sample() + state.pose[0, 0] = 0.1 + assert not sample().accepted + assert row._hold_report()["max_translation_drift_m"] == pytest.approx(0.1) @pytest.mark.parametrize("ground", [False, True]) @@ -119,24 +184,44 @@ def test_native_contacts_only_resolve_present_default_plane(contact_row, ground) assert ("default_plane" in row.frames.values()) is ground -def test_contact_sampling_uses_measured_world_time(contact_row): - from unittest.mock import Mock - from embodichain.lab.expansion.contracts import ValidationCheck, ValidationResult - +def test_contact_sampling_uses_measured_physics_intervals(contact_row, sample_contacts): row = contact_row(ground=True) - passed = ValidationResult((ValidationCheck("task.success", "passed"),)) - row.monitor = SimpleNamespace(observe=Mock(), validation=lambda env: passed) - row.env.sim.get_rigid_object = lambda uid: SimpleNamespace( - get_local_pose=lambda: torch.tensor([[0.0, 0, 0, 0, 0, 0, 1]]) - ) - row.sensor.get_data = lambda: { - "user_ids": torch.tensor([[[11, 2], [11, 3]]]), - "is_valid": torch.ones((1, 2), dtype=torch.bool), - "impulse_valid": torch.ones((1, 2), dtype=torch.bool), - } - for timestamp, accepted in ((0.0, False), (0.1, False), (0.2, False), (0.3, True)): - row.env.sim.simulation_time = timestamp - row._interval_samples = 1 - row.sample((0,), None) - assert row.terminal[0].accepted is accepted - assert row._hold_report()["elapsed_duration_s"] == 0.3 + sample, _ = sample_contacts(row) + for accepted in (False, False, False, True): + assert sample().accepted is accepted + assert row._hold_report()["elapsed_duration_s"] == pytest.approx(0.3) + + +@pytest.mark.parametrize("prior_steps", [500_000, 5_000_000]) +@pytest.mark.parametrize("physics_dt,passed", [(0.001, True), (0.0009999, False)]) +def test_hold_clock_is_independent_of_long_running_world_roundoff( + contact_row, sample_contacts, prior_steps, physics_dt, passed +): + row = contact_row(0.7, ground=True, frequency=100) + sample, _ = sample_contacts(row) + clock = 0.0 + for _ in range(prior_steps): + clock += 0.001 + row.env.sim.simulation_time = clock + row.env.sim.physics_step_index = prior_steps + # 71 samples span 700 steps; verify additional rolling windows as well. + for index in range(80): + result = sample((physics_dt,) * 10) + assert result.accepted is (passed and index >= 70) + report = row._hold_report() + assert report["elapsed_duration_s"] == pytest.approx(700 * physics_dt, abs=1e-15) + assert row.env.sim.simulation_time > clock + assert report["passed"] is passed + + +def test_hold_clock_follows_variable_physics_intervals(contact_row, sample_contacts): + row = contact_row(0.25, ground=True, frequency=10) + sample, _ = sample_contacts(row) + for intervals, passed in ( + ((0.03, 0.07), False), + ((0.02, 0.08), False), + ((0.01, 0.04, 0.05), False), + ((0.04, 0.06), True), + ): + assert sample(intervals).accepted is passed + assert row._hold_report()["elapsed_duration_s"] == pytest.approx(0.3) diff --git a/tests/lab/expansion/test_extension_ports_sim.py b/tests/lab/expansion/test_extension_ports_sim.py index ab6a1ecfbf..abec9dad6c 100644 --- a/tests/lab/expansion/test_extension_ports_sim.py +++ b/tests/lab/expansion/test_extension_ports_sim.py @@ -276,8 +276,17 @@ def _probe(output): ], } for backend in ("geometry", "native_contacts"): + selected = dict(configuration) + if backend == "native_contacts": + selected["contact_hold"] = { + "entity": "cube", + "links": ["gripper_finger1_link_1", "gripper_finger2_link_1"], + "duration_s": env.step_dt * 1.4, + "max_translation_drift_m": 0.001, + "max_rotation_drift_rad": 0.001, + } check = MeasuredExpansionValidator( - env, configuration, Path(output) / backend, backend=backend + env, selected, Path(output) / backend, backend=backend ) try: check.prepare() @@ -293,6 +302,13 @@ def _probe(output): assert check.terminal[1] is peer and 0 not in check.terminal if backend == "native_contacts": assert check.rows[1].substeps > 0 and check.rows[0].substeps == 0 + # The clock uses the same native physics intervals that + # supplied contact evidence, independently of World time. + report = check.rows[1]._hold_report() + assert report["samples"] == report["required_samples"] == 3 + assert report["elapsed_duration_s"] == pytest.approx( + 2 * env.step_dt + ) finally: check.close() finally: diff --git a/tests/lab/expansion/test_gym_workloads.py b/tests/lab/expansion/test_gym_workloads.py index 44abf5ab6f..3df961fe9a 100644 --- a/tests/lab/expansion/test_gym_workloads.py +++ b/tests/lab/expansion/test_gym_workloads.py @@ -157,7 +157,14 @@ def propose(*args, **kwargs): @pytest.mark.parametrize( - "difference", [None, "position_velocity", "use_action_manager", "joint_selection"] + "difference", + [ + None, + "position_velocity", + "use_action_manager", + "active_joint_ids", + "joint_order", + ], ) def test_workload_action_schema_checked_before_constructing_world( tmp_path, monkeypatch, difference @@ -173,6 +180,16 @@ class ReachedWorld(Exception): factory = Mock(side_effect=ReachedWorld) monkeypatch.setattr(host, "GymExpansionHost", factory) + from copy import deepcopy + from pathlib import Path + from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv + from embodichain.utils.utility import load_config + + deployment = ( + Path(__file__).resolve().parents[3] + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml" + ) + base = utils.config_to_cfg(load_config(deployment), source_path=deployment) workloads, configs = [], {} for i, name in enumerate(("first", "second")): deployment = tmp_path / f"{name}.json" @@ -185,26 +202,19 @@ class ReachedWorld(Exception): ), use_action_manager=bool(i and difference == "use_action_manager"), ) - configs[name] = SimpleNamespace( - robot=SimpleNamespace( - to_dict=lambda: { - "joint_names": ["a", "b"], - "control_parts": {"arm": [0, 1]}, - } - ), - expert_trajectory=expert, - ) - cls = type( - f"Env{i}", - (), - { - "control_parts": ["arm"], - "active_joint_ids": ( - [1] if i and difference == "joint_selection" else [0] - ), - }, - ) - monkeypatch.setitem(REGISTERED_ENVS, name, SimpleNamespace(cls=cls)) + config = deepcopy(base) + config.expert_trajectory = expert + config.control_parts = ["arm"] + config.active_joint_ids = [] + if difference in ("active_joint_ids", "joint_order"): + config.control_parts = None + config.active_joint_ids = ( + [i] if difference == "active_joint_ids" else ([1, 0] if i else [0, 1]) + ) + configs[name] = config + # Configured tasks share this implementation class. Selection belongs + # to the resolved configs above, never to artificial per-task classes. + monkeypatch.setitem(REGISTERED_ENVS, name, SimpleNamespace(cls=EmbodiedEnv)) cfg = ExpansionRunCfg( deployment=str(deployment), output_dir=str(tmp_path / name), @@ -243,3 +253,71 @@ class ReachedWorld(Exception): workloads, execution, output_dir=tmp_path / "run" ) factory.assert_not_called() + + +def test_real_deployments_with_shared_class_reject_different_control_parts( + tmp_path, monkeypatch +): + from pathlib import Path + from embodichain.lab.expansion import ExpansionRunCfg + from embodichain.lab.expansion.task_program_jobs import _prepare_deployment + from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import REGISTERED_ENVS + from embodichain.utils.utility import load_config + import embodichain.lab.expansion.host as host + + import yaml + + task = ( + Path(__file__).resolve().parents[3] + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place/task.ur5.yaml" + ) + inputs = tmp_path / "inputs" + inputs.mkdir() + base = load_config(_prepare_deployment(task, inputs)) + workloads = [] + for name, parts in (("Arm", ["arm"]), ("ArmEef", ["arm", "eef"])): + component = load_config(task.parent / "envs/default.yaml") + component["env"]["control_parts"] = parts + physical = inputs / f"{name}.environment.yaml" + physical.write_text(yaml.safe_dump(component)) + declaration = { + **base, + "id": f"WorkloadControlSchema-{name}-v1", + "environment": {"component": str(physical)}, + } + path = inputs / f"{name}.json" + path.write_text(json.dumps(declaration)) + config = config_to_cfg(declaration, source_path=path) + assert config.control_parts == parts + assert REGISTERED_ENVS[declaration["id"]].cls is EmbodiedEnv + cfg = ExpansionRunCfg( + deployment=str(path), + output_dir=str(tmp_path / name), + max_steps=20, + settling_steps=1, + ) + workloads.append( + GymExpansionWorkload( + name, + cfg, + { + "input_files": { + "deployment": hashlib.sha256(path.read_bytes()).hexdigest() + } + }, + {}, + ) + ) + constructor = Mock(side_effect=AssertionError("World must not be constructed")) + monkeypatch.setattr(host, "GymExpansionHost", constructor) + with pytest.raises(ValueError, match="schema"): + run_gym_expansion_workloads( + workloads, + WorkloadExecutionCfg( + workload_count=2, batch_size=1, max_steps=20, settling_steps=1 + ), + output_dir=tmp_path / "run", + ) + constructor.assert_not_called() From 565d9812925a305ef692b041f2f3f562eb054985 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Mon, 16 Nov 2026 13:53:19 +0000 Subject: [PATCH 19/49] fix(gensim): clear supports and settle opening before release --- agent_context/topics/gen-sim/gen-sim.md | 6 ++++++ embodichain/gen_sim/README.md | 14 ++++++++++--- embodichain/gen_sim/_run_binding.py | 11 ++++++---- embodichain/gen_sim/_run_config.py | 3 ++- .../lab/sim/atomic_skills/primitives/place.py | 21 ++++++++++++++++++- .../lab/task_program/integrations/catalog.py | 2 ++ .../task_program/integrations/configured.py | 8 +++++++ examples/gensim/scripted_pick_place/README.md | 10 ++++++--- tests/gen_sim/test_workflow.py | 15 ++++++++++++- .../lab/expansion/test_extension_ports_sim.py | 21 +++++++++++++++++++ 10 files changed, 98 insertions(+), 13 deletions(-) diff --git a/agent_context/topics/gen-sim/gen-sim.md b/agent_context/topics/gen-sim/gen-sim.md index 95f7877943..3615432177 100644 --- a/agent_context/topics/gen-sim/gen-sim.md +++ b/agent_context/topics/gen-sim/gen-sim.md @@ -64,6 +64,12 @@ normative TaskSpec certification remain distinct. See the [command guide](../../../embodichain/gen_sim/README.md) and provider-free [scripted reproduction](../../../examples/gensim/scripted_pick_place/README.md). +Automatic placements default to 0.02 m release clearance above their measured +resting target and a 0.4 s open-command hold on the native control grid. Explicit +clearance/Place timing declarations keep their ownership. Opening, terminal +separation, resting-position and stability evidence are unchanged; clearance +and actuation time are planning behavior, not weaker acceptance thresholds. + Articulated USDC admission allows absent `gen_sim:closedPosition` metadata; present declarations must identify a finite joint-limit endpoint. Missing endpoint semantics remain unknown. Operation-specific target qualification diff --git a/embodichain/gen_sim/README.md b/embodichain/gen_sim/README.md index 955eb4360a..0da3041172 100644 --- a/embodichain/gen_sim/README.md +++ b/embodichain/gen_sim/README.md @@ -128,9 +128,17 @@ through the existing closed decoders. `binding.resource_anchors` maps declared resources to planar `[x, y]` anchors: a single-arm call without a resource then uses the arm already holding its object, or the arm anchored nearest to it, and a placement on a support prefers its robot-side region. `binding.release_clearance` -(metres, default 0) releases placements above their resting pose while validators -keep the resting target; the place gate otherwise expects a released object to -separate from the open gripper before retracting. +(metres, default 0.02) releases placements above their resting pose so fingers +can open without wedging against the support. An explicit zero keeps contact +placement. Ordinary generated Place calls also hold the final open command for +0.4 physical seconds before the unchanged release gate; the native planner +rounds this duration upward to the actual control grid. Explicit +`release_settle_duration` values, including zero, are retained; declaring +`release_settle_steps` suppresses that generated duration default. When both +options are explicitly supplied, the longer hold applies. External nominal +sources retain their authored timing. The gate measures opening before retract, +terminal verification measures separation, and the original resting-position +and stability validators remain unchanged. Further optional run fields: `task` reuses a published task-plan directory instead of planning, after verifying its artifacts and that it planned the same instruction diff --git a/embodichain/gen_sim/_run_binding.py b/embodichain/gen_sim/_run_binding.py index 72adfd6614..6cc99c54f7 100644 --- a/embodichain/gen_sim/_run_binding.py +++ b/embodichain/gen_sim/_run_binding.py @@ -979,10 +979,9 @@ def _bind_deployment( if set(anchors) - declared_resources: raise ValueError("resource_anchors must name declared profile resources") holders: dict[str, str] = {} - # Placements may release above their resting pose. The place gate requires a - # released object to separate from the still-open gripper before retracting, - # which an object already resting on its support cannot do. - release_clearance = float(cfg.binding.get("release_clearance", 0.0)) + # Open above the support to avoid wedging a finger against it. The landing + # validators below retain the original measured resting pose. + release_clearance = cfg.binding["release_clearance"] configured_services = runtime_services # Measured legacy geometry binds only the registered calls whose lowerer the # run configuration does not supply. A configured lowerer owns its targets, @@ -1063,6 +1062,10 @@ def subject_of(node: dict[str, Any]) -> str | None: _register_call_options( options, monitors, call, cid, "pick" if skill == "pick_up" else skill, skill ) + if cid == "place" and "release_settle_steps" not in options[key]: + # Allow actual opening before the unchanged release monitor starts. + # This physical duration is converted on the native control grid. + options[key].setdefault("release_settle_duration", 0.4) if cid == "hand_over": options[key].setdefault("release_at_target", False) options[key].setdefault("arm_selection", "bound") diff --git a/embodichain/gen_sim/_run_config.py b/embodichain/gen_sim/_run_config.py index f37af1d132..7398cf4853 100644 --- a/embodichain/gen_sim/_run_config.py +++ b/embodichain/gen_sim/_run_config.py @@ -82,13 +82,14 @@ def __post_init__(self) -> None: "binding supports profile, release_clearance, resource_anchors, " "runtime_services, scene_binding and segments" ) - clearance = self.binding.get("release_clearance", 0.0) + clearance = self.binding.get("release_clearance", 0.02) if ( isinstance(clearance, bool) or not isinstance(clearance, (int, float)) or not 0.0 <= clearance < 0.2 ): raise ValueError("release_clearance must be a height in [0, 0.2) m") + self.binding = {**self.binding, "release_clearance": float(clearance)} anchors = self.binding.get("resource_anchors", {}) if type(anchors) is not dict or any( type(value) is not list diff --git a/embodichain/lab/sim/atomic_skills/primitives/place.py b/embodichain/lab/sim/atomic_skills/primitives/place.py index 5ca67d4308..26f1e0836b 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/place.py +++ b/embodichain/lab/sim/atomic_skills/primitives/place.py @@ -19,6 +19,7 @@ from __future__ import annotations from dataclasses import dataclass, field +import math from typing import ClassVar, Literal import torch @@ -138,6 +139,14 @@ class PlaceOptions(SkillOptions): release_settle_steps: int = 0 """Fully open hold frames before retracting the end-effector.""" + release_settle_duration: float = field(default=0.0, kw_only=True) + """Minimum physical seconds to hold open in a newly planned native Place. + + Rounded upward to control intervals and combined with release_settle_steps + using the larger hold. This is actuation time, not an acceptance tolerance. + External nominal sources retain their authored release timing unchanged. + """ + lift_height: float = 0.1 """Height (m) to retract the end-effector after opening the gripper.""" @@ -157,6 +166,13 @@ class PlaceOptions(SkillOptions): """Keep the held object's observed world orientation at the place target.""" def __post_init__(self) -> None: + if ( + isinstance(self.release_settle_duration, bool) + or not isinstance(self.release_settle_duration, (int, float)) + or not math.isfinite(self.release_settle_duration) + or self.release_settle_duration < 0 + ): + raise ValueError("release_settle_duration must be finite and nonnegative.") if type(self.cartesian_approach) is not bool: raise TypeError("cartesian_approach must be boolean.") if self.hand_interp_steps < 1: @@ -459,7 +475,10 @@ def _plan( hold_hand_qpos, hand_open_qpos, n_waypoints=n_open ) - n_settle = options.release_settle_steps + n_settle = max( + options.release_settle_steps, + math.ceil(options.release_settle_duration / context.require_control_dt()), + ) open_start = n_down settle_start = open_start + n_open back_start = settle_start + n_settle diff --git a/embodichain/lab/task_program/integrations/catalog.py b/embodichain/lab/task_program/integrations/catalog.py index 2d82e87787..64afa95dff 100644 --- a/embodichain/lab/task_program/integrations/catalog.py +++ b/embodichain/lab/task_program/integrations/catalog.py @@ -251,6 +251,8 @@ def _canonical_value(value: object) -> object: metadata.pop("grasp_retract_distance") if isinstance(value, PlaceOptions) and value.cartesian_approach is False: metadata.pop("cartesian_approach") + if isinstance(value, PlaceOptions) and value.release_settle_duration == 0.0: + metadata.pop("release_settle_duration") if isinstance(value, SlideOptions) and value.push_approach_offset is None: metadata.pop("push_approach_offset") return {"type": _qualified_name(value), "fields": metadata} diff --git a/embodichain/lab/task_program/integrations/configured.py b/embodichain/lab/task_program/integrations/configured.py index c8af7a9fdc..847420d1dd 100644 --- a/embodichain/lab/task_program/integrations/configured.py +++ b/embodichain/lab/task_program/integrations/configured.py @@ -1087,6 +1087,7 @@ def _decode_skill_options(value: object, *, path: str) -> SkillOptions: "object_motion_keyframes", "grasp_settle_steps", "release_settle_steps", + "release_settle_duration", "pick_object_part", "lift_height", "pre_grasp_distance", @@ -1287,6 +1288,7 @@ def _decode_skill_options(value: object, *, path: str) -> SkillOptions: { "hand_interp_steps", "release_settle_steps", + "release_settle_duration", "lift_height", "max_approach_retract_z", "cartesian_waypoint_count", @@ -1312,6 +1314,12 @@ def _decode_skill_options(value: object, *, path: str) -> SkillOptions: path=f"{path}.release_settle_steps", minimum=0, ) + if "release_settle_duration" in config: + kwargs["release_settle_duration"] = _real( + config["release_settle_duration"], + path=f"{path}.release_settle_duration", + minimum=0.0, + ) if "lift_height" in config: kwargs["lift_height"] = _real( config["lift_height"], diff --git a/examples/gensim/scripted_pick_place/README.md b/examples/gensim/scripted_pick_place/README.md index 4c766aa754..17e6985147 100644 --- a/examples/gensim/scripted_pick_place/README.md +++ b/examples/gensim/scripted_pick_place/README.md @@ -18,9 +18,13 @@ This example prepares fixed inputs, runs the shared GenSim workflow, and measure wall-clock time through native execution and cleanup. It demonstrates the previous dual-UR5 table/cube case without a live model or reconstruction service. -The recorded outcome is **pickup succeeds, placement release verification fails**. -It is a reproducible failure investigation, not a successful expert dataset -collection or qualification of real photograph-to-scene generation. +The current defaults release 0.02 m above the resting target and hold open for +0.4 physical seconds before release verification. This avoids the previously +recorded finger/support interference while retaining measured opening, +separation, stability and landing requirements. Explicit zero clearance can +still reproduce a physically rejected contact placement. The historical failure +measurements below remain tied to their original revision; this scripted case +does not qualify real photograph-to-scene generation or model quality. ## Requirements and inputs diff --git a/tests/gen_sim/test_workflow.py b/tests/gen_sim/test_workflow.py index 094eb72c59..dba3cf2242 100644 --- a/tests/gen_sim/test_workflow.py +++ b/tests/gen_sim/test_workflow.py @@ -259,6 +259,19 @@ def run_cfg(tmp_path: Path) -> _RunCfg: ) +@pytest.mark.parametrize( + "binding,expected", + [({}, 0.02), ({"profile": {}}, 0.02), ({"release_clearance": 0.0}, 0.0)], +) +def test_release_clearance_default_preserves_explicit_contact_placement( + run_cfg, binding, expected +): + original = json.loads(json.dumps(binding)) + cfg = _RunCfg(**{**run_cfg.to_dict(), "binding": binding}) + assert cfg.binding["release_clearance"] == expected + assert binding == original + + @pytest.mark.parametrize("success", [True, False]) def test_workflow_generates_binds_and_preserves_actual_execution_verdict( run_cfg: _RunCfg, monkeypatch: pytest.MonkeyPatch, success: bool @@ -274,7 +287,7 @@ def test_workflow_generates_binds_and_preserves_actual_execution_verdict( run_cfg.instruction += " \n" run_cfg.task_id = " gensim_task " - # Releasing above the resting pose is opt-in; cover both settings. + # Exercise raised release and an explicit zero-clearance contact placement. clearance = 0.03 if success else 0.0 run_cfg = _RunCfg( **{ diff --git a/tests/lab/expansion/test_extension_ports_sim.py b/tests/lab/expansion/test_extension_ports_sim.py index abec9dad6c..30d8422bba 100644 --- a/tests/lab/expansion/test_extension_ports_sim.py +++ b/tests/lab/expansion/test_extension_ports_sim.py @@ -143,6 +143,27 @@ def _check_place_keyframes(env, generator): ), context, ) + for period, steps, expected in ((0.04, 0, 3), (0.02, 0, 6), (0.04, 5, 5)): + timed = engine.plan( + replace( + invocation, + skill_options=replace( + options, release_settle_duration=0.11, release_settle_steps=steps + ), + ), + engine.initial_context(control_dt=period), + ) + release = timed.segment("release") + assert release.stop - release.start == options.hand_interp_steps + expected + hand_ids = env.robot.get_joint_ids("eef") + torch.testing.assert_close( + timed.joint_trajectory.positions[ + :, release.stop - expected : release.stop, hand_ids + ], + hand_limits[None, :, 0].expand(1, expected, -1), + rtol=0, + atol=0, + ) def _probe(output): From 33fe553aec636a5d9f1398d09defb68a73ac3270 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 02:09:05 +0000 Subject: [PATCH 20/49] test(gensim): align binding coverage with release clearance defaults Keep landing-pose acceptance independent of the raised release target, covering zero and default clearance as well as configured lowerer ownership. Reconstruct the coordinated-transport configuration through its normal validator instead of replacing its normalized binding dictionary. Validation: reproduced both failed CI cases; all 62 GenSim workflow tests and the native placement/release integration probe passed on pinned DexSim 0.6.0rc2. Black 26.10.1, API docs 5010/5010, context map and diff checks passed. No production behavior changed; existing GenSim context already describes clearance and landing validation correctly. --- tests/gen_sim/test_workflow.py | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/tests/gen_sim/test_workflow.py b/tests/gen_sim/test_workflow.py index dba3cf2242..3ff9de567d 100644 --- a/tests/gen_sim/test_workflow.py +++ b/tests/gen_sim/test_workflow.py @@ -1120,8 +1120,12 @@ def _node(node_id: str, call: dict, depends_on: list[str], **semantic) -> dict: @pytest.mark.parametrize("configured", [False, True]) +@pytest.mark.parametrize("clearance", [0.0, 0.02]) def test_relative_placement_validators_follow_the_selected_lowerer( - run_cfg: _RunCfg, monkeypatch: pytest.MonkeyPatch, configured: bool + run_cfg: _RunCfg, + monkeypatch: pytest.MonkeyPatch, + configured: bool, + clearance: float, ) -> None: instruction = "Put the cube right of the table" semantic = dict( @@ -1166,7 +1170,7 @@ def test_relative_placement_validators_follow_the_selected_lowerer( **{ **run_cfg.to_dict(), "instruction": instruction, - "binding": {"runtime_services": services}, + "binding": {"runtime_services": services, "release_clearance": clearance}, } ) @@ -1184,7 +1188,13 @@ def test_relative_placement_validators_follow_the_selected_lowerer( assert validators == [] else: (validator,) = validators - assert lowerer["routes"][0]["world_displacement"] == validator["displacement"] + # The route is the release pose; acceptance still measures the resting + # landing pose. Explicit zero clearance retains contact placement. + landing = validator["displacement"] + release = lowerer["routes"][0]["world_displacement"] + assert release[:2] == landing[:2] + assert landing[2] == pytest.approx(0.005) + assert release[2] == pytest.approx(0.005 + clearance) def test_held_upright_without_reference_validates_its_terminal_pose( @@ -1923,7 +1933,7 @@ def test_legacy_configured_coordinated_target_survives_binding(run_cfg, monkeypa route = dict( object_id="source", target_id="tray_target", world_displacement=[0.1, 0.0, 0.0] ) - run_cfg.binding = { + binding = { "runtime_services": { "registered_semantic_lowerers": [ dict(kind="coordinated_transport", routes=[route]) @@ -1937,6 +1947,7 @@ def test_legacy_configured_coordinated_target_survives_binding(run_cfg, monkeypa } }, } + run_cfg = _RunCfg(**{**run_cfg.to_dict(), "binding": binding}) run_cfg.output.mkdir() with _services(step=step, plan=proposed) as services: task = plan_image_task( From bf4a25422890b2524814119439a255da57f37840 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 02:49:51 +0000 Subject: [PATCH 21/49] fix(expansion): preserve selected rows and batch measured validation --- .../topics/atomic-actions/atomic-actions.md | 6 + .../topics/expansion-engine/workloads.md | 17 ++ embodichain/data_pipeline/recording/media.py | 5 +- embodichain/lab/expansion/_gym_episode.py | 9 +- embodichain/lab/expansion/acceptance.py | 174 +++++++++++++++--- .../lab/gym/envs/task_program/bridge.py | 58 ++++-- .../sim/atomic_skills/primitives/hand_over.py | 5 + tests/gym/envs/task_program/test_bridge.py | 33 ++++ .../lab/expansion/test_extension_ports_sim.py | 121 +++++++++++- 9 files changed, 380 insertions(+), 48 deletions(-) diff --git a/agent_context/topics/atomic-actions/atomic-actions.md b/agent_context/topics/atomic-actions/atomic-actions.md index f8927e9e9b..2dcc7d3636 100644 --- a/agent_context/topics/atomic-actions/atomic-actions.md +++ b/agent_context/topics/atomic-actions/atomic-actions.md @@ -24,6 +24,12 @@ Hosts acquire versioned measurements; verification is the boundary that commits or invalidates observed effects. Preserve required stop/hold boundaries on the executed control grid instead of relying only on native planner timing. +Row-local planning within a larger World must carry the same explicit +`context.env_ids` through FK/IK, root poses and diagnostics. HandOver applies this +to both source/destination arms, including its continuation and failed-waypoint +diagnostic routes. A one-row planning context does not implicitly select arena +zero or all arenas of the robot. + ## Package map | Concern | Source of truth | diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index c22d2af281..b1be19998c 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -118,6 +118,23 @@ each native event state machine and receipts. `ContactPermissionChecker` checks all valid native contact slots with the original applied-impulse and loss gates; hosts still own sampling at every required physics substep. +`MeasuredExpansionValidator` uses these same batch interfaces. Compatible rows +share one immutable geometry declaration/checker; selected rows are compacted +into bounded Newton queries and mapped back in their original order. Different +geometry retains separate checker groups. Query models never step physics. +Predicate inputs share the current complete measured snapshot, while events, +consecutive counts, failures and contact holds remain row-owned. Shape snapshots +are needed only by declared support-bound predicates; native-contact rows do not +gain a homogeneous-topology requirement. + +The built-in joint transport writes all of a frame's destinations into one owned +output. Single commands, subclasses, replaced encoder methods and custom +transports retain normal dispatch and registration order. Numerical/frame checks, +inactive holds and position-velocity evidence remain unchanged. Episode assembly +shares validated immutable segment metadata internally; mutable readback still +owns its containers. Durable JSON uses the same finite sorted representation and +fsync/atomic publication, with one encoded text allocation. + Default GPU dynamics use Direct GPU reporting, whose static contact identity limitations remain explicit admission constraints. Physics devices and task qualification must be reported separately. Existing CPU deployments do not diff --git a/embodichain/data_pipeline/recording/media.py b/embodichain/data_pipeline/recording/media.py index e36105a060..8be9ddbdae 100644 --- a/embodichain/data_pipeline/recording/media.py +++ b/embodichain/data_pipeline/recording/media.py @@ -65,7 +65,10 @@ def _atomic_json(path: Path, value: object) -> None: handle, temporary = tempfile.mkstemp(dir=path.parent, prefix=".pending-") try: with os.fdopen(handle, "w") as stream: - json.dump(value, stream, allow_nan=False, sort_keys=True) + # The C encoder returns one owned string instead of issuing a + # Python write for every metadata leaf. Keep the durable publish + # boundary and finite-value rejection unchanged. + stream.write(json.dumps(value, allow_nan=False, sort_keys=True)) stream.flush() os.fsync(stream.fileno()) os.replace(temporary, path) diff --git a/embodichain/lab/expansion/_gym_episode.py b/embodichain/lab/expansion/_gym_episode.py index fd686fc458..6eb1f02a83 100644 --- a/embodichain/lab/expansion/_gym_episode.py +++ b/embodichain/lab/expansion/_gym_episode.py @@ -120,6 +120,11 @@ def assemble(self, assignments, collector, services, result, physics_after): key = f"scene_state_{index}" observations[key] = torch.stack(values) scene_keys.append({"key": key, "entity_uid": uid, "field": field}) + from embodichain.utils._owned_json import freeze_metadata + + # Both compatibility fields describe the same immutable audit tree. + # Validate/own it once; mutable public projections still detach. + segments = freeze_metadata(result.segments[result_row]) metadata = { "source_env_id": row, "attempt_sequence": ctx.requests[row].sequence, @@ -146,13 +151,13 @@ def assemble(self, assignments, collector, services, result, physics_after): "initial_state": record["initial_state"], "scene_state_fields": scene_keys, "physics_backend": env.sim.physics_backend, - "program_segments": result.segments[result_row], + "program_segments": segments, "expansion": ( result.expansion_records[result_row] if result.expansion_records else () ), - "segments": result.segments[result_row], + "segments": segments, "instruction": program.instruction, "instruction_source": "task_program", } diff --git a/embodichain/lab/expansion/acceptance.py b/embodichain/lab/expansion/acceptance.py index 03ec618bbe..2b7937e28e 100644 --- a/embodichain/lab/expansion/acceptance.py +++ b/embodichain/lab/expansion/acceptance.py @@ -137,7 +137,14 @@ def pairs(values): return ignored, allowed def __init__( - self, env, configuration: dict, output: Path, *, device="cpu", env_id=0 + self, + env, + configuration: dict, + output: Path, + *, + device="cpu", + env_id=0, + checker_pool=None, ): self.env_id = env_id from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( @@ -151,9 +158,14 @@ def __init__( ignored, self.allowed_contacts = self.contact_permissions( env, configuration, known ) - checker = NewtonCollisionChecker( - bodies, ignored_pairs=ignored, device=device, max_shapes=512 - ) + key = (tuple(bodies), tuple(ignored), device) + checker = None if checker_pool is None else checker_pool.get(key) + if checker is None: + checker = NewtonCollisionChecker( + bodies, ignored_pairs=ignored, device=device, max_shapes=512 + ) + if checker_pool is not None: + checker_pool[key] = checker self.checkers = [(checker, self.allowed_contacts, known)] atomic_json( output / "collision-geometry.json", @@ -222,28 +234,32 @@ def sample(self, ids, action, snapshot=None): allowed_contacts=contacts, moving_objects=tuple(uid for uid in self.moving if uid in aliases), ) - if self.env_id not in self.results or report.status != "passed": - self.results[self.env_id] = SimpleNamespace( - status=report.status, - reason=f"{report.reason}; pair={checker.last_pair}", - ) + self.record_geometry(report, checker.last_pair, action) if report.status != "passed": - metadata = action.metadata.get("row_actions", {}).get( - str(self.env_id), action.metadata - ) - atomic_json( - self.output / "collision-failure.json", - { - "reason": self.results[self.env_id].reason, - "action": { - key: str(value) - for key, value in metadata.items() - if isinstance(value, (str, int, float, bool)) - }, - }, - ) break + def record_geometry(self, report, pair, action): + """Retain measured failure and its original row-owned diagnostic.""" + if self.env_id not in self.results or report.status != "passed": + self.results[self.env_id] = SimpleNamespace( + status=report.status, reason=f"{report.reason}; pair={pair}" + ) + if report.status != "passed": + metadata = action.metadata.get("row_actions", {}).get( + str(self.env_id), action.metadata + ) + atomic_json( + self.output / "collision-failure.json", + { + "reason": self.results[self.env_id].reason, + "action": { + key: str(value) + for key, value in metadata.items() + if isinstance(value, (str, int, float, bool)) + }, + }, + ) + def close(self): for checker, _, _ in self.checkers: checker.close() @@ -533,18 +549,48 @@ def __init__( ) ) environment.sensors[self.sensor_uid] = self.sensor + checker_pool = {} for row in range(environment.num_envs): path = output if environment.num_envs == 1 else output / f"row-{row}" path.mkdir(parents=True, exist_ok=True) self.rows[row] = ( _GeometryRow( - environment, configuration, path, device=device, env_id=row + environment, + configuration, + path, + device=device, + env_id=row, + checker_pool=checker_pool, ) if self.sensor is None else _ContactRow( environment, configuration, path, sensor=self.sensor, env_id=row ) ) + conditions = [ + *configuration["initial_checks"], + *configuration["final_checks"], + ] + for event in configuration["events"]: + conditions.extend(event["conditions"]) + shape_entities = { + condition["entity"] + for condition in conditions + if condition["kind"] == "support_bounds" + } + self._shapes = { + uid: ( + tuple( + environment.sim.get_rigid_object(uid).get_collision_shapes( + env_id=row, allow_heterogeneous=True + ) + for row in range(environment.num_envs) + ) + if uid in shape_entities + else () + ) + for uid in environment.sim.get_rigid_object_uid_list() + } if self.sensor is not None: permissions = self.rows[0].allowed self.checker = ContactPermissionChecker( @@ -624,13 +670,83 @@ def sample( snapshot: SceneState | None = None, ) -> None: """Check measured task state and retain each row's first physical failure.""" + if not ids: + return + from .collision import _measured_frame + from embodichain.lab.task_program.integrations.feasibility import ( + MeasuredTaskMonitor, + ) + + env = self.env + measured = ( + _measured_frame(env, snapshot, self._shapes) + if getattr(snapshot, "env_ids", None) == tuple(range(env.num_envs)) + else env + ) + monitors = tuple(self.rows[row].monitor for row in ids) + with MeasuredTaskMonitor.batch_scope(measured, monitors): + for row in ids: + check = self.rows[row] + if self.sensor is None: + check.monitor.observe(measured, action) + check.terminal[row] = check.monitor.validation(measured) + else: + check.sample((row,), action, snapshot) + check._interval_samples = 0 + self.terminal[row] = check.terminal[row] + if self.sensor is None: + self._sample_geometry(ids, action) + for row in ids: + self.results[row] = self.rows[row].results[row] + + def _sample_geometry(self, ids, action): + """Batch compatible physical geometry, retaining heterogeneous-row checks.""" + from embodichain.utils.math import matrix_from_quat + + env = self.env + poses = env.robot.body_data.body_link_pose + matrices = torch.eye(4, dtype=poses.dtype, device=poses.device).repeat( + env.num_envs, len(env.robot.link_names), 1, 1 + ) + matrices[..., :3, :3] = matrix_from_quat(poses[..., 3:]) + matrices[..., :3, 3] = poses[..., :3] + matrices = matrices.detach().cpu().numpy() + frames = { + f"{env.robot.uid}/{link}": matrices[:, index] + for index, link in enumerate(env.robot.link_names) + } + frames.update( + { + uid: env.sim.get_rigid_object(uid) + .get_local_pose(to_matrix=True) + .detach() + .cpu() + .numpy() + for uid in env.sim.get_rigid_object_uid_list() + } + ) + frames["default_plane"] = np.broadcast_to(np.eye(4), (env.num_envs, 4, 4)) + groups = {} for row in ids: check = self.rows[row] - check.sample((row,), action, snapshot) - self.terminal[row] = check.terminal[row] - self.results[row] = check.results[row] - if self.sensor is not None: - check._interval_samples = 0 + for checker, allowed, aliases in check.checkers: + moving = tuple(uid for uid in check.moving if uid in aliases) + groups.setdefault((checker, tuple(allowed), moving), []).append(row) + for (checker, allowed, moving), rows in groups.items(): + # Respect the existing aggregate contact-buffer ceiling. Compact + # selected rows also prevent inactive/heterogeneous rows consuming it. + width = max(1, min(env.num_envs, 1048576 // checker._capacity)) + for start in range(0, len(rows), width): + selected = rows[start : start + width] + reports = checker.check_batch( + {uid: values[selected] for uid, values in frames.items()}, + allowed_contacts=allowed, + moving_objects=moving, + ) + for row, report, pair in zip( + selected, reports, checker.last_batch_pairs + ): + self.rows[row].record_geometry(report, pair, action) def close(self) -> None: """Detach owned observers before releasing resources; safe on failure.""" diff --git a/embodichain/lab/gym/envs/task_program/bridge.py b/embodichain/lab/gym/envs/task_program/bridge.py index 9de1c60d4d..5ee67cc941 100644 --- a/embodichain/lab/gym/envs/task_program/bridge.py +++ b/embodichain/lab/gym/envs/task_program/bridge.py @@ -452,14 +452,33 @@ def encode( active_mask: torch.Tensor, ) -> EnvAction: """Write addressed joints while holding every other qpos column.""" + return self._encode_commands( + (command,), base_action=base_action, active_mask=active_mask + ) + + def _encode_commands(self, commands, *, base_action, active_mask): + """Own one output for a validated frame's built-in joint destinations.""" + if not isinstance(base_action, (torch.Tensor, TensorDict)): + raise TypeError( + "The built-in joint-position encoder requires a tensor action or " + "a TensorDict containing qpos." + ) + action = base_action.clone() + for command in commands: + self._write_command(command, action=action, active_mask=active_mask) + return action + + @staticmethod + def _write_command(command, *, action, active_mask): + """Apply one command to an already-owned frame output.""" if not isinstance(command.target, JointPositionTarget): raise TypeError("Joint-position transport requires JointPositionTarget.") if not isinstance(command.payload, JointPositionPayload): raise TypeError("Joint-position transport requires JointPositionPayload.") - if isinstance(base_action, torch.Tensor): - qpos = base_action - elif isinstance(base_action, TensorDict) and "qpos" in base_action: - qpos = base_action["qpos"] + if isinstance(action, torch.Tensor): + qpos = action + elif isinstance(action, TensorDict) and "qpos" in action: + qpos = action["qpos"] else: raise TypeError( "The built-in joint-position encoder requires a tensor action or " @@ -487,38 +506,34 @@ def encode( if not qpos.is_floating_point(): raise TypeError("The full-qpos base action must be floating point.") - action_qpos = qpos.clone() + action_qpos = qpos columns = torch.tensor(joint_ids, dtype=torch.long, device=qpos.device) selected = action_qpos.index_select(1, columns) selected[active_mask] = positions[active_mask].to(dtype=action_qpos.dtype) action_qpos[:, columns] = selected - if isinstance(base_action, torch.Tensor): - return action_qpos + if isinstance(action, torch.Tensor): + return velocities = command.payload.velocities if velocities is None: raise ValueError( "position_velocity joint commands require payload velocities." ) - if "qvel" not in base_action: + if "qvel" not in action: raise TypeError( "Position-velocity joint actions require qpos and qvel base targets." ) - qvel = base_action["qvel"] + qvel = action["qvel"] if qvel.shape != qpos.shape or qvel.device != qpos.device: raise ValueError( "Full qpos and qvel base targets must share shape and device." ) - action_qvel = qvel.clone() + action_qvel = qvel selected_velocity = action_qvel.index_select(1, columns) selected_velocity[active_mask] = velocities[active_mask].to( dtype=action_qvel.dtype ) action_qvel[:, columns] = selected_velocity - action = base_action.clone() - action["qpos"] = action_qpos - action["qvel"] = action_qvel - return action def hold( self, @@ -534,6 +549,9 @@ def hold( return base_action.clone() +_BUILTIN_JOINT_ENCODE = JointPositionGymTransportEncoder.encode + + class RuntimeCommandFrameEncoder: """Encode transport-neutral command frames to controller-ready Gym actions. @@ -742,7 +760,17 @@ def encode(self, frame: RuntimeCommandFrame) -> EnvAction: self._validate_command_types(transport, command) by_transport.setdefault(command.transport_id, []).append(command) for transport_id, transport in self._transports.items(): - for command in by_transport.get(transport_id, ()): + commands = by_transport.get(transport_id, ()) + if ( + len(commands) > 1 + and type(transport) is JointPositionGymTransportEncoder + and getattr(transport.encode, "__func__", None) is _BUILTIN_JOINT_ENCODE + ): + action = transport._encode_commands( + commands, base_action=action, active_mask=frame.active_mask + ) + continue + for command in commands: action = transport.encode( command, base_action=action, diff --git a/embodichain/lab/sim/atomic_skills/primitives/hand_over.py b/embodichain/lab/sim/atomic_skills/primitives/hand_over.py index c868348965..3ba75931b5 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/hand_over.py +++ b/embodichain/lab/sim/atomic_skills/primitives/hand_over.py @@ -740,6 +740,7 @@ def _plan_existing_hold( qpos=source_start_qpos, name=resources.first.arm.control_part, to_matrix=True, + env_ids=context.env_ids, ) current_object_pose = torch.bmm(source_eef, pose_inv(source_object_to_eef)) @@ -781,6 +782,7 @@ def _plan_existing_hold( qpos=destination_start_qpos, name=resources.second.arm.control_part, to_matrix=True, + env_ids=context.env_ids, ) # Approach diagonally from the receiver's side of the embodiment. A # top-down receiver places two bulky parallel grippers in the same @@ -1268,12 +1270,14 @@ def _plan_direction( qpos=handover_start_qpos, name=handover.arm.control_part, to_matrix=True, + env_ids=context.env_ids, ) receive_start_qpos = start_qpos[:, list(receive.arm.joint_ids)] receive_start_eef = self.robot.compute_fk( qpos=receive_start_qpos, name=receive.arm.control_part, to_matrix=True, + env_ids=context.env_ids, ) vertical_mode = ( @@ -1967,6 +1971,7 @@ def _report_phase_failure( pose=target_poses[:, waypoint_index], name=arm.control_part, joint_seed=joint_seed, + env_ids=context.env_ids, ) ik_success = normalize_success_mask( ik_success, diff --git a/tests/gym/envs/task_program/test_bridge.py b/tests/gym/envs/task_program/test_bridge.py index 1746c21e81..a461f3e8d9 100644 --- a/tests/gym/envs/task_program/test_bridge.py +++ b/tests/gym/envs/task_program/test_bridge.py @@ -1148,6 +1148,39 @@ def test_joint_encoder_emits_full_qpos_and_holds_inactive_rows() -> None: assert torch.equal(action[1], qpos[1]) +@pytest.mark.parametrize("mode", ["position", "position_velocity"]) +def test_joint_encoder_groups_destinations_without_aliasing_source(mode) -> None: + """A complete frame preserves independent destinations and inactive rows.""" + qpos = torch.arange(BATCH_SIZE * ROBOT_DOF, dtype=torch.float32).reshape( + BATCH_SIZE, ROBOT_DOF + ) + source = qpos.clone() + encoder = RuntimeCommandFrameEncoder(_QposProvider(qpos), joint_command_mode=mode) + first = _joint_frame( + duration=STEP_DT, + active_mask=torch.tensor([True, False]), + velocities=torch.tensor([[1.0, 3.0], [11.0, 13.0]]), + ) + extra = EndpointCommand( + target=JointPositionTarget(control_part="second", joint_ids=(0,)), + payload=JointPositionPayload( + positions=torch.tensor([[90.0], [91.0]]), + velocities=torch.tensor([[9.0], [9.1]]), + ), + ) + frame = replace(first, commands=(*first.commands, extra)) + action = encoder.encode(frame) + positions = action if mode == "position" else action["qpos"] + assert torch.equal(positions[0], torch.tensor([90.0, 10.0, 2.0, 30.0, 4.0])) + assert torch.equal(positions[1], source[1]) + if mode == "position_velocity": + assert torch.equal(action["qvel"][0], torch.tensor([9.0, 1.0, 0.0, 3.0, 0.0])) + assert torch.equal(action["qvel"][1], torch.zeros(ROBOT_DOF)) + positions.zero_() + assert torch.equal(qpos, source) + assert torch.equal(extra.payload.positions, torch.tensor([[90.0], [91.0]])) + + def test_joint_encoder_holds_unaddressed_joints_at_controller_targets() -> None: """A scoped command must not chase measured drift on another resource.""" current = torch.zeros(BATCH_SIZE, ROBOT_DOF) diff --git a/tests/lab/expansion/test_extension_ports_sim.py b/tests/lab/expansion/test_extension_ports_sim.py index 30d8422bba..8230db610e 100644 --- a/tests/lab/expansion/test_extension_ports_sim.py +++ b/tests/lab/expansion/test_extension_ports_sim.py @@ -321,6 +321,52 @@ def _probe(output): peer = check.terminal[1] check.prepare(env_ids=(0,)) assert check.terminal[1] is peer and 0 not in check.terminal + if backend == "geometry": + from embodichain.lab.gym.envs.types import ControllerAction + + # A real collider overlap in only one selected arena must + # not reject the safe peer, including reordered selection. + forbidden = { + **configuration, + "allowed_contacts": [ + pair + for pair in configuration["allowed_contacts"] + if not ( + "cube" in pair + and any( + name.startswith(env.robot.uid + "/") + for name in pair + ) + ) + ], + } + measured = MeasuredExpansionValidator( + env, + forbidden, + Path(output) / "geometry-selected", + backend="geometry", + ) + cube = env.sim.get_rigid_object("cube") + original = cube.get_local_pose(to_matrix=True)[1:2].clone() + try: + measured.prepare() + body = next( + b + for b in collision_bodies_from_simulation(env, env_id=1) + if b.robot and b.kind != "halfspace" + ) + link = body.frame_uid.split("/", 1)[1] + pose = env.robot.get_link_pose(link, to_matrix=True)[1:2] + pose = pose @ torch.tensor(body.local_pose, dtype=pose.dtype) + before_query = env.sim.physics_step_index + cube.set_local_pose(pose, env_ids=[1]) + measured.sample((1, 0), ControllerAction(env.robot.get_qpos())) + assert measured.results[0].status == "passed" + assert measured.results[1].status == "failed" + assert env.sim.physics_step_index == before_query + finally: + cube.set_local_pose(original, env_ids=[1]) + measured.close() if backend == "native_contacts": assert check.rows[1].substeps > 0 and check.rows[0].substeps == 0 # The clock uses the same native physics intervals that @@ -350,5 +396,78 @@ def test_explicit_phase_paths_and_selected_row_acceptance(tmp_path): assert result.returncode == 0, result.stdout[-3000:] + result.stderr[-5000:] +def _probe_handover_rows(): + """Plan and consume selected rows in a larger real handover World.""" + import torch + from embodichain.lab.expansion.program import collect_program_batch + from embodichain.lab.gym.utils.gym_utils import config_to_cfg + from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, + discover_task_packages, + execute_init_hooks, + ) + from embodichain.lab.sim import SimulationManager + from embodichain.utils.utility import load_config + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + path = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/hand_over/task.tianji_marvin.yaml" + ) + discover_task_packages() + execute_init_hooks() + cfg = config_to_cfg(load_config(path), source_path=path) + cfg.num_envs = cfg.sim_cfg.num_envs = 4 + cfg.sim_cfg.device, cfg.sim_cfg.headless = "cpu", True + cfg.sim_cfg.render_cfg.renderer = "no-render" + cfg.sensor, cfg.enable_sensor, cfg.dataset = [], False, None + cfg.init_rollout_buffer = cfg.record_trajectory = False + env = REGISTERED_ENVS[load_config(path)["id"]].make(cfg=cfg) + adapters = [] + try: + env.reset(seed=2) + program = env.task_program_adapter.compile(cfg.task_program) + bridges = {} + for row in (3, 1): + adapter = env.task_program_adapter.for_env_ids((row,)) + adapters.append(adapter) + bridges[row] = adapter.create_bridge(program, isolate_policy_sessions=True) + observed = [] + result = collect_program_batch( + env, + bridges, + max_steps=2, + observe_step=lambda ids, action, observation: observed.append(ids), + ) + # The original FK omitted selected IDs and rejected both plans at zero + # commands. Budget cancellation must instead follow real commands. + assert result.env_ids == (3, 1) + assert all(length >= 1 for length in result.lengths), result.lengths + assert observed and set(observed[0]) == {3, 1} + assert not any(result.accepted) + finally: + for adapter in adapters: + adapter.close() + env.close(exit_process=False) + SimulationManager.flush_cleanup_queue() + + +@pytest.mark.subprocess_sim +def test_selected_handover_rows_preserve_world_batch(tmp_path): + result = subprocess.run( + [sys.executable, __file__, "handover"], + cwd=Path(__file__).resolve().parents[3], + env={**os.environ, "SDL_VIDEODRIVER": "offscreen", "OMP_NUM_THREADS": "1"}, + capture_output=True, + text=True, + timeout=300, + ) + assert result.returncode == 0, result.stdout[-3000:] + result.stderr[-5000:] + + if __name__ == "__main__": - _probe(sys.argv[1]) + if sys.argv[1] == "handover": + _probe_handover_rows() + else: + _probe(sys.argv[1]) From c3e6cd1bac6b273f1c5c46d017d0e074d7a36a30 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 03:04:45 +0000 Subject: [PATCH 22/49] test(expansion): use native monitors in hold sampling coverage Bind the test validator to its measured environment and retain the real MeasuredTaskMonitor with deterministic joint evidence. This keeps hold-duration and contact assertions intact while exercising the new batched predicate boundary, instead of supplying an incomplete synthetic monitor. Validation: 471 related expansion/bridge/configuration/GenSim tests passed, plus both native validation/selected-handover probes on pinned DexSim 0.6.0rc2. Black 26.10.1, API docs 5013/5013, context map and diff checks passed. Dataset cache was isolated to task-owned tmpfs because the host root filesystem had no non-reserved free space. Production behavior and documentation contracts are unchanged. --- tests/lab/expansion/test_acceptance.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tests/lab/expansion/test_acceptance.py b/tests/lab/expansion/test_acceptance.py index bfb1e65a73..cfd5507e56 100644 --- a/tests/lab/expansion/test_acceptance.py +++ b/tests/lab/expansion/test_acceptance.py @@ -86,13 +86,12 @@ def actor_ids(uid, links=None): @pytest.fixture def sample_contacts(): """Feed the production observer/sample boundary using explicit physics intervals.""" - from unittest.mock import Mock from embodichain.lab.expansion.acceptance import MeasuredExpansionValidator - from embodichain.lab.expansion.contracts import ValidationCheck, ValidationResult def build(row): - passed = ValidationResult((ValidationCheck("task.success", "passed"),)) - row.monitor = SimpleNamespace(observe=Mock(), validation=lambda env: passed) + row.env.num_envs = 1 + row.env.robot.joint_names = ["j"] + row.env.robot.get_qpos = lambda: torch.zeros((1, 1)) row.active = True state = SimpleNamespace( pose=torch.tensor([[0.0, 0, 0, 0, 0, 0, 1]]), @@ -108,7 +107,9 @@ def build(row): "is_valid": state.contacts, "impulse_valid": torch.ones((1, 2), dtype=torch.bool), } + row.monitor.reset(row.env) validator = object.__new__(MeasuredExpansionValidator) + validator.env = row.env validator.rows = {0: row} validator.sensor = row.sensor validator.checker = SimpleNamespace( From d887e99361bc5e20d12c7e1c9f00448fe957ffa7 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 04:57:25 +0000 Subject: [PATCH 23/49] fix(expansion): validate prepared scenes and PickUp path conflicts Include scene preparation declarations and parameters in shared-World compatibility before creating the host. Reject cartesian_lift combined with phase_paths, consistent with Place's explicit conflict handling. Cover real deployment decoding, matching and mismatched preparation hooks, and public fixed-grid PickUp planning. Keep the dual-arm test robot aligned with selected-row FK queries. Update the affected project context. --- .../topics/expansion-engine/workloads.md | 4 +- .../topics/motion-planning/motion-planning.md | 3 + embodichain/lab/expansion/gym_workloads.py | 3 +- .../sim/atomic_skills/primitives/pick_up.py | 7 +- tests/lab/expansion/test_gym_workloads.py | 55 ++++++++++++++-- tests/sim/atomic_skills/test_actions.py | 66 ++++++++++++++++++- 6 files changed, 126 insertions(+), 12 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index b1be19998c..3b4a93bfb1 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -42,7 +42,9 @@ independent collection budget, artifacts and row callbacks. The facade opens one World, captures the original seeded nominal scene in row zero, and composes the existing session, frame collector, episode assembler and confirmed artifact sink. Different integration/grasp policies may share that World only when their -physical configuration, program, cadence and expert action schema agree. +physical configuration, program, cadence and expert action schema agree. The +scene-preparation declaration and its parameters must also match, because the +common nominal scene is prepared once before constructing the World. Command mode, ActionManager declarations and controlled-joint selections cannot vary between workloads in one World. Selections belong to the resolved environment configurations, not the shared registered environment implementation class. Physical/visual/prototype diff --git a/agent_context/topics/motion-planning/motion-planning.md b/agent_context/topics/motion-planning/motion-planning.md index eda26894ab..8163844115 100644 --- a/agent_context/topics/motion-planning/motion-planning.md +++ b/agent_context/topics/motion-planning/motion-planning.md @@ -60,6 +60,9 @@ failure masks. No robot UID or waypoint count enables the behavior. Atomic `MotionPolicy.phase_paths` names the PickUp/Place phases that opt into this path; ordinary calls and other primitives retain their own planning semantics. All inserted Place translation keyframes inherit their original phase's mode. +PickUp's explicit `cartesian_lift` and Place's `cartesian_approach` are mutually +exclusive with `phase_paths`; conflicting declarations reject before trajectory +generation. `motion_gen` delegates timing to its backend. `ik_interp` needs explicit start/count/dt, rejects backend-specific options and uses minimum-jerk segments diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 98616ebe46..7b8f638419 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -610,6 +610,7 @@ def physical_key(cfg: Any) -> str: "actions", "control_parts", "active_joint_ids", + "scene_preparation", ) if hasattr(cfg, name) } @@ -617,7 +618,7 @@ def physical_key(cfg: Any) -> str: if any(physical_key(cfg) != physical_key(first) for _, cfg in configs[1:]): raise ValueError( - "workloads must share physical environment, robot, sensors, cadence and expert action schema" + "workloads must share physical environment, robot, sensors, cadence, expert action schema and scene preparation" ) owner = source = None diff --git a/embodichain/lab/sim/atomic_skills/primitives/pick_up.py b/embodichain/lab/sim/atomic_skills/primitives/pick_up.py index 566c6488e5..ce65f7fb95 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/pick_up.py +++ b/embodichain/lab/sim/atomic_skills/primitives/pick_up.py @@ -223,7 +223,10 @@ class PickUpOptions(SkillOptions): """ cartesian_lift: bool = False - """Preserve a straight world-Z lift with IK interpolation and native limits.""" + """Preserve a straight world-Z lift with IK interpolation and native limits. + + Mutually exclusive with explicit ``MotionPolicy.phase_paths``. + """ initial_lift_height: float = field(default=0.0, kw_only=True) """Initial world-Z clearance (m) from the current TCP pose before approach.""" @@ -382,6 +385,8 @@ def _get_full_pickup_trajectory( hand_grasp_qpos: torch.Tensor, interpolation_dt: float, ) -> tuple[torch.Tensor, torch.Tensor, dict[str, int]]: + if options.cartesian_lift and motion_policy.phase_paths: + raise ValueError("cartesian_lift and phase_paths are mutually exclusive.") if options.approach_along_grasp_axis: approach_direction = grasp_xpos[:, :3, 2] pre_grasp_xpos = translate_pose_world( diff --git a/tests/lab/expansion/test_gym_workloads.py b/tests/lab/expansion/test_gym_workloads.py index 3df961fe9a..02905565b1 100644 --- a/tests/lab/expansion/test_gym_workloads.py +++ b/tests/lab/expansion/test_gym_workloads.py @@ -39,6 +39,21 @@ pytestmark = pytest.mark.no_sim +def _prepare_cube_scene(cfg, *, x): + """A valid pre-World hook whose parameters alter the prepared scene.""" + from copy import deepcopy + + prepared = deepcopy(cfg) + cube = next(obj for obj in prepared.rigid_object if obj.uid == "cube") + cube.init_pos = (x, *cube.init_pos[1:]) + return prepared + + +def _prepare_cube_scene_offset(cfg, *, x): + """A distinct callable declaration with different scene preparation.""" + return _prepare_cube_scene(cfg, x=x + 0.1) + + @pytest.mark.parametrize("settled", [0, 5]) def test_expired_warming_row_finishes_group_without_disturbing_live_peer( monkeypatch, settled @@ -164,6 +179,9 @@ def propose(*args, **kwargs): "use_action_manager", "active_joint_ids", "joint_order", + "preparation_params", + "preparation_func", + "preparation_same", ], ) def test_workload_action_schema_checked_before_constructing_world( @@ -211,6 +229,18 @@ class ReachedWorld(Exception): config.active_joint_ids = ( [i] if difference == "active_joint_ids" else ([1, 0] if i else [0, 1]) ) + if difference in {"preparation_params", "preparation_func", "preparation_same"}: + from embodichain.lab.gym.envs.managers.cfg import FunctorCfg + + function = ( + "_prepare_cube_scene_offset" + if i and difference == "preparation_func" + else "_prepare_cube_scene" + ) + config.scene_preparation = FunctorCfg( + func=f"{__name__}:{function}", + params={"x": 0.8 if i and difference == "preparation_params" else 0.2}, + ) configs[name] = config # Configured tasks share this implementation class. Selection belongs # to the resolved configs above, never to artificial per-task classes. @@ -241,7 +271,7 @@ class ReachedWorld(Exception): execution = WorkloadExecutionCfg( workload_count=2, batch_size=1, max_steps=20, settling_steps=1 ) - if difference is None: + if difference in (None, "preparation_same"): with pytest.raises(ReachedWorld): run_gym_expansion_workloads( workloads, execution, output_dir=tmp_path / "run" @@ -255,8 +285,9 @@ class ReachedWorld(Exception): factory.assert_not_called() -def test_real_deployments_with_shared_class_reject_different_control_parts( - tmp_path, monkeypatch +@pytest.mark.parametrize("field", ["control_parts", "scene_preparation"]) +def test_real_deployments_reject_incompatible_shared_world_setup( + tmp_path, monkeypatch, field ): from pathlib import Path from embodichain.lab.expansion import ExpansionRunCfg @@ -277,9 +308,17 @@ def test_real_deployments_with_shared_class_reject_different_control_parts( inputs.mkdir() base = load_config(_prepare_deployment(task, inputs)) workloads = [] - for name, parts in (("Arm", ["arm"]), ("ArmEef", ["arm", "eef"])): + settings = ( + (("Arm", ["arm"]), ("ArmEef", ["arm", "eef"])) + if field == "control_parts" + else tuple( + (name, {"func": f"{__name__}:_prepare_cube_scene", "params": {"x": x}}) + for name, x in (("Near", 0.2), ("Far", 0.8)) + ) + ) + for name, value in settings: component = load_config(task.parent / "envs/default.yaml") - component["env"]["control_parts"] = parts + component["env"][field] = value physical = inputs / f"{name}.environment.yaml" physical.write_text(yaml.safe_dump(component)) declaration = { @@ -290,7 +329,11 @@ def test_real_deployments_with_shared_class_reject_different_control_parts( path = inputs / f"{name}.json" path.write_text(json.dumps(declaration)) config = config_to_cfg(declaration, source_path=path) - assert config.control_parts == parts + if field == "control_parts": + assert config.control_parts == value + else: + assert config.scene_preparation.func == value["func"] + assert config.scene_preparation.params == value["params"] assert REGISTERED_ENVS[declaration["id"]].cls is EmbodiedEnv cfg = ExpansionRunCfg( deployment=str(path), diff --git a/tests/sim/atomic_skills/test_actions.py b/tests/sim/atomic_skills/test_actions.py index c2d3391ad9..fc3defc09c 100644 --- a/tests/sim/atomic_skills/test_actions.py +++ b/tests/sim/atomic_skills/test_actions.py @@ -677,8 +677,9 @@ def get_link_pose( env_ids: list[int] | None = None, to_matrix: bool = True, ) -> torch.Tensor: - del env_ids, to_matrix - pose = torch.eye(4).repeat(NUM_ENVS, 1, 1) + del to_matrix + count = NUM_ENVS if env_ids is None else len(env_ids) + pose = torch.eye(4).repeat(count, 1, 1) pose[:, 0, 3] = -1.0 if link_name == "left_root" else 1.0 return pose @@ -745,8 +746,15 @@ def compute_fk( qpos: torch.Tensor | None = None, name: str | None = None, to_matrix: bool = True, + env_ids: list[int] | torch.Tensor | None = None, ) -> torch.Tensor: - count = NUM_ENVS if qpos is None else qpos.shape[0] + count = ( + (NUM_ENVS if env_ids is None else len(env_ids)) + if qpos is None + else qpos.shape[0] + ) + if env_ids is not None: + assert len(env_ids) == count return torch.eye(4).repeat(count, 1, 1) robot.get_qpos.side_effect = get_qpos @@ -2339,6 +2347,58 @@ def generate(states, options=None): ) +@pytest.mark.parametrize("cartesian_lift", [False, True]) +def test_pick_phase_paths_and_cartesian_lift_require_explicit_choice( + cartesian_lift, tmp_path +): + generator = _motion_generator() + # Fixed-grid planning retains the real authored-velocity-limit check. + urdf = tmp_path / "arm.urdf" + urdf.write_text( + '' + + "".join(f'' for i in range(ROBOT_DOF + 1)) + + "".join( + f'' + f'' + '' + for i in range(ROBOT_DOF) + ) + + "" + ) + generator.robot.cfg.fpath = str(urdf) + generator.generate = Mock(wraps=generator.generate) + action = _bind_action(generator, PickUp()) + pose = torch.eye(4).repeat(NUM_ENVS, 1, 1) + invocation = SkillInvocation( + skill_id="pick_up", + goal=GraspGoal(semantics=_semantics(entity_id="target"), grasp_xpos=pose), + binding=_binding(action), + motion_policy=MotionPolicy( + strategy="ik_interp", + sample_count=20, + interpolation_mode="fixed_grid", + ik_seed_mode="sequential", + acceleration_limit=None, + phase_paths={"pre_grasp": "cartesian"}, + ), + skill_options=PickUpOptions(cartesian_lift=cartesian_lift, lift_height=0.1), + ) + context = _context(scene=_target_scene(pose, timestamp=0.0, version=0)) + if cartesian_lift: + with pytest.raises(ValueError, match="cartesian_lift and phase_paths"): + _plan_action(action, invocation, context) + generator.generate.assert_not_called() + else: + _plan_action(action, invocation, context) + assert generator.generate.call_args_list[0].kwargs[ + "options" + ].waypoint_modes == ( + "cartesian", + "joint", + "joint", + ) + + def test_pick_holds_fully_closed_before_lifting_when_configured() -> None: generator = _motion_generator() generator.generate = Mock(wraps=generator.generate) From cba37a4aeab5786c53415ac8ed6644772d459f30 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 05:26:01 +0000 Subject: [PATCH 24/49] fix(expansion): retain reset holds and batch seeded solver paths Keep settling rows controller-active without trajectory or receipt credit. Retain configured grasp preload through coordinated placement. Use explicitly supported preceding-seed path kernels and cooperatively merge compatible requests, preserving active planning budgets and legacy solver fallbacks. Validation: actual reset/grasp negative regressions reproduce on the published SDK; selected-row real path batching passes, motion checks 123 passed, workload integration 3 passed, SSIK checks 2 passed. Five-task repeated physical qualification follows separately. --- .../topics/atomic-actions/atomic-actions.md | 4 + .../topics/expansion-engine/workloads.md | 11 +- .../topics/motion-planning/motion-planning.md | 5 + .../lab/expansion/_planning_batches.py | 5 +- embodichain/lab/expansion/workloads.py | 5 + .../primitives/coordinated_placement.py | 7 +- .../lab/sim/motion/motion_generator.py | 11 ++ .../lab/sim/motion/solvers/base_solver.py | 10 ++ .../lab/sim/motion/solvers/ssik_solver.py | 9 + .../lab/expansion/test_extension_ports_sim.py | 154 ++++++++++++++++++ tests/lab/expansion/test_workloads_sim.py | 13 ++ 11 files changed, 230 insertions(+), 4 deletions(-) diff --git a/agent_context/topics/atomic-actions/atomic-actions.md b/agent_context/topics/atomic-actions/atomic-actions.md index 2dcc7d3636..c538354cfd 100644 --- a/agent_context/topics/atomic-actions/atomic-actions.md +++ b/agent_context/topics/atomic-actions/atomic-actions.md @@ -105,6 +105,10 @@ are calibrated scene inputs. Preserve their selected owners and fingerprints; never infer capabilities or general physical success from a sample name. The host's sampled footprint/support checks remain finite measured acceptance, separate from geometric proposal qualification. +`CoordinatedPlacement` retains each binding's configured grasp command during +approach/hold and on the support hand through release/retreat. Contact-blocked +measured jaw positions cannot replace these closing targets. Measured robot +observations and held-object transforms still supply geometry and validation. ## Recommended change sites diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 3b4a93bfb1..58f6ff49c1 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -74,6 +74,12 @@ can finish incomplete while already-admitted peers continue and export normally. The native source also handles expiry during initial-state validation before atomic session proposal. +Settling rows remain controller-active so Gym consumes their explicit reset +hold targets. They are not live trajectories: only cursor rows receive source +observations, command acknowledgements, trajectory lengths or receipt credit. +Using Gym's inactive measured-qpos substitution during settling would remove +restoring drive error on every tick and change the admitted initial posture. + `started` calls `mark_row_started` after the first actual command. `observe` captures every active T+1 boundary and performs the original physical checks; it returns only active rows needing native safe rejection. The executor retains @@ -95,7 +101,10 @@ Partial quotas remain explicit failures even when some episodes were exported. The optional cooperative planner merges compatible fixed-grid motion requests and pure FK/IK/Jacobian calls. Budget-bearing whole-motion requests keep their -original execution so charge semantics are preserved. Context variables and +original execution so charge semantics are preserved. Solvers declaring the +strong sequential-path capability also merge compatible native path requests, +retaining each row's preceding-valid seed and independently owned results. +Context variables and candidate random streams remain row-local; results are independently owned. Default CPU command gathering shares native numeric reads through a bounded World-owner scope in `sim/objects/backends/_numeric_observations.py`. It ends diff --git a/agent_context/topics/motion-planning/motion-planning.md b/agent_context/topics/motion-planning/motion-planning.md index 8163844115..900db5cad7 100644 --- a/agent_context/topics/motion-planning/motion-planning.md +++ b/agent_context/topics/motion-planning/motion-planning.md @@ -70,6 +70,11 @@ when limits apply. Adaptive timing and batched IK remain defaults. Explicit `fixed_grid` preserves count/intervals and rejects overspeed rows against runtime and authored joint caps; `sequential` retains previous-valid-posture seeds and callback/RNG order. Neither mode is a generic option for other strategies. +Solvers may opt into `supports_sequential_batch_ik` only when their continuous +path hook enumerates the ordinary candidate pool against each preceding valid +seed. SSIK Warp SRS `seed_local` supplies this stronger contract, allowing +bounded path batches instead of Python point dispatch. Other solvers and active +planning budgets retain the original point-query sequence and charging rules. Rejected rows hold their start; `rejected_candidate` retains original samples and rejected-row identity for audit/recovery. A zero-speed hold does not prove diff --git a/embodichain/lab/expansion/_planning_batches.py b/embodichain/lab/expansion/_planning_batches.py index 552e434f2c..87df329d23 100644 --- a/embodichain/lab/expansion/_planning_batches.py +++ b/embodichain/lab/expansion/_planning_batches.py @@ -98,7 +98,10 @@ def __init__(self, robot, seed): self.solve_rng = self._rng() self._restore_rng(previous) for solver in dict.fromkeys(robot._solvers.values()): - for name in ("get_fk", "get_ik", "get_jacobian"): + names = ("get_fk", "get_ik", "get_jacobian") + if getattr(solver, "supports_sequential_batch_ik", False): + names += ("_get_continuous_ik_path",) + for name in names: self._bind(solver, name) from ._motion_batches import MotionBatches diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index 89fca5bd4c..af147937f7 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -585,6 +585,11 @@ def run(self) -> Mapping[str, object]: env.num_envs, dtype=torch.bool, device=env.device ) mask[list(commands)] = True + # Settling rows execute their explicit reset hold. Marking + # them inactive lets Gym replace that target with measured + # qpos at every tick, removing the drive's restoring error. + # They still have no cursor, receipt or acceptance samples. + mask[list(self.warming)] = True env._demo_active_mask = mask before = env.sim.physics_step_index self.observation, _, terminated, truncated, _ = env.step(action) diff --git a/embodichain/lab/sim/atomic_skills/primitives/coordinated_placement.py b/embodichain/lab/sim/atomic_skills/primitives/coordinated_placement.py index 34a7c42dd4..9ad8e0d16b 100644 --- a/embodichain/lab/sim/atomic_skills/primitives/coordinated_placement.py +++ b/embodichain/lab/sim/atomic_skills/primitives/coordinated_placement.py @@ -400,8 +400,11 @@ def failed_with_batching(message: str) -> SkillPlan: placing_place_qpos = placing_approach_traj[:, -1] support_place_qpos = support_approach_traj[:, -1] - placing_hand_qpos = state.last_qpos[:, list(resources.placing_hand.joint_ids)] - support_hand_qpos = state.last_qpos[:, list(resources.support_hand.joint_ids)] + # A contact-blocked measured position does not retain closing effort. + # Both bindings already require a grasp command; use it until release, + # just as MoveHeldObject does for a single held object. + placing_hand_qpos = resources.placing_hand_close_qpos + support_hand_qpos = resources.support_hand_close_qpos approach_trajectory = self._assemble_segment( state.last_qpos, placing_approach_traj, diff --git a/embodichain/lab/sim/motion/motion_generator.py b/embodichain/lab/sim/motion/motion_generator.py index 0da837274a..23fdb63547 100644 --- a/embodichain/lab/sim/motion/motion_generator.py +++ b/embodichain/lab/sim/motion/motion_generator.py @@ -1270,6 +1270,17 @@ def _solve_seeded_cartesian_waypoints( or poses.shape[1] == 0 ): raise ValueError("Cartesian waypoints must have shape (B, N, 4, 4), N > 0.") + solver = self.robot.get_solver(control_part) + from ._budget import _ACTIVE_BUDGET + + if ( + solver is not None + and getattr(solver, "supports_sequential_batch_ik", False) + and _ACTIVE_BUDGET.get() is None + ): + # The solver owns the sequential dependency inside its bounded + # path hook. Do not re-enter Python/Robot once per Cartesian node. + return self._solve_cartesian_waypoints(poses, seed, control_part) success = torch.ones(batch, dtype=torch.bool, device=seed.device) points = [] for index in range(poses.shape[1]): diff --git a/embodichain/lab/sim/motion/solvers/base_solver.py b/embodichain/lab/sim/motion/solvers/base_solver.py index 54e5cbe6e0..4b5cd78402 100644 --- a/embodichain/lab/sim/motion/solvers/base_solver.py +++ b/embodichain/lab/sim/motion/solvers/base_solver.py @@ -531,6 +531,16 @@ def get_tcp(self) -> np.ndarray: """ return self.tcp_xpos + @property + def supports_sequential_batch_ik(self) -> bool: + """Whether continuous batching uses each preceding point-query seed. + + This stronger contract also preserves seed-dependent candidate search. + Merely supporting continuous selection from a fixed candidate pool is + insufficient. Solvers opt in only when their path hook implements it. + """ + return False + @property def supports_continuous_batch_ik(self) -> bool: """Whether all-candidate IK and temporally continuous selection are supported. diff --git a/embodichain/lab/sim/motion/solvers/ssik_solver.py b/embodichain/lab/sim/motion/solvers/ssik_solver.py index c8befce863..8eeb36445e 100644 --- a/embodichain/lab/sim/motion/solvers/ssik_solver.py +++ b/embodichain/lab/sim/motion/solvers/ssik_solver.py @@ -352,6 +352,15 @@ def prepare_buffers(self, max_batch: int) -> None: if provider is not None: provider.prepare_buffers(capacity) + @property + def supports_sequential_batch_ik(self) -> bool: + """Whether the path hook enumerates the ordinary preceding-seed pool.""" + return ( + self.cfg.backend == "warp" + and self.family == "srs" + and self.cfg.srs_search == "seed_local" + ) + @property def supports_continuous_batch_ik(self) -> bool: """Whether candidate generation and previous-frame selection are supported.""" diff --git a/tests/lab/expansion/test_extension_ports_sim.py b/tests/lab/expansion/test_extension_ports_sim.py index 8230db610e..0b4304d017 100644 --- a/tests/lab/expansion/test_extension_ports_sim.py +++ b/tests/lab/expansion/test_extension_ports_sim.py @@ -396,6 +396,159 @@ def test_explicit_phase_paths_and_selected_row_acceptance(tmp_path): assert result.returncode == 0, result.stdout[-3000:] + result.stderr[-5000:] +def _check_coordinated_grasp_targets(env): + """Real selected-row IK keeps commanded preload on contact-blocked hands.""" + import torch + from embodichain.lab.sim.atomic_skills import ( + AntipodalAffordance, + AtomicSkillEngine, + ControlPartCommandProfile, + CoordinatedPlacementGoal, + CoordinatedPlacementOptions, + HeldObjectState, + MotionPolicy, + ObjectSemantics, + SkillInvocation, + TaskState, + ) + from embodichain.lab.sim.motion.motion_generator import ( + MotionGenerator, + MotionGenCfg, + ) + from embodichain.lab.sim.motion.planners.trapezoidal_planner import ( + TrapezoidalPlannerCfg, + ) + + rows = (3, 1) + generator_cfg = MotionGenCfg( + planner_cfg=TrapezoidalPlannerCfg( + robot_uid=env.robot.uid, sim_instance_id=env.sim.instance_id + ) + ) + generator = MotionGenerator(generator_cfg, env_ids=rows) + profiles = {} + for part in ("left_eef", "right_eef"): + limits = env.robot.get_qpos_limits(name=part)[0] + profiles[part] = ControlPartCommandProfile.joint_positions( + open=limits[:, 0], grasp=limits[:, 1] + ) + engine = AtomicSkillEngine(generator, env_ids=rows, control_profiles=profiles) + binding = engine.bind_control_parts( + "coordinated_placement", + { + "placing": {"motion": "left_arm", "grasp": "left_eef"}, + "support": {"motion": "right_arm", "grasp": "right_eef"}, + }, + ) + poses, held = {}, {} + for slot, arm in (("placing", "left_arm"), ("support", "right_arm")): + poses[slot] = env.robot.compute_fk( + qpos=env.robot.get_qpos(name=arm)[list(rows)], + name=arm, + to_matrix=True, + env_ids=rows, + ) + held[binding.endpoint(slot, "motion").task_state_key] = HeldObjectState( + semantics=ObjectSemantics( + entity_id=slot, + label=slot, + geometry={}, + affordance=AntipodalAffordance(), + ), + object_to_eef=torch.eye(4).repeat(2, 1, 1), + grasp_xpos=poses[slot], + ) + context = engine.initial_context( + task=TaskState(batch_size=2, device="cpu", held_objects=held), control_dt=0.04 + ) + before = env.sim.physics_step_index + # The stronger solver capability must preserve actual preceding-seed IK, + # including a failed peer, without losing non-contiguous physical rows. + start = context.robot.qpos[:, env.robot.get_joint_ids("right_arm")] + nodes = start[:, None].repeat(1, 4, 1) + nodes[:, :, 0] += torch.tensor([0.0, 0.01, 0.02, 0.03]) + targets = torch.stack( + [ + env.robot.compute_fk( + qpos=node, name="right_arm", to_matrix=True, env_ids=rows + ) + for node in nodes.unbind(1) + ], + dim=1, + ) + for failed_peer in (False, True): + requested = targets.clone() + if failed_peer: + requested[1, 2, 0, 3] += 100 + seed, points = start, [] + accepted = torch.ones(2, dtype=torch.bool) + for pose in requested.unbind(1): + valid, point = env.robot.compute_ik( + pose=pose, name="right_arm", joint_seed=seed, env_ids=rows + ) + seed = torch.where(valid[:, None], point, seed) + points.append(seed) + accepted &= valid + expected = torch.where( + accepted[:, None, None], torch.stack(points, 1), start[:, None] + ) + valid, actual = generator._solve_seeded_cartesian_waypoints( + requested, start, "right_arm" + ) + assert torch.equal(valid, accepted) + torch.testing.assert_close(actual, expected, rtol=0, atol=1e-6) + from embodichain.lab.expansion._planning_batches import batched_planning + + class PathQuery: + # A numerical request producer, with the real Robot/SSIK implementation. + def __init__(self, index): + self.index = index + + def next(self): + index = self.index + single = MotionGenerator(generator_cfg, env_ids=(rows[index],)) + return single._solve_seeded_cartesian_waypoints( + requested[index : index + 1], start[index : index + 1], "right_arm" + ) + + with batched_planning(env.robot, seed=2) as broker: + answers = broker.gather({row: PathQuery(i) for i, row in enumerate(rows)}) + assert broker.stats["max_group"] == 2 + for index, row in enumerate(rows): + assert torch.equal(answers[row][0], accepted[index : index + 1]) + torch.testing.assert_close( + answers[row][1], expected[index : index + 1], rtol=0, atol=1e-6 + ) + for release in (False, True): + plan = engine.plan( + SkillInvocation( + skill_id="coordinated_placement", + binding=binding, + goal=CoordinatedPlacementGoal( + placing_object_target_pose=poses["placing"], + support_object_target_pose=poses["support"], + ), + motion_policy=MotionPolicy(sample_count=30, strategy="ik_interp"), + skill_options=CoordinatedPlacementOptions( + release=release, lift_height=0, hand_interp_steps=4, retreat_steps=4 + ), + ), + context, + ) + assert plan.success_all, plan.diagnostics + for part in ("left_eef", "right_eef"): + ids = env.robot.get_joint_ids(part) + expected = env.robot.get_qpos_limits(name=part)[0, :, 1] + actual = plan.joint_trajectory.positions[:, :, ids] + if part == "left_eef" and release: + actual = actual[:, : plan.segments[0].stop] + assert not torch.equal(context.robot.qpos[:, ids], expected.expand(2, -1)) + torch.testing.assert_close( + actual, expected.expand_as(actual), rtol=0, atol=0 + ) + assert env.sim.physics_step_index == before + + def _probe_handover_rows(): """Plan and consume selected rows in a larger real handover World.""" import torch @@ -427,6 +580,7 @@ def _probe_handover_rows(): adapters = [] try: env.reset(seed=2) + _check_coordinated_grasp_targets(env) program = env.task_program_adapter.compile(cfg.task_program) bridges = {} for row in (3, 1): diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index eb457d8e5b..419e01dfab 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -193,9 +193,22 @@ def __init__(self): def prepare(self, assignments): assert len(SimulationManager._instances) == 1 + self.reset_holds = getattr(self, "reset_holds", {}) + for assignment in assignments: + self.reset_holds[assignment.env_id] = robot.get_qpos(target=True)[ + assignment.env_id + ].clone() def activate(self, assignment, observation): row = assignment.env_id + # The physical settling ticks must keep the authored drive + # target, rather than repeatedly holding gravity-displaced qpos. + torch.testing.assert_close( + robot.get_qpos(target=True)[row], + self.reset_holds[row], + rtol=0, + atol=0, + ) checks.prepare(env_ids=(row,)) from copy import deepcopy From 4dad7078dd2e568d17fb2520e923debc3258446f Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 08:41:01 +0000 Subject: [PATCH 25/49] feat(expansion): reuse idle rows for bounded retry candidates Keep W times B physical capacity and original attempt/time/byte/step limits. Competing retries reserve only running slots; pending writes and confirmed commits retain the hard quota. Cancel peers through the original command handshake after confirmed persistence, retaining canonical outcomes and measured partial evidence. Preserve phase metadata on safe stops and do not advance an already pending rejection hold twice. Native Task Program jobs enable idle-row reuse; custom sources opt in with an explicit cancellation port. Validation: 41 focused lifecycle, configuration and real simulation checks pass on DexSim rc2. The actual known-bad scheduler copy fails the new unexecuted-hold regression. Independent engine/robotics/verification passes completed; API/context/Black gates pass. Full five-task after measurements follow on an installed VCS package. --- .../expansion-engine/expansion-engine.md | 6 + .../topics/expansion-engine/workloads.md | 23 ++ embodichain/lab/expansion/_gym_episode.py | 45 ++-- .../lab/expansion/_task_program_config.py | 3 + embodichain/lab/expansion/_workload_cursor.py | 10 + embodichain/lab/expansion/engine.py | 34 ++- embodichain/lab/expansion/gym_workloads.py | 61 ++++- embodichain/lab/expansion/session.py | 18 +- .../lab/expansion/task_program_jobs.py | 1 + embodichain/lab/expansion/workloads.py | 100 +++++++- tests/lab/expansion/test_session.py | 89 +++++++ tests/lab/expansion/test_workloads_sim.py | 220 +++++++++++++++++- 12 files changed, 578 insertions(+), 32 deletions(-) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 79a12efc97..e900ef03d3 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -156,6 +156,12 @@ Compatible fixed-grid planning and pure solver requests can be cooperatively merged on the owner thread. Scoped planning budgets retain per-row charges; unsupported requests keep native execution. Export callbacks receive frozen group evidence and never access the World. See [rolling execution](workloads.md). +Optional idle-row reuse keeps the same W×B capacity while competing retry +candidates use otherwise idle slots. Native write reservations still enforce +the original quota; peers are cancelled only after a confirmed receipt, using +measured partial evidence and the bridge's ordinary stop handshake. The low-level +source must supply an explicit cancellation port. Native Task Program jobs enable +this policy by default without adding processes or Worlds. Native numerical evidence has T submitted actions and T+1 measured states. It includes all represented dynamic scene entities, source/action semantics, physical parameters diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 58f6ff49c1..28f45c742d 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -59,6 +59,22 @@ counter so another row cannot advance outside the World-owner loop. Frozen groups export through one bounded writer thread without World access. Fresh output is required; this facade does not resume interrupted collection. +`WorkloadExecutionCfg.reuse_idle_rows` optionally lends unused physical rows to +unfinished groups; capacity remains exactly W times B. Queued groups keep their +normal lane priority. Healthy candidates fill only their remaining quota. Each +observed unsuccessful attempt permits one additional competing candidate, bounded +by the existing attempt, admission-time, settling, step and pending-byte limits. +The low-level flag defaults false; the native Task Program job enables it by +default and accepts `engine.reuse_idle_rows: false` to retain fixed lanes. + +This mode requires a source `cancel(result, *, reason)` port. Only a confirmed +receipt fills quota. Remaining live candidates use the ordinary safe-stop +handshake; unstarted warming rows are cancelled without fabricated commands. +Already completed peers retain their canonical program acceptance in cancelled +diagnostics; they do not become physical failures or successful persisted rows. +The native source retains measured T+1 partial buffers and plan traces, then +releases the native assignment. Cancelled rows earn no receipt or quota credit. + `WorkloadSource.prepare` runs inside the selected-row `episode_prepare` reset callback. It must not step physics, alter an active peer or mutate World-wide appearance/resources. Incompatible topology or shared resources require a @@ -92,6 +108,13 @@ control indices. It assembles the original source evidence and calls count. None is a rejection, never a placeholder success. Unavailable or ambiguous writes retain the ordinary native stage/reconciliation contract and stop the rolling owner from issuing unsupported quota credit. +`ExpansionSession.take_ready(speculative=True)` may reserve competing running +rows while quota is unfilled. Required physical checks are unchanged, and +pending writes plus confirmed commits can never exceed the original target. +`ExpansionEngine.cancel_row` cannot release pending persistence; its existing +reconciliation path still owns uncertain or failed writes. Safe-stop controller +values retain the interrupted invocation/phase metadata for ordinary physical +validators, while their cancellation kind and reason remain explicit. Frozen groups can call `export_expansion_episodes` from bounded writer threads. The callback must not retain mutable live state or operate on the World. diff --git a/embodichain/lab/expansion/_gym_episode.py b/embodichain/lab/expansion/_gym_episode.py index 6eb1f02a83..274be4bbdd 100644 --- a/embodichain/lab/expansion/_gym_episode.py +++ b/embodichain/lab/expansion/_gym_episode.py @@ -37,6 +37,29 @@ __all__: list[str] = [] +def _save_partial(numeric, path: Path, step_dt: float) -> dict: + """Publish actual T+1 buffers for rejected or administratively cancelled work.""" + arrays = { + "qpos": torch.stack(numeric["qpos"]).numpy(), + "timestamps": np.arange(len(numeric["qpos"])) * step_dt, + } + if numeric["actions"]: + arrays["actions"] = torch.stack(numeric["actions"]).numpy() + arrays.update( + { + "object_" + str(index): torch.stack(values).numpy() + for index, values in enumerate(numeric["objects"].values()) + } + ) + with path.open("wb") as stream: + np.savez_compressed(stream, **arrays) + return { + "path": path.name, + "sha256": hashlib.sha256(path.read_bytes()).hexdigest(), + "object_uids": list(numeric["objects"]), + } + + class GymEpisodeAssembler: """Convert frozen cohort buffers into canonical accepted or rejected evidence.""" @@ -73,27 +96,9 @@ def assemble(self, assignments, collector, services, result, physics_after): record["source_execution_reports"] = dict( services[row].tracer.execution_reports ) - partial = records[row] - path = directory / "rejected.npz" - arrays = { - "qpos": torch.stack(partial["qpos"]).numpy(), - "timestamps": np.arange(len(partial["qpos"])) * env.step_dt, - } - if partial["actions"]: - arrays["actions"] = torch.stack(partial["actions"]).numpy() - arrays.update( - { - "object_" + str(index): torch.stack(values).numpy() - for index, values in enumerate(partial["objects"].values()) - } + record["partial_rollout"] = _save_partial( + records[row], directory / "rejected.npz", env.step_dt ) - with path.open("wb") as stream: - np.savez_compressed(stream, **arrays) - record["partial_rollout"] = { - "path": path.name, - "sha256": hashlib.sha256(path.read_bytes()).hexdigest(), - "object_uids": list(partial["objects"]), - } _atomic_json(directory / "attempt.json", record) episodes[row] = None continue diff --git a/embodichain/lab/expansion/_task_program_config.py b/embodichain/lab/expansion/_task_program_config.py index b092888ffc..a4b1518890 100644 --- a/embodichain/lab/expansion/_task_program_config.py +++ b/embodichain/lab/expansion/_task_program_config.py @@ -100,6 +100,7 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: "grasp_nms_chunk_size", "collection_renderer", "collision_backend", + "reuse_idle_rows", }: raise ValueError("Unknown or missing expansion engine settings") engine.setdefault("cpu_threads", 1) @@ -116,6 +117,8 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: engine.setdefault("grasp_nms_chunk_size", 2048) engine.setdefault("collection_renderer", "auto") engine.setdefault("collision_backend", "newton") + if "reuse_idle_rows" in engine and type(engine["reuse_idle_rows"]) is not bool: + raise ValueError("engine.reuse_idle_rows must be a boolean") if engine["collection_renderer"] not in ("auto", "rt", "fast-rt", "hybrid"): raise ValueError( "engine.collection_renderer must be auto, rt, fast-rt or hybrid" diff --git a/embodichain/lab/expansion/_workload_cursor.py b/embodichain/lab/expansion/_workload_cursor.py index b61fe04fea..3a0c04449f 100644 --- a/embodichain/lab/expansion/_workload_cursor.py +++ b/embodichain/lab/expansion/_workload_cursor.py @@ -68,6 +68,16 @@ def next(self) -> ControllerAction | None: try: action = super().next() if action is not None: + if ( + self.rejection is not None or self.emergency is not None + ) and self.last_command is not None: + # The safe-stop value is new; its active invocation and + # phase still belong to the command being interrupted. + # Phase-aware physical validators must see that context. + action = ControllerAction( + action.value, + metadata={**self.last_command.metadata, **action.metadata}, + ) self.last_command = action if self.finished and self.rejection is not None: self.accepted, self.reason = False, self.rejection diff --git a/embodichain/lab/expansion/engine.py b/embodichain/lab/expansion/engine.py index ef38064d6e..1c5db9e250 100644 --- a/embodichain/lab/expansion/engine.py +++ b/embodichain/lab/expansion/engine.py @@ -480,12 +480,16 @@ def on_started(identity: CandidateIdentity) -> None: break return self._snapshot() - def admit_row(self, item: PreparedEpisodeWorkItem) -> ExpansionAssignment | None: + def admit_row( + self, item: PreparedEpisodeWorkItem, *, speculative: bool = False + ) -> ExpansionAssignment | None: """Admit one independently prepared physical row through the native session. Args: item: Host-owned candidate proposed in this session, bound to its actual World row. Cohort collection remains unchanged. + speculative: Permit a competing rollout while quota is unfilled; + persistence still reserves at most the original target count. Returns: Assigned episode/commit identity, or None for rejected preparation @@ -494,6 +498,8 @@ def admit_row(self, item: PreparedEpisodeWorkItem) -> ExpansionAssignment | None """ if self._configured_cfg is not None or self._failed: raise RuntimeError("row admission requires a healthy custom engine") + if type(speculative) is not bool: + raise TypeError("speculative must be a bool") if not isinstance(item, PreparedEpisodeWorkItem): raise TypeError("rolling admission requires PreparedEpisodeWorkItem") if ( @@ -517,6 +523,7 @@ def admit_row(self, item: PreparedEpisodeWorkItem) -> ExpansionAssignment | None identity.initial_state_id, episode_byte_budget=self.cfg.episode_byte_budget, candidate_id=identity.candidate_id, + speculative=speculative, ) if ready is None: self.session.release(identity, reason="row_admission_backpressure") @@ -596,6 +603,31 @@ def complete_row( self._started_rows.discard(row) return receipt + def cancel_row(self, assignment: ExpansionAssignment, *, reason: str) -> None: + """Retire an uncommitted row without a receipt or fabricated rejection. + + Args: + assignment: Exact active identity returned by :meth:`admit_row`. + reason: Explicit cancellation reason retained in native diagnostics. + + Raises: + ValueError: For an inactive row or work with pending persistence. + """ + row = assignment.env_id + if self._row_assignments.get(row) != assignment: + raise ValueError("cancellation does not identify an active rolling row") + if ( + assignment.commit_id in self._pending + or assignment.commit_id in self._submitted + ): + raise ValueError( + "pending persistence must be reconciled before cancellation" + ) + self.session.release(assignment.item.spec.identity, reason=reason) + self._queue.remove(assignment.item) + del self._row_assignments[row] + self._started_rows.discard(row) + def run_source(self, source: ExpansionRecipeSource) -> Mapping[str, object]: """Drive bounded source batches through the same admission/execution/writer core. diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 7b8f638419..2c1d871072 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -106,10 +106,13 @@ def encode(value: Any) -> Any: class _GymWorkloadSource: """Compose existing native admission, frame assembly and persistence owners.""" - def __init__(self, owner: Any, groups: Mapping[str, Any]) -> None: + def __init__( + self, owner: Any, groups: Mapping[str, Any], *, reuse_idle_rows: bool = False + ) -> None: from ._gym_frames import GymFrameCollector self.owner, self.groups, self.env = owner, groups, owner.env + self.reuse_idle_rows = reuse_idle_rows self.collector = GymFrameCollector(owner._context, {}) self.active: dict[int, dict[str, Any]] = {} self.activation_snapshot = None @@ -299,7 +302,7 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: ctx.compatibility.key, row, ) - native = engine.admit_row(item) + native = engine.admit_row(item, speculative=self.reuse_idle_rows) if native is None: ctx.journal.update(request, status="initial_rejected") return None @@ -445,6 +448,56 @@ def complete(self, result: WorkloadRowResult) -> Any: state["adapter"].close() self.collector.discard(row) + def cancel(self, result: WorkloadRowResult, *, reason: str) -> None: + """Retire competing work without changing its canonical program outcome.""" + from ._gym_episode import _save_partial + + row = result.assignment.env_id + state = self.active.pop(row, None) + group = self.groups[result.assignment.workload_id] + ctx = group["host"]._context + request = ctx.requests[row] + record = { + "status": "cancelled", + "reason": reason, + "program_accepted": result.program.accepted[0], + "program_reason": result.program.reasons[0], + "program_segments": result.program.segments[0], + "steps": result.program.lengths[0], + "world_control_start": result.world_control_start, + "world_control_end": result.world_control_end, + } + if state is None: + ctx.journal.update(request, **record) + return + try: + group["engine"].cancel_row(state["native"], reason=reason) + measured = ( + None + if self.owner.collision is None + else self.owner.collision.results.get(row) + ) + if measured is not None: + record["measured_collision"] = { + "status": measured.status, + "reason": measured.reason, + } + if state["factory"] is not None: + record["expansion"] = [ + r.to_metadata() for r in state["factory"].records + ] + record["partial_rollout"] = _save_partial( + self.collector.records[row], + request.directory / "cancelled.npz", + self.env.step_dt, + ) + if row in self.collector.spools: + record["media_manifest"] = str(self.collector.spools[row].finish()) + ctx.journal.update(request, **record) + finally: + state["adapter"].close() + self.collector.discard(row) + def close(self) -> None: for state in self.active.values(): state["adapter"].close() @@ -804,7 +857,9 @@ def admission_clock(admitted_at=admitted_at): "admitted_at": admitted_at, } journal.stage("collection", "running") - source = _GymWorkloadSource(owner, groups) + source = _GymWorkloadSource( + owner, groups, reuse_idle_rows=execution.reuse_idle_rows + ) specs = tuple( ExpansionWorkloadCfg( workload_id=w.workload_id, diff --git a/embodichain/lab/expansion/session.py b/embodichain/lab/expansion/session.py index 8087f9d7b9..53d5248e2a 100644 --- a/embodichain/lab/expansion/session.py +++ b/embodichain/lab/expansion/session.py @@ -564,6 +564,12 @@ def _reserved(self) -> int: for attempt in self._attempts.values() ) + def _write_reserved(self) -> int: + return sum( + attempt.state in {"pending_write", "committed"} + for attempt in self._attempts.values() + ) + def take_ready( self, case_id: str, @@ -571,6 +577,7 @@ def take_ready( *, episode_byte_budget: int | None = None, candidate_id: str | None = None, + speculative: bool = False, ) -> CandidateTrajectoryBatch | EpisodeCandidate | None: """Reserve a row, rollout attempt, and pending payload capacity before execution. @@ -586,12 +593,17 @@ def take_ready( episode_byte_budget: Maximum episode payload bytes to reserve for this row. candidate_id: Optional exact ready candidate to reserve. Omission preserves deterministic FIFO selection within the case. + speculative: Permit competing rollouts for unfilled quota. Payload, + attempt and write reservations still bound execution; only one + passed episode can reserve each remaining persistence slot. Returns: One assigned candidate row, or ``None`` when no matching row or capacity is available or the session has stopped. """ self._cases[(case_id, initial_state_id)] + if type(speculative) is not bool: + raise TypeError("speculative must be a bool") if candidate_id is not None and ( type(candidate_id) is not str or not candidate_id.strip() ): @@ -608,7 +620,8 @@ def take_ready( ) if ( self.stop_reason - or self._reserved() >= self._cfg.collection.target_committed_episodes + or (self._write_reserved() if speculative else self._reserved()) + >= self._cfg.collection.target_committed_episodes or self._counts["rollout_attempted"] + assigned >= self._cfg.collection.max_rollout_attempts or pending_count >= self._cfg.persistence.pending_episode_limit @@ -761,6 +774,9 @@ def accept_episode(self, episode: ExpertEpisode) -> bool: if self._episode_bytes(episode) > attempt.episode_byte_budget: self.release(episode.identity, reason="episode_byte_budget_exceeded") raise BufferError("Payload exceeds its reserved episode byte budget.") + if self._write_reserved() >= self._cfg.collection.target_committed_episodes: + self.release(episode.identity, reason="quota_reserved_by_peer") + return False owned = replace(episode) if not self._reserve_coverage(owned): self.release(episode.identity, reason="coverage_rejected") diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index 4576457c4f..23d8a1a755 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -403,6 +403,7 @@ def _run_operators( max_steps=settings["max_steps"], settling_steps=settings["settling_steps"], seed=seed, + reuse_idle_rows=settings.get("reuse_idle_rows", True), ) chunks = settings["grasp_nms_chunk_size"] if torch.cuda.is_available() else 2048 with pose_nms_scope(chunk_size=chunks): diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index af147937f7..b655d02175 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -93,6 +93,10 @@ class WorkloadExecutionCfg: settling_steps: Minimum physical substeps before a row becomes active. seed: Base seed; each candidate owns a stream keyed by local ordinal. batch_planning: Cooperatively merge compatible native motion/solver calls. + reuse_idle_rows: Let unfinished groups borrow otherwise idle rows. A + rejected attempt permits one additional competing candidate, bounded + by physical capacity and the original admission budgets. Sources must + implement ``cancel(result, *, reason)`` without returning a receipt. """ workload_count: int = 1 @@ -101,6 +105,7 @@ class WorkloadExecutionCfg: settling_steps: int = 5 seed: int = 0 batch_planning: bool = True + reuse_idle_rows: bool = False def __post_init__(self) -> None: for name in ("workload_count", "batch_size", "max_steps"): @@ -111,6 +116,8 @@ def __post_init__(self) -> None: raise ValueError(f"{name} must be a nonnegative integer") if type(self.batch_planning) is not bool: raise TypeError("batch_planning must be a bool") + if type(self.reuse_idle_rows) is not bool: + raise TypeError("reuse_idle_rows must be a bool") @property def num_envs(self) -> int: @@ -160,6 +167,9 @@ class WorkloadSource(Protocol): after all required checks pass and native persistence confirms the write. Callbacks must not advance physics or create another World. A completed group's frozen evidence can be exported independently of the live World. + Idle-row reuse additionally requires ``cancel(result, *, reason) -> None``. + That port retires uncommitted native work and preserves the canonical + program result; administrative cancellation never earns quota. """ def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: @@ -239,6 +249,8 @@ def __init__( if len(self.workloads) != len(workloads) or cfg.workload_count > len(workloads): raise ValueError("workload IDs must be unique and cover every active lane") self.cfg, self.source = WorkloadExecutionCfg(**cfg.to_dict()), source + if cfg.reuse_idle_rows and not callable(getattr(source, "cancel", None)): + raise TypeError("idle-row reuse requires a native source cancellation port") self.checkpoint, self.on_workload_done = checkpoint, on_workload_done self.owner = get_ident() from embodichain.lab.sim import SimulationManager @@ -279,6 +291,8 @@ def __init__( self.hold = self.env.robot.get_qpos(target=True).clone() self.observation = None self.planning_stats: dict[str, int] = {} + self.reused_rows = 0 + self.cancelled = {name: 0 for name in self.workloads} self.torch = torch @property @@ -349,6 +363,36 @@ def _fill(self) -> None: self.started_at.setdefault(name, time.monotonic()) self.warming[row] = {"assignment": assignment, "settled": 0} added.append(assignment) + if self.cfg.reuse_idle_rows: + for row in range(self.cfg.num_envs): + if row in self.live or row in self.warming: + continue + candidates = [] + for name in dict.fromkeys(self.lanes): + if name is None or not self._eligible(name): + continue + counts = self.counts[name] + inflight = self._inflight(name) + failed = counts["attempts"] - counts["committed"] - inflight + demand = ( + self.workloads[name].target_episodes + - counts["committed"] + + failed + ) + if inflight < demand: + candidates.append((inflight, counts["attempts"], name)) + if not candidates: + break + name = min(candidates)[2] + counts = self.counts[name] + assignment = WorkloadAssignment( + name, counts["attempts"], row, self.cfg.seed + counts["attempts"] + ) + counts["attempts"] += 1 + self.started_at.setdefault(name, time.monotonic()) + self.warming[row] = {"assignment": assignment, "settled": 0} + added.append(assignment) + self.reused_rows += 1 if not added: return self.refills += bool(self.live) @@ -439,9 +483,15 @@ def _finish(self, row: int) -> None: (cursor.reason,), (tuple(cursor.results),), ) - receipt = self.source.complete( - WorkloadRowResult(assignment, result, state["start"], end) - ) + row_result = WorkloadRowResult(assignment, result, state["start"], end) + cancelled = state.get("cancel_reason") + if cancelled: + if getattr(self.source, "cancel")(row_result, reason=cancelled) is not None: + raise ValueError("cancelled work cannot earn a receipt") + self.cancelled[assignment.workload_id] += 1 + receipt = None + else: + receipt = self.source.complete(row_result) if receipt is not None: if ( not isinstance(receipt, CommitReceipt) @@ -463,6 +513,41 @@ def _finish(self, row: int) -> None: self.counts[assignment.workload_id]["committed"] += 1 cursor.close() del self.live[row] + name = assignment.workload_id + if ( + receipt is not None + and self.cfg.reuse_idle_rows + and self.counts[name]["committed"] == self.workloads[name].target_episodes + ): + self._cancel_peers(name) + + def _cancel_peers(self, name: str) -> None: + from .program import ProgramBatchResult + + reason = "quota_fulfilled_by_peer" + for state in self.live.values(): + if state["assignment"].workload_id == name and not state.get( + "cancel_reason" + ): + state["cancel_reason"] = reason + cursor = state["cursor"] + # An existing rejection/stop already yielded its next real + # hold during gather. Do not resume and acknowledge it twice. + state["replace_command"] = ( + not cursor.finished + and cursor.rejection is None + and cursor.emergency is None + ) + state["cursor"].abort(reason) + for row, state in tuple(self.warming.items()): + if state["assignment"].workload_id != name: + continue + outcome = ProgramBatchResult((row,), (0,), (False,), (reason,), ((),)) + result = WorkloadRowResult(state["assignment"], outcome, None, None) + if getattr(self.source, "cancel")(result, reason=reason) is not None: + raise ValueError("cancelled preparation cannot earn a receipt") + self.cancelled[name] += 1 + del self.warming[row] def run(self) -> Mapping[str, object]: """Collect until every group meets quota or exhausts its original budget. @@ -525,6 +610,13 @@ def run(self) -> Mapping[str, object]: ) for row in tuple(commands): cursor = self.live[row]["cursor"] + if self.live[row].pop("replace_command", False): + replacement = cursor.next() + if replacement is None: + del commands[row] + self._finish(row) + continue + commands[row] = replacement if ( cursor.length >= self.cfg.max_steps and cursor.emergency is None @@ -644,6 +736,8 @@ def run(self) -> Mapping[str, object]: self.counts[name]["committed"] == spec.target_episodes for name, spec in self.workloads.items() ), + "reused_rows": self.reused_rows, + "cancelled": dict(self.cancelled), "num_envs": self.cfg.num_envs, "workload_count": self.cfg.workload_count, "batch_size": self.cfg.batch_size, diff --git a/tests/lab/expansion/test_session.py b/tests/lab/expansion/test_session.py index d8c802989d..c3301850dc 100644 --- a/tests/lab/expansion/test_session.py +++ b/tests/lab/expansion/test_session.py @@ -59,6 +59,95 @@ def test_old_and_new_session_paths_export_the_identical_class(): assert ExpansionSession.__module__ == "embodichain.lab.expansion.session" +def test_competing_rollouts_keep_one_pending_write_and_confirmed_quota(): + session = ExpansionSession( + ExpansionSessionCfg.from_mapping( + { + "collection": { + "target_committed_episodes": 1, + "max_proposals": 3, + "max_rollout_attempts": 3, + }, + "execution": {"ready_high_watermark": 3, "ready_low_watermark": 0}, + "persistence": {"pending_episode_limit": 2, "pending_max_bytes": 4096}, + } + ) + ) + session.register_case( + SceneCase("case", "initial", "scene", "task", "robot"), + torch.tensor([[-1.0, 1.0]]), + joint_names=("joint",), + ) + passed = ValidationResult( + ( + ValidationCheck("path_collision", "passed"), + ValidationCheck("task_success", "passed"), + ) + ) + episodes = [] + for index in range(2): + identity, _ = session.propose( + "case", + "initial", + source_id="source", + source_revision="v1", + template_id=f"recipe{index}", + operator_id="episode", + ) + session.add_prepared_episode(EpisodeCandidate(identity, "{}"), passed) + if index: + assert ( + session.take_ready( + "case", + "initial", + episode_byte_budget=2048, + candidate_id=identity.candidate_id, + ) + is None + ) + assert ( + session.take_ready( + "case", + "initial", + episode_byte_budget=2048, + candidate_id=identity.candidate_id, + speculative=True, + ) + is not None + ) + session.mark_rollout_started(identity) + episode_id, commit_id = session.episode_ids(identity) + episodes.append( + ExpertEpisode( + identity, + {"joint_positions": torch.tensor([[0.0], [0.1]])}, + torch.tensor([[0.1]]), + torch.tensor([0.0, 0.1]), + "qpos", + passed, + episode_id, + commit_id, + ) + ) + assert session.accept_episode(episodes[0]) + # Even before the writer confirms its receipt, the second qualified row + # cannot reserve or write the only quota slot. + assert not session.accept_episode(episodes[1]) + assert session.snapshot()["counts"]["validated_accepted"] == 1 + episode = episodes[0] + receipt = CommitReceipt( + episode.episode_id, + episode.identity.candidate_id, + episode.identity.attempt_id, + "stored", + episode.commit_id, + "case", + ) + assert session.apply_receipt(receipt) + assert not session.apply_receipt(receipt) + assert session.snapshot()["counts"]["committed"] == 1 + + @pytest.mark.parametrize("legacy", [False, True]) def test_explicit_policy_keeps_legacy_trajectory_dedup_and_generic_episode_credit( legacy, diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index 419e01dfab..ed2ddaf50b 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -588,6 +588,215 @@ def validator(env, output): assert not SimulationManager._instances +def _reuse_probe(output: str) -> None: + """A real rejected installation opens reuse, then only one receipt wins.""" + import json + import numpy as np + import torch + from embodichain.lab.expansion import ( + ArtifactEpisodeSink, + ExpansionRunCfg, + GymExpansionHostExtensions, + GymExpansionWorkload, + WorkloadExecutionCfg, + run_gym_expansion_workloads, + load_expansion_episode, + ) + from embodichain.lab.expansion.collision import _MeasuredCollision + from embodichain.lab.sim.scene.expansion import SceneVariant + from embodichain.lab.sim.scene.feasibility import ( + JointSceneCandidate, + RobotDeploymentCandidate, + ) + from embodichain.lab.sim import SimulationManager + from embodichain.lab.expansion._planning_batches import PlanningBatches + from embodichain.utils.utility import load_config + import yaml + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + task = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/repeated_pick_place" + ) + path = Path(output) + path.mkdir(exist_ok=True) + raw = load_config(task / "task.ur5.yaml") + + def absolute(value, base): + if isinstance(value, dict): + return {k: absolute(v, base) for k, v in value.items()} + if isinstance(value, list): + return [absolute(v, base) for v in value] + if isinstance(value, str) and value.endswith((".yaml", ".yml", ".json")): + return str((base / value).resolve()) + return value + + raw = absolute(raw, task) + program = yaml.safe_load((task / "task_program/program.yaml").read_text()) + program["program"]["repeat"]["count"] = 1 + program_path = path / "program.yaml" + program_path.write_text(yaml.safe_dump(program)) + raw["task_program"]["program"] = str(program_path) + deployment = path / "deployment.yaml" + deployment.write_text(yaml.safe_dump(raw)) + + def scenes(env): + nominal = env.robot.get_local_pose(to_matrix=True)[0].cpu().tolist() + + class Source: + def candidate(self, ordinal): + pose = np.array(nominal) + if ordinal == 0: + pose[2, 3] -= 0.6 + elif ordinal == 2: + pose[0, 3] += 0.02 + return JointSceneCandidate( + "retry", + SceneVariant("retry", 2, ordinal, ()), + RobotDeploymentCandidate({env.robot.uid: pose.tolist()}), + "installation", + (), + ) + + return Source() + + cfg = ExpansionRunCfg( + deployment=str(deployment), + output_dir=str(path / "group"), + batch_size=1, + target_episodes=1, + max_attempts=6, + max_steps=2500, + max_wall_time_s=180, + settling_steps=5, + seed=2, + ) + workload = GymExpansionWorkload( + "retry", + cfg, + { + "job_id": "retry", + "semantic_id": "retry", + "execution_id": "retry", + "recipe_revision": "v1", + "input_files": {}, + "runtime_versions": {}, + }, + {}, + GymExpansionHostExtensions(scene_source_factory=scenes), + ) + original_gather = PlanningBatches.gather + boundary = {"injected": False, "executed": False} + + def gather(broker, cursors): + actions = original_gather(broker, cursors) + if not boundary["injected"] and any( + c.finished and c.accepted for c in cursors.values() + ): + for row, cursor in cursors.items(): + if row not in actions or cursor.finished: + continue + # Exercise the real host-stop path before quota completion; + # the controlled administrative stop is not fake physics. + cursor.abort("test_stop_before_peer_quota") + hold = cursor.next() + assert hold is not None + actions[row] = hold + boundary.update( + injected=True, + row=row, + cursor=cursor, + clock=cursor.bridge.clock.step_index, + hold=hold, + ) + break + return actions + + def validator(env, output): + original_step = env.step + + def step(action, *args, **kwargs): + pending = boundary["injected"] and not boundary["executed"] + if pending: + assert boundary["cursor"].bridge.clock.step_index == boundary["clock"] + actual = ( + action.value + if isinstance(action.value, torch.Tensor) + else action.value["qpos"] + ) + expected = boundary["hold"].value + expected = ( + expected if isinstance(expected, torch.Tensor) else expected["qpos"] + ) + torch.testing.assert_close( + actual[boundary["row"]], expected[0], rtol=0, atol=0 + ) + result = original_step(action, *args, **kwargs) + if pending: + boundary["executed"] = True + return result + + env.step = step + return _MeasuredCollision( + env, + str(root / "examples/expansion/scene_robot_feasibility/search.ur5.yaml"), + output, + ) + + PlanningBatches.gather = gather + try: + result = run_gym_expansion_workloads( + (workload,), + WorkloadExecutionCfg( + workload_count=1, + batch_size=2, + max_steps=2500, + settling_steps=5, + seed=2, + reuse_idle_rows=True, + ), + extensions=GymExpansionHostExtensions(validator_factory=validator), + output_dir=path / "execution", + ) + finally: + PlanningBatches.gather = original_gather + assert boundary["injected"] and boundary["executed"] + assert result["complete"] and result["reused_rows"] > 0, result + assert result["counts"]["retry"]["committed"] == 1 + assert result["cancelled"]["retry"] > 0 + assert result["num_envs"] == 2 and result["world"]["world_count"] == 1 + receipts = ArtifactEpisodeSink(path / "group").inspect() + assert len(receipts) == 1 + episode = load_expansion_episode(receipts[0].storage_id) + assert ( + episode.validation.accepted + and len(episode.timestamps) == len(episode.actions) + 1 + ) + records = [ + json.loads(p.read_text()) + for p in (path / "group/attempts").glob("*/attempt.json") + ] + assert next(r for r in records if r["ordinal"] == 0)["status"] in { + "initial_rejected", + "rejected", + } + cancelled = [ + p + for p in (path / "group/attempts").glob("*/attempt.json") + if json.loads(p.read_text())["status"] == "cancelled" + ] + assert cancelled + for entry in cancelled: + record = json.loads(entry.read_text()) + assert record["reason"] == "quota_fulfilled_by_peer" + if "partial_rollout" in record: + with np.load(entry.parent / record["partial_rollout"]["path"]) as data: + assert len(data["qpos"]) == record["steps"] + 1 + assert len(data.get("actions", [])) == record["steps"] + assert not SimulationManager._instances + + def _declarative_probe(output: str) -> None: import json from embodichain.lab.expansion import ( @@ -619,7 +828,7 @@ def _declarative_probe(output: str) -> None: @pytest.mark.requires_sim -@pytest.mark.parametrize("mode", ["executor", "facade", "declarative"]) +@pytest.mark.parametrize("mode", ["executor", "facade", "declarative", "reuse"]) def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path, mode): result = subprocess.run( [sys.executable, __file__, str(tmp_path), mode], @@ -633,6 +842,9 @@ def test_rolling_workloads_keep_native_receipts_and_world_boundaries(tmp_path, m if __name__ == "__main__": - {"executor": _probe, "facade": _facade_probe, "declarative": _declarative_probe}[ - sys.argv[2] if len(sys.argv) > 2 else "executor" - ](sys.argv[1]) + { + "executor": _probe, + "facade": _facade_probe, + "declarative": _declarative_probe, + "reuse": _reuse_probe, + }[sys.argv[2] if len(sys.argv) > 2 else "executor"](sys.argv[1]) From db388b3b7732442dacd58a2c63c37ced1e021eea Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 09:31:08 +0000 Subject: [PATCH 26/49] fix(expansion): retain owner-proven holds after terminal runtime A finished runtime may still have its last ordinary motion awaiting env.step. Keep the default fail-closed abort contract, but allow the joint controller owner to supply actual applied target positions when no runtime safe hold exists. Never reuse the pending motion or acknowledge before real physics consumption. Retain the interrupted phase when terminal fields are empty, and keep the last actual scalar controller metadata and row identity in cancelled diagnostics without per-step serialization. Validation: 12 focused abort, safe-hold and actual reuse cases pass on rc2; full bottle trigger and repeated five-task qualification follow on the installed revision. Independent reviews completed. --- .../topics/expansion-engine/workloads.md | 6 ++++ embodichain/lab/expansion/_workload_cursor.py | 25 ++++++++++++++-- embodichain/lab/expansion/gym_workloads.py | 14 +++++++++ .../lab/gym/envs/task_program/bridge.py | 29 ++++++++++++++++++- tests/lab/expansion/test_workloads_sim.py | 3 ++ 5 files changed, 74 insertions(+), 3 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 28f45c742d..097fb4ae48 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -115,6 +115,12 @@ pending writes plus confirmed commits can never exceed the original target. reconciliation path still owns uncertain or failed writes. Safe-stop controller values retain the interrupted invocation/phase metadata for ordinary physical validators, while their cancellation kind and reason remain explicit. +When a runtime is already terminal with a final unconsumed motion, the joint +controller owner supplies its actual already-applied position targets and zero +velocity through the abort callback's optional `controller_hold`. The bridge +prefers a runtime-generated hold, never relabels pending motion, and advances +the clock only after the fallback hold receives a real `env.step`. Without an +explicit owner-proven hold, the existing fail-closed abort behavior remains. Frozen groups can call `export_expansion_episodes` from bounded writer threads. The callback must not retain mutable live state or operate on the World. diff --git a/embodichain/lab/expansion/_workload_cursor.py b/embodichain/lab/expansion/_workload_cursor.py index 3a0c04449f..92a1633c2f 100644 --- a/embodichain/lab/expansion/_workload_cursor.py +++ b/embodichain/lab/expansion/_workload_cursor.py @@ -76,7 +76,15 @@ def next(self) -> ControllerAction | None: # Phase-aware physical validators must see that context. action = ControllerAction( action.value, - metadata={**self.last_command.metadata, **action.metadata}, + metadata={ + **self.last_command.metadata, + **{ + key: value + for key, value in action.metadata.items() + if value is not None + or key not in self.last_command.metadata + }, + }, ) self.last_command = action if self.finished and self.rejection is not None: @@ -96,7 +104,7 @@ def next(self) -> ControllerAction | None: def abort(self, reason: str) -> None: if self.finished or self.rejection is not None or self.emergency is not None: return - if not self.pending_consumed: + if not self.pending_consumed and self.last_command is None: # An unconsumed command must go through the original safe-stop # iterator; acknowledging it here would manufacture a World step. super().abort(reason) @@ -111,5 +119,18 @@ def abort(self, reason: str) -> None: if "qvel" in previous: fields["qvel"] = torch.zeros_like(hold) value = TensorDict(fields, batch_size=[len(ids)]) + if not self.pending_consumed: + self.reason = reason + self.emergency = iter( + self.segment.abort_actions( + reason, + last_action_consumed=False, + controller_hold=ControllerAction( + value, + metadata={"bridge_action_kind": "runtime_abort_safe_hold"}, + ), + ) + ) + return self.bridge.request_row_rejection(ids, ControllerAction(value), reason=reason) self.rejection = reason diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 2c1d871072..c26a9d953e 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -362,6 +362,14 @@ def observe( for name in {a.workload_id for a in assignments}: self.groups[name]["host"]._context.journal.checkpoint() self.collector.observe(ids, action, observation) + if self.reuse_idle_rows: + row_metadata = action.metadata.get("row_actions", {}) + for row in ids: + # Retain one already-owned metadata view, rather than copying + # command histories on the control hot path. + self.active[row]["last_controller_metadata"] = row_metadata.get( + str(row), {} + ) checks = self.owner.collision return tuple( row @@ -458,6 +466,7 @@ def cancel(self, result: WorkloadRowResult, *, reason: str) -> None: ctx = group["host"]._context request = ctx.requests[row] record = { + "env_id": row, "status": "cancelled", "reason": reason, "program_accepted": result.program.accepted[0], @@ -472,6 +481,11 @@ def cancel(self, result: WorkloadRowResult, *, reason: str) -> None: return try: group["engine"].cancel_row(state["native"], reason=reason) + record["last_controller_metadata"] = { + key: value + for key, value in state.get("last_controller_metadata", {}).items() + if value is None or type(value) in (str, int, float, bool) + } measured = ( None if self.owner.collision is None diff --git a/embodichain/lab/gym/envs/task_program/bridge.py b/embodichain/lab/gym/envs/task_program/bridge.py index 5ee67cc941..ae38d02e77 100644 --- a/embodichain/lab/gym/envs/task_program/bridge.py +++ b/embodichain/lab/gym/envs/task_program/bridge.py @@ -2095,12 +2095,14 @@ def abort( reason: str, *, last_action_consumed: bool, + controller_hold: ControllerAction | None = None, ) -> Iterator[ControllerAction]: return self._abort_segment( segment, lifecycle, reason=reason, last_action_consumed=last_action_consumed, + controller_hold=controller_hold, ) return abort @@ -2112,12 +2114,28 @@ def _abort_segment( *, reason: str, last_action_consumed: bool, + controller_hold: ControllerAction | None = None, ) -> Iterator[ControllerAction]: - """Abort one segment, surfacing a safe hold only after controller activity.""" + """Abort after activity, preferring runtime-proven controller holds. + + A trusted controller owner may supply an explicit labelled hold when + the runtime became terminal before its final yielded motion was + consumed. Pending motion alone is never promoted to a safe stop. + """ if type(reason) is not str or not reason: raise ValueError("abort reason must be a non-empty string.") if type(last_action_consumed) is not bool: raise TypeError("last_action_consumed must be a bool.") + if controller_hold is not None: + if not isinstance(controller_hold, ControllerAction): + raise TypeError("controller_hold must be a ControllerAction or None.") + if ( + controller_hold.metadata.get("bridge_action_kind") + not in _SAFE_HOLD_ACTION_KINDS + ): + raise ValueError( + "controller_hold requires an explicit safe-hold action kind." + ) if lifecycle.abort_started: raise RuntimeError( f"Segment {segment.segment_id!r} abort handshake already started." @@ -2181,6 +2199,15 @@ def _abort_segment( safe_action = self._sink.drain_safe_stop_action( fallback=None if last_action_consumed else pending, ) + if safe_action is None and controller_hold is not None: + # A controller owner can prove a hold even after a runtime has + # become terminal while its final motion is still unconsumed. + # Never treat that pending motion itself as a safe stop. + held = controller_hold.snapshot() + safe_action = ControllerAction( + held.value, + metadata={**held.metadata, "abort_hold_source": "controller_owner"}, + ) if safe_action is None: raise TaskProgramBridgeError( f"Segment {segment.segment_id!r} stopped before exhaustion, but " diff --git a/tests/lab/expansion/test_workloads_sim.py b/tests/lab/expansion/test_workloads_sim.py index ed2ddaf50b..95b79fc8a7 100644 --- a/tests/lab/expansion/test_workloads_sim.py +++ b/tests/lab/expansion/test_workloads_sim.py @@ -791,6 +791,9 @@ def step(action, *args, **kwargs): record = json.loads(entry.read_text()) assert record["reason"] == "quota_fulfilled_by_peer" if "partial_rollout" in record: + assert record["env_id"] in (0, 1) + if record["steps"]: + assert record["last_controller_metadata"].get("bridge_action_kind") with np.load(entry.parent / record["partial_rollout"]["path"]) as data: assert len(data["qpos"]) == record["steps"] + 1 assert len(data.get("actions", [])) == record["steps"] From 9e29ad63abb96af1026b82ad72353f52eac38d0f Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 09:57:29 +0000 Subject: [PATCH 27/49] fix(expansion): keep speculative retry reuse opt-in --- agent_context/topics/expansion-engine/workloads.md | 6 ++++-- embodichain/lab/expansion/task_program_jobs.py | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 097fb4ae48..2593368236 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -64,8 +64,10 @@ unfinished groups; capacity remains exactly W times B. Queued groups keep their normal lane priority. Healthy candidates fill only their remaining quota. Each observed unsuccessful attempt permits one additional competing candidate, bounded by the existing attempt, admission-time, settling, step and pending-byte limits. -The low-level flag defaults false; the native Task Program job enables it by -default and accepts `engine.reuse_idle_rows: false` to retain fixed lanes. +The low-level flag and native Task Program job both default false. Enable +reuse explicitly with `engine.reuse_idle_rows: true`. On +CPU-bound planning, competing retries may increase total work despite higher +row occupancy; validate qualified output per wall time before enabling reuse. This mode requires a source `cancel(result, *, reason)` port. Only a confirmed receipt fills quota. Remaining live candidates use the ordinary safe-stop diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index 23d8a1a755..2fa1ad6b1e 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -403,7 +403,7 @@ def _run_operators( max_steps=settings["max_steps"], settling_steps=settings["settling_steps"], seed=seed, - reuse_idle_rows=settings.get("reuse_idle_rows", True), + reuse_idle_rows=settings.get("reuse_idle_rows", False), ) chunks = settings["grasp_nms_chunk_size"] if torch.cuda.is_available() else 2048 with pose_nms_scope(chunk_size=chunks): From 86303c7a5f9bbbc7fb6a9e1dff73ce3d66126a6a Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 17 Nov 2026 11:35:00 +0000 Subject: [PATCH 28/49] fix(expansion): compare effective scene preparation defaults Resolve scene preparation with the same precedence as EmbodiedEnv: explicit config first, registered defaults second. Normalize registered declarations through an owned FunctorCfg before shared-World compatibility checks. Extend real deployment coverage for mismatched and identical registration defaults, explicit overrides, and equivalent explicit/registered declarations. Preserve single-workload validation behavior and document the effective-hook contract. --- .../topics/expansion-engine/workloads.md | 6 +- embodichain/lab/expansion/gym_workloads.py | 61 ++++++------ tests/lab/expansion/test_gym_workloads.py | 92 ++++++++++++++----- 3 files changed, 107 insertions(+), 52 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 2593368236..511afaa956 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -43,8 +43,10 @@ World, captures the original seeded nominal scene in row zero, and composes the existing session, frame collector, episode assembler and confirmed artifact sink. Different integration/grasp policies may share that World only when their physical configuration, program, cadence and expert action schema agree. The -scene-preparation declaration and its parameters must also match, because the -common nominal scene is prepared once before constructing the World. +effective scene-preparation declaration and its parameters must also match: +explicit configuration wins over the environment's registered default, following +`EmbodiedEnv` construction. The common nominal scene is prepared once before +constructing the World. Command mode, ActionManager declarations and controlled-joint selections cannot vary between workloads in one World. Selections belong to the resolved environment configurations, not the shared registered environment implementation class. Physical/visual/prototype diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index c26a9d953e..e818f96574 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -555,6 +555,7 @@ def run_gym_expansion_workloads( from .persistence import ArtifactEpisodeSink, load_expansion_episode from .workflow import _RecordedSink from .episode_export import export_expansion_episodes + from embodichain.lab.gym.envs.managers.cfg import FunctorCfg from embodichain.lab.gym.utils.gym_utils import config_to_cfg from embodichain.lab.gym.utils.registration import REGISTERED_ENVS from embodichain.utils.utility import load_config @@ -647,43 +648,49 @@ def run_gym_expansion_workloads( ) first = configs[0][1] - def physical_key(cfg: Any) -> str: + def physical_key(env_id: str, cfg: Any) -> str: robot = deepcopy(cfg.robot.to_dict()) for binding in robot.get("gripper_bindings", {}).values(): binding["declaration"].pop("root_from_contact_frame", None) binding["defaults"].pop("root_from_contact_frame", None) binding["defaults"].get("binding", {}).pop("root_from_contact_frame", None) + physical = { + name: getattr(cfg, name) + for name in ( + "robot", + "sim_cfg", + "rigid_object", + "background", + "target_control_frequency", + "sim_steps_per_control", + "events", + "sensor", + "expert_trajectory", + "actions", + "control_parts", + "active_joint_ids", + "scene_preparation", + ) + if hasattr(cfg, name) + } + physical["robot"] = robot + # EmbodiedEnv uses the registration default only without an explicit + # hook. Normalize both routes without mutating either declaration. + if physical.get("scene_preparation") is None: + default = REGISTERED_ENVS[env_id].default_kwargs.get("scene_preparation") + if default is not None: + physical["scene_preparation"] = FunctorCfg(**deepcopy(default)) return _hash( { - name: ( - robot - if name == "robot" - else ( - getattr(cfg, name).to_dict() - if hasattr(getattr(cfg, name), "to_dict") - else getattr(cfg, name) - ) - ) - for name in ( - "robot", - "sim_cfg", - "rigid_object", - "background", - "target_control_frequency", - "sim_steps_per_control", - "events", - "sensor", - "expert_trajectory", - "actions", - "control_parts", - "active_joint_ids", - "scene_preparation", - ) - if hasattr(cfg, name) + name: value.to_dict() if hasattr(value, "to_dict") else value + for name, value in physical.items() } ) - if any(physical_key(cfg) != physical_key(first) for _, cfg in configs[1:]): + if any( + physical_key(raw["id"], cfg) != physical_key(configs[0][0]["id"], first) + for raw, cfg in configs[1:] + ): raise ValueError( "workloads must share physical environment, robot, sensors, cadence, expert action schema and scene preparation" ) diff --git a/tests/lab/expansion/test_gym_workloads.py b/tests/lab/expansion/test_gym_workloads.py index 02905565b1..0c7737e906 100644 --- a/tests/lab/expansion/test_gym_workloads.py +++ b/tests/lab/expansion/test_gym_workloads.py @@ -189,7 +189,7 @@ def test_workload_action_schema_checked_before_constructing_world( ): from embodichain.lab.expansion import ExpansionRunCfg from embodichain.lab.gym.envs.expert_trajectory import ExpertTrajectoryCfg - from embodichain.lab.gym.utils.registration import REGISTERED_ENVS + from embodichain.lab.gym.utils.registration import REGISTERED_ENVS, EnvSpec import embodichain.lab.gym.utils.gym_utils as utils import embodichain.lab.expansion.host as host @@ -244,7 +244,7 @@ class ReachedWorld(Exception): configs[name] = config # Configured tasks share this implementation class. Selection belongs # to the resolved configs above, never to artificial per-task classes. - monkeypatch.setitem(REGISTERED_ENVS, name, SimpleNamespace(cls=EmbodiedEnv)) + monkeypatch.setitem(REGISTERED_ENVS, name, EnvSpec(name, EmbodiedEnv)) cfg = ExpansionRunCfg( deployment=str(deployment), output_dir=str(tmp_path / name), @@ -285,16 +285,37 @@ class ReachedWorld(Exception): factory.assert_not_called() -@pytest.mark.parametrize("field", ["control_parts", "scene_preparation"]) -def test_real_deployments_reject_incompatible_shared_world_setup( - tmp_path, monkeypatch, field +@pytest.mark.parametrize( + "field,registered_x,explicit_x,compatible", + [ + ("control_parts", (None, None), (None, None), False), + ("scene_preparation", (None, None), (0.2, 0.8), False), + ("scene_preparation", (0.2, 0.8), (None, None), False), + ("scene_preparation", (0.2, 0.2), (None, None), True), + ("scene_preparation", (0.2, 0.8), (0.4, 0.4), True), + ("scene_preparation", (None, 0.2), (0.2, None), True), + ], + ids=[ + "control_parts", + "explicit_preparation_mismatch", + "registered_preparation_mismatch", + "registered_preparation_same", + "explicit_preparation_overrides_defaults", + "explicit_matches_registered_preparation", + ], +) +def test_real_deployments_validate_shared_world_setup( + tmp_path, monkeypatch, field, registered_x, explicit_x, compatible ): from pathlib import Path from embodichain.lab.expansion import ExpansionRunCfg from embodichain.lab.expansion.task_program_jobs import _prepare_deployment from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv from embodichain.lab.gym.utils.gym_utils import config_to_cfg - from embodichain.lab.gym.utils.registration import REGISTERED_ENVS + from embodichain.lab.gym.utils.registration import ( + REGISTERED_ENVS, + register_env_function, + ) from embodichain.utils.utility import load_config import embodichain.lab.expansion.host as host @@ -308,17 +329,16 @@ def test_real_deployments_reject_incompatible_shared_world_setup( inputs.mkdir() base = load_config(_prepare_deployment(task, inputs)) workloads = [] - settings = ( - (("Arm", ["arm"]), ("ArmEef", ["arm", "eef"])) - if field == "control_parts" - else tuple( - (name, {"func": f"{__name__}:_prepare_cube_scene", "params": {"x": x}}) - for name, x in (("Near", 0.2), ("Far", 0.8)) - ) - ) - for name, value in settings: + + def preparation(x): + return {"func": f"{__name__}:_prepare_cube_scene", "params": {"x": x}} + + for i, name in enumerate(("first", "second")): component = load_config(task.parent / "envs/default.yaml") - component["env"][field] = value + if field == "control_parts": + component["env"][field] = ["arm"] if i == 0 else ["arm", "eef"] + elif explicit_x[i] is not None: + component["env"][field] = preparation(explicit_x[i]) physical = inputs / f"{name}.environment.yaml" physical.write_text(yaml.safe_dump(component)) declaration = { @@ -330,11 +350,27 @@ def test_real_deployments_reject_incompatible_shared_world_setup( path.write_text(json.dumps(declaration)) config = config_to_cfg(declaration, source_path=path) if field == "control_parts": - assert config.control_parts == value + assert config.control_parts == component["env"][field] + elif explicit_x[i] is None: + assert config.scene_preparation is None else: - assert config.scene_preparation.func == value["func"] - assert config.scene_preparation.params == value["params"] - assert REGISTERED_ENVS[declaration["id"]].cls is EmbodiedEnv + assert config.scene_preparation.func == preparation(explicit_x[i])["func"] + assert config.scene_preparation.params == {"x": explicit_x[i]} + spec = REGISTERED_ENVS[declaration["id"]] + # Keep the real configured integration and ordinary environment class, + # but register task-owned defaults through the supported entry point. + register_env_function( + EmbodiedEnv, + declaration["id"], + override=True, + max_episode_steps=spec.max_episode_steps, + task_program_adapter_factory=spec.task_program_adapter_factory, + **( + {"scene_preparation": preparation(registered_x[i])} + if registered_x[i] is not None + else {} + ), + ) cfg = ExpansionRunCfg( deployment=str(path), output_dir=str(tmp_path / name), @@ -353,9 +389,16 @@ def test_real_deployments_reject_incompatible_shared_world_setup( {}, ) ) - constructor = Mock(side_effect=AssertionError("World must not be constructed")) + + class ReachedWorld(Exception): + pass + + constructor = Mock(side_effect=ReachedWorld) monkeypatch.setattr(host, "GymExpansionHost", constructor) - with pytest.raises(ValueError, match="schema"): + with pytest.raises( + ReachedWorld if compatible else ValueError, + match=None if compatible else "workloads must share", + ): run_gym_expansion_workloads( workloads, WorkloadExecutionCfg( @@ -363,4 +406,7 @@ def test_real_deployments_reject_incompatible_shared_world_setup( ), output_dir=tmp_path / "run", ) - constructor.assert_not_called() + if compatible: + constructor.assert_called_once() + else: + constructor.assert_not_called() From 5c557e82b610d5ecf837209cce8966f4d0901eb1 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 03:31:52 +0000 Subject: [PATCH 29/49] feat(expansion): add workspace pose coverage and distribution reports --- .../expansion-engine/expansion-engine.md | 15 + .../topics/expansion-engine/workloads.md | 20 + .../topics/scene-expansion/scene-expansion.md | 6 + docs/source/api_reference/public_api.rst | 15 + embodichain/lab/expansion/_distribution.html | 39 + embodichain/lab/expansion/_distribution.py | 337 +++++++++ .../lab/expansion/_distribution_pose.py | 141 ++++ embodichain/lab/expansion/_gym_context.py | 1 + embodichain/lab/expansion/_pose_cells.py | 90 +++ embodichain/lab/expansion/_pose_sampling.py | 712 ++++++++++++++++++ .../lab/expansion/_pose_sampling_cfg.py | 162 ++++ .../lab/expansion/_task_program_config.py | 14 +- embodichain/lab/expansion/_workload_cursor.py | 39 +- embodichain/lab/expansion/distribution.md | 65 ++ embodichain/lab/expansion/gym_workloads.py | 81 +- embodichain/lab/expansion/host.py | 2 + embodichain/lab/expansion/host_extensions.py | 9 +- .../lab/expansion/task_pose_coverage.py | 240 ++++++ .../lab/expansion/task_program_jobs.py | 76 +- embodichain/lab/expansion/workloads.py | 12 +- .../lab/task_program/compiler/lowering.py | 2 +- .../task_program/integrations/feasibility.py | 138 +++- .../workspace_pose_pick_place/README.md | 109 +++ .../env.obstacle.yaml | 93 +++ .../workspace_pose_pick_place/env.yaml | 81 ++ .../workspace_pose_pick_place/expansion.yaml | 201 +++++ .../task.obstacle.ur5.yaml | 19 + .../workspace_pose_pick_place/task.ur5.yaml | 19 + .../task_program/integration.yaml | 47 ++ .../task_program/program.yaml | 44 ++ .../benchmark/expansion/task_pose_coverage.py | 540 +++++++++++++ .../expansion/test_task_pose_report.py | 78 ++ tests/lab/expansion/test_distribution.py | 165 ++++ .../lab/expansion/test_task_pose_coverage.py | 595 +++++++++++++++ .../task_program/test_semantic_compiler.py | 27 + 35 files changed, 4154 insertions(+), 80 deletions(-) create mode 100644 embodichain/lab/expansion/_distribution.html create mode 100644 embodichain/lab/expansion/_distribution.py create mode 100644 embodichain/lab/expansion/_distribution_pose.py create mode 100644 embodichain/lab/expansion/_pose_cells.py create mode 100644 embodichain/lab/expansion/_pose_sampling.py create mode 100644 embodichain/lab/expansion/_pose_sampling_cfg.py create mode 100644 embodichain/lab/expansion/distribution.md create mode 100644 embodichain/lab/expansion/task_pose_coverage.py create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/README.md create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.obstacle.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/expansion.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.obstacle.ur5.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.ur5.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/integration.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/program.yaml create mode 100644 scripts/benchmark/expansion/task_pose_coverage.py create mode 100644 tests/benchmark/expansion/test_task_pose_report.py create mode 100644 tests/lab/expansion/test_distribution.py create mode 100644 tests/lab/expansion/test_task_pose_coverage.py diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index e900ef03d3..0928121f21 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -207,3 +207,18 @@ measured state plus explicitly labeled FK, and pure-visual children retain their physical parent's clock. Qualification requires admitted operator evidence, not just a requested profile or completed nominal episodes. Report completeness and capability acceptance are separate, including diagnostic unsupported combinations. + +## Offline distribution reports + +`python -m embodichain.lab.expansion._distribution` compares explicit before/after +confirmed job directories using the existing receipt inspector and episode loader. +It emits structured JSON/JSONL and a standalone HTML report with world-XY layout +bins, start/end joint counts, measured object paths, joint-motion summaries, and +existing geometry descriptor buckets. Version 2 adds full SO(3) orientation +features and recorded-URDF TCP FK with explicit gripper calibration. A lightweight +index drives filters; 100-record detail pages are shared by the offline viewer +and Agent JSON consumers. Matching task/robot/scene domains are required. +The report distinguishes cumulative additions from independent cohorts; observed +bins are not a feasible-volume certificate. The reader uses existing artifact +validation dependencies but creates no World. See +[distribution usage](../../../embodichain/lab/expansion/distribution.md). diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 511afaa956..9edead8cc6 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -184,6 +184,26 @@ limitations remain explicit admission constraints. Physics devices and task qualification must be reported separately. Existing CPU deployments do not switch devices. +## Optional task-pose proposal feedback + +Task-facing expansion configs select `scene_sampling.strategy` (`bounded_pose` +or `workspace_joint`) independently of `scheduling.policy` (`fifo` or +`task_pose_coverage`). Absent settings preserve the legacy bounded sampler. +`_pose_sampling.py` owns bounded candidate snapshots, source feedback and budgets; +`task_pose_coverage.TaskPoseCoverage` implements the session coverage protocol. +Measured rigid initial/terminal poses contribute only after native sink receipts. +Separate SceneCase identities aggregate within a declared configuration/grid +fingerprint; installation changes remain separate domains. FIFO can omit coverage. + +Joint sampling uses an explicit cache or joint-uniform FK prior and repeats +full-pose IK/FK checks after planar projection. Fixed pick grasp policy and prior +must agree; unsupported dynamic grasp replacement rejects. Normal scene preparation, +planning, measured acceptance and persistence still determine success. Feedback +checkpoints do not restore a live World or replace job receipt reconciliation. +The configured acceptance task is +`extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place`; +its four-way runner is `scripts/benchmark/expansion/task_pose_coverage.py`. + ## Focused validation `tests/lab/expansion/test_workloads_sim.py` runs a real four-row task through diff --git a/agent_context/topics/scene-expansion/scene-expansion.md b/agent_context/topics/scene-expansion/scene-expansion.md index bc4ecbf6c2..f2bf1e517b 100644 --- a/agent_context/topics/scene-expansion/scene-expansion.md +++ b/agent_context/topics/scene-expansion/scene-expansion.md @@ -28,6 +28,12 @@ Joint task-conditioned layout/installation search is owned by attempts. Its configured search adapter still evaluates one B=1 deployment per attempt through the shared selected-row preparation/restoration contract. +The task-facing rolling collector also exposes selectable bounded versus +workspace-conditioned pose proposals with optional receipt-confirmed task-pose +coverage feedback; see [workload feedback](../expansion-engine/workloads.md#optional-task-pose-proposal-feedback). +This is distinct from offline atlas region validation and does not certify +continuous reachable volume. + ## Entry points | Request | Owner | diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index 0c93def98d..4a931a2a43 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -6321,3 +6321,18 @@ contracts. The package-level imports above are the convenient extension API. discover_sensor_plugins get_sensor_registration list_sensor_types + +Task pose coverage +------------------ + +The task pose coverage adapter counts measured pick/place XY-yaw cells across +scene cases in one explicitly declared experiment domain. Reservations remain +pending until the ordinary ExpansionSession persistence receipt confirms them; +planned candidate poses never contribute to confirmed coverage. + +.. autosummary:: + + embodichain.lab.expansion.task_pose_coverage.TaskPoseCoverage + +.. autoclass:: embodichain.lab.expansion.task_pose_coverage.TaskPoseCoverage + :members: diff --git a/embodichain/lab/expansion/_distribution.html b/embodichain/lab/expansion/_distribution.html new file mode 100644 index 0000000000..af699051a1 --- /dev/null +++ b/embodichain/lab/expansion/_distribution.html @@ -0,0 +1,39 @@ +任务数据分布 + +
EMBODICHAIN / DATA OBSERVATORY

任务数据分布

从空间覆盖到运动多样性,检查每一轮数据补充。
确认落盘 · 实测证据

+ +

空间覆盖地图

世界坐标 XY / m;点击区域筛选实测轨迹。颜色深浅表示确认样本数。

稀疏密集 · 前后共用色标
按网格选择样本

代表轨迹联动

来源与现有预览入口
+

起点 × 终点联合分布

点击计数筛选该组合;零表示无确认数据,不代表不可行。只展示两快照中出现过的区域。

+

完整姿态分布

SO(3) 规范旋转向量三维分箱,步长 30°,非等体积;不合并物体对称姿态。

补数前后对照

数据说明与导出

本报告是 HTML 入口。分页明细位于 pages/;分享时请保留整个目录。

    Agent 结构化结果 · 前快照特征 · 后快照特征
    + diff --git a/embodichain/lab/expansion/_distribution.py b/embodichain/lab/expansion/_distribution.py new file mode 100644 index 0000000000..c2c25cc99b --- /dev/null +++ b/embodichain/lab/expansion/_distribution.py @@ -0,0 +1,337 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Offline confirmed-episode distribution analysis and linked HTML report. + +Run with ``python -m embodichain.lab.expansion._distribution --help``. +""" + +from __future__ import annotations + +import argparse +from collections import Counter +from copy import deepcopy +import hashlib +import json +from pathlib import Path +from typing import Any +import numpy as np + +__all__: list[str] = [] + + +def _digest(value: Any) -> str: + return hashlib.sha256( + json.dumps(value, sort_keys=True, allow_nan=False).encode() + ).hexdigest() + + +def _cell(pose: list[float], cell_size: float) -> str: + return ",".join(str(int(x)) for x in np.floor(np.asarray(pose[:2]) / cell_size)) + + +def _motion(points: np.ndarray, times: np.ndarray) -> dict: + if points.ndim != 2 or points.shape[0] != len(times) or len(times) < 2: + raise ValueError("Motion requires aligned T+1 points and timestamps") + if ( + not np.isfinite(points).all() + or not np.isfinite(times).all() + or np.any(np.diff(times) <= 0) + ): + raise ValueError("Motion must be finite with increasing timestamps") + lengths = np.linalg.norm(np.diff(points, axis=0), axis=1) + arc = np.r_[0.0, np.cumsum(lengths)] + keep = np.r_[True, np.diff(arc) > 1e-12] + grid = np.linspace(0, arc[-1], 32) + path = np.stack( + [np.interp(grid, arc[keep], points[keep, i]) for i in range(points.shape[1])], + axis=1, + ) + return { + "path_length": float(arc[-1]), + "duration_s": float(times[-1] - times[0]), + "speed_p50_p95": np.quantile(lengths / np.diff(times), [0.5, 0.95]).tolist(), + "path": path.tolist(), + } + + +def _summarize(rows: list[dict], size: float, minimum: int) -> dict: + unique = {} + for row in rows: + key = row["commit_id"] + if key in unique and unique[key] != row: + raise ValueError("Conflicting commit identity") + unique[key] = deepcopy(row) + rows = list(unique.values()) + pick, place, joint = Counter(), Counter(), Counter() + for row in rows: + if row["object_motion"] is None: + continue + a, b = _cell(row["initial_pose"], size), _cell(row["final_pose"], size) + pick[a] += 1 + place[b] += 1 + joint[a + "|" + b] += 1 + row["pick_cell"], row["place_cell"] = a, b + distributions = {} + for family in ("object_motion", "joint_motion", "tcp_motion"): + for metric in ("path_length", "duration_s"): + values = [ + r[family][metric] for r in rows if r.get(family) and metric in r[family] + ] + distributions[family + "." + metric] = { + "valid_count": len(values), + "missing_count": len(rows) - len(values), + "p0_p25_p50_p75_p100": ( + np.quantile(values, [0, 0.25, 0.5, 0.75, 1]).tolist() + if values + else None + ), + } + orientation_counts = {} + for phase in ("initial", "final"): + orientation_counts[phase] = dict( + Counter( + r["orientation"]["rotation_bin_" + phase] + for r in rows + if r.get("orientation") + ) + ) + return { + "orientation": orientation_counts, + "tcp_valid": sum(r.get("tcp_motion") is not None for r in rows), + "motion_distributions": distributions, + "episodes": rows, + "count": len(rows), + "layout_valid": sum(pick.values()), + "layout_missing": len(rows) - sum(pick.values()), + "pick": dict(pick), + "place": dict(place), + "joint": dict(joint), + "joint_at_minimum": sum(n >= minimum for n in joint.values()), + "unique_geometry_buckets": len( + {r["geometry_bucket"] for r in rows if r["geometry_bucket"]} + ), + "geometry_missing": sum(r["geometry_bucket"] is None for r in rows), + } + + +def _read(paths: list[Path], entity: str) -> tuple[list[dict], list[str]]: + from .persistence import ArtifactEpisodeSink, load_expansion_episode + + from ._distribution_pose import RecordedTCP, orientation + + rows, domains = [], [] + for directory in dict.fromkeys(p.resolve() for p in paths): + if not (directory / "job.json").is_file(): + raise ValueError(f"Expected confirmed job directory: {directory}") + job = json.loads((directory / "job.json").read_text()) + deployment = job.get("resolved_deployment", {}) + tcp = RecordedTCP(deployment) + for receipt in ArtifactEpisodeSink(directory).inspect(): + if not receipt.confirmed: + continue + episode = load_expansion_episode(receipt.storage_id) + if not episode.validation.accepted: + raise ValueError("Confirmed episode lacks acceptance") + meta = episode.metadata + # Fixed topology, installation and task identity; sampled object poses are features. + robot = [ + dict(uid=s["uid"], joints=list(s["joint_names"]), pose=list(s["pose"])) + for s in meta.get("initial_state", ()) + if s["kind"] == "robot" + ] + domain = _digest( + { + "robot": robot, + "instruction": meta.get("instruction"), + "backend": meta.get("physics_backend"), + "deployment_robot": deployment.get("robot"), + "scene_topology": [ + (v["uid"], v["kind"], v["body_type"]) + for v in meta.get("initial_state", ()) + ], + "scene_configuration": { + k: deployment.get(k) + for k in ("rigid_object", "background", "physics_config") + }, + } + ) + domains.append(domain) + times = episode.timestamps.cpu().numpy() + state = episode.observations.get(f"rigid/{entity}/state") + motion = ( + None if state is None else _motion(state.cpu().numpy()[:, :3], times) + ) + q = episode.observations.get("full_joint_positions") + joint_motion = None if q is None else _motion(q.cpu().numpy(), times) + descriptor = meta.get("coverage_descriptor") + bucket = None + if descriptor: + bucket = _digest( + [ + list(descriptor["phase_ids"]), + np.rint(np.asarray(descriptor["geometry"]) / 0.001) + .astype(int) + .tolist(), + ] + ) + tcp_poses = tcp.poses(episode) + rows.append( + { + "episode_id": episode.episode_id, + "commit_id": episode.commit_id, + "artifact": receipt.storage_id, + "job": str(directory), + "domain_id": domain, + "source_episode_uuid": meta.get("source_episode_uuid"), + "initial_pose": None if state is None else state[0, :7].tolist(), + "final_pose": None if state is None else state[-1, :7].tolist(), + "orientation": ( + None + if state is None + else orientation(state.cpu().numpy(), times) + ), + "tcp_motion": ( + None if tcp_poses is None else _motion(tcp_poses[:, :3], times) + ), + "tcp_orientation": ( + None if tcp_poses is None else orientation(tcp_poses, times) + ), + "tcp_evidence": ( + {"unavailable": tcp.reason} if tcp.reason else tcp.evidence + ), + "object_motion": motion, + "joint_motion": joint_motion, + "geometry_bucket": bucket, + } + ) + return rows, sorted(set(domains)) + + +def _run( + before: list[Path], + after: list[Path], + output: Path, + entity: str, + size: float, + minimum: int, +) -> None: + if not np.isfinite(size) or size <= 0 or minimum < 1: + raise ValueError("Positive cell size and minimum count required") + if output.exists(): + raise FileExistsError("Use a new output directory") + b, bd = _read(before, entity) + a, ad = _read(after, entity) + if not b or not a or bd != ad or len(bd) != 1: + raise ValueError( + "Comparison requires nonempty snapshots of one matching domain" + ) + report = { + "schema_version": 2, + "feature_version": "se3-world-object-joint-tcp-v2", + "entity": entity, + "coordinate_frame": "world", + "cell_size_m": size, + "minimum": minimum, + "domain_id": bd[0], + "before": _summarize(b, size, minimum), + "after": _summarize(a, size, minimum), + } + report["comparison_kind"] = ( + "cumulative" + if {r["commit_id"] for r in b} <= {r["commit_id"] for r in a} + else "independent_cohorts" + ) + keys = sorted(set(report["before"]["joint"]) | set(report["after"]["joint"])) + report["comparison"] = [ + { + "cell": k, + "before": report["before"]["joint"].get(k, 0), + "after": report["after"]["joint"].get(k, 0), + "deficit": max(0, minimum - report["after"]["joint"].get(k, 0)), + } + for k in keys + ] + report["limitations"] = [ + "XY bins cover observed domain only; no feasible-volume denominator.", + "TCP is recorded-URDF FK from measured qpos/root plus explicit gripper TCP calibration.", + "Orientation bins: canonical SO(3) rotation vectors, 30-degree Cartesian bins, not equal-volume; no symmetry folding.", + "Joint path length mixes joint coordinates; compare only matching domains.", + "Geometry buckets reuse existing 1e-3 descriptor quantization, not clustering.", + ] + report["snapshot_id"] = _digest(report) + output.mkdir(parents=True) + # Detail pages are shared by the web viewer and Agent; summaries retain only an index. + pages = output / "pages" + pages.mkdir() + for name in ("before", "after"): + rows = report[name]["episodes"] + for start in range(0, len(rows), 100): + chunk = rows[start : start + 100] + payload = json.dumps(chunk, ensure_ascii=False, allow_nan=False).replace( + "<", "\\u003c" + ) + key = f"{name}-{start//100}" + (pages / f"{key}.json").write_text(payload) + (pages / f"{key}.js").write_text( + f"window.distributionPage({json.dumps(key)},{payload});" + ) + with (output / f"{name}-episodes.jsonl").open("w") as f: + for row in rows: + f.write(json.dumps(row, ensure_ascii=False, allow_nan=False) + "\n") + report[name]["episodes"] = [ + dict( + episode_id=row["episode_id"], + commit_id=row["commit_id"], + initial_pose=row["initial_pose"], + final_pose=row["final_pose"], + object_motion=row["object_motion"] is not None, + pick_cell=row.get("pick_cell"), + place_cell=row.get("place_cell"), + page=f"{name}-{i//100}", + ) + for i, row in enumerate(rows) + ] + (output / "summary.json").write_text( + json.dumps(report, ensure_ascii=False, indent=2, allow_nan=False) + ) + template = Path(__file__).with_name("_distribution.html").read_text() + (output / "report.html").write_text( + template.replace( + "__REPORT__", + json.dumps(report, ensure_ascii=False, allow_nan=False).replace( + "<", "\\u003c" + ), + ) + ) + + +def _main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--before", type=Path, nargs="+", required=True) + parser.add_argument("--after", type=Path, nargs="+", required=True) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--entity", default="cube") + parser.add_argument("--cell-size", type=float, default=0.1) + parser.add_argument("--minimum", type=int, default=5) + args = parser.parse_args() + _run( + args.before, args.after, args.output, args.entity, args.cell_size, args.minimum + ) + + +if __name__ == "__main__": + _main() diff --git a/embodichain/lab/expansion/_distribution_pose.py b/embodichain/lab/expansion/_distribution_pose.py new file mode 100644 index 0000000000..9558c4ff1b --- /dev/null +++ b/embodichain/lab/expansion/_distribution_pose.py @@ -0,0 +1,141 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Full orientation features and recorded-model TCP reconstruction.""" + +from __future__ import annotations +from pathlib import Path +import hashlib +import numpy as np +from scipy.spatial.transform import Rotation + +__all__: list[str] = [] + + +def orientation(poses: np.ndarray, times: np.ndarray) -> dict: + q = np.asarray(poses, dtype=float)[:, 3:7] + if ( + q.shape != (len(times), 4) + or not np.isfinite(q).all() + or np.any(np.linalg.norm(q, axis=1) < 1e-12) + ): + raise ValueError("Orientation requires finite nonzero xyzw quaternions") + rot = Rotation.from_quat(q) + canonical = rot.as_quat(canonical=True) + vectors = rot.as_rotvec() + angle = (rot[:-1].inv() * rot[1:]).magnitude() + dt = np.diff(times) + if np.any(dt <= 0): + raise ValueError("Increasing orientation times required") + return { + "initial_xyzw": canonical[0].tolist(), + "final_xyzw": canonical[-1].tolist(), + "initial_rotvec_rad": vectors[0].tolist(), + "final_rotvec_rad": vectors[-1].tolist(), + "angular_path_rad": float(angle.sum()), + "angular_speed_p50_p95": np.quantile(angle / dt, [0.5, 0.95]).tolist(), + "net_rotation_rad": float((rot[0].inv() * rot[-1]).magnitude()), + "rotation_bin_initial": ",".join( + map(str, np.floor((vectors[0] + np.pi) / (np.pi / 6)).astype(int)) + ), + "rotation_bin_final": ",".join( + map(str, np.floor((vectors[-1] + np.pi) / (np.pi / 6)).astype(int)) + ), + } + + +class RecordedTCP: + """Cache one recorded URDF chain; reconstruct in bounded 256-frame batches.""" + + def __init__(self, deployment: dict): + import pytorch_kinematics as pk + + robot = deployment.get("robot") or {} + bindings = list((robot.get("gripper_bindings") or {}).values()) + self.reason = None + if len(bindings) != 1: + self.reason = "single_explicit_gripper_binding_required" + return + binding = bindings[0] + self.link = binding.get("root_link") + transform = binding.get("defaults", {}).get("default_root_from_tcp") + asset = robot.get("fpath") + if not self.link or transform is None or not asset or not Path(asset).is_file(): + self.reason = "recorded_tcp_calibration_or_asset_missing" + return + self.offset = np.asarray(transform, dtype=float) + if ( + self.offset.shape != (4, 4) + or not np.isfinite(self.offset).all() + or not np.allclose(self.offset[3], [0, 0, 0, 1]) + or not np.allclose( + self.offset[:3, :3].T @ self.offset[:3, :3], np.eye(3), atol=1e-6 + ) + or not np.isclose(np.linalg.det(self.offset[:3, :3]), 1) + ): + raise ValueError("Invalid TCP transform") + if robot.get("body_scale") not in (None, [1.0, 1.0, 1.0]): + self.reason = "scaled_robot_not_supported" + return + content = Path(asset).read_bytes() + self.chain = pk.build_chain_from_urdf(content) + self.names = self.chain.get_joint_parameter_names() + self.evidence = { + "method": "fk_from_measured_qpos_and_root", + "root_link": self.link, + "root_from_tcp": self.offset.tolist(), + "urdf_sha256": hashlib.sha256(content).hexdigest(), + } + + def poses(self, episode) -> np.ndarray | None: + import torch + + if self.reason: + return None + robots = [ + s for s in episode.metadata.get("initial_state", ()) if s["kind"] == "robot" + ] + if len(robots) != 1: + raise ValueError("TCP requires one recorded robot") + robot = robots[0] + fields = { + s["field"]: s["key"] + for s in episode.metadata["scene_state_fields"] + if s["entity_uid"] == robot["uid"] + } + q = episode.observations[fields["qpos"]].cpu() + roots = episode.observations[fields["pose"]].cpu().numpy() + indices = [list(robot["joint_names"]).index(n) for n in self.names] + out = [] + with torch.no_grad(): + for start in range(0, len(q), 256): + local = ( + self.chain.forward_kinematics( + q[start : start + 256, indices].float() + )[self.link] + .get_matrix() + .numpy() + @ self.offset + ) + rp = roots[start : start + 256] + world = np.broadcast_to(np.eye(4), local.shape).copy() + world[:, :3, :3] = Rotation.from_quat(rp[:, 3:]).as_matrix() + world[:, :3, 3] = rp[:, :3] + tcp = world @ local + out.append( + np.c_[tcp[:, :3, 3], Rotation.from_matrix(tcp[:, :3, :3]).as_quat()] + ) + return np.concatenate(out) diff --git a/embodichain/lab/expansion/_gym_context.py b/embodichain/lab/expansion/_gym_context.py index 0ae951c4af..70ce0d8b48 100644 --- a/embodichain/lab/expansion/_gym_context.py +++ b/embodichain/lab/expansion/_gym_context.py @@ -72,6 +72,7 @@ class GymHostContext: auxiliary_baseline: Mapping[str, torch.Tensor] | None = None profile: Real2SimTabletopCollectionCfg | None = None scene_source: JointSceneSource | None = None + feedback: Any | None = None motion_profile: CombinedExpansionProfile | None = None motion_recipes: tuple[CandidateRecipe, ...] = () names: tuple[str, ...] = () diff --git a/embodichain/lab/expansion/_pose_cells.py b/embodichain/lab/expansion/_pose_cells.py new file mode 100644 index 0000000000..2340e7cbc8 --- /dev/null +++ b/embodichain/lab/expansion/_pose_cells.py @@ -0,0 +1,90 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Pure XY/yaw grid validation and symmetric pose quantization.""" + +from __future__ import annotations +import math +from collections.abc import Mapping +import numpy as np + +__all__: list[str] = [] + + +def _grid(value: Mapping) -> dict: + if not isinstance(value, Mapping) or set(value) != { + "lower", + "upper", + "cell_size", + "yaw_period", + }: + raise ValueError("Pose grids require lower, upper, cell_size and yaw_period") + lower, upper, size = ( + np.asarray(value[k], dtype=float) for k in ("lower", "upper", "cell_size") + ) + period = value["yaw_period"] + if any(a.shape != (3,) or not np.isfinite(a).all() for a in (lower, upper, size)): + raise ValueError("Pose grid coordinates must be three finite numbers") + if type(period) not in (int, float) or not math.isfinite(period) or period <= 0: + raise ValueError("yaw_period must be finite and positive") + if period > 2 * math.pi or not math.isclose( + 2 * math.pi / period, round(2 * math.pi / period), rel_tol=0, abs_tol=1e-8 + ): + raise ValueError("yaw_period must divide a complete turn") + if ( + np.any(upper <= lower) + or np.any(size <= 0) + or not math.isclose(upper[2] - lower[2], period) + ): + raise ValueError("Pose grids need positive extents and one complete yaw period") + bins = (upper - lower) / size + if not np.allclose(bins, np.round(bins), rtol=0, atol=1e-8): + raise ValueError("Pose grid extents must be divisible by cell_size") + return { + "lower": lower.tolist(), + "upper": upper.tolist(), + "cell_size": size.tolist(), + "yaw_period": float(period), + } + + +def _pose_cell(pose, grid: Mapping) -> tuple[int, int, int] | None: + value = np.asarray(pose, dtype=float) + if value.shape == (4, 4): + x, y = value[:2, 3] + yaw = math.atan2(value[1, 0], value[0, 0]) + elif value.ndim == 1 and value.shape[0] >= 7: + x, y = value[:2] + q = value[3:7] + norm = np.linalg.norm(q) + if not math.isfinite(norm) or norm < 1e-12: + raise ValueError("Pose quaternion must be finite and nonzero") + qx, qy, qz, qw = q / norm + yaw = math.atan2(2 * (qw * qz + qx * qy), 1 - 2 * (qy * qy + qz * qz)) + else: + raise ValueError("Expected a pose matrix or xyz/xyzw state") + if not np.isfinite(value).all(): + raise ValueError("Pose must be finite") + lo, hi, size = (np.asarray(grid[k]) for k in ("lower", "upper", "cell_size")) + point = np.array([x, y, (yaw - lo[2]) % grid["yaw_period"] + lo[2]]) + if np.any(point[:2] < lo[:2] - 1e-7) or np.any(point[:2] > hi[:2] + 1e-7): + return None + bins = np.rint((hi - lo) / size).astype(int) + return tuple( + np.minimum( + bins - 1, np.maximum(0, np.floor((point - lo) / size).astype(int)) + ).tolist() + ) diff --git a/embodichain/lab/expansion/_pose_sampling.py b/embodichain/lab/expansion/_pose_sampling.py new file mode 100644 index 0000000000..99e2eaf5a4 --- /dev/null +++ b/embodichain/lab/expansion/_pose_sampling.py @@ -0,0 +1,712 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Selectable bounded and workspace-guided scene proposals with owned feedback.""" + +from __future__ import annotations +from collections.abc import Mapping +from collections import Counter +from copy import deepcopy +from pathlib import Path +from typing import Any +import hashlib +import json +import math +import numpy as np +import torch + +__all__: list[str] = [] + + +class _BoundedPoseSource: + """Sample bounded arena-frame changes with task-declared support followers.""" + + def __init__( + self, env: Any, configuration: Mapping[str, Any], *, seed: int, revision: str + ) -> None: + self.configuration, self.seed, self.request_id = ( + {uid: deepcopy(dict(options)) for uid, options in configuration.items()}, + seed, + revision, + ) + self.poses = { + uid: env.sim.get_rigid_object(uid) + .get_local_pose(to_matrix=True)[0] + .detach() + .cpu() + .numpy() + .copy() + for uid in configuration + } + self.roots = { + env.robot.uid: env.robot.get_local_pose(to_matrix=True)[0] + .detach() + .cpu() + .tolist() + } + + def candidate(self, ordinal: int) -> JointSceneCandidate: + import numpy as np + from embodichain.lab.sim.scene.expansion import ScenePoseChange, SceneVariant + from embodichain.lab.sim.scene.feasibility import ( + JointSceneCandidate, + RobotDeploymentCandidate, + ) + + offsets = {} + for uid, options in self.configuration.items(): + if "follow" in options: + continue + seed = int.from_bytes( + hashlib.sha256(f"{self.seed}/{ordinal}/{uid}".encode()).digest()[:8], + "little", + ) + generator = np.random.default_rng(seed) + offsets[uid] = [ + generator.uniform(*bounds) + for bounds in (*options["translation_m"], options["yaw_rad"]) + ] + changes, parameters = [], [] + for uid, options in self.configuration.items(): + dx, dy, dz, yaw = offsets[options.get("follow", uid)] + pose = self.poses[uid].copy() + c, s = np.cos(yaw), np.sin(yaw) + pose[:3, :3] = np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]) @ pose[:3, :3] + pose[:3, 3] += (dx, dy, dz) + changes.append(ScenePoseChange(uid, tuple(map(tuple, pose)))) + parameters.extend((dx, dy, dz, yaw)) + scene = SceneVariant(self.request_id, self.seed, ordinal, tuple(changes)) + return JointSceneCandidate( + self.request_id, + scene, + RobotDeploymentCandidate(self.roots), + "object_pose", + tuple(parameters), + ) + + +from embodichain.lab.sim.scene.feasibility.budget import ( + FeasibilityBudget, + FeasibilityBudgetExhausted, +) + + +class _PoseBudget(FeasibilityBudget): + """Use whole-job limits, including raw proposals discarded by selection.""" + + def charge(self, kind: str, amount: int = 1) -> None: + self.check() + if type(amount) is not int or amount < 1: + raise ValueError("Budget charges must be positive integers") + limits = { + "candidates": self.cfg.max_candidates, + "ik": self.cfg.max_ik_calls, + "planning": self.cfg.max_planning_calls, + "rollouts": self.cfg.max_rollouts, + } + if self.counts[kind] + amount > limits[kind]: + self._blocked = (self.validation, kind + "_budget_exhausted") + raise FeasibilityBudgetExhausted(self._blocked[1]) + self.counts[kind] += amount + + +class _AdaptivePoseSource(_BoundedPoseSource): + """One bounded proposal stream; candidates never change after allocation.""" + + def __init__(self, env, options, *, seed, revision): + super().__init__(env, options["scene"], seed=seed, revision=revision) + from .task_pose_coverage import TaskPoseCoverage + from ._gym_utils import _hash + from embodichain.lab.sim.scene.feasibility import ( + FeasibilityBudget, + SceneRobotFeasibilityCfg, + ) + + self.env, self.options = env, deepcopy(options) + self.cfg, self.schedule = ( + self.options["scene_sampling"], + self.options["scheduling"], + ) + if self.cfg["control_part"] not in env.robot.control_parts: + raise ValueError("scene_sampling.control_part is absent from the robot") + self.coverage_cfg = self.options.get("pose_coverage") + invariant = { + "robot": env.robot.cfg.to_dict(), + "physics": env.sim.sim_config.physics_cfg.to_dict(), + "poses": self.poses, + "roots": self.roots, + "domain": self.configuration, + "coverage": self.coverage_cfg, + "validation": options["validation"], + "objects": { + uid: obj.cfg.to_dict() + for uid in getattr(env.sim, "get_rigid_object_uid_list", lambda: ())() + if (obj := env.sim.get_rigid_object(uid)) is not None + }, + } + # _hash handles JSON data only; pose arrays are owned host arrays here. + invariant.pop("poses") + self.domain_id = _hash(invariant) + self.coverage = ( + None + if self.coverage_cfg is None + else TaskPoseCoverage( + self.domain_id, self.coverage_cfg["entity"], self.coverage_cfg["grids"] + ) + ) + self.budget = _PoseBudget( + SceneRobotFeasibilityCfg( + max_candidates=self.cfg["max_candidates"], + max_ik_calls=self.cfg["max_ik_calls"], + max_planning_calls=self.cfg["max_planning_calls"], + max_rollouts=self.cfg["max_rollouts"], + max_wall_time_s=options["engine"]["max_wall_time_s"], + ) + ) + self.budget.validation = ( + True # Use the full host allocation, not search/held-out splitting. + ) + self._candidates = {} + self._checks = {} + self._predicted = {} + self._outcomes = {} + self._stats = {} + self._events = [] + self._raw_ordinal = 0 + self._root_pose = env.robot.get_local_pose(to_matrix=True)[0].detach().clone() + self._joint_seed = ( + env.robot.get_qpos(name=self.cfg["control_part"])[0:1].detach().clone() + if self.cfg["strategy"] == "workspace_joint" + else None + ) + self._local = None + self.output = None + if self.cfg["strategy"] == "workspace_joint": + self._prepare_workspace() + + def bind_program(self, adapter, program): + """Reject mismatched authored grasp branches before any candidate mutates a row.""" + if self.cfg["strategy"] != "workspace_joint": + return + profile = adapter._factory.create_robot_skill_profile() + preset = profile.presets[self.env.cfg.task_program.integration.runtime_preset] + pick = preset.skill_option_templates.get( + "pick_up", preset.skill_option_templates.get("pick") + ) + fixed = None if pick is None else pick.fixed_object_to_eef + if fixed is None: + raise ValueError( + "workspace_joint requires a fixed_object_to_eef pick policy; sampled grasp replacement is unsupported" + ) + from embodichain.lab.task_program.semantics.calls import Pick + + picked = { + entry.call.object.entity_id + for segment in program.iter_segments() + for entry in segment.calls + if type(entry.call) is Pick + } + if not picked: + raise ValueError( + "workspace_joint requires an explicit Pick in its task program" + ) + for entity in picked: + transform = self.cfg["targets"].get(entity) + if transform is None or not np.allclose( + np.array(transform), fixed.detach().cpu().numpy(), rtol=0, atol=1e-6 + ): + raise ValueError( + "Workspace grasp target must match the executed fixed_object_to_eef branch" + ) + + def _prepare_workspace(self): + robot = self.env.robot + part = self.cfg["control_part"] + n = self.cfg["sample_count"] + generator = torch.Generator(device=robot.device).manual_seed(self.seed) + if self.cfg["workspace_source"] == "cache": + cache = robot.get_workspace(part) + settings = robot.cfg.workspace_cfg[part] + ids = cache.sample_indices( + n, + strategy=settings.strategy, + min_score=settings.min_score, + generator=generator, + ) + if bool((ids < 0).any()): + raise ValueError("Workspace cache returned invalid indices") + q = cache.qpos[ids].to(robot.device) + else: + limits = robot.get_qpos_limits(name=part, env_ids=[0])[0] + if not bool(torch.isfinite(limits).all()): + raise ValueError("Workspace FK requires finite joint limits") + q = limits[:, 0] + torch.rand( + (n, len(limits)), device=robot.device, generator=generator + ) * (limits[:, 1] - limits[:, 0]) + fk = robot.compute_batch_fk(q[None], name=part, env_ids=[0], to_matrix=True)[0] + if not bool(torch.isfinite(fk).all()): + raise ValueError("Workspace FK produced nonfinite poses") + self._local = ( + (torch.linalg.inv(self._root_pose)[None] @ fk).detach().cpu().numpy().copy() + ) + + def _guided(self, candidate, rng): + from dataclasses import replace + from embodichain.lab.sim.scene.expansion import ScenePoseChange, SceneVariant + + poses = { + c.entity_uid: np.array(c.arena_pose) for c in candidate.scene.pose_changes + } + origin = "uniform_exploration" + if rng.random() >= self.cfg["uniform_fraction"]: + origin = "workspace_joint" + root = np.array(candidate.deployment.poses[self.env.robot.uid]) + for uid, transform in self.cfg["targets"].items(): + proposed = ( + root[None] @ self._local @ np.linalg.inv(np.array(transform))[None] + ) + base = self.poses[uid] + options = self.configuration[uid] + yaw = np.arctan2(proposed[:, 1, 0], proposed[:, 0, 0]) - math.atan2( + base[1, 0], base[0, 0] + ) + bounds = np.array(options["yaw_rad"]) + yaw += (2 * math.pi) * np.round((bounds.mean() - yaw) / (2 * math.pi)) + xy = proposed[:, :2, 3] - base[:2, 3] + valid = np.flatnonzero( + np.all( + (xy >= np.array(options["translation_m"])[:2, 0]) + & (xy <= np.array(options["translation_m"])[:2, 1]), + axis=1, + ) + & (yaw >= bounds[0]) + & (yaw <= bounds[1]) + ) + if not len(valid): + return candidate, "workspace_no_projected_sample" + index = int(rng.choice(valid)) + angle = float(yaw[index]) + c, s = math.cos(angle), math.sin(angle) + poses[uid][:3, :3] = ( + np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]) @ base[:3, :3] + ) + poses[uid][:2, 3] = proposed[index, :2, 3] + for uid, opts in self.configuration.items(): + if "follow" in opts: + parent = opts["follow"] + poses[uid][:3, 3] = ( + self.poses[uid][:3, 3] + + poses[parent][:3, 3] + - self.poses[parent][:3, 3] + ) + poses[uid][:3, :3] = ( + poses[parent][:3, :3] + @ self.poses[parent][:3, :3].T + @ self.poses[uid][:3, :3] + ) + changes = tuple( + ScenePoseChange(uid, tuple(map(tuple, pose))) for uid, pose in poses.items() + ) + return ( + replace( + candidate, + scene=SceneVariant( + self.request_id, self.seed, candidate.scene.ordinal, changes + ), + ), + origin, + ) + + def _check(self, candidate): + from embodichain.lab.sim.motion._budget import _planning_budget_scope + + robot = self.env.robot + part = self.cfg["control_part"] + poses = { + c.entity_uid: np.array(c.arena_pose) for c in candidate.scene.pose_changes + } + for uid, transform in self.cfg["targets"].items(): + target = torch.tensor( + poses[uid] @ np.array(transform), + device=robot.device, + dtype=torch.float32, + )[None] + with _planning_budget_scope(self.budget): + ok, q = robot.compute_ik( + pose=target, joint_seed=self._joint_seed, name=part, env_ids=[0] + ) + limits = robot.get_qpos_limits(name=part, env_ids=[0]) + if ( + not bool(ok.all()) + or not bool(torch.isfinite(q).all()) + or not bool(((q >= limits[..., 0]) & (q <= limits[..., 1])).all()) + ): + return False, "pose_ik_or_joint_limits" + fk = robot.compute_fk(qpos=q, name=part, env_ids=[0], to_matrix=True) + angle = torch.acos( + ( + ( + torch.einsum( + "bii->b", fk[:, :3, :3].transpose(1, 2) @ target[:, :3, :3] + ) + - 1 + ) + / 2 + ).clamp(-1, 1) + ) + if ( + not bool(torch.isfinite(fk).all()) + or float((fk[:, :3, 3] - target[:, :3, 3]).norm()) > 1e-3 + or float(angle.max()) > 1e-2 + ): + return False, "full_pose_fk_residual" + return True, "passed" + + def candidate(self, ordinal): + from dataclasses import replace + from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted + + if ordinal in self._candidates: + return self._candidates[ordinal] + if ( + type(ordinal) is not int + or not 0 <= ordinal < self.options["engine"]["max_attempts"] + ): + raise ValueError("ordinal must be within the configured attempt budget") + rng = np.random.default_rng( + int.from_bytes( + hashlib.sha256( + f"{self.seed}/{ordinal}/pose-selection".encode() + ).digest()[:8], + "little", + ) + ) + remaining = max( + 1, + self.cfg["max_rollouts"] + - self.budget.counts["rollouts"] + - len(self._predicted), + ) + quota = max(1, (self.cfg["max_candidates"] - self._raw_ordinal) // remaining) + count = ( + 1 + if self.schedule["policy"] == "fifo" + and self.cfg["strategy"] == "bounded_pose" + else min(self.schedule["pool_size"], quota) + ) + pool = [] + last = None + origin = "bounded_pose" + reason = "no_candidate" + for _ in range(count): + raw = self._raw_ordinal + # Keep the historical simple FIFO sequence exactly intact. + candidate = super().candidate( + ordinal + if count == 1 and self.cfg["strategy"] == "bounded_pose" + else raw + ) + last = candidate + try: + self.budget.charge("candidates") + self._raw_ordinal += 1 + ok = True + if self.cfg["strategy"] == "workspace_joint": + candidate, origin = self._guided(candidate, rng) + ok, reason = self._check(candidate) + else: + reason = "passed" + except FeasibilityBudgetExhausted as e: + ok = False + reason = str(e) + poses = {c.entity_uid: c.arena_pose for c in candidate.scene.pose_changes} + cells = ( + () + if self.coverage is None + else self.coverage.cells( + poses[self.coverage_cfg["entity"]], + poses[self.coverage_cfg["place_reference"]], + ) + ) + self._events.append( + { + "event": "proposal", + "ordinal": ordinal, + "raw_ordinal": raw, + "origin": origin, + "screened": ok, + "reason": reason, + "pose_changes": { + c.entity_uid: c.arena_pose for c in candidate.scene.pose_changes + }, + "installation": dict(candidate.deployment.poses), + "cells": cells, + } + ) + if ok: + pool.append((candidate, cells, origin)) + if self.schedule["policy"] == "fifo" and pool: + break + if self.budget._blocked is not None: + break + valid = bool(pool) + if pool: + if ( + self.schedule["policy"] == "fifo" + or rng.random() < self.schedule["exploration_fraction"] + ): + chosen = pool[int(rng.integers(len(pool)))] + selection = "exploration" + else: + predicted = Counter( + c for values in self._predicted.values() for c in values + ) + + def score(entry): + cells = entry[1] + success, total = self._stats.get(self._region(cells), (0, 0)) + return ( + (success + 1) + / (total + 2) + * self.coverage.gain(cells, predicted) + ) + + scores = np.array([score(c) for c in pool]) + ids = np.flatnonzero(scores == scores.max()) + chosen = pool[int(rng.choice(ids))] + selection = "coverage" + candidate, cells, origin = chosen + self._predicted[ordinal] = cells + reason = "passed" + else: + candidate = last + cells = () + selection = "rejected" + # Candidate identity includes the complete correlated vector, not just + # the raw draw before workspace conditioning. + parameters = tuple( + v + for change in candidate.scene.pose_changes + for row in change.arena_pose + for v in row + ) + candidate = replace( + candidate, + scene=replace(candidate.scene, ordinal=ordinal), + parameters=parameters, + ) + self._candidates[ordinal] = candidate + self._checks[ordinal] = (valid, reason) + self._events.append( + { + "event": "selection", + "ordinal": ordinal, + "candidate_id": candidate.candidate_id, + "selection": selection, + "origin": origin, + "cells": cells, + "screened": valid, + } + ) + self.checkpoint() + return candidate + + def validate(self, ordinal): + from .contracts import ValidationCheck, ValidationResult + + ok, reason = self._checks[ordinal] + return ValidationResult( + ( + ValidationCheck( + "scene_sampling.proposal", "passed" if ok else "failed", reason + ), + ) + ) + + @staticmethod + def _region(cells): + return tuple((cell[0], *(axis // 2 for axis in cell[1:])) for cell in cells) + + def finish(self, ordinal, episode, receipt, *, executed): + if ordinal in self._outcomes: + return + cells = self._predicted.pop(ordinal, ()) + success = episode is not None and episode.validation.accepted + if executed: + s, n = self._stats.get(self._region(cells), (0, 0)) + self._stats[self._region(cells)] = (s + int(success), n + 1) + result = { + "elapsed_s": self.budget.clock() - self.budget.started, + "proposals": self.budget.counts["candidates"], + "rollouts": self.budget.counts["rollouts"], + "event": "outcome", + "ordinal": ordinal, + "executed": executed, + "physical_accepted": success, + "committed": receipt is not None and receipt.confirmed, + "coverage": ({} if self.coverage is None else self.coverage.phase_counts()), + } + if episode is not None and "full_joint_positions" in episode.observations: + states = episode.observations["full_joint_positions"] + segments = episode.metadata.get("program_segments", ()) + pick_end = ( + min(len(states) - 1, int(segments[0]["end_step"])) if segments else 0 + ) + ids = self.env.robot.control_parts[self.cfg["control_part"]] + if ids and isinstance(ids[0], str): + ids = [self.env.robot.joint_names.index(name) for name in ids] + row = int(episode.metadata["source_env_id"]) + values = states[[pick_end, len(states) - 1]][:, ids].to( + self.env.robot.device + )[None] + tcp = self.env.robot.compute_batch_fk( + values, name=self.cfg["control_part"], env_ids=[row], to_matrix=True + )[0] + result["measured_tcp_poses"] = tcp.detach().cpu().tolist() + result["measured_tcp_indices"] = [pick_end, len(states) - 1] + self._outcomes[ordinal] = result + self._events.append(result) + self.checkpoint() + + def state_dict(self): + from dataclasses import asdict + + return deepcopy( + { + "version": 1, + "seed": self.seed, + "revision": self.request_id, + "options": self.options, + "coverage": ( + None if self.coverage is None else self.coverage.state_dict() + ), + "raw_ordinal": self._raw_ordinal, + "candidates": { + str(k): { + "request_id": v.request_id, + "scene": asdict(v.scene), + "deployment": {"poses": dict(v.deployment.poses)}, + "mode_id": v.mode_id, + "parameters": v.parameters, + } + for k, v in self._candidates.items() + }, + "checks": self._checks, + "predicted": self._predicted, + "outcomes": self._outcomes, + "events": self._events, + "statistics": [ + [cells, list(counts)] for cells, counts in self._stats.items() + ], + "budget": dict(self.budget.counts), + "elapsed_s": self.budget.clock() - self.budget.started, + "blocked": self.budget._blocked, + } + ) + + def load_state_dict(self, state): + """Restore deterministic proposal history; never promote pending writes.""" + from embodichain.lab.sim.scene.expansion import ScenePoseChange, SceneVariant + from embodichain.lab.sim.scene.feasibility import ( + JointSceneCandidate, + RobotDeploymentCandidate, + ) + + data = deepcopy(state) + if ( + self._candidates + or data.get("version") != 1 + or data.get("seed") != self.seed + or data.get("revision") != self.request_id + or data.get("options") != self.options + ): + raise ValueError("Sampling restore requires an empty, matching source") + candidates = {} + for key, value in data["candidates"].items(): + scene = dict(value["scene"]) + scene["pose_changes"] = tuple( + ScenePoseChange(**change) for change in scene["pose_changes"] + ) + candidates[int(key)] = JointSceneCandidate( + value["request_id"], + SceneVariant(**scene), + RobotDeploymentCandidate(**value["deployment"]), + value["mode_id"], + tuple(value["parameters"]), + ) + if ( + any(not 0 <= k < self.options["engine"]["max_attempts"] for k in candidates) + or not 0 <= data["raw_ordinal"] <= self.cfg["max_candidates"] + ): + raise ValueError("Sampling checkpoint exceeds declared bounds") + budget = data["budget"] + limits = { + "candidates": self.cfg["max_candidates"], + "ik": self.cfg["max_ik_calls"], + "planning": self.cfg["max_planning_calls"], + "rollouts": self.cfg["max_rollouts"], + } + if ( + set(budget) != set(limits) + or any( + type(v) is not int or not 0 <= v <= limits[k] for k, v in budget.items() + ) + or not math.isfinite(data["elapsed_s"]) + or data["elapsed_s"] < 0 + ): + raise ValueError("Malformed sampling budget checkpoint") + if self.coverage is not None: + self.coverage.load_state_dict(data["coverage"]) + elif data["coverage"] is not None: + raise ValueError("Checkpoint unexpectedly contains pose coverage") + self._candidates = candidates + self._checks = {int(k): tuple(v) for k, v in data["checks"].items()} + self._predicted = { + int(k): tuple(tuple(c) for c in v) for k, v in data["predicted"].items() + } + self._outcomes = {int(k): v for k, v in data["outcomes"].items()} + self._events = data["events"] + self._stats = { + tuple(tuple(c) for c in cells): tuple(counts) + for cells, counts in data["statistics"] + } + self._raw_ordinal = data["raw_ordinal"] + self.budget.counts = budget + self.budget.started = self.budget.clock() - data["elapsed_s"] + self.budget.deadline = self.budget.started + self.budget.cfg.max_wall_time_s + self.budget._blocked = ( + None if data["blocked"] is None else tuple(data["blocked"]) + ) + + def checkpoint(self): + if self.output is None: + return + from embodichain.data_pipeline.recording.media import _atomic_json + + _atomic_json( + self.output / "pose-sampling.json", + { + "strategy": self.cfg["strategy"], + "policy": self.schedule["policy"], + "domain_id": self.domain_id, + "budget": dict(self.budget.counts), + "events": self._events, + "coverage": ( + None if self.coverage is None else self.coverage.state_dict() + ), + "checkpoint": self.state_dict(), + }, + ) diff --git a/embodichain/lab/expansion/_pose_sampling_cfg.py b/embodichain/lab/expansion/_pose_sampling_cfg.py new file mode 100644 index 0000000000..0f996d6370 --- /dev/null +++ b/embodichain/lab/expansion/_pose_sampling_cfg.py @@ -0,0 +1,162 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Strict optional scene sampling and pose coverage declarations.""" + +from __future__ import annotations +import math +import numpy as np + +__all__: list[str] = [] + + +def validate_sampling(value: dict) -> None: + """Normalize optional settings without changing legacy configurations.""" + from ._pose_cells import _grid + + allowed = { + "strategy", + "workspace_source", + "control_part", + "sample_count", + "uniform_fraction", + "targets", + "max_rollouts", + "max_candidates", + "max_ik_calls", + "max_planning_calls", + } + if not any(k in value for k in ("scene_sampling", "scheduling", "pose_coverage")): + return + sampling = value.setdefault("scene_sampling", {}) + schedule = value.setdefault("scheduling", {}) + if not isinstance(sampling, dict) or set(sampling) - allowed: + raise ValueError("Unknown scene_sampling settings") + if not isinstance(schedule, dict) or set(schedule) - { + "policy", + "pool_size", + "exploration_fraction", + }: + raise ValueError("Unknown pose scheduling settings") + for k, v in { + "strategy": "bounded_pose", + "workspace_source": "joint_uniform_fk", + "control_part": "arm", + "sample_count": 4096, + "uniform_fraction": 0.25, + "targets": {}, + "max_candidates": 4096, + "max_rollouts": value["engine"]["max_attempts"], + "max_ik_calls": 32768, + "max_planning_calls": 4096, + }.items(): + sampling.setdefault(k, v) + for k, v in { + "policy": "fifo", + "pool_size": 64, + "exploration_fraction": 0.25, + }.items(): + schedule.setdefault(k, v) + if sampling["strategy"] not in ("bounded_pose", "workspace_joint"): + raise ValueError( + "scene_sampling.strategy must be bounded_pose or workspace_joint" + ) + if sampling["workspace_source"] not in ("cache", "joint_uniform_fk"): + raise ValueError( + "workspace_source must explicitly select cache or joint_uniform_fk" + ) + if schedule["policy"] not in ("fifo", "task_pose_coverage"): + raise ValueError("Pose scheduling supports fifo or task_pose_coverage") + for k in ( + "sample_count", + "max_candidates", + "max_rollouts", + "max_ik_calls", + "max_planning_calls", + ): + if type(sampling[k]) is not int or not 0 < sampling[k] <= 1000000: + raise ValueError(f"{k} must be a bounded positive integer") + if sampling["sample_count"] > 65536: + raise ValueError("Workspace sample_count must be <= 65536") + if sampling["max_rollouts"] < value["engine"].get("episodes_per_operator", 1): + raise ValueError("max_rollouts must cover the requested episode quota") + if sampling["max_candidates"] < value["engine"]["max_attempts"]: + raise ValueError("max_candidates must cover at least one proposal per attempt") + if type(schedule["pool_size"]) is not int or not 1 <= schedule["pool_size"] <= 64: + raise ValueError("pool_size must be between 1 and 64") + for obj, key in ( + (sampling, "uniform_fraction"), + (schedule, "exploration_fraction"), + ): + if ( + type(obj[key]) not in (int, float) + or not math.isfinite(obj[key]) + or not 0 <= obj[key] <= 1 + ): + raise ValueError(f"{key} must be a probability") + if ( + type(sampling["control_part"]) is not str + or not sampling["control_part"].strip() + ): + raise ValueError("control_part must be explicit") + if not isinstance(sampling["targets"], dict): + raise ValueError( + "workspace targets must map scene entities to object-from-TCP matrices" + ) + if sampling["strategy"] == "workspace_joint" and not sampling["targets"]: + raise ValueError( + "workspace_joint requires explicit object-local target transforms" + ) + for uid, pose in sampling["targets"].items(): + m = np.asarray(pose, dtype=float) + if ( + uid not in value["scene"] + or "follow" in value["scene"][uid] + or m.shape != (4, 4) + or not np.isfinite(m).all() + or not np.allclose(m[3], [0, 0, 0, 1]) + or not np.allclose(m[:3, :3].T @ m[:3, :3], np.eye(3), atol=1e-6) + or not np.isclose(np.linalg.det(m[:3, :3]), 1) + ): + raise ValueError( + "Workspace targets require a declared independent scene entity and rigid transform" + ) + coverage = value.get("pose_coverage") + if coverage is None: + if schedule["policy"] == "task_pose_coverage": + raise ValueError( + "task_pose_coverage scheduling requires pose_coverage grids" + ) + return + if not isinstance(coverage, dict) or set(coverage) != { + "entity", + "place_reference", + "grids", + }: + raise ValueError("pose_coverage requires entity, place_reference and grids") + if ( + any(coverage[k] not in value["scene"] for k in ("entity", "place_reference")) + or coverage["entity"] == coverage["place_reference"] + ): + raise ValueError( + "Coverage entity and place_reference must select distinct scene entities" + ) + if not isinstance(coverage["grids"], dict) or set(coverage["grids"]) != { + "pick", + "place", + }: + raise ValueError("Coverage requires pick and place grids") + coverage["grids"] = {k: _grid(v) for k, v in coverage["grids"].items()} diff --git a/embodichain/lab/expansion/_task_program_config.py b/embodichain/lab/expansion/_task_program_config.py index a4b1518890..73c464e8f2 100644 --- a/embodichain/lab/expansion/_task_program_config.py +++ b/embodichain/lab/expansion/_task_program_config.py @@ -77,10 +77,13 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: """ path = Path(path) value = load_mapping(path) - if ( - set(value) != {"schema_version", "engine", "scene", "trajectory", "validation"} - or value["schema_version"] != 1 - ): + if (set(value) - {"scene_sampling", "scheduling", "pose_coverage"}) != { + "schema_version", + "engine", + "scene", + "trajectory", + "validation", + } or value["schema_version"] != 1: raise ValueError("Invalid demo expansion configuration") engine, motion = value["engine"], value["trajectory"] required_engine = { @@ -365,4 +368,7 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: or hold[field] <= 0 ): raise ValueError(f"contact_hold.{field} must be finite and positive") + from ._pose_sampling_cfg import validate_sampling + + validate_sampling(value) return value diff --git a/embodichain/lab/expansion/_workload_cursor.py b/embodichain/lab/expansion/_workload_cursor.py index 92a1633c2f..4e35e96e73 100644 --- a/embodichain/lab/expansion/_workload_cursor.py +++ b/embodichain/lab/expansion/_workload_cursor.py @@ -32,9 +32,17 @@ class _WorkloadCursor(_Cursor): - def __init__(self, bridge: TaskProgramDemoBridge, robot: Any, seed: int) -> None: + def __init__( + self, + bridge: TaskProgramDemoBridge, + robot: Any, + seed: int, + *, + budget: Any = None, + ) -> None: super().__init__(bridge) self.robot = robot + self.budget = budget self.rejection = None self.last_command = None self.devices = ( @@ -66,7 +74,34 @@ def next(self) -> ControllerAction | None: np.random.set_state(self.numpy_rng) random.setstate(self.python_rng) try: - action = super().next() + if ( + self.budget is None + or self.rejection is not None + or self.emergency is not None + ): + action = super().next() + else: + from embodichain.lab.sim.motion._budget import ( + _planning_budget_scope, + ) + from embodichain.lab.sim.scene.feasibility import ( + FeasibilityBudgetExhausted, + ) + + try: + with _planning_budget_scope(self.budget): + action = super().next() + except FeasibilityBudgetExhausted as error: + if self.segment is None: + # No command or segment exists yet: rejection has no + # safe-stop action to acknowledge and earns no step. + self.finished = True + self.accepted = False + self.reason = str(error) + action = None + else: + self.abort(str(error)) + action = super().next() if action is not None: if ( self.rejection is not None or self.emergency is not None diff --git a/embodichain/lab/expansion/distribution.md b/embodichain/lab/expansion/distribution.md new file mode 100644 index 0000000000..d73bfb3343 --- /dev/null +++ b/embodichain/lab/expansion/distribution.md @@ -0,0 +1,65 @@ +# Task distribution report + +Run from an EmbodiChain environment with the existing artifact reader dependencies: + +```bash +python -m embodichain.lab.expansion._distribution \ + --before /absolute/job-a \ + --after /absolute/job-a /absolute/job-b \ + --entity cube --cell-size 0.1 --minimum 5 \ + --output /absolute/new-report-directory +``` + +Inputs must be job directories containing `job.json` and confirmed artifact receipts. +Repeated input paths/commit identities do not multiply samples. Conflicting commit +identities fail. Output must be new; inputs are never overwritten. Both snapshots +must have the same task, robot installation, topology and configured scene domain. + +Open `report.html`. Select a spatial region or joint-distribution cell to inspect +recorded object paths. The evidence panel identifies the full artifact and the +existing native preview command (which retains its original preload limit). +The report itself needs no server or external network. `summary.json` carries +version, snapshot hash, domain, distributions, observed-bin deficits and limitations; +`before-episodes.jsonl` and `after-episodes.jsonl` carry source references and metrics. + +Version 2 adds full orientation statistics: normalized sign-canonical xyzw, +initial/final SO(3) rotation vectors, angular path length, net rotation and angular +speed quantiles. Three-dimensional rotation-vector bins have 30-degree edges; +they are not equal-volume and no object symmetry is assumed. Original full XYZ +and quaternion poses remain in every episode record. + +TCP is explicitly derived, not directly measured: recorded full joint states and +root poses drive the recorded URDF chain, followed by the single declared gripper +root-to-TCP calibration. The record includes the asset digest, link, transform and +method. Missing/ambiguous calibration returns unavailable; malformed transforms +fail. FK runs in 256-frame batches. Scaled robots are not supported. This is the +same recorded-URDF FK approach used by the existing preview, extended with TCP +calibration; no physics World is created. + +`summary.json` now holds aggregate statistics and a lightweight episode index, +not all trajectory details. `pages/{snapshot}-{page}.json` and matching local JS +files contain 100 records per page; the latter lets the offline HTML open without +an HTTP service. Agent tools use JSON. The viewer loads details on demand, retains +at most two detail pages, and displays 50 episode options per page. Joint heatmaps +are paged in 20-by-20 blocks; orientation counts are paged in rows of 20. Filters +operate on the full index before pagination. Index memory remains O(N); extracting +features also retains O(N) bounded descriptors, not full raw trajectories. Page +files and JSONL contain identical episode records. + +World-XY maps remain the spatial projection; trajectory display switches between +object and TCP XY paths. Raw numeric evidence is never changed. Joint path length +is in joint-coordinate units and must not be interpreted as Cartesian metres. +Whole-episode metrics and existing phase-aware geometry buckets remain separate. + +Counts cover observed cells only; no continuous workspace coverage or unobserved +feasibility claim is made. Different physical parents remain separate samples. +Use physical collection roots, not visual-child datasets. Comparison is cumulative +only if every before commit occurs in after; other comparisons are independent. +No automatic collection, arbitrary LeRobot import or learned clustering is added. + +Validation dataset: the complete `formal-qualified` pick-place matrix has 40 +physical job roots (two scenes, five seeds, four sampling/scheduling variants). +For each scene, the before snapshot is variant A across five seeds; after is +the cumulative union A+B+C+D. Interrupted diagnostics and visual children are +excluded. This compares dataset composition, not a causal learning experiment. +Use all matching job roots in `--before` and `--after`; retain scene separation. diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index e818f96574..8c61d3c501 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -125,6 +125,24 @@ def __init__( for uid in self.env.sim.get_rigid_object_uid_list() } + def planning_budget(self, assignment): + feedback = self.groups[assignment.workload_id]["host"]._context.feedback + return None if feedback is None else feedback.budget + + def can_admit(self, name): + feedback = self.groups[name]["host"]._context.feedback + if feedback is None: + return True + if self.groups[name]["session"].stop_reason is not None: + return False + from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted + + try: + feedback.budget.check() + except FeasibilityBudgetExhausted: + return False + return True + def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: from embodichain.lab.sim.scene import ( SceneView, @@ -168,9 +186,12 @@ def prepare(self, assignments: tuple[WorkloadAssignment, ...]) -> None: ) ctx.requests[assignment.env_id] = request if ctx.scene_source is not None: - candidates[assignment.env_id] = ctx.scene_source.candidate( - assignment.ordinal - ) + candidate = ctx.scene_source.candidate(assignment.ordinal) + if ( + ctx.feedback is None + or ctx.feedback.validate(assignment.ordinal).accepted + ): + candidates[assignment.env_id] = candidate if candidates: apply_joint_scene_candidates( SceneView(self.env.sim, env_ids=tuple(candidates)), candidates @@ -297,6 +318,11 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: ), ) ) + if ctx.feedback is not None: + ctx.preparation_checks[row] = ValidationResult( + ctx.preparation_checks[row].checks + + ctx.feedback.validate(assignment.ordinal).checks + ) item = PreparedEpisodeWorkItem( EpisodeCandidate(identity, json.dumps(request.recipe.to_dict())), ctx.compatibility.key, @@ -346,6 +372,8 @@ def started(self, assignment: WorkloadAssignment, world_control_step: int) -> No state = self.active[row] ctx = state["group"]["host"]._context state["group"]["engine"].mark_row_started(state["native"]) + if ctx.feedback is not None: + ctx.feedback.budget.counts["rollouts"] += 1 ctx.prepared[row][4]["world_control_start"] = world_control_step ctx.journal.update( ctx.requests[row], status="running", world_control_start=world_control_step @@ -393,6 +421,10 @@ def complete(self, result: WorkloadRowResult) -> Any: status="initial_rejected", reason="wall_time_exhausted", ) + if ctx.feedback is not None: + ctx.feedback.finish( + result.assignment.ordinal, None, None, executed=False + ) return None group = state["group"] ctx = group["host"]._context @@ -451,7 +483,18 @@ def complete(self, result: WorkloadRowResult) -> Any: }, }, ) - return group["engine"].complete_row(state["native"], episode) + receipt = None + try: + receipt = group["engine"].complete_row(state["native"], episode) + return receipt + finally: + if ctx.feedback is not None: + ctx.feedback.finish( + result.assignment.ordinal, + episode, + receipt, + executed=result.world_control_start is not None, + ) finally: state["adapter"].close() self.collector.discard(row) @@ -465,6 +508,13 @@ def cancel(self, result: WorkloadRowResult, *, reason: str) -> None: group = self.groups[result.assignment.workload_id] ctx = group["host"]._context request = ctx.requests[row] + if ctx.feedback is not None: + ctx.feedback.finish( + result.assignment.ordinal, + None, + None, + executed=result.world_control_start is not None, + ) record = { "env_id": row, "status": "cancelled", @@ -513,6 +563,10 @@ def cancel(self, result: WorkloadRowResult, *, reason: str) -> None: self.collector.discard(row) def close(self) -> None: + for group in self.groups.values(): + feedback = group["host"]._context.feedback + if feedback is not None: + feedback.checkpoint() for state in self.active.values(): state["adapter"].close() self.active.clear() @@ -569,6 +623,7 @@ def run_gym_expansion_workloads( common = extensions or GymExpansionHostExtensions() if ( common.scene_source_factory + or common.feedback_factory or common.recipe_transform or common.plan_transform_factory ): @@ -784,9 +839,14 @@ def physical_key(env_id: str, cfg: Any) -> str: bridges={}, extensions=workload.extensions, scene_source=None, + feedback=None, ) if workload.extensions.scene_source_factory is not None: ctx.scene_source = workload.extensions.scene_source_factory(env) + if workload.extensions.feedback_factory is not None: + ctx.feedback = workload.extensions.feedback_factory( + env, ctx.scene_source, path + ) builder = GymRecipeBuilder(ctx) transform = workload.extensions.recipe_transform ctx.recipe = lambda ordinal, builder=builder, transform=transform: ( @@ -814,6 +874,10 @@ def physical_key(env_id: str, cfg: Any) -> str: ) adapters[id(factory)] = adapter ctx.program = adapter.compile(environment_cfg.task_program) + if ctx.feedback is not None: + bind = getattr(ctx.feedback, "bind_program", None) + if bind is not None: + bind(adapter, ctx.program) if ( workload.extensions.plan_transform_factory is not None and adapter.configured_nominal_sources @@ -839,7 +903,11 @@ def admission_clock(admitted_at=admitted_at): { "collection": { "target_committed_episodes": cfg.target_episodes, - "max_rollout_attempts": cfg.max_attempts, + "max_rollout_attempts": ( + cfg.max_attempts + if ctx.feedback is None + else ctx.feedback.budget.cfg.max_rollouts + ), "max_proposals": cfg.max_attempts, "max_wall_time_s": cfg.max_wall_time_s, }, @@ -855,6 +923,7 @@ def admission_clock(admitted_at=admitted_at): "validation": {"require_path_collision": True}, } ), + coverage=None if ctx.feedback is None else ctx.feedback.coverage, episode_namespace=journal.job_instance_id, clock=admission_clock, ) @@ -907,6 +976,8 @@ def export(name: str) -> dict[str, Any]: def done(name: str, counts: Mapping[str, object]) -> None: group = groups[name] journal = group["host"]._context.journal + if group["host"]._context.feedback is not None: + group["host"]._context.feedback.checkpoint() complete = counts["committed"] == group["host"].cfg.target_episodes journal.stage("collection", "complete" if complete else "budget_exhausted") journal.checkpoint(force=True) diff --git a/embodichain/lab/expansion/host.py b/embodichain/lab/expansion/host.py index 2bb2bcfd5b..739a4355c9 100644 --- a/embodichain/lab/expansion/host.py +++ b/embodichain/lab/expansion/host.py @@ -103,6 +103,8 @@ def __init__( self._context.extensions = extensions or GymExpansionHostExtensions() if not isinstance(self._context.extensions, GymExpansionHostExtensions): raise TypeError("extensions must be GymExpansionHostExtensions") + if self._context.extensions.feedback_factory is not None: + raise ValueError("feedback_factory requires run_gym_expansion_workloads") self._recipe_builder = GymRecipeBuilder(self._context) self._context.recipe = self.recipe self._preparer = GymCohortPreparer(self._context) diff --git a/embodichain/lab/expansion/host_extensions.py b/embodichain/lab/expansion/host_extensions.py index c7acc00d60..911e1e67b4 100644 --- a/embodichain/lab/expansion/host_extensions.py +++ b/embodichain/lab/expansion/host_extensions.py @@ -18,7 +18,7 @@ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, field from collections.abc import Callable, Mapping from pathlib import Path from typing import Any, Protocol @@ -83,6 +83,9 @@ class GymExpansionHostExtensions: plan_transform_factory: Receives environment and immutable row identity; returns an ordinary Task Program transform factory. Its record metadata and hashed plan attachments are archived by the native episode owner. + feedback_factory: Optional rolling-collection feedback owner receiving env, + scene source and artifact directory; exposes coverage, budget, validate, + finish and checkpoint without advancing physics or writing episodes. require_plan_transform: Reject completed programs without transform records. """ @@ -91,6 +94,9 @@ class GymExpansionHostExtensions: validator_factory: Callable[[Any, Path], ExpansionValidator] | None = None recipe_transform: Callable[[ExpansionRecipe], ExpansionRecipe] | None = None plan_transform_factory: Callable[[Any, ExpansionRowContext], Any] | None = None + feedback_factory: Callable[[Any, Any, Path], Any] | None = field( + default=None, kw_only=True + ) require_plan_transform: bool = False def __post_init__(self) -> None: @@ -101,6 +107,7 @@ def __post_init__(self) -> None: raise ValueError("collection_renderer must be a nonempty renderer name") for name in ( "scene_source_factory", + "feedback_factory", "validator_factory", "recipe_transform", "plan_transform_factory", diff --git a/embodichain/lab/expansion/task_pose_coverage.py b/embodichain/lab/expansion/task_pose_coverage.py new file mode 100644 index 0000000000..106495c268 --- /dev/null +++ b/embodichain/lab/expansion/task_pose_coverage.py @@ -0,0 +1,240 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Receipt-confirmed task pose coverage shared across sampled scene cases.""" + +from __future__ import annotations + +from collections import Counter +from collections.abc import Mapping +from copy import deepcopy +from typing import TYPE_CHECKING + +import numpy as np +import torch + +if TYPE_CHECKING: + from .contracts import ExpertEpisode, SceneCase + +__all__ = ["TaskPoseCoverage"] + + +from ._pose_cells import _grid, _pose_cell + + +class TaskPoseCoverage: + """Count measured pick/place cells only after ordinary sink confirmation. + + Args: + domain_id: Host-validated invariant experiment identity, including the + installation and grid, excluding sampled scene poses and RNG seed. + entity_uid: Manipulated rigid object whose measured states are counted. + grids: Explicit ``pick`` and ``place`` XY/yaw grids in arena coordinates. + + Scene cases keep their existing identities. This adapter aggregates them + within one declared experiment, never across separate instances/domains. + """ + + def __init__(self, domain_id: str, entity_uid: str, grids: Mapping) -> None: + if not all( + type(s) is str and s.strip() == s and s for s in (domain_id, entity_uid) + ): + raise ValueError("Coverage requires nonempty domain and entity identities") + if not isinstance(grids, Mapping) or set(grids) != {"pick", "place"}: + raise ValueError("Coverage requires pick and place grids") + self.domain_id, self.entity_uid = domain_id, entity_uid + self.grids = {k: _grid(v) for k, v in grids.items()} + self._cases: dict[str, tuple[str, str, str]] = {} + self._population = None + self._pending: dict[str, tuple[str, tuple]] = {} + self._confirmed: dict[str, tuple[str, tuple]] = {} + self._counts = Counter() + + def register_case( + self, + case: SceneCase, + joint_limits: torch.Tensor, + joint_names: tuple[str, ...], + reference: float | None, + ) -> None: + """Register a scene without changing its identity or normalization.""" + if reference is not None: + raise ValueError( + "Task pose coverage does not accept a manipulability reference" + ) + population = ( + case.task_id, + case.robot_profile_id, + case.calibration_id, + tuple(joint_names), + ) + if self._population is not None and population != self._population: + raise ValueError( + "Coverage domain cannot mix task/robot/calibration/joint layouts" + ) + self._population = population + identity = (case.task_id, case.robot_profile_id, case.calibration_id) + if ( + case.scene_case_id in self._cases + and self._cases[case.scene_case_id] != identity + ): + raise ValueError("Conflicting scene case registration") + self._cases[case.scene_case_id] = identity + + def reference(self, case: SceneCase) -> None: + """This coverage policy supplies no motion normalization reference.""" + if case.scene_case_id not in self._cases: + raise KeyError(case.scene_case_id) + return None + + def cells( + self, pick_pose: object, place_pose: object + ) -> tuple[tuple[str, int, int, int], ...]: + """Return ordered tagged cells; out-of-domain poses contribute no cell.""" + return tuple( + (phase, *cell) + for phase, pose in (("pick", pick_pose), ("place", place_pose)) + if (cell := _pose_cell(pose, self.grids[phase])) is not None + ) + + def reserve(self, episode: ExpertEpisode) -> bool: + """Own measured cells until the matching persistence receipt arrives.""" + case_id = episode.identity.scene_case_id + if case_id not in self._cases: + raise ValueError("Episode scene is outside this coverage domain") + if not episode.validation.accepted: + return False + states = episode.observations.get(f"rigid/{self.entity_uid}/state") + if ( + states is None + or states.ndim != 2 + or states.shape[0] != len(episode.timestamps) + or states.shape[1] < 7 + ): + raise ValueError("Task coverage requires T+1 measured rigid states") + cells = self.cells( + states[0].detach().cpu().numpy(), states[-1].detach().cpu().numpy() + ) + value = (case_id, cells) + previous = self._confirmed.get( + episode.commit_id, self._pending.get(episode.commit_id) + ) + if previous is not None and previous != value: + raise ValueError("Commit identity was reused with different measured cells") + if episode.commit_id not in self._confirmed: + self._pending[episode.commit_id] = value + return True # Duplicates are valid data; they cannot increase unique coverage. + + def confirm(self, case_id: str, commit_id: str) -> None: + """Idempotently count the reservation qualified by the session's receipt.""" + value = self._confirmed.get(commit_id, self._pending.get(commit_id)) + if value is None or value[0] != case_id: + raise ValueError("Foreign or unreserved coverage confirmation") + if commit_id in self._confirmed: + return + self._pending.pop(commit_id) + self._confirmed[commit_id] = value + self._counts.update(value[1]) + + def release(self, case_id: str, commit_id: str) -> None: + """Release unconfirmed evidence without erasing committed coverage.""" + value = self._pending.get(commit_id) + if value is not None and value[0] != case_id: + raise ValueError("Foreign coverage release") + self._pending.pop(commit_id, None) + + def gain(self, cells: tuple, predicted: Mapping | None = None) -> float: + """Score scarcity using formal counts and explicitly tentative occupancy.""" + pending = Counter( + cell for _, values in self._pending.values() for cell in values + ) + predicted = {} if predicted is None else predicted + return sum( + 1 / (1 + self._counts[cell] + pending[cell] + predicted.get(cell, 0)) + for cell in cells + ) + + def snapshot(self) -> tuple[Mapping[str, int], Mapping[str, Mapping[int, int]]]: + """Return confirmed coverage with no fabricated manipulability bands.""" + return {self.domain_id: len(self._counts)}, {} + + def phase_counts(self) -> Mapping[str, int]: + """Return owned pick/place counts separately from motion quality bands.""" + return { + phase: sum(cell[0] == phase for cell in self._counts) + for phase in self.grids + } + + def state_dict(self) -> dict: + """Return an owned receipt-derived checkpoint, including pending evidence.""" + return deepcopy( + { + "version": 1, + "domain_id": self.domain_id, + "entity_uid": self.entity_uid, + "grids": self.grids, + "population": self._population, + "cases": self._cases, + "pending": self._pending, + "confirmed": self._confirmed, + } + ) + + def load_state_dict(self, state: Mapping) -> None: + """Restore matching-domain counts; pending evidence remains unconfirmed.""" + data = deepcopy(dict(state)) + if data.get("version") != 1 or any( + data.get(k) != getattr(self, k) + for k in ("domain_id", "entity_uid", "grids") + ): + raise ValueError("Coverage checkpoint belongs to another domain/grid") + if self._pending or self._confirmed or self._cases: + raise ValueError("Restore coverage only into a new adapter") + + def decode(entries): + return { + key: (value[0], tuple(tuple(cell) for cell in value[1])) + for key, value in entries.items() + } + + pending, confirmed = decode(data["pending"]), decode(data["confirmed"]) + if pending.keys() & confirmed.keys(): + raise ValueError("Coverage checkpoint repeats pending/confirmed identities") + cases = {k: tuple(v) for k, v in data["cases"].items()} + for case, cells in (*pending.values(), *confirmed.values()): + if case not in cases or any( + len(c) != 4 + or c[0] not in self.grids + or any(type(i) is not int or i < 0 for i in c[1:]) + or any( + i >= round((hi - lo) / step) + for i, lo, hi, step in zip( + c[1:], + self.grids[c[0]]["lower"], + self.grids[c[0]]["upper"], + self.grids[c[0]]["cell_size"], + ) + ) + for c in cells + ): + raise ValueError("Malformed coverage checkpoint cells") + pop = data["population"] + self._cases = cases + self._population = None if pop is None else (*pop[:3], tuple(pop[3])) + self._pending, self._confirmed = pending, confirmed + self._counts = Counter( + cell for _, cells in confirmed.values() for cell in cells + ) diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index 2fa1ad6b1e..c92a00c296 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -55,67 +55,7 @@ def _load_deployment(path: Path) -> None: config_to_cfg(load_mapping(path), source_path=path) -class _BoundedPoseSource: - """Sample bounded arena-frame changes with task-declared support followers.""" - - def __init__( - self, env: Any, configuration: Mapping[str, Any], *, seed: int, revision: str - ) -> None: - self.configuration, self.seed, self.request_id = configuration, seed, revision - self.poses = { - uid: env.sim.get_rigid_object(uid) - .get_local_pose(to_matrix=True)[0] - .detach() - .cpu() - .numpy() - .copy() - for uid in configuration - } - self.roots = { - env.robot.uid: env.robot.get_local_pose(to_matrix=True)[0] - .detach() - .cpu() - .tolist() - } - - def candidate(self, ordinal: int) -> JointSceneCandidate: - import numpy as np - from embodichain.lab.sim.scene.expansion import ScenePoseChange, SceneVariant - from embodichain.lab.sim.scene.feasibility import ( - JointSceneCandidate, - RobotDeploymentCandidate, - ) - - offsets = {} - for uid, options in self.configuration.items(): - if "follow" in options: - continue - seed = int.from_bytes( - hashlib.sha256(f"{self.seed}/{ordinal}/{uid}".encode()).digest()[:8], - "little", - ) - generator = np.random.default_rng(seed) - offsets[uid] = [ - generator.uniform(*bounds) - for bounds in (*options["translation_m"], options["yaw_rad"]) - ] - changes, parameters = [], [] - for uid, options in self.configuration.items(): - dx, dy, dz, yaw = offsets[options.get("follow", uid)] - pose = self.poses[uid].copy() - c, s = np.cos(yaw), np.sin(yaw) - pose[:3, :3] = np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]) @ pose[:3, :3] - pose[:3, 3] += (dx, dy, dz) - changes.append(ScenePoseChange(uid, tuple(map(tuple, pose)))) - parameters.extend((dx, dy, dz, yaw)) - scene = SceneVariant(self.request_id, self.seed, ordinal, tuple(changes)) - return JointSceneCandidate( - self.request_id, - scene, - RobotDeploymentCandidate(self.roots), - "object_pose", - tuple(parameters), - ) +from ._pose_sampling import _BoundedPoseSource, _AdaptivePoseSource def _task_expansion_extensions(*, options, operator, seed, report): @@ -126,11 +66,20 @@ def _task_expansion_extensions(*, options, operator, seed, report): def source(env): nonlocal pose_source - pose_source = _BoundedPoseSource( - env, options["scene"], seed=seed, revision=report["semantic_id"] + pose_source = ( + _AdaptivePoseSource(env, options, seed=seed, revision=report["semantic_id"]) + if "scene_sampling" in options + else _BoundedPoseSource( + env, options["scene"], seed=seed, revision=report["semantic_id"] + ) ) return pose_source + def feedback(env, source, path): + source.output = path + source.checkpoint() + return source + def recipe_transform(recipe): operations = [] for operation in recipe.operations: @@ -163,6 +112,7 @@ def plans(env, row): return GymExpansionHostExtensions( scene_source_factory=source, + feedback_factory=feedback if "scene_sampling" in options else None, recipe_transform=recipe_transform, plan_transform_factory=plans, require_plan_transform=operator != "object_pose", diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index b655d02175..bbb27180bc 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -305,7 +305,8 @@ def world_info(self) -> Mapping[str, object]: def _eligible(self, name: str) -> bool: workload, counts = self.workloads[name], self.counts[name] return ( - counts["committed"] < workload.target_episodes + getattr(self.source, "can_admit", lambda name: True)(name) + and counts["committed"] < workload.target_episodes and counts["attempts"] < workload.max_attempts and ( name not in self.started_at @@ -464,7 +465,14 @@ def _activate(self) -> None: ) self.live[row] = { **state, - "cursor": _WorkloadCursor(bridge, self.env.robot, assignment.seed), + "cursor": _WorkloadCursor( + bridge, + self.env.robot, + assignment.seed, + budget=getattr( + self.source, "planning_budget", lambda assignment: None + )(assignment), + ), "start": None, } diff --git a/embodichain/lab/task_program/compiler/lowering.py b/embodichain/lab/task_program/compiler/lowering.py index 3b6ecdbe3c..013eb09d03 100644 --- a/embodichain/lab/task_program/compiler/lowering.py +++ b/embodichain/lab/task_program/compiler/lowering.py @@ -2028,7 +2028,7 @@ def _lower_place( option_template = self._skill_option_template(analyzed, PlaceOptions) if call.at is not None: object_target = self._broadcast_pose( - call.at.to_matrix(), + self._ground_object_target(SemanticObjectTarget(pose=call.at), context), context, name="Place.at", ) diff --git a/embodichain/lab/task_program/integrations/feasibility.py b/embodichain/lab/task_program/integrations/feasibility.py index 8f688a15da..f422c48727 100644 --- a/embodichain/lab/task_program/integrations/feasibility.py +++ b/embodichain/lab/task_program/integrations/feasibility.py @@ -23,6 +23,8 @@ from pathlib import Path from typing import Any +import math +import json import numpy as np from scipy.spatial.transform import Rotation @@ -98,12 +100,28 @@ def __init__( self._previous = [] self._order_ok = True self.receipts = [] + self._transport = {} @staticmethod def _validate(value: Mapping[str, object]) -> dict: kinds = { "pose_near": {"entity", "position", "tolerance_m"}, + "pose_relative": { + "entity", + "other", + "position_tolerance", + "yaw_tolerance_rad", + "yaw_period_rad", + "tilt_tolerance_rad", + }, "lifted": {"entity", "height_m"}, + "transport_guard": { + "entity", + "other", + "lift_height_m", + "minimum_transit_height_m", + "goal_tolerance_m", + }, "joint_range": {"joint", "lower", "upper"}, "speed_below": {"entity", "linear_m_s", "angular_rad_s"}, "axis_relation": {"entity", "other", "axis", "lower", "upper"}, @@ -114,7 +132,13 @@ def _validate(value: Mapping[str, object]) -> dict: "Unsupported measured rigid-task predicate" ) kind = value["kind"] - data = _closed(value, kinds[kind] | {"kind", "negate"}, "predicate") + data = _closed( + value, + kinds[kind] + | {"kind", "negate"} + | ({"position_offset"} if kind == "pose_relative" else set()), + "predicate", + ) if ( not kinds[kind] <= data.keys() or type(data.get("negate", False)) is not bool @@ -153,6 +177,51 @@ def _validate(value: Mapping[str, object]) -> dict: raise ValueError( "Axis relation requires an arena axis and finite ordered bounds" ) + if kind == "pose_relative": + offset = np.asarray(data.get("position_offset", (0, 0, 0)), dtype=float) + if offset.shape != (3,) or not np.isfinite(offset).all(): + raise ValueError("position_offset must have three finite values") + tolerance = np.asarray(data["position_tolerance"], dtype=float) + if ( + tolerance.shape != (3,) + or not np.isfinite(tolerance).all() + or np.any(tolerance <= 0) + ): + raise ValueError( + "position_tolerance must contain three positive finite values" + ) + for key in ("yaw_tolerance_rad", "yaw_period_rad", "tilt_tolerance_rad"): + if ( + type(data[key]) not in (int, float) + or not math.isfinite(data[key]) + or data[key] <= 0 + ): + raise ValueError(f"{key} must be finite and positive") + if data["yaw_tolerance_rad"] > data[ + "yaw_period_rad" + ] / 2 or not math.isclose( + 2 * math.pi / data["yaw_period_rad"], + round(2 * math.pi / data["yaw_period_rad"]), + ): + raise ValueError( + "Yaw symmetry must divide a full turn and tolerance cannot exceed half a period" + ) + if kind == "transport_guard": + for key in ( + "lift_height_m", + "minimum_transit_height_m", + "goal_tolerance_m", + ): + if ( + type(data[key]) not in (int, float) + or not math.isfinite(data[key]) + or data[key] <= 0 + ): + raise ValueError(f"{key} must be finite and positive") + if data["minimum_transit_height_m"] >= data["lift_height_m"]: + raise ValueError( + "Transit threshold must be below the verified lift height" + ) return data def reset(self, env: Any) -> None: @@ -166,6 +235,7 @@ def reset(self, env: Any) -> None: self._previous = [False] * len(self.events) self._order_ok = True self.receipts = [] + self._transport = {} def predicate(self, env: Any, condition: Mapping[str, object]) -> bool: """Read one explicitly declared condition from current physical state. @@ -184,6 +254,12 @@ def predicate(self, env: Any, condition: Mapping[str, object]) -> bool: if key in cached: return bool(cached[key][self.env_id]) kind = condition["kind"] + if kind == "transport_guard": + lifted, dropped = self._transport.get( + json.dumps(dict(condition), sort_keys=True), (False, False) + ) + passed = lifted and not dropped + return bool(not passed if condition.get("negate", False) else passed) if kind == "joint_range": index = env.robot.joint_names.index(condition["joint"]) value = float(env.robot.get_qpos()[self.env_id, index]) @@ -195,7 +271,40 @@ def predicate(self, env: Any, condition: Mapping[str, object]) -> bool: position = ( obj.get_local_pose()[self.env_id, :3].detach().cpu().double().numpy() ) - if kind == "pose_near": + if kind == "pose_relative": + other = env.sim.get_rigid_object(condition["other"]) + if other is None: + raise ValueError("Relative target entity is absent") + actual = ( + obj.get_local_pose(to_matrix=True)[self.env_id] + .detach() + .cpu() + .double() + .numpy() + ) + target = ( + other.get_local_pose(to_matrix=True)[self.env_id] + .detach() + .cpu() + .double() + .numpy() + ) + delta = actual[:3, 3] - ( + target[:3, 3] + + target[:3, :3] + @ np.asarray(condition.get("position_offset", (0, 0, 0))) + ) + relative = target[:3, :3].T @ actual[:3, :3] + yaw = math.atan2(relative[1, 0], relative[0, 0]) + period = condition["yaw_period_rad"] + yaw_error = abs((yaw + period / 2) % period - period / 2) + tilt = math.acos(float(np.clip(relative[2, 2], -1, 1))) + passed = ( + bool(np.all(np.abs(delta) <= condition["position_tolerance"])) + and yaw_error <= condition["yaw_tolerance_rad"] + and tilt <= condition["tilt_tolerance_rad"] + ) + elif kind == "pose_near": passed = ( np.linalg.norm(position - condition["position"]) <= condition["tolerance_m"] @@ -325,6 +434,31 @@ def batch_scope( def observe(self, env: Any, action: Any) -> None: """Record consecutive event predicates at actual control boundaries.""" self._steps += 1 + for condition in self.final_checks: + if condition["kind"] != "transport_guard": + continue + key = json.dumps(dict(condition), sort_keys=True) + lifted, dropped = self._transport.get(key, (False, False)) + pose = env.sim.get_rigid_object(condition["entity"]).get_local_pose()[ + self.env_id, :3 + ] + goal = env.sim.get_rigid_object(condition["other"]).get_local_pose()[ + self.env_id, :3 + ] + if ( + not np.isfinite(pose.detach().cpu().numpy()).all() + or not np.isfinite(goal.detach().cpu().numpy()).all() + ): + self._transport[key] = (lifted, True) + continue + height = float(pose[2]) - self.initial_heights[condition["entity"]] + lifted = lifted or height >= condition["lift_height_m"] + dropped = dropped or ( + lifted + and height < condition["minimum_transit_height_m"] + and float((pose[:2] - goal[:2]).norm()) > condition["goal_tolerance_m"] + ) + self._transport[key] = (lifted, dropped) expected = self._index for i, (name, conditions, required) in enumerate(self.events): current = all(self.predicate(env, c) for c in conditions) diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/README.md b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/README.md new file mode 100644 index 0000000000..dc771fbc51 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/README.md @@ -0,0 +1,109 @@ +# Workspace-conditioned task pose coverage + +This acceptance task picks a 6×4×4 cm cuboid, lifts it, places it at a live +scene-relative XY/yaw target, releases it and waits for stability. Default CPU +physics, the UR5/DH gripper embodiment and the original controller/validation +owners are retained. The nominal robot installation is fixed. The non-colliding +goal reference is below the support plane; its declared +0.12 m offset identifies +the intended object centre. The two opposing physical gripper fingers have +explicit contact permissions, including the mimic finger. + +`expansion.yaml` selects two independent dimensions: + +```yaml +scene_sampling: + strategy: bounded_pose # bounded_pose | workspace_joint +scheduling: + policy: fifo # fifo | task_pose_coverage +``` + +Existing configurations without these settings retain the original sampler and +sequence. `workspace_joint` requires explicit object-to-TCP target matrices and +selects `joint_uniform_fk` or `cache` as its prior source. It does not silently +substitute a cache when none is configured. Both sources retain the same task +execution, measured validation and sink receipt path. Coverage is optional for +FIFO; feedback scheduling requires explicit `pose_coverage` grids. + +The task uses one declared fixed object-to-EEF grasp for all four comparisons. +The joint source verifies that its grasp transform matches the executed policy. +Workspace samples are only proposals: projected XY/yaw is checked again at the +actual height and orientation using IK, joint limits and FK residuals. Runtime +planning and the measured collision/effect gates remain authoritative. A prior +miss retains a labelled uniform fallback; it is not an infeasibility certificate. + +The joint candidate remains immutable for its logical ordinal. Feedback affects +only future candidates. Candidate RNG is independent of physical slot assignment; +adaptive selection also depends on the recorded feedback order, so different +parallel schedules need not produce identical future candidate sequences. + +## Coverage and accounting + +Each fully accepted and persisted episode contributes the measured initial and +terminal cuboid XY/yaw to separate pick/place grids. The cuboid's pi yaw symmetry +is canonicalized. Pick has 144 declared cells; place has 54. These are declared +domain cells, not a certified continuous feasible-volume denominator. Trajectory +variants of the same measured task poses do not increase unique task-pose coverage. + +A measured transport guard latches a failure if, after the first 5 cm lift, +the object falls below 2.5 cm above its initial height while more than 3 cm +from the placement goal in XY. Reaching the target later cannot erase that +failure. This control-boundary guard complements collision/effect validation; +it is not a continuous-contact or substep retention certificate. + +The domain fingerprint includes robot/installation, physical object configuration, +validation settings, ranges and grids. It excludes seed, sampling strategy and +individual candidate poses. SceneCase identities remain distinct. Existing session +receipts own acceptance: pending or failed writes do not increase confirmed counts. +Success-rate feedback records actual executions; preflight failures remain a +separate class. Observed TCP poses are auxiliary measurements, not extra points in +the primary score. + +`pose-sampling.json` retains raw proposals, provenance, selections, outcome order, +resource counts, confirmed coverage and a source checkpoint. Checkpoint loading +reproduces proposal state but is **not** a full live-World or job-resume facility; +ordinary session/sink reconciliation must resolve pending writes before continuing. +The collector still requires a fresh output directory. + +The source scores 75% of eligible choices by Beta(1,1) success estimate times +scarcity, with coarse paired pick/place regions; 25% use the underlying proposal +stream. The workspace prior independently reserves 25% uniform proposals. These +are different probabilities and are recorded separately. Pools are bounded at 64; +all generated candidates and decorated IK/planning calls consume budgets, including +unselected candidates. Physical rollouts have a separate cap from preparations. +Calls are cooperatively bounded, not forcibly preempted inside native code. + +## Acceptance runs + +From the repository root: + +```bash +python -m scripts.benchmark.expansion.task_pose_coverage --suite pilot --output outputs/pose-pilot +python -m scripts.benchmark.expansion.task_pose_coverage --suite smoke --output outputs/pose-smoke +python -m scripts.benchmark.expansion.task_pose_coverage --suite formal --output outputs/pose-formal +python -m scripts.benchmark.expansion.task_pose_coverage --suite installation --output outputs/pose-installations +python -m scripts.benchmark.expansion.task_pose_coverage --suite parallel --output outputs/pose-b4 +python -m scripts.benchmark.expansion.task_pose_coverage --suite trajectory --output outputs/pose-trajectories +python -m scripts.benchmark.expansion.task_pose_coverage --output outputs/pose-formal --rebuild +``` + +A/B/C/D are bounded+FIFO, bounded+feedback, workspace+FIFO, workspace+feedback. +Pilot uses fixed nominal poses and must pass physical acceptance before broad-domain +claims. Smoke uses 12 rollouts per group. Formal runs use both open/obstacle scenes, +five paired seeds, 4096 raw candidates, 128 rollouts, 32768 IK calls, 4096 planning +calls and 1800 seconds per cell. Initialization and prior preparation are included +in end-to-end wall time; pose budgets begin with source construction. Process +startup/import is recorded by the orchestrator log but excluded from worker wall +windows. No warmup is subtracted from these cold measurements. + +The target is a median D/C unique-cell gain >=15%, positive in >=4/5 seeds, +without reduced median pick or place coverage or more than 5 percentage points +acceptance-rate loss. A failed target remains failed; no thresholds are relaxed. +Installation experiments are separate domains; they cannot inflate the nominal +installation score. Obstacle placement and physical criteria are fixed before +formal runs. Run `--media` only for separate illustrative replay; numerical T+1 +evidence and confirmed artifact/LeRobot export are always retained. + +`--suite parallel` verifies real B=4 operation but is not an assertion of identical +adaptive sample order to B=1. Deterministic source checkpoint tests cover feedback +replay and owned candidate reuse. Report wall time, physics outcomes, failures and +coverage separately; never infer physical success from program completion alone. diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.obstacle.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.obstacle.yaml new file mode 100644 index 0000000000..3c71af7a46 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.obstacle.yaml @@ -0,0 +1,93 @@ +environment_id: workspace_pose_pick_place-obstacle +physics: default +max_episodes: 1 +max_episode_steps: 1200 +num_envs: 1 +arena_space: 2.5 +simulation: + light: + direct: + - uid: main_light + light_type: sun + color: + - 0.6 + - 0.6 + - 0.6 + intensity: 5.0 + direction: + - 0.0 + - 0.0 + - -1.0 + - uid: rect_light + light_type: rect + color: + - 1.0 + - 1.0 + - 1.0 + intensity: 8.0 + init_pos: + - -0.42 + - 0.08 + - 0.8 + direction: + - 0.0 + - 0.0 + - -1.0 + rect_width: 0.5 + rect_height: 0.5 + background: + - uid: goal + shape: + shape_type: Cube + size: + - 0.01 + - 0.01 + - 0.001 + body_type: static + init_pos: + - -0.4 + - 0.48 + - -0.1 + attrs: + collision_props: + collision_enabled: false + - uid: obstacle + shape: + shape_type: Cube + size: + - 0.08 + - 0.08 + - 0.12 + body_type: static + init_pos: + - -0.75 + - -0.2 + - 0.06 + rigid_object: + - uid: cube + shape: + shape_type: Cube + size: + - 0.06 + - 0.04 + - 0.04 + body_type: dynamic + init_pos: + - -0.42 + - -0.08 + - 0.02 + attrs: + mass_props: + mass: 0.05 + rigid_props: + linear_damping: 0.2 + angular_damping: 0.2 + material_props: + dynamic_friction: 0.97 + static_friction: 0.99 + rigid_object_group: [] + articulation: [] +env: + sim_steps_per_control: 4 + events: {} + dataset: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.yaml new file mode 100644 index 0000000000..3639166932 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/env.yaml @@ -0,0 +1,81 @@ +environment_id: workspace_pose_pick_place +physics: default +max_episodes: 1 +max_episode_steps: 1200 +num_envs: 1 +arena_space: 2.5 +simulation: + light: + direct: + - uid: main_light + light_type: sun + color: + - 0.6 + - 0.6 + - 0.6 + intensity: 5.0 + direction: + - 0.0 + - 0.0 + - -1.0 + - uid: rect_light + light_type: rect + color: + - 1.0 + - 1.0 + - 1.0 + intensity: 8.0 + init_pos: + - -0.42 + - 0.08 + - 0.8 + direction: + - 0.0 + - 0.0 + - -1.0 + rect_width: 0.5 + rect_height: 0.5 + background: + - uid: goal + shape: + shape_type: Cube + size: + - 0.01 + - 0.01 + - 0.001 + body_type: static + init_pos: + - -0.4 + - 0.48 + - -0.1 + attrs: + collision_props: + collision_enabled: false + rigid_object: + - uid: cube + shape: + shape_type: Cube + size: + - 0.06 + - 0.04 + - 0.04 + body_type: dynamic + init_pos: + - -0.42 + - -0.08 + - 0.02 + attrs: + mass_props: + mass: 0.05 + rigid_props: + linear_damping: 0.2 + angular_damping: 0.2 + material_props: + dynamic_friction: 0.97 + static_friction: 0.99 + rigid_object_group: [] + articulation: [] +env: + sim_steps_per_control: 4 + events: {} + dataset: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/expansion.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/expansion.yaml new file mode 100644 index 0000000000..74fa2ef3fe --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/expansion.yaml @@ -0,0 +1,201 @@ +schema_version: 1 +engine: + episodes_per_operator: 128 + max_attempts: 4096 + max_steps: 1200 + max_wall_time_s: 1800.0 + settling_steps: 30 + capture_media: false + collision_backend: newton + collision_device: cpu +scene: + cube: + translation_m: + - - -0.48 + - 0.12 + - - -0.22 + - 0.18 + - - 0 + - 0 + yaw_rad: + - -1.5707963267948966 + - 1.5707963267948966 + goal: + translation_m: + - - -0.2 + - 0.1 + - - -0.18 + - 0.12 + - - 0 + - 0 + yaw_rad: + - -1.5707963267948966 + - 1.5707963267948966 +trajectory: + operators: + - object_pose + joint_offset_scale: 0.005 + via_count: 1 + max_proposals: 64 + minimum_joint_delta: 0.002 + velocity_limit: 0.5 + acceleration_limit: 0.5 + nullspace_task_rows: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: + place: + - retract +validation: + initial_checks: + - kind: support_bounds + entity: cube + lower: + - -1 + - -0.4 + - -0.003 + upper: + - -0.2 + - 0.7 + - 0.05 + final_checks: + - &id001 + kind: pose_relative + entity: cube + other: goal + position_tolerance: + - 0.02 + - 0.02 + - 0.01 + yaw_tolerance_rad: 0.17453292519943295 + yaw_period_rad: 3.141592653589793 + tilt_tolerance_rad: 0.17453292519943295 + position_offset: + - 0 + - 0 + - 0.12 + - &id002 + kind: joint_range + joint: gripper_finger1_joint_1 + lower: -0.001 + upper: 0.005 + - &id003 + kind: speed_below + entity: cube + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: transport_guard + entity: cube + other: goal + lift_height_m: 0.05 + minimum_transit_height_m: 0.025 + goal_tolerance_m: 0.03 + events: + - event_id: lift + conditions: + - kind: lifted + entity: cube + height_m: 0.05 + - event_id: placed_and_released + conditions: + - *id001 + - *id002 + - *id003 + consecutive_steps: 3 + allowed_contacts: + - - cube + - UR5/gripper_finger1_link_1 + - - cube + - UR5/gripper_finger2_link_1 + - - cube + - default_plane + mounting_contacts: + - - '@root' + - default_plane +scene_sampling: + strategy: bounded_pose + workspace_source: joint_uniform_fk + control_part: arm + sample_count: 4096 + uniform_fraction: 0.25 + max_candidates: 4096 + max_rollouts: 128 + max_ik_calls: 32768 + max_planning_calls: 4096 + targets: + cube: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.0 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + goal: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.12 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 +scheduling: + policy: fifo + pool_size: 64 + exploration_fraction: 0.25 +pose_coverage: + entity: cube + place_reference: goal + grids: + pick: + lower: + - -0.9 + - -0.3 + - -1.5707963267948966 + upper: + - -0.3 + - 0.1 + - 1.5707963267948966 + cell_size: + - 0.1 + - 0.1 + - 0.5235987755982988 + yaw_period: 3.141592653589793 + place: + lower: + - -0.6 + - 0.3 + - -1.5707963267948966 + upper: + - -0.3 + - 0.6 + - 1.5707963267948966 + cell_size: + - 0.1 + - 0.1 + - 0.5235987755982988 + yaw_period: 3.141592653589793 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.obstacle.ur5.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.obstacle.ur5.yaml new file mode 100644 index 0000000000..c9ba26d82f --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.obstacle.ur5.yaml @@ -0,0 +1,19 @@ +id: TaskProgramWorkspacePosePickPlaceObstacle-v1 +environment: + component: env.obstacle.yaml +task_program: + program: task_program/program.yaml + integration: task_program/integration.yaml + execution_policy: ../../../components/execution_policies/trajectory_open_loop.yaml +embodiment: + component: ../../../components/embodiments/ur5_dh_pgi_140_80.yaml + overrides: + init_qpos: + - 0 + - -1.57 + - 1.57 + - -1.57 + - -1.57 + - 0 + - 0 + - 0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.ur5.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.ur5.yaml new file mode 100644 index 0000000000..a70cff410f --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task.ur5.yaml @@ -0,0 +1,19 @@ +id: TaskProgramWorkspacePosePickPlace-v1 +environment: + component: env.yaml +task_program: + program: task_program/program.yaml + integration: task_program/integration.yaml + execution_policy: ../../../components/execution_policies/trajectory_open_loop.yaml +embodiment: + component: ../../../components/embodiments/ur5_dh_pgi_140_80.yaml + overrides: + init_qpos: + - 0 + - -1.57 + - 1.57 + - -1.57 + - -1.57 + - 0 + - 0 + - 0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/integration.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/integration.yaml new file mode 100644 index 0000000000..baa11842f9 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/integration.yaml @@ -0,0 +1,47 @@ +integration_id: workspace_pose_pick_place_v1 +program_id: workspace_pose_pick_place +requires: + scene_contract: workspace_pose_pick_place_scene_v1 + embodiment_contract: single_arm_parallel_gripper +scene_binding: + contract_id: workspace_pose_pick_place_scene_v1 + registry_id: task_program_workspace_pose_pick_place + rigid_objects: + - entity_id: cube + dynamics: dynamic + semantic_type: cube + affordances: + - entity_id: cube_grasp + kind: antipodal_grasp + - entity_id: goal + dynamics: static + semantic_type: placement_reference +profile: + defaults: + pick_up: + primary: primary_manipulator + place: + primary: primary_manipulator + skill_options: + pick: + kind: pick_up + fixed_object_to_eef: + - 1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - 1.0 + place: + kind: place + effect_monitors: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/program.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/program.yaml new file mode 100644 index 0000000000..610056960c --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/task_program/program.yaml @@ -0,0 +1,44 @@ +program_id: workspace_pose_pick_place +instruction: Pick up the cuboid and place it at the scene-relative goal pose. +targets: + drop_pose: + kind: scene_relative + entity: goal + frame: parent + position: + - 0 + - 0 + - 0.12 + quaternion_xyzw: + - 0 + - 0 + - 0 + - 1 +program: + kind: repeat + count: 1 + body: + kind: sequence + items: + - kind: segment + name: pick_cube + instruction: Grasp and lift the cube. + steps: + kind: invoke + call: + kind: pick + object: cube + - kind: segment + name: place_cube + instruction: Place the cube at the next target position and release it. + steps: + kind: invoke + call: + kind: place + object: cube + at: + kind: target_ref + target: drop_pose + post: + - kind: wait_stable + entity: cube diff --git a/scripts/benchmark/expansion/task_pose_coverage.py b/scripts/benchmark/expansion/task_pose_coverage.py new file mode 100644 index 0000000000..154f438866 --- /dev/null +++ b/scripts/benchmark/expansion/task_pose_coverage.py @@ -0,0 +1,540 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Compare bounded/workspace sampling and FIFO/coverage scheduling. + +Run: python -m scripts.benchmark.expansion.task_pose_coverage --output DIR +Use --suite formal only after the smoke scene qualification succeeds. +The worker uses real physics, measured acceptance and native persistence. +""" + +from __future__ import annotations + +import argparse +from copy import deepcopy +import importlib.metadata +import json +import math +import os +from pathlib import Path +import resource +import subprocess +import sys +import time +import statistics +import yaml + +ROOT = Path(__file__).resolve().parents[3] +TASK = ( + ROOT + / "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place" +) +GROUPS = { + "A": ("bounded_pose", "fifo"), + "B": ("bounded_pose", "task_pose_coverage"), + "C": ("workspace_joint", "fifo"), + "D": ("workspace_joint", "task_pose_coverage"), +} + + +def _write(path: Path, value: object) -> None: + path.write_text(json.dumps(value, indent=2, default=str) + "\n") + + +def _worker(args) -> None: + sys.path[:0] = [ + str(ROOT), + str(ROOT / "extensions/embodichain_tasks"), + str(ROOT / "extensions/embodichain_robots"), + ] + from embodichain.lab.expansion.task_program_jobs import run_task_program_expansion + + args.output.mkdir(parents=True, exist_ok=False) + cfg = yaml.safe_load((TASK / "expansion.yaml").read_text()) + cfg["scene_sampling"]["strategy"], cfg["scheduling"]["policy"] = GROUPS[args.group] + cfg["engine"].update( + episodes_per_operator=args.rollouts, + max_attempts=args.candidates, + batch_size=args.rows, + max_wall_time_s=args.seconds, + ) + cfg["scene_sampling"].update( + max_candidates=args.candidates, + max_rollouts=args.rollouts, + max_ik_calls=args.ik_calls, + max_planning_calls=args.planning_calls, + ) + if args.nominal: + for v in cfg["scene"].values(): + v.update(translation_m=[[0, 0], [0, 0], [0, 0]], yaw_rad=[0, 0]) + cfg["trajectory"]["operators"] = [args.operator] + config = args.output / "configuration.yaml" + config.write_text(yaml.safe_dump(cfg, sort_keys=False)) + deployment = TASK / ( + "task.obstacle.ur5.yaml" if args.scene == "obstacle" else "task.ur5.yaml" + ) + raw = yaml.safe_load(deployment.read_text()) + # Resolve every component before writing an installation-specific deployment. + for key in ("environment", "embodiment"): + raw[key]["component"] = str((TASK / raw[key]["component"]).resolve()) + for key in ("program", "integration", "execution_policy"): + raw["task_program"][key] = str((TASK / raw["task_program"][key]).resolve()) + if args.installation != "nominal": + sign = 1 if args.installation == "positive" else -1 + raw["embodiment"]["overrides"].update( + init_pos=[sign * 0.05, 0, 0], init_rot=[0, 0, sign * 10] + ) + if args.media: + cfg["engine"]["capture_media"] = True + config.write_text(yaml.safe_dump(cfg, sort_keys=False)) + dep = args.output / "deployment.yaml" + dep.write_text(yaml.safe_dump(raw, sort_keys=False)) + import hashlib + + source_paths = subprocess.check_output( + ["git", "ls-files", "--cached", "--others", "--exclude-standard"], + cwd=ROOT, + text=True, + ).splitlines() + selected = [ + ROOT / path + for path in source_paths + if path.startswith( + ( + "embodichain/lab/expansion/", + "embodichain/lab/task_program/", + "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/", + "scripts/benchmark/expansion/task_pose_coverage.py", + ) + ) + and (ROOT / path).is_file() + ] + _write( + args.output / "source-manifest.json", + { + str(p.relative_to(ROOT)): hashlib.sha256(p.read_bytes()).hexdigest() + for p in selected + }, + ) + start = time.perf_counter() + result = None + error = None + try: + result = run_task_program_expansion( + dep, config, args.output / "collection", seed=args.seed + ) + except Exception as exc: + error = f"{type(exc).__name__}: {exc}" + import traceback + + traceback.print_exc() + samples = list((args.output / "collection").rglob("pose-sampling.json")) + data = json.loads(samples[0].read_text()) if samples else {} + events = data.get("events", []) + outcomes = [e for e in events if e["event"] == "outcome"] + confirmed = data.get("coverage", {}).get("confirmed", {}) + cells = {tuple(cell) for _, values in confirmed.values() for cell in values} + counts = {p: sum(c[0] == p for c in cells) for p in ("pick", "place")} + failure = {} + for record in (args.output / "collection").rglob("attempt.json"): + d = json.loads(record.read_text()) + if d.get("status") != "committed": + reason = d.get("reason", d.get("status", "unknown")) + failure[reason] = failure.get(reason, 0) + 1 + versions = { + name: importlib.metadata.version(name) for name in ("torch", "dexsim-engine") + } + summary = { + "source_digest": hashlib.sha256( + (args.output / "source-manifest.json").read_bytes() + ).hexdigest(), + "suite": args.suite, + "declared_budget": { + "rollouts": args.rollouts, + "candidates": args.candidates, + "ik_calls": args.ik_calls, + "planning_calls": args.planning_calls, + "seconds": args.seconds, + }, + "group": args.group, + "scene": args.scene, + "installation": args.installation, + "seed": args.seed, + "rows": args.rows, + "operator": args.operator, + "nominal": args.nominal, + "media": args.media, + "execution_status": "error" if error else "completed", + "error": error, + "wall_s": time.perf_counter() - start, + "peak_rss_mib": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024, + "committed": len(confirmed), + "physical_accepted": sum(e["physical_accepted"] for e in outcomes), + "executed": sum(e["executed"] for e in outcomes), + "coverage": counts, + "unique_cells": len(cells), + "budget": data.get("budget", {}), + "failures": failure, + "versions": versions, + "result": result, + "coverage_domain": data.get("domain_id"), + "path": str(args.output), + } + _write(args.output / "metrics.json", summary) + print(json.dumps(summary), flush=True) + if error: + raise SystemExit(1) + + +def _report(output: Path, rows: list[dict]) -> None: + _write(output / "results.json", rows) + lines = [ + "# Task pose coverage acceptance", + "", + "Default CPU physics; cold end-to-end preparation, planning, rollout, validation and export. " + "Grasp classification may use CUDA. RSS is a process high-water mark; GPU memory unmeasured. " + "Only receipt-confirmed, physically validated episodes increase coverage.", + "", + "## Time & Memory", + "", + "|Case|Group|Seed|cost_time_ms|peak RSS MiB|cpu_delta_mb|gpu_delta_mb|peak_gpu_mb|", + "|---|---|---:|---:|---:|---|---|---|", + ] + for r in rows: + lines.append( + f"|{r['scene']}/{r['installation']}/B={r['rows']}|{r['group']}|{r['seed']}|{r['wall_s']*1000:.1f}|{r['peak_rss_mib']:.1f}|N/A|N/A|N/A|" + ) + lines += [ + "", + "## Success & Other Metrics", + "", + "|Case|Group|Executed|Physically accepted|Committed|Pick cells|Place cells|Outcome|", + "|---|---|---:|---:|---:|---:|---:|---|", + ] + for r in rows: + lines.append( + f"|{r['scene']}/{r['installation']}|{r['group']}|{r['executed']}|{r['physical_accepted']}|{r['committed']}|{r['coverage']['pick']}|{r['coverage']['place']}|{r['error'] or 'completed'}|" + ) + lines += [ + "", + "## Leaderboard", + "", + "Ranked by measured acceptance rate; coverage gates are evaluated separately.", + "", + "|Group|Accepted / executed|Acceptance rate|Confirmed unique cells (sum across separate runs)|", + "|---|---|---:|---:|", + ] + aggregates = [] + for group in GROUPS: + selected = [r for r in rows if r["group"] == group] + if selected: + n = sum(r["executed"] for r in selected) + k = sum(r["physical_accepted"] for r in selected) + aggregates.append((group, k, n, sum(r["unique_cells"] for r in selected))) + for g, k, n, u in sorted( + aggregates, key=lambda v: v[1] / max(v[2], 1), reverse=True + ): + lines.append(f"|{g}|{k}/{n}|{k/max(n,1):.3f}|{u}|") + gates = {} + for scene in ("open", "obstacle"): + pairs = [] + for seed in (7, 17, 27, 37, 47): + matched = { + r["group"]: r + for r in rows + if r["scene"] == scene + and r["seed"] == seed + and r["installation"] == "nominal" + and not r["nominal"] + and not r["media"] + and r["rows"] == 1 + and r["operator"] == "object_pose" + and r.get("suite") == "formal" + and r.get("execution_status") == "completed" + and r.get("error") is None + and r.get("declared_budget") + == { + "rollouts": 128, + "candidates": 4096, + "ik_calls": 32768, + "planning_calls": 4096, + "seconds": 1800, + } + } + if ( + set(matched) >= {"C", "D"} + and matched["C"].get("coverage_domain") + == matched["D"].get("coverage_domain") + and matched["C"].get("versions") == matched["D"].get("versions") + and matched["C"].get("source_digest") + == matched["D"].get("source_digest") + and bool(matched["C"].get("source_digest")) + ): + pairs.append((matched["C"], matched["D"])) + if len(pairs) != 5 or any(c["unique_cells"] == 0 for c, d in pairs): + gates[scene] = { + "status": "unqualified", + "reason": "Need five complete paired seeds with nonzero baseline coverage", + } + continue + gains = [d["unique_cells"] / c["unique_cells"] - 1 for c, d in pairs] + phase_ok = all( + statistics.median(d["coverage"][p] for c, d in pairs) + >= statistics.median(c["coverage"][p] for c, d in pairs) + for p in ("pick", "place") + ) + rate = lambda r: r["physical_accepted"] / max(1, r["executed"]) + passed = ( + statistics.median(gains) >= 0.15 + and sum(g > 0 for g in gains) >= 4 + and phase_ok + and statistics.median(rate(d) - rate(c) for c, d in pairs) >= -0.05 + ) + gates[scene] = { + "status": "passed" if passed else "failed", + "median_gain": statistics.median(gains), + "positive_seeds": sum(g > 0 for g in gains), + } + _write(output / "acceptance.json", gates) + lines += [ + "", + "## Acceptance gates", + "", + json.dumps(gates, indent=2), + "", + "Raw proposal/outcome logs and receipt checkpoints remain in each run directory. Single-point nominal pilots do not qualify broad-domain improvement.", + ] + (output / "report.md").write_text("\n".join(lines) + "\n") + # Offline plot, without importing simulation during report rebuild. + try: + import matplotlib + + matplotlib.use("Agg") + import matplotlib.pyplot as plt + + fig, axes = plt.subplots(1, 3, figsize=(15, 4)) + for r in rows: + logs = list(Path(r["path"]).rglob("pose-sampling.json")) + if not logs: + continue + events = [ + e + for e in json.loads(logs[0].read_text())["events"] + if e["event"] == "outcome" + ] + for ax, key in zip(axes, ("proposals", "rollouts", "elapsed_s")): + ax.step( + [e.get(key, 0) for e in events], + [sum(e["coverage"].values()) for e in events], + where="post", + label=f"{r['group']}/{r['scene']}/{r['seed']}", + ) + ax.set_xlabel(key) + ax.set_ylabel("Confirmed task pose cells") + if axes[-1].lines: + axes[-1].legend(fontsize=6) + fig.tight_layout() + fig.savefig(output / "coverage.svg") + plt.close(fig) + except ImportError: + pass + + +def main() -> None: + """Run isolated comparable trials or rebuild reports from their artifacts.""" + p = argparse.ArgumentParser(description=__doc__) + p.add_argument("--output", type=Path, required=True) + p.add_argument("--worker", action="store_true") + p.add_argument( + "--seeds", + default=None, + help="Comma-separated seed subset; omitted uses suite defaults", + ) + p.add_argument( + "--scenes", default=None, help="Comma-separated open/obstacle subset" + ) + p.add_argument( + "--suite", + choices=("pilot", "smoke", "formal", "installation", "parallel", "trajectory"), + default="smoke", + ) + p.add_argument("--rebuild", action="store_true") + p.add_argument("--group", choices=tuple(GROUPS), default="A") + p.add_argument("--scene", choices=("open", "obstacle"), default="open") + p.add_argument( + "--installation", choices=("nominal", "positive", "negative"), default="nominal" + ) + p.add_argument("--seed", type=int, default=7) + p.add_argument("--rows", type=int, default=1) + p.add_argument("--rollouts", type=int, default=12) + p.add_argument("--candidates", type=int, default=384) + p.add_argument("--ik-calls", type=int, default=32768) + p.add_argument("--planning-calls", type=int, default=4096) + p.add_argument("--seconds", type=float, default=300) + p.add_argument("--nominal", action="store_true") + p.add_argument("--media", action="store_true") + p.add_argument( + "--operator", choices=("object_pose", "joint_residual"), default="object_pose" + ) + args = p.parse_args() + args.output = args.output.resolve() + if args.worker: + _worker(args) + return + if args.rebuild: + _report( + args.output, + [ + json.loads(f.read_text()) + for f in sorted(args.output.glob("*/metrics.json")) + ], + ) + return + args.output.mkdir(parents=True, exist_ok=False) + seeds = ( + [7, 17, 27, 37, 47] + if args.suite == "formal" + else [7, 17, 27] if args.suite == "installation" else [7] + ) + scenes = ["open", "obstacle"] if args.suite in ("formal", "pilot") else [args.scene] + if args.seeds is not None: + seeds = [int(value) for value in args.seeds.split(",")] + if args.scenes is not None: + scenes = args.scenes.split(",") + if not set(scenes) <= {"open", "obstacle"}: + p.error("Unknown scene") + installations = ( + ["positive", "negative"] if args.suite == "installation" else ["nominal"] + ) + groups = ["C", "D"] if args.suite == "installation" else list(GROUPS) + rows = [] + _write( + args.output / "provenance.json", + { + "head": subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=ROOT, text=True + ).strip(), + "diff": subprocess.check_output(["git", "diff"], cwd=ROOT, text=True), + "scope": vars(args), + "cpu_affinity": sorted(os.sched_getaffinity(0)), + }, + ) + for scene in scenes: + for installation in installations: + for i, seed in enumerate(seeds): + for group in ( + groups + if ( + (7, 17, 27, 37, 47).index(seed) + if seed in (7, 17, 27, 37, 47) + else i + ) + % 2 + == 0 + else groups[::-1] + ): + destination = args.output / f"{scene}-{installation}-{group}-{seed}" + n = ( + 128 + if args.suite == "formal" + else ( + 64 + if args.suite == "installation" + else 1 if args.suite == "pilot" else args.rollouts + ) + ) + cap = ( + 4096 + if args.suite == "formal" + else 2048 if args.suite == "installation" else args.candidates + ) + seconds = ( + 1800 + if args.suite == "formal" + else 900 if args.suite == "installation" else args.seconds + ) + command = [ + sys.executable, + str(Path(__file__).resolve()), + "--worker", + "--suite", + args.suite, + "--output", + str(destination), + "--group", + group, + "--scene", + scene, + "--seed", + str(seed), + "--installation", + installation, + "--rows", + str(4 if args.suite == "parallel" else args.rows), + "--rollouts", + str(n), + "--candidates", + str(cap), + "--seconds", + str(seconds), + "--operator", + ( + "joint_residual" + if args.suite == "trajectory" + else args.operator + ), + ] + if args.suite == "installation": + command += ["--ik-calls", "16384", "--planning-calls", "2048"] + if args.suite == "pilot" or args.nominal: + command += ["--nominal"] + if args.media: + command += ["--media"] + with (args.output / (destination.name + ".log")).open("w") as log: + try: + result = subprocess.run( + command, + cwd=ROOT, + env={ + **os.environ, + "OMP_NUM_THREADS": "1", + "MKL_NUM_THREADS": "1", + "SDL_VIDEODRIVER": "offscreen", + }, + stdout=log, + stderr=subprocess.STDOUT, + timeout=seconds + 180, + ) + except subprocess.TimeoutExpired: + raise RuntimeError( + f"Worker timeout; preserve log {log.name}" + ) + if (destination / "metrics.json").exists(): + rows.append( + json.loads((destination / "metrics.json").read_text()) + ) + _report(args.output, rows) + if result.returncode: + raise RuntimeError(f"Worker failed; inspect {destination}") + if args.suite == "pilot" and not rows[-1]["committed"]: + raise RuntimeError( + "Nominal scene qualification failed; do not relax acceptance or narrow the declared domain" + ) + print(args.output / "report.md") + + +if __name__ == "__main__": + main() diff --git a/tests/benchmark/expansion/test_task_pose_report.py b/tests/benchmark/expansion/test_task_pose_report.py new file mode 100644 index 0000000000..46ef649d19 --- /dev/null +++ b/tests/benchmark/expansion/test_task_pose_report.py @@ -0,0 +1,78 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Formal evidence gates cannot be satisfied by smoke or incompatible results.""" + +from __future__ import annotations +import json +import pytest +from scripts.benchmark.expansion.task_pose_coverage import _report + + +@pytest.mark.parametrize( + "change", + [ + {"suite": "smoke"}, + {"execution_status": "error", "error": "crash"}, + {"declared_budget": {"rollouts": 12}}, + {"coverage_domain": "other"}, + {"source_digest": "other"}, + ], +) +def test_formal_gate_rejects_incomplete_or_incompatible_records(tmp_path, change): + rows = [] + for seed in (7, 17, 27, 37, 47): + for group in ("C", "D"): + count = 10 if group == "C" else 20 + r = { + "suite": "formal", + "declared_budget": { + "rollouts": 128, + "candidates": 4096, + "ik_calls": 32768, + "planning_calls": 4096, + "seconds": 1800, + }, + "scene": "open", + "installation": "nominal", + "seed": seed, + "group": group, + "rows": 1, + "operator": "object_pose", + "nominal": False, + "media": False, + "execution_status": "completed", + "error": None, + "coverage_domain": "domain", + "versions": {"sdk": "v1"}, + "source_digest": "same", + "coverage": {"pick": count, "place": count}, + "unique_cells": 2 * count, + "executed": 128, + "physical_accepted": 128, + "committed": 128, + "wall_s": 100, + "peak_rss_mib": 100, + "path": str(tmp_path / "missing"), + } + if group == "D": + r.update(change) + rows.append(r) + _report(tmp_path, rows) + assert ( + json.loads((tmp_path / "acceptance.json").read_text())["open"]["status"] + == "unqualified" + ) diff --git a/tests/lab/expansion/test_distribution.py b/tests/lab/expansion/test_distribution.py new file mode 100644 index 0000000000..3e6d07a7a3 --- /dev/null +++ b/tests/lab/expansion/test_distribution.py @@ -0,0 +1,165 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +from __future__ import annotations +import numpy as np +import pytest +from embodichain.lab.expansion._distribution import _motion, _summarize + + +def test_motion_density_and_time_are_separate(): + a = _motion(np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]), np.array([0.0, 2.0])) + b = _motion( + np.array([[0.0, 0.0, 0.0], [0.5, 0.0, 0.0], [1.0, 0.0, 0.0]]), + np.array([0.0, 2.0, 4.0]), + ) + assert a["path_length"] == b["path_length"] == 1 + assert a["duration_s"] == 2 and b["duration_s"] == 4 + np.testing.assert_allclose(a["path"], b["path"]) + with pytest.raises(ValueError): + _motion(np.zeros((2, 3)), np.array([1.0, 1.0])) + + +def test_joint_distribution_and_idempotency(): + rows = [ + dict( + commit_id=str(i), + initial_pose=[x, 0, 0], + final_pose=[x, 0, 0], + object_motion={}, + geometry_bucket=None, + ) + for i, x in enumerate([-0.15, 0.15]) + ] + r = _summarize(rows + rows, 0.1, 1) + assert r["count"] == 2 + assert r["joint"] == {"-2,0|-2,0": 1, "1,0|1,0": 1} + assert r["joint_at_minimum"] == 2 + with pytest.raises(ValueError): + _summarize([rows[0], dict(rows[0], final_pose=[9, 0, 0])], 0.1, 1) + + +def test_missing_layout_is_not_zero(): + r = _summarize( + [dict(commit_id="a", object_motion=None, geometry_bucket=None)], 0.1, 5 + ) + assert r["layout_missing"] == 1 and r["layout_valid"] == 0 + assert r["joint"] == {} + + +def test_orientation_sign_and_out_of_plane_rotation(): + from embodichain.lab.expansion._distribution_pose import orientation + + poses = np.array([[0, 0, 0, 0, 0, 0, 1], [0, 0, 0, 1, 0, 0, 0]], dtype=float) + a = orientation(poses, np.array([0.0, 2.0])) + poses[:, 3:] *= -1 + b = orientation(poses, np.array([0.0, 2.0])) + assert a == b + assert a["angular_path_rad"] == pytest.approx(np.pi) + assert a["angular_speed_p50_p95"] == pytest.approx([np.pi / 2] * 2) + assert a["initial_rotvec_rad"] == [0.0, 0.0, 0.0] + assert abs(a["final_rotvec_rad"][0]) == pytest.approx(np.pi) + poses[:, 3:] = 0 + with pytest.raises(ValueError): + orientation(poses, np.array([0.0, 2.0])) + + +def test_tcp_root_transform_and_calibration(tmp_path): + import torch + from types import SimpleNamespace + from embodichain.lab.expansion._distribution_pose import RecordedTCP + + asset = tmp_path / "test.urdf" + asset.write_text( + """""" + ) + offset = np.eye(4) + offset[2, 3] = 0.15 + tcp = RecordedTCP( + { + "robot": { + "fpath": str(asset), + "gripper_bindings": { + "eef": { + "root_link": "tool", + "defaults": {"default_root_from_tcp": offset.tolist()}, + } + }, + } + } + ) + e = SimpleNamespace( + metadata={ + "initial_state": [{"kind": "robot", "uid": "r", "joint_names": ["slide"]}], + "scene_state_fields": [ + {"entity_uid": "r", "field": "pose", "key": "root"}, + {"entity_uid": "r", "field": "qpos", "key": "q"}, + ], + }, + observations={ + "root": torch.tensor([[1.0, 2.0, 3.0, 0.0, 0.0, 0.0, 1.0]] * 2), + "q": torch.tensor([[0.0], [1.0]]), + }, + ) + p = tcp.poses(e) + np.testing.assert_allclose(p[:, :3], [[1, 2, 3.15], [2, 2, 3.15]]) + np.testing.assert_allclose(p[:, 3:], [[0, 0, 0, 1]] * 2) + + +def test_detail_pages_match_agent_records_and_summary(tmp_path, monkeypatch): + import json + from embodichain.lab.expansion import _distribution as module + + rows = [] + for i in range(101): + rows.append( + dict( + episode_id=f"e{i}", + commit_id=f"c{i}", + initial_pose=[0, 0, 0, 0, 0, 0, 1], + final_pose=[1, 0, 0, 0, 0, 0, 1], + object_motion={ + "path_length": 1.0, + "duration_s": 2.0, + "path": [[0, 0, 0], [1, 0, 0]], + }, + joint_motion=None, + tcp_motion=None, + orientation={ + "rotation_bin_initial": "6,6,6", + "rotation_bin_final": "6,6,6", + }, + geometry_bucket=None, + ) + ) + monkeypatch.setattr(module, "_read", lambda paths, entity: (rows, ["domain"])) + output = tmp_path / "result" + module._run([], [], output, "cube", 0.1, 5) + summary = json.loads((output / "summary.json").read_text()) + detail = [ + json.loads(line) + for line in (output / "after-episodes.jsonl").read_text().splitlines() + ] + pages = [ + json.loads((output / "pages" / f"after-{n}.json").read_text()) for n in range(2) + ] + assert [len(p) for p in pages] == [100, 1] + assert pages[0] + pages[1] == detail + assert summary["after"]["orientation"]["initial"] == {"6,6,6": 101} + assert summary["after"]["joint"] == {"0,0|10,0": 101} + assert summary["after"]["episodes"][100]["page"] == "after-1" + assert summary["after"]["episodes"][0]["object_motion"] is True + assert rows[0].get("pick_cell") is None diff --git a/tests/lab/expansion/test_task_pose_coverage.py b/tests/lab/expansion/test_task_pose_coverage.py new file mode 100644 index 0000000000..2ffb4b10e1 --- /dev/null +++ b/tests/lab/expansion/test_task_pose_coverage.py @@ -0,0 +1,595 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Measured-cell accounting, sampling compatibility and feedback regressions.""" + +from __future__ import annotations +from copy import deepcopy +from types import SimpleNamespace +import json +import math +import numpy as np +import pytest +import torch +from embodichain.lab.expansion.task_pose_coverage import TaskPoseCoverage +from embodichain.lab.expansion.contracts import SceneCase +from embodichain.lab.expansion._pose_sampling import ( + _BoundedPoseSource, + _AdaptivePoseSource, +) +from embodichain.lab.expansion._pose_sampling_cfg import validate_sampling +from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted + + +def grids(): + return { + phase: { + "lower": [-1, -1, -math.pi / 2], + "upper": [1, 1, math.pi / 2], + "cell_size": [0.5, 0.5, math.pi / 2], + "yaw_period": math.pi, + } + for phase in ("pick", "place") + } + + +def coverage(): + cov = TaskPoseCoverage("domain", "object", grids()) + for name in ("scene-a", "scene-b"): + cov.register_case( + SceneCase(name, "initial", "signature", "task", "robot"), + torch.tensor([[-1.0, 1.0]]), + ("joint",), + None, + ) + return cov + + +def episode(commit="c1", case="scene-a", x=0.1, yaw=0.0, accepted=True): + state = torch.tensor( + [ + [x, 0.1, 0.02, 0, 0, math.sin(yaw / 2), math.cos(yaw / 2)], + [x + 0.1, 0.1, 0.02, 0, 0, math.sin(yaw / 2), math.cos(yaw / 2)], + ] + ) + return SimpleNamespace( + commit_id=commit, + identity=SimpleNamespace(scene_case_id=case), + validation=SimpleNamespace(accepted=accepted), + timestamps=torch.tensor([0.0, 0.1]), + observations={"rigid/object/state": state}, + ) + + +def test_receipts_aggregate_cases_without_double_credit_and_own_cells(): + cov = coverage() + e = episode() + assert cov.reserve(e) + assert cov.snapshot()[0] == {"domain": 0} + e.observations["rigid/object/state"].fill_(99) + cov.confirm("scene-a", "c1") + cov.confirm("scene-a", "c1") + assert cov.phase_counts() == {"pick": 1, "place": 1} + assert cov.snapshot()[1] == {} + assert cov.reserve(episode("c2", "scene-b", yaw=math.pi)) + cov.confirm("scene-b", "c2") + assert cov.snapshot()[0] == { + "domain": 2 + } # Symmetry and scene changes aren't novelty. + assert not cov.reserve(episode("bad", accepted=False)) + cov.reserve(episode("c3", x=-0.9)) + cov.release("scene-a", "c3") + with pytest.raises(ValueError): + cov.confirm("scene-a", "c3") + assert cov.snapshot()[0] == {"domain": 2} + + +def test_checkpoint_keeps_pending_unconfirmed_and_rejects_foreign_domain(): + cov = coverage() + cov.reserve(episode()) + cov.confirm("scene-a", "c1") + cov.reserve(episode("pending", x=-0.9)) + state = json.loads(json.dumps(cov.state_dict())) + restored = TaskPoseCoverage("domain", "object", grids()) + restored.load_state_dict(state) + assert restored.snapshot() == cov.snapshot() + restored.confirm("scene-a", "pending") + assert restored.snapshot()[0] == {"domain": 4} + assert cov.snapshot()[0] == {"domain": 2} + with pytest.raises(ValueError): + TaskPoseCoverage("another", "object", grids()).load_state_dict(state) + with pytest.raises(ValueError): + restored.confirm("scene-b", "pending") + + +def test_cells_boundaries_periodicity_and_measured_not_requested_pose(): + cov = coverage() + assert cov.cells([-1, -1, 0, 0, 0, 0, 1], [1, 1, 0, 0, 0, 0, 1]) == ( + ("pick", 0, 0, 1), + ("place", 3, 3, 1), + ) + assert cov.cells([-1.1, 0, 0, 0, 0, 0, 1], [1.1, 0, 0, 0, 0, 0, 1]) == () + with pytest.raises(ValueError): + cov.cells([0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 1]) + e = episode(x=-0.9) + e.metadata = {"requested_pose": [0.9, 0.9, 0]} + cov.reserve(e) + cov.confirm("scene-a", "c1") + assert cov.gain((("pick", 0, 2, 1),)) == 0.5 + + +class _Robot: + control_parts = {"arm": [0, 1, 2]} + device = torch.device("cpu") + uid = "robot" + cfg = SimpleNamespace(to_dict=lambda: {"uid": "robot"}) + + def get_local_pose(self, to_matrix=False): + return torch.eye(4)[None] + + def get_qpos(self, **kwargs): + return torch.tensor([[0.0, 0.0, 0.02]]) + + def get_qpos_limits(self, **kwargs): + return torch.tensor([[[-1.0, 1.0], [-1.0, 1.0], [0.02, 0.02]]]) + + def compute_batch_fk(self, qpos, **kwargs): + pose = torch.eye(4).expand(*qpos.shape[:2], 4, 4).clone() + pose[..., :3, 3] = qpos + return pose + + def compute_ik(self, pose, **kwargs): + return torch.ones(len(pose), dtype=torch.bool), pose[:, :3, 3].clone() + + def compute_fk(self, qpos, **kwargs): + pose = torch.eye(4).repeat(len(qpos), 1, 1) + pose[:, :3, 3] = qpos + return pose + + +def environment(): + pose = torch.eye(4)[None] + pose[:, 2, 3] = 0.02 + obj = SimpleNamespace(get_local_pose=lambda to_matrix=True: pose.clone()) + return SimpleNamespace( + robot=_Robot(), + sim=SimpleNamespace( + get_rigid_object=lambda uid: obj, + sim_config=SimpleNamespace( + physics_cfg=SimpleNamespace(to_dict=lambda: {"physics": "default"}) + ), + ), + ) + + +def options(strategy="bounded_pose", policy="fifo"): + value = { + "engine": {"max_attempts": 8, "max_wall_time_s": 120}, + "validation": {}, + "scene": { + uid: { + "translation_m": [[-0.9, 0.9], [-0.9, 0.9], [0, 0]], + "yaw_rad": [0, 0], + } + for uid in ("object", "goal") + }, + "scene_sampling": { + "strategy": strategy, + "sample_count": 64, + "max_candidates": 64, + "targets": ( + {uid: np.eye(4).tolist() for uid in ("object", "goal")} + if strategy == "workspace_joint" + else {} + ), + }, + "scheduling": {"policy": policy, "pool_size": 8}, + "pose_coverage": { + "entity": "object", + "place_reference": "goal", + "grids": grids(), + }, + } + validate_sampling(value) + return value + + +def test_legacy_config_and_simple_fifo_keep_identical_poses(): + old = {"engine": {}, "scene": {}} + expected = deepcopy(old) + validate_sampling(old) + assert old == expected + env = environment() + opts = options() + simple = _BoundedPoseSource(env, opts["scene"], seed=7, revision="revision") + new = _AdaptivePoseSource(env, opts, seed=7, revision="revision") + for ordinal in range(4): + assert ( + new.candidate(ordinal).scene.pose_changes + == simple.candidate(ordinal).scene.pose_changes + ) + + +@pytest.mark.parametrize("strategy", ["bounded_pose", "workspace_joint"]) +@pytest.mark.parametrize("policy", ["fifo", "task_pose_coverage"]) +def test_candidate_is_frozen_after_feedback_and_source_is_seeded(strategy, policy): + opts = options(strategy, policy) + a = _AdaptivePoseSource(environment(), opts, seed=7, revision="revision") + b = _AdaptivePoseSource(environment(), opts, seed=7, revision="revision") + first = a.candidate(0) + assert first == b.candidate(0) + assert a.validate(0).accepted + a.finish(0, None, None, executed=True) + assert a.candidate(0) is first + assert a.budget.counts["candidates"] <= 64 + assert len(a._predicted) == 0 + + +def test_bounded_budget_never_bypasses_candidate_quota(): + a = _AdaptivePoseSource(environment(), options(), seed=7, revision="r") + a.budget.charge("candidates", 64) + with pytest.raises(FeasibilityBudgetExhausted): + a.budget.charge("candidates") + assert a.budget.counts["candidates"] == 64 + + +def test_invalid_joint_config_does_not_fall_back(): + opt = options() + opt["scene_sampling"]["strategy"] = "workspace_joint" + with pytest.raises(ValueError, match="target transforms"): + validate_sampling(opt) + + +def test_sampler_checkpoint_replays_choices_after_feedback(): + opts = options("workspace_joint", "task_pose_coverage") + a = _AdaptivePoseSource(environment(), opts, seed=7, revision="r") + first = a.candidate(0) + a.finish(0, None, None, executed=True) + state = json.loads(json.dumps(a.state_dict())) + b = _AdaptivePoseSource(environment(), opts, seed=7, revision="r") + b.load_state_dict(state) + assert b.candidate(0) == first + assert a.candidate(1) == b.candidate(1) + assert a.budget.counts == b.budget.counts + + +def test_relative_pose_validation_preserves_yaw_symmetry_and_tilt(): + from embodichain.lab.task_program.integrations.feasibility import ( + MeasuredTaskMonitor, + ) + + actual = torch.eye(4).repeat(2, 1, 1) + target = actual.clone() + target[:, 2, 3] = -0.1 + actual[:, 2, 3] = 0.02 + actual[0, 0, 0] = actual[0, 1, 1] = -1 + actual[1, 0, 0] = actual[1, 1, 1] = 0 + actual[1, 0, 1] = -1 + actual[1, 1, 0] = 1 + + class Entity: + def __init__(self, poses): + self.poses = poses + + def get_local_pose(self, to_matrix=False): + if to_matrix: + return self.poses.clone() + return self.poses[:, :3, 3].clone() + + objects = {"object": Entity(actual), "target": Entity(target)} + env = SimpleNamespace(sim=SimpleNamespace(get_rigid_object=objects.get)) + condition = { + "kind": "pose_relative", + "entity": "object", + "other": "target", + "position_offset": [0, 0, 0.12], + "position_tolerance": [0.02, 0.02, 0.01], + "yaw_period_rad": math.pi, + "yaw_tolerance_rad": 0.18, + "tilt_tolerance_rad": 0.18, + } + monitor = MeasuredTaskMonitor([condition], [], env_id=0) + assert monitor.predicate(env, condition) + monitor.env_id = 1 + assert not monitor.predicate(env, condition) + actual[1] = actual[0] + actual[1, 2, 3] += 0.02 + assert not monitor.predicate(env, condition) + with pytest.raises(ValueError): + MeasuredTaskMonitor([{**condition, "yaw_period_rad": 0}], []) + + +def test_workspace_fifo_does_not_require_coverage_policy(): + opts = options("workspace_joint", "fifo") + del opts["pose_coverage"] + validate_sampling(opts) + source = _AdaptivePoseSource(environment(), opts, seed=7, revision="r") + assert source.coverage is None + source.candidate(0) + assert source.validate(0).accepted + source.finish(0, None, None, executed=False) + opts["scheduling"]["policy"] = "task_pose_coverage" + with pytest.raises(ValueError, match="grids"): + validate_sampling(opts) + + +def test_checkpoint_rejects_out_of_grid_cell_without_partial_restore(): + cov = coverage() + cov.reserve(episode()) + state = cov.state_dict() + state["pending"]["c1"] = ("scene-a", (("pick", 99, 0, 0),)) + restored = TaskPoseCoverage("domain", "object", grids()) + with pytest.raises(ValueError): + restored.load_state_dict(state) + assert not restored._cases and not restored._pending + + +def test_sampling_proposal_budget_counts_discarded_pool_candidates(): + opts = options("bounded_pose", "task_pose_coverage") + source = _AdaptivePoseSource(environment(), opts, seed=7, revision="r") + source.candidate(0) + assert source.budget.counts["candidates"] == 8 + assert len(source._candidates) == 1 + # Re-reading the chosen immutable candidate consumes no extra budget. + source.candidate(0) + assert source.budget.counts["candidates"] == 8 + + +def test_coverage_gain_uses_confirmed_pending_and_predicted_separately(): + cov = coverage() + e = episode() + cells = cov.cells( + e.observations["rigid/object/state"][0], + e.observations["rigid/object/state"][-1], + ) + assert cov.gain(cells) == 2 + cov.reserve(e) + assert cov.gain(cells) == 1 + cov.release("scene-a", "c1") + assert cov.gain(cells) == 2 + assert cov.gain(cells, {c: 1 for c in cells}) == 1 + + +def test_workspace_branch_must_match_execution_policy(): + source = _AdaptivePoseSource( + environment(), options("workspace_joint"), seed=7, revision="r" + ) + source.env.cfg = SimpleNamespace( + task_program=SimpleNamespace( + integration=SimpleNamespace(runtime_preset="trajectory") + ) + ) + pick = SimpleNamespace(fixed_object_to_eef=torch.eye(4)) + profile = SimpleNamespace( + presets={ + "trajectory": SimpleNamespace(skill_option_templates={"pick_up": pick}) + } + ) + adapter = SimpleNamespace( + _factory=SimpleNamespace(create_robot_skill_profile=lambda: profile) + ) + from embodichain.lab.task_program.semantics.calls import Pick + from embodichain.lab.task_program.semantics.scene import SceneObjectRef + + program = SimpleNamespace( + iter_segments=lambda: [ + SimpleNamespace( + calls=[SimpleNamespace(call=Pick(object=SceneObjectRef("object")))] + ) + ] + ) + source.bind_program(adapter, program) + pick.fixed_object_to_eef[0, 3] = 0.1 + with pytest.raises(ValueError, match="match"): + source.bind_program(adapter, program) + pick.fixed_object_to_eef = None + with pytest.raises(ValueError, match="fixed_object"): + source.bind_program(adapter, program) + + +def test_budget_expiry_before_first_command_has_no_fabricated_hold(): + from embodichain.lab.expansion._workload_cursor import _WorkloadCursor + + class Bridge: + def __iter__(self): + raise AssertionError("Expired planning must not enter the bridge") + yield + + class Budget: + def check(self): + raise FeasibilityBudgetExhausted("ik_budget_exhausted") + + cursor = _WorkloadCursor( + Bridge(), SimpleNamespace(device=torch.device("cpu")), 7, budget=Budget() + ) + assert cursor.next() is None + assert cursor.finished and not cursor.accepted and cursor.length == 0 + assert cursor.reason == "ik_budget_exhausted" and cursor.last_command is None + + +def test_coverage_rejects_nonphysical_yaw_period_and_identifies_branch_cut(): + from embodichain.lab.expansion._pose_cells import _grid + + with pytest.raises(ValueError, match="complete turn"): + _grid( + { + "lower": [-1, -1, -0.5], + "upper": [1, 1, 0.5], + "cell_size": [0.5, 0.5, 0.1], + "yaw_period": 1, + } + ) + cov = coverage() + a = [0, 0, 0, 0, 0, 1, 0] + b = [0, 0, 0, 0, 0, -1, 0] + assert cov.cells(a, a) == cov.cells(b, b) + + +def test_cache_configuration_is_used_and_empty_qualified_cache_fails(): + from unittest.mock import Mock + + env = environment() + opts = options("workspace_joint") + opts["scene_sampling"]["workspace_source"] = "cache" + cache = SimpleNamespace( + sample_indices=Mock(side_effect=ValueError("No samples meet min_score")) + ) + env.robot.cfg = SimpleNamespace( + to_dict=lambda: {"uid": "robot"}, + workspace_cfg={"arm": SimpleNamespace(strategy="point_uniform", min_score=0.8)}, + ) + env.robot.get_workspace = lambda part: cache + with pytest.raises(ValueError, match="min_score"): + _AdaptivePoseSource(env, opts, seed=7, revision="r") + assert cache.sample_indices.call_args.kwargs["strategy"] == "point_uniform" + assert cache.sample_indices.call_args.kwargs["min_score"] == 0.8 + + +def test_fifo_without_coverage_still_checks_grasp_correspondence(): + from embodichain.lab.task_program.semantics.calls import Pick + from embodichain.lab.task_program.semantics.scene import SceneObjectRef + + opts = options("workspace_joint") + del opts["pose_coverage"] + source = _AdaptivePoseSource(environment(), opts, seed=7, revision="r") + source.env.cfg = SimpleNamespace( + task_program=SimpleNamespace( + integration=SimpleNamespace(runtime_preset="trajectory") + ) + ) + fixed = torch.eye(4) + fixed[2, 3] = 0.2 + profile = SimpleNamespace( + presets={ + "trajectory": SimpleNamespace( + skill_option_templates={ + "pick_up": SimpleNamespace(fixed_object_to_eef=fixed) + } + ) + } + ) + adapter = SimpleNamespace( + _factory=SimpleNamespace(create_robot_skill_profile=lambda: profile) + ) + program = SimpleNamespace( + iter_segments=lambda: [ + SimpleNamespace( + calls=[SimpleNamespace(call=Pick(object=SceneObjectRef("object")))] + ) + ] + ) + with pytest.raises(ValueError, match="match"): + source.bind_program(adapter, program) + + +def test_transport_guard_remembers_a_drop_and_resets_per_episode(): + from embodichain.lab.task_program.integrations.feasibility import ( + MeasuredTaskMonitor, + ) + + state = torch.tensor([[0.0, 0.0, 0.02]]) + goal = torch.tensor([[0.5, 0.0, 0.02]]) + objects = { + "object": SimpleNamespace(get_local_pose=lambda: state.clone()), + "goal": SimpleNamespace(get_local_pose=lambda: goal.clone()), + } + env = SimpleNamespace( + sim=SimpleNamespace( + get_rigid_object=objects.get, + get_rigid_object_uid_list=lambda: tuple(objects), + ) + ) + condition = { + "kind": "transport_guard", + "entity": "object", + "other": "goal", + "lift_height_m": 0.05, + "minimum_transit_height_m": 0.025, + "goal_tolerance_m": 0.03, + } + monitor = MeasuredTaskMonitor([condition], []) + monitor.reset(env) + assert not monitor.validation(env).accepted + state[0, 2] = 0.08 + monitor.observe(env, None) + assert monitor.validation(env).accepted + state[0, 2] = 0.02 + monitor.observe(env, None) + state[0] = goal[0] + monitor.observe(env, None) + assert not monitor.validation(env).accepted + state[0] = torch.tensor([0.0, 0.0, 0.02]) + monitor.reset(env) + state[0, 2] = 0.08 + monitor.observe(env, None) + state[0] = goal[0] + monitor.observe(env, None) + assert monitor.validation(env).accepted + + +def test_new_feedback_hook_preserves_legacy_positional_extension_constructor(): + from embodichain.lab.expansion.host_extensions import GymExpansionHostExtensions + + factory = lambda env, row: None + extensions = GymExpansionHostExtensions(None, None, None, None, factory, True) + assert ( + extensions.require_plan_transform + and extensions.plan_transform_factory is factory + ) + assert extensions.feedback_factory is None + + +def test_bounded_source_owns_input_ranges(): + cfg = options()["scene"] + source = _BoundedPoseSource(environment(), cfg, seed=7, revision="r") + expected = source.candidate(3) + cfg["object"]["translation_m"][0][:] = [0.5, 0.5] + assert source.candidate(3) == expected + + +def test_transport_guard_rejects_nonfinite_measured_state(): + from embodichain.lab.task_program.integrations.feasibility import ( + MeasuredTaskMonitor, + ) + + state = torch.tensor([[0.0, 0.0, 0.02]]) + goal = torch.tensor([[0.5, 0.0, 0.02]]) + objects = { + "object": SimpleNamespace(get_local_pose=lambda: state.clone()), + "goal": SimpleNamespace(get_local_pose=lambda: goal.clone()), + } + env = SimpleNamespace( + sim=SimpleNamespace( + get_rigid_object=objects.get, + get_rigid_object_uid_list=lambda: tuple(objects), + ) + ) + condition = { + "kind": "transport_guard", + "entity": "object", + "other": "goal", + "lift_height_m": 0.05, + "minimum_transit_height_m": 0.025, + "goal_tolerance_m": 0.03, + } + monitor = MeasuredTaskMonitor([condition], []) + monitor.reset(env) + state[0, 2] = 0.08 + monitor.observe(env, None) + assert monitor.validation(env).accepted + state[0, 2] = float("nan") + monitor.observe(env, None) + assert not monitor.validation(env).accepted diff --git a/tests/lab/task_program/test_semantic_compiler.py b/tests/lab/task_program/test_semantic_compiler.py index 001e32598e..2d9b436506 100644 --- a/tests/lab/task_program/test_semantic_compiler.py +++ b/tests/lab/task_program/test_semantic_compiler.py @@ -2373,3 +2373,30 @@ def test_occurrence_policy_rejects_unknown_preset_and_assurance_changes( (Pick(object=SceneObjectRef("cube")),), preset_ids=(preset_id,) ) assert all(provider.calls == 0 for provider in providers) + + +def test_place_grounds_scene_relative_pose_from_current_observation() -> None: + from embodichain.lab.task_program.semantics.calls import SemanticRelativePose + + registry, (_, table) = _scene_registry() + compiler, _ = _compiler(registry) + pick = compiler.analyze((Pick(object=SceneObjectRef("cube")),)) + semantics = compiler.ground(pick, 0, _context(registry)).invocation.goal.semantics + object_to_eef = torch.eye(4).repeat(2, 1, 1) + object_to_eef[:, 2, 3] = 0.12 + target = SemanticRelativePose("table", (0.1, 0.0, 0.02), (0, 0, 0, 1)) + workflow = compiler.analyze((Place(object=SceneObjectRef("cube"), at=target),)) + first = compiler.ground( + workflow, 0, _held_context(registry, semantics, object_to_eef) + ) + expected = table.pose.clone() + expected[:, 0, 3] += 0.1 + expected[:, 2, 3] += 0.14 + torch.testing.assert_close(first.invocation.goal.xpos, expected) + table.pose[:, 1, 3] += 0.2 + second = compiler.ground( + workflow, 0, _held_context(registry, semantics, object_to_eef) + ) + expected[:, 1, 3] += 0.2 + torch.testing.assert_close(second.invocation.goal.xpos, expected) + assert not torch.equal(first.invocation.goal.xpos, second.invocation.goal.xpos) From 910db94634a55c58d59a86869296ec85196f8542 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 03:34:59 +0000 Subject: [PATCH 30/49] feat(expansion): add bidirectional conditional layout sampling Generate layouts from authored anchors or workspace samples and alternate proposal directions within the existing budget. Retain the default bounded sampler, full task screening and independent measured acceptance. Compare all four strategies on pick/place, stacking and dual-arm RGB sorting. --- .../topics/expansion-engine/workloads.md | 41 ++ .../topics/scene-expansion/scene-expansion.md | 21 +- .../embodichain.lab.sim.scene.expansion.rst | 26 + embodichain/compute/geometry/_hierarchical.py | 21 +- embodichain/lab/expansion/_pose_sampling.py | 22 +- .../lab/expansion/_pose_sampling_cfg.py | 166 ++++- .../lab/expansion/_robot_first_sampling.py | 207 ++++++ .../lab/expansion/_scene_first_sampling.py | 377 +++++++++++ embodichain/lab/expansion/gym_workloads.py | 6 + .../lab/expansion/task_program_jobs.py | 9 +- .../lab/sim/scene/expansion/__init__.py | 2 + .../lab/sim/scene/expansion/conditions.py | 183 +++++ embodichain/lab/sim/scene/expansion/layout.py | 24 + .../lab/sim/scene/feasibility/proposals.py | 157 +++-- .../acceptance/scene_first/README.md | 20 + .../acceptance/scene_first/env.yaml | 125 ++++ .../acceptance/scene_first/expansion.yaml | 555 +++++++++++++++ .../acceptance/scene_first/integration.yaml | 82 +++ .../acceptance/scene_first/program.yaml | 86 +++ .../acceptance/scene_first/task.yaml | 18 + .../acceptance/scene_first/README.md | 9 + .../acceptance/scene_first/env.yaml | 99 +++ .../acceptance/scene_first/expansion.yaml | 296 ++++++++ .../acceptance/scene_first/integration.yaml | 69 ++ .../acceptance/scene_first/program.yaml | 44 ++ .../acceptance/scene_first/task.yaml | 19 + .../acceptance/scene_first/README.md | 9 + .../acceptance/scene_first/env.yaml | 93 +++ .../acceptance/scene_first/expansion.yaml | 295 ++++++++ .../acceptance/scene_first/integration.yaml | 47 ++ .../acceptance/scene_first/program.yaml | 44 ++ .../acceptance/scene_first/task.yaml | 19 + .../benchmark/expansion/README.scene_first.md | 101 +++ scripts/benchmark/expansion/scene_first.py | 635 ++++++++++++++++++ .../expansion/test_scene_first_report.py | 161 +++++ .../expansion/test_scene_first_sampling.py | 428 ++++++++++++ tests/sim/scene/expansion/test_conditions.py | 238 +++++++ 37 files changed, 4666 insertions(+), 88 deletions(-) create mode 100644 embodichain/lab/expansion/_robot_first_sampling.py create mode 100644 embodichain/lab/expansion/_scene_first_sampling.py create mode 100644 embodichain/lab/sim/scene/expansion/conditions.py create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/README.md create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/env.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/expansion.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/integration.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/program.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/task.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/README.md create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/env.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/expansion.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/integration.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/program.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/task.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/README.md create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/env.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/integration.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/program.yaml create mode 100644 extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml create mode 100644 scripts/benchmark/expansion/README.scene_first.md create mode 100644 scripts/benchmark/expansion/scene_first.py create mode 100644 tests/benchmark/expansion/test_scene_first_report.py create mode 100644 tests/lab/expansion/test_scene_first_sampling.py create mode 100644 tests/sim/scene/expansion/test_conditions.py diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 9edead8cc6..a3a245238c 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -204,6 +204,47 @@ The configured acceptance task is `extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place`; its four-way runner is `scripts/benchmark/expansion/task_pose_coverage.py`. +## Conditional layout proposals and task screening + +`scene_sampling.strategy: scene_first` adds a prepared support-tree layout source +before ordinary native execution. `_scene_first_sampling.py` reuses shared scene +preparation/conditional generation and `RobotFeasibilityBackend`/`plan_task_mode`; +it creates no physics World and owns only the isolated collision-query resources. +`layout` and `task_mode` are explicit, validated task declarations. Root layout +variables currently use XY only; selected nested members retain declared XY/yaw. +B=1 is checked before runtime creation. A `bounded_pose` job may opt into the +same layout/task-mode screens for a controlled comparison without changing +ordinary simple-sampling defaults. Screening budgets are bounded and separate +from fixed physical quality thresholds. Prepared candidates stay immutable by +ordinal; failed screening cannot turn into an accepted simple fallback. + +`robot_first` anchors one movable support-tree root per proposal from the +workspace of a declared `robot_anchors` phase/part target. It uses the target's +initial rigid relation to the root and projects current-arena TCP XY onto the +root's allowed XY domain, preserving authored height and rotation. Per-part FK +populations are prepared once and selected across occupied cells. The layout +generator reserves the anchor and completes the remaining groups. A prior +without an in-domain sample is a budgeted rejection. + +`bidirectional` alternates scene-first and robot-first by raw ordinal, including +rejections. Attempt budgets, FIFO or task-pose coverage selection, execution and +receipt rules stay in their shared owners. The source records the direction of +each draw and selection, and records the requested anchor separately from the +generated and measured poses. + +The current geometry, joint limits, full-pose FK residuals, full-state/mimic +branches and synchronized path collision checks remain in their existing owners. +Actual execution replans and measured acceptance/persistence remain mandatory. +`scene-first-checks.json` retains phase results, workspace prior and anchor +evidence, and the unchanged World clock; +the query is closed before the owner environment, including setup failures. +The reproducible cross-task runner is +`scripts/benchmark/expansion/scene_first.py`; per-task fixtures are under the +existing grab/place, stack and dual-arm RGB sorting task configurations. The +sorting program operates the two arms sequentially and retains its original +segment validators; receipt-based coverage counts both manipulated blocks and +does not turn fixed-goal tracking noise into placement diversity. + ## Focused validation `tests/lab/expansion/test_workloads_sim.py` runs a real four-row task through diff --git a/agent_context/topics/scene-expansion/scene-expansion.md b/agent_context/topics/scene-expansion/scene-expansion.md index f2bf1e517b..0086ea2467 100644 --- a/agent_context/topics/scene-expansion/scene-expansion.md +++ b/agent_context/topics/scene-expansion/scene-expansion.md @@ -11,6 +11,12 @@ imported from `embodichain.lab.sim.scene.expansion`. movable permissions. `prepare_scene_randomization` prepares geometry; `generate_scene_variants` returns addressed CPU/CUDA candidates; `apply_scene_variants` preflights selected rigid poses without stepping. +`SceneLayoutCondition` restricts prepared generation to explicit arena-pose +anchors, with root XY/member XY-yaw permissions retained. Moving ancestors +must also be anchored. Anchored roots reserve space before unanchored groups +are sampled. Invalid domains reject before generation; unsupported +geometry returns budget exhaustion rather than silently moving the anchors. +The source/policy remain reusable; empty conditions preserve the old stream. `SimulationSceneExpansionHost` prepares/restores ordered rows with independent validation. Offline scheduling and confirmed persistence belong to the [Expansion Engine](../expansion-engine/expansion-engine.md). @@ -31,8 +37,19 @@ attempt through the shared selected-row preparation/restoration contract. The task-facing rolling collector also exposes selectable bounded versus workspace-conditioned pose proposals with optional receipt-confirmed task-pose coverage feedback; see [workload feedback](../expansion-engine/workloads.md#optional-task-pose-proposal-feedback). -This is distinct from offline atlas region validation and does not certify -continuous reachable volume. +The collector's optional scene-first, robot-first and bidirectional strategies +compose support-tree layout generation with the existing full-state task +feasibility backend. Robot-first projects a declared target's workspace TCPs to +root XY conditions before generating the rest of the layout. See the +[conditional layout source contract](../expansion-engine/workloads.md#conditional-layout-proposals-and-task-screening) +for selectors and direction scheduling. Explicit +`layout` and `task_mode` declarations bind support parents, permissions and +synchronized task stages. Its current path screening requires B=1, including +for a bounded-sampling baseline that opts into the same screens. Declared +workspace caches supply seeds; no cache hit certifies a pose or task. Pure +layout queries do not advance the owning World; topology changes invalidate +the prepared geometry. This is distinct from offline atlas region validation +and does not certify continuous reachable volume. ## Entry points diff --git a/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst b/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst index 70132c16ba..84f4e27f9d 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst @@ -135,6 +135,7 @@ proposals. Hosts retain stepping, cache refresh and task-acceptance ownership. :nosignatures: SceneLayoutInput + SceneLayoutCondition PreparedSceneRandomization SceneRandomizationBatch SceneVariantApplicationResult @@ -154,6 +155,22 @@ proposals. Hosts retain stepping, cache refresh and task-acceptance ownership. .. autoclass:: SceneLayoutInput :members: +Conditional layout generation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``generate_scene_variants(..., conditions=SceneLayoutCondition(poses))`` fixes +arena-space anchors while completing the rest of the layout through the same +support and clearance checks. Group-root anchors currently restrict XY only; +selected members retain their support-frame XY/yaw domain. Anchor every moving +ancestor of an absolute member anchor. Conditions cannot change permissions, +height, authored tilt, topology or physics. Invalid domains reject before sampling; +geometric infeasibility consumes the bounded proposal budget without repair. +The prepared source and original policy stay reusable and independently owned. +Omitting conditions, or providing an empty condition, retains the legacy sequence. + +.. autoclass:: SceneLayoutCondition + :members: + .. autoclass:: PreparedSceneRandomization :members: @@ -192,3 +209,12 @@ proposals. Hosts retain stepping, cache refresh and task-acceptance ownership. .. autofunction:: save_scene_variants .. autofunction:: load_scene_variants + +Condition implementation module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: embodichain.lab.sim.scene.expansion.conditions + +.. autoclass:: SceneLayoutCondition + :members: + :no-index: diff --git a/embodichain/compute/geometry/_hierarchical.py b/embodichain/compute/geometry/_hierarchical.py index 68acbad096..88587d2934 100644 --- a/embodichain/compute/geometry/_hierarchical.py +++ b/embodichain/compute/geometry/_hierarchical.py @@ -212,6 +212,7 @@ def _sample_hierarchy( support_gap: float, movable_roots: tuple[int, ...] | None = None, root_offset_bounds: dict[int, torch.Tensor] | None = None, + anchored_roots: tuple[int, ...] = (), ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]: """One proposal per ordinal, with no per-member retry loops.""" local = [matrix.expand(count, 4, 4).clone() for matrix in relative] @@ -299,7 +300,7 @@ def _sample_hierarchy( world.append( local[node] if parent < 0 else _matrix_product(world[parent], local[node]) ) - root_boxes, deltas = [], [] + root_boxes, deltas = [], {} fixed_boxes = {} if randomize_groups and movable_roots is not None: for root in root_keys: @@ -327,7 +328,15 @@ def _sample_hierarchy( ) fixed_boxes[root] = box root_boxes.append(box) - for root, key in root_keys.items(): + # Place exact anchors before variable groups, so their space is already + # reserved when choosing the free region of an unanchored sibling. + roots = ( + sorted(root_keys, key=lambda root: root not in anchored_roots) + if anchored_roots + else root_keys + ) + for root in roots: + key = root_keys[root] points = ( _rotate_points( _subtree_points(root, local, corners, parents), world[root][:, :3, :3] @@ -336,8 +345,8 @@ def _sample_hierarchy( ) box = torch.stack((points[:, :, :2].amin(1), points[:, :, :2].amax(1)), dim=1) if root in fixed_boxes: - deltas.append( - torch.zeros((count, 2), dtype=relative.dtype, device=relative.device) + deltas[root] = torch.zeros( + (count, 2), dtype=relative.dtype, device=relative.device ) continue if randomize_groups: @@ -392,9 +401,9 @@ def _sample_hierarchy( >= group_margin - 1e-10 ) root_boxes.append(box) - deltas.append(delta) + deltas[root] = delta return ( - torch.stack(deltas, dim=1), + torch.stack([deltas[root] for root in root_keys], dim=1), ( torch.stack([sampled[node] for node in sorted(targets)], dim=1) if targets diff --git a/embodichain/lab/expansion/_pose_sampling.py b/embodichain/lab/expansion/_pose_sampling.py index 99e2eaf5a4..85c41306fe 100644 --- a/embodichain/lab/expansion/_pose_sampling.py +++ b/embodichain/lab/expansion/_pose_sampling.py @@ -375,6 +375,16 @@ def _check(self, candidate): return False, "full_pose_fk_residual" return True, "passed" + def _offer(self, candidate, rng, raw): + if self.cfg["strategy"] == "workspace_joint": + candidate, origin = self._guided(candidate, rng) + ok, reason = self._check(candidate) + return candidate, origin, ok, reason + return candidate, "bounded_pose", True, "passed" + + def _offer_origin(self, raw): + return self.cfg["strategy"] + def candidate(self, ordinal): from dataclasses import replace from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted @@ -420,15 +430,12 @@ def candidate(self, ordinal): else raw ) last = candidate + origin = self._offer_origin(raw) try: self.budget.charge("candidates") self._raw_ordinal += 1 ok = True - if self.cfg["strategy"] == "workspace_joint": - candidate, origin = self._guided(candidate, rng) - ok, reason = self._check(candidate) - else: - reason = "passed" + candidate, origin, ok, reason = self._offer(candidate, rng, raw) except FeasibilityBudgetExhausted as e: ok = False reason = str(e) @@ -457,7 +464,7 @@ def candidate(self, ordinal): } ) if ok: - pool.append((candidate, cells, origin)) + pool.append((candidate, cells, origin, raw)) if self.schedule["policy"] == "fifo" and pool: break if self.budget._blocked is not None: @@ -488,7 +495,7 @@ def score(entry): ids = np.flatnonzero(scores == scores.max()) chosen = pool[int(rng.choice(ids))] selection = "coverage" - candidate, cells, origin = chosen + candidate, cells, origin, raw = chosen self._predicted[ordinal] = cells reason = "passed" else: @@ -514,6 +521,7 @@ def score(entry): { "event": "selection", "ordinal": ordinal, + "raw_ordinal": raw, "candidate_id": candidate.candidate_id, "selection": selection, "origin": origin, diff --git a/embodichain/lab/expansion/_pose_sampling_cfg.py b/embodichain/lab/expansion/_pose_sampling_cfg.py index 0f996d6370..c0ae0999ba 100644 --- a/embodichain/lab/expansion/_pose_sampling_cfg.py +++ b/embodichain/lab/expansion/_pose_sampling_cfg.py @@ -22,6 +22,9 @@ __all__: list[str] = [] +_ROBOT_LAYOUT_STRATEGIES = ("robot_first", "bidirectional") +_LAYOUT_STRATEGIES = ("scene_first", *_ROBOT_LAYOUT_STRATEGIES) + def validate_sampling(value: dict) -> None: """Normalize optional settings without changing legacy configurations.""" @@ -29,6 +32,10 @@ def validate_sampling(value: dict) -> None: allowed = { "strategy", + "layout", + "task_mode", + "screening", + "robot_anchors", "workspace_source", "control_part", "sample_count", @@ -70,9 +77,14 @@ def validate_sampling(value: dict) -> None: "exploration_fraction": 0.25, }.items(): schedule.setdefault(k, v) - if sampling["strategy"] not in ("bounded_pose", "workspace_joint"): + if sampling["strategy"] not in ( + "bounded_pose", + "workspace_joint", + *_LAYOUT_STRATEGIES, + ): raise ValueError( - "scene_sampling.strategy must be bounded_pose or workspace_joint" + "scene_sampling.strategy must be bounded_pose, workspace_joint, " + "scene_first, robot_first or bidirectional" ) if sampling["workspace_source"] not in ("cache", "joint_uniform_fk"): raise ValueError( @@ -134,6 +146,156 @@ def validate_sampling(value: dict) -> None: raise ValueError( "Workspace targets require a declared independent scene entity and rigid transform" ) + if sampling["strategy"] == "workspace_joint" and "layout" in sampling: + raise ValueError( + "workspace_joint does not consume layout conditions; choose scene_first or a screened bounded_pose baseline" + ) + if sampling["strategy"] in _LAYOUT_STRATEGIES or "layout" in sampling: + if ( + value["engine"].get("batch_size", 1) + * value["engine"].get("workload_count", 1) + != 1 + ): + raise ValueError("Layout task-path screening currently requires B=1") + layout = sampling.get("layout") + if ( + not isinstance(layout, dict) + or set(layout) - {"support_uid", "parent_by_uid", "policy", "conditions"} + or not {"support_uid", "parent_by_uid", "policy"} <= layout.keys() + ): + raise ValueError( + "Layout sampling requires support_uid, parent_by_uid and policy" + ) + if ( + not isinstance(layout["support_uid"], str) + or not layout["support_uid"].strip() + or not isinstance(layout["parent_by_uid"], dict) + or not layout["parent_by_uid"] + or any( + type(k) is not str or type(v) is not str + for k, v in layout["parent_by_uid"].items() + ) + ): + raise ValueError( + "layout requires an explicit support UID and parent mapping" + ) + if not isinstance(layout["policy"], dict): + raise ValueError("layout.policy must be a mapping") + mode = sampling.get("task_mode") + if ( + not isinstance(mode, dict) + or set(mode) - {"mode_id", "phases"} + or not {"mode_id", "phases"} <= mode.keys() + or not isinstance(mode["phases"], list) + or not mode["phases"] + ): + raise ValueError( + "Layout sampling requires a declared task_mode phase graph" + ) + screening = sampling.setdefault("screening", {}) + if not isinstance(screening, dict) or set(screening) - { + "beam_width", + "ik_seeds", + "max_rrt_nodes", + "planning_timeout_s", + }: + raise ValueError("Unknown scene-first screening budgets") + for key, default in { + "beam_width": 2, + "ik_seeds": 2, + "max_rrt_nodes": 64, + "planning_timeout_s": 0.5, + }.items(): + screening.setdefault(key, default) + for key in ("beam_width", "ik_seeds", "max_rrt_nodes"): + if type(screening[key]) is not int or not 1 <= screening[key] <= 4096: + raise ValueError("Screening counts must be positive and bounded") + if ( + type(screening["planning_timeout_s"]) not in (int, float) + or not math.isfinite(screening["planning_timeout_s"]) + or not 0 < screening["planning_timeout_s"] <= 60 + ): + raise ValueError("Screening timeout must be positive and bounded") + from embodichain.lab.sim.scene.expansion.layout import _policy_data + from embodichain.lab.sim.scene.feasibility import request_from_mapping + + normalized_policy = _policy_data(layout["policy"]) + if any( + "follow" in value["scene"].get(uid, {}) + for uid in normalized_policy["intra_group"]["targets"] + ): + raise ValueError( + "Rigid scene followers cannot also be independent intra-group targets" + ) + parents = layout["parent_by_uid"] + support = layout["support_uid"] + for uid in parents: + seen = set() + current = uid + while current != support: + if current in seen or current not in parents: + raise ValueError("Layout parents must form one rooted support tree") + seen.add(current) + current = parents[current] + identities = {support, *parents, *value["scene"]} + request = request_from_mapping( + dict( + task_id="preflight", + robot_profile_id="preflight", + policy_id="preflight", + validator_id="preflight", + parent_scene_id="preflight", + entity_poses={uid: np.eye(4).tolist() for uid in identities}, + variables=[], + modes=[mode], + ) + ) + for uid, parent in parents.items(): + if ( + parent == support + and uid in value["scene"] + and "follow" not in value["scene"][uid] + ): + bounds = value["scene"][uid] + if bounds["yaw_rad"] != [0, 0] or bounds["translation_m"][2] != [0, 0]: + raise ValueError("Root layout domains currently support XY only") + conditions = layout.get("conditions", {}) + if not isinstance(conditions, dict): + raise ValueError("layout.conditions must map UIDs to arena poses") + for uid, m in conditions.items(): + m = np.asarray(m, dtype=float) + if ( + m.shape != (4, 4) + or not np.isfinite(m).all() + or not np.allclose(m[3], [0, 0, 0, 1]) + or not np.allclose(m[:3, :3].T @ m[:3, :3], np.eye(3), atol=1e-6) + or not np.isclose(np.linalg.det(m[:3, :3]), 1) + ): + raise ValueError("layout conditions require proper rigid matrices") + if ( + "robot_anchors" in sampling + or sampling["strategy"] in _ROBOT_LAYOUT_STRATEGIES + ): + from ._robot_first_sampling import _anchor_targets + + anchors = _anchor_targets( + request.modes[0], + layout, + normalized_policy, + sampling.get("robot_anchors"), + ) + if any( + a.root_uid not in value["scene"] + or "follow" in value["scene"][a.root_uid] + for a in anchors + ): + raise ValueError( + "A robot anchor requires an independently declared scene root" + ) + elif "task_mode" in sampling: + raise ValueError("task_mode screening requires an explicit layout") + elif "robot_anchors" in sampling: + raise ValueError("robot_anchors requires an explicit layout and task_mode") coverage = value.get("pose_coverage") if coverage is None: if schedule["policy"] == "task_pose_coverage": diff --git a/embodichain/lab/expansion/_robot_first_sampling.py b/embodichain/lab/expansion/_robot_first_sampling.py new file mode 100644 index 0000000000..1cbd0cdabe --- /dev/null +++ b/embodichain/lab/expansion/_robot_first_sampling.py @@ -0,0 +1,207 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Owned workspace priors for conditional layout completion.""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +import numpy as np + +from embodichain.lab.sim.scene.expansion import SceneLayoutCondition +from embodichain.lab.sim.scene.feasibility.proposals import _workspace_fk_samples + +if TYPE_CHECKING: + from embodichain.lab.sim.objects import Robot + from embodichain.lab.sim.scene.expansion import PreparedSceneRandomization + from embodichain.lab.sim.scene.feasibility import ( + FeasibilityBudget, + PhaseTarget, + TaskOperationMode, + ) + +__all__: list[str] = [] + + +@dataclass(frozen=True) +class _AnchorTarget: + phase_id: str + target: PhaseTarget + root_uid: str + + +def _anchor_targets( + mode: TaskOperationMode, layout: Mapping, policy: Mapping, selections: object +) -> tuple[_AnchorTarget, ...]: + """Resolve each named target to a rigid frame in the initial support tree.""" + if not isinstance(selections, list) or not selections: + raise ValueError( + "robot_anchors requires a nonempty list of phase/part selectors" + ) + targets = {} + moved = set() + support, parents = layout["support_uid"], layout["parent_by_uid"] + variable_members = policy["intra_group"]["targets"] + for phase in mode.phases: + for target in phase.targets: + targets[phase.phase_id, target.control_part] = (target, moved.copy()) + moved.update(held.entity_uid for held in phase.held_objects) + moved.update(change.entity_uid for change in phase.resulting_poses) + result, seen = [], set() + for sel in selections: + if ( + not isinstance(sel, Mapping) + or set(sel) != {"phase_id", "control_part"} + or any(type(value) is not str for value in sel.values()) + ): + raise ValueError("robot_anchors selects explicit phase_id and control_part") + key = (sel["phase_id"], sel["control_part"]) + if key not in targets or key in seen: + raise ValueError("robot_anchors must select unique declared phase targets") + seen.add(key) + target, earlier_moves = targets[key] + root = target.frame_uid + if root not in parents: + raise ValueError("A robot anchor target needs a frame in the support tree") + while True: + if root in variable_members or root in earlier_moves: + raise ValueError( + "A robot anchor needs an initial frame rigidly attached to its layout root" + ) + if parents[root] == support: + break + root = parents[root] + groups = policy["group_targets"] + if not policy["randomize_groups"] or ( + groups is not None and root not in groups + ): + raise ValueError("A robot anchor requires a movable layout root") + if root in layout.get("conditions", {}): + raise ValueError("A robot anchor cannot replace an authored root condition") + result.append(_AnchorTarget(key[0], target, root)) + return tuple(result) + + +@dataclass(frozen=True) +class _AnchorPool: + selection: _AnchorTarget + base: np.ndarray + buckets: tuple[np.ndarray, ...] + + def condition( + self, visit: int, fixed: SceneLayoutCondition + ) -> SceneLayoutCondition | None: + """Cycle over occupied cells and shuffle within each cell once per job.""" + if not self.buckets: + return None + cycle, cell = divmod(visit, len(self.buckets)) + points = self.buckets[cell] + pose = self.base.copy() + pose[:2, 3] = points[cycle % len(points)] + return SceneLayoutCondition({**fixed.poses, self.selection.root_uid: pose}) + + def metrics(self) -> dict[str, object]: + return { + "phase_id": self.selection.phase_id, + "control_part": self.selection.target.control_part, + "root_uid": self.selection.root_uid, + "samples_in_domain": sum(map(len, self.buckets)), + "occupied_xy_cells": len(self.buckets), + } + + +def _prepare_anchor_pools( + robot: Robot, + budget: FeasibilityBudget, + prepared: PreparedSceneRandomization, + config: Mapping[str, Any], + selections: Sequence[_AnchorTarget], + scene: Mapping[str, Any], + nominal: Mapping[str, np.ndarray], + *, + seed: int, +) -> tuple[_AnchorPool, ...]: + """Precompute at most sample_count FK rows per arm, retaining only legal XY.""" + policy = prepared.policy + movable_roots = { + root + for root, parent in prepared.source.parent_by_uid.items() + if parent == prepared.source.support_uid and root in prepared.movable_uids + } + nodes_by_part: dict[str, list[tuple[int, _AnchorTarget]]] = {} + for index, selection in enumerate(selections): + root = selection.root_uid + if root not in movable_roots or root not in scene or "follow" in scene[root]: + raise ValueError( + f"Robot anchor root {root!r} must have independent XY bounds" + ) + nodes_by_part.setdefault(selection.target.control_part, []).append( + (index, selection) + ) + + pools = {} + for part, entries in nodes_by_part.items(): + part_index = entries[0][0] + fk = _workspace_fk_samples( + robot, + budget, + control_part=part, + source=config["workspace_source"], + sample_count=config["sample_count"], + seed=seed + part_index, + ) + for index, selection in entries: + root, target = selection.root_uid, selection.target + base = np.array(prepared.source.poses[root], dtype=float) + bounds = np.asarray(scene[root]["translation_m"], dtype=float)[:2].T + bounds = bounds + np.asarray(nominal[root])[:2, 3] + offsets = policy["group_xy_offset_bounds_m"].get(root) + if offsets is not None: + layout_bounds = base[:2, 3] + np.asarray(offsets) + bounds[0] = np.maximum(bounds[0], layout_bounds[0]) + bounds[1] = np.minimum(bounds[1], layout_bounds[1]) + lower, upper = bounds + if np.any(upper < lower): + raise ValueError(f"Robot anchor root {root!r} has disjoint XY bounds") + + # Preserve sampled TCP XY under the root's allowed rotation/height. + # Sampled TCP height/orientation are not retained by this projection. + frame = np.asarray(prepared.source.poses[target.frame_uid]) + root_from_tcp = np.linalg.solve(base, frame @ np.asarray(target.pose)) + xy = fk[:, :2, 3] - (base[:3, :3] @ root_from_tcp[:3, 3])[:2] + xy[:, lower == upper] = lower[lower == upper] + xy = xy[np.all((lower <= xy) & (xy <= upper), axis=1)] + # Balance across occupied cells, so a dense set of joint samples in + # one region cannot dominate every proposal. No extrapolation. + size = budget.cfg.archive_bins + scaled = np.divide( + xy - lower, upper - lower, out=np.zeros_like(xy), where=upper > lower + ) + cells = np.minimum((scaled * size).astype(int), size - 1) + occupied = cells[:, 0] * size + cells[:, 1] + rng = np.random.default_rng(np.random.SeedSequence([seed, index])) + buckets = [] + for cell in rng.permutation(np.unique(occupied)): + points = rng.permutation(xy[occupied == cell]) + points.setflags(write=False) + buckets.append(points) + base.setflags(write=False) + pools[index] = _AnchorPool(selection, base, tuple(buckets)) + budget.check() + return tuple(pools[index] for index in range(len(selections))) diff --git a/embodichain/lab/expansion/_scene_first_sampling.py b/embodichain/lab/expansion/_scene_first_sampling.py new file mode 100644 index 0000000000..f9a7c20838 --- /dev/null +++ b/embodichain/lab/expansion/_scene_first_sampling.py @@ -0,0 +1,377 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Conditional layout proposals with shared full task screening.""" + +from __future__ import annotations + +from dataclasses import replace +import math +import time +import numpy as np + +from ._pose_sampling import _AdaptivePoseSource +from ._pose_sampling_cfg import _ROBOT_LAYOUT_STRATEGIES +from ._robot_first_sampling import _anchor_targets, _prepare_anchor_pools +from embodichain.lab.sim.scene.expansion import ( + SceneLayoutCondition, + scene_layout_input_from_sim, + prepare_scene_randomization, + generate_scene_variants, + ScenePoseChange, + SceneVariant, +) + +__all__: list[str] = [] + + +class _LayoutPoseSource(_AdaptivePoseSource): + """Generate or certify complete layouts before checking task branches. + + The numerical layout source owns no World. The existing task backend owns + workspace seed selection, full-state IK and collision-checked path screening. + Runtime execution still replans and independently validates measured outcomes. + """ + + def __init__(self, env, options, *, seed, revision): + if env.num_envs != 1: + raise ValueError("Layout task-path screening currently requires B=1") + before = self._world_clock(env.sim) + self._collision = None + super().__init__(env, options, seed=seed, revision=revision) + for key, value in self.cfg["screening"].items(): + setattr(self.budget.cfg, key, value) + self.budget.cfg.__post_init__() + layout = self.cfg["layout"] + source = scene_layout_input_from_sim( + env.sim, + support_uid=layout["support_uid"], + parent_by_uid=layout["parent_by_uid"], + movable_entity_ids=tuple( + uid for uid in options["scene"] if uid in layout["parent_by_uid"] + ), + scene_id=revision, + ) + self._prepared_layout = prepare_scene_randomization(source, layout["policy"]) + self._fixed_layout = { + uid: ScenePoseChange(uid, source.poses[uid]) + for uid in self.configuration + if uid in source.poses and uid not in self._prepared_layout.movable_uids + } + self._conditions = SceneLayoutCondition(layout.get("conditions", {})) + # Compile/check condition syntax and permissions before any row is reset. + from embodichain.lab.sim.scene.expansion.conditions import _condition_prepared + + _condition_prepared(self._prepared_layout, self._conditions) + nodes = self._prepared_layout._geometry["nodes"] + for n in nodes: + if n["uid"] in options["scene"] and n["parent"] < 0: + bounds = options["scene"][n["uid"]] + if "follow" not in bounds and ( + bounds["yaw_rad"] != [0, 0] or bounds["translation_m"][2] != [0, 0] + ): + raise ValueError( + "Root layout sampling supports XY only; put member yaw in a declared intra-group domain" + ) + from embodichain.lab.sim.scene.feasibility import request_from_mapping + + entities = { + uid: obj.get_local_pose(to_matrix=True)[0].detach().cpu().double().tolist() + for uid in env.sim.get_rigid_object_uid_list() + if (obj := env.sim.get_rigid_object(uid)) is not None + } + entities[env.robot.uid] = self.roots[env.robot.uid] + if getattr(env.sim, "_default_plane", None) is not None: + entities["default_plane"] = np.eye(4).tolist() + request = request_from_mapping( + dict( + task_id=revision, + robot_profile_id=env.robot.uid, + policy_id=revision, + validator_id=revision, + parent_scene_id=revision, + entity_poses=entities, + variables=[], + modes=[self.cfg["task_mode"]], + ) + ) + self._mode = request.modes[0] + for phase in self._mode.phases: + for target in phase.targets: + if ( + target.control_part not in env.robot.control_parts + or env.robot.get_solver(name=target.control_part) is None + ): + raise ValueError( + f"Task phase names unavailable control part {target.control_part!r}" + ) + self._entities = {k: np.array(v) for k, v in entities.items()} + self._anchor_pools = () + self._workspace_seconds = self._screening_seconds = 0.0 + if self.cfg["strategy"] in _ROBOT_LAYOUT_STRATEGIES: + started = time.perf_counter() + selections = _anchor_targets( + self._mode, + layout, + self._prepared_layout.policy, + self.cfg["robot_anchors"], + ) + self._anchor_pools = _prepare_anchor_pools( + env.robot, + self.budget, + self._prepared_layout, + self.cfg, + selections, + self.configuration, + self.poses, + seed=seed, + ) + self._workspace_seconds = time.perf_counter() - started + + from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( + collision_bodies_from_simulation, + ) + from .acceptance import _GeometryRow + from embodichain.lab.sim.scene.feasibility import NewtonCollisionChecker + + bodies = collision_bodies_from_simulation(env) + known = {b.frame_uid for b in bodies} + ignored, _ = _GeometryRow.contact_permissions(env, options["validation"], known) + try: + self._collision = NewtonCollisionChecker( + bodies, ignored_pairs=ignored, device="cpu", max_shapes=512 + ) + self._check_clock(env.sim, before) + except BaseException: + self.close() + raise + self._scene_identity = ( + (id(env.sim.spawn_result), env.sim.spawn_result.topology_revision) + if hasattr(env.sim, "spawn_result") + else None + ) + self._task_checks = {} + self._anchor_checks = {} + + def bind_program(self, adapter, program): + """Keep the declared phase graph and live runtime independent authorities.""" + if not tuple(program.iter_segments()): + raise ValueError("Layout sampling requires a nonempty task program") + + @staticmethod + def _world_clock(sim): + return getattr(sim, "physics_step_index", None), getattr( + sim, "simulation_time", None + ) + + @classmethod + def _check_clock(cls, sim, before): + if before != cls._world_clock(sim): + raise RuntimeError("Scene proposal screening advanced the owning World") + + def _offer_origin(self, raw): + if self.cfg["strategy"] == "bidirectional": + return "robot_first" if (raw + self.seed) % 2 else "scene_first" + return super()._offer_origin(raw) + + def _offer(self, candidate, rng, raw): + sim = self.env.sim + if self._scene_identity is not None and self._scene_identity != ( + id(sim.spawn_result), + sim.spawn_result.topology_revision, + ): + raise RuntimeError( + "Prepared layout geometry is stale after a topology change" + ) + before = self._world_clock(sim) + started = time.perf_counter() + try: + return self._offer_layout(candidate, raw, self._offer_origin(raw)) + finally: + self._screening_seconds += time.perf_counter() - started + self._check_clock(sim, before) + self._task_checks.setdefault(raw, []).append( + dict( + stage="screening.clock", + status="passed", + reason="Owning World step/time unchanged", + phase_id=None, + ) + ) + + def _offer_layout(self, candidate, raw, origin): + if origin != "bounded_pose": + conditions = self._conditions + if origin == "robot_first": + ordinal = raw // 2 if self.cfg["strategy"] == "bidirectional" else raw + visit, index = divmod(ordinal, len(self._anchor_pools)) + pool = self._anchor_pools[index] + conditions = pool.condition(visit, conditions) + self._anchor_checks[raw] = { + "root_uid": pool.selection.root_uid, + "phase_id": pool.selection.phase_id, + "control_part": pool.selection.target.control_part, + "pose": ( + None + if conditions is None + else conditions.poses[pool.selection.root_uid] + ), + } + if conditions is None: + return candidate, origin, False, "no_workspace_anchor" + batch = generate_scene_variants( + self._prepared_layout, + seed=self.seed, + candidate_count=1, + max_attempts=1, + start_ordinal=raw, + conditions=conditions, + ) + if not batch.variants: + return candidate, origin, False, "layout_budget_exhausted" + generated = batch.variants[0] + # References outside the support tree (e.g. a numerical goal) + # retain their declared independent bounded sampling. + changes = { + c.entity_uid: self._fixed_layout.get(c.entity_uid, c) + for c in candidate.scene.pose_changes + } + changes.update({c.entity_uid: c for c in generated.pose_changes}) + candidate = replace( + candidate, + scene=SceneVariant( + candidate.scene.parent_scene_id, + self.seed, + raw, + tuple(changes.values()), + generated.metadata, + ), + ) + else: + # Equal downstream geometric/kinematic gates for the simple baseline. + for change in candidate.scene.pose_changes: + fixed = self._fixed_layout.get(change.entity_uid) + if fixed is not None and not np.allclose( + change.arena_pose, fixed.arena_pose, rtol=0, atol=1e-9 + ): + return candidate, origin, False, "layout_moves_fixed_entity" + anchors = { + c.entity_uid: c.arena_pose + for c in candidate.scene.pose_changes + if c.entity_uid in self._prepared_layout.movable_uids + } + for uid, pose in self._conditions.poses.items(): + actual = anchors.get(uid, self._prepared_layout.source.poses[uid]) + if not np.allclose(actual, pose, rtol=0, atol=1e-9): + return candidate, "bounded_pose", False, "condition_mismatch" + batch = generate_scene_variants( + self._prepared_layout, + seed=self.seed, + candidate_count=1, + max_attempts=1, + start_ordinal=raw, + conditions=SceneLayoutCondition(anchors), + ) + if not batch.variants: + return candidate, "bounded_pose", False, "layout_budget_exhausted" + poses = { + **self._entities, + **{ + c.entity_uid: np.array(c.arena_pose) + for c in candidate.scene.pose_changes + }, + **{uid: np.array(pose) for uid, pose in candidate.deployment.poses.items()}, + } + # Never expand explicit task-facing ranges while applying layout policy. + for c in candidate.scene.pose_changes: + opts = self.configuration[c.entity_uid] + if "follow" in opts: + continue + delta = np.asarray(c.arena_pose)[:3, 3] - self.poses[c.entity_uid][:3, 3] + bounds = np.asarray(opts["translation_m"]) + rotation = np.asarray(c.arena_pose)[:3, :3] @ np.linalg.inv( + self.poses[c.entity_uid][:3, :3] + ) + yaw = math.atan2(rotation[1, 0], rotation[0, 0]) + low, high = opts["yaw_rad"] + yaw += 2 * math.pi * round(((low + high) / 2 - yaw) / (2 * math.pi)) + if ( + np.any(delta < bounds[:, 0] - 1e-6) + or np.any(delta > bounds[:, 1] + 1e-6) + or yaw < low - 1e-6 + or yaw > high + 1e-6 + ): + return ( + candidate, + origin, + False, + "layout_outside_task_domain", + ) + from embodichain.lab.sim.scene.feasibility import ( + RobotFeasibilityBackend, + plan_task_mode, + ) + + backend = RobotFeasibilityBackend( + self.env.robot, + self._collision, + self.budget.cfg, + poses, + seed=self.seed + raw, + ) + plan = plan_task_mode(self._mode, backend, poses, self.budget) + self._task_checks[raw] = [ + { + "stage": c.stage, + "status": c.status, + "reason": c.reason, + "phase_id": c.phase_id, + } + for c in plan.checks + ] + reason = ( + "passed" + if plan.accepted + else next( + (c.reason for c in plan.checks if c.status != "passed"), + "task_path_unverified", + ) + ) + return candidate, origin, plan.accepted, reason + + def checkpoint(self): + super().checkpoint() + if self.output is not None and hasattr(self, "_task_checks"): + from embodichain.data_pipeline.recording.media import _atomic_json + + _atomic_json( + self.output / "scene-first-checks.json", + dict( + phase_checks=self._task_checks, + layout_source=self._prepared_layout.source.fingerprint, + conditions=self._conditions.to_dict(), + workspace_prior=[pool.metrics() for pool in self._anchor_pools], + workspace_anchor_checks=self._anchor_checks, + workspace_prepare_wall_s=self._workspace_seconds, + proposal_screen_wall_s=self._screening_seconds, + ), + ) + + def close(self): + """Release only query resources, without modifying the owning World.""" + if self._collision is not None: + self._collision.close() + self._collision = None diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 8c61d3c501..c8e32ac457 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -751,6 +751,7 @@ def physical_key(env_id: str, cfg: Any) -> str: ) owner = source = None + feedback_closers = [] groups: dict[str, Any] = {} adapters: dict[int, Any] = {} futures: dict[str, Any] = {} @@ -847,6 +848,9 @@ def physical_key(env_id: str, cfg: Any) -> str: ctx.feedback = workload.extensions.feedback_factory( env, ctx.scene_source, path ) + close = getattr(ctx.feedback, "close", None) + if close is not None: + feedback_closers.append(close) builder = GymRecipeBuilder(ctx) transform = workload.extensions.recipe_transform ctx.recipe = lambda ordinal, builder=builder, transform=transform: ( @@ -1064,5 +1068,7 @@ def done(name: str, counts: Mapping[str, object]) -> None: adapter.close() for group in groups.values(): group["host"]._context.journal.checkpoint(force=True, state="finished") + for close in reversed(feedback_closers): + close() if owner is not None: owner.close() diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index c92a00c296..55af8d08d0 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -66,8 +66,15 @@ def _task_expansion_extensions(*, options, operator, seed, report): def source(env): nonlocal pose_source + from ._scene_first_sampling import _LayoutPoseSource + + source_type = ( + _LayoutPoseSource + if "layout" in options.get("scene_sampling", {}) + else _AdaptivePoseSource + ) pose_source = ( - _AdaptivePoseSource(env, options, seed=seed, revision=report["semantic_id"]) + source_type(env, options, seed=seed, revision=report["semantic_id"]) if "scene_sampling" in options else _BoundedPoseSource( env, options["scene"], seed=seed, revision=report["semantic_id"] diff --git a/embodichain/lab/sim/scene/expansion/__init__.py b/embodichain/lab/sim/scene/expansion/__init__.py index 32758cf991..35b0707b5c 100644 --- a/embodichain/lab/sim/scene/expansion/__init__.py +++ b/embodichain/lab/sim/scene/expansion/__init__.py @@ -27,10 +27,12 @@ from .cfg import SceneExpansionCfg from .contracts import ScenePoseChange, SceneVariant +from .conditions import SceneLayoutCondition from .source import FixedSceneCandidateSource __all__ = [ "SceneExpansionCfg", + "SceneLayoutCondition", "ScenePoseChange", "SceneVariant", "FixedSceneCandidateSource", diff --git a/embodichain/lab/sim/scene/expansion/conditions.py b/embodichain/lab/sim/scene/expansion/conditions.py new file mode 100644 index 0000000000..2b70be330d --- /dev/null +++ b/embodichain/lab/sim/scene/expansion/conditions.py @@ -0,0 +1,183 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Owned arena-space anchors that restrict an existing prepared layout domain.""" + +from __future__ import annotations + +from collections.abc import Mapping +from copy import deepcopy +from dataclasses import dataclass, replace +import math +from types import MappingProxyType +from typing import TYPE_CHECKING + +import numpy as np + +from .._validation import _identifier, _rigid_pose + +if TYPE_CHECKING: + from .layout import PreparedSceneRandomization + +__all__ = ["SceneLayoutCondition"] + + +@dataclass(frozen=True) +class SceneLayoutCondition: + """Fix declared entities to arena poses without enlarging their motion domain. + + Args: + poses: Native UID to rigid arena-space pose. Inputs are independently + owned immutable tuples. Group roots retain their authored rotation + and height; selected members retain their declared support-frame + XY/yaw constraints. A moving ancestor of a member anchor must also + be anchored, so an absolute anchor cannot drift with its parent. + + Conditions do not authorize new motion, topology changes or physics steps. + Geometric infeasibility yields an empty/budget-exhausted generation result; + malformed or unsupported conditions reject before candidate generation. + """ + + poses: Mapping[str, object] + + def __post_init__(self) -> None: + if not isinstance(self.poses, Mapping): + raise TypeError("Condition poses must be a UID-to-pose mapping") + owned = {} + for uid, pose in self.poses.items(): + _identifier(uid, "condition UID") + owned[uid] = _rigid_pose(pose) + object.__setattr__(self, "poses", MappingProxyType(dict(sorted(owned.items())))) + + def to_dict(self) -> dict[str, list[list[float]]]: + """Return a detached JSON-compatible projection of the anchors.""" + return {uid: [list(row) for row in pose] for uid, pose in self.poses.items()} + + +def _condition_prepared( + prepared: PreparedSceneRandomization, condition: SceneLayoutCondition +) -> PreparedSceneRandomization: + """Compile anchors to zero-width bounds, keeping existing geometry checks.""" + if not isinstance(condition, SceneLayoutCondition): + raise TypeError("conditions must be SceneLayoutCondition") + if not condition.poses: + return prepared + source, policy = prepared.source, prepared.policy + unknown = set(condition.poses) - set(source.poses) + if unknown: + raise ValueError(f"Unknown condition entities: {sorted(unknown)}") + nodes = prepared._geometry["nodes"] + index = {n["uid"]: i for i, n in enumerate(nodes)} + roots = {nodes[i]["uid"] for i in prepared._movable_roots} + targets = policy["intra_group"]["targets"] + variable = roots | set(targets) + world = {source.support_uid: np.asarray(source.poses[source.support_uid])} + for n in nodes: + uid = n["uid"] + original = np.asarray(source.poses[uid]) + parent_uid = source.parent_by_uid[uid] + anchored = uid in condition.poses + if anchored: + parent = parent_uid + while parent != source.support_uid: + if parent in variable and parent not in condition.poses: + raise ValueError( + f"Anchor {uid!r} requires its moving ancestor {parent!r} to be anchored" + ) + parent = source.parent_by_uid[parent] + parent_world = world[parent_uid] + if n["parent"] < 0: + if not anchored: + world[uid] = original + continue + wanted = np.asarray(condition.poses[uid]) + if ( + not np.allclose(wanted[:3, :3], original[:3, :3], rtol=0, atol=1e-9) + or abs(wanted[2, 3] - original[2, 3]) > 1e-9 + ): + raise ValueError( + "Root anchors support declared XY translation only; rotation/height must remain authored" + ) + delta = wanted[:2, 3] - original[:2, 3] + if uid not in roots: + if not np.allclose(delta, 0, rtol=0, atol=1e-9): + raise ValueError(f"Condition cannot move fixed group {uid!r}") + else: + bounds = policy["group_xy_offset_bounds_m"].get(uid) + if bounds is not None and ( + np.any(delta < np.asarray(bounds)[0] - 1e-9) + or np.any(delta > np.asarray(bounds)[1] + 1e-9) + ): + raise ValueError("Anchor lies outside declared root XY bounds") + policy["group_xy_offset_bounds_m"][uid] = [ + delta.tolist(), + delta.tolist(), + ] + world[uid] = wanted + continue + relative = np.asarray(n["relative_pose"]) + if not anchored: + world[uid] = parent_world @ relative + continue + wanted = np.asarray(condition.poses[uid]) + if uid not in targets: + if not np.allclose(wanted, parent_world @ relative, rtol=0, atol=1e-9): + raise ValueError(f"Condition cannot move undeclared member {uid!r}") + world[uid] = wanted + continue + spec = targets[uid] + support = prepared._geometry["supports"][parent_uid] + inv_frame = np.linalg.inv(np.asarray(support["parent_from_support"])) + baseline = inv_frame @ relative + local = inv_frame @ np.linalg.inv(parent_world) @ wanted + rotation = local[:3, :3] @ np.linalg.inv(baseline[:3, :3]) + angle = math.degrees(math.atan2(rotation[1, 0], rotation[0, 0])) + c, s = math.cos(math.radians(angle)), math.sin(math.radians(angle)) + yaw_rotation = np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]) + low, high = spec["yaw_delta_range_deg"] + angle += 360 * math.floor(((low + high) / 2 - angle) / 360 + 0.5) + height = ( + policy["intra_group"]["support_gap_m"] + + support.get("height_ceiling_m", 0) + - support["root_min_z"][uid] + ) + if ( + not np.allclose(rotation, yaw_rotation, rtol=0, atol=1e-9) + or abs(local[2, 3] - height) > 1e-9 + ): + raise ValueError( + "Member anchor violates its authored tilt or support height" + ) + if angle < low - 1e-8 or angle > high + 1e-8: + raise ValueError("Member anchor lies outside declared yaw bounds") + offset = local[:2, 3] - baseline[:2, 3] + bounds = spec["xy_offset_bounds_m"] + if bounds is not None and ( + np.any(offset < np.asarray(bounds)[0] - 1e-9) + or np.any(offset > np.asarray(bounds)[1] + 1e-9) + ): + raise ValueError("Member anchor lies outside declared XY bounds") + spec["xy_offset_bounds_m"] = [offset.tolist(), offset.tolist()] + spec["yaw_delta_range_deg"] = [angle, angle] + world[uid] = wanted + if source.support_uid in condition.poses and not np.allclose( + condition.poses[source.support_uid], + source.poses[source.support_uid], + rtol=0, + atol=1e-9, + ): + raise ValueError("The main support is fixed") + return replace(prepared, _policy=deepcopy(policy)) diff --git a/embodichain/lab/sim/scene/expansion/layout.py b/embodichain/lab/sim/scene/expansion/layout.py index 479946ce70..14ec5af156 100644 --- a/embodichain/lab/sim/scene/expansion/layout.py +++ b/embodichain/lab/sim/scene/expansion/layout.py @@ -37,6 +37,7 @@ from ..geometry import SupportSurfaceConfig, detect_support_region from ..query import _backend_tensor from .contracts import ScenePoseChange, SceneVariant +from .conditions import SceneLayoutCondition, _condition_prepared from ._layout_numeric import ( _hierarchy_batch_limit, _numeric_geometry, @@ -571,6 +572,7 @@ def generate_scene_variants( candidate_count: int = 10, max_attempts: int = 1000, start_ordinal: int = 0, + conditions: SceneLayoutCondition | None = None, ) -> SceneRandomizationBatch: """Generate a batch without loading meshes or constructing simulation objects. @@ -580,10 +582,17 @@ def generate_scene_variants( candidate_count: Requested valid layouts. max_attempts: Whole-layout proposal budget. start_ordinal: First logical proposal; allows bounded continuation. + conditions: Optional owned arena-pose anchors. They restrict existing + root XY/member XY-yaw domains and never authorize extra motion. + Moving ancestors must be anchored explicitly. Empty conditions + preserve the ordinary sequence. Infeasible geometry exhausts the + declared proposal budget without moving or repairing anchors. Returns: Complete or budget-exhausted proposals with exact continuation ordinal. """ + if conditions is not None: + prepared = _condition_prepared(prepared, conditions) _validate_generation_parameters( seed=seed, candidate_count=candidate_count, @@ -600,6 +609,15 @@ def generate_scene_variants( ): raise ValueError("Requested CUDA device is unavailable.") spec = _specification(prepared._geometry, policy, device) + anchored_roots = ( + tuple( + i + for i in prepared._movable_roots + if prepared._geometry["nodes"][i]["uid"] in conditions.poses + ) + if conditions is not None + else () + ) limit = ( _hierarchy_batch_limit(policy["batch_size"], len(spec[-1])) if policy["randomize_groups"] @@ -619,6 +637,7 @@ def generate_scene_variants( group_margin=policy["collision_margin_m"], support_gap=policy["intra_group"]["support_gap_m"], movable_roots=prepared._movable_roots, + anchored_roots=anchored_roots, root_offset_bounds={ i: torch.tensor( policy["group_xy_offset_bounds_m"][node["uid"]], @@ -656,6 +675,11 @@ def generate_scene_variants( ("generator", _ALGORITHM), ("source_sha256", prepared.source.fingerprint), ("geometry_sha256", prepared.geometry_sha256), + *( + (("conditions_sha256", _digest(conditions.to_dict())),) + if conditions is not None and conditions.poses + else () + ), ), ) return SceneRandomizationBatch( diff --git a/embodichain/lab/sim/scene/feasibility/proposals.py b/embodichain/lab/sim/scene/feasibility/proposals.py index 06c01176da..5bf8281d82 100644 --- a/embodichain/lab/sim/scene/feasibility/proposals.py +++ b/embodichain/lab/sim/scene/feasibility/proposals.py @@ -37,6 +37,83 @@ __all__ = ["RobotWorkspaceProposalSource"] +def _workspace_fk_samples( + robot: Robot, + budget: FeasibilityBudget, + *, + control_part: str, + source: str, + sample_count: int, + seed: int, +) -> np.ndarray: + """Return owned current-arena FK poses from a bounded workspace population.""" + generator = torch.Generator(device=robot.device).manual_seed(seed) + budget.check() + if source == "cache": + workspace = robot.get_workspace(control_part) + settings = robot.cfg.workspace_cfg[control_part] + indices = workspace.sample_indices( + sample_count, + strategy=settings.strategy, + min_score=settings.min_score, + generator=generator, + ) + if ( + indices.shape != (sample_count,) + or indices.dtype != torch.int64 + or bool(((indices < 0) | (indices >= workspace.num_samples)).any()) + ): + raise ValueError("workspace sampler returned invalid cache indices") + qpos = workspace.qpos[indices].to(device=robot.device) + else: + limits = robot.get_qpos_limits(name=control_part)[0] + if ( + not bool(torch.isfinite(limits).all()) + or bool((limits[:, 1] < limits[:, 0]).any()) + or bool((limits.abs() > 1e6).any()) + ): + raise UnsupportedFeasibilityError( + "Joint-uniform workspace preparation requires explicit finite joint bounds" + ) + qpos = limits[:, 0] + torch.rand( + (sample_count, len(limits)), device=robot.device, generator=generator + ) * (limits[:, 1] - limits[:, 0]) + if ( + qpos.ndim != 2 + or len(qpos) != sample_count + or not bool(torch.isfinite(qpos).all()) + ): + raise ValueError( + "workspace proposals require finite selected joint configurations" + ) + poses = np.empty((sample_count, 4, 4), dtype=np.float64) + for start in range(0, sample_count, budget.cfg.batch_size): + budget.check() + stop = min(start + budget.cfg.batch_size, sample_count) + batch = robot.compute_batch_fk( + qpos=qpos[None, start:stop], + name=control_part, + env_ids=[0], + to_matrix=True, + ) + if batch.shape != (1, stop - start, 4, 4): + raise ValueError("workspace FK proposals must match the requested batch") + poses[start:stop] = batch[0].detach().cpu().numpy() + if not np.isfinite(poses).all(): + raise ValueError("workspace FK proposals must be finite rigid matrices") + rotations = poses[:, :3, :3] + if ( + not np.allclose(poses[:, 3, :], [0.0, 0.0, 0.0, 1.0], atol=1e-5, rtol=0) + or not np.allclose( + rotations.transpose(0, 2, 1) @ rotations, np.eye(3), atol=1e-5, rtol=0 + ) + or not np.allclose(np.linalg.det(rotations), 1.0, atol=1e-5, rtol=0) + ): + raise ValueError("workspace FK proposals must be proper rigid transforms") + budget.check() + return poses + + class RobotWorkspaceProposalSource: """Copy current-model FK samples into an independent numerical proposal prior. @@ -112,76 +189,16 @@ def __init__( np.linalg.inv(np.array(target.pose)), np.linalg.inv(np.array(variable.members[target.frame_uid])), ) - generator = torch.Generator(device=robot.device).manual_seed(budget.cfg.seed) - budget.check() - if control_part in (robot.cfg.workspace_cfg or {}): - workspace = robot.get_workspace(control_part) - settings = robot.cfg.workspace_cfg[control_part] - indices = workspace.sample_indices( - sample_count, - strategy=settings.strategy, - min_score=settings.min_score, - generator=generator, - ) - if ( - indices.shape != (sample_count,) - or indices.dtype != torch.int64 - or bool(((indices < 0) | (indices >= workspace.num_samples)).any()) - ): - raise ValueError("workspace sampler returned invalid cache indices") - qpos = workspace.qpos[indices].to(device=robot.device) - origin = "configured_qpos_cache" - else: - limits = robot.get_qpos_limits(name=control_part)[0] - if ( - not bool(torch.isfinite(limits).all()) - or bool((limits[:, 1] < limits[:, 0]).any()) - or bool((limits.abs() > 1e6).any()) - ): - raise UnsupportedFeasibilityError( - "Joint-uniform workspace preparation requires explicit finite joint bounds" - ) - qpos = limits[:, 0] + torch.rand( - (sample_count, len(limits)), device=robot.device, generator=generator - ) * (limits[:, 1] - limits[:, 0]) - origin = "joint_uniform_fk" - if ( - qpos.ndim != 2 - or len(qpos) != sample_count - or not bool(torch.isfinite(qpos).all()) - ): - raise ValueError( - "workspace proposals require finite selected joint configurations" - ) - batches = [] - for start in range(0, sample_count, budget.cfg.batch_size): - budget.check() - batch = ( - robot.compute_batch_fk( - qpos=qpos[None, start : start + budget.cfg.batch_size], - name=control_part, - env_ids=[0], - to_matrix=True, - )[0] - .detach() - .cpu() - .double() - .numpy() - .copy() - ) - batches.append(batch) - poses = np.concatenate(batches) - if poses.ndim != 3 or poses.shape[1:] != (4, 4) or not np.isfinite(poses).all(): - raise ValueError("workspace FK proposals must be finite rigid matrices") - rotations = poses[:, :3, :3] - if ( - not np.allclose(poses[:, 3, :], [0.0, 0.0, 0.0, 1.0], atol=1e-5, rtol=0) - or not np.allclose( - rotations.transpose(0, 2, 1) @ rotations, np.eye(3), atol=1e-5, rtol=0 - ) - or not np.allclose(np.linalg.det(rotations), 1.0, atol=1e-5, rtol=0) - ): - raise ValueError("workspace FK proposals must be proper rigid transforms") + has_cache = control_part in (robot.cfg.workspace_cfg or {}) + poses = _workspace_fk_samples( + robot, + budget, + control_part=control_part, + source="cache" if has_cache else "joint_uniform_fk", + sample_count=sample_count, + seed=budget.cfg.seed, + ) + origin = "configured_qpos_cache" if has_cache else "joint_uniform_fk" self._local = np.linalg.inv(self._root)[None] @ poses self._uniform_fraction = uniform_fraction self._rng = np.random.default_rng(budget.cfg.seed) diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/README.md b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/README.md new file mode 100644 index 0000000000..898a52473c --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/README.md @@ -0,0 +1,20 @@ +# Dual-arm RGB sorting acceptance + +This scene-first fixture reuses the original RGB block-sorting program unchanged: +right arm moves red, left arm moves blue, green stays stationary. It selects the +existing dual-UR5 profile and open-loop dual-arm execution policy. The two arms +act sequentially; this case does not demonstrate simultaneous manipulation. + +Default physics, sensors disabled, B=1. The supported primitive tabletop has its +top at 0.835 m, with the 5 cm blocks resting at 0.86 m. Red/blue nominal poses +are the midpoints of the original reset domains, with the same ±2.5 cm X / ±3 cm +Y ranges. Green is +a fixed reference at its original domain midpoint. Geometry/robot topology stays +fixed. Both source strategies share the same layout and task-path screens. + +All original lift (5 cm), XY placement (3.5 / 3 cm), and wait-stable validators +remain unchanged. Independent measured acceptance additionally requires both +objects at table height, both hands released, green within 5 mm of its initial +reference, and stable terminal speeds. Coverage records both manipulated blocks. + +See [the comparison guide](../../../../../../../../../scripts/benchmark/expansion/README.scene_first.md). diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/env.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/env.yaml new file mode 100644 index 0000000000..bd36d9f6c1 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/env.yaml @@ -0,0 +1,125 @@ +environment_id: conditional_dual_arm_sort +physics: default +max_episodes: 1 +max_episode_steps: 2400 +simulation: + light: + direct: + - uid: light_1 + light_type: sun + color: + - 1.0 + - 1.0 + - 1.0 + intensity: 5.0 + direction: + - 0.0 + - 0.0 + - -1.0 + background: + - uid: support_surface + shape: + shape_type: Cube + size: + - 1.0 + - 1.0 + - 0.1 + body_type: static + init_pos: + - 0.725 + - 0.0 + - 0.785 + rigid_object: + - uid: block_1 + shape: + shape_type: Cube + size: + - 0.05 + - 0.05 + - 0.05 + attrs: + mass_props: + mass: 0.05 + rigid_props: + max_depenetration_velocity: 10.0 + min_position_iters: 32 + min_velocity_iters: 8 + collision_props: + contact_offset: 0.003 + rest_offset: 0.001 + material_props: + static_friction: 0.5 + dynamic_friction: 0.5 + restitution: 0.0 + init_pos: + - 0.625 + - -0.15 + - 0.86 + body_scale: + - 1 + - 1 + - 1 + - uid: block_2 + shape: + shape_type: Cube + size: + - 0.05 + - 0.05 + - 0.05 + attrs: + mass_props: + mass: 0.05 + rigid_props: + max_depenetration_velocity: 10.0 + min_position_iters: 32 + min_velocity_iters: 8 + collision_props: + contact_offset: 0.003 + rest_offset: 0.001 + material_props: + static_friction: 0.5 + dynamic_friction: 0.5 + restitution: 0.0 + init_pos: + - 0.675 + - 0.0 + - 0.86 + body_scale: + - 1 + - 1 + - 1 + - uid: block_3 + shape: + shape_type: Cube + size: + - 0.05 + - 0.05 + - 0.05 + attrs: + mass_props: + mass: 0.05 + rigid_props: + max_depenetration_velocity: 10.0 + min_position_iters: 32 + min_velocity_iters: 8 + collision_props: + contact_offset: 0.003 + rest_offset: 0.001 + material_props: + static_friction: 0.5 + dynamic_friction: 0.5 + restitution: 0.0 + init_pos: + - 0.725 + - 0.15 + - 0.86 + body_scale: + - 1 + - 1 + - 1 +env: + sim_steps_per_control: 4 + events: {} + dataset: {} +num_envs: 1 +arena_space: 3.0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/expansion.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/expansion.yaml new file mode 100644 index 0000000000..1d4d02c893 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/expansion.yaml @@ -0,0 +1,555 @@ +schema_version: 1 +engine: + episodes_per_operator: 4 + max_attempts: 64 + max_steps: 3200 + max_wall_time_s: 600.0 + settling_steps: 30 + capture_media: false + collision_backend: newton + collision_device: cpu +scene: + block_1: + translation_m: + - - -0.025 + - 0.025 + - - -0.03 + - 0.03 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 + block_3: + translation_m: + - - -0.025 + - 0.025 + - - -0.03 + - 0.03 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 +trajectory: + operators: + - object_pose + joint_offset_scale: 0.005 + via_count: 1 + max_proposals: 64 + minimum_joint_delta: 0.002 + velocity_limit: 0.5 + acceleration_limit: 0.5 + nullspace_task_rows: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: + place: + - retract +validation: + initial_checks: + - kind: support_bounds + entity: block_1 + lower: + - 0.2 + - -0.5 + - 0.82 + upper: + - 1.2 + - 0.5 + - 0.95 + - kind: support_bounds + entity: block_2 + lower: + - 0.2 + - -0.5 + - 0.82 + upper: + - 1.2 + - 0.5 + - 0.95 + - kind: support_bounds + entity: block_3 + lower: + - 0.2 + - -0.5 + - 0.82 + upper: + - 1.2 + - 0.5 + - 0.95 + final_checks: &id001 + - kind: axis_relation + entity: block_1 + other: block_2 + axis: 0 + lower: -0.115 + upper: -0.045 + - kind: axis_relation + entity: block_1 + other: block_2 + axis: 1 + lower: -0.03 + upper: 0.03 + - kind: axis_relation + entity: block_1 + other: block_2 + axis: 2 + lower: -0.012 + upper: 0.012 + - kind: speed_below + entity: block_1 + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: axis_relation + entity: block_3 + other: block_2 + axis: 0 + lower: 0.045 + upper: 0.115 + - kind: axis_relation + entity: block_3 + other: block_2 + axis: 1 + lower: -0.03 + upper: 0.03 + - kind: axis_relation + entity: block_3 + other: block_2 + axis: 2 + lower: -0.012 + upper: 0.012 + - kind: speed_below + entity: block_3 + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: joint_range + joint: left_gripper_finger1_joint_1 + lower: -0.001 + upper: 0.005 + - kind: joint_range + joint: right_gripper_finger1_joint_1 + lower: -0.001 + upper: 0.005 + - kind: pose_near + entity: block_2 + position: + - 0.675 + - 0.0 + - 0.86 + tolerance_m: 0.005 + - kind: speed_below + entity: block_2 + linear_m_s: 0.03 + angular_rad_s: 0.2 + events: + - event_id: block_1_lifted + conditions: + - kind: lifted + entity: block_1 + height_m: 0.05 + - event_id: block_3_lifted + conditions: + - kind: lifted + entity: block_3 + height_m: 0.05 + - event_id: both_sorted_released_stable + conditions: *id001 + consecutive_steps: 3 + allowed_contacts: &id002 + - - block_1 + - support_surface + - - block_1 + - default_plane + - - block_2 + - support_surface + - - block_2 + - default_plane + - - block_3 + - support_surface + - - block_3 + - default_plane + - - block_1 + - DualUR5/right_gripper_finger1_link_1 + - - block_1 + - DualUR5/right_gripper_finger2_link_1 + - - block_3 + - DualUR5/left_gripper_finger1_link_1 + - - block_3 + - DualUR5/left_gripper_finger2_link_1 + mounting_contacts: + - - '@root' + - default_plane + - - '@root' + - support_surface +scene_sampling: + strategy: scene_first + workspace_source: joint_uniform_fk + control_part: right_arm + sample_count: 16384 + robot_anchors: + - phase_id: block_1_grasp + control_part: right_arm + - phase_id: block_3_grasp + control_part: left_arm + uniform_fraction: 0.25 + max_candidates: 256 + max_rollouts: 4 + max_ik_calls: 16384 + max_planning_calls: 2048 + targets: {} + layout: + support_uid: support_surface + parent_by_uid: + block_1: support_surface + block_2: support_surface + block_3: support_surface + policy: + group_targets: + - block_1 + - block_3 + batch_size: 1 + collision_margin_m: 0.002 + group_xy_offset_bounds_m: + block_1: + - - -0.025 + - -0.03 + - - 0.025 + - 0.03 + block_3: + - - -0.025 + - -0.03 + - - 0.025 + - 0.03 + task_mode: + mode_id: sort_with_both_arms + phases: + - phase_id: block_1_approach + dependencies: [] + targets: + - control_part: right_arm + frame_uid: block_1 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.11 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: block_1_grasp + dependencies: + - block_1_approach + targets: + - control_part: right_arm + frame_uid: block_1 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: block_1_lift + dependencies: + - block_1_grasp + targets: + - control_part: right_arm + frame_uid: block_1 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.14 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_1 + control_part: right_arm + tcp_from_object: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + - phase_id: block_1_place + dependencies: + - block_1_lift + targets: + - control_part: right_arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - -0.08 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.07 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_1 + control_part: right_arm + tcp_from_object: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + - phase_id: block_1_retreat + dependencies: + - block_1_place + targets: + - control_part: right_arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - -0.08 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.22 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: block_3_approach + dependencies: + - block_1_retreat + targets: + - control_part: left_arm + frame_uid: block_3 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.11 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: block_3_grasp + dependencies: + - block_3_approach + targets: + - control_part: left_arm + frame_uid: block_3 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: block_3_lift + dependencies: + - block_3_grasp + targets: + - control_part: left_arm + frame_uid: block_3 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.14 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_3 + control_part: left_arm + tcp_from_object: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + - phase_id: block_3_place + dependencies: + - block_3_lift + targets: + - control_part: left_arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.08 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.07 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_3 + control_part: left_arm + tcp_from_object: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - -0.01 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + - phase_id: block_3_retreat + dependencies: + - block_3_place + targets: + - control_part: left_arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.08 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.22 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 +scheduling: + policy: fifo + pool_size: 8 + exploration_fraction: 0.25 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/integration.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/integration.yaml new file mode 100644 index 0000000000..63e3ac866d --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/integration.yaml @@ -0,0 +1,82 @@ +integration_id: blocks_ranking_rgb_scene_first_dual_ur5 +program_id: rank_blocks_rgb +requires: + scene_contract: blocks_ranking_rgb_scene_v1 + embodiment_contract: dual_arm_parallel_gripper +scene_binding: + contract_id: blocks_ranking_rgb_scene_v1 + registry_id: task_program_blocks_ranking_rgb + rigid_objects: + - entity_id: block_1 + dynamics: dynamic + semantic_type: block + affordances: + - entity_id: block_1_grasp + kind: antipodal_grasp + - entity_id: block_2 + dynamics: dynamic + semantic_type: block + affordances: + - entity_id: red_placement + kind: support_surface + native_name: red_neighbor + object_target_frame: world_axes + object_target_pose: + position: + - -0.08 + - 0.0 + - 0.08 + quaternion_xyzw: + - 0.0 + - 0.0 + - 0.0 + - 1.0 + - entity_id: blue_placement + kind: support_surface + native_name: blue_neighbor + object_target_frame: world_axes + object_target_pose: + position: + - 0.08 + - 0.0 + - 0.08 + quaternion_xyzw: + - 0.0 + - 0.0 + - 0.0 + - 1.0 + - entity_id: block_3 + dynamics: dynamic + semantic_type: block + affordances: + - entity_id: block_3_grasp + kind: antipodal_grasp +profile: + defaults: + pick_up: + primary: primary_manipulator + place: + primary: primary_manipulator + skill_options: + pick: + kind: pick_up + pre_grasp_distance: 0.12 + lift_height: 0.15 + hand_interp_steps: 10 + grasp_settle_steps: 45 + fixed_object_to_eef: + position: + - 0.0 + - 0.0 + - -0.01 + quaternion_xyzw: + - 1.0 + - 0.0 + - 0.0 + - 0.0 + place: + kind: place + lift_height: 0.15 + hand_interp_steps: 10 + preserve_current_object_orientation: true + effect_monitors: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/program.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/program.yaml new file mode 100644 index 0000000000..9f8ecd558b --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/program.yaml @@ -0,0 +1,86 @@ +program_id: rank_blocks_rgb +instruction: Arrange the red, green, and blue blocks from left to right while keeping the green block + stationary. +targets: {} +program: +- segment: pick_red_block + instruction: Grasp and lift red block clear of the table. + steps: + pick: + object: block_1 + grasp: block_1_grasp + resources: + primary: primary_manipulator + validators: + - kind: object_lifted + object: block_1 + minimum_lift: 0.05 +- segment: place_red_block + instruction: Place the red block left of the green block, release it, and let it settle. + steps: + place: + object: block_1 + 'on': red_placement + resources: + primary: primary_manipulator + post: + - kind: wait_stable + entity: block_1 + validators: + - kind: object_relative_position + object: block_1 + reference: block_2 + position_offset: + - -0.08 + - 0.0 + - 0.0 + position_tolerance: + - 0.035 + - 0.03 + - null +- segment: pick_blue_block + instruction: Grasp and lift blue block clear of the table. + steps: + pick: + object: block_3 + grasp: block_3_grasp + resources: + primary: secondary_manipulator + validators: + - kind: object_lifted + object: block_3 + minimum_lift: 0.05 +- segment: place_blue_block + instruction: Place the blue block right of the green block, release it, and let it settle. + steps: + place: + object: block_3 + 'on': blue_placement + resources: + primary: secondary_manipulator + post: + - kind: wait_stable + entity: block_3 + validators: + - kind: object_relative_position + object: block_3 + reference: block_2 + position_offset: + - 0.08 + - 0.0 + - 0.0 + position_tolerance: + - 0.035 + - 0.03 + - null + - kind: object_relative_position + object: block_1 + reference: block_2 + position_offset: + - -0.08 + - 0.0 + - 0.0 + position_tolerance: + - 0.035 + - 0.03 + - null diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/task.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/task.yaml new file mode 100644 index 0000000000..f63099d29e --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/blocks_ranking_rgb/acceptance/scene_first/task.yaml @@ -0,0 +1,18 @@ +id: ConditionalSceneBlocksRankingRGB-DualUR5-v1 +environment: + component: env.yaml +task_program: + program: program.yaml + integration: integration.yaml + execution_policy: ../../../../../../components/execution_policies/trajectory_open_loop_dual_arm_manipulation.yaml +embodiment: + component: ../../../../../../components/embodiments/dual_ur5_dh_pgi_140_80.yaml + overrides: + init_pos: + - 1.683 + - 0.0 + - 0.5275 + init_rot: + - 0.0 + - 0.0 + - -90.0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/README.md b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/README.md new file mode 100644 index 0000000000..458e189193 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/README.md @@ -0,0 +1,9 @@ +# Conditional scene-first task fixture + +This deployment keeps the task's declared controller, physical acceptance and +confirmed persistence gates while comparing bounded versus scene-first XY layouts. +`expansion.yaml` owns explicit support parents, sampling ranges, the task phase +graph and screening effort. It does not change the ordinary deployment defaults. + +See the [cross-task acceptance guide](../../../../../../../../../scripts/benchmark/expansion/README.scene_first.md) for commands, conditional +anchor semantics, scope restrictions and result interpretation. diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/env.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/env.yaml new file mode 100644 index 0000000000..a2ca89425d --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/env.yaml @@ -0,0 +1,99 @@ +environment_id: conditional_stack +physics: default +max_episodes: 1 +max_episode_steps: 2400 +num_envs: 1 +arena_space: 2.5 +simulation: + light: + direct: + - uid: main_light + light_type: sun + color: + - 0.6 + - 0.6 + - 0.6 + intensity: 5.0 + direction: + - 0.0 + - 0.0 + - -1.0 + - uid: rect_light + light_type: rect + color: + - 1.0 + - 1.0 + - 1.0 + intensity: 8.0 + init_pos: + - -0.42 + - 0.08 + - 0.8 + direction: + - 0.0 + - 0.0 + - -1.0 + rect_width: 0.5 + rect_height: 0.5 + background: + - uid: support_surface + shape: + shape_type: Cube + size: + - 2.0 + - 2.0 + - 0.1 + body_type: static + init_pos: + - 0.0 + - 0.0 + - -0.05 + rigid_object: + - uid: block_1 + shape: + shape_type: Cube + size: + - 0.05 + - 0.05 + - 0.05 + body_type: dynamic + init_pos: + - -0.4 + - 0.48 + - 0.025 + attrs: + mass_props: + mass: 0.05 + rigid_props: + linear_damping: 0.2 + angular_damping: 0.2 + material_props: + dynamic_friction: 0.97 + static_friction: 0.99 + - uid: block_2 + shape: + shape_type: Cube + size: + - 0.05 + - 0.05 + - 0.05 + body_type: dynamic + init_pos: + - -0.42 + - -0.08 + - 0.025 + attrs: + mass_props: + mass: 0.05 + rigid_props: + linear_damping: 0.2 + angular_damping: 0.2 + material_props: + dynamic_friction: 0.97 + static_friction: 0.99 + rigid_object_group: [] + articulation: [] +env: + sim_steps_per_control: 4 + events: {} + dataset: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/expansion.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/expansion.yaml new file mode 100644 index 0000000000..f42b1e302c --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/expansion.yaml @@ -0,0 +1,296 @@ +schema_version: 1 +engine: + episodes_per_operator: 4 + max_attempts: 64 + max_steps: 2400 + max_wall_time_s: 600.0 + settling_steps: 30 + capture_media: false + collision_backend: newton + collision_device: cpu +scene: + block_1: + translation_m: + - - -0.06 + - 0.06 + - - -0.06 + - 0.06 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 + block_2: + translation_m: + - - -0.06 + - 0.06 + - - -0.06 + - 0.06 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 +trajectory: + operators: + - object_pose + joint_offset_scale: 0.005 + via_count: 1 + max_proposals: 64 + minimum_joint_delta: 0.002 + velocity_limit: 0.5 + acceleration_limit: 0.5 + nullspace_task_rows: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: + place: + - retract +validation: + initial_checks: + - kind: support_bounds + entity: block_2 + lower: + - -1 + - -1 + - -0.003 + upper: + - 1 + - 1 + - 0.1 + final_checks: &id001 + - kind: axis_relation + entity: block_2 + other: block_1 + axis: 2 + lower: 0.04 + upper: 0.062 + - kind: speed_below + entity: block_2 + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: speed_below + entity: block_1 + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: joint_range + joint: gripper_finger1_joint_1 + lower: -0.001 + upper: 0.005 + events: + - event_id: lift + conditions: + - kind: lifted + entity: block_2 + height_m: 0.05 + - event_id: stacked + conditions: *id001 + consecutive_steps: 3 + allowed_contacts: &id002 + - - block_1 + - default_plane + - - block_1 + - support_surface + - - block_1 + - UR5/gripper_finger1_link_1 + - - block_1 + - UR5/gripper_finger2_link_1 + - - block_2 + - default_plane + - - block_2 + - support_surface + - - block_2 + - UR5/gripper_finger1_link_1 + - - block_2 + - UR5/gripper_finger2_link_1 + - - block_1 + - block_2 + mounting_contacts: + - - '@root' + - default_plane + - - '@root' + - support_surface +scene_sampling: + strategy: scene_first + workspace_source: joint_uniform_fk + control_part: arm + sample_count: 16384 + robot_anchors: + - phase_id: grasp + control_part: arm + uniform_fraction: 0.25 + max_candidates: 256 + max_rollouts: 4 + max_ik_calls: 16384 + max_planning_calls: 2048 + targets: {} + layout: + support_uid: support_surface + parent_by_uid: + block_1: support_surface + block_2: support_surface + policy: + group_targets: + - block_1 + - block_2 + batch_size: 1 + collision_margin_m: 0.02 + group_xy_offset_bounds_m: + block_1: + - - -0.06 + - -0.06 + - - 0.06 + - 0.06 + block_2: + - - -0.06 + - -0.06 + - - 0.06 + - 0.06 + task_mode: + mode_id: runtime + phases: + - phase_id: approach + dependencies: [] + targets: + - control_part: arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.1 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: grasp + dependencies: + - approach + targets: + - control_part: arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.0 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + - phase_id: lift + dependencies: + - grasp + targets: + - control_part: arm + frame_uid: block_2 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.1 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_2 + control_part: arm + tcp_from_object: + - - 1 + - 0 + - 0 + - 0 + - - 0 + - -1 + - 0 + - 0 + - - 0 + - 0 + - -1 + - 0 + - - 0 + - 0 + - 0 + - 1 + - phase_id: place + dependencies: + - lift + targets: + - control_part: arm + frame_uid: block_1 + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.05 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id002 + held_objects: + - entity_uid: block_2 + control_part: arm + tcp_from_object: + - - 1 + - 0 + - 0 + - 0 + - - 0 + - -1 + - 0 + - 0 + - - 0 + - 0 + - -1 + - 0 + - - 0 + - 0 + - 0 + - 1 +scheduling: + policy: fifo + pool_size: 8 + exploration_fraction: 0.25 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/integration.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/integration.yaml new file mode 100644 index 0000000000..fb0de39013 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/integration.yaml @@ -0,0 +1,69 @@ +integration_id: stack_blocks_two_v1 +program_id: stack_two_blocks +requires: + scene_contract: stack_blocks_two_scene_v1 + embodiment_contract: single_arm_parallel_gripper +scene_binding: + contract_id: stack_blocks_two_scene_v1 + registry_id: task_program_stack_blocks_two + rigid_objects: + - entity_id: block_1 + dynamics: dynamic + semantic_type: block + affordances: + - entity_id: block_1_top + kind: support_surface + native_name: top + object_target_frame: world_axes + object_target_pose: + position: + - 0.0 + - 0.0 + - 0.05 + quaternion_xyzw: + - 0.0 + - 0.0 + - 0.0 + - 1.0 + - entity_id: block_2 + dynamics: dynamic + semantic_type: block + affordances: + - entity_id: block_2_grasp + kind: antipodal_grasp +profile: + defaults: + pick_up: + primary: primary_manipulator + place: + primary: primary_manipulator + skill_options: + pick: + kind: pick_up + pre_grasp_distance: 0.12 + lift_height: 0.15 + hand_interp_steps: 10 + grasp_settle_steps: 45 + fixed_object_to_eef: + - 1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - 1.0 + place: + kind: place + lift_height: 0.1 + hand_interp_steps: 10 + preserve_current_object_orientation: false + effect_monitors: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/program.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/program.yaml new file mode 100644 index 0000000000..8ef78b03e3 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/program.yaml @@ -0,0 +1,44 @@ +program_id: stack_two_blocks +instruction: Stack the two blocks into a stable tower with block 2 on top of block + 1. +targets: {} +program: +- segment: pick_block_2 + instruction: Grasp and lift block 2 clear of the table. + steps: + pick: + object: block_2 + grasp: block_2_grasp + validators: + - kind: object_lifted + object: block_2 + minimum_lift: 0.05 +- segment: place_block_2_on_block_1 + instruction: Place block 2 on top of block 1, release it, and let the stack settle. + steps: + place: + object: block_2 + 'on': block_1_top + post: + - kind: wait_stable + entity: block_2 + - kind: wait_stable + entity: block_1 + validators: + - kind: object_relative_position + object: block_2 + reference: block_1 + position_offset: + - 0.0 + - 0.0 + - 0.05 + position_tolerance: + - 0.025 + - 0.025 + - 0.012 + - kind: object_upright + object: block_1 + maximum_tilt_degrees: 45.0 + - kind: object_upright + object: block_2 + maximum_tilt_degrees: 45.0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/task.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/task.yaml new file mode 100644 index 0000000000..a371b22ba4 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/tableware/stack_blocks_two/acceptance/scene_first/task.yaml @@ -0,0 +1,19 @@ +id: ConditionalSceneStack-UR5-v1 +environment: + component: env.yaml +task_program: + program: program.yaml + integration: integration.yaml + execution_policy: ../../../../../../components/execution_policies/trajectory_open_loop.yaml +embodiment: + component: ../../../../../../components/embodiments/ur5_dh_pgi_140_80.yaml + overrides: + init_qpos: + - 0 + - -1.57 + - 1.57 + - -1.57 + - -1.57 + - 0 + - 0 + - 0 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/README.md b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/README.md new file mode 100644 index 0000000000..de725d51be --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/README.md @@ -0,0 +1,9 @@ +# Conditional scene-first task fixture + +This deployment keeps the task's declared controller, physical acceptance and +confirmed persistence gates while comparing bounded versus scene-first XY layouts. +`expansion.yaml` owns explicit support parents, sampling ranges, the task phase +graph and screening effort. It does not change the ordinary deployment defaults. + +See the [cross-task acceptance guide](../../../../../../../../scripts/benchmark/expansion/README.scene_first.md) for commands, conditional +anchor semantics, scope restrictions and result interpretation. diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/env.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/env.yaml new file mode 100644 index 0000000000..212bf07c3a --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/env.yaml @@ -0,0 +1,93 @@ +environment_id: conditional_pick_place +physics: default +max_episodes: 1 +max_episode_steps: 2400 +num_envs: 1 +arena_space: 2.5 +simulation: + light: + direct: + - uid: main_light + light_type: sun + color: + - 0.6 + - 0.6 + - 0.6 + intensity: 5.0 + direction: + - 0.0 + - 0.0 + - -1.0 + - uid: rect_light + light_type: rect + color: + - 1.0 + - 1.0 + - 1.0 + intensity: 8.0 + init_pos: + - -0.42 + - 0.08 + - 0.8 + direction: + - 0.0 + - 0.0 + - -1.0 + rect_width: 0.5 + rect_height: 0.5 + background: + - uid: goal + shape: + shape_type: Cube + size: + - 0.01 + - 0.01 + - 0.001 + body_type: static + init_pos: + - -0.4 + - 0.48 + - -0.1 + attrs: + collision_props: + collision_enabled: false + - uid: support_surface + shape: + shape_type: Cube + size: + - 2.0 + - 2.0 + - 0.1 + body_type: static + init_pos: + - 0.0 + - 0.0 + - -0.05 + rigid_object: + - uid: cube + shape: + shape_type: Cube + size: + - 0.06 + - 0.04 + - 0.04 + body_type: dynamic + init_pos: + - -0.42 + - -0.08 + - 0.02 + attrs: + mass_props: + mass: 0.05 + rigid_props: + linear_damping: 0.2 + angular_damping: 0.2 + material_props: + dynamic_friction: 0.97 + static_friction: 0.99 + rigid_object_group: [] + articulation: [] +env: + sim_steps_per_control: 4 + events: {} + dataset: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml new file mode 100644 index 0000000000..73e8e9df09 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml @@ -0,0 +1,295 @@ +schema_version: 1 +engine: + episodes_per_operator: 4 + max_attempts: 64 + max_steps: 2400 + max_wall_time_s: 600.0 + settling_steps: 30 + capture_media: false + collision_backend: newton + collision_device: cpu +scene: + cube: + translation_m: + - - -0.06 + - 0.06 + - - -0.06 + - 0.06 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 + goal: + translation_m: + - - -0.06 + - 0.06 + - - -0.06 + - 0.06 + - - 0 + - 0 + yaw_rad: + - 0 + - 0 +trajectory: + operators: + - object_pose + joint_offset_scale: 0.005 + via_count: 1 + max_proposals: 64 + minimum_joint_delta: 0.002 + velocity_limit: 0.5 + acceleration_limit: 0.5 + nullspace_task_rows: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: + place: + - retract +validation: + initial_checks: + - kind: support_bounds + entity: cube + lower: + - -1 + - -0.4 + - -0.003 + upper: + - -0.2 + - 0.7 + - 0.05 + final_checks: + - &id001 + kind: pose_relative + entity: cube + other: goal + position_tolerance: + - 0.02 + - 0.02 + - 0.01 + yaw_tolerance_rad: 0.17453292519943295 + yaw_period_rad: 3.141592653589793 + tilt_tolerance_rad: 0.17453292519943295 + position_offset: + - 0 + - 0 + - 0.12 + - &id002 + kind: joint_range + joint: gripper_finger1_joint_1 + lower: -0.001 + upper: 0.005 + - &id003 + kind: speed_below + entity: cube + linear_m_s: 0.03 + angular_rad_s: 0.2 + - kind: transport_guard + entity: cube + other: goal + lift_height_m: 0.05 + minimum_transit_height_m: 0.025 + goal_tolerance_m: 0.03 + events: + - event_id: lift + conditions: + - kind: lifted + entity: cube + height_m: 0.05 + - event_id: placed_and_released + conditions: + - *id001 + - *id002 + - *id003 + consecutive_steps: 3 + allowed_contacts: &id004 + - - cube + - default_plane + - - cube + - support_surface + - - cube + - UR5/gripper_finger1_link_1 + - - cube + - UR5/gripper_finger2_link_1 + mounting_contacts: + - - '@root' + - default_plane + - - '@root' + - support_surface +scene_sampling: + strategy: scene_first + workspace_source: joint_uniform_fk + control_part: arm + sample_count: 16384 + robot_anchors: + - phase_id: grasp + control_part: arm + uniform_fraction: 0.25 + max_candidates: 256 + max_rollouts: 4 + max_ik_calls: 16384 + max_planning_calls: 2048 + targets: {} + layout: + support_uid: support_surface + parent_by_uid: + cube: support_surface + policy: + group_targets: + - cube + batch_size: 1 + collision_margin_m: 0.02 + group_xy_offset_bounds_m: + cube: + - - -0.06 + - -0.06 + - - 0.06 + - 0.06 + task_mode: + mode_id: runtime + phases: + - phase_id: approach + dependencies: [] + targets: + - control_part: arm + frame_uid: cube + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.1 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id004 + - phase_id: grasp + dependencies: + - approach + targets: + - control_part: arm + frame_uid: cube + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.0 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id004 + - phase_id: lift + dependencies: + - grasp + targets: + - control_part: arm + frame_uid: cube + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.1 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id004 + held_objects: + - entity_uid: cube + control_part: arm + tcp_from_object: + - - 1 + - 0 + - 0 + - 0 + - - 0 + - -1 + - 0 + - 0 + - - 0 + - 0 + - -1 + - 0 + - - 0 + - 0 + - 0 + - 1 + - phase_id: place + dependencies: + - lift + targets: + - control_part: arm + frame_uid: goal + pose: + - - 1.0 + - 0.0 + - 0.0 + - 0.0 + - - 0.0 + - -1.0 + - 0.0 + - 0.0 + - - 0.0 + - 0.0 + - -1.0 + - 0.12 + - - 0.0 + - 0.0 + - 0.0 + - 1.0 + allowed_contacts: *id004 + held_objects: + - entity_uid: cube + control_part: arm + tcp_from_object: + - - 1 + - 0 + - 0 + - 0 + - - 0 + - -1 + - 0 + - 0 + - - 0 + - 0 + - -1 + - 0 + - - 0 + - 0 + - 0 + - 1 +scheduling: + policy: fifo + pool_size: 8 + exploration_fraction: 0.25 diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/integration.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/integration.yaml new file mode 100644 index 0000000000..baa11842f9 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/integration.yaml @@ -0,0 +1,47 @@ +integration_id: workspace_pose_pick_place_v1 +program_id: workspace_pose_pick_place +requires: + scene_contract: workspace_pose_pick_place_scene_v1 + embodiment_contract: single_arm_parallel_gripper +scene_binding: + contract_id: workspace_pose_pick_place_scene_v1 + registry_id: task_program_workspace_pose_pick_place + rigid_objects: + - entity_id: cube + dynamics: dynamic + semantic_type: cube + affordances: + - entity_id: cube_grasp + kind: antipodal_grasp + - entity_id: goal + dynamics: static + semantic_type: placement_reference +profile: + defaults: + pick_up: + primary: primary_manipulator + place: + primary: primary_manipulator + skill_options: + pick: + kind: pick_up + fixed_object_to_eef: + - 1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - -1.0 + - 0.0 + - 0.0 + - 0.0 + - 0.0 + - 1.0 + place: + kind: place + effect_monitors: {} diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/program.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/program.yaml new file mode 100644 index 0000000000..610056960c --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/program.yaml @@ -0,0 +1,44 @@ +program_id: workspace_pose_pick_place +instruction: Pick up the cuboid and place it at the scene-relative goal pose. +targets: + drop_pose: + kind: scene_relative + entity: goal + frame: parent + position: + - 0 + - 0 + - 0.12 + quaternion_xyzw: + - 0 + - 0 + - 0 + - 1 +program: + kind: repeat + count: 1 + body: + kind: sequence + items: + - kind: segment + name: pick_cube + instruction: Grasp and lift the cube. + steps: + kind: invoke + call: + kind: pick + object: cube + - kind: segment + name: place_cube + instruction: Place the cube at the next target position and release it. + steps: + kind: invoke + call: + kind: place + object: cube + at: + kind: target_ref + target: drop_pose + post: + - kind: wait_stable + entity: cube diff --git a/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml new file mode 100644 index 0000000000..73df857927 --- /dev/null +++ b/extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml @@ -0,0 +1,19 @@ +id: ConditionalScenePickPlace-UR5-v1 +environment: + component: env.yaml +task_program: + program: program.yaml + integration: integration.yaml + execution_policy: ../../../../../components/execution_policies/trajectory_open_loop.yaml +embodiment: + component: ../../../../../components/embodiments/ur5_dh_pgi_140_80.yaml + overrides: + init_qpos: + - 0 + - -1.57 + - 1.57 + - -1.57 + - -1.57 + - 0 + - 0 + - 0 diff --git a/scripts/benchmark/expansion/README.scene_first.md b/scripts/benchmark/expansion/README.scene_first.md new file mode 100644 index 0000000000..655dcc7f5a --- /dev/null +++ b/scripts/benchmark/expansion/README.scene_first.md @@ -0,0 +1,101 @@ +# Conditional layout sampling acceptance + +Run the three native task fixtures with: + +```bash +python -m scripts.benchmark.expansion.scene_first --pilot --seeds 7 --rollouts 2 --candidates 8 --output outputs/layout-pilot +python -m scripts.benchmark.expansion.scene_first --seeds 7,18,29,40 --rollouts 6 --candidates 48 --seconds 300 --output outputs/layout-comparison +python -m scripts.benchmark.expansion.scene_first --output outputs/layout-comparison --rebuild +``` + +The collector accepts four strategies for layout comparisons. + +| `scene_sampling.strategy` | Proposal | +| --- | --- | +| `bounded_pose` | Draw each declared independent pose in its bounds. A comparison opts into the same layout and task-path screening by providing `layout` and `task_mode`. | +| `scene_first` | Generate the declared layout before checking the robot's task path. | +| `robot_first` | Use a workspace sample to anchor one support group, then generate the remaining layout. | +| `bidirectional` | Alternate scene-first and robot-first by raw ordinal under the same candidate budget. Seed parity chooses the first direction. | + +The legacy default stays `bounded_pose`. Use `--cases` and `--strategies` to +select subsets. The four-seed run balances the order within each task and uses +one raw draw per attempt. The report merges coverage cells across seeds and +retains per-seed timings, rejected proposals and source counts in `results.json`. + +`layout.support_uid` and `parent_by_uid` select real prepared rigid entities and +an acyclic support tree. The shared scene generator prepares scaled geometry and +conservative support/clearance data once. A proposal fixes optional arena-space +`layout.conditions`, then samples the rest of the allowed layout. It does not +step physics, resize a World or mutate runtime asset topology. It preserves +complete support groups rather than independently mixing their coordinates. + +Current group roots support XY translation with authored rotation/height; +member XY/yaw requires an explicitly declared intra-group policy. Root yaw or +Z expansion is rejected rather than silently ignored. Exact member anchors +require their moving ancestors to be anchored. Anchors restrict an existing +domain, not create a new placement permission. No-condition layouts retain the +old addressed RNG stream and continuation behavior. `SceneLayoutCondition` +is also available directly in `embodichain.lab.sim.scene.expansion`. + +Robot-first and bidirectional jobs declare `scene_sampling.robot_anchors`. Each +entry selects a `phase_id` and `control_part` from `task_mode`. The target must +refer to an existing, movable layout root or to a member rigidly attached to one. +Earlier task phases must leave that relation intact. For example, the sorting +fixture alternates the right-arm red pickup and left-arm blue pickup as anchors. + +The proposal source prepares `sample_count` FK samples per selected control +part, from the declared `workspace_source` (`cache` or `joint_uniform_fk`). +It projects each TCP's XY through the target's authored offset to the initial +group, intersects task and layout bounds, and balances selection across +occupied XY cells. The room occupied by the anchor is reserved during layout +completion. An empty prior spends one raw proposal and rejects that draw. The +next draw in the bidirectional stream still follows its assigned direction. +Height and orientation come from the authored root. The projected pose goes +through full-pose IK and task-path collision screening. + +`task_mode` uses existing TaskOperationMode/TaskPhase declarations. Targets name +control parts explicitly and can describe multiple simultaneous arms. Held-object +transforms belong to each incoming phase and must match the intended task; they +are never inferred from a name. The existing feasibility backend selects current +or cached workspace seeds, checks IK, current joint limits and full-pose FK +residuals, and searches collision-checked full-state phase connections. A cache +miss is not a reachability rejection; bounded direct seeds remain available. +A no-solution result means this attempt exhausted its declared search, not proof +that the complete region is unreachable. Every actual Task Program still grounds +and plans again from the measured prepared scene. + +`screening` bounds beam_width, ik_seeds, max_rrt_nodes and planning_timeout_s; +it changes preflight effort, not acceptance thresholds. All raw proposals, +discarded candidates and IK/planning calls consume the declared budgets. Failed +layout or task screening remains preparation rejection and never earns physical +success or a sink receipt. The B=1 path is explicit; batch settings reject before +World construction. Collision queries own no physical World and are released on +normal completion and startup failures. A topology revision invalidates the +prepared source instead of silently retaining stale geometry. + +The fixtures reuse native Task Program execution, physical geometry, controllers, +segment validators and measured terminal/event acceptance. The grab/place and +stack fixtures use a rectangular primitive support with the existing UR5 +embodiment. The dual-arm RGB sorting fixture reuses its original program and +dual-UR5 profile: right arm moves red, left arm moves blue, with the green +reference fixed. The arms act sequentially; this does not measure simultaneous +bimanual execution. Its original 5 cm lift and 3.5 / 3 cm XY placement bounds +remain unchanged. Independent acceptance additionally checks both release +states, terminal heights/speeds and the stationary green reference. All +movable topology and physical parameters stay fixed. Only declared XY layouts +vary in the controlled run. Both source strategies share the same task ranges, +path checks, physical thresholds and persistence gate. An initial geometry/path +pass never substitutes physical task completion. + +Reports keep proposed/prepared/executed/accepted/persisted counts separately, +record full failed attempts and numerical T+1 evidence, and audit read-back from +confirmed episode artifacts. Declared scene-grid coverage is not a certified +continuous feasible-volume fraction. Task pose diversity is counted separately; +each fixed sorting placement contributes one category rather than novelty from +tracking noise. Both manipulated blocks contribute initial/placement coverage. +For each strategy the report shows cold wall time per seed and per receipt, +including World preparation, screening, execution and export. The separate +screening figure helps identify where time was spent. + +The acceptance path rejects unsupported phases or geometry and uses the original +task validation thresholds. RGB sorting exercises both arms in the comparison. diff --git a/scripts/benchmark/expansion/scene_first.py b/scripts/benchmark/expansion/scene_first.py new file mode 100644 index 0000000000..e63342f3b8 --- /dev/null +++ b/scripts/benchmark/expansion/scene_first.py @@ -0,0 +1,635 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Compare four layout proposal strategies on three native Task Programs. + +Run: python -m scripts.benchmark.expansion.scene_first --output DIR +Use --pilot first. Each case uses a fresh process, Default CPU physics, the +same full-state geometric/task-path screens and measured acceptance/receipts. +""" + +from __future__ import annotations + +import argparse +from collections import Counter, defaultdict +import hashlib +import importlib.metadata +import json +import os +from pathlib import Path +import resource +from statistics import median +import subprocess +import sys +import time +import numpy as np +import yaml + +ROOT = Path(__file__).resolve().parents[3] +TASKS = ROOT / "extensions/embodichain_tasks/configs/tasks/manipulation" +CASES = { + "pick_place": TASKS / "workspace_pose_pick_place/acceptance/scene_first", + "stack": TASKS / "tableware/stack_blocks_two/acceptance/scene_first", + "dual_arm_sort": TASKS / "tableware/blocks_ranking_rgb/acceptance/scene_first", +} +STRATEGIES = ("bounded_pose", "scene_first", "robot_first", "bidirectional") +PLACEMENTS = { + "pick_place": {"cube": ("goal", (0.0, 0.0))}, + "stack": {"block_2": ("block_1", (0.0, 0.0))}, + "dual_arm_sort": { + "block_1": ("block_2", (-0.08, 0.0)), + "block_3": ("block_2", (0.08, 0.0)), + }, +} + + +def _write(path, value): + path.write_text(json.dumps(value, indent=2, default=str) + "\n") + + +def _xy_cell(pose, origin, bounds): + """Four fixed XY bins per authored nonzero axis; never fit bins to results.""" + delta = np.asarray(pose)[:2] - np.asarray(origin)[:2] + lo, hi = np.array(bounds)[:2, 0], np.array(bounds)[:2, 1] + if np.any(delta < lo - 1e-5) or np.any(delta > hi + 1e-5): + return None + return tuple( + min(3, max(0, int(np.floor(4 * (v - a) / (b - a))))) if b > a else 0 + for v, a, b in zip(delta, lo, hi) + ) + + +def _confirmed_episodes(root): + """Read only receipt-confirmed evidence; a staged NPZ is not a commit.""" + from embodichain.lab.expansion.persistence import ( + ArtifactEpisodeSink, + load_expansion_episode, + ) + + if not root.exists(): + return () + return tuple( + load_expansion_episode(receipt.storage_id) + for receipt in ArtifactEpisodeSink(root).inspect() + if receipt.confirmed + ) + + +def _task_pose_cells(episode, case, cfg, nominal): + """Count each manipulated object on frozen initial and placement domains.""" + cells = set() + for uid, (goal, offset) in PLACEMENTS[case].items(): + values = episode.observations[f"rigid/{uid}/state"].cpu().numpy() + initial_uid = cfg["scene"][uid].get("follow", uid) + initial = _xy_cell( + values[0], nominal[uid], cfg["scene"][initial_uid]["translation_m"] + ) + if initial is not None: + cells.add((uid, "initial", *initial)) + bounds = cfg["scene"].get(goal, {}).get("translation_m", [[0, 0]] * 3) + if all(pair[0] == pair[1] for pair in bounds[:2]): + # A fixed target contributes one category after measured acceptance; + # tracking error inside its tolerance cannot create pose diversity. + cells.add((uid, "placed-fixed")) + else: + origin = np.asarray(nominal[goal], dtype=float).copy() + origin[:2] += offset + placed = _xy_cell(values[-1], origin, bounds) + if placed is not None: + cells.add((uid, "placed", *placed)) + return cells + + +def _strategy_order(strategies: list[str], seed_index: int) -> list[str]: + """Balance position and preceding strategy over four seeds in the full comparison.""" + width = len(strategies) + order = [0, *(i // 2 + 1 if i % 2 else width - i // 2 for i in range(1, width))] + return [strategies[(index + seed_index) % width] for index in order] + + +def _source_breakdown(events, checks): + """Attribute screened and executed outcomes to the actual raw source.""" + origins = defaultdict(Counter) + selections = {} + rejected = Counter() + for e in events: + if e["event"] == "proposal": + source = origins[e["origin"]] + source["proposed"] += 1 + source["screened"] += int(e["screened"]) + if not e["screened"]: + rejected[e["reason"]] += 1 + elif e["origin"] == "robot_first": + anchor = checks["workspace_anchor_checks"][str(e["raw_ordinal"])] + actual = e["pose_changes"][anchor["root_uid"]] + if not np.allclose(actual, anchor["pose"], atol=1e-9, rtol=0): + raise ValueError( + "Conditioned layout did not preserve the workspace anchor" + ) + elif e["event"] == "selection": + selections[e["ordinal"]] = e["origin"] + elif e["event"] == "outcome": + source = origins[selections[e["ordinal"]]] + for key in ("executed", "physical_accepted", "committed"): + source[key] += int(e[key]) + return {k: dict(v) for k, v in origins.items()}, dict(rejected) + + +def worker(args): + """Execute one isolated source/case/seed with complete failure denominators.""" + sys.path[:0] = [ + str(ROOT), + str(ROOT / "extensions/embodichain_tasks"), + str(ROOT / "extensions/embodichain_robots"), + ] + from embodichain.lab.expansion.task_program_jobs import run_task_program_expansion + + directory = args.output + directory.mkdir(parents=True, exist_ok=False) + cfg = yaml.safe_load((CASES[args.case] / "expansion.yaml").read_text()) + cfg["scene_sampling"]["strategy"] = args.strategy + cfg["engine"].update( + episodes_per_operator=args.rollouts, + max_attempts=args.candidates, + max_wall_time_s=args.seconds, + ) + cfg["scene_sampling"].update( + max_candidates=args.candidates, max_rollouts=args.rollouts + ) + # One raw draw per attempt across all four variants. The screening budgets + # and measured acceptance remain those declared by the fixture. + cfg["scheduling"]["pool_size"] = 1 + if args.pilot: + for value in cfg["scene"].values(): + if "follow" not in value: + value["translation_m"] = [[0, 0]] * 3 + for key in cfg["scene_sampling"]["layout"]["policy"][ + "group_xy_offset_bounds_m" + ]: + cfg["scene_sampling"]["layout"]["policy"]["group_xy_offset_bounds_m"][ + key + ] = [[0, 0], [0, 0]] + config = directory / "expansion.yaml" + config.write_text(yaml.safe_dump(cfg, sort_keys=False)) + files = subprocess.check_output( + ["git", "ls-files", "--cached", "--others", "--exclude-standard"], + cwd=ROOT, + text=True, + ).splitlines() + paths = [ + p + for p in files + if p.startswith( + ( + "embodichain/lab/expansion/", + "embodichain/lab/sim/scene/", + "embodichain/compute/geometry/", + "extensions/embodichain_tasks/configs/tasks/manipulation/", + ) + ) + and (ROOT / p).is_file() + ] + paths.append(str(Path(__file__).resolve().relative_to(ROOT))) + _write( + directory / "source-manifest.json", + {p: hashlib.sha256((ROOT / p).read_bytes()).hexdigest() for p in paths}, + ) + started = time.perf_counter() + result = None + error = None + try: + result = run_task_program_expansion( + CASES[args.case] / "task.yaml", + config, + directory / "collection", + seed=args.seed, + ) + except Exception as exc: + error = f"{type(exc).__name__}: {exc}" + import traceback + + traceback.print_exc() + run_wall_s = time.perf_counter() - started + root = directory / "collection/dataset/object_pose" + source = root / "pose-sampling.json" + data = json.loads(source.read_text()) if source.exists() else {} + events = data.get("events", []) + outcomes = [e for e in events if e["event"] == "outcome"] + screen_path = root / "scene-first-checks.json" + screens = json.loads(screen_path.read_text()) if screen_path.exists() else {} + origins, proposal_rejections = _source_breakdown(events, screens) + failures = {} + for path in root.glob("attempts/*/attempt.json"): + d = json.loads(path.read_text()) + if d.get("status") != "committed": + key = d.get("reason", d.get("status", "unavailable")) + failures[key] = failures.get(key, 0) + 1 + nominal_path = directory / "collection/reference-scene.json" + nominal = ( + json.loads(nominal_path.read_text())["poses_xyzw"] + if nominal_path.exists() + else {} + ) + independent = [uid for uid, opts in cfg["scene"].items() if "follow" not in opts] + joint = set() + marginal = set() + task = set() + audits = [] + committed = 0 + for episode in _confirmed_episodes(root): + committed += 1 + row = [] + for uid in independent: + states = episode.observations[f"rigid/{uid}/state"] + cell = _xy_cell( + states[0].cpu().numpy(), + nominal[uid], + cfg["scene"][uid]["translation_m"], + ) + if cell is not None: + marginal.add((uid, *cell)) + row.append((uid, cell)) + if all(cell is not None for _, cell in row): + joint.add(tuple((uid, *cell) for uid, cell in row)) + task.update(_task_pose_cells(episode, args.case, cfg, nominal)) + steps = len(episode.actions) + if ( + not episode.validation.accepted + or len(episode.timestamps) != steps + 1 + or any(len(v) != steps + 1 for v in episode.observations.values()) + or episode.metadata["source_env_id"] != 0 + ): + raise ValueError("Invalid measured episode evidence at confirmed readback") + arm_motion = {} + if args.case == "dual_arm_sort": + q = episode.observations["full_joint_positions"].cpu().numpy() + names = episode.metadata["joint_names"] + for arm in ("left", "right"): + columns = [ + i for i, name in enumerate(names) if name.startswith(f"{arm}_joint") + ] + arm_motion[arm] = float(np.ptp(q[:, columns], axis=0).max()) + if min(arm_motion.values()) <= 0.1: + raise ValueError( + "Dual-arm sorting requires measured motion in both arms" + ) + audits.append( + { + "episode_id": episode.episode_id, + "T": len(episode.actions), + "observations": len(episode.timestamps), + "source_row": episode.metadata["source_env_id"], + "validation": episode.validation.accepted, + "arm_joint_range_rad": arm_motion, + } + ) + slots_per_uid = { + uid: int( + np.prod( + [ + 4 if pair[1] > pair[0] else 1 + for pair in cfg["scene"][uid]["translation_m"][:2] + ] + ) + ) + for uid in independent + } + metric = { + "case": args.case, + "strategy": args.strategy, + "seed": args.seed, + "pilot": args.pilot, + "budget": data.get("budget", {}), + "declared_budget": { + "candidates": args.candidates, + "rollouts": args.rollouts, + "seconds": args.seconds, + }, + "cpu_affinity": sorted(os.sched_getaffinity(0)), + "cuda_visible_devices": os.environ.get("CUDA_VISIBLE_DEVICES"), + "execution": ( + json.loads((directory / "collection/execution.json").read_text()) + if (directory / "collection/execution.json").exists() + else None + ), + "error": error, + "wall_s": run_wall_s, + "peak_rss_mib": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024, + "executed": sum(bool(e["executed"]) for e in outcomes), + "physically_accepted": sum(bool(e["physical_accepted"]) for e in outcomes), + "committed": committed, + "scene_joint_cells": len(joint), + "scene_joint_declared_cells": int(np.prod(list(slots_per_uid.values()))), + "scene_marginal_cells": len(marginal), + "scene_marginal_declared_cells": sum(slots_per_uid.values()), + "task_pose_cells": len(task), + "coverage_cells": { + "scene_joint": sorted(joint), + "scene_marginal": sorted(marginal), + "task": sorted(task), + }, + "preparation_rejected": sum(not e["executed"] for e in outcomes), + "proposal_rejections": proposal_rejections, + "origins": origins, + "workspace_prior": screens.get("workspace_prior", []), + "workspace_prepare_wall_s": screens.get("workspace_prepare_wall_s"), + "proposal_screen_wall_s": screens.get("proposal_screen_wall_s"), + "failures": failures, + "episode_audit": audits, + "versions": { + name: importlib.metadata.version(name) + for name in ["torch", "dexsim-engine"] + }, + "result": result, + } + _write(directory / "metrics.json", metric) + print(json.dumps(metric), flush=True) + if error: + raise SystemExit(1) + + +def _aggregate(rows): + """Combine unique receipt-confirmed coverage across seeds in a fixed domain.""" + groups = defaultdict(list) + for row in rows: + groups[row["case"], row["strategy"]].append(row) + result = [] + for (case, strategy), runs in sorted(groups.items()): + origins = defaultdict(Counter) + for run in runs: + for origin, values in run.get("origins", {}).items(): + origins[origin].update(values) + coverage = {} + for kind in ("scene_joint", "scene_marginal", "task"): + if all("coverage_cells" in run for run in runs): + coverage[kind] = len( + { + json.dumps(cell) + for run in runs + for cell in run["coverage_cells"][kind] + } + ) + else: + coverage[kind] = None + totals = { + k: sum(run[k] for run in runs) + for k in ( + "executed", + "physically_accepted", + "committed", + "preparation_rejected", + ) + } + proposed = [run["budget"].get("candidates") for run in runs] + result.append( + dict( + case=case, + strategy=strategy, + seeds=[r["seed"] for r in runs], + raw_proposals=( + None if any(v is None for v in proposed) else sum(proposed) + ), + median_wall_s=median(run["wall_s"] for run in runs), + total_wall_s=sum(run["wall_s"] for run in runs), + median_screen_s=median( + [ + run["proposal_screen_wall_s"] + for run in runs + if run.get("proposal_screen_wall_s") is not None + ] + or [0.0] + ), + peak_rss_mib=max(run["peak_rss_mib"] for run in runs), + scene_joint_declared=max( + run["scene_joint_declared_cells"] for run in runs + ), + scene_marginal_declared=max( + run["scene_marginal_declared_cells"] for run in runs + ), + coverage=coverage, + origins={key: dict(val) for key, val in origins.items()}, + failed_runs=[ + f'{run["seed"]}: {run["error"]}' for run in runs if run["error"] + ], + **totals, + ) + ) + return result + + +def report(output, rows): + """Write aggregated comparisons and preserve seed-level results separately.""" + aggregate = _aggregate(rows) + _write(output / "results.json", rows) + _write(output / "aggregate.json", aggregate) + lines = [ + "# Conditional layout sampling across three tasks", + "", + "Default CPU physics, B=1, sensors disabled. Each strategy uses the same", + "task domains, layout and path checks, runtime replanning, physical", + "acceptance and artifact/LeRobot export. CUDA grasp classification may be", + "used. Cold wall time covers the expansion call, including initialization", + "and export, excluding process startup and benchmark readback. RSS is the", + "process high-water mark; incremental CPU/GPU allocations are unmeasured.", + "", + "## Time & Memory", + "", + "|Task|Strategy|Seeds|Median cost_time_ms|Median screen s|Wall s / receipt|Peak RSS MiB|cpu_delta_mb|gpu_delta_mb|peak_gpu_mb|", + "|---|---|---:|---:|---:|---:|---:|---|---|---|", + ] + for r in aggregate: + per_episode = ( + f'{r["total_wall_s"]/r["committed"]:.2f}' if r["committed"] else "N/A" + ) + lines.append( + f"|{r['case']}|{r['strategy']}|{len(r['seeds'])}|{r['median_wall_s']*1000:.1f}|" + f"{r['median_screen_s']:.2f}|{per_episode}|{r['peak_rss_mib']:.1f}|N/A|N/A|N/A|" + ) + lines += [ + "", + "## Success & Other Metrics", + "", + "|Task|Strategy|Raw proposals|Prep rejected|Accepted / executed|Committed|Marginal XY cells|Joint XY cells|Task pose cells|Failed runs|", + "|---|---|---:|---:|---:|---:|---:|---:|---:|---:|", + ] + for r in aggregate: + coverage = r["coverage"] + number = lambda x: "N/A" if x is None else str(x) + lines.append( + f"|{r['case']}|{r['strategy']}|{number(r['raw_proposals'])}|{r['preparation_rejected']}|" + f"{r['physically_accepted']}/{r['executed']}|{r['committed']}|" + f"{number(coverage['scene_marginal'])}/{r['scene_marginal_declared']}|" + f"{number(coverage['scene_joint'])}/{r['scene_joint_declared']}|" + f"{number(coverage['task'])}|{len(r['failed_runs'])}|" + ) + lines += [ + "", + "## Leaderboard", + "", + "Order within each task by physical acceptance per executed rollout.", + "", + "|Task|Strategy|Physical acceptance|Confirmed episodes|", + "|---|---|---:|---:|", + ] + for r in sorted( + aggregate, + key=lambda r: ( + r["case"], + -r["physically_accepted"] / r["executed"] if r["executed"] else 1.0, + ), + ): + rate = ( + f"{r['physically_accepted']/r['executed']:.3f}" + if r["executed"] + else "N/A (no rollout)" + ) + lines.append(f"|{r['case']}|{r['strategy']}|{rate}|{r['committed']}|") + lines += [ + "", + "Scene coverage is the union of fixed XY grid cells from receipt-confirmed", + "measured initial layouts. Task cells use measured initial/terminal object", + "positions; each fixed placement is a single category. The counted cells", + "describe observed sample diversity in the fixture domains.", + "See results.json for each seed, proposal failures, source usage, recorded", + "budgets, hardware affinity, and readback audit. Aggregated wall times", + "include all recorded runs, including errors.", + ] + (output / "report.md").write_text("\n".join(lines) + "\n") + + +def main(): + """Run fresh worker processes sequentially, alternating source order by seed.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--worker", action="store_true") + parser.add_argument("--pilot", action="store_true") + parser.add_argument("--rebuild", action="store_true") + parser.add_argument("--cases", default=",".join(CASES)) + parser.add_argument("--strategies", default=",".join(STRATEGIES)) + parser.add_argument("--case", choices=tuple(CASES), default="pick_place") + parser.add_argument("--strategy", choices=STRATEGIES, default="scene_first") + parser.add_argument("--seeds", default="7,17") + parser.add_argument("--seed", type=int, default=7) + parser.add_argument("--rollouts", type=int, default=4) + parser.add_argument("--candidates", type=int, default=64) + parser.add_argument("--seconds", type=float, default=600) + args = parser.parse_args() + args.output = args.output.resolve() + if args.worker: + worker(args) + return + if args.rebuild: + report( + args.output, + [ + json.loads(p.read_text()) + for p in sorted(args.output.rglob("metrics.json")) + ], + ) + return + cases = args.cases.split(",") + strategies = args.strategies.split(",") + if any(case not in CASES for case in cases) or len(set(cases)) != len(cases): + parser.error("Select distinct task cases from " + ",".join(CASES)) + if any(s not in STRATEGIES for s in strategies) or len(set(strategies)) != len( + strategies + ): + parser.error("Select distinct strategies from " + ",".join(STRATEGIES)) + args.output.mkdir(parents=True, exist_ok=False) + rows = [] + for case in cases: + for index, seed in enumerate(map(int, args.seeds.split(","))): + for strategy in _strategy_order(strategies, index): + directory = args.output / f"{case}-{strategy}-{seed}" + command = [ + sys.executable, + str(Path(__file__).resolve()), + "--worker", + "--output", + str(directory), + "--case", + case, + "--strategy", + strategy, + "--seed", + str(seed), + "--rollouts", + str(args.rollouts), + "--candidates", + str(args.candidates), + "--seconds", + str(args.seconds), + ] + if args.pilot: + command += ["--pilot"] + attempt_started = time.perf_counter() + env = { + **os.environ, + "OMP_NUM_THREADS": "1", + "MKL_NUM_THREADS": "1", + "SDL_VIDEODRIVER": "offscreen", + } + with (args.output / (directory.name + ".log")).open("w") as log: + try: + proc = subprocess.run( + command, + cwd=ROOT, + env=env, + stdout=log, + stderr=subprocess.STDOUT, + timeout=args.seconds + 180, + ) + worker_error = f"Worker exited with status {proc.returncode}" + except subprocess.TimeoutExpired: + worker_error = "Worker exceeded the hard process timeout" + metrics = directory / "metrics.json" + if not metrics.exists(): + directory.mkdir(exist_ok=True) + _write( + metrics, + { + "case": case, + "strategy": strategy, + "seed": seed, + "budget": {}, + "declared_budget": { + "candidates": args.candidates, + "rollouts": args.rollouts, + "seconds": args.seconds, + }, + "error": worker_error, + "wall_s": time.perf_counter() - attempt_started, + "peak_rss_mib": 0, + "executed": 0, + "physically_accepted": 0, + "committed": 0, + "scene_joint_declared_cells": 0, + "scene_marginal_declared_cells": 0, + "preparation_rejected": 0, + }, + ) + row = json.loads(metrics.read_text()) + rows.append(row) + report(args.output, rows) + if row["error"]: + print( + f"Worker failed: {directory}; diagnostics retained", flush=True + ) + print(args.output / "report.md", flush=True) + + +if __name__ == "__main__": + main() diff --git a/tests/benchmark/expansion/test_scene_first_report.py b/tests/benchmark/expansion/test_scene_first_report.py new file mode 100644 index 0000000000..5bf5e69be2 --- /dev/null +++ b/tests/benchmark/expansion/test_scene_first_report.py @@ -0,0 +1,161 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Receipt and frozen-domain semantics for cross-task scene acceptance reports.""" + +from __future__ import annotations +from types import SimpleNamespace +import numpy as np +import torch +from scripts.benchmark.expansion.scene_first import ( + STRATEGIES, + _aggregate, + _confirmed_episodes, + _strategy_order, + _task_pose_cells, + _xy_cell, +) + + +def test_each_strategy_runs_once_at_each_position_and_after_each_peer(): + strategies = list(STRATEGIES) + orders = [_strategy_order(strategies, i) for i in range(4)] + assert all(set(column) == set(strategies) for column in zip(*orders)) + assert len({pair for order in orders for pair in zip(order, order[1:])}) == 12 + + +def test_cross_seed_coverage_counts_each_measured_cell_once(): + run = dict( + case="stack", + strategy="bidirectional", + executed=2, + physically_accepted=2, + committed=2, + preparation_rejected=1, + budget={"candidates": 3}, + wall_s=30.0, + peak_rss_mib=2000, + scene_joint_declared_cells=256, + scene_marginal_declared_cells=32, + error=None, + ) + shared = ["a", 0, 0] + rows = [ + dict( + run, + seed=seed, + coverage_cells={ + "scene_joint": [[shared, ["b", seed, 0]]], + "scene_marginal": [shared, ["b", seed, 0]], + "task": [["a", "initial", 0, 0], ["a", "placed", seed, 0]], + }, + ) + for seed in (1, 2) + ] + (result,) = _aggregate(rows) + assert result["coverage"] == {"scene_joint": 2, "scene_marginal": 3, "task": 3} + assert (result["committed"], result["raw_proposals"]) == (4, 6) + + +def test_staged_numerical_file_without_receipt_has_no_coverage_credit(tmp_path): + folder = tmp_path / "episodes" / "staged" + folder.mkdir(parents=True) + (folder / "episode.npz").write_bytes(b"not committed") + assert _confirmed_episodes(tmp_path) == () + + +def test_confirmed_readback_uses_verified_receipt_storage(monkeypatch, tmp_path): + from unittest.mock import Mock + import embodichain.lab.expansion.persistence as persistence + + episode = object() + load = Mock(return_value=episode) + monkeypatch.setattr(persistence, "load_expansion_episode", load) + monkeypatch.setattr( + persistence.ArtifactEpisodeSink, + "inspect", + lambda self: ( + SimpleNamespace(confirmed=True, storage_id="confirmed.npz"), + SimpleNamespace(confirmed=False, storage_id="pending.npz"), + ), + ) + assert _confirmed_episodes(tmp_path) == (episode,) + load.assert_called_once_with("confirmed.npz") + + +def test_xy_bins_are_fixed_and_reject_outside_domain(): + bounds = [[-0.1, 0.1], [-0.1, 0.1], [0, 0]] + assert _xy_cell([-0.1, -0.1, 0], [0, 0, 0], bounds) == (0, 0) + assert _xy_cell([0.1, 0.1, 0], [0, 0, 0], bounds) == (3, 3) + assert _xy_cell([0.11, 0, 0], [0, 0, 0], bounds) is None + assert _xy_cell([0, 0, 0], [0, 0, 0], [[0, 0], [0, 0], [0, 0]]) == (0, 0) + + +def test_both_arms_count_but_fixed_goal_tracking_noise_adds_no_diversity(): + nominal = { + "block_1": [0.625, -0.15, 0.86], + "block_2": [0.675, 0, 0.86], + "block_3": [0.725, 0.15, 0.86], + } + cfg = { + "scene": { + uid: {"translation_m": [[-0.025, 0.025], [-0.03, 0.03], [0, 0]]} + for uid in ("block_1", "block_3") + } + } + episode = SimpleNamespace( + observations={ + "rigid/block_1/state": torch.tensor( + [[0.62, -0.155, 0.86], [0.59, -0.005, 0.86]] + ), + "rigid/block_3/state": torch.tensor( + [[0.72, 0.145, 0.86], [0.76, 0.005, 0.86]] + ), + } + ) + cells = _task_pose_cells(episode, "dual_arm_sort", cfg, nominal) + assert cells == { + ("block_1", "initial", 1, 1), + ("block_3", "initial", 1, 1), + ("block_1", "placed-fixed"), + ("block_3", "placed-fixed"), + } + for value in episode.observations.values(): + value[-1, :2] += 0.01 + assert _task_pose_cells(episode, "dual_arm_sort", cfg, nominal) == cells + + +def test_relative_placement_offsets_use_the_reference_sampling_domain(): + nominal = { + "block_1": [0.625, -0.15, 0.86], + "block_2": [0.675, 0, 0.86], + "block_3": [0.725, 0.15, 0.86], + } + bounds = [[-0.025, 0.025], [-0.03, 0.03], [0, 0]] + cfg = {"scene": {uid: {"translation_m": bounds} for uid in nominal}} + episode = SimpleNamespace( + observations={ + "rigid/block_1/state": torch.tensor( + [nominal["block_1"], [0.575, -0.02, 0.86]] + ), + "rigid/block_3/state": torch.tensor( + [nominal["block_3"], [0.775, 0.02, 0.86]] + ), + } + ) + cells = _task_pose_cells(episode, "dual_arm_sort", cfg, nominal) + assert ("block_1", "placed", 0, 0) in cells + assert ("block_3", "placed", 3, 3) in cells diff --git a/tests/lab/expansion/test_scene_first_sampling.py b/tests/lab/expansion/test_scene_first_sampling.py new file mode 100644 index 0000000000..6564b3eb9d --- /dev/null +++ b/tests/lab/expansion/test_scene_first_sampling.py @@ -0,0 +1,428 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""All layout sources share conservative screening and own selected poses.""" + +from __future__ import annotations +from types import SimpleNamespace +from copy import deepcopy +import json +import numpy as np +import pytest +import torch + +from scene_layout_support import make_source +from embodichain.lab.expansion._scene_first_sampling import _LayoutPoseSource +from embodichain.lab.expansion._pose_sampling_cfg import validate_sampling +from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted + + +def setup_source( + monkeypatch, + strategy="scene_first", + accepted=True, + member_yaw=False, + workspace=None, + bounded_fixed_root=False, +): + import embodichain.lab.expansion._scene_first_sampling as module + + source = make_source() + + class Object: + def __init__(self, uid): + self.uid = uid + self.cfg = SimpleNamespace(to_dict=lambda: {"uid": uid}) + + def get_local_pose(self, to_matrix=True): + return torch.tensor(np.array(source.poses[self.uid]))[None] + + objects = {uid: Object(uid) for uid in source.poses} + robot = SimpleNamespace( + uid="robot", + device=torch.device("cpu"), + control_parts={"custom_arm": [0]}, + cfg=SimpleNamespace(to_dict=lambda: {"uid": "robot"}), + get_local_pose=lambda to_matrix=True: torch.eye(4)[None], + get_solver=lambda name: object(), + get_qpos_limits=lambda name: torch.tensor([[[0.0, 1.0]]]), + compute_batch_fk=lambda **kw: workspace[None], + ) + env = SimpleNamespace( + num_envs=1, + robot=robot, + sim=SimpleNamespace( + num_envs=1, + get_rigid_object_uid_list=lambda: tuple(objects), + get_rigid_object=objects.get, + sim_config=SimpleNamespace( + physics_cfg=SimpleNamespace(to_dict=lambda: {"backend": "default"}) + ), + ), + ) + checked = [] + closed = [] + monkeypatch.setattr(module, "scene_layout_input_from_sim", lambda *a, **kw: source) + monkeypatch.setattr( + "embodichain.lab.task_program.integrations.simulation.feasibility_geometry.collision_bodies_from_simulation", + lambda env: (), + ) + monkeypatch.setattr( + "embodichain.lab.expansion.acceptance._GeometryRow.contact_permissions", + lambda *a: ((), ()), + ) + monkeypatch.setattr( + "embodichain.lab.sim.scene.feasibility.NewtonCollisionChecker", + lambda *a, **kw: SimpleNamespace(close=lambda: closed.append(True)), + ) + monkeypatch.setattr( + "embodichain.lab.sim.scene.feasibility.RobotFeasibilityBackend", + lambda *a, **kw: None, + ) + + def screen(mode, backend, poses, budget): + checked.append(deepcopy(poses)) + return SimpleNamespace( + accepted=accepted, + checks=( + SimpleNamespace( + stage="motion", + status="passed" if accepted else "failed", + reason="checked task path", + phase_id="reach", + ), + ), + ) + + monkeypatch.setattr("embodichain.lab.sim.scene.feasibility.plan_task_mode", screen) + opts = { + "engine": { + "max_attempts": 8, + "max_wall_time_s": 120.0, + "episodes_per_operator": 1, + }, + "scene": { + "tray": { + "translation_m": [[-0.1, 0.1], [-0.1, 0.1], [0, 0]], + "yaw_rad": [0, 0], + }, + "mug": {"follow": "tray"}, + }, + "validation": {}, + "scene_sampling": { + "strategy": strategy, + "control_part": "custom_arm", + "max_candidates": 64, + "max_rollouts": 8, + "layout": { + "support_uid": "workbench", + "parent_by_uid": dict(source.parent_by_uid), + "policy": { + "group_targets": ["tray"], + "group_xy_offset_bounds_m": {"tray": [[-0.1, -0.1], [0.1, 0.1]]}, + }, + "conditions": {"tray": np.array(source.poses["tray"]).tolist()}, + }, + "task_mode": { + "mode_id": "runtime", + "phases": [ + { + "phase_id": "reach", + "targets": [ + { + "control_part": "custom_arm", + "frame_uid": "mug", + "pose": np.eye(4).tolist(), + } + ], + } + ], + }, + }, + "scheduling": {"policy": "fifo", "pool_size": 4}, + } + if strategy in ("robot_first", "bidirectional"): + sampling = opts["scene_sampling"] + sampling["sample_count"] = len(workspace) + sampling["robot_anchors"] = [ + {"phase_id": "reach", "control_part": "custom_arm"} + ] + sampling["layout"]["conditions"] = { + "workbench": source.poses["workbench"], + } + sampling["task_mode"]["phases"][0]["targets"][0]["pose"][0][3] = 0.04 + opts["scene"]["z_target"] = { + "translation_m": [[-0.1, 0.1], [-0.1, 0.1], [0, 0]], + "yaw_rad": [0, 0], + } + sampling["layout"]["policy"]["group_targets"].append("z_target") + sampling["layout"]["policy"]["group_xy_offset_bounds_m"]["z_target"] = [ + [-0.1, -0.1], + [0.1, 0.1], + ] + if bounded_fixed_root: + opts["scene_sampling"]["layout"]["conditions"] = {} + opts["scene"]["z_target"] = { + "translation_m": [[-0.1, 0.1], [-0.1, 0.1], [0, 0]], + "yaw_rad": [0, 0], + } + if member_yaw: + opts["scene"]["mug"] = { + "translation_m": [[-0.15, 0.15], [-0.15, 0.15], [0, 0]], + "yaw_rad": [0, 0], + } + opts["scene_sampling"]["layout"]["policy"]["intra_group"] = { + "targets": {"mug": {"yaw_delta_range_deg": [30, 30]}} + } + validate_sampling(opts) + return ( + _LayoutPoseSource(env, opts, seed=7, revision="test-source"), + checked, + closed, + ) + + +def test_scene_first_anchors_and_workspace_task_checks_are_owned_and_cached( + monkeypatch, tmp_path +): + source, checked, closed = setup_source(monkeypatch) + source.output = tmp_path + candidate = source.candidate(0) + assert source.validate(0).accepted and len(checked) == 1 + poses = {c.entity_uid: np.array(c.arena_pose) for c in candidate.scene.pose_changes} + np.testing.assert_allclose(poses["tray"], source._conditions.poses["tray"]) + np.testing.assert_allclose(poses["mug"], checked[0]["mug"]) + checked[0]["mug"][0, 3] = 99 + assert candidate is source.candidate(0) + assert source.budget.counts["candidates"] == 1 + assert ( + json.loads((tmp_path / "scene-first-checks.json").read_text())["phase_checks"][ + "0" + ][0]["stage"] + == "motion" + ) + source.close() + source.close() + assert closed == [True] + + +@pytest.mark.parametrize("strategy", ["scene_first", "robot_first", "bidirectional"]) +def test_failed_task_screening_never_becomes_a_successful_fallback( + monkeypatch, strategy +): + source, checked, _ = setup_source( + monkeypatch, strategy=strategy, accepted=False, workspace=_workspace() + ) + source.candidate(0) + assert not source.validate(0).accepted and len(checked) == 4 + assert all(not e["screened"] for e in source._events if e["event"] == "proposal") + + +def _workspace() -> torch.Tensor: + # Tool XY is +4 cm along the support group's X. The first three TCP samples + # share one cell, the fourth is in a different cell, and the last is illegal. + poses = torch.eye(4, dtype=torch.float64).repeat(5, 1, 1) + poses[:, :2, 3] = torch.tensor( + [[-0.309, -0.04], [-0.310, -0.04], [-0.311, -0.04], [-0.19, 0.05], [0.9, 0.0]], + dtype=poses.dtype, + ) + # Keep authored root height and orientation despite the projected FK pose. + poses[:, 2, 3] = 0.7 + poses[:, 1, 1] = poses[:, 2, 2] = -1 + return poses + + +def test_robot_first_balances_prior_cells_and_completes_other_groups(monkeypatch): + workspace = _workspace() + source, checked, _ = setup_source(monkeypatch, "robot_first", workspace=workspace) + workspace.fill_(77) + first = source.candidate(0) + second = source.candidate(1) + assert source.validate(0).accepted and source.validate(1).accepted + assert source.candidate(0) is first + x_coords, other_poses = [], [] + for index, candidate in enumerate((first, second)): + poses = { + c.entity_uid: np.array(c.arena_pose) for c in candidate.scene.pose_changes + } + x_coords.append(poses["tray"][0, 3]) + other_poses.append(poses["z_target"]) + np.testing.assert_allclose(poses["tray"][:3, :3], np.eye(3)) + assert poses["tray"][2, 3] == pytest.approx(0.061) + np.testing.assert_allclose(poses["mug"][:2, 3], poses["tray"][:2, 3]) + np.testing.assert_allclose(checked[index]["tray"], poses["tray"]) + assert min(x_coords) == pytest.approx(-0.35, abs=0.0011) + assert max(x_coords) == pytest.approx(-0.23) + assert not np.allclose(*other_poses) + + +@pytest.mark.parametrize("strategy", ["robot_first", "bidirectional"]) +def test_empty_workspace_draw_costs_a_candidate_and_never_runs_task_screen( + monkeypatch, strategy +): + workspace = _workspace() + workspace[:, 0, 3] = 99 + source, checked, _ = setup_source(monkeypatch, strategy, workspace=workspace) + source.candidate(0) + proposals = [e for e in source._events if e["event"] == "proposal"] + assert not proposals[0]["screened"] + assert proposals[0]["reason"] == "no_workspace_anchor" + if strategy == "robot_first": + assert not source.validate(0).accepted and checked == [] + else: + assert source.validate(0).accepted and len(checked) == 1 + assert [p["origin"] for p in proposals] == ["robot_first", "scene_first"] + assert source._events[-1]["raw_ordinal"] == 1 + assert source.budget.counts["candidates"] == len(proposals) + + +def test_mixed_draws_keep_direction_and_layout_after_checkpoint_restore(monkeypatch): + source, _, _ = setup_source(monkeypatch, "bidirectional", workspace=_workspace()) + first = source.candidate(0) + restored, _, _ = setup_source(monkeypatch, "bidirectional", workspace=_workspace()) + restored.load_state_dict(source.state_dict()) + assert restored.candidate(0) == first + assert restored.candidate(1) == source.candidate(1) + proposals = [e for e in restored._events if e["event"] == "proposal"] + assert [(e["raw_ordinal"], e["origin"]) for e in proposals] == [ + (0, "robot_first"), + (1, "scene_first"), + ] + + +def test_simple_baseline_keeps_identical_task_screening_and_conditions(monkeypatch): + source, checked, _ = setup_source(monkeypatch, strategy="bounded_pose") + # Its simple random draw does not satisfy the exact anchor, and must be + # rejected before any workspace/path computation. + source.candidate(0) + assert not source.validate(0).accepted and checked == [] + assert any(e.get("reason") == "condition_mismatch" for e in source._events) + + +def test_source_obeys_hard_raw_candidate_budget(monkeypatch): + source, checked, _ = setup_source(monkeypatch) + source.budget.charge("candidates", source.cfg["max_candidates"]) + source.candidate(0) + assert not source.validate(0).accepted and checked == [] + assert source.budget.counts["candidates"] == 64 + + +def test_scene_first_config_rejects_batch_and_unknown_phase_fields_before_runtime(): + # Reuse a valid source's owned config, without constructing a new World. + import yaml + from pathlib import Path + + root = Path(__file__).resolve().parents[3] + path = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml" + ) + cfg = yaml.safe_load(path.read_text()) + cfg["engine"]["batch_size"] = 4 + with pytest.raises(ValueError, match="B=1"): + validate_sampling(cfg) + cfg["engine"]["batch_size"] = 1 + cfg["scene_sampling"]["task_mode"]["phases"][0]["unknown"] = True + with pytest.raises(ValueError, match="Unknown TaskPhase"): + validate_sampling(cfg) + + +@pytest.mark.parametrize( + "invalid, error", + [ + ("unknown_stage", "declared phase targets"), + ("moved_frame", "initial frame"), + ("pinned_root", "authored root condition"), + ], +) +def test_robot_anchors_reject_invalid_frame_provenance(invalid, error): + import yaml + from pathlib import Path + + root = Path(__file__).resolve().parents[3] + path = root / ( + "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/" + "acceptance/scene_first/expansion.yaml" + ) + cfg = yaml.safe_load(path.read_text()) + sampling = cfg["scene_sampling"] + sampling["strategy"] = "robot_first" + if invalid == "unknown_stage": + sampling["robot_anchors"][0]["phase_id"] = "unknown" + elif invalid == "moved_frame": + sampling["task_mode"]["phases"][0]["held_objects"] = [ + {"entity_uid": "cube", "control_part": "arm"} + ] + else: + sampling["layout"]["conditions"] = {"cube": np.eye(4).tolist()} + with pytest.raises(ValueError, match=error): + validate_sampling(cfg) + + +def test_source_rejects_stale_geometry_and_does_not_refresh_silently(monkeypatch): + source, checked, _ = setup_source(monkeypatch) + source.env.sim.spawn_result = SimpleNamespace(topology_revision=2) + source._scene_identity = (id(source.env.sim.spawn_result), 1) + with pytest.raises(RuntimeError, match="stale"): + source.candidate(0) + assert checked == [] + + +def test_fixed_layout_geometry_cannot_be_moved_by_a_bounded_draw(monkeypatch): + source, checked, _ = setup_source( + monkeypatch, strategy="bounded_pose", bounded_fixed_root=True + ) + source.candidate(0) + assert not source.validate(0).accepted and not checked + assert source._events[0]["reason"] == "layout_moves_fixed_entity" + + +def test_member_layout_yaw_cannot_expand_the_task_domain(monkeypatch): + source, checked, _ = setup_source(monkeypatch, member_yaw=True) + source.candidate(0) + assert not source.validate(0).accepted and checked == [] + reasons = [e["reason"] for e in source._events if e["event"] == "proposal"] + assert reasons and set(reasons) == {"layout_outside_task_domain"} + + +def test_screening_must_not_step_the_owning_world(monkeypatch): + source, _, _ = setup_source(monkeypatch) + source.env.sim.physics_step_index = 0 + + def bad_query(*args): + source.env.sim.physics_step_index += 1 + return SimpleNamespace(accepted=True, checks=()) + + monkeypatch.setattr( + "embodichain.lab.sim.scene.feasibility.plan_task_mode", bad_query + ) + with pytest.raises(RuntimeError, match="advanced"): + source.candidate(0) + + +def test_legacy_workspace_strategy_cannot_silently_ignore_new_layout(): + import yaml + from pathlib import Path + + path = ( + Path(__file__).resolve().parents[3] + / "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml" + ) + value = yaml.safe_load(path.read_text()) + value["scene_sampling"]["strategy"] = "workspace_joint" + value["scene_sampling"]["targets"] = {"cube": np.eye(4).tolist()} + with pytest.raises(ValueError, match="does not consume layout"): + validate_sampling(value) diff --git a/tests/sim/scene/expansion/test_conditions.py b/tests/sim/scene/expansion/test_conditions.py new file mode 100644 index 0000000000..2496b2bb2a --- /dev/null +++ b/tests/sim/scene/expansion/test_conditions.py @@ -0,0 +1,238 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Anchored layout restrictions preserve geometry, ownership and addressed RNG.""" + +from __future__ import annotations +from dataclasses import replace +import numpy as np +import pytest + +from embodichain.lab.sim.scene.expansion import ( + SceneLayoutCondition, + prepare_scene_randomization, + generate_scene_variants, + save_scene_variants, + load_scene_variants, +) +from scene_layout_support import make_source, make_policy + + +def _poses(variant): + return {c.entity_uid: np.asarray(c.arena_pose) for c in variant.pose_changes} + + +def test_condition_owns_anchors_and_leaves_prepared_and_other_samples_independent(): + prepared = prepare_scene_randomization(make_source(), make_policy()) + anchor = np.array(prepared.source.poses["tray"]) + anchor[0, 3] += 0.1 + condition = SceneLayoutCondition({"tray": anchor}) + anchor[0, 3] = 99 + original_policy = prepared.policy + result = generate_scene_variants( + prepared, conditions=condition, seed=7, candidate_count=4 + ) + assert result.status == "completed" + for variant in result.variants: + np.testing.assert_allclose( + _poses(variant)["tray"], condition.poses["tray"], rtol=0, atol=1e-12 + ) + assert not np.allclose( + _poses(result.variants[0])["mug"], _poses(result.variants[-1])["mug"] + ) + assert prepared.policy == original_policy + projection = condition.to_dict() + projection["tray"][0][3] = 77 + assert condition.to_dict()["tray"][0][3] == pytest.approx(-0.2) + with pytest.raises(TypeError): + condition.poses["tray"] = np.eye(4) + + +def test_member_anchor_requires_pinned_ancestors_and_preserves_full_pose(): + prepared = prepare_scene_randomization(make_source(), make_policy()) + first = generate_scene_variants(prepared, seed=9, candidate_count=1).variants[0] + poses = _poses(first) + with pytest.raises(ValueError, match="ancestor"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"mug": poses["mug"]}) + ) + condition = SceneLayoutCondition(poses) + batch = generate_scene_variants( + prepared, conditions=condition, candidate_count=2, max_attempts=10 + ) + assert batch.status == "completed" + for variant in batch.variants: + for uid, pose in poses.items(): + np.testing.assert_allclose(_poses(variant)[uid], pose, rtol=0, atol=1e-10) + + +@pytest.mark.parametrize("size", [1, 7, 64]) +def test_condition_prefix_continuation_and_persistence(size, tmp_path): + source = make_source() + condition = SceneLayoutCondition({"tray": source.poses["tray"]}) + prepared = prepare_scene_randomization(source, make_policy(batch_size=size)) + one = generate_scene_variants( + prepared, conditions=condition, seed=13, candidate_count=3 + ) + two = generate_scene_variants( + prepared, + conditions=condition, + seed=13, + candidate_count=2, + start_ordinal=one.next_ordinal, + ) + together = generate_scene_variants( + prepared, conditions=condition, seed=13, candidate_count=5 + ) + assert tuple(one.variants) + tuple(two.variants) == tuple(together.variants) + reference = generate_scene_variants( + prepare_scene_randomization(source, make_policy(batch_size=1)), + conditions=condition, + seed=13, + candidate_count=5, + ) + assert tuple(reference.variants) == tuple(together.variants) + saved = save_scene_variants(together, tmp_path / "layouts.json") + loaded = load_scene_variants(saved) + assert tuple(loaded.variants) == tuple(together.variants) + + +def test_bad_anchor_rejects_without_relaxing_domain_or_permissions(): + source = make_source() + prepared = prepare_scene_randomization( + source, + make_policy(group_xy_offset_bounds_m={"tray": [[-0.1, -0.1], [0.1, 0.1]]}), + ) + outside = np.array(source.poses["tray"]) + outside[0, 3] += 0.2 + with pytest.raises(ValueError, match="bounds"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"tray": outside}) + ) + tilted = np.array(source.poses["tray"]) + tilted[0, 0] = -1 + tilted[1, 1] = -1 + with pytest.raises(ValueError, match="rotation"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"tray": tilted}) + ) + fixed = np.array(source.poses["z_target"]) + fixed[0, 3] += 0.01 + with pytest.raises(ValueError, match="fixed"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"z_target": fixed}) + ) + with pytest.raises(ValueError, match="Unknown"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"missing": np.eye(4)}) + ) + + +def test_geometrically_impossible_anchor_returns_exact_exhaustion_without_repair(): + source = make_source() + prepared = prepare_scene_randomization(source, make_policy()) + overlap = np.array(source.poses["tray"]) + overlap[:2, 3] = np.array(source.poses["z_target"])[:2, 3] + result = generate_scene_variants( + prepared, + conditions=SceneLayoutCondition({"tray": overlap}), + candidate_count=1, + max_attempts=9, + ) + assert result.status == "budget_exhausted" and not result.variants + assert result.attempts == 9 and result.next_ordinal == 9 + + +def test_anchor_reserves_room_before_sampling_an_earlier_sibling(): + source = make_source() + prepared = prepare_scene_randomization( + source, + make_policy( + group_targets=["tray", "z_target"], + intra_group={}, + collision_margin_m=0.02, + group_xy_offset_bounds_m={ + "tray": [[0, -0.04], [0.35, 0.04]], + "z_target": [[-0.8, -0.4], [0.4, 0.4]], + }, + ), + ) + target = np.array(source.poses["z_target"]) + target[:2, 3] = [-0.3, 0.0] + result = generate_scene_variants( + prepared, + conditions=SceneLayoutCondition({"z_target": target}), + seed=11, + candidate_count=8, + max_attempts=8, + ) + assert result.status == "completed" and len(result.variants) == 8 + for variant in result.variants: + poses = _poses(variant) + np.testing.assert_allclose(poses["z_target"], target, rtol=0, atol=1e-10) + # Their Y ranges always overlap. Clearance is possible only in X: + # 0.15 m tray half-width + 0.05 m block half-width + 0.02 m margin. + assert poses["tray"][0, 3] - target[0, 3] >= 0.22 - 1e-10 + + +def test_no_condition_and_empty_condition_preserve_legacy_exact_sequence(): + prepared = prepare_scene_randomization(make_source(), make_policy()) + a = generate_scene_variants(prepared, seed=41, candidate_count=4) + b = generate_scene_variants( + prepared, seed=41, candidate_count=4, conditions=SceneLayoutCondition({}) + ) + assert tuple(a.variants) == tuple(b.variants) and a.attempts == b.attempts + + +@pytest.mark.gpu +def test_cuda_anchors_keep_cpu_geometry_certificate_and_selected_pose(): + import torch + + if not torch.cuda.is_available(): + pytest.skip("CUDA unavailable") + source = make_source() + condition = SceneLayoutCondition({"tray": source.poses["tray"]}) + prepared = prepare_scene_randomization( + source, make_policy(device="cuda:0", batch_size=7) + ) + result = generate_scene_variants( + prepared, conditions=condition, seed=13, candidate_count=3 + ) + assert result.status == "completed" + for candidate in result.variants: + np.testing.assert_allclose( + _poses(candidate)["tray"], source.poses["tray"], rtol=0, atol=1e-10 + ) + + +def test_member_anchor_under_fixed_parent_and_invalid_height_are_explicit(): + prepared = prepare_scene_randomization( + make_source(), make_policy(randomize_groups=False) + ) + initial = generate_scene_variants(prepared, seed=19, candidate_count=1).variants[0] + pose = _poses(initial)["mug"] + result = generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"mug": pose}), candidate_count=1 + ) + assert result.status == "completed" + np.testing.assert_allclose( + _poses(result.variants[0])["mug"], pose, rtol=0, atol=1e-10 + ) + pose[2, 3] += 0.01 + with pytest.raises(ValueError, match="height"): + generate_scene_variants( + prepared, conditions=SceneLayoutCondition({"mug": pose}) + ) From 97493f37bb76cc046d1e57367b3eb38fc48b9a70 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 03:46:48 +0000 Subject: [PATCH 31/49] fix(expansion): address point-IK and idle-row review feedback --- agent_context/topics/expansion-engine/expansion-engine.md | 4 ++-- tests/sim/motion/_cartesian_segment_fixture.py | 2 +- tests/sim/motion/test_explicit_interpolation.py | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 0928121f21..84c13178ee 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -160,8 +160,8 @@ Optional idle-row reuse keeps the same W×B capacity while competing retry candidates use otherwise idle slots. Native write reservations still enforce the original quota; peers are cancelled only after a confirmed receipt, using measured partial evidence and the bridge's ordinary stop handshake. The low-level -source must supply an explicit cancellation port. Native Task Program jobs enable -this policy by default without adding processes or Worlds. +source must supply an explicit cancellation port. Native Task Program jobs opt in +with the [idle-row reuse setting](workloads.md#source-ports-and-native-accounting). Native numerical evidence has T submitted actions and T+1 measured states. It includes all represented dynamic scene entities, source/action semantics, physical parameters diff --git a/tests/sim/motion/_cartesian_segment_fixture.py b/tests/sim/motion/_cartesian_segment_fixture.py index e448a779b3..9360717571 100644 --- a/tests/sim/motion/_cartesian_segment_fixture.py +++ b/tests/sim/motion/_cartesian_segment_fixture.py @@ -27,7 +27,7 @@ def segment_fixture(case): calls = [] - robot = NS(device=torch.device("cpu")) + robot = NS(device=torch.device("cpu"), get_solver=lambda name=None: None) def fk(qpos, **kwargs): result = torch.eye(4).expand(qpos.shape[0], 4, 4).clone() diff --git a/tests/sim/motion/test_explicit_interpolation.py b/tests/sim/motion/test_explicit_interpolation.py index 807b26271a..f32bfa2436 100644 --- a/tests/sim/motion/test_explicit_interpolation.py +++ b/tests/sim/motion/test_explicit_interpolation.py @@ -77,6 +77,7 @@ def solve(*, pose, joint_seed, name): get_qpos_limits=lambda **kwargs: torch.tensor([[[-1.0, 1.0]]]).expand( batch, -1, -1 ), + get_solver=lambda name=None: None, compute_ik=solve, ) return generator, seeds From 5b5a30706fdbbecc2c011d46247d8ea10d390095 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 04:26:23 +0000 Subject: [PATCH 32/49] docs: refresh scene expansion architecture evidence --- docs/architecture/curated.json | 6 +- docs/architecture/generated/architecture.json | 198 +++++++------- docs/architecture/generated/summary.md | 248 +++++++++--------- 3 files changed, 226 insertions(+), 226 deletions(-) diff --git a/docs/architecture/curated.json b/docs/architecture/curated.json index 23cce03d11..faefda5424 100644 --- a/docs/architecture/curated.json +++ b/docs/architecture/curated.json @@ -1275,9 +1275,9 @@ { "path": "embodichain/lab/sim/scene/expansion/__init__.py", "symbol": "", - "start_line": 25, - "end_line": 27, - "excerpt": "from .cfg import SceneExpansionCfg\nfrom .contracts import ScenePoseChange, SceneVariant\nfrom .source import FixedSceneCandidateSource" + "start_line": 28, + "end_line": 31, + "excerpt": "from .cfg import SceneExpansionCfg\nfrom .contracts import ScenePoseChange, SceneVariant\nfrom .conditions import SceneLayoutCondition\nfrom .source import FixedSceneCandidateSource" }, { "path": "embodichain/lab/sim/scene/expansion/source.py", diff --git a/docs/architecture/generated/architecture.json b/docs/architecture/generated/architecture.json index a7bce18684..0cb0f66d19 100644 --- a/docs/architecture/generated/architecture.json +++ b/docs/architecture/generated/architecture.json @@ -3,8 +3,8 @@ "kind": "static-architecture", "coverage": "curated-sample", "repository": "DexForce/EmbodiChain", - "revision": "87d8d9454cd18f19d24434380bcd26bcd0dd376e", - "source_ref": "87d8d9454cd18f19d24434380bcd26bcd0dd376e", + "revision": "cfdc9f3cf510432ceb8c19af996c746f798a4eb3", + "source_ref": "HEAD", "package_version": "0.3.2", "topic_index": "agent_context/MAP.yaml", "limitations": [ @@ -496,8 +496,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "BufferedGymCommandSink", - "start_line": 864, - "end_line": 864, + "start_line": 892, + "end_line": 892, "excerpt": "class BufferedGymCommandSink:" } ], @@ -1418,8 +1418,8 @@ { "path": "embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py", "symbol": "GripperCollisionChecker", - "start_line": 39, - "end_line": 39, + "start_line": 96, + "end_line": 96, "excerpt": "class GripperCollisionChecker:" } ], @@ -1556,8 +1556,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge", - "start_line": 1149, - "end_line": 1149, + "start_line": 1177, + "end_line": 1177, "excerpt": "class TaskProgramDemoBridge:" } ], @@ -1591,8 +1591,8 @@ { "path": "embodichain/lab/task_program/integrations/catalog.py", "symbol": "TaskProgramIntegrationCatalog", - "start_line": 611, - "end_line": 611, + "start_line": 617, + "end_line": 617, "excerpt": "class TaskProgramIntegrationCatalog:" } ], @@ -1765,8 +1765,8 @@ { "path": "embodichain/lab/sim/motion/motion_generator.py", "symbol": "MotionGenerator", - "start_line": 310, - "end_line": 310, + "start_line": 334, + "end_line": 334, "excerpt": "class MotionGenerator:" } ], @@ -2310,8 +2310,8 @@ { "path": "embodichain/lab/sim/objects/rigid_object.py", "symbol": "RigidObject", - "start_line": 430, - "end_line": 430, + "start_line": 434, + "end_line": 434, "excerpt": "class RigidObject(BatchEntity):" } ], @@ -2607,8 +2607,8 @@ "path": "embodichain/lab/sim/scene/expansion/__init__.py", "symbol": "", "start_line": 28, - "end_line": 30, - "excerpt": "from .cfg import SceneExpansionCfg\nfrom .contracts import ScenePoseChange, SceneVariant\nfrom .source import FixedSceneCandidateSource" + "end_line": 31, + "excerpt": "from .cfg import SceneExpansionCfg\nfrom .contracts import ScenePoseChange, SceneVariant\nfrom .conditions import SceneLayoutCondition\nfrom .source import FixedSceneCandidateSource" }, { "path": "embodichain/lab/sim/scene/expansion/source.py", @@ -3116,8 +3116,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager", - "start_line": 562, - "end_line": 562, + "start_line": 566, + "end_line": 566, "excerpt": "class SimulationManager:" } ], @@ -3349,8 +3349,8 @@ { "path": "embodichain/gen_sim/task_engine/semantic_plan_validation.py", "symbol": "_validate_interpreted_plan", - "start_line": 824, - "end_line": 831, + "start_line": 838, + "end_line": 845, "excerpt": " \"status\": \"covered\",\n \"semantic_status\": \"valid\",\n \"visual_status\": (\"complete\" if observed == total else \"pending\"),\n \"pending_bindings\": len(bindings),\n \"visual_observed_entities\": observed,\n \"visual_total_entities\": total,\n \"execution_ready\": False,\n \"runtime_evidence_status\": \"not_run\"," } ], @@ -4001,8 +4001,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge.__init__", - "start_line": 1287, - "end_line": 1287, + "start_line": 1315, + "end_line": 1315, "excerpt": " self._clock = clock" } ] @@ -4019,8 +4019,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge.__init__", - "start_line": 1285, - "end_line": 1285, + "start_line": 1313, + "end_line": 1313, "excerpt": " self._runtime = runtime" }, { @@ -4044,8 +4044,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge.__init__", - "start_line": 1284, - "end_line": 1284, + "start_line": 1312, + "end_line": 1312, "excerpt": " self._program = program" }, { @@ -4069,8 +4069,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge.__init__", - "start_line": 1286, - "end_line": 1286, + "start_line": 1314, + "end_line": 1314, "excerpt": " self._sink = command_sink" } ] @@ -4087,8 +4087,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "TaskProgramDemoBridge._segment_actions", - "start_line": 1995, - "end_line": 1995, + "start_line": 2023, + "end_line": 2023, "excerpt": " self._sink.pop()," } ] @@ -4604,8 +4604,8 @@ { "path": "pyproject.toml", "symbol": "", - "start_line": 100, - "end_line": 101, + "start_line": 101, + "end_line": 102, "excerpt": "[project.entry-points.\"embodichain.tasks\"]\nembodichain_tasks = \"embodichain_tasks\"" }, { @@ -5251,8 +5251,8 @@ { "path": "embodichain/lab/sim/objects/rigid_object.py", "symbol": "RigidObject", - "start_line": 430, - "end_line": 430, + "start_line": 434, + "end_line": 434, "excerpt": "class RigidObject(BatchEntity):" } ] @@ -5819,15 +5819,15 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_robot", - "start_line": 4395, - "end_line": 4396, + "start_line": 4389, + "end_line": 4390, "excerpt": " robot = self._declare_spawn_articulation(cfg, Robot)\n self._robots[uid] = robot" }, { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager._declare_spawn_articulation", - "start_line": 4435, - "end_line": 4438, + "start_line": 4429, + "end_line": 4432, "excerpt": " facade = facade_type(\n cfg=cfg,\n device=self.device,\n )" } ] @@ -5844,8 +5844,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.start_visualization", - "start_line": 1194, - "end_line": 1199, + "start_line": 1198, + "end_line": 1203, "excerpt": " runtime = VisualizationRuntime(\n SceneExporter(self, visualization_cfg),\n visualization_cfg,\n )\n self._visualization_runtime = runtime\n runtime.start()" } ] @@ -5862,8 +5862,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_robot", - "start_line": 4396, - "end_line": 4401, + "start_line": 4390, + "end_line": 4395, "excerpt": " self._robots[uid] = robot\n if was_materialized:\n self.prepare()\n for sensor_cfg in mounted_sensors:\n self.add_sensor(sensor_cfg)\n return robot" } ] @@ -5880,8 +5880,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.enable_gizmo", - "start_line": 4591, - "end_line": 4591, + "start_line": 4585, + "end_line": 4585, "excerpt": " gizmo = Gizmo(target, gizmo_cfg, control_part)" } ] @@ -5898,8 +5898,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.create_rigid_constraint", - "start_line": 4041, - "end_line": 4041, + "start_line": 4051, + "end_line": 4051, "excerpt": " constraint = RigidConstraint(" } ] @@ -5916,8 +5916,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_rigid_object_group", - "start_line": 4182, - "end_line": 4182, + "start_line": 4192, + "end_line": 4192, "excerpt": " group = RigidObjectGroup(" } ] @@ -5934,8 +5934,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager._declare_rigid_objects", - "start_line": 3462, - "end_line": 3462, + "start_line": 3472, + "end_line": 3472, "excerpt": " rigid_obj = RigidObject(cfg=cfg, device=self.device)" } ] @@ -5952,8 +5952,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_articulation", - "start_line": 4283, - "end_line": 4283, + "start_line": 4293, + "end_line": 4293, "excerpt": " self._articulations[uid] = articulation" } ] @@ -5970,8 +5970,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_deformable_object", - "start_line": 3841, - "end_line": 3841, + "start_line": 3851, + "end_line": 3851, "excerpt": " self._deformable_objects[uid] = deformable" } ] @@ -5988,8 +5988,8 @@ { "path": "embodichain/lab/sim/sim_manager.py", "symbol": "SimulationManager.add_light", - "start_line": 2973, - "end_line": 2973, + "start_line": 2983, + "end_line": 2983, "excerpt": " self._lights[uid] = batch_lights" } ] @@ -6006,8 +6006,8 @@ { "path": "embodichain/lab/gym/envs/task_program/bridge.py", "symbol": "BufferedGymCommandSink.__init__", - "start_line": 880, - "end_line": 881, + "start_line": 908, + "end_line": 909, "excerpt": " self._encoder = encoder\n self._clock = clock" } ] @@ -6030,24 +6030,6 @@ } ] }, - { - "id": "static-imports-01a9592b5f6f", - "source": "simulation-manager", - "target": "configuration", - "relation": "imports", - "description": "The selected source module declares an absolute import associated with this target.", - "provenance": "static-extracted", - "scope": "Module-level declaration. Not a runtime call or proof that every class in the file uses the imported symbol.", - "evidence": [ - { - "path": "embodichain/lab/sim/sim_manager.py", - "symbol": "", - "start_line": 166, - "end_line": 166, - "excerpt": "from embodichain.utils import configclass, logger" - } - ] - }, { "id": "static-imports-023d746bdd8d", "source": "scene-generation", @@ -6606,6 +6588,24 @@ } ] }, + { + "id": "static-imports-3d3109273aad", + "source": "simulation-manager", + "target": "configuration", + "relation": "imports", + "description": "The selected source module declares an absolute import associated with this target.", + "provenance": "static-extracted", + "scope": "Module-level declaration. Not a runtime call or proof that every class in the file uses the imported symbol.", + "evidence": [ + { + "path": "embodichain/lab/sim/sim_manager.py", + "symbol": "", + "start_line": 170, + "end_line": 170, + "excerpt": "from embodichain.utils import configclass, logger" + } + ] + }, { "id": "static-imports-3d4c7a13ce4e", "source": "environment-adapter", @@ -7488,6 +7488,24 @@ } ] }, + { + "id": "static-imports-9ccfb0f3bdcf", + "source": "simulation-manager", + "target": "physics", + "relation": "imports", + "description": "The selected source module declares an absolute import associated with this target.", + "provenance": "static-extracted", + "scope": "Module-level declaration. Not a runtime call or proof that every class in the file uses the imported symbol.", + "evidence": [ + { + "path": "embodichain/lab/sim/sim_manager.py", + "symbol": "", + "start_line": 141, + "end_line": 141, + "excerpt": "from embodichain.lab.sim.physics import make_physics_backend" + } + ] + }, { "id": "static-imports-a225c2b26ae1", "source": "environment-adapter", @@ -7848,24 +7866,6 @@ } ] }, - { - "id": "static-imports-c84985d043b9", - "source": "simulation-manager", - "target": "physics", - "relation": "imports", - "description": "The selected source module declares an absolute import associated with this target.", - "provenance": "static-extracted", - "scope": "Module-level declaration. Not a runtime call or proof that every class in the file uses the imported symbol.", - "evidence": [ - { - "path": "embodichain/lab/sim/sim_manager.py", - "symbol": "", - "start_line": 137, - "end_line": 137, - "excerpt": "from embodichain.lab.sim.physics import make_physics_backend" - } - ] - }, { "id": "static-imports-c8cfa7225b4a", "source": "embodied-env", @@ -8604,8 +8604,8 @@ "static-imports-735fdeb87797", "static-imports-30e2933cfbeb", "static-imports-a38ea1f6aa90", - "static-imports-c84985d043b9", - "static-imports-01a9592b5f6f", + "static-imports-9ccfb0f3bdcf", + "static-imports-3d3109273aad", "static-imports-3d4c7a13ce4e", "static-imports-14722eceaa11", "static-imports-84f40c9ef00a", @@ -9060,8 +9060,8 @@ "static-imports-735fdeb87797", "static-imports-30e2933cfbeb", "static-imports-a38ea1f6aa90", - "static-imports-c84985d043b9", - "static-imports-01a9592b5f6f" + "static-imports-9ccfb0f3bdcf", + "static-imports-3d3109273aad" ], "groups": [ { @@ -9363,7 +9363,7 @@ "static-imports-a954b58f9edc", "static-imports-17df33c96f97", "static-imports-9bc131d4e099", - "static-imports-01a9592b5f6f" + "static-imports-3d3109273aad" ], "groups": [ { diff --git a/docs/architecture/generated/summary.md b/docs/architecture/generated/summary.md index 6336b00c5b..e15c9ac680 100644 --- a/docs/architecture/generated/summary.md +++ b/docs/architecture/generated/summary.md @@ -1,139 +1,139 @@ # Architecture overview -Source revision: `87d8d9454cd18f19d24434380bcd26bcd0dd376e` · package 0.3.2 +Source revision: `cfdc9f3cf510432ceb8c19af996c746f798a4eb3` · package 0.3.2 Curated static relationships; not a complete dependency graph or runtime trace. | Module | Responsibility | Evidence and documentation | | --- | --- | --- | -| CLI | Dispatches commands and lazily loads task discovery, environment, and training entry points. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/cli/main.py#L17-L17) · [CLI reference](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/guides/cli.md) | -| Environment launcher | Runs task discovery, configuration loading, and Gym environment creation. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/scripts/run_task.py#L2015-L2015) · [Environment launch guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/guides/run_task.md) | -| Task discovery | Imports installed task packages through entry points to populate the environment registry. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/utils/registration.py#L446-L446) · [Task discovery and supported tasks](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/resources/task/index.rst) | -| Official tasks | Registers official task entry points and organises reusable robot tasks. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/extensions/embodichain_tasks/embodichain_tasks/__init__.py#L17-L23) · [Supported tasks](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/resources/task/index.rst) | -| Config loader | Loads deployment files, resolves components, and assembles the typed environment configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/utils/gym_utils.py#L1954-L1954) · [Configuration guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/guides/configuration.md) | -| Component composition | Resolves environment and embodiment components into runnable Gym configurations. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/utils/_component_composition.py#L17-L17) · [Configuration guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/guides/configuration.md) | -| EmbodiedEnv | Assembles scenes, managers, and demonstrations with optional Task Program integration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/embodied_env.py#L518-L518) · [EmbodiedEnv documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/env.md) | -| BaseEnv | Owns the Gym loop, simulation initialisation, and environment step lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/base_env.py#L118-L118) · [BaseEnv documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/env.md) | -| Managers | Organises observations, actions, rewards, events, and data recording within the environment lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/__init__.py#L17-L20) · [Gym managers and environment lifecycle](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/index.rst) | -| Configuration utilities | Defines typed configuration copying, serialization, and required-field validation. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/utils/configclass.py#L15-L15) · [Configuration utilities documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.utils.rst) | -| Domain randomization | Event functors randomize physical, visual, spatial, and geometric properties. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/randomization/__init__.py#L17-L20) · [Domain randomization documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.managers.rst) | -| DifferentiableEnv | Preserves the Gym lifecycle while bridging task-defined kinematics to autograd. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/differentiable_env.py#L48-L48) · [DifferentiableEnv documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.rst) | -| EventManager | Dispatches configured event functors with lifecycle scheduling and scoped seeds. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/event_manager.py#L97-L97) · [EventManager documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.managers.rst) | -| TaskProgramCompiler | Compiles task configuration into an analysable program using a static scene manifest. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/compiler/program.py#L1613-L1613) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [TaskProgramCompiler documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | -| SemanticCallCompiler | Analyses and lowers Semantic Calls against the bound scene and skill integration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/compiler/lowering.py#L1033-L1033) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [SemanticCallCompiler documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | -| SemanticCallExecutor | Lowers and executes semantic calls, creating an execution session for each call. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/runtime/executor.py#L258-L258) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [SemanticCallExecutor documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst) | -| TaskProgramEnvironmentAdapter | Validates integration choices and assembles the semantic runtime and Gym bridge. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/integrations/environment.py#L315-L315) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [TaskProgramEnvironmentAdapter documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst) | -| TaskProgramDemoBridge | Converts program segments into lazy Gym demonstrations with a shared runtime, buffer, and clock. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/task_program/bridge.py#L1149-L1149) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [TaskProgramDemoBridge documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | -| Scene expansion attempts | Prepares selected scene candidates and executes a shared Task Program with per-row measured acceptance. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/integrations/scene_expansion.py#L241-L241) · [Task Program scene preparation and measured acceptance](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.scene_expansion.rst) | -| MLLM frontend | Decodes untrusted model JSON and compiles it through the existing Task Program adapter. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/agents/mllm/task_program.py#L17-L17) · [MLLM frontend documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) | -| AtomicSkillEngine | Manages planning resources and atomic skills to create executable action sessions. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/atomic_skills/engine.py#L85-L85) · [Atomic Skills guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/atomic_skills/index.md) · [AtomicSkillEngine documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_skills.rst) | -| Motion benchmarks | Evaluates motion planners and Atomic Skills using installed suites and external adapters. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/extensions/embodichain_benchmarks/motion_generation/__init__.py#L17-L21) · [Benchmark API and external adapters](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/benchmarks.rst) | -| MotionGenerator | Composes planning backends behind a unified robot motion generation interface. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/motion/motion_generator.py#L310-L310) · [Motion generation guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/motion/motion_generator.md) · [MotionGenerator documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.motion.motion_generator.rst) | -| Planners | Provides motion planning backends that generate constrained robot trajectories. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/motion/planners/__init__.py#L17-L22) · [Motion planner guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/motion/planners/index.rst) | -| Solvers | Provides inverse kinematics backends and stateful robot solving capabilities. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/motion/solvers/__init__.py#L17-L20) · [Kinematic solver guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/motion/solvers/index.rst) | -| Robot workspace | Loads reachability caches and samples robot joint configurations and poses. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/motion/workspace/runtime.py#L53-L53) · [Robot workspace documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/workspace_analyzer/runtime.md) | -| Expansion session | Owns bounded candidate lifecycles, collection budgets and final commit receipts. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/expansion/session.py#L121-L121) · [Trajectory augmentation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.motion.expansion.rst) | -| SimulationManager | Manages the world, robots, sensors, physics, and visualisation lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/sim_manager.py#L562-L562) · [SimulationManager documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/sim_manager.md) | -| Scene expansion contracts | Defines immutable arena-local scene proposals and bounded authored candidate sources. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/scene/expansion/__init__.py#L28-L30) · [Scene expansion contracts and fixed candidates](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst) | -| Robot | Represents a simulated robot with control parts, joint state, and kinematics. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/robot.py#L17-L17) · [Robots and articulations](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/sim_articulation.md) | -| Sensors | Provides camera, stereo, and contact observations for the environment. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/sensors/__init__.py#L17-L20) · [Sensor guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/sensors/index.rst) | -| Physics backends | Constructs the configured physics backend and connects simulation state to physics solving. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/physics/__init__.py#L16-L21) · [Physics backend guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/sim_manager/physics/index.md) | -| Browser visualization | Publishes simulation snapshots and interactive controls through a browser runtime. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/visualization/runtime.py#L17-L17) · [Browser visualization guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/visualization/viser.md) | -| Rigid objects | Represents rigid scene objects and their physical state. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/rigid_object.py#L430-L430) · [Rigid objects documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Rigid object groups | Groups multiple rigid bodies into a batched scene entity. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/rigid_object_group.py#L187-L187) · [Rigid object group guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/sim_rigid_object_group.md) · [Object API reference](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Articulations | Represents jointed scene entities and articulated state. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/articulation.py#L724-L724) · [Articulations documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Deformable objects | Represents Newton-backed deformable particle-set entities. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/deformable/base.py#L49-L49) · [Deformable objects documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Lights | Controls light color, intensity, falloff, and pose through a batched facade. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/light.py#L40-L40) · [Lights documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Rigid constraints | Wraps per-arena fixed constraints between two rigid objects. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/constraint.py#L36-L36) · [Rigid constraints documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Gizmo | Provides native robot IK and browser manipulation controls for simulation targets. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/gizmo.py#L458-L458) · [Gizmo documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Compute | Shared numerical algorithms for kinematics, trajectories, geometry, and images. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/compute/__init__.py#L17-L21) · [Compute API reference](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.compute.rst) | -| Trajectory computation | Shared interpolation, resampling, timing, and trajectory warping algorithms. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/compute/trajectory/__init__.py#L17-L20) · [Trajectory computation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.compute.rst) | -| Kinematics computation | Shared numerical kinematics and manipulability algorithms. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/compute/kinematics/__init__.py#L17-L24) · [Kinematics computation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.compute.rst) | -| DatasetManager | Coordinates dataset functors for frame collection, saving, and finalization. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/dataset_manager.py#L46-L46) · [DatasetManager documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/dataset_functors.md) | -| LeRobot recording | Persists demonstrations and metadata in LeRobot datasets with optional depth sidecars. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/datasets.py#L167-L167) · [LeRobot recording documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/dataset_functors.md) | -| Async recording | Moves durable dataset writes to one background worker. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/managers/async_datasets.py#L58-L58) · [Async recording documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/gym/dataset_functors.md) | -| Depth sidecar writer | Coordinates depth-video files and metadata alongside recorded demonstrations. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/depth_video/writer.py#L226-L226) · [Depth video documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | -| Depth sidecar reader | Loads depth metadata and decodes episode/sensor depth video frames. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/depth_video/reader.py#L17-L23) · [Depth sidecar reader documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | -| Depth quantization | Converts depth values to and from the sidecar video representation. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/depth_video/depth_utils.py#L24-L35) · [Depth quantization documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | -| OnlineDataEngine | Online data engine managing workers and their lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/engine/data.py#L17-L17) · [Online data streaming guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/online_data.md) | -| OnlineDataset | Exposes live engine samples as an infinite PyTorch IterableDataset. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/datasets/online_data.py#L39-L39) · [OnlineDataset documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.data_pipeline.datasets.rst) | -| Chunk samplers | Selects fixed-shape time windows using configurable chunk-length distributions. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data_pipeline/datasets/sampler.py#L17-L17) · [Chunk samplers documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.data_pipeline.datasets.rst) | -| Data assets | Resolves asset paths and coordinates registered dataset downloads and caches. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/data/dataset.py#L17-L17) · [Data assets documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/resources/assets.md) · [Asset catalog and task role contracts](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/asset_generalization.rst) | -| Scene generation | Generates scene state from input images for scene asset workflows. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/generate.py#L17-L17) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene understanding | Interprets an image, segments objects, and initializes a validated support graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/generation/scene_understanding.py#L260-L260) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Asset generation & refinement | Generates geometry and articulated assets, then refines scene placement. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/generation/scene_generation.py#L96-L96) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene asset preparation | Prepares generated Scene Engine geometry for layout and export. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/utils/simready_processor.py#L90-L90) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene editing | Edits an existing portable scene using a typed edit plan. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/edit.py#L17-L17) · [Scene editing documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene edit layout | Reconstructs scene placement against an edited goal graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/editing/scene_edit_layout_generation.py#L32-L32) · [Scene editing documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene import | Reconstructs an editable scene and graph from a portable scene export. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/utils/scene_importer.py#L50-L50) · [Scene export documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Scene export | Writes portable scene metadata and assets for downstream simulation preparation. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/scene_engine/pipeline/utils/scene_exporter.py#L53-L53) · [Scene export documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Asset Engine | Prepares an existing mesh through source conversion, semantic/physics inference, and mesh/USD export. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/asset_engine/pipeline/ingest.py#L172-L178) · [Asset Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/asset_engine.md) | -| Asset parser stages | Dispatches inspector, geometry, physics, USD, and internal asset parsers. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/asset_engine/parser/base.py#L58-L64) · [Asset Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/asset_engine.md) | -| GenSim UI sessions | Tracks one replaceable subprocess per Gradio session. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/gradio_ui/app_processes.py#L109-L109) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/scene_engine.md) | -| Training assembly | Builds environments, policies, algorithms, and the compatible trainer from configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/train.py#L17-L17) · [Training assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/rl/train_script.md) | -| RL algorithms | Registers PPO, GRPO, and APG with their rollout contracts. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/algo/__init__.py#L17-L17) · [RL algorithms documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/rl/algorithm.md) | -| PPO | Optimizes an actor-critic policy from standard TensorDict rollouts. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/algo/ppo.py#L52-L52) · [PPO documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | -| GRPO | Optimizes policies with group-relative advantages from standard rollouts. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/algo/grpo.py#L48-L48) · [GRPO documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | -| APG | Optimizes policy parameters through differentiable rollout rewards. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/algo/apg.py#L119-L119) · [APG documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | -| Policy models | Defines policy action inference and model interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/policies/policy.py#L35-L35) · [Policy models documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/rl/models.md) | -| ActorCritic | Provides Gaussian actions and value estimates with separate actor and critic inputs. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/policies/actor_critic.py#L33-L33) · [ActorCritic documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.policies.rst) | -| ActorOnly | Provides Gaussian actions without a learned value network. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/policies/actor_only.py#L31-L31) · [ActorOnly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.policies.rst) | -| Learning environments | Defines lightweight vector-environment protocols and factory registration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/env.py#L17-L17) · [Learning environments documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | -| Standard trainer | Coordinates standard rollout collection, algorithm updates, evaluation, and checkpoints. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/utils/trainer.py#L17-L17) · [Reinforcement learning overview](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/rl/index.rst) | -| SyncCollector | Collects standard vector-environment rollouts into the training buffer. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/collector/sync_collector.py#L33-L33) · [SyncCollector documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.collector.rst) | -| Rollout buffer | Stores standard rollout transitions and bootstrap state in TensorDict buffers. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/buffer/standard_buffer.py#L27-L27) · [Rollout buffer documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/rl/buffer.md) | -| DifferentiableTrainer | Coordinates graph-connected rollouts and analytic policy-gradient updates. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/differentiable_trainer.py#L77-L77) · [DifferentiableTrainer documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | -| Differentiable collector | Collects differentiable trajectories while preserving their autograd graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/collector/differentiable.py#L145-L145) · [Differentiable collector documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.collector.rst) | -| Running observation normalization | Normalizes continuous observation fields with explicit running-statistic updates. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/normalization.py#L29-L29) · [Running observation normalization documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | -| Policy evaluation | Runs trained policy evaluation in headless or viewer workflows. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/rl/policy_evaluation/cli.py#L17-L17) · [Policy evaluation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.rl.policy_evaluation.rst) | -| Devices | Defines start, stop, and controller-state interfaces for robot input devices. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/devices/device.py#L17-L17) · [Laboratory and device API reference](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.rst) | -| Device controller | Maps input-device state to robot joint commands with joint-limit handling. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/devices/device_controller.py#L29-L29) · [Device controller documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.rst) | -| GraspKit | Defines parallel-jaw gripper models and grasp-pose generation interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/graspkit/pose_generator.py#L17-L17) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| URDF assembly | Assembles URDF components, connections, sensors, and mesh resources. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/urdf_assembly_manager.py#L81-L81) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| Convex decomposition | Prepares convex collision meshes for URDF assets. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/acd/cli.py#L17-L17) · [Convex decomposition documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/convex_decomposition.md) | -| Shared scene services | Composes explicit configurations, proposes layouts, and operates on caller-owned physical state. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/scene/__init__.py#L17-L22) · [Scene services architecture and capabilities](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/scene/index.md) · [Scene construction and preparation workflows](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/scene/workflows.md) · [Production scene service integrations](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/scene/integrations.md) · [Scene composition, layout, state and validation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.rst) · [Shared numerical geometry and layout](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.compute.scene_geometry.rst) | -| NeRD model extension | Bundles the causal NeRD network, physical codec, trajectory windows and supervised recipe in the main wheel. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/extensions/embodichain_models/embodichain_models/dynamics/nerd/model.py#L201-L201) · [Official model library](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/model_catalogs.rst) · [NeRD data and training workflow](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/neural_dynamics/nerd.md) | -| Supervised learning (SL) | Shares structured batches, objective-owned losses, optimizer updates and offline recovery across policy and dynamics fitting. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/learning/sl/learner.py#L52-L52) · [SL batches, updates and recovery](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.learning.sl.rst) | -| NeRD showcase | Prepares pinned external resources and routes default NeRD training through shared SL. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/examples/learning/nerd/__main__.py#L81-L81) · [NeRD showcase commands](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/neural_dynamics/nerd.md) | -| Robot world model (RWM) | Owns action-conditioned robot-state prediction, differentiable rollout objectives and bounded transition replay. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/extensions/embodichain_models/embodichain_models/dynamics/rwm/model.py#L77-L77) · [RWM state, objectives, prediction, replay and SL recipe](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/rwm.rst) · [RWM principles and usage](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/neural_dynamics/rwm.md) | -| TaskSpec | Defines simulator-independent task requirements, milestones, semantic identity and evidence evaluation. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/task_spec/spec.py#L335-L335) · [TaskSpec protocol API](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/public_api.rst) | -| Task Engine | Interprets instructions and image evidence into candidates, TaskSpec requirements and canonical Semantic Call graphs. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/gen_sim/task_engine/agent.py#L72-L72) · [Task Engine workflow and artifact guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/generative_sim/task_engine.md) · [Task Engine semantic contracts](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.gen_sim.task_engine.rst) | +| CLI | Dispatches commands and lazily loads task discovery, environment, and training entry points. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/cli/main.py#L17-L17) · [CLI reference](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/guides/cli.md) | +| Environment launcher | Runs task discovery, configuration loading, and Gym environment creation. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/scripts/run_task.py#L2015-L2015) · [Environment launch guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/guides/run_task.md) | +| Task discovery | Imports installed task packages through entry points to populate the environment registry. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/utils/registration.py#L446-L446) · [Task discovery and supported tasks](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/resources/task/index.rst) | +| Official tasks | Registers official task entry points and organises reusable robot tasks. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/extensions/embodichain_tasks/embodichain_tasks/__init__.py#L17-L23) · [Supported tasks](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/resources/task/index.rst) | +| Config loader | Loads deployment files, resolves components, and assembles the typed environment configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/utils/gym_utils.py#L1954-L1954) · [Configuration guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/guides/configuration.md) | +| Component composition | Resolves environment and embodiment components into runnable Gym configurations. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/utils/_component_composition.py#L17-L17) · [Configuration guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/guides/configuration.md) | +| EmbodiedEnv | Assembles scenes, managers, and demonstrations with optional Task Program integration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/embodied_env.py#L518-L518) · [EmbodiedEnv documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/env.md) | +| BaseEnv | Owns the Gym loop, simulation initialisation, and environment step lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/base_env.py#L118-L118) · [BaseEnv documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/env.md) | +| Managers | Organises observations, actions, rewards, events, and data recording within the environment lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/__init__.py#L17-L20) · [Gym managers and environment lifecycle](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/index.rst) | +| Configuration utilities | Defines typed configuration copying, serialization, and required-field validation. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/utils/configclass.py#L15-L15) · [Configuration utilities documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.utils.rst) | +| Domain randomization | Event functors randomize physical, visual, spatial, and geometric properties. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/randomization/__init__.py#L17-L20) · [Domain randomization documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.managers.rst) | +| DifferentiableEnv | Preserves the Gym lifecycle while bridging task-defined kinematics to autograd. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/differentiable_env.py#L48-L48) · [DifferentiableEnv documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.rst) | +| EventManager | Dispatches configured event functors with lifecycle scheduling and scoped seeds. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/event_manager.py#L97-L97) · [EventManager documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.managers.rst) | +| TaskProgramCompiler | Compiles task configuration into an analysable program using a static scene manifest. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/compiler/program.py#L1613-L1613) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [TaskProgramCompiler documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | +| SemanticCallCompiler | Analyses and lowers Semantic Calls against the bound scene and skill integration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/compiler/lowering.py#L1033-L1033) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [SemanticCallCompiler documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | +| SemanticCallExecutor | Lowers and executes semantic calls, creating an execution session for each call. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/runtime/executor.py#L258-L258) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [SemanticCallExecutor documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst) | +| TaskProgramEnvironmentAdapter | Validates integration choices and assembles the semantic runtime and Gym bridge. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/integrations/environment.py#L315-L315) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [TaskProgramEnvironmentAdapter documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst) | +| TaskProgramDemoBridge | Converts program segments into lazy Gym demonstrations with a shared runtime, buffer, and clock. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/task_program/bridge.py#L1177-L1177) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [TaskProgramDemoBridge documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | +| Scene expansion attempts | Prepares selected scene candidates and executes a shared Task Program with per-row measured acceptance. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/integrations/scene_expansion.py#L241-L241) · [Task Program scene preparation and measured acceptance](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.scene_expansion.rst) | +| MLLM frontend | Decodes untrusted model JSON and compiles it through the existing Task Program adapter. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/agents/mllm/task_program.py#L17-L17) · [MLLM frontend documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) | +| AtomicSkillEngine | Manages planning resources and atomic skills to create executable action sessions. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/atomic_skills/engine.py#L85-L85) · [Atomic Skills guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/atomic_skills/index.md) · [AtomicSkillEngine documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_skills.rst) | +| Motion benchmarks | Evaluates motion planners and Atomic Skills using installed suites and external adapters. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/extensions/embodichain_benchmarks/motion_generation/__init__.py#L17-L21) · [Benchmark API and external adapters](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/benchmarks.rst) | +| MotionGenerator | Composes planning backends behind a unified robot motion generation interface. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/motion/motion_generator.py#L334-L334) · [Motion generation guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/motion/motion_generator.md) · [MotionGenerator documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.motion.motion_generator.rst) | +| Planners | Provides motion planning backends that generate constrained robot trajectories. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/motion/planners/__init__.py#L17-L22) · [Motion planner guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/motion/planners/index.rst) | +| Solvers | Provides inverse kinematics backends and stateful robot solving capabilities. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/motion/solvers/__init__.py#L17-L20) · [Kinematic solver guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/motion/solvers/index.rst) | +| Robot workspace | Loads reachability caches and samples robot joint configurations and poses. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/motion/workspace/runtime.py#L53-L53) · [Robot workspace documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/workspace_analyzer/runtime.md) | +| Expansion session | Owns bounded candidate lifecycles, collection budgets and final commit receipts. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/expansion/session.py#L121-L121) · [Trajectory augmentation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.motion.expansion.rst) | +| SimulationManager | Manages the world, robots, sensors, physics, and visualisation lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/sim_manager.py#L566-L566) · [SimulationManager documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/sim_manager.md) | +| Scene expansion contracts | Defines immutable arena-local scene proposals and bounded authored candidate sources. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/scene/expansion/__init__.py#L28-L31) · [Scene expansion contracts and fixed candidates](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.expansion.rst) | +| Robot | Represents a simulated robot with control parts, joint state, and kinematics. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/robot.py#L17-L17) · [Robots and articulations](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/sim_articulation.md) | +| Sensors | Provides camera, stereo, and contact observations for the environment. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/sensors/__init__.py#L17-L20) · [Sensor guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/sensors/index.rst) | +| Physics backends | Constructs the configured physics backend and connects simulation state to physics solving. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/physics/__init__.py#L16-L21) · [Physics backend guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/sim_manager/physics/index.md) | +| Browser visualization | Publishes simulation snapshots and interactive controls through a browser runtime. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/visualization/runtime.py#L17-L17) · [Browser visualization guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/visualization/viser.md) | +| Rigid objects | Represents rigid scene objects and their physical state. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/rigid_object.py#L434-L434) · [Rigid objects documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Rigid object groups | Groups multiple rigid bodies into a batched scene entity. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/rigid_object_group.py#L187-L187) · [Rigid object group guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/sim_rigid_object_group.md) · [Object API reference](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Articulations | Represents jointed scene entities and articulated state. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/articulation.py#L724-L724) · [Articulations documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Deformable objects | Represents Newton-backed deformable particle-set entities. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/deformable/base.py#L49-L49) · [Deformable objects documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Lights | Controls light color, intensity, falloff, and pose through a batched facade. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/light.py#L40-L40) · [Lights documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Rigid constraints | Wraps per-arena fixed constraints between two rigid objects. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/constraint.py#L36-L36) · [Rigid constraints documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Gizmo | Provides native robot IK and browser manipulation controls for simulation targets. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/gizmo.py#L458-L458) · [Gizmo documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Compute | Shared numerical algorithms for kinematics, trajectories, geometry, and images. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/compute/__init__.py#L17-L21) · [Compute API reference](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.compute.rst) | +| Trajectory computation | Shared interpolation, resampling, timing, and trajectory warping algorithms. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/compute/trajectory/__init__.py#L17-L20) · [Trajectory computation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.compute.rst) | +| Kinematics computation | Shared numerical kinematics and manipulability algorithms. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/compute/kinematics/__init__.py#L17-L24) · [Kinematics computation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.compute.rst) | +| DatasetManager | Coordinates dataset functors for frame collection, saving, and finalization. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/dataset_manager.py#L46-L46) · [DatasetManager documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/dataset_functors.md) | +| LeRobot recording | Persists demonstrations and metadata in LeRobot datasets with optional depth sidecars. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/datasets.py#L167-L167) · [LeRobot recording documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/dataset_functors.md) | +| Async recording | Moves durable dataset writes to one background worker. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/managers/async_datasets.py#L58-L58) · [Async recording documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/gym/dataset_functors.md) | +| Depth sidecar writer | Coordinates depth-video files and metadata alongside recorded demonstrations. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/depth_video/writer.py#L226-L226) · [Depth video documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | +| Depth sidecar reader | Loads depth metadata and decodes episode/sensor depth video frames. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/depth_video/reader.py#L17-L23) · [Depth sidecar reader documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | +| Depth quantization | Converts depth values to and from the sidecar video representation. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/depth_video/depth_utils.py#L24-L35) · [Depth quantization documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.data_pipeline.depth_video.rst) | +| OnlineDataEngine | Online data engine managing workers and their lifecycle. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/engine/data.py#L17-L17) · [Online data streaming guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/online_data.md) | +| OnlineDataset | Exposes live engine samples as an infinite PyTorch IterableDataset. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/datasets/online_data.py#L39-L39) · [OnlineDataset documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.data_pipeline.datasets.rst) | +| Chunk samplers | Selects fixed-shape time windows using configurable chunk-length distributions. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data_pipeline/datasets/sampler.py#L17-L17) · [Chunk samplers documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.data_pipeline.datasets.rst) | +| Data assets | Resolves asset paths and coordinates registered dataset downloads and caches. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/data/dataset.py#L17-L17) · [Data assets documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/resources/assets.md) · [Asset catalog and task role contracts](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/asset_generalization.rst) | +| Scene generation | Generates scene state from input images for scene asset workflows. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/generate.py#L17-L17) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene understanding | Interprets an image, segments objects, and initializes a validated support graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/generation/scene_understanding.py#L260-L260) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Asset generation & refinement | Generates geometry and articulated assets, then refines scene placement. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/generation/scene_generation.py#L96-L96) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene asset preparation | Prepares generated Scene Engine geometry for layout and export. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/utils/simready_processor.py#L90-L90) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene editing | Edits an existing portable scene using a typed edit plan. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/edit.py#L17-L17) · [Scene editing documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene edit layout | Reconstructs scene placement against an edited goal graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/editing/scene_edit_layout_generation.py#L32-L32) · [Scene editing documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene import | Reconstructs an editable scene and graph from a portable scene export. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/utils/scene_importer.py#L50-L50) · [Scene export documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Scene export | Writes portable scene metadata and assets for downstream simulation preparation. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/scene_engine/pipeline/utils/scene_exporter.py#L53-L53) · [Scene export documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Asset Engine | Prepares an existing mesh through source conversion, semantic/physics inference, and mesh/USD export. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/asset_engine/pipeline/ingest.py#L172-L178) · [Asset Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/asset_engine.md) | +| Asset parser stages | Dispatches inspector, geometry, physics, USD, and internal asset parsers. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/asset_engine/parser/base.py#L58-L64) · [Asset Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/asset_engine.md) | +| GenSim UI sessions | Tracks one replaceable subprocess per Gradio session. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/gradio_ui/app_processes.py#L109-L109) · [Scene Engine guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/scene_engine.md) | +| Training assembly | Builds environments, policies, algorithms, and the compatible trainer from configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/train.py#L17-L17) · [Training assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/rl/train_script.md) | +| RL algorithms | Registers PPO, GRPO, and APG with their rollout contracts. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/algo/__init__.py#L17-L17) · [RL algorithms documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/rl/algorithm.md) | +| PPO | Optimizes an actor-critic policy from standard TensorDict rollouts. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/algo/ppo.py#L52-L52) · [PPO documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | +| GRPO | Optimizes policies with group-relative advantages from standard rollouts. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/algo/grpo.py#L48-L48) · [GRPO documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | +| APG | Optimizes policy parameters through differentiable rollout rewards. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/algo/apg.py#L119-L119) · [APG documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.algo.rst) | +| Policy models | Defines policy action inference and model interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/policies/policy.py#L35-L35) · [Policy models documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/rl/models.md) | +| ActorCritic | Provides Gaussian actions and value estimates with separate actor and critic inputs. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/policies/actor_critic.py#L33-L33) · [ActorCritic documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.policies.rst) | +| ActorOnly | Provides Gaussian actions without a learned value network. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/policies/actor_only.py#L31-L31) · [ActorOnly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.policies.rst) | +| Learning environments | Defines lightweight vector-environment protocols and factory registration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/env.py#L17-L17) · [Learning environments documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | +| Standard trainer | Coordinates standard rollout collection, algorithm updates, evaluation, and checkpoints. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/utils/trainer.py#L17-L17) · [Reinforcement learning overview](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/rl/index.rst) | +| SyncCollector | Collects standard vector-environment rollouts into the training buffer. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/collector/sync_collector.py#L33-L33) · [SyncCollector documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.collector.rst) | +| Rollout buffer | Stores standard rollout transitions and bootstrap state in TensorDict buffers. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/buffer/standard_buffer.py#L27-L27) · [Rollout buffer documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/rl/buffer.md) | +| DifferentiableTrainer | Coordinates graph-connected rollouts and analytic policy-gradient updates. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/differentiable_trainer.py#L77-L77) · [DifferentiableTrainer documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | +| Differentiable collector | Collects differentiable trajectories while preserving their autograd graph. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/collector/differentiable.py#L145-L145) · [Differentiable collector documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.collector.rst) | +| Running observation normalization | Normalizes continuous observation fields with explicit running-statistic updates. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/normalization.py#L29-L29) · [Running observation normalization documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.rst) | +| Policy evaluation | Runs trained policy evaluation in headless or viewer workflows. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/rl/policy_evaluation/cli.py#L17-L17) · [Policy evaluation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.rl.policy_evaluation.rst) | +| Devices | Defines start, stop, and controller-state interfaces for robot input devices. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/devices/device.py#L17-L17) · [Laboratory and device API reference](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.rst) | +| Device controller | Maps input-device state to robot joint commands with joint-limit handling. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/devices/device_controller.py#L29-L29) · [Device controller documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.rst) | +| GraspKit | Defines parallel-jaw gripper models and grasp-pose generation interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/graspkit/pose_generator.py#L17-L17) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| URDF assembly | Assembles URDF components, connections, sensors, and mesh resources. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/urdf_assembly_manager.py#L81-L81) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| Convex decomposition | Prepares convex collision meshes for URDF assets. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/acd/cli.py#L17-L17) · [Convex decomposition documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/convex_decomposition.md) | +| Shared scene services | Composes explicit configurations, proposes layouts, and operates on caller-owned physical state. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/scene/__init__.py#L17-L22) · [Scene services architecture and capabilities](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/scene/index.md) · [Scene construction and preparation workflows](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/scene/workflows.md) · [Production scene service integrations](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/scene/integrations.md) · [Scene composition, layout, state and validation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.scene.rst) · [Shared numerical geometry and layout](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.compute.scene_geometry.rst) | +| NeRD model extension | Bundles the causal NeRD network, physical codec, trajectory windows and supervised recipe in the main wheel. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/extensions/embodichain_models/embodichain_models/dynamics/nerd/model.py#L201-L201) · [Official model library](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/model_catalogs.rst) · [NeRD data and training workflow](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/neural_dynamics/nerd.md) | +| Supervised learning (SL) | Shares structured batches, objective-owned losses, optimizer updates and offline recovery across policy and dynamics fitting. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/learning/sl/learner.py#L52-L52) · [SL batches, updates and recovery](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.learning.sl.rst) | +| NeRD showcase | Prepares pinned external resources and routes default NeRD training through shared SL. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/examples/learning/nerd/__main__.py#L81-L81) · [NeRD showcase commands](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/neural_dynamics/nerd.md) | +| Robot world model (RWM) | Owns action-conditioned robot-state prediction, differentiable rollout objectives and bounded transition replay. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/extensions/embodichain_models/embodichain_models/dynamics/rwm/model.py#L77-L77) · [RWM state, objectives, prediction, replay and SL recipe](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/rwm.rst) · [RWM principles and usage](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/neural_dynamics/rwm.md) | +| TaskSpec | Defines simulator-independent task requirements, milestones, semantic identity and evidence evaluation. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/task_spec/spec.py#L335-L335) · [TaskSpec protocol API](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/public_api.rst) | +| Task Engine | Interprets instructions and image evidence into candidates, TaskSpec requirements and canonical Semantic Call graphs. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/gen_sim/task_engine/agent.py#L72-L72) · [Task Engine workflow and artifact guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/generative_sim/task_engine.md) · [Task Engine semantic contracts](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.gen_sim.task_engine.rst) | ### Additional modules in specialist views | Module | Responsibility | Evidence and documentation | | --- | --- | --- | -| Antipodal grasp generator | Generates candidate grasp poses through a reusable parallel-jaw interface. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/graspkit/pg_grasp/pose_generator.py#L284-L284) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Newton autograd bridge | Connects Warp tape derivatives to PyTorch action and functional-state gradients. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/diff/bridge.py#L81-L81) · [Newton autograd bridge documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.rst) | -| BatchEntity | Defines shared configuration and instance operations for batched simulation entities. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/common.py#L55-L55) · [BatchEntity documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| URDF collision processor | Replaces mesh collisions with convex pieces and optionally recomputes inertia. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/acd/urdf_modifider.py#L17-L17) · [Convex decomposition documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/convex_decomposition.md) | -| BufferedGymCommandSink | Validates and buffers control commands for incremental Gym demonstration consumption. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/task_program/bridge.py#L864-L864) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [BufferedGymCommandSink documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | -| CompiledTaskProgram | Immutable compilation result with materialized task segments and analysis views. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/compiler/program.py#L1343-L1343) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [CompiledTaskProgram documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | -| Effect evidence | Collects typed evidence from registered providers for semantic effects. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/semantics/evidence.py#L438-L438) · [Effect evidence documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst) | -| ExecutionRunner | Advances atomic skill sessions through observation, command, and clock interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/atomic_skills/runner.py#L367-L367) · [Atomic Skills execution guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/sim/atomic_skills/index.md) · [ExecutionRunner documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_skills.rst) | -| Interactive grasp annotation | Offers browser selection of a graspable mesh region. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/scripts/annotate_grasp.py#L42-L42) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Mesh grasp backend | Coordinates sampling, annotation, collision checks, and caches for one mesh. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/graspkit/pg_grasp/_antipodal_backend.py#L71-L71) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Gripper collision checks | Checks gripper geometry against the target mesh. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py#L39-L39) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Antipodal sampling | Samples opposing surface contacts using mesh ray casting. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/graspkit/pg_grasp/antipodal_sampler.py#L62-L62) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Parallel-jaw gripper configuration | Owns native hand physics, calibration and declared grasp-generator support. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/cfg/gripper.py#L53-L53) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/grasp_generator.rst) | -| Integration catalog | Describes one Task Program integration and validates compilation against its fingerprint. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/integrations/catalog.py#L611-L611) · [Integration catalog documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst) | -| Object backend views | Adapts rigid and articulated object state to backend-neutral Scene batches. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/backends/__init__.py#L19-L19) · [Object backend views documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Parallel execution | Coordinates parallel semantic branches through command and safety interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/runtime/parallel_executor.py#L629-L629) · [Parallel execution documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst) | -| Program loading & validation | Loads bounded JSON or YAML into the canonical Task Program configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/language/loader.py#L17-L17) · [Program loading & validation documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst) | -| SceneRegistry | Binds semantic entity identifiers to scene metadata and runtime providers. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/semantics/scene.py#L1113-L1113) · [SceneRegistry documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/scene_registry.md) | -| SimulationTaskProgramFactory | Binds simulated robots, planners, and services to construct the atomic skill engine. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/integrations/simulation/environment.py#L731-L731) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [Simulation integration API](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst) | -| RobotSkillProfile | Declares robot resources, skill bindings, and effect-assurance capabilities. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/semantics/profiles.py#L1495-L1495) · [RobotSkillProfile documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/robot_profiles.md) | -| EnvironmentStepClock | Maintains execution time on the environment step grid. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/gym/envs/task_program/bridge.py#L351-L351) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [Gym Task Program API](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | -| Surface deformables | Specializes deformable objects for cloth particle sets. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/deformable/surface.py#L28-L28) · [Surface deformables documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| TaskProgramCfg | Declarative task configuration describing intent and execution structure. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/task_program/language/schema.py#L1067-L1067) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/overview/task_program/index.md) · [TaskProgramCfg documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst) | -| Toolkit directory | Standalone grasp sampling, collision-mesh preparation, URDF composition and precision assembly assets. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/__init__.py#L17-L21) · [Toolkits documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/index.rst) · [Precision Assembly guide and native demos](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/precision_assembly.md) | -| URDF components | Processes component links, joints, naming, and mesh references. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/component.py#L87-L87) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| URDF connections | Applies component connection rules and sensor attachment joints. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/connection.py#L30-L30) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| URDF mesh resources | Copies mesh resources and rewrites references for the assembled robot. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/mesh.py#L33-L33) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| URDF sensor attachments | Processes sensor descriptions and attachment metadata for assembly. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/sensor.py#L75-L75) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| URDF file output | Formats and persists the assembled URDF document. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/toolkits/urdf_assembly/file_writer.py#L28-L28) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/toolkits/urdf_assembly.md) | -| Volume deformables | Specializes deformable objects for volumetric soft-body particle sets. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/objects/deformable/volume.py#L36-L36) · [Volume deformables documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | -| Workspace analyzer | Analyzes robot reachability and metrics for reusable workspace caches. | [Source](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/embodichain/lab/sim/motion/workspace/analyzer.py#L182-L182) · [Workspace analyzer documentation](https://github.com/DexForce/EmbodiChain/blob/87d8d9454cd18f19d24434380bcd26bcd0dd376e/docs/source/features/workspace_analyzer/workspace_analyzer.md) | +| Antipodal grasp generator | Generates candidate grasp poses through a reusable parallel-jaw interface. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/graspkit/pg_grasp/pose_generator.py#L284-L284) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Newton autograd bridge | Connects Warp tape derivatives to PyTorch action and functional-state gradients. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/diff/bridge.py#L81-L81) · [Newton autograd bridge documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.rst) | +| BatchEntity | Defines shared configuration and instance operations for batched simulation entities. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/common.py#L55-L55) · [BatchEntity documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| URDF collision processor | Replaces mesh collisions with convex pieces and optionally recomputes inertia. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/acd/urdf_modifider.py#L17-L17) · [Convex decomposition documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/convex_decomposition.md) | +| BufferedGymCommandSink | Validates and buffers control commands for incremental Gym demonstration consumption. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/task_program/bridge.py#L892-L892) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [BufferedGymCommandSink documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | +| CompiledTaskProgram | Immutable compilation result with materialized task segments and analysis views. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/compiler/program.py#L1343-L1343) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [CompiledTaskProgram documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst) | +| Effect evidence | Collects typed evidence from registered providers for semantic effects. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/semantics/evidence.py#L438-L438) · [Effect evidence documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst) | +| ExecutionRunner | Advances atomic skill sessions through observation, command, and clock interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/atomic_skills/runner.py#L367-L367) · [Atomic Skills execution guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/sim/atomic_skills/index.md) · [ExecutionRunner documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_skills.rst) | +| Interactive grasp annotation | Offers browser selection of a graspable mesh region. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/scripts/annotate_grasp.py#L42-L42) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Mesh grasp backend | Coordinates sampling, annotation, collision checks, and caches for one mesh. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/graspkit/pg_grasp/_antipodal_backend.py#L71-L71) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Gripper collision checks | Checks gripper geometry against the target mesh. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/graspkit/pg_grasp/gripper_collision_checker.py#L96-L96) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Antipodal sampling | Samples opposing surface contacts using mesh ray casting. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/graspkit/pg_grasp/antipodal_sampler.py#L62-L62) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Parallel-jaw gripper configuration | Owns native hand physics, calibration and declared grasp-generator support. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/cfg/gripper.py#L53-L53) · [Grasp generation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/grasp_generator.rst) | +| Integration catalog | Describes one Task Program integration and validates compilation against its fingerprint. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/integrations/catalog.py#L617-L617) · [Integration catalog documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst) | +| Object backend views | Adapts rigid and articulated object state to backend-neutral Scene batches. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/backends/__init__.py#L19-L19) · [Object backend views documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Parallel execution | Coordinates parallel semantic branches through command and safety interfaces. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/runtime/parallel_executor.py#L629-L629) · [Parallel execution documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst) | +| Program loading & validation | Loads bounded JSON or YAML into the canonical Task Program configuration. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/language/loader.py#L17-L17) · [Program loading & validation documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst) | +| SceneRegistry | Binds semantic entity identifiers to scene metadata and runtime providers. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/semantics/scene.py#L1113-L1113) · [SceneRegistry documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/scene_registry.md) | +| SimulationTaskProgramFactory | Binds simulated robots, planners, and services to construct the atomic skill engine. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/integrations/simulation/environment.py#L731-L731) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [Simulation integration API](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst) | +| RobotSkillProfile | Declares robot resources, skill bindings, and effect-assurance capabilities. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/semantics/profiles.py#L1495-L1495) · [RobotSkillProfile documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/robot_profiles.md) | +| EnvironmentStepClock | Maintains execution time on the environment step grid. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/gym/envs/task_program/bridge.py#L351-L351) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [Gym Task Program API](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.gym.envs.task_program.rst) | +| Surface deformables | Specializes deformable objects for cloth particle sets. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/deformable/surface.py#L28-L28) · [Surface deformables documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| TaskProgramCfg | Declarative task configuration describing intent and execution structure. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/task_program/language/schema.py#L1067-L1067) · [Task Program guide](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/overview/task_program/index.md) · [TaskProgramCfg documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst) | +| Toolkit directory | Standalone grasp sampling, collision-mesh preparation, URDF composition and precision assembly assets. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/__init__.py#L17-L21) · [Toolkits documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/index.rst) · [Precision Assembly guide and native demos](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/precision_assembly.md) | +| URDF components | Processes component links, joints, naming, and mesh references. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/component.py#L87-L87) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| URDF connections | Applies component connection rules and sensor attachment joints. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/connection.py#L30-L30) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| URDF mesh resources | Copies mesh resources and rewrites references for the assembled robot. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/mesh.py#L33-L33) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| URDF sensor attachments | Processes sensor descriptions and attachment metadata for assembly. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/sensor.py#L75-L75) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| URDF file output | Formats and persists the assembled URDF document. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/toolkits/urdf_assembly/file_writer.py#L28-L28) · [URDF assembly documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/toolkits/urdf_assembly.md) | +| Volume deformables | Specializes deformable objects for volumetric soft-body particle sets. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/objects/deformable/volume.py#L36-L36) · [Volume deformables documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/api_reference/embodichain/embodichain.lab.sim.objects.rst) | +| Workspace analyzer | Analyzes robot reachability and metrics for reusable workspace caches. | [Source](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/embodichain/lab/sim/motion/workspace/analyzer.py#L182-L182) · [Workspace analyzer documentation](https://github.com/DexForce/EmbodiChain/blob/cfdc9f3cf510432ceb8c19af996c746f798a4eb3/docs/source/features/workspace_analyzer/workspace_analyzer.md) | ## Coverage and interpretation From 0557cdcdf251fb98d652c9ca658bd4414f96f3ff Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 04:46:55 +0000 Subject: [PATCH 33/49] feat(expansion): support rolling layouts and measured phase coverage --- .../topics/expansion-engine/workloads.md | 12 +- .../topics/scene-expansion/scene-expansion.md | 6 +- docs/source/api_reference/public_api.rst | 12 ++ embodichain/lab/expansion/__init__.py | 2 + embodichain/lab/expansion/_distribution.py | 1 + embodichain/lab/expansion/_pose_cells.py | 30 +++++ embodichain/lab/expansion/_pose_sampling.py | 16 ++- .../lab/expansion/_pose_sampling_cfg.py | 17 ++- .../lab/expansion/_scene_first_sampling.py | 9 +- embodichain/lab/expansion/distribution.md | 6 + embodichain/lab/expansion/distribution.py | 75 ++++++++++++ .../lab/expansion/task_pose_coverage.py | 103 ++++++++++++++--- .../lab/sim/scene/feasibility/planning.py | 43 +++++-- .../benchmark/expansion/README.scene_first.md | 6 +- .../lab/expansion/test_layout_sampling_sim.py | 97 ++++++++++++++++ .../expansion/test_scene_first_sampling.py | 8 +- .../lab/expansion/test_task_pose_coverage.py | 107 ++++++++++++++++++ 17 files changed, 502 insertions(+), 48 deletions(-) create mode 100644 embodichain/lab/expansion/distribution.py create mode 100644 tests/lab/expansion/test_layout_sampling_sim.py diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index a3a245238c..52e7c65d8e 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -192,6 +192,12 @@ or `workspace_joint`) independently of `scheduling.policy` (`fifo` or `_pose_sampling.py` owns bounded candidate snapshots, source feedback and budgets; `task_pose_coverage.TaskPoseCoverage` implements the session coverage protocol. Measured rigid initial/terminal poses contribute only after native sink receipts. +An optional `pose_coverage.measurements` mapping selects entity states at initial, +terminal or an explicitly named successful segment end. Its grids use the same +names. This supports held-object and multi-stage tasks without creating fake +place-reference entities. `fixed: true` contributes one category inside its +declared grid; tracking noise does not create placement novelty. Proposal ranking +predicts only initial cells; later boundaries require measured T+1 evidence. Separate SceneCase identities aggregate within a declared configuration/grid fingerprint; installation changes remain separate domains. FIFO can omit coverage. @@ -212,7 +218,11 @@ preparation/conditional generation and `RobotFeasibilityBackend`/`plan_task_mode it creates no physics World and owns only the isolated collision-query resources. `layout` and `task_mode` are explicit, validated task declarations. Root layout variables currently use XY only; selected nested members retain declared XY/yaw. -B=1 is checked before runtime creation. A `bounded_pose` job may opt into the +Homogeneous replicas support rolling W times B collection, including eight rows. +Preparation snapshots the common prototype geometry, installation and nominal +full-joint planning start before any row executes. The feasibility adapter uses +an explicit solver row and never treats an active peer's live posture as its +planning start. It creates no additional physical World. A `bounded_pose` job may opt into the same layout/task-mode screens for a controlled comparison without changing ordinary simple-sampling defaults. Screening budgets are bounded and separate from fixed physical quality thresholds. Prepared candidates stay immutable by diff --git a/agent_context/topics/scene-expansion/scene-expansion.md b/agent_context/topics/scene-expansion/scene-expansion.md index 0086ea2467..688c46e261 100644 --- a/agent_context/topics/scene-expansion/scene-expansion.md +++ b/agent_context/topics/scene-expansion/scene-expansion.md @@ -44,8 +44,10 @@ root XY conditions before generating the rest of the layout. See the [conditional layout source contract](../expansion-engine/workloads.md#conditional-layout-proposals-and-task-screening) for selectors and direction scheduling. Explicit `layout` and `task_mode` declarations bind support parents, permissions and -synchronized task stages. Its current path screening requires B=1, including -for a bounded-sampling baseline that opts into the same screens. Declared +synchronized task stages. Homogeneous replicas can share the prepared layout +and frozen nominal planning start within one rolling W times B World; the +feasibility adapter explicitly selects its solver row. A bounded-sampling +baseline can opt into the same screens. Declared workspace caches supply seeds; no cache hit certifies a pose or task. Pure layout queries do not advance the owning World; topology changes invalidate the prepared geometry. This is distinct from offline atlas region validation diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index 0fb8621648..ea8aeca076 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1744,6 +1744,18 @@ and durable episode-boundary recovery. See the offline expansion example. MeasuredTrajectory record_reference_trajectory preview_expansion_comparison + report_expansion_distribution + +Offline distribution reporting validates confirmed native receipts and emits a +complete HTML/JSON/JSONL bundle without opening a physics World. Comparisons +require matching task, robot installation and configured scene domains. + +embodichain.lab.expansion.distribution +------------------------------------- + +.. currentmodule:: embodichain.lab.expansion.distribution + +.. autofunction:: report_expansion_distribution embodichain.lab.expansion.acceptance ------------------------------------ diff --git a/embodichain/lab/expansion/__init__.py b/embodichain/lab/expansion/__init__.py index 97a515b7ed..468fa04777 100644 --- a/embodichain/lab/expansion/__init__.py +++ b/embodichain/lab/expansion/__init__.py @@ -83,6 +83,7 @@ "MeasuredTrajectory", "record_reference_trajectory", "preview_expansion_comparison", + "report_expansion_distribution", ] @@ -144,6 +145,7 @@ def __getattr__(name: str) -> object: "MeasuredTrajectory": "comparison", "record_reference_trajectory": "comparison", "preview_expansion_comparison": "comparison", + "report_expansion_distribution": "distribution", }.get(name, "engine") module = f"{__name__}.{owner}" value = getattr(import_module(module), name) diff --git a/embodichain/lab/expansion/_distribution.py b/embodichain/lab/expansion/_distribution.py index c2c25cc99b..239c514fc9 100644 --- a/embodichain/lab/expansion/_distribution.py +++ b/embodichain/lab/expansion/_distribution.py @@ -269,6 +269,7 @@ def _run( "XY bins cover observed domain only; no feasible-volume denominator.", "TCP is recorded-URDF FK from measured qpos/root plus explicit gripper TCP calibration.", "Orientation bins: canonical SO(3) rotation vectors, 30-degree Cartesian bins, not equal-volume; no symmetry folding.", + "Raw terminal pose bins include tracking variation; receipt-confirmed fixed task categories are a separate coverage metric.", "Joint path length mixes joint coordinates; compare only matching domains.", "Geometry buckets reuse existing 1e-3 descriptor quantization, not clustering.", ] diff --git a/embodichain/lab/expansion/_pose_cells.py b/embodichain/lab/expansion/_pose_cells.py index 2340e7cbc8..c62014829c 100644 --- a/embodichain/lab/expansion/_pose_cells.py +++ b/embodichain/lab/expansion/_pose_cells.py @@ -24,6 +24,36 @@ __all__: list[str] = [] +def _measurements(value: Mapping, grids: Mapping) -> dict: + from copy import deepcopy + + if not isinstance(value, Mapping) or not value or set(value) != set(grids): + raise ValueError("Named coverage measurements require matching grids") + for name, declaration in value.items(): + if ( + not isinstance(name, str) + or not name + or not isinstance(declaration, Mapping) + or set(declaration) - {"entity", "boundary", "segment", "fixed"} + or not {"entity", "boundary"} <= declaration.keys() + or not isinstance(declaration["entity"], str) + or not declaration["entity"] + or declaration["boundary"] not in ("initial", "terminal", "segment_end") + ): + raise ValueError("Invalid named coverage measurement") + if (declaration["boundary"] == "segment_end") != ("segment" in declaration) or ( + "segment" in declaration + and ( + not isinstance(declaration["segment"], str) + or not declaration["segment"] + ) + ): + raise ValueError("Segment coverage requires an explicit segment name") + if "fixed" in declaration and type(declaration["fixed"]) is not bool: + raise ValueError("Coverage fixed flag must be boolean") + return deepcopy(dict(value)) + + def _grid(value: Mapping) -> dict: if not isinstance(value, Mapping) or set(value) != { "lower", diff --git a/embodichain/lab/expansion/_pose_sampling.py b/embodichain/lab/expansion/_pose_sampling.py index 85c41306fe..f4c0090353 100644 --- a/embodichain/lab/expansion/_pose_sampling.py +++ b/embodichain/lab/expansion/_pose_sampling.py @@ -164,7 +164,11 @@ def __init__(self, env, options, *, seed, revision): None if self.coverage_cfg is None else TaskPoseCoverage( - self.domain_id, self.coverage_cfg["entity"], self.coverage_cfg["grids"] + self.domain_id, + self.coverage_cfg.get("entity") + or next(iter(self.coverage_cfg["measurements"].values()))["entity"], + self.coverage_cfg["grids"], + measurements=self.coverage_cfg.get("measurements"), ) ) self.budget = _PoseBudget( @@ -443,9 +447,13 @@ def candidate(self, ordinal): cells = ( () if self.coverage is None - else self.coverage.cells( - poses[self.coverage_cfg["entity"]], - poses[self.coverage_cfg["place_reference"]], + else ( + self.coverage.proposal_cells(poses) + if self.coverage_cfg.get("measurements") is not None + else self.coverage.cells( + poses[self.coverage_cfg["entity"]], + poses[self.coverage_cfg["place_reference"]], + ) ) ) self._events.append( diff --git a/embodichain/lab/expansion/_pose_sampling_cfg.py b/embodichain/lab/expansion/_pose_sampling_cfg.py index c0ae0999ba..b454e134b2 100644 --- a/embodichain/lab/expansion/_pose_sampling_cfg.py +++ b/embodichain/lab/expansion/_pose_sampling_cfg.py @@ -151,12 +151,6 @@ def validate_sampling(value: dict) -> None: "workspace_joint does not consume layout conditions; choose scene_first or a screened bounded_pose baseline" ) if sampling["strategy"] in _LAYOUT_STRATEGIES or "layout" in sampling: - if ( - value["engine"].get("batch_size", 1) - * value["engine"].get("workload_count", 1) - != 1 - ): - raise ValueError("Layout task-path screening currently requires B=1") layout = sampling.get("layout") if ( not isinstance(layout, dict) @@ -303,6 +297,17 @@ def validate_sampling(value: dict) -> None: "task_pose_coverage scheduling requires pose_coverage grids" ) return + if isinstance(coverage, dict) and set(coverage) == {"measurements", "grids"}: + from ._pose_cells import _measurements + + measurements, grids = coverage["measurements"], coverage["grids"] + if not isinstance(grids, dict): + raise ValueError("Named coverage measurements require matching grids") + coverage["measurements"] = _measurements(measurements, grids) + if any(d["entity"] not in value["scene"] for d in measurements.values()): + raise ValueError("Coverage requires declared scene entities") + coverage["grids"] = {k: _grid(v) for k, v in grids.items()} + return if not isinstance(coverage, dict) or set(coverage) != { "entity", "place_reference", diff --git a/embodichain/lab/expansion/_scene_first_sampling.py b/embodichain/lab/expansion/_scene_first_sampling.py index f9a7c20838..b6935d1a83 100644 --- a/embodichain/lab/expansion/_scene_first_sampling.py +++ b/embodichain/lab/expansion/_scene_first_sampling.py @@ -47,8 +47,6 @@ class _LayoutPoseSource(_AdaptivePoseSource): """ def __init__(self, env, options, *, seed, revision): - if env.num_envs != 1: - raise ValueError("Layout task-path screening currently requires B=1") before = self._world_clock(env.sim) self._collision = None super().__init__(env, options, seed=seed, revision=revision) @@ -119,6 +117,7 @@ def __init__(self, env, options, *, seed, revision): f"Task phase names unavailable control part {target.control_part!r}" ) self._entities = {k: np.array(v) for k, v in entities.items()} + self._initial_qpos = None self._anchor_pools = () self._workspace_seconds = self._screening_seconds = 0.0 if self.cfg["strategy"] in _ROBOT_LAYOUT_STRATEGIES: @@ -170,6 +169,11 @@ def bind_program(self, adapter, program): """Keep the declared phase graph and live runtime independent authorities.""" if not tuple(program.iter_segments()): raise ValueError("Layout sampling requires a nonempty task program") + # The owner binds every group before rolling admission. Retain its + # nominal planning start even while another row subsequently executes. + self._initial_qpos = ( + self.env.robot.get_qpos()[0].detach().cpu().double().numpy().copy() + ) @staticmethod def _world_clock(sim): @@ -331,6 +335,7 @@ def _offer_layout(self, candidate, raw, origin): self.budget.cfg, poses, seed=self.seed + raw, + initial_qpos=self._initial_qpos, ) plan = plan_task_mode(self._mode, backend, poses, self.budget) self._task_checks[raw] = [ diff --git a/embodichain/lab/expansion/distribution.md b/embodichain/lab/expansion/distribution.md index d73bfb3343..7cde799567 100644 --- a/embodichain/lab/expansion/distribution.md +++ b/embodichain/lab/expansion/distribution.md @@ -1,5 +1,11 @@ # Task distribution report +Integrators call the lazy public `embodichain.lab.expansion.report_expansion_distribution` +with before/after native jobs, expansion aggregates or workflow directories. It +uses the same receipt reader and report writer as the command below, returns the +HTML path and snapshot identity, and creates no simulation World. Preserve the +complete output directory, including detail pages and JSONL records. + Run from an EmbodiChain environment with the existing artifact reader dependencies: ```bash diff --git a/embodichain/lab/expansion/distribution.py b/embodichain/lab/expansion/distribution.py new file mode 100644 index 0000000000..128d608fe2 --- /dev/null +++ b/embodichain/lab/expansion/distribution.py @@ -0,0 +1,75 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Offline distribution reports from confirmed native collection artifacts.""" + +from __future__ import annotations + +from collections.abc import Sequence +import json +from pathlib import Path + +__all__ = ["report_expansion_distribution"] + + +def report_expansion_distribution( + before: Sequence[str | Path], + after: Sequence[str | Path], + output: str | Path, + *, + entity: str, + cell_size_m: float = 0.01, + minimum: int = 1, +) -> dict: + """Compare matching-domain receipts without creating a simulation World. + + Args: + before: Native jobs, expansion aggregates or workflow run directories. + after: Independent or cumulative matching-domain collection directories. + output: New destination for the complete HTML/JSON/JSONL report bundle. + entity: Recorded rigid entity whose measured states are compared. + cell_size_m: World-XY bin width, selected before examining results. + minimum: Required episode count for observed-bin deficit diagnostics. + + Returns: + Report directory, HTML entry, snapshot identity and confirmed counts. + + Raises: + ValueError: For invalid inputs, mismatched domains or corrupt evidence. + FileExistsError: If the destination already exists. + """ + from ._distribution import _run + from .preview import _inputs + + def jobs(paths): + return _inputs( + [ + Path(p) / "expand" if (Path(p) / "run.json").is_file() else Path(p) + for p in paths + ] + ) + + output = Path(output).expanduser().resolve() + _run(jobs(before), jobs(after), output, entity, cell_size_m, minimum) + report = json.loads((output / "summary.json").read_text()) + return { + "directory": str(output), + "html": str(output / "report.html"), + "snapshot_id": report["snapshot_id"], + "comparison_kind": report["comparison_kind"], + "before": report["before"]["count"], + "after": report["after"]["count"], + } diff --git a/embodichain/lab/expansion/task_pose_coverage.py b/embodichain/lab/expansion/task_pose_coverage.py index 106495c268..a095c3fcba 100644 --- a/embodichain/lab/expansion/task_pose_coverage.py +++ b/embodichain/lab/expansion/task_pose_coverage.py @@ -32,7 +32,7 @@ __all__ = ["TaskPoseCoverage"] -from ._pose_cells import _grid, _pose_cell +from ._pose_cells import _grid, _pose_cell, _measurements class TaskPoseCoverage: @@ -43,20 +43,37 @@ class TaskPoseCoverage: installation and grid, excluding sampled scene poses and RNG seed. entity_uid: Manipulated rigid object whose measured states are counted. grids: Explicit ``pick`` and ``place`` XY/yaw grids in arena coordinates. + measurements: Optional named entity/boundary declarations. Initial, + terminal and named segment-end states are measured independently. + Fixed categories never turn tracking noise into pose novelty. Scene cases keep their existing identities. This adapter aggregates them within one declared experiment, never across separate instances/domains. """ - def __init__(self, domain_id: str, entity_uid: str, grids: Mapping) -> None: + def __init__( + self, + domain_id: str, + entity_uid: str, + grids: Mapping, + *, + measurements: Mapping | None = None, + ) -> None: if not all( type(s) is str and s.strip() == s and s for s in (domain_id, entity_uid) ): raise ValueError("Coverage requires nonempty domain and entity identities") - if not isinstance(grids, Mapping) or set(grids) != {"pick", "place"}: - raise ValueError("Coverage requires pick and place grids") + if not isinstance(grids, Mapping) or not grids: + raise ValueError("Coverage requires explicit grids") + if measurements is None and set(grids) != {"pick", "place"}: + raise ValueError("Legacy coverage requires pick and place grids") + if measurements is not None and set(measurements) != set(grids): + raise ValueError("Coverage measurements must match grid names") self.domain_id, self.entity_uid = domain_id, entity_uid self.grids = {k: _grid(v) for k, v in grids.items()} + self.measurements = ( + None if measurements is None else _measurements(measurements, grids) + ) self._cases: dict[str, tuple[str, str, str]] = {} self._population = None self._pending: dict[str, tuple[str, tuple]] = {} @@ -117,17 +134,43 @@ def reserve(self, episode: ExpertEpisode) -> bool: raise ValueError("Episode scene is outside this coverage domain") if not episode.validation.accepted: return False - states = episode.observations.get(f"rigid/{self.entity_uid}/state") - if ( - states is None - or states.ndim != 2 - or states.shape[0] != len(episode.timestamps) - or states.shape[1] < 7 - ): - raise ValueError("Task coverage requires T+1 measured rigid states") - cells = self.cells( - states[0].detach().cpu().numpy(), states[-1].detach().cpu().numpy() - ) + if self.measurements is None: + states = self._states(episode, self.entity_uid) + cells = self.cells( + states[0].detach().cpu().numpy(), states[-1].detach().cpu().numpy() + ) + else: + measured = [] + for phase, declaration in self.measurements.items(): + states = self._states(episode, declaration["entity"]) + boundary = declaration["boundary"] + index = 0 if boundary == "initial" else len(states) - 1 + if boundary == "segment_end": + segments = [ + s + for s in episode.metadata.get("program_segments", ()) + if s["name"] == declaration["segment"] + ] + if len(segments) != 1 or not segments[0]["success"]: + raise ValueError( + "Coverage requires one successful named segment" + ) + index = int(segments[0]["end_step"]) + if not 0 <= index < len(states): + raise ValueError( + "Coverage segment boundary is outside T+1 states" + ) + cell = _pose_cell( + states[index].detach().cpu().numpy(), self.grids[phase] + ) + if cell is not None: + measured.append( + ( + phase, + *((0, 0, 0) if declaration.get("fixed", False) else cell), + ) + ) + cells = tuple(measured) value = (case_id, cells) previous = self._confirmed.get( episode.commit_id, self._pending.get(episode.commit_id) @@ -138,6 +181,33 @@ def reserve(self, episode: ExpertEpisode) -> bool: self._pending[episode.commit_id] = value return True # Duplicates are valid data; they cannot increase unique coverage. + @staticmethod + def _states(episode: ExpertEpisode, entity: str) -> torch.Tensor: + states = episode.observations.get(f"rigid/{entity}/state") + if ( + states is None + or states.ndim != 2 + or states.shape[0] != len(episode.timestamps) + or states.shape[1] < 7 + or not bool(torch.isfinite(states).all()) + ): + raise ValueError("Task coverage requires finite T+1 measured rigid states") + return states + + def proposal_cells(self, poses: Mapping) -> tuple: + """Predict only declared initial cells; later phases require measurements.""" + if self.measurements is None: + raise ValueError( + "Legacy proposal cells require explicit pick/place references" + ) + return tuple( + (phase, *((0, 0, 0) if declaration.get("fixed", False) else cell)) + for phase, declaration in self.measurements.items() + if declaration["boundary"] == "initial" + and (cell := _pose_cell(poses[declaration["entity"]], self.grids[phase])) + is not None + ) + def confirm(self, case_id: str, commit_id: str) -> None: """Idempotently count the reservation qualified by the session's receipt.""" value = self._confirmed.get(commit_id, self._pending.get(commit_id)) @@ -186,6 +256,7 @@ def state_dict(self) -> dict: "domain_id": self.domain_id, "entity_uid": self.entity_uid, "grids": self.grids, + "measurements": self.measurements, "population": self._population, "cases": self._cases, "pending": self._pending, @@ -198,7 +269,7 @@ def load_state_dict(self, state: Mapping) -> None: data = deepcopy(dict(state)) if data.get("version") != 1 or any( data.get(k) != getattr(self, k) - for k in ("domain_id", "entity_uid", "grids") + for k in ("domain_id", "entity_uid", "grids", "measurements") ): raise ValueError("Coverage checkpoint belongs to another domain/grid") if self._pending or self._confirmed or self._cases: diff --git a/embodichain/lab/sim/scene/feasibility/planning.py b/embodichain/lab/sim/scene/feasibility/planning.py index c871153968..d07d7dec51 100644 --- a/embodichain/lab/sim/scene/feasibility/planning.py +++ b/embodichain/lab/sim/scene/feasibility/planning.py @@ -227,7 +227,7 @@ def plan_task_mode( class RobotFeasibilityBackend: - """Live B=1 Robot adapter with multi-seed IK and full-joint RRT fallback. + """Selected-row Robot adapter with multi-seed IK and full-joint RRT fallback. Args: robot: Prepared robot at the candidate's actual installation. @@ -235,6 +235,9 @@ class RobotFeasibilityBackend: cfg: Bounded branch and discretization settings. entity_poses: Settled arena poses for static and movable scene entities. seed: Candidate-local planner randomness. + env_id: Explicit prototype row for numeric solver and geometry bindings. + initial_qpos: Optional owned nominal full-joint planning start. This avoids + using another rollout's current state during rolling admission. The fallback plans in full joint coordinates, with the same collision checks for straight connections and sampled detours. It does not replace runtime @@ -249,19 +252,37 @@ def __init__( entity_poses: Mapping[str, object], *, seed: int = 0, + env_id: int = 0, + initial_qpos: np.ndarray | None = None, ) -> None: - if robot.get_qpos().shape[0] != 1 or robot.pk_chain is None: + if ( + type(env_id) is not int + or not 0 <= env_id < robot.get_qpos().shape[0] + or robot.pk_chain is None + ): raise UnsupportedFeasibilityError( - "Robot planning requires B=1 and full-link kinematics" + "Robot planning requires a valid selected row and full-link kinematics" ) self.robot, self.collision, self.cfg = robot, collision, cfg + self.env_id = env_id self.joint_names = tuple(robot.joint_names) - self.initial_qpos = robot.get_qpos()[0].detach().cpu().double().numpy().copy() + self.initial_qpos = ( + robot.get_qpos()[env_id].detach().cpu().double().numpy().copy() + if initial_qpos is None + else np.array(initial_qpos, dtype=float, copy=True) + ) + if ( + self.initial_qpos.shape != (len(self.joint_names),) + or not np.isfinite(self.initial_qpos).all() + ): + raise ValueError( + "Planning start must contain finite full-joint coordinates" + ) self.joint_limits = ( - robot.get_qpos_limits()[0].detach().cpu().double().numpy().copy() + robot.get_qpos_limits()[env_id].detach().cpu().double().numpy().copy() ) self._root = ( - robot.get_local_pose(to_matrix=True)[0].detach().cpu().double().numpy() + robot.get_local_pose(to_matrix=True)[env_id].detach().cpu().double().numpy() ) self._entities = {k: np.asarray(v) for k, v in entity_poses.items()} self._rng = np.random.default_rng(seed) @@ -380,7 +401,9 @@ def solutions( solver = self.robot.get_solver(name=target.control_part) live_root = ( self.robot.get_link_pose( - link_name=solver.root_link_name, env_ids=[0], to_matrix=True + link_name=solver.root_link_name, + env_ids=[self.env_id], + to_matrix=True, )[0] .detach() .cpu() @@ -397,7 +420,7 @@ def solutions( budget.check() samples = self.robot.sample_reachable_pose( name=target.control_part, - env_ids=[0], + env_ids=[self.env_id], num_samples=self.cfg.ik_seeds, max_attempts=self.cfg.ik_seeds, generator=torch.Generator(device=self.robot.device).manual_seed( @@ -434,7 +457,7 @@ def solutions( device=self.robot.device, ), name=target.control_part, - env_ids=[0], + env_ids=[self.env_id], return_all_solutions=True, ) budget.check() @@ -484,7 +507,7 @@ def solutions( q[None], dtype=torch.float32, device=self.robot.device ), name=target.control_part, - env_ids=[0], + env_ids=[self.env_id], to_matrix=True, )[0] .detach() diff --git a/scripts/benchmark/expansion/README.scene_first.md b/scripts/benchmark/expansion/README.scene_first.md index 655dcc7f5a..02651c1bf1 100644 --- a/scripts/benchmark/expansion/README.scene_first.md +++ b/scripts/benchmark/expansion/README.scene_first.md @@ -68,8 +68,10 @@ and plans again from the measured prepared scene. it changes preflight effort, not acceptance thresholds. All raw proposals, discarded candidates and IK/planning calls consume the declared budgets. Failed layout or task screening remains preparation rejection and never earns physical -success or a sink receipt. The B=1 path is explicit; batch settings reject before -World construction. Collision queries own no physical World and are released on +success or a sink receipt. Homogeneous W times B replicas share one prepared +prototype and retain a frozen nominal planning start; eight-row collection is +covered by `tests/lab/expansion/test_layout_sampling_sim.py`. Each proposal still +uses the complete task-path screen before normal measured execution. Collision queries own no physical World and are released on normal completion and startup failures. A topology revision invalidates the prepared source instead of silently retaining stale geometry. diff --git a/tests/lab/expansion/test_layout_sampling_sim.py b/tests/lab/expansion/test_layout_sampling_sim.py new file mode 100644 index 0000000000..1baf5423d0 --- /dev/null +++ b/tests/lab/expansion/test_layout_sampling_sim.py @@ -0,0 +1,97 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Real eight-row conditional layout collection and immutable readback.""" + +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys +import pytest + + +def _probe(output: Path, strategy: str) -> None: + import json + import yaml + import torch + from embodichain.lab.expansion import ( + ArtifactEpisodeSink, + load_expansion_episode, + run_task_program_expansion, + report_expansion_distribution, + ) + + torch.set_num_threads(1) + root = Path(__file__).resolve().parents[3] + fixture = ( + root + / "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first" + ) + cfg = yaml.safe_load((fixture / "expansion.yaml").read_text()) + cfg["engine"].update( + workload_count=1, batch_size=8, episodes_per_operator=8, max_attempts=32 + ) + cfg["scene_sampling"].update(strategy=strategy, max_rollouts=32) + path = output / "expansion.yaml" + path.write_text(yaml.safe_dump(cfg)) + result = run_task_program_expansion( + fixture / "task.yaml", path, output / "collection", seed=7 + ) + execution = json.loads((output / "collection/workload-execution.json").read_text()) + assert execution["num_envs"] == 8 and execution["world"]["world_count"] == 1 + group = result["operators"]["object_pose"] + receipts = ArtifactEpisodeSink(group["directory"]).inspect() + assert len(receipts) == group["committed_episodes"] == 8 + selected = set() + for receipt in receipts: + episode = load_expansion_episode(receipt.storage_id) + assert episode.validation.accepted + assert len(episode.timestamps) == len(episode.actions) + 1 + selected.add(episode.metadata["source_env_id"]) + assert selected == set(range(8)) + source = Path(group["directory"]) / "scene-first-checks.json" + checks = json.loads(source.read_text())["phase_checks"] + assert checks and all( + any(c["stage"] == "screening.clock" and c["status"] == "passed" for c in rows) + for rows in checks.values() + ) + report = report_expansion_distribution( + [output / "collection"], + [output / "collection"], + output / "distribution", + entity="cube", + cell_size_m=0.01, + ) + assert report["before"] == report["after"] == 8 + assert report["comparison_kind"] == "cumulative" + + +@pytest.mark.parametrize("strategy", ["scene_first", "robot_first", "bidirectional"]) +def test_conditional_layout_uses_one_world_and_eight_real_rows(tmp_path, strategy): + result = subprocess.run( + [sys.executable, __file__, str(tmp_path), strategy], + env={**os.environ, "EMBODICHAIN_SIM_EXIT_PROCESS": "0"}, + capture_output=True, + text=True, + timeout=600, + ) + assert result.returncode == 0, result.stdout + result.stderr + + +if __name__ == "__main__": + _probe(Path(sys.argv[1]), sys.argv[2]) diff --git a/tests/lab/expansion/test_scene_first_sampling.py b/tests/lab/expansion/test_scene_first_sampling.py index 6564b3eb9d..76c4ce805f 100644 --- a/tests/lab/expansion/test_scene_first_sampling.py +++ b/tests/lab/expansion/test_scene_first_sampling.py @@ -320,7 +320,7 @@ def test_source_obeys_hard_raw_candidate_budget(monkeypatch): assert source.budget.counts["candidates"] == 64 -def test_scene_first_config_rejects_batch_and_unknown_phase_fields_before_runtime(): +def test_scene_first_config_accepts_batch_and_rejects_unknown_phase_fields(): # Reuse a valid source's owned config, without constructing a new World. import yaml from pathlib import Path @@ -331,10 +331,8 @@ def test_scene_first_config_rejects_batch_and_unknown_phase_fields_before_runtim / "extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/expansion.yaml" ) cfg = yaml.safe_load(path.read_text()) - cfg["engine"]["batch_size"] = 4 - with pytest.raises(ValueError, match="B=1"): - validate_sampling(cfg) - cfg["engine"]["batch_size"] = 1 + cfg["engine"]["batch_size"] = 8 + validate_sampling(cfg) cfg["scene_sampling"]["task_mode"]["phases"][0]["unknown"] = True with pytest.raises(ValueError, match="Unknown TaskPhase"): validate_sampling(cfg) diff --git a/tests/lab/expansion/test_task_pose_coverage.py b/tests/lab/expansion/test_task_pose_coverage.py index 2ffb4b10e1..9c008eb475 100644 --- a/tests/lab/expansion/test_task_pose_coverage.py +++ b/tests/lab/expansion/test_task_pose_coverage.py @@ -131,6 +131,113 @@ def test_cells_boundaries_periodicity_and_measured_not_requested_pose(): assert cov.gain((("pick", 0, 2, 1),)) == 0.5 +def test_named_boundaries_use_real_artifacts_and_fixed_categories(tmp_path): + from embodichain.lab.expansion import ArtifactEpisodeSink, load_expansion_episode + from embodichain.lab.expansion.contracts import ( + CandidateIdentity, + ExpertEpisode, + ValidationCheck, + ValidationResult, + ) + + measurements = { + "initial": {"entity": "object", "boundary": "initial"}, + "handover": { + "entity": "object", + "boundary": "segment_end", + "segment": "handover", + "fixed": True, + }, + "handover_pose": { + "entity": "object", + "boundary": "segment_end", + "segment": "handover", + }, + "held": {"entity": "object", "boundary": "terminal", "fixed": True}, + } + grid = grids()["pick"] + cov = TaskPoseCoverage( + "domain", + "object", + {name: grid for name in measurements}, + measurements=measurements, + ) + cov.register_case( + SceneCase("case", "initial", "signature", "task", "robot"), + torch.tensor([[-1.0, 1.0]]), + ("joint",), + None, + ) + sink = ArtifactEpisodeSink(tmp_path / "episodes") + for ordinal, x in enumerate((-0.7, 0.7)): + state = torch.tensor( + [ + [x, 0.1, 0.1, 0, 0, 0, 1], + [0.1, 0.1, 0.1, 0, 0, 0, 1], + [0.1 + ordinal * 0.6, 0.1, 0.1, 0, 0, 0, 1], + ] + ) + episode = ExpertEpisode( + CandidateIdentity( + "case", + "initial", + f"candidate{ordinal}", + "family", + "source", + "v1", + "plan", + ), + {"rigid/object/state": state}, + torch.zeros(2, 1), + torch.tensor([0.0, 0.1, 0.2]), + "qpos", + ValidationResult((ValidationCheck("task", "passed"),)), + f"episode{ordinal}", + f"commit{ordinal}", + metadata={ + "program_segments": [ + { + "name": "handover", + "start_step": 0, + "end_step": 1, + "success": True, + } + ] + }, + ) + assert cov.reserve(episode) + assert cov.phase_counts()["initial"] == ordinal + receipt = sink.submit(episode, submission_id=ordinal) + restored = load_expansion_episode(receipt.storage_id) + assert cov.reserve(restored) + cov.confirm("case", episode.commit_id) + cov.confirm("case", episode.commit_id) + assert cov.phase_counts() == { + "initial": 2, + "handover": 1, + "handover_pose": 1, + "held": 1, + } + assert ("handover_pose", 2, 2, 1) in cov.state_dict()["confirmed"]["commit1"][1] + assert cov.proposal_cells({"object": np.eye(4)}) == (("initial", 2, 2, 1),) + snapshot = cov.state_dict() + restored = TaskPoseCoverage( + "domain", + "object", + {name: grid for name in measurements}, + measurements=measurements, + ) + restored.load_state_dict(snapshot) + assert restored.phase_counts() == cov.phase_counts() + with pytest.raises(ValueError, match="segment name"): + TaskPoseCoverage( + "domain", + "object", + {"bad": grid}, + measurements={"bad": {"entity": "object", "boundary": "segment_end"}}, + ) + + class _Robot: control_parts = {"arm": [0, 1, 2]} device = torch.device("cpu") From 88c2e18503a9beeb3403d6623aba55389b5d09ac Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 05:15:21 +0000 Subject: [PATCH 34/49] fix(packaging): include expansion distribution report template --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index a301c9939e..fde2fea84d 100644 --- a/setup.py +++ b/setup.py @@ -153,7 +153,7 @@ def get_package_data() -> dict[str, list[str]]: ] return { "embodichain": ["VERSION"], - "embodichain.lab.expansion": ["_preview.html"], + "embodichain.lab.expansion": ["_preview.html", "_distribution.html"], "embodichain.data": ["default_materials.json"], "embodichain.compute.kinematics._warp": [ "ssik_LICENSE.txt", From 4132d860105147c1090bfa71ec7cdcae2f259aff Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 05:29:07 +0000 Subject: [PATCH 35/49] docs(expansion): correct distribution API heading --- docs/source/api_reference/public_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api_reference/public_api.rst b/docs/source/api_reference/public_api.rst index ea8aeca076..39bea20b8c 100644 --- a/docs/source/api_reference/public_api.rst +++ b/docs/source/api_reference/public_api.rst @@ -1751,7 +1751,7 @@ complete HTML/JSON/JSONL bundle without opening a physics World. Comparisons require matching task, robot installation and configured scene domains. embodichain.lab.expansion.distribution -------------------------------------- +-------------------------------------- .. currentmodule:: embodichain.lab.expansion.distribution From 65f7d5d63bb36d93de4714c33318c6cb30ec003d Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 05:55:34 +0000 Subject: [PATCH 36/49] feat(expansion): separate nominal scene and proposal seeds --- .../topics/expansion-engine/workloads.md | 6 ++++++ .../lab/expansion/_task_program_config.py | 5 +++++ embodichain/lab/expansion/gym_workloads.py | 20 ++++++++++++++++--- .../lab/expansion/task_program_jobs.py | 1 + embodichain/lab/expansion/workloads.py | 14 ++++++++++++- tests/lab/expansion/test_configured.py | 9 +++++++++ .../lab/expansion/test_layout_sampling_sim.py | 10 ++++++++-- 7 files changed, 59 insertions(+), 6 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 52e7c65d8e..1ef5208038 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -189,6 +189,12 @@ switch devices. Task-facing expansion configs select `scene_sampling.strategy` (`bounded_pose` or `workspace_joint`) independently of `scheduling.policy` (`fifo` or `task_pose_coverage`). Absent settings preserve the legacy bounded sampler. +`engine.nominal_seed` optionally fixes the authored scene reset independently of +the expansion seed. Without it, both retain the historical shared seed. Runtime +candidate streams and proposal streams still use the expansion seed/ordinal; +the reference manifest records both seeds. This prevents a sampler comparison +from silently changing the nominal scene's reset randomization and moving its +declared local domain. Rolling resets use the same explicit nominal reset seed. `_pose_sampling.py` owns bounded candidate snapshots, source feedback and budgets; `task_pose_coverage.TaskPoseCoverage` implements the session coverage protocol. Measured rigid initial/terminal poses contribute only after native sink receipts. diff --git a/embodichain/lab/expansion/_task_program_config.py b/embodichain/lab/expansion/_task_program_config.py index 73c464e8f2..40ff525a1a 100644 --- a/embodichain/lab/expansion/_task_program_config.py +++ b/embodichain/lab/expansion/_task_program_config.py @@ -104,6 +104,7 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: "collection_renderer", "collision_backend", "reuse_idle_rows", + "nominal_seed", }: raise ValueError("Unknown or missing expansion engine settings") engine.setdefault("cpu_threads", 1) @@ -122,6 +123,10 @@ def load_task_program_expansion(path: str | Path) -> dict[str, Any]: engine.setdefault("collision_backend", "newton") if "reuse_idle_rows" in engine and type(engine["reuse_idle_rows"]) is not bool: raise ValueError("engine.reuse_idle_rows must be a boolean") + if "nominal_seed" in engine and ( + type(engine["nominal_seed"]) is not int or engine["nominal_seed"] < 0 + ): + raise ValueError("engine.nominal_seed must be a nonnegative integer") if engine["collection_renderer"] not in ("auto", "rt", "fast-rt", "hybrid"): raise ValueError( "engine.collection_renderer must be auto, rt, fast-rt or hybrid" diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index c8e32ac457..20a58221d2 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -759,7 +759,15 @@ def physical_key(env_id: str, cfg: Any) -> str: writer = ThreadPoolExecutor(max_workers=1, thread_name_prefix="expansion-export") try: cfg = ExpansionRunCfg( - **{**workloads[0].cfg.to_dict(), "batch_size": execution.num_envs} + **{ + **workloads[0].cfg.to_dict(), + "batch_size": execution.num_envs, + "seed": ( + workloads[0].cfg.seed + if execution.nominal_seed is None + else execution.nominal_seed + ), + } ) owner = GymExpansionHost( cfg, @@ -786,7 +794,9 @@ def physical_key(env_id: str, cfg: Any) -> str: # No trajectories are live during this one nominal reset. event.params["allow_partial_envs"] = True events.set_functor_cfg(name, event) - env.reset(seed=execution.seed, options={"save_data": False, "reset_ids": [0]}) + env.reset( + seed=execution.reset_seed, options={"save_data": False, "reset_ids": [0]} + ) # The reference now owns all reset-time scene randomization/settling. # Re-running those functors during row refill could advance live peers # outside the executor and lose measured control boundaries. @@ -810,7 +820,11 @@ def physical_key(env_id: str, cfg: Any) -> str: } _atomic_json( root / "reference-scene.json", - {"seed": execution.seed, "poses_xyzw": nominal}, + { + "seed": execution.reset_seed, + "sampling_seed": execution.seed, + "poses_xyzw": nominal, + }, ) for workload, (raw, environment_cfg) in zip(workloads, configs, strict=True): path = Path(workload.cfg.output_dir) diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index 55af8d08d0..d62af0d1c1 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -361,6 +361,7 @@ def _run_operators( settling_steps=settings["settling_steps"], seed=seed, reuse_idle_rows=settings.get("reuse_idle_rows", False), + nominal_seed=settings.get("nominal_seed"), ) chunks = settings["grasp_nms_chunk_size"] if torch.cuda.is_available() else 2048 with pose_nms_scope(chunk_size=chunks): diff --git a/embodichain/lab/expansion/workloads.py b/embodichain/lab/expansion/workloads.py index bbb27180bc..edbc884b2c 100644 --- a/embodichain/lab/expansion/workloads.py +++ b/embodichain/lab/expansion/workloads.py @@ -92,6 +92,8 @@ class WorkloadExecutionCfg: max_steps: Maximum ordinary controller commands per candidate. settling_steps: Minimum physical substeps before a row becomes active. seed: Base seed; each candidate owns a stream keyed by local ordinal. + nominal_seed: Optional independent reset seed for the authored nominal + scene. Omission preserves the historical coupling to ``seed``. batch_planning: Cooperatively merge compatible native motion/solver calls. reuse_idle_rows: Let unfinished groups borrow otherwise idle rows. A rejected attempt permits one additional competing candidate, bounded @@ -106,6 +108,7 @@ class WorkloadExecutionCfg: seed: int = 0 batch_planning: bool = True reuse_idle_rows: bool = False + nominal_seed: int | None = None def __post_init__(self) -> None: for name in ("workload_count", "batch_size", "max_steps"): @@ -118,6 +121,15 @@ def __post_init__(self) -> None: raise TypeError("batch_planning must be a bool") if type(self.reuse_idle_rows) is not bool: raise TypeError("reuse_idle_rows must be a bool") + if self.nominal_seed is not None and ( + type(self.nominal_seed) is not int or self.nominal_seed < 0 + ): + raise ValueError("nominal_seed must be a nonnegative integer or None") + + @property + def reset_seed(self) -> int: + """Return the declared nominal scene seed, with legacy coupling by default.""" + return self.seed if self.nominal_seed is None else self.nominal_seed @property def num_envs(self) -> int: @@ -400,7 +412,7 @@ def _fill(self) -> None: assignments = tuple(added) before = self.env.sim.physics_step_index result = self.env.reset( - seed=self.cfg.seed, + seed=self.cfg.reset_seed, options={ "save_data": False, "reset_ids": [a.env_id for a in added], diff --git a/tests/lab/expansion/test_configured.py b/tests/lab/expansion/test_configured.py index 94bb78c69f..2f018fb898 100644 --- a/tests/lab/expansion/test_configured.py +++ b/tests/lab/expansion/test_configured.py @@ -42,6 +42,15 @@ def test_task_program_declarations_are_pure_and_protect_contact_phases(tmp_path) value = json.loads(process.stdout) assert (value["engine"]["workload_count"], value["engine"]["batch_size"]) == (2, 1) assert value["trajectory"]["operators"] == ["object_pose", "joint_residual"] + value["engine"]["nominal_seed"] = 7 + nominal = tmp_path / "nominal.yaml" + nominal.write_text(yaml.safe_dump(value)) + assert load_task_program_expansion(nominal)["engine"]["nominal_seed"] == 7 + value["engine"]["nominal_seed"] = True + nominal.write_text(yaml.safe_dump(value)) + with pytest.raises(ValueError, match="nominal_seed"): + load_task_program_expansion(nominal) + value["engine"]["nominal_seed"] = 7 value["trajectory"]["free_phases"]["pick_up"] = ["approach", "lift"] invalid = tmp_path / "protected.yaml" invalid.write_text(yaml.safe_dump(value)) diff --git a/tests/lab/expansion/test_layout_sampling_sim.py b/tests/lab/expansion/test_layout_sampling_sim.py index 1baf5423d0..1c92261536 100644 --- a/tests/lab/expansion/test_layout_sampling_sim.py +++ b/tests/lab/expansion/test_layout_sampling_sim.py @@ -44,15 +44,21 @@ def _probe(output: Path, strategy: str) -> None: ) cfg = yaml.safe_load((fixture / "expansion.yaml").read_text()) cfg["engine"].update( - workload_count=1, batch_size=8, episodes_per_operator=8, max_attempts=32 + workload_count=1, + batch_size=8, + episodes_per_operator=8, + max_attempts=32, + nominal_seed=7, ) cfg["scene_sampling"].update(strategy=strategy, max_rollouts=32) path = output / "expansion.yaml" path.write_text(yaml.safe_dump(cfg)) result = run_task_program_expansion( - fixture / "task.yaml", path, output / "collection", seed=7 + fixture / "task.yaml", path, output / "collection", seed=11 ) execution = json.loads((output / "collection/workload-execution.json").read_text()) + reference = json.loads((output / "collection/reference-scene.json").read_text()) + assert (reference["seed"], reference["sampling_seed"]) == (7, 11) assert execution["num_envs"] == 8 and execution["world"]["world_count"] == 1 group = result["operators"]["object_pose"] receipts = ArtifactEpisodeSink(group["directory"]).inspect() From 657daec6c21a9d8f296dd0f4b5083472e3117845 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 06:00:37 +0000 Subject: [PATCH 37/49] fix(expansion): stabilize installation identity in offline reports --- embodichain/lab/expansion/_distribution.py | 24 +++++++++++++++++++++- embodichain/lab/expansion/distribution.md | 4 ++++ tests/lab/expansion/test_distribution.py | 15 ++++++++++++++ 3 files changed, 42 insertions(+), 1 deletion(-) diff --git a/embodichain/lab/expansion/_distribution.py b/embodichain/lab/expansion/_distribution.py index 239c514fc9..421751f942 100644 --- a/embodichain/lab/expansion/_distribution.py +++ b/embodichain/lab/expansion/_distribution.py @@ -43,6 +43,23 @@ def _cell(pose: list[float], cell_size: float) -> str: return ",".join(str(int(x)) for x in np.floor(np.asarray(pose[:2]) / cell_size)) +def _installation_pose(pose: list[float]) -> list[float]: + """Group installation readout jitter only; never alter recorded/FK evidence.""" + value = np.array(pose, dtype=float, copy=True) + if value.shape != (7,) or not np.isfinite(value).all(): + raise ValueError("Installation requires a finite XYZ/xyzw pose") + norm = np.linalg.norm(value[3:]) + if norm < 1e-12: + raise ValueError("Installation quaternion must be nonzero") + value[3:] /= norm + value = np.round(value, 6) + first = next(v for v in value[[6, 3, 4, 5]] if v != 0) + if first < 0: + value[3:] *= -1 + value[value == 0] = 0.0 + return value.tolist() + + def _motion(points: np.ndarray, times: np.ndarray) -> dict: if points.ndim != 2 or points.shape[0] != len(times) or len(times) < 2: raise ValueError("Motion requires aligned T+1 points and timestamps") @@ -149,7 +166,11 @@ def _read(paths: list[Path], entity: str) -> tuple[list[dict], list[str]]: meta = episode.metadata # Fixed topology, installation and task identity; sampled object poses are features. robot = [ - dict(uid=s["uid"], joints=list(s["joint_names"]), pose=list(s["pose"])) + dict( + uid=s["uid"], + joints=list(s["joint_names"]), + pose=_installation_pose(s["pose"]), + ) for s in meta.get("initial_state", ()) if s["kind"] == "robot" ] @@ -270,6 +291,7 @@ def _run( "TCP is recorded-URDF FK from measured qpos/root plus explicit gripper TCP calibration.", "Orientation bins: canonical SO(3) rotation vectors, 30-degree Cartesian bins, not equal-volume; no symmetry folding.", "Raw terminal pose bins include tracking variation; receipt-confirmed fixed task categories are a separate coverage metric.", + "Installation grouping rounds measured XYZ and canonical normalized xyzw to 1e-6; declared calibration is exact and raw states/FK remain unrounded.", "Joint path length mixes joint coordinates; compare only matching domains.", "Geometry buckets reuse existing 1e-3 descriptor quantization, not clustering.", ] diff --git a/embodichain/lab/expansion/distribution.md b/embodichain/lab/expansion/distribution.md index 7cde799567..65351f0b7d 100644 --- a/embodichain/lab/expansion/distribution.md +++ b/embodichain/lab/expansion/distribution.md @@ -20,6 +20,10 @@ Inputs must be job directories containing `job.json` and confirmed artifact rece Repeated input paths/commit identities do not multiply samples. Conflicting commit identities fail. Output must be new; inputs are never overwritten. Both snapshots must have the same task, robot installation, topology and configured scene domain. +For installation identity only, measured XYZ and sign-canonical normalized xyzw +components are rounded to 1e-6 to avoid splitting one fixed base by readout noise. +Declared robot calibration remains exact in the domain fingerprint. Raw episode +poses, TCP FK and every physical acceptance threshold remain unchanged. Open `report.html`. Select a spatial region or joint-distribution cell to inspect recorded object paths. The evidence panel identifies the full artifact and the diff --git a/tests/lab/expansion/test_distribution.py b/tests/lab/expansion/test_distribution.py index 3e6d07a7a3..7fdcf87c1e 100644 --- a/tests/lab/expansion/test_distribution.py +++ b/tests/lab/expansion/test_distribution.py @@ -20,6 +20,21 @@ from embodichain.lab.expansion._distribution import _motion, _summarize +def test_installation_noise_does_not_split_domain_or_modify_raw_poses(): + from embodichain.lab.expansion._distribution import _installation_pose + + measured = [2.3283064365386963e-10, -3.725290298461914e-9, 0, 0, 0, 0, -1] + raw = list(measured) + assert _installation_pose(measured) == _installation_pose([0, 0, 0, 0, 0, 0, 1]) + assert measured == raw + assert _installation_pose([0.01, 0, 0, 0, 0, 0, 1]) != _installation_pose(measured) + assert _installation_pose([0, 0, 0, 0, 0, -1, -1e-10]) == _installation_pose( + [0, 0, 0, 0, 0, 1, 1e-10] + ) + with pytest.raises(ValueError, match="nonzero"): + _installation_pose([0] * 7) + + def test_motion_density_and_time_are_separate(): a = _motion(np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]), np.array([0.0, 2.0])) b = _motion( From f18d7f7f4788a987650b3f4bfa74ce369e430e4e Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 06:09:24 +0000 Subject: [PATCH 38/49] fix(expansion): enforce task identity and layout admission contracts Share simulator-free layout and feasibility declaration validation. Preserve final parent follower poses, distinguish sampled rejection from invalid authored anchors, retire exhausted warming rows, and record event transport history. --- agent_context/MAP.yaml | 1 + .../topics/expansion-engine/workloads.md | 14 +- .../topics/scene-expansion/scene-expansion.md | 1 + embodichain/lab/_scene_config/__init__.py | 20 + embodichain/lab/_scene_config/feasibility.py | 294 ++++++++++++ embodichain/lab/_scene_config/policy.py | 430 ++++++++++++++++++ embodichain/lab/_scene_config/scene.py | 157 +++++++ embodichain/lab/_scene_config/values.py | 195 ++++++++ embodichain/lab/expansion/_distribution.py | 16 +- embodichain/lab/expansion/_pose_sampling.py | 21 +- .../lab/expansion/_pose_sampling_cfg.py | 73 ++- .../lab/expansion/_robot_first_sampling.py | 67 +-- .../lab/expansion/_scene_first_sampling.py | 34 +- embodichain/lab/expansion/distribution.md | 3 + embodichain/lab/expansion/gym_workloads.py | 17 +- embodichain/lab/sim/scene/_support_grid.py | 39 +- embodichain/lab/sim/scene/_validation.py | 65 +-- .../lab/sim/scene/expansion/_policy.py | 325 +------------ .../lab/sim/scene/expansion/conditions.py | 30 +- .../lab/sim/scene/expansion/contracts.py | 148 +----- embodichain/lab/sim/scene/expansion/layout.py | 65 +-- .../lab/sim/scene/feasibility/_values.py | 133 +----- .../lab/sim/scene/feasibility/contracts.py | 239 +--------- .../lab/sim/scene/feasibility/persistence.py | 48 +- .../task_program/integrations/feasibility.py | 13 +- .../gym/envs/task_program/test_feasibility.py | 38 ++ tests/lab/expansion/test_configured.py | 34 ++ tests/lab/expansion/test_distribution.py | 49 ++ tests/lab/expansion/test_gym_workloads.py | 69 ++- .../expansion/test_scene_first_sampling.py | 47 ++ 30 files changed, 1563 insertions(+), 1122 deletions(-) create mode 100644 embodichain/lab/_scene_config/__init__.py create mode 100644 embodichain/lab/_scene_config/feasibility.py create mode 100644 embodichain/lab/_scene_config/policy.py create mode 100644 embodichain/lab/_scene_config/scene.py create mode 100644 embodichain/lab/_scene_config/values.py diff --git a/agent_context/MAP.yaml b/agent_context/MAP.yaml index 90d9f63338..8f2c36270a 100644 --- a/agent_context/MAP.yaml +++ b/agent_context/MAP.yaml @@ -303,6 +303,7 @@ topics: SimulationSceneExpansionHost, SimulationSceneInitialState, episode_prepare] paths: [topics/scene-expansion/scene-expansion.md] source_of_truth: + - embodichain/lab/_scene_config/ - embodichain/lab/sim/scene/feasibility/ - embodichain/lab/sim/scene/expansion/ - embodichain/lab/task_program/integrations/feasibility.py diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 52e7c65d8e..cfad989c0c 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -88,11 +88,11 @@ After at least the declared physical settling substeps, `activate` captures the initial measured boundary, performs the source's required preparation checks, registers a native candidate and uses `ExpansionEngine.admit_row`. It returns a fresh bridge bound exactly to that row and the environment's control cadence. -Rejected preparation returns None and never earns quota. A warming row whose -admission time budget expires is retired without proposal or receipt; its group -can finish incomplete while already-admitted peers continue and export normally. -The native source also handles expiry during initial-state validation before -atomic session proposal. +Rejected preparation returns None and never earns quota. The native source retires +warming rows when the admission time or independent rollout budget is exhausted. +It records the stop reason before proposal, including exhaustion detected during +initial-state validation. The group can finish incomplete while already-admitted +peers continue and export normally. Settling rows remain controller-active so Gym consumes their explicit reset hold targets. They are not live trajectories: only cursor rows receive source @@ -227,6 +227,10 @@ same layout/task-mode screens for a controlled comparison without changing ordinary simple-sampling defaults. Screening budgets are bounded and separate from fixed physical quality thresholds. Prepared candidates stay immutable by ordinal; failed screening cannot turn into an accepted simple fallback. +Static policy and task-mode decoding use shared simulator-free declarations. +Authored anchors must satisfy the prepared layout domain. An out-of-domain +bounded draw rejects only that proposal. Followers outside the support tree +inherit the final parent's displacement before task screening. `robot_first` anchors one movable support-tree root per proposal from the workspace of a declared `robot_anchors` phase/part target. It uses the target's diff --git a/agent_context/topics/scene-expansion/scene-expansion.md b/agent_context/topics/scene-expansion/scene-expansion.md index 688c46e261..ae6adb910c 100644 --- a/agent_context/topics/scene-expansion/scene-expansion.md +++ b/agent_context/topics/scene-expansion/scene-expansion.md @@ -57,6 +57,7 @@ and does not certify continuous reachable volume. | Request | Owner | |---|---| +| Simulator-free layout policy and feasibility declarations | `embodichain/lab/_scene_config/` | | Shared proposal contracts and fixed source | `embodichain/lab/sim/scene/expansion/` | | Candidate limits and movable entity permissions | `cfg.py` in that package | | Arena poses and proposal identity | `contracts.py` in that package | diff --git a/embodichain/lab/_scene_config/__init__.py b/embodichain/lab/_scene_config/__init__.py new file mode 100644 index 0000000000..b5ff999488 --- /dev/null +++ b/embodichain/lab/_scene_config/__init__.py @@ -0,0 +1,20 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- +"""Scene layout and feasibility declarations with no simulator imports.""" + +from __future__ import annotations + +__all__: list[str] = [] diff --git a/embodichain/lab/_scene_config/feasibility.py b/embodichain/lab/_scene_config/feasibility.py new file mode 100644 index 0000000000..d69e076d71 --- /dev/null +++ b/embodichain/lab/_scene_config/feasibility.py @@ -0,0 +1,294 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- +"""Closed, immutable scene and task feasibility request declarations.""" + +from __future__ import annotations + +from collections.abc import Mapping +from dataclasses import dataclass, fields +from functools import cached_property +import math +from typing import Literal + +from .scene import ScenePoseChange +from .values import _identifier, _rigid_pose, digest, finite, names, poses + +__all__: list[str] = [] + + +_IDENTITY = ( + (1.0, 0.0, 0.0, 0.0), + (0.0, 1.0, 0.0, 0.0), + (0.0, 0.0, 1.0, 0.0), + (0.0, 0.0, 0.0, 1.0), +) + + +@dataclass(frozen=True) +class PoseSearchVariable: + """One XY/yaw displacement applied to a scene group or robot installation. + + Args: + name: Unique variable name. + kind: ``scene`` or ``robot``; robot members are physical robot UIDs. + reference_pose: Group-to-arena Z-up transform, including mounting height. + lower: Lower XY metre / yaw radian displacement bounds. + upper: Upper displacement bounds; equal endpoints fix a parameter. + members: Member UID to member-to-group transforms. All members move + together, preserving dual-arm mounting and support-group relations. + """ + + name: str + kind: Literal["scene", "robot"] + reference_pose: tuple + lower: tuple[float, float, float] + upper: tuple[float, float, float] + members: Mapping[str, tuple] + + def __post_init__(self) -> None: + _identifier(self.name, "variable name") + if self.kind not in ("scene", "robot"): + raise ValueError("variable kind must be scene or robot") + object.__setattr__(self, "reference_pose", _rigid_pose(self.reference_pose)) + lo, hi = finite(self.lower, "lower"), finite(self.upper, "upper") + if len(lo) != 3 or len(hi) != 3 or any(a > b for a, b in zip(lo, hi)): + raise ValueError("bounds require three ordered XY/yaw coordinates") + if hi[2] - lo[2] > 2 * math.pi + 1e-10: + raise ValueError("yaw interval must span at most one turn") + object.__setattr__(self, "lower", lo) + object.__setattr__(self, "upper", hi) + object.__setattr__(self, "members", poses(self.members)) + if not self.members: + raise ValueError("variables require explicit member UIDs") + + +@dataclass(frozen=True) +class PhaseTarget: + """One simultaneous TCP target in an explicit arena or entity frame. + + Args: + control_part: Explicit solver name, preserving custom names. + pose: TCP-to-frame rigid transform. + frame_uid: Entity frame UID, or ``None`` for the arena frame. + """ + + control_part: str + pose: tuple + frame_uid: str | None = None + + def __post_init__(self) -> None: + _identifier(self.control_part, "control_part") + object.__setattr__(self, "pose", _rigid_pose(self.pose)) + if self.frame_uid is not None: + _identifier(self.frame_uid, "frame_uid") + + +@dataclass(frozen=True) +class HeldObject: + """Rigid attachment during travel; never a physical-success assertion. + + Args: + entity_uid: Held object UID. + control_part: Owner TCP/control part. + tcp_from_object: Object-to-TCP transform used by collision FK. + """ + + entity_uid: str + control_part: str + tcp_from_object: tuple = _IDENTITY + + def __post_init__(self) -> None: + _identifier(self.entity_uid, "held entity") + _identifier(self.control_part, "held owner") + object.__setattr__(self, "tcp_from_object", _rigid_pose(self.tcp_from_object)) + + +@dataclass(frozen=True) +class TaskPhase: + """A synchronized stage and its explicit planning-state transition. + + Args: + phase_id: Stable stage identity. + targets: Simultaneous targets, at most one per control part. + dependencies: Predecessors; input order must be a topological order. + held_objects: Attachments during incoming motion, one owner per object. + allowed_contacts: Physical collision IDs allowed to touch in this stage. + resulting_poses: Projected object states after this stage, used only for + subsequent planning; runtime must still read fresh physical state. + joint_targets: Explicit joint-name commands, e.g. open/closed fingers. + """ + + phase_id: str + targets: tuple[PhaseTarget, ...] = () + dependencies: tuple[str, ...] = () + held_objects: tuple[HeldObject, ...] = () + allowed_contacts: tuple[tuple[str, str], ...] = () + resulting_poses: tuple[ScenePoseChange, ...] = () + joint_targets: tuple[tuple[str, float], ...] = () + + def __post_init__(self) -> None: + _identifier(self.phase_id, "phase_id") + for attr, cls in ( + ("targets", PhaseTarget), + ("held_objects", HeldObject), + ("resulting_poses", ScenePoseChange), + ): + values = tuple(getattr(self, attr)) + if any(not isinstance(v, cls) for v in values): + raise TypeError(f"{attr} contains an invalid contract") + object.__setattr__(self, attr, values) + names([v.control_part for v in self.targets], "phase target parts") + names([v.entity_uid for v in self.held_objects], "held objects") + names([v.entity_uid for v in self.resulting_poses], "resulting poses") + object.__setattr__( + self, "dependencies", names(self.dependencies, "dependencies") + ) + pairs = tuple( + tuple(sorted(names(pair, "contact pair"))) for pair in self.allowed_contacts + ) + if any(len(p) != 2 for p in pairs) or len(set(pairs)) != len(pairs): + raise ValueError("allowed contacts require unique distinct pairs") + object.__setattr__(self, "allowed_contacts", pairs) + joints = tuple( + (_identifier(k, "joint target"), finite((v,), "joint target")[0]) + for k, v in self.joint_targets + ) + names([k for k, _ in joints], "joint targets") + object.__setattr__(self, "joint_targets", joints) + + +@dataclass(frozen=True) +class TaskOperationMode: + """One permitted grasp/assignment/handover branch of the original task.""" + + mode_id: str + phases: tuple[TaskPhase, ...] + + def __post_init__(self) -> None: + _identifier(self.mode_id, "mode_id") + values = tuple(self.phases) + if not values or any(not isinstance(v, TaskPhase) for v in values): + raise ValueError("modes require explicit task phases") + names([v.phase_id for v in values], "phase IDs") + seen = set() + for phase in values: + if not set(phase.dependencies) <= seen: + raise ValueError("phases must be in dependency order without cycles") + seen.add(phase.phase_id) + object.__setattr__(self, "phases", values) + + +@dataclass(frozen=True) +class TaskFeasibilityRequest: + """Versioned fixed semantics, robot, scene, and allowed joint search domain. + + Args: + task_id: Semantic identity including original roles/goals/invariants. + robot_profile_id: Robot, tool and calibrated configuration identity. + policy_id: Planner/runtime policy version. + validator_id: Measured acceptance version. + parent_scene_id: Base scene revision/content identity. + entity_poses: Authored arena poses, including every variable member. + variables: Permitted scene and mounting changes. + modes: Allowed operation modes, preserving resource constraints. + """ + + task_id: str + robot_profile_id: str + policy_id: str + validator_id: str + parent_scene_id: str + entity_poses: Mapping[str, tuple] + variables: tuple[PoseSearchVariable, ...] + modes: tuple[TaskOperationMode, ...] + + def __post_init__(self) -> None: + for key in ( + "task_id", + "robot_profile_id", + "policy_id", + "validator_id", + "parent_scene_id", + ): + _identifier(getattr(self, key), key) + object.__setattr__(self, "entity_poses", poses(self.entity_poses)) + variables, modes = tuple(self.variables), tuple(self.modes) + if any(not isinstance(v, PoseSearchVariable) for v in variables): + raise TypeError("variables require PoseSearchVariable values") + if not modes or any(not isinstance(v, TaskOperationMode) for v in modes): + raise ValueError("request requires explicit operation modes") + names([v.name for v in variables], "variable names") + members = [k for v in variables for k in v.members] + names(members, "variable members") + if not set(members) <= self.entity_poses.keys(): + raise ValueError("variable members must exist in the authored scene") + names([v.mode_id for v in modes], "mode IDs") + for mode in modes: + for phase in mode.phases: + referenced = { + t.frame_uid for t in phase.targets if t.frame_uid is not None + } + referenced |= {h.entity_uid for h in phase.held_objects} + referenced |= {p.entity_uid for p in phase.resulting_poses} + if not referenced <= self.entity_poses.keys(): + raise ValueError("phase refers to an undeclared entity") + object.__setattr__(self, "variables", variables) + object.__setattr__(self, "modes", modes) + + @cached_property + def request_id(self) -> str: + """Return the content identity of all fixed conditions and permissions.""" + return digest(self) + + +def _closed(cls: type, value: Mapping[str, object]) -> dict: + if not isinstance(value, Mapping): + raise ValueError(f"{cls.__name__} requires a mapping") + unknown = set(value) - {f.name for f in fields(cls)} + if unknown: + raise ValueError(f"Unknown {cls.__name__} fields: {sorted(unknown)}") + return dict(value) + + +def request_from_mapping(value: Mapping[str, object]) -> TaskFeasibilityRequest: + """Decode a provider-independent request through closed production contracts. + + Args: + value: JSON/YAML task, scene, mounting and phase declarations. + Returns: + Validated immutable request. No dotted import or model client is loaded. + """ + data = _closed(TaskFeasibilityRequest, value) + data["variables"] = tuple( + PoseSearchVariable(**_closed(PoseSearchVariable, v)) for v in data["variables"] + ) + modes = [] + for mode in data["modes"]: + m = _closed(TaskOperationMode, mode) + phases = [] + for phase in m["phases"]: + p = _closed(TaskPhase, phase) + for key, cls in ( + ("targets", PhaseTarget), + ("held_objects", HeldObject), + ("resulting_poses", ScenePoseChange), + ): + p[key] = tuple(cls(**_closed(cls, v)) for v in p.get(key, ())) + phases.append(TaskPhase(**p)) + m["phases"] = tuple(phases) + modes.append(TaskOperationMode(**m)) + data["modes"] = tuple(modes) + return TaskFeasibilityRequest(**data) diff --git a/embodichain/lab/_scene_config/policy.py b/embodichain/lab/_scene_config/policy.py new file mode 100644 index 0000000000..acbb6342da --- /dev/null +++ b/embodichain/lab/_scene_config/policy.py @@ -0,0 +1,430 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Source-independent policies for bounded scene layout sampling.""" + +from __future__ import annotations +from collections.abc import Mapping +from copy import deepcopy +from dataclasses import MISSING +import math +from typing import Any, TYPE_CHECKING +from embodichain.utils import configclass + +if TYPE_CHECKING: + from shapely.geometry import Polygon, MultiPolygon + +__all__: list[str] = [] + + +@configclass +class MemberRandomizationCfg: + """One non-root member's displacement bounds in its parent support frame. + + ``xy_offset_bounds_m`` is ``[[min_x, min_y], [max_x, max_y]]`` relative + to the original entity origin; ``None`` samples the complete support area. + Yaw is a continuous increment around the support normal, retaining tilt. + """ + + xy_offset_bounds_m: list[list[float]] | None = None + yaw_delta_range_deg: list[float] = [-180.0, 180.0] + + +@configclass +class SupportOverrideCfg: + """Explicit parent-local support frame and GeoJSON Polygon/MultiPolygon. + + The proper rigid ``parent_from_support`` matrix locates the support plane + at support Z=0 in the parent local Z-up geometry after asset scaling. Its polygon must be covered by actual coplanar mesh faces. + """ + + parent_from_support: list[list[float]] = MISSING + polygon: dict = MISSING + + +@configclass +class IntraGroupRandomizationCfg: + """Explicit member selection and conservative support geometry settings. + + Fixed members follow their parent. Clearances and grid resolution are in + metres. Overrides are keyed by parent UID, independently of target order. + """ + + targets: dict[str, MemberRandomizationCfg] = {} + boundary_margin_m: float = 0.002 + sibling_margin_m: float = 0.002 + support_gap_m: float = 0.001 + grid_resolution_m: float = 0.001 + support_overrides: dict[str, SupportOverrideCfg] = {} + + +def _validate_backend(*, backend: str, device: str, batch_size: int) -> None: + """Validate execution controls without initializing CUDA or reading assets.""" + if backend not in ("slsqp", "batched"): + raise ValueError("backend must be slsqp or batched.") + if not isinstance(device, str) or not ( + device == "cpu" + or device == "cuda" + or ( + device.startswith("cuda:") and device[5:].isascii() and device[5:].isdigit() + ) + ): + raise ValueError("device must be cpu, cuda, or cuda:N.") + if backend == "slsqp" and device != "cpu": + raise ValueError( + "The slsqp backend runs on CPU; use backend: batched for CUDA." + ) + if type(batch_size) is not int or batch_size < 1: + raise ValueError("batch_size must be a positive integer.") + + +def _validate_generation_parameters( + *, seed: int, candidate_count: int, max_attempts: int, collision_margin_m: float +) -> None: + """Validate YAML values and Python overrides before accessing scene files.""" + for name, value, minimum in ( + ("seed", seed, 0), + ("candidate_count", candidate_count, 1), + ("max_attempts", max_attempts, 1), + ): + if type(value) is not int or value < minimum: + raise ValueError(f"{name} must be an integer >= {minimum}.") + if candidate_count > max_attempts: + raise ValueError("max_attempts must be at least candidate_count.") + if type(collision_margin_m) not in (int, float) or collision_margin_m < 0: + raise ValueError("collision_margin_m must be finite and nonnegative.") + try: + finite = math.isfinite(collision_margin_m) + except OverflowError: + finite = False + if not finite: + raise ValueError("collision_margin_m must be finite and nonnegative.") + + +def _mapping(value: Any, *, name: str, allowed: set[str]) -> dict[str, Any]: + if not isinstance(value, dict): + raise ValueError(f"{name} must be a mapping.") + unknown = set(value) - allowed + if unknown: + raise ValueError(f"Unknown {name} fields: {', '.join(sorted(unknown))}.") + return value + + +def _decode_intra(value: Any) -> IntraGroupRandomizationCfg | None: + """Strictly decode nested YAML mappings, also used for persisted policies.""" + if value is None: + return None + root = _mapping( + value, + name="intra_group", + allowed={ + "targets", + "boundary_margin_m", + "sibling_margin_m", + "support_gap_m", + "grid_resolution_m", + "support_overrides", + }, + ) + targets = root.get("targets", {}) + if not isinstance(targets, dict): + raise ValueError("targets must be a mapping.") + decoded = {} + for uid, target in targets.items(): + if not isinstance(uid, str) or not uid.strip(): + raise ValueError("Target UIDs must be nonempty strings.") + item = _mapping( + target, + name=f"target {uid}", + allowed={"xy_offset_bounds_m", "yaw_delta_range_deg"}, + ) + decoded[uid] = MemberRandomizationCfg(**item) + overrides = root.get("support_overrides", {}) + if not isinstance(overrides, dict): + raise ValueError("support_overrides must be a mapping.") + override_cfg = {} + for uid, override in overrides.items(): + item = _mapping( + override, + name=f"support override {uid}", + allowed={"parent_from_support", "polygon"}, + ) + if set(item) != {"parent_from_support", "polygon"}: + raise ValueError("Support overrides require a transform and polygon.") + override_cfg[uid] = SupportOverrideCfg(**item) + cfg = IntraGroupRandomizationCfg( + **{k: v for k, v in root.items() if k not in ("targets", "support_overrides")}, + targets=decoded, + support_overrides=override_cfg, + ) + _validate_intra(cfg) + return cfg + + +def _read_support_polygon(value: object) -> Polygon | MultiPolygon: + """Decode finite XY GeoJSON before accessing any scene assets.""" + import numpy as np + import shapely + from shapely.geometry import Polygon, MultiPolygon, shape + + if not isinstance(value, dict) or value.get("type") not in ( + "Polygon", + "MultiPolygon", + ): + raise ValueError( + "Support polygon must be a GeoJSON Polygon or MultiPolygon mapping." + ) + try: + polygon = shape(value) + except ( + AttributeError, + KeyError, + IndexError, + TypeError, + ValueError, + OverflowError, + shapely.errors.GEOSException, + ) as exc: + raise ValueError("Support polygon has invalid GeoJSON coordinates.") from exc + if ( + not isinstance(polygon, (Polygon, MultiPolygon)) + or polygon.is_empty + or polygon.has_z + or not np.isfinite(shapely.get_coordinates(polygon)).all() + or not polygon.is_valid + or polygon.area <= 0 + ): + raise ValueError( + "Support polygon must contain a valid nonempty finite XY area." + ) + return polygon + + +def _validate_intra(cfg: IntraGroupRandomizationCfg) -> None: + import numpy as np + + if not isinstance(cfg, IntraGroupRandomizationCfg): + raise ValueError("intra_group must be an IntraGroupRandomizationCfg.") + cfg.validate() + if not isinstance(cfg.targets, dict) or not isinstance(cfg.support_overrides, dict): + raise ValueError("targets and support_overrides must be mappings.") + for field in ( + "boundary_margin_m", + "sibling_margin_m", + "support_gap_m", + "grid_resolution_m", + ): + value = getattr(cfg, field) + try: + finite = type(value) in (int, float) and math.isfinite(value) + except OverflowError: + finite = False + if not finite or value < 0 or (field == "grid_resolution_m" and value == 0): + raise ValueError( + f"{field} must be finite and {'positive' if field == 'grid_resolution_m' else 'nonnegative'}." + ) + for uid, item in cfg.targets.items(): + if ( + not isinstance(uid, str) + or not uid + or not isinstance(item, MemberRandomizationCfg) + ): + raise ValueError("targets must map UIDs to MemberRandomizationCfg.") + yaw = np.asarray(item.yaw_delta_range_deg) + if ( + yaw.shape != (2,) + or yaw.dtype.kind not in "fi" + or not np.isfinite(yaw).all() + or yaw[0] > yaw[1] + or not np.isfinite(yaw[1] - yaw[0]) + ): + raise ValueError( + "yaw_delta_range_deg requires finite ordered bounds and width." + ) + if item.xy_offset_bounds_m is not None: + xy = np.asarray(item.xy_offset_bounds_m) + if ( + xy.shape != (2, 2) + or xy.dtype.kind not in "fi" + or not np.isfinite(xy).all() + or np.any(xy[0] > xy[1]) + ): + raise ValueError( + "xy_offset_bounds_m requires finite ordered lower/upper XY corners." + ) + for uid, override in cfg.support_overrides.items(): + if ( + not isinstance(uid, str) + or not uid + or not isinstance(override, SupportOverrideCfg) + ): + raise ValueError("support_overrides must map UIDs to SupportOverrideCfg.") + override.validate() + try: + _read_support_polygon(override.polygon) + except ValueError as exc: + raise ValueError(f"Support override {uid!r}: {exc}") from exc + try: + matrix = np.asarray(override.parent_from_support, dtype=float) + except (TypeError, ValueError, OverflowError) as exc: + raise ValueError( + "parent_from_support must contain finite numeric values." + ) from exc + if ( + matrix.shape != (4, 4) + or not np.isfinite(matrix).all() + or not np.array_equal(matrix[3], [0, 0, 0, 1]) + or not np.allclose( + matrix[:3, :3].T @ matrix[:3, :3], np.eye(3), atol=1e-8, rtol=0 + ) + or not np.isclose(np.linalg.det(matrix[:3, :3]), 1, atol=1e-8, rtol=0) + ): + raise ValueError("parent_from_support must be a proper rigid transform.") + + +def _intra_payload(cfg: IntraGroupRandomizationCfg) -> dict: + """Serialize only documented settings, independent of configclass internals.""" + return deepcopy( + { + "targets": { + uid: { + "xy_offset_bounds_m": item.xy_offset_bounds_m, + "yaw_delta_range_deg": list(item.yaw_delta_range_deg), + } + for uid, item in sorted(cfg.targets.items()) + }, + **{ + key: float(getattr(cfg, key)) + for key in ( + "boundary_margin_m", + "sibling_margin_m", + "support_gap_m", + "grid_resolution_m", + ) + }, + "support_overrides": { + uid: { + "parent_from_support": item.parent_from_support, + "polygon": item.polygon, + } + for uid, item in sorted(cfg.support_overrides.items()) + }, + } + ) + + +@configclass +class SceneRandomizationPolicyCfg: + """Geometric policy independent of scene files and runtime lifecycles. + + Args: + backend: Explicit numeric backend; the shared interface uses batched sampling. + device: CPU or CUDA tensor device. + batch_size: Maximum logical proposals evaluated together. + collision_margin_m: Minimum group AABB separation in metres. + randomize_groups: Sample permitted group-root XY translations. + group_targets: Root UIDs to move; None selects all permitted roots. + group_xy_offset_bounds_m: Optional per-root arena XY displacement bounds. + intra_group: Selected non-root XY/yaw changes and support settings. + """ + + backend: str = "batched" + device: str = "cpu" + batch_size: int = 4096 + collision_margin_m: float = 0.02 + randomize_groups: bool = True + group_targets: tuple[str, ...] | None = None + group_xy_offset_bounds_m: dict[str, list[list[float]]] = {} + intra_group: IntraGroupRandomizationCfg | None = None + + +@configclass +class SceneRandomizationJobCfg: + """Bounded caller-owned generation settings and output representation. + + Args: + policy: Source-independent geometric sampling policy. + seed: Addressed generation seed. + candidate_count: Requested valid layouts. + max_attempts: Whole-layout proposal budget. + layout_storage: JSON or packed candidate storage. + """ + + policy: SceneRandomizationPolicyCfg = SceneRandomizationPolicyCfg() + seed: int = 0 + candidate_count: int = 10 + max_attempts: int = 1000 + layout_storage: str = "packed" + + +def _policy_data(cfg: SceneRandomizationPolicyCfg | Mapping) -> dict: + if isinstance(cfg, Mapping): + raw = dict(cfg) + cfg = SceneRandomizationPolicyCfg(**raw) + if not isinstance(cfg, SceneRandomizationPolicyCfg): + raise TypeError("policy must be a SceneRandomizationPolicyCfg or mapping") + cfg = cfg.copy() + cfg.validate() + _validate_backend(backend=cfg.backend, device=cfg.device, batch_size=cfg.batch_size) + if cfg.backend != "batched": + raise ValueError( + "The source-independent layout API supports backend='batched'." + ) + _validate_generation_parameters( + seed=0, + candidate_count=1, + max_attempts=1, + collision_margin_m=cfg.collision_margin_m, + ) + if type(cfg.randomize_groups) is not bool: + raise ValueError("randomize_groups must be a boolean.") + intra = cfg.intra_group + if isinstance(intra, dict) or intra is None: + intra = _decode_intra(intra) + if intra is None: + intra = IntraGroupRandomizationCfg() + _validate_intra(intra) + if not isinstance(cfg.group_xy_offset_bounds_m, dict): + raise ValueError("group_xy_offset_bounds_m must map root UIDs to XY bounds.") + for uid, bounds in cfg.group_xy_offset_bounds_m.items(): + if bounds is None: + raise ValueError( + "Root XY bounds must be explicit lower/upper corners; omit unbounded roots." + ) + _decode_intra( + { + "targets": { + uid: {"xy_offset_bounds_m": bounds, "yaw_delta_range_deg": [0, 0]} + } + } + ) + if cfg.group_xy_offset_bounds_m and not cfg.randomize_groups: + raise ValueError("Root XY bounds require randomize_groups=True.") + if cfg.group_targets is not None and ( + isinstance(cfg.group_targets, str) + or len(set(cfg.group_targets)) != len(cfg.group_targets) + ): + raise ValueError("group_targets must contain unique root UIDs.") + return { + "backend": cfg.backend, + "device": cfg.device, + "batch_size": cfg.batch_size, + "collision_margin_m": float(cfg.collision_margin_m), + "randomize_groups": cfg.randomize_groups, + "group_targets": None if cfg.group_targets is None else list(cfg.group_targets), + "group_xy_offset_bounds_m": deepcopy(cfg.group_xy_offset_bounds_m), + "intra_group": _intra_payload(intra), + } diff --git a/embodichain/lab/_scene_config/scene.py b/embodichain/lab/_scene_config/scene.py new file mode 100644 index 0000000000..e22e38fecc --- /dev/null +++ b/embodichain/lab/_scene_config/scene.py @@ -0,0 +1,157 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Immutable scene proposals, independent of task and execution lifecycles.""" + +from __future__ import annotations + +from dataclasses import dataclass +import hashlib +import json + +__all__: list[str] = [] + + +from .values import _identifier, _nonnegative_integer, _rigid_pose + + +def _variant_id( + parent_scene_id: str, + seed: int, + ordinal: int, + pose_changes: tuple, + metadata: tuple, +) -> str: + """Hash already validated, canonically ordered proposal values.""" + payload = { + "schema": "scene-variant/v1", + "parent_scene_id": parent_scene_id, + "seed": seed, + "ordinal": ordinal, + "pose_changes": pose_changes, + "metadata": metadata, + } + encoded = json.dumps( + payload, sort_keys=True, separators=(",", ":"), allow_nan=False + ).encode("utf-8") + return "scene-variant:" + hashlib.sha256(encoded).hexdigest() + + +@dataclass(frozen=True) +class ScenePoseChange: + """A proposed pose for one existing physical entity. + + Args: + entity_uid: Stable physical entity UID, independent of environment slots. + arena_pose: Homogeneous 4x4 transform from the entity frame into its + local Z-up arena frame. Inputs are copied into immutable tuples. + + .. attention:: + An arena pose excludes replication offsets. The host converts it to + backend coordinates when applying the candidate. This contract does + not establish support, collision freedom, or manipulation feasibility. + """ + + entity_uid: str + arena_pose: tuple[tuple[float, ...], ...] + + def __post_init__(self) -> None: + _identifier(self.entity_uid, "entity_uid") + object.__setattr__(self, "arena_pose", _rigid_pose(self.arena_pose)) + + +@dataclass(frozen=True) +class SceneVariant: + """An immutable scene proposal with reproducible proposal identity. + + Args: + parent_scene_id: Content/revision identity of the original scene. + seed: Nonnegative proposal-generation seed. + ordinal: Nonnegative position in the candidate source. + pose_changes: Unique existing entities and their proposed arena poses. + metadata: Unique string key/value provenance entries. Entries and pose + changes are sorted so equivalent input ordering has one identity. + + .. attention:: + ``variant_id`` identifies a proposal, not a settled initial state or a + successful execution. Hosts record those identities and evidence + separately. Metadata describes provenance, not executable operations. + Since ``ordinal`` participates in the hash, consuming the same layout + at a different source position changes ``variant_id``. File-backed + consumers should retain the original layout identity and proposal + ordinal in metadata for provenance across selection orders; this ID + is not a geometry-only deduplication key. + """ + + parent_scene_id: str + seed: int + ordinal: int + pose_changes: tuple[ScenePoseChange, ...] + metadata: tuple[tuple[str, str], ...] = () + + def __post_init__(self) -> None: + _identifier(self.parent_scene_id, "parent_scene_id") + _nonnegative_integer(self.seed, "seed") + _nonnegative_integer(self.ordinal, "ordinal") + try: + changes = tuple(self.pose_changes) + except TypeError as exc: + raise ValueError( + "pose_changes must contain ScenePoseChange values" + ) from exc + if any(not isinstance(change, ScenePoseChange) for change in changes): + raise ValueError("pose_changes must contain ScenePoseChange values") + if len({change.entity_uid for change in changes}) != len(changes): + raise ValueError("pose_changes must contain unique entity UIDs") + object.__setattr__( + self, + "pose_changes", + tuple(sorted(changes, key=lambda change: change.entity_uid)), + ) + try: + entries = tuple(self.metadata) + if any(isinstance(entry, str) for entry in entries): + raise ValueError("metadata must contain string key/value pairs") + metadata = tuple(tuple(entry) for entry in entries) + except TypeError as exc: + raise ValueError("metadata must contain string key/value pairs") from exc + if any(len(entry) != 2 for entry in metadata): + raise ValueError("metadata must contain string key/value pairs") + for key, value in metadata: + _identifier(key, "metadata key") + if not isinstance(value, str): + raise ValueError("metadata values must be strings") + if len({key for key, _ in metadata}) != len(metadata): + raise ValueError("metadata must contain unique keys") + object.__setattr__(self, "metadata", tuple(sorted(metadata))) + + @property + def variant_id(self) -> str: + """Return a stable identity including geometry, source, seed, and ordinal. + + Returns: + SHA-256 identity independent of Python hash randomization and + temporary physical environment assignments. + """ + return _variant_id( + self.parent_scene_id, + self.seed, + self.ordinal, + tuple( + (change.entity_uid, change.arena_pose) for change in self.pose_changes + ), + self.metadata, + ) diff --git a/embodichain/lab/_scene_config/values.py b/embodichain/lab/_scene_config/values.py new file mode 100644 index 0000000000..53efdf7eb2 --- /dev/null +++ b/embodichain/lab/_scene_config/values.py @@ -0,0 +1,195 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- +"""Private canonical value validation for feasibility artifacts.""" + +from __future__ import annotations + +from collections.abc import Mapping +from dataclasses import fields, is_dataclass +import hashlib +import json +import math +from numbers import Real +from enum import Enum +import numpy as np +import sys +from pathlib import Path +from types import MappingProxyType + +__all__ = [] + + +def _identifier(value: str, name: str) -> str: + if not isinstance(value, str) or not value or value.strip() != value: + raise ValueError(f"{name} must be a nonempty stripped string") + return value + + +def _nonnegative_integer(value: int, name: str) -> int: + if type(value) is not int or value < 0: + raise ValueError(f"{name} must be a nonnegative integer") + return value + + +def _rigid_pose(value: object) -> tuple[tuple[float, ...], ...]: + try: + rows = tuple(tuple(row) for row in value) # type: ignore[union-attr] + except TypeError as exc: + raise ValueError("arena_pose must be a 4x4 rigid transform") from exc + if len(rows) != 4 or any(len(row) != 4 for row in rows): + raise ValueError("arena_pose must be a 4x4 rigid transform") + if any( + isinstance(item, bool) or not isinstance(item, Real) or not math.isfinite(item) + for row in rows + for item in row + ): + raise ValueError("arena_pose must contain finite real numbers") + pose = tuple( + tuple(float(item) if item != 0 else 0.0 for item in row) for row in rows + ) + tolerance = 1e-6 + if any( + abs(pose[3][index] - target) > tolerance + for index, target in enumerate((0, 0, 0, 1)) + ): + raise ValueError("arena_pose must have homogeneous last row [0, 0, 0, 1]") + rotation = tuple(row[:3] for row in pose[:3]) + if any( + abs(sum(rotation[k][i] * rotation[k][j] for k in range(3)) - (i == j)) + > tolerance + for i in range(3) + for j in range(3) + ): + raise ValueError("arena_pose rotation must be orthonormal") + determinant = ( + rotation[0][0] + * (rotation[1][1] * rotation[2][2] - rotation[1][2] * rotation[2][1]) + - rotation[0][1] + * (rotation[1][0] * rotation[2][2] - rotation[1][2] * rotation[2][0]) + + rotation[0][2] + * (rotation[1][0] * rotation[2][1] - rotation[1][1] * rotation[2][0]) + ) + if abs(determinant - 1.0) > tolerance: + raise ValueError("arena_pose rotation must be proper (determinant +1)") + return (*pose[:3], (0.0, 0.0, 0.0, 1.0)) + + +def plain(value: object) -> object: + if isinstance(value, np.ndarray): + return plain(value.tolist()) + if isinstance(value, np.generic): + return plain(value.item()) + # Tensor values can only exist when torch is already loaded by the caller. + torch = sys.modules.get("torch") + if torch is not None and isinstance(value, torch.Tensor): + return plain(value.detach().cpu().tolist()) + if isinstance(value, Path) or ( + torch is not None and isinstance(value, torch.device) + ): + return str(value) + if isinstance(value, slice): + return {"slice": [value.start, value.stop, value.step]} + if isinstance(value, Enum): + return plain(value.value) + if isinstance(getattr(value, "name", None), str) and isinstance( + getattr(value, "value", None), Real + ): + return { + "enum_type": type(value).__module__ + "." + type(value).__qualname__, + "name": value.name, + "value": plain(value.value), + } + if isinstance(value, (set, frozenset)): + return sorted( + (plain(v) for v in value), key=lambda v: json.dumps(v, sort_keys=True) + ) + if is_dataclass(value) and not isinstance(value, type): + return {f.name: plain(getattr(value, f.name)) for f in fields(value)} + if isinstance(value, Mapping): + return {str(k): plain(v) for k, v in value.items()} + if isinstance(value, (tuple, list)): + return [plain(v) for v in value] + return value + + +def digest(value: object) -> str: + return hashlib.sha256( + json.dumps( + plain(value), sort_keys=True, separators=(",", ":"), allow_nan=False + ).encode() + ).hexdigest() + + +def owned_json(value: Mapping[str, object]) -> Mapping[str, object]: + copied = json.loads(json.dumps(plain(value), allow_nan=False)) + + def freeze(item: object) -> object: + if isinstance(item, dict): + return MappingProxyType({k: freeze(v) for k, v in item.items()}) + if isinstance(item, list): + return tuple(freeze(v) for v in item) + return item + + return freeze(copied) + + +def finite(values: object, name: str) -> tuple[float, ...]: + result = tuple(values) + if any( + isinstance(v, bool) or not isinstance(v, Real) or not math.isfinite(v) + for v in result + ): + raise ValueError(f"{name} requires finite real values") + return tuple(float(v) for v in result) + + +def count(value: int, name: str, minimum: int = 1) -> None: + if type(value) is not int or value < minimum: + raise ValueError(f"{name} must be an integer >= {minimum}") + + +def names(values: object, name: str) -> tuple[str, ...]: + if isinstance(values, str): + raise ValueError(f"{name} requires a sequence") + result = tuple(values) + for value in result: + _identifier(value, name) + if len(set(result)) != len(result): + raise ValueError(f"{name} must be unique") + return result + + +def poses(values: Mapping[str, object]) -> Mapping[str, tuple]: + return MappingProxyType( + { + _identifier(k, "entity UID"): _rigid_pose(v) + for k, v in sorted(values.items()) + } + ) + + +def atomic_json(path: Path, value: object) -> None: + import os + import tempfile + + path.parent.mkdir(parents=True, exist_ok=True) + fd, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent) + try: + with os.fdopen(fd, "w", encoding="utf-8") as stream: + json.dump(plain(value), stream, allow_nan=False, sort_keys=True, indent=2) + os.replace(temporary, path) + finally: + Path(temporary).unlink(missing_ok=True) diff --git a/embodichain/lab/expansion/_distribution.py b/embodichain/lab/expansion/_distribution.py index 239c514fc9..d5d660aca3 100644 --- a/embodichain/lab/expansion/_distribution.py +++ b/embodichain/lab/expansion/_distribution.py @@ -23,6 +23,7 @@ import argparse from collections import Counter +from collections.abc import Mapping from copy import deepcopy import hashlib import json @@ -147,6 +148,17 @@ def _read(paths: list[Path], entity: str) -> tuple[list[dict], list[str]]: if not episode.validation.accepted: raise ValueError("Confirmed episode lacks acceptance") meta = episode.metadata + case = meta.get("scene_case") + task_id = case.get("task_id") if isinstance(case, Mapping) else None + source_uuid = meta.get("source_episode_uuid") + if isinstance(task_id, str) and task_id.strip(): + task_identity = ("task_id", task_id) + elif isinstance(source_uuid, str) and source_uuid.strip(): + task_identity = ("legacy_source_episode_uuid", source_uuid) + else: + raise ValueError( + f"Episode {episode.episode_id} lacks a recorded task identity" + ) # Fixed topology, installation and task identity; sampled object poses are features. robot = [ dict(uid=s["uid"], joints=list(s["joint_names"]), pose=list(s["pose"])) @@ -156,6 +168,7 @@ def _read(paths: list[Path], entity: str) -> tuple[list[dict], list[str]]: domain = _digest( { "robot": robot, + "task_identity": task_identity, "instruction": meta.get("instruction"), "backend": meta.get("physics_backend"), "deployment_robot": deployment.get("robot"), @@ -196,7 +209,8 @@ def _read(paths: list[Path], entity: str) -> tuple[list[dict], list[str]]: "artifact": receipt.storage_id, "job": str(directory), "domain_id": domain, - "source_episode_uuid": meta.get("source_episode_uuid"), + "task_id": task_id, + "source_episode_uuid": source_uuid, "initial_pose": None if state is None else state[0, :7].tolist(), "final_pose": None if state is None else state[-1, :7].tolist(), "orientation": ( diff --git a/embodichain/lab/expansion/_pose_sampling.py b/embodichain/lab/expansion/_pose_sampling.py index f4c0090353..42458748e7 100644 --- a/embodichain/lab/expansion/_pose_sampling.py +++ b/embodichain/lab/expansion/_pose_sampling.py @@ -311,16 +311,7 @@ def _guided(self, candidate, rng): for uid, opts in self.configuration.items(): if "follow" in opts: parent = opts["follow"] - poses[uid][:3, 3] = ( - self.poses[uid][:3, 3] - + poses[parent][:3, 3] - - self.poses[parent][:3, 3] - ) - poses[uid][:3, :3] = ( - poses[parent][:3, :3] - @ self.poses[parent][:3, :3].T - @ self.poses[uid][:3, :3] - ) + poses[uid] = self._follower_pose(uid, parent, poses[parent]) changes = tuple( ScenePoseChange(uid, tuple(map(tuple, pose))) for uid, pose in poses.items() ) @@ -379,6 +370,16 @@ def _check(self, candidate): return False, "full_pose_fk_residual" return True, "passed" + def _follower_pose( + self, uid: str, parent: str, parent_pose: np.ndarray + ) -> np.ndarray: + """Apply the parent's arena displacement and rotation to the nominal follower.""" + nominal_parent = self.poses[parent] + pose = self.poses[uid].astype(parent_pose.dtype, copy=True) + pose[:3, 3] = pose[:3, 3] + parent_pose[:3, 3] - nominal_parent[:3, 3] + pose[:3, :3] = parent_pose[:3, :3] @ nominal_parent[:3, :3].T @ pose[:3, :3] + return pose + def _offer(self, candidate, rng, raw): if self.cfg["strategy"] == "workspace_joint": candidate, origin = self._guided(candidate, rng) diff --git a/embodichain/lab/expansion/_pose_sampling_cfg.py b/embodichain/lab/expansion/_pose_sampling_cfg.py index b454e134b2..e8fc9bfe65 100644 --- a/embodichain/lab/expansion/_pose_sampling_cfg.py +++ b/embodichain/lab/expansion/_pose_sampling_cfg.py @@ -17,15 +17,82 @@ """Strict optional scene sampling and pose coverage declarations.""" from __future__ import annotations + +from collections.abc import Mapping +from dataclasses import dataclass import math +from typing import TYPE_CHECKING + import numpy as np +if TYPE_CHECKING: + from embodichain.lab._scene_config.feasibility import PhaseTarget, TaskOperationMode + __all__: list[str] = [] _ROBOT_LAYOUT_STRATEGIES = ("robot_first", "bidirectional") _LAYOUT_STRATEGIES = ("scene_first", *_ROBOT_LAYOUT_STRATEGIES) +@dataclass(frozen=True) +class _AnchorTarget: + phase_id: str + target: PhaseTarget + root_uid: str + + +def _anchor_targets( + mode: TaskOperationMode, layout: Mapping, policy: Mapping, selections: object +) -> tuple[_AnchorTarget, ...]: + """Resolve each named target to a rigid frame in the initial support tree.""" + if not isinstance(selections, list) or not selections: + raise ValueError( + "robot_anchors requires a nonempty list of phase/part selectors" + ) + targets = {} + moved = set() + support, parents = layout["support_uid"], layout["parent_by_uid"] + variable_members = policy["intra_group"]["targets"] + for phase in mode.phases: + for target in phase.targets: + targets[phase.phase_id, target.control_part] = (target, moved.copy()) + moved.update(held.entity_uid for held in phase.held_objects) + moved.update(change.entity_uid for change in phase.resulting_poses) + result, seen = [], set() + for sel in selections: + if ( + not isinstance(sel, Mapping) + or set(sel) != {"phase_id", "control_part"} + or any(type(value) is not str for value in sel.values()) + ): + raise ValueError("robot_anchors selects explicit phase_id and control_part") + key = (sel["phase_id"], sel["control_part"]) + if key not in targets or key in seen: + raise ValueError("robot_anchors must select unique declared phase targets") + seen.add(key) + target, earlier_moves = targets[key] + root = target.frame_uid + if root not in parents: + raise ValueError("A robot anchor target needs a frame in the support tree") + while True: + if root in variable_members or root in earlier_moves: + raise ValueError( + "A robot anchor needs an initial frame rigidly attached to its layout root" + ) + if parents[root] == support: + break + root = parents[root] + groups = policy["group_targets"] + if not policy["randomize_groups"] or ( + groups is not None and root not in groups + ): + raise ValueError("A robot anchor requires a movable layout root") + if root in layout.get("conditions", {}): + raise ValueError("A robot anchor cannot replace an authored root condition") + result.append(_AnchorTarget(key[0], target, root)) + return tuple(result) + + def validate_sampling(value: dict) -> None: """Normalize optional settings without changing legacy configurations.""" from ._pose_cells import _grid @@ -210,8 +277,8 @@ def validate_sampling(value: dict) -> None: or not 0 < screening["planning_timeout_s"] <= 60 ): raise ValueError("Screening timeout must be positive and bounded") - from embodichain.lab.sim.scene.expansion.layout import _policy_data - from embodichain.lab.sim.scene.feasibility import request_from_mapping + from embodichain.lab._scene_config.feasibility import request_from_mapping + from embodichain.lab._scene_config.policy import _policy_data normalized_policy = _policy_data(layout["policy"]) if any( @@ -270,8 +337,6 @@ def validate_sampling(value: dict) -> None: "robot_anchors" in sampling or sampling["strategy"] in _ROBOT_LAYOUT_STRATEGIES ): - from ._robot_first_sampling import _anchor_targets - anchors = _anchor_targets( request.modes[0], layout, diff --git a/embodichain/lab/expansion/_robot_first_sampling.py b/embodichain/lab/expansion/_robot_first_sampling.py index 1cbd0cdabe..34076263ee 100644 --- a/embodichain/lab/expansion/_robot_first_sampling.py +++ b/embodichain/lab/expansion/_robot_first_sampling.py @@ -27,77 +27,16 @@ from embodichain.lab.sim.scene.expansion import SceneLayoutCondition from embodichain.lab.sim.scene.feasibility.proposals import _workspace_fk_samples +from ._pose_sampling_cfg import _AnchorTarget + if TYPE_CHECKING: from embodichain.lab.sim.objects import Robot from embodichain.lab.sim.scene.expansion import PreparedSceneRandomization - from embodichain.lab.sim.scene.feasibility import ( - FeasibilityBudget, - PhaseTarget, - TaskOperationMode, - ) + from embodichain.lab.sim.scene.feasibility import FeasibilityBudget __all__: list[str] = [] -@dataclass(frozen=True) -class _AnchorTarget: - phase_id: str - target: PhaseTarget - root_uid: str - - -def _anchor_targets( - mode: TaskOperationMode, layout: Mapping, policy: Mapping, selections: object -) -> tuple[_AnchorTarget, ...]: - """Resolve each named target to a rigid frame in the initial support tree.""" - if not isinstance(selections, list) or not selections: - raise ValueError( - "robot_anchors requires a nonempty list of phase/part selectors" - ) - targets = {} - moved = set() - support, parents = layout["support_uid"], layout["parent_by_uid"] - variable_members = policy["intra_group"]["targets"] - for phase in mode.phases: - for target in phase.targets: - targets[phase.phase_id, target.control_part] = (target, moved.copy()) - moved.update(held.entity_uid for held in phase.held_objects) - moved.update(change.entity_uid for change in phase.resulting_poses) - result, seen = [], set() - for sel in selections: - if ( - not isinstance(sel, Mapping) - or set(sel) != {"phase_id", "control_part"} - or any(type(value) is not str for value in sel.values()) - ): - raise ValueError("robot_anchors selects explicit phase_id and control_part") - key = (sel["phase_id"], sel["control_part"]) - if key not in targets or key in seen: - raise ValueError("robot_anchors must select unique declared phase targets") - seen.add(key) - target, earlier_moves = targets[key] - root = target.frame_uid - if root not in parents: - raise ValueError("A robot anchor target needs a frame in the support tree") - while True: - if root in variable_members or root in earlier_moves: - raise ValueError( - "A robot anchor needs an initial frame rigidly attached to its layout root" - ) - if parents[root] == support: - break - root = parents[root] - groups = policy["group_targets"] - if not policy["randomize_groups"] or ( - groups is not None and root not in groups - ): - raise ValueError("A robot anchor requires a movable layout root") - if root in layout.get("conditions", {}): - raise ValueError("A robot anchor cannot replace an authored root condition") - result.append(_AnchorTarget(key[0], target, root)) - return tuple(result) - - @dataclass(frozen=True) class _AnchorPool: selection: _AnchorTarget diff --git a/embodichain/lab/expansion/_scene_first_sampling.py b/embodichain/lab/expansion/_scene_first_sampling.py index b6935d1a83..ff94f5d5a2 100644 --- a/embodichain/lab/expansion/_scene_first_sampling.py +++ b/embodichain/lab/expansion/_scene_first_sampling.py @@ -24,8 +24,8 @@ import numpy as np from ._pose_sampling import _AdaptivePoseSource -from ._pose_sampling_cfg import _ROBOT_LAYOUT_STRATEGIES -from ._robot_first_sampling import _anchor_targets, _prepare_anchor_pools +from ._pose_sampling_cfg import _ROBOT_LAYOUT_STRATEGIES, _anchor_targets +from ._robot_first_sampling import _prepare_anchor_pools from embodichain.lab.sim.scene.expansion import ( SceneLayoutCondition, scene_layout_input_from_sim, @@ -34,6 +34,7 @@ ScenePoseChange, SceneVariant, ) +from embodichain.lab.sim.scene.expansion.conditions import _LayoutConditionDomainError __all__: list[str] = [] @@ -254,6 +255,16 @@ def _offer_layout(self, candidate, raw, origin): for c in candidate.scene.pose_changes } changes.update({c.entity_uid: c for c in generated.pose_changes}) + for uid, options in self.configuration.items(): + if ( + uid not in self._prepared_layout.source.poses + and "follow" in options + ): + parent = options["follow"] + pose = self._follower_pose( + uid, parent, np.asarray(changes[parent].arena_pose) + ) + changes[uid] = ScenePoseChange(uid, pose) candidate = replace( candidate, scene=SceneVariant( @@ -281,14 +292,17 @@ def _offer_layout(self, candidate, raw, origin): actual = anchors.get(uid, self._prepared_layout.source.poses[uid]) if not np.allclose(actual, pose, rtol=0, atol=1e-9): return candidate, "bounded_pose", False, "condition_mismatch" - batch = generate_scene_variants( - self._prepared_layout, - seed=self.seed, - candidate_count=1, - max_attempts=1, - start_ordinal=raw, - conditions=SceneLayoutCondition(anchors), - ) + try: + batch = generate_scene_variants( + self._prepared_layout, + seed=self.seed, + candidate_count=1, + max_attempts=1, + start_ordinal=raw, + conditions=SceneLayoutCondition(anchors), + ) + except _LayoutConditionDomainError: + return candidate, origin, False, "layout_outside_sampled_domain" if not batch.variants: return candidate, "bounded_pose", False, "layout_budget_exhausted" poses = { diff --git a/embodichain/lab/expansion/distribution.md b/embodichain/lab/expansion/distribution.md index 7cde799567..92d1a2c5e7 100644 --- a/embodichain/lab/expansion/distribution.md +++ b/embodichain/lab/expansion/distribution.md @@ -20,6 +20,9 @@ Inputs must be job directories containing `job.json` and confirmed artifact rece Repeated input paths/commit identities do not multiply samples. Conflicting commit identities fail. Output must be new; inputs are never overwritten. Both snapshots must have the same task, robot installation, topology and configured scene domain. +The recorded scene-case task ID identifies the task across seeds and source +recordings. Older artifacts can use their recorded source UUID when the task ID +is absent. Artifacts without either identity cannot be compared. Open `report.html`. Select a spatial region or joint-distribution cell to inspect recorded object paths. The evidence panel identifies the full artifact and the diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index c8e32ac457..356075f06a 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -215,10 +215,11 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: host, engine = group["host"], group["engine"] ctx = host._context request = ctx.requests[row] - if group["session"].stop_reason == "wall_time_exhausted": - ctx.journal.update( - request, status="initial_rejected", reason="wall_time_exhausted" - ) + session = group["session"] + budget_stops = ("wall_time_exhausted", "rollout_budget_exhausted") + stop_reason = session.stop_reason + if stop_reason in budget_stops: + ctx.journal.update(request, status="initial_rejected", reason=stop_reason) return None if self.activation_snapshot is None: self.activation_snapshot = ( @@ -270,7 +271,6 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: ctx.program.program_id, self.env.robot.uid, ) - session = group["session"] session.register_case(case, ctx.limits, joint_names=ctx.names) try: identity, _ = session.propose( @@ -285,11 +285,10 @@ def activate(self, assignment: WorkloadAssignment, observation: object) -> Any: except RuntimeError: # The budget can expire during initial-state validation, including # between the early check and the session's atomic proposal guard. - if session.stop_reason != "wall_time_exhausted": + stop_reason = session.stop_reason + if stop_reason not in budget_stops: raise - ctx.journal.update( - request, status="initial_rejected", reason="wall_time_exhausted" - ) + ctx.journal.update(request, status="initial_rejected", reason=stop_reason) return None episode_id, commit_id = session.episode_ids(identity) record = ctx.journal.update( diff --git a/embodichain/lab/sim/scene/_support_grid.py b/embodichain/lab/sim/scene/_support_grid.py index 96aaeaeb39..97dfd4d0c9 100644 --- a/embodichain/lab/sim/scene/_support_grid.py +++ b/embodichain/lab/sim/scene/_support_grid.py @@ -24,45 +24,12 @@ import numpy as np import shapely -from shapely.geometry import Polygon, MultiPolygon, mapping, shape +from shapely.geometry import Polygon, MultiPolygon, mapping from shapely.ops import unary_union -__all__: list[str] = [] - +from embodichain.lab._scene_config.policy import _read_support_polygon -def _read_support_polygon(value: object) -> Polygon | MultiPolygon: - """Decode finite XY GeoJSON before accessing any scene assets.""" - if not isinstance(value, dict) or value.get("type") not in ( - "Polygon", - "MultiPolygon", - ): - raise ValueError( - "Support polygon must be a GeoJSON Polygon or MultiPolygon mapping." - ) - try: - polygon = shape(value) - except ( - AttributeError, - KeyError, - IndexError, - TypeError, - ValueError, - OverflowError, - shapely.errors.GEOSException, - ) as exc: - raise ValueError("Support polygon has invalid GeoJSON coordinates.") from exc - if ( - not isinstance(polygon, (Polygon, MultiPolygon)) - or polygon.is_empty - or polygon.has_z - or not np.isfinite(shapely.get_coordinates(polygon)).all() - or not polygon.is_valid - or polygon.area <= 0 - ): - raise ValueError( - "Support polygon must contain a valid nonempty finite XY area." - ) - return polygon +__all__: list[str] = [] def _plane_region( diff --git a/embodichain/lab/sim/scene/_validation.py b/embodichain/lab/sim/scene/_validation.py index 52898f649f..a867003193 100644 --- a/embodichain/lab/sim/scene/_validation.py +++ b/embodichain/lab/sim/scene/_validation.py @@ -18,69 +18,18 @@ from __future__ import annotations -import math -from numbers import Real from typing import TYPE_CHECKING +from embodichain.lab._scene_config.values import ( + _identifier, + _nonnegative_integer, + _rigid_pose, +) + if TYPE_CHECKING: import torch -__all__ = [] - - -def _identifier(value: str, name: str) -> str: - if not isinstance(value, str) or not value or value.strip() != value: - raise ValueError(f"{name} must be a nonempty stripped string") - return value - - -def _nonnegative_integer(value: int, name: str) -> int: - if type(value) is not int or value < 0: - raise ValueError(f"{name} must be a nonnegative integer") - return value - - -def _rigid_pose(value: object) -> tuple[tuple[float, ...], ...]: - try: - rows = tuple(tuple(row) for row in value) # type: ignore[union-attr] - except TypeError as exc: - raise ValueError("arena_pose must be a 4x4 rigid transform") from exc - if len(rows) != 4 or any(len(row) != 4 for row in rows): - raise ValueError("arena_pose must be a 4x4 rigid transform") - if any( - isinstance(item, bool) or not isinstance(item, Real) or not math.isfinite(item) - for row in rows - for item in row - ): - raise ValueError("arena_pose must contain finite real numbers") - pose = tuple( - tuple(float(item) if item != 0 else 0.0 for item in row) for row in rows - ) - tolerance = 1e-6 - if any( - abs(pose[3][index] - target) > tolerance - for index, target in enumerate((0, 0, 0, 1)) - ): - raise ValueError("arena_pose must have homogeneous last row [0, 0, 0, 1]") - rotation = tuple(row[:3] for row in pose[:3]) - if any( - abs(sum(rotation[k][i] * rotation[k][j] for k in range(3)) - (i == j)) - > tolerance - for i in range(3) - for j in range(3) - ): - raise ValueError("arena_pose rotation must be orthonormal") - determinant = ( - rotation[0][0] - * (rotation[1][1] * rotation[2][2] - rotation[1][2] * rotation[2][1]) - - rotation[0][1] - * (rotation[1][0] * rotation[2][2] - rotation[1][2] * rotation[2][0]) - + rotation[0][2] - * (rotation[1][0] * rotation[2][1] - rotation[1][1] * rotation[2][0]) - ) - if abs(determinant - 1.0) > tolerance: - raise ValueError("arena_pose rotation must be proper (determinant +1)") - return (*pose[:3], (0.0, 0.0, 0.0, 1.0)) +__all__: list[str] = [] def _owned_batch_pose(value: torch.Tensor, name: str) -> torch.Tensor: diff --git a/embodichain/lab/sim/scene/expansion/_policy.py b/embodichain/lab/sim/scene/expansion/_policy.py index 52567481ca..03a4c4ffee 100644 --- a/embodichain/lab/sim/scene/expansion/_policy.py +++ b/embodichain/lab/sim/scene/expansion/_policy.py @@ -13,15 +13,23 @@ # See the License for the specific language governing permissions and # limitations under the License. # ---------------------------------------------------------------------------- - -"""Source-independent policies for bounded scene layout sampling.""" +"""Public scene policy configuration imports.""" from __future__ import annotations -from copy import deepcopy -from dataclasses import MISSING -import math -from typing import Any -from embodichain.utils import configclass + +from embodichain.lab._scene_config.policy import ( + IntraGroupRandomizationCfg, + MemberRandomizationCfg, + SceneRandomizationJobCfg, + SceneRandomizationPolicyCfg, + SupportOverrideCfg, + _decode_intra, + _intra_payload, + _policy_data, + _validate_backend, + _validate_generation_parameters, + _validate_intra, +) __all__ = [ "MemberRandomizationCfg", @@ -30,306 +38,3 @@ "SceneRandomizationPolicyCfg", "SceneRandomizationJobCfg", ] - - -@configclass -class MemberRandomizationCfg: - """One non-root member's displacement bounds in its parent support frame. - - ``xy_offset_bounds_m`` is ``[[min_x, min_y], [max_x, max_y]]`` relative - to the original entity origin; ``None`` samples the complete support area. - Yaw is a continuous increment around the support normal, retaining tilt. - """ - - xy_offset_bounds_m: list[list[float]] | None = None - yaw_delta_range_deg: list[float] = [-180.0, 180.0] - - -@configclass -class SupportOverrideCfg: - """Explicit parent-local support frame and GeoJSON Polygon/MultiPolygon. - - The proper rigid ``parent_from_support`` matrix locates the support plane - at support Z=0 in the parent local Z-up geometry after asset scaling. Its polygon must be covered by actual coplanar mesh faces. - """ - - parent_from_support: list[list[float]] = MISSING - polygon: dict = MISSING - - -@configclass -class IntraGroupRandomizationCfg: - """Explicit member selection and conservative support geometry settings. - - Fixed members follow their parent. Clearances and grid resolution are in - metres. Overrides are keyed by parent UID, independently of target order. - """ - - targets: dict[str, MemberRandomizationCfg] = {} - boundary_margin_m: float = 0.002 - sibling_margin_m: float = 0.002 - support_gap_m: float = 0.001 - grid_resolution_m: float = 0.001 - support_overrides: dict[str, SupportOverrideCfg] = {} - - -def _validate_backend(*, backend: str, device: str, batch_size: int) -> None: - """Validate execution controls without initializing CUDA or reading assets.""" - if backend not in ("slsqp", "batched"): - raise ValueError("backend must be slsqp or batched.") - if not isinstance(device, str) or not ( - device == "cpu" - or device == "cuda" - or ( - device.startswith("cuda:") and device[5:].isascii() and device[5:].isdigit() - ) - ): - raise ValueError("device must be cpu, cuda, or cuda:N.") - if backend == "slsqp" and device != "cpu": - raise ValueError( - "The slsqp backend runs on CPU; use backend: batched for CUDA." - ) - if type(batch_size) is not int or batch_size < 1: - raise ValueError("batch_size must be a positive integer.") - - -def _validate_generation_parameters( - *, seed: int, candidate_count: int, max_attempts: int, collision_margin_m: float -) -> None: - """Validate YAML values and Python overrides before accessing scene files.""" - for name, value, minimum in ( - ("seed", seed, 0), - ("candidate_count", candidate_count, 1), - ("max_attempts", max_attempts, 1), - ): - if type(value) is not int or value < minimum: - raise ValueError(f"{name} must be an integer >= {minimum}.") - if candidate_count > max_attempts: - raise ValueError("max_attempts must be at least candidate_count.") - if type(collision_margin_m) not in (int, float) or collision_margin_m < 0: - raise ValueError("collision_margin_m must be finite and nonnegative.") - try: - finite = math.isfinite(collision_margin_m) - except OverflowError: - finite = False - if not finite: - raise ValueError("collision_margin_m must be finite and nonnegative.") - - -def _mapping(value: Any, *, name: str, allowed: set[str]) -> dict[str, Any]: - if not isinstance(value, dict): - raise ValueError(f"{name} must be a mapping.") - unknown = set(value) - allowed - if unknown: - raise ValueError(f"Unknown {name} fields: {', '.join(sorted(unknown))}.") - return value - - -def _decode_intra(value: Any) -> IntraGroupRandomizationCfg | None: - """Strictly decode nested YAML mappings, also used for persisted policies.""" - if value is None: - return None - root = _mapping( - value, - name="intra_group", - allowed={ - "targets", - "boundary_margin_m", - "sibling_margin_m", - "support_gap_m", - "grid_resolution_m", - "support_overrides", - }, - ) - targets = root.get("targets", {}) - if not isinstance(targets, dict): - raise ValueError("targets must be a mapping.") - decoded = {} - for uid, target in targets.items(): - if not isinstance(uid, str) or not uid.strip(): - raise ValueError("Target UIDs must be nonempty strings.") - item = _mapping( - target, - name=f"target {uid}", - allowed={"xy_offset_bounds_m", "yaw_delta_range_deg"}, - ) - decoded[uid] = MemberRandomizationCfg(**item) - overrides = root.get("support_overrides", {}) - if not isinstance(overrides, dict): - raise ValueError("support_overrides must be a mapping.") - override_cfg = {} - for uid, override in overrides.items(): - item = _mapping( - override, - name=f"support override {uid}", - allowed={"parent_from_support", "polygon"}, - ) - if set(item) != {"parent_from_support", "polygon"}: - raise ValueError("Support overrides require a transform and polygon.") - override_cfg[uid] = SupportOverrideCfg(**item) - cfg = IntraGroupRandomizationCfg( - **{k: v for k, v in root.items() if k not in ("targets", "support_overrides")}, - targets=decoded, - support_overrides=override_cfg, - ) - _validate_intra(cfg) - return cfg - - -def _validate_intra(cfg: IntraGroupRandomizationCfg) -> None: - import numpy as np - - if not isinstance(cfg, IntraGroupRandomizationCfg): - raise ValueError("intra_group must be an IntraGroupRandomizationCfg.") - cfg.validate() - if not isinstance(cfg.targets, dict) or not isinstance(cfg.support_overrides, dict): - raise ValueError("targets and support_overrides must be mappings.") - for field in ( - "boundary_margin_m", - "sibling_margin_m", - "support_gap_m", - "grid_resolution_m", - ): - value = getattr(cfg, field) - try: - finite = type(value) in (int, float) and math.isfinite(value) - except OverflowError: - finite = False - if not finite or value < 0 or (field == "grid_resolution_m" and value == 0): - raise ValueError( - f"{field} must be finite and {'positive' if field == 'grid_resolution_m' else 'nonnegative'}." - ) - for uid, item in cfg.targets.items(): - if ( - not isinstance(uid, str) - or not uid - or not isinstance(item, MemberRandomizationCfg) - ): - raise ValueError("targets must map UIDs to MemberRandomizationCfg.") - yaw = np.asarray(item.yaw_delta_range_deg) - if ( - yaw.shape != (2,) - or yaw.dtype.kind not in "fi" - or not np.isfinite(yaw).all() - or yaw[0] > yaw[1] - or not np.isfinite(yaw[1] - yaw[0]) - ): - raise ValueError( - "yaw_delta_range_deg requires finite ordered bounds and width." - ) - if item.xy_offset_bounds_m is not None: - xy = np.asarray(item.xy_offset_bounds_m) - if ( - xy.shape != (2, 2) - or xy.dtype.kind not in "fi" - or not np.isfinite(xy).all() - or np.any(xy[0] > xy[1]) - ): - raise ValueError( - "xy_offset_bounds_m requires finite ordered lower/upper XY corners." - ) - for uid, override in cfg.support_overrides.items(): - if ( - not isinstance(uid, str) - or not uid - or not isinstance(override, SupportOverrideCfg) - ): - raise ValueError("support_overrides must map UIDs to SupportOverrideCfg.") - override.validate() - from embodichain.lab.sim.scene._support_grid import _read_support_polygon - - try: - _read_support_polygon(override.polygon) - except ValueError as exc: - raise ValueError(f"Support override {uid!r}: {exc}") from exc - try: - matrix = np.asarray(override.parent_from_support, dtype=float) - except (TypeError, ValueError, OverflowError) as exc: - raise ValueError( - "parent_from_support must contain finite numeric values." - ) from exc - if ( - matrix.shape != (4, 4) - or not np.isfinite(matrix).all() - or not np.array_equal(matrix[3], [0, 0, 0, 1]) - or not np.allclose( - matrix[:3, :3].T @ matrix[:3, :3], np.eye(3), atol=1e-8, rtol=0 - ) - or not np.isclose(np.linalg.det(matrix[:3, :3]), 1, atol=1e-8, rtol=0) - ): - raise ValueError("parent_from_support must be a proper rigid transform.") - - -def _intra_payload(cfg: IntraGroupRandomizationCfg) -> dict: - """Serialize only documented settings, independent of configclass internals.""" - return deepcopy( - { - "targets": { - uid: { - "xy_offset_bounds_m": item.xy_offset_bounds_m, - "yaw_delta_range_deg": list(item.yaw_delta_range_deg), - } - for uid, item in sorted(cfg.targets.items()) - }, - **{ - key: float(getattr(cfg, key)) - for key in ( - "boundary_margin_m", - "sibling_margin_m", - "support_gap_m", - "grid_resolution_m", - ) - }, - "support_overrides": { - uid: { - "parent_from_support": item.parent_from_support, - "polygon": item.polygon, - } - for uid, item in sorted(cfg.support_overrides.items()) - }, - } - ) - - -@configclass -class SceneRandomizationPolicyCfg: - """Geometric policy independent of scene files and runtime lifecycles. - - Args: - backend: Explicit numeric backend; the shared interface uses batched sampling. - device: CPU or CUDA tensor device. - batch_size: Maximum logical proposals evaluated together. - collision_margin_m: Minimum group AABB separation in metres. - randomize_groups: Sample permitted group-root XY translations. - group_targets: Root UIDs to move; None selects all permitted roots. - group_xy_offset_bounds_m: Optional per-root arena XY displacement bounds. - intra_group: Selected non-root XY/yaw changes and support settings. - """ - - backend: str = "batched" - device: str = "cpu" - batch_size: int = 4096 - collision_margin_m: float = 0.02 - randomize_groups: bool = True - group_targets: tuple[str, ...] | None = None - group_xy_offset_bounds_m: dict[str, list[list[float]]] = {} - intra_group: IntraGroupRandomizationCfg | None = None - - -@configclass -class SceneRandomizationJobCfg: - """Bounded caller-owned generation settings and output representation. - - Args: - policy: Source-independent geometric sampling policy. - seed: Addressed generation seed. - candidate_count: Requested valid layouts. - max_attempts: Whole-layout proposal budget. - layout_storage: JSON or packed candidate storage. - """ - - policy: SceneRandomizationPolicyCfg = SceneRandomizationPolicyCfg() - seed: int = 0 - candidate_count: int = 10 - max_attempts: int = 1000 - layout_storage: str = "packed" diff --git a/embodichain/lab/sim/scene/expansion/conditions.py b/embodichain/lab/sim/scene/expansion/conditions.py index 2b70be330d..8d9390a6f0 100644 --- a/embodichain/lab/sim/scene/expansion/conditions.py +++ b/embodichain/lab/sim/scene/expansion/conditions.py @@ -35,6 +35,10 @@ __all__ = ["SceneLayoutCondition"] +class _LayoutConditionDomainError(ValueError): + """A well-formed anchor conflicts with its prepared layout domain.""" + + @dataclass(frozen=True) class SceneLayoutCondition: """Fix declared entities to arena poses without enlarging their motion domain. @@ -94,7 +98,7 @@ def _condition_prepared( parent = parent_uid while parent != source.support_uid: if parent in variable and parent not in condition.poses: - raise ValueError( + raise _LayoutConditionDomainError( f"Anchor {uid!r} requires its moving ancestor {parent!r} to be anchored" ) parent = source.parent_by_uid[parent] @@ -108,20 +112,24 @@ def _condition_prepared( not np.allclose(wanted[:3, :3], original[:3, :3], rtol=0, atol=1e-9) or abs(wanted[2, 3] - original[2, 3]) > 1e-9 ): - raise ValueError( + raise _LayoutConditionDomainError( "Root anchors support declared XY translation only; rotation/height must remain authored" ) delta = wanted[:2, 3] - original[:2, 3] if uid not in roots: if not np.allclose(delta, 0, rtol=0, atol=1e-9): - raise ValueError(f"Condition cannot move fixed group {uid!r}") + raise _LayoutConditionDomainError( + f"Condition cannot move fixed group {uid!r}" + ) else: bounds = policy["group_xy_offset_bounds_m"].get(uid) if bounds is not None and ( np.any(delta < np.asarray(bounds)[0] - 1e-9) or np.any(delta > np.asarray(bounds)[1] + 1e-9) ): - raise ValueError("Anchor lies outside declared root XY bounds") + raise _LayoutConditionDomainError( + "Anchor lies outside declared root XY bounds" + ) policy["group_xy_offset_bounds_m"][uid] = [ delta.tolist(), delta.tolist(), @@ -135,7 +143,9 @@ def _condition_prepared( wanted = np.asarray(condition.poses[uid]) if uid not in targets: if not np.allclose(wanted, parent_world @ relative, rtol=0, atol=1e-9): - raise ValueError(f"Condition cannot move undeclared member {uid!r}") + raise _LayoutConditionDomainError( + f"Condition cannot move undeclared member {uid!r}" + ) world[uid] = wanted continue spec = targets[uid] @@ -158,18 +168,22 @@ def _condition_prepared( not np.allclose(rotation, yaw_rotation, rtol=0, atol=1e-9) or abs(local[2, 3] - height) > 1e-9 ): - raise ValueError( + raise _LayoutConditionDomainError( "Member anchor violates its authored tilt or support height" ) if angle < low - 1e-8 or angle > high + 1e-8: - raise ValueError("Member anchor lies outside declared yaw bounds") + raise _LayoutConditionDomainError( + "Member anchor lies outside declared yaw bounds" + ) offset = local[:2, 3] - baseline[:2, 3] bounds = spec["xy_offset_bounds_m"] if bounds is not None and ( np.any(offset < np.asarray(bounds)[0] - 1e-9) or np.any(offset > np.asarray(bounds)[1] + 1e-9) ): - raise ValueError("Member anchor lies outside declared XY bounds") + raise _LayoutConditionDomainError( + "Member anchor lies outside declared XY bounds" + ) spec["xy_offset_bounds_m"] = [offset.tolist(), offset.tolist()] spec["yaw_delta_range_deg"] = [angle, angle] world[uid] = wanted diff --git a/embodichain/lab/sim/scene/expansion/contracts.py b/embodichain/lab/sim/scene/expansion/contracts.py index 2b103efa11..a1bc4fb78a 100644 --- a/embodichain/lab/sim/scene/expansion/contracts.py +++ b/embodichain/lab/sim/scene/expansion/contracts.py @@ -13,145 +13,19 @@ # See the License for the specific language governing permissions and # limitations under the License. # ---------------------------------------------------------------------------- - -"""Immutable scene proposals, independent of task and execution lifecycles.""" +"""Public scene proposal contracts shared with simulator-free configuration.""" from __future__ import annotations -from dataclasses import dataclass -import hashlib -import json +from embodichain.lab._scene_config.scene import ( + ScenePoseChange, + SceneVariant, + _variant_id, +) +from embodichain.lab._scene_config.values import ( + _identifier, + _nonnegative_integer, + _rigid_pose, +) __all__ = ["ScenePoseChange", "SceneVariant"] - - -from .._validation import _identifier, _nonnegative_integer, _rigid_pose - - -def _variant_id( - parent_scene_id: str, - seed: int, - ordinal: int, - pose_changes: tuple, - metadata: tuple, -) -> str: - """Hash already validated, canonically ordered proposal values.""" - payload = { - "schema": "scene-variant/v1", - "parent_scene_id": parent_scene_id, - "seed": seed, - "ordinal": ordinal, - "pose_changes": pose_changes, - "metadata": metadata, - } - encoded = json.dumps( - payload, sort_keys=True, separators=(",", ":"), allow_nan=False - ).encode("utf-8") - return "scene-variant:" + hashlib.sha256(encoded).hexdigest() - - -@dataclass(frozen=True) -class ScenePoseChange: - """A proposed pose for one existing physical entity. - - Args: - entity_uid: Stable physical entity UID, independent of environment slots. - arena_pose: Homogeneous 4x4 transform from the entity frame into its - local Z-up arena frame. Inputs are copied into immutable tuples. - - .. attention:: - An arena pose excludes replication offsets. The host converts it to - backend coordinates when applying the candidate. This contract does - not establish support, collision freedom, or manipulation feasibility. - """ - - entity_uid: str - arena_pose: tuple[tuple[float, ...], ...] - - def __post_init__(self) -> None: - _identifier(self.entity_uid, "entity_uid") - object.__setattr__(self, "arena_pose", _rigid_pose(self.arena_pose)) - - -@dataclass(frozen=True) -class SceneVariant: - """An immutable scene proposal with reproducible proposal identity. - - Args: - parent_scene_id: Content/revision identity of the original scene. - seed: Nonnegative proposal-generation seed. - ordinal: Nonnegative position in the candidate source. - pose_changes: Unique existing entities and their proposed arena poses. - metadata: Unique string key/value provenance entries. Entries and pose - changes are sorted so equivalent input ordering has one identity. - - .. attention:: - ``variant_id`` identifies a proposal, not a settled initial state or a - successful execution. Hosts record those identities and evidence - separately. Metadata describes provenance, not executable operations. - Since ``ordinal`` participates in the hash, consuming the same layout - at a different source position changes ``variant_id``. File-backed - consumers should retain the original layout identity and proposal - ordinal in metadata for provenance across selection orders; this ID - is not a geometry-only deduplication key. - """ - - parent_scene_id: str - seed: int - ordinal: int - pose_changes: tuple[ScenePoseChange, ...] - metadata: tuple[tuple[str, str], ...] = () - - def __post_init__(self) -> None: - _identifier(self.parent_scene_id, "parent_scene_id") - _nonnegative_integer(self.seed, "seed") - _nonnegative_integer(self.ordinal, "ordinal") - try: - changes = tuple(self.pose_changes) - except TypeError as exc: - raise ValueError( - "pose_changes must contain ScenePoseChange values" - ) from exc - if any(not isinstance(change, ScenePoseChange) for change in changes): - raise ValueError("pose_changes must contain ScenePoseChange values") - if len({change.entity_uid for change in changes}) != len(changes): - raise ValueError("pose_changes must contain unique entity UIDs") - object.__setattr__( - self, - "pose_changes", - tuple(sorted(changes, key=lambda change: change.entity_uid)), - ) - try: - entries = tuple(self.metadata) - if any(isinstance(entry, str) for entry in entries): - raise ValueError("metadata must contain string key/value pairs") - metadata = tuple(tuple(entry) for entry in entries) - except TypeError as exc: - raise ValueError("metadata must contain string key/value pairs") from exc - if any(len(entry) != 2 for entry in metadata): - raise ValueError("metadata must contain string key/value pairs") - for key, value in metadata: - _identifier(key, "metadata key") - if not isinstance(value, str): - raise ValueError("metadata values must be strings") - if len({key for key, _ in metadata}) != len(metadata): - raise ValueError("metadata must contain unique keys") - object.__setattr__(self, "metadata", tuple(sorted(metadata))) - - @property - def variant_id(self) -> str: - """Return a stable identity including geometry, source, seed, and ordinal. - - Returns: - SHA-256 identity independent of Python hash randomization and - temporary physical environment assignments. - """ - return _variant_id( - self.parent_scene_id, - self.seed, - self.ordinal, - tuple( - (change.entity_uid, change.arena_pose) for change in self.pose_changes - ), - self.metadata, - ) diff --git a/embodichain/lab/sim/scene/expansion/layout.py b/embodichain/lab/sim/scene/expansion/layout.py index 14ec5af156..17763a96f3 100644 --- a/embodichain/lab/sim/scene/expansion/layout.py +++ b/embodichain/lab/sim/scene/expansion/layout.py @@ -45,13 +45,10 @@ _specification, ) from ._policy import ( - IntraGroupRandomizationCfg, SceneRandomizationPolicyCfg, - _decode_intra, - _intra_payload, + _policy_data, _validate_backend, _validate_generation_parameters, - _validate_intra, ) if TYPE_CHECKING: @@ -253,66 +250,6 @@ def scene_layout_input_from_sim( ) -def _policy_data(cfg: SceneRandomizationPolicyCfg | Mapping) -> dict: - if isinstance(cfg, Mapping): - raw = dict(cfg) - cfg = SceneRandomizationPolicyCfg(**raw) - if not isinstance(cfg, SceneRandomizationPolicyCfg): - raise TypeError("policy must be a SceneRandomizationPolicyCfg or mapping") - cfg = cfg.copy() - cfg.validate() - _validate_backend(backend=cfg.backend, device=cfg.device, batch_size=cfg.batch_size) - if cfg.backend != "batched": - raise ValueError( - "The source-independent layout API supports backend='batched'." - ) - _validate_generation_parameters( - seed=0, - candidate_count=1, - max_attempts=1, - collision_margin_m=cfg.collision_margin_m, - ) - if type(cfg.randomize_groups) is not bool: - raise ValueError("randomize_groups must be a boolean.") - intra = cfg.intra_group - if isinstance(intra, dict) or intra is None: - intra = _decode_intra(intra) - if intra is None: - intra = IntraGroupRandomizationCfg() - _validate_intra(intra) - if not isinstance(cfg.group_xy_offset_bounds_m, dict): - raise ValueError("group_xy_offset_bounds_m must map root UIDs to XY bounds.") - for uid, bounds in cfg.group_xy_offset_bounds_m.items(): - if bounds is None: - raise ValueError( - "Root XY bounds must be explicit lower/upper corners; omit unbounded roots." - ) - _decode_intra( - { - "targets": { - uid: {"xy_offset_bounds_m": bounds, "yaw_delta_range_deg": [0, 0]} - } - } - ) - if cfg.group_xy_offset_bounds_m and not cfg.randomize_groups: - raise ValueError("Root XY bounds require randomize_groups=True.") - if cfg.group_targets is not None and ( - isinstance(cfg.group_targets, str) - or len(set(cfg.group_targets)) != len(cfg.group_targets) - ): - raise ValueError("group_targets must contain unique root UIDs.") - return { - "backend": cfg.backend, - "device": cfg.device, - "batch_size": cfg.batch_size, - "collision_margin_m": float(cfg.collision_margin_m), - "randomize_groups": cfg.randomize_groups, - "group_targets": None if cfg.group_targets is None else list(cfg.group_targets), - "group_xy_offset_bounds_m": deepcopy(cfg.group_xy_offset_bounds_m), - "intra_group": _intra_payload(intra), - } - - @dataclass(frozen=True) class PreparedSceneRandomization: """Own reusable numeric geometry, policy, permissions and source identity.""" diff --git a/embodichain/lab/sim/scene/feasibility/_values.py b/embodichain/lab/sim/scene/feasibility/_values.py index 1d3f6a1ea2..0c86962f9d 100644 --- a/embodichain/lab/sim/scene/feasibility/_values.py +++ b/embodichain/lab/sim/scene/feasibility/_values.py @@ -13,126 +13,19 @@ # See the License for the specific language governing permissions and # limitations under the License. # ---------------------------------------------------------------------------- -"""Private canonical value validation for feasibility artifacts.""" +"""Internal compatibility imports for canonical feasibility value validation.""" from __future__ import annotations -from collections.abc import Mapping -from dataclasses import fields, is_dataclass -import hashlib -import json -import math -from numbers import Real -from enum import Enum -import numpy as np -import torch -from pathlib import Path -from types import MappingProxyType - -from .._validation import _identifier, _rigid_pose - -__all__ = [] - - -def plain(value: object) -> object: - if isinstance(value, np.ndarray): - return plain(value.tolist()) - if isinstance(value, np.generic): - return plain(value.item()) - if isinstance(value, torch.Tensor): - return plain(value.detach().cpu().tolist()) - if isinstance(value, (Path, torch.device)): - return str(value) - if isinstance(value, slice): - return {"slice": [value.start, value.stop, value.step]} - if isinstance(value, Enum): - return plain(value.value) - if isinstance(getattr(value, "name", None), str) and isinstance( - getattr(value, "value", None), Real - ): - return { - "enum_type": type(value).__module__ + "." + type(value).__qualname__, - "name": value.name, - "value": plain(value.value), - } - if isinstance(value, (set, frozenset)): - return sorted( - (plain(v) for v in value), key=lambda v: json.dumps(v, sort_keys=True) - ) - if is_dataclass(value) and not isinstance(value, type): - return {f.name: plain(getattr(value, f.name)) for f in fields(value)} - if isinstance(value, Mapping): - return {str(k): plain(v) for k, v in value.items()} - if isinstance(value, (tuple, list)): - return [plain(v) for v in value] - return value - - -def digest(value: object) -> str: - return hashlib.sha256( - json.dumps( - plain(value), sort_keys=True, separators=(",", ":"), allow_nan=False - ).encode() - ).hexdigest() - - -def owned_json(value: Mapping[str, object]) -> Mapping[str, object]: - copied = json.loads(json.dumps(plain(value), allow_nan=False)) - - def freeze(item: object) -> object: - if isinstance(item, dict): - return MappingProxyType({k: freeze(v) for k, v in item.items()}) - if isinstance(item, list): - return tuple(freeze(v) for v in item) - return item - - return freeze(copied) - - -def finite(values: object, name: str) -> tuple[float, ...]: - result = tuple(values) - if any( - isinstance(v, bool) or not isinstance(v, Real) or not math.isfinite(v) - for v in result - ): - raise ValueError(f"{name} requires finite real values") - return tuple(float(v) for v in result) - - -def count(value: int, name: str, minimum: int = 1) -> None: - if type(value) is not int or value < minimum: - raise ValueError(f"{name} must be an integer >= {minimum}") - - -def names(values: object, name: str) -> tuple[str, ...]: - if isinstance(values, str): - raise ValueError(f"{name} requires a sequence") - result = tuple(values) - for value in result: - _identifier(value, name) - if len(set(result)) != len(result): - raise ValueError(f"{name} must be unique") - return result - - -def poses(values: Mapping[str, object]) -> Mapping[str, tuple]: - return MappingProxyType( - { - _identifier(k, "entity UID"): _rigid_pose(v) - for k, v in sorted(values.items()) - } - ) - - -def atomic_json(path: Path, value: object) -> None: - import os - import tempfile - - path.parent.mkdir(parents=True, exist_ok=True) - fd, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent) - try: - with os.fdopen(fd, "w", encoding="utf-8") as stream: - json.dump(plain(value), stream, allow_nan=False, sort_keys=True, indent=2) - os.replace(temporary, path) - finally: - Path(temporary).unlink(missing_ok=True) +from embodichain.lab._scene_config.values import ( + atomic_json, + count, + digest, + finite, + names, + owned_json, + plain, + poses, +) + +__all__: list[str] = [] diff --git a/embodichain/lab/sim/scene/feasibility/contracts.py b/embodichain/lab/sim/scene/feasibility/contracts.py index c38fdcfa09..51069c3e43 100644 --- a/embodichain/lab/sim/scene/feasibility/contracts.py +++ b/embodichain/lab/sim/scene/feasibility/contracts.py @@ -22,12 +22,19 @@ from dataclasses import dataclass, field from functools import cached_property from types import MappingProxyType -import math from typing import Literal -from .._validation import _identifier, _rigid_pose -from ..expansion import ScenePoseChange, SceneVariant -from ._values import count, digest, finite, names, owned_json, poses +from embodichain.lab._scene_config.feasibility import ( + HeldObject, + PhaseTarget, + PoseSearchVariable, + TaskFeasibilityRequest, + TaskOperationMode, + TaskPhase, +) +from .._validation import _identifier +from ..expansion import SceneVariant +from ._values import digest, finite, names, owned_json, poses __all__ = [ "PoseSearchVariable", @@ -42,230 +49,6 @@ "CandidateEvaluation", ] -_IDENTITY = ( - (1.0, 0.0, 0.0, 0.0), - (0.0, 1.0, 0.0, 0.0), - (0.0, 0.0, 1.0, 0.0), - (0.0, 0.0, 0.0, 1.0), -) - - -@dataclass(frozen=True) -class PoseSearchVariable: - """One XY/yaw displacement applied to a scene group or robot installation. - - Args: - name: Unique variable name. - kind: ``scene`` or ``robot``; robot members are physical robot UIDs. - reference_pose: Group-to-arena Z-up transform, including mounting height. - lower: Lower XY metre / yaw radian displacement bounds. - upper: Upper displacement bounds; equal endpoints fix a parameter. - members: Member UID to member-to-group transforms. All members move - together, preserving dual-arm mounting and support-group relations. - """ - - name: str - kind: Literal["scene", "robot"] - reference_pose: tuple - lower: tuple[float, float, float] - upper: tuple[float, float, float] - members: Mapping[str, tuple] - - def __post_init__(self) -> None: - _identifier(self.name, "variable name") - if self.kind not in ("scene", "robot"): - raise ValueError("variable kind must be scene or robot") - object.__setattr__(self, "reference_pose", _rigid_pose(self.reference_pose)) - lo, hi = finite(self.lower, "lower"), finite(self.upper, "upper") - if len(lo) != 3 or len(hi) != 3 or any(a > b for a, b in zip(lo, hi)): - raise ValueError("bounds require three ordered XY/yaw coordinates") - if hi[2] - lo[2] > 2 * math.pi + 1e-10: - raise ValueError("yaw interval must span at most one turn") - object.__setattr__(self, "lower", lo) - object.__setattr__(self, "upper", hi) - object.__setattr__(self, "members", poses(self.members)) - if not self.members: - raise ValueError("variables require explicit member UIDs") - - -@dataclass(frozen=True) -class PhaseTarget: - """One simultaneous TCP target in an explicit arena or entity frame. - - Args: - control_part: Explicit solver name, preserving custom names. - pose: TCP-to-frame rigid transform. - frame_uid: Entity frame UID, or ``None`` for the arena frame. - """ - - control_part: str - pose: tuple - frame_uid: str | None = None - - def __post_init__(self) -> None: - _identifier(self.control_part, "control_part") - object.__setattr__(self, "pose", _rigid_pose(self.pose)) - if self.frame_uid is not None: - _identifier(self.frame_uid, "frame_uid") - - -@dataclass(frozen=True) -class HeldObject: - """Rigid attachment during travel; never a physical-success assertion. - - Args: - entity_uid: Held object UID. - control_part: Owner TCP/control part. - tcp_from_object: Object-to-TCP transform used by collision FK. - """ - - entity_uid: str - control_part: str - tcp_from_object: tuple = _IDENTITY - - def __post_init__(self) -> None: - _identifier(self.entity_uid, "held entity") - _identifier(self.control_part, "held owner") - object.__setattr__(self, "tcp_from_object", _rigid_pose(self.tcp_from_object)) - - -@dataclass(frozen=True) -class TaskPhase: - """A synchronized stage and its explicit planning-state transition. - - Args: - phase_id: Stable stage identity. - targets: Simultaneous targets, at most one per control part. - dependencies: Predecessors; input order must be a topological order. - held_objects: Attachments during incoming motion, one owner per object. - allowed_contacts: Physical collision IDs allowed to touch in this stage. - resulting_poses: Projected object states after this stage, used only for - subsequent planning; runtime must still read fresh physical state. - joint_targets: Explicit joint-name commands, e.g. open/closed fingers. - """ - - phase_id: str - targets: tuple[PhaseTarget, ...] = () - dependencies: tuple[str, ...] = () - held_objects: tuple[HeldObject, ...] = () - allowed_contacts: tuple[tuple[str, str], ...] = () - resulting_poses: tuple[ScenePoseChange, ...] = () - joint_targets: tuple[tuple[str, float], ...] = () - - def __post_init__(self) -> None: - _identifier(self.phase_id, "phase_id") - for attr, cls in ( - ("targets", PhaseTarget), - ("held_objects", HeldObject), - ("resulting_poses", ScenePoseChange), - ): - values = tuple(getattr(self, attr)) - if any(not isinstance(v, cls) for v in values): - raise TypeError(f"{attr} contains an invalid contract") - object.__setattr__(self, attr, values) - names([v.control_part for v in self.targets], "phase target parts") - names([v.entity_uid for v in self.held_objects], "held objects") - names([v.entity_uid for v in self.resulting_poses], "resulting poses") - object.__setattr__( - self, "dependencies", names(self.dependencies, "dependencies") - ) - pairs = tuple( - tuple(sorted(names(pair, "contact pair"))) for pair in self.allowed_contacts - ) - if any(len(p) != 2 for p in pairs) or len(set(pairs)) != len(pairs): - raise ValueError("allowed contacts require unique distinct pairs") - object.__setattr__(self, "allowed_contacts", pairs) - joints = tuple( - (_identifier(k, "joint target"), finite((v,), "joint target")[0]) - for k, v in self.joint_targets - ) - names([k for k, _ in joints], "joint targets") - object.__setattr__(self, "joint_targets", joints) - - -@dataclass(frozen=True) -class TaskOperationMode: - """One permitted grasp/assignment/handover branch of the original task.""" - - mode_id: str - phases: tuple[TaskPhase, ...] - - def __post_init__(self) -> None: - _identifier(self.mode_id, "mode_id") - values = tuple(self.phases) - if not values or any(not isinstance(v, TaskPhase) for v in values): - raise ValueError("modes require explicit task phases") - names([v.phase_id for v in values], "phase IDs") - seen = set() - for phase in values: - if not set(phase.dependencies) <= seen: - raise ValueError("phases must be in dependency order without cycles") - seen.add(phase.phase_id) - object.__setattr__(self, "phases", values) - - -@dataclass(frozen=True) -class TaskFeasibilityRequest: - """Versioned fixed semantics, robot, scene, and allowed joint search domain. - - Args: - task_id: Semantic identity including original roles/goals/invariants. - robot_profile_id: Robot, tool and calibrated configuration identity. - policy_id: Planner/runtime policy version. - validator_id: Measured acceptance version. - parent_scene_id: Base scene revision/content identity. - entity_poses: Authored arena poses, including every variable member. - variables: Permitted scene and mounting changes. - modes: Allowed operation modes, preserving resource constraints. - """ - - task_id: str - robot_profile_id: str - policy_id: str - validator_id: str - parent_scene_id: str - entity_poses: Mapping[str, tuple] - variables: tuple[PoseSearchVariable, ...] - modes: tuple[TaskOperationMode, ...] - - def __post_init__(self) -> None: - for key in ( - "task_id", - "robot_profile_id", - "policy_id", - "validator_id", - "parent_scene_id", - ): - _identifier(getattr(self, key), key) - object.__setattr__(self, "entity_poses", poses(self.entity_poses)) - variables, modes = tuple(self.variables), tuple(self.modes) - if any(not isinstance(v, PoseSearchVariable) for v in variables): - raise TypeError("variables require PoseSearchVariable values") - if not modes or any(not isinstance(v, TaskOperationMode) for v in modes): - raise ValueError("request requires explicit operation modes") - names([v.name for v in variables], "variable names") - members = [k for v in variables for k in v.members] - names(members, "variable members") - if not set(members) <= self.entity_poses.keys(): - raise ValueError("variable members must exist in the authored scene") - names([v.mode_id for v in modes], "mode IDs") - for mode in modes: - for phase in mode.phases: - referenced = { - t.frame_uid for t in phase.targets if t.frame_uid is not None - } - referenced |= {h.entity_uid for h in phase.held_objects} - referenced |= {p.entity_uid for p in phase.resulting_poses} - if not referenced <= self.entity_poses.keys(): - raise ValueError("phase refers to an undeclared entity") - object.__setattr__(self, "variables", variables) - object.__setattr__(self, "modes", modes) - - @cached_property - def request_id(self) -> str: - """Return the content identity of all fixed conditions and permissions.""" - return digest(self) - @dataclass(frozen=True) class RobotDeploymentCandidate: diff --git a/embodichain/lab/sim/scene/feasibility/persistence.py b/embodichain/lab/sim/scene/feasibility/persistence.py index b8d3e5b135..1e47b696e8 100644 --- a/embodichain/lab/sim/scene/feasibility/persistence.py +++ b/embodichain/lab/sim/scene/feasibility/persistence.py @@ -19,21 +19,15 @@ from __future__ import annotations from collections.abc import Mapping -from dataclasses import fields from pathlib import Path import json import numpy as np +from embodichain.lab._scene_config.feasibility import _closed, request_from_mapping from ..expansion import ScenePoseChange, SceneVariant from ._values import atomic_json, digest, plain from .cfg import SceneRobotFeasibilityCfg from .contracts import ( - PoseSearchVariable, - PhaseTarget, - HeldObject, - TaskPhase, - TaskOperationMode, - TaskFeasibilityRequest, RobotDeploymentCandidate, JointSceneCandidate, CandidateEvaluation, @@ -49,46 +43,6 @@ __all__ = ["request_from_mapping", "save_feasibility_atlas", "load_feasibility_atlas"] -def _closed(cls: type, value: Mapping[str, object]) -> dict: - if not isinstance(value, Mapping): - raise ValueError(f"{cls.__name__} requires a mapping") - unknown = set(value) - {f.name for f in fields(cls)} - if unknown: - raise ValueError(f"Unknown {cls.__name__} fields: {sorted(unknown)}") - return dict(value) - - -def request_from_mapping(value: Mapping[str, object]) -> TaskFeasibilityRequest: - """Decode a provider-independent request through closed production contracts. - - Args: - value: JSON/YAML task, scene, mounting and phase declarations. - Returns: - Validated immutable request. No dotted import or model client is loaded. - """ - data = _closed(TaskFeasibilityRequest, value) - data["variables"] = tuple( - PoseSearchVariable(**_closed(PoseSearchVariable, v)) for v in data["variables"] - ) - modes = [] - for mode in data["modes"]: - m = _closed(TaskOperationMode, mode) - phases = [] - for phase in m["phases"]: - p = _closed(TaskPhase, phase) - for key, cls in ( - ("targets", PhaseTarget), - ("held_objects", HeldObject), - ("resulting_poses", ScenePoseChange), - ): - p[key] = tuple(cls(**_closed(cls, v)) for v in p.get(key, ())) - phases.append(TaskPhase(**p)) - m["phases"] = tuple(phases) - modes.append(TaskOperationMode(**m)) - data["modes"] = tuple(modes) - return TaskFeasibilityRequest(**data) - - def save_feasibility_atlas(atlas: FeasibilityAtlas, path: str | Path) -> None: """Atomically publish a frozen, content-addressed evidence snapshot. diff --git a/embodichain/lab/task_program/integrations/feasibility.py b/embodichain/lab/task_program/integrations/feasibility.py index f422c48727..279b2e5f3b 100644 --- a/embodichain/lab/task_program/integrations/feasibility.py +++ b/embodichain/lab/task_program/integrations/feasibility.py @@ -93,6 +93,14 @@ def __init__( self.events.append((data["event_id"], conditions, steps)) if len({e[0] for e in self.events}) != len(self.events): raise ValueError("event IDs must be unique") + event_conditions = ( + condition for _, conditions, _ in self.events for condition in conditions + ) + self._transport_guards = { + json.dumps(condition, sort_keys=True): condition + for condition in (*self.final_checks, *event_conditions) + if condition["kind"] == "transport_guard" + } self.initial_heights = {} self._index = 0 self._steps = 0 @@ -434,10 +442,7 @@ def batch_scope( def observe(self, env: Any, action: Any) -> None: """Record consecutive event predicates at actual control boundaries.""" self._steps += 1 - for condition in self.final_checks: - if condition["kind"] != "transport_guard": - continue - key = json.dumps(dict(condition), sort_keys=True) + for key, condition in self._transport_guards.items(): lifted, dropped = self._transport.get(key, (False, False)) pose = env.sim.get_rigid_object(condition["entity"]).get_local_pose()[ self.env_id, :3 diff --git a/tests/gym/envs/task_program/test_feasibility.py b/tests/gym/envs/task_program/test_feasibility.py index 9a62f0a910..e61087f2d2 100644 --- a/tests/gym/envs/task_program/test_feasibility.py +++ b/tests/gym/envs/task_program/test_feasibility.py @@ -99,6 +99,44 @@ def test_monitor_requires_measured_lift_then_stable_terminal_and_rejects_reverse assert not monitor.validation(env).accepted +@pytest.mark.parametrize("drop", [False, True]) +def test_event_only_transport_guard_uses_earlier_measured_boundaries(drop): + env, cube = environment() + goal = Cube() + goal.position[0, 0] = 0.5 + objects = {"cube": cube, "goal": goal} + env.sim.get_rigid_object_uid_list = lambda: tuple(objects) + env.sim.get_rigid_object = objects.get + arrived = { + "kind": "pose_near", + "entity": "cube", + "position": [0.5, 0.0, 0.025], + "tolerance_m": 0.01, + } + transport = { + "kind": "transport_guard", + "entity": "cube", + "other": "goal", + "lift_height_m": 0.05, + "minimum_transit_height_m": 0.025, + "goal_tolerance_m": 0.03, + } + monitor = MeasuredTaskMonitor( + (arrived,), + ({"event_id": "transported", "conditions": [arrived, transport]},), + ) + monitor.reset(env) + cube.position[0, 2] = 0.1 + monitor.observe(env, None) + assert not monitor.receipts + if drop: + cube.position[0, 2] = 0.025 + monitor.observe(env, None) + cube.position[:] = goal.position + monitor.observe(env, None) + assert monitor.validation(env).accepted is not drop + + def test_monitor_reads_physical_velocity_and_closed_schema(): env, cube = environment() monitor = MeasuredTaskMonitor( diff --git a/tests/lab/expansion/test_configured.py b/tests/lab/expansion/test_configured.py index 94bb78c69f..efb844a7a7 100644 --- a/tests/lab/expansion/test_configured.py +++ b/tests/lab/expansion/test_configured.py @@ -49,6 +49,40 @@ def test_task_program_declarations_are_pure_and_protect_contact_phases(tmp_path) load_task_program_expansion(invalid) +def test_official_layout_jobs_load_without_simulation_imports(): + import subprocess + import sys + + task_root = ( + Path(__file__).resolve().parents[3] + / "extensions/embodichain_tasks/configs/tasks/manipulation" + ) + paths = sorted(task_root.glob("**/acceptance/scene_first/expansion.yaml")) + assert paths + code = """ +import importlib.abc +import sys + +class NoSimulator(importlib.abc.MetaPathFinder): + def find_spec(self, fullname, path=None, target=None): + if fullname.startswith(("dexsim", "embodichain.lab.sim", "embodichain.lab.gym")): + raise AssertionError(f"configuration loader imported {fullname}") + +sys.meta_path.insert(0, NoSimulator()) +from embodichain.lab.expansion import load_task_program_expansion +for path in sys.argv[1:]: + sampling = load_task_program_expansion(path)["scene_sampling"] + assert sampling["layout"]["policy"] and sampling["task_mode"]["phases"] + assert sampling["robot_anchors"] +""" + result = subprocess.run( + [sys.executable, "-c", code, *map(str, paths)], + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stderr + + @pytest.mark.parametrize("name", ["default", "newton", "rgbd", "motion"]) def test_example_preflight_resolves_owned_backend_and_budget(name, tmp_path): path = ( diff --git a/tests/lab/expansion/test_distribution.py b/tests/lab/expansion/test_distribution.py index 3e6d07a7a3..0a04e75923 100644 --- a/tests/lab/expansion/test_distribution.py +++ b/tests/lab/expansion/test_distribution.py @@ -60,6 +60,55 @@ def test_missing_layout_is_not_zero(): assert r["joint"] == {} +@pytest.mark.parametrize( + ("tasks", "source_uuids", "matches"), + [ + (("program-a", "program-b"), ("source-a", "source-b"), False), + (("program-a", "program-a"), ("source-a", "source-b"), True), + ((None, None), ("source-a", "source-b"), False), + ((None, None), ("source-a", "source-a"), True), + ], +) +def test_report_requires_matching_recorded_task_identity( + tmp_path, monkeypatch, tasks, source_uuids, matches +): + from types import SimpleNamespace + import torch + from embodichain.lab.expansion import report_expansion_distribution + from embodichain.lab.expansion import persistence + + jobs = [tmp_path / name for name in ("before", "after")] + episodes = {} + for job, task_id, source_uuid in zip(jobs, tasks, source_uuids, strict=True): + job.mkdir() + (job / "job.json").write_text("{}") + metadata = {"instruction": "Pick and place", "source_episode_uuid": source_uuid} + if task_id is not None: + metadata["scene_case"] = {"task_id": task_id} + episodes[job.name] = SimpleNamespace( + episode_id=f"episode-{job.name}", + commit_id=f"commit-{job.name}", + metadata=metadata, + timestamps=torch.tensor([0.0, 1.0]), + observations={}, + validation=SimpleNamespace(accepted=True), + ) + monkeypatch.setattr( + persistence.ArtifactEpisodeSink, + "inspect", + lambda self: (SimpleNamespace(confirmed=True, storage_id=self.directory.name),), + ) + monkeypatch.setattr(persistence, "load_expansion_episode", episodes.__getitem__) + output = tmp_path / "report" + if matches: + report = report_expansion_distribution(jobs[:1], jobs[1:], output, entity="mug") + assert (report["before"], report["after"]) == (1, 1) + else: + with pytest.raises(ValueError, match="matching domain"): + report_expansion_distribution(jobs[:1], jobs[1:], output, entity="mug") + assert not output.exists() + + def test_orientation_sign_and_out_of_plane_rotation(): from embodichain.lab.expansion._distribution_pose import orientation diff --git a/tests/lab/expansion/test_gym_workloads.py b/tests/lab/expansion/test_gym_workloads.py index 0c7737e906..820bdd5ee2 100644 --- a/tests/lab/expansion/test_gym_workloads.py +++ b/tests/lab/expansion/test_gym_workloads.py @@ -96,16 +96,69 @@ def test_expired_warming_row_finishes_group_without_disturbing_live_peer( assert executor.live[1] is peer -def test_native_source_retires_expired_attempt_before_reading_world(): +@pytest.mark.parametrize("stop", ["wall_time_exhausted", "rollout_budget_exhausted"]) +def test_native_source_retires_exhausted_attempt_before_reading_world(stop): + from embodichain.lab.expansion.contracts import ( + EpisodeCandidate, + SceneCase, + ValidationCheck, + ValidationResult, + ) from embodichain.lab.expansion.session import ExpansionSession from embodichain.lab.expansion.session_cfg import ExpansionSessionCfg clock = [0.0] session = ExpansionSession( - ExpansionSessionCfg.from_mapping({"collection": {"max_wall_time_s": 0.01}}), + ExpansionSessionCfg.from_mapping( + { + "collection": { + "max_wall_time_s": 0.01, + "target_committed_episodes": 2, + "max_proposals": 3, + "max_rollout_attempts": 2, + }, + "execution": {"ready_high_watermark": 3, "ready_low_watermark": 0}, + "persistence": {"pending_episode_limit": 2, "pending_max_bytes": 4096}, + } + ), clock=lambda: clock[0], ) - clock[0] = 1.0 + if stop == "wall_time_exhausted": + clock[0] = 1.0 + else: + session.register_case( + SceneCase("case", "initial", "scene", "task", "robot"), + torch.tensor([[-1.0, 1.0]]), + joint_names=("joint",), + ) + passed = ValidationResult( + ( + ValidationCheck("path_collision", "passed"), + ValidationCheck("task_success", "passed"), + ) + ) + identities = [] + for index in range(2): + identity, _ = session.propose( + "case", + "initial", + source_id="source", + source_revision="revision", + template_id=f"recipe-{index}", + operator_id="episode", + ) + session.add_prepared_episode(EpisodeCandidate(identity, "{}"), passed) + assert ( + session.take_ready("case", "initial", episode_byte_budget=1024) + is not None + ) + session.mark_rollout_started(identity) + identities.append(identity) + session.release(identities[0], reason="rejected") + assert session.stop_reason is None + session.release(identities[1], reason="rejected") + assert session.stop_reason == stop + proposed = session.snapshot()["counts"]["proposed"] request = object() journal = Mock() ctx = SimpleNamespace(requests={0: request}, journal=journal) @@ -119,12 +172,14 @@ def test_native_source_retires_expired_attempt_before_reading_world(): } assert source.activate(WorkloadAssignment("expired", 0, 0, 0), None) is None journal.update.assert_called_once_with( - request, status="initial_rejected", reason="wall_time_exhausted" + request, status="initial_rejected", reason=stop ) - assert session.snapshot()["counts"]["proposed"] == 0 + assert session.snapshot()["counts"]["proposed"] == proposed -@pytest.mark.parametrize("stop", ["wall_time_exhausted", "unexpected"]) +@pytest.mark.parametrize( + "stop", ["wall_time_exhausted", "rollout_budget_exhausted", "unexpected"] +) def test_admission_expiry_race_only_suppresses_budget_exhaustion(stop): session = SimpleNamespace(stop_reason=None, register_case=Mock()) @@ -162,7 +217,7 @@ def propose(*args, **kwargs): source.activation_snapshot = (SimpleNamespace(batches={0: ()}), {}) source.env = SimpleNamespace(robot=SimpleNamespace(uid="robot")) assignment = WorkloadAssignment("group", 0, 0, 0) - if stop == "wall_time_exhausted": + if stop != "unexpected": assert source.activate(assignment, None) is None assert ctx.journal.update.call_args.kwargs["reason"] == stop else: diff --git a/tests/lab/expansion/test_scene_first_sampling.py b/tests/lab/expansion/test_scene_first_sampling.py index 76c4ce805f..85f8b6ba5b 100644 --- a/tests/lab/expansion/test_scene_first_sampling.py +++ b/tests/lab/expansion/test_scene_first_sampling.py @@ -37,6 +37,7 @@ def setup_source( member_yaw=False, workspace=None, bounded_fixed_root=False, + configure=None, ): import embodichain.lab.expansion._scene_first_sampling as module @@ -187,6 +188,8 @@ def screen(mode, backend, poses, budget): opts["scene_sampling"]["layout"]["policy"]["intra_group"] = { "targets": {"mug": {"yaw_delta_range_deg": [30, 30]}} } + if configure is not None: + configure(opts, objects) validate_sampling(opts) return ( _LayoutPoseSource(env, opts, seed=7, revision="test-source"), @@ -388,6 +391,50 @@ def test_fixed_layout_geometry_cannot_be_moved_by_a_bounded_draw(monkeypatch): assert source._events[0]["reason"] == "layout_moves_fixed_entity" +def test_external_follower_uses_final_layout_parent_pose(monkeypatch): + def configure(opts, objects): + opts["scene"]["reference"] = {"follow": "tray"} + objects["reference"] = SimpleNamespace( + cfg=SimpleNamespace(to_dict=lambda: {"uid": "reference"}), + get_local_pose=lambda to_matrix=True: torch.eye(4)[None], + ) + opts["scene_sampling"]["layout"]["conditions"]["tray"][0][3] += 0.05 + + source, checked, _ = setup_source(monkeypatch, configure=configure) + candidate = source.candidate(0) + assert source.validate(0).accepted + poses = { + c.entity_uid: np.asarray(c.arena_pose) for c in candidate.scene.pose_changes + } + np.testing.assert_allclose(poses["reference"][:3, 3], [0.05, 0, 0], atol=1e-9) + np.testing.assert_allclose(checked[0]["reference"], poses["reference"]) + + +@pytest.mark.parametrize("authored", [False, True]) +def test_outside_layout_bounds_rejects_sample_but_invalidates_authored_anchor( + monkeypatch, authored +): + def configure(opts, objects): + opts["scene"]["tray"]["translation_m"][0] = [0.075, 0.075] + layout = opts["scene_sampling"]["layout"] + layout["policy"]["group_xy_offset_bounds_m"]["tray"][1][0] = 0.06 + if authored: + layout["conditions"]["tray"][0][3] += 0.075 + else: + layout["conditions"] = {} + + if authored: + with pytest.raises(ValueError, match="outside declared root XY bounds"): + setup_source(monkeypatch, strategy="bounded_pose", configure=configure) + else: + source, checked, _ = setup_source( + monkeypatch, strategy="bounded_pose", configure=configure + ) + source.candidate(0) + assert not source.validate(0).accepted and not checked + assert source._events[0]["reason"] == "layout_outside_sampled_domain" + + def test_member_layout_yaw_cannot_expand_the_task_domain(monkeypatch): source, checked, _ = setup_source(monkeypatch, member_yaw=True) source.candidate(0) From f38aacba9d82e956ea277a01dad9faffe3c08715 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Wed, 18 Nov 2026 06:31:09 +0000 Subject: [PATCH 39/49] fix(expansion): preserve admission deadlines for active rollouts --- .../topics/expansion-engine/workloads.md | 4 +++ embodichain/lab/expansion/_pose_sampling.py | 26 ++++++++++++++++ embodichain/lab/expansion/gym_workloads.py | 6 +++- .../lab/expansion/test_task_pose_coverage.py | 31 +++++++++++++++++++ 4 files changed, 66 insertions(+), 1 deletion(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index 1ef5208038..3121786f51 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -195,6 +195,10 @@ candidate streams and proposal streams still use the expansion seed/ordinal; the reference manifest records both seeds. This prevents a sampler comparison from silently changing the nominal scene's reset randomization and moving its declared local domain. Rolling resets use the same explicit nominal reset seed. +The raw pose budget enforces the original admission deadline. An admitted +trajectory's planning view retains shared IK/planning call limits and explicit +cancellation without treating that deadline as a new mid-trajectory hard stop. +The original max_steps, physical checks and safe-stop handshake still apply. `_pose_sampling.py` owns bounded candidate snapshots, source feedback and budgets; `task_pose_coverage.TaskPoseCoverage` implements the session coverage protocol. Measured rigid initial/terminal poses contribute only after native sink receipts. diff --git a/embodichain/lab/expansion/_pose_sampling.py b/embodichain/lab/expansion/_pose_sampling.py index f4c0090353..63694b1263 100644 --- a/embodichain/lab/expansion/_pose_sampling.py +++ b/embodichain/lab/expansion/_pose_sampling.py @@ -109,6 +109,9 @@ class _PoseBudget(FeasibilityBudget): def charge(self, kind: str, amount: int = 1) -> None: self.check() + self._reserve(kind, amount) + + def _reserve(self, kind: str, amount: int = 1) -> None: if type(amount) is not int or amount < 1: raise ValueError("Budget charges must be positive integers") limits = { @@ -123,6 +126,28 @@ def charge(self, kind: str, amount: int = 1) -> None: self.counts[kind] += amount +class _AdmittedPoseBudget: + """Retain shared call limits/cancellation after the admission deadline. + + Already admitted trajectories still have the host's original max_steps and + bridge safe-stop rules. The source's raw budget alone admits new work. + """ + + def __init__(self, budget: _PoseBudget) -> None: + self.budget = budget + + def check(self) -> None: + budget = self.budget + if budget._blocked is not None and budget._blocked[0] == budget.validation: + raise FeasibilityBudgetExhausted(budget._blocked[1]) + if budget.cancelled is not None and budget.cancelled.is_set(): + raise FeasibilityBudgetExhausted("cancelled") + + def charge(self, kind: str, amount: int = 1) -> None: + self.check() + self.budget._reserve(kind, amount) + + class _AdaptivePoseSource(_BoundedPoseSource): """One bounded proposal stream; candidates never change after allocation.""" @@ -183,6 +208,7 @@ def __init__(self, env, options, *, seed, revision): self.budget.validation = ( True # Use the full host allocation, not search/held-out splitting. ) + self.planning_budget = _AdmittedPoseBudget(self.budget) self._candidates = {} self._checks = {} self._predicted = {} diff --git a/embodichain/lab/expansion/gym_workloads.py b/embodichain/lab/expansion/gym_workloads.py index 20a58221d2..8327074e25 100644 --- a/embodichain/lab/expansion/gym_workloads.py +++ b/embodichain/lab/expansion/gym_workloads.py @@ -127,7 +127,11 @@ def __init__( def planning_budget(self, assignment): feedback = self.groups[assignment.workload_id]["host"]._context.feedback - return None if feedback is None else feedback.budget + return ( + None + if feedback is None + else getattr(feedback, "planning_budget", feedback.budget) + ) def can_admit(self, name): feedback = self.groups[name]["host"]._context.feedback diff --git a/tests/lab/expansion/test_task_pose_coverage.py b/tests/lab/expansion/test_task_pose_coverage.py index 9c008eb475..23a8adf3ae 100644 --- a/tests/lab/expansion/test_task_pose_coverage.py +++ b/tests/lab/expansion/test_task_pose_coverage.py @@ -34,6 +34,37 @@ from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted +def test_admitted_planning_retains_count_and_cancel_limits_after_admission_time(): + from threading import Event + import time + from embodichain.lab.expansion._pose_sampling import ( + _PoseBudget, + _AdmittedPoseBudget, + ) + from embodichain.lab.sim.scene.feasibility import SceneRobotFeasibilityCfg + + cancellation = Event() + budget = _PoseBudget( + SceneRobotFeasibilityCfg(max_wall_time_s=0.01, max_ik_calls=2), + cancelled=cancellation, + ) + budget.validation = True + admitted = _AdmittedPoseBudget(budget) + time.sleep(0.03) + with pytest.raises(FeasibilityBudgetExhausted, match="wall_time"): + budget.charge("candidates") + admitted.check() + admitted.charge("ik") + assert budget.counts["ik"] == 1 and budget.counts["candidates"] == 0 + cancellation.set() + with pytest.raises(FeasibilityBudgetExhausted, match="cancelled"): + admitted.check() + cancellation.clear() + with pytest.raises(FeasibilityBudgetExhausted, match="ik_budget"): + admitted.charge("ik", 2) + assert budget.counts["ik"] == 1 + + def grids(): return { phase: { From 93c4e40d79b8d11361bcec6640adbf7de2f392f6 Mon Sep 17 00:00:00 2001 From: matafela Date: Thu, 19 Nov 2026 10:59:38 +0800 Subject: [PATCH 40/49] feat(expansion): compare trajectory ghosts against a fixed reference --- .../expansion-engine/expansion-engine.md | 16 +- embodichain/cli/expansion.py | 5 +- embodichain/lab/expansion/_preview.html | 139 +++++++++-- embodichain/lab/expansion/_preview_charts.js | 199 ++++++++++++++++ embodichain/lab/expansion/_preview_data.py | 136 +++++++---- .../lab/expansion/_preview_deviations.py | 196 +++++++++++++++ embodichain/lab/expansion/_preview_heatmap.js | 169 +++++++++++++ embodichain/lab/expansion/_preview_heatmap.py | 95 ++++++++ embodichain/lab/expansion/_preview_render.py | 133 +++++------ embodichain/lab/expansion/_preview_server.py | 21 ++ examples/expansion/engine/ghost-preview.md | 42 +++- .../expansion/ur5_pick_place/README.md | 56 +++++ .../ur5_pick_place/assets/deviation-bands.png | Bin 0 -> 80078 bytes .../ur5_pick_place/assets/object-heatmap.png | Bin 0 -> 56301 bytes .../ur5_pick_place/assets/replay-before.jpg | Bin 0 -> 131978 bytes .../ur5_pick_place/assets/replay-ghosts.jpg | Bin 0 -> 129489 bytes .../expansion/ur5_pick_place/collect.py | 77 ++++++ .../expansion/ur5_pick_place/expansion.yaml | 122 ++++++++++ setup.py | 7 +- tests/lab/expansion/test_preview.py | 223 +++++++++++++++++- 20 files changed, 1466 insertions(+), 170 deletions(-) create mode 100644 embodichain/lab/expansion/_preview_charts.js create mode 100644 embodichain/lab/expansion/_preview_deviations.py create mode 100644 embodichain/lab/expansion/_preview_heatmap.js create mode 100644 embodichain/lab/expansion/_preview_heatmap.py create mode 100644 scripts/tutorials/expansion/ur5_pick_place/README.md create mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png create mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png create mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg create mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/replay-ghosts.jpg create mode 100644 scripts/tutorials/expansion/ur5_pick_place/collect.py create mode 100644 scripts/tutorials/expansion/ur5_pick_place/expansion.yaml diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 84c13178ee..3d698b19bc 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -105,9 +105,19 @@ then replays full measured states using `_preview_render.py` and a loopback-only physics stepping occurs. It accepts one URDF robot and recorded rigid visual objects (including file Mesh/USD via native visual loading), with fixed layouts; unsupported geometry is rejected. Constant static backgrounds remain single -instances. Space filters group -input directories; missing motion annotations remain explicit. HTTP publishes a -single immutable image/state snapshot; WebRTC is follow-up work. FK and episode +instances. The solid robot and objects always follow the explicit reference, +or the first input recording when a reference is absent. The play button and +Space key toggle playback. Candidate buttons toggle individual ghosts. See the +[UR5 layout and grasp tutorial](../../../scripts/tutorials/expansion/ur5_pick_place/README.md) +for collection and replay. Filters preserve each toggle and playback of the solid +trajectory. Space filters group input directories and missing motion annotations +remain explicit. `_preview_deviations.py` reuses recorded world FK and gripper +calibration for TCP errors. At each reference time it reports the minimum, mean +and maximum across recordings still in range for TCP translation distance, +TCP rotation angle and each episode's worst joint deviation. `_preview_heatmap.py` +counts distinct recordings per rigid object's measured XY cell, including the solid +reference, for the full recording and its first and last frame. The HTTP service +publishes both chart datasets independently of the live image/state snapshots. FK and episode budgets bound preload, controls are queued for the render owner, and native resources/ports close on exit. See the example's `ghost-preview.md` for usage. diff --git a/embodichain/cli/expansion.py b/embodichain/cli/expansion.py index d3774a65d8..bc61368128 100644 --- a/embodichain/cli/expansion.py +++ b/embodichain/cli/expansion.py @@ -82,7 +82,10 @@ def main(argv: Sequence[str] | None = None) -> int: ) command.add_argument( "--reference", - help="Optional result directory containing exactly one reference episode", + help=( + "Job directory containing one confirmed original trajectory for solid " + "playback. Defaults to the first loaded input recording as a comparison." + ), ) command.add_argument( "--robot-asset", help="Matching URDF override if recorded asset paths moved" diff --git a/embodichain/lab/expansion/_preview.html b/embodichain/lab/expansion/_preview.html index f1615652c9..9453f31c3a 100644 --- a/embodichain/lab/expansion/_preview.html +++ b/embodichain/lab/expansion/_preview.html @@ -1,35 +1,146 @@ EmbodiChain · 扩增结果回放

    EmbodiChain · 扩增结果回放

    完整模型虚影 · 已确认的真实扩增结果

    正在连接原生渲染器
    -
    拖动画面旋转 · 滚轮缩放
    EmbodiChain 原生场景渲染画面
    正在加载完整机器人模型…
    ——
    +
    空格 播放 / 暂停 · 拖动画面旋转 · 滚轮缩放
    EmbodiChain 原生场景渲染画面
    正在加载完整机器人模型…
    ——
    +

    场景图层

    +
    +
    +
    +
    +
    实色模型始终播放固定对照。点击轨迹按钮可分别显示或隐藏对应的虚影。
    +

    真实执行记录

    等待渲染结果…
    +
    +
    +

    扩增轨迹偏差

    正在读取统计曲线…

    + +
    + +
    +
    +

    物体位置分布热力图

    +

    正在读取物体位置…

    + +
    EmbodiChain SimulationManager / RobotMarkers / VisualizationMarkers → DexSim Hybrid 原生渲染。仅回放,物理推进 0 步。机器人与物体使用逐帧记录;轨迹线每 4 帧取点并连接。视角、灯光与透明材质仅用于验收展示。
    + + \ No newline at end of file + diff --git a/embodichain/lab/expansion/_preview_charts.js b/embodichain/lab/expansion/_preview_charts.js new file mode 100644 index 0000000000..ba150dfcec --- /dev/null +++ b/embodichain/lab/expansion/_preview_charts.js @@ -0,0 +1,199 @@ +// ---------------------------------------------------------------------------- +// Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// ---------------------------------------------------------------------------- + +const deviationCharts = (() => { + const left = 48, right = 12, top = 8, bottom = 24; + const plots = []; + let data, playbackFrame = 0, hoverFrame = null; + const number = new Intl.NumberFormat('zh-CN', {maximumSignificantDigits: 4}); + const description = document.getElementById('deviation-description'); + const readout = document.getElementById('deviation-time'); + + function updateReadout() { + if (!data || !plots.length) return; + const frame = hoverFrame ?? playbackFrame; + const time = data.time_s[frame]; + const fraction = time / data.time_s.at(-1); + readout.textContent = `${number.format(time)} s · ${data.count[frame]} / ${data.episodes} 条轨迹`; + for (const plot of plots) { + const value = plot.values[frame]; + const format = v => `${number.format(v)} ${plot.unit}`; + if (value === null) { + plot.value.textContent = '无样本'; + } else if (plot.range) { + plot.value.textContent = `最小 ${format(plot.range.min[frame])} · 均值 ${format(value)} · 最大 ${format(plot.range.max[frame])}`; + } else { + plot.value.textContent = format(value); + } + plot.cursor.style.left = `calc(${fraction * 100}% + ${left - fraction * (left + right)}px)`; + } + } + + function nearestFrame(time) { + let lo = 0, hi = data.time_s.length - 1; + while (lo < hi) { + const mid = Math.floor((lo + hi) / 2); + if (data.time_s[mid] < time) lo = mid + 1; + else hi = mid; + } + if (lo > 0 && time - data.time_s[lo - 1] < data.time_s[lo] - time) return lo - 1; + return lo; + } + + function tickStep(span) { + const target = span / 4; + const magnitude = 10 ** Math.floor(Math.log10(target)); + return magnitude * [1, 2, 2.5, 5, 10].find(step => step * magnitude >= target); + } + + function drawBand(ctx, range, color, x, y) { + // All episodes start at zero. Only the tail can have no samples. + const last = range.max.findLastIndex(value => value !== null); + if (last < 0) return; + ctx.beginPath(); + ctx.moveTo(x(0), y(range.max[0])); + for (let i = 1; i <= last; i++) ctx.lineTo(x(i), y(range.max[i])); + for (let i = last; i >= 0; i--) ctx.lineTo(x(i), y(range.min[i])); + ctx.closePath(); + ctx.fillStyle = `${color}40`; + ctx.fill(); + ctx.strokeStyle = `${color}99`; + ctx.stroke(); + } + + function draw(plot) { + const canvas = plot.canvas; + const width = canvas.clientWidth, height = canvas.clientHeight; + if (width <= left + right || height <= top + bottom) return; + const scale = window.devicePixelRatio || 1; + canvas.width = Math.round(width * scale); + canvas.height = Math.round(height * scale); + const ctx = canvas.getContext('2d'); + ctx.scale(scale, scale); + const w = width - left - right, h = height - top - bottom; + const duration = data.time_s.at(-1); + ctx.font = '11px system-ui, sans-serif'; + ctx.lineWidth = 1; + ctx.textBaseline = 'middle'; + ctx.strokeStyle = '#384451'; + ctx.fillStyle = '#adbdcb'; + ctx.textAlign = 'right'; + for (let i = 0; i <= plot.ticks; i++) { + const y = top + h * (1 - i / plot.ticks); + ctx.beginPath(); + ctx.moveTo(left, y); + ctx.lineTo(width - right, y); + ctx.stroke(); + ctx.fillText(number.format(i * plot.step), left - 5, y, left - 6); + } + const seconds = tickStep(duration); + for (let i = 0; i <= Math.floor(duration / seconds); i++) { + const fraction = i * seconds / duration; + ctx.textAlign = fraction > 0.95 ? 'right' : 'center'; + ctx.fillText(`${number.format(i * seconds)} s`, left + w * fraction, height - 9); + } + const x = frame => left + w * data.time_s[frame] / duration; + const y = value => top + h * (1 - value / plot.max); + if (plot.range) drawBand(ctx, plot.range, plot.color, x, y); + ctx.strokeStyle = plot.color; ctx.lineWidth = 2; + ctx.beginPath(); + let previous = false; + for (let i = 0; i < plot.values.length; i++) { + const value = plot.values[i]; + if (value === null) { + previous = false; + continue; + } + const px = x(i), py = y(value); + if (previous) ctx.lineTo(px, py); + else { + ctx.moveTo(px, py); + ctx.fillStyle = plot.color; + ctx.fillRect(px - 1, py - 1, 2, 2); + } + previous = true; + } + ctx.stroke(); + } + + function addCurve(panel, key, title, unit, color) { + const values = data.mean[key]; + if (!values) return; + const range = data.range?.[key]; + const figure = document.createElement('figure'); + figure.className = 'curve'; figure.style.setProperty('--line', color); + const caption = document.createElement('figcaption'); + const label = document.createElement('span'); + label.textContent = `${title}(${unit})`; + const value = document.createElement('output'); + caption.append(label, value); + const area = document.createElement('div'); + area.className = 'curve-plot'; + const canvas = document.createElement('canvas'); + canvas.setAttribute('role', 'img'); + const summary = range ? '均值曲线及最小值至最大值色带' : '均值曲线'; + canvas.setAttribute('aria-label', `${title}随实测时间的${summary},单位 ${unit}`); + const cursor = document.createElement('i'); + area.append(canvas, cursor); figure.append(caption, area); panel.append(figure); + const peak = (range?.max ?? values).reduce((max, v) => v === null ? max : Math.max(max, v), 0); + const step = tickStep(peak || 1); + const ticks = Math.ceil((peak || 1) / step); + const plot = {values, value, range, unit, color, canvas, cursor, step, ticks, max: step * ticks}; + plots.push(plot); + new ResizeObserver(() => draw(plot)).observe(canvas); + canvas.addEventListener('pointermove', event => { + const rect = canvas.getBoundingClientRect(); + const ratio = Math.min(1, Math.max(0, (event.clientX - rect.left - left) / (rect.width - left - right))); + hoverFrame = nearestFrame(ratio * data.time_s.at(-1)); updateReadout(); + }); + canvas.addEventListener('pointerleave', () => { hoverFrame = null; updateReadout(); }); + } + + async function load() { + try { + const response = await fetch('/deviations'); + if (!response.ok) throw Error('deviations'); + data = await response.json(); + if (!data.episodes) { + description.textContent = '当前只有对照轨迹。加入扩增轨迹即可显示偏差曲线。'; + return; + } + const reference = data.explicit_reference ? '原始轨迹' : '首条对照记录'; + description.textContent = `相对${reference},按实测时间对齐全部 ${data.episodes} 条扩增轨迹。每个时刻只计仍有记录的轨迹。`; + if (Object.keys(data.range ?? {}).length) description.append('色带覆盖最小值至最大值,实线表示均值。'); + document.getElementById('deviation-panels').hidden = false; + const tcp = document.getElementById('tcp-deviations'); + addCurve(tcp, 'translation_mm', '平移距离', 'mm', '#80c7ff'); + addCurve(tcp, 'rotation_deg', '相对旋转角', '°', '#e6af77'); + if (!data.mean.translation_mm) tcp.append('记录中缺少所选机械臂的完整 TCP 标定。'); + const joints = document.getElementById('joint-deviations'); + addCurve(joints, 'qpos_deg', '转动关节最大绝对偏差', '°', '#85d5b8'); + addCurve(joints, 'qpos_mm', '移动关节最大绝对偏差', 'mm', '#c9a9f2'); + const names = Object.values(data.arm_joint_groups).flat(); + const note = document.createElement('p'); + note.textContent = names.length ? `统计关节 · ${names.join('、')}` : '记录中缺少可识别的机械臂关节组。'; + joints.append(note); + updateReadout(); + } catch { + description.textContent = '偏差曲线加载失败,请刷新页面重试。'; + } + } + + load(); + return {setFrame(frame) { + if (frame !== playbackFrame) { playbackFrame = frame; updateReadout(); } + }}; +})(); diff --git a/embodichain/lab/expansion/_preview_data.py b/embodichain/lab/expansion/_preview_data.py index 2fa9ce66d0..409dad699b 100644 --- a/embodichain/lab/expansion/_preview_data.py +++ b/embodichain/lab/expansion/_preview_data.py @@ -18,7 +18,7 @@ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path from typing import Any import json @@ -28,6 +28,7 @@ from .comparison import MeasuredTrajectory from .persistence import ArtifactEpisodeSink, load_expansion_episode +from ._preview_deviations import recorded_coordinates __all__: list[str] = [] @@ -52,6 +53,7 @@ class PreviewClip: label: str = "" links: np.ndarray | None = None tips: np.ndarray | None = None + tcp_frame: tuple[str, np.ndarray] | None = None def annotations(metadata: Any, measured: MeasuredTrajectory) -> dict[str, Any]: @@ -275,6 +277,16 @@ class PreviewData: ground_visible: bool = True coverage: dict[str, Any] | None = None object_specs: dict[str, dict[str, Any]] | None = None + arm_joint_groups: dict[str, list[str]] = field(default_factory=dict) + + @property + def solid_clip(self) -> PreviewClip: + """Pin the supplied reference, or the first input recording for comparison.""" + return self.reference if self.reference is not None else self.clips[0] + + @property + def ghost_indices(self) -> range: + return range(0 if self.reference is not None else 1, len(self.clips)) @property def all_clips(self) -> list[PreviewClip]: @@ -327,6 +339,7 @@ def load_preview( boxes = None robot_spec = None object_specs = None + arm_joint_groups = None end = None ground = True seen = set() @@ -360,8 +373,9 @@ def load_preview( # URDF assembly comments may differ; compare the actual XML model. import xml.etree.ElementTree as ET + model = ET.parse(resolved_asset).getroot() if asset is not None and ET.tostring(ET.parse(asset).getroot()) != ET.tostring( - ET.parse(resolved_asset).getroot() + model ): raise ValueError("Output directories reference different robot models") asset = resolved_asset @@ -376,6 +390,11 @@ def load_preview( "Specify --eef-link when the recorded solver endpoint is ambiguous" ) end = inferred + groups, tcp_frame = recorded_coordinates(robot, end, model) + if arm_joint_groups is None: + arm_joint_groups = groups + elif groups != arm_joint_groups: + arm_joint_groups = {} if group == 0: ground = job["resolved_deployment"].get("ground_plane_visible") is not False elif ground != ( @@ -425,6 +444,7 @@ def load_preview( clip = PreviewClip( measured=measured, space=f"S{group+1} · {path.name}", + tcp_frame=tcp_frame, **annotations(episode.metadata, measured), ) if is_reference: @@ -434,22 +454,28 @@ def load_preview( clips.append(clip) clip.label = f"C-{len(clips):03d}" return PreviewData( - clips, reference_clip, asset, end, boxes, ground, coverage, object_specs + clips, + reference_clip, + asset, + end, + boxes, + ground, + coverage, + object_specs, + arm_joint_groups=arm_joint_groups or {}, ) class PreviewState: def __init__(self, data: PreviewData) -> None: self.data = data + self.enabled_ghosts: set[int] = set() self.values = dict( space="all", aff="all", variant="all", - selected=0, progress=0.0, playing=False, - reference=data.reference is not None, - ghosts=True, paths=True, targets=True, positions=True, @@ -458,10 +484,11 @@ def __init__(self, data: PreviewData) -> None: elevation=0.55, distance=1.65, ) + candidates = [data.clips[i] for i in data.ghost_indices] self.options = { - "space": sorted({c.space for c in data.clips}), - "aff": sorted({c.affordance for c in data.clips}), - "variant": sorted({c.variant for c in data.clips}), + "space": sorted({c.space for c in candidates}), + "aff": sorted({c.affordance for c in candidates}), + "variant": sorted({c.variant for c in candidates}), "align": ["time"] + (["phase"] if data.phase_alignment else []), } @@ -469,18 +496,21 @@ def validate(self, update: Any) -> dict[str, Any]: if ( not isinstance(update, dict) or not update - or set(update) - self.values.keys() + or set(update) + - (self.values.keys() | {"toggle_playback", "toggle_ghost", "ghosts"}) ): raise ValueError("Invalid preview controls") bounds = { - "selected": (0, len(self.data.clips) - 1), "progress": (0, 1), "yaw": (-20, 20), "elevation": (0.1, 1.5), "distance": (0.2, 20), } for key, value in update.items(): - if key in self.options: + if key == "toggle_ghost": + if type(value) is not int or value not in self.data.ghost_indices: + raise ValueError(key) + elif key in self.options: if value not in self.options[key] + ([] if key == "align" else ["all"]): raise ValueError(key) elif key in bounds: @@ -488,7 +518,6 @@ def validate(self, update: Any) -> dict[str, Any]: type(value) not in (float, int) or not math.isfinite(value) or not bounds[key][0] <= value <= bounds[key][1] - or (key == "selected" and type(value) is not int) ): raise ValueError(key) elif type(value) is not bool: @@ -496,28 +525,35 @@ def validate(self, update: Any) -> dict[str, Any]: return dict(update) def apply(self, update: dict[str, Any]) -> None: - self.values.update(self.validate(update)) - visible = self.visible() - if visible and self.values["selected"] not in visible: - self.values["selected"] = visible[0] - if not visible: - self.values["playing"] = False - - def visible(self) -> list[int]: + controls = self.validate(update) + toggle = controls.pop("toggle_ghost", None) + show_matching = controls.pop("ghosts", None) + toggle_playback = controls.pop("toggle_playback", False) + self.values.update(controls) + if toggle_playback: + self.values["playing"] = not self.values["playing"] + if self.values["playing"] and self.values["progress"] >= 1: + self.values["progress"] = 0.0 + if show_matching is True: + self.enabled_ghosts.update(self.matching()) + elif show_matching is False: + self.enabled_ghosts.difference_update(self.matching()) + if toggle is not None: + self.enabled_ghosts.symmetric_difference_update((toggle,)) + + def matching(self) -> list[int]: v = self.values return [ i - for i, c in enumerate(self.data.clips) - if all( - v[k] == "all" or v[k] == actual - for k, actual in [ - ("space", c.space), - ("aff", c.affordance), - ("variant", c.variant), - ] - ) + for i in self.data.ghost_indices + if v["space"] in ("all", self.data.clips[i].space) + and v["aff"] in ("all", self.data.clips[i].affordance) + and v["variant"] in ("all", self.data.clips[i].variant) ] + def visible_ghosts(self) -> list[int]: + return [i for i in self.matching() if i in self.enabled_ghosts] + def frame_at(self, clip: PreviewClip) -> int: p = self.values["progress"] if self.values["align"] == "phase": @@ -533,34 +569,31 @@ def duration(self) -> float: return max(float(c.measured.timestamps[-1]) for c in self.data.all_clips) def snapshot(self) -> dict[str, Any]: - visible = self.visible() - c = self.data.clips[self.values["selected"]] + matching = self.matching() + c = self.data.solid_clip f = self.frame_at(c) return { **self.values, - "visible": visible, - "count": len(visible), - "total": len(self.data.clips), + "visible": matching, + "visible_ghosts": [i for i in matching if i in self.enabled_ghosts], + "count": len(matching), + "total": len(self.data.ghost_indices), "options": self.options, "has_reference": self.data.reference is not None, "coverage": self.data.coverage, - "label": c.label if visible else "No matches", - "source_frame": f if visible else None, - "source_frames": len(c.measured.timestamps) if visible else 0, - "time": float(c.measured.timestamps[f]) if visible else None, - "episode": c.measured.name if visible else "", + "label": c.label, + "source_frame": f, + "source_frames": len(c.measured.timestamps), + "time": float(c.measured.timestamps[f]), + "episode": c.measured.name, "candidate": ", ".join(c.candidate_ids) or "unrecorded", - "phase": ( - next( - ( - name - for name, t in reversed(list(zip(c.phase_names, c.anchors))) - if t <= c.measured.timestamps[f] - ), - "unrecorded", - ) - if visible - else "" + "phase": next( + ( + name + for name, t in reversed(list(zip(c.phase_names, c.anchors))) + if t <= c.measured.timestamps[f] + ), + "unrecorded", ), "clips": [ dict( @@ -571,5 +604,6 @@ def snapshot(self) -> dict[str, Any]: variant=c.variant, ) for i, c in enumerate(self.data.clips) + if i in self.data.ghost_indices ], } diff --git a/embodichain/lab/expansion/_preview_deviations.py b/embodichain/lab/expansion/_preview_deviations.py new file mode 100644 index 0000000000..6180120d13 --- /dev/null +++ b/embodichain/lab/expansion/_preview_deviations.py @@ -0,0 +1,196 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Time-aligned deviations from the fixed reference in the expansion viewer.""" + +from __future__ import annotations + +import re +from typing import TYPE_CHECKING, Any +from xml.etree import ElementTree as ET + +import numpy as np +from scipy.spatial.transform import Rotation, Slerp + +from embodichain.robot_registry import _validate_gripper_transform +from embodichain.utils.string import resolve_matching_names + +if TYPE_CHECKING: + from ._preview_data import PreviewClip, PreviewData + +__all__: list[str] = [] + + +def recorded_coordinates( + robot: dict, endpoint: str, model: ET.Element +) -> tuple[dict[str, list[str]], tuple[str, np.ndarray] | None]: + """Resolve the selected motion group and its own recorded gripper calibration.""" + solvers = robot.get("solver_cfg") or {} + bindings = list((robot.get("gripper_bindings") or {}).values()) + parts = [ + part for part, cfg in solvers.items() if cfg.get("end_link_name") == endpoint + ] + + def motion_part(binding: dict) -> str | None: + declaration = binding.get("declaration") or {} + defaults = binding.get("defaults", {}).get("binding") or {} + return declaration.get("motion_part") or defaults.get("motion_part") + + if len(parts) == 1: + part = parts[0] + matched = [b for b in bindings if motion_part(b) == part] + if len(bindings) == len(solvers) == 1 and motion_part(bindings[0]) is None: + matched = bindings + elif not parts: + matched = [b for b in bindings if b.get("root_link") == endpoint] + if len(matched) != 1: + return {}, None + part = motion_part(matched[0]) + else: + return {}, None + solver = solvers.get(part, {}) + names = solver.get("joint_names") or (robot.get("control_parts") or {}).get(part) + joints = {j.get("name"): j for j in model.findall("joint")} + units = {"continuous": "deg", "revolute": "deg", "prismatic": "mm"} + if names and any(name not in joints for name in names): + try: + _, names = resolve_matching_names( + names, [n for n, j in joints.items() if j.get("type") in units] + ) + except (ValueError, re.error): + names = [] + elif not names: + # Older jobs can declare just the solver's root and end links. + parents = {j.find("child").get("link"): j for j in joints.values()} + link = solver.get("end_link_name") or endpoint + root = solver.get("root_link_name") + path = [] + while link != root and link in parents: + joint = parents.pop(link) + if joint.get("type") != "fixed": + path.append(joint.get("name")) + link = joint.find("parent").get("link") + names = list(reversed(path)) if root is None or link == root else [] + + groups: dict[str, list[str]] = {} + for name in names: + if name not in joints or joints[name].get("type") not in units: + groups = {} + break + groups.setdefault(units[joints[name].get("type")], []).append(name) + + if len(matched) == 1: + binding = matched[0] + offset = binding.get("defaults", {}).get("default_root_from_tcp") + if binding.get("root_link") and offset is not None: + try: + return groups, ( + binding["root_link"], + np.asarray(_validate_gripper_transform(offset)), + ) + except ValueError: + pass # The joint measurements still support a qpos comparison. + return groups, None + + +def _tcp(clip: PreviewClip, links: dict[str, int]) -> np.ndarray: + root, offset = clip.tcp_frame + return clip.links[:, links[root]] @ offset + + +def deviation_curves(data: PreviewData, link_names: list[str]) -> dict[str, Any]: + """Report the range and mean of each deviation on the reference clock.""" + ref = data.solid_clip + times = ref.measured.timestamps + candidates = [data.clips[i] for i in data.ghost_indices] + counts = np.zeros(len(times), dtype=np.int64) + sums = {} + links = {name: i for i, name in enumerate(link_names)} + tcp_available = all( + c.tcp_frame is not None and c.tcp_frame[0] in links for c in (ref, *candidates) + ) + if tcp_available: + original = _tcp(ref, links) + original_inverse = Rotation.from_matrix(original[:, :3, :3]).inv() + sums["translation_mm"] = np.zeros(len(times)) + sums["rotation_deg"] = np.zeros(len(times)) + for unit in data.arm_joint_groups: + sums[f"qpos_{unit}"] = np.zeros(len(times)) + ranges = {key: (np.full(len(times), np.inf), np.zeros(len(times))) for key in sums} + + def accumulate(key: str, values: np.ndarray) -> None: + end = len(values) + sums[key][:end] += values + low, high = ranges[key] + np.minimum(low[:end], values, out=low[:end]) + np.maximum(high[:end], values, out=high[:end]) + + for c in candidates: + sample = c.measured + end = times.searchsorted(sample.timestamps[-1], side="right") + grid = times[:end] + counts[:end] += 1 + if tcp_available: + tcp = _tcp(c, links) + xyz = np.column_stack( + [ + np.interp(grid, sample.timestamps, tcp[:, axis, 3]) + for axis in range(3) + ] + ) + rotations = Slerp(sample.timestamps, Rotation.from_matrix(tcp[:, :3, :3]))( + grid + ) + accumulate( + "translation_mm", + 1000 * np.linalg.norm(xyz - original[:end, :3, 3], axis=1), + ) + accumulate( + "rotation_deg", + np.rad2deg((original_inverse[:end] * rotations).magnitude()), + ) + for unit, names in data.arm_joint_groups.items(): + worst = np.zeros(end) + for name in names: + q = sample.qpos[:, sample.joint_names.index(name)] + q_ref = ref.measured.qpos[:end, ref.measured.joint_names.index(name)] + delta = np.interp(grid, sample.timestamps, q) - q_ref + np.maximum(worst, np.abs(delta), out=worst) + accumulate( + f"qpos_{unit}", np.rad2deg(worst) if unit == "deg" else 1000 * worst + ) + + # Every recording starts at zero, so uncovered reference samples form a tail. + covered = np.count_nonzero(counts) + empty_tail = [None] * (len(times) - covered) + return { + "time_s": times.tolist(), + "count": counts.tolist(), + "episodes": len(candidates), + "explicit_reference": data.reference is not None, + "arm_joint_groups": data.arm_joint_groups, + "mean": { + key: (values[:covered] / counts[:covered]).tolist() + empty_tail + for key, values in sums.items() + }, + "range": { + key: { + "min": low[:covered].tolist() + empty_tail, + "max": high[:covered].tolist() + empty_tail, + } + for key, (low, high) in ranges.items() + }, + } diff --git a/embodichain/lab/expansion/_preview_heatmap.js b/embodichain/lab/expansion/_preview_heatmap.js new file mode 100644 index 0000000000..abb0b7215f --- /dev/null +++ b/embodichain/lab/expansion/_preview_heatmap.js @@ -0,0 +1,169 @@ +// ---------------------------------------------------------------------------- +// Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// ---------------------------------------------------------------------------- + +(() => { + const element = name => document.getElementById('heatmap-' + name); + const canvas = element('plot'); + const ctx = canvas.getContext('2d'); + const objectSelect = element('object'), phaseSelect = element('phase'); + const number = new Intl.NumberFormat('zh-CN', {maximumFractionDigits: 4}); + const meters = (a, b) => `${number.format(a)} ~ ${number.format(b)} m`; + const peak = counts => Math.max(...counts.map(row => Math.max(...row))); + let data, object, view, colors, area, cell = null; + + function colorScale(max) { + const stops = [[70, 111, 172], [47, 178, 166], [245, 215, 98]]; + const scale = ['#202c38']; + for (let n = 1; n <= max; n++) { + const t = max === 1 ? 2 : 2 * (n - 1) / (max - 1); + const i = Math.min(1, Math.floor(t)); + const rgb = stops[i].map((v, c) => Math.round(v + (stops[i + 1][c] - v) * (t - i))); + scale.push(`rgb(${rgb.join(',')})`); + } + return scale; + } + + function draw() { + if (!view || !canvas.clientWidth) return; + const width = canvas.clientWidth, height = canvas.clientHeight; + const dpr = window.devicePixelRatio || 1; + if (canvas.width !== Math.round(width * dpr) || canvas.height !== Math.round(height * dpr)) { + canvas.width = Math.round(width * dpr); + canvas.height = Math.round(height * dpr); + } + ctx.setTransform(dpr, 0, 0, dpr, 0, 0); + ctx.clearRect(0, 0, width, height); + const left = 48, top = 22, size = Math.min(width - left - 18, height - top - 40); + const n = view.counts.length, step = size / n; + area = {left, top, size}; + ctx.fillStyle = colors[0]; + ctx.fillRect(left, top, size, size); + for (let row = 0; row < n; row++) { + view.counts[row].forEach((count, col) => { + if (!count) return; + ctx.fillStyle = colors[count]; + ctx.fillRect(left + col * step, top + (n - 1 - row) * step, step, step); + }); + } + + ctx.font = '11px system-ui, sans-serif'; + ctx.fillStyle = '#b6c5d3'; + ctx.strokeStyle = '#94b2c340'; + ctx.lineWidth = 1; + const ticks = width < 260 ? 2 : 4; + for (let i = 0; i <= ticks; i++) { + const fraction = i / ticks, edge = Math.round(fraction * n); + const x = left + size * fraction, y = top + size * (1 - fraction); + ctx.beginPath(); + ctx.moveTo(x, top); ctx.lineTo(x, top + size); + ctx.moveTo(left, y); ctx.lineTo(left + size, y); + ctx.stroke(); + ctx.textAlign = 'center'; + ctx.fillText(number.format(object.x_edges_m[edge]), x, top + size + 16); + ctx.textAlign = 'right'; + ctx.fillText(number.format(object.y_edges_m[edge]), left - 7, y + 4); + } + ctx.fillStyle = '#d4dfe9'; + ctx.textAlign = 'left'; + ctx.fillText('Y (m)', left, top - 9); + ctx.textAlign = 'center'; + ctx.fillText('X (m)', left + size / 2, top + size + 33); + if (cell) { + ctx.strokeStyle = '#ffffff'; + ctx.lineWidth = 2; + ctx.strokeRect(left + cell.col * step, top + (n - 1 - cell.row) * step, step, step); + } + } + + function reportCell() { + const output = element('cell'); + if (!cell) { + output.textContent = '指向或轻点网格,查看该位置的坐标和轨迹数。'; + return; + } + const {row, col} = cell; + const x = object.x_edges_m, y = object.y_edges_m; + output.textContent = `覆盖 ${view.counts[row][col]} / ${data.episodes} 条轨迹 · X ${meters(x[col], x[col + 1])} · Y ${meters(y[row], y[row + 1])}`; + } + + function selectView() { + object = data.objects[objectSelect.selectedIndex]; + view = object.views[phaseSelect.value]; + cell = null; + const [low, high] = view.bounds_m; + element('x').textContent = meters(low[0], high[0]); + element('y').textContent = meters(low[1], high[1]); + element('step').textContent = number.format(object.x_edges_m[1] - object.x_edges_m[0]) + ' m'; + element('peak').textContent = `${peak(view.counts)} / ${data.episodes} 条`; + // Use the same colors and axes for all three views of an object. + const max = peak(object.views.all.counts); + colors = colorScale(max); + element('scale-max').textContent = max; + element('scale').replaceChildren(...colors.map(color => { + const swatch = document.createElement('i'); + swatch.style.backgroundColor = color; + return swatch; + })); + canvas.setAttribute('aria-label', `${object.uid} · ${phaseSelect.selectedOptions[0].text} · X ${meters(low[0], high[0])} · Y ${meters(low[1], high[1])} · 单格最多 ${peak(view.counts)} 条轨迹`); + reportCell(); + draw(); + } + + function inspect(event) { + if (!area) return; + const rect = canvas.getBoundingClientRect(), n = view.counts.length; + const col = Math.floor((event.clientX - rect.left - area.left) / area.size * n); + const row = n - 1 - Math.floor((event.clientY - rect.top - area.top) / area.size * n); + const inside = row >= 0 && row < n && col >= 0 && col < n; + if (inside ? cell?.row === row && cell.col === col : !cell) return; + cell = inside ? {row, col} : null; + reportCell(); + draw(); + } + + objectSelect.addEventListener('change', selectView); + phaseSelect.addEventListener('change', selectView); + canvas.addEventListener('pointermove', inspect); + canvas.addEventListener('pointerdown', inspect); + canvas.addEventListener('pointerleave', event => { + if (event.pointerType !== 'mouse' || !cell) return; + cell = null; + reportCell(); + draw(); + }); + new ResizeObserver(draw).observe(canvas); + + async function load() { + const description = element('description'); + try { + const response = await fetch('/object-heatmaps'); + if (!response.ok) throw Error('heatmaps'); + data = await response.json(); + if (!data.objects.length) { + description.textContent = `已加载 ${data.episodes} 条轨迹,其中没有刚体物体的位置记录。`; + return; + } + const cohort = data.explicit_reference ? `(原始 1 条,扩增 ${data.episodes - 1} 条)` : ''; + description.textContent = `场景 XY 俯视 · 全部 ${data.episodes} 条轨迹${cohort}。每格统计在此记录过物体原点的轨迹条数,每条轨迹只计一次。`; + for (const item of data.objects) objectSelect.add(new Option(item.uid, item.uid)); + element('panel').hidden = false; + selectView(); + } catch { + description.textContent = '物体位置分布加载失败,请刷新页面重试。'; + } + } + load(); +})(); diff --git a/embodichain/lab/expansion/_preview_heatmap.py b/embodichain/lab/expansion/_preview_heatmap.py new file mode 100644 index 0000000000..1bc9b0a41b --- /dev/null +++ b/embodichain/lab/expansion/_preview_heatmap.py @@ -0,0 +1,95 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Measured object-position coverage for the expansion replay.""" + +from __future__ import annotations + +import math +from typing import TYPE_CHECKING, Any + +import numpy as np + +if TYPE_CHECKING: + from ._preview_data import PreviewData + +__all__: list[str] = [] + +_BINS = 32 + + +def _grid_edges(bounds: np.ndarray) -> np.ndarray: + """Build equal-length XY axes with a margin and a useful scale for still objects.""" + desired = max(float(np.max(bounds[1] - bounds[0])) / (_BINS - 2), 0.001) + magnitude = 10.0 ** math.floor(math.log10(desired)) + step = next(n * magnitude for n in (1, 2, 2.5, 5, 10) if n * magnitude >= desired) + center = np.rint(bounds.mean(axis=0) / step) + return (center[:, None] + np.arange(_BINS + 1) - _BINS // 2) * step + + +def object_heatmaps(data: PreviewData) -> dict[str, Any]: + """Count the distinct recordings with a measured object origin in each XY cell.""" + clips = data.all_clips + specs = data.object_specs or {} + uids = sorted( + data.solid_clip.measured.object_poses, + key=lambda uid: ( + specs.get(uid, {}).get("body_type") in {"static", "kinematic"}, + uid, + ), + ) + objects = [] + for uid in uids: + paths = [clip.measured.object_poses[uid][:, :2] for clip in clips] + bounds = { + "all": np.array( + [ + np.min([p.min(axis=0) for p in paths], axis=0), + np.max([p.max(axis=0) for p in paths], axis=0), + ], + dtype=float, + ) + } + for phase, index in (("start", 0), ("end", -1)): + xy = np.stack([p[index] for p in paths]) + bounds[phase] = np.stack([xy.min(axis=0), xy.max(axis=0)]) + + x_edges, y_edges = _grid_edges(bounds["all"]) + counts = {phase: np.zeros((_BINS, _BINS), dtype=np.int32) for phase in bounds} + for xy in paths: + column = x_edges.searchsorted(xy[:, 0], side="right") - 1 + row = y_edges.searchsorted(xy[:, 1], side="right") - 1 + cells = np.ravel_multi_index((row, column), (_BINS, _BINS)) + visited = np.bincount(cells, minlength=_BINS**2) > 0 + counts["all"] += visited.reshape(_BINS, _BINS) + counts["start"].flat[cells[0]] += 1 + counts["end"].flat[cells[-1]] += 1 + objects.append( + { + "uid": uid, + "x_edges_m": x_edges.tolist(), + "y_edges_m": y_edges.tolist(), + "views": { + phase: {"counts": grid.tolist(), "bounds_m": bounds[phase].tolist()} + for phase, grid in counts.items() + }, + } + ) + return { + "episodes": len(clips), + "explicit_reference": data.reference is not None, + "objects": objects, + } diff --git a/embodichain/lab/expansion/_preview_render.py b/embodichain/lab/expansion/_preview_render.py index 4591772dee..f48b00a3e3 100644 --- a/embodichain/lab/expansion/_preview_render.py +++ b/embodichain/lab/expansion/_preview_render.py @@ -94,6 +94,7 @@ def __init__( ) self.data, self.sim, self.publisher, self.center = data, sim, publisher, center + self.link_names = names scene = sim.spawn_result self.step = sim.physics_step_index self.previous = None @@ -106,7 +107,7 @@ def __init__( and all( np.allclose( c.measured.object_poses[uid], - data.clips[0].measured.object_poses[uid][0], + data.solid_clip.measured.object_poses[uid][0], rtol=0, atol=1e-7, ) @@ -114,18 +115,16 @@ def __init__( ) } self.moving_objects = [uid for uid in data.boxes if uid not in self.backgrounds] - for uid in self.backgrounds: - self.models[uid].set_local_pose( - data.clips[0].measured.object_poses[uid][0:1] - ) - self.models[uid].set_visible(True) + for uid, model in self.models.items(): + model.set_local_pose(data.solid_clip.measured.object_poses[uid][0:1]) + model.set_visible(True) palette = [ (0.18, 0.58, 1), (0.15, 0.9, 0.5), (0.9, 0.55, 0.2), (0.7, 0.4, 0.95), ] - variants = sorted({c.variant for c in data.clips}) + variants = sorted({data.clips[i].variant for i in data.ghost_indices}) self.colors = {v: palette[i % len(palette)] for i, v in enumerate(variants)} for name, pos, intensity in [ ("preview_key", [-1, -2, 3], 35), @@ -138,20 +137,16 @@ def __init__( name=name, light_type="POINT", pose=pose, intensity=intensity ) ) - self.robots = [] - self.objects = [] + self.ghosts = {} def markers(name: str, shapes: dict) -> Any: return VisualizationMarkers( VisualizationMarkersCfg(prim_path=name, markers=shapes), publisher ) - for i, c in enumerate(data.all_clips): - color = ( - self.colors.get(c.variant, (0.65, 0.7, 0.75)) - if i < len(data.clips) - else (0.65, 0.7, 0.75) - ) + for i in data.ghost_indices: + c = data.clips[i] + color = self.colors[c.variant] robot = RobotMarkers( RobotMarkersCfg( name=f"preview_robot_{i}", @@ -160,7 +155,7 @@ def markers(name: str, shapes: dict) -> Any: ), publisher, ) - self.robots.append((robot, [names.index(n) for n in robot.link_names])) + link_order = [names.index(n) for n in robot.link_names] objects = ( markers( f"preview_objects_{i}", @@ -172,10 +167,8 @@ def markers(name: str, shapes: dict) -> Any: if self.moving_objects else None ) - self.objects.append(objects) - robot.visualize_link_poses( - c.links[0, [names.index(n) for n in robot.link_names]][None] - ) + self.ghosts[i] = (robot, link_order, objects) + robot.visualize_link_poses(c.links[0, link_order][None]) robot.set_visibility(False) if objects: p = np.array( @@ -183,21 +176,21 @@ def markers(name: str, shapes: dict) -> Any: ) objects.visualize(p[:, :3], p[:, 3:], marker_indices=np.arange(len(p))) objects.set_visibility(False) - self.selected = RobotMarkers( + self.solid_robot = RobotMarkers( RobotMarkersCfg( - name="selected_model", + name="solid_model", asset_path=str(data.asset), appearance=RobotMarkersAppearanceCfg(mode="asset", opacity=1), ), publisher, ) - self.selected_order = [names.index(n) for n in self.selected.link_names] - self.selected.visualize_link_poses( - data.clips[0].links[0, self.selected_order][None] + self.solid_order = [names.index(n) for n in self.solid_robot.link_names] + self.solid_robot.visualize_link_poses( + data.solid_clip.links[0, self.solid_order][None] ) - self.selected_objects = ( + self.solid_objects = ( markers( - "selected_objects", + "solid_objects", { uid: self._object_prototype( uid, color=(0.9, 0.58, 0.2, 1), scene_lighting=True, unlit=False @@ -208,16 +201,15 @@ def markers(name: str, shapes: dict) -> Any: if self.moving_objects and not self.models else None ) - self.paths = markers( - "measured_paths", - { - str(i): MarkerPrototypeCfg( - shape="cylinder", color=(*self.colors[v], 0.8) - ) - for i, v in enumerate(variants) - }, - ) - self.variant_ids = {v: i for i, v in enumerate(variants)} + path_shapes = { + "solid": MarkerPrototypeCfg(shape="cylinder", color=(1, 0.9, 0.7, 1)) + } + self.variant_ids = {v: i for i, v in enumerate(variants, start=1)} + for variant, index in self.variant_ids.items(): + path_shapes[str(index)] = MarkerPrototypeCfg( + shape="cylinder", color=(*self.colors[variant], 0.8) + ) + self.paths = markers("measured_paths", path_shapes) self.targets = markers( "recorded_grasp_targets", {"target": MarkerPrototypeCfg(shape="frame", scale=(0.065, 0.065, 0.065))}, @@ -274,14 +266,16 @@ def _object_prototype(self, uid: str, **appearance: Any) -> Any: def draw(self, state: PreviewState) -> bytes: v = state.values - visible = state.visible() + solid = self.data.solid_clip + visible = state.visible_ghosts() if tuple(visible) != self.previous: + displayed = [solid, *(self.data.clips[i] for i in visible)] positions = [] rotations = [] scales = [] types = [] - for i in visible: - c = self.data.clips[i] + for c in displayed: + path_type = 0 if c is solid else self.variant_ids[c.variant] points = c.tips[ np.unique(np.r_[np.arange(0, len(c.tips), 4), len(c.tips) - 1]) ] @@ -303,18 +297,14 @@ def draw(self, state: PreviewState) -> bytes: positions.append((a + b) / 2) rotations.append(rotation.as_quat()) scales.append([0.002, 0.002, length]) - types.append(self.variant_ids[c.variant]) + types.append(path_type) self.paths.visualize( np.array(positions).reshape(-1, 3), np.array(rotations).reshape(-1, 4), np.array(scales).reshape(-1, 3), np.asarray(types, dtype=int), ) - targets = ( - np.concatenate([self.data.clips[i].targets for i in visible]) - if visible - else np.empty((0, 4, 4)) - ) + targets = np.concatenate([c.targets for c in displayed]) self.targets.visualize( targets[:, :3, 3], ( @@ -325,48 +315,33 @@ def draw(self, state: PreviewState) -> bytes: ) initial = [ p[0, :3] - for i in visible - for uid, p in self.data.clips[i].measured.object_poses.items() + for c in displayed + for uid, p in c.measured.object_poses.items() if uid not in self.backgrounds ] self.positions.visualize(np.asarray(initial).reshape(-1, 3)) self.previous = tuple(visible) - self.selected.set_visibility(bool(visible)) - if self.selected_objects: - self.selected_objects.set_visibility(bool(visible)) - for uid, obj in self.models.items(): - if uid not in self.backgrounds: - obj.set_visible(bool(visible)) - if visible: - c = self.data.clips[v["selected"]] - f = state.frame_at(c) - self.selected.visualize_link_poses(c.links[f, self.selected_order][None]) - for uid in self.moving_objects: - if uid in self.models: - self.models[uid].set_local_pose( - c.measured.object_poses[uid][f : f + 1] - ) - if self.selected_objects: - p = np.array( - [c.measured.object_poses[uid][f] for uid in self.moving_objects] - ) - self.selected_objects.visualize( - p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) + f = state.frame_at(solid) + self.solid_robot.visualize_link_poses(solid.links[f, self.solid_order][None]) + for uid in self.moving_objects: + if uid in self.models: + self.models[uid].set_local_pose( + solid.measured.object_poses[uid][f : f + 1] ) - ghost_count = 0 - for i, (c, (robot, order), objects) in enumerate( - zip(self.data.all_clips, self.robots, self.objects) - ): - show = ( - v["reference"] - if i == len(self.data.clips) - else v["ghosts"] and i in visible and i != v["selected"] + if self.solid_objects: + p = np.array( + [solid.measured.object_poses[uid][f] for uid in self.moving_objects] ) + self.solid_objects.visualize( + p[:, :3], p[:, 3:], marker_indices=np.arange(len(p)) + ) + for i, (robot, order, objects) in self.ghosts.items(): + show = i in visible robot.set_visibility(show) if objects: objects.set_visibility(show) if show: - ghost_count += 1 + c = self.data.clips[i] f = state.frame_at(c) robot.visualize_link_poses(c.links[f, order][None]) if objects: @@ -400,7 +375,7 @@ def draw(self, state: PreviewState) -> bytes: image.save(buffer, format="JPEG", quality=88) self.stats = { "physics_steps": self.sim.physics_step_index - self.step, - "ghost_count": ghost_count, + "ghost_count": len(visible), "path_segments": self.paths.count if v["paths"] else 0, "grasp_targets": self.targets.count if v["targets"] else 0, "scene_objects": len(self.data.boxes), diff --git a/embodichain/lab/expansion/_preview_server.py b/embodichain/lab/expansion/_preview_server.py index fa8392b292..1390189cf2 100644 --- a/embodichain/lab/expansion/_preview_server.py +++ b/embodichain/lab/expansion/_preview_server.py @@ -29,6 +29,7 @@ from typing import Any from urllib.parse import urlsplit from ._preview_data import PreviewData, PreviewState +from ._preview_heatmap import object_heatmaps __all__: list[str] = [] @@ -41,7 +42,13 @@ def __init__(self, state: PreviewState, port: int) -> None: self.status: dict[str, Any] = {} self.jpeg = b"" self.snapshot = b"{}" + self.deviations = b"{}" html = Path(__file__).with_name("_preview.html").read_bytes() + charts_js = Path(__file__).with_name("_preview_charts.js").read_bytes() + heatmap_js = Path(__file__).with_name("_preview_heatmap.js").read_bytes() + heatmaps = json.dumps( + object_heatmaps(state.data), allow_nan=False, separators=(",", ":") + ).encode() owner = self class Handler(BaseHTTPRequestHandler): @@ -64,6 +71,12 @@ def do_GET(self) -> None: with owner.lock: if route == "/": data, kind = html, "text/html; charset=utf-8" + elif route == "/preview-charts.js": + data, kind = charts_js, "text/javascript; charset=utf-8" + elif route == "/preview-heatmap.js": + data, kind = heatmap_js, "text/javascript; charset=utf-8" + elif route == "/object-heatmaps": + data, kind = heatmaps, "application/json" elif route == "/state": data, kind = ( json.dumps(owner.status, allow_nan=False).encode(), @@ -71,6 +84,8 @@ def do_GET(self) -> None: ) elif route == "/snapshot": data, kind = owner.snapshot, "application/json" + elif route == "/deviations": + data, kind = owner.deviations, "application/json" elif route == "/frame.jpg": data, kind = owner.jpeg, "image/jpeg" else: @@ -140,6 +155,7 @@ def serve_preview( open_browser: bool = False, duration: float = 0, ) -> None: + from ._preview_deviations import deviation_curves from ._preview_render import native_renderer state = PreviewState(data) @@ -147,6 +163,11 @@ def serve_preview( thread = None try: with native_renderer(data, gpu) as renderer: + transport.deviations = json.dumps( + deviation_curves(data, renderer.link_names), + allow_nan=False, + separators=(",", ":"), + ).encode() frame = 0 def publish() -> None: diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index 376d3ca9d8..4420cb8ce8 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -89,8 +89,8 @@ job 输出目录旁创建唯一目录。原 job 文件和原产物不修改, 保留报告和日志,不伪造成功回放。 页面显示所有计划点的参数和状态,候选虚影只来自确认结果;初始位置图层中, -红色计划点表示未完全确认的参数点,不代表一条失败轨迹。筛选后没有匹配样本时 -显示空结果,不用别的候选替代。WebRTC 接入仍为 TODO。 +红色计划点表示未完全确认的参数点,不代表一条失败轨迹。筛选后没有匹配样本时, +候选列表为空,固定对照继续显示。WebRTC 接入仍为 TODO。 ## 从已有结果启动 @@ -112,7 +112,9 @@ embodichain expansion preview \ 数据集或单个 NPZ。可重复传入 `--input`,空间筛选以输入结果目录分组。 已有结果直接读取仍要求固定布局;`--job` 会将 scene-atlas 的每个采样点冻结为 独立布局子作业,再作为一个参数组加载。 -`--reference` 可省略;指定时必须恰好含一个已确认参考 episode,且不能与候选重复。 +`--reference` 指向原始轨迹的作业目录,其中应有一条独立的已确认记录。 +提供该参数时,原始轨迹始终以实体播放,所有输入候选都可以作为虚影叠加。 +省略该参数时,预览固定使用第一份输入中首条载入的记录,页面标记为「首条记录(固定对照)」。 模型从 `job.json.resolved_deployment.robot` 的 URDF 路径恢复,场景刚体几何从 同一快照恢复。方块、球和文件 Mesh/USD 资产通过原生纯视觉对象加载,保留原生 @@ -165,7 +167,7 @@ embodichain expansion preview \ 2. 核对 episode 身份、机器人模型、关节名称与顺序,以及动作和状态的 T+1 对齐。 加载逐帧完整关节位置、机器人根位姿、物体位姿和时间戳。 3. 使用与记录匹配的 URDF 和实测关节计算 FK,驱动 `RobotMarkers` 的完整视觉网格。 - 选中样本显示原始模型外观,其余可见候选显示半透明虚影;参考单独开关。 + 固定对照始终显示原始模型外观。每条启用的扩增轨迹叠加半透明机器人和物体。 4. 用真实物体位姿驱动物体模型,并通过 `VisualizationMarkers` 显示初始位置、 抓取目标坐标轴和末端路径。 5. 启动时分块预计算 FK,使用 `MarkerFramePublisher` 发布一致的跨组帧; @@ -179,10 +181,13 @@ embodichain expansion preview \ ## 联动筛选与时间语义 -空间、affordance、轨迹三个筛选器取交集,同时作用于候选列表、虚影、物体、 -初始位置、抓取目标和轨迹线。选中样本被筛掉时,选择交集内的一个有效样本。 -没有匹配候选时显示空结果、停止播放并隐藏候选图层;参考对照仍可独立显示。 -参考轨迹是独立对照,不计入 8 条候选数量,也不受候选筛选限制。 +回放工具栏列出了快捷键。按空格播放或暂停,轨迹结束后再按空格从头播放。 +从采集开始对比两种布局和抓取分支的完整步骤见 [UR5 布局与抓取姿态扩增教程](../../../scripts/tutorials/expansion/ur5_pick_place/README.md)。 + +页面初始只显示固定对照。点击候选按钮会切换该条轨迹的高亮和虚影,其他按钮保留各自状态。 +空间、affordance、轨迹三个筛选器取交集,临时隐藏不匹配的虚影,切回筛选时恢复之前的选择。 +「显示全部匹配虚影」批量切换当前筛选内的候选。末端轨迹线、抓取目标和初始位置图层 +跟随固定对照与当前显示的虚影。匹配数为零时,固定对照仍可播放和拖动。 - **空间**:显示实际初始位置,不给样本添加人为排列偏移。 - **Affordance**:A0/A1 是配方分支编号,不是底层候选 ID。读取规划诊断时按实际 @@ -196,6 +201,25 @@ embodichain expansion preview \ 时刻之前最近的已记录帧,不插值生成新姿态;短轨迹到末帧后保持。 阶段对齐只改变浏览进度映射,不改变原始时间戳。页面保留实际秒数和源帧号。 +## 按实测时间比较偏差 + +回放页下方的两张统计图使用全部扩增轨迹。横轴是固定对照的实测时间(秒)。 +第一张图从各轨迹记录的世界位姿、URDF 正运动学和夹爪 TCP 标定恢复末端位姿, +逐条计算与对照轨迹的平移距离(mm)和相对旋转的最小转角(°),分别绘图。 +第二张图在每条轨迹内先取机械臂关节的最大绝对 qpos 差。 +每幅图的色带下沿和上沿分别是该时刻所有参与轨迹的最小值和最大值,带内实线是均值。只有一条轨迹仍有记录时,三者重合。 +转动关节使用记录的关节坐标差,移动关节以 mm 单列。 +时间戳不同时,位置和 qpos 线性插值,TCP 姿态按最短弧球面插值。 +每个时刻只统计仍有记录的轨迹,样本数为零的区间留空。悬停可读取各项偏差的三项统计值和参与条数, +移开鼠标后读数跟随对照的回放时间。 + +### 物体位置分布热力图 + +俯视图把原始轨迹和全部扩增轨迹中所选物体的实测原点投影到场景 XY 平面,坐标单位为米。 +「全程」读取每条记录的全部实测帧,同一条轨迹多次进入同一网格只计一次。「起点」和「终点」 +分别读取每条记录的首帧和末帧。三种视图共用该物体的网格和色标,可以直接对照初始布局、 +搬运范围和最终落点。指向或轻点网格可查看该格的 XY 边界及覆盖轨迹数。选择不同的三维筛选项时,热力图始终统计全部记录。 + ## 验收与当前限制 本地浏览器验收覆盖:筛选数量 8 → 4 → 2 → 1,筛选后原生画面改变, @@ -223,7 +247,7 @@ CLI 不触发采集和安装包页面资源由生产模块的聚焦测试覆盖 负责,CLI 由 `embodichain/cli/expansion.py` 分发。 当前渲染支持单 URDF 机器人、单位机器人缩放,以及有完整实测位姿的刚体场景。 -文件 Mesh 和 USD 通过原生视觉资产加载,选中物体保留源模型外观,虚影复用实测几何。 +文件 Mesh 和 USD 通过原生视觉资产加载,固定对照中的物体保留源模型外观,虚影复用实测几何。 其他 articulated objects、软体、流体、线缆、显式 visual replacement 和直接 scene-atlas 输入会被拒绝; 不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,虚影材质与灯光用于展示, diff --git a/scripts/tutorials/expansion/ur5_pick_place/README.md b/scripts/tutorials/expansion/ur5_pick_place/README.md new file mode 100644 index 0000000000..cedb7b8716 --- /dev/null +++ b/scripts/tutorials/expansion/ur5_pick_place/README.md @@ -0,0 +1,56 @@ +# UR5 抓取放置的布局与抓取姿态扩增 + +这个教程用同一台 UR5 和平行夹爪抓取桌上的立方体,把它放到目标位置。先记录一条原始轨迹作为对照,再用两种策略改变布局。每种策略各采集 4 条固定抓取轨迹(`object_pose`)和 4 条抓取姿态扩增轨迹(`affordance`),共 16 条扩增轨迹。 + +| 采集模式 | 改变的内容 | +| --- | --- | +| `reference` | 立方体和放置目标使用任务的初始位置,执行一次固定抓取。 | +| `scene_first` | 先在桌面范围内提出布局,再检查机械臂能否完成接近、抓取、抬升和放置。 | +| `robot_first` | 先从机械臂工作空间选取可达抓取位姿,再以此为约束生成布局。 | + +## 采集 + +从仓库根目录运行。在装有 EmbodiChain、DexSim 和 LeRobot 的 `py312` 环境中执行以下命令。每个模式把实际配置和采集结果写入单独的子目录。已有完整结果时可以直接进入「网页回放」。重新采集时给 `out` 换一个新目录。 + +```bash +conda activate py312 +demo=scripts/tutorials/expansion/ur5_pick_place +out=outputs/ur5-affordance-demo + +python "$demo/collect.py" reference --output "$out" +python "$demo/collect.py" scene_first --output "$out" +python "$demo/collect.py" robot_first --output "$out" +``` + +三个命令默认使用种子 7,可用 `--seed` 指定。每次采集结束都会打印各算子通过验收并保存的轨迹数。各模式的 `expansion.yaml` 保存实际使用的参数,`collection/expansion.json` 记录完成情况,`collection/dataset/<算子>/` 保存轨迹和验收记录。 + +## 网页回放 + +已有原始录制时,跳过 `reference` 采集,将下面的 `reference` 变量指向原始录制的 `job.json` 所在目录,即可逐帧复用同一条实体轨迹和图表基准。 + +```bash +conda activate py312 +out=outputs/ur5-affordance-demo +reference="$out/reference/collection/dataset/object_pose" +python -m embodichain expansion preview \ + --reference "$reference" \ + --input "$out/scene_first/collection" \ + --input "$out/robot_first/collection" \ + --port 0 --open +``` + +- **空格**播放或暂停,播放结束后再按空格从头开始。拖动进度条可定位到某一帧。使用下拉框或复选框时,空格操作当前控件,点击回放画面即可继续用空格控制播放。 +- 原始轨迹始终以实体显示。右侧每个轨迹按钮独立切换一条半透明虚影。按上述命令加载时,前两个参数组来自 `scene_first`,后两个来自 `robot_first`。 +- 在 **Affordance** 下拉框中选择 `1` 或 `2`,可以查看采用该抓取分支的轨迹。使用任务固定抓取姿态的 `object_pose` 记录显示为「未记录」。 +- 画面下方的 TCP 图分开显示相对原始轨迹的平移距离(mm)和最短旋转角(°)。关节图显示每条轨迹最大的臂关节绝对偏差。三条曲线都用色带标出同一时刻各轨迹的最小值至最大值,用实线标出均值。悬停可读取三项数值和参与轨迹数。 +- **物体位置分布热力图**从上方看场景 XY 平面,默认显示抓取方块 `cube`。选「起点」查看物体的初始布局,选「终点」查看最后的落点,选「全程」查看搬运所经过的区域。原始轨迹和全部扩增轨迹都参与统计,同一条轨迹在同一格只计一次。切换物体可以查看放置目标 `goal` 或台面 `support_surface`。悬停或轻点网格可读取坐标和轨迹数,右侧的三维筛选只影响回放画面。 + +下图停在 9.00 秒。选择抓取分支 `2` 后有四条轨迹符合条件,图中打开了 `C-002`(`scene_first`)和 `C-011`(`robot_first`)两条虚影。两条虚影和原始轨迹共享同一回放时钟。[查看偏差曲线](assets/deviation-bands.png) · [查看方块位置热力图](assets/object-heatmap.png) + +![原始 UR5 轨迹与两条单独开启的扩增虚影](assets/replay-ghosts.jpg) + +## 修改配置或可视化 + +两种策略共用一份配置。默认布局允许立方体和放置目标在 X、Y 方向各偏移 ±6 cm。`trajectory.affordance.call_indices: [0]` 将抓取扩增应用到第一次调用 `pick`。`fixed_object_to_eef: null` 在 affordance 组启用夹爪的对向接触候选生成器。`branches: 3` 让采集器轮流请求分支 1 和 2,再按实际抓取、搬运、释放和放置结果验收。可以在同一处调整分支数、布局范围和每组轨迹数。[扩增配置](expansion.yaml) · [任务与机器人配置](../../../../extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml) + +播放键、筛选器和时间轴在回放页面中实现,偏差曲线和物体热力图各有独立的绘图脚本。改完重新运行「网页回放」命令即可用同一批轨迹查看效果。[回放页面](../../../../embodichain/lab/expansion/_preview.html) · [偏差曲线脚本](../../../../embodichain/lab/expansion/_preview_charts.js) · [热力图脚本](../../../../embodichain/lab/expansion/_preview_heatmap.js) diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png b/scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png new file mode 100644 index 0000000000000000000000000000000000000000..28c0ede648b95a22977b95fde0e6dca81a39ce07 GIT binary patch literal 80078 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�Ri7Kdp%id53vxrP_wdWrTesK4ijD{gmXS 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 OaI$ZeB)^Iq2mTl0g2m$i literal 0 HcmV?d00001 diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png b/scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png new file mode 100644 index 0000000000000000000000000000000000000000..7886a68c916d39e2064b094231cbab99f9768ca8 GIT binary patch literal 56301 zcmaI7cRX8v`#`1?Mr^V7OpLbn3S!4dZLvq} z_04_1@6Ug~$1i_)ydEcVl5?HcbzRSKok(p>Wn#jYgm`#(#HuO^x_EdGX7KRt$v(b^ zJ2J|zE`x{n6i-#*ot|Ij&ceeFgS)tKG36)M+g;h&XHHdz^PVHFbGssYf#?m$3g#tP5O?nXyrTZt{JX%Tc>IO! z-z6KxJ)M77+H4Q<{$1s0ce6cR`}CHQV@9Am1{Mx0Os2g5?^`kiTDn`~(2@BTPhL}) zkPAwvaeZgDP8@}@>Ww`)I2hVLxHsW+l(qIaOhNae1+J z_KSp0JcdT%6q(FPBkG)^>f(}>A?j9KRyJK`XkJT8z{toLF^~-Yb9j7we0Y*vLMv(g z16I1#a=algCuffwn(*oywFn7mSB|4)_jAx}aCDh#To~`Hvx3IONG7pr&`VpMFSZ35 zR+$Y?>6PkTOq3+Gx3^cAG}#g^bw-d53=Hg|8jg>S2C6i0i^<7}v_GmEYJrzn_J6NY z+xf@+F#>Ydsgm96!~6*Bld?qS-JKnUH#*uMKm8LA^+Wza3P=eG`eNT#w+CM#?+cEP z&-Qn9J&2krHK;(Rhf)HE2Wu)0VdDHCGQ$CrIyf7k%Ny=LHPukk! zw!<&}dmlbq%G3TZs4{Ewu!(4LLjy+aQ3V7Gq1Wg9V$3a{dwq9NVS7~{U|kf73ovg^ z{Zdd$O32PRziQ#28Wo|!_HVfl}km;%2T4k~W5ys9eE;7jZT z2qYbRDL(CkxcRlzsjN+ro}L(R@b_Kg`kyc&&_9(QT8?J;SDtelvpKLQ1+0B)8O~_> z=uum~L)bq&Imyi})n*&Jr6 zook;pv86)h91sxT=hy6&*<<*ex6$}y%Vq$Sp!et@e&{7OlADxXG7T4x z7D?Cn?||f;SpXd!9jwZ{<9B}&>rDEuUpXZ}sK6ZqAi`&RF_v%xkrf>sn>0~n(zN&M z%YBMJbW$Ggk;$SR6Wf1j{dq!H0^@@_ zPr9&^z%r1w+nS!7hP?MtUJ~?2eplex9=8z;l)^afe7M|=Op1u7HG^5RQySMh8^L{C zapE*E(H&MB#_!*YI3Sr`{mO=v1)RJ*Jw45HPFSrmX>t`75CECI%pQSW zO_mwh5eisCHgS7{)1drkNv60BAYUmqZQsfi7sDjFxu*YBrf$-a8UQ7IJQW#P0yx3K z!G@BYoaWiHiE<;s(xBsY4Lv=*=;z#VbP{{3deL%pTBKTYgpHB?%k;V59ub$CRlKCk zv&xeRI?pM<+TfXCejx|vB)EmcxFf>93y9@E;QmnknXsgU9TYL&?2v!E)VcNYC9Vt{ zx|<`DL8IfN6ORcCz@5QRD=3-fzxbGR!J!-duu1E>)c~Nm4V?5(fzq5 zUP`tL>Sr%G#yvX2iBGmB>lzvsTK$i!mpUKZ`#oq_1@qniji3|uV0xHGk#o8=Sr*h% zi@RsJ4HG%34Z`b+$8`bWg|7P}GsnZ83;YA?#l6 zs!k&%M_LAW%`Dx;EFT}Zs2`vUl()itqcb8&x?wPtS2x#Y(4eQM2P?jT09(1bBL2I# z@F-+j#ZR`zvTv@=fG_>qe)u z%5kVxT{7+ugQOo{TMX{A{LAePuq+AR{^LnCs21}8sK%BkmPRyBojt6XqRX|9I>Rs= z3f%~gr72Q}EU)e;aI3k#2uesvWgTTAiJZ~7_Z24&57BKg$z_JXK8@FG zboco9Myo#B@jiRZP8b^-OCu8^XaD}i|9Tx8#IL~v_E$Rav^?Ns%bAiU-W2AgswUq# z|7RI@Nzd2UOG`^h8Ki~y_&#twZIJ?lSWsKJ8_}CA4`mm zVq*Q0Os}QC46dP4?o#g8S6Am;X=TgQC0XQJSoOx_ezlq`m0V0E`PJYw&2G}TQwJT9 zRFC z$oo4#JY3@<-B zFrLJvX`lp_OD-;Vs~MEP*A%AWF)Lr=ilaxj z1y1M6<0}QdvB@hdEAw=*lac8_7OJVG*f=@i>Vl~;=u7*T+ysk{vUuHYAb^z5j@r{c zmPgsr!N#~k)}Jpa)tz8%L_?!WO!Fh;R=ifn10XCnaE$fZye;r)gTouq^`NSmMvR8 zuF{*g1x)^~0YEcfBzoWdz9HTgWnyMQqzl7Uf$mRco84C=d|mDA?0`m*P!O8aB5?Kc zVlb|xtgukyERq2IFt4ATy*G}IhVPT?oXGA>PAXZpei_Vee~&Y@sx{yw>Ynqz;mSE* zGHvxcL^U|!lC=y7C1Iq0+{BS2C>dW@2gJp7d3jlrUdDatkAH%S*Gf-p$j#OG{3fo* zMv!i8ZfOg6p8r@%v?1;T2VQp_^5=IE43R@MH8aF3l+PfEve+T8U|d{W;OS0_$6C~? z4g^9E27_(a*D3gGsThR^#axgJ!`vf=LD)W>T$R(>Oq4MSnfuBgyE%5S#As=m=i)Nx z`GREf361p7@7#eF&yBtL_Tk2w#zwG^zpiD_pHWFI9wSnaPY1OKfEd8RG1}2V>+ntLrBC5sqU=!SBiMXK7{jU510(5WcHb!P-L3wLd zz47qoW^M4u%19djO5ajv%ZQQ7d-I@sj(gE?d#C7?q3_@KVe9m7tFxzGn2-<<7_|kQ zM4avS#?X!D%J)LV{txU#HrbEmo$k(+g-8JtBwORrMwJOJyYwH>+=E&(?SoDe&#ixe_iS z{SS${rilt4ut=;{oeyt3(aA^yDX31{jX-q#SAQgsvuapR-w*S5b=}+1H*wUf3OVm1 zBOGLwr_Pe}m-7fHg~KJfQ)2uw3)~nI_zShsM#TBx=m_S0 z<%2_oxbC1_;sEGqbev86=ieN*^(!eUp$L0~|1c~(T$k_SU@2eNX$tbz{ev2C8wZQ8 z&h}-h@9-M(W3nqNNg84zBMbd>ZQ0k?*SDw2*AD$~G4Jc^`zZMH1Bu;kx-hQ(W%0Rx z4gD;`taltp_WJd*Y`t}VBE=7bQnq%>sHW+S>z7mlj2z#-%Hp6u7V9O#-H#j{&ABQl za7(r27o<{7)XJ7F{FofeO;lo71t|n1m+F-WBnt`%N_cJZ`R;uHfI}{^4!f|1`o*3Y zde0M-{y?wzq=)XbHt8^>?b!}H{Q>51rI(%_B2X6-0~nPGRzfCIAUgtX(g`U!4JaOe zk9{f1m65NufgpY<^fvfX=;6p?h5tq)=f$#Vdl2|*C94($iy4o&r&Efj7e;Q?{UgXv#k}rja4E#CcrYjsu$RH8qu$ zmB}3X#_i7j+S;SIQh6LimXMI(<>tylzn1)m19ta!D;>?r6Qrc~GGnIIb0ZE5PTHAK zI~1dew9t79NldJDoGis5K|#eoOHW?#{UkF_VcG3pQI-n87O+i>cY0oT5vU_x$nEr( z?Ju^K=@t@FR+_?DZZ>^(QIl2X*@XC{^dO_^sHi9i#MQvSK=xyfS1`bl<6%9nFCd2c zaz1QglAz6!5O1)6>z?bA|LzD`{vOXkZ;tg^n?W&J1PlE#|%&de9xXp5z#@Ngxh)diPXYZ~`=gkDPdco}7QXhaCzTw}-!#o1pN=Vw2hw6{SV#U%2Zi%y1gNyc*DH zE^c?-*47R8pP&BXO`4?C=LO1`&*pluZINgQ}tN73sfT|A)gw=j2)@CcX@>m-Lp6+)?Z(IoTI4afSz%~&T&&MvRf|eIAp1zVQ zvqp%4cN+8wBaeCv3{qmwUve*VHdu!YS0MpqM)~3T{fSE9;S>po4AGJ4X;E(BVMOI0 zti$*Rv-Sd6(6j1BN@wCKYR8NJ(*m9lr*NBc8091-k*_5=c>7pr z*4H84d)NLj49%v5L5ZcEd5zM^7Oq7QZ;2M`)zn%)`1s#gd|nPuwX3MCMBug#r(q>6 z8JYX>`mhe8@}mcj8eJ!&Z2kTH`-M(Vj&C-yLvbyh$*|jb9LB9^aCN$u`~+{V!6~(Q z<}Das#C5*dK-2EyfL*Q5_KsNHu)0Q4Qj&7)%kD-T4XMZ|a|$D*EG{o#3Tb#~t#C0Q zc`BYw4}rXX{ThKlbVd-{RqY?`VCs@N4F$y#3Lp?Ouej2Ptk}y1a8dZ-2PuYS0>E*agJ~%#3Es+V{QkT`VvD8K4 z$oi}eYIc^}oTYtzt2DWcjnKveAt5XxQuH^;tS6(%ZELDxu2z4rE%21bsP+6Hfe{BA z^I{5N;g6U#OWfc4olmeQ6*69@ZEoVaHGqX(w#{oPZ-|rK?-NUa>i>#C4aoNu%;n05 zL8b#+k0oVT1p0uG$?LZ3Zs-mP&r6}el9B9Xoap0*Ze?%Q_@ttuYq>nbZ$|_GYAfY`ggrl8v9-0uw&&$ro$f6pUCpZm<(-5TaN)cje zYHWC+He_Y}c?vVwTwcS}3N_#TNQs%yUeMx_Rx0@Zy6>ncUmD!Gq9)SlAD0PXq37lA zs|vc3CcJhhJHFQtFvdf^EKSTt>*?!*-{egyGB5xYh%*|?KQzF+G?JdXNO#qZh)j2 z#1jLYnwYY^b-M|VD>WE5a;@W-bVLGvsv9SBjKkzpB~6S|xTHc*w3zhQ`7C^$EBZFvhOnM+=Xg`{J(k{-Ccz8?{rP)W`2N(g+MOj|}uZ8|E!aULz}I8~{9_Dw0K zkQ;1P8q9oX*kG`W)0g<}vgJY~2rtCJ<}E3!mtWjI=!}^pE$ZRn{na{KGfy{Fj5zrD zG}N4da2H@Qr_$sXbcdKFS7u5I#*eS(FydfmSG9d7E-rqH6E#nFKZbxk8hw0{X?ZfG zc}i4O0p-S>nA_cL0qzw`t4AaZbwNv93EC=m;e&JfAjlOae-1J11ZJ4@9sOh){0&C@ zQmx||^0avGsnxVbf$o&g-yhq?9jCaqIMf_6ahuKV`)e@=9DE3mRMi@1)hZ-oh}=VEAH zj`h|Aca~0oC<4NOcD!88H${_b_P~O#-m^zbr1DHBK{g@ZdWI`arAMwM!#-Hu#plR| zMiFkdo%;nRRzkfiiz*Q*^78irv2?9|r-Ag@T4iU*S@I!XCG*U^;79CbY*mY`Cc6F? z^CfW6s#+Uz!Q)fY02iYsNi`pZenga~waVI)bGbm~Vdra$BRx*?~buAMAdf!Jh+YMWgT^ZgOMPnFZfCi}M+Qe%z8 zWvw#)d}8lBn%eJwySX{to#z@4HzR1H$E3Rh?XupsY6+ASR>&Xr_vhmu1rg>y>#^aS zfzoQ)vSR3rjFJ%xF(l;m`^azo=1NLELy?T&Hv;^^`EKUAx^E;LY+XwVx{_}l6013k z#D%#};OQUmwb*Cqg)J^yl9Xq?2ak?EZKLWK=%~(j4*Ab4*FwmCRG1caefMjeuh*Bj zR0964)U}!RbpzkYFLls`1!WEKzE|^-b)3E2RhNcHxB6bryl%X{k8b`tw(UG$e$p_w zv3d74$Sj^rVxRlcOVRS1)okS88stEu_COw{u3nbn;^eg-wkY z7MnVf@s77vHCn{i^+N)Lv#nQ^w^m;h5OMkzTy>R2fl^dfS~YXNQ5vQzo#Yd4%DKB# zTUSrsAsmPDg?5XBdnoW^nmrlM7D}a< zyJPL_HIdjd&g=;tGCn`pi%lKLUJv<5K%P|n_hY|xCkwZrpy1{t^0}fi+FUv?b7S0l zTQJ9(-N_1A_r3W&hIOEV&uJ&3Kgh?5<*xI&M-{(ulTuF+c50LFXK8vV3??3C@!Wvf zlL3?H0Wi^e*EMv$G>0S+@cA9o$@~7A>sS7Kyia_qG z1_WF#?$Ri0rE9uC)?4U3R^#r^?uQ8x%00gpjASPif8J= z3-E4=uUHmnMZSa!VmY=fML}7yFF0qY25K_RV+!|6;T|_UNs0(Oot`$x&AT6r&&=@8 z4b@DeD|4Y|*4Bib)67?Fe1XtqLhi2^fz@fAtcH3H{mzz3>*vhI%xhtH>Y6G)I9I8@ zwECZ9N&)0(JPmxFUkzG0+PW_d-Fg2iu13fGX+xMdq<9Rykdb@U2Qt!x(g!CuqY-=T ztD=<$o2;N)BjADmr|Fb~>e1RpAFRv3@he=5zs~i;%A-R!?S1m}BM>{UT{3DLaZT~a z>+aL_LHo`JIPaM&y02|xqFK>N@VNELyrnHvE$|}v5s4iT1PchD2s4uk73UDR?rS%_ z8#13Nl228$(-II*Q+{DTtAS6|<&*v1u$xwr+KrD3tQyjoDOOEayW z$*=tCsbp&)5c%0hl-)vw;CK$&&Z~T z&8eI?NK-;w{fpe!dsE!zqs9K5s6!9`%OCxiwUdKI7fQ-CM`5RNX?);ggf~ri_=AXu z@V*Jsm;44mwTQvBG!x@Vhnb0zz0@C;=(t$+{(cIu@6KX0%k2BTp~KE9h)l(FF*WlB zd(Xk`s%oGc{T@RiIk~4yJ}mw6N|bk)yPPeB^KTfXM=T{o955){sofnM2v zIEpsyO@w(YYW+?p@}yh!uMq#-N}Ehqe(W+Ob{bv(t(03340RpJmi`ePo5dH5sN~*e zr;$&vUa_q(;D*Q(c=rD$F)(%<$X%FQURfse<58u3-%~U{%Ad48@`AUIVs$zV5)CcD zZr<)nZsXmbmf7GH8jR}dx2m^<-I)(&13t4SQ zVow-YZbRR7OyWG3wnsr2d3pwhKtHW^|2ko{jfhA119|``ineSz>M^NF%cqozteg6p z&Y6$j;@)acXoMvxpPEYsJKshT9~Z@Q{vEd%8)2-tKu+0U$}~h->`o96f$(ir>eipTcRZKia=wU|@X~ar{7ri5x_b!@G{AzB1<5E&VX!vw{l8XGWQ*C5Q5qpL&z zMsyvVB2|+grnKeFJEW ze}2=uQ0vp(M*uv*o)iiiLiSu2E}ux=>@SsbB?Q~_DxbCQ)*318K7j0Olhw>B=@zVfhJB}^oaW$Avg4G$Q1llsR6Ha*E2|sfI9{_|*GtOQ)=yDv zkQG3s$uMZ@rc;ZBaBn*p%ELS+i%cb%r5X2r1qrf^#*>JT67Ea*S>r$uT`(yTLC6^@ z%*q6>RONTNX0(L)&d#}IY8Sw=xchch&7P&Ok~%!R?> zYnkE7U$(ENdDJ!Wy9qTofrP08yAo#wXONBi^73Ef=qUER#oi9sp0G2hEN#PVh^!4t zo&ZWEgZ<8KG7LfJoc#NjkHSH7RD@v}2E4=w%qO)N&z8VhrXM{m?YYa+pXYStD;0&m%JLROxG`0O@xtu29z zu2((!6eYS{n&@}pza~meq4(j9qjMOkPi%#IHnm|o2}j4?UfjNTJ7NT?>(HEu^$o?zJ&2wka~e zn&FHQ^1R7|Ydzfxbut;)0wRNQL!cok_H3>`Ky}Zs8@NtGot!4R0tf1{ho|oG>-d$h z_j?w_S$QB{LmQN{{nXWCnAW;ijvxHtU5g^o4{ntloB=`6*(3A}%uZ>&vhy4j%A^g@JPhsci=rG1>U4j%LveP6Z z6jXbWQQcM+9t)<(9MNLN^~F}6HtJ?J zADmolo|++J9>H0fuR3GgZP^#ui^lcR0bY;}%Gb(2ejBVvL+U4@%= z56~F$JSVWZTEx-QaTz_#%COf1sbAB9tLKEhqQC$72L#HI3ZF@1!xaCj2^gkH z<>8Y7C>wTscnJRnZ(0+Z9$!fI2mnc!Vm?%TkHid@Q7PVgm;bzCV0L!g75KS|cTNpV z22FF+c~azN|Gpwc@L?V=M7m(ED|DSsrha;~TA`vU3)hbf7=%7ZZgywU7*=M=m^Qt$ zB0M-B7yx6acRngo(CSX@&G+X&Y_%oU&;Yckz^utp+cv(wt9dt=1HMC!!n4Bs3X|~` zl80^espTbw!^0R-mS>TB3osVZX9%sO=@~8MFAsLl;xojrP=$5N2j1(~c%f)r8|Swl zDk~xMyIH_K9MQ`9sw17^qfR5@qEiFV&z0T8+J^Rzu1wtA6mgW}}C`im2 z6qZNCgB8rJ(*pwH{`(*jXWSK5F>KR6T| z_Pa{I8BVY;t&|L|Voq8JAZ>PEYyI-&HC;?}WE_XlfViZ!Oon~oeJOz~KMXWYx7l{N zE_D)199z)w0efgewU?omQi(2N@kX?GP0tT*Xf3q43y&y!Z=#M--JXf6?X^(_b^>jD z(@k#91GC5~{IK`+0a~=PGHw{ug&@o5mnZ%5o1gUC!ZnIz3F`X}_#zyIH5p`vKD`hr z8hBHEH6+G=csB&G7cJ>0+rwwv&{Cxt~qCOfZQH=z1t^ zgJy}&_Gg$dGD^yuG{Q~|UVBaBrf;7pGbPqh3A=8ULrM4BeEeBVRWF)&+AiAyZtL^p zle^1AH$wER70z+Qg*{uzf`gfI*s~`hQ{0YBB9%l@<}x7QMRt{?PA#Zv#BM!e!eR8s zpO1i+RfytY=$%FW1wgV&i@wTCve4AC(QbXgWSaf8YRL+H@S`z~nHC3^oDSaIVRJZJ z;8b>06d)koc`xiMv(K60HJNAgyMIDZD441$0SdP4PK0g^lJ;N!`t`of{my3uhv?v` zdPe4_A+x=C!Kp(-`v{3d`lrZw|Y{*`foa1RBYO%{92PyNktaClt0>>O)hDLWk~6Z8R5X{l@GzkhENgQ-JzMcZlO z&N1maYXA4ZT|%TH#X%_ooZjf10R}JaT|%A-ICr?Cc5p0Y8z;lmy0Dfd7Ft?aP4Sxd z(Q8JU~2L#3JHp4lgoP-AH%J$6>Xb0XyhSJj%^?n^YOq>uF|f%9^$Si&DX)U6k@#wz$+BLia71;hf&yqt?| z=HhVqXes|2Mw|hv(oXOhpY>u$^4y7OR0Z=-*4KNB`|e*|b^|e;>K--liRGo7mJb1o z%ym$maFLM|a{n&(vfqkE)XjT;>O^xPpu_*L z{9V%Xje_u!6^~>A&pbxLUz;zYu!5zl!ZD{i>{gytPcH`qFY?_O%oSVIs&1XN@Go`p zh?9ehYrGylm5F$t@YkwHk6a|VAU4FyIr>H?ScnKTIOo%xs4NYSiN6ER48nB6 zMcJtXcabfU4BJOLWZeYLuLksWYilZG*%RzpYCk-@(k-lDPi0Aq;niZ%MbLr5`ja=UWwQT8t(S;Ki+n&_sxHx}c$o}#ydHvv@ zIGT4xBq;gGv9WwSx6Nr&t*E5g-%%cKhJwr~!|*BabwR}y`SMo{^$$u5Zma;+tMpF{ z(gk(_Au?TIuyES|RO*S61WyZm9WY>1KByC-3RH{k7hBky=%{V`bWHQGo{ta*SUc2> zW!9W`hq<^gX>Fe0dL%^32Zn@Ol_B=2(H9-=Z$F?6d|k|XPw)MRc>?|3sID8`9PGEf zzi~4=E?@h4>|JIV6+$=h6m~x68`p0B=#f&QCNXZpt<=$RC>}XAt~Nk@Eh5YuhUBd$ zb+orvh;&6|fZ}pq3cFqOFL3koztbA|jGSO8S{KgTHhb%tDaS#`r8Wl&Jo+mVynrK( zj*||uVm^e*C9`!AzUa09ox*?$9L`9oVJ{mp%+;td(u|1vlh5YW)yxjUD>&)d;H;X* zx~OZa(pUW@YhjD_UWv+tkO*3yLxHew!0DZ+j|Z`tWK1 zYs;`6!_?*TbXVehP!1y1Zl0TnQy)w{kU5z^lw38X1!f@O1jcJu4D$8R#DH}+Cb4N6~r0P(9kYkzp$`CB@VAPq}hq* z=B0|}Mf79R{Met3Rs+8bOLb%OUg_(f3}x>Aj8j(0)&?l&qzr*eD=Wd7nQ7?6i-7@e z8sWmx?uj7*4#^L?`~KRK*-mQD$xob!j4@IF*f!? zNg0@cOab42spddjL+GV(B33T()=cH<%ezSX$%R&q4!fV$@Bg9CHt*1h)+e&7lL1^l zQosYQWa3$s?&3qr%a)(gUm!m*#Jx6+O4J%0w4tD(T- zI0}3;-8Ox?#gs3&bV=&2g#Z#L*&<{yfO;pD>;P2&fkk6^mKUFn(h4baxB{Y6s?(cVA1>r}|$mGs~N*eY$ zgOd|tqL~ElUpZt}vk9hYnd1oNlSJ#j=91+EH}K)KxB0THa{%XnR*NTFyz!@~MfRQ<&d=Q08Hl$e~#4e5MbBa0v zGa+{|*Hddi$b%zEWvrbMPTjyVbqmH#I^G6;B88VN6xeJxRhdtCmCh9!b_{N4t~LF~ zpIG&O?uFB^OC_fH`S=RZzi`Y@nl#sTZv(;ddVBM!G{-~*4xV4R4mUzHt_B2CSlj$%YH4Snj6{ zY(}+qce($xFM7WeT5JuVW~K>~OK3`k+VmsY+3)s8f=`US?d_a~6EAcUmPq&KcNXn_ zX2(y*-%#cLddoJ7o|woSsDFSOPRtDbvwEE*5xB$G&F6EP9M7-_&C45L;S4yXv2?Yt zF>E1x_~pX1qTr*vl16pa2SovPv4bI!Q?>7FmjJ z#tcHyrjxRJVN!Yd`I|o_!$uRC_#V>ioXbYrX^c%xD!kUSw9|hIFULkcezvh65-8ZSc13?C2Z+=amdVr8r`F#3uXUUY|(V)#+JWW>3O!A zdBbHId~^O@%npn)^r&uRR~F+0|MQVeZr!6<5f;SCtbvo;a3jtiC4^sO81acwk@YVi z(bEy9T$r+Vfn^i{s?WG~0)9F;8tMiS&iYl20h^&9MSS6JtN^U#S)< zINw<-1D| z1DO_kgGFwR_*EGjQo$G`2-yoG+R!7Q~&5cXY+T9BM3#xEaN7LqKDQJwzY zrNODw_rqgzvz0es#IYK~@jG*h5qE6ciWv$mgp@WU37_6(eqrnhIrYK`8^Y%S!qYhK z0AbWxq?kdnqgDLHf?&F-3d3rD3L2|-M-I}9*dpPgJRnY-)t-!bEf$EhUsryJ|4_2k zcdoB5E#&Qtpl|^`T@J%f9Pspm!NDfRVd1NRX|F_BqC&PD7^}<%{fE!!^qFoZi7pg# z@@WP)?gYJt3MSRok*sRN(yLFX74L%YT?e<&#to@F=wTNo zz@$^>BPHX;dr68|eZujahFoLTdz~u(F872+B-Q#a#ym2%V&P)E_oa{n;`HT5%3EIo z++#nKJU3s*Z=G6>DDAV;;odS^!Pw$;$Cq&gHmT*yST+eq#X(D|=ZnlFS`8 zY|I~*cdUh<0D9JBFm)K=Hr6OwXI(f|BYTUKJ&*=NEpSqYXoHx5wZ5-Z6IIyEn z@8fU-6RUrCMEHZ%m@sK4-snBH zGB)5N#xrUOb%eb-D9;++isX0Z7;n$A=Bbb^^*_Yc%tLWVR;;jyISKT!K&3fxrRj4; zz4z=pTy!$vexnEOMYikpb$O*lnwY73N|Lr?5PUl6&?L{b7bF{SI`qBKkc{{yJH?37 z#FylP(SI{rqdeP`fE!#zFVZTY$$}0&lBy}6`&Et2#67=uelqsm%yYBvqDa>-5vYe@ zvBdsCHXNfkBTogY{(9;~G#$O_W$daF@B7Pwx6z4(Zy5g^IXme6u|6m!Fen57X?$9# zMFyE#4v#~B??~iXlZ74Xv00hMRX~R!dC?)?l((o~AffZ^Kwp#w*WW(H?B9$iugj_4 z#i4nRKiHPUR|j>4b?jnJEAu=U$Fgn7kW)L^4G;v2Er2G+CJp={3i2QeaYNRbP|?(zT(W3%C9%R_bJAT%JP$x4ao=(3h)W@8UVe#w%i{| z^7BKtw-iwzX;@n-Mg&*24FAl`3?0qs*Ip7+tBS$;1vjn$Cjh@h&pdbmu<%R57|ufK z?q7{Fbz3V)_Bz3`ou-(1ctcSXcDj73Y8h?z%yiMYe+FXVd-JVGoD)e76jTbDRTm7E zabIi>%>EtxDE6mhN}Qf%x|r6bg5{;|h*4|QqG?zZi8CzT@^88rRarT@S!~Ue+Mj;0 zjrtiah}=Gslwiz?eY22is@OrzSP$pwOG2K}&0e1`1^*tzjJZ{B!<*d2tSUU4m(@P6 zy8_dA?*$jVeEAaVG+V9@e-$d@Q*C4%TR1rLKD93S!h6|6%+YZRlxMffKGc+dP<5PI z$t-R?TO@DT{{kUNpB*=}-X8w6?62F0rLldVI}0m_Obf4=VxCo#bQR94xICc0=_p>p z?#@PE!XMxs_jxc<10%l~Y4+Vlt>8B?r}DhOIp8vMY9nIvu9nWvu1@mUyLz{i2FI1_ zqh%$+c2q>Bd9(6EN!`q(&W^6rHaxKm;)%BlwRSxGV*NbgNEwUE%y~MmHQX1z`JxRQ zd_&{dXg|&05iu%Lm-*ViO6}GzwXVSs2uunzo*q%G`8~rfIF1|_sTf+xd)%-s4Duqh z={^3awQw!a6w({LA^D+&Pg^o~ypY zaX@lSOVBM7@NK=;Y=hk$j!f6yR8{~|q(hG$@3#8vppFl2vl62V>};)dKfiN`h%Ngw zTldXgxe@)B3`gU+OpBaxLnL)|L=u*EIDJ|zrO|fK`6n11wm?+Z^S-IlH1B===g%Ud zS5f+!w8Mc4%Ho&glw>}8t2#a#TKf9>>#Y(4Kh`f~D-#o$oJEA|*bIL|kSuEJns(+F z>%xQfD`0WEgjbB6H=T1t7rwfM52_&TxBMk)pGPYflaHZ~NNDODhM)ECyIJB!_q0`UTS;qwV^1e}d%~$OI zB{McgEn|ryl01#_ol%yt8belj9S`n;=+P7N9;nRj)RDDAn-U}FEoZ8o*ZWdqZadUq zQ+0j7#Wg|jSNUG`z5(0Q-5E*C>j_oC4RcA)ox%O;5^B0!+_O&ATt5C*cMwidh*`1GWD=lQ}qc8HXU5v0$Om^F)`r*bf1oS&7N2*=Ua^V z@iA87XJ(qp2qYy1!qqSf?G^H+UMs*iNE>*iTG+7Jsx9zlUyY zC`(I7aNk`vA{tDbcq6_wmn`=m{cyQoUc6jB`)hbgBQWcdz`e%nZM;CBmzTrXmc}3T zFN5P60@-q}J04@dvfr2S_~Rx1)gL$aq>gCRKr38Yv%4>ZZWg<28>%2g&@~Rj#RTJP zB&yndZpusM8&xK1Afm$jFYw0lBrnQbb8m5H4YKmmbks^!{vp5270oox8x!_EDcczh zpw-+y&2s2>N{tk3>LuBumUeZtS9u(mwfN?S=N~-T!{1j2>&&~3L4yRJ-nQXCSt~34 z@YeHd1)H5YhOV1QOyc(%r(S{lAB)#t>@;a@Xzc84#zIDJ=BCq|Ff)O__@Xom@3?F1 z_W?yLZ%0E>Gr36NGdFYIA;o%^f!RlE!V0->l~bn+AKGiBlaweae+SOYmfbxyLlEfH zL-o_jhSapn6R*xIhYqki!kRNj>D=hbD(;Js-HjFfUtkfc5lD_nh^Is9a=Knl8f(Rt3ZY_);>#81;zW6} z>Kdv*AkfdWw70ec-BYdi))V(rd{xTlN!06R}p zTU0CmvcC3QG!3EF5&r@FWuOq4>2G$W^Jo`nP_fkNdJ)v9W`ST+UKZ6<76+u%>`jKI zohLGhEeHonp{KA)+tfWAC4G0l#c?Af*L@u5+nF+O2Z(bA6KBh z2{mZE3|&m!hR84+8BeI?k-8j>whNTij)DvuZ*S8S6|G?}Ha=x;3FX|J;J6$UWpm{7 zXD*$@>Ge;oZS9?$WCFe7EyVymJ>5O60f)}r;dDVZHkSl>RE!ta6@zn*4h~t;J_mIX z$`L$LvmcYQ6vc!t_eS46(BO6fi0LNU;Z$;G@vNJ-n|Q-h-h=G;!k^BYf6CrfY#SO> z=|>o}pKocCwx`#-aFPWM(=Q`2J#|JOFbA^S-cU8QxSzbC%XFM>k$C7p5v7ev`pRD#A0In5 zMiyVayKDbTTS%KfD{WWR=A|Uiq=$%9omzXr0xz?04H>E+Agpw7&9>K zquMV=YXT}N+pc6S>Rc8Ged3dDgMBcQ@j5@MN1vinZH_wy*Lm|79uF|r z*5NGb=L8SmSS(U^;~tb@I1jk!%K3!{_@XGhmGoCwS-y!@RW`~7#PrSjqHbQYZshT z<0S6y`%+)6UYA&%n)3!5_1C-{P7qU0IDM1LaNi3#+Qj$ip$H&#w>ck|&*GrJX5O=c+ACBCnVMTe6a!@?CQjRr=z ziFCi6skXKb$IMqQ#wxUBlxJtfR-8#o62`xQn5l(Dd3byd%h}E78BEdb2&tb(hw_1& zDS-(b100;s5zn%V2A8x;9V;gM1S#yt*58e&pubWQwPz|x2Ozx$Sa3Y@`=f`oRhvf_ zKnnh?t?lvE6V8o}uA14|Ggnh94{5Fo)=x3`X~s_WKAigS2#Qx}-(AySp1?(+$$y-Q6MGyc6{~ z_jBIwe!p|h?+gFpr|!kvYt1$07}vP2YsB#9veWj9>)kA=XnZz5 z?xe4Ay;Vmc0R-dPaTc?6*_AEF!fWG)_UPz~+}?%KL{2n-PN{u)$W!TDt>1gh{}*H@zH&a_rfX?E3jBJLe3e))3G6IL9{He2M;{vwg5a}L_&l+&dx3s1{*e>$RT(@$n>_!6Z12A4;z@~tXm0#tJMYbJr34%=0ZL@o(ob8BD<~NU6B{}CE4ea%%a=lp znMIYd5g)@s;+p?l{K}b;v9v-+2<_FqiHV62AyQdnqq1h%MTH2Mn4nO~@*fWkxP51I zEgc75!Uw0@onUr>-L+GjD~~K_g^b)fn24%4Ez6O z$B?3T(F2+d60cdQ#xd>_$}Ss|Iap|HnK58f9`2t(W_0@dlSfBK2?%*QRVKG959#R{ z_`bRR7OkA&g9jIc=Duj$(}`&`Swf{Y8_`*NaRj7(x_xmG#!1=PBP9xl!fP}bI{L2z z2!YJ`>F*m?j~aLnG7BpI)7{zYzHK&NtlquB(y4JtVr>93O&&E}o<@HYp+Lpwp8f%l zXyGoP6YbhM+(3W*!H+=m^JmkQ!StoJn{gTAK(;#`)F>xMT7A07rP&!qm-@kaeLDU9W6iQg zpta1EE$sO9+#5{3@nYN{wFMGjK60mzH&+1G2$FymC@4RMnoXXKv$0WE$4xjh0~Dsu z(4T?(A{0s9#GKTcp`-JAGhUIc$2@UHNR|j9#aQ7Iez|;jCKY**^5=U!z7PIsrqZ#iP9yzCIgM=2 zQK~2E@4a;<$|@Td`+?t$4)l4BW0`4`Y9JI8LdIRdwSkRQW}-}+;m<`}gNw+){ZadF zv=tGOE`*tpUQn=`4FB-YbsU4x{z!&e-hTL(@(B5F%xl{tr#i5-;W0asfQpo)&5qWko%2S&w2@Q=7=>l>lqqkYn-Gf_(cY$Ew zxCf{qD%f@d1(X%wW<N82rEmgCG&JT^0G90wZgtO6#P#x zyV^8WS<#-xqRATPjCLb(S8E6Kr6p_#V_pGK<0i$kJnFlzPi`6j!RRrJ#9}fWlUt=6 z%D1D+9HU8;22W6R!n{mILQZnw@Jwdjw6fP~>s%1|Jy3}gJM+wqM`2sTzD9scfU|4P z!w*~peCY^M;a&xpGRd=A$Kw!u`f|P&Au7dkC0fIngoN2|D~4Y<2}tRa8tpPy6zAL`)#+b8Ky@Vc}o!ej+|a+sExg{6fSHw~XpdxSaCww+3h2 zs@2~|$A4e6_upRZ-zvaGI?xBEEU3x|;gvDPLkXl564O{-)Yc+xH;jm&772DfqoHJo zzk7?$#NPqMpfk-<1Xqch!h`Y!LddXwBfgt;mEkfOcFIuXW*rf-whwmt+=Fv(SWyD&=S}XWdSidQv$e2G zot-U{4fFQaciP!vfi^GwBn_>yyLcWEfpjGgov3T-p607s?MxT8x7iE3Y{<%j7#bR` zO4DV80eKKiU%3Z1b&YYz^Im|?fV@OC?=%Cw%T3J8$R9mzr?#M;|kCBVS` zve?bWtya^Ko{@2~GZBC9s~X&|xCsf1j@DN+$gva+&yk%`Ryj1BE3rL1HXNnh2j6tK zz4jq$Uko=D5s^cGP%=?4gq(b1yQOQ;$l7Sm>3TAJIz0_?2!-K%^NC z$wXs|v?-3ZMw*HYjxUgLPj+~C2V1AQ3@^e2W%OoY+IEUn>FFz*R$J*1U- z;QwfFZm(p>ybD~mC)*3ImyDI4J7CRee^I=X6S2g2hv2JAV_VUncaT3X_n5rrXNcS^u zY=V=}drq$$8h<^#&QD5xF?2JNtr;>KgGww$+ta1FnVy%UJ+Y(4HO_af51;*eqRXw%PW9<`_e0&je#egz zFO6Pfc$rsD1CxT?$z6eP3!R(P)Ldbu_Wrl<8k!o`d*hAVS}T)QYhsDOjYK~|IOAw_ z2H3dF)V#``sL-AYe)mwds^X&oi6`4=p^E4ZkGF z=7?itq)D4~%k6fwPOm!0L!ZTNuYFT)H8w6P|5dSQb}H^ysux9~F-({1t0x^pLzUL} z2siIOAmdF|I!*~=^%jS6b8`b#u5{z%Bs&8!F(ZjvzD=H@|L*0AtLO~)DiEVMm2SJUu}+b-P|~ZW(K8vsrnZdAUap+XsGQ; zk;rXppl^_#=2dS4Y5^8;Ws}L22UDNq<;!z4OM$p~Tt0{7sn%$L(&@%h8`2e4Wu+4~ zi+T!uqFSmP)yAQx;aIllDZ+;jCD}6Ort5>HcuG8ut8dEsidM< zdj9nwkdg$IHh?d#Rap z8B;NZBUxp#iEN>Tb&f!UPyE!!lc)B}&GgsCcW7QWy6u)dK!lIHe_ANnm2Ev^_waO2 zQ+H#19k`XHr>DoWJH;`Fq`aZ-adTHDs#F>72B{N& z2)MDXObR5NS-WCzy?ZLZgTwHdcPJ!1J0pVt7Z+x>6Ei+u(KBVUJyF^;*eRr<5-+8W zk(5F5nvTtpm^3g2>63p<=?4_N$qMf;NvSM_YBoEgsk(*SZGrgO^L;D^;}X`x%7Q&h z0)f?*dj%;e7Z)qSWf`KECm2S|CKD9ES*;8`1M=+IA}S##E%dCNtypI@fy3y4gwTYh zEG{NQuKq2&&&O;|^X`iAaXkb$r+dFN=}8hlfBsZrHU^T>9PmD>tE)?A_MNTot{z;S z_b(6=aDQp=LRVuC4n`Y9rK4qh!J~iRt=TrN8kq-wc}lHX_U)M*;cUI;d_A9c8!**D zdW=$Kvvv}s-qf4O5euyNdJTpvI{dOj$)Bd1pQ_fb)4DB7h7?pLa&g^8b2Igk&ed5l zFi|maa8RDUk(I^du(xMmIIO6s7%No1INB44)s>P82@M@u_FlpP<=rp+`&YiA)ETLl zLZ_f3=Pl^{@MN2gjxJxNeD`c%af^3zV@p7QUyvtFe9r0B+qYrl_;d!0N`Mx&((LAT zs4FfW#i>0$?-CL!wh%a!C5X->TUvMhFiPo@gd8Uahmx?g#gNA_cyDE;q$ng)+|pLQ zRa$`1F@DgY*|y#qakw2rX%PUSv{Bpjmd@DR+~`sG4tc{!LQizC;A$@eQutLt=?qdb zGSyl;g#$mheT!db^w&8uQc~@)lN}jsc8%qpEf(;lvXx<49YH~#H*{VH5{iomeH2AY zWSxXrO;H2{P)1Pe=&DqkKagA}%$MCNOXRWlaCe`svQ5nhMJKJ@ka)nK=6H#mW|S&F zSBH$pq(d|NPJi$RjhuOaULz;BQ=ZI(`otnXxYKTZYleCTF)`6bb1-jka)I<0#IY-# zrPpHgw6vdU`Cc%GmFI)11rq}sGV_v?^G$tQYg-$`{_9w7?T|F(d^@YE!o^QkgTos( z#y}vxBV;ag;3gP~jD)m;@`bWztc{Y2Y3^QM_?MczJesjb;7Bvbq*fs*-lmj;PUMJc zKlIcT2yAWs(3ik+yU_G7kbv{i6J%|;`OM$O1@)o8FXlF#N+4W|yETAS(`fnaSHB}m9yK+dITOvb3%kp-^mNz?IL6#P{tCpU3lpuc zu5+HN(a!xK8Uv#NF9nep=30g%nmQ71QCfaxpZt)BUmFt*B0tD}cZ;eJz2)S?Csdx8 zokz@@uUKN+?k3VSuP8}9b2Z-4xe*z!@^O=kd`ZPdM;!q&t*^>{exj9skc+SP|IXF^ z(Xk=F_{Q z6bU@atB3k}6k9ksnA0Cfq(*urI;0jcrv1Fzg~mp;m(g?{^XotUwE~R$|CWXl-}y?` zyOb5wCAbvjRIvxP>CX4P#y}jDmR?FBeunO}j94{JaHDzCw{!0X;a48dJJ6liX&U~8 zJiEiptVlrt7$nty?UI#}lN_a^9qb=`{N#jkP_u~Z>hy|d3jT_;p9u^64h)|Z6pvgC zLaf+?2#>5K9#?Lm3tnJLP{CQ3t-bMs=jl|F^B}4T>i#M3FBc1+)b!jw*~QnbZFKvD z;ZF&3o25qw2WUhzp{TdE{F4Opg`jA^yRN`oKPwkkxXW$H(GlZC(vzWQQ%!S8``|ar z{*DogSvlFDM@+w;7!e))me5jNQN#WW55vj+YdsxquGv1n3&oKa6W`uzpSX{Q8lv)dDOSt zx3{;2Fn5$^xP|)6E%TJevgOXrnfYAS$2W?}T3bC&j3bSoV!Rl%>3;+^HRYcVi>Kt| zR9XI0$kvDs{fboD?+CJd|R@--EyQPb)UjcP5o>Dk;!*YgNk`Y^^XKMzI%xE@}? z!{fj~T7T~XIG-f@$bj-aE-!yzle)gO#bo^H_GscsH%&%reyPC(kz|D4WcPX4W?D?{ zmVYsh^)URJChVLKDFW5ahTT2!Efp z7}CJojdv~qd2^JGnfYRVvrfB>fQe~@Yl@|Gv!9EJDI6E7SblK*aIE%WfP{jQfMM4~ zxV91W3jTii&h+8zNIZp6UY7_q0}MJrUsP1|T0D`*d4mG}HZfpFF%XBX2K+j8)e2TA^qRInDCgTT`9+m>Gut|2JvI@RKi7FKKSxd6hF zj<&Wx4qMvS))9PsYSl`*&+B@9eX7Mb(cmfOWM)?DoD=ydA)w$FpEe96yIyjPE-av7=tz8j>rGQtBq?C}aeZiwx|`-5;d;Be>$)D_IgFWwCehJ!3wC6*TH>wS zr)DskhV~#=MC??>z8X>6s1wvFbo-Ro1z>6Lzd)m}8aZaJ7j5G4whIS7orWw%rQ|9Z zUt3WLxGHTgsWF+2W+rL`iQ6c`dqn(-VK5dbT3{3|0oq%2!M3veg!(TX4Y#kDnT@y8 zaPY>cQ$K4?d5p+t8W=o#hAZ@#ZlgDv2S0rb=(~l1FGyc8Q~YGPm30oc=j;6SAG)cZZq%U;+4i=+2}gW4g?_gos0uI5rwQeTV3m+J2zBC_d)qy#*c z)+w5y_w{DZkEwMyCVNFUkSx^#QZ^ceA`c3ADkam?o24xl6NY_h%-fxNKCgczP!b}f z&98w~GfaE3ZKpqDrKkEdyL-)X!z4RB`IUZNYHH7O))xU~W!7K5q~-Yd6c*kl#WCU* zmC%Zd398TQdinVfu$(6v#g1xuzsInWfc$`T-l!;bg;A47hrQ5?s@FTe77)+sPck;* zPTbpB)6Ft5o$s$tNUXs=YjIjSfpez*vkaAbt8(efGVz4kk3vGbbD5qQ8D#E}!0fRn zhMC*(gb(yoM0!L>{I`a!={cMz7#X3>{Vrgy5Gv0&TwhKDuDdLQ+H0KTh7p!yRaRe)95Y+26l7agoXqv9B_W0{N?bz3p4v;-j+AY5G#x)5=Nr7@{s~iWmOIsVYK;LO{l}xVv2j1kg|r zZb4gbP_*h`+g;c)RG-ax;D9r7erJipY*Pf`2E8=^cQW5XAX;d{;%jQEX4MfcuOtM- zPJ-VJp)+`ZMtB?T!UK7&nuG?d+Bta;0`u6g5ugi;EM| z^cK2Q%8FHfRsah~EF3#$$aJXX-onAooBS?2$V>9fpOB7~fmn0lfJx{1b0{g*+F&IE z$Q`c69=qSCmM5naZfQnY)rLZWJK5_Wb@0W!&RWwoHr*gFJg&TwJWRI$9uq+u?e7xAc4s;-(Rq5u7t| z(DMlNMx+rDhN3#V{s0+=JOIIcKFF)hHO<6R34Cx<2&V|G?wM}s$`=X`@bmgqtL0)@ zoA1aEIPNTk$|Ouc^W4$-+_tJZk<|{uOvc`)I}9AEl1y(rtkP4GV@UdgrbME1W5Qb^ zhsa_x6R2)KD`&tc)Z_!tw-#bQk(5*|4u;^g3rlIlWdsxi6sYn!ynw&uXRo^W)_t_x z%;#7K60Sp^60Qcd2Y&<9ET1@SGODUPq-X4aXV)is6StkF-yOZ_cw26r0+*Bgs z&M>O6497M!%~l#U#z2?)SpAs(9K-NVCS_T?rgn=BH-!jyEcTnuDJhF`qM z?YY$TNkazDXm9KId^{OmSgx>d4<{6OXPSkTKyIc-(nDV@|6F!+zi;gEoX0)*wP;vy zcW^!BJ4rposyJN{!H$OK5Et2dJWpB(6zvc$5J-`b{JuDF!#i^)^9Cg(;NsyV$Q(^$ zm3iJK-0Fe^@2~rkkeD%Q8bAp*Uu$KekS|=Z++C)l08ttzoc82mJ3Bu=HMfv(eNP}9 z8JEdFz(*@pLh5fsT}pwUR4I(~DI$;=Tg=!wVZ$E5&C`TpV7+5Oc=@pG;n#ZPyWaq| z#T(&>xMHo!k0f@No1`3C#_m4hiY3P7pGO&~BRTZWAWwuTbNqb$xhixsmtA^~ai^=C zWa+arGs{1p;}Qf4Y>1(zBlf03 zRLi>6iUo~WUNNVEr(~Y&KIzJ`7Z?WM_boQP_2DlJd0!e-K3^A!iZcl0#jEF;8y6;C zmr~)_5}kQph3EkMS(lO@pCbsHunk-u?yE+!;ay7v{Q2im6Mrw{pCaIo-w?6co31cT zxcNQw<;&=ML4Rt7ha9OO#DGTApUeNt-TOZ^Em#FG;Cy^1Hxgw-h7pa?Bd8H?K6kf= zlgy{JU`)F;E&cvV953&_QVNVszE47o#Xk~9k*ZGtusP$aj-}+~`}T@}M;+T(e&5xcjEw9UbfV*$-6J|9f>{)78-Pm= z-?d)O;=jRPQwc}BQES`{Z4-!A0G=A;G1 zjW=hRV{Ur};?PL5LA(Fj=&0o=`%+Pf=>7w6^MGq62^q;>=a)MZbpR?Q94e3w;V)I3O?ASOi0InYo=_X#B_8Ug74N}2hIb;OjH!f?vk1UvA zb^NjZCfKW^!;AV;T}(Ww(aPdElvX5$(F7A8^XJVDUWYUi4pYQEcZ*<*u?Z2ubWYjwIL?s*-id+*9OQY5=vp7vqsXqDc zA4#Pm)sjpf*@gV%iT%m6c3ZDXi59}V?w{KC`LkywPUp`=sq&Z8NMh1NQeiOjFP|VB zHW$sqoNcOF^M=yayRx%h3$#cklz90DS0j&ff zgI+T>GBPp+Ha3p7j@Gc@a9AffIXNJT>+&x6`TMgNeR96sjW=5&V`r67tuWt%=mO z(ycMoof+{&Sg_>dve}6a{huih%J*h3byr_Z9jxf|#L?NW@;rG?rS9baqrT_p$Zv&G z9^`c~QBeTv|Gc&8uTpgiLS!i8r>ZZ(v9b0|9>?GmPbaLfxpfKLRjVR7yL4u&OU=ny z-P*EWJQGCmEcy;xAFqSYk6R%AKnKSI|7Ta042J>ZG!#z`oxu`7`Ra@3RLvFR^4S$5 zBT@T$2N)fdmM=hf|)8W7=KqpVH$LKhr=dU zHg~dADe~(6fLD9_B`QIuOqKK1c(J@%nZwE^lX#%`6RciJL(Qd?9V2b+iB$VjDy4FK zwu{2)?Qo{nTwt7|UfBa~QR!iD9u~^Ar3ONAIt%3MlP!rwT zv!9w}I_*g=IR-gk?`87Jth&t3a#zZuXnV-#DN{vbAih6hW_uAJ^0aGtS%$@AVl>U{ z9Ufk6Un0-mc;#zai0O}tBC+05BH|QglNoATWVmO)qAG9lxBFLtgxtLD$hi>!R4f1_ zaUoBgv`k^#D|=HKrT)QDTyEuD@Nc{o}-LDV{t{Cf1wiH-IE)br~Qc_MxQ2ADJqy6Q~&ly#m3O z?2Mp1U2u&}6W<1jJ18%N&YQfvyr%t?%Am8rmZ7~Jf`t_c=nrjeD?fuD7dQI~bqfy5 zTUp9TE#??zsnwcG3Mj=s^9EKsnQ-Ao(Gg-3ZAfKtVNswd2uY6NcsepPhR3Aw9#jZN z$Hzc*R%x)q9=*oIL>G)#_k6<$cIKek^}I(@LxYQpYdl6MoZ@(6%D$nY5rcV%q$PB4 zN4F=gPHW&>P*9K|i}CJkEsIT7c5bFpX4zq`yoq_A#_{^VPNS>m8jUjW7bZ^k1w{&k zXr{vKN$qfDv2L01lxo<}9zO5=JIKylxehThlcHR~z&vA^oWd4e+x&fppdY6KUou2c zi~$Xm=PO*jf4*Z2S&vdYtNG`?0ICumwb@Z>B2Gq|VoI#uTIb6QU{xbB07SHE^_F$g zr>Z8voT_SVDwc(v-u!s*0mwDNs5Rrm!myv?R#{J!2Q(Hxrw-TO+q$;xs***bPib*= zsjEv&tku-ZJCU34U3D_;&h)TE}?Ii8N ze5UBv>HAi5yYU#`3D_Ono@H{`S@Kvf?_WLe1s2v?c$Qm}R?A+=Mw2!nwxm2)%pF0E zt{(!QtsRoL?+QDCGC)@!S@pEh`|7$c^NnfZ~;oiB7d* zeJY|}f5{H=Lxg6h4;@KA@q#Q zba-6)p#9=IR6GO(OVhLUJ;mClpW$Z4E#CWf*1_KCeE6_I&kQDR@CHR!-%IQ>nX8-v zFHHiMUBhymYbP&VMq#1zR;z58!`A4IvrbP314pE8tMO@qW5`2r2S1+{;9JGVLsr8W zX<1n2s%$kyM7lvo6ZC&0g>8G0@mS_+Y<*7K{X;W9^)rkXR$pec*w)cKEG@k+s&g5PC}T$v0|C&d1v^( zSG)Q)cmA^uMvm~qHs}_Uzw;rg_JWXuZT4(RL@G5k zwN}4LQHWM7fjyp!N1b=j-M|BrdrFn6;jPHI)~(5U8?2TE2Ay_Q)ApgE(5@A!`-elBG;2E5t4Tq? zCHr+4e!fgmO0E)t3X+?e{VYuVuw2l?KZ*^h;q+HN{FSeCXE#Xo)wLee1Fh{-ki46)e3IkVz+Itog# zw6fY7%FNU{i!+eLCr8laNPYe_#9pNLBjuE-uzwA*QzCX(O(Nw?1C0w)))Bx!Ma2Hl4hg}Lu zY^Rj+g#!}ux?92#6l_l0QC3^bb@sR1r>RgQqYZ`o_gxQE-e6sO&#(Q?tPrivr*W!^ zv19TWdy|Kx#i9eNV7gKy zwbI*YF2gN)#;t4npV|yer6nJb2!(=Yhcf&0U~a(!5md1#6eV7FivG zEKj|WFM#^$^r*}z1F|Y+XQbiy_j@fPVDMAA4vku!yB?w4zp#LiH~Ak7tg39%-L?gO z9xE!AL5=l3w|lI}k>+2V?pR!OD=_;`2 z;@A$?`eKWr8yc9}+CE|e0R+UAWSL-8My)$9?Dl4JR9$Rr7Z-Fzg{Z`o7SUz1eDUn5p9YzWO`;=cMMY-&{d- zwprgtLvnh;^CZ*9Vkpat79r^qaB5l0)gN@WLqL41B=0czkxp5qs;u-0!>56QRd?*X z_4vtxGdn*{qB#j!V&895S%($sx~Cdj6logOR+!=?Re$Ms+|eMH`N2H7sb+iE`ci@%c~% z`4D+>r>gRBwwMZ+V-rw%Gw|d%Jg5eW8tOE4%^5V|Z!#JKN z+lc#zz=$%t&PDy6uTP+_3cU>(V6GluX^VI60+iEOLr_L%+|q*#VLozcKfIzU#ynO(gEV`+^D+I9=7akI&w&9zG5@zCw{KIAWCuw9O8WE& z<*59P0u1axaRNeZ9YEaymM-G4)%%kzheqty-ad~qg=CpZ;dtgi85a&w&r8lu&opVc z3L*ovSc9>*^p!eYVjGp)X%a85bO*8Rd?tJ&Fl$Q63zdNcrVC(R3%^1coI8blqtjW` zPx|ntR*|5D>1s`1&)8fE2rzw?fE$Of#y|GnKHY^Vu@lV>WB9GjR$XHxK!vTZ2G_FV)eDO zzAp|v#$_s^Q1Efl;8jy|?pSE;JNxfEelbA!t@E)!HwrOGd+N-?s4 z>k7Wk=;J>_6k58n*;2OaL5*N>-Q5@!RaLv=rI&}gG}dxka#Z$5>pGf7@o{knU_fhn zm;9r@_*U1<{!4J>`nbC6^Xv-_j_MH7e9%#wD%*nSYZ|F!*pC$i$l_DI>3+w@2ZsJt z==RNm>Q>P8E&K%-K{`6#?AEuWQthNUd*zPQ(D(IsU!RJEMDO~5G)7UeLr{=0+vIar zUfv6W=bgRr+^5xCGxB|jxHz%2Y_GD6+m=T>o$JfKghdQPoGln~ z3?s*PdwT=bdx8ran;WP2jA2x<3W~Vlw9g;WXK!D3FpwVKD$-xQS7J5-twC20Bya$z zm6*;BlKPT~#e`HxClt(jq86CU)oqQH2X^QEA5jYiI=a~krT}w_5THeAqB_oifzT&YTF)kY27TNXpEWUpLfOm&50BOjO@VQQMi&?8^IWIY3}Ar* za%x}Lm(^m=%OL?&dt~eqyN>(8663|UNdWNXu5xOh8O*W7c?bV4X6xd{KkcBW3(K-= zhLxLIE`;n__a+2XI-c$x-$TRDw3D#2q^Bw!&dpstQBIGKQ#$}kQuwLNjgN-L#3UL_ z{(z=jdLVDEp}dzbP$VX=x4k?WA80zUJ_#h`DJ%S(nVnr}yJbyCs20;Ay=XE~lMJ1J z6&M>M;|}`<1}5^D+- zbk&ETeHZLJByNxvFgD01GQP z^_KpDx$TYCVT6$=E=x&K(fQT+VL-h7eb@W1{qVMyl_}|oeB^NRc@gIA|7-kYzpEoc zaZ(W&k$kz@zd39Rj7q7nJW0!sSJ}Jw4v^d`m3J%AZTCJ%2V^-$8m~}{tFSu41iR#r zV;Lh80DXpAchUymgPgWt`%^gLWEDHtC9(!X3NUQfO!|@~k<2G$K6rVmhQiM2bl|qT zvrVxKoQ_@l)=HrRoMdF9Lqo1)Ja%?q4&q(CZZ`CsKs;O9SEsSDakh>dx>RyxDQGjA z)=WYWD4+bzXqQ(;T+L+I3(X&wxqob|+H7exr*vyEJtU%exS8ZM^m!`NpP0ENZLG;oyU&n|t>#f&o6`uDUrr!Jt%bBpz*mz>D}B<6~61^bw6IXE$4J zNWfRpdstVKuk!wj-mVT9w_tyJBHAI99!>P@(O&{6+xQ&%xSmZDMfxfp!;eh{r+I2F zj|TEV&k=}67zJ&Ii(d!8ih*NGMt9unp__%;DN9Xr?f1!1U<_#HO9}dDU=mmUjMOiR z2$%j#|GFe`7O!n@bn)s3fi{U~sd$UEo?>qzh2knm5ownN-&YwK5ta0dIULP&pYDarFRk9bB5OFed zIXHF-W;uzpwzLe?X6qBUtQW7*1jMuQy926EEVB_zb1K5c)wAPGJ{$^4_*98;rO{=i zOEs9{3o9<>u-0?F`O)Hb_7~!ha-*4HzzZB7AHQRmUyrWlD`oFbbZzZ7UhDS8gUMW| zq8@G@+v8;;or8mYbBUls@|GB+A-n^eGc(iNHH2LH?1^oFJheW@dB~i z(2OkOnK}lmNx#}l)aK?^swf^$4Pi1}Y!V+a*LQrQ1ykRxwocNPmq~q}XXSW5w0FK) zY*{4jngjz=3zrus7y!(Xc_s?MXn#|t+eZLoimo0gJPyn2Ae0CM;%qG}6gkZp_ zy~FXn(c6sXDmiSXqvFTx+YcRgW{da0v@1)ca;GJbw|7pC4_jGlAZ9vUR{_pzh55>4 zeOo{=(+lcIscJlCY@KOS9Jx!2qy2vmNuu0DN)?7*Ag8;_`Nn z`+9=9VvSn0#&Jn8R*tGSj!Qf=j3G@40Qlhb0wo`~r-q*;g1R-p06&X`MSj6J@~4k< zyW^O&57N+@JOT*V24`j*SMw%N30KXiwJk;bjxGm>hBTXrojL^DL6{EM747Mc;sf*I z765;SlJgq$kyOxliCC1*VTqwA1HDS^BAc>oG8C-xN-GN+fq?(cJu(l+j>;fTig33>|yK zgXwdzv__+`V>DqEHAf}GSmKG_iQxoUN3w5kc5;WqmTgQ_!znbcTUYosG`@LO8)~I} z@l<^$?R$Rf=HY>a!zKqv=$GXtvw`@H5y0zpXi)0V;iYF6KASo$S>2oAbpY;S%<~rb z78m1P!c5UP-k3owJn|kuhKZrB;8#J#;cZ zm2%_MkdVPJ@=*Fgh6L_QbEw8?K63JPvx@Man5W{wz+YHR7x^K<|l8R2M)!+Cc* zf6AIwreL^CbW6p)4r!hAx-KujtN)F49vNtgp*49rU9JB-+K80@l&>gDB`T_^iH@ng z0ul)69^XisA*msQ;jA+AmIG8mWdQ6>*!>8o7M_>^Og?{nE_!NaY6=R2)+7Bev|8&W zgnvDT|5xw{>ciWO+04Y4m`PB$DwXd=+3zk#TaZRVgP()8XF^1o<`TR0vq%$i?hKLm zvM&qY;4e@5t@&O}d~;W$UIlKJ+9tZ02^K=HH^z$``v_(x4&o*lqT_PQ;yA6?si^V| zWIgY}Ur6oJ5z!A0Ee(P22q8#CFuubTdpBmP*Iez(^%ufO;@GbV1#drX(QDhS#NEez z@dBpzQ>r7J(-~37>2LHSG$_dQU^)ApXTY+P+QtTs>H4UgbeqjkW)m+}**_hqa}OOokhJhGV%(p2i`%d2&l#(dibe-5?3;g{AwFJESww znjc{!3gLWBbdheU)R%dW4KMLVe{17#gb{t|XQ(^`m{5m)@LAZDD%fhb$$MEI%`f*t z&0Wnjc3Dqds)~SE{9q~)=YX2?6I5RQ=bg&(Z@9u8COEnR1!HRDayPaYZWhiK;6n_{ zS;q|fVMdT}AxJpr8yMQ`&JH#8SY3Cv03S7c zWapE07f}24D3y=&_owkP0wLI}kr_`ztEkd!ozn{F*i$5Onr9jK$Dl1N97g5~iHmd8 zn4liMJL{xiii-myetsm_Y+i2+H7ul#v9bx{O5mRSh(@27P~dZEm^p3&E&W3!j0YpF z8Sc2x0QKNgyBA-Pho4?B##CImP^e;#s6mI396ObW@k`vL(5UVrjb*_K3x=LU%|@f3 zManxx=i3iQ;>jsF6oRe5qvXeL3bZrL`(yw$Jc;~69FchWn~(ON2_gUYxWPXSCHyxa zf&d-}?Xz_<^!_^UGKvTZk3fr5HpP3J0%0I^3w|y9QtJ-vNUFHQA?o8Y*!zBbP%|#} zJHx2<963TY_t>Xgfu6wW|S z>?@Qgf{CO9fh;(DY^g)rmi*&6RrqCPt3sL<C)6#&?K?99PS2EAzksAc~VS-#l|!a*cUe_uU@^~ zilpf<*ph4HkM+$E`G)pTcJ@HJHrB;o%?u6c2sp`W&4jGB=In zDPlBV|M1{0gXwpVh|vK5Ef9!szVdi#VtV2*WB|4b83~DUy|v>|gpn=t(Abz7?2Ain ze7pq2;qv7A%H3B=N-Ar1vP$H%Km|XSUGY5){vBy%t4hwLRbpEX48%^~qGFRa4f_P*Ntq^KH5~*6K21 zx1`q83_U*{GdlmqR>wViha$BAN5V3LpPcGq%^z2^pXjWOh1?vMK&KV}csNF*me$eB zb&-|<+}#im&Ju4J`xNfZ)*TwbNQL9rHg~ zqf&wCEvAvn?8)THZP2IhO;-v_>g6jkU7T(Kb^}aj$F2kZbeCs;;F?(J5?rvN$D`2OXoRT6{>9bUY>6;#T z4j466bCtI7U%oXd6gh1jxEG@@F6tQ!yOHDI*ru^pA8*J{POc7C4)qc6XaPArSCti- zwr>QL8b}>MgHtJAain0T3RIndUreo5H$9)+q z(D;%vFcb?ewGO&um6!KjKQyny4`ZFF(N+p=MK*#$!L;@o&9#Jvq=v^!t?X=LK7L-4 zHCC5PZGkv<38Z_|i6tjX>^5#hBnwkA(Isp7I$=W{m}a0C;HFqVQXtl z$kT9zBnb#OB0>wInJg|s_@D6c@fFNeRN9};LbKoT-<6qv*VJZ!kMnm?-S@kw4wNo@ z3)I69dPMws3|JIV_E^$DvB2Cxy3%N2fR7&pU`??n_yT@7^$r7^2sg&}?pqmW=rkI^ z+@lQ+-YLSJ!JpYVJKY?a#iFP{+L0b3I+(6m=UT@bt5!mWx|0p8w6&e$FOWCXTC<%| zrTw=q%SYl3bbpz8M=-|nXu>igPU85xNSVq`!mk}1NJ4=TJ+S?e3EHiw)*HFtRKrVG ztxuD^=feW;=*Yw4+@Yo18;m6_J;6KNz{^8UC-@%)x>m&MyhNqwR>V}cXYnnOJxS`i~5ZYIm_$ zRhgZq(OIN&!2x#5;Y~DAcCrd$)#>qt!*;(5Y3|tCX~S}JbMqN10%AUP0d>A#7*YYR zaq%(~C6ai}RKM(FP)oS;M(tOjcdrI=bpRF4Etd=@k?EG@U$r%NJ`oaX-=0yC-nZ0oeb>^~8eJdLq z9V_PK<f$-CAb+|fU?BuiBLm6pPsMZ6T3adXzP1I_&1SoPOilh=< z-i;#=w~0?Wo>e3#4-6|<*t}q+uzk6M&S`tbOE1V17Hhqi8DYq5!oW;7Rcb{HdNt0` zcF1^Y)nBOJu#Q(6Utjpgs#KaXGqGidyc?k@W{Z>C;h3qma*aQ@xjLUuzy}^o(rp2s zO(?PY0t0<#$}MucD|N$jSj+Z?kFTQ9?>9!)VPjIrWz^)-CJI-Qkdkpb9wpuOqX7q6 zqz1y4k&%2UQhSs&;VAk19N?z&+0xQaq&TxL(NNz2p#RbFdD5B8j)tmrSLWHXh?r28 zJhftzTNlyT^5^@?Wo2a;T428W9jmTtl`mL@)xyVkkO@TmFeK&*P3hTqC{|DOD=r)~ z0&W8dwY!8ujwya?eSNdm_Ij{ytPS|CWJHWskI_g=OCk9SIp_z+J8o=mxE136NKGX| z|6km_WmuJMyDo}>fd~?U2!hg$bc523gKm^=q+<{kUD6HG&5#^)cXtiCyF2%de&71$ znz80Qj=lDu%^%+v0SDu`<2tYFjQw>2LabNKI1&-`jdM&qgs^m*DUyp5kO-8~@ky8b z!*nIjj8(rVFRsm-$ZK4OoN%{RVP60!2#Zpd6PvO627q$df2pH)CdtqD2Kk zy{-?@+QoWbaF`AC--7}aK7Ky6?>q?tCP7)~?f+;7uG`rMSs?F?fdZ?@W2U!A%|vAU ztuj#@2Z?Jdy@}#tVjNEULrH?7W2&G}4CXxRCMKJUVOfJX3>u$5&Jco$`1O?+@{`El zMzdWTzpKVZdh@x)j>FY;FQ$0dKnW%P1)SE-P;s5t?)}~WRkJNaZ z`VgJ6iY|490wXP9i=v=lg8V=waJpZm44;v`aKhZ4lsdRn`5dcLS>a3Z*X?C5ST5?H zy#O&u8Gk?h*9_RFtdpBZhEro^lE%iKcrHGR4phKL!H;C9aR-gvsm#o5HMQ_X>ODZw)2gic zc(E}NMh6U8Z;#n7|3hVl1fbT%!oUIXAr5Qfl_mjdT7bi8Idxlv!#?Smfr|^&;g=6W zD8qh3GJy$e6&X#qqQc!v7uPC&$z_orUTLI$FrMJ}_^bAX6w-D;;G0P@br9jXpU*T! ziP9}5J5#N%JF4Xh5)p>;P9m}1fzWwMk+fEF3NlcGfy9yWI1p!qe0qU=>RQ?4_wJ|D z0vWB_jW)jC>#j-Cf|&sEM$0D(_|zrtYtSSjSSO*+id$iKiZgK8l=&KMxO?x%r?k z(0B|Dhy`AD-GZbq4YxddqE>k&_5xEXxN2&kdvSU6q(RzXgMuw9;IdzEQpH==x22>f zrCR9FX9Q5={uvF`S$_SiJ^jCk>i*9#5m@YeAp$a|@C0lsIGz_x+kQ|4f>!ADtZ+Kc zBssHI9mex{yzqfSWDI0@yVCr>q1+R-E?Fy4@0kDsy)v!k%TADwOt;N#x;k z238(2T*Fzh(NvBH`yQKj&pJq2q`P+3j&~*^LgL~or+*9i6ojVJX}_f)A^Cn*3!>2$ z00X#yQ5&rqFE-|Qll${R%yTJwwtKs{QS1&l=9_?rr;D@*Y@xt2sr~wzxpA@~TR8R@ zj41R?51*pqvzwk>AJIfdw2-IQzkeUnF4C=*09aTjcgrO-fN$}Q)XPxlNMT8=qlEUc zlV{*dLsM-?di_92Y%0Y}jWwt9M@w)Vfh5>MR*@ERai7O)#>QY=N}Zj}2!WVYuZW%? zMqy%vVsDH<<&CyE-6O+hG|56ujR~Q=d#soCmoaZYF6?)e`W{0)h}KOSxSv{eMW6<1)Hh0u-*vJD6$E6 zl+dM+?Y*KTyir%a1Y%oekAvBsJm3z?!osp|`uf=;QpoD6_+S|Un!Y~B7A1q#cMUL+ zQ^$}~O;tcQL>|m~p%RS2AdQ|QX`O&kYqvJh$p88slWBbwr@g&BnWUPquqfPov|x6L zR<-Kq_DWYggXVbVr|*D!JswulKRBpaZqnT@pFvhcpTMtcVL?B2x)+*(MK04*tq1VO zQfI_i1jEYp-a?rb78WL!VpzCxo?22?63|%ffB!pk&V$%Uc-R|s(y*C@Ck+3B3{s$P zCvw}-o}_RPSag=YqCBp2J0q61-|nYiJ*u28B~B9Kq7PR&c5Mg+eDdN#-Qh_(*D5~k zN?R=^V`D|@?g8YitgJ9m*ZtKRuUJ!12ZPYGSNzsrdI3AQKxx1laXuWvlqPj6aT#6M#V;R#HHvo^MwFWbQKuIP*2C?c=4Y^Ybk}h_!81Iv89t3mS|J z=+g`jDF6*tU{6(f5$NnkLfgT7U!%m@$;ikkgMKQKPOBJt(({}~NhXdXA^C%Z7ZcLi zUt(Nsea=cRWn9WPP>z3F%Ehiu2XQx^duBRAEGuq3OZ=bHUr_nO znvp-{d=eCZNLDu^J5U%_VuwJ}9Anzr8{{Q}7S-B!q|J^Wq;TKc6&$gAMkH=L z_RDSiooxrpUOKoG@0Wkgl+RPkrlv+G;*H4SceuVgmHCtVnd{s9rvfJAOco1=Hig*k%G{qbmnuCoY%NM|p zdwr%+VF3hDfiwkGfw{&?I9Ydkuck`FSn8}HDjMpqwg|f0b>2H&J78;jHP>aN`aG|ED=BT)N6V+a%$qZJEvFxdUDyGJ~|Mj^k!vd=61MtNw9G+L#XA&=sG%b zq^VO##cgiTY*T$cKg5G_SIWe5NhR`?NUaT=5c0$^>XP4k4Rnp*NW|9uAEKSjO+~*I zxET#$W+<<#?f8WB6GPby0^@Dub^I5{gm24cDbgNsaxsO-!NAcvI5L9AYh@xLQc+ka zfqdcntxKvjz$ehx4_XJlAm;XRv)j9TDS9#@skf`i^KMmp_`bO z{njK^-r8LB%4BGUjQLbew=Vsf*S8%XSkJYp8 zj))K04}Ewt{tZy+`et9dy1Js=0D@?bc8!R%big_=5o>1qoDITU2F|nU-<*Dt@?GK{2N{9N_PHY! zuB~>RxKD%|7(>&SPJViwSPTZ-q0E2DYO=b%e5`9|Hh}wECVpbmDch+6x^tZw+=#x3 zpwm1%Y!?)FLLA3KPqqyIK%3hqur=L{Z>!tM^!>SO;~YpNHoj=F1L!N6YNt05#O7;4dxWAOG8OMTrfC3e7^MgTEi{l?`}8HFXYz-& zX8DG}nvg~Z*!sv*htZRe_6J~6Z#2b5PEP*jO#;Tr=2OrYQD9Yg(pz39B_Ss#Wt*C6 z1=6dhE)I3~t=1-uQw8VPv*i(IEqSqB=xbn<35Zpn*W~V)m+p)SvtwZ`?Cw4i7YXZ> zms>u-!o+5FS2zFSidabpS+hyN1==K2hoEDEwNCN2Of1Te-aDB*xbmR4JXJ`MMm;LzR zjqVLPeu|RvgJWYt!m8x}c_Ot>(eC&@(c!v}}zqZZH1X zmYE4QI_cAi5@XkuZQf}8<@B74O6X`{9-@>VdK{N$JX2~O%a-SfPUI2n`&#yvF4wBh zIR5RB^sL)afIRD2x7^?oyuA&ZaUZu?&*w*$b&QYD>7Dzhyn6IU(Uu}%pHdG(kyF}~ zdh2$NXd*L$wl`MS17hBm-~7a=gj={=&Js3P1BsNi>kauy3TVTswATmIZ2N4K~8fbfN@!~SaFSbH*m>3dhMcwe+(x~<2&P+P-J8v{SDOVz)( zbkSG{qx!A?cep_IVkEoE{nR;hJ5h} zRM2IpUa)Mk+GuN9QAs!EWKy`QTt!IwrLewDsMET23>B3P5Z(_0ml%l^nS}+NaRCHc zyrRM|CC0i2+)Y8~{%{!gCaOq4O#wF(q6lt4EvtjlbixN@yhtoL%=_PR`T1 zj~t5UVM8wL{jJbF^}o0`*LzZm3ql9Q88RynsfboFTKtC7Zz4X}Jw7?y`qJ zcUW#Ow92AHb;>EqBdV-iot@9)oDQO4xOyEOJ;@i(bAYC!ro=LFS~T#w6Uhbr&vAPx zL!8t%Gn(<`0mj@Xs`hz4G~mMw3SYT|(7cQ>nBXXbaWdV8vLt`1Go7I>mVDBOGUINP zU@;-%0njJ{gOGy`51SCS6N{;zPRSBziuf$XFJEFx^-^le?wNz`ACLzP4G-^3RbgOa zXXd~xKN=~NR+%d(EFMYXMszjXQT;k~zPWA$D#2)N&zhIG^coee7i_MAfUm;u&_jzG z8F}~XPe9pB?~aAPRnBlgV*K}zRm%S+`2F;?z(j?!Ev#+0S$UXB(=ck%fN}j!oUeg( ztWQYDqJfZb5~%+Hb}gK09I~TBu}DepdRkNdP+j>AmD|R7O8+`$Dj9{F^az+_ePJQd zl|PjFL!#>USl$!RFn;!V5SLOY%=tF<|ak zG5r8;1ZYE1-2h>O#`}cGTFJa{wpxo z3h`=c5rXebZq;pXX-D*x87nA|hQ`ws>B-yJpq(JTURamfi~IOUY0*kVpzfZ8OJ!%7 zMny%n7Z*@jB69U(-O;xsz5PNJDr(%>%??j9(20O&ngsRWzyQ_q;lZ&11-Jc%o9&Gj zwE}GEa<+%=0n#k`UoU)YX-&ZteFPe?9bzx-R?vAmr6y)WDAO7!N{}ckbG13dx96&P%;*`eP2gfCtB|D=sjbggm+QzEw zQWn21E0OU|YLbNlX5{$9IJ@bvXMC0GRtF$lWc;aVe~<$)&=j=pBZ^gIcVhfX=kD2M zG$Ef;OWai@{AiQAt*=dt$#if1$m|UlwF#)P!0?=Cx|)$1^37zGuGVdjhl^THR8*Pr z87UbV7^}H+{3-Q*8M!_{3kdXADgFe;vDB9U6ViLYuw}JsU4qHEPgX-?VrZjH{}<{L z6b*p>Php>aLOy5#gFEy?67V#k=XI`iJU{L5C<!-}${ov?yHW|I!_W`Xj$tcuBBBIn{CJh1j^XXkN?wfrzeX|VZ+A%Dw%%&5`tl_QF z7^0nY2zws)^RoP!>lixjake|xZinw~pVdcHQ-QOz#HCjC=bq74KXT2PYR)o4!*Y~k5JWXrVD$>H6Ab@y4+=jBhf=+P zM~l&ji_3$C)3_BxL-#Dj_A}oTg+<^QNjM}X#6@q0-phm) zYy$hOfiuv}u5md&?54rp<3Tg*UVarFtsVHxT%|-xT-rOc&BDNj8!S-NA}UJP01}2m_t@eDxYJxs=?lj5>}L zMH?E0To-6}$Mn4iqQWA-HEn=3X(%&t0Je-IA(QbkfsKtM^#`@#nvn1L`3V3<87xN{ zv2jrs+Ih*y5>84=izl&9gLWxINeNH{s@2)gpT2Sf5OaxUEF;4&C@?xE8h80n4LEo_ z`BQmNVsnqkREtPoxi*vRY4Ew1-u#>kv#fGF#!iIAkzwi^x^oLGekkE;hT5&Ory>Or zGm7vO_afG1N{W6ocsW=~#;mQbKgDOh2BT;Q1_q#Itgo&o@VP0RivtHi;Aatib5A%M zdjlMdprN!69P1Stm6bj*!;iyhTAN$sE~%!pq!q*CY0QD302`A*yVj#4{8dhQjk_oV zE7_UkL)|2?!~X6(lcSg*qDg!v6WZpqR&=5lJUad`_~?4`!3Mj@`cZphSA&GSWM@}H zL+=G}+TU%xT@JUMz0!OOou1vIH}AjVE79Y>H6sPqNW#LZQAbm%DgRT5YbFt@RsLB< zUET1oDGLv8EzBVIqc&uhbz%Yl|HKh9qkHsx_c6v(MGC(*23-=Ipt?oUfi?Mh@E|2xvFsp0boOCZu*VbD%V zPZxQb?OGj}DIf3r^d-AGTxai0zLlze?0<)|o9H`J>G<*-Oe@}UZ{F~2*H~DdBxb)pm)tYZt$XPl4rx%W< zi*c!axps*2fSBLmbcoW7i&yxg!0ofr)e*QPQTXOiwE{)YWx+qhvUE|L0j&#k>XpXZ z{_WVEx65tssuJLyWYw1Rba0w$b6KXBz498&cFowrAGKTS_e-zhcjqfJY^_U5S(b{e zqi<~+(`y=gd|_|#+(!tU)0X`e=2B8p0s=hUC}^nv0KMo>liI^lQ=?YJ+Mi^uX~3b0 zZfDh1k}EQ}E=fIr47|FA51>evsS)XlhPd$gd16|wIjv-Pg~NeoR&?{i#mT<9H{!y< z)>5-HuF$s-sC31vKTzsp2=3IdNAuLLI<{ff#MY58_4=j^!!WuE-LB-nl!| zKQ6LmoQTJdAA?{ETSTdw9RR>j10=w{6p@tVraLnI5P3VQGwyg-DBllaFba#KjO@D- z{t1WkF8?DOCOYa^I@=Sx02%9fNm=4=h^oJ&rr!4@gdV?Y!@kS=W4ol-789%Ks}V?h z$dw3Zq=g8Gibgi*YQtoK4-7W1+})xt9=qX+6-V13=`u1W)|!)`eYZTfaH$hC5jE>; z0J$WArn1Xs?N{ws%SCy*5<)=@P-W7cN+r91X8jz4(caF;Sl#VSz&aSoI zqxJCE&fj@b{;uPb+P(QXUi5IaC&M%mRDQp5W4{4d7 zbefU-b$d`#?eRffs+{L&k&8#^<4>+HvjC$5tmQNW`b$QGo1Q$Wp2s;-Jz3f9?c!kc zq+RW()G^__nY#8VDT#3g-NE*-ZW;(Gft6u=bgi+|U&i<-^gm0Up(VnMz8L$mvE(Oxx9vy%^O# z$Yr+?9rg3`!8#chbCGx7TVMPYTCMz?3|YFIQCl4%V$SD9|3Z^~Fg|KdQH7WKs=)Zn zbjTX*@wv4zNSTu@Kt9$xTI9ik{NSfbZcZekYMWS-#0 zYi4?1^?{$km6^Rs)a1)xUiU#x?(s^xz5%EcsOosnx9pZ-%4YEVd7r<=!ODeb*MxtZ zBS1>cJ1t-!9Q-G><+S}7NHW6q2dn4L2jw#+fDk)<2AG*_=$Dk=CW*C4N`;M*e}5d3 zXgEu*=N+;XXZuwIu;U4QQs;2)87qDaslwY-9T=fWQx!AnQhLx zQLF+fv2dG9!rTKX*;zCM2a{*nOgbiibTrTg#^vlJU`|9CN@s80g`{YBlp^LxhJY=?lW$l$_6lA znVV8yd(bEvWaD(bxjZZhu3#b-oi1Mwo2>orjYv_n?P0*LoG5ZQnRaE*RqJ8Xs`(fQ z3;IVwkUN%bw?}f8*5KM%s3_iTQkOA(Z$e+{;Us2DOZqYnpd_U3PpPv@L{R5tz!Jlv zPW!j+4U{mzu7w=nf901b7$*!0+Ht0}wz@%T&OGI(#jm zLxjv9R9EBW8u@aAO6F6VGvX7n|DI5n2$5Hh{n|iPx*?&N`nDYa@4w!G0RM@LgC<8% z1}O|Lv3JFKk-;}7J2#znxdOs#cc4~SZDdtwOx#`lbX4rq&OVvD~|;6UHd$4&xzWl>RfCgN}Lo6{NE64v`Y zS5VRbDwMQ;h5NX=^(MqcMFH=+cS+A1hnuCv7YsXUi{JTv$Rx!Cof<%nTW&KJh)szoXNOr(9wTd?;mwEzB74o$@ z*CyL_6;6qu4tEHL3r?&qH(NBt!~`%kzEwi4;Iki6n|+~ua=)76!`}VIp+xhLJc=kS zyKkP7N+L;%-TAjG_@8L1F{r2j%1)%#Lw*$t1%~25Ul%SS&^aCR>`Cq=@(@dU`DCL&B5$ zs5|1_rz@(Pq4D>TDDNjHil`vQtf(Nrem_1kj&8C|Bco^%<`4ae4;3}6Bo=1H#YW!EmnWm} z2}(>5_7wkuCQ5-zoeb75tSK?|QV|8ogJAS;)Yj_r_kV)6ektF-bq+xKqJ{Ct#v94G z*#I=^-px=e0rrtmri7Uz`E`pgdxxXs2$U z@cAo(S0`H&PD=yGkK4Zbf^k|Ojg8I02|t1Bd1R<0ZdZ3#*CzAF-}h%{sOZ_2$L78h zdl+n>KSjIL$&nS}xX>k$RS>#UWrdeKhJm3m`@7gb?69fqvNdyorO^HCgT# zLlzb`rF7~6xhEWI2HDh9tYXw+BI#;(cdboEO`qXly3BP^_4C;q-3*Nr#YRU{P*8x^ zZ0=TTr8#h!l5hEorEjbD^KtS0MZec5vjNN@Qh8mICV0lPo-e&JrOGrsDu`&-&v$8TvN=Su) z%jofQ@c#c&?oB54<`6DbWJovG6oG^|+ME~cxf;}W z&UB3bxKh4@Jpu~}d{h(vO%Xiw{ew2abN+TaJOyiPj1{*I9~ak|n~EGP=@uos=lxV? zLGAw15)ffAWXQ`@vGojOR3pMu?l z^kEe&$0{r1Y?VF5*|(B8Y!608ZvS35Itn`+B_turLxRN|>bJ zJ?>K0A`)t351VBnfw(;LxgRREu;6@TtFKG0VN^ z15p`i%5PfWJ7cQnGr$H~zRIm!bGlKt-%v7jbnZJw3J>(8`{)gf^B{s=JL@WDnKj4q z<_>V*vzRPaT`SZtX*@sNu>^LW7Xb_8QYL#^IT}Hn<}Ff!g5Bhi68FAK*C6}@{0pC+ z+OAnoQFI?GHq}G8t@|znp(h&|)s_8*MR|GVJ%-rv`&EEkQ?0)-Vr|H%JZje1bhu8) zLt*vPWZ3j@f0G%QdmT;3oNO_Pr80XV*$R2& z(*^T}xDJR?O9qP#R--g~vBeQ2}=Pfbnr zf5ArjW=PYaaH5!H-GD4^`%?^P zh5c5IwefcU==Aibn9)s-gB1fko*Dkjk-V81)8X^cL|FrT)g1e+WSO3|wU`Y}{mfwy zAETJ9SZRNhz5QYjN-zWqGV%^W<$J-T0-viMA00d0;aGuW&0oWg+suRKoANk5_C$`B zK+*3BHoj7K_2c4D_%tug;nMVI=V(K?(gavSr!QZ*9A4UhnvUNL2 zZOsO!@MG3X4RsR`5ENfkLv3%a5i9rj2sk??8;D`p)ce^MdYZKcN3hyU+LtSUOI@O) znm-ewJXKZYsbX<%-_?dqj2 zvKQ(&7<-Gd{Jx&{*2OzNf$OK3lY7{#!&%|?loZN1Us|py(}+^{`LL{cNfx0YYzQYG z{Wj#?7a;yl^;u1;nJgC^2(y`@*D8Dck0;?=0-d>IW78cXiNRlbYJ{`8J##S}EuS%D zB3&fW(h8bC+NFWcWLYmz{$}7~={psWcm{%o0`Pg|;PQI+FnTZP zeTt!4@LGxRY`cxoL`FN`u!nmnCBdxtkY;HKDa>Fw1+|l{DY^+Qo8@?p;}c_OCvJHC0CrQJM5Sk1FBYWeGFqS~toxGx?k6uUz3fj)$vrVUHKmZoWEt zp%OAFu-Lm6$akpC(zPzQK17$~B6{~|#`QqjNGy{w`FJy1wUn;mGB8g)meun5aBXlw zn`pS_OLcX%cRC;zwxp9w$FT6aZ5kn?2lYnKMLxXG=fq?+DT?{Q`?f~=qV;rrRCF=G z=?RWMeo7V#o8>eQHL-w9k^ndi{jjaVt{;Ms5P%J>5#3Xol|Ks2%J<8>4*u zDX=Q9)?B9pVMp&_)t3|5c8CHja-*G6M_70%aW-8_I}YuoZO)DXWXIS0k#@C3W3f1v zrl#iAy~~-B1bYM{jlUmZwqv<3v+ zF+Sn$s`T{q4?I2h508mBemfty*}LXUU55=yYJ*zQL6}vmYea}4?PM# zIEX0#cUoLr++t~41ejDRYjtg@fuYZt%Yri_^ZW^!PR1!n$!c8&&o^~* z*y6H9efk(8=G!GD?K(ErvJX;3pO@3 zKLTldQ!$DoN+WV35n_@Nu+!PAdSanlk>|~IwNyNE8XzIAj&~mPeZAV^wzsvmKi-=L z|0XrR?S96MGfX>j%TA^{comIsjNN|nho0iT!%V`nB^aX;e2ISbEiEm?Ux4GrN)Q5W!y8j2Fa|Axg(>R1;4aq@$@)X1B5c00BWJ6ha8l1k^nxz_?oZb~> z6$$+AO3-Hz^vSE?Yb1B+CX}aWT9@N;<+U0fC?JicAI)?q)z|}tFnLa?s*FSC^M?=c z1YVMcM)&ibpyXMg2zg`NGx4h21~CHI1==zRsOV2j$1;6F{W`%-uo$ym01NWARIN2A zF>u}(dOn!*fjXAWl$;^#xs_{O-TQHz7m+l|`Hp+@CMC{Inf)}8bm7*6Ns@-p3*zJ& z6N^s;wr3qTmn)~u2PQQ1*?q(C@>Vduy*<U7w4;0LHy(Jlbi{=4NB6b?-vXuTR6KGBmh2Scpuefv#@o$ zOL+$C>7|CC=;$qfobRW+VT`~ru(}?_#0)(kig=0t=8mH)Dk|y)+KawoV`fPj8hq}` z9A$c#Mv+XGg6|6|^k>cOQ`&A>m3NPC-muUr45e_{uCv%oD3q@>oD~6fmC;C*aLGF8 zk!X_4cf|8sbmFm+2_Kz#J{_mm3*i^W>3@X&l$o8~!PXWVLQ2fj(B7=-5LHy`eCa20j{gzYMNMQcs_Jf;+|Oe%u8NmD6hNA7dW1*ySkG zUD~#<4Q6z8(ShuA;gts2O$xXpTzNL*J}N6!pMM|P0{zN z1Is6Y#)ecLP!QPeY)>U~#YBZ=YO1(hPpU#nj>BE39Tf;TKL3ubgbE1>RocG-=3N=m z2}b6+gO!%GQYFsI*VUMRaPXyk6Ee0-MVL=frF8cLWHd=XRu-DMn41^Oy83-V>I*u_ zWJu1W*Lv{6;@b$<**Ai0?lq8Y>|r`cbQq$XKDH~7@*SPVVb)}g(?La<>*ea)?5D0OP5_ z?d{g&(ujDu0irGpzkd&5Gs@|f4=;*A`;&z5;0g&Ij zh0vmq9v_>SuD)=1y$R$|4z!-mQ-Ki!1>-DZ z5|N-9`z;esH9EHn%ruFunaT|P&J&j^cJJ}dBYkh|Y;!*o;P$49;YCc`wQ^J#$)Jfz zgv)N-6=k#1vrect*Lonl07~`<9Gv7-m(#vGz0I_%J|r1 zRq&M{&6Ym1aCwPPJ0>t$3J!*VF8h8nwXo)4rDYAqQ!qxe+8xmE=!vfV*go%Jy~*Qv zsIo&iWgE1-;$YnN>khH59uxwh@-a6lL4IpT#PhWyTAa_|;1_enebBYeP`1 zjc%^voLbG zK_Por)Au>nQ;Zwy1XmLSljG~YO~0?<3|d~y%KLcb_a30T#n?3~Q<;(wZ>13Vzj&Vb zEOKjrR%v7esG`vcCkKyNj7Mx2&X05^$htih8Q*_>PkapGTA>sE(aFSlEPYj|kh1Aw zE8Tn|`(pE%8k6C5!f`SV`*@%gbRnAp`G<8aZ(}3UuGB$EGA#b!-+*xuVywpk+M;DgW z&L__cOs*-O1V~E(svOWr3r%*mS#2kd^nGd+Y!nE3#aZY)b#A3A;@5b5xLI@>8l+xo zqFJa%1>p$yidI+gR-4JqO$Ff$6igYgUh;5>66^7h;FMPHo}r;3C!4C&NSqg^sQ`f^ zKj@$R^$~(*elveQurYdrwlbgQtB&F5i$kaOQFv&qug|oH2U7Z+N?~ywv;(dV7tqZo zN?@~)y=~BYl$R;`wQ4#=%tncZHGH7wY)U$9}WTJjmvKPLVDC|v6+(s0M4y{uJ zUWiqxd!iC;SI_P6<}|gEft`#+rUazaxXSQ~qxIn|b%!HgkZ)gZv9L04T^T*-OIXb$!?aEj30NxqIyd9)>C-Xo z@npqsY+Mrg%w#kYc~nYUW)G8W^A*AI<~fsQ{PCH=%vf2OQ&CkzgMfRblTAzRIA5aW zVWq7&YG>C(toUNSs?AF042QKpxiNgFPyBMe3AGJ>SAqe~q6`hpjPUd89L%JIsQLT2 zktdeWSjS)ZF)9wI#?W|6?2kc6Y>5=bd|x5p;;P6hXY!slhP~JfssbGqn;Bu>k0p2} za_O~)L>FZ-goHur^Ypwc<&Dhn8fesOHq&z!ZuQD=(^21<>%hF4EUK)1 z+3X&!lIN5Px4Y>b>;XF7L`vieoZ^}UxW=sZC*8X!_EWexCVG})qu6UEL^xJp3it33 z{!&|eipe{TKVnKm2izgPiv$?-#$Y_hqe7AHp>JO9(f(P~LOH(#x(vk*K?MA7EK-t_ zMbLP3;738?|li->1x5Q8MwB#YW@SBmQf0(?XY6;|z&+ zDwN~JrKKxv*XAb_85D$?i%7Gsr<1yyn)DhgN@}O77*BM&Y2(k2aLaFc`7NL@ZBvUq zmlJZ~k!dNnNQO?tz_Q8a>ErF~W*|&18vf|vb$y-8%)#NU$AL!>8NP}S7Qyh zbNJ+OrHe7BYu&H2RDEfwb7&$No?EKzJqE(iEuaBc$yH%gEL<0#)uq}f3jg)%7bpov z^0c+F6PK1|PPQkF2lJ;Iz3w2`EOErSd3emu7u(}2?XaT9TM-vmbB$pr_ofDDK8R78 zu$aBVBc#4_BQ|1xEMgF0MsW}V8s1G?mAsndJ=?;FWBSi36DiM_p=>nH@hFXz8?2av z;Sq7qaId89Y6XUdg0KMygF6*&l`%Pa`uqX%wIhXh^oB5zKylWZq5(CrP(X@VniA*@1_~wlg8yhD0_UQ-TD8IOecA=JV zG0Hf<8X~8C3^)aj+^5{YzUOvg^Y7k2B?lfj<4F9{A7HqC7_FDv?LM)@$$3v9Q=@_g%PLS^e}Fyoc}J zyaOZIEY%E)1p~U3?zr3!l(_VoN0hVmmhAZ(Xl3@pmM6Ff+Pqv~D7(u1v2S8Ya(^8= zf;I|&_U0X!rXhWZ`ptq1OP8sBfZH1{4oS-l31!gcpx9pLdr5?Q(wa9TL;^T_Bi$SJ z$7oJ=x8Ffooawz2MGI#7PacR1y;qnY9-BbiI9-%Z20lWk(<-#hZw!<8KJtod=K4zH zIzH5}r@KvIrrZ^JlfaP38_;p|A!1|%Qwz=JNFpj8#D8pW}T=OM2e09X?WJeU>e9K6QjaBKI zUdI!A_#(bsoE*EA+wA$WI`MM5cir+{c3ym=L}9aR!8X5GUy{^xKIS@WbV%0BaQmL} z@YvTgFE3sfl5ugeO&R_m0p!cas&5`1^}9*t$G4D^N3Z)AAF_DJjsF%O^fFVuouXmC zybr00F;%9ojHG0A*uyMQbG`CStkSn=rdCAQZ5Dn!J_M+&#CS&h@ZU_yxkhDx@iwxg zlCOZNhDKK++`@8C3yes?Ga&fqOdR|V*ir`s@fu|=V3c`#=>Lbk+U>gwV0sMdE5?@b zW-?}ZF8kHG?hWOlr>g^lMN09`5^3)bi!v9y&>x)gQ)=eBCY3KVJ8|jC0IT4zhw5_$0f8Ud%i~Yuprae$e{Hka$KD#mq>##G3%6FO895x-^9?1z3c;n&mV{`XNT$*ZV5Ec<8U?uJj5Dadm&UA8Ht3qCQ*kno$eJv8i_2rr8m`;2UY3hO)bx<)D&!)G@Ya) zbA@wCvlnZ*qw}lMX-1^Yno`A6T0v23L z>AZ;}x3e|Te#gtVuSrQW4dN>*f($y~(b1}KIR%AOBX9mqf$!giNoYwq>TcWs+>uKP zzOfz7R75m2Ep~3HCnxerOUhy$kT7aG$wq$EZc1{>8Sy&V=|6s}DMvUMzR~sPPsI$a z?*OeeUwR*Bh2G?;W+W(-{do}(jAnIRT|@krn51xUmk|*7uJfJu-PBiCIz;AbF-!n^ zK^h!}KG&fdv0y;S-5DzsuQ4^#*{t63YdSrpaf=Mxo}mbdI_zn8ukhvKZWZE>yl}YdHsSy(rDw{-m zj7BfF=+UM6=+EoI5ZXJ|Gw48;eX{`bjQFk#;pV;&J}?j#7AiIwbz5!gH;rTnCSqcT zN3rN02hF(CB*vskNW`$}yO>FtmBg?@kJn%_%0$yQ;fLGp4i(rT4a3!^=Zc*|KIv9P zI3z7Hr+UYzXK&JJR&1+B)2C9tAl*P6wtV#%q!=|hGbAI-4Xn5HD)dmcQt(W~llqQv z2iEQ)y=K1;S(VLV(iaVkfBh2BJ#D;p$oEzv^YSzgiwu)nTUw5Lh~TylM=ggIRTYLp zMPruCBN^f>N3;AUEzR_JEIJN%WC$uhFBeayDCI1DpDc53o|vf6N+BQMo(oT>IUfgA zy*D?UH6FJoevNzA)k6*htJd3!mrE;ma~<(eD_S6uLS053Mr$|+DMWvGFlowJ43aG! z@5sy(=}zCg@WW+z12^CD6A~8b*lJ+b1aoTCZ&b4rS z9H4$x>o0Kit9Es3D&PZ6`kz6MsfE7zD{$TzN;aM z8%vrte>MgTYz*so(14EwyVK6v9u0K)rjv&Qa@^$J!~#l#mS?g^<4Eva66P<5c}p0& zNPvy4bw^j%kk;K#ZC)ut;U7-|^OAqDJ5Q#9001Kb-yhOx64yf3 z9zg!>xx&dXBll;U#({J2AIIMn#`~~8&W!-M{0ExFe>ful59|iVjG1b&e zD|1HkcLrhZrJz?Bpf*0yU z9p(!>VGZyH-TQuNyPuJ<(v{Su@H(GTl5zO}VEnx|@W4oHdHi}d`OW>q$yvd zl()`m>dNB$BPSLLhUA63F<@R}WR!{sjX1y5gJ6itmzdjmCeS*w?$5j&Xt)c{}kNv-`rT_1JK^O>j5)dZweM?4|^6FoHVi-iBI(ZOgb01(! z_`oJ1DXl&A)Q=q!p4GA!KTJ@+wyg{ltH4DJ4O@F-D?SMC%uUEj)Xlv1GVR#$V-~x` z{QbR!OM^fSTwua+yyEosjck+L-SdC4>lZzD3^{dbQQ^jmj}i?vOif*Zkp}F&)F)@A z0*{uI`J|!{oIX9Kb?xHpZH3p&zNJkI^J;Ypald@2b<3F^9*Bue8dJQSot2fH&-QZ6 z@8m4}xbfo6<4<@NHC;Mz;mVaWSMD4F?&TNp;N{tI0lX}0K|&VrR`pdA7I}GvsH&%@ zEO{<7xf(R71hkmbXqx29i+t5)z4*}Q$iB}?Y@Jd literal 0 HcmV?d00001 diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg b/scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg new file mode 100644 index 0000000000000000000000000000000000000000..23a691750086af80675efcc58bdca99e794b85d6 GIT binary patch literal 131978 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

    =fAf9bDIZcvi|G5|2$asO>)l+ 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≪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 t8Y|xGCrI#p+;1M None: + """Save the resolved configuration and collect one group of measured episodes.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("mode", choices=("reference", "scene_first", "robot_first")) + parser.add_argument("--output", type=Path, required=True, help="Result root") + parser.add_argument("--seed", type=int, default=7) + args = parser.parse_args() + + config = yaml.safe_load((HERE / "expansion.yaml").read_text()) + sampling = config["scene_sampling"] + if args.mode == "reference": + config["engine"]["episodes_per_operator"] = 1 + config["trajectory"]["operators"] = ["object_pose"] + config["trajectory"].pop("affordance", None) + sampling.update(strategy="scene_first", max_rollouts=1) + for ranges in config["scene"].values(): + ranges.update(translation_m=[[0, 0], [0, 0], [0, 0]], yaw_rad=[0, 0]) + bounds = sampling["layout"]["policy"]["group_xy_offset_bounds_m"] + for uid in bounds: + bounds[uid] = [[0, 0], [0, 0]] + else: + sampling["strategy"] = args.mode + + directory = args.output.resolve() / args.mode + if directory.exists(): + parser.error(f"{directory} already exists. Choose a fresh output directory.") + directory.mkdir(parents=True) + snapshot = directory / "expansion.yaml" + snapshot.write_text(yaml.safe_dump(config, sort_keys=False)) + result = run_task_program_expansion( + TASK, snapshot, directory / "collection", seed=args.seed + ) + for name, group in result["operators"].items(): + print(f"{args.mode}/{name}: {group['committed_episodes']} confirmed") + if not result["complete"]: + raise SystemExit( + f"Collection quota incomplete. See {directory / 'collection'}." + ) + + +if __name__ == "__main__": + main() diff --git a/scripts/tutorials/expansion/ur5_pick_place/expansion.yaml b/scripts/tutorials/expansion/ur5_pick_place/expansion.yaml new file mode 100644 index 0000000000..2bbfd6642c --- /dev/null +++ b/scripts/tutorials/expansion/ur5_pick_place/expansion.yaml @@ -0,0 +1,122 @@ +schema_version: 1 +engine: + episodes_per_operator: 4 + max_attempts: 32 + max_steps: 2400 + max_wall_time_s: 240 + settling_steps: 30 + capture_media: false + collision_backend: newton + collision_device: cpu + +scene: + cube: &xy_range + translation_m: [[-0.06, 0.06], [-0.06, 0.06], [0, 0]] + yaw_rad: [0, 0] + goal: *xy_range + +trajectory: + operators: [object_pose, affordance] + affordance: + branches: 3 + call_indices: [0] # Pick the cube; the second call places it. + action_options: + pick: + fixed_object_to_eef: null # Use the gripper's antipodal candidate generator. + grasp_generators: + eef: + approach_deviation_angle: 0.12 # radians + max_candidates: 64 + joint_offset_scale: 0.005 + via_count: 1 + max_proposals: 64 + minimum_joint_delta: 0.002 + velocity_limit: 0.5 + acceleration_limit: 0.5 + nullspace_task_rows: [0, 1, 2, 3, 4, 5] + nullspace_translation_tolerance_m: 0.001 + nullspace_rotation_tolerance_rad: 0.01 + free_phases: {place: [retract]} + +validation: + initial_checks: + - {kind: support_bounds, entity: cube, lower: [-1, -0.4, -0.003], upper: [-0.2, 0.7, 0.05]} + final_checks: + - &placed + kind: pose_relative + entity: cube + other: goal + position_tolerance: [0.02, 0.02, 0.01] + position_offset: [0, 0, 0.12] + yaw_tolerance_rad: 0.17453292519943295 + yaw_period_rad: 3.141592653589793 + tilt_tolerance_rad: 0.17453292519943295 + - &released {kind: joint_range, joint: gripper_finger1_joint_1, lower: -0.001, upper: 0.005} + - &stable {kind: speed_below, entity: cube, linear_m_s: 0.03, angular_rad_s: 0.2} + - {kind: transport_guard, entity: cube, other: goal, lift_height_m: 0.05, minimum_transit_height_m: 0.025, goal_tolerance_m: 0.03} + events: + - event_id: lift + conditions: [{kind: lifted, entity: cube, height_m: 0.05}] + - event_id: placed_and_released + conditions: [*placed, *released, *stable] + consecutive_steps: 3 + allowed_contacts: &contacts + - [cube, default_plane] + - [cube, support_surface] + - [cube, UR5/gripper_finger1_link_1] + - [cube, UR5/gripper_finger2_link_1] + mounting_contacts: [['@root', default_plane], ['@root', support_surface]] + +scene_sampling: + strategy: scene_first + workspace_source: joint_uniform_fk + control_part: arm + sample_count: 16384 + robot_anchors: [{phase_id: grasp, control_part: arm}] + uniform_fraction: 0.25 + max_candidates: 32 + max_rollouts: 12 + max_ik_calls: 16384 + max_planning_calls: 2048 + targets: {} + layout: + support_uid: support_surface + parent_by_uid: {cube: support_surface} + policy: + group_targets: [cube] + batch_size: 1 + collision_margin_m: 0.02 + group_xy_offset_bounds_m: {cube: [[-0.06, -0.06], [0.06, 0.06]]} + task_mode: + mode_id: runtime + phases: + - phase_id: approach + dependencies: [] + targets: + - &above_cube + control_part: arm + frame_uid: cube + pose: [[1, 0, 0, 0], [0, -1, 0, 0], [0, 0, -1, 0.1], [0, 0, 0, 1]] + allowed_contacts: *contacts + - phase_id: grasp + dependencies: [approach] + targets: + - control_part: arm + frame_uid: cube + pose: &grasp_pose [[1, 0, 0, 0], [0, -1, 0, 0], [0, 0, -1, 0], [0, 0, 0, 1]] + allowed_contacts: *contacts + - phase_id: lift + dependencies: [grasp] + targets: [*above_cube] + allowed_contacts: *contacts + held_objects: &held [{entity_uid: cube, control_part: arm, tcp_from_object: *grasp_pose}] + - phase_id: place + dependencies: [lift] + targets: + - control_part: arm + frame_uid: goal + pose: [[1, 0, 0, 0], [0, -1, 0, 0], [0, 0, -1, 0.12], [0, 0, 0, 1]] + allowed_contacts: *contacts + held_objects: *held + +scheduling: {policy: fifo, pool_size: 1, exploration_fraction: 0.25} diff --git a/setup.py b/setup.py index fde2fea84d..e0d5e89dea 100644 --- a/setup.py +++ b/setup.py @@ -153,7 +153,12 @@ def get_package_data() -> dict[str, list[str]]: ] return { "embodichain": ["VERSION"], - "embodichain.lab.expansion": ["_preview.html", "_distribution.html"], + "embodichain.lab.expansion": [ + "_preview.html", + "_preview_charts.js", + "_preview_heatmap.js", + "_distribution.html", + ], "embodichain.data": ["default_materials.json"], "embodichain.compute.kinematics._warp": [ "ssik_LICENSE.txt", diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 1c9054d10a..ebe6a40c4a 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -38,6 +38,11 @@ ) from embodichain.lab.expansion.persistence import ArtifactEpisodeSink from embodichain.lab.expansion._preview_data import load_preview, PreviewState +from embodichain.lab.expansion._preview_deviations import ( + deviation_curves, + recorded_coordinates, +) +from embodichain.lab.expansion._preview_heatmap import object_heatmaps from embodichain.lab.expansion._preview_render import prepare_geometry from embodichain.lab.expansion._preview_server import PreviewTransport @@ -164,6 +169,12 @@ def test_result_loading_binds_grasp_row_and_fk_without_writing_results(recorded_ } data = load_preview([path]) clip = data.clips[0] + state = PreviewState(data) + assert data.solid_clip is clip and state.snapshot()["total"] == 0 + state.apply({"playing": True, "progress": 1}) + assert state.snapshot()["source_frame"] == 2 and state.values["playing"] + with pytest.raises(ValueError, match="toggle_ghost"): + state.apply({"toggle_ghost": 0}) assert ( clip.affordance == "1" and clip.candidate_ids == ("31",) and clip.variant == "1" ) @@ -197,6 +208,148 @@ def test_result_loader_rejects_incomplete_scene_and_budget(recorded_job, tmp_pat load_preview([path]) +def test_curves_use_calibrated_tcp_and_per_episode_joint_maxima(recorded_job): + from scipy.spatial.transform import Rotation + from xml.etree import ElementTree as ET + + path, _, _ = recorded_job + data = load_preview([path]) + sample = data.clips[0] + offset = np.eye(4) + offset[0, 3] = 1 + robot = { + "solver_cfg": {"wrist": {"end_link_name": "tool"}}, + "control_parts": {"wrist": ["a|b"]}, + "gripper_bindings": { + "other": { + "declaration": {"motion_part": "other_arm"}, + "root_link": "other_tool", + }, + "hand": { + "declaration": {"motion_part": "wrist"}, + "root_link": "hand_root", + "defaults": {"default_root_from_tcp": offset.tolist()}, + }, + }, + } + model = ET.fromstring( + '' + ) + data.arm_joint_groups, tcp_frame = recorded_coordinates(robot, "tool", model) + assert data.arm_joint_groups == {"deg": ["a", "b"]} + + def clip(times, yaw_deg, joint_names, qpos_deg): + transforms = np.tile(np.eye(4), (len(times), 1, 1)) + transforms[:, :3, :3] = Rotation.from_euler( + "z", np.asarray(yaw_deg)[:, None], degrees=True + ).as_matrix() + measured = replace( + sample.measured, + timestamps=np.array(times), + joint_names=joint_names, + qpos=np.deg2rad(qpos_deg), + root_poses=np.tile([0, 0, 0, 0, 0, 0, 1], (len(times), 1)), + object_poses={}, + ) + return replace( + sample, measured=measured, links=transforms[:, None], tcp_frame=tcp_frame + ) + + data.reference = clip( + [0, 1, 2, 3], [170] * 4, ("a", "b", "finger"), np.zeros((4, 3)) + ) + data.clips = [ + clip([0, 2], [170, -100], ("finger", "b", "a"), [[180, 0, 0], [180, 0, 60]]), + clip([0, 1], [170, 80], ("a", "finger", "b"), [[0, 180, 0], [0, 180, -60]]), + clip([0, 1], [170, -160], ("a", "b", "finger"), [[0, 0, 180], [-36, 0, 180]]), + ] + report = deviation_curves(data, ["hand_root"]) + assert report["time_s"] == [0, 1, 2, 3] and report["count"] == [3, 3, 1, 0] + means = report["mean"] + # At 1 s the three rotations are 45, 90 and 30 degrees. The first + # position is interpolated halfway along the 90-degree TCP chord. + chord_mm = 1000 * np.sqrt(2) + short_chord_mm = 2000 * np.sin(np.deg2rad(15)) + mean_mm = (0.5 * chord_mm + chord_mm + short_chord_mm) / 3 + expected = { + "translation_mm": ( + [0, short_chord_mm, chord_mm], + [0, mean_mm, chord_mm], + [0, chord_mm, chord_mm], + ), + "rotation_deg": ([0, 30, 90], [0, 55, 90], [0, 90, 90]), + # Per-episode worst joint deviations at 1 s are 30, 60 and 36 degrees. + "qpos_deg": ([0, 30, 60], [0, 42, 60], [0, 60, 60]), + } + for key, (low, mean, high) in expected.items(): + band = report["range"][key] + np.testing.assert_allclose(band["min"][:3], low, atol=1e-9) + np.testing.assert_allclose(means[key][:3], mean, atol=1e-9) + np.testing.assert_allclose(band["max"][:3], high, atol=1e-9) + assert ( + band["min"][-1] is None + and means[key][-1] is None + and band["max"][-1] is None + ) + fallback = replace(data, clips=[data.reference, *data.clips], reference=None) + implicit = deviation_curves(fallback, ["hand_root"]) + assert implicit["mean"] == means and implicit["range"] == report["range"] + # Older jobs may lack TCP calibration while retaining valid arm measurements. + data.clips[0].tcp_frame = None + no_tcp = deviation_curves(data, ["hand_root"]) + assert no_tcp["mean"] == {"qpos_deg": means["qpos_deg"]} + assert no_tcp["range"] == {"qpos_deg": report["range"]["qpos_deg"]} + + +def test_heatmaps_count_each_recording_once_per_object_cell_and_phase(recorded_job): + path, _, _ = recorded_job + data = load_preview([path]) + sample = data.solid_clip + anchor = sample.measured.object_poses["box"] + + def clip(positions): + poses = anchor.copy() + poses[:, :2] = positions + measured = replace( + sample.measured, object_poses={"box": poses, "anchor": anchor} + ) + return replace(sample, measured=measured) + + a, b, c, detour = (-0.25, 0.5), (0.125, -0.375), (0.75, 0.25), (0.375, 0.875) + data.reference = clip([b, detour, a]) + data.clips = [clip([a, a, c]), clip([a, b, b])] + data.object_specs = {"anchor": {"body_type": "static"}} + report = object_heatmaps(data) + assert report["episodes"] == 3 and report["explicit_reference"] + box, still = report["objects"] + assert [box["uid"], still["uid"]] == ["box", "anchor"] + + for phase, hits in { + "all": {a: 3, b: 2, c: 1, detour: 1}, + "start": {a: 2, b: 1}, + "end": {a: 1, b: 1, c: 1}, + }.items(): + view = box["views"][phase] + expected = np.zeros_like(view["counts"]) + for (x, y), count in hits.items(): + row = np.searchsorted(box["y_edges_m"], y, side="right") - 1 + col = np.searchsorted(box["x_edges_m"], x, side="right") - 1 + expected[row, col] = count + np.testing.assert_array_equal(view["counts"], expected) + points = np.array(list(hits)) + np.testing.assert_allclose( + view["bounds_m"], [points.min(axis=0), points.max(axis=0)] + ) + # The fixed body's single cell includes all three recordings. + fixed_counts = np.array(still["views"][phase]["counts"]) + assert fixed_counts.max() == 3 and fixed_counts.sum() == 3 + + implicit = object_heatmaps( + replace(data, clips=[data.reference, *data.clips], reference=None) + ) + assert implicit == {**report, "explicit_reference": False} + + def test_result_loader_keeps_real_mesh_spec_and_native_operator_labels( recorded_job, tmp_path ): @@ -226,21 +379,35 @@ def test_result_loader_keeps_real_mesh_spec_and_native_operator_labels( assert result["affordance"] == "unrecorded" -def test_filter_empty_intersection_and_phase_alignment(recorded_job): +def test_independent_ghosts_keep_reference_playing_across_filters(recorded_job): path, _, _ = recorded_job data = load_preview([path]) first = data.clips[0] + data.reference = replace(first, measured=replace(first.measured, name="original")) data.clips = [ replace(first, space="A", affordance="0", variant="0"), replace(first, space="B", affordance="1", variant="1"), ] state = PreviewState(data) + assert state.snapshot()["visible_ghosts"] == [] + state.apply({"toggle_ghost": 0}) + state.apply({"toggle_ghost": 1}) + assert state.visible_ghosts() == [0, 1] + state.apply({"toggle_ghost": 1}) + assert state.visible_ghosts() == [0] state.apply({"space": "B"}) - assert state.visible() == [1] and state.values["selected"] == 1 + assert state.matching() == [1] and state.visible_ghosts() == [] + state.apply({"ghosts": True}) + assert state.visible_ghosts() == [1] state.apply({"aff": "0", "playing": True}) - assert state.visible() == [] and not state.values["playing"] - assert state.snapshot()["source_frame"] is None + assert state.matching() == [] and state.values["playing"] + assert state.snapshot()["episode"] == "original" + assert state.snapshot()["source_frame"] == 0 state.apply({"space": "all", "aff": "all", "progress": 0.5}) + assert state.visible_ghosts() == [0, 1] + state.apply({"space": "B", "ghosts": False}) + state.apply({"space": "all"}) + assert state.visible_ghosts() == [0] assert state.frame_at(first) == 0 # phase boundary .4 s -> recorded frame at 0 s state.apply({"align": "time"}) assert state.frame_at(first) == 1 # exactly .5 s @@ -248,7 +415,8 @@ def test_filter_empty_intersection_and_phase_alignment(recorded_job): assert state.frame_at(first) == 2 for update in ( {"progress": float("nan")}, - {"selected": True}, + {"toggle_ghost": True}, + {"toggle_ghost": 2}, {"playing": "true"}, {"unknown": 0}, {"aff": "missing"}, @@ -259,6 +427,20 @@ def test_filter_empty_intersection_and_phase_alignment(recorded_job): assert state.values == before +def test_playback_toggles_in_order_and_restarts_from_the_end(recorded_job): + path, _, _ = recorded_job + state = PreviewState(load_preview([path])) + state.apply({"progress": 0.5}) + toggle = {"toggle_playback": True} + state.apply(toggle) + assert state.values["playing"] and state.values["progress"] == 0.5 + state.apply(toggle) + assert not state.values["playing"] and state.values["progress"] == 0.5 + state.apply({"progress": 1}) + state.apply(toggle) + assert state.values["playing"] and state.values["progress"] == 0 + + def test_http_snapshot_control_and_shutdown(recorded_job): path, _, _ = recorded_job state = PreviewState(load_preview([path])) @@ -267,6 +449,13 @@ def test_http_snapshot_control_and_shutdown(recorded_job): thread = threading.Thread(target=transport.server.serve_forever) thread.start() try: + heatmaps = json.load(urllib.request.urlopen(transport.url + "object-heatmaps")) + assert heatmaps["episodes"] == 1 + assert heatmaps["objects"][0]["views"]["all"]["bounds_m"] == [ + [10, 20], + [10, 20], + ] + assert np.sum(heatmaps["objects"][0]["views"]["all"]["counts"]) == 1 snapshot = json.load(urllib.request.urlopen(transport.url + "snapshot")) assert snapshot["frame"] == 7 and snapshot["source_frame"] == 2 assert base64.b64decode(snapshot["image"].split(",")[1]) == b"jpeg-frame-7" @@ -314,7 +503,7 @@ def test_preview_cli_dispatch_does_not_collect(monkeypatch, recorded_job): ) -def test_viewer_html_is_in_package_data(tmp_path): +def test_viewer_assets_are_in_package_data(tmp_path): from setup import get_package_data from setuptools import Distribution from setuptools.command.build_py import build_py @@ -323,10 +512,10 @@ def test_viewer_html_is_in_package_data(tmp_path): package = "embodichain.lab.expansion" source = tmp_path / "source" source.mkdir() - original = ( - Path(__file__).resolve().parents[3] / "embodichain/lab/expansion/_preview.html" - ) - shutil.copyfile(original, source / "_preview.html") + originals = Path(__file__).resolve().parents[3] / "embodichain/lab/expansion" + assets = ("_preview.html", "_preview_charts.js", "_preview_heatmap.js") + for name in assets: + shutil.copyfile(originals / name, source / name) (source / "__init__.py").write_text("") distribution = Distribution( { @@ -341,8 +530,9 @@ def test_viewer_html_is_in_package_data(tmp_path): command.build_lib = str(tmp_path / "build") command.ensure_finalized() command.run() - packaged = Path(command.build_lib) / "embodichain/lab/expansion/_preview.html" - assert packaged.read_bytes() == original.read_bytes() + packaged = Path(command.build_lib) / "embodichain/lab/expansion" + for name in assets: + assert (packaged / name).read_bytes() == (originals / name).read_bytes() def test_manifest_keeps_rejected_points_visible_in_coverage(recorded_job): @@ -456,3 +646,12 @@ def test_aggregate_input_keeps_explicit_reference_separate(recorded_job, second_ assert len(data.clips) == 1 + second_count assert data.reference.space.endswith("reference") assert all(not clip.space.endswith("reference") for clip in data.clips) + # Without a separate original, the first input stays solid across group changes. + fallback = PreviewState(replace(data, reference=None)) + fallback.apply({"space": data.clips[-1].space, "ghosts": True}) + snapshot = fallback.snapshot() + assert snapshot["episode"] == "first-0" + assert snapshot["total"] == second_count + assert {data.clips[i].measured.name for i in snapshot["visible_ghosts"]} == { + f"second-{index}" for index in range(second_count) + } From dff0d4e54eee42907722801c2ab70413017f522e Mon Sep 17 00:00:00 2001 From: matafela Date: Thu, 19 Nov 2026 15:19:32 +0800 Subject: [PATCH 41/49] fix(expansion): handle decomposed colliders in scene-first screening --- .../topics/expansion-engine/workloads.md | 6 + .../topics/scene-expansion/feasibility.md | 6 +- .../geometry/_warp/batch_contact_query.py | 12 +- .../compute/geometry/_warp/contact_query.py | 21 +- .../lab/expansion/_scene_first_sampling.py | 25 +- embodichain/lab/expansion/acceptance.py | 23 +- .../lab/expansion/task_program_jobs.py | 23 +- .../scene/feasibility/_collision_batches.py | 20 +- .../lab/sim/scene/feasibility/collision.py | 223 ++++++++++++------ .../lab/sim/scene/feasibility/planning.py | 5 + .../task_program/integrations/feasibility.py | 2 +- .../simulation/feasibility_geometry.py | 48 +++- .../expansion/test_scene_first_sampling.py | 70 +++++- .../feasibility/test_collision_planning.py | 79 +++++++ 14 files changed, 425 insertions(+), 138 deletions(-) diff --git a/agent_context/topics/expansion-engine/workloads.md b/agent_context/topics/expansion-engine/workloads.md index c4396fe6f4..0b6fcd4ed4 100644 --- a/agent_context/topics/expansion-engine/workloads.md +++ b/agent_context/topics/expansion-engine/workloads.md @@ -228,6 +228,12 @@ preparation/conditional generation and `RobotFeasibilityBackend`/`plan_task_mode it creates no physics World and owns only the isolated collision-query resources. `layout` and `task_mode` are explicit, validated task declarations. Root layout variables currently use XY only; selected nested members retain declared XY/yaw. +Placement uses projected object bounds and support geometry. The subsequent +phase/path screen preserves physical convex hulls. For `scene_first` +`object_pose` only, each rigid triangle mesh uses a box enclosing its scaled +vertices in collider-local axes. This can reject placements inside concave +fixtures. `scene-first-checks.json` records the affected collider IDs in +`rigid_mesh_box_proxies`. Rollout contacts use the simulator's physical shapes. Homogeneous replicas support rolling W times B collection, including eight rows. Preparation snapshots the common prototype geometry, installation and nominal full-joint planning start before any row executes. The feasibility adapter uses diff --git a/agent_context/topics/scene-expansion/feasibility.md b/agent_context/topics/scene-expansion/feasibility.md index 27596fb744..176417dd30 100644 --- a/agent_context/topics/scene-expansion/feasibility.md +++ b/agent_context/topics/scene-expansion/feasibility.md @@ -43,8 +43,10 @@ states. The physical extractor preserves native convex shapes, includes the global ground, and rejects triangle meshes, SDFs, non-robot articulations and unsupported robot asset scales/formats. No collider is silently convexified. Halfspaces use analytic physical-shape support. Phase masks do not mutate live -filters, and the query never advances the simulation clock. Shape/pair/contact -storage is bounded; saturation and nonfinite results remain unverified. +filters, and the query never advances the simulation clock. Explicit pair +lists and phase masks contain only eligible pairs. Batched rows share a +bounded pair/contact budget and run in chunks when needed. Callers can set a +separate shape quota. Saturation and nonfinite results remain unverified. The host closes the owned query arrays/graphs after every attempt. Query transforms are rebased before composing local offsets; precision budgets diff --git a/embodichain/compute/geometry/_warp/batch_contact_query.py b/embodichain/compute/geometry/_warp/batch_contact_query.py index af31b4fa4f..3083890b25 100644 --- a/embodichain/compute/geometry/_warp/batch_contact_query.py +++ b/embodichain/compute/geometry/_warp/batch_contact_query.py @@ -21,6 +21,8 @@ import warp as wp +from .contact_query import _pair_slot + __all__: list[str] = [] @@ -36,6 +38,7 @@ def contact_summary( margin1: wp.array(dtype=float), shape_body: wp.array(dtype=wp.int32), poses: wp.array(dtype=wp.transform), + pair_keys: wp.array(dtype=wp.int64), active: wp.array(dtype=wp.int32), width: int, batches: int, @@ -74,7 +77,10 @@ def contact_summary( else: row = a // width x, y = a % width, b % width - if active[x * width + y] != 0: + slot = _pair_slot(pair_keys, width, x, y) + if slot < 0: + wp.atomic_min(output, row, 2, 0.0) + elif active[slot] != 0: p0 = wp.transform_point(poses[shape_body[a]], point0[index]) p1 = wp.transform_point(poses[shape_body[b]], point1[index]) distance = ( @@ -85,6 +91,4 @@ def contact_summary( else: wp.atomic_min(output, row, 0, distance) if distance <= required + tolerance[row]: - wp.atomic_min( - output, row, 1, float(wp.min(x, y) * width + wp.max(x, y)) - ) + wp.atomic_min(output, row, 1, float(slot)) diff --git a/embodichain/compute/geometry/_warp/contact_query.py b/embodichain/compute/geometry/_warp/contact_query.py index 70f808542d..37c22ea3c0 100644 --- a/embodichain/compute/geometry/_warp/contact_query.py +++ b/embodichain/compute/geometry/_warp/contact_query.py @@ -23,6 +23,16 @@ __all__ = [] +@wp.func +def _pair_slot(keys: wp.array(dtype=wp.int64), width: int, a: int, b: int): + key = wp.int64(wp.min(a, b)) * wp.int64(width) + wp.int64(wp.max(a, b)) + slot = wp.lower_bound(keys, key) + if slot < keys.shape[0]: + if keys[slot] == key: + return slot + return int(-1) + + @wp.kernel(enable_backward=False) def _contact_summary( count: wp.array(dtype=wp.int32), @@ -35,6 +45,7 @@ def _contact_summary( margin1: wp.array(dtype=float), shape_body: wp.array(dtype=wp.int32), poses: wp.array(dtype=wp.transform), + pair_keys: wp.array(dtype=wp.int64), active: wp.array(dtype=wp.int32), shapes: int, required: float, @@ -65,7 +76,11 @@ def _contact_summary( a, b = first[index], second[index] if a < 0 or b < 0 or a >= shapes or b >= shapes: wp.atomic_min(output, 3, 0.0) - elif active[a * shapes + b] != 0: + return + slot = _pair_slot(pair_keys, shapes, a, b) + if slot < 0: + wp.atomic_min(output, 3, 0.0) + elif active[slot] != 0: p0 = wp.vec3(point0[index][0], point0[index][1], point0[index][2]) p1 = wp.vec3(point1[index][0], point1[index][1], point1[index][2]) owner0, owner1 = shape_body[a], shape_body[b] @@ -79,6 +94,4 @@ def _contact_summary( else: wp.atomic_min(output, 0, distance) if distance <= required + tolerance[0]: - wp.atomic_min( - output, 1, float(wp.min(a, b) * shapes + wp.max(a, b)) - ) + wp.atomic_min(output, 1, float(slot)) diff --git a/embodichain/lab/expansion/_scene_first_sampling.py b/embodichain/lab/expansion/_scene_first_sampling.py index ff94f5d5a2..1f3f682c18 100644 --- a/embodichain/lab/expansion/_scene_first_sampling.py +++ b/embodichain/lab/expansion/_scene_first_sampling.py @@ -39,6 +39,19 @@ __all__: list[str] = [] +def _layout_collision_bodies(env, strategy, operator): + from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( + _physical_collision_bodies, + collision_bodies_from_simulation, + ) + + if strategy == "scene_first" and operator == "object_pose": + mesh_boxes = [] + bodies = _physical_collision_bodies(env, env_id=0, layout_mesh_boxes=mesh_boxes) + return bodies, mesh_boxes + return collision_bodies_from_simulation(env), [] + + class _LayoutPoseSource(_AdaptivePoseSource): """Generate or certify complete layouts before checking task branches. @@ -47,7 +60,7 @@ class _LayoutPoseSource(_AdaptivePoseSource): Runtime execution still replans and independently validates measured outcomes. """ - def __init__(self, env, options, *, seed, revision): + def __init__(self, env, options, *, seed, revision, operator=None): before = self._world_clock(env.sim) self._collision = None super().__init__(env, options, seed=seed, revision=revision) @@ -141,18 +154,17 @@ def __init__(self, env, options, *, seed, revision): ) self._workspace_seconds = time.perf_counter() - started - from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( - collision_bodies_from_simulation, - ) from .acceptance import _GeometryRow from embodichain.lab.sim.scene.feasibility import NewtonCollisionChecker - bodies = collision_bodies_from_simulation(env) + bodies, self._layout_mesh_boxes = _layout_collision_bodies( + env, self.cfg["strategy"], operator + ) known = {b.frame_uid for b in bodies} ignored, _ = _GeometryRow.contact_permissions(env, options["validation"], known) try: self._collision = NewtonCollisionChecker( - bodies, ignored_pairs=ignored, device="cpu", max_shapes=512 + bodies, ignored_pairs=ignored, device="cpu" ) self._check_clock(env.sim, before) except BaseException: @@ -381,6 +393,7 @@ def checkpoint(self): dict( phase_checks=self._task_checks, layout_source=self._prepared_layout.source.fingerprint, + rigid_mesh_box_proxies=self._layout_mesh_boxes, conditions=self._conditions.to_dict(), workspace_prior=[pool.metrics() for pool in self._anchor_pools], workspace_anchor_checks=self._anchor_checks, diff --git a/embodichain/lab/expansion/acceptance.py b/embodichain/lab/expansion/acceptance.py index 2b7937e28e..8dfba26254 100644 --- a/embodichain/lab/expansion/acceptance.py +++ b/embodichain/lab/expansion/acceptance.py @@ -162,7 +162,7 @@ def __init__( checker = None if checker_pool is None else checker_pool.get(key) if checker is None: checker = NewtonCollisionChecker( - bodies, ignored_pairs=ignored, device=device, max_shapes=512 + bodies, ignored_pairs=ignored, device=device ) if checker_pool is not None: checker_pool[key] = checker @@ -733,20 +733,13 @@ def _sample_geometry(self, ids, action): moving = tuple(uid for uid in check.moving if uid in aliases) groups.setdefault((checker, tuple(allowed), moving), []).append(row) for (checker, allowed, moving), rows in groups.items(): - # Respect the existing aggregate contact-buffer ceiling. Compact - # selected rows also prevent inactive/heterogeneous rows consuming it. - width = max(1, min(env.num_envs, 1048576 // checker._capacity)) - for start in range(0, len(rows), width): - selected = rows[start : start + width] - reports = checker.check_batch( - {uid: values[selected] for uid, values in frames.items()}, - allowed_contacts=allowed, - moving_objects=moving, - ) - for row, report, pair in zip( - selected, reports, checker.last_batch_pairs - ): - self.rows[row].record_geometry(report, pair, action) + reports = checker.check_batch( + {uid: values[rows] for uid, values in frames.items()}, + allowed_contacts=allowed, + moving_objects=moving, + ) + for row, report, pair in zip(rows, reports, checker.last_batch_pairs): + self.rows[row].record_geometry(report, pair, action) def close(self) -> None: """Detach owned observers before releasing resources; safe on failure.""" diff --git a/embodichain/lab/expansion/task_program_jobs.py b/embodichain/lab/expansion/task_program_jobs.py index d62af0d1c1..2d8f37f632 100644 --- a/embodichain/lab/expansion/task_program_jobs.py +++ b/embodichain/lab/expansion/task_program_jobs.py @@ -68,18 +68,19 @@ def source(env): nonlocal pose_source from ._scene_first_sampling import _LayoutPoseSource - source_type = ( - _LayoutPoseSource - if "layout" in options.get("scene_sampling", {}) - else _AdaptivePoseSource - ) - pose_source = ( - source_type(env, options, seed=seed, revision=report["semantic_id"]) - if "scene_sampling" in options - else _BoundedPoseSource( - env, options["scene"], seed=seed, revision=report["semantic_id"] + revision = report["semantic_id"] + if "layout" in options.get("scene_sampling", {}): + pose_source = _LayoutPoseSource( + env, options, seed=seed, revision=revision, operator=operator + ) + elif "scene_sampling" in options: + pose_source = _AdaptivePoseSource( + env, options, seed=seed, revision=revision + ) + else: + pose_source = _BoundedPoseSource( + env, options["scene"], seed=seed, revision=revision ) - ) return pose_source def feedback(env, source, path): diff --git a/embodichain/lab/sim/scene/feasibility/_collision_batches.py b/embodichain/lab/sim/scene/feasibility/_collision_batches.py index 6ffe907fc9..40e2c520b0 100644 --- a/embodichain/lab/sim/scene/feasibility/_collision_batches.py +++ b/embodichain/lab/sim/scene/feasibility/_collision_batches.py @@ -57,6 +57,7 @@ def __init__(self, checker, count, allowed, moving, all_pairs=False): gap=checker.detection_gap_m / 2, margin=0.0, density=0.0, + collision_group=0, # All query pairs are supplied explicitly. collision_filter_parent=False, ) for index in checker._native: @@ -98,19 +99,8 @@ def __init__(self, checker, count, allowed, moving, all_pairs=False): self.model = batch.finalize(device=checker.device) self.state = self.model.state() width = len(checker._native) - pairs = [ - (checker._native_lookup[i], checker._native_lookup[j]) - for i, j in checker._pairs - if i in checker._native_lookup and j in checker._native_lookup - ] - explicit = np.asarray( - [ - (a + row * width, b + row * width) - for row in range(count) - for a, b in pairs - ], - dtype=np.int32, - ) + offsets = np.arange(count, dtype=np.int32) * width + explicit = (checker._shape_pairs + offsets[:, None, None]).reshape(-1, 2) self.explicit = wp.array(explicit, dtype=wp.vec2i, device=checker.device) self.capacity = checker._capacity * count self.pipeline = newton.CollisionPipeline( @@ -170,6 +160,7 @@ def _run(self): contacts.rigid_contact_margin1, self.model.shape_body, self.state.body_q, + checker._pair_keys, self.active, len(checker._native), self.count, @@ -303,8 +294,7 @@ def check(self, frame_poses, rows): "Batched Newton query overflowed or returned invalid evidence" ) if row not in failures and math.isfinite(summary[row, 1]): - a, b = divmod(int(summary[row, 1]), len(checker._native)) - failures[row] = (checker._native[a], checker._native[b]) + failures[row] = checker._native_pairs[int(summary[row, 1])] self.queries += 1 result = [] for row in rows: diff --git a/embodichain/lab/sim/scene/feasibility/collision.py b/embodichain/lab/sim/scene/feasibility/collision.py index f45478e3e0..4e4a4dc6f0 100644 --- a/embodichain/lab/sim/scene/feasibility/collision.py +++ b/embodichain/lab/sim/scene/feasibility/collision.py @@ -21,9 +21,12 @@ from collections.abc import Mapping, Sequence from collections import OrderedDict from dataclasses import dataclass +from functools import cached_property from importlib.metadata import version +from itertools import islice import math from numbers import Integral +from typing import ClassVar import numpy as np @@ -33,6 +36,11 @@ __all__ = ["CollisionBody", "NewtonCollisionChecker", "UnsupportedFeasibilityError"] +# Each explicit pair has one mask entry. Its ordinal fits exactly in the +# float32 contact summary, including when a heavily decomposed shape has a large ID. +_MAX_QUERY_PAIRS = 1 << 20 +_MAX_CONTACTS = 1 << 20 + class UnsupportedFeasibilityError(RuntimeError): """Required geometry, task adaptation or runtime capability is unavailable.""" @@ -151,7 +159,8 @@ class NewtonCollisionChecker: numeric_tolerance_m: Conservative contact threshold and returned-distance allowance for float32 geometry. use_cuda_graph: Capture repeated CUDA queries after a warm call. - max_shapes: Explicit shape budget, at most 512; bounds pair storage. + max_shapes: Optional caller limit on physical shapes. Storage is budgeted + separately for eligible collision pairs and actual contacts. max_contacts: Upper contact-buffer budget; saturation is unsupported. Returns from check contain a capped conservative clearance estimate, not @@ -163,6 +172,8 @@ class NewtonCollisionChecker: representation/precision budgets return unsupported. """ + query_contract: ClassVar[str] = "newton-convex-query/v2" + def __init__( self, bodies: Sequence[CollisionBody], @@ -173,15 +184,18 @@ def __init__( detection_gap_m: float = 0.03, numeric_tolerance_m: float = 1e-6, use_cuda_graph: bool = True, - max_shapes: int = 256, - max_contacts: int = 1048576, + max_shapes: int | None = None, + max_contacts: int = _MAX_CONTACTS, ) -> None: self.bodies = tuple(bodies) - count(max_shapes, "max_shapes") + if max_shapes is not None: + count(max_shapes, "max_shapes") count(max_contacts, "max_contacts") - if max_contacts > 1048576: - raise ValueError("max_contacts must not exceed 1048576") - if max_shapes > 512 or not 1 <= len(self.bodies) <= max_shapes: + if max_contacts > _MAX_CONTACTS: + raise ValueError(f"max_contacts must not exceed {_MAX_CONTACTS}") + if not self.bodies or ( + max_shapes is not None and len(self.bodies) > max_shapes + ): raise UnsupportedFeasibilityError( "Physical collision shape budget exceeded" ) @@ -268,7 +282,8 @@ def __init__( ) for collision_id in ids: self._aliases.setdefault(collision_id, {collision_id}) - self.ignored_pairs = frozenset(self._expand_pairs(ignored_pairs)) + self._ignored_alias_pairs = self._permission_pairs(ignored_pairs) + ignored_targets = self._permission_targets(self._ignored_alias_pairs) self.last_pair = None self.last_clearance_interval: tuple[float, float] | None = None self._frame_uids = tuple(dict.fromkeys(b.frame_uid for b in self.bodies)) @@ -278,23 +293,35 @@ def __init__( self._native_lookup = { logical: index for index, logical in enumerate(self._native) } - self._pairs = tuple( + eligible = ( (i, j) for i in range(len(self.bodies)) for j in range(i + 1, len(self.bodies)) if self.bodies[i].frame_uid != self.bodies[j].frame_uid - and frozenset((self.bodies[i].collision_id, self.bodies[j].collision_id)) - not in self.ignored_pairs + and self.bodies[j].frame_uid not in ignored_targets[i] + and self.bodies[j].collision_id not in ignored_targets[i] ) - native_pairs = [ - (self._native_lookup[i], self._native_lookup[j]) - for i, j in self._pairs + pairs = tuple(islice(eligible, _MAX_QUERY_PAIRS + 1)) + if len(pairs) > _MAX_QUERY_PAIRS: + raise UnsupportedFeasibilityError("Explicit collision pair budget exceeded") + self._native_pairs = tuple( + (i, j) + for i, j in pairs if i in self._native_lookup and j in self._native_lookup - ] - requested_capacity = max(64, 16 * len(native_pairs)) - if requested_capacity > 1048576: - raise UnsupportedFeasibilityError("Physical collision pair budget exceeded") - self._capacity = min(max_contacts, requested_capacity) + ) + self._plane_pairs = tuple( + (i, j) + for i, j in pairs + if i not in self._native_lookup or j not in self._native_lookup + ) + self._shape_pairs = np.asarray( + [ + (self._native_lookup[i], self._native_lookup[j]) + for i, j in self._native_pairs + ], + dtype=np.int32, + ).reshape(-1, 2) + self._capacity = min(max_contacts, max(64, 16 * len(self._native_pairs))) self._mask_cache = OrderedDict() self._batch_queries = OrderedDict() self.last_batch_pairs: tuple[tuple[str, str] | None, ...] = () @@ -302,17 +329,17 @@ def __init__( self._graph = self._active = self._output = self._empty_count = ( self._explicit ) = None - self._tolerance = None + self._pair_keys = self._tolerance = None self._meshes = [] self._closed = False self._version = version("newton") self.verification_id = digest( ( - "newton-convex-query/v1", + self.query_contract, "relative-origin/scale-allowance/v1", self._version, self.bodies, - self.ignored_pairs, + self._ignored_alias_pairs, self.clearance_m, self.detection_gap_m, self.numeric_tolerance_m, @@ -323,8 +350,8 @@ def __init__( ) ) try: - if native_pairs: - self._build_query(native_pairs) + if self._native_pairs: + self._build_query() except Exception: self.close() raise @@ -348,13 +375,14 @@ def metadata(self) -> dict[str, str | float | int | bool]: "max_effective_tolerance_m": self._max_effective_tolerance, "max_abs_query_coordinate_m": 1e6, "shape_count": len(self.bodies), + "native_pair_count": len(self._native_pairs), "contact_capacity": self._capacity, "cuda_graph": "captured" if self._graph is not None else "disabled", "halfspace_check": "analytic_physical_support", "continuous": False, } - def _build_query(self, pairs: list[tuple[int, int]]) -> None: + def _build_query(self) -> None: import newton import warp as wp from embodichain.compute.geometry._warp.contact_query import _contact_summary @@ -366,6 +394,9 @@ def _build_query(self, pairs: list[tuple[int, int]]) -> None: gap=self.detection_gap_m / 2, margin=0.0, density=0.0, + # Leave the builder's default pair table empty. The explicit + # pipeline supplies all eligible pairs. + collision_group=0, collision_filter_parent=False, ) for index in self._native: @@ -406,9 +437,13 @@ def _build_query(self, pairs: list[tuple[int, int]]) -> None: ) self._model = builder.finalize(device=self.device) self._state = self._model.state() - self._explicit = wp.array( - np.asarray(pairs, dtype=np.int32), dtype=wp.vec2i, device=self.device + self._explicit = wp.array(self._shape_pairs, dtype=wp.vec2i, device=self.device) + # Native shape IDs follow logical order, so these keys are sorted. + keys = ( + self._shape_pairs[:, 0].astype(np.int64) * len(self._native) + + self._shape_pairs[:, 1] ) + self._pair_keys = wp.array(keys, dtype=wp.int64, device=self.device) self._pipeline = newton.CollisionPipeline( self._model, broad_phase="explicit", @@ -423,13 +458,26 @@ def _build_query(self, pairs: list[tuple[int, int]]) -> None: ) self._contacts = self._pipeline.contacts() self._active = wp.zeros( - len(self._native) ** 2, dtype=wp.int32, device=self.device + len(self._native_pairs), dtype=wp.int32, device=self.device ) self._output = wp.empty(4, dtype=float, device=self.device) self._empty_count = wp.zeros(1, dtype=wp.int32, device=self.device) self._tolerance = wp.empty(1, dtype=float, device=self.device) - def _expand_pairs(self, pairs: Sequence[tuple[str, str]]) -> set[frozenset[str]]: + @cached_property + def ignored_pairs(self) -> frozenset[frozenset[str]]: + """Return the expanded physical IDs for callers exporting the query.""" + return frozenset( + frozenset((a, b)) + for left, right in self._ignored_alias_pairs + for a in self._aliases[left] + for b in self._aliases[right] + if a != b + ) + + def _permission_pairs( + self, pairs: Sequence[tuple[str, str]] + ) -> frozenset[tuple[str, str]]: output = set() for pair in pairs: if ( @@ -440,13 +488,21 @@ def _expand_pairs(self, pairs: Sequence[tuple[str, str]]) -> set[frozenset[str]] raise ValueError( "contact permissions require two distinct known physical IDs or frames" ) - output.update( - frozenset((a, b)) - for a in self._aliases[pair[0]] - for b in self._aliases[pair[1]] - if a != b - ) - return output + output.add(tuple(sorted(pair))) + return frozenset(output) + + def _permission_targets(self, pairs): + # A permission can name a whole frame or just one of its colliders. + # Keep frame exemptions compact even for heavily decomposed assets. + targets = {} + for left, right in pairs: + targets.setdefault(left, set()).add(right) + targets.setdefault(right, set()).add(left) + empty = frozenset() + return tuple( + targets.get(body.frame_uid, empty) | targets.get(body.collision_id, empty) + for body in self.bodies + ) def _mask( self, @@ -461,30 +517,37 @@ def _mask( raise UnsupportedFeasibilityError( "Moving object has no physical collision geometry" ) - allowed = frozenset(self._expand_pairs(allowed_contacts)) + allowed = self._permission_pairs(allowed_contacts) key = (allowed, frozenset(moving), all_pairs) if key in self._mask_cache: self._mask_cache.move_to_end(key) return self._mask_cache[key] - mask = np.zeros(len(self._native) ** 2, dtype=np.int32) - planes = [] - for i, j in self._pairs: + + allowed_targets = self._permission_targets(allowed) + + def active(pair): + i, j = pair a, b = self.bodies[i], self.bodies[j] - if frozenset((a.collision_id, b.collision_id)) in allowed or not ( - all_pairs - or a.robot - or b.robot - or a.frame_uid in moving - or b.frame_uid in moving - ): - continue - if a.kind == "halfspace" or b.kind == "halfspace": - planes.append((i, j)) - else: - x, y = self._native_lookup[i], self._native_lookup[j] - mask[x * len(self._native) + y] = mask[y * len(self._native) + x] = 1 + return ( + b.frame_uid not in allowed_targets[i] + and b.collision_id not in allowed_targets[i] + and ( + all_pairs + or a.robot + or b.robot + or a.frame_uid in moving + or b.frame_uid in moving + ) + ) + + mask = np.fromiter( + map(active, self._native_pairs), + dtype=np.int32, + count=len(self._native_pairs), + ) + planes = tuple(filter(active, self._plane_pairs)) mask.setflags(write=False) - value = mask, tuple(planes), bool(mask.any()) + value = mask, planes, bool(mask.any()) self._mask_cache[key] = value if len(self._mask_cache) > 16: self._mask_cache.popitem(last=False) @@ -521,6 +584,7 @@ def _run_query(self) -> None: c.rigid_contact_margin1, self._model.shape_body, self._state.body_q, + self._pair_keys, self._active, len(self._native), self.clearance_m, @@ -696,8 +760,7 @@ def check( upper_clearance = min(upper_clearance, max(0.0, separation + tolerance)) if math.isfinite(summary[1]): self.last_clearance_interval = (clearance, upper_clearance) - a, b = divmod(int(summary[1]), len(self._native)) - return self._failure(self._native[a], self._native[b]), clearance + return self._failure(*self._native_pairs[int(summary[1])]), clearance self.last_clearance_interval = (clearance, upper_clearance) return FeasibilityCheck( "collision", @@ -714,7 +777,7 @@ def check_batch( all_pairs: bool = False, env_ids: Sequence[int] | None = None, ) -> tuple[FeasibilityCheck, ...]: - """Check independent measured rows with one bounded numerical query. + """Check independent measured rows in bounded numerical batches. Args: frame_poses: Every declared frame with arena poses ``(B, 4, 4)``. @@ -763,27 +826,33 @@ def check_batch( if type(all_pairs) is not bool: raise TypeError("all_pairs must be a bool") # Resolve permissions with the same native validation before caching. - allowed = frozenset(self._expand_pairs(allowed_contacts)) + allowed = self._permission_pairs(allowed_contacts) self._mask(allowed_contacts, moving_objects, all_pairs) - key = size, allowed, frozenset(moving_objects), all_pairs - query = self._batch_queries.get(key) - if query is None: - if size * self._capacity > 1048576: - raise UnsupportedFeasibilityError( - "Batched collision contact budget exceeded" + width = min( + _MAX_CONTACTS // self._capacity, + _MAX_QUERY_PAIRS // max(1, len(self._native_pairs)), + ) + reports = {} + for start in range(0, size, width): + count = min(width, size - start) + key = count, allowed, frozenset(moving_objects), all_pairs + query = self._batch_queries.get(key) + if query is None: + query = _CollisionBatches( + self, count, allowed_contacts, moving_objects, all_pairs ) - query = _CollisionBatches( - self, size, allowed_contacts, moving_objects, all_pairs - ) - self._batch_queries[key] = query - while len(self._batch_queries) > 2: - _, old = self._batch_queries.popitem(last=False) - old.close() - else: - self._batch_queries.move_to_end(key) - result = query.check(frames, rows) - self.last_batch_pairs = tuple(pair for _, _, pair in result) - return tuple(report for _, report, _ in result) + self._batch_queries[key] = query + if len(self._batch_queries) > 2: + _, old = self._batch_queries.popitem(last=False) + old.close() + else: + self._batch_queries.move_to_end(key) + local_rows = [row - start for row in rows if start <= row < start + count] + chunk = {uid: poses[start : start + count] for uid, poses in frames.items()} + for row, report, pair in query.check(chunk, local_rows): + reports[start + row] = report, pair + self.last_batch_pairs = tuple(reports[row][1] for row in rows) + return tuple(reports[row][0] for row in rows) def _failure(self, i: int, j: int) -> FeasibilityCheck: self.last_pair = self.bodies[i].collision_id, self.bodies[j].collision_id @@ -821,7 +890,7 @@ def _close_arrays(self) -> None: self._graph = self._pipeline = self._contacts = self._state = self._model = None self._active = self._output = self._empty_count = None self._tolerance = None - self._explicit = None + self._explicit = self._pair_keys = None self._meshes.clear() self._mask_cache.clear() self._closed = True diff --git a/embodichain/lab/sim/scene/feasibility/planning.py b/embodichain/lab/sim/scene/feasibility/planning.py index d07d7dec51..1edd2c0e04 100644 --- a/embodichain/lab/sim/scene/feasibility/planning.py +++ b/embodichain/lab/sim/scene/feasibility/planning.py @@ -466,6 +466,11 @@ def solutions( mask, q = result q = q.detach().cpu().double().numpy() valid = mask.detach().cpu().numpy() + # Analytic Warp solvers encode branch validity as integer 0/1. + if np.issubdtype(valid.dtype, np.integer) and np.all( + (valid == 0) | (valid == 1) + ): + valid = valid.astype(bool) if ( q.ndim not in (2, 3) or q.shape[0] != 1 diff --git a/embodichain/lab/task_program/integrations/feasibility.py b/embodichain/lab/task_program/integrations/feasibility.py index 279b2e5f3b..79cdddd2da 100644 --- a/embodichain/lab/task_program/integrations/feasibility.py +++ b/embodichain/lab/task_program/integrations/feasibility.py @@ -634,7 +634,7 @@ def build_feasibility_host( + digest( ( adapter, - "newton-convex-query/v1", + NewtonCollisionChecker.query_contract, version("newton"), cfg.collision_device, cfg.collision_use_cuda_graph, diff --git a/embodichain/lab/task_program/integrations/simulation/feasibility_geometry.py b/embodichain/lab/task_program/integrations/simulation/feasibility_geometry.py index 668a6084c3..61e5f97a7d 100644 --- a/embodichain/lab/task_program/integrations/simulation/feasibility_geometry.py +++ b/embodichain/lab/task_program/integrations/simulation/feasibility_geometry.py @@ -45,6 +45,13 @@ def collision_bodies_from_simulation( Unsupported physical geometry APIs/scales and shapes fail explicitly. The caller owns permanent structural and phase-specific contact permissions. """ + return _physical_collision_bodies(env, env_id=env_id) + + +def _physical_collision_bodies( + env: Any, *, env_id: int, layout_mesh_boxes: list[str] | None = None +) -> tuple[CollisionBody, ...]: + """Optionally bound rigid triangle meshes for an isolated layout proposal query.""" robot = env.robot if env.sim.get_articulation_uid_list(): raise UnsupportedFeasibilityError( @@ -58,6 +65,7 @@ def collision_bodies_from_simulation( def convert(shape, collision_id, frame_uid, *, is_robot=False): kind = shape.shape_type.name.lower() kwargs = {} + local_pose = shape.local_pose.cpu().numpy() if kind == "box": dimensions = tuple((shape.half_extents.cpu().numpy() * 2).tolist()) elif kind == "sphere": @@ -78,6 +86,44 @@ def convert(shape, collision_id, frame_uid, *, is_robot=False): for f in shape.triangles.cpu().numpy().reshape(-1, 3) ), } + elif kind == "mesh" and not is_robot and layout_mesh_boxes is not None: + if ( + shape.vertices is None + or shape.triangles is None + or not shape.triangles.numel() + ): + raise UnsupportedFeasibilityError( + f"Missing physical mesh geometry for {collision_id}" + ) + points = shape.vertices.cpu().numpy() + if ( + points.ndim != 2 + or points.shape[1] != 3 + or not len(points) + or not np.isfinite(points).all() + ): + raise UnsupportedFeasibilityError( + f"Invalid physical mesh vertices for {collision_id}" + ) + faces = shape.triangles.cpu().numpy() + if ( + faces.dtype.kind not in "iu" + or faces.size % 3 + or faces.min() < 0 + or faces.max() >= len(points) + ): + raise UnsupportedFeasibilityError( + f"Invalid physical mesh triangles for {collision_id}" + ) + low = points.min(axis=0).astype(float) + high = points.max(axis=0).astype(float) + # Descriptors already include body scale. Keep the box in the shape + # axes and transform its center to the owner frame exactly once. + local_pose = local_pose.astype(float, copy=True) + local_pose[:3, 3] += local_pose[:3, :3] @ ((low + high) / 2) + dimensions = tuple(np.maximum(high - low, 1e-6)) + kind = "box" + layout_mesh_boxes.append(collision_id) else: raise UnsupportedFeasibilityError( f"Native physical shape {collision_id}: {kind} is unsupported" @@ -87,7 +133,7 @@ def convert(shape, collision_id, frame_uid, *, is_robot=False): frame_uid, kind, dimensions, - shape.local_pose.cpu().tolist(), + local_pose.tolist(), robot=is_robot, **kwargs, ) diff --git a/tests/lab/expansion/test_scene_first_sampling.py b/tests/lab/expansion/test_scene_first_sampling.py index 85f8b6ba5b..2b185b1ae4 100644 --- a/tests/lab/expansion/test_scene_first_sampling.py +++ b/tests/lab/expansion/test_scene_first_sampling.py @@ -25,9 +25,75 @@ import torch from scene_layout_support import make_source -from embodichain.lab.expansion._scene_first_sampling import _LayoutPoseSource +from embodichain.lab.expansion._scene_first_sampling import ( + _LayoutPoseSource, + _layout_collision_bodies, +) from embodichain.lab.expansion._pose_sampling_cfg import validate_sampling -from embodichain.lab.sim.scene.feasibility import FeasibilityBudgetExhausted +from embodichain.lab.sim.scene.feasibility import ( + FeasibilityBudgetExhausted, + UnsupportedFeasibilityError, +) + + +def test_scene_first_object_pose_bounds_only_native_rigid_triangle_meshes(): + from embodichain.lab.task_program.integrations.simulation.feasibility_geometry import ( + collision_bodies_from_simulation, + ) + + hull = SimpleNamespace( + shape_type=SimpleNamespace(name="CONVEX"), + local_pose=torch.eye(4), + vertices=torch.tensor([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]]), + triangles=torch.tensor([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]]), + ) + pose = torch.tensor([[0, -1, 0, 10], [1, 0, 0, 0], [0, 0, 1, 1], [0, 0, 0, 1.0]]) + mesh = SimpleNamespace( + shape_type=SimpleNamespace(name="MESH"), + local_pose=pose.clone(), + vertices=torch.tensor([[1, 2, 0], [5, 2, 0], [1, 4, 0]]), + triangles=torch.tensor([[0, 1, 2]]), + ) + robot = SimpleNamespace( + uid="robot", + cfg=SimpleNamespace(body_scale=(1, 1, 1)), + link_names=("arm",), + get_link_collision_shapes=lambda link: [hull], + ) + env = SimpleNamespace( + robot=robot, + sim=SimpleNamespace( + get_articulation_uid_list=lambda: (), + get_rigid_object_uid_list=lambda: ["shelf"], + get_rigid_object=lambda uid: SimpleNamespace( + get_collision_shapes=lambda: [mesh] + ), + ), + ) + (arm, shelf), proxies = _layout_collision_bodies(env, "scene_first", "object_pose") + assert arm.kind == "convex" and arm.robot + np.testing.assert_array_equal(arm.vertices, hull.vertices) + assert proxies == [shelf.collision_id] == ["shelf/0"] + assert shelf.kind == "box" + np.testing.assert_allclose(shelf.dimensions, [4, 2, 1e-6]) + np.testing.assert_allclose(np.array(shelf.local_pose)[:3, :3], pose[:3, :3]) + np.testing.assert_allclose(np.array(shelf.local_pose)[:3, 3], [7, 3, 1]) + torch.testing.assert_close(mesh.local_pose, pose) + + with pytest.raises(UnsupportedFeasibilityError, match="shelf/0: mesh"): + collision_bodies_from_simulation(env) + for strategy, operator in [ + ("scene_first", "affordance"), + ("robot_first", "object_pose"), + ]: + with pytest.raises(UnsupportedFeasibilityError, match="shelf/0: mesh"): + _layout_collision_bodies(env, strategy, operator) + mesh.triangles = torch.tensor([[0, 1, 3]]) + with pytest.raises(UnsupportedFeasibilityError, match="triangles for shelf/0"): + _layout_collision_bodies(env, "scene_first", "object_pose") + robot.get_link_collision_shapes = lambda link: [mesh] + with pytest.raises(UnsupportedFeasibilityError, match="robot/arm/0: mesh"): + _layout_collision_bodies(env, "scene_first", "object_pose") def setup_source( diff --git a/tests/sim/scene/feasibility/test_collision_planning.py b/tests/sim/scene/feasibility/test_collision_planning.py index 12b028b1ee..6c091bf4cb 100644 --- a/tests/sim/scene/feasibility/test_collision_planning.py +++ b/tests/sim/scene/feasibility/test_collision_planning.py @@ -130,6 +130,72 @@ def test_batched_geometry_matches_scalar_rows_and_rebinds_permissions(device): checker.close() +@pytest.mark.parametrize( + "device", ["cpu", pytest.param("cuda:0", marks=pytest.mark.gpu)] +) +def test_decomposed_geometry_crosses_512_shapes_with_physical_pair_identity( + monkeypatch, device +): + pytest.importorskip("newton") + bodies = [CollisionBody("ground", "ground", "halfspace", (0, 0, 1, 0))] + for frame, axis, count in (("arm", 0, 257), ("payload", 1, 256)): + for i in range(count): + local = np.eye(4) + local[axis, 3] = i / 8 + bodies.append( + CollisionBody( + f"{frame}/{i}", + frame, + "sphere", + (0.01,), + local, + robot=frame == "arm", + ) + ) + with pytest.raises(UnsupportedFeasibilityError, match="shape budget"): + NewtonCollisionChecker(bodies, max_shapes=512) + checker = NewtonCollisionChecker( + bodies, device=device, ignored_pairs=(("ground", "arm"),), max_contacts=64 + ) + try: + frames = { + name: np.repeat(np.eye(4)[None], 2, axis=0) + for name in ("arm", "payload", "ground") + } + frames["ground"][:, 2, 3] = -1 + frames["payload"][:, :3, 3] = [256 / 8, -255 / 8, 0] + frames["payload"][1, 2, 3] = 1 + pair = ("arm/256", "payload/255") + assert checker.metadata["native_pair_count"] == 257 * 256 + assert len(checker.ignored_pairs) == 257 + assert frozenset(("ground", "arm/256")) in checker.ignored_pairs + assert checker.check({k: v[0] for k, v in frames.items()})[0].status == "failed" + assert checker.last_pair == pair + assert [r.status for r in checker.check_batch(frames)] == ["failed", "passed"] + assert checker.last_batch_pairs == (pair, None) + assert ( + checker.check_batch(frames, allowed_contacts=(pair,))[0].status == "passed" + ) + assert ( + checker.check_batch(frames, allowed_contacts=(("payload", "arm/256"),))[ + 0 + ].status + == "passed" + ) + # One row fits the aggregate pair budget. The reversed selection crosses chunks. + monkeypatch.setattr( + "embodichain.lab.sim.scene.feasibility.collision._MAX_QUERY_PAIRS", + 257 * 256, + ) + assert [r.status for r in checker.check_batch(frames, env_ids=(1, 0))] == [ + "passed", + "failed", + ] + assert checker.last_batch_pairs == (None, pair) + finally: + checker.close() + + def test_phase_branches_must_connect_and_dual_targets_stay_synchronized(): identity = np.eye(4).tolist() mode = TaskOperationMode( @@ -297,6 +363,19 @@ def check(self, *args, **kwargs): result = plan_task_mode(simultaneous, backend, {}, FeasibilityBudget(cfg)) assert result.accepted and result.paths[-1][-1] == pytest.approx((1.0, 0.0)) + # OPW supplies one integer flag per analytic branch on the selected row. + validity = torch.tensor([[0, 1]], dtype=torch.int32) + backend.robot.compute_ik = lambda pose, **kw: ( + validity, + pose[:, None, 2, 3, None].expand(-1, 2, -1), + ) + assert plan_task_mode(mode, backend, {}, FeasibilityBudget(cfg)).accepted + validity[0, 1] = 0 + assert not plan_task_mode(mode, backend, {}, FeasibilityBudget(cfg)).accepted + validity[0, 1] = 2 + with pytest.raises(ValueError, match="IK result shape/type"): + plan_task_mode(mode, backend, {}, FeasibilityBudget(cfg)) + def test_robot_adapter_projects_mimic_follower_for_collision(): from types import SimpleNamespace From 86d9d540809927ab0dd924cadc9236f35c18ae28 Mon Sep 17 00:00:00 2001 From: matafela Date: Thu, 19 Nov 2026 16:00:58 +0800 Subject: [PATCH 42/49] fix(expansion): plot only measured object_pose starting layouts --- .../expansion-engine/expansion-engine.md | 6 +- embodichain/lab/expansion/_preview.html | 17 +-- embodichain/lab/expansion/_preview_data.py | 22 +++ embodichain/lab/expansion/_preview_heatmap.js | 27 ++-- embodichain/lab/expansion/_preview_heatmap.py | 53 +++----- examples/expansion/engine/ghost-preview.md | 10 +- .../expansion/ur5_pick_place/README.md | 4 +- .../ur5_pick_place/assets/object-heatmap.png | Bin 56301 -> 50385 bytes tests/lab/expansion/test_preview.py | 127 ++++++++++++------ 9 files changed, 160 insertions(+), 106 deletions(-) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index 3d698b19bc..b0572168a3 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -115,8 +115,10 @@ remain explicit. `_preview_deviations.py` reuses recorded world FK and gripper calibration for TCP errors. At each reference time it reports the minimum, mean and maximum across recordings still in range for TCP translation distance, TCP rotation angle and each episode's worst joint deviation. `_preview_heatmap.py` -counts distinct recordings per rigid object's measured XY cell, including the solid -reference, for the full recording and its first and last frame. The HTTP service +bins the measured first-frame XY of each rigid target in an `object_pose` input +episode's `joint_scene.pose_changes`. The recipe's selected motion operator takes +precedence over the job-level operator. The explicit reference belongs to replay. +The HTTP service publishes both chart datasets independently of the live image/state snapshots. FK and episode budgets bound preload, controls are queued for the render owner, and native resources/ports close on exit. See the example's `ghost-preview.md` for usage. diff --git a/embodichain/lab/expansion/_preview.html b/embodichain/lab/expansion/_preview.html index 9453f31c3a..a2a801f4fc 100644 --- a/embodichain/lab/expansion/_preview.html +++ b/embodichain/lab/expansion/_preview.html @@ -7,7 +7,7 @@ .controls-help{font-size:12px;color:#a8bacb}.controls-help kbd{font:inherit;border:1px solid #465363;border-radius:4px;padding:1px 4px} @media(max-width:850px){.chart-grid{grid-template-columns:1fr}.chart-grid section:has(.curve:only-of-type) canvas{height:150px}} .heatmap{grid-column:1/-1;min-width:0}.heatmap h2{font-size:18px;margin:0 0 6px}.heatmap-panel{margin-top:14px;display:grid;grid-template-columns:minmax(0,470px) minmax(200px,340px);gap:clamp(20px,6vw,90px);justify-content:center;align-items:center}.heatmap-panel[hidden]{display:none} -.heatmap canvas{display:block;width:100%;aspect-ratio:1;cursor:crosshair}.heatmap-controls{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.heatmap-controls label{display:grid;gap:6px}.heatmap-controls select{width:100%} +.heatmap canvas{display:block;width:100%;aspect-ratio:1;cursor:crosshair}.heatmap-controls{display:grid;gap:6px}.heatmap-controls select{width:100%} .heatmap dl{margin:18px 0;border-block:1px solid #384451}.heatmap dl div{display:flex;justify-content:space-between;align-items:baseline;gap:12px;padding:6px 0}.heatmap dt,.heatmap-legend{color:#a7b6c4}.heatmap dd{margin:0;font-variant-numeric:tabular-nums} .heatmap-scale{display:flex;height:12px;overflow:hidden;border-radius:3px;border:1px solid #465363;margin:7px 0 3px}.heatmap-scale i{flex:1}.heatmap-ticks{display:flex;justify-content:space-between;font-size:12px}.heatmap-readout{display:block;min-height:3.3em;margin-top:18px;color:#c9d4df;font-size:13px;line-height:1.6;font-variant-numeric:tabular-nums} @media(max-width:650px){.heatmap-panel{display:flex;flex-direction:column;align-items:stretch;gap:12px}.heatmap-controls{margin-top:2px}.heatmap canvas{align-self:center;max-width:450px}.heatmap-readout{min-height:3.2em}} @@ -35,22 +35,19 @@

    机械臂最大关节偏差

    -

    物体位置分布热力图

    -

    正在读取物体位置…

    +

    object_pose 物体起点分布

    +

    正在读取扩增起点…

    +
    +

    +

    + +
    + +
    + + + + + - + diff --git a/embodichain/lab/expansion/_preview_charts.js b/embodichain/lab/expansion/_preview_charts.js index ba150dfcec..65ad982d0d 100644 --- a/embodichain/lab/expansion/_preview_charts.js +++ b/embodichain/lab/expansion/_preview_charts.js @@ -17,8 +17,8 @@ const deviationCharts = (() => { const left = 48, right = 12, top = 8, bottom = 24; const plots = []; - let data, playbackFrame = 0, hoverFrame = null; - const number = new Intl.NumberFormat('zh-CN', {maximumSignificantDigits: 4}); + let data, playbackFrame = 0, hoverFrame = null, failed = false; + let number, tcpNote, jointNote; const description = document.getElementById('deviation-description'); const readout = document.getElementById('deviation-time'); @@ -27,14 +27,22 @@ const deviationCharts = (() => { const frame = hoverFrame ?? playbackFrame; const time = data.time_s[frame]; const fraction = time / data.time_s.at(-1); - readout.textContent = `${number.format(time)} s · ${data.count[frame]} / ${data.episodes} 条轨迹`; + readout.textContent = previewText('deviationTime', { + time: number.format(time), + count: data.count[frame], + total: data.episodes, + }); for (const plot of plots) { const value = plot.values[frame]; const format = v => `${number.format(v)} ${plot.unit}`; if (value === null) { - plot.value.textContent = '无样本'; + plot.value.textContent = previewText('deviationNoSample'); } else if (plot.range) { - plot.value.textContent = `最小 ${format(plot.range.min[frame])} · 均值 ${format(value)} · 最大 ${format(plot.range.max[frame])}`; + plot.value.textContent = previewText('deviationRange', { + min: format(plot.range.min[frame]), + mean: format(value), + max: format(plot.range.max[frame]), + }); } else { plot.value.textContent = format(value); } @@ -129,7 +137,7 @@ const deviationCharts = (() => { ctx.stroke(); } - function addCurve(panel, key, title, unit, color) { + function addCurve(panel, key, titleKey, unit, color) { const values = data.mean[key]; if (!values) return; const range = data.range?.[key]; @@ -137,21 +145,18 @@ const deviationCharts = (() => { figure.className = 'curve'; figure.style.setProperty('--line', color); const caption = document.createElement('figcaption'); const label = document.createElement('span'); - label.textContent = `${title}(${unit})`; const value = document.createElement('output'); caption.append(label, value); const area = document.createElement('div'); area.className = 'curve-plot'; const canvas = document.createElement('canvas'); canvas.setAttribute('role', 'img'); - const summary = range ? '均值曲线及最小值至最大值色带' : '均值曲线'; - canvas.setAttribute('aria-label', `${title}随实测时间的${summary},单位 ${unit}`); const cursor = document.createElement('i'); area.append(canvas, cursor); figure.append(caption, area); panel.append(figure); const peak = (range?.max ?? values).reduce((max, v) => v === null ? max : Math.max(max, v), 0); const step = tickStep(peak || 1); const ticks = Math.ceil((peak || 1) / step); - const plot = {values, value, range, unit, color, canvas, cursor, step, ticks, max: step * ticks}; + const plot = {values, value, range, titleKey, label, unit, color, canvas, cursor, step, ticks, max: step * ticks}; plots.push(plot); new ResizeObserver(() => draw(plot)).observe(canvas); canvas.addEventListener('pointermove', event => { @@ -162,36 +167,63 @@ const deviationCharts = (() => { canvas.addEventListener('pointerleave', () => { hoverFrame = null; updateReadout(); }); } + function renderLanguage() { + number = new Intl.NumberFormat(document.documentElement.lang, {maximumSignificantDigits: 4}); + if (failed || !data?.episodes) { + const key = failed ? 'deviationsFailed' : data ? 'deviationsEmpty' : 'deviationsLoading'; + description.textContent = previewText(key); + return; + } + description.textContent = previewText('deviationsHelp', { + reference: previewText(data.explicit_reference ? 'reference' : 'firstReference'), + count: data.episodes, + }); + if (Object.keys(data.range ?? {}).length) description.append(' ', previewText('deviationsBand')); + if (tcpNote) tcpNote.textContent = previewText('tcpUnavailable'); + if (jointNote) { + const separator = document.documentElement.lang === 'en' ? ', ' : '、'; + const names = Object.values(data.arm_joint_groups).flat(); + jointNote.textContent = names.length + ? previewText('jointNames', {names: names.join(separator)}) + : previewText('jointsUnavailable'); + } + for (const plot of plots) { + const values = {title: previewText(plot.titleKey), unit: plot.unit}; + plot.label.textContent = previewText('curveLabel', values); + plot.canvas.setAttribute('aria-label', previewText(plot.range ? 'curveWithBand' : 'curveMean', values)); + draw(plot); + } + updateReadout(); + } + async function load() { try { const response = await fetch('/deviations'); - if (!response.ok) throw Error('deviations'); + if (!response.ok) throw Error('Could not read deviations'); data = await response.json(); - if (!data.episodes) { - description.textContent = '当前只有对照轨迹。加入扩增轨迹即可显示偏差曲线。'; - return; + if (data.episodes) { + document.getElementById('deviation-panels').hidden = false; + const tcp = document.getElementById('tcp-deviations'); + addCurve(tcp, 'translation_mm', 'translationDistance', 'mm', '#80c7ff'); + addCurve(tcp, 'rotation_deg', 'rotationAngle', '°', '#e6af77'); + if (!data.mean.translation_mm) { + tcpNote = document.createElement('p'); + tcp.append(tcpNote); + } + const joints = document.getElementById('joint-deviations'); + addCurve(joints, 'qpos_deg', 'revoluteDeviation', '°', '#85d5b8'); + addCurve(joints, 'qpos_mm', 'prismaticDeviation', 'mm', '#c9a9f2'); + jointNote = document.createElement('p'); + joints.append(jointNote); } - const reference = data.explicit_reference ? '原始轨迹' : '首条对照记录'; - description.textContent = `相对${reference},按实测时间对齐全部 ${data.episodes} 条扩增轨迹。每个时刻只计仍有记录的轨迹。`; - if (Object.keys(data.range ?? {}).length) description.append('色带覆盖最小值至最大值,实线表示均值。'); - document.getElementById('deviation-panels').hidden = false; - const tcp = document.getElementById('tcp-deviations'); - addCurve(tcp, 'translation_mm', '平移距离', 'mm', '#80c7ff'); - addCurve(tcp, 'rotation_deg', '相对旋转角', '°', '#e6af77'); - if (!data.mean.translation_mm) tcp.append('记录中缺少所选机械臂的完整 TCP 标定。'); - const joints = document.getElementById('joint-deviations'); - addCurve(joints, 'qpos_deg', '转动关节最大绝对偏差', '°', '#85d5b8'); - addCurve(joints, 'qpos_mm', '移动关节最大绝对偏差', 'mm', '#c9a9f2'); - const names = Object.values(data.arm_joint_groups).flat(); - const note = document.createElement('p'); - note.textContent = names.length ? `统计关节 · ${names.join('、')}` : '记录中缺少可识别的机械臂关节组。'; - joints.append(note); - updateReadout(); } catch { - description.textContent = '偏差曲线加载失败,请刷新页面重试。'; + failed = true; } + renderLanguage(); } + document.addEventListener('preview-language-change', renderLanguage); + renderLanguage(); load(); return {setFrame(frame) { if (frame !== playbackFrame) { playbackFrame = frame; updateReadout(); } diff --git a/embodichain/lab/expansion/_preview_controls.js b/embodichain/lab/expansion/_preview_controls.js new file mode 100644 index 0000000000..9224f40336 --- /dev/null +++ b/embodichain/lab/expansion/_preview_controls.js @@ -0,0 +1,273 @@ +// ---------------------------------------------------------------------------- +// Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// ---------------------------------------------------------------------------- + +let status=null,busy=false,dragging=false,filterKey=null,initialized=false,sending=false; +const pending=[]; +const $=id=>document.getElementById(id); +const viewport = $('viewport'); +let videoConnectionFailed = false; +let video; +const recordedLabel = value => value === 'unrecorded' ? previewText('unrecorded') : value; +let connection = 'connecting'; +function setConnection(state) { + connection = state; + $('connection').textContent = previewText(state); + $('connection').classList.toggle('error', state === 'controlFailed' || state === 'disconnected'); +} +async function connectVideo() { + while (!window.RTC_SceneLeaving) { + try { + const description = await RTC_ReadSceneDescription(); + if (description.state === 'error' || !description.room || !description.sources?.length) { + throw Error('Native video source unavailable'); + } + const sources = description.sources; + await window.RTC_Run({ + Room: description.room, Role: 'offerer', Video: true, View: true, + TestPattern: false, Timeout: 30, Input: false, + InputStreams: sources.map(() => false), Cameras: sources.length, + FramesPerSecond: description.fps, BitrateBps: description.bitrate, + StreamNames: sources.map(source => source.name), + StreamSizes: sources.map(source => [source.width, source.height]), + }); + } catch { + // The page shows a localized reconnecting status below. + } + videoConnectionFailed = true; + await new Promise(resolve => setTimeout(resolve, 1000)); + } +} + +function updateVideo() { + const peer = window.RTC_ViewPeer; + const next = peer?.Videos[0]?.Element; + if (next && next !== video) { + video?.remove(); + video = next; + video.controls = false; + video.dataset.label = 'frameAlt'; + video.setAttribute('aria-label', previewText('frameAlt')); + viewport.insertBefore(video, $('caption')); + } + if (peer?.ViewReady && !peer.Stopped && video?.readyState >= 2) { + videoConnectionFailed = false; + return 'connected'; + } + return videoConnectionFailed ? 'reconnecting' : 'connecting'; +} + +function isDiscrete(update){return 'toggle_playback' in update || 'toggle_ghost' in update || 'ghosts' in update} +async function control(update) { + const last = pending.at(-1); + // Coalesce continuous controls, preserving individual clicks and their filters. + if (last && !isDiscrete(last) && !isDiscrete(update)) Object.assign(last, update); + else pending.push(update); + if (sending) return; + sending = true; + try { + while (pending.length) { + const peer = window.RTC_ViewPeer; + if (!peer?.ViewReady || peer.Stopped) throw Error('WebRTC viewer is not ready'); + // The native listener validates and strips these room credentials. + const body = {...pending.shift(), room: peer.Config.Room, token: peer.Token, after: peer.After}; + const response = await fetch('/api/command', { + method: 'POST', + headers: {'Content-Type': 'application/json'}, + body: JSON.stringify(body), + }); + if (!response.ok) throw Error('Preview control request failed'); + } + } catch { + pending.length = 0; + setConnection('controlFailed'); + } finally { + sending = false; + } +} +for(const k of ['space','aff','variant','align'])$(k).onchange=()=>control({[k]:$(k).value}); +for(const k of ['ghosts','paths','targets','positions'])$(k).onchange=()=>control({[k]:$(k).checked}); +$('play').onclick=()=>control({toggle_playback:true}); +$('reset').onclick=()=>control({progress:0,playing:false}); +document.addEventListener('keydown',event=>{ + if((event.code!=='Space' && event.key!==' ') || event.defaultPrevented || event.isComposing || + event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)return; + if(event.target.isContentEditable || event.target.closest?.('select, textarea, input:not([type="range"]), summary'))return; + event.preventDefault(); + if(!event.repeat)$('play').click(); +}); +$('progress').onpointerdown=()=>dragging=true;$('progress').oninput=()=>control({progress:+$('progress').value/1000,playing:false});window.addEventListener('pointerup',()=>dragging=false); +const cameras={orbit:{yaw:-2.15,elevation:.55,distance:1.65},top:{yaw:-1.57,elevation:1.48,distance:1.5},front:{yaw:-1.57,elevation:.2,distance:1.5},close:{yaw:-2.15,elevation:.7,distance:.85}}; +$('camera').onchange=()=>{if(cameras[$('camera').value])control(cameras[$('camera').value])}; +let pointer = null; +viewport.onpointerdown = event => { + if (!status) return; + pointer = {x: event.clientX, y: event.clientY, yaw: status.yaw, elevation: status.elevation}; + viewport.setPointerCapture(event.pointerId); +}; +viewport.onpointermove = event => { + if (pointer) control({ + yaw: Math.max(-20, Math.min(20, pointer.yaw - (event.clientX - pointer.x) * .008)), + elevation: Math.max(.1, Math.min(1.5, pointer.elevation + (event.clientY - pointer.y) * .006)), + }); +}; +viewport.onpointerup = viewport.onpointercancel = () => { pointer = null; }; +viewport.addEventListener('wheel', event => { + event.preventDefault(); + if (status) control({distance: Math.max(.2, Math.min(20, status.distance + event.deltaY * .001))}); +}, {passive: false}); +function updateCandidates(s){ + const list=$('candidates'); + const key=s.visible.join(','); + if(key!==filterKey){ + filterKey=key; + const buttons=s.clips.filter(c=>s.visible.includes(c.index)).map(c=>{ + const button=document.createElement('button'); + button.type='button'; + button.dataset.index=c.index; + button.textContent=c.label; + const details=document.createElement('small'); + details.textContent = previewText('candidateInfo', { + space: c.space, + aff: recordedLabel(c.aff), + variant: recordedLabel(c.variant), + }); + button.append(details); + button.onclick=()=>control({toggle_ghost:c.index}); + return button; + }); + list.replaceChildren(...buttons); + } + const shown=new Set(s.visible_ghosts); + for(const button of list.children){ + const pressed=shown.has(Number(button.dataset.index)); + button.classList.toggle('active',pressed); + button.setAttribute('aria-pressed',String(pressed)); + } + const all=$('ghosts'); + all.disabled=s.count===0; + all.checked=s.count>0 && shown.size===s.count; + all.indeterminate=shown.size>0 && !all.checked; +} +function renderCoverage(coverage) { + $('coverage-panel').hidden = false; + $('coverage-summary').textContent = previewText('coverageCounts', { + planned: coverage.planned_attempts, + attempted: coverage.records.reduce((count, record) => count + record.attempts, 0), + confirmed: coverage.records.reduce((count, record) => count + record.confirmed, 0), + result: previewText(coverage.coverage_complete ? 'coverageComplete' : 'coverageIncomplete'), + }); + const axes = coverage.axes.map(axis => `${axis.name}: [${axis.lower}, ${axis.upper}]`); + const records = coverage.records.map(record => { + const summary = previewText('coverageRecord', { + ...record, + planned: record.planned ?? coverage.recipes_per_point, + }); + const values = Object.entries(record.values).map(([name, value]) => `${name}=${Number(value).toPrecision(4)}`); + return `${summary}\n${values.join(', ')}`; + }); + $('coverage-details').style.whiteSpace = 'pre-line'; + $('coverage-details').textContent = [previewText('coverageScope'), axes.join('\n'), records.join('\n\n')].join('\n\n'); +} + +function renderReplayText() { + setConnection(connection); + $('play').textContent = previewText(status?.playing ? 'pause' : 'play'); + if (!status) { + $('caption').textContent = previewText('loadingModel'); + $('detail').textContent = previewText('waitingResults'); + return; + } + + const reference = status.has_reference + ? previewText('reference') + : previewText('firstRecording', {label: status.label}); + $('total').textContent = previewText('matchingTotal', {total: status.total}); + $('clock').textContent = previewText('clock', { + time: status.time.toFixed(2), + frame: status.source_frame, + last: status.source_frames - 1, + }); + $('phase').textContent = recordedLabel(status.phase); + $('caption').textContent = previewText('caption', {reference, count: status.visible_ghosts.length}); + $('detail').textContent = previewText('executionDetail', { + reference, + candidate: recordedLabel(status.candidate), + steps: status.physics_steps, + episode: status.episode, + }); +} + +function populateFilters(s) { + for (const key of ['space', 'aff', 'variant']) { + for (const value of s.options[key]) { + const option = new Option(recordedLabel(value), value); + if (value === 'unrecorded') option.dataset.text = 'unrecorded'; + $(key).append(option); + } + } + if (!s.options.align.includes('phase')) $('align').querySelector('[value="phase"]').remove(); +} + +async function poll() { + if (busy || document.hidden) return; + busy = true; + try { + const response = await fetch('/api/state', {cache: 'no-store'}); + if (!response.ok) throw Error('Could not read replay state'); + const s = await response.json(); + if (s.frame === undefined) return; + status = s; + if (!initialized) { + populateFilters(s); + if (s.coverage) renderCoverage(s.coverage); + initialized = true; + } + if (!sending) { + for (const key of ['space', 'aff', 'variant', 'align']) { + if (document.activeElement !== $(key)) $(key).value = s[key]; + } + for (const key of ['paths', 'targets', 'positions']) $(key).checked = s[key]; + if (document.activeElement !== $('camera')) { + $('camera').value = Object.keys(cameras).find(key => + Object.keys(cameras[key]).every(axis => Math.abs(s[axis] - cameras[key][axis]) < .001) + ) || 'custom'; + } + } + connection = updateVideo(); + renderReplayText(); + $('count').textContent = s.count; + if (!dragging) $('progress').value = Math.round(s.progress * 1000); + updateCandidates(s); + deviationCharts.setFrame(s.source_frame); + } catch { + setConnection('disconnected'); + } finally { + busy = false; + } +} + +document.addEventListener('preview-language-change', () => { + renderReplayText(); + if (status) { + filterKey = null; + updateCandidates(status); + if (status.coverage) renderCoverage(status.coverage); + } +}); +renderReplayText(); +connectVideo(); +setInterval(poll, 100); +poll(); diff --git a/embodichain/lab/expansion/_preview_heatmap.js b/embodichain/lab/expansion/_preview_heatmap.js index 09b34646a5..616c27bb12 100644 --- a/embodichain/lab/expansion/_preview_heatmap.js +++ b/embodichain/lab/expansion/_preview_heatmap.js @@ -19,17 +19,19 @@ const canvas = element('plot'); const ctx = canvas.getContext('2d'); const objectSelect = element('object'); - const millimeters = new Intl.NumberFormat('zh-CN', {maximumSignificantDigits: 4}); const peak = counts => Math.max(...counts.map(row => Math.max(...row))); - let data, object, view, xAxis, yAxis, colors, area, cell = null; + let data, object, view, xAxis, yAxis, colors, area, cell = null, failed = false; function axisScale(edges) { const bins = edges.length - 1; const step = (edges[bins] - edges[0]) / bins; const digits = Math.min(20, Math.max(0, 1 - Math.floor(Math.log10(step)))); - const number = new Intl.NumberFormat('zh-CN', {maximumFractionDigits: digits, useGrouping: false}); + const number = new Intl.NumberFormat(document.documentElement.lang, { + maximumFractionDigits: digits, + useGrouping: false, + }); const ticks = [0, 0.25, 0.5, 0.75, 1].map(t => number.format(edges[Math.round(t * bins)])); - const meters = (a, b) => `${number.format(a)} ~ ${number.format(b)} m`; + const meters = (a, b) => previewText('meters', {low: number.format(a), high: number.format(b)}); return {step, ticks, meters}; } @@ -108,27 +110,48 @@ function reportCell() { const output = element('cell'); if (!cell) { - output.textContent = '指向或轻点网格,查看该位置的坐标和轨迹数。'; + output.textContent = previewText('heatmapInspect'); return; } const {row, col} = cell; const x = object.x_edges_m, y = object.y_edges_m; - output.textContent = `起点 ${view.counts[row][col]} / ${object.episodes} 条轨迹 · X ${xAxis.meters(x[col], x[col + 1])} · Y ${yAxis.meters(y[row], y[row + 1])}`; + output.textContent = previewText('heatmapCell', { + count: view.counts[row][col], + total: object.episodes, + x: xAxis.meters(x[col], x[col + 1]), + y: yAxis.meters(y[row], y[row + 1]), + }); } - function selectObject() { - object = data.objects[objectSelect.selectedIndex]; - view = object.views.start; + function renderLanguage() { + const description = element('description'); + if (failed || !object) { + const key = failed ? 'heatmapFailed' : data ? 'heatmapEmpty' : 'heatmapLoading'; + description.textContent = previewText(key); + return; + } xAxis = axisScale(object.x_edges_m); yAxis = axisScale(object.y_edges_m); - cell = null; - element('description').textContent = `${object.episodes} 条 object_pose 扩增轨迹记录了 ${object.uid} 的起点。X、Y 轴按各自的首帧实测范围缩放。`; + description.textContent = previewText('heatmapHelp', {count: object.episodes, object: object.uid}); const [low, high] = view.bounds_m; - element('x').textContent = xAxis.meters(low[0], high[0]); - element('y').textContent = yAxis.meters(low[1], high[1]); + const x = xAxis.meters(low[0], high[0]); + const y = yAxis.meters(low[1], high[1]); + const millimeters = new Intl.NumberFormat(document.documentElement.lang, {maximumSignificantDigits: 4}); + element('x').textContent = x; + element('y').textContent = y; element('step').textContent = `${millimeters.format(xAxis.step * 1000)} × ${millimeters.format(yAxis.step * 1000)} mm`; const max = peak(view.counts); - element('peak').textContent = `${max} / ${object.episodes} 条`; + element('peak').textContent = previewText('heatmapPeak', {max, total: object.episodes}); + canvas.setAttribute('aria-label', previewText('heatmapAlt', {object: object.uid, x, y, max})); + reportCell(); + draw(); + } + + function selectObject() { + object = data.objects[objectSelect.selectedIndex]; + view = object.views.start; + cell = null; + const max = peak(view.counts); colors = colorScale(max); element('scale-max').textContent = max; element('scale').replaceChildren(...colors.map(color => { @@ -136,9 +159,7 @@ swatch.style.backgroundColor = color; return swatch; })); - canvas.setAttribute('aria-label', `${object.uid} 扩增起点 · X ${xAxis.meters(low[0], high[0])} · Y ${yAxis.meters(low[1], high[1])} · 单格最多 ${max} 条轨迹`); - reportCell(); - draw(); + renderLanguage(); } function inspect(event) { @@ -165,21 +186,23 @@ new ResizeObserver(draw).observe(canvas); async function load() { - const description = element('description'); try { const response = await fetch('/object-heatmaps'); - if (!response.ok) throw Error('heatmaps'); + if (!response.ok) throw Error('Could not read starting positions'); data = await response.json(); - if (!data.objects.length) { - description.textContent = '当前输入中没有记录 object_pose 扩增物体的起点。'; + if (data.objects.length) { + for (const item of data.objects) objectSelect.add(new Option(item.uid, item.uid)); + element('panel').hidden = false; + selectObject(); return; } - for (const item of data.objects) objectSelect.add(new Option(item.uid, item.uid)); - element('panel').hidden = false; - selectObject(); } catch { - description.textContent = '扩增起点加载失败,请刷新页面重试。'; + failed = true; } + renderLanguage(); } + + document.addEventListener('preview-language-change', renderLanguage); + renderLanguage(); load(); })(); diff --git a/embodichain/lab/expansion/_preview_render.py b/embodichain/lab/expansion/_preview_render.py index f48b00a3e3..1f2c7c4098 100644 --- a/embodichain/lab/expansion/_preview_render.py +++ b/embodichain/lab/expansion/_preview_render.py @@ -21,11 +21,9 @@ from contextlib import contextmanager from collections.abc import Iterator from typing import Any -import io import math import numpy as np from scipy.spatial.transform import Rotation -from PIL import Image from ._preview_data import PreviewData, PreviewState, pose_matrix __all__: list[str] = [] @@ -247,11 +245,7 @@ def markers(name: str, shapes: dict) -> Any: np.asarray(points).reshape(-1, 3), marker_indices=np.asarray(types, dtype=int), ) - self.camera = scene.add_camera( - spawn.CameraDesc(name="expansion_preview_camera", resolution=(1100, 760)) - ) - self.camera.open_camera() - self.camera.set_visual_overlay_enabled(True) + self.web_viewer = sim.viewer publisher.publish(preload=True) def _object_prototype(self, uid: str, **appearance: Any) -> Any: @@ -264,7 +258,7 @@ def _object_prototype(self, uid: str, **appearance: Any) -> Any: ) return MarkerPrototypeCfg(shape="box", scale=self.data.boxes[uid], **appearance) - def draw(self, state: PreviewState) -> bytes: + def draw(self, state: PreviewState) -> None: v = state.values solid = self.data.solid_clip visible = state.visible_ghosts() @@ -362,17 +356,13 @@ def draw(self, state: PreviewState) -> bytes: eye = self.center + d * np.array( [math.cos(e) * math.cos(yaw), math.cos(e) * math.sin(yaw), math.sin(e)] ) - self.camera.look_at(eye.tolist(), self.center.tolist(), [0, 0, 1]) - with self.sim.render_frame(capture_camera_images=False): - self.sim.sync_render_state() - self.camera.render() + self.web_viewer.set_look_at(eye.tolist(), self.center.tolist()) + if not self.sim.capture_visualization(force=True, capture_camera_images=False): + raise RuntimeError( + f"WebRTC observer did not render: {self.web_viewer.error}" + ) if self.sim.physics_step_index != self.step: raise RuntimeError("Preview unexpectedly advanced physics") - image = Image.fromarray( - np.ascontiguousarray(self.camera.get_rgb_map()[..., :3], dtype=np.uint8) - ) - buffer = io.BytesIO() - image.save(buffer, format="JPEG", quality=88) self.stats = { "physics_steps": self.sim.physics_step_index - self.step, "ghost_count": len(visible), @@ -381,17 +371,19 @@ def draw(self, state: PreviewState) -> bytes: "scene_objects": len(self.data.boxes), "fixed_backgrounds": len(self.backgrounds), } - return buffer.getvalue() @contextmanager -def native_renderer(data: PreviewData, gpu: int = 0) -> Iterator[NativeRenderer]: +def native_renderer( + data: PreviewData, gpu: int = 0, *, web_port: int +) -> Iterator[NativeRenderer]: import os os.environ.setdefault("SDL_VIDEODRIVER", "offscreen") import torch from embodichain.lab.sim import SimulationManager, SimulationManagerCfg from embodichain.lab.sim.cfg import RenderCfg, DenoisingCfg + from embodichain.lab.visualization import DexSimWebCfg, VisualizationCfg from embodichain.lab.visualization.markers import MarkerFramePublisher torch.set_num_threads(1) @@ -404,6 +396,10 @@ def native_renderer(data: PreviewData, gpu: int = 0) -> Iterator[NativeRenderer] num_envs=1, enable_entity_gizmo=False, startup_summary="off", + web=True, + visualization=VisualizationCfg( + web=DexSimWebCfg(port=web_port, width=1100, height=760, fps=25) + ), render_cfg=RenderCfg( renderer="hybrid", spp=4, diff --git a/embodichain/lab/expansion/_preview_server.py b/embodichain/lab/expansion/_preview_server.py index 1390189cf2..a53c875591 100644 --- a/embodichain/lab/expansion/_preview_server.py +++ b/embodichain/lab/expansion/_preview_server.py @@ -14,137 +14,94 @@ # limitations under the License. # ---------------------------------------------------------------------------- -"""Loopback-only native preview transport. WebRTC integration remains a TODO.""" +"""Serve recorded expansion playback through the native WebRTC viewport.""" from __future__ import annotations -import base64 +from collections import deque import json -import queue -import threading +import socket import time import webbrowser -from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path -from typing import Any -from urllib.parse import urlsplit +from typing import TYPE_CHECKING from ._preview_data import PreviewData, PreviewState from ._preview_heatmap import object_heatmaps +if TYPE_CHECKING: + from embodichain.lab.visualization._web_viewer import _WebViewer + __all__: list[str] = [] -class PreviewTransport: - def __init__(self, state: PreviewState, port: int) -> None: +def _json(value: object) -> str: + return json.dumps(value, allow_nan=False, separators=(",", ":")) + + +def _assets(data: PreviewData) -> dict[str, tuple[str, bytes]]: + static = { + route: (mime, Path(__file__).with_name(filename).read_bytes()) + for route, filename, mime in ( + ("/", "_preview.html", "text/html; charset=utf-8"), + ("/preview.css", "_preview.css", "text/css; charset=utf-8"), + ("/preview-text.js", "_preview_text.js", "text/javascript; charset=utf-8"), + ( + "/preview-controls.js", + "_preview_controls.js", + "text/javascript; charset=utf-8", + ), + ( + "/preview-charts.js", + "_preview_charts.js", + "text/javascript; charset=utf-8", + ), + ( + "/preview-heatmap.js", + "_preview_heatmap.js", + "text/javascript; charset=utf-8", + ), + ) + } + static["/object-heatmaps"] = ( + "application/json", + _json(object_heatmaps(data)).encode(), + ) + return static + + +class _WebPreviewTransport: + """Serve replay controls and statistics over the native video listener.""" + + def __init__( + self, state: PreviewState, viewer: _WebViewer, deviations: bytes + ) -> None: self.state = state - self.commands: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=64) - self.lock = threading.Lock() - self.status: dict[str, Any] = {} - self.jpeg = b"" - self.snapshot = b"{}" - self.deviations = b"{}" - html = Path(__file__).with_name("_preview.html").read_bytes() - charts_js = Path(__file__).with_name("_preview_charts.js").read_bytes() - heatmap_js = Path(__file__).with_name("_preview_heatmap.js").read_bytes() - heatmaps = json.dumps( - object_heatmaps(state.data), allow_nan=False, separators=(",", ":") - ).encode() - owner = self - - class Handler(BaseHTTPRequestHandler): - def setup(self) -> None: - super().setup() - self.connection.settimeout(3) - - def log_message(self, *_: object) -> None: - pass - - def do_GET(self) -> None: - if urlsplit("//" + self.headers.get("Host", "")).hostname not in { - "127.0.0.1", - "localhost", - "::1", - }: - self.send_error(403) - return - route = self.path.split("?")[0] - with owner.lock: - if route == "/": - data, kind = html, "text/html; charset=utf-8" - elif route == "/preview-charts.js": - data, kind = charts_js, "text/javascript; charset=utf-8" - elif route == "/preview-heatmap.js": - data, kind = heatmap_js, "text/javascript; charset=utf-8" - elif route == "/object-heatmaps": - data, kind = heatmaps, "application/json" - elif route == "/state": - data, kind = ( - json.dumps(owner.status, allow_nan=False).encode(), - "application/json", - ) - elif route == "/snapshot": - data, kind = owner.snapshot, "application/json" - elif route == "/deviations": - data, kind = owner.deviations, "application/json" - elif route == "/frame.jpg": - data, kind = owner.jpeg, "image/jpeg" - else: - self.send_error(404) - return - self.send_response(200) - self.send_header("Content-Type", kind) - self.send_header("Cache-Control", "no-store") - self.send_header("X-Content-Type-Options", "nosniff") - self.send_header("Content-Length", str(len(data))) - self.end_headers() - try: - self.wfile.write(data) - except (BrokenPipeError, ConnectionResetError): - pass - - def do_POST(self) -> None: - if self.path != "/control": - self.send_error(404) - return - origin = self.headers.get("Origin") - host = self.headers.get("Host", "") - # Same-origin loopback controls also work through a different forwarded port. - if ( - urlsplit("//" + host).hostname - not in {"127.0.0.1", "localhost", "::1"} - or self.headers.get("Content-Type") != "application/json" - or (origin and origin != "http://" + host) - ): - self.send_error(403) - return - try: - size = int(self.headers.get("Content-Length", "0")) - if not 0 < size <= 4096: - raise ValueError("control size") - update = owner.state.validate(json.loads(self.rfile.read(size))) - owner.commands.put_nowait(update) - except (ValueError, TypeError, queue.Full, TimeoutError): - self.send_error(400) - return - self.send_response(204) - self.end_headers() - - self.server = ThreadingHTTPServer(("127.0.0.1", port), Handler) - self.server.daemon_threads = True - self.url = f"http://127.0.0.1:{self.server.server_port}/" - - def publish(self, status: dict[str, Any], jpeg: bytes) -> None: - snapshot = json.dumps( - { - **status, - "image": "data:image/jpeg;base64," + base64.b64encode(jpeg).decode(), - }, - allow_nan=False, - ).encode() - with self.lock: - self.status = status - self.jpeg = jpeg - self.snapshot = snapshot + self.commands: deque[dict[str, object]] = deque() + self.url = viewer.endpoint + self.status = "{}" + assets = _assets(state.data) + assets["/deviations"] = ("application/json", deviations) + viewer._replace_application(assets, self._request) + + def _request(self, path: str, raw: str) -> tuple[int, str]: + if path == "/api/state": + return 200, self.status + if path != "/api/command": + return 404, '{"error":"unknown route"}' + # DexSim has already checked same-origin and the current viewer token. + if len(self.commands) >= 64: + return 429, '{"error":"replay control queue is full"}' + try: + if len(raw) > 4096: + raise ValueError("control size") + update = self.state.validate(json.loads(raw)) + except (ValueError, TypeError): + return 400, '{"error":"invalid replay control"}' + self.commands.append(update) + return 200, "{}" + + def publish(self, status: dict[str, object]) -> None: + self.status = _json(status) def serve_preview( @@ -155,79 +112,77 @@ def serve_preview( open_browser: bool = False, duration: float = 0, ) -> None: + """Replay confirmed episodes in a browser using the native observer.""" from ._preview_deviations import deviation_curves from ._preview_render import native_renderer - state = PreviewState(data) - transport = PreviewTransport(state, port) - thread = None - try: - with native_renderer(data, gpu) as renderer: - transport.deviations = json.dumps( - deviation_curves(data, renderer.link_names), - allow_nan=False, - separators=(",", ":"), - ).encode() - frame = 0 - - def publish() -> None: - nonlocal frame - jpeg = renderer.draw(state) - transport.publish( - { - **state.snapshot(), - **renderer.stats, - "frame": frame, - "renderer": "EmbodiChain / DexSim Hybrid + OptiX", - "transport": "HTTP JPEG", - }, - jpeg, - ) - frame += 1 + if port == 0: + # The native World configuration requires a concrete listening port. + with socket.socket() as probe: + probe.bind(("0.0.0.0", 0)) + port = probe.getsockname()[1] - publish() - thread = threading.Thread( - target=transport.server.serve_forever, daemon=True - ) - thread.start() - print( - json.dumps( - { - "state": "ready", - "url": transport.url, - "episodes": len(data.clips), - "physics_steps": 0, - "transport": "HTTP JPEG", - } - ), - flush=True, + state = PreviewState(data) + with native_renderer(data, gpu, web_port=port) as renderer: + viewer = renderer.web_viewer + deviations = _json(deviation_curves(data, renderer.link_names)).encode() + transport = _WebPreviewTransport(state, viewer, deviations) + frame_period = 1 / viewer.cfg.fps + frame = 0 + + def publish() -> None: + nonlocal frame + renderer.draw(state) + transport.publish( + { + **state.snapshot(), + **renderer.stats, + "frame": frame, + "transport": "WebRTC", + } ) - if open_browser: - webbrowser.open(transport.url) - start = last = time.monotonic() - while not duration or time.monotonic() - start < duration: - now = time.monotonic() - elapsed = now - last - last = now + frame += 1 + + publish() + print( + json.dumps( + { + "state": "ready", + "url": transport.url, + "episodes": len(data.clips), + "physics_steps": 0, + "transport": "WebRTC", + } + ), + flush=True, + ) + if open_browser: + webbrowser.open(transport.url) + + start = last = next_frame = time.monotonic() + next_idle_frame = start + 0.25 + dirty = False + while not duration or time.monotonic() - start < duration: + now = time.monotonic() + elapsed = now - last + last = now + while transport.commands: + state.apply(transport.commands.popleft()) + dirty = True + if state.values["playing"]: + state.values["progress"] = min( + 1.0, state.values["progress"] + elapsed / state.duration + ) + if state.values["progress"] >= 1: + state.values["playing"] = False + dirty = True + if now >= next_frame and (dirty or now >= next_idle_frame): + # Capturing the native observer also services its app requests. + publish() dirty = False - while True: - try: - state.apply(transport.commands.get_nowait()) - dirty = True - except queue.Empty: - break - if state.values["playing"]: - state.values["progress"] = min( - 1.0, state.values["progress"] + elapsed / state.duration - ) - if state.values["progress"] >= 1: - state.values["playing"] = False - dirty = True - if dirty: - publish() - time.sleep(max(0.01, 0.1 - (time.monotonic() - now))) - finally: - if thread is not None: - transport.server.shutdown() - thread.join(timeout=5) - transport.server.server_close() + next_frame = now + frame_period + next_idle_frame = now + 0.25 + else: + viewer._process_application_requests() + wait = min(0.01, next_frame - time.monotonic()) if dirty else 0.01 + time.sleep(max(0.001, wait)) diff --git a/embodichain/lab/expansion/_preview_text.js b/embodichain/lab/expansion/_preview_text.js new file mode 100644 index 0000000000..6f0a99b498 --- /dev/null +++ b/embodichain/lab/expansion/_preview_text.js @@ -0,0 +1,147 @@ +// ---------------------------------------------------------------------------- +// Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// ---------------------------------------------------------------------------- + +const previewText = (() => { + // Keep labels and runtime messages together. Recorded IDs are passed as values. + const messages = { + title: ['EmbodiChain · 扩增结果回放', 'EmbodiChain · Expansion replay'], + subtitle: ['完整模型虚影 · 已确认的真实扩增结果', 'Full-model overlays of confirmed expansion recordings'], + language: ['语言', 'Language'], + disconnected: ['渲染服务未连接', 'Renderer disconnected'], + connected: ['● 原生视频 · WebRTC', '● Native video · WebRTC'], + connecting: ['正在连接 WebRTC 视频…', 'Connecting WebRTC video…'], + reconnecting: ['WebRTC 视频连接失败,正在重试…', 'WebRTC video unavailable. Reconnecting…'], + controlFailed: ['控制未成功应用', 'Could not apply replay control'], + play: ['播放', 'Play'], + pause: ['暂停', 'Pause'], + reset: ['回到起点', 'Back to start'], + alignment: ['对齐方式', 'Alignment'], + alignPhase: ['按动作阶段对齐', 'Align by motion phase'], + alignTime: ['按真实时间对齐', 'Align by recorded time'], + camera: ['观察视角', 'Camera view'], + cameraCustom: ['自由视角', 'Free view'], + cameraOrbit: ['斜视', 'Orbit view'], + cameraTop: ['俯视', 'Top view'], + cameraSide: ['侧视', 'Side view'], + cameraClose: ['抓取区域近景', 'Grasp close-up'], + spaceKey: ['空格', 'Space'], + controlsHelp: ['播放 / 暂停 · 拖动画面旋转 · 滚轮缩放', 'Play / pause · Drag to rotate · Scroll to zoom'], + frameAlt: ['EmbodiChain 原生场景渲染画面', 'Native EmbodiChain scene rendering'], + loadingModel: ['正在加载完整机器人模型…', 'Loading the full robot model…'], + progress: ['回放进度', 'Playback progress'], + coverageTitle: ['采样覆盖 · 包含未通过点', 'Sampling coverage, including unqualified points'], + coverageDetails: ['边界与样本明细', 'Bounds and sample details'], + coverageCounts: ['计划 {planned} · 已尝试 {attempted} · 已确认 {confirmed}。{result}', + 'Planned {planned} · Attempted {attempted} · Confirmed {confirmed}. {result}'], + coverageComplete: ['全部计划样本已确认', 'All planned samples confirmed.'], + coverageIncomplete: ['包含未通过、回退或未执行点', 'Includes rejected, fallback or unrun points.'], + coverageScope: ['有限参数采样,不代表连续空间或全部边界组合穷举。', + 'This finite sample covers selected parameter points.'], + coverageRecord: ['#{index} {role} · {status} · {confirmed}/{planned} 确认', + '#{index} {role} · {status} · {confirmed}/{planned} confirmed'], + filters: ['分布筛选 · 三维联动', 'Filter 3D overlays'], + layoutGroup: ['参数组', 'Layout group'], + allSpaces: ['全部空间组', 'All layout groups'], + affordance: ['抓取分支', 'Affordance'], + allAffordances: ['全部抓取分支', 'All grasp branches'], + trajectory: ['轨迹', 'Trajectory'], + allVariants: ['全部变体', 'All variants'], + matching: [' 条符合筛选', ' matching'], + matchingTotal: [' / {total} 条符合筛选', ' / {total} matching'], + unrecorded: ['未记录', 'Unrecorded'], + candidateInfo: ['{space} · 抓取 {aff} · 变体 {variant}', '{space} · Grasp {aff} · Variant {variant}'], + layers: ['场景图层', 'Scene layers'], + showGhosts: ['显示全部匹配虚影', 'Show all matching overlays'], + showPaths: ['末端轨迹线', 'End-effector paths'], + showTargets: ['抓取目标坐标轴', 'Grasp target axes'], + showPositions: ['初始空间位置', 'Initial positions'], + layersHelp: ['实色模型始终播放固定对照。点击轨迹按钮可分别显示或隐藏对应的虚影。', + 'The solid model follows the reference. Click a trajectory button to toggle its overlay.'], + execution: ['真实执行记录', 'Recorded execution'], + waitingResults: ['等待渲染结果…', 'Waiting for the first rendered frame…'], + reference: ['原始轨迹', 'Original trajectory'], + firstReference: ['首条对照记录', 'First recording'], + firstRecording: ['首条记录 {label}(固定对照)', 'First recording {label} (fixed reference)'], + clock: ['{time} s · 记录帧 {frame} / {last}', '{time} s · Recorded frame {frame} / {last}'], + caption: ['{reference} · {count} 条扩增虚影', '{reference} · Overlays shown: {count}'], + executionDetail: ['{reference} · 已通过验收\n抓取候选 {candidate} · 物理推进 {steps} 步\n{episode}', + '{reference} · Accepted\nGrasp candidate: {candidate} · Physics steps: {steps}\n{episode}'], + deviations: ['扩增轨迹偏差', 'Expansion trajectory deviations'], + deviationsLoading: ['正在读取统计曲线…', 'Loading deviation curves…'], + deviationsEmpty: ['当前只有对照轨迹。加入扩增轨迹即可显示偏差曲线。', + 'Only the reference is available. Add expanded trajectories to display deviation curves.'], + deviationsFailed: ['偏差曲线加载失败,请刷新页面重试。', 'Could not load deviation curves. Refresh to try again.'], + deviationsHelp: ['相对{reference},按实测时间对齐全部 {count} 条扩增轨迹。每个时刻只计仍有记录的轨迹。', + 'All {count} expanded trajectories are aligned to the {reference} by recorded time. Each time uses trajectories with data at that point.'], + deviationsBand: ['色带覆盖最小值至最大值,实线表示均值。', 'The band spans the minimum to maximum. The line shows the mean.'], + deviationTime: ['{time} s · {count} / {total} 条轨迹', '{time} s · Trajectories: {count} / {total}'], + deviationRange: ['最小 {min} · 均值 {mean} · 最大 {max}', 'Min {min} · Mean {mean} · Max {max}'], + deviationNoSample: ['无样本', 'No samples'], + tcpDeviations: ['TCP 位姿偏差', 'TCP pose deviation'], + jointDeviations: ['机械臂最大关节偏差', 'Maximum arm joint deviation'], + translationDistance: ['平移距离', 'Translation distance'], + rotationAngle: ['相对旋转角', 'Relative rotation angle'], + revoluteDeviation: ['转动关节最大绝对偏差', 'Maximum absolute revolute-joint deviation'], + prismaticDeviation: ['移动关节最大绝对偏差', 'Maximum absolute prismatic-joint deviation'], + curveLabel: ['{title}({unit})', '{title} ({unit})'], + curveWithBand: ['{title}随实测时间的均值曲线及最小值至最大值色带,单位 {unit}', + '{title} over recorded time, with mean and minimum-to-maximum range, in {unit}'], + curveMean: ['{title}随实测时间的均值曲线,单位 {unit}', '{title} mean over recorded time, in {unit}'], + tcpUnavailable: ['记录中缺少所选机械臂的完整 TCP 标定。', 'The selected arm has incomplete TCP calibration in the recordings.'], + jointsUnavailable: ['记录中缺少可识别的机械臂关节组。', 'The recordings do not identify an arm joint group.'], + jointNames: ['统计关节 · {names}', 'Included joints · {names}'], + heatmapTitle: ['object_pose 物体起点分布', 'object_pose starting positions'], + heatmapLoading: ['正在读取扩增起点…', 'Loading starting positions…'], + heatmapEmpty: ['当前输入中没有记录 object_pose 扩增物体的起点。', + 'The inputs contain no recorded object_pose starting positions.'], + heatmapFailed: ['扩增起点加载失败,请刷新页面重试。', 'Could not load starting positions. Refresh to try again.'], + heatmapObject: ['扩增物体', 'Expanded object'], + heatmapX: ['实测 X 范围', 'Recorded X range'], + heatmapY: ['实测 Y 范围', 'Recorded Y range'], + heatmapCellSize: ['单格尺寸(X × Y)', 'Cell size (X × Y)'], + heatmapMostVisited: ['单格最多轨迹', 'Most trajectories in one cell'], + heatmapLegend: ['起点落入该格的轨迹数', 'Trajectories starting in each cell'], + heatmapInspect: ['指向或轻点网格,查看该位置的坐标和轨迹数。', 'Hover or tap a cell to see its coordinates and count.'], + heatmapCell: ['起点 {count} / {total} 条轨迹 · X {x} · Y {y}', 'Starts: {count} / {total} trajectories · X {x} · Y {y}'], + heatmapHelp: ['{count} 条 object_pose 扩增轨迹记录了 {object} 的起点。X、Y 轴按各自的首帧实测范围缩放。', + 'The starting positions of {object} come from {count} object_pose trajectories. Each axis fits its recorded first-frame range.'], + heatmapPeak: ['{max} / {total} 条', '{max} / {total}'], + heatmapAlt: ['{object} 扩增起点 · X {x} · Y {y} · 单格最多 {max} 条轨迹', + '{object} starting positions · X {x} · Y {y} · Most trajectories in one cell: {max}'], + meters: ['{low} ~ {high} m', '{low} to {high} m'], + footer: ['EmbodiChain SimulationManager / RobotMarkers / VisualizationMarkers → DexSim Hybrid 原生渲染。仅回放,物理推进 0 步。机器人与物体使用逐帧记录;轨迹线每 4 帧取点并连接。视角、灯光与透明材质仅用于验收展示。', + 'Native DexSim Hybrid rendering through EmbodiChain. Replay advances physics by zero steps. Robot and object states come from recorded frames. Path lines connect every fourth frame. Camera, lighting and transparency are for display.'], + }; + const language = document.getElementById('language'); + function t(key, values = {}) { + const message = messages[key][language.value === 'en' ? 1 : 0]; + return message.replace(/\{(\w+)\}/g, (_, name) => values[name]); + } + function applyLanguage() { + document.documentElement.lang = language.value; + document.title = t('title'); + for (const node of document.querySelectorAll('[data-text]')) { + node.textContent = t(node.dataset.text); + } + for (const node of document.querySelectorAll('[data-label]')) { + node.setAttribute('aria-label', t(node.dataset.label)); + } + document.dispatchEvent(new Event('preview-language-change')); + } + language.addEventListener('change', applyLanguage); + applyLanguage(); + return t; +})(); diff --git a/embodichain/lab/expansion/preview.py b/embodichain/lab/expansion/preview.py index b136d85869..a0b5b4d397 100644 --- a/embodichain/lab/expansion/preview.py +++ b/embodichain/lab/expansion/preview.py @@ -144,7 +144,7 @@ def launch_expansion_preview( Args: paths: Native job, aggregate result or preview-plan directories. output: New directory for owned service status and logs. - port: Loopback port; zero allocates an available port. + port: Browser preview port; zero selects an available port. gpu: Visible GPU index used by the read-only renderer. duration: Service seconds after readiness; zero waits for interruption. open_browser: Open a browser after native rendering is ready. diff --git a/embodichain/lab/visualization/_web_viewer.py b/embodichain/lab/visualization/_web_viewer.py index ff8699d7f6..f40fddf5a6 100644 --- a/embodichain/lab/visualization/_web_viewer.py +++ b/embodichain/lab/visualization/_web_viewer.py @@ -20,6 +20,7 @@ import json import ctypes +from collections.abc import Callable from copy import deepcopy import os from pathlib import Path @@ -121,11 +122,34 @@ def __init__(self, sim: SimulationManager) -> None: ("/style.css", "style.css", "text/css; charset=utf-8"), ) } - self.application = dexsim.WebApplication(sim.get_world(), assets) + self._replace_application(assets, self._request) except BaseException: self.close() raise + def _replace_application( + self, + assets: dict[str, tuple[str, bytes]], + handler: Callable[[str, str], tuple[int, str]], + ) -> None: + """Install host-owned routes on the existing observer and listener.""" + import dexsim + + self._assert_owner() + if self.closed: + raise RuntimeError("WebRTC viewer is closed.") + if self.application is not None: + self.application.close() + self.application = None + self.application = dexsim.WebApplication(self.sim.get_world(), assets) + self._application_handler = handler + + def _process_application_requests(self) -> None: + """Service application requests without scheduling an observer render.""" + self._assert_owner() + if self.application is not None: + self.application.process(self._application_handler) + def _assert_owner(self) -> None: if threading.get_ident() != self.owner: raise RuntimeError("WebRTC viewer must run on the World creator thread.") @@ -210,7 +234,7 @@ def capture(self, *, force: bool = False) -> bool: self._assert_owner() if self.closed: return False - self.application.process(self._request) + self._process_application_requests() if self.error is not None: return False if not (force or self.dirty or time.monotonic() >= self.next_render): diff --git a/examples/expansion/engine/README.md b/examples/expansion/engine/README.md index e1165c7648..f02d6c232d 100644 --- a/examples/expansion/engine/README.md +++ b/examples/expansion/engine/README.md @@ -45,7 +45,7 @@ folder; it is no longer the existing-result input flag. `--plan-only` freezes an validates samples without executing, and `--no-open` suppresses automatic opening. The [preview guide](ghost-preview.md) explains budgets, failed-boundary evidence, scene-atlas domains, finite-sampling limitations and the WebRTC TODO. Rendering is -native; browser transport remains HTTP JPEG, not WebRTC. +native; the browser receives H.264 video over WebRTC. ## Run a configured job diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index 1ec07e9993..435ea8cf67 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -8,14 +8,11 @@ | 路径 | 渲染与交互 | 状态 | | --- | --- | --- | | SDK 原生窗口对照 | `preview_expansion_comparison` 加载已验收轨迹,显示参考与选中虚影;N 切换、Space 暂停、Q 关闭 | 仓库已有能力,见 [comparison.py](../../../embodichain/lab/expansion/comparison.py) | -| 浏览器结果预览 | EmbodiChain 原生离屏渲染完整模型;HTTP JPEG 传图,HTTP 控制筛选与回放 | `embodichain expansion preview`,直接读取已确认结果 | -| 原生 WebRTC 推流 | 复用 EmbodiChain 的原生推流生命周期与控制接口 | TODO,尚未接入本预览 | +| 浏览器 WebRTC 回放 | 原生观察相机输出 H.264 视频,SDK 鉴权后控制回放与视角 | `embodichain expansion preview` | -“原生渲染”指场景由 `SimulationManager`、`RobotMarkers`、 -`VisualizationMarkers` 和 DexSim Hybrid 渲染器生成,**不表示采用 WebRTC**。 -浏览器预览没有自行绘制机器人骨架,也不使用 Viser 重建场景;它显示原生离屏 -相机输出的 JPEG。本次使用 OptiX 去噪。展示灯光、视角和透明材质与采集时可以不同, -不能把预览图片当作采集传感器的原始观测。 +浏览器回放使用 `SimulationManager`、`RobotMarkers`、`VisualizationMarkers` 和带 OptiX +去噪的 DexSim Hybrid 场景。展示灯光、视角和透明材质用于观看实测状态,采集传感器 +图像可在原始作业中查看。 最初实验使用采集时冻结的源码 `ab04d972b5b75042434498db9a889b4edd03b6fe`。 仓库入口直接读取原始结果,不需要该源码快照、本地预处理 JSON 或实验脚本。 @@ -90,7 +87,7 @@ job 输出目录旁创建唯一目录。原 job 文件和原产物不修改, 页面显示所有计划点的参数和状态,候选虚影只来自确认结果;初始位置图层中, 红色计划点表示未完全确认的参数点,不代表一条失败轨迹。筛选后没有匹配样本时, -候选列表为空,固定对照继续显示。WebRTC 接入仍为 TODO。 +候选列表为空,固定对照继续显示。 ## 从已有结果启动 @@ -264,9 +261,8 @@ objects、软体、流体、线缆、显式 visual replacement 和直接 scene-a 不会用方块代替不支持的几何。预览保持记录中的运动与尺寸,虚影材质与灯光用于展示, 不声称精确恢复采集传感器的原始图像。新任务支持应扩展场景恢复契约并验证实测坐标。 -HTTP JPEG 轮询不提供 WebRTC 的编码、拥塞控制、连接恢复或低延迟保证。 -页面是单个服务的共享回放会话,多人操作会改变同一状态;尚未提供独立会话、 -认证或通用资产包恢复。当前不应对外公开监听。 +页面由单个 WebRTC 查看者操作,适用于可信网络。回放控件只改变预览的时间、筛选、 +图层和视角。 ## 一体化入口的实测验收 @@ -280,18 +276,13 @@ XY、安装 XY/yaw、质量、摩擦与六个受控关节残差,共 13 个变 图层;回放物理推进为 0,自动关闭后端口释放。另行验证了无 motion profile 的 普通 Task Program 作业也能重新计算并进入预览;批内诊断由来源行号绑定。 -## TODO:接入 EmbodiChain 原生 WebRTC 推流 +## WebRTC 视频回放 -后续直接复用 EmbodiChain 原生 WebRTC 能力,替换 HTTP JPEG 轮询;先核对实际 -推流入口、信令与关闭接口,不在本示例另建一套独立 WebRTC 栈。 -保留真实结果加载、原生场景、三类筛选联动、播放、时间轴及视角控制。 -控制通道的实现需按原生接口确定,不能预先宣称已经通过 DataChannel 接入。 +`embodichain expansion preview` 默认使用 WebRTC。服务复用 +[DexSim WebRTC 观察视口](../../../embodichain/lab/visualization/README.md),以最高 25 帧/秒更新 +回放相机。视频通过 H.264 发送,时间轴和图表读取独立的回放状态。语言、筛选、虚影、播放、 +拖动和视角沿用同一页面。时间轴上的源帧描述服务端回放位置;浏览器的视频显示另有编解码和网络延迟。 -验收条件: - -- 浏览器建立真实 WebRTC 连接并接收原生相机视频,确认画面不再依赖 JPEG 轮询。 -- 沿用这 8 条扩增结果和参考轨迹,复测筛选、拖动、暂停、切换视角及重新连接。 -- 控制状态、源帧和视频画面的对应关系可检查;显示延迟不冒充记录时间。 -- 回放物理步数仍为 0,不触发重采集、不修改原始证据或成功计数。 -- 关闭预览后释放推流、相机、端口及场景资源;记录端到端延迟与实际帧率, - 再据此报告改善,不能用传输协议名称推断性能。 +原生 SDK 需要 Linux/NVIDIA 和 NVENC。其信令监听所有 IPv4 接口,适合可信网络; +客户端需要 ICE 媒体连通性。通过 SSH 转发页面时,仍需配置媒体路径。使用完毕可通过 +Ctrl+C 或 `--duration` 结束服务,观察相机、应用与端口由原有 World 生命周期统一释放。 diff --git a/scripts/tutorials/expansion/ur5_pick_place/README.md b/scripts/tutorials/expansion/ur5_pick_place/README.md index cca21399fa..63c46d5aab 100644 --- a/scripts/tutorials/expansion/ur5_pick_place/README.md +++ b/scripts/tutorials/expansion/ur5_pick_place/README.md @@ -39,9 +39,11 @@ python -m embodichain expansion preview \ --port 0 --open ``` +- 回放通过原生 WebRTC 视频呈现。连接要求见[预览说明](../../../../examples/expansion/engine/ghost-preview.md#webrtc-视频回放)。 +- 页眉的 **语言**可以在简体中文和 English 之间切换。播放进度和当前筛选会保留。 - **空格**播放或暂停,播放结束后再按空格从头开始。拖动进度条可定位到某一帧。使用下拉框或复选框时,空格操作当前控件,点击回放画面即可继续用空格控制播放。 - 原始轨迹始终以实体显示。右侧每个轨迹按钮独立切换一条半透明虚影。按上述命令加载时,前两个参数组来自 `scene_first`,后两个来自 `robot_first`。 -- 在 **Affordance** 下拉框中选择 `1` 或 `2`,可以查看采用该抓取分支的轨迹。使用任务固定抓取姿态的 `object_pose` 记录显示为「未记录」。 +- 在 **抓取分支**(**Affordance**)下拉框中选择 `1` 或 `2`,可以查看采用该抓取分支的轨迹。使用任务固定抓取姿态的 `object_pose` 记录显示为「未记录」。 - 画面下方的 TCP 图分开显示相对原始轨迹的平移距离(mm)和最短旋转角(°)。关节图显示每条轨迹最大的臂关节绝对偏差。三条曲线都用色带标出同一时刻各轨迹的最小值至最大值,用实线标出均值。悬停可读取三项数值和参与轨迹数。 - **object_pose 物体起点分布**统计两种布局策略各 4 条 `object_pose` 扩增轨迹。选择抓取方块 `cube` 或放置目标 `goal`,可查看该物体在 8 条轨迹首帧的实测 XY 位置。X、Y 轴分别贴合该物体的起点范围,两端各留半格。图旁标有单格的实际宽、高。悬停或轻点网格可读取坐标和轨迹数。 diff --git a/setup.py b/setup.py index bac3016a33..a6d0ce67d4 100644 --- a/setup.py +++ b/setup.py @@ -155,6 +155,9 @@ def get_package_data() -> dict[str, list[str]]: "embodichain": ["VERSION"], "embodichain.lab.expansion": [ "_preview.html", + "_preview.css", + "_preview_text.js", + "_preview_controls.js", "_preview_charts.js", "_preview_heatmap.js", "_distribution.html", diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 9f402cc3aa..06e8a63516 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -14,18 +14,14 @@ # limitations under the License. # ---------------------------------------------------------------------------- -"""Result-only preview: provenance, row selection, controls and HTTP lifecycle.""" +"""Result-only preview: provenance, row selection and WebRTC controls.""" from __future__ import annotations -import base64 from dataclasses import replace import hashlib import json from pathlib import Path -import threading -import urllib.error -import urllib.request import numpy as np import pytest import torch @@ -44,7 +40,7 @@ ) from embodichain.lab.expansion._preview_heatmap import object_heatmaps from embodichain.lab.expansion._preview_render import prepare_geometry -from embodichain.lab.expansion._preview_server import PreviewTransport +from embodichain.lab.expansion._preview_server import _WebPreviewTransport @pytest.fixture @@ -500,43 +496,39 @@ def test_playback_toggles_in_order_and_restarts_from_the_end(recorded_job): assert state.values["playing"] and state.values["progress"] == 0 -def test_http_snapshot_control_and_shutdown(recorded_job): +def test_native_preview_publishes_metadata_and_queues_valid_replay_controls( + recorded_job, +): + from types import SimpleNamespace + path, _, _ = recorded_job state = PreviewState(load_preview([path])) - transport = PreviewTransport(state, 0) - transport.publish({"frame": 7, "source_frame": 2}, b"jpeg-frame-7") - thread = threading.Thread(target=transport.server.serve_forever) - thread.start() - try: - heatmaps = json.load(urllib.request.urlopen(transport.url + "object-heatmaps")) - assert heatmaps["episodes"] == 0 and heatmaps["objects"] == [] - snapshot = json.load(urllib.request.urlopen(transport.url + "snapshot")) - assert snapshot["frame"] == 7 and snapshot["source_frame"] == 2 - assert base64.b64decode(snapshot["image"].split(",")[1]) == b"jpeg-frame-7" - req = urllib.request.Request( - transport.url + "control", - data=b'{"progress":0.5}', - headers={"Content-Type": "application/json"}, - method="POST", - ) - assert urllib.request.urlopen(req).status == 204 - assert ( - state.values["progress"] == 0 - ) # only the render owner applies queued commands - state.apply(transport.commands.get_nowait()) - assert state.values["progress"] == 0.5 - req.add_header("Origin", "https://untrusted.example") - with pytest.raises(urllib.error.HTTPError) as error: - urllib.request.urlopen(req) - assert error.value.code == 403 - finally: - transport.server.shutdown() - thread.join(timeout=5) - transport.server.server_close() - assert not thread.is_alive() - - -def test_preview_cli_dispatch_does_not_collect(monkeypatch, recorded_job): + application = {} + + def install(assets, request): + application.update(assets=assets, request=request) + + viewer = SimpleNamespace( + endpoint="http://127.0.0.1:8769/", _replace_application=install + ) + transport = _WebPreviewTransport(state, viewer, b'{"episodes":0}') + transport.publish({"frame": 7, "source_frame": 2}) + request = application["request"] + code, body = request("/api/state", "{}") + assert code == 200 + assert json.loads(body) == {"frame": 7, "source_frame": 2} + assert b'' in application["assets"]["/"][1] + assert request("/api/command", '{"progress":0.5}')[0] == 200 + assert state.values["progress"] == 0 + state.apply(transport.commands.popleft()) + assert state.values["progress"] == 0.5 + assert request("/api/command", '{"playing":"yes"}')[0] == 400 + assert not transport.commands + + +def test_preview_cli_dispatches_confirmed_records_without_collecting( + monkeypatch, recorded_job +): from embodichain.cli.expansion import main import embodichain.lab.expansion._preview_server as server from embodichain.lab.expansion import ExpansionEngine @@ -567,7 +559,14 @@ def test_viewer_assets_are_in_package_data(tmp_path): source = tmp_path / "source" source.mkdir() originals = Path(__file__).resolve().parents[3] / "embodichain/lab/expansion" - assets = ("_preview.html", "_preview_charts.js", "_preview_heatmap.js") + assets = ( + "_preview.html", + "_preview.css", + "_preview_text.js", + "_preview_controls.js", + "_preview_charts.js", + "_preview_heatmap.js", + ) for name in assets: shutil.copyfile(originals / name, source / name) (source / "__init__.py").write_text("") diff --git a/tests/visualization/test_web_viewer.py b/tests/visualization/test_web_viewer.py index 6592c354b3..ebc18bba92 100644 --- a/tests/visualization/test_web_viewer.py +++ b/tests/visualization/test_web_viewer.py @@ -65,6 +65,7 @@ def viewer(): value.orbit = np.array(value.cfg.target) value.group = object() value.application = Mock() + value._application_handler = value._request value.arena = Mock() value.error = None value.frames = 0 From 76ad5aa952cd6d84c1a1ab7cd289b226938ece3a Mon Sep 17 00:00:00 2001 From: yuecideng Date: Thu, 19 Nov 2026 11:23:17 +0000 Subject: [PATCH 48/49] refactor(expansion): group browser assets in a frontend package --- .../expansion-engine/expansion-engine.md | 3 +- embodichain/lab/expansion/_distribution.py | 7 ++- .../lab/expansion/_frontend/__init__.py | 49 +++++++++++++++++++ .../distribution.html} | 0 .../preview-charts.js} | 0 .../preview-controls.js} | 0 .../preview-heatmap.js} | 0 .../preview-text.js} | 0 .../{_preview.css => _frontend/preview.css} | 0 .../{_preview.html => _frontend/preview.html} | 0 embodichain/lab/expansion/_preview_server.py | 39 +++------------ examples/expansion/engine/ghost-preview.md | 2 +- .../expansion/ur5_pick_place/README.md | 2 +- setup.py | 10 +--- tests/lab/expansion/test_preview.py | 29 +++++------ 15 files changed, 78 insertions(+), 63 deletions(-) create mode 100644 embodichain/lab/expansion/_frontend/__init__.py rename embodichain/lab/expansion/{_distribution.html => _frontend/distribution.html} (100%) rename embodichain/lab/expansion/{_preview_charts.js => _frontend/preview-charts.js} (100%) rename embodichain/lab/expansion/{_preview_controls.js => _frontend/preview-controls.js} (100%) rename embodichain/lab/expansion/{_preview_heatmap.js => _frontend/preview-heatmap.js} (100%) rename embodichain/lab/expansion/{_preview_text.js => _frontend/preview-text.js} (100%) rename embodichain/lab/expansion/{_preview.css => _frontend/preview.css} (100%) rename embodichain/lab/expansion/{_preview.html => _frontend/preview.html} (100%) diff --git a/agent_context/topics/expansion-engine/expansion-engine.md b/agent_context/topics/expansion-engine/expansion-engine.md index f145c73178..14eca61aef 100644 --- a/agent_context/topics/expansion-engine/expansion-engine.md +++ b/agent_context/topics/expansion-engine/expansion-engine.md @@ -102,7 +102,8 @@ process orchestration remain outside the replay core. `embodichain expansion preview --input` reads confirmed job outputs through `_preview_data.py`, then replays full measured states using `_preview_render.py` and `_preview_server.py`. Browser replay defaults to the DexSim WebRTC observer -and its owner-thread application. +and its owner-thread application. `_frontend/` owns the packaged preview +HTML, CSS and JavaScript and the offline distribution report template. Video is separate from the HTTP replay state; authenticated commands queue only validated replay controls. Inputs retain their original evidence; no collection or physics stepping occurs. It accepts one URDF robot and recorded rigid visual diff --git a/embodichain/lab/expansion/_distribution.py b/embodichain/lab/expansion/_distribution.py index cb2ec86430..608f31364c 100644 --- a/embodichain/lab/expansion/_distribution.py +++ b/embodichain/lab/expansion/_distribution.py @@ -26,11 +26,14 @@ from collections.abc import Mapping from copy import deepcopy import hashlib +from importlib.resources import files import json from pathlib import Path from typing import Any import numpy as np +from . import _frontend + __all__: list[str] = [] @@ -345,7 +348,9 @@ def _run( (output / "summary.json").write_text( json.dumps(report, ensure_ascii=False, indent=2, allow_nan=False) ) - template = Path(__file__).with_name("_distribution.html").read_text() + template = ( + files(_frontend).joinpath("distribution.html").read_text(encoding="utf-8") + ) (output / "report.html").write_text( template.replace( "__REPORT__", diff --git a/embodichain/lab/expansion/_frontend/__init__.py b/embodichain/lab/expansion/_frontend/__init__.py new file mode 100644 index 0000000000..7dcd44e464 --- /dev/null +++ b/embodichain/lab/expansion/_frontend/__init__.py @@ -0,0 +1,49 @@ +# ---------------------------------------------------------------------------- +# Copyright (c) 2021-2026 DexForce Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ---------------------------------------------------------------------------- + +"""Packaged browser assets for expansion playback and distribution reports.""" + +from __future__ import annotations + +from importlib.resources import files + +__all__: list[str] = [] + + +def _preview_assets() -> dict[str, tuple[str, bytes]]: + """Load same-origin assets for the native WebRTC preview.""" + directory = files(__name__) + assets = { + "/": ( + "text/html; charset=utf-8", + directory.joinpath("preview.html").read_bytes(), + ), + "/preview.css": ( + "text/css; charset=utf-8", + directory.joinpath("preview.css").read_bytes(), + ), + } + for name in ( + "preview-text.js", + "preview-controls.js", + "preview-charts.js", + "preview-heatmap.js", + ): + assets[f"/{name}"] = ( + "text/javascript; charset=utf-8", + directory.joinpath(name).read_bytes(), + ) + return assets diff --git a/embodichain/lab/expansion/_distribution.html b/embodichain/lab/expansion/_frontend/distribution.html similarity index 100% rename from embodichain/lab/expansion/_distribution.html rename to embodichain/lab/expansion/_frontend/distribution.html diff --git a/embodichain/lab/expansion/_preview_charts.js b/embodichain/lab/expansion/_frontend/preview-charts.js similarity index 100% rename from embodichain/lab/expansion/_preview_charts.js rename to embodichain/lab/expansion/_frontend/preview-charts.js diff --git a/embodichain/lab/expansion/_preview_controls.js b/embodichain/lab/expansion/_frontend/preview-controls.js similarity index 100% rename from embodichain/lab/expansion/_preview_controls.js rename to embodichain/lab/expansion/_frontend/preview-controls.js diff --git a/embodichain/lab/expansion/_preview_heatmap.js b/embodichain/lab/expansion/_frontend/preview-heatmap.js similarity index 100% rename from embodichain/lab/expansion/_preview_heatmap.js rename to embodichain/lab/expansion/_frontend/preview-heatmap.js diff --git a/embodichain/lab/expansion/_preview_text.js b/embodichain/lab/expansion/_frontend/preview-text.js similarity index 100% rename from embodichain/lab/expansion/_preview_text.js rename to embodichain/lab/expansion/_frontend/preview-text.js diff --git a/embodichain/lab/expansion/_preview.css b/embodichain/lab/expansion/_frontend/preview.css similarity index 100% rename from embodichain/lab/expansion/_preview.css rename to embodichain/lab/expansion/_frontend/preview.css diff --git a/embodichain/lab/expansion/_preview.html b/embodichain/lab/expansion/_frontend/preview.html similarity index 100% rename from embodichain/lab/expansion/_preview.html rename to embodichain/lab/expansion/_frontend/preview.html diff --git a/embodichain/lab/expansion/_preview_server.py b/embodichain/lab/expansion/_preview_server.py index a53c875591..d554738640 100644 --- a/embodichain/lab/expansion/_preview_server.py +++ b/embodichain/lab/expansion/_preview_server.py @@ -23,8 +23,8 @@ import socket import time import webbrowser -from pathlib import Path from typing import TYPE_CHECKING +from ._frontend import _preview_assets from ._preview_data import PreviewData, PreviewState from ._preview_heatmap import object_heatmaps @@ -38,37 +38,6 @@ def _json(value: object) -> str: return json.dumps(value, allow_nan=False, separators=(",", ":")) -def _assets(data: PreviewData) -> dict[str, tuple[str, bytes]]: - static = { - route: (mime, Path(__file__).with_name(filename).read_bytes()) - for route, filename, mime in ( - ("/", "_preview.html", "text/html; charset=utf-8"), - ("/preview.css", "_preview.css", "text/css; charset=utf-8"), - ("/preview-text.js", "_preview_text.js", "text/javascript; charset=utf-8"), - ( - "/preview-controls.js", - "_preview_controls.js", - "text/javascript; charset=utf-8", - ), - ( - "/preview-charts.js", - "_preview_charts.js", - "text/javascript; charset=utf-8", - ), - ( - "/preview-heatmap.js", - "_preview_heatmap.js", - "text/javascript; charset=utf-8", - ), - ) - } - static["/object-heatmaps"] = ( - "application/json", - _json(object_heatmaps(data)).encode(), - ) - return static - - class _WebPreviewTransport: """Serve replay controls and statistics over the native video listener.""" @@ -79,7 +48,11 @@ def __init__( self.commands: deque[dict[str, object]] = deque() self.url = viewer.endpoint self.status = "{}" - assets = _assets(state.data) + assets = _preview_assets() + assets["/object-heatmaps"] = ( + "application/json", + _json(object_heatmaps(state.data)).encode(), + ) assets["/deviations"] = ("application/json", deviations) viewer._replace_application(assets, self._request) diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index 435ea8cf67..0dfe51e606 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -251,7 +251,7 @@ CLI 不触发采集和安装包页面资源由生产模块的聚焦测试覆盖 上述文件是原型的历史实验产物;仓库入口不再依赖它们。结果读取与控制语义由 `embodichain/lab/expansion/_preview_data.py` 负责,原生渲染与资源释放由 -`_preview_render.py` 负责,HTTP 服务与页面由 `_preview_server.py`、`_preview.html` +`_preview_render.py` 负责,HTTP 服务与页面由 `_preview_server.py`、`_frontend/preview.html` 负责,CLI 由 `embodichain/cli/expansion.py` 分发。 当前渲染支持单 URDF 机器人、单位机器人缩放,以及有完整实测位姿的刚体场景。 diff --git a/scripts/tutorials/expansion/ur5_pick_place/README.md b/scripts/tutorials/expansion/ur5_pick_place/README.md index 63c46d5aab..759a026ecc 100644 --- a/scripts/tutorials/expansion/ur5_pick_place/README.md +++ b/scripts/tutorials/expansion/ur5_pick_place/README.md @@ -55,4 +55,4 @@ python -m embodichain expansion preview \ 两种策略共用一份配置。默认布局允许立方体和放置目标在 X、Y 方向各偏移 ±6 cm。`trajectory.affordance.call_indices: [0]` 将抓取扩增应用到第一次调用 `pick`。`fixed_object_to_eef: null` 在 affordance 组启用夹爪的对向接触候选生成器。`branches: 3` 让采集器轮流请求分支 1 和 2,再按实际抓取、搬运、释放和放置结果验收。可以在同一处调整分支数、布局范围和每组轨迹数。[扩增配置](expansion.yaml) · [任务与机器人配置](../../../../extensions/embodichain_tasks/configs/tasks/manipulation/workspace_pose_pick_place/acceptance/scene_first/task.yaml) -播放键、筛选器和时间轴在回放页面中实现,偏差曲线和物体热力图各有独立的绘图脚本。改完重新运行「网页回放」命令即可用同一批轨迹查看效果。[回放页面](../../../../embodichain/lab/expansion/_preview.html) · [偏差曲线脚本](../../../../embodichain/lab/expansion/_preview_charts.js) · [热力图脚本](../../../../embodichain/lab/expansion/_preview_heatmap.js) +播放键、筛选器和时间轴在回放页面中实现,偏差曲线和物体热力图各有独立的绘图脚本。改完重新运行「网页回放」命令即可用同一批轨迹查看效果。[回放页面](../../../../embodichain/lab/expansion/_frontend/preview.html) · [偏差曲线脚本](../../../../embodichain/lab/expansion/_frontend/preview-charts.js) · [热力图脚本](../../../../embodichain/lab/expansion/_frontend/preview-heatmap.js) diff --git a/setup.py b/setup.py index a6d0ce67d4..aee8741741 100644 --- a/setup.py +++ b/setup.py @@ -153,15 +153,7 @@ def get_package_data() -> dict[str, list[str]]: ] return { "embodichain": ["VERSION"], - "embodichain.lab.expansion": [ - "_preview.html", - "_preview.css", - "_preview_text.js", - "_preview_controls.js", - "_preview_charts.js", - "_preview_heatmap.js", - "_distribution.html", - ], + "embodichain.lab.expansion._frontend": ["*.html", "*.css", "*.js"], "embodichain.lab.visualization": [ "web_assets/*.html", "web_assets/*.js", diff --git a/tests/lab/expansion/test_preview.py b/tests/lab/expansion/test_preview.py index 06e8a63516..4c6d83d4b7 100644 --- a/tests/lab/expansion/test_preview.py +++ b/tests/lab/expansion/test_preview.py @@ -549,27 +549,22 @@ def test_preview_cli_dispatches_confirmed_records_without_collecting( ) -def test_viewer_assets_are_in_package_data(tmp_path): +def test_expansion_frontend_assets_are_in_package_data(tmp_path): from setup import get_package_data from setuptools import Distribution from setuptools.command.build_py import build_py - import shutil - package = "embodichain.lab.expansion" - source = tmp_path / "source" - source.mkdir() - originals = Path(__file__).resolve().parents[3] / "embodichain/lab/expansion" + package = "embodichain.lab.expansion._frontend" + source = Path(__file__).resolve().parents[3] / "embodichain/lab/expansion/_frontend" assets = ( - "_preview.html", - "_preview.css", - "_preview_text.js", - "_preview_controls.js", - "_preview_charts.js", - "_preview_heatmap.js", + "distribution.html", + "preview.html", + "preview.css", + "preview-text.js", + "preview-controls.js", + "preview-charts.js", + "preview-heatmap.js", ) - for name in assets: - shutil.copyfile(originals / name, source / name) - (source / "__init__.py").write_text("") distribution = Distribution( { "packages": [package], @@ -583,9 +578,9 @@ def test_viewer_assets_are_in_package_data(tmp_path): command.build_lib = str(tmp_path / "build") command.ensure_finalized() command.run() - packaged = Path(command.build_lib) / "embodichain/lab/expansion" + packaged = Path(command.build_lib) / "embodichain/lab/expansion/_frontend" for name in assets: - assert (packaged / name).read_bytes() == (originals / name).read_bytes() + assert (packaged / name).read_bytes() == (source / name).read_bytes() def test_manifest_keeps_rejected_points_visible_in_coverage(recorded_job): From c4cd5f70672e1750c18d1882a998a88a89281479 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Thu, 19 Nov 2026 14:04:40 +0000 Subject: [PATCH 49/49] refactor(expansion): simplify replay and drop tutorial screenshots --- .../lab/expansion/_frontend/preview-charts.js | 14 ++++----- .../expansion/_frontend/preview-controls.js | 29 +++++++++--------- .../lab/expansion/_frontend/preview-text.js | 1 - .../lab/expansion/_frontend/preview.css | 6 ++-- .../assets/piper-scene-first-replay.jpg | Bin 143302 -> 0 bytes examples/expansion/engine/ghost-preview.md | 9 ++---- .../expansion/ur5_pick_place/README.md | 4 +-- .../ur5_pick_place/assets/deviation-bands.png | Bin 80078 -> 0 bytes .../ur5_pick_place/assets/object-heatmap.png | Bin 54641 -> 0 bytes .../ur5_pick_place/assets/replay-before.jpg | Bin 131978 -> 0 bytes .../ur5_pick_place/assets/replay-ghosts.jpg | Bin 129489 -> 0 bytes 11 files changed, 27 insertions(+), 36 deletions(-) delete mode 100644 examples/expansion/engine/assets/piper-scene-first-replay.jpg delete mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png delete mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png delete mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg delete mode 100644 scripts/tutorials/expansion/ur5_pick_place/assets/replay-ghosts.jpg diff --git a/embodichain/lab/expansion/_frontend/preview-charts.js b/embodichain/lab/expansion/_frontend/preview-charts.js index 65ad982d0d..e1a42ad180 100644 --- a/embodichain/lab/expansion/_frontend/preview-charts.js +++ b/embodichain/lab/expansion/_frontend/preview-charts.js @@ -37,14 +37,12 @@ const deviationCharts = (() => { const format = v => `${number.format(v)} ${plot.unit}`; if (value === null) { plot.value.textContent = previewText('deviationNoSample'); - } else if (plot.range) { + } else { plot.value.textContent = previewText('deviationRange', { min: format(plot.range.min[frame]), mean: format(value), max: format(plot.range.max[frame]), }); - } else { - plot.value.textContent = format(value); } plot.cursor.style.left = `calc(${fraction * 100}% + ${left - fraction * (left + right)}px)`; } @@ -115,7 +113,7 @@ const deviationCharts = (() => { } const x = frame => left + w * data.time_s[frame] / duration; const y = value => top + h * (1 - value / plot.max); - if (plot.range) drawBand(ctx, plot.range, plot.color, x, y); + drawBand(ctx, plot.range, plot.color, x, y); ctx.strokeStyle = plot.color; ctx.lineWidth = 2; ctx.beginPath(); let previous = false; @@ -140,7 +138,7 @@ const deviationCharts = (() => { function addCurve(panel, key, titleKey, unit, color) { const values = data.mean[key]; if (!values) return; - const range = data.range?.[key]; + const range = data.range[key]; const figure = document.createElement('figure'); figure.className = 'curve'; figure.style.setProperty('--line', color); const caption = document.createElement('figcaption'); @@ -153,7 +151,7 @@ const deviationCharts = (() => { canvas.setAttribute('role', 'img'); const cursor = document.createElement('i'); area.append(canvas, cursor); figure.append(caption, area); panel.append(figure); - const peak = (range?.max ?? values).reduce((max, v) => v === null ? max : Math.max(max, v), 0); + const peak = range.max.reduce((max, v) => v === null ? max : Math.max(max, v), 0); const step = tickStep(peak || 1); const ticks = Math.ceil((peak || 1) / step); const plot = {values, value, range, titleKey, label, unit, color, canvas, cursor, step, ticks, max: step * ticks}; @@ -178,7 +176,7 @@ const deviationCharts = (() => { reference: previewText(data.explicit_reference ? 'reference' : 'firstReference'), count: data.episodes, }); - if (Object.keys(data.range ?? {}).length) description.append(' ', previewText('deviationsBand')); + if (plots.length) description.append(' ', previewText('deviationsBand')); if (tcpNote) tcpNote.textContent = previewText('tcpUnavailable'); if (jointNote) { const separator = document.documentElement.lang === 'en' ? ', ' : '、'; @@ -190,7 +188,7 @@ const deviationCharts = (() => { for (const plot of plots) { const values = {title: previewText(plot.titleKey), unit: plot.unit}; plot.label.textContent = previewText('curveLabel', values); - plot.canvas.setAttribute('aria-label', previewText(plot.range ? 'curveWithBand' : 'curveMean', values)); + plot.canvas.setAttribute('aria-label', previewText('curveWithBand', values)); draw(plot); } updateReadout(); diff --git a/embodichain/lab/expansion/_frontend/preview-controls.js b/embodichain/lab/expansion/_frontend/preview-controls.js index 9224f40336..b8d9416744 100644 --- a/embodichain/lab/expansion/_frontend/preview-controls.js +++ b/embodichain/lab/expansion/_frontend/preview-controls.js @@ -14,9 +14,12 @@ // limitations under the License. // ---------------------------------------------------------------------------- -let status=null,busy=false,dragging=false,filterKey=null,initialized=false,sending=false; -const pending=[]; -const $=id=>document.getElementById(id); +let status = null, busy = false, dragging = false, filterKey = null, sending = false; +const pending = []; +const filterKeys = ['space', 'aff', 'variant']; +const selectKeys = [...filterKeys, 'align']; +const layerKeys = ['paths', 'targets', 'positions']; +const $ = id => document.getElementById(id); const viewport = $('viewport'); let videoConnectionFailed = false; let video; @@ -97,8 +100,8 @@ async function control(update) { sending = false; } } -for(const k of ['space','aff','variant','align'])$(k).onchange=()=>control({[k]:$(k).value}); -for(const k of ['ghosts','paths','targets','positions'])$(k).onchange=()=>control({[k]:$(k).checked}); +for (const key of selectKeys) $(key).onchange = () => control({[key]: $(key).value}); +for (const key of ['ghosts', ...layerKeys]) $(key).onchange = () => control({[key]: $(key).checked}); $('play').onclick=()=>control({toggle_playback:true}); $('reset').onclick=()=>control({progress:0,playing:false}); document.addEventListener('keydown',event=>{ @@ -152,9 +155,7 @@ function updateCandidates(s){ } const shown=new Set(s.visible_ghosts); for(const button of list.children){ - const pressed=shown.has(Number(button.dataset.index)); - button.classList.toggle('active',pressed); - button.setAttribute('aria-pressed',String(pressed)); + button.setAttribute('aria-pressed', String(shown.has(Number(button.dataset.index)))); } const all=$('ghosts'); all.disabled=s.count===0; @@ -178,7 +179,6 @@ function renderCoverage(coverage) { const values = Object.entries(record.values).map(([name, value]) => `${name}=${Number(value).toPrecision(4)}`); return `${summary}\n${values.join(', ')}`; }); - $('coverage-details').style.whiteSpace = 'pre-line'; $('coverage-details').textContent = [previewText('coverageScope'), axes.join('\n'), records.join('\n\n')].join('\n\n'); } @@ -211,7 +211,7 @@ function renderReplayText() { } function populateFilters(s) { - for (const key of ['space', 'aff', 'variant']) { + for (const key of filterKeys) { for (const value of s.options[key]) { const option = new Option(recordedLabel(value), value); if (value === 'unrecorded') option.dataset.text = 'unrecorded'; @@ -229,17 +229,16 @@ async function poll() { if (!response.ok) throw Error('Could not read replay state'); const s = await response.json(); if (s.frame === undefined) return; - status = s; - if (!initialized) { + if (!status) { populateFilters(s); if (s.coverage) renderCoverage(s.coverage); - initialized = true; } + status = s; if (!sending) { - for (const key of ['space', 'aff', 'variant', 'align']) { + for (const key of selectKeys) { if (document.activeElement !== $(key)) $(key).value = s[key]; } - for (const key of ['paths', 'targets', 'positions']) $(key).checked = s[key]; + for (const key of layerKeys) $(key).checked = s[key]; if (document.activeElement !== $('camera')) { $('camera').value = Object.keys(cameras).find(key => Object.keys(cameras[key]).every(axis => Math.abs(s[axis] - cameras[key][axis]) < .001) diff --git a/embodichain/lab/expansion/_frontend/preview-text.js b/embodichain/lab/expansion/_frontend/preview-text.js index 6f0a99b498..8dd80e52a6 100644 --- a/embodichain/lab/expansion/_frontend/preview-text.js +++ b/embodichain/lab/expansion/_frontend/preview-text.js @@ -99,7 +99,6 @@ const previewText = (() => { curveLabel: ['{title}({unit})', '{title} ({unit})'], curveWithBand: ['{title}随实测时间的均值曲线及最小值至最大值色带,单位 {unit}', '{title} over recorded time, with mean and minimum-to-maximum range, in {unit}'], - curveMean: ['{title}随实测时间的均值曲线,单位 {unit}', '{title} mean over recorded time, in {unit}'], tcpUnavailable: ['记录中缺少所选机械臂的完整 TCP 标定。', 'The selected arm has incomplete TCP calibration in the recordings.'], jointsUnavailable: ['记录中缺少可识别的机械臂关节组。', 'The recordings do not identify an arm joint group.'], jointNames: ['统计关节 · {names}', 'Included joints · {names}'], diff --git a/embodichain/lab/expansion/_frontend/preview.css b/embodichain/lab/expansion/_frontend/preview.css index 0c515dea51..3b6b7a0398 100644 --- a/embodichain/lab/expansion/_frontend/preview.css +++ b/embodichain/lab/expansion/_frontend/preview.css @@ -16,11 +16,11 @@ * ---------------------------------------------------------------------------- */ -*{box-sizing:border-box}body{margin:0;background:#10151b;color:#e8edf3;font:14px system-ui,sans-serif}header{padding:22px 28px;border-bottom:1px solid #303944;display:flex;align-items:center;justify-content:space-between}h1{font-size:20px;margin:0 0 6px}p{color:#9eacba;margin:0;line-height:1.6}.badge{color:#77dbb2;border:1px solid #376455;border-radius:20px;padding:7px 12px}main{display:grid;grid-template-columns:minmax(0,1fr) 290px;gap:18px;padding:20px;max-width:1700px;margin:auto}.stage{background:#1b222b;border:1px solid #303944;border-radius:12px;overflow:hidden}.toolbar{display:flex;gap:10px;padding:12px;align-items:center;flex-wrap:wrap}button,select{background:#27323f;color:#e8edf3;border:1px solid #465363;border-radius:6px;padding:9px;cursor:pointer}button:hover{background:#34475a}button:focus-visible,select:focus-visible,input:focus-visible{outline:2px solid #63b7ff}select{max-width:100%}.viewport{position:relative;background:#222;aspect-ratio:1100/760}.overlay{position:absolute;left:16px;top:14px;background:#10151bdc;padding:9px 12px;border-radius:7px;pointer-events:none;font-size:12px}.timeline{padding:16px}input[type=range]{width:100%;accent-color:#6bb7ff}.timeinfo{display:flex;justify-content:space-between;gap:10px;color:#a8bacb;font-size:12px;margin-top:9px}.side{display:flex;flex-direction:column;gap:14px}.panel{padding:17px;background:#1b222b;border:1px solid #303944;border-radius:12px}.panel h2{font-size:14px;margin:0 0 15px}.field{display:flex;align-items:center;justify-content:space-between;gap:10px;margin:11px 0}.field select{width:160px}label{color:#c9d4df}input[type=checkbox]{accent-color:#6bb7ff}.count{font-size:30px;color:#80bfff}.candidates{display:grid;grid-template-columns:1fr 1fr;gap:7px;margin-top:12px}.candidates button{text-align:left;font-size:12px}.candidates button small{display:block;color:#a5b5c6;margin-top:4px}.candidates button.active{border-color:#7cbcff;background:#253e58}.legend{font-size:12px;color:#a7b6c4;line-height:1.9}.detail{font-size:12px;line-height:1.9;overflow-wrap:anywhere}.error{color:#ffba9b}footer{padding:0 22px 20px;color:#8393a3;font-size:12px}@media(max-width:850px){main{grid-template-columns:1fr;padding:10px}.side{display:grid;grid-template-columns:1fr 1fr}header{padding:15px}.badge{display:none}}@media(max-width:550px){.side{grid-template-columns:1fr}.toolbar{gap:5px}h1{font-size:17px}} +*{box-sizing:border-box}body{margin:0;background:#10151b;color:#e8edf3;font:14px system-ui,sans-serif}header{padding:22px 28px;border-bottom:1px solid #303944;display:flex;align-items:center;justify-content:space-between}h1{font-size:20px;margin:0 0 6px}p{color:#9eacba;margin:0;line-height:1.6}.badge{color:#77dbb2;border:1px solid #376455;border-radius:20px;padding:7px 12px}main{display:grid;grid-template-columns:minmax(0,1fr) 290px;gap:18px;padding:20px;max-width:1700px;margin:auto}.stage{background:#1b222b;border:1px solid #303944;border-radius:12px;overflow:hidden}.toolbar{display:flex;gap:10px;padding:12px;align-items:center;flex-wrap:wrap}button,select{background:#27323f;color:#e8edf3;border:1px solid #465363;border-radius:6px;padding:9px;cursor:pointer}button:hover{background:#34475a}button:focus-visible,select:focus-visible,input:focus-visible{outline:2px solid #63b7ff}select{max-width:100%}.viewport{position:relative;background:#222;aspect-ratio:1100/760;touch-action:none;cursor:grab}.overlay{position:absolute;left:16px;top:14px;background:#10151bdc;padding:9px 12px;border-radius:7px;pointer-events:none;font-size:12px}.timeline{padding:16px}input[type=range]{width:100%;accent-color:#6bb7ff}.timeinfo{display:flex;justify-content:space-between;gap:10px;color:#a8bacb;font-size:12px;margin-top:9px}.side{display:flex;flex-direction:column;gap:14px}.panel{padding:17px;background:#1b222b;border:1px solid #303944;border-radius:12px}.panel h2{font-size:14px;margin:0 0 15px}.field{display:flex;align-items:center;justify-content:space-between;gap:10px;margin:11px 0}.field select{width:160px}label{color:#c9d4df}input[type=checkbox]{accent-color:#6bb7ff}.count{font-size:30px;color:#80bfff}.candidates{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:7px;margin-top:12px}.candidates button{text-align:left;font-size:12px}.candidates button small{display:block;color:#a5b5c6;margin-top:4px}.candidates button[aria-pressed="true"]{border-color:#7cbcff;background:#253e58}.legend{font-size:12px;color:#a7b6c4;line-height:1.9}.detail{font-size:12px;line-height:1.9;overflow-wrap:anywhere}.error{color:#ffba9b}footer{padding:0 22px 20px;color:#8393a3;font-size:12px}@media(max-width:850px){main{grid-template-columns:1fr;padding:10px}.side{display:grid;grid-template-columns:1fr 1fr}header{padding:15px}.badge{display:none}}@media(max-width:550px){.side{grid-template-columns:1fr}.toolbar{gap:5px}h1{font-size:17px}} .deviations{grid-column:1/-1;min-width:0}.deviations h2{font-size:18px;margin:0 0 6px}.chart-heading{display:flex;flex-wrap:wrap;justify-content:space-between;gap:8px;align-items:end;margin:6px 0 14px}.chart-heading output,.curve output{font-variant-numeric:tabular-nums}.chart-heading output{color:#cad9e6}.chart-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}.chart-grid h3{font-size:15px;margin:0 0 14px}.curve{margin:12px 0 0}.curve figcaption{display:flex;align-items:baseline;justify-content:space-between;gap:8px;font-size:13px}.curve figcaption span{border-left:3px solid var(--line);padding-left:7px}.curve output{color:var(--line)}.curve-plot{position:relative}.curve canvas{display:block;width:100%;height:120px}.curve-plot i{position:absolute;top:8px;bottom:24px;width:0;border-left:1px dashed #e2eaf3;pointer-events:none}.chart-grid section:has(.curve:only-of-type) canvas{height:250px} .chart-grid[hidden]{display:none} .curve figcaption{flex-wrap:wrap;row-gap:4px} -.viewport{touch-action:none;cursor:grab}.viewport video{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;pointer-events:none}.header-controls{display:flex;align-items:center;gap:12px}.language-control{display:flex;gap:6px;align-items:center}.candidates{grid-template-columns:repeat(2,minmax(0,1fr))}.candidates small{overflow-wrap:anywhere} +.viewport video{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;pointer-events:none}.header-controls{display:flex;align-items:center;gap:12px}.language-control{display:flex;gap:6px;align-items:center}.candidates small{overflow-wrap:anywhere} @media(max-width:550px){header{flex-wrap:wrap;gap:10px}} .controls-help{font-size:12px;color:#a8bacb}.controls-help kbd{font:inherit;border:1px solid #465363;border-radius:4px;padding:1px 4px} @media(max-width:850px){.chart-grid{grid-template-columns:1fr}.chart-grid section:has(.curve:only-of-type) canvas{height:150px}} @@ -29,7 +29,7 @@ .heatmap dl{margin:18px 0;border-block:1px solid #384451}.heatmap dl div{display:flex;justify-content:space-between;align-items:baseline;gap:12px;padding:6px 0}.heatmap dt,.heatmap-legend{color:#a7b6c4}.heatmap dd{margin:0;font-variant-numeric:tabular-nums} .heatmap-scale{display:flex;height:12px;overflow:hidden;border-radius:3px;border:1px solid #465363;margin:7px 0 3px}.heatmap-scale i{flex:1}.heatmap-ticks{display:flex;justify-content:space-between;font-size:12px}.heatmap-readout{display:block;min-height:3.3em;margin-top:18px;color:#c9d4df;font-size:13px;line-height:1.6;font-variant-numeric:tabular-nums} @media(max-width:650px){.heatmap-panel{display:flex;flex-direction:column;align-items:stretch;gap:12px}.heatmap-controls{margin-top:2px}.heatmap canvas{align-self:center;max-width:450px}.heatmap-readout{min-height:3.2em}} -#detail{white-space:pre-line} +#detail,#coverage-details{white-space:pre-line} /* The SDK stages clips here before the active video moves to the viewport. */ #RTC_Videos { diff --git a/examples/expansion/engine/assets/piper-scene-first-replay.jpg b/examples/expansion/engine/assets/piper-scene-first-replay.jpg deleted file mode 100644 index fa43f52c11d247b7fcb04b9f8a610bb832f0b45d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 143302 zcmeFZ2T)W`vpBj)5=oM?f+Q6eB!>kRk<5}aEQ(~7ys&^I0Rbhf#6_Z#<1PZrl9M2r zB`s;mS+WuZMIV0O{oU_Y-FIKrzv{hr|My?NK6U1F&-8TnnVQoxr_ap!J@tDLa9u-1 zT?Ify1OO0S9)RD=L{sWYN>6q5byU=~l>b@K1Gof|`v8Eeo41#~>SJzGGjne8#edfL zQ)X=g^Z0Z9FW^${$;2P&0KgdVzu@_Q%BHZjgV|g%e7!vRye^er8q0WzGdlbezx@Y) z{!d)~5AN&j;eE-Y`v>0d4>rfbbGndqpg8Q2+^SXkNE*l6iFxHwq3m|59a{|F(vtV%{oMoC6S$$Fjo zI_v*3{B8r#T_rIljU^_!1-L>-L`+BYyA!~5+1yvI5dZ0ke*w`I5>jF^@~ae=#g5kj zM8w2I#H8f3B#7LM9CQ#6-SwF=^0rkCSPS{5tEQKH1>ogRaT9R z@k$wZhbH7pKi2n2$*FGdVC55kh38j(?xkcGmWTPY^wq{T_Zx-46P0j58C4VHr6vxd zzu+%B07QQ@k&#~(%Ftb^y)*2*x2!!AM##kU zL)(`gSBih-<@+Y_n*gA?WWGX2Ob2)f_?|__lGFL*3CWX3|K}#k@9it+YnbLi+V3$Y zb7gBJ-Rg?kXKQ}Me3AF*J%|K-0pUa}@Dq-;fZu>)W9+Yv(w~x}x^#3zEFP1Y$n6%b z{90Ai4y50wOIlMy&QSa?&P^ z!c1IuS?eQfB35^rmvH;$IxlERa#pLYEbDKh)`X)!<2GO1p)z8jNuh*ua!w=+rXEHG z5Tqr(DUKyL5L{BrED_{>e!y13+by8 zZ61`j$l=O%TcWrzvT3yza$v{bpy2*|&jKylV6Hcs^F9;mnRF)Dcw@@5n`vyAj>Tgn z5DCTUqNHQ8-&Xo+AO|_@Dv}D6XvHQa_sHoL3TE;`YKCZUD~^rO5z$?zbCtM=+$cUK zVQvIhH7tqGQs(AHjP|f4V0I)JLbGM8`un6y@=Pr11Dn1ew2sEl4_)%Y?nb{T-B9Te z*V1FVn*4g|BDKFda-XAmNpZ2KC1LVLK8-F4J1A|Ddyhr4tju*VaZ}w$0mPqEc4JP{+$!$?sTx>%vFD$ksOiIGVUX%4>o z@K+w_6*B1dm%VQmX#OAUrP)<2S<4X_A>WqnEsxGq%gO?Kmz!#l4^)ICq=h92Ah4b> zUeD@AyX_{Es3F*J@?i#zzZf`BlI1>|$WqgYuBw%L zhLuv~7`9so)$5ZxQC(^rGgzXp*`LcVRL#+0-Gu_9SLD(OF;Ib~swJO7C{HQ3s}$GZ zK%j@$ehT@()#i{y^po55%Bu%I%F%>%YDssDkuq2)zqZ!|V@qtigdl%I911yT#1|Ey zu#E~`wMc?YNd*t?L(;^BQvKp6(JU8o-{WLzIeh(z)e?9s5UODM)r-Xgzcv`4`Q9fi zm3&sE__^3Vw>$RWjJdBUiPnIN-vys?qc|o;AYw0W_qf{7W6?uJ$+MID?3iVg;2UqH zRMWWUZO(!G5wX0XrScns;FkM_xSu6XD3#Aa-+@nFeZMN6JiRkcKqo;K*0Ja1n3mM&TThuYOAxPzz>&m*S+!BNSwFfD!@e#Uyycrs z*$y!{X&4X8A#4Qf(k5e9bPR;}3L=t!u4HyeE+IVTAHmcFJ$q)Wj-TFb$=ijNLyxs{ zS2v#GXSY}B4K=3OSYa=zPf%q5H{zENP~tBOZ+OJ9yw}^_3m@z;zkR-)A^hyla@@!h zz9LcaELc7bs|=2~)=&3^|7sq7Jos2<>|k8k4nLs@tTIU_@EF@=H`;4ERnl+Nmy0Bf zoDTAO@)Ez^1{5Gcjf5Y7clPIR%kiq^FFjFE#(p=Q+v+~Nv-dcf$5NwgeS!M zd?~JX8O6-!SiHTpUpr6ztFTzB5Bd3~GBuOuVDs$yJls?jv+_1Y_R(6k##XD|UhHb& zoO_e9f0bdoBv|>09yV<$L965A5|5{BN?pIoVu)i9?^b&Gs@1g5a7q(ux}vtZ!OXfa z7u!E5CUZ!aXm%B5sn)M#KKd{#yI{@y5T9ccHLj3%giNX*H*m_*BpG+}MsM&H*aGB? zD?8mu(a)UVYQhWg%xM!2QYF3O5Z{GkPD^Em^b7W5UuN0+AXT^RLO?s|2%PyWO z5tk6Vx>C43WaNW8-HIE_%-IYOe1diASi=9M{zV%azUtPM3YY^I&Savc%(V;E6{KyI1L1L%z?5Nu5hXln{!^JCigl^H9I)#3%UK`>L$=BFnV8Ubfw%jQNNq9vN;a+ zh$aq2a{Vwfd^}b}V|9D{PX0_!eqgfKSl(S9g|L*+WY|a@#k;QTZ?9OyNngfK)+~mG zB5KC!btdFPO}+?B`SY(X?>eFrD^nOCZU<3)yiiLjt)Ka?u2|A6E1-XVIBy+i#HnPI zoPp#^3H#D%&Qn`=@3K?W7f(&f0qYB3mXnYM&$#~j=sEGY&$Cf@2I;|R zk=s|X8f-woK#Jc$T%cZEya!c)g*GT%TYINm_^GV#C}+vm1*Ol}$@ZLt6hPSky7UGS z62j3cSjihY+tGeNFU1tyec`SHDXb-+Dr${JEzKCkGF5&Q_yDGW5gRuOY&I{zxj_adDxNkd`ZzVyQ_{oB>CwP>`8Q%Y!(63W8i8Ze^|B1Rt#Uu8}R| z)Fhyq44P|F#u-#4D(mVI>&vhDt0w42)d@Y*j({tkqq298AAOmlHs~8jh1#81mkS0W zf5lK~uZK#qZomuNhJM-yK+xp9@e2p4y$^YPL-gWSlF_;@$AzT}CZdTgk)_6igOwx8 zQmVCsyCD8FSjhX#y`Hu;i$t{g-h=!Y9iS!B3~emHoO4XMK_&s~{cM>nXNp-7yP^BHRtSly^Nr}5N_!od;o zu47;a7J#sXWy5;g{qJ%g1uN~$<}Aos6y>ktmiS4RJ~o&+vl$ay(>*M3cAc?tD;~WE z&zMg3Z&!`$ZKF+u=K6@;M3r-e{F^}>b2av!h2eIc8`NUR`l&Wh=t9a@5kYu5bmO*! zal@dI`YR>=$=rX^HvWbRKrWuE`4P|qpz zeLZ(#T>KpC?QLkz-fHZu85BDzckMg4F;9oDVD8?c8gH!V-a^zf5d5bw`=0R`QMjsO zse&e~W)>|$u#cpGFts@E*d}F-_p=b=mz07&P`}~bOar+2gkK5AOh19Yrp#01EMJb52 zdyKA;l7)NI=8D=Ti3_XDM*dvl=qRNhee>22`*D%c20hFq&LBfUh)+`GrLK2$IA&DN zYML6iOfKce;!qOk^r7bMttR9b3+>YMmJ75`M(&1n6}U#z9jieBP!m)7s-lYRX`i;1 zy^&FVVJH%lG_MU6J~TbHliZ7}Y(RJDNVo>twg^KxNE*m7t}YJ#?c4h=U4A4KtNsR{ zM8MmW=*)`hnf=&e##?otaq0u+S)6Hf&EGpJJC7rZ$G$n2JuN}Z`L7-({j7*vJKyA9PA z$1uwPj`PN4HA-{aRj(N{6Vjq_RTL_Ds03*h=Z-ZJW3C_K+liEy*q2vjyfMPnKp9e6 z@Mab-PGo(&S7_@kB=9%NVSb9L=xr9^miv$QeLM!%h(d&(0UZYHre zznjx=-wU4kXx2Df^)K$0uFbHB}a(@QVuGIv9{^{dmqK|Wy3*paL{5YBtWk#!a{Qb+z>{i(*s+0o7*b93dYRr_7Huq-^#hI~pb5=hU8)aJ||abok=>E0o;YlYsJ>Y@FlI zoxYl0g*NV>vfH&EoAn?Ydrcf-#x2}^Q{Y9e`JJ*`8QKrBuT1od`*77&iS6t}f!?-U3>e%hvMog4e~*-CeU`Y-HhqU zJ%r2vLViaZro9wP+!^}$`P@#5vEC!+{D=!Vgxu6wt~Tq>MG&|9te>sFK~?AG0A9a& zy8ME=b(nic5DtB)eHsV+rQpRzdYibH+B zTcgERvCyq-*5M^T1dLR!F!K1s63e*bWMBNyhjaH1TI@XA})_-re4t8g2?yG zg^bl&7}&~Kqw^C1hl?D~>_Eb@PId%=2in4abpeLII$cB@6SWJTVNyw5J{hxyN{6dx z-V(<3!0M!BWQI7Isv8_HENpU^YEi%!*fDxQc2%UQsrsT+<}gFG!Pc^~^VEOn1J375 zweQa^JHhh{Vsu_j!7suvWaOpPRg@Y{{F{Za~u7q9}=NAvKwYs zUN5VT=&RqiUI{a&VWNt1S`?z#aOGsD+1eV<>Ou_Ft(b7Np z_HNCc{B4sDqCkCfqo5=)y_Ah7U7EQ?mfd_kq4T;rKHZ>O@Hbw{<=&Gj30s>r zK<&xfE7F~o9&JyQE&l0Xm|f9>zAeV-AYdtWO?QHgO2R|VAu@~z-mfUr%keXZj9z%j zpx5EH;R)gHkU2|9gn^ZRaj}4RJhHBqUfKpI=*jhjuJtu5Gm7O!WBNqbb`W1OIAKf) zV!(LCtdKU! z;%GeJ8fF-U`5$`rk%-c14m8f=<+xE5U@q;61IUjc>(OC`Sr&ikk;30FDm>^noSMOf z4Qr^X>gDr617i*5N(#7l>oZQC?s|=-Qeiwi$$4xIy&TH#Xi+C7&Ti<)dsm7H)$pMM z6Q5P)ppvte1|RZ}?9Hd}cNFL1>di}CgBbGP4QUkG83vFmtW?LI`2v$)$ZbnThV65K z3qBf0HAvwtd5Zj|{H^=#V6Y}nHVRF*mYB-T3-Z!qFx4@VL$^GPLN@Kj-COotu`4Ye zxV_4HPm?drnl9O!OrHo&gQ#*Ji}ylOydr?g#%DX1Z~oVZ)j_9jcl1-Kuie_n%SSe} z+*P|t%$G6)^ga}0CSD8ZfvP6QGn!lx#to7NC#rOFS!KXxJtk`PEP4go9tu}}k+A!< z=2LIsw47sSREcx7^pU>yBG}zFewiv!Lgva?;%sQ6yo#%arNq@nAq?=RX=5>Nqn|a} zIjXboixw(UkXa6rg+7aDZ%4Zgg9N$E@JbF9#UBmlpS@C7*W|Uy8t@Q~ff7=sUps-Y zbq>Dtj0MoOJzsLtS36Xx3YydsT_aZ_4^-)v zEa-Z%AEZny&x6zHC^}j9E|^c5Qv=+59XvRts+*qCB?2`p<-&k?b5(t#xl$muU+eTm zG`wasMv-aPk=JwPWpnF7w=WYGwOXBg_jbw6?Z?Nucb_qY>L`j2`185QyVzB5$kXbP zhf?TU%Dn()Nk%T2J!jD{rbyqK`ogBe3M&Y#fMyO)gtmhCJaKBX*jjCEpXTgt()m^` z$n%0kK~3H{RiPL6p)qQyKn_mgP|$1Mkn4;VWw|?-(L+7UGTwp@`I2JligVX*(Rk49 z)VI--ZEz(5L_FVNh+4}FSg7fRr$q$L(X9R*Ou1TP4=Q6L50!;hBjRA0C!$rU z@__E_qnplwlqDsa&o5*5xBdk1|945K`ZcF-e8@@EaU{H+-H(^Cv%z(D8}NBKxT1Nc zzpiR|d<2Rs%^XhCfrJ>hFpEhc=V(e6?KwctA{P~B`N4J8M zUUX#2y)|_sTJ#l`U6R$(dccz3%!c<-P+@QI$E)^#i-N3n`wC4^AlBQB2~qEfZAkYX z))&0U6hW>Op=hzr5M^abpwzltB68d8$)tScM`BK3Zu~>Bnq7iTR#MVLliWDGtlDVM z;IR#TzYg#YEF*D3ql4qyB1qU{D8+5N=6HR@0i9nO7B?=5j>)dDvFi1&`}q7#91UGp z*WxqDmuJQYU28{j*%?5HTHiz3A8?HSw4p*=O79sIoe|T%W&?ueA}Sn>nf2gj;EUDQr5W{zljY4vV2RZO8E|&K9q| zb>3$LiixSHSD8v7+GkIwlj_|h*QkyH-xig{6pgW9pb4GpuGsyN@ah~aj^Ep7Np(+0;>Xy zp`JSRgV3>L{W{;8`Q8{sy#0g(OjY8rk*|n>0Rsn&0Sheg5r$ORWPr$RfbPe=gRhLTFgR5P9{CavXtA zuDzQsyk*hYAEd;c1btpa?zH3A%{6sVHjoMuDzmB8bVpRd^|elVfgsykvYfM#^@EFQ z1USV~(vtbR+6oKR2^;Liw}<&NqmsK2tgt4AkpQWcV;AT0vvJLcBov=QEH&@$)SC0{nmv(24d(a%|WEPLPx$j7nz zdJs+~xg3qEn_zE@us!ynftuT8EAjR~mCVI_7bO6fD-iOZZxoEV^a%t^>}SqQ?n|b) zAFF45$g z=XQUl=0`|mTzu2`DYQIQMp(>p`=*&T?{$2G1KX|jHoBcgS+^cy)}>GcCA*njw(pSq z+e9-?tJ9`b+0M*F^<{lg8ydtd&pG)g!Ig7!N0SG1=-&YInv43$4_>JyJ955e+XR^k z>9VX(`{ar~RT`d5Tz3Sd*(lE@S?Y6|_gH7?O;TzNM-9B5N+s74xJbdST0Sh4;al*t zZ*)oNHoViEQ=ID;dwiiCVZ+9g#=(_PC6QetX#20U<-uiz{ABhm%sgzgn`HK2-)!fUG5-}vJ|k1}mKQikU$j%QGXv%9XvSt`%h!Ls#Q zHliyW93a!_t{sn09hj{+@Uv*Oa`Wh2sBM&pE0bkBc{UqQz8&w4fu)f(1Z(G{dsm>z ziCeuM=CkdZ_L5s9dc&~mGguJhosnJKzqt}$v)|V11Ro-*Bc0p{sNrH5s<9mmXgvr| zx@aqx-AFGi)QC>YPj}+9Jmd3(W$MtY&ujEYU37(MMD1n6S(n{>Yl>i*fv@cHI+7O6 zPYos!;)qOZahT!d{220&FK(pGqo>dwA!7PCRzpb zFeTVaO?I(*c@no#!C>s9N$pbWrEIV+2_6Vs;ito>f*wI39QQqI8c8x!8oz#4Ffbn( z(fg8-=R@)~jnCOu-~1Y4v1Lz|1vIreKNeV(Xc&g?-tKMSG_Yu=*Uv<0_X>rFQcsi6 zBvr=)wz_uDOugk=sv^T8v#>L^`yX7wkk0S45O0Qpr-OUp9htP$h4J!i^BHj!>T8Ua zC__d@=>W)C<;Yx`_+ARKx1bPsk84{_>)?&{GMoaceN}cDdn^rB^~R1vZmS@Q_IwD} zzP#HiQ}3jnvUT-N=oy_n4Oci60}Xr5S8x`OpPEmMse48vTCnNhy0S8EhW^+@(~EMf z@mlAyN*w|aT5sRoCy*bR?(CR5_O0UqNoB3hFj;SS0!B8LlWXNp0}Hg)LP%Nq&R%q{ zf%u%$Shc>g5!Vwf*!-PY_Vr$>3Y&mUcCl$1T2pyYhNN(LaplOUx`BV~+%2L=8RxCi z{DBnu%0}hmgjy$b#L|p)8$dd=&aYFBu-KQL=Im;$5s4p*R)3C&NOtiKT(JdymX>Tn z0(3ZSZSCBP*4!EjDW1RAFnvFyJfL={5Ii$o!~0s~@`I3o6Rg$Glbn}=J}IW!F(abk zm^lYsT4>i}Xt`0s=o6Qhvf(CsbBGzY4ltjnOB_QSt-6HOoMT@&H)gF*a)H6;=yd6K zPLxx9LNE(TlBBxI_Q*#gA17)(fE=?PV%cqc(2P8^^H_+5xI=ouSui>4y-u zO=~zZ0x(-$BRdZrMGocyp105DezH*JomwDr3ecrfSLS!Y5KebrN>n48wO@}Yl zukmTjnq=-~iDb&BW3boDc?+s!%r}Kf^^wxDynzh63P)b2a8_9wkDlcQ#mUqSnFbA4 z1>RY8*xE;31)Sg;;rod?$!IAk%8YuwY9IU}JFx+smHamQE#sao_#V(UaLO?*FT=6J z-%UUdm)h5z)6HQus7 zN8qo7Yb(!j_*jBnjd-#~dl_PJ!81|=0YJLi0Mq*%NlT`NvmfSp@YPoKc^^sxlg98z z{uzQ&-3Ayer%MxvisTs!=T7WKu+Is~;sr*m@S0hk4-les_wJ_EQ13W1y%Jv+W!l1x zLzxGp_RsZiSx=oQRrjg+`T)Nb{7*Tg@qHWVT*6frluW}`tter$)gOyc!jB|p76rj^(MvT}$fRo#~-(lmENpZJqS)|lJcm(FI)Y( zGH#lBs@qsvBnx`%iB89l6qO$xNwxj5U$~w&T-W>=2Rm7V&8l}FR?dgUx|vovXAGoA zf`-$x<%-h=Ri;XwyJ*>8ouVV#aal|VyANwN?c)(-OLecE5tf+EUvNF%LriL%=iN(~ z1gmRP(ASU1e>Pr!^X_V|BdC1^5BI$gECJ?eSpju78x`!txePZx`{lk#&^~`75Qh>2 zFN8AWcw7c9A`cok*$a*)&-SmIy0{i6#8Fx26QapugY^<*kgl8#B+RjUL|%H^C>>3Y z@>1mL*1CyIOBJ$?;zNlb>RTh+?^!HeXc%Lid1}Eyke(iMFp^X2A%Nj zF$n^e#v@Ec1ro5VcCnQP;Z$P`dj!$x_HjcAIN~*-5a@(2rQ{oIzYjGD-vf29asQl9 z_V2(I<`hxbyJ9V@zSM zTYfO%qm(alh1ABx__I=y9t(8DY@ySO{8$mAM5`t5Jl{zg61CoZjyrc$oqEY5*=$==QJ;$&VdW1=M z3<$_vhO-aPu66qXe$8!Lq!Es(Q9NY%CFAtt7SFMIwe^N%9ItlbDtk#{r-KI>(TQ5H zw<3h;{+GRVrqjBzj;fRLQI9=QmyDbKlGDB%Ix9W+v$~mC$rcxbtAPcdq%@)Q9q}4Nca8Y1 z9R5z%OcvGyn=a5NodGckF%!`$sYetShL~TPn zEpOo-JWw8N{xdbJ)5c>iA!TwcVRYcklAUtaQi+|NEbwymN)N-GYSschI=h_zZN3}) zBf7`}RCt0JJ&bQ8iA%iNq%D-%0I%Rk%L$z=Gy4(jcw! zd)Lwzt)E5}Po##B9eViq78o89J z$@hJJ=D)qwk?!P>HKui{uqP|*Id4SAESf_{_vC-pvakR3RkLgg?6j<7{#9^;JjE4u zcPZ_@t|x!z{oMwC_k+Kmg}?p5-#+pG#Bt$rlvMW13mnDXp22Kz0(g!aG55f~-d{wJYHPOf6Wp?}kml%DsU@Q-y_!kjv=C4s#V4-sTUj*#mY?J!i(7#*s?>_qX!}LGE zJ$d%3YToX2y$>p0t#8G68aTP?3-xm>rH!b~rAjPDC^J5>xb4Vmqf{E6dDxmk&hhZh z*E6Qqm8d^nulqNkt~1!=A?7c?YvTO3kNkgU)KPnu>(QQP6Nn0^zE~~19J$O=3@!12 zM|=$rH;6yK7kT9$a(+)T~9*n`pI{De*@Ocgu-U_uD#EEyY*tj0>S2` zq@$;Q(C5dO)=?^zdUMZ=tGD5MRrMFhDX{oiSmIUQ*)aw__`^)g;boou?j1u5Lg(tl zslfJf-%yV4Y}UUsCkoX_*EIh{3bSqAEvX!JDvXks?PA_IMSWT?e3lK@S8tKcWL>P$0_q6}wK=v{?HKX>xlb=)GKi;ng z{l#Fx2QECR{rBo7Gs1cwTQq|V%wm=$xCFpH zCKE0X(sp|I%gqSr{cX^Icg+!I{Wf!2o)aFf5&}g+nW$Hg8PM@g}s4JNgBJ4!g5)NAa6 zpF*GI?&LO9=Gmnfh~|Zx9t=NxW-zwh!l8E*wQm9i&DpWoZyqmD7oRJg7X8&6QW^g( z+064B40bu2`9wmtbakO|+ZC8>6FBnR?3%)p$2H{RXD{sQdfQhZVUcIwk2w-_nJzz21X6`o^Vzp zD;E>!m=x(OGD0MAJ0Ken$aL;KnXVDjyY60YTNl`@pJX222b%%6c+t;s+$=|_e zH)q3&qxT~1l{hOdW3gI0@|c%9ZZZmfihp8ek0@k_`H7fbd2ucwWI%$%73~+Fjs9%j z{l8sMP0n|ZUW-SbZ=ZH|79;dgKcIy+(|w}h9H)8Z*1h7_uchD%9)>?xLkuS67O_9V ziZ*!9v+E~TA|cUk*Mlo)zq>--t9ykMOUC7%dDd9C8MH(5H%X81`r5rWaVqmrr!Nz_lN3XRqDGHnZ&hOQMK={Kdhn760S6dd5Q8!2GSk}QGehjJa! zyEahQ<4s|!Qzm!5=E0G1ldUWxC0(APz#T+%wyNY(p`(SvQ>`F9;QiM^^Aj7s=F$vIg@n`vsBaO@=bQ`s4J)0gp0?*wixe&z$h|} zW#kprb@qL{Q@oT(6O!NHpmzU2GY{^+5!KBhb?qQd5{B8_1DBf!6()UXuylc&Ns=;eVTZx3hjMb!;7A85Y zoJLKC6?LOtCda9oHMKuUNT40{8xW?y!b zcS}l2>nQq(AwsttuduFq@{dZNwbr-;IWsNXC(niWi;^#R^qyLP?vyO8ySdCHtV*K# zi`&@v-1$h|bnFrD)u2x6@Bz=^5d~bA2Wek&Vzcu?`C^M#fpdOR@(|>C?NbXhGXYq- z;eFS>C12)wu7KqGZ#f+I1fyQ^^^4N7kNwOtat2Crt*7dlbK7kANUI{{YQZ=%xyQp( ziym;+Pb*cH03eR?rKJz&d&@hRpQqBZj+rDFa8btzZ(54wNoSQ$`!*S6F1!2JdL*N1z(a_XvHn3nOB=5EN=^CsjBa%*(S zaNZ!z31TXp(^2=$shy-&m?N@I9+q1x+P$x<_SMdX*43uNbmybQ>wbFQ8w6{g5TT* z&PVTBdz;AJcxQud($iI^+pv9WE9OKvrS08t1kk8$3FV9AlsQL0NPSAzs3BYS!xMz! z;*aPF5q|dT}0c47|sn|Sw9Qoo~{EhhqSW~klo|gRv6dzT4qAs3ZsPJ#Z zv26VYY$@EEg@%~?2Ixfx5Pkzfs@Qb(@H@7zHEGPhl1=l^$X{h8|5RR0 z)z_l@WivOd&u1>)+1K)J3AK0*n(^?e`LG#hWIT;$1wAyhUrg0pqrkzR- zaWFHxRBk76(&y(yf|el~*D2$m>RsS{2jJ)-3K-v?B$@5-n#5&>P?PJ{}_x!+mD8=2OgNX%gtv=_3kWn#cCU@&_}@QcK*5Aahu+A2js+)mWx@u|#} zJ&*edQIa3RyeMWT4unjGB}uRuaT23uThDWS!RW#~ggR@Rkkw7`DcQQhK+iCW-h}$) z+VpS(9p}BceXz;Zeo0$HLn9YQ_}HD|EFJ7Xc&oiiykFc06&hwkxk$Z!ox54nb+XCK z1dG`Fm)nWrEjcK;;BUGa$C$eXEDyA&w{gBC^>?{M)DMinenC^tKpmz^k=#qnfk?VYZhVq=>B{SAHyW>c0AqRxrBreHKR_3@dS13Ekw=X=+ z7hhM=Rhal**Yd8_iL*18h+A<<1*kN)42dRJSl4mkUtg#4#Cd4ym}=f-7xLw+8h4x_ zCFm9NCtlp68#B}+WS+At@~ej*jFYyp?8(@u($6NO;Ko1dgtbbrBY@$PosIVh-?pa7o5i1*v|G-Zb;5GsaIEc5Z?h z_1LT+VS7;9_}SgcX&GX~aq@(-u*NQP8KZBXo9>S1aN-?Jp-s2z1Ls&3s&8E#YLw}d ztFG6H;ptrA-2>@o|gxywwfrDeWF5~y^e`*Qv)R7#U5Rh z`R5+TZ7V{}6?C4Z#FiHdHl;LbrM$8pY4WLQi+^$6MRV;463}<@u584I-6o0p)}V;$ z3t(BR{L)am<;J_%{ppAzKVmlAI>uH;{_$Z~%yG!^4Wyf7>mPsB+4L><(qE|-WW>4u z@mHcc0Z+f#p-xgq51e1b!~|5h)fmit8T0`g`Mv9!>WqEs5h;5^8;_dhSTbkY3XE*m zGYA~_&>u50?Av{C@va0&2U+v|F)m$GkQ}Lbz|iR+ZQeqjWss~(?^|W_sA%gtPGx=^=S?Ct;7pI5XgtDJVygn9qMoiiW`3>OQSvDW*boPIM zmpVfs%6*c@ECmy@+24s^#2!86FyCa~%n(J0aq!Xxt71958dEwF`XMF9$1Ff)&o5z4 zT#B>l8Wu4{mzx$#{Ws)|D&soAo^5=YZp+NZB}ItAUUUNd}f^0_K%MT`|Z$1kW-+UHJjO$x(UPAG=QKK?<>Q;zDtScd< zWFN-~4VR6Ajj<$nQCRilM6VL1eN-Z|j;~CViISZW?joBE4{>aqE0>h&-TZ=vfpsq^ z_!7EyMU+%HaZYpJvSl?_&ah$g<@=h6Ifrt$fMSw4WY%E3AU)v1)r{r< z$-`C+Bh8$)c(d8KI4kQE-a55Ak#k4vhwM@~9k*^*Peh1R)r!yl23T@Vt^1=gy|dk; z9wJT&U$>|C8B?N$#^=9ko_B`WD;I~c;0?P;g6CDqq}K!~ePBrSonwZ9Q+2)+t$_KJ z#AOQ}K9pOnLEnac2Kd78k7bT{sTlL_>tc_36|7zN z{=lxq(z9hqN3$_28tE6vE`gA-%&*J&>ecCldADG>pkujN@&j3a^4!M0-1{yXem`Yak}}@uD>~N=!n*8rOj>oMy*4`xRK*s zbD0{hzU(>OJ_m0T6VY)x$!~c2o;9CG39Vmes)(h@BwTuAKk3CXBzLqgjhJWWwo@-t zO4@7|Caa8chg>0o9#+SNXSzDPJ`;Z%GR86}?uks?cPn`*=J2U^fpVJja}i0`1`$TC zJ3ive3uogQ?;tFy0nU*{h)g?;f!T@G?`dnFR($tB`7Ie$4Wev4B_^fSzjHc09`X3Dx@g?Kthak=hrUc9=d zLq_(~PW(Yo@z%YGAF;P)*C(4%VGJIjRgEso;#F1(m9&5Wm#&|oamV=gC&9=uB+tu} zF}XFFoB74umzzDkdT4irMvmNa(qod!Y_`f~NZd+nmfseUts3k~lh!bmvwHgRiH0`s zU0terEnuH*I45f$T##3(Z=!27j_>0k%ho?pS>Ev->Jpt$>mjnu;_&Um^&#!LO>y2A(NuAstO;$SV7L=c%KEtDDL+#V_jo|~1Dm7Rw zL#s@ejik@jVg5Y*S+Wf3J+s1%yiLpAScJR72bbML|KEVom4`#y8n5O=uA3qIT~5uX z@02WXSoQgDsmI4lJ%2M==SJ=iy?VpaW4S~X$SC}7Vx%Qsj-`rw+P}r^F=#TYo15zg zsCtPKd*I;hTCHcvC+VwZ>FR@~8^*(~fYZ$&3!vbuUFIGhJ2wh=N}NkE4@wJbM<*${ zf|M1Mg`7JvN23a{Hle&u?RDe;(Az7_l;x6xAEG}Fx{3BzR!vxP2R5IGzDqy&*6j!E z+5U8_iR#w2++`Ta@R3iI+mafOG9*`*KWKQpQy*ue#H#dKkQX4a7}u_hOoYwSxip#X z9uJR=;&t@g7%TDhi1-EvmQLB8ex5+g?ID+xQb;>kfeWMmo{ zs50c%8WRiP@gtJxjhl3YUSXahVmnCTraza!OS~i=QBr{H;B$GceK<$BZez{uD$iCm zxaYVKOHa95y$aa~N6(^kh0_Rrvi=z+ zN;5EW0cYl)pu_jAgO~cgm~>O5N`1tXFu7g+HxG!g>E6e=J3{+-BPL0Y%~Wim&|8_C zyoDu5GRX~|Gx-(ICQe!a_@i5@YU!|fOX4K>slfYsIoXxKS7OM=*3<#-{BftvvQ9Ez z-M5Y9m`?`@{esoK{DV2ek7o*Gf=^}hxSKrh$#nTHdd@bB7>#w}2zY5*($jl2Qj`M|gwk~O)UFNbtlSdYZ*}C%tISEUD>87d zSX)vwq%qmP16)4m5}n!3&*y5Vq;*~O?737nQRM9of*8Ql?WZm0^@ed*ZX{WGWl%JIk)vy6cuI zJw03}id{59>b-jv73jK=;prk&`ut!+9PK;7iVZw)Y^N4@OaY8Tkc0T4E}{)q7LY`&m`DW#O^h~94 zqXAhw;EM8N{=`Kdko@FK0IUDxdtSnrv2nL{&p_K6K)(5}WT<`J$WIgM#(j1(k-8aqZ6Ayfh{x9asW zUHAU8*YvLL+SO7$)z#I%))lv~MatUT+t2+FS1pD=5?hP>L_c(ZWGTA=oO=5uSz+P? z|FyQw{}1R#u}-H;6uuFea}I055!eBSeM;QUyBQYKfiBM3!4NPWr}k-KYa*S`zD2oYvl9vbWup7@bs4|Uv>+h=f`$W zUN6V8OtdN5+n^bnu9}mZx{+k}*$HP-hOTk2)BdC2d4KEr? zJaOFCW>-}~i`@EIMT3Kj5#e#e^m&KzI(|)VH{re}pqgQmYEHHo5`$yr3t9&Y2sWAf zfx)#x-kDFGHHeNkW#WvtcUob>_OMzPGEmQJJ}J7|D?M`w+$U_@N1308_HO*(8~71r zXTa(eqr?WDgMA8; zLoEJ!dp#sQ#itglrKxuKqX`-}PZurtV1)0(XTn--hGgCMxigxPtZad`J8u0dE}Prm zm`Z`YRAG`yUJlUVfp1^E`B{68yn6j$X|wqUWC=a4R2w(oCeXA?l>$|HH@SkmFI`HP zj&Nf{op>FuSkEdSJNsBl?#WC0@)@F3Efrzi+T07PYWuMnhpC5SDd7g5^m) z%Ui)D_tM&WT^&mXR}_g!&<_;vv@Km>hyWzn)=xS=P1am3j*Q>fZw)w8+lz=cd_yCp ze}30mzm17knCwvQyzsEl)5O!7>=cODvzeA#+^lQGGJCTt{Pt}@Rsk?cjd;*)ZhbOn zh7+SpuVz1BI+nLcsu$7YiEt#uSvPe9r#dP(#}~=8c857HHM2q2S5|WnM0><>tjPfy z!K;ZJMV1Rn69l=`C1*~F6tS}AyGjOBpSbPtVKlOq`5Y$)1>l6S$Qn3ZA}p;8L)Jwx zOC^Y?kG{-h!VKflp%z_l2E`GOI?$wbh3N~gUyQY6kMAVYGw3wsWyYU&(`iVArOB)f zirRD1f%f6J01!d{qm2TQoQ+%A?Qr3Bs9W8RfUShvl)y)+_h}e?Z=)VUO+sYdIQEBP zPov(`An;ezY$4H)UK39?ISHGVoSj$8PGT?#?7l7yPtIv?O}R}UMSNlLfV!vV38!&a z)JdgFLJ>`zplii48{fVdZAlw%_U9(uZL3}S2sKn&9NUs8)GY^=!w~dkGA)HkvU(@i zd{3Fwz)9Afs7t51Q7!k_z(I2Ke2;mD+q;%!%eYOX<}a28S?bNQqb-uuE9 z$PSY&_q*6waoQsd+a}qMI&*H~q%B+)f+n)=@0eT(^|79wkS5GlYH|zr43esE>1P$nnFEq zeXzXihE!^kIgtWSuF;VKb|Ez2A1K-1xYNMzfxw*weOHy@cJ;;QA&e+;LuyJx965bh zPoKV*CVooqi8EN{vi1BXD5lxQMKgJt_JWn1^725K)a-^T zFx$VoZR=awC}I{mJvu2+msAPT^de_|S5rsq^_sh;7MmTcMHsTS&L?EFaT-KL7JMpO z5lGGS-!`g(lH!(*e4y`ZXJ?IaE`2EZS4v&aQ^3ftwN-E*+w8Zk7GC$=<(Ij3+Fqh4 zjYypfJD2uiHRCT*{Val<&kC9XVOCk-r-fzmCK^)NJ=+vL4MN<~ItD%aJUJmT zc!{13!>4lvVGGLCa!CbGYE-Giy_Ymnug1Zy%8 ztCf^vvVn5qJ&b`G(M%WC6T6^vIz|bNYzxR7T98va|NFPe5$Tw~_S1BlW1=DL6v#F_% zCuQpnkG%dMzbc+a=CrDxc8i8Xg$G1^@$H`t5eMgZ3hw+PvTrOQv zf`TD)DW1k_sw68$c~w9_=k2rouH@G20OGX{P)i=n52Pd8SCj>#(EuC^36~~qbC=MP zT@E>i>j`~$>@_RD#UNy#j;Xs+f0{n!PhZR(ET>u*MSj(~w8~KDtz!0% zF~U{Bb2E;yTNGV7FC|^xrgMn~IDevrl1}|;eg-aG2-gyW{)RDa|Brp7+i9jZ|NEu_ zi_T72f-2bzxTk0D1qDB}{Q~G`RZ1tf&Ez@bzbZMHr*1Hd(R832@`oUv9##dMC z&@E>zlG#4Bg1wV>?Ub}3W?2f%J@^dA>|3C>eoE`Os!7hOp+TU_R8VA=mzp;5#^BB7 zLC-p0WVf-)uGV(3NI+}N_DuPtrZ1AWrGt7M=qB)oYj$Q%lfeN`&BfJq5r2`DAq``q zKd&(k?TfdiiyR#ugo0&!XzCgxJ39$-Z_o>42G+Mb9UK<`hgGX&&NGN_dBM|7Eo2V3J!Z_y{0Ez@6Y-+r~kTGEoN#*c6?kcSdlueCvh?t=i%fc_8(m_Q${A${L(^ z>Rz$9;8?k2Z3~LDw6?Oyci}{kM8~m2L$+g%tjD-WDoujKPV@{b(z(NW#@r~|+ek&p ze;5&jPL>+xmE53SOy=vfD`=l#@8@=^4iJC>7k531Qd9-RxC*;Qc?}Q|VJ*D=j>OPF zALanHKUwn?Yu_hTe@y zDay5j8?kC8dNcZgs(KqRKh**U*`_i7y5pS1&~3MtcQ*-Rpy|z46u8KOScQ^{%h=Nb zlq|M@(_3dZspH^onsLseVrWgn1}qKjpti2Obqk%!|07zdE&k`~c%4|(UB&~3dfcR(D$UVVsdL0@j-LFkecr=p-ut~a}z0>V|Gd+jVz2-^c~ zS)L%Jgz_J!)$fcE{+9G5pTJKm{;bOIG=d0k8L3+ zAt(}Ydu6M3nWc>rW;ONN7Z|@wimY`)&o%Zf)*D(4m_lEy`R{|m?LYTO>Yp*A`!Cg0JM3ghYPIV2A7$z3hG}HQ9ir{ zKlwVC$DzEatk+#tcX3NdM*O7vv+M)WSMw}H6+6HdBO&H;jb8a_2RaBTE}omf0^ zZL-)9|1sw(ocWGr51iWa*Hww~jauS{thPLQQ>TNqbyo&&q}_32r+hGZv9*dA3$!H^ z3fYb(IZ_s=qN*e-OYc5fxFIaNv%X@enUnBs6I0yrVCO^6^cL4AWulmAK;1(S72@?? ziE~E@v7&dSVbm82LFI3)Bq9el_&-GQr{y-eMhkGv!tok_6bHX8Duthk(wQM@jv^VG ziH<=)+taQQNLJNl2qv#r*0}JfdL31&Aeu}pGJktl z5Ej;ymk8qcY;MEZ7^sN{?DhBF+`#U2gGGGgb+l5Dz%Fl$St)ZIw|RQQ%#=nAKciQj zVzhB^Qi5)tmU`fVCxe$V(M!l*1C9;E5%{>HXA$(g4eHROaaNq_t6+15y=7(U64kNF zxvofrrKW%!d?b67qO(cF(VbJ(`i>2*maR z1Oy5Rkb--&Nr^sBO+;5>JSS85TSFab>uWU_$@VdygT4Gn|c-^b;X-E+o?iPfqa0yj}743kq$>Be|pnKVGjzFo{xa%XS(+)NP4sY8`Ip}pq~g2aU5tu9+F#=KQ?c=_V)d(L+MfO+Jb;WT;Lgs zu;HHAOa7g|#KLN)5bEQgK8#1X59tMmx|i7<@n4oXT$4#@>oEigB%OO?gMcba#f2*r zyyWHk0sT)Aj5{i0|83mQ z|BT?E*V?IY3iOrN>8@_{4ou#nz4=@lPV7`M^miFwVf+62QF7cKz?{{%lbV_-@V_7^ zv3xF_eF%LbF0MxN2#u5ev7ZGxN35Cqe~U6?ma*a1{u^^h?_}4;QgTD&+b>Zu{x5RV z5q3!=E+&_UGm8YTIQ``ouZvA+{>djqnKW9rATPF!Nj8jrZDFJp~b$^ zh&o9qtX*se-WL;}WX#USs}pfOURztsfPJ9AdD-ecx1k%y^%LP}=H(XCOI$mCGxO#R z6GOdQj1%)?`>TQIuWEbD{psE1P&ie+zOSII>4IQmbba<1MENm)PA!f-+^}crJvHGq zF464!FDZ#W+IPI!$M{jNuQ_`+XOC+sKL)pnOPn88q(3(#^ouO`E+O(o@ALOxxgOW| zF|@UleR6smJ)91;dWkFip^@XN`n#>v`ZN0&Twi~{la1bT`JV`+Dp#NO==wvuf91mT zc^|&_=q;PP2+O}DA@)T-C;mS7j~t#ab|)!+iFkEQG-vQdD8c8=FVZc#li{)P6(suW zs}&0B+edTaKzIPkudK0sp>!*RFX7U@W<7?mSNaBBvt3o*%SB(|_YXyarM_3Xt^4B9 zM)P{_eLd4UzyHIUfc1FdUl)S2`~RejZvJAIKPL!04Eu@jTXY!FTz<@*T=n%YDHtzs z;9qV3-MRpYim8k!0Pn z&v5}q!&Z9L@2Jy_+GOvTet5}oe^vTL^83F?QQITvH|(~D z7Wv^~`j~|8jlv~5y)OOkss!&xLpnc#_NZT#O=7PW4!mZ*`d5^y(PutjAI&>~{A0ZT zs5ar%IMMw3&J@u1e@FQ@Wu#(8e*tB(Uyu5GYHfSqxUa%X zTA|b`eem`kmJi!|NXUtJ|2#CmJv_ax&>kG?s|cXnI9$IxcD|SnrCCgM-CkMW+RwBH z#rkUP3HFcp@%h1XmH@~%pf8itdz2PltuRvGv^eqgw|9?1>Gz9qBpZ2qH@EKRq)&|} zPV6PEA)dTf_1{gU)|tJrPON{=Wa7>nHHJF3SWf?>HOb%-A6wr~a&XcIL%k>oPp+%l z-=#2|Opnd)bqG#+ZD@ca0pR>SGckKVJTd-D!Z$SXe(3b}cUqI|Pc6e{ou;+Kw!J40y=&C*^qGLLT7A5Xu8PwC9S_TQ>an*KEFmfwk>U+cFD zDOD)Z8U9uoK9Ls^7k=>cO9DT*3Q5q!q{+T#`tv!1@cn0fQvc9iU!ZN|ub1ER4%zB1 zXqzMpI#Ej>HoR9#rHYqyl)pH<<`ZF-xX9Qb1xAOp|DIRuWJQ>MO&)eW>f!r_Mt{;_ zz5$-}SB3XV46n8w+*}*3yC24 zF?KR{zxaRJd(_X@t#mIB_UOk0gVnt2evv%ZcjqhWguqIRC3i8a$tnFOk!LM%jOvj# z#jA!urxPXAsM-xVVy8uie`}*0CP@Jm-j;BKy3~{xa-wGCNW+;-IePlj1cGwBNl5ti zg;My)&7BIqSv2SF#_4va{jkaisR}tJ7?JG4y0A>vucr4h#7o9?+#(^v=^GJyO6L|f zs&-J3*|@-vAK1)Oz8St?`?-z}wQuVX3GD&z-VxivA|F2MhDEb5Tfo$o_QDx#XVmar zTJ=e?yMQ*;=9-;++~d`U#w4>1u~QS(dp;=&Ub(eHKh%tC+xB&KNHDyEn7+of5MtfQ zqSa<3YQy957zAY5WY%1T)oTu^n)tv^_)W;zxPM^~5Q7_x)4ugck8Osu!tw*=E!|!= z+EQHhooqEUTx+%s9yVMj`h9U4(d`Wty2iD2xkzcTN?u^ql;u-bTs1h6wti-GF(G~0 z7-6xjCynS%3Is0RNh@xTZva<58S4BHduZ!D10itvc1GQ0v^{@ktyCk zM+JJOSFUsnXbC4nPOG5bC%95~l`J;~tV$o-6L1r}6DW>}!le)gCO&v7Wf~6Zj~a9B_U`;Wo^CyQl{b z?&>tnM%_cgH93%6qs^ zfU2;G8d{M?!)7ggEqHjKLkF?D7z_r@hATj#tOOt`!%9kAZu+DjN{}BnRgEZqKHB{2 zM4n?5UO^k-+tv4V?r*@wHGTbBZ2vA#35I(7L;o(DXo?xOqQ-s_?tkWpi1Mr&Fiuc^o?G0kcF zxu^H1YgzemT>C~f<~43Lr+weW9D<|3=TPfIlxIFJrBefguGW}>M%=CRalXjn2~y5A&4rYff1yv#=shr&%dL-m@lGEIKZ?~ z*e?cPa?-#>sf!L!)No27hEkO&`N~`f_u^2!;4~C9>pz$grW+nm8pFf^}DL-(A_gaZnH#@>T18R}>l6tn-y2cfoQ&KF2B$vO*$HEV`at(RbAtmaU`(7dXk z7|<{r(GsGkS}0EvFuDS>Dj33}Fjj+ma9~EtP7lg3pcow)8yKCAfu*T^fCqK%Y%eqd z#2kZdK%(xS*uT-y4joD3dKN?h+rXUis^1EfPE(Mz(iyk>H0p0S+QTcb>J zRBYWV)6!j!j6?e91utPX zE2XtAm5bWE*$snBgkX&(neZiMMcx3%WyE<4D%_Yc9MLcM=i#QdDAChMp7r{98Bq&L z)?xEX1h)7f--!^0EEDQycn0ETSk{C70OO@K{jfm|eUx44x~&2m^=W6TPeZXQB{)19 z$o;ZzMmTx#ldI(5%W-InU}bYB<9S(GP9S>0Io-r(F?ow@?sJ^T;UH`KB#0$)we|ac zeq9|3_1efbU|?FBw_tGV_kEVQxo>7*M$U&Z(pPd9{nj#`g0E|yxHG90FaEeKxxW07 zRjH}a)0VaEng-RRf@5gYTz@1+;`CUHKrFpRKs08^y7w|*2PdpJo^t*~_y9|(uxY!k zAH>i8iQooHsgK6-JlWSl)m`8bwM{z~ZjHoF%1&(WGIc4j4nZ`XR_5$%e8f(ngx zns#4k9Td~vzZib&&hsV2BLB%rsjY)aNS5kyY-1};D+|EVjSr7=NdtXzK85^;c-5_(5d-wBY73=+j@yYQ; z`=P>ynaOb(2?-9c%!kq>{icMW;|fIMS--sI z>;>E(TR3AgEFbs=ve{U<_`$~Fvet%9d?PL{wbt$IB_er=fuE{KKr13zhFhzP^je~6#=Jn{ z4WAHgBky#!L6d&(p4D0YSYX9j-SFfq-I^b)MoadhM z_ARhl(v1S1_6B6B9(Zptkr-5k#zh+IDrEAQCb8?sOigL%%YYf@bT!9WOw@WSDW)Px z2QT|NQ)1JRUQ2&S#Kl$rjgwWe{ZjpT)}&rKCfP+1Y3a;zuY^&n<_j6&+-Ooxo)1Aa zypC0z93A`IsL>P>&spDDjv8ud7^2KHHRb6fB`%B%a+k6BL~&Lm@TYFX%`{D{3^tAH zr!^$Kyo|U72goOPh4RohuU_~3ur4p_lsUK(actMw-Az;I_!!PaP5sF396o*+_@Z|X z&!4ts7_#3aw#Q?(pZncJ7%H>&VkxmRoQwHAcX>JE_!A+R>ADeqsa)Wl{5QW6_;EfA zjZ>!)z1nD;?R-z(CM$2`TFr&h_(d7(ZCju|BQfi1Z+4fmt~^xEjt*&WNgbJyJqp2m z`UEClISI3h*#%duT3cgd-T{c`DLpSG)x1d*t1-^l76l2qrQ2#NSDawFb0Z3TK-V^* zF5R`?9e+#q$j|(VFvIQrX7ne*rwF*wD||`VQtWHbc!M}z6?R}{BT2mjX~>DFnVoq6 z<*uHV$>6HL~XBnaGv+OSeAdcVW(*%w>Bo_S%49k#2*PwN>cM%LkW9 zgq8v%7AUsP`8lP9nOV&<;&cQi4t?VK$WO-6p(p{P7LgSRs4)*6G0RSzNo(2s>%&{W ztZ3fo=6bW%ge;<`cP=tjoDLCKPOvFg9LYES!s!dXAVP=V*;m{mB>a?+_#{M5PT zl{FbD4JP9K0WMQ|PA*a`H>Y|K*(WP6Zw24Z=?e63md{J#(&`oqJ5A)-9UdjcM&LZl zLD1uLAY8UmRIxP7qnn19by}G6*orgm&n{>P7sgeNSDp$V_mfhyU>hN>HS4}XvRGx8 zY2fWLn>dS|OE)G7Yl^BoQ=XbHuszmWi@n9R1nXE_)RD*_nemQxICKSVVk+cq`L<4K z@11dJ&T0rrVGFTBoELqNZcnH9O4BmNlY->cx`iPaB4$#bKh(IMokv>tob(D1weT!U z86AkAG;NIR+t=!OUz>sp(3)VE}VJyLr5+)y`7_JHG!W%Pyb)VHlzSv8cj zimXZ#!T_``zK@hvw$lYe`n#@sc+Gkiq0Y%Q9!8Fck?+PxnpNlNnze0F^T2#b>zsS_}UyI z8#E(FgUDQV0VhA>g;{6(qWro#;Xv!Zd<7&lBrY>V0(*k#$%O>k~TjD1Nk*6L-1&>PrC)oiwW30w$%Wi0oB}W9* zN(73U!Lm$Cws}18P|ITh*=?SwlRl_?Pi>ssXd8d(GS3k9JgL|Mf=LXzOF<3K0IQg5 zwLUB=tZ2pBckE+2xg4!I=lo|RsHY{4F~lu^e-tMd!d*_|WSCt)rRQqf7MN5TBRrg+ zQ&5zYB0n#07n>PrWWPaKvwA}ELUA8Do?LF{Dy6Aq;VV;2Y?hf(n8uVOoAlA5@EJHY zm5`XUzLMazo$);Qz_TCinZuj&$0XF9?;6AfEd@dH+Y8z%hH{x+zy!FPB#Knf;3oW7nDW-bC%UjW1kC%uf%Dp6Ch|_>lWha%@=b!siiGay zWWOSc8rd4ILofdjZfHF`AX`|%%|M|hH(kT(Q=(s+vMy_la#EskL3v=5&Jga$XFiA4 zNQ++mU6P955yZ=uOX~FneG94$3Uac`@~PyIKMy(~1@tY7AwQN}N2hT#2({f1xYf=5 zRz~2S>|54UWX?UNDIwUz@`{5Bm?!=DViGu6L&`Slg;^aueJ$3YS4NgKJ+ru8+f8M| z(WPWt8djHvP7_%Y_Iwa;c^0*2hWqmC2HD}jMKb(+>3mkPwY7pR9O6M`Schf$s9Qpb zcCs>=ON!u`N!jM&)~VC!0XD6-k@O?{NgayaB1U)sUKL4E!QPo!;e@Jco0;tENDDJb zUMI|yhs0et2mJE}jV!HmHAkhTP1~D`)IiN?h{VZR;2g>M!L%(~ejC*Nz^+*M zR+{C``|TY&Wk%Fb*}&YHE8DStB`)|45OQjm#yH$VpQ2nogw_tvA-}lH_d2;#F5^x} z(>$l^332O}5*~3Ed$D?T{pIQYGT~~*zRd>xn?7ruD+QYEZw$LM2T|RmrY=LD4x>-X zEy?C$SDTT|sFy~l*xLOzX4Q2(#hTz)_eE`&!l<>nUWnA|Y(su4W9A_;00T>tDV~|66pl@4 z=ODb1b)oRFl|q&{ZBlJImIYCJ>m0<4yZxOpNM|PVj=@!Cc@Ael%q*FyC0iYHEl_y@ zgt=}hycgt6eygcK*i@WdY^vV`esZ*YHh?+0r$JV>Blsy6^d(7}OwLe=1#6yWSNro( z&C~;&qavjMTc%fJb}XI=&50h&S6aCKo>w> ziWz2Ai(-*eH6UJbE!cB6T?s)pVoNM$y1t!Km+u*3g}4v+-56h%HSybzaD+ye@6bqz zvm}WtU+|sSQEeC>=m&;0=~zIJ`j*xP#yR;TYE-d7$)=^%w>}wIITAVH8Q@!g%zt&?$5eqhYg&7F)NyFW@WpeS$f$pYT|F3Q#T zhI}wu5EQT&6hl5Bwp@S%qdFAxDa6Rglf{JTGDkCYz@0|GqI?m2B2|nGCNVLaV5*`m zCb2J=4-z#7;t5ft;qDGGn_?3-p~3+iQTM_DD4JJlIW;DXvpAjF6r~D(-;;ndpAO|D zQKMfuaGr@X+dWuPS(h<|K=1ICvJYsd2mlkA@;kS__jHuIpQ{_si%droJ*tDPVd4#z z{Ch9>f8D9CaS~zFWwB%RR)ix?SS-{s+L>i|`e}z5jo*eV&D1hKXLkMK@ik^_s;{ea z=+jq9$b(AGINU>Xcg@gM0t%qu!zCR`e|0bEJ(j;{J^z8{W2c&#@P|(CYVjUXWt*m= z@-KYP-x9!$0@KU?0mF?(CSu>|%qtYBoTx8mEpYw|;IfCG zb{MopdS2F64g6=VYkSV+$3Wz_1HXy;XOp7wn?RZqqt)Y6_% zWLX4Y4SAEK2l2Xs#YA4&b0}(P8;K^wr*5+!{n+xov1otza{g4(W90U1 z{QVR4gh$CLzI1n^N&l3Lk5=1^czKz6yPfr&wvdgIm-aSl-iw{(R^c4bJwz z(8_-cp>{V)!rYT^m>+rs%xUl$3*Yv;@EAAv%_)8FIIG3-{f$TaLngV<;fKJs1h^29 z1W>`B2$Nk`vVQYW2@kmFM|bzlki^x<`747j-o2DvS2A}aH*nrR5&mI532()fy+b%l zzZ(xfcq6Vzcuf36_)}cPm;FB#h=*6bC+xoJYrmS2t8B0z#xk8!ygirk);ZZBL=|Dw zt2eaaZWDCi_lqf9PQQn4Kc4mXfX7uuyd_woi@e>)HB^5z^716%ITcNGXDG2Cl*g)EHP2;j#DuE;J-eftL)#P60Tpn)YOB^>XVJSjMONoNgQFJQ)40pJS} zgmugir$_P3T1%W$y%0#}UJJRFWoajaNQl9aE;$frqDzg{64s5nKf;p7(Zp;KbrzHW?$p71165C?m&Y)AG75oSr~+j# zgK)HVqX68`5~kM3V!3(zZpp`EE7=!OD0zbu|^J~ z@@FB&R9hU7n_qz1Gr=k{qkR)|Zk4qW!MP!b;_I@ z<=~JU(??@2tz@nZro=EvbH#SH%asSKjrsd=q4yGy?ZO2u<2jp%C$BNH(Ev1^DWyo( zTo1V;Od@*VmL!Els(nL0o{Wtha>RrEIYXu5GjO^_X1$2<-Q1a9ma8viIYn`cQv2XX z&?}ATI{L0w$AVpxEk1uG(#DfIu7-WiUWgUn4_2@2prtAbYlpNG!QjWa2-3}5QxHeJ{&Xx)Zr!p zktQ0G|C;Q*rI7c}+YuO5#s>Ux0H;&6xidd#me_ghLv%DPNq>Y6Ah z)iC*M4fVjshD=U{Ae)Q|xXIfuW&@%s3QQDpY*q9L3xnIl7;qZkB%@9?1tbCZ$L94Z zfM^WB?SyPPNp*8COqk4SVf@GjCEZP7d;G4!;cbI&Jv)ZM_D+u5EMr~uPlV#o1*fCh zh(^~aV(?!OGVJn|XQxiSp)9Zx58BuI;MvSWB40G;>G+8WULgDgKX;AED~zQ!JEP8( zJz&NOxXw3W^G0^;dH6LN;4O+G#|SHE?QV&;a9{2K-t9CwD_BKVXh)O??On`HwMn(* zJqu~+*s9?sdno$sgH5D<`|EGv2@I}oZVPtf6B2pbWkGBi5P0ec7S$!nsGU2LvLpr=RLTpXm z#JMUh*m4oApse~0v!}2*QD1&rFx~VX2!K?yO_UE7+k-QE$M}@1nAwQB%k zM3S=P3+EdC*vNT-Y31L?ZU3)r__yWxjo$v=?ocfM>CO2l)SgL@@C`^BjN?n9UfE2h3;kKU7sjRsOCykaDfg2{3Gt zTo;H|h1qh2T=Q!G*i{Kp`wB2G&kqIgpA@&GVKRs-j<4{iQ!SQ`RQiW-BX%*@xXcfB z7H`{<@gK67_0lwOmuXH45<4RGgJhV=W{$DnRB6^c#!4PV{F*-3`t;1;+GpQhN#3o8 zF-;c_2lFCq6`UF5kEyL;u;W3>5ebJk{5%<9Z^v~W9E|80o*k3=SOG=4{B^t=v68aN?-@MS(%G_37(n(amOOZ@v;1PNIiQ&tl zkC8I@JFU3!u*ui3LCc|6b1!I&euNLWzT}W8$n0A-5txl}`Xt2- zNgd7qbRt9;3C23MU=|k96bULu|ui{RM275F~0I?r3E_tZItE8tcL)7xyyl{*4| znw8U7kT!({QOqeYpi1KvowKAP@nPryA>T`+jm=Kyr8LA)!1aq(NUBIwjs0X&Lie{H z^s_E_B>I|M@zm!U4!})FQ-)qwM--xc0XzO-mbKi-{Id)X*|AXrqkR1HsY&#u24WIP zSZv<*dQ#!(E7IXFOZk4AE0I4DT0M*S zWErrIWK}*iVHI-tG1v*_hb2HCRcDr$=jW@%Uph|CsOwV7>Zh3tvhC4SREsBqyD>5f``|WB5D4y40f-qn*1E9*W}e3hrZK~-f^l;=~x z4gz4nOA*3N9u>G_L%kpVd%#qS5&jG&md~hDrw()o+E~$eOcUR%>7ysIkPyP|bgtsZ z=+?e-43F>NF=o>@4l(^}v;SU8np#VEbM`R$xL_E%Se#-gT$1Fvk*u0+vK1lyd_)}>S)Y?Eo55R3*=E#?(cbJ`bZ zp^|F}s101vC{XlIN-o9I@#@Y7#-VBx3a+_hSk=Q0Avy1gigUlp(Zsz3Q9mIDZ&CB% z#&A|}4}aCNv{NFtnVuPZQK9!7xJ9n-%$U|I@ZLf3={if6@Cz4Cf?=Tk1JkMa!2ES5-VopbVd z)K57|=`G9Vw|F0#;e2N&f6chqDAlB;cj(rm)tSHMOV=7dWD2Z2kF5oOR$j^2u9j%d-S}zF`fDxQVH~7BTgK-Qm|n#LVZp5?B%D!W8nj zRZY+PlmIkUGcPTB1y9>0%F5hkEGJPW)(2aC)z$G-AoK)y3fv`Ws@Lgk9HEtmZ@VrQ z6{Qz3j&fvmeI;C)G`+Se7VHQI1l6l$2LApEcT}ax>Tlb zR}iyf<4k}23= zYY<-%uAFKk0@Re@bOCx(_V^#5cF=Fq%CatAt3+#z4hXwmYIVsDER;kQ85c5T7k(Pw zGHreoIf9bG%}uuD_G35i&takqa{8SQQ##ghYsP8Q;;u~#bKgpcih3T>*Hl8yBr9Uv zLPmHcCHcwo{KuhvIo%}+fZd&);?<^EE%iY)H9^mLGf?+vY>(!XExZ<>*Q}22wYv^; z^(>y$-Ep{Rp2Aw!zdErq`h4}Z1RQ4_t6x1Ge9X>UA4G&PgD~HEL7H@Yq ztbKyn_7#O?!Hu1oTx6IuKtn#G3aM3{fC`3kf~&z9*m0=Yr-6QNHkB!p_p#w@3`AsM z+Wp$oxS#mU`?47V=h2Ju8R+2ayhizq3MTlp7!Ok?V4xR~0ALi{6F;(qWfTrzn*8V8 z4tRhfJgV>n@0k`&2i)$62`fy62ZJ3I(vE*|rs)z6MTzo`2rbCY3A97%hd1yR2&^0LQ%SMEvYPi{Me(Wr(j5fbacsxyivJq>Z@#vaEk) zs+nCjOqw_Q+5Ad#q1WALR7#sjbZ)J{qS>$tRRQKT9S#rgCMgD`cvz4w?N#|xYChLtNU$d|BCbg0rAqiMKt>z+XYs|6n z1QXCyXUl~jgoiJwA@$gcV`zOu&&PzcqD7k3*yb)mzqtq_OTv(n;6K7X;k zWyj_?uvdrlnU3-*!GPY)3w*28{6Ga}pjVZW2RlES>{aAlBfvh=e+553g0eON^`4tJ zEdHKg3(?n7zTI5#8cAl0Sp^B?jY&Fi3-`HI-{drtjxJ4(oYRwk0Alpid-z6wiLPB4H8CsIVVX|d& z)NxXF;tqnxlThKVGS7x;rzkBST={Ap-G$U~J(Y)Y?hx=jO%$Z@yja@h=!MAze4g8k zdN9d6Cki=&2Z6Y085LD8SS`=f3 zsUlMpmjhbGuN+d!iINSmYO>98)T>q_1d6g)HcmxR&wVoAjlZHR!4m9PUfa-fIT1-~ z&Vj=NLgSkKV$CLJob6pCpRZod+rdhlBhKG(${!7ITT`6%7i2n8TXDLzr;>U^Gu*+J zu!$rl&n89%BVgGUf}cbl&3Ags8mt7F7QdCEgKOR1%)=*zI^v_u)&=V$`4wv&HnsD-HfHgP9dkU&=hax;Aty zfcXK|Inm@oXkWaE1@JBP$%AGWUcVeo$=gPz6mAL)0eq+rz=ys7_)y>fTZ8pa>E1sA<+1V- zj#0A~5b&JKgI$jQOC9}h$Zh@qr;flEf&qa*)GUy@J8AdRNyLozX9hqXIsQ!^3Hl4* zOscRxU1y#ifyX~#Ny~nlyo|S=BBLIzaSWFS#rrpxA5F5i(;eA3X7y;~w=g~koM5?19DT!J zD&=tJ)P6FFS1;4T81hZ~v!O@+YO6PRt*BY@XvWr!!rh4f;|6RcugEFD0_#T2voy%? z{`Y&IJcw=mzSaz~wHEv=;{pj(#W+V5J)Mi$&|`yTxNTUy>4K!P5lFkXzHt&bp&!RP zGQ8iyZPfCR!8YJUXcaMRs*X&&aA^4_?*(jD8G148P9|PJL7PWwAdNtUX?cDUkLSxt zM!hG}A#MX|3oCXAg8t!BP8JHpemr2|rd25kC8zsAmTMyH90R#pl6g6KR_Bl33QG6z}V$XT_t=EU~Z8yfTIoG|@jSxlbD6Zg!$Ieu@yU-k8 zdC#?hHoxs%x0^P|j#`HG^-44eL3*E6r$u+tT!HuCa@=;1NZEUVn?cV+&x>+z=D3gc zR`VwxaZbS(2C}!qw8Z1>z@qKgIsVz1kMBz2!Ur2HIw>3dVIq7|UMlOe&%OA{al!MAQJK?LPDl}GMx{?x#M5A+n zN)UPfdyNV&S|SWf^qe2hcn*Gkxn^4{~)3)9^SiT^){GMerZarUcgFzj8$&T5c5?|T?$?gLHfCYG`Fp7r~v`GfO-cTuEf0ziCEgO5q`--dz~9d23z&7(Z!RsZ2qD9vwQ+zo-Ar zSN=56XU)4?=gM{Y$HFY*HPD-H2anRWLqFcE!QdwGjd}Q% zssytE4bkT%ZW%Or3e?YuI!JVe*HJy=^9n@s_C>3z4j*{LOJQl zbE+&FVJ~S`fmsbNR#b?Fny%tfPO=1%nhVk-j7o_w#1Bb`g;|WkHYBCcP&>cJR}#DH z16b!u`pOiU6|k7(pR*DsbA9tAA5}yv6ENB(mtb}=VS>RP35erEL`?}w9*%H2_oZ%j zLk`+|DUSV=+DRc+ETV5-#09L%#SOgL9CLw5f|A{w>9YT8d)Lzj7?8xQfC zK}Vj!5?HQqV{HunlI|o^S=ywc)O-ei(DMOnHzTl@R$BsKnBhJ%Z>2P5)419My%z4a+tqo&hqm=Nqst_uQ0jqYSURSe&YK1aS< zjL=^^t=%KWs5Hzt3Q1X-PhT9Em|jg+we2h?cIXvs2gRPWv3%w*0vH4zY*koiAC39Rhr?c{^A(N;LuhPik~5C0eKTc z!-MOA{S&{zCA+@r5JApKym-mbc8lg?dHL6wk*hB4db5zew1B+nuV3cdVoj`K+gD+~ zwMHA6rc){*q=?Vn##FzR3ld+gB43Qa90jW4T*WtLH>WXdBDhY3CHPhYO1b;M$dvL~ zQrWLy&`GV31hw)|MxP=h`B>swP@7N&FBXZWfH`lh4K1B1L5uzCW#9Jqi(jj&OL11Q zj7iV37II4NH3DWvY&xLe0+ZW9XcE1eCp!WAtn`~NM(jZd5HNf(M%|5R*ErHT*ggO} z{u1~U!9=C~asV_Og`M$uw=ZEOOE3Hp;U4Tm*CaMEy|5Uy{Ft^$|3UufTw&!hf~7%oZZleQ;-N~osPm6COTRVcWsc>cgL}%= zAdFYf#mc@E=`5G(6lPDE+UD`Q1=mnLeC(v?tirDEALBm$_i7=&dnEshP_BLe1sj;42goDb2Dc9u86P_neh-P%;Pe&D5AbUE6Jur?TtS#e7 zsRwZO9cx4ZBJKXZ8kII%Ypq|4WQris<7bZe_A!$>irkc4Sp9$8I1{A#~0 zZVobhbF|l*`+9URZ!4#~jdCx`Uy``k;mCeMN9^4Y_moV&tFrT^2(fot1qSXj_(B{0fFM;ukvs`0|s`jd^ekq*`aQ^L$= zznqeg$x*N+0(Cr0UI_qdis<#|0XE$d zP!R)v%5`$!g)iSr+vg(T$&WK{*wK#>{V$eRRFeBu-V-N&;v=!b%mwPdk~`3_N6}mg zcD1;vF%if9FszrQRuguVRCX2j$no`yHX=I0^~2r$$t^SJ5dGHsHPrIsy{ii!R}mGNGt-Ef9(6fEs))%JrO3tnB9#XX)5VQuPyTN%7Hk;RxxBX&NW$9duj1r0xRtn>oI_=xnA z2Xs*}$)K14SO@!(0pV?7z{^^E4;m@mwwlEGh`wNKTgbu_!^wPy3DD6|$AAZaE7pvl z5an(lq5tn!0+=w&L(RlIR*I$fhbqM^E)Vup06aV>z1xzNl|nOFSL^eJw1|dMh#%Wq z7o?IUD`X*Oqo_|gPKq=x0OB`R_x>KAXSqKAIHkhti!i^Wx36ki_v0&6-&;*t2;Fp? zki6zi(i2pv?8e}K>a|7>W_QeV5rod!QY%D#vv09@6C*C+dEsdMSgRVb)XCcM{k%xPr|Fr=LxC!h2l|$J!jI zF<*vNrUZ@hP+dGry^-0W>Y?TmJpxa;{}fdd*%@gosRa(ew<(`u6F$t>*1qWp=V_R# ztw*6CnvP#Fn0x6CK4smYFA29ir~6*#kizX`oiW$R2;CS|W;75t?X8QU7<6q7X(y}y zs0VGeTNBjj(=I6~g5FqEb521&rB9I#MZ<^tV>3@SFn@S@iI6tCUq0!lCE>Gl#_stw zV^R_GxgSX>lUdgyX~w?xgt|#VYzYkV@SJ3~Phmrul`8VoHQB^t{;2Fg7Z z?RNJ}h9!_eaO@bOTN z5<_ryFDTRrJsM0>icT-zq+vFPK%d44IEh^Axzdc{mDkx@tWQ4krry_#37DES6n;k5 zZd6F?n-h6K{;Z!@!N!&^8w#hA`EE#NOa?e^Zk|#iGjZ65zqEYzCHMY{c~}M5 zYXo+{IvGf3Lr)ywx%)^)g7u_GRsjb9AV5K2cZQ&(kC7W{E+L&iNH#QINs*AD;&nxi z+2vp2uK!*A|L*L8uV>fvHXzkzCiv@ukInCYIgNrD=deaI#N1uo2yo>-GM5n6rh_e! zKNt7A;;;JN@UuwGTcIxSZfIV`rEu8;@pJt%XOEN0tX*bv{TG43p#Jfzh^UPCi!vn+VnyD^^ZzEY=X&{cN44_5e_W`? z>EFcrbq_N0=kYuKOXdgYDCZ7W+r>Rf1qV*zoOqp(yKc|&7TKho7~-O{4nUX>v0dOu;Q!Uih&?ZauG+d^*X8cO zM+|7jN3ekVi|Fq}PM$x2#}KHP_x%89*{>^03=`G;>lJ_x%U{+fQDCaGEIfZ4RSb-H z0QJ{$!y3|G(x#?_F1qj24pWC5gr~La8WmV+1(`#*?c3 zB$c7L*xEytkZLbloKfDRaFv*lCsw&gXmeb8atsvn#FV=RNQfsyY!j+Z{wyxQy!bsoD=vK6OLgxB@!-{Y&?DilI^9;Bn#B03?v?FYI~6TcEf?ZShH3h6gCi zrxy<>mU50Yvvwceo$~B_IaxbzUGhX$bCOn6x8`aa*Me{iAfOx|QiWP({hNct`0rP2t2+&`DkPW zvZ!tMG}z$+@s_$qzh-|Y*kr!sGhhf_Ak3&MwZ*W+D;s()DFC&JX~FjBJz7%ApWbcv zA0K!^%S!L9$3bxnO*|n9YJa-r z-K(I9>n|ZO*)5v8uok=KiB|@mTNuW`;BN$(O0$Drd3<)#=G2fp5F&+QVU{tKX~2?;*su7A~>g z(BGkq*lwB`^!MLROL04Ak=T08TfT3z5gA`KB97iu2KnNa6J8o%#?4}Fl>;iTaWC~P zf0_K)!rs^SMYbql6!?7+O<}?ESa2irtaf^fcB$?9{F}}i@8Zwx9nYO5&B3-R__~VC zQ67Zu074C>ZF-w+HYm&~d8VvR3wxt&8gu?jqt{tPbc<2aHv|RUVdIA83yw9KyW8JH zuU$|R6t@0I-LgUEYI@dVA z2gvb^a7Pzqfm*))T2?O{O+QL5<++bz?TJa=g@R)FMW&9$;b#@nO)K(JEy@2uqchU* zvJJ04d5y{uPrl>gzW=S)*1dy9^C3FecT-(%vGzwCTrBn+pbTIIA0u>8bk)^4 zcUSQX9m^b6PQoxHWWXdDU}5+Ndry*64P*w*NsFEWbY2sV%X=1jbV)lRh#agBOHv7` zK%#(ZM~rMxPTiUUx~GU|&KK%|td|vk>7FG2^?~TdT|z3 z?znY7glAz3Ol|ZVvJt3bbP>pr%F$N+kfD%@NC4H{H&8h`z9n!()rZl6W{vG~esN2a z0)>ht5JR;kRF<#2o4G5r^c|=pY3S*UO-@Z{PO7RaO}FRj zuW?&)xrR!6W8h6Yw^4*Y<&ffGeKEy>+{v|N0+<_*ZNSLTb zNI6=}qsG#=6PTH82m=EhX99BPg%%sITFip;iF+H3q#7~t;NwD~E7u{A{6(L-Fh5&D z;(iMvZIw*^2b8dm1FEs@`y2p&8wA^T(s4XW>W2P9B4x%b0j!zcwXx zM}ra89txE4frYJuw()LeE#q(x`ek2dB^$S1&@|bU^dr|u`l=89fmN<%W<%p+^Fkx* zz4Id-Warl_`vwod6-^6#3Hi~|=ncwT4n3y4x z=%ZTdNqhj3h~7Rojoi6#hF3vPR(5uL5YusbDT0oR+EjM*yrGE)T|Ll?v1do_#1;jQ z`z;|{q9UEcia%4|6qIHq*6=w9hhI#&a}FVIujT%!;wFFK+F&3ki5Q}+wSat-B z;(9%Pc3V~hTNBC!r@GgGy-*%E_1d48}r)dPCVa`FcaPwC^JF-=0Ka+Y5>Ben?ws%R{WPjJe&fU7Z@b3bRe zcHObB9(I|ZKXc;pzA$smri#e3LFyTNCPToq>?|FkN?~~4jTRL)5@-1 zQ0U#ad3>Agl9_HLBlJ}|KlX-y8aY!h|Dme0_6XCNBRKg)K)4m#GI8N(b|kd3X|9!8 zT~};OS6x0E{)OfUS__gfFj);{rR&|XmbEDu^KtJllO7MLfx!e}f{6GR5g$Pwh zaFa^=b|C7LH)Q1(_4AD{R^~oa_bR`afWyp-MK~}G0r4>arveFc3@ZkDh*zwf1SFvy zAwXZT$5j zHHj6Gkq;ahQUJ&c0O$lDMP^lsWyw%6*CZAw4Z2EpRB;Gu2zYh_l*q4YH%oMbVdk$I z`=P@5LM_H6&Tbh{_1%$_d;e+PYHwfXTgDPbbX_z%vidgY%q1~3QptZR_k9bF+{Lg! zJ6z7LZkGnEEiS1g-p@14j4rC8ytC@Km}Nx!v-d4T7Nk!@MDQv;Z6B5pWa^1ZlXr`5{&_+3bmw!nFi7 zC@);f&sye2DOG+A>}8%GNv@RF7{=lTr+a$_(*) z!?!fID5d?v9l9vZG#2vXZE)*_Y(gU6L$~Dp{@&G<>6Zt_35HxrE)c|#AlLZi?hm^i zww-5U)me2Ucm$6r=)kyU>2M6=2eIG4CT&dv+hVEO+DigUX;q`z%Ib<%Id0tc?}@o& z6WbN77AHM2#?~!#YcK0ds%()5qPo^~ru$PheY(t81J(ONHa!`$`akkx_dRI7JMR-Y zOPevD&qEElgyw}g^>BWcMy zFn7DmL-~GAlffQa9=zqn*o|+xa7nZkE9tfb@eDRPnyEaPouBJlpvsmXe;RYJ+%e-o-D4GKQSjC zsPkpItJv;co3`fUfU2_HXg!(skf`O6le{aYbM33?5aY{w)f_ZJk^V#BJr!YUVFPJo zEjBwKRF`*6*|ibiX~1QqI*8HEK!^{;8=o+m)UVVk8!OKwYP*EmS|d$cl6^A$!DTRE zrRKv(s*IQ;DXS^-WDJx^YL*eZX?^O-oOI2+ z3Xhy`inM!0j(Q(>W~;K4)Y}+E*G_+`h#Iylhtz8G*7DEX=Svh>&rnB^H42q|3Bnj^ zX{R!vyUNz2Rei=RoWX8l5v4EkbYr&t>tem1!-Kx&K?8kFEB>UVv}JVuuSMZ zuRa)Sc!j!`MRbabXhNvGRLxlkw}4JS_<2&-Ku=AROtVeuf{}C0_@ZD~b$RZIc_MVy zC%;l?o2@uEVe=D=tAr- zMD+I#8sLR1T6Xphb^%MW4ww6|*_!d^&@=FB=Te3oqoTyr_UGsEfI{b*#d)GkwJ^%y zRxJ|V$LN9~b9u}=UH7iKenC{CXoBok-KY7BI_Ev1>2IuMfaf_}xSE%#N|~v8{~?HS zMkEO20Mue%_%bG!;f^i0*C!Q4A=x>jkS;n^?9#d;VM@7xz*@gu2MK*}rxd$a`Zx2f z1_;6E*nwl+1#p}_L|MHASaV$!Z=h@an>hzy7`~Fk^asyAva?&G?($mYi~;)zXMiq6 zH$eaL5#4pWK-bC^UjpQ`TA^#k=Ko!!!J--xwxEFZodBK`#N^Xl5wR4`%&_4sB{h~Grh z#}PXAge!zW#3DD%2G%T(MuG!A;H$VpI-YH2nJJcygH36+-uUTUu}e#+-O~^*lO1v+ z{FabUnj~GPv{Kda(^R*v6pDkSMi^qCUEVsF5hHef|3O;}SRM;VZWHO#ol%B*B2yiQ zHBVA%Uv)FRp>fjB%P&=eU`c`jE3x0Bz0xOrSyHt-SEx2n!guj)BrtHC^t&eM>t6Sd$}(Y0dvaD4?PeY1Tlk5X6qJI*VD&Qc8|ecUPYlG| zo@|V_Try1;v*p@&`Wdgpee<{@1Y(>Gqk9(mx_MK8WV{Wkjv?Mm6oX&8Qz8F_KTUq$ z2gUZUs)wpMFYs(=Yman7a+;%rk3=B2?rwELJ1Wd!-%`;CzrBtEo9t#h{emSD(7%LE z^?a#AIoW?3?)BlUwDO|rQMAZp-H+MXVF`9x@o3*^i$Qo9)p}D`ElY!9OXRFL%*Zpw zT(X+K+YdKetcHMpd;j>Tt|O`l`!p0gT#q+d?Z@{w1HPdyWbYThyUvaA4u~9u>`$}n z^<%kx+ni0J*|#jAY+Sp_OMSTg&NZfp@&iF`R;eo;0i6I|9Jij~oUh#j+g>1Da;SZT zS?X{veJ|OY&s-mL=5S;bkbN(>0>Vul1L;^P{idF+UYC zf(ZYh6?k2=v3zRqkZ7-%6FBMJ^p&ZfQ#L5shn{sE zjonW19#el&6f_s!dNlj&h|%dl1h=FDwX-2=mArm^7EnY8{1gYVE(s@dg{~C!ukdH3 z?!9=vpfs3^m7MHggKcyF58Cy6;E0)Ag3q|=^L^iv=y2}uB&WOXx#Fs0j4sGAmtf>} zKKAVR4cqAze#1}b0Zlm|&)l@$_=C1)E>A$RVq|4x8Ghhyjr-oyC7+PJay18pcu@HI zN?oqmAg-S*a^Z<%)n~>Ud0hXhIn#i=!|&(kjfX=$9Kl)Z)U%pdsPXPKM)(LJ)@SNv z^FxjliRUIUIx^|VE{KCUM@WgzIyR29?rYE^J)BPDy|NA2f^Hb#`0r-uMBpHS&>jTn zZzzaV4#@nm52M$81u*+Sg9%_oK$vkzCj!vMkpV((mk7=~HyrvM{fDFj&acoWKnU;$ z?cQH^{*t}k3+c~e*U$$#;&MT*)zFO!ohAQ-GVkYCcj9b@wvH*$o4kLBvrn-8qd1#P zSF*VrDdoaCUp2YaR*JpO&B&fdO4id@_ZufrF}gPEOU1GFPZg5_JFS%pxynPXz>tsQ zZx2`?;2Vjr6dY=Df4oF$~|Mc2@bwSryvetjl((m4uG#~oP%FU&+>R`c8{=w^zhe)f< zoS3!+XR+3z&fLbo-sqMxP%-X*uOH&CU*})HAmb^LI+6n{A#0)-hY=q zE6VvGq8f-WzEsyP+WPW$5lq0{Jo>MD@mN4bv=RkG`;W|B3V?Y=O;@_xiW8_;5AHrG zFYB2A^K}$1AQ#ao160%SJI|0<1BbQCLs?m}-8*a160(RH69LezmUQ*n>~~&(0hPas z9ZT6=O*{o2m69`tQLsMyJFfiB8xWiS1ZAadEA4R(N>?rDgJFI@kshq|W5?}WZEWh~ z%gdrzAaZpG!;`C2cAi+PS+Y)4?-g7}(xi+Ga z%4pz`5Us9#`HW22aIxsmWRDVT5fAAPc}ZRE#m$wqD=$r8I-FE|;jMFgO_O{cASq9r zEzx7~gocAF4n16o%ef0R(?;lo}Er|y*`E%moB>fgh42Q17;Mn#eFLZ+xO@Sxdc}Z@L{RC89QgSPM zV*V-&o}T_6UtatqE{U-nGRo!>*V^{jjOWSvf#I_i!X0Nuf|*o(EL@KARA{*>uf2NY zYdajsDphyNlNm6>T0Z>!0X|iA6^9}fc7QA3Qv7uA@^hK9WA99uancilSv~CT#$bwF zEwv}YdP1YSD&=&ZY^X%hP*`-ZF*-^)`H5l6Fn*)s0Kp$L=1LZq8Pf+sCsV)-n(*qk zeW38b`MQ}LT+odv`>dq1#_+-F;;pjLD`k$ZUMeWPgHYyVpwBO#bgP)J3WQs8l;j&! zdE6^tz|jiK}%daq;APp(&u{9{k)vGq6?19A_jPNGb)&hh=jmQ^%ZXlVG*~kak5E7TO&bnUxeO(_2@xXC|gu z!-=*9u3m70)-}(i7P*MFgH$kPxPWy(`mfaS@rf8QFBC)h)`iE+&dJVs5uwNPjXG52 zoHss&6k6V%Rv+0b&=RB1sobxR3@>>gF{CV=8t}%%9LubpOQsFu1Y$M|j{>kC3vRo1 zFGGQ)OsL_#U9x7+A@}!U!uHtr6tQue;rC&yyET!;A4a#2)0zr9&?G;5>46e>fAue~ z7=Igf4lA&uML@|N-&ntXi2;LE7yk%$JousuxmSvVu*m%U^kgzLneCJv%Q+HEz>Y!! z08CE^D>jZ-PJDrm<6k8U8Lw$;u7k{3hyXSo7$cUVmH(22=W^z=hlYuwaIJmfbxA@( zw(s&EfYasvIe-`gzHOySfFfb^0X7>Tq|G&T*iaAU06RB~OT;Cn7^L~;^a^PoiW2-= z!}eLP-ly<+va;DO#zB);Mz3+R0^Z=ii0%9TS{Oeq@tAv1e~j9#vcZ)B5}VhF-f3d% zVfP2kAKC8x2hG6f%ZQK|_l{GgZS=dKhTW{!^L5s4yIY0%x%KMQqTn}=4*IWY`cC+Q zD5-8H68XqV8mC(-SSP2c`OPFI1*e=R#wTCPQZRaVkA0{GSrvSKEDW-=;84+i5j|tu zBsBiSV`gS<@0o^CXn=uOXj^+6lFcKrxfRVr;PUfQNr zh+0lt(L0B4)Q~PkSXT;B#~pk^@m{V)@R-v@LCSJb-52-l8AH3B zoXvjU?3rd^F`=dt(V-*dJl8A=MhK?_S@7Q>>3=z`EEY5H@tOMOQx$3af&}7f^_bf} zrM$R2bW3U~mm-?3jjPq=Za*LQJMYi|Cw^FZ(4n8S-&@qy@uNJtdV5Gzu9)M{)r7sM zsKK!8bO9MFE}bIJJ7jLb-}ppI9xto&u`?vJCxDVq*@5eI+Tj;2>4g2_Pff1|E)6l1 zEiFqe&b+9ip0xXR9uU&%= zvT~Ir^*w$&lqIyw)KA~4amY5D`i_~Mas5FfjeY^BxIzC}#Z8Nt@n~oX$OER+vAxYd zXxbfHb$=ITD6Wb+2b5hG9hK1Z$PdsP6#=ORE@^iR2?41~J}9Sh383jw(%r=(TEaQN z0J;=PZ)3)O*BSx6;CY00>^JR@G->k1Cf-=oH`E&}o_s8Or|(4%*sAjd_3?MVNo$a-^_Sk? z5Rq2#CZ>_=r!2C{i+&QO9?g9^1hZH7lWGju;) zuf@XgPqI6JW%n_-dC{Ks15Gx?3Zklb$Nk%zHiMR+K)VG#Me9IOp%Kx9#3if%bxw~B zUc!T)l$qyM>6>q<$38r25Fh4yjX(M>O}z8vkVOa6^3A8W#soI%zs+m7E2sPTKhWT2 zW?_@-ue4MmT>#r=s=P+JzG8M=#aw_VX9WD{UMLR;VeG)(&vZnUf;E*W^**BamFPlE zDky!a)FadTXW4_9@j)f)RKo&q(wOBI4*M6YRp6aj(8*-4knb^QtY^c3+4p4FwRhzQ zms*OCeG&dEL|AhwaaJqLp%i~Fc-=bc+-9wQ6OfQ=J{YJy zVvn5`GfAO(`Z2*;)*%0+8o#~mjvZLVqUe3Ipg&?YSw}||M3}Gba_rn>s)Lpw_+f?UZc^!@DMgkEiu~Tw{dQLC{I)3gYl$7VQt(Caud^ zZ@XcV=+}{Fp82)aJ7;|l8xK~H#pQK^L8XuPhTIh%6v?4#b{ zMGKG#{S`Iw#TqT!=dH8^)wI;b!Ue92gTP~KIc?<^-|XmN1<=Twb!boUlCWseWqAp3 zT^4#rJv}?cXpOUbVj|&oe$sk-Na0Q$sF%G+KL6;*mSa_D@4Y}Rpy}&@)8C$4_Hi^C z+FFOq4=W8j*{?f5dPTU?P279IkFp!5KwWR zm3ib&O)Lm9c_ekYodmBMk|H&Qtn^_z8Be}02{X!nq}_7rKo~H65bs5M_`Jzx*{{HH zG&U}wbIrN$(Da#E*+)VGYBJM(=0&$yJYn40n3Cvh^LL{Ji(%UWmnia}&Fvgp>Nla! z+uUf>z=g<^dQF-^s_IdnnLK$#3>Ke8+pXtA&k&zRRTP%OmCfTa@xQ&3AU8zKYtFhN z!q0Ao3+iJI(OoPtvN=j^XP%i#K7BNp*DS0+AA3OG6QLQ$esED6KdJDc(!pH>Vu({> zd44e8JO4ai3~*O@z-=o;RI^Z@oxa0;QgStWjj}#F8mmQ@25i8pfi1I*pSwUW;XlZv zV`%6hVviT%ky?PRPTNZhhh$wl3l#*Im`R#hAI66P9v5A@PaJ?)u9z>PIvz-YDq%wb z2PA<;{>CdNb_5oVJ_rH0kcrZa*nwb}3kJ@prq>`MedoKQQhXFd_Z^^>k${Rqt0ehv zHd+M9hV4U`+NO<}t;rQw4CLFcg6Ac*05chN#RWQ`f>-^I;)r(@S92v>A1`3jdjGoF zYJBEY>N5;hjcc5`q>}u(G%%z?G9#}fCs2-0;ESilyLfDYZp&O`Y3XQOCs6>7EI}3( zPP$KTvs*!}M~ybz1)o}gsc6^9Wq79h$SJU09qOHLxqg>h5RIs z89ntG5so{xx^wSdyH*rLj%wqiEswu(7smQ^bwb{IUQnOCXQb-fJgBE= zlUMih#(r$9Sx=4z4g0=c+pqqCLFg$YIH+>^w<^8&yB>Uw++^(ZW}O6SkX1GLN&VKE zH~DgiI$rFqO|8{sd3$!oD~1AoH97|GJd4?DQ=7(Kle%i!l%yETM_<^e{mBd(bTU_J zKT~i?f6S}pJ>c@Kua^fA@Ti+Q*JCJ}#e}s{qV?7dyY-eoA{H{Hl*ym}W{WjM&P4OW zaf!(Gk)zdk!!{eOrXaS^^sDWr22>X#eCB?m5T8d@$cuhVPHQ21qbKPt1I5 zrF_hgf&(%~m}aGlmlnpJ|Mrmf(#(xfmUuC^cIx}gn1VXLW#st<$rR^&crHtfm~btT zvU+^T15Bb99G==J)!!mJ^b?P?Z6DauTr)a;belYS<||{orLsfKQH@6aj1hGIwAKSx z=9!-GxKzRD{^uQxx8{ikull^Ha5HPy;A@P|5?)-9mg!tn4=6KR`8hvPHncq%a{YAZ%9{eDKGcc?nZPE})is#~ zV2`>OKScyH0fx+XUX~Zu*to9J`G*%-IC|aRY>}1`uJAR`k8jr)nBiPym0#mABG3}= zd%n+Im^rY}^{wf%4W9tlYTy)2w`VL2P|jLA-> zT-RbPddf^T&M;?culxE{G4<;o(Isrx$Gwu}ZvMYAtG_?&I`X;6i(o&o&0LhjBz4w| zG!Vy3;1ku~p_yP205KBG_kNol7Ri}pSo%5AasEM;4bgA!2%Es^_b#j}2b-h|U7{2C zN@K1&;LlHspKol6`_)zC+eFcAiMW29p9K$sj=vs|Vc)|I;_4T_V#e3vR+t!}7H}sF zk?&z+5Cx4>p7O$Juqi06^(X<)L%QU4#Wm1hMSaOJy8f@*1_P}k|DBq(X?^D&17~qW zgk<#O(e;7*tpXtT$$NP{IC;`yWD*Fh6xA%*{#phY6@vAE^if$ODJ=GnbpYWGmoBP~R2P)) zVI2we!QJZ5vxQIqkc5Jmho*N(|4mxu!Hv$DnR>Q(~1?Q~fj1Dp-R=RtS8aLF6Bb)x$hB3h)4 zIiGOV-I~w!(&)h|S&onevMZ|A=-l0R&EhT5o|Yf*ym(r+Er?T>qWzYYz*~8FUap)t z4eGjDmdK>`m6Qw4Z}izu54!Z%dNA)fKQ~`$G^Ap}Px`64L>Ok0nG1G}zb{2O3sHX+6e92Vbp$!SvZuMewzw@Y-exJH8Lzm6GEIpIE|g;v2@$tI_(qOvNG7dePJ>Iznf} z`lGWCU0u|CQVVR2ChD+K#IEEST%n+@9(unv{nCP4>|E42&rNpx*!BIJ=*JEIqRZ1Y zlnQdTiw7^K7oR@Tbja$V<9>YELk`g}B-KCO#7Ou>dfM1b$HV*Nm!Js^dcNpWP}G=v zV0^ZSK1;9Cj+W%a?I<8mPPNV>2<)n_D!(iLY8v&Rr7)E|F^r&k<5k z`LV_Y^2pes>0ds@-m1VY_&JwbWPvC2ld`GnXvnl6Z_^Tpu-KHpY$^)A+zJ_qDB_V-cj4!rhcy7wKob;IvV4;o)>+rlr-O*`VQ z`;SppP#+QcilU&#ef-Gagn}V15%7XqfN^=1ONU*v{>L|E9lEN(vYoP681tBD&b{ts zTu8OTzF`a3Q$?)X#+7ECMU*lkW{G9L1qVXJ+3HIp%X+5SgGlXkY}BE7A07LtX}X45&mG?d5z0PfnL{;7igA{W7rIGnalO_)P=UnTC1=KZu|nc8G}{M zN;==VHh8@0t5g5Og?5E}AMPSUx8H+^dIl%fa?@La67?hhJn9Kv%^!L;9_{LkQ6E%v z)L(DDpyoC-ebL{&Fb(!qr5dE?Mmp2}7YGwxc=}E%==YJzz=MCmTBa*gMRN$M zontD&T#t0_{nTQN_nenh`;`)+pC4iYs!EY?C;dk2UoXQNd6AGx9D~0nW%H)w!&|S< zv5a)LgODWR=)zDKbBUFKZ3;ZKC!OJ#dY#MTHkY@{$-PD=7G`YaLdZ^3${2hS(rCQk z&RIy0OUa;*Lx1YeE=Pg0T5YqA{ruW()Js|$Pz2GzcisL$fM&s z!`rewvQ!w9+XK*bI(?^+;N_23e>Lj9W=Q?5Wbwa|zuf||lcpbjB4MZu zE!beNwKWJ5sR3H9JjM7d(A6dn6MudF(%q zBs6kE!SH@Yq`tXSE zw8G{@)YkWfq)N_L2bV~=5_!J80Tek~T1_xLR8!OVz!;X7TrF>4!}t}+pO6VD z+GpWa4j7lwgTBnO*3$ST3BiOut9K;rj*0@s3xOT+BdGTx(>$)&0{RY8$SN*Jh3IcU z_D*A)ZKt&6>7bAjW8p{hL?NxpczGgaZcdQdLPtz7F1bN*!gl||6Aj1A^bmed7jseT zLTna1FfVVsia%Y_RyViXI&XC+I$ago=__3-8b+qV&)+TVOi&^7sP@%%U`7jo(fBI* zdTsrZqOl*ZOC4{ZaGMnQ4K;Q~RQ5{i>{T|j?Bls=2&wlf|kLl!w zM;K~kYY-Ne`Ro}kc6qBnhWLvq%FVCWfiI?+?s&^U|MI886T3&Q+{7Yl?&p|XP@^U7 z<(RSOQKLK9a7>(8hRy}4w>2N8I%1vnYe~AB^9mF+|4k8&gU40Z+|&#gfgA&0f29xSD$h69lK_tpB{2s>Nd zaoskG;yqio$Z=5VnW?K*F~kooS|mlcwL^elnHgGpjI9u{GFQDFLYQu zps#l6ory~-gfkGxN~K2g#GXhrs=+}zm3f@(CBiRm02$q2^$AtLNdUP(%DV0A*ZC7# z-(G3d&Dk*IMt(_VOJ~bq{J6Z4(J!}@wn6*Uu_xor%oOhr9Su!2g>CevL>m_GC%E&t z^De=wI~|8_PYpefQ(kQ?_6XpQou5hMrDl;0A@1IDKKl<;?gUYJV9z-*GG@yI6=d}&P^6a5xZnm=2G&OclmC)YslPsC3b%k3sbU&pAA>&o1z zFs_y4rxdx5iE0Qq&|LF}$qTK@sZxH2gF`S~y?pK7yu5|U+Gpm3ATihr9H;ZvGMIT^ z^`x5h$aOY$yaiJYmcFZR(KF1?PK!k!8WAA>xIs{*NW=JLTCnrWymv!QEG~ZoxV%nI zC{ZCw4B`zRXJ%edMiD{5AQz$NXMy$#??fqS5D=rjl;-<)()>RY=>J`l^!Pt)P%sJ+ zZ{NXf(ruLKtH3swOYui9V?P8vgIIdR>V8Sr`{P7M#QJgT^`GXLf%t4@1TU_MRYc#W zg^)%F#hNnkkc$u4#goS^bWIO#F*M-PHw}pEuU;Lun2QKARb+Ih32s}>=f6juo?)^3Vut3Nssn62Ms8#(W*)uwGRuzFZGY;pf5v6OR&`S$dx(R zkPxd7UBoJ+D3-4TIaW9`@;OO`7ACtp9zdT&&)b!V`Zi^k(ayKhxp!;E^L0T{{urT> zBIE4U;9_IYhu}3nZ6z&UpK|YT&``8feF!N2UHYZrpj>J;p1mt~p|jUli1b78EAGtv zNvG6c0Zm!*9&bL_Qp@R$-e=)fiuLC7g!fbNx|TTz03WtA-6}37Cz|-{G5KUdZ3lM_ z#XkoH)n65B)9i$=a_@X`ZDz$UzHST!P+pr~sNuZ!tFddNiX&!oU6Q?%*{T2R)-8z| z{&4Vt+2^=ed_MJlVkVagI=?TPZk+b|hjX+|`*y2vd`el|+jJT@re&|%XG<3q4RCr< zI;fQqd$Bk1b!Q(+!0ildGkkTvmug-U%yr0p7WB=l!!3@{I++AyaQ;)@}5By1)9_*OFJ zmCkc_2*}9L@o|xH9S+M^ZIJ?vDj?5={%YCGxAzqbR<65>5 zzH*v>dV`l>4ukO3T^7f3qc?}@pCT+7L*SXk+&tPlPS`~m3B4;FxY3Df zH;t~PZ;;aK5q*oqu+aox?j-U{trwks#HRDmn9jHEv6aOcl}IN^JZo$EdelOnAtS27 zkqQ;_2Ix*I`$MX&i=W%V^Lk__K7A>akm2RsEeLn-D}T8u&~2#CV^LPHo>Oxr8BJ z;tsn)n2e{BU;5?=IP{PsM_NgPzZ)EULMzqWn-?~B!(B1I6QZA2A25e@(p|rwcN44 zPR%X{Eo#Jwr^#@Nz&K^j6%E^hr<>Ksf3=1ytxQ9Q)m4i5gQxXU_iw;>lk){vujn}k z2jg4ky1MkEjce{LdkeQayVZDE4UQB8(?~q@Es_-Bo{6boP4t0%O-up-TyhVazlYU$%&NMl0Ke!Ut z9k_nRJ;$V+C>~k^^dQYD8#hqebB|{Jm}9X6{AG)|TqLvUY&3(v9V?G7kEU8%km#Wv ztl8P=6gQoX6=@|9jiluPnl>4YWf$eyB)?hCrR@`bPa;(Lji@=6g#JW(^F$AbdV1K)X?iO{QA6r!O`ZmB~M);IK9um5z3 zu@m4U#J317+p)Ip>C?;`?uP(~+vm zQm=Q|o0Do;CGpR77R@rb1bzcfm7|8jPDTtSV)>-$Ej9vwywcG@6T3K_9H!Q)5we~= zqoPLzVj%S(Bdts$lybLs3hVoZQ(edgy+kBR3yBqGA7HCv4IUV1buB4>t&+jn zII&?>pdR4faZCf@C>^JuViIO=Se~x@`aQYBzY81Pxibe@jGSD3D4`c*cQiILB^0$| zGkKKIB~14O0`)*W1Yy_Ymc~u%G@To<+A!^&4J@7vQn+0~r_WQFTP==|g)JN@1~Ozc ze>CZr2{$q(B55%l1%86#Sn!GR87R#gt*sH-3IVe#KSHUz- zuj)lQ+?>$8lAgNTl?ZBRe{(8{wytYzH01w~T%+hVFe2yV94*2&>&}rFT%Q~?nIxwv z%c;SaTov+xGccMWeJ8Y^dN`YP@y9)(8~{c1U?jEf%|)*Bf)1BXZ%R{Qy51LM`xppC z`gX+;{;87T3O=59Gi>Fn@X#FpCy(;yU%yrpA?#BI{g+~C+S>q-m8nL}tRvUr%;<=s zoj2l~-XMG>et55aAXUhx0DlGAr=Jfa1zu{r{L}vU-*E4R5^n#XUi~ zoeN6phDoQiC(8vKaT(veGh1sI!Cf%e26!!!4wkDenEDE_+vEf`MMTSM$I&iWq_8rj zNXH-bh_w6wfN|zGV!gf-4XbF;s0fV93aH{mD=Zpp1E~Wsmodfd(h=A7iDy5z4oos_ z=PH>$#q&EseXMWYla)SC1IsxZftN(`a<-5&sr^RQui>S+3*AKq*TNzm-G-HYo+7Kc zDeND!!>!sxd1*KW1?gg=T2??&AvJBfp?)By#0?Y*7L+n2uND<`mXsr7rmu&e6>gS| zXultVMAjGKv?Xx%Zue%bsfZ%)Gz+b;9vNNb?FJqwM0!LRXJFP%O~3TGlq|8Go|EJ*IC1!|ko>KP<9q|zd{ygxK92Lj%Ty{`B7~VmV zkZ)(_531s6x^{)65nQy67jM%(x{f)I%sHQ@W$_0(x3f>_rM5c5_YX=P6n)IeDDs`J zzED$BI{6mRQ$za)-Dt*DFzj|o1b!GT@9o;zGL#f05|E-QLngp>Idjl?(8rIez%|&y zg-RYaTzsrav`q8^zfE=^P2NzY@<7#fo$6_{>j#_#3XJzWYFciY?czT~uA4umsr?3^ zrX+nLJ#=rrhAcG~%D$MHjob!Jb%tafDI0439D#$mS5_cPt=t6VFJJxTM+xo}Z5#+{PkaU%cy6p7x-YPx)v2&cRgH(k6Lp;4_*QC{~0Jo~((r&fTZ4 zvy&ove)de{EY)yYB%?!eKwk8G8sE~vOlTfmQGd=k)aNkM`joz(uexwfhu;IqNMEy{ z(K{xNPmQn$$VRR6)p0gIdJ9WRnjVnzv_KO`A1nNIIfrf8A4spVFN01Tq}z)xM}(w6 zp^L)Gj$DBS)$y0cl7X`UGSS$j7E6#ZQM}*~We!huDXn03d18FzSe{%}d>Qz25`P5j zW$miKB-cbI@^X}V1yrUtQ&pnO9g z`+n=9tT501R&|XkM4o2{yh&jSO#gMN`#dQLb?OX_DT1=8v z{}OtHvnbQa2|`5H*3LZLcbAPWOBY!K?)0>FEf}ge)w&eDkn*$)Qtw zw?+cq=GO-NDdg_I0Rmh?m3e{&lzVDXnYViNw6qtctqrx)voW~WrM7}C@7V$b+XpMzn@VNY*8Ip1sd2HYbwix@eW$lc+ zjv6kt3e;<+mlSQO z>0VGCWQukBo!1}eXNx=(Ki}W@UW2#yXRCb6R4@BC;M*VkjQIbwq8p$9iILKDu?%5T zj*q)lhf+h{^g)+a4TdJ2haG*ik8s~Vp*ThQ^w8;TyLWmknx+`~v{bCy@HZd`@7Tb0 zyDAz|eM(EgwEWlmcd4 zpv~WILgm2shcF#{Hf6NFu0{%k3OrYV?N*xh>)+-#&0Uh+h!fc$&iAMirA~o2V zc-4LX7*!?Y;0!h zbUGrDc%QoO@ZHw(%_2H=-e{<=Zucs5bc||t=f;?)3t0h?z&{p^Ar-^cg{^$MHwKh5 zvQ!_yE8W%`l8qK!$5dwpB`0&S!W@-0lrVt=Li-(5M`Ls2PsT}sQq<^M$!ODg@ffd^ z!pM(7EHOvYd%YXdkdKhOETOmFn(pNSO*$?|vU&zIHFI>!bSP4bl@|PyC>%jmhmlE+ zKnH53hfLrb>x~-Q< z65|e*Fb6y=OM;;U8rx4bG#zRkm6H&f$<>+!7rybR{HOJ|vW0G(MXjaYO2&bB z8itYa=FC&_38d3m6Y)C}AXLX$F-h}jkr?nt+VL4&E)G~i<9Ci$X(U4|-c}oGRqXIF z!9H<2`e3wNbgD1gX}`Ms-Al5>IKqF#Y=0&}Q&?;mnJ^9{`4Edx^zoJcY3C@i$l^@a zh);g0Px8mzO*sKjC{2&hvS4xkQ}mLnqpE?(Gm>#cfM-h`1W^9as-v*}5$}tyW~kU# zLrIOlK=Q=?XOS(enOpxmOOLAm6A8}Mq9yijoA+s3Z2 zHR)dT(Pz9uVcy_1uNI?$ob>z2xR7`rSUgk?+O)T~1)t_NNZtrCQL$33eV{(bF*X>alM6_e?u&4KBwd)szD^H;wCy3M|+dOhze?;0MmmA*fIx)Vqf zow~Ih&2)4SbuGS_%8*)~U%H(c^P?tA19aoA0~a}U`lY?ckKKBbedddXU;fu z_Xq!J)KDesah_ovZ`}PCRXtR93Pmh;5&!wU8p$`*x81b1b9?r-n+l%6CZSm_Yc%iH zL@~c3vr)VJ)8;g$(b?oMf%J9%M!fz$+qRX6nii=W^E+5v+G-#s{Rt|kttg8Q8L&m3 z$hW$G^bn<_T&!1rOKWJ1C|Z9JI(zXi?@LUhwj^G`h1r7YmioO!_E@Nc$>GDyzh1M3 zy9C+O+ZZ{TnqwWj?tO7`w~5AUqkp|AHvawTe;#;e$?0FO$G?sX%5WX{mkVAd@z2u& z{XM?#|LfC(>Mk-@do|zYzlYJ$=DSIB-n4i7<<89el&T(~z-ScN zNzWw4Xuq|TLed9>y`>dlm+C{KXOpH!1F9p}kp!^I1iuwy5ATX4Kroa%WysOB7HB}t zFh;Bnh%y@{fUPT*c$FRHQJ1-qIi>02=TtkHmke6&36hOI+B6 zE>@)NpO1uUra*Nc-se<>PN4842q0W2-Ksz?h2r&D6a4}}oE3`?(DD!S55q`MK%m1g z|C~s+E--6+B-=|?S*(L61vT0oz%~~C>)>;vpXaVGtS*dXZhgNm*dS(S*U+_Fc1h4; z)+LWDY0D|-RN-3kB>SYQuByhO zg&-Ca!p^XGKO2)`$fdY7J2F!tNkSP0h+i=zg8>OrEa3KKeBLd`=FVO~Q!RiYM*NhP zI^nrDGsrdf&MnNztKDnrpssfD%S!#pE|G6wRn6YQL`_aJ3z%-Xp%(reqV@s`P;`A- zO8y(ruN~}D-#_si@K`VrsCLgLF<`2&<8@OX|4x)!2jR_yO+A}~N_StpJJ!jR|J+H( zGFk-e%p6s27lN&30AFQWcQ0gf>Buil9919m3Kf0L0+(mopo_f`E3WF}um}SJ@qMVK z)Af@DR3qd3myX_T7f&{fnQH2$fFEro&eAS?$alp|_}MaJbbLV!nb^7_CS)wdgdCC?)-)HDvYV z@I2no?p^cqjHBNG`-m@!ah<~$SDd;Nf*% zr~=gAeu8pwxb*u|6F2crPm!e$D+ZtB*fXSZVOS&lASFl&8uXJvN^>_Nk~w7dICk## z!QYr17y~uU@}mhf@C1``7mD1T+xd&(3X`NM>7Xgjp$aZPEgObrMtBU-cE~5V90aG^ z3Mboq{OEBQT^^_CkYH+;*P!)<-P~^8FNaJmXCkuFgvmuyVRs9|c?r%v|ze9ar>`0S*+@1T0R<86_*XvYQX~$RHlBv&y zsy-x=;(o%Pqqlg!)e^Q5zF4C>IHNZyY~xRA6}T)sPkp*t@{~J6mTTZgN=RkLhS#Bh zwzgpobmz&c;$qA7^krAo4rlXPWD7ha!R=1_MV&^N^6{770L8w*?5e5JVT1e#p~{?I zgT<#XW83G4FQ)>LK;H*fr z=Jq|3{*n$W@5y>Sk-ZM^qf>EJV;xi*++VQ9g^)ZN@kz;DIli%M#L6w;agSzD;9wi8 zUDO3_IJ-x!p|CqObS|~CcLXUK|0OmE_~V>wF^IGFM;?qwJ|g`C!eTXa|N6;nAA}~u zfc;#i?DezpIV>dlEtwDTOZ^fSmkNkV18LWLWQjQw?$*>Px(w6l7I=CfVw0~jiL39w zYc_hJI=w-iXG@fH>iWa~OMY#sFeDiW^c+{$;yUbPlRc7+|>4xuqKt<NYjk2b`>Ru1Ko`cPIve?+}*3@P_;HFHG0bMSc z4Uc@Edn?y!Pv;p~?m550{y@7sPj1j*S{WGv0kktpR8d|!{d6&|{(NWTX7c7zr4G}2 zHISoJjUR_u3JH_ORY}nYOir&uxWXe+{yhTIzH+`b*_go0?Kq>T>ww>ZX6|*K1`M&|2j|gp|`jyLX zz_0A{jJt#}cU6_rNs^h5Q?GQ|I1+Tw(zEJ9Lf$1+dCpZwR(M0FDVXL~JzH-mu(_K; zHSD-V>`Ic9Z0^)VGz6ea=SuHF3eW|6`KWi-L1ME01M{6sYtVWF7gUoO+lqz4LV?GW z^dXyq%m$lvj*=LE&1iH+uLCj){GXYRq41Nr$y8f=X}S0?Az%i*O6znOd4i5 z_*O+EcXocg0q?Cvjo2Yw2Pzu8zjah^6iSMVd7NN&v_uUL!_&jkKi| zguoPVdW2T9mw>S6mHjiuC&8=%cN%{|4+hO_T5S^NFq^X%>4H)y2v90{aSS|lG?fLp zsgecR6}fem6;pOL_K3x>0kYK(a4GhU&=+*He~zs=_r2N223cK~G`qs`Qr}5`8NKEL zlRY<1;r)8R&K_AkDNm%PPQkGYQ7jO!;c5f%TZr9xNepU;@Zv5@O!wO z%JhFNEvj9lFnz^f{~h!aZwIZV;`F=a*2R~&Q5$<$>D(q@NjBDrgen){CxJbXfHQ2?;NQSMmaj!}NMd9H=>flJxSUEqP&w@ZA( zRO<4`Ricn%<2IWf?UT<@!>Es2+d5Nx#_U^`FXPQ++?;%iaMyBirxWtsoS?9~!NEyY z*ti};0-pf-3d>|%mS^z_831sOT>xraLypt1VK*nfx?ydw z;J*HqNpBP1)i2E6%Y)d#fv@(JK#?E|pldmB@@lsPM+8RcK8MlSiZR%6X%qMIYEUf9iwqc_Da>(tzo4MinJVV`G;imng8Cvo zUH-i$dSoKeG${)mZd`)A+c>;NLMWhP%bs?v3NT6%)SpH>v^c)F0VwH%SNIekT!?zE z5j3&=%2*exIiKz|*F#0>E3|oWrYeN!70j&XSRo05q?>Y# z&GVvLEyBmNC_O8FD*v2nG32;ttc|TV zHs6M=!i?0S-jNn;pW)kDhT4Vc^Zy9P71Dk90S+^QM75}UPVFeSTTg06CEbt)QWgzT zbU#N+lb4t*H%JizlE%Ty>RoFlM#gEV6eM0!8W;u%;>@vFJ|bro!q2gdgt^3B+p+@g zVDZ2D)YnP&AOVNlTW({gK_p-Eqp5eoao^sjqj##D0)tL3QGL>l#CehwXb#5L= zC+-;t`#BXWJRv|Ub(x*H*7fcwmiyYn1$Y)unL9PV!6eeSV9j# zfnS>jczbY$V3Bg9uV|C);B)LId&aB#4@0(hK2W(I(}LL@$WPPgsMl{szYoWPxd11f z#uwbV=12*L`%C`K=GX{>9QLrlyB7A2B2+XAr@(v(9VvGEG3xRJm<<38Tk!Z)PdGJYrf){XT*JsHE3M( zVZmKq!6n^b5s3iDB9H*@WH!}Q4GipuhU!VihQ(9R=fcqKwq7}etvEQ!rR^-e6h!`7 zW-Fe%?!<_Nu@K9Yfgh2k%F2mwD5yfD(Cg42BfQ{>5H(2zGRPtRg9hMPubqex*2+Pf z2q$zbJXF2!=>_**kF^`Cj7JF@9CNK28!Ne^~jObp7W^O4n*j>G4$?de*^qZd#d-vW%DgkR3zUw&YOZ{nO)Je zR`~>=i0~ptKZBWJfm#y0bWc;xDq!Q8__q<5m?BHKalOj?kznFHklo>Q$k0&zSC*h- zIs?y%!E`5+r?m%6WQS7js)S;%v~qXED{p>KG`}{D;Qo9`P;vg5eBzFUe1pH6^ay~v zJL&xhi9lE3>%)*ht&{jE^eUQ#YZV9%{8rv%beu#4ZCtcHupQyo z(BjXD-3awrSKYD&c^5-mhy~7t-qqlqp^;8@|8vjWe&1%z9F&S%-N!y(vCjPF=TWpm2{Zmnf=Yb&i4W zh#HJbf8FPeM0LjN$}HaYMe`L7v4GC1WbSw;&tG6urem?gs`PD;lgQ+Ck&~%dBK6H{F^>DKlOR!TU;boBQo&qg!;Bcvc7|K0*?)3U0I**VS1#STD^iN=Ymt!}unK z$LRy1Mtnkj*uv)i>DO+{K0R%Vz0`Z8Iei#jyl)EXICT*F6#OZ#uz;mOd%!7=UmAx$ zXDF31D{4W-+NEUF+E3*4!5v5B)m0Dm z_-^_SS=b8QAwPT5xF*-yP1z1L=jdA&pVcY5Vtd<%9rQP^nas55j? z78J7Pc6EPZP9A7e*rPnZos(RNyfWxOw1UzakOOspI> zu^q(I+5iImY^UmqUlJs9%pcR95?V7Dnh_+CO&^qq!#3w5?HRybFn(?z$@&8uHF??N zZF&KtS&mO{7SB~{DSqrxKJpW8s>%R=Tm|vd4$x0FBkShYAtl4Y8Y4oSFUJDPAzACY z+xGF~d6HT4C(53|%~wtqBA^h#;oKVGSEE{55C>4Cg@(=m$IWfy%WNk3+A7AU^BAy` zkR7510~$**#&xhw_GfLmYq8kf6q=gvVAM^ppYD^jcI>Est+)QO2mk*fA@o|IH%%w| z3)Joc$VTt|A3cl_pw^*ymxpvCgyl1!JP5(sXClK%=-E)Z{E^|$;Phsy_;^?q2wtrB zqAM0(0n2Nm^bHD@3?K(*7Yj;Uh~k8a^ajCi1q9R6V?q4^SRK!iWATYMy1rm_Sfa8a zsUp*}A>goo4l2@X#1m+&u(e4GdyJ_cch&fxUlA>TnygpxpeLDDSm}JHrJINo znh{%8DPgotQ?0g7IV|i+GWli}l=~5ghrPn(9zivn&Jj#>P8~IZN1B0rlTdAi!BMfN z^5#uG1Z>&+S`n9yKyq0O%krcC=2euM(c7vv%(U?5C-VJG%2E;2p(rgdj*6)vlI{7y zK}9Fbd7BZ~CW8%jU7i(Arh7Chw@S50_b^RbcVOXrRkiB^>*ol~3_QpIG%)Y;DiAT&>v)D7jB6nR?RP*&mS``A}^Xe zHi!l-qf)OoKec?F>&MX^ns?vm_uuebZ>w`g)Q0)>w8V`z*c1@md5nzC2G}VIM$!u` z^uY**1q#^UNOb<(V>^Www+#;np6U?sqfb;Xg`DUvaXS*-ueO zQKDSRJc(WNXnIV2T5%ai!t9$BlDg5TWuL8 z8!86ZqC3XMZb6Y*Kbl3X`j~O{~dInJa1qgir+-q{CKi-TW(?qRNIuo@b z$$mqGq~z(yqcKKcqgiUp=?+$arucFZruys5N|6j9!IQzv#PtRBe{x3)?$nM!6OnGRWN?YsgzX3J0sd7)}=j z{xRD!B0*$#ppyMTnpv;slw;U~WJq5j@dawbSc$XRz?bsygFCDJe?ykO8Y>xB-|ta< zt6FT#4WlU%+kHZZ2d=2A6LHE{7|xx1LpirfJed9yl>AbzIzu<;mi<^$h;SzvS{e6y zZVLBH`cRDUeQN*ZWRN*ol2bon@PepQ%{}=PbG6XN9uHNpOPxo&I7M+~xxrIrwJ=F% zSdpa2AoZIHV`VSxZ8gGZkl=Pf@FZu}Z6$Pb}o}Q$vcB$e1;@Rk;^uZQg zC^dF$=+s+0XW_?Tl5TmFToo@LadUUDfBb$~CQ4(;g_Dw!DEgc-!dgYl**%rp?DL>( zrx|Q{qjMFy1m9Xb>~oN)w~wi*!oD*Wz8l&@d55lgC$?r~a_>I7UMx#n#nU=Hdy*$Q zfCcJ80pIz_PGtPz?fFS ziN%JL2SJ~73}g8D*}*A5t63%$w%Egln!{KqpL9P4A_CD3x|lV6`owzQ_C%0pT$(yQ zWPpDo-#&IzaBgvtPi7o1xI1vwmAj~ZuWuYlu+a*?r(lE-1pmxE*LQ5nQWK-4;`1u_M|D``M zN!WJa(j*eyxL9;x^!<=BIgJ70v0)8|>LW@)VIsBv6}D`iq8o_%a67*CNJ9CC-y=I9 z^!+mPspvOgNbV})f+}e zC`+Nky9{IXkZF03me$K3b!F}olger}&Z#4D_s2H5_p0R1YrTm>&O#p-1$$}V3mx%U zW7m1krjPek1A#+EYjA2y`?$}t6EZcM)l+g0lG#bmDlTlV0=eU>xW&))TIt^J3%kt_b4EGiaavE+bqv}ax?@?VF-lov>4TlaokI-`jIJ$Cnftoxtc*owQoJV4kdgpGFQdl}%Y9MO@Ab`(PHi*&=(huNQ~@p&@;tW|aa_vCEY$Z!yfKo9n%X zrH@2q>9TI!2)#ZiV-6vcop!F4et=TWE*XZwNVupxo&YRfu^{?O}Wr)anOjGsA9}@T`6L7Tc+Y?0pBdF{% zzF%w2x?KHlfPxtCv~(k>F}!d2KvYRj;-mQzEVc;_muHZe*gAWmXi@5oK%1-Xfk6Bg zf}av>O0?KUz)-Zsn!FNM#yLoX*q0~WOp@Pkd?L0!@?5a*VKYWS@G5DQ6$})5H+lU|4%0W>lkv?WE0KOqx62>9gtk7nqud)_-$wHM#Nl%7I#ObM z>FTY@Xx9dT7L(>RcE7%!d_|n&x?!oi#z<#iIN3p2nb*xq(?ET^To!G3`5S=2MVm@7 z(YyH5uE4FMC^MmPeVaPC;p=4G-RD4dn~F2>;(C&CWlk7Ke)FtYQ-gQP;SYY68%mvY z{tehO&7A1N90WfFv7R;>=O zQwr~|(k+5#`ADs<1MU);QyrRmF`1IAtKrTm=-XSR0}r{Lz8ulC#bVjr?b1zN@MlYF z%^?~+X2OK3+G6g_NoyH3>g^UM?B6|L>$Ovat*N7E-$+azS%tZKx5~@ka`mt0=xoA_ zh=%G2n8PbKHOWcNGKpoWK9RGwPrLje&i-&xt@X-2plEB5~>1CacFQx1aTBFI%S6sqn==g|8!hxv?$;j zd`gClXMmFMWw#TX=JfEy7K;NHE0jS2)bN)vVgXMM%`P{vP)GM=90399XaZ6At55_@ zxsm2;k1+i_W;`O2wRHdZIXCmp^w?zruOQDw zjQ;J!dhp$ygvp>+-*g7?i&9rHPH^@aGc%FMTf44IQg=~`pJK;4wT=y&eBPe=N{0m_f< zyLa5CQ*`-vZsKN!Y9#41`Oi{BwzCqwQbK!HuY?p|s%&?MtQ*W4#tU1-P1ceQ7;@ps zpgu8Vh|7dKYyzatuD{x1(#OhS?z4XfZ+cibIK$o1Yb+8rCnw=&OD}XOVId&nPnmi? zSlPRyi)qNst2%UY@3(UQJ}1y8*PoVFKbnsbJ)9_x>q{e#?!bIIq;n+wF`8ih?sb$zkhHrqQE ze$^ZQW7y4Ik`?5FTmEaV7k?k>@7u_9)#2W-EWr4bJtkYy>7S>OnDqCd{yyawr$Uch zGg4*0NaV*d8b$wc8beBdAL{QrGU*qUAL+sWWcEt;IPD+JjOlYSQ__tmlu?94=TSaX z`A{Q|6%P?tD1cK~dVhW^x52n3d6k?Bc?O?MKl!jjby?QdjK#j6Sv(Y6}Q zN{_}a6N``Vas*-`BM7W#ah)g#v>{wf&xQ$PL)2)A{R0BOXy%|21Y5jB17c~Q`hV%r zgu64+ub23n;S>Ak;uA%%Q4wmB-#te^cp!v6OSr2|y{%?RpY9?ZP}BU6mgSNC8ZkX+ zht%+pH$z>HMgz3t&N$?wU3|hOtElBjv@>jpxfuE)nrX?MABJMQkU#Jv4bP)yV`oF1 z6;Y`JMUzkoLllHY4BUM_3RKerY5D>eRjMv=FiOx|IUMxZqzc~cE^izKUdVN>AVrJY zZTs)7CRcSlgw|}8VUTmo3y?PCHH`PYa`Lnv?v`D8v=afV$f?QY`txQx&GG}F`f1Oe z-$@y-&S~0x>2*-5rt%ta>Q)XnV6s8wu7wfE>r~18oJ7AIHZ67#NXAK?0EJL=UnfkK zE#|3f$z6+l9&5mR;5d^%Ms$rHh=Wv|>J<$YUsLFi`Rt*iPxzpD3Juu#-%g)vIHl3R zI2~k{DEc|Wzm`gF``PYJ*a|fup)%27M=UB4;VF;bMqBT*9ZkiPNzpBfZ6?woFE16R zDe3>Z>u$HR1{KGA*fb&F8rgco@ix#Z6u}qGR^h7kwK8BOK_{-v9Bgk}VDkk?$cqq^%(D=TZGRV($bfkg^3ava`>3v5wP-O!C#~UIP^#@>ap1UjBw?$y(PYH>0QaT*djEz1Q*EtG|F|4i0>i;g*6@xEHHJ z?;0AQqrtw5f-XC(_0@$_ts-IWHpz5O)_ZV(4HxQ%xPai!Jbk9AB&Vr9ltKOT%Rq!J`lA09TIXVbOk5{w78?pHg96r3otMoUD zH;9HvfjSxX!oeq6e+7QaXfw#Y)W~@DC!4!KTI5LrrYb@U&N>>0B+ZU_fZ|1q#i!XT zaG}xS(6=nv1tbYE*lxz9VmUB05x0vPtL$royw_&Vs2onkdMf7ob zqhqeDNkg@ZkV|kk6<@OsqI`bUiDejBurGHkeJ)v~bR$*wKI;I%QRAFH%0q(OU(OVr$)cJi?sl5EBf|GP8uGcKNg#<>5L z6oV|?4`dBPB#`3f=NC!-q}}P=SewJ4&v@bcFcd%ENm4M$?-Kudcc`h`fD(4+*50Ul zaH7I8s&pyW$m+ZL@iJWEyRG*EqPDeL-=wD^sby5O;p?JJ>_Y6MH?7k@{%A}3mXK1o z@!N=<)KdIfJo@X}+p&Dsqng@VcdfSF0Sh0^i7AbX*I`Ps3b41{^ZJKy{KM;fdiHLq zkF5)yq9JVqj(n!d!p*sLc?Z%E;%4P|a*@T*p*kVjM|0y?%C*KuMjPiPPvOiO&BZ3U z?3CBdjD6G}d#GFZMd&wv;#I{9_Z0v&Gernk8N~}4bG#=91;}XxmXiYq@n-qTC zcwFl8bIgbfHr77~RWjtAEl6^PQ&ZwT!C?vEpU{ye!2iqb837S>c+{*5_#Alz#DjiP zI2*_htoS*Naowk1=-m(beKY^Txw#jLYpdqoc^-8;V`?1uY3bBw<9+SSj9BVFB6r&N zz3(rY9&;pnY;T!;PWHY2Y~}v3IA#o7g!Y^PN`RT``B<5V^{Xo1UlJiCH3I;aR2Q7Z z0K=f_kKVZV0_hFn>jv>ngW^?(jEflv&BZ{a#s}!WlxB?hjQP*X2~5*J%{qsX?d3~E z*@T(^Nn!OXLac}Qf+75ac&Q02UcN-kEI5wf$^WA6t)t@Tx30m)y@Lj82pSxMdxE<| zBaI{kcj@3H!6CR42oT&oIKdr49e=D>XgqZ)(*m=-xdB^Ph03*s2&z@_RP{OKCZtr7!5Rv)S zlW*VkqZ8P}YwB`)Mb=~jPr9&|IhaCv2*z}?j?}VLIvFxcq>S`Dn3NW*HZ-<33`+yV zX5SUOcZqr8wo*=F&uTBP&OhX*`2cqgZ{}7R9QB*NaXQCGu~KgE<=B%QmWNZ1JZQ7KJGo(}A~! zx){H4Wwk1bkq>NXATBO>stYN`%y~!8#eTFP;H92JPE0)SD*Z5F%FeTUB zQs1em6%-o>+*{CUgjx9{JkFkL2)LGX!n?DL1`ML_xm3AgJg|$?e@-~mNjYylI5l)` zl0|!0zz0XHm~00|S7vDfLp>LiCfWhkwr2Q0zFZ(&BVOb4&n&~!?9`~{!j;z;noM6V z7G%@Yl~9jDOg7vlfQZ%%`v?xUm)RNCs(1s_km>l14)0yw#m;F31vi!T#@&QrBrE?x z>)wPx%jGhY7plAYWgJU_f0nRY+N^r2u+(HgK&u{4@9NA9q!xug=$WqW)BEl`)$!u%O zt${=*LnHQhbih@U=CEUu_0X@0o7f$i?cO{j&2HSUM=&&@1xdz^EdxG7!CK82}nU4FCchfW%-ZU%IphU76*klBo16=&%kh z9x5>MqXm4aTA>%IL>Fl%@8m@nX{peR;EaTjr2Gk}Y7v!_l1JZE@XD!U9SLs7NTP)5 z;NW(ZFMw8RnVpA+HoQ2el<}x?z%G)~_K$&qzW!$IP>U0pvLmocJYVDjPC!seF-`~> zy<1C8=t#a5CgaAlFC1}x8rVk7xUmkVeRKmO@jw978E)kWQwxf2!d#gM8NHtW*kSC? z`^Nji-yp>9U(3sd>pO?RF2!Yz0RxE^kN=UcFwN*(x3A8AJ7-|@uTA|6_}I#R$=B2D zosQYkQ`j26_fYBY1qDsA+1dxw@``nll?i|Fv=f?#&;v|f@9tjsP(pbp1W(?}k}(kUJv zhidr!`QWzaw3LK!NfD>7-|#~HdGaHxUOE%WDoV;Z`DJgxewF!)e6n=>yn%|M*J%5i89t@$&|=3W zRAyt;FMD!5D`-lP^c6V`5BA%~CN`60XDdo9j19}6 z2;NO-<5Old>|%z0SZf&vbE5~xt8Ck_!fMkD=A%MI;rn;lcI&blht9DyjSTy{nG-;Y z6($1dvfa+Ezd2Y{`NYU$7D~oU`sx)T7B_-1GG|7?BK4ut{2*fhw?*)`4-M;>@!)d< z6QlX4{*m7x-|Q35Qb9p@LKD5MZ5K+Vt%DSStu06Z^ykNrz3xA%>_+R|wDQ%|FYPLo zN8Sv-UTS`#+WxPHvcGk19aHJ*&~%$N81w7Q59m1lAmQ)D$&GYgMSOYi=f?1%PY+0XFCYJ5%j1$RWFTFq*)gQ>hU z)DRyv_h-LE?B0ShrI%l?+Zvz5XPwkV-%jl;D4-f@jGyeH56j3-%0!|Q$&*-EpmeRE zVQFpYzjOTMvbs)fS=2N;t6rdeZF9mC=bk(jv3>!^6jP>Tw5wUt5R!*8HE=#qG8|x0|m| z4PVVU^jlU&#?G2*-JCc!vO+FTGO=EubW&2DThevQXPMfUH)&64>Y<4#`8e9pA9MPc zgVCKu?F?D}ALHfU9_Y>^3+JzSfb71==VCvyJ0$`1{7ZrlHh`7W>Eq^+1(_>J z)7US_4SWSRI6fx9rm-I?0N0~*8?pjU-@vL>1@(`vm<>V-W*@>v&193(A>{yLV@E0w zsxW|Ahd?8B45%J?U{=nE2;APFlC6p;1_lOPMGRa;(&z5lM1*p3hCq*jqC(8}r=wsd zA`EcT4Q!X8XO$pR8tOVaFDK3+$_$9OE!tJH2s7j zeZ0siHP-7G#wN1(%bKEp9JQ4PPp-YTkF>nN9N9r4?A-Cv0s~Kw&U7|Ru6Wus zo1+F?%~sEXCzjXxRtQ!dGGcNY0>>l|>{jm{a@^=fdypk5$!0z<8~zdbV_{~O@cykZ z5#KN$X1&YE_N&bTaS z$O(PSm++8>hiXSIA9?gC<^;i^)fAYeS$#+@m*X>;gO+n1^*NYl9+Is^yNzcrgNE`F zT)3yc^niXFtD0jp&A;e*^?n2IxGcrsD&g89k4wI5kh`gdrV*n1F0FW>jOxe3mN>AT zC^`?Bvtsx+vc<0hxvz`d@ON4h25Aj{mZuu}tqrBs%BwA{51$-=#&5Vstz%;^jC6iy zxSAf0HUrFYn232Q%qm&OY+fAiJUoBKusS<22z>}yk!)Mo>@W1W1V-26v0aDOVqy>? zw!qkv5nWn(869o0ho}>SC*b%kR<3^^>yzH7Gmk_b!C?F-5hralu2++LJG6eFr#8Tn`tDIe6IhQM*kepZL zU*;aeOlrj!T}Wyr%}U9Nb0jA%s-2lDqMb}!=AFxyuqh=6g)a@HwRGpWF=H{r*TbJ@ z+?o=!rm7UjAqmE?MhqS(wi{R!&k3bxs%fEoOky?+I%vu6NJM$}*csjhsq~-Ktoq_w zdu;7);>A|fFr|~#_@w1GXxc9-?xvz5n_{Jjq6MLHyaCF`-IdwjD`V>kA(RQVLTBj9 z358m&MCRgR>uYJbrB<;#vG5{8$b?X|@t}$5^rl(h(S;7|5#)H2KH~Gu9}xUi^Y#|| zk2?07i=Gdnv(aVz?k}-y-~X(Y{m9o?axpQ$!?A+O*=TC4kbI0=|S0i zONK%VbD06m4xSMR4bP?>q^L36TwYdURxkPZ74x+vHV{7x4AncmNCb%9jcouZmqe@& zZ!=V;r`;vH%1&a)aa&kNv<&3NyF3WD1(|_`6x^RkG4~c~&CMEDy}H3=Q-caz3fUHb zXwn3BAT)#CN5;w?PCu*#!^*H1hHg^_F*vmaE0M-RXt0TATf9}jvUQVn8s{bP_tsc~ zrcG7$h;OE+$2e96;_GCo3s^olxI*SLokg%fF?+VJ7}X~yR(M`PrmaefZ3CyA#+Z0d zBrBHUXb!m0GtsiYrW9LOb`Fw8JHg@fqVe67@u*ky4$nW;&!rKoN)s?;EzjuMm!Gh` z?=_&EsT<~nA8h+L>`?Q-@iIJx!cZ0mTqRJ%87&c-XAg3MYG!p5@hiFEyTmn$5s#i; zTJ*LJt+#)W6Y zf6`#4pSti}(zBNtpaW`VQ415KV2c~Cnu7As(s|6nx!E-%C!!+Kvo$e&Vj8Q1HET@V z>gO6l0d|u5tke0|@;Lf2c?_dR?NYj_@tEUDohYNN_bUxQ)eIcCl;>X7F*hihn2$f) zv2NDnngFASMG>Jd8CYepOlM&_carE9m?*u*+pgbu?bfU#lwD=J!-Zq!8g z(A%owpQ0TU5j^QaX>(%G5T^@s8wPD3Qd_kKr3U#5L8p~<1|?@w+#8h{trdEQ9gJgY z6R8wjQHH^I;Osm1qWt2*Sf%G=;$Pw$?Y(#RR!jyVTF$=G_QP?)i+nRim3>P$*cyvX%tbjE}XVT02%R6gdO(hn@UM8s=969xH) zcv4)q)6L{vaTV1mZ#k;Pn(e#{s$>$tzd%$gtINxJW?UKT(eD$A z*}G26D;*5uN7oj_PZ(@Q7wtxh^^h3B9zLQ{Tomz*|N{izdaQEb>!2v z1s_d9_ae{NDc#Oa1^bi-^?GC(x!ehU<49HSq z`i4p0d*1OyDd0u1E|cMhiIH$Hy;hAV`Ix=9=!1Me7f5RYf(ys8&=;bS%wLU}*5%H1 z5s+DNS!4`18qW*&0dOTy`YWAcfJF7AA7Rl--MOd{=l=hK=M4O1V-}#`8Y4md1bi zGj7<u!e>5Oc~E-{#nGmADc!h8T7GEa+xGr_+`@tW0CdVQb_9f4||`%Zx-@Mkq+3 zUqAe~;B76OOm{FW${kRVlI~bjCX|Mr*|eTY_B;cHOy%o$5+xe)GKP( zeJCn?^(cigv)r-@oTwm?eNWsY{^dpe#TNGZbjCggXN2GqfZ>NoOR>k$ZW-7&R8D5 zHPy^54PbzP{g1USPSRQ=5E1I~y#j{O`ET2qA9}<8yLioPjrhL@@)urfKFe-;KGQj4 z|AQ0bs=9RhYU$)h9AHtZ0Q$qXMD_-O3f!P5{hDS(N>XUJ+PsNDie#(-bfAg|R2+z2 zENg+QG`o~^zY0^NlvafZLqw#MG-D7$LO+P$P@72fPZJBAqE+CkpaYEciRAr(kr_}K z7<#02a@=&@F)+|2^s5ARs}M6V5OT0z?<$F6*Cj)=#U=nGj8IMsko)Sm@)asxdF9;x z1|>ffda8Y@ZsArBFn~)i9F8hE;VR_FYw?%!<8a}tnPZ>(Z@)p8RT-GWiV7AGpW65W z|H#^#NmO!H+#VIwAic80GP-lEoO89DzDmkyvTFD73a_2F_VXkuFSPs3XZ)b4zH`h9 z8&JsCoTphWMl~8Q(rodA`#7lqhQ||YMBk`qEO{v{e6W5xUY}Vvn+h^dxcQl=k6Wbp zm0a9jb~WnfzM<7YcYxNQJ@ov=TPE-7)Vd*6GC*|?+4v1&;oeo?rE{LYGHv#c>dlSqr8!>nX3wAbM+;nLl$gB~oxbE2 z5*RuL<5idlo>bvSQu(kKbfX~7s57hDpp|DSqK-U~seH$=c5PkfmesVnlvezFKYYz% z=0~d7X^XXuRb>fN^Srkl+|nchKEt)eB2A${&n=uUdTZybBp&AWky{_XZd~hv=}MWS zHl`G!e1DDRKA=mo^ax(CkCgFJ3othn#~^)x8|Tole`2g#bZX?vuRYvq3s01&ysY-l zZPr<_Wvs|guj{27H6b58i5KQ(0+GWfU}b)uc|{HVjD^MJ@w}7SpsYn&=(q$=o8jmR zvM90)b+F#@{F(b)FK0dUWn$?f);%PftTB4q(}2cQ0P1?>-t-i0j{GC1(>x?VLpIPz zYliq()Q&zw1r{4)ko9p-N$eh4=MXmJIvDDnra$u{x*Q`Ezu0}$4sdxdXD`K`>M8}C zbmEmZDnv>kq#?w>OI*wvpTZbfrH5oKw`3@@qyvDeKg>lg>xedxKTD=8_fQ@yK(@0I zRHBz?t?;G2>jCcJ{I9nbb#kZfrB%t!j*e&VSjBals&EcB0$coJ#)CNq4n?(FO|4_u zDPqJSC-IuZ?rnMu1~rt~&mUtdpI0gfec9FMm;7~>mQfsKn^gBi|CJutudks_%)sKF zQgR>mLGqcn2}D6iVd^+M=zwB6bJxB$#6meWt1)sm^*$b~|IW#(XH2$>u` zVF6*TkpcC01}Oz7G(H3hg(lPNv&)p?B~hoi2EAv0KsFp|V!4SmdSCir7xnLfu%2&m zdhv|O)GwZ)0KPorhN;_OR{xUj20Ppg`LBF59~E_=#UcM!a@2nck#ZDE%$R>sR#*~d z$G!zGY8?9F*vpylzJPmp=*$y>J^q^7ztCnuP%tm>>*FJ+XURTvrr`_xrNg_u^tzX4 z1uJtKnAtTV!T|@iO^)Ix)uxkE`V$#N^Q!8~WZ0JUm9CEQ?Xi9V+ymzjlr4C0K=Z-% z?6b<|QfI<(BdxiIwiu(7jJ}cc&K7mldR#HVa^E(DMClfe}Utb?79hRke*=X?@ zt){NXIr2~QJBp{jK%#I;zWz=fMuiFYI{G1NRI9j(=R`?nm6t3mFrI24ny4_b7ql_& zc;Sqe6^h(X)txNfMV+TBL1iCoIkru>>`yX|G|XL07SdY5QnG8%&R=7j6ndY@i&g5y>@*G^+4gNoE09JSJii*I(VE7 zOZUu;4)4%URZ>-T3m5FOpjht~XM8y6kb33egwNlN7VSP_l^H+KD6-1$%mi_E`{n!NGyS60r9$w-Qi~7Qn$obU7o2Nk$W*#T}9C=SQZB z7>1>hb(llbI5u|$%(d?WiBbhV5paQB(Lr9tmW~yzsEwbOkJyWBbF=d(_K1WO+ADwr z02q@0MdmfC(hY6Is=;c7F<>B|NZ5rza5O6f!}ut5j`vRZ}i58RvSqEJXrLmMXFJ6_(w7-!UhGx^;CkprNn2lvFW9O(HA`?7ikqB0$0>@whWzUR>5 z2-P8fEbOMo9!bj)eQpxMo=gGlJnxxHY!vLe5Oj(jpaWPdNGS+Uo(_0rbvseDet<(FSA z1^%&{X^@ooJybG0OkwU1MLzDmiulixsI)6b8YLpV1YAUJp`Ht1>5~f1>VPtu76x{k-ZJP3(tnwqB zLniKD!(=Q<^VaUK$I&ve!X?jci%d8r_r*Oo<4|kedWu|yw^>bFe146U3gBn+4MrpH zQX#~{iXufNOnt8_!pn#By~Uf#RPo_`7D?XERz4+j^Q)B%ARd}n+2)qN?ogPXZEnSK zw(NL7Z(M?aVT;m|4bLWuaKz%plqb6>1OOHc^7QCH-7b=dNX!gnFY670LGyD+0J)z0(mPz4!olD7_@gR6w(Nlf?warpR7JsONne1ha!NVqKp98wa%FmM%x|GQD3fm*Mo&(`* zy^;+Y+AtP9^-c4xk?tmUkJs&@4H>aJu+!%6+dGGNEz4icvg&l7dQR~f8GcDGJd53E zqA=#qlpS(jD%V@hfFV0l8GjCBWmYvF!3*Dt>ilZT&U0_Nq4bqUmHzI;+d6yIBoJ&LLP&eL73Fq9to#h1Wg6FWhu$J8~n!=iH7z?txShwudsk8+iW}4gxKfpKiygv@5ouPvy#Y9|Fl)xO zg{x#*f#NIXV-`{AZI!otW<9;9yca2tPLpb~2A=Ze|C;iASY=pZ4gX)BM!fU?gR{h? zgl{y^F8MS@{_QbER^9Shx^FdlOj5wqp%(0FZZZ$}A9|`bH)pflg`XNU&Gkbbr{?z8 zra3ii*jR33F?P8=bMMQ}hS^2y3WI?KLy!dBb!e7#t-*74CM(`ZR&$i;nHlkytkNRX zianYj6qXWaU5Zh*lHH18iUDMp&EKE3M$bP#Rj#-Sm`1x-QTI9AWBu#!(Zi(ewGThU z&VE>}AOFaH>UP)cd&2XK?N`RBd+p1#N7}FJlk;zrfB#u_o9g(;TkE#WoQuL|={)A5BM+!_Zxg>g9Gv4~8EhB+`hUKf<=xZb zxXd@ms;R5XkBe3RyoSaldGIf5G>gqWjpk`}C*drQ66yEl2gA ze-?jpX!*xANd9?I$JZ~X{QaiiDw+Zc)9hNir;-Pq`BlF`MVg-uy>ACk|37%N{L0D@ zosNtQ4X@0BmG^WnAR9Js37@&oR*oI1&n;TS=FXBf%;<=lrzAVW^SK8+H739gwVhxz zNmaFGWUS$s75KZFni=-}HR-o25xgEJ?$XaC4Z{7VIsV%`lk zbcNz`u;OYxsfY*+wS@es%wm8O4j^+m`lE9>l*0f9h=Ee9Ba&BKN~E;)4uq>sB+nQb zN)Igf`ToIS{TZFA$=Vg0iNyxCf*3qP=ouqZOh;rm3&keICeh{OLqgfx?HA=pSb^p@ zsA{9kn}bZzPmlKPNIC38P?_;VdxJ6k8VClz#@HEiTj=@rRF{r#KV13acYZ$2G*Oq| zAij&52jT3hTF7GYtk6W^3&R>`9~y5XQ%YoF*q$DCR6x65rSqeQr@>Vv`K0V$ts4Gm3P z^<3Agz`GbYt~4W|+tqQQ?jmuh8)C>fp>5V= zqAb2;El|KYut<-%{38P%ak_R2dQRf*!RIKc?YGUd7VVCx61U3Zzd`JmKda4lpvAeX zA7hr?qVESek-gdvU`ZIuDJW3zIE>qgCwU~#GAFGeQK0q&qd0=zO-GZfBR@U8|7+h( z9E+c3pu3CA#J7jdmb8WM2IlyR_E=5?2;Fg!7#>6HMU8F5)+)}$9<|P;@3}qaKy3QX}LT3ziYT;w;9s2M7J7F;fNM- za?>%vGDF3)d^`aJy*PMK%0)Zc0DmS^9gM6w1Y`Lj2}bdjViwouRc!Pe0I-${jr%xx@p;O*_=X98)7gpC|JM}7#aeLv+m|D%wXhOnd55q}0fN-%TjjMk z4Q-9RO?o&K1Z&NW{6R8{#@mbU#u=BLjg@Tj(6ueKyi4WerC2Mx+4B~1E_8A(WC$Z7 zBIsr6q8WPlh%|6R^k{L(k_m$ffg^y4l#7~+KK4`NYgOl6@E@mKpyak!&+>e0%nj`YZh$tp|B9IS51NXG+%GSGy45f7PQSRt?zl=}b44YBSl@`H z8_B+gJH792)8z-`ABhpln%iMlWn!u;f9y`n&`(RXAbdgc~ zvNf;d-&7%OC@V{f+Z{+IXa9gF0Gw)?xG*<3%#61HdNuD`OMjo*C$LO;D>``F@6q

    =fAf9bDIZcvi|G5|2$asO>)l+ zHiK*Iu0y|8YQ>sf0$~02On3-BKUv!FUnDJCbZTGTLRT__)Rb9>*xYfAtZ>WSiV*kH z0X+H#4l;kr{i|qdw3sOO`J-c*7ICa|6znk|;laDZLA20i!Yup6aM-W8xvJQLh55uD zBcs;*-8+(XPGlmokUGGuSn#05M7Zwl66!(X3ujc&6~hSkewdzzL9g+LW74x)u}i+Ei6o=_w6_y3wutlz=A+S;JtsE;_{Qhi@)xxB;16mC=liZ z@=1q(iH>+7G9&VTA=q?m&fB(qcC*TKD*byQUAu+%XXP-x^f{B`@|@xiegOr%uXedB zfg}r3TL1ujBb-#{b{tW$fa0Pmse=R66>l7CK)yMzp zY?>X?zmn;eOtzaXg!diHJTq-efQPHHEATfFlm)g{V8!f=Sti68A;Ck@7#=n=blZPW z(Xy&x4(dn7V4_5ZZ2Bof#i)$`0E+$qrc57QFMDjivnfbZDiB6&(Io2+w_0*S8LF)$ z82G*iE;(x^?R2W}i3^EA<9125jD;*_-8-@uL6t(m;T}zQ9$0V>ifaNYYHy@#@b6vC zvR?Ze!~8W3s%5;ZDZ^`11y*D|kzt-kE-oI-OJz=2QB@16KH>(QA>l*3KtA;=84Sef z<_#O0pv^dF+|K#jo$9c4ZVt@Few(f`+U9&`Z!`jknbT_d>i*m-OGkFxFqjMufrFIZ zn?0fS;*thAw}*k?6IeR)!;FYPnfUZCYpu1=eL@BpLkLSz15ikVN|stqmioo~AqfXh z`IiQ#sJvuUs0?>xWHJp6)qgy2%Ek)dwh?|nNZ*cyd@v^B@Ptu~h zF~PZ`jIAtGAlv!m6TJx8)ydq%$q^xd3h9sPLLG}uZeJd3U4LH>Ha&rZN0CQXAjX+ zBEU;r*zG4h_m$LD{|D6!1}q>Y+Jclw<+;OM7f)3E*cm4rH8kvhkoQ(`ZLQt@FBB~l zcL)}w5Tv*iDeg{!OCh+s6sS;KLJ3ZR;t(8)ySo(k7I(J-EnO#F?~=X$XYcbl*XP{K zIiCs1MUwdp`;OlzXgZ=Jx(!}@%Rk61p+UL7ZP1X1l>g%c(=~R_5xwIu+0YP?5*<9x ztUkLVH;$&8?v_43sjd>2R>T*^!j0MHk5LRa*s&dsv}c6pzz0X$!n^zyU@Nw3G@L2J zj76ap_7cz@OsqJuU)%BOXsmH(;mkfD(57pU^W-C=ufi|T8t_DJg^j0w_{&-MzKO6E zS&Z$j@7x?EuB=bB4J2?k*Np>Sj<%83FEBaYRwsnI34)^xVmLfM!-#nsS2#KuQDQ7i zYzn6=H_|IsLL+rn#6_&OZI!x*0MiRT2A2&{B=1JNuWLOJk>M$9Hx?EShrqQ@l7e+R zRgOzj{P78kne+4e7iC{*4O&fXatFM7U=~IDMzG)=olUbzx9&O@uzl;`Xlnre*| z*k6RA6w?gF*jly&Jns2>CYjFi?6DYPLe0qWDl{LW)qBOc%d9xZtJ|7PS=l2#MuQ{h z=6yo-hS_O684N}AvQb(;5qHEUCMT}*6p(T$W0$BQ-MtT~(%3~fggmL(5loLm+1`c7 zArr6|7%B_}N?SQZ`B@G`M9gwp8boMAG8tQJ$iET#v$_>XZw31ocW3oVb@!KK=apJG ztKs<#*cpNdm;tc^ijSTo?^ka?f7J~`zRYQ>K@soH*N!xqPRI@!Y}531f~issIn@I+ zdDfE}$1NhK!{gW3Ot%LVCuh)Dh)(<^Z1*Y@+Q-}*#J|gNuO9{YVtB=Dm=rw@!`>;y zc?U0nBqtakDV*cWhwe8gE67^4za#yBk+p(z!zr!znlIv5?FAWssj%joB~btmnsB$(rloe(Mj(x>}v63d~>a zNWH;Bjla&)DxgN1`+HZ(iE@#@&KPWezo7Q77uJ&ImcHw#EWA9rpZ@Fo<^TI{Rb8P$ zJElqRf;1{|Xh^ILa>rU2Vtpwjdk7SLy1qqT;r~fnH0gF|3yVQq+Q!<#nTQ-LCr3AX z;J9qI`X3|daPI`DObb#spE&HedUF?Ru3qsQq+-}9l9b0T1tr>IAQ6RKX0Bfe<)rgF zy_aihBJSHXp%Wz=X=h+XF@jK<_u-vszM=gNW&>GV!ybzUIhjd55e}PfTzS?P9&EF8)f4GhLfl&eL_0q0R-kRuU~Tp$zDW+4L}bU6bJ@yNv?nGf1h z!a5N#*~C>K28NW)$o#F)EFo}~*~v&@mS@Ncf3jG*(MPS8srJn36qUJc7_xB;Byf}C zRhXHqQj#LDrcAiKjp6m(IHn3Rrv4;M6nd6wvTxP)1#tVt))8k2<{ydtG`_j`R_&GO6Y1U=7cG~fYTaZz{-ts44xLZ^AWuy&`?$gy8)+(VMFXrM{z zQCq!sxB~{<-@^z5BP(H?_NGH3RJ= z4+Rr)yVKuTihQ2%H&jHtgHb%e5;$G{uwM1RQe`kNBrvNzKqD1!Ano`$1_huYiJ~B0 z%7O6l@$GM@6w3qb_Pt)sxXLZ!gf8DH3W|}u8v`?5|K`K-9H}+X6l48Y5wFtyfQgEn zlhqea{Y{+|0a*g^<_H;bl7- zjW)sX)B2^mkHTUI0|6FDzg+NCjgvW`Xvmm6odfLBbrb|ML-_q;CbkMdy4FnLZNng z?b1ZK(Wa67Oz+t#5xCJ8VS^15yhw;%*7HSrnBP5Fq17hp>u>;&sZ|owaCCbSzE}_t zNOE4j-Sl9MrcBB3q4wDB08Mcd>fKm>jFztGBJ;E1K{3X5YDJOw$JaQ1ScCr#mEz07 zCseQ?d#zJ@A_5gZtZ;=18Kine z)-ki{W@CupkZz-|xn1aON5c6-kMZe%d}QNXi9QTpOa$th5fwZvAeL-hA`P(M%lJKOaRF4XtIl0ORU_9mZqH#9Jj8pr#_ z^!uZtHjNu+;hP6C2b~4%&p&2PZKmJ2PHJ3>E!KWpzS7CBf5iFguZ8Yk|4NGBdK>-X z@5QNZ+eh_>4tbF3OW?%c3$ef6M+N@>`!}uGX_z3v?XoIIWA68Sw>cmfksI;*M zGyn79FJYtEtFQW_S%n?D$A30GR~Dw2__z5K_CJA-Kk)q! zGJD2}?34U6qy763pVe!i0t8}tVk6I+1Mg{HU6pBnRyf6j?sgb(XB;mvgzXnA3=XT7?Q;E zr4Nwr9czb$vnoZ#?_E<@@y3ElL^_Intu!w-iAZn_MZv$p1=?GkZ@m;Ob>POaU%wHi z=r+3AuWI7sYu`1{T<=VY0t!A3Yu%)=ZT0h*P~bbIEr?b(*VK_k4fNP#rTW-;en$7^ zQJsG8Q>NP3R#nzQczO*Q9+)#Jyb5Nf6+n>W;ILP^$KI7w>UD%3PiDx?B+7tw*{}4| z=|`!bMG@kKjpN15!$U_4m30=;O)gTR^e3mjGJR0F*QpP4V4NRXFO%ETO*g~!3L31R zP!2`GIm&Am#>&X6(AtZ)cbL$TPlSs-F5|XuEZ#WSVL=q2^PfJBav-XA=07rp%oo zP|@NObrUA_jySRMgk+zes!ONNqYvT^Qs>+nQ!y4Qe_k@$btj1+LkA9Hzc9n&eEG2o ze5QVJ)p+#BgK$ZDFBgheJ6JrmSx{VUrd;T#H=dmvO$x?MkZ?(+xGhe@`_jqPL~9o_ zy?!I(t{4x|?j1pzA}c;@+(=6Clsw785QUx3Z|RH$-J6@vgx*(J^+bL}u{*y+%IMx} zsvX!$7{s==3!CQ=74f^UA*EC9e4eI%IRCJ)oN-fT1OK_}{Ysd;(Y1=>x&uG2wS$*x z_4fgRW4jKAf&pFKg{|&MACB!2t#|e+6!Mj=d4gfN}*^Ps8ROVs54)ho+X4Jz07@ zP;u=k-C{1OIE;%tnOO0thFrc;9~hGub*`X=j&Srl=!ty~E5!oLs>hy+IGUc6M~}M4 zo{7IR@>W=Q**!J_Zc{{!;!_@p8Zq!n;@aSC1SCvU+j5S$cPCLoh&I&7s0&17cnSy$ z*z)6uV;H4Z6-aYQk)cWs5xTVuf+w1|06ARz5fF$S5lkS6qw+TT=+Ea42Pd(cumBtp zZG)6lQn*8sFI*a=No=8cbPyb+bGCjWyq|Uv!PwvrrGr`uD)`WROUcXhVxRB1r9V=h zjU?SiPl*i3E>+UaK;C$5-+9$N1}}Ux!%jw|o3% zV)-xk*ur}t9B_xK!=J?Vd(Vm=!wJy~Rb#1i{8){}aGO%Ld=ToKm0VhP^lcR|pCHW9 zJSn(-b9X!?#vOAVgRC-Dyox{BFOpbQ0zm*UGAMlOsMrIk)+`=RsI>E2dx5-HP7dia z6EMq><|23qbs{2=+Zrh_^8-VOZU}M~^g+HHr<@#;Ko#T33t`uV2czhQ0HW}bt;i8? zF%QWbg%MODU0XHXeU&lFC|zAx)=;>ghklc#b9W}pZDcJen{Ike&i(w6-dRiS6E4i` zcNtzfspp&?O|i@u82OnU_lms@Qtl$*woKJQ60fp8X+SRnk7;ff|3I;7+7*L?33u`8 zAx>BkY@77CNHuvsvpP<9be;^16onhUoJ<$m_TI7=*KmuT5Px!K4xm-+I+{fG14xZi zIF@P^5-O*o$jO=fwC=nuXDmQN8p};uU&NJ$q{y zKOD`ky&J5|tjr_vjNacn)U+F#s$qLCWsgsJy^O$HLr-3JWH0QI#SaYU5E7-mZS6X* z+Gl9s zGBu;1tFZL8u_&jB5koLN6-&bTTvH;F$y9}jWpC!IgFUj^D~eGQk|H(byNokpFef1R z&bm5-SFmwQjGWcEI8;R55QldYM;Hf8ruWE#Oa_!l)XY-cPXx}xW|YR!eykIvq!qzR zM5q&`Dfrul0`W;1caSj|@&W%3tM*qi5eFLytI6v<3MQ0c?}l0d8kCVSr)PTQJ+Smg z(eEcXZc6e2{{Wet9|rw_()8+Qqftn_i{;N{xxcf6h7Y~HE^46yKqmeVf_4qq2J1Oz=(opfmVnq9l-Ozy|( zZE}76NLWN2y;?wS+(Rs~r;BFYL3?hw8Rg6P-mey&Z*|Ez4T>(0a3Y!N`oskx((M4S zi&gIo%F){!7~lz9c;LksSLqpAPE~}lZ@Wp^>duK9m8Pq=8r-{3x&?J`Ku6~sr>^5;i_(WbtQ~bZuq94FDrRhLiYHJqVj;a zbHGcOJ*%DPPfpjjLPJzk*W4-ILS@l8Z5A&)?N!Q^)g>gvz7-u4&nlwc>DJ;arNZwJ^gnBXePE$jPm^y^kTTo0*CI=Q^-uGnck(8YXv*&jTY0qo!MXr?e z(l>@vrna8Ldo8&MYBfsMT>~Vv^G|AT$o7qN-ovmqDUN-j3 zs$7b{`{5pD8}}9kSE+xbpkRjev*Jiec@Uk0SS@uDAm=D(!S|4pXUw${OR)|HFvai78Xj?$$mY4+yn5V zJs~So*aE~xY~^>$&9ntoZrH7w+b`N5C0W)_YDxxj<5M7c<_4P3-B+8f9E0*I{@V6B zNMY-L1plS96GgS6Wq^#9Sq`MZQ5GsdzJI)622c_xA6;%0RS5_4AfK>o{I*e*9v;Ap zoU>b10(DDmjYBVeEG}AZO6ZeCQm;{drm{%=tE@{a-)Q8?Pif3s)d#GC>nC)S->$RI{ikZMd)$vMKw+m=ttP^X8u4K>4FK)Y~S?; zHbL8Yrk?j?T3#HQz@b-cu z+XAI)xD*$^3PXz~o2H~wUI+7_N=S#gWPK4M&C=;hv#^I-_atQMF(QV)p~vjBz~yGv0#Py8m>-Ba zlHLmH8+73C;x1r0f4|{oUVHTi3K%w-aJgzOJGyaEtl{tkIg400EV_^R0Ty;Df{^O#YN;I*Z-9u3dy}y9&H9udJUU$$J$5g}U zi}s$oh8FN9UhHvlZM0TF&yAE!{m?T|Ke^l0wl$4G4;^S)ZlL}a?Jq*TC+m5>p`f&b z$J*kb80;&HCRl730vPj9USb$B_-iJlHxA;qvSVUJ_kZS_k%@q!M-ng&nRhpJqoC^O z8AoV`qJz#5j2O&p5I}HtF4C}Q@MRxGs`w6rs*{u#iO|^~Af;}$>WE)wvu1lBNywh^SnL~e0>9X zBL{iov3=)(bQ1sZ2`Rh>oEOA?Q-t5P^YN*g6&EzY4()u2=BZ6|tBS#y>L)FcId^h!Cor zS&ILjKGJfHF*}bl_Z(C*02#C?hK2za=`$LMs?jq-KItA9Rg^Y+N7Pm zz3eeq$xKH^sV`?})qUN&PcFNd>eMA` z=LG5-%WIo!?l4H1!a#PV+fMFrBu2FF&bX)<7R;W_w@E|r)NhWBJ<_p_HA#~^pX>7p z?LNU6c*&d(+Jo>W_ zMNSS9|GVSDfS4zZP7phiyFo!8bBqgj_3bHM$3}|}vaLwIq)cmdtynz$NNh!XzC__f zr03&Ewc9wzEQWR6TWM8?Oxn6O7hfq@CTkWAo;8CMAVYrbYB^g7`H+NW=g`No@p5ts za)3#q0;TtGpi;zN4S>L4EtL-*#pB}keOuD*nvLb&QL^2*Y3GPzaO`jyLy}EC2`a-y zmwplnPdkNRh$7q(jZ^ZQA{YrnfMk|f%m(!Nzy3vng%3(RE)vkRDx&dLingy*jvk?Opr{<{v6aP$@2Re zgRzBuT_4RygH+it@JUj}Gds778*W>jMf=#M@wmt==^^j+G^1FVuCD{f3(fnEwgtj5 z(^-Dd3~;-7yPLE}8VvpIMqT3kr2I4efj;_jiD*{@)7X^nn|gg3a96L7xsHUZQT?{= z!>1Pqt7465;ntW%bxLb22uFg*#qPzLQ%5fRlUrnU+5()Qdnm#N0& z;=%O3`#{#I;YVGgmo8LbX5Vs~ZKtbHsSdN${Tv|nxUA{D>LA+?U+7^btsnm*Av5fc zuv2+`0?&e?FcqKR$*Rr)%Ry4D*q_g0jT-PlK0l%@dTKams}#nTItgNxagfktgOx+F z8;wAiz#sCBEke``{$|e?xl_#k z4ktZ2wC|PIe~den|ABIpUU_2D!A+jS{7)w(7vDeIh$Fc*=$eH~-aC*K9RJ)Xa?43u z;j61B425o=(a=<1VcxMkufX_8{l`pewB5?0qNJcK436Cs13bAEkuxUrN1JC&d8>>;Tu+ts z4GZQ7wH>3uNu)PR`#{*TXGeN!MyK0OREjqqQ@`lzsP$&CvMPN$)sT7Wk-TSQ`UhC6 z+%UV$sk$j;CZOFjj1?U@z;}_@5e)+TYpyK_dGo!hwP1H{+T=92U1>eO*H0tn?Kunz zko^>ErDMN*+>Jx!e3RbXewwA?prG4t6?maA*K`b}Ng+m$5ySuH9fVbERX1xt(h%Sk z!n%ku!&a9K;eYWfkoZfgdziYU+^Mn%nCEjkJ9+Vnj;rzlO|OrecGG2MU~p ze38?E(`PZ%AT}FgV)|(Ip=!MC3U!wz%uWgTlnZ++G~o(s03Oe2`{*&7q~?`Hk5-4J zdhL~*2$S_DzR(nhs2oyftLke_&rE>0jw{ER;o?9d*ClX|-AkytvPQ@Bc*$npR926E zWoad}g=ftbzZm2?mPkY_pI0w`;z14+>+=Pj9k@~378l}&|4C4BUZv?O|)V4^5vNb^yL@n z6^G|?h+=rnA1HP$tMrCizbIs(b)7ew;?>jqWMr<46TI@28+ZZHk@(C4?xH$h$s?lJ z{&j)>y=s1tn0(zbtEabGriV4FEzwt=Hr+?)j)jGKf_{QMyhSlfOY6|lM6a8b+Bjif zQkLVD#95r45o|x;rP{3|e&HsDmGa?*>~ym;ZQun`l)WGL<8?LN(~+(NT7`-*%JCSv zZGPmorTl56r>A0-&@0;NGuYI{$oX7HmuHAG77?a_3A4rX7opqOpqPgU{TS0%Fd8v% zpcuik?jO@xU=x|Z;1Y@4F6Y`Z@q}w^N~AFcM%5kAveHTpb#L%RpH6Ha18!}z4=(3d zsb)8q8|ZiZE;uNj4YIdgXy!!yOO&@;o!#^Njg(jFnqS`kiInS4`4lG!UK%>++ERo;3V^~qa_jfIF%cPTPNM(#iMUIC7O00C9> zst_q4`ywMW1}U|4S)|!?Jo1Jk6G`Fa61Q01#^WP6{vt-c(#9p!FO;Q9?T&Z1jX>!| zf?L*5q3Z3QUyurkbpw{4X&4x|UBWz+j8pR$7{0u(V@PsUeY z5($m;Y4P(mHYG}+Oa4d+j_~PgbCs<3x&Wxi1R$4{Zy>T`Mds3S1)E4(D3pJE6D*N#k+1x<=9%I>=UYs_{vQ@}!N0(P1S}8}$ ztR~S?{&ymlOO1lACe3$o*cHzU+Ua9`UWLNEyP?}AW#`0~AM*3SdlwqRLm>%6POGTr zY}V`&Q49SA(P7dJ4%epGzi`50DkZ}{hAwuW3Rv`6K`B?IPxauY8sFSqcxscyQ;ko! z-|{<^Om(@&8+&Syt9}f1?y;iWazZegaV;7%V$_hK`;(2bbq(Vp2O5Jm!(+9AgGoV& zgu$W8JEe>=z$6TnU_Qb`I+Y}yV8RfPTZ!xtF*p~9Not|Okbe}Vv?{$wip;?3lptrV zb^eLlJ^B+~Kpsd!q~vLfe{1D!zfxY#d4N0+K^{g@wuc`S_n-a>_tyRcWt+@=rRlW^ zmyFW?G(c&Nb68(Hr!FL&`-k8-ueX07D=!(woUxz(AXB-Q8O>tDM!0Yw;Hb&VNU=!! z>T(L*_h4x`bZ6U8(Lj+Fr5VyaD78J)1`k&VY!ZE7*q%_VaA0)atH()?tPln{Mmunn zj9yfA?*q_bT$nPix>EdJM2`eDG0SAVGcUgiHJvIsrTfs*Uat>U2awID9@tqVzx2ys z5a|5y7#}U}qcPmAj`!eR@yo)Vi=Mu|_ENE_nmw(-?M6vLv%^y>IObcoult^U(nBcg zJ<+&Ha#+P-CE^AMmPHCSS z)p>zW=3W_1&)JRj*iG(}uSfZ%?tQ!`4*o#F zS=db0K|}ZVyzoKIT^%viG;}BngH6ghmp2i+cwco!g2FsIQAHv{U{3`bH+&_kCWmsl z{*V0W-^(@{<*V6}t1x)9hSsDJXwUK)Cs|e7cFs6AQ&)gA74wOhen#$bUL_(Y`B)U; zG52M9ZonnqL_+V!^sl;({pMvZd9vgzoIz9c8r>d-H)vr1RId=1$AFY1AV=lQ!QrSz zg+5QZgk)BTnmttJpX$cHlaZq*#Kr!nN{2cD=q_bu_UEsEinU+kJM8W zsHj$EF-S`#CifALPHC7gJ2yCZd1&2exZx7RDPI!RNM#XUNxGoiht5rpS(8KWCG^t~Hv1|pcYcZv zR?~w{EbWiT%E~##ij0L}DT(m7k3!u?HqBpD?zPDl4-?%t`ziG(j<|u1i1xV_=&X9OP6)}QH8xQd8`=#A;DSB^~?C&y{Hqqg{@_JHh zvst(_ioziPkHyrf?XXRqf()EtopWqe?r7q>j=F}r&~P6$EjT)DQd|;ByA%GbpbT$= z=9hr0-A}vKrEhMrouJvQE_K^>vlH;R-D$b1LssXgTdUl{&{HuuRmSngMfs2$v#s|{ zkRl$f+Qonj2X)lXA}5nyH}`Fr`B%Cz`#upjKU?*82BNi1t%_hG_J~+zwCLEAC)?{p z?~st-{i<11)bl$kmS3BK7SP5%u{RhflH5csRf_v0R~1mjRg1>2brSSuR#~fF-bltv zQEwXH>L`7@xVY$T!T`u}T=V)GJ-cW2sl*{rEjJ)QKEUT<_aI1EdCu{t6K`hS1HVLW z(2qAG0jhWvjFkCd=?tAlJOb)wDGxBnTjd5 z>OMG#d1i*gd$y^J*<9-P!=Q+mJH8qtQ*x>pZh9kep|3mi#HaMyk1e_`JV|oonGMj#T@>Ur83MPgPXw#A2ui zU~m<3q$SypU6ghA*-u`AEt*;^jF|>&R{HG67BM-3bId#;pJTFfy0jFAcN?=q$m6(G zlH5X-X|n6HkzskFvhJ9U59C7*ww6q&Hcq0bj(;wk6v!^GlOOY&(+d{fDL~#rT0bR( z_^cwl02@gJ{hPn*{%sGjC*oCr`1<*u?g6s_$jR$u=BuKwO)6(x;O~%eI1KLYu}C&1oO_Bfv8wdW(5O zcoL&ahR}d*#$MD67v+9FftZvljw!9M5~bR@Zm6o-5+Z%r9}8Q2VQMF=?U<6KjC*%U z8ZD)2UtP5XlwUMmkDEC;Ngmk}m8{$=u87j{mX4@;cY|Z^0b=M>IjdGSL+$?=%=c*7 z8$7ida}^uc9i?A2E99R#SJ$unk%ULd%`3I*GLuX`7bF;R?jXD;BsfoHGDNHG=9xYx zAa;hVE@^u!VuenLx2DkdFMyIa>If9lzo|i17X7AYXJ&4`iz}N75QJsv)l1U@G(QNJ zVT`-*HlYJp-YBGREa$SneBqW#pOC_egW@i(zAC&14MvkT3L*!XwW5Z5!K&WJ9m2x0?IyYj) zO}kw`jkb$~XTZcyR#AX&?%C7YyH_W^U2dtZsB zekninn49tpBl1hh^!jg1r8V_gYm2lbAeY3e8hor|K)vl}vG*+=5h z?RTFiA8NX`D(WrSHfPl5RAh;4IlTw4jCqN=iHSWGs~AeJG=kV4P_sK!&W-eP5v69A zmz5>(fyZe4GFiOTHypD+h?U`^pm<<*C!f*sPqx?23Ef8>3)_&*TwPof4}vV>LT|^# zg=3DFg!EjVW9b=zo)NAbv!*UC)0Af2<*h{wQX70ZJE4&1>I|z*p}kqyoV$O~v{ZTK z5D;t4?5nNoTU<&iIF_9*J15U{f3Xx^g~eMQ5NW~G#SA0Vt274d%&k_=`IQ`8vp6$r z@@P|0(PEUxyo-hB^udVI(2STIY1Zn-(7469fM41EmngoCNy&?)v@RdFJRf=KJvU7ab&Mk4AsNDQTYlL=O}% ztKm>sR9NhvD95Mz-js5=%h%Py%%r`&WZJvdl=Ki!xj2KRW2Kx-BlSjiV5TLE{Pyj# zr1o-5Yu$h=YvJw5^|nZ>ywQl0XeVg>I>??F-a90j!OUvz(&D0jR0NYNN_RAwqDg< z{E*69aQ0uNIc!E5gfw>jZ^DB#L^l*$D=b zdwh&Q4K8{c1z!mSb4p)tW9An578kj$`|1jv>f0}-SYys5TI4u0iD8t7y#1;wB+M{8 zTrkcA7uaHFV#NCR^pi;M(ffhEXt?uY+lHx7BeBHRSY$oaLprtLi<&1bos8P ziDgul;&N%MRNC!^lS{C{1nNZ!zohh*F{l{_RAsEMj3LFvyJ67tlO))vO?8^o7(9@1@&_2b(wH+sN?C zl(lja8G49DpDt6zjR*aKqSSGeYkckWombf*-)YqE%z?g_l6N$-0VV!Cv^{jvYH;(h#Cct21OL55^KG2tId>Ny}TgV@bF+Uxhd!!^Y8jK6iymR7zYWFZI8u4b#Phvu&j880s&(`PL9 z)y>1@tMI-5^7E30}m>;0OUJ$tAV2fpSSLh@`g=pwB}( z(KrxL0aiL`D257$GSXdgnq?@4#gQo-uM)@G4g1@yP-;XJ8 z1rx9^93kWY1Io6vcn+0&$P9l*2RFrmu(H^da7q7*qx4U|Z|ME6DSr;uZ+gSH zu3dMoCy7(2*Cpr*s0=gMfQyWH9O2`Cj(Fm<(@;g|50;)?t~>63uOwYW?@&88)nmdT zTM7(>y*_4r>Ss~Nw^JJ*lK~ZB=E|q#IzThkL{h0*rjGj=yIsc2bzpe^EBV}+&b`zuB@8(29Sth4&I_beqGqZ^2(PmAJhItji z-&`8x)pbD4C4oxDN)AAtrcv=gO|IB+=&NZ4J5QKMBxr2j_yD&rey+J`-N{plr8Jq+ z7*IFiGUjzkGt@0=>vU_t&79@^kE+{$E$JYMIPd#_0zBUWr}El`%F}{eX!J+i>?o}% z4Gr8SrIm!xLEwH-X;$LN^swa{?okJO3j~d4MC#8UEddRx55TWSv*e}8`GK`boV+76 z_BnB}MX4hO_yo<3A#$^GGqWFOhHc)6)=p1OBZGi`rmHBj=#(weuXj(s^aU9-y_Qx# zg$F$`DGFC|BqFlNAtDSgN0i<@`2LFf1BJJAzwVMAQF-^{?`6R}<hTp)ILq8y>ZP_<5~%uFJL zkxE*Hz1sqv!*#2ILvt0gy?Bj_OwYsD_`Yzr+U_7NCVRHkdYLmSD5++3R!w9Tvs?J3 zry=K?B*)Z;WL4&VLMJL#(q<>0GG1;mNSXuoRyp$s*CmWQpyc@)zUO(lW6@a?!YMy9 zN`r#b|lV8pmS`={@!=L4KzN&N6@e~)jQ?9z~vobuX6fEMRN#j7>a13uI zQ}ca4;XT*SzU4wsD7mL|DDh;IJLJhtgH=sNwr`RN{&M=ap#n=$9*v!>&h@1C+-XhS z$}frIZXmUVjhRU-i^uw``K9meUj_tyDSyFbgDjLOs~y+W?n3KytfaxP<@DLPMmMrd zrY;wcx>-$(0xX(WqKK|@E(P+X6X|l_c!$nK>tY2m^*9zVP5tndle-8upPl_Bhk|I* zH7mTHFHUXh(F$F8(f4PWP69zeQ&~h~7lIvB=HM>emxVC$3#hD20yD?D3vZ}wu075M zr_nTyl8=aihn%A23VE=w!DrbGTz8>Z{)IB7z8d&5U_bl?Fwfw|pR7pGrd^zaz`>x$ z6H+8-Em|_2UdwAjhR$)~P`eg9Ck*~j0rghK=FD=yX_U#1jc1YGK?ZPEARHEi_zay& z9U(EcqbftCKd;(DxAqP?K4g$(olD#PPw3g{?+kPqt_$XYV5&`eIj3so|4PBedOI6D)kqkjqo>gMp2uy-4t zSEOoDxi4j{OMY>BL-`@HBKryU@!e0RxUPv1VJb9N>YlnQ({k>5v9@knF@I<|Tu9W? zyV;4PuZMwqy~mW!$Yi<^J+o22+Kl~*_Ec(rgga&G`Rn$B{#oC4P;>h2e(4Bv?j@V)P%G%WNA&aO%fsLE{1`8ZZ~1 zin!yY+<=1k)diN6CMxfIuVC_I!AeKDz9|Zk!Kwb*>xmwi<0KVNdu$gBIx)+fk1r1!ke&stS#U=YC(m&wOm73Ex1YX?(u+tNbL;nHWWC6L7~JSD>!! z-B$mtgb|Uxk0E%nzcQ`Y&jEzd)pH{%oZgLc4zR|@0S`~AYQok%KQDS+B5X=ZV96jO z2fgZ92)|^q|MS#58hJ7ak*6pq`x6$}#{D^aH&?4ciUlr$MIM&LXnV5!> zF0P;X5}+AJmQnk^9yr z%{^BUWRZ1$3Q1T(J=cTlqbjhBTG|>ks2iFom*(nvANA0fY+xGGp$-iXPbWsrIzGOxZEr7V9yM$*@P7_zTNV>G!CXC<8b7iA7ZYVmUqRxIt9v$(4lMCiCDM;QHve^585(TaU3EH7ys z2UQB*G$Tq&R_|STI-bxU#jFwhf#Pwy?Ku0&#Oo3^VnYWNFKN?#2eJ8<~*`ky{lI}4v4B$+S6 zz9=)zdN-U=tV5cgp9_ot0u9~|JtEGwtu`7jmfU|kjk!~wpe8Qy6I;Vx-T-9YT)Tv5_d}=TkhYL9%N4uau@u4 zc!@woXFVvh;0aFrHdvyDP71Y_4Q`g|&JLl}ttG6TMS62nvB|mREu_@K4c&S}-5oFZ zs!bpfHuGp_l|o2E3p@oCm37a^sMT{9pXqTX5c`+C{ydx~dS0$elOhX)?06a+Q*m%( z63gfqgNWeu0!aC4%Pf*!@{M%7un`jc)ZuOMr`C1B+$vFi;?dUVPo0xl8cl*Fx))`- z>LJBBOf;Ogxgs=dQ$M-TW0S`z->--hRwLHj#gpfvRT~biiqoy?0 zWrUU7>Zn|Sf6S)y+hZ*K9D6*4&kZ~=_)Qf9aabJt@|WKgW0?%Uv{3zgdP{bNGp_mw z$XT4z!>D5GMG5cAoFlFFG`4*b8qI0#!n)|dY#VQ>wBo~+Uv|OCPPI;^(6(;qW(enn zwv}ojEnox2hqbasm*6g(V6qLe26Xa_V$eRARN0tOOQsQmK_m^%OtMC%G!Y=uB<$Mv zLox`Rm?)eiEI23Qzi=YB1c}aL%Zq6F$p4k^WI@$ULW=YAy-(ezM5+UOLUxy;{-leL zv4_$hD9GUB50qR`NAv$ahYh{Vhcz$Psftz^@eq)OpO=6CRjcax?Y*(}*L$xNi$gVPihz>1l8!!!df zHFRtc@jn0g554B+g_0*Gpwzu>?l3+jU(>!|{|GsutroQM~l&5d=MZXg)7m%u~3ZMWxcf1{j!XCy3j?( zxcjBVMb`(hsHpVU_R+w7But3X+@`ZfbI;FR3LBf=Ha3Pe=L#nWD~r+1jso!xuVHy7 zX;1STaiIkv(}P?*ic*VA-1uCcFCEdskTPbB8~WwfoF1K=fHifBIKwdq*=#%L!#G%Uv#6wJ5CsYvwf` ze4I5Ecux?P+iXaA>RqtFp%Rg1n;dlUk+%mB044pOSdnUR!M|y6hijw;-3yn$ad3fl z>pyS&%ZH0{FSsFxm*~O^c*?6CRM?pYGoujAS+gpob;`;_q!w~Kr0Yaz)wSy8db{h2;md z>}xu>C~ShjXvs$f7Bl~*>UBeDOY%uKv5`?V0`+%2?h$G;J2oW}!~^0$p2CYmH3oUN za3SE;sAZ+PBqoMjRcS48zN*a8@=UdWG71I1ChmBAPflA51>sd|?|=)9qQTl8Qekg5 z0$@8MX!E6!ig6VG5_x|*NqqfqMD_(&0Vkkd$J&xg;Dg7a%l^v+r)tE@tp@Oy3zI@q zOA3bf7Bv%5guFE+l;M#!eH1KXQ$(baGW9&Njf--GCql;0{lt`%A>gx3^s*`*QWTU$ zm0b{>>c}fgH`1H1-Pi2Ox9M$47iOx{xSx$3Y!o-df1Oo`!!LPR56qthmvz{d&>c5b zlo2FY*3Ej5tZiEjK19u_d4Q9`#6C6)w&X~Xlc~`Zmmb+I+D=!cght|ehSuf16v4o< z&&l=lwnlrmTuxbQf?m z=NIP4SLHH^HJET1kB=r-DB)QlE5e&oO)qOj&fGxmNq(`j4Gc9>NG4L$n2k+*7DEq$ zm5xKeq72EJMP@aUR1nhA$i6!9_$0Q7V0e_0_J{xY0iu8Yq}do%fXMd9Mc!@gEg9X| z8J}Dr4o(sVhN!5P#(~ms48zWIMUlM#2*EGyKPiN%2ibk5UlD@(S4a+t+dL&&3(hra z{?T3nITME_IqjcTow{hgq*<>w`3j$BkL#3m(Fw7wlNFVXG5F)2xOn=#n#X^J{p9Uq zw5KomL?Pd}k7WVhI$w0V60YW3k=f?`ieeLdXsZM3OUQNqDCH`s z^%0um%dBx3+VRV5eS&r#hrgO;YL${6V7*vZC-6n9$En3W9IV?DPbhS2z4KnvtVCe4NxIyAnU<@+&|Q}*a@8E5-MQvB60v@W8gnTIO1`vj z=8wIpxHA^aOfF=1{%ppMun8*xrLpJo39d-V?4>byY1+FQDH3*izC+&_C=^Jd`@h(G z>!`S%ZC#WE2yO}PK|*i{?hqV;djlZ^2(FC=2n2_qjk{ap)<7c(?hxGFH8=zUc`Lv3 zvwhA!``t6f8{>|5@BV|XuI{yJ6|1Xet(x=uz8PJ;#DiVXqCVmhrkAWDVIBrZC&r4h zF5MIj%NvV*nrmt^Z}@tX&TL!|$+Tai&!Slo98uk8<~-U*ulUwe@}{*h37eXdgwg?l z-iG@^yUag3f^t#BbXTwyQAP9h9j$W$>|Z^s=|i6(cCM zb;J;PO>f2A+j13lp&U|4$w0F7WxQvw!34t$dQK25v;V|u!VNkn=%zM4KvK^O+2sT6 z(0Y}{lodslSb!JXRo3~COxL(@p1L!Uf7PEdJ*lxrTBtQG`V9W0o$`83 zn5_r(*tJind=cJ#;;>siU8)LS32dGy~9=N*Kx6QEm1?PYUA~10Z z&4yxSrJYL3A|_@bvGJwXsB`ETFwtUkAFr3Q&c!a)hjbr+9&up9|EYJg`k41~ywOID2XoJ3q^rU@guL*Dqdorm&q#$UF{mpOGqySsk)8$!u3a1^Xhz zR!vT*S@6zL(Lc+ZP@fJt?WM1lB$vMap+Q~Zh&8h7@MPn4aXt@$VZE&N+@m>n7uL3R z{W{jMZ?uuZDakO=2W=~AniQuzVZgyuq2su4a%c$0T}<<+ zFdEf@%@>4^pV#48-oSgA)^ZCYM;8mSe{kE83wUtys*fE+PxH~OI1=RSf`*pLgB4ph zd9Y$5t?|8dEcrXr@Oey1>{m>V*N3S_=pvGP$Cgn4Sx54s~EPstiPqR54QZQCXC zeZ73hE)^N+mp<~5F_TbH><h$%dmK zOaENp&s_;)e*pQYMm!S-dK^F%2E3_nZ&aOk(s?PT#0a&!8+U~CDa29MRPos|ZJ5V;DO!QiM?Do1GcHJ#ZZ161t2v{KRm-Gti zlY_zn9()G-+=Mlp#&!&mkEc&2KWHEHPAjh2^7|;)bCAzKwi75`$DU^Gx+9kortYc=UnB5i|}THw54@#C+cQlkw#GS?#?X zF;J)aV@;o+`)8@4Sl!u{%M!A5sDC$FuByvxkAnG+NVD$Z1T0L~5^p^r&438`xi za^Q+|$KXv=w_+koJ<`YD z8l|*|QH;KVafpmoce}76ooqe5zR4+lT#pSc(-}1-y?4xaf=gMzDp~Q%hQ5;~qUQuu zLfD?4M8q+^&k)sT&BL5w(IwVye{?EsCbdj6BR*7JwPHMLUX{i3_FYPd_HXi`z8>t< zyDw$sp>LytEmka07U?RCgcBj>(F=Q(KKGJ7UDlN9uidYQwYi68ZI-EmwCP66!@1Au zfHV*BwdqO7Z$vVrh-Z%Dujk=e+}n`8(5BT#QkE>V!U$O1zJ0yb^1-Vm-@^nm7!9V=HXbjSx}FN}o!j}B*TTwESt1k0RrJ+FG*vYQRORu@!QG}< z8`};i4>F{-lQ854Z=*&DKPjy-A7X8-I@Z2sJUAV)ZtkMsc?AjWb2dIV8^Xjj@j7{u z-pCT8mX(iB zaPxZPl{YOEf14Jx;!VzlsRzkolAGn?$+nxhV}CKV52qrjvY8+>*K;xKzi=qX3W9Gt z@q%VDOk>6YDf762Cr(F2G9biDR_9cdji3o@7aU2VJuH4b#e(t^Z4j&BvP)S)!s{Fl zgO%+LvJqcQHGb2mZq``uARB#d(U96vX`cxfAoZP%Uu4Sr6A7yT3G#Rjo`cX>cv=1! zNAH;UJ1@k9<4sp0I3XZ7G_8MtS(sa^BtqX!p}{?kN9|7ye*#)>1b=))&7u5-RW$PP zQrQ%S3_N#~2m_g$jYG*0s;9yuMBcttUldvQv3zY6B}`Pzz;#BzvtE`L&J;$<>~ge8 zKLuS^lqEo(TP7ebigfs)f*+&#iY}axCx2+ZgO~v_)0IdAD3peB_|drVU#xX)4c-f1&%Nxgi|}mzM<3lkBG2VF528NocmZ59rdG86wVWvk*BHg z-#;#pfyt2jRIZ?&5ZKG>n-x^;-lU`!qy)i6kjLZ%hotQu9Hl&1DC=={u5y4pOBv0zBkKi$Ter6sA#ao4@NS@6%;Yg7Zk44 zFTd=bx9#4SRN_{Fq_jSJTU^f1YI3CF{-D9qICPi|h5QSlAXUxcA&1rOq8%jb1#$6u zQBF~@vr6=<_N^YZmvrC|6b64<@=HU)rh=Bm8{$@;DbKWc%#!@f<5)vz`WL~mt2NlO zrQy`oN1(g13(Gz zM?QVIT(Y|wu&M>7xSRy{*i(AXoTtA!3qRUps9QW4@exISyZIfNuT}n>)96ngG*Nd3 z)$2c2VL%r1Z%^y?v}R`v{}9!m$0i4FAi4;>DIy=&0wXSY$h8;2``b;nM(EVz|0iCs)9irg$HF?`Mp2}J05 zSiB8|IXg$5$PiN4Ue1dvT3L}&?UOovplk1xOrFKMVFcxYI0~gx&Eonxw3t1 zmvUx)Kh2@>HnI{n_P7@jYD(rV#J9@qUs6$8?xUxrMpt;3TX{{$rm!2Cn82XzoeIBG z1DExh7CfRF4F~Y-V}kPJr&s(98RPJ0t{ZSEDTi$?u7MZRx)$XQ6PKJTnc%wj%{Z0| zEAsIOeFK5?hP$5M)Y9e_nQ&tlSoGtrcazH zd&xmCIly?dfcl#>od-MDE_QPH1g>JlGQwSF#VdpEimD;!+{l9D{Bdy{U$IxLCL&|T z>#?%I1RuGyw+dKJ_``ACFpOBlfn|RZYo^R29O9~<64HaF8<-RjTaD$W)2L(o!%m@| zuZ>;M`pefuE=s z%@qjA{as3kqtFK$S%L$N`#-U1rw_em8gHbo^ezP0EUZlN9c$D>JzP1Nc zg_{utlCPO{`toa5;PXI6X}aft=oAvA6@G@*i+>0;0;#Hhi2^Wz?FZv$bb3*{hz=#8HI8G*kgaz z(D{>isn`CGjFk&kg6h__6-GWU!}_Kni<1oRFdg0T5b%JynMNo$l!2kP zsIC9a^~B+ZKDfq<`gs_Wj6>FGJ57Fa`);kvo3KrKvSFm5-k%7~L@z4TCPX7wu@sdt zDA9-2987rFjg5Ozh_y_axyR8{*ZaCZ+T8Hq4(ZHW^hJ{2a)WFty9tR32$Q!$dD%|*F0HHr94{CY)3mPZBq$5bwp zeDKgD_Xg&ZVE2T&Ay%ZA%EPVJ1ZXvgS&qkbPA_DEs2hE9DC<0LBXN$FWQ+KU`@>rK zt%BE{$v&^S{aeXbG9&z~2SyS-qur6AKh)+NyzeD{BJAlic{3L>n%Pw96{XU8h(VEl znDLE`e>qIBj(09Kqd=CHOdt3dOhrY%mtrkW>RO%it(_cY`v_)rY}8KvGH*Q{K=R~kz7H#^@XUUv^8z|3_|0Y|MnZ1PZ+!^fXo8vD zYgkQl%>o&CGWqBO*?DAWr-Y^?fxo~+C++k;L)TS(*B#ajEC0C?;YpM_WNhsbddL3R zjqrZRf8Z*uG$|D{Ddm8teLZ{vCLC@lfOSQp`Z6Aw5b!Vf{Sn8eK|NFt`8ZcXe5l>F zsEKw0sIMqG+z#zk{nGRL6~U}CDyE=+a+N;m-m?V+InzF~PW|_I%IwjJ%bS6NIG3r! zh0PR7QVX)!)lgyscYQjuZRq3US|K(^i$jCch27M6g7Q-urgdX!P z&YUkr=T?J?k9f2(;#@SNnx~bxtdRyIxo8E849UbTkfX5a(qc0n6EB=4D)}HEktSJ{ zy52ks3D>mC&noZ;{McY)w-zM~V0!`shy=b+_?0h~KPw!Ar5cJ>O}bL91|GvPUK?WO zkIS>`)t;=*L~|eb;M>n|4=Kv4y~)m=)STe6UgQzMdc|5yFcCcx7mZr+!6lZ8$SKx! zFzeRT92$^f2X@VgB6#I&+4^8|PF;!WN^HSR$a7Y%pLg-82}6qR^&(45VvUX#x7Ob%M@N|LKt1@$fNgJsFJsv3q*tOydUEyemv~6Ht=5(KcDSk_u=ZVEg2vEO7d>dotA{H+0$oGI3<#Sq^S{34 zUV?-HU|bjY4%;yegBz~$N_>D~$~uC>jDVRg zBW0c3d9W;gkcY+6N7w!HbbAk`xvzN*hL+bZ-n2EdZLIcdrZ*`muUjh8M?VFNHMP_A1imSUDk$!n&^}dKH+$GK4S~5!C57Fxpw>w>3Ri*ox zC%q!A;?5_-4=@)pHs{HczIV_fA14^&EM|-3jC(`Imn9MmgN^}L%y1&?^3T#=$Io5V z)UJqRdZbOCTzO_cP1EBc*E_1AcEbqpU>TO#_QxV;xucd9@xobeBF0K6m{+yhw$&VK zSu6BS=2&{>FC_E`(Ss5%weI~eEa5vc;6IlSBo#lN~2~PHtawsY51! z!{@OG7@X=R>^zgU2*uuqHYoZxvm8GHFB9u~i$H7dAbz?OhHC8kGB@@Z%4#BmY~+KH z(Qt8L% zN={3c0T=n~bW^ZiW*$eVD*lw*e|h!E@w3@jXUV#h98&keSh<-QfyNEwk?DPO;s<8T zhUz~Nh-W{Ou39mdFw?U`GvrlnWyKmn>-s&)PeUh?R~yPF+^ohVia09o!}Yz)Qzj4= z@T&UyUTqS|g+!7U*him93~}Tko3TC*srI8`LJf&S4W0AN?$5y|kj=H&JKC*8B?r@C zulB?y-RMZCoxZlsvu=XiJY~R2a`+(v@N^_BsM$pw)h~?s(4_f^RjU`!=0XH=pi)w% zTG$E?<9=zIi+|J#0QSS`_^tr9D{Cvv!B34Nz362Y6cKQ^LQ$(t`k@avtBa7NYMH*M zJ}k>d?v9weZm<1XO^f;>2ZQ(7scvOpD)9{MtB^SucL(H4IBNt)hu>g$r>}(Wurul3#vT8HQjiq`3Ic$ zzgI6%BeEWihc6lxLzfLT+E_Hzuec@Bq)!F%oAtwicpU$e8;K^0DTskOyCGb4w}dyK zC`d+sOJro>+v6no^*g#gV$+z>#|B%Rg>12QeB9A8S|G)ST{hlgA3-~G0a;V9HX0XR6}C9jS=9YhA zAEV#|#M!xzvD@Ys)`U1C9oEcj6h>A*&x81_9Ki%0M4G1wS|a+sSUu$2a52ZWHdt`P zpCZ;TWjcge6m6MKxlVS;yROB5!^yQ(OeI@?(;2ZGxb(=;zlyrpwln9_x-6%kTjhOj zjUMLtkk@hlEK|5${1Mc;0WB>}pw`i0BLM;q7f?<}LHFjeEcPONG_I+lsG^~!Ljk8% zL*2*H)a7?veUwDWjv3R*8JD+k67V`(Ud5K;sg8=1sisRps^;k@8_lmW(guzqUD;pj zeS?k@gYlx>K@x3xZY7iv1v~HjU_v5S@SLI)%jZMGl!A`5)E!GlTgP*V#XoRKB@#(a zp4UTYt_&F^q=}?z>-Yo@g=Y#sJXiAE-AyvJw1mi9Oh`2zT9}${i8~#(S%54`VYk7` zk9$0l>zQ(;ZUcE(tCQnjLX9yBEqst1cwbZV{~)~fQnD0+;M;kSvYSrL$-rvl-G*1~ zn>D7!$NHR08Z>tsc2ZTZddVi`F8LodU>!?_vM~tx3PTbiCLOip=E5wRGAJ8D^D$pw zKdTS)z2^e#X2dbtfqa;5stL`(d#>Wb{AtyR2|bIWhw}^UGuuR#o;dn?nJ}?#?X;Xu z7VKt^YgWyc);HCqkQrByjB`$g%_XBog~)BkCY*3z*!K97^bO0OdX_~_7u2OIWnAv( zMRzGo*ZUEU56_x@tmdrd>}qRfbH^qb?jg%-dtzsc=UImg>oOg6Z89`0Y~0%{Hj~xY zvWu3(kQji{n!Q=)_cWljpfAIwPjaWnGaVA9Co1BSZ~YLv_onWvmIklfEUjG4_=p@* zFuCo1q4Qe?yab`}4an$#ccQ#~C8>TQ*w6xMWkkJJoLiVR&`lN+tizE=Zaa{%#eaZ+ zMY5)D=e|et{Oe!n;(sk?3IN#BtbZ54eq~B<##db9?coMQqkm(+ME{CTffppgb7GEI zY1HuKOx3-@@FNv^GdiX8kfcDrIT|r@Xyh7In6sg#L;PS=+QrvZ_Qhs~bQ(1$rf+Eb zHeSoTcz9H6YYADp(GhA7T|zx27*H2kbgurU+~As%If}wW#NhaZUjohoD4mLfwVtD^ z;(`H@Kx1{lQ{>0^MI!+BVVwFy0JRp);VV$wZmjA1u$1X#sS_ZaR0NdN(dFDsFB>L^ zNC~A(AeCL-=^^86^rkGcMXx}ebFS)2^7$22>4HbCEb9k%Jc%^ z7oa1!r>f{^!tqSt>HuB*42cKJkT_{3S$cF&T&HxpZ(r|A?n9vWy91}2fJA0gX3L`z zIv;>>|4V7+Ur;Z`y51*r8HpHhCMwc%S8}#3&<7rV@u5uv0}R6GHW8^HL3h*m)yQZV zZzAqgZR7Bl11zN2nFq{rhl^u@i#P5wkO}VKRNbHIbj~`HMqOW6R#al zR#g<`j|D4f?S7dD8;21Jh84Amk}CFk1xBu0#*D-U)IaF4^)=9-^$G}?*~Z0)LLElf z(qfv^6jBUo4ukJlN5G5v7F;wt%8Ea=drMOG^skb$VDrcHB*?e13CF+KhbiTK*xanS zxNM^&{=S!XlOXqCg+>)&#gYN<`1r`vVYNF)PxWAJm*#lr`2g3pWB+d@O%sAH2&8KjValJUAnT!g?aF1hK@ir_sbb_cm0m=&anm4^@vXL zb@H^h3p@$@(>7X~q$gwxW2DE}IB17$^QL}iP^;X6f*|>V__mlXGR3s3C%y<|5S6!j zs{3q$@NuW?qQauuMbzZM=$fWgOl%VjT15QS1x%C&X}XC0PS9HGDa-!nyQQEH(Wce% z%MS4u^rze=5x#^Wk=xi7>vpa_Q86yUhX7zMD_Z;t&f5=iH`wwu`0DW(F-7iRjgrTf zrO3I`>ODG^f<0jgZSm5L-YSFy>X{uRZ{o?{LngmU{^q#p6Tg7a;fLHj=0lmxuqDqp zwl;=y1z-uktE0MW9~3Go#Ji?swLt-oI#+= z_=2WA*6#)zjRQUNq&Q zSP8IJ!x={1km9}-A%8Q@KQb4JC`I6}O~m9vxWsJ?8q*R5xz8$bWvWGHX9pxZt&O&e zDYhfo&Y{X#T0xnb63{L4Gx_(D+PBTSKEm}>moyg7hY&YX!rGjiyBWHtCKvQrq#E-c zUh+OlL~wA7X~0O=q4TrI36nRD36IY|X&j;!eh88i$)%2HlF*Ws*WwHSA}v8~7mklO zGOFg?Sx?ftJG$|;&B~8%T||_~a@O-oIjc)$Bg{1THWVH}6fYTo(&@!*EC=9hQ0gVLzOVZL-^t7*o zyNVt5JhO!=Jk_-#XxbRx0VI@@|3k*oY7ZkfI(D%8%ka~IwwMu;gSPgqg2IfnN)^l) zqDr~1m%u7^M9wuxMG7DA_KFNG%_(+FVNk)fu@f=1U0d^XUCjOXoz}Sh8=kbmx4K?K zrGBQ_H&8D0kE{ZFpG=XWw~ki;pdM$qxf#60nl!aFA#8}H9u(D4U7&ZQgQ%%E*Taq4 zX6;V4+7QzyWM937hmMC|6$O#$0k{?ot7R5_44t?yS%Ouks!?9u2nKa8oCtSI%Ai{I zUCB}Iw%22cNXzO?NYJ(DV@9o5x*^K)kvmap5{?=Kq3uy_X>`z)TT?u>v1NN&hCJ-p z^9BLpi6E;nJg2QCNP>jpnbfDKf|2$W!&f-;!B8(SU$}uYA!s>~jPyY=FW#MWZ*%)z zo)B)fawasGy7~zbIE`wzX=o_%(47pulFQ)hmdt*-KqpKw?85p93+qk zUVQqMd~Jx*ohx3XkjlS3Tm1Eu@#j0g zP;BD5@g@O%G#>(M^DXV{342vBpMBISe^sG_R% zy$FHP&`{^vtfHyq+8Zk*nE`RM4yt}zR~yiZOJ*f5 zii;0oE(qe;p9u%Uiz7_4{Oi%IT`7{8?yy@YYMs+Zc);bDHZcQ4UXRdoO`z_zB8tmi2Q5Rv2WFJY=8z)p29X(D~$@_FZjqqEy{)KnDA1V5Wt^A^b zJmdnj_g`k)V#^-B?5XQSS^e^m&tll2Od47q(d^a^#?pX8i=;HTj~`9&%Jib3A^DVf zkR2%KsTfSSXb-%LwxxL8Frij8J}sD{#}@wx^l{?lTO_yV*e0Rx79?^bIz?vrEj{Ch zV`b(oi_7Z;UAa`07_?N1pJtmFyo(D)HFz=oCaRsHk)5@CY8oS#1i63SsyH`D6q*n- zu^FCc$AM&LiGu)cb3{6FlGiQNG@t;d)OILcgPzR~3e#~`2Jw8%^@>R08+MZ4QXi^N z3kuW!CVwek{zQV?ruGFWr73-NynhOfer+WKrKZ%wg0;67QGgiPSl$SnlV4aRxT$Sv zDD4%eaq*4w0?SV~+m3uaf#<7G0Qq{#*>@f@z0YHdjAiHCISI)V(dwOaoU&vo$Fc#Z zYd(MjcKvfFG*M^z6;s+C`lBHcjvUiL>$U=4ZoZO;W&>(mY}P~^4ah9 zph)*(6a2$es72rfC6FehbhZkv5gW4@f#O(~&b)+rK^Vqb)uChQmyv!@QtCB2$dp$S z@9!&1ZOrEBe!Q~YMsiUyV0mHd&6B4pD=*#NugCZ__G8;unD{DlYB0j<;{$9spt(5egz9{Lqu?!5e{NZXsM$j}dF(rsaXXp z*RfDD8|eezR!Q1VAXJogw%J)qyjgw5-J2d&?YsUZvy@v69_~caUNY38lEMVG8s9Dq zeOl6Ko-`bscdI!{l?H_KuO#ptEpI@&&g;y3ta#&mjpgb+s#BsX_cc%-1Fmb)+Kke~ zhtvK+3ANvO>{?nDcMVm1f|lJZ!n@F*`PPQ7P-moet`)_%$TINOwCSb@w#F&2=n1fh zbY!0E3uAi3NhdZQVuRB=x_2oJ!_Db)v5wWpt@Ed3&;-?U%S&rCUOy`a$m5DIH66J6 zI}1;KjHIiU{OnSG1|iRqVI677Qs!MAvq!mJZx$?qq@~z7McsVe4H>B-W+=jm!u_1& z4Zd+f^6GF*M{j~o%xblH56dd*T(D|eby?5(WE`^{LC$l-^vu(upcGQQwIrB$e*zI|zJ-J7U>lN1vvSY7TfdUR z$wVew#wFt79SYP0d1H;D$jZlWl|y5OZ4=GehEBs8N?WrBdQKdk{ zvCP4jt+nQMB_rpe(gavJlVI4aC0(wIe)ek2kf)--6=6*G>6m`!it_hucz^NqG`xwn zG`36XR!3`6R_gjwDt1rcpl7H%>#%I#$JWlr=>6{(Ro?55Dgg>-L=L0lqnzhs+Uklt z83$_G^&&^|;SVZQa%Jp3VmguAZ*jGA7pZBG2}v*yApEzJTfzy?kyX&^ zl2$k+HIPS0Y*?{vG!kPAo$Fs`l`qbK_<_47{MGKa1VmwgA!=skbpjYtY)8vAiJF9wR6>|kDFNXMm;qedTwje^bc!t+#MFwt` z`y`*cn^YxJ<2OO?Yk(Ym3Mzgoh%FuU6D`WLokNXajFC9E_YSE6Id}njw$zLgeJI>W zS~N^?>K@OfB!r4a;uZWJsd8;$;-R3O?zxDZV9y z(!iXz0Zfnpu9Ngo_CN70{S_ZTPLA@ctJ&DJDfppPo@~eePWN%(Cz^ryw_+)inC5}T z15a0V-8J>x)=JC_+~{or2uJ884t3CBFVWGnz7w<)AklyV6-uEBG=RH_0MHkEoNEJ! zse)bt)9f;hJa^s>j)vC(ILTB zrr1_o@a*AsZ2P>o%gy&C^Y=X^_nZ5ti-5N&Xho26GT?G{@5>p$DP(H@r@F>VEdAPA zt&93D4KIS0AEda|4P*A&4OxOi>3k8a<>{^ym=53^UaY$hpA9G?Eohzv!8NE?MKoZ? zgktv$_8OK>8QN07Sou4SNinVv6_hNf8^L ze!7U}@qjX8hh@sx%GwdjwUq4&!2!c0VxB9YlF0`ITIN3;61@V4ge5x-pd~lF|8m0A zAwvWKlHjmXMGX;E@Da^1eU77y>e>3VocigI;5zBM`ReBCKJh7I_k0C|J@kp}$CjK+ zpIb-ooXkzMT$Q_6FUk!y?;NjJUYR)TIJyX~&u~ILBraZB3=b$>4M|^y{>XNILk6-B zUJPTeRSAuX1)AI26MwA)eC}39^clF~bI~FZa%Im+FRHtu)=|-CqAJ0O!DaZbl|@uj zxP<1|ldgb|aiBypt{`@kp9pnCa}1q5eaENA7v7bh`ca@yq_;h_&OM{MF2iu3I5PJU z&};9Rx3^M2=S3-BQ&t7aKlPBic)7DWJnDG{^p#5USp==8*4eM#op7Fd2{()AakV}? zjoI@b4K}fAU0-^8D=pR!G<&9WMtSkq+FEekq0pIKk@KUH8OQ6g%x|Ja2=B!8uYkDo=z!d%Rrq z`@bK&uejmE`q2dqJ#iDJvdJ7k%#E_(kxeSRHEm!rlGxbfTB*qRi4gx2L6#zcLgUO` zbXMi`^Ue(488(#RZYlE+vQq5*PRqU$&Q zKz|Cqe)$$?#B-UcLP6iaq za#&%lZPnjPzFVFfXKrnkQeFQ#?(K#3IcVzoJy^%QPf6u+*FiK9(A&GDRNQ)Z1AEV8 z4`}V~BmP7PD!6sg_tsw|;K>|nd82aM!toP91h^&ARMar;4L@EZM(Mqco%}4v-E`w4 z-i*}4DSdCl#V5QRqFX$PM0SkDt&8t^ro^wAbo$FK-k-}ny0HfRm`c1iHn@L%hjTx) z?~^ZVd+v8nXZc&sGEr-#p9mcOdzL}Eb+O22ig&MDp78td0>3`+OBxUC z9qcrY9CLSaEt0ufE^7T6z1k~Q<#0%_c zBPA-izyq&RpB|SKkeI@zjV{|2=jrddh6bi#(8+d$tXF5aHothe}U;rtL0o2PFd-_db}a#epnSt?bI2>CL8Q@91B z!Lup8*A*d)1o>#L4Z&M~q!G z5n1%3P*IzaXp}aJEW&oPVD1)RPJLJ?BO5+*ScQ867V4MbdXZb_b^Q%EM9TKf#Qj?w znA(p@LBXCgAB|rIiVZ#St7+P*jFV&h*~-NmXIHUn9}TMePAV%XWyyUcSBt+U&JSS} zz?3if|jRv%g zI&Lxnd)2Q32)pD~b8z1m^fXIc7CUIR2GGmsjN}4lcDk1Iw?ljYQz=A969MSu zFAI;lU|vTwQV1M0 zKM^W<_<>3P%UZg5UNbOx1fHE-ygmoV{Q5>L$^S6=rUK3{bmgy!_zk$b1_bOreSOOh z^gWL`W8znQ`pkJYR%0KFQnbZp1>!R| z1+kWS1H=M6h0p=!|w1oV3FUsrXeDJ;i3x=iS^Mu%5hynh9bm$+IKiWw|{=d9YF4D2>N41Yts0oqV z-?eJL>_OqBmc`wW-;T;%QR8X%(AE9gn<9f6ZbG}bRfV6d`w^hNOG%Ll*>4btey93+ z;jIh1m(chYbBCidwH_ortLm&aMlifc;6j*G3_$~t_mI$9Qh&$zNQG)(bu%_HzAf9b zmVY!i7bbsG)q?_-JMCDb!=(D?31`K^GAQ6Vo5!KjD=W(nSB@mhUs?9Zi1jhu^E!A9 z@!oo`bQfEER`p(S$LI4mnb!-NKZcE@MSmi+ka#+3oC$anoVQj0ro7WDQ)u_jXTfV( z_^)&1uabB9E|m+1yLQ>L@Bcan|Mvde?66B^aPwSa?(-&qlxtdVqA%%Du4SA{-e`Tg%>{& z9M8N?{^}{iU(K`z|E;5cYo_E*?1YN;-~aBve_db#{ChC}d+z?fTFHN#s{aj^89PW& zi4E~cJ=ceP^u6^g_fLf4dL>D-s3XX#p_YRun8B%+HjHb{VwG;aTlt}Bv5K`TQdu8%q8PC`8Q9*f`>0~)b|}j z!mDO~v?}eAWiv-Y8hX@Bp^??&0<5O-E_mYC=_4Pzjw~E$>G0NsFzq|MyN$fGNA?wr zYK;_~cfG453K+TXY?mMqm`AGm)L(}%vUastOB>=PMmf-t{ z-e^bRUiJ8BGqhJkNkvv-z?m!DjE-rhlB9w`-7 z%0fhkS~Y`{-eLA5ZU1im-!}&sYyTcO|6(HkpKx=&PFOM@^035X14*u9Y8&r{bTE%B z$os4*m4zEX(#sl)EZQjv24tRv5ObzpXXHNvuqN6xPP z!3d?5Z`a^vhf$2(f0^vO+}i+xBpoZSxQNuU0ef~vn=DFQU23WiLp33eOu-eld*gBU zU88$>Lc=4-TTx$qj$412_dX|ekZVu*_fjdp)}lVm_D-5F$$a9EGF8!H)SiF-Cd{5= zr1+1LH(@kq$+7+df5|vg{g2X?HCMWM-F}a;xkEJXk8)05=99zx{wl z962j$PCht?R?7f=>hu)B|zbM0inA3j}*Zm(= zSr2nTR`bYcIW<;7@dTWGd&cQ)z8R+2;@@A6(oB(T1}t%@54)SBX{$MW*3;K>C{KX3 z0@*>6Rq$h#Pp_J<`-I|+@#Is#G2|E&v0+O5&bGeG-FxMk3EFW?7?e-z2; z+Gd)4pyglj*9Qc1DWDX=M2#tp0TnLsX9BvqE2u~|ZVR~H?Pb(0fBIpv@_w}9c-fCN zUZf=;H+;;7^?QAY29Na90<_lJeK671oQkJd_eN)24)erBybFYQXZKx^JGpcfNAt(^ zFCghS{p9mVXaQ_&fnnTDch~CrHp5)KnfEnfutS=?pN#h;)cFZ--Z-3ujKl3gcx|ww zQ@6k-a;=`5kYWFTYsR!&R&iE&p&Qb~Bxlk__&PsWdF9(&brYv%l!?7e^4`Q^!P?cei!pU)RwY8YsD zcqHiin2?mU9P)bVYP&tiM$c87*Fzy5eO`p8LCft!lm)BtQT#c_FVtcq(`^Iu_$@9J zvu)pi=@CW$*Q|KhVg(DMZ-A9|wx{YyM5svxyqxf1rdU1w&i)l)UHQj~-(LS_vO#Cf zi`vtYL$X4B8wd~TJvah%R_U29$yUPiZ{!nA(i{F3t8DYq=V6oD98f9luMLxFM)z10lok|oA zT@t*^103_&$e0*(Sna1YX}?R=T?GvG&uaJ>_^R$MYQyzzECVdou4Y!W&^$o+OuF|k zac~4Yl25SOwcByR3Gau1r&P~09$iTlDoiLZK8Ofk^(bnV59fk)dI4nF>4G79CQI`d zpu!%AMI&ECRMH|-Xt`69f=|K12X^-jU&%HteWKdX+8P}{eL{;#6FdVkyO&-`h#4o( z7Cg${57vB{WH_6CrAX^eGK%vu7gJ{@*N6}Gq$P3L@(P}1kqZ9|soEueQhcjj50ihM z^oT(sSdS3PAP5t`F5j%=R2G3}UfjfEC*;DR2%#`s4Wm&{wlsrK_x@GISBxT4pNi*( z`3jMzMo{P73|?a5)0>lE@X50p1qqe=s@ek*qUHk`Zsa-4E{;`}(m8il;JF{6S(GCc z7N8cK@%&)`9;tU%x7;ttUb`99lz6B!9mHcn2SBvFToNVYX8;Hq8R(!NUEdlmtI|Gg zEoo#;*K>6(Fr3vW*^}Pjz`G{E$fgo@72$nt?g8vCbmqQ^{6(Lp&vk`y%C$ug0Jk-w zEJ?S)6Z7(sGUkOLr}lR>%CQHsp&|~i;#L!g?(1@bbjhckGkKd|sjKB}cWozu`-#_I zo+cmlLICIcqXJr^D5VpTb;cDfMq$`cUT)(#h|ohjn!@w&OTlH82X)eEYK;DG86LPv zx}=a*?44ves&Q7}5wO*ERobRo^wWC*0m$uh>dOGZE*6Q4*gB$Vk4`yxaW7O-lJVHa z+-}E2@UGcg;v)bfl&qjOD=?Uw^tcC6V=i77@<&12kPQ>M?p%fmhM@*X|Eyk0s=s@a zS-n;wG*d~D_a{3>4fZ_;^HdJ zd1Cqa+~ZvEqNB2Ahj3AU4&u7p9@j*^E$O~dz@%a)gVoG{U2xJRL#3&W5Ct6ZP=eTH zbuA^hn3p@jMO91A=T%=^5nEAF#Pn_coSO>$-pjkI(1!54jTB>zHj{iMj$6?E2F0IY4n9Pk*6susTV<&((TW5+h zKe1c-9O#rGpF*nTGJGJLG#^fE**7^xHPe2@df2EggMikUN*e@L8wQeS3qsEAc!EC+ zaPaxbrFdWbn{|_3+GvCQLx45D=~>B0aeoe|@DqWy*qbz9&~8`Y z8{+U1iWRqZ?OuIN$j`v`hL-1tS62_6xAeQ$oL9%_Usum+;?KrPcI{B4saqPl;m_Wh zv)NAN^%WaT)x#tY>Bb?<^b4)-Ei4ZL}cd-wi2KMEc}8OR2Y(>(qJPig%^3i4?y*Y^gpG zO8g6*y*(2c{Q0BS@qv<_EKVU99oX+ovVcT$5so-7HJ`^r6APMQtsCL3zq)6=a6P(~ z=Tj45G8r;y8*)m70g8F|P3B$>Y4!o}AfK4>dC`(uGIwgSjC(0=A|QpqN$!qs4ldCS z*Y~DjuyczZF-Us!F>rM9EN^-uD(nrBxGCHzli{3rPu;y{j8BJ`_bl-sq**C*)k)46 zuD4SxJF1Xl0_azk50q$S&v+ftd{maFU{p6j3_QkvpEdE$^aAn%(O6cvfpbQ%$GW_4 zX2I*g%zD9;nZp+LM(8^u>W}i;Ok}m0#+0Qw2KH%Fw8Q_H;Gq-lK&uutKD}?D z_n^~eS44LiDKuQR^f5RUQ76=BX=8Va+s~N2oNmFv8ml&+{EY%tZEd~fG7seKN8{Jo ziEqI+kgj9**eJm1Q(-~)VTHtpmaiuKyYnD6ZT@IjYjiqRRhT=yCk)bkc$VXlbP!duAI ztw~5c28*mK{}F^l=e6;C9+#HU$%vpx_g!7uyShOGX& zmx!u5YE1KIeR@&(?eZY+O;`UAJgko$=WVBWi3eFn;ELZyBt=ss8jZU=9A3o~boA?<45?spbppq={sA)j?Ido@TL3 zN?vSJB4MlBOV*8UZ>71H??$d_1JB=kFiuCt{pl~zH2iNKiR-~9>Xhl8oeVO54wMlp zqCNU}qlPC`p(130tJlG$8^8=9H_*K86)d;)N}X;Q68o{=AHjoTV+DlujLfy_vg>Bw zd`X!4?ffuOc?NgwM?W^ns$)P?ruGbxh)PW@JDLjbJ3v=0x(N#zS;ia5^!`^iz_?H`r(OF zhlo#b710ZMAxiGv4z&cYXE9eDWqhTtKH6C+pMem;5L!!GyzQtGL;4X}QcvN<>a3lm zK{NS#{O~PhwZB1h2Ob z(2}uh9M-iU?zbsyP10>_lSsjE-P)&l{3il`q4ql&irIT<)Qk37EfXlVPFSNUi- zZ0~>c+};_`jc#3%Uz~>%3*5`AZcZNJO?op20ar*D)wk#Xv0=Zi?Cdh`$S+5`7@6p4$TE26hIgFbgMOH!>9vLEs~rzGnnJSW+ zQFc;kuOPE^NS%`iDk;Ij!OvdY+Pnhwea*dU*1_Q$lA>JgZsHRw$WHf_Y14x0WPaJs zw^(-AC^$5`S=tVJ?&auq02iY1{ytYeoy8BfueJS^(~BG-Z@k_%S`WlbB)*@et~EPW zI@+_YM)wBN?BW_iEv(g#Ip#049VL` zY7BV}Jhk*@W$#}vPwz($$bz8*U?Z`oHv^jjjl@~IwB#9^v{pW!*V}5+hv@!8(el5m ziTy_VqFuk zjeCc6IJ*xFFrnhCg!TIPJnjDG5Vz%dF|O?Fq6~4T%4;f9fGkaOZ=u#EC6>^5?D9fT zudcwbevV2)adKFgI)m>C0+m*^uMxI5?QO9&8SWEmK$-X4SNdwssQqy4ReEU9?Wz|I zZSpJ(l5M)Mk8Q9;#lXbs-^Xl%vnM(oPKJ>*f(cZQLk2sMw_ z<9AvaqFnkJ^wX|319+gP{2Eew9XM@;Khf^itn`tyBEB>MDD}?}d+v&K@4vnD2U|K< z_oJ$VrNkfIF+-=*R;ODX+9#_Aw%Q|#Og`DGZFon*ZUE#^n!3IeBjbIr@$liq=x%X$$72V7T zV1!t6ctGoYVf$nE*R>j0^?e)T`B34VwMxAGGRzIxVT|#p@JckoU+jM<-QKsDvC1OP zT9{Ds((N78_qb_v^6dqros<990S#~FmM?fkUZ)bZjC#(V$1&-+-ZPX) zl1C!8Tpbw}?I{|lsOGy+ph|7ZSQUytkYn@8f++p&1_R2DxtOwedG74@R@cR#R@Kbc zcdf1NcEmLhQRk%M9|}fzM0D;ult`AgEcid+xZ{&hM&(5NNEW^!rnT3D$Vvyv6~V8| zT5V2cV@PvBlv7J?si==(blOe{Mi+hJm;!qAsYyF{^AOywh&nAoL&$SGaCm-Y^al>M zkmr?|cLw-|J3-2w^h4@U_EYCs`F4?onovlRi3S=SYlZcJcQ`n+L`S_XVvY7}s9oJ< z2n!wzF2>6!oH55Zfr2WgP6C~-Z&%5Encrobl&?{VS7d9mwwY{d=$C4181X@x(0$GN z0)_iG&Jp$6Xklin6OY6?+~?&ww=l||-IIB1gYBMLs{~t?^0U`YBW{wChE4T#B}9^Q zful0!6;L7wtJ-12ub#0BnZ9_wA7p5k@pn~+e-f*CPyTGJGFkaoXH4eNKXr?Ca({{$ z39B?ung1(V#ea~z<*)i%{U?OyResk&#+kiNV@_wY;$wK}Y2!~n$b*)&FL3GhSL;Fd zO|ALMLS!EB!`(td5Rr2;ZdhmiTs;;sZW<->nAtdFK{;vL?C$Ih?5f&y)D)s^^lAhIbX3K&aPNi zz`F4ki!VE-xtiQZ37YNS#EasuM(7bxYXGN}6;Gvs4_+Ns*odnyEhZzlRs=%4cSF?uavKW4Aor8UD;d91*eF zqHWuABjrso-4hSrkegX?=w%aVAO_xFHGS=Av2}E!NYz>0b;vm7NV`@pIC<#qK=Rd* za(qYmFf@qwg*85_pY75p#auy9{LokPoxowkAQ#GK?(8zw(Ld(AH%115Y##%(z@eMj zM>a-`zn902WMJQSPY)_e6uWW<3HFQ{w!DbYP$(tpHNpga^W}aI`G}u*l2nzAyELSA zL?UXW8iPEZjb=Z0SKGM~9NCy}bDJ*VSx0KVY0RX{Uc;OUcof62_rk!E9lJcKKkVr! z>IeqqKfb8G00+qZ^vqY`OL5;gcC~P*iMhN~N2HjZIZ%&3H48_%0MG=#uJD26y5T0eil|sfkQ*SgE!SWIn|8@_F+{tmRijC z+!?VPat|S}!L6ox?qdu{ltwsR3-Hn6>$MQUmh@#uR)8iE6}l#o6)j*BxzGoos;W|Q zi0bQY$mi+zu9ljw#MS|F3isAlv*K^+es2077Lxy$CDngRPJAqPdihS36gB(DEh&jI z|EA)zGz;jC&(2=XG|}`1Qq}N%HmlQg_cxcV2oCu}iN|!S%PbOXA{XSu-(jex__~kU z&XkvcxzyoWv+)8;hFMp(K#ePLS>jy3k=F-gWq0k(ZxK``ziRFga}Er*NH3}L0NX%5 zGS+YaP@AY);Jy~3-&EY|@Jsf&lKz`*poomUop&P!1GmEe0%9RT#Ir{lB{s@P$oqWd zr%l?mtAlhbd|UTT=iXI-ej-ig!27L*dep(}#czegVk@W2CiC=j18d0)YHB6|@`uwe z&{ikR$BjO(bTtj^xBIc9a}lt$P<$I19PqYf-?vdKT{QN^4!6U~)0V7t_^Ow%toV-sHk)YXWci2ppZyqIS@5fGsN z*|n2prG#nZUNC`$J9TY>-k;WLQAM7#kAOYxhS2`NYbe1F7G+U4s&*JN#2()|Q}dhY z*BzbFP|@Aamw$1!rg@l6;~^i>G*x$Ua#E05Xkxad{-Rsw;(Gs9pz-I=E}x22a+>+- zishS51^1gDg{quh*Uo^A9W5dVfK^sd5%d+O8hhue+EB3x$(*?oB~X1Vg1B(4+M~*= ztg6~~HD`?SzDvA3SZQy**IjK$jJ=@~%?Zvezi?wWgZR<4{07V$K6T{$`T=s~eT3Nr zFg<0=cie0Xft6Bu@a?C2tn*s*8HQ@fTn%40Cr{2fu{DgC4&BiBekCd(f;h^zam1m} zCornXS9>v3BNw`GB3Vn>n%~3kz^X-pFq!eU-h#nudZvEtc3|F*;ybd zh!G&HOpa{P0}Wru;{*Vk7L2N=R>UL10Ro!#r!%w($_nNiFn_fq{7 z$)*G*leQA{pYBd)kw z-k~l~9k~UhtFB(__ZSLp9HzT;$60B12FJc^zVOP)6XUC7!u^`&L_CB>-g1}Cxs{~2 zr^fQEGd(tnFPn-h7V!evMxuAMM~PH_-2AoOl`0_DK>C)+wHRtNmnilMvr$!7Om6DqfnCg-p*a1(z&UYpL zhFF^sHn@ie(Jm0U+84W#FyyXT(k{%)aPlILe;Vd@sB}CWfsmRGBsNW)Gb<|sT(xUi z^tW#fT-m5I^~()?(X4TUvT%*sntI(W9+^3BZf+_lPr^+e_0OP0Z;JGiX@$%cncLCY z&{O>%6D_}c#z+Tfa2wH=tIXf$*j(9pdM{Q_?dG{rWg@3ryO)SM=EnB^eiepK(;^S| z^18QQNZ8P(a)FxAPHMu`t*5|Qu}f>r!W~P%x*EO_VC{}vm=8{SG^sk(t2_}SgyK+} z`@+5PY&2ucP4a2e3SuMJF*xK+?T&x{flXNaqea8vs5N9_@$qMyw;!`LiUy`=K6IUO zYMldOH3K$fCyb3yVCWxvx`EkU?dIq%vu_ME)H2~WG+(n@=EV=b92TaWw%cRq-J)Xt z#X6g9q1{FB=N_oFo*kUFugPv`!e8P328u$P(2I*+^o0+cb+?^bQTMKttJGo;4f(_o zy;N)CelC2e1oY4@Sh;m#_C$v^)hTj|(Rx(-jiCx%h z(WOGh(6y3iuez(C4d$);m2r9O$W#9+esKz3y?_^BvAZfKFW>VGOKDA3`GgGxX3mpB zKhJ|p)JRUuW4D*c~Te>Qt=B)8GkP z4W0U5H$ZSjOhkIqTb+{XT@Qx1R`r1_z>6gfy{YLzs(Uq|%Th$nGOULepL&5=HJVOJ zE-szfjD9uCGLNO6TBwuK0`oC%v~cv#7Y;$5B_ivV!%*@!5K4ld_2wwRxDjdD+iA}S z)CZ?Rl9(__medg=kCKVG%(qa?_M+o`T=F#!`i2t~lFe$_XSSBE1vMJ7OX|GK6DLx6 zYh5Brda0xWuHDt_Fv8Bm^AsFwW;uypnnO?x5})y56Y>0O)V_zo;L_b6DfL=?de=8)S@$|OFSyN{XApAkweSrpy+EEXBZxqp4?dY(9G}SCs)`1K-v)1ug*&%FO0XB{G?%yQT z1fv4h<2t&og(EMl{E(`evR-IfOxh1O>v6KzW}h30z|F+7qc( zR@I4nB#nxajx?3U@6&`j`+{AsYZx!H`$C=_HMsihOqdeKt!6pcL!t9SGYVoq$~uI# zNfbZMP#^`ZfmzvX>OdRvBl5K}<p8 z5WOps`-%29hq#MOhF`8cVx#$c)@=XMELS*-oT{jrEs3J+vIo~Ik8W%3@%F1uYS%xP zu3PbElm{?iRyfucgM=P?m2E%#5;z6%x3rmY)ISr3+IWel;_KGqI=9OiYMyYeo8$*D z@1+wM`fPlPK?WroWEF5o)8wVzZOITGm7__JFv?|n*-Ah%_`GzNf;fvn|FBX?X}hC+ zDJ*2f{nM1)j)sx7&4n}(wp?AVQ9Y>;DZ?THN^Ip*(U#`xy?W>+YN32`@s#~eghGJh zDlzo)a_ui?k_ore{=L(wOKJx3AF7shu|s_Jwq+9ktOqs&F_wJuzPYP0hM z=s2L`)886z#(Ibie#yTSwAL~dN-29~p)_P;V_>3Q|qMLX(_9Oz-yX2g^ACn zL|Dy(D{iEmx#PHp4O1bZ7@&xR#+4>S z;YVeaA2lMn(M>@GN%nWewe%6#TO6&21s=s|?+@Cqc()sQ=gbDxl|GOl;n5LZG-C|& z%Iw#P9WH3q&^mw-(|1jpquaA;1>cfPED>?dYey3+6e)BeQtjz-ZAd^rrTs5-durS* zM=wPC%Bw>*OT*&cImsQ9pjEh9jL;ks#12GjNDZ1?q-Pj&0cMRY4~Hu!QH`U_#kQbDv@r6xQLYi zfncMjD?vA#RFMqv zNCC;OA@K(&vZSVYe42Dpetlcc_CY`@|?5ir>upX;G);{j?{T3=3+9j&`jf_2=NQgdW-yB zCCAqYK{Zj0eqh|5I*jFMSmuX1pdXOAqTM?Z`Ka#XVoTFRsLCNN_&|(oYw~iL*N~K( z{A#(0={Y8lP~HFUp1Sp2o=sRF$)KbSZ>dO|uv|MVL!IFYL zdEbhwx1K%m2c0EZ7*y_qn>THg;xTBi6?CSZiMaD0WuKz(_cBlyMOhnjpS6uopJjkb zw>9M6R8f!+lh%!IoA?D05rzcp=l3s@*AS|SeCmBGP25>~-JC22$KeL~AngN7>Ym0g zgQa;9In>Ico?8shDE!fg-jA9=f%{i#6*JXErw!eDl#HGC3QP91ohCwq<(v34K$DR{ zPA8hwT^W!1U|qtC>^oFrCj6{Xjt3bLqdLvfclN${zSPsO&)^#1F68gm0a~V&|cpoQ@zz);D=Y z<{SXC0Gd^%q0!X~XBp`T`7Gi^g6(__CpxvmTgdc=PZMuOc{-TuyiZlRmY+L>`KBrU*x@KFnFO}gizthD8XDtHT#~|}@2qOY)o`wlrMPeL zxHLa(wTKj<+E`jSSL9oguqeolpaTZx^>ds9K52n1i|}LfvkGts%x}9Ju~qX)X~35- zw5S5^*Mx(DWk-2$(y6V>4YPi01ME*TiVCG|`+&{$t~KpH&%C1o_DifGOm_=umbql zX)}JOi+aA>SJ8|0btJnnesocBXg;Ptbk<~G0xIJ#vh=V<}C3CPz%W z#Cn^BO=5_8wZbJk=&oC{62=*&?zyv%(^q*EFg~uS%G%ImXS*w!cLtn(-r-HH+MFt1 zl0)XSQG~*idQUY9zIk!2j`$RItAQZr!)6@5SMiS%FAY>whg!Ux;%mRcT!<;1I?15fdKbC50Iz>}+P&t{GC>|tUeB(< z$OicOX&K}k(y2X9!2dE|wwC@Rw3LIK5OV&03;6dQZ!&PK!Z$ZUvLWAe2&#Ne`p{tZ%E}R(IFNVs zEVl%zx@&~_?I1WlMt&G)QBvQmlPQdoHC#3u&>D10G!YgjEa=1K{3ftwalMLL?H6~T zZYA=~bDQ4PWx(g4yJJuw6Yt0V&)wcla=GB*Qc>voVGiyZ+90bA!ag6xLuMo+?mUV(g@mlfcdnkG-HPG8>c+sb55PhV-$*HME zG0VgVo6zG${Y~oT`y2OiUcVEWwIzMfu~%m5Y|C1bmlpXJFtKSG-w^aOzHnLMOrZY% zptB%3x$^(0@#R1H6k-i}(FRV0AM^KUlqd z;NBH%EWYB9+>}vkQ8|grZ&3h7rtVq?BBXUCeQ`lLp8cB$^=BJLd^FsMxSCk@V9gEC zvltfF1t5;6eS)=Wb4MarV`lN&hcJ#kH9;2lX9W+*k!jXCVbmW?q)$6xM<1?T_bBRJ z7ADYl&g@5nenX+WF*8+So;;*B!+sAoLJ|Etxp7ZNpy(S~aMzOacZ*SFdn+N7vkG$i z$Pxd|c%y8O3|NiRJ!J2qV>DmO!s*BznUAzj9d(9Y=07iyV`2CmGGC0xk44oqIltNQ zxwaLfaumoCU_8Lr(!!V!e{N7h)>b%dr`BRbHe?tmvWWkEZQYkQ=fZuHHEGNkNANp& z+O{&WHnn$N7J@z=c6SevL&HPR7Y963;))w9B*Hf~K%xY*$-?5ZNQWNRY{?+?khv&oo;JCHuik{Ly%~tIA zsxBIZmEgc?M07j~YrOI@O9-^i2<)Zh;j&ooCTj@mv`uS7l6Ij9jyu9&)*=^}m!GmO zSKv%ezZx4&?=KrhyJ^w?%i2bE)=|ptl-*fzui}b(Bq2X)9ajt(@Qb*PoRu?E~1@*x<2Ep}Z$kFOHi| zLUG)ECW475bq{%8HhBfPd(vJ0+(n<*v1?Iw8e$7ez_6N0+km^??3Ry+Wb%4dVh7%F zmXDc*rh6C0&&$O?X{rqgh5FhmOo*ZqO4?E!<(`qi<{lL0bBB)pEdZe;M)iYUJx+L( zS)88{UggJLUW~I+t)pt81q)Gvg1zhAN4ZJt{ic0&6i5d(rmWrh1iX*mGS;iw_4X;t z@iJCtdLEpH4DRTIaWOBog1ytq;JgpU?m~CHuR(-OfaV@KIxpGo8E##2U}jd#1YL~@ zt=+*f$(>a@EN>D?x8jigmyi+)NE58XheQmc44vG^HdoR*!sJhuynEFk;XD{x}`drC_B~5zKaq{dhbWoC|tF{zw(h3yt#1ZnX&IUMT(XUo| zWl3!RUJy z?e~bSc8;}v_}LTf&1L;lej+jl?@$t)*^9t+db$zGS6NSZaky-o0egF`PvvQqao9oU zE6$USMMlcK*f+FB{5T z1)hcH&Q_l1${tBiDB?~?SI{;njiE1r;mmg~{8Ef05s|}AMvqI0Q)3mifi^}KM=a+u z%XO|5n4Y6w{fPwqWEg_O=6&0IG}}*07O#6vYA@D#J3=K5#J!^sOJ;tFhL>(ntVI=D ztt&?uuXwEqEN_V{#4x=I_qu5F-5z6P!{?i%$G5oE zl-7$@XW3n^XD4y3-T2=EY5gx1F6_pCq4QJzfvT^KVb^n`ndz*lv#>r->$U3}3AQ-5 zMGy}#N*A3XtQP$KS69G)&tLk#_Nc<$J?Qx(?TXX77(eM3cRO7yBm#Qjd&|e|W4|IO z#h#M?B8;c8ih6#~G%(oLFHJau2&*fbT7MuOJrD0Y{La&h`27kafGb{;3;sXU;s4>w zzZU4(X+TOpy&o^JLepw1VQe`TbfQX8d_>}#Ml*_GFu?s;#lZRvOI9{peFqxwmiL>_ z4cL4SPw6d6*12z~ZW)!oRE||G|-P zOM|4Eo$(nj)%5e8tO_V6XRGBvAu6rtQBIKQQv+J_!2_jrM`1nvg*!p(UQb9Ds{gif n(Uv^%e=cMHX>0l2pHq22_Ep4Pr`TVK&PbG`Br!ey=ez%N?ppVLcfGgPyYGAJy;HrqdiUN{d;h9>_wMeh>OV7oRseL5 z)il%qL_`1p(bWd{vqm(dp{#7JXP~R5p{4pCf!hUDsmLkF zZqQKC($G**Q`6EjG0@U6(o<72urV+)v#_$V(%xhTv9o}fSXf#9QbKf9^*ZTw%InuD zS?H+gSpF}kKb-)2a^g`^05Q=Wz%_azVtS%Ky#UZ(?nFxTmnZ(6h^`S|fg~fRxDq?i z0f?@kUn3@?rX-^vAtxat0{kVWzs_}2l#D^?7ULa#o1{r{F+(F`Ph?0!;@cV=6EnAj zh+}a5iDFg4it{xt7>8Gf?0{kkUveyx>s+xW1tJnDycTH{Wx{o0$^}Sby*sdV_ zBmIry$`Ag5<4Pt)e`S=2_!==O8Ob%`e?TRozeaqMi$s)ENuS}CO+qf?oht;MT?QdF z6XL7fkB*M>{>%ZWh_C9=6Vn4804_4=nR9zpR7g}F{(m7eKSO}_^x^CEJ3mx|<~sDW zP;YM?W|;cj|uT%WV8k7x9sv z^>#Uvd0!;ARI!Ko{NRbb0A~M1&$!7+^ltczn#z9Nm8>uRtK-0Fj^M~vYUYV&Z96w` zel6QSm;*~)CK@fiUt#r6X{qvnBD9g%B{4^DB&EfY-QyR#_ zu&1N5`g}8MyF2`N_xaT2u7BC!!5OTOx8sIdOQz=KR=8Ze%Z7ss9o_S2k@Brm)&-ur z9VpZ{deKv4Wy=Z2G`FXFZdHPb~FrB9jJMq+CWdgp3C z*+t6$m94vPvvRsE-KUK`u^7jDmu(CAKXv8gF0CwStVN6nGg~~XWy>RDu$gU%&!T}J z=6nxft~xRP6vnLH&SCAHJa5@mRCyL%Qd)>g`7Uq~8|;xG+WC#sORx=d%D;nf#f*Da z?lhtW5QE4Po*&sIzLsnc<;d(?oBh8amA>5(@hCb~l+3E|lcj8S_S$SO9LIKPzPd;# zV~K4YWZ!G+P^~T9?!gaez$AI0Wp~zwas%=MUTiv}fi&cUZZfZLE9PCobWSKg`7{NM z#VDheJ=!d{U2&G${MDm6RGuM8eVmS)o9O4uiG&mAuH}^f?tlk&ml8C&tZHf(|< z7Acz+9ZD2c+r;}*nCwA%tealoS03QqpJm1~KrUJk3;{ zaE*n-a$%s^iNry$Uqsf>XlL+gs@_g{dy!0(i+fdmBH*h`cxt`fk3mWD$l%Dx|2Jms z%Xr^EfOFsC53_p@{s1ggS1BhiNp@&PCfs!zE1gRC5xb83cQO-IANDI6*oA#$p+!Qa zsSbz8W`p=low3@!FVp6CYbP(Q?nMP!cooTVD@d`>n)oe&5`7n5cv!LTdTyuZwY%@W zn6{`Ykh44t%Ke(M;IwOR_qMt=y8`*HzfE+E{S9!EVrIjo_SE`uNB%yd0&%L7x4mVJ zU)bBYY4muOl?540eOg%#a3SMtK8U$=otR_BA5T7jo)YHq$!Q76`tuvb(bB4Pi5b0P z4P$R0Pu3wc^Zl=I#gS*+pf7!bP>_u8D1gi5qo7rwd}<+L5UWqc(x)_--fm zoA+hV+{M46E~V>FsPp~d+rzVPho+?hbQZ$fSh2R=T2c}%g_9TKf9D6}5#|$XVs)Ik9jlmds%?T2alvjsUP}2gJ--YRs>bQV?04S- zpGOV}y_Ui7*ymO{-OkMF`)u(IpKBX2rI3G;lGHL~=#;5RGUbNC?C})Z0c1^Tdfg~3 zJ14)qfpBe#qlTFqIx#Mxr*AO%oIHCiC@Gf><+Lxx(|4L~d}50=Y0i58Cg_4xdE z1_ng>$qB5i@v<0gW*)@&mG1j`eB5d!Dy#(n*%%15P!o;)3TO0BL$yjqsGqjqo5CB< zNT}4RT$C(r$C=rJ_!D~l9+LOyQmV`N%2S`wT^3$aHk^c+Pqt_0rEgCs>qF#6%qAZ5 zAR(432i&1*y^;NDK0|_Uw)3atC6<~94e&cN8|~(jvGG}}x+-k985V$(1j#X?k3zmg zq@63onP}yOORm!G+Vx%g9p|kH`?7Bic`2c#$x`zfd4`np8hn)Re)HX&mRyM9Vaoa_ z!aFIeIAr_>uv%4iYT3WFd{2<0-vci2UKfoeS~YA`Vn73Zh4>P_P}s-f8PFZl>* z%xaEcZO6j4$#IZGRiL*>in$Fc(2#i~MY81ywL4R1mc2)sZ_%Qlcf_laa~XYeNc?M zr&VbO!YdgkO~mpLl}mcxRa_AvQQ5EG1Z#%O#KSuDf~prV3k&CJx?BX1`K2FpBTRgKd`&8$Iw&>Ec_2iZNr@2AG693ZN@NQIo zn%RQofVbx(`&9&m6VI`oM?HWDvL-8V`fz)Z+Hmq?D#HHErh+dp<@e`sKJSNVvEFS4 zO%Xr8DY!FpZw$I$a&Kqnwtgt-Kb|yIm-5FMyO+NkvQ{=0e6~BYeaz0izI&0G__5_f zcE)}}$Yhf$oM9nIgDEQwD^zD$p(T0eMw;wg>X@Co#WuXJcgv=0pM>cRIUje5Oq?9f zExF!5%KaCu(flE8$AU9l!dSGAwa`(l_YZ)g|KW-!d&~W^d#OdEf_x<=G+|*K$IBPH zTKxrmx4qV}i_(}q$hU6KJ(-^+@~r;T+L_mBT83x&tyEu z{KxrtH%eYjT+-H|A_8~ZvXb)UUcY4y@7}R5v4=S|J9W96r`{BkW~a)&OJwbK5(75o z!0vdpFLFw)-?F&VRF11@UodfCbA(vxc;NUEnX$yxa-Rb!Cl-s+zE4s!V(N@xCwQ@A znW=MD5C}pIRE_u80QH1qMs@C6>!L;`b)nTezf&7%lBVjJWBRMhb83}HMS1$PNhN|@ z(nC_3Pvh2DIhtNPAsYhy0d)Lm@VwOg1Bkw?%3FHpomqu9EX9Z#O&st12E?mqz1;z8x$ zFP*bw3r4AXCI!VQ=lX@Gs+*yk1iZe&nHMpCHhysC8^O;-BqrWN;W@D7Vl$60C4Sk6 zLK#`GeK2v>42qqUy>X%4+EScoaIgotNxn`M(9}~6YP>K(U}4+WsX=)qr{J+^uV$Q6 z8VfJV0d-HKDpc01;Z8!ymsEaLi^40!D#aLS^T1+!kp54#C3_C+rL=@%B$t$wH?YCvL(_Sw(ih2-aYY@djM*J?t}=;hudo8N4C)6RV(gibAoC4) zR^M?^C_&-I2`txDw#@m*Sqs4}rZRj;ni1SFdyj{RbBMN!m7|rLEbR4$zgyj@UWahJ zzf48zsO{9-X)Ig+ZY#C?M8k371-8QD<~GMfUsvWBt@~?Yho!hj4}Kb)ELCH7hJPq@ zTnvXi5{!l0WvZ4=3?;BH$I1c69WCM>FqJi2zT2P9ikB6s+1;B`D`@U9LAZ=!0=RB| zAmb)+11w<_^$lpg|l1r%1Rcu`CA#f3ed2q+lQaof{ESx%?t)6nwC()<0K9;!W*|^iu|| zhX-3uLSqDTwmbGeEoPfLgC5BSHScQHW1TU}Ecj{-bqLU6g`h3hDDwx-I7gXW}n^t7ZZ(mU*TZS%X;b-UQOdZn>`9%|NA`AZB}U5L_wcD++MINs!h z=+jbVyWZYAZu`a4DM?{*HNTZ3Ssa?v*5gR6^FjaP?*UVYD#WRXt}nF+<7OUar1%nh z?@nNw_TD_Z$~gCBp#3P{FXKJ7_(Hb`f5^_$Q=EP1iR4%%o^~atX|m;$l6#>$l?V#M zE$>DTye8h<s&7541^6+znL z!SVRN;7z`;61l|EpDHszlw+5e>oD;LkOXrU9QeKv$tAN`5Nf%4NEH8@GfG^~LtpPg zykB4!3b}}k%X*}Cpm@x3oP6g{&L=u$ssExCE&Y31BDqSXV3s4W5%j&{jQ!;&&J%_Y zl36|Omn0ma)0oiNyu&60kFP({ITUSfP32{}SbFbrpjx6?vhMMu2gkx2(PqO)2N8$Y zR>ssXUmz61mruwQNDfCGs^@=)kmWQ^SCW?0pBM|b%8pRIEoLyRJyjLjmmvlj-WB0{ zq10ilA}eqRrZN@|5_$wPY6`D~zF8;c*z^Ld_SV0l6@8V73+Gl~jfsjz$bB>aBJ~H5 zqqNQUw;58mY4@PHV_moCqLlaFK7`axedLNN{^gLFCST|+0l$fgu^f4oH!1xr`d;Q; zZ6L-~$tBLlP8gwS=d-Z_>Vby_80s&KD}Wyih|(bb*=XO*x*69$fQPR>ncHeub2pp7 z4sM|vOeXtzg1{fyOq&yWS%^E2M!Z&Vp(|2Do#ss)Xz#{M9R9qu|2=k6|8e*E5Exi- z>kr_yXb3;@p$*S9BDo0Z{tWgLw>#@8+5Zze7N?xd5XqcG9RR2dhxr)9`s;tZ6b0t) z*DrqDtDk012X4wnKK$K+apdi+13nC<;AVeP*&q!~`&}E&HmpEhD!{*KYZvWUnbe*r z+QT*K;YQ9GN^Te-UpqO_9>mu1lMq1tVVlmMVmWQxrs>x;S|vBAS|)cE{Pu44l;I^M z2bdUB6r{;D;U5k)_)uPg0M{{4HY+znVcINt62!-goc|A5&3xbe_CjQK*nVFs6T%> zj!Ap^ufEs$8z$wQ7>(WZWJ2Do8_qNuyKD1)$7y>b(d^}MwKVvmyUq)T4IM>>FZ$J3 z?w=+FZ##rm2LmB;tIdwwMdi#9`O)=X0hRx~lHU?Ue`5pxJRD#b;$&x27tE za}jG9RA~+z!Xmecey@LcTM<)~f2QF*;tVdv_lJJmq2oELlrBs3pv44L=#RCu1Rn6owoOdi&+z>ImQPg&-ucx)c z1@?5~aldY%)9XX0_Or9I!LfB}fzT)o+u_M`L8r0p&Xj(3il3IKIiMk{;~^U75j04p zdCvTJpQwB^RBlQ#y0$Uw;4ND;OQs>a3Y5k(@JUmIOxGAKg{D+Q>$0=Zr->;TxA*KA z9a~xBL-w9~v0L##s4xoxlA-27bF-jHBBrR#QF9bMuLL(Yw@Z|rX6olZz)!yMTNu5t z-t)qxQq_BTl5yD?p&TmswWt#l7q)ceQ8i+M4Lq2@#3wbmm2We9(t_3~=24}>z-Xbp zK{=j&Z6O}E=MU9xrQ zCyoYCztP0$nq@0hD9lCz7pw>WG;7@+J0D?*c8=&B-qxxN=VOw!;t-(->*~U|)5-IJ z-s6=Ws!FPjmY%%U(9qLlVX8)jn>X83SQXZv&$gHL^(jN9}M-R6Kb8vafSN);u zj8#_luEWp6<l^wf)lF#nQ>&^91UK3q|5QZ8O z_m8AZpC?c#3wC|Wa_+*M0!c9qrDeK1G#>OvEuA;7kIC}@o@WrXm{eIv>&@^r;1>3A zeG0=&BP4gF$?OM+A~^j5>QiD@6k56F}vu!)|y>y&NQulzhO`Rk+pmazbqS&VpWj^k}&b*FieM=6L* zYDS5MX@M8pWfej+2?w5vWX$r?g!Pnx`sAb78V#zkXcMOPViLxsZL9aEThNpiun+rd zF+GL8wUk=nhJ@yCNNLgzdE(f^uyI4yVS(G?eOLvnDz*EQX|UR)r@1&wnBcD7|9d7*ij+C+(8 zN}SEOy4ed6HVtbNA4Big)OF8Vi_d;!^WtQevxj^Nn#yb9<5I7+Tv{TGZqG3 zR{a6IEY3lNNqeFYaMu>AgXzaRZuqL$X;Zvu{dFb50_xS0?1_uF{^OY`vk-qm&L#pe>Tm)}Xxq7OmfM1it9 z=QwN%PFth<{C>UsDSdTwlf3rWLrx&lWXD@F?Z&+)>G}IIrra!SyHUkev~NRNGgyrX z8{Z%RzhDzjglW;py+{oAWXFU0z}#h35DEO=9#|5IN3VK&*5W3OWOLgCsowNMo)#7d z0MA6@TwK8j3w5sI*F;mx^?fucr9s2rpW~8tqDKOmnoCx)>cZdG7(w-BKGsZXfqJ*2 zgpn53{a=Yao1%keObmPxE==>@Vac&BUN^2Qj3XX$joQ^Ie65yKq@x9_(3oHUbz9vc zF|>%4|5*{eSh$=^eQoFLlhTm)V3(Q?;FsbZQeV2$?PD($w2JQX#p|YyH1!n}Ne%2m zGQIZRyLzijg1U+PB4WCCUmc0}WO0bxHE#5M@M3-;T$#*DwxbCcC=c_rby?4163?*w zx*nU98BR7xcXOId;*HWEcMU2?Hi&cfMD)~hkvn|01Qu{G_sJm$bvHe}G%51*Dcu3k zfjC~iN$?}eHOON-ra;I9Pg52i35}u+`3<9+4{DtCe01u^Jg^it*KE18r7)G}dpd>; zq2c|$#uKU}v&?H2j&00B7bRxZ`jzgc5%8+Ou!?t*U8A(b4uBQ%@jFCju~tA?aE}>ZW=7Cft-s*Y3;E#vi4JK8d5+g0qs1 z*;Q!<{5D5k_6`&S+)0Nb0>zlhg3vrRi=h>Ckz$#TDi`9}Gv#J0G7PIDL?MTxS8}Ro z23&+es?BPxrB^7Jy$PQD&0%QKG567G-Bvn z(1F7*?I$jjuxO+t3S@1eT7fimVGD9AnN5JWx`gafN!NJ;XU!>s(?${c&~TCQmdD^K zeHU*WcTzJ^C*R1rfv1CMQAROPbnTAZA3&hPh5zF9vN~sf1y}gO^kum>Z}_}2K~?-| zv+=3%{iaG}4JVE8!sQ`}twOnG9$)^CwMAZ>k?$~~1UCiWwqNqW8=XIs>0M=)-n|^7 zyN=8}@BSvJnDb$0H;S*?TG*u2-kl^-58pwi&@x70!+OKbKS|#TbALgEc`vgY10a!P z^wv#L@020Jc=EV+ES5IJdsfb@&%MM$-IjFL(n2+hm1T=oQKeH8aPVlTQ$SIjgg5W0 z&=W)+5)u>4bMV_%aFl6judG4gEJYT!RM5JR6MHNsFgJ7;K^seU^BMt%8#07M%hOD5 z0VVV6lV+Im_;)9|QS1C8WA116c-P{4EJ2=W4)H&E?$gd)JvN4`O3=?|2F3A@x^9_o zJ{;m(=gE$HTDBMKap#W2)r9KOPCytow6V0w;u7mD8>u1=)m53pY(Ghe7j0&J3U(4= zMOuOyuZz`d+S|8Mf(KgDU2`kn=N~D|Oe<8k(JA*R2Ya$?tZW_*ai*3nRVr}IIl0r^ z@-!Gnl!T^e?6^t_C(76(7N+lOAi=!thIPH787^ujP^kZt=HQZ1aM35`24Zj%4R2C>x?ZaK$F&~JCP~`?? zcYl!K0e&?V>BAJ{GTgNDN@m(elj{?bv<5RNkQSO3Gsr|XvCWJ~VP7_FzQRh7PT7ZP z!}(${-)3zyZsZ*Fb^l;DmFkx`3?l8}I_pMT=wW5ap>Z-}1D07Qtz|w!XGri>2=yun z&Cco|z{l40YxTBwkUcdiwVZ3?(DK7sQlY8)??DV%zr}vvJRpN`SZZ_n)nVPF+W89f zy&ClN^cMGhHwU0TcH>wR*xi(O_0@ht2k$@M%#2#$t%PuHrOo3PB|($(#;9C2+3fad zN5MSXvPwQW>5znmNhr6b^$OL6*5HxSKxms+zUd+Yrp?3ew zz_Wl#Ss!Qhviy=LbU>fnE6Z7~&qa+1i2oq>WpI z09k&6gTu?ZlZ)P3H~SRd);z$(lq78W|CX+chSFItT0-wSAv;!kfw4S~b%fJZ7QoXb z4baldA)nySMYFC0oW?>f6rp(fgT z)UEpUVQDjFJehrHDzWS6>kX~fCR)*KegQt!mat+ zp7g1b?KXZyWAZ}+ivy-s2PqM-vS*P{!QNysRR(ijSpO($jQs;~iqF{Z=0y9Wh7mY| zDIe+nBGYV6k?ff5K8}x>Xk~!DA98`*7?U=iQ;1C}&?NB^t+K^Ptd4pNat<$qG9_Dv zI+d2$mJ}yUXfnK-IRi2^14C)!1;KK%ttr9zQ@CN&Sl(KA%@}WLiL%%2nWc@-O+r5r zMYy+wn4$uLDdm*pF!6I2F#}xhSsx$L*cAF6GGg@!%5eR@7jQLU)RWB0I%92zzy2iN zlXpC&>)|;h%dWXwL(!nJ4(>eYE}80&xEeB^LVYO+Jn<_=-f^-)aPRi0xPoA6>>(lO z$p#nPw#B`9I3u@1S`YhOCagxOT~0&dwq}NZs&_2~r6nsXpo#l6OHb24WS?6hb{qci zp2P=lT(kzT;wE1QD&h(|H%Ci?qlZN0Dc zcJY?ev>Bl6sqR!G@*F20^BwD$Dt9*tH|o-qa4Re?u~&r)&R)pob*tOG>q5$NuQ-tP zR(yP{q9v>N#-%?(V~4_G&05#>ma*r$-(62hCCu^7;i8|e9$y5pc-brgSp~Jb9oBBK zg;{86J)@>j0nUr1?p+7(D&WJLN)^U4O3T$|ASpsJFBHAEQ0E{D^M#eIk^-|HuSp(*u?@GoDfsh#U)mVOMt zpH~HmmvRfEjwAUs;hkbiT|Q778c@ulpwlxDw=PTT;(OXaH2=J78%yw>f+Ny_-j>}? z`W5KiY~Y@Cc^ryR6sO=&oZCotDs}OCEUfQ97@0jFn6;+!K#qf)rGJD;+wggk-he-Y z;eauNY{@*MkakpT7w{VA5)JU?eKi_i6R}8*e*5Y9{Zux$MEAzab10%PNIyk=uc)Ay zB+7C->uEVse*;Unw|W%L=Tw)2d)E4l>&6^UI4$(7BAd8&@f&y&A%h z>mlRO6aLx5!#Ndaz15~N#&Ait$gU&*{`o?DtEdHeF#&D^d z4#plCv&WAJPP>s9V9nk*E<_)C|Nf&?N`sS*_%eYzp9pMZ&X+sH4XW&lsTf|6LS;iu}lvMmF*xn zEoBE$QB@vygdc|!6=$B-NEJsF?my>|r_(W$39T(6G|dWBHt2VtQvy)B;bfDOs^mlm z$fy;BGBOp^Nw&U-K+0L=_7!mAlV$TP%3Vx`rOwNOdpt4|8f7>WGDKGMk|#CLHJ^W4 z%6PCsEaa#`<(jBc&z!=R8|s_6=&bjZm{Qa?Ulo@CIMt^KhQ83nOa|SsxTD9PSto_d zBn)u`6T?NS$y!73Qi{O2bQp#j;eXa9;pgz?MpVODe&Uu#bC)ET5gsUNII6%aekZ^d zEz08JMl5>mlNf8TCmP1@QGcFksx$iFX+cE={*)%Fv9vOgEq&iui|A|A`r7*hy~H)h z7-j5p(RB_YzD-s(R>60(?3^UQXInI1V}oDlVaX*sa`H=>#+CI!f+Z!bOKkmQwSLV@ zzgf+GHhdS6qmK)pWwrcSD{G!D_(~}tCel{<;dmr<@K=&ymwx`ocZBM%-chknkKJLade`N}_JZQ;@dllufrGf7ZLJ^1RVq^B@4UlYwi z6xq(1+VP9*5ue_lm0Lx+W}Ebs*8Ir#xMWbAl1;yjm8Q)V-#2Nen^&xi_^0N78msi@ zY7BzW{H@vOpT;aslwB?xL4Rv5{im^p?eN)Cmw#$D{HHO*1a;l+f8LDMnt=~+kCHzC z(=t1mi;L`2K|?}nx6{t5y#yJnEd}qzJ`%mP`&CFq*}Wt(^3#98bj$xHlVSmBv?!+z zm#k=C365=C;H&~;Y~;V0|L%}~JHx+kgnvhde@Dgtho1;n3zDOo^8+Uv@6Gpa0RfHr z6O+B7+*$|wGGO;!nR0sj2K6Qd z|Kri^j6VPksTACug;S#!pCYy%OzQkCu5WzLwDosQ@Bb#%F03E?AN9I|i&R^7OMd0j zj=e0%{M)LNs~C9P7`jjX0{M&QZ)v)wQ-Yg+*#k%AZ`nJ1e@o|JS~19f;*tGt;=7ao zhI@6@{@uHO`O3eY;UBl~|G%Aq>Xr_Rgo}G}mCs8j{=Wj0y)m=#Z8(K+{I`(J@t6Jb zA5P2=0(S&Y@Z+U#g8j@E7rxE@)J-6L4f8S7zi-=u9T$q1`}tY```;oA*!ADx=pWC5 z|9!#U)h@sA?Nh0DpcyaA^3(Z?Fx_tGse&~O{Sl+At8egi*pKIZPpwqy?U`CRocFm{-N)7oaLJRvuy=Uxdj#V#b#_Mt{9RX2eA3v^ z7VA_LA&>26+WHI&^M4=ud{*P`@yC?`iSIh%hp*>a7v?bc3bT}eqKeQgZCi~8oJQb% zK@z5DBuBqbY8%>t2Kn&3?e<(9y{i@uzLZ|olAL9~-1RSfiC|aT0NDRba2NM~f^YD{ zeprfm$h`~!72D1L{EBfb#2_t!lS-gmDa=_2Q~xnL%#dmnz?!!QioeZ}ru(DC$YN(b ztq3~&X|w0HdG~Y3@%7lBZsr)L^0k?JSbezJME7v%yNRKS=Z?4O3>QzA7E8WGT$DFt z9@sN$|9x8QJ00MYKX!X9UHiY7T_QP!28xuu-0nx)HzbvB)Yh&;YAHy*2i|PBp=GEq zb>~j>|Bd5dEtDilDETezef{ zT`Fm1{IEro_g-Xu=$({?aX(u&%Prvbki^I2sys~14V|Ghb0KAcRTra{izJ|gPgfn>+R@?Zmk?0KUq&P zYKgb$nb|y0TW3exkly>x{<@=N+w8O{POm?{|I_U1uQ#zF6JhH}!$6*F!&_Osl97?s zSA$McKFhrVFK#|4-My@F{rRYPmHRTQs&e2N{MJIwAAm!|4=GHx2I^&rWL(~N&jy&A zVHcv{AoS9ipU*CSkK5h2ciG~Ax#d?em7EXyshi%*x}IO@riCbN<6>|l+}0DD-aDml z0sSsX5?Az-*4xk%qT?6&lHLvQ>^{vp7b;amvTP|TU_QUBYD%^&JV#mQ`z(l29*yX+ zElw!t&}Sj)uFWR7=JgYx-c8_$mRw!{DV97-`5?>s45>+7`-Gj=WT5tiB9LXVceQWO zHIF`CcH_kr7KWDxzTbJZ0{>M` z2ytKknV@te{CjE-(v-1;4oTtzmNfrK`JcF6#*!l9eMRovb`=>Nha)&(PWG2&YY7D$h?7 z3S<2qq{D9$+ntvyRyt6H&IL&YEaqHTr#3DGf_WRGh>2Z73zh=QRqk zkIMb^e*jQpix_R_^Fq8yB+K_j?S-!cCOg>90d)&@APr3qi>04tFlkGd$BjiOboz$t z1BKCZHa;RSgVWJ(@=beFco$cq4m}GB$cUp;Z zFZKvvTYTDCK$rtF7$<#64`wsCKHgFio?lJSgStGU$OJ*vQ91E+|N$ zp{7ehpQE(uRxQi%tu{c&s$`C*O9D?%YI?q4DUJYZXPoQa#-J2tY%y*6dK&b5cJZ&p zoaWAHyS5?$H0oajBdwK9rfy(w>=_TUwc|NM{>X5L0bDoft3ipXs?S4s!%-^ zvGq5fG`Ir4Ry@`c6_MZmFnhIl*WbK_@CQ)$2N2oY_U&q6mBSwZ{m!#3*zfV*+_%0V z{s2rYzSOIQC7I5PoMz6d61(DQOQPy5OG_gzH&af%~tzST;P&9zbKlLf7(Z>bkU=% zKw>Ps+3+J5LdnjH?V)Ucn>x_1SsmQPzD2Bx3Mdpgo0Dt!W=NR7XTP@|nA8}aj841v z>Z50ebM@B2MZbTW-xChthJWGVL8x2UV(E^=B07(}VnRvPxoi?II%P0Ikeu>f)Q|W% z@Vyhn0lP3sBytke&BNT9v&DaRD=lg6TzL7Bv-><120TR_j81_VEQR%LAdAQ9$ zyi&nN@{_IkWj?#D99fM^8JF=`)wq3~`k#Q`c1wvBwO*Dla4*Jr7 zx+lFn{5#@#8XZ%e?;2U{R2rrHQhkP+bWZ1R0NV;IaA&3^J!!yTSs&2gr4*^yV0hL)i7Lc0!LrN3Z3o25^jh`S+ zUCY{kgPvvOmnT=>*O+P^B0TIKo%?z7zMpQ?-R+jGLRe93)-UB^fn1EYB(-8Lx`^L- z#&VTC1WhL0P1MX65fkaLC5R=&e>!qb*KSPF42&%*iVjU-M=bn4x3sCeiNAksf91`% z2<4a;v1b->CSw+x#j?@e^1KQh;qubNQkbzpa!ORzQ1zCYY3h^KvQ-{wc^4lYz!r8G zA<3-j6Js1L_gPxq2ePekt1$VbiTqg*jQhIZx=jJ;DB>$5lBi9arfX|cldvnkcF=Ys=I6HvMJHrdp7;kUuw1Zc z#uq|t1X-lj^NE*#g{G4_WaWQ^rl{vzs(*#1$8>$IH`!YVt%Et zx6px~Bl?+ygwzA_7R>1=Ak<5!4m39;D^%Qscec<(=M|+ij%dqc3SJ2%EC|uY{S;wc zRb;T5WV=`(wj>g$d@ympeW%rU4YnvLDUZom0BIU)zra^-%ILW#Igr)ToKd3U2jVbv=x0ol}jnidh62x>|f9M&r9 z*sXQZS#wV=(E<_IC=2b^qW?He3{vUptTj0cWu|FQEi$bu!!*raAS&=vZy8;%o=2yl zd5i2%9phOCsKpoivI9xiA9t%qM(6xvLa@pgWbJ!S>ovM)8Dy>B>37lMarA9GL7%D? zhlk3G$;#Mz1aRO&Cux)@ul(vQZ}Gv)gSvx9sfU&L^A88F%0aruJ?Nd?@7@Fy2eg<5YL(${PBA|%UhGIrnams*)%8tjYH~L# zS8ui#dsujEUM(g<>PVBKn)VuMN8EQE?+Iobdgn8?2WcBYOHeBjN2eY&^G%$=E4a)# zwV^I)SM63!sU69hxA+6cs%Z0ho`z9dF7%z1^Wk+Swuw%iK+S7APSF$AAjbYgeODI#XRhr1C0L3>iQ z(%m;x>Svl(p6Y|*VAfz&7wsUUgrms^!6T{u1KHagi}74dj;E~(gtBragNeS91EaIu za6`EkxaEM6%JhJqCU^4GHMKv0ba!&98PWW3CBn_vCmBT?v^3H9QzmkEI`i_|+7fwE z3B=#&D6O-A9>Db&`GNL~fZy*roYG_KQv{eUbS|t0H^Gp*(hwT1Ir-Nj$~c3@ z`TYF`S6ubN0bXLf4VKQIJnj--6;9s91R>j^^`X>&u*@QV-81ZimfR~TG1G2@aO^%$ z+iXu{y_*OP-b|#h&7J~sc$SKG_kLY#O)G8=b3l$PeEy}E9(?4vE-!Cc_bNj;kt4nV zq?)$u`5KlncivF_$c;|Q)H6fPPjdjnwL%MjxBN!5UG{3M1-j!Z^OS|wRUBg&@+Fys z=?~z{oakcsB#6D_S>E>U%w^eG7kio6MgGCcLiCHfD~)*#uV_R_!tYCWbpf08Nj~C+ z(~AY{@%26ek9TiivF}wlal=-F3-EY~i+(u`R)A1azMDedA{gs5ePN%+^}LXln{}=0 zjmryb7Rpb~BFt<$31GajG#R`LSEmfpw#)MsN3#NVSYX_99LjzgG(NqD8MdNn*w>CX zCraIjwZqRVaNZN=rUtg$<*NrY9Ew#B&YQ=#&I%v7rA7*k*f$1Ly1d07##PzNpYjZ< z14UJKETzc22z2tzpGWnf;9J7)2ooIzvdp!dv;G~JNAk>>=!bGg``IjTcQs$Nc}d1@ zWm8mG|Fp#_h#IQLvs#$E#L(2mGNMBRdNorZ2{tx~m@*<s-dK1>lei=WA#mH;g)b4(91}iI>14=JBk9LDSPh6^;%E_}u zUEVQlT!YON(WI_CCQn}2*6dS1-5SMUCpCooN#2Nt%prNBm5|Tnw$qL?UrEyqvt7#p zb+~xU8pzK6O~?KHF0kEulAFeJV>{0g6^uRlCg%Qgckz?z7X_#(&n{LWUy7a$q|)-6 ztqoHL9J7GGxd2aT9h2JRIr+g!A|zP64#qF6_>e-7;OZ-zsapb0O|KIaMv8?r-TN3D zWb|oZd9X_eAhSfJ?bidX#?OZ5i6?yvFnn(g|3EGYk2exxGz3-xY{XYetRC8!`@5&?exFMu^$Iz4@6{)4Twr zrPHoBt~BxE;lZpNf9TiK=T^Ho%M^wLh{8)NL%YP@V_{Xuh=IFOYTLZWViyyMGm_EocXa?5=+ zi)lt$bEqoCBAs*-;cBc+t+|d&CrlXC`YjO0cu{KfduGVd^ow1a7H%zg)}vjq=n|dL z#mnPrudGD}y?6@AA_~9PGbaY{bh{XYa3PJ8^hYFgbMw6gVN|XG)*`S0PDk38T)|s* zM`sSKf?{~t8`?yHmFt0wCN{*jw2U_`b8JDq-J25jouO+GwTDNwH1|EV`JmX24(vKq z`B_#YA^@_>uKL@E1sTHebPf1?{8h#UU$1Go*?SG;B1As^E&k@Y$_XYBJ@biRpdn=G z=B)y@p|2)i?nm~LF|ZNtXYB6p2g13W1A>msWsCI&hqM>Qc8IwPllNWh-vv&DvT41( z3A_5f_Ipg2u|>5twray&=Pc$+1o9A0!ZZoh2YwMm{g$HDo@=YeM{>Q5blY+Zd3-~X zwTXOvKy+GdqpXjbor76Fq%EGjiHsPs#@c_e)1d7OA~ts|$SUio#c3FOq&=L_zNL*& zR?+*qxw*39@v55;H*})50Qc@_Kh`y;wiVzKiH@q7w6DP#k8QG)eynnb30dlpw%NCF zld;~5G#|F&)6Qwoh9gQ#_tDw6#>#HuAV$5L;cdY@F;Q(gy9RcE-}}3J-Wu z?KGQ{Irq{gZqPpjh>lydS?wW5f@&1fSN#>>9qN+p`_p%g7j4R$^bOx(>a^Agy2ix4 z50Cmd0a8#2o930zXur$RkE!`(WpnJxjv!`J2Uj7UEH?5YR9p#X;ul3d!Z9eyY1yL) zhiVI>XM$agrTt?-?SGk(?&=P#T&Vp*WW!1M){g?YUo?zYY*d3kS|>RvQvLps^4{&~ z&vcC=hx3JZiOD;e*SBLh>USPzVzbVjo6KGN8j?LtjiHp~Y|~UqEYAU{z-wLrl8mob z&#*z14wJsFD(48e_L7{c5PU+~lz20%gp3H^4H#grtMLRNmnqdRy~ZbgSARgwmhuZx4Uy&L}?Nx!WLRv1>J%D`k*$tVrA(CR8TU!;3qBXjzW@LR+eIA~Yl_W!}&TSdjSy!)a}Ah) z9D=(A5+KmHJHahL<4uAG@5Wt{5ZnX7-5P?sdv34w-)rr2@7WLMKHf3z+Z;9LtXWl` z%&Jd*pIi2-v14W3APQQ5^Z_?X=^0f2N7&U(ZKhL8-{o*hot@3w=B2G0j;)6cQ){Y> zRI?Av9y+dy!y*Ot?{d@XB(90t3Hvrv7tj1`$H&efg=`gb^6e7YqPEI00bCOry8T$j zN-VmsINP=e0C}n`rflomMw)KV+@>_dxO2hb&K@%ODM?B^53Cbx|!No&=RD3dx+J&G%gu>9K^D(jL7#8<8ph&k~9! zDH6sPoIH2K2X-KM@a?A&GXwgV=EoAV$8`YdWne{&_F4YuMY9LDW8Bn5IfbzQO7jBT z2{sVQ-D9MWrnb!*CQ`&ZB^Y(l&gwSv1$hrffdx2t5wIj|N15U~6_)0YBTGvoY<|0$ zys;JLVTN5X$D_G5(#Jo)XpP!iWSVG=ojo|$($W@6BIEVL>uk!1MOzW8yWp8G-dBQ5 z=-Y9@GB(ni_+RMsbG^W|jY38!z32Zv?7ta(;J0)d1aN$@@y)|P!DrOM7Ew=U+PXX% z_v~9KjPQl#@Uv%>byw;((fd-FXv2O~12y0>EmwaBbRgUHH4}fK(tpz@bHJJ0~woH-E?d%*(cAqtjSh z!;mtoIJ`d2e<*=3InqTYyAo3m%6e?oY0v(%bk2i2FMZslFgrA_-|47j@5XCfV-^CJ zVGIzURq~GOF_6OHFg4-aewFE=9Va`%NNw8$X42e4QA&TQq)l?d`lRn z^ibnT{C((Y+9eRe7oJRoAj+qc&gT%4Kn@QIO?|vxHrR_R&92C6RYZnYQ})SNL_^(P zdbfl4z7h=9G_ksW{j#|&pn5jyX60dZ!P-2n%1y!*rdvZuy|d~wXbjBiPzi7|O{RO>!<;@<(eK+lUv_Ex$*jmm4gqGLMPDo7M^_saCV^PcPZN(#yP3T>>n^O@ zNS<~VG%}){VdK~*_o6SVc`KOM;vE)V*j_#i4qE>X4K4f-cdjp++Tfj`^yRRoQ~zy# zfR(AL-_tyV8wV@Q5Dzb&EZ+}PAW~&lM)|lk-Gd@S>+FZVZn2$M!?=oyl2aiZ-wmTY zBpa3P<&5!Yqbc^{t${*L-qZgaQ~%fCRow2uV_c`O{O;i`XTi>_|x7 zqWmWI`#+*|?wA9$C(r+H&e9h4X6c6!q6-JZ2~Tjx$Ck0r}v72a+?Nazgu?5F_VkMvqICIQs8oeXPeuquoOwpVLnDcC`q8P~8B*aNXmSknME~glW&AUe zp3h z6ktSO6S}Az`1yJ6e}4xo;#6+5Ydm9nu(3KbyY(|5--lYj-KiH7=Ey;U#sU6aRXVLs(fE|N^mx|0=Lqc($n)Woz<66 z&<4JZDNp!O8rNDMH}VYH_5zPzLaF3keqO=Hdp9cyBEyA*2KZ{q;(PC#>P&$cR&bB2 zYrVujV-stc+?&jP+nR1d!5v<7>Q%Kc?^3;J=a3o)v9q-)cIOAkV-rHKFzj_37C7f@ zo9t{AJfO6h%7>j$#yzP(Y!`snKA=qUf10yKSsCS~akmaKaSSI*jo!EB2%CuecNcop zh&b7r9tGY1HUvYh^8ap?uB;D+_3ND?`GlIUuHq-kQ#q-!-Ocv?0FV+~3%h}Txqseu zmcj!}6^vGB0jqWj8}X!Cx{^uxWj2Hu&dtTAk zMGCVCg4`CzVHbJ+-SoJ|=>z|HBPNP45bmRSoqOrY>1@ zChpxGBh=u(Gwr=zh=Jz(q-QNNC$Q(O{~2B! z)3LF(Ce{9y>-EWYtd1}_6`wsKz!Y)pSwD0EYZ~)r4a+<_#;Qw95EFYeoT0nK!MAXxbJ|=t|#2Tk(H(t%ztfnzL<&Z>Gh>9et}xIIv)gQ5N(jAvy8Jaz9;^*ht@o6OCnd)!MT5e>!sc9(t@6b*lRRh~nYxi-= z`tXCzh&rMCB>>tn*BqTHoIB+ebiRbA&V8SygVwj1$(;4`Dh7UPsVvQ;aA~(yp9#mo zt_YXI zQ^&;669%KfdhgP0n4gE}cOj>Fo1xq+6^|=`p2Uhwb)*#7A2chuxxe#{W=b(zqO77*w?k}+y$q(L|Vs~lk6z=Z=oUjSo7tk8+Gq|X9)NTy6v&5kx!XkT7O|bgmHW%~+*6?PDCVCbJVv}^A z9eM^$!KCJLJM;n<7Xll!{10safG40lk8zMnCBqyM-bh>XShWZf-7yorKLtBIb#6)uWhxm1&K$;a@I4UK+OnG}9wL zITI=bXSyw?3B?hZ>WVu-aX;r--1`}v{5pL6bAj*!UZ%t*$((MAbe5{`H_d^5wu8xu z!*~$kN3W_z0&Z%?{fOqyC1%f3^`-@81guE;CQX%76wcya!Q;mVC3Q>U1@uN+{2wQ< z;Z5Ykw;#pbOiQ-l{&P|{>^C?5^yAr>Kh6CmH~;@LAm=Y&^nbGBIFKI=*GW3b)_vBe z1d~rN$e#`!s!lHqjPM_>WNo+Hem2}Ny`v~-pye7qTMQT~JLP%6`8Pa`?f(nSpB*l- znfO&@w1HT{lB@tpeoFq2oK(-d*jq`};U90RUGH9HtTNwxD!6!3CMy>aCM#Xr@bE(3bN3bx|z)q~ZR`Zva1DE?NPlc&gadE||P#BnA&2ypA>{Y;;DEB?pA3z-Z zR<0?VGza+fmf;XM>MXV$cr_Par+pc>)d+<6{{fuWGuXi5<3E4NSqTRI04axK-O3T7T6*fp3Y$?_ zFdpi2Eb+0L0Xam{S>%t*o~7EQO9@R*%1B-?8}?4zj=A9J z9+eo7(yAVpIF z@9pm?%))lp8c&0~km}pn$vH^nW}wNtWj&-Bg@{1{e#|32jOzK~ZB;V-bh_HfsZ;su zE|)vasM%KIorC%u`)!ZAUf_lCgJ|(SX>X5B>(ATnGyNORKL9$^)N{U>$pz*uA5TjC z^>JCV_w*q*oIP`YKTUQ>^>-)#nd)dj+GXrk?U~tM9TA_=j9R}>`vZW&Z)Iz8XrJDS zN`|(uIeMR^Q8NMcCqg6+JKV0d4@pJ^g83jw|0KPMN0O4YIL(mbkI!pzewoRYdl4;E zV+|VrJq9ParUyHVKY;STdjsa(g52pwy&O^f|3y=*+=G~}g6&tOwnSIaR+1ue7doaG z?$&$+kxELO-(Hu(SuYeT=!06oQ2Ckw1}?ezU~W?teo2u>Mv{DT7xv%L-OVWR>b~-- zp*i$;1!$%6Y%%0DG)6&sr26J=a#Xqe-^J{s|I(Lz2Usn}2|N?4DBj(rsQu+6yMlJf zBfb9zz+EDRER2sG4fwQ#nk3=fvt+->oBDI~KY&e+k`|J!JmID+`hEpQ=1K(kYMxDn zfjaM&UoFg+-S1@aY2PjHz)qf&ec@kx_}@gL&AXN432R}o;mS~OiQjH$Edd8!^4(Hw zoZraWtXF5_B`hU@hLdtvi;~#)r;M!kz{cU3Q+EHt-@CRV^1Qb_JXeMvZP=np{X?{|r$zf*pQ z3GCIm&oj81rJ7a99gY#Wo9_Js_=~0r(pePAt*QTEkm}>S=e6q6rj%q2u(p$F)Eff1 zA7UBUqFYo)e82<_R!T0Hkp?LKV>W~Q$c4t_e`?px%fgQXP=4GgBKCJAO!xzEO*sl0@3dfbSLIZ5Yq|6v>3Hqj2j7g((*?*xUG^F#9*0BjG2E4By$y@J z=W|RrZ58%*$z0T9Gy@7ALRwfzuS9jbKd;*%q#s7LP!gF@1`<^#I2LU!K>7Vi2mIf} z?6ZsFZWSK#I40SfKiJtJsw54SbO=LQIEHWjURTsZ<}rJh?i8bnK#192VyA(6q3jP} zukvrrkaE>cHHVd({jmWR9o_g>6PpCaUsU;z7>*u?JgrePMb&^YqgaiUY&tH@ichX*mY@@&*xp zRT!l4T!U7W1h}%4OLEFx1TJyrC3ubfVDLiGsKlLUR9~vu^luHr%|P|^RvbkFv#rYB zMU=KEM#;7w)*nFX->k(AIre>Cm%l}o*I&rjSx}I;JZfd762F)DMzZ)ImfD3Ukq>0) zF*(V%xipl|ZgZ7IH5Zxt<|D9+p(r16GClDJ;2y5E6e7yR)p>S_9%)kwcb2;EsxR&? zX&t7+JX55JZ}w_lEdFW>c$idJlFF0Meg+Y4ivJnVliRq~*?teVlH`}Wu(%=FD!dg| zlpk_}>FWmi7iukq-f-I0xM!G%t5qN#wn;~i5zlL}P#T+V80IC>R$0QtAfYFUx0P1z zeEZ3ZP@L4xR`{A3CBRQ_HQcdARR)3d>2br(zZcJ$um)ZSYl&iR)rNiBraBTlO7pTp zg`A&%QemLXyM1{^G5S*K=ii*5bB}D{7&-k9pY-;ywT|3&{Y!dsXoxRc&yCLgU)p#o zhbr$@>X2+yPaU<8e@m6*u_=Xxlxxm^DP#;Y>j2~p=g6rx!##?L*l)Ytb>lbw;jwnA z+2Y)a7=Z@Zf8-3M*mZAE!i-YvC_RZ<5bLGqdEWy6Bd>Z(VJ)ms{%M=7f_~QM$#Wli z)k5?Omi#r;HJELHkNP`H;YBW#o&-P+cH&xjs=10$Kc>OJR}vH=adz&p_DmTW zrn+f<*D0meDCMv4F!%@1GZBzyBng(gVBeC;TW~1+16Z?_9M$k8+4>;{iT~?Ij~bwF z%-)k<@p9J>_JMyrpYttJZaJUf`0roqI>$e|Gcya@4^g6G^)|QV1Ixv}2!yTD`v|q& ztOX)FC9KEmAd+*NqNRaC-!Z6P2d+(!J*9rvhI*+NcAs z6LxqQapuu!mhYveaXPTrSrq#x#A+&DwCXiJ`O;?biE)jkl~5XqZ9J0br4Nnv$f_9_ zEPR2257Iub=T1GI+q4Nz_z?+x-Pkq^a^54x+}Im;8Puj(KIOSphs01oe-f5#Kg+Ie zxam1EE>93Eg_jW?sVZVkbyKsnWnwj9#x+HaX9Ua5sD4>%+!fQMnA_Wc>=t~fOAmqO zRDLw*Z}Wz@c|jN@!rO|MGdj5sQNy?*O+m;TKKhLTuw<&hM*_U%UQft0sK>K6!_Zl z=s1>Gjoj2-N@1FV{cwu2HNS3Nmb4eR%k8YBvgoXxCdxWIH{Bw@Ipd86IbR`U|=i@d@ z_Hr@TbgAxK-leW}Sz*({(T5*emK!jIG!HmSdtzP`64ugTVmnOoT^S{4r2wfL1j zyaROmNNZ=BSHSNpYG|-oqnrTQaC>7!>#gVr4msI>Yg06S|I}BMN1qlR6tk=9t*OArzPsJ^{>iU`IUM;@Y`;>^5nf)VLM58o~cL?Ll=bj=2 z54AHI=6r{7cduO_C)}oEl+x~gOg45Z21lc_UBC7|Opexc`X;Lk!f9+vJ@VM+m2XyQ zb~4y8B2e(DSd(jb(!O^UA26Tqr5Bl|_kMlzuc@1J=U@BxrbO01d-=mRg$hDh&)$G8 zu%H)o(Y^P(RFhxYq+%lNHy``w>=>Z3S*db%#_vn1CYy~^^qD#rvx%1(HK)j^U2&r!R-~OwpAK1_ zx_(HJuUsXX<;kT?zu$Nk#mSePywX=s+Kob67BMnft$yr})3kxW0KZ-4Ft}Y#>?jed z_Qy4ZTFEa7))g;@&!6gA`J*+as?GjBDNMON`r*$RcbT^N;Qtb%|AZyw9*vp8Oqbo7 zIIhcY@N};!+e%(Nj@vA^EW(EgY5ClF_=Uz(zf2<)TIqHoXQ!zjlGDby=aZZAJHAFA zZMVM$^-WETHLv$v^)EYiU@9_Qh1C_$-7Av9Bn{?+cWV=G`QcpV&V&iXUP$v{NfS=< z6;{dtSou&a7_<3+uGz-vGF4@k@=iRE<_{pR_z4lSytZ|8H6^x@G!Tn)MFM4=bH$Qf zh4H`m=4Su7w@cx&Ov6*l6e(Bl0JA}&hks)IY|ixiiPqfbJRWxeN&W+WtjHZ*e(Ro> z7$liTO;*K7j`i4rPse=Uhu3~Kv*b|O+?VhzYI0Sgj7Z;?gh2@JVOK)juiT(tf)e|K zMC`z?>OEy3w|#8o@)3blvCZ`05b|{k`=`tnY-(Eqv1>T7xt7m#YJ?^3xFD=uWTk<| zld#n#R)_Q4*e@IvgaXoL!1dr*eN|IP>-eA?$ZDNSobM=_u7kF6- z3eoc`ptm~9P=G3qSlwlzTCwpdfsZkX&7ZHh&0z+3@k+{aS-+vRdK`3c5fb=*;4Xy% zAL3@f>?GcGAXVxCWBveG1O0tb~f+# zZ8zinx>HCOPJ^k#gkLYNh4o&7P9i@oV#;j#ZSt>US&P`LUh|eDc@3Ogejj$(Fmcrd zbrg%`qTnWRv$+uHDZep-6u46lTJ;58zV*jjihxh7lj;^b$^ftMGM&?YkBVVDSX2e< zPpVpg{Au_`ruWaSZ&O2D#Xm~74RG7nix<k*QC2t>$KD2--KqZkpXhnm>80|a zWcOQZuYch&GH*T{ukWw-kWeaVY&ueOG6G*v&q*DvKP5*udrsO9QwrcwK-3>Q>E zBJG7!`!!&wI%MYYGyMePuKl}0tv7)unpCoc7+62?uwsA2T)OIBZIG`wh+eM5-@?8! zPfNQr&$bS|gwz%5S|sPZNg_qT1( zCDa=4WE1aC-3FMZ? z_WV(qPk_I%DmITfK4R-)fi_t*vnGy`JZYr;Diiv9PJ4X3{qAiehR~cq<`-){2zxS7 z$tu}Pd694U!N+iaQeL6q6|{vYXDKai&LN)YuIl#XjE>dd!#{v~9n3BxKK9>9DlVZX zsrb>EJZs(%P{bxjR;ZYNeiCJQ8Pdj0(S?;7D=<;ZB7+AK-Bvq|j{-x*V?|nuzwRyf ziyr9@ml(T{-CA3^H!XYHsF!I!)6bFe^V8jN! zDr742!i&T=7yGn|8>x6H&*TfcsLaehAN3GKbPY|l>>KdnSR}+g3u{}~zrK}a@}wjIA}uTkR!Ig$+%sh{t7n)LMzwRBdJ(|l zN@&QokW#S_WhtGQnUFZth75)2*@gl@H|qvcPla49An%;xsatpHG~u5?`h$z6CM21? zuT4Agt$SuNB7~7>1_cvyAtC)sAMw8HvM`u%;OmU+G!;;HW*UbedHIrDX2X>I2p(2h zmUE3$Z(vh1i|XC)ijvYl*X_YVTb_KLe8u%UceuBH2E;7{V%!gJ9Zv%v@NJ-m>W%0_(%MS99G-cTmAA!%iZ7eBKyfA z{{UQe4Qg{NpXar(wwiG#woCj07%Uj$pQZ8({oH;Ul1|dAywNqSCEmQBCQk6Ui&88M z27N>|TvFCuO{VVkrFP*5*Dm>cGONaO(BBZ zl`rSHQGxiz`ua|jLogpVbOuc-T^7HtAf+jx{8E=0=OpJfBwGsXVz3onJL^zZyReat z!&x?k8&yc@YnKm*_$c2*y+c1$m)+dt+&>dn(?~&O|;(GZ%y1!c;v0FH&q1!_)*24RmvGkj~7*iw4lQIRgnly&?pRCebT(=No0|}(M11C z8c5NbCrgG(J1+U#!N3zQYZo9rdQnw8;pv*1jpPyEBhUa zIsqIqYZ5)o>%9lt(OXsio6$>g{_gixxNwKkIo~@!Q5l1%7y|65&?O1wA);-bqj4rC zR0>dW#|M`Ok8DQ$$&tuNhDeKGsdS>tpjP#BuFb=EpWfyl$m#&&BzgY2_^0RcJw0cJ zPEX&RE*o5|^xh9G>7EiU@waB3%jewkEBx zn2;8(O5Chz@6IFuD}n@(uLqr=>+|7)R%b`p92`LA`Y~c4e$~);Cmw!29sskrN8?|2rqjMBn2=@Zp!&nnJN^o*X}5p+EunFQGm`ajRVk2 z;6GpD<3|)_j&RP6352+ABrH}nJ3MEJ)OV-kqB6SW%p8mZzG2%!80_#K?0-Ia{W`Hb zVX3)$$S%mvrDKm*P#kfZ>)0Tf!Xcc-s-WJcqV9f0{&loF*JX|Jq{wK zCk3aH%}ZcKDhVwL_|^RA?&T$!A~hk4dCtFAt@hBp@DG^+9%kQ#0OeCE$~@@sM5AoB z-XjX&iDRQ^WUQ9&MW~;CK_9*l*!^n7@CojsLLl&cwjvO;sSxrPTy%W#3%CSHd z9;O)jWt10wib-Q)T>{ODwdpb0?Axf%cWHj2DrCnk3bliP~;AGcYqC!n$M zI?ef>7gpTw{?JIb4F$e8C$f)C62`CJ^TV;5^8<~&+84ZhbvbyEV6|hMD%9Zn`HK}D z{>14|=4wTd>x&9j;^L=8T+;SH7=Jt1Bo=0>EqLz~#zj|O!)DV0k^ z#5S#Qp~Q>K%5>U~tknrhpcHxTN>VCR^w~Vy{yH`4@guPvm z0h973pdpP^F{%i8WcHrTF{N^tMl9m)e0VU@f!hL2*KYCr8P~*ANORX zX}T4^PY-#f?i7K$va}748zy;y{my=crYPC-k&J0p2$AUbGj{mioF`{Bh10WzfonK} zO@)2c?@T9)%o$VSRhoYHxHhaO-(Yf5ue^M}i%|?@BfcEK#^&>}LwE`oG@@lqOuZN= z??iTvbDr&vd&E&z-jmt~E0HzE4vh(|f2|#R-eULJpXV zJiaXA&X+tJhta}!wq_}W(7BHIjRwZ?t$IYiJjXIHI?j~q;p@!iZ)X9K+PkD`JK!FjIpZSS1 zDZ~xZ;=bhHn^=CBu#C5ikQWQfq3mM^9id&5M|?kAu`^jiqTwx=_4aswvrTfnYf5hQ zl6DJ5sy$kw3M_khGx2DtklR4Mn8+Sj642j>Sy<4U1N2H2=0P_Dqd$^ z;t*3Ehzq(4b^BNnNmU~YR__sEm8K^diho;RtN#_LH; z+{|%s8(@9*x4@&*Yf9>2&p&`0#-?p%|4b(zw|HT)Bsi1EAHc8<+HYNYMMhU#Ku3c1 z0P(AYd=9k5$3D2~6&fN>L|kzrnVFN~*yHgm$ue1~!amJ2rNznPh&hJrx%C5^K3(!H zT%|kf>H9A;`wO`r>1>{64~cCOObM`a6fp86 zny~s6PX}XN8ka_dP{k}|fL(3Rtk00*GFQc}=2W72Qg_@Utm~Ss1Ndl_sM1r2R61Q(;Nn2(k+E>O%Spukc_~vLg|#!W9=`N7 zw+p>Y>_gX}OD!!?t8R@l^r^^OOc~1+M<7UHz_|PTw^)(h5ezJ^P+iCSFvJPSp^Z&& z4y%;(VM%FK0-gAoxN7|1?m-(7a>8QI%(NnQ23-u4=_t}ld(nG}Tg2?Hmw){r2lkXR z*)>wzBj_Iq(JZ%zvR2|#kF26S?3Kz|9%KaneB258)c4l;xVD3#+SpUxl~;jRvv7zp zlGxw;paLhGp&Rzqe{~-@G7$1hii66&qW!TlW$u9~Ov1pw5cW*n#1WX{@!4GWw@tI?*6utU&nV=_*vP z7+M&;KPyMFU|fPT@z3fNZz-*ofg6;eW$CM<;qtD&oV#qA&Um|Ua%AYGbCLqrE2P?b zl7I6nFGDBF*_Zwf*`z)pM;CW8fcO-I7>t#neX{#dikm}-%XKXip~UPBQz@?x%EoT_ zCGu&3;TCh3UcN=x`Fr8_CMM9NmBPD7x>UIWl9~`=?VmcM;flXo$}F%S3-7V{Fp4oI zCs4eCQ14YAKzeYn(sMU^a<4ilMMm1_acD-KL;`S23WK1W31@ zB@%QgRu+XI0~2OP>0Uy@z{q`#S7_^O96Q-22BTds`&XVUYt{K!V}Y7ELt(moOo${s zT2F~C28`f_fCojs+Tg22Z&GQ64SrE5;6-!5axbqx_{z8t{k zI*3dfvTtame>Se8sK9vrlK!ESqd`vzh*J#x$Wxho)5A;qV2aw>|+ zcaYuYsT=lgP}@)-BD;#$+mG&fba!I*!A@A*-R%Ra;3W7DV87WPGq3I6BfpW=zn-zC zq!d{r>HjrjHiWbT{tGJ?i#m4x0}4Sk12w+@3g-R!n%%w(U5iiNlQY4_0<>lV@zW6rtwbic_~is(^lPc&c>L6jK2Akw;L!+s&DtXu>pPsp`Q`v zY`at)H~&eX4h!?S1euJWJ&%J>2fHPss}n}-$iPvniJ9-jsHO?q#+N4fe)xNcW#act z2S0UQY0e?r0QD^T34JAj_ut3mkuDTMuixfx_MG18d@}H_irF6D@%Z)4GA28hU=K5o z6cyY8kqJ;sXL5B+J4W7#OIfBEZwQ*H3r}q4;fw@0J$zuO(Z0*9Q{eNMphsORbDv@o zMXOPb|L7l-^;{If%8A@dA=1u{>iw-My}5eJoVU!k`s&8(T4XEUy4b5wKd8x3*4FC|O z(I`JNot|QafKQt9A$xM>^7zY5i zVBoAKGdV@tFz0@erZ(jMQpVUcHZTRX>Wti#R(MVXTqL(h3p>8kFeGdPCdN|^K1o$g zNjB(JO$>VA68E>+QJg^wZ~(Jbe^a|j=zYbzwDWn1zb`_>)2eev+SsOBMX4aQ(z$=f zY~@=#t3@lz$CZt5)jzqNH$c3v`s`sBKO{zUc?i45F+&f7#sY2o4vWd(*8Cdp8@+#e zvgd=tx+7gS{O~+L2R%j!keF%tsA0%o9b;4l#N)gqV(@Eqov?>!PmdK*?zB?qUxw8| zuujzf6O#$Tk=?eTJ+R_K+}ZM(Z6}X=_Z>c~zsNq;`hX;aUfOK|DPp;aJEgP{a%&C& zqta-5<536`uCSU<3>~UZsPFo&?+OjE9F+-Cdl^N+AbLtg^_yWd6U(YPVs`37&V~Kf z*IX~1i=zP1_7M}!72c8qoo~M?vC2Tu)v4)!%FCws?L2J>r*n z2!!fNyp8aaF{IggiC}eiSY0$HQso&4k=O!WjS(c@Ljc64;8GcePy zYyDx;u=H~meRXGKqGMk^`$p=py^Bbf8^9W8LZZnnhE^c14}94xq_VV)!^6^bk({Ip zQb=O1q?BdhK8QG4dol#sL@wj5AiT6T`YvC)M0^H#9W(tlfW8dl&(T%8_U;D6WmuK@ z^hhAX&nl5S*)z4xq`h5O-{h4Hz76jPKowO4jt-0L@C)}GSA=HK3?zv{lMk)a8;3R< zdrEg%#6(}MB0aZ^_+5sI{FN(e_?HPuvMw#E)PH2gC%%jepVt+pzPoU~GyOvTSOjsK zt)>bIOpW9S0jm-A4g_KD@P-b22AsYG{8pkj@gcWT#@>H9nms9j;17{+S5b3?0}pg9 z0E{Kz3pQ4<6{2W)d5xR<>nD)Ay^E{cR|C*hREFaFA_W2J6&IvapQphWT>M6zw$m$R zo7z|x0WPUprx_?Ysoy(c3pyyxefZlXowN@wj88jx#QfceXAT5^x?mvR8Q!|Y&z1K( zmPOC-e#Scc@>Key@rfpe)&w{zKk1c7gkYxMm7&Xg1<7mB7CuHS3ZKw=e}G%)H`Hdq z{0iDFJa1KZ#{^cD8^9-Y=r#E8I?y+5!ic(qxnOsJusaliwazxE;{{~vgf4zBwW2fq zwwkEPPwdHZowmz_!<fkpec6K~jul$U4#TEr(T@Dtw} z%)QpnK&+pmYVdAwo~e!5s$z|y+FWdUWu0V*Twciv+pbo84D7ly8}va}fsWIXS-W|S zx+{t7M^_o?tNf@i?$pIGS>S}6It|b&G5*ltWI|QIMQ}`DQ%RJ_RW}L`-M4*aAUnIhuSIv7{_;<^NVG#~dU zH4HC)!j!^1B)z*g3)toTaH&5=xOkXzEBri|JT>^=bnm)BH>&kH^-!tS-!3d{F&wjw zrC*my_6133YV?t*N`>>u8n5oz7%v6~KlW)5_=?ZhsNj3S9GD$LT==>q$YXek<+DfKm zousJ`Ef&jpE9BBFzsi)s*3r9kUgb%U`O3y?=Z6W}I%6fl zrMyUW{(GU2Z94cm=5#Ae8okDu?-^L_LAUg!@thtuH~EG{?EZ5f&@gBt_|RLb-Ujv{ z)lbgw=y3l{eT<0btEc-#TRq1FA$iS>e$4d~bp*{5vq-p0X~gID3R1B1k^OXi_m|&o zbZtg%F8>2iX2XlGj}I=@%_QJf}_SWXP zS?Wkz_kFU?V6DNW-DFG}l6)D5b)q}Kp!vfS)uW_<*Cv~_1^)%aDKS4$|B!enHCcSC z_Z-peYR2IUJH71rwzjZ*Y|vV2WCctpBy`Swi*c$3BH!0iT#rTI>e6UuVo+o&^TUUg zJx}D6IM5{EGdZLj>QQVxkI-8}G+v0Y^?v(&%#j~qNc-AF@p#T?Ohe0)+E~SE_N<(I zlH0y6(weW6nTYksAY|F#9jWNksce%sgdcPSwS>`5+D14FaJ_(daoOzbaRG3o0ZxCc zqw!(j<1fzKV*BgH2pYMHvUl6)vt4)@K$Dfg_xueV%hnT*$H$L5*+zf{FL@+BV@Yvj zrG15BWKW8rwTz@w+q_T0*|OwEZv^(CuLJK8?Qrw=G%5gz!nUuwoUf-5JvcON9Zl3o zamuFKc0JnyZU{ki(?bl_kxokm{0f^nT4q6bmO$YIrqk zRU9k)+5M-KCX0p0VZ!eNw@jZTpWK%r20XQE=CbP;^J}yB}&!qo()IO-YI03SAQ3q31@i~B2!&c z0^;=6jt!$oD~l>+hDugiS3Owtyy~Pua+IA&XMx<^YTFaW`{RvHVabQ547BwUEUE(S z={&@TM#rd_9ZJbnOYMmfK$jK@&lLnt|L`=%PObnSp|ofZ-a_O**%Pd}5XmOPIf-5O zSD{zth!E@pPRYO6WjczyCx%HX=@N0oGLWXcJXNO>9KL;~sXfR>cw2(SqQi%jRcXX& z0{zNvBPRu?FF=|4H~|9T8UsQFO|{9*D|-d_o}ufHH9_CZXp_YFOZnvKm)L`yZsM5Z z({R6y3pP=zF!l@+;@^LgGD@oI5%VnR@q5)``5t&h`AE!5@PWjQ`LfBx`GZ_B4N}*#&W#N=2&d2)f3(q>wPG*hTYJk}&A>GVZaxt? z7*@&LOR8CEnd%ru6G;+ihH7>#+;+b?$gq-rniu^Ge3JBe-hV7JQ^;yoENc>DGimm+ zI;kpMbcRK|rSXB_51{c~HR~5dp;Tn>aga;W;zuSRb7&a46_^8u(N&tgJKjg$Q^Q}e zrZVc8j)fIg`qRAiJsr!Or=E;SURsJhog93LVd#Ja4MmaPsbasiTwf*lM=?Iijcvr( zD~|CHp?+xxb)~qNd=2bCPB&7oCVpx2o5dZLCueNkY`b%jZXdjxhc5HzIFGlgQ7Ues zvH@D8zBk{bW?Bi$g-^>obL}|}z8*SiEqv*DCC1?$B}R&UU;3nW=n_+mf779tM9xV3 z*IR4tUlTg`G47cdYq4S|G^SdlzL{;@r(I5X-iT!d(0?qj8P^UgQ8$Nlu3_0Rro-cP zy*IEXHQy=r^qPVP-Z=K-NH63vu2!3m@pc~&0D-8QQQodv@k49uMQIHS9Gz7R6t8uA z7dQOCPm2nI&>QuM`>uv}7SeF9ommhmu@-1uPb=~4S3b}j$ske1G)KDN_Iek9_hoKb zeGTCL`{H+1(ITvYejM}JZvCY5WGvO?M{l#=5q2M}VlAUzA@Wq^gV zl^nu!hMq#|$e6jS${S6!$@X5R?YhII7ySwh4bwfS{#8iYG{MhvF{9o#M2(6pFNT z=h@Huzn^<%-}{}}ANI`tu)kfIT(dG+Ym#-Y^El4m@fA!L%W!5_Xtlx|;pslO96`@B z#Ggy=-PM=c=RZkC!rX7Ls+}5xEGtdU8zC3OF?h6NE#s;j8De$I zph4MWj^br#5UleLrmuOw2yVzjE-TI7U1zQ`-iNy!KYX&p;^D*m*YKQU#y{?pku7zj zpea|2=)t!w2Zw*;HX8IKr>DDhhfwxqX;+%UcoA(_-?*qB5%aq#ABHOx1-YWmKM6uQ z7%f~W4NPGlXDRB_$=44zgC~kYR9+6ZMewY(= zLOI3eKd$dM$LH-%shrS|^Hw2S>0uIT##SutSU;WLcXG8WpFlP0l)7C%;&u>7nHRr2 ze?e7?Pb?&*ccp`|s`RNaf(20-{9<4QPpkEDZPg#rpyNBg_{4PL)Jj;iw_JChf_IOJ zXhhC3q5n?19$9J47*E*?y8M~!Qqz?KrejMS^NJ?(!pe;7tbR7zoGNR7(bV^F5)lkP z61TFl>fW#G6^)G+qS#5z)8p>Z@mCx@CCJL)M4!{G568~U7Q>Y`O;Rt3o{=i@9JeNc z^~~QI{cuxjAeM%7wysF|xQV+4Lr7c|1>9 zJ3A+1e|0;&;A8pwlwob2gow4whW&0w=Q_AiMghgIV{6opgTrS=$ImoASvoZ@TWT($ z+^&c#U{3&!Vbd?lF_ll~d#M2ej)Yx$*_j|jrIfcdJFA`c>AUk;^q6RZpie+z& zuQ%X~7Yz6x*qVZ2T^JMWZFpGdmM8nI-Qh*c4b7KYrwL<;&m$)nN@xe)al;#%=$bv# z|1mmP{>%M9#q~dR)WU32lj=g=!GD!aNOrs6h68X(_UEFNb|Ku%kB%}=B2;eY{nD@8 zJw`alNA=Xmj|J1n??viIx>?)`WgzLq(iqO;N^^+jIHxXX~bt{wn@aX|f27 zZTkMD@oHWQ*bSomuH~~c{;G#?<=~NFj-}~-Cf)EwunsHLQewk`2XL}5CDC0%Z3E-H zjUYw&MW*`Qh%&%40;DE$=4RN?U84O|LTV&={@fme(7yA9Vf7QsCv{8o44(I7jqi)7 z#zk-K&#b?g_N=%@OR493kfsybUCr_%w_T;+b$23ali#}Z`AjIHru6i!5+fEZdrxgE zSnJXle>-GMoK||9^iotLuwf5AF+NQL7)qr#z^fZgTh>?iNdkF?hW84i2o25m$usSl z#2w&j1C&n5m{jjm7OQ3^#l^d-j*^g1{R!j8j8L-rE^BaBKI1K_7D+RLaH)7&5f0=T+AAZFFQ^WVOC1M6 zfO7hYv)%@gM5pP%Z`sA_kCasRP)tw5@ih@VyOVG{p$o4xo;6i25MMY~tIYF;38t6o zpIdB+N%;jFk3F&Or=zM^(^;;|6T>{2fHqbaJAX_d9{RqvABstjh@l>N&^Fl`ZZn)$ z;Ux~t{n%C3AX~hpjBk2F!!JJT2p!v)0)&-uP@ z%VtBUqI$5^u(FnINHi59DWtupSG++=fH*ZGCdEcU^`<8SGQsiKcls(K^#=A10yOyu zg1>y^PblP}fWTm;7MC8UH&;yO$D&;-`V(N{)*PQqZ-&JV95n6jIo~~JPSoR|SADEE z#%b@s7Il0<^%sCm37ia_7y_vD#`+-L!u7fV;*EYqH0xC4QaBuaM`y2f33UKT?Qob~rhGK88?<6(o zftB~auD%Y$k_H#P{|lf_bdDa(mMRuNp_&Y*Hs{1@m1loZN#g%GJ>e);l~~Y zP!YOPk5IYo#4oHS7MG2)gYk!&!GY_h?ttI%USgmNg7nVkA481C(L5*Czkn7bqsdLq zP^B-Vpfgk2RrDr^>D!|(+=c{J2p(PK=Ul!lwl4Z9EKqJPEPM8U(9T9Qd z-cnjvpg6ZHD$;Uo0sT?$bD}|H8zgEF@%<8;NQponD~7ihH1 zfPB|#&|r4o7C4Wt-jqGpzN5s%_T6)w2`;Q{T@P)~dtGQ+PZ>r;vL{TXo-YxJa+XwV z*V^y7j!8=1zvfk?0RuKZxkPJsiSn~n$s&4Q-jamAp;St{c+#tDvUN!JuDYg)C!)7j ze}!dwLe9tK@Fo3~Eoi&z8zIAn1eaBD3k|^~imQtxFn}@Xtg};ngda*0#IuLl$q}_A z7?JfC&?d!oKkExV0StoAQx4y_3GZytP7YD28_N*Zq~ZDc{;XpruGnIF-VC~*tGu~U z?LKFW#})A^5-Y>QMolKtMS5(M9UJu5!k*EI6qOA+%KK~gQRK{V(Lk6@k#g!hN4nnQ z*iX{s(0t4M{8IWdED{K2BsMo`kVQtzI9o$00XF>koA!(mI`3Y-fbeprM~17MQ9F31SP_UOB13KUOd|NWjNW2UoS=4;uV z>dz{uJG)i4gcGnnH>NB#{YFj|I>*?pB|nCC*9Rv`Ll;!{_fr# zVrJ91VYa>W>7lLt=AG2#&!g_ma6XAS-qqVE~WkP$VZ4lliwj~K_kW*H$-EsEO%mtl>(m*Y8oiq(qw zq;bSgHyp0cBiR$NV;C8Ijs78warYE>3FSj0*VKvAORhLNwt&5RrEEAKWJuElie2Fu zyN{Ze5WOj>G$6Dd?Rg>SK&DOQ+q$jiQg&zs#D;M`smtKxDa$h?EDYACQXLfU+K3?{ zL&~sF+ejH6YhaZooI$kc_p^QtI$Tt}DG5ix%X;}0o82=`@GtltrxLwX5A*V<@)aR7 zSD=pwCkkUu1%j!fzpx&ATwwj#5P0ejA@V>4EHiC^9qErCU|fo?gK=>V$WJuH8SrvX+jEt8aDbf~9cAfU*#m9W6L8J}Wm zhY_)*#@xhQ!)(BsTH#>phD95f_~zSh7Ctj?Jwzns2X@abAK35(N?FPY5hhfM&pVl} zuYJ$TSQc)I>zz1f4%*>;NwDn^F8ybw30`)o3(OCMSoasQp~po@`=W4N#A{k*sv4el~5wSF5~| zhCcp4s0*w}q=fT`R`7;NVT^AN9$oyQu#Dp3S^-qM5HxvoGd<$uhnJ!+l_1y{UK0CW zO7Kk}vpH$I@+dW1Um5db=u^!1a3B|z@`3k`<}I1B-x6f8(1qvapi?qZwg!wZl`N!= zyI%ti@k;jJiH)dX!($Rx`xR#-+=pbrhRE+FjT4^hX6s(*cI0~w!kHS|f~QZ3 zAw1PLzEzYNn53kcy*r=kW4LR(qA*?wm*HU`?RbALQY9lTpt(V>XJLB6q~(xU^gC!% zz_A!>@ZKO?J{Yk7WC)q_%Eh-m794%>xS07AV6PV&Rh;)UA5kq%VJ zbV{uGF91ZO^npj~mqc%@0yCEoFT(7UxY2xyjh++pqft;%&M$5{Mn+;OqCIBpml5Zc zT1u`ypFQ9xd#o`}hTsGyy5(&9H;-~BS#}!vJNm_fsR@I{@n{a|H>7zJ;+#ei`vHoj z5m5UbGaH3BRgS)t{j(P~4yfqCZRRWE88nN2OoYyc|J^7#sr!)zjRJ-;t{(*0cD9Y} z8cqqs%C5+dVsSx$+=|?XArb_P%@;f@n{s#zU*(SU(hY&!tT@24bd@1w4}v9)B_D6g zAhA&nOHv`1frY+AVlRv?5IHb}`v^lQSe1>2SGW<}jIgp|l_8->f639z`sxJfxe1Ev z__QJUZqC8&Yu0)3)AJC~^FdA8_t3rzk>D2g;4ED&prlI?)}QCw2P2Jvyb|hWuY`aT zzv;KpKy(6Fn>c7xqY5R|R{aam z`^|OVQ>LPQzAKu)y!G_c5m@>Oz0 zevO42C8S<3q|?d4eB?!$GcA`n2TPoF(1#{S^Dqd_$gKbI_HeGi^nhUHmGy@j4IKkB zM$v8OSmLw~8fJ6nWYZ@CNm7`Ph@U=_YyT-%c69eT{^wy-xaw|91=6}hx4vt;Z%>S= zJuYC|At=C0mEFem_w7HhWUA}*a6%T}3nom>;xGdTh$^Kb?iw6Bfy_ZO76j z{DvU07llRHZwFQm>AT$;U!GKzRD-(3S(wcztTHh@m^SF1Z?S2+;ZR#YkAZ!wI0hRz z*L^6hf=5p~5xjWU$z#KXu~|I6RupzkjVBrm4I>RTn}S71%#X?+Yv~ReKrn2{6;wob zi;1F6T?W+O_p<-7$KR0bjSeQ$Y$%O=dSxn@_|x~YXidSY>40#T5~r~;Z3_I0LVQe0 zzm}-eK#XDc9UWbd`PzAnNp@SID={u2&%p7%v%r;K7g$y3T0(uM_M|Q6LbA0ku}0=i zYVyL_BRWzmKA!EN4!5-__9vpsOI4W~A-R8oFgIt-gGxnbG`O(!nvikF)|fm@`%-n7 zhVC0}41WRYrc^QVhaZcpKI$$zijyECLPxJOY#4S z;6SrY6KtHTU!D3~T`mhid}~%V#363sBInpI!(JVE(f_fp&hN7MMt_sFHM3*dR>U9v z{aX3!d`8V?VO`v(#XseRcF|XynVI?`bB2eC294=gJ)(2Z^&b&!?IK9a2dKiYZq0ua zSuTldwuvYCb^NEIWa58@NLHmaEq@T4|FL-Bqn>R(|D4gGX(G+KE_~vDQ(Sy(D*Q zI(j9CXysJg#o4mkmw7XZu9OOCM}L!Fq*449+<+J4%JPI#pX{nrd5J<#w=`k>zT-tU zI*gh{H-%8E-?nI{M`>k|8{zAe{k~sB@4CXjRVmc0fqCh_5Rq@>uBHp3vg&cKT-h2@ z8j6Cg>~M7D#8qx%ZP8>SEVaAz_3bRIc@Gs>usa|rfseU@J-|&+M#TRXe2ytGm;^7l zDY5d8F`$xi8P+w?>1~H`{V@!ETmjrQ=!nN8iI->uXurKxEP?$flr=uJX1R(g=+@Oi|d5$AId z3%evUb)33Db=%T@Ku?+L`!o$5K__Jq*!QkoLLdC zA}Td#{i|nEde~gWMD;taEAgpe)xl=lAEMMoCW-W6ji%u0mEXI!)I4H=onAkOm)BwxVWxHi;Wm z;C?=}d1V}FUGzt_KV0V;SZH|OBr_=rZTxon_0B#C6P}xqg#oPMG{aUr^(=YSb zEPAgvGDfM?H{_59$ZTyLeZ!wOeWnS~}_Feqp5!c9}9)VBf z0$s$pZ*te_OMi9c`yhEnrhZ+0m*ut~~$0C{6L)aaig*-LKLC{;YdaiyHR zQ=+i?iZGvdzr?bmfebRhoADR-nV%>dnhE$CkA+LpkH*_aznciH!Np(_mjie&+2fae zfbqt0NUq9{i81rYcAKA!ICwc8pWB0EUcXZL#bZN2!(Nsej-SWZvYE(UQRjq&Vj12z zs>t>XVcg;#d=N}OO(>@nv<>~5)WytVY}*X8z5ia(%ZQD~S#t>rzS7)e(waO|G5>G& z*qF^Wt?@_X#5%ZOVVuJN_B5&L<{9ZV=|;`arWBVwiA_CQQ#U>N^5@#BcO;dkhcv+F zFB$MUaxEXTF}sv`c6aY@nJ5>0*nX^!d;R3eXsGoN_{wKG4>NyoC;ek^<>V}xjV+f` z^FbipX3x4%AQjohJ0-{N-q(aWu}7&`DwV4DE8p5fPX9|7dK7Y1`DLo(7brAY>pm)& zpibcBe>5Xk6u+fbBnq6Ho1l_FUvVx2>Eo7Ocd_yGahsh(PUmc|o@=UYkBjyzBcfUZ zbc~etCR_rqVQ~T<_+K#x1j~P(eLi`fAiYW_4OVEi05|Np}K_H$L9t)uJA^GYf>YMJ$(bNmI-LjPA zfuX{b3o+r}n$8O5>tu9vD){sOOr(y%EOmU4TVk`!E=5CQAd0m%KC2KX9TvTM!z?B! z>D=pN%7iaT<36}iUW{BYYDL*#r@i$|6yV>A(D^EVhCeWAi_vxKo!nB4PfkvusEDS; znBDvZuwq-t0&bA*v!}A+&rHce5zcu zeAz~Gm%O{an#GZir3XksMv?W;^T)D`e*qdVs%Q@cNz1ao>EIX`tD*qoSfLZNOth?c zk;#&eh9>5J!VMj`lnRgM`8r%kkv_kq`8>;mcz9mDdXqS%rT?p~V)99xl@%@E3wu+S z9*@9@p@mYZBfshMCOr$mo-2q$2(dJnVys+9_!nK{$o3!~DY+Fn@wE#Kl#Kb+XYTEE zQ;wbiV{6F|gSYvgk;S>Ff(%KUY?4+Lbo`W2Ce82$=}H^|BoPzJuUOFc51B{tr3F*$ z{9Q!hv9(Uw&s`$}1L_ENo%I*7lT|R~2XAd)P@h$pkz}kibIG&2i*lT7vR)gXr2FoGAH2xM)#(T#3zaA z`3CbTI@nvsmoYw{ly$PNT%_l@Ey<#{H(FtNngW4($YDvfGpL}SixR9qb43#6k(uB| zH&o)x*4C7!7BOJ$g1D)9&m?Usb2U_YKcp)eq7P_SS5PyDA*A2l?2;})VW!GSLa)W?J}An`dc6p0lfy}5IZ_3QRc zU&_;H9VefswuS7L?|hK#Nu`?gI6xiEX1;xQ)HF1p?%%z0%6d*YI*L7e`GR(vKL8Y7 z%YAs@!1Y*;6JxRd!sA@<6WmOkgWEZV=$Ia(E;~3^sBTRB24Mv%1MwfGSCy>j^>UAr zRtD@C($WjmjCmA2i9maHA~!EM$sYrGj^u__@!9IQJ>*kI3E(rmlRg5vd<J#}Ecq zCsKASR&;G|K_BSk{wzWKYbOD?wfDH5hmOmZUpk9MX0&z4Cc5?2@Mw;E)*3^E z2~GF(=jS9D?*?(P&WUHf)X$#aMo%g|!V?JkIB=R)?yO}YEuf|S)j*32I?%HrBh;8U zV+3FAOjBI-e8Si3fh?Q-g^FR~T~L<&Q%#?gly_{pbg+*KWz@VFJF*dxY<`#nO1j$A z&eUU>1QtdN&CD||qJ$l@1MnD?T+QmfU@5xFK07yM2tRT1+uCCI?Wq6pW9gb}a(z6X zm>FXZ2u+H!{{wmA1WH55v*AdBUek09wri`;UUM$3akso_{oxg~!dCv~nLArw?bBuh z2z;f2y&3vE;3Wyu&5mI;4<5mk*OG?wwj(_HQ@YDQfJxn8=XAqoN9S0NO}5tr8LBqP zYV?Rf5~WgX{&R2J?GoPL%6Tb=f}z(Vd?|ZEhZS2$qIadQKw9G1;{XxT z*h|wNPknTRhZe+pUoQ|bFBb^p%vu`?L$A4y!3IfmFm*LNt3oDra(LuXQDQo937e9| zB|l(>iwR6*#m&^l>lK!trufnzF^y9fU2sM2czn_k!x#o*!sPHe!z;MixPeGHnw9Jp z?8_OAc>^u>XAB7p@}EFtZfvuZf@jVf(KRuzZ5>DkJ5d2MR~5Ki;|e@`%$wqlF$vtj zU3H6bL?c}{vx)kR(>8O?lgoRmR@LIfRT1SqP~T>haL1XX3=h*F$vi>;YIHY66JMDE z=>u`NscMh*H7NS|p*+Kyv{QBFzx3G7-;(r?pDm{TXzeVoD##^Rynm7De!)>GmhV))(3wT{I+t3RqHEq-?YMMcSSBZ)q z6FO#TzY}dFpELYE;rKnEW@zF>;Lm0)->V_c51Z9}w~UiS*m;X}O1YI4+XxZdZP};* zN13y|=u^u%Utw+QBp^{t7js>9w|AVBiubmzJ%NUcil|YiJV^jcQr54@GyQ{B8db4+ zBJVJk&QJZfH_-q-Q^sWV@T2$Rgm2XRDpPH^Z9JjMU%T(ASlOGKo8dv~MLEA6bLO7( zzlZfpnK90R0@9eD;&<~_Y}=^`9`!(X3gk-}F2Ds(3xT@eZ32d1RUS4U1Na9yZ3#_g z<|7F6(}-alpvTUZ)F(r(WYWvXo8ESocWmi$cmzVa8F^-EL^-sUrjCn)3Bmh`k>SBu zV~%JhpN8-%7g=#qfXN+;m{(!$*ceBHt0npH!)`A z9@N#sSUyoInb~CXdVRPkFjXgUlKwgH9o0>v&7q2JKRkx)%G*9A<5?`zC)brna8g`T z*kQBKU;kD`Vd1mUoc~6ta4_>C^3%~Zi#V;El)7IJw!e%j!<-fv$4qsEpe7YwL_{&P zQ(A*Xt3Pa8lBGoymE_Kajb%pyxW;A-DY;eijnp%@vC4v4y+`9UgZd1su1en&aK4qd zE8X9<|FTV}5Yb2?+&NlSdtg9gCotKQFdyd$$Gck>{}2bWp629=^JW{7&<_;sJT2Km zCA7K1?8zA{%mQWC%@ej$;J)sT&IA2bi&14CUwak<5J+s8(@(IkfowPpdvfl8Q1e57 zZGz@2J7RyY*zBM;DHVgAqIrvPTB@sF2GHEOw)?#352bAHb@tph{UW0+%W;#r#yJc_tw-O~k{`}6^h@eu6b8nE zsl(BPulF@QpFzZP)qeUwma=pv2sVpF|!RKNp50^XQ6XC09e@fT91R?!t$3*rkXWS~+p{PGoE4lDfx#tP(n6~UMgS@f| z^=!IqHA(xZ^L-E1#d68PKU5(C>$SO0un@dFw={1UwEhB0`$~n(H7pWm$-|qp;s?!F zmDnn;7@=92iaHO1lZn>zria{?Hvyy=Yqizq%9}eLOH|fj^7&B#Q7(xo6eRY2r35bx z8bM@wk!*IldqvPl3TzN>HO87jMB3xnSQij-m);kgJ9Q6Hs>e;~7qKsxUHK+woK zwQ%fxDL?qJKJq3Y-^%`YAk?WFZZvYj!ydHiFBr(4CTT~f&MhZu{pz{uaZxkzYaeIA&_%)Msm`zojPOMGK? zK{y&n9z@tYI6!)KvjA+Qh}njx=W9 z`b|5S;pQgr-583wbUQ24^l+;jO0;o9a{G9?gN{ROKdknE+X=}S_hZNEyrnI;oFXOH z##cQ{FFcWC>ny&U<*1N5mMd4C=w_<>~`b^tG?NIIT$teR$i6kfKSzMeJD za%?23r|7zXEFN0w1cjNb;r=NbRjEw+^YL5E!~gl1jT7>#iedhzd+_-$qTW9}o!BPB z?f(&iOI6H`HW~_O`36&fJv!gU?YQVEc4taYNCHS{Ih>x()D?Vf#r+GIrpkxUSi2DU z=+WAhA-z9RXzfVGV(;XH0e*+2)c?RLuuz%mz@fCbXk5@88D?a79k0eD=YYK*mw5i! zr(S05Yfh4e1ImEtE>CyWv8_`sqH9onz8%fy17t`H1mtWJV$B)-UYyB0)_>Tr^p+)= zp84TD`fM=KvgdcFPGXWJGS2`e`S7UqX5r)Rj-n;;^?#wQOen=DXZ2==O;q%>N3tT% zUO0?mPr+XXiAZtoR?*ViGCwBrF|sZ}mf230mS!0COf>2bP~$HpOXk271RaKt*#?qI zkgyEi4?MfJPpI*Cz44t#J^Sba8EowtYROEM%=I*+j>7T3@z+WUL#+h8<0JtXV`wvM zZbp@LvG8ry#0$B0_rHMhFa59Y68QE)^*gwH z5C6ymIL=LpDzWP03LmzNrt=X3+e?#zhaY&-Rd*``7~UV9BORVeIt)($7)A(Q@|GkK5oO*IjDXk~w98s$jEI{Zm&R@%fm=)Z31eYv;wo`7Loa1+9@)KZ zpao)B#)o(MpY^K;?(yvB>-rOa=$g??|6mdj*;3kLODrgh<~S7008fMBf?=K)>GUMVkMuK{v^!z9 zZyH`YZopeVwG0Vj5nljQd)AcJ?<;}j?~{ivq^MQ9Jc6*oFKyD(-o6P>TmtLrf7r06z6Q$J`9x#nfR)GXr_$xqWun;0oZVe>GFzuZGjkk#ip zP}qsYe`Zw$8eV|&Kcg=`H;M8P-_S@os~OtSNT6@pIiW5JQ=ciuvSJ9?b(zh$jOz** zIW3)WvR`J{H=;S^M<8)*YKvjO#otbsuV#jjxzTS!OgpuuU(Y2F3mC zu>y4TldZv+ru~BAU%;cPn~X>Mt@U@YOVu2MeQWbIGo!!?YeX$Hs3}^*t}j*0;xy|a z_!WiXt%^_$uPcONorXV~Y527i`mR_o|I1|MOlLs00J0neO`GWSrC8N1c+{!soL{ebj{>ixQ zA-O1Zf-Ytm&YZ!rz|R{&>ksP^Ih{&1N#zckwx0DQU0-Wnr0o2l^WNJS_1{CXL=1hF z_t70^CaP9qIj4%MK+U9i@62?31!Xa;TyWLLsm)|ECA?@{GEzKJBliX|t@ZQ>uvD%J zk5Gh%Jw9P@-y#&`(;D!LsZHNR+~jQ}rRDd6ID-h5=q=dU=|(H~r7I(SW7f}k1CGh0 zXpnnIwk3-m(mvVv2#mI7F-)CUx4O*+Bkc)c3>(>ERwCvGwe~r21VsUzq1RLHF0O4* z1<*dj-*b|0*FW)OM1NH@sulJmyR8Tflh?z=x;W|OU#MTf5HyC z=au$UBNB!QE;#`xEQ%gp!<&37N38x_X9D#&`%s39VYV7*M_)NhI?L^2xSdfNH#_nO ze95Ec^j<5C0j9QyDhBfUPjcuE?G@usD3f{X<2fZZxA4g42MNIlL|dW9X&A{x(qkUp zYS;|nBm{PHBgBcE`7P5;kwZ(1fwk6s1mnIv-CoRh@~a0Xr28`$=&AcY!}p~8c08`F zA9bcDW0p=lX8o@8nW&R~|JE=wa%k3jC#=DzEZX0jauF35(Vuc}I1Rh^FR-$OxCMuP z&Fp1vP|q@pa}sR~B0C=Tfm>8c5TE#!h$u|F4aHeHPX_)D1k>Z-*t{Kutn)A)iMniL zD!m0BpSOnNADdidd`u(>DuBP7x;7c^`M!1k&@FpHdG>Td z>pyDuSq(g|^1f19gnyf%kRVntlT*Q_sO{uAEOF7a{fH61g-1nL-QGri^SV7RR885o*)`E_;>LT`s%-2x-Q z=pyq>>BP4PRb>=#l7Vw`BcG)iw)*J}{a_Q*8|u*r!;{kSj|-^?Hd6PggH|WxJ+oXp zzc?E=p6l_PaFY5XYyYgI0`fM`#I$}F|1W^2d9GiLcEID+*=iokgid=SBa4wq6(iTH z1F>U9agI+7+R^d6e&SG}!JFqGVt^;Gl7y?iId|>_vw^`6Mm6d4pVQ+;j5wNNg4O^9 zJ$~&(IO19q+8p@OeENp8`AQq^^xa*W=sU3rRZfk`As<&uzhu2`ZF=o3Tx=9x65}kf zKYKbW%?r}~8KP0dobQu}!@*2jR8|mQrlt9VVNi9CdKTE?k0m#%<0h2i(_L0j*GuT? zr+u&B`aGZkqcqfCBr|MqF2?iBR$0^fH-mMXC%1SG?TS_F&vZErJz`Yp!iyJXMZO~a zdYnQ7zCPnVa8PVG4PF$KG5#*M_Dj**HF`ZI#?M8qphO63J$)O0IG68V}a{n#{$S#iIIV0JkTch zI%|z{!&bbA8e^r}?74G-&mG;>H>cLSN(IX|;k^tlpAwUw<2yO-+ScmKpLcAgZAtkC zHwO#AW2~nj**)Vz_w$Hap9udsEeD6zWwD`_nPqnN9p#CR4CA+J})GSRvsMqcI96(UDg8C{04hahm^SZenk$5j2N$z(!0;ODIAP#r$5;&(@ zv-^XZI~Mdj;^tSNV7Wr%!P&kHZF5qxSkRyN95s|rj=S>n4!#op%#ZF~YrJlce~onV zuFEuXvoSog6}I_3S;;RW!-fFd>1P-Gp!_o{v1Z|6CoQgI2XZQ?5+f>dKBQNm3FrR7 zE8#$N5EC&6zhJ^xiCf_O0hxIR&(l1t(Shjk&-y@`f^xKc`QgGx#Xid9a?D^`Z~SDB zPKiv0W|DXBCNj8@CuGwqN}j03ejG+wpE*rpjWI}1qhs!B^8PSuGDd&30D}sF<+NL7 z*}^qwcAoyDL&f7cqv;+e<6m=go&I2zd9wK{Pv58(hiwl4j13XRH}AtZvcjc8T>s*f zkw~YsvQ9GjEMrN_v8Y9N=3FdJ z@wHmP=qoj}z55r4D{gYH{m{&kW!7{gs94-i3#=VaW5S`tKw3P` z&VF5t#jFe$PkH|-kN>A+{@)kMQ=NtHo=hK~!@9TXC9SR>=%kWT`M$3t@)Wk}XoX8M zHmV4Zg*fk`@1W@#Wq06~IU(CY_X*L&)_J>-K$MjzLC{A)@5ipA;7`Wc_S{WkqRaU^ zs8}=^1E)z8?oHqkiw`UacHmvjbyDd>GR%gDS5u(m%Vq8`%Xrm}?|R04h zK(aB?bgHbrYwnTNI*m1Rxm-!dK@qzE8YXeQ`ekct@fXo)h$EJ>hhqK}0Z#vwY#+pHQ;_gZ&Jt$v{-c%oH(9!HU)zQL`WD{b#2(^oH1sa2# zMnm|qKdWfEJBPM9L2X!a84yCE{uO~7;)NoQMhI@A!PIV*`*th^&w8cOE*l+kP1r~j z-ggtW)E+nm6}^t$nQycYV9B^4eIN{9jH2mAGe9!zX)+35`2Jesn!|&v(Cw?-e)Ve_ zkqzHvSP<_c4}ZSq(pG$rgb zfEQ}wAlCw!^VKN%13{WX?Wa@JdoU(IZ(wSuQdv|wAF)L(3UiV()GVzIE@v{$Bx;D^ z8t8Z-O;u7c>#>de43nxezitXn3N$;EY@8UyiRy!IsW+31qM_+GKPE*-M>7q8fgZyv z46`uxUMA&1kI%3%zl#0HO{oT$9(-lXxyfPEKShB_A%S^}?}lJ@YPa3>s`t7o%dYL@ z&4lrSWUWmg=t&;$3&SQ!V?Fqu_@MQ$g|mkr5Nn{lHHS$!eYA@1Qn-(!|ALu#(faq) zau)HT3q>X_G%v;UndffpacQ){fRsY6iK4$n4@%Nf^u~By>e`yeajz^5*Xx+WZQI4i z1yhQd_PjhJ*Z4Zubl`PR<&4>V464WnBvN$>4slx0vMq(bs;TK?{KMGAHBzM_ zdol>%CJiu-3X!(8r>Uae@^yQN(a zc*Lh+qNO41{iDmK?d6VdwNLSN;Ozt9f0F-pXG7)M2~R z3$VH77l{2+{ygK#tB}QD_Dk41nXG zjDRP}Vq!Jq4Lp!n_i+#f1re7}Ovu-5dX_0?xm?(@m89XzzkoMJUCyVK4yxZz?m(b# zve#~wn8?%s!vCO?@FeJ`DZPWmS8ZD`QW8t0Q$9wBNUp$7zTH*!S(2rSk5xQ9h*8P@ z$V6T%gbvXAHA0ng8u45{CFPWckaKERW}}#AgRdAJdiQ{_VYgTLv|L z{;4yf6EOWycH08BFj_y=58{Zqy24xG`nP49(_et%@1p;&AFI9f2mMucIZl+m8b>4n`i`D#8 zAT&Pjhwxi2PgBws=r%GUbqep*n)Yj5vsSM+934^}IrUYq4 zqYp}Ak2@upgiNPjPTYVMN>99?**5e#T&fy?!@G(&C5;CCFaU)7=U^ z&7}j}#F?-AL+nf~Cc+LrZ2I5g5OYYxjlZ!-3VA(Vc52YP*QqSNLRClnu#3cw()Co= zNMEwg_V?7`hquv;u9}BBHH49Pe9$acwc%Bkx8)vrTD?^|P&R^y1n2XLka1){o_2-W>cbgd`^^izhF!6Xi*K@f|01bS}WPyQ?JEyNF{BF^Qbq|hL@ z7puxJ4LmYQ;$1Nnr*tjelHM!k5{x}f;y$M=6oGHy0th5?w)v(QISm+E?j7Pbf1FZ{ zYq^rxyvIuI>Rk-hh-+OsIQGUJo8AM>tFEiuP`;P*tZ1Agh&M@K07kS~oJM`8Dj#Qj zi0qZ}jCJ;}cB z1m{>mS^@V+MKL8wGEtaFMW+d#jY{$}G|`F6(3Ru%|O+-zd_I5G%le$ zX9ixc-oIyu*E)Q+Eo1HT5X}vC_Tc`$^q#?tWTu6;_PVCo0l>a*{(9E&(yM^Gu+*K% zhDnyU$>7=hamCa?Lt@1xYg*&jCPU($P{2l|k2idb$q6+qnXPQt3Vgp(FPJ;&1Dr6k z!1m5%3aW@bh?SZz;qh8`y0qoH_%OJhxikb{PbbcrX=tz*Q@1{hn#__ zzy4F^@5JVFesS0O^s&TT@-=79W)0EmnI0;sD#3RoN5}#>8BfO zGOiiW^@=ch#Rn22R+BmywAQOXiEkvpWZm1VPO za|+?-PT`(mL^V*^>%Rc9dOTk>dSrv^*B5Kn%^s~Q9zs%R`t;;qfaO-TQ~jT5geN}s z*#6+7E#|>%0c&?RDkbrOP2~q((-xZxtmKe0KOX(2$7mW5Y|~pqCl<Am|l<1l_9Zi1g*msal6M{M2W@Z<#O~ttZ8jvRtgrvpk@+?G=VNA< z^G}smi-(Rc#AZo*Ig&b3za+-gm2>f3wrCc&zmEDBiuT_^8Y$DNX4HhMziY{PBz2dG zi=|muEyfnPDy)Bl_Ke+9Q?!}S4rYxv<)^f>6mw_N9dcE0p27-u zD#nePM4@C-sz(8f(9d?4I+UJn7SyiAKPM1n(`T0A{FxF8M*emsG?f=35-J;bGDg%5 ztHz{nXaExrWEMC&%2Z}{>jGSsCLWo(b9zQ|y#|Df%f{oP2Xq6#sN#w36QkYk-k8KT z5RTdetIea#w1N{}pOe(Q!o$Ra1@UDdH?8Kpp<(CqUXQXshYb9J4HD-phJE|Q2SO2r zfbh+^xcaP5B0*l)vT%ZI`(J&_?Ypdf_UY= z*wym$_1Py4La=dx)$flAR>YQvmL{U_TH$}RQ@k+PO`j^coEvrC%|Cn!e<_gILJilw zcY8Uy|0rxen11(aEZ;S!V78y6rpwrcU@G$U*C}g?QG>&CQ@St_3#6h&5tlmOsy{NM z5(GSsuyBY2PEH}R=F!ajJTRq?pI;CT(N~o>)aP+(Oi9(f#p#)$_1Ad&pzzMCcWMV< zBe*v@MQBX_WlrOVTkVF6TK%XjUQBaT29$CvT%rK%m(cC+fn)da)=wTF{oJMnC5S~Y zv%O%gQ_QJ)HXnIbh7FMTZSxo{E$E3Y6ci`M1S7%%=V|Ic*R6C_jx09j|IIK4;2=>Z z$Ws$^Uko)|G9bZ5#`q4$PGCqhrq=z10Xf=v|2kS>y;|kh^iSYn_uoLvh12TpitdQOBWePqgCrN7iHZZ1z+we$x ztl-^7iUG8QYPmcTU4}MjBbZvOP-bt(BchHX6)5+ppuiEp1@x9T{w$M@=zb(3c z5UQv30(&8QR7;e?RPV-k;E&G4nPGpkc;A~bk~YD;l=?F^nhX(qX|O`i3VS<5QPn3% zmDtiera|v6o+H*>m-m)e+f{AC>jCM8LoH7kcS4?BI4c>aWz;wUa?;!>;=GMhpmKc# zy}gFwF_Ytpwggb#f*CA{HKG><2Y$P?3l%UO=$?h)l>mMD^k^9J&J4!2p>S6sl`>dQ zmEIw8gH3ao!hss$G~a>&*RGc~7)y+TZ&5C66z#nSoTXGY4fDG6sI3O`Yf58LqofMl zDn}21zDMnHvMqx-@Fc&ho(|Wz`0UV89;NZfkMj4o2?F9g?ISipXDxuI@vsuN6xY+R zoc+!6s7XV5!K{_u>(o5_F#ZJV)T!&w4J+JV$-tcQ_M?%zH@t6<84}D`j|Ah)syGMT zQ9Xf@1d=_M#Kig)Wc|oPn^AW?z#LZQ$c$q{!kEV$UykgUm(%oy))LWD^xkP~U^rjc zTDV|ayhuo$aoRARNPWlsG~dMHXsmml%U4namUyhVUAw7@K>{KM0N0@WZhE zkmoxQ!HfFhJcg`aPeQ|y?wbw`3zkjq)U{VrW#)l4EQXqzpTTsUuHB<)8Wp}gx!0G~ z%Ede7f{?WqUN8HnOvlnItfS?QOmfL~LEhUMFeRDVYHsW{{Xwl>jvR1&Iu|k^^ie2e zSZv9M#lg3J-IkGwrL2HU+=iel2vRzR_Ru->Pnc=eS$P9ak}|1h30ncmp4X{eB3QziAYw0~}OzcuSd}b5z7;Oqskn zKH=Tu(?;F%hTe4$ky1q3Ri#XUPf6={>aOwE1z;*QX$M=C#@U>RB|^A)KY;`ch=wi9 zQjF%i5q2FMSW{9nL92cH4->1-Jh$%S>a+b2N#m$45q&jv&3mtSg5d+Ba45j5{v3)n z##k}#0A*xc(7P5wlQ+f++}85B@vPw`%XO?3+@!P^$8x?>+b|<?9jD-4mJQp- zEwG}!>~$*N(-%D*qO=6s9d zEla1Jg0Zl{4_s*PKT3M(Uhfv zBF|vHZ+cHBr+_5pgPBvshYAd& zcrC_G%Ey&VbdFalQ;vRWM)I9+k1N`xt9f~(tm;;I&lYjG4Nuv)ltvFgkw(zGa@K8XZk#IwV*wtvq1{4%Byc@=~fZO94YN_%kuMU*cU-rw?p@?(B@u_a{ESDQ+7JR{nX@DT#g-??i(v+bJ z8_dyX^DSI7KB7p+i~guXA-bS^cA1f?kS#6tMn~>}>{S;j_H*qHKzX=lPyL3E|H#Tf@%29)W&kVL}$}t7pF20wcrfbU~>j9>BYK`{=Q?u zd+7$rT?TR4ngDnQ<_f!9Mb513=vo^XdUo7!H=jB$A-%bbA1x^)?n>uOhCcYJRteWc zcCFkt4uUF0!1Eqj3rOo8B=&H&^!P&eZInYsScB9c&~=F6os0hPFin4urQ}f@^@a$g zg|d-tqKPAJca~C^G);c&q{9I^T{Zg@jOb@k269mfoaPFFwSQX(%`{3ps?FyurEIS? z`JR{FykI`b1a=Z)R9;y=O<(=;_#Vx%CXqJkl{S^cQvJ(oSF_aPWv+XbC@L7@8mvfP zVhPRB>7&K&nI-VgSB(dS>Qt!hWb#qtK)e_2@+VS2O zasu*Zg>m-)FEsxLmu9&ma#Gzshx`_A32m(z9S&Aj8hl+HGgHwKy zqqMoB4E{A^le3Guo?}9TD7jOj+bm0cr2!tU`>A%tRFGcWXX?S3b+__bn^v(jAr=vnvX= z;lcSH8ntKKEMGel-2Qc~gz2&NVSg;tGvli>ET}x}e|WjqyypFn}v`dX^PY z8WwB~CDL+RiFPd4lEW%{DxwoO%ydd;ej$D3H4$ww)I=ARm4*s%@zFRpgmf6Chvh@2lgdJ^9?> zf!9U*xN3md8pGS`ev#==(lEJK4w9knjrY2>L@oUa2X8hR8(iovMkP?BfbO3=cTVJ2G;M%)ij{4KjtkMP( zdKW@1B2i~S!)v?N^>Cd9+yndd%niA9Op<0bHN~-gBAb+r@s`cFnZc-S=b%Goz1I8f z_EEp+6$3A5XQvMNOHbc<99KNoW@a9JTQw^^0~*1LlEO7>R>a5Np$WH^yU?hkuskH} zZp=hK*D>xma=X|DXoG9$M4)#Q#z^L_D$4+@Zp06pI5uQyN}EFiIYSk&T|w|d9bI%d zi;BCHivu5jr`GFwZGVfHXy8XOoA5KCMDe;|!2emT$DH5O{bM0g^N>-HVf~rO;@Df} z?e3{f8)fZ!Vk7$p)a@W|SeEqA6Q|{SWz!D=B|}LnRfhCE;@CRl{QP4jX>k?%5^!w& zQdeMK%)RgWnp@^LhsRdkhKJa1m&Gnt_$mV(=c^+4Kkm?`XT;Z6S~@prYsd)K4^rLE zky|?oy0%&8r3hPwSAfZadH{}C!CokZ4I?GR9s>%BFdgyCyI{93&ZEn~4l_Fs+ocTL^9HsG- z&e)NUg`X%#q;*v9EOSFArt|Pp<_SkPwemT)vN>gDNf-=CjkEiCMuvLLX=^==*aR)aSk7Xu6ud85Z!A!i5|AZP<4Cyuv#Xmh za@zF(7nS8Uzlzsg{IZg{&@FM<6p8GZ%b4t$570_NZ(8qo*{9N#XXXW}D&5LJ-a=PK z;&i%d`3-BCi&EjO?pAqKp^&ScfUvuCFamMfh%et+cp{s&-W{0GobW%4iEX5GoJ1}~-0%9D$M z!xHPyedjewWi>OC@(OF^h4fNTJB!g34EwmB9L#hwouj=AU()Q1vZ`HaL4IMmM?F8n z*pG?fpbmDw4Nw@*JGuU}gKDRSZa>|_G>B?kGgxnI=0YA(P@K~jd(V_?3St%4P8t9% zU|2ntE*X>+0+o6sHBC84XZe^Bt*n^VQ8T!Nzk8zF3+K|;dK`N=fuLh%$t&z^NhT-9 zr@F9a4eeSq2?r;orJjR|-25hj!2AeUJHt&i0QA<+y|i%-PGVlE`Gu9dAmd7A^2bps zv4K4z@*l!!yJxWPR^3*({rxrss%h7<^!U?4XSxlGa-#Tym$PiY$kTw=x^Bm!-I$=_VCC1G%Iuna6!P{WyJ20Fk5)y)QtVlQ5$axe$Dk&_o#+y}F z1+uz1%5nM_?+PYyD+a)n7MD+LaF??}r8>!)6QZ415`}>>Y1`gA`^zQEXP{FL^WD+wgB%=Es4- ztOPv_WZEkE8?t+9l&BjB7ri5JWNCbIjU5Z7+wR!&vKl`iF+?k80#&*5N!)6?mx4Di z(^=aZ_UOE98MSzCz&=dt+Oq1hi_W&wI@Z;d z6r3wGv2@+N5kFO1--MyMOeoEljAc3{C$IX$iBh{?*td@5ImIRI1-(gL^%UhOLX7fKIP3iz!FB5zR-!Rq99lV zziD=X;5Lpux7O7`a>$r*ToE2p>P#~Z^VJTUu^t;=?n(L&py*ua#ZL95QXjk)$T9N= z&?x`Z`;h<|TdlYTdYsFC(yJ9~d^OMi1F((%4OK%wp#}QBlEOK*r+7N#_&5tx=~PH*~MbmYQd1v9|B zeyf62KtOL^3U1m%EuvZLI%qdoI^(ddbPVaGGT%uq!?SE!Q{UOsn32BJLvyyR%ki*y z+Oc}T;;W}K05=!_3t(NVmMR{i|*hkC^<O_b14~ z3O>2JJ6Nk`{#XcV3WCOMHIIx@p9-=fzhd^d&0h=W{1%NRb3F-4@GKDkwyPVtHA}T9 zyU+E8rY5g$?{+QLST{}bsh$`Rtp&nf$%rZ_J`;^1y4BHWJ1r41TdJdrm2B(k5TkRZ zDS#j7tU%lf`)nAyB121O8;LDq3tP9kLQ_$lSIomDiwF5M zI#kjlep(ONp>PjKuL2#ELmDZR*R85`Y3=vVT9+H^7dc^KQQ?>fgkWSei?%j?rpaxC z3sM+c*m7yoZ|SioT3JU`uq35T0tqp2iwzI1$EHo|nH;m6-$hVXeXYpK5;Eo~V^S5B zY=65Omd5E$lPv$c#zIlAZ~J3ylg8rw`oV?wA_Ctnb~?Z05SSgX;{|sGHAsbao1A4< zo`^ia?^Vn@RnGsv>Z&+30)oW*B;%1T_ z_%Jjc$_ovEZRp+?P_mLPLqJztfmVw-buRy{q>pb4v(HeD=^udpA3((5ud9P@i(B46 ziHkpg#Xo>Ot^iRX_KaZ+LvKvFH9O%Uoi%&5hTRR|=hx_OFAop;_^D0vO$AYZ0H|B8 zqnLVUcMy6(uBIIUQ^65S+q@i8C~K8${CJh7S^70GI(9 zL=Tv#G;UB3yI5AA8~*?&iSMlMc~)B@O)c19T5nh*suw|zE3NX6>#RSjd}yl6 zde0o*{4Q`)TV#4(ORKzi(sQcr8Uzh@2>KFTE zhNFRojw_e#ttq^t9Wc_-Y`_LO1ks+fT@F;BoN1#Yu!EI}DV3Yh=veH}BzH~!jS}}U z$azFW)R!G9$fTtz7h-50u|chWVj`tqYoMUbw;@7DUIqryruW3UXj5d<^@cFY)@~Vc zKhwSs`RVL54Uk)W*%GR4unn!>v8WZtmXdu4fP5=wP4{s*<t7FT#EsTxX+}52FB=1C!dyJByptQ-LkF zVG&}z_VLUi;=QoltwVl+-_?UC7AE^#Gg=H^b!_+5O~o{wGcsxoD==t!K|kJDU(7g9 z-k)aqa>)e2v4*(kDfM$0-;X})3$&LI~A|!Q^oV9w9 z<*+biRFx%T4^@#t^iK3SY9Wym%)R;SKjX+dSyBQqU}o^Ld+!~Zd>S9YAqM~;@EftQ zs4pDK3SO**V7powM91 zXO)c*I!X58XE?A_TI%$Yp+i}Y^8SAOqvNJCcO)o>p5&JnS8NJ?i7Z)#I-TM{usRGwhs*QDH7N&PfcePbthC?*9DH&kfVsqEL}SXt9t zqxO(*`p*YKdHGVdMwR`{T)%JuCD-l5_n-)8&P=z3=Et?=tGRh`>HQ(V{nYr^!Z{8Q zY-Q;#)XB>>J*GEQtGUKVyeLIu4U(H39ETjVwNL7U%0SsLPNFvT*&PtA8}Ota*XB|K zc>H~M@>AlOnLdu4nBAKvX-At|KQf_210ZGjDN{6d|iVe1(kc=q`8V*Z!Q z4UVJRGm^ru<1S!2?}@t`!C-P3qwn7(XS`o1_R3N`&whJ?>hTF*-eXSh*3$ibY!jMa zHw_QZfr-&~d1HO&+NkER0;P`;@wjxcD{K-EtKPEV$ z`hKSd6N7(-+-|V4jd*)|*ZH%-ug1zI1-Nth{=F+Kz7i+F$X^i(-M7;(gvf zOYn8^^@IGAy7%I}{~y4yFMi%X2l-FOgL>!wIvn`_>}X=!`nymkVDW+8r~9nrl{1Ml zTk%2hf0knV%KJC*cYfWq{YOxU&`8zGH6KI$N}$F}Kvcj#OTVG?VF<<9?*Q}g>DTl` z!>2uab<4Wf{I5@V|7i*J>&1^rtX@2R$IN>XW&_^MpH`XfB|0^IBf|sD=`-@O$Z8bTV4rDqmo0HZBQSJiA`3 z@9k~&lceJs!!(9U?ZQD@q z0-3~Y!7qKXnbQWtkvhLy^Zn9CUb86glkdaozihkkHW5~BsCzFL1LN|3%zkA0`w`k6 zq}Dmnh~ITzg#!y^f0TZzeD;81dZK4lXPna9S;=4Y?~h+&2@7%`Yp>^DNH}B#q?-Tx zPXI#;fc73y&At81y_3I$^bK()?mNJ$pTkpl*ZQG;Tv^Ti24uB(FoH2)R#`XLe_QYV z{5E@+_A#Tjl8|G7sT)VVJQ{bk%mEwQ0@|$ivnelxzPG$zYySYSqmOq-{rmrmcIo48 z>UOrD=gBMwgV+d+rzW>YHzT`2_m@&cQU)UOn0F@1m^hycMhs=JuO5g=}4IL;X z2x=XGmMYlTFbWz)Aj#evCe1wR6gbU19BcS@6`#jiQZ>dvoHR zm`mIwK5$JjB-oCjeBM;^8k-6p^(-IOS1^(&`Wf0>JiCYix2RJe^2kce!jmGc`DHwt zef?c=Y?3@+NNC_bOy5(vn9bEPwkBggdu&}=R$UF&A~LZtP{u-WdbVu-*45*VG*?;5 zi6;Zo;m%mtiGr&a3d#3(vK=+`aTYCeM~t-eZy|BR(EFw`GtbXNI&@?OJJ?>H@}fE5 z6oKZnv-3LG*~Tw#yxAKQEb;S6U&2^4Wk%@CA#R0;c;igMnQ-gs`DR*;%SSlJt)D54 zEAl)^9SIZZhIm!s3%}%9M}${$PKC2}6ic-%*SmLCakdWf?*vyJm}=t6DpE6V<9pcG z--{|=9NXF3TYM*9c*s224Kuc$nOzb}Wi4^r!`LRLN^Jtcwg?%a`rw#k9VK~2Fi zi_7z8N+aZJ+#(J+0U@hTF;@^WEGmj58gYmG#j? z*d(_X+e0eL(CMjpRtIXhD}1S3O#8@U`}K@Ul#c*uE$#%ga|Z{h%7?ays2GNF$YV)T ztm|Y;c*zgCZ6}gbr*DiB_my;yOAsk@LMy?p!wG75>Uv9!N!~_TSzjLj)t zv=b0@@g^A#oh6GRD;BR)C+j`)p5PU!{$kN?x{iipA!d`cjyg6M{&^@5?m7^Dfj>() zuvccNK6bSl_8sB!%wpvbIhzVc8Xb63-HsLSe4DcE!1;4q6{eF7 zwhj&6K#<5t@`xELIc1x%xl)92^qO%~fk;N+Tr1oI7O5bnTn6fn5>T+D;}#j8(P--8802eV?Nnb=rz@(+ZiwY>?8kT7_!Z zTq*A(hVW?}yWZ3+D;j|`vDjZTpxP<8X5JGk>Ex}AO~l#mGgK7aC{?qVN^B2S&@YKo zu-Zuz;Oei7VPO~{$bfB8v(^XVs_l$ef;Rj}xS_30wS5ig6Cb<%X$I#rzcG~oR+(|> z)LeOo>RMO4g-ejHTVmLAvDZSD{p{PRX1z?HP`5iLp1!@GYBvoY2d*f3Ce}LS;9K{T zKto4UqY*n-`0^qSC>iKyvu~^~KK}l5k0;*!{nq8BiRY)9HeH;Nh*FDnw2kLVS=!n( zZQ6L~X_&a{tnzGn4|sX;wa-za+S*0O|AIiS;V1RBSS~QcphM}6H}6&p_YBCQ1ih#9 z3W>rPm{P3{EaXnG?NW`QudSpkvC3Zq=hCu-%Ge1{zo3@~hhD!Ov%w*yoeNL9wsfDN_NBC> zg&AkbFl|o%3pDo!aH<@5ryD&#Z%J$~qdxpB`l6;CmowonF>b|2rYuKnH}7P7ATlU( z=Kq0OeMtKvsdl4F;4wJ-Os@tE{@C7HZfB8X2l0s$EVKiG_gqN;8%bV$KiJnWbynGU zOlk=3WyM6+$)rlF!txiU+biFj!?_x`&j-A++ls1@mVDXO6(QVFK)e2i3C0O=xQ$_XDg8ij1pk z9d$i9Twve(8vvz=bv zEJhmNuJqmg*Y*htMZNkzOCt}}hmYBov;S8Q?g(ZMFgHh!Ygly*E~(xlF{&UDEGGlj z2-;vpRy$;=!NA!dQU(*|X!o6Djg+rIwH!3K`_aB%)tIlzjYqe|0(aGBes<5_rC(<$ zF5w|3d-Po6(|Nlm#~)l+{aas+^^hpZOz>t1Vq1$N8-%vBOfb*1moXhQUkD^*jZIZ6 z3#%>sTIThP&o$dp-(@KrR)!JV4=D%2;%-r}@5BS30%i2rFZaXt-E(`1g5e*fCSuj{ zzYJdRQyspUa_FyAEsY5=)TB;1SP$8jSyR)Q z@7MWQJ=}*iMho326;_G%`X<8PT(Dx`CUI(jHeK(UC}u5xY1fc16+W_lirQY|r7!Q6 zWldZ6S9kOj8$ess=wF(Sxz)Vx^o)n>d}DBH-UZFc-4}ak)lc{#J7nz!&j|%%<9qh6 zEdxZ2MmqEBrsNpwc$@=zm@W-f4JK*=saKL3IIY?!TTxa|8=$ zFR_z*POGgn!;$T;%FM|A#6r>J9yU6Q^DucD?u~>6s^dSZ(`c1V+W(H?y)LFoG5z%Y zHt;^iT%98$;6H6)DA$PPfG$EN-!h%)ra7h6&6@3GGkgIP#@vym%U1qq{TkI(C@6|S zGq}=v{jGs80Cw<5p_!&5T2TEJ8lIF;pN{LC@e^<7w@SX9Rh$JJK@K)VwuL7P8WBg2 zf|3Z3f!F#R!z3xAwt%rnljW2uLP>2i_PGWWWXmvupw*8Ynyqf#wiuXIluR+_H4aiP zWX^%Dus0+UizQ}u4l5*1=l*IVNc!;R^0+az0XI_`B5_KVwuBmh&iDq!Aj99Hqw3P0 z_t4B&`9s@c3zz1Yd@OXNTea|%9Hc4g7LV&s-JyZJUaw$3al|&1BkvWKt+cia7$q(7 zjvaVWc7n&J6Y;SqjRjvB(v=|)d~hm@2&IauLl982EeLY1&?!JkWyqpNBdzoHJ#<}Z zY9n5upx$+`uPDZr@%cX0LM-A4x<#v%O`=zZEljYkA)<0$?(m8G$m!)^bGu(h&D;<(cNk8V?L`vm?!xvm=2mO6nx zODY3M_4`8vblthNEfciw zs{w`LxEdae+NNrE!)wXfz1?TGYE=W~TMOOZu;r~LrQ9M&in0c^k#1@TJhtulfPl|U zlN)4dee-5yDl<1e9r}5!A4J+M!8~iG+E!!jKp%dVyvi1Ls@?+o9Prm?bKM)Z0Xg#-(zmH%@uYy)P2$Jvgw3bs4^24=;HJ8&oaMJ{+Y+s79XUwIU7InA10S|7h@-~UJgcX$HF7AuUCyVXA zoH|L_7c|b37%7ARL^_(bwDfFYK6<#VqT7g+rc!mV;C>_eBpS^DJ5ZL`shQAmJgE%U zbR8gNi>*;Th=%IRzIv_h`gTQJy7jLnKn}HT(qD(b#+$0lxDhu*ur6X&jrz|^s0l?E zj)Oof|3?bG;z5OI3UicO>U(aQ))?^oll+UG($cch3MuO)EniS;9>I7Cwp;qylJcXJFWn^>ncWVjLHygtGa%i+ijqZ3@c$Y;9YH;OM{8O=leuVF3znRW?F{giu)cHRf|Y72(JJNOrjAfSNV^0Nv1yD zP_c+NDIatS%H>dy&b6@6;E-r}M(Y*FwqxQ}0Qip9s%zaxo%v5!yx8@&$b_@4V0j;}M zdd8KE*1Kh&C&}VSgX=p4Oba@}z8w&vX+GjrMQDaeb&wFVu3%p!m87iV;s0>lL`0x) zidA8f)?@!Ew1OKvpdMp8nUke=Q+|+*ty?mb#5T?Hj4wuM{9ZpAe&~}>TkM=bA1Mq4hJes;6@ZfL#P|Oiu<&d{L%InW2O0|NH z1GvCVLU?v`>ozpTQvq$=kSsM?wSpz#bLqk!@cV?39hVVw6}A|UH`T6bhGPVXY2J5% zfa}A!{auY)zr@UPOTP^p8_GmclMcFz!btxOtiHr&`WN%I~_ zG%8;;!6n_e{1#213$^&TxOLLdy~s)5i#U4Y%3J`K`{?6Y%YYgo?KcX$_Cc46W46?o z;$4Tw-*0!O2!XuUmPE8zn9c+w3$nD65jEn-g<(QPVRFOlDlQ-e%--JK^WIfsU1*y` z)-$DvTT5A=jJGxzXK9?pK$*xCjI}>vgGhW7T%&F5%vYz%M+UDe;~K|gj;7{kNiKlJ zf8hIdNJfVA{NL72KaBpZwGlew!S%mpJkBY`t-AOND&_6JmAVKx**dB<8<&?cmk}$9 zHp!O(seVm4eEg0ExI{nek319*xB6yk+rdA_UemM`1zT6iDN-S_zq}8;JM2vPW!yNI z6)kPd;XFxp5oR=|bb=CHt?R&SFr=eBj%$U*jnIi@)_2(_^6m^aF*cTGuTi!!Q z;P<#oy)eDW1@ACskTluZ+#=7WpD8t%)?m*@os$j|AHedL{VcEtT0CqpK z9%!>pwON~-Did$IrpjFi=xK90-2mQ4t%w0V`i#{A#@QyPP7MupT)j2CSM6#zzR-we zK|zB!hm4zL-lm?NU`{E$q?xD#S5;Q`Q9N$3gqApYzM?RJ2myAnkiR%`lwOs#P~=3^ zEgPM#rLA|g>D~_os zj{ZIlqB^r+$vqRp1j_($IWX-aPsoq`y3lo#m%z3tRuP;41J6U^?_-#=3l+kAHwdCr z)vo45L)PR7=FrK^IT3s#Lv~A;UK3e83${Lr$E5b_`=*l&`jb`Cn{ZmE=im7^osCG)#van}~wT z7@?(Ct09M8T0;v17n5?-_y!r(CI=R56C+rA(wYIUhz~Y2cD93*F%TA z7nm6O$6{cgjcya0IGt9i2(k=(i)zFVpD&q(f84{i)*(&PIW58lwI#OopdG{j@Ty8f zpX$f?6MOWBFhF~#K5ZZM+b-}m$H)dmapvoOr`?1#H38(QfIcG+VPX31qTudq zEqZ4E)reBZv*-ikWrYLoMx$uWL7P%rTbyZnAH&tl)Q%*1S-7MIE}D$Fo#|sNp4jvl z2jTYCTUy+yy&v{W@3S&5hD`dlHlZO4a6Y{^94_+nevS`k*PbsbKkT-|{s8)^n~zOh zQ|ELSx(0`rLV^$@;KN9Ga{GG1_DQpMS>w**VLgA-sN3K@4;g*S*_dqbC94m0)$wEn zJtS}gjD9Z|iaUWr``$;I#%YV|GV$ z)MC^{_1VHswo=AO z>t4Ym>fL5!B1U^bav;!X#~n$~D9Wgg=q}`8P@7GYS>;+8d$KEAZ4-U1AMcWKY`S;E z-^%OR64h0RgYU;!*JZojj0jx`7mI&}poGz{-qub3je>@ZPst@yp!rBdK0y?Xs*XA< zn1;4)T{&0XljfbKZJhd*u6t{r&Q)1uu?DwB39z^LV@{<;V1|8rr=hH>81~AU&Q3)` zG;+LLALmQbB6+u4Hiui{RXaVq>JN3W%h}?infK)5lY=ph$_JB%+QKplGTc#{GuI{A%zqHBb$NutfYyGjg9pecv^}` zNR}};WkmNKV;>SU_|3JHNQR&&N+`>a)yYrYGE6UQzxYQ5OaK?B;@*&vzI>=UhHjf; zM0)1(>IELAm?K=>CqHlack#$MrqN5loMdNeO5;&3ecAVJtZY-JUGqkd`Jq3 zsm*I#?e{a>PrK&u99?|rk3!u^fqwvRTsELSyO>Sh!GAMYnljk-FHXAuowKf=epqLX zO-u|*51#NqL7fbL{OMC8lk4kp*0DV?rvl0w-rRhQ;GL1avI@kPJPT{1Bm$aJ@{ zwQ0iymXs&$0HkN>O!%njZQ+Spgq9I3WocUPGwc8wKy>ExGOlv|U%L)i)tC8ih*R$x67G8^^T4K1s|)BV`j-kw@j8Eg`kDVR00H$f<{)Pe4$ z?9&13^Lc}QqAmwybNjFbW!y2##ii%r8ps7%q9gXlYNDK zjg~CFXsV+q?}lt2EY=8o|1xnmJNd?W@^5rCx+n%S6AGR~);|CSTQVIDZg0VK1%R7l z20A3MBWP1On4`mvzxLbWtdz3e2{Osb4mw6lOK1{*kR0%ghuz`Bp}>kGs+VAc8E>x0 zk2Q-H-DG_gXB;U>l2uDvF&iCVZ_oTrFu;x$_zu51Phn1bfZlUY@qO-DRLcB3a?bCz zP6Ho@X$&DBx`(qV{QF;`IJ&|)X5?h*G!|8E#aEV~eE-5q(ZDZ6k^P^@`(Tj!Zr0^} z=iLVt*abvXQt_^YGQ+kEVc4@Hc1v=5$bo^IG55pHWKQdHzlW4;?aC>fuywE(=dQ+% zye&70FxmDfKJUQ#16=);vb|!O^`!Y&36X7T%1TPpvTI6D3L{i?@toXTeaBnP+&8cU zzL7!U!0#`nnY6>6=ie$0t4L>!@-~lYhwJ{x2-cBFBB&Utp^qSS>?@J zbXso0&d=nAJ<0UVwaJd@L?U^vGJyq5NE=gE&{Bn65n-o2oM3) z?A+MNI}&6HmPu(yRcYmrHjadfl$2XD5ZnEX?JnMIPM7#jU*E zXjn@+!dP>#5pY-GHX?48pKPqf!&~OZUHxk3v+R-Wzh+6v2#$aCki2TC>cu#fL#9dF z#qJdTuC{L7s=Y@4)rmJ)en@0%`ORWI^DbG>%zj=MIb?GSkp_t z>ekO;z=fiuY8e(@>ihNQ5uBo$y3Ea8;|CawbHgMuW!_$H8w^5@TGmlnfr5CHlstY@?_W_(xo# z-3v9=o$&OO`BX~`kDOGXD2Hi6oujl7Bkm~%m>4gLwYFP2Q}Vn{<8wX%k^VvtKIfQz zSyhGKoP$d^0j{zPD|jHh|_c0RvC3|&k7T(=j%bl;b}j@ZHCTM zNQaCvB$ZjU@}ebmv^$YX5g`;9(uq^L5^SZ7I~Gy|6~#~x6Ej~b%%|tf8?&6KQ57X_ znY?4`5>IHI2t+ePx=v2r;_D=D0r>Lk#tt1+xug}UFHUINwhNB%;VKFwI1-$I$D!G? zJ9d_cLvrfphOHvZDVdqhToGr*RSpJ-Nb3U`XS&u3nmSB}-q2d(TvA5sEz)!%HkRU< z)FjgCTUOfhhA+^@9=42(3>F$x4yGocre>vOOn@c*3~g5*78R+wCy%F8$EKtc=r(;p z3Fl{0ARccx|9anMWh7HoUiLT0Oe$P%H+59jEiJ6sA;2pC z7TwL;V7HH4)aUx=*o(Pz&aJRE5r_+F-jE+$jAA zP-fLlj*X0oX+<7kVXT`rf3rmuRu-4JZRKB3HRRn+TRUwj-0^V}h;k=gLhJ>7(3ag7! zXLWdEfLMN_g(J-=cnh~pYPfEZfGdXB6+h%dqYKM#+vkQSTtmDKnTIUx$0kR(@nfd) z_PD7P0oK-ae*o!kAG4fB%RhthEWgF(Ol{|E+#SF-#2J*tDB{H?h9}xh=^y-@9Y^}k zur{p4vp=cng~$=>6S`H9Rj8$J=dfuigEh?L)crN4Ik&&p)=zTOGK&Nm*zEOmw4Os2 z=g`}(R^lN>sZR5m3`BJ0{|SlsC3m(Yz8 zVPZ(Dg(g(wg@+G!kx({uDPPWJbU7v*H%u*1$oVbHGWHTX|bkXl)CRt)@eU(Vx2*Dohrrd zOqvtFQafOP(f_3;nFu1`9@tntF&vq~^=Vb}zsST>j(-es56jXr zni?DBc4|@(ZCZG-MWP}|_0nYTndKtixG%&xeae1b9;yYQ3<^Bd#+q{29`1f#Yd!hI z?-1r?TIXy?0xBPiqGeS5a%u@g5^p>ub&RWaQQy zK$^yOqaYwO#9vy~*co9d-`Zax=WdO4q4dfRqrb6|e0resoSo0k$f&^;Q~AJ7zk;`q zjw&oR*8jza%0_0R&0i=0$#iHe9CoFKTnRjwmT|+|dKGgy`Oy>4RJI!_FrU=;2GDsD z$HO;96!xqRh>!hf%+<%q`KB(Z9N~DS2&9YUC9CB{J(v3&QHsK;2`7n?gNOY^br$Mc z#PvXN#X_WoMbU&KxBLItd+V^a_O1(%7AO=C?oM%cFU4JhOKEU-r$vfGfMCVlf>SiO zTXEOo?!^ji@1*y=_r34;%{SjXGk?xA|0L(+Ne+jToZsGi?X}nXNF#_!eHs~AKue1z zs#9u*I*f*&V}~P!hNW&-j$`PqNK9v0Q8RnPKmJM~lxpeDL3hVfcS(02H~%2z(GC`y zCbI#P@FibJIb-ui&oB&-w>*)-#$C`eu(9vqeKU1F)clTcM}Sd%dVeH~U`FqVr7Xit z=8Dz#GCTUfI^51yh%s)u4eqbhGRiOkXX$FQt1VrBvrNgaC-b8 z`Rm2+s$}3kwf1Y_*m+>SC%jFwi%CG(S~UdB=vm6hWHbW02u~BD?h0xv#4V@5t!>@7iQS`j ziHm3j4<vvHU_SxA*{_pIiAjT+7?+5&>xR?>-D zI5u02=KOPxvz?@f>*I=#8C2gJ+5{mv}GjS@=1QP z^?4kcz;iN9x=tl!oA|#uWj4P5^)Q&Ne(Iw}>;QPreCw1*$d28FAc$^mxvKaVCf0KgRND^I)z%1Vm&XnY_1|^v z{1i74$k7zG+><{aL@RT^H$+ePTE>p5_g-kPAO7dPCHNf| zl{1%l&0H(ot=zvd@d`ze{~#iAZWUu65xW#qM)~_NrQU`e8K1uh&MLDQA^Ns`I@%F5 zoEd$GfqAkXsj%dN@gRv?Y33ZqPjBjkFpotV!b0_69&7&eVB`o}@b;`&t`O@Bg95{%C8d3{v-N*V2(FNIf$_ssVvK64mZn$8DZf(NlCIAc%6|lXWajM@xHD@ooKl z8#!@~aC#6!GU(nJU~jg*P-9j34fAI9?^7$zw9Gc~Xf>gCNMnsN0j;3gLtlA(w9Y|~ z(vJq8H~RBie{wF#Ubnlmo87-x@W{Ux&jLMR~g=t@$hA3IHS5DR$ZsZx(Eo zR8YqBTzrYeUIwS`a4%usG>eeb%r69O&33Blv?&OsxItJsk#No zyxwxEmZYcfIV6LyNRWLt)Le)P4j-??BVT_@r**X**%g)iwremU)O2$&(#1~6FCI-% z*P|uOp;ks`0S^f&sFCz;T6u2TE5S+IvW#c|naLD9N*QXIUTW*nsE_cubs0Fz^WREQ zgt*U>$rEvmRt_)QgZ_r$CRAJ5$< z+@d0@k*XkYo@+-8tZ16ASj2amdh~iMuo^YX^uG0B8$MXjpOm!HG6X-;m)1!C!oE_c z^F?)%rXy8lZ+}(xCXFGtfY7kcUrMKrKQR}@nv|>NW3Ajk!L5>TYa8T~Q~TH5Hi*O3 zTLEiuqD7m_V@BYM9E$I5ggIcoj=F6*4OoHtk&b9QrKxgR2$&cJgIj=0l$5L9P!Pz; zVX&9x>(AXs{sDu@o~x`Z9*hVExzsRG17M%VRVxSJPAjMtiNz4YEzPi-0_U{MO%N+# ziI@V#&axFN0dfhgP-Z_?kLOIrD9Hp|hFba3fYkmu*|cC0=}>_wFoQh`I- zVJH?jaz|lIAzW~noA^&BMHv}45b;;P6L7M6`%0#e}V76Wl8Ha&URm|O@21I)pv@WYjHl?kRL{-8)16;;$w z;(hdO0*^P#9Gqd(I|8y_@ons5^*P|`Kk6Id!soc&DLg!W28p~E%X$!QbmPCX4{JSu zQHzPkJ8k~3FS5kl6H?)l=hxSXd&1vyOij{sdx0Nl z&`syhv%Ys9@c(}P|NfyW?UN$hwTD*Iy7s#NK=`iIML#zc+i5lYAs;XzNk!f0{^c?1 zOU=Kaht5*dt(lqp-5Y1Q`*>bFUP5tN!O#*eM|lObNJBz=W0E)U6{T8yoV zPwB64lyZz%`P}QPr!kGyu` z`HK=RY>!|}h*^%KEaVInmle9N4^Rq|=jfXiUH))JT~FG()gG5&=h+`+Hly(WlCW15 zori&!W4=>+(BRlb4HFfc?xdBz_uBLV>>#^^g$p*;&6zGFrvaH#ez(bL@WpTs*-p5MRo7MUsdHMi1Tg4TIwKrX?m5t zbm!MMhdy5Jg1I^qyXiQ6ve5t$|LjLRP2QrS80he%={ZC&R*wr^_F>SX&eI;TbtVvYi2{Nz|hqwT- zof>>-RD18F@6g^l2LRY}z1cg$bRu|*!Gr*)FGCF5^aqTnzk7xDoKhh(uNP{Li{kUW zQrOY~6gU~>z?!vmxN%Qq)N;SbDK?S5>)K37x6;`qU3gY^@Ofa)&LM~Bm_rq7YsB@6 z{~fH}fKJ?$^rFg;t8w*lcAG4WTL#3Q*o~K+wl*ZMjNwF=7UDk1>>CbCytcFUERAdu z2+sAF+-NOv1-*NH&5>&?q*!^}j>ENp@!>LT(h;uT{)m+eXDN|eCd*24&cjRM)OQRv zQ3@-1ESRi0-u__VRqT1wU5ss2X523fb_u}McRcN7+Z|y?_nAI%l|pjMnkL&r7Dis3 zx{0VziSMUIk1o#;i4iSp%Q3-nZ@%!yIUzVx*R^FuJV^Y3(AlY0A`&P&X&d;HoM$Tf ze5IE+EMq-0EL84*_@0>V-RIAV7l*0i4 zkcDKmXv<}VG{R6LBWZtA)`|fD3z zXb0u1X{e!KGdSs|vkI9`ZEe%h7;i7jzr#fCQ#OKr+Cjv?^&-6fPQ++d%8^XnG3{9w zKWX&`LY<%HepOdsUHzOTSN|67Wt@d1Tt-e|kjV;81>1z96_219PYC3FbR)Y)B#**b z3a+c5Ln2x9j|pA3h9Qaq+SJAg7keow-EKG@Fk zki>B!K=*fK&|V5{pSs<*cWAn&*b#Pa|8NXToJ9ZP(P)!Dm(V(dk#H&WbTa!v)N@GU z{6V!>QzJo_fvkQG5WNH9oyQ1HOY{0f@hH%HED0?O^vxQngJ2<34OiovcEI#@7D#GokU#~ zYkw4frJ4NI{H9iCW{5&Y)&Dh;h12W~N^K=${n_hZA_01{j-O0VRn`ZUjlH~Wdxm0I z?LQ7Kv+jUuxcdi&3RhE;)osfkxS7xK=jpjzhd6l5Q`)hq00&nb+L~$)oE@sKzwq$k z1eipi*FcL(DoeTMdPnsA$%TETP9-#2I`o`UAsHxAK(^Cu7mPA*fYo;d$sFFFY`H9T z;W?#S8M*45xoP)`lVXe)vOhi?efjFJ3!GJyW{eQT`?Tipnk=_s&-f+{n(6A!dRBk- zeHx1z78AJIasNrx!U=%7YyFXD%GhA|4}{CA4)f+YEE@Ttq|dGFo`%|`VB#;nAJ{w| z6LSnE2L=~Sa*^eM(y|P?eOSXzdvV@uN#B>Q69Saxyx>eF!TKg?hvL1+p8>g4?@npM znZlXN=^{ZSbc}Zu1w3jdTbz{Knq%`kb1P?rPe3x}a&uRE6sOgP`QbeWzl_9lOnaHy z1IN04xZFgO7`0FkVL>&nb8%lpY0~jn^Ew=wArN$uIH83 zXry1Cb#f8Bb!g{&CwN`9t``#I5R&zZz~`EY&PkzZVSO{z-WA|(-x7HhkGuOhYB({t zb=4Jik=4DQ`fz9Hi=mP@J=d7u?PN@}e7RBWah1igfmI>LGs@GEWay=|g=M;+V({lNCB+IBw zsN=Q+mG!(+3tmgFEgVQl;1Hrq?JF2~>k%1ScySMdHi-4bWC$LA!fovaVyzEH4ktK@yj{hxfuDJP4z| znbtNrP}P2T2~rkdF|4S!^@A+O>HXBrT z9zhD|IZD)fs;W`9g)z3aF4@_BIRH*uxcfxlo??LGZPhyI%Uvip7J19g9VcsB`E(p- zG}KLi1A~h24}=XOlejeOVvdCAiAQEP64rXEtj%kauUMnKN-GKQTpsRj$a0yFn_K|F zH^+`Vh^`&RphT≪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 t8Y|xGCrI#p+;1M

    BaX6F~{ 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 QVez4{<}Sp({7?RW04iH>uK)l5 diff --git a/examples/expansion/engine/ghost-preview.md b/examples/expansion/engine/ghost-preview.md index 0dfe51e606..df880edbc6 100644 --- a/examples/expansion/engine/ghost-preview.md +++ b/examples/expansion/engine/ghost-preview.md @@ -159,12 +159,9 @@ embodichain expansion preview \ ### Piper 书架取书 -下图来自 `piper-coverage-expansion` 的 8 环境 `scene_first` 回放。 -`object_pose`、`affordance` 和 `joint_residual` 各有 3 条通过验收的记录。 -该命令将首条记录 C-001 用作固定对照。图中独立开启 C-004 和 C-009, -可在提书阶段比较抓取分支与关节扰动产生的差异。 - -![Piper 从书架提起书本时,C-004 和 C-009 的虚影叠加在固定对照上](assets/piper-scene-first-replay.jpg) +`piper-coverage-expansion` 使用 8 个环境,`object_pose`、`affordance` 和 +`joint_residual` 各有 3 条通过验收的记录。回放以首条记录 C-001 为 +固定对照,可同时开启 C-004 和 C-009 比较提书阶段的抓取与关节扰动。 ## 数据到画面的运行逻辑 diff --git a/scripts/tutorials/expansion/ur5_pick_place/README.md b/scripts/tutorials/expansion/ur5_pick_place/README.md index 759a026ecc..2370ca8391 100644 --- a/scripts/tutorials/expansion/ur5_pick_place/README.md +++ b/scripts/tutorials/expansion/ur5_pick_place/README.md @@ -47,9 +47,7 @@ python -m embodichain expansion preview \ - 画面下方的 TCP 图分开显示相对原始轨迹的平移距离(mm)和最短旋转角(°)。关节图显示每条轨迹最大的臂关节绝对偏差。三条曲线都用色带标出同一时刻各轨迹的最小值至最大值,用实线标出均值。悬停可读取三项数值和参与轨迹数。 - **object_pose 物体起点分布**统计两种布局策略各 4 条 `object_pose` 扩增轨迹。选择抓取方块 `cube` 或放置目标 `goal`,可查看该物体在 8 条轨迹首帧的实测 XY 位置。X、Y 轴分别贴合该物体的起点范围,两端各留半格。图旁标有单格的实际宽、高。悬停或轻点网格可读取坐标和轨迹数。 -下图停在 9.00 秒。选择抓取分支 `2` 后有四条轨迹符合条件,图中打开了 `C-002`(`scene_first`)和 `C-011`(`robot_first`)两条虚影。两条虚影和原始轨迹共享同一回放时钟。[查看偏差曲线](assets/deviation-bands.png) · [查看方块扩增起点热力图](assets/object-heatmap.png) - -![原始 UR5 轨迹与两条单独开启的扩增虚影](assets/replay-ghosts.jpg) +可在 9 秒附近暂停,选择抓取分支 `2`,分别开启 `scene_first` 和 `robot_first` 的一条虚影。点击其中一条的按钮即可单独隐藏它。 ## 修改配置或可视化 diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png b/scripts/tutorials/expansion/ur5_pick_place/assets/deviation-bands.png deleted file mode 100644 index 28c0ede648b95a22977b95fde0e6dca81a39ce07..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 80078 zcmb??^Lt!v+iuXfF&m>{gT}TR+icL-&ctkN+g9UDY&5nfw(ULd{`UJk-yg8&m|tdQ ztvP1ybzj$YYK1AvOClrUBSJtxAWQuaQ-*-}v;+YG*#r*-euo^RvKRsa4MIvxSk*oA zGz&&(O&W8^X^_aZ1&FnhUxZjBzy5z8dYvm3Kp-GbV%3?UC2hSL{kH^ag=($(;-x5{>zU{2(sZZyvvP!5x$1JW z+eP*|;1CLvTCV*9;Co-WEKP8KK7TV^5Xx#cuKHK^j|ubX`1Euf4J#3^YrF5o`&uQy{!J1VmXPg5kmFD@=tzl|7-Bm&$lFer{mKPlu0s3<8}EYWnZr|9!hVtVl?Pfp6>D2e>q?0z3h)B=GRUdDqzKq zL2ECrwXxRK{m(^wIIe0rSa2+Lwzs#>;IM&j#Z2WHUR%>WR`!$Bphp)@@7oG!2oY0N zog0qpBfHukUq!-YMEhrd{z&_op`+V)-pqd2tRm zF_KU;L|>=sH57_!D(K)aN)&SbS79kLF5Mk3Wbp&-KbI6GVGp-1))**7kO+7UPfXCY z$?012B|6tOb8@l4Ha&5U@wX;OS#y$%F%NNl$oo3tdboSs+Snl_y+-gGPah2K~JY>uc zqlvT+Z|86@aLP|0XH%B6m;1A`wX%rxHhiywA7A~vKB(VSA?*#-YnvyBhq>G@Nh!q^ zYxHswG78*zKu~H}`E$Z_IEPbp6fGWaudgU1JcVAg+dByVlx!hit%|aWuv=MqS)k$A z*fRKo{4^$Y^y<=*Zo7LNT}?#^uf@#Qr)u(gr$1$X>vo24 z?tarT_M-E|sTMn(o?34)r3_W*7ql6TppuZ=uC+`3(+^4a{Jrl+u^-(5fQz+ORyw+J znUv~S0J!N=Gxd>fK`DYRJhwWP4bjLmA{bfe=Xw$*(EL(b){Or=CyQ+pzfb!ccP^c?o{(#q1( z%8K$)`>WUE$!yE?u2ez{i6F|kB3gs<2!&*H_x6q1DWfv**8 zvJINYb7i72L`7xljh5^lZo27ksKniz82^@xhhfSed8&k@hU1Z)p-V^wDtINuJW#?~ zy9Fz}5>5mW5%$2geQso3+|_Ec-Rz72Qq*d-H}50hWx{44OVH;Q{#`ytAd3{RtMB6W zVeM`ik<1_&g)d%YoL}IL&uP1qOICQX*|pi~bkNY?+_sy=>z2-DF;n9!$d&zt)ePL4 zL>&YPpOpN481Ew;9dBB6tA&K_PuJ_sP=7nobrqX2OjU!Z^t)WEW~jScr z`5_V#8638wBjZY2_CJ{o&VA@{Rk3vO&A4y#v#M-#JWRCpi1a9oDSpgVs>!IR>^$Az zYSie@PtBnr27mdICjH{|bWK?*X=6iFzF3{-p9dbR%F4=`nt1fTe*K!Fe7IO$Y;oAR zKU=k1Y0)y+gmAQ7Z=0|E+1IOLnm}EF_4`L0MJOt`4jWTsOz|&odkutz{gu0P!+(vZ zXA5{!eg7US^#7*UC*e_8pmI@o7LRMSQUw+L;qmb!+kG7B7s?Wmk?|4Qm*^&&O`qr6 zviODK!eR`^ys?7>=BUHRw)qORK-ADa@9hsU85v$m?xMq{PRDZ9G7*I75f!R>%}SLL z1tknl7P@%GFX&$o1T=ARaY=F{P8Og#yDoKj-W@O1VK&Cb#W{ew{bg{O&X<8H zq=1TK(cb}HcbBD5)f4#@jyKoc6$oLWs3hP&y|TF}_>DCIQ5@;KKZCP+sDH4HD}gm) zuzxV|onapb=Tb^WX0z4%pmMpM^k6$($$6u?zRfQwtwkeBB#kkwS*tfHo-_OqUdE;i5en`&wI;!M6eB_;K=zx`sh z9ul3ZPprql{n+@#$a;eV#lN^L5$>Lw8^ryIOxo0+(X>vpj+yy3k$S+$%t~gQVx`fl zxzqclO1mR`w99KxTG(#=l$khlj#!T4`E4LouQKncPn7>`%hN!c6+@iu4dHf0k&~x?`kEUT)7tDPd8+ zeD;00JJD$H0?z|5PLVJ2#(zN@h>On*5W)H{d?;+k!en2ZoyB|)@qJVr{q>&)H(!C9 zgcBy7qM+w_z0?)GHnRL$a8sXJ^=mS}1fd9m@(I)vnA@Ez9)TMsmJbG6GZk!4ui$}e zyV1S}Zk*CDUj(c*V~E$u>OAk#!7Y#_?K3+&yCxQV5T$oxRu+-)^Y?n;&nYYtiTO?k z6JQJ$)PJ_xtdPwmY`SoL8>E7QfS}c7OO!-`mi*}QZ-zNpqi*C;(4+M^m-6VF^_G zd;3a278Z_>uI1(B0Z-k30B|fzZ&Pi9bERU>!~`);Axl|IjKY94b`Q75@otzh2hi<- zIALV1%g$F=7*griJ;@R(3EkPQDqfJfhC;L5W@jvy?>k>oLXPD5?C2=syM&~qTD7jn z*hdo{!Iy*m{Q&(cjb>sl4rplT9#cfdQEG+k!lI%-%b7tzLCf{O`ZgLG8$?9{Q|Ps% zeVGD#E-x?r#C|A#ho4rCwm)BM)oXM17t_{$&d{hCjQ%28lg}6zR#rBH#U6@66c!mt z`fpkO>4A-F^67)U{M0M*f6zuvqpfljzmO z-hTJWy*4y4(S$BRcv$ed(Ycm9O!bfF9X=;#Gq_O=4pGw}$RlDJ8y7w4*=}|Q{;!>V zT3bL)VYk-OWArDx%iZU3_@@)=P0}~@YCT}`qqg)>x(>Ze3jNh(X`9KFQ8@vF{oZI2 zIz`B0rB(uBEYNa~4(+rbI zYVf+V5zA~MJNY-|yFzv(KDXmwrB*Q&)yT+*>X4x&);F$jW8?fV7BnnEv40VWX-J-p zVR2$nS)P_>`&xYNKDzhSv8kmrT}MSayVdUgo_|bTB68H{D2xP*FcMj*1GOS)Y$BpF z$rzH^KH-126Nx1Azkm9Zun(c^zuZ9Bhnz<2-$Qc{5taS{b-N}1s||d5D$7L^|L5ZR z(Ea~EO_@e4jea5h<1D1Be{oy6Xys6fHLNDTQ-M_@#xk5cD!s{av&d{Z-tzePCb`PA zZpm4`D{UX)8rRRM0qCR9)5-yaV3DTk{G5*4VXxtLELN+9YK>EsTr2LZ=xO6~{mI_#8GKN2gNTR?`a$=d3lfaTFdGM}4v$+pQ1Wib=YfH~sw}=frE+1K7K_8J z+JM{b*j&nB=vQ6GF$X;jjr;zGeb4osI8wiuc%{~Ja89waBTKz@!%2(B-Jh9=~}-rM}A9oDoTQCptYnc~szxODV`u`g|syw{kgJ zHVCfxB zb&)Z}8*|EzsO=5~!Rx^7L48_{6_>sQ*UefV_wrut2mrXb)_P&&XUyi0%StLstr9#1unv2kBO~VGM#;%;c}z}BlV0Xy|~#5wH3Q%wX~SG?6-M7$9B5C;HwR8)G6OA5S2D0C*zb#w_Ga{;eAQ#7n4+a zx->akuM6I=aqbVzGp6nU+{L$X5zkweS6F?erl#`-rUefi735?I!2EV?Ir)w8otZTz zI-K5uA!Y2w7UXntT(T%mNxc{dZ2Fc=E5m>IG4*iS`O&$@)gwZN6BcI2HBm!F%}a2c z?uneC%jML*1T}9p-_-D@2)76WL0F((xw)LZe7@Y<`GavOGd2V8S5Vy*OZq->C-k1b z-8bWLh7#HR#dB!C@zy8{HcDT>H$EpthGF5l{N{LI)`;^pPXhsr)@Z}Fy@hMC`Imw9 zwb-RaMXXL_%Tv4ds>yas5-D*bCZYGI?)SStrGV;|t8$sl9~)H_?=i$!3>N0rgd~`v zObd2%vNTwHKK7H#RfwsqdD$Vd_MqES1DcQ?4~()gZsXCDru#!9tvTDf})0ci*B$Lk!!sN=l_{1I)_a*?k6v^cr`G?tHC;8D$mhW_&KAzas@NJ>ksOxBbW! z$uwmsm)19p4P|VUFron)1|9Y|@9%c&(%%Sx@1l~p6(YP3r&gvmW+q1IY1zeJiI)iF zUnbUxz5&fo4iSR_WJ+RQ)`5D?s32R*`RW9-byz6jo)y!Z9%Tp*JM&$4AanYr=)YOb zGqR1SAQYWQB&1{@#pA6VrA+2P0mNJs>^!l#h7KEMnp1-1`CkG)(6oI9s*ycETvrF@ z!?{V1Lt@gL-*=U`U@tYZ`5nY85-R^jddv=r8a=j*Q2H_~d*>?6Cg((ZJ@L>%a^B~n z@3`8nsyZi>8Ha?6i4^_4*8|k0<_uy9iQad8RFN?IglnwBqK3bd>)2CHs+Grxw zZLoZ7w*q+iXh1}KNpnV&W}LjC;kTH$_!upwtRdW6u1UTiQsxhog}q7BhK57^X?I&^3`yx*cQiXdW1RC3~HEg*EVFAWXYcW zg1dRCtfB_ETig7*HnTP(Z83jYmw+54>vgdn9tK}Ra3$>*Ny76B<1jYr8!oU-0|xH2 zhksRXt-M8}qSfh!r)Bmq9t?y0Ht{ixsU`zL;MabLi)$;Tex~Be1?jS|&VZ^{+kcg* z(p4Sl8R%@NJS_RIAIKAC1FhFHX$z7F%f&seZkZb{w$lCjg09o(^_pGw`{Rh(Ze^w9 z+nja~m3%<*94u`5Tu#bg^u`U*4|z>?jW>a)-WPl~zTb^r+0f=C?>{8503N2F<>bcm z&*q+^GHkRPvC=`8{+pgFYm}=T)%1Hr8u}o}wPs@(3D0NT$>5SvXl&`>Gno7s6bVHp zT0~-iHgf>7?O?B|%rAv+df7d84c@c(?gwZFP(A{TDKc2Th`}Nv)7ZL2+T;B}k9#*} zs+Ff~9&?7HM+c|c!N(MDV;7X}Rd-*wUjJTEBq9c{b{=$-4WXVZwKd9<@I#Qe0~*X% zf8H5gQzC%(b)6_FZx0M&=T#Dt*=#VF=Ygx}{yI$%o&ecJZi+RRq+1@+4prnmJwH@K zh$!!oL6KdT-*^A)1ecQNtc>C%;*Jf&R5Wl>!;9N57^`q>zj3T5^~c`aW%-Wghy@t; zMA#z1{_*b{@+%8a&I@YCsH^?6(Q2Bt{q3qEMnzNwlP_VQnr_h{IqS<#XrGjl0V2y% z{~RA*{5`Xl#V1S;krFE9v(jK?p}{hn>lp^iCBt0 zH0VgD?K}Z3SURno#&=3h1ntvPyJv^5h4tSRjn6Nb(T-p8aMDKd8Ch-dw#bd+CnjR^du7DdN zUw%-#2ebQJP%vv^2K-gsvXpy5wWw0D{Rh?jN3*7afptx() zyRLsbPyl+UMnpv`CPq)#5>r|@j%uI^=EtMmmFgpTfvl4MsjmrO<-11@HSAXuEn+P}KB4!^Pbx#*({Mvi zm+wSV^KY<$?m2KMQAX9QqRClVRpy|>xenCFXDmRx+u;hu<@&dlY*0ez!2{_0?9X+k zh}2hVN}oE}1RNX0Yb0;Eaz3?bN$SG5I*YkbBUOhAl&mc{I`QC{uB@4{lCQ-v1nO)F z14cD#4HR9V1j%nqoMsD!(?M&w(D;AXdg<8Nlg?Ad_G`trdvBTAQ$TmCWs)S1XWe0+ zNO-y?bJ111{FhQ`q+ON8eBk*VN^3dUf2-AQ3X?Oi@6}y+53EyBQL$OC{4rgf(9%ky z$8lP2v#BL%DJvyAA&+YT6*R{ldkWc=*4WME>y^ODA-*|YY__*~+y!iBj~!ZAFBXM{ zzRbK%bd zo2rG{&70Fl>2dyncFtp8Xs6RfcXCrrZooHT1n^VH0%|%icai$;KcesPPq18*(W{at zHCQdqb`P5$B;Vzh_M}7TJ6PICE0ebym$B*o#gx1c^d=(i@N=^RVQ0m~QPH63@_7@s zKhG&*Ax=F>LrY;ba;}G#o+{4gq_@GUE+AZ%hlkHCOs5Iha(P?3qF{sN2)QEPesIs& zjqw{XaXp!@=~Tc}ak`n?HL*X*;&w=U-0-8eA07rS$;19v3#e_`?}jUnO5Dp@;%*z=B_m6;tftB%*Dy}Dqmp)NW$NDN@oFW} zB>7{HY*yT+3w(6mh-w-0w;p9fg&(`KI3%GEDcDwvY= zJDh+1TwFuM7Cb@TQ*Ru^53VlRjNO~r;bgMu`}`cjE_kmTNO2?>6uIGWb1Ysf1X#3!pMeQVs1*{@niWP| zuv*%^tqbg56tN()w+ZOZC6I7FAh*25=hDy3KVvsMJf?IKf;~9cQ?U~E?g=FwUwW0E zsIFEk_t%J}5j@7n7q2=B_cL#Ix;Z9zip4`y5-+d?qmx2^R|d9ts&QS?q>&#EK5wj& zh-_s#O=pMe-Eir;F>mK|)z?5bUS4Xz?xRKRe3exS%^5ld7HD61a0z1B_35>QtjAC? zbWvEVFqj;q2T7^5SyEOH4AuOK;`M;$b-pI%Ww^#g}cRG3%B3PX!yFL?V(!ba4^U&^UbQQHUc=5fjfCd zMAr)qwGD~2J`D{#pw~w(Myz$78aPCW0tL!R|8}d;CQ5fUQGj_WN{}w(V|T&jMAha@ zhC%xd>KdK+o2v^+y1#`Ebie;PFOEjob(?_Fg~Y~KU;k%;$p8yirfKpoJ^lPVd-qL~ z@s0N7usbAe_ahfM9*Yz4af~R(H(<=4TAo3b=$#_)UNrH z#XM?vOUVomtt6@D+LYL)OnT!R|5e(Wd2{#O>QGgT^)*~<;>c>V(dmjmhD1v4FGby& z^HUfaov2!IE0*?g$TR^XIVOOGzp0JdV)ymHMj&C16B zx^;?jnlKqSeF4Q*8q)wEL1id1L36Hzh`O_*LzS{x9faoi;VMF9FDtIs@gTx4l@?TC zdDQsO5DWyEqocA*CrR;;icD7lxk{?BIlfzeN2nOIarJ;k>o}K{ zx?F(x&&!II1*P)PIhRw0lwde1x+L@s{+5`FAW7X{RjbzPZU?SYgE2FB6u+Hm;M`*_ zh*nOgNgrs{9QLV=4k~v#rnlF0M#*4rvL zb+DYK6&B_IDha?(KOHc!Kt@nhNtvX5xfPPe_7dQOEyPu|Q00w`^zAkbP>7#goS2x{ zwMyuD%YG3||L(n^fuvM4ofLkix&p)OwYKZmY)6VbpG{>zVBIYa9VPVQvzNa-uG7r4 z(?ai=OEoO$4PCIcQ&O2Kn9y|L17rHZj?jAESXZIg@yo_WZ~Y{NNeCMS3gY-8w)bJ%whhzVRK4;vGb1A*BSYp368tq88GlruWPDWvQHGQp ziaIpEw|6amq72&c;i2*t<3tu;abDh$T8(fQSwXX{W|`_|>l=Y_ZG_+eH#>cQyVzrx z2hfJi_YrWf1e@gmv?vRUGOLscjrJz(mA22YD!OZ_)!WfxG1v2cB%*S99r^Vc$xRc+ zt#kfkntA!NTOGUv-h>shvEHkyNg?nUB)n|OZykA62sL;DIXM-%=lYL=;M9qFYky!n z`hB(QIxM#%_2(rwPgFb(%iddtljOdb39w6PhNG+YV7IAyO*{R#-f{PScCzAvFNB1O zZ|TKg^GpjduUDXMGgTK(CQ6e^Z;yf+VBkA7e8tn&CQD^C&|4E(FDEJ`e2LDj?id0L zwjJZJn-x~rRGhAX>C|!`usS+aj5tpBqQgSdROmJlnlUBbw@@XuZXhjCjEFcGUgDUi}#uGLuX*MJ`Z#gUacZn6U?_MQBd|hOqEJRjUtVz z%|W(?)T$`8&g1af1u$I~zzJNw>6B}@wnnQk57oubt}Zft<8BoK3OmTslaatG-|x`# z+V3EfaNhME8Jk5D1q^Mj7kKL1GE=B-%_+xors`+{7RuaqMq%7vdz$TxenDQOLH0?2 zmx-!>C?m-zUgBd$!~SatF1fY)~+pTr^cMQ`=9Fo9fh~o0L`eiq6bL-87V1Mqa4?8Ohczdc+i3U?*)To`U zzR+aN@p2`)xtuVR@}|=(5|G05)h1Zli3UPIPKQg~6{<(wSy4jC(!)d0M^V<9puEKD zPFr6*_;55rE{6D2ae>Zko z_%k{#Fjze#z%MJeXgHc;Zw-Pd`LsNA&BGSh{U;+9jexF3gsdCO3yJ6Fl}Qat>JWV_c}MIo_3#Jjq6V4-Q_&|OARAaF7VG{@K9n_| z`NKe?W4?LW*wEbv3n1McT%1cZ;j*%9&}@Yu+S}DO?Hd&*&$I9EKe{Q74E*H}n8ycu zUb-E-DoA(3@9S@&(c9(aVCu5+cP9L}NDJ#yY`P$%^S4oLe&TNbfdaAX8NcD?1VfSa zOuihz-WuatSPVg&M>+Xwk&T6e=)0G!qq2yy*DJ8Orj)t4dp$#=X9<-NNs$PwvaEMn zAhVH_slRmS1ZU6RUo)DNU`sen*GYsUb3vZNix4wW)3dc$RJe-oY$rm&i`&=OY_^1i zuf`=NLTGDfYzmd3ay-hC3k1ba_6>zXrn96>WFxx293w8LJhHK+-rjx|3XaGB^9RX% z1+s4tw$m3A8=VourxlZZ4Rv-9nZbggWdaKhG9b=$x>Cy05}%t}i_!+_4`JqCK(ieO zbK?*B$GIslFvJ_O^#++2nI;Uec@Ys^%41&Rae&C7{R?aCV$n#3_G>9gUc3U%LJ+gm zFpkP-oik;N48;|QpFJ1KP~XvtrVZ>fol2t65rZy=Q3;uUJuJxSX4BF57WMdq(`b8P zJsBzH=dZQ-&lcCO7&nS6!bM6Nm9MU2L$gF9~na#r(u%L*`&_JO$D9+-=f+W9PgqF#8i zATkF||FMz8eJIbx_TXdBTNAtHU6a|wjb+Of$q~3F;J1L~%PuQ3^r}qwO5!Iyyz{oC zZl4RA*t-f8UzHDE?e(6|l|pK>VuY~MEA@;fT0%~itZh;1`6aZ$ciHh$95hvC4?&6^ zab^K^f!tD?-ALd!_VAd;&qA9=qc?gk8ps3hW8fKw!mL-lQwUjMPHEN*_HafDF={-K zC%ra|9+P+IVOj(Z(_ki>-h5VTzyI}^;p|jC`7CMn8>F?)p*J+xAWVN-h{Q@OLxX4~olWCj7?x!e%EvzmV?5P&%Jzo1(DU zYa}zU4QQ^`aCL}@e5Fssq(Rs7e*1%@1oqaEz0&>rkmpXL#ttY1gWOK|K?4bri4H4y z@tE+~1J_fsADeASJZ-zTftL|f)PpGvW-3l&nK8yeyS66GN*vX?T&x!R0m@V<(B0Vj z(u=zJ)?HMZaLJ>gg}uc1>{e1pN&%5dr_y5-QF;AnbKJOG{jnj_BVcAgjA={e>K1J1l^J35L5b*oSXFO6xGh+wC(RWSv(cpk7<(Zs{%D2li zD|3>-@((m(k%K-P5(1*4k`jY^fxm`?dB!4i>3fG#@KTVZ7sJwxtDX4vv&clePiGY= z(oeZKLi;YK3ol$;{UU*b^4V#LimwHEha0bqUko*-OTa$VW-<&{eG`NxH*yLrXE-W)qy#GA6a3oa3tA|mLZFmq#&ifW5Y z_)YM_*86-;$udzGxrV2+*)Fjm;ov={!o$-aEqE0VD|fqG*~^?13)_IH|G+LIu~2LP z^23x*9>4V4)>v*B1iR7)S%Ixy$0v0%Pn*{0dfiWO?Qmlhcb36)^oKXcF;HI#2{G`5 z_{#yV=gYoB#q6ki9U|T46(x2MQQ`W~A^y-gIIEy&+xhBt6=LL+cGszgE@KCQ^+c8= z<_AiaH$!@q;Czd3ch6E8VA82X4{D>ct^zcb>%a;d2&N&jFiv^Q-`PHu;4USSA&)~p zVgZ|7K3*<*msL2cb?I*&5+FPNLzh$DAG+jLv{x8b8gqaq1BrD5&Uxi}%>pe2quX3X z%&hf(T{gVVovuev@V(mL6s|#&=VI3Z3+b zL;uXoPDXr2VzJZhXz(}?Q2wo6wKbx&r5wl{Bm&t$%74N}Q)a~ogLkyGex}w;rb%L4 zKp`yJ)~12!^L`K4#emK0uoW5R)v2zo{tIkmMMlb^T)ZeSzmjIsX|}*c6Pj7tI-I-b z9YZJ}@n_+38?*wpy!ILf71h+>&Jwe;q3$GgN8&8H7wgR6zW8+5ijsW5<;acY;Wfb> zi<^&3?{tR4MBfB|7`HIh*VlL3j_=!7TA%fN{=6Z=#g5Av!(fHPg#N>d?y(jlyf<4h zl@>A*4wA&q95#WLwjM1w{^etp4h#M-14EcyE?E2}lal8oS z>8~!28)Eu!!Y_v5QBq%88=JGl!orzozaGB~K7MvJ`Zz!AknEUG&P+tQVs$_!J_^uR zc&`VX%&!i0l!#pob0(L^ebed{N3F*e1`yN( zXjOv=?D7)g5@_KttiWtT2ulNc&fJTkUB{g8i%vO)hz042ogLM*G+<5Du zbKRF|f}MgT5fSYsL$#=BLk3&d(&Z4N!L3PA$_lD#E{!IwJxteqZb%0e@C}|l!f+*1 zV12Zn8l|GNboXE{D*gNT)bJ6)vnSM)(*AOF+R&YJ3Gi5iYg2|sHSm|v%PWMP{HW}VW;YN zH;Mom#L3_kJ{-1G(lX&A4W{fbY?kdMZv5YKYP9(>1irdQv6-)&D#tD1#duwK3d_wF z!mJ;Kx_EeMOX9o zalLkojZ(wGyACJJ^gVIt>6i5mq$W@nTnsp&K*PhbJu!YVF!)k-y8Yaei7DE9LS#KY zOC6c#ibsTv5G^((=8R^CuW->8)5S)wfF=2gM z?T%Of3nHG(@k0caVDhb|D67eAJ`|Dw=Q^&S;7@_1&Gl}n&6W1=zpXmoRcp!hlz%1@ zF4tZ7$(SjCHKjZ}chfV%;jp#5#!NI^xCsP~-*aFN&$2s&=xb_loDOrbCn2Y8yV_E2 z*40C5B&?Ci)xabmu&_}VZ^Ue@;$%;bel7Ks-fXLIUl#}6G;*bKkjd?nY72vdwVNa8 zfwgA9u;Tg|0fpuWU~@`0XE&$1Is8Lm673k;+(oa;vGY%Ym3=pEv7yDQj=#fY+mNzdy+|f8kuKEf(f$#;Tmet2^?{t&O5m*WTq2u6Pt5`7KETYz} zZbMG@mxtU>xrQd|+Z>`Sm0_w(xuJQe$E9c^p=lEUOVxNK?`@tI>)y+*Y@W zrTLEc7R*o4N6@Qg9#okxuCYK(n6Y#wDk?fB6*X3sr>93(3uF{PojZt}6N9}RxXnK{ zB^%HoM1t)aIyxnCFN{-MG7POb9+Qxwd3y40zn~5J{kDuhntfn8!t(9>`Mx4qU6x}5 zE2QPC$5$KR`oO79n;(XLP1VF)#Wa(!WF&LcNjL)PhC87pD4z|d?x6@esB%!p9qbd& zmTrUn)bs$T?l;#k?kfn_+@?QFbIASKt!G#+*H7Mf-;OzLC14U6y)`6?i+7Rash~@| zp&iZNgBVVJphNxn-nMoUW6f@L&X^L4GmG9F&jAq_40=wgT-P~)Ev(J1O>!`x_NfpF{>O8Vzk#%#ocG}C-X&WWuR}kubMghu4Hw67^E}(f#wm9j zpNYKccsj{CQG*YkVfEB8C|}q&KH}`OE$NnkR-Owm zjR@>8cv{{1YsJRRD=q}>9(P6q0crM`_Pb$MS9@*Jn<$9Nm`Xz-Ip6zqzJ1 zCZCplXM-$DXd&n(IxO#6RmOPs@WkWWQ&ie}tGlCNacqi=xVe`(YxD%%-UP7uND-xT1{6>Z72F>QI`kV3&&{$9kB-tc4ag6RzR7%zPZ&Z85agh_ zWKDv*!&h}Z1%ti3V;DhVC62cH(}(wQnbNNl**xl15)9^VvzWhWjVw%^_Lm@QBbra< zY(CCyoV{So0|Rsn!7AK|##hB2)V!=|K=)K2uz7h&y>ziQOjg~iQg3*2WZcIgEOTL? zLLd4&fvDVCnbn2Nfq<4o1;DefHTFh<1@AdTVoCsT2uR7~avtMBqw5=#ZE9-lvX^Kj zIl3D=5RM2)NT5MwNjp6<7PRN&Rdw99IuVMfHQz&)Zqz!te{r=Yi~9C?aQI3EdZUXU z@Jh;meiU{c{100B}Zbv^&jU|g{-A2KAGEn?zfjQ&RwB7f|@8VEBz(uBsZ2IX{ zSX+A{z4bnT>lC+PNSFJ*dshzyXQj6493JdLd|sV{BIw2Fp}0B^G6cGoRMFKLEq^Od zc)(Lki=JbN{(Q3)(hY?jJGM0#dl+({nV2n=_+?#2_IIG9s9pl9&DGyqHuHB8r|^Ma zOq#9!gyNTm(0at}Kc_wgiCw<9v3H!H7v}A}hwwac1WFR6Zm=y@6Y$8YSTQ zEH!E{l<<6dc5cNu1N|GxQ%@9+`L3q<$@xkfx^~A-$t1tq_4hA~3ehuo)03`4hTSqr zo=0!j0EAd6Q^WOdK16{^T}t&sK5jC&`QeyWwD_JpE*Hi&8p1SKo#3qLdsaqn+m?@C z0r_Yc`jQw!73gRKXdIE8EPs&g&FgxGjd6KDb$+I@PapEF-cspjt(IlG?UA*9N5j&q z9f_Le{m$3jVvS4D zSO6P-Rw?5NBtQl{{;jfhuXi@J_4?FG#OS2%fX^q^)@RLj+DNXNEy!D@@DhXIAuH;l zUiHhSl=FzII}t6IMZQ`M)adaF(pPhdQo<}T;P!n!AGb0*3IybaXsq9j;o<;({Os{( zR#F0IkHPt?To>R($RHJg22;^s+v0--Y-pR!j%Aw$0bT)=^r4Q@j2hj=tUu{+4%9IC z{yf7r%k|Ek1j&I#n6N7c$@>ek;l+UCvax2pwRJn+hIU^hJAHwg#VN_a8gb;=z~s-b zax_L%73W7Vj1?LNh=jSH4(V%K{C$%qnCojJ>ByjdWDL5%x0cJw$rbbGo0zT4Oxykq)Dv!3jHgHN&2q{7KSlyycR zg?f>Js}P8tNnBoDjv@7v`SRM-%q&2FnA>5nQRbj@A12UHS%uv%wbkX$s96Adk--3* z)ec=t7TNgZ1HcdZ8OVSU**6s*fnmUE_JnX z_s{^x%t_INGG+!kENdV|d(uUM_55)dQr*F+ZB>m$hzsOL88XaQ=tZU+Xmoa$iTDUJ z`S@Sfum#C(dY08GJa^uI=_|X5QGbQ`h)VbyM88WMfB3lB?I(X1iW^s_eZj($4gRfW z`pSOP3n~hdP(FGwXm>?ABrK8zt8y?lif}*{_BX15(AwS?_pudhv5`cUJVLe}&dS$o zXD3oSzH&gd7Ej9YDMO5-7)Njqp`oeOV#lQ60Ggt`K@UvDW(#*qRd^J&Y^8U>_tH_6e~F81ePFn?76@o9xS4{Z@Vc>cGrqF>zBlw zmvm;O6UPQjF4Cdx!ohWdZ;cqQvcla8bH6SUAhQn(Cj!vg9WE9XyD{N{Z-fIoGT>Zu z#yI2f$6PfGa>W{X;3rnKfk& zhwd?yuyBt5u9sgh26}eE%3Ur@m)T44>12rsJ&wIzz<}jlyhnJNeH?ORr1a68wCE-S zn`<;SJ3G4q;RXRA+EkMuSCz$~2wrQXODR5tMF(?ZOC z1z(UM332P>hs%aXTKv`?(Pl&g1ZwuxNqF0R?hkUs=prY%Wd~o(RhO0)?RDQxrX%7 zM<0UG>%^Mipi))~-%dtWX3O7=d5w+Ze>(b*zMq-TD+&v5J?w-{+LS1ar1cr}i6k+^ z!!)D8x8xvO7>WD2r5+N4w}uP6{DLM@yIh}3jbUH{fsP&bn{7L*m<+J{!ln09b$*6l z#PYAvm9-qweC?GLpeZ9;R7SmEB8zjXY+cXH#Yd*yp-Crko-J*mlGdCbSQ@M8_PNQ< zfK~pSjvDuw8{Xwt7l`52dsUYx6m9Si&Beu8B)q1IC8zgxI(dl;VMTJmiss8Tb&-+u zSdq!_C&U4_Y;9%-$D>H{Q5SHzpC{kEWB(wCGRMkRSHDzi!)fhXpoO3}dpu<;@1?Vr zvK4@lE3kZZ8eus(uij+!mIXOOy9^1J59W!aDDt!j;Ri;nL<7Zr|+e@%Z%!kZUTYH$dYdbF)`DINw$`QV_apVVy3kPUO4<&X)=s z?`5Qkv(Fyw$>~?rgqUXpM&yvfHnBF)@tP&Vq%U43RzhPTTLhE!ZJ|HKl%JEg2c$Eh*{MA?3b~rWmLG4klH!m_eTagPqG;v>Tfcll+Tbk8 zv-xpp`g2mjpyo3@eW8tCe-!ZwWt%=T?q3w!8Be7bk?5NcQ8Es#1L+5r@c_+*Dqm-! z`Z6x(BPh~}{2J4OH#%?=Tt*wDjPdb`;h`!Tn9<6jrfxnXtor>tt}EFkuu&5Fg#}K$ zS%t99wneaRYn@&nPjy^H1;Cg*dXwMV?K7{gIoq0-m5ZC5?|Td~%=H%Eg`x5+1PFmB z$P5vEJ{DNrB&X^)Z9EI32AnLl@edjTRHoPYYsErD-vR6H3#V-9pWW!UZb(qB(Me-j zg3gjgj2n(BG{3rinOgx;I*a!o0zpiLl=xm^ycxTTRG4{y6io0WzSP?4?@_q`U?VuZ zZ_vsbwqr@FWJ9q40RjyR%bJ}jn*%eA%l z79~VvsAfFq=lBQ->NgPvNy_&2M;l6PEQG_M(m6Msm5GY_!*+OUx{K4@U60`6bQ}-B zH)TP1U3bT^X<}`)IEn9GWcr5bXP20WCD*C?oHx3x3kIlu;MEB?tsR(C!QNV_ z;#CmhVOCpAt#BcGUR_-a2J?At!d3~kGGm%;wYRskj_fKC5@ZuHI}ew?cMF0meeL02d2y>`c}h;{%kb;=(*KvVkaE0wQe1dNmy#8^~Kfu|Z)7 zfV=t8Fns<}eZ2k-($rUm(2K3Myr@#5K}e9$!5#P3BtWR!|AQaJMCxtVDlFo~B@zGG zD)lWYl|o11Uf>-0O@sOGO0v}m=ZjIdvn0G$i9x@4p_u|mwmtv{M?IbC&u`aMN#Ppr z?kWJy`fCn_ve^zBi@P#u%^uH*gTZIwEkn3EnJFnBZ*5k8v}TL8p z+9vM>9be`n5UtyN+ZyrVJ%oI_>}|k=9(p~V7|`PBg#nZ*06fzvNkv8yFX;Znb-|Xy z<^t$6q3lSw6(VFd$Gcl=w58~C$bjL43W~(#%cdk84$j`CO^EtH$YB*9kicpMm!h-g zq}h1%o=uW5Ka?_%_>|1QfDVtj$S zu^E0cmGOClqw*XpE>fWyZLIe%rjq!-q8HI!C@^tDCJu|A2|kjHj0}yBOOtsasdfBS zlX`_SF45t~$d%{DOHr33k6lUs&)0ng%2Fw`Dh5{h(iCK!#Q*s;Q=du|Z6;TiB*5}T zv}{{Bw)&p=kAlesgajR-Tgu$bATuN3yrce$O4Z+^!7p1gXPJX$%&3N~;#@){p;+So z&mDPV6~kU$+DFLHF*8rYZ)!ID`*}DaOw|tTZ)2=%O{2r3|8}aA1eb?9VlYc>rga}; z{nb1$!z@!(48CY^A~&cJ|NI&F3)*`UxMB=)^pe6vlyl^N7v)nZa7k(Gw2IO~pFbFX zKO_>fl1|IY)ZC*wUhO+a^H;tEGoVr@MXM6eulwKcx+j3~8`>#B*MXHToZ^T1tDl70wrEw%Wi>hqr~AS!n-DL3=fsQud)e!)pvlRUEX;eWqEadGw# z_TPICeJ6=-A+cHZ^WR4a4Jg(5O^dBbk?^k!j0ehWRCyJOivNEu4hvlTe`)xP2Y(~icHh6ct@!Tlpy-o#B_Sy@?LnUbQulamu2pRT!s zHKFxC$Fma|J50GtN86N=5@_e0-s~l^vML`@TNBXLEm3@Q@Hy1c)s_1?(7)6ge<7;* z0R;sM4%m`y*vmcmDK`hx^>(|t>FIaV@)GOK&IR6GUXsQD0J7B|sZy?yNU!a9_-ktV zmdE=v-S6?%p2JF9)y}2O{=lP)uOp1k+|(5Oa$Le$XG&!vo5FJbkRY|T*6`1=-NU%@ ztQ{)TJlq}u?U=UXW1u*AT6n+wC2$s#$1Tq6_dtVXXB>VnZ% z>$PUX$9aR35!B~X;>D&Q9Uk|)>@3Kt!L3$>#vF5zY`x`jpoUhL%~&UIn?OpEBQB*J zfrFD%fkQgAYGD7*%8ccImPD+FqBC?ED6e2?Dm+{fo}E5}#eay^nBJb!(~n0+V&yBU zOG}UDiAA}b{8o+5TF(PFg<$kgrNIT{=I8&Se3@vpT20MN)S1rYEp7G_K|(}~3Jnbu zy-Nhtlo+ZsB>P%j4p!P!Cjiz05ud%$%2la7dV-ijR6xe3I{vZs8p`@>PfB)(>1@ySk!8Z9+-=$gX>(dr+lkeV&ZhlhtLV+xr}>bN1yCWEi)G%B>lXyiA{ ziu!RCh%xda@!_S^6U)nO%4LZ-^ji7$)XJr5dEcBk+Wh@{5N7A+`=@(+C7Dx@oSax& ziBy%8jG2$HIziAt=Umzd0mBLkL@?9F)2PpFAM9o`%Q;2YEKy zF0k=t#8<^@@i^XzJKNYa(Psc+FyxpBRMzlw_#T+IH=8?Uf__1Y=4kzA?EL)1(u1MK z`+c5|sO9U`CH6a#q0ryLaSPQJhlfKoxJ^%=!jkAQ{;^%W;t~?ttyY|$vB$Gi6+gPT zs9IO_d?0;*c{o!I7`eW_EZaIkF4O7sK-Qq=S#Pz=}xBiu|>szhVXlY-pf)Z8j@j)ZN!n&hD!$c#mv)eMs`WEqUb0C8_)p?;K z4ykrB1oiX-Geh>dn@v1RcLd7IP8J7RJ1&#`z7 zgPl@&ViDgR9P)rO)ug&~Ioa*E!GPP@=6EFdSAv88M-^snoyo-3;7JDkIQ{cO4C_D# z_;wc2PGt}0Io>S@pl06io7?~eN`HF=el zkr5G2ZO+zFMBF-8QaKhSnoY9)1O*6&^P>kKgI6EFqj}r+gy44;3p1uLsCZ_2*{I)C z)DYm2Q}~>Q%T%jwPWTtgRORH`0hyNEMkW?Uv)N*jJ7&mQ8)SdK+T`S6aZ$~E@B5(tHjA7cM{Y5Pt2oOjI^iv%e74Gj%H4>jaJeH!!< z_T_eg2nx|+%>;D2TiTi;_I+B-_Tv4%2s} z06mT(vIxC52-(ib=_9i$UonMC{kW8pGMmFx9GJ zky{&Wb=vt;-badX{KwPhNA0$oFJ7#7qBNi{?IQT>)^DS}bRgi-_4oG!+J8#4s6+~X zoyGlEj{>yoORxa>?Cfl@h=C%yvY2A{N9I_?oLk5`F}prfMi-!l6Hof^tFNy+@N8&k zJcsLOX=xGj`5U2j#>bh#LlQ0I`yxheg+ z-%dxfKBZ=T!^(yOk-pLcp;$A_OawHbH>^@+10QFK&YD*=n;?k>>jmOcQehDh%*@Pm zPYAphTJeWVcmD5>lfr;g<^fH}1vJ=|kR`x)uUfFP7b^+`U~4wp5Zby&Bi_-W5^+8K zT7SK-!^!^4%*5R7e+YSvXF3)dgZ4&7LW;k6W0}Qs9`x(NSn8dhuM1>NIQrqN?k$t< zRq%9AY+)%ZXJ~_h-vd2;R-b08_c|&{2_RL(+vZZl49EnE7IgnF zp=#}~B;#PzA2FvfC&%yE=*upriW&(qnS$|IDKmv12f6VC$8ZSHFAjIgh(_8f)|<`O zJE8nn&{t|j9g5eAeTY3|ysC6o+nf)O3|t|6XR$=5Gi8*s*4c^59Mm&~(nO4A!HJF7 z#+!s+4b(EYjFdmeV5X*+Bi4}C^EPX@v4L)hQc+HpdjNOn{nFD89ro8;zNexrlFe|t z+OILK(8%C&%5FXTA?A1(AJT{2>9UR!-U2{JGBOJl>#ke=IB03PZkSs#FdzFf0{l;9j2mhQbH~6*2E~V8e84s&-0dJa^7%ZSH zRBS;;N+!uQI~q>=ebM)qGI}CQ1pecfo&2IgVHp`hwv2Y{JQ$c{D*;;anD<`X)4SGvKqt%NC27*ZHnrt(0}>V_MRCRsc1MM;X&@h zMP&;}D4>_BRfVcZ{ZeI!it4W>=>^oCg3#Zd5u zaambpyjj1FlH%{h>Dkd}cSmYD@~0Yue*1y`u_=d#hedLPGxPJZ5)!MO&s~576lYzb z->iSD>C2NS(6qO@G#W?t(cd6b+I}r*d>oBKR3@d;HcKMnjIy&lZC~t^T#%BIJ`wSO=;_Gn zo$BvXQ=Jq@h&2 z*;M;SkA2Z%w((5fA`lF9A0TPBdV5L8YyUX`gOCuaQHL9>3E&)~1TRA52;M+645-#s zX>~O2crOF?pHcta!P@&44&%cscH4C!_l@ivKUmb`xjM17M(b};AG0zu?M@z?Bw@-* zV|gR6+Tf?|9{JlG?}wk<9Gv(d8c1_G3Q~+7+LwvOr9FRjokTv+@pWl5l=}1djs2r9LYH%6aVUs%YkNM34OE z-n*N}+nd|@6^|v@Vd24`6-^bDc?Y-hJ2J7TF7U0_Lw$)}eTV&yMFielPGYVD)CxYkXA8mCN-75!w%J`KZc=PmTK}$XF^Kdd)9&uq1b=B{=OxOb2nPmK8f#>UTu?cT3yBP5~U*B2&+O3+tx zv(0C-eH2kAkPOEVMYY#-iudFD5R;D#G8H@UGb91`7&}5tS42$A?I(zq@KEg58<5M$dss62I=r^3NjOyqZ@0I_#XGoPs{x zpG30m9%ne^S9`rfBWE&shoT#iuuH(VLK&WCXHWMIa4^D}MT`gvAP`7Ixd>$S(y3JIBf2mQ zvOJQ?d$S`m8WfDx`}N9K&-C^(Og#*=+)&P%uQh;?npc@8$;r{X2oDeSrw-L<@HkLx z#bAJ*Z4)h9YhP&}(|o}pdg;y!ivNq9R-(-iOFtQQq_N~ ze;^DDZ>tM33cOvh{GaY#u|(`$>*f0S$w_fZ$=ne}K3PVs#9s{bGce0F}Zz$oKMjpHoF{jNmX}`Azh;jAn3$ zr5>C--6MvQ*0rDSVNsH(rgK%Q<>uy=zz+dJ$nU5@6mdSV&1N+Vwrhn21t0#}7}O0h z_$j|2RF{)!2~|}bq+;$y+YYBAXAh5dKrC@qPOp}hD{3ETS*=Qtk&d{$xXj7D_I?YX0u@at7P@!zJ%@bK`QPgeqTc)>=-#tM0Aa_L-oAg>D%``t!sZf6Al9zyO{%?A5> zKzQ1nN*XmYK0V!$J%xU~LsJzkqPv@fjg4(%ir4MoIE{UsM7|xWmEsyXmCYao z00|GsX~liD;dFpthG1tTU=n;B_80{EIK4)3nGuAviIxNl>PCb|&sCoE z>DM*XH+Vb~{XlN^;=R8zMxtPSe>H{i>igs&A1*IO@tLBvrFH)1BL6uNuo%0$g@67$ zh(gr@7{gD48l5gL%`Pu(Mn(*K<~kADkdO!{U3z7`>qD$U3W`s4E+=bc7j{Td=o%Ut ze*-Xr`M)^bC*!x&I4FBcbLFLlOU-t@;o;!`&{0evIcDd^!g%D=naMJ+T1pVtm(4_Xjr||Z4 zwWuqyP*GH@xFlyTr?N0HIo`~fe}614v%68&T897+zvoT5N{*FgH2z86D)jQ9_EyO~gaC=|GW+ zC09Ems_`7{9@nLtP4br+^5y{8XlY3!bc&RpkqCHbYmFutpQMZgLM$v~tkRa2d*Cg^ zX3%(p$Mp59f~u$BS$Rmtu}hUY;Q~gZAO8f+2%eJ9JSHu zX+=A>serJ=bSm^w;=j4Bvsbp*)qvg8FDjxa&1oRB{6!vyt*(|FH$NGSNSbNU2va`~;oqM|NTxN@Zd zO-)Vw_Nq^oMdQgSF`4?7mP%H8I;rjL9{&QeZ|UU<%;P9F=9fD!&!z+8cY4Vz@ex_iQ>1Kx~YjV5s$|mkP~rpf%ey%qMDi(9)J88kb43|VD0V(Q!)UR z&{CBHS|;YY2UJ`h*U6u!tF7(s*VOEkwoi9<8-_gKo0S*8AafrX!nr?WVma>6QI<#Z zbnBg-V)1V{q{1>B<6&01zJC2mq|Bq2Wp{o~LXsm9A~99-6#xncq3Z0_Tmc&qB&)r# zNFkTe|7Ds)JtjL_?;n8SE#nHWXDr56NEaewLn!$spdBwswY9tZaQN5j(9wBex!ev8 z7S~^~z{DM#9zL9|f?FZKnW_@GT)!ZD7s;KdH z@t+(L{f*|CNqN;-p@#?ejr-5rf+1h3C}@QWa~YwMvh(tUvw03_qedz=HUz}p__oT4 zX+EBIJchDrSTo2)8-0k0>AMLe->&&iv$!le@XOzmFA07&vpUBh7jvH}fm+$$kfuX& zZu644F5U%hfGS3unAb~dIIyy^(t~e(VL??>YEjplH^y5Rz;bDt%KL_d%TlkU3CvKiS*I z!Kt9~hpS%{7E|+eEh$Q4kKB7$bmrO>F$H4J;AK;#Fv7$P_huJ!k01Q!O_x|M8f^h$ zy6M01?vL4gp5R%4tRtt=>tR%#tH{~9DwVaYO1-Z03K@KT9FvgXbovC{CmroPQz)z6 zq%Z8H!|NF-&Fvxs6Sa_qb$pD{Hb@mHdLK)8SsR--tmG&g*?@Aa3@hL2Y@Y&UT$oI1q($ zSl|FT1h9j554_Ee_Xs{u`1{K#bAa!Rbk<0 zCH-@{yCr(5PH;1+G}6?VMT#XA+?5JMIjU7!3SC~SvGYJYVz?Bp4wL}$zM%laUx<77 zY1QiAUudUis8(o=8!^pSs#7sIU;gYCj&8O;5Hdh_143ck)3v%LsXbXBlnmu2;Px^w z5ZWwPpTT0z$Vk6A{Vj^d#AP}(y#r)@B16(?JXEBl7mw86eB|L8UN%J$Tb&@HpI#a9 z-1}>6iKh`lO@3zLkXz>(+9VO&1PWkooIBM^mmi2OV0!{vuVW>FW>^yAW4%Y1kKGVq zZE=(QIWCxl@cekb?DF-4Hl&Ni{?j%9$-B`mV-cd>Cs42^o1` zwDf_QnH74uczVrIiIY3LL?&K7H>g5Qm)$Du44%(XFqvcd|qq(Y_-2RhldzOZqo_4~X zm3NyHf&U)-B&><*sFy}`6ThrfUNBCa?x%1ZwJ8QmgnTyZ7zOr zRZ;?DNd1b3cfQDnXKJZDo^kovb_+@9#2mglo_d}?;XYYv48+4h-_X6jxoCCVv6w03 z1K%7oJSWotg{Y2i*Yw(8wDmN@0XY_n#cbin#v<7)@@Vg51g9k*VL7U}p_jse>R35d zL{(cuG1L%|bhHhKx1*^J4xPgi?&+dV|#;B z#pSiK0K0-i9^{klU>62i+c2=|7oqa9M-JA598+xxt!U!w&C@utvH&+u;}tqZT44GB z5wpeT1b~eBD^Mma2>D~~MU65rjK{WE+H$rO`Cv$?5NkDk?2mZCbnZQniR(1xPimJ` zR`MB5{`gq8J8h}SVhdv<;eMX-N*UAQK8Ha4_Av71B7&ITS?$HN7MKG;$Il=21%=Mq zOULHCESp?@pv^f-$Ft$i!xQTH?@R~lg|E!amSd$@f^P*u9~~Sn>x$$i(|{sGgN84k&K}=*#I^$1MQBMq{9%xjy|WA@PG9PvOoIctJ)w9yNm&%`?;&@xUK5xoIj@ z3F$Wa5iNxjd9&>GExJq#*6qg9Tx;sv`aCTI8O`Q-+W>53Fm(RdRJN~ZMCKUM$(V8j z%lOzD_T@!fTz`wPb&*M?htl)0|Lo)P#IH^Ss)xBlca4bt-nP}n*RzHuoUYm#?6|(t z-(}GI(p(^pGu>NtUxEu-EloGrb+4O?Swd>!r{b6wi12BmnJl5BV@)WY+*i}r?7rV2 z=2n@Zs;?@EbJQglb4op%l~sJvap?-jMCqEd&eob@GxDkwF+7W&Is0y&Tk2p`b4u#F z(arupb_w=ouBq}=h`|gB(-5_WFuAd{EQytD?g<-U|F+G3+s&!pXU{+C~X-wOp{4A3dILC=01M z2dW^UiR{eG+Rd)#i(m7Ck*lqvfY}yZ05b4}ax9h2?eb=I#&kj~3U8`V#!?9*PE;!K zBQ9>e#neTZP`z>3ZW6sVm0?!ah5gfA2w?Sc(4Gh2TfBF}yr|{n3ll7Xx9XKvX(HKH zkBIoLexFad;fjx^<+KT$6X>Jf5SgbjdI#C}H(@HlKP-DzZc&KxSGJ znfpi$^9J70mif!YJzYxuWa=P${h(wxwP(=zTRGj#RUO-3(*_Ik9~s%d?zh z^sf>gHgq*wfNb0idKGAnP<8DMS6w%6vuRyYNwu831b36fgpK;e2-0RHsg#s8`B}N{ z=K8eJb0!N!vkK#y(o^Qhc`4%iRLmJY%vZp#mzUtOBV4zelwDrE(+Zimk!H<&H2^;I zzFE0n^z)HV~4)KkA`YET;pxiXfmfnOWdD_NrMFc2|yrzkM#tU0(K+t*_Ruv znZff&)Vc})bD;t1<@CvR;kD5QHb5d|wAOJ9dcIOy*Ey=Vu~AmV*}0|+z_=VvpF}Up zZ;vJA%0>pdL?GDvs-}QfqLhqedqEe%^yVM;O+J$7HtA=?ObKJ9oNz ztKGgm6Nh5qJkTf1|?)wm#i~#PS$n7n6LEh zL)&ZcJ|C#`Yeeqf>L-54@~}Fl#9BJ)NWmy08&SMM;#;H`tZA2}g!&DL6Vb-zjsk`Xi!W)50OaTG1Do zrP%UV>dIdm-vs+sV{UJM(9O+XKmT2Wf0i@7p$+M9_%@ia7cGkvs+f*jJ}_U>x2Em8 z;=4y_TXtYJi$7K4Z%c7iE^~a?Oo-psKl{7#G*~tX=Y+H~l=zE?Tn1mAT`w0o$x?mD zMEyZsF-x<+Km;AjhwFpYGV4d#-@ny?SvUaM=63@aGH;#Lx*QM?09kGuSzF`#{CT@C zEGZf)>}qL?QkGt`Q}J9A9V4!`uI?ieOi*u$R>|h$4}n}H(Dj*G$4wmmd#&0goApYC zyw;A2)jAvom2$1sQsb~jYt6Ef5}h_@hlAQ3V6F{8yDEdOR;!2T#ObP&V*^l8Xz=Ro zZ*eeDF58XC(yg|<&BUOTRRCXtugq?aQ{+GRwxkNYNZ2c45F9ly92QAN+>JJ&zL0+> zrK0*47dmI*Na$iD#9X4*^5^1d8=E>NE%R!7f5{m!%FK6PGI&%r61iDjjS_1+`iB1u z0p0kU9WD7C=%X}+t5|~n7geRU36*s)_ik$g(a)J#c(CiidCuH*AU&H?Dfx$OUheCz zY;MY&DfuLd2}mWO;sSe4z?ZnOnBYNbg7)snYwnIt0q4$&Rqw=J*6}!epd}Ij7&%>uS|}Y ziC)uhy|W>7vRJ_YotIs<WIucRjOD#O=#S#y4Gw)JjVR8hY#_Z2H9L$E;(^@5MI_%gLZ} z6ruQ{5@g-;t6$&5dnwOuB#J0jL#j6S*3G+^S6dxh+>XXaKPriZ;~_HDdUx@GUZA>! z1jS3l3MvG?_L%mC7IfY|k7smM8$PPUv@_qN)a`8uC;TZb{wbSHPhYa|#Y|T8_wP2_ z*IeVCUj84uwA9?ay@+k4Kptg%gl$X{k_$tz-D?fvNRK4swpxE#&xLl-?esV}K3*ww zqCt(KR#8bjKZgguEW=+Y4{^e~Gtu*TEsR^+*w}=E3+V^%>P-=j^`jMV~d=-wg75InDCajc=_4Rg~CJ(l;B-aaUY?89%J4Tt)CmLA!zHhP!c9Cf^il znZ||sLQ}{e&&b~OiAJ?QT4LBru4KMLB7#VUWXfT=K7Cf2BF@co=Pfc6p~k*%6o?d4 zFjplD8wtDY6EjX^HKfz6QICgi!WG@dyN0rp-L@^H1~Y}e^XF@^ zDTYDko@eVKSVBz$O#YxZ^utip03#%0E@)$5&YxUsUnpX>K#-u0Whx3N3h#5X$hzk_P}207$|NIDj4of zWN3GJ@fO?OK=`+{m!%YfBMI3BrNX?=e)0{Yaa--90X=2K>fZ~fy%>^4K5}HQ1C$tG z0Go-Wlu%`VqU8FGdQB`BNeCk*|fGZJT#b$aldZ0(r>9I3>$ZDAebPRc|EONV?7UoAI&pfqzG~-pD1O>yr zyB~PtT{y8nSAhA(2lM`Ee8eFiv1hi$#2~nKk9rp3t6Aogfam=7KzY~;=|uaIS;--m zU;Uufw!I`r>gIK5LYiit5J9bZ;iTn0QslG$&GXC_KEKF(APVoW^KV6DI%-6N1 zlBw;R-4Z11wwLMx!bDe?b>2%ohT@oc9Zypco;IpM3fAfbv1c(@6&|kUl>)b{Z-xs6 z9|!eegjMVvms^66 ztkN?xR*)k)muSof4eAdcIh)0Jlu;OR3Ju|2e%3j(rhrOyTn0%W2j^`WP9>1Q+IdIstN57r z*LrSrDu_>Y6F=gd&e@ubq_ipWwRbf;MkfNQ^!j0jYdql|&S77A$*CVRU{qtr>&q3_ zO;=jCfwUCoib4|lX5ILj97`Gbd(`8Jw)Asz=+CGgl|K}Lu}++7-+HpNT&$;Ff0vBm zxqoxc9NSvseQ8})ddi%`dUa~s0zXwEauQl zL4C+gPqz4Q3Z1PcCMpypNt*X=JGlA<`KR&4npwveOZgI8nY^tDp#J%JY)ryMQ^;C} z+#@6WeQ;VNAs0~TbzFUj2;H$FiGcbv=M&{2}HOh(LAT17OjFvU&OY(C$z!Co9NI@dqpqINBZn)6wa)SFRa=*O4qO zc$m86<-Phr*ARhxwNEr8tY?MZ4K@)~bjzy8M5)pT*17|P=!zlRhZmkACHu>1 zMg9r;Mzzv~&F@dUb43NF?xhb8m~#fUpps_796;`l7I0pAk}p#{ydKDWt88+e?XGer zTD6@SDV-JSes2G3QNk@ zmRE^`tS>I^Be%vEcm+>ewz^qg-tt-+ zGAiB?cVa*Dh)<~=uvSM%NkNiKAv|l~kUJP$=|Dq23tI;MFRjBREtG>AToxcViHKlS z@3U6OS_{>mngvy&&z*_H_^d9cE6{d!c06-J1*Z_m>+YB-yUIq5Y6SS#sNaOQ#8FN_nHo!D6}&lf*)~K`_E*3v!xFmf*o8LrAn5Jh0GE zF$I!YKtsvfSBYVO_-KeD0h38oid3pfs4eik+He%gepa;R71dRWLZiLeKrDbRMQ50> zkwc-(Ix604`gtopbikf;)7*fUZHwHfd~uzGdBL@T{SgPnzf$waN6ym8_ zA7{15IKh3RkD6KpOCpRy(+MXD#fsN53PkH}=gh4ss!aQ7c|N7)&(|uC19PI4C8W~D z>}oK)s|YYhqwV$BMHTgno1Y+e_Y3sz6vs$L1~KL3?ET&ER@sckic}n+jMQt%FgQ4G zAs8_?Coj`S(X3X506q@l=L`DJYr6c?j?;zAb#3sMwai;&n^0Lko;k&6bT{Y;&$3Ft zdMa)nkAi?q4JymcSutcRes(__7M$d}J;PchU$z&It>luPv8;V=0u{4vwAuf2c|eH_ zAtFlO3#T1+w5DqH-Sp5O2+^_T16EtX{RfvN;-HR2b=az9}s&{h3M=AT?h=2(@X zVPTg$VS9goVS*%C6LON0Y|QK@vn`r^p;!x5&!h1U&!zS>-)Hyj3gE;G0!2JLo_==s zg}aRpjm^ocQbu=WjD$J+eMh+Vgh!DmGHE~}tgxwK=+vpZwnz3>lcpS6*z;(!O)0M| z5^d!T`)=L$l6DlOrdnaNX^?~oS~`nM_0&*n<|cTJC1iVW)9bZcmB~2STnkiJsW8(T z;^O5hG5gAqTsPAcUz;^N#v^>%B_C@fneX4%BPJTL;I)&ywY7k4v^}_umz+1;*0$q+ zyWtG_>f}i$>doXT(n}Q2_Pxqr3$NQHON!r_KimyVqr@)aR+VVS)I=4shFM=(+Gww& zHKT^JQkNZCMgN-&9j*hmDM0sRa4=zgr~FS5Y?EmmRY!5yI*{X0QdUk(-1RUDIIutN zQQCm6O3ovMFi&ZSbf2|jK2(%yq;5QSo+H1D{bW1-ct+A0K};%wHIP2}#i?B#;D7)j z?$79h#|?cgtMZhVkIe|n^){>q9H8%c*{Ai@jOz^!V4%XNZnfG<4yOQYmweIf>3!nG z+~qDqK6-^lJuYK51BYw~Q(Q`lxsg%%B6*0t$vd}upc4r?Td1VZ_uX4pvjYPOi2ymO zcuA?p*|<&t`Rs}cQ3gQs`17v;j6r_sGW9n2641;fDKklIj0aYT)#dc-Ayp;yo` z`BQ)ff01m(rmB=?zq3%0}X{CK8aS&k2i( zJzfn7<@Lu=zVwP=vn~A$YB3*~FO*69vEz7+SKCz#>~em)DoWJA*vJGR9mne|^1IRL z{K>Qi$^Gh3$-Uldb?eOLAITD+x==0w7C|t$x+y5i2v>{q7!rhdwkSvS&t-nC&9C z%}*FBpZ2`r$35BR5I6P9jOjfc4`Qu-FL5F__Jqq`5S&8aSIQp-vs$9riY01O=c6eO zczB0Oh0<9(=DuZNBLH%FXUa4pS7LO#)Ihn*;@_mK+gtQyDR-@s=J2j3P8Ww40`6f4bSZb-T}+p2F= zV32#V29+V`kmZ5|7-DopQtbKsfR+Shq+_ixtXzI#C(jv`y4ylASifBbg_$ce{*@Y= z$EF38(qaot{D*5zo?K_0v4~@BSmGz6;=rp2WDLQddxhi&>dKMeTmMhS$-KqG;foBn z?RT6Wz$;j?k}u}2<$4j+h@Iu(U?(Sgm~>*yl!EzEqZaUoAe^v_Ev1^|p`j|5 zhpkk=88@%c6`BU7yX&$~0;CsnddRI(_Nopa^rEG94BSy5Su*ZFRvk&wH%VXjm; zUIyna zBPlCo@w?#p8!JaqZ=}B` z8BHwS2Zz$8H%QWDnTPXk4RI5^HQyNNnL!O3MElmqNTF}aQV-wt^6`|1W|)CuMWcl$ zSC+1Qb1lHM-y1!;XT`TI4KeK--h&2j(?mGcX3n9McrDQw=|VQL?H`-?up^ z+ZXJa($~exmV&L*(?;+u5h02J)EhezMc0|BzJU-Ur@U%ym*cAW+09bJ3HP`GRYeHt{&UK%5f@ff%+%V}cr5SrW+&-bSMNwueaTol>Cn7{y0B;xAaG z96uZKS4sOePqf=iZ*Au1=Yb|KU^2MJ&GEe(=PTcUFm9)PMvrY%KNNubb#lBdaxV^m+ROigt-p+_^84CA zVY<7UO?P)mcXv0^of6U=(k-2vMnD0jLApWdas$$`MOt`o{5}8io-xiD!%uj#STWbE zbwi}#uyIq=kdV2D^SbFLae>+5Je+FKq_0rZW;;@@c`&yHKh)gb|d3t%_ zCNb<#1M&hdpX%r=_eGAqqe**pW0U4wUn$gHFlv16BY$^q`EWkv;G@O&ru7>`YIL99e;U*`*S@6$n*Z!+Z$6n>)(Q?tplICT>;0V2c6J0VT&S2JxGJ93 zUPnqwD4QT%`F>IdtQD1-JRP??*qNYka%$L~b6PjkKS)9jw z8xIFFr-tjQM7d{ztBc6?>SMmV#pr?(JI;QkU7p?t@N$hjq%B-7klMZ});Yyu+M?t) zVu_E2x5C_Xjr-a0$QKNxX4mDWS1h<*`+jjbGfb%f@9039gk)&Nb?HZ;?^Iq+#t&2N zv)vD({I$-fj>;(%u@&CV+UqV-C&-^?!bWmMKhOJbe{`l zq(HzKpb|1CgdMZ_z!-%7e>qeJu%@aH_;NYUF z#yFUO$%F};8_BAw8!g)oD_PItVkNtw$B$uW#3cyQO5^mu$coqmOw?|FuvuegE28VU zuSJdQ-Xp&pUvR;S)Qsq5rdMd(P2wmt|Z$0w*$^% zD|Fx$Au0G_2P}S!-EW}n#_PrRX2E+gQ@Yy1LR6T8H~w~+pS16CDAPsps{mp^Nq4W; zpC;Q93Jdjz2m#C~pM}KBgY0>_HJ{&CHD>7bL`39i^0&4dFw`&d zq9`yl2x!#D@}o!rfDSDAF60Oi`!gUBlYJ>ET3NCmDEo>pXlBV*T}ve3?HS;{mh^>T zAtPhZ!qQmeeE~tc&d?0tLQkZ8Hhgkq2=od%S;Q}tTD342pzE4Um_22kJVL?hwI1O;^M6;Q_VV(TJYDDx55-N_1`@# z`ht8OX3Q_viZ!y?bajo%$jSE)AQJ>K8B!xc!QYb654j?*(b1n<{QsZ{CbijqZ;E`x zLw5MqbS41Qk$2t-TW%xk@c@tftmp1KxJ9CFNJ~L%Ib4)tK}%QpZFID>H|O^r>+gyZ zH_dv)T>un;Jv8g+N{#6^G5Z=2Em>G>tyzA$tSx!2^VkKviXbKj`h-9-GvSZ(otF{r?`MwDa#bb-BAYP3Eu@ zsSewYYLx0Z2Hx4o!eJl-zVb@IPGPJ)O&HqFEnL@r7{o;7O$bAY^E=G?Lecfj?V!3J zbv%P1umU~_YOG=cUT;~%#+5a;zlW7AP?VL!mC5$hS^PCkiY{;H%nGkhEiPilV6f8f z`A{8!#f(PiX92jhX|l6tKnvtg0U-5y(Cp7CLG*F!Dd4tYb^pm4vG1_pj-J+M8Jkf> zOAwU^jM90m^eEH$QJ^vHY;NflUNBNQ-|0?KJTb4$23C?^JBYnI8o7<0JjZR^n9|MS zLg{)i{?5T++jG!{)bEp9l!5z)f9L7jU_2k|aUCZ|&k%JlA{Z&@(>H2Znl-1hH-6@! z8|y9gs(mHZU|g({mrT7Lg7+xVLZh#*cAN8mvTg-kTt8Pw0+Sc!eAB(7KILz1#0>1FR~PuC!4e z*e2L$icQXwF}i;rZrNe|*3j^KN}=GQS3qN9!wa07b6VG7hC(ESo$X;!){x%_SH0%l zS&e2P+PmKV9V<@}08&>Gu>AzEM#N&0W@KfJX=@vQa<>Igg)3PAoMWpqeRg4=jnm@Z zRW0~$kY6sRF~*vJ&qoeAEmEW1kKIkN*-w# zdAN1tQ%3FD9{r2!zxA~CrjTmt{+Wvl@%&#d;BWTmMYBXkVm3VNx6?%#ebv7+Uw;g5 zBRWdr=n_i53f~4Z@9rqu-YY)9# ze$2N#a1q{E8F$#U<^LTpMRzv7O#F)|_2-^VqCAm=jEvKS`}y+6D4+dI=-#t&^S*iT z^`IgTa@~SW03IP_QBKa&uIz9@M~SPd7GZ=7fh!F%R*tYT2-DHrbK-D6ED&q;109hn z@MPMgw@LdHsmyg+-r7wv5~3IZwd)qzB^S#%kzB{HNJ{Am?{YkTu?x^nM^H6u4Y#Mz+cUY0n@Mv>+o`4T7$3WZ0SE|NF_ zD(AAoG7QS3f=q&JOJaeg!s=c`U)rK0L}s%och%Q411?($V11?v`;@fZ6yy}H$+=q$ zQ>o6@KlKD$gc?{G7{A-?y@>ieZ8~3u)9rh{)ahmG;7~KJTN4$802U7x6iGs@JUcx_ z!lXpfP_2>xDuX=ccFKSX<^_n$)|a;@(B=B8C6?pkW6HG}YOx@cVLo;l^|v?YZ?(#H zq6GK^D0y9lYqey~d1Cv-^_N|8Icq(;h`CrEv=QM367ZS$_;~U6@TCc5_jZ4bg31_l zP&=~*RMn=R%7uMDe#zQO`*jnRXmAu3H<|P_8Ly61!bF2jZVPeTbPeh&U4O#%FNSZn z?Py9dohJ8o|5gKvEc*UVs6}X2dHTyuU*@o7+%KOR&MI&}{Hm{gn52N zjn(wlG>~h^vbXkgG0mOUMeV*c#qfHhP1l6;|5G4~u9W-HuV3Bm)X^{SlG770D(=gC zG?nJH<&1{fa+`pJNZ{LfC)@tuK<~l(pb9acW&LMf8kI+iRAvB)uc@#&M=_;ooG_0N z8A9GyqeuX7$8dd}n(qC%qX6OhAq0&F$c#c1Rr0a%Uoh@z+oXDB&nT8Ga`U+Vh@-YC zeWQUd0JzQWMP-bQ8Ot0Nd?8M6C#oFR1Hfn|f)4rlxCQxse^#9dJqSL`0a_U3FJ_cH-r&6uh zx?4*)LVhy%*h}^5F;+~DRmL3I@Dc8w{KP|nV$)?S<+CSC#6B+CRn_3e!@Whuo*p0X z^}MI=hzD4aLJ$Eas|%xDjOQP503TM_Km_U0(E(A86PSgpfJ_e-DXMJX zu!f$2un=GbgGO})-Qm4Z_9}m#*@Sxg0F1$0L`l}T^@a#{Z(q2Wm_zdw`I*Gngt_}i zIwt7)g1=T*o2-ep&d&oY1KRHapj3%4XsvUK32G~kaX!%K9hkAStZ?Kb%CB*mG)XL^ zsMU|U#QFjqL%{*_`CyjumuX(WzcNOF`(G`JWyHsK8UWQTK&&-vGe5#t1Hauv11W<9 zW0MTp_{hP zk%SY)%W*vlzVKZ|e+l}VEd$&NK;glYZ>eV?RO&)zSW|5bh9Kx&|qUxAAPE!1`0 zron{wal>cpZOyJO6Db_ZL_x$$&|)8(RaMnUMO98k$KOBvkCQ43#(!EK2aNzItq37y zOmaIvb~`v_Av!p8s3L~g(IbcxqN7*xq9%>+)`IJuj|;kkjP+fza?|l{&b@-vxFcRf z4fw|p4ookN%gVT_x6AbGOM7MBC+rc#2`tS7InX!(fgKSNjNW&F4~@%N5>s93&ahK%H|Oa}X_gfa^zgw#|I-HqQoydo z^Ri=oQi;P2HdIRp-Dks3if?8R65t$sF3`{J2GCOfZOK>^AyD@FGAlV$zqdb}i$*Ku zk?^(?Rz9WXxxNejZ2jLPP$I{qficIJd>dIs1;aF6g}0%0!?6Q31{Y4O$N!aT z0aap$FCQw=#1d|tISV9(2Bw;v&V}(`{>6dV$-U}1+VYQ&?PdA5mCvjs4JgvgTEIEV zlvles9_XTQkA3U=qCLWJF$|(X1b`-lSSrreWq@_n=i-KEY44Z+l9`W|TmBO&97xFvz1`#D zuapKL%fy8AiY}DXI<-l!b~D4nRsH|Y_?hZulx_L!=EH?AhB7;gHs3?Ht>ons-agbu z29OJw+y0x|6DhY5ZlqQVP{s44OrmCx()1(h?JQp3yUqY?i8btC?>8yjTuJ}Rl_1oy z(-EJhf^$<}79F^l=00NxNu0_8gTe zcC4i7gZL3VBYHdDYP7;>o1|!)d_6dIDrQvjL^L_A_psYTKa{EfLOnPJYsp{ccra*u z00(m1v~_|!E!aqgo3v%v=7Ss@O$g#?#I&_)C9iUX7Ck`%I)cuvU_`tby5)owF9`-| zLu^zg4+(qZfYn5$&Wa=|1y&rQ!+;%6o~J#TGdtlsH8ji7XxW(GF_=}fs1z`9lh$6s zEt&~N6IM8`RKyb~ztKv$L!uJNuzU6NK;igtlY_fnBeV%dpy>M1gF(cdcyu|>U(igO zq1;3$f~P%(U}pV9lr9coe^q9NVPXv}ZjwBrO=Q}jKH^SYVl*C}L>0Y=Np-ZCj?)@9O;6o2*E$wd+ z9ah@8gFHbF(S&`uo2DcyqQ5aY@S{q?S|OT0b5%2Qi-+|O4Qm$#Ay3T|ZU1b7WIg5;_?1K z1Z<0=mE%g=vlUhx9bN*~=~{Zmdp#Y-NYMVveb;I>zpbbrzEBKOtL<$}0GH5I!41=i93>%p#Cc}<|Trg@RjfjdhYI+w3ax3k9O7-Z;j#ViA zPS-f#7Z{*~=YD7e9D z6Jf-TlWt2WVh2NI-3v2J6FBEuEk}=gKolzmMmGvnnvts*xblRKB9OPS%MC;GXF%3~G2o>MLB z=w^T;Mx?d}hDu(A`W}8=MoKBXCKa}u{vglrnifUJV#5SG`AyL0=E$ zJ}Zlzmk}&Ce*3<%G$SKIXn!v;d4h!tWiT4{PH!=Z<-2(0LdK{stc2>ZI6y)W0+$3W z8k6lFt7uMhQKD2pGa;g}%*wDFx1XTvNV`u-#)FsNN0!C$Zbi&cS3xRDPa9Q#8Z8w> z5K#<8mZrk)BG>6l_cDg4WJ%O7om0`~c&tn&-Vj&!l1n|ZbI`!GP@DV%WX*s}r><u~ioIIjQ6j2Ot0t;OA{JS`FNUj;P$}bZ2rdca%cZ z(eG5 zuL%WDS7bTf6$tvq)oaq(;}>VriuI>7N#}xStuUR9{ zun|}i5-~rAyz$}^6M4tXBq?c>PD{#?V4zPf*Bh8olC1*xT8}9|O-Mg?)RRBIq7@O( zk$NK4I2VuC&_3$nHe2dK+9JREiZj+ zTxEZpf4w&=M~lZ8*Vnkz;?v*w129!%mU8>{9V-+X8-?6}S%g@|yhL5OdmEjGQ{<9+ zE_X41y`4T}mIsDN=rU=(eBn{%EJWR^^d4HaLC2WZ2meC1_s<8t7@nz*0ST$*70N&E z(j!Rl`CRHP3xa?+;3>q+B>1rA5JF%5!e{v`_~LAGMSHk{-E0cU2&F>c|M|Drd)t!N zjzY7nY6#Ry@d(Zi?PSWOXkI2H#VP=1nVOtb zpZ-^XF7h&==E44N@{?oYY%B%0_MvfB@`;tvJs)pe0d&zz@DN6Dpii-4rlFvQ76E$k zoBhFYp`U74*^yOVV{(tsP$WRWp2A*UL>;=pYb?yr>7Pk2A1pgcfOwZ-JZ~EknNPVCu*uCwC_27>?wazcI z@8h}tvjJ$k!S`@4-VX~LKqGKR?&&7LP4kQ8()?~Sl8^=O=E-Xriw5m z_QgkXs3`MrK0eI{R8NRU=n$}@Kmg@JYD%u>`LZdYe5`_X#W*<9N_K$P0vkn0gM#=n ztv2vVsn3*)CEwHHzKh-&I+{n#a~;L7{5_sSYy&60_?OLbtNp10z?@P3oFLmcTeDxNWXOl6RLNWS$T4>2yTR;+m8(qfK zFVh$5?{&|9KkN%uQUfWW{#&pWAgzxP+^ZDd58g(e7tuTg0yp7L16x7&n~|PCDG-Vb z&a~;LW|Ov@vh?|TLRFymI(P~Ih36OK>mH#yXqbO~gN26_8!PdEec&lfoBp%EiIQbp z83Bq}d*pn)o+l@PP7CZq8dn4rFh4pkHxbbBbSfp;eIYWN4!r>FT!Rj#n@=z>yGSLC z`Br56MUm-& zfuM;A$^FU6{3pK5al0+Wu;t*#QsVD}O@oKahSYd`8Lx6{rM(euW?hdqn1sY8pv>5+I#;)P5`k;w#K2a%rwEx}K zc$tSzP@Z;}M1Cyy-+j59j3flRIDd59{MP!Rt-D)6?#<6t{87BUAMto_Oji7e2xY&1 za`UpBVn$?1NgJ3D34H@Q%?22HAz(#@D43|AJ*J>wi-rE|f6u@+_I`-~QytTp10Z+X z`K_CgRd0xHiVSy$r$)5cA;0-^R64f$00A06Lx7^!X$II2{r0OXT{`@D>Y?W3f(Pgb zUoF=1((=0h@miD5r$+K`IM9AnO=`(*pC8UqU)3KlC_dP)mS^w+vHMW9fseGiedt$B zAYyR7`6@ZXf(D@<8^mp+Xvos_!F z!FYbKC-iDk43M4RD{9dXDjmmZBx0{){&$d41vvxg% z6$W9GEYvFdq$_n^^qnE-gmxA<+h?E2od1|4mBy(IdAtvlBgJ6Ui-5hbz-K_vu;N*j z=hKb{UK);rzFu!N(v@t|rhP~!BXo2;tgCJ$_C2HrGHfKJd;uO0>`V+IPJ_Q9Y!VOugS={FAUuOD?$wEUJRc%(uI~*0!xH{iv47)mE1G zENP1HQhwcEIIvrbvz;xiOOy*u>66@Rp!e%7R;_q9F0F|Qp$5?~W=N%#Bz1FI>RK}0 z2jWD4UL!s1)1r(3Zv2^Oz~togX4~JeC7ad={L;X`BaUd}s9wM(Rq35^^WN^h1}hn< zkmjo)X(C53r{|PA=o)VhvJ5_p0`r9Szy>(lhX7^;P--Q>;gDk3uWOhCsb#E-O?ihL z0^!}Hc>;PH+z3z@9q_uMi55)9Iz|^N8s^wS%K*G9o*3(YsNWR5J!g4QWDjNTr2vW{ zA1}7rvohqL4!C_Sv$QZ#XPs%E_Uoz%9k`Bs_L^jhSvbP56)d1<#%0kIl>`(5h#lUT zP#PI&>1+FwjfUBEwucv6a1q^;YpTHBEeqtFdNY9O(b2t1Cf#Uu3uBg)@eIj z%KP4{)0%ecW96-P8+*Y1anMmepIt}-3=%84t+M+XTYo}oc*cJ`o&8sa;2KCs@*N|s z6@2X;4;60Z19ZC~^aRlVVFDD(x06jKK1EAem}!u8b{3)7TGY;dDM zaV)&~YG66qOl4HYsEG(aodhFVTorj*04|(X!Z9{(gTo8Qf|b8PTtEPQ{9ZS=@UZVp zR&bfp(4NczKq&IrKX$*PNp03u2~5z+%BJ8TOoFy8@Z!^c*rVHRHev>a5&@MGk*62{ z8jH4gO9?Gd9ypf}_;31@nXS5XFm9Z)afTl-3eJj%v~u} z3}P3;089i6gB@N%9u55JxJ@|gYaq)++BIe)O+>>$^BO4QwBs2!8Z8y8(h)RFX&lT{ z<;Z8|;u4ae;Si+Io27T3rlM*hgUjccu2o2!+{MtLS5_UH$1l7CJu06Uyi zdK@|K=_OSR>YJIS6=oCOz}h+3Zy>iS!6bFDREZ$3m=#x-A+E6S|CyFrj6^1UtSwL= zBI}N=&aT&ety3X`7gbUvA7?)t3n;AHo2SxRm+Jz&z2H|IwBdk#XJPs#z*-XmI9HJR z{{QopfPP4(-|NaF8rxc<6#Z2~ERc>WRj?j*-xA9Qisb)Fz>I6Jdlw;}Evk|7xn?95 z0G~Px%R?%M@t*OVyT1~i1mF-t~z(@Mk;0i$P$rV)nVlb^42SjM_TA& z=5D5xI3hLpBe=(Fq>iE~$l1=yW^8im7JJw-rQl;(etk_&dX>18``yy!jr{u5w}qaj z-p00qoMLf0Y`o>8PHa@W~61+2m(GzdH8=UU%tB^KQ>1%pKK#%4%IC;%MTCTya>2t zxR-qW(pa?8^TqQ*)G=Yq&%T(lA~yc>e2VOi_Ti~pl+_Y$5IzCRn`3@VwV19|fb0n< zdsKbQZ|SNt!=&`1eCzjCS6u>Mzztp+z_8n>z4+j4FryXk#NEo;Lp0Bg>qg+P0k{0 zd?Y&e``MyUnqOhDmGbrmg;VU(JfbAS!)|n?=~Iu4~wC`TH6;f z80SWUs-Y)%7?G$+YK-|gJdgmsD2A!YoMyQR1T<~A^jO=^h?}7*v5|^t&4@3C0!LCW zevf3nk3!-^g{a9-%JOy1utM(_Ri&z7YE_FM-VhS@cg0l|>KzKLu$twT8-x&hylogm zS<~4C>Cr*yq5iBiC297=Xha}^O3R+6BxP@}IxGV=lG9M9gU4ja#MQ~q8nBZdDpuwu zUXO=iqkv0fga@mgV zcQ8inYcTX&RmKW~F9|TbJ8<{wm#(vQM=zOB4;t=yOY#?Lp|BA^u7uI27o^6Vec*Hi zb~!2({chv4!roLsW{F)11__zcj^&Q;7m=Lfmq{s1o5+pzYtT&0Mu;Jw6SQ(uhui|l zTf}^@rzNf=MoWStS>Ax6>^8;~pP_!y^nR=Uk{z$`6om{etUlTSVL}L+r7$;lRxR`o z+6TU!Eu?ic)tJ!(&*(cV9ozxZR*^b9FKKrZUUB0fXdFjWMr0i4(SG~L1&RzC!ro8JZEbdz z$LTRosU@pn+yzHIjMJBAVSDUW*lG{-Y^Eiz{Hi71$Kr#x;DQ$u%1qQ>_Qmwk-5V!q z4Sl(6msaKt$semy%GZT;c_qBD9ucI@hM93!rB*X^1fZYBB+@7mij|07- ziHcVty!aIZ734Sf5k|KX4AhQek+U8gojzk=uT^&L_!cAAJB)5M?_M)h5~hC58Ef!Q zo>f=DIP{U7e0!fRiekpGg{z<3TE0%&(!&8V>Z4lQ)gOvq%M%J_(^~Hn4f7Vf@O?7%ZSExg{R11-5fiTN@tSTxLm5)t(ky17z4x2Dc^! zuBR_}yeB{puPxSr9WnhoG*Y@?V?FM$iNl>4GL!@p+Rzg`9oDgD!sH+d-5M$uZ z*4GVaFTymNxI4q~_x|S7@m^Hwxr%vuk5OIL*al8wdL#ZJ({{mjP-+n`OrSs^N3>ed zSh*GV>HFlus{T+vhS~61wO|*i@~ScqqOsHPcD&O*8A$q%E9?9ZNxnTgDZ~-vR}}|Z zcVaM@_U9_1N&;6Y*4nfLBZ%S&L4h{`Vv28amOE0G+W+V;-R^u(34Rvl`g;-uLoOCX zV&G}Gyfi*LGp6zm_i-oKX!HwQ=E%FyvqDm0jmJ!@?`F|5vul+y5~;Ng5&sk!{5#yg zx`0x;VyFD$_8wqJL+Dy9k2JH^u$R_|1=URTD3fAnH3E;S#nnWH=BDTN){)H9%BoY! zDbpGWv+Bxr-2G((3mv{o9kno)hJZ7XN%6aRItj(lXnmMbf>9j0UlfV=rDACbM0U@Z z56$OJ=)-Dx^>bY`zboj7WPRbU$F6}gS|H`0M}Lju?Z><*kCqRb0ln!W9eG7~#CNCu z7{W@3fx{k18*!rcA9n^*e)Xki;u&6J8dDSlb*KkT7DuhSBI90>8zn-Esj(5@*y8-y zV%(LFcyJ}va*w8$GC;6G(ByUuaR4}TLl@t?1oe{W1m$5Qbtd;AbgJ;C4*G5q+7|8> z_A34=rvVi2#}^lLmlu9GIkv8t5h+%I#AMfp$$H^@o&0SGF0tXawAJC;HnMKV4nGn0 z0Q7eHQ|8X9^yLkeKOe999I!~VibJ$^s=t|h6)YV(+L7G>+N;0GC6b+azT?OYdombE zoQTwsq5~aF57iz9ER=_RCN*CAqu!Cs{vq=RZOPW-p0IN1xpgT?qDFQ%tW+r4d=7-qQIlS>Iv0kq!_0(>SkVWdFT>n;lLw)(_a$xKQS`2VN_ zgWlfT^XBt&u?ev893u;mW`AwGLtS6{PtoE@dnvu{a~ z@F}|5gX@yRQONQB-?K}YN>90J(}|{Pl;Se$V4BnU5NqB-=$YjDy2<~n-P9wShXr`+?(I}qTb<84*{Q4) zVm}EDNA893s-`0CjL*hD<6J_>F6$${lZEW?2>D#@fnCDhcxOuiVE*5%@0{kJ4Gigk z)27Bmn{P%AA?rTCiuIq_DW95DVjWXM4nu5bNhnd3))2jfpW|({sjrP(nqLy4%Tw!( z5K#owv@X05)}^i1MjLRe7uGheAdwCHS~bR~+DBg0!-!qwkzX42#QPy3O;b!H32}+hECO&B z^SuL0`R^tqlVqeS5_9yAGyb+>CbQl7#%OM=k1A7dRY&)+jXlw5st1lMzl%ui)vqGk zWQ0^PsSMl5C;(`7=mOqAcH_kNj>c7f2|;!sYP~e2$&6?--~QGG@XG~~vUpNY(9>Fn zYDoK6GfR?FVG8DsYA;)XJqJ`6=yvX+erG60BiiX%Tf-{3d%u^lcn4zoOJUxg>Ii8YYo@TED(rK^_~p5d077TmTD1q$EtJ&sd0V zfSRC`Mns7r8K7KP>qK7Xe8ell>e>83m{lG)9<6tcHAW5 zy;M=-RxQG=x4)KFSk2x%k(P>7+2qRs*a9Hqoj+v9W6aK&sjT5KVPKsh9kUEP!#nE9 z&=R6T0l&+85f3pCA{FE%-D{M_L`0CL`y)QaPI%iA6Tl3y*NXz#Nd|-`SUz(aAOx`V zO#XQh2~Yt6BuM~zd7udHUNP(Wv+r+R8T0S)HDK9l6188OUT>UtrVwt(+8u;DieBcC0KG1YuIDmKYG4!D1 z6EjJN18dV5C#07@n&IBk;%7B5VMwqk%5YZo+s^8+)K^s#e897na!=pRCXmIXbRP0Hja=ah*xv5z6*z~XO(wXfvCyX96k6VfPJZi>-_g(tzIj$ zSUN>^K}oiOaC5Ahg39F=*FEZkRCI$Y`MoWPcbRc3^KDJ8ke^L%cGE(wOKlA>)aCE{ zf74bfz8~C#OG3+G@sq$Wj{R06KbLtN!m6HHBhf) z(#{Xqq_Wmpmm{OJY^uA*ZvkGB;A4{7%Rd0Xt2#ntj44u2w+?_Q&n42eGhOLsaQh=<4huQa`r^ia zrN*B!CGbZLl`-?wy8a#<#~}<4p05NCnz7Wbv$&|uHwubfen+Hs(+9Zi4X+LfX*VyMz(8R1$$CO zxtp_W7CtYTx(>gDO5!PVAq7V!!N)uLLAbQstk1G}B`K}Wj-_|+elR`j(q)Hl@vX$BbY2&Z({5yaCH^i)FcBA)22H=mVNjWJ1&ftE%!X2{-$s`BRSf4P9Ncs152KX$Cts&YUHD+i-xj_WUn z_u2hqk%o00+pU`*;k6DemSc~-(AU4F)i7b)w|1SAgOQ#?6yaJ{%ZGs66w2Sed$r31QdC0w%@7G!*9Py3 z9h^PRp{piHz9c3~TgFN7h}9CtLi0L95|#X&jKZ}iVh3AvQU5Fx_6nQ*hjB|4Dj6jV zN$R9W%KRmK#Ao3;X9@vzZNS!Z6`n3)3Bg3c&|rFS$3E&v@qo3IsK`xYhIC_6b{t|B z59^$~1a7tDXo;k-Ok*akT1FzxZnMV=5qule3Q*nkTS?x%oBlDdn;GFx3hnJwv-kHl z(^)YU#>^4lNPnas!SEI%GNa{IQ+kcZT>aXP1NZH0`Z@|+p73hbXsI#&-ORs~?JZxl zPbp)PoD3AEFY$KFGa@sXWa5Ua0DUa4>=@kobtu%9@N#zBSQJBK?`^#tN1Fsq_^yMs?7a})IIA$BL^K(}We*37}! zxsS02rAB5jShy=_*L1MR@oBE2nJQ7!cv7?l?UdsI`qkhD0{J1F>%Fq)m`w#7nPf z_JnxeK`>onwbHOtLUkNG19|VNqS%lQrHgqP(sp2k&C+0L%cK~I(nXV}t;h0ctvSt9 zJAEmdL~HGFU754{{~$jg2Es%}4$>L!CZZwWDZ^&jfos!|wbGaf6UIQCP-9udyVYnT zv^cbYQX>@PLM~gS-5U_L6bL6tSs8{HJ=DxIZ<5%ULSG*WgU|&EwIY14G*6csFR#O6FCKN{6jf{`+3{W1H>68So=!tVkpy#fATP_^%8Z64B zqCO9EEdteWE9uW|W&+7BcC#-#1p{1&bz%o8mO5jqIue8M=(A*j6@&PrG30o~#9fvd z1cjjIN{DLmWBv|Nw4wqd4Yj?@c~e%BP3Hk*RxzkRS(!C^9b@ND=^*_lh8SkMj8Tp; z;xwi_%sBO}#BC(;2?#u#5Y=7mZW{8$ZvPppkZGD?e+G6??syFEMrdV0%=gx;FR_&o zs1UH8OaTw%0DEB%p+>6CO@ZRX+U6HJoOCa>r^D(}!{gKOKkV=w>?5p<-v0-F>I}eB z;iwa=HFpyc`f^Z|svDPity-VXmO6dbFj?C-&j@^OiYFS<*+}s=vL{ z^%k7Dllz=BH(eJOp`#UKU$pm`sq|8;nv=GCs{Ch4VbBBI4$z1;&*%y58;DRaTBy~| zqGa92vx+3csjzeSjIOCshF zgCq1Nm6#~SYkOpM-lh;SZN5sYOVob&;JX{6w``gBS&z01kE)34=cZ+~hO$HqnZEv5 zEWqeI-}2m#QV7(aXoB*s~avyP?blKRIA0 zU-M&b0A3akU)j{@@oUVjIo79>&s7oAqq$?Huf{8y!r1U9dJt{$<8qth9I(?jM$O#A z>sUh8j!q)=42}hst(#kuMt1{|6%z@c2-h<9CYATs%2nR7Ks3F5)b1B1k%g)#H|R6& zj99Pq80HWW`c8E}?=q%ol@Vk0=%vJkppSpsz>?o7l%wSSU>yIzA$*(|`5@=?TOXk; zC$@-?X4o?dbbMC9?dWH4uO$Ase8T^#cj5q1`*|gTw@<5VNfmNLcMZi?mayJlH?xi= zASMw)!80EszHTv|zL#Nj)*08eMEe69yG*DHz zqOJVZ{cu75l~Rye6#t5LEGx2KHo$v85N zBN7D%qGmHUKHr@AKYN-_-efuQ9#6eCQH{ZcmaUe4%Acq+p%Hb(fvemKEe@qg!^EsR(qLcTHRxQ|UO3r^#cZZ!y)baKV%?_WChR77?|k8#=PSs8 zJWm;g!oO1Uvd_I?}tsoT&g**DPGlsj7 zXZ_aNU?3*SEIn^}*SP5$mHv@KlR%>aiXRWn-*Vp-PT~$M*W4tWA3_L=^S(br$w=U8PZIqH*dt z?4(@J^Z6rjWNHPv6mjHVe&`HuLDQQZ>+SOT#O#KgCVEbvL=IO5_@BDyt5g=QW&CIp zOn-xDoFR!B-2Z;TO&oVyY-3w%1)7VlfI_1OkEH$b=V=lx%{m!t@^j;5YtviWXroE~ zZy;vesGy&h&@vR7CB|PA|9!hhc9D6(pGn5Z4Wiu1qPCsgv0CObrN^ZV#N{8s*XKe`$NWr5Sp)=4 z51}2)HZ)_K$tB_fp`PW6K^_x%m>H(-=5l7Ze;N<6!UU4aklM&HDb_z+7x-XVJ& z9v*N8K`t*dt6lGZ2t{tB)OC7JC+?%?h#T07hlZt_{`eL6#ABWNB%uuKO9!eDdig7~ zsxYm&vbUeDZ+EsfGix^4a)XcmbRVPI1Yc8$1U1O9>fhftKDhfWI6cZA(R)sI6BkbV zpU%O0P{*8%gWmsIz(gpew+#N!2 z3vMAm@Gw9~(7_!71PHE!OK=Mg!GgQH3@*VP1_|!&?%d6L&biNXzxx+vcK7b-TGds( zR#nKto-&&m3J5RB^#H6@mT(4nB<}5AjD@hlG7VvV1>!~ znmoetRM>zj!v+93Ke``AKLb&_xL2@P&0}Ut6FF}+p#6lmA@Y@j=*h%b=ho_RZYZsm6_dQ(s?kV5T>ZlGbbm&d%b| zfmE=!6}s#o48G#vUqz~K|vlI+T13&n2DDY`eUeS$F(5T(o92>4Rll% zj}lxty_FB@GO6x34Gte&~nmMl3T(y5p+eXm&E^a^jgyaWj za%vJ>{Z0c#<|^*3D?b7h{^7~#J><$#$29$X7FXC7&lJ2|uyH6Sa!Uf3?67TH9@L^$ zOJuu4GP@_DUW-k%L{D>loFUy?lP2C+_e;ITu(!=kDit4ff_v*pPm>ON@Aol%>DC65 zZepId?QHu_OAkBTvn8Ar2PwxBlS&DmH`dVc2B%BDb7Ij>omS)dtu~$fppbO$N2?b3 zl$6+PwL*CcQ4l!j{c&b4P=VRkr#IcR!@6Gd^u*);JJpjgOpaluw`lBbg#|_T>GP|3QxXh76)06F)pKOIg7&VAs=y|v^7Z{7@Jy#4gfF00 z5L;Y6dK)O1g^Xlnie)CU8hl@Qas(y4->R&)}``ugd`^P${}qx$4B?a!`iO z;lB)*og{Ygr#CjyM@+%$Eii8!5V_vh@*@`~U{N7Bv+s#t{-o<$PFI zK&#&GzV+$xcCY>ZW=tu2^TxAi4>R_D8sPnlYuTc-@Q0P7zZu?#Hb(d#t zeq2}s3ndBfdRL2o#mW)4vit79@bW>ktUyBk@g4~=O}X%sz0YY2=C(!Twu5HSQu>FB zzietvu~e{1y8sVtO0)h=9bd3}adkD#P4K{@r-o(S9|iUc90vrQq;%|{!9oWtr=~6q z6?1OwVZygYUkWEz-xFAr5SsW#X`5w-?rgO^W1L(&lRNBNWe*Idj9D#~d0#g_OrXo+ zkn`K;$QKunX`>#J|s#TX>#VH8iet7WwwrjX$tz&t>Qr^<)c`rYKGAexT zsHWzW%0%$cVEuSzoSrJ^O$~H3r-CIL`fb*?G-UVm1*~ViY8Kl2t;f37gD{AaWv5xv zuwnt-Z^gxxQra*3B`b}>A6@ojvdhVvdMEDj=Tj^X*C*62*IdH#GEo_U0PClTO>Oqn z{;`ILgXQ7-=#WZ?{Aiv!avpet=#{%fq9Y+fW`x)QZ36P03)0PiU%Z}=bgRba8*mI^_ zh}qW8U565pDH4t9=kf7^xSWCR$nPBc#{N1SsTUV6o#!c}_n1^ZKRWZ7`8PDoilO=) zrP@(C@KI5%)T-+rEtSqE^DLL&?=rlOjj`XYUw+o8v3+7GZ{PF$kxZ>Rxn53#8{p zq3NYBat!F#8JcQchVd>{E4!;|lnL5zcWh6;R+eL5i%%)p_>|@MO{S;!3gwsk7etv> z0ehO3qR|Oxy|ec>!{7UH+VWeiSIT(YI?HG!SAG7ot+-2EVpU4nuEzmc<@NbVr4UQp z#8L5e!wK|oj&f05^BNqOD&ln*yKFxlN-cg!dV=W>5JkZSnvw|D%@U<*khwy3Kil+H zyvCp$r)9lZn#z1BR5w~{8W*VdL(>S6pO8xuETAw!%wP4&wqf_0@j(7o++ zugA@82+*n}u*q4W$znIAJG*BIPICN>@>A{ZF;B5t>-Ce=m+jFMW|p?+Cn?4*ujj@3 z*yH9wOK9CQT&CmhS~rfE=+h3o3C5q#@zO1ODTJKO){mot&QIcde0H5TK>6~7_;@bo zbkDo~w&x}Ly^CGvCAY_g+w*M>ogdMnj~D0Z-cKXzcBPjO=)T~vih1($=VROOXfQ6J zZJEUocTuFbmJhYMr!LP*-O|%NI|2WGkx9$D?8rzJ&i(91X@%A8b9^eUC#M1vj311b zTL(|aRv+4)4NtqA|FCL*a5>X{?pz>v2iH99+*Gb%<%9xBXOm4l?|&LvI}3xl%@hki zUbW%gkEmbj?rOn2cbArMy_7y@a_W$`x8J~taV$)_t1F2e=6c>PiHw%;cbHU)xO`n% zJU*nC>s_x9NhEEvbQm~RpTydjz~09E7ASRf#iw~-7J#(H9wvFCh7%Iz!wl3m<|7$VN)@&qNmE z9`2v59mt;_k63Jt0zEfD!PoN&>Q>8lYG1?EpPkg_y2(7-td|tzcURd6VeE2U`Hr$} z?e`)}%WX}g=actBEqVP6h8ZJbTgStO)k8hfzF<;3*DvvlejwyO1AYWTBFmS+m4~J} zIBQVV>|Ev|pa?BI`h9d!nbQ_ck_Lr@v94=HxoL$G;}uu}p|f;PQf{l6J7FrxH4r41 zq$P!8Zc~aUL5?wtTQyNUXfSrj%`q!Ey+U*7vGBNOfK|mEZLMkd#nFBuDHN z9?9bY2-%GW27YR#j_f*Wm8jaO+i-p}HOBr)>9Vn-=nF1}BGC705h{YxY4_ZmcmFg1 zfa!#p6_xjE0TytdE7lv^0&15GvwzT z^~3k|07cK9pGTxOqknx%^UDa0MCV-WCfZlv7Coqf8%2oCJu}hz%Y!1O67!=*eUdyb zwk4GYVbqyTF=#A9kX})v0L-Q6QYI^j1PwV(eWJ+7fRb8kO4VOJdpht;ry>1z-sGbpC-E*a2vf9t=^4EH4PIh7V#aS%GAGvP zYMx*Ip(p(t%FdEZsL)&IksZsAX7$P{I;iNG!F<)(rI&bW-g_|7@5*1H& z&Ny2A=c`6VAFr1eqe69wEvFCoM<0(#CUm58-?3e4G0;!h-YtX3}@L;^QHn7i*OJ6}E= zg4M#azUu@tJP0SKPW4>M=9%pJYxEiM80zT+AAs$rNaEF+&XrnQ)f35l3-;g3!o$ur zd9a)0N#7tvXG_==ae19(d__T@x2RJp1+b z(DR{fAz91lftDq5P;vpHuqd!wy2wd|V@vsl*z>vX=vf!Cuu2Dl3;L3S9T^rKb|Z^} z7z9*7dgd>5dz+%)*mA|edG~qC^Raa{Iayap&E1!uwkdyW zH&VaVI{#rh&C9{&SZ`S<`&BMZv-(kk2dmts*0h(U(!!87jn{(vX0cV_#@lu={}4Zr zmuOt~g4I{VX$E!;FQ)Pc74O^vjG`TFJ(Aeua&MCRoxM)qJE{C9hu>5%v>Uu=^$I15 z9dyWN<8LSl-c~b>6BA#wa76k*j2}M}+VH*@8xMG>7m3q`q z6loKQxToI`c=YsDk`o*?W0h5s6+hybitbH=i6sblS(aQ%uo)tQh`rti63q* zb|+23=$YTWV`M~;F6TTe4{!6noeG^=F5AT=z8>#QpT3;{B90&1o&Wri^cHO+;Xd+N z&1lcass559hEvKSH-kk^NJKQEe*-@39~c;<1oA< zS8x4P<%mdZ5j)M?@{+&O9;3IN3`YlCMGF6@0HtT#Wo|zuT>ZMUXCd1>y(SQ&AA`IL zM*Ea-4j&$`M%fSaS@35R5=lz0SpDo2-k6@??`?toOgx=d)KcI~A80L@q}^2EdR%b= z^AOkaTD7me|EeKR!0O009Ms)8L5#_@u<9YT5f)yq&oD`A9J82#Z{# z1k6m#npki13>UlGh|k~L()<%??=xQ9r(u&pD_ZMuJz+7&FLjy?tcP|TQ`)bBnx5>M8L|>A6jA!R+)h5pepZS)dOAMdXiOWP zb7PJ)JKGab(>I6@E`yNM5i57$*q95E#N@+rgQyFG6LjrMO%PFCH)H|M0uC~>;cld&=0)~%f?cb#r z`g%P%pKbWBP;(8u39ENBJZRfSd&B z2FJp`qsk2?Gn;mguQD^x6o0*+siCI6XD1T7OoM7aqm`^9w3+5zCF4-m?1Xh8z7cxF zo{}RWEE?vZMp;BCi`pjH*(TXoCplojR*@!5D~mKgm&QQc>x3O-ZG3_R*BVSU^0I_Z z=a)#J*RvpxR=O^%h(r(ceRcg2IW#IoMoCJfkeUr=tOWVwWnlkSLfIF*|2>|n2z>LC z(z~~p(py0ArnP?ARi7>^6se4SqtW+{K}8H1<24ly8r9pzg<8o<5={S$Rl3I| zY8GUGis^3E>B0FdQJjC0RE^|6J(-rrP_1hiAXr^Jwik$!Q?gTfH>U) zU+=6wAj$JqkMr%`jGrbJ!_@YeQSADaKC8JNDqr8c5jf7ie@04|D7%%=g`796nYVbk zf}%CDOsL004Yx>+3fDF0HvjmTZbk!S709yTj>JUmq~r}BkC&c2qrpp%Ktyj!tRw4u zJ&@UDKFAM2wf28%^}h%^#k#%@$1)hmSq!?WOdPrsis!ATyVlW?Dn6xgo&f^I>7PkJ z;cOodlrE`A#m8u&OBjAF$8u-X7h|AIzHn^Z#dL~|(A})}^Mi%*v0jVC5a(N70fvM* z%uAdw7P)vYFRzXcG0x}Gc_-HAH5rrS)vlo7G#+jtp@kWBeskDizI>`-r3R4oSx)!9 zJ$&MSzTHmOH67J!k_Fj*9V>{YP50VE-8x$F_vc%72`6bam|OsoV&RRCS61`R?>Xgw zzG+sx?$+#jQUtYS7KDn8#c6E$XB4fpcd~(RHC8LPU#V{YME~V|Ke~B`2Xf1-{H*<# zd&prqz+$uHAg0QDlyHP%{IE7XmMVWynC_srMO8N?;%J@Ya>YtW+LNShIrV93jT+a> zuwYT{4S{7XKW}PAk2sBP9hJd(zfdEQ);T0|>GNfjqsD*bUhS7Pxc_k#;_b{ z!=kLdmBT(#=&O>)q9Q1;Zj3u*9KVY^8sq2RwSD&~sMGBSWQ~;M)umE{WF#55kVDyc zWAnH4)MotbkectnfhMCH9ija^z?kRv@Z}YUp#+1S{BydPw9EGWKrJM@2{6# zc@T80W>GumZmMVTDpQ5Av$Ly+Yzr-1PUr_f?Ows>g_3?steTuAE#{Jj)f1-Q&;lM}KK0T1BBZPor2| z>UPa6T(Ybi!>=je__j1zob$Y@vx~gT&BVp22dBKc0q9{Fsv|eGaEiqtXFMd_yX+Zd z(;s#@E298WT&G=My+hsp+vHB(pz$zOCqqP9yXG5D;aVi%hHD9cPV=SAM2U9O) zJQ5YHIi6wd7P7}deikc8J#%TE|Flq~RIJRAyX3q)bh+UCzaR6@=$xZ3ZN^5t;>zS7^cbBIS1sWNVErPo~gm-KAy$xH&m1@oUJ#}d3HVzJsegW2!$Tfw=5%D58T zB!lPj`JIOs$InXYzNm^fy%IOQ{$B{wY|)SKr@ZH^rZQ9C^mQp$DH_$TZEEY}=H?0C ztaRe3PSv|@hL#^-Nj-ac`n`fD7H&@D*Ny!W2#Wr`Jw5E<^L22#$Y@?~X$g$ga(`qN z%OLk-ZnxbBe)_55324A`@u{mslRGgi;GO3N5H>P1gqj&030@*TxC*zdu0jH<^9G7I!A5 zbM9^Frf*7+Ttf1&P#=#|g)<61c;8YN>@FtZoLx>(V|&}>2v`Vn(I2&HH>oFDiXOCp zaHx5d1Y$u!y|?UXIQZm@%g&iQ2vg+;wRzouBjGC2{|BQ%O(HW5YPq`N>?P=&+t;EU zL?O*Ya(Nc9_mAsxuyyu5;sxrt+ul4rvmeyPf5zha^4WYp_m!NnW7L6a7q zu>KlgxM%4^6hwP|y^8wAO@GTimc3j<{WBtir%xluh{~#f)=>>6g!69o7lbZpkM9F` z7gcqWO5gaJDo@zq@*8YZ>3r&~Cv@0yiZB7h1qEeWOiW2bX?zxzQyLr9*FW0HV3F!F zes_5n@q@^yYs#948@$|c{rZk6x%aMi$)K84TG}elNkn6-RjfuN zv;fCu&#(xRuBQ#}@11gME{MoW`f3{!KBtLs=CzaeRdtI)s^|eFsampboF`3E&HEcy ztL#wVZW3B(A4{&x2(m_YN^>M{CELTt{RoM|FNi~A{N}ZkGi+ubrd>Cgsx~}ym!)LU z4I$R!jaQ8;bd)vSFxC=R)i@4eex=$$<~KsGAsTK#yV!m`4Nrob9^>xPdN&Ek2p zR%BjhaabdwqTV8Du9n@zn@m(j@JWB@ck>5Z}eVEudoe_-V(VE z{#mLLdxnZ9D0|$tCym%Gu}U!pr}L=kXPAdmNhdG9Cq@StJpMR)6~6bq1>9(#d%L#m z;N2n0PUvb9NFlm5{lvGX}IcikRp9A^ty>x1*#%@0`s_Y$>;~8(%I->v=z7x6U?~t0dv97TzmiE#1F#Z_}hH<|4Z9+}@ z?6_a&n$f;Tfs%gRdJE;(k6YV_-h(i$2?5T3IRFL9r;(_Wo6d2mx<0V%-q}ADJ~K`? zXtCTf)oAvkIXtcS1h6E>RtE`OaR|Sl^-(QOtaf&y7lsOkp)b;oz+Q61mw%6+sz1b zx9MG>{`~!aiB)$SE%ke(A;1i&Rs8fFgB43@ofynS)5Jo9sXdEQS~h>n4U7EJNe*aX zq=nJv9JY4&RAkBg%{=8g!R}^5KQ1~2k0ih2C zzh=Td!#t!+sk@fd{9;iXXnf27r54 zD+Gbo%VGuS+~2i}4{_{i#abG7(dJgqGHGly*M6Vcdz&wpG4cqSP5MZO`%tM617w~l zhR2Ue*9M+c2%X_IB39Omi$~v5W!1*4oW)!%KCL-nWjQZ$S7$XpG{x(4Iscb%S*^hu zBAds~w0e3|D~0C|W|^FPF^poMY5_E zzfYckLk-D~qzqU1%sMd2y;EqNyhpZ+hV4%advlT!0K6uUA4wTTa#znOMaiM?Gl@`i zM5npf&FF8E|1f_tg$qiJ%&Z`vbF4`KwpFHqL49NkJW?P=8{rc`-b+Y-;=p*}V*W-Z z4u2!KWM2DF;YQDGmrDB|{$#*KRBDN(8lW%T016Bgd6H4oKMU6*Uq|?_ zHlOdB@*Pwrl>#&&0rKbBiiv})1N{D++>TL}D{FvwgF;% z8AI2`PSt6{S7tPi!7QG}^~VA38*o7opaUBtz=Gk!6`-mck-@EDeNMxz7k;O^wQa>Z zPN7lB_4pC*g(bs!=zUA{FTSL#l9DTx0m>pi$x0(ULmNsIc+Fmpw8e%jicBFpxhuA_oR;}%sObN2XX(Ati^Du$1*3x@3Ef#~J9Jo0i(+!97?GA828H0fH)Sa%_G|f zao)w9S+p8wm{2f>A{IFG)#9H7pr|20Z<-xK+Mpq{&DkG9TLQeEl?>SW)Ca75|T>O4*A2Us(j-5JVj;+4g4C z*KCBR2tsw?p>+Pe>%liT0l`y8Kgbw2PIGA3hkDH&KK4bUK!vdK7c6J1|UkbE=3~h2lM_gO$wC^a8qkG{;DWQ7wXGM5DDTVRKoaH~8NR z3FJy;f2AhF#1PG}QoOQaBYygO(G117z9mFIbY#t0A_$Po7er=7PmsyA-a|BiuPl`N z$c9#H2{Shxucp7SG_Yz%=igD!6d|m*Tg4P89Gkt88OfUvd6W>a=tM>op>Q(!bb?9^ zqec=WS1OJWtVn7)p<;RW5e*p*E3d&q3@FUa822P57IbwOxa#NbtdQnZu5(m4QxDwT zu(34g$FY~!@(Qc>k>0JOE>U}J*-xHc&dYG4p@8^IyNVzh1d_o3nQizV!N(;fpL~A~ zB3q#w9R;ps8MLN5SX$YSt}7gSYEBJH`Czz;>Z6Wzd)EW|Si(?l9U>W;wGOZEuDOU# zN3NE2LBYtIKi_fJIteH#y#atTDz9Eh3L zhZl0g8~+j|pHe3V-ER)Rty|OF%-=68e*l`t!^P4tl!Iv>a^RL|C<}k|<}!;CntbL^ z`QbC5RMz;a6DH3^UEzl+RJcV_HpUVM`Ra+q`A>)0PPXm8tWEXxoG{Mh%VOuH!H_$ELX!IO2-oFDQ z-AeGwU>{HYb$y-;XmewA82kwc_$Xn!Fg_CcwTU_@Mjr?roTiTBV z@6~}2h#(4x4HKZ@2K$H+C~i$ob-o%{haeAWGB{U}MJ& zRt4qT(Z8S^6{Ke(@ z{ez!#nNFDi`sTlWx=6ss9Ux#GEL5Q)#r=Pk812!zzSeKj2j496RX8V_x*7cKARq)L z;lF_Jr#nM0I>9NGicMl%`1_476Q`}yUnS8-CUN>ZX5P>fFJ>=0j2>XqS?}@%ys%Ymo+L zXIl+_oue;chk$!&iXs5#EPr6N>6b9qZpHJp%8SmiV(yHHQvi8=%}e{ z9Ux>Py^xDDBlMsZoB>IA54Ew?g};8*<6JXys)859UG_`?Qc!r)Cx3f zUsvM49oBBR0Zyuc(O3z3I;jx?ZjSM;uK2JFDvs3+xK_kB=YEHQA3F5f9;P}c3HHK#BEyCCou>uGLTt>((v9{MDvJ*kLpn~vP)5!$^F|>d- zO%io4?Ka-`S)@Gwkw-{rvi_2ItDNxFR8r2tqGWVuDHNaN?za;Dzdz|O=LS&)I!;oS zzG2jZMXNq|eChy`)X%NW*YCv&N`dd7a0#eM#{C}~B;l-5DV_K(jZ8l7bl#gExD-#Fb?wC?@W@w0e!mJn$}fvEA7lm2$vE~7c)7&t?JUas{ce`YLp`~YLa${Cw%dz1kTu@>KQ5XKLr#6wYIQd@n8 z?SRug1dl>bY4l@2X2GqfRnz5PyaXurY625_ZnmDtg{Ycjv)+|27{v)yq&XWPiW!rsq33i6A*+H9LN> zovp7;I{x5Z>L@qHM&$i-)f~+trGlW04?OonJuUyL3%aQ0T!RsRGaQ8qI!J0~^;*;b zj%QEB_g*T2_j)c9l;kq|&>sad!0Mej21Y6VPt1TcF5jg+LklTsFeBGpYkBiuZuvf>B8BqVwKukJTZJz72Enh}N9;+;)4NYcfmw9jct==0b zB>}`Kuw4lZpp?_}-^?hGjizJ5(5QB*s*B68Nf6%KZSh9}T7Sx5jKCZN)51W9VdYO!8a zF0i94>s`}6_1L#>giJj?Mg~_YJ^BzvfliC&fPdl|;6P*+AL*_!Fz4MVv^QQ}tR}~6 z>7A&JxT0BXnrb|VC(w`O={?EGzn>Rd<n4Er|k zDk|CZ7!=<#8@S~fjJDxR`k4q)lzQ2uf7(L}Qcx9x^DwZw2}0-od08EEDUroj&{uk{ zg_)-cUz*e9GfnoRc~Vj?B!DHbDi>zST4zuQr~JLMzkPj+e5?cg-SboB?rtQlKB{+J zvvj(4*(+Nu9>!ONein~@B#R;(wII1H0@!OAt-VHi)<#K>g6Kv^zn3C)6bQTYNhTpo zG_GKM?!OYWLv7suID}>uPhC43zzvuxq&}RK&cw*4H+w&2A$@YtAwXp54>p}K zlJ(_nQ*@0P-o)_ynw6y;mD}lPJEb4knRi(p25xEx92u8@PB|1SzuIl~znK?6;Hrmi zgDq&Q$?&TW1$1fqfy~kgozM1WS-kp0IcOnZtjiClS?8N6)#drG8@J6=s7Du5ArVxS z3Ffhq()LsG1?&4#9ZU2a{!ebD5P0EtTZ?ag|F)?33xFwLXO~GHGGFGxIsPi8f`&Ka zk=3k$wOi=>kK@Z$m5`ZY4$pJ^2wK}+ms-ci3p+cO&6%J6nhwlQtZXOK9kw;#4;iE}UoJRn71EfuY7^WOQgm8s|b6>vz zRwg^>fc82JmF3H@+1KO@k!S#CdFmbl5FZR zolZ8h0RCTVES09n!HA3;6o^*Z&Tbvg1hQtUAqdF}YwH&EDHxkCV9(&Y9b6~M8#Y8q z9KZymHNi6-gs5&2luD*(n<$8nc@eJ#Z18f%hKz`>yrFQ)jC->G&G*bN$11x~KyzqN zAe=8kv4TswA&L};5cJBWux+$YDldoutnR>nIe(NRdi{dhskpquR;CK_A%b3-#?^xV zZg!rZ8g2?bY}@vid0rnj!c-J6j&;kjk_4b#C{SGe&nQ9p!h^4$^Kzr^B*-vW)W(zv_t~g zt85C65WQw8LCCza9TZpQI2P13%IQ-USXojW2>$qbM6S`}Xw*|J7BCu;fAwda!F4Gl zU0vur@pESpwH!P2s{uE`;_)$H{mQ7`=+FkZB}3oFJaHRg{#*vJRC&iJ4@XgR=jTY; zznb*MmiMI9vSQ%%pX^Wtz|(UqEATXG}( zse1wu-J6aw2Y=nyY+u*KrN}>=Mef5ec&OuDsVGpo9#X^6sv)s+pL z9WPBzY#q&Xo~b^}B6Lj#`txitY0Gcq5WTke2@tfZ=g4v{|yro|bZ>OxGPW|9=@N=tjpgYoCr|r@$3o$R{AFmK_e!anz z0Bb0X1h9r-g(1{Vf=sX)1+>d+yi2T0GMrufRdt7aIdv1oT{*QNVSU}`Z1x#-4LKtB z2()X|#)8fLx)nklfn4R?H#ekf>vr2KIB=1Z?QyI`EX-hDJMj0zQL%_3%dTj${A!4w zr)&m+()ZTJhXip=9t!DTHH^q}Kh~CY*^a2!h(G!5H08ijgs^&d+vP-H3m5kyTpbZP z+*3i@urWwOWk#(8{1Z@th=4t}3vql~&z*&nF_C2HVVhF0-qIH?xBU3P72Q<`NUP}H zAM%;Ulk&B`5&dC~n~+~dW!0z643J(iBh)_LI4&N;;*+Rtx8mYViwCNt2Y$x$`r_=p zv6o>1h|q3b{YXyN(Aot3@MsZxIG9R$Lp8D)ev157?k1`EPu4LNj8K&ej7wkA1s)ZR zN%MFsMX7eeGj|0tBzUM}m`++$`A;+~g`G{(FOSotGBqSpBc>EBA8|n8y(V@pI#?_A z8aljT!+~(GflTG8IFZ4Tec_{Ueiv#l!Cy|yutVDqznze$HiCx@_{r3Y!`m5~$nz>S z53!1ett~Nn8zDH2m9gs5z=cOn)M%QkjDNkvN3HbM z&X~B&LgChuiL04PvK#dXsCGdiUBRx_{Rf-R&xuh!m3tS>@8ac&GEhix@MnutW@F7G zl{2~Z7M$pwbp*r;!jf8dL@g;K#QS1#NdDq5pgsU?EQDTvt1cA!5{?X9k9Hd?8cclo z;K5EDiYmk|AywolC?Sb8Xi}9p$V@E`>hVW0=TUY}jbbaL+O5&Hk`Iov4U(+2t(+%! zls2v|z!(gS#`)svQ3ifXY^lQ*&(3#+7Ixuzi^CrpLyUWb2C4!EVk?(_FGBOMFgRsE z3ZF|I-6$&PE~@a5hlurHV#6b1Y$!aGvr4d^zp?f{!1D;Meaj2vA1jx6j&xHVA#FCE zp||m2u-C3kkmCEEyq^ueLq;T@t0xV_K3WuZoolg&<^w09BNIn`?^&BBC0HX9!IQB} z@L32}Tz8<$fN+r;S?T-vh}^;nGz@6b+0~&l0u&dBTK0^pKD6FnqnX(>jS_Z*lN^!n zeF0C_F4-*s5@G}R^#Ryj49wCsqw0D?`ymUI7&HLsDKR3R#D2?fWj$v0z*FIj`u9hn zh}{PmJHus=_+iaB{7J%GfM2fxWjgc6jtKGtrK*AuS4(DI@V%#s721cd`J-a`L#Z-{ z(%Nz+4THWyow;r~`3?boh^zjCkj|r`VX?!ViRggP*T8C;qE`pJNmxX3AGdUg!sZwa zbpK-z6p(RMje1GdqW)#7w?MsSuFxF^^pz53oqa7x9n7gv!_`z|$vz{t!=!nE&rjw; zjAc$qqUVRK;E#hKxT`|2qJ;j{k714+roCooW71E45d=3)ErICbNeY?yQfk32i`p$n zS_@ZjDcd6D*6kEWU#_*yNvdH_6edj!L;7*u8K53CK_e8+Lhv#0+Y(AD!)*mnY9)5q zJirF7xnR+-RxSBZZBJL6rm9`sgu4X4DclY1k4)l^Mh7X#?=h#fLUmaQozGK>EjLyRQP4s#x^j9&U*IQwdCsu39#S!S; z+Q0m?n0;V=T9Bv~gO(0Z=uJgv0Yx3T6IS{t{)wep*zh+$%np28e%s*TZ_xEkuxg8jfLPSMT&W=5kVBJ|NQhZK)2+m#v~$bb>=mn|NGUVBQEOftLutUdjLZy z!iiblFE|k%`Rvmx#n&|gMXCQ#pQx8l z-rO)RvImd6roei3%O!gKc|R(&!LH+Mhw5)TW5EAY*;z)#(QWG*65I&{5?q3Na1RpP zU4mO^2<{p@KyZgZ<4$mwh5#XWun^qc>Bj98$^Py*d!KX19rs_;UA?MCvAWip?>px+ zW3}sbp;H^Oy6KEJ=vMz|0h}*q-*IPc0e<$=Y!Hs?;#o;86a47>`SC9l`X)G!VpRb>?KeBpJJtT-i@O@_#gEu)CT zvttY7gcQ$yBBer0qA6}y`B8}_XaEh=l+u)3#uZf0{kXr8T}n4n%7_?wkiWT=Po5jW zrZSvUMxG9do3(yTr{-SLEKmv}#Q|^2eGcj^PRG{7GT~Goe@kQu|7D0(FejH+ znC6Z?QfYJ2r0ulqhT%^*NV- zs0!X2F{F!+xKus1ed2Yj0SD{%eMye8qp8LP}3U#}5n0~5{ zzCur?029%)G{b6bt(;y{%)4e}cZYm!@%)sO;J(lOOx&bO>fnAZz1j72v`1Ompu5jA z<@S!ln!q^(6~yp-wnnaEOeZ&|G>+L#W|Y2|K(jvBMWukTRH-j$QU-Xfb|9-u0{>i~ z#4^ndSwX5%pf)Y%iLSMy+A!iwRg6te`U=0TN?4sBrJ+E%MnRlikac6%5jlbkF@TrQ zE4kNBWt5w6Tox6-IR8dj%oH^Gj0BOAr6NdMC4Hcj*XE37mTB^ye_gFQW~f^p4Y@RN zA#j_h2Crl19Xw%2JPvmhqpxQUmT77IIEIlGu}@y*y+jYqyi$Xu05TAI>q+;aFG+GOGSrb*J07bqMk4&_QvW1ihBHe1+1yts|zvdf~GY<=*@* zdMq1~=;JsX!IpaRpX3_Z`5uEH2_5G6G4Xc1s~-s6Yd&G$88=Kzi{vCiHe^8kIgvCp zzpnty)nkm9IS176`0-ycJVv(lSXvOuJk8z^g!($&#$aN`4{v7)nsPfkWsX)H{i-Q7 ztpWCu|1G*J&?3!|lSMq$GK<5yfRy+k?YE@uM+s8NPgW zu_7RiB1Yz-xY_}(&P6*H?_**{s90S{c*uNF5p3Q$r)qxkb})~ohn^x(3UMH$E^1jp%P0Y5trMS#Ti??`6SlE6TZ2Yh`Jv_1R`oe#ZF3J5>qozJ5D38rvWv6m=0 zI!r0+QC%#OfnMj>g~eP_%mKO4PXG<&&o?U&g0>aIQIi#4;JDCAn3dOYpE3mHJqJXK zw}=C&t^Lij?Sv7d7NEya{qaPum@gzV?15@jdsP32UMU0D;U#$&8|6|2#%CH8Q2FMT z4@FRQC?+5)043vcMoTkLf>RHnvZ;t^`~!t7?}LiYY-3B0zwT8yMPu)V(-yM_-)lxW z`e&l`=3-};S?xE9=>o(3R5XYodmTm}>UB_@c>kx$xj(;TgpoTuwqW$yTe8tvw*{S_ z_kHx>S`A*VPiXIzD>UV`8OHNu2?m-QHUgW$<0X{I91}nxYDxUh$cCz|Y}}pWR`uG#R<5^+2JhAN7xg;t2HVa-9z2 zelzax?yE;^NMnU7PCqW;yTlgB=9D&g9ij+u!4uRPWTf=uBo#QPWm>0Kwg)ST@tiMz z<36SjMfd)j_UV0E=e^;i+-|5XEM_~pNG%Quc#2I#ObSbu69Lb6Mp1Az)K-)}&D@P=O&m8C*f%WY@x>RQUwqk#d;K>?mW zjIv)KXhK{vkLN6Get#cUHz`jzinlJJ#rmL-rxoVDC*t-k-xHnC|N4IJYs_l$0m&C_ z2qc!rM#!8e%|&l`h~L>&;KO)Hf|MEF*VB))23z;{ra0{ZS(K+M!ngZaeO>rTJJ&Kh zG@Eac`|-^1aqrbAk3fWyo-O$b2T4?B(WQ^hzxd%B_0nV+nj!Yc-uOo@;hq4~^<7cD zoG8RDZfwG8vC(RJMB?TgXPx%Hq0F=wud=`AHCYJ4S7_nk6OH^~nT_kW5t&b7FZysZ z=jyxI&d1Y%uXZP5pin0iC%nv?n>{kIx`WnJyyM?N0GxUZEo$sbd=V3`=35m?@WO&o z@{5Ykm~paiZ+CatHs5nb4n`Lw7i0WJ#NB=MNIx@>{$J3A{suEW63kl93A=|U2AQZ{ zqpd}>{y)KIRbfJ~UvndwA{zi#4vFHkrIlqTi@;au_Z|pHs_tVu5JmDGS$P}~csMG9=M$rP-wx)cBXfj{+}1eyt5rotkOzS0AcLw$EDE?%kW z{z`I*oVvXTUDBlK1u$$VbZl)W03eow2$mAhW_Nw3J+1DKYNyK!+mr_PZ)6QQ0Cc+= z>?ImZ!wy7|r=yVj2E(G^;r1PB^0=^wO-kqZ z+($Kn{e2h`C35Jm?`tZJ{0~crGFB{�Ri7Kdp%id53vxrP_wdWrTesK4ijD{gmXS z8Wm3IBOb*itr=JL{d;3EC%`t0CGPq|4{OG~^mGj>Z06k`s65GilK&c8BxaBRoj;4p z&*hU)r~LLtS4t$J(kcvwf@Yy*uVR11z&>WqS4uJgF<({LFw@bRHimTwqFIjK>pc(I`mT10O_!HMryQ zyTowd%P~dRuv_O-C1iA|DwO#U2FmSk!aPHvy)|9Jfb@4VskCg1+a1W%gkP9*LMSxTdx02{owPG()7xaEG-slRm~QW1chp7PV>G!MHFX zlr};^S3)w&lVutdA@pQ|@3qUD6iR~ap))Xp)Pf){JXky)L7Q1q7e&fjmgXcqcqNZd z>2xLO3}Jd=lZitHn=I;3M*$OquGOwQo@<(w0HowEhFig2Jz}$FnY^a`E1p<7X2EIL z%*|1=0<6S?E4H;XMFf5Qpz(Nhax$Js`Qj@T;>-?o=d%0MfZ(RiYZ1%ivA{-S8(2}V z6bs)Od2M`&GIC@(wgM_xAS~1GCfLi~ZPQm3%%nq>JgihvQ94RD6#q6=6Rx(x&x(9MOYMXLDN9jL1lQM9+QS>=tjP-E%X47;x$ z7K3mF#%{*``o93gF){ctape{(FZSHbRx6_iY@#ZVmS5N-3xL-w6c{roK5@7hTG-gI#-fHTG!)%edeLL!|PQ`sCNPYuI zvs%{tJ$K={+$HGuu03uUH9XAKNOp! zC+4}0SisQbTvf9^{fcCAt;$z_H+eu@mh6q7swpdLV_1Xu&vRwY#VMMQ?!G1{)r!~X0d`TsR!!9ynkYgitGrglto zqEC+1QHL#7(f33jGXIg=FiEPIT@I=^c6z@2k(t>K4Xsu~t4%}e4XS1}oSd>YEf(ts zF~WEAm~`GJQSLYAF?0teBSDdc3gEG0t}3~u+hz4?Nx9i~)J82FN4ZHZw~F(rDR%3v z?=eaJ@u(-|=JSBAX~2S1W?UV*=rq^i@BYoWvg6KjC`|tYIW#Im;Gg8YXS);sY!?>?C19!OxaoN? zbn+G0XX1RiRH+x2DOU(vSUfhTwj-ZtHG0?p`*hB4oLp5g zn3=BKK7F!6^Ll*ZexZ8U_-8`l`*nHVO#_^kpY11&V76D87Kfps(hBKb?r+}24qIv` z;b#hat{!*!=7;OK;%T?Ku5WX!(G}7f>D(-U#wDXXcceNZo6*U}6G8Wjm-=TfF11?7 zC}*1wj-GnE0i#bTDr^%F07V@{FYy3~t{!u;e}kQf9}GvV_^AVgq7-(PDQr&}(+6a2 z*+A~3Di|q?)&Cce@a_Jv?y-ZpMxx3qKTv<*?uoGXMFy8^dcs>dG_+}7$SkNDXWj0* zau$&&-`Mo%5fpo|*@-{uW%$w(0hh-Q_OfB8bC|45s;re#`|UoS-#t8l|83YEwCL@9 zOO;dgUF6z`*zZi0o+yj1)_)YkJu7~fc|1*&z_^h!liT&@qjkEn<1+i}UYf6rWQ4qD`gx3&9v zogXH+F>L(27Z#(;d5VOkb$wO&?p`;+a{Nci;$k^lrV4#qYGR%9pd}f2Yj00;_#Jp6xRo|a$Z{SwSst=lW3q8@^x zyzXPvF)?5+iwSZF?z){uZ-|W+bJ#nLM{Kfw@ce`gtO-@+=k`>qedCW}$ipS6lv29D z-ExO;@7oXn27n#2eLvW8WB@j8oRg2RuR22aKAu9wQ)t_>0}z{ovq!`p0~u@vH>ctx z9}LlGTq67KPf!O%ykeRK-yg^Jm^6AZ_|z4otM^4~OfMPwtSt-^`&-4snXj>A-0x2{ zvh`r+bvYOxWvTbYym?_+14FNbJoQgt`*O1r#*H(*g5+*b`)S0}0at_J;rfp7Me=}o z!eNUba~ttwlT*#><>CmXGD;U5ughw>CGWMQ)7NX;j%#_Qt0Q!oA;XmT;jb(6yW_h_ zkZ7<-eftoc>RsAgC&1EJhc~CSrBvs=&@D74XR9GkxM-rp(y1sTq3IM_7ffh$xcl`L zvX+)se&M_MhAXy=DZMp=A){LvSyjpywolRF&d;{4YON@`-*g@95E`yP5mn5>^qa>n z7c(l~$b=F@#TnLxH0)a6O7U`kYOyoLO5wD;&ChDTj_5Vzv#W8Q+Z=)o4w+A7q%yQs z8q}gOeuC+h zjgq+wvqCJpIsI+OIIjiVR~Vj*(aQqXPtqm4FGw$bgI-`GL;Xx+%?x84`!{M>=tpH$7RVKIdAud3MY7j4*f zT=fD4vJ(0-=C5%fkf`ZAZSvnInL;00B&imT_q@u6(WDJL-yQawh56!lR6)==>a~~d z3FAk4u;tqJ$aaIPBO)T)jl3QE@syDf5Hv@NT3#NU4`*bPOkX0Vo`9R%uVH0Js=qhx zmMgSnox4O%0G3><^PZ)LVEaw4a+VkGt-h)iQ&*2kx4Z2fG0?D~OQLArS6S=31&Tcr zb7zl`;$rCfFoP{bd~DL&Dk_cL zx_fj_i9~pRh0^Uqx_;2Y&PNDsLO54SQOfkwNCLoqsJyw?H}ZeDIrLWn3ZeE|$U(|8 zMGu{s`VXNWk-J>4KR@6TJ{MED+Ro$!HO`eIJ(z|Chi3A*1Uv&BNplS`zr`wj`^deSImH<^ zIbfNPMllKBq>B^cPlKtKnIv+F{I@D@ocq%v|6SIZjn>wNIdmC}5D-hzSo0@Am+rR5 z?vKyn=!*hiw3jzF3>GX)imQG~udH3u@B74Lcx*)~3m>`&= zm`B1Qdp4IhJ(EBe8uh~SCRNb**156`)t`l+Rx9tNpdS@}q*5jy8gIzBJEei-_31?E z0C8eQ;et2$ehkksqbj?Xzx21s?ibhc7TS=u)5 zMS6wR-V3T0rwU|zZ`tB_G4cUe8(YpQqbyu#hBd!$aOs4xJM65641I=G9Xk}7Y87o6 zdCzqR?H-{m?sP0X#BQ#hdfXw??$6ZY$<;etjABB>?;L)xG;+LcBXYC5Y0WQ2L0W#E zB69LsfwmI5uUjnpE$p_4974mA!_9LNCxHy`!gFlrD!kW$o&-=BtOQp*Bfl3yot2d} zBsx6r4Q%4NT@s=VYsccuye=q1i(7?iArGmUHe^Cv)-BWdW!KN6HOxrj1;fssK* zmvy@`)+uU0*=@PAT&8@`r_tl#PEG3cs`9QbT8p>j(MY`rt>5tGgt-%Vc!g~Oj6v~|+r2l5i+{euHdr*qf! zm2K*^26%QeN^i=h5DeNwbBa>jqs$s(RYg6ZQ&per#;P6VvwSwolto8I2PuCjE?+bj zpacgpOjv1XB?1eEo3X=>E%FZMb6EdL!cmP5Gg<+ahzUEwSmqoLuXR>ZQqottPvQpG z{%q}CgvStr6T}H$yGRG$a3ns`X)N)XOgF9e1Oxx z=y{_W@VZy*d^P&kLJPza1QC+*4>xstKX^qiVL*z$Y0DUBWVQYq?N_bXls?N^;gU_! z;Ul?P3kbDTUQTZAXW5+W{8Rz;$%#4QAo^XD`F(-hf2vY&L;saddA%16?m98kbUdk+ zKvp6Ve1`k-ZEVIzQfk%|0p=&7$w8qQgCjqRIpBf&O0hGv^XV`S?fN(LZ&!epLY3o} z%O@TVRS)0~`e;z7csDhm;{mf?EXM>_E~F;E>2k7v?QyFkVAySn8vO0liQ1a-u@}HB zvotnos?$aLJF=L%oN+Z**P{W7SFh^o>QFK5((s&h_KA;Lju8Vrv01ElMX9S|C<)}v zfuF8HwdC&3hURRdB)ls-{hQ|K0QT|D? z!5Ik|nTSuN+PkKg{8!?o3&sl#X3jQwt4Vn{S{GG_UXWmf!PV(8u5kl9jdl0n$=M!< zMEFIgvw~3HyC=()hGmo}u5gFbT<*i#gIhvPpRP&k_55_&Yrf|xi#*gwG7h%H+f}DO zEFKGr*#W7*|LHw}6h7+zI%vBZv#QcHF`nUFDkv&oy*XZR%5yx}wclj(3vTuqY$zK} zd%=DJt%OueTRS^DO)^gPuklWqAc2ITWO}py%M>p>Zf6Mh-EQ!(NBfTK(FdBGuDacg ztca+@X)vE8RaSzQhz`-GdWhKP`L3?j8Z6+5+Qgp~J#-7MjVkn@TiraKvNKq?S>E?~c<}FU zfj)f8DAHv9_a}nm@40y#J=4Zqp_r|%2VNHEwa?itEpM6yfx|yHO*>e)D$DJRs|6TJ6kOV!HK2h`l z_emM~{E&)wWqxKth>Se`xTjqU9`QG-?s5K_iH>Yqs`1r zO^+{UWHlZ6vCy(J8hHEe0j?Ad5&36XQ9vM>WQjZ>Te$&rcprIF8GHp^^1H5%gHBs> z1En{pb0_^ zx+z-cau^tdUfTCx$EWsJu>;dg{MMv4_Q@8dZ$--^_sF zOV6l-G4#^JSRqQ4E>^Rp`={COYxncqUG-QbC;BH24bR7JCamtZRxtHbQ-3!Fwh4`sEf0Tv@N?~+KtK$;L`2|O+ihZ@q87f}LxK{=3&D<&mcgX92LlRH#z<)oUEO1XNRZME~rx8i1HnFy(V4C*Q6}=$m zU5t@GPt!Za{IyS?qcb^f?$^<`9iE!J4bgC{n0#vFtDn<3G{MVAFx_D1gPZB6L zNoOHNExoqV6DPbJ;uQ#fh8%x@E@$8Vm?iamz8-xV-#KA`<=r~;^%IXoeM2_C?4Dj9!={4=!_|8L5sZR^5!Q!|psrdpuDCF#qg zSHpp#m5*P~Oa*H#^WNTWf1{&s8juGQm6Yl^RbZVwimekFl!&$>aUpb)leg zY8E0(xqb?X-mpN*GnCguzHfUh!=fUBLIE~CqAiv-JwB>%k530&X)y_wAu1*?D4jVF zF%uZ`XeI)E5J<6ztrh=VS~1i6q0zmEr*Lo&4~5!a8Q|dHkRF%nr*Py)Hy-uuUgE$z OaI$ZeB)^Iq2mTl0g2m$i diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png b/scripts/tutorials/expansion/ur5_pick_place/assets/object-heatmap.png deleted file mode 100644 index 39e799472610561f128bd641141fce9ec87d409b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 54641 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 z zS6ROBASg51w0@@1?h*SzM+2%Syt}VYQC@y-W0UKnvyp3iC?hdVf3mqk7>4WR3Ul(8uYJh^P6s0*p~i{6eKSEF@$TnXAUJfC!^7{9q*}+6{u9 zozI-r(nOgyMl&C}o~)0e+>)WBY@R)<&_Y-6U8OLzZk8MR&g#^uTxn@U;|MO(8AKx z>dL&eo3BVf;PIAn$T{E^0)w9!+^PoWnFghC5S-H8#ZdkC(ZZP%ae;badS1dk%Kr23 zt-j7Fdj#7yV4!blWm@fVkqGQ|p^itC{4e;~xoK9L0MqV(+<-Qx}z9 zaX2+XW}caWj^S`k2y@9~eB{dHlwz%}u6ant9_?o9tXt6qXkUXKZW9cU?kI8n`S~cL zp2-?3l`;H=N0NgeIq}2Orn}0PP3JBkvoN#5NI75CZetmYd8Fbzct9|TVetOm9^3+@ zE3e)WE3NVHuVAU*YJrENn#jrw|B#B1$VkPcF~^gW>zj|q0ZdQ9Ut)b!K(f-OXYs)R zRj3sgl`E@u`ij?Ko!et7`XnrPf?;*g0P+0UbI0u|LHmi0syns9iJX>orVBT$t>w}o=jBDfW(kN23?mVE1vVU!xZs4Lz3?w#aVk-6t5ma9W1<`e-QLm2gF;MQ!7#;$^p$Gmn|X9CGuXcDr{t%V2O zyE6zXhD@DQ_uE*>N~lzBUXLP!Yy$f)Uj!BIEY*jtF1R_Fe9;iP)aP|XpX~8;rO&2k zWz@O$GTgSYVGvd<(keCUtv}O)?gBm>4r;j zi2=(t6zE4QySZ1slDxF9iiK?fE-{0kHpn(OA4y=}>kBon+YLATs2CuCvdU#f{dMk< z#$SaP35kXEt$tOaQ&#ixnQjaR264E5FsfIlqG};04-t|EoS0rfSVl} z1oheU?P=s{*3PPwM&p|RC*C4*##VR-y;FfJFZVf@cAo2 zW=CMJF5t=+KVGcI8VDjzU}hs(AR+S=|M`~{t(^9GeFNa9HVb>ZlBCAMdgTkU*nk_@ zEx?w!%>J+B8nanxt7G^2b;L))&Ihk`9qQk^H1y%U*v1KZ*eUBTClK)O=eMMLuY=#g>%VPV(X8>yabS)TLJ;D(xVL{46m)Ba9Pm-neqdeAeShsZI0ZBO@L})_ZjIrhqY<<@Er6zOfxZv0 z+}u;Zkf=p0Jd^m-R_h>?Vj}lyZe-+R9Buf7r~vlce6diF0n_C!7e0gM;!+J@1p}a% zjb+i&R&6iPs7<|wq4*aq_8}qB>gu}FmX+7aG6zgtL$p!{!3@$CPQ=Vi%tXaSZHSSM zo3;yGZ9!xYiSCb$vZ-^snYF2Gz|lm6Kd<_zpV9++o`+Gq4tXeu1RHE0)U#Vf#m)h1 zq>n^=18j+bzZVdSpKux~j#n7OZLP=xqc^Dq$5UsI$3lkf8^p{H#Ywz{Qh;uxj;Gvh z5~)<{#Nq}k2U5PS3KGDjd*prRPZ6GGvvi&y!M4m_wa`N(3XJ7;hL%jVEu=Z{O$Vy- zf}m3q62lX1I|JVU58Q4Xc)3a^EvWA*Wa#U=3xJqOV50}p7*2m|p)KU{VQ8fN>cQ@X z-fTR1Tp`Fc$@2gFq3|g+A}i-vv0kZfp7cBUZ+X>i$=9XADQCD$CQMW~IJTf1T8<^5 zi&_m(0-c<2T`ShCe5si6x%`eFY10 zrfT@BlL{aw00@b=76DT&WwKap@`w#Fks65g3#P;hW`n7>n!=#2f2m@-5RtW|;Wh zG;C~uEGKCq1zj+&g@plp=nrHcW=Te=H(N2n-ry(h}V=NW(* ztSBr1m1Rd&qh~@wL=)=$8_&!0wJ5W_5kOI}0QrE!VJpQ!7{%zdBUmT zVc*1q!&d6xYu=4-zNb-Ii$?QZ#K5T}3rIQc6BCzLn!i=}W=q||b9*3wW{k;%We^0g zRku_j>{P$((LUFL6&7Ynk%8g(62i%P8&xxy3I7sSBxoo)vrBZikqhQMmy77=$mkc4 zofubyer}yk&ZE2OeAEH`l z%*;acLcJAh=eKIZdp6ENs`lI59AJnPYE|3;1KW}Iv4IZfZI}#@x1l!AMEnC>sv3>D zx;Tq92D5Ljh@@=(%mmx6Ze?qPSr#D|Bs)`TR88_LSP_oasBia($DQT|XnHM8MssxZ zpaRF++(Hdbh>X;jhR;v=aGU^AZy~Czt3c0}-*urhRpVN7dYT*dcoSd%!orW?vu6vn z0ICB{eAW<;GZ;`$DJTpQsvWLdS`QbT#4wJ#pPwhPn@!|8ZO_fk<&RtK;MUrolnq~E z3knKu0?g)o7=f=fF?DisHXMq6`j2X0j&h)N%HL{QlykcjY+&WMV9KhWnF+KeU=<6U zoE1!zs7Oi%osw}`_TiPlEJtf}5MV6=RsSd0WKVlm7`>9Gyh-;My5?xJ4P^vKYoPRj z(2)`o)Vp<``eK~dM@EKnucw)@|A_@@2F;`qT$G1HYOB6*|d3oVD))ZWwPXi=^$3 zqF(nOteedmUlpP8ux}14ev%*Pq`nF4bn5Icr5)=N{g+!!*}}=~^_A#$4?Y<%W^BOF zo`>gO6BBu31ZL|!GNCz~An|uAJsmJt;}hZN2?@ZdzCd!_2?}a%PF_$3)<5L0%w8efZ66BZhRPh=#a-htH{ED()iwMuJibAVA{#HFW`0Tm)$uqs|% zOpFFw{$CtiI)<13ZpsjLGc}HWT`?ANwu)5nUdHD@9IiTP`|y&2}ZuD$oSK0(?P%p6k`)$#@B0L!`l#B?TQ zs6OtkW}|C=5PUW_xFIDJT2u4w+w1SMg9Be5i-|q<6DwwlkkDCv@iJ>ZtRQ2MKjeYnSr=Uiv#Ne$Br_KDRL&JuL3B)6QpEuImSjPAi;6mXpAPxFx+KEL+jkJevLp{8`2jBFv4wZ zf31M{09R-PEX|_^rK}>wzlU`kY;yI;drXrc?T^r-2Udf_uw zPCd<6QlR8zw>bvdet(o?PAMYLvAn&1$TPnp=AoyEvq@Eb>;;M(`8A+n5E1Tjgx6GY zvOWIuA_SbNEG*@e%Gc`~&*cK-f`Qa`@myKr@#8%jxPNhW4dmWa1`9t#+p zpq1mi@=GQZ%trto8xKlNJ!Ua$>v8bo>;`ZOXX>0b_m(;i*>`4o+$UgdgoGCUe(!+Y zqV+)}gBDp~aubsLt6RB_7X$FNJML3CV0t~(~TqPUuOrLdTo z^TecNiM2Hbvct|uN4k{8c51m9z?Z}+)u@C`+6hZX|I`5SZ~LvIas~<9&}gQC#6f1D zsYsXzIrD+@q5bE%Y8tJqva+&jeK+I0=^{ZzsoCVn;))=8PGuFrh&$k!-U>`2%_mh@ zd52|>YiWsBSg7OS5hxr0$~|uv3`*?qtHKV?d&?fXv#_&dw>8gW-k1v62S96J z@*18Hp)z6sh-~dri9!tIZz;SHT|GU4!Tx3jW*3LQ+!~s1@eMK_^{W*GwSX2_4C^z7 zuRnZrqkxjFYn&LNa%M8f%INbDZG~P;wCA(2@j)O{j>%-P_=!zc5C9!oae|~QDCy18 z(Gx7^=IQ>rI@j)a?dIk!ot^8u{e-+?fna-raIOQSwSd+OxR`r>evt_^M|xAg6MM5w zV3N)q!TAZmCKb39g@k^%JskTwGv(>|56H)xW~u@LrU6N8LJ;cn0NLHz}6e@Skg8?Sxwf|00T=gDY5wm1KF|OI*<+zKSbH(-73pnyo>jLfILi> zbDTc_J}}d590seItC$3}_BZ?KC)?AFOIuZ@5j8)^>2R?}Q=7oaQRm(U5!2EW`S^_6 zwf|d22iguEiz!P)Y<2Fa=|nRdBn-k>VFka&5xBQ*x0^(42^`Brm_FcEKAA=I$W^|%aDVr?qHQg5Id&(^`zG;q@8St~K} zr}h*iKE5_HRNdmV{A_N{R@)7O{_5O&ne!_>ro5$z*g~_h#^wMx4Y65F3fOv5CdvhIK#ojDx;wVm{s)y{6UmFq64i3}$&* zIS>vMLcnbZ;0@xzvw*PoQC@Mi{laIL(fJhs>b(7}nEZwJt5;QP@0tIMCQqZ&5u~CZ zQR4zNr>pBndB8+D5I6uu@VtkF3Qk)a=pB4qKG<{Cf*Vj3uC}?x%ovYVc!q}`4td9m zR)a(R$BqRhFDldT9Mit(2|1-cs z6b?4Ntu)Yfs!V_nnV;X|i3%0&C%i-qxI%VHP#=2D@*r+V*waAQ(kSk^s$caW=z%6& zyuAv}RAEkzzRcW)jFaDNg*(O!8UbsCc9?;DdcDhm^XE=O)x)#X>*Y{SyI$H!yA9V* zV-7(-fm|fnpNT>8DuYH&N={qFgv8P19=}b``Idw{kMn~c%xesbh=qjMT9ck1**=yP zKuP&3WPU)1oLn9)-BKYW%Hix1z8mt4o&5}cfXP#3lMBPrHP&PxApyfc_l8-b8~_vZ z!@Dfd;@CM~tcJ!quWfS&12K}8?3oNh3-h|^YNvY8t$_wk5l!129~>LcRd42yAOmV0 zm+>Vj04;zyG&A!XYBzh}#tv|%l@`i<2vE4CJ?jaNQs~fxc@ z$sZp`1huyLfp-oxElv0-b*`$iDit-gufI4trn_h4Ybe>=j z=)t+8qGTVo0hQ-Ehs{j0+|dgAd;rN>(rA;yBjmCFXU5-GyjP`8LS4cYh;E={K~(Jz zn>1%h#DOhW3W|}*7`V&~&L1{4$!L;!YT=kzLnfb~KqSl-u~-ex#=(J$Z3N!2FF+e+ zYs)mcs~S_UNYC!cLLghJnw)HT7=K#9<$$oVwR9xIC&NT>(W5uN2zlY5r3IaXNx!w< zXX(zsl1jp6wle;_yGCcC_%SeQ7ROA(O@*D^Ok<{K{?!Ad_pko0A7DA!A(>dAy#j+i z_=ppB##gAGc)Y$cSXSK!j>m~%XntB8Bz`zm!9+|aBO^op(=v_Yo0Y6wz}q}_K4D{c z3z(cKV5_I~s_5|xkMTSF9FPC?&_PCFRb1n2`vw)@dTL6dp`uEgK-Phn-h$@*av5Q;3 z-uPbXs!NN<0yf}RGZQ0|g9NI|*VIUwTrRRgijn337#ufTAfB@Gt9~l!@+y0#SPcyX zM^B#n@jUiEF1w`g*(`=O=Eq3@A2nsaK3pI-23%!xo&AbJJ}I!41Gt;qW4Ghouae@m zHJJv$!c_O2l8=!~Ep7zrSw`-PnKp zcv!Pk?+zzxrGA|K^c~onH{2J8x}Ki_$nqqhWG*8mMSr45Mpf+bN&#@LK-H)j3e;Fx zI+|Tu5}rlBJz&4p{RBgv@ixGAlZfNKN$^&)*6$F7W;6GjaHz-jnp%$9D>KU`Lmy}HN=0CNv@USUY$mXTEq4Tq#A zCDa#C{ksmPx-!14gRk?Tfv3)H=`Kr?cCBQsp1jD`7a+DzP!}JJh=ZP|U0E~ zPK9}&Sdr*&9uoi^{kyL9)zV5G!*wn@JcdC;3yGk-Bf30fB=s>y z(py_gDS~9P)6UmIWON4-xDw-)-Cvog0Jf)6Hnb~9LP~78!b!mn1BYJB*Oq}IDz(*@w6kE2IS1tio{Z$cJ=8!}Bm{XDxRY5bjMpX^_~ zfU*2si;q3PCK_@BHp+Op!O@1lpD%DQz1lw;fjL)*xmYdRb#LU zIumU9TR?&X489l=*aa*7JUQ(*aqv5-w&Cj=k&%%fp8*vGGuZSG>!l%KG+=*-*j#A? z%?ZcW_1&UpVkvWOchFmY1mFV4gU4@MO8_x}4XR$1MM4_XjQx+XK{~zoLs^{n@$vb1g#b85KoC=# zsxUUz6~~Ywrk-~5_lv<(0&%f0D>Ku6@fn2)Ky}NBhTz@?TukSK?lzyIkg_s)s6CIz zWwKx{Tg`(XaY}{r=Gx=yd-C;qQ(zya5I39Fx)e5`(-x|8ofKUDjB`chM5G$8HKmXM z<0x@|Sy`BTWWYl-8<#WJ@pY@r)kxrf$L{`_2;&9Sl4RVH5xlQC<>- zr*9Sfd_{0&8oV;&zg&?aaRP-!w(f5KNU+V#IBjPeFM0%d#Cy601O*Pe(U@3SE0Y~v z;al)Xv#B5V?iXW0AE7;3NPy-21{)Mwd=fDl1!8DzrCDNr{y^SnnCY#B(b#scZ;SkA zZjbX*z>WRx^}R5jw*^$1eSZRxrI?sF2&154$f&5@6t7WWR+iN8ggtj@h5(u?8$^Zx z2DCGnn2G^L)DUf_hlWzt@ME&atvz;CcXp@98V%M&nzX2AyCh%$O&oWeB-*A0%AW_6 z^#N?-`Z~PSKUD`z25PwKTui|H0HB-!(|f6ZG6P>6uA;nLSSb5w&x(B_UTzY$iGs45 zCDC(CLrrzE@%D=u1$n!Zo1@mAQ&zu~USYoT=6QseR&-9x_r^kp=`p8jU?3rbg1UQ> zW-qsi2`r9Ko;*4}J8j6~=LO;5b5V5FyOx;c_$X{5;X(=y>izbWCr5d>uqT`j``9kl zpP+QX30%5!{d8NlbIYx*32~#9MsuOJYv~bd5j>>T=9|TrxyZl6V}0aVB!*ie%OFw1 zezQkl-RrD^Z^1(j3rq4Z53Q)Xd-|8DobFr_w6?ZZ3zz+abeWs;FZqOBhA-%kkvv}f z*V@6B0hGh?4Bpou4bEz>t+c3G3t!uqv3M_MqGtCrFn@Clfaw*6fQ1f|?ee;_;!_NC z^g7U}s&#u}S1?(mpr#Z>@E)(x?uz;^GXNC(*`a_P0mi`^6`v{qF?u6#>L^(DIEBd8dUTz2MDp8+2{q;7l4KY__O?C3x0vs)1@`?Whz`ij36*c!R_<_HZ3H~cjZ!+_t?KOTJ!E;%Ktavo_0_nGhWeJo!TJ?E&SD~p zY<7KCNiqyOQ7R)KA8C8$RBc4%nra{#ek6csR(A(2@wY(M=8d+fYNrW$4mh#Bk9hJjlqji#w6Ijrk^2rZyo*S$zE~!3idH!|rQ)nJWI6i#m(8Ca~%A z88wFud3kxLM#rIdMNCZ0Ue{cq_7eH<=&vE5DIE}mf)y14Mt5n1K>IT;GXJM#_iI2T z#Txm*%nSqS+}9+=a1oRpS|N{9a8UpOfa|maPci&dWQ+I#fj|I|X@VIeW~6j$I)AOZ z?I4HSsC}zlk{!z-rqU57FownWvqAz8e#HZ6?o^P5pTA$w_FPzGEHovj+PXy%+5p%J z$fxH7){`KHHxcPD}U>~!?&jju`n_VBTg))ZBd5W_@1aswGB6Y9nVJwAyl z|NkPqoqfmu$0*-dca%#CZR2eZ#iWc6?nKi#UkX8+jFA=V_aa5Q_xN|?0sQcP{?70> zN}w6Yvg&ttTP~`9xd|$Y2Fa2vn0#gb7Gs}J&maX|Gb>>5a*6!$G51xn&-E@CD*O>Z z`4$$7UYM7eWAUlAI+^ma<4~o$$>ZtBhap+nKLXf)@)UG8vbIXuTW7WZE-c|^m*4GL z9^8nH0gyrwO+G-^SRVf6dCM|Fy5u`Y#aHbZmQavH{Di+uw3r5?_1wq4!bbxtd(f>%Fet1>B@ zlG+d>{#DVR|0VJK>LVb?fP&qWlZq*&h*1k1DS(T1^Wt}J?inSHO3Yn4caT?CBsm{((v*laZ0*bI-Seg=ai48i?|~{J*_Q{_8dL z|BHXUzN1ld6wT;l-PbV?%^FAe^HK_vR&#Qw!GZOzP%z$Dy|DDQPUBZk+KmxiD1gJ( z-0aHOJ$?EBX+D^|`*tr~rcvgXmzeZbfW+9|Z0`JehI93V%?cL2Iyy>CO}i6h*J0p+2M8;MxFq6_at@-MxqG^N5PptNCj;o3$w*-*1Jf zf>M@_XJ26>D<_*R^h!{d&MZMtDhLB(W!Y@X9x-Y@U1lBQvQ_JFsZ{Xi|tT0nE!ifof^r&YB3kw5NW)Al(bDY7}I3p!AEW+-%Hz!LvarmvQ zqLleg!xaz=ks}XSvbA3y?=o1GuzM;gBO}u&9DKYzD>@=kWW>fc^ArWZWtNtf0OdR~ zCX^3ob(+p;jp>m!(-_>E4qW zs8MT|pv&1XeyX#K=x% z)%3on4{ucFrqzAN&86;GWgyyVeC-PmPRpHwm?+V|jsD<`LNGb^Q)lSh4rqQ#6%?TM zOW7G1d{7haDDr;(h)Y31!B*N-qIZ44LxTYUuji#?3^505K&#r8X?11_=(|Z(#_;_l z)SxG?Ha{38kdXyTSP?$NJ1~q)-zGsg%}aSur3BucfyNyl~#cH{}HE zsHycJf}0v+)mlls{l0p~>-d`=N7noMvH5C4SES!@aj_8xlX3C!EcTbD7`bEgWf#s) zPO4%XDR(dWE{;ql#1hW??VYy9%g1a^J7vZSulZ(!5*Yb3WwiS?BGBK5efv{ft~BTX z3A((pyu9e>=!!^GxXNNhc7Nzy+6NQt?<{8_=p8ve;2s|AHghNLfj-ewa)sF998m#f zZ0RhZf#NGoD>8Ty%hOmqq@AYvqnKqpE-AB0jIgXa@mgjp%M7IyqR$rF#w0_Y6^ znb;K^^4?Fh%IoVZ)rKiy{vjbB5eQpEW)^gGakQ^+ZO&weu;%&hzMy|39rDd_`Gf0= z-REs&Z7%kR^tsV%a`%_%_;kcn3#D_l0euZ?o8k=-q!unN&ZC4zI>ywq64P@xj~t#Q zyff;S^SH@Xq7SnNuS;(<+r~uAlMA$MAupwY_!eZ;cn*(HQk(M<UV0g2SLBpE_t#+*x9!LzbKj^zSUdj_OE&{R>q(0Wp`1lFyxFCMyS|)dOIl?If^djOVoZaWQa5FNrLJR1`aHV@#;h z%+-}kG{u8(j1z)wf<}^MwP72#vMnz1GrbCC=N&}g`On>BM<*H@8V|8c+q1>*^Sm_m z9+;kRdxa@`Gxnq%vj85q3xd79GqCYY3J|eJc#Cr$%H`Hh{-91GNYE4%2*K%OPV5!3 z1|Y8_5J&I>8qrGq<8R6U%4j<8k!A`%?CL0-m*V31r4H;QkL*hGgM~JCH55yG(iOZOl)04+2=r6G-n6`S7rWPEi z!^1_K!XgG14@0tP848=211?9BgR9ScYjoHH(Pf@K4ctDP&9DCq8#bCbJPab>5olD9 zmmeP5x$eF3MZ~L&U7zayOz*1i>vK{pj$y5}i7HTgYaY$zzLls!*iKGPGnPkY;_K%J zIViP0ie3dkeUqz%`x8JC))y_IBnRwx`LcH&~BmqN8I4>)rdPqO4Hx_1Mj)z2qo@c|DHH+%8au@(n|p zdgaismi99Mhsl!Ob4y$A@WLlFH?n%J(IKi1SmmjenW}tLo$I zsBnHD;dob*XAPdjY@rE2v!Y$00t_`-McIsOY(IF|L7v3S#>&dL)oepSEW0HsEuLjj zjgE;crkQ>ZvA9Z3MWxVBkM{WSy!u2B-?im?tfZH`Zq{X$Bwb`V zuV1H!#z%KnvqZUk@ht6$#~HPaLr?C^Jr;WXvn9u)=gTl5(Z$HN#ZGY1E>C^@;I*Ajl|^ux!; zHwLGRja0zuywYOgaz(u5yJQeMFpul$w%;CSvK?pKj4AyI1d}W6GD0nT++0#NNV>aW zuu&%h6}LI^k|YUoX86uPG|0fn7Gj1;*}20qrC8x+t6QH2;KVYBy%ywYlSjeGxHf~P9Y$=eXXubz6_#PUX7UfK3j(%RS9ic|>Xd$xz5n5x8>fU9E46d*tlfwVxRLf1eFB9d35Y@8ImUw z4A0E6Ff|@6))g*cRpWG#eH9TBz9_d!)+WTNzY6CA+52KTt-gEeXB>$L&joWS!TU38~ zVr28nz!EardPn7;h>EhPD10;!Z#qt6eR;ZAZcSf&+EE7)(Sud#vPG^i2vUq=;Q5Rg zH5+qqT<`RBIS~rP> zaWJ2IUG28K{!8LPn0pc3ggkIR%lT%%KB(P23!m&g`SGn1->@u8 z=bs<=AE4lO=15v4&Kj99ld#eqO-9fV)}GKt8%`C=W&KiI8ZA^AvG^jmIjU;M!@9S- z7Y4>i@_lzz+m!?J-3rqZ+sUnVbe|Y&WQ(41yOUCrZ!9lPrYhua<>i4US{Ox;j2+X? z6fn&DiZ`0KdI%IG3sh^}eK%j9n{$JRBmz0Cx7nf#5$=cdaCk$Ep3n z^8G8glF6@c&3dYVcu8RiHfy7Ool4J1tBw(K10A)+Cm%DYC@IG$7`WUIDYN3&i`}MX z-7eVC&awxcU5I;=+cl*)mxh?02UhsGtJXf`x`(1zzd* zG(x5k)xq1^r4vgX0jb8&gaUdgup_MO?MRq*T8q;d5_z*4%1cV#U>OR(@yL{@yx!#r zO8+ROga4WRbVBZCvhrr(_;i6^k*BA*OGQl_Q0v^MA_Hx;RTLELx=JuUeE2}>|Ko=j zKF99ZNhdh>b#>)xBn{qBbwO~%@4UbAIt-wD1G{M^nnH3%$8owJY9M>&(b>riQN? z?GUxfyEZ-(ECmI~y{d|6xd>SiF=ozHVxDbM+G zw|UuUNKhc!#ojrDLocBPh)TVO8V4QQlga~2*M9rs0AO%OLLo(GWk;;tt~)Rr))Dl> z`}@_9N5Vbdx4&dAOL06%fn8yRX0@r2wzhU~BDXgxUa@mECp^i_BsX`ezpu^Lh4BhU zhRVo@)BC%qOW;3Ax{1uy~xb%;(18Oey4o4n5l@>ox@e~yV zk4fE!*MDI##FHFVMlmEl#d$Mqy!EbK5@txGN0ezsyv_B zoP;)pqTDczU0To7%VsB`izx?w_4`bs&B6MBI`szqM2^hkIjMV8=|oj66%x|ZTmBQ$ zvobBZ?=R9_#XyG}OFj7^_)p;V&n<=E|N6VObR>8BtZhAB6#98ya;B$fn8-+{XvM#a z|7surYb(DTls_dVE^ZwBYjC(sYkgRZpM-*Db1OzpI*BXgq8{}$J158L2UsA!fxanI z;9M$+VV47iHAt@jhPJ-e!P>%d!*)|fH?KdQ%L%^dw85Ee;q5f+wDq@;Yxna0p08F9 zVd)Izptl|wF;i1jjEs-Qe*WD3yw%DXB?*9(cZtBjkvFa>`?Vi6;DjdoV!yHd?D523 za&t^y-+;ZkhT|P4(A@Mj3@9qv-N(q)s(-B2XkaJ3q=_2TFY4<{^zy}e23X|a+-WWK zvyWrzQOa-l&${)-EGH;P8!hed5NH%pZ*a~xw&1%4aj)3ye{-tfTB4z*0ai~QpOTco zpd2U(XiQ^gWNshi7t&Sv^<` z_mCgJ{M!SQL`t+k-^kTI&pY(jPK(fbg;~d^H`{ZyE?c|ACA#q$U_K0BJFbdrjV*!f z_JU;k16RmoWTcwHLg)C?1Kk5_d5*iCOrVN~y{g{pO6#~B;72TRI4=+WYT;=S3b55! zyk2n23qIk&^w-~6XPGqK`o+(K4y;W7aMaQG|G~%+E!kIzPfSgH?c{VnQ5)o5=}89_ z$;t1f0B{2|crXsO>8LPJ@wpsR!ff>Q+dxs0PMQHEP!11|>g&09TiXJ$xhE&=id*Wc zLH}(77uT(~j{vK8tyGCTGxH^d^bEZCO4qecDvs?g9bM(lw4`4yaWkK({h60&m@`fs zZCPALS4{cd#6mm%MMv->Z#2S(C@6!&gJp^ACL^(S{#e!W@~)CUZ48uqy1Q`VqNymU zfq&sXJ6gFzK&ysq3Rxg?mQ*0F?$Pe`Rd)8+GU8=p$8s`IlH~hqle~Y-o|l^X0oTFJ z4P?F2xUe^{_zV~fc9zGLs2~y|_wnO$9RQE$V7S*a%mD9Iczc`88fY2;+hWOol=-yz z0MNHFiAdu>Lan$~JAZN!+fWXscb>o|u?OC&0oJ*G#Cjoi%x= z_pe?+dAZvB{IZ1eY)4zZO7%CxC!p@@y*MTbY?V&JM<7nO7=?i~i(3bHQ20)v4@7-) zBWr<9duA=)$$avwei7LxNA+$)PN7rLR=NO}sW#`7?e>|yn%&m3Rh2DHl86MDM1HV` zfVGPLr|+NbRBCA52n6qbC!{!{BhyBaU3%nXd7r2>^6cnpgjRMdjm5ZPs0dwQ%HmZ~XCUzETUr z3AX2Kv~FP@wEdIM@U?JToUf5dWzNii8zE>M$L-?Zp24S~1)9}doiJGmiTE<%Ai|gE z*dpFcKmmekC=bqrwmm~bLxuCM6H@jk2Xnp(rb*9-LPygKrD6OdTzUE-D~7OGXsej^Q#57=^y2} z>)v{A1fyS4NE+p5D5$CeG4&5W*H*-_)<=kVT|2uC+2667n7~O%TP>zan3zdCUxeR& z*FVV(0B7=a%ogxp%y|&e&q~CHODyT=u;poJ$SYs@%CW_naqDKL^#GL9x8>G!HId>r~kBiO15$`JYpWCbWl7vp3I!Jl`gInU_aH`5+BD0*PxA!8Hv5WZ?9qZAT zv4Y-SlS6vuD=8r|50?;?dadDKLdDPfv>ZY zciGN2?^kNU+e`LNa55*AHIW-kE1%?|g zk9BWu(O`PI^kpSE83{k1XEcPC&GRM%LY)~9&vo>qMctV65mke>wBH2fL4t=ND353K^1E-#U4V7i}?ba8_F^&DWfI& z-u)VEg&JKRa%b!l=qx`|mhN~5$u$w_@RN|W*QF#A>v1d~gO6|G1>Nc+)yfgiEPw0K!JZTlLlo3RHS*-8D5GMHrnz-B(tr&u5-8!-hQY zm}G@3^9Q^*?_E8{8u?Wswk|{9jOtUm|NE$I6eQ(Sm!U~6lGeL)PDct|Hc#6vh?+7XpP-lY$k*FkY^E* z5bI$>4`9`eU;_5<4Axq3m(2%mxwB8F9NsF)EYQwu7Sp}qvIRTE+<8V}M3vO-+;;B7 zURmT-y=~_XN$>fwoOyw4NK)gt)t%aSNmf3cMV-;owH#=Uf`ZH#y@n$Oq3Rmr8X3)G zg@uI)cXfl5s1aP_!u6ehMS&Ut)`gT>CF09hz%8%^!hEho2iwcVBwHo2P@{9Kp&ajG zcye=Nj!8v>%@XxVew@hw(+DOVg=A@DXee-X?N5A%d$CP7!m^hnMGZ9;SIQ3yhjjP# zxe*;4AMT~y&vS)Yu-jINTG(h4Z@8&%<>-1-cjqQitFJv$k~QaPGf>2vskm*^D$&o> zTqFPfoUqKPL%5*~*nHuqT{{c)Sl80)*OR<98~7@78@IO{^`6YBwg`PJ_kjCmJFD-b zN8r)42&-stIK&zTJe1S(>)RTywCJ=jwH+uCd;)(U`VqC?yiiMFuJOc1XA!aK@$d<= zI7`n4A+B zSQvW&aG+o-YSog^CfJ5*V^-zT-7^6spZ6vzqweLaRM_A3MyYp0JRZ4sRSTEz)X}K6 ztZ9+8;Hc`8c=ad-Yg*kX8Odii@bIXpT7$F2_&iz+g%PGD z3N$>{AL-kP?U~$?5|w!xDyphF%!b$VDJ13^wX$oEurLkY)l_@<1gaFbX1rq1Dt5Ag z8W~%1aM!u4UBX{38%lwm`r0IC!{et^w6u9Zem;R@b1NO(J9jb=2i&pw(=^j@-@6Zx zAb{ldCLZnxA+!BHdLy!fO-ZSji1y-6?*-~Z$Gw1iQqWcSn{)wwF(-z^bJnoWpyMdW zaiM~8SntmLnk5~GW!T8R;4Y!sF#mLT+RP0*4S$vdf#g|?dm4WEmI^sT^6y!bemky$ z$9|KO#2Y50+P!v)W(D|&@ba5dS|~kp9--N2I}a zzlO46$*+fU(yOAucJJ)!E`ah);;K&W?JSA(#a|YpU!7xIC1-L-S7|!j1xPxe;|d83 z(RmdkFF!OqZ!0D(p60QNUZkuLq441+3N$f^-7YAv^d*2;L;)PdCFA~MKdpxJAw>8< z5(b77Nr-vvG1NG}ADYDhTnTIRXTe(u7#!Zz0x2ykSr9?1;k^1uyp47R_^A>vN# ze%-or9^o%PL`uUD6$_E51Sej2xMQva^V-C%r&~aud6AsF#PH^>mFxqQN2r%em+adn z5x__|&^d;XdtH)M@@Bvm`tk&yr1~}Mip|@*Enuk+kFa7y#NKL7O3HZ-i3-S@&MhpZ zKPP2j~27!TS)ZNu1cND+73WZj)PZabhmcs^pJZ=`IyV9tV z!g9#7o8bZy(Z<}L2IoskU>a&~_ike3T=d)$e(xiBfd%0g=Le6wHXy@uCW)^lLVbr! zgSJlcYy_8hR@0*o$PgC6O$gq>lH9~*zJZxTHNctQpMz%j+nddZbn|dK$9$9=PWn!j zxwY|UzhX72A0)LuJ&n-H{qddW*oQOPgz56$YQEhSY{}pEN0Nd zCo1(uQ<_O>dJ%rS!S%)lnNcSS3 z`T&lGF?Pb7b=-N*0g@qif^45}@B3m63)6DNaW!l0m-P&dK7WQ?SwHrR!NHj(DYu(~ zntV2&x={KmrBV$D1ck&y>6K?sJb1VFW}XH*AF@o8IpeIQDLPeG%M|`pIXhd%xZx=% zkF>XJdIF^ygc&hst-d`4M^Ny&?gT)BhdFz~=rj90UF!^{yMztW zE@2&shr{Sl-&5fsUlQgeaS_YGabK++H$guaTepF_#_wVW8^iKzk0=uK+8ln3Ot}JP z%xTwIzY^U5rrPmIay$wl|q(Dg4y7!Ip;V|(|eZ0M< zdA~^R9yJsSH!@mvLl*FQFmzQf;eyQNfqTFf8?L{eh-0(5vb+kbWG7RF=H}*=qV zP+|Y%iinqVE#BC;q01I3hhP`-YX?=}vTG17b5NgwuyB25td9pvf~wKyRq!0vRzi8D zv5y&Fw`6a8Ao6V1Q&bFh7}?=*4H(HNH54&aw)}*6DaFQP@KewFn1_N42m4q=O3d^_ zQlI&y?dw3W*#sNi1;P2lp$Bbk49?g%i;-LF9=Zf~{hkvS*-n`L2&og+@$K@6@WT8Z-BH*6U;D*>hk5kEg zYnGp#{m}6`pkYWt?y#e+lzEL_x!lS`L1E;V=PW5|X#ZDF50VbMjrEjvi>x?zhq#Fm zqF~Z;tbIHH`^OTgwczzXPT&Z`Vn-~SeYTvx=H>*p+jEjxcOv=8C1Rv1J&4%bbq^lM zrlfAf>Uw$*@#u~Fz`z*7s@SE%!l>q?VUahX6UWBZCMqH#!+6`E%;E$U_Q{XYVfz5g z^tw(V+b##~J%%F@2OQGx&cp{7?rNr&iO49VA5IFay%_O<>y1_>rA^7gK*X{>*ua1& ziPrZ2$Fci5-Ow~NH1W3Gcl&bn=%zNVQhEO8r~kGk*dGH1@Js*O-?-#DtaaeESx8M! zC%qcg9ZR%&NxmNt3JK?MJoU-;`Ru7?l0V{HnT7Q`iJQayHu2I7=#$>_6BXc-2UtZe zpoaC&-G5f;iYO4jbo0Q@p^xY6VK!I{r*aP_iYo5Gou2IQ3a(~nCpR$oT~@ftNjyfH zrzn~0+1%Y*YJ5t-VZM0JrS_~G`4Eq>$tmUT%xwAC!BB@+Wd3lMhf<-sHU>HhK8pyS zruIpH0)W8lHOYB+i1#!Dp~ke^`!PSoCy0*ZPMwiKmRRdRXKP<=d8{sUj+L0Pfg1}D zFh)5!9(Io&Rad`bu(pk5G%88`mb&!q{#2!Dap_I0yq2Jl?Z$M>ZAJCP;ufsn&Q>1~ z$V=fdIy9DBpRM163Fi3I++Xk90kDm(F46n6qdiyyqSAWHGzzQ=4@%F!J%6DOntDKh z^tKvBI<*Jz!uhOJU?ThWYWu*4*I%DI+L?6u}iqn`p9h{sCwCXvSnZy3v69E;$+aC03`90+OWE5mf*Z~iO zq0k(Sdh7c@!3*5~IN%m=d*xtRfF}2!ch6XUcW=NC|F@dE|9|fD7WVh8iHV8-Rnu^i z?1g!K)V5clk`wUyU8I8r(JykT7Zv$1Dk73G=J!YqT*dB;FQZ_0x0si>m>-VBgFht_ z(ryA%bT4F4XQ2e50|h;>->=hIC=@Ct?)ROBy4&AR86pe&d$*e$NT}#EmYJ)56Bf1dH@*N__SK9`XJ;}}JE`ZlMa&(310pgjK9A0p`N?9TF#N}ocp62*b8 za%d=O78r{MTC>Fsi~e3xx4Yr%@P`$Qa0qXE=)CBO>(f+uNlXB~CHC)129y1NUGfbH z8662wpNC)%h^Baj#9NCeTD>WG+?SsI{kxZlUATr+Q7*NWmd2lN^*K7Eh%t-`xaeGe z_-Uxk$3w&5?I3}8CH9axdU3I@m5daSXhpt;H-D1-dl^r2vMCLto@bB=ekW^di-=e$ z?-(W!_Wj#k diff --git a/scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg b/scripts/tutorials/expansion/ur5_pick_place/assets/replay-before.jpg deleted file mode 100644 index 23a691750086af80675efcc58bdca99e794b85d6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 131978 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