newton.selection.ArticulationView#

class newton.selection.ArticulationView(model, pattern, *, include_joints=None, exclude_joints=None, include_links=None, exclude_links=None, include_joint_types=None, exclude_joint_types=None, include_loop_closing_joints=False, verbose=None)[source]#

Bases: object

ArticulationView provides a flexible interface for selecting and manipulating subsets of articulations and their joints, links, and shapes within a Model. It supports pattern-based selection, inclusion/exclusion filters, and convenient attribute access and modification for simulation and control.

This is useful in RL and batched simulation workflows where a single policy or control routine operates on many parallel environments with consistent tensor shapes.

Example:

import newton

view = newton.selection.ArticulationView(model, pattern="robot*")
q = view.get_dof_positions(state)
q_np = q.numpy()
q_np[..., 0] = 0.0
view.set_dof_positions(state, q_np)

The pattern, include_joints, exclude_joints, include_links, and exclude_links parameters accept label patterns or integer indices — see Label Matching.

Parameters:

  • model (Model) – The model containing the articulations.

  • pattern (str | list[str] | list[int]) – Pattern or list of patterns to match articulation labels, or a list of absolute articulation indices. Indices must be unique and in ascending order.

  • include_joints (list[str] | list[int] | None) – List of joint names, patterns, or indices to include. Unsorted integer indices are deprecated and will be rejected in a future release.

  • exclude_joints (list[str] | list[int] | None) – List of joint names, patterns, or indices to exclude.

  • include_links (list[str] | list[int] | None) – List of link names, patterns, or indices to include. Unsorted integer indices are deprecated and will be rejected in a future release.

  • exclude_links (list[str] | list[int] | None) – List of link names, patterns, or indices to exclude.

  • include_joint_types (list[int] | None) – List of joint types to include.

  • exclude_joint_types (list[int] | None) – List of joint types to exclude.

  • include_loop_closing_joints (bool) – If True, include converted loop-closing joints.

  • verbose (bool | None) – If True, prints selection summary.

__init__(model, pattern, *, include_joints=None, exclude_joints=None, include_links=None, exclude_links=None, include_joint_types=None, exclude_joint_types=None, include_loop_closing_joints=False, verbose=None)#
eval_fk(target, mask=None)#

Evaluates forward kinematics given the joint coordinates and updates the body information.

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

Parameters:

  • target (Model | State) – The target where to evaluate forward kinematics (Model or State).

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

eval_inverse_dynamics_force(state, *, mass_matrix, joint_qdd, coriolis_force, gravity_force, joint_f, mask=None)#

Compute inverse-dynamics joint forces for articulations in this view.

Entries outside this view or the optional sub-selection are zeroed.

Experimental

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

Parameters:

  • state (newton.State) – State providing body transforms consistent with the supplied mass matrix and bias forces.

  • 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 [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 [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) | wp.array(dtype=wp.bool, ndim=2) | None) – Optional mask of articulations in this ArticulationView. Either 1-D [world_count] or 2-D [world_count, count_per_world].

eval_inverse_dynamics_passive(state, *, mass_matrix=None, gravity_force=None, coriolis_force=None, mask=None)#

Compute passive inverse-dynamics quantities for this view.

Forwards to eval_inverse_dynamics_passive() with an articulation mask derived from this view and the optional view-local mask. Each non-None output is computed; entries belonging to articulations outside the selection are zero.

Experimental

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

Parameters:

  • state (newton.State) – The state containing the current generalized coordinates and velocities. state.body_q must already reflect state.joint_q.

  • mass_matrix (wp.array(dtype=wp.float32, ndim=3) | None) – Optional output, 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.

  • gravity_force (wp.array(dtype=wp.float32, ndim=1) | None) – Optional gravity-force output [N or N·m, depending on joint type], shape (model.joint_dof_count,), dtype float.

  • coriolis_force (wp.array(dtype=wp.float32, ndim=1) | None) – Optional Coriolis + centrifugal-force output [N or N·m, depending on joint type], shape (model.joint_dof_count,), dtype float.

  • mask (wp.array(dtype=wp.bool, ndim=1) | wp.array(dtype=wp.bool, ndim=2) | None) – Optional mask of articulations in this ArticulationView (all by default). Either 1-D [world_count] selecting whole worlds or 2-D [world_count, count_per_world] selecting individual articulations per world.

eval_jacobian(state, J=None, joint_S_s=None, mask=None)#

Evaluate spatial Jacobian for articulations in this view.

Computes the spatial Jacobian J that maps joint velocities to spatial velocities of each link in world frame, matching state.body_qd under Newton’s public COM/world body-twist convention.

Parameters:

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

  • J – Optional output array for the Jacobian, shape (articulation_count, max_links*6, max_dofs). If None, allocates internally.

  • joint_S_s – Optional pre-allocated temp array for motion subspaces.

  • mask – Optional mask of articulations in this ArticulationView (all by default).

Returns:

The Jacobian array J, or None if the model has no articulations.

eval_mass_matrix(state, H=None, J=None, body_I_s=None, joint_S_s=None, mask=None)#

Evaluate generalized mass matrix for articulations in this view.

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 resulting matrix is consistent with kinetic energy computed from COM-referenced body twists.

Parameters:

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

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

  • J – Optional pre-computed Jacobian. If None, computes internally.

  • body_I_s – Optional pre-allocated temp array for spatial inertias.

  • joint_S_s – Optional pre-allocated temp array for motion subspaces.

  • mask – Optional mask of articulations in this ArticulationView (all by default).

Returns:

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

get_actuator_parameter(actuator, component, name)#

Read an actuator-component parameter for every DOF in this view.

The returned array covers all DOFs selected by the view (one column per DOF, one row per world). DOFs that are not driven by actuator are left at zero; driven DOFs contain the corresponding value gathered from component.<name>.

