Some formatting cleanup around code blocks.

This commit is contained in:
Stephen Canon committed 2025-08-12 13:20:29 -04:00
1 parent c3757dc266
commit 61a8b91b3e
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