newton.actuators.Actuator#

class newton.actuators.Actuator(indices, drive=None, 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_q', control_target_vel_attr='joint_target_qd', control_feedforward_attr='joint_act', control_output_attr='joint_f', control_computed_output_attr=None, requires_grad=False, *, controller=_DEPRECATED_UNSET)[source]#

Bases: object

Composed actuator: delay → drive → clamping.

An actuator reads from simulation state/control arrays, optionally delays command inputs, computes effort via a drive, 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,
    drive=DrivePD(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)

Effort is computed explicitly by default (control law evaluated at the current state, zero-order hold over the step).

class ImplicitOptions(max_iters=4, residual_tol=1e-05, update_tol=1e-05, fd_epsilon=0.0001, derivative_floor=1e-08, warm_start=WarmStart.EXPLICIT)#

Bases: object

Configuration for implicit actuation; see Actuator.set_effort_mode_implicit().

class WarmStart(*values)#

Bases: str, Enum

Initial impulse guess for the Newton solve.

EXPLICIT = 'explicit'#: Start from the clamped explicit force impulse.

ZERO = 'zero'#: Start from zero impulse.

__init__(max_iters=4, residual_tol=1e-05, update_tol=1e-05, fd_epsilon=0.0001, derivative_floor=1e-08, warm_start=WarmStart.EXPLICIT)#

derivative_floor: float = 1e-08#: Smallest Jacobian pivot used during elimination and back-substitution (dimensionless: the Jacobian is d(impulse)/d(impulse)).

fd_epsilon: float = 0.0001#: Relative forward finite-difference step in velocity space (dimensionless).

max_iters: int = 4#: Maximum Newton iterations per articulation group.

residual_tol: float = 1e-05#: Stop when the residual vector norm falls below this [N·s or N·m·s].

update_tol: float = 1e-05#: Stop when the impulse-update vector norm falls below this [N·s or N·m·s].

warm_start: WarmStart = 'explicit'#: Initial impulse guess.

__init__(indices, drive=None, 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_q', control_target_vel_attr='joint_target_qd', control_feedforward_attr='joint_act', control_output_attr='joint_f', control_computed_output_attr=None, requires_grad=False, *, controller=_DEPRECATED_UNSET)#

Initialize actuator.

Parameters:

indices (wp.array[wp.uint32]) – DOF indices into velocity-shaped arrays (velocities, velocity targets, feedforward, effort output). Shape (N,).
drive (DriveBase | None) – Drive that computes raw effort.
delay (Delay | None) – Optional Delay instance for input delay.
clamping (list[ClampingBase] | None) – List of Clamping objects (post-drive 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_q. Defaults to pos_indices when newton.use_coord_layout_targets is True (coord layout), otherwise to indices (legacy DOF layout). The flag is read once here, so toggling newton.use_coord_layout_targets after construction does not change target_pos_indices.
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 | None) – Attribute on sim_control for target positions. None selects the default "joint_target_q".
control_target_vel_attr (str | None) – Attribute on sim_control for target velocities. None selects the default "joint_target_qd".
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.
controller (DriveBase | object | None) – Deprecated in Newton 1.6; use drive instead.

is_graphable()#

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

is_stateful()#

Return True if the delay or drive maintains internal state.

set_effort_mode_explicit()#

Switch effort computation back to the default explicit mode.

set_effort_mode_implicit(response, options=None)#

Switch effort computation to implicit mode.

The control law is solved against the predicted end-of-step state before the solver runs. See Effort Modes for details on the computation of effort in the implicit mode, its caveats, and its expected use.

Parameters:

response (JointSpaceResponse) – JointSpaceResponse supplying the coupled effective inverse mass [1/kg or 1/(kg·m²)]. Refresh it once per step before step().
options (ImplicitOptions | None) – Solver options; defaults to Actuator.ImplicitOptions.

Raises:

NotImplementedError – The actuator was built with requires_grad=True. The implicit solve is not differentiable.

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.

Delay read — read per-DOF delayed targets from current_state (falls back to current targets when the buffer is empty).
Effort — raw effort into _computed_forces (explicit control law, or the implicit end-of-step solve).
Clamping — bounded effort into _applied_forces. Explicit clamps after the drive law; implicit enforces them inside the solve.
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.
State updates — drive 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].

property controller: DriveBase#: Deprecated alias for drive.

Deprecated since version 1.6: Use drive instead.