Simbody
3.6

This force element represents a uniform gravitational field applied to a set of bodies. More...
Public Member Functions  
Construction  
Methods in this section refer both to constructors, and to methods that can be used to set or change construction (Topologystage) parameters; these specify the values assigned by default to the corresponding state variables. Note:
 
Gravity (GeneralForceSubsystem &forces, const SimbodyMatterSubsystem &matter, const UnitVec3 &down, Real g, Real zeroHeight=0)  
This is the most general constructor for creating a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, given gravity magnitude and direction separately. More...  
Gravity (GeneralForceSubsystem &forces, const SimbodyMatterSubsystem &matter, const Vec3 &gravity)  
Convenience constructor to create a Gravity force element by specifying only a gravity vector, that is, the product of the gravity magnitude and the "down" direction vector. More...  
Gravity (GeneralForceSubsystem &forces, const SimbodyMatterSubsystem &matter, Real g)  
Convenience constructor to create a Gravity force element by specifying only gravity's magnitude, with the direction chosen to oppose the containing System's "up" direction. More...  
Gravity ()  
Default constructor creates an empty handle. More...  
Gravity &  setDefaultBodyIsExcluded (MobilizedBodyIndex mobod, bool isExcluded) 
Set how the indicated body is to be treated by default. More...  
Gravity &  setDefaultGravityVector (const Vec3 &gravity) 
Set the default value for the gravity vector, that is, the direction and magnitude with which gravity will act. More...  
Gravity &  setDefaultDownDirection (const UnitVec3 &down) 
Set the default "down" direction d, that is, the direction along which gravity will act. More...  
Gravity &  setDefaultDownDirection (const Vec3 &down) 
Convenience overload that takes the down direction as a Vec3 and normalizes it (throwing away the magnitude) to create the required unit vector for the down direction. More...  
Gravity &  setDefaultMagnitude (Real g) 
Set the default magnitude of gravity (a nonegative scalar). More...  
Gravity &  setDefaultZeroHeight (Real zeroHeight) 
Set the default zero height (a signed scalar), for use in potential energy calculation. More...  
bool  getDefaultBodyIsExcluded (MobilizedBodyIndex mobod) const 
Return the current setting of the "is excluded by default" flag for the given body. More...  
Vec3  getDefaultGravityVector () const 
Return the default gravity vector being used for this Gravity force element, calculated from the default magnitude and direction. More...  
const UnitVec3 &  getDefaultDownDirection () const 
Return the default down direction (a unit vector) for this Gravity force element. More...  
Real  getDefaultMagnitude () const 
Return the default gravity magnitude g (a nonnegative scalar). More...  
Real  getDefaultZeroHeight () const 
Return the default zero height used in the calculation of graviational potential energy. More...  
Runtime Changes  
These refer to Dynamicsstage discrete state variables that determine the actual values to be used to calculate gravitational forces and energy from a given State object, and which bodies are to be excluded from that calculation. If these are not set explicitly, the values are set to those provided in the constructor or via the corresponding setDefault...() methods. Note:
 
