Newton Mimic Joints

Executive summary

Numerically, the benefit comes from eliminating follower state: zero-DOF joint-based import reduces Robotiq generalized coordinates from 6 to 1 in the synthetic URDF and 14/12 to 6/6 in imported Robotiq models, improving FK by 30–40% on those assets. A same-DOF mimic keeps those follower coordinates, so it mostly becomes the separate-constraint prototype. Multi-DOF mimic should not be a special vector joint initially: MuJoCo, PhysX USD, and scanned assets use scalar per-axis couplings.

Prototype branch: eric-heiden/newton · mimic-constraint at aa76da85.

How a mimic joint should be parameterized in Model

A mimic relation is the scalar affine equation q_follower = offset + multiplier * q_leader. To make it a Newton joint without inflating generalized state, the follower should be a zero-DOF joint that derives its effective coordinate during FK/IK/state transfer.

Why zero DOF instead of matching the leader DOF count?

A same-DOF mimic is a valid design, but it changes what we are optimizing for. If the follower has the same coordinate and velocity slots as the leader, Newton can reuse all per-DOF arrays normally: joint_axis, limits, target gains, armature, friction, effort limits, and control slots all exist. That makes parameterization easy and avoids the zero-DOF metadata problem.

The cost is that the follower is no longer derived state. It has its own joint_q, joint_qd, controls, forces, limits, and solver unknowns. The affine mimic relation then has to be enforced as an equality/constraint or by overwriting the follower state before every consumer. If enforced as a constraint, the follower can drift unless the solver stabilizes it. If overwritten, the extra DOF rows are dead storage and any user-written controls/forces on those rows become ambiguous.

The eric/mimic-constraint prototype at aa76da85 is the same-DOF/separate-constraint model: URDF import creates the follower as a normal joint, then adds constraint_mimic_joint0/joint1/coef0/coef1. The branch does not add JointType.MIMIC, and no solver/FK kernels consume constraint_mimic_* yet. Metadata creation is covered by targeted tests (Ran 4 tests in 0.202s: OK); full mimic test discovery was blocked by dependency issues, documented in prototype_investigation.json.

Reuse existing joint attributes

• joint_type[j] = JointType.MIMIC marks the row as a derived joint.
• joint_child, joint_X_p, joint_X_c, joint_label, joint_world, and joint_enabled should be used exactly as for other joints.
• joint_q_start[j] == joint_q_start[j+1], joint_qd_start[j] == joint_qd_start[j+1], and joint_dof_dim[j] = (0, 0). The follower adds no generalized coordinates, velocities, forces, limits, armature, target, or actuation rows.
• The leader coordinate can be resolved through the leader joint's existing joint_q_start/joint_qd_start. For the current URDF/USD scalar mimic use case, only scalar revolute and prismatic leaders should be accepted.

No-extra-array encoding using existing fields

The most aggressive encoding is type-dependent overloading for JointType.MIMIC:

• joint_parent[j] stores the leader joint index instead of a parent body index.
• joint_target_ke[j] stores offset and joint_target_kd[j] stores multiplier, interpreted at joint frequency for mimic joints.
• The follower axis and scalar type are not repeated. They are inferred from the follower joint's existing transform convention and/or the leader's scalar joint type; for URDF mimics this is usually sufficient if follower and leader are both scalar revolute/prismatic joints.

This is genuinely attractive if we only care about the affine dependency: it needs no new arrays and the lookup is direct. However it changes two important Model invariants. First, joint_parent is currently a body index used by topology, FK, articulation construction, body filtering, and import/export; using it as a joint index means any code that needs the follower's parent body must recover it elsewhere. Second, joint_target_ke and joint_target_kd are per-DOF arrays today, while a zero-DOF mimic has no DOF slot. Making joint_target_ke[j] work would require either changing those arrays to joint frequency, adding a fake metadata DOF, or defining an exception where mimic joints index target arrays by joint id. Those are API changes even though they avoid new array names.

Can joint_axis store offset and multiplier?

It can only work as another documented overload, and it is weaker than using joint_target_ke/kd. The tempting layout is joint_parent[j] as the leader joint index and joint_axis[j].x/y as offset/multiplier. That uses the two useful floats in the existing wp.vec3 and leaves z unused or available for a future scalar flag.

The blocker is the current Newton invariant: joint_axis is not joint-frequency metadata. It is a per-DOF array indexed from joint_qd_start; the docs explicitly say it has length joint_dof_count. A zero-DOF mimic joint therefore has no legal axis slot. Storing coefficients at joint_axis[j] would be unsafe because joint index and DOF index are different spaces: fixed joints have zero slots, free/D6 joints have multiple slots, and j can either collide with another joint's real axis or exceed joint_dof_count.

Adding a fake axis row would also not be free. If the fake row increments joint_dof_count, the mimic is no longer a true zero-DOF joint and it perturbs every per-DOF array. If the row does not increment joint_dof_count, Newton needs a second indexing rule or a separate metadata count, which is effectively a new schema rule hidden behind an old name.

Practical recommendation

If Newton is comfortable with explicit type-dependent semantics, the target-gain overload is the better no-new-array encoding for scalar mimic joints: document that for JointType.MIMIC, joint_parent means leader joint and target stiffness/damping mean offset/multiplier. I would not use joint_axis for coefficients unless Newton is already willing to split axis metadata away from DOF storage. If we want to preserve global invariants that joint_parent is always a body index and per-DOF arrays are always per DOF, then the dependency has to live somewhere else. In that case the compact generic relation table remains preferable to dense mimic-specific arrays.

