This force element implements a passive elastic element (like a rubber band) that follows a frictionless CablePath across a set of "obstacles". More...

#include <CableSpring.h>

Inheritance diagram for SimTK::CableSpring:

Public Member Functions
	CableSpring (GeneralForceSubsystem &forces, const CablePath &path, Real defaultStiffness, Real defaultSlackLength, Real defaultDissipationCoef)
	Create an elastic force element that follows a given CablePath and add it to a GeneralForceSubsystem. More...

	CableSpring ()
	Default constructor creates an empty handle. More...

Default Parameters
These refer to Topology-stage parameters normally set in the constructor; these determine the initial values assigned to the corresponding Instance-stage state variables. Notes Changing one of these parameters invalidates the containing System's topology, meaning that realizeTopology() will have to be called before subsequent use. The set...() methods return a reference to "this" CableSpring (in the manner of an assignment operator) so they can be chained in a single expression.
CableSpring &	setDefaultStiffness (Real stiffness)
	Set the stiffness (spring constant) k that will be used by default for this cable spring; must be nonnegative. More...

CableSpring &	setDefaultSlackLength (Real slackLength)
	Set the slack length L0 that will be used by default for this cable spring; must be nonnegative. More...

CableSpring &	setDefaultDissipationCoef (Real dissipation)
	Set the dissipation coefficient c that will be used by default for this cable spring; must be nonnegative. More...

Real	getDefaultStiffness () const
	Return the stiffnesses k that will be used by default for this cable spring. More...

Real	getDefaultSlackLength () const
	Return the slack length L0 that will be used by default for this cable spring. More...

Real	getDefaultDissipationCoef () const
	Return the dissipation coefficient c that will be used by default for this cable spring. More...

Instance Parameters
These refer to the Instance-stage state variables that determine the geometry and material properties that will be used in computations involving this cable spring when performed with the given State. If these are not set explicitly, the default values are set to those provided in the constructor or via the correponding setDefault...() methods. Notes Changing one of these parameters invalidates the given State's Instance stage, meaning that realize(Instance) will have to be called (explicitly or implicitly by realizing a higher stage) before subsequent use. The set...() methods here return a const reference to "this" CableSpring (in the manner of an assignment operator, except read-only) so they can be chained in a single expression.
const CableSpring &	setStiffness (State &state, Real stiffness) const
	Set the stiffness (spring constant) k that will be used for this cable spring when evaluated using this State. More...

const CableSpring &	setSlackLength (State &state, Real slackLength) const
	Set the slack length L0 that will be used for this cable spring when evaluated using this State. More...

const CableSpring &	setDissipationCoef (State &state, Real dissipationCoef) const
	Set the dissipation coefficient c that will be used for this cable spring when evaluated using this State. More...

Real	getStiffness (const State &state) const
	Return the stiffness (spring constant) k currently being used for this cable spring by this State. More...

Real	getSlackLength (const State &state) const
	Return the slack length L0 currently being used for this cable spring by this State. More...

Real	getDissipationCoef (const State &state) const
	Return the dissipation coefficient c currently being used for this cable spring by this State. More...

Position-related Quantities
These methods return position-dependent quantities that are calculated by the cable spring as part of its force calculations and stored in the State cache. These can be obtained at no cost, although the first call after a position change may initiate computation if forces haven't already been computed. Precondition These methods may be called only after the supplied state has been realized to Stage::Position.
Real	getLength (const State &state) const
	Return the current length of the CablePath that underlies this cable spring element. More...

Velocity-related Quantities
These methods return velocity-dependent quantities that are calculated by the cable spring as part of its force calculations and stored in the State cache. These can be obtained at no cost, although the first call after a velocity change may initiate computation if forces haven't already been computed. Precondition These methods may be called only after the supplied state has been realized to Stage::Velocity.
Real	getLengthDot (const State &state) const
	Return the current rate of length change (time derivative of length) of the CablePath that underlies this cable spring element. More...

Forces
These methods return the forces being applied by this cable spring in the configuration and velocities contained in the supplied State. These are evaluated during force calculation and available at no computational cost afterwards, although the first call after a velocity change may initiate computation if forces haven't already been computed. Precondition These methods may be called only after the supplied state has been realized to Stage::Velocity.
Real	getTension (const State &state) const
	Return the current level of tension in the cable spring. More...

Energy, Power, and Work
These methods return the energy, power, and work-related quantities associated with this CableSpring element for the values in the supplied State.
Real	getPotentialEnergy (const State &state) const
	Obtain the potential energy stored in this cable spring in the current configuration. More...

Real	getPowerDissipation (const State &state) const
	Obtain the rate at which energy is being dissipated by this cable spring, that is, the power being lost (presumably due to heat). More...

