Drake
MultibodyTree< T > Class Template Reference

MultibodyTree provides a representation for a physical system consisting of a collection of interconnected rigid and deformable bodies. More...

#include <drake/multibody/multibody_tree/body.h>

Public Member Functions

 MultibodyTree ()
 Creates a MultibodyTree containing only a world body. More...
 
int get_num_frames () const
 Returns the number of Frame objects in the MultibodyTree. More...
 
int get_num_bodies () const
 Returns the number of bodies in the MultibodyTree including the world body. More...
 
int get_num_mobilizers () const
 Returns the number of mobilizers in the MultibodyTree. More...
 
int get_tree_height () const
 Returns the height of the tree data structure of this MultibodyTree. More...
 
const Body< T > & get_world_body () const
 Returns a constant reference to the world body. More...
 
const BodyFrame< T > & get_world_frame () const
 Returns a constant reference to the world frame. More...
 
const Body< T > & get_body (BodyIndex body_index) const
 Returns a constant reference to the body with unique index body_index. More...
 
bool topology_is_valid () const
 Returns true if this MultibodyTree was finalized with Finalize() after all multibody elements were added, and false otherwise. More...
 
const MultibodyTreeTopologyget_topology () const
 Returns the topology information for this multibody tree. More...
 
void Finalize ()
 This method must be called after all elements in the tree (joints, bodies, force elements, constraints) were added and before any computations are performed. More...
 
std::unique_ptr< systems::Context< T > > CreateDefaultContext () const
 Allocates a new context for this MultibodyTree uniquely identifying the state of the multibody system. More...
 
void SetDefaults (systems::Context< T > *context) const
 Sets default values in the context. More...
 
void CalcPositionKinematicsCache (const systems::Context< T > &context, PositionKinematicsCache< T > *pc) const
 Computes into the position kinematics pc all the kinematic quantities that depend on the generalized positions only. More...
 
Does not allow copy, move, or assignment
 MultibodyTree (const MultibodyTree &)=delete
 
MultibodyTreeoperator= (const MultibodyTree &)=delete
 
 MultibodyTree (MultibodyTree &&)=delete
 
MultibodyTreeoperator= (MultibodyTree &&)=delete
 
Methods to add new MultibodyTree elements.

To create a MultibodyTree users will add multibody elements like bodies, joints, force elements, constraints, etc, using one of these methods.

Once a user is done adding multibody elements, the Finalize() method must be called before invoking any MultibodyTree method. See Finalize() for details.

template<template< typename Scalar > class BodyType>
const BodyType< T > & AddBody (std::unique_ptr< BodyType< T >> body)
 Takes ownership of body and adds it to this MultibodyTree. More...
 
template<template< typename Scalar > class BodyType, typename... Args>
const BodyType< T > & AddBody (Args &&...args)
 Constructs a new body with type BodyType with the given args, and adds it to this MultibodyTree, which retains ownership. More...
 
template<template< typename Scalar > class FrameType>
const FrameType< T > & AddFrame (std::unique_ptr< FrameType< T >> frame)
 Takes ownership of frame and adds it to this MultibodyTree. More...
 
template<template< typename Scalar > class FrameType, typename... Args>
const FrameType< T > & AddFrame (Args &&...args)
 Constructs a new frame with type FrameType with the given args, and adds it to this MultibodyTree, which retains ownership. More...
 
template<template< typename Scalar > class MobilizerType>
const MobilizerType< T > & AddMobilizer (std::unique_ptr< MobilizerType< T >> mobilizer)
 Takes ownership of mobilizer and adds it to this MultibodyTree. More...
 
template<template< typename Scalar > class MobilizerType, typename... Args>
const MobilizerType< T > & AddMobilizer (Args &&...args)
 Constructs a new mobilizer with type MobilizerType with the given args, and adds it to this MultibodyTree, which retains ownership. More...
 

Detailed Description

template<typename T>
class drake::multibody::MultibodyTree< T >

