mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
Some formatting cleanup around code blocks.
This commit is contained in:
3 files changed
+16
-3
No files matched your search
@@ -50,15 +50,16 @@ However, there are good reasons to make a different choice:
|
||||
- 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 if `z` is finite.
|
||||
or `imaginary`, so it is necessarily representable.
|
||||
- The ∞-norm is the choice of established computational libraries, like
|
||||
BLAS and LAPACK.
|
||||
|
||||
@@ -113,11 +114,13 @@ 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)
|
||||
|
||||
@@ -9,23 +9,29 @@ or the result is exact.
|
||||
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.
|
||||
@@ -7,6 +7,7 @@ floating-point to allow reassociation of arithmetic and FMA formation.
|
||||
|
||||
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 + ε = ε
|
||||
@@ -16,6 +17,7 @@ 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
|
||||
@@ -26,6 +28,7 @@ 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, +)
|
||||
@@ -35,13 +38,14 @@ 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 `Relaxed.sum` and `Relaxed.product`, `Relaxed` provides the
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user