From ded5210651b8823a0be6e9f3715c0669497ee77e Mon Sep 17 00:00:00 2001 From: "isaaclab-bot[bot]" <282401363+isaaclab-bot[bot]@users.noreply.github.com> Date: Wed, 30 Sep 2026 05:12:53 +0000 Subject: [PATCH 1/3] [CI][Auto Version Bump] Compile changelog fragments (schedule) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumped packages: - isaaclab: 32.0.0 → 32.1.0 - isaaclab_experimental: 0.2.3 → 0.2.4 - isaaclab_newton: 9.1.0 → 9.1.1 - isaaclab_ov: 4.0.0 → 4.1.0 - isaaclab_tasks: 22.0.0 → 23.0.0 --- .../henry-go2-base-height-inf-guard.rst | 7 ---- .../newton-collection-path-documentation.skip | 1 - .../ovrtx-async-capture-metadata.minor.rst | 5 --- ...-ovrtx-async-frame-announcements.minor.rst | 7 ---- source/isaaclab/docs/CHANGELOG.rst | 22 ++++++++++ source/isaaclab/pyproject.toml | 2 +- .../changelog.d/warp-base-height-reward.rst | 5 --- .../isaaclab_experimental/docs/CHANGELOG.rst | 10 +++++ source/isaaclab_experimental/pyproject.toml | 2 +- .../fabric-review-regressions.skip | 1 - .../fix-newton-collection-exact-match.rst | 6 --- source/isaaclab_newton/docs/CHANGELOG.rst | 11 +++++ source/isaaclab_newton/pyproject.toml | 2 +- ...nk-heterogeneous-cloning-ovphysx.minor.rst | 16 -------- .../ovrtx-async-operation-ownership.rst | 5 --- .../pv-ovrtx-async-slot-buffers.minor.rst | 9 ----- source/isaaclab_ov/docs/CHANGELOG.rst | 29 ++++++++++++++ source/isaaclab_ov/pyproject.toml | 2 +- .../antoiner-fix-drlegs-padmm-divergence.rst | 5 --- .../henry-cassie-gait-symmetry.minor.rst | 13 ------ .../henry-go2-crouch-and-gait-fix.minor.rst | 12 ------ ...nk-heterogeneous-cloning-ovphysx.minor.rst | 4 -- ...ximiliank-remove-franka-reorient.major.rst | 5 --- .../pv-ovrtx-async-slot-buffers.skip | 0 source/isaaclab_tasks/docs/CHANGELOG.rst | 40 +++++++++++++++++++ source/isaaclab_tasks/pyproject.toml | 2 +- 26 files changed, 117 insertions(+), 106 deletions(-) delete mode 100644 source/isaaclab/changelog.d/henry-go2-base-height-inf-guard.rst delete mode 100644 source/isaaclab/changelog.d/newton-collection-path-documentation.skip delete mode 100644 source/isaaclab/changelog.d/ovrtx-async-capture-metadata.minor.rst delete mode 100644 source/isaaclab/changelog.d/pv-ovrtx-async-frame-announcements.minor.rst delete mode 100644 source/isaaclab_experimental/changelog.d/warp-base-height-reward.rst delete mode 100644 source/isaaclab_newton/changelog.d/fabric-review-regressions.skip delete mode 100644 source/isaaclab_newton/changelog.d/fix-newton-collection-exact-match.rst delete mode 100644 source/isaaclab_ov/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst delete mode 100644 source/isaaclab_ov/changelog.d/ovrtx-async-operation-ownership.rst delete mode 100644 source/isaaclab_ov/changelog.d/pv-ovrtx-async-slot-buffers.minor.rst delete mode 100644 source/isaaclab_tasks/changelog.d/antoiner-fix-drlegs-padmm-divergence.rst delete mode 100644 source/isaaclab_tasks/changelog.d/henry-cassie-gait-symmetry.minor.rst delete mode 100644 source/isaaclab_tasks/changelog.d/henry-go2-crouch-and-gait-fix.minor.rst delete mode 100644 source/isaaclab_tasks/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst delete mode 100644 source/isaaclab_tasks/changelog.d/maximiliank-remove-franka-reorient.major.rst delete mode 100644 source/isaaclab_tasks/changelog.d/pv-ovrtx-async-slot-buffers.skip diff --git a/source/isaaclab/changelog.d/henry-go2-base-height-inf-guard.rst b/source/isaaclab/changelog.d/henry-go2-base-height-inf-guard.rst deleted file mode 100644 index a64094f7ef1f..000000000000 --- a/source/isaaclab/changelog.d/henry-go2-base-height-inf-guard.rst +++ /dev/null @@ -1,7 +0,0 @@ -Fixed -^^^^^ - -* Fixed :func:`~isaaclab.envs.mdp.rewards.base_height_l2` returning an infinite reward for any - environment whose own height scan contained a missed ray, since ``ray_hits_w`` reports ``inf`` - for a ray that finds nothing within its ``max_distance`` rather than a clamped value. Now only - finite ray hits are averaged into the terrain-adjusted target height. diff --git a/source/isaaclab/changelog.d/newton-collection-path-documentation.skip b/source/isaaclab/changelog.d/newton-collection-path-documentation.skip deleted file mode 100644 index ccc05452ffd4..000000000000 --- a/source/isaaclab/changelog.d/newton-collection-path-documentation.skip +++ /dev/null @@ -1 +0,0 @@ -Removed the obsolete Newton collection path restriction from the configuration documentation. diff --git a/source/isaaclab/changelog.d/ovrtx-async-capture-metadata.minor.rst b/source/isaaclab/changelog.d/ovrtx-async-capture-metadata.minor.rst deleted file mode 100644 index 63b9ab93c79a..000000000000 --- a/source/isaaclab/changelog.d/ovrtx-async-capture-metadata.minor.rst +++ /dev/null @@ -1,5 +0,0 @@ -Added -^^^^^ - -* Attached capture poses, calibration, and frame indices to delayed OVRTX images through - ``CameraData.info[output_name]["capture"]`` while preserving the live camera fields. diff --git a/source/isaaclab/changelog.d/pv-ovrtx-async-frame-announcements.minor.rst b/source/isaaclab/changelog.d/pv-ovrtx-async-frame-announcements.minor.rst deleted file mode 100644 index 1c7e84c49008..000000000000 --- a/source/isaaclab/changelog.d/pv-ovrtx-async-frame-announcements.minor.rst +++ /dev/null @@ -1,7 +0,0 @@ -Added -^^^^^ - -* Added :meth:`~isaaclab.renderers.BaseRenderer.prepare_capture` and - :meth:`~isaaclab.renderers.BaseRenderer.reset` hooks for delayed camera observations. - Asynchronous renderers can publish matching image metadata through ``CameraData.info`` and - discard pending observations on reset without changing live camera fields. diff --git a/source/isaaclab/docs/CHANGELOG.rst b/source/isaaclab/docs/CHANGELOG.rst index 0b4aae421047..567236d4fce3 100644 --- a/source/isaaclab/docs/CHANGELOG.rst +++ b/source/isaaclab/docs/CHANGELOG.rst @@ -1,6 +1,28 @@ Changelog --------- +32.1.0 (2026-09-30) +~~~~~~~~~~~~~~~~~~~ + +Added +^^^^^ + +* Attached capture poses, calibration, and frame indices to delayed OVRTX images through + ``CameraData.info[output_name]["capture"]`` while preserving the live camera fields. +* Added :meth:`~isaaclab.renderers.BaseRenderer.prepare_capture` and + :meth:`~isaaclab.renderers.BaseRenderer.reset` hooks for delayed camera observations. + Asynchronous renderers can publish matching image metadata through ``CameraData.info`` and + discard pending observations on reset without changing live camera fields. + +Fixed +^^^^^ + +* Fixed :func:`~isaaclab.envs.mdp.rewards.base_height_l2` returning an infinite reward for any + environment whose own height scan contained a missed ray, since ``ray_hits_w`` reports ``inf`` + for a ray that finds nothing within its ``max_distance`` rather than a clamped value. Now only + finite ray hits are averaged into the terrain-adjusted target height. + + 32.0.0 (2026-09-29) ~~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab/pyproject.toml b/source/isaaclab/pyproject.toml index dec277df0135..7d4bd2a99362 100644 --- a/source/isaaclab/pyproject.toml +++ b/source/isaaclab/pyproject.toml @@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta" [project] name = "isaaclab" -version = "32.0.0" +version = "32.1.0" description = "Extension providing main framework interfaces and abstractions for robot learning." license = {text = "BSD-3-Clause"} authors = [{name = "Isaac Lab Project Developers"}] diff --git a/source/isaaclab_experimental/changelog.d/warp-base-height-reward.rst b/source/isaaclab_experimental/changelog.d/warp-base-height-reward.rst deleted file mode 100644 index e90c5e8cc9ef..000000000000 --- a/source/isaaclab_experimental/changelog.d/warp-base-height-reward.rst +++ /dev/null @@ -1,5 +0,0 @@ -Fixed -^^^^^ - -* Added the Warp implementation of ``base_height_l2``, restoring Warp frontend support for - Unitree Go2 tasks with the base-height reward enabled. diff --git a/source/isaaclab_experimental/docs/CHANGELOG.rst b/source/isaaclab_experimental/docs/CHANGELOG.rst index d38920be6c03..75e86b9fd04e 100644 --- a/source/isaaclab_experimental/docs/CHANGELOG.rst +++ b/source/isaaclab_experimental/docs/CHANGELOG.rst @@ -1,6 +1,16 @@ Changelog --------- +0.2.4 (2026-09-30) +~~~~~~~~~~~~~~~~~~ + +Fixed +^^^^^ + +* Added the Warp implementation of ``base_height_l2``, restoring Warp frontend support for + Unitree Go2 tasks with the base-height reward enabled. + + 0.2.3 (2026-09-28) ~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab_experimental/pyproject.toml b/source/isaaclab_experimental/pyproject.toml index 3b49e46241d1..da3388127359 100644 --- a/source/isaaclab_experimental/pyproject.toml +++ b/source/isaaclab_experimental/pyproject.toml @@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta" [project] name = "isaaclab_experimental" -version = "0.2.3" +version = "0.2.4" description = "Provides early access to future features that are not yet production-ready." license = {text = "BSD-3-Clause"} authors = [{name = "Isaac Lab Project Developers"}] diff --git a/source/isaaclab_newton/changelog.d/fabric-review-regressions.skip b/source/isaaclab_newton/changelog.d/fabric-review-regressions.skip deleted file mode 100644 index 654f59c39c58..000000000000 --- a/source/isaaclab_newton/changelog.d/fabric-review-regressions.skip +++ /dev/null @@ -1 +0,0 @@ -Covered nested articulation root-pose rendering and rigid-body rendering alongside cables. diff --git a/source/isaaclab_newton/changelog.d/fix-newton-collection-exact-match.rst b/source/isaaclab_newton/changelog.d/fix-newton-collection-exact-match.rst deleted file mode 100644 index d99377614559..000000000000 --- a/source/isaaclab_newton/changelog.d/fix-newton-collection-exact-match.rst +++ /dev/null @@ -1,6 +0,0 @@ -Fixed -^^^^^ - -* Fixed :class:`~isaaclab_newton.assets.RigidObjectCollection` selecting rigid bodies outside the - collection whose names share the members' prefix or suffix, and rejecting members at different - path depths. The collection view now matches each configured prim path exactly. diff --git a/source/isaaclab_newton/docs/CHANGELOG.rst b/source/isaaclab_newton/docs/CHANGELOG.rst index 92cb8aefd29f..2c725643e883 100644 --- a/source/isaaclab_newton/docs/CHANGELOG.rst +++ b/source/isaaclab_newton/docs/CHANGELOG.rst @@ -1,6 +1,17 @@ Changelog --------- +9.1.1 (2026-09-30) +~~~~~~~~~~~~~~~~~~ + +Fixed +^^^^^ + +* Fixed :class:`~isaaclab_newton.assets.RigidObjectCollection` selecting rigid bodies outside the + collection whose names share the members' prefix or suffix, and rejecting members at different + path depths. The collection view now matches each configured prim path exactly. + + 9.1.0 (2026-09-29) ~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab_newton/pyproject.toml b/source/isaaclab_newton/pyproject.toml index fe05d0b3714a..0d428e348dd3 100644 --- a/source/isaaclab_newton/pyproject.toml +++ b/source/isaaclab_newton/pyproject.toml @@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta" [project] name = "isaaclab_newton" -version = "9.1.0" +version = "9.1.1" description = "Extension providing IsaacLab with Newton specific abstractions." license = {text = "BSD-3-Clause"} authors = [{name = "Isaac Lab Project Developers"}] diff --git a/source/isaaclab_ov/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst b/source/isaaclab_ov/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst deleted file mode 100644 index 43ebcc61e693..000000000000 --- a/source/isaaclab_ov/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst +++ /dev/null @@ -1,16 +0,0 @@ -Added -^^^^^ - -* Added plan-driven OvPhysX cloning for heterogeneous rigid-body and articulation geometry variants. GPU cloning imported complete original worlds and assigned one native environment ID per copied world; CPU imported full USD copies with collision grouping. - -Fixed -^^^^^ - -* Preserved numeric environment order in tensor bindings, including non-cloned multi-instance assets, so indexed state reads and writes address the intended instances. -* Paired each cloned contact sensor with its own environment's filters and shared filters, and rejected missing filters that would silently remove sensor rows. -* Preserved all active source variants and independently authored assets during physics export, including custom environment templates and scaled asset roots. -* Preserved contacts with USD-only physics in each world composition and rejected incompatible active rotation-axis and tendon layouts before combining articulation variants. -* Removed destination placeholders and empty exported environment roots that caused quadratic native binding lookup costs. -* Registered Newton USD schemas before OVStage parsing. This affected all authored physics assets, including mimic-joint constraints, not only cloned assets. -* Deferred scene-data tensor bindings until visualization requests them, avoiding unnecessary headless-training startup cost. -* Matched the native scene's declared step rate to ``SimulationCfg.dt`` so automatic contact offsets used the actual simulation timestep instead of the 60 Hz default. diff --git a/source/isaaclab_ov/changelog.d/ovrtx-async-operation-ownership.rst b/source/isaaclab_ov/changelog.d/ovrtx-async-operation-ownership.rst deleted file mode 100644 index 0e601fdd46cc..000000000000 --- a/source/isaaclab_ov/changelog.d/ovrtx-async-operation-ownership.rst +++ /dev/null @@ -1,5 +0,0 @@ -Fixed -^^^^^ - -* Unified retention of asynchronous OVRTX camera, transform, and geometry buffers until native writes completed, - isolated camera captures across resets, and avoided extracting priming images twice. diff --git a/source/isaaclab_ov/changelog.d/pv-ovrtx-async-slot-buffers.minor.rst b/source/isaaclab_ov/changelog.d/pv-ovrtx-async-slot-buffers.minor.rst deleted file mode 100644 index 827a57a5339b..000000000000 --- a/source/isaaclab_ov/changelog.d/pv-ovrtx-async-slot-buffers.minor.rst +++ /dev/null @@ -1,9 +0,0 @@ -Added -^^^^^ - -* Added an opt-in asynchronous OVRTX render path controlled by - :attr:`~isaaclab_ov.renderers.OVRTXRendererCfg.async_rendering`. - ``True`` returns each camera's previous capture while rendering the next image. The first - capture and the first capture after reset wait for a fresh image. Matching capture poses, - calibration, and frame indices are available in ``camera.data.info[output_name]["capture"]``; - the live camera fields remain current. diff --git a/source/isaaclab_ov/docs/CHANGELOG.rst b/source/isaaclab_ov/docs/CHANGELOG.rst index 3d486c727fde..644bde5a3c2c 100644 --- a/source/isaaclab_ov/docs/CHANGELOG.rst +++ b/source/isaaclab_ov/docs/CHANGELOG.rst @@ -1,6 +1,35 @@ Changelog --------- +4.1.0 (2026-09-30) +~~~~~~~~~~~~~~~~~~ + +Added +^^^^^ + +* Added plan-driven OvPhysX cloning for heterogeneous rigid-body and articulation geometry variants. GPU cloning imported complete original worlds and assigned one native environment ID per copied world; CPU imported full USD copies with collision grouping. +* Added an opt-in asynchronous OVRTX render path controlled by + :attr:`~isaaclab_ov.renderers.OVRTXRendererCfg.async_rendering`. + ``True`` returns each camera's previous capture while rendering the next image. The first + capture and the first capture after reset wait for a fresh image. Matching capture poses, + calibration, and frame indices are available in ``camera.data.info[output_name]["capture"]``; + the live camera fields remain current. + +Fixed +^^^^^ + +* Preserved numeric environment order in tensor bindings, including non-cloned multi-instance assets, so indexed state reads and writes address the intended instances. +* Paired each cloned contact sensor with its own environment's filters and shared filters, and rejected missing filters that would silently remove sensor rows. +* Preserved all active source variants and independently authored assets during physics export, including custom environment templates and scaled asset roots. +* Preserved contacts with USD-only physics in each world composition and rejected incompatible active rotation-axis and tendon layouts before combining articulation variants. +* Removed destination placeholders and empty exported environment roots that caused quadratic native binding lookup costs. +* Registered Newton USD schemas before OVStage parsing. This affected all authored physics assets, including mimic-joint constraints, not only cloned assets. +* Deferred scene-data tensor bindings until visualization requests them, avoiding unnecessary headless-training startup cost. +* Matched the native scene's declared step rate to ``SimulationCfg.dt`` so automatic contact offsets used the actual simulation timestep instead of the 60 Hz default. +* Unified retention of asynchronous OVRTX camera, transform, and geometry buffers until native writes completed, + isolated camera captures across resets, and avoided extracting priming images twice. + + 4.0.0 (2026-09-29) ~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab_ov/pyproject.toml b/source/isaaclab_ov/pyproject.toml index b0d45d79189b..f456f3ae71b3 100644 --- a/source/isaaclab_ov/pyproject.toml +++ b/source/isaaclab_ov/pyproject.toml @@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta" [project] name = "isaaclab_ov" -version = "4.0.0" +version = "4.1.0" description = "Extension providing Omniverse rendering and OVPhysX simulation integrations." license = {text = "BSD-3-Clause"} authors = [{name = "Isaac Lab Project Developers"}] diff --git a/source/isaaclab_tasks/changelog.d/antoiner-fix-drlegs-padmm-divergence.rst b/source/isaaclab_tasks/changelog.d/antoiner-fix-drlegs-padmm-divergence.rst deleted file mode 100644 index 0ec40801a7be..000000000000 --- a/source/isaaclab_tasks/changelog.d/antoiner-fix-drlegs-padmm-divergence.rst +++ /dev/null @@ -1,5 +0,0 @@ -Fixed -^^^^^ - -* Stabilized the DR Legs Kamino P-ADMM preset by disabling its driven-joint effort limit; PhysX retained - the 3.1 N m limit. diff --git a/source/isaaclab_tasks/changelog.d/henry-cassie-gait-symmetry.minor.rst b/source/isaaclab_tasks/changelog.d/henry-cassie-gait-symmetry.minor.rst deleted file mode 100644 index 0da0e419b2b7..000000000000 --- a/source/isaaclab_tasks/changelog.d/henry-cassie-gait-symmetry.minor.rst +++ /dev/null @@ -1,13 +0,0 @@ -Added -^^^^^ - -* Added :func:`~isaaclab_tasks.core.velocity.mdp.rewards.feet_air_time_variance`, penalizing an - uneven swing/stance split between a biped's feet. - -Changed -^^^^^^^ - -* Changed ``Isaac-Velocity-Flat-Cassie``, ``Isaac-Velocity-Rough-Cassie`` and - ``Isaac-Velocity-Flat-H1`` to include the new ``air_time_variance`` reward term, which fixes the - tilted gait these tasks otherwise converge on. Policies trained on them will differ from ones - trained before this change; set the weight to ``0.0`` to recover the previous reward. diff --git a/source/isaaclab_tasks/changelog.d/henry-go2-crouch-and-gait-fix.minor.rst b/source/isaaclab_tasks/changelog.d/henry-go2-crouch-and-gait-fix.minor.rst deleted file mode 100644 index 022ede555879..000000000000 --- a/source/isaaclab_tasks/changelog.d/henry-go2-crouch-and-gait-fix.minor.rst +++ /dev/null @@ -1,12 +0,0 @@ -Changed -^^^^^^^ - -* Changed ``Isaac-Velocity-Flat-UnitreeGo2`` and ``Isaac-Velocity-Rough-UnitreeGo2`` to add a - ``base_height_l2`` reward term at weight ``-30.0`` (rough, height-scanner adjusted) and disabled - on flat via ``sensor_cfg=None``. Without it, Go2's leg colliders let a policy rest its weight on - the legs and collect the full episode-length alive bonus from a permanent crouch, since torso - contact never fires and flat-orientation reward can't see it. -* Changed ``action_rate_l2`` on both tasks from the shared default of ``-0.01`` to ``-0.005``. The - stronger penalty locked one hind foot into a low-amplitude, dragging gait on flat terrain with - the Newton backend. Policies trained on these tasks will differ from ones trained before this - change. diff --git a/source/isaaclab_tasks/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst b/source/isaaclab_tasks/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst deleted file mode 100644 index 095cc149d70c..000000000000 --- a/source/isaaclab_tasks/changelog.d/maximiliank-heterogeneous-cloning-ovphysx.minor.rst +++ /dev/null @@ -1,4 +0,0 @@ -Changed -^^^^^^^ - -* Enabled the heterogeneous shapes preset by default for KUKA–Allegro tasks with OvPhysX. Select the ``cube`` preset explicitly to retain the previous homogeneous object setup. diff --git a/source/isaaclab_tasks/changelog.d/maximiliank-remove-franka-reorient.major.rst b/source/isaaclab_tasks/changelog.d/maximiliank-remove-franka-reorient.major.rst deleted file mode 100644 index 04a0cd995c0e..000000000000 --- a/source/isaaclab_tasks/changelog.d/maximiliank-remove-franka-reorient.major.rst +++ /dev/null @@ -1,5 +0,0 @@ -Removed -^^^^^^^ - -* Removed the unsupported ``Isaac-Reorient-Franka`` task and its environment configuration. Migrate custom - reorientation experiments to a maintained task or keep a local copy of the old configuration. diff --git a/source/isaaclab_tasks/changelog.d/pv-ovrtx-async-slot-buffers.skip b/source/isaaclab_tasks/changelog.d/pv-ovrtx-async-slot-buffers.skip deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/source/isaaclab_tasks/docs/CHANGELOG.rst b/source/isaaclab_tasks/docs/CHANGELOG.rst index c5e93e8ea44f..46f7f08640be 100644 --- a/source/isaaclab_tasks/docs/CHANGELOG.rst +++ b/source/isaaclab_tasks/docs/CHANGELOG.rst @@ -1,6 +1,46 @@ Changelog --------- +23.0.0 (2026-09-30) +~~~~~~~~~~~~~~~~~~~ + +Added +^^^^^ + +* Added :func:`~isaaclab_tasks.core.velocity.mdp.rewards.feet_air_time_variance`, penalizing an + uneven swing/stance split between a biped's feet. + +Changed +^^^^^^^ + +* Enabled the heterogeneous shapes preset by default for KUKA–Allegro tasks with OvPhysX. Select the ``cube`` preset explicitly to retain the previous homogeneous object setup. +* Changed ``Isaac-Velocity-Flat-Cassie``, ``Isaac-Velocity-Rough-Cassie`` and + ``Isaac-Velocity-Flat-H1`` to include the new ``air_time_variance`` reward term, which fixes the + tilted gait these tasks otherwise converge on. Policies trained on them will differ from ones + trained before this change; set the weight to ``0.0`` to recover the previous reward. +* Changed ``Isaac-Velocity-Flat-UnitreeGo2`` and ``Isaac-Velocity-Rough-UnitreeGo2`` to add a + ``base_height_l2`` reward term at weight ``-30.0`` (rough, height-scanner adjusted) and disabled + on flat via ``sensor_cfg=None``. Without it, Go2's leg colliders let a policy rest its weight on + the legs and collect the full episode-length alive bonus from a permanent crouch, since torso + contact never fires and flat-orientation reward can't see it. +* Changed ``action_rate_l2`` on both tasks from the shared default of ``-0.01`` to ``-0.005``. The + stronger penalty locked one hind foot into a low-amplitude, dragging gait on flat terrain with + the Newton backend. Policies trained on these tasks will differ from ones trained before this + change. + +Removed +^^^^^^^ + +* Removed the unsupported ``Isaac-Reorient-Franka`` task and its environment configuration. Migrate custom + reorientation experiments to a maintained task or keep a local copy of the old configuration. + +Fixed +^^^^^ + +* Stabilized the DR Legs Kamino P-ADMM preset by disabling its driven-joint effort limit; PhysX retained + the 3.1 N m limit. + + 22.0.0 (2026-09-29) ~~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab_tasks/pyproject.toml b/source/isaaclab_tasks/pyproject.toml index ec6b8fb7088a..c2714465d760 100644 --- a/source/isaaclab_tasks/pyproject.toml +++ b/source/isaaclab_tasks/pyproject.toml @@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta" [project] name = "isaaclab_tasks" -version = "22.0.0" +version = "23.0.0" description = "Extension containing suite of environments for robot learning." license = {text = "BSD-3-Clause"} authors = [{name = "Isaac Lab Project Developers"}] From 4aa39c103a61dbcd2acf680732531892b2dc83d7 Mon Sep 17 00:00:00 2001 From: Kelly Guo Date: Wed, 30 Sep 2026 07:21:31 +0100 Subject: [PATCH 2/3] [Workflow] Use Newton 1.6 release branch (#8114) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Description Moves Isaac Lab from the published `newton[sim]==1.6.0` wheel to Newton's `release-1.6` Git branch. The regenerated lockfile currently resolves `newton==1.6.1rc1` at `dff29635`. The root uv override, wheel-builder override, install-CI override, install smoke expectation, and version-consistency coverage are updated together. Published wheel metadata keeps the compatible `newton[sim]>=1.2.0` lower bound, while source and CI workflows select the release branch through their resolver overrides. ## Type of change - Bug fix / dependency workflow update (non-breaking) ## Release backport - [x] Backport this pull request to the active release branch after it merges into `develop` ## Screenshots Not applicable. ## Validation - `uv lock --check` - `PYTHONPATH=source/isaaclab uv run --no-project --with pytest --with packaging python -m pytest source/isaaclab/test/cli/test_install.py source/isaaclab/test/cli/test_uv_run_pyproject.py source/isaaclab/test/cli/test_wheel_builder_metadata.py -k 'EnsureNewton or version_single_source or wheel_builder_uv_overrides'` — 5 passed - `uv run --no-project python tools/changelog/cli.py check develop` — passed against the current upstream `develop` base - Changed-file pre-commit hooks — all applicable checks passed ## Checklist - [x] I have read and understood the contribution guidelines - [x] I have run the applicable pre-commit checks (the project-managed `uv run isaaclab -f` entry point is unavailable on macOS because the lockfile intentionally excludes macOS; the equivalent changed-file pre-commit run passed) - [x] Documentation changes are not required for this dependency update - [x] My changes generate no new warnings - [x] Existing metadata and install tests cover the updated dependency contract - [x] I have added a changelog fragment under `source/isaaclab/changelog.d/` - [x] My name already exists in `CONTRIBUTORS.md` --- pyproject.toml | 5 +++-- .../changelog.d/use-newton-release-1-6.rst | 5 +++++ source/isaaclab/test/cli/test_uv_run_pyproject.py | 2 +- ..._uv_pip_install_isaaclab_all_trains_cartpole.py | 14 ++++++++++++-- .../test/install_ci/uv_pip/uv-overrides.txt | 2 +- tools/wheel_builder/uv-overrides.txt | 2 +- uv.lock | 11 ++++------- 7 files changed, 27 insertions(+), 14 deletions(-) create mode 100644 source/isaaclab/changelog.d/use-newton-release-1-6.rst diff --git a/pyproject.toml b/pyproject.toml index 10ef9a8d5506..7c9bf36ec16d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -88,7 +88,7 @@ dependencies = [ "gitpython>=3.1.59", # used by RL training and experiment logging # ----- newton (default physics engine) ----- # Pin the Newton release used by both workspace and wheel installs. - "newton[sim]==1.6.0", + "newton[sim]>=1.2.0", # Import and mesh-processing packages used by Newton, including the ones that honoring # USD-authored ``physics:approximation`` requires. Keep these explicit instead of selecting # newton[importers], whose standalone USD dependency would overlap with usd-exchange. @@ -229,6 +229,7 @@ torchaudio = "2.11.0" ovphysx = "0.6.3" ovrtx = "0.5.0.377615" ovstage = "0.2.0.377349" +newton = "release-1.6" warp = "1.17.0" [tool.ruff] @@ -411,7 +412,7 @@ override-dependencies = [ "numpy>=2", "mujoco~=3.12.0", "mujoco-warp~=3.12.0", - "newton[sim]==1.6.0", + "newton[sim] @ git+https://github.com/newton-physics/newton.git@release-1.6", # Force the Newton-matched schemas over isaacsim's ==0.2.0 pin. "newton-usd-schemas>=0.5.0", # isaacsim-asset-isolated and isaacsim-robot-schema 6.1 pin usd-exchange ==2.3.0. diff --git a/source/isaaclab/changelog.d/use-newton-release-1-6.rst b/source/isaaclab/changelog.d/use-newton-release-1-6.rst new file mode 100644 index 000000000000..22fea0715e38 --- /dev/null +++ b/source/isaaclab/changelog.d/use-newton-release-1-6.rst @@ -0,0 +1,5 @@ +Changed +^^^^^^^ + +* Changed the Newton dependency from the ``1.6.0`` PyPI release to the ``release-1.6`` Git branch. + Existing uv installations update automatically. diff --git a/source/isaaclab/test/cli/test_uv_run_pyproject.py b/source/isaaclab/test/cli/test_uv_run_pyproject.py index 51a5ec8a39a3..130407753702 100644 --- a/source/isaaclab/test/cli/test_uv_run_pyproject.py +++ b/source/isaaclab/test/cli/test_uv_run_pyproject.py @@ -160,7 +160,7 @@ def spec(package: str) -> str: # The Newton uv override is its single pin and may select a release or Git revision. newton_spec = next(requirement for requirement in overrides if requirement.startswith("newton[sim]")) - assert "==" in newton_spec or " @ git+" in newton_spec + assert newton_spec.endswith(f"newton.git@{versions['newton']}") # warp-lang is a core dependency whose table value may be an exact pin # ("1.2.3" -> ``==``) or a range (">=1.2.3" -> mirrored verbatim). diff --git a/source/isaaclab/test/install_ci/uv_pip/test_uv_pip_install_isaaclab_all_trains_cartpole.py b/source/isaaclab/test/install_ci/uv_pip/test_uv_pip_install_isaaclab_all_trains_cartpole.py index 02c285389892..379a364471d8 100644 --- a/source/isaaclab/test/install_ci/uv_pip/test_uv_pip_install_isaaclab_all_trains_cartpole.py +++ b/source/isaaclab/test/install_ci/uv_pip/test_uv_pip_install_isaaclab_all_trains_cartpole.py @@ -51,12 +51,22 @@ def test_uv_pip_install_isaaclab_all_trains_cartpole(self, isaaclab_root, wheel, self.create_uv_env(isaaclab_root) result = self.run_in_uv_env( - ["uv", "--no-config", "pip", "install", f"{wheel}[all]"], cwd=isaaclab_root, timeout=1800 + [ + "uv", + "--no-config", + "pip", + "install", + f"{wheel}[all]", + "--overrides", + str(isaaclab_root / "source/isaaclab/test/install_ci/uv_pip/uv-overrides.txt"), + ], + cwd=isaaclab_root, + timeout=1800, ) assert result.returncode == 0, f"uv pip install {wheel}[all] failed:\n{result.stdout}\n{result.stderr}" result = self.run_in_uv_env( - ["python", "-c", "import importlib.metadata as m; assert m.version('newton') == '1.6.0'"], + ["python", "-c", "import importlib.metadata as m; assert m.version('newton') == '1.6.1rc1'"], cwd=isaaclab_root, ) assert result.returncode == 0, ( diff --git a/source/isaaclab/test/install_ci/uv_pip/uv-overrides.txt b/source/isaaclab/test/install_ci/uv_pip/uv-overrides.txt index 95864a020a72..f8afc819ca8e 100644 --- a/source/isaaclab/test/install_ci/uv_pip/uv-overrides.txt +++ b/source/isaaclab/test/install_ci/uv_pip/uv-overrides.txt @@ -1,7 +1,7 @@ numpy>=2 mujoco~=3.12.0 mujoco-warp~=3.12.0 -newton[sim]==1.6.0 +newton[sim] @ git+https://github.com/newton-physics/newton.git@release-1.6 newton-usd-schemas>=0.5.0 usd-exchange==3.0.0 torch==2.12.0 diff --git a/tools/wheel_builder/uv-overrides.txt b/tools/wheel_builder/uv-overrides.txt index 95864a020a72..f8afc819ca8e 100644 --- a/tools/wheel_builder/uv-overrides.txt +++ b/tools/wheel_builder/uv-overrides.txt @@ -1,7 +1,7 @@ numpy>=2 mujoco~=3.12.0 mujoco-warp~=3.12.0 -newton[sim]==1.6.0 +newton[sim] @ git+https://github.com/newton-physics/newton.git@release-1.6 newton-usd-schemas>=0.5.0 usd-exchange==3.0.0 torch==2.12.0 diff --git a/uv.lock b/uv.lock index b3764fe92283..6836cbae6930 100644 --- a/uv.lock +++ b/uv.lock @@ -19,7 +19,7 @@ prerelease-mode = "allow" overrides = [ { name = "mujoco", specifier = "~=3.12.0" }, { name = "mujoco-warp", specifier = "~=3.12.0" }, - { name = "newton", extras = ["sim"], specifier = "==1.6.0" }, + { name = "newton", extras = ["sim"], git = "https://github.com/newton-physics/newton.git?rev=release-1.6" }, { name = "newton-usd-schemas", specifier = ">=0.5.0" }, { name = "numpy", specifier = ">=2" }, { name = "packaging", specifier = ">=20,<27" }, @@ -1989,7 +1989,7 @@ requires-dist = [ { name = "meshio", specifier = ">=5.3.5" }, { name = "moviepy", marker = "extra == 'video'", specifier = ">=1.0.3,<2.0.0.dev0" }, { name = "myst-parser", marker = "extra == 'dev'" }, - { name = "newton", extras = ["sim"], specifier = "==1.6.0" }, + { name = "newton", extras = ["sim"], specifier = ">=1.2.0" }, { name = "newton-usd-schemas", specifier = ">=0.5.0" }, { name = "numba", specifier = ">=0.63.1" }, { name = "numpy", specifier = ">=2" }, @@ -3291,14 +3291,11 @@ wheels = [ [[package]] name = "newton" -version = "1.6.0" -source = { registry = "https://pypi.org/simple" } +version = "1.6.1rc1" +source = { git = "https://github.com/newton-physics/newton.git?rev=release-1.6#dff296359317779bd08e3ba4bc23bc5d4e20bbcd" } dependencies = [ { name = "warp-lang" }, ] -wheels = [ - { url = "https://files.pythonhosted.org/packages/7b/d0/1955c2623762fd1d9f3bc0bb9866b6c0669e1e277202bdc16772520d7da1/newton-1.6.0-py3-none-any.whl", hash = "sha256:5eedebe17d7261ca39e8f97c2f2f20e22e7264d0aed01782f3cb1dd60180b872", size = 6159741, upload-time = "2026-09-10T13:50:10.666Z" }, -] [package.optional-dependencies] sim = [ From de2970f28d8e0aacc4554f9cfe385b66aa1c5c2c Mon Sep 17 00:00:00 2001 From: Maximilian Krause <99733341+maxkra15@users.noreply.github.com> Date: Wed, 30 Sep 2026 09:07:51 +0200 Subject: [PATCH 3/3] Document MPM solver behavior and recordings (#7897) # Description Document Newton MPM tuning and the published comparison recordings without introducing new scripts or APIs. This is a documentation-only PR so the guide can land independently of tutorial implementation. The MPM Solver page covers resolution, timestep, convergence, material comparisons, and interpretation limits. The existing MPM concept page now groups the core scenes and surface-rendering recording; the coupled-solvers page hosts the G1 one-way and two-way recordings and explains their differing proxy geometry. All 18 MP4s are hosted under the verified Isaac Lab /videos/ media path, not in Git. The runnable material, rigid-limit, G1, and surface scripts are in the independent draft PR #8130 under scripts/tutorials/08_mpm/. No commands in this PR require that later PR. ## Type of change - Documentation update ## Validation - Diff against current develop contains only five docs/source files. - `uv run isaaclab -f` passed. - `uv run --isolated --frozen --extra dev -- make -C docs current-docs` passed with warnings treated as errors. - The PR link checker, pre-commit, changelog, and wheel checks passed; remaining CI checks are in progress. ## Release backport - [x] Backport this pull request to the active release branch after it merges into develop ## Checklist - [x] I have read and understood the contribution guidelines - [x] I have run the formatting and link checks - [x] The guide references only APIs and programs already on develop - [x] Media is externally hosted; no encoded videos are committed --- docs/source/concepts/coupled_solvers.rst | 35 +++ docs/source/concepts/solver-tuning/index.rst | 1 + .../concepts/solver-tuning/tune_mpm.rst | 278 ++++++++++++++++++ docs/source/concepts/using_mpm.rst | 171 ++++++----- docs/source/setup/demos.rst | 2 + 5 files changed, 417 insertions(+), 70 deletions(-) create mode 100644 docs/source/concepts/solver-tuning/tune_mpm.rst diff --git a/docs/source/concepts/coupled_solvers.rst b/docs/source/concepts/coupled_solvers.rst index f16fcddd3710..8f3863ab2c4d 100644 --- a/docs/source/concepts/coupled_solvers.rst +++ b/docs/source/concepts/coupled_solvers.rst @@ -224,6 +224,41 @@ can grow independently while retaining matching: ) +Rigid--MPM Comparison Recordings +-------------------------------- + +For proxy coupling, ``mass_scale`` changes a source body's effective mass and +inertia in the destination view; it does not change the authored rigid-body +mass. Start at ``1`` and increase it only when the rigid solver strongly +constrains the body during MPM contact. Check both supported and freely moving +cases, since a large scale can suppress legitimate motion. + +The G1 recordings show one policy walking across sand, snow, and clay. The +one-way recording uses lower-leg proxies, while the two-way recording uses +full-body proxies. They are presentation examples, **not** a controlled +single-variable comparison; keep the policy, seed, commands, and proxy geometry +identical when measuring a coupling effect. + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: One-way, lower-leg proxies + + .. raw:: html + + + + .. grid-item-card:: Two-way, full-body proxies + + .. raw:: html + + + + Start from a maintained task ---------------------------- diff --git a/docs/source/concepts/solver-tuning/index.rst b/docs/source/concepts/solver-tuning/index.rst index dcd195a72380..a128f3399307 100644 --- a/docs/source/concepts/solver-tuning/index.rst +++ b/docs/source/concepts/solver-tuning/index.rst @@ -20,3 +20,4 @@ and defaults remain in the generated API reference. tune_mjwarp tune_kamino tune_vbd + tune_mpm diff --git a/docs/source/concepts/solver-tuning/tune_mpm.rst b/docs/source/concepts/solver-tuning/tune_mpm.rst new file mode 100644 index 000000000000..afc21b5ead26 --- /dev/null +++ b/docs/source/concepts/solver-tuning/tune_mpm.rst @@ -0,0 +1,278 @@ +.. Copyright (c) 2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +.. All rights reserved. +.. +.. SPDX-License-Identifier: BSD-3-Clause + +.. _newton-tuning-mpm: + +MPM Solver +========== + +Start with :ref:`newton-using-mpm` for scene construction. These experiments +help separate numerical accuracy from constitutive response. They are +qualitative examples, not calibrated material models or performance benchmarks. + +Tune Resolution, Time, Then Convergence +--------------------------------------- + +Tune one group at a time in this order: + +1. **Voxel and particle resolution.** ``MPMSolverCfg.voxel_size`` controls the + background grid. Smaller voxels resolve thinner geometry but increase active + cells and memory. ``MPMGridCfg.particles_per_cell`` controls particle density; + doubling it along each axis creates about eight times as many particles in + 3D. Start coarse, then refine until the measured behavior stops changing. +2. **Timestep and substeps.** Each Newton substep uses + ``SimulationCfg.dt / NewtonCfg.num_substeps``. Reduce ``dt`` or increase + ``num_substeps`` first when contacts tunnel, jitter, or become unstable. + Substeps do not change the policy period, which also includes environment + decimation. +3. **Iterations and tolerance.** ``MPMSolverCfg.max_iterations`` caps the + rheology solve; ``tolerance`` permits an earlier exit after convergence. + Increase the cap only when the solver reaches it, and lower the tolerance + only when tighter convergence improves a physical metric. These settings do + not repair an unstable timestep, invalid reset, or incorrect collider. + + +Material Comparisons +-------------------- + +The recordings below hold the scene and solver configuration fixed within +each comparison while varying one material parameter. The annotated values +are examples for observing different responses, not calibrated material +recommendations. + +.. list-table:: Values shown in the material recordings + :header-rows: 1 + :widths: 21 35 44 + + * - Preset + - Varied values + - Behavior to inspect + * - ``young_modulus`` + - 100 kPa, 300 kPa, 1 MPa + - Compression, recovery, and impact rebound + * - ``poisson_ratio`` + - 0.05, 0.30, 0.499 + - Volume loss versus near-incompressibility + * - ``friction`` + - 0, 0.68, 2.0 + - Runout and the final angle of repose + * - ``tensile_yield_ratio`` + - 0, 0.01, 0.05 + - Fragmentation versus tensile cohesion + * - ``yield_pressure`` + - 100 kPa, 1 MPa, 4 MPa + - Onset and amount of irreversible compression + * - ``hardening`` + - 0, 0.05, 5.0 + - Strength gained after plastic compaction + * - ``dilatancy`` + - 0, 0.1, 1.0 + - Compaction versus expansion under shear + * - ``yield_stress`` + - 0, 10 kPa, 20 kPa + - Cohesive flow and retained shape + * - ``viscosity`` + - 0, 10 Pa·s, 500 Pa·s + - Rate-dependent plastic flow + * - ``particle_jitter`` + - 0%, 30% of particle spacing + - Grid-alignment artifacts and packing symmetry + + +Design a Useful Parameter Study +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use these practices when designing a comparison: + +* Change one physical quantity at a time. Use the same generated positions, + particle mass, collider, timestep, and camera for every variant. +* Choose values that bracket visibly different regimes. Geometric spacing is + usually more informative than small linear increments for stiffness, yield, + viscosity, and coupling mass scales. +* Preserve the feature the comparison is meant to explain. If a soft elastic + specimen loses its silhouette before rebound can be read, reduce the impact + energy or raise the lower end of the stiffness range. Do not shorten a clip + merely to hide later breakup. +* Use deterministic jitter for constitutive comparisons so lattice alignment + does not dominate the motion. Keep the no-jitter case as a separate packing + diagnostic. +* Run until impact, peak deformation, recovery or flow, and the final settled + state are all visible. A short clip can make different materials appear + identical. +* Tune numerical resolution and timestep before interpreting material values. + Record the voxel size, particles per voxel axis, particle count, physics + timestep, substeps, iterations, tolerance, random seed, and code revision. +* Check a quantitative signal alongside the video when possible: center of + mass, runout distance, rebound height, retained volume, or settled height. + +``particles_per_cell`` is the number of particles along one voxel axis. A value +of ``2`` therefore produces approximately eight particles per filled voxel in +3D, not two. Refining both voxel size and particle density can increase memory +and runtime rapidly. + + +Interpret the Comparisons +------------------------- + +* **Elastic response:** Poisson's ratio changes both bulk and shear moduli at + fixed Young's modulus. Values close to 0.5 approach incompressibility; this + is not an independent sweep of volume stiffness. The recording uses 50 kPa + Young's modulus and a gentler drop so the impact produces visible strain + without obscuring the comparison through loss of the specimen silhouette. +* **Plastic response:** yielding, hardening, friction, and dilatancy interact. + Keep the other fields fixed within a preset, not necessarily between presets. + A high-friction label is not a water-content model; these sand, snow, and + clay labels describe illustrative responses rather than measured materials. +* **Nearly rigid MPM:** high stiffness and yield limits suppress intended strain + and plastic flow but do not impose rigid-body constraints. Residual shape + drift, contact differences, and particle sampling error can remain. Compare + silhouettes and mass as well as motion; increase resolution only after + checking timestep and convergence. Higher particle density is more + expensive than a coarse comparison. + + +Example Recordings +------------------ + +Recordings are hosted outside Git on the Isaac Lab documentation media host, +following the other deformable tuning examples. + +Material Response +~~~~~~~~~~~~~~~~~ + +The selected material clips were recorded in Kit at 1920 × 1080. Their +annotations belong to those recordings; do not treat video duration as +simulation time. + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: Elastic stiffness + + .. raw:: html + + + + Plate compression at 100 kPa, 300 kPa, and 1 MPa. + + + .. grid-item-card:: Compressibility + + .. raw:: html + + + + Plate compression at Poisson ratios 0.05, 0.30, and 0.499 with E = 50 kPa. + + + .. grid-item-card:: Granular friction + + .. raw:: html + + + + Runout for internal friction 0, 0.68, and 2.0; cohesion is unchanged. + + + .. grid-item-card:: Tensile cohesion + + .. raw:: html + + + + Tensile yield ratios 0, 0.01, and 0.05. + + + .. grid-item-card:: Pressure yielding + + .. raw:: html + + + + Stronger impact reveals compression at 100 kPa, 1 MPa, and 4 MPa. + + + .. grid-item-card:: Plastic hardening + + .. raw:: html + + + + Fixed strength (0) versus slow (0.05) and rapid (5) strength buildup. + + + .. grid-item-card:: Shear dilatancy + + .. raw:: html + + + + Spreading and packing for dilatancy 0, 0.1, and 1. + + + .. grid-item-card:: Cohesive yield stress + + .. raw:: html + + + + Retained shape at 0, 10 kPa, and 20 kPa. + + + .. grid-item-card:: Plastic viscosity + + .. raw:: html + + + + Rate of plastic flow at 0, 10 Pa·s, and 500 Pa·s. + + + .. grid-item-card:: Initial packing + + .. raw:: html + + + + Aligned sampling versus deterministic 30% particle-spacing jitter. + + +Nearly Rigid Limit +~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 + :gutter: 2 + + .. grid-item-card:: Nearly rigid MPM versus MJWarp + + .. raw:: html + + + + Inspect matched colored primitives rolling down separated inclines. This + older presentation recording is not an accuracy claim for the current + implementation; high stiffness does not enforce rigid shape constraints. diff --git a/docs/source/concepts/using_mpm.rst b/docs/source/concepts/using_mpm.rst index 3c38a8d37b67..b6c9e59dc22e 100644 --- a/docs/source/concepts/using_mpm.rst +++ b/docs/source/concepts/using_mpm.rst @@ -5,9 +5,69 @@ Using Implicit MPM Newton's implicit Material Point Method (MPM) solver models particle materials such as granular media. MPM support and rigid-MPM coupling are experimental. -Start with the compact ``mpm-granular`` example; the ``snowball-smash`` and ``teapot-fill`` demos provide polished -coupling and cavity-sampling showcases. +Start with the compact ``mpm-granular`` example; the ``snowball-smash`` and +``teapot-fill`` demos provide polished coupling and cavity-sampling showcases. +The launcher uses ``cuda:0`` by default. Pass ``--device cuda:N`` to select a +different GPU. + + +Explore MPM Scenes +------------------ + +These examples and demos introduce MPM construction and interaction before any +parameter study. They default to Newton GL for interactive viewing: + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: Granular drop + + .. raw:: html + + + + .. code-block:: bash + + uv run isaaclab example mpm-granular + + .. grid-item-card:: Two-way sphere pit + + .. raw:: html + + + + .. code-block:: bash + + uv run isaaclab example mpm-two-way-coupling + + .. grid-item-card:: Snowball smash + + .. raw:: html + + + + .. code-block:: bash + + uv run isaaclab demo snowball-smash + + .. grid-item-card:: Teapot fill + + .. raw:: html + + + + .. code-block:: bash + + uv run isaaclab demo teapot-fill --fluid_render_mode particles .. _franka-pour-reset-artifact: @@ -22,7 +82,7 @@ training needs no artifact setup: .. code-block:: bash uv run isaaclab train --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ - --num_envs 2048 --device cuda:0 + --num_envs 2048 The checked-in generator remains the executable reference for reproducing or customizing the distribution. It takes about two minutes on an L40S-class GPU @@ -30,9 +90,9 @@ and writes a local artifact that can be selected explicitly: .. code-block:: bash - uv run python scripts/tools/generate_franka_pour_reset_dataset.py --device cuda:0 + uv run python scripts/tools/generate_franka_pour_reset_dataset.py uv run isaaclab train --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ - --num_envs 2048 --device cuda:0 \ + --num_envs 2048 \ env.reset_dataset_path=datasets/franka_pour/reset_dataset.pt The task validates the payload's stored content digest automatically. Setting @@ -51,8 +111,8 @@ callback or particle override is required: .. code-block:: bash - uv run isaaclab play --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ - --checkpoint /path/to/model.pt --num_envs 1 --device cuda:0 --visualizer kit + uv run --extra isaacsim isaaclab play --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ + --checkpoint /path/to/model.pt --num_envs 1 --visualizer kit Minimal Setup @@ -116,35 +176,48 @@ USD clones share the same local particle distribution. Use reset events or domai randomization when each environment needs an independent distribution. +Controlled material experiments, comparison demos, and practical solver advice +are collected in :ref:`newton-tuning-mpm`. + + Render a Particle Surface ------------------------- MPM simulation state remains a set of particles. Surface reconstruction is an optional visualization pass: it does not change particle motion, collisions, or -material behavior. Run the teapot example to compare the available modes: +material behavior. Run the teapot demo to compare the available modes: .. code-block:: bash - # Reconstructed surface (default) - uv run isaaclab demo teapot-fill --device cuda:0 \ + # Reconstructed surface + uv run isaaclab demo teapot-fill \ --visualizer newton_gl --fluid_render_mode surface # Surface and source particles together - uv run isaaclab demo teapot-fill --device cuda:0 \ + uv run isaaclab demo teapot-fill \ --visualizer newton_gl --fluid_render_mode both # Path-traced translucent surface - uv run --extra ovrtx isaaclab demo teapot-fill --device cuda:0 \ + uv run --extra ovrtx isaaclab demo teapot-fill \ --visualizer newton_rtx --fluid_render_mode surface +The teapot demo defaults to the reconstructed surface. Select ``particles`` or +``both`` to inspect the source MPM state in Newton GL or Newton RTX. + Surface rendering is available in the Newton GL and Newton RTX visualizers. The Kit visualizer continues to render the MPM particles directly. -To reconstruct a surface in another Newton MPM script, create one reusable -``newton.geometry.ParticleSurface`` after ``sim.reset()``. On each render update, -extract from the current Newton particle positions, radii, flags, and world indices, -then pass the returned vertex, triangle-index, and normal arrays to -``NewtonGLVisualizer.log_mesh()`` or ``NewtonRTXVisualizer.log_mesh()`` with -``dynamic=True`` before calling ``sim.render()``. The visualizer stages the latest -mesh by name and submits it inside Newton's required viewer-frame lifecycle. +.. raw:: html + + + +This recording demonstrates rendering appearance, not a different +constitutive model. + +The teapot demo configures ``newton.geometry.ParticleSurface`` after +``sim.reset()`` and updates the mesh before ``sim.render()``. Its renderer +captures extraction on CUDA when enabled and stages the dynamic mesh inside +the viewer's frame lifecycle. Tune reconstruction independently from the simulation: @@ -157,10 +230,10 @@ Tune reconstruction independently from the simulation: * Anisotropic kernels preserve sheets and stretched fluid features better, but cost more than isotropic kernels. -The demo handles CUDA graph capture, empty surfaces, inactive particles, and -dynamic topology in one reusable helper: +The teapot demo handles CUDA graph capture, empty surfaces, inactive particles, +and dynamic topology: -.. dropdown:: ``FluidSurfaceRenderer`` implementation +.. dropdown:: Teapot surface renderer implementation :icon: code .. literalinclude:: ../../../examples/demos/teapot_fill.py @@ -168,51 +241,9 @@ dynamic topology in one reusable helper: :pyobject: FluidSurfaceRenderer -Tune Resolution, Time, Then Convergence ---------------------------------------- - -Tune one group at a time in this order: - -1. **Voxel and particle resolution.** ``MPMSolverCfg.voxel_size`` controls the - background grid. Smaller voxels resolve thinner geometry but increase active - cells and memory. ``MPMGridCfg.particles_per_cell`` controls particle density; - doubling it along each axis creates about eight times as many particles in - 3D. Start coarse, then refine until the measured behavior stops changing. -2. **Timestep and substeps.** Each Newton substep uses - ``SimulationCfg.dt / NewtonCfg.num_substeps``. Reduce ``dt`` or increase - ``num_substeps`` first when contacts tunnel, jitter, or become unstable. - Substeps do not change the policy period, which also includes environment - decimation. -3. **Iterations and tolerance.** ``MPMSolverCfg.max_iterations`` caps the - rheology solve; ``tolerance`` permits an earlier exit after convergence. - Increase the cap only when the solver reaches it, and lower the tolerance - only when tighter convergence improves a physical metric. These settings do - not repair an unstable timestep, invalid reset, or incorrect collider. - - -Tune Rigid-MPM Coupling ------------------------ - -For :class:`~isaaclab_contrib.coupling.CouplerProxyCfg`, first stabilize each -solver alone. Then tune the additional controls: - -* ``CouplerEntryCfg.substeps`` divides one coupled step for that entry. Increase - the MPM entry's value when only the particle solve needs a smaller timestep. -* ``CouplerProxyCfg.iterations`` repeats the proxy exchange and relaxation; it - does not replace smaller physical timesteps. -* ``CouplerProxyMappingCfg.mass_scale`` scales the source body's effective mass - and inertia only in the destination proxy view. It does not change the body's - authored mass in the rigid solver. - -Start ``mass_scale`` at ``1`` for a freely moving collider. Increase it when the -rigid solver strongly constrains the collider during MPM contact. For example, a -cup resting on a table has much greater effective resistance in the supported -direction than its free-body mass suggests. Sweep finite values geometrically, -such as ``1``, ``10``, and ``100``, and keep the smallest value that prevents -unrealistic proxy motion. Newton requires a finite positive value: do not use -infinity. An excessively large scalar also suppresses legitimate motion in -unsupported directions and can make the interaction effectively one-way. - -Validate both the supported and free-moving cases after changing coupling. If -the uncoupled systems are unstable, fix their timestep, contacts, and reset -states before adjusting ``mass_scale`` or coupling iterations. +Next Steps +---------- + +See :ref:`newton-tuning-mpm` for resolution and convergence tuning, controlled +material comparisons, and the nearly rigid MPM limit. See +:ref:`newton-coupled-solvers` for rigid--MPM coupling. diff --git a/docs/source/setup/demos.rst b/docs/source/setup/demos.rst index ae4c7a9c1558..a8992dc13d8e 100644 --- a/docs/source/setup/demos.rst +++ b/docs/source/setup/demos.rst @@ -27,6 +27,8 @@ For example, run ``uvx isaaclab demo zoo --viz newton_gl`` to explore the catalo Programs whose required modules are unavailable, hardware-dependent teleoperation, and Kit-only demos are not shown. +For particle-material comparisons and solver guidance, see :ref:`newton-tuning-mpm`. + Command Builder ---------------