mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
Compare commits
14
Commits
Quaternions
...
1.0.1
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0a23770641 | ||
|
|
d560765047 | ||
|
|
1e5cbc4e21 | ||
|
|
b4ec7556e9 | ||
|
|
79f6025798 | ||
|
|
03c5840722 | ||
|
|
ed66862a2c | ||
|
|
bcde4bc513 | ||
|
|
58f95289a0 | ||
|
|
832dac1ef8 | ||
|
|
419caa222f | ||
|
|
5a0aedbccd | ||
|
|
8e3d889b5f | ||
|
|
92f0095962 |
No files matched your search
@@ -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: "0.1.0"),
|
||||
.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
|
||||
```
|
||||
|
||||
2. Add `Numerics` as a dependency for your target:
|
||||
@@ -56,6 +56,22 @@ To use Swift Numerics in a SwiftPM project:
|
||||
|
||||
3. Add `import Numerics` in your source code.
|
||||
|
||||
## Source stability
|
||||
|
||||
The Swift Numerics package is source stable; version numbers follow [Semantic Versioning](https://semver.org).
|
||||
The public API of the `swift-numerics` package consists of non-underscored declarations that are marked either `public` or `usableFromInline` in modules re-exported by the top-level `Numerics` module, *excepting any API that involves a conformance to Differentiable (because Differentiable itself is not stable in Swift)*.
|
||||
Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
|
||||
|
||||
Note that contents of the `_NumericsShims` and `_TestSupport` modules, as well as contents of the `Tests` directory, explicitly are not public API.
|
||||
The definitions therein may therefore change at whim, and the entire module may be removed in any new release.
|
||||
If you have a use case that requires underscored operations, please raise an issue to request that they be made public API.
|
||||
|
||||
Future minor versions of the package may introduce changes to these rules as needed.
|
||||
|
||||
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.
|
||||
Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release.
|
||||
Requiring a new Swift release will only require a minor version bump.
|
||||
|
||||
## Contributing to Swift Numerics
|
||||
|
||||
Swift Numerics is a standalone library that is separate from the core Swift project, but it will sometimes act as a staging ground for APIs that will later be incorporated into the Swift Standard Library.
|
||||
|
||||
@@ -52,13 +52,31 @@ extension Complex: AdditiveArithmetic {
|
||||
// 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.
|
||||
Complex(x*a, y*a)
|
||||
}
|
||||
|
||||
/// `self` unscaled by `a`.
|
||||
@usableFromInline @_transparent
|
||||
internal func divided(by a: RealType) -> Complex {
|
||||
// See implementation notes for `multiplied` above.
|
||||
Complex(x/a, y/a)
|
||||
}
|
||||
}
|
||||
@@ -145,12 +163,12 @@ extension Complex: AlgebraicField {
|
||||
/// 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.
|
||||
/// denominator, this may sometimes be a significant performance win.
|
||||
///
|
||||
/// Typical use looks like this:
|
||||
/// A typical use case looks something like this:
|
||||
/// ```
|
||||
/// func divide<T: Real>(data: [Complex<T>], by divisor: Complex<T>) -> [Complex<T>] {
|
||||
/// // If divisor is well-scaled, use multiply by reciprocal.
|
||||
/// // If divisor is well-scaled, multiply by reciprocal.
|
||||
/// if let recip = divisor.reciprocal {
|
||||
/// return data.map { $0 * recip }
|
||||
/// }
|
||||
@@ -158,6 +176,12 @@ extension Complex: AlgebraicField {
|
||||
/// return data.map { $0 / divisor }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Error Bounds:
|
||||
///
|
||||
/// Unlike real types, when working with complex types, multiplying by the
|
||||
/// reciprocal instead of dividing cannot change the result. If the
|
||||
/// reciprocal is non-nil, the two computations are always equivalent.
|
||||
@inlinable
|
||||
public var reciprocal: Complex? {
|
||||
let recip = 1/self
|
||||
|
||||
@@ -311,13 +311,13 @@ extension Complex: ElementaryFunctions {
|
||||
// as exact head-tail products (u is guaranteed to be well scaled,
|
||||
// v may underflow, but if it does it doesn't matter, the u term is
|
||||
// all we need).
|
||||
let (a,b) = Augmented.twoProdFMA(u, u)
|
||||
let (c,d) = Augmented.twoProdFMA(v, v)
|
||||
let (a,b) = Augmented.product(u, u)
|
||||
let (c,d) = Augmented.product(v, v)
|
||||
// It would be nice if we could simply use a - 1, but unfortunately
|
||||
// we don't have a tight enough bound to guarantee that that expression
|
||||
// is exact; a may be as small as 1/4, so we could lose a single bit
|
||||
// to rounding if we did that.
|
||||
var (s,e) = Augmented.fastTwoSum(-1, a)
|
||||
var (s,e) = Augmented.sum(large: -1, small: a)
|
||||
// Now we are ready to assemble the result. If cancellation happens,
|
||||
// then |c| > |e| > |b|, |d|, so this assembly order is safe. It's
|
||||
// also possible that |c| and |d| are small, but if that happens then
|
||||
@@ -353,9 +353,9 @@ extension Complex: ElementaryFunctions {
|
||||
// So now we need to evaluate (2+x)x + y² accurately. To do this,
|
||||
// we employ augmented arithmetic; the key observation here is that
|
||||
// cancellation is only a problem when y² ≈ -(2+x)x
|
||||
let xp2 = Augmented.fastTwoSum(2, z.x) // Known that 2 > |x|.
|
||||
let a = Augmented.twoProdFMA(z.x, xp2.head)
|
||||
let y² = Augmented.twoProdFMA(z.y, z.y)
|
||||
let xp2 = Augmented.sum(large: 2, small: z.x) // Known that 2 > |x|.
|
||||
let a = Augmented.product(z.x, xp2.head)
|
||||
let y² = Augmented.product(z.y, z.y)
|
||||
let s = (a.head + y².head + a.tail + y².tail).addingProduct(z.x, xp2.tail)
|
||||
return Complex(.log(onePlus: s)/2, θ)
|
||||
}
|
||||
|
||||
@@ -47,23 +47,47 @@
|
||||
/// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
|
||||
public protocol AlgebraicField: SignedNumeric {
|
||||
|
||||
/// Replaces a with the (approximate) quotient `a/b`.
|
||||
static func /=(a: inout Self, b: Self)
|
||||
|
||||
/// The (approximate) quotient `a/b`.
|
||||
static func /(a: Self, b: Self) -> Self
|
||||
|
||||
/// The (approximate) reciprocal (multiplicative inverse) of this number,
|
||||
/// if it is representable.
|
||||
///
|
||||
/// If reciprocal is non-nil, you can replace division by self with
|
||||
/// multiplication by reciprocal and either get exact the same result
|
||||
/// (for finite fields) or approximately the same result up to a typical
|
||||
/// rounding error (for floating-point formats).
|
||||
/// If self is zero and the type has no representation for infinity (as
|
||||
/// in a typical finite field implementation), or if a reciprocal would
|
||||
/// overflow or underflow such that it cannot be accurately represented,
|
||||
/// the result is nil.
|
||||
///
|
||||
/// If self is zero, or if a reciprocal would overflow or underflow such
|
||||
/// that it cannot be accurately represented, the result is nil. Note that
|
||||
/// `.zero.reciprocal`, somewhat surprisingly, is *not* nil for `Real` or
|
||||
/// `Complex` types, because these types have an `.infinity` value that
|
||||
/// acts as the reciprocal of `.zero`.
|
||||
/// Note that `.zero.reciprocal`, somewhat surprisingly, is *not* nil
|
||||
/// for `Real` or `Complex` types, because these types have an
|
||||
/// `.infinity` value that acts as the reciprocal of `.zero`.
|
||||
///
|
||||
/// If `x.reciprocal` is non-nil, you may be able to replace division by `x`
|
||||
/// with multiplication by this value. It is not advantageous to do this
|
||||
/// for an isolated division unless it is a compile-time constant visible
|
||||
/// to the compiler, but if you are dividing many values by a single
|
||||
/// denominator, this will often be a significant performance win.
|
||||
///
|
||||
/// Note that this will slightly perturb results for some fields with
|
||||
/// approximate arithmetic, such as real types--using a normal division
|
||||
/// is generally more accurate--but no catastrophic loss of accuracy will
|
||||
/// result. For fields with exact arithmetic, or for the Complex types,
|
||||
/// the results are identical.
|
||||
///
|
||||
/// A typical use case looks something like this:
|
||||
/// ```
|
||||
/// func divide<T: AlgebraicField>(data: [T], by divisor: T) -> [T] {
|
||||
/// // If divisor is well-scaled, multiply by reciprocal.
|
||||
/// if let recip = divisor.reciprocal {
|
||||
/// return data.map { $0 * recip }
|
||||
/// }
|
||||
/// // Fallback on using division.
|
||||
/// return data.map { $0 / divisor }
|
||||
/// }
|
||||
/// ```
|
||||
var reciprocal: Self? { get }
|
||||
}
|
||||
|
||||
|
||||
@@ -9,21 +9,98 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// 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 {
|
||||
/// The product `a * b` represented as an implicit sum `head + tail`.
|
||||
///
|
||||
/// `head` is the correctly rounded value of `a*b`. If no overflow or
|
||||
/// underflow occurs, `tail` represents the rounding error incurred in
|
||||
/// computing `head`, such that the exact product is the sum of `head`
|
||||
/// and `tail` computed without rounding.
|
||||
///
|
||||
/// This operation is sometimes called "twoProd" or "twoProduct".
|
||||
///
|
||||
/// Edge Cases:
|
||||
/// -
|
||||
/// - `head` is always the IEEE 754 product `a * b`.
|
||||
/// - If `head` is not finite, `tail` is unspecified and should not be
|
||||
/// interpreted as having any meaning (it may be `NaN` or `infinity`).
|
||||
/// - When `head` is close to the underflow boundary, the rounding error
|
||||
/// may not be representable due to underflow, and `tail` will be rounded.
|
||||
/// If `head` is very small, `tail` may even be zero, even though the
|
||||
/// product is not exact.
|
||||
/// - If `head` is zero, `tail` is also a zero with unspecified sign.
|
||||
///
|
||||
/// Postconditions:
|
||||
/// -
|
||||
/// - If `head` is normal, then `abs(tail) < head.ulp`.
|
||||
/// Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
|
||||
/// - 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 twoProdFMA<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
|
||||
public static func product<T:Real>(_ 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,
|
||||
// falling back on the C math.h fma funcions, but may be slow on older x86.
|
||||
let tail = (-head).addingProduct(a, 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.product(a, b)`, the rounding error of a sum can
|
||||
/// never underflow. However, it may not be exactly representable when
|
||||
/// `a` and `b` differ widely in magnitude.
|
||||
///
|
||||
/// This operation is sometimes called "fastTwoSum".
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - a: The summand with larger magnitude.
|
||||
/// - b: The summand with smaller magnitude.
|
||||
///
|
||||
/// Preconditions:
|
||||
/// -
|
||||
/// - `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.
|
||||
///
|
||||
/// Edge Cases:
|
||||
/// -
|
||||
/// - `head` is always the IEEE 754 sum `a + b`.
|
||||
/// - If `head` is not finite, `tail` is unspecified and should not be
|
||||
/// 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`.
|
||||
@_transparent
|
||||
public static func fastTwoSum<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
|
||||
public static func sum<T:Real>(large a: T, small b: T) -> (head: T, tail: T) {
|
||||
assert(!(b.magnitude > a.magnitude))
|
||||
let head = a + b
|
||||
let tail = a - head + b
|
||||
return (head, tail)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "product")
|
||||
public static func twoProdFMA<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
|
||||
product(a, b)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "sum(large:small:)")
|
||||
public static func fastTwoSum<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
|
||||
sum(large: a, small: b)
|
||||
}
|
||||
}
|
||||
@@ -99,6 +99,53 @@ extension Real {
|
||||
return x.squareRoot()
|
||||
}
|
||||
|
||||
/// The (approximate) reciprocal (multiplicative inverse) of this number,
|
||||
/// if it is representable.
|
||||
///
|
||||
/// If `x` if finite and nonzero, and `1/x` overflows or underflows,
|
||||
/// then `x.reciprocal` is `nil`. Otherwise, `a.reciprocal` is `1/x`.
|
||||
///
|
||||
/// If `x.reciprocal` is non-nil, you may be able to replace division by `x`
|
||||
/// with multiplication by this value. It is not advantageous to do this
|
||||
/// for an isolated division unless it is a compile-time constant visible
|
||||
/// to the compiler, but if you are dividing many values by a single
|
||||
/// denominator, this will often be a significant performance win.
|
||||
///
|
||||
/// A typical use case looks something like this:
|
||||
/// ```
|
||||
/// func divide<T: Real>(data: [T], by divisor: T) -> [T] {
|
||||
/// // If divisor is well-scaled, multiply by reciprocal.
|
||||
/// if let recip = divisor.reciprocal {
|
||||
/// return data.map { $0 * recip }
|
||||
/// }
|
||||
/// // Fallback on using division.
|
||||
/// return data.map { $0 / divisor }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Error Bounds:
|
||||
///
|
||||
/// Multiplying by the reciprocal instead of dividing will slightly
|
||||
/// perturb results. For example `5.0 / 3` is 1.6666666666666667, but
|
||||
/// `5.0 * 3.reciprocal!` is 1.6666666666666665.
|
||||
///
|
||||
/// The error of a normal division is bounded by half an ulp of the
|
||||
/// result; we can derive a quick error bound for multiplication by
|
||||
/// 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,
|
||||
/// 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.
|
||||
@inlinable
|
||||
public var reciprocal: Self? {
|
||||
let recip = 1/self
|
||||
|
||||
Reference in new issue
Block a user