newton.actuators.Controller#

class newton.actuators.Controller[source]#

Bases: object

Base class for actuator control laws.

Control laws compute actuator output effort from authored controller parameters, commanded inputs (targets, feedforward), and simulation state. The output may still be constrained by one or more Clamping objects.

Subclasses must override compute and resolve_arguments.

Validation contract: resolve_arguments() validates scalar parameter values (e.g. kp >= 0) before they are batched into Warp arrays. __init__ receives pre-built arrays and validates shapes only — reading back array contents for value checks would force a synchronous device-to-host copy on every construction.

classmethod resolve_arguments(args)#

Resolve user-provided arguments with defaults.

Parameters:

args (dict[str, Any]) – User-provided arguments.

Returns:

Complete arguments with defaults filled in.

Return type:

dict[str, Any]

compute(positions, velocities, target_pos, target_vel, feedforward, pos_indices, vel_indices, target_pos_indices, target_vel_indices, forces, state, dt, device=None)#

Compute actuator output effort and write to forces[i].

Parameters:

  • positions (wp.array[float]) – Joint positions [m or rad].

  • velocities (wp.array[float]) – Joint velocities [m/s or rad/s].

  • target_pos (wp.array[float]) – Target positions [m or rad].

  • target_vel (wp.array[float]) – Target velocities [m/s or rad/s].

  • feedforward (wp.array[float] | None) – Feedforward effort [N or N·m] (may be None).

  • pos_indices (wp.array[wp.uint32]) – Indices into positions for each DOF.

  • vel_indices (wp.array[wp.uint32]) – Indices into velocities for each DOF.

  • target_pos_indices (wp.array[wp.uint32]) – Indices into target_pos.

  • target_vel_indices (wp.array[wp.uint32]) – Indices into target_vel and feedforward.

  • forces (wp.array[float]) – Scratch buffer to write effort [N or N·m] to. Shape (N,).

  • state (Controller.State | None) – Controller state (None if stateless).

  • dt (float) – Timestep [s].

  • device (wp.Device | None) – Warp device for kernel launches.

finalize(device, num_actuators)#

Called by Actuator after construction to set up device-specific resources.

Override in subclasses that need to place tensors or networks on a specific device, or pre-compute index tensors.

Parameters:

  • device (Device) – Warp device to use.

  • num_actuators (int) – Number of actuators (DOFs) this controller manages.

is_graphable()#

Return True if compute() can be captured in a CUDA graph.

is_stateful()#

Return True if this controller maintains internal state.

state(num_actuators, device)#

Create and return a new state object, or None if stateless.

update_state(current_state, next_state)#

Advance internal state after a compute step.

Parameters:

  • current_state (State) – Current controller state.

  • next_state (State) – Next controller state to write.

SHARED_PARAMS: ClassVar[set[str]] = {}#