Drake
Joint< T > Class Template Referenceabstract

## Detailed Description

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

A Joint models the kinematical relationship which characterizes the possible relative motion between two bodies.

The two bodies connected by this Joint object are referred to as parent and child bodies. The parent/child ordering defines the sign conventions for the generalized coordinates and the coordinate ordering for multi-DOF joints. A Joint is a model of a physical kinematic constraint between two bodies, a constraint that in the real physical system does not specify a tree ordering.

In Drake we define a frame F rigidly attached to the parent body P with pose X_PF and a frame M rigidly attached to the child body B with pose X_BM. A Joint object specifies a kinematic relation between frames F and M, which in turn imposes a kinematic relation between bodies P and B.

Typical joints include the ball joint, to allow unrestricted rotations about a given point, the revolute joint, that constraints two bodies to rotate about a given common axis, etc.

Consider the following example to build a simple pendulum system:

MultibodyPlant<double> plant(0.0);
// ... Code here to setup quantities below as mass, com, etc. ...
const Body<double>& pendulum =
// We will connect the pendulum body to the world using a RevoluteJoint.
// In this simple case the parent body P is the model's world body and frame
// F IS the world frame.
// Additionally, we need to specify the pose of frame M on the pendulum's
// body frame B.
// Say we declared and initialized X_BM...
const RevoluteJoint<double>& elbow =
"Elbow", /* joint name */
plant.world_body(), /* parent body */
{}, /* frame F IS the world frame W */
pendulum, /* child body, the pendulum */
X_BM, /* pose of frame M in the body frame B */
Vector3d::UnitZ()); /* revolute axis in this case */
Warning
Do not ever attempt to instantiate and manipulate Joint objects on the stack; it will fail. Add joints to your plant using the provided API MultibodyPlant::AddJoint() as in the example above.
Template Parameters
 T The scalar type, which must be one of the default scalars.

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

## Classes

struct  BluePrint
(Advanced) Structure containing all the information needed to build the MultibodyTree implementation for a Joint. More...

struct  JointImplementation
(Advanced) A Joint is implemented in terms of MultibodyTree elements such as bodies, mobilizers, force elements and constraints. More...

## Public Member Functions

Joint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, const VectorX< double > &pos_lower_limits, const VectorX< double > &pos_upper_limits, const VectorX< double > &vel_lower_limits, const VectorX< double > &vel_upper_limits, const VectorX< double > &acc_lower_limits, const VectorX< double > &acc_upper_limits)
Creates a joint between two Frame objects which imposes a given kinematic relation between frame F attached on the parent body P and frame M attached on the child body B. More...

virtual ~Joint ()

const std::string & name () const
Returns the name of this joint. More...

const Body< T > & parent_body () const
Returns a const reference to the parent body P. More...

const Body< T > & child_body () const
Returns a const reference to the child body B. More...

const Frame< T > & frame_on_parent () const
Returns a const reference to the frame F attached on the parent body P. More...

const Frame< T > & frame_on_child () const
Returns a const reference to the frame M attached on the child body B. More...

virtual const std::string & type_name () const =0
Returns a string identifying the type of this joint, such as "revolute" or "prismatic". More...

int velocity_start () const
Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system. More...

int num_velocities () const
Returns the number of generalized velocities describing this joint. More...

int position_start () const
Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system. More...

int num_positions () const
Returns the number of generalized positions describing this joint. More...

const T & GetOnePosition (const systems::Context< T > &context) const
Returns the position coordinate for joints with a single degree of freedom. More...

const T & GetOneVelocity (const systems::Context< T > &context) const
Returns the velocity coordinate for joints with a single degree of freedom. More...

void AddInOneForce (const systems::Context< T > &context, int joint_dof, const T &joint_tau, MultibodyForces< T > *forces) const
Adds into forces a force along the one of the joint's degrees of freedom indicated by index joint_dof. More...

void AddInDamping (const systems::Context< T > &context, MultibodyForces< T > *forces) const
Adds into forces the force due to damping within this joint. More...

void Lock (systems::Context< T > *context) const
Lock the joint. More...

