newton.actuators.Actuator#

class newton.actuators.Actuator(indices, controller, delay=None, clamping=None, pos_indices=None, target_pos_indices=None, effort_indices=None, state_pos_attr='joint_q', state_vel_attr='joint_qd', control_target_pos_attr='joint_target_pos', control_target_vel_attr='joint_target_vel', control_feedforward_attr='joint_act', control_output_attr='joint_f', control_computed_output_attr=None, requires_grad=False)[source]#

Bases: object

Composed actuator: delay → controller → clamping.

An actuator reads from simulation state/control arrays, optionally delays command inputs, computes effort via a controller, applies clamping (effort limits, saturation, etc.), and accumulates the result into the output array (scatter-add). The caller must zero the output array before stepping actuators.

Usage:

actuator = Actuator(
    indices=indices,
    controller=ControllerPD(kp=kp, kd=kd),
    delay=Delay(delay_steps=wp.array([5, 5], dtype=wp.int32), max_delay=5),
    clamping=[ClampingMaxEffort(max_effort=max_effort)],
)

# Simulation loop
actuator.step(sim_state, sim_control, state_a, state_b, dt=0.01)
__init__(indices, controller, delay=None, clamping=None, pos_indices=None, target_pos_indices=None, effort_indices=None, state_pos_attr='joint_q', state_vel_attr='joint_qd', control_target_pos_attr='joint_target_pos', control_target_vel_attr='joint_target_vel', control_feedforward_attr='joint_act', control_output_attr='joint_f', control_computed_output_attr=None, requires_grad=False)#

Initialize actuator.

Parameters:

  • indices (wp.array[wp.uint32]) – DOF indices into velocity-shaped arrays (velocities, velocity targets, feedforward, effort output). Shape (N,).

  • controller (Controller) – Controller that computes raw effort.

  • delay (Delay | None) – Optional Delay instance for input delay.

  • clamping (list[Clamping] | None) – List of Clamping objects (post-controller effort bounds).

  • pos_indices (wp.array[wp.uint32] | None) – Indices into coordinate-shaped arrays (positions = state.joint_q). Defaults to indices. Differs from indices when position and velocity arrays have different layouts (e.g. floating-base or ball-joint articulations).

  • target_pos_indices (wp.array[wp.uint32] | None) – Indices into control.joint_target_pos (DOF-shaped). Defaults to indices. Typically equal to indices since joint_target_pos uses DOF layout.

  • effort_indices (wp.array[wp.uint32] | None) – DOF indices into effort output arrays. Defaults to indices. Differs from indices for coupled transmissions or tendon-driven joints.

  • state_pos_attr (str) – Attribute on sim_state for positions.

  • state_vel_attr (str) – Attribute on sim_state for velocities.

  • control_target_pos_attr (str) – Attribute on sim_control for target positions.

  • control_target_vel_attr (str) – Attribute on sim_control for target velocities.

  • control_feedforward_attr (str | None) – Attribute on sim_control for feedforward effort. None to skip.

  • control_output_attr (str) – Attribute on sim_control for clamped output effort.

  • control_computed_output_attr (str | None) – Attribute on sim_control for raw (pre-clamp) effort. None to skip writing computed effort.

  • requires_grad (bool) – Allocate intermediate arrays with gradient support for differentiable simulation.

is_graphable()#

Return True if all components can be captured in a CUDA graph.

is_stateful()#

Return True if delay or controller maintains internal state.

state()#

Return a new composed state, or None if fully stateless.

step(sim_state, sim_control, current_act_state=None, next_act_state=None, dt=None)#

Execute one control step.

  1. Delay read — read per-DOF delayed targets from current_state (falls back to current targets when the buffer is empty).

  2. Controller — compute raw effort into _computed_forces.

  3. Clamping — clamp effort from computed → _applied_forces.

  4. Scatter-add — accumulate applied (and optionally computed) effort into the output array. The caller must zero the output (e.g. control.joint_f.zero_()) before looping over actuators.

  5. State updates — controller state update, then delay buffer write (push current targets into next_state).

Parameters:

  • sim_state (Any) – Simulation state with position/velocity arrays.

  • sim_control (Any) – Control structure with target/output arrays.

  • current_act_state (State | None) – Current composed state (None if stateless).

  • next_act_state (State | None) – Next composed state (None if stateless).

  • dt (float | None) – Timestep [s].