OpenSim::Muscle Class Reference

A base class representing a muscle-tendon actuator. More...

#include <Muscle.h>

Inheritance diagram for OpenSim::Muscle:

Public Member Functions
	Muscle ()
	Default constructor.
	Muscle (const Muscle &aMuscle)
	Copy constructor.
virtual	~Muscle ()
	Destructor.
virtual Object *	copy () const =0
	Construct and return a copy of this object.
virtual void	setup (Model &aModel)
	Perform set up functions after model has been deserialized or copied.
virtual void	postInit (Model &aModel)
	Perform set up functions after initSystem() has been called on the model.
void	setName (const std::string &aName)
Muscle &	operator= (const Muscle &aMuscle)
	Assignment operator.
void	copyData (const Muscle &aMuscle)
	Copy data members from one Muscle to another.
virtual void	updateFromXMLNode ()
	Override of the default implementation to account for versioning.
virtual void	initState (SimTK::State &s) const
	This is called after a SimTK System and State have been created for the Model.
virtual void	setDefaultsFromState (const SimTK::State &state)
	Set all default values for this object to match those in a specified State.
virtual void	initStateCache (SimTK::State &s, SimTK::SubsystemIndex subsystemIndex, Model &model)
	allocate and initialize the SimTK state for this acuator.
virtual void	equilibrate (SimTK::State &state) const
virtual double	getPennationAngleAtOptimalFiberLength () const =0
GeometryPath &	getGeometryPath () const
void	addNewPathPoint (const std::string &proposedName, OpenSim::Body &aBody, const SimTK::Vec3 &aPositionOnBody)
	Note that this function does not maintain the State and so should be used only before a valid State is created.
virtual double	getDefaultActivation () const
virtual void	setDefaultActivation (double activation)
virtual double	getDefaultFiberLength () const
virtual void	setDefaultFiberLength (double length)
virtual double	getPennationAngle (const SimTK::State &s) const =0
virtual double	getLength (const SimTK::State &s) const
	Get the length of the muscle.
virtual double	getTendonLength (const SimTK::State &s) const
	Get the length of the tendon.
virtual double	getFiberLength (const SimTK::State &s) const =0
virtual void	setFiberLength (SimTK::State &s, double fiberLength) const =0
virtual double	getNormalizedFiberLength (const SimTK::State &s) const =0
virtual double	getFiberLengthAlongTendon (const SimTK::State &s) const
	Get the length of the muscle fiber(s) along the tendon.
virtual double	getShorteningSpeed (const SimTK::State &s) const
virtual double	getFiberForce (const SimTK::State &s) const
	Compute the force generated by the muscle fibers.
virtual double	getActiveFiberForce (const SimTK::State &s) const
	Get the active force generated by the muscle fibers.
virtual double	getPassiveFiberForce (const SimTK::State &s) const =0
virtual double	getActiveFiberForceAlongTendon (const SimTK::State &s) const
	Get the active force generated by the muscle fibers along the direction of the tendon.
virtual double	getPassiveFiberForceAlongTendon (const SimTK::State &s) const
	Get the passive force generated by the muscle fibers along the direction of the tendon.
virtual double	getMaxIsometricForce () const
	getMaxIsometricForce needs to be overridden by derived classes to be usable
virtual double	getActivation (const SimTK::State &s) const =0
virtual void	setActivation (SimTK::State &s, double activation) const =0
virtual double	getExcitation (const SimTK::State &s) const
virtual double	computeActuation (const SimTK::State &s) const
	Compute values needed for calculating the muscle's actuation.
virtual double	computeIsometricForce (SimTK::State &s, double activation) const =0
virtual double	computeIsokineticForceAssumingInfinitelyStiffTendon (SimTK::State &s, double aActivation)=0
virtual double	evaluateForceLengthVelocityCurve (double aActivation, double aNormalizedLength, double aNormalizedVelocity)
	Evaluate the normalized force-length-velocity curve for the muscle.
virtual double	calcPennation (double aFiberLength, double aOptimalFiberLength, double aInitialPennationAngle) const
	Utility function to calculate the current pennation angle in a muscle.
virtual OpenSim::Array < std::string >	getRecordLabels () const
	Methods to query a Force for the value actually applied during simulation The names of the quantities (column labels) is returned by this first function getRecordLabels().
virtual OpenSim::Array< double >	getRecordValues (const SimTK::State &state) const
	Given SimTK::State object extract all the values necessary to report forces, application location frame, etc.
virtual VisibleObject *	getDisplayer () const
virtual void	updateDisplayer (const SimTK::State &s)
	Update the visible object used to represent the muscle.
	OPENSIM_DECLARE_DERIVED (Muscle, CustomActuator)
