Drake
ScrewJoint< T > Class Template Referencefinal

## Detailed Description

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

This joint models a screw joint allowing two bodies to rotate about one axis while translating along that same axis with one degree of freedom.

That is, given a frame F attached to the parent body P and a frame M attached to the child body B (see the Joint class's documentation), this joint allows frame M to translate (while rotating) along the z axis of frame F, with M's z-axis Mz and F's z-axis Fz coincident at all times. The rotation about z-axis of F and their rate specify the state of the joint. Zero (θ) corresponds to frames F and M being coincident and aligned. Translation z is defined to be positive in the direction of the respective axis and the rotation θ is defined to be positive according to the right-hand-rule with the thumb aligned in the direction of frame F's z-axis.

Template Parameters
 T The scalar type, which must be one of the default scalars.

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

## Public Types

template<typename Scalar >
using Context = systems::Context< Scalar >

## Public Member Functions

ScrewJoint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, double screw_pitch, double damping)
Constructor to create a screw joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B translate and rotate as described in the class's documentation. More...

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

double screw_pitch () const
Returns this joint's amount of translation in meters occuring over a one full revolution. More...

double damping () const
Returns this joint's damping constant N⋅m⋅s for the rotational degree. More...

get_default_translation () const
Gets the default position for this joint. More...

void set_default_translation (const double &z)
Sets the default translation of this joint. More...

double get_default_rotation () const
Gets the default angle for this joint. More...

void set_default_rotation (double theta)
Sets the default angle of this joint. More...

void set_random_pose_distribution (const Vector1< symbolic::Expression > &theta)
Sets the random distribution that the angle of this joint will be randomly sampled from. More...

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

ScrewJointoperator= (const ScrewJoint &)=delete

ScrewJoint (ScrewJoint &&)=delete

ScrewJointoperator= (ScrewJoint &&)=delete

Context-dependent value access
get_translation (const Context< T > &context) const
Gets the translation of this joint from context. More...

const ScrewJoint< T > & set_translation (Context< T > *context, const T &z) const
Sets the context so that the translation of this joint equals to (z). More...

get_rotation (const systems::Context< T > &context) const
Gets the angle θ of this joint from context. More...

const ScrewJoint< T > & set_rotation (systems::Context< T > *context, const T &theta) const
Sets the context so that the angle θ of this joint equals theta. More...

get_translational_velocity (const systems::Context< T > &context) const
Gets the translational velocity vz, in meters per second, of this joint's Mo measured and expressed in frame F from context. More...

const ScrewJoint< T > & set_translational_velocity (systems::Context< T > *context, const T &vz) const
Sets the translational velocity, in meters per second, of this this joint's Mo along frame F's Z-axis to vz. More...

get_angular_velocity (const systems::Context< T > &context) const
Gets the rate of change, in radians per second, of this joint's angle θ from context. More...

const ScrewJoint< T > & set_angular_velocity (systems::Context< T > *context, const T &theta_dot) const
Sets the rate of change, in radians per second, of this joint's angle θ (see class documentation) to theta_dot. More...

Public Member Functions inherited from Joint< T >
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...

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

Joint (const Joint &)=delete

Jointoperator= (const Joint &)=delete

Joint (Joint &&)=delete

Jointoperator= (Joint &&)=delete

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

## Static Public Attributes

static constexpr char kTypeName [] = "screw"
The name for this Joint type. More...

## Friends

template<typename >
class ScrewJoint

Protected Member Functions inherited from Joint< T >
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...

void DoSetTopology (const internal::MultibodyTreeTopology &) override
Implementation of the NVI SetTopology(). 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...

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

## ◆ Context

 using Context = systems::Context

## ◆ ScrewJoint() [1/3]

 ScrewJoint ( const ScrewJoint< T > & )
delete

## ◆ ScrewJoint() [2/3]

 ScrewJoint ( ScrewJoint< T > && )
delete

## ◆ ScrewJoint() [3/3]

 ScrewJoint ( const std::string & name, const Frame< T > & frame_on_parent, const Frame< T > & frame_on_child, double screw_pitch, double damping )

Constructor to create a screw joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B translate and rotate as described in the class's documentation.

This constructor signature creates a joint with no joint limits, i.e. the joint angular position, angular velocity and angular acceleration limits are the pair (-∞, ∞). These can be set using the Joint methods set_position_limits(), set_velocity_limits() and set_acceleration_limits() in radians, radians/sec, radians/sec^2 units. The first three arguments to this constructor are those of the Joint class constructor. See the Joint class's documentation for details. The additional parameters are:

