Simbody  3.7
SimTK::CableSpring Class Reference

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

+ 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.
CableSpringsetDefaultStiffness (Real stiffness)
 Set the stiffness (spring constant) k that will be used by default for this cable spring; must be nonnegative. More...
 
CableSpringsetDefaultSlackLength (Real slackLength)
 Set the slack length L0 that will be used by default for this cable spring; must be nonnegative. More...
 
CableSpringsetDefaultDissipationCoef (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 corresponding 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 CableSpringsetStiffness (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 CableSpringsetSlackLength (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 CableSpringsetDissipationCoef (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 CablePathgetCablePath () 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 GeneralForceSubsystemgetForceSubsystem () 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...
 
PIMPLHandlereferenceAssign (const Force &source)
 "Copy" assignment but with shallow (pointer) semantics. More...
 
PIMPLHandlecopyAssign (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...
 
PIMPLHandleoperator= (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

◆ CableSpring() [1/2]

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]defaultDissipationCoefA nonnegative dissipation coefficient for this elastic element in units of 1/velocity.

◆ CableSpring() [2/2]

SimTK::CableSpring::CableSpring ( )
inline

Default constructor creates an empty handle.

Member Function Documentation

◆ setDefaultStiffness()

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]stiffnessThe spring constant k to be used by default.
Returns
A writable reference to "this" CableSpring which will now have the new default stiffness.

◆ setDefaultSlackLength()

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]slackLengthThe slack length L0 to be used by default.
Returns
A writable reference to "this" CableSpring which will now have the new default slack length.

◆ setDefaultDissipationCoef()

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]dissipationThe dissipation coefficient c to be used by default.
Returns
A writable reference to "this" CableSpring which will now have the new default dissipation coefficient.

◆ getDefaultStiffness()

Real SimTK::CableSpring::getDefaultStiffness ( ) const

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

Returns
The default spring constant.

◆ getDefaultSlackLength()

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.

◆ getDefaultDissipationCoef()

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.

◆ setStiffness()

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]stateThe State object to be modified by this method.
[in]stiffnessThe spring constant k.
Returns
A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

◆ setSlackLength()

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]stateThe State object to be modified by this method.
[in]slackLengthThe slack length L0.
Returns
A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

◆ setDissipationCoef()

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]stateThe State object that is modified by this method.
[in]dissipationCoefThe dissipation coefficient c.
Returns
A const reference to "this" CableSpring for convenient chaining of set...() methods in a single expression.

◆ getStiffness()

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]stateThe State object from which to obtain the stiffness.
Returns
The current value in the given state of the spring constant k.

◆ getSlackLength()

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]stateThe State object from which to obtain the slack length.
Returns
The current value in the given state of the slack length L0.

◆ getDissipationCoef()

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]stateThe State object from which to obtain the dissipation coefficient.
Returns
The current value in the given state of the dissipation coefficient c.

◆ getLength()

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
stateThe State from which the path length is retrieved.
Returns
The current length of the underlying CablePath (nonnegative).
See also
getLengthDot()

◆ 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
stateThe State from which the path length rate of change is retrieved.
Returns
The current length change rate of the underlying CablePath.
See also
getLength()

◆ getTension()

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).

◆ getPotentialEnergy()

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).

◆ getPowerDissipation()

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

◆ getDissipatedEnergy()

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

◆ setDissipatedEnergy()

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).

◆ getCablePath()

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: