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

Constructor & Destructor Documentation

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

Creates a MultibodyTree containing only a world body.

Member Function Documentation

 const BodyType& 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 =
Exceptions
 std::logic_error if body is a nullptr. std::logic_error if Finalize() was already called on this tree.
Parameters
 [in] body A 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
 BodyType The 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& 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.

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;
Exceptions
 std::logic_error if Finalize() was already called on this tree.
Parameters
 [in] args The 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
 BodyType A 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& 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 =
Exceptions
 std::logic_error if frame is a nullptr. std::logic_error if Finalize() was already called on this tree.
Parameters
 [in] frame A 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
 FrameType The 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& 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 =

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 =
Exceptions
 std::logic_error if Finalize() was already called on this tree.
Parameters
 [in] args The 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
 FrameType A 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& 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
const RevoluteMobilizer<T>& pin =
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_error if mobilizer is a nullptr. std::logic_error if Finalize() was already called on this tree. a std::runtime_error if the new mobilizer attempts to connect a frame with itself. std::runtime_error if attempting to connect two bodies with more than one mobilizer between them.
Parameters
 [in] mobilizer A 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
 MobilizerType The 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& 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
// Notice RevoluteMobilizer is a template an a scalar type.
const RevoluteMobilizer<T>& pin =
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_error if Finalize() was already called on this tree. a std::runtime_error if the new mobilizer attempts to connect a frame with itself. std::runtime_error if attempting to connect two bodies with more than one mobilizer between them.
Parameters
 [in] args The 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
 MobilizerType A 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_cast if context is not a MultibodyTreeContext. std::runtime_error if 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_error If 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_error If 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& 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& get_world_body ( ) const
inline

Returns a constant reference to the world body.

Here is the call graph for this function:

 const BodyFrame& 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.