newton.eval_inverse_dynamics_force#

newton.eval_inverse_dynamics_force(model, state, *, mass_matrix, joint_qdd, coriolis_force, gravity_force, joint_f, mask=None)[source]#

Evaluate tau = M(q)*joint_qdd + C(q,q_dot)*q_dot + g(q).

Combines a per-articulation mass-matrix-times-acceleration product with the Coriolis and gravity forces to produce the full joint force required to realize joint_qdd at the current (q, q_dot) under gravity, writing the result to joint_f in place. The two force inputs follow the standard manipulator-equation sign convention (+C(q,q_dot)*q_dot and +g(q) = +∂U/∂q, the buffers populated by eval_inverse_dynamics_passive()) and are added directly. Per-articulation DOF counts are recovered from joint_qd_start, so a mix of fixed-root and floating-root articulations across multiple worlds is handled uniformly.

For any FREE/DISTANCE joint in the articulation tree, the mass matrix in mass_matrix is expressed in the joint’s parent frame while the bias forces are in the world-frame CoM-wrench convention of joint_f. Each such joint’s mass-matrix-times-acceleration wrench is rotated to world (using state.body_q for the parent-frame-in-world rotation) before the sum, so joint_f is entirely in that world convention.

CABLE joints are not supported because their DOF slots are constraints rather than generalized coordinates for this inverse-dynamics formulation.

Experimental

Experimental feature. API, behavior, defaults, and supported use cases may change without prior notice.

Parameters:

  • model (Model) – The model containing articulation definitions.

  • state (newton.State) – State providing body_q, used to rotate the FREE/DISTANCE root mass-matrix-times-acceleration wrench into the world frame. Must be consistent with the mass-matrix and bias-force buffers in this call (i.e. the state passed to eval_inverse_dynamics_passive()).

  • mass_matrix (wp.array(dtype=wp.float32, ndim=3)) – Joint-space mass matrix, shape (model.articulation_count, model.max_dofs_per_articulation, model.max_dofs_per_articulation), dtype float. Entry units depend on the row and column DOF types: [kg] for two translational DOFs, [kg·m] for mixed translational/rotational DOFs, and [kg·m²] for two rotational DOFs.

  • joint_qdd (wp.array(dtype=wp.float32, ndim=1)) – Generalized joint accelerations [m/s² or rad/s², depending on joint type], shape (model.joint_dof_count,), dtype float.

  • coriolis_force (wp.array(dtype=wp.float32, ndim=1)) – Coriolis + centrifugal force C(q, q_dot)*q_dot [N or N·m, depending on joint type], shape (model.joint_dof_count,), dtype float.

  • gravity_force (wp.array(dtype=wp.float32, ndim=1)) – Gravity force g(q) = ∂U/∂q [N or N·m, depending on joint type], shape (model.joint_dof_count,), dtype float.

  • joint_f (wp.array(dtype=wp.float32, ndim=1)) – Output generalized joint force :math:` au` [N or N·m, depending on joint type], shape (model.joint_dof_count,), dtype float. Uses the same layout and convention as joint_f.

  • mask (wp.array(dtype=wp.bool, ndim=1) | None) – Optional wp.array[bool] of shape (articulation_count,) selecting which articulations to compute. Unselected joint-force entries are zeroed without reading their mass-matrix, acceleration, or bias-force inputs.

Raises:

ValueError – If the model contains a CABLE joint or an input, output, or mask has an unexpected shape.