Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
98 commits
Select commit Hold shift + click to select a range
75d3c9a
feat(sim): default Newton rigid simulation to MJVBD V2
Sep 17, 2026
731a20d
fix(sim): tune MJVBD V2 manipulation examples and record limitations
Sep 18, 2026
51af322
fix(tutorial): align drawer damping across physics backends
Sep 20, 2026
bc5369b
docs(sim): clarify MJVBD V2 coupling and control limitations
Sep 20, 2026
5f19889
fix(sim): adapt examples to DexUni solver config
yuecideng Sep 29, 2026
1e9d5f9
Merge remote-tracking branch 'origin/main' into codex/dexuni-interfac…
yuecideng Sep 29, 2026
347ce76
fix(sim): unify Newton solver adaptation on DexUni
yuecideng Sep 29, 2026
aa9f0b6
feat(sim): expose DexUni contact sensor data
yuecideng Sep 29, 2026
1832e56
test(sim): cross-check DexUni contact impulses
yuecideng Sep 29, 2026
c763aad
test(sim): assert DexUni contact invariants
yuecideng Sep 29, 2026
32e08fc
Merge remote-tracking branch 'origin/main' into codex/dexuni-interfac…
yuecideng Oct 3, 2026
7049fcf
fix(sim): update DexUni migration validation
yuecideng Oct 3, 2026
a09bd7e
docs(sim): use DexUni terminology consistently
yuecideng Oct 3, 2026
ad9ba87
wip
yuecideng Oct 4, 2026
b589354
Merge latest main into DexUni interface adaptation
yuecideng Oct 10, 2026
9428020
feat(physics): support current DexUni two-way coupling contracts
yuecideng Oct 10, 2026
41806cd
feat(demo): add Franka volume-map DFSPH pouring demo
kioxli Oct 13, 2026
40f73d8
feat(sim): integrate fixed-count fluids through public scene APIs
yuecideng Oct 13, 2026
c0be5af
feat(gym): replay qualified Task Program trajectories with live fluids
yuecideng Oct 13, 2026
952575b
docs(fluid): record Gym qualification and finalize API entries
yuecideng Oct 13, 2026
d5b93bc
feat(gym): record fluid replay camera views per environment
yuecideng Oct 14, 2026
fa3db6a
feat(sim): generate fluid fills from local volume profiles
yuecideng Oct 14, 2026
fc3f1ba
fix(fluid): render visible water in recorded Gym views
yuecideng Oct 14, 2026
d720fe6
fix(sim): enforce fluid gate for Hybrid process renderers
yuecideng Oct 14, 2026
f1e9e90
Merge main into fluid integration and adapt the pouring demo
yuecideng Oct 14, 2026
d6c7b39
feat(data): host pouring task assets on Hugging Face
yuecideng Oct 14, 2026
26507e1
chore(pr): remove development notes and obsolete asset documentation
yuecideng Oct 14, 2026
0dd4d16
fix(fluid): preserve cleanup and selected replay state
yuecideng Oct 14, 2026
7c17d77
feat(fluid): solve pouring demos and Task Program online
yuecideng Oct 14, 2026
899f912
fix(fluid): clear DFSPH warm start after explicit state writes
kioxli Oct 15, 2026
6533337
feat(fluid): prototype DexUni + DFSPH pouring path
kioxli Oct 15, 2026
59b866e
feat(fluid): solve the DexUni pouring prototype with MuJoCo and DFSPH…
kioxli Oct 16, 2026
6e60b8e
fix(dexsim): adapt latest 0.5.1 runtime contracts
yuecideng Oct 20, 2026
794bbb9
feat(dexsim): consolidate two-way coupling adaptation from PR #720
yuecideng Oct 21, 2026
e8a6419
fix(dexsim): reconcile current particle material and task contracts
yuecideng Oct 21, 2026
eb6b9aa
refactor(fluid): separate rc1 foundation from pouring tasks
yuecideng Oct 22, 2026
b325d5c
refactor(fluid): move pouring tasks onto the prototype layer
yuecideng Oct 22, 2026
9655ab0
chore(fluid): sync foundation with main
yuecideng Oct 22, 2026
697afb4
fix(fluid): address material, solver and lifecycle review findings
yuecideng Oct 22, 2026
848ca61
refactor(fluid): separate construction from source resolution
yuecideng Oct 22, 2026
c24a6fd
perf(fluid): vectorize render clipping across particle ranges
yuecideng Oct 22, 2026
b8922a0
Merge latest main into DexSim adaptation
yuecideng Oct 27, 2026
57d0262
fix(dexsim): follow current DexUni dispatch and device defaults
yuecideng Oct 27, 2026
1eef398
feat(sim): expose DexSim controls and deformable initialization
Oct 27, 2026
9a2d016
fix(sim): preserve continuous URDF joint limits for DexUni
yuecideng Oct 27, 2026
b440c56
Merge DexSim adaptation and enable multi-world fluid tutorial
yuecideng Oct 27, 2026
cddb815
feat(tutorial): render fluid mesh surface by default
yuecideng Oct 27, 2026
a48f07c
fix(examples): complete DexUni workflows and physical placement checks
yuecideng Oct 27, 2026
f9f128d
Merge main be57e1b97 into DexUni adaptation
yuecideng Oct 27, 2026
0835fc9
refactor(fluid): route DFSPH through DexUni
yuecideng Oct 27, 2026
4d72509
fix(examples): preserve placement asset frames across renderers
yuecideng Oct 27, 2026
c224a59
perf(tutorial): use static fluid container
yuecideng Oct 27, 2026
2706dfd
feat(fluid): adapt pouring tasks to DexUni foundation
yuecideng Oct 28, 2026
8e88cd0
perf(task): shorten fluid pouring trajectory
yuecideng Oct 28, 2026
4a7be27
refactor(fluid): keep DexUni pouring demo
yuecideng Oct 28, 2026
bb6bab7
fix(fluid): keep neighboring pours out of camera view
yuecideng Oct 28, 2026
2b5a4ee
revert: restore fluid task environment spacing
yuecideng Oct 28, 2026
da67a3e
Merge main into codex/adapt-latest-dexsim
yuecideng Nov 2, 2026
37085da
Merge main and adapt DexSim 0.6 contact reports
yuecideng Nov 7, 2026
731427f
refactor(sim): narrow Newton articulation root options
yuecideng Nov 7, 2026
834f88d
refactor(sim): remove legacy AutoSolver compatibility
yuecideng Nov 7, 2026
a6c3693
docs(sim): standardize native DexUni automatic dispatch
yuecideng Nov 7, 2026
f249fbe
update dexsim version
yuecideng Nov 7, 2026
8f792d0
Merge branch 'main' into codex/adapt-latest-dexsim
yuecideng Nov 7, 2026
28f8b6a
fix(sensors): honor native contact sampling boundaries
yuecideng Nov 7, 2026
3aafa0c
Merge latest main into codex/adapt-latest-dexsim
yuecideng Nov 9, 2026
feee146
chore(fluid): merge latest main through DexSim base
yuecideng Nov 9, 2026
afe3e06
fix: validate placement frames, mesh indices and deployment fixtures
yuecideng Nov 9, 2026
43fad08
fix(sim): reject direct standalone SPH solver configs
yuecideng Nov 9, 2026
c1af874
fix(docker): align rc1 runtime guidance and pinned installer fallback
yuecideng Nov 9, 2026
cb28664
chore(fluid): merge DexUni foundation into pouring tasks
yuecideng Nov 9, 2026
e14fc4e
Add basic fluid simulation and standalone tutorial (#777)
yuecideng Nov 9, 2026
722189a
docs: record rc1 wheel and container dependency qualification
yuecideng Nov 9, 2026
f5c55ff
chore(fluid): sync pouring PR with updated target
yuecideng Nov 9, 2026
c6e991c
Merge concurrent fluid update and retain rc1 qualification
yuecideng Nov 9, 2026
419d0ba
chore(fluid): include latest target documentation
yuecideng Nov 9, 2026
42e5e6a
chore(fluid): merge latest main into pouring PR
yuecideng Nov 10, 2026
4d15a11
chore(fluid): sync main and refresh pouring preview deployment
yuecideng Nov 11, 2026
65d32b0
chore(task): halve fluid pour control steps
yuecideng Nov 11, 2026
16d7234
chore(task): halve fluid pouring simulation time
yuecideng Nov 11, 2026
7f7673b
feat(pour): support slower tilt and return timing
yuecideng Nov 11, 2026
e954b64
chore(fluid): merge latest main with slower pour
yuecideng Nov 11, 2026
5a55274
Honor fluid pour rotation duration during motion
yuecideng Nov 11, 2026
65e437d
Unify fluid trajectory replay with Gym modes
yuecideng Nov 11, 2026
24ddaaf
Merge latest origin/main into fluid prototype
yuecideng Nov 11, 2026
07af65f
Use prepared DexUni fluid for world capability checks
yuecideng Nov 11, 2026
511d641
Remove legacy pour variants and relocate DexUni demo
yuecideng Nov 11, 2026
bc2618e
Scope fluid recorder to one published trajectory
yuecideng Nov 11, 2026
4e798e4
Merge current PR790 and remove legacy pour variants
yuecideng Nov 11, 2026
dd1a1f2
Merge latest fluid recorder changes into pour cleanup
yuecideng Nov 11, 2026
7d3d9f5
Remove residual standalone SPH solver usage
yuecideng Nov 11, 2026
cf71962
Merge latest main while retaining DexUni-only fluids
yuecideng Nov 11, 2026
e8028a1
Consolidate standalone SPH rejection at solver normalization
yuecideng Nov 11, 2026
fab037d
refactor(fluid): collect qualified replay through run-task
yuecideng Nov 11, 2026
1315f44
fix(fluid): simplify pouring integration and preserve replay timing
yuecideng Nov 12, 2026
006f27b
refactor(gym): consolidate fluid recording and qualification
yuecideng Nov 12, 2026
ae90b79
refactor(tasks): remove empty-cup pouring deployment
yuecideng Nov 12, 2026
614ca2e
Merge origin/main into fluid pouring branch
yuecideng Nov 12, 2026
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 @@ -15,7 +15,7 @@ topics:
UsdSourceSnapshot, read_usd_source, LinkMesh,
PhysicalCollisionGeometry, capture_physical_collision_geometry,
ArticulationJointKinematics, get_parent_joint_chain, asset_physics_mode, joint_drive_props, enable_gravity,
fixed-cadence playback, FluidObjectCfg, FluidSpawnCfg, FluidObject, SPHSolverCfg, revolved_volume, fill_level,
fixed-cadence playback, FluidObjectCfg, FluidSpawnCfg, FluidObject, sph_cfg, DFSPH, revolved_volume, fill_level,
粒子采样, fluid, 流体, quaternion, xyzw, cable, CableObject, CableObjectCfg,
CableObjectData, 线缆对象]
paths: [topics/simulation-system/simulation-system.md]
Expand Down Expand Up @@ -55,7 +55,7 @@ topics:
keywords: [UnitreeG1MotionRL-v1, motion_tracking, 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,
ExpertTrajectoryCfg, joint_command_mode, position_velocity, qpos qvel, expert action schema, ObservationHistorySnapshot, ObservationFrame,
fluid Gym, 流体 Gym, fluid replay, 粒子回放, DemoQualification, ObjectMotionMetrics, ExpertTrajectoryCfg, joint_command_mode, position_velocity, qpos qvel, expert action schema, ObservationHistorySnapshot, ObservationFrame,
EvaluationSpec, RuleSession, evaluate_recorded_rules,
task_instruction, resolve_demo_instruction,
show-task, task catalog, task gallery, 任务画廊, physical_objective, 物理目标, RLTaskCfg, rl_task]
Expand Down Expand Up @@ -595,7 +595,7 @@ topics:
title: Data Assets
aliases: [data assets, data path, asset download, 数据资产, 资产下载, 数据路径]
keywords: [get_data_path, get_data_class, _resolve_data_reference, EmbodiChainDataset, TabletopFourBases, Real2SimCarton, Real2SimCartonV1, demo assets, EMBODICHAIN_DATA_ROOT, EMBODICHAIN_DATASET_ROOT,
CATEGORY_MODULES, embodichain.assets, ROBOT_ASSETS, 资产注册, download lock, get_registry, DefaultMaterials, list_default_materials, get_default_material_info]
CATEGORY_MODULES, embodichain.assets, ROBOT_ASSETS, 资产注册, download lock, get_registry, DefaultMaterials, list_default_materials, get_default_material_info, task_assets, PourCupAssets, PourCupDemoData]
paths: [topics/data-assets/data-assets.md]
source_of_truth:
- embodichain/data/dataset.py
Expand Down
11 changes: 7 additions & 4 deletions agent_context/topics/atomic-actions/atomic-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,10 +144,13 @@ fixed-centre target. Neither option establishes path or physical feasibility.
opening and source-mouth geometry. The action derives the tilt direction,
source-body clearance and mouth-compensated approach/tilt/return path from the
held transform. Omission retains the original local-axis rotation mode.
Geometry belongs to the goal/integration; motion timing, IK and collision
checks remain with the selected planning policy. Validate executed mouth
alignment and height throughout tilted motion with host observations, rather
than treating an accepted final pose as evidence of pouring.
Geometry belongs to the goal/integration. `PourOptions.rotation_duration`
optionally sets a minimum simulated duration for each tilt and return leg on
the control grid. The local-axis mode stretches each row's native segment timing
before control-grid resampling and batch padding; strategy, control period,
joint motion limits, IK and collision checks remain with the selected planning policy. Validate
executed mouth alignment and height throughout tilted motion with host
observations, rather than treating an accepted final pose as evidence of pouring.

