mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
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.
This commit is contained in:
10 files changed
+222
-137
No files matched your search
@@ -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,12 +32,13 @@
|
||||
/// 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 where Magnitude: AlgebraicField {
|
||||
@@ -90,10 +91,10 @@ public protocol AlgebraicField: SignedNumeric where Magnitude: AlgebraicField {
|
||||
/// ```
|
||||
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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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,
|
||||
|
||||
@@ -2,14 +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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Namespace for augmented arithmetic operations.
|
||||
public enum Augmented { }
|
||||
|
||||
extension Augmented {
|
||||
@@ -40,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,
|
||||
@@ -59,11 +60,6 @@ extension Augmented {
|
||||
/// 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"].
|
||||
///
|
||||
/// > Note:
|
||||
/// > `tail` is guaranteed to be the best approximation to the error of
|
||||
/// the sum only if `large.magnitude` >= `small.magnitude`. If this is
|
||||
@@ -72,6 +68,15 @@ extension Augmented {
|
||||
/// 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:
|
||||
///
|
||||
/// - `head` is always the IEEE 754 sum `a + b`.
|
||||
@@ -85,7 +90,14 @@ 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) {
|
||||
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)
|
||||
@@ -103,7 +115,7 @@ extension Augmented {
|
||||
/// result somewhat more efficiently. If you do not have such a static
|
||||
/// bound, you usually want to use this function instead.
|
||||
///
|
||||
/// Unlike ``product(_:_:)``, the rounding error of a sum never underflows.
|
||||
/// Unlike ``product(_:_:)``, the rounding error of `sum` never underflows.
|
||||
///
|
||||
/// This operation is sometimes called ["twoSum"].
|
||||
///
|
||||
@@ -124,7 +136,9 @@ extension Augmented {
|
||||
///
|
||||
/// ["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,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(_:)``
|
||||
@@ -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
|
||||
|
||||
@@ -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 (`sin`, `cos`, etc.) 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
|
||||
}
|
||||
@@ -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
|
||||
@@ -41,7 +41,7 @@ extension Real {
|
||||
|
||||
/// 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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user