newton.actuators.BatteryBase#

class newton.actuators.BatteryBase(actuator_start, actuators, *, world=None, world_count=0)[source]#

Bases: object

Base class for actuator batteries.

A battery powers the motors of one or more actuators (see MotorDC). One object holds several batteries of the same type: its parameter arrays have one entry per battery. step() and reset() read and write these arrays on sim_control, with one entry per actuator of the model, indexed like Actuator.actuator_indices:

input actuator_supply_current: the current each motor draws from its battery [A], written by the motor;
output actuator_supply_voltage: the supply voltage of each motor [V], read by the motor.

The motors and the batteries form an explicit loop: the motors read the voltage of the previous step. With one Control per step, e.g. to differentiate several steps on one tape, pass the next step’s Control as next_control to step().

Subclasses must override resolve_arguments(), step() and reset().

Validation contract: resolve_arguments() validates scalar parameter values before they are batched into Warp arrays. __init__ receives pre-built arrays and validates shapes only — reading back array contents 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]

__init__(actuator_start, actuators, *, world=None, world_count=0)#

Initialize the batteries.

Parameters:

actuator_start (wp.array[wp.int32]) – Start of each battery’s actuators in actuators. Shape (B + 1,).
actuators (wp.array[wp.int32]) – Actuators of all batteries, sorted by battery, so that battery b powers actuators[actuator_start[b]:actuator_start[b + 1]].
world (wp.array[wp.int32] | None) – World of each battery, -1 for none. Shape (B,). None places every battery outside any world.
world_count (int) – Number of worlds, which sets the shape of the mask in reset().

Raises:

ValueError – world does not have one entry per battery.

reset(sim_control, *, world_mask=None)#

Reset the batteries and the supply voltage of their actuators.

Writes actuator_supply_voltage for the actuators of the reset batteries. Call after resetting worlds.

Parameters:

sim_control (Any) – Object carrying actuator_supply_voltage, e.g. Control.
world_mask (wp.array[wp.bool] | None) – Optional boolean mask of shape (world_count + 1,) specifying which worlds to reset. Entries before the last select local worlds by index, and the final entry selects batteries whose world is -1. If None, all batteries are reset.

step(sim_control, next_control=None)#

Update the supply voltage of the actuators from their current.

Reads actuator_supply_current from sim_control and writes actuator_supply_voltage to next_control for the actuators of the batteries. Call once per step, after the actuators have stepped.

Parameters:

sim_control (Any) – Object carrying actuator_supply_current, e.g. Control.
next_control (Any | None) – Object carrying actuator_supply_voltage for the next step. None writes it to sim_control.

actuator_start#: Start of each battery’s actuators in actuators, shape (B + 1,).

actuators#: Actuators of all batteries, sorted by battery.

num_batteries#: Number of batteries B.

world#: World of each battery, -1 for none, shape (B,).

world_count#: Number of worlds.