Clean up tests and add docs related to WyRand

Author: wigging

Sources/RandomModule/Random.swift

@@ -1,6 +1,5 @@
 /*
-Protocol for random vector.
-Random vector protocol and init.
+Random vector protocol using WyRand.
 */
 
 import VectorModule
@@ -35,6 +34,18 @@ extension Double: Random {
 }
 
 extension Vector {
+
+    /// Create a vector of random values from a uniform distrubtion over [0, 1).
+    /// ```swift
+    /// let vec = Vector<Double>.random(size: 5)
+    /// ```
+    /// 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.
+    /// - Parameters:
+    ///   - size: Size of the vector.
+    ///   - seed: Seed for the random number generator.
+    /// - Returns: Vector of random values.
     public static func random(size: Int, seed: UInt64? = nil) -> Vector where Scalar: Random {
         Scalar.random(size: size, seed: seed)
     }

Sources/RandomModule/WyRand.swift

@@ -11,7 +11,7 @@ https://lemire.me/blog/2019/03/19/the-fastest-conventional-random-number-generat
 import Foundation
 
 public struct WyRand: RandomNumberGenerator {
-    private var state : UInt64
+    private var state: UInt64
 
     public init(seed: UInt64? = nil) {
         state = seed ?? UInt64(abs(UUID().hashValue))

Sources/VectorModule/Trigonometry.swift

@@ -37,39 +37,39 @@ extension Float: Trigonometry {
         vForce.tan(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func asin(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.asin(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func acos(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.acos(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func atan(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.atan(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func csc(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.sin(a.buffer, result: &result.buffer)
         vForce.reciprocal(result.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func sec(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.cos(a.buffer, result: &result.buffer)
         vForce.reciprocal(result.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func cot(_ a: Vector<Float>) -> Vector<Float> {
         var result = Vector(like: a)
         vForce.tan(a.buffer, result: &result.buffer)
@@ -98,39 +98,39 @@ extension Double: Trigonometry {
         vForce.tan(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func asin(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.asin(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func acos(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.acos(a.buffer, result: &result.buffer)
         return result
     }
-    	
+
     public static func atan(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.atan(a.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func csc(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.sin(a.buffer, result: &result.buffer)
         vForce.reciprocal(result.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func sec(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.cos(a.buffer, result: &result.buffer)
         vForce.reciprocal(result.buffer, result: &result.buffer)
         return result
     }
-    
+
     public static func cot(_ a: Vector<Double>) -> Vector<Double> {
         var result = Vector(like: a)
         vForce.tan(a.buffer, result: &result.buffer)
@@ -174,7 +174,8 @@ public func tan<Scalar>(_ vec: Vector<Scalar>) -> Vector<Scalar> where Scalar: T
 
 /// Calculate the arcsine of each element in a vector.
 ///
-/// Elements in the vector should be within the domain -1 ≤ x ≤ 1 otherwise results may be nan. Results are returned on the closed interval -π / 2 ≤ y ≤ π / 2.
+/// Elements in the vector should be within the domain -1 ≤ x ≤ 1 otherwise results may be nan.
+/// Results are returned on the closed interval -π / 2 ≤ y ≤ π / 2.
 /// ```swift
 /// let vec = Vector([-1, -0.5, 0, 0.5, 1])
 /// let result = asin(vec)

Tests/RandomDistTests.swift

@@ -33,4 +33,11 @@ struct RandomTests {
         let d = Vector<Double>.random(size: 4, seed: 12345)
         #expect(d == Vector<Double>([0.7132790974854359, 0.9815675033121781, 0.7952823641045631, 0.25364800714420743]))
     }
+
+    @Test func randomDist() {
+        let a = Vector<Float>.randomDistribution(size: 4)
+        let b = Vector<Double>.randomDistribution(size: 5)
+        #expect(a[0] <= 1.0)
+        #expect(b[0] <= 1.0)
+    }
 }

Tests/RandomTests.swift

@@ -9,26 +9,26 @@ struct TrigonometryTests {
 
     @Test func vectorTrig() {
         let a = Vector<Float>([1, 2, 3, 4])  // single precision
-        
+
         #expect(sin(a).isApproximatelyEqual(to: [0.841471, 0.909297, 0.14112, -0.756802]))
         #expect(cos(a).isApproximatelyEqual(to: [0.540302, -0.416147, -0.989992, -0.653644]))
         #expect(tan(a).isApproximatelyEqual(to: [1.55741, -2.18504, -0.142547, 1.15782], relativeTolerance: 1e-4))
-        
+
         #expect(csc(a).isApproximatelyEqual(to: [1.18839511, 1.09975017, 7.0861674, -1.32134871]))
         #expect(sec(a).isApproximatelyEqual(to: [1.85081572, -2.40299796, -1.01010867, -1.52988566]))
         #expect(cot(a).isApproximatelyEqual(to: [0.64209262, -0.45765755, -7.01525255, 0.86369115]))
 
         let b = Vector([1, 2, 3, 4.0])  // double precision
-        
+
         #expect(sin(b).isApproximatelyEqual(to: [0.841471, 0.909297, 0.14112, -0.756802], relativeTolerance: 1e-4))
         #expect(cos(b).isApproximatelyEqual(to: [0.540302, -0.416147, -0.989992, -0.6536], relativeTolerance: 1e-4))
         #expect(tan(b).isApproximatelyEqual(to: [1.55741, -2.18504, -0.142547, 1.15782], relativeTolerance: 1e-4))
-        
+
         #expect(csc(b).isApproximatelyEqual(to: [1.18839511, 1.09975017, 7.0861674, -1.32134871]))
         #expect(sec(b).isApproximatelyEqual(to: [1.85081572, -2.40299796, -1.01010867, -1.52988566]))
         #expect(cot(b).isApproximatelyEqual(to: [0.64209262, -0.45765755, -7.01525255, 0.86369115]))
     }
-    
+
     @Test func vectorArcTrig() {
         let a = Vector<Float>([-1, -0.5, 0, 0.5, 1])  // single precision
         #expect(asin(a) == [-1.57079633, -0.52359878, 0.0, 0.52359878, 1.57079633])