Configure native MuJoCo Warp determinism before model constants

[huster-wgm]

Description

Configure MuJoCo Warp's native determinism option before Newton computes derived model constants. With an API-capable backend, SolverMuJoCo(deterministic=RUN_TO_RUN) currently leaves that option disabled. Setting it after construction cannot repair constants already computed through nondeterministic reductions.

Closes #4631. Related: #2479 and google-deepmind/mujoco_warp#1775.

This draft adapts the existing Newton argument to the upcoming backend API. It sets the per-model flag immediately after put_model, delegates kernel selection and scatter bounds to the native backend, and keeps Newton conversion kernels under the requested Warp mode. Older backends retain the existing module configuration and generated-kernel invalidation path. The global Warp configuration is restored after each scoped operation. Stronger GPU_TO_GPU requests are rejected rather than silently mapped to RUN_TO_RUN.

No new public parameter, USD schema, dependency-range change, or production-environment upgrade is introduced. The API-capable integration reports mujoco-warp==3.15.0, outside the current ~=3.14.0 dependency range; its warning remains visible. Keep this draft pending the upstream native API and compatible dependency release.

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• A user-facing changelog fragment has been added

Test plan

• Against Newton main a6e1649, the new construction-time regression fails with CRB observations [0, 0]; it passes after the fix. The observer invokes the real CRB calculation.
• Locked legacy dependencies: uv run --frozen python -m unittest newton.tests.test_mujoco_version_check newton.tests.test_mujoco_native_determinism — 9 passed, 2 skipped because the native API is unavailable.
• API-capable source integration: python -m unittest newton.tests.test_mujoco_native_determinism — CPU and RTX PRO 6000 CUDA, 4 passed. Covers flags during constant computation, finite and equal per-world constants, independent enabled/disabled solvers, model-property updates, restored global settings, repeated contact rollouts, and eager/CUDA Graph equality with zero overflow.
• Native integration dependencies: Warp 1.18.0, MuJoCo 3.14.1.dev990581733, MuJoCo Warp integration 7460a2c (runtime; 91c0ac8 adds documentation). The graph regression exercises the default conditional solver graph on Warp 1.18.0.
• uvx pre-commit run -a, git diff --check, and Towncrier draft preview pass. New test functions have docstrings and use portable unittest/NumPy/Warp APIs.

Bug fix

Steps to reproduce:

1. Use Newton main with the API-capable backend from Integrate native determinism with canonical contacts and constraint allocation google-deepmind/mujoco_warp#1775.
2. Construct SolverMuJoCo(..., deterministic=wp.DeterministicMode.RUN_TO_RUN).
3. Observe model.opt.deterministic == NONE during the constructor's CRB calls. The full timing reproduction is in the linked issue and the regression test.

Minimal reproduction:

import warp as wp
import newton
from newton.solvers import SolverMuJoCo
import mujoco_warp as mjw

assert hasattr(mjw, "DeterminismType")
builder = newton.ModelBuilder()
body = builder.add_link(xform=wp.transform((0, 0, 0.1), wp.quat_identity()))
builder.add_shape_box(body, hx=0.1, hy=0.1, hz=0.1)
builder.add_articulation([builder.add_joint_free(child=body)])
builder.add_ground_plane()
solver = SolverMuJoCo(
    builder.finalize(device="cpu"), use_mujoco_contacts=True,
    deterministic=wp.DeterministicMode.RUN_TO_RUN,
)
assert solver.mjw_model.opt.deterministic == int(mjw.DeterminismType.ALL)

Summary by CodeRabbit

• Bug Fixes
  • Improved deterministic behavior for simulations using MuJoCo Warp backends with native determinism support. Repeated runs now produce consistent results under supported settings, including contact simulations.
  • Unsupported GPU determinism settings are rejected. Older backends continue to use the existing configuration behavior.
• Documentation
  • Clarified determinism options and backend-specific guarantees.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: newton-physics/newton/.coderabbit.yml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9d41be4a-8c91-41d7-a4de-0b7d28d77601

---

📥 Commits

Reviewing files that changed from the base of the PR and between a6e1649 and 46b1237.

---

📒 Files selected for processing (3)

• changelog/+mujoco-native-determinism-31c7a62e.fixed.md
• newton/_src/solvers/mujoco/solver_mujoco.py
• newton/tests/test_mujoco_native_determinism.py

---

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The solver configures native MuJoCo Warp determinism before model constants are initialized. It limits native GPU modes to NOT_GUARANTEED and RUN_TO_RUN, preserves the legacy configuration path for older backends, and adds configuration and rollout tests.

Changes

Native MuJoCo determinism

Layer / File(s)	Summary
Configure model determinism before constants newton/_src/solvers/mujoco/solver_mujoco.py, changelog/*	When the native API is available, the solver validates GPU modes and sets model determinism flags after put_model and before model constants are initialized. The changelog records the native and legacy paths.
Separate native and Newton kernel settings newton/_src/solvers/mujoco/solver_mujoco.py	Native backends use NOT_GUARANTEED for Warp’s global and native module settings. Newton conversion kernels retain the configured mode and dynamic-record bound. Native backends skip generated-kernel cache clearing and deterministic record-bound calculation.
Test configuration and repeated rollouts newton/tests/test_mujoco_native_determinism.py	Tests check mode mapping, configuration timing, restored Warp settings, finite matching inverse weights, and repeatable contact rollouts across identical worlds. CUDA devices also compare graph-captured execution.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant SolverMuJoCo
  participant MuJoCoWarp
  participant Warp
  SolverMuJoCo->>MuJoCoWarp: put_model
  SolverMuJoCo->>MuJoCoWarp: set model determinism flags before constants
  SolverMuJoCo->>MuJoCoWarp: initialize model constants
  SolverMuJoCo->>Warp: set global determinism to NOT_GUARANTEED during native execution

Loading

---

Merge Risk: ⚪ Minimal · up to 46b12

The change configures native MuJoCo Warp determinism before model constants are computed and keeps the legacy behavior for older backends. No concrete merge-blocking defect was identified in the supplied context. The native API depends on an upstream release, which the PR already tracks.

Pre-merge checks | 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: configuring native MuJoCo Warp determinism before model constants are computed.
Linked Issues check		The changes satisfy the coding requirements in [#4631]. SolverMuJoCo detects DeterminismType, sets the native per-model flag immediately after put_model, and does so before model-change constant…
Out of Scope Changes check		The changed solver code directly implements [#4631]. The regression tests verify the required native and legacy behavior. The changelog documents the fix. No unrelated public API, schema, dependency-r…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 2 files. (1 skipped: 1…

---

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}