Merge branch 'main' into dev/tw4/improve-cube-stacking-stability

# Conflicts:
#	newton/_src/geometry/mpr.py

Author: nvtw

CHANGELOG.md

@@ -18,22 +18,25 @@
 - 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.
 - Add three VBD contact examples — `vbd_rigid_rigid_contact`, `vbd_soft_rigid_contact`, and `vbd_soft_rigid_mix_contact` — demonstrating rigid-rigid, soft (particle-rigid), and mixed cloth-bag contacts
-- Add masked rigid-body reset support to `SolverVBD`; particle resets are not yet supported. (#3256)
+- Add masked rigid-body reset support to `SolverVBD`. (#3256)
 - Add `Mesh.invalidate_cache()` to drop cached derived data (hash, edges, finalized Warp meshes) after in-place modification of `Mesh.vertices` or `Mesh.indices`; reassigning those properties invalidates automatically.
 - Add viewer layer system to overlay multiple solvers/models in supported rendering viewers; call `ViewerBase.activate(layer_id)` to route subsequent `set_model` / `log_state` / `log_*` calls into a named layer, `ViewerBase.set_layer_visible()` to toggle layers independently, and `ViewerBase.set_layer_transform()` to position layers side-by-side. See `example_basic_multi_solver_overlay.py`
 - Add `Heightfield.create_from_mesh()` and `newton.utils.rasterize_mesh_to_heightfield()` to build a heightfield collider by ray-casting a `wp.Mesh`, replacing a large static terrain mesh with an equivalent heightfield.
 - Add `ViewerBase.camera_speed` to configure keyboard translation speed for interactive viewers. (#3439)
+- Add read-only `Contacts.contact_matching_mode` metadata reporting whether the `CollisionPipeline` that produced or last filled the buffer used `"disabled"`, `"latest"`, or `"sticky"` contact matching.
 - Add a "Show Ground" visualization toggle (`ViewerBase.show_ground`, default on) to hide or show ground-plane shapes in the viewer.
 - Add opt-in DVI forward dynamics to `SolverKamino` through `SolverKamino.Config(dynamics_solver="dvi")`, with sparse and dense execution, DVI-specific diagnostics, and warm-starting. PADMM remains the default.
 - Add opt-in DVI forward dynamics to `SolverKamino` through `SolverKamino.Config(dynamics_solver="dvi")`, with sparse and dense execution, DVI-specific convergence diagnostics, warm-starting, bounded contact-recovery controls, and RCM-reordered bilateral factorization with reusable ordering and panel-parallel numeric factorization for large systems. PADMM remains the default.
 - Add SDF contact support for convex-hull shapes with mesh-attached SDFs and opt-in SDF contact generation for box shapes.
 - Warn in `ModelBuilder.add_usd()` when a rigid body prim has a mirrored (negative-determinant) world transform. Improper transforms have no unique rotation decomposition, so imported body and joint frames can acquire a spurious constant rotation (common with mirror-scaled CAD exports); the warning recommends baking the reflection into the mesh geometry before import.
 - Add opt-in filtering of static-static, static-kinematic, and kinematic-kinematic contacts during broad-phase collision detection. Set `CollisionPipeline(include_static_kinematic_pairs=False)` to enable filtering; the default preserves existing contact generation. `Model.shape_contact_pairs` remains an unfiltered superset for direct consumers such as `SolverKamino` and hydroelastic SDF setup.
 - Add opt-in `body_frame_origin="com"` to `ModelBuilder.add_rod()` and `ModelBuilder.add_rod_graph()` for COM-centered cable capsule body frames.
+- Add dedicated gravity for global world `-1` while preserving the single-entry `Model.gravity` array for implicit single-world models and local-only array updates through `Model.set_gravity()`. (#3723)
 - Add `sign_method` argument to `Mesh.build_sdf` and `SDF.create_from_mesh` support for a `"normal"` (angle-weighted pseudo-normal) sign strategy, for selecting the inside/outside sign of the baked SDF (`"auto"`, `"parity"`, `"winding"`, or `"normal"`).
 - Add opt-in MuJoCo Warp sleeping support to `SolverMuJoCo` with MJCF sleep configuration, initial tree policies, `sleep_tolerance`, compact `nvmax` storage, and a launchable `mujoco_sleeping` example. (#3725)
 - Add `forward_depth_image` output support to `SensorTiledCamera.update()` and `SensorTiledCamera.utils.create_forward_depth_image_output()` for native forward-depth rendering without post-processing `depth_image`.
@@ -48,10 +51,12 @@
 - Add simulation throughput, real-time factor, p95 step-time, steady-state GPU-memory, timestep, and MuJoCo solver-iteration metrics to the ASV robot-learning benchmarks.
 - Add `joint_dof_mask` to `newton.ik.IKSolver` to keep selected joint DOFs fixed during LM optimization. (#3488)
 - Add `SolverMuJoCo(disable_sensors=True)` to skip MuJoCo sensor computation.
+- Add masked deformable reset to `SolverVBD.reset()`: `StateFlags.PARTICLE_Q` / `StateFlags.PARTICLE_QD` restore cloth and soft-body particle state per world selected by `world_mask`. (#3400)
 
 ### Changed
 
 - Decide collider visibility from USD `purpose` and visibility rather than from a bound render material. A collider whose `purpose` resolves to `default` is viewport geometry and is drawn; mark it `guide` to state that it is collision-only. Previously an unrelated visual elsewhere in the scene could make a collider vanish. `force_show_colliders` and `hide_collision_shapes` are unchanged.
+- Require `warp-lang>=1.16.0`; upgrade Warp to version 1.16.0 or later.
 - Disable the implicit positive Dahl-friction defaults in `SolverVBD.register_custom_attributes()` (deprecated in 1.3.0): `vbd:dahl_eps_max` and `vbd:dahl_tau` now default to zero, and Dahl cable friction is enabled only where both are authored positive. Pass `dahl_defaults_enabled=True` to temporarily restore the old defaults; the compatibility mode will be removed in a future release.
 - Keep the authored render mesh when `ModelBuilder.add_usd()` approximates a collider. `physics:approximation` is scoped to collision, so a Mesh that is both render geometry and a collider now imports as an approximated collision shape plus a visual shape carrying the original topology, instead of replacing the render mesh with the approximation. This raises `Model.shape_count` for such prims: iterate on `ShapeFlags.COLLIDE_SHAPES` rather than assuming one shape per collider prim. The visual shape adds no mass and no collision, appends after the originals so existing shape indices and `path_shape_map` entries are unchanged, and is skipped when `load_visual_shapes=False`.
 - Compile tiled camera render kernels with CUDA fast math by default for faster rendering; set `SensorTiledCamera.render_config.enable_fast_math = False` for bit-exact, IEEE-precise output.
@@ -91,9 +96,11 @@
 - Deprecate `SensorTiledCamera(..., config=...)` in favor of `SensorTiledCamera(..., default_render_config=...)`; migrate constructor calls that pass a render config to the new keyword.
 - Deprecate `SensorTiledCamera.render_config` in favor of `SensorTiledCamera.default_render_config`; migrate `sensor.render_config.enable_shadows = True` to `sensor.default_render_config.enable_shadows = True`.
 - Deprecate `SensorTiledCamera.utils.compute_pinhole_camera_rays()` in favor of `SensorTiledCamera.utils.compute_camera_rays_pinhole()`.
+- Deprecate the legacy DOF-shaped `joint_target_q` layout (`newton.use_coord_layout_targets = False`) for models whose joint coordinate and DOF counts differ (free/ball/distance joints); `ModelBuilder.finalize()` now emits a `DeprecationWarning` for such models. Set `newton.use_coord_layout_targets = True` before building models and index targets via `Model.joint_target_q_start`. A future release will make the coordinate layout the only layout and remove the flag.
 
 ### Removed
 
+- Remove the deprecated `joint_target_pos` / `joint_target_vel` aliases from `Model`, `Control`, and `ModelBuilder` (deprecated in 1.3.0); use `joint_target_q` / `joint_target_qd` instead. Reading or assigning the removed names raises `AttributeError` naming the replacement, so a stale `control.joint_target_pos = targets` fails loudly instead of being silently ignored. `Actuator` now always defaults `control_target_pos_attr` / `control_target_vel_attr` to the canonical `joint_target_q` / `joint_target_qd` names; passing `None` explicitly selects the same defaults.
 - Remove the deprecated SDF compatibility attributes `Model.shape_sdf_index`, `Model.texture_sdf_data`, `Model.texture_sdf_coarse_textures`, `Model.texture_sdf_subgrid_textures`, `Model.texture_sdf_subgrid_start_slots`, `Model.sdf_block_coords`, `Model.sdf_index2blocks`, and `SDF.texture_block_coords` (deprecated in 1.3.0); the hydroelastic broadphase derives block coordinates arithmetically and the remaining storage is internal.
 - Remove the deprecated `newton.geometry.build_bvh_shape()`, `refit_bvh_shape()`, `build_bvh_particle()`, and `refit_bvh_particle()` helpers (deprecated in 1.3.0); use `Model.bvh_build_shapes()`, `Model.bvh_refit_shapes()`, `Model.bvh_build_particles()`, and `Model.bvh_refit_particles()` instead.
 - Remove the deprecated `Model.has_heightfields` property (deprecated in 1.3.0); use `Model.heightfield_count`, or `model.heightfield_count > 0` for boolean checks, instead.
@@ -102,6 +109,7 @@
 
 ### Fixed
 
+- Fix MPR returning scale-dependent, excessively deep contacts for small convex shapes on large mesh triangles while preserving triangle-specific shared-edge manifold witnesses.
 - Make deterministic collision pipelines cover hydroelastic contact generation and reduction, including unique reduced-contact sort keys and overflow-safe fixed-point pressure accumulation.
 - Preserve box-box face contact manifolds under sub-microradian solver drift.
 - Fix `SolverMuJoCo` retaining an invalid external-contact cache when its first step is captured in a CUDA graph. (#3767)
@@ -117,6 +125,7 @@
 - Exclude active particles with non-finite positions from rebuildable `SolverImplicitMPM` sparse-grid packing.
 - Fix incorrect hydroelastic contact surfaces for primitive shapes. (#3150, #3239)
 - Fix masked `SolverCoupledProxy.reset()` calls clearing proxy feedback history for unselected worlds.
+- Fix masked solver resets modifying unselected worlds or discarding their coupling and contact history.
 - Fix MJCF, URDF, and USD imports rendering collision-only bodies as visuals when the asset authors visual geometry elsewhere. (#3291)
 - Fix `SchemaResolverPhysx` reading every D6 translational limit gain from the `linear` instance instead of its `transX`, `transY`, or `transZ` instance.
 - Fix USD capsule, cylinder, and cone visuals and sites without authored `radius`/`height` to use the UsdGeom schema fallbacks, matching collision shapes.
@@ -139,6 +148,8 @@
 - Fix Style3D solver divergence caused by isolated vertices.
 - Fix a use-after-free where finalizing a second model built from shared mesh geometry (e.g. via `ModelBuilder.replicate()` or `ModelBuilder.add_builder()`) invalidated the meshes referenced by previously finalized models.
 - Fix compiler warnings about overflowing int32 constants when compiling SDF texture and `SensorTiledCamera` kernels.
+- Fix `SolverVBD` particles using world 0 gravity in multi-world models instead of their assigned world's gravity. (#3692)
+- Fix `SensorIMU` to use per-world gravity for world-local sites not attached to a body.
 - Fix USD site import to discover sites beneath non-visual containers, collider prims, and instanceable rigid-body prims independently of `load_visual_shapes`; the reworked traversal also speeds up import of scenes with many nested `Xform` or instance prims.
 - Fix `SolverFeatherstone` BALL joints to apply passive `joint_damping` on all three angular DOFs.
 - Fix `eval_ik()` and `SolverSemiImplicit` rounding small float32 revolute-joint angles to zero. (#3434)
@@ -147,6 +158,7 @@
 - Fix `FastKitchenG1` ASV metrics to build the kitchen scene instead of a plain G1 model.
 - Fix the `diffsim_bear` example crashing with its default CUDA configuration and diverging after a few training iterations.
 - Fix masked PID state reset to execute on the integral-state device. (#3447)
+- Fix `eval_inverse_dynamics_passive()` reading past a DOF-sized scratch buffer under `newton.use_coord_layout_targets = True`, producing intermittent NaNs for models with free, ball, or distance joints.
 - Fix MJCF imports ignoring `fromto` transforms and lengths on sites.
 - Reject invalid hollow primitive shell thickness before computing inertia.
 - Fix `ModelBuilder.add_mjcf()` ignoring positive explicit mass on mesh geoms. (#3595)

asv.conf.json

@@ -16,7 +16,7 @@
   "build_command": ["python -m build --wheel -o {build_cache_dir} {build_dir}"],
   "install_command": [
     "in-dir={env_dir} python -m pip install {wheel_file}[dev] --extra-index-url=https://pypi.nvidia.com/",
-    "in-dir={env_dir} python -m pip install warp-lang==1.16.0.dev20260716 mujoco==3.11.0 mujoco-warp==3.11.0 --extra-index-url=https://pypi.nvidia.com/",
+    "in-dir={env_dir} python -m pip install warp-lang==1.16.0 mujoco==3.11.0 mujoco-warp==3.11.0 --extra-index-url=https://pypi.nvidia.com/",
     "python -m pip install torch==2.10.0+cu130 --index-url https://download.pytorch.org/whl/cu130"
   ]
 }

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