Add log to quaternion

Author: markuswntr

Sources/QuaternionModule/ElementaryFunctions.swift

@@ -164,6 +164,23 @@ extension Quaternion/*: ElementaryFunctions */ {
     return sin(q) / cos(q)
   }
 
+  // MARK: - log-like functions
+  @inlinable
+  public static func log(_ q: Quaternion) -> Quaternion {
+    // If q is zero or infinite, the phase is undefined, so the result is
+    // the single exceptional value.
+    guard q.isFinite && !q.isZero else { return .infinity }
+
+    let vectorLength = q.imaginary.length
+    let scale = q.halfAngle / vectorLength
+
+    // We deliberatly choose log(length) over the (faster)
+    // log(lengthSquared) / 2 which is used for complex numbers; as
+    // the squared length of quaternions is more prone to overflows than the
+    // squared length of complex numbers.
+    return Quaternion(real: .log(q.length), imaginary: q.imaginary * scale)
+  }
+
   // MARK: - pow-like functions
   @inlinable
   public static func pow(_ q: Quaternion, _ p: Quaternion) -> Quaternion {

Tests/QuaternionTests/ElementaryFunctionTests.swift

@@ -209,6 +209,23 @@ final class ElementaryFunctionTests: XCTestCase {
     }
   }
 
+  func testLog<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
+    // log(0) = undefined/infinity
+    XCTAssertFalse(Quaternion<T>.log(Quaternion(real: 0, imaginary: 0, 0, 0)).isFinite)
+    XCTAssertFalse(Quaternion<T>.log(Quaternion(real:-0, imaginary: 0, 0, 0)).isFinite)
+    XCTAssertFalse(Quaternion<T>.log(Quaternion(real:-0, imaginary:-0,-0,-0)).isFinite)
+    XCTAssertFalse(Quaternion<T>.log(Quaternion(real: 0, imaginary:-0,-0,-0)).isFinite)
+
+    var g = SystemRandomNumberGenerator()
+    let values: [Quaternion<T>] = (0..<100).map { _ in
+      Quaternion(
+        real: T.random(in: -1 ... 1, using: &g),
+        imaginary: SIMD3(repeating: T.random(in: -.pi ... .pi, using: &g) / 3))
+    }
+    for q in values {
+      XCTAssertTrue(q.isApproximatelyEqual(to: .log(.exp(q))))
+    }
+  }
 
   func testCos<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
     var g = SystemRandomNumberGenerator()
@@ -266,6 +283,8 @@ final class ElementaryFunctionTests: XCTestCase {
     testSinh(Float32.self)
     testCos(Float32.self)
     testSin(Float32.self)
+
+    testLog(Float32.self)
   }
 
   func testDouble() {
@@ -275,5 +294,7 @@ final class ElementaryFunctionTests: XCTestCase {
     testSinh(Float64.self)
     testCos(Float64.self)
     testSin(Float64.self)
+
+    testLog(Float64.self)
   }
 }