ExecuteDemoSkill executes task-specific demonstration assets with measured runtime
contracts through the same nominal-source and runner interfaces. Its internal
Expand Down
4 changes: 4 additions & 0 deletions agent_context/topics/data-assets/data-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,10 @@ Keep the lock outside the directory repair may delete. POSIX uses `flock`;
Windows uses a polled byte lock. Direct Open3D subclasses do not automatically
receive the project's locking/repair behavior.

The `task` category registers `PourCupAssets` runtime meshes and
`PourCupDemoData` historical recordings through `assets/task_assets.py`.
Both use the shared download cache and class-prefixed paths.

The CLI honors an asset class's optional `cache_prefix` when checking readiness
and ensuring extraction; otherwise the class name is the cache entry.
The shared registry merges core category modules and `embodichain.assets`
Expand Down
4 changes: 3 additions & 1 deletion agent_context/topics/env-framework/env-framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,14 @@ Lightweight RL environments have a separate owner in
| Raw schema, optional history and exact historical queries | `managers/observation_manager.py`; Env dispatches capture/reset/close boundaries |
| Optional measured physical objectives | `embodichain/lab/gym/envs/objectives/`; Gym owns observation/reset hooks independently of expert acceptance |
| Controller-ready commands | `embodichain/lab/gym/envs/types.py`: `ControllerAction` |
| Demo segment execution / outcomes | `embodichain/lab/gym/envs/demo.py` |
| Demo segment execution / outcomes / collection qualification | `embodichain/lab/gym/envs/demo.py` |
| Configured Task Program registration | `embodichain/lab/gym/envs/task_program/registration.py` |
| Timing instrumentation | `embodichain/lab/gym/utils/profiler.py` |