void Unlock (systems::Context< T > *context) const
Unlock the joint. More...

bool is_locked (const systems::Context< T > &context) const

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

Jointoperator= (const Joint &)=delete

Joint (Joint &&)=delete

Jointoperator= (Joint &&)=delete

Methods to get and set the limits of <tt>this</tt> joint. For position

limits, the layout is the same as the generalized position's.

For velocity and acceleration limits, the layout is the same as the generalized velocity's. A limit with value +/- ∞ implies no upper or lower limit.

Returns the position lower limits.

const VectorX< double > & position_lower_limits () const

const VectorX< double > & position_upper_limits () const
Returns the position upper limits. More...

const VectorX< double > & velocity_lower_limits () const
Returns the velocity lower limits. More...

const VectorX< double > & velocity_upper_limits () const
Returns the velocity upper limits. More...

const VectorX< double > & acceleration_lower_limits () const
Returns the acceleration lower limits. More...

const VectorX< double > & acceleration_upper_limits () const
Returns the acceleration upper limits. More...

const VectorX< double > & default_positions () const
Returns the default positions. More...

void set_position_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
Sets the position limits to lower_limits and upper_limits. More...

void set_velocity_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
Sets the velocity limits to lower_limits and upper_limits. More...

void set_acceleration_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
Sets the acceleration limits to lower_limits and upper_limits. More...

void set_default_positions (const VectorX< double > &default_positions)
Sets the default positions to default_positions. More...

Public Member Functions inherited from MultibodyElement< Joint, T, JointIndex >
virtual ~MultibodyElement ()

JointIndex index () const
Returns this element's unique index. More...

ModelInstanceIndex model_instance () const
Returns the ModelInstanceIndex of the model instance to which this element belongs. More...

const MultibodyPlantDeferred & GetParentPlant () const
Returns the MultibodyPlant that owns this MultibodyElement. More...

void DeclareParameters (internal::MultibodyTreeSystem< T > *tree_system)
Declares MultibodyTreeSystem Parameters at MultibodyTreeSystem::Finalize() time. More...

MultibodyElement (const MultibodyElement &)=delete

MultibodyElement (MultibodyElement &&)=delete

MultibodyElementoperator= (const MultibodyElement &)=delete

MultibodyElementoperator= (MultibodyElement &&)=delete

## Protected Member Functions

virtual int do_get_velocity_start () const =0
Implementation to the NVI velocity_start(), see velocity_start() for details. More...

virtual int do_get_num_velocities () const =0
Implementation to the NVI num_velocities(), see num_velocities() for details. More...

virtual int do_get_position_start () const =0
Implementation to the NVI position_start(), see position_start() for details. More...

virtual int do_get_num_positions () const =0
Implementation to the NVI num_positions(), see num_positions() for details. More...

virtual void do_set_default_positions (const VectorX< double > &default_positions)=0
Implementation to the NVI set_default_positions(), see set_default_positions() for details. More...

virtual const T & DoGetOnePosition (const systems::Context< T > &) const
Implementation to the NVI GetOnePosition() that must only be implemented by those joint subclasses that have a single degree of freedom. More...

virtual const T & DoGetOneVelocity (const systems::Context< T > &) const
Implementation to the NVI GetOneVelocity() that must only be implemented by those joint subclasses that have a single degree of freedom. More...

virtual void DoAddInOneForce (const systems::Context< T > &context, int joint_dof, const T &joint_tau, MultibodyForces< T > *forces) const =0
Adds into forces a force along the one of the joint's degrees of freedom given by joint_dof. More...

virtual void DoAddInDamping (const systems::Context< T > &, MultibodyForces< T > *) const
Adds into MultibodyForces the forces due to damping within this joint. More...

void DoSetTopology (const internal::MultibodyTreeTopology &) override
Implementation of the NVI SetTopology(). More...

virtual std::unique_ptr< BluePrintMakeImplementationBlueprint () const =0
This method must be implemented by derived classes in order to provide JointImplementationBuilder a BluePrint of their internal implementation JointImplementation. More...

const JointImplementationget_implementation () const
Returns a const reference to the internal implementation of this joint. More...

