Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions agent_context/MAP.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ topics:
keywords: [BaseEnv, EmbodiedEnv, EpisodeContext, EnvCfg, ControlTiming, resolve_control_timing, register_env, list-task, run-task, run-example, target_control_frequency,
sim_steps_per_control, step_dt, environment.component, embodiment.component, file-owned physics backend,
physics_config, ControllerAction, EnvProfiler, startup_summary, dexsim_startup_info,
FluidReplayEnv, fluid Gym, 流体 Gym, ExpertTrajectoryCfg, joint_command_mode, position_velocity, qpos qvel, expert action schema, ObservationHistorySnapshot, ObservationFrame,
fluid Gym, 流体 Gym, fluid replay, 粒子回放, ExpertTrajectoryCfg, joint_command_mode, position_velocity, qpos qvel, expert action schema, ObservationHistorySnapshot, ObservationFrame,
task_instruction, resolve_demo_instruction,
show-task, task catalog, task gallery, 任务画廊, physical_objective, 物理目标, RLTaskCfg, rl_task]
paths: [topics/env-framework/env-framework.md]
Expand All @@ -79,14 +79,14 @@ topics:
- embodichain/lab/gym/envs/embodied_env.py
- embodichain/lab/gym/envs/episode_context.py
- embodichain/lab/gym/envs/expert_trajectory.py
- embodichain/lab/gym/envs/fluid_replay.py
- embodichain/lab/gym/envs/_fluid_trajectory.py
- embodichain/lab/scripts/run_fluid_task_program.py
- embodichain/lab/gym/utils/trajectory_state.py
- embodichain/lab/gym/envs/managers/observation_types.py
- embodichain/lab/gym/envs/demo.py
- embodichain/lab/gym/utils/profiler.py
watch_paths: [embodichain/lab/gym/envs/managers/observation_types.py, embodichain/lab/gym/envs/episode_context.py, embodichain/lab/gym/envs/base_env.py, embodichain/lab/gym/envs/embodied_env.py, embodichain/lab/gym/envs/expert_trajectory.py,
embodichain/lab/gym/envs/demo.py, embodichain/lab/gym/envs/fluid_replay.py,
embodichain/lab/gym/envs/demo.py, embodichain/lab/gym/envs/_fluid_trajectory.py,
embodichain/lab/scripts/run_fluid_task_program.py, embodichain/lab/gym/utils/, embodichain/lab/gym/envs/task_program/, embodichain/cli/, embodichain/lab/scripts/run_task.py,
extensions/embodichain_tasks/, tests/gym/envs/, embodichain/lab/gym/envs/objectives/,
embodichain/lab/scripts/evaluate_task_objective.py, tests/lab/scripts/test_evaluate_task_objective.py]
Expand Down
4 changes: 4 additions & 0 deletions agent_context/topics/env-framework/execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,10 @@ not orchestrate multiple experiments or qualify kinematic playback.
accepted. Objective-enabled dynamic replay requires one row and a full reset.
`control` exposes `go_to_step(step)` for O(1) scrubbing. The replay env must
use the same robot/objects/`actions` config as the recording env.
Qualified fluid recordings carry bounded particle-state sidecars. Kinematic
and control replay restore complete particle states at each recorded boundary;
dynamic replay restores only the initial particle state and recomputes later
fluid motion from recorded actions.
- **Policy projection**: `rollout_buffer` retains actual policy observations,
including sampled noise, and its existing obs/action/reward alignment for
LeRobot/RL. It shares the acquisition boundary with raw history, rather than
Expand Down
12 changes: 8 additions & 4 deletions agent_context/topics/env-framework/fluid-replay.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,14 @@ assurance alone does not prove grasp or pouring success. Optional trajectory
recording stores measured online state for inspection. `--seconds` qualifies
only a bounded fragment, not completion of the task.

`FluidReplayEnv` remains an explicit diagnostic utility for accepted historical
recordings; it is not the default deployment or task runner. It requires a
separate kinematic configuration, one Newton substep and fixed-root source
states, and rejects action managers and policy dataset/trajectory recording.
Accepted Task Program recordings can opt into control-aligned full particle-state
sidecars with `--record-trajectory --record-fluid-state`. Each source row has a
bounded, content-verified chunk manifest. Particle positions are arena-local in
the artifact and converted to the target arena on replay. The ordinary
`ReplayWrapper` restores particles along with rigid states in `kinematic` and
`control`; `dynamic` restores only the initial particle frame, then replays
recorded controls through DexUni. Fluid replay requires qualified sidecars and
does not infer fluid state from the scene's initial fill.

## Rendering and recording

