Simbody  3.7
SimTK::Force Class Reference

This is the base class from which all Force element handle classes derive. More...

+ Inheritance diagram for SimTK::Force:

Classes

class  ConstantForce
 A constant force applied to a body station. More...
 
class  ConstantTorque
 A constant torque to a body. More...
 
class  Custom
 This class is used to define new force elements. More...
 
class  DiscreteForces
 Arbitrary discrete body forces and mobility (generalized) forces. Useful for applying external forces or forces that are updated at discrete times due to the occurrence of events. More...
 
class  GlobalDamper
 A general energy "drain" on the system. More...
 
class  Gravity
 This force element represents a uniform gravitational field applied to a set of bodies. More...
 
class  LinearBushing
 This force element represents a bushing acting to connect a frame F fixed on one body (B1) to a frame M fixed on a second body (B2), by a massless, compliant element with linear stiffness and damping properties. More...
 
class  MobilityConstantForce
 A constant generalized force f (a scalar) applied to a mobility. More...
 
class  MobilityDiscreteForce
 A discrete mobility (generalized) force f applied to a particular mobility that is specified at construction. Useful for applying external forces or forces that are updated at discrete times due to the occurrence of events. More...
 
class  MobilityLinearDamper
 A linear damper that acts along or around a mobility coordinate to apply a generalized force there. More...
 
class  MobilityLinearSpring
 A linear spring that acts along or around a mobility coordinate to apply a generalized force there. More...
 
class  MobilityLinearStop
 Model a compliant stop element that acts to keep a mobilizer coordinate q within specified bounds. More...
 
class  Thermostat
 This is a feedback-controlled force that uses Nose'-Hoover chains to maintain a particular temperature Tb, as though the system were immersed in an infinite heat bath at that temperature. More...
 
class  TwoPointConstantForce
 A constant force f (a signed scalar) which acts along the line between two points, specified as a station on each of two bodies. More...
 
class  TwoPointLinearDamper
 A force which resists changes in the distance between two points, acting along the line between those points. More...
 
class  TwoPointLinearSpring
 A linear spring between two points, specified as a station on each of two bodies. More...
 
class  UniformGravity
 A uniform gravitational force applied to every body in the system. See Force::Gravity for a more flexible option. More...
 

Public Member Functions

Enabling and disabling

These methods determine whether this force element is active in a given State.

When disabled, the Force element is completely ignored and will not be updated during realization. Normally force elements are enabled when defined unless explicitly disabled; you can reverse that using the setDisabledByDefault() method below.

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...
 
Advanced methods

Don't use these unless you're sure you know what you're doing.

They aren't normally necessary but can be handy sometimes, especially when debugging newly-developed force elements.

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

These methods are not normally needed.

They provide bookkeeping information such as access to the parent force subsystem and the force index assigned to this force element.

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

Protected Member Functions

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

Additional Inherited Members

- Public Types inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
typedef PIMPLHandle< Force, ForceImpl, PTR > HandleBase
 
typedef HandleBase ParentHandle
 

Detailed Description

This is the base class from which all Force element handle classes derive.

A Force object applies forces to some or all of the bodies, particles, and mobilities in a System. There are subclasses for various standard types of forces, or you can create your own forces by deriving from Force::Custom.

Constructor & Destructor Documentation

◆ Force() [1/2]

SimTK::Force::Force ( )
inline

Default constructor for Force handle base class does nothing.

◆ Force() [2/2]

SimTK::Force::Force ( ForceImpl *  r)
inlineexplicitprotected

Use this in a derived Force handle class constructor to supply the concrete implementation object to be stored in the handle base.

Member Function Documentation

◆ disable()

void SimTK::Force::disable ( State ) const

Disable this force element, effectively removing it from the System for computational purposes (it is still using its ForceIndex, however).

This is an Instance-stage change.

◆ enable()

void SimTK::Force::enable ( State ) const

Enable this force element if it was previously disabled.

