Detailed Description

template<typename T>
class drake::multibody::RotationalInertia< T >

This class describes the mass distribution (inertia properties) of a body or composite body about a particular point.

Herein, "composite body" means one body or a collection of bodies that are welded together. In this documentation, "body" and "composite body" are used interchangeably.

A rigid body's mass distribution is described by three quantities: the body's mass; the body's center of mass; and the body's rotational inertia about a particular point. The term rotational inertia is used here and by [Jain 2010] to distinguish from a body's spatial inertia. In this class, a 3x3 inertia matrix I represents a body's rotational inertia about a point and expressed in a frame. More specifically, I_BP_E is the inertia matrix of a body B about-point P and expressed-in frame E (herein frame E's orthogonal unit vectors Ex, Ey, Ez are denoted 𝐱̂, 𝐲̂, 𝐳̂).

    | Ixx Ixy Ixz |
I = | Ixy Iyy Iyz |
    | Ixz Iyz Izz |

The moments of inertia Ixx, Iyy, Izz and products of inertia Ixy, Ixz, Iyz are defined in terms of the mass dm of a differential volume of the body. The position of dm from about-point P is xx̂ + yŷ + zẑ = [x, y, z]_E.

Ixx = ∫ (y² + z²) dm
Iyy = ∫ (x² + z²) dm
Izz = ∫ (x² + y²) dm
Ixy = - ∫ x y dm
Ixz = - ∫ x z dm
Iyz = - ∫ y z dm

We use the negated convention for products of inertia, so that I serves to relate angular velocity ω and angular momentum h via h = I ⋅ ω. Ensure your products of inertia follow this negative sign convention.

The 3x3 inertia matrix is symmetric and its diagonal elements (moments of inertia) and off-diagonal elements (products of inertia) are associated with a body (or composite body) S, an about-point P, and an expressed-in frame E (𝐱̂, 𝐲̂, 𝐳̂̂). A rotational inertia is ill-defined unless there is a body S, about-point P, and expressed-in frame E. The user of this class is responsible for tracking the body S, about-point P and expressed-in frame E (none of these are stored in this class).

Note

This class does not store the about-point nor the expressed-in frame, nor does this class help enforce consistency of the about-point or expressed-in frame. To help users of this class track the about-point and expressed-in frame, we strongly recommend the following notation.

In typeset material, use the symbol \( [I^{S/P}]_E \) to represent the rotational inertia (inertia matrix) of a body (or composite body) S about-point P, expressed in frame E. In code and comments, use the monogram notation I_SP_E (e.g., as described in Spatial Mass Matrix (Spatial Inertia)). If the about-point P is fixed to a body B, the point is named \( B_P \) and this appears in code/comments as Bp. Examples: I_BBp_E is rigid body B's rotational inertia about-point Bp expressed-in frame E; I_BBo_E is B's rotational inertia about-point Bo (body B's origin) expressed-in frame E; and I_BBcm_E is B's inertia matrix about-point Bcm (B's center of mass) expressed-in frame E.

The rotational inertia (inertia matrix) can be re-expressed in terms of a special frame whose orthogonal unit vectors are parallel to principal axes of inertia so that the inertia matrix is diagonalized with elements called principal moments of inertia.

The formal definition of the inertia matrix \( I^{S/P} \) of a system S about a point P follows the definition of the inertia dyadic 𝐈 of S about P, which begins by modeling S with n particles S₁ ... Sₙ (e.g., 12 grams of carbon can be modeled with n = 6.02 * 10²³ molecules/particles). The inertia dyadic 𝐈₁ of one particle S₁ about point P is defined [Kane, 1985] in terms of m₁ (mass of S₁), ᴾ𝐩ˢ¹ (position vector from P to S₁), and the unit dyadic 𝐔 which is defined by the property 𝐔 ⋅ 𝐯 = 𝐯 where 𝐯 is is any vector (this definition of 𝐔 is analogous to defining the identity matrix by the property 𝑰𝒅𝒆𝒏𝒕𝒊𝒕𝒚𝑴𝒂𝒕𝒓𝒊𝒙 * 𝒂𝒏𝒚𝑴𝒂𝒕𝒓𝒊𝒙 = 𝒂𝒏𝒚𝑴𝒂𝒕𝒓𝒊𝒙).

    𝐈₁ = m₁ * [𝐔 * (ᴾ𝐩ˢ¹ ⋅ ᴾ𝐩ˢ¹)  -  ᴾ𝐩ˢ¹ * ᴾ𝐩ˢ¹]

Note: The vector dot-product (⋅) above produces a scalar whereas the vector multiply (*) produces a dyadic which is a 2nd-order tensor (ᴾ𝐩ˢ¹ * ᴾ𝐩ˢ¹ is similar to the matrix outer-product of a 3x1 matrix multiplied by a 1x3 matrix). An example inertia dyadic for a single particle is shown further below. The inertia dyadic 𝐈 of the entire system S is defined by summing the inertia dyadic of each particle Sᵢ about P (i = 1, ... n), i.e.,

    𝐈 = 𝐈₁ + 𝐈₂ + ... 𝐈ₙ

The elements of the inertia matrix \( [I^{S/P}]_E \) expressed in frame E (in terms of orthogonal unit vectors 𝐱̂, 𝐲̂, 𝐳̂̂) are found by pre-dot multiplying and post-dot multiplying 𝐈 with appropriate unit vectors.

   Ixx = 𝐱̂ ⋅ 𝐈 ⋅ 𝐱̂     Ixy = 𝐱̂ ⋅ 𝐈 ⋅ 𝐲̂      Ixz = 𝐱̂ ⋅ 𝐈 ⋅ 𝐳̂̂
   Iyx = 𝐲̂ ⋅ 𝐈 ⋅ 𝐱̂     Iyy = 𝐲̂ ⋅ 𝐈 ⋅ 𝐲̂      Iyz = 𝐲̂ ⋅ 𝐈 ⋅ 𝐳̂̂
   Izx = 𝐳̂̂ ⋅ 𝐈 ⋅ 𝐱̂     Izy = 𝐳̂̂ ⋅ 𝐈 ⋅ 𝐲̂      Izz = 𝐳̂̂ ⋅ 𝐈 ⋅ 𝐳̂̂

The inertia dyadic 𝐈ᴮ of a rigid body B about Bcm (B's center of mass) is related to various dynamic quantities. For example, B's angular momentum 𝐇 about Bcm in a frame N and B's kinetic energy KE in N relate to 𝐈ᴮ by

   𝐇 = 𝐈ᴮ ⋅ 𝛚
   KE = 1/2 𝛚 ⋅ 𝐈ᴮ ⋅ 𝛚  +  1/2 mᴮ 𝐯 ⋅ 𝐯

where 𝛚 is B's angular velocity in N, 𝐯 is Bcm's translational velocity in N, and mᴮ is B's mass. When frame N happens to be a Newtonian frame (also called an inertial frame or non-rotating/non-accelerating frame), the moment 𝐓 of all forces on B about Bcm relates to 𝐈ᴮ and 𝛂 (B's angular acceleration in N) by Euler's rigid body equation as

   𝐓 = 𝐈ᴮ ⋅ 𝛂  +  𝛚 × 𝐈ᴮ ⋅ 𝛚

Example: For a particle Q of mass m whose position vector from a point O is written in terms of right-handed orthogonal unit vectors 𝐱̂, 𝐲̂, 𝐳̂ (below), the inertia dyadic 𝐈 of particle Q about point O is defined and calculated

    𝐩 = x 𝐱̂  +  y 𝐲̂                               (given)
    𝐈 = m * [𝐔 * (𝐩 ⋅ 𝐩)  -  𝐩 * 𝐩]              (definition)
      = m * [𝐔 * (x² + y²)  -  (x𝐱̂ + y𝐲̂̂) * (x𝐱̂ + y𝐲̂)
      = m * [(𝐱̂𝐱̂ + 𝐲̂𝐲̂ + 𝐳̂𝐳̂) * (x² + y²) - (x²𝐱̂𝐱̂ + xy𝐱̂𝐲̂̂ + xy𝐲̂̂𝐱̂ + y²𝐲̂̂𝐲̂̂)]
      = m * [y²𝐱̂𝐱̂ + x²𝐲̂𝐲̂ + (x² + y²)𝐳̂𝐳̂ - xy𝐱̂𝐲̂̂ - xy𝐲̂̂𝐱̂]

which means the inertia matrix for particle Q about point O for 𝐱̂, 𝐲̂, 𝐳̂ is

    |  m y²     -m x y         0     |
I = | -m x y     m x²          0     |
    |    0         0     m (x² + y²) |

[Kane, 1985] pg. 68. "Dynamics: Theory and Applications," McGraw-Hill Co., New York, 1985 (with D. A. Levinson). Available for free .pdf download: https://ecommons.cornell.edu/handle/1813/637

Several methods in this class throw a std::exception for invalid rotational inertia operations in debug releases only. This provides speed in a release build while facilitating debugging in debug builds. In addition, these validity tests are only performed for scalar types for which drake::scalar_predicate<T>::is_bool is true. For instance, validity checks are not performed when T is symbolic::Expression.

The methods of this class satisfy the "basic exception guarantee": if an exception is thrown, the program will still be in a valid state. Specifically, no resources are leaked, and all objects' invariants are intact. Be aware that RotationalInertia objects may contain invalid inertia data in cases where input checking is skipped.

See also: https://en.cppreference.com/w/cpp/language/exceptions

Various methods in this class require numerical (not symbolic) data types.

Template Parameters

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

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

Public Member Functions

RotationalInertia ()

Constructs a rotational inertia that has all its moments/products of inertia equal to NaN (helps quickly detect uninitialized values). More...

RotationalInertia (const T &Ixx, const T &Iyy, const T &Izz)

Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with each product of inertia set to zero. More...

RotationalInertia (const T &Ixx, const T &Iyy, const T &Izz, const T &Ixy, const T &Ixz, const T &Iyz)

Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with products of inertia Ixy, Ixz, Iyz. More...

RotationalInertia (const T &mass, const Vector3< T > &p_PQ_E)

Constructs a rotational inertia for a particle Q of mass mass, whose position vector from about-point P is p_PQ_E (E is expressed-in frame). More...

int rows () const

For consistency with Eigen's API, the rows() method returns 3. More...

int cols () const

For consistency with Eigen's API, the cols() method returns 3. More...

Vector3< T > get_moments () const

Returns 3-element vector with moments of inertia [Ixx, Iyy, Izz]. More...

Vector3< T > get_products () const

Returns 3-element vector with products of inertia [Ixy, Ixz, Iyz]. More...

T Trace () const

Returns a rotational inertia's trace (i.e., Ixx + Iyy + Izz, the sum of the diagonal elements of the inertia matrix). More...

T CalcMaximumPossibleMomentOfInertia () const

Returns the maximum possible moment of inertia for this rotational inertia about-point P for any expressed-in frame E. More...

const T & operator() (int i, int j) const

Const access to the (i, j) element of this rotational inertia. More...

Matrix3< T > CopyToFullMatrix3 () const

Gets a full 3x3 matrix copy of this rotational inertia. More...

boolean< T > IsNearlyEqualTo (const RotationalInertia &other, double precision) const

Compares this rotational inertia to other rotational inertia within the specified precision (which is a dimensionless number specifying the relative precision to which the comparison is performed). More...

RotationalInertia< T > & operator+= (const RotationalInertia< T > &I_BP_E)

Adds a rotational inertia I_BP_E to this rotational inertia. More...

RotationalInertia< T > operator+ (const RotationalInertia< T > &I_BP_E) const

Adds a rotational inertia I_BP_E to this rotational inertia. More...

RotationalInertia< T > & operator-= (const RotationalInertia< T > &I_BP_E)

Subtracts a rotational inertia I_BP_E from this rotational inertia. More...

RotationalInertia< T > operator- (const RotationalInertia< T > &I_BP_E) const

Subtracts a rotational inertia I_BP_E from this rotational inertia. More...

RotationalInertia< T > & operator *= (const T &nonnegative_scalar)

Multiplies this rotational inertia by a nonnegative scalar (>= 0). More...

RotationalInertia< T > operator * (const T &nonnegative_scalar) const

Multiplies this rotational inertia by a nonnegative scalar (>= 0). More...

Vector3< T > operator * (const Vector3< T > &w_E) const

Multiplies this rotational inertia about-point P, expressed-in frame E by the vector w_E (which must also have the same expressed-in frame E). More...

RotationalInertia< T > & operator/= (const T &positive_scalar)

Divides this rotational inertia by a positive scalar (> 0). More...

RotationalInertia< T > operator/ (const T &positive_scalar) const

Divides this rotational inertia by a positive scalar(> 0). More...

RotationalInertia< T > MultiplyByScalarSkipValidityCheck (const T &s) const

(Internal use only) Multiplies a rotational inertia by a scalar. More...

void SetToNaN ()

Sets this rotational inertia so all its elements are equal to NaN. More...

void SetZero ()

Sets this rotational inertia so all its moments/products of inertia are zero, e.g., for convenient initialization before a computation or for inertia calculations involving a particle (point-mass). More...

boolean< T > IsNaN () const

Returns true if any moment/product in this rotational inertia is NaN. More...

boolean< T > IsZero () const

Returns true if all moments and products of inertia are exactly zero. More...

template<typename Scalar >

RotationalInertia< Scalar > cast () const

Returns a new RotationalInertia object templated on Scalar initialized from the values of this rotational inertia's entries. More...

Vector3< double > CalcPrincipalMomentsOfInertia () const

Forms the 3 principal moments of inertia for this rotational inertia. More...

std::pair< Vector3< double >, math::RotationMatrix< double > > CalcPrincipalMomentsAndAxesOfInertia () const

Forms the 3 principal moments of inertia and their 3 associated principal directions for this rotational inertia. More...

boolean< T > CouldBePhysicallyValid () const

Performs several necessary checks to verify whether this rotational inertia could be physically valid, including: More...

void ReExpressInPlace (const math::RotationMatrix< T > &R_AE)

Re-expresses this rotational inertia I_BP_E in place to I_BP_A. More...

RotationalInertia< T > ReExpress (const math::RotationMatrix< T > &R_AE) const

Re-expresses this rotational inertia I_BP_E to I_BP_A i.e., re-expresses body B's rotational inertia from frame E to frame A. More...

Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable

RotationalInertia (const RotationalInertia &)=default

RotationalInertia & operator= (const RotationalInertia &)=default

RotationalInertia (RotationalInertia &&)=default

RotationalInertia & operator= (RotationalInertia &&)=default

Shift methods

Each shift method shifts a body's rotational inertia from one about-point to another about-point.

The expressed-in frame is unchanged.

In-place methods (`this` changes)	Const methods
ShiftFromCenterOfMassInPlace	ShiftFromCenterOfMass
ShiftToCenterOfMassInPlace	ShiftToCenterOfMass
ShiftToThenAwayFromCenterOfMassInPlace	ShiftToThenAwayFromCenterOfMass

void ShiftFromCenterOfMassInPlace (const T &mass, const Vector3< T > &p_BcmQ_E)

Shifts this rotational inertia for a body (or composite body) B from about-point Bcm (B's center of mass) to about-point Q. More...

RotationalInertia< T > ShiftFromCenterOfMass (const T &mass, const Vector3< T > &p_BcmQ_E) const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point Bcm (B's center of mass) to about-point Q. More...

void ShiftToCenterOfMassInPlace (const T &mass, const Vector3< T > &p_QBcm_E)

Shifts this rotational inertia for a body (or composite body) B from about-point Q to about-point Bcm (B's center of mass). More...

RotationalInertia< T > ShiftToCenterOfMass (const T &mass, const Vector3< T > &p_QBcm_E) const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point Q to about-point Bcm (B's center of mass). More...

void ShiftToThenAwayFromCenterOfMassInPlace (const T &mass, const Vector3< T > &p_PBcm_E, const Vector3< T > &p_QBcm_E)

Shifts this rotational inertia for a body (or composite body) B from about-point P to about-point Q via Bcm (B's center of mass). More...

RotationalInertia< T > ShiftToThenAwayFromCenterOfMass (const T &mass, const Vector3< T > &p_PBcm_E, const Vector3< T > &p_QBcm_E) const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point P to about-point Q via Bcm (B's center of mass). More...

Static Public Member Functions
static RotationalInertia< T >	TriaxiallySymmetric (const T &I_triaxial)
	Constructs a rotational inertia with equal moments of inertia along its diagonal and with each product of inertia set to zero. More...

static RotationalInertia< T >	MakeFromMomentsAndProductsOfInertia (const T &Ixx, const T &Iyy, const T &Izz, const T &Ixy, const T &Ixz, const T &Iyz, bool skip_validity_check=false)
	(Internal use only) Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with products of inertia Ixy, Ixz, Iyz. More...

Protected Member Functions
RotationalInertia< T > &	MinusEqualsUnchecked (const RotationalInertia< T > &I_BP_E)
	Subtracts a rotational inertia `I_BP_E` from `this` rotational inertia. More...

Friends
template<typename >
class	RotationalInertia

RotationalInertia< T >	operator * (const T &nonnegative_scalar, const RotationalInertia< T > &I_BP_E)
	Multiplies a nonnegative scalar (>= 0) by the rotational inertia `I_BP_E`. More...

Related Functions
(Note that these are not member functions.)
template<typename T >
std::ostream &	operator<< (std::ostream &out, const RotationalInertia< T > &I)
	Writes an instance of RotationalInertia into a std::ostream. More...

Constructor & Destructor Documentation

◆ RotationalInertia() [1/6]

RotationalInertia ( const RotationalInertia< T > & )

default

◆ RotationalInertia() [2/6]

RotationalInertia ( RotationalInertia< T > && )

default

◆ RotationalInertia() [3/6]

RotationalInertia ( )

Constructs a rotational inertia that has all its moments/products of inertia equal to NaN (helps quickly detect uninitialized values).

◆ RotationalInertia() [4/6]

RotationalInertia	(	const T &	Ixx,
		const T &	Iyy,
		const T &	Izz
	)

Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with each product of inertia set to zero.

Exceptions

std::exception for Debug builds if not CouldBePhysicallyValid().

◆ RotationalInertia() [5/6]

RotationalInertia	(	const T &	Ixx,
		const T &	Iyy,
		const T &	Izz,
		const T &	Ixy,
		const T &	Ixz,
		const T &	Iyz
	)

Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with products of inertia Ixy, Ixz, Iyz.

Exceptions

std::exception for Debug builds if not CouldBePhysicallyValid().

◆ RotationalInertia() [6/6]

RotationalInertia	(	const T &	mass,
		const Vector3< T > &	p_PQ_E
	)

Constructs a rotational inertia for a particle Q of mass mass, whose position vector from about-point P is p_PQ_E (E is expressed-in frame).

This std::logic_error exception only occurs if mass < 0.

Parameters

mass	The mass of particle Q.
p_PQ_E	Position from about-point P to Q, expressed-in frame E.

Return values

I_QP_E,Q's rotational inertia about-point P expressed-in frame E.

Remarks: Negating the position vector p_PQ_E has no affect on the result.

Exceptions

std::exception for Debug builds if not CouldBePhysicallyValid().

Member Function Documentation

◆ CalcMaximumPossibleMomentOfInertia()

T CalcMaximumPossibleMomentOfInertia ( ) const

Returns the maximum possible moment of inertia for this rotational inertia about-point P for any expressed-in frame E.

Remarks: The maximum moment Imax has range: trace / 3 <= Imax <= trace / 2.

See also: Trace()

◆ CalcPrincipalMomentsAndAxesOfInertia()

std::pair<Vector3<double>, math::RotationMatrix<double> > CalcPrincipalMomentsAndAxesOfInertia ( ) const

Forms the 3 principal moments of inertia and their 3 associated principal directions for this rotational inertia.

Returns: 3 principal moments of inertia [Ixx Iyy Izz], sorted in ascending order (Ixx ≤ Iyy ≤ Izz) and a rotation matrix R_EA whose columns are the 3 associated principal directions that relate the expressed-in frame E to a frame A, where frame E is the expressed-in frame for this rotational inertia I_BP_E (body B's rotational inertia about-point P) and frame A contains right-handed orthonormal vectors Ax, Ay, Az. The 1ˢᵗ column of R_EA is Ax_E (Ax expressed in frame E) which is parallel to the principal axis associated with Ixx (the smallest principal moment of inertia). Similarly, the 2ⁿᵈ and 3ʳᵈ columns of R_EA are Ay_E and Az_E, which are parallel to principal axes associated with Iyy and Izz (the intermediate and largest principal moments of inertia). If all principal moments of inertia are equal (i.e., Ixx = Iyy = Izz), R_EA is the identity matrix.

Exceptions

std::exception if the elements of this rotational inertia cannot be converted to a real finite double. For example, an exception is thrown if this contains an erroneous NaN or if scalar type T is symbolic.

See also: CalcPrincipalMomentsOfInertia() to calculate the principal moments of inertia [Ixx Iyy Izz], without calculating the principal directions.

◆ CalcPrincipalMomentsOfInertia()

Vector3<double> CalcPrincipalMomentsOfInertia ( ) const

Forms the 3 principal moments of inertia for this rotational inertia.

Return values

The	3 principal moments of inertia [Imin Imed Imax], sorted in ascending order (Imin ≤ Imed ≤ Imax).

Exceptions

std::exception if the elements of this rotational inertia cannot be converted to a real finite double. For example, an exception is thrown if this contains an erroneous NaN or if scalar type T is symbolic.

See also: CalcPrincipalMomentsAndAxesOfInertia() to also calculate principal moment of inertia directions associated with this rotational inertia.

◆ cast()

RotationalInertia<Scalar> cast ( ) const

Returns a new RotationalInertia object templated on Scalar initialized from the values of this rotational inertia's entries.

Template Parameters

Scalar The scalar type on which the new rotational inertia will be templated.

Note: RotationalInertia<From>::cast<To>() creates a new RotationalInertia<To> from a RotationalInertia<From> but only if type To is constructible from type From. This cast method works in accordance with Eigen's cast method for Eigen's Matrix3 that underlies this RotationalInertia. For example, Eigen currently allows cast from type double to AutoDiffXd, but not vice-versa.

◆ cols()

int cols ( ) const

For consistency with Eigen's API, the cols() method returns 3.

◆ CopyToFullMatrix3()

Matrix3<T> CopyToFullMatrix3 ( ) const

Gets a full 3x3 matrix copy of this rotational inertia.

The returned copy is symmetric and includes both lower and upper parts of the matrix.

◆ CouldBePhysicallyValid()

boolean<T> CouldBePhysicallyValid ( ) const

Performs several necessary checks to verify whether this rotational inertia could be physically valid, including:

No NaN moments or products of inertia.
Ixx, Iyy, Izz and principal moments are all non-negative.
Ixx, Iyy Izz and principal moments satisfy the triangle inequality:
- Ixx + Iyy >= Izz
- Ixx + Izz >= Iyy
- Iyy + Izz >= Ixx

Warning: These checks are necessary (but NOT sufficient) conditions for a rotational inertia to be physically valid. The sufficient condition requires a rotational inertia to satisfy the above checks after this is shifted to the center of mass, i.e., the sufficient condition requires calling CouldBePhysicallyValid() when the about-point is Bcm (the body's center of mass). Note: this class does not know its about-point or its center of mass location.

Returns: true for a plausible rotational inertia passing the above necessary but insufficient checks and false otherwise.

Exceptions

std::exception if principal moments of inertia cannot be calculated (eigenvalue solver) or if scalar type T cannot be converted to a double.

◆ get_moments()

Vector3<T> get_moments ( ) const

Returns 3-element vector with moments of inertia [Ixx, Iyy, Izz].

◆ get_products()

Vector3<T> get_products ( ) const

Returns 3-element vector with products of inertia [Ixy, Ixz, Iyz].

◆ IsNaN()

boolean<T> IsNaN ( ) const

Returns true if any moment/product in this rotational inertia is NaN.

Otherwise returns false.

◆ IsNearlyEqualTo()

boolean<T> IsNearlyEqualTo	(	const RotationalInertia< T > &	other,
		double	precision
	)		const

Compares this rotational inertia to other rotational inertia within the specified precision (which is a dimensionless number specifying the relative precision to which the comparison is performed).

Denoting I_maxA as the largest element value that can appear in a valid this rotational inertia (independent of the expressed-in frame E) and denoting I_maxB as the largest element value that can appear in a valid other rotational inertia (independent of the expressed-in frame E), this and other are considered nearly equal to each other, if: ‖this - other‖∞ < precision * min(I_maxA, I_maxB)

Parameters

other	Rotational inertia to compare with `this` rotational inertia.
precision	is a dimensionless real positive number that is usually based on two factors, namely expected accuracy of moments/products of inertia (e.g., from end-user or CAD) and/or machine-precision.

Returns: true if the absolute value of each moment/product of inertia in this is within epsilon of the corresponding moment/ product absolute value in other. Otherwise returns false.

Note: : This method only works if all moments of inertia with scalar type T in this and other can be converted to a double (discarding supplemental scalar data such as derivatives of an AutoDiffXd). It fails at runtime if type T cannot be converted to double.

◆ IsZero()

boolean<T> IsZero ( ) const

Returns true if all moments and products of inertia are exactly zero.

◆ MakeFromMomentsAndProductsOfInertia()

static RotationalInertia<T> MakeFromMomentsAndProductsOfInertia	(	const T &	Ixx,
		const T &	Iyy,
		const T &	Izz,
		const T &	Ixy,
		const T &	Ixz,
		const T &	Iyz,
		bool	skip_validity_check = `false`
	)

static

(Internal use only) Creates a rotational inertia with moments of inertia Ixx, Iyy, Izz, and with products of inertia Ixy, Ixz, Iyz.

Parameters

[in]	Ixx,Iyy,Izz	Moments of inertia.
[in]	Ixy,Ixz,Iyz	Products of inertia.
[in]	skip_validity_check	If set to false, the rotational inertia is checked via CouldBePhysicallyValid() to ensure it is physically valid. If set to true (not generally recommended), the check is skipped (which reduces some computational cost). The default value is false.

Exceptions

std::exception if skip_validity_check is false and CouldBePhysicallyValid() fails.

◆ MinusEqualsUnchecked()

RotationalInertia<T>& MinusEqualsUnchecked ( const RotationalInertia< T > & I_BP_E )

protected

Subtracts a rotational inertia I_BP_E from this rotational inertia.

No check is done to determine if the result is physically valid.

Parameters

I_BP_E Rotational inertia of a body (or composite body) B to be subtracted from this rotational inertia.

Returns: A reference to this rotational inertia. this changes since rotational inertia I_BP_E has been subtracted from it.

See also: operator-().

Warning: This operator may produce an invalid rotational inertia. Use operator-=() to perform necessary (but insufficient) checks on the physical validity of the resulting rotational inertia.

Note: : Although this method is mathematically useful, it may result in a rotational inertia that is physically invalid. This method helps perform intermediate calculations which do not necessarily represent a real rotational inertia. For example, an efficient way to shift a rotational inertia from an arbitrary point P to an arbitrary point Q is mathematical equivalent to a + (b - c). Although a must be physically valid and the result a + (b - c) must be physically valid, the intermediate quantity (b - c) is not necessarily physically valid. This method allows (b - c) to be calculated without requiring (b - c) to be physically valid.

See also: operator-=().

◆ MultiplyByScalarSkipValidityCheck()

RotationalInertia<T> MultiplyByScalarSkipValidityCheck ( const T & s ) const

(Internal use only) Multiplies a rotational inertia by a scalar.

Parameters

[in] s Scalar which multiplies this.

Returns: this rotational inertia multiplied by s.

See also: operator*(const T&, const RotationalInertia<T>&).

Note: This method works even if s is negative or this is invalid. This method is useful for error messages associated with an invalid inertia.

◆ operator *() [1/2]

RotationalInertia<T> operator * ( const T & nonnegative_scalar ) const

Multiplies this rotational inertia by a nonnegative scalar (>= 0).

In debug builds, throws std::exception if nonnegative_scalar < 0.

Parameters

nonnegative_scalar Nonnegative scalar which multiplies this.

Returns: this rotational inertia multiplied by nonnegative_scalar.

See also: operator*=(), operator*(const T&, const RotationalInertia<T>&)

◆ operator *() [2/2]

Vector3<T> operator * ( const Vector3< T > & w_E ) const

Multiplies this rotational inertia about-point P, expressed-in frame E by the vector w_E (which must also have the same expressed-in frame E).

Note: This calculation is equivalent to regarding this rotational inertia as an inertia dyadic and dot-multiplying it by w_E.

Parameters

w_E	Vector to post-multiply with `this` rotational inertia.

Returns: The Vector that results from multiplying this by w_E.

◆ operator *=()

RotationalInertia<T>& operator *= ( const T & nonnegative_scalar )

Multiplies this rotational inertia by a nonnegative scalar (>= 0).

In debug builds, throws std::exception if nonnegative_scalar < 0.

Parameters

nonnegative_scalar Nonnegative scalar which multiplies this.

Returns: A reference to this rotational inertia. this changes since this has been multiplied by nonnegative_scalar.

See also: operator*(), operator*(const T&, const RotationalInertia<T>&).

◆ operator()()

const T& operator()	(	int	i,
		int	j
	)		const

Const access to the (i, j) element of this rotational inertia.

Remarks: A mutable version of operator() is intentionally absent so as to prevent an end-user from directly setting elements. This prevents the creation of a non-physical (or non-symmetric) rotational inertia.

◆ operator+()

RotationalInertia<T> operator+ ( const RotationalInertia< T > & I_BP_E ) const

Adds a rotational inertia I_BP_E to this rotational inertia.

This method requires both rotational inertias (I_BP_E and this) to have the same about-point P and the same expressed-in frame E.

Parameters

I_BP_E Rotational inertia of a body (or composite body) B to be added to this rotational inertia. I_BP_E and this must have the same about-point P and expressed-in frame E.

Returns: The sum of this rotational inertia and I_BP_E.

See also: operator+=().

◆ operator+=()

RotationalInertia<T>& operator+= ( const RotationalInertia< T > & I_BP_E )

Adds a rotational inertia I_BP_E to this rotational inertia.

This method requires both rotational inertias (I_BP_E and this) to have the same about-point P and the same expressed-in frame E. The += operator updates this so I_BP_E is added to this.

Parameters

I_BP_E Rotational inertia of a body (or composite body) B to be added to this rotational inertia. I_BP_E and this must have the same about-point P and expressed-in frame E.

Returns: A reference to this rotational inertia. this changes since rotational inertia I_BP_E has been added to it.

See also: operator+().

◆ operator-()

RotationalInertia<T> operator- ( const RotationalInertia< T > & I_BP_E ) const

Subtracts a rotational inertia I_BP_E from this rotational inertia.

This method requires both rotational inertias (I_BP_E and this) to have the same about-point P and the same expressed-in frame E.

Parameters

I_BP_E Rotational inertia of a body (or composite body) B to be subtracted from this rotational inertia. I_BP_E and this must have the same about-point P and expressed-in frame E.

Returns: The subtraction of I_BP_E from this rotational inertia.

Exceptions

std::exception for Debug builds if not CouldBePhysicallyValid().

See also: operator-=().

Warning: See warning and documentation for operator-=().

◆ operator-=()

RotationalInertia<T>& operator-= ( const RotationalInertia< T > & I_BP_E )

Subtracts a rotational inertia I_BP_E from this rotational inertia.

This method requires both rotational inertias (I_BP_E and this) to have the same about-point P and the same expressed-in frame E. The -= operator updates this so I_BP_E is subtracted from this.

Parameters

I_BP_E Rotational inertia of a body (or composite body) B to be subtracted from this rotational inertia. I_BP_E and this must have the same about-point P and expressed-in frame E.

Returns: A reference to this rotational inertia. this changes since rotational inertia I_BP_E has been subtracted from it.

Exceptions

std::exception for Debug builds if not CouldBePhysicallyValid().

See also: operator-().

Note: This subtract operator is useful for computing rotational inertia of a body with a hole. First the rotational inertia of a fully solid body S (without the hole) is calculated, then the rotational inertia of the hole (treated as a massive solid body B) is calculated. The rotational inertia of a composite body C (comprised of S and -B) is computed by subtracting B's rotational inertia from S's rotational inertia.

◆ operator/()

RotationalInertia<T> operator/ ( const T & positive_scalar ) const

Divides this rotational inertia by a positive scalar(> 0).

In debug builds, throws std::exception if positive_scalar <= 0.

Parameters

positive_scalar Positive scalar (> 0) which divides this.

Returns: this rotational inertia divided by positive_scalar.

See also: operator/=().

◆ operator/=()

RotationalInertia<T>& operator/= ( const T & positive_scalar )

Divides this rotational inertia by a positive scalar (> 0).

In debug builds, throws std::exception if positive_scalar <= 0.

Parameters

positive_scalar Positive scalar (> 0) which divides this.

Returns: A reference to this rotational inertia. this changes since this has been divided by positive_scalar.

See also: operator/().

◆ operator=() [1/2]

RotationalInertia& operator= ( RotationalInertia< T > && )

default

◆ operator=() [2/2]

RotationalInertia& operator= ( const RotationalInertia< T > & )

default

◆ ReExpress()

RotationalInertia<T> ReExpress ( const math::RotationMatrix< T > & R_AE ) const

Re-expresses this rotational inertia I_BP_E to I_BP_A i.e., re-expresses body B's rotational inertia from frame E to frame A.

Parameters

[in] R_AE RotationMatrix relating frames A and E.

Return values

I_BP_A Rotational inertia of B about-point P expressed-in frame A.

Exceptions

std::exception for Debug builds if the rotational inertia that is re-expressed-in frame A violates CouldBePhysicallyValid().

See also: ReExpressInPlace()

◆ ReExpressInPlace()

void ReExpressInPlace ( const math::RotationMatrix< T > & R_AE )

Re-expresses this rotational inertia I_BP_E in place to I_BP_A.

In other words, starts with this rotational inertia of a body (or composite body) B about-point P expressed-in frame E and re-expresses to B's rotational inertia about-point P expressed-in frame A. More concisely, we compute I_BP_A = R_AE * I_BP_E * (R_AE)ᵀ.

Parameters

[in] R_AE RotationMatrix relating frames A and E.

Exceptions

std::exception for Debug builds if the rotational inertia that is re-expressed-in frame A violates CouldBePhysicallyValid().

See also: ReExpress().

◆ rows()

int rows ( ) const

For consistency with Eigen's API, the rows() method returns 3.

◆ SetToNaN()

void SetToNaN ( )

Sets this rotational inertia so all its elements are equal to NaN.

This helps quickly detect uninitialized moments/products of inertia.

◆ SetZero()

void SetZero ( )

Sets this rotational inertia so all its moments/products of inertia are zero, e.g., for convenient initialization before a computation or for inertia calculations involving a particle (point-mass).

Note: Real 3D massive physical objects have non-zero moments of inertia.

◆ ShiftFromCenterOfMass()

RotationalInertia<T> ShiftFromCenterOfMass	(	const T &	mass,
		const Vector3< T > &	p_BcmQ_E
	)		const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point Bcm (B's center of mass) to about-point Q.

I.e., shifts I_BBcm_E to I_BQ_E (both are expressed-in frame E).

Parameters

mass	The mass of body (or composite body) B.
p_BcmQ_E	Position vector from Bcm to Q, expressed-in frame E.

Return values

I_BQ_E B's rotational inertia about-point Q expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Q violates CouldBePhysicallyValid().

Remarks: Negating the position vector p_BcmQ_E has no affect on the result.

◆ ShiftFromCenterOfMassInPlace()

void ShiftFromCenterOfMassInPlace	(	const T &	mass,
		const Vector3< T > &	p_BcmQ_E
	)

Shifts this rotational inertia for a body (or composite body) B from about-point Bcm (B's center of mass) to about-point Q.

I.e., shifts I_BBcm_E to I_BQ_E (both are expressed-in frame E). On return, this is modified to be shifted from about-point Bcm to about-point Q.

Parameters

mass	The mass of body (or composite body) B.
p_BcmQ_E	Position vector from Bcm to Q, expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Q violates CouldBePhysicallyValid().

Remarks: Negating the position vector p_BcmQ_E has no affect on the result.

◆ ShiftToCenterOfMass()

RotationalInertia<T> ShiftToCenterOfMass	(	const T &	mass,
		const Vector3< T > &	p_QBcm_E
	)		const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point Q to about-point Bcm (B's center of mass).

I.e., shifts I_BQ_E to I_BBcm_E (both are expressed-in frame E).

Parameters

mass	The mass of body (or composite body) B.
p_QBcm_E	Position vector from Q to `Bcm`, expressed-in frame E.

Return values

I_BBcm_E B's rotational inertia about-point Bcm expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Bcm violates CouldBePhysicallyValid().

Remarks: Negating the position vector p_QBcm_E has no affect on the result.

◆ ShiftToCenterOfMassInPlace()

void ShiftToCenterOfMassInPlace	(	const T &	mass,
		const Vector3< T > &	p_QBcm_E
	)

Shifts this rotational inertia for a body (or composite body) B from about-point Q to about-point Bcm (B's center of mass).

I.e., shifts I_BQ_E to I_BBcm_E (both are expressed-in frame E). On return, this is shifted from about-point Q to about-point Bcm.

Parameters

mass	The mass of body (or composite body) B.
p_QBcm_E	Position vector from Q to `Bcm`, expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Bcm violates CouldBePhysicallyValid().

Remarks: Negating the position vector p_QBcm_E has no affect on the result.

◆ ShiftToThenAwayFromCenterOfMass()

RotationalInertia<T> ShiftToThenAwayFromCenterOfMass	(	const T &	mass,
		const Vector3< T > &	p_PBcm_E,
		const Vector3< T > &	p_QBcm_E
	)		const

Calculates the rotational inertia that results from shifting this rotational inertia for a body (or composite body) B from about-point P to about-point Q via Bcm (B's center of mass).

I.e., shifts I_BP_E to I_BQ_E (both are expressed-in frame E).

Parameters

mass	The mass of body (or composite body) B.
p_PBcm_E	Position vector from P to Bcm, expressed-in frame E.
p_QBcm_E	Position vector from Q to Bcm, expressed-in frame E.

Return values

I_BQ_E,B's rotational inertia about-point Q expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Q violates CouldBePhysicallyValid().

Remarks: Negating either (or both) position vectors p_PBcm_E and p_QBcm_E has no affect on the result.

◆ ShiftToThenAwayFromCenterOfMassInPlace()

void ShiftToThenAwayFromCenterOfMassInPlace	(	const T &	mass,
		const Vector3< T > &	p_PBcm_E,
		const Vector3< T > &	p_QBcm_E
	)

Shifts this rotational inertia for a body (or composite body) B from about-point P to about-point Q via Bcm (B's center of mass).

I.e., shifts I_BP_E to I_BQ_E (both are expressed-in frame E). On return, this is modified to be shifted from about-point P to about-point Q.

Parameters

mass	The mass of body (or composite body) B.
p_PBcm_E	Position vector from P to Bcm, expressed-in frame E.
p_QBcm_E	Position vector from Q to Bcm, expressed-in frame E.

Exceptions

std::exception for Debug builds if the rotational inertia that is shifted to about-point Q violates CouldBePhysicallyValid().

Remarks: Negating either (or both) position vectors p_PBcm_E and p_QBcm_E has no affect on the result.; This method is more efficient (by 6 multiplications) than first shifting to the center of mass, then shifting away, e.g., as (ShiftToCenterOfMassInPlace()).ShiftFromCenterOfMassInPlace();

◆ Trace()

T Trace ( ) const

Returns a rotational inertia's trace (i.e., Ixx + Iyy + Izz, the sum of the diagonal elements of the inertia matrix).

The trace happens to be invariant to its expressed-in frame (i.e., the trace does not depend on the frame in which it is expressed). The trace is useful because the largest moment of inertia Imax has range: trace / 3 <= Imax <= trace / 2, and the largest possible product of inertia must be <= Imax / 2. Hence, trace / 3 and trace / 2 give a lower and upper bound on the largest possible element that can be in a valid rotational inertia.

◆ TriaxiallySymmetric()

static RotationalInertia<T> TriaxiallySymmetric ( const T & I_triaxial )

static

Constructs a rotational inertia with equal moments of inertia along its diagonal and with each product of inertia set to zero.

This factory is useful for the rotational inertia of a uniform-density sphere or cube. In debug builds, throws std::exception if I_triaxial is negative/NaN.

Friends And Related Function Documentation

◆ operator *

RotationalInertia<T> operator *	(	const T &	nonnegative_scalar,
		const RotationalInertia< T > &	I_BP_E
	)

friend

Multiplies a nonnegative scalar (>= 0) by the rotational inertia I_BP_E.

In debug builds, throws std::exception if nonnegative_scalar < 0.

Parameters

nonnegative_scalar Nonnegative scalar which multiplies I_BP_E.

Returns: nonnegative_scalar multiplied by rotational inertia I_BP_E.

See also: operator*=(), operator*()

Multiplication of a scalar with a rotational matrix is commutative.

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	out,
		const RotationalInertia< T > &	I
	)

◆ RotationalInertia

friend class RotationalInertia

friend

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

drake/multibody/tree/rotational_inertia.h

Detailed Description

template<typename T> class drake::multibody::RotationalInertia< T >

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Related Functions

Constructor & Destructor Documentation

◆ RotationalInertia() [1/6]

◆ RotationalInertia() [2/6]

◆ RotationalInertia() [3/6]

◆ RotationalInertia() [4/6]

◆ RotationalInertia() [5/6]

◆ RotationalInertia() [6/6]

Member Function Documentation

◆ CalcMaximumPossibleMomentOfInertia()

◆ CalcPrincipalMomentsAndAxesOfInertia()

◆ CalcPrincipalMomentsOfInertia()

◆ cast()

◆ cols()

◆ CopyToFullMatrix3()

◆ CouldBePhysicallyValid()

◆ get_moments()

◆ get_products()

◆ IsNaN()

◆ IsNearlyEqualTo()

◆ IsZero()

◆ MakeFromMomentsAndProductsOfInertia()

◆ MinusEqualsUnchecked()

◆ MultiplyByScalarSkipValidityCheck()

◆ operator *() [1/2]

◆ operator *() [2/2]

◆ operator *=()

◆ operator()()

◆ operator+()

◆ operator+=()

◆ operator-()

◆ operator-=()

◆ operator/()

◆ operator/=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReExpress()

◆ ReExpressInPlace()

◆ rows()

◆ SetToNaN()

◆ SetZero()

◆ ShiftFromCenterOfMass()

◆ ShiftFromCenterOfMassInPlace()

◆ ShiftToCenterOfMass()

◆ ShiftToCenterOfMassInPlace()

◆ ShiftToThenAwayFromCenterOfMass()

◆ ShiftToThenAwayFromCenterOfMassInPlace()

◆ Trace()

◆ TriaxiallySymmetric()

Friends And Related Function Documentation

◆ operator *

◆ operator<<()

◆ RotationalInertia

template<typename T>
class drake::multibody::RotationalInertia< T >