newton.controllers.ControllerJointImpedance#

class newton.controllers.ControllerJointImpedance(model, *, articulations=None, joints=None, stiffness, damping, use_gravity_compensation=True, use_coriolis_compensation=True, use_inertia_decoupling=True, has_qdd_feedforward=False)[source]#

Bases: ControllerBase

Joint-space impedance controller with internally computed dynamics.

Implements the joint-space impedance control law. This model-based variant computes the mass matrix, gravity, and Coriolis terms itself: it evaluates forward kinematics and the enabled dynamics terms from model on every step(), so the caller supplies only joint positions and velocities.

model is borrowed, not owned — it is never written to, and changes to it are visible to the controller immediately.

Joint selection. articulations and joints select the controlled joints, following Label Matching: each is a list of model indices and/or label patterns (or a single pattern), matched against articulation_label and the leaf component of joint_label respectively. The constructor resolves them to each selected joint’s starting coordinate/DOF index in the model — one entry per joint, not per DOF — and validates the result. q_start and qd_start expose the resolved indices afterward, e.g. to gather/scatter a compact port against a simulation-sized array.

Ports. Most arrays passed in and out are compact: one entry per controlled DOF — robot 0’s DOFs first, then robot 1’s — rather than one entry per DOF in the model. inputs.joint_q and inputs.joint_qd are the exception and cover the whole model, since the dynamics terms depend on uncontrolled joints too. A compact port may be bound to a plain array, or to an indexed view of a simulation-sized array:

outputs.joint_f = control.joint_f[controller.qd_start]  # scatter to the sim

Each articulation in model is one robot. Only joints spanning a single coordinate and a single DOF can be controlled, since the PD error term q_des - q is only a well-defined scalar subtraction for those; every other joint (Fixed, or any multi-DOF type) is read for FK and dynamics but never actuated. The default joints selection leaves such joints uncontrolled automatically; explicitly naming one in joints raises ValueError at construction instead, as does addressing a joint that belongs to no robot, or the same DOF twice.

Supports heterogeneous robot fleets — robots may have different controlled-DOF counts, and a robot may be left uncontrolled entirely. An uncontrolled robot occupies no slot in any buffer and is masked out of the FK and dynamics evaluations, so its body_q is left untouched. model_robot_count counts every robot in the model, controlled_robot_count only those with controlled DOFs.

See also ControllerJointImpedanceModelFree, which takes the mass matrix, gravity, and Coriolis terms as inputs instead of computing them from a Model.

Impedance law (terms enabled at construction):

τ = [M(q) if use_inertia_decoupling else I] · (q̈_des + Kp·Δq + Kd·Δq̇)

[C(q,q̇)·q̇ if use_coriolis_compensation else 0]

[g(q) if use_gravity_compensation else 0]

Parameters:

model (Model) – Model whose articulations are the robots. Articulations may mix controlled single-DOF joints with uncontrolled joints of any type. The controller’s device and requires_grad are taken from model; every other array argument (stiffness, damping) must match both.
articulations (list[int | str | re.Pattern[str]] | str | re.Pattern[str] | None) – Articulation indices or label patterns to control, as a list or as a single pattern. None selects every articulation in model.
joints (list[int | str | re.Pattern[str]] | str | re.Pattern[str] | None) – Model joint indices or label patterns to control within the selected articulations, as a list or as a single pattern. None selects every joint spanning exactly one coordinate and one DOF — the only kind this controller can actuate — in each selected articulation; any other joint (Fixed, or a multi-DOF type such as a floating base) is left uncontrolled instead of rejected. A joint named explicitly is not filtered this way and still raises ValueError if it is not 1-coordinate/1-DOF.
stiffness (wp.array[wp.float32] | float | None) – Position-error gain Kp. Units depend on use_inertia_decoupling: [1/s²] when enabled, since the PD term is then an acceleration premultiplied by M(q); otherwise [N/m or N·m/rad]. Pass a scalar to apply the same gain to every controlled DOF, an array of shape [total_controlled_dofs] to set them individually, or None to read inputs.stiffness each step.
damping (wp.array[wp.float32] | float | None) – Velocity-error gain Kd, [1/s] when use_inertia_decoupling is enabled, otherwise [N·s/m or N·m·s/rad]. Same format as stiffness.
use_gravity_compensation (bool) – Add gravity generalized forces to τ.
use_coriolis_compensation (bool) – Add Coriolis generalized forces to τ.
use_inertia_decoupling (bool) – Premultiply the PD term by M(q).
has_qdd_feedforward (bool) – Accept a desired-acceleration feedforward via inputs.joint_qdd.