Static Public Member Functions
static void	deleteMuscle (Muscle *aMuscle)
static double	EstimateActivation (double aTRise, double aTFall, double aA0, double aX, double aDT)
	Estimate an new activation level given an initial activation level, an excitation level, and a time interval.
static double	InvertActivation (double aTRise, double aTFall, double aA0, double aA, double aDT)
	Invert the equation for activation dynamics in order to compute an excitation value which will produce a given change in activation over a given time interval.
static double	DADT (double aTRise, double aTFall, double aX, double aA)
	Compute the time derivative of an activation level given its excitation signal, a rise-time, and a fall-time.
static double	DADTNonlinear (double aTRise, double aTFall, double aX, double aA)
	Compute the time derivative of an activation level given its excitation signal, a rise-time, and a fall-time.
static double	f (double aFMax, double aA)
	Compute the force in an actuator given its maximum force and activation state.
Protected Member Functions
virtual void	preScale (const SimTK::State &s, const ScaleSet &aScaleSet)
	Perform computations that need to happen before the muscle is scaled.
virtual void	scale (const SimTK::State &s, const ScaleSet &aScaleSet)
	Scale the muscle based on XYZ scale factors for each body.
virtual void	postScale (const SimTK::State &s, const ScaleSet &aScaleSet)
	Perform computations that need to happen after the muscle is scaled.
virtual void	computeForce (const SimTK::State &s) const
	Apply the muscle's force at its points of attachment to the bodies.
virtual void	updateGeometry (const SimTK::State &s) const
Protected Attributes
PropertyObj	_pathProp
GeometryPath &	_path
double	_defaultActivation
double	_defaultFiberLength

Detailed Description

A base class representing a muscle-tendon actuator.

It adds data and methods to Actuator, but does not implement all of the necessary methods, so it is abstract too. The path information for a muscle is contained in this class, and the force-generating behavior should be defined in the derived classes.

Author:: Peter Loan; Frank C. Anderson

Version:: 1.0

Constructor & Destructor Documentation

Muscle::Muscle ( )

Default constructor.

Muscle::Muscle ( const Muscle & aMuscle )

Copy constructor.

Parameters:

aMuscle

Muscle to be copied.

Muscle::~Muscle ( ) [virtual]

Destructor.

Member Function Documentation

void Muscle::addNewPathPoint	(	const std::string &	proposedName,
		OpenSim::Body &	aBody,
		const SimTK::Vec3 &	aPositionOnBody
	)

Note that this function does not maintain the State and so should be used only before a valid State is created.

Add a Muscle point to the _path of the muscle.

The new point is appended to the end of the current path

double Muscle::calcPennation	(	double	aFiberLength,
		double	aOptimalFiberLength,
		double	aInitialPennationAngle
	)			const `[virtual]`

Utility function to calculate the current pennation angle in a muscle.

Pennation angle increases as muscle fibers shorten. The implicit modeling assumption is that muscles have constant width.

Parameters:

	aFiberLength	Current fiber length of muscle.
	aOptimalFiberLength	Optimal fiber length of muscle.
	aInitialPennationAngle	Pennation angle at optimal fiber length (in radians).

Returns:: Current pennation angle (in radians).

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

Compute values needed for calculating the muscle's actuation.

Right now this is only speed (contraction velocity; all other calculations are handled by the derived classes).

Implements OpenSim::Actuator.

Reimplemented in OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::computeForce ( const SimTK::State & s ) const [protected, virtual]

Apply the muscle's force at its points of attachment to the bodies.

Implements OpenSim::CustomActuator.

virtual double OpenSim::Muscle::computeIsokineticForceAssumingInfinitelyStiffTendon	(	SimTK::State &	s,
		double	aActivation
	)			`[pure virtual]`

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual double OpenSim::Muscle::computeIsometricForce	(	SimTK::State &	s,
		double	activation
	)			const `[pure virtual]`

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual Object* OpenSim::Muscle::copy ( ) const [pure virtual]

Construct and return a copy of this object.

The object is allocated using the new operator, so the caller is responsible for deleting the returned object.

Returns:: Copy of this object.

Implements OpenSim::Actuator.

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::copyData ( const Muscle & aMuscle )

Copy data members from one Muscle to another.

Parameters:

aMuscle

Muscle to be copied.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::DADT	(	double	aTRise,
		double	aTFall,
		double	aX,
		double	aA
	)			`[static]`

Compute the time derivative of an activation level given its excitation signal, a rise-time, and a fall-time.

This method represents the rise or fall using a simple 1st order differential equation which is linear in x and a. The time constant is chosen based on whether x is greater than or less than a.

double Muscle::DADTNonlinear	(	double	aTRise,
		double	aTFall,
		double	aX,
		double	aA
	)			`[static]`

Compute the time derivative of an activation level given its excitation signal, a rise-time, and a fall-time.

This method represents the rise and fall using a 1st order differential equation which is non-linear in x. The advantange of this method is that a single equation is used. However, the equation is only valid if tFall is mutch greater than tRise.

