119 Commits
Author SHA1 Message Date
Stephen Canon e4b6b631fb Cleanup some swift 6 warnings. 2025-08-15 16:13:56 -04:00
Markus Winter 9a726a793e Remove AlgebraicField conformance on quaternions
Replace the (incorrect) conformance on AlgebraicField with a conformance to SignedNumeric
2025-08-14 21:50:12 -04:00
Markus Winter 98b9088b4c Replace argument with halfAngle 2025-08-14 21:50:11 -04:00
Markus Winter bb31091fdc Simplify implementation of halfAngle 2025-08-14 21:50:10 -04:00
Markus Winter 8a9ad438cb Rename halfAngle to argument and make it public 2025-08-14 21:50:08 -04:00
Joe SchulteandMarkus Winter 1bab0de693 Update Sources/QuaternionModule/README.md
Co-authored-by: Markus Winter <markus@wntr.me>
2025-08-14 21:50:07 -04:00
Joe Schulte 0b6cdc3844 Update Quaternions README.md 2025-08-14 21:50:05 -04:00
Joe Schulte c2184941ab Update README.md for importing Quaternions 2025-08-14 21:50:04 -04:00
Markus Winter e5ed4ac651 Fix header documentation 2025-08-14 21:50:02 -04:00
Markus Winter eeff10ed00 Sync quaternion module structure with complex module 2025-08-14 21:49:57 -04:00
Markus Winter aa376839bf Remove log and pow functions 2025-08-14 21:49:21 -04:00
Markus Winter bc944e79f0 Update trig tests 2025-08-14 21:49:20 -04:00
Markus Winter ff9f52fc92 Update implementations of sin/cos/tan 2025-08-14 21:49:19 -04:00
Markus Winter 360b914e9c First stab at log1p 2025-08-14 21:49:18 -04:00
Markus Winter e7c68b70b7 Add norms to imaginary helper 2025-08-14 21:49:17 -04:00
Markus Winter c142bcedfe Add more comments to pow like functions 2025-08-14 21:49:15 -04:00
Markus Winter e8940b786e Fix sign of tan special case and add more comments 2025-08-14 21:49:13 -04:00
Markus Winter 5ea4f613d3 Fix todos and update comments 2025-08-14 21:49:12 -04:00
Markus Winter f99c42cacb Fix a typo in the comments 2025-08-14 21:49:10 -04:00
Markus Winter 9d7b668a10 Add log to quaternion 2025-08-14 21:49:09 -04:00
Markus Winter 42c26ee85d Add pow, sqrt and root to quaternions 2025-08-14 21:49:07 -04:00
Markus Winter 844aff56c5 Add cos, sin and tan to quaternions 2025-08-14 21:49:06 -04:00
Markus Winter b197152494 Add cosh, sinh and tanh to quaternions 2025-08-14 21:49:04 -04:00
Markus Winter 85281cc937 Add expMinusOne to quaternions 2025-08-14 21:49:03 -04:00
Markus Winter 52bb20ad8f Add more comments and clean up comments and variable names 2025-08-14 21:49:02 -04:00
Markus Winter af266bb9d9 Add an early skip when calculating the length in exp 2025-08-14 21:49:00 -04:00
Markus Winter 92af6727ee Add exponential function to quaternions 2025-08-14 21:48:58 -04:00
Markus Winter e9dfc766be Move imaginary helper functions into a distinct file 2025-08-14 21:48:56 -04:00
Markus Winter 211b94fb16 Add isReal to quaternion and refined comments on isPure 2025-08-14 21:48:51 -04:00
Markus Winter ea46df54b9 Account for over and underflow in quaternion length 2025-08-14 21:48:17 -04:00
Markus Winter fda8513ec0 Prevents infinite loop in quaternion act on zero lanes 2025-08-14 21:48:13 -04:00
Markus Winter 1b541a1581 Update transformation APIs to use the new SIMD initializer on quaternion 2025-08-14 21:47:29 -04:00
Markus Winter acbdeeaa3d Update Transformation.md of quaternions 2025-08-14 21:47:27 -04:00
Markus Winter 4b8ae5dd44 Update underflow tests for quaternions 2025-08-14 21:47:26 -04:00
Markus Winter daff65f930 Account for underflow in quaternion rotation 2025-08-14 21:47:24 -04:00
Markus Winter 22f1901206 Account for over/underflow on halfAngle and axis calculations 2025-08-14 21:47:23 -04:00
Markus Winter 46a25b6d61 Update angle/axis tests on quaternion 2025-08-14 21:47:21 -04:00
Markus Winter 111d482833 Update polar initializer to assume a unit axis parameter 2025-08-14 21:47:19 -04:00
Markus Winter 5c4bce2635 Add length parameter to angle/axis initializer 2025-08-14 21:47:18 -04:00
Markus Winter 31bf80751a Update documentation of act(on:) 2025-08-14 21:47:17 -04:00
Markus Winter bd99cdeffb Add links to documentation and fix typo in comment 2025-08-14 21:47:15 -04:00
Markus Winter 5b96cba10e Rename half angle with phase to make it more distinct 2025-08-14 21:47:15 -04:00
Markus Winter e99724f03b Add transformation documentation 2025-08-14 21:47:13 -04:00
Markus Winter 015c9bd961 Add transformation tests to quaternion 2025-08-14 21:47:11 -04:00
Markus Winter 896142fc32 Add method to rotate a vector by a quaternion 2025-08-14 21:47:10 -04:00
Markus Winter 528fb9daf1 Add transformation representations 2025-08-14 21:47:08 -04:00
Markus Winter ab8c3d9ddb Exposes QuaternionModule as part of the Numerics module 2025-08-14 21:47:02 -04:00
Markus Winter 1fe4ce7b1f Update documentation on 3D transformations 2025-08-14 21:46:37 -04:00
Markus Winter e50371b030 Rename transformEquals to equals(as3DTransform:) 2025-08-14 21:46:35 -04:00
Markus Winter 39bd408dad Remove duplicated comment on equatable 2025-08-14 21:46:33 -04:00
Markus Winter 06341f3bea Fix invalid canonicalizedTransform for quaternions with negative real 2025-08-14 21:46:33 -04:00
Markus Winter 1ded0b7c56 Update transformation hashing and equality tests 2025-08-14 21:46:31 -04:00
Markus Winter fb718d6f74 Rename transformCanonicalized to canonicalizedTransform 2025-08-14 21:46:30 -04:00
Markus Winter a5c6f27f26 Rename rotationEquals to transformationEquals on Quaternion 2025-08-14 21:46:29 -04:00
Markus Winter a5478a7885 Change hashing behavior of Quaternion to use the canonical form 2025-08-14 21:46:28 -04:00
Markus Winter 1b1c7cddf5 Add canonicalized transform representation to Quaternion 2025-08-14 21:46:27 -04:00
Markus Winter e7aa60d838 Add canonicalized quaternion representation 2025-08-14 21:46:25 -04:00
Markus Winter 7896ee2eef Update rotation documentation on Quaternion 2025-08-14 21:46:24 -04:00
Markus Winter e5b84606f5 Update rotation equals documentation on Quaternion 2025-08-14 21:46:23 -04:00
Markus Winter 273c6f7e54 Refine Hashable and Equatable on Quaternion 2025-08-14 21:46:23 -04:00
Markus Winter 8ec29a889b Change initializer on quaternion to be more explicit 2025-08-14 21:46:22 -04:00
Markus Winter 03e1f5ba6b Split static imaginary units on quaternion 2025-08-14 21:46:20 -04:00
Markus Winter 4188358cb4 Change quaternion initializer to more explicit variants 2025-08-14 21:46:19 -04:00
Markus Winter fcab66685d Use shorthand isZero operator on SIMD storage of quaternion 2025-08-14 21:46:17 -04:00
Markus Winter bb05e58135 Fix isNormal on quaternion 2025-08-14 21:46:15 -04:00
Markus Winter 5e1de5d8e0 Change the conjugate implementation on quaternion 2025-08-14 21:46:13 -04:00
Markus Winter 9b7cbcdb4a Flip storage order on quaternion to real part last
This commit will also replace references to a,b,c,d with r,x,y,z respectivly.
2025-08-14 21:46:12 -04:00
Markus Winter 43932b1cfe Fix parameter on multiplication header 2025-08-14 21:46:11 -04:00
Markus Winter 09c038ed3b Replace imaginary setter on quaternion with SIMD variant 2025-08-14 21:46:09 -04:00
Markus Winter 69100e86b4 Update documentation on quaternions 2025-08-14 21:46:07 -04:00
Markus Winter 2bf3285bde Make type casts explicit in quaternion tests 2025-08-14 21:46:06 -04:00
Markus Winter 4dd08f1c10 Remove debug print in quaternion tests 2025-08-14 21:46:05 -04:00
Markus Winter 00e141fb19 Update quaternion documentation 2025-08-14 21:46:04 -04:00
Markus Winter 000df70c1b Update quaternion tests 2025-08-14 21:46:02 -04:00
Markus Winter bdd9b2f4bc Update README for inclusion of quaternioin module 2025-08-14 21:45:56 -04:00
Markus Winter 2f438bd6c9 Add more basic arithmetic tests to quaternions 2025-08-14 21:45:03 -04:00
Markus Winter 57fc357bfc Fix invalid multiplication of quaternions 2025-08-14 21:45:01 -04:00
Markus Winter 7fb314a581 Update header documentation on quaternion 2025-08-14 21:45:00 -04:00
Markus Winter f1e353ec03 Split quaternion norms from polar implementation 2025-08-14 21:44:59 -04:00
Markus Winter e2ad631369 Update README in quaaternion module 2025-08-14 21:44:57 -04:00
Markus Winter e29fa04051 Add first quaternion arithmetic tests 2025-08-14 21:44:56 -04:00
Markus Winter 22ec1b960b Add property tests on quaternions 2025-08-14 21:44:54 -04:00
Markus Winter 99a7c6113d Fix typo in Quaternion Documentation 2025-08-14 21:44:52 -04:00
Markus Winter 15fee28c1f Update quaternions 2025-08-14 21:44:50 -04:00
Markus Winter dd731f3362 Add quaternion module 2025-08-14 21:44:45 -04:00
Stephen Canon be0d7c65d1 Merge pull request #325 from stephentyrone/enable-wasm-testing
Enable workflows testing for wasm.
2025-08-14 12:57:32 -04:00
Stephen Canon 5bfe9e16ce Remove relaxed add/mul for Float16 on wasm, as they cannot be defined. 2025-08-14 09:45:04 -04:00
Stephen Canon 46619b49ec Attempt to turn on workflows testing for wasm. 2025-08-14 09:40:35 -04:00
Stephen Canon 231815ea4b Merge pull request #324 from stephentyrone/disable-windows-5.9
Disable Swift 5.9 testing on Windows for now
2025-08-14 09:36:21 -04:00
Stephen Canon e74905c6d5 Disable Swift 5.9 testing on Windows for now
That docker image seems to be broken, so it's all false positives.
2025-08-14 09:08:40 -04:00
Stephen Canon a50d9575fe Merge pull request #265 from stephentyrone/docc-stuff
Documentation overhaul, including broad .docc adoption and organization.
2025-08-13 23:02:13 -04:00
Stephen Canon 1e94d23860 Cleanup further doc comment typos. 2025-08-13 14:37:51 -04:00
Stephen Canon b3fe4357f8 Fix typo. 2025-08-13 13:50:49 -04:00
Stephen Canon aa901641d1 Further docc improvements for RealModule.
This commit _also_ relaxes the constraint on Augmented algorithms from Real to FloatingPoint. It's worth calling out that fastTwoSum does not work with decimal floating-point types, so the unordered `Augemented.sum(_:_:)` now has a radix check and calls into the ordered twoSum function instead for Decimal. This makes more sense that a `BinaryFloatingPoint` constraint, as otherwise generic code written against Real or FloatingPoint would have to do the check at every call site.
2025-08-13 12:38:56 -04:00
Stephen Canon 2c19b7b8cd Last few review notes on complex. 2025-08-12 15:13:07 -04:00
Stephen Canon 221387985a Further review edits from Nate. 2025-08-12 15:04:11 -04:00
Stephen Canon 8b2fd7bbde Provide transliteration of Чебышёв. 2025-08-12 14:52:42 -04:00
Stephen Canon b43c10c1e3 Merge branch 'main' into docc-stuff 2025-08-12 13:23:02 -04:00
Stephen Canon 61a8b91b3e Some formatting cleanup around code blocks. 2025-08-12 13:20:29 -04:00
Stephen Canon 8c4747f116 Merge pull request #321 from stephentyrone/remove-2sum-assert
Remove precondition assert from Augmented.sum(large:small:)
2025-08-11 19:34:53 -04:00
Stephen Canon c3757dc266 Fix typo. (Thanks, Guillaume) 2025-08-11 19:33:27 -04:00
Stephen Canon d86286fc8b Remove precondition assert from Augmented.sum(large:small:)
This is potentially useful to identify some bugs, but there are also algorithms (notably Kahan summation) that can be written in terms of fast2sum but would fail this check. Rework documentation to account for the change.
2025-08-11 18:14:41 -04:00
Stephen Canon 9c548804c8 Massage docc files to make the Documentation check happier 2025-08-11 18:11:44 -04:00
Stephen Canon acbf4257ca Remove precondition assert from Augmented.sum(large:small:)
This is potentially useful to identify some bugs, but there are also algorithms (notably Kahan summation) that can be written in terms of fast2sum but would fail this check. Rework documentation to account for the change.
2025-08-11 18:09:22 -04:00
Stephen Canon 6ff93f255e Merge pull request #319 from lamtrinhdev/Fix_Typo_Issue
Correct typo issue at ApproximateEquality.swift
2025-08-09 20:18:34 -04:00
Stephen Canon af0352e8b1 Some additional organization for Complex docc. 2025-08-09 14:29:05 -04:00
LamTrinh.Dev e79692fab1 Correct typo issue from occured to occurred at ApproximateEquality.swift 2025-08-10 01:15:04 +07:00
Stephen Canon c1e6972eeb Merge pull request #315 from stephentyrone/algebraic-field-magnitude
Constrain AlgebraicField to required Magnitude:AlgebraicField
2025-08-08 17:17:28 -04:00
Stephen Canon da6c765795 Constrain AlgebraicField to required Magnitude:AlgebraicField
This is formally a source-breaking change. However it is expected to not be source-breaking in practice, because any conforming type either has a real magnitude (in the case of real or complex types), which would necessarily have to support all the AF operations to implement the type, or is perhaps a finite field with a bogus stand-in Magnitude.
2025-08-08 13:45:33 -04:00
Stephen Canon 2361b4959b Add overview for RealModule documentation. 2025-08-08 13:43:30 -04:00
Stephen Canon 264b17140b Merge pull request #314 from stephentyrone/relax-f16-x86
Restore relaxed mul/add bindings for Float16 on x86
2025-08-08 10:07:29 -04:00
Stephen Canon 5cc83cc00a WIP 2025-08-08 09:56:01 -04:00
Stephen Canon 5b34639450 Further documentation work for Complex. 2025-08-08 09:55:59 -04:00
Stephen Canon 450691764d typo. 2025-08-08 09:55:56 -04:00
Stephen Canon 95e9441f8c Changes from review feedback. 2025-08-08 09:55:54 -04:00
Stephen Canon d2f6811b87 More docc changes. 2025-08-08 09:55:47 -04:00
Stephen Canon 129e496ef1 Further docc work. 2025-08-08 09:55:46 -04:00
Stephen Canon 5d8425644a Initial work on docc setup. 2025-08-08 09:55:42 -04:00
Stephen Canon cd967fa90f Restore relaxed mul/add bindings for Float16 on x86
The ABI is stable, so these operations can be turned on.
2025-08-08 09:52:30 -04:00
56 changed files with 3362 additions and 334 deletions

No files matched your search