This is an Instance-stage change. Nothing happens if the force element was already enabled.

◆ isDisabled()

bool SimTK::Force::isDisabled ( const State ) const

Test whether this force element is currently disabled in the supplied State.

If it is disabled you cannot depend on any computations it normally performs being available.

◆ setDisabledByDefault()

void SimTK::Force::setDisabledByDefault ( bool  shouldBeDisabled)

Normally force elements are enabled when defined and can be disabled later.

If you want to define this force element but have it be off by default, use this method. Note that this is a Topology-stage (construction) change; you will have to call realizeTopology() before using the containing System after a change to this setting has been made.

◆ isDisabledByDefault()

bool SimTK::Force::isDisabledByDefault ( ) const

Test whether this force element is disabled by default in which case it must be explicitly enabled before it will take effect.

See also
enable()

◆ calcForceContribution()

void SimTK::Force::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.

This sizes the given arrays if necessary, zeroes them, and then calls the force element's calcForce() method which adds its force contributions if any to the appropriate array elements for bodies, particles, and mobilities. Note that in general we have no idea what elements of the system are affected by a force element, and in fact that can change based on state and time (consider contact forces, for example). A disabled force element will return all zeroes without invoking calcForce(), since that method may depend on earlier computations which may not have been performed in that case.

Parameters
[in]stateThe State containing information to be used by the force element to calculate the current force. This must have already been realized to a high enough stage for the force element to get what it needs; if you don't know then realize it to Stage::Velocity.
[out]bodyForcesThis is a Vector of spatial forces, one per mobilized body in the matter subsystem associated with this force element. This Vector is indexed by MobilizedBodyIndex so it has a 0th entry corresponding to Ground. A spatial force contains two Vec3's; index with [0] to get the moment vector, with [1] to get the force vector. This argument is resized if necessary to match the number of mobilized bodies and any unused entry will be set to zero on return.
[out]particleForcesThis is a Vector of force vectors, one per particle in the matter subsystem associated with this force element. This vector is indexed by ParticleIndex; the 0th entry is the 1st particle, not Ground. This argument is resized if necessary to match the number of particles and any unused entry will be set to zero on return. (As of March 2010 Simbody treats particles as mobilized bodies so this is unused.)
[out]mobilityForcesThis is a Vector of scalar generalized forces, one per mobility in the matter subsystem associated with this force element. This is the same as the number of generalized speeds u that collectively represent all the mobilities of the mobilizers. To determine the per-mobilizer correspondence, you must call methods of MobilizedBody; there is no hint here.
Note
This method must zero out the passed in arrays, and in most cases almost all returned entries will be zero, so this is not the most efficent way to calculate forces; use it sparingly.

◆ calcPotentialEnergyContribution()

Real SimTK::Force::calcPotentialEnergyContribution ( const State state) const

Calculate the potential energy contribution that is made by this force element at the given state.

This calls the force element's calcPotentialEnergy() method. A disabled force element will return zero without invoking calcPotentialEnergy().

Parameters
[in]stateThe State containing information to be used by the force element to calculate the current potential energy. This must have already been realized to a high enough stage for the force element to get what it needs; if you don't know then realize it to Stage::Position.
Returns
The potential energy contribution of this force element at this state value.

◆ operator ForceIndex()

SimTK::Force::operator ForceIndex ( ) const
inline

Implicit conversion to ForceIndex when needed.

This will throw an exception if the force element has not yet been adopted by a force subsystem.

◆ getForceSubsystem()

const GeneralForceSubsystem& SimTK::Force::getForceSubsystem ( ) const

Get the GeneralForceSubsystem of which this Force is an element.

This will throw an exception if the force element has not yet been adopted by a force subsystem.

◆ getForceIndex()

ForceIndex SimTK::Force::getForceIndex ( ) const

Get the index of this force element within its parent force subsystem.

The returned index will be invalid if the force element has not yet been adopted by any subsystem (test with the index.isValid() method).


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