69 Commits
Author SHA1 Message Date
Stephen Canon eb58826429 Merge pull request #362 from charles-zablit/cz/cmake/cmp0157
[CMake] Require CMake 3.29 to enable CMP0157
2026-11-18 11:01:42 -05:00
Charles Zablit 02deda5402 [CMake] Require CMake 3.29 to enable CMP0157 2026-11-06 12:05:41 +00:00
Stephen Canon 669f618518 Merge pull request #360 from stephentyrone/use-builtin-module-for-builtins
Enable and include Builtin module to pickup fadd/fmul_relaxed.
2026-10-11 17:05:59 -04:00
Stephen Canon 673c0f6c3d Enable and include Builtin module to pickup fadd/fmul_relaxed. 2026-10-11 17:00:36 -04:00
Stephen Canon 20fe3d7d8e Merge pull request #358 from stephentyrone/adopt-builtin-relaxed-ops
Use BuiltinRelaxedFP ops instead of C shims when they're available.
2026-10-09 15:31:22 -04:00
Stephen Canon 69890e3639 Use BuiltinRelaxedFP ops instead of C shims when they're available.
There used to not be any way to attach reassociate or contract flags to fadd/fmul from Swift, which meant that we had to use inline C shims to accomplish this. But I added some Builtins to Swift, so now we don't need C to do this any longer.
2026-10-08 11:24:58 -04:00
Stephen Canon 8a65bea94b Merge pull request #336 from kkebo/fix-freebsd-tests
Skip Float80 overflow/underflow tests on FreeBSD
2026-10-08 11:15:15 -04:00
Stephen Canon 9f745b7c9b Merge pull request #355 from reginaldalfret/docs/approximate-equality
docs: add dedicated documentation for ApproximateEquality
2026-10-08 10:44:08 -04:00
reginaldalfret 8630961065 docs(ApproximateEquality): address maintainer review feedback on abstraction and tolerances
Signed-off-by: reginaldalfret <reginaldalfret@gmail.com>
2026-10-08 17:46:40 +05:30
reginaldalfret 0d1ccaf0d3 docs: add dedicated documentation for ApproximateEquality (#153)
Add a comprehensive DocC guide for ApproximateEquality covering:
- Background and motivation for approximate equality in floating-point math
- Relative and absolute tolerance guidelines and formulas
- Special value handling (NaN, infinities, signed zeroes)
- Custom norms with AdditiveArithmetic
- Mathematical properties (non-transitivity and why not to use for Equatable)

Also update RealModule.md to link to the DocC article and restore the
Approximate equality section with a link in Sources/RealModule/README.md.

Resolves #153.

Signed-off-by: reginaldalfret <reginaldalfret@gmail.com>
2026-10-01 18:56:12 +05:30
Stephen Canon a7d826ead0 Merge pull request #352 from stephentyrone/fix-cosh-sinh-signs
Fix signs of cosh and sinh near the overflow boundary.
2026-09-10 10:53:41 -04:00
Stephen Canon 20a774f1a6 Merge pull request #351 from stephentyrone/recip-documentation
Relax documented behavior of Complex.reciprocal
2026-09-10 10:30:39 -04:00
Stephen Canon c2d05532d3 Fix signs of cosh and sinh near the overflow boundary.
Resovles https://github.com/apple/swift-numerics/issues/347
2026-09-10 10:27:51 -04:00
Stephen Canon 3b272b08af a word. 2026-09-10 10:09:49 -04:00
Stephen Canon bb7b69501f Relax documented behavior of Complex.reciprocal
In cases of underflow, multiplication by reciprocal may not be the same as division. Document this, rather than tightening the behavior, because it's still about as good as multiplication by reciprocal would be for a Real type.
2026-09-10 10:07:01 -04:00
Stephen Canon 738b0cdb23 Merge pull request #345 from kadyrbekovhamit-cyber/fix-rounding-documentation-examples
Replace nonexistent stochastic-rounding examples
2026-09-10 09:45:04 -04:00
Stephen Canon ee167adfea Merge pull request #350 from pkubaj/add-freebsd-ppc64
cmake: recognize FreeBSD powerpc64le/powerpc64 in get_swift_host_arch
2026-09-10 09:44:45 -04:00
Stephen Canon a6c13f7de8 Merge pull request #348 from kadyrbekovhamit-cyber/patch-2
Correct toNearestOrZero shift example
2026-09-10 09:44:24 -04:00
Piotr Kubaj ea5d4cf4a5 cmake: recognize FreeBSD powerpc64le/powerpc64 in get_swift_host_arch
get_swift_host_arch() maps CMAKE_SYSTEM_PROCESSOR to a Swift architecture
name using the Linux spellings (ppc64le, ppc64).  On FreeBSD the
processor is reported as powerpc64le / powerpc64, so the PowerPC host was
falling through to the "Unrecognized architecture" error.  Accept the
FreeBSD spellings alongside the existing ones.
2026-09-08 09:25:01 +02:00
kadyrbekovhamit-cyber 15eab09844 Correct toNearestOrZero shift example
5 / 2 is exactly halfway between 2 and 3. The toNearestOrZero tie-breaking rule selects 2, the value with smaller magnitude.
2026-09-05 14:08:17 +05:00
kadyrbekovhamit-cyber 2d92c04e96 Leave existing tie-to-zero fix to PR 341 2026-09-04 22:37:41 +05:00
kadyrbekovhamit-cyber aa5684820a Correct rounding documentation examples 2026-09-04 21:30:38 +05:00
Kenta Kubo 63dc00f053 [CI] Enable FreeBSD testing 2026-05-27 22:02:24 +09:00
Kenta Kubo 1f6c508c58 Skip Float80 overflow/underflow tests on FreeBSD
This is a workaround for FreeBSD's bug.
2026-02-07 20:30:49 +09:00
Stephen Canon 899af71c02 Merge pull request #328 from stephentyrone/complex-divide-docs
Added some notes on complex division.
2026-01-28 20:58:00 -05:00
Stephen Canon 178f513ce6 Merge pull request #316 from stephentyrone/enable-macos-github
Enable macos checks via github workflows.
2025-11-13 18:34:22 -05:00
Stephen Canon 3403d50630 Merge branch 'main' into enable-macos-github 2025-11-13 16:09:08 -05:00
Stephen Canon 167fe9b22a Merge pull request #332 from incertum/chore/workflow-permissions
chore: restrict GitHub workflow permissions - future-proof
2025-10-27 17:08:09 -04:00
Melissa Kilby 50552bf86b chore: restrict GitHub workflow permissions - future-proof
Signed-off-by: Melissa Kilby <mkilby@apple.com>
2025-10-17 16:12:07 -07:00
Stephen Canon 18274b1caa Merge pull request #330 from ebariaux/main
Support Embedded Swift
2025-09-25 11:15:42 -04:00
Eric Bariaux 894008997c Ensure compatibility with Swift versions below 6 2025-09-25 12:41:14 +02:00
Eric Bariaux d46e20b4c5 String(reflecting:) not available in Embedded mode.
And Real does not conform to CustomDebugStringConvertible, so can't access debugDescription property directly on x and y
2025-09-18 07:21:15 +02:00
Eric Bariaux 6a7cf593bf Codable not available right-now in Embedded mode 2025-09-18 07:20:19 +02:00
Stephen Canon cbdb286797 Added some notes on complex division. 2025-08-20 19:18:41 -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 30074a3846 Enable macos checks via github workflows. 2025-08-08 13:55:13 -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
45 changed files with 1355 additions and 344 deletions

No files matched your search

+9
View File
@@ -1,5 +1,8 @@
name: Pull request
permissions:
contents: read
on:
pull_request:
types: [opened, reopened, synchronize]
@@ -8,6 +11,12 @@ jobs:
tests:
name: Test
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
with:
enable_macos_checks: true
windows_exclude_swift_versions: '[{"swift_version": "5.9"}]'
enable_wasm_sdk_build: true
wasm_sdk_build_command: swift build --target Numerics
enable_freebsd_checks: true
soundness:
name: Soundness
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+1 -1
View File
@@ -7,7 +7,7 @@ Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
#]]
cmake_minimum_required(VERSION 3.16)
cmake_minimum_required(VERSION 3.29)
project(swift-numerics
LANGUAGES Swift)
+3
View File
@@ -47,6 +47,9 @@ let package = Package(
name: "RealModule",
dependencies: ["_NumericsShims"],
exclude: excludedFilenames,
swiftSettings: [
.enableExperimentalFeature("BuiltinModule")
],
linkerSettings: [
.linkedLibrary("m", .when(platforms: [.linux, .android]))
]
@@ -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)
@@ -153,9 +155,17 @@ extension Complex: AlgebraicField {
///
/// 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.
/// Unlike real types, with Complex types, _if no underflow occurs in
/// computing the reciprocal_, replacing division with multiplication by
/// this value does not perturb the result. Note that this condition is
/// not the same as `reciprocal` returning a non-nil value. If the `real`
/// and `imaginary` components are poorly scaled with respect to each other,
/// one component of `reciprocal` may underflow while the other component
/// is normal, resulting in a non-nil `reciprocal`.
///
/// We return a non-nil reciprocal in this case because it still
/// satisfies the accuracy expectations of `reciprocal` in any Complex
/// norm (but not componentwise).
@inlinable
public var reciprocal: Complex? {
let recip = 1/self
+7 -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
@@ -12,6 +12,9 @@
import RealModule
// FloatingPoint does not refine Codable, so this is a conditional conformance.
#if compiler(>=6.0)
@_unavailableInEmbedded
#endif
extension Complex: Decodable where RealType: Decodable {
public init(from decoder: Decoder) throws {
var unkeyedContainer = try decoder.unkeyedContainer()
@@ -21,6 +24,9 @@ extension Complex: Decodable where RealType: Decodable {
}
}
#if compiler(>=6.0)
@_unavailableInEmbedded
#endif
extension Complex: Encodable where RealType: Encodable {
public func encode(to encoder: Encoder) throws {
var unkeyedContainer = encoder.unkeyedContainer()
@@ -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
@@ -141,7 +141,10 @@ extension Complex: ElementaryFunctions {
public static func cosh(_ z: Complex) -> Complex {
guard z.isFinite else { return z }
guard z.x.magnitude < -RealType.log(.ulpOfOne) else {
let phase = Complex(RealType.cos(z.y), RealType.sin(z.y))
let phase = Complex(
RealType.cos(z.y),
RealType(signOf: z.x, magnitudeOf: 1) * RealType.sin(z.y)
)
let firstScale = RealType.exp(z.x.magnitude/2)
let secondScale = firstScale/2
return phase.multiplied(by: firstScale).multiplied(by: secondScale)
@@ -171,9 +174,12 @@ extension Complex: ElementaryFunctions {
public static func sinh(_ z: Complex) -> Complex {
guard z.isFinite else { return z }
guard z.x.magnitude < -RealType.log(.ulpOfOne) else {
let phase = Complex(RealType.cos(z.y), RealType.sin(z.y))
let phase = Complex(
RealType(signOf: z.x, magnitudeOf: RealType.cos(z.y)),
RealType.sin(z.y)
)
let firstScale = RealType.exp(z.x.magnitude/2)
let secondScale = RealType(signOf: z.x, magnitudeOf: firstScale/2)
let secondScale = firstScale/2
return phase.multiplied(by: firstScale).multiplied(by: secondScale)
}
return Complex(
+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
@@ -16,6 +16,9 @@ extension Complex: CustomStringConvertible {
}
}
#if compiler(>=6.0)
@_unavailableInEmbedded
#endif
extension Complex: CustomDebugStringConvertible {
public var debugDescription: String {
"Complex<\(RealType.self)>(\(String(reflecting: x)), \(String(reflecting: y)))"
+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,140 @@
# Notes on Complex Division
A discussion of the algorithms used to implement complex division
## Overview
How does compute the quotient of two complex numbers z/w? The naïve schoolbook
answer is to turn it into complex multiplication by scaling both numerator and
denominator by the conjugate of w: z/w = (zw̅)/(ww̅) = (zw̅)/|w|². Translated
directly into swift, this expression would become:
```swift
extension Complex {
func naïveDivision(_ z: Complex, _ w: Complex) -> Complex {
(z * w.conjugate).divded(by: w.lengthSquared)
}
}
```
If both z and w are both "well-scaled" (i.e. their exponents are neither very
large nor very small), then this expression works reasonably well when
evaluated in floating-point. Cancellation may occur in the computation of
either the real or the imaginary part of the zw̅ term, but not in both
simultaneously, so the relative error in any vector norm is bounded by a
small multiple of machine epsilon.
However, if z or w is not well-scaled, then either zw̅ or |w|² or both may
underflow or overflow, even when the actual quotient may be perfectly
representable. For example, if we have
```swift
let a: Float = 1.84467441E+19 // large, but not outrageously large
let z = Complex(a, a)
let w = z
```
then both `(z * w.conjugate)` and `w.lengthSquared` overflow, and the result
of `naïveDivision` is `(NaN, NaN)` even though the actual mathematical quotient
is 1.
At least `(NaN, NaN)` is obviously wrong; when intermediate results underflow
instead of overflow, we can instead get bogus results that are not obvious at
all. For example:
```swift
let z = Complex<Float>(imaginary: 6.6174449e-24)
let w = Complex<Float>(5.29395592e-23, 3.97046694e-23)
let q = naïveDivision(z, w)
```
`q` is computed as `(0.666666686, 0.666666686)`, which looks like a reasonable
result, but the exact `z/w` would be `(0.6, 0.8)`; both the phase and magnitude
of the computed result have large errors, and there is no indication that
anything went wrong.
## Complex division in Swift Numerics
### Goals
Programming languages and libraries have developed a variety of approaches to
handle this problem. Swift Numerics' approach is somewhat novel, so I will
first lay out the considerations that lead us to it.
1. Division should be reasonably fast, and permit compiler optimizations that
make it faster. So long as all inputs are well-scaled, it should not be
much slower than multiplication.
2. Division should have the same error characteristics as multiplication;
componentwise error bounds and correct rounding are non-goals. Good error
bounds in a complex norm are what matters.
3. Division should not be any more sensitive to undue overflow or underflow
than multiplication is (i.e. it is OK for results very near the boundaries
to overflow or underflow even though the exact result would be
representable, but results that are far from those boundaries should always
be computed with good accuracy).
### Fast path
These considerations lead us to a first draft of our implementation; since we
want division to be roughly like multiplication, we will "simply" turn it into
a multiplication via the naïve formula:
```swift
public static func /(z: Complex, w: Complex) -> Complex {
let lenSq = w.lengthSquared
guard lenSq.isNormal else { /* naive formula will not work */ }
return z * w.conjugate.divided(by: lenSq)
}
```
if `lenSq` can be computed without overflow or underflow, then
`w.conjugate.divided(by: lenSq)` is a (rounded) reciprocal `1/w`, and so
multiplying that by `z` satisfies the goals that we laid out above. Note
in particular that if we are dividing multiple values by a single divisor,
the reciprocal is a constant, and this check only has to happen once.
That leaves us just needing to figure out what to do when the reciprocal
is not well-scaled.
### Slow path
When an approximate reciprocal for the divisor is not representable, we use
a scaling algorithm adapted from Doug Priest's "Efficient Scaling for
Complex Division". In hand-wavy form, Priest's idea is:
1. choose a scale factor s ~ |w|^(-¾)
2. let wʹ ← sw
2. let zʹ ← sz
Note that we _can_ compute a reciprocal for wʹ without overflow or underflow,
because |wʹ| ~ |w|^(¼), so |wʹ²| ~ |w|^(½) and so |w̅ʹ/wʹ²| ~ |w|^(-¼).¹
To compute z/w, we compute zʹ/wʹ. sz might overflow or underflow, but only
if the final computation would overflow or underflow anyway. This is because
division by w is a dilation combined with a rotation; because |w| is bounded
away from 1, the multiplication by s is a dilation if and only if division
by w is also dilation (this is where we diverge from Priest; because he
doesn't have a fast-path for well-scaled w, he has to handle this case
carefully).
Like Priest, we arrange for s to be a power of the radix with the desired
scale, which makes the computation of wʹ and zʹ exact (unless zʹ over- or
underflows). This achieves one more desirable property: barring underflow,
rescaling both w and z by the radix does not change results when we move
between the fast and slow algorithms.
Instead of `zʹ/wʹ = zʹ(w̅ʹ/|wʹ|²)`, Priest uses `(zw″)/|wʹ|²`. There isn't
a strong reason to favor one or the other numerically, but our formulation
lets us preserve `z/w = z * w.reciprocal` under scaling by powers of the
radix (up to the underflow boundary), which is somewhat nice to have, and
allows us to extract a little bit more ILP in some cases.
----
### Notes
¹ This analysis fails for types like Float16 where the number of
significand bits is on the order of the greatest exponent because the desired
s may not be representable if w is subnormal. Note that the problem is _only_
in the representation of s, so we can handle this case by rescaling in two
steps.
@@ -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:)`
+1 -1
View File
@@ -163,7 +163,7 @@ public enum RoundingRule {
/// - `(-4).divided(by: 3, rounding: .toNearestOrZero)`
/// is `-1`, because –4/3 = –1.3̅ is closer to –1 than it is to –2.
///
/// - `5.shifted(rightBy: 1, rounding: .toNearestOrZero)` is `3`,
/// - `5.shifted(rightBy: 1, rounding: .toNearestOrZero)` is `2`,
/// because 5/2 = 2.5 is equally close to 2 and 3, and 2 is closer to zero.
case toNearestOrZero
@@ -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:
///
@@ -27,9 +27,8 @@ extension BinaryInteger {
/// // is odd.
/// 3.shifted(rightBy: 1, rounding: .toOdd)
///
/// // 7/4 = 1.75, so the result is 1 with probability 1/4, or 2
/// // with probability 3/4.
/// 7.shifted(rightBy: 2, rounding: .stochastically)
/// // 6/4 = 1.5, so the tie is broken in favor of the even value 2.
/// 6.shifted(rightBy: 2, rounding: .toNearestOrEven)
///
/// // 4/4 is exactly 1, so this does not trap.
/// 4.shifted(rightBy: 2, rounding: .requireExact)
@@ -138,8 +137,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:
///
@@ -153,9 +152,8 @@ extension BinaryInteger {
/// // is odd.
/// 3.shifted(rightBy: 1, rounding: .toOdd)
///
/// // 7/4 = 1.75, so the result is 1 with probability 1/4, or 2
/// // with probability 3/4.
/// 7.shifted(rightBy: 2, rounding: .stochastically)
/// // 6/4 = 1.5, so the tie is broken in favor of the even value 2.
/// 6.shifted(rightBy: 2, rounding: .toNearestOrEven)
///
/// // 4/4 is exactly 1, so this does not trap.
/// 4.shifted(rightBy: 2, rounding: .requireExact)
+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,228 @@
# Approximate Equality
Test whether two values agree within a specified tolerance.
## Overview
In numerical computing, mathematical equality often diverges from computed
equality. Rounding in floating-point arithmetic is one common cause, but many
nontrivial numerical algorithms also have inherent truncation or discretization
errors, and empirical measurements carry uncertainty to begin with. In these
scenarios, exact equality (`==`) may be too strict or inappropriate, and an
approximate equality comparison is needed instead. Conversely, exact equality
remains entirely appropriate when checking for identical values, sentinel states,
or integers.
`RealModule` provides a family of `isApproximatelyEqual` methods that test
whether two values are within a tolerance of one another. They are available
on any `Numeric` type whose `Magnitude` is a `FloatingPoint` type (including
`Float`, `Double`, and `Complex`), and a more general form is available on any
`AdditiveArithmetic` type for which you can supply a norm.
```swift
import Numerics
let x = 0.1 + 0.2
x == 0.3 // false
x.isApproximatelyEqual(to: 0.3) // true
```
### Comparing non-Numeric types with a custom norm
The approximate equality API is not limited to scalar numbers or `Numeric`
types. Any type conforming to `AdditiveArithmetic` can be compared once you
supply a suitable norm function mapping differences to a `FloatingPoint`
magnitude.
For example, consider a 2D geometric vector or point type representing spatial
displacements:
```swift
struct Vector2D: AdditiveArithmetic, Equatable {
var x: Double
var y: Double
static var zero: Vector2D {
Vector2D(x: 0, y: 0)
}
static func + (lhs: Vector2D, rhs: Vector2D) -> Vector2D {
Vector2D(x: lhs.x + rhs.x, y: lhs.y + rhs.y)
}
static func - (lhs: Vector2D, rhs: Vector2D) -> Vector2D {
Vector2D(x: lhs.x - rhs.x, y: lhs.y - rhs.y)
}
}
// Compare vectors using the Euclidean distance (L2 norm):
let v1 = Vector2D(x: 1.0, y: 2.0)
let v2 = Vector2D(x: 1.000000001, y: 1.999999999)
let areClose = v1.isApproximatelyEqual(
to: v2,
absoluteTolerance: 1e-6,
norm: { v in (v.x * v.x + v.y * v.y).squareRoot() }
)
// areClose == true
```
Because `Vector2D` is not `Numeric` (it does not define multiplication of
vectors to produce a vector), it cannot use the standard `Numeric.isApproximatelyEqual`
overload. However, because vector subtraction forms a difference vector in an
additive space, the general `AdditiveArithmetic` overload evaluates the custom
norm directly.
### Choosing a tolerance
The simplest method uses a _relative_ tolerance:
```swift
public func isApproximatelyEqual(
to other: Self,
relativeTolerance: Magnitude = Magnitude.ulpOfOne.squareRoot(),
norm: (Self) -> Magnitude = \.magnitude
) -> Bool
```
Two finite values compare equal when
```
norm(self - other) <= relativeTolerance * scale
```
where `scale` is `max(norm(self), norm(other), .leastNormalMagnitude)`.
Because the bound grows with the size of the operands, a single relative
tolerance works across a wide range of magnitudes.
The default tolerance is `.ulpOfOne.squareRoot()`, which corresponds to
expecting about half of the available digits in the result to be correct. This
is the usual rule of thumb in numerical analysis when you have no other
information about the computation, but it is not appropriate for every use
case, so you should pass an explicit value when you can estimate how much error
your computation introduces.
#### Absolute versus relative tolerance
A relative tolerance scales with the magnitude of the operands, making it
effective across numbers of very small or very large scale. However, a pure
relative tolerance fails when comparing against zero or numbers much smaller
than the surrounding computation, because `scale` approaches zero and shrinks
the allowable difference to near zero.
To handle values near zero, use the overload that also accepts an _absolute_
tolerance:
```swift
public func isApproximatelyEqual(
to other: Self,
absoluteTolerance: Magnitude,
relativeTolerance: Magnitude = 0
) -> Bool
```
Two finite values compare equal when _either_ the absolute or the relative
bound is satisfied:
```
(self - other).magnitude <= absoluteTolerance
```
or
```
(self - other).magnitude <= relativeTolerance * scale
```
where `scale` is `max(self.magnitude, other.magnitude)`.
When choosing values:
- Use **relative tolerance** when the allowed error is proportional to the
magnitude of the values being computed (e.g. general floating-point arithmetic).
- Use **absolute tolerance** when values can be near zero, or when the error
is independent of the scale of the inputs (e.g. fixed measurement resolution).
- Supplying both allows the absolute tolerance to govern comparisons near
zero, while the relative tolerance takes over once values grow beyond
`absoluteTolerance / relativeTolerance`.
Setting `absoluteTolerance == relativeTolerance` is typically appropriate only
when values are expected to lie on an integral or unit-spaced grid due to
algorithmic considerations (where `1.0` represents the base unit scale). For
general computations, the two tolerances should be chosen independently based on
the scale of the problem and the expected precision.
### Special values
The comparison follows the same conventions as `FloatingPoint`:
```swift
Double.nan.isApproximatelyEqual(to: .nan) // false
Double.infinity.isApproximatelyEqual(to: .infinity) // true
(0.0).isApproximatelyEqual(to: -0.0) // true
```
A NaN is never approximately equal to anything, including itself, and a finite
value is never approximately equal to an infinity. Equal values always compare
approximately equal regardless of the tolerance, so infinities compare equal to
themselves and `+0` compares equal to `-0`.
### Comparing other types with a custom norm
The methods above measure the difference between two values using the
`.magnitude` property. Sometimes you want to use a different
[norm](https://en.wikipedia.org/wiki/Norm_(mathematics)). The most general
overload, defined on `AdditiveArithmetic`, lets you supply one:
```swift
public func isApproximatelyEqual<Magnitude>(
to other: Self,
absoluteTolerance: Magnitude,
relativeTolerance: Magnitude = 0,
norm: (Self) -> Magnitude
) -> Bool
where Magnitude: FloatingPoint
```
#### Complex magnitude vs other norms
For complex numbers, the default norm is `\.magnitude`, which computes the
infinity-norm (`max(abs(real), abs(imaginary))`).
A major numerical advantage of `\.magnitude` for complex values is that it is
finite and non-zero for any finite non-zero value:
- Unlike Euclidean length (`\.length`, $\sqrt{x^2 + y^2}$), which can overflow
to infinity if $x^2 + y^2$ exceeds the maximum representable finite value or
underflow if both components are tiny, `\.magnitude` never overflows or underflows
for finite numbers.
- It avoids intermediate squaring, square roots, or the complex scaling logic of
`hypot`, making it robust even when handling very poorly scaled values.
If you specifically need to test whether a complex number lies inside a circular
disk of radius `0.001` centered at `1 + 0i` rather than a square box, you can
pass the Euclidean length as the norm:
```swift
import ComplexModule
z.isApproximatelyEqual(
to: 1,
absoluteTolerance: 0.001,
norm: \.length
)
```
## Mathematical properties
For any fixed tolerance, approximate equality is _reflexive_ on
non-exceptional values and _symmetric_: if `a` is approximately equal to `b`,
then `b` is approximately equal to `a`.
It is **not transitive**. `a` can be approximately equal to `b`, and `b` to
`c`, while `a` and `c` differ by more than the tolerance. Approximate equality
is therefore **not** an equivalence relation, even when restricted to
non-exceptional values. For this reason you must not use it to implement a
conformance to `Equatable`: doing so would violate the invariants that generic
code written against `Equatable` relies on.
For any point `a`, the set of values that compare approximately equal to `a`
is _convex_ (under the assumption that `norm` implements a valid norm).
@@ -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,32 @@
# ``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.
``RealModule`` also provides `isApproximatelyEqual` methods for comparing
floating-point values up to a tolerance, which is almost always what you want
instead of an exact `==` comparison. See <doc:ApproximateEquality> for details.
@@ -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.
+10 -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
@@ -10,6 +10,7 @@
//===----------------------------------------------------------------------===//
import _NumericsShims
import Builtin
extension Double: Real {
@_transparent
@@ -222,11 +223,19 @@ extension Double: Real {
@_transparent
public static func _relaxedAdd(_ a: Double, _ b: Double) -> Double {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Double(Builtin.fadd_relaxed_FPIEEE64(a._value, b._value))
#else
_numerics_relaxed_add(a, b)
#endif
}
@_transparent
public static func _relaxedMul(_ a: Double, _ b: Double) -> Double {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Double(Builtin.fmul_relaxed_FPIEEE64(a._value, b._value))
#else
_numerics_relaxed_mul(a, b)
#endif
}
}
+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
}
+9
View File
@@ -10,6 +10,7 @@
//===----------------------------------------------------------------------===//
import _NumericsShims
import Builtin
extension Float: Real {
@_transparent
@@ -195,11 +196,19 @@ extension Float: Real {
@_transparent
public static func _relaxedAdd(_ a: Float, _ b: Float) -> Float {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float(Builtin.fadd_relaxed_FPIEEE32(a._value, b._value))
#else
_numerics_relaxed_addf(a, b)
#endif
}
@_transparent
public static func _relaxedMul(_ a: Float, _ b: Float) -> Float {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float(Builtin.fmul_relaxed_FPIEEE32(a._value, b._value))
#else
_numerics_relaxed_mulf(a, b)
#endif
}
}
+14 -3
View File
@@ -10,6 +10,7 @@
//===----------------------------------------------------------------------===//
import _NumericsShims
import Builtin
// Float16 is only available on macOS when targeting arm64.
#if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
@@ -173,17 +174,27 @@ 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) || hasFeature(BuiltinRelaxedFP)
// WASM doesn't have _Float16 on the C side, so we can't define the C hooks
// that these use. However, if we have BuiltinRelaxedFP we can use builtins
// to do this directly without needing the C hooks.
@_transparent
public static func _relaxedAdd(_ a: Float16, _ b: Float16) -> Float16 {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float16(Builtin.fadd_relaxed_FPIEEE16(a._value, b._value))
#else
_numerics_relaxed_addf16(a, b)
#endif
}
@_transparent
public static func _relaxedMul(_ a: Float16, _ b: Float16) -> Float16 {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float16(Builtin.fmul_relaxed_FPIEEE16(a._value, b._value))
#else
_numerics_relaxed_mulf16(a, b)
#endif
}
#endif
}
+9
View File
@@ -10,6 +10,7 @@
//===----------------------------------------------------------------------===//
import _NumericsShims
import Builtin
// Restrict extension to platforms for which Float80 exists.
#if (arch(i386) || arch(x86_64)) && !os(Windows) && !os(Android)
@@ -168,12 +169,20 @@ extension Float80: Real {
@_transparent
public static func _relaxedAdd(_ a: Float80, _ b: Float80) -> Float80 {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float80(Builtin.fadd_relaxed_FPIEEE80(a._value, b._value))
#else
_numerics_relaxed_addl(a, b)
#endif
}
@_transparent
public static func _relaxedMul(_ a: Float80, _ b: Float80) -> Float80 {
#if hasFeature(BuiltinRelaxedFP) // Swift 6.5 and later
Float80(Builtin.fmul_relaxed_FPIEEE80(a._value, b._value))
#else
_numerics_relaxed_mull(a, b)
#endif
}
}
#endif
+21
View File
@@ -68,9 +68,30 @@ This gives us an implementation that works for `Float`, `Double`, and `Float80`
When new basic floating-point types are added to Swift, like `Float16` or `Float128`, it will work for them as well.
Not having this protocol is a significant missing feature for numerical computing in Swift, and I'm really looking forward to seeing what people do with it.
## Approximate equality
`RealModule` provides a family of `isApproximatelyEqual` methods that test
whether two values agree up to a relative or absolute tolerance:
```swift
import Numerics
let x = 0.1 + 0.2
x == 0.3 // false
x.isApproximatelyEqual(to: 0.3) // true
```
These methods are available on any `Numeric` type whose `Magnitude` is a
`FloatingPoint` type, with a more general form on `AdditiveArithmetic` that
takes a custom norm.
See the [Approximate Equality][ApproximateEquality] article for a discussion of
how to choose a tolerance, how special values are handled, and why approximate
equality must not be used to implement `Equatable`.
### Dependencies:
- The C standard math library (`libm`) via the `_NumericsShims` target.
[ApproximateEquality]: Documentation.docc/ApproximateEquality.md
[ErrorFunction]: https://en.wikipedia.org/wiki/Error_function
[GammaFunction]: https://en.wikipedia.org/wiki/Gamma_function
[SE-0246]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0246-mathable.md
+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) {
@@ -180,7 +180,13 @@ final class ElementaryFunctionTests: XCTestCase {
XCTAssert(huge.imaginary.isApproximatelyEqual(to: mag))
huge = Complex<T>.cosh(Complex(-x, .pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: -mag))
huge = Complex<T>.cosh(Complex(-x, -.pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: mag))
huge = Complex<T>.cosh(Complex(x, -.pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: -mag))
}
func testSinh<T: Real & FixedWidthFloatingPoint>(_ type: T.Type) {
@@ -212,6 +218,12 @@ final class ElementaryFunctionTests: XCTestCase {
XCTAssert(huge.imaginary.isApproximatelyEqual(to: mag))
huge = Complex<T>.sinh(Complex(-x, .pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: -mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: mag))
huge = Complex<T>.sinh(Complex(-x, -.pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: -mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: -mag))
huge = Complex<T>.sinh(Complex(x, -.pi/4))
XCTAssert(huge.real.isApproximatelyEqual(to: mag))
XCTAssert(huge.imaginary.isApproximatelyEqual(to: -mag))
// For randomly-chosen well-scaled finite values, we expect to have
// cosh² - sinh² ≈ 1. Note that this test would break down due to
@@ -31,6 +31,11 @@ internal extension Real where Self: FixedWidthFloatingPoint {
XCTAssertEqual(Self.pow(-1, Int.max), -1)
XCTAssertEqual(Self.pow(-1, -Int.max), -1)
XCTAssertEqual(Self.pow(-1, Int.min), 1)
}
static func testIntegerExponentOverflowAndUnderflow() {
// TODO: replace with seedable generator, print seed.
var g = SystemRandomNumberGenerator()
// Generate some random test values that definitely overflow or
// underflow; we want to be sure that we get the right ±0 or ±∞
// result.
@@ -82,6 +87,7 @@ internal extension Real where Self: FixedWidthFloatingPoint {
extension Float16 {
static func testIntegerExponent() {
testIntegerExponentCommon()
testIntegerExponentOverflowAndUnderflow()
testIntegerExponentDoubleAndSmaller()
let u = Float16(1).nextUp
let d = Float16(1).nextDown
@@ -109,6 +115,7 @@ extension Float16 {
extension Float {
static func testIntegerExponent() {
testIntegerExponentCommon()
testIntegerExponentOverflowAndUnderflow()
testIntegerExponentDoubleAndSmaller()
let u = Float(1).nextUp
let d = Float(1).nextDown
@@ -135,6 +142,7 @@ extension Float {
extension Double {
static func testIntegerExponent() {
testIntegerExponentCommon()
testIntegerExponentOverflowAndUnderflow()
// Following tests only make sense (and are only necessary) on 64b platforms.
#if arch(arm64) || arch(x86_64)
testIntegerExponentDoubleAndSmaller()
@@ -193,6 +201,10 @@ final class IntegerExponentTests: XCTestCase {
#if (arch(i386) || arch(x86_64)) && !os(Windows) && !os(Android)
func testFloat80() {
Float80.testIntegerExponentCommon()
// FreeBSD's powl(3) has a bug where a minus sign is not perserved on overflow/underflow.
#if !os(FreeBSD)
Float80.testIntegerExponentOverflowAndUnderflow()
#endif
}
#endif
}
+2 -2
View File
@@ -23,9 +23,9 @@ function(get_swift_host_arch result_var_name)
else()
set("${result_var_name}" "aarch64" PARENT_SCOPE)
endif()
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64")
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64" OR "${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "powerpc64")
set("${result_var_name}" "powerpc64" PARENT_SCOPE)
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64le")
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64le" OR "${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "powerpc64le")
set("${result_var_name}" "powerpc64le" PARENT_SCOPE)
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "s390x")
set("${result_var_name}" "s390x" PARENT_SCOPE)