Simbody
3.7
|
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 (Topology-stage) 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 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:
| |
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 non-virtual. 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 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.
[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 zero-length 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 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.
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).