MultibodyTree provides a representation for a physical system consisting of a collection of interconnected rigid and deformable bodies.

As such, it owns and manages each of the elements that belong to this physical system. Multibody dynamics elements include bodies, joints, force elements and constraints.

Template Parameters
TThe 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.

Constructor & Destructor Documentation

MultibodyTree ( const MultibodyTree< T > &  )
delete
MultibodyTree ( MultibodyTree< T > &&  )
delete

Creates a MultibodyTree containing only a world body.

Member Function Documentation

const BodyType<T>& AddBody ( std::unique_ptr< BodyType< T >>  body)
inline

Takes ownership of body and adds it to this MultibodyTree.

Returns a constant reference to the body just added, which will remain valid for the lifetime of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Code to define spatial_inertia, a SpatialInertia<T> object ...
const RigidBody<T>& body =
model.AddBody(std::make_unique<RigidBody<T>>(spatial_inertia));
Exceptions
std::logic_errorif body is a nullptr.
std::logic_errorif Finalize() was already called on this tree.
Parameters
[in]bodyA unique pointer to a body to add to this MultibodyTree. The body class must be specialized on the same scalar type T as this MultibodyTree.
Returns
A constant reference of type BodyType to the created body. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
BodyTypeThe type of the specific sub-class of Body to add. The template needs to be specialized on the same scalar type T of this MultibodyTree.

Here is the call graph for this function:

Here is the caller graph for this function:

const BodyType<T>& AddBody ( Args &&...  args)
inline

Constructs a new body with type BodyType with the given args, and adds it to this MultibodyTree, which retains ownership.

The BodyType will be specialized on the scalar type T of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Code to define spatial_inertia, a SpatialInertia<T> object ...
// Notice RigidBody is a template on a scalar type.
const RigidBody<T>& body = model.AddBody<RigidBody>(spatial_inertia);

Note that for dependent names you must use the template keyword (say for instance you have a MultibodyTree<T> member within your custom class):

MultibodyTree<T> model;
auto body = model.template AddBody<RigidBody>(Args...);
Exceptions
std::logic_errorif Finalize() was already called on this tree.
Parameters
[in]argsThe arguments needed to construct a valid Body of type BodyType. BodyType must provide a public constructor that takes these arguments.
Returns
A constant reference of type BodyType to the created body. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
BodyTypeA template for the type of Body to construct. The template will be specialized on the scalar type T of this MultibodyTree.

Here is the call graph for this function:

const FrameType<T>& AddFrame ( std::unique_ptr< FrameType< T >>  frame)
inline

Takes ownership of frame and adds it to this MultibodyTree.

Returns a constant reference to the frame just added, which will remain valid for the lifetime of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Define body and X_BF ...
const FixedOffsetFrame<T>& frame =
model.AddFrame(std::make_unique<FixedOffsetFrame<T>>(body, X_BF));
Exceptions
std::logic_errorif frame is a nullptr.
std::logic_errorif Finalize() was already called on this tree.
Parameters
[in]frameA unique pointer to a frame to be added to this MultibodyTree. The frame class must be specialized on the same scalar type T as this MultibodyTree.
Returns
A constant reference of type FrameType to the created frame. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
FrameTypeThe type of the specific sub-class of Frame to add. The template needs to be specialized on the same scalar type T of this MultibodyTree.

Here is the call graph for this function:

Here is the caller graph for this function:

const FrameType<T>& AddFrame ( Args &&...  args)
inline

Constructs a new frame with type FrameType with the given args, and adds it to this MultibodyTree, which retains ownership.

The FrameType will be specialized on the scalar type T of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Define body and X_BF ...
// Notice FixedOffsetFrame is a template an a scalar type.
const FixedOffsetFrame<T>& frame =
model.AddFrame<FixedOffsetFrame>(body, X_BF);

Note that for dependent names you must use the template keyword (say for instance you have a MultibodyTree<T> member within your custom class):

