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, *, custom_inputs=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.

  • custom_inputs (dict[str, Any] | None) – Arrays for the names this drive lists in custom_inputs, keyed by attribute name. Values are passed without validation and may be None when absent. Empty when the drive names none.

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, *, custom_inputs=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.

custom_inputs carries the same arrays as the matching argument of compute().

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]] = {}#
custom_inputs: tuple[str, ...] = ()#

Names of extra caller-provided Control arrays this drive reads.

Set in __init__ when the declaration depends on drive configuration. Actuator reads the same-named values from sim_control and passes them to compute() as custom_inputs. The actuator routes values without validating them; the drive owns requiredness, fallback behavior, and validation.

evaluate_force: ClassVar[Function | None] = None#

@wp.func form of this drive’s force law, called inside the implicit solve kernel (see Actuator.set_effort_mode_implicit()). None means the drive does not support implicit actuation.

Required signature (float64):

evaluate_force(q, qd, target_q, target_qd, feedforward,
               params: wp.array2d[float], i: int) -> wp.float64

params[i] holds the drive’s parameters for actuator slot i; see bind_params().