class Inputs#

Bases: object

Input struct returned by input().

Dynamics fields (mass matrix, gravity, Coriolis) are computed internally and do not appear here.

damping: wp.array[wp.float32] | wp.indexedarray[wp.float32] | None#: Velocity-error gain Kd, shape [total_controlled_dofs]. [1/s] when use_inertia_decoupling is enabled, otherwise [N·s/m or N·m·s/rad]. None when gains are baked at construction.

joint_q: wp.array[wp.float32] | wp.indexedarray[wp.float32]#: Current joint positions [m or rad], shape [model.joint_coord_count].

joint_q_des: wp.array[wp.float32] | wp.indexedarray[wp.float32]#: Desired joint positions [m or rad], shape [total_controlled_dofs].

joint_qd: wp.array[wp.float32] | wp.indexedarray[wp.float32]#: Current joint velocities [m/s or rad/s], shape [model.joint_dof_count].

joint_qd_des: wp.array[wp.float32] | wp.indexedarray[wp.float32]#: Desired joint velocities [m/s or rad/s], shape [total_controlled_dofs].

joint_qdd: wp.array[wp.float32] | wp.indexedarray[wp.float32] | None#: Desired acceleration feedforward [m/s² or rad/s²], shape [total_controlled_dofs]. None unless has_qdd_feedforward=True.

stiffness: wp.array[wp.float32] | wp.indexedarray[wp.float32] | None#: Position-error gain Kp, shape [total_controlled_dofs]. [1/s²] when use_inertia_decoupling is enabled, otherwise [N/m or N·m/rad]. None when gains are baked at construction.

class Outputs#

Bases: object

Output struct returned by output().

joint_f: wp.array[wp.float32] | wp.indexedarray[wp.float32]#: Joint torque command [N or N·m], shape [total_controlled_dofs].

__init__(model, *, articulations=None, joints=None, stiffness, damping, use_gravity_compensation=True, use_coriolis_compensation=True, use_inertia_decoupling=True, has_qdd_feedforward=False)#

input()#

Return a pre-allocated Inputs without dynamics fields.

is_graphable()#

output()#

Return a pre-allocated Outputs with a compact torque array.

step(*, inputs, outputs, dt)#

Run one impedance-control step.

Parameters:

inputs (Inputs) – Populated Inputs struct. Dynamics terms are computed internally from the Newton model.
outputs (Outputs) – Outputs struct to write torques into.
dt (float | wp.array[wp.float32]) – Unused. Accepted for API compatibility.

property controlled_robot_count: int#: Number of robots with at least one controlled DOF.

property max_controlled_dofs: int#: Largest controlled-DOF count over the controlled robots.

property model_robot_count: int#: Number of articulations in model, controlled or not.

property q_start: wp.array[wp.int32]#

Model coordinate index of each controlled joint, shape [total_controlled_dofs].

Use to gather or scatter a compact port against a simulation-sized coordinate array, e.g. model.joint_q[controller.q_start].

property qd_start: wp.array[wp.int32]#

Model DOF index of each controlled joint, shape [total_controlled_dofs].

Use to scatter a compact port into a simulation-sized array, e.g. control.joint_f[controller.qd_start].

property total_controlled_dofs: int#: Total controlled-DOF count across all robots, the length of every compact port.