#include <TorqueMuscleFittingToolkit.h>

Static Public Member Functions
static void	fitTorqueMuscleParameters (Millard2016TorqueMuscle const &tqMcl, RigidBodyDynamics::Math::VectorNd const &jointAngle, RigidBodyDynamics::Math::VectorNd const &jointAngularVelocity, RigidBodyDynamics::Math::VectorNd const &jointTorque, double activationUpperBound, double passiveTorqueAngleMultiplierUpperBound, TorqueMuscleParameterFittingData &parametersOfBestFit, bool verbose=false)
	This function will adjust the parameters of the muscle-torque-generator (MTG) so that the MTG is strong enough and flexible enough that it can produce the measured output torque across the vector of measured joint angles and angular velocities without exceeding the desired activation upper bound, nor the passive forces exceeding the prescribed upper bound. This function requires that IPOPT is installed and that cmake has been correctly configured to point at IPOPT's install directory. For a detailed description of the method please see : M.Millard, A.L.Kleesattel, M.Harant, & K.Mombaur. A reduced muscle model and planar musculoskeletal model fit for the synthesis of whole body movements. Journal of Biomechanics. (under review as of August 2018) More...

Detailed Description

Definition at line 15 of file TorqueMuscleFittingToolkit.h.

Member Function Documentation

◆ fitTorqueMuscleParameters()

static void fitTorqueMuscleParameters	(	Millard2016TorqueMuscle const &	tqMcl,
		RigidBodyDynamics::Math::VectorNd const &	jointAngle,
		RigidBodyDynamics::Math::VectorNd const &	jointAngularVelocity,
		RigidBodyDynamics::Math::VectorNd const &	jointTorque,
		double	activationUpperBound,
		double	passiveTorqueAngleMultiplierUpperBound,
		TorqueMuscleParameterFittingData &	parametersOfBestFit,
		bool	verbose = `false`
	)

static

This function will adjust the parameters of the muscle-torque-generator (MTG) so that the MTG is strong enough and flexible enough that it can produce the measured output torque across the vector of measured joint angles and angular velocities without exceeding the desired activation upper bound, nor the passive forces exceeding the prescribed upper bound. This function requires that IPOPT is installed and that cmake has been correctly configured to point at IPOPT's install directory. For a detailed description of the method please see : M.Millard, A.L.Kleesattel, M.Harant, & K.Mombaur. A reduced muscle model and planar musculoskeletal model fit for the synthesis of whole body movements. Journal of Biomechanics. (under review as of August 2018)

The method adjusts five parameters:

: the scale of the domain (angle) of the active-torque-angle-curve. This scaling is applied so that the angle which corresponds to the peak value of the active-torque-angle-curve remains unchanged.
: the scaling applied to the maximum angular velocity at which the concentric side of the torque-angular-velocity curve goes to zero.
$\lambda^P$ : the passive-torque-angle-blending-variable
$\Delta^P$ : the passive-torque-angle-offset
$s^\tau$ : the scaling applied to $\tau_{o}$ the maximum active isometric torque

These 5 parameters are a subset of the fitting variables that are available, and are illustrated below:

Examples of the adjustable characteristic curves

To peform the fitting, the user must provide vectors of the joint angle, joint angular velocity, and the joint torque for the joint that the muscle-torque-generator (MTG) actuates. The sign of all of these quantities must be consistent with the multibody and the torque muscle. IPOPT solves for the fitting parameters $\mathbf{x}$ such that the final result is as close as possible to the values the MTG has before the fitting is performed $\mathbf{x}_o$

$(\mathbf{x}-\mathbf{x}_o)^T \mathbf{K} (\mathbf{x}-\mathbf{x}_o)$

such that at every point $i$ in the vector of joint angles, velocities, and torques the following constraints are satisfied

$\tau^M(a^{max},\theta_i,\dot{\theta}_i,\mathbf{x})-\tau_i \ge 0$

$\tau^M(0,\theta_i,\dot{\theta}_i,\mathbf{x})-\tau_i \le 0$

$\mathbf{t}_{P}(\theta_i) - \mathbf{t}_{P}^{max} \le 0$

$s^A, s^V, s^{\tau} \ge 1$

$1 \ge \lambda^P \ge 0$

$\pi/2 \ge \Delta^P \ge -\pi/2.$

These constraints ensure that the muscle can deliver the requested torque with an activation of $a^{max}$ or less, such that the active forces of the muscle are never fighting the passive forces, and that passive forces that are $\mathbf{t}_{P}^{max}$ or less. The bound limits on the various optimization variables ensure that the muscle is not made to be weaker or slower than the default settings for the muscle. Thus if your subject is weaker than the default settings for the muscle, you should first weaken the MTG and then run this function.

Notes

This routine will return the parameters that fit the data, even if they are unreasonable: it is your responsibility to have a look at this data to sanity check it before using it.
This function will not update the internal parameters of the model - it just calculates what they need to be and returns them in the TorqueMuscleParametersFittingData structure. If you decide that these parameters are parameters are suitable, then they can be assigned to the model using the function Millard2016TorqueMuscle.setFittedParameters. The solve and set functions have been deliberately split up to reflect the inherentely iterative, and interactive nature of fitting the strength of a musculoskeletal model to data.
Before attempting to fit the strength of the muscles to experimental data we recommend that you pre-process the data first. Normally this involves filtering the joint angles using a zero-phase 2nd order low-pass Butterworth filter with a cutoff frequency of 8-10 Hz (for human data). This can be achieved in Matlab using the functions 'butter' and 'filtfilt'. Following this filtering step joint angular velocities can be safely calculated numerically using a central-difference method. If you fail to filter measured joint angles it is likely that the joint angular velocities you calculate will be noisy and will result in a terrible fit. This function is not magic, and so the rule garbage in, garbage out applies.

Parameters

tqMcl	The Millard2016TorqueMuscle object that is to be fitted.
jointAngle	(radians) A vector of measured joint angles. The sign of this vector must be consistent with the multibody model and this torque muscle.
jointAngularVelocity	(radians/s) A vector of joint angular velocities. The sign of this vector must be consistent with the multibody model and this torque muscle.
jointTorque	(Nm) A vector of joint torques. Only the values in this vector that have the same torque sign as the muscle are considered during the fitting process. This means, inherently, that the muscle fitting is done assuming that there is no co-contraction. If you want co-contraction to be included in the fitting process, you must preprocess this vector so that it just contains the (estimated) single-signed torque of the muscle in question. The sign of this vector must be consistent with the multibody model and this torque muscle.
activationUpperBound	(0,1] The maximum activation that is permitted for the given set of joint angles, joint angular velocities, and joint torques.
passiveTorqueAngleMultiplierUpperBound	(0, $\infty$ ] The maximum passive torque angle multipler that you expect to see when the muscle moves through the values in jointAngle. Note that a value of 1 is quite large: this corresponds to 1 maximum active isometric torque.
parametersOfBestFit	A structure that contains the parameters of best fit along with a summary of the internal variables of the muscle model at the points in the data where the peak passive forces are developed and where the maximum activation is developed.
verbose	Setting this to will print information from IPOPT to the screen during the solution process.

The documentation for this class was generated from the following file:

addons/muscle/TorqueMuscleFittingToolkit.h

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ fitTorqueMuscleParameters()