Simbody
3.6

This force element implements a passive elastic element (like a rubber band) that follows a frictionless CablePath across a set of "obstacles". More...
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 Topologystage parameters normally set in the constructor; these determine the initial values assigned to the corresponding Instancestage state variables.
 
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 Instancestage 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 corresponding setDefault...() methods.
 
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...  
Positionrelated Quantities  
These methods return positiondependent 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.
 
Real  getLength (const State &state) const 
Return the current length of the CablePath that underlies this cable spring element. More...  
Velocityrelated Quantities  
These methods return velocitydependent 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.
 
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.
 
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 workrelated 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 nonvirtual. 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...  
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.
Given current CablePath length L with time derivative Ldot, and slack length L0 for this force element, define stretch x=max(0,LL0) 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 ratedependent 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 ratedependent dissipation in the elastic element, is calculated as a fraction of the stretchdependent 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 physicallyrealizable 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).
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.
[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. 

inline 
Default constructor creates an empty handle.
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.
[in]  stiffness  The spring constant k to be used by default. 
CableSpring& SimTK::CableSpring::setDefaultSlackLength  (  Real  slackLength  ) 
Set the slack length L0 that will be used by default for this cable spring; must be nonnegative.
[in]  slackLength  The slack length L0 to be used by default. 
CableSpring& SimTK::CableSpring::setDefaultDissipationCoef  (  Real  dissipation  ) 
Set the dissipation coefficient c that will be used by default for this cable spring; must be nonnegative.
[in]  dissipation  The dissipation coefficient c to be used by default. 
Real SimTK::CableSpring::getDefaultStiffness  (  )  const 
Return the stiffnesses k that will be used by default for this cable spring.
Real SimTK::CableSpring::getDefaultSlackLength  (  )  const 
Return the slack length L0 that will be used by default for this cable spring.
Real SimTK::CableSpring::getDefaultDissipationCoef  (  )  const 
Return the dissipation coefficient c that will be used by default for this cable spring.
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.
[in,out]  state  The State object to be modified by this method. 
[in]  stiffness  The spring constant k. 
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.
[in,out]  state  The State object to be modified by this method. 
[in]  slackLength  The slack length L0. 
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.
[in,out]  state  The State object that is modified by this method. 
[in]  dissipationCoef  The dissipation coefficient c. 
Return the stiffness (spring constant) k currently being used for this cable spring by this State.
[in]  state  The State object from which to obtain the stiffness. 
Return the slack length L0 currently being used for this cable spring by this State.
[in]  state  The State object from which to obtain the slack length. 
Return the dissipation coefficient c currently being used for this cable spring by this State.
[in]  state  The State object from which to obtain the dissipation coefficient. 
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.
state  The State from which the path length is retrieved. 
Return the current rate of length change (time derivative of length) of the CablePath that underlies this cable spring element.
state  The State from which the path length rate of change is retrieved. 
Return the current level of tension in the cable spring.
[in]  state  The State from which the current tension is retrieved. 
Obtain the potential energy stored in this cable spring in the current configuration.
[in]  state  The State from whose cache the potential energy is retrieved. 
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.
[in]  state  The State from which to obtain the current value of the power dissipation. 
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 nonconservative 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.
[in]  state  The State from which to obtain the current value of the dissipated energy. 
Set the accumulated dissipated energy to an arbitrary value.
Typically this is used only to reset the dissipated energy to zero, but nonzero 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.
[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.