Expand Down
280 changes: 280 additions & 0 deletions embodichain/lab/gym/envs/_fluid_trajectory.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
# ----------------------------------------------------------------------------
# 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, control-aligned fluid states for Gym trajectory replay."""

from __future__ import annotations

from collections.abc import Mapping, Sequence
from pathlib import Path
import shutil
from uuid import uuid4

import numpy as np
import torch

from embodichain.data_pipeline.recording.media import (
MediaFrameReader,
MediaSpool,
verify_media_manifest,
)

__all__: list[str] = []

_MAX_BUFFER_BYTES = 32 * 1024 * 1024


class FluidTrajectoryRecorder:
"""Spool one full particle-state frame per recorded control boundary."""

def __init__(self, directory: Path, num_envs: int, step_dt: float) -> None:
self.directory = directory / f"fluid-state-{uuid4().hex}"
self.num_envs = num_envs
self.step_dt = step_dt
self._spools: list[MediaSpool | None] = [None] * num_envs
self._parent_ids = [str(uuid4()) for _ in range(num_envs)]
self._counts = [0] * num_envs
self._published = False
self._committed = False

def capture(
self, env: object, env_ids: Sequence[int], *, reset: bool = False
) -> None:
"""Capture selected rows, including the reset frame when requested."""
ids = tuple(int(index) for index in env_ids)
if not ids:
return
if reset:
for index in ids:
if self._spools[index] is not None:
shutil.rmtree(self._spools[index].directory)
self._spools[index] = None
self._parent_ids[index] = str(uuid4())
self._counts[index] = 0
elif any(self._spools[index] is None for index in ids):
raise RuntimeError("Fluid trajectory has no initial control frame.")
offsets = env.sim.arena_offsets.detach().cpu().numpy()
frames = {}
for uid in sorted(fluid.uid for fluid in env.cfg.fluid_object):
state = env.sim.get_fluid_object(uid).data.particle_state_w
if state.dtype != torch.float32 or state.ndim != 3 or state.shape[-1] != 6:
raise ValueError("Recorded fluid state must be float32 (E, N, 6).")
values = state.detach().cpu().numpy()
if not np.isfinite(values).all():
raise ValueError("Recorded fluid state must be finite.")
frames[uid] = values
for index in ids:
if self._spools[index] is None:
self._spools[index] = MediaSpool(
self.directory / f"env_{index:03d}",
max_buffer_bytes=_MAX_BUFFER_BYTES,
parent_episode_id=self._parent_ids[index],
calibration={"coordinate_frame": "arena_local", "channels": 6},
)
row = {}
for uid, values in frames.items():
local = values[index].copy()
local[:, :3] -= offsets[index]
row[uid] = local
self._spools[index].append(self._counts[index] * self.step_dt, row)
self._counts[index] += 1

def finish(self, trajectory_path: Path, lengths: Sequence[int]) -> dict:
"""Publish verified sidecars before the trajectory references them."""
if self._published:
raise RuntimeError("Fluid trajectory was already published.")
if len(lengths) != self.num_envs:
raise ValueError("Fluid trajectory row count differs from source.")
manifests = []
for index, (spool, length) in enumerate(zip(self._spools, lengths)):
if spool is None or self._counts[index] != int(length) + 1:
raise ValueError("Fluid frames do not align with trajectory lengths.")
path = spool.finish()
verify_media_manifest(
path,
expected_frames=self._counts[index],
parent_episode_id=self._parent_ids[index],
expected_timestamps=np.arange(self._counts[index]) * self.step_dt,
)
manifests.append(str(path.relative_to(trajectory_path.parent)))
self._published = True
return {
"schema_version": 1,
"coordinate_frame": "arena_local",
"manifests": manifests,
"parent_ids": list(self._parent_ids),
}

def commit(self) -> None:
"""Retain sidecars after their referring trajectory is durable."""
if not self._published:
raise RuntimeError("Fluid sidecars must be finalized before commit.")
self._committed = True

def abort(self) -> None:
"""Discard uncommitted particle chunks after failure or interruption."""
if not self._committed:
shutil.rmtree(self.directory, ignore_errors=True)


class FluidTrajectoryReader:
"""Validate and stream selected fluid frames from a qualified trajectory."""