static void OpenSim::Muscle::deleteMuscle ( Muscle * aMuscle ) [inline, static]

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

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::EstimateActivation	(	double	aTRise,
		double	aTFall,
		double	aA0,
		double	aX,
		double	aDT
	)			`[static]`

Estimate an new activation level given an initial activation level, an excitation level, and a time interval.

The assumptions are that the excitation is constant over the interval and that activation dynamics is represented as a pure exponential. The equation for activation is

at = x - (x-a0)*exp[-dt/tau]

Parameters:

	aTRise	Activation rise time constant.
	aTFall	Activation fall time constant.
	aA0	Starting value of activation.
	aX	Excitation value.
	aDT	Time interval over which activation is to change.

Returns:: Estimated activation level.

double Muscle::evaluateForceLengthVelocityCurve	(	double	aActivation,
		double	aNormalizedLength,
		double	aNormalizedVelocity
	)			`[virtual]`

Evaluate the normalized force-length-velocity curve for the muscle.

A simple generic implementation is used here. Derived classes should override this method for more precise evaluation of the force-length-velocity curve.

Parameters:

	aActivation	Activation level of the muscle. 1.0 is full activation; 0.0 is no activation.
	aNormalizedLength	Normalized length of the muscle fibers. 1.0 indicates the muscle fibers are at their optimal length. Lnorm = L / Lo.
	aNormalizedVelocity	Normalized shortening velocity of the muscle fibers. Positive values indicate concentric contraction (shortening); negative values indicate eccentric contraction (lengthening). Normalized velocity is the fiber shortening velocity divided by the maximum shortening velocity times the optimal fiber length. Vnorm = V / (Vmax*Lo).

Returns:: Force normalized by the optimal force.

double Muscle::f	(	double	aFMax,
		double	aA
	)			`[static]`

Compute the force in an actuator given its maximum force and activation state.

