K i>dZddlmZddlmZmZddlmZmZddl m Z m Z ddl m Z ddlmZmZddlmZmZmZmZdd lmZdd lmZmZmZmZmZmZm Z m!Z!dd l"m#Z#dd l$m%Z%dd l&m'Z'gdZ(eGddeZ)e)jTZ+Gdde%e#Z,Gdde,Z-y)a 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. )abstractmethod)IntEnumunique)FloatInteger)Symbolsymbols)sqrt)cossin)MutableDenseMatrixdiageyezeros)ActivationBase)CharacteristicCurveCollection"FiberForceLengthActiveDeGroote2016#FiberForceLengthPassiveDeGroote2016*FiberForceLengthPassiveInverseDeGroote2016FiberForceVelocityDeGroote2016%FiberForceVelocityInverseDeGroote2016TendonForceLengthDeGroote2016$TendonForceLengthInverseDeGroote2016) _NamedMixin) ForceActuator)dynamicsymbols)MusculotendonBaseMusculotendonDeGroote2016MusculotendonFormulationc*eZdZdZdZdZdZdZdZdZ y) raEnumeration 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_TENDON : 0 A rigid tendon model. FIBER_LENGTH_EXPLICIT : 1 An explicit elastic tendon model with the muscle fiber length (l_M) as the state variable. TENDON_FORCE_EXPLICIT : 2 An explicit elastic tendon model with the tendon force (F_T) as the state variable. FIBER_LENGTH_IMPLICIT : 3 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_IMPLICIT : 4 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. rc,t|jS)aReturns a string representation of the enumeration value. Notes ===== This hard coding is required due to an incompatibility between the ``IntEnum`` implementations in Python 3.10 and Python 3.11 (https://github.com/python/cpython/issues/84247). From Python 3.11 onwards, the ``__str__`` method uses ``int.__str__``, whereas prior it used ``Enum.__str__``. Once Python 3.11 becomes the minimum version supported by SymPy, this method override can be removed. )strvalueselfs n/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/sympy/physics/biomechanics/musculotendon.py__str__z MusculotendonFormulation.__str__Rs4::N) __name__ __module__ __qualname____doc__ RIGID_TENDONFIBER_LENGTH_EXPLICITTENDON_FORCE_EXPLICITFIBER_LENGTH_IMPLICITTENDON_FORCE_IMPLICITr+r,r*rr,s+<Lr,rc \eZdZdZeddddddddfd Zeedddedededd d Ze d Z e d Z e d Z e dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZdZdZd Z d!Z!d"Z"e d#Z#e d$Z$e d%Z%e d&Z&e d'Z'e d(Z(e d)Z)e d*Z*d+Z+d,Z,d-Z-xZ.S).raAbstract base class for all musculotendon classes to inherit from. 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. 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 to ``MusculotendonFormulation.RIGID_TENDON`` (or the integer value ``0``, 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 to ``MusculotendonFormulation.FIBER_LENGTH_EXPLICIT`` (or the integer value ``1``). To use an explicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_EXPLICIT`` (or the integer value ``2``). To use an implicit formulation with the fiber length as the state, set this to ``MusculotendonFormulation.FIBER_LENGTH_IMPLICIT`` (or the integer value ``3``). To use an implicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_IMPLICIT`` (or the integer value ``4``). The default is ``MusculotendonFormulation.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 :math:`\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 :math:`\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 :math:`\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 :math:`\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 is ``False``. NF)musculotendon_dynamicstendon_slack_lengthpeak_isometric_forceoptimal_fiber_lengthmaximal_fiber_velocityoptimal_pennation_anglefiber_damping_coefficient with_defaultsc||_t | td|t |t sd|dt |d} t| ||_|jf|_ |||_ ntd|j|_ |||_ ntd|j|_ |||_ ntd|j|_ |||_ ntd|j|_ | | |_ntd |j|_| | |_ntd |j|_| |_|t"j$k(r|j'n|t"j(k(r|j+n|t"j,k(r|j/nu|t"j0k(r|j3nQ|t"j4k(r|j7n-d t9|d t |d t"d} t| ||_|j< |_y)NFz-Can't set attribute `activation_dynamics` to z- as it must be of type `ActivationBase`, not . l_T_slack_F_M_max_l_M_opt_v_M_max_ alpha_opt_beta_zMusculotendon dynamics z0 passed to `musculotendon_dynamics` was of type z , must be ) namesuper__init__r isinstancertype TypeError_activation_dynamics_child_objects _l_T_slack_F_M_max_l_M_opt_v_M_max _alpha_opt_beta_with_defaultsrr1$_rigid_tendon_musculotendon_dynamicsr2-_fiber_length_explicit_musculotendon_dynamicsr3-_tendon_force_explicit_musculotendon_dynamicsr4-_fiber_length_implicit_musculotendon_dynamicsr5-_tendon_force_implicit_musculotendon_dynamicsrepr_musculotendon_dynamics_F_T_force)r)rIpathwayactivation_dynamicsr8r9r:r;r<r=r>r?msg __class__s r*rKzMusculotendonBase.__init__s?  g.-~>@&'())-.A)B(C1F  C. $7!#88;  *1DO$z$))%=>DO  +0DM"Xdii[#9:DM  +0DM"Xdii[#9:DM ! -2DM"Xdii[#9:DM " .5DO$z$))%=>DO $ 02DJ% { 34DJ, !%=%J%J J  5 5 7 #'?'U'U U  > > @ #'?'U'U U  > > @ #'?'U'U U  > > @ #'?'U'U U  > > @*$/E*F)GHB./0 +,A/  C. '=$yyj r,z10.0z0.0z0.1)r8r9r:r;r<r=r>c (|||||||||| | d S)aRecommended constructor that will use the published constants. Explanation =========== Returns a new instance of the musculotendon class using recommended values for ``v_M_max``, ``alpha_opt``, and ``beta``. The values are: :math:`v^M_{max} = 10` :math:`\alpha_{opt} = 0` :math:`\beta = \frac{1}{10}` The musculotendon curves are also instantiated using the constants from the original publication. 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 to ``MusculotendonFormulation.RIGID_TENDON`` (or the integer value ``0``, 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 to ``MusculotendonFormulation.FIBER_LENGTH_EXPLICIT`` (or the integer value ``1``). To use an explicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_EXPLICIT`` (or the integer value ``2``). To use an implicit formulation with the fiber length as the state, set this to ``MusculotendonFormulation.FIBER_LENGTH_IMPLICIT`` (or the integer value ``3``). To use an implicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_IMPLICIT`` (or the integer value ``4``). The default is ``MusculotendonFormulation.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 :math:`\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 :math:`\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 :math:`\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 :math:`\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. T) rbr8r9r:r;r<r=r>r?r6) clsrIrarbr8r9r:r;r<r=r>s r*r?zMusculotendonBase.with_defaultss3D   3#9 3!5!5#9$;&?  r,cy)z_Return a ``CharacteristicCurveCollection`` of the curves related to the specific model.Nr6)rfs r*curveszMusculotendonBase.curvess r,c|jS)a 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 :math:`\tilde{l}^T = \frac{l^T}{l^T_{slack}}`. The alias ``l_T_slack`` can also be used to access the same attribute. rQr(s r*r9z%MusculotendonBase.tendon_slack_lengths r,c|jS)aSymbol 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 :math:`\tilde{l}^T = \frac{l^T}{l^T_{slack}}`. The alias ``tendon_slack_length`` can also be used to access the same attribute. rjr(s r* l_T_slackzMusculotendonBase.l_T_slacks"r,c|jS)aSymbol 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 :math:`\tilde{F}^T = \frac{F^T}{F^M_{max}}`. The alias ``F_M_max`` can also be used to access the same attribute. rRr(s r*r:z&MusculotendonBase.peak_isometric_force }}r,c|jS)aSymbol 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 :math:`\tilde{F}^T = \frac{F^T}{F^M_{max}}`. The alias ``peak_isometric_force`` can also be used to access the same attribute. rnr(s r*F_M_maxzMusculotendonBase.F_M_maxs"}}r,c|jS)aSymbol 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 :math:`\tilde{l}^M = \frac{l^M}{l^M_{opt}}`. The alias ``l_M_opt`` can also be used to access the same attribute. rSr(s r*r;z&MusculotendonBase.optimal_fiber_length}}r,c|jS)aSymbol 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 :math:`\tilde{l}^M = \frac{l^M}{l^M_{opt}}`. The alias ``optimal_fiber_length`` can also be used to access the same attribute. rsr(s r*l_M_optzMusculotendonBase.l_M_optror,c|jS)aSymbol 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 :math:`\tilde{v}^M = \frac{v^M}{v^M_{max}}`. The alias ``v_M_max`` can also be used to access the same attribute. rTr(s r*r<z(MusculotendonBase.maximal_fiber_velocityrtr,c|jS)aSymbol 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 :math:`\tilde{v}^M = \frac{v^M}{v^M_{max}}`. The alias ``maximal_fiber_velocity`` can also be used to access the same attribute. rxr(s r*v_M_maxzMusculotendonBase.v_M_maxror,c|jS)a0Symbol 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. rUr(s r*r=z)MusculotendonBase.optimal_pennation_anglesr,c|jS)aFSymbol 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. r|r(s r* alpha_optzMusculotendonBase.alpha_opt&sr,c|jS)a7Symbol 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. rVr(s r*r>z+MusculotendonBase.fiber_damping_coefficient7szzr,c|jS)aTSymbol 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. rr(s r*betazMusculotendonBase.betaGszzr,c|jS)aRActivation 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. )rOr(s r*rbz%MusculotendonBase.activation_dynamicsXs(((r,c.|jjS)zDynamic symbol representing excitation. Explanation =========== The alias ``e`` can also be used to access the same attribute. rO_er(s r* excitationzMusculotendonBase.excitationf((+++r,c.|jjS)zDynamic symbol representing excitation. Explanation =========== The alias ``excitation`` can also be used to access the same attribute. rr(s r*ezMusculotendonBase.errr,c.|jjS)zDynamic symbol representing activation. Explanation =========== The alias ``a`` can also be used to access the same attribute. rO_ar(s r* activationzMusculotendonBase.activation~rr,c.|jjS)zDynamic symbol representing activation. Explanation =========== The alias ``activation`` can also be used to access the same attribute. rr(s r*azMusculotendonBase.arr,c|jS)aThe 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 to ``MusculotendonFormulation.RIGID_TENDON`` (or the integer value ``0``, 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 to ``MusculotendonFormulation.FIBER_LENGTH_EXPLICIT`` (or the integer value ``1``). To use an explicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_EXPLICIT`` (or the integer value ``2``). To use an implicit formulation with the fiber length as the state, set this to ``MusculotendonFormulation.FIBER_LENGTH_IMPLICIT`` (or the integer value ``3``). To use an implicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_IMPLICIT`` (or the integer value ``4``). The default is ``MusculotendonFormulation.RIGID_TENDON``, which corresponds to a rigid tendon formulation. )r^r(s r*r8z(MusculotendonBase.musculotendon_dynamicss:+++r,c\|jj|_|jj|_|j |_td|_t|j|j z dz|jt|jzdzz|_ |j|jz |_|j|j|j z z|jz |_|j|j z |_|j$r|j&j(j+|j|_|j&j.j+|j|_|j&j2j+|j|_|j&j6j+|j"|_nt;d|j<}|j&j(|jg||_t;d|j<}|j&j.|jg||_t;d|j<}|j&j2|jg||_t;d|j<}|j&j6|j"g||_|j>|j4z|j8z|j0z|j@|j"zz|_!|jB|_"|jB|jFz|_$tK|j|_&|jH|jLz|_'tQdd|_)tQdd|_*tQdd|_+|j$stYzzz|_-ytQdd|_-y) zRigid tendon musculotendon.r!r" c_0:4_fl_T_c_0:2_fl_M_pas_c_0:12_fl_M_act_ c_0:4_fv_M_rN).ralength_l_MTextension_velocity_v_MTrQ_l_Tr _l_T_tilder rSr rU_l_M _l_M_tilde_v_MrT _v_M_tilderWrhtendon_force_lengthr?_fl_Tfiber_force_length_passive _fl_M_pasfiber_force_length_active _fl_M_actfiber_force_velocity_fv_Mr rIrrV _F_M_tilde _F_T_tilderR_F_Mr _cos_alphar_r _state_vars _input_vars _state_eqnsMatrix_curve_constantsr)fl_T_constantsfl_M_pas_constantsfl_M_act_constantsfv_M_constantss r*rXz6MusculotendonBase._rigid_tendon_musculotendon_dynamicss#\\(( \\44 OO !!*$**tyy014 c$//FZ8Z]^7^^_ ))DMM1JJ T__ <=diiG ))DMM1   88FFtWDJ![[CCQQRVRaRabDN![[BBPPQUQ`Q`aDN99GGXDJ${499+%>?N888Z>ZDJ!(?499+)F!G CT[[CCDOOiVhiDN!(+;DII;)G!H BT[[BB4??hUghDN${499+%>?N999$//[N[DJ&&/ :T^^KdjjY]YhYhNhh//OODMM1 doo.IIdoo- !A; A; A; $$ !'   !  ! !  +01+ r,ctd|j|_|jj|_|jj |_|j|jz|_ |j t|jdz|jt|jzdzz z |_ |j|jz |_|j |jz |jz |_|j"r|j$j&j)|j|_|j$j,j)|j|_|j$j0j)|j|_nt5d|j}|j$j&|jg||_t5d|j}|j$j,|jg||_t5d|j}|j$j0|jg||_|j*|_|j6|j8z|_|j:|j z |_|j<|j8z |_|j>|j.z |j@|j2zz |_!|j"r5|j$jDj)|jB|_#nDt5d|j}|j$jD|jBg||_#|jH|jz |jFz|_%tM|jg|_'tQdd|_)tM|jJg|_*|j"stMzzz|_+y tQdd|_+y ) z:Elastic tendon musculotendon using `l_M_tilde` as a state. l_M_tilde_r"rrrrrr!N),rrIrrarrrrrSrr r rUrrQrrrWrhrr?rrrrrr rrRr_rrrrfiber_force_velocity_inverserrT_dl_M_tilde_dtrrrrrrrs r*rYz?MusculotendonBase._fiber_length_explicit_musculotendon_dynamicss@(:dii[)AB\\(( \\44 OODMM1 JJdiildmmCDX6X[\5\&\!]] ))DOO3:: 1499<   88FFtWDJ![[CCQQRVRaRabDN![[BBPPQUQ`Q`aDN${499+%>?N888Z>ZDJ!(?499+)F!G CT[[CCDOOiVhiDN!(+;DII;)G!H BT[[BB4??hUghDN**OODMM1 IIdoo- ))DMM1oo69NO   "kkFFTTUYU_U_`DO${499+%>?NFdkkFFtzzcTbcDO#}}T]]:DOOK!4??"34 A;!4#6#6"78 $$ !'   !  ! !  +01+ r,c4 td|j|_|jj|_|jj |_|j|_|jr5|jjj|j|_ nDtd|j}|jj|jg||_ |j|_|j|j z|_t%|j |j"z dz|j&t)|j*zdzz|_|j,|j&z |_|jri|jj0j|j.|_|jj4j|j.|_ntd|j}|jj0|j.g||_td|j}|jj4|j.g||_|j |j"z |j,z |_|j|j:z|_|j<|j8z |_|j>|j:z |_ |j@|j2z |jB|j6zz |_"|jr5|jjFj|jD|_$nDtd|j}|jjF|jDg||_$|jH|_%|jJ|jLz|_'|j|jN|j8z z |_(|jP|j z |_)|jr5|jjTj|j|_n,|jjT|jg|_|jjWtjXj[|jjWtjX|jRi|_.t_|jg|_0tcdd|_2t_|j\g|_3|jst_zzz|_4y tcdd|_4y ) z:Elastic tendon musculotendon using `F_T_tilde` as a state. F_T_tilde_rr"rrrrr!N)5rrIrrarrrrrrWrhtendon_force_length_inverser? _fl_T_invr rrQrr rSr rUrrrrrrrrRr_rrrrr _fv_M_invrrTr_v_T _v_T_tilderdiff_tsubs_dF_T_tilde_dtrrrrrrrs r*rZz?MusculotendonBase._tendon_force_explicit_musculotendon_dynamicss$(:dii[)AB\\(( \\44 __   ![[DDRRSWS]S]^DN${499+%>?NDT[[DDTZZaR`aDN..OODOO3 $**tyy014 c$//FZ8Z]^7^^_ ))DMM1   ![[CCQQRVRaRabDN![[BBPPQUQ`Q`aDN!(?499+)F!G CT[[CCDOOiVhiDN!(+;DII;)G!H BT[[BB4??hUghDN:: 1499<OODMM1 IIdoo- ))DMM1oo69NO   ![[EESSTXT^T^_DN${499+%>?NET[[EEdjjbSabDN..OODMM1 JJ$))DOO";< ))DOO3   88FFtWDJ888Z>ZDJ"jjoon.?.?@EEtG[G[\j\m\mGnptppGAB!4??"34 A;!4#6#6"78 $$ !'   !  ! !  +01+ r,ctNNotImplementedErrorr(s r*r[z?MusculotendonBase._fiber_length_implicit_musculotendon_dynamics=!!r,ctrrr(s r*r\z?MusculotendonBase._tendon_force_implicit_musculotendon_dynamics@rr,c|jg}|jD]}|j|jt j |S)zOrdered column matrix of functions of time that represent the state variables. Explanation =========== The alias ``x`` can also be used to access the same attribute. rrPappend state_varsrvstackr)rchilds r*rzMusculotendonBase.state_varsCJ&&' (( 0E   e.. / 0}}j))r,c|jg}|jD]}|j|jt j |S)zOrdered 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. rrs r*xzMusculotendonBase.xSrr,c|jg}|jD]}|j|jt j |S)zOrdered column matrix of functions of time that represent the input variables. Explanation =========== The alias ``r`` can also be used to access the same attribute. rrPr input_varsrrr)rrs r*rzMusculotendonBase.input_varscrr,c|jg}|jD]}|j|jt j |S)zOrdered 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. rrs r*rzMusculotendonBase.rsrr,c|j|j|j|j|j|j g}|Dcgc]}|j r|}}|r t|n tddg}|jD]}|j|j|j|jtj|Scc}w)azOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. Explanation =========== Only symbolic constants are returned. If a numeric type (e.g. ``Float``) has been used instead of ``Symbol`` 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. rr!rQrRrSrTrUrV is_numberrrrPr constantsrrr)musculotendon_constantscrrs r*rzMusculotendonBase.constants& OO MM MM MM OO JJ # /# akkA# # ' * +q! (( .E   U__ - .../}}i((# CCc|j|j|j|j|j|j g}|Dcgc]}|j r|}}|r t|n tddg}|jD]}|j|j|j|jtj|Scc}w)aOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. Explanation =========== Only symbolic constants are returned. If a numeric type (e.g. ``Float``) has been used instead of ``Symbol`` 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. rr!rrs r*pzMusculotendonBase.prrctt|jg}|jD]}|j |j t |S)aOrdered 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 square ``Matrix`` with shape (0, 0). )rlenrrPrMr)r)rrs r*rzMusculotendonBase.MsJ"T%%& ' ((( E HHUWW  Qxr,c|jg}|jD]}|j|jt j |S)aOrdered 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 column ``Matrix`` with shape (0, 1). )rrPrrArr)r)rArs r*rAzMusculotendonBase.FsF"   (( E HHUWW  }}a  r,ctjtjf}|jtjur9|j Dcgc]}|j }}tj|S|j|vrI|j}|j Dcgc]}|j }}tj|g|S|jj|jScc}wcc}w)aOrdered 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). ) rr2r3r8r1rPrhsrrrrsolverA)r) is_explicitr child_rhsrs r*rzMusculotendonBase.rhss" % : : $ : :   & &*B*O*O O262E2EFFIF==), ,  ( (K 7""C262E2EFFIF==1y1 1vv||DFF## GGs C2C7c8|jjd|jd|jd|jd|j d|j d|jd|jd|jd |jd |jd S) z;Returns a string representation to reinstantiate the model.(z , pathway=z, activation_dynamics=z, musculotendon_dynamics=z, tendon_slack_length=z, peak_isometric_force=z, optimal_fiber_length=z, maximal_fiber_velocity=z, optimal_pennation_angle=z, fiber_damping_coefficient=)) rdr-rIrarbr8rQrRrSrTrUrVr(s r*__repr__zMusculotendonBase.__repr__s~~&&'q 6||&'##'#;#;">?&&*&A&A%BC##'??"56$$(MM#45$$(MM#45&&*mm%67''+&9:))-a 9 r,c,t|jS)zRReturns a string representation of the expression for musculotendon force.)r&forcer(s r*r+zMusculotendonBase.__str__)s4::r,)/r-r.r/r0"_DEFAULT_MUSCULOTENDON_FORMULATIONrK classmethodrr?rrhpropertyr9rlr:rqr;rvr<rzr=r~r>rrbrrrrr8rXrYrZr[r\rrrrrrrrArrr+ __classcell__)rds@r*rrfsOn B !!# $"&V!p B !!$V} %e "',m m ^  "$"$ " "       ) ) , , , , , , , ,,,<'6R(6T36j"" * * * * * * * *$)$)L$)$)L*!!*$:  r,rc .eZdZdZeeeeee e e Z y)ra9Musculotendon model using the curves of De Groote et al., 2016 [1]_. Examples ======== This class models the musculotendon actuator parametrized by the characteristic curves described in De Groote et al., 2016 [1]_. 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 point ``O`` to represent the musculotendon's origin and another ``I`` 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 force ``F_M_max``, optimal fiber length ``l_M_opt``, tendon slack length ``l_T_slack``, maximum fiber velocity ``v_M_max``, optimal pennation angle ``alpha_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`` and ``r`` attributes respectively. Note that both ``x`` and ``r`` have the alias attributes of ``state_vars`` and ``input_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`` or ``constants`` attribute. This returns a ``Matrix`` populated by the constants that are represented by a ``Symbol`` 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 a ``Matrix`` 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 the ``Method`` 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 symbol ``a_muscle(t)``, so the returned value is a 1-by-1 ``Matrix``. >>> 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 the ``musculotendon_dynamics`` parameter when calling the constructor. This enumeration is an ``IntEnum``, 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 the ``FIBER_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]]) 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 to ``MusculotendonFormulation.RIGID_TENDON`` (or the integer value ``0``, 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 to ``MusculotendonFormulation.FIBER_LENGTH_EXPLICIT`` (or the integer value ``1``). To use an explicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_EXPLICIT`` (or the integer value ``2``). To use an implicit formulation with the fiber length as the state, set this to ``MusculotendonFormulation.FIBER_LENGTH_IMPLICIT`` (or the integer value ``3``). To use an implicit formulation with the tendon force as the state, set this to ``MusculotendonFormulation.TENDON_FORCE_IMPLICIT`` (or the integer value ``4``). The default is ``MusculotendonFormulation.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 :math:`\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 :math:`\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 :math:`\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 :math:`\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 is ``False``. References ========== .. [1] De Groote, F., Kinney, A. L., Rao, A. V., & Fregly, B. J., Evaluation of direct collocation optimal control problem formulations for solving the muscle redundancy problem, Annals of biomedical engineering, 44(10), (2016) pp. 2922-2936 )rrr"fiber_force_length_passive_inverserrrN) r-r.r/r0rrrrrrrrrhr6r,r*rr/s*Vp +9$H#F+U"D;%JFr,rN).r0abcrenumrrsympy.core.numbersrrsympy.core.symbolrr (sympy.functions.elementary.miscellaneousr (sympy.functions.elementary.trigonometricr r sympy.matrices.denser rrrr%sympy.physics.biomechanics.activationr sympy.physics.biomechanics.curverrrrrrrr!sympy.physics.biomechanics._mixinr sympy.physics.mechanics.actuatorrsympy.physics.vector.functionsr__all__rr1rrrr6r,r*r s  --9=OO@   ::9 3w33l&>%J%J"F {FRa 1ar,