newton.eval_mass_matrix#

newton.eval_mass_matrix(model, state, H=None, J=None, body_I_s=None, joint_S_s=None, mask=None, *, include_armature=True)[source]#

Evaluate generalized mass matrix for articulations.

Computes the generalized mass matrix H = J^T * M * J, where J is the spatial Jacobian and M is the block-diagonal spatial mass matrix. The mass matrix relates joint accelerations to joint forces/torques and is consistent with kinetic energy computed from COM-referenced body twists.

joint_armature is added to the diagonal, so H is the joint-space inertia that solvers supporting armature (SolverMuJoCo, SolverFeatherstone and SolverKamino) integrate. Solver-specific overrides, such as the large armature some solvers assign to kinematic bodies, are not included.

Parameters:

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

  • state (newton.State) – The state containing body transforms (body_q).

  • H (array | None) – Optional output array for mass matrix, shape (articulation_count, max_dofs, max_dofs). If None, allocates internally.

  • J (array | None) – Optional pre-computed Jacobian, shape (articulation_count, max_links*6, max_dofs). If None, H is assembled by the composite rigid body algorithm without forming J, unless gradients are required or the model has no FK level schedule (non-tree articulations or a tree level wider than 512 joints); then J is computed internally.

  • body_I_s (array | None) – Optional pre-allocated temp array for spatial inertias, shape (body_count,), dtype wp.spatial_matrix. If None, allocates internally.

  • joint_S_s (array | None) – Optional pre-allocated temp array for motion subspaces (only used if J is None), shape (joint_dof_count,), dtype wp.spatial_vector. If None, allocates internally.

  • mask (wp.array[wp.bool] | None) – Optional one-dimensional mask of shape (articulation_count,) selecting which articulations to compute. If None, computes for all articulations. Two-dimensional per-world masks are not supported.

  • include_armature (bool) – Deprecated in Newton 1.8. If True (default), add joint_armature to the diagonal. Passing False returns the rigid-body matrix and emits a DeprecationWarning. This argument will be removed in a future minor release.

Returns:

The mass matrix array H, or None if the model has no articulations.

Return type:

array | None

On this page