How to stabilize tendon actuators with biastype="affine" in MJWarp?

[vreutskyy]

Context:

I'm simulating a gripper model with:

• A floating base (D6 joint: 3 slide + 3 hinge on one body)
• Finger joints coupled via a fixed tendon
• Position control using general actuators with biastype="affine" on the tendon

This setup runs in native MuJoCo (with a warning about instability at DOF 6, but it recovers). However, in MJWarp the simulation explodes to NaN.

Questions:

1. Why is this configuration numerically unstable? Is it the combination of tendon + affine, or something about the D6 base joint?

2. What's the recommended way to set up tendon actuators for GPU simulation? Should I avoid biastype="affine" on tendons?

Minimal Reproduction:
repro_mjwarp_tendon_affine_bug.py

Attached is a script that demonstrates the issue - native MuJoCo passes, MJWarp fails.

Environment:

• MuJoCo: 3.4.1
• MJWarp: 0.0.2
• Warp: 1.12.0.dev20260127

[mzamoramora-nvidia]

I also encountered a similar issue trying to simulate a Robotiq gripper mounted on a ur5e robot.

I used the xml provided here that uses the assets from the MuJoCo Menagerie. The full assets can be found in ur5e_2f85.zip for convenience.

When the ur5e_2f85.xml is loaded to the MuJoCo viewer (python -m mujoco.viewer) the simulation runs fine. But if I load the asset to the MJWarp viewer (mjwarp-viewer ur5e_2f85.xml) the scene explodes.

[vreutskyy]

I traced this issue by comparing the MuJoCo and MuJoCo Warp source code.

In native MuJoCo, mj_step calls mj_checkAcc after mj_forward (see engine_forward.c:85). When qacc contains NaN/Inf/huge values, it triggers mj_resetData + mj_forward — a full state autoreset. This is why native MuJoCo warns but recovers.

In MuJoCo Warp, mj_checkPos, mj_checkVel, and mj_checkAcc are all listed as TODOs in forward.py:936-939:

def step(m: Model, d: Data):
    # TODO(team): mj_checkPos
    # TODO(team): mj_checkVel
    forward(m, d)
    # TODO(team): mj_checkAcc

So when the solver produces a bad qacc value, there's no safety net — the NaN propagates into qvel and qpos on the next integration step, and the simulation explodes.

The attached repro script shows this: both backends hit the same instability at DOF 6, but native MuJoCo autoresets while MuJoCo Warp diverges to NaN.

[yuvaltassa]

This is by design. @thowell we should document the behaviour and reasoning.

[adenzler-nvidia]

By "by design" - do you mean the reset? Because I traced the issue a bit further and stumbled upon something in the derivative calculation.

The reason this use-case fails is because the tendon couples 2 joints that are not part of the same subtree, and thus there is no qM entry for their interaction. MjWarp then misses that contribution because it only iterates of qM entries, and has a stale value in the derivative which makes the matrix ill-conditioned and leads to a NaN later on. Looking at the code, the sparse versions of both MuJoCo and MjWarp seem to have this issue, but in MuJoCo we're just dropping the term because it doesn't even appear in the sparse layout.

That's a bug, right? Or are fixed tendons required to target the same subtree?

[yuvaltassa]

Oh whoops. I only read the thread and not the OP. Not sure what my opinion is yet, but I can definitely retract my comment above 😳

Thanks @adenzler-nvidia 🙏

[adenzler-nvidia]

Thanks Yuval - should we move this to an issue on the main MuJoCo github?