Skip to content

[Docs] Unify volume, surface, and cable deformables into one guide - #7576

Draft
mmichelis wants to merge 2 commits into
isaac-sim:developfrom
mmichelis:docs/unify-deformables
Draft

[Docs] Unify volume, surface, and cable deformables into one guide#7576
mmichelis wants to merge 2 commits into
isaac-sim:developfrom
mmichelis:docs/unify-deformables

Conversation

@mmichelis

Copy link
Copy Markdown
Collaborator

Description

Deformable documentation is currently split by solver rather than by concept. Volume and surface deformables are documented inside the Newton VBD solver guide, cables have their own page under the Newton backend, and the only crisp definition of the volume/surface split lives in the 3.0 migration guide. A reader asking "what is a deformable in Isaac Lab, and how do I author one" has no single place to look.

This adds a single Core Concepts > Deformables page covering the three kinds at the asset level:

  • what each kind is and how it is discretized, plus a backend support matrix
  • authoring volume, surface, and cable assets, including from pre-authored USD
  • how volume vs surface is resolved from the physics material, both at author time and at initialization
  • tetrahedralization, and exactly which paths need the optional extra
  • nodal runtime state, root position semantics, and kinematic targets
  • cable material parameters, collision, runtime state, rendering, and limitations
  • seven side-by-side animations, each sweeping one material parameter across three values

Solver configuration, tuning, and coupling deliberately stay where they are. The new page links to the Newton VBD solver guide and the coupled solvers page rather than restating them, and using-vbd-solver.rst is unchanged. MPM is explicitly out of scope and cross-linked so readers are not left guessing.

using-cables.rst is reduced to a pointer, keeping its newton-using-cables label so existing references still resolve. The Newton index, the showroom, and the Newton asset preparation skill are repointed at the new guide.

Corrections to inherited content

Two errors in the existing cable material documentation surfaced while verifying the text against the importer, and are fixed here:

  • Stiffness is discretized per rod joint using that joint's dual rest length 0.5 * (L_parent + L_child), not once for the whole cable from the mean segment length. The "uniform point spacing assumed" caveat and its associated warning were therefore incorrect and have been removed.
  • The twist fallback reuses the bend structural stiffness E * I / L, whereas an explicitly authored twist_stiffness is applied to the polar moment J = 2 * I. Setting twist_stiffness = bend_stiffness gives twice the fallback stiffness, not the same value. This asymmetry with the shear fallback is now documented.

Note on the media

The animations are added as a separate commit so they can be dropped or swapped for externally hosted files without touching the prose. They are GIFs, routed through Git LFS by the existing *.gif rule, so history stores 132-byte pointers rather than binaries. Re-encoded mp4s of the same clips come to 644 KB total against 13 MB of GIF, so I am happy to switch if reviewers prefer.

Type of change

  • Documentation update

Release backport

  • Backport this pull request to the active release branch after it merges into develop

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have added a changelog fragment under source/<pkg>/changelog.d/ for every touched package (do not edit CHANGELOG.rst or bump extension.toml — CI handles that)
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

Notes on the two unchecked items: this change touches only docs/ and skills/, so there is no source package to add a changelog fragment for and nothing to unit test. sphinx-build succeeds on the branch with one warning, a pre-existing duplicate RigidBodyMaterialCfg autoclass shared between isaaclab.sim.spawners.rst and isaaclab_physx.sim.spawners.rst, both untouched here.

Deformable documentation was split by solver rather than by concept. Volume and
surface deformables were documented inside the Newton VBD solver guide, cables
had their own Newton backend page, and the only crisp definition of the volume
and surface split lived in the 3.0 migration guide.

Add a single Core Concepts > Deformables page covering the three kinds at the
asset level: what each one is, how it is authored, how volume and surface are
resolved from the physics material, tetrahedralization, runtime state, kinematic
targets, and the cable material, collision, and rendering contracts.

Solver configuration, tuning, and coupling stay in the Newton VBD solver guide
and the coupled solvers page, which the new page links to instead of restating.

Reduce the cable page to a pointer, keeping its label so existing references
resolve, and repoint the Newton index, the showroom, and the Newton asset
preparation skill at the new guide.

Also correct two inherited errors in the cable material documentation. Stiffness
is discretized per rod joint using that joint's dual rest length rather than once
for the whole cable from the mean segment length, so the uniform point spacing
caveat no longer applies. The twist fallback reuses the bend structural stiffness
rather than the bend modulus, so setting twist_stiffness equal to bend_stiffness
gives twice the fallback value.
Add the seven side-by-side animations referenced by the deformables guide, one
per material parameter, each sweeping three values with everything else held
fixed: Young's modulus, Poisson's ratio, and particle radius for volume, stretch
and bend stiffness for surface, and bend and twist stiffness for cables.

Kept as a separate commit so the media can be dropped or replaced with externally
hosted files without touching the prose.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant