Improve comments.

Author: Paul Mitiguy

multibody/tree/quaternion_floating_mobilizer.cc

@@ -292,7 +292,7 @@ Eigen::Matrix<T, 4, 3> QuaternionFloatingMobilizer<T>::CalcLMatrix(
   // component of the quaternion (Euler parameters). Notice however here we use
   // qs and qv for the "scalar" and "vector" components of the quaternion q_FM,
   // respectively, while Mitiguy uses ε₀ and ε (in bold), respectively.
-  // This mobilizer is parameterized by the angular velocity w_FM-F, i.e. time
+  // This mobilizer is parameterized by the angular velocity w_FM_F, i.e. time
   // derivatives of the vector component of the quaternion are taken in the F
   // frame. If you are confused by this, notice that the vector component of a
   // quaternion IS a vector, and therefore you must specify in what frame time
@@ -301,11 +301,12 @@ Eigen::Matrix<T, 4, 3> QuaternionFloatingMobilizer<T>::CalcLMatrix(
   // Notice this is equivalent to:
   // Dt_F(q_FM) = 1/2 * w_FM⋅q_FM, where ⋅ denotes the "quaternion product" and
   // both the vector component qv_FM of q_FM and w_FM are expressed in frame F.
-  // Dt_F(q) is short for [Dt_F(q)]_F.
+  // Using Dt_F(q) as an abbreviation of [Dt_F(q_FM)]_F.
   // The expression above can be written as:
   // Dt_F(q) = 1/2 * (-w_FM.dot(qv_F); qs * w_FM + w_FM.cross(qv_F))
   //         = 1/2 * (-w_FM.dot(qv_F); qs * w_FM - qv_F.cross(w_FM))
   //         = 1/2 * (-w_FM.dot(qv_F); (qs * Id - [qv_F]x) * w_FM)
+  //         = 1/2 * L(q_FM) * w_FM
   //         = L(q_FM/2) * w_FM
   // That is:
   //           |         -qv_Fᵀ    |   ⌈ -qx   -qy   -qz ⌉
@@ -401,8 +402,7 @@ void QuaternionFloatingMobilizer<T>::DoCalcNDotMatrix(
   const Vector4<T> qdot = CalcLMatrixOverTwo(q_FM) * w_FM_F;
   const Quaternion<T> qdot_FM(qdot[0], qdot[1], qdot[2], qdot[3]);
 
-  // Leveraging comments and code in CalcLMatrixOverTwo() and noting that
-  // Nᵣ(qᵣ) = 0.5 * L(q_FM), where the elements of the matrix L are linear in
+  // Since Nᵣ(qᵣ) = 0.5 * L(q_FM), where L(q_FM) is linear in the elements of
   // q_FM = [qw, qx, qy, qz]ᵀ, so Ṅᵣ(qᵣ,q̇ᵣ) = 0.5 * L(q̇_FM).
   const Eigen::Matrix<T, 4, 3> NrDotMatrix = CalcLMatrixOverTwo(qdot_FM);
 
@@ -438,8 +438,8 @@ void QuaternionFloatingMobilizer<T>::DoCalcNplusDotMatrix(
   const Vector4<T> qdot = CalcLMatrixOverTwo(q_FM) * w_FM_F;
   const Quaternion<T> qdot_FM(qdot[0], qdot[1], qdot[2], qdot[3]);
 
-  // Since N⁺ᵣ(qᵣ) = 2 * L(q_FM)ᵀ, where L(q_FM) is linear in q_FM, hence
-  // Ṅ⁺ᵣ(qᵣ,q̇ᵣ) = 2 * L(q̇_FM)ᵀ.
+  // Since N⁺ᵣ(qᵣ) = 2 * L(q_FM)ᵀ, where L(q_FM) is linear in the elements of
+  // q_FM = [qw, qx, qy, qz]ᵀq_FM, hence Ṅ⁺ᵣ(qᵣ,q̇ᵣ) = 2 * L(q̇_FM)ᵀ.
   const Eigen::Matrix<T, 3, 4> NrPlusDot =
       CalcTwoTimesLMatrixTranspose(qdot_FM);
 
@@ -482,15 +482,13 @@ void QuaternionFloatingMobilizer<T>::DoMapAccelerationToQDDot(
   // It first calculates the rotational part, then the translational part.
   //
   // For the rotational part of this mobilizer, the 2nd-derivatives of the
-  // generalized positions q̈_FM = q̈ᵣ = [q̈w, q̈x, q̈y, q̈z]ᵀ are related to the
-  // 1st-derivatives of the generalized velocities ẇ_FM_F = v̇ᵣ = [ẇx, ẇy, ẇz]ᵀ
-  // as q̈_FM = Ṅᵣ(q,q̇)⋅v + Nᵣ(q)⋅v̇, where Nᵣ(q) is the 3x4 matrix below and
-  // Ṅᵣ(q,q̇)⋅v = -0.25 ω² q_FM, where ω² = |w_FM_F|² and w_FM_F = [wx, wy, wz]ᵀ.
+  // generalized positions q̈_FM = [q̈w, q̈x, q̈y, q̈z]ᵀ are related to the
+  // 1st-derivatives of generalized velocities ω̇ = ẇ_FM_F = [ω̇x, ω̇y, ω̇z]ᵀ as
+  // shown below where L(q_FM) is the 4x3 matrix documented in CalcLMatrix(),
+  // ω = [ωx, ωy, ωz]ᵀ, ω² = |ω|², and 0.5 L̇(q̇_FM)⋅ω = -0.25 ω² q_FM.
   //
-  // ⌈ q̈w ⌉       ⌈ -qx   -qy   -qz ⌉ ⌈ ẇx ⌉           ⌈ qw ⌉
-  // | q̈x | = 0.5 |  qw    qz   -qy | | ẇy | - 0.25 ω² | qx |
-  // | q̈y |       |  qw   qw    qx  | ⌊ ẇz ⌋           | qy |
-  // ⌊ q̈z ⌋       ⌊  qy   -qx    qw ⌋                  ⌊ qz ⌋
+  // q̈_FM = 0.5 L(q_FM)⋅ω̇ + 0.5 L̇(q̇_FM)⋅ω
+  //      = 0.5 L(q_FM)⋅ω̇ - 0.25 ω² q_FM
   //
   // Formulas and proofs in Sections 9.3 and 9.6 of [Mitiguy, August 2025].
   // [Mitiguy, August 2025] Mitiguy, P. Advanced Dynamics & Motion Simulation.

multibody/tree/quaternion_floating_mobilizer.h

@@ -339,29 +339,29 @@ class QuaternionFloatingMobilizer final : public MobilizerImpl<T, 7, 6> {
   //           | -qz    qw    qx |
   //           ⌊  qy   -qx    qw ⌋
   //
-  // The matrix L(q_FM) is an intermediary for various quaternion-related
+  // Note: The matrix L(q_FM) is an intermediary for various quaternion-related
   // calculations. For example, denoting w_FM_F = [ωx, ωy, ωz]ᵀ as frame M's
-  // angular velocity in frame F, expressed in F, the following involve L(q_FM):
+  // angular velocity in frame F, expressed in F, the rotational part of the N
+  // and N⁺ matrices are 0.5 * L(q_FM) and 2 * L(q_FM)ᵀ, respectively. Others:
   //
   // q̇_FM = 0.5 * L(q_FM) * w_FM_F
   // q̈_FM = 0.5 * L(q_FM) * ẇ_FM_F - 0.25 ω² q_FM    Note: ω² = |w_FM_F|²
   // w_FM_F = 2 * L(q_FM)ᵀ * q̇_FM
   // ẇ_FM_F = 2 * L(q_FM)ᵀ * q̇_FM
-  // Nᵣ(q_FM) = 0.5 * L(q_FM)  Nᵣ is the rotational part of the N matrix.
-  // N⁺ᵣ(q_FM) = 2 * L(q_FM)ᵀ  N⁺ᵣ is the rotational part of the Nplus matrix.
+  //
+  // Note: Since L(q_FM) depends linearly on q_FM, s * L(q_FM) = L(s * q_FM),
+  // where s is a scalar (e.g., 0.5 or 2).
   static Eigen::Matrix<T, 4, 3> CalcLMatrix(const Quaternion<T>& q);
 
   // Returns the 4x3 matrix 0.5 * L(q_FM), where q_FM = [qw, qx, qy, qz] is the
-  // quaternion relating frames F and M. As documented in CalcLMatrix(),
-  // L(q_FM) depends linearly on q_FM, so 0.5 * L(q_FM) = L(0.5 * q_FM).
+  // quaternion relating frames F and M.  See documentation in CalcLMatrix(),
   static Eigen::Matrix<T, 4, 3> CalcLMatrixOverTwo(const Quaternion<T>& q_FM) {
     return CalcLMatrix(
         {0.5 * q_FM.w(), 0.5 * q_FM.x(), 0.5 * q_FM.y(), 0.5 * q_FM.z()});
   }
 
   // Returns the 3x4 matrix 2 * L(q_FM)ᵀ, where q_FM = [qw, qx, qy, qz] is the
-  // quaternion relating frames F and M. As documented in CalcLMatrix(),
-  // L(q_FM) depends linearly on q_FM, so 2 * L(q_FM)ᵀ = L(2 * q_FM)ᵀ.
+  // quaternion relating frames F and M. See documentation in CalcLMatrix().
   static Eigen::Matrix<T, 3, 4> CalcTwoTimesLMatrixTranspose(
       const Quaternion<T>& q_FM) {
     return CalcLMatrix({2 * q_FM.w(), 2 * q_FM.x(), 2 * q_FM.y(), 2 * q_FM.z()})