Read [configuration and registration](configuration.md) for task-first layout,
component ownership, path resolution, config-owned IDs, and task listing.
Read [fluid Gym integration](fluid-replay.md) for online Task Program execution
with DexUni rigid/DFSPH dynamics, fluid configuration and coordinate conventions.
Read [execution](execution.md) for hooks, bridge acceptance, reset ordering,
wrappers, and replay. Read [profiling](profiling.md) only for instrumentation.

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 @@ -331,6 +331,10 @@ not orchestrate multiple experiments or qualify kinematic playback.
Use `evaluate_recorded_rules` to evaluate a compiled graph directly from a
trusted trajectory in bounded chunks. It can use a recorded segment
occurrence to select the matching control slots and acquisition revisions.
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
80 changes: 80 additions & 0 deletions agent_context/topics/env-framework/fluid-replay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Fluid Gym integration

`EmbodiedEnvCfg.fluid_object` owns fixed-count fluid declarations. Physical
components own these alongside rigid entities; `config_to_cfg()` resolves
fluid point files and explicit relative rigid/visual mesh paths against the
owning component. Spawn rigid references are resolved before fluid binding.
The default pour deployment generates its fill from a local revolved profile;
no particle asset file is required. Pouring meshes use `PourCupAssets/...`
references resolved through the [data asset cache](../data-assets/data-assets.md),
so installed task packages carry configuration without mesh payloads. The configuration helper `gym_utils.configure_fluid_spacing` resamples the
same volume recipe and rejects fixed point imports. It scales explicit render
radius, mesh cell size and reconstruction kernel radius by the spacing ratio,
keeping the surface reconstruction consistent with the new particle density. Fill definitions and
in-memory template ownership are documented under
[simulation fluids](../simulation-system/fluids.md).

`managers/observations.py` provides particle state, summary and volume-in-region
observations. Particle arrays are world-frame; rigid `get_local_pose()` is
arena-local. Region measurement and `events.reset_fluid_in_container()` add
arena offsets before comparing or placing particles. Region volume is particle
count times nominal spacing cubed, not a reconstructed-surface measurement.

## Online Task Program workflow

`run-task` runs the configured pour-cup deployment through ordinary `EmbodiedEnv`
and `execute_demo_episode()`. The environment
component selects DexUni with DFSPH settings nested under `sph_cfg`. Robot
drive targets, dynamic grasp contacts and fluid state
advance in one World, with no recorded trajectory input. DexUni's fluid component reads live rigid
boundaries; fluid reaction forces are not fed back into the rigid solver.
The fluid program measures cup lift and alignment, transports the held cup
to a receiver-relative pour pose through the existing MoveHeldObject lowerer,
then pours and returns it. The standalone Sim example uses the same physical
component and relative pour target with freshly planned Atomic Action targets.

Program completion and physical qualification are separate. The deployment's
`collection.qualification` declares generic `object_motion` bounds and named
numeric observation bounds. `demo.DemoQualification` tracks motion extrema on
the input device without storing every pose; stateless env-only raw observation functions
are sampled without policy inputs, projection or noise. `when: always` bounds apply at every
sampled boundary, while default `final` bounds apply to the last sample. The
collector combines measured truth with episode completion before commit.
Rejected attempts retain `qualification_result.json` diagnostics and video.
Projected effect assurance alone does not prove grasp or pouring success.

