newton.actuators.MotorDC#

class newton.actuators.MotorDC(kt, resistance, vin, *, supply_from_battery=None)[source]#

Bases: object

DC motor driven by an average terminal voltage, as in BAM (Better Actuator Models).

Computes the effort from the commanded voltage \(u\), bounded by the supply voltage \(V\), since the motor cannot receive more:

\[\begin{split}u &\leftarrow \operatorname{clamp}(u,\; -V,\; V) \\ I &= \frac{u - k_t\, \dot q}{R} \\ \tau &= k_t\, I\end{split}\]

where \(I\) is the motor current [A], \(\tau\) the effort [N or N·m], \(k_t\) is kt and \(R\) is resistance.

Standalone calls accept average terminal voltage. In an actuator, the actuator bounds signed duty to [-1, 1] and multiplies it by the actual fixed or battery supply voltage. The motor reports source current d * I, where d = u / V for positive V, and zero at zero supply voltage. Effort clamps cannot be combined with this motor.

Note

This motor models the back-EMF itself, so it cannot be combined with a ClampingDCMotor, which would apply the effort-speed limit a second time.

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.

Raises:

ValueError – kt or resistance is missing or not positive, or vin is without supply_from_battery.

Return type:

dict[str, Any]

__init__(kt, resistance, vin, *, supply_from_battery=None)#

Initialize the DC motor.

Parameters:

  • kt (wp.array[wp.float32]) – Torque constant [N/A or N·m/A]. Shape (N,).

  • resistance (wp.array[wp.float32]) – Motor resistance [Ω]. Shape (N,).

  • vin (wp.array[wp.float32]) – Supply voltage [V] without a battery; unused with supply_from_battery. Shape (N,).

  • supply_from_battery (wp.array[wp.float32] | None) – Per actuator, nonzero to read the supply voltage from the battery instead of vin. Shape (N,). None uses vin everywhere.

Raises:

ValueError – An array shape does not match kt.

compute(src_forces, dst_forces, velocities, vel_indices, supply_voltage, actuator_indices, supply_current, device=None)#

Read the voltage command from src, write the motor effort to dst.

When src and dst are the same array, this is an in-place update.

Parameters:

  • src_forces (wp.array[wp.float32]) – Voltage command [V]. Shape (N,).

  • dst_forces (wp.array[wp.float32]) – Motor effort [N or N·m]. Shape (N,).

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

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

  • supply_voltage (wp.array[wp.float32]) – Supply voltage of each slot [V], written by compute_supply_voltage(). Shape (N,).

  • actuator_indices (wp.array[wp.uint32] | None) – Index of each slot into supply_current, or None without a battery.

  • supply_current (wp.array[wp.float32] | None) – Current each actuator draws from its battery [A], one entry per actuator of the model (actuator_supply_current), written here and read by BatteryBase.step, or None to skip.

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

compute_supply_voltage(battery_voltage, actuator_indices, supply_voltage, device=None)#

Write vin, or the battery voltage with supply_from_battery, to supply_voltage.

Parameters:

  • battery_voltage (wp.array[wp.float32] | None) – Supply voltage of each actuator [V], one entry per actuator of the model (actuator_supply_voltage), written by BatteryBase.step, or None without a battery.

  • actuator_indices (wp.array[wp.uint32] | None) – Index of each slot into battery_voltage, or None without a battery.

  • supply_voltage (wp.array[wp.float32]) – Supply voltage of each slot [V]. Shape (N,).

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

Raises:

ValueError – An actuator has supply_from_battery set and actuator_indices or battery_voltage is None.

finalize(device, num_actuators, requires_grad=False)#

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

Parameters:

  • device (Device) – Warp device to use.

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

  • requires_grad (bool) – Whether to allocate internal buffers with gradient support.

is_graphable()#

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

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

Torque constant [N·m/A or N/A], shape (N,).

resistance#

Motor resistance [Ω], shape (N,).

supply_from_battery#

Per actuator, nonzero when the supply voltage is read from the battery, shape (N,).

uses_battery#

Whether an actuator slot draws from a battery.

vin#

Supply voltage [V] without a battery, shape (N,).