MultibodyTree<T> model;
// ... Define body and X_BF ...
const auto& frame =
model.template AddFrame<FixedOffsetFrame>(body, X_BF);
Exceptions
std::logic_errorif Finalize() was already called on this tree.
Parameters
[in]argsThe arguments needed to construct a valid Frame of type FrameType. FrameType must provide a public constructor that takes these arguments.
Returns
A constant reference of type FrameType to the created frame. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
FrameTypeA template for the type of Frame to construct. The template will be specialized on the scalar type T of this MultibodyTree.

Here is the call graph for this function:

const MobilizerType<T>& AddMobilizer ( std::unique_ptr< MobilizerType< T >>  mobilizer)
inline

Takes ownership of mobilizer and adds it to this MultibodyTree.

Returns a constant reference to the mobilizer just added, which will remain valid for the lifetime of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Code to define inboard and outboard frames by calling
// MultibodyTree::AddFrame() ...
const RevoluteMobilizer<T>& pin =
model.AddMobilizer(std::make_unique<RevoluteMobilizer<T>>(
inboard_frame, elbow_outboard_frame,
Vector3d::UnitZ() /*revolute axis*/));

A Mobilizer effectively connects the two bodies to which the inboard and outboard frames belong.

Exceptions
std::logic_errorif mobilizer is a nullptr.
std::logic_errorif Finalize() was already called on this tree.
astd::runtime_error if the new mobilizer attempts to connect a frame with itself.
std::runtime_errorif attempting to connect two bodies with more than one mobilizer between them.
Parameters
[in]mobilizerA unique pointer to a mobilizer to add to this MultibodyTree. The mobilizer class must be specialized on the same scalar type T as this MultibodyTree. Notice this is a requirement of this method's signature and therefore an input mobilzer specialized on a different scalar type than that of this MultibodyTree's T will fail to compile.
Returns
A constant reference of type MobilizerType to the created mobilizer. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
MobilizerTypeThe type of the specific sub-class of Mobilizer to add. The template needs to be specialized on the same scalar type T of this MultibodyTree.

Here is the call graph for this function:

Here is the caller graph for this function:

const MobilizerType<T>& AddMobilizer ( Args &&...  args)
inline

Constructs a new mobilizer with type MobilizerType with the given args, and adds it to this MultibodyTree, which retains ownership.

The MobilizerType will be specialized on the scalar type T of this MultibodyTree.

Example of usage:

MultibodyTree<T> model;
// ... Code to define inboard and outboard frames by calling
// MultibodyTree::AddFrame() ...
// Notice RevoluteMobilizer is a template an a scalar type.
const RevoluteMobilizer<T>& pin =
model.template AddMobilizer<RevoluteMobilizer>(
inboard_frame, outboard_frame,
Vector3d::UnitZ() /*revolute axis*/);

Note that for dependent names only you must use the template keyword (say for instance you have a MultibodyTree<T> member within your custom class).

Exceptions
std::logic_errorif Finalize() was already called on this tree.
astd::runtime_error if the new mobilizer attempts to connect a frame with itself.
std::runtime_errorif attempting to connect two bodies with more than one mobilizer between them.
Parameters
[in]argsThe arguments needed to construct a valid Mobilizer of type MobilizerType. MobilizerType must provide a public constructor that takes these arguments.
Returns
A constant reference of type MobilizerType to the created mobilizer. This reference which will remain valid for the lifetime of this MultibodyTree.
Template Parameters
MobilizerTypeA template for the type of Mobilizer to construct. The template will be specialized on the scalar type T of this MultibodyTree.

Here is the call graph for this function:

void CalcPositionKinematicsCache ( const systems::Context< T > &  context,
PositionKinematicsCache< T > *  pc 
) const

Computes into the position kinematics pc all the kinematic quantities that depend on the generalized positions only.

These include:

  • For each body B, the pose X_BF of each of the frames F attached to body B.
  • Pose X_WB of each body B in the model as measured and expressed in the world frame W.
  • Across-mobilizer Jacobian matrices H_FM and H_PB_W.
  • Body specific quantities such as com_W and M_Bo_W.
