newton.eval_fk#

newton.eval_fk(model, joint_q, joint_qd, state, mask=None, indices=None, body_flag_filter=BodyFlags.ALL, *, joint_mask=None)[source]#

Evaluates the model’s forward kinematics given the joint coordinates and updates the state’s body information (State.body_q and State.body_qd).

The written State.body_qd values use Newton’s public body-twist convention (v_com_world, omega_world).

To edit a branch while preserving the rest of a simulated articulation: refresh stale joint coordinates with eval_ik() if needed, edit the desired joint coordinates, and pass a joint_mask selecting the edited joint and all descendants that should follow it. Use Model.joint_ancestor to identify those descendants. Selecting only the edited joint leaves its descendants’ body poses and velocities unchanged.

An eval_ik() / full FK round trip can change unrelated bodies when simulated poses or velocities do not exactly satisfy the joint constraints, as well as through numerical roundoff. The joint mask preserves unselected body state exactly instead of reconstructing it from joint coordinates.

Parameters:

  • model (Model) – The model to evaluate.

  • joint_q (wp.array[float]) – Generalized joint position coordinates, shape [joint_coord_count], float

  • joint_qd (wp.array[float]) – Generalized joint velocity coordinates, shape [joint_dof_count], float

  • state (State | Model | object) – The state-like target to update (e.g., State or Model).

  • mask (wp.array[bool] | None) – The mask to use to enable / disable FK for an articulation. If None then treat all as enabled, shape [articulation_count], bool

  • indices (wp.array[int] | None) – Integer indices of articulations to update. If None, updates all articulations. Cannot be used together with mask parameter.

  • body_flag_filter (int) – Body flag filter controlling which bodies are written to in state.body_q and state.body_qd. Default updates both dynamic and kinematic bodies. Bodies that do not match the filter retain their existing values; they are not zeroed or invalidated.

  • joint_mask (wp.array[bool] | None) – Optional bool array on model.device, shape [joint_count]. Only selected joints update their child bodies; unselected joints preserve the existing body pose and velocity. This only selects FK writes and is independent of Model.joint_enabled. Selected joints use their parents’ current state, whether preserved or updated by this call. Descendants are not selected automatically: include them to propagate an edit through a branch. Intersects with mask or indices and body_flag_filter. Supports autodiff and graph capture, including changes to mask values between graph replays.

Raises:

ValueError – If both articulation filters are supplied, or joint_mask has the wrong dtype, shape, or device.

On this page