bool has_implementation () const
Returns whether this joint owns a particular implementation. More...

void DoDeclareParameters (internal::MultibodyTreeSystem< T > *tree_system) override
Implementation of the NVI DeclareParameters(). More...

Methods to make a clone templated on different scalar types.

Clones this Joint (templated on T) to a joint templated on double.

virtual std::unique_ptr< Joint< double > > DoCloneToScalar (const internal::MultibodyTree< double > &tree_clone) const =0

virtual std::unique_ptr< Joint< AutoDiffXd > > DoCloneToScalar (const internal::MultibodyTree< AutoDiffXd > &tree_clone) const =0
Clones this Joint (templated on T) to a joint templated on AutoDiffXd. More...

virtual std::unique_ptr< Joint< symbolic::Expression > > DoCloneToScalar (const internal::MultibodyTree< symbolic::Expression > &) const =0

Protected Member Functions inherited from MultibodyElement< Joint, T, JointIndex >
MultibodyElement ()
Default constructor made protected so that sub-classes can still declare their default constructors if they need to. More...

MultibodyElement (ModelInstanceIndex model_instance)
Constructor which allows specifying a model instance. More...

const internal::MultibodyTree< T > & get_parent_tree () const
Returns a constant reference to the parent MultibodyTree that owns this element. More...

const internal::MultibodyTreeSystem< T > & GetParentTreeSystem () const
Returns a constant reference to the parent MultibodyTreeSystem that owns the parent MultibodyTree that owns this element. More...

void SetTopology (const internal::MultibodyTreeTopology &tree)
Gives MultibodyElement-derived objects the opportunity to retrieve their topology after MultibodyTree::Finalize() is invoked. More...

systems::NumericParameterIndex DeclareNumericParameter (internal::MultibodyTreeSystem< T > *tree_system, const systems::BasicVector< T > &model_vector)
To be used by MultibodyElement-derived objects when declaring parameters in their implementation of DoDeclareParameters(). More...

systems::AbstractParameterIndex DeclareAbstractParameter (internal::MultibodyTreeSystem< T > *tree_system, const AbstractValue &model_value)
To be used by MultibodyElement-derived objects when declaring parameters in their implementation of DoDeclareParameters(). More...

## Friends

template<typename >
class Joint

class internal::JointImplementationBuilder< T >

## ◆ Joint() [1/3]

 Joint ( const Joint< T > & )
delete

## ◆ Joint() [2/3]

 Joint ( Joint< T > && )
delete

## ◆ Joint() [3/3]

 Joint ( const std::string & name, const Frame< T > & frame_on_parent, const Frame< T > & frame_on_child, const VectorX< double > & pos_lower_limits, const VectorX< double > & pos_upper_limits, const VectorX< double > & vel_lower_limits, const VectorX< double > & vel_upper_limits, const VectorX< double > & acc_lower_limits, const VectorX< double > & acc_upper_limits )

Creates a joint between two Frame objects which imposes a given kinematic relation between frame F attached on the parent body P and frame M attached on the child body B.

The joint will be initialized to the model instance from frame_on_child (this is the typical convention for joints between the world and a model, or between two models (e.g. an arm to a gripper)). See this class's documentation for further details.

Parameters
 [in] name A string with a name identifying this joint. [in] frame_on_parent The frame F attached on the parent body connected by this joint. [in] frame_on_child The frame M attached on the child body connected by this joint. [in] pos_lower_limits A vector storing the lower limit for each generalized position. It must have the same size as pos_upper_limit. A value equal to -∞ implies no lower limit. [in] pos_upper_limits A vector storing the upper limit for each generalized position. It must have the same size as pos_lower_limit. A value equal to +∞ implies no upper limit. [in] vel_lower_limits A vector storing the lower limit for each generalized velocity. It must have the same size as vel_upper_limit. A value equal to -∞ implies no lower limit. [in] vel_upper_limits A vector storing the upper limit for each generalized velocity. It must have the same size as vel_lower_limit. A value equal to +∞ implies no upper limit. [in] acc_lower_limits A vector storing the lower limit for each generalized acceleration. It must have the same size as acc_upper_limit. A value equal to -∞ implies no lower limit. [in] acc_upper_limits A vector storing the upper limit for each generalized acceleration. It must have the same size as acc_lower_limit. A value equal to +∞ implies no upper limit.

## ◆ ~Joint()

 virtual ~Joint ( )
virtual

## ◆ acceleration_lower_limits()

 const VectorX& acceleration_lower_limits ( ) const

Returns the acceleration lower limits.

## ◆ acceleration_upper_limits()

 const VectorX& acceleration_upper_limits ( ) const

Returns the acceleration upper limits.

 void AddInDamping ( const systems::Context< T > & context, MultibodyForces< T > * forces ) const

Adds into forces the force due to damping within this joint.

Parameters
 [in] context The context storing the state and parameters for the model to which this joint belongs. [out] forces On return, this method will add the force due to damping within this joint. This method aborts if forces is nullptr or if forces does not have the right sizes to accommodate a set of forces for the model to which this joint belongs.

 void AddInOneForce ( const systems::Context< T > & context, int joint_dof, const T & joint_tau, MultibodyForces< T > * forces ) const

Adds into forces a force along the one of the joint's degrees of freedom indicated by index joint_dof.

The meaning for this degree of freedom and even its dimensional units depend on the specific joint sub-class. For a RevoluteJoint for instance, joint_dof can only be 0 since revolute joints's motion subspace only has one degree of freedom, while the units of joint_tau are those of torque (N⋅m in the MKS system of units). For multi-dof joints please refer to the documentation provided by specific joint sub-classes regarding the meaning of joint_dof.

Parameters
 [in] context The context storing the state and parameters for the model to which this joint belongs. [in] joint_dof Index specifying one of the degrees of freedom for this joint. The index must be in the range 0 <= joint_dof < num_velocities() or otherwise this method will abort. [in] joint_tau Generalized force corresponding to the degree of freedom indicated by joint_dof to be added into forces. [out] forces On return, this method will add force joint_tau for the degree of freedom joint_dof into the output forces. This method aborts if forces is nullptr or if forces doest not have the right sizes to accommodate a set of forces for the model to which this joint belongs.

## ◆ child_body()

 const Body& child_body ( ) const

Returns a const reference to the child body B.

## ◆ default_positions()

 const VectorX& default_positions ( ) const

Returns the default positions.

## ◆ do_get_num_positions()

 virtual int do_get_num_positions ( ) const
protectedpure virtual

Implementation to the NVI num_positions(), see num_positions() for details.

Note
Implementations must meet the styleguide requirements for snake_case accessor methods.

## ◆ do_get_num_velocities()

 virtual int do_get_num_velocities ( ) const
protectedpure virtual

Implementation to the NVI num_velocities(), see num_velocities() for details.

Note
Implementations must meet the styleguide requirements for snake_case accessor methods.

## ◆ do_get_position_start()

 virtual int do_get_position_start ( ) const
protectedpure virtual

Implementation to the NVI position_start(), see position_start() for details.

Note
Implementations must meet the styleguide requirements for snake_case accessor methods.

## ◆ do_get_velocity_start()

 virtual int do_get_velocity_start ( ) const
protectedpure virtual

Implementation to the NVI velocity_start(), see velocity_start() for details.

Note
Implementations must meet the styleguide requirements for snake_case accessor methods.

## ◆ do_set_default_positions()

 virtual void do_set_default_positions ( const VectorX< double > & default_positions )
protectedpure virtual

Implementation to the NVI set_default_positions(), see set_default_positions() for details.

It is the responsibility of the subclass to ensure that their joint implementation, should they have one, is updated with default_positions.

Note
Implementations must meet the styleguide requirements for snake_case accessor methods.

 virtual void DoAddInDamping ( const systems::Context< T > & , MultibodyForces< T > * ) const
protectedvirtual

Adds into MultibodyForces the forces due to damping within this joint.

How forces are added to a MultibodyTree model depends on the underlying implementation of a particular joint (for instance, mobilizer vs. constraint) and therefore specific Joint subclasses must provide a definition for this method. The default implementation is a no-op for joints with no damping.

