bam.actuator ============ .. py:module:: bam.actuator Classes ------- .. autoapisummary:: bam.actuator.Actuator bam.actuator.DCMotorActuator bam.actuator.VoltageControlledActuator bam.actuator.CurrentControlledActuator Module Contents --------------- .. py:class:: Actuator(testbench_class: bam.testbench.Testbench) Abstract base class for all BAM actuator models. Subclasses implement the firmware control law and the motor torque equation for a specific actuator family. An actuator is always attached to a :class:`~bam.model.Model` via :meth:`~bam.model.Model.set_actuator`, which calls :meth:`initialize` to create the motor parameters (``kt``, ``R``, …) on the model. :param testbench_class: Class used to instantiate the testbench when a log is loaded (typically :class:`~bam.testbench.Pendulum`). .. py:attribute:: testbench_class .. py:attribute:: testbench :type: bam.testbench.Testbench | None :value: None .. py:method:: set_model(model) Attach this actuator to a model and run :meth:`initialize`. :param model: :class:`~bam.model.Model` instance to attach to. .. py:method:: reset() .. py:method:: load_log(log: dict) Called when a log is loaded. Instantiates the testbench from the log metadata (mass, length, …) and updates actuator settings (kp, vin) from the log. :param log: Log dict as loaded from a processed JSON file. .. py:method:: initialize() :abstractmethod: Create motor parameters on the attached model. Called automatically by :meth:`set_model`. Must create at minimum ``self.model.kt`` and ``self.model.R`` as :class:`~bam.parameter.Parameter` instances. .. py:method:: control_unit() -> str :abstractmethod: Return the physical unit of the control signal (e.g. ``"volts"``, ``"amps"``). .. py:method:: compute_control(q_target: float, q: float, dq: float, dt: float) -> float | None :abstractmethod: Compute the control signal from the current state and target. :param q_target: Target joint angle [rad]. :param q: Current joint angle [rad]. :param dq: Current joint velocity [rad/s]. :param dt: Timestep [s]. :returns: Control signal in the unit given by :meth:`control_unit`. .. py:method:: compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) -> float :abstractmethod: Compute the motor torque from the control signal and current state. :param control: Control signal (volts, amps, or Nm depending on the actuator). :param torque_enable: Whether the actuator is powered. :param q: Current joint angle [rad]. :param dq: Current joint velocity [rad/s]. :returns: Motor torque [Nm]. .. py:method:: get_extra_inertia() -> float :abstractmethod: Return the actuator's apparent inertia added to the load [kg·m²]. .. py:method:: to_mujoco() :abstractmethod: .. py:class:: DCMotorActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float) Bases: :py:obj:`Actuator` Base class for DC motor actuators with a supply voltage and a P-gain. Loads ``kp`` and ``vin`` from the log metadata when :meth:`load_log` is called. :param testbench_class: Testbench class (see :class:`Actuator`). :param vin: Default supply voltage [V]. :param kp: Default firmware proportional gain. .. py:attribute:: vin .. py:attribute:: kp .. py:method:: load_log(log: dict) Called when a log is loaded. Instantiates the testbench from the log metadata (mass, length, …) and updates actuator settings (kp, vin) from the log. :param log: Log dict as loaded from a processed JSON file. .. py:method:: initialize() Create ``kt`` and ``R`` parameters on the attached model. .. py:class:: VoltageControlledActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float, error_gain: float, max_pwm: float = 1.0) Bases: :py:obj:`DCMotorActuator` Voltage-controlled servo with a firmware P-position controller. Implements the control law ``duty_cycle = clip(error_gain * kp * Δq, -max_pwm, max_pwm)`` and the DC motor torque equation with back-EMF. :param testbench_class: Testbench class (see :class:`Actuator`). :param vin: Supply voltage [V]. :param kp: Firmware proportional gain. :param error_gain: Converts ``kp * Δq`` to a duty cycle in [−1, 1]. Depends on the servo's internal encoder resolution and gain scaling. :param max_pwm: Maximum duty cycle magnitude (default 1.0). .. py:attribute:: error_gain .. py:attribute:: max_pwm :value: 1.0 .. py:method:: control_unit() -> str Return the physical unit of the control signal (e.g. ``"volts"``, ``"amps"``). .. py:method:: compute_control(q_target: float, q: float, dq: float, dt: float) -> float | None Compute the voltage command from position error. :param q_target: Target joint angle [rad]. :param q: Current joint angle [rad]. :param dq: Current joint velocity [rad/s] (unused here). :param dt: Timestep [s] (unused here). :returns: Voltage [V] sent to the motor. .. py:method:: compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) -> float Compute motor torque using the DC motor equation with back-EMF. :math:`\tau = k_t V / R - k_t^2 \dot{q} / R` :param control: Voltage [V]. :param torque_enable: If ``False``, returns zero torque. :param q: Current joint angle [rad] (unused here). :param dq: Current joint velocity [rad/s]. :returns: Motor torque [Nm]. .. py:method:: to_mujoco() .. py:class:: CurrentControlledActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float, error_gain: float) Bases: :py:obj:`DCMotorActuator` Current-controlled servo with a firmware P-position controller. The controller outputs a target current proportional to position error, clipped by both the voltage limits and a user-configurable current cap. :param testbench_class: Testbench class (see :class:`Actuator`). :param vin: Supply voltage [V], used to compute the current saturation. :param kp: Firmware proportional gain. :param error_gain: Converts ``kp * Δq`` to a target current [A]. .. py:attribute:: error_gain .. py:method:: control_unit() -> str Return the physical unit of the control signal (e.g. ``"volts"``, ``"amps"``). .. py:method:: initialize() Create ``kt`` and ``R`` parameters on the attached model. .. py:method:: compute_control(q_target: float, q: float, dq: float, dt: float) -> float | None Compute the current command from position error. Clips the P-controller output by both the back-EMF voltage limit and the ``current_limit`` parameter. :param q_target: Target joint angle [rad]. :param q: Current joint angle [rad]. :param dq: Current joint velocity [rad/s]. :param dt: Timestep [s] (unused here). :returns: Target current [A]. .. py:method:: compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) -> float Compute motor torque from current command. :math:`\tau = k_t I - b_{\text{active}} \dot{q}` :param control: Current command [A]. :param torque_enable: If ``False``, returns zero torque. :param q: Current joint angle [rad] (unused here). :param dq: Current joint velocity [rad/s]. :returns: Motor torque [Nm]. .. py:method:: to_mujoco()