const Gravity &  setBodyIsExcluded (State &state, MobilizedBodyIndex mobod, bool isExcluded) const 
Within a given State, selectively exclude (or include) a body from the effects of this Gravity force. More...  
const Gravity &  setGravityVector (State &state, const Vec3 &gravity) const 
Set the gravity vector v, that is, the magnitude and direction with which gravitational forces will act, overriding the default magnitude and direction that are stored in this Gravity force element. More...  
const Gravity &  setDownDirection (State &state, const UnitVec3 &down) const 
Set the "down" direction d (a unit vector), that is, the direction along which gravitational forces will act. More...  
const Gravity &  setDownDirection (State &state, const Vec3 &down) const 
Convenience overload that takes the down direction as a Vec3 and normalizes it (throwing away the magnitude) to create the required unit vector. More...  
const Gravity &  setMagnitude (State &state, Real g) const 
Set the gravity magnitude g (a nonnegative scalar) in this state, overriding the default gravity magnitude that is stored in this Gravity force element. More...  
const Gravity &  setZeroHeight (State &state, Real hz) const 
Set the potential energy zero height hz (a scalar) in this state, overriding the default zero height that is stored in this Gravity force element. More...  
bool  getBodyIsExcluded (const State &state, MobilizedBodyIndex mobod) const 
Return the current setting of the "is excluded" flag for a given body in a given State. More...  
Vec3  getGravityVector (const State &state) const 
Get the gravity vector v that will be used for computations done with this state. More...  
const UnitVec3 &  getDownDirection (const State &state) const 
Get the gravity "down" direction d (a unit vector) that is currently set in this state. More...  
Real  getMagnitude (const State &state) const 
Get the gravity magnitude g (a nonnegative scalar) that is currently set in this state. More...  
Real  getZeroHeight (const State &state) const 
Get the zero height hz that is currently set in this state for use in calculating gravitational potential energy. More...  
Energy and Forces  
These methods return the gravitational potential energy and the forces being applied by this Gravity element in the configuration contained in the supplied State. These are evaluated during force calculation and available at no computational cost afterwards, although the first call after a position or runtime variable change will initiate computation if forces haven't already been computed.  
Real  getPotentialEnergy (const State &state) const 
Obtain the gravitational potential energy contained in this Gravity force element in the given configuration. More...  
const Vector_< SpatialVec > &  getBodyForces (const State &state) const 
Obtain a reference to the set of gravitational forces currently being applied by this Gravity force element, as a Vector of spatial forces indexed by MobilizedBodyIndex. More...  
const SpatialVec &  getBodyForce (const State &state, MobilizedBodyIndex mobod) const 
Convenience method to extract the gravitational force on just one body; see getBodyForces() to get the whole set at once, and for more information. More...  
Debugging/Testing  
This is information for use by developers of this class for debugging and testing – please ignore.  
long long  getNumEvaluations () const 
Return a count of the number of times the set of gravitational forces or potential energy was calculated since this force element was constructed. More...  
bool  isForceCacheValid (const State &state) const 
Return true if the gravitational forces for this configuration have already been calculated and are up to date. More...  
void  invalidateForceCache (const State &state) const 
Invalidate the stored gravitational forces if they have already been calculated at this configuration. 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 represents a uniform gravitational field applied to a set of bodies.
This can be used instead of the more limited Force::UniformGravity class if you want more control.
Force::Gravity is given a magnitude g in units of acceleration, and a "down" direction (unit vector) d, expressed in the Ground frame. For example, in SI units "standard gravity" g at the Earth's surface is defined to be exactly g=9.80665 m/s^2. If gravity acts in Ground's Y direction, then its direction vector is d=[0,1,0]; together this yields a gravity vector v=g*d=[0,9.80665,0]. By default gravity will be applied to each MobilizedBody in the given SimbodyMatterSubsystem (except for Ground). You can specify that some bodies are excluded; those will not have a gravity force applied. You can include multiple Force::Gravity elements with different exclusion lists in the same System if you want different bodies to feel different effects.
SimTK::Force::Gravity::Gravity  (  GeneralForceSubsystem &  forces, 
const SimbodyMatterSubsystem &  matter,  
const UnitVec3 &  down,  
Real  g,  
Real  zeroHeight = 0 

) 
This is the most general constructor for creating a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, given gravity magnitude and direction separately.
If you want to exclude by default some bodies from the effects of this force element, call setDefaultBodyIsExcluded(). You can also make changes on the fly with setBodyIsExcluded().
[in,out]  forces  The subsystem to which this force should be added. 
[in]  matter  The subsystem containing the bodies that will be affected. 
[in]  down  The default gravity direction vector d (i.e., the "down" direction), expressed in the Ground frame. Gravity will be directed along this direction unless explicitly changed within a particular State via the setDirection() or setGravityVector() methods. This is a unit vector; if you provide an ordinary Vec3 it will be normalized before use and its magnitude ignored. It is an error to provide a zero vector here; provide a zero magnitude instead or use the alternate constructor. 
[in]  g  The default magnitude g to be used for gravity, given as a nonnegative scalar with units of acceleration. The gravity vector is calculated as v=g*d where d is the current direction vector, typically the default direction as given by the down argument to this constructor. Gravity will have the magnitude given here unless explicitly changed within a particular State via the setMagnitude() or setGravityVector() methods. 
[in]  zeroHeight  This is an optional specification of the default value for the height up the gravity vector that is considered to be "zero" for purposes of calculating the gravitational potential energy. The default is zeroHeight == 0, i.e., a body's potential energy is defined to be zero when the height of its mass center is the same as the height of the Ground origin. The zero height will have the value specified here unless explicitly changed within a particular State use the setZeroHeight() method. 
SimTK::Force::Gravity::Gravity  (  GeneralForceSubsystem &  forces, 
const SimbodyMatterSubsystem &  matter,  
const Vec3 &  gravity  
) 
Convenience constructor to create a Gravity force element by specifying only a gravity vector, that is, the product of the gravity magnitude and the "down" direction vector.
We have to extract both a magnitude and direction from this since they are maintained separately by this force element. If you provide a zero vector here (exactly zero, that is), then the magnitude is zero but there is no direction. In that case we default to the negative of the containing System's default "up" direction.
If you want to exclude by default some bodies from the effects of this force element, call setDefaultBodyIsExcluded(). You can also make changes on the fly with setBodyIsExcluded().
[in,out]  forces  The subsystem to which this force should be added. 
[in]  matter  The subsystem containing the bodies that will be affected. 
[in]  gravity  The default gravity vector v, interpreted as v=g*d where g=gravity is a positive scalar and d is the "down" direction unit vector d=gravity/g. If the magnitude is exactly zero we'll set the "down" direction to the opposite of the containing System's "up" direction, otherwise the direction is extracted from the given vector. 
This constructor sets the default zero height hz to zero (for use in calculating gravitational potential energy). If you want a different default value, use the more general constructor or the setDefaultZeroHeight() method.
SimTK::Force::Gravity::Gravity  (  GeneralForceSubsystem &  forces, 
const SimbodyMatterSubsystem &  matter,  
Real  g  
) 
Convenience constructor to create a Gravity force element by specifying only gravity's magnitude, with the direction chosen to oppose the containing System's "up" direction.
Note that the direction is extracted from the System and recorded when this Gravity element is constructed; it will not be affected by subsequent changes to the System's up direction.
If you want to exclude by default some bodies from the effects of this force element, call setDefaultBodyIsExcluded(). You can also make changes on the fly with setBodyIsExcluded().
[in,out]  forces  The subsystem to which this force should be added. 
[in]  matter  The subsystem containing the bodies that will be affected. 
[in]  g  The default magnitude g to be used for gravity, given as a nonnegative scalar with units of acceleration. Gravity will have the magnitude given here unless explicitly changed within a particular State via the setMagnitude() or setGravityVector() methods. 
This constructor sets the default zero height hz to zero (for use in calculating gravitational potential energy). If you want a different default value, use the more general constructor or the setDefaultZeroHeight() method.

