Clean up Vector random methods and add more docs for random

Author: wigging

Sources/Numerix/Documentation.docc/Random.md

@@ -1,17 +1,19 @@
-# Random Numbers
+# Random
 
 Random number generation.
 
 ## Overview
 
-Numerix provides random number generators 
+Numerix provides pseudorandom number generators (PRNGs) which are not cryptographically secure but offer much better performance than Swift's default random type methods.
 
 ## Topics
 
 - ``Wyrand``
 - ``Xoshiro128Plus``
 - ``Xoroshiro128Plus``
 - ``Xoroshiro128PlusPlus``
-- ``Vector/random(size:seed:)``
+- ``Vector/random(_:)``
+- ``Vector/random(_:seed:)``
+- ``Vector/random(_:using:)``
 - ``Vector/randomDistribution(size:dist:)``
 - ``Vector/randomBNNS(size:bounds:seed:)``

Sources/Numerix/Random/Random.swift

@@ -6,13 +6,25 @@ import Accelerate
 
 @_documentation(visibility: private)
 public protocol Random {
-    static func random(size: Int, seed: UInt64?) -> Vector<Self>
+    static func random(size: Int) -> Vector<Self>
+    static func random(size: Int, seed: UInt64) -> Vector<Self>
+    static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Self>
     static func randomBNNS(size: Int, bounds: (Self, Self), seed: UInt64, buffer: UnsafeMutableBufferPointer<Self>)
 }
 
 @_documentation(visibility: private)
 extension Float: Random {
-    public static func random(size: Int, seed: UInt64?) -> Vector<Float> {
+
+    public static func random(size: Int) -> Vector<Float> {
+        var vec = Vector<Float>(size: size)
+        var rng = Wyrand()
+        for i in 0..<size {
+            vec[i] = rng.next()
+        }
+        return vec
+    }
+
+    public static func random(size: Int, seed: UInt64) -> Vector<Float> {
         var vec = Vector<Float>(size: size)
         var rng = Wyrand(seed: seed)
         for i in 0..<size {
@@ -21,6 +33,14 @@ extension Float: Random {
         return vec
     }
 
+    public static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Float> {
+        var vec = Vector<Float>(size: size)
+        for i in 0..<size {
+            vec[i] = Float(rng.next() >> 40) * 0x1.0p-24
+        }
+        return vec
+    }
+
     public static func randomBNNS(
         size: Int, bounds: (Float, Float),
         seed: UInt64, buffer: UnsafeMutableBufferPointer<Float>
@@ -33,7 +53,17 @@ extension Float: Random {
 
 @_documentation(visibility: private)
 extension Double: Random {
-    public static func random(size: Int, seed: UInt64?) -> Vector<Double> {
+
+    public static func random(size: Int) -> Vector<Double> {
+        var vec = Vector<Double>(size: size)
+        var rng = Wyrand()
+        for i in 0..<size {
+            vec[i] = rng.next()
+        }
+        return vec
+    }
+
+    public static func random(size: Int, seed: UInt64) -> Vector<Double> {
         var vec = Vector<Double>(size: size)
         var rng = Wyrand(seed: seed)
         for i in 0..<size {
@@ -42,6 +72,14 @@ extension Double: Random {
         return vec
     }
 
+    public static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Double> {
+        var vec = Vector<Double>(size: size)
+        for i in 0..<size {
+            vec[i] = Double(rng.next() >> 11) * 0x1.0p-53
+        }
+        return vec
+    }
+
     public static func randomBNNS(
         size: Int, bounds: (Double, Double),
         seed: UInt64, buffer: UnsafeMutableBufferPointer<Double>
@@ -52,21 +90,49 @@ extension Double: Random {
 
 extension Vector where Scalar: Random {
 
-    /// Create a vector of random values from a uniform distrubtion over [0, 1).
+    /// Create a vector of random values from a uniform distribution over [0, 1) using the Wyrand generator.
+    /// ```swift
+    /// let vec = Vector<Double>.random(5)
+    /// ```
+    /// This uses the ``Wyrand`` pseudorandom number generator (PRNG) to generate the random values in the vector.
+    /// The values are sampled from a uniform distribution [0, 1) which includes zero but excludes one.
+    /// - Parameter size: Size of the vector.
+    /// - Returns: Vector of random values.
+    public static func random(_ size: Int) -> Vector {
+        Scalar.random(size: size)
+    }
+
+    /// Create a vector of random values from a uniform distribution over [0, 1) using a seed for the Wyrand generator.
     /// ```swift
-    /// let vec = Vector<Double>.random(size: 5)
+    /// let vec = Vector<Double>.random(5, seed: 123456)
     /// ```
-    /// This uses the Wyrand pseudorandom number generator (PRNG) to generate the random values in the vector.
-    /// Values are a uniform distribution over 0 to 1 excluding 1 which is denoted as [0, 1).
-    /// Provide a seed input value to create a reproducible random vector.
+    /// This uses the ``Wyrand`` pseudorandom number generator (PRNG) to generate the random values in the vector.
+    /// The values are sampled from a uniform distribution [0, 1) which includes zero but excludes one. Provide a seed
+    /// for reproducible results.
     /// - Parameters:
     ///   - size: Size of the vector.
-    ///   - seed: Seed for the random number generator.
+    ///   - seed: Seed for the Wyrand generator.
     /// - Returns: Vector of random values.
-    public static func random(size: Int, seed: UInt64? = nil) -> Vector {
+    public static func random(_ size: Int, seed: UInt64) -> Vector {
         Scalar.random(size: size, seed: seed)
     }
 
+    /// Create a vector of random values from a uniform distribution over [0, 1) using a random number generator.
+    /// ```swift
+    /// var rng = Xoroshiro128Plus(seed: (1227493545477, 7213431619994))
+    /// let a = Vector<Float>.random(5, using: &rng)
+    /// ```
+    /// The example uses the ``Xoroshiro128Plus`` pseudorandom number generator (PRNG) to generate random values to
+    /// fill the vector. The generator is seeded with two integers otherwise random seeds are provided if none are
+    /// given.
+    /// - Parameters:
+    ///   - size: Size of the vector.
+    ///   - rng: Random number generator.
+    /// - Returns: Vector or random values.
+    public static func random<G: RandomNumberGenerator>(_ size: Int, using rng: inout G) -> Vector {
+        Scalar.random(size: size, rng: &rng)
+    }
+
     /// Create a vector of random float values using BNNS.
     /// - Parameters:
     ///   - size: Size of the vector.

Sources/Numerix/Random/Wyrand.swift

@@ -9,6 +9,8 @@ https://lemire.me/blog/2019/03/19/the-fastest-conventional-random-number-generat
 
 import Foundation
 
+/// Wyrand is a fast 64-bit pseudorandom number generator (PRNG) for floating-point numbers. This is the default PRNG
+/// for Vector, Matrix, and ShapedArray types in Numerix.
 public struct Wyrand: RandomNumberGenerator {
     private var state: UInt64
 

Sources/Numerix/Random/Xoroshiro.swift

@@ -38,6 +38,13 @@ public struct Xoroshiro128Plus: RandomNumberGenerator {
         return result
     }
 
+    /// Generate a random single-precision value from a uniform distribution in [0, 1) which includes zero but
+    /// excludes one.
+    /// - Returns: Random single-precision value.
+    public mutating func next() -> Float {
+        Float(next() >> 40) * 0x1.0p-24
+    }
+
     /// Generate a random double-precision value from a uniform distribution in [0, 1) which includes zero but
     /// excludes one.
     /// - Returns: Random double-precision value.
@@ -72,6 +79,13 @@ public struct Xoroshiro128PlusPlus: RandomNumberGenerator {
         return result
     }
 
+    /// Generate a random single-precision value from a uniform distribution in [0, 1) which includes zero but
+    /// excludes one.
+    /// - Returns: Random single-precision value.
+    public mutating func next() -> Float {
+        Float(next() >> 40) * 0x1.0p-24
+    }
+
     /// Generate a random double-precision value from a uniform distribution in [0, 1) which includes zero but
     /// excludes one.
     /// - Returns: Random double-precision value.

Tests/RandomTests.swift

@@ -8,46 +8,87 @@ import Numerix
 struct RandomTests {
 
     @Test func wyrand() {
-        var rand = Wyrand(seed: 12345)
-        #expect(rand.next() == 13157676964440363053)
+        var rng = Wyrand(seed: 12345)
+        #expect(rng.next() == 13157676964440363053)
 
-        let a: Float = rand.next()
+        let a: Float = rng.next()
         #expect(a == 0.9815675)
 
-        let b: Double = rand.next()
+        let b: Double = rng.next()
         #expect(b ==  0.7952823641045631)
     }
 
-    @Test func xoshiro() {
-        var rng = Xoshiro128Plus(seed: (2719949631, 2719949631, 2719949631, 2719949631))
-        let a: Float = rng.next()
-        #expect(a == 0.26657522)
+    @Test func wyrandVector() {
+        // Without seed
+        let a = Vector<Float>.random(5)
+        #expect(a[0] < 1)
+
+        let aa = Vector<Double>.random(5)
+        #expect(aa[0] < 1)
+
+        // With seed
+        let b = Vector<Float>.random(5, seed: 123456)
+        #expect(b == [0.81488985, 0.30684602, 0.31690413, 0.3039148, 0.18646216])
+
+        let bb = Vector<Double>.random(4, seed: 123456)
+        #expect(bb == [0.8148898875141517, 0.3068460469993851, 0.3169041625894291, 0.30391479120110254])
+
+        // With generator
+        var rng = Wyrand(seed: 123456)
+        let c = Vector<Float>.random(5, using: &rng)
+        #expect(c == [0.81488985, 0.30684602, 0.31690413, 0.3039148, 0.18646216])
+
+        var rngg = Wyrand(seed: 123456)
+        let cc = Vector<Double>.random(4, using: &rngg)
+        #expect(cc == [0.8148898875141517, 0.3068460469993851, 0.3169041625894291, 0.30391479120110254])
     }
 
     @Test func xoroshiro() {
+        // Xoroshiro128Plus
         var rng = Xoroshiro128Plus(seed: (12274935454779349997, 7213431619994351707))
-        let a: Double = rng.next()
-        #expect(a == 0.05646649603323106)
+        #expect(rng.next() == 1041623001064150088)
+
+        let a: Float = rng.next()
+        #expect(a == 0.061123848)
 
+        let b: Double = rng.next()
+        #expect(b == 0.1307673047034703)
+
+        // Xoroshiro128PlusPlus
         var rngg = Xoroshiro128PlusPlus(seed: (12274935454779349997, 7213431619994351707))
-        let b: Double = rngg.next()
-        #expect(b == 0.8419936520290631)
+        #expect(rngg.next() == 15532041410668181718)
+
+        let c: Float = rngg.next()
+        #expect(c == 0.4994716)
+
+        let d: Double = rngg.next()
+        #expect(d == 0.7990605775501556)
     }
 
-    @Test func randomVector() {
-        // No seed
-        let a = Vector<Float>.random(size: 3)
-        #expect(a[0] < 1.0)
+    @Test func xoroshiroVector() {
+        // Xoroshiro128Plus vector
+        var rng = Xoroshiro128Plus(seed: (12274935454779349997, 7213431619994351707))
+        let a = Vector<Float>.random(5, using: &rng)
+        #expect(a == [0.05646646, 0.061123848, 0.13076729, 0.672823, 0.86956143])
 
-        let b = Vector<Double>.random(size: 3)
-        #expect(b[0] < 1.0)
+        let b = Vector<Double>.random(4, using: &rng)
+        #expect(b == [0.12803432662341308, 0.17036647757843948, 0.8789760758360461, 0.6166839170638875])
 
-        // With seed
-        let c = Vector<Float>.random(size: 4, seed: 12345)
-        #expect(c == Vector<Float>([0.71327907, 0.9815675, 0.79528236, 0.25364798]))
+        // Xoroshiro128PlusPlus vector
+        var rngg = Xoroshiro128PlusPlus(seed: (12274935454779349997, 7213431619994351707))
+        let c = Vector<Float>.random(5, using: &rngg)
+        #expect(c == [0.84199363, 0.4994716, 0.7990605, 0.74130404, 0.2992577])
 
-        let d = Vector<Double>.random(size: 4, seed: 12345)
-        #expect(d == Vector<Double>([0.7132790974854359, 0.9815675033121781, 0.7952823641045631, 0.25364800714420743]))
+        let d = Vector<Double>.random(4, using: &rngg)
+        #expect(d == [0.6241821269000679, 0.18502002919976157, 0.2555743212406011, 0.5790431050892778])
+    }
+
+    @Test func xoshiro() {
+        var rng = Xoshiro128Plus(seed: (2719949631, 2719949631, 2719949631, 2719949631))
+        #expect(rng.next() == 1144931966)
+
+        let a: Float = rng.next()
+        #expect(a == 0.6332876)
     }
 
     @Test func randomBNNSVector() {