Reimplemented in RevoluteJoint< T >, PrismaticJoint< T >, BallRpyJoint< T >, and UniversalJoint< T >.

 virtual void DoAddInOneForce ( const systems::Context< T > & context, int joint_dof, const T & joint_tau, MultibodyForces< T > * forces ) const
protectedpure virtual

Adds into forces a force along the one of the joint's degrees of freedom given by joint_dof.

How forces are added to a MultibodyTree model depends on the underlying implementation of a particular joint and therefore specific Joint subclasses must provide a definition for this method. For instance, a revolute joint could be modeled with a single generalized coordinate for the angular rotation (implemented through a RevoluteMobilizer) or it could be modeled using a constraint that only allows rotation about the joint's axis but that constrains the motion in the other five degrees of freedom. This method is only called by the public NVI AddInOneForce() and therefore input arguments were checked to be valid.

The public NVI AddInOneForce() for details.

Implemented in RevoluteJoint< T >, PrismaticJoint< T >, BallRpyJoint< T >, UniversalJoint< T >, and WeldJoint< T >.

## ◆ DoCloneToScalar() [1/3]

 virtual std::unique_ptr > DoCloneToScalar ( const internal::MultibodyTree< double > & tree_clone ) const
protectedpure virtual

## ◆ DoCloneToScalar() [2/3]

 virtual std::unique_ptr > DoCloneToScalar ( const internal::MultibodyTree< AutoDiffXd > & tree_clone ) const
protectedpure virtual

Clones this Joint (templated on T) to a joint templated on AutoDiffXd.

## ◆ DoCloneToScalar() [3/3]

 virtual std::unique_ptr > DoCloneToScalar ( const internal::MultibodyTree< symbolic::Expression > & ) const
protectedpure virtual

## ◆ DoDeclareParameters()

 void DoDeclareParameters ( internal::MultibodyTreeSystem< T > * )
overrideprotectedvirtual

Implementation of the NVI DeclareParameters().

MultibodyElement-derived objects must override to declare their specific parameters. If an object is not a direct descendent of MultibodyElement, it must invoke its parent classes' DoDeclareParameters() before declaring its own parameters.

Reimplemented from MultibodyElement< Joint, T, JointIndex >.

## ◆ DoGetOnePosition()

 virtual const T& DoGetOnePosition ( const systems::Context< T > & ) const
protectedvirtual

Implementation to the NVI GetOnePosition() that must only be implemented by those joint subclasses that have a single degree of freedom.

The default implementation for all other joints is to abort with an appropriate message. Revolute and prismatic are examples of joints that will want to implement this method.

## ◆ DoGetOneVelocity()

 virtual const T& DoGetOneVelocity ( const systems::Context< T > & ) const
protectedvirtual

Implementation to the NVI GetOneVelocity() that must only be implemented by those joint subclasses that have a single degree of freedom.

The default implementation for all other joints is to abort with an appropriate message. Revolute and prismatic are examples of joints that will want to implement this method.

## ◆ DoSetTopology()

 void DoSetTopology ( const internal::MultibodyTreeTopology & tree )
overrideprotectedvirtual

Implementation of the NVI SetTopology().

For advanced use only for developers implementing new MultibodyTree components.

Implements MultibodyElement< Joint, T, JointIndex >.

## ◆ frame_on_child()

 const Frame& frame_on_child ( ) const

Returns a const reference to the frame M attached on the child body B.

## ◆ frame_on_parent()

 const Frame& frame_on_parent ( ) const

Returns a const reference to the frame F attached on the parent body P.

## ◆ get_implementation()

 const JointImplementation& get_implementation ( ) const
protected

Returns a const reference to the internal implementation of this joint.

Warning
The MultibodyTree model must have already been finalized, or this method will abort.

## ◆ GetOnePosition()

 const T& GetOnePosition ( const systems::Context< T > & context ) const

Returns the position coordinate for joints with a single degree of freedom.

Exceptions
 std::exception if the joint does not have a single degree of freedom.

## ◆ GetOneVelocity()

 const T& GetOneVelocity ( const systems::Context< T > & context ) const

