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

#include <Force_Gravity.h>

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 contruction (Topology-stage) parameters; these specify the values assigned by default to the corresponding Instance-stage state variables. Note: Changing one of these default parameters invalidates the containing System's topology, meaning that realizeTopology() will have to be called 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 Vec3 &gravity)
	Create a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, by specifying only a gravity vector, that is, the product of the gravity magnitude and the "down" direction vector.
	Gravity (GeneralForceSubsystem &forces, const SimbodyMatterSubsystem &matter, const UnitVec3 &down, Real g, Real zeroHeight=0)
	Create a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, providing gravity magnitude and direction separately.
Gravity &	setDefaultGravityVector (const Vec3 &gravity)
	Set the default value for the gravity vector, that is, the direction and magnitude with which gravity will act (must not be zero).
Gravity &	setDefaultDownDirection (const UnitVec3 &down)
	Set the default "down" direction d, that is, the direction along which gravity will act.
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.
Gravity &	setDefaultMagnitude (Real g)
	Set the default magnitude of gravity (a nonegative scalar).
Gravity &	setDefaultZeroHeight (Real zeroHeight)
	Set the default zero height (a signed scalar), for use in potential energy calculation.
Vec3	getDefaultGravityVector () const
	Return the default gravity vector being used for this Gravity force element, calculated from the default magnitude and direction.
const UnitVec3 &	getDefaultDownDirection () const
	Return the default down direction (a unit vector) for this Gravity force element.
Real	getDefaultMagnitude () const
	Return the default gravity magnitude g (a nonnegative scalar).
Real	getDefaultZeroHeight () const
	Return the default zero height used in the calculation of graviational potential energy.
Instance Parameters
These refer to the Instance-stage state variables that determine the actual values to be used to calculate gravitational forces and energy from a given State object. If these are not set explicitly, the default values are set to those provided in the constructor or via the correponding setDefault...() methods. Note: Changing one of these parameters invalidates the given State's Instance stage, meaning that realize(Instance) will have to be called (explicitly or implicitly by realizing a higher stage) before subsequent use. 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 &	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.
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.
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.
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.
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.
Vec3	getGravityVector (const State &state) const
	Get the gravity vector v that will be used for computations done with this state.
const UnitVec3 &	getDownDirection (const State &state) const
	Get the gravity "down" direction d (a unit vector) that is currently set in this state.
Real	getMagnitude (const State &state) const
	Get the gravity magnitude g (a nonnegative scalar) that is currently set in this state.
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.
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 instance-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.
const SpatialVec &	getBodyForce (const State &state, MobilizedBodyIndex mobod) const
	Obtain the gravitational force currently being applied by this Gravity force element to the given mobilized body.

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]. Gravity affects all the bodies and particles in the given SimbodyMatterSubsystem (except for Ground).

Force: Each body b experiences 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 there will also be a moment unless the body frame is located at the body's mass center.

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.

Constructor & Destructor Documentation

SimTK::Force::Gravity::Gravity	(	GeneralForceSubsystem &	forces,
		const SimbodyMatterSubsystem &	matter,
		const Vec3 &	gravity
	)

Create a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, by specifying only a gravity vector, that is, the product of the gravity magnitude and the "down" direction vector.

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. This value is used to calculate g and d separately so must not be zero length. If you want to create a Gravity force element with default magnitude zero, use the other constructor which allows magnitude and direction to be provided separately.

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,
		const UnitVec3 &	down,
		Real	g,
		Real	zeroHeight = `0`
	)

Create a Gravity force element within a particular force subsystem and affecting all the bodies of a particular matter subsystem, providing gravity magnitude and direction separately.

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. This is a unit vector; if you provide an ordinary Vec3 it will be normalized before use and its magnitude ignored. Gravity will be directed along this direction unless explicitly changed within a particular State via the setDirection() or setGravityVector() methods.
[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 direction* argument to this constructor. Gravity will have the magnitude given here unless explicitly changed within a particular State.
[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.

Member Function Documentation

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 (must not be zero).

From the given vector we extract separately the magnitude g and "down" direction d (a unit vector) so the supplied vector cannot be zero. If you want the default magnitude to be zero, use setDefaultMagnitude() and setDefaultDownDirection() methods to provide them separately instead of combining them as is required by this method.

Parameters:

[in] gravity A vector giving the magnitude and direction with which gravity will act on the bodies. Must not be zero.

Returns:: A writable reference to "this" Gravity element which will now have the new default magnitude and direction.

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.

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.

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.

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.

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

This is used to calculate the magnitude and direction separately, so must not be zero.

Parameters:

[in,out]	state	The State object that is modified by this method.
[in]	gravity	The gravity vector including both the magnitude and direction. Must not 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.

See also:: setDownDirection(), setMagnitude()

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

See also:: setMagnitude()

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.

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

See also:: setDownDirection()

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

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 Instance variables used to calculate the gravity vector.

Returns:: The current value of the gravity vector.

Precondition:: state must have been realized to Topology stage.

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 Instance variable whose value is returned.

Returns:: The current value of the gravity direction Instance variable.

Precondition:: state must have been realized to Topology stage.

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 Instance variable whose value is returned.

Returns:: The current value of the gravity magnitude Instance variable.

Precondition:: state must have been realized to Topology stage.

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 Instance variable whose value is returned.

Returns:: The current value of the zero height Instance variable.

Precondition:: state must have been realized to Topology stage.

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

Precondition:: state must be realized to Stage::Position

const SpatialVec& SimTK::Force::Gravity::getBodyForce	(	const State &	state,
		MobilizedBodyIndex	mobod
	)		const

Obtain the gravitational force currently being applied by this Gravity force element to the given mobilized body.

Parameters:

[in]	state	The State from whose cache the force is retrieved.
[in]	mobod	The index of the mobilized body whose force is wanted.

Returns:: The spatial force (meaning the gravitational force and moment about the body origin) currently being applied to the given mobilized body, expressed in the Ground frame.

Precondition:: state must be realized to Stage::Position

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

Force_Gravity.h

SimTK::Force::Gravity Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation