pydrake.multibody.tree

Bindings for MultibodyTree and related components.

class pydrake.multibody.tree.BallRpyJoint

Bases: pydrake.multibody.tree.Joint

This Joint allows two bodies to rotate freely relative to one another. 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 rotate freely with respect to F, while the origins, Mo and Fo, of frames M and F respectively remain coincident. The orientation of M relative to F is parameterized with space x-y-z Euler angles.

Note

This class is templated; see BallRpyJoint_ for the list of instantiations.

__init__(self: pydrake.multibody.tree.BallRpyJoint, name: str, frame_on_parent: pydrake.multibody.tree.Frame, frame_on_child: pydrake.multibody.tree.Frame, damping: float = 0) → None

Constructor to create a ball rpy joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B rotate freely relative to one another. See this class’s documentation for further details on the definition of these frames, get_angles() for an explanation of the angles defining orientation, and get_angular_velocity() for an explanation of the generalized velocities. This constructor signature creates a joint with no joint limits, i.e. the joint position, velocity and acceleration limits are the pair (-∞, ∞). These can be set using the Joint methods set_position_limits(), set_velocity_limits() and set_acceleration_limits(). 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:

Parameter damping:: Viscous damping coefficient, in N⋅m⋅s, used to model losses within the joint. See documentation of default_damping() for details on modelling of the damping torque.

Raises: RuntimeError if damping is negative. –

default_damping(self: pydrake.multibody.tree.BallRpyJoint) → float: Returns this joint’s default damping constant in N⋅m⋅s. The damping torque (in N⋅m) is modeled as τ = -damping⋅ω, i.e. opposing motion, with ω the angular velocity of frame M in F (see get_angular_velocity()) and τ the torque on child body B (to which M is rigidly attached).

get_angles(self: pydrake.multibody.tree.BallRpyJoint, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]

Gets the rotation angles of this joint from context.

The orientation R_FM of the child frame M in parent frame F is parameterized with space x-y-z Euler angles (also known as extrinsic angles). That is, the angles θr, θp, θy, correspond to a sequence of rotations about the x̂, ŷ, ẑ axes of parent frame F, respectively. Mathematically, rotation R_FM is given in terms of angles θr, θp, θy by:

Click to expand C++ code...

R_FM(q) = Rz(θy) * Ry(θp) * Rx(θr)

where Rx(θ), Ry(θ) and Rz(θ) correspond to the elemental rotations in amount of θ about the x, y and z axes respectively. Zero θr, θp, θy angles corresponds to frames F and M being coincident. Angles θr, θp, θy are defined to be positive according to the right-hand-rule with the thumb aligned in the direction of their respective axes.

Note

Space x-y-z angles (extrinsic) are equivalent to Body z-y-x angles (intrinsic).

Note

This particular choice of angles θr, θp, θy for this joint are many times referred to as the roll, pitch and yaw angles by many dynamicists. They are also known as the Tait-Bryan angles or Cardan angles.

Parameter context:: The context of the model this joint belongs to.

Returns: The angle coordinates of this joint stored in the context ordered as θr, θp, θy.

get_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]

Retrieves from context the angular velocity w_FM of the child frame M in the parent frame F, expressed in F.

Parameter context:: The context of the model this joint belongs to.
Returns w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

get_default_angles(self: pydrake.multibody.tree.BallRpyJoint) → numpy.ndarray[numpy.float64[3, 1]]

Gets the default angles for this joint. Wrapper for the more general Joint::default_positions().

Returns: The default angles of this stored in default_positions_

kTypeName = 'ball_rpy'

set_angles(self: pydrake.multibody.tree.BallRpyJoint, context: pydrake.systems.framework.Context, angles: numpy.ndarray[numpy.float64[3, 1]]) → pydrake.multibody.tree.BallRpyJoint

Sets the context so that the generalized coordinates corresponding to the rotation angles of this joint equals angles.

Parameter context:: The context of the model this joint belongs to.
Parameter angles:: The desired angles in radians to be stored in context ordered as θr, θp, θy. See get_angles() for details.

Returns: a constant reference to this joint.

set_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint, context: pydrake.systems.framework.Context, w_FM: numpy.ndarray[numpy.float64[3, 1]]) → pydrake.multibody.tree.BallRpyJoint

Sets in context the state for this joint so that the angular velocity of the child frame M in the parent frame F is w_FM.

Parameter context:: The context of the model this joint belongs to.
Parameter w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

Returns: a constant reference to this joint.

set_default_angles(self: pydrake.multibody.tree.BallRpyJoint, angles: numpy.ndarray[numpy.float64[3, 1]]) → None

Sets the default angles of this joint.

Parameter angles:: The desired default angles of the joint

set_random_angles_distribution(self: pydrake.multibody.tree.BallRpyJoint, angles: numpy.ndarray[object[3, 1]]) → None: Sets the random distribution that angles of this joint will be randomly sampled from. See get_angles() for details on the angle representation.

template pydrake.multibody.tree.BallRpyJoint_: Instantiations: BallRpyJoint_[float], BallRpyJoint_[AutoDiffXd], BallRpyJoint_[Expression]

class pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd]

Bases: pydrake.multibody.tree.Joint_[AutoDiffXd]

This Joint allows two bodies to rotate freely relative to one another. 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 rotate freely with respect to F, while the origins, Mo and Fo, of frames M and F respectively remain coincident. The orientation of M relative to F is parameterized with space x-y-z Euler angles.

__init__(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], name: str, frame_on_parent: pydrake.multibody.tree.Frame_[AutoDiffXd], frame_on_child: pydrake.multibody.tree.Frame_[AutoDiffXd], damping: float = 0) → None

Constructor to create a ball rpy joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B rotate freely relative to one another. See this class’s documentation for further details on the definition of these frames, get_angles() for an explanation of the angles defining orientation, and get_angular_velocity() for an explanation of the generalized velocities. This constructor signature creates a joint with no joint limits, i.e. the joint position, velocity and acceleration limits are the pair (-∞, ∞). These can be set using the Joint methods set_position_limits(), set_velocity_limits() and set_acceleration_limits(). 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:

Parameter damping:: Viscous damping coefficient, in N⋅m⋅s, used to model losses within the joint. See documentation of default_damping() for details on modelling of the damping torque.

Raises: RuntimeError if damping is negative. –

default_damping(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd]) → float: Returns this joint’s default damping constant in N⋅m⋅s. The damping torque (in N⋅m) is modeled as τ = -damping⋅ω, i.e. opposing motion, with ω the angular velocity of frame M in F (see get_angular_velocity()) and τ the torque on child body B (to which M is rigidly attached).

get_angles(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → numpy.ndarray[object[3, 1]]

Gets the rotation angles of this joint from context.

The orientation R_FM of the child frame M in parent frame F is parameterized with space x-y-z Euler angles (also known as extrinsic angles). That is, the angles θr, θp, θy, correspond to a sequence of rotations about the x̂, ŷ, ẑ axes of parent frame F, respectively. Mathematically, rotation R_FM is given in terms of angles θr, θp, θy by:

Click to expand C++ code...

R_FM(q) = Rz(θy) * Ry(θp) * Rx(θr)

where Rx(θ), Ry(θ) and Rz(θ) correspond to the elemental rotations in amount of θ about the x, y and z axes respectively. Zero θr, θp, θy angles corresponds to frames F and M being coincident. Angles θr, θp, θy are defined to be positive according to the right-hand-rule with the thumb aligned in the direction of their respective axes.

Note

Space x-y-z angles (extrinsic) are equivalent to Body z-y-x angles (intrinsic).

Note

This particular choice of angles θr, θp, θy for this joint are many times referred to as the roll, pitch and yaw angles by many dynamicists. They are also known as the Tait-Bryan angles or Cardan angles.

Parameter context:: The context of the model this joint belongs to.

Returns: The angle coordinates of this joint stored in the context ordered as θr, θp, θy.

get_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → numpy.ndarray[object[3, 1]]

Retrieves from context the angular velocity w_FM of the child frame M in the parent frame F, expressed in F.

Parameter context:: The context of the model this joint belongs to.
Returns w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

get_default_angles(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[3, 1]]

Gets the default angles for this joint. Wrapper for the more general Joint::default_positions().

Returns: The default angles of this stored in default_positions_

kTypeName = 'ball_rpy'

set_angles(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], angles: numpy.ndarray[object[3, 1]]) → pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd]

Sets the context so that the generalized coordinates corresponding to the rotation angles of this joint equals angles.

Parameter context:: The context of the model this joint belongs to.
Parameter angles:: The desired angles in radians to be stored in context ordered as θr, θp, θy. See get_angles() for details.

Returns: a constant reference to this joint.

set_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], w_FM: numpy.ndarray[object[3, 1]]) → pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd]

Sets in context the state for this joint so that the angular velocity of the child frame M in the parent frame F is w_FM.

Parameter context:: The context of the model this joint belongs to.
Parameter w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

Returns: a constant reference to this joint.

set_default_angles(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], angles: numpy.ndarray[numpy.float64[3, 1]]) → None

Sets the default angles of this joint.

Parameter angles:: The desired default angles of the joint

set_random_angles_distribution(self: pydrake.multibody.tree.BallRpyJoint_[AutoDiffXd], angles: numpy.ndarray[object[3, 1]]) → None: Sets the random distribution that angles of this joint will be randomly sampled from. See get_angles() for details on the angle representation.

class pydrake.multibody.tree.BallRpyJoint_[Expression]

Bases: pydrake.multibody.tree.Joint_[Expression]

This Joint allows two bodies to rotate freely relative to one another. 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 rotate freely with respect to F, while the origins, Mo and Fo, of frames M and F respectively remain coincident. The orientation of M relative to F is parameterized with space x-y-z Euler angles.

__init__(self: pydrake.multibody.tree.BallRpyJoint_[Expression], name: str, frame_on_parent: pydrake.multibody.tree.Frame_[Expression], frame_on_child: pydrake.multibody.tree.Frame_[Expression], damping: float = 0) → None

Constructor to create a ball rpy joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B rotate freely relative to one another. See this class’s documentation for further details on the definition of these frames, get_angles() for an explanation of the angles defining orientation, and get_angular_velocity() for an explanation of the generalized velocities. This constructor signature creates a joint with no joint limits, i.e. the joint position, velocity and acceleration limits are the pair (-∞, ∞). These can be set using the Joint methods set_position_limits(), set_velocity_limits() and set_acceleration_limits(). 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:

Parameter damping:: Viscous damping coefficient, in N⋅m⋅s, used to model losses within the joint. See documentation of default_damping() for details on modelling of the damping torque.

Raises: RuntimeError if damping is negative. –

default_damping(self: pydrake.multibody.tree.BallRpyJoint_[Expression]) → float: Returns this joint’s default damping constant in N⋅m⋅s. The damping torque (in N⋅m) is modeled as τ = -damping⋅ω, i.e. opposing motion, with ω the angular velocity of frame M in F (see get_angular_velocity()) and τ the torque on child body B (to which M is rigidly attached).

get_angles(self: pydrake.multibody.tree.BallRpyJoint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → numpy.ndarray[object[3, 1]]

Gets the rotation angles of this joint from context.

The orientation R_FM of the child frame M in parent frame F is parameterized with space x-y-z Euler angles (also known as extrinsic angles). That is, the angles θr, θp, θy, correspond to a sequence of rotations about the x̂, ŷ, ẑ axes of parent frame F, respectively. Mathematically, rotation R_FM is given in terms of angles θr, θp, θy by:

Click to expand C++ code...

R_FM(q) = Rz(θy) * Ry(θp) * Rx(θr)

where Rx(θ), Ry(θ) and Rz(θ) correspond to the elemental rotations in amount of θ about the x, y and z axes respectively. Zero θr, θp, θy angles corresponds to frames F and M being coincident. Angles θr, θp, θy are defined to be positive according to the right-hand-rule with the thumb aligned in the direction of their respective axes.

Note

Space x-y-z angles (extrinsic) are equivalent to Body z-y-x angles (intrinsic).

Note

This particular choice of angles θr, θp, θy for this joint are many times referred to as the roll, pitch and yaw angles by many dynamicists. They are also known as the Tait-Bryan angles or Cardan angles.

Parameter context:: The context of the model this joint belongs to.

Returns: The angle coordinates of this joint stored in the context ordered as θr, θp, θy.

get_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → numpy.ndarray[object[3, 1]]

Retrieves from context the angular velocity w_FM of the child frame M in the parent frame F, expressed in F.

Parameter context:: The context of the model this joint belongs to.
Returns w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

get_default_angles(self: pydrake.multibody.tree.BallRpyJoint_[Expression]) → numpy.ndarray[numpy.float64[3, 1]]

Gets the default angles for this joint. Wrapper for the more general Joint::default_positions().

Returns: The default angles of this stored in default_positions_

kTypeName = 'ball_rpy'

set_angles(self: pydrake.multibody.tree.BallRpyJoint_[Expression], context: pydrake.systems.framework.Context_[Expression], angles: numpy.ndarray[object[3, 1]]) → pydrake.multibody.tree.BallRpyJoint_[Expression]

Sets the context so that the generalized coordinates corresponding to the rotation angles of this joint equals angles.

Parameter context:: The context of the model this joint belongs to.
Parameter angles:: The desired angles in radians to be stored in context ordered as θr, θp, θy. See get_angles() for details.

Returns: a constant reference to this joint.

set_angular_velocity(self: pydrake.multibody.tree.BallRpyJoint_[Expression], context: pydrake.systems.framework.Context_[Expression], w_FM: numpy.ndarray[object[3, 1]]) → pydrake.multibody.tree.BallRpyJoint_[Expression]

Sets in context the state for this joint so that the angular velocity of the child frame M in the parent frame F is w_FM.

Parameter context:: The context of the model this joint belongs to.
Parameter w_FM:: A vector in ℝ³ with the angular velocity of the child frame M in the parent frame F, expressed in F. Refer to this class’s documentation for further details and definitions of these frames.

Returns: a constant reference to this joint.

set_default_angles(self: pydrake.multibody.tree.BallRpyJoint_[Expression], angles: numpy.ndarray[numpy.float64[3, 1]]) → None

Sets the default angles of this joint.

Parameter angles:: The desired default angles of the joint

set_random_angles_distribution(self: pydrake.multibody.tree.BallRpyJoint_[Expression], angles: numpy.ndarray[object[3, 1]]) → None: Sets the random distribution that angles of this joint will be randomly sampled from. See get_angles() for details on the angle representation.

pydrake.multibody.tree.Body: alias of pydrake.multibody.tree.RigidBody

template pydrake.multibody.tree.Body_: Instantiations: RigidBody_[float], RigidBody_[AutoDiffXd], RigidBody_[Expression]

class pydrake.multibody.tree.BodyIndex

Type used to identify RigidBodies (a.k.a. Links) by index in a multibody plant. Interchangeable with LinkIndex.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.BodyIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

__init__(self: pydrake.multibody.tree.BodyIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.multibody.tree.BodyIndex) → bool: Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

pydrake.multibody.tree.CalcSpatialInertia(*args, **kwargs)

Overloaded function.

CalcSpatialInertia(shape: pydrake.geometry.Shape, density: float) -> drake::multibody::SpatialInertia<double>

Computes the SpatialInertia of a body made up of a homogeneous material (of given density in kg/m³) uniformly distributed in the volume of the given shape.

The shape is defined in its canonical frame S and the body in frame B. The two frames are coincident and aligned (i.e., X_SB = I).

Most shapes are defined such that their center of mass is coincident with So (and, therefore, Bo). These are the shapes that have symmetry across So along each of the axes Sx, Sy, Sz (e.g., geometry::Box, geometry::Sphere, etc.) For meshes, it depends on how the mesh is defined. For more discussion on the nuances of geometry::Mesh and geometry::Convex calculations CalcSpatialInertia(const geometry::TriangleSurfaceMesh<double>&,double) “see below”.

Returns M_BBo_B:: The spatial inertia of the hypothetical body implied by the given shape.

Raises

RuntimeError if shape is an instance of geometry::HalfSpace or –
geometry::MeshcatCone. –

CalcSpatialInertia(mesh: pydrake.geometry.TriangleSurfaceMesh, density: float) -> drake::multibody::SpatialInertia<double>

Computes the SpatialInertia of a body made up of a homogeneous material (of given density in kg/m³) uniformly distributed in the volume of the given mesh.

The mesh is defined in its canonical frame M and the body in frame B. The two frames are coincident and aligned (i.e., X_MB = I).

For the resultant spatial inertia to be meaningful, the mesh must satisfy certain requirements:

The mesh must fully enclose a volume (no cracks, no open manifolds,

etc.) - All triangles must be “wound” such that their normals point outward (according to the right-hand rule based on vertex winding).

If these requirements are not met, a value will be returned, but its value is meaningless.

pydrake.multibody.tree.default_model_instance() → pydrake.multibody.tree.ModelInstanceIndex: Returns the model instance which contains all tree elements with no explicit model instance specified.

class pydrake.multibody.tree.DoorHinge

Bases: pydrake.multibody.tree.ForceElement

This ForceElement models a revolute DoorHinge joint that could exhibit different force/torque characteristics at different states due to the existence of different type of torques on the joint. This class implements a “christmas tree” accumulation of these different torques in an empirical and unprincipled way. Specifically, different curves are assigned to different torques to mimic their evolution based on the joint state and some prespecified parameters.

Torques considered in this implementation include: * torsional spring torque (τ_ts) – position dependent * catch torque (τ_c) – position dependent * dynamic friction torque (τ_df) – velocity dependent * static friction torque (τ_sf) – velocity dependent * viscous friction torque (τ_vf) – velocity dependent

We then implement two curves to approximate the progression of different torques. A curve s(t, x) = tanh(x/t) uses the tanh function to approximate a step curve ({x<0: -1 ; x>0: 1}) outside of -t < x < t. The curve doublet(t, x) = 2 * s * (1 − s²) is the second derivative of s scaled by -t², which yields a lump at negative x that integrates to -1 and a lump at positive x that integrates to 1. Finally, the total external torque on the hinge joint would be:

τ = τ_ts + τ_c + τ_df + τ_sf + τ_vf.

where τ_ts = -k_ts * (q − qs₀), τ_c = k_c * doublet(qc₀/2, q − qc₀/2)`, τ_df = -k_df * s(k_q̇₀, q̇)`, τ_sf = -k_sf * doublet(k_q̇₀, q̇) and τ_vf = -k_vf * q̇. The door is assumed to be closed at q=0, opening in the positive-q direction. Note that, the sign of the torques depends on two elements: one is the sign of the torque related constants and another one is the sign of the assigned curves. For example, as defined above, the static friction torque τ_sf should be opposite to the direction of the velocity q̇. The catch torque τ_c should be negative when q < qc₀/2 and positive otherwise. This class applies all hinge-originating forces, so it can be used instead of the SDF viscous damping. The users could change the values of these different elements to obtain different characteristics for the DoorHinge joint that the users want to model. A jupyter notebook tool is also provided to help the users visualize the curves and design parameters. Run bazel run //bindings/pydrake/multibody:examples/door_hinge_inspector to bring up the notebook.

To give an example, a common dishwasher door has a frictional torque sufficient for it to rest motionless at any angle, a catch at the top to hold it in place, a dashpot (viscous friction source) to prevent it from swinging too fast, and a spring to counteract some of its mass. Two figures are provided to illustrate the dishwasher DoorHinge torque with the given default parameters. Figure 1 shows the static characteristic of the dishwasher door. At q = 0, there exists a negative catch torque to prevent the door from moving. After that, the torsional spring torque will dominate to compensate part of the door gravity. Figure 2 shows the dynamic feature of the dishwasher door at q = 30 deg. It shows the door can be closed easily since the torque is small when the velocity is negative. However, whenever the door intends to open further, there will be a counter torque to prevent that movement, which therefore keeps the door at rest. Note that, due to the gravity, the dishwasher door will be fully open eventually. This process can be really slow because of the default motion_threshold is set to be very small. You can change the motion_threshold parameter to adjust the time. @image html drake/multibody/tree/images/torque_vs_angle.svg “Figure 1” @image html drake/multibody/tree/images/torque_vs_velocity.svg “Figure 2”

Note

This class is templated; see DoorHinge_ for the list of instantiations.

__init__(self: pydrake.multibody.tree.DoorHinge, joint: pydrake.multibody.tree.RevoluteJoint, config: pydrake.multibody.tree.DoorHingeConfig) → None: Constructs a hinge force element with parameters config applied to the specified joint. It will throw an exception if the DoorHingeConfig is invalid.

CalcHingeFrictionalTorque(self: pydrake.multibody.tree.DoorHinge, angular_rate: float) → float: Calculates the total frictional torque with the given angular_rate and the internal DoorHingeConfig.

CalcHingeSpringTorque(self: pydrake.multibody.tree.DoorHinge, angle: float) → float: Calculate the total spring related torque with the given angle and the internal DoorHingeConfig.

CalcHingeTorque(self: pydrake.multibody.tree.DoorHinge, angle: float, angular_rate: float) → float: Calculate the total torque with the given angle and angular_rate and the internal DoorHingeConfig.

config(self: pydrake.multibody.tree.DoorHinge) → pydrake.multibody.tree.DoorHingeConfig

joint(self: pydrake.multibody.tree.DoorHinge) → pydrake.multibody.tree.RevoluteJoint

template pydrake.multibody.tree.DoorHinge_: Instantiations: DoorHinge_[float], DoorHinge_[AutoDiffXd], DoorHinge_[Expression]

class pydrake.multibody.tree.DoorHinge_[AutoDiffXd]

Bases: pydrake.multibody.tree.ForceElement_[AutoDiffXd]

This ForceElement models a revolute DoorHinge joint that could exhibit different force/torque characteristics at different states due to the existence of different type of torques on the joint. This class implements a “christmas tree” accumulation of these different torques in an empirical and unprincipled way. Specifically, different curves are assigned to different torques to mimic their evolution based on the joint state and some prespecified parameters.

Torques considered in this implementation include: * torsional spring torque (τ_ts) – position dependent * catch torque (τ_c) – position dependent * dynamic friction torque (τ_df) – velocity dependent * static friction torque (τ_sf) – velocity dependent * viscous friction torque (τ_vf) – velocity dependent

We then implement two curves to approximate the progression of different torques. A curve s(t, x) = tanh(x/t) uses the tanh function to approximate a step curve ({x<0: -1 ; x>0: 1}) outside of -t < x < t. The curve doublet(t, x) = 2 * s * (1 − s²) is the second derivative of s scaled by -t², which yields a lump at negative x that integrates to -1 and a lump at positive x that integrates to 1. Finally, the total external torque on the hinge joint would be:

τ = τ_ts + τ_c + τ_df + τ_sf + τ_vf.

where τ_ts = -k_ts * (q − qs₀), τ_c = k_c * doublet(qc₀/2, q − qc₀/2)`, τ_df = -k_df * s(k_q̇₀, q̇)`, τ_sf = -k_sf * doublet(k_q̇₀, q̇) and τ_vf = -k_vf * q̇. The door is assumed to be closed at q=0, opening in the positive-q direction. Note that, the sign of the torques depends on two elements: one is the sign of the torque related constants and another one is the sign of the assigned curves. For example, as defined above, the static friction torque τ_sf should be opposite to the direction of the velocity q̇. The catch torque τ_c should be negative when q < qc₀/2 and positive otherwise. This class applies all hinge-originating forces, so it can be used instead of the SDF viscous damping. The users could change the values of these different elements to obtain different characteristics for the DoorHinge joint that the users want to model. A jupyter notebook tool is also provided to help the users visualize the curves and design parameters. Run bazel run //bindings/pydrake/multibody:examples/door_hinge_inspector to bring up the notebook.

To give an example, a common dishwasher door has a frictional torque sufficient for it to rest motionless at any angle, a catch at the top to hold it in place, a dashpot (viscous friction source) to prevent it from swinging too fast, and a spring to counteract some of its mass. Two figures are provided to illustrate the dishwasher DoorHinge torque with the given default parameters. Figure 1 shows the static characteristic of the dishwasher door. At q = 0, there exists a negative catch torque to prevent the door from moving. After that, the torsional spring torque will dominate to compensate part of the door gravity. Figure 2 shows the dynamic feature of the dishwasher door at q = 30 deg. It shows the door can be closed easily since the torque is small when the velocity is negative. However, whenever the door intends to open further, there will be a counter torque to prevent that movement, which therefore keeps the door at rest. Note that, due to the gravity, the dishwasher door will be fully open eventually. This process can be really slow because of the default motion_threshold is set to be very small. You can change the motion_threshold parameter to adjust the time. @image html drake/multibody/tree/images/torque_vs_angle.svg “Figure 1” @image html drake/multibody/tree/images/torque_vs_velocity.svg “Figure 2”

__init__(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd], joint: pydrake.multibody.tree.RevoluteJoint_[AutoDiffXd], config: pydrake.multibody.tree.DoorHingeConfig) → None: Constructs a hinge force element with parameters config applied to the specified joint. It will throw an exception if the DoorHingeConfig is invalid.

CalcHingeFrictionalTorque(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd], angular_rate: pydrake.autodiffutils.AutoDiffXd) → pydrake.autodiffutils.AutoDiffXd: Calculates the total frictional torque with the given angular_rate and the internal DoorHingeConfig.

CalcHingeSpringTorque(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd], angle: pydrake.autodiffutils.AutoDiffXd) → pydrake.autodiffutils.AutoDiffXd: Calculate the total spring related torque with the given angle and the internal DoorHingeConfig.

CalcHingeTorque(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd], angle: pydrake.autodiffutils.AutoDiffXd, angular_rate: pydrake.autodiffutils.AutoDiffXd) → pydrake.autodiffutils.AutoDiffXd: Calculate the total torque with the given angle and angular_rate and the internal DoorHingeConfig.

config(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd]) → pydrake.multibody.tree.DoorHingeConfig

joint(self: pydrake.multibody.tree.DoorHinge_[AutoDiffXd]) → pydrake.multibody.tree.RevoluteJoint_[AutoDiffXd]

class pydrake.multibody.tree.DoorHinge_[Expression]

Bases: pydrake.multibody.tree.ForceElement_[Expression]

This ForceElement models a revolute DoorHinge joint that could exhibit different force/torque characteristics at different states due to the existence of different type of torques on the joint. This class implements a “christmas tree” accumulation of these different torques in an empirical and unprincipled way. Specifically, different curves are assigned to different torques to mimic their evolution based on the joint state and some prespecified parameters.

Torques considered in this implementation include: * torsional spring torque (τ_ts) – position dependent * catch torque (τ_c) – position dependent * dynamic friction torque (τ_df) – velocity dependent * static friction torque (τ_sf) – velocity dependent * viscous friction torque (τ_vf) – velocity dependent

We then implement two curves to approximate the progression of different torques. A curve s(t, x) = tanh(x/t) uses the tanh function to approximate a step curve ({x<0: -1 ; x>0: 1}) outside of -t < x < t. The curve doublet(t, x) = 2 * s * (1 − s²) is the second derivative of s scaled by -t², which yields a lump at negative x that integrates to -1 and a lump at positive x that integrates to 1. Finally, the total external torque on the hinge joint would be:

τ = τ_ts + τ_c + τ_df + τ_sf + τ_vf.

where τ_ts = -k_ts * (q − qs₀), τ_c = k_c * doublet(qc₀/2, q − qc₀/2)`, τ_df = -k_df * s(k_q̇₀, q̇)`, τ_sf = -k_sf * doublet(k_q̇₀, q̇) and τ_vf = -k_vf * q̇. The door is assumed to be closed at q=0, opening in the positive-q direction. Note that, the sign of the torques depends on two elements: one is the sign of the torque related constants and another one is the sign of the assigned curves. For example, as defined above, the static friction torque τ_sf should be opposite to the direction of the velocity q̇. The catch torque τ_c should be negative when q < qc₀/2 and positive otherwise. This class applies all hinge-originating forces, so it can be used instead of the SDF viscous damping. The users could change the values of these different elements to obtain different characteristics for the DoorHinge joint that the users want to model. A jupyter notebook tool is also provided to help the users visualize the curves and design parameters. Run bazel run //bindings/pydrake/multibody:examples/door_hinge_inspector to bring up the notebook.

To give an example, a common dishwasher door has a frictional torque sufficient for it to rest motionless at any angle, a catch at the top to hold it in place, a dashpot (viscous friction source) to prevent it from swinging too fast, and a spring to counteract some of its mass. Two figures are provided to illustrate the dishwasher DoorHinge torque with the given default parameters. Figure 1 shows the static characteristic of the dishwasher door. At q = 0, there exists a negative catch torque to prevent the door from moving. After that, the torsional spring torque will dominate to compensate part of the door gravity. Figure 2 shows the dynamic feature of the dishwasher door at q = 30 deg. It shows the door can be closed easily since the torque is small when the velocity is negative. However, whenever the door intends to open further, there will be a counter torque to prevent that movement, which therefore keeps the door at rest. Note that, due to the gravity, the dishwasher door will be fully open eventually. This process can be really slow because of the default motion_threshold is set to be very small. You can change the motion_threshold parameter to adjust the time. @image html drake/multibody/tree/images/torque_vs_angle.svg “Figure 1” @image html drake/multibody/tree/images/torque_vs_velocity.svg “Figure 2”

__init__(self: pydrake.multibody.tree.DoorHinge_[Expression], joint: pydrake.multibody.tree.RevoluteJoint_[Expression], config: pydrake.multibody.tree.DoorHingeConfig) → None: Constructs a hinge force element with parameters config applied to the specified joint. It will throw an exception if the DoorHingeConfig is invalid.

CalcHingeFrictionalTorque(self: pydrake.multibody.tree.DoorHinge_[Expression], angular_rate: pydrake.symbolic.Expression) → pydrake.symbolic.Expression: Calculates the total frictional torque with the given angular_rate and the internal DoorHingeConfig.

CalcHingeSpringTorque(self: pydrake.multibody.tree.DoorHinge_[Expression], angle: pydrake.symbolic.Expression) → pydrake.symbolic.Expression: Calculate the total spring related torque with the given angle and the internal DoorHingeConfig.

CalcHingeTorque(self: pydrake.multibody.tree.DoorHinge_[Expression], angle: pydrake.symbolic.Expression, angular_rate: pydrake.symbolic.Expression) → pydrake.symbolic.Expression: Calculate the total torque with the given angle and angular_rate and the internal DoorHingeConfig.

config(self: pydrake.multibody.tree.DoorHinge_[Expression]) → pydrake.multibody.tree.DoorHingeConfig

joint(self: pydrake.multibody.tree.DoorHinge_[Expression]) → pydrake.multibody.tree.RevoluteJoint_[Expression]

class pydrake.multibody.tree.DoorHingeConfig

Configuration structure for the DoorHinge.

__init__(self: pydrake.multibody.tree.DoorHingeConfig, **kwargs) → None: Initialize to empirically reasonable values measured approximately by banging on the door of a dishwasher with a force gauge.

property catch_torque: k_c maximum catch torque applied over catch_width [Nm]. It should be non-negative.

property catch_width: qc₀ measured from closed (q=0) position [radian]. It should be non-negative.

property dynamic_friction_torque: k_df maximum dynamic friction torque measured opposite direction of motion [Nm]. It should be non-negative.

property motion_threshold: k_q̇₀ motion threshold to start to apply friction torques [rad/s]. It should be non-negative. Realistic frictional force is very stiff, reversing entirely over zero change in position or velocity, which kills integrators. We approximate it with a continuous function. This constant [rad/s] is the scaling factor on that function – very approximately the rad/s at which half of the full frictional force is applied. This number is nonphysical; make it small but not so small that the simulation vibrates or explodes.

property spring_constant: k_ts torsional spring constant measured toward the spring zero angle [Nm/rad]. It should be non-negative.

property spring_zero_angle_rad: qs₀ measured outward from the closed position [radian].

property static_friction_torque: k_sf maximum static friction measured opposite direction of motion [Nm]. It should be non-negative.

property viscous_friction: k_vf viscous friction measured opposite direction of motion [Nm]. It should be non-negative.

class pydrake.multibody.tree.FixedOffsetFrame

Bases: pydrake.multibody.tree.Frame

%FixedOffsetFrame represents a material frame F whose pose is fixed with respect to a parent material frame P. The pose offset is given by a spatial transform X_PF, which is constant after construction. For instance, we could rigidly attach a frame F to move with a rigid body B at a fixed pose X_BF, where B is the RigidBodyFrame associated with body B. Thus, the World frame pose X_WF of a FixedOffsetFrame F depends only on the World frame pose X_WP of its parent P, and the constant pose X_PF, with X_WF=X_WP*X_PF.

For more information about spatial transforms, see multibody_spatial_pose.

Note

This class is templated; see FixedOffsetFrame_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.FixedOffsetFrame, name: str, P: pydrake.multibody.tree.Frame, X_PF: pydrake.math.RigidTransform, model_instance: Optional[pydrake.multibody.tree.ModelInstanceIndex] = None) -> None

Creates a material Frame F whose pose is fixed with respect to its parent material Frame P. The pose is given by a spatial transform X_PF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter P:: The frame to which this frame is attached with a fixed pose.
Parameter X_PF:: The default transform giving the pose of F in P, therefore only the value (as a RigidTransform<double>) is provided.
Parameter model_instance:: The model instance to which this frame belongs to. If unspecified, will use P.body().model_instance().

__init__(self: pydrake.multibody.tree.FixedOffsetFrame, name: str, bodyB: drake::multibody::RigidBody<double>, X_BF: pydrake.math.RigidTransform) -> None

Creates a material Frame F whose pose is fixed with respect to the RigidBodyFrame B of the given RigidBody, which serves as F’s parent frame. The pose is given by a RigidTransform X_BF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter bodyB:: The body whose RigidBodyFrame B is to be F’s parent frame.
Parameter X_BF:: The transform giving the pose of F in B.

GetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame, context: pydrake.systems.framework.Context) → pydrake.math.RigidTransform

Returns the rigid transform X_PF that characterizes this frame F’s pose in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.

SetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame, context: pydrake.systems.framework.Context, X_PF: pydrake.math.RigidTransform) → None

Sets the pose of this frame F in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.
Parameter X_PF:: Rigid transform that characterizes this frame F’s pose (orientation and position) in its parent frame P.

template pydrake.multibody.tree.FixedOffsetFrame_: Instantiations: FixedOffsetFrame_[float], FixedOffsetFrame_[AutoDiffXd], FixedOffsetFrame_[Expression]

class pydrake.multibody.tree.FixedOffsetFrame_[AutoDiffXd]

Bases: pydrake.multibody.tree.Frame_[AutoDiffXd]

%FixedOffsetFrame represents a material frame F whose pose is fixed with respect to a parent material frame P. The pose offset is given by a spatial transform X_PF, which is constant after construction. For instance, we could rigidly attach a frame F to move with a rigid body B at a fixed pose X_BF, where B is the RigidBodyFrame associated with body B. Thus, the World frame pose X_WF of a FixedOffsetFrame F depends only on the World frame pose X_WP of its parent P, and the constant pose X_PF, with X_WF=X_WP*X_PF.

For more information about spatial transforms, see multibody_spatial_pose.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.FixedOffsetFrame_[AutoDiffXd], name: str, P: pydrake.multibody.tree.Frame_[AutoDiffXd], X_PF: pydrake.math.RigidTransform, model_instance: Optional[pydrake.multibody.tree.ModelInstanceIndex] = None) -> None

Creates a material Frame F whose pose is fixed with respect to its parent material Frame P. The pose is given by a spatial transform X_PF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter P:: The frame to which this frame is attached with a fixed pose.
Parameter X_PF:: The default transform giving the pose of F in P, therefore only the value (as a RigidTransform<double>) is provided.
Parameter model_instance:: The model instance to which this frame belongs to. If unspecified, will use P.body().model_instance().

__init__(self: pydrake.multibody.tree.FixedOffsetFrame_[AutoDiffXd], name: str, bodyB: drake::multibody::RigidBody<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >, X_BF: pydrake.math.RigidTransform) -> None

Creates a material Frame F whose pose is fixed with respect to the RigidBodyFrame B of the given RigidBody, which serves as F’s parent frame. The pose is given by a RigidTransform X_BF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter bodyB:: The body whose RigidBodyFrame B is to be F’s parent frame.
Parameter X_BF:: The transform giving the pose of F in B.

GetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]

Returns the rigid transform X_PF that characterizes this frame F’s pose in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.

SetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], X_PF: pydrake.math.RigidTransform_[AutoDiffXd]) → None

Sets the pose of this frame F in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.
Parameter X_PF:: Rigid transform that characterizes this frame F’s pose (orientation and position) in its parent frame P.

class pydrake.multibody.tree.FixedOffsetFrame_[Expression]

Bases: pydrake.multibody.tree.Frame_[Expression]

%FixedOffsetFrame represents a material frame F whose pose is fixed with respect to a parent material frame P. The pose offset is given by a spatial transform X_PF, which is constant after construction. For instance, we could rigidly attach a frame F to move with a rigid body B at a fixed pose X_BF, where B is the RigidBodyFrame associated with body B. Thus, the World frame pose X_WF of a FixedOffsetFrame F depends only on the World frame pose X_WP of its parent P, and the constant pose X_PF, with X_WF=X_WP*X_PF.

For more information about spatial transforms, see multibody_spatial_pose.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.FixedOffsetFrame_[Expression], name: str, P: pydrake.multibody.tree.Frame_[Expression], X_PF: pydrake.math.RigidTransform, model_instance: Optional[pydrake.multibody.tree.ModelInstanceIndex] = None) -> None

Creates a material Frame F whose pose is fixed with respect to its parent material Frame P. The pose is given by a spatial transform X_PF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter P:: The frame to which this frame is attached with a fixed pose.
Parameter X_PF:: The default transform giving the pose of F in P, therefore only the value (as a RigidTransform<double>) is provided.
Parameter model_instance:: The model instance to which this frame belongs to. If unspecified, will use P.body().model_instance().

__init__(self: pydrake.multibody.tree.FixedOffsetFrame_[Expression], name: str, bodyB: drake::multibody::RigidBody<drake::symbolic::Expression>, X_BF: pydrake.math.RigidTransform) -> None

Creates a material Frame F whose pose is fixed with respect to the RigidBodyFrame B of the given RigidBody, which serves as F’s parent frame. The pose is given by a RigidTransform X_BF; see class documentation for more information.

Parameter name:: The name of this frame. Cannot be empty.
Parameter bodyB:: The body whose RigidBodyFrame B is to be F’s parent frame.
Parameter X_BF:: The transform giving the pose of F in B.

GetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.math.RigidTransform_[Expression]

Returns the rigid transform X_PF that characterizes this frame F’s pose in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.

SetPoseInParentFrame(self: pydrake.multibody.tree.FixedOffsetFrame_[Expression], context: pydrake.systems.framework.Context_[Expression], X_PF: pydrake.math.RigidTransform_[Expression]) → None

Sets the pose of this frame F in its parent frame P.

Parameter context:: of the multibody plant associated with this frame.
Parameter X_PF:: Rigid transform that characterizes this frame F’s pose (orientation and position) in its parent frame P.

class pydrake.multibody.tree.ForceElement

A ForceElement allows modeling state and time dependent forces in a MultibodyTree model. Examples of such forces are springs, dampers, drag and gravity. Forces that depend on accelerations such as virtual mass cannot be modeled with a ForceElement. This abstract class provides an API that all force elements subclasses must implement in order to be fully defined. These are:

CalcAndAddForceContribution(): computes the force contribution of a force element in a MultibodyTree model.
CalcPotentialEnergy(): computes a force element potential energy contribution.
CalcConservativePower(): computes the power generated by conservative forces.
CalcNonConservativePower(): computes the power dissipated by non-conservative forces.

Note

This class is templated; see ForceElement_ for the list of instantiations.

__init__(*args, **kwargs)

GetParentPlant(self: pydrake.multibody.tree.ForceElement) → drake::multibody::MultibodyPlant<double>

index(self: pydrake.multibody.tree.ForceElement) → pydrake.multibody.tree.ForceElementIndex

model_instance(self: pydrake.multibody.tree.ForceElement) → pydrake.multibody.tree.ModelInstanceIndex

template pydrake.multibody.tree.ForceElement_: Instantiations: ForceElement_[float], ForceElement_[AutoDiffXd], ForceElement_[Expression]

class pydrake.multibody.tree.ForceElement_[AutoDiffXd]

A ForceElement allows modeling state and time dependent forces in a MultibodyTree model. Examples of such forces are springs, dampers, drag and gravity. Forces that depend on accelerations such as virtual mass cannot be modeled with a ForceElement. This abstract class provides an API that all force elements subclasses must implement in order to be fully defined. These are:

CalcAndAddForceContribution(): computes the force contribution of a force element in a MultibodyTree model.
CalcPotentialEnergy(): computes a force element potential energy contribution.
CalcConservativePower(): computes the power generated by conservative forces.
CalcNonConservativePower(): computes the power dissipated by non-conservative forces.

__init__(*args, **kwargs)

GetParentPlant(self: pydrake.multibody.tree.ForceElement_[AutoDiffXd]) → drake::multibody::MultibodyPlant<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

index(self: pydrake.multibody.tree.ForceElement_[AutoDiffXd]) → pydrake.multibody.tree.ForceElementIndex

model_instance(self: pydrake.multibody.tree.ForceElement_[AutoDiffXd]) → pydrake.multibody.tree.ModelInstanceIndex

class pydrake.multibody.tree.ForceElement_[Expression]

A ForceElement allows modeling state and time dependent forces in a MultibodyTree model. Examples of such forces are springs, dampers, drag and gravity. Forces that depend on accelerations such as virtual mass cannot be modeled with a ForceElement. This abstract class provides an API that all force elements subclasses must implement in order to be fully defined. These are:

CalcAndAddForceContribution(): computes the force contribution of a force element in a MultibodyTree model.
CalcPotentialEnergy(): computes a force element potential energy contribution.
CalcConservativePower(): computes the power generated by conservative forces.
CalcNonConservativePower(): computes the power dissipated by non-conservative forces.

__init__(*args, **kwargs)

GetParentPlant(self: pydrake.multibody.tree.ForceElement_[Expression]) → drake::multibody::MultibodyPlant<drake::symbolic::Expression>

index(self: pydrake.multibody.tree.ForceElement_[Expression]) → pydrake.multibody.tree.ForceElementIndex

model_instance(self: pydrake.multibody.tree.ForceElement_[Expression]) → pydrake.multibody.tree.ModelInstanceIndex

class pydrake.multibody.tree.ForceElementIndex

Type used to identify force elements by index within a multibody plant.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.ForceElementIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

__init__(self: pydrake.multibody.tree.ForceElementIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.multibody.tree.ForceElementIndex) → bool: Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.multibody.tree.Frame

%Frame is an abstract class representing a material frame (also called a physical frame) of its underlying RigidBody. The Frame’s origin is a material point of its RigidBody, and its axes have fixed directions in that body. A Frame’s pose (position and orientation) with respect to its RigidBodyFrame may be parameterized, but is fixed (not time or state dependent) once parameters have been set.

An important characteristic of a Frame is that forces or torques applied to a Frame are applied to the Frame’s underlying RigidBody. Force-producing elements like joints, actuators, and constraints usually employ two Frames, with one Frame connected to one body and the other connected to a different body. Every Frame F can report the RigidBody B to which it is attached and its pose X_BF with respect to B’s RigidBodyFrame.

A Frame’s pose in World (or relative to other frames) is always calculated starting with its pose relative to its underlying RigidBodyFrame. Subclasses derived from Frame differ in how kinematic calculations are performed. For example, the angular velocity of a FixedOffsetFrame or RigidBodyFrame is identical to the angular velocity of its underlying body, whereas the translational velocity of a FixedOffsetFrame differs from that of a RigidBodyFrame.

Frame provides methods for obtaining its current orientation, position, motion, etc. from a Context passed to those methods.

Note

This class is templated; see Frame_ for the list of instantiations.

__init__(*args, **kwargs)

body(self: pydrake.multibody.tree.Frame) → drake::multibody::RigidBody<double>: Returns a const reference to the body associated to this Frame.

CalcAngularVelocity(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, measured_in_frame: pydrake.multibody.tree.Frame, expressed_in_frame: pydrake.multibody.tree.Frame) → numpy.ndarray[numpy.float64[3, 1]]

Calculates this frame F’s angular velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M (the frame in which this angular velocity is to be measured).
Parameter expressed_in_frame:: which is frame E (the frame in which the returned angular velocity is to be expressed).

Returns: ω_MF_E, this frame F’s angular velocity ω measured in frame M, expressed in frame E.

See also

EvalAngularVelocityInWorld() to evaluate ω_WF_W (this frame F’s angular velocity ω measured and expressed in the world frame W).

CalcOffsetPoseInBody(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, X_FQ: pydrake.math.RigidTransform) → pydrake.math.RigidTransform: Given the offset pose X_FQ of a frame Q in this frame F, this method computes the pose X_BQ of frame Q in the body frame B to which this frame is attached. In other words, if the pose of this frame F in the body frame B is X_BF, this method computes the pose X_BQ of frame Q in the body frame B as X_BQ = X_BF * X_FQ. In particular, if this **is**` the body frame B, i.e. X_BF is the identity transformation, this method directly returns X_FQ. Specific frame subclasses can override this method to provide faster implementations if needed.

CalcOffsetRotationMatrixInBody(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, R_FQ: pydrake.math.RotationMatrix) → pydrake.math.RotationMatrix

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

CalcPose(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, frame_M: pydrake.multibody.tree.Frame) → pydrake.math.RigidTransform: Computes and returns the pose X_MF of this frame F in measured in frame_M as a function of the state of the model stored in context.

See also

CalcPoseInWorld().

CalcPoseInBodyFrame(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.math.RigidTransform: Returns the pose X_BF of this frame F in the body frame B associated with this frame. In particular, if this is the body frame B, this method directly returns the identity transformation. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcPoseInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.math.RigidTransform: Computes and returns the pose X_WF of this frame F in the world frame W as a function of the state of the model stored in context.

Note

RigidBody::EvalPoseInWorld() provides a more efficient way to obtain the pose for a body frame.

CalcRelativeSpatialAcceleration(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, other_frame: pydrake.multibody.tree.Frame, measured_in_frame: pydrake.multibody.tree.Frame, expressed_in_frame: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialAcceleration

Calculates this frame C’s spatial acceleration relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_M_BC_E = A_MC_E - A_MB_E, frame C’s spatial acceleration relative to frame B, measured in frame M, expressed in frame E.

In general, A_M_BC = DtW(V_M_BC), the time-derivative in frame M of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_MC_E - α_MB_E = DtM(ω_BC)_E. Note: For 3D analysis, DtM(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_M_BoCo_E (Co’s translational acceleration relative to Bo, measured in frame M, expressed in frame E).

Click to expand C++ code...

α_MC_E - α_MB_E = DtM(ω_MC)_E - DtM(ω_MB)_E = DtM(ω_BC)_E
 a_M_BoCo_E = a_MCo_E - a_MBo_E = DtM(v_MCo) - DtM(v_MBo) = Dt²M(p_BoCo)_E

where Dt²M(p_BoCo)_E is the 2ⁿᵈ time-derivative in frame M of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame E.

Note

The calculation of the 2ⁿᵈ time-derivative of the distance between Bo and Co can be done with relative translational acceleration, but this calculation does not depend on the measured-in-frame, hence in this case, consider CalcRelativeSpatialAccelerationInWorld() since it is faster.

See also

CalcSpatialAccelerationInWorld(), CalcSpatialAcceleration(), and CalcRelativeSpatialAccelerationInWorld().

CalcRelativeSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, other_frame: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialAcceleration

Calculates this frame C’s spatial acceleration relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: A_W_BC_W = A_WC_W - A_WB_W, frame C’s spatial acceleration relative to frame B, measured and expressed in the world frame W.

In general, A_W_BC = DtW(V_W_BC), the time-derivative in the world frame W of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_WC_W - α_WB_W = DtW(ω_BC)_W. For 3D analysis, DtW(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_W_BoCo_W (Co’s translational acceleration relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

α_WC_W - α_WB_W = DtW(ω_WC)_W - DtW(ω_WB)_W = DtW(ω_BC)_W
 a_W_BoCo_W = a_WCo_W - a_WBo_W = DtW(v_WCo) - DtW(v_WBo) = Dt²W(p_BoCo)_W

where Dt²W(p_BoCo)_W is the 2ⁿᵈ time-derivative in frame W of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame W.

Note

The method CalcSpatialAccelerationInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialAccelerationInWorld(), CalcRelativeSpatialAcceleration().

CalcRelativeSpatialVelocity(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, other_frame: pydrake.multibody.tree.Frame, measured_in_frame: pydrake.multibody.tree.Frame, expressed_in_frame: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialVelocity

Calculates this frame C’s spatial velocity relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: V_M_BC_E = V_MC_E - V_MB_E, frame C’s spatial velocity relative to frame B, measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_BC_E (C’s angular velocity measured in B and expressed in E). The translational part is v_M_BoCo_E (Co’s translational velocity relative to Bo, measured in M, and expressed in E).

Click to expand C++ code...

ω_BC_E = ω_MC_E - ω_MB_E
 v_M_BoCo_E = v_MCo_E - v_MBo_E = DtM(p_BoCo)

where DtM(p_BoCo) is the time-derivative in frame M of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame E.

Note

The method CalcSpatialVelocity() is more efficient and coherent if any of this, other_frame, or measured_in_frame are the same. Also, the value of V_M_BoCo does not depend on the measured_in_frame if Bo and Co are coincident (i.e., p_BoCo = 0), in which case consider the more efficient method CalcRelativeSpatialVelocityInWorld(). Lastly, the calculation of elongation between Bo and Co can be done with relative translational velocity, but elongation does not depend on the measured-in-frame (hence consider CalcRelativeSpatialVelocityInWorld()).

See also

CalcSpatialVelocityInWorld(), CalcSpatialVelocity(), and CalcRelativeSpatialVelocityInWorld().

CalcRelativeSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, other_frame: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialVelocity

Calculates this frame C’s spatial velocity relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: V_W_BC_W = V_WC_W - V_WB_W, frame C’s spatial velocity relative to frame B, measured and expressed in the world frame W. The rotational part of the returned quantity is ω_BC_W (C’s angular velocity measured in B and expressed in W). The translational part is v_W_BoCo_W (Co’s translational velocity relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

ω_BC_W  = ω_WC_W - ω_WB_W
 v_W_BoCo_W = v_WCo_W - v_WBo_W = DtW(p_BoCo)

where DtW(p_BoCo) is the time-derivative in frame W of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame W.

Note

The method CalcSpatialVelocityInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialVelocityInWorld() and CalcRelativeSpatialVelocity().

CalcRotationMatrix(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, frame_M: pydrake.multibody.tree.Frame) → pydrake.math.RotationMatrix: Calculates and returns the rotation matrix R_MF that relates frame_M and this frame F as a function of the state stored in context.

CalcRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.math.RotationMatrix: Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Note

If this is B, this method returns the identity RotationMatrix. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcRotationMatrixInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.math.RotationMatrix: Calculates and returns the rotation matrix R_WF that relates the world frame W and this frame F as a function of the state stored in context.

CalcSpatialAcceleration(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, measured_in_frame: pydrake.multibody.tree.Frame, expressed_in_frame: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialAcceleration

Calculates this frame F’s spatial acceleration measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_MF_E, this frame F’s spatial acceleration measured in frame M, expressed in frame E. The rotational part of the returned quantity is α_MF_E (frame F’s angular acceleration α measured in frame M, expressed in frame E). The translational part is a_MFo_E (translational acceleration of frame F’s origin point Fo, measured in frame M, expressed in frame E). Although α_MF is defined below in terms of DtM(ω_MF), the time-derivative in frame M of ω_MF, the actual calculation of α_MF avoids differentiation. Similarly for the definition vs. calculation for a_MFo.

Click to expand C++ code...

α_MF = DtM(ω_MF)           ω_MF is frame F's angular velocity in frame M.
 a_MFo = DtM(v_MFo)    v_MF is Fo's translational acceleration in frame M.

See also

CalcSpatialAccelerationInWorld() and CalcSpatialVelocity().

CalcSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.multibody.math.SpatialAcceleration

Calculates this frame F’s spatial acceleration measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: A_WF_W, this frame F’s spatial acceleration measured and expressed in the world frame W. The rotational part of the returned quantity is α_WF_E (frame F’s angular acceleration α measured and expressed in the world frame W). The translational part is a_WFo_W (translational acceleration of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialAccelerationInWorld() provides a more efficient way to obtain a body frame’s spatial acceleration measured in the world frame.

Note

When cached values are out of sync with the state stored in context, this method performs an expensive forward dynamics computation, whereas once evaluated, successive calls to this method are inexpensive.

See also

CalcSpatialAcceleration() and CalcSpatialVelocityInWorld().

CalcSpatialVelocity(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context, frame_M: pydrake.multibody.tree.Frame, frame_E: pydrake.multibody.tree.Frame) → pydrake.multibody.math.SpatialVelocity

Calculates this frame F’s spatial velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter frame_M:: which is the measured_in_frame.
Parameter frame_E:: which is the expressed_in_frame.

Returns: V_MF_E, this frame F’s spatial velocity measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_MF_E (frame F’s angular velocity ω measured in frame M, expressed in frame E). The translational part is v_MFo_E (translational velocity v of frame F’s origin point Fo, measured in frame M, expressed in frame E).

See also

CalcSpatialVelocityInWorld(), CalcRelativeSpatialVelocity(), and CalcSpatialAcceleration().

CalcSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → pydrake.multibody.math.SpatialVelocity

Calculates this frame F’s spatial velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: V_WF_W, this frame F’s spatial velocity measured and expressed in the world frame W. The rotational part of the returned quantity is ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W). The translational part is v_WFo_W (translational velocity v of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialVelocityInWorld() provides a more efficient way to obtain a body frame’s spatial velocity measured in the world frame.

See also

CalcSpatialVelocity(), CalcRelativeSpatialVelocityInWorld(), and CalcSpatialAccelerationInWorld().

EvalAngularVelocityInWorld(self: pydrake.multibody.tree.Frame, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]

Evaluates this frame F’s angular velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W).

See also

CalcAngularVelocity() to calculate ω_MF_E (this frame F’s angular velocity ω measured in a frame M and expressed in a frame E).

GetFixedOffsetPoseInBody(self: pydrake.multibody.tree.Frame, X_FQ: pydrake.math.RigidTransform) → pydrake.math.RigidTransform

Variant of CalcOffsetPoseInBody() that given the offset pose X_FQ of a frame Q in this frame F, returns the pose X_BQ of frame Q in the body frame B to which this frame is attached.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(*args, **kwargs)

Overloaded function.

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame) -> pydrake.math.RigidTransform

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame) -> pydrake.math.RigidTransform

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedRotationMatrixInBody(self: pydrake.multibody.tree.Frame, R_FQ: pydrake.math.RotationMatrix) → pydrake.math.RotationMatrix

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –

GetFixedRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame) → pydrake.math.RotationMatrix

Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –
Frame sub-classes that have a constant R_BF must override this –
method. An example of a frame sub-class not implementing this –
method would be that of a frame on a soft body, for which its pose –
in the body frame depends on the state of deformation of the body. –

GetParentPlant(self: pydrake.multibody.tree.Frame) → drake::multibody::MultibodyPlant<double>

index(self: pydrake.multibody.tree.Frame) → pydrake.multibody.tree.FrameIndex

is_body_frame(self: pydrake.multibody.tree.Frame) → bool: Returns true if this is the body frame.

is_world_frame(self: pydrake.multibody.tree.Frame) → bool: Returns true if this is the world frame.

model_instance(self: pydrake.multibody.tree.Frame) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Frame) → str: Returns the name of this frame. The name will never be empty.

scoped_name(self: pydrake.multibody.tree.Frame) → pydrake.multibody.tree.ScopedName: Returns scoped name of this frame. Neither of the two pieces of the name will be empty (the scope name and the element name).

template pydrake.multibody.tree.Frame_: Instantiations: Frame_[float], Frame_[AutoDiffXd], Frame_[Expression]

class pydrake.multibody.tree.Frame_[AutoDiffXd]

%Frame is an abstract class representing a material frame (also called a physical frame) of its underlying RigidBody. The Frame’s origin is a material point of its RigidBody, and its axes have fixed directions in that body. A Frame’s pose (position and orientation) with respect to its RigidBodyFrame may be parameterized, but is fixed (not time or state dependent) once parameters have been set.

An important characteristic of a Frame is that forces or torques applied to a Frame are applied to the Frame’s underlying RigidBody. Force-producing elements like joints, actuators, and constraints usually employ two Frames, with one Frame connected to one body and the other connected to a different body. Every Frame F can report the RigidBody B to which it is attached and its pose X_BF with respect to B’s RigidBodyFrame.

A Frame’s pose in World (or relative to other frames) is always calculated starting with its pose relative to its underlying RigidBodyFrame. Subclasses derived from Frame differ in how kinematic calculations are performed. For example, the angular velocity of a FixedOffsetFrame or RigidBodyFrame is identical to the angular velocity of its underlying body, whereas the translational velocity of a FixedOffsetFrame differs from that of a RigidBodyFrame.

Frame provides methods for obtaining its current orientation, position, motion, etc. from a Context passed to those methods.

__init__(*args, **kwargs)

body(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → drake::multibody::RigidBody<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >: Returns a const reference to the body associated to this Frame.

CalcAngularVelocity(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], measured_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], expressed_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → numpy.ndarray[object[3, 1]]

Calculates this frame F’s angular velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M (the frame in which this angular velocity is to be measured).
Parameter expressed_in_frame:: which is frame E (the frame in which the returned angular velocity is to be expressed).

Returns: ω_MF_E, this frame F’s angular velocity ω measured in frame M, expressed in frame E.

See also

EvalAngularVelocityInWorld() to evaluate ω_WF_W (this frame F’s angular velocity ω measured and expressed in the world frame W).

CalcOffsetPoseInBody(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], X_FQ: pydrake.math.RigidTransform_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]: Given the offset pose X_FQ of a frame Q in this frame F, this method computes the pose X_BQ of frame Q in the body frame B to which this frame is attached. In other words, if the pose of this frame F in the body frame B is X_BF, this method computes the pose X_BQ of frame Q in the body frame B as X_BQ = X_BF * X_FQ. In particular, if this **is**` the body frame B, i.e. X_BF is the identity transformation, this method directly returns X_FQ. Specific frame subclasses can override this method to provide faster implementations if needed.

CalcOffsetRotationMatrixInBody(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], R_FQ: pydrake.math.RotationMatrix_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

CalcPose(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], frame_M: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]: Computes and returns the pose X_MF of this frame F in measured in frame_M as a function of the state of the model stored in context.

See also

CalcPoseInWorld().

CalcPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]: Returns the pose X_BF of this frame F in the body frame B associated with this frame. In particular, if this is the body frame B, this method directly returns the identity transformation. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcPoseInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]: Computes and returns the pose X_WF of this frame F in the world frame W as a function of the state of the model stored in context.

Note

RigidBody::EvalPoseInWorld() provides a more efficient way to obtain the pose for a body frame.

CalcRelativeSpatialAcceleration(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], other_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], measured_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], expressed_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialAcceleration_[AutoDiffXd]

Calculates this frame C’s spatial acceleration relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_M_BC_E = A_MC_E - A_MB_E, frame C’s spatial acceleration relative to frame B, measured in frame M, expressed in frame E.

In general, A_M_BC = DtW(V_M_BC), the time-derivative in frame M of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_MC_E - α_MB_E = DtM(ω_BC)_E. Note: For 3D analysis, DtM(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_M_BoCo_E (Co’s translational acceleration relative to Bo, measured in frame M, expressed in frame E).

Click to expand C++ code...

α_MC_E - α_MB_E = DtM(ω_MC)_E - DtM(ω_MB)_E = DtM(ω_BC)_E
 a_M_BoCo_E = a_MCo_E - a_MBo_E = DtM(v_MCo) - DtM(v_MBo) = Dt²M(p_BoCo)_E

where Dt²M(p_BoCo)_E is the 2ⁿᵈ time-derivative in frame M of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame E.

Note

The calculation of the 2ⁿᵈ time-derivative of the distance between Bo and Co can be done with relative translational acceleration, but this calculation does not depend on the measured-in-frame, hence in this case, consider CalcRelativeSpatialAccelerationInWorld() since it is faster.

See also

CalcSpatialAccelerationInWorld(), CalcSpatialAcceleration(), and CalcRelativeSpatialAccelerationInWorld().

CalcRelativeSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], other_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialAcceleration_[AutoDiffXd]

Calculates this frame C’s spatial acceleration relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: A_W_BC_W = A_WC_W - A_WB_W, frame C’s spatial acceleration relative to frame B, measured and expressed in the world frame W.

In general, A_W_BC = DtW(V_W_BC), the time-derivative in the world frame W of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_WC_W - α_WB_W = DtW(ω_BC)_W. For 3D analysis, DtW(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_W_BoCo_W (Co’s translational acceleration relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

α_WC_W - α_WB_W = DtW(ω_WC)_W - DtW(ω_WB)_W = DtW(ω_BC)_W
 a_W_BoCo_W = a_WCo_W - a_WBo_W = DtW(v_WCo) - DtW(v_WBo) = Dt²W(p_BoCo)_W

where Dt²W(p_BoCo)_W is the 2ⁿᵈ time-derivative in frame W of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame W.

Note

The method CalcSpatialAccelerationInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialAccelerationInWorld(), CalcRelativeSpatialAcceleration().

CalcRelativeSpatialVelocity(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], other_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], measured_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], expressed_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialVelocity_[AutoDiffXd]

Calculates this frame C’s spatial velocity relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: V_M_BC_E = V_MC_E - V_MB_E, frame C’s spatial velocity relative to frame B, measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_BC_E (C’s angular velocity measured in B and expressed in E). The translational part is v_M_BoCo_E (Co’s translational velocity relative to Bo, measured in M, and expressed in E).

Click to expand C++ code...

ω_BC_E = ω_MC_E - ω_MB_E
 v_M_BoCo_E = v_MCo_E - v_MBo_E = DtM(p_BoCo)

where DtM(p_BoCo) is the time-derivative in frame M of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame E.

Note

The method CalcSpatialVelocity() is more efficient and coherent if any of this, other_frame, or measured_in_frame are the same. Also, the value of V_M_BoCo does not depend on the measured_in_frame if Bo and Co are coincident (i.e., p_BoCo = 0), in which case consider the more efficient method CalcRelativeSpatialVelocityInWorld(). Lastly, the calculation of elongation between Bo and Co can be done with relative translational velocity, but elongation does not depend on the measured-in-frame (hence consider CalcRelativeSpatialVelocityInWorld()).

See also

CalcSpatialVelocityInWorld(), CalcSpatialVelocity(), and CalcRelativeSpatialVelocityInWorld().

CalcRelativeSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], other_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialVelocity_[AutoDiffXd]

Calculates this frame C’s spatial velocity relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: V_W_BC_W = V_WC_W - V_WB_W, frame C’s spatial velocity relative to frame B, measured and expressed in the world frame W. The rotational part of the returned quantity is ω_BC_W (C’s angular velocity measured in B and expressed in W). The translational part is v_W_BoCo_W (Co’s translational velocity relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

ω_BC_W  = ω_WC_W - ω_WB_W
 v_W_BoCo_W = v_WCo_W - v_WBo_W = DtW(p_BoCo)

where DtW(p_BoCo) is the time-derivative in frame W of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame W.

Note

The method CalcSpatialVelocityInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialVelocityInWorld() and CalcRelativeSpatialVelocity().

CalcRotationMatrix(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], frame_M: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]: Calculates and returns the rotation matrix R_MF that relates frame_M and this frame F as a function of the state stored in context.

CalcRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]: Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Note

If this is B, this method returns the identity RotationMatrix. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcRotationMatrixInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]: Calculates and returns the rotation matrix R_WF that relates the world frame W and this frame F as a function of the state stored in context.

CalcSpatialAcceleration(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], measured_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd], expressed_in_frame: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialAcceleration_[AutoDiffXd]

Calculates this frame F’s spatial acceleration measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_MF_E, this frame F’s spatial acceleration measured in frame M, expressed in frame E. The rotational part of the returned quantity is α_MF_E (frame F’s angular acceleration α measured in frame M, expressed in frame E). The translational part is a_MFo_E (translational acceleration of frame F’s origin point Fo, measured in frame M, expressed in frame E). Although α_MF is defined below in terms of DtM(ω_MF), the time-derivative in frame M of ω_MF, the actual calculation of α_MF avoids differentiation. Similarly for the definition vs. calculation for a_MFo.

Click to expand C++ code...

α_MF = DtM(ω_MF)           ω_MF is frame F's angular velocity in frame M.
 a_MFo = DtM(v_MFo)    v_MF is Fo's translational acceleration in frame M.

See also

CalcSpatialAccelerationInWorld() and CalcSpatialVelocity().

CalcSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.multibody.math.SpatialAcceleration_[AutoDiffXd]