Returns the velocity coordinate for joints with a single degree of freedom.

Exceptions
 std::exception if the joint does not have a single degree of freedom.

## ◆ has_implementation()

 bool has_implementation ( ) const
protected

Returns whether this joint owns a particular implementation.

If the MultibodyTree has been finalized, this will return true.

## ◆ is_locked()

 bool is_locked ( const systems::Context< T > & context ) const
Returns
true if the joint is locked, false otherwise.

## ◆ Lock()

 void Lock ( systems::Context< T > * context ) const

Lock the joint.

Its generalized velocities will be 0 until it is unlocked. Locking is not yet supported for continuous-mode systems.

Exceptions
 std::exception if the parent model uses continuous state.

## ◆ MakeImplementationBlueprint()

 virtual std::unique_ptr MakeImplementationBlueprint ( ) const
protectedpure virtual

This method must be implemented by derived classes in order to provide JointImplementationBuilder a BluePrint of their internal implementation JointImplementation.

## ◆ name()

 const std::string& name ( ) const

Returns the name of this joint.

## ◆ num_positions()

 int num_positions ( ) const

Returns the number of generalized positions describing this joint.

## ◆ num_velocities()

 int num_velocities ( ) const

Returns the number of generalized velocities describing this joint.

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

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

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

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

## ◆ parent_body()

 const Body& parent_body ( ) const

Returns a const reference to the parent body P.

## ◆ position_lower_limits()

 const VectorX& position_lower_limits ( ) const

## ◆ position_start()

 int position_start ( ) const

Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system.

## ◆ position_upper_limits()

 const VectorX& position_upper_limits ( ) const

Returns the position upper limits.

## ◆ set_acceleration_limits()

 void set_acceleration_limits ( const VectorX< double > & lower_limits, const VectorX< double > & upper_limits )

Sets the acceleration limits to lower_limits and upper_limits.

Exceptions
 std::exception if the dimension of lower_limits or upper_limits does not match num_velocities(). std::exception if any of lower_limits is larger than the corresponding term in upper_limits.

## ◆ set_default_positions()

 void set_default_positions ( const VectorX< double > & default_positions )

Sets the default positions to default_positions.

Joint subclasses are expected to implement the do_set_default_positions().

Exceptions
 std::exception if the dimension of default_positions does not match num_positions().
Note
The values in default_positions are NOT constrained to be within position_lower_limits() and position_upper_limits().

## ◆ set_position_limits()

 void set_position_limits ( const VectorX< double > & lower_limits, const VectorX< double > & upper_limits )

Sets the position limits to lower_limits and upper_limits.

Exceptions
 std::exception if the dimension of lower_limits or upper_limits does not match num_positions(). std::exception if any of lower_limits is larger than the corresponding term in upper_limits.
Note
Setting the position limits does not affect the default_positions(), regardless of whether the current default_positions() satisfy the new position limits.

## ◆ set_velocity_limits()

 void set_velocity_limits ( const VectorX< double > & lower_limits, const VectorX< double > & upper_limits )

Sets the velocity limits to lower_limits and upper_limits.

Exceptions
 std::exception if the dimension of lower_limits or upper_limits does not match num_velocities(). std::exception if any of lower_limits is larger than the corresponding term in upper_limits.

## ◆ type_name()

 virtual const std::string& type_name ( ) const
pure virtual

Returns a string identifying the type of this joint, such as "revolute" or "prismatic".

## ◆ Unlock()

 void Unlock ( systems::Context< T > * context ) const

Unlock the joint.

Unlocking is not yet supported for continuous-mode systems.

Exceptions
 std::exception if the parent model uses continuous state.

## ◆ velocity_lower_limits()

 const VectorX& velocity_lower_limits ( ) const

Returns the velocity lower limits.

## ◆ velocity_start()

 int velocity_start ( ) const

Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system.

## ◆ velocity_upper_limits()

 const VectorX& velocity_upper_limits ( ) const

Returns the velocity upper limits.

## ◆ internal::JointImplementationBuilder< T >

 friend class internal::JointImplementationBuilder< T >
friend

## ◆ Joint

 friend class Joint
friend

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