Move standalone VBD support into Newton core

[mmichelis]

Description

Moves the standalone Newton VBD solver configuration and manager from isaaclab_contrib.deformable into isaaclab_newton.physics. The core VBD API can now be imported without isaaclab_contrib. When the contrib deformable integration is installed, NewtonVBDManager uses its registered deformable builder hook and Fabric synchronization.

• Adds core NewtonVBDManager, VBDSolverCfg, and NewtonSoftContactCfg.
• Moves global soft-contact parameters from the nested solver_cfg.model_cfg to NewtonCfg.soft_contact_cfg.
• Removes the contrib NewtonModelCfg, NewtonModelSolverCfg, VBDSolverCfg, and NewtonVBDManager symbols. Import the standalone VBD types from isaaclab_newton.physics instead.
• Keeps coupled solvers and deformable object integration in contrib. Custom coupling now imports the VBD manager and configuration from core.
• Keeps deformable USD exclusions localized in the core VBD manager without changing the generic Newton manager importer API.
• Migrates the launcher, examples, tutorials, and Franka soft-body task presets to the core API.
• Updates API, migration, deformable, and VBD usage documentation.
• Adds focused core API, VBD USD exclusion, BVH, manager abstraction, launcher, and contrib consumer tests.
• Adds changelog fragments for all four touched packages.

No new external dependencies are required.

The removed symbols are experimental contrib APIs. This change intentionally does not retain compatibility aliases at the old import paths.

Migration

Import the standalone VBD types from isaaclab_newton.physics:

from isaaclab_newton.physics import NewtonCfg, NewtonSoftContactCfg, VBDSolverCfg

physics_cfg = NewtonCfg(
    solver_cfg=VBDSolverCfg(iterations=10),
    soft_contact_cfg=NewtonSoftContactCfg(soft_contact_kd=0.01),  # preserve the previous contrib default
)

Global soft-contact parameters move from solver_cfg.model_cfg to the outer NewtonCfg.soft_contact_cfg. NewtonSoftContactCfg.soft_contact_kd defaults to Newton's 10.0; set it explicitly if you relied on the previous contrib default of 0.01.

Type of change

• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Validation

• 5 core VBD tests passed.
• 5 VBD manager abstraction tests passed.
• 64 contrib deformable and coupling consumer tests passed.
• 1 launcher VBD configuration test passed.
• 39 Newton cloner tests passed against the latest develop changes.
• All modified packages passed changelog-fragment validation.
• The full documentation build completed without warnings or errors.
• All repository pre-commit hooks passed.

Pytest warnings were limited to third-party PyTorch deprecation warnings and existing Newton warnings.

Checklist

• I have read and understood the contribution guidelines.
• I have run the pre-commit checks with ./isaaclab.sh -f.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have added tests that prove the feature works.
• I have added a changelog fragment for every touched package.
• My name already exists in CONTRIBUTORS.md.

[greptile-apps]

Greptile Summary

The PR moves standalone VBD configuration and manager support from isaaclab_contrib into isaaclab_newton.physics, while retaining optional contrib deformable hooks and synchronization.

• Adds the core VBD manager, solver configuration, and outer Newton soft-contact configuration.
• Migrates launcher, task, coupling, demo, test, and documentation consumers to the new API.
• Removes the intentionally unsupported experimental contrib import paths.

Confidence Score: 5/5

The PR appears safe to merge; no concrete changed-code failure remains after checking the VBD lifecycle, replication, optional contrib integration, and configuration migration.

The migrated contact settings remain attached to the outer Newton configuration, optional contrib integration is isolated behind guarded imports, and the new VBD replication path preserves per-world transforms, hooks, sites, and deformable exclusions.

Important Files Changed