Parameters
 [in] screw_pitch Amount of translation in meters occuring over a one full screw revolution. It's domain is (-∞, ∞). When the screw pitch is negative, positive rotation will result in translating towards the negative direction of z-axis. When the screw pitch is zero, this joint will behave like a revolute joint. [in] damping Viscous damping coefficient, N⋅m⋅s/rad for rotation, used to model losses within the joint. See documentation of damping() for details on modelling of the damping torque.
Exceptions
 std::exception if damping is negative.

## ◆ damping()

 double damping ( ) const

Returns this joint's damping constant N⋅m⋅s for the rotational degree.

The damping torque (in N⋅m) is modeled as τ = -damping⋅ω i.e. opposing motion, with ω the angular rate for this joint (see get_angular_velocity()) and τ the torque on child body B expressed in frame F as t_B_F = τ⋅Fz_F.

## ◆ get_angular_velocity()

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

Gets the rate of change, in radians per second, of this joint's angle θ from context.

See class documentation for the definition of this angle.

Parameters
 [in] context The context of the model this joint belongs to.
Return values
 theta_dot The rate of change of this joint's angle θ as stored in the context.

## ◆ get_default_rotation()

 double get_default_rotation ( ) const

Gets the default angle for this joint.

Return values
 theta The default angle of this joint.

## ◆ get_default_translation()

 T get_default_translation ( ) const

Gets the default position for this joint.

Return values
 z The default position of this joint.

## ◆ get_rotation()

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

Gets the angle θ of this joint from context.

Parameters
 [in] context The context of the model this joint belongs to.
Return values
 theta The angle of this joint stored in the context. See class documentation for details.

## ◆ get_translation()

 T get_translation ( const Context< T > & context ) const

Gets the translation of this joint from context.

Parameters
 [in] context The context of the model this joint belongs to.
Return values
 z The translation of this joint stored in the context as (z). See class documentation for details.

## ◆ get_translational_velocity()

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

Gets the translational velocity vz, in meters per second, of this joint's Mo measured and expressed in frame F from context.

Parameters
 [in] context The context of the model this joint belongs to.
Return values
 vz The translational velocity of this joint as stored in the context.

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

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

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

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

## ◆ screw_pitch()

 double screw_pitch ( ) const

Returns this joint's amount of translation in meters occuring over a one full revolution.

## ◆ set_angular_velocity()

 const ScrewJoint& set_angular_velocity ( systems::Context< T > * context, const T & theta_dot ) const

Sets the rate of change, in radians per second, of this joint's angle θ (see class documentation) to theta_dot.

The new rate of change gets stored in context.

Parameters
 [in] context The context of the model this joint belongs to. [in] theta_dot The desired rates of change of this joint's angle in radians per second.
Returns
a constant reference to this joint.

## ◆ set_default_rotation()

 void set_default_rotation ( double theta )

Sets the default angle of this joint.

This will change the default_translation too, because they are not independent in this joint.

Parameters
 [in] theta The desired default angle of the joint

## ◆ set_default_translation()

 void set_default_translation ( const double & z )

Sets the default translation of this joint.

This will change the default_rotation too, which are not independent in this joint.

Parameters
 [in] z The desired default translation of the joint
Exceptions
 std::exception if pitch is very near zero.

## ◆ set_random_pose_distribution()

 void set_random_pose_distribution ( const Vector1< symbolic::Expression > & theta )

Sets the random distribution that the angle of this joint will be randomly sampled from.

See class documentation for details on the definition of the position and angle.

## ◆ set_rotation()

 const ScrewJoint& set_rotation ( systems::Context< T > * context, const T & theta ) const

Sets the context so that the angle θ of this joint equals theta.

Parameters
 [in] context The context of the model this joint belongs to. [in] theta The desired angle in radians to be stored in context. See class documentation for details.
Returns
a constant reference to this joint.

## ◆ set_translation()

 const ScrewJoint& set_translation ( Context< T > * context, const T & z ) const

Sets the context so that the translation of this joint equals to (z).

Parameters
 [in] context The context of the model this joint belongs to. [in] z The desired translation in meters to be stored in context as (z). See class documentation for details.
Returns
a constant reference to this joint.

## ◆ set_translational_velocity()

 const ScrewJoint& set_translational_velocity ( systems::Context< T > * context, const T & vz ) const

Sets the translational velocity, in meters per second, of this this joint's Mo along frame F's Z-axis to vz.

The new translational velocity gets stored in context.

Parameters
 [in] context The context of the model this joint belongs to. [in] vz The desired translational velocity of this joint in meters per second along F frame's Z-axis.
Returns
a constant reference to this joint.

## ◆ type_name()

 const std::string& type_name ( ) const
finalvirtual

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

Implements Joint< T >.

## ◆ ScrewJoint

 friend class ScrewJoint
friend

## ◆ kTypeName

 constexpr char kTypeName[] = "screw"
static

The name for this Joint type.

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