Drake
RotationalInertia< T > Class Template Reference

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.
Template Parameters
 T The underlying scalar type. Must be a valid Eigen scalar. Various methods in this class require numerical (not symbolic) data types.

Instantiated templates for the following kinds of T's are provided:

They are already available to link against in the containing library.

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

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

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

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

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< doubleCalcPrincipalMomentsOfInertia () const
This method takes this rotational inertia about-point P, expressed-in frame E, and computes its principal moments of inertia about-point P, but expressed-in a frame aligned with the principal axes. More...

boolean< T > CouldBePhysicallyValid () const
Performs several necessary checks to verify whether this rotational inertia could be physically valid, including: More...

RotationalInertia< T > & ReExpressInPlace (const math::RotationMatrix< T > &R_AE)
Re-expresses this rotational inertia I_BP_E to I_BP_A. More...

RotationalInertia< T > ReExpress (const math::RotationMatrix< T > &R_AE) const __attribute__((warn_unused_result))
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

RotationalInertiaoperator= (const RotationalInertia &)=default

RotationalInertia (RotationalInertia &&)=default

RotationalInertiaoperator= (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
RotationalInertia< T > & 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 __attribute__((warn_unused_result))
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...

RotationalInertia< T > & 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 __attribute__((warn_unused_result))
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...

RotationalInertia< T > & 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 __attribute__((warn_unused_result))
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...

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 &o, const RotationalInertia< T > &I)
Insertion operator to write RotationalInertia's into a std::ostream. More...

◆ 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::logic_error 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::logic_error 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::logic_error for Debug builds if not CouldBePhysicallyValid().

◆ 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.
Trace()

◆ CalcPrincipalMomentsOfInertia()

 Vector3 CalcPrincipalMomentsOfInertia ( ) const

This method takes this rotational inertia about-point P, expressed-in frame E, and computes its principal moments of inertia about-point P, but expressed-in a frame aligned with the principal axes.

Note
: This method only works for a rotational inertia with scalar type T that can be converted to a double (discarding any supplemental scalar data such as derivatives of an AutoDiffScalar).
Return values
 principal_moments The vector of principal moments of inertia [Ixx Iyy Izz] sorted in ascending order.
Exceptions
 std::runtime_error if eigenvalue solver fails or if scalar type T cannot be converted to a double.

◆ cast()

 RotationalInertia 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 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 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::runtime_error if principal moments of inertia cannot be calculated (eigenvalue solver) or if scalar type T cannot be converted to a double.

◆ get_moments()

 Vector3 get_moments ( ) const

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

◆ get_products()

 Vector3 get_products ( ) const

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

◆ IsNaN()

 boolean IsNaN ( ) const

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

Otherwise returns false.

◆ IsNearlyEqualTo()

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

Compares this rotational inertia to other rotional 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 AutoDiffScalar). It fails at runtime if type T cannot be converted to double.

◆ MinusEqualsUnchecked()

 RotationalInertia& 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.
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.
operator-=().

◆ operator *() [1/2]

 RotationalInertia operator * ( const T & nonnegative_scalar ) const

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

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

Parameters
 nonnegative_scalar Nonnegative scalar which multiplies this.
Returns
this rotational inertia multiplied by nonnegative_scalar.
operator*=(), operator*(const T&, const RotationalInertia<T>&)

◆ operator *() [2/2]

 Vector3 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& 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.
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 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.
operator+=().

◆ operator+=()

 RotationalInertia& 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.
operator+().

◆ operator-()

 RotationalInertia 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::logic_error for Debug builds if not CouldBePhysicallyValid().
operator-=().
Warning
See warning and documentation for operator-=().

◆ operator-=()

 RotationalInertia& 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::logic_error for Debug builds if not CouldBePhysicallyValid().
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 operator/ ( const T & positive_scalar ) const

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

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

Parameters
 positive_scalar Positive scalar (> 0) which divides this.
Returns
this rotational inertia divided by positive_scalar.
operator/=().

◆ operator/=()

 RotationalInertia& 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.
operator/().

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ ReExpress()

 RotationalInertia 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::logic_error for Debug builds if the rotational inertia that is re-expressed-in frame A violates CouldBePhysicallyValid().
ReExpressInPlace()

◆ ReExpressInPlace()

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

Re-expresses this rotational inertia I_BP_E 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, i.e., I_BP_A = R_AE * I_BP_E * (R_AE)ᵀ.

Parameters
 [in] R_AE RotationMatrix relating frames A and E.
Returns
A reference to this rotational inertia about-point P, but with this expressed in frame A (instead of frame E).
Exceptions
 std::logic_error for Debug builds if the rotational inertia that is re-expressed-in frame A violates CouldBePhysicallyValid().
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 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::logic_error 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()

 RotationalInertia& 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).

Parameters
 mass The mass of body (or composite body) B. p_BcmQ_E Position vector from Bcm to Q, expressed-in frame E.
Returns
A reference to this rotational inertia expressed-in frame E, but with this shifted from about-point Bcm to about-point Q. i.e., returns I_BQ_E, B's rotational inertia about-point Bcm expressed-in frame E.
Exceptions
 std::logic_error 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 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::logic_error 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()

 RotationalInertia& 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).

Parameters
 mass The mass of body (or composite body) B. p_QBcm_E Position vector from Q to Bcm, expressed-in frame E.
Returns
A reference to this rotational inertia expressed-in frame E, but with this shifted from about-point Q to about-point Bcm, i.e., returns I_BBcm_E, B's rotational inertia about-point Bcm expressed-in frame E.
Exceptions
 std::logic_error 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 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::logic_error 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()

 RotationalInertia& 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).

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.
Returns
A reference to this rotational inertia expressed-in frame E, but with this shifted from about-point P to about-point Q, i.e., returns I_BQ_E, B's rotational inertia about-point Q expressed-in frame E.
Exceptions
 std::logic_error 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 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::logic_error if I_triaxial is negative/NaN.

◆ operator *

 RotationalInertia 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::logic_error if nonnegative_scalar < 0.

Parameters
 nonnegative_scalar Nonnegative scalar which multiplies I_BP_E.
Returns
nonnegative_scalar multiplied by rotational inertia I_BP_E.
operator*=(), operator*()

Multiplication of a scalar with a rotational matrix is commutative.

◆ operator<<()

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

Insertion operator to write RotationalInertia's into a std::ostream.

Especially useful for debugging.

◆ RotationalInertia

 friend class RotationalInertia
friend

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