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

Additional Inherited Members

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

Member Typedef Documentation

◆ Context

using Context = systems::Context<Scalar>

Constructor & Destructor Documentation

◆ 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_pitchAmount 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]dampingViscous 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::exceptionif damping is negative.

Member Function Documentation

◆ 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]contextThe context of the model this joint belongs to.
Return values
theta_dotThe 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
thetaThe default angle of this joint.

◆ get_default_translation()

T get_default_translation ( ) const

Gets the default position for this joint.

Return values
zThe 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]contextThe context of the model this joint belongs to.
Return values
thetaThe 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]contextThe context of the model this joint belongs to.
Return values
zThe 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]contextThe context of the model this joint belongs to.
Return values
vzThe 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<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.

The new rate of change gets stored in context.

Parameters
[in]contextThe context of the model this joint belongs to.
[in]theta_dotThe 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]thetaThe 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]zThe desired default translation of the joint
Exceptions
std::exceptionif 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<T>& set_rotation ( systems::Context< T > *  context,
const T &  theta 
) const

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

Parameters
[in]contextThe context of the model this joint belongs to.
[in]thetaThe 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<T>& set_translation ( Context< T > *  context,
const T &  z 
) const

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

Parameters
[in]contextThe context of the model this joint belongs to.
[in]zThe 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<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.

The new translational velocity gets stored in context.

Parameters
[in]contextThe context of the model this joint belongs to.
[in]vzThe 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 >.

Friends And Related Function Documentation

◆ ScrewJoint

friend class ScrewJoint
friend

Member Data Documentation

◆ kTypeName

constexpr char kTypeName[] = "screw"
static

The name for this Joint type.


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