Design alternatives compared

This is the decision center of the report. Green options preserve the most useful Model invariants or measured wins; yellow options are workable but require clear tradeoffs; red options add hidden complexity or redundant state.

RecommendedViable with caveatsAvoid

Multi-DOF mimic joints and schema evidence

Practical assets and interchange schemas do not justify a first-class vector-valued mimic relation yet: there are many coupled mechanisms, but the practical representation is almost always a set of scalar DOF-to-DOF relations. Raw notes: schema research JSON and MuJoCo Menagerie scan JSON.

What counts as multi-DOF in practice?

Assets such as ms_human_700, iit_softfoot, toddlerbot_2xc/2xm, and hello_robot_stretch have mechanisms that feel multi-DOF at the component level: knees with translations and rotations, shoulder/scapula couplings, multi-link phalanx chains, geared humanoid joints, and telescoping arm segments. But they are authored as multiple scalar equations, not as one relation q_follower_vector = A q_leader_vector + b.

Recommended Newton representation

Use a scalar relation row as the primitive: target_joint, target_dof, source_joint, source_dof, offset, multiplier, plus optional polynomial coefficients if Newton wants to preserve MuJoCo's quartic equality exactly. A multi-DOF mimic is then just a group of scalar rows sharing a group id/key. This matches PhysX USD's multiple-apply mimic API and MuJoCo's scalar equality model, and it avoids inventing matrix-valued metadata before an asset needs it.

For zero-DOF derived joints, each scalar row derives one follower coordinate from one leader coordinate. For same-DOF constraints, each row contributes one scalar residual. For true vector maps, Newton could later add a relation-table extension with compressed row blocks or a dense/sparse matrix, but that should be a second step rather than the default mimic API.

Do we currently handle it?

The current eric/mimic-constraint prototype only stores one scalar coef0/coef1 pair per mimic constraint between two joint indices. Its docstring says multi-DOF joints are supported by applying the same scalar coefficients to all DOFs, but the stored Model data has no target DOF index, source DOF index, per-axis coefficient vector, or matrix. Also, no FK/solver kernels consume constraint_mimic_* yet. So the prototype handles scalar metadata creation, but it does not yet robustly implement multi-DOF mimic semantics.

Real Newton asset benchmarks

Branch-vs-main benchmark data: branch JSON and main JSON. The important signal is where mimic representation changes state size: Robotiq-style assets get smaller and faster; unrelated assets mostly show noise.

FK and state-size results

Interpretation: the performance win appears exactly where mimic followers remove generalized coordinates. Robotiq assets improve 30–40% in FK. Assets without mimics are neutral or noisy; the branch does not provide a general speedup independent of mimic state reduction.

Solver step results

Solver interpretation: semi-implicit, XPBD, Featherstone, and VBD timings are mostly dominated by solver implementation and asset size rather than mimic representation. MuJoCo's Robotiq USD row improves from 29.9 ms to 15.4 ms after lowering the zero-DOF mimic representation to MuJoCo's equality format. VBD still rejects the synthetic rigid JointType.MIMIC case, so full solver parity is not yet achieved.

Parameterization microbenchmark

This microbenchmark isolates Model metadata traversal and storage overhead across the parameterization choices: script and raw JSON. It is not a solver benchmark; it answers which representation adds hidden bookkeeping cost before physics even runs.

Takeaway: the compact relation table is the cleanest general-purpose design because it scales with the number of mimic relations and preserves Model invariants. The target-gain overload is the best no-new-array option, but its zero-storage win comes from accepting type-dependent semantics. Same-DOF + constraint is implementation-friendly but gives up the state-size win. The joint-axis overload should be avoided because it mixes DOF-axis storage with joint-level relation metadata.

Asset behavior videos

These videos show the imported hands and grippers used in the benchmark set, including the Robotiq mimic cases where follower coordinates are removed.

Validation

Passed: the earlier mimic-joint prototype passed 23 mimic-related tests in 17.395 s.

Passed: eric/mimic-constraint at aa76da85 passed 4 targeted metadata tests in 0.202 s. Full mimic discovery was blocked by environment/dependency issues, not by assertion failures; see prototype_investigation.json.

Conclusion

Same-DOF mimics answer the parameterization problem but not the original modeling problem: they are normal joints with an added relation, so they keep redundant state and require enforcement. That matches the current constraint_mimic_* prototype. Multi-DOF evidence argues for scalar rows, not a matrix-valued mimic joint: MJCF equality/joint is hinge/slide only, PhysX USD mimic is per-axis, and Menagerie's 209 equality joint constraints are all scalar. If Newton wants mimic followers to be derived kinematic joints and keep the Robotiq state-size/FK wins, they should be zero-DOF with scalar per-axis relation rows. For zero-DOF mimics, the no-extra-array target-gain overload is viable only as a documented JointType.MIMIC exception; I still prefer a compact generic relation table if preserving Model invariants matters. If Newton prefers constraint semantics and minimal API disruption, keep the same-DOF/separate-constraint prototype but add explicit source/target DOF indices and enforcement.

Last updated: 2026-05-30 16:11:45 UTC