Expose VBD stabilization and contact capacity for rigid cables

[rebeccazhang0707]

Description

Rigid cable tasks such as shoelace currently need a VBDSolverCfg subclass to configure shared joint/contact stabilization and per-body body-body contact capacity. Expose rigid_avbd_alpha and rigid_body_contact_buffer_size so those settings can be passed directly:

VBDSolverCfg(
    rigid_avbd_alpha=0.0,
    rigid_body_contact_buffer_size=256,
)

The defaults (None and 64) preserve the pinned Newton constructor's behavior. The existing manager already forwards both fields. The change adds two configuration fields, two tuning-guide entries, a package changelog fragment, and two parameterized test cases.

Related: #6733.

Validation

• uv run --frozen --extra test python -m pytest -q source/isaaclab_newton/test/physics/test_vbd_core.py — 10 passed with Newton 1.6.0. The two configuration cases compare real CPU solver construction with direct Newton construction for defaults and shoelace settings, including unchanged contact mode and allocated contact capacity.
• Regression check: both configuration cases fail against the configuration from the PR base and pass with the added fields.
• uv run --frozen --isolated --extra dev -- make -C docs current-docs — warning-free build.
• ISAACLAB_CHANGELOG_BASE_REF=upstream-develop-pr-base UV_FROZEN=1 uv run isaaclab -f and the changelog gate — passed. The base ref tracks upstream develop rather than the fork's older origin/develop.

Type of change

• New feature (non-breaking change which adds functionality)
• 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 uv run isaaclab -f.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings (the focused tests report existing upstream deprecation warnings; the documentation build is warning-free).
• I have added tests that prove my fix is effective or that my feature works.
• I have added a changelog fragment for every touched package.
• My name already exists in CONTRIBUTORS.md.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the new controls preserve pinned Newton defaults and are exercised against real solver construction.

Summary

This PR exposes four Newton 1.6 rigid-solver controls through VBDSolverCfg while preserving upstream defaults.

• Adds explicit selection of compliant ALM and shared rigid stabilization.
• Exposes legacy hard-contact selection and per-body body-contact capacity.
• Documents migration behavior, mode-dependent defaults, and tuning considerations.
• Adds real CPU solver-construction tests covering defaults and representative overrides.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[VBDSolverCfg] --> B[to_dict]
    B --> C[_filter_solver_kwargs]
    C --> D[Newton SolverVBD constructor]
    D --> E[Legacy rigid path]
    D --> F[Compliant ALM path]

Loading

_{Reviews (1) · Last reviewed commit: "Expose VBD rigid solver controls and com..."}

[isaaclab-review-bot]

Isaac Lab Review Bot

The PR additively exposes four Newton VBD rigid-solver controls on VBDSolverCfg, documents their migration semantics, adds the required package changelog fragment, and tests manager-created solvers against direct Newton SolverVBD construction.

• Design and architecture: The controls remain localized to the Newton-specific solver configuration and rely on the existing manager forwarding path. Using None for mode-dependent backend defaults preserves current behavior while allowing explicit compliant-ALM opt-in. Exposing the already deprecated legacy rigid_contact_hard option is a deliberate migration aid that may require later cleanup when Newton removes that mode.
• API: The public API change is additive and follows the package’s rigid_* naming and modern union-type conventions. Declared and documented defaults are consistent, existing configurations retain their behavior, and the tuning guide plus past-tense changelog fragment provide migration guidance for compliant ALM.
• Implementation: The parameterized test exercises default, legacy hard-contact, legacy penalty-contact, and compliant-ALM configurations on a real CPU model. It compares both solver attributes and body-body buffer allocation against direct SolverVBD construction, covering the existing config-to-manager forwarding path. The main residual maintenance risk is that documentation of Newton-specific mode defaults and deprecations may need updating alongside future backend versions.

No blocking issues. No inline issue met the actionable-evidence threshold; the assessment above records the review feedback.

Automated review; human maintainers own approval decisions.

[maxkra15]

• The final two-field implementation looks good. Please rebase onto the latest develop and resolve the current import conflict in test_vbd_core.py, retaining NewtonBackendCfg and SimulationContext alongside the new test imports.
• Please rerun the focused VBD tests and refresh current-head CI/reviews after the rebase.

[rebeccazhang0707]

run-ci

[maxkra15]

@mmichelis please also review

[maxkra15]

• we should expose rigid_compliant_alm: bool | None = None and set it to True in the new rigid-cable configuration; Newton 1.6 otherwise selects the deprecated legacy mode. Validate the cable stiffness and add manager-path coverage for ALM.
• rigid_avbd_alpha=0.0 does not enable ALM and is already the ALM default; remove this field if no non-default alpha is needed.

[mmichelis]

Thanks for the addition! I agree with Max, what is the reasoning of not exposing rigid_compliant_alm as well? This seems like a logical additional parameter. I would also state the Newton mode-dependent defaults for alpha explicitly here, just so that is clear as well.

[rebeccazhang0707]

Thank you for the guidance, @maxkra15.

Added rigid_compliant_alm: bool | None = None, enabled ALM in the documented cable example, and removed rigid_avbd_alpha. Added a manager-path test checking finite cable stretch against mg/k. Small cable bend/contact checks also passed at a 1/1200 s substep with 12 VBD iterations; full shoelace task tuning remains separate.

[rebeccazhang0707]

Thank you for the review, @mmichelis.

Agreed that the mode switch belongs here. Added rigid_compliant_alm and removed the unnecessary alpha override. The docs now explicitly state Newton 1.6's alpha defaults: 0.0 for compliant ALM and 0.95 for legacy AVBD.