Add more comments and clean up comments and variable names

Author: markuswntr

Sources/ComplexModule/ElementaryFunctions.swift

@@ -32,6 +32,11 @@
 // Except where derivations are given, the expressions used here are all
 // adapted from Kahan's 1986 paper "Branch Cuts for Complex Elementary
 // Functions; or: Much Ado About Nothing's Sign Bit".
+//
+// As quaternions share the same goals and use adoptions of the elementary
+// functions: If you make a modification to either of the following functions,
+// you should almost surely make a parallel modification to the same elementary
+// function of quaternions (See ElementaryFunctions.swift in QuaternionModule).
 
 import RealModule
 

Sources/QuaternionModule/ElementaryFunctions.swift

@@ -12,39 +12,43 @@
 
 import RealModule
 
+// As the following elementary functions algorithms are adoptions of the
+// elementary functions of complex numbers: If you make a modification to either
+// of the following functions, you should almost surely make a parallel
+// modification to the same elementary function of complex numbers (See
+// ElementaryFunctions.swift in ComplexModule).
 extension Quaternion/*: ElementaryFunctions */ {
 
   // MARK: - exp-like functions
 
-  /// The quaternion exponential function e^q whose base `e` is the base of the
-  /// natural logarithm.
-  ///
-  /// Mathematically, this operation can be expanded in terms of the `Real`
-  /// operations `exp`, `cos` and `sin` as follows:
-  /// ```
-  /// exp(r + xi + yj + zk) = exp(r + v) = exp(r) exp(v)
-  ///                       = exp(r) (cos(θ) + (v/θ) sin(θ)) where θ = ||v||
-  /// ```
-  /// Note that naive evaluation of this expression in floating-point would be
-  /// prone to premature overflow, since `cos` and `sin` both have magnitude
-  /// less than 1 for most inputs (i.e. `exp(r)` may be infinity when
-  /// `exp(r) cos(θ)` would not be).
-  public static func exp(_ q: Quaternion<RealType>) -> Quaternion<RealType> {
+  // Mathematically, this operation can be expanded in terms of the `Real`
+  // operations `exp`, `cos` and `sin` as follows:
+  // ```
+  // exp(r + xi + yj + zk) = exp(r + v) = exp(r) exp(v)
+  //                       = exp(r) (cos(||v||) + (v/||v||) sin(||v||))
+  // ```
+  // Note that naive evaluation of this expression in floating-point would be
+  // prone to premature overflow, since `cos` and `sin` both have magnitude
+  // less than 1 for most inputs (i.e. `exp(r)` may be infinity when
+  // `exp(r) cos(θ)` would not be).
+  @inlinable
+  public static func exp(_ q: Quaternion) -> Quaternion {
     guard q.isFinite else { return q }
     // For real quaternions we can skip phase and axis calculations
     // TODO: Replace q.imaginary == .zero with `q.isReal`
-    let phase = q.imaginary == .zero ? .zero : q.imaginary.length
-    let unitAxis = q.imaginary == .zero ? .zero : (q.imaginary / phase)
+    let θ = q.imaginary == .zero ? .zero : q.imaginary.length // θ = ||v||
+    let n̂ = q.imaginary == .zero ? .zero : (q.imaginary / θ)  // n̂ = v / ||v||
     // If real < log(greatestFiniteMagnitude), then exp(q.real) does not overflow.
     // To protect ourselves against sketchy log or exp implementations in
     // an unknown host library, or slight rounding disagreements between
     // the two, subtract one from the bound for a little safety margin.
     guard q.real < RealType.log(.greatestFiniteMagnitude) - 1 else {
       let halfScale = RealType.exp(q.real/2)
-      let rotation = Quaternion(
-        halfAngle: phase,
-        unitAxis: unitAxis
-      )
+      let rotation = Quaternion(halfAngle: θ, unitAxis: n̂)
+      return rotation.multiplied(by: halfScale).multiplied(by: halfScale)
+    }
+    return Quaternion(halfAngle: θ, unitAxis: n̂).multiplied(by: .exp(q.real))
+  }
       return rotation.multiplied(by: halfScale).multiplied(by: halfScale)
     }
     return Quaternion(

Sources/QuaternionModule/Transformation.swift

@@ -407,13 +407,8 @@ extension Quaternion {
   }
 }
 
-// MARK: - Transformation Helper
-//
-// While Angle/Axis, Rotation Vector and Polar are different representations
-// of transformations, they have common properties such as being based on a
-// rotation *angle* about a rotation axis of unit length.
-//
-// The following extension provides these common operation internally.
+// MARK: - Operations for working with polar form
+
 extension Quaternion {
   /// The half rotation angle in radians within *[0, π]* range.
   ///

Tests/QuaternionTests/ElementaryFunctionTests.swift

@@ -23,7 +23,7 @@ final class ElementaryFunctionTests: XCTestCase {
     XCTAssertEqual(1, Quaternion<T>.exp(Quaternion(real:-0, imaginary: 0, 0, 0)))
     XCTAssertEqual(1, Quaternion<T>.exp(Quaternion(real:-0, imaginary:-0,-0,-0)))
     XCTAssertEqual(1, Quaternion<T>.exp(Quaternion(real: 0, imaginary:-0,-0,-0)))
-    // In general, exp(Quaternion(r, 0, 0, 0)) should be exp(r), but that breaks
+    // In general, exp(Quaternion(r,0,0,0)) should be exp(r), but that breaks
     // down when r is infinity or NaN, because we want all non-finite
     // quaternions to be semantically a single point at infinity. This is fine
     // for most inputs, but exp(Quaternion(-.infinity, 0, 0, 0)) would produce