K icdZddlmZmZddlmZddlmZddlm Z m Z m Z ddl m Z ddlmZmZddlmZdd lmZgd ZGd d eeZGd deZGddeZy)aLActivation dynamics for musclotendon models. Musculotendon models are able to produce active force when they are activated, which is when a chemical process has taken place within the muscle fibers causing them to voluntarily contract. Biologically this chemical process (the diffusion of :math:`\textrm{Ca}^{2+}` ions) is not the input in the system, electrical signals from the nervous system are. These are termed excitations. Activation dynamics, which relates the normalized excitation level to the normalized activation level, can be modeled by the models present in this module. )ABCabstractmethod)cached_property)Symbol)FloatIntegerRational)tanh)MutableDenseMatrixzeros) _NamedMixin)dynamicsymbols)ActivationBase FirstOrderActivationDeGroote2016ZerothOrderActivationcveZdZdZdZeedZedZ edZ edZ edZ eedZ eed Zeed Zeed Zeed Zeed ZeedZeedZeedZedZdZdZy)ra Abstract base class for all activation dynamics classes to inherit from. Notes ===== Instances of this class cannot be directly instantiated by users. However, it can be used to created custom activation dynamics types through subclassing. cpt||_td||_td||_y)z#Initializer for ``ActivationBase``.e_a_N)strnamer_e_a)selfrs k/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/sympy/physics/biomechanics/activation.py__init__zActivationBase.__init__,s3I !2dV- 2dV-cy)zOAlternate constructor that provides recommended defaults for constants.Nclsrs r with_defaultszActivationBase.with_defaults4s rc|jS)zDynamic symbol representing excitation. Explanation =========== The alias ``e`` can also be used to access the same attribute. rrs r excitationzActivationBase.excitation; wwrc|jS)zDynamic symbol representing excitation. Explanation =========== The alias ``excitation`` can also be used to access the same attribute. r$r%s rezActivationBase.eGr'rc|jS)zDynamic symbol representing activation. Explanation =========== The alias ``a`` can also be used to access the same attribute. rr%s r activationzActivationBase.activationSr'rc|jS)zDynamic symbol representing activation. Explanation =========== The alias ``activation`` can also be used to access the same attribute. r+r%s razActivationBase.a_r'rcy):Order of the (differential) equation governing activation.Nrr%s rorderzActivationBase.orderks rcy)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. Nrr%s r state_varszActivationBase.state_varsq rcy)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. Nrr%s rxzActivationBase.xr5rcy)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. Nrr%s r input_varszActivationBase.input_varsr5rcy)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. Nrr%s rrzActivationBase.rr5rcy)zOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. 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. Explanation =========== The alias ``p`` can also be used to access the same attribute. Nrr%s r constantszActivationBase.constants& rcy)aOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. 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. Explanation =========== The alias ``constants`` can also be used to access the same attribute. Nrr%s rpzActivationBase.prBrcy)<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)``. Nrr%s rMzActivationBase.M rcy)1Ordered 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)``. Nrr%s rFzActivationBase.FrHrcy)z 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)``. Nrr%s rrhszActivationBase.rhss rcht|t|k7ry|j|jk7ryy)z'Equality check for activation dynamics.FT)typer)rothers r__eq__zActivationBase.__eq__s+ :e $ 99 "rcN|jjd|jdS)z.Default representation of activation dynamics.()) __class____name__rr%s r__repr__zActivationBase.__repr__ s$..))*!DII=::rN)rV __module__ __qualname____doc__r classmethodrr"propertyr&r)r,r.r1r4r8r;r>rArDrGrKrMrQrWrrrrr s .                              &  &            ;rrceZdZdZfdZedZedZedZ edZ edZ edZ ed Z ed Zed Zed Zd ZxZS)raSimple zeroth-order activation dynamics mapping excitation to activation. Explanation =========== Zeroth-order activation dynamics are useful in instances where you want to reduce the complexity of your musculotendon dynamics as they simple map exictation to activation. As a result, no additional state equations are introduced to your system. They also remove a potential source of delay between the input and dynamics of your system as no (ordinary) differential equations are involved. cFt|||j|_y)zInitializer for ``ZerothOrderActivation``. Parameters ========== name : str The name identifier associated with the instance. Must be a string of length at least 1. N)superrrr)rrrUs rrzZerothOrderActivation.__init__s ''rc||S)aAlternate constructor that provides recommended defaults for constants. Explanation =========== As this concrete class doesn't implement any constants associated with its dynamics, this ``classmethod`` simply creates a standard instance of ``ZerothOrderActivation``. An implementation is provided to ensure a consistent interface between all ``ActivationBase`` concrete classes. rr s rr"z#ZerothOrderActivation.with_defaults0s4yrcy)r0rrr%s rr1zZerothOrderActivation.order@rctddS)aOrdered column matrix of functions of time that represent the state variables. Explanation =========== As zeroth-order activation dynamics simply maps excitation to activation, this class has no associated state variables and so this property return an empty column ``Matrix`` with shape (0, 1). The alias ``x`` can also be used to access the same attribute. rr r%s rr4z ZerothOrderActivation.state_varsEQ{rctddS)aOrdered column matrix of functions of time that represent the state variables. Explanation =========== As zeroth-order activation dynamics simply maps excitation to activation, this class has no associated state variables and so this property return an empty column ``Matrix`` with shape (0, 1). The alias ``state_vars`` can also be used to access the same attribute. rrdrer%s rr8zZerothOrderActivation.xVrfrc.t|jgS)aOrdered column matrix of functions of time that represent the input variables. Explanation =========== Excitation is the only input in zeroth-order activation dynamics and so this property returns a column ``Matrix`` with one entry, ``e``, and shape (1, 1). The alias ``r`` can also be used to access the same attribute. Matrixrr%s rr;z ZerothOrderActivation.input_varsgtwwi  rc.t|jgS)aOrdered column matrix of functions of time that represent the input variables. Explanation =========== Excitation is the only input in zeroth-order activation dynamics and so this property returns a column ``Matrix`` with one entry, ``e``, and shape (1, 1). The alias ``input_vars`` can also be used to access the same attribute. rir%s rr>zZerothOrderActivation.rxrkrctddS)aNOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. 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. Explanation =========== As zeroth-order activation dynamics simply maps excitation to activation, this class has no associated constants and so this property return an empty column ``Matrix`` with shape (0, 1). The alias ``p`` can also be used to access the same attribute. rrdrer%s rrAzZerothOrderActivation.constants,Q{rctddS)aVOrdered column matrix of non-time varying symbols present in ``M`` and ``F``. 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. Explanation =========== As zeroth-order activation dynamics simply maps excitation to activation, this class has no associated constants and so this property return an empty column ``Matrix`` with shape (0, 1). The alias ``constants`` can also be used to access the same attribute. rrdrer%s rrDzZerothOrderActivation.prnrctgS)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). )rjr%s rrGzZerothOrderActivation.Ms"bzrctddS)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). rrdrer%s rrKzZerothOrderActivation.Fs"Q{rctddS)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). rrdrer%s rrMzZerothOrderActivation.rhss Q{r)rVrXrYrZrr[r"r\r1r4r8r;r>rArDrGrKrM __classcell__rUs@rrrs "    !! !! ..$$rrceZdZdZ dfd ZedZedZejdZedZ edZ e jdZ ed Z ed Z e jd Z ed Zed ZedZedZedZedZedZedZedZedZdZedZdZdZxZS)raAFirst-order activation dynamics based on De Groote et al., 2016 [1]_. Explanation =========== Gives the first-order activation dynamics equation for the rate of change of activation with respect to time as a function of excitation and activation. The function is defined by the equation: .. math:: \frac{da}{dt} = \left(\frac{\frac{1}{2} + a0}{\tau_a \left(\frac{1}{2} + \frac{3a}{2}\right)} + \frac{\left(\frac{1}{2} + \frac{3a}{2}\right) \left(\frac{1}{2} - a0\right)}{\tau_d}\right) \left(e - a\right) where .. math:: a0 = \frac{\tanh{\left(b \left(e - a\right) \right)}}{2} with constant values of :math:`tau_a = 0.015`, :math:`tau_d = 0.060`, and :math:`b = 10`. 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 cNt||||_||_||_y)aInitializer for ``FirstOrderActivationDeGroote2016``. Parameters ========== activation time constant : Symbol | Number | None The value of the activation time constant governing the delay between excitation and activation when excitation exceeds activation. deactivation time constant : Symbol | Number | None The value of the deactivation time constant governing the delay between excitation and activation when activation exceeds excitation. smoothing_rate : Symbol | Number | None The slope of the hyperbolic tangent function used to smooth between the switching of the equations where excitation exceed activation and where activation exceeds excitation. The recommended value to use is ``10``, but values between ``0.1`` and ``100`` can be used. N)r_ractivation_time_constantdeactivation_time_constantsmoothing_rate)rrrwrxryrUs rrz)FirstOrderActivationDeGroote2016.__init__s-2 )A%*D',rcZtd}td}td}|||||S)awAlternate constructor that will use the published constants. Explanation =========== Returns an instance of ``FirstOrderActivationDeGroote2016`` using the three constant values specified in the original publication. These have the values: :math:`tau_a = 0.015` :math:`tau_d = 0.060` :math:`b = 10` z0.015z0.060z10.0)r)r!rtau_atau_dbs rr"z.FirstOrderActivationDeGroote2016.with_defaults8s0"gg &M4q))rc|jS)zDelay constant for activation. Explanation =========== The alias ```tau_a`` can also be used to access the same attribute. _tau_ar%s rrwz9FirstOrderActivationDeGroote2016.activation_time_constantN{{rct|dr'dt|d|jd}t||t d|j |_y||_y)Nrz2Can't set attribute `activation_time_constant` to * as it is immutable and already has value .tau_a_)hasattrreprrAttributeErrorrr)rr{msgs rrwz9FirstOrderActivationDeGroote2016.activation_time_constantZs^ 4 "E;-I;;-q"  !% %6;mfvdii[12  rc|jS)zDelay constant for activation. Explanation =========== The alias ``activation_time_constant`` can also be used to access the same attribute. rr%s rr{z&FirstOrderActivationDeGroote2016.tau_ae{{rc|jS)zDelay constant for deactivation. Explanation =========== The alias ``tau_d`` can also be used to access the same attribute. _tau_dr%s rrxz;FirstOrderActivationDeGroote2016.deactivation_time_constantrrrct|dr'dt|d|jd}t||t d|j |_y||_y)Nrz4Can't set attribute `deactivation_time_constant` to rrtau_d_)rrrrrr)rr|rs rrxz;FirstOrderActivationDeGroote2016.deactivation_time_constant~s^ 4 "G;-I;;-q"  !% %6;mfvdii[12  rc|jS)zDelay constant for deactivation. Explanation =========== The alias ``deactivation_time_constant`` can also be used to access the same attribute. rr%s rr|z&FirstOrderActivationDeGroote2016.tau_drrc|jS)zSmoothing constant for the hyperbolic tangent term. Explanation =========== The alias ``b`` can also be used to access the same attribute. _br%s rryz/FirstOrderActivationDeGroote2016.smoothing_rater'rct|drd|d|jd}t||td|j|_y||_y)Nrz(Can't set attribute `smoothing_rate` to rrb_)rrrrr)rr}rs rryz/FirstOrderActivationDeGroote2016.smoothing_rates] 4 ;A5A33777+Q@ !% %./i&2dii[)*Qrc|jS)zSmoothing constant for the hyperbolic tangent term. Explanation =========== The alias ``smoothing_rate`` can also be used to access the same attribute. rr%s rr}z"FirstOrderActivationDeGroote2016.bs wwrcy)r0rdrr%s rr1z&FirstOrderActivationDeGroote2016.orderrbrc.t|jgS)r3rjrr%s rr4z+FirstOrderActivationDeGroote2016.state_varstwwi  rc.t|jgS)r7rr%s rr8z"FirstOrderActivationDeGroote2016.xrrc.t|jgS)r:rir%s rr;z+FirstOrderActivationDeGroote2016.input_varsrrc.t|jgS)r=rir%s rr>z"FirstOrderActivationDeGroote2016.rrrc|j|j|jg}|Dcgc]}|jr|}}|r t |St ddScc}w)r@rrdrrr is_numberrjr rrAcsymbolic_constantss rrAz*FirstOrderActivationDeGroote2016.constantsU$[[$++tww7 )2FA!++aFF-?v()PU1a[PG AAc|j|j|jg}|Dcgc]}|jr|}}|r t |St ddScc}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. rrdrrs rrDz"FirstOrderActivationDeGroote2016.prrc,ttdgS)rFrd)rjrr%s rrGz"FirstOrderActivationDeGroote2016.Mswqzl##rc.t|jgS)rJrj_da_eqnr%s rrKz"FirstOrderActivationDeGroote2016.F-st||n%%rc.t|jgS)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)``. rr%s rrMz$FirstOrderActivationDeGroote2016.rhs<st||n%%rcLtdd}|t|j|j|jz zz}|tdd|jzz}||z|j |zz }|||z z|j z }||z|j|jz z}|S)Nrd)r r rrrrr)rHALFa0a1a2a3activation_dynamics_equations rrz(FirstOrderActivationDeGroote2016._da_eqnJs1~ DDGGdgg$567 7Xa^dgg--RiDKK", - 4"9  +(*RDGGdgg4E'F$++rct|t|k7ry|j|j|j|jf}|j|j|j|jf}||k(ryy)z8Equality check for ``FirstOrderActivationDeGroote2016``.FT)rOrr{r|r})rrP self_attrs other_attrss rrQz'FirstOrderActivationDeGroote2016.__eq__Ts_ :e $iiTZZ@ zz5;; UWWE  $rc |jjd|jd|jd|jd|j d S)z7Representation of ``FirstOrderActivationDeGroote2016``.rSz, activation_time_constant=z, deactivation_time_constant=z, smoothing_rate=rT)rUrVrr{r|r}r%s rrWz)FirstOrderActivationDeGroote2016.__repr__^sT~~&&'q 6((, ~6**.**8"ffZq * r)NNN)rVrXrYrZrr[r"r\rwsetterr{rxr|ryr}r1r4r8r;r>rArDrGrKrMrrrQrWrsrts@rrrs#N"&#' -@***  $$O%O     &&O'O    ??   ! ! ! ! ! ! ! !QQ*QQ* $ $ & & &,, rrN)rZabcrr functoolsrsympy.core.symbolrsympy.core.numbersrrr %sympy.functions.elementary.hyperbolicr sympy.matrices.denser rjr !sympy.physics.biomechanics._mixinr sympy.physics.mechanicsr__all__rrrrrrrs\ $%$776D92 l;S+l;^`N`Fs ~s r