Preserve MuJoCo collision filtering semantics

[eric-heiden]

Summary

Newton does not yet preserve the full collision-selection semantics of MJCF models.

For automatically generated contacts, MuJoCo accepts a geom pair when:

(contype_a & conaffinity_b) != 0 or (contype_b & conaffinity_a) != 0

Newton currently handles the special case where both values are zero by assigning collision_group=0, but other contype / conaffinity combinations are flattened into Newton's existing collision-group representation. This can introduce unintended contacts or remove required selective self-collisions.

Explicit MJCF <contact><pair> entries are a separate selection path: they intentionally bypass the automatic mask and parent-child filters, can retain otherwise zero-mask geoms, and can override contact parameters. Their import, selection, and parameter precedence must remain separate from automatic mask filtering.

The goal of this epic is to preserve MJCF collision behavior across Newton collision pipelines and SolverMuJoCo without regressing the existing collision-group API or replicated-model scalability.

Goals

• Preserve exact automatic pair eligibility from MJCF contype / conaffinity masks.
• Preserve explicit <pair> inclusion and contact-parameter overrides, including default-class inheritance.
• Preserve <exclude>, same-body, parent-child, world-parent, and articulation self-collision semantics.
• Define coherent composition between collision_group, mask filtering, and shape_collision_filter_pairs.
• Avoid imposing a 32-group limit or another breaking restriction on existing Newton collision groups.
• Preserve or intentionally define SolverMuJoCo mask export and round-trip behavior.
• Keep model construction and collision-filter storage scalable across replicated worlds.
• Validate semantic pair equivalence instead of relying only on raw geom_contype / geom_conaffinity array equality.

Workstreams

1. Automatic mask filtering

• Decide whether exact type/affinity masks are a public API, an internal runtime representation, or importer-compiled data.
• Rebase or rework Fix MJCF collision mask filtering #3104 on current main after the newer importer, broad-phase, filter-storage, and explicit-pair changes.
• Preserve the existing unbounded collision-group behavior; do not lower every existing group into a fixed 32-bit allocation without a compatible fallback.
• Define mixed-model behavior when MJCF masks interact with Newton-authored shapes, global shapes, multiple imported assets, and existing collision groups.
• Apply the mask predicate only to automatically generated pairs; explicit included pairs must retain MuJoCo's bypass semantics.
• Export exact authored masks through SolverMuJoCo where possible, while retaining graph-coloring or another equivalent path for Newton-native collision groups.

2. Explicit contact pairs

• Resolve <pair> default classes before collecting endpoints or parameters.
• Apply pair-specific condim, friction, margin/gap, solref, solreffriction, and solimp to Newton-generated contacts.
• Force explicit MuJoCo pairs into Newton's collision pipeline even when automatic collision groups, masks, parent-child filters, or sparse exclusions reject them.
• Avoid duplicate candidate generation and preserve pair-specific precedence across multiple worlds.

3. Correctness coverage

Add semantic pair-matrix comparisons against compiled MuJoCo for:

• asymmetric mask acceptance, including the floor/two-sphere reproduction;
• multiple mask bits and zero-mask geoms;
• selective self-collision within one articulation;
• same-body, parent-child, fixed/world-parent, and welded-body cases;
• <exclude> and explicit <pair> precedence;
• explicit-pair default inheritance and zero-mask endpoints;
• Explicit, NxN, and SAP broad phases;
• native MuJoCo contacts and Newton-generated contacts;
• multiple worlds and replicated models;
• Newton models using more than 32 collision groups.

Fix the menagerie comparison path so unordered geom fields can be checked when appropriate, and compare effective pair eligibility when raw mask values are intentionally regenerated.

4. Performance and storage

• Benchmark sparse and dense MJCF mask patterns at representative geom and world counts.
• Measure import time, finalization time, collision-pipeline construction, filter-pair counts, and peak host memory.
• If masks are compiled into sparse exclusions, provide a compact representation and prove that dense incompatibility matrices do not recreate the filter-pair memory failure addressed by Only emit collision filters between colliding shapes #3574.
• Finish removal of unreachable filters involving non-colliding USD shapes so all importer paths follow the same storage invariants.

Active issues

• [BUG] contype/conaffinity collision filtering not working #3014 — full contype / conaffinity filtering is not implemented.
• [BUG] MuJoCo geom groups are dropped and contact masks differ #3235 — distinguish exact raw mask preservation from behavior-level pair equivalence.
• Compare unordered geom fields in menagerie tests #3306 — unordered geom-field comparisons are currently suppressed by the menagerie skip logic.
• Avoid collision filters for non-colliding USD shapes #3579 — remove residual collision filters involving non-colliding USD shapes.
• Honor explicit MuJoCo pair parameters for Newton-generated contacts #3644 — honor explicit MuJoCo pair selection and parameters for Newton-generated contacts.
• [BUG] MJCF contact pairs ignore pair default classes #3670 — resolve explicit contact-pair default classes during MJCF import.

Active pull requests

• Preserve MJCF collision filtering semantics #3714 — compile masks into groups/exclusions and preserve exact MuJoCo round trips without a new core mask API.
• Fix MJCF collision mask filtering #3104 — prototype first-class type/affinity masks; requires an architectural decision and substantial rebase/rework.
• Fix MJCF contact pair defaults #3671 — explicit-pair default-class inheritance.
• Honor MuJoCo pairs for Newton contacts #3645 — explicit-pair parameter propagation for Newton-generated contacts.
• Select explicit MuJoCo pairs for Newton contacts #3662 — explicit-pair selection, stacked on Honor MuJoCo pairs for Newton contacts #3645.

Landed groundwork

• Preserve MJCF geom groups #3283 preserves MJCF geom visualization groups independently from collision groups.
• Preserve explicit-pair MJCF geoms #3285 retains zero-mask geoms referenced by explicit contact pairs.
• Only emit collision filters between colliding shapes #3574 limits generated filters to colliding MJCF/URDF/ModelBuilder shapes and demonstrated the cost of unreachable filter pairs.
• Startup Optimization: hydro-elastics, mesh creation, builder merge, and filter template #3656 improves replicated filter-template construction and finalization performance.

Completion criteria

• The eligible automatic and explicit geom-pair sets match compiled MuJoCo for the regression matrix.
• All Newton broad-phase modes and both SolverMuJoCo contact-generation paths agree on selection and precedence.
• Existing Newton collision-group behavior remains backward compatible.
• Replicated-model benchmarks show bounded construction time and memory for both sparse and dense filtering patterns.
• Related menagerie skips and open issues are narrowed or closed with behavior-level evidence.

[andrewkaufman]

@eric-heiden can you add cross-repo isues to an Epic? We have been tracking this in the USD converter for a long time & still don't really settle on any reasonable solution newton-physics/mujoco-usd-converter#10