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, 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 — see Label Matching.

Parameters:

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

  • pattern (str) – Pattern to match articulation labels.

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

  • 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.

  • 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.

  • 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, 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 (array) – Mask of articulations in this ArticulationView (all by default).

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 (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 (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 (array) – 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 (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 (array) – The values to set for the attribute.

  • mask (array) – 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 (array) – The values to set (dtype=float).

  • mask (array, optional) – 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 (array) – The values to set (dtype=float).

  • mask (array, optional) – 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 (array) – The values to set (dtype=float).

  • mask (array, optional) – 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 (array) – The root transforms to set (dtype=wp.transform).

  • mask (array) – 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 (array) – The root velocities to set (dtype=wp.spatial_vector).

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

property body_names#

Alias for link_names.

property body_shapes#

Alias for link_shapes.