def __init__(self, path: str | Path, trajectory: Mapping, cfg: object) -> None:
self.path = Path(path).resolve()
meta = trajectory["meta"]
qualification = meta.get("fluid_qualification")
if (
meta.get("artifact_purpose") != "recording"
or not isinstance(qualification, Mapping)
or qualification.get("kind") != "task_program"
or qualification.get("accepted") is not True
):
raise ValueError(
"Fluid replay requires an accepted Task Program recording."
)
episodes = meta.get("demo_episodes", [])
source_envs = int(meta["num_envs"])
if len(episodes) != source_envs or not episodes:
raise ValueError("Fluid replay source episodes do not match recorded rows.")
program_hash = qualification.get("program_hash")
if (
not isinstance(program_hash, str)
or not program_hash
or any(
episode.get("program_hash") != program_hash
or episode.get("completed") is not True
or episode.get("success") is not True
for episode in episodes
)
):
raise ValueError("Fluid replay program provenance differs from the source.")
target_envs = int(cfg.num_envs)
if source_envs not in (1, target_envs):
raise ValueError(
"Fluid replay source must match env count or contain one row."
)
sidecar = meta.get("fluid_state")
if (
not isinstance(sidecar, Mapping)
or sidecar.get("schema_version") != 1
or sidecar.get("coordinate_frame") != "arena_local"
):
raise ValueError("Fluid replay requires aligned particle-state sidecars.")
paths = sidecar.get("manifests")
parent_ids = sidecar.get("parent_ids")
if not isinstance(paths, list) or not isinstance(parent_ids, list):
raise ValueError("Fluid replay sidecar manifest is malformed.")
if len(paths) != source_envs or len(parent_ids) != source_envs:
raise ValueError("Fluid replay sidecar rows do not match the trajectory.")
self._uids = tuple(sorted(fluid.uid for fluid in cfg.fluid_object))
if not self._uids:
raise ValueError("Fluid replay requires configured fluid objects.")
expected_counts = {
fluid.uid: int(fluid.spawn.sample(fluid.particle_spacing).shape[0])
for fluid in cfg.fluid_object
}
self._readers = []
try:
for index, (name, parent_id) in enumerate(zip(paths, parent_ids)):
if (
not isinstance(name, str)
or not name
or not isinstance(parent_id, str)
or not parent_id
):
raise ValueError(
"Fluid replay manifest paths and IDs must be strings."
)
relative = Path(name)
if relative.is_absolute() or ".." in relative.parts:
raise ValueError(
"Fluid replay manifest escapes its artifact directory."
)
candidate = self.path.parent / relative
if any(
part.is_symlink()
for part in (candidate, *candidate.parents)
if part.is_relative_to(self.path.parent)
):
raise ValueError("Fluid replay manifest cannot use symlinks.")
manifest_path = candidate.resolve()
if not manifest_path.is_relative_to(self.path.parent):
raise ValueError(
"Fluid replay manifest escapes its artifact directory."
)
count = int(meta["lengths"][index]) + 1
declared = verify_media_manifest(
manifest_path,
expected_frames=count,
parent_episode_id=parent_id,
expected_timestamps=np.arange(count) * float(meta["dt"]),
)
if declared.get("calibration") != {
"coordinate_frame": "arena_local",
"channels": 6,
}:
raise ValueError("Fluid replay particle frame convention differs.")
if tuple(sorted(declared["features"])) != self._uids:
raise ValueError(
"Fluid replay particle UIDs differ from the scene."
)
for uid, schema in declared["features"].items():
if (
len(schema["shape"]) != 2
or schema["shape"][0] != expected_counts[uid]
or schema["shape"][1] != 6
or np.dtype(schema["dtype"]) != np.dtype("float32")
):
raise ValueError("Fluid replay requires float32 (N, 6) frames.")
self._readers.append(MediaFrameReader(manifest_path))
except Exception:
self.close()
raise
self._source_envs = source_envs
self._target_envs = target_envs

def apply(self, env: object, steps: torch.Tensor) -> None:
"""Write selected control-boundary frames without advancing physics."""
if tuple(steps.shape) != (self._target_envs,):
raise ValueError("Fluid replay step indices do not match target rows.")
indices = [int(value) for value in steps.detach().cpu().tolist()]
offsets = env.sim.arena_offsets
selected: dict[tuple[int, int], dict[str, np.ndarray]] = {}
for row, step in enumerate(indices):
source = 0 if self._source_envs == 1 else row
key = source, step
if key not in selected:
_, selected[key] = self._readers[source].read(step)
for uid in self._uids:
fluid = env.sim.get_fluid_object(uid)
values = []
for row, step in enumerate(indices):
source = 0 if self._source_envs == 1 else row
state = selected[source, step][uid]
if (
state.shape != (fluid.num_particles, 6)
or not np.isfinite(state).all()
):
raise ValueError("Fluid replay particle count or state is invalid.")
values.append(state)
world = torch.as_tensor(np.stack(values), device=env.device).clone()
world[:, :, :3] += offsets[:, None, :]
fluid.write_particle_state_to_sim(world)

def close(self) -> None:
for reader in getattr(self, "_readers", ()):
reader.close()
Loading