Real	getDissipatedEnergy (const State &state) const
	Obtain the total amount of energy dissipated by this cable spring since some arbitrary starting point. More...

void	setDissipatedEnergy (State &state, Real energy) const
	Set the accumulated dissipated energy to an arbitrary value. More...

Advanced/obscure/debugging
Miscellaneous methods that you probably aren't going to need.
const CablePath &	getCablePath () const
	Get a reference to the CablePath that is used to determine the routing of this cable spring force element. More...

Public Member Functions inherited from SimTK::Force
void	disable (State &) const
	Disable this force element, effectively removing it from the System for computational purposes (it is still using its ForceIndex, however). More...

void	enable (State &) const
	Enable this force element if it was previously disabled. More...

bool	isDisabled (const State &) const
	Test whether this force element is currently disabled in the supplied State. More...

void	setDisabledByDefault (bool shouldBeDisabled)
	Normally force elements are enabled when defined and can be disabled later. More...

bool	isDisabledByDefault () const
	Test whether this force element is disabled by default in which case it must be explicitly enabled before it will take effect. More...

void	calcForceContribution (const State &state, Vector_< SpatialVec > &bodyForces, Vector_< Vec3 > &particleForces, Vector &mobilityForces) const
	Calculate the force that would be applied by this force element if the given state were realized to Dynamics stage. More...

Real	calcPotentialEnergyContribution (const State &state) const
	Calculate the potential energy contribution that is made by this force element at the given state. More...

	Force ()
	Default constructor for Force handle base class does nothing. More...

	operator ForceIndex () const
	Implicit conversion to ForceIndex when needed. More...

const GeneralForceSubsystem &	getForceSubsystem () const
	Get the GeneralForceSubsystem of which this Force is an element. More...

ForceIndex	getForceIndex () const
	Get the index of this force element within its parent force subsystem. More...

Public Member Functions inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
bool	isEmptyHandle () const
	Returns true if this handle is empty, that is, does not refer to any implementation object. More...

bool	isOwnerHandle () const
	Returns true if this handle is the owner of the implementation object to which it refers. More...

bool	isSameHandle (const Force &other) const
	Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...

void	disown (Force &newOwner)
	Give up ownership of the implementation to an empty handle. More...

PIMPLHandle &	referenceAssign (const Force &source)
	"Copy" assignment but with shallow (pointer) semantics. More...

PIMPLHandle &	copyAssign (const Force &source)
	This is real copy assignment, with ordinary C++ object ("value") semantics. More...

void	clearHandle ()
	Make this an empty handle, deleting the implementation object if this handle is the owner of it. More...

const ForceImpl &	getImpl () const
	Get a const reference to the implementation associated with this Handle. More...

ForceImpl &	updImpl ()
	Get a writable reference to the implementation associated with this Handle. More...

int	getImplHandleCount () const
	Return the number of handles the implementation believes are referencing it. More...

Additional Inherited Members
Public Types inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
typedef PIMPLHandle< Force, ForceImpl, PTR >	HandleBase

typedef HandleBase	ParentHandle

Protected Member Functions inherited from SimTK::Force
	Force (ForceImpl *r)
	Use this in a derived Force handle class constructor to supply the concrete implementation object to be stored in the handle base. More...

Protected Member Functions inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
	PIMPLHandle ()
	The default constructor makes this an empty handle. More...

	PIMPLHandle (ForceImpl *p)
	This provides consruction of a handle referencing an existing implementation object. More...

	PIMPLHandle (const PIMPLHandle &source)
	The copy constructor makes either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer semantics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...

	~PIMPLHandle ()
	Note that the destructor is non-virtual. More...

PIMPLHandle &	operator= (const PIMPLHandle &source)
	Copy assignment makes the current handle either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer sematics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...

void	setImpl (ForceImpl *p)
	Set the implementation for this empty handle. More...

bool	hasSameImplementation (const Force &other) const
	Determine whether the supplied handle is a reference to the same implementation object as is referenced by "this" PIMPLHandle. More...

Detailed Description

This force element implements a passive elastic element (like a rubber band) that follows a frictionless CablePath across a set of "obstacles".

The element calculates a uniform nonnegative tension that is used to apply forces at the end points of the CablePath and to each intermediate obstacle. The model provides stiffness and dissipation, and has a slack length below which the tension is zero and no forces are generated. Dissipated power is calculated and integrated so that work lost to dissipation is available for conservation of energy calculations.

Theory:

Given current CablePath length L with time derivative Ldot, and slack length L0 for this force element, define stretch x=max(0,L-L0) and xdot=Ldot. Then calculate the nonnegative tension f(x,xdot), the potential energy pe(x) stored in this force element, and dissipating power powerLoss(x,xdot) due to rate-dependent resistance to length change, as follows:

    f_stretch   = k*x
    f_rate      = max(-f_stretch, f_stretch*c*xdot)    
    f           = f_stretch + f_rate
    pe          = k*x^2/2
    powerLoss   = f_rate * xdot
    dissipation = integ(powerLoss, dt)