Accepted Task Program recordings can opt into control-aligned full particle-state
sidecars with `run-task --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. The adapters in `gym/utils/trajectory_state.py` validate particle data and frame
alignment independently of task policy. `run-task` checks accepted Task Program
provenance before creating a World. Replay does not infer fluid state from the
scene's initial fill.

## Rendering and recording

The pouring environment selects `fast-rt`. Hybrid is rejected for
native fluid rendering: OptiX-only liquid geometry is absent from its Vulkan
primary surface. Particle-state and video-decode checks alone do not qualify
liquid visibility; use the image-based fluid regression linked below. The
default record view focuses on the cup and receiver; the mesh kernel radius
is 1.5 times the particle spacing to retain a connected surface after settling.
Its interval `record_camera` event uses the existing `record_camera_data`
functor with `fps=None`, recording independent environment views at the
control frequency. `run-task` redirects the output directory and sets the
recording limit to the resolved environment count. Accepted episodes commit
through the ordinary reset boundary; rejected attempts use the recorder's
diagnostic purpose. Explicit NoRender selection removes the camera event before
environment construction.
Selected-row recording and camera consumption are owned by the
[recording functor](../manager-functor/manager-functor.md#camera-recording).

Production configuration/measurement checks are in
`tests/gym/envs/test_fluid_integration.py`; live isolation checks are in
`tests/sim/objects/test_fluid_batch_runtime.py` and
`tests/sim/objects/test_fluid_online_runtime.py`; actual primary-surface visibility
is checked by `tests/sim/objects/test_fluid_visibility.py`. Generated trajectories/videos
are local qualification evidence, not packaged task assets.
17 changes: 17 additions & 0 deletions agent_context/topics/manager-functor/manager-functor.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
| Observation manager + built-in functors | `managers/observation_manager.py`, `managers/observations.py` |
| Reward manager + built-in functors | `managers/reward_manager.py`, `managers/rewards.py` |
| Event manager + built-in functors | `managers/event_manager.py`, `managers/events.py` |
| Episode camera recording events | `managers/record.py` |
| Action manager + built-in terms | `managers/action_manager.py`, `managers/actions.py` |
| RL termination manager + condition functors | `managers/termination_manager.py`, `managers/conditions.py` |
| Dataset manager + built-in recorders | `managers/dataset_manager.py`, `managers/datasets.py`, `managers/async_datasets.py` |
Expand Down Expand Up @@ -177,6 +178,22 @@ Event and observation calls have per-functor profiling through
`ManagerBase._call_functor()`; reward/action/dataset calls do not yet use that
helper. See [profiling](../env-framework/profiling.md).

### Camera recording

`record_camera_data` is an interval event, independent of policy dataset
recording. It renders its camera group before reading the buffers because
interval events precede observation rendering. Views use arena-relative camera
extrinsics. It retains separate owned CPU frames and episode counters per row.
It captures only the event's selected `env_ids` within `max_env_num`, preserving
their original arena IDs; `None` captures all views within that limit. Selected
save/discard only touches those rows. `fps=None` follows control frequency for
an every-step recording event; an explicit fps fixes the output cadence.

Reset commits or discards frames via `save_and_clear` / `discard_and_clear`.
Close discards uncommitted frames, so a host ending without reset must explicitly
commit its last episode. Source and regression tests live in `record.py` and
`tests/gym/envs/managers/test_record.py`.

## Change sites and validation

Change the selected manager's dispatch for scheduling changes; change its
Expand Down
45 changes: 37 additions & 8 deletions agent_context/topics/simulation-system/fluids.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

`cfg/fluid.py` owns source, object and render configuration. Fluids use DexUni,
which dispatches DFSPH when the scene contains fluid particles. Optional
numerical settings belong to DexSim `SPHSolverCfg`, nested under
`NewtonPhysicsCfg.solver_cfg.sph_cfg`; omitting them uses native DFSPH defaults.
numerical settings belong only under DexUni's
`NewtonPhysicsCfg.solver_cfg.sph_cfg`; DexSim materializes it inside DexUni.
There is no standalone fluid solver selection.
`SimulationManager.add_fluid_object()` declares through SpawnScene and binds
`objects/fluid.py` in place at `prepare()`.

The fluid declaration owns density and spacing. Default native SPH values for
The fluid declaration owns density and spacing. Default nested DFSPH values for
`rest_density` and `particle_diameter` are placeholders, equally for mappings
and native config objects; non-default solver values must match the fluid.
DexSim derives the effective solver values from the fluid descriptors.
Expand All @@ -16,9 +17,10 @@ DexSim derives the effective solver values from the fluid descriptors.

Fluid simulation requires Newton CUDA, a DexSim build exposing
`DexUniSolverCfg.sph_cfg`, no gradients and fixed particle topology.
Multiple environments require a DexSim SPH solver that explicitly advertises
both world isolation and selected-world reset; arena spacing alone does not
establish isolation. The repository's pinned `dexsim_engine==0.6.0rc1` build
Multiple environments require DexUni's prepared internal fluid solver to
advertise both world isolation and selected-world reset; the check runs after
scene preparation and before the first physical step. Arena spacing alone does
not establish isolation. The repository's pinned `dexsim_engine==0.6.0rc1` build
provides the DexUni/DFSPH composition and both multi-world capabilities.

The current native DexUni/DFSPH implementation is a prototype: DFSPH follows
Expand All @@ -35,7 +37,7 @@ Writes use Scene particle batches, invalidate captured graphs and reset
supported solver history. The legacy single-world solver rebaselines optional
SDF boundary pose history. Reset restores the immutable initial state or
transforms a saved local template without stepping the world. Explicit state
writes do not refresh density diagnostics until the next SPH step.
writes do not refresh density diagnostics until the next DexUni fluid step.

A spawn reference resolves a declared rigid body's initial pose once; it is
not a persistent attachment. Sources include explicit points/NPZ, primitives,
Expand Down Expand Up @@ -70,7 +72,7 @@ follow the renderer requirements of the [material system](materials.md).

`scripts/tutorials/sim/create_fluid.py` demonstrates procedural box sampling,
five primitive container walls, prepare, step, state reads and reset. Pass
`--num-envs` to use multiple independent worlds on a capable SPH build. The
`--num-envs` to use multiple independent worlds on a capable DexUni build. The
fixed container uses static SDF collision shapes, so DFSPH can collide with it
without running a rigid-body solver. It needs no robot, task configuration or downloaded assets:

Expand All @@ -84,3 +86,30 @@ Focused checks are `tests/compute/test_particles.py`,
`tests/sim/objects/test_fluid_runtime.py`; `test_fluid_visibility.py` checks
camera pixels after stepping and direct state writes. Tutorial checks remain
syntax/CLI smoke checks rather than tutorial import tests.

## Online task and replay layer

The pouring task uses DexUni with nested DFSPH, a shared simulation clock and
one-way rigid-to-fluid coupling. When no joint ownership was explicitly authored,
the fluid setup assigns every finalized joint to MuJoCo before solver construction,
which covers a robot and a free cup across replicated worlds. Explicit ownership
selectors remain caller-owned. The current native prototype requires the pure
MuJoCo rigid path when bodies exist and does not support fluid reaction forces.

`RigidObjectCfg.particle_collision_shape` puts a particle-only SDF boundary on
the same body as its rigid contact hulls. Where DexSim exposes
`NewtonCollisionDesc.contributes_to_mass`, the boundary explicitly excludes
itself from mass. Older builds need explicit mass and inertia for dynamic bodies;
the pouring cup authors its COM and body-frame inertia from its contact hulls.
Static/kinematic boundaries retain their respective motion semantics. Independent
`visual_shape` settings preserve the render mesh.

Normal Gym reset restores or refills selected fluid rows without stepping peer
worlds. Online action execution supplies physical settling. Replay uses the
ordinary object-state and fluid-state writers; its modes and artifact contracts
belong to [fluid Gym integration](../env-framework/fluid-replay.md).

The robot demonstrations, task assets, Gym declarations, observations, recording,
Task Program runner and replay belong to the pouring task layer. See
[fluid Gym integration](../env-framework/fluid-replay.md) and the task's
`extensions/embodichain_tasks/configs/tasks/manipulation/tableware/pour_cup/README.md`.
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ contact-path policy. Expert settings use the native option groups
(`vbd_options`, `mujoco_options`, `collision_options`); unknown solver names
are rejected for mappings and native config objects, and flat DexUni options
are rejected by native validation.
Standalone SPH is not a supported solver family; fluid settings belong under
[DexUni's nested SPH configuration](fluids.md). Robot presets select
Fluid settings belong under [DexUni's nested DFSPH configuration](fluids.md);
there is no separate fluid solver family. Robot presets select
`newton_dexuni` before the MuJoCo aliases and portable fallbacks. Gradient mode
requires an explicit `semi_implicit` solver or a direct/named provider supporting
the requested gradient mode. Functional Scene calls additionally require its
Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/curated.json
Original file line number Diff line number Diff line change
Expand Up @@ -4289,9 +4289,9 @@
{
"path": "embodichain/lab/scripts/run_task.py",
"symbol": "cli",
"start_line": 1680,
"end_line": 1680,
"excerpt": " env = gymnasium.make(id=gym_config[\"id\"], cfg=env_cfg, **action_config)"
"start_line": 2180,
"end_line": 2180,
"excerpt": " env = gymnasium.make(id=gym_config[\"id\"], cfg=env_cfg, **action_config)"
}
]
},
Expand Down
Loading
Loading