Add random extensions for Matrix struct

Author: wigging

Sources/Numerix/Documentation.docc/Random.md

@@ -4,7 +4,7 @@ Random number generation.
 
 ## Overview
 
-Numerix provides pseudorandom number generators (PRNGs) which are not cryptographically secure but offer much better performance than Swift's default random type methods.
+Numerix provides pseudorandom number generators (PRNGs) which are not cryptographically secure but offer much better performance than Swift's default random type methods. The generators can be used on their own or with Vector, Matrix, and ShapedArray structs to create bulk random values. By default the ``Wyrand`` generator is used with Vector, Matrix, and ShapedArray structs.
 
 ## Topics
 
@@ -13,6 +13,8 @@ Numerix provides pseudorandom number generators (PRNGs) which are not cryptograp
 - ``Xoroshiro128Plus``
 - ``Xoroshiro128PlusPlus``
 - ``Vector/random(_:seed:)``
+- ``Matrix/random(_:_:seed:)``
 - ``Vector/random(_:using:)``
+- ``Matrix/random(_:_:using:)``
 - ``Vector/randomBNNS(size:bounds:seed:)``
 - ``Vector/randomDistribution(size:dist:)``

Sources/Numerix/Random/Random.swift

@@ -9,7 +9,11 @@ import Accelerate
 @_documentation(visibility: private)
 public protocol Random {
     static func random(size: Int, seed: UInt64?) -> Vector<Self>
+    static func random(rows: Int, columns: Int, seed: UInt64?) -> Matrix<Self>
+
     static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Self>
+    static func random<G: RandomNumberGenerator>(rows: Int, columns: Int, rng: inout G) -> Matrix<Self>
+
     static func randomBNNS(size: Int, bounds: (Self, Self), seed: UInt64, buffer: UnsafeMutableBufferPointer<Self>)
 }
 
@@ -25,6 +29,17 @@ extension Float: Random {
         return vec
     }
 
