Overview#

Core actuator framework including base classes and parsers.

Actuator Models for Biomechanical Simulation.

This module provides classes and functions for modeling different types of actuators in biomechanical systems. Actuators represent force/torque generating elements such as muscles, motors, or other active components that can produce motion in the model.

The module includes: - Base actuator classes defining the common interface - Parsers for loading actuator definitions from XML files - Specific actuator model implementations (general, Hill-type muscle, passive torques)

Examples

Load actuators from an XML file:

>>> import biosym.model.actuators.actuator_parser as parser
>>> actuators = parser.get("path/to/actuators.xml")

Access actuator properties:

>>> n_actuators = actuators.get_n_actuators()
>>> actuator_states = actuators.get_n_states()

Base Classes#

class biosym.model.actuators.base_actuator.BaseActuator(xml_root)#

Bases: ABC

Abstract base class for actuator models in biomechanical simulations.

This class defines the interface that all actuator implementations must follow. Actuators represent force/torque generating elements in the biomechanical model, such as muscles, motors, or other active components.

The base class handles common functionality like XML parsing and provides abstract methods that must be implemented by specific actuator types.

Parameters:

xml_root (xml.etree.ElementTree.Element) – Root element of the XML tree containing actuator definitions.

xml_root#

The XML root element containing actuator configuration.

Type:

xml.etree.ElementTree.Element

actuator#

The actuator object instance (implementation-specific).

Type:

object or None

Notes

Subclasses must implement all abstract methods to define the specific behavior of different actuator types (e.g., general torque actuators, Hill-type muscle models, passive torques).

See also

biosym.model.actuators.actuator_models.general.General

General torque actuators

biosym.model.actuators.actuator_models.hill2d.Hill2D

Hill-type muscle model

biosym.model.actuators.actuator_models.passive_torques.PassiveTorques

Passive torques

abstractmethod get_actuated_joints()#

Get the list of joints actuated by this actuator model.

Returns:

Names of joints that are actuated by this actuator model.

Return type:

list of str

Notes

This method must be implemented by all actuator subclasses to specify which joints in the biomechanical model are influenced by the actuators.

abstractmethod get_n_actuators()#

Get the number of actuators in the model.

Returns:

Number of actuators defined in this actuator model.

Return type:

int

Notes

This method must be implemented by all actuator subclasses to specify how many individual actuator elements are present in the model.

get_n_constraints(*args, **kwargs)#

Get the number of constraints defined by this actuator model.

Returns:

Number of constraints. Default is 0.

Return type:

int

Notes

The default implementation returns 0. Actuator subclasses that define constraints (e.g., activation dynamics, force equilibrium) should override this method to return the correct number of constraints.

abstractmethod get_n_states()#

Get the number of states associated with this actuator model.

Returns:

Number of states defined by this actuator model.

Return type:

int

Notes

The default implementation returns 0. Actuator subclasses that define internal states (e.g., muscle activation, fiber length) should override this method to return the correct number of states.

get_nnz()#

Get the number of non-zero entries in the Jacobian of the actuator model.

Returns:

Number of non-zero entries in the Jacobian. Default is 0.

Return type:

int

Notes

The default implementation returns 0. Actuator subclasses that define constraints or dynamics should override this method to return the correct number of non-zero entries in their Jacobian matrices.

process_eom(model)#

Process the equations of motion for the actuator model.

This method is called during the symbolic equation generation phase to integrate actuator dynamics into the overall system equations.

Parameters:

model (biosym.model.model.BiosymModel) – The biomechanical model containing the actuator.

Notes

The default implementation does nothing. Actuator subclasses should override this method if they need to add additional equations of motion, constraints, or symbolic relationships to the model.

Examples of when this is needed: - Muscle activation dynamics - Force-length-velocity relationships - Internal state evolution equations

abstractmethod reset()#

Reset the actuator model to its initial state.

Notes

This method is called at the beginning of simulations to ensure actuators start from a clean state. Implementations should reset any internal state variables, cached values, or dynamic properties.

The exact reset behavior depends on the specific actuator type: - Muscle models may reset activation states - Motor models may reset control states - Passive elements may reset stored energy states

Parsers#

Parser for actuator model definitions from XML files.

This module provides functionality to parse XML files containing actuator definitions and instantiate the appropriate actuator model classes.

biosym.model.actuators.actuator_parser.get(file_path, body_weight=None, **kwargs)#

Parse an actuator model file and return the appropriate actuator instance.

This function reads XML files containing actuator definitions and creates the corresponding actuator model objects based on the specified type.

Parameters:

  • file_path (str or xml.etree.ElementTree.Element) – Path to the XML file containing actuator definitions, or an XML Element if the XML has already been parsed.

  • body_weight (float, optional) – Body weight for scaling actuator forces. Currently not used but may be implemented for muscle force scaling in future versions.

Returns:

An instance of the appropriate actuator model class based on the XML type specification.

Return type:

BaseActuator

Raises:

ValueError – If the actuator type specified in the XML is not recognized or supported.

Notes

Supported actuator types: - “actuator” or “general”: General torque actuators - None (MuJoCo format): Motor elements parsed from MuJoCo XML

The function automatically detects the format and actuator type from the XML structure and attributes.

Examples

Load actuators from an XML file:

>>> actuators = get("path/to/actuators.xml")
>>> n_actuators = actuators.get_n_actuators()

Load from an already parsed XML element:

>>> import xml.etree.ElementTree as ET
>>> tree = ET.parse("actuators.xml")
>>> root = tree.getroot()
>>> actuators = get(root)

See also

biosym.model.actuators.actuator_models.general.General

General actuator implementation

biosym.model.actuators.actuator_models.general.GeneralMujoco

MuJoCo actuator implementation