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
7 changes: 1 addition & 6 deletions .github/workflows/dataset-tooling.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python: ['3.10', '3.11', '3.12']
python: ['3.11', '3.12']
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
Expand All @@ -61,11 +61,6 @@ jobs:
fail-fast: false
matrix:
include:
- python: '3.10'
torch: '2.7.0'
torchvision: '0.22.0'
torchcodec: '0.5.0'
tensordict: '0.13.0'
- python: '3.11'
torch: '2.7.0'
torchvision: '0.22.0'
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,9 @@ jobs:
NVIDIA_DISABLE_REQUIRE: 1
HF_ENDPOINT: https://hf-mirror.com
PIP_CACHE_DIR: /cache/pip
PYTHONFAULTHANDLER: "1"
SDL_VIDEODRIVER: dummy
XDG_RUNTIME_DIR: /tmp/embodichain-ci-runtime
NEEDS_GENSIM: ${{ needs.test_plan.outputs.needs_gensim }}
NEEDS_CUROBO: ${{ needs.test_plan.outputs.needs_curobo }}
container: *container_template
Expand Down Expand Up @@ -414,6 +417,7 @@ jobs:
run: |
source activate py311
set -euo pipefail
install -d -m 0700 "$XDG_RUNTIME_DIR"
# Login shells may use a different Git config from actions/checkout.
git config --global --add safe.directory "$GITHUB_WORKSPACE"
git -C "$GITHUB_WORKSPACE" rev-parse \
Expand All @@ -427,6 +431,7 @@ jobs:
python scripts/ci/run_test_plan.py \
--plan test-plan.json \
--repo-root "${GITHUB_WORKSPACE}" \
--no-finalize-resource-lanes \
--lane fast \
--lane distributed \
--lane gpu \
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
[![License](https://img.shields.io/github/license/DexForce/EmbodiChain?style=for-the-badge)](LICENSE)
[![Website](https://img.shields.io/badge/website-dexforce.com-yellow?style=for-the-badge&logo=google-chrome&logoColor=white)](https://dexforce.com/embodichain/index.html#/)
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-docs-blue?style=for-the-badge&logo=github&logoColor=white)](https://dexforce.github.io/EmbodiChain/main/index.html)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue?style=for-the-badge&logo=python&logoColor=white)](https://docs.python.org/3/whatsnew/3.12.html)
[![Python](https://img.shields.io/badge/python-3.11%20|%203.12-blue?style=for-the-badge&logo=python&logoColor=white)](https://docs.python.org/3/whatsnew/3.12.html)
[![Version](https://img.shields.io/github/v/release/DexForce/EmbodiChain?style=for-the-badge&label=version)](https://github.com/DexForce/EmbodiChain/releases)
---

Expand Down
40 changes: 26 additions & 14 deletions agent_context/topics/sensor-system/contact-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,27 +21,39 @@ boundary. Observation reads reuse the sampled sensor buffer.
`SimulationManager.physics_step_index` and the query's current actor binding.
Reading a raw sample before its history callback does not consume the history
update. Query metadata is checked even on cache hits so topology rebuilds cannot
retain old contacts. Cached CUDA reads wait for the producing stream. Caller-owned
CUDA graph capture bypasses raw/history deduplication and records the query read
and reductions on the capture stream. Capture invalidates eager cache keys rather
than marking unexecuted work as a completed sample; replay does not execute Python
cache bookkeeping. Callers own replay scheduling and establish stream dependencies before capture
and replay. Capture skips eager producer waits and never records its stream as
a completed producer, including control-interval initialization and reset.
retain old contacts. Cached CUDA reads wait for the producing stream.
`update()` and `update_physics_step()` require eager calls outside caller-owned
CUDA graph capture. Native snapshot reads can wait on uncaptured producer events;
the sensor rejects capture before calling the query or sampling observers.
Callers sample eagerly before capture/replay and establish stream dependencies,
then consume the stable `get_data()` buffers inside their graphs. Replays alone
do not refresh contacts or advance history. The sensor's own reduction graph
remains supported because native acquisition runs before its capture boundary.

Sensor reset clears only selected rows and invalidates this cache; it does not
reset the physics solver. An explicit `update()` may therefore refresh a valid
settled snapshot without advancing history, as scene preparation requires.
It cannot recompute solved contacts after physical state writes; the backend's
contact-availability rules still apply. Empty selections do not invalidate the
cache. `BaseEnv` retains its ordinary acquisition and substep scheduling.
If DexSim reports that physics reset invalidated its solved snapshot, observation
reads return invalid contact rows until a new solve. Other query failures still
propagate. Empty selections do not invalidate the cache. `BaseEnv` retains its
ordinary acquisition and substep scheduling.

CUDA queries use `fetch_async()` and device-resident counts. Sparse Warp kernels
CUDA queries use `fetch_solver_report_async()` and device-resident counts. Sparse Warp kernels
process valid contact rows, using precomputed sorted environment/actor indices;
no environment-by-contact-by-body tensor is allocated. Per-body force, contact
flags and timing buffers persist between samples. `current_air_time` measures
an unfinished flight; `last_air_time` retains its completed duration on landing.
Selective reset clears only the selected rows.
Selective reset clears only the selected rows. Force reduction uses only
components marked available by the sample's normal/friction validity flags.
Geometry-only rows can count as contact when no force threshold is requested;
they do not create measured force or satisfy a positive force threshold.
Native friction is the tangential impulse on actor 0, while the normal points
toward actor 1: actor-0 force is `(-normal * impulse + friction) / impulse_dt`
and actor 1 receives the opposite force. Newton reports the final internal
solver substep's impulse, so the sensor uses the actual World-step duration
divided by the active backend's `num_substeps` for `impulse_dt`. History clocks
still advance by the full World-step duration. Standalone `ContactHistory.update`
accepts `impulse_dt` explicitly and defaults it to the elapsed `dt`.

`dropped_contacts` reports query loss plus separately counted scatter overflow
across the control interval. Query counts stay on the device until this diagnostic
Expand All @@ -64,8 +76,8 @@ and `tests/gym/envs/test_substep_sensors.py`.
observer to the same lifecycle. It receives begin, before-sample, after-sample and
selected-row reset notifications. With no observers, the update path does not
enumerate subscriptions, construct token generators or enter callback loops.
Hooks run outside the sensor's internal CUDA capture; external capture with
observers fails before callbacks run. Observer tokens and after-sample callbacks
Hooks run outside the sensor's internal CUDA capture; all sampling in external
capture fails before callbacks run. Observer tokens and after-sample callbacks
run once per physics step alongside history reduction. A raw sample fetched
earlier in the same step is reused; repeated reads do not advance history or
repeat callbacks. Removal can supply `expected=observer` to retain a replacement
Expand Down
26 changes: 23 additions & 3 deletions agent_context/topics/sensor-system/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,20 @@ configuration failures; missing per-arena render topology is a runtime failure.

`SimulationManager.add_sensor()` prepares the scene and passes its explicit
owner to `ContactSensor`. The sensor resolves configured rigid/link targets to
Spawn handles and creates one query. Preserve these query/buffer contracts:
Spawn handles and creates one query.

Sampling reads completed solver contacts through DexSim's
`fetch_solver_report()` or `fetch_solver_report_async()`. `detect()` and
`fetch()` operate on a separate geometry-only observation and cannot replace
solver reports when interpreting measured impulses or force histories.

After a physics reset invalidates the native solved report, sensor observation
reads return invalid rows until the next solve. A sensor-buffer-only reset may
still reread the same valid native report. Contact sampling must run outside
caller-owned CUDA graph capture; only the stable observation buffers are consumed
inside that graph. See [history and substeps](contact-history.md) for ordering.

Preserve these query/buffer contracts:

- `filter_need_both_actor` chooses query `match="all"` or `"any"`.
- Capacity is bounded per Arena as well as globally, so a busy environment
Expand All @@ -35,11 +48,18 @@ Spawn handles and creates one query. Preserve these query/buffer contracts:
- Only validity/counts reset each update. Data outside valid rows is undefined.

`contact_capabilities` distinguishes geometry from normal/friction impulse
support. Do not infer force support from sensor construction alone. Inspect
support for the whole query. Current DexSim DexUni reports may mix geometry-only
and measured-force rows; `impulse_valid` and `friction_valid` preserve their
per-row quantity availability through sensor scatter, filtering and reset.
Unavailable values are placeholders, not measured zeros. Older buffers without
per-row flags use the query capabilities; DexUni queries require the newer
validity contract. Do not infer force support from sensor construction alone. Inspect
`supports_contact_sensor` in `embodichain/lab/sim/physics/` for the current
backend/solver/device matrix: Newton AutoSolver may change the answer during
backend/solver/device matrix: DexUni's scene-based dispatch may change the answer during
preparation, so the manager checks again afterwards.

Particle-shape contacts do not enter this rigid ContactQuery.

The sensor retains backend-emitted rows rather than reducing an actor pair to
one contact. Force-reporting paths apply the query's positive-impulse filtering;
geometry-only paths may provide valid rows with zero impulse. Solver settings
Expand Down
2 changes: 1 addition & 1 deletion agent_context/topics/sensor-system/sensor-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Create sensors through `SimulationManager.add_sensor()`. The explicit manager
owns the World, ordered Arenas, preparation and semantic parent resolution;
sensors must not rediscover a singleton manager. Cameras are render features
on both physics backends. Contact availability is a backend capability checked
before preparation and again after Newton AutoSolver selection.
before preparation and again after DexUni's scene-based dispatch.

Robot-mounted cameras are declared in `RobotCfg.sensors` with robot-local
parent links. `SimulationManager.add_robot()` initializes them only when the
Expand Down
7 changes: 5 additions & 2 deletions agent_context/topics/simulation-system/deformables.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ binding. Return to the [simulation overview](simulation-system.md).
uses one registry and backend dispatch for both topologies.

The supported path is Newton on CUDA, without gradient mode. Declarations
accept unresolved AutoSolver or a supported particle solver (`xpbd`,
`semi_implicit`, `vbd`, `dexuni`); they reject unsupported backends/solvers and
accept the default DexUni solver or an explicit supported particle solver
(`xpbd`, `semi_implicit`, `vbd`); they reject unsupported backends/solvers and
post-finalization additions. Default soft/cloth compatibility is absent.
Future backend support belongs at dispatch, not inside a monolithic config.

Expand Down Expand Up @@ -45,6 +45,9 @@ parser. Volume-only `meshing` and common `surface_props` preserve topology
ownership. Volume elasticity uses Young's modulus/Poisson's ratio, translated
to Lamé coefficients at Spawn; density units differ (kg/m³ volume, kg/m²
surface). Exact fields and defaults stay in the typed config source.
Optional `attrs.contact_material` sets DexUni stiffness, damping and dynamic
friction per soft or cloth object; it is separate from element elasticity and
replaces removed flat solver-level soft-contact coefficients in examples.

## Kinematic node controls

Expand Down
23 changes: 14 additions & 9 deletions agent_context/topics/simulation-system/physics-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,11 @@ device, not a separate environment tensor device.
`None` retains the native default. Gym accepts the former in `physics_config`
and the latter at the top level through `config_to_cfg()`.

Newton `solver_cfg=None` preserves DexSim's scene-aware `AutoSolverCfg`.
The concrete solver is resolved from the complete Spawn scene, then exposed
through `NewtonPhysicsBackend.solver_type`. Do not guess a solver-specific robot
preset while it is unresolved. Gradient mode requires an explicit
Newton `solver_cfg=None` preserves DexSim's scene-aware `DexUniSolverCfg`.
DexUni resolves its ownership and contact paths from the complete Spawn scene;
the configured solver type is exposed through `NewtonPhysicsBackend.solver_type`.
Do not guess a solver-specific robot preset while scene ownership is unresolved.
Gradient mode requires an explicit
`semi_implicit` solver. Read exact solver options/defaults in
`cfg/simulation.py` and the installed DexSim config types; do not substitute a
hardcoded fallback when an expected DexSim API is absent.
Expand All @@ -40,8 +41,10 @@ The manual differentiable trajectory requires the external pipeline; see

Capability checks remain explicit: Default owns native rigid constraints and
Newton deformables are separate. Contact support is rechecked after Newton
solver resolution; DexUni and MuJoCo-Warp on CPU do not expose the supported
ContactQuery path. See `physics/` and [sensors](../sensor-system/sensor-system.md).
solver resolution. DexUni requires per-row `ContactBuffer` quantity validity;
its one-way CPU MuJoCo path can expose geometry-only contacts, while CPU
MuJoCo force reports are unavailable. See `physics/` and
[sensors](../sensor-system/sensor-system.md).

## Sparse source physics

Expand Down Expand Up @@ -86,9 +89,11 @@ preserve mode, without replacing explicit zero, margins or materials. Inspect
`spawn/descriptors.py` for these application defaults rather than altering
DexSim global defaults.

Newton `condim` belongs in collision descriptors before preparation; friction
coefficients belong in material properties. Use per-link overlays for contact
intent, not finalized solver-array mutations. `has_particle_collision` is
Newton `condim`, `contype` and `conaffinity` belong in collision descriptors
before preparation; friction coefficients and raw MuJoCo `solref`, `solimp` and
`solmix` belong in material properties. Explicit `solref` retains its native
positive or direct-mode meaning. Use per-link overlays for contact intent, not
finalized solver-array mutations. `has_particle_collision` is
per-shape participation; Arena isolation remains scene-owned.

`DefaultRigidBodyPropertiesCfg.has_gravity` is Default-native configuration,
Expand Down
5 changes: 5 additions & 0 deletions agent_context/topics/simulation-system/rendering.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@ native renderer. Viser retains native rendering because its current exporter
reads visual meshes. Checkpoint evaluation with `--viewer` defaults to Hybrid
when the saved training configuration uses NoRender.

DexSim 0.6 still processes Spawn's visual material table on NoRender native
add/finalize calls. `SpawnScene` temporarily excludes that table during those
calls so texture binding is never attempted without a renderer, then restores
the authored definitions for metadata and later declarations.

## Default scene presentation

`SimulationManager.set_default_background()` authors the native ground material
Expand Down
7 changes: 4 additions & 3 deletions docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,8 @@ complete Python dependency sets and explicit conda package URLs/checksums.
The CUDA base, Node base, Miniforge installer and cuRobo commit are pinned.
Both DexSim wheel URLs carry SHA256 pins, which the installer verifies even
though the wheel server uses HTTP. These match the published index checksums
and the payloads in the previously qualified Python 3.11/3.12 installations.
for DexSim 0.6.0rc1. Build and qualify both updated profiles before promoting
new image digests.
DexSim and LeRobot currently require different OpenCV distributions sharing
`cv2`. Python-selected dependencies pin both to the same release; qualification
checks the imported binding as well as distribution metadata.
Expand All @@ -189,10 +190,10 @@ free to install their own Torch/codec profile.
## CI rollout and rollback

CI defaults to the published internal `v4-py311-py312` image
and activates `py311`. The image reference and activation command are explicit
and activates `py312`. The image reference and activation command are explicit

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 CI guide names wrong Python

docker/README.md says CI activates py312, but the latest change switches both the shared action and the main test job back to py311. Contributors following this guide will use a different Python and dependency set from CI. docker/VALIDATION.md also still says main CI uses Python 3.12. Update both statements to match the workflows, or restore the intended Python 3.12 jobs.

Prompt To Fix With AI
This is a comment left during a code review.
Path: docker/README.md
Line: 193

Comment:
**CI guide names wrong Python**

`docker/README.md` says CI activates `py312`, but the latest change switches both the shared action and the main test job back to `py311`. Contributors following this guide will use a different Python and dependency set from CI. `docker/VALIDATION.md` also still says main CI uses Python 3.12. Update both statements to match the workflows, or restore the intended Python 3.12 jobs.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Codex Fix in Claude Code

in the existing workflows/shared action; the existing job graph, triggers,
test selection and installation commands are preserved. The SDK compatibility
matrix selects Python 3.10, 3.11 and 3.12 independently of this default.
matrix selects Python 3.11 and 3.12 independently of this default.

Builds continue producing source-commit candidate tags. After qualification
and successful CI, promote the existing manifests to the public
Expand Down
6 changes: 6 additions & 0 deletions docker/VALIDATION.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Published container images

> Historical qualification below includes Python 3.10 results from an earlier
> dependency profile. This checkout requires Python 3.11 or newer;
> the main CI uses Python 3.12.
> The current Docker locks select DexSim 0.6.0rc1; the published image digests
> and qualification runs below describe the earlier DexSim 0.5.1rc1 images.

Source commit: `c42e8a0b0857ae00aeeb21d414d30318abb2e171`.
Implementation: [PR #914](https://github.com/DexForce/EmbodiChain/pull/914),
which incorporates [PR #911](https://github.com/DexForce/EmbodiChain/pull/911).
Expand Down
10 changes: 6 additions & 4 deletions docker/locks/py311.txt
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ datasets==4.8.5
datetime==6.0
decorator==5.3.1
deepdiff==8.6.2
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.5.1rc1-cp311-cp311-manylinux_2_31_x86_64.whl#sha256=e6177696fca4cedf91b08e98c2789c3c98ebd48c3283d4dbe194f65fbf7fb4a5
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.6.0rc1-cp311-cp311-manylinux_2_31_x86_64.whl#sha256=f3cef56bd987b3166b871d7d9f29b2f2d6ceb274cf47ca9a598c51d6a6785718
diffusers==0.35.2
dill==0.4.1
distro==1.9.0
Expand Down Expand Up @@ -138,16 +138,16 @@ mdurl==0.1.2
mergedeep==1.3.4
mpmath==1.3.0
msgspec==0.22.0
mujoco==3.12.0
mujoco-warp==3.12.0
mujoco==3.15.0
mujoco-warp==3.15.0
multidict==7.2.1
multiprocess==0.70.19
mypy-extensions==1.1.0
narwhals==2.28.0
nbformat==5.11.1
nest-asyncio==1.6.0
networkx==3.6.1
newton==1.6.0
newton==1.7.0
nodeenv==1.12.0
nuitka==4.3.3
numpy==2.2.6
Expand Down Expand Up @@ -187,6 +187,7 @@ parso==0.8.7
pathspec==1.1.1
pexpect==4.9.0
pfzy==0.3.4
physx-usd-schemas==25.11.2.72696984
pillow==12.3.0
pin==4.1.0
pin-pink==4.4.0
Expand Down Expand Up @@ -285,6 +286,7 @@ typing-extensions==4.16.0
typing-inspect==0.9.0
typing-inspection==0.4.4
tzdata==2026.6
urdfdom-py==1.2.1.post1
urllib3==2.8.0
usd-core==26.11
uuid-utils==0.19.0
Expand Down
10 changes: 6 additions & 4 deletions docker/locks/py312.txt
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ dash==4.5.0
datasets==4.8.5
datetime==6.0
decorator==5.3.1
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.5.1rc1-cp312-cp312-manylinux_2_31_x86_64.whl#sha256=88178eb81ebe9b16fa8a79d17c7ffa52b9c0256c94942fdeb6f637200d465866
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.6.0rc1-cp312-cp312-manylinux_2_31_x86_64.whl#sha256=f84c0f1763689b6d57f63308b417932237325666c20d1e3379bafbb7cdad7076
dill==0.4.1
distro==1.9.0
draccus==0.11.6
Expand Down Expand Up @@ -133,16 +133,16 @@ mdurl==0.1.2
mergedeep==1.3.4
mpmath==1.3.0
msgspec==0.22.0
mujoco==3.12.0
mujoco-warp==3.12.0
mujoco==3.15.0
mujoco-warp==3.15.0
multidict==7.2.1
multiprocess==0.70.19
mypy-extensions==1.1.0
narwhals==2.28.0
nbformat==5.11.1
nest-asyncio==1.6.0
networkx==3.7
newton==1.6.0
newton==1.7.0
nodeenv==1.12.0
nuitka==4.3.3
numpy==2.2.6
Expand Down Expand Up @@ -181,6 +181,7 @@ pandas==2.3.3
parso==0.8.7
pathspec==1.1.1
pexpect==4.9.0
physx-usd-schemas==25.11.2.72696984
pillow==12.3.0
pin==4.1.0
pin-pink==4.4.0
Expand Down Expand Up @@ -274,6 +275,7 @@ typing-extensions==4.16.0
typing-inspect==0.9.0
typing-inspection==0.4.4
tzdata==2026.6
urdfdom-py==1.2.1.post1
urllib3==2.8.0
usd-core==26.11
uuid-utils==0.19.0
Expand Down
2 changes: 1 addition & 1 deletion docker/profiles/py311.in
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Qualified CUDA 12.8 versions; regenerate using docker/lock.sh.
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.5.1rc1-cp311-cp311-manylinux_2_31_x86_64.whl#sha256=e6177696fca4cedf91b08e98c2789c3c98ebd48c3283d4dbe194f65fbf7fb4a5
dexsim-engine @ http://pyp.open3dv.site:2345/packages/dexsim_engine-0.6.0rc1-cp311-cp311-manylinux_2_31_x86_64.whl#sha256=f3cef56bd987b3166b871d7d9f29b2f2d6ceb274cf47ca9a598c51d6a6785718
torch==2.7.0+cu128
torchvision==0.22.0+cu128
torchcodec==0.5.0+cu128
Expand Down
Loading
Loading