+    public static func random(rows: Int, columns: Int, seed: UInt64?) -> Matrix<Float> {
+        var mat = Matrix<Float>(rows: rows, columns: columns)
+        var rng = Wyrand(seed: seed)
+        for i in 0..<rows {
+            for j in 0..<columns {
+                mat[i, j] = rng.next()
+            }
+        }
+        return mat
+    }
+
     public static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Float> {
         var vec = Vector<Float>(size: size)
         for i in 0..<size {
@@ -33,6 +48,16 @@ extension Float: Random {
         return vec
     }
 
+    public static func random<G: RandomNumberGenerator>(rows: Int, columns: Int, rng: inout G) -> Matrix<Float> {
+        var mat = Matrix<Float>(rows: rows, columns: columns)
+        for i in 0..<rows {
+            for j in 0..<columns {
+                mat[i, j] = Float(rng.next() >> 40) * 0x1.0p-24
+            }
+        }
+        return mat
+    }
+
     public static func randomBNNS(
         size: Int, bounds: (Float, Float),
         seed: UInt64, buffer: UnsafeMutableBufferPointer<Float>
@@ -55,6 +80,17 @@ extension Double: Random {
         return vec
     }
 
+    public static func random(rows: Int, columns: Int, seed: UInt64?) -> Matrix<Double> {
+        var mat = Matrix<Double>(rows: rows, columns: columns)
+        var rng = Wyrand(seed: seed)
+        for i in 0..<rows {
+            for j in 0..<columns {
+                mat[i, j] = rng.next()
+            }
+        }
+        return mat
+    }
+
     public static func random<G: RandomNumberGenerator>(size: Int, rng: inout G) -> Vector<Double> {
         var vec = Vector<Double>(size: size)
         for i in 0..<size {
@@ -63,6 +99,16 @@ extension Double: Random {
         return vec
     }
 
+    public static func random<G: RandomNumberGenerator>(rows: Int, columns: Int, rng: inout G) -> Matrix<Double> {
+        var mat = Matrix<Double>(rows: rows, columns: columns)
+        for i in 0..<rows {
+            for j in 0..<columns {
+                mat[i, j] = Double(rng.next() >> 11) * 0x1.0p-53
+            }
+        }
+        return mat
+    }
+
     public static func randomBNNS(
         size: Int, bounds: (Double, Double),
         seed: UInt64, buffer: UnsafeMutableBufferPointer<Double>
@@ -117,3 +163,39 @@ extension Vector where Scalar: Random {
         return vec
     }
 }
+
+extension Matrix where Scalar: Random {
+
+    /// Create a matrix of random values from a uniform distribution over [0, 1).
+    /// ```swift
+    /// let a = Matrix<Float>.random(2, 3)
+    /// let b = Matrix<Double>.random(2, 2, seed: 123456)
+    /// ```
+    /// This method uses the ``Wyrand`` pseudorandom number generator (PRNG) to generate the random values in the
+    /// matrix. The values are sampled from a uniform distribution [0, 1) which includes zero but excludes one. An
+    /// optional seed can be provided for reproducible results.
+    /// - Parameters:
+    ///   - rows: Number of matrix rows.
+    ///   - columns: Number of matrix columns.
+    ///   - seed: Seed for the Wyrand generator.
+    /// - Returns: Matrix of random values.
+    public static func random(_ rows: Int, _ columns: Int, seed: UInt64? = nil) -> Matrix {
+        Scalar.random(rows: rows, columns: columns, seed: seed)
+    }
+
+    /// Create a matrix of random values from a uniform distribution over [0, 1) using a random number generator.
+    /// ```swift
+    /// var rng = Xoroshiro128Plus(seed: (1227493545477, 7213431619994))
+    /// let a = Matrix<Double>.random(5, 4, using: &rng)
+    /// ```
+    /// The example uses the ``Xoroshiro128Plus`` pseudorandom number generator (PRNG) to generate random values to
+    /// fill the matrix. The generator is seeded with two integers otherwise random seeds are used if none are given.
+    /// - Parameters:
+    ///   - rows: Number of matrix rows.
+    ///   - columns: Number of matrix columns.
+    ///   - rng: Random number generator.
+    /// - Returns: Matrix of random values.
+    public static func random<G: RandomNumberGenerator>(_ rows: Int, _ columns: Int, using rng: inout G) -> Matrix {
+        Scalar.random(rows: rows, columns: columns, rng: &rng)
+    }
+}

Tests/RandomTests.swift

@@ -43,6 +43,31 @@ struct RandomTests {
         #expect(cc == [0.8148898875141517, 0.3068460469993851, 0.3169041625894291, 0.30391479120110254])
     }
 
+    @Test func wyrandMatrix() {
+        // Without seed
+        let a = Matrix<Float>.random(3, 3)
+        #expect(a[0, 0] < 1)
+
+        let aa = Matrix<Double>.random(3, 3)
+        #expect(aa[0, 0] < 1)
+
+        // With seed
+        let b = Matrix<Float>.random(2, 2, seed: 123456)
+        #expect(b == [[0.81488985, 0.30684602], [0.31690413, 0.3039148]])
+
+        let bb = Matrix<Double>.random(2, 2, seed: 123456)
+        #expect(bb == [[0.8148898875141517, 0.3068460469993851], [0.3169041625894291, 0.30391479120110254]])
+
+        // With generator
+        var rng = Wyrand(seed: 123456)
+        let c = Matrix<Float>.random(2, 2, using: &rng)
+        #expect(c == [[0.81488985, 0.30684602], [0.31690413, 0.3039148]])
+
+        var rngg = Wyrand(seed: 123456)
+        let cc = Matrix<Double>.random(2, 2, using: &rngg)
+        #expect(cc == [[0.8148898875141517, 0.3068460469993851], [0.3169041625894291, 0.30391479120110254]])
+    }
+
     @Test func xoroshiro() {
         // Xoroshiro128Plus
         var rng = Xoroshiro128Plus(seed: (12274935454779349997, 7213431619994351707))
@@ -66,15 +91,15 @@ struct RandomTests {
     }
 
     @Test func xoroshiroVector() {
-        // Xoroshiro128Plus vector
+        // Xoroshiro128Plus
         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(4, using: &rng)
         #expect(b == [0.12803432662341308, 0.17036647757843948, 0.8789760758360461, 0.6166839170638875])
 
-        // Xoroshiro128PlusPlus vector
+        // Xoroshiro128PlusPlus
         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])
@@ -83,6 +108,24 @@ struct RandomTests {
         #expect(d == [0.6241821269000679, 0.18502002919976157, 0.2555743212406011, 0.5790431050892778])
     }
 
+    @Test func xoroshiroMatrix() {
+        // Xoroshiro128Plus
+        var rng = Xoroshiro128Plus(seed: (12274935454779349997, 7213431619994351707))
+        let a = Matrix<Float>.random(2, 2, using: &rng)
+        #expect(a == [[0.05646646, 0.061123848], [0.13076729, 0.672823]])
+
+        let b = Matrix<Double>.random(2, 2, using: &rng)
+        #expect(b == [[0.8695614471421985, 0.12803432662341308], [0.17036647757843948, 0.8789760758360461]])
+
+        // Xoroshiro128PlusPlus
+        var rngg = Xoroshiro128PlusPlus(seed: (12274935454779349997, 7213431619994351707))
+        let c = Matrix<Float>.random(2, 2, using: &rngg)
+        #expect(c == [[0.84199363, 0.4994716], [0.7990605, 0.74130404]])
+
+        let d = Matrix<Double>.random(2, 2, using: &rngg)
+        #expect(d == [[0.2992577376225274, 0.6241821269000679], [0.18502002919976157, 0.2555743212406011]])
+    }
+
     @Test func xoshiro() {
         var rng = Xoshiro128Plus(seed: (2719949631, 2719949631, 2719949631, 2719949631))
         #expect(rng.next() == 1144931966)