where k >= 0 is the stiffness coefficient (force per unit length) and c >= 0 is the dissipation coefficient (1/velocity) for this force element.

Note that in this model the tension component f_rate, due to rate-dependent dissipation in the elastic element, is calculated as a fraction of the stretch-dependent tension component f_stretch, similar to a Hunt and Crossley contact model. That is why the dissipation coefficient c has units of 1/velocity, rather than force/velocity. This makes the generated tension grow smoothly from zero as the slack length is exceeded, but even so this is not necessarily a good model for any particular physically-realizable elastic element. A ligament, for example, while perhaps qualitatively similar to this element, is likely to require a more complicated relationship between x, xdot, and f to yield quantitative agreement with experimental data.

While the total tension f must be nonnegative, the tension f_rate due to stretch rate can be positive (resists stretching) or negative (resists shortening) but can never be less than -f_stretch since f can't be negative. When a stretched cable spring is shortening so rapidly that force due to dissipation cancels the force due to stiffness, there will be no tension generated but we will still dissipate power at a rate that exactly accounts for the continuing loss of potential energy in the spring (k*x*xdot) as it shortens to its slack length. In that way total energy E=pe+ke+dissipation is conserved, where dissipation is the time integral of powerLoss calculated above (note that powerLoss >= 0 as defined).

See Also: CablePath, CableTrackerSubsystem

Constructor & Destructor Documentation

SimTK::CableSpring::CableSpring	(	GeneralForceSubsystem &	forces,
		const CablePath &	path,
		Real	defaultStiffness,
		Real	defaultSlackLength,
		Real	defaultDissipationCoef
	)

Create an elastic force element that follows a given CablePath and add it to a GeneralForceSubsystem.

Default values for the cable spring properties are given here; you can override them in the State. See the CableSpring class description for a detailed explanation of these parameters.

Parameters

[in,out]	forces	The subsystem to which this force element should be added.
[in]	path	The CablePath that defines the routing of this elastic element over geometric obstacles.
[in]	defaultStiffness	A nonnegative spring constant representing the stiffness of this element, in units of force/length, where the force represents a uniform tension along the element that results from stretching it beyond its slack length.
[in]	defaultSlackLength	The maximum length this elastic element can have before it begins to generate force. At or below this length the element is slack and has zero tension and zero power dissipation.
[in]	defaultDissipationCoef	A nonnegative dissipation coefficient for this elastic element in units of 1/velocity.

SimTK::CableSpring::CableSpring ( )

inline

Default constructor creates an empty handle.

Member Function Documentation

CableSpring& SimTK::CableSpring::setDefaultStiffness ( Real stiffness )

Set the stiffness (spring constant) k that will be used by default for this cable spring; must be nonnegative.

Parameters

[in] stiffness The spring constant k to be used by default.

Returns: A writable reference to "this" CableSpring which will now have the new default stiffness.

CableSpring& SimTK::CableSpring::setDefaultSlackLength ( Real slackLength )

Set the slack length L0 that will be used by default for this cable spring; must be nonnegative.

Parameters

[in] slackLength The slack length L0 to be used by default.

Returns: A writable reference to "this" CableSpring which will now have the new default slack length.

CableSpring& SimTK::CableSpring::setDefaultDissipationCoef ( Real dissipation )

Set the dissipation coefficient c that will be used by default for this cable spring; must be nonnegative.

Parameters

[in] dissipation The dissipation coefficient c to be used by default.

Returns: A writable reference to "this" CableSpring which will now have the new default dissipation coefficient.

Real SimTK::CableSpring::getDefaultStiffness ( ) const

Return the stiffnesses k that will be used by default for this cable spring.

Returns: The default spring constant.

Real SimTK::CableSpring::getDefaultSlackLength ( ) const

Return the slack length L0 that will be used by default for this cable spring.

Returns: The default slack length.

Real SimTK::CableSpring::getDefaultDissipationCoef ( ) const

Return the dissipation coefficient c that will be used by default for this cable spring.

Returns: The default dissipation coefficient.

const CableSpring& SimTK::CableSpring::setStiffness	(	State &	state,
		Real	stiffness
	)		const

Set the stiffness (spring constant) k that will be used for this cable spring when evaluated using this State.

Precondition: state realized to Stage::Topology

Parameters

[in,out]	state	The State object to be modified by this method.
[in]	stiffness	The spring constant k.

Returns: A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

const CableSpring& SimTK::CableSpring::setSlackLength	(	State &	state,
		Real	slackLength
	)		const

