newton.actuators.ClampingCurrentDuty#

class newton.actuators.ClampingCurrentDuty(max_current, *, kt_estimate=None, resistance_estimate=None, max_duty=None, voltage_source=VoltageSource.INPUT, nominal_voltage=None, min_voltage=None)[source]#

Bases: ClampingBase

Limit signed duty using a DC-motor current estimate, then max_duty.

Input and output are dimensionless duty commands. For a voltage estimate V > min_voltage, the current-derived duty window is:

lower = (kt_estimate * velocity - resistance_estimate * max_current) / V
upper = (kt_estimate * velocity + resistance_estimate * max_current) / V
duty = clamp(requested_duty, lower, upper)
duty = clamp(duty, -max_duty, max_duty)

voltage_source explicitly selects the estimate: INPUT reads the supplied voltage; NOMINAL uses nominal_voltage. The actuator separately uses actual supply voltage to convert the resulting duty into motor voltage. This clamp never performs that conversion.

kt_estimate and resistance_estimate are the firmware’s estimates of the motor parameters. By default they are the motor’s own kt and resistance arrays; set them to model firmware estimates that differ from the physical motor. A zero entry uses the motor’s value for that slot.

A zero max_current disables the current window. An estimated voltage at or below min_voltage also skips it, avoiding division by a near-zero voltage. This threshold does not change the actual voltage delivered to the motor. The duty bound [-max_duty, max_duty] always applies and takes precedence over the current window. Overspeed or an inaccurate voltage estimate can therefore cause motor current to exceed the limit. This is a quasi-static current estimate, not an inductive current controller.

class VoltageSource(*values)#

Bases: StrEnum

Voltage used by the firmware’s current estimate.

INPUT = 'input'#

Read the supplied voltage array.

NOMINAL = 'nominal'#

Use the configured nominal voltage, independently of the live supply.

classmethod resolve_arguments(args)#
__init__(max_current, *, kt_estimate=None, resistance_estimate=None, max_duty=None, voltage_source=VoltageSource.INPUT, nominal_voltage=None, min_voltage=None)#

Initialize current estimation and duty limits.

Parameters:

  • max_current (wp.array[float]) – Current limit [A], shape (N,). Zero disables it.

  • kt_estimate (wp.array[float] | None) – Firmware estimate of the motor torque constant [N/A or N·m/A], shape (N,). None uses the motor’s kt.

  • resistance_estimate (wp.array[float] | None) – Firmware estimate of the motor winding resistance [Ω], shape (N,). None uses the motor’s resistance.

  • max_duty (wp.array[float] | None) – Largest duty magnitude in [0, 1], shape (N,). Defaults to 1 per slot.

  • voltage_source (VoltageSource) – Select supplied or nominal voltage for the current estimate. Shared by all slots in this component.

  • nominal_voltage (wp.array[float] | None) – Positive firmware voltage estimate [V], shape (N,). Required in NOMINAL mode and rejected in INPUT mode. As with other batched parameters, scalar values are validated by resolve_arguments before construction; this constructor checks shapes.

  • min_voltage (wp.array[float] | None) – Positive voltage threshold [V], shape (N,). Defaults to 1e-6 V per slot. Skip the current window when the selected voltage estimate is at or below this threshold; still bound duty.

Raises:

ValueError – Invalid source, missing or unused nominal voltage, or inconsistent array shapes.

modify_forces(src_forces, dst_forces, positions, velocities, pos_indices, vel_indices, device=None, *, supply_voltage=None)#

Read signed duty from src_forces and write limited duty to dst_forces.

Both buffers have shape (N,) and are dimensionless. INPUT mode reads the supplied supply_voltage array. NOMINAL mode needs no runtime voltage input. See the base method for the remaining arguments.

Raises:

ValueError – INPUT mode has no voltage array, or its shape does not match the actuator slots. There is no fallback to nominal voltage. Also raised when an estimate is unset outside an actuator with a motor.

SHARED_PARAMS: ClassVar[set[str]] = {'voltage_source'}#
input_space: DriveOutputSpace = 'duty'#

Space accepted by this clamp. Physical effort clamps keep the default.

kt_estimate#

Firmware estimate of the motor torque constant [N/A or N·m/A], shape (N,); the motor’s kt by default.

max_current#

Current limit [A], shape (N,); zero disables current limiting.

max_duty#

Largest duty magnitude, shape (N,).

min_voltage#

Minimum voltage estimate for applying the current window [V], shape (N,).

nominal_voltage#

Nominal voltage estimate [V], shape (N,), or None in INPUT mode.

resistance_estimate#

Firmware estimate of the motor winding resistance [Ω], shape (N,); the motor’s resistance by default.

voltage_source#

Source of the firmware’s voltage estimate.