Parameters:

  • actuator (Actuator) – Actuator instance whose DOF indices determine which view DOFs are considered actuated.

  • component (Any) – The component that owns the parameter — a Controller, Clamping, or Delay instance.

  • name (str) – Attribute name on component (e.g. "kp", "max_effort", "delay_steps").

Returns:

Parameter values shaped (world_count, dofs_per_world) where dofs_per_world is the total number of DOFs in the view (not just the actuated subset).

get_attribute(name, source)#

Get an attribute from the source (Model, State, or Control).

Parameters:

  • name (str) – The name of the attribute to get.

  • source (Model | State | Control) – The source from which to get the attribute.

Returns:

The attribute values (dtype matches the attribute).

Return type:

array

get_dof_forces(source)#

Get the joint forces (DoF forces) for the selected articulations.

Parameters:

source (Control) – The source from which to retrieve the DoF forces.

Returns:

The joint forces (dtype=float).

Return type:

array

get_dof_positions(source)#

Get the joint coordinate positions (DoF positions) for the selected articulations.

Parameters:

source (Model | State) – The source from which to retrieve the DoF positions.

Returns:

The joint coordinate positions (dtype=float).

Return type:

array

get_dof_velocities(source)#

Get the joint coordinate velocities (DoF velocities) for the selected articulations.

Parameters:

source (Model | State) – The source from which to retrieve the DoF velocities.

Returns:

The joint coordinate velocities (dtype=float).

Return type:

array

Get the world-space transforms of all links in the selected articulations.

Parameters:

source (Model | State) – The source from which to retrieve the link transforms.

Returns:

The link transforms (dtype=wp.transform).

Return type:

array

Get the world-space spatial velocities of all links in the selected articulations.

The returned body_qd values follow Newton’s public convention: (v_com_world, omega_world).

Parameters:

source (Model | State) – The source from which to retrieve the link velocities.

Returns:

The link velocities (dtype=wp.spatial_vector).

Return type:

array

get_model_articulation_mask(mask=None)#

Get Model articulation mask from a mask in this ArticulationView.

Parameters:

mask (wp.array(dtype=wp.bool, ndim=1) | wp.array(dtype=wp.bool, ndim=2) | None) – Mask of articulations in this ArticulationView (all by default).

get_root_transforms(source)#

Get the root transforms of the articulations.

Parameters:

source (Model | State) – Where to get the root transforms (Model or State).

Returns:

The root transforms (dtype=wp.transform).

Return type:

array

get_root_velocities(source)#

Get the root velocities of the articulations.

Parameters:

source (Model | State) – Where to get the root velocities (Model or State).

Returns:

The root velocities (dtype=wp.spatial_vector).

Return type:

array

set_actuator_parameter(actuator, component, name, values, mask=None)#

Write an actuator-component parameter for every DOF in this view.

values must cover all DOFs in the view (one column per DOF, one row per world). Only entries whose DOFs are actually driven by actuator are written back to component.<name>; the rest are ignored.

Parameters:

  • actuator (Actuator) – Actuator instance whose DOF indices determine which view DOFs are considered actuated.

  • component (Any) – The component that owns the parameter — a Controller, Clamping, or Delay instance.

  • name (str) – Attribute name on component (e.g. "kp", "max_effort", "delay_steps").

  • values (wp.array) – New parameter values shaped (world_count, dofs_per_world) where dofs_per_world is the total number of DOFs in the view.

  • mask – Per-world mask (world_count,). Only masked worlds are updated.

set_attribute(name, target, values, mask=None)#

Set an attribute in the target (Model, State, or Control).

Parameters:

  • name (str) – The name of the attribute to set.

  • target (Model | State | Control) – The target where to set the attribute.

  • values (wp.array[Any]) – The values to set for the attribute.

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

Note

When setting attributes on the Model, it may be necessary to inform the solver about such changes by calling newton.solvers.SolverBase.notify_model_changed() after finished setting Model attributes.

set_dof_forces(target, values, mask=None)#

Set the joint forces (DoF forces) for the selected articulations.

Parameters:

  • target (Control) – The target where to set the DoF forces.

  • values (wp.array(dtype=wp.float32, ndim=1)) – The values to set (dtype=float).

  • mask (wp.array(dtype=wp.bool, ndim=1) | wp.array(dtype=wp.bool, ndim=2) | None) – Mask of articulations in this ArticulationView (all by default).

set_dof_positions(target, values, mask=None)#

Set the joint coordinate positions (DoF positions) for the selected articulations.

Parameters:

  • target (Model | State) – The target where to set the DoF positions.

  • values (wp.array[float]) – The values to set (dtype=float).

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

set_dof_velocities(target, values, mask=None)#

Set the joint coordinate velocities (DoF velocities) for the selected articulations.

Parameters:

  • target (Model | State) – The target where to set the DoF velocities.

  • values (wp.array[float]) – The values to set (dtype=float).

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

set_root_transforms(target, values, mask=None)#

Set the root transforms of the articulations. Call eval_fk() to apply changes to all articulation links.

Parameters:

  • target (Model | State) – Where to set the root transforms (Model or State).

  • values (wp.array[wp.transform]) – The root transforms to set (dtype=wp.transform).

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

set_root_velocities(target, values, mask=None)#

Set the root velocities of the articulations.

Parameters:

  • target (Model | State) – Where to set the root velocities (Model or State).

  • values (wp.array[wp.spatial_vector]) – The root velocities to set (dtype=wp.spatial_vector).

  • mask (wp.array[bool] | wp.array2d[bool] | None) – Mask of articulations in this ArticulationView (all by default).

property body_labels#

Alias for link_labels.

property body_names#

Alias for link_names.

property body_shapes#

Alias for link_shapes.