Set the slack length L0 that will be used for this cable spring when evaluated using this State.

Precondition: state realized to Stage::Topology

Parameters

[in,out]	state	The State object to be modified by this method.
[in]	slackLength	The slack length L0.

Returns: A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

const CableSpring& SimTK::CableSpring::setDissipationCoef	(	State &	state,
		Real	dissipationCoef
	)		const

Set the dissipation coefficient c that will be used for this cable spring when evaluated using this State.

Precondition: state realized to Stage::Topology

Parameters

[in,out]	state	The State object that is modified by this method.
[in]	dissipationCoef	The dissipation coefficient c.

Returns: A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

Real SimTK::CableSpring::getStiffness ( const State & state ) const

Return the stiffness (spring constant) k currently being used for this cable spring by this State.

Precondition: state realized to Stage::Topology

Parameters

[in] state The State object from which to obtain the stiffness.

Returns: The current value in the given state of the spring constant k.

Real SimTK::CableSpring::getSlackLength ( const State & state ) const

Return the slack length L0 currently being used for this cable spring by this State.

Precondition: state realized to Stage::Topology

Parameters

[in] state The State object from which to obtain the slack length.

Returns: The current value in the given state of the slack length L0.

Real SimTK::CableSpring::getDissipationCoef ( const State & state ) const

Return the dissipation coefficient c currently being used for this cable spring by this State.

Precondition: state realized to Stage::Topology

Parameters

[in] state The State object from which to obtain the dissipation coefficient.

Returns: The current value in the given state of the dissipation coefficient c.

Real SimTK::CableSpring::getLength ( const State & state ) const

Return the current length of the CablePath that underlies this cable spring element.

Note that this may return a value less than the spring's slack length.

Precondition: state realized to Stage::Position

Parameters

state The State from which the path length is retrieved.

Returns: The current length of the underlying CablePath (nonnegative).

See Also: getLengthDot()

Real SimTK::CableSpring::getLengthDot ( const State & state ) const

Return the current rate of length change (time derivative of length) of the CablePath that underlies this cable spring element.

Precondition: state realized to Stage::Velocity

Parameters

state The State from which the path length rate of change is retrieved.

Returns: The current length change rate of the underlying CablePath.

See Also: getLength()

Real SimTK::CableSpring::getTension ( const State & state ) const

Return the current level of tension in the cable spring.

Precondition: state realized to Stage::Velocity

Parameters

[in] state The State from which the current tension is retrieved.

Returns: The current tension in the cable spring in the configuration and velocity contained in state (a nonnegative scalar).

Real SimTK::CableSpring::getPotentialEnergy ( const State & state ) const

Obtain the potential energy stored in this cable spring in the current configuration.

Precondition: state realized to Stage::Position

Parameters

[in] state The State from whose cache the potential energy is retrieved.

Returns: The potential energy currently contained in the cable spring in the configuration contained in state (a nonnegative scalar).

Real SimTK::CableSpring::getPowerDissipation ( const State & state ) const

Obtain the rate at which energy is being dissipated by this cable spring, that is, the power being lost (presumably due to heat).

This is in units of energy/time which is watts in MKS.

Precondition: state realized to Stage::Velocity

Parameters

[in] state The State from which to obtain the current value of the power dissipation.

Returns: The instantaneous power dissipation (a nonnegative scalar).

See Also: getDissipatedEnergy() for the time-integrated power loss

Real SimTK::CableSpring::getDissipatedEnergy ( const State & state ) const

Obtain the total amount of energy dissipated by this cable spring since some arbitrary starting point.

This is the time integral of the power dissipation. For a system whose only non-conservative forces are cable springs, the sum of potential, kinetic, and dissipated energies should be conserved. This is a State variable so you can obtain its value any time after it is allocated.

Precondition: state realized to Stage::Model

Parameters

[in] state The State from which to obtain the current value of the dissipated energy.

Returns: The total dissipated energy (a nonnegative scalar).

See Also: getPowerDissipation() for the instantaneous power loss

void SimTK::CableSpring::setDissipatedEnergy	(	State &	state,
		Real	energy
	)		const

Set the accumulated dissipated energy to an arbitrary value.

Typically this is used only to reset the dissipated energy to zero, but non-zero values can be useful if you are trying to match some existing data or continuing a simulation. This is a State variable so you can set its value any time after it is allocated.

Precondition: state realized to Stage::Model

Parameters

[in,out]	state	The State whose dissipated energy variable for this cable spring is to be modified.
[in]	energy	The new value for the accumulated dissipated energy (must be a nonnegative scalar).

const CablePath& SimTK::CableSpring::getCablePath ( ) const

Get a reference to the CablePath that is used to determine the routing of this cable spring force element.

This is set during CableSpring construction and cannot be changed subsequently.

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

CableSpring.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation