General Actuator

General-purpose actuator model for various force/torque generation mechanisms.

class biosym.model.actuators.actuator_models.general.General(xml_root)

Bases: BaseActuator

General torque actuator model for biomechanical simulations.

This class implements a simple torque actuator model where actuators directly apply torques to joints without complex dynamics. It is suitable for models where actuator dynamics are simplified or when representing idealized motor inputs.

Parameters:

xml_root (xml.etree.ElementTree.Element) – Root element of the XML tree containing actuator definitions. Expected to contain ‘general’ subelements with actuator specifications.

actuators

Dictionary mapping actuator names to their properties parsed from XML. Each actuator entry contains attributes like name, position, etc.

Type:

dict

n_actuators

Number of actuators defined in the model.

Type:

int

states

List of state variable names, formatted as “torque_i” where i is the actuator index.

Type:

list of str

Notes

The general actuator model assumes: - Direct torque application to joints - No actuator dynamics (instantaneous response) - Linear mapping from actuator states to joint torques

XML Format

The expected XML format for actuator definition:

<actuators type="general">
    <general name="actuator_1" pos="0 0 1"/>
    <general name="actuator_2" pos="1 0 0"/>
</actuators>

Examples

Create actuators from XML:

>>> import xml.etree.ElementTree as ET
>>> root = ET.fromstring(xml_string)
>>> actuators = General(root)
>>> n_act = actuators.get_n_actuators()

See also

GeneralMujoco

MuJoCo-specific general actuator implementation

biosym.model.actuators.actuator_models.hill2d.Hill2D

Hill-type muscle model

forward(states, constants, model)

Evaluate the actuator model to compute joint torques.

This method maps actuator states (torque commands) to the appropriate joints in the biomechanical model.

Parameters:

• states (object) – Current state values containing actuator_model attribute with torque values for each actuator.

• constants (object) – Current constant parameter values (unused for general actuators).

• model (biosym.model.model.BiosymModel) – The biomechanical model containing joint and force information.

Returns:

Array of joint torques with shape (n_coordinates,). Torques are placed at the indices specified by model.forces[“active_idx”].

Return type:

jax.Array

Notes

The method creates a zero array for all coordinates and fills in the actuator torques at the active joint indices. This ensures proper mapping between actuator outputs and joint inputs.

get_actuated_joints()

Get the list of joints actuated by this actuator model.

Returns:

List of joint names that are actuated by the defined actuators. If no specific joints are defined, returns an empty list.

Return type:

list of str

get_actuators()

Get the dictionary of actuator definitions.

Returns:

Dictionary mapping actuator names to their property dictionaries. Each property dictionary contains attributes parsed from the XML.

Return type:

dict

get_n_actuators()

Get the number of actuators in the model.

Returns:

Number of actuators defined in this actuator model.

Return type:

int

get_n_constants()

Get the number of constant parameters required by the actuator model.

Returns:

Number of constant parameters. Always 0 for general actuators as they have no internal parameters.

Return type:

int

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.

get_n_states()

Get the number of state variables required by the actuator model.

Returns:

Number of actuator state variables, equal to the number of actuators. Each actuator contributes one torque state variable.

Return type:

int

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.

is_torque_actuator()

Check if this is a torque-based actuator model.

Returns:

True, as general actuators directly apply torques.

Return type:

bool

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

reset()

Reset the actuator model to its initial state.

Notes

For general actuators, there is no internal state to reset. This method is provided for interface compatibility.

class biosym.model.actuators.actuator_models.general.GeneralMujoco(actuator_list)

Bases: General

General actuator model specifically for MuJoCo-format XML files.

This class extends the General actuator class to handle actuator definitions in MuJoCo XML format, which uses ‘motor’ elements instead of ‘general’ elements.

Parameters:

actuator_list (list of xml.etree.ElementTree.Element) – List of XML elements representing motor actuators from MuJoCo format.

Notes

MuJoCo format differences: - Uses ‘motor’ elements instead of ‘general’ - May have different attribute naming conventions - Handles MuJoCo-specific actuator properties

See also

General

Base general actuator implementation

forward(states, constants, model)

Evaluate the actuator model to compute joint torques.

This method maps actuator states (torque commands) to the appropriate joints in the biomechanical model.

Parameters:

• states (object) – Current state values containing actuator_model attribute with torque values for each actuator.

• constants (object) – Current constant parameter values (unused for general actuators).

• model (biosym.model.model.BiosymModel) – The biomechanical model containing joint and force information.

Returns:

Array of joint torques with shape (n_coordinates,). Torques are placed at the indices specified by model.forces[“active_idx”].

Return type:

jax.Array

Notes

The method creates a zero array for all coordinates and fills in the actuator torques at the active joint indices. This ensures proper mapping between actuator outputs and joint inputs.

get_actuated_joints()

Get the list of joints actuated by this actuator model.

Returns:

List of joint names that are actuated by the defined actuators. If no specific joints are defined, returns an empty list.

Return type:

list of str

get_actuators()

Get the dictionary of actuator definitions.

Returns:

Dictionary mapping actuator names to their property dictionaries. Each property dictionary contains attributes parsed from the XML.

Return type:

dict

get_n_actuators()

Get the number of actuators in the model.

Returns:

Number of actuators defined in this actuator model.

Return type:

int

get_n_constants()

Get the number of constant parameters required by the actuator model.

Returns:

Number of constant parameters. Always 0 for general actuators as they have no internal parameters.

Return type:

int

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.

get_n_states()

Get the number of state variables required by the actuator model.

Returns:

Number of actuator state variables, equal to the number of actuators. Each actuator contributes one torque state variable.

Return type:

int

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.

is_torque_actuator()

Check if this is a torque-based actuator model.

Returns:

True, as general actuators directly apply torques.

Return type:

bool

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

reset()

Reset the actuator model to its initial state.

Notes

For general actuators, there is no internal state to reset. This method is provided for interface compatibility.