Simbody  3.7
SimTK::Force::Gravity Class Reference

This force element represents a uniform gravitational field applied to a set of bodies. More...

+ Inheritance diagram for SimTK::Force::Gravity:

Public Member Functions

Construction

Methods in this section refer both to constructors, and to methods that can be used to set or change construction (Topology-stage) parameters; these specify the values assigned by default to the corresponding state variables.

Note:

  • Changing one of these default parameters invalidates the containing System's topology, meaning that realizeTopology() will have to be called and a new State obtained before subsequent use.
  • The set...() methods return a reference to "this" Gravity element (in the manner of an assignment operator) so they can be chained in a single expression.
 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...
 
GravitysetDefaultBodyIsExcluded (MobilizedBodyIndex mobod, bool isExcluded)
 Set how the indicated body is to be treated by default. More...
 
GravitysetDefaultGravityVector (const Vec3 &gravity)
 Set the default value for the gravity vector, that is, the direction and magnitude with which gravity will act. More...
 
GravitysetDefaultDownDirection (const UnitVec3 &down)
 Set the default "down" direction d, that is, the direction along which gravity will act. More...
 
GravitysetDefaultDownDirection (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...
 
GravitysetDefaultMagnitude (Real g)
 Set the default magnitude of gravity (a nonegative scalar). More...
 
GravitysetDefaultZeroHeight (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 UnitVec3getDefaultDownDirection () 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 Dynamics-stage 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:

  • Changing one of these parameters invalidates the given State's Stage::Dynamics, meaning that the State's stage will be no higher than Stage::Velocity after the parameter change. That ensures that forces will be recalcuated before they are used (forces are calculated when Stage::Dynamics is realized).
  • The set...() methods here return a const reference to "this" Gravity force element (in the manner of an assignment operator, except read-only) so they can be chained in a single expression.
const GravitysetBodyIsExcluded (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 GravitysetGravityVector (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 GravitysetDownDirection (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 GravitysetDownDirection (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 GravitysetMagnitude (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 GravitysetZeroHeight (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 UnitVec3getDownDirection (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 SpatialVecgetBodyForce (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 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 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.

Force
Each body B that has not been explicitly excluded will experience a force fb = mb*g*d, applied to its center of mass, where mb is the mass of body B. Although this is a pure force, note that when it is measured in the body frame B there will also be a moment unless the body frame origin Bo is located at the body's mass center. You can obtain the applied forces if you need them, for example for gravity compensation; see getBodyForces().
Potential Energy
Gravitational potential energy for a body B is mb*g*hb where hb is the height of body B's mass center over an arbitrary "zero" height hz (default is hz=0), measured along the "up" direction -d. If pb is the Ground frame vector giving the position of body B's mass center, its height over or under hz is hb=pb*(-d) - hz. Note that this is a signed quantity so the potential energy is also signed.
Author
Michael Sherman

Constructor & Destructor Documentation

◆ Gravity() [1/4]

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

Parameters
[in,out]forces
The subsystem to which this force should be added.
[in]matter
The subsystem containing the bodies that will be affected.
[in]downThe 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]gThe 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]zeroHeightThis 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.

◆ Gravity() [2/4]

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

Parameters
[in,out]forces
The subsystem to which this force should be added.
[in]matter
The subsystem containing the bodies that will be affected.
[in]gravityThe 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.

See also
SimTK::System::setUpDirection()

◆ Gravity() [3/4]

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

Parameters
[in,out]forces
The subsystem to which this force should be added.
[in]matter
The subsystem containing the bodies that will be affected.
[in]gThe 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.

See also
SimTK::System::setUpDirection()

◆ Gravity() [4/4]

Default constructor creates an empty handle.

Member Function Documentation

◆ setDefaultBodyIsExcluded()

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 on-the-fly changes you should call setBodyIsExcluded() instead. Ground is always excluded; you can call this method on Ground but the call will be ignored.

Parameters
[in]mobodThis is a MobilizedBody or MobilizedBodyIndex for the body whose default exclusion status you want to change.
[in]isExcludedSet to true if the default should be that this body is not to be affected by this Gravity force element.
Returns
A writable reference to "this" Gravity element which will now have the indicated body excluded.
See also
setBodyIsExcluded()

◆ setDefaultGravityVector()

Gravity& SimTK::Force::Gravity::setDefaultGravityVector ( const Vec3 gravity)

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.

Parameters
[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.
Returns
A writable reference to "this" Gravity element which will now have the new default magnitude and direction.

◆ setDefaultDownDirection() [1/2]

Gravity& SimTK::Force::Gravity::setDefaultDownDirection ( const UnitVec3 down)

Set the default "down" direction d, that is, the direction along which gravity will act.

Parameters
[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 zero-length Vec3, however.
Returns
A writable reference to "this" Gravity element which will now have the new default direction.

◆ setDefaultDownDirection() [2/2]

Gravity& SimTK::Force::Gravity::setDefaultDownDirection ( const Vec3 down)
inline

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.

◆ setDefaultMagnitude()

Gravity& SimTK::Force::Gravity::setDefaultMagnitude ( Real  g)

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.

Parameters
[in]gThe 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.
Returns
A writable reference to "this" Gravity element which will now have the new default strength.

◆ setDefaultZeroHeight()

Gravity& SimTK::Force::Gravity::setDefaultZeroHeight ( Real  zeroHeight)

Set the default zero height (a signed scalar), for use in potential energy calculation.

See the Gravity class comments for how this is used.

Parameters
[in]zeroHeightThe 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.
Returns
A writable reference to "this" Gravity element which will now have the new default zeroHeight.

◆ getDefaultBodyIsExcluded()

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

Parameters
[in]mobodThis is a MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to obtain.
Returns
The current value of the "is excluded by default" flag for this body; this will always be true for Ground.
See also
getBodyIsExcluded()

◆ getDefaultGravityVector()

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.

◆ getDefaultDownDirection()

const UnitVec3& SimTK::Force::Gravity::getDefaultDownDirection ( ) const

Return the default down direction (a unit vector) for this Gravity force element.

◆ getDefaultMagnitude()

Real SimTK::Force::Gravity::getDefaultMagnitude ( ) const

Return the default gravity magnitude g (a nonnegative scalar).

◆ getDefaultZeroHeight()

Real SimTK::Force::Gravity::getDefaultZeroHeight ( ) const

Return the default zero height used in the calculation of graviational potential energy.

◆ setBodyIsExcluded()

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.

Parameters
[in,out]stateThe State object that is modified by this method; Stage::Dynamics will be invalidated leaving the current stage no higher than Stage::Velocity.
[in]mobodThis is a MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to change.
[in]isExcludedSet to true if this body should not be affected by this force element.
Returns
A const reference to "this" Gravity force element for convenient chaining of set...() methods in a single expression.
Precondition
state must already be realized to Stage::Topology.
Postcondition
Stage::Dynamics is invalidated in state if anything was changed.
See also
setDefaultBodyIsExcluded(), getBodyIsExcluded()

◆ setGravityVector()

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.

Parameters
[in,out]stateThe 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.
Returns
A const reference to "this" Gravity element for convenient chaining of set...() methods in a single expression.
Precondition
state must already be realized to Stage::Topology.
Postcondition
Stage::Dynamics is invalidated in state if anything was changed.
See also
setDownDirection(), setMagnitude()

◆ setDownDirection() [1/2]

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

Parameters
[in,out]stateThe 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.
Returns
A const reference to "this" Gravity element for convenient chaining of set...() methods in a single expression.
Precondition
state must already be realized to Stage::Topology.
Postcondition
Stage::Dynamics is invalidated in state if anything was changed.
See also
setMagnitude()

◆ setDownDirection() [2/2]

const Gravity& SimTK::Force::Gravity::setDownDirection ( State state,
const Vec3 down 
) const
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.

◆ setMagnitude()

const Gravity& SimTK::Force::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.

Parameters
[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.
Returns
A const reference to "this" Gravity element for convenient chaining of set...() methods in a single expression.
Precondition
state must already be realized to Stage::Topology.
Postcondition
Stage::Dynamics is invalidated in state if anything was changed.
See also
setDownDirection()

◆ setZeroHeight()

const Gravity& SimTK::Force::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.

Parameters
[in,out]stateThe 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.
Returns
A const reference to "this" Gravity element for convenient chaining of set...() methods in a single expression.
Precondition
state must already be realized to Stage::Topology.
Postcondition
Stage::Dynamics is invalidated in state if anything was changed.

◆ getBodyIsExcluded()

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.

Parameters
[in]stateThe state containing the "is excluded" flag to be obtained.
[in]mobodA MobilizedBody or MobilizedBodyIndex for the body whose exclusion status you want to obtain.
Returns
The current value of the "is excluded" flag for this body in this state; this will always be true for Ground.
Precondition
state must already be realized to Stage::Topology.
See also
getDefaultBodyIsExcluded(), setBodyIsExcluded()

◆ getGravityVector()

Vec3 SimTK::Force::Gravity::getGravityVector ( const State state) const

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.

Parameters
[in]stateThe state containing the gravity runtime variables used to calculate the gravity vector.
Returns
The current value of the gravity vector.
Precondition
state must have been realized to Topology stage.

◆ getDownDirection()

const UnitVec3& SimTK::Force::Gravity::getDownDirection ( const State state) const

Get the gravity "down" direction d (a unit vector) that is currently set in this state.

Parameters
[in]stateThe state containing the gravity direction runtime variable whose value is returned.
Returns
The current value of the gravity direction variable.
Precondition
state must have been realized to Topology stage.

◆ getMagnitude()

Real SimTK::Force::Gravity::getMagnitude ( const State state) const

Get the gravity magnitude g (a nonnegative scalar) that is currently set in this state.

Parameters
[in]stateThe state containing the gravity magnitude runtime variable whose value is returned.
Returns
The current value of the gravity magnitude variable.
Precondition
state must have been realized to Topology stage.

◆ getZeroHeight()

Real SimTK::Force::Gravity::getZeroHeight ( const State state) const

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.

Parameters
[in]stateThe state containing the zero height runtime variable whose value is returned.
Returns
The current value of the zero height variable.
Precondition
state must have been realized to Topology stage.

◆ getPotentialEnergy()

Real SimTK::Force::Gravity::getPotentialEnergy ( const State state) const

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.

Parameters
[in]state
The State from whose cache the potential energy is retrieved.
Returns
The gravitational potential energy of this Gravity force element in the configuration contained in state (a signed scalar).
Precondition
state must be realized to Stage::Position

◆ getBodyForces()

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.

Parameters
[in]state
The State from whose cache the force is retrieved.
Returns
A reference to the vector of spatial forces (meaning the gravitational moment about and force at the body origin, not necessarily the center of mass) currently being applied to each of the mobilized bodies, expressed in the Ground frame.
Precondition
state must be realized to Stage::Position

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.

◆ getBodyForce()

const SpatialVec& SimTK::Force::Gravity::getBodyForce ( const State state,
MobilizedBodyIndex  mobod 
) const
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.

Parameters
[in]state
The State from whose cache the force is retrieved.
[in]mobod
The MobilizedBody or MobilizedBodyIndex whose force is wanted.
Returns
The spatial force (meaning the gravitational force and moment about the body origin, not necessarily the center of mass) currently being applied to the given mobilized body, expressed in the Ground frame.
Precondition
state must be realized to Stage::Position

◆ getNumEvaluations()

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

◆ isForceCacheValid()

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.

◆ invalidateForceCache()

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


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