Use MJVBD V2 as the default Newton solver

[MahooX]

Description

Make MJVBD V2 the default Newton solver and adapt EmbodiChain's rigid-body/articulation interfaces, state lifecycle, and existing examples. MuJoCo owns articulations; VBD owns free rigid bodies. Cloth and soft bodies are outside this PR's scope.

This remains a draft integration, not a behavior-preserving replacement for existing manipulation control. The main blocker is missing contact reaction from VBD objects back to articulations, not simply unfinished demo tuning.

Control and contact compatibility

• Position-driven grasping changes fundamentally. With two-way contact, an over-closing gripper target creates sustained clamping force while the object prevents the fingers from reaching the target. In V2's one-way coupling, the object cannot oppose articulation motion: fingers can keep closing into it, leaving VBD to resolve incompatible contact constraints by moving or rotating the object. Object-specific target calibration can recover selected grasps, but friction, iterations, and smaller timesteps cannot restore the missing reaction path. Preserving the original contact-driven control behavior requires two-way dynamics for these interactions; contact-aware stopping would instead be a controller change.
• Scene composition changes the contact route. The native mixed branch disables MuJoCo contacts and does not return VBD reaction forces. Adding a free rigid body can therefore remove articulation ground support. Later local validation enables MuJoCo-Warp contacts for the compact articulation/static model alongside Newton collision for VBD. This uses two collision pipelines, departs from the native mixed contact configuration, and does not restore object-to-robot reaction. A Newton-only collision path feeding articulation contacts into MuJoCo is not connected; V2 rejects use_mujoco_contacts=False.
• Identical parameter names do not imply identical physics. Margin handling and friction models differ; VBD does not consume separate torsional/rolling friction coefficients in the current rigid contact path. Legacy rigid-body damping fields are not effective Newton damping controls, whereas joint-drive damping is effective. These differences must be distinguished from the missing feedback mechanism.
• Contact observation is not unified. Pure MuJoCo contact geometry and impulses are adapted and numerically checked. Mixed queries do not merge both solvers into an equivalent force interface; placeholder zeros are not measured zero forces. get_qf() also does not expose actual PD actuator output in the existing Newton path. Querying a force would not itself apply it back to the robot.
• Collision cost and capacity matter. VBD contact capacity is separate from MuJoCo capacity; overflow can omit constraints. In one warmed-up, headless dual-arm scene at equal substeps, V2 stepping took about 3.8 times as long as old MuJoCo, dominated by Newton convex narrow-phase collision. This is not a universal performance ratio, and reducing substeps requires renewed physical validation.

The concise integration issue record documents evidence, boundaries, and remaining issues. Asset-frame mismatches, initial penetration, and robot/table path conflicts also affected comparisons; not every task failure is caused by one-way coupling.

Implementation scope

• Accept V2 aliases, preserve explicit automatic selection, and avoid an additional EmbodiChain-owned collision pipeline; V2 owns its internal collision routing.
• Reuse MuJoCo articulation presets and adapt child-solver access, mimic indices, target modes, reset, and state ownership.
• Repair example initialization, trajectory timing, obstacle geometry, and lifecycle issues; retain scoped manipulation candidates without claiming generic grasp compatibility.
• Align Slide damping between Default and Newton using the same effective joint-drive configuration.

Dependencies and reproducibility

The pushed DexSim compatibility base is MJVBDV2 commit f7d60c2a2b4ec9f2de7cd9d9abac973f74b0bfb8 (MR !1345). It includes compact index mapping, state-ownership fixes, teleport/warmup history synchronization, reset, and same-name asset replacement.

Later local results additionally depend on two uncommitted, unpushed DexSim code patches: enabling native MuJoCo contacts in mixed mode and correcting single-convex mesh import coordinates. They are installed locally but are not part of this GitHub PR or the pushed DexSim base. Checking out those two repositories at their published heads is insufficient to reproduce all later results. Dependency version pins are unchanged; no dependency package release is claimed.

The mixed dual-pipeline approach remains an experimental dependency, not a settled architecture. The local CoordinatedPlacement reduction from 20 to 5 substeps is awaiting full validation and is not included in this documentation update.

Validation

What the results establish

• Pure-articulation ANYmal-C on static ground/platforms has fixed-action and closed-loop policy comparisons, contact checks, and partial/full reset coverage. Normal fixed-action differences were about 1.1e-6 rad for joint positions and 0.015 N for foot normal force, comparable to old MuJoCo repeat variation. Mixed ground-support results rely on the additional contact-enabling patch; they do not qualify the native mixed branch. PPO training convergence, production reward/done behavior, and complex terrain are unverified.
• Several adapted manipulation entries complete their tasks, but orientation, loaded grasping, release behavior, and repeatability remain unresolved across the task set. Successful calibration is not evidence that unchanged control commands are compatible. Slide's latest Default/Newton behavior was accepted by the requester.
• Historical execution coverage includes 15 atomic skill IDs through 18 tutorials and 26 additional Newton-capable entries. This is coverage, not a pass count: the full set was not rerun after every patch, and it does not cover all robots, initial conditions, or planners. Twist is deferred. NeuralPlanner assets, generic rigid constraints, and complete Newton USD physics export remain gaps.

Checks

For this documentation update: black ., python docs/scripts/check_api_docs.py, and git diff --check. No runtime behavior is changed by this commit; previous physical experiments were not rerun for the prose rewrite.

Earlier focused validation included 191 passing checks with 1 skip for configuration/context, 5 replacement tests, and 84 DexSim adapter/runtime/batch tests. The recent tutorial-helper check passed 105 existing tests; that working-tree check also included the local substep override, so it is not a runtime qualification of the committed PR. No new test cases or benchmark files were added at the requester's direction. Full local CI was not reproduced; remote CI determines its current status.

Type of change

• Enhancement
• Bug fix
• Breaking change: Newton's default solver and contact/control behavior change.
• Documentation update

Checklist

• Run black ..
• Document integration mechanisms, limitations, and validation scope.
• Public API documentation coverage passes.
• New tests: intentionally not added at the requester's direction; existing checks and runtime entries were used.
• Full dependency reproducibility: the compatibility base is pushed, but two later local DexSim patches and a published dependency package remain outstanding.
• General manipulation control compatibility and complete training validation.