inline 
Default constructor creates an empty handle.
Gravity& SimTK::Force::Gravity::setDefaultBodyIsExcluded  (  MobilizedBodyIndex  mobod, 
bool  isExcluded  
) 
Set how the indicated body is to be treated by default.
Normally all bodies except Ground are affected by this force element so you only need to call this if you want to exclude a body. This is a topological change since the flag will be stored with the System; for onthefly changes you should call setBodyIsExcluded() instead. Ground is always excluded; you can call this method on Ground but the call will be ignored.
[in]  mobod  This is a MobilizedBody or MobilizedBodyIndex for the body whose default exclusion status you want to change. 
[in]  isExcluded  Set to true if the default should be that this body is not to be affected by this Gravity force element. 
Set the default value for the gravity vector, that is, the direction and magnitude with which gravity will act.
From the given vector we extract separately the magnitude g and "down" direction d (a unit vector), unless the magnitude is exactly zero in which case we'll leave the direction unchanged.
[in]  gravity  A vector giving the magnitude and direction with which gravity will act on the bodies. If exactly zero only the magnitude will be changed. 
Set the default "down" direction d, that is, the direction along which gravity will act.
[in]  down  A unit vector giving the direction along which gravity will act ("down"). If you pass an ordinary Vec3, it will be normalized before use and its length will be ignored. Do not pass a zerolength Vec3, however. 
Convenience overload that takes the down direction as a Vec3 and normalizes it (throwing away the magnitude) to create the required unit vector for the down direction.
It is an error if the supplied Vec3 has zero length.
Set the default magnitude of gravity (a nonegative scalar).
This will be combined with the default direction unit vector d to calculate the gravity vector v = g*d that is used to generate body forces mb*v where mb is the mass of body b and the force is applied to b's mass center.
[in]  g  The magnitude of the uniform gravitational field, given as a nonnegative scalar in units of acceleration. If this is zero no forces will be applied by this element. 
Set the default zero height (a signed scalar), for use in potential energy calculation.
See the Gravity class comments for how this is used.
[in]  zeroHeight  The height that is considered to be "zero" for purposes of potential energy calculation. An affected body whose mass center is at this height will have zero gravitational potential energy. 
bool SimTK::Force::Gravity::getDefaultBodyIsExcluded  (  MobilizedBodyIndex  mobod  )  const 
Return the current setting of the "is excluded by default" flag for the given body.
This is the status that the flag will have in the default State returned by System::realizeTopology().
[in]  mobod  This is a MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to obtain. 
true
for Ground. Vec3 SimTK::Force::Gravity::getDefaultGravityVector  (  )  const 
Return the default gravity vector being used for this Gravity force element, calculated from the default magnitude and direction.
const UnitVec3& SimTK::Force::Gravity::getDefaultDownDirection  (  )  const 
Return the default down direction (a unit vector) for this Gravity force element.
Real SimTK::Force::Gravity::getDefaultMagnitude  (  )  const 
Return the default gravity magnitude g (a nonnegative scalar).
Real SimTK::Force::Gravity::getDefaultZeroHeight  (  )  const 
Return the default zero height used in the calculation of graviational potential energy.
const Gravity& SimTK::Force::Gravity::setBodyIsExcluded  (  State &  state, 
MobilizedBodyIndex  mobod,  
bool  isExcluded  
)  const 
Within a given State, selectively exclude (or include) a body from the effects of this Gravity force.
The default State will inherit the "is excluded by default" values set during construction, but then you can change them. Ground is always excluded; you can call this method on Ground but the call will be ignored.
[in,out]  state  The State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity. 
[in]  mobod  This is a MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to change. 
[in]  isExcluded  Set to true if this body should not be affected by this force element. 
const Gravity& SimTK::Force::Gravity::setGravityVector  (  State &  state, 
const Vec3 &  gravity  
)  const 
Set the gravity vector v, that is, the magnitude and direction with which gravitational forces will act, overriding the default magnitude and direction that are stored in this Gravity force element.
If the given vector is exactly zero, then only the magnitude will be changed here.
[in,out]  state  The State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity. 
[in]  gravity  The gravity vector including both the magnitude and direction. If this is exactly zero only the magnitude will be changed. 
const Gravity& SimTK::Force::Gravity::setDownDirection  (  State &  state, 
const UnitVec3 &  down  
)  const 
Set the "down" direction d (a unit vector), that is, the direction along which gravitational forces will act.
Magnitude can be changed independently with setMagnitude().
[in,out]  state  The State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity. 
[in]  down  A unit vector giving the "down" direction along which gravity will act. 

inline 
Convenience overload that takes the down direction as a Vec3 and normalizes it (throwing away the magnitude) to create the required unit vector.
It is an error if the supplied Vec3 has zero length.
Set the gravity magnitude g (a nonnegative scalar) in this state, overriding the default gravity magnitude that is stored in this Gravity force element.
[in,out]  state  The State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity. 
[in]  g  The magnitude of the uniform gravitational field. 
Set the potential energy zero height hz (a scalar) in this state, overriding the default zero height that is stored in this Gravity force element.
[in,out]  state  The State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity. 
[in]  hz  The height at which potential energy is considered to be zero. 
bool SimTK::Force::Gravity::getBodyIsExcluded  (  const State &  state, 
MobilizedBodyIndex  mobod  
)  const 
Return the current setting of the "is excluded" flag for a given body in a given State.
This is not necessarily the same as the default value for this body's exclusion status.
[in]  state  The state containing the "is excluded" flag to be obtained. 
[in]  mobod  A MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to obtain. 
true
for Ground. Get the gravity vector v that will be used for computations done with this state.
This is calculated as v=g*d from the current values of the magnitude g and direction d Instance variables in the state.
[in]  state  The state containing the gravity runtime variables used to calculate the gravity vector. 
Get the gravity "down" direction d (a unit vector) that is currently set in this state.
[in]  state  The state containing the gravity direction runtime variable whose value is returned. 
Get the gravity magnitude g (a nonnegative scalar) that is currently set in this state.
[in]  state  The state containing the gravity magnitude runtime variable whose value is returned. 
Get the zero height hz that is currently set in this state for use in calculating gravitational potential energy.
See the class documentation for information about hz is used.
[in]  state  The state containing the zero height runtime variable whose value is returned. 
Obtain the gravitational potential energy contained in this Gravity force element in the given configuration.
Note that gravitational potential energy is m*g*h for each body where the height h is measured from an arbitrary zero height. By default the zero height is defined to be height of the Ground origin but that can be changed arbitrarily.
[in]  state  The State from whose cache the potential energy is retrieved. 
const Vector_<SpatialVec>& SimTK::Force::Gravity::getBodyForces  (  const State &  state  )  const 
Obtain a reference to the set of gravitational forces currently being applied by this Gravity force element, as a Vector of spatial forces indexed by MobilizedBodyIndex.
The force on Ground or on any explicitly excluded body is zero, but there is an entry for every mobilized body (starting with Ground) in the returned result. The return vector of spatial vectors is in a form suitable for direct use with the SimbodyMatterSubsystem Jacobian operators, which can be used to transform these into the equivalent generalized forces. This can be useful for gravity compensation.
[in]  state  The State from whose cache the force is retrieved. 
Forces are returned as though applied at the body origin, which is not necessarily the same place as the body center of mass. That means that in general there will be both a moment and a force returned for each body.
If gravity forces have not yet been calculated for the configuration given in state, the computation will be initiated here and cached for use later.

inline 
Convenience method to extract the gravitational force on just one body; see getBodyForces() to get the whole set at once, and for more information.
[in]  state  The State from whose cache the force is retrieved. 
[in]  mobod  The MobilizedBody or MobilizedBodyIndex whose force is wanted. 
long long SimTK::Force::Gravity::getNumEvaluations  (  )  const 
Return a count of the number of times the set of gravitational forces or potential energy was calculated since this force element was constructed.
Note that this is not a perbody count. This count is only incremented when an actual computation is performed, not when forces are requested but are already valid. Also, we don't consider it a computation if the gravity magnitude is zero. This is intended for use in testing that caching and invalidation is being done properly.
bool SimTK::Force::Gravity::isForceCacheValid  (  const State &  state  )  const 
Return true if the gravitational forces for this configuration have already been calculated and are up to date.
That means they can be retrieved with no further evaluation.
void SimTK::Force::Gravity::invalidateForceCache  (  const State &  state  )  const 
Invalidate the stored gravitational forces if they have already been calculated at this configuration.
That will force a new evaluation the next time they are requested (unless the gravity magnitude is currently zero).