Drake
UniformGravityFieldElement< T > Class Template Reference

This ForceElement allows modeling the effect of a uniform gravity field as felt by bodies on the surface of the Earth. More...

#include <drake/multibody/tree/uniform_gravity_field_element.h>

## Public Member Functions

UniformGravityFieldElement ()
Constructs a uniform gravity field element with a default strength (on the earth's surface) and direction (-z). More...

UniformGravityFieldElement (Vector3< double > g_W)
Constructs a uniform gravity field element with a strength given by the acceleration of gravity vector g_W, expressed in the world frame W. More...

const Vector3< double > & gravity_vector () const
Returns the acceleration of gravity vector, expressed in the world frame W. More...

VectorX< T > CalcGravityGeneralizedForces (const systems::Context< T > &context) const
Computes the generalized forces tau_g(q) due to this gravity field element as a function of the generalized positions q stored in the input context, for the multibody model to which this element belongs. More...

CalcPotentialEnergy (const internal::MultibodyTreeContext< T > &context, const internal::PositionKinematicsCache< T > &pc) const final
Computes the total potential energy of all bodies in the model in this uniform gravity field. More...

CalcConservativePower (const internal::MultibodyTreeContext< T > &context, const internal::PositionKinematicsCache< T > &pc, const internal::VelocityKinematicsCache< T > &vc) const final
(Advanced) Calculates and returns the power generated by conservative force elements or zero if this force element is non-conservative. More...

CalcNonConservativePower (const internal::MultibodyTreeContext< T > &context, const internal::PositionKinematicsCache< T > &pc, const internal::VelocityKinematicsCache< T > &vc) const final
(Advanced) Calculates the rate at which mechanical energy is being generated (positive) or dissipated (negative) other than by conversion between potential and kinetic energy. More...

Does not allow copy, move, or assignment
UniformGravityFieldElement (const UniformGravityFieldElement &)=delete

UniformGravityFieldElementoperator= (const UniformGravityFieldElement &)=delete

UniformGravityFieldElement (UniformGravityFieldElement &&)=delete

UniformGravityFieldElementoperator= (UniformGravityFieldElement &&)=delete

Public Member Functions inherited from ForceElement< T >
ForceElement (ModelInstanceIndex model_instance)
Default constructor for a generic force element. More...

void CalcAndAddForceContribution (const internal::MultibodyTreeContext< T > &context, const internal::PositionKinematicsCache< T > &pc, const internal::VelocityKinematicsCache< T > &vc, MultibodyForces< T > *forces) const
(Advanced) Computes the force contribution for this force element and adds it to the output arrays of forces. More...

ForceElement (const ForceElement &)=delete

ForceElementoperator= (const ForceElement &)=delete

ForceElement (ForceElement &&)=delete

ForceElementoperator= (ForceElement &&)=delete

## Static Public Attributes

static constexpr double kDefaultStrength = 9.81
The strength used by our class's default constructor (i.e., on the earth's surface). More...

## Protected Member Functions

void DoCalcAndAddForceContribution (const internal::MultibodyTreeContext< T > &context, const internal::PositionKinematicsCache< T > &pc, const internal::VelocityKinematicsCache< T > &vc, MultibodyForces< T > *forces) const final
This method is called only from the public non-virtual CalcAndAddForceContributions() which will already have error-checked the parameters so you don't have to. More...

std::unique_ptr< ForceElement< double > > DoCloneToScalar (const internal::MultibodyTree< double > &tree_clone) const override
Clones this ForceElement (templated on T) to a mobilizer templated on double. More...

std::unique_ptr< ForceElement< AutoDiffXd > > DoCloneToScalar (const internal::MultibodyTree< AutoDiffXd > &tree_clone) const override
Clones this ForceElement (templated on T) to a mobilizer templated on AutoDiffXd. More...

Methods to make a clone templated on different scalar types.

Specific force element subclasses must implement these to support scalar conversion to other types.

These methods are only called from MultibodyTree::CloneToScalar(); users must not call these explicitly since there is no external mechanism to ensure the argument tree_clone is in a valid stage of cloning. In contrast, MultibodyTree::CloneToScalar() guarantees that by when ForceElement::CloneToScalar() is called, all Body, Frame and Mobilizer objects in the original tree (templated on T) to which this ForceElement<T> belongs, have a corresponding clone in the cloned tree (argument tree_clone for these methods). Therefore, implementations of ForceElement::DoCloneToScalar() can retrieve clones from tree_clone as needed. Consider the following example for a SpringElement<T> used to model an elastic spring between two bodies:

template <typename T>
class SpringElement {
public:
// Class's constructor.
SpringElement(
const Body<T>& body1, const Body<T>& body2, double stiffness);
// Get the first body to which this spring is connected.
const Body<T>& get_body1() const;
// Get the second body to which this spring is connected.
const Body<T>& get_body2() const;
// Get the spring stiffness constant.
double get_stiffness() const;
protected:
// Implementation of the scalar conversion from T to double.
std::unique_ptr<ForceElement<double>> DoCloneToScalar(
const MultibodyTree<double>& tree_clone) const) {
const Body<ToScalar>& body1_clone =
tree_clone.get_variant(get_body1());
const Body<ToScalar>& body2_clone =
tree_clone.get_variant(get_body2());
return std::make_unique<SpringElement<double>>(
body1_clone, body2_clone, get_stiffness());
}

MultibodyTree::get_variant() methods are available to retrieve cloned variants from tree_clone, and are overloaded on different element types.

For examples on how a MultibodyTree model can be converted to other scalar types, please refer to the documentation for MultibodyTree::CloneToScalar().

## Detailed Description

### template<typename T> class drake::multibody::UniformGravityFieldElement< T >

This ForceElement allows modeling the effect of a uniform gravity field as felt by bodies on the surface of the Earth.

This gravity field acts on all bodies in the MultibodyTree model.

Template Parameters
 T The scalar type. Must be a valid Eigen scalar.

Instantiated templates for the following kinds of T's are provided:

• double
• AutoDiffXd

They are already available to link against in the containing library. No other values for T are currently supported.

## ◆ UniformGravityFieldElement() [1/4]

 UniformGravityFieldElement ( const UniformGravityFieldElement< T > & )
delete

## ◆ UniformGravityFieldElement() [2/4]

 UniformGravityFieldElement ( UniformGravityFieldElement< T > && )
delete

## ◆ UniformGravityFieldElement() [3/4]

 UniformGravityFieldElement ( )