+4
View File
@@ -8,6 +8,10 @@ jobs:
tests:
name: Test
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
with:
windows_exclude_swift_versions: '[{"swift_version": "5.9"}]'
enable_wasm_sdk_build: true
wasm_sdk_build_command: swift build --target Numerics
soundness:
name: Soundness
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+21 -4
View File
@@ -20,11 +20,22 @@ let package = Package(
products: [
.library(name: "ComplexModule", targets: ["ComplexModule"]),
.library(name: "Numerics", targets: ["Numerics"]),
.library(name: "QuaternionModule", targets: ["QuaternionModule"]),
.library(name: "RealModule", targets: ["RealModule"]),
],
targets: [
// MARK: - Public API
.target(
name: "Numerics",
dependencies: [
"ComplexModule",
"IntegerUtilities",
"QuaternionModule",
"RealModule"],
exclude: excludedFilenames
),
.target(
name: "ComplexModule",
dependencies: ["RealModule"],
@@ -38,9 +49,9 @@ let package = Package(
),
.target(
name: "Numerics",
dependencies: ["ComplexModule", "IntegerUtilities", "RealModule"],
exclude: excludedFilenames
name: "QuaternionModule",
dependencies: ["RealModule"],
exclude: ["README.md", "Transformation.md"]
),
.target(
@@ -73,7 +84,7 @@ let package = Package(
.testTarget(
name: "IntegerUtilitiesTests",
dependencies: ["IntegerUtilities", "_TestSupport"],
dependencies: ["_TestSupport"],
exclude: ["CMakeLists.txt"]
),
@@ -81,6 +92,12 @@ let package = Package(
name: "RealTests",
dependencies: ["_TestSupport"],
exclude: ["CMakeLists.txt"]
),
.testTarget(
name: "QuaternionTests",
dependencies: ["_TestSupport"],
exclude: ["CMakeLists.txt"]
)
]
)
+3 -2
View File
@@ -42,7 +42,7 @@ To use Swift Numerics in a SwiftPM project:
1. Add the following line to the dependencies in your `Package.swift` file:
```swift
.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
.package(url: "https://github.com/apple/swift-numerics", branch: "Quaternions"),
```
2. Add `Numerics` as a dependency for your target:
@@ -105,7 +105,8 @@ Questions about how to use Swift Numerics modules, or issues that are not clearl
1. [`RealModule`](Sources/RealModule/README.md)
2. [`ComplexModule`](Sources/ComplexModule/README.md)
3. [`IntegerUtilities`](Sources/IntegerUtilities/README.md) (on main only, not yet present in a released tag)
3. [`QuaternionModule`](Sources/QuaternionModule/README.md) (on main only, not yet present in a released tag)
4. [`IntegerUtilities`](Sources/IntegerUtilities/README.md) (on main only, not yet present in a released tag)
## Future expansion
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -14,7 +14,7 @@ import RealModule
extension Complex: AdditiveArithmetic {
/// The additive identity, with real and imaginary parts both zero.
///
/// See also: `one`, `i`, `infinity`
/// See also: ``one``, ``i``, ``infinity``
@_transparent
public static var zero: Complex {
Complex(0, 0)
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019-2024 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -13,6 +13,8 @@ import RealModule
extension Complex: AlgebraicField {
/// The multiplicative identity `1 + 0i`.
///
/// See also: ``zero``, ``i``, ``infinity``
@_transparent
public static var one: Complex {
Complex(1, 0)
+1 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019-2020 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -32,6 +32,12 @@
// 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".
//
// Elementary functions of complex numbers have many similarities with
// elementary functions of quaternions and their definition in terms of real
// operations. Therefore, if you make a modification to one of the following
// functions, you should almost surely make a parallel modification to the same
// elementary function of quaternions.
import RealModule
+1 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
+12 -9
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -37,17 +37,20 @@ extension Complex: Numeric {
self.init(real, 0)
}
/// The ∞-norm of the value (`max(abs(real), abs(imaginary))`).
/// The infinity-norm of the value (a.k.a. "maximum norm" or "Чебышёв
/// [Chebyshev] norm").
///
/// If you need the Euclidean norm (a.k.a. 2-norm) use the `length` or
/// `lengthSquared` properties instead.
/// Equal to `max(abs(real), abs(imaginary))`.
///
/// Edge cases:
/// - If `z` is not finite, `z.magnitude` is `.infinity`.
/// - If `z` is zero, `z.magnitude` is `0`.
/// If you need to work with the Euclidean norm (a.k.a. 2-norm) instead,
/// use the ``length`` or ``lengthSquared`` properties. If you just need
/// to know "how big" a number is, use this property.
///
/// **Edge cases:**
///
/// - If `z` is not finite, `z.magnitude` is infinity.
/// - If `z` is zero, `z.magnitude` is zero.
/// - Otherwise, `z.magnitude` is finite and non-zero.
///
/// See also `.length` and `.lengthSquared`.
@_transparent
public var magnitude: RealType {
guard isFinite else { return .infinity }
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
+25 -43
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -11,39 +11,8 @@
import RealModule
/// A complex number represented by real and imaginary parts.
///
/// TODO: introductory text on complex numbers
///
/// Implementation notes:
///
/// This type does not provide heterogeneous real/complex arithmetic,
/// not even the natural vector-space operations like real * complex.
/// There are two reasons for this choice: first, Swift broadly avoids
/// mixed-type arithmetic when the operation can be adequately expressed
/// by a conversion and homogeneous arithmetic. Second, with the current
/// typechecker rules, it would lead to undesirable ambiguity in common
/// expressions (see README.md for more details).
///
/// Unlike C's `_Complex` and C++'s `std::complex<>` types, we do not
/// attempt to make meaningful semantic distinctions between different
/// representations of infinity or NaN. Any Complex value with at least
/// one non-finite component is simply "non-finite". In as much as
/// possible, we use the semantics of the point at infinity on the
/// Riemann sphere for such values. This approach simplifies the number of
/// edge cases that need to be considered for multiplication, division, and
/// the elementary functions considerably.
///
/// `.magnitude` does not return the Euclidean norm; it uses the "infinity
/// norm" (`max(|real|,|imaginary|)`) instead. There are two reasons for this
/// choice: first, it's simply faster to compute on most hardware. Second,
/// there exist values for which the Euclidean norm cannot be represented
/// (consider a number with `.real` and `.imaginary` both equal to
/// `RealType.greatestFiniteMagnitude`; the Euclidean norm would be
/// `.sqrt(2) * .greatestFiniteMagnitude`, which overflows). Using
/// the infinity norm avoids this problem entirely without significant
/// downsides. You can access the Euclidean norm using the `length`
/// property.
// A [complex number](https://en.wikipedia.org/wiki/Complex_number).
// See Documentation.docc/Complex.md for more details.
@frozen
public struct Complex<RealType> where RealType: Real {
// A note on the `x` and `y` properties
@@ -53,11 +22,11 @@ public struct Complex<RealType> where RealType: Real {
// `.real` and `.imaginary` properties, which wrap this storage and
// fixup the semantics for non-finite values.
/// The real component of the value.
/// The storage for the real component of the value.
@usableFromInline @inline(__always)
internal var x: RealType
/// The imaginary part of the value.
/// The storage for the imaginary part of the value.
@usableFromInline @inline(__always)
internal var y: RealType
@@ -95,11 +64,24 @@ extension Complex {
set { y = newValue }
}
/// The raw representation of the value.
///
/// Use this when you need the underlying RealType values,
/// without fixup for NaN or infinity.
public var rawStorage: (x: RealType, y: RealType) {
@_transparent
get { (x, y) }
@_transparent
set { (x, y) = newValue }
}
/// The raw representation of the real part of this value.
@available(*, deprecated, message: "Use rawStorage")
@_transparent
public var _rawX: RealType { x }
/// The raw representation of the imaginary part of this value.
@available(*, deprecated, message: "Use rawStorage")
@_transparent
public var _rawY: RealType { y }
}
@@ -107,7 +89,7 @@ extension Complex {
extension Complex {
/// The imaginary unit.
///
/// See also `.zero`, `.one` and `.infinity`.
/// See also ``zero``, ``one`` and ``infinity``.
@_transparent
public static var i: Complex {
Complex(0, 1)
@@ -115,7 +97,7 @@ extension Complex {
/// The point at infinity.
///
/// See also `.zero`, `.one` and `.i`.
/// See also ``zero``, ``one`` and ``i``.
@_transparent
public static var infinity: Complex {
Complex(.infinity, 0)
@@ -125,7 +107,7 @@ extension Complex {
///
/// A complex value is finite if neither component is an infinity or nan.
///
/// See also `.isNormal`, `.isSubnormal` and `.isZero`.
/// See also ``isNormal``, ``isSubnormal`` and ``isZero``.
@_transparent
public var isFinite: Bool {
x.isFinite && y.isFinite
@@ -138,7 +120,7 @@ extension Complex {
/// one of the components is normal if its exponent allows a full-precision
/// representation.
///
/// See also `.isFinite`, `.isSubnormal` and `.isZero`.
/// See also ``isFinite``, ``isSubnormal`` and ``isZero``.
@_transparent
public var isNormal: Bool {
isFinite && (x.isNormal || y.isNormal)
@@ -150,7 +132,7 @@ extension Complex {
/// When the result of a computation is subnormal, underflow has occurred and
/// the result generally does not have full precision.
///
/// See also `.isFinite`, `.isNormal` and `.isZero`.
/// See also ``isFinite``, ``isNormal`` and ``isZero``.
@_transparent
public var isSubnormal: Bool {
isFinite && !isNormal && !isZero
@@ -161,7 +143,7 @@ extension Complex {
/// A complex number is zero if *both* the real and imaginary components
/// are zero.
///
/// See also `.isFinite`, `.isNormal` and `isSubnormal`.
/// See also ``isFinite``, ``isNormal`` and ``isSubnormal``.
@_transparent
public var isZero: Bool {
x == 0 && y == 0
@@ -200,7 +182,7 @@ extension Complex {
self.init(real, 0)
}
/// The complex number with specified imaginary part and zero real part.
/// The complex number with zero real part and specified imaginary part.
///
/// Equivalent to `Complex(0, imaginary)`.
@inlinable
@@ -0,0 +1,67 @@
# ``Complex``
A complex number type represented by its real and imaginary parts, and equipped
with the usual arithmetic operators and math functions.
## Overview
You can access these Cartesian components using the real and imaginary
properties.
```swift
let z = Complex(1,-1) // 1 - i
let re = z.real // 1
let im = z.imaginary // -1
```
All `Complex` numbers with a non-finite component are treated as a single
"point at infinity," with infinite magnitude and indeterminant phase. Thus,
the real and imaginary parts of an infinity are nan.
```swift
let w = Complex<Double>.infinity
w == -w // true
let re = w.real // .nan
let im = w.imag // .nan
```
See <doc:Infinity> for more details.
The ``magnitude`` property of a complex number is the infinity norm of the
value (a.k.a. “maximum norm” or “Чебышёв [Chebyshev] norm”). To get the two
norm (a.k.a. "Euclidean norm"), use the ``length`` property. See
<doc:Magnitude> for more details.
## Topics
### Real and imaginary parts
- ``real``
- ``imaginary``
- ``rawStorage``
- ``init(_:_:)``
- ``init(_:)-5aesj``
- ``init(imaginary:)``
### Phase, length and magnitude
- ``magnitude``
- ``length``
- ``lengthSquared``
- ``normalized``
- ``phase``
- ``polar``
- ``init(length:phase:)``
### Scaling by real numbers
- ``multiplied(by:)``
- ``divided(by:)``
### Complex-specific operations
- ``conjugate``
### Classification
- ``isZero``
- ``isSubnormal``
- ``isNormal``
- ``isFinite``
@@ -0,0 +1,88 @@
# ``ComplexModule``
Types and operations for working with complex numbers.
## Overview
### Representation
The `Complex` type is generic over an associated `RealType`; complex numbers
are represented as two `RealType` values, the real and imaginary parts of the
number.
```
let z = Complex<Double>(1, 2)
let re = z.real
let im = z.imaginary
```
### Memory layout
A `Complex` value is stored as two `RealType` values arranged consecutively
in memory. Thus it has the same memory layout as:
- A Fortran complex value built on the corresponding real type (as used
by BLAS and LAPACK).
- A C struct with real and imaginary parts and nothing else (as used by
computational libraries predating C99).
- A C99 `_Complex` value built on the corresponding real type.
- A C++ `std::complex` value built on the corresponding real type.
Functions taking complex arguments in these other languages are not
automatically converted on import, but you can safely write shims that
map them into Swift types by converting pointers.
### Real-Complex arithmetic
Because the real numbers are a subset of the complex numbers, many
languages support arithmetic with mixed real and complex operands.
For example, C allows the following:
```c
#include <complex.h>
double r = 1;
double complex z = CMPLX(0, 2); // 2i
double complex w = r + z; // 1 + 2i
```
The `Complex` type does not provide such mixed operators:
```swift
let r = 1.0
let z = Complex(imaginary: 2.0)
let w = r + z // error: binary operator '+' cannot be applied to operands of type 'Double' and 'Complex<Double>'
```
In order to write the example from C above in Swift, you have to perform an
explicit conversion:
```swift
let r = 1.0
let z = Complex(imaginary: 2.0)
let w = Complex(r) + z // OK
```
There are two reasons for this choice. Most importantly, Swift generally avoids
mixed-type arithmetic. Second, if we _did_ provide such heterogeneous operators,
it would lead to undesirable behavior in common expressions when combined with
literal type inference. Consider the following example:
```swift
let a: Double = 1
let b = 2*a
```
`b` ought to have type `Double`, but if we did have a Complex-by-Real `*`
operation, `2*a` would either be ambiguous (if there were no type context),
or be inferred to have type `Complex<Double>` (if the expression appeared
in the context of an extension defined on `Complex`).
Note that we _do_ provide heterogeneous multiplication and division by a real
value, spelled as ``Complex/divided(by:)`` and ``Complex/multiplied(by:)``
to avoid ambiguity.
```swift
let z = Complex<Double>(1,3)
let w = z.multiplied(by: 2)
```
These operations are generally more efficient than converting the scale to
a complex number and then using `*` or `/`.
@@ -0,0 +1,55 @@
# Zero and infinity
Semantics of `Complex` zero and infinity values, and important considerations
when porting code from other languages.
## Overview
Unlike C and C++'s complex types, `Complex` does not attempt to make a
semantic distinction between different infinity and NaN values. Any `Complex`
datum with a non-finite component is treated as the "point at infinity" on
the Riemann sphere--a value with infinite magnitude and unspecified phase.
As a consequence, all values with either component infinite or NaN compare
equal, and hash the same. Similarly, all zero values compare equal and hash
the same.
### Rationale
This choice has some drawbacks,¹ but also some significant advantages.
In particular, complex multiplication is the most common operation performed
with a complex type, and one would like to be able to use the usual naive
arithmetic implementation, consisting of four real multiplications and two
real additions:
```
(a + bi) * (c + di) = (ac - bd) + (ad + bc)i
```
`Complex` can use this implementation, because we do not differentiate between
infinities and NaN values. C and C++, by contrast, cannot use this
implementation by default, because, for example:
```
(1 + ∞i) * (0 - 2i) = (1*0 - ∞*(-2)) + (1*(-2) + ∞*0)i
= (0 - ∞) + (-2 + nan)i
= -∞ + nan i
```
`Complex` treats this as "infinity", which is the correct result. C and C++
treat it as a nan value, however, which is incorrect; infinity multiplied
by a non-zero number should be infinity. Thus, C and C++ (by default) must
detect these special cases and fix them up, which makes multiplication a
more computationally expensive operation.²
### Footnotes:
¹ W. Kahan, Branch Cuts for Complex Elementary Functions, or Much Ado
About Nothing's Sign Bit. In A. Iserles and M.J.D. Powell, editors,
_Proceedings The State of Art in Numerical Analysis_, pages 165–211, 1987.
² This can be addressed in C programs by use of the `STDC CX_LIMITED_RANGE`
pragma, which instructs the compiler to simply not care about these cases.
Unfortunately, this pragma is not often used in real C or C++ programs
(though it does see some use in _libraries_). Programmers tend to specify
`-ffast-math` or maybe `-ffinite-math-only` instead, which has other
undesirable consequences.
@@ -0,0 +1,144 @@
# Magnitude and norms
Introduction to the concept of norm and discussion of the `Complex` type's
`.magnitude` property.
## Overview
In mathematics, a *norm* is a function that gives each element of a vector
space a non-negative length.¹
Many different norms can be defined on the complex numbers, viewed as a
vector space over the reals. All of these norms have some basic
properties. If we use *‖z‖* to represent any norm of *z*, it must:
- be *subadditive* (a.k.a. satisfy the triangle inequalty):
‖z + w‖ ≤ ‖z‖ + ‖w‖ for any two complex numbers z and w.
- be *homogeneous*
‖az‖ = |a|‖z‖ for any real number a and complex number z.
- and be *positive definite*
‖z‖ is zero if and only if z is zero.
The three most commonly-used norms are:
- 1-norm ("taxicab norm"):
‖x + iy‖₁ = |x| + |y|
- 2-norm ("Euclidean norm"):
‖x + iy‖₂ = √(x² + y²)
- ∞-norm ("maximum norm" or "Чебышёв [Chebyshev] norm")²:
‖x + iy‖ = max(|x|,|y|)
> Exercise:
> 1. Check that these properties hold for one of the three norms
that we just defined. (Hint: write z = a+bi and w = c+di,
and use the fact that the absolute value is a norm on the
real numbers, and therefore has the same property).
The `Complex` type gives special names to two of these norms; `length`
for the 2-norm, and `magnitude` for the ∞-norm.
### Magnitude:
The `Numeric` protocol requires us to choose a norm to call `magnitude`,
but does not give guidance as to which one we should pick. The easiest choice
might have been the Euclidean norm; it's the one with which people are most
likely to be familiar.
However, there are good reasons to make a different choice:
- Computing the Euclidean norm requires special care to avoid spurious
overflow/underflow (see implementation notes for `length` below). The
naive expressions for the taxicab and maximum norm always give the best
answer possible.
- Even when special care is used, the Euclidean and taxicab norms are
not necessarily representable. Both can be infinite even for finite
numbers.
```swift
let big = Double.greatestFiniteMagnitude
let z = Complex(big, big)
```
The taxicab norm of `z` would be `big + big`, which overflows; the
Euclidean norm would be `sqrt(2) * big`, which also overflows.
But the maximum norm is always equal to the magnitude of either `real`
or `imaginary`, so it is necessarily representable.
- The ∞-norm is the choice of established computational libraries, like
BLAS and LAPACK.
For these reasons, the `magnitude` property of `Complex` binds the
maximum norm:
```swift
Complex(2, 3).magnitude // 3
Complex(-1, 0.5).magnitude // 1
```
### Length:
The `length` property of a `Complex` value is its Euclidean norm.
```swift
Complex(2, 3).length // 3.605551275463989
Complex(-1, 0.5).length // 1.118033988749895
```
Aside from familiarity, the Euclidean norm has one important property
that the maximum norm lacks:
- it is *multiplicative*:
‖zw‖₂ = ‖z‖₂‖w‖₂ for any two complex numbers z and w.
> Exercises:
> 1. Find z and w that show that the maximum norm is not multiplicative.
(i.e. exhibit z and w such that ‖zw‖ ≠ ‖z‖‖w‖.)
> 2. Is the 1-norm multiplicative?
### Implementation notes:
The `length` property takes special care to produce an accurate answer,
even when the value is poorly-scaled. The naive expression for `length`
would be `sqrt(x*x + y*y)`, but this can overflow or underflow even when
the final result should be a finite number.
```swift
// Suppose that length were implemented like this:
extension Complex {
var naiveLength: RealType {
.sqrt(real*real + imaginary*imaginary)
}
}
// Then taking the length of even a modestly large number:
let z = Complex<Float>(1e20, 1e20)
// or small number:
let w = Complex<Float>(1e-24, 1e-24)
// would overflow:
z.naiveLength // Inf
// or underflow:
w.naiveLength // 0
```
Instead, `length` is implemented using a two-step algorithm. First we
compute `lengthSquared`, which is `x*x + y*y`. If this is a normal
number (meaning that no overflow or underflow has occured), we can safely
return its square root. Otherwise, we redo the computation with a more
careful computation, which avoids spurious under- or overflow:
```swift
let z = Complex<Float>(1e20, 1e20)
let w = Complex<Float>(1e-24, 1e-24)
z.length // 1.41421358E+20
w.length // 1.41421362E-24
```
### Footnotes:
¹ Throughout this documentation, "norm" refers to a
[vector norm](https://en.wikipedia.org/wiki/Norm_(mathematics)).
To confuse the matter, there are several similar things also called
"norm" in mathematics. The other one you are most likely to run into
is the [field norm](https://en.wikipedia.org/wiki/Field_norm).
Field norms are much less common than vector norms, but the C++
`std::norm` operation implements a field norm. To get the (Euclidean)
vector norm in C++, use `std::abs`.
² There's no subscript-∞ in unicode, so I write the infinity norm
without the usual subscript.
+18 -21
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -12,7 +12,7 @@
import RealModule
extension Complex {
/// The Euclidean norm (a.k.a. 2-norm, `sqrt(real*real + imaginary*imaginary)`).
/// The Euclidean norm (a.k.a. 2-norm).
///
/// This property takes care to avoid spurious over- or underflow in
/// this computation. For example:
@@ -26,15 +26,15 @@ extension Complex {
/// because the length can be as much as sqrt(2) times larger than
/// either component, and thus may not be representable in the real type.
///
/// For most use cases, you can use the cheaper `.magnitude`
/// For most use cases, you can use the cheaper ``magnitude``
/// property (which computes the ∞-norm) instead, which always produces
/// a representable result.
/// a representable result. See <doc:Magnitude> for more details.
///
/// Edge cases:
/// - If a complex value is not finite, its `.length` is `infinity`.
/// - If a complex value is not finite, its `length` is `infinity`.
///
/// See also `.magnitude`, `.lengthSquared`, `.phase`, `.polar`
/// and `init(r:θ:)`.
/// See also ``lengthSquared``, ``phase``, ``polar``
/// and ``init(length:phase:)``.
@_transparent
public var length: RealType {
let naive = lengthSquared
@@ -42,7 +42,7 @@ extension Complex {
return .sqrt(naive)
}
// Internal implementation detail of `length`, moving slow path off
// Internal implementation detail of ``length``, moving slow path off
// of the inline function. Note that even `carefulLength` can overflow
// for finite inputs, but only when the result is outside the range
// of representable values.
@@ -54,34 +54,31 @@ extension Complex {
/// The squared length `(real*real + imaginary*imaginary)`.
///
/// This property is more efficient to compute than `length`, but is
/// This property is more efficient to compute than ``length``, but is
/// highly prone to overflow or underflow; for finite values that are
/// not well-scaled, `lengthSquared` is often either zero or
/// infinity, even when `length` is a finite number. Use this property
/// only when you are certain that this value is well-scaled.
///
/// For many cases, `.magnitude` can be used instead, which is similarly
/// For many cases, ``magnitude`` can be used instead, which is similarly
/// cheap to compute and always returns a representable value.
///
/// See also `.length` and `.magnitude`.
/// Note that because of how `lengthSquared` is used, it is a primary
/// design goal that it be as fast as possible. Therefore, it does not
/// normalize infinities, and may return either `.infinity` or `.nan`
/// for non-finite values.
@_transparent
public var lengthSquared: RealType {
x*x + y*y
}
@available(*, unavailable, renamed: "lengthSquared")
public var unsafeLengthSquared: RealType { lengthSquared }
/// The phase (angle, or "argument").
///
/// Returns the angle (measured above the real axis) in radians. If
/// - Returns: The angle (measured above the real axis) in radians. If
/// the complex value is zero or infinity, the phase is not defined,
/// and `nan` is returned.
///
/// Edge cases:
/// - If the complex value is zero or non-finite, phase is `nan`.
///
/// See also `.length`, `.polar` and `init(r:θ:)`.
/// See also ``length``, ``polar`` and ``init(length:phase:)``.
@inlinable
public var phase: RealType {
guard isFinite && !isZero else { return .nan }
@@ -94,7 +91,7 @@ extension Complex {
/// - If the complex value is zero or non-finite, phase is `.nan`.
/// - If the complex value is non-finite, length is `.infinity`.
///
/// See also: `.length`, `.phase` and `init(r:θ:)`.
/// See also: ``length``, ``phase`` and ``init(length:phase:)``.
public var polar: (length: RealType, phase: RealType) {
(length, phase)
}
@@ -117,7 +114,7 @@ extension Complex {
/// ```
/// - Otherwise, `θ` must be finite, or a precondition failure occurs.
///
/// See also `.length`, `.phase` and `.polar`.
/// See also ``length``, ``phase`` and ``polar``.
@inlinable
public init(length: RealType, phase: RealType) {
if phase.isFinite {
+13 -27
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -20,36 +20,22 @@
// what is the type of b? If we don't have a type context, it's ambiguous.
// If we have a Complex type context, then b will be inferred to have type
// Complex! Obviously, that doesn't help anyone.
//
// TODO: figure out if there's some way to avoid these surprising results
// and turn these into operators if/when we have it.
// (https://github.com/apple/swift-numerics/issues/12)
extension Complex {
/// `self` scaled by `a`.
@usableFromInline @_transparent
internal func multiplied(by a: RealType) -> Complex {
// This can be viewed in two different ways, which are mathematically
// equivalent: either we are computing `self * Complex(a)` (i.e.
// converting `a` to be a complex value, and then using the complex
// multiplication) or we are using the scalar product of the vector
// space structure: `Complex(a*real, a*imaginary)`.
//
// Although these two interpretations are _mathematically_ equivalent,
// they will generate different representations of the point at
// infinity in general. For example, suppose `self` is represented by
// `(infinity, 0)`. Then `self * Complex(1)` would evaluate as
// `(1*infinity - 0*0, 0*infinity + 1*0) = (infinity, nan)`, but
// the vector space interpretation produces `(infinity, 0)`. This does
// not matter much, because these are two representations of the same
// semantic value, but note that one requires four multiplies and two
// additions, while the one we use requires only two real multiplications.
/// The result of multiplying this value by the real number `a`.
///
/// Equivalent to `self * Complex(a)`, but may be computed more efficiently.
@inlinable @inline(__always)
public func multiplied(by a: RealType) -> Complex {
Complex(x*a, y*a)
}
/// `self` unscaled by `a`.
@usableFromInline @_transparent
internal func divided(by a: RealType) -> Complex {
// See implementation notes for `multiplied` above.
/// The result of dividing this value by the real number `a`.
///
/// More efficient than `self / Complex(a)`. May not produce exactly the
/// same result, but will always be more accurate if they differ.
@inlinable @inline(__always)
public func divided(by a: RealType) -> Complex {
Complex(x/a, y/a)
}
}
@@ -12,26 +12,29 @@
extension BinaryInteger {
/// `self` divided by `other`, rounding the result according to `rule`.
///
/// The default rounding rule is `.down`, which _is not the same_ as the
/// behavior of the `/` operator from the Swift standard library, but is
/// chosen because it generally produces a more useful remainder. In
/// particular, when `b` is positive, the remainder is always positive.
/// To match the behavior of `/`, use the `.towardZero` rounding mode.
/// By default, this function uses ``RoundingRule/down``, which **is not
/// the same** as the rounding of the `/` operator from the Swift standard
/// library. They agree when the signs of the arguments match, but produce
/// different results when the quotient is negative. This behavior is
/// chosen because it generally produces a more useful remainder; in
/// particular, when the divisor is positive, the remainder is always
/// positive. To match the behavior of `/`, use ``RoundingRule/towardZero``.
///
/// Note that the remainder of division is not always representable in an
/// unsigned type if a rounding rule other than `.down`, `.towardZero`, or
/// `.requireExact` is used. For example:
///
/// let a: UInt = 5
/// let b: UInt = 3
/// let q = a.divided(by: b, rounding: .up) // 2
/// let r = a - b*q // 5 - 3*2 overflows UInt.
///
/// unsigned type if a rounding rule other than ``RoundingRule/down``,
/// ``RoundingRule/towardZero``, or ``RoundingRule/requireExact`` is
/// used. For example:
/// ```swift
/// let a: UInt = 5
/// let b: UInt = 3
/// let q = a.divided(by: b, rounding: .up) // 2
/// let r = a - b*q // 5 - 3*2 overflows UInt.
/// ```
/// For this reason, there is no `remainder(dividingBy:rounding:)`
/// operation defined on `BinaryInteger`. Signed integers do not have
/// this problem, so it is defined on the `SignedInteger` protocol
/// instead, as is an overload of `divided(by:rounding:)` that returns
/// both quotient and remainder.
/// this problem, so the `SignedInteger` protocol is extended with
/// ``SignedInteger/divided(by:rounding:)`` returning both quotient
/// and remainder.
@inlinable
public func divided(
by other: Self,
@@ -52,7 +55,7 @@ extension BinaryInteger {
// rounded toward zero.
//
// If we subtract 1 from q, we add other to r to compensate, because:
//
//
// self = q*other + r
// = (q-1)*other + (r+other)
//
@@ -151,10 +154,10 @@ extension SignedInteger {
/// Divides `self` by `other`, rounding the quotient according to `rule`,
/// and returns the remainder.
///
/// The default rounding rule is `.down`, which _is not the same_ as the
/// behavior of the `%` operator from the Swift standard library, but is
/// chosen because it generally produces a more useful remainder. To
/// match the behavior of `%`, use the `.towardZero` rounding mode.
/// The default rounding rule is ``RoundingRule/down``, which _is not the
/// same_ as the behavior of the `%` operator from the Swift standard
/// library, but is chosen because it generally produces a more useful
/// remainder. To match the behavior of `%`, use ``RoundingRule/towardZero``.
///
/// - Precondition: `other` cannot be zero.
@inlinable
@@ -170,10 +173,10 @@ extension SignedInteger {
/// Divides `self` by `other`, rounding the quotient according to `rule`,
/// and returns both the quotient and remainder.
///
/// The default rounding rule is `.down`, which _is not the same_ as the
/// behavior of the `/` operator from the Swift standard library, but is
/// chosen because it generally produces a more useful remainder. To
/// match the behavior of `/`, use the `.towardZero` rounding mode.
/// The default rounding rule is ``RoundingRule/down``, which _is not the
/// same_ as the behavior of the `%` operator from the Swift standard
/// library, but is chosen because it generally produces a more useful
/// remainder. To match the behavior of `/`, use ``RoundingRule/towardZero``.
///
/// Because the default rounding mode does not match Swift's standard
/// library, this function is a disfavored overload of `divided(by:)`
@@ -31,8 +31,8 @@ extension FixedWidthInteger {
/// let c = a.addingWithSaturation(b)
/// ```
///
/// Anytime the "normal addition" `self + other` does not trap,
/// `addingWithSaturation` produces the same result.
/// If the "normal addition" `self + other` does not trap,
/// this method produces the same result.
@inlinable
public func addingWithSaturation(_ other: Self) -> Self {
let (wrapped, overflow) = addingReportingOverflow(other)
@@ -54,8 +54,8 @@ extension FixedWidthInteger {
/// `a.subtractingWithSaturation(b)`, because `-b` is not representable
/// if `b` is the minimum value of a signed type.
///
/// Anytime the "normal subtraction" `self - other` does not trap,
/// `subtractingWithSaturation` produces the same result.
/// If the "normal subtraction" `self - other` does not trap,
/// this method produces the same result.
@inlinable
public func subtractingWithSaturation(_ other: Self) -> Self {
let (wrapped, overflow) = subtractingReportingOverflow(other)
@@ -85,8 +85,8 @@ extension FixedWidthInteger {
/// let c = a.multipliedWithSaturation(by: b)
/// ```
///
/// Anytime the "normal multiplication" `self * other` does not trap,
/// `multipliedWithSaturation` produces the same result.
/// If the "normal multiplication" `self * other` does not trap,
/// this method produces the same result.
@inlinable
public func multipliedWithSaturation(by other: Self) -> Self {
let (high, low) = multipliedFullWidth(by: other)
@@ -100,12 +100,12 @@ extension FixedWidthInteger {
/// `self` multiplied by the rational number 2^(`count`), saturated to the
/// range `Self.min ... Self.max`, and rounded according to `rule`.
///
/// See `shifted(rightBy:rounding:)` for more discussion of rounding
/// shifts with examples.
/// See `shifted(rightBy:rounding:)`, defined on `BinaryInteger`, for more
/// discussion of rounding shifts with examples.
///
/// - Parameters:
/// - leftBy count: the number of bits to shift by. If positive, this is a left-shift,
/// and if negative a right shift.
/// - leftBy count: the number of bits to shift by. If positive, this is
/// a left-shift, and if negative a right shift.
/// - rounding rule: the direction in which to round if `count` is negative.
@inlinable
public func shiftedWithSaturation(
@@ -12,8 +12,8 @@
extension BinaryInteger {
/// `self` divided by 2^(`count`), rounding the result according to `rule`.
///
/// The default rounding rule is `.down`, which matches the behavior of
/// the `>>` operator from the standard library.
/// The default rounding rule is ``RoundingRule/down``, which matches the
/// behavior of the `>>` operator from the standard library.
///
/// Some examples of different rounding rules:
///
@@ -138,8 +138,8 @@ extension BinaryInteger {
/// `self` divided by 2^(`count`), rounding the result according to `rule`.
///
/// The default rounding rule is `.down`, which matches the behavior of
/// the `>>` operator from the standard library.
/// The default rounding rule is ``RoundingRule/down``, which matches the
/// behavior of the `>>` operator from the standard library.
///
/// Some examples of different rounding rules:
///
+1
View File
@@ -13,3 +13,4 @@
@_exported import ComplexModule
@_exported import IntegerUtilities
@_exported import RealModule
@_exported import QuaternionModule
@@ -0,0 +1,83 @@
//===--- ImaginaryHelper.swift --------------------------------*- swift -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2019-2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
// Provides common vector operations on SIMD3 to ease the use of the quaternions
// imaginary/vector components internally to the module, and in tests.
extension SIMD3 where Scalar: FloatingPoint {
/// Returns a vector with infinity in all lanes
@usableFromInline @inline(__always)
internal static var infinity: Self {
SIMD3(repeating: .infinity)
}
/// Returns a vector with nan in all lanes
@usableFromInline @inline(__always)
internal static var nan: Self {
SIMD3(repeating: .nan)
}
/// True if all values of this instance are finite
@usableFromInline @inline(__always)
internal var isFinite: Bool {
x.isFinite && y.isFinite && z.isFinite
}
/// The ∞-norm of the value (`max(abs(x), abs(y), abs(z))`).
@usableFromInline @inline(__always)
internal var magnitude: Scalar {
Swift.max(x.magnitude, y.magnitude, z.magnitude)
}
/// The 1-norm of the value (`abs(x) + abs(y) + abs(z))`).
@usableFromInline @inline(__always)
internal var oneNorm: Scalar {
x.magnitude + y.magnitude + z.magnitude
}
/// The Euclidean norm (a.k.a. 2-norm, `sqrt(x*x + y*y + z*z)`).
@usableFromInline @inline(__always)
internal var length: Scalar {
let naive = lengthSquared
guard naive.isNormal else { return carefulLength }
return naive.squareRoot()
}
// Implementation detail of `length`, moving slow path off of the
// inline function.
@usableFromInline
internal var carefulLength: Scalar {
guard isFinite else { return .infinity }
guard !magnitude.isZero else { return .zero }
// Unscale the vector, calculate its length and rescale the result
return (self / magnitude).length * magnitude
}
/// Returns the squared length of this instance.
@usableFromInline @inline(__always)
internal var lengthSquared: Scalar {
dot(self)
}
/// Returns the scalar/dot product of this vector with `other`.
@usableFromInline @inline(__always)
internal func dot(_ other: SIMD3<Scalar>) -> Scalar {
(self * other).sum()
}
/// Returns the vector/cross product of this vector with `other`.
@usableFromInline @inline(__always)
internal func cross(_ other: SIMD3<Scalar>) -> SIMD3<Scalar> {
let yzx = SIMD3<Int>(1,2,0)
let zxy = SIMD3<Int>(2,0,1)
return (self[yzx] * other[zxy]) - (self[zxy] * other[yzx])
}
}
+201
View File
@@ -0,0 +1,201 @@
//===--- Polar.swift ------------------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import RealModule
// Norms and related quantities defined for Quaternion.
//
// The following API are provided by this extension:
//
// var magnitude: RealType // infinity norm
// var length: RealType // Euclidean norm
// var lengthSquared: RealType // Euclidean norm squared
//
// For detailed documentation, consult Norms.md or the inline documentation
// for each operation.
//
// Implementation notes:
//
// `.magnitude` does not bind the Euclidean norm; it binds the infinity norm
// instead. There are two reasons for this choice:
//
// - It's simply faster to compute in general, because it does not require
// a square root.
//
// - There exist finite values `q` for which the Euclidean norm is not
// representable (consider the quaternion with `r`, `x`, `y` and `z` all
// equal to `RealType.greatestFiniteMagnitude`; the Euclidean norm is
// `.sqrt(4) * .greatestFiniteMagnitude`, which overflows).
//
// The infinity norm is unique among the common vector norms in having
// the property that every finite vector has a representable finite norm,
// which makes it the obvious choice to bind `.magnitude`.
extension Quaternion {
/// The Euclidean norm (a.k.a. 2-norm, `sqrt(r*r + x*x + y*y + z*z)`).
///
/// This value is highly prone to overflow or underflow.
///
/// For most use cases, you can use the cheaper `.magnitude`
/// property (which computes the ∞-norm) instead, which always produces
/// a representable result.
///
/// Edge cases:
/// - If a quaternion is not finite, its `.length` is `infinity`.
///
/// See also `.magnitude`, `.lengthSquared`, `.polar` and
/// `init(length:halfAngle:axis:)`.
@_transparent
public var length: RealType {
let naive = lengthSquared
guard naive.isNormal else { return carefulLength }
return .sqrt(naive)
}
// Internal implementation detail of `length`, moving slow path off
// of the inline function.
@usableFromInline
internal var carefulLength: RealType {
guard isFinite else { return .infinity }
guard !magnitude.isZero else { return .zero }
// Unscale the quaternion, calculate its length and rescale the result
return divided(by: magnitude).length * magnitude
}
/// The squared length `(r*r + x*x + y*y + z*z)`.
///
/// This value is highly prone to overflow or underflow.
///
/// For many cases, `.magnitude` can be used instead, which is similarly
/// cheap to compute and always returns a representable value.
///
/// This property is more efficient to compute than `length`.
///
/// See also `.magnitude`, `.length`, `.polar` and
/// `init(length:halfAngle:axis:)`.
@_transparent
public var lengthSquared: RealType {
(components * components).sum()
}
/// The half rotation angle in radians within *[0, π]* range.
///
/// Edge cases:
/// - If the quaternion is zero or non-finite, halfAngle is `nan`.
@inlinable
public var halfAngle: RealType {
guard isFinite else { return .nan }
// A zero quaternion does not encode transformation properties.
// If imaginary is zero, real must be non-zero or nan is returned.
guard !isReal else { return isPure ? .nan : .zero }
// If lengthSquared computes without over/underflow, everything is fine
// and the result is correct. If not, we have to do the computation
// carefully and unscale the quaternion first.
let lenSq = imaginary.lengthSquared
guard lenSq.isNormal else { return divided(by: magnitude).halfAngle }
return .atan2(y: .sqrt(lenSq), x: real)
}
/// The [polar decomposition][wiki].
///
/// Returns the length of this quaternion, halfAngle in radians of range
/// *[0, π]* and the rotation axis as SIMD3 vector of unit length.
///
/// Edge cases:
/// - If the quaternion is zero, length is `.zero` and halfAngle and axis
/// are `nan`.
/// - If the quaternion is non-finite, length is `.infinity` and halfAngle and
/// axis are `nan`.
/// - For any length other than `.zero` or `.infinity`, if halfAngle is zero,
/// axis is `nan`.
///
/// See also `.magnitude`, `.length`, `.lengthSquared` and
/// `init(length:halfAngle:axis:)`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
public var polar: (
length: RealType,
halfAngle: RealType,
axis: SIMD3<RealType>
) {
(length, halfAngle, axis)
}
/// Creates a new quaternion from given half rotation angle about given
/// rotation axis.
///
/// The angle-axis values are transformed using the following equation:
///
/// Q = (cos(halfAngle), unitAxis * sin(halfAngle))
///
/// - Parameters:
/// - halfAngle: The half rotation angle
/// - unitAxis: The rotation axis of unit length
@usableFromInline @inline(__always)
internal init(halfAngle: RealType, unitAxis: SIMD3<RealType>) {
self.init(real: .cos(halfAngle), imaginary: unitAxis * .sin(halfAngle))
}
/// Creates a quaternion specified with [polar coordinates][wiki].
///
/// This initializer reads given `length`, `halfAngle` and `axis` values and
/// creates a quaternion of equal rotation properties and specified *length*
/// using the following equation:
///
/// Q = (cos(halfAngle), axis * sin(halfAngle)) * length
///
/// Edge cases:
/// - Negative lengths are interpreted as reflecting the point through the
/// origin, i.e.:
/// ```
/// Quaternion(length: -r, halfAngle: θ, axis: axis) == -Quaternion(length: r, halfAngle: θ, axis: axis)
/// ```
/// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
/// ```
/// Quaternion(length: .zero, halfAngle: θ, axis: axis) == .zero
/// ```
/// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
/// ```
/// Quaternion(length: .infinity, halfAngle: θ, axis: axis) == .infinity
/// ```
/// - Otherwise, `θ` must be finite, or a precondition failure occurs and
/// `axis` must be of unit length, or an assertion failure occurs.
///
/// See also `.magnitude`, `.length`, `.lengthSquared` and `.polar`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
@inlinable
public init(length: RealType, halfAngle: RealType, axis: SIMD3<RealType>) {
guard !length.isZero, length.isFinite else {
self = Quaternion(length)
return
}
// Length is finite and non-zero, therefore
// 1. `halfAngle` must be finite or a precondition failure needs to occur;
// as this is not representable.
// 2. `axis` must be of unit length or an assertion failure occurs; while
// "wrong" by definition, it is representable.
precondition(
halfAngle.isFinite,
"Either halfAngle must be finite, or length must be zero or infinite."
)
assert(
// TODO: Replace with `approximateEquality()`
abs(.sqrt(axis.lengthSquared)-1) < max(.sqrt(axis.lengthSquared), 1)*RealType.ulpOfOne.squareRoot(),
"Given axis must be of unit length."
)
self = Quaternion(
halfAngle: halfAngle,
unitAxis: axis
).multiplied(by: length)
}
}
@@ -0,0 +1,41 @@
//===--- Quaternion+AdditiveArithmetic.swift ------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: AdditiveArithmetic {
/// The additive identity, with real and *all* imaginary parts zero, i.e.:
/// `0 + 0i + 0j + 0k`
///
/// See also: `one`, `i`, `j`, `k`, `infinity`
@_transparent
public static var zero: Quaternion {
Quaternion(from: SIMD4(repeating: 0))
}
@_transparent
public static func + (lhs: Quaternion, rhs: Quaternion) -> Quaternion {
Quaternion(from: lhs.components + rhs.components)
}
@_transparent
public static func - (lhs: Quaternion, rhs: Quaternion) -> Quaternion {
Quaternion(from: lhs.components - rhs.components)
}
@_transparent
public static func += (lhs: inout Quaternion, rhs: Quaternion) {
lhs = lhs + rhs
}
@_transparent
public static func -= (lhs: inout Quaternion, rhs: Quaternion) {
lhs = lhs - rhs
}
}
@@ -0,0 +1,25 @@
//===--- Quaternion+Codable.swift -----------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import RealModule
// FloatingPoint does not refine Codable, so this is a conditional conformance.
extension Quaternion: Decodable where RealType: Decodable {
public init(from decoder: Decoder) throws {
try self.init(from: SIMD4(from: decoder))
}
}
extension Quaternion: Encodable where RealType: Encodable {
public func encode(to encoder: Encoder) throws {
try components.encode(to: encoder)
}
}
@@ -0,0 +1,221 @@
//===--- Quaternion+ElementaryFunctions.swift -----------------*- swift -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
// (r + xi + yj + zk) is a common representation that is often seen for
// quaternions. However, when we want to expand the elementary functions of
// quaternions in terms of real operations it is almost always easier to view
// them as real part (r) and imaginary vector part (v),
// i.e: r + xi + yj + zk = r + v; and so we diverge a little from the
// representation that is used in the documentation in other files and use this
// notation of quaternions in the comments of the following functions.
//
// Quaternionic elementary functions have many similarities with elementary
// functions of complex numbers and their definition in terms of real
// operations. Therefore, if you make a modification to one of the following
// functions, you should almost surely make a parallel modification to the same
// elementary function of complex numbers.
import RealModule
extension Quaternion/*: ElementaryFunctions */ {
// MARK: - exp-like functions
@inlinable
public static func exp(_ q: Quaternion) -> Quaternion {
// Mathematically, this operation can be expanded in terms of the `Real`
// operations `exp`, `cos` and `sin` as follows (`let θ = ||v||`):
//
// ```
// exp(r + v) = exp(r) exp(v)
// = exp(r) (cos(θ) + (v/θ) sin(θ))
// ```
//
// 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(||v||)` would not be.
guard q.isFinite else { return q }
let (â, θ) = q.imaginary.unitAxisAndLength
let rotation = Quaternion(halfAngle: θ, unitAxis: â)
// If real < log(greatestFiniteMagnitude), then exp(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)
return rotation.multiplied(by: halfScale).multiplied(by: halfScale)
}
return rotation.multiplied(by: .exp(q.real))
}
@inlinable
public static func expMinusOne(_ q: Quaternion) -> Quaternion {
// Mathematically, this operation can be expanded in terms of the `Real`
// operations `exp`, `cos` and `sin` as follows (`let θ = ||v||`):
//
// ```
// exp(r + v) - 1 = exp(r) exp(v) - 1
// = exp(r) (cos(θ) + (v/θ) sin(θ)) - 1
// = exp(r) cos(θ) + exp(r) (v/θ) sin(θ) - 1
// = (exp(r) cos(θ) - 1) + exp(r) (v/θ) sin(θ)
// -------- u --------
// ```
//
// Note that the imaginary part is just the usual exp(x) sin(y);
// the only trick is computing the real part ("u"):
//
// ```
// u = exp(r) cos(θ) - 1
// = exp(r) cos(θ) - cos(θ) + cos(θ) - 1
// = (exp(r) - 1) cos(θ) + (cos(θ) - 1)
// = expMinusOne(r) cos(θ) + cosMinusOne(θ)
// ```
//
// See `expMinusOne` on complex numbers for error bounds.
guard q.isFinite else { return q }
let (â, θ) = q.imaginary.unitAxisAndLength
// If exp(q) is close to the overflow boundary, we don't need to
// worry about the "MinusOne" part of this function; we're just
// computing exp(q). (Even when θ is near a multiple of π/2,
// it can't be close enough to overcome the scaling from exp(r),
// so the -1 term is _always_ negligable).
guard q.real < RealType.log(.greatestFiniteMagnitude) - 1 else {
let halfScale = RealType.exp(q.real/2)
let rotation = Quaternion(halfAngle: θ, unitAxis: â)
return rotation.multiplied(by: halfScale).multiplied(by: halfScale)
}
return Quaternion(
real: RealType._mulAdd(.cos(θ), .expMinusOne(q.real), .cosMinusOne(θ)),
imaginary: â * .exp(q.real) * .sin(θ)
)
}
@inlinable
public static func cosh(_ q: Quaternion) -> Quaternion {
// Mathematically, this operation can be expanded in terms of
// trigonometric `Real` operations as follows (`let θ = ||v||`):
//
// ```
// cosh(q) = (exp(q) + exp(-q)) / 2
// = cosh(r) cos(θ) + (v/θ) sinh(r) sin(θ)
// ```
//
// Like exp, cosh is entire, so we do not need to worry about where
// branch cuts fall. Also like exp, cancellation never occurs in the
// evaluation of the naive expression, so all we need to be careful
// about is the behavior near the overflow boundary.
//
// Fortunately, if |r| >= -log(ulpOfOne), cosh(r) and sinh(r) are
// both just exp(|r|)/2, and we already know how to compute that.
//
// This function and sinh should stay in sync; if you make a
// modification here, you should almost surely make a parallel
// modification to sinh below.
guard q.isFinite else { return q }
let (â, θ) = q.imaginary.unitAxisAndLength
guard q.real.magnitude < -RealType.log(.ulpOfOne) else {
let rotation = Quaternion(halfAngle: θ, unitAxis: â)
let firstScale = RealType.exp(q.real.magnitude/2)
return rotation.multiplied(by: firstScale).multiplied(by: firstScale/2)
}
return Quaternion(
real: .cosh(q.real) * .cos(θ),
imaginary: â * .sinh(q.real) * .sin(θ)
)
}
@inlinable
public static func sinh(_ q: Quaternion) -> Quaternion {
// Mathematically, this operation can be expanded in terms of
// trigonometric `Real` operations as follows (`let θ = ||v||`):
//
// ```
// sinh(q) = (exp(q) - exp(-q)) / 2
// = sinh(r) cos(θ) + (v/θ) cosh(r) sin(θ)
// ```
guard q.isFinite else { return q }
let (â, θ) = q.imaginary.unitAxisAndLength
guard q.real.magnitude < -RealType.log(.ulpOfOne) else {
let rotation = Quaternion(halfAngle: θ, unitAxis: â)
let firstScale = RealType.exp(q.real.magnitude/2)
let secondScale = RealType(signOf: q.real, magnitudeOf: firstScale/2)
return rotation.multiplied(by: firstScale).multiplied(by: secondScale)
}
return Quaternion(
real: .sinh(q.real) * .cos(θ),
imaginary: â * .cosh(q.real) * .sin(θ)
)
}
@inlinable
public static func tanh(_ q: Quaternion) -> Quaternion {
// Mathematically, this operation can be expanded in terms of
// trigonometric `Real` operations as follows (`let θ = ||v||`):
//
// ```
// tanh(q) = sinh(q) / cosh(q)
// ```
guard q.isFinite else { return q }
// Note that when |r| is larger than -log(.ulpOfOne),
// sinh(r + v) == ±cosh(r + v), so tanh(r + v) is just ±1.
guard q.real.magnitude < -RealType.log(.ulpOfOne) else {
return Quaternion(
real: RealType(signOf: q.real, magnitudeOf: 1),
imaginary:
RealType(signOf: q.components.x, magnitudeOf: 0),
RealType(signOf: q.components.y, magnitudeOf: 0),
RealType(signOf: q.components.z, magnitudeOf: 0)
)
}
return sinh(q) / cosh(q)
}
@inlinable
public static func cos(_ q: Quaternion) -> Quaternion {
// cos(q) = cosh(q * (v/θ)))
let (â,_) = q.imaginary.unitAxisAndLength
let p = Quaternion(imaginary: â)
return cosh(q * p)
}
@inlinable
public static func sin(_ q: Quaternion) -> Quaternion {
// sin(q) = -(v/θ) * sinh(q * (v/θ)))
let (â,_) = q.imaginary.unitAxisAndLength
let p = Quaternion(imaginary: â)
return -p * sinh(q * p)
}
@inlinable
public static func tan(_ q: Quaternion) -> Quaternion {
// tan(q) = -(v/θ) * tanh(q * (v/θ)))
let (â,_) = q.imaginary.unitAxisAndLength
let p = Quaternion(imaginary: â)
return -p * tanh(q * p)
}
}
extension SIMD3 where Scalar: FloatingPoint {
/// Returns the normalized axis and the length of this vector.
@usableFromInline @inline(__always)
internal var unitAxisAndLength: (Self, Scalar) {
if self == .zero {
return (SIMD3(
Scalar(signOf: x, magnitudeOf: 0),
Scalar(signOf: y, magnitudeOf: 0),
Scalar(signOf: z, magnitudeOf: 0)
), .zero)
}
return (self/length, length)
}
}
@@ -0,0 +1,72 @@
//===--- Quaternion+Hashable.swift ----------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: Hashable {
/// Returns a Boolean value indicating whether two values are equal.
///
/// - Important:
/// Quaternions are frequently used to represent 3D transformations. It's
/// important to be aware that, when used this way, any quaternion and its
/// negation represent the same transformation, but they do not compare
/// equal using `==` because they are not the same quaternion. You can
/// compare quaternions as 3D transformations using `equals(as3DTransform:)`.
@_transparent
public static func == (lhs: Quaternion, rhs: Quaternion) -> Bool {
// Identify all numbers with either component non-finite as a single "point at infinity".
guard lhs.isFinite || rhs.isFinite else { return true }
// For finite numbers, equality is defined componentwise. Cases where
// only one of lhs or rhs is infinite fall through to here as well, but this
// expression correctly returns false for them so we don't need to handle
// them explicitly.
return lhs.components == rhs.components
}
/// Returns a Boolean value indicating whether the 3D transformation of the
/// two quaternions are equal.
///
/// Use this method to test for equality of the 3D transformation properties
/// of quaternions; where for any quaternion `q`, its negation represent the
/// same 3D transformation; i.e. `q.equals(as3DTransform: q)` as well as
/// `q.equals(as3DTransform: -q)` are both `true`.
///
/// - Parameter other: The value to compare.
/// - Returns: True if the 3D transformation of this quaternion equals `other`.
@_transparent
public func equals(as3DTransform other: Quaternion) -> Bool {
// Identify all numbers with either component non-finite as a single "point at infinity".
guard isFinite || other.isFinite else { return true }
// For finite numbers, equality is defined componentwise. Cases where only
// one of lhs or rhs is infinite fall through to here as well, but this
// expression correctly returns false for them so we don't need to handle
// them explicitly.
return components == other.components || components == -other.components
}
@_transparent
public func hash(into hasher: inout Hasher) {
// There are two equivalence classes to which we owe special attention:
// All zeros should hash to the same value, regardless of sign, and all
// non-finite numbers should hash to the same value, regardless of
// representation. The correct behavior for zero falls out for free from
// the hash behavior of floating-point, but we need to use a
// representative member for any non-finite values.
// For any normal values we use the "canonical transform" representation,
// where real is always non-negative. This allows people who are using
// quaternions as rotations to get the expected semantics out of collections
// (while unfortunately producing some collisions for people who are not,
// but not in too catastrophic of a fashion).
if isFinite {
canonicalizedTransform.components.hash(into: &hasher)
} else {
hasher.combine(RealType.infinity)
}
}
}
@@ -0,0 +1,19 @@
//===--- Quaternion+IntegerLiteral.swift ----------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: ExpressibleByIntegerLiteral {
public typealias IntegerLiteralType = RealType.IntegerLiteralType
@inlinable
public init(integerLiteral value: IntegerLiteralType) {
self.init(RealType(integerLiteral: value))
}
}
@@ -0,0 +1,66 @@
//===--- Quaternion+Numeric.swift -----------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: Numeric {
@_transparent
public static func * (lhs: Quaternion, rhs: Quaternion) -> Quaternion {
let rhsX = SIMD4(+rhs.components.w, +rhs.components.z, -rhs.components.y, +rhs.components.x)
let rhsY = SIMD4(-rhs.components.z, +rhs.components.w, +rhs.components.x, +rhs.components.y)
let rhsZ = SIMD4(+rhs.components.y, -rhs.components.x, +rhs.components.w, +rhs.components.z)
let rhsR = SIMD4(-rhs.components.x, -rhs.components.y, -rhs.components.z, +rhs.components.w)
let x = (lhs.components * rhsX).sum()
let y = (lhs.components * rhsY).sum()
let z = (lhs.components * rhsZ).sum()
let r = (lhs.components * rhsR).sum()
return Quaternion(from: SIMD4(x,y,z,r))
}
@_transparent
public static func *= (lhs: inout Quaternion, rhs: Quaternion) {
lhs = lhs * rhs
}
/// The quaternion with specified real part and zero imaginary part.
///
/// Equivalent to `Quaternion(RealType(real))`.
@inlinable
public init<Other: BinaryInteger>(_ real: Other) {
self.init(RealType(real))
}
/// The quaternion with specified real part and zero imaginary part,
/// if it can be constructed without rounding.
@inlinable
public init?<Other: BinaryInteger>(exactly real: Other) {
guard let real = RealType(exactly: real) else { return nil }
self.init(real)
}
/// The ∞-norm of the value (`max(abs(r), abs(x), abs(y), abs(z))`).
///
/// If you need the Euclidean norm (a.k.a. 2-norm) use the `length` or `lengthSquared`
/// properties instead.
///
/// Edge cases:
/// - If `q` is not finite, `q.magnitude` is `.infinity`.
/// - If `q` is zero, `q.magnitude` is `0`.
/// - Otherwise, `q.magnitude` is finite and non-zero.
///
/// See also `.length` and `.lengthSquared`
@_transparent
public var magnitude: RealType {
guard isFinite else { return .infinity }
return max(abs(components.max()), abs(components.min()))
}
}
@@ -0,0 +1,118 @@
//===--- Quaternion+SignedNumeric.swift -----------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: SignedNumeric {
/// The multiplicative identity, with real part one and *all* imaginary parts
/// zero, i.e.: `1 + 0i + 0j + 0k`
///
/// See also: `zero`, `i`, `j`, `k`, `infinity`
@_transparent
public static var one: Quaternion {
Quaternion(from: SIMD4(0,0,0,1))
}
/// The [conjugate][conj] of this value.
///
/// [conj]: https://en.wikipedia.org/wiki/Quaternion#Conjugation,_the_norm,_and_reciprocal
@_transparent
public var conjugate: Quaternion {
Quaternion(from: components * [-1, -1, -1, 1])
}
@_transparent
public static func / (lhs: Quaternion, rhs: Quaternion) -> Quaternion {
// Try the naive expression lhs/rhs = lhs*conj(rhs) / |rhs|^2; if we can compute
// this without over/underflow, everything is fine and the result is
// correct. If not, we have to rescale and do the computation carefully.
let lengthSquared = rhs.lengthSquared
guard lengthSquared.isNormal else { return rescaledDivide(lhs, rhs) }
return lhs * (rhs.conjugate.divided(by: lengthSquared))
}
@_transparent
public static func /= (lhs: inout Quaternion, rhs: Quaternion) {
lhs = lhs / rhs
}
@usableFromInline @_alwaysEmitIntoClient @inline(never)
internal static func rescaledDivide(_ lhs: Quaternion, _ rhs: Quaternion) -> Quaternion {
if rhs.isZero { return .infinity }
if lhs.isZero || !rhs.isFinite { return .zero }
// TODO: detect when RealType is Float and just promote to Double, then
// use the naive algorithm.
let lhsScale = lhs.magnitude
let rhsScale = rhs.magnitude
let lhsNorm = lhs.divided(by: lhsScale)
let rhsNorm = rhs.divided(by: rhsScale)
let r = (lhsNorm * rhsNorm.conjugate).divided(by: rhsNorm.lengthSquared)
// At this point, the result is (r * lhsScale)/rhsScale computed without
// undue overflow or underflow. We know that r is close to unity, so
// the question is simply what order in which to do this computation
// to avoid spurious overflow or underflow. There are three options
// to choose from:
//
// - r * (lhsScale / rhsScale)
// - (r * lhsScale) / rhsScale
// - (r / rhsScale) * lhsScale
//
// The simplest case is when lhsScale / rhsScale is normal:
if (lhsScale / rhsScale).isNormal {
return r.multiplied(by: lhsScale / rhsScale)
}
// Otherwise, we need to compute either rNorm * lhsScale or rNorm / rhsScale
// first. Choose the first if the first scaling behaves well, otherwise
// choose the other one.
if (r.magnitude * lhsScale).isNormal {
return r.multiplied(by: lhsScale).divided(by: rhsScale)
}
return r.divided(by: rhsScale).multiplied(by: lhsScale)
}
/// A normalized quaternion with the same direction and phase as this value.
///
/// If such a value cannot be produced, `nil` is returned.
@inlinable
public var normalized: Quaternion? {
if length.isNormal {
return divided(by: length)
}
if isZero || !isFinite {
return nil
}
return divided(by: magnitude).normalized
}
/// The reciprocal of this value, if it can be computed without undue overflow or underflow.
///
/// If z.reciprocal is non-nil, you can safely replace division by z with multiplication by this
/// value. It is not advantageous to do this for an isolated division, but if you are dividing
/// many values by a single denominator, this will often be a significant performance win.
///
/// Typical use looks like this:
/// ```
/// func divide<T: Real>(data: [Quaternion<T>], by divisor: Quaternion<T>) -> [Quaternion<T>] {
/// // If divisor is well-scaled, use multiply by reciprocal.
/// if let recip = divisor.reciprocal {
/// return data.map { $0 * recip }
/// }
/// // Fallback on using division.
/// return data.map { $0 / divisor }
/// }
/// ```
@inlinable
public var reciprocal: Quaternion? {
let recip = Quaternion(1)/self
if recip.isNormal || isZero || !isFinite {
return recip
}
return nil
}
}
@@ -0,0 +1,28 @@
//===--- Quaternion+StringConvertible.swift -------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension Quaternion: CustomStringConvertible {
public var description: String {
guard isFinite else { return "inf" }
return "(\(components.w), \(components.x), \(components.y), \(components.z))"
}
}
extension Quaternion: CustomDebugStringConvertible {
public var debugDescription: String {
let x = String(reflecting: components.x)
let y = String(reflecting: components.y)
let z = String(reflecting: components.z)
let r = String(reflecting: components.w)
return "Quaternion<\(RealType.self)>(\(r), \(x), \(y), \(z))"
}
}
+302
View File
@@ -0,0 +1,302 @@
//===--- Quaternion.swift -------------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import RealModule
/// A quaternion represented by a real (or scalar) part and three imaginary (or vector) parts.
///
/// TODO: introductory text on quaternions
///
/// Implementation notes:
/// -
/// This type does not provide heterogeneous real/quaternion arithmetic,
/// not even the natural vector-space operations like real * quaternion.
/// There are two reasons for this choice: first, Swift broadly avoids
/// mixed-type arithmetic when the operation can be adequately expressed
/// by a conversion and homogeneous arithmetic. Second, with the current
/// typechecker rules, it would lead to undesirable ambiguity in common
/// expressions (see README.md for more details).
///
/// `.magnitude` does not return the Euclidean norm; it uses the "infinity
/// norm" (`max(|r|,|x|,|y|,|z|)`) instead. There are two reasons for this
/// choice: first, it's simply faster to compute on most hardware. Second,
/// there exist values for which the Euclidean norm cannot be represented.
/// Using the infinity norm avoids this problem entirely without significant
/// downsides. You can access the Euclidean norm using the `length` property.
/// See `Complex` type of the swift-numerics package for additional details.
///
/// Quaternions are frequently used to represent 3D transformations. It's
/// important to be aware that, when used this way, any quaternion and its
/// negation represent the same transformation, but they do not compare equal
/// using `==` because they are not the same quaternion.
/// You can compare quaternions as 3D transformations using `equals(as3DTransform:)`.
public struct Quaternion<RealType> where RealType: Real & SIMDScalar {
/// The components of the 4-dimensional vector space of the quaternion.
///
/// Components are stored within a 4-dimensional SIMD vector with the
/// scalar part last, i.e. in the form of:
///
/// xi + yj + zk + r // SIMD(x,y,z,r)
@usableFromInline @inline(__always)
internal var components: SIMD4<RealType>
/// A quaternion constructed from given 4-dimensional SIMD vector.
///
/// Creates a new quaternion by reading the values of the SIMD vector
/// as components of a quaternion with the scalar part last, i.e. in the form of:
///
/// xi + yj + zk + r // SIMD(x,y,z,r)
@usableFromInline @inline(__always)
internal init(from components: SIMD4<RealType>) {
self.components = components
}
}
// MARK: - Basic Property
extension Quaternion {
/// The real part of this quaternion.
///
/// If `q` is not finite, `q.real` is `.nan`.
public var real: RealType {
@_transparent
get { isFinite ? components[3] : .nan }
@_transparent
set { components[3] = newValue }
}
/// The imaginary part of this quaternion.
///
/// If `q` is not finite, `q.imaginary` is `.nan` in all lanes.
public var imaginary: SIMD3<RealType> {
@_transparent
get { isFinite ? components[SIMD3(0,1,2)] : SIMD3(repeating: .nan) }
@_transparent
set {
components = SIMD4(newValue, components[3])
}
}
/// The quaternion with the imaginary unit **i** one, i.e. `0 + i + 0j + 0k`.
///
/// See also `.zero`, `.one`, `.j`, `.k` and `.infinity`.
@_transparent
public static var i: Quaternion {
Quaternion(imaginary: SIMD3(1,0,0))
}
/// The quaternion with the imaginary unit **j** one, i.e. `0 + 0i + j + 0k`.
///
/// See also `.zero`, `.one`, `.i`, `.k` and `.infinity`.
@_transparent
public static var j: Quaternion {
Quaternion(imaginary: SIMD3(0,1,0))
}
/// The quaternion with the imaginary unit **k** one, i.e. `0 + 0i + 0j + k`.
///
/// See also `.zero`, `.one`, `.i`, `.j` and `.infinity`.
@_transparent
public static var k: Quaternion {
Quaternion(imaginary: SIMD3(0,0,1))
}
/// The point at infinity.
///
/// See also `.zero`, `.one`, `.i`, `.j` and `.k`.
@_transparent
public static var infinity: Quaternion {
Quaternion(.infinity)
}
/// True if this value is finite.
///
/// A quaternion is finite if neither component is an infinity or nan.
///
/// See also `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
@_transparent
public var isFinite: Bool {
return components.x.isFinite
&& components.y.isFinite
&& components.z.isFinite
&& components.w.isFinite
}
/// True if this value is normal.
///
/// A quaternion is normal if it is finite and *any* of its real or imaginary components
/// are normal. A floating-point number representing one of the components is normal
/// if its exponent allows a full-precision representation.
///
/// See also `.isFinite`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
@_transparent
public var isNormal: Bool {
return isFinite && (
components.x.isNormal ||
components.y.isNormal ||
components.z.isNormal ||
components.w.isNormal
)
}
/// True if this value is subnormal.
///
/// A quaternion is subnormal if it is finite, not normal, and not zero. When the result of a
/// computation is subnormal, underflow has occurred and the result generally does not have full
/// precision.
///
/// See also `.isFinite`, `.isNormal`, `.isZero`, `.isReal`, `.isPure`.
@_transparent
public var isSubnormal: Bool {
isFinite && !isNormal && !isZero
}
/// True if this value is zero.
///
/// A quaternion is zero if the real and *all* imaginary components are zero.
///
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isReal`, `.isPure`.
@_transparent
public var isZero: Bool {
components == .zero
}
/// True if this quaternion is real.
///
/// A quaternion is real if *all* imaginary components are zero.
///
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isPure`.
@_transparent
public var isReal: Bool {
imaginary == .zero
}
/// True if this quaternion is pure.
///
/// A quaternion is pure if the real component is zero.
///
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`.
@_transparent
public var isPure: Bool {
real.isZero
}
/// A "canonical" representation of the value.
///
/// For normal quaternion instances with a RealType conforming to
/// BinaryFloatingPoint (the common case), the result is simply this value
/// unmodified. For zeros, the result has the representation (+0, +0, +0, +0).
/// For infinite values, the result has the representation (+inf, +0, +0, +0).
///
/// If the RealType admits non-canonical representations, the x, y, z and r
/// components are canonicalized in the result.
///
/// This is mainly useful for interoperation with other languages, where
/// you may want to reduce each equivalence class to a single representative
/// before passing across language boundaries, but it may also be useful
/// for some serialization tasks. It's also a useful implementation detail for
/// some primitive operations.
///
/// See also `.canonicalizedTransform`.
@_transparent
public var canonicalized: Self {
guard !isZero else { return .zero }
guard isFinite else { return .infinity }
return self.multiplied(by: 1)
}
/// A "canonical transformation" representation of the value.
///
/// For normal quaternion instances with a RealType conforming to
/// BinaryFloatingPoint (the common case) and a non-negative real component,
/// the result is simply this value unmodified. For instances with a negative
/// real component, the result is this quaternion negated -(r, x, y, z); so
/// the real component is always positive.
/// For zeros, the result has the representation (+0, +0, +0, +0). For
/// infinite values, the result has the representation (+inf, +0, +0, +0).
///
/// If the RealType admits non-canonical representations, the x, y, z and r
/// components are canonicalized in the result.
///
/// See also `.canonicalized`.
@_transparent
public var canonicalizedTransform: Self {
let canonical = canonicalized
if canonical.real.sign == .plus { return canonical }
return -canonical
}
}
// MARK: - Additional Initializers
extension Quaternion {
/// The quaternion with specified real part and zero imaginary part.
///
/// Equivalent to `Quaternion(real: real, imaginary: SIMD3(repeating: 0))`.
@inlinable
public init(_ real: RealType) {
self.init(real: real, imaginary: SIMD3(repeating: 0))
}
/// The quaternion with specified imaginary part and zero real part.
///
/// Equivalent to `Quaternion(real: 0, imaginary: imaginary)`.
@inlinable
public init(imaginary: SIMD3<RealType>) {
self.init(real: 0, imaginary: imaginary)
}
/// The quaternion with specified imaginary part and zero real part.
///
/// Equivalent to `Quaternion(real: 0, imaginary: imaginary)`.
@inlinable
public init(imaginary x: RealType, _ y: RealType, _ z: RealType) {
self.init(imaginary: SIMD3(x, y, z))
}
/// The quaternion with specified real part and imaginary parts.
@inlinable
public init(real: RealType, imaginary: SIMD3<RealType>) {
self.init(from: SIMD4(imaginary, real))
}
/// The quaternion with specified real part and imaginary parts.
@inlinable
public init(real: RealType, imaginary x: RealType, _ y: RealType, _ z: RealType) {
self.init(real: real, imaginary: SIMD3(x, y, z))
}
}
extension Quaternion where RealType: BinaryFloatingPoint {
/// `other` rounded to the nearest representable value of this type.
@inlinable
public init<Other: BinaryFloatingPoint>(_ other: Quaternion<Other>) {
self.init(from: SIMD4(
RealType(other.components.x),
RealType(other.components.y),
RealType(other.components.z),
RealType(other.components.w)
))
}
/// `other`, if it can be represented exactly in this type; otherwise `nil`.
@inlinable
public init?<Other: BinaryFloatingPoint>(exactly other: Quaternion<Other>) {
guard
let x = RealType(exactly: other.components.x),
let y = RealType(exactly: other.components.y),
let z = RealType(exactly: other.components.z),
let r = RealType(exactly: other.components.w)
else { return nil }
self.init(from: SIMD4(x, y, z, r))
}
}
+30
View File
@@ -0,0 +1,30 @@
# Quaternion
This module provides a `Quaternion` type generic over an underlying `RealType`:
```swift
1> import QuaternionModule
2> let q = Quaternion(real: 1, imaginary: 1, 1, 1) // q = 1 + i + j + k
```
The usual arithmetic operators are provided for Quaternions, many useful properties, plus conformances to the
obvious usual protocols: `Equatable`, `Hashable`, `Codable` (if the underlying `RealType` is), and `AlgebraicField`
(hence also `AdditiveArithmetic` and `SignedNumeric`).
### Dependencies:
- `RealModule`.
### The magnitude property
The `Numeric` protocol requires a `.magnitude` property, but (deliberately) does not fully specify the semantics.
The most obvious choice for `Quaternion` would be to use the Euclidean norm (aka the "2-norm", given by `sqrt(real*real + i*i + k*k + j*j)`).
However, in practice there are good reasons to use something else instead:
- The 2-norm requires special care to avoid spurious overflow/underflow, but the naive expressions for the 1-norm ("taxicab norm") or ∞-norm ("sup norm") are always correct.
- Even when care is used, near the overflow boundary the 2-norm and the 1-norm are not representable.
As an example, consider `q = Quaternion(big, (big, big, big))`, where `big` is `Double.greatestFiniteMagnitude`. The 1-norm and 2-norm of `q` both overflow (the 1-norm would be `4*big`, and the 2-norm would be `sqrt(4)*big`, neither of which are representable as `Double`), but the ∞-norm is always equal to either `real`, `i`, `j` or `k`, so it is guaranteed to be representable.
Because of this, the ∞-norm is the obvious alternative; it gives the nicest API surface.
- If we consider the magnitude of more exotic types, like operators, the 1-norm and ∞-norm are significantly easier to compute than the 2-norm (O(n) vs. "no closed form expression, but O(n^3) iterative methods"), so it is nice to establish a precedent of `.magnitude` binding one of these cheaper-to-compute norms.
- The ∞-norm is heavily used in other computational libraries; for example, it is used by the `izamax` and `icamax` functions in BLAS.
The 2-norm still needs to be available, of course, because sometimes you need it.
This functionality is accessed via the `.length` and `.lengthSquared` properties.
+39
View File
@@ -0,0 +1,39 @@
//===--- Scale.swift ------------------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019-2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
// Policy: deliberately not using the * and / operators for these at the
// moment, because then there's an ambiguity in expressions like 2*p; is
// that Quaternion(2) * p or is it RealType(2) * p? This is especially
// problematic in type inference: suppose we have:
//
// let a: RealType = 1
// let b = 2*a
//
// what is the type of b? If we don't have a type context, it's ambiguous.
// If we have a Quaternion type context, then b will be inferred to have type
// Quaternion! Obviously, that doesn't help anyone.
//
// TODO: figure out if there's some way to avoid these surprising results
// and turn these into operators if/when we have it.
// (https://github.com/apple/swift-numerics/issues/12)
extension Quaternion {
/// `self` scaled by `scalar`.
@usableFromInline @_transparent
internal func multiplied(by scalar: RealType) -> Quaternion {
Quaternion(from: components * scalar)
}
/// `self` unscaled by `scalar`.
@usableFromInline @_transparent
internal func divided(by scalar: RealType) -> Quaternion {
Quaternion(from: components / scalar)
}
}
@@ -0,0 +1,25 @@
# Transformation
In computer science, quaternions are frequently used to represent three-dimensional rotations; as quaternions have some dvantages over other representations][advantages].
`Transformation.swift` encapsulates an API to interact with the three-dimensional transformation properties of quaternions. It provides conversions to and from other rotation representations, namely [*Angle-Axis*][angle_axis_wiki], [*Rotation Vector*][rotation_vector_wiki] and [*Polar decomposition*][polar_wiki], as well as it provides methods to directly transform arbitrary vectors by quaternions.
## Policies
- zero and non-finite quaternions have indeterminate transformation properties and can not be converted to other representations. Thus,
- The `angle` of `.zero` or `.infinity` is `RealType.nan`.
- The `axis` of `.zero` or `.infinity` is `RealType.nan` in all lanes.
- The `rotationVector` of `.zero` or `.infinity` is `RealType.nan` in all lanes.
- The polar `phase` of `.zero` or `.infinity` is `RealType.nan`
- Quaternions with an `angle` of `.zero` have an indeterminate rotation axis. Thus,
- the `axis` of `angle == .zero` is `RealType.nan` in all lanes.
- the `rotationVector` of `angle == .zero` is `RealType.nan` in all lanes.
[advantages]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Advantages_of_quaternions
[angle_axis_wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Recovering_the_axis-angle_representation
[polar_wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
[rotation_vector_wiki]: https://en.wikipedia.org/wiki/Axis–angle_representation#Rotation_vector
@@ -0,0 +1,271 @@
//===--- Transformation.swift ---------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020 - 2022 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import RealModule
extension Quaternion {
/// The [rotation angle][wiki] of the Angle-Axis representation.
///
/// Returns the rotation angle about the rotation *axis* in radians
/// within *[0, 2π]* range.
///
/// Edge cases:
/// - If the quaternion is zero or non-finite, angle is `nan`.
///
/// See also `.axis`, `.angleAxis`, `.rotationVector`,
/// `init(length:angle:axis:)` and `init(rotation:)`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Recovering_the_axis-angle_representation
@inlinable
public var angle: RealType {
2 * halfAngle
}
/// The [rotation axis][wiki] of the Angle-Axis representation.
///
/// Returns the *(x,y,z)* rotation axis encoded in the quaternion
/// as SIMD3 vector of unit length.
///
/// Edge cases:
/// - If the quaternion is zero or non-finite, axis is `nan` in all lanes.
/// - If the rotation angle is zero, axis is `nan` in all lanes.
///
/// See also `.angle`, `.angleAxis`, `.rotationVector`,
/// `init(length:angle:axis:)` and `init(rotation:)`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Recovering_the_axis-angle_representation
@inlinable
public var axis: SIMD3<RealType> {
guard isFinite, imaginary != .zero else { return SIMD3(repeating: .nan) }
// If lengthSquared computes without over/underflow, everything is fine
// and the result is correct. If not, we have to do the computation
// carefully and unscale the quaternion first.
let lenSq = imaginary.lengthSquared
guard lenSq.isNormal else { return divided(by: magnitude).axis }
return imaginary / .sqrt(lenSq)
}
/// The [Angle-Axis][wiki] representation.
///
/// Returns the length of the quaternion, the rotation angle in radians
/// within *[0, 2π]* and the rotation axis as SIMD3 vector of unit length.
///
/// Edge cases:
/// - If the quaternion is zero or non-finite, angle and axis are `nan`.
/// - If the angle is zero, axis is `nan` in all lanes.
///
/// See also `.angle`, `.axis`, `.rotationVector`, `init(length:angle:axis:)`
/// and `init(rotation:)`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Recovering_the_axis-angle_representation
public var angleAxis: (length: RealType, angle: RealType, axis: SIMD3<RealType>) {
(length, angle, axis)
}
/// The [rotation vector][rotvector].
///
/// A rotation vector is a vector of same direction as the rotation axis,
/// whose length is the rotation angle of an Angle-Axis representation. It
/// is effectively the product of multiplying the rotation `axis` by the
/// rotation `angle`. Rotation vectors are often called "scaled axis" — this
/// is a different name for the same concept.
///
/// Edge cases:
/// - If the quaternion is zero or non-finite, the rotation vector is `nan`
/// in all lanes.
/// - If the rotation angle is zero, the rotation vector is `nan`
/// in all lanes.
///
/// See also `.angle`, `.axis`, `.angleAxis`, `init(length:angle:axis:)`
/// and `init(rotation:)`.
///
/// [rotvector]: https://en.wikipedia.org/wiki/Axis–angle_representation#Rotation_vector
@_transparent
public var rotationVector: SIMD3<RealType> {
axis * angle
}
/// Creates a unit quaternion specified with [Angle-Axis][wiki] values.
///
/// Angle-Axis is a representation of a three-dimensional rotation using two
/// different quantities: an angle describing the magnitude of rotation, and
/// a vector of unit length indicating the axis direction to rotate along.
/// The optional length parameter scales the quaternion after the conversion.
///
/// This initializer reads given `length`, `angle` and `axis` values and
/// creates a quaternion of equal rotation properties and of specified length
/// using the following equation:
///
/// Q = (cos(angle/2), axis * sin(angle/2)) * length
///
/// If `length` is not specified, it defaults to *1*; and the final
/// quaternion is of unit length.
///
/// - Note: `axis` must be of unit length, or an assertion failure occurs.
///
/// Edge cases:
/// - Negative lengths are interpreted as reflecting the point through the origin, i.e.:
/// ```
/// Quaternion(length: -r, angle: θ, axis: axis) == -Quaternion(length: r, angle: θ, axis: axis)
/// ```
/// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
/// ```
/// Quaternion(length: .zero, angle: θ, axis: axis) == .zero
/// ```
/// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
/// ```
/// Quaternion(length: .infinity, angle: θ, axis: axis) == .infinity
/// ```
/// - Otherwise, `θ` must be finite, or a precondition failure occurs.
///
/// See also `.angle`, `.axis`, `.angleAxis`, `.rotationVector`
/// and `init(rotation:)`.
///
/// - Parameter length: The length of the quaternion. Defaults to `1`.
/// - Parameter angle: The rotation angle about the rotation axis in radians.
/// - Parameter axis: The rotation axis. Must be of unit length.
///
/// [wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Recovering_the_axis-angle_representation
@inlinable
public init(length: RealType = 1, angle: RealType, axis: SIMD3<RealType>) {
guard !length.isZero, length.isFinite else {
self = Quaternion(length)
return
}
// Length is finite and non-zero, therefore
// 1. `angle` must be finite or a precondition failure needs to occur; as
// this is not representable.
// 2. `axis` must be of unit length or an assertion failure occurs; while
// "wrong" by definition, it is representable.
precondition(
angle.isFinite,
"Either angle must be finite, or length must be zero or infinite."
)
assert(
// TODO: Replace with `approximateEquality()`
abs(.sqrt(axis.lengthSquared)-1) < max(.sqrt(axis.lengthSquared), 1)*RealType.ulpOfOne.squareRoot(),
"Given axis must be of unit length."
)
self = Quaternion(halfAngle: angle/2, unitAxis: axis).multiplied(by: length)
}
/// Creates a unit quaternion specified with given [rotation vector][wiki].
///
/// A rotation vector is a vector of same direction as the rotation axis,
/// whose length is the rotation angle of an Angle-Axis representation. It
/// is effectively the product of multiplying the rotation `axis` by the
/// rotation `angle`.
///
/// This initializer reads the angle and axis values of given rotation vector
/// and creates a quaternion of equal rotation properties using the following
/// equation:
///
/// Q = (cos(angle/2), axis * sin(angle/2))
///
/// Rotation vectors are sometimes referred to as *scaled axis* — this is a
/// different name for the same concept.
///
/// The final quaternion is of unit length.
///
/// Edge cases:
/// - If `vector` is `.zero`, the quaternion is `.zero`:
/// ```
/// Quaternion(rotation: .zero) == .zero
/// ```
/// - If `vector` is `.infinity` or `-.infinity`, the quaternion is `.infinity`:
/// ```
/// Quaternion(rotation: -.infinity) == .infinity
/// ```
///
/// See also `.angle`, `.axis`, `.angleAxis`, `.rotationVector`
/// and `init(length:angle:axis:)`.
///
/// - Parameter vector: The rotation vector.
///
/// [wiki]: https://en.wikipedia.org/wiki/Axis–angle_representation#Rotation_vector
@inlinable
public init(rotation vector: SIMD3<RealType>) {
let angle: RealType = .sqrt(vector.lengthSquared)
if !angle.isZero, angle.isFinite {
self = Quaternion(halfAngle: angle/2, unitAxis: vector/angle)
} else {
self = Quaternion(angle)
}
}
/// Transforms a vector by this quaternion.
///
/// Quaternions are frequently used to represent three-dimensional
/// transformations, and thus are used to transform vectors in
/// three-dimensional space. The transformation of an arbitrary vector
/// by a quaternion is known as an action.
///
/// The canonical way of transforming an arbitrary three-dimensional vector
/// `v` by a quaternion `q` is given by the following [formula][wiki]
///
/// p' = qpq⁻¹
///
/// where `p` is a *pure* quaternion (`real == .zero`) with imaginary part
/// equal to vector `v`, and where `p'` is another pure quaternion with
/// imaginary part equal to the transformed vector `v'`. The implementation
/// uses this formular but boils down to a simpler and faster implementation
/// as `p` is known to be pure and `q` is assumed to have unit length – which
/// allows for simplification.
///
/// - Note: This method assumes this quaternion is of unit length.
///
/// Edge cases:
/// - For any quaternion `q`, even `.zero` or `.infinity`, if `vector` is
/// `.infinity` or `-.infinity` in any of the lanes or all, the returning
/// vector is `.infinity` in all lanes:
/// ```
/// SIMD3(-.infinity,0,0) * q == SIMD3(.infinity,.infinity,.infinity)
/// ```
/// - For any quaternion `q`, even `.zero` or `.infinity`, if `vector` is
/// `.zero`, the returning vector is also `.zero`.
/// ```
/// SIMD3(0,0,0) * q == .zero
/// ```
///
/// - Parameter vector: A vector to rotate by this quaternion
/// - Returns: The vector rotated by this quaternion
///
/// [wiki]: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Using_quaternion_as_rotations
@inlinable
public func act(on vector: SIMD3<RealType>) -> SIMD3<RealType> {
guard vector.isFinite else { return .infinity }
guard vector != .zero else { return .zero }
// The following expression have been split up so the type-checker
// can resolve them in a reasonable time.
let p1 = vector * (real*real - imaginary.lengthSquared)
let p2 = imaginary * imaginary.dot(vector)
let p3 = imaginary.cross(vector) * real
let rotatedVector = p1 + (p2 + p3) * 2
// If the rotation computes without over/underflow, everything is fine
// and the result is correct. If not, we have to do the computation
// carefully and first unscale the vector, rotate it again and then
// rescale the vector
if
(rotatedVector.x.isNormal || rotatedVector.x.isZero) &&
(rotatedVector.y.isNormal || rotatedVector.y.isZero) &&
(rotatedVector.z.isNormal || rotatedVector.z.isZero)
{
return rotatedVector
}
let scale = max(abs(vector.max()), abs(vector.min()))
return act(on: vector/scale) * scale
}
}
+8 -7
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -32,15 +32,16 @@
/// Because integer multiplication does not form a group; it's commutative and
/// associative, but integers do not have multiplicative inverses.
/// I.e. if a is any integer other than 1 or -1, there is no integer b such
/// that a*b = 1. The existence of inverses is requried to form a field.
/// that `a*b = 1`. The existence of inverses is requried to form a field.
///
/// If a type `T` conforms to the `Real` protocol, then `T` and `Complex<T>`
/// If a type `T` conforms to the ``Real`` protocol, then `T` and `Complex<T>`
/// both conform to `AlgebraicField`.
///
/// See also `Real`, `SignedNumeric`, `Numeric` and `AdditiveArithmetic`.
/// See also Swift's `SignedNumeric`, `Numeric` and `AdditiveArithmetic`
/// protocols.
///
/// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
public protocol AlgebraicField: SignedNumeric {
public protocol AlgebraicField: SignedNumeric where Magnitude: AlgebraicField {
/// Replaces a with the (approximate) quotient `a/b`.
static func /=(a: inout Self, b: Self)
@@ -90,10 +91,10 @@ public protocol AlgebraicField: SignedNumeric {
/// ```
var reciprocal: Self? { get }
/// a + b, with the optimizer licensed to reassociate and form FMAs.
/// `a + b`, with the optimizer licensed to reassociate and form FMAs.
static func _relaxedAdd(_ a: Self, _ b: Self) -> Self
/// a * b, with the optimizer licensed to reassociate and form FMAs.
/// `a * b`, with the optimizer licensed to reassociate and form FMAs.
static func _relaxedMul(_ a: Self, _ b: Self) -> Self
}
+3 -9
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2020-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -47,7 +47,7 @@ extension Numeric where Magnitude: FloatingPoint {
/// property implements a valid norm.)
///
/// - `isApproximatelyEqual(to:relativeTolerance:norm:)` is _scale invariant_,
/// so long as no underflow or overflow has occured, and no exceptional
/// so long as no underflow or overflow has occurred, and no exceptional
/// value is produced by the scaling.
///
/// See also `isApproximatelyEqual(to:absoluteTolerance:[relativeTolerance:norm:])`.
@@ -218,7 +218,7 @@ extension AdditiveArithmetic {
/// norm: \.length
/// )
/// ```
/// (if we used the default norm, `.magnitude`, we would be testing if
/// (if we used the default norm, `\.magnitude`, we would be testing if
/// `z` were inside a square region instead.)
@inlinable
public func isApproximatelyEqual<Magnitude>(
@@ -227,12 +227,6 @@ extension AdditiveArithmetic {
relativeTolerance: Magnitude = 0,
norm: (Self) -> Magnitude
) -> Bool
// TODO: constraint should really be weaker than FloatingPoint,
// but we need to have `isFinite` for it to work correctly with
// floating-point magnitudes in generic contexts, which is the
// most common case. The fix for this is to lift the isFinite
// requirement to Numeric in the standard library, but that's
// source-breaking, so requires an ABI rumspringa.
where Magnitude: FloatingPoint {
assert(
absoluteTolerance >= 0 && absoluteTolerance.isFinite,
+43 -37
View File
@@ -2,19 +2,13 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020-2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2020-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// A namespace for "augmented arithmetic" operations for types conforming to
/// `Real`.
///
/// Augmented arithmetic refers to a family of algorithms that represent
/// the results of floating-point computations using multiple values such that
/// either the error is minimized or the result is exact.
public enum Augmented { }
extension Augmented {
@@ -45,7 +39,9 @@ extension Augmented {
/// - If both `head` and `tail` are normal, then `a * b` is exactly
/// equal to `head + tail` when computed as real numbers.
@_transparent
public static func product<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
public static func product<T:FloatingPoint>(
_ a: T, _ b: T
) -> (head: T, tail: T) {
let head = a*b
// TODO: consider providing an FMA-less implementation for use when
// targeting platforms without hardware FMA support. This works everywhere,
@@ -56,24 +52,30 @@ extension Augmented {
/// The sum `a + b` represented as an implicit sum `head + tail`.
///
/// `head` is the correctly rounded value of `a + b`. `tail` is the
/// error from that computation rounded to the closest representable
/// value.
///
/// Unlike `Augmented.product(a, b)`, the rounding error of a sum can
/// never underflow.
///
/// This operation is sometimes called ["fastTwoSum"].
///
/// - Parameters:
/// - a: The summand with larger magnitude.
/// - b: The summand with smaller magnitude.
///
/// Preconditions:
/// `head` is the correctly rounded value of `a + b`. `tail` is the
/// error from that computation rounded to the closest representable
/// value.
///
/// - `large.magnitude` must not be smaller than `small.magnitude`.
/// They may be equal, or one or both may be `NaN`.
/// This precondition is only enforced in debug builds.
/// > Note:
/// > `tail` is guaranteed to be the best approximation to the error of
/// the sum only if `large.magnitude` >= `small.magnitude`. If this is
/// not the case, then `head` is the correctly rounded sum, but `tail`
/// is not guaranteed to be the exact error. If you do not know a priori
/// how the magnitudes of `a` and `b` compare, you likely want to use
/// ``sum(_:_:)`` instead.
///
/// Unlike ``product(_:_:)``, the rounding error of `sum` never underflows.
///
/// This operation is sometimes called ["fastTwoSum"].
///
/// > Note:
/// > Classical fastTwoSum does not work when `radix` is 10. This function
/// will fall back on another algorithm for decimal floating-point types
/// to ensure correct results.
///
/// Edge Cases:
///
@@ -88,35 +90,37 @@ extension Augmented {
///
/// ["fastTwoSum"]: https://en.wikipedia.org/wiki/2Sum
@_transparent
public static func sum<T:Real>(large a: T, small b: T) -> (head: T, tail: T) {
assert(!(b.magnitude > a.magnitude))
public static func sum<T: FloatingPoint>(
large a: T, small b: T
) -> (head: T, tail: T) {
// Fall back on 2Sum if radix != 2. Future implementations might use an
// cheaper algorithm specialized for decimal FP, but must deliver a
// correct result if the preconditions are satisfied.
guard T.radix == 2 else { return sum(a, b) }
// Fast2Sum:
let head = a + b
let tail = a - head + b
return (head, tail)
}
/// The sum `a + b` represented as an implicit sum `head + tail`.
///
/// `head` is the correctly rounded value of `a + b`. `tail` is the
/// error from that computation rounded to the closest representable
/// value.
///
/// Unlike `Augmented.sum(large: a, small: b)`, the magnitude of the summands
/// does not matter and `a.magnitude` might as well be strictly less than
/// `b.magnitude`. However, it is recommended to only use this function over
/// `Augmented.sum(large: a, small: b)` in cases where the ordering of the
/// summands magnitude is unknown at compile time. In cases where either of
/// the summands magnitude is guaranteed to be greater than or equal the
/// magnitude of the other summand, use `Augmented.sum(large: a, small: b)`
/// over this function; as it faster to calculate.
/// The magnitude of the summands does not change the result of this
/// operation. If you know statically that `a.magnitude >= b.magnitude`,
/// you may want to consider using ``sum(large:small:)`` to get the same
/// result somewhat more efficiently. If you do not have such a static
/// bound, you usually want to use this function instead.
///
/// Unlike `Augmented.product(a, b)`, the rounding error of a sum can
/// never underflow.
/// Unlike ``product(_:_:)``, the rounding error of `sum` never underflows.
///
/// This operation is sometimes called ["twoSum"].
///
/// - Parameters:
/// - a: One of the summand
/// - a: One of the summands
/// - b: The other summand
///
/// Edge Cases:
@@ -126,13 +130,15 @@ extension Augmented {
/// interpreted as having any meaning (it may be `NaN` or `infinity`).
///
/// Postconditions:
///
///
/// - If `head` is normal, then `abs(tail) < head.ulp`.
/// Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
///
/// ["twoSum"]: https://en.wikipedia.org/wiki/2Sum
@_transparent
public static func sum<T: Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
public static func sum<T: FloatingPoint>(
_ a: T, _ b: T
) -> (head: T, tail: T) {
let head = a + b
let x = head - b
let y = head - x
@@ -0,0 +1,37 @@
# ``Augmented``
A namespace for a family of algorithms that compute the results of floating-
point arithmetic using multiple values such that either the error is minimized
or the result is exact.
## Overview
Consider multiplying two Doubles. A Double has 53 significand bits, so their
product could be up to 106 bits wide before it is rounded to a Double result.
So up to 53 of those 106 bits will be "lost" in that process:
```swift
let a = 1.0 + .ulpOfOne // 1 + 2⁻⁵²
let b = 1.0 - .ulpOfOne // 1 - 2⁻⁵²
let c = a * b // 1 - 2⁻¹⁰⁴ before rounding, rounds to 1.0
```
Sometimes it is necessary to preserve some or all of those low-order bits;
maybe a subsequent subtraction cancels most of the high-order bits, and so
the low-order part of the product suddenly becomes significant:
```swift
let result = 1 - c // exactly zero, but "should be" 2⁻¹⁰⁴
```
Augmented arithmetic is a building-block that library writers can use to
handle cases like this more carefully. For the example above, one might
compute:
```swift
let (head, tail) = Augmented.product(a,b)
```
`head` is then 1.0 and `tail` is -2⁻¹⁰⁴, so no information has been lost.
Of course, the result is now split across two Doubles instead of one, but the
information in `tail` can be carried forward into future computations.
@@ -0,0 +1,68 @@
# ``ElementaryFunctions``
A type that has elementary functions (`sin`, `cos`, etc.) available.
## Overview
An ["elementary function"][elfn] is a function built up from powers, roots,
exponentials, logarithms, trigonometric functions (sin, cos, tan) and
their inverses, and the hyperbolic functions (sinh, cosh, tanh) and their
inverses.
Conformance to this protocol means that all of these building blocks are
available as static functions on the type.
```swift
let x: Float = 1
let y = Float.sin(x) // 0.84147096
```
`ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
and subtraction and the `zero` property are also available.
``RealFunctions`` refines this protocol and adds additional functions that
are primarily used with real numbers, such as ``RealFunctions/atan2(y:x:)``
and ``RealFunctions/exp10(_:)``.
``Real`` conforms to `RealFunctions` and `FloatingPoint`, and is the
protocol that you will use most often for generic code.
## Topics
There are a few families of functions defined by `ElementaryFunctions`:
### Exponential functions
- ``exp(_:)``
- ``expMinusOne(_:)``
### Logarithmetic functions
- ``log(_:)``
- ``log(onePlus:)``
### Power and root functions:
- ``pow(_:_:)-9imp6``
- ``pow(_:_:)-2qmul``
- ``sqrt(_:)``
- ``root(_:_:)``
### Trigonometric functions
- ``cos(_:)``
- ``sin(_:)``
- ``tan(_:)``
### Inverse trigonometric functions
- ``acos(_:)``
- ``asin(_:)``
- ``atan(_:)``
### Hyperbolic functions
- ``cosh(_:)``
- ``sinh(_:)``
- ``tanh(_:)``
### Inverse hyperbolic functions
- ``acosh(_:)``
- ``asinh(_:)``
- ``atanh(_:)``
[elfn]: http://en.wikipedia.org/wiki/Elementary_function
@@ -0,0 +1,27 @@
# ``RealFunctions``
A type that extends ``ElementaryFunctions`` with additional operations that
are primarily used with real numbers.
## Topics
### Exponential functions
- ``exp2(_:)``
- ``exp10(_:)``
### Logarithmetic functions
- ``log2(_:)``
- ``log10(_:)``
### Plane geometry
- ``atan2(y:x:)``
- ``hypot(_:_:)``
### Gamma function
- ``gamma(_:)``
- ``logGamma(_:)``
- ``signGamma(_:)``
### Error function
- ``erf(_:)``
- ``erfc(_:)``
@@ -0,0 +1,28 @@
# ``RealModule``
Extensions on the Swift standard library that provide functionality for
floating-point types.
## Overview
``RealModule`` provides four protocols that extend the standard library's
numeric protocol hierarchy: AlgebraicField, ElementaryFunctions,
RealFunctions, and Real.
Types conforming to AlgebraicField represent
[fields](https://en.wikipedia.org/wiki/Field_(mathematics)). These are the
mathematical structures that typically form the elements of vectors and
matrices, so this protocol is appropriate for writing generic code to do
linear-algebra-type operations.
ElementaryFunctions provides bindings for the "math functions": the logarithm
and exponential functions, sine, cosine and tangent as well as their inverses,
and other functions that you may be familiar with from trigonometry and
calculus. RealFunctions refines ElementaryFunctions and provides functions that
are primarily used with the real numbers, such as atan2, erf and gamma, and
the base-2 and -10 logarithm and exponential funtions.
The Real protocol is a convenient name for the intersection of `FloatingPoint`,
`RealFunctions`, and `AlgebraicField`; this is the protocol that you are most
likely to want to constrain to when writing generic "math" code that works
with floating-point types.
@@ -0,0 +1,53 @@
# ``Relaxed``
A namespace for a family of operations that "relax" the usual rules for
floating-point to allow reassociation of arithmetic and FMA formation.
## Overview
Because of rounding, and the arithmetic rules for infinity and NaN values,
floating-point addition and multiplication are not associative:
```swift
let ε = Double.leastNormalMagnitude
let sumLeft = (-1 + 1) + ε // 0 + ε = ε
let sumRight = -1 + (1 + ε) // -1 + 1 = 0
let ∞ = Double.infinity
let productLeft = (ε * ε) * ∞ // 0 * ∞ = .nan
let productRight = ε * (ε * ∞) // ε * ∞ = ∞
```
For some algorithms, the distinction between these results is incidental; for
some others it is critical to their correct function. Because of this,
compilers cannot freely change the order of reductions, which prevents some
important optimizations: extraction of instruction-level parallelism and
vectorization.
If you know that you are in a case where the order of elements being summed
or multiplied is incidental, the Relaxed operations give you a mechanism
to communicate that to the compiler and unlock these optimizations. For
example, consider the following two functions:
```swift
func sum(array: [Float]) -> Float {
array.reduce(0, +)
}
func relaxedSum(array: [Float]) -> Float {
array.reduce(0, Relaxed.sum)
}
```
when called on an array with 1000 elements in a Release build, `relaxedSum`
is about 8x faster than `sum` on Apple M2, with a similar speedup on Intel
processors, without the need for any unsafe code or flags.
### multiplyAdd
In addition to `sum` and `product`, `Relaxed` provides the
``multiplyAdd(_:_:_:)`` operation, which communciates to the compiler that
it is allowed to replace separate multiply and add operations with a single
_fused multiply-add_ instruction if its cost model indicates that it would
be advantageous to do so. When targeting processors that support this
instruction, this may be a significant performance advantage.
+1 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
+39 -77
View File
@@ -2,62 +2,19 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// A type that has elementary functions available.
///
/// An ["elementary function"][elfn] is a function built up from powers, roots,
/// exponentials, logarithms, trigonometric functions (sin, cos, tan) and
/// their inverses, and the hyperbolic functions (sinh, cosh, tanh) and their
/// inverses.
///
/// Conformance to this protocol means that all of these building blocks are
/// available as static functions on the type.
///
/// ```swift
/// let x: Float = 1
/// let y = Float.sin(x) // 0.84147096
/// ```
///
/// There are three broad families of functions defined by
/// `ElementaryFunctions`:
/// - Exponential, trigonometric, and hyperbolic functions:
/// `exp`, `expMinusOne`, `cos`, `sin`, `tan`, `cosh`, `sinh`, and `tanh`.
/// - Logarithmic, inverse trigonometric, and inverse hyperbolic functions:
/// `log`, `log(onePlus:)`, `acos`, `asin`, `atan`, `acosh`, `asinh`, and
/// `atanh`.
/// - Power and root functions:
/// `pow`, `sqrt`, and `root`.
///
/// `ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
/// and subtraction and the `.zero` property are also available.
///
/// There are two other protocols that you are more likely to want to use
/// directly:
///
/// `RealFunctions` refines `ElementaryFunctions` and includes
/// additional functions specific to real number types.
///
/// `Real` conforms to `RealFunctions` and `FloatingPoint`, and is the
/// protocol that you will want to use most often for generic code.
///
/// See Also:
///
/// - `RealFunctions`
/// - `Real`
///
/// [elfn]: http://en.wikipedia.org/wiki/Elementary_function
public protocol ElementaryFunctions: AdditiveArithmetic {
/// The [exponential function][wiki] e^x whose base `e` is the base of the
/// natural logarithm.
///
/// See also `expMinusOne()`, as well as `exp2()` and `exp10()`
/// defined for types conforming to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see
/// ``RealFunctions/exp2(_:)`` and ``RealFunctions/exp10(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Exponential_function
static func exp(_ x: Self) -> Self
@@ -68,7 +25,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// catastrophic cancellation and the result will not have full accuracy.
/// The `.expMinusOne(x)` function gives you a means to address this problem.
///
/// As an example, consider the expression `(x + 1)*exp(x) - 1`. When `x`
/// As an example, consider the expression `(x + 1) * .exp(x) - 1`. When `x`
/// is smaller than `.ulpOfOne`, this expression evaluates to `0.0`, when it
/// should actually round to `2*x`. We can get a full-accuracy result by
/// using the following instead:
@@ -79,8 +36,8 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// This re-written expression delivers an accurate result for all values
/// of `x`, not just for small values.
///
/// See also `exp()`, as well as `exp2()` and `exp10()` defined for types
/// conforming to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see
/// ``RealFunctions/exp2(_:)`` and ``RealFunctions/exp10(_:)``.
static func expMinusOne(_ x: Self) -> Self
/// The [hyperbolic cosine][wiki] of `x`.
@@ -90,7 +47,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// 2
/// ```
///
/// See also `sinh()`, `tanh()` and `acosh()`.
/// See also ``acosh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func cosh(_ x: Self) -> Self
@@ -102,7 +59,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// 2
/// ```
///
/// See also `cosh()`, `tanh()` and `asinh()`.
/// See also ``asinh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func sinh(_ x: Self) -> Self
@@ -114,7 +71,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// cosh(x)
/// ```
///
/// See also `cosh()`, `sinh()` and `atanh()`.
/// See also ``atanh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func tanh(_ x: Self) -> Self
@@ -123,7 +80,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `sin()`, `tan()` and `acos()`.
/// See also ``acos(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Cosine
static func cos(_ x: Self) -> Self
@@ -133,7 +90,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `cos()`, `tan()` and `asin()`.
/// See also ``asin(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Sine
static func sin(_ x: Self) -> Self
@@ -142,49 +99,54 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `cos()`, `sin()` and `atan()`, as well as `atan2(y:x:)` for
/// types that conform to `RealFunctions`.
/// See also ``atan(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Tangent
static func tan(_ x: Self) -> Self
/// The [natural logarithm][wiki] of `x`.
///
/// See also `log(onePlus:)`, as well as `log2()` and `log10()` for types
/// that conform to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see also
/// ``RealFunctions/log2(_:)`` and ``RealFunctions/log10(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Logarithm
static func log(_ x: Self) -> Self
/// log(1 + x), computed in such a way as to maintain accuracy for small x.
///
/// See also `log()`, as well as `log2()` and `log10()` for types
/// that conform to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see also
/// ``RealFunctions/log2(_:)`` and ``RealFunctions/log10(_:)``.
static func log(onePlus x: Self) -> Self
/// The [inverse hyperbolic cosine][wiki] of `x`.
///
/// ```
/// cosh(acosh(x)) ≅ x
/// ```
/// See also `asinh()`, `atanh()` and `cosh()`.
///
/// See also ``cosh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func acosh(_ x: Self) -> Self
/// The [inverse hyperbolic sine][wiki] of `x`.
///
/// ```
/// sinh(asinh(x)) ≅ x
/// ```
/// See also `acosh()`, `atanh()` and `sinh()`.
///
/// See also ``sinh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func asinh(_ x: Self) -> Self
/// The [inverse hyperbolic tangent][wiki] of `x`.
///
/// ```
/// tanh(atanh(x)) ≅ x
/// ```
/// See also `acosh()`, `asinh()` and `tanh()`.
///
/// See also ``tanh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func atanh(_ x: Self) -> Self
@@ -193,10 +155,12 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// cos(acos(x)) ≅ x
/// ```
/// See also `asin()`, `atan()` and `cos()`.
///
/// See also ``cos(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func acos(_ x: Self) -> Self
@@ -205,10 +169,12 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// sin(asin(x)) ≅ x
/// ```
/// See also `acos()`, `atan()` and `sin()`.
///
/// See also ``sin(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func asin(_ x: Self) -> Self
@@ -217,11 +183,14 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// tan(atan(x)) ≅ x
/// ```
/// See also `acos()`, `asin()` and `tan()`, as well as `atan2(y:x:)` for
/// types that conform to `RealArithmetic`.
///
/// See also ``tan(_:)``.
/// For types that conform to ``RealFunctions``, you will sometimes want
/// to use ``RealFunctions/atan2(y:x:)`` instead.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func atan(_ x: Self) -> Self
@@ -233,10 +202,9 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// In particular, this means that if `x` and `y` are both zero, `pow(x,y)`
/// is `nan` for real types and `infinity` for complex types, rather than 1.
///
/// There is also a `pow(_:Self,_:Int)` overload, whose behavior is defined
/// in terms of repeated multiplication, and hence returns 1 for this case.
///
/// See also `sqrt()` and `root()`.
/// There is also
/// <doc:/documentation/RealModule/ElementaryFunctions/pow(_:_:)-9imp6>,
/// whose behavior is defined in terms of repeated multiplication.
static func pow(_ x: Self, _ y: Self) -> Self
/// `x` raised to the nth power.
@@ -244,19 +212,13 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// The edge-cases of this function are defined in terms of repeated
/// multiplication or division, rather than exp(n log x). In particular,
/// `Float.pow(0, 0)` is 1.
///
/// See also `sqrt()` and `root()`.
static func pow(_ x: Self, _ n: Int) -> Self
/// The [square root][wiki] of `x`.
///
/// See also `pow()` and `root()`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Square_root
static func sqrt(_ x: Self) -> Self
/// The nth root of `x`.
///
/// See also `pow()` and `sqrt()`.
static func root(_ x: Self, _ n: Int) -> Self
}
+4 -3
View File
@@ -173,9 +173,10 @@ extension Float16: Real {
}
#endif
// TODO: once clang stabilizes the calling conventions for _Float16 on Intel,
// we can re-enable these; presently the type is disabled on the target.
#if !(arch(i386) || arch(x86_64))
#if !arch(wasm32)
// WASM doesn't have _Float16 on the C side, so we can't define the C hooks
// that these use. TODO: implement these as Swift builtins instead.
@_transparent
public static func _relaxedAdd(_ a: Float16, _ b: Float16) -> Float16 {
_numerics_relaxed_addf16(a, b)
+15 -14
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -24,23 +24,24 @@
/// }
/// ```
/// See also `ElementaryFunctions`, `RealFunctions` and `AlgebraicField`.
public protocol Real: FloatingPoint, RealFunctions, AlgebraicField {
}
public protocol Real: FloatingPoint, RealFunctions, AlgebraicField { }
// While `Real` does not provide any additional customization points,
// it does allow us to default the implementation of a few operations,
// and also provides `signGamma`.
extension Real {
// Most math libraries do not provide exp10, so we need a default
// implementation.
// implementation. This is not a great one (if the underlying math
// library does not have a sub-ulp accurate pow, this will not get
// exact powers of ten right), but suffices in the short term.
@_transparent
public static func exp10(_ x: Self) -> Self {
return pow(10, x)
pow(10, x)
}
/// cos(x) - 1, computed in such a way as to maintain accuracy for small x.
///
/// See also `ElementaryFunctions.expMinusOne()`.
/// See also ``ElementaryFunctions/expMinusOne(_:)``.
@_transparent
public static func cosMinusOne(_ x: Self) -> Self {
let sinxOver2 = sin(x/2)
@@ -90,7 +91,7 @@ extension Real {
@_transparent
public static func sqrt(_ x: Self) -> Self {
return x.squareRoot()
x.squareRoot()
}
/// The (approximate) reciprocal (multiplicative inverse) of this number,
@@ -128,13 +129,13 @@ extension Real {
/// the real reciprocal (when it exists) as follows (I will use circle
/// operators to denote real-number arithmetic, and normal operators
/// for floating-point arithmetic):
///
/// a * b.reciprocal! = a * (1/b)
/// = a * (1 ⊘ b)(1 + δ₁)
/// = (a ⊘ b)(1 + δ₁)(1 + δ₂)
/// = (a ⊘ b)(1 + δ₁ + δ₂ + δ₁δ₂)
///
/// where 0 < δᵢ <= ulpOfOne/2. This gives a roughly 1-ulp error,
/// ```
/// a * b.reciprocal! = a * (1/b)
/// = a * (1 ⊘ b)(1 + δ₁)
/// = (a ⊘ b)(1 + δ₁)(1 + δ₂)
/// = (a ⊘ b)(1 + δ₁ + δ₂ + δ₁δ₂)
/// ```
/// where `0 < δᵢ <= ulpOfOne/2`. This gives a roughly 1-ulp error,
/// about twice the error bound we get using division. For most
/// purposes this is an acceptable error, but if you need to match
/// results obtained using division, you should not use this.
+46 -27
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2019-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -10,70 +10,89 @@
//===----------------------------------------------------------------------===//
public protocol RealFunctions: ElementaryFunctions {
/// `atan(y/x)`, with sign selected according to the quadrant of `(x, y)`.
/// The signed angle formed in the plane between the vector `(x,y)` and the
/// positive real axis, measured in radians.
///
/// See also `atan()`.
/// The result is in the interval `[-π, π]`.
///
/// The argument order to `atan2` may be surprising to new programmers.
/// The convention of `y` being the first argument goes back at least to
/// Fortran IV in 1961 and is generally followed in computing with a few
/// notable exceptions (e.g. Mathematica and Excel). This convention was
/// originally chosen because of the mathematical definition of the
/// function:
///
/// ```
/// atan2(y,x) = atan(y/x) if x > 0
/// ```
///
/// See also ``ElementaryFunctions/atan(_:)``, as well as the `phase` and
/// `polar` properties defined on the `Complex` type.
static func atan2(y: Self, x: Self) -> Self
/// The error function evaluated at `x`.
///
/// See also `erfc()`.
/// The [error function](https://en.wikipedia.org/wiki/Error_function)
/// evaluated at `x`.
static func erf(_ x: Self) -> Self
/// The complimentary error function evaluated at `x`.
///
/// See also `erf()`.
/// The complimentary [error function](https://en.wikipedia.org/wiki/Error_function)
/// evaluated at `x`.
static func erfc(_ x: Self) -> Self
/// 2^x
/// 2 raised to the power x.
///
/// See also `exp()`, `expMinusOne()`, `exp10()`, `log2()` and `pow()`.
/// See also ``log2(_:)``, ``ElementaryFunctions/exp(_:)``,
/// ``ElementaryFunctions/expMinusOne(_:)``
/// and ``ElementaryFunctions/pow(_:_:)-2qmul``.
static func exp2(_ x: Self) -> Self
/// 10^x
/// 10 raised to the power x.
///
/// See also `exp()`, `expMinusOne()`, `exp2()`, `log10()` and `pow()`.
/// See also ``log10(_:)``, ``ElementaryFunctions/exp(_:)``,
/// ``ElementaryFunctions/expMinusOne(_:)``
/// and ``ElementaryFunctions/pow(_:_:)-2qmul``.
static func exp10(_ x: Self) -> Self
/// `sqrt(x*x + y*y)`, computed in a manner that avoids spurious overflow or
/// underflow.
/// The length of the vector `(x,y)`, computed in a manner that avoids
/// spurious overflow or underflow.
///
/// See also the `length` and `polar` properties defined on the `Complex`
/// type.
static func hypot(_ x: Self, _ y: Self) -> Self
/// The gamma function Γ(x).
///
/// See also `logGamma()` and `signGamma()`.
/// The [gamma function](https://en.wikipedia.org/wiki/Gamma_function) Γ(x).
static func gamma(_ x: Self) -> Self
/// The base-2 logarithm of `x`.
///
/// See also `exp2()`, `log()`, `log(onePlus:)` and `log10()`.
/// See also ``exp2(_:)``, ``ElementaryFunctions/log(_:)``,
/// and ``ElementaryFunctions/log(onePlus:)``.
static func log2(_ x: Self) -> Self
/// The base-10 logarithm of `x`.
///
/// See also: `exp10()`, `log()`, `log(onePlus:)` and `log2()`.
/// See also ``exp10(_:)``, ``ElementaryFunctions/log(_:)``,
/// and ``ElementaryFunctions/log(onePlus:)``.
static func log10(_ x: Self) -> Self
#if !os(Windows)
/// The logarithm of the absolute value of the gamma function, log(|Γ(x)|).
/// The logarithm of the absolute value of the
/// [gamma function](https://en.wikipedia.org/wiki/Gamma_function),
/// log(|Γ(x)|).
///
/// Not available on Windows targets.
///
/// See also `gamma()` and `signGamma()`.
static func logGamma(_ x: Self) -> Self
/// The sign of the gamma function, Γ(x).
/// The sign of the
/// [gamma function](https://en.wikipedia.org/wiki/Gamma_function), Γ(x).
///
/// For `x >= 0`, `signGamma(x)` is `.plus`. For negative `x`, `signGamma(x)`
/// is `.plus` when `x` is an integer, and otherwise it is `.minus` whenever
/// `trunc(x)` is even, and `.plus` when `trunc(x)` is odd.
///
/// This function is used together with `logGamma`, which computes the
/// This function is used together with ``logGamma(_:)``, which computes the
/// logarithm of the absolute value of Γ(x), to recover the sign information.
///
/// Not available on Windows targets.
///
/// See also `gamma()` and `logGamma()`.
static func signGamma(_ x: Self) -> FloatingPointSign
#endif
}
+5 -5
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2021-2025 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
@@ -11,12 +11,11 @@
import _NumericsShims
/// A namespace for "relaxed arithmetic" operations for types conforming to
/// `AlgebraicField`.
public enum Relaxed { }
extension Relaxed {
/// a+b with the optimizer licensed to reassociate expressions and form FMAs.
/// a+b, but grants the optimizer permission to reassociate expressions
/// and form FMAs.
///
/// Floating-point addition is not an associative operation, so the Swift
/// compiler does not have any flexibility in how it evaluates an expression
@@ -45,7 +44,8 @@ extension Relaxed {
T._relaxedAdd(a, b)
}
/// a*b with the optimizer licensed to reassociate expressions and form FMAs.
/// a*b, but grants the optimizer permission to reassociate expressions
/// and form FMAs.
///
/// Floating-point addition and multiplication are not associative operations,
/// so the Swift compiler does not have any flexibility in how it evaluates
@@ -389,7 +389,7 @@ HEADER_SHIM long double libm_lgammal(long double x, int *signp) {
// MARK: - math inlines with relaxed semantics to support optimization.
#define CLANG_RELAX_FP _Pragma("clang fp reassociate(on) contract(fast)")
#if !(__i386__ || __x86_64__)
#if !defined __wasm__ // No _Float16 on wasm
/// a + b with the "allow reassociation" and "allow FMA formation" flags
/// set in the IR.
HEADER_SHIM _Float16 _numerics_relaxed_addf16(_Float16 a, _Float16 b) {
@@ -0,0 +1,67 @@
//===--- ArithmeticTests.swift --------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2020 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import XCTest
import RealModule
@testable import QuaternionModule
final class ArithmeticTests: XCTestCase {
func testMultiplication<T: Real & SIMDScalar>(_ type: T.Type) {
for value: T in [-3, -2, -1, +1, +2, +3] {
let q = Quaternion<T>(real: value, imaginary: value, value, value)
XCTAssertEqual(q * .one, q)
XCTAssertEqual(q * 1, q)
XCTAssertEqual(1 * q, q)
}
}
func testMultiplication() {
testMultiplication(Float32.self)
testMultiplication(Float64.self)
}
func testDivision<T: Real & SIMDScalar>(_ type: T.Type) {
for value: T in [-3, -2, -1, +1, +2, +3] {
let q = Quaternion<T>(real: value, imaginary: value, value, value)
XCTAssertEqual(q/q, .one)
XCTAssertEqual(0/q, .zero)
for q2: Quaternion<T> in [-3, -2, -1, 0, +1, +2, +3] {
XCTAssertEqual(q2/q, q2 * q.reciprocal!)
}
for q2: T in [-3, -2, -1, +1, +2, +3] {
XCTAssertEqual(q.divided(by: q2), q.multiplied(by: 1/q2))
}
}
}
func testDivision() {
testDivision(Float32.self)
testDivision(Float64.self)
}
func testDivisionByZero<T: Real & SIMDScalar>(_ type: T.Type) {
XCTAssertFalse((Quaternion<T>(real: 0, imaginary: 0, 0, 0) / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
XCTAssertFalse((Quaternion<T>(real: 1, imaginary: 1, 1, 1) / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
XCTAssertFalse((Quaternion<T>.infinity / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
XCTAssertFalse((Quaternion<T>.i / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
XCTAssertFalse((Quaternion<T>.j / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
XCTAssertFalse((Quaternion<T>.k / Quaternion<T>(real: 0, imaginary: 0, 0, 0)).isFinite)
}
func testDivisionByZero() {
testDivisionByZero(Float32.self)
testDivisionByZero(Float64.self)
}
}
@@ -0,0 +1,252 @@
//===--- ElementaryFunctionTests.swift ------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import XCTest
import RealModule
import _TestSupport
@testable import QuaternionModule
final class ElementaryFunctionTests: XCTestCase {
// MARK: - exp-like functions
func testExp<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
// exp(0) = 1
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)))
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
// 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
// 0 if we evaluated it in the usual way.
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: 0, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: -.infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: -.infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: -.infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: 0, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .nan, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .nan, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: -.infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.exp(Quaternion(real: .nan, imaginary: -.infinity)).isFinite)
// Find a value of x such that exp(x) just overflows. Then exp((x, π/4))
// should not overflow, but will do so if it is not computed carefully.
// The correct value is:
//
// exp((log(gfm) + log(9/8), π/4) = exp((log(gfm*9/8), π/4))
// = gfm*9/8 * (1/sqrt(2), 1/(sqrt(2))
let x = T.log(.greatestFiniteMagnitude) + T.log(9/8)
let huge = Quaternion<T>.exp(Quaternion(real: x, imaginary: SIMD3(.pi/4, 0, 0)))
let mag = T.greatestFiniteMagnitude/T.sqrt(2) * (9/8)
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
// For randomly-chosen well-scaled finite values, we expect to have the
// usual identities:
//
// exp(z + w) = exp(z) * exp(w)
// exp(z - w) = exp(z) / exp(w)
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 z in values {
for w in values {
let p = Quaternion.exp(z) * Quaternion.exp(w)
let q = Quaternion.exp(z) / Quaternion.exp(w)
XCTAssert(Quaternion.exp(z + w).isApproximatelyEqual(to: p))
XCTAssert(Quaternion.exp(z - w).isApproximatelyEqual(to: q))
}
}
}
func testExpMinusOne<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
// expMinusOne(0) = 0
XCTAssertEqual(0, Quaternion<T>.expMinusOne(Quaternion(real: 0, imaginary: 0, 0, 0)))
XCTAssertEqual(0, Quaternion<T>.expMinusOne(Quaternion(real:-0, imaginary: 0, 0, 0)))
XCTAssertEqual(0, Quaternion<T>.expMinusOne(Quaternion(real:-0, imaginary:-0,-0,-0)))
XCTAssertEqual(0, Quaternion<T>.expMinusOne(Quaternion(real: 0, imaginary:-0,-0,-0)))
// In general, expMinusOne(Quaternion(r,0,0,0)) should be expMinusOne(r),
// but that breaks down when r is infinity or NaN, because we want all non-
// finite Quaternion values to be semantically a single point at infinity.
// This is fine for most inputs, but expMinusOne(Quaternion(-.infinity,0,0,0))
// would produce 0 if we evaluated it in the usual way.
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: 0, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: -.infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: -.infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: -.infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: 0, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .nan, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .nan, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: -.infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.expMinusOne(Quaternion(real: .nan, imaginary: -.infinity)).isFinite)
// Near-overflow test, same as exp() above.
let x = T.log(.greatestFiniteMagnitude) + T.log(9/8)
let huge = Quaternion<T>.expMinusOne(Quaternion(real: x, imaginary: SIMD3(.pi/4, 0, 0)))
let mag = T.greatestFiniteMagnitude/T.sqrt(2) * (9/8)
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
// For small values, expMinusOne should be approximately the identity.
var g = SystemRandomNumberGenerator()
let small = T.ulpOfOne
for _ in 0 ..< 100 {
let q = Quaternion<T>(
real: T.random(in: -small ... small, using: &g),
imaginary:
T.random(in: -small ... small, using: &g),
T.random(in: -small ... small, using: &g),
T.random(in: -small ... small, using: &g)
)
XCTAssert(q.isApproximatelyEqual(to: Quaternion.expMinusOne(q), relativeTolerance: 16 * .ulpOfOne))
}
}
func testCosh<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
// cosh(0) = 1
XCTAssertEqual(1, Quaternion<T>.cosh(Quaternion(real: 0, imaginary: 0, 0, 0)))
XCTAssertEqual(1, Quaternion<T>.cosh(Quaternion(real:-0, imaginary: 0, 0, 0)))
XCTAssertEqual(1, Quaternion<T>.cosh(Quaternion(real:-0, imaginary:-0,-0,-0)))
XCTAssertEqual(1, Quaternion<T>.cosh(Quaternion(real: 0, imaginary:-0,-0,-0)))
// cosh is the identity at infinity.
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: 0, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: -.infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: -.infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: -.infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: 0, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .nan, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .nan, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: -.infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.cosh(Quaternion(real: .nan, imaginary: -.infinity)).isFinite)
// Near-overflow test, same as exp() above, but it happens later, because
// for large x, cosh(x + v) ~ exp(x + v)/2.
let x = T.log(.greatestFiniteMagnitude) + T.log(18/8)
let mag = T.greatestFiniteMagnitude/T.sqrt(2) * (9/8)
var huge = Quaternion<T>.cosh(Quaternion(real: x, imaginary: SIMD3(.pi/4, 0, 0)))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
huge = Quaternion<T>.cosh(Quaternion(real: -x, imaginary: SIMD3(.pi/4, 0, 0)))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
}
func testSinh<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
// sinh(0) = 0
XCTAssertEqual(0, Quaternion<T>.sinh(Quaternion(real: 0, imaginary: 0, 0, 0)))
XCTAssertEqual(0, Quaternion<T>.sinh(Quaternion(real:-0, imaginary: 0, 0, 0)))
XCTAssertEqual(0, Quaternion<T>.sinh(Quaternion(real:-0, imaginary:-0,-0,-0)))
XCTAssertEqual(0, Quaternion<T>.sinh(Quaternion(real: 0, imaginary:-0,-0,-0)))
// sinh is the identity at infinity.
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: 0, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: -.infinity, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: -.infinity, imaginary: .zero)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: -.infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: 0, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .infinity, imaginary: -.infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .nan, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .nan, imaginary: .infinity)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: -.infinity, imaginary: .nan)).isFinite)
XCTAssertFalse(Quaternion<T>.sinh(Quaternion(real: .nan, imaginary: -.infinity)).isFinite)
// Near-overflow test, same as exp() above, but it happens later, because
// for large x, sinh(x + v) ~ ±exp(x + v)/2.
let x = T.log(.greatestFiniteMagnitude) + T.log(18/8)
let mag = T.greatestFiniteMagnitude/T.sqrt(2) * (9/8)
var huge = Quaternion<T>.sinh(Quaternion(real: x, imaginary: SIMD3(.pi/4, 0, 0)))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
huge = Quaternion<T>.sinh(Quaternion(real: -x, imaginary: SIMD3(.pi/4, 0, 0)))
XCTAssert(huge.real.isApproximatelyEqual(to: -mag))
XCTAssert(huge.imaginary.x.isApproximatelyEqual(to: -mag))
XCTAssertEqual(huge.imaginary.y, .zero)
XCTAssertEqual(huge.imaginary.z, .zero)
// For randomly-chosen well-scaled finite values, we expect to have
// cosh² - sinh² ≈ 1. Note that this test would break down due to
// catastrophic cancellation as we get further away from the origin.
var g = SystemRandomNumberGenerator()
let values: [Quaternion<T>] = (0..<1000).map { _ in
Quaternion(
real: T.random(in: -2 ... 2, using: &g),
imaginary:
T.random(in: -2 ... 2, using: &g),
T.random(in: -2 ... 2, using: &g),
T.random(in: -2 ... 2, using: &g)
)
}
for q in values {
let c = Quaternion.cosh(q)
let s = Quaternion.sinh(q)
XCTAssert((c*c - s*s).isApproximatelyEqual(to: .one))
}
}
func testCosSin<T: Real & FixedWidthFloatingPoint & SIMDScalar>(_ type: T.Type) {
var g = SystemRandomNumberGenerator()
let values: [Quaternion<T>] = (0..<1000).map { _ in
Quaternion(
real: T.random(in: -2 ... 2, using: &g),
imaginary:
T.random(in: -2 ... 2, using: &g),
T.random(in: -2 ... 2, using: &g),
T.random(in: -2 ... 2, using: &g)
)
}
for q in values {
// For randomly-chosen well-scaled finite values, we expect to have
// cos² + sin² ≈ 1
let s = Quaternion.sin(q)
let c = Quaternion.cos(q)
XCTAssert((c*c + s*s).isApproximatelyEqual(to: .one))
}
}
func testFloat() {
testExp(Float32.self)
testExpMinusOne(Float32.self)
testCosh(Float32.self)
testSinh(Float32.self)
testCosSin(Float32.self)
}
func testDouble() {
testExp(Float64.self)
testExpMinusOne(Float64.self)
testCosh(Float64.self)
testSinh(Float64.self)
testCosSin(Float64.self)
}
}
+236
View File
@@ -0,0 +1,236 @@
//===--- PropertyTests.swift ----------------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import XCTest
import RealModule
@testable import QuaternionModule
final class PropertyTests: XCTestCase {
func testProperties<T: Real & SIMDScalar>(_ type: T.Type) {
// The real and imaginary parts of a non-finite value should be nan.
XCTAssertTrue(Quaternion<T>.infinity.real.isNaN)
XCTAssertTrue(Quaternion<T>.infinity.imaginary.x.isNaN)
XCTAssertTrue(Quaternion<T>.infinity.imaginary.y.isNaN)
XCTAssertTrue(Quaternion<T>.infinity.imaginary.z.isNaN)
XCTAssertTrue(Quaternion<T>(real: .infinity, imaginary: .nan, .nan, .nan).real.isNaN)
XCTAssertTrue(Quaternion<T>(real: .nan, imaginary: 0, 0, 0).imaginary.x.isNaN)
XCTAssertTrue(Quaternion<T>(real: .nan, imaginary: 0, 0, 0).imaginary.y.isNaN)
XCTAssertTrue(Quaternion<T>(real: .nan, imaginary: 0, 0, 0).imaginary.z.isNaN)
// The length of a non-finite value should be infinity.
XCTAssertEqual(Quaternion<T>.infinity.length, .infinity)
XCTAssertEqual(Quaternion<T>(real: .infinity, imaginary: .nan, .nan, .nan).length, .infinity)
XCTAssertEqual(Quaternion<T>(real: .nan, imaginary: 0, 0, 0).length, .infinity)
// The length of a zero value should be zero.
XCTAssertEqual(Quaternion<T>.zero.length, .zero)
XCTAssertEqual(Quaternion<T>(real: .zero, imaginary: -.zero).length, .zero)
XCTAssertEqual(Quaternion<T>(real: -.zero, imaginary: -.zero).length, .zero)
// Check for overflow and underflow when calculating the length
XCTAssertEqual(Quaternion<T>(real: .greatestFiniteMagnitude, imaginary: 0, 0, 0).length, .greatestFiniteMagnitude)
XCTAssertEqual(Quaternion<T>(real: 0, imaginary: -.greatestFiniteMagnitude, 0, 0).length, .greatestFiniteMagnitude)
XCTAssertEqual(Quaternion<T>(real: 0, imaginary: 0, .leastNormalMagnitude, 0).length, .leastNormalMagnitude)
XCTAssertEqual(Quaternion<T>(real: 0, imaginary: 0, 0, -.leastNormalMagnitude).length, .leastNormalMagnitude)
// The properties of pure and real
XCTAssertTrue(Quaternion<T>.zero.isPure) // zero quaternion is both, pure...
XCTAssertTrue(Quaternion<T>.zero.isReal) // and real
XCTAssertFalse(Quaternion<T>(1).isPure)
XCTAssertTrue(Quaternion<T>(1).isReal)
XCTAssertTrue(Quaternion<T>(real: .zero, imaginary: 1, 0, 0).isPure)
XCTAssertFalse(Quaternion<T>(real: .zero, imaginary: 1, 0, 0).isReal)
XCTAssertFalse(Quaternion<T>(from: SIMD4(repeating: 1)).isPure)
XCTAssertFalse(Quaternion<T>(from: SIMD4(repeating: 1)).isReal)
}
func testProperties() {
testProperties(Float32.self)
testProperties(Float64.self)
}
func testEquatableHashable<T: Real & SIMDScalar>(_ type: T.Type) {
// Validate that all zeros compare and hash equal, and all non-finites
// do too.
let zeros = [
Quaternion<T>(real: .zero, imaginary: .zero, .zero, .zero),
Quaternion<T>(real: .zero, imaginary: -.zero, .zero, .zero),
Quaternion<T>(real: .zero, imaginary: .zero, -.zero, .zero),
Quaternion<T>(real: .zero, imaginary: .zero, .zero, -.zero),
Quaternion<T>(real: .zero, imaginary: -.zero, -.zero, .zero),
Quaternion<T>(real: .zero, imaginary: -.zero, .zero, -.zero),
Quaternion<T>(real: .zero, imaginary: .zero, -.zero, -.zero),
Quaternion<T>(real: .zero, imaginary: -.zero, -.zero, -.zero),
Quaternion<T>(real: -.zero, imaginary: .zero, .zero, .zero),
Quaternion<T>(real: -.zero, imaginary: -.zero, .zero, .zero),
Quaternion<T>(real: -.zero, imaginary: .zero, -.zero, .zero),
Quaternion<T>(real: -.zero, imaginary: .zero, .zero, -.zero),
Quaternion<T>(real: -.zero, imaginary: -.zero, -.zero, .zero),
Quaternion<T>(real: -.zero, imaginary: -.zero, .zero, -.zero),
Quaternion<T>(real: -.zero, imaginary: .zero, -.zero, -.zero),
Quaternion<T>(real: -.zero, imaginary: -.zero, -.zero, -.zero)
]
for z in zeros[1...] {
XCTAssertEqual(zeros[0], z)
XCTAssertEqual(zeros[0].hashValue, z.hashValue)
}
let infs = [
Quaternion<T>(real: .nan, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: -.infinity, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: -.ulpOfOne, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: .zero, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: .pi, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: .infinity, imaginary: .nan, .nan, .nan),
Quaternion<T>(real: .nan, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: -.infinity, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: -.ulpOfOne, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: .zero, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: .pi, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: .infinity, imaginary: -.infinity, -.infinity, -.infinity),
Quaternion<T>(real: .nan, imaginary: -.ulpOfOne, -.ulpOfOne, -.ulpOfOne),
Quaternion<T>(real: -.infinity, imaginary: -.ulpOfOne, -.ulpOfOne, -.ulpOfOne),
Quaternion<T>(real: .infinity, imaginary: -.ulpOfOne, -.ulpOfOne, -.ulpOfOne),
Quaternion<T>(real: .nan, imaginary: .zero, .zero, .zero),
Quaternion<T>(real: -.infinity, imaginary: .zero, .zero, .zero),
Quaternion<T>(real: .infinity, imaginary: .zero, .zero, .zero),
Quaternion<T>(real: .nan, imaginary: .pi, .pi, .pi),
Quaternion<T>(real: -.infinity, imaginary: .pi, .pi, .pi),
Quaternion<T>(real: .infinity, imaginary: .pi, .pi, .pi),
Quaternion<T>(real: .nan, imaginary: .infinity, .infinity, .infinity),
Quaternion<T>(real: -.infinity, imaginary: .infinity, .infinity, .infinity),
Quaternion<T>(real: -.ulpOfOne, imaginary: .infinity, .infinity, .infinity),
Quaternion<T>(real: .zero, imaginary: .infinity, .infinity, .infinity),
Quaternion<T>(real: .pi, imaginary: .infinity, .infinity, .infinity),
Quaternion<T>(real: .infinity, imaginary: .infinity, .infinity, .infinity),
]
for i in infs[1...] {
XCTAssertEqual(infs[0], i)
XCTAssertEqual(infs[0].hashValue, i.hashValue)
}
// Validate that all *normal* values hash their absolute components, so
// that rotations in *R³* of `q` and `-q` will hash to same value.
let pairs: [(lhs: Quaternion<T>, rhs: Quaternion<T>)] = [
(
Quaternion<T>(real: -.pi, imaginary: .pi, .pi, .pi),
Quaternion<T>(real: .pi, imaginary: -.pi, -.pi, -.pi)
), (
Quaternion<T>(real: .pi, imaginary: -.pi, .pi, .pi),
Quaternion<T>(real: -.pi, imaginary: .pi, -.pi, -.pi)
), (
Quaternion<T>(real: .pi, imaginary: .pi, -.pi, .pi),
Quaternion<T>(real: -.pi, imaginary: -.pi, .pi, -.pi)
), (
Quaternion<T>(real: .pi, imaginary: .pi, .pi, -.pi),
Quaternion<T>(real: -.pi, imaginary: -.pi, -.pi, .pi)
), (
Quaternion<T>(real: -.pi, imaginary: -.pi, .pi, .pi),
Quaternion<T>(real: .pi, imaginary: .pi, -.pi, -.pi)
), (
Quaternion<T>(real: .pi, imaginary: -.pi, -.pi, .pi),
Quaternion<T>(real: -.pi, imaginary: .pi, .pi, -.pi)
), (
Quaternion<T>(real: .pi, imaginary: .pi, -.pi, -.pi),
Quaternion<T>(real: -.pi, imaginary: -.pi, .pi, .pi)
), (
Quaternion<T>(real: .pi, imaginary: .pi, .pi, .pi),
Quaternion<T>(real: -.pi, imaginary: -.pi, -.pi, -.pi)
)
]
for pair in pairs {
XCTAssertEqual(pair.lhs.hashValue, pair.rhs.hashValue)
}
}
func testEquatableHashable() {
testEquatableHashable(Float32.self)
testEquatableHashable(Float64.self)
}
func testTransformationEquals<T: Real & SIMDScalar>(_ type: T.Type) {
let rotations: [(lhs: Quaternion<T>, rhs: Quaternion<T>)] = [
(
Quaternion<T>(real: -.pi, imaginary: -.pi, -.pi, -.pi),
Quaternion<T>(real: .pi, imaginary: .pi, .pi, .pi)
), (
Quaternion<T>(real: .ulpOfOne, imaginary: .ulpOfOne, .ulpOfOne, .ulpOfOne),
Quaternion<T>(real: -.ulpOfOne, imaginary: -.ulpOfOne, -.ulpOfOne, -.ulpOfOne)
), (
Quaternion<T>(real: .pi, imaginary: -.pi, .pi, -.pi),
Quaternion<T>(real: -.pi, imaginary: .pi, -.pi, .pi)
), (
Quaternion<T>(real: -.ulpOfOne, imaginary: -.ulpOfOne, .ulpOfOne, .ulpOfOne),
Quaternion<T>(real: .ulpOfOne, imaginary: .ulpOfOne, -.ulpOfOne, -.ulpOfOne)
),
// Zero and infinity must have equal rotations too
(
Quaternion<T>.zero,
-Quaternion<T>.zero
), (
-Quaternion<T>.infinity,
Quaternion<T>.infinity
),
]
for (lhs, rhs) in rotations {
XCTAssertTrue(lhs.equals(as3DTransform: rhs))
}
let signDifferentAxis: [(lhs: Quaternion<T>, rhs: Quaternion<T>)] = [
(
Quaternion<T>(real: -.pi, imaginary: -.pi, -.pi, -.pi),
Quaternion<T>(real: -.pi, imaginary: .pi, .pi, .pi)
), (
Quaternion<T>(real: -.ulpOfOne, imaginary: .ulpOfOne, .ulpOfOne, .ulpOfOne),
Quaternion<T>(real: -.ulpOfOne, imaginary: -.ulpOfOne, -.ulpOfOne, -.ulpOfOne)
), (
Quaternion<T>(real: -.pi, imaginary: -.pi, .pi, -.pi),
Quaternion<T>(real: -.pi, imaginary: .pi, -.pi, .pi)
), (
Quaternion<T>(real: -.ulpOfOne, imaginary: -.ulpOfOne, .ulpOfOne, .ulpOfOne),
Quaternion<T>(real: -.ulpOfOne, imaginary: .ulpOfOne, -.ulpOfOne, -.ulpOfOne)
)
]
for (lhs, rhs) in signDifferentAxis {
XCTAssertFalse(lhs.equals(as3DTransform: rhs))
}
}
func testTransformationEquals() {
testTransformationEquals(Float32.self)
testTransformationEquals(Float64.self)
}
func testCodable<T: Real & SIMDScalar>(_ type: T.Type) throws {
let encoder = JSONEncoder()
encoder.nonConformingFloatEncodingStrategy = .convertToString(
positiveInfinity: "inf",
negativeInfinity: "-inf",
nan: "nan"
)
let decoder = JSONDecoder()
decoder.nonConformingFloatDecodingStrategy = .convertFromString(
positiveInfinity: "inf",
negativeInfinity: "-inf",
nan: "nan"
)
for expected: Quaternion<T> in [.zero, .one, .i, .infinity] {
let data = try encoder.encode(expected)
let actual = try decoder.decode(Quaternion<T>.self, from: data)
XCTAssertEqual(actual, expected)
}
}
func testCodable() throws {
try testCodable(Float32.self)
try testCodable(Float64.self)
}
}
@@ -0,0 +1,379 @@
//===--- TransformationTests.swift ----------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import XCTest
import RealModule
@testable import QuaternionModule
final class TransformationTests: XCTestCase {
// MARK: Angle/Axis
func testAngleAxis<T: Real & SIMDScalar>(_ type: T.Type) {
let xAxis = SIMD3<T>(1,0,0)
// Positive angle, positive axis
XCTAssertEqual(Quaternion<T>(angle: .pi, axis: xAxis).angle, .pi)
XCTAssertEqual(Quaternion<T>(angle: .pi, axis: xAxis).axis, xAxis)
// Negative angle, positive axis
XCTAssertEqual(Quaternion<T>(angle: -.pi, axis: xAxis).angle, .pi)
XCTAssertEqual(Quaternion<T>(angle: -.pi, axis: xAxis).axis, -xAxis)
// Positive angle, negative axis
XCTAssertEqual(Quaternion<T>(angle: .pi, axis: -xAxis).angle, .pi)
XCTAssertEqual(Quaternion<T>(angle: .pi, axis: -xAxis).axis, -xAxis)
// Negative angle, negative axis
XCTAssertEqual(Quaternion<T>(angle: -.pi, axis: -xAxis).angle, .pi)
XCTAssertEqual(Quaternion<T>(angle: -.pi, axis: -xAxis).axis, xAxis)
}
func testAngleAxis() {
testAngleAxis(Float32.self)
testAngleAxis(Float64.self)
}
func testAngleAxisMultipleOfPi<T: Real & SIMDScalar>(_ type: T.Type) {
let xAxis = SIMD3<T>(1,0,0)
// 2π
let pi2 = Quaternion<T>(angle: .pi * 2, axis: xAxis)
XCTAssertEqual(pi2.angle, .pi * 2)
XCTAssertEqual(pi2.axis, xAxis)
// 3π - axis inverted
let pi3 = Quaternion<T>(angle: .pi * 3, axis: xAxis)
XCTAssertTrue(closeEnough(pi3.angle, .pi, ulps: 1))
XCTAssertEqual(pi3.axis, -xAxis)
// 5π - axis restored
let pi5 = Quaternion<T>(angle: .pi * 5, axis: xAxis)
XCTAssertTrue(closeEnough(pi5.angle, .pi, ulps: 5))
XCTAssertEqual(pi5.axis, xAxis)
}
func testAngleAxisMultipleOfPi() {
testAngleAxisMultipleOfPi(Float32.self)
testAngleAxisMultipleOfPi(Float64.self)
}
func testAngleAxisEdgeCases<T: Real & SIMDScalar>(_ type: T.Type) {
// Zero/Zero
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .zero, axis: .zero).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .zero, axis: .zero).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .zero, angle: .zero, axis: .zero), .zero)
// Inf/Zero
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .infinity, axis: .infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .infinity, axis: .infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .zero, angle: .infinity, axis: .infinity), .zero)
// -Inf/Zero
XCTAssertTrue(Quaternion<T>(length: .zero, angle: -.infinity, axis: -.infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .zero, angle: -.infinity, axis: -.infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .zero, angle: -.infinity, axis: -.infinity), .zero)
// NaN/Zero
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .nan, axis: .nan).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .zero, angle: .nan, axis: .nan).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .zero, angle: .nan, axis: .nan), .zero)
// Zero/Inf
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .zero, axis: .zero).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .zero, axis: .zero).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .infinity, angle: .zero, axis: .zero), .infinity)
// Inf/Inf
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .infinity, axis: .infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .infinity, axis: .infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .infinity, angle: .infinity, axis: .infinity), .infinity)
// -Inf/Inf
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: -.infinity, axis: -.infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: -.infinity, axis: -.infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .infinity, angle: -.infinity, axis: -.infinity), .infinity)
// NaN/Inf
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .nan, axis: .nan).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: .infinity, angle: .nan, axis: .nan).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: .infinity, angle: .nan, axis: .nan), .infinity)
// Zero/-Inf
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .zero, axis: .zero).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .zero, axis: .zero).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: -.infinity, angle: .zero, axis: .zero), .infinity)
// Inf/-Inf
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .infinity, axis: .infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .infinity, axis: .infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: -.infinity, angle: .infinity, axis: .infinity), .infinity)
// -Inf/-Inf
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: -.infinity, axis: -.infinity).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: -.infinity, axis: -.infinity).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: -.infinity, angle: -.infinity, axis: -.infinity), .infinity)
// NaN/-Inf
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .nan, axis: .nan).axis.isNaN)
XCTAssertTrue(Quaternion<T>(length: -.infinity, angle: .nan, axis: .nan).angle.isNaN)
XCTAssertEqual(Quaternion<T>(length: -.infinity, angle: .nan, axis: .nan), .infinity)
}
func testAngleAxisEdgeCases() {
testAngleAxisEdgeCases(Float32.self)
testAngleAxisEdgeCases(Float64.self)
}
func testHalfAngleAndAxisOverflow<T: Real & SIMDScalar>(_ type: T.Type) {
let unscaled = Quaternion<T>(real: 1, imaginary: .one)
let scaled = Quaternion<T>(
real: .greatestFiniteMagnitude,
imaginary: SIMD3(repeating: .greatestFiniteMagnitude)
)
XCTAssertEqual(scaled.angle, unscaled.angle)
XCTAssertEqual(scaled.axis, unscaled.axis)
}
func testHalfAngleAndAxisOverflow() {
testHalfAngleAndAxisOverflow(Float32.self)
testHalfAngleAndAxisOverflow(Float64.self)
}
func testHalfAngleAndAxisUnderflow<T: Real & SIMDScalar>(_ type: T.Type) {
let unscaled = Quaternion<T>(real: 1, imaginary: .one)
let scaled = Quaternion<T>(
real: .leastNormalMagnitude,
imaginary: SIMD3(repeating: .leastNormalMagnitude)
)
XCTAssertEqual(scaled.angle, unscaled.angle)
XCTAssertEqual(scaled.axis, unscaled.axis)
}
func testHalfAngleAndAxisUnderflow() {
testHalfAngleAndAxisUnderflow(Float32.self)
testHalfAngleAndAxisUnderflow(Float64.self)
}
// MARK: Rotation Vector
func testRotationVector<T: Real & SIMDScalar>(_ type: T.Type) {
let vector = SIMD3<T>(0,-1,0) * .pi
XCTAssertEqual(Quaternion<T>(rotation: vector).rotationVector.x, .zero)
XCTAssertEqual(Quaternion<T>(rotation: vector).rotationVector.y, -.pi)
XCTAssertEqual(Quaternion<T>(rotation: vector).rotationVector.z, .zero)
XCTAssertEqual(Quaternion<T>(rotation: vector).axis, SIMD3(0,-1,0))
XCTAssertEqual(Quaternion<T>(rotation: vector).angle, .pi)
}
func testRotationVector() {
testRotationVector(Float32.self)
testRotationVector(Float64.self)
}
func testRotationVectorEdgeCases<T: Real & SIMDScalar>(_ type: T.Type) {
XCTAssertEqual(Quaternion<T>(rotation: .zero), .zero)
XCTAssertEqual(Quaternion<T>(rotation: .infinity), .infinity)
XCTAssertEqual(Quaternion<T>(rotation: -.infinity), .infinity)
XCTAssertTrue(Quaternion<T>(rotation: .nan).real.isNaN)
XCTAssertTrue(Quaternion<T>(rotation: .nan).imaginary.isNaN)
}
func testRotationVectorEdgeCases() {
testRotationVectorEdgeCases(Float32.self)
testRotationVectorEdgeCases(Float64.self)
}
// MARK: Polar Decomposition
func testPolarDecomposition<T: Real & SIMDScalar>(_ type: T.Type) {
let axis = SIMD3<T>(0,-1,0)
let q = Quaternion<T>(length: 5, halfAngle: .pi, axis: axis)
XCTAssertEqual(q.axis, axis)
XCTAssertEqual(q.angle, .pi * 2)
XCTAssertEqual(q.polar.length, 5)
XCTAssertEqual(q.polar.halfAngle, .pi)
XCTAssertEqual(q.polar.axis, axis)
}
func testPolarDecomposition() {
testPolarDecomposition(Float32.self)
testPolarDecomposition(Float64.self)
}
func testPolarDecompositionEdgeCases<T: Real & SIMDScalar>(_ type: T.Type) {
XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .zero, axis: .zero), .zero)
XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .infinity, axis: .infinity), .zero)
XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle:-.infinity, axis:-.infinity), .zero)
XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .nan, axis: .nan), .zero)
XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .zero, axis: .zero), .infinity)
XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .infinity, axis: .infinity), .infinity)
XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle:-.infinity, axis:-.infinity), .infinity)
XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .nan, axis: .infinity), .infinity)
XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .zero, axis: .zero), .infinity)
XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .infinity, axis: .infinity), .infinity)
XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle:-.infinity, axis:-.infinity), .infinity)
XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .nan, axis: .infinity), .infinity)
}
func testPolarDecompositionEdgeCases() {
testPolarDecompositionEdgeCases(Float32.self)
testPolarDecompositionEdgeCases(Float64.self)
}
// MARK: Act on Vector
func testActOnVector<T: Real & SIMDScalar>(_ type: T.Type) {
let vector = SIMD3<T>(1,1,1)
let xAxis = SIMD3<T>(1,0,0)
let singleAxis = Quaternion<T>(angle: .pi/2, axis: SIMD3(0, 1, 0))
XCTAssertTrue(singleAxis.act(on: xAxis).x.isApproximatelyEqual(
to: .zero, absoluteTolerance: T.ulpOfOne.squareRoot()
))
XCTAssertTrue(singleAxis.act(on: xAxis).y.isApproximatelyEqual(
to: .zero, absoluteTolerance: T.ulpOfOne.squareRoot()
))
XCTAssertEqual(singleAxis.act(on: xAxis).z, -1)
let piHalf = Quaternion<T>(angle: .pi/2, axis: xAxis)
XCTAssertTrue(closeEnough(piHalf.act(on: vector).x, 1, ulps: 0))
XCTAssertTrue(closeEnough(piHalf.act(on: vector).y, -1, ulps: 1))
XCTAssertTrue(closeEnough(piHalf.act(on: vector).z, 1, ulps: 1))
let pi = Quaternion<T>(angle: .pi, axis: xAxis)
XCTAssertTrue(closeEnough(pi.act(on: vector).x, 1, ulps: 0))
XCTAssertTrue(closeEnough(pi.act(on: vector).y, -1, ulps: 2))
XCTAssertTrue(closeEnough(pi.act(on: vector).z, -1, ulps: 2))
let twoPi = Quaternion<T>(angle: .pi * 2, axis: xAxis)
XCTAssertTrue(closeEnough(twoPi.act(on: vector).x, 1, ulps: 0))
XCTAssertTrue(closeEnough(twoPi.act(on: vector).y, 1, ulps: 3))
XCTAssertTrue(closeEnough(twoPi.act(on: vector).z, 1, ulps: 3))
}
func testActOnVector() {
testActOnVector(Float32.self)
testActOnVector(Float64.self)
}
func testActOnVectorRandom<T>(_ type: T.Type)
where T: Real, T: BinaryFloatingPoint, T: SIMDScalar,
T.Exponent: FixedWidthInteger, T.RawSignificand: FixedWidthInteger
{
// Generate random angles, axis and vector to test rotation properties
// - angle are selected from range -π to π
// - axis values are selected from -1 to 1; axis length is unity
// - vector values are selected from 10 to 10000
let inputs: [(angle: T, axis: SIMD3<T>, vector: SIMD3<T>)] = (0..<100).map { _ in
let angle = T.random(in: -.pi ... .pi)
var axis = SIMD3<T>.random(in: -1 ... 1)
axis /= .sqrt((axis * axis).sum()) // Normalize
var vector = SIMD3<T>.random(in: -1 ... 1)
vector /= .sqrt((vector * vector).sum()) // Normalize
vector *= T.random(in: 10 ... 10000) // Scale
return (angle, axis, vector)
}
for (angle, axis, vector) in inputs {
let q = Quaternion(angle: angle, axis: axis)
// The following equation in the form of v' = qvq⁻¹ is the mathmatical
// definition for how a quaternion rotates a vector (by promoting it to
// a quaternion) and goes "the full and long way" to calculate the
// rotation of vector by a quaternion. The result is used to test the
// rotation properties of "act(on:)"
let vrot = (q // q
* Quaternion(imaginary: vector) // v (pure quaternion)
* q.conjugate // q⁻¹ (as q is of unit length, q⁻¹ == q*)
).imaginary // the result is a pure quaternion with v' == imaginary
XCTAssertTrue(q.act(on: vector).x.isFinite)
XCTAssertTrue(q.act(on: vector).y.isFinite)
XCTAssertTrue(q.act(on: vector).z.isFinite)
// Test for sign equality on the components to see if the vector rotated
// to the correct quadrant and if the vector is of equal length, instead
// of testing component equality – as they are hard to compare with
// proper tolerance
XCTAssertEqual(q.act(on: vector).x.sign, vrot.x.sign)
XCTAssertEqual(q.act(on: vector).y.sign, vrot.y.sign)
XCTAssertEqual(q.act(on: vector).z.sign, vrot.z.sign)
XCTAssertTrue(closeEnough(q.act(on: vector).lengthSquared, vrot.lengthSquared, ulps: 16))
}
}
func testActOnVectorRandom() {
testActOnVectorRandom(Float32.self)
testActOnVectorRandom(Float64.self)
}
func testActOnVectorEdgeCase<T: Real & SIMDScalar>(_ type: T.Type) {
/// Test for zero, infinity
let q = Quaternion(angle: .pi, axis: SIMD3(1,0,0))
XCTAssertEqual(q.act(on: .zero), .zero)
XCTAssertEqual(q.act(on: -.zero), .zero)
XCTAssertEqual(q.act(on: .nan ), .infinity)
XCTAssertEqual(q.act(on: .infinity), .infinity)
XCTAssertEqual(q.act(on: -.infinity), .infinity)
}
func testActOnVectorEdgeCase() {
testActOnVectorEdgeCase(Float32.self)
testActOnVectorEdgeCase(Float64.self)
}
func testActOnVectorOverflow<T: Real & ExpressibleByFloatLiteral & SIMDScalar>(_ type: T.Type) {
// Create a vector (somewhat) close to greatestFiniteMagnitude on all lanes.
// We can not use greatestFiniteMagnitude here to test the careful rotation
// path, as we lose some precision in the process and it will overflow after
// rescaling the vector.
let scalar = T(
sign: .plus, exponent: T.greatestFiniteMagnitude.exponent,
significand: 1.999999
)
let closeToBounds = SIMD3<T>(repeating: scalar)
// An axis perpendicular to the vector, so all lanes change equally
let axis = SIMD3<T>(1,0,-1) / .sqrt(2)
// Perform a 180° rotation on all components
let pi = Quaternion(angle: .pi, axis: axis).act(on: closeToBounds)
// Must be finite after the rotation
XCTAssertTrue(pi.x.isFinite)
XCTAssertTrue(pi.y.isFinite)
XCTAssertTrue(pi.z.isFinite)
XCTAssertTrue(closeEnough(pi.x, -scalar, ulps: 4))
XCTAssertTrue(closeEnough(pi.y, -scalar, ulps: 4))
XCTAssertTrue(closeEnough(pi.z, -scalar, ulps: 4))
}
func testActOnVectorOverflow() {
testActOnVectorOverflow(Float32.self)
testActOnVectorOverflow(Float64.self)
}
func testActOnVectorUnderflow<T: Real & ExpressibleByFloatLiteral & SIMDScalar>(_ type: T.Type) {
let scalar = T.leastNormalMagnitude
let closeToZero = SIMD3<T>(repeating: scalar)
// An axis perpendicular to the vector, so all lanes change equally
let axis = SIMD3<T>(1,0,-1) / .sqrt(2)
// Perform a 180° rotation on all components
let pi = Quaternion(angle: .pi, axis: axis).act(on: closeToZero)
// Must be finite after the rotation
XCTAssertTrue(!pi.x.isZero)
XCTAssertTrue(!pi.y.isZero)
XCTAssertTrue(!pi.z.isZero)
XCTAssertTrue(closeEnough(pi.x, -scalar, ulps: 2))
XCTAssertTrue(closeEnough(pi.y, -scalar, ulps: 2))
XCTAssertTrue(closeEnough(pi.z, -scalar, ulps: 2))
}
func testActOnVectorUnderflow() {
testActOnVectorUnderflow(Float32.self)
testActOnVectorUnderflow(Float64.self)
}
}
// MARK: - Helper
extension SIMD3 where Scalar: FloatingPoint {
fileprivate var isNaN: Bool { x.isNaN && y.isNaN && z.isNaN }
}
// TODO: replace with approximately equals
func closeEnough<T: Real>(_ a: T, _ b: T, ulps allowed: T) -> Bool {
let scale = max(a.magnitude, b.magnitude, T.leastNormalMagnitude).ulp
return (a - b).magnitude <= allowed * scale
}