Calculates this frame F’s spatial acceleration measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: A_WF_W, this frame F’s spatial acceleration measured and expressed in the world frame W. The rotational part of the returned quantity is α_WF_E (frame F’s angular acceleration α measured and expressed in the world frame W). The translational part is a_WFo_W (translational acceleration of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialAccelerationInWorld() provides a more efficient way to obtain a body frame’s spatial acceleration measured in the world frame.

Note

When cached values are out of sync with the state stored in context, this method performs an expensive forward dynamics computation, whereas once evaluated, successive calls to this method are inexpensive.

See also

CalcSpatialAcceleration() and CalcSpatialVelocityInWorld().

CalcSpatialVelocity(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], frame_M: pydrake.multibody.tree.Frame_[AutoDiffXd], frame_E: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.math.SpatialVelocity_[AutoDiffXd]

Calculates this frame F’s spatial velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter frame_M:: which is the measured_in_frame.
Parameter frame_E:: which is the expressed_in_frame.

Returns: V_MF_E, this frame F’s spatial velocity measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_MF_E (frame F’s angular velocity ω measured in frame M, expressed in frame E). The translational part is v_MFo_E (translational velocity v of frame F’s origin point Fo, measured in frame M, expressed in frame E).

See also

CalcSpatialVelocityInWorld(), CalcRelativeSpatialVelocity(), and CalcSpatialAcceleration().

CalcSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.multibody.math.SpatialVelocity_[AutoDiffXd]

Calculates this frame F’s spatial velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: V_WF_W, this frame F’s spatial velocity measured and expressed in the world frame W. The rotational part of the returned quantity is ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W). The translational part is v_WFo_W (translational velocity v of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialVelocityInWorld() provides a more efficient way to obtain a body frame’s spatial velocity measured in the world frame.

See also

CalcSpatialVelocity(), CalcRelativeSpatialVelocityInWorld(), and CalcSpatialAccelerationInWorld().

EvalAngularVelocityInWorld(self: pydrake.multibody.tree.Frame_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → numpy.ndarray[object[3, 1]]

Evaluates this frame F’s angular velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W).

See also

CalcAngularVelocity() to calculate ω_MF_E (this frame F’s angular velocity ω measured in a frame M and expressed in a frame E).

GetFixedOffsetPoseInBody(self: pydrake.multibody.tree.Frame_[AutoDiffXd], X_FQ: pydrake.math.RigidTransform_[AutoDiffXd]) → pydrake.math.RigidTransform_[AutoDiffXd]

Variant of CalcOffsetPoseInBody() that given the offset pose X_FQ of a frame Q in this frame F, returns the pose X_BQ of frame Q in the body frame B to which this frame is attached.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(*args, **kwargs)

Overloaded function.

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) -> pydrake.math.RigidTransform_[AutoDiffXd]

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) -> pydrake.math.RigidTransform_[AutoDiffXd]

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedRotationMatrixInBody(self: pydrake.multibody.tree.Frame_[AutoDiffXd], R_FQ: pydrake.math.RotationMatrix_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –

GetFixedRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.math.RotationMatrix_[AutoDiffXd]

Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –
Frame sub-classes that have a constant R_BF must override this –
method. An example of a frame sub-class not implementing this –
method would be that of a frame on a soft body, for which its pose –
in the body frame depends on the state of deformation of the body. –

GetParentPlant(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → drake::multibody::MultibodyPlant<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

index(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.tree.FrameIndex

is_body_frame(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → bool: Returns true if this is the body frame.

is_world_frame(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → bool: Returns true if this is the world frame.

model_instance(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → str: Returns the name of this frame. The name will never be empty.

scoped_name(self: pydrake.multibody.tree.Frame_[AutoDiffXd]) → pydrake.multibody.tree.ScopedName: Returns scoped name of this frame. Neither of the two pieces of the name will be empty (the scope name and the element name).

class pydrake.multibody.tree.Frame_[Expression]

%Frame is an abstract class representing a material frame (also called a physical frame) of its underlying RigidBody. The Frame’s origin is a material point of its RigidBody, and its axes have fixed directions in that body. A Frame’s pose (position and orientation) with respect to its RigidBodyFrame may be parameterized, but is fixed (not time or state dependent) once parameters have been set.

An important characteristic of a Frame is that forces or torques applied to a Frame are applied to the Frame’s underlying RigidBody. Force-producing elements like joints, actuators, and constraints usually employ two Frames, with one Frame connected to one body and the other connected to a different body. Every Frame F can report the RigidBody B to which it is attached and its pose X_BF with respect to B’s RigidBodyFrame.

A Frame’s pose in World (or relative to other frames) is always calculated starting with its pose relative to its underlying RigidBodyFrame. Subclasses derived from Frame differ in how kinematic calculations are performed. For example, the angular velocity of a FixedOffsetFrame or RigidBodyFrame is identical to the angular velocity of its underlying body, whereas the translational velocity of a FixedOffsetFrame differs from that of a RigidBodyFrame.

Frame provides methods for obtaining its current orientation, position, motion, etc. from a Context passed to those methods.

__init__(*args, **kwargs)

body(self: pydrake.multibody.tree.Frame_[Expression]) → drake::multibody::RigidBody<drake::symbolic::Expression>: Returns a const reference to the body associated to this Frame.

CalcAngularVelocity(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], measured_in_frame: pydrake.multibody.tree.Frame_[Expression], expressed_in_frame: pydrake.multibody.tree.Frame_[Expression]) → numpy.ndarray[object[3, 1]]

Calculates this frame F’s angular velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M (the frame in which this angular velocity is to be measured).
Parameter expressed_in_frame:: which is frame E (the frame in which the returned angular velocity is to be expressed).

Returns: ω_MF_E, this frame F’s angular velocity ω measured in frame M, expressed in frame E.

See also

EvalAngularVelocityInWorld() to evaluate ω_WF_W (this frame F’s angular velocity ω measured and expressed in the world frame W).

CalcOffsetPoseInBody(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], X_FQ: pydrake.math.RigidTransform_[Expression]) → pydrake.math.RigidTransform_[Expression]: Given the offset pose X_FQ of a frame Q in this frame F, this method computes the pose X_BQ of frame Q in the body frame B to which this frame is attached. In other words, if the pose of this frame F in the body frame B is X_BF, this method computes the pose X_BQ of frame Q in the body frame B as X_BQ = X_BF * X_FQ. In particular, if this **is**` the body frame B, i.e. X_BF is the identity transformation, this method directly returns X_FQ. Specific frame subclasses can override this method to provide faster implementations if needed.

CalcOffsetRotationMatrixInBody(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], R_FQ: pydrake.math.RotationMatrix_[Expression]) → pydrake.math.RotationMatrix_[Expression]

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

CalcPose(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], frame_M: pydrake.multibody.tree.Frame_[Expression]) → pydrake.math.RigidTransform_[Expression]: Computes and returns the pose X_MF of this frame F in measured in frame_M as a function of the state of the model stored in context.

See also

CalcPoseInWorld().

CalcPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.math.RigidTransform_[Expression]: Returns the pose X_BF of this frame F in the body frame B associated with this frame. In particular, if this is the body frame B, this method directly returns the identity transformation. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcPoseInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.math.RigidTransform_[Expression]: Computes and returns the pose X_WF of this frame F in the world frame W as a function of the state of the model stored in context.

Note

RigidBody::EvalPoseInWorld() provides a more efficient way to obtain the pose for a body frame.

CalcRelativeSpatialAcceleration(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], other_frame: pydrake.multibody.tree.Frame_[Expression], measured_in_frame: pydrake.multibody.tree.Frame_[Expression], expressed_in_frame: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialAcceleration_[Expression]

Calculates this frame C’s spatial acceleration relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_M_BC_E = A_MC_E - A_MB_E, frame C’s spatial acceleration relative to frame B, measured in frame M, expressed in frame E.

In general, A_M_BC = DtW(V_M_BC), the time-derivative in frame M of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_MC_E - α_MB_E = DtM(ω_BC)_E. Note: For 3D analysis, DtM(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_M_BoCo_E (Co’s translational acceleration relative to Bo, measured in frame M, expressed in frame E).

Click to expand C++ code...

α_MC_E - α_MB_E = DtM(ω_MC)_E - DtM(ω_MB)_E = DtM(ω_BC)_E
 a_M_BoCo_E = a_MCo_E - a_MBo_E = DtM(v_MCo) - DtM(v_MBo) = Dt²M(p_BoCo)_E

where Dt²M(p_BoCo)_E is the 2ⁿᵈ time-derivative in frame M of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame E.

Note

The calculation of the 2ⁿᵈ time-derivative of the distance between Bo and Co can be done with relative translational acceleration, but this calculation does not depend on the measured-in-frame, hence in this case, consider CalcRelativeSpatialAccelerationInWorld() since it is faster.

See also

CalcSpatialAccelerationInWorld(), CalcSpatialAcceleration(), and CalcRelativeSpatialAccelerationInWorld().

CalcRelativeSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], other_frame: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialAcceleration_[Expression]

Calculates this frame C’s spatial acceleration relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: A_W_BC_W = A_WC_W - A_WB_W, frame C’s spatial acceleration relative to frame B, measured and expressed in the world frame W.

In general, A_W_BC = DtW(V_W_BC), the time-derivative in the world frame W of frame C’s spatial velocity relative to frame B. The rotational part of the returned quantity is α_WC_W - α_WB_W = DtW(ω_BC)_W. For 3D analysis, DtW(ω_BC) ≠ α_BC. The translational part of the returned quantity is a_W_BoCo_W (Co’s translational acceleration relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

α_WC_W - α_WB_W = DtW(ω_WC)_W - DtW(ω_WB)_W = DtW(ω_BC)_W
 a_W_BoCo_W = a_WCo_W - a_WBo_W = DtW(v_WCo) - DtW(v_WBo) = Dt²W(p_BoCo)_W

where Dt²W(p_BoCo)_W is the 2ⁿᵈ time-derivative in frame W of p_BoCo (the position vector from Bo to Co), and this result is expressed in frame W.

Note

The method CalcSpatialAccelerationInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialAccelerationInWorld(), CalcRelativeSpatialAcceleration().

CalcRelativeSpatialVelocity(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], other_frame: pydrake.multibody.tree.Frame_[Expression], measured_in_frame: pydrake.multibody.tree.Frame_[Expression], expressed_in_frame: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialVelocity_[Expression]

Calculates this frame C’s spatial velocity relative to another frame B, measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: V_M_BC_E = V_MC_E - V_MB_E, frame C’s spatial velocity relative to frame B, measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_BC_E (C’s angular velocity measured in B and expressed in E). The translational part is v_M_BoCo_E (Co’s translational velocity relative to Bo, measured in M, and expressed in E).

Click to expand C++ code...

ω_BC_E = ω_MC_E - ω_MB_E
 v_M_BoCo_E = v_MCo_E - v_MBo_E = DtM(p_BoCo)

where DtM(p_BoCo) is the time-derivative in frame M of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame E.

Note

The method CalcSpatialVelocity() is more efficient and coherent if any of this, other_frame, or measured_in_frame are the same. Also, the value of V_M_BoCo does not depend on the measured_in_frame if Bo and Co are coincident (i.e., p_BoCo = 0), in which case consider the more efficient method CalcRelativeSpatialVelocityInWorld(). Lastly, the calculation of elongation between Bo and Co can be done with relative translational velocity, but elongation does not depend on the measured-in-frame (hence consider CalcRelativeSpatialVelocityInWorld()).

See also

CalcSpatialVelocityInWorld(), CalcSpatialVelocity(), and CalcRelativeSpatialVelocityInWorld().

CalcRelativeSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], other_frame: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialVelocity_[Expression]

Calculates this frame C’s spatial velocity relative to another frame B, measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.
Parameter other_frame:: which is frame B.

Returns: V_W_BC_W = V_WC_W - V_WB_W, frame C’s spatial velocity relative to frame B, measured and expressed in the world frame W. The rotational part of the returned quantity is ω_BC_W (C’s angular velocity measured in B and expressed in W). The translational part is v_W_BoCo_W (Co’s translational velocity relative to Bo, measured and expressed in world frame W).

Click to expand C++ code...

ω_BC_W  = ω_WC_W - ω_WB_W
 v_W_BoCo_W = v_WCo_W - v_WBo_W = DtW(p_BoCo)

where DtW(p_BoCo) is the time-derivative in frame W of p_BoCo (position vector from Bo to Co), and this vector is expressed in frame W.

Note

The method CalcSpatialVelocityInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also

CalcSpatialVelocityInWorld() and CalcRelativeSpatialVelocity().

CalcRotationMatrix(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], frame_M: pydrake.multibody.tree.Frame_[Expression]) → pydrake.math.RotationMatrix_[Expression]: Calculates and returns the rotation matrix R_MF that relates frame_M and this frame F as a function of the state stored in context.

CalcRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.math.RotationMatrix_[Expression]: Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Note

If this is B, this method returns the identity RotationMatrix. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

CalcRotationMatrixInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.math.RotationMatrix_[Expression]: Calculates and returns the rotation matrix R_WF that relates the world frame W and this frame F as a function of the state stored in context.

CalcSpatialAcceleration(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], measured_in_frame: pydrake.multibody.tree.Frame_[Expression], expressed_in_frame: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialAcceleration_[Expression]

Calculates this frame F’s spatial acceleration measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter measured_in_frame:: which is frame M.
Parameter expressed_in_frame:: which is frame E.

Returns: A_MF_E, this frame F’s spatial acceleration measured in frame M, expressed in frame E. The rotational part of the returned quantity is α_MF_E (frame F’s angular acceleration α measured in frame M, expressed in frame E). The translational part is a_MFo_E (translational acceleration of frame F’s origin point Fo, measured in frame M, expressed in frame E). Although α_MF is defined below in terms of DtM(ω_MF), the time-derivative in frame M of ω_MF, the actual calculation of α_MF avoids differentiation. Similarly for the definition vs. calculation for a_MFo.

Click to expand C++ code...

α_MF = DtM(ω_MF)           ω_MF is frame F's angular velocity in frame M.
 a_MFo = DtM(v_MFo)    v_MF is Fo's translational acceleration in frame M.

See also

CalcSpatialAccelerationInWorld() and CalcSpatialVelocity().

CalcSpatialAccelerationInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.multibody.math.SpatialAcceleration_[Expression]

Calculates this frame F’s spatial acceleration measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: A_WF_W, this frame F’s spatial acceleration measured and expressed in the world frame W. The rotational part of the returned quantity is α_WF_E (frame F’s angular acceleration α measured and expressed in the world frame W). The translational part is a_WFo_W (translational acceleration of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialAccelerationInWorld() provides a more efficient way to obtain a body frame’s spatial acceleration measured in the world frame.

Note

When cached values are out of sync with the state stored in context, this method performs an expensive forward dynamics computation, whereas once evaluated, successive calls to this method are inexpensive.

See also

CalcSpatialAcceleration() and CalcSpatialVelocityInWorld().

CalcSpatialVelocity(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression], frame_M: pydrake.multibody.tree.Frame_[Expression], frame_E: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.math.SpatialVelocity_[Expression]

Calculates this frame F’s spatial velocity measured in a frame M, expressed in a frame E.

Parameter context:: contains the state of the multibody system.
Parameter frame_M:: which is the measured_in_frame.
Parameter frame_E:: which is the expressed_in_frame.

Returns: V_MF_E, this frame F’s spatial velocity measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_MF_E (frame F’s angular velocity ω measured in frame M, expressed in frame E). The translational part is v_MFo_E (translational velocity v of frame F’s origin point Fo, measured in frame M, expressed in frame E).

See also

CalcSpatialVelocityInWorld(), CalcRelativeSpatialVelocity(), and CalcSpatialAcceleration().

CalcSpatialVelocityInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.multibody.math.SpatialVelocity_[Expression]

Calculates this frame F’s spatial velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: V_WF_W, this frame F’s spatial velocity measured and expressed in the world frame W. The rotational part of the returned quantity is ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W). The translational part is v_WFo_W (translational velocity v of frame F’s origin point Fo, measured and expressed in the world frame W).

Note

RigidBody::EvalSpatialVelocityInWorld() provides a more efficient way to obtain a body frame’s spatial velocity measured in the world frame.

See also

CalcSpatialVelocity(), CalcRelativeSpatialVelocityInWorld(), and CalcSpatialAccelerationInWorld().

EvalAngularVelocityInWorld(self: pydrake.multibody.tree.Frame_[Expression], context: pydrake.systems.framework.Context_[Expression]) → numpy.ndarray[object[3, 1]]

Evaluates this frame F’s angular velocity measured and expressed in the world frame W.

Parameter context:: contains the state of the multibody system.

Returns: ω_WF_W (frame F’s angular velocity ω measured and expressed in the world frame W).

See also

CalcAngularVelocity() to calculate ω_MF_E (this frame F’s angular velocity ω measured in a frame M and expressed in a frame E).

GetFixedOffsetPoseInBody(self: pydrake.multibody.tree.Frame_[Expression], X_FQ: pydrake.math.RigidTransform_[Expression]) → pydrake.math.RigidTransform_[Expression]

Variant of CalcOffsetPoseInBody() that given the offset pose X_FQ of a frame Q in this frame F, returns the pose X_BQ of frame Q in the body frame B to which this frame is attached.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(*args, **kwargs)

Overloaded function.

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[Expression]) -> pydrake.math.RigidTransform_[Expression]

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedPoseInBodyFrame(self: pydrake.multibody.tree.Frame_[Expression]) -> pydrake.math.RigidTransform_[Expression]

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_BF of this frame F in the body frame B associated with this frame.

Raises

RuntimeError if called on a Frame that does not have a fixed –
offset in the body frame. –

GetFixedRotationMatrixInBody(self: pydrake.multibody.tree.Frame_[Expression], R_FQ: pydrake.math.RotationMatrix_[Expression]) → pydrake.math.RotationMatrix_[Expression]

Calculates and returns the rotation matrix R_BQ that relates body frame B to frame Q via this intermediate frame F, i.e., R_BQ = R_BF * R_FQ (B is the body frame to which this frame F is attached).

Parameter R_FQ:: rotation matrix that relates frame F to frame Q.

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –

GetFixedRotationMatrixInBodyFrame(self: pydrake.multibody.tree.Frame_[Expression]) → pydrake.math.RotationMatrix_[Expression]

Returns the rotation matrix R_BF that relates body frame B to this frame F (B is the body frame to which this frame F is attached).

Raises

RuntimeError if this frame F is a Frame that does not have a –
fixed offset in the body frame B (i.e., R_BF is not constant) –
Frame sub-classes that have a constant R_BF must override this –
method. An example of a frame sub-class not implementing this –
method would be that of a frame on a soft body, for which its pose –
in the body frame depends on the state of deformation of the body. –

GetParentPlant(self: pydrake.multibody.tree.Frame_[Expression]) → drake::multibody::MultibodyPlant<drake::symbolic::Expression>

index(self: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.tree.FrameIndex

is_body_frame(self: pydrake.multibody.tree.Frame_[Expression]) → bool: Returns true if this is the body frame.

is_world_frame(self: pydrake.multibody.tree.Frame_[Expression]) → bool: Returns true if this is the world frame.

model_instance(self: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Frame_[Expression]) → str: Returns the name of this frame. The name will never be empty.

scoped_name(self: pydrake.multibody.tree.Frame_[Expression]) → pydrake.multibody.tree.ScopedName: Returns scoped name of this frame. Neither of the two pieces of the name will be empty (the scope name and the element name).

class pydrake.multibody.tree.FrameIndex

Type used to identify frames by index in a multibody plant.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.FrameIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

__init__(self: pydrake.multibody.tree.FrameIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.multibody.tree.FrameIndex) → bool: Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.multibody.tree.JacobianWrtVariable

Enumeration that indicates whether the Jacobian is partial differentiation with respect to q̇ (time-derivatives of generalized positions) or with respect to v (generalized velocities).

Members:

kQDot : J = ∂V/∂q̇

kV : J = ∂V/∂v

__init__(self: pydrake.multibody.tree.JacobianWrtVariable, value: int) → None

kQDot = <JacobianWrtVariable.kQDot: 0>

kV = <JacobianWrtVariable.kV: 1>

property name

property value

class pydrake.multibody.tree.Joint

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. @image html drake/multibody/plant/images/BodyParentChildJoint.png width=50%

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:

Click to expand C++ code...

MultibodyPlant<double> plant(0.0);
// ... Code here to setup quantities below as mass, com, etc. ...
const RigidBody<double>& pendulum =
  plant.AddRigidBody(SpatialInertia<double>(mass, com, unit_inertia));
// 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 =
  plant.AddJoint<RevoluteJoint>(
    "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.

Note

This class is templated; see Joint_ for the list of instantiations.

__init__(*args, **kwargs)

acceleration_lower_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration lower limits.

acceleration_upper_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration upper limits.

AddInDamping(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context, forces: drake::multibody::MultibodyForces<double>) → None

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

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.

AddInOneForce(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context, joint_dof: int, joint_tau: float, forces: drake::multibody::MultibodyForces<double>) → None

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.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.
Parameter joint_tau:: Generalized force corresponding to the degree of freedom indicated by joint_dof to be added into forces.
Parameter 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.

can_rotate(self: pydrake.multibody.tree.Joint) → bool

Returns true if this joint’s mobility allows relative rotation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_translate()

can_translate(self: pydrake.multibody.tree.Joint) → bool

Returns true if this joint’s mobility allows relative translation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_rotate()

child_body(self: pydrake.multibody.tree.Joint) → pydrake.multibody.tree.RigidBody: Returns a const reference to the child body B.

default_damping_vector(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns all default damping coefficients for joints that model viscous damping, of size num_velocities(). Joints that do not model damping return a zero vector of size num_velocities(). If vj is the vector of generalized velocities for this joint, of size num_velocities(), viscous damping models a generalized force at the joint of the form tau = -diag(dj)⋅vj, with dj the vector returned by this function. The units of the coefficients will depend on the specific joint type. For instance, for a revolute joint where vj is an angular velocity with units of rad/s and tau having units of N⋅m, the coefficient of viscous damping has units of N⋅m⋅s. Refer to each joint’s documentation for further details.

default_positions(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the default positions.

frame_on_child(self: pydrake.multibody.tree.Joint) → pydrake.multibody.tree.Frame: Returns a const reference to the frame M attached on the child body B.

frame_on_parent(self: pydrake.multibody.tree.Joint) → pydrake.multibody.tree.Frame: Returns a const reference to the frame F attached on the parent body P.

GetDampingVector(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[m, 1]]

Returns the Context dependent damping coefficients stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.

GetDefaultPose(self: pydrake.multibody.tree.Joint) → pydrake.math.RigidTransform

Returns this Joint’s default pose as a RigidTransform X_FM.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

Returns X_FM:: The default pose as a rigid transform.

See also

get_default_positions() to see the generalized positions q₀ that this joint used to generate the returned transform.

GetDefaultPosePair(self: pydrake.multibody.tree.Joint) → tuple[pydrake.common.eigen_geometry.Quaternion, numpy.ndarray[numpy.float64[3, 1]]]

(Advanced) This is the same as GetDefaultPose() except it returns this Joint’s default pose as a (quaternion, translation vector) pair.

Returns q_FM:: ,p_FM The default pose as a (quaternion, translation) pair.

See also

GetDefaultPose() for more information

GetOnePosition(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → float

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetOneVelocity(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → float

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetParentPlant(self: pydrake.multibody.tree.Joint) → drake::multibody::MultibodyPlant<double>

index(*args, **kwargs)

Overloaded function.

index(self: pydrake.multibody.tree.Joint) -> pydrake.multibody.tree.JointIndex
index(self: pydrake.multibody.tree.Joint) -> pydrake.multibody.tree.JointIndex

Returns this element’s unique index.

is_locked(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → bool

Returns: true if the joint is locked, false otherwise.

Lock(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → None: Lock the joint. Its generalized velocities will be 0 until it is unlocked.

model_instance(self: pydrake.multibody.tree.Joint) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Joint) → str: Returns the name of this joint.

num_positions(self: pydrake.multibody.tree.Joint) → int: Returns the number of generalized positions describing this joint.

num_velocities(self: pydrake.multibody.tree.Joint) → int: Returns the number of generalized velocities describing this joint.

parent_body(self: pydrake.multibody.tree.Joint) → pydrake.multibody.tree.RigidBody: Returns a const reference to the parent body P.

position_lower_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: @name Methods to get and set the limits of this 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.

position_start(self: pydrake.multibody.tree.Joint) → int: Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system.

position_suffix(self: pydrake.multibody.tree.Joint, arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th position in this joint. ``position_index_in_joint` must be in [0, num_positions()).

Precondition:: the MultibodyPlant must be finalized.

position_upper_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the position upper limits.

set_acceleration_limits(self: pydrake.multibody.tree.Joint, lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the acceleration limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

set_default_damping_vector(self: pydrake.multibody.tree.Joint, damping: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default value of the viscous damping coefficients for this joint. Refer to default_damping_vector() for details.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Precondition:: the MultibodyPlant must not be finalized.

set_default_positions(self: pydrake.multibody.tree.Joint, default_positions: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default positions to default_positions. Joint subclasses are expected to implement the do_set_default_positions().

Raises

RuntimeError 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(self: pydrake.multibody.tree.Joint, lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the position limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_positions() –
RuntimeError 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(self: pydrake.multibody.tree.Joint, lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the velocity limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

SetDampingVector(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context, damping: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the value of the viscous damping coefficients for this joint, stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter damping:: The vector of damping values.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Note

Some multi-dof joints may have specific semantics for their damping vector that are not enforced here. For instance, QuaternionFloatingJoint assumes identical damping values for all 3 angular velocity components and identical damping values for all 3 translational velocity components. It will thus use angular_damping = damping[0] and translational_damping = damping[3]. Refer to the particular subclass for more semantic information.

SetDefaultPose(self: pydrake.multibody.tree.Joint, X_FM: pydrake.math.RigidTransform) → None

Sets this Joint’s default generalized positions q₀ such that the pose of the child frame M in the parent frame F best matches the given pose. The pose is given by a RigidTransform X_FM, but a Joint will represent pose differently.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

See also

get_default_positions() to see the resulting q₀ after this call.

See also

SetDefaultPosePair() for an alternative using a quaternion

SetDefaultPosePair(self: pydrake.multibody.tree.Joint, q_FM: pydrake.common.eigen_geometry.Quaternion, p_FM: numpy.ndarray[numpy.float64[3, 1]]) → None: (Advanced) This is the same as SetDefaultPose() except it takes the pose as a (quaternion, translation vector) pair.

See also

SetDefaultPose() for more information

type_name(self: pydrake.multibody.tree.Joint) → str: Returns a string identifying the type of this joint, such as “revolute” or “prismatic”.

Unlock(self: pydrake.multibody.tree.Joint, context: pydrake.systems.framework.Context) → None: Unlock the joint.

velocity_lower_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity lower limits.

velocity_start(self: pydrake.multibody.tree.Joint) → int: Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system.

velocity_suffix(self: pydrake.multibody.tree.Joint, arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th velocity in this joint. ``velocity_index_in_joint` must be in [0, num_velocities()).

Precondition:: the MultibodyPlant must be finalized.

velocity_upper_limits(self: pydrake.multibody.tree.Joint) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity upper limits.

template pydrake.multibody.tree.Joint_: Instantiations: Joint_[float], Joint_[AutoDiffXd], Joint_[Expression]

class pydrake.multibody.tree.Joint_[AutoDiffXd]

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. @image html drake/multibody/plant/images/BodyParentChildJoint.png width=50%

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:

Click to expand C++ code...

MultibodyPlant<double> plant(0.0);
// ... Code here to setup quantities below as mass, com, etc. ...
const RigidBody<double>& pendulum =
  plant.AddRigidBody(SpatialInertia<double>(mass, com, unit_inertia));
// 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 =
  plant.AddJoint<RevoluteJoint>(
    "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.

__init__(*args, **kwargs)

acceleration_lower_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration lower limits.

acceleration_upper_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration upper limits.

AddInDamping(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], forces: drake::multibody::MultibodyForces<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >) → None

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

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.

AddInOneForce(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], joint_dof: int, joint_tau: pydrake.autodiffutils.AutoDiffXd, forces: drake::multibody::MultibodyForces<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >) → None

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.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.
Parameter joint_tau:: Generalized force corresponding to the degree of freedom indicated by joint_dof to be added into forces.
Parameter 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.

can_rotate(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → bool

Returns true if this joint’s mobility allows relative rotation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_translate()

can_translate(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → bool

Returns true if this joint’s mobility allows relative translation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_rotate()

child_body(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.multibody.tree.RigidBody_[AutoDiffXd]: Returns a const reference to the child body B.

default_damping_vector(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns all default damping coefficients for joints that model viscous damping, of size num_velocities(). Joints that do not model damping return a zero vector of size num_velocities(). If vj is the vector of generalized velocities for this joint, of size num_velocities(), viscous damping models a generalized force at the joint of the form tau = -diag(dj)⋅vj, with dj the vector returned by this function. The units of the coefficients will depend on the specific joint type. For instance, for a revolute joint where vj is an angular velocity with units of rad/s and tau having units of N⋅m, the coefficient of viscous damping has units of N⋅m⋅s. Refer to each joint’s documentation for further details.

default_positions(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the default positions.

frame_on_child(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.multibody.tree.Frame_[AutoDiffXd]: Returns a const reference to the frame M attached on the child body B.

frame_on_parent(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.multibody.tree.Frame_[AutoDiffXd]: Returns a const reference to the frame F attached on the parent body P.

GetDampingVector(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

Returns the Context dependent damping coefficients stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.

GetDefaultPose(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.math.RigidTransform

Returns this Joint’s default pose as a RigidTransform X_FM.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

Returns X_FM:: The default pose as a rigid transform.

See also

get_default_positions() to see the generalized positions q₀ that this joint used to generate the returned transform.

GetDefaultPosePair(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → tuple[pydrake.common.eigen_geometry.Quaternion, numpy.ndarray[numpy.float64[3, 1]]]

(Advanced) This is the same as GetDefaultPose() except it returns this Joint’s default pose as a (quaternion, translation vector) pair.

Returns q_FM:: ,p_FM The default pose as a (quaternion, translation) pair.

See also

GetDefaultPose() for more information

GetOnePosition(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetOneVelocity(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetParentPlant(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → drake::multibody::MultibodyPlant<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

index(*args, **kwargs)

Overloaded function.

index(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) -> pydrake.multibody.tree.JointIndex
index(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) -> pydrake.multibody.tree.JointIndex

Returns this element’s unique index.

is_locked(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → bool

Returns: true if the joint is locked, false otherwise.

Lock(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → None: Lock the joint. Its generalized velocities will be 0 until it is unlocked.

model_instance(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → str: Returns the name of this joint.

num_positions(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → int: Returns the number of generalized positions describing this joint.

num_velocities(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → int: Returns the number of generalized velocities describing this joint.

parent_body(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → pydrake.multibody.tree.RigidBody_[AutoDiffXd]: Returns a const reference to the parent body P.

position_lower_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: @name Methods to get and set the limits of this 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.

position_start(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → int: Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system.

position_suffix(self: pydrake.multibody.tree.Joint_[AutoDiffXd], arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th position in this joint. ``position_index_in_joint` must be in [0, num_positions()).

Precondition:: the MultibodyPlant must be finalized.

position_upper_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the position upper limits.

set_acceleration_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the acceleration limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

set_default_damping_vector(self: pydrake.multibody.tree.Joint_[AutoDiffXd], damping: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default value of the viscous damping coefficients for this joint. Refer to default_damping_vector() for details.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Precondition:: the MultibodyPlant must not be finalized.

set_default_positions(self: pydrake.multibody.tree.Joint_[AutoDiffXd], default_positions: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default positions to default_positions. Joint subclasses are expected to implement the do_set_default_positions().

Raises

RuntimeError 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(self: pydrake.multibody.tree.Joint_[AutoDiffXd], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the position limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_positions() –
RuntimeError 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(self: pydrake.multibody.tree.Joint_[AutoDiffXd], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the velocity limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

SetDampingVector(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], damping: numpy.ndarray[object[m, 1]]) → None

Sets the value of the viscous damping coefficients for this joint, stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter damping:: The vector of damping values.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Note

Some multi-dof joints may have specific semantics for their damping vector that are not enforced here. For instance, QuaternionFloatingJoint assumes identical damping values for all 3 angular velocity components and identical damping values for all 3 translational velocity components. It will thus use angular_damping = damping[0] and translational_damping = damping[3]. Refer to the particular subclass for more semantic information.

SetDefaultPose(self: pydrake.multibody.tree.Joint_[AutoDiffXd], X_FM: pydrake.math.RigidTransform) → None

Sets this Joint’s default generalized positions q₀ such that the pose of the child frame M in the parent frame F best matches the given pose. The pose is given by a RigidTransform X_FM, but a Joint will represent pose differently.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

See also

get_default_positions() to see the resulting q₀ after this call.

See also

SetDefaultPosePair() for an alternative using a quaternion

SetDefaultPosePair(self: pydrake.multibody.tree.Joint_[AutoDiffXd], q_FM: pydrake.common.eigen_geometry.Quaternion, p_FM: numpy.ndarray[numpy.float64[3, 1]]) → None: (Advanced) This is the same as SetDefaultPose() except it takes the pose as a (quaternion, translation vector) pair.

See also

SetDefaultPose() for more information

type_name(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → str: Returns a string identifying the type of this joint, such as “revolute” or “prismatic”.

Unlock(self: pydrake.multibody.tree.Joint_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → None: Unlock the joint.

velocity_lower_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity lower limits.

velocity_start(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → int: Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system.

velocity_suffix(self: pydrake.multibody.tree.Joint_[AutoDiffXd], arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th velocity in this joint. ``velocity_index_in_joint` must be in [0, num_velocities()).

Precondition:: the MultibodyPlant must be finalized.

velocity_upper_limits(self: pydrake.multibody.tree.Joint_[AutoDiffXd]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity upper limits.

class pydrake.multibody.tree.Joint_[Expression]

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. @image html drake/multibody/plant/images/BodyParentChildJoint.png width=50%

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:

Click to expand C++ code...

MultibodyPlant<double> plant(0.0);
// ... Code here to setup quantities below as mass, com, etc. ...
const RigidBody<double>& pendulum =
  plant.AddRigidBody(SpatialInertia<double>(mass, com, unit_inertia));
// 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 =
  plant.AddJoint<RevoluteJoint>(
    "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.

__init__(*args, **kwargs)

acceleration_lower_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration lower limits.

acceleration_upper_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the acceleration upper limits.

AddInDamping(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression], forces: drake::multibody::MultibodyForces<drake::symbolic::Expression>) → None

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

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.

AddInOneForce(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression], joint_dof: int, joint_tau: pydrake.symbolic.Expression, forces: drake::multibody::MultibodyForces<drake::symbolic::Expression>) → None

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.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter 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.
Parameter joint_tau:: Generalized force corresponding to the degree of freedom indicated by joint_dof to be added into forces.
Parameter 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.

can_rotate(self: pydrake.multibody.tree.Joint_[Expression]) → bool

Returns true if this joint’s mobility allows relative rotation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_translate()

can_translate(self: pydrake.multibody.tree.Joint_[Expression]) → bool

Returns true if this joint’s mobility allows relative translation of the two frames associated with this joint.

Precondition:: the MultibodyPlant must be finalized.

See also

can_rotate()

child_body(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.multibody.tree.RigidBody_[Expression]: Returns a const reference to the child body B.

default_damping_vector(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns all default damping coefficients for joints that model viscous damping, of size num_velocities(). Joints that do not model damping return a zero vector of size num_velocities(). If vj is the vector of generalized velocities for this joint, of size num_velocities(), viscous damping models a generalized force at the joint of the form tau = -diag(dj)⋅vj, with dj the vector returned by this function. The units of the coefficients will depend on the specific joint type. For instance, for a revolute joint where vj is an angular velocity with units of rad/s and tau having units of N⋅m, the coefficient of viscous damping has units of N⋅m⋅s. Refer to each joint’s documentation for further details.

default_positions(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the default positions.

frame_on_child(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.multibody.tree.Frame_[Expression]: Returns a const reference to the frame M attached on the child body B.

frame_on_parent(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.multibody.tree.Frame_[Expression]: Returns a const reference to the frame F attached on the parent body P.

GetDampingVector(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → numpy.ndarray[object[m, 1]]

Returns the Context dependent damping coefficients stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.

GetDefaultPose(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.math.RigidTransform

Returns this Joint’s default pose as a RigidTransform X_FM.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

Returns X_FM:: The default pose as a rigid transform.

See also

get_default_positions() to see the generalized positions q₀ that this joint used to generate the returned transform.

GetDefaultPosePair(self: pydrake.multibody.tree.Joint_[Expression]) → tuple[pydrake.common.eigen_geometry.Quaternion, numpy.ndarray[numpy.float64[3, 1]]]

(Advanced) This is the same as GetDefaultPose() except it returns this Joint’s default pose as a (quaternion, translation vector) pair.

Returns q_FM:: ,p_FM The default pose as a (quaternion, translation) pair.

See also

GetDefaultPose() for more information

GetOnePosition(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetOneVelocity(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

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

Raises

RuntimeError if the joint does not have a single degree of –
freedom. –

GetParentPlant(self: pydrake.multibody.tree.Joint_[Expression]) → drake::multibody::MultibodyPlant<drake::symbolic::Expression>

index(*args, **kwargs)

Overloaded function.

index(self: pydrake.multibody.tree.Joint_[Expression]) -> pydrake.multibody.tree.JointIndex
index(self: pydrake.multibody.tree.Joint_[Expression]) -> pydrake.multibody.tree.JointIndex

Returns this element’s unique index.

is_locked(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → bool

Returns: true if the joint is locked, false otherwise.

Lock(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → None: Lock the joint. Its generalized velocities will be 0 until it is unlocked.

model_instance(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.Joint_[Expression]) → str: Returns the name of this joint.

num_positions(self: pydrake.multibody.tree.Joint_[Expression]) → int: Returns the number of generalized positions describing this joint.

num_velocities(self: pydrake.multibody.tree.Joint_[Expression]) → int: Returns the number of generalized velocities describing this joint.

parent_body(self: pydrake.multibody.tree.Joint_[Expression]) → pydrake.multibody.tree.RigidBody_[Expression]: Returns a const reference to the parent body P.

position_lower_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: @name Methods to get and set the limits of this 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.

position_start(self: pydrake.multibody.tree.Joint_[Expression]) → int: Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system.

position_suffix(self: pydrake.multibody.tree.Joint_[Expression], arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th position in this joint. ``position_index_in_joint` must be in [0, num_positions()).

Precondition:: the MultibodyPlant must be finalized.

position_upper_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the position upper limits.

set_acceleration_limits(self: pydrake.multibody.tree.Joint_[Expression], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the acceleration limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

set_default_damping_vector(self: pydrake.multibody.tree.Joint_[Expression], damping: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default value of the viscous damping coefficients for this joint. Refer to default_damping_vector() for details.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Precondition:: the MultibodyPlant must not be finalized.

set_default_positions(self: pydrake.multibody.tree.Joint_[Expression], default_positions: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the default positions to default_positions. Joint subclasses are expected to implement the do_set_default_positions().

Raises

RuntimeError 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(self: pydrake.multibody.tree.Joint_[Expression], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the position limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_positions() –
RuntimeError 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(self: pydrake.multibody.tree.Joint_[Expression], lower_limits: numpy.ndarray[numpy.float64[m, 1]], upper_limits: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the velocity limits to lower_limits and upper_limits.

Raises

RuntimeError if the dimension of lower_limits or –
upper_limits` does not match num_velocities() –
RuntimeError if any of lower_limits is larger than the –
corresponding term in upper_limits. –

SetDampingVector(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression], damping: numpy.ndarray[object[m, 1]]) → None

Sets the value of the viscous damping coefficients for this joint, stored as parameters in context. Refer to default_damping_vector() for details.

Parameter context:: The context storing the state and parameters for the model to which this joint belongs.
Parameter damping:: The vector of damping values.

Raises

RuntimeError if damping.size() != num_velocities() –
RuntimeError if any of the damping coefficients is negative. –

Note

Some multi-dof joints may have specific semantics for their damping vector that are not enforced here. For instance, QuaternionFloatingJoint assumes identical damping values for all 3 angular velocity components and identical damping values for all 3 translational velocity components. It will thus use angular_damping = damping[0] and translational_damping = damping[3]. Refer to the particular subclass for more semantic information.

SetDefaultPose(self: pydrake.multibody.tree.Joint_[Expression], X_FM: pydrake.math.RigidTransform) → None

Sets this Joint’s default generalized positions q₀ such that the pose of the child frame M in the parent frame F best matches the given pose. The pose is given by a RigidTransform X_FM, but a Joint will represent pose differently.

Note

Currently this is implemented only for floating (6 dof) joints which can represent any pose.

Raises

RuntimeError if called for any Joint type that does not implement –
this function. –

See also

get_default_positions() to see the resulting q₀ after this call.

See also

SetDefaultPosePair() for an alternative using a quaternion

SetDefaultPosePair(self: pydrake.multibody.tree.Joint_[Expression], q_FM: pydrake.common.eigen_geometry.Quaternion, p_FM: numpy.ndarray[numpy.float64[3, 1]]) → None: (Advanced) This is the same as SetDefaultPose() except it takes the pose as a (quaternion, translation vector) pair.

See also

SetDefaultPose() for more information

type_name(self: pydrake.multibody.tree.Joint_[Expression]) → str: Returns a string identifying the type of this joint, such as “revolute” or “prismatic”.

Unlock(self: pydrake.multibody.tree.Joint_[Expression], context: pydrake.systems.framework.Context_[Expression]) → None: Unlock the joint.

velocity_lower_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity lower limits.

velocity_start(self: pydrake.multibody.tree.Joint_[Expression]) → int: Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system.

velocity_suffix(self: pydrake.multibody.tree.Joint_[Expression], arg0: int) → str

Returns a string suffix (e.g. to be appended to the name()) to identify the k`th velocity in this joint. ``velocity_index_in_joint` must be in [0, num_velocities()).

Precondition:: the MultibodyPlant must be finalized.

velocity_upper_limits(self: pydrake.multibody.tree.Joint_[Expression]) → numpy.ndarray[numpy.float64[m, 1]]: Returns the velocity upper limits.

class pydrake.multibody.tree.JointActuator

The JointActuator class is mostly a simple bookkeeping structure to represent an actuator acting on a given Joint. It helps to flag whether a given Joint is actuated or not so that MultibodyTree clients can apply forces on actuated joints through their actuators, see AddInOneForce().

Note

This class is templated; see JointActuator_ for the list of instantiations.

__init__(*args, **kwargs)

calc_reflected_inertia(self: pydrake.multibody.tree.JointActuator, context: pydrake.systems.framework.Context) → float: Calculates the reflected inertia value for this actuator in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

default_gear_ratio(self: pydrake.multibody.tree.JointActuator) → float: Gets the default value for this actuator’s gear ratio. See reflected_inertia.

default_reflected_inertia(self: pydrake.multibody.tree.JointActuator) → float: Returns the default value for this actuator’s reflected inertia. It is calculated as ρ²⋅Iᵣ, where ρ is the default gear ratio and Iᵣ is the default rotor inertia for this actuator. See reflected_inertia.

default_rotor_inertia(self: pydrake.multibody.tree.JointActuator) → float: Gets the default value for this actuator’s rotor inertia. See reflected_inertia.

effort_limit(self: pydrake.multibody.tree.JointActuator) → float: Returns the actuator effort limit.

gear_ratio(self: pydrake.multibody.tree.JointActuator, context: pydrake.systems.framework.Context) → float: Returns the associated gear ratio value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

get_actuation_vector(self: pydrake.multibody.tree.JointActuator, u: numpy.ndarray[numpy.float64[m, 1]]) → numpy.ndarray[numpy.float64[m, 1]]

Gets the actuation values for this actuator from the actuation vector u for the entire plant model.

Returns: a reference to a nv-dimensional vector, where nv is the number of velocity variables of joint().

get_controller_gains(self: pydrake.multibody.tree.JointActuator) → pydrake.multibody.tree.PdControllerGains

Returns a reference to the controller gains for this actuator.

Precondition:: has_controller() is True.

GetParentPlant(self: pydrake.multibody.tree.JointActuator) → drake::multibody::MultibodyPlant<double>

has_controller(self: pydrake.multibody.tree.JointActuator) → bool: Returns True if controller gains have been specified with a call to set_controller_gains().

index(self: pydrake.multibody.tree.JointActuator) → pydrake.multibody.tree.JointActuatorIndex

input_start(self: pydrake.multibody.tree.JointActuator) → int

Returns the index to the first element for this joint actuator / within the vector of actuation inputs for the full multibody / system.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

joint(self: pydrake.multibody.tree.JointActuator) → pydrake.multibody.tree.Joint: Returns a reference to the joint actuated by this JointActuator.

model_instance(self: pydrake.multibody.tree.JointActuator) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.JointActuator) → str: Returns the name of the actuator.

num_inputs(self: pydrake.multibody.tree.JointActuator) → int

Returns the number of inputs associated with this actuator.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

rotor_inertia(self: pydrake.multibody.tree.JointActuator, context: pydrake.systems.framework.Context) → float: Returns the associated rotor inertia value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

set_actuation_vector(self: pydrake.multibody.tree.JointActuator, u_actuator: numpy.ndarray[numpy.float64[m, 1]], u: Optional[numpy.ndarray[numpy.float64[m, 1], flags.writeable]]) → None

Given the actuation values u_actuator for this actuator, updates the actuation vector u for the entire multibody model to which this actuator belongs to.

Parameter u_actuator:: Actuation values for this actuator. It must be of size equal to num_inputs(). For units and sign conventions refer to the specific Joint sub-class documentation.
Parameter u:: Actuation values for the entire plant model to which this actuator belongs to. The actuation value in u for this actuator must be found at offset input_start(). Only values corresponding to this actuator are changed.

Raises

RuntimeError if u_actuator.size() != this->num_inputs() –
RuntimeError if u is nullptr. –
RuntimeError if ``u.size() != –
this->GetParentPlant()num_actuated_dofs()``. –

set_controller_gains(self: pydrake.multibody.tree.JointActuator, gains: pydrake.multibody.tree.PdControllerGains) → None

Set controller gains for this joint actuator. This enables the modeling of a simple PD controller of the form: ũ = -Kp⋅(q − qd) - Kd⋅(v − vd) + u_ff u = max(−e, min(e, ũ)) where qd and vd are the desired configuration and velocity for joint(), Kp and Kd are the proportional and derivative gains specified in gains, u_ff is the feedforward actuation and e corresponds to effort_limit().

For simulation, feedforward actuation can be provided through MultibodyPlant::get_actuation_input_port(). Desired configuration and velocity are specified through MultibodyPlant::get_desired_state_input_port().

Precondition:: The MultibodyPlant associated with this actuator has not yet allocated a Context. In other words, although gains can be changed post-Finalize, they cannot be changed during simulation.

Raises

iff the proportional gain is not strictly positive or if the –
derivative gain is negative. –
iff the owning MultibodyPlant is finalized and no gains were set –
pre-finalize. In other words, editing gains post-finalize is –
fine, but adding gains post-finalize is an error. See –
MultibodyPlant::Finalize() –

set_default_gear_ratio(self: pydrake.multibody.tree.JointActuator, gear_ratio: float) → None: Sets the default value for this actuator’s gear ratio. See reflected_inertia.

set_default_rotor_inertia(self: pydrake.multibody.tree.JointActuator, rotor_inertia: float) → None: Sets the default value for this actuator’s rotor inertia. See reflected_inertia.

SetGearRatio(self: pydrake.multibody.tree.JointActuator, context: pydrake.systems.framework.Context, gear_ratio: float) → None: Sets the associated gear ratio value for this actuator in context. See reflected_inertia.

SetRotorInertia(self: pydrake.multibody.tree.JointActuator, context: pydrake.systems.framework.Context, rotor_inertia: float) → None: Sets the associated rotor inertia value for this actuator in context. See reflected_inertia.

template pydrake.multibody.tree.JointActuator_: Instantiations: JointActuator_[float], JointActuator_[AutoDiffXd], JointActuator_[Expression]

class pydrake.multibody.tree.JointActuator_[AutoDiffXd]

The JointActuator class is mostly a simple bookkeeping structure to represent an actuator acting on a given Joint. It helps to flag whether a given Joint is actuated or not so that MultibodyTree clients can apply forces on actuated joints through their actuators, see AddInOneForce().

__init__(*args, **kwargs)

calc_reflected_inertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd: Calculates the reflected inertia value for this actuator in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

default_gear_ratio(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → float: Gets the default value for this actuator’s gear ratio. See reflected_inertia.

default_reflected_inertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → float: Returns the default value for this actuator’s reflected inertia. It is calculated as ρ²⋅Iᵣ, where ρ is the default gear ratio and Iᵣ is the default rotor inertia for this actuator. See reflected_inertia.

default_rotor_inertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → float: Gets the default value for this actuator’s rotor inertia. See reflected_inertia.

effort_limit(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → float: Returns the actuator effort limit.

gear_ratio(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd: Returns the associated gear ratio value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

get_actuation_vector(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], u: numpy.ndarray[object[m, 1]]) → numpy.ndarray[object[m, 1]]

Gets the actuation values for this actuator from the actuation vector u for the entire plant model.

Returns: a reference to a nv-dimensional vector, where nv is the number of velocity variables of joint().

get_controller_gains(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → pydrake.multibody.tree.PdControllerGains

Returns a reference to the controller gains for this actuator.

Precondition:: has_controller() is True.

GetParentPlant(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → drake::multibody::MultibodyPlant<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

has_controller(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → bool: Returns True if controller gains have been specified with a call to set_controller_gains().

index(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → pydrake.multibody.tree.JointActuatorIndex

input_start(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → int

Returns the index to the first element for this joint actuator / within the vector of actuation inputs for the full multibody / system.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

joint(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → pydrake.multibody.tree.Joint_[AutoDiffXd]: Returns a reference to the joint actuated by this JointActuator.

model_instance(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → str: Returns the name of the actuator.

num_inputs(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd]) → int

Returns the number of inputs associated with this actuator.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

rotor_inertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd: Returns the associated rotor inertia value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

set_actuation_vector(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], u_actuator: numpy.ndarray[object[m, 1]], u: Optional[numpy.ndarray[object[m, 1], flags.writeable]]) → None

Given the actuation values u_actuator for this actuator, updates the actuation vector u for the entire multibody model to which this actuator belongs to.

Parameter u_actuator:: Actuation values for this actuator. It must be of size equal to num_inputs(). For units and sign conventions refer to the specific Joint sub-class documentation.
Parameter u:: Actuation values for the entire plant model to which this actuator belongs to. The actuation value in u for this actuator must be found at offset input_start(). Only values corresponding to this actuator are changed.

Raises

RuntimeError if u_actuator.size() != this->num_inputs() –
RuntimeError if u is nullptr. –
RuntimeError if ``u.size() != –
this->GetParentPlant()num_actuated_dofs()``. –

set_controller_gains(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], gains: pydrake.multibody.tree.PdControllerGains) → None

Set controller gains for this joint actuator. This enables the modeling of a simple PD controller of the form: ũ = -Kp⋅(q − qd) - Kd⋅(v − vd) + u_ff u = max(−e, min(e, ũ)) where qd and vd are the desired configuration and velocity for joint(), Kp and Kd are the proportional and derivative gains specified in gains, u_ff is the feedforward actuation and e corresponds to effort_limit().

For simulation, feedforward actuation can be provided through MultibodyPlant::get_actuation_input_port(). Desired configuration and velocity are specified through MultibodyPlant::get_desired_state_input_port().

Precondition:: The MultibodyPlant associated with this actuator has not yet allocated a Context. In other words, although gains can be changed post-Finalize, they cannot be changed during simulation.

Raises

iff the proportional gain is not strictly positive or if the –
derivative gain is negative. –
iff the owning MultibodyPlant is finalized and no gains were set –
pre-finalize. In other words, editing gains post-finalize is –
fine, but adding gains post-finalize is an error. See –
MultibodyPlant::Finalize() –

set_default_gear_ratio(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], gear_ratio: float) → None: Sets the default value for this actuator’s gear ratio. See reflected_inertia.

set_default_rotor_inertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], rotor_inertia: float) → None: Sets the default value for this actuator’s rotor inertia. See reflected_inertia.

SetGearRatio(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], gear_ratio: pydrake.autodiffutils.AutoDiffXd) → None: Sets the associated gear ratio value for this actuator in context. See reflected_inertia.

SetRotorInertia(self: pydrake.multibody.tree.JointActuator_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], rotor_inertia: pydrake.autodiffutils.AutoDiffXd) → None: Sets the associated rotor inertia value for this actuator in context. See reflected_inertia.

class pydrake.multibody.tree.JointActuator_[Expression]

The JointActuator class is mostly a simple bookkeeping structure to represent an actuator acting on a given Joint. It helps to flag whether a given Joint is actuated or not so that MultibodyTree clients can apply forces on actuated joints through their actuators, see AddInOneForce().

__init__(*args, **kwargs)

calc_reflected_inertia(self: pydrake.multibody.tree.JointActuator_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression: Calculates the reflected inertia value for this actuator in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

default_gear_ratio(self: pydrake.multibody.tree.JointActuator_[Expression]) → float: Gets the default value for this actuator’s gear ratio. See reflected_inertia.

default_reflected_inertia(self: pydrake.multibody.tree.JointActuator_[Expression]) → float: Returns the default value for this actuator’s reflected inertia. It is calculated as ρ²⋅Iᵣ, where ρ is the default gear ratio and Iᵣ is the default rotor inertia for this actuator. See reflected_inertia.

default_rotor_inertia(self: pydrake.multibody.tree.JointActuator_[Expression]) → float: Gets the default value for this actuator’s rotor inertia. See reflected_inertia.

effort_limit(self: pydrake.multibody.tree.JointActuator_[Expression]) → float: Returns the actuator effort limit.

gear_ratio(self: pydrake.multibody.tree.JointActuator_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression: Returns the associated gear ratio value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

get_actuation_vector(self: pydrake.multibody.tree.JointActuator_[Expression], u: numpy.ndarray[object[m, 1]]) → numpy.ndarray[object[m, 1]]

Gets the actuation values for this actuator from the actuation vector u for the entire plant model.

Returns: a reference to a nv-dimensional vector, where nv is the number of velocity variables of joint().

get_controller_gains(self: pydrake.multibody.tree.JointActuator_[Expression]) → pydrake.multibody.tree.PdControllerGains

Returns a reference to the controller gains for this actuator.

Precondition:: has_controller() is True.

GetParentPlant(self: pydrake.multibody.tree.JointActuator_[Expression]) → drake::multibody::MultibodyPlant<drake::symbolic::Expression>

has_controller(self: pydrake.multibody.tree.JointActuator_[Expression]) → bool: Returns True if controller gains have been specified with a call to set_controller_gains().

index(self: pydrake.multibody.tree.JointActuator_[Expression]) → pydrake.multibody.tree.JointActuatorIndex

input_start(self: pydrake.multibody.tree.JointActuator_[Expression]) → int

Returns the index to the first element for this joint actuator / within the vector of actuation inputs for the full multibody / system.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

joint(self: pydrake.multibody.tree.JointActuator_[Expression]) → pydrake.multibody.tree.Joint_[Expression]: Returns a reference to the joint actuated by this JointActuator.

model_instance(self: pydrake.multibody.tree.JointActuator_[Expression]) → pydrake.multibody.tree.ModelInstanceIndex

name(self: pydrake.multibody.tree.JointActuator_[Expression]) → str: Returns the name of the actuator.

num_inputs(self: pydrake.multibody.tree.JointActuator_[Expression]) → int

Returns the number of inputs associated with this actuator.

Raises: RuntimeError if the MultibodyTree model is not finalized. –

rotor_inertia(self: pydrake.multibody.tree.JointActuator_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression: Returns the associated rotor inertia value for this actuator, stored in context. See reflected_inertia. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

set_actuation_vector(self: pydrake.multibody.tree.JointActuator_[Expression], u_actuator: numpy.ndarray[object[m, 1]], u: Optional[numpy.ndarray[object[m, 1], flags.writeable]]) → None

Given the actuation values u_actuator for this actuator, updates the actuation vector u for the entire multibody model to which this actuator belongs to.

Parameter u_actuator:: Actuation values for this actuator. It must be of size equal to num_inputs(). For units and sign conventions refer to the specific Joint sub-class documentation.
Parameter u:: Actuation values for the entire plant model to which this actuator belongs to. The actuation value in u for this actuator must be found at offset input_start(). Only values corresponding to this actuator are changed.

Raises

RuntimeError if u_actuator.size() != this->num_inputs() –
RuntimeError if u is nullptr. –
RuntimeError if ``u.size() != –
this->GetParentPlant()num_actuated_dofs()``. –

set_controller_gains(self: pydrake.multibody.tree.JointActuator_[Expression], gains: pydrake.multibody.tree.PdControllerGains) → None

Set controller gains for this joint actuator. This enables the modeling of a simple PD controller of the form: ũ = -Kp⋅(q − qd) - Kd⋅(v − vd) + u_ff u = max(−e, min(e, ũ)) where qd and vd are the desired configuration and velocity for joint(), Kp and Kd are the proportional and derivative gains specified in gains, u_ff is the feedforward actuation and e corresponds to effort_limit().

For simulation, feedforward actuation can be provided through MultibodyPlant::get_actuation_input_port(). Desired configuration and velocity are specified through MultibodyPlant::get_desired_state_input_port().

Precondition:: The MultibodyPlant associated with this actuator has not yet allocated a Context. In other words, although gains can be changed post-Finalize, they cannot be changed during simulation.

Raises

iff the proportional gain is not strictly positive or if the –
derivative gain is negative. –
iff the owning MultibodyPlant is finalized and no gains were set –
pre-finalize. In other words, editing gains post-finalize is –
fine, but adding gains post-finalize is an error. See –
MultibodyPlant::Finalize() –

set_default_gear_ratio(self: pydrake.multibody.tree.JointActuator_[Expression], gear_ratio: float) → None: Sets the default value for this actuator’s gear ratio. See reflected_inertia.

set_default_rotor_inertia(self: pydrake.multibody.tree.JointActuator_[Expression], rotor_inertia: float) → None: Sets the default value for this actuator’s rotor inertia. See reflected_inertia.

SetGearRatio(self: pydrake.multibody.tree.JointActuator_[Expression], context: pydrake.systems.framework.Context_[Expression], gear_ratio: pydrake.symbolic.Expression) → None: Sets the associated gear ratio value for this actuator in context. See reflected_inertia.

SetRotorInertia(self: pydrake.multibody.tree.JointActuator_[Expression], context: pydrake.systems.framework.Context_[Expression], rotor_inertia: pydrake.symbolic.Expression) → None: Sets the associated rotor inertia value for this actuator in context. See reflected_inertia.

class pydrake.multibody.tree.JointActuatorIndex

Type used to identify actuators by index within a multibody plant.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.JointActuatorIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

__init__(self: pydrake.multibody.tree.JointActuatorIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.multibody.tree.JointActuatorIndex) → bool: Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.multibody.tree.JointIndex

Type used to identify joints by index within a multibody plant.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.multibody.tree.JointIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

__init__(self: pydrake.multibody.tree.JointIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.multibody.tree.JointIndex) → bool: Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.multibody.tree.LinearBushingRollPitchYaw

Bases: pydrake.multibody.tree.ForceElement

This ForceElement models a massless flexible bushing that connects a frame A of a link (body) L0 to a frame C of a link (body) L1. The bushing can apply a torque and force due to stiffness (spring) and dissipation (damper) properties. Frame B is the bushing frame whose origin Bo is halfway between Ao (A’s origin) and Co (C’s origin) and whose unit vectors 𝐁𝐱, 𝐁𝐲, 𝐁𝐳 are “halfway” (in an angle-axis sense) between the unit vectors of frame A and frame C. Frame B is a “floating” frame in the sense that it is calculated from the position and orientation of frames A and C (B is not welded to the bushing).

@image html drake/multibody/tree/images/LinearBushingRollPitchYaw.png width=80%

The set of forces on frame C from the bushing is equivalent to a torque 𝐭 on frame C and a force 𝐟 applied to a point Cp of C. The set of forces on frame A from the bushing is equivalent to a torque −𝐭 on frame A and a force −𝐟 applied to a point Ap of A. Points Ap and Cp are coincident with Bo (frame B’s origin).

This “quasi-symmetric” bushing force/torque model was developed at Toyota Research Institute and has advantages compared to traditional bushing models because it employs a bushing-centered “symmetric” frame B and it ensures the moment of −𝐟 on A about Ao is equal to the moment of 𝐟 on C about Co. Traditional models differ as they lack a “symmetric” frame B and apply −𝐟 at Ao, which means the moment of −𝐟 on A about Ao is always zero. Note: This bushing model is not fully symmetric since the orientation between frames A and C is parameterized with roll-pitch-yaw angles [q₀ q₁ q₂]. Since these angles have an inherent sequence, they are not mathematically symmetric.

The torque model depends on spring-damper “gimbal” torques τ ≜ [τ₀ τ₁ τ₂] which themselves depend on roll-pitch-yaw angles q ≜ [q₀ q₁ q₂] and rates q̇ = [q̇₀ q̇₁ q̇₂] via a diagonal torque-stiffness matrix K₀₁₂ and a diagonal torque-damping matrix D₀₁₂ as

Click to expand C++ code...

⌈ τ₀ ⌉     ⌈k₀    0    0⌉ ⌈ q₀ ⌉     ⌈d₀    0    0⌉ ⌈ q̇₀ ⌉
τ ≜ | τ₁ | = − | 0   k₁    0| | q₁ |  −  | 0   d₁    0| | q̇₁ |
    ⌊ τ₂ ⌋     ⌊ 0    0   k₂⌋ ⌊ q₂ ⌋     ⌊ 0    0   d₂⌋ ⌊ q̇₂ ⌋

where k₀, k₁, k₂ and d₀, d₁, d₂ are torque stiffness and damping constants and must have non-negative values.

Note

τ does not represent a vector expressed in one frame. Instead it is regarded as a 3x1 array of torque scalars associated with roll-pitch yaw.

Note

As discussed in the Advanced section below, τ is not 𝐭 (τ ≠ 𝐭).

Note

This is a “linear” bushing model as gimbal torque τ varies linearly with q and q̇ as τ = τᴋ + τᴅ where τᴋ = −K₀₁₂ ⋅ q and τᴅ = −D₀₁₂ ⋅ q̇.

The bushing model for the net force 𝐟 on frame C from the bushing depends on scalars x, y, z which are defined so 𝐫 (the position vector from Ao to Co) can be expressed in frame B as 𝐫 ≜ p_AoCo = [x y z]ʙ = x 𝐁𝐱 + y 𝐁𝐲 + z 𝐁𝐳. The model for 𝐟 uses a diagonal force-stiffness matrix Kxyᴢ, a diagonal force-damping matrix Dxyᴢ, and defines fx, fy, fz so 𝐟 = [fx fy fz]ʙ.

Click to expand C++ code...

⌈ fx ⌉      ⌈kx    0    0⌉ ⌈ x ⌉     ⌈dx    0    0⌉ ⌈ ẋ ⌉
| fy | =  − | 0   ky    0| | y |  −  | 0   dy    0| | ẏ |
⌊ fz ⌋      ⌊ 0    0   kz⌋ ⌊ z ⌋     ⌊ 0    0   dz⌋ ⌊ ż ⌋

where kx, ky, kz and dx, dy, dz are force stiffness and damping constants and must have non-negative values.

Note

This is a “linear” bushing model as the force 𝐟 varies linearly with 𝐫 and 𝐫̇̇ as 𝐟 = 𝐟ᴋ + 𝐟ᴅ where 𝐟ᴋ = −Kxyz ⋅ 𝐫 and 𝐟ᴅ = −Dxyz ⋅ 𝐫̇̇.

This bushing’s constructor sets the torque stiffness/damping constants [k₀ k₁ k₂] and [d₀ d₁ d₂] and the force stiffness/damping constants [kx ky kz] and [dx dy dz]. The examples below demonstrate how to model various joints that have a flexible (e.g., rubber) mount. The damping values below with ? may be set to 0 or a reasonable positive number.

Bushing type | torque constants | force constants ——————————–|:--------------------|:—————— z-axis revolute joint | k₀₁₂ = [k₀ k₁ 0] | kxyz = [kx ky kz] ^ | d₀₁₂ = [d₀ d₁ ?] | dxyz = [dx dy dz] x-axis prismatic joint | k₀₁₂ = [k₀ k₁ k₂] | kxyz = [0 ky kz] ^ | d₀₁₂ = [d₀ d₁ d₂] | dxyz = [? dy dz] Ball and socket joint | k₀₁₂ = [0 0 0] | kxyz = [kx ky kz] ^ | d₀₁₂ = [? ? ?] | dxyz = [dx dy dz] Weld/fixed joint | k₀₁₂ = [k₀ k₁ k₂] | kxyz = [kx ky kz] ^ | d₀₁₂ = [d₀ d₁ d₂] | dxyz = [dx dy dz]

Angles q₀, q₁, q₂ are calculated from frame C’s orientation relative to frame A, with [−π < q₀ ≤ π, −π/2 ≤ q₁ ≤ π/2, −π < q₂ ≤ π], hence, there is no angle wrapping and torque stiffness has a limited range. Gimbal torques τ can be discontinuous if one of q₀, q₁, q₂ is discontinuous and its associated torque spring constant is nonzero. For example, τ₂ is discontinuous if k₂ ≠ 0 and the bushing has a large rotation so q₂ jumps from ≈ −π to π. τ can also be discontinuous if one of q̇₀, q̇₁, q̇₂ is discontinuous and its associated torque damper constant is nonzero. For example, τ₀ is discontinuous if d₀ ≠ 0 and q̇₀ is undefined (which occurs when pitch = q₁ = π/2). Note: Due to the relationship of 𝐭 to τ shown below, 𝐭 is discontinuous if τ is discontinuous.

As shown below, there are multiple ways to estimate torque and force stiffness and damping constants. Use a method or combination of methods appropriate for your application. For example, some methods are more useful for a real physical bushing whereas other methods (called “penalty methods”) can be more useful when replacing an ideal joint (such as a revolute or fixed/weld joint) with a bushing.

Consider a penalty method if you want a bushing to substitute for a “hard” constraint (e.g., an ideal joint). Since a bushing is inherently compliant it will violate a hard constraint somewhat. The stiffer the bushing, the more accurately it enforces the hard constraint, but at a cost of more computational time. To balance accuracy versus time, consider your tolerance for constraint errors. For example, is it OK for your bushing to displace xₘₐₓ = 1 mm for an estimated Fxₘₐₓ = 100 N? Also, one way to choose a force damping constant dx is by choosing a “reasonably small” settling time tₛ, where settling time tₛ is the interval of time for a system to settle to within 1% (0.01) of an equilibrium solution). Is tₛ = 0.01 s negligible for a robot arm with a 10 s reach maneuver?

**** How to choose a torque stiffness constant k₀ or damping constant d₀. The estimate of stiffness k₀ depends on whether you are modeling a physical bushing (consider stiffness methods 1 or 2 below) or whether you are using a bushing to replace an ideal joint such as a revolute or fixed/weld joint (consider stiffness “penalty methods” 3 or 4 below). 1. Use a static experiment, e.g., apply a known moment load Mx, measure the associated angular displacement Δq (radians), and estimate k₀ = Mx / Δq. 2. Use FEA (finite element analysis) software to estimate k₀. 3. Pick a desired maximum angular displacement qₘₐₓ, estimate a maximum moment load Mxₘₐₓ, and estimate k₀ = Mxₘₐₓ / qₘₐₓ (units of N*m/rad). 4. Choose a characteristic moment of inertia I₀ (directionally dependent), choose a desired angular frequency ωₙ > 0 (in rad/s) and estimate k₀ = I₀ ωₙ² (units of N*m/rad).

The estimate of damping d₀ depends on whether you are modeling a physical bushing (consider damping method 1 below) or whether you are using a bushing to enforce a constraint (consider damping methods 2 or 3 below). 1. Use experiments to estimate a damping ratio ζ and settling time tₛ. Compute “undamped natural frequency” ωₙ from ζ and tₛ (as shown below in the Advanced section), then d₀ = 2 ζ k₀ / ωₙ (units of N*m*s/rad). 2. Choose a damping ratio ζ (e.g., ζ = 1, critical damping) and a desired settling time tₛ, calculate ωₙ (as shown below in the Advanced section), then d₀ = 2 ζ k₀ / ωₙ (units of N*m*s/rad). 3. Choose a damping ratio ζ (e.g., ζ = 1, critical damping), estimate a characteristic moment of inertia and calculate d₀ = 2 ζ √(I₀ k₀).

Refer to Advanced_bushing_stiffness_and_damping “Advanced bushing stiffness and damping” for more details.

**** How to choose a force stiffness constant kx or damping constant dx. The estimate of stiffness kx depends on whether you are modeling a real bushing (consider stiffness methods 1 or 2 below) or whether you are using a bushing to replace an ideal joint such as a revolute or fixed/weld joint (consider stiffness “penalty methods” 3 or 4 below). 1. Use a static experiment, e.g., apply a known force load Fx, measure the associated displacement (stretch) Δx (in meters), and estimate kx = Fx / Δx. 2. Use FEA (finite element analysis) software to estimate kx (units of N/m). 3. Pick a desired maximum displacement xₘₐₓ, estimate a maximum force load Fxₘₐₓ, and estimate kx = Fxₘₐₓ / xₘₐₓ (units of N/m). 4. Choose a characteristic mass m (which may be directionally dependent), choose a desired angular frequency ωₙ > 0 (in rad/s) and estimate kx = m ωₙ² (units of N/m).

The estimate of damping dx depends on whether you are modeling a physical bushing (consider damping method 1 below) or whether you are using a bushing to enforce a constraint (consider damping methods 2 or 3 below). 1. Use experiments to estimate a damping ratio ζ and settling time tₛ. Compute “undamped natural frequency” ωₙ from ζ and tₛ (as shown below in the Advanced section), then dx = 2 ζ kx / ωₙ (units of N*s/m). 2. Choose a damping ratio ζ (e.g., ζ = 1, critical damping) and a desired settling time tₛ, calculate ωₙ (as shown below in the Advanced section), then dx = 2 ζ kx / ωₙ (units of N*s/m). 3. Choose a damping ratio ζ (e.g., ζ = 1, critical damping), estimate a characteristic mass m and calculate dx = 2 ζ √(m kx) (units of N*s/m).

Refer to Advanced_bushing_stiffness_and_damping “Advanced bushing stiffness and damping” for more details.

**** Advanced: Relationship of 𝐭 to τ. To understand how “gimbal torques” τ relate to 𝐭, it helps to remember that the RollPitchYaw class documentation states that a Space-fixed (extrinsic) X-Y-Z rotation with roll-pitch-yaw angles [q₀ q₁ q₂] is equivalent to a Body-fixed (intrinsic) Z-Y-X rotation by yaw-pitch-roll angles [q₂ q₁ q₀]. In the context of “gimbal torques”, the Body-fixed Z-Y-X rotation sequence with angles [q₂ q₁ q₀] is physical meaningful as it produces torques associated with successive frames in a gimbal as τ₂ 𝐀𝐳, τ₁ 𝐏𝐲, τ₀ 𝐂𝐱, where each of 𝐀𝐳, 𝐏𝐲, 𝐂𝐱 are unit vectors associated with a frame in the yaw-pitch-roll rotation sequence and 𝐏𝐲 is a unit vector of the “pitch” intermediate frame. As described earlier, torque 𝐭 is the moment of the bushing forces on frame C about Cp. Scalars tx, ty, tz are defined so 𝐭 can be expressed 𝐭 = [tx ty tz]ᴀ = tx 𝐀𝐱 + ty 𝐀𝐲 + tz 𝐀𝐳. As shown in code documentation, the relationship of [tx ty tz] to [τ₀ τ₁ τ₂] was found by equating 𝐭’s power to τ’s power as 𝐭 ⋅ w_AC = τ ⋅ q̇.

Click to expand C++ code...

⌈ tx ⌉      ⌈ τ₀ ⌉            ⌈ cos(q₂)/cos(q₁)  sin(q₂)/cos(q₁)   0 ⌉
| ty | = Nᵀ | τ₁ |  where N = |   −sin(q2)            cos(q2)      0 |
⌊ tz ⌋      ⌊ τ₂ ⌋            ⌊ cos(q₂)*tan(q₁)   sin(q₂)*tan(q₁)  1 ⌋

**** Advanced: More on how to choose bushing stiffness and damping constants. The basics on how to choose bushing stiffness and damping constants are at: - Basic_bushing_torque_stiffness_and_damping “How to choose torque stiffness and damping constants” - Basic_bushing_force_stiffness_and_damping “How to choose force stiffness and damping constants”

The list below provides more detail on: The performance tradeoff between high stiffness and long simulation time; loads that affect estimates of Mxₘₐₓ or Fxₘₐₓ; and how a linear 2ⁿᵈ-order ODE provides insight on how to experimentally determine stiffness and damping constants. - Stiffness [k₀ k₁ k₂] and [kx ky kz] affect simulation time and accuracy. Generally, a stiffer bushing better resembles an ideal joint (e.g., a revolute joint or fixed/weld joint). However (depending on integrator), a stiffer bushing usually increases numerical integration time. - An estimate for a maximum load Mxₘₐₓ or Fxₘₐₓ accounts for gravity forces, applied forces, inertia forces (centripetal, Coriolis, gyroscopic), etc. - One way to determine physical stiffness and damping constants is through the mathematical intermediaries ωₙ (units of rad/s) and ζ (no units). The constant ωₙ (called “undamped natural frequency” or “angular frequency”) and constant ζ (called “damping ratio”) relate to the physical constants mass m, damping constant dx, and stiffness constant kx via the following prototypical linear constant-coefficient 2ⁿᵈ-order ODEs.

Click to expand C++ code...

m ẍ +     dx ẋ +  kx x = 0   or alternatively as
   ẍ + 2 ζ ωₙ ẋ + ωₙ² x = 0   where ωₙ² = kx/m,  ζ = dx / (2 √(m kx))

ωₙ and ζ also appear in the related ODEs for rotational systems, namely

Click to expand C++ code...

I₀ q̈ +     d₀ q̇ +  k₀ q = 0   or alternatively as
    q̈ + 2 ζ ωₙ q̇ + ωₙ² q = 0   where ωₙ² = k₀/I₀,  ζ = d₀ / (2 √(I₀ k₀))

One way to determine ωₙ is from settling time tₛ which approximates the time for a system to settle to within a specified settling ratio of an equilibrium solutions. Typical values for settling ratio are 1% (0.01), 2% (0.02), 5% (0.05), and 10% (0.10). - When ζ < 0.7 (underdamped), a commonly used approximation is ωₙ ≈ -ln(settling_ratio) / (ζ tₛ) which for settling ratios 0.01 and 0.05 give ωₙ ≈ 4.6 / (ζ tₛ) and ωₙ ≈ 3 / (ζ tₛ). Another commonly used approximation is ωₙ ≈ -ln(settling_ratio √(1- ζ²)) / (ζ tₛ). See https://en.wikipedia.org/wiki/Settling_time or the book Modern Control Engineering by Katsuhiko Ogata. Although these approximate formulas for ωₙ are common, they are somewhat inaccurate. Settling time for underdamped systems is discontinuous and requires solving a nonlinear algebraic equation (an iterative process). For more information, see http://www.scielo.org.co/pdf/rfiua/n66/n66a09.pdf [Ramos-Paja, et. al 2012], “Accurate calculation of settling time in second order systems: a photovoltaic application”. Another reference is https://courses.grainger.illinois.edu/ece486/sp2020/laboratory/docs/lab2/estimates.html - When ζ ≈ 1 (critically damped), ωₙ is determined by choosing a settling ratio and then solving for (ωₙ tₛ) via the nonlinear algebraic equation (1 + ωₙ tₛ)*exp(-ωₙ tₛ) = settling_ratio. Settling ratio | ωₙ ————– | ————- 0.01 | 6.64 / tₛ 0.02 | 5.83 / tₛ 0.05 | 4.74 / tₛ 0.10 | 3.89 / tₛ See https://electronics.stackexchange.com/questions/296567/over-and-critically-damped-systems-settling-time - When ζ ≥ 1.01 (overdamped), ωₙ ≈ -ln(2 settling_ratio sz/s₂) / (s₁ tₛ) where sz = √(ζ² - 1), s₁ = ζ - sz, s₂ = ζ + sz. The derivation and approximation error estimates for this overdamped settling time formula is ApproximateOverdampedSettlingTime “below”.

For a real physical bushing, an experiment is one way to estimate damping

constants. For example, to estimate a torque damping constant d₀ associated with underdamped vibrations (damping ratio 0 < ζ < 1), attach the bushing to a massive rod, initially displace the rod by angle Δq, release the rod and measure q(t). From the q(t) measurement, estimate decay ratio (the ratio of successive peak heights above the final steady-state value) calculate logarithmic decrement δ = -ln(decay_ratio), calculate damping ratio ζ = √(δ² / (4π² + δ²)), then calculate d₀ using d₀ = 2 ζ √(I₀ k₀) or d₀ = 2 ζ k₀ / ωₙ. For more information, see https://en.wikipedia.org/wiki/Damping_ratio#Logarithmic_decrement

**** Derivation: Approximate formula for overdamped settling time. Since a literature reference for this formula was not found, the derivation below was done at TRI (it has not been peer reviewed). This formula results from the “dominant pole” solution in the prototypical constant-coefficient linear 2ⁿᵈ-order ODE. For ẋ(0) = 0, mathematics shows poles p₁ = -ωₙ s₁, p₂ = -ωₙ s₂, where sz = √(ζ² - 1), s₁ = ζ - sz, s₂ = ζ + sz. and

Click to expand C++ code...

x(t) / x(0) = p₂/(p₂-p₁) exp(p₁ t) - p₁/(p₂-p₁) exp(p₂ t)
             = s₂/(s₂-s₁) exp(p₁ t) - s₁/(s₂-s₁) exp(p₂ t)
             =  k/( k-1 ) exp(p₁ t) -  1/( k-1 ) exp(p₂ t) where k = s₂ / s₁
             ≈  k/( k-1 ) exp(p₁ t)                        since p₁ > p₂

Note: k = s₂ / s₁ is real, k > 0, s₂ = k s₁, and p₁ > p₂ (p₁ is less negative then p₂), so exp(p₁ t) decays to zero slower than exp(p₂ t) and exp(p₁ t) ≫ exp(p₂ t) for sufficiently large t. Hence we assume exp(p₂ t) ≈ 0 (which is why p₁ is called the “dominant pole”). Next,

Click to expand C++ code...

k/(k - 1) = s₂ / s₁ / (s₂/s₁ -1) = s₂ / (s₂ - s₁) = s₂ / (2 sz),  so
  x(t) / x(0)  ≈  s₂ / (2 sz) exp(-s₁ ωₙ t),                        hence
  settling_ratio ≈ s₂ / (2 sz) exp(-s₁ ωₙ tₛ),                      finally
  ωₙ ≈ -ln(settling_ratio 2 sz / s₂) / (s₁ tₛ)

The table below shows that there is little error in this approximate formula for various settling ratios and ζ, particularly for ζ ≥ 1.1. For 1.0 ≤ ζ < 1.1, the critical damping estimates of ωₙ work well. Settling ratio | ζ = 1.01 | ζ = 1.1 | ζ = 1.2 | ζ = 1.3 | ζ = 1.5 ————– | ——– | ——- | ——- | ——- | ——– 0.01 | 1.98% | 0.005% | 2.9E-5% | 1.6E-7% | 2.4E-12% 0.02 | 2.91% | 0.016% | 1.8E-4% | 2.1E-6% | 1.6E-10% 0.05 | 5.10% | 0.076% | 2.3E-3% | 7.0E-5% | 4.4E-8% 0.10 | 8.28% | 0.258% | 1.6E-2% | 1.0E-3% | 3.3E-6% Note: There is a related derivation in the reference below, however, it needlessly makes the oversimplified approximation k/(k - 1) ≈ 1. https://electronics.stackexchange.com/questions/296567/over-and-critically-damped-systems-settling-time

Note

The complete theory for this bushing is documented in the source code. Please look there if you want more information.

Template parameter T:: The underlying scalar type. Must be a valid Eigen scalar.

See also

math::RollPitchYaw for definitions of roll, pitch, yaw [q₀ q₁ q₂].

Note

Per issue #12982, do not directly or indirectly call the following methods as they have not yet been implemented and throw an exception: CalcPotentialEnergy(), CalcConservativePower(), CalcNonConservativePower().

Note

This class is templated; see LinearBushingRollPitchYaw_ for the list of instantiations.

__init__(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, frameA: pydrake.multibody.tree.Frame, frameC: pydrake.multibody.tree.Frame, torque_stiffness_constants: numpy.ndarray[numpy.float64[3, 1]], torque_damping_constants: numpy.ndarray[numpy.float64[3, 1]], force_stiffness_constants: numpy.ndarray[numpy.float64[3, 1]], force_damping_constants: numpy.ndarray[numpy.float64[3, 1]]) → None

Construct a LinearBushingRollPitchYaw B that connects frames A and C, where frame A is welded to a link L0 and frame C is welded to a link L1.

Parameter frameA:: frame A of link (body) L0 that connects to bushing B.
Parameter frameC:: frame C of link (body) L1 that connects to bushing B.
Parameter torque_stiffness_constants:: [k₀ k₁ k₂] multiply the roll-pitch-yaw angles [q₀ q₁ q₂] to produce the spring portion of the “gimbal” torques τ₀, τ₁, τ₂. The SI units of k₀, k₁, k₂ are N*m/rad.
Parameter torque_damping_constants:: [d₀ d₁ d₂] multiply the roll-pitch-yaw rates [q̇₀ q̇₁ q̇₂] to produce the damper portion of the “gimbal” torques τ₀, τ₁, τ₂. The SI units of d₀, d₁, d₂ are N*m*s/rad.
Parameter force_stiffness_constants:: [kx ky kz] multiply the bushing displacements [x y z] to form 𝐟ᴋ, the spring portion of the force 𝐟 = [fx fy fz]ʙ. The SI units of kx, ky, kz are N/m.
Parameter force_damping_constants:: [dx dy dz] multiply the bushing displacement rates [ẋ ẏ ż] to form 𝐟ᴅ, the damper portion of the force 𝐟 = [fx fy fz]ʙ. The SI units of dx, dy, dz are N*s/m.

Note

The LinearBushingRollPitchYaw class documentation describes the stiffness and damping constants.

Note

The net moment on C about Co is affected by both the gimbal torque and the moment of 𝐟 about Co. Similarly, for the net moment on A about Ao.

Note

math::RollPitchYaw describes the roll pitch yaw angles q₀, q₁, q₂. The position from Ao to Co is p_AoCo_B = x 𝐁𝐱 + y 𝐁𝐲 + z 𝐁𝐳 = [x y z]ʙ.

Note

The ModelInstanceIndex assigned to this by the constructor is the one assigned to frame C, i.e., frameC.model_instance().

Precondition:: All the stiffness and damping constants must be non-negative.

CalcBushingSpatialForceOnFrameA(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → pydrake.multibody.math.SpatialForce

Calculate F_A_A, the bushing’s spatial force on frame A expressed in A. F_A_A contains two vectors: the moment of all bushing forces on A about Ao (−𝐭 + p_AoAp × −𝐟) and the net bushing force on A (−𝐟 expressed in A).

Parameter context:: The state of the multibody system.

See also

CalcBushingSpatialForceOnFrameC().

Raises: RuntimeError if pitch angle is near gimbal-lock. For more info, –

See also

RollPitchYaw::DoesCosPitchAngleViolateGimbalLockTolerance().

CalcBushingSpatialForceOnFrameC(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → pydrake.multibody.math.SpatialForce

Calculate F_C_C, the bushing’s spatial force on frame C expressed in C. F_C_C contains two vectors: the moment of all bushing forces on C about Co (𝐭 + p_CoCp × 𝐟) and the resultant bushing force on C (𝐟 expressed in C).

Parameter context:: The state of the multibody system.

See also

CalcBushingSpatialForceOnFrameA().

Raises: RuntimeError if pitch angle is near gimbal-lock. For more info, –

See also

RollPitchYaw::DoesCosPitchAngleViolateGimbalLockTolerance().

force_damping_constants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → numpy.ndarray[numpy.float64[3, 1]]: Returns the default force damping constants [dx dy dz] (units of N*s/m). Refer to Basic_bushing_force_stiffness_and_damping “How to choose force stiffness and damping constants” for more details.

force_stiffness_constants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → numpy.ndarray[numpy.float64[3, 1]]: Returns the default force stiffness constants [kx ky kz] (units of N/m). Refer to Basic_bushing_force_stiffness_and_damping “How to choose force stiffness and damping constants” for more details.

frameA(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → pydrake.multibody.tree.Frame: Returns frame A, which is the frame that is welded to link (body) L0 and attached to the bushing.

frameC(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → pydrake.multibody.tree.Frame: Returns frame C, which is the frame that is welded to link (body) L1 and attached to the bushing.

GetForceDampingConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]: Returns the force damping constants [dx dy dz] (units of N*s/m) stored in context.

GetForceStiffnessConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]: Returns the force stiffness constants [kx ky kz] (units of N/m) stored in context.

GetTorqueDampingConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]: Returns the torque damping constants [d₀ d₁ d₂] (units of N*m*s/rad) stored in context.

GetTorqueStiffnessConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context) → numpy.ndarray[numpy.float64[3, 1]]: Returns the torque stiffness constants [k₀ k₁ k₂] (units of N*m/rad) stored in context.

link0(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → pydrake.multibody.tree.RigidBody: Returns link (body) L0 (frame A is welded to link L0).

link1(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → pydrake.multibody.tree.RigidBody: Returns link (body) L1 (frame C is welded to link L1).

SetForceDampingConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context, force_damping: numpy.ndarray[numpy.float64[3, 1]]) → None: Sets the force damping constants [dx dy dz] (units of N*s/m) in context.

SetForceStiffnessConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context, force_stiffness: numpy.ndarray[numpy.float64[3, 1]]) → None: Sets the force stiffness constants [kx ky kz] (units of N/m) in context.

SetTorqueDampingConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context, torque_damping: numpy.ndarray[numpy.float64[3, 1]]) → None: Sets the torque damping constants [d₀ d₁ d₂] (units of N*m*s/rad) in context.

SetTorqueStiffnessConstants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw, context: pydrake.systems.framework.Context, torque_stiffness: numpy.ndarray[numpy.float64[3, 1]]) → None: Sets the torque stiffness constants [k₀ k₁ k₂] (units of N*m/rad) in context.

torque_damping_constants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → numpy.ndarray[numpy.float64[3, 1]]: Returns the default torque damping constants [d₀ d₁ d₂] (units of N*m*s/rad). Refer to Basic_bushing_torque_stiffness_and_damping “How to choose torque stiffness and damping constants” for more details.

torque_stiffness_constants(self: pydrake.multibody.tree.LinearBushingRollPitchYaw) → numpy.ndarray[numpy.float64[3, 1]]: Returns the default torque stiffness constants [k₀ k₁ k₂] (units of N*m/rad). Refer to Basic_bushing_torque_stiffness_and_damping “How to choose torque stiffness and damping constants” for more details.

template pydrake.multibody.tree.LinearBushingRollPitchYaw_: Instantiations: LinearBushingRollPitchYaw_[float], LinearBushingRollPitchYaw_[AutoDiffXd], LinearBushingRollPitchYaw_[Expression]

class pydrake.multibody.tree.LinearBushingRollPitchYaw_[AutoDiffXd]

Bases: pydrake.multibody.tree.ForceElement_[AutoDiffXd]

This ForceElement models a massless flexible bushing that connects a frame A of a link (body) L0 to a frame C of a link (body) L1. The bushing can apply a torque and force due to stiffness (spring) and dissipation (damper) properties. Frame B is the bushing frame whose origin Bo is halfway between Ao (A’s origin) and Co (C’s origin) and whose unit vectors 𝐁𝐱, 𝐁𝐲, 𝐁𝐳 are “halfway” (in an angle-axis sense) between the unit vectors of frame A and frame C. Frame B is a “floating” frame in the sense that it is calculated from the position and orientation of frames A and C (B is not welded to the bushing).

@image html drake/multibody/tree/images/LinearBushingRollPitchYaw.png width=80%

The set of forces on frame C from the bushing is equivalent to a torque 𝐭 on frame C and a force 𝐟 applied to a point Cp of C. The set of forces on frame A from the bushing is equivalent to a torque −𝐭 on frame A and a force −𝐟 applied to a point Ap of A. Points Ap and Cp are coincident with Bo (frame B’s origin).

This “quasi-symmetric” bushing force/torque model was developed at Toyota Research Institute and has advantages compared to traditional bushing models because it employs a bushing-centered “symmetric” frame B and it ensures the moment of −𝐟 on A about Ao is equal to the moment of 𝐟 on C about Co. Traditional models differ as they lack a “symmetric” frame B and apply −𝐟 at Ao, which means the moment of −𝐟 on A about Ao is always zero. Note: This bushing model is not fully symmetric since the orientation between frames A and C is parameterized with roll-pitch-yaw angles [q₀ q₁ q₂]. Since these angles have an inherent sequence, they are not mathematically symmetric.

The torque model depends on spring-damper “gimbal” torques τ ≜ [τ₀ τ₁ τ₂] which themselves depend on roll-pitch-yaw angles q ≜ [q₀ q₁ q₂] and rates q̇ = [q̇₀ q̇₁ q̇₂] via a diagonal torque-stiffness matrix K₀₁₂ and a diagonal torque-damping matrix D₀₁₂ as

Click to expand C++ code...

⌈ τ₀ ⌉     ⌈k₀    0    0⌉ ⌈ q₀ ⌉     ⌈d₀    0    0⌉ ⌈ q̇₀ ⌉
τ ≜ | τ₁ | = − | 0   k₁    0| | q₁ |  −  | 0   d₁    0| | q̇₁ |
    ⌊ τ₂ ⌋     ⌊ 0    0   k₂⌋ ⌊ q₂ ⌋     ⌊ 0    0   d₂⌋ ⌊ q̇₂ ⌋

where k₀, k₁, k₂ and d₀, d₁, d₂ are torque stiffness and damping constants and must have non-negative values.

Note

τ does not represent a vector expressed in one frame. Instead it is regarded as a 3x1 array of torque scalars associated with roll-pitch yaw.

Note

As discussed in the Advanced section below, τ is not 𝐭 (τ ≠ 𝐭).

Note

This is a “linear” bushing model as gimbal torque τ varies linearly with q and q̇ as τ = τᴋ + τᴅ where τᴋ = −K₀₁₂ ⋅ q and τᴅ = −D₀₁₂ ⋅ q̇.

The bushing model for the net force 𝐟 on frame C from the bushing depends on scalars x, y, z which are defined so 𝐫 (the position vector from Ao to Co) can be expressed in frame B as 𝐫 ≜ p_AoCo = [x y z]ʙ = x 𝐁𝐱 + y 𝐁𝐲 + z 𝐁𝐳. The model for 𝐟 uses a diagonal force-stiffness matrix Kxyᴢ, a diagonal force-damping matrix Dxyᴢ, and defines fx, fy, fz so 𝐟 = [fx fy fz]ʙ.

Click to expand C++ code...

⌈ fx ⌉      ⌈kx    0    0⌉ ⌈ x ⌉     ⌈dx    0    0⌉ ⌈ ẋ ⌉
| fy | =  − | 0   ky    0| | y |  −  | 0   dy    0| | ẏ |
⌊ fz ⌋      ⌊ 0    0   kz⌋ ⌊ z ⌋     ⌊ 0    0   dz⌋ ⌊ ż ⌋