Colision doc extension (#3755)

Author: nvtw

CHANGELOG.md

@@ -18,6 +18,7 @@
 - Add opt-in isolated multi-world implicit MPM with capacity-bounded rebuildable sparse grids, selective world resets, outer graph capture, and asynchronous overflow reporting; legacy shared topology remains the default.
 - Add `cloth_stiff_material_hanging` and `cloth_stiff_material_stretch` examples regression-guarding the new Neo-Hookean triangle material (stability under gravity at extreme stiffness, and bulk area-preservation across a Poisson-ratio sweep)
 - Add contact examples for Newton's cradle, a balance bird, and a domino spiral
+- Document geometry-pair contact behavior and clarify that MuJoCo Warp currently produces a single contact for cylinder--box pairs even with MultiCCD enabled.
 - Add `ViewerUSD(points_as_spheres=...)` to render `log_points` particles as a `UsdGeom.PointInstancer` of sphere prototypes; enabled by default (opt out with `points_as_spheres=False` for flat `UsdGeom.Points` splats)
 - Add list-of-pattern and explicit-index selectors to `ArticulationView`.
 - Add `newton[onnx]` for ONNX policy inference through Warp-NN; `ControllerNeuralMLP`, `ControllerNeuralLSTM`, and RL policy examples can run exported `.onnx` policies without requiring PyTorch for ONNX execution.

docs/concepts/collisions.rst

@@ -143,6 +143,205 @@ Examples:
 See :ref:`Solver Integration` for the full code pattern showing how to configure
 this.
 
+.. _Geometry Pair Contact Behavior:
+
+Geometry-Pair Contact Behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The two tables below describe contacts generated by Newton's
+:class:`~CollisionPipeline` only; they do not apply to contacts generated by the
+native MuJoCo CPU or MuJoCo Warp collision pipelines. The values are theoretical
+upper bounds per shape pair and collision pass before the shared
+``rigid_contact_max`` capacity is applied. Actual counts vary with pose, margin,
+and collision settings.
+
+**CollisionPipeline primitive and convex-hull pairs**
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 18 9 9 10 11 11 8 9 13
+
+   * - Shape A / Shape B
+     - Plane
+     - Sphere
+     - Capsule
+     - Ellipsoid
+     - Cylinder
+     - Box
+     - Cone
+     - Convex hull
+   * - Plane
+     - 5
+     - 1
+     - 2
+     - 1
+     - 4
+     - 4
+     - 5
+     - 5
+   * - Sphere
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+   * - Capsule
+     - 2
+     - 1
+     - 2
+     - 1
+     - 5
+     - 5
+     - 5
+     - 5
+   * - Ellipsoid
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+     - 1
+   * - Cylinder
+     - 4
+     - 1
+     - 5
+     - 1
+     - 5
+     - 5
+     - 5
+     - 5
+   * - Box
+     - 4
+     - 1
+     - 5
+     - 1
+     - 5
+     - 5
+     - 5
+     - 5
+   * - Cone
+     - 5
+     - 1
+     - 5
+     - 1
+     - 5
+     - 5
+     - 5
+     - 5
+   * - Convex hull
+     - 5
+     - 1
+     - 5
+     - 1
+     - 5
+     - 5
+     - 5
+     - 5
+
+The plane--plane upper bound is five when at least one plane is finite. Two
+infinite planes produce no contacts.
+
+**CollisionPipeline mesh, heightfield, and SDF routes**
+
+``V`` is a mesh vertex count, ``T_overlap`` is the number of overlapping
+triangles, and ``E`` is the number of collision edges. The estimated typical
+count is the sizing heuristic used for allocation, not a measured statistical
+average or a per-pair limit.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 27 18 23 12 20
+
+   * - Pair or route
+     - Reduced maximum (default)
+     - Unreduced maximum
+     - Estimated typical count
+     - Notes
+   * - Triangle mesh--infinite plane
+     - 240
+     - ``V_mesh``
+     - About 40
+     - At most one candidate per mesh vertex.
+   * - Mesh/heightfield--sphere or ellipsoid
+     - 240
+     - ``T_overlap``
+     - About 40
+     - At most one contact per overlapping triangle.
+   * - Mesh/heightfield--other primitive or convex hull
+     - 240
+     - ``5 * T_overlap``
+     - About 40
+     - Each overlapping triangle uses the convex manifold path.
+   * - Mesh--mesh
+     - 240
+     - ``E_A + E_B``
+     - About 40
+     - Uses edge-vs-SDF queries, with BVH distance fallback when needed.
+   * - Heightfield--mesh
+     - 240
+     - ``E_heightfield + E_mesh``
+     - About 40
+     - Uses the mesh/SDF route with on-the-fly heightfield evaluation.
+   * - Hydroelastic SDF--SDF
+     - 240 by default
+     - Geometry and buffer dependent
+     - No fixed estimate
+     - ``anchor_contact=True`` can add contacts beyond the reduced set.
+
+The reduced maximum follows the current 240-slot contact-reduction layout.
+Disabling reduction exposes the geometry-dependent candidate bounds shown above.
+
+**Common pair guidance**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 16 23 31 30
+
+   * - Pair
+     - Expected behavior
+     - Backend notes
+     - Asset guidance
+   * - Sphere--plane or sphere--box
+     - A point contact.
+     - Newton, MuJoCo Warp, and MuJoCo CPU use single-contact primitive paths.
+     - Use one sphere unless the asset needs a finite support patch; then use
+       multiple collision shapes or a surface-contact representation.
+   * - Capsule--plane or capsule--box
+     - End-on contact is point-like; side-on contact can span the capsule axis.
+     - Newton and both MuJoCo backends have multi-contact paths for the
+       line-like side contact.
+     - A single capsule is normally sufficient. Use a compound only when the
+       physical profile is not capsule-shaped.
+   * - Box--plane or box--box
+     - Face contact forms an area-supporting manifold; edge and corner contacts
+       use fewer points.
+     - Newton and both MuJoCo backends generate multi-point face contacts.
+     - Prefer a single box for box-like parts; it is cheaper and usually more
+       stable than a tessellated mesh.
+   * - Cylinder--box
+     - A cylinder lying across a broad box face should have a manifold spanning
+       its support region.
+     - Newton generates a convex manifold. MuJoCo CPU can generate a multi-point
+       manifold with multi-CCD enabled. MuJoCo Warp currently emits one contact
+       for this pair even with ``enable_multiccd=True``; contact location can
+       alternate between the cylinder ends. This is a known discrepancy tracked
+       in `mujoco_warp#1555
+       <https://github.com/google-deepmind/mujoco_warp/issues/1555>`__.
+     - Keep a single cylinder with Newton contacts. While the MuJoCo Warp issue
+       is open, use ``use_mujoco_contacts=False`` or, if that is not possible,
+       approximate load-bearing regions with multiple collision shapes.
+
+The MuJoCo Warp cylinder--box behavior above is a known discrepancy, not the intended
+single-contact behavior of the geometry pair. For non-convex assets, use a
+convex compound or Newton's mesh/SDF paths rather than expecting one primitive
+to reproduce the surface. See :ref:`Mesh Collisions` and :ref:`Simulation Tuning`.
+
 .. _Collision Pipeline:
 
 Collision Pipeline

docs/solvers/mujoco.rst

@@ -495,7 +495,8 @@ allows up to four contact points per geom pair instead of one. Pairs
 where either geom has non-zero MuJoCo ``geom_margin`` still fall back
 to a single contact regardless of the flag (see *Margin zeroing*
 below for how Newton's :attr:`~newton.Model.shape_margin` is forwarded
-to it).
+to it). MuJoCo Warp currently remains single-contact for cylinder--box;
+see :ref:`Geometry Pair Contact Behavior`.
 
 **Margin zeroing.** ``mujoco_warp`` rejects non-zero geom margins on
 box-box pairs (its default NATIVECCD path) and on any box/mesh pair