Add internal ADMM collision capacity controls

[rebeccazhang0707]

Description

Dense cross-solver contacts can exhaust ADMM's internal triangle-pair and contact-reduction buffers even when the outer Newton collision pipeline has sufficient capacity. Expose CouplerAdmmCfg.contact_max_triangle_pairs and contact_reduction_hashtable_size_factor so tasks can size those internal buffers independently. Both default to None, preserving existing allocations.

Validate the supplied capacities and rebuild the pinned Newton 1.6 internal pipeline before stepping, preserving pair filters, output capacities, and contact matching. This adapter uses Newton's private internal pipeline because the current ADMM constructor has no capacity hook. Document the matching-enabled triangle-pair limit and how to grow the hashtable independently.

Extracted the general interface from the shoelace task branch; environment-count scaling and task/training changes remain outside this PR. No new dependencies.

Validation

• uv run --extra test python -m pytest -q source/isaaclab_contrib/test/coupling/test_coupler.py source/isaaclab_contrib/test/coupling/test_coupler_runtime.py — 66 passed with Newton 1.6.0. CPU runtime coverage constructs, resets, and steps real proxy/ADMM solvers, including mesh contact, resized buffers, and preserved contact matching.
• Regression check: all 6 new capacity cases fail against unchanged develop and pass with this change.
• uv run --isolated --extra dev -- make -C docs current-docs — warning-free build.
• uv run isaaclab -f and the changelog gate — passed. ISAACLAB_CHANGELOG_BASE_REF=upstream-develop-pr-base points the local hook at the fetched upstream develop base instead of 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: 4/5

This PR is not safe to merge until configurations that combine rigid contact matching with contact_max_triangle_pairs >= 2**20 are rejected before constructing the Newton pipeline.

Findings

1.  Matching limit is unenforced ▶

Summary

This PR adds independent capacity controls for ADMM’s internal collision pipeline, validates the new settings, rebuilds the pinned Newton pipeline while preserving key state, and documents and tests the resulting behavior.

• Adds triangle-pair and contact-reduction hashtable capacity fields to CouplerAdmmCfg.
• Reconstructs ADMM’s internal collision pipeline when either capacity override is supplied.
• Adds configuration and real-solver runtime coverage, including mesh contacts and contact matching.
• Documents capacity sizing, multi-rank allocation, and Newton’s matching-dependent triangle-pair limit.
• The matching-dependent upper limit is documented but not enforced by configuration validation.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Config[CouplerAdmmCfg] --> Validate[Validate capacity values]
  Validate --> ADMM[Construct SolverCoupledADMM]
  ADMM --> Existing[Read existing internal pipeline]
  Existing --> Rebuild[Rebuild CollisionPipeline with capacity overrides]
  Rebuild --> Contacts[Replace internal contacts]
  Contacts --> Step[Reset and step solver]

Loading

_{Reviews (1) · Last reviewed commit: "Add internal ADMM collision capacity con..."}

[greptile-apps]

Matching limit is unenforced

When rigid contact matching is enabled, contact_max_triangle_pairs values at or above 2**20 pass this positive-only validation and are forwarded to the rebuilt pipeline. Newton 1.6 requires the capacity to remain below that limit for deterministic contact packing, so this configuration can fail during solver construction or stepping instead of being rejected here. Please validate the matching-dependent upper bound along with the existing positivity check.

[isaaclab-review-bot]

Isaac Lab Review Bot

Adds opt-in ADMM collision-capacity controls with validation, documentation, changelog coverage, and runtime tests. One documented backend constraint is not enforced before constructing the replacement pipeline.

• Design and architecture: Rebuilding Newton 1.6's private ADMM collision pipeline before stepping and graph capture is a proportionate adapter while no public capacity hook exists, though it intentionally couples the implementation to pinned private attributes.
• API: The new fields default to None and preserve the existing API path, but contact_max_triangle_pairs accepts values at or above 2**20 even when rigid contact matching is enabled, despite the public documentation stating that this combination is unsupported.
• Implementation: The rebuild refreshes the solver's internal contacts and carries forward filters, output capacities, and matching settings. Add conditional validation rejecting triangle-pair capacities at or above 2**20 when rigid contact matching is enabled, while retaining larger capacities for matching-disabled configurations.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🔵 Suggestion · Api — Matching triangle-pair limit is unenforced

The new field documentation states Newton 1.6 requires the triangle-pair capacity to stay below 2**20 when rigid contact matching is enabled, but _validate_config accepts any positive integer. A configuration that this package documents as unsupported passes validation and is forwarded to the rebuilt pipeline. Consider rejecting capacities at or above that limit when rigid_contact_matching is enabled, while allowing larger values otherwise.