Constructs a uniform gravity field element with a default strength (on the earth's surface) and direction (-z).

## ◆ UniformGravityFieldElement() [4/4]

 UniformGravityFieldElement ( Vector3< double > g_W )
explicit

Constructs a uniform gravity field element with a strength given by the acceleration of gravity vector g_W, expressed in the world frame W.

## ◆ CalcConservativePower()

 T CalcConservativePower ( const internal::MultibodyTreeContext< T > & context, const internal::PositionKinematicsCache< T > & pc, const internal::VelocityKinematicsCache< T > & vc ) const
finalvirtual

(Advanced) Calculates and returns the power generated by conservative force elements or zero if this force element is non-conservative.

This quantity is defined to be positive when the potential energy is decreasing. In other words, if PE is the potential energy as defined by CalcPotentialEnergy(), then the conservative power, Pc, is Pc = -d(PE)/dt.

CalcPotentialEnergy(), CalcNonConservativePower()

Implements ForceElement< T >.

## ◆ CalcGravityGeneralizedForces()

 VectorX< T > CalcGravityGeneralizedForces ( const systems::Context< T > & context ) const

Computes the generalized forces tau_g(q) due to this gravity field element as a function of the generalized positions q stored in the input context, for the multibody model to which this element belongs.

tau_g(q) is defined such that it appears on the right hand side of the equations of motion together with any other generalized forces, like so:

  Mv̇ + C(q, v)v = tau_g(q) + tau_app


where tau_app includes any other generalized forces applied on the system.

Parameters
 [in] context The context storing the state of the multibody model to which this element belongs.
Returns
tau_g A vector containing the generalized forces due to this gravity field force element. The generalized forces are consistent with the vector of generalized velocities v for the parent MultibodyTree model so that the inner product v⋅tau_g corresponds to the power applied by the gravity forces on the mechanical system. That is, v⋅tau_g > 0 corresponds to potential energy going into the system, as either mechanical kinetic energy, some other potential energy, or heat, and therefore to a decrease of potential energy.

## ◆ CalcNonConservativePower()

 T CalcNonConservativePower ( const internal::MultibodyTreeContext< T > & context, const internal::PositionKinematicsCache< T > & pc, const internal::VelocityKinematicsCache< T > & vc ) const
finalvirtual

(Advanced) Calculates the rate at which mechanical energy is being generated (positive) or dissipated (negative) other than by conversion between potential and kinetic energy.

Integrating this quantity yields work W, and the total energy E = PE + KE - W should be conserved by any physically-correct model, to within integration accuracy of W.

CalcConservativePower()

Implements ForceElement< T >.

## ◆ CalcPotentialEnergy()

 T CalcPotentialEnergy ( const internal::MultibodyTreeContext< T > & context, const internal::PositionKinematicsCache< T > & pc ) const
finalvirtual

Computes the total potential energy of all bodies in the model in this uniform gravity field.

The definition of potential energy allows to arbitrarily choose the zero energy height. This element takes the zero energy height to be the same as the world's height. That is, a body will have zero potential energy when its the height of its center of mass is at the world's origin.

Implements ForceElement< T >.

 void DoCalcAndAddForceContribution ( const internal::MultibodyTreeContext< T > & context, const internal::PositionKinematicsCache< T > & pc, const internal::VelocityKinematicsCache< T > & vc, MultibodyForces< T > * forces ) const
finalprotectedvirtual

This method is called only from the public non-virtual CalcAndAddForceContributions() which will already have error-checked the parameters so you don't have to.

Refer to the documentation for CalcAndAddForceContribution() for details describing the purpose and parameters of this method. It assumes forces to be a valid pointer to a MultibodyForces object compatible with the MultibodyTree model owning this force element.

Precondition
The position kinematics pc must have been previously updated with a call to CalcPositionKinematicsCache().
The velocity kinematics vc must have been previously updated with a call to CalcVelocityKinematicsCache().

Implements ForceElement< T >.

## ◆ DoCloneToScalar() [1/2]

 std::unique_ptr< ForceElement< double > > DoCloneToScalar ( const internal::MultibodyTree< double > & tree_clone ) const
overrideprotectedvirtual

Clones this ForceElement (templated on T) to a mobilizer templated on double.

Implements ForceElement< T >.

## ◆ DoCloneToScalar() [2/2]

 std::unique_ptr< ForceElement< AutoDiffXd > > DoCloneToScalar ( const internal::MultibodyTree< AutoDiffXd > & tree_clone ) const
overrideprotectedvirtual

Clones this ForceElement (templated on T) to a mobilizer templated on AutoDiffXd.

Implements ForceElement< T >.

## ◆ gravity_vector()

 const Vector3& gravity_vector ( ) const
inline

Returns the acceleration of gravity vector, expressed in the world frame W.

## ◆ operator=() [1/2]

 UniformGravityFieldElement& operator= ( const UniformGravityFieldElement< T > & )
delete

## ◆ operator=() [2/2]

 UniformGravityFieldElement& operator= ( UniformGravityFieldElement< T > && )
delete

## ◆ kDefaultStrength

 constexpr double kDefaultStrength = 9.81
static

The strength used by our class's default constructor (i.e., on the earth's surface).

This is an unsigned (positive) value in m/s².

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