Musculotendon (Docstrings)¶
Implementations of musculotendon models.
Musculotendon models are a critical component of biomechanical models, one that differentiates them from pure multibody systems. Musculotendon models produce a force dependent on their level of activation, their length, and their extension velocity. Length- and extension velocity-dependent force production are governed by force-length and force-velocity characteristics. These are normalized functions that are dependent on the musculotendon’s state and are specific to a given musculotendon model.
- class sympy.physics.biomechanics.musculotendon.MusculotendonBase(
- name,
- pathway,
- activation_dynamics,
- *,
- musculotendon_dynamics=MusculotendonFormulation.RIGID_TENDON,
- tendon_slack_length=None,
- peak_isometric_force=None,
- optimal_fiber_length=None,
- maximal_fiber_velocity=None,
- optimal_pennation_angle=None,
- fiber_damping_coefficient=None,
- with_defaults=False,
Abstract base class for all musculotendon classes to inherit from.
- Parameters:
name : str
The name identifier associated with the musculotendon. This name is used as a suffix when automatically generated symbols are instantiated. It must be a string of nonzero length.
pathway : PathwayBase
The pathway that the actuator follows. This must be an instance of a concrete subclass of
PathwayBase
, e.g.LinearPathway
.activation_dynamics : ActivationBase
The activation dynamics that will be modeled within the musculotendon. This must be an instance of a concrete subclass of
ActivationBase
, e.g.FirstOrderActivationDeGroote2016
.musculotendon_dynamics : MusculotendonFormulation | int
The formulation of musculotendon dynamics that should be used internally, i.e. rigid or elastic tendon model, the choice of musculotendon state etc. This must be a member of the integer enumeration
MusculotendonFormulation
or an integer that can be cast to a member. To use a rigid tendon formulation, set this toMusculotendonFormulation.RIGID_TENDON
(or the integer value0
, which will be cast to the enumeration member). There are four possible formulations for an elastic tendon model. To use an explicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_EXPLICIT
(or the integer value1
). To use an explicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_EXPLICIT
(or the integer value2
). To use an implicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_IMPLICIT
(or the integer value3
). To use an implicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_IMPLICIT
(or the integer value4
). The default isMusculotendonFormulation.RIGID_TENDON
, which corresponds to a rigid tendon formulation.tendon_slack_length : Expr | None
The length of the tendon when the musculotendon is in its unloaded state. In a rigid tendon model the tendon length is the tendon slack length. In all musculotendon models, tendon slack length is used to normalize tendon length to give \(\tilde{l}^T = \frac{l^T}{l^T_{slack}}\).
peak_isometric_force : Expr | None
The maximum force that the muscle fiber can produce when it is undergoing an isometric contraction (no lengthening velocity). In all musculotendon models, peak isometric force is used to normalized tendon and muscle fiber force to give \(\tilde{F}^T = \frac{F^T}{F^M_{max}}\).
optimal_fiber_length : Expr | None
The muscle fiber length at which the muscle fibers produce no passive force and their maximum active force. In all musculotendon models, optimal fiber length is used to normalize muscle fiber length to give \(\tilde{l}^M = \frac{l^M}{l^M_{opt}}\).
maximal_fiber_velocity : Expr | None
The fiber velocity at which, during muscle fiber shortening, the muscle fibers are unable to produce any active force. In all musculotendon models, maximal fiber velocity is used to normalize muscle fiber extension velocity to give \(\tilde{v}^M = \frac{v^M}{v^M_{max}}\).
optimal_pennation_angle : Expr | None
The pennation angle when muscle fiber length equals the optimal fiber length.
fiber_damping_coefficient : Expr | None
The coefficient of damping to be used in the damping element in the muscle fiber model.
with_defaults : bool
Whether
with_defaults
alternate constructors should be used when automatically constructing child classes. Default isFalse
.
Explanation
A musculotendon generates a contractile force based on its activation, length, and shortening velocity. This abstract base class is to be inherited by all musculotendon subclasses that implement different characteristic musculotendon curves. Characteristic musculotendon curves are required for the tendon force-length, passive fiber force-length, active fiber force- length, and fiber force-velocity relationships.
- property F¶
Ordered column matrix of equations on the RHS of
M x' = F
.Explanation
The column matrix that forms the RHS of the linear system of ordinary differential equations governing the activation dynamics:
M(x, r, t, p) x' = F(x, r, t, p)
.As zeroth-order activation dynamics have no state variables, this linear system has dimension 0 and therefore
F
is an empty columnMatrix
with shape (0, 1).
- property F_M_max¶
Symbol or value corresponding to the peak isometric force constant.
Explanation
The maximum force that the muscle fiber can produce when it is undergoing an isometric contraction (no lengthening velocity). In all musculotendon models, peak isometric force is used to normalized tendon and muscle fiber force to give \(\tilde{F}^T = \frac{F^T}{F^M_{max}}\).
The alias
peak_isometric_force
can also be used to access the same attribute.
- property M¶
Ordered square matrix of coefficients on the LHS of
M x' = F
.Explanation
The square matrix that forms part of the LHS of the linear system of ordinary differential equations governing the activation dynamics:
M(x, r, t, p) x' = F(x, r, t, p)
.As zeroth-order activation dynamics have no state variables, this linear system has dimension 0 and therefore
M
is an empty squareMatrix
with shape (0, 0).
- property a¶
Dynamic symbol representing activation.
Explanation
The alias
activation
can also be used to access the same attribute.
- property activation¶
Dynamic symbol representing activation.
Explanation
The alias
a
can also be used to access the same attribute.
- property activation_dynamics¶
Activation dynamics model governing this musculotendon’s activation.
Explanation
Returns the instance of a subclass of
ActivationBase
that governs the relationship between excitation and activation that is used to represent the activation dynamics of this musculotendon.
- property alpha_opt¶
Symbol or value corresponding to the optimal pennation angle constant.
Explanation
The pennation angle when muscle fiber length equals the optimal fiber length.
The alias
optimal_pennation_angle
can also be used to access the same attribute.
- property beta¶
Symbol or value corresponding to the fiber damping coefficient constant.
Explanation
The coefficient of damping to be used in the damping element in the muscle fiber model.
The alias
fiber_damping_coefficient
can also be used to access the same attribute.
- property constants¶
Ordered column matrix of non-time varying symbols present in
M
andF
.Explanation
Only symbolic constants are returned. If a numeric type (e.g.
Float
) has been used instead ofSymbol
for a constant then that attribute will not be included in the matrix returned by this property. This is because the primary use of this property attribute is to provide an ordered sequence of the still-free symbols that require numeric values during code generation.The alias
p
can also be used to access the same attribute.
- abstract curves()[source]¶
Return a
CharacteristicCurveCollection
of the curves related to the specific model.
- property e¶
Dynamic symbol representing excitation.
Explanation
The alias
excitation
can also be used to access the same attribute.
- property excitation¶
Dynamic symbol representing excitation.
Explanation
The alias
e
can also be used to access the same attribute.
- property fiber_damping_coefficient¶
Symbol or value corresponding to the fiber damping coefficient constant.
Explanation
The coefficient of damping to be used in the damping element in the muscle fiber model.
The alias
beta
can also be used to access the same attribute.
- property input_vars¶
Ordered column matrix of functions of time that represent the input variables.
Explanation
The alias
r
can also be used to access the same attribute.
- property l_M_opt¶
Symbol or value corresponding to the optimal fiber length constant.
Explanation
The muscle fiber length at which the muscle fibers produce no passive force and their maximum active force. In all musculotendon models, optimal fiber length is used to normalize muscle fiber length to give \(\tilde{l}^M = \frac{l^M}{l^M_{opt}}\).
The alias
optimal_fiber_length
can also be used to access the same attribute.
- property l_T_slack¶
Symbol or value corresponding to the tendon slack length constant.
Explanation
The length of the tendon when the musculotendon is in its unloaded state. In a rigid tendon model the tendon length is the tendon slack length. In all musculotendon models, tendon slack length is used to normalize tendon length to give \(\tilde{l}^T = \frac{l^T}{l^T_{slack}}\).
The alias
tendon_slack_length
can also be used to access the same attribute.
- property maximal_fiber_velocity¶
Symbol or value corresponding to the maximal fiber velocity constant.
Explanation
The fiber velocity at which, during muscle fiber shortening, the muscle fibers are unable to produce any active force. In all musculotendon models, maximal fiber velocity is used to normalize muscle fiber extension velocity to give \(\tilde{v}^M = \frac{v^M}{v^M_{max}}\).
The alias
v_M_max
can also be used to access the same attribute.
- property musculotendon_dynamics¶
The choice of rigid or type of elastic tendon musculotendon dynamics.
Explanation
The formulation of musculotendon dynamics that should be used internally, i.e. rigid or elastic tendon model, the choice of musculotendon state etc. This must be a member of the integer enumeration
MusculotendonFormulation
or an integer that can be cast to a member. To use a rigid tendon formulation, set this toMusculotendonFormulation.RIGID_TENDON
(or the integer value0
, which will be cast to the enumeration member). There are four possible formulations for an elastic tendon model. To use an explicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_EXPLICIT
(or the integer value1
). To use an explicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_EXPLICIT
(or the integer value2
). To use an implicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_IMPLICIT
(or the integer value3
). To use an implicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_IMPLICIT
(or the integer value4
). The default isMusculotendonFormulation.RIGID_TENDON
, which corresponds to a rigid tendon formulation.
- property optimal_fiber_length¶
Symbol or value corresponding to the optimal fiber length constant.
Explanation
The muscle fiber length at which the muscle fibers produce no passive force and their maximum active force. In all musculotendon models, optimal fiber length is used to normalize muscle fiber length to give \(\tilde{l}^M = \frac{l^M}{l^M_{opt}}\).
The alias
l_M_opt
can also be used to access the same attribute.
- property optimal_pennation_angle¶
Symbol or value corresponding to the optimal pennation angle constant.
Explanation
The pennation angle when muscle fiber length equals the optimal fiber length.
The alias
alpha_opt
can also be used to access the same attribute.
- property p¶
Ordered column matrix of non-time varying symbols present in
M
andF
.Explanation
Only symbolic constants are returned. If a numeric type (e.g.
Float
) has been used instead ofSymbol
for a constant then that attribute will not be included in the matrix returned by this property. This is because the primary use of this property attribute is to provide an ordered sequence of the still-free symbols that require numeric values during code generation.The alias
constants
can also be used to access the same attribute.
- property peak_isometric_force¶
Symbol or value corresponding to the peak isometric force constant.
Explanation
The maximum force that the muscle fiber can produce when it is undergoing an isometric contraction (no lengthening velocity). In all musculotendon models, peak isometric force is used to normalized tendon and muscle fiber force to give \(\tilde{F}^T = \frac{F^T}{F^M_{max}}\).
The alias
F_M_max
can also be used to access the same attribute.
- property r¶
Ordered column matrix of functions of time that represent the input variables.
Explanation
The alias
input_vars
can also be used to access the same attribute.
- rhs()[source]¶
Ordered column matrix of equations for the solution of
M x' = F
.Explanation
The solution to the linear system of ordinary differential equations governing the activation dynamics:
M(x, r, t, p) x' = F(x, r, t, p)
.As zeroth-order activation dynamics have no state variables, this linear has dimension 0 and therefore this method returns an empty column
Matrix
with shape (0, 1).
- property state_vars¶
Ordered column matrix of functions of time that represent the state variables.
Explanation
The alias
x
can also be used to access the same attribute.
- property tendon_slack_length¶
Symbol or value corresponding to the tendon slack length constant.
Explanation
The length of the tendon when the musculotendon is in its unloaded state. In a rigid tendon model the tendon length is the tendon slack length. In all musculotendon models, tendon slack length is used to normalize tendon length to give \(\tilde{l}^T = \frac{l^T}{l^T_{slack}}\).
The alias
l_T_slack
can also be used to access the same attribute.
- property v_M_max¶
Symbol or value corresponding to the maximal fiber velocity constant.
Explanation
The fiber velocity at which, during muscle fiber shortening, the muscle fibers are unable to produce any active force. In all musculotendon models, maximal fiber velocity is used to normalize muscle fiber extension velocity to give \(\tilde{v}^M = \frac{v^M}{v^M_{max}}\).
The alias
maximal_fiber_velocity
can also be used to access the same attribute.
- classmethod with_defaults(
- name,
- pathway,
- activation_dynamics,
- *,
- musculotendon_dynamics=MusculotendonFormulation.RIGID_TENDON,
- tendon_slack_length=None,
- peak_isometric_force=None,
- optimal_fiber_length=None,
- maximal_fiber_velocity=10.0000000000000,
- optimal_pennation_angle=0.0,
- fiber_damping_coefficient=0.100000000000000,
Recommended constructor that will use the published constants.
- Parameters:
name : str
The name identifier associated with the musculotendon. This name is used as a suffix when automatically generated symbols are instantiated. It must be a string of nonzero length.
pathway : PathwayBase
The pathway that the actuator follows. This must be an instance of a concrete subclass of
PathwayBase
, e.g.LinearPathway
.activation_dynamics : ActivationBase
The activation dynamics that will be modeled within the musculotendon. This must be an instance of a concrete subclass of
ActivationBase
, e.g.FirstOrderActivationDeGroote2016
.musculotendon_dynamics : MusculotendonFormulation | int
The formulation of musculotendon dynamics that should be used internally, i.e. rigid or elastic tendon model, the choice of musculotendon state etc. This must be a member of the integer enumeration
MusculotendonFormulation
or an integer that can be cast to a member. To use a rigid tendon formulation, set this toMusculotendonFormulation.RIGID_TENDON
(or the integer value0
, which will be cast to the enumeration member). There are four possible formulations for an elastic tendon model. To use an explicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_EXPLICIT
(or the integer value1
). To use an explicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_EXPLICIT
(or the integer value2
). To use an implicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_IMPLICIT
(or the integer value3
). To use an implicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_IMPLICIT
(or the integer value4
). The default isMusculotendonFormulation.RIGID_TENDON
, which corresponds to a rigid tendon formulation.tendon_slack_length : Expr | None
The length of the tendon when the musculotendon is in its unloaded state. In a rigid tendon model the tendon length is the tendon slack length. In all musculotendon models, tendon slack length is used to normalize tendon length to give \(\tilde{l}^T = \frac{l^T}{l^T_{slack}}\).
peak_isometric_force : Expr | None
The maximum force that the muscle fiber can produce when it is undergoing an isometric contraction (no lengthening velocity). In all musculotendon models, peak isometric force is used to normalized tendon and muscle fiber force to give \(\tilde{F}^T = \frac{F^T}{F^M_{max}}\).
optimal_fiber_length : Expr | None
The muscle fiber length at which the muscle fibers produce no passive force and their maximum active force. In all musculotendon models, optimal fiber length is used to normalize muscle fiber length to give \(\tilde{l}^M = \frac{l^M}{l^M_{opt}}\).
maximal_fiber_velocity : Expr | None
The fiber velocity at which, during muscle fiber shortening, the muscle fibers are unable to produce any active force. In all musculotendon models, maximal fiber velocity is used to normalize muscle fiber extension velocity to give \(\tilde{v}^M = \frac{v^M}{v^M_{max}}\).
optimal_pennation_angle : Expr | None
The pennation angle when muscle fiber length equals the optimal fiber length.
fiber_damping_coefficient : Expr | None
The coefficient of damping to be used in the damping element in the muscle fiber model.
Explanation
Returns a new instance of the musculotendon class using recommended values for
v_M_max
,alpha_opt
, andbeta
. The values are:\(v^M_{max} = 10\) \(\alpha_{opt} = 0\) \(\beta = \frac{1}{10}\)
The musculotendon curves are also instantiated using the constants from the original publication.
- property x¶
Ordered column matrix of functions of time that represent the state variables.
Explanation
The alias
state_vars
can also be used to access the same attribute.
- class sympy.physics.biomechanics.musculotendon.MusculotendonDeGroote2016(
- name,
- pathway,
- activation_dynamics,
- *,
- musculotendon_dynamics=MusculotendonFormulation.RIGID_TENDON,
- tendon_slack_length=None,
- peak_isometric_force=None,
- optimal_fiber_length=None,
- maximal_fiber_velocity=None,
- optimal_pennation_angle=None,
- fiber_damping_coefficient=None,
- with_defaults=False,
Musculotendon model using the curves of De Groote et al., 2016 [R728].
- Parameters:
name : str
The name identifier associated with the musculotendon. This name is used as a suffix when automatically generated symbols are instantiated. It must be a string of nonzero length.
pathway : PathwayBase
The pathway that the actuator follows. This must be an instance of a concrete subclass of
PathwayBase
, e.g.LinearPathway
.activation_dynamics : ActivationBase
The activation dynamics that will be modeled within the musculotendon. This must be an instance of a concrete subclass of
ActivationBase
, e.g.FirstOrderActivationDeGroote2016
.musculotendon_dynamics : MusculotendonFormulation | int
The formulation of musculotendon dynamics that should be used internally, i.e. rigid or elastic tendon model, the choice of musculotendon state etc. This must be a member of the integer enumeration
MusculotendonFormulation
or an integer that can be cast to a member. To use a rigid tendon formulation, set this toMusculotendonFormulation.RIGID_TENDON
(or the integer value0
, which will be cast to the enumeration member). There are four possible formulations for an elastic tendon model. To use an explicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_EXPLICIT
(or the integer value1
). To use an explicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_EXPLICIT
(or the integer value2
). To use an implicit formulation with the fiber length as the state, set this toMusculotendonFormulation.FIBER_LENGTH_IMPLICIT
(or the integer value3
). To use an implicit formulation with the tendon force as the state, set this toMusculotendonFormulation.TENDON_FORCE_IMPLICIT
(or the integer value4
). The default isMusculotendonFormulation.RIGID_TENDON
, which corresponds to a rigid tendon formulation.tendon_slack_length : Expr | None
The length of the tendon when the musculotendon is in its unloaded state. In a rigid tendon model the tendon length is the tendon slack length. In all musculotendon models, tendon slack length is used to normalize tendon length to give \(\tilde{l}^T = \frac{l^T}{l^T_{slack}}\).
peak_isometric_force : Expr | None
The maximum force that the muscle fiber can produce when it is undergoing an isometric contraction (no lengthening velocity). In all musculotendon models, peak isometric force is used to normalized tendon and muscle fiber force to give \(\tilde{F}^T = \frac{F^T}{F^M_{max}}\).
optimal_fiber_length : Expr | None
The muscle fiber length at which the muscle fibers produce no passive force and their maximum active force. In all musculotendon models, optimal fiber length is used to normalize muscle fiber length to give \(\tilde{l}^M = \frac{l^M}{l^M_{opt}}\).
maximal_fiber_velocity : Expr | None
The fiber velocity at which, during muscle fiber shortening, the muscle fibers are unable to produce any active force. In all musculotendon models, maximal fiber velocity is used to normalize muscle fiber extension velocity to give \(\tilde{v}^M = \frac{v^M}{v^M_{max}}\).
optimal_pennation_angle : Expr | None
The pennation angle when muscle fiber length equals the optimal fiber length.
fiber_damping_coefficient : Expr | None
The coefficient of damping to be used in the damping element in the muscle fiber model.
with_defaults : bool
Whether
with_defaults
alternate constructors should be used when automatically constructing child classes. Default isFalse
.
Examples
This class models the musculotendon actuator parametrized by the characteristic curves described in De Groote et al., 2016 [R728]. Like all musculotendon models in SymPy’s biomechanics module, it requires a pathway to define its line of action. We’ll begin by creating a simple
LinearPathway
between two points that our musculotendon will follow. We’ll create a pointO
to represent the musculotendon’s origin and anotherI
to represent its insertion.>>> from sympy import symbols >>> from sympy.physics.mechanics import (LinearPathway, Point, ... ReferenceFrame, dynamicsymbols)
>>> N = ReferenceFrame('N') >>> O, I = O, P = symbols('O, I', cls=Point) >>> q, u = dynamicsymbols('q, u', real=True) >>> I.set_pos(O, q*N.x) >>> O.set_vel(N, 0) >>> I.set_vel(N, u*N.x) >>> pathway = LinearPathway(O, I) >>> pathway.attachments (O, I) >>> pathway.length Abs(q(t)) >>> pathway.extension_velocity sign(q(t))*Derivative(q(t), t)
A musculotendon also takes an instance of an activation dynamics model as this will be used to provide symbols for the activation in the formulation of the musculotendon dynamics. We’ll use an instance of
FirstOrderActivationDeGroote2016
to represent first-order activation dynamics. Note that a single name argument needs to be provided as SymPy will use this as a suffix.>>> from sympy.physics.biomechanics import FirstOrderActivationDeGroote2016
>>> activation = FirstOrderActivationDeGroote2016('muscle') >>> activation.x Matrix([[a_muscle(t)]]) >>> activation.r Matrix([[e_muscle(t)]]) >>> activation.p Matrix([ [tau_a_muscle], [tau_d_muscle], [ b_muscle]]) >>> activation.rhs() Matrix([[((1/2 - tanh(b_muscle*(-a_muscle(t) + e_muscle(t)))/2)*(3*...]])
The musculotendon class requires symbols or values to be passed to represent the constants in the musculotendon dynamics. We’ll use SymPy’s
symbols
function to create symbols for the maximum isometric forceF_M_max
, optimal fiber lengthl_M_opt
, tendon slack lengthl_T_slack
, maximum fiber velocityv_M_max
, optimal pennation anglealpha_opt, and fiber damping coefficient ``beta
.>>> F_M_max = symbols('F_M_max', real=True) >>> l_M_opt = symbols('l_M_opt', real=True) >>> l_T_slack = symbols('l_T_slack', real=True) >>> v_M_max = symbols('v_M_max', real=True) >>> alpha_opt = symbols('alpha_opt', real=True) >>> beta = symbols('beta', real=True)
We can then import the class
MusculotendonDeGroote2016
from the biomechanics module and create an instance by passing in the various objects we have previously instantiated. By default, a musculotendon model with rigid tendon musculotendon dynamics will be created.>>> from sympy.physics.biomechanics import MusculotendonDeGroote2016
>>> rigid_tendon_muscle = MusculotendonDeGroote2016( ... 'muscle', ... pathway, ... activation, ... tendon_slack_length=l_T_slack, ... peak_isometric_force=F_M_max, ... optimal_fiber_length=l_M_opt, ... maximal_fiber_velocity=v_M_max, ... optimal_pennation_angle=alpha_opt, ... fiber_damping_coefficient=beta, ... )
We can inspect the various properties of the musculotendon, including getting the symbolic expression describing the force it produces using its
force
attribute.>>> rigid_tendon_muscle.force -F_M_max*(beta*(-l_T_slack + Abs(q(t)))*sign(q(t))*Derivative(q(t), t)...
When we created the musculotendon object, we passed in an instance of an activation dynamics object that governs the activation within the musculotendon. SymPy makes a design choice here that the activation dynamics instance will be treated as a child object of the musculotendon dynamics. Therefore, if we want to inspect the state and input variables associated with the musculotendon model, we will also be returned the state and input variables associated with the child object, or the activation dynamics in this case. As the musculotendon model that we created here uses rigid tendon dynamics, no additional states or inputs relating to the musculotendon are introduces. Consequently, the model has a single state associated with it, the activation, and a single input associated with it, the excitation. The states and inputs can be inspected using the
x
andr
attributes respectively. Note that bothx
andr
have the alias attributes ofstate_vars
andinput_vars
.>>> rigid_tendon_muscle.x Matrix([[a_muscle(t)]]) >>> rigid_tendon_muscle.r Matrix([[e_muscle(t)]])
To see which constants are symbolic in the musculotendon model, we can use the
p
orconstants
attribute. This returns aMatrix
populated by the constants that are represented by aSymbol
rather than a numeric value.>>> rigid_tendon_muscle.p Matrix([ [ l_T_slack], [ F_M_max], [ l_M_opt], [ v_M_max], [ alpha_opt], [ beta], [ tau_a_muscle], [ tau_d_muscle], [ b_muscle], [ c_0_fl_T_muscle], [ c_1_fl_T_muscle], [ c_2_fl_T_muscle], [ c_3_fl_T_muscle], [ c_0_fl_M_pas_muscle], [ c_1_fl_M_pas_muscle], [ c_0_fl_M_act_muscle], [ c_1_fl_M_act_muscle], [ c_2_fl_M_act_muscle], [ c_3_fl_M_act_muscle], [ c_4_fl_M_act_muscle], [ c_5_fl_M_act_muscle], [ c_6_fl_M_act_muscle], [ c_7_fl_M_act_muscle], [ c_8_fl_M_act_muscle], [ c_9_fl_M_act_muscle], [c_10_fl_M_act_muscle], [c_11_fl_M_act_muscle], [ c_0_fv_M_muscle], [ c_1_fv_M_muscle], [ c_2_fv_M_muscle], [ c_3_fv_M_muscle]])
Finally, we can call the
rhs
method to return aMatrix
that contains as its elements the righthand side of the ordinary differential equations corresponding to each of the musculotendon’s states. Like the method with the same name on theMethod
classes in SymPy’s mechanics module, this returns a column vector where the number of rows corresponds to the number of states. For our example here, we have a single state, the dynamic symbola_muscle(t)
, so the returned value is a 1-by-1Matrix
.>>> rigid_tendon_muscle.rhs() Matrix([[((1/2 - tanh(b_muscle*(-a_muscle(t) + e_muscle(t)))/2)*(3*...]])
The musculotendon class supports elastic tendon musculotendon models in addition to rigid tendon ones. You can choose to either use the fiber length or tendon force as an additional state. You can also specify whether an explicit or implicit formulation should be used. To select a formulation, pass a member of the
MusculotendonFormulation
enumeration to themusculotendon_dynamics
parameter when calling the constructor. This enumeration is anIntEnum
, so you can also pass an integer, however it is recommended to use the enumeration as it is clearer which formulation you are actually selecting. Below, we’ll use theFIBER_LENGTH_EXPLICIT
member to create a musculotendon with an elastic tendon that will use the (normalized) muscle fiber length as an additional state and will produce the governing ordinary differential equation in explicit form.>>> from sympy.physics.biomechanics import MusculotendonFormulation
>>> elastic_tendon_muscle = MusculotendonDeGroote2016( ... 'muscle', ... pathway, ... activation, ... musculotendon_dynamics=MusculotendonFormulation.FIBER_LENGTH_EXPLICIT, ... tendon_slack_length=l_T_slack, ... peak_isometric_force=F_M_max, ... optimal_fiber_length=l_M_opt, ... maximal_fiber_velocity=v_M_max, ... optimal_pennation_angle=alpha_opt, ... fiber_damping_coefficient=beta, ... )
>>> elastic_tendon_muscle.force -F_M_max*TendonForceLengthDeGroote2016((-sqrt(l_M_opt**2*... >>> elastic_tendon_muscle.x Matrix([ [l_M_tilde_muscle(t)], [ a_muscle(t)]]) >>> elastic_tendon_muscle.r Matrix([[e_muscle(t)]]) >>> elastic_tendon_muscle.p Matrix([ [ l_T_slack], [ F_M_max], [ l_M_opt], [ v_M_max], [ alpha_opt], [ beta], [ tau_a_muscle], [ tau_d_muscle], [ b_muscle], [ c_0_fl_T_muscle], [ c_1_fl_T_muscle], [ c_2_fl_T_muscle], [ c_3_fl_T_muscle], [ c_0_fl_M_pas_muscle], [ c_1_fl_M_pas_muscle], [ c_0_fl_M_act_muscle], [ c_1_fl_M_act_muscle], [ c_2_fl_M_act_muscle], [ c_3_fl_M_act_muscle], [ c_4_fl_M_act_muscle], [ c_5_fl_M_act_muscle], [ c_6_fl_M_act_muscle], [ c_7_fl_M_act_muscle], [ c_8_fl_M_act_muscle], [ c_9_fl_M_act_muscle], [c_10_fl_M_act_muscle], [c_11_fl_M_act_muscle], [ c_0_fv_M_muscle], [ c_1_fv_M_muscle], [ c_2_fv_M_muscle], [ c_3_fv_M_muscle]]) >>> elastic_tendon_muscle.rhs() Matrix([ [v_M_max*FiberForceVelocityInverseDeGroote2016((l_M_opt*...], [ ((1/2 - tanh(b_muscle*(-a_muscle(t) + e_muscle(t)))/2)*(3*...]])
It is strongly recommended to use the alternate
with_defaults
constructor when creating an instance because this will ensure that the published constants are used in the musculotendon characteristic curves.>>> elastic_tendon_muscle = MusculotendonDeGroote2016.with_defaults( ... 'muscle', ... pathway, ... activation, ... musculotendon_dynamics=MusculotendonFormulation.FIBER_LENGTH_EXPLICIT, ... tendon_slack_length=l_T_slack, ... peak_isometric_force=F_M_max, ... optimal_fiber_length=l_M_opt, ... )
>>> elastic_tendon_muscle.x Matrix([ [l_M_tilde_muscle(t)], [ a_muscle(t)]]) >>> elastic_tendon_muscle.r Matrix([[e_muscle(t)]]) >>> elastic_tendon_muscle.p Matrix([ [ l_T_slack], [ F_M_max], [ l_M_opt], [tau_a_muscle], [tau_d_muscle], [ b_muscle]])
References
- class sympy.physics.biomechanics.musculotendon.MusculotendonFormulation(
- value,
- names=<not given>,
- *values,
- module=None,
- qualname=None,
- type=None,
- start=1,
- boundary=None,
Enumeration of types of musculotendon dynamics formulations.
Explanation
An (integer) enumeration is used as it allows for clearer selection of the different formulations of musculotendon dynamics.
Members
- RIGID_TENDON0
A rigid tendon model.
- FIBER_LENGTH_EXPLICIT1
An explicit elastic tendon model with the muscle fiber length (l_M) as the state variable.
- TENDON_FORCE_EXPLICIT2
An explicit elastic tendon model with the tendon force (F_T) as the state variable.
- FIBER_LENGTH_IMPLICIT3
An implicit elastic tendon model with the muscle fiber length (l_M) as the state variable and the muscle fiber velocity as an additional input variable.
- TENDON_FORCE_IMPLICIT4
An implicit elastic tendon model with the tendon force (F_T) as the state variable as the muscle fiber velocity as an additional input variable.