Remove stochastic rounding mode

It's a useful operation, but it deserves its own API to allow the use of a custom random source.
Also, the existing API blocks some constant-folding operations because the call to the system random source is an opaque optimization barrier, so removing it allows us to produce better codegen for the other rounding modes.

We're also bumping required Swift version to 5.9, and removing the executable test targets for log/log1p, as they're really only useful for development of those algorithms.

Author: stephentyrone

Package.swift

@@ -1,9 +1,9 @@
-// swift-tools-version:5.5
+// swift-tools-version:5.9
 //===--- Package.swift ----------------------------------------*- swift -*-===//
 //
 // 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
@@ -81,19 +81,6 @@ let package = Package(
       name: "RealTests",
       dependencies: ["_TestSupport"],
       exclude: ["CMakeLists.txt"]
-    ),
-    
-    // MARK: - Test executables
-    .executableTarget(
-      name: "ComplexLog",
-      dependencies: ["Numerics", "_TestSupport"],
-      path: "Tests/Executable/ComplexLog"
-    ),
-    
-    .executableTarget(
-      name: "ComplexLog1p",
-      dependencies: ["Numerics", "_TestSupport"],
-      path: "Tests/Executable/ComplexLog1p"
     )
   ]
 )

Sources/IntegerUtilities/DivideWithRounding.swift

@@ -116,22 +116,6 @@ extension BinaryInteger {
       // If q is already odd, we have the correct result.
       if q._lowWord & 1 == 1 { return q }
 
-    case .stochastically:
-      let bmag = other.magnitude
-      let rmag = r.magnitude
-      var bhi: UInt64
-      var rhi: UInt64
-      if other.magnitude <= UInt64.max {
-        bhi = UInt64(bmag)
-        rhi = UInt64(rmag)
-      } else {
-        let shift = bmag._msb - 63
-        bhi = UInt64(truncatingIfNeeded: bmag >> shift)
-        rhi = UInt64(truncatingIfNeeded: rmag >> shift)
-      }
-      let (sum, car) = rhi.addingReportingOverflow(.random(in: 0 ..< bhi))
-      if sum < bhi && !car { return q }
-      
     case .requireExact:
       preconditionFailure("Division was not exact.")
     }
@@ -299,22 +283,6 @@ extension SignedInteger {
       // If q is already odd, we have the correct result.
       if q._lowWord & 1 == 1 { return (q, r) }
 
-    case .stochastically:
-      let bmag = other.magnitude
-      let rmag = r.magnitude
-      var bhi: UInt64
-      var rhi: UInt64
-      if other.magnitude <= UInt64.max {
-        bhi = UInt64(bmag)
-        rhi = UInt64(rmag)
-      } else {
-        let shift = bmag._msb - 63
-        bhi = UInt64(truncatingIfNeeded: bmag >> shift)
-        rhi = UInt64(truncatingIfNeeded: rmag >> shift)
-      }
-      let (sum, car) = rhi.addingReportingOverflow(.random(in: 0 ..< bhi))
-      if sum < bhi && !car { return (q, r) }
-      
     case .requireExact:
       preconditionFailure("Division was not exact.")
     }