virtual double OpenSim::Muscle::getActivation ( const SimTK::State & s ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::getActiveFiberForce ( const SimTK::State & s ) const [virtual]

Get the active force generated by the muscle fibers.

Returns:: Current active force of the muscle fibers.

double Muscle::getActiveFiberForceAlongTendon ( const SimTK::State & s ) const [virtual]

Get the active force generated by the muscle fibers along the direction of the tendon.

Returns:: Current active force of the muscle fibers along tendon.

double Muscle::getDefaultActivation ( ) const [virtual]

double Muscle::getDefaultFiberLength ( ) const [virtual]

virtual VisibleObject* OpenSim::Muscle::getDisplayer ( ) const [inline, virtual]

Reimplemented from OpenSim::Object.

double Muscle::getExcitation ( const SimTK::State & s ) const [virtual]

double Muscle::getFiberForce ( const SimTK::State & s ) const [virtual]

Compute the force generated by the muscle fibers.

This accounts for pennation angle. That is, the fiber force is computed by dividing the actuator force by the cosine of the pennation angle.

Returns:: Force in the muscle fibers.

virtual double OpenSim::Muscle::getFiberLength ( const SimTK::State & s ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::getFiberLengthAlongTendon ( const SimTK::State & s ) const [virtual]

Get the length of the muscle fiber(s) along the tendon.

This method accounts for the pennation angle.

Returns:: Current length of the muscle fiber(s) along the direction of the tendon.

GeometryPath& OpenSim::Muscle::getGeometryPath ( ) const [inline]

double Muscle::getLength ( const SimTK::State & s ) const [virtual]

Get the length of the muscle.

This is a convenience function that passes the request on to the muscle path.

Returns:: Current length of the muscle path.

double Muscle::getMaxIsometricForce ( ) const [virtual]

getMaxIsometricForce needs to be overridden by derived classes to be usable

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual double OpenSim::Muscle::getNormalizedFiberLength ( const SimTK::State & s ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual double OpenSim::Muscle::getPassiveFiberForce ( const SimTK::State & s ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::getPassiveFiberForceAlongTendon ( const SimTK::State & s ) const [virtual]

Get the passive force generated by the muscle fibers along the direction of the tendon.

Returns:: Current passive force of the muscle fibers along tendon.

virtual double OpenSim::Muscle::getPennationAngle ( const SimTK::State & s ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual double OpenSim::Muscle::getPennationAngleAtOptimalFiberLength ( ) const [pure virtual]

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual OpenSim::Array<std::string> OpenSim::Muscle::getRecordLabels ( ) const [inline, virtual]

Methods to query a Force for the value actually applied during simulation The names of the quantities (column labels) is returned by this first function getRecordLabels().

Reimplemented from OpenSim::Force.

virtual OpenSim::Array<double> OpenSim::Muscle::getRecordValues ( const SimTK::State & state ) const [inline, virtual]

Given SimTK::State object extract all the values necessary to report forces, application location frame, etc.

used in conjunction with getRecordLabels and should return same size Array

Reimplemented from OpenSim::Force.

double Muscle::getShorteningSpeed ( const SimTK::State & s ) const [virtual]

double Muscle::getTendonLength ( const SimTK::State & s ) const [virtual]

Get the length of the tendon.

Returns:: Current length of the tendon.

void Muscle::initState ( SimTK::State & state ) const [virtual]

This is called after a SimTK System and State have been created for the Model.

It may be overridden to set initial values of state variables.

Parameters:

state

the State to initialize

Reimplemented from OpenSim::ModelComponent.

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

allocate and initialize the SimTK state for this acuator.

Reimplemented from OpenSim::Actuator.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

double Muscle::InvertActivation	(	double	aTRise,
		double	aTFall,
		double	aA0,
		double	aA,
		double	aDT
	)			`[static]`

Invert the equation for activation dynamics in order to compute an excitation value which will produce a given change in activation over a given time interval.

The assumptions are that the excitation is constant over the interval and that activation dynamics is represented as a pure exponential. The equation which is inverted is

at = x - (x-a0)*exp[-dt/tau]

Parameters:

Parameters:

	aTRise	The rise time constant.
	aTFall	The fall time constant.
	aA0	The starting value of activation
	aA	The final desired value of activation.
	aDT	The time interval over which a is to change.

Returns:: Excitation that will achieve the desired activation.

OpenSim::Muscle::OPENSIM_DECLARE_DERIVED	(	Muscle	,
		CustomActuator
	)

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

Assignment operator.

Parameters:

aMuscle

The muscle from which to copy its data

Returns:: Reference to this object.

Reimplemented from OpenSim::Actuator.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::postInit ( Model & aModel ) [virtual]

Perform set up functions after initSystem() has been called on the model.

Parameters:

aModel

The model containing this muscle.

Reimplemented from OpenSim::Force.

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

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

For this object, that entails updating the muscle path. Derived classes should probably also scale or update some of the force-generating properties.

Parameters:

aScaleSet

XYZ scale factors for the bodies.

Reimplemented from OpenSim::Actuator.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::preScale	(	const SimTK::State &	s,
		const ScaleSet &	aScaleSet
	)			`[protected, virtual]`

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

For this object, that entails calculating and storing the muscle-tendon length in the current body position.

Parameters:

aScaleSet

XYZ scale factors for the bodies.

Reimplemented from OpenSim::Actuator.

void Muscle::scale	(	const SimTK::State &	s,
		const ScaleSet &	aScaleSet
	)			`[protected, virtual]`

Scale the muscle based on XYZ scale factors for each body.

Parameters:

aScaleSet

XYZ scale factors for the bodies.

Returns:: Whether muscle was successfully scaled or not.

Reimplemented from OpenSim::Actuator.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

virtual void OpenSim::Muscle::setActivation	(	SimTK::State &	s,
		double	activation
	)			const `[pure virtual]`

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::setDefaultActivation ( double activation ) [virtual]

void Muscle::setDefaultFiberLength ( double length ) [virtual]

void Muscle::setDefaultsFromState ( const SimTK::State & state ) [virtual]

Set all default values for this object to match those in a specified State.

It should be overridden to set any default values defined by each subclass.

Parameters:

state

the State from which to take values that should become the defaults for this object

Reimplemented from OpenSim::ModelComponent.

virtual void OpenSim::Muscle::setFiberLength	(	SimTK::State &	s,
		double	fiberLength
	)			const `[pure virtual]`

Implemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void OpenSim::Muscle::setName ( const std::string & aName )

Reimplemented from OpenSim::Object.

void Muscle::setup ( Model & aModel ) [virtual]

Perform set up functions after model has been deserialized or copied.

Parameters:

aModel

The model containing this muscle.

Reimplemented from OpenSim::Actuator.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void Muscle::updateDisplayer ( const SimTK::State & s ) [virtual]

Update the visible object used to represent the muscle.

Reimplemented from OpenSim::Actuator.

void Muscle::updateFromXMLNode ( ) [virtual]

Override of the default implementation to account for versioning.

Override default implementation by object to intercept and fix the XML node underneath the model to match current version.

Reimplemented from OpenSim::Object.

void Muscle::updateGeometry ( const SimTK::State & s ) const [protected, virtual]

Member Data Documentation

double OpenSim::Muscle::_defaultActivation [protected]

double OpenSim::Muscle::_defaultFiberLength [protected]

GeometryPath& OpenSim::Muscle::_path [protected]

PropertyObj OpenSim::Muscle::_pathProp [protected]

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

OpenSim/Simulation/Model/Muscle.h
OpenSim/Simulation/Model/Muscle.cpp

OpenSim::Muscle Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation