OpenSim::ContDerivMuscle Class Reference

A class implementing a SIMM muscle. More...

#include <ContDerivMuscle.h>

Inheritance diagram for OpenSim::ContDerivMuscle:

Public Member Functions
	ContDerivMuscle ()
	Default constructor.
	ContDerivMuscle (const ContDerivMuscle &aMuscle)
	Copy constructor.
virtual	~ContDerivMuscle ()
	Destructor.
virtual Object *	copy () const
	Copy this muscle point and return a pointer to the copy.
ContDerivMuscle &	operator= (const ContDerivMuscle &aMuscle)
	Assignment operator.
void	copyData (const ContDerivMuscle &aMuscle)
	Copy data members from one ContDerivMuscle to another.
virtual void	copyPropertyValues (Actuator &aActuator)
	Copy the property values from another actuator, which may not be a ContDerivMuscle.
virtual void	initStateCache (SimTK::State &s, SimTK::SubsystemIndex subsystemIndex, Model &model)
	allocate and initialize the SimTK state for this acuator.
virtual double	getMaxIsometricForce () const
	getMaxIsometricForce needs to be overridden by derived classes to be usable
virtual double	getOptimalFiberLength () const
virtual double	getTendonSlackLength () const
virtual double	getPennationAngleAtOptimalFiberLength () const
virtual double	getActivationTimeConstant () const
virtual double	getDeactivationTimeConstant () const
virtual double	getVmax () const
virtual double	getVmax0 () const
virtual double	getFmaxTendonStrain () const
virtual double	getFmaxMuscleStrain () const
virtual double	getKshapeActive () const
virtual double	getKshapePassive () const
virtual double	getDamping () const
virtual double	getAf () const
virtual double	getFlen () const
virtual double	getPennationAngle (const SimTK::State &s) const
	Get the current pennation angle of the muscle fiber(s).
virtual double	getNormalizedFiberLength (const SimTK::State &s) const
	_____________________________________________________________________________ /** Get the normalized length of the muscle fiber(s).
virtual double	getPassiveFiberForce (const SimTK::State &s) const
	Get the passive force generated by the muscle fibers.
virtual double	getStress (const SimTK::State &s) const
	getStress needs to be overridden by derived classes to be usable
virtual double	getActivation (const SimTK::State &s) const
virtual void	setActivation (SimTK::State &s, double activation) const
virtual double	getActivationDeriv (const SimTK::State &s) const
virtual void	setActivationDeriv (const SimTK::State &s, double activationDeriv) const
virtual double	getFiberLength (const SimTK::State &s) const
virtual void	setFiberLength (SimTK::State &s, double fiberLength) const
virtual double	getFiberLengthDeriv (const SimTK::State &s) const
virtual void	setFiberLengthDeriv (const SimTK::State &s, double fiberLengthDeriv) const
virtual void	setTendonForce (const SimTK::State &s, double aForce) const
virtual double	getTendonForce (const SimTK::State &s) const
virtual void	setActiveForce (const SimTK::State &s, double aForce) const
virtual double	getActiveForce (const SimTK::State &s) const
virtual void	setPassiveForce (const SimTK::State &s, double aForce) const
virtual double	getPassiveForce (const SimTK::State &s) const
virtual void	computeStateDerivatives (const SimTK::State &s)
	Compute the derivatives of the muscle states.
virtual void	computeEquilibrium (SimTK::State &s) const
	Compute the equilibrium states.
virtual double	computeActuation (const SimTK::State &s)
	Compute the actuation for the muscle.
double	calcTendonForce (const SimTK::State &s, double aNormTendonLength) const
	Tendon force is calculated by an integral-of-sigmoid function - zero for most negative inputs, linear for most positive inputs, and a toe region that's continuous and smooth with both linear regions.
double	calcPassiveForce (const SimTK::State &s, double aNormFiberLength) const
	Written by Darryl Thelen, modified by Tom Erez this routine calculates the passive force in the muscle fibers using an exponential-linear function instead of cubic splines.
double	calcActiveForce (const SimTK::State &s, double aNormFiberLength) const
	From gmc.dt.c - calc_active_force_dt.
double	calcFiberVelocity (const SimTK::State &s, double aActivation, double aActiveForce, double aVelocityDependentForce) const
	This function is based on the equations in appendix 3 to Lisa Schutte's Ph.D.
virtual double	computeIsometricForce (SimTK::State &s, double activation) const
	Find the force produced by an actuator (the musculotendon unit), assuming static equilibrium.
virtual double	computeIsokineticForceAssumingInfinitelyStiffTendon (SimTK::State &s, double aActivation)
	Find the force produced by muscle under isokinetic conditions assuming an infinitely stiff tendon.
virtual void	postScale (const SimTK::State &s, const ScaleSet &aScaleSet)
	Perform computations that need to happen after the muscle is scaled.
virtual void	scale (const SimTK::State &s, const ScaleSet &aScaleSet)
	Scale the muscle.
virtual void	setup (Model &aModel)
	Perform some set up functions that happen after the object has been deserialized or copied.
virtual void	equilibrate (SimTK::State &state) const
	OPENSIM_DECLARE_DERIVED (ContDerivMuscle, Actuator)
Protected Attributes
PropertyDbl	_maxIsometricForceProp
	Maximum isometric force that the fibers can generate.
double &	_maxIsometricForce
PropertyDbl	_optimalFiberLengthProp
	Optimal length of the muscle fibers.
double &	_optimalFiberLength
PropertyDbl	_tendonSlackLengthProp
	Resting length of the tendon.
double &	_tendonSlackLength
PropertyDbl	_pennationAngleProp
	Angle between tendon and fibers at optimal fiber length.
double &	_pennationAngle
PropertyDbl	_activationTimeConstantProp
	Activation time constant.
double &	_activationTimeConstant
PropertyDbl	_deactivationTimeConstantProp
	Deactivation time constant.
double &	_deactivationTimeConstant
PropertyDbl	_vmaxProp
	Max contraction velocity full activation in fiber lengths per second.
double &	_vmax
PropertyDbl	_vmax0Prop
	Max contraction velocity at low activation.
double &	_vmax0
PropertyDbl	_fmaxTendonStrainProp
	Tendon strain due to maximum isometric muscle force.
double &	_fmaxTendonStrain
PropertyDbl	_fmaxMuscleStrainProp
	Passive muscle strain due to maximum isometric muscle force.
double &	_fmaxMuscleStrain
PropertyDbl	_kShapeActiveProp
	Shape factor for Gaussian active muscle force-length relationship.
double &	_kShapeActive
PropertyDbl	_kShapePassiveProp
	Exponential shape factor for passive force-length relationship.
double &	_kShapePassive
PropertyDbl	_dampingProp
	Passive damping included in the force-velocity relationship.
double &	_damping
PropertyDbl	_afProp
	Force-velocity shape factor.
double &	_af
PropertyDbl	_flenProp
	Maximum normalized lengthening force.
double &	_flen
SimTK::CacheEntryIndex	_tendonForceIndex
	indexes for Forces in various components
SimTK::CacheEntryIndex	_activeForceIndex
SimTK::CacheEntryIndex	_passiveForceIndex

Detailed Description

A class implementing a SIMM muscle.

Author:: Peter Loan

Version:: 1.0

Constructor & Destructor Documentation

ContDerivMuscle::ContDerivMuscle ( )

Default constructor.

ContDerivMuscle::ContDerivMuscle ( const ContDerivMuscle & aMuscle )

Copy constructor.

Parameters:

aMuscle

ContDerivMuscle to be copied.

ContDerivMuscle::~ContDerivMuscle ( ) [virtual]

Destructor.

Member Function Documentation

double ContDerivMuscle::calcActiveForce	(	const SimTK::State &	s,
		double	aNormFiberLength
	)			const

From gmc.dt.c - calc_active_force_dt.

CALC_ACTIVE_FORCE_DT: this routine calculates the active component of force in the muscle fibers. It uses the current fiber length to interpolate the active force-length curve - described by Gaussian curve as in Thelen, JBME 2003 *

Parameters:

aNormFiberLength

Normalized length of the muscle fiber.

Returns:: The active force in the muscle fibers.

double ContDerivMuscle::calcFiberVelocity	(	const SimTK::State &	s,
		double	aActivation,
		double	aActiveForce,
		double	aVelocityDependentForce
	)			const

This function is based on the equations in appendix 3 to Lisa Schutte's Ph.D.

dissertation (Stanford, Dec. 1992), as implemented in the Schutte1993Muscle. My modification involves smoothing the transition between the two formulas using a sigmoidal function.

This equation is parameterized using the following dynamic parameters which must be specified in the muscle file Dynamic Parameters: damping - normalized passive damping in parallel with contractile element Af - velocity shape factor from Hill's equation Flen - Maximum normalized force when muscle is lengthening

Parameters:

	aActivation	Activation of the muscle.
	aActiveForce	Active force in the muscle fibers.
	aVelocityDependentForce	Force value that depends on fiber velocity.

Returns:: The velocity of the muscle fibers.

double ContDerivMuscle::calcPassiveForce	(	const SimTK::State &	s,
		double	aNormFiberLength
	)			const

Written by Darryl Thelen, modified by Tom Erez this routine calculates the passive force in the muscle fibers using an exponential-linear function instead of cubic splines.

This equation is parameterized using the following dynamic parameters which must be specified in the muscle file Dynamic Parameters: FmaxMuscleStrain - passive muscle strain due to the application of maximum isometric muscle force KshapePassive - exponential shape factor

The normalized force due to passive stretch is given by For L < (1+maxStrain)*Lo f/f0 = exp(ks*(L-1)/maxStrain) / exp(ks)

At higher normalized lengths, we transition to a linear model through a smoothed-sigmoidal transition.

Parameters:

aNormFiberLength

Normalized length of the muscle fiber.

Returns:: The passive force in the muscle fibers.

double ContDerivMuscle::calcTendonForce	(	const SimTK::State &	s,
		double	aNormTendonLength
	)			const

Tendon force is calculated by an integral-of-sigmoid function - zero for most negative inputs, linear for most positive inputs, and a toe region that's continuous and smooth with both linear regions.

The slope of the linear region is specified by the variable klin, and is taken from older code by Thelen. Currently, this value is about 51.87, which is bigger than the value found in the spline usually specifying the Schutte model (which has an effective slope of about 37.52).

The size of the toe region (where the function transitions from one linear region to another) is parameterized by "smoothcoef". The bigger its value, the wider the toe region. For smoothcoef=1, the area where the discrepency between the linear models and the function is bigger than 0.1 is about [-0.04, 0.04], and the area where it is bigger than 0.5 is smaller than [-0.01, 0.01], with maximum discrepency of about 0.7.

Note that while the tendon strain depends on the tendon length normalized in tendon slack length units, the input to this function is assumed to be the tendon length normalized in optimal fiber length units, hence the transformations in the first two lines.

FmaxTendonStrain - this function is parameterized by the tendon strain due to maximum isometric muscle force This should be specified as a dynamic parameter in the muscle file

Parameters:

aNormTendonLength

Normalized length of the tendon.

Returns:: The force in the tendon.

double ContDerivMuscle::computeActuation ( const SimTK::State & s ) [virtual]

Compute the actuation for the muscle.

This function assumes that computeDerivatives has already been called.

This function is based on muscle_deriv_func9 from derivs.c (old pipeline code)

void ContDerivMuscle::computeEquilibrium ( SimTK::State & s ) const [virtual]

Compute the equilibrium states.

This method computes a fiber length for the muscle that is consistent with the muscle's activation level.

Reimplemented from OpenSim::Actuator.

double ContDerivMuscle::computeIsokineticForceAssumingInfinitelyStiffTendon	(	SimTK::State &	s,
		double	aActivation
	)			`[virtual]`

Find the force produced by muscle under isokinetic conditions assuming an infinitely stiff tendon.

That is, all the shortening velocity of the actuator (the musculotendon unit) is assumed to be due to the shortening of the muscle fibers alone. This methods calls computeIsometricForce() and so alters the internal member variables of this muscle.

Note that the current implementation approximates the effect of the force-velocity curve. It does not account for the shortening velocity when it is solving for the equilibrium length of the muscle fibers. And, a generic representation of the force-velocity curve is used (as opposed to the implicit force-velocity curve assumed by this model.

Parameters:

aActivation

Activation of the muscle.

Returns:: Isokinetic force generated by the actuator.

Implements OpenSim::Muscle.

double ContDerivMuscle::computeIsometricForce	(	SimTK::State &	s,
		double	aActivation
	)			const `[virtual]`

Find the force produced by an actuator (the musculotendon unit), assuming static equilibrium.

Using the total muscle-tendon length, it finds the fiber and tendon lengths so that the forces in each match. This routine takes pennation angle into account, so its definition of static equilibrium is when tendon_force = fiber_force * cos(pennation_angle). This funcion will modify the object's values for _length, _fiberLength, _activeForce, and _passiveForce.

Parameters:

aActivation

Activation of the muscle.

Returns:: The isometric force in the muscle.

Implements OpenSim::Muscle.

void ContDerivMuscle::computeStateDerivatives ( const SimTK::State & s ) [virtual]

Compute the derivatives of the muscle states.

Parameters:

rDYDT

the state derivatives are returned here.

Reimplemented from OpenSim::Actuator.

Object * ContDerivMuscle::copy ( ) const [virtual]

Copy this muscle point and return a pointer to the copy.

The copy constructor for this class is used.

Returns:: Pointer to a copy of this ContDerivMuscle.

Implements OpenSim::Muscle.

void ContDerivMuscle::copyData ( const ContDerivMuscle & aMuscle )

Copy data members from one ContDerivMuscle to another.

Parameters:

aMuscle

ContDerivMuscle to be copied.

Reimplemented from OpenSim::Muscle.

void ContDerivMuscle::copyPropertyValues ( Actuator & aActuator ) [virtual]

Copy the property values from another actuator, which may not be a ContDerivMuscle.

Parameters:

aActuator

Actuator to copy property values from.

void ContDerivMuscle::equilibrate ( SimTK::State & state ) const [virtual]

Reimplemented from OpenSim::Muscle.

virtual double OpenSim::ContDerivMuscle::getActivation ( const SimTK::State & s ) const [inline, virtual]

Implements OpenSim::Muscle.

virtual double OpenSim::ContDerivMuscle::getActivationDeriv ( const SimTK::State & s ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getActivationTimeConstant ( ) const [inline, virtual]

double ContDerivMuscle::getActiveForce ( const SimTK::State & s ) const [virtual]

virtual double OpenSim::ContDerivMuscle::getAf ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getDamping ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getDeactivationTimeConstant ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getFiberLength ( const SimTK::State & s ) const [inline, virtual]

Implements OpenSim::Muscle.

virtual double OpenSim::ContDerivMuscle::getFiberLengthDeriv ( const SimTK::State & s ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getFlen ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getFmaxMuscleStrain ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getFmaxTendonStrain ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getKshapeActive ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getKshapePassive ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getMaxIsometricForce ( ) const [inline, virtual]

getMaxIsometricForce needs to be overridden by derived classes to be usable

Reimplemented from OpenSim::Muscle.

double ContDerivMuscle::getNormalizedFiberLength ( const SimTK::State & s ) const [virtual]

_____________________________________________________________________________ /** Get the normalized length of the muscle fiber(s).

This is the current fiber length(s) divided by the optimal fiber length.

Parameters:

Current

length of the muscle fiber(s).

Implements OpenSim::Muscle.

virtual double OpenSim::ContDerivMuscle::getOptimalFiberLength ( ) const [inline, virtual]

double ContDerivMuscle::getPassiveFiberForce ( const SimTK::State & s ) const [virtual]

Get the passive force generated by the muscle fibers.

Parameters:

Current

passive force of the muscle fiber(s).

Implements OpenSim::Muscle.

double ContDerivMuscle::getPassiveForce ( const SimTK::State & s ) const [virtual]

double ContDerivMuscle::getPennationAngle ( const SimTK::State & s ) const [virtual]

Get the current pennation angle of the muscle fiber(s).

Parameters:

Pennation

angle.

Implements OpenSim::Muscle.

virtual double OpenSim::ContDerivMuscle::getPennationAngleAtOptimalFiberLength ( ) const [inline, virtual]

Implements OpenSim::Muscle.

double ContDerivMuscle::getStress ( const SimTK::State & s ) const [virtual]

getStress needs to be overridden by derived classes to be usable

Reimplemented from OpenSim::Actuator.

double ContDerivMuscle::getTendonForce ( const SimTK::State & s ) const [virtual]

virtual double OpenSim::ContDerivMuscle::getTendonSlackLength ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getVmax ( ) const [inline, virtual]

virtual double OpenSim::ContDerivMuscle::getVmax0 ( ) const [inline, virtual]

void ContDerivMuscle::initStateCache	(	SimTK::State &	s,
		SimTK::SubsystemIndex	subsystemIndex,
		Model &	model
	)			`[virtual]`

allocate and initialize the SimTK state for this acuator.

Reimplemented from OpenSim::Muscle.

OpenSim::ContDerivMuscle::OPENSIM_DECLARE_DERIVED	(	ContDerivMuscle	,
		Actuator
	)

Reimplemented from OpenSim::CustomActuator.

ContDerivMuscle & ContDerivMuscle::operator= ( const ContDerivMuscle & aMuscle )

Assignment operator.

Returns:: Reference to this object.

Reimplemented from OpenSim::Muscle.

void ContDerivMuscle::postScale	(	const SimTK::State &	s,
		const ScaleSet &	aScaleSet
	)			`[virtual]`

Perform computations that need to happen after the muscle is scaled.

For this object, that entails comparing the musculotendon length before and after scaling, and scaling some of the force-generating properties a proportional amount.

Parameters:

aScaleSet

XYZ scale factors for the bodies.

Reimplemented from OpenSim::Muscle.