@@ -347,7 +315,7 @@ extension SignedInteger {
 ///   is not representable.
 ///
 /// - Returns: `(quotient, remainder)`, with `0 <= remainder < b.magnitude`.
-func euclideanDivision<T>(_ a: T, _ b: T) -> (quotient: T, remainder: T)
+public func euclideanDivision<T>(_ a: T, _ b: T) -> (quotient: T, remainder: T)
 where T: SignedInteger
 {
   a.divided(by: b, rounding: a >= 0 ? .towardZero : .awayFromZero)

Sources/IntegerUtilities/RoundingRule.swift

@@ -2,21 +2,13 @@
 //
 // This source file is part of the Swift Numerics open source project
 //
-// Copyright (c) 2021-2024 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
 //
 //===----------------------------------------------------------------------===//
 
-// TODO: it's unfortunate that we can't specify a custom random source
-// for the stochastic rounding rule, but I don't see a nice way to have
-// that share the API with the other rounding rules, because we'd then
-// have to take either the rule in-out or have an additional RNG/state
-// parameter. The same problem applies to rounding with dithering and
-// any other stateful rounding method. We should consider adding a
-// stateful rounding API down the road to support those use cases.
-
 /// A rule that defines how to select one of the two representable results
 /// closest to a given value.
 ///
@@ -59,22 +51,22 @@
 ///   2.0  |     2    |     2    |     2    |     2    |     2    |
 /// -------+----------+----------+----------+----------+----------+
 ///
-///                      Specialized rounding rules
+///            Specialized rounding rules
 ///
-///  value |    toOdd     |    stochastically     |  requireExact  |
-/// =======+==============+=======================+================+
-///  -1.5  |      -1      |    50% -2, 50% -1     |      trap      |
-/// -------+--------------+-----------------------+----------------+
-///  -0.5  |      -1      |    50% -1, 50% 0      |      trap      |
-/// -------+--------------+-----------------------+----------------+
-///   0.5  |       1      |     50% 0, 50% 1      |      trap      |
-/// -------+--------------+-----------------------+----------------+
-///   0.7  |       1      |     30% 0, 70% 1      |      trap      |
-/// -------+--------------+-----------------------+----------------+
-///   1.2  |       1      |     80% 1, 20% 2      |      trap      |
-/// -------+--------------+-----------------------+----------------+
-///   2.0  |       2      |          2            |        2       |
-/// -------+--------------+-----------------------+----------------+
+///  value |    toOdd     |  requireExact  |
+/// =======+==============+================+
+///  -1.5  |      -1      |      trap      |
+/// -------+--------------+----------------+
+///  -0.5  |      -1      |      trap      |
+/// -------+--------------+----------------+
+///   0.5  |       1      |      trap      |
+/// -------+--------------+----------------+
+///   0.7  |       1      |      trap      |
+/// -------+--------------+----------------+
+///   1.2  |       1      |      trap      |
+/// -------+--------------+----------------+
+///   2.0  |       2      |        2       |
+/// -------+--------------+----------------+
 /// ```
 public enum RoundingRule {
   /// Produces the closest representable value that is less than or equal
@@ -200,45 +192,6 @@ public enum RoundingRule {
   /// because 5/2 = 2.5 is equally close to 2 and 3, and 2 is even.
   case toNearestOrEven
 
-  /// Adds a uniform random value from [0, d) to the value being rounded,
-  /// where d is the distance between the two closest representable values,
-  /// then rounds the sum downwards.
-  ///
-  /// Unlike all the other rounding modes, this mode is _not deterministic_;
-  /// repeated calls to rounding operations with this mode will generally
-  /// produce different results. There is a tradeoff implicit in using this
-  /// mode: you can sacrifice _reproducible_ results to get _more accurate_
-  /// results in aggregate. For a contrived but illustrative example, consider
-  /// the following:
-  /// ```
-  /// let data = Array(repeating: 1, count: 100)
-  /// let result = data.reduce(0) {
-  ///   $0 + $1.divided(by: 3, rounding: rule)
-  /// }
-  /// ```
-  /// because 1/3 is always the same value between 0 and 1, any
-  /// deterministic rounding rule must produce either 0 or 100 for
-  /// this computation. But rounding `stochastically` will
-  /// produce a value close to 33. The _error_ of the computation
-  /// is smaller, but the result will now change between runs of the
-  /// program.
-  ///
-  /// For this simple case a better solution would be to add the
-  /// values first, and then divide. This gives a result that is both
-  /// reproducible _and_ accurate:
-  /// ```
-  /// let result = data.reduce(0, +)/3
-  /// ```
-  /// but this isn't always possible in more sophisticated scenarios,
-  /// and in those cases this rounding rule may be useful.
-  ///
-  /// Examples:
-  /// - `(-4).divided(by: 3, rounding: .stochastically)`
-  /// will be –1 with probability 2/3 and –2 with probability 1/3.
-  /// - `5.shifted(rightBy: 1, rounding: .stochastically)`
-  /// will be 2 with probability 1/2 and 3 with probability 1/2.
-  case stochastically
-  
   /// If the value being rounded is representable, that value is returned.
   /// Otherwise, a precondition failure occurs.
   ///
@@ -304,15 +257,6 @@ extension FloatingPoint {
       // which way that rounds, then select the other value.
       let even = (trunc + one/2).rounded(.toNearestOrEven)
       return trunc == even ? trunc + one : trunc
-    case .stochastically:
-      let trunc = rounded(.towardZero)
-      if trunc == self { return trunc }
-      // We have eliminated all large values at this point; add dither in
-      // ±[0,1) and then truncate.
-      let bits = Swift.min(-Self.ulpOfOne.exponent, 32)
-      let random = Self(UInt32.random(in: 0 ... (1 << bits &- 1)))
-      let dither = Self(sign: sign, exponent: -bits, significand: random)
-      return (self + dither).rounded(.towardZero)
     case .requireExact:
       let trunc = rounded(.towardZero)
       precondition(isInfinite || trunc == self, "\(self) is not an exact integer.")

Sources/IntegerUtilities/ShiftWithRounding.swift

@@ -130,27 +130,6 @@ extension BinaryInteger {
       return floor + Self((round + lost) >> count)
     case .toOdd:
       return floor | (lost == 0 ? 0 : 1)
-    case .stochastically:
-      // In theory, u01 should be Self.random(in: 0 ..< onesBit), but the
-      // random(in:) method does not exist on BinaryInteger. This is
-      // (arguably) good, though, because there's actually no reason to
-      // generate large amounts of randomness just to implement stochastic
-      // rounding; 32b suffices for almost all purposes, and 64b is more
-      // than enough.
-      var g = SystemRandomNumberGenerator()
-      let u01 = g.next()
-      if count < 64 {
-        // count is small, so mask and lost are representable as both
-        // UInt64 and Self, regardless of what type Self actually is.
-        return floor + Self(((u01 & UInt64(mask)) + UInt64(lost)) >> count)
-      } else {
-        // count is large, so lost may not be representable as UInt64; pre-
-        // shift by count-64 to isolate the high 64b of the fraction, then
-        // add u01 and carry-out to round.
-        let highWord = UInt64(truncatingIfNeeded: lost >> (Int(count) - 64))
-        let (_, carry) = highWord.addingReportingOverflow(u01)
-        return floor + (carry ? 1 : 0)
-      }
     case .requireExact:
       precondition(lost == 0, "shift was not exact.")
       return floor