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.

Author: stephentyrone

Sources/RealModule/AlgebraicField.swift

@@ -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
 }
 

Sources/RealModule/ApproximateEquality.swift

@@ -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,

Sources/RealModule/AugmentedArithmetic.swift

@@ -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

Sources/RealModule/Documentation.docc/ElementaryFunctions.md

@@ -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

Sources/RealModule/Documentation.docc/RealFunctions.md

@@ -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(_:)``

Sources/RealModule/Double+Real.swift

@@ -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