Exceptions
std::bad_castif context is not a MultibodyTreeContext.
std::runtime_errorif pc is the nullptr.

Here is the caller graph for this function:

std::unique_ptr< systems::Context< T > > CreateDefaultContext ( ) const

Allocates a new context for this MultibodyTree uniquely identifying the state of the multibody system.

Precondition
The method Finalize() must be called before attempting to create a context in order for the MultibodyTree topology to be valid at the moment of allocation.
Exceptions
std::logic_errorIf users attempt to call this method on a MultibodyTree with an invalid topology.

Here is the caller graph for this function:

void Finalize ( )

This method must be called after all elements in the tree (joints, bodies, force elements, constraints) were added and before any computations are performed.

It essentially compiles all the necessary "topological information", i.e. how bodies, joints and, any other elements connect with each other, and performs all the required pre-processing to perform computations at a later stage.

If the finalize stage is successful, the topology of this MultibodyTree is validated, meaning that the topology is up-to-date after this call. No more multibody tree elements can be added after a call to Finalize().

Exceptions
std::logic_errorIf users attempt to call this method on an already finalized MultibodyTree.

Here is the call graph for this function:

Here is the caller graph for this function:

const Body<T>& get_body ( BodyIndex  body_index) const
inline

Returns a constant reference to the body with unique index body_index.

This method aborts in Debug builds when body_index does not correspond to a body in this multibody tree.

Here is the call graph for this function:

int get_num_bodies ( ) const
inline

Returns the number of bodies in the MultibodyTree including the world body.

Therefore the minimum number of bodies in a MultibodyTree is one.

Here is the caller graph for this function:

int get_num_frames ( ) const
inline

Returns the number of Frame objects in the MultibodyTree.

Frames include body frames associated with each of the bodies in the MultibodyTree including the world body. Therefore the minimum number of frames in a MultibodyTree is one.

Here is the caller graph for this function:

int get_num_mobilizers ( ) const
inline

Returns the number of mobilizers in the MultibodyTree.

Since the world has no Mobilizer, the number of mobilizers equals the number of bodies minus one, i.e. get_num_mobilizers() returns get_num_bodies() - 1.

Here is the caller graph for this function:

const MultibodyTreeTopology& get_topology ( ) const
inline

Returns the topology information for this multibody tree.

Users should not need to call this method since MultibodyTreeTopology is an internal bookkeeping detail. Used at Finalize() stage by multibody elements to retrieve a local copy of their topology.

Here is the call graph for this function:

int get_tree_height ( ) const
inline

Returns the height of the tree data structure of this MultibodyTree.

That is, the number of bodies in the longest kinematic path between the world and any other leaf body. For a model that only contains the world body, the height of the tree is one. Kinematic paths are created by Mobilizer objects connecting a chain of frames. Therefore, this method does not count kinematic cycles, which could only be considered in the model using constraints.

Here is the call graph for this function:

const Body<T>& get_world_body ( ) const
inline

Returns a constant reference to the world body.

Here is the call graph for this function:

const BodyFrame<T>& get_world_frame ( ) const
inline

Returns a constant reference to the world frame.

Here is the call graph for this function:

MultibodyTree& operator= ( MultibodyTree< T > &&  )
delete
MultibodyTree& operator= ( const MultibodyTree< T > &  )
delete
void SetDefaults ( systems::Context< T > *  context) const

Sets default values in the context.

For mobilizers, this method sets them to their zero configuration according to Mobilizer::set_zero_configuration().

Here is the caller graph for this function:

bool topology_is_valid ( ) const
inline

Returns true if this MultibodyTree was finalized with Finalize() after all multibody elements were added, and false otherwise.

When a MultibodyTree is instantiated, its topology remains invalid until Finalize() is called, which validates the topology.

See also
Finalize().

Here is the call graph for this function:

Here is the caller graph for this function:


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