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

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

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]	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=gd 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.

◆ 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]	gravity	The default gravity vector v, interpreted as v=gd 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]

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

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

See also: SimTK::System::setUpDirection()

◆ Gravity() [4/4]

SimTK::Force::Gravity::Gravity ( )

inline

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

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

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

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] mobod This 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]	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.

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

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

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

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

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] state The 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] state The 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] state The 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] state The 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:

Force_Gravity.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Gravity() [1/4]

◆ Gravity() [2/4]

◆ Gravity() [3/4]

◆ Gravity() [4/4]

Member Function Documentation

◆ setDefaultBodyIsExcluded()

◆ setDefaultGravityVector()

◆ setDefaultDownDirection() [1/2]

◆ setDefaultDownDirection() [2/2]

◆ setDefaultMagnitude()

◆ setDefaultZeroHeight()

◆ getDefaultBodyIsExcluded()

◆ getDefaultGravityVector()

◆ getDefaultDownDirection()

◆ getDefaultMagnitude()

◆ getDefaultZeroHeight()

◆ setBodyIsExcluded()

◆ setGravityVector()

◆ setDownDirection() [1/2]

◆ setDownDirection() [2/2]

◆ setMagnitude()

◆ setZeroHeight()

◆ getBodyIsExcluded()

◆ getGravityVector()

◆ getDownDirection()

◆ getMagnitude()

◆ getZeroHeight()

◆ getPotentialEnergy()

◆ getBodyForces()

◆ getBodyForce()

◆ getNumEvaluations()

◆ isForceCacheValid()

◆ invalidateForceCache()