//===--- ElementaryFunctions.swift ----------------------------*- swift -*-===// // // This source file is part of the Swift Numerics open source project // // Copyright (c) 2019 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`. /// /// [wiki]: https://en.wikipedia.org/wiki/Exponential_function static func exp(_ x: Self) -> Self /// exp(x) - 1, computed in such a way as to maintain accuracy for small x. /// /// When `x` is close to zero, the expression `.exp(x) - 1` suffers from /// 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` /// 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: /// ``` /// let t = .expMinusOne(x) /// return x*(t+1) + t // x*exp(x) + (exp(x)-1) = (x+1)*exp(x) - 1 /// ``` /// 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`. static func expMinusOne(_ x: Self) -> Self /// The [hyperbolic cosine][wiki] of `x`. /// ``` /// e^x + e^-x /// cosh(x) = ------------ /// 2 /// ``` /// /// See also `sinh()`, `tanh()` and `acosh()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function static func cosh(_ x: Self) -> Self /// The [hyperbolic sine][wiki] of `x`. /// ``` /// e^x - e^-x /// sinh(x) = ------------ /// 2 /// ``` /// /// See also `cosh()`, `tanh()` and `asinh()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function static func sinh(_ x: Self) -> Self /// The [hyperbolic tangent][wiki] of `x`. /// ``` /// sinh(x) /// tanh(x) = --------- /// cosh(x) /// ``` /// /// See also `cosh()`, `sinh()` and `atanh()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function static func tanh(_ x: Self) -> Self /// The [cosine][wiki] of `x`. /// /// For real types, `x` may be interpreted as an angle measured in radians. /// /// See also `sin()`, `tan()` and `acos()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Cosine static func cos(_ x: Self) -> Self /// The [sine][wiki] of `x`. /// /// For real types, `x` may be interpreted as an angle measured in radians. /// /// See also `cos()`, `tan()` and `asin()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Sine static func sin(_ x: Self) -> Self /// The [tangent][wiki] of `x`. /// /// 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`. /// /// [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`. /// /// [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`. static func log(onePlus x: Self) -> Self /// The [inverse hyperbolic cosine][wiki] of `x`. /// ``` /// cosh(acosh(x)) ≅ x /// ``` /// See also `asinh()`, `atanh()` and `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()`. /// /// [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()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function static func atanh(_ x: Self) -> Self /// The [arccosine][wiki] (inverse cosine) of `x`. /// /// For real types, the result may be interpreted as an angle measured in /// radians. /// ``` /// cos(acos(x)) ≅ x /// ``` /// See also `asin()`, `atan()` and `cos()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions static func acos(_ x: Self) -> Self /// The [arcsine][wiki] (inverse sine) of `x`. /// /// For real types, the result may be interpreted as an angle measured in /// radians. /// ``` /// sin(asin(x)) ≅ x /// ``` /// See also `acos()`, `atan()` and `sin()`. /// /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions static func asin(_ x: Self) -> Self /// The [arctangent][wiki] (inverse tangent) of `x`. /// /// 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`. /// /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions static func atan(_ x: Self) -> Self /// exp(y * log(x)) computed with additional internal precision. /// /// The edge-cases of this function are defined based on the behavior of the /// expression `exp(y log x)`, matching IEEE 754's `powr` operation. /// 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()`. static func pow(_ x: Self, _ y: Self) -> Self /// `x` raised to the nth power. /// /// 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 }