Activation (Docstrings)

Activation 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 \(\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.

class sympy.physics.biomechanics.activation.ActivationBase(name)

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.

abstract 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).

abstract 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).

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.

abstract property constants

Ordered 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.

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.

abstract 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.

abstract property order

Order of the (differential) equation governing activation.

abstract property p

Ordered 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.

abstract 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.

abstract rhs()

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).

abstract 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.

abstract classmethod with_defaults(name)

Alternate constructor that provides recommended defaults for constants.

abstract 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.activation.FirstOrderActivationDeGroote2016(

name,

activation_time_constant=None,

deactivation_time_constant=None,

smoothing_rate=None,

)

First-order activation dynamics based on De Groote et al., 2016 [R720].

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:

\[\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

\[a0 = \frac{\tanh{\left(b \left(e - a\right) \right)}}{2}\]

with constant values of \(tau_a = 0.015\), \(tau_d = 0.060\), and \(b = 10\).

References

[R720] (1,2)

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

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).

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).

property activation_time_constant

Delay constant for activation.

Explanation

The alias `tau_a can also be used to access the same attribute.

property b

Smoothing constant for the hyperbolic tangent term.

Explanation

The alias smoothing_rate can also be used to access the same attribute.

property constants

Ordered 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.

property deactivation_time_constant

Delay constant for deactivation.

Explanation

The alias tau_d 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 order

Order of the (differential) equation governing activation.

property p

Ordered 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.

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()

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).

property smoothing_rate

Smoothing constant for the hyperbolic tangent term.

Explanation

The alias b can also be used to access the same attribute.

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 tau_a

Delay constant for activation.

Explanation

The alias activation_time_constant can also be used to access the same attribute.

property tau_d

Delay constant for deactivation.

Explanation

The alias deactivation_time_constant can also be used to access the same attribute.

classmethod with_defaults(

name,

)

Alternate 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:

\(tau_a = 0.015\) \(tau_d = 0.060\) \(b = 10\)

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.activation.ZerothOrderActivation(name)

Simple 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 involed.

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 column Matrix with shape (0, 1).

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 square Matrix with shape (0, 0).

property constants

Ordered 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.

property input_vars

Ordered 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.

property order

Order of the (differential) equation governing activation.

property p

Ordered 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.

property r

Ordered 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.

rhs()

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

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.

classmethod with_defaults(name)

Alternate 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.

property x

Ordered 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.