newton.controllers.ControllerJointImpedanceModelFree#

class newton.controllers.ControllerJointImpedanceModelFree(*, controlled_dofs_per_robot, stiffness, damping, use_gravity_compensation=True, use_coriolis_compensation=True, use_inertia_decoupling=True, has_qdd_feedforward=False, device=None, requires_grad=False)[source]#

Bases: ControllerBase

Joint-space impedance controller with caller-supplied dynamics.

Implements the joint-space impedance control law. This model-free variant expects the mass matrix, gravity, and Coriolis terms to be computed externally — it is the caller’s responsibility to compute the enabled ones correctly and write them into the input struct before every step().

Every port is compact: a 1-D array with one entry per controlled DOF, ordered robot 0’s DOFs first, then robot 1’s, matching controlled_dofs_per_robot. A port may be bound either to a plain compact array or to an indexed view of a simulation-sized array, which is how a caller expresses a gather or scatter without the controller owning an index table — for example, using a paired model-based controller’s own q_start/qd_start properties (see ControllerJointImpedance.qd_start):

inputs.joint_q = state.joint_q[ctrl.q_start]  # gather
outputs.joint_f = control.joint_f[ctrl.qd_start]  # scatter

Views are live and graph-capturable: bind them once, and each step (or graph replay) reads through to the current contents of the underlying array.

Array shapes and devices are validated on each direct call to step(), but not when a captured graph is replayed, since the checks run in Python at capture time only.

Supports heterogeneous robot fleets — robots may have different controlled-DOF counts. Only the mass matrix is padded, to max_controlled_dofs; every other buffer is compact.

Allocate input and output structs via input() and output(). All field names on those structs are fixed — see Inputs and Outputs for the typed schema. Fields for disabled features (e.g. gravity_force when use_gravity_compensation=False) are allocated as None and must not be written.

See also ControllerJointImpedance, which computes the mass matrix, gravity, and Coriolis terms internally from a Newton model.

Parameters:

  • controlled_dofs_per_robot (wp.array[wp.int32]) – Controlled-DOF count for each robot. Its length sets controlled_robot_count, its sum sets total_controlled_dofs (the length of every port), and its maximum sets max_controlled_dofs (the padded width of the mass matrix). Every entry must be positive.

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

  • device (Any) – Warp device.

  • requires_grad (bool) – Whether internal buffers need gradient support.

class Inputs#

Bases: object

Input struct returned by input().

Every 1-D field is compact, shape [total_controlled_dofs]. Optional fields are None when the corresponding feature is disabled at construction.

coriolis_force: wp.array[wp.float32] | wp.indexedarray[wp.float32] | None#

Coriolis generalized forces [N or N·m], shape [total_controlled_dofs]. None unless use_coriolis_compensation=True.

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.

gravity_force: wp.array[wp.float32] | wp.indexedarray[wp.float32] | None#

Gravity generalized forces [N or N·m], shape [total_controlled_dofs]. None unless use_gravity_compensation=True.

joint_q: wp.array[wp.float32] | wp.indexedarray[wp.float32]#

Current joint positions [m or rad], shape [total_controlled_dofs].

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 [total_controlled_dofs].

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.

mass_matrix: wp.array3d[wp.float32] | <warp._src.types.indexedarray object> | None#

[kg] translational, [kg·m] mixed, [kg·m²] rotational. None unless use_inertia_decoupling=True.

Type:

Per-robot mass matrices over the controlled DOFs, shape [controlled_robot_count, max_controlled_dofs, max_controlled_dofs]; a robot with fewer than max_controlled_dofs DOFs leaves the trailing rows and columns unread. May be bound to a view selecting those robots’ blocks out of a larger set. Units by row/column DOF type

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__(*, controlled_dofs_per_robot, stiffness, damping, use_gravity_compensation=True, use_coriolis_compensation=True, use_inertia_decoupling=True, has_qdd_feedforward=False, device=None, requires_grad=False)#
input()#

Return a pre-allocated Inputs with zero-initialised arrays.

is_graphable()#
output()#

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

step(*, inputs, outputs, dt)#

Compute one impedance-control step and write joint torques.

Parameters:

  • inputs (Inputs) – Populated Inputs struct. Dynamics fields must be filled by the caller before each call.

  • 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, i.e. the length of controlled_dofs_per_robot.

property max_controlled_dofs: int#

Largest controlled-DOF count over the robots, the padded width of inputs.mass_matrix.

property total_controlled_dofs: int#

Total controlled-DOF count across all robots, the length of every compact port.