newton.actuators.DriveBase#

class newton.actuators.DriveBase[source]#

Bases: object

Base class for actuator drives.

Drives compute actuator output effort from authored drive parameters, commanded inputs (targets, feedforward), and simulation state. The output may still be constrained by one or more ClampingBase 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]

bind_params()#

Build the per-actuator parameter pack and wire attributes to it.

Called once when the implicit effort mode is installed. Override to:

  1. Pack the drive’s parameters into a contiguous (num_actuators, P) array — row i for actuator slot i, layout matching evaluate_force.

  2. Re-point the drive’s parameter arrays (e.g. kp) at columns of the pack so later writes stay visible.

None (the default) means the drive does not support implicit actuation.

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[wp.float32]) – Joint positions [m or rad].

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

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

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

  • feedforward (wp.array[wp.float32] | 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[wp.float32]) – Scratch buffer to write effort [N or N·m] to. Shape (N,).

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

  • dt (float) – Timestep [s].

  • device (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 drive manages.

is_graphable()#

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

is_stateful()#

Return True if this drive maintains internal state.

prepare_implicit(positions, velocities, target_pos, target_vel, pos_indices, vel_indices, target_pos_indices, target_vel_indices, drive_state, dt, inv_mass=None, device=None)#

Refresh the parameter pack before an implicit solve step.

Called by the implicit effort mode once per step, before the solve kernel. Drives whose evaluate_force law needs per-step preparation (e.g. a neural network linearized about the current state) override this to rewrite the pack built by bind_params() in place. The default is a no-op — parameter-static laws like PD need nothing here.

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 drive state.

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

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