newton.eval_mimic#

newton.eval_mimic(model, state_in, state_out=None, *, mask=None, indices=None)[source]#

Update follower joint coordinates from their reference joints.

For each follower, this function reads every position and velocity coordinate of the reference joint, then writes the matching follower coordinates according to Model.joint_mimic_coeffs. Independent joints are left unchanged. Only State.joint_q and State.joint_qd are written.

If state_out is omitted, state_in is updated in place. Otherwise, independent joint coordinates are copied from state_in to state_out and follower coordinates are evaluated from state_in.

Like eval_fk() and eval_ik(), mask or indices selects articulations, not worlds or joints. Only the selected articulations are copied and updated; unselected coordinates in state_out retain their existing values. With neither selector, all joints are processed.

Solvers with mimic support enforce the relationship during step(); this helper is not a required post-step call. Whether step() refreshes joint coordinates in state_out is solver-defined. If a solver advances body coordinates without refreshing joint coordinates, use eval_ik() to derive current joint values from the output body state; calling this function on stale joint arrays would use stale reference values. Call this helper before eval_fk() when initializing body poses from joint values that need mimic projection.

Parameters:

  • model (Model) – Model containing the joint mimic metadata.

  • state_in (State) – State providing the input joint coordinates.

  • state_out (State | None) – State receiving the updated joint coordinates. If None, update state_in in place.

  • mask (wp.array[bool] | None) – Boolean mask of shape (model.articulation_count,) on the model device. True selects an articulation. Mutually exclusive with indices.

  • indices (wp.array[int] | None) – One-dimensional array of unique integer articulation indices on the model device. Out-of-range indices are skipped, matching eval_fk() and eval_ik(). An empty array updates nothing. Mutually exclusive with mask.

Raises:

ValueError – If either state does not contain joint coordinate arrays, both selectors are provided, or a selector has an incompatible shape, dtype, or device.

On this page