Filename	Overview
source/isaaclab_newton/isaaclab_newton/physics/vbd_manager.py	Adds the core VBD lifecycle, USD import and replication path, optional contrib hooks, solver construction, and per-step BVH rebuilding without an identified regression.
source/isaaclab_newton/isaaclab_newton/physics/newton_manager_cfg.py	Adds outer model-global soft-contact configuration to NewtonCfg while preserving native Newton defaults when unset.
source/isaaclab_newton/isaaclab_newton/physics/newton_manager.py	Applies explicitly configured soft-contact parameters to the finalized Newton model.
source/isaaclab_newton/isaaclab_newton/physics/vbd_manager_cfg.py	Introduces the core VBD solver configuration with the fields previously supplied by contrib.
source/isaaclab_contrib/isaaclab_contrib/coupling/coupler.py	Migrates coupling to the core VBD manager and removes obsolete nested model-configuration validation.
source/isaaclab_contrib/isaaclab_contrib/custom_coupling/franka_soft_env_cfg.py	Migrates custom coupling to core VBD configuration while preserving the outer soft-contact configuration inherited from the core preset.
source/isaaclab_tasks/isaaclab_tasks/core/lift/config/franka_soft/franka_soft_env_cfg.py	Moves task-specific soft-contact values from the nested solver configuration to NewtonCfg without changing their values.
source/isaaclab_tasks/isaaclab_tasks/core/lift/config/franka_soft/franka_cloth_env_cfg.py	Migrates the cloth task to core VBD and outer soft-contact configuration while retaining its prior tuning.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Launcher["Launcher / task preset"] --> NewtonCfg["NewtonCfg"]
  NewtonCfg --> VBDCfg["VBDSolverCfg"]
  NewtonCfg --> ContactCfg["NewtonSoftContactCfg"]
  VBDCfg --> VBDManager["NewtonVBDManager"]
  VBDManager --> CoreBuilder["Core Newton builder and VBD solver"]
  Contrib["Optional isaaclab_contrib deformable integration"] -. registers builder and Fabric hooks .-> VBDManager
  VBDManager --> Model["Finalized Newton model"]
  ContactCfg --> Model

Loading

_{Reviews (1): Last reviewed commit: "Correct coupled VBD migration note" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The VBD manager/config relocation into isaaclab_newton.physics, outer NewtonCfg.soft_contact_cfg, and migrated launcher, coupling, task, documentation, and test paths are internally consistent. Before merge, preserve the removed contrib APIs through a deprecation cycle and document the changed damping default in the contrib migration guidance.

• Design and architecture: Moving standalone VBD ownership into Newton core while retaining deformable-object integration and coupled solvers in contrib is coherent. Hoisting global soft-contact parameters onto NewtonCfg also removes the solver-specific model-config shim cleanly.
• API: The new core exports and API documentation are wired correctly. However, the previously public contrib VBD symbols are deleted without the prior deprecation required by repository policy; forwarding aliases should remain for a release. The contrib changelog must also state that soft_contact_kd changes from 0.01 to 10.0 and explain how to preserve the old behavior.
• Implementation: The model-finalization soft-contact application, VBD stage-import exclusions and replication hooks, BVH rebuild ordering, launcher path, and migrated coupling consumers align with the new API. The required implementation change is compatibility forwarding at the old contrib import paths; the associated migration note should cover the materially changed damping default.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Api — Contrib VBD symbols removed without prior deprecation

VBDSolverCfg, NewtonModelCfg, NewtonModelSolverCfg, and vbd_manager.NewtonVBDManager were exported from isaaclab_contrib.deformable.__init__.pyi and documented via autoclass; this change deletes them so existing imports fail immediately. Repository rules require deprecating public symbols in a prior release before removal. Keep thin forwarding aliases at the old paths that emit DeprecationWarning and resolve to the core types for one release.

[isaaclab-review-bot]

🔵 Suggestion · Api — Migration note omits soft_contact_kd default change

NewtonModelCfg.soft_contact_kd defaulted to 1.0e-2 while NewtonSoftContactCfg.soft_contact_kd defaults to 10.0, so users who simply move settings to soft_contact_cfg silently get 1000x the contact damping. Changed entries must carry migration guidance; add the default-value change and the explicit soft_contact_kd=0.01 restoration note to this fragment.