Merge pull request #64 from Magnus167/randomx

Implement built-in random number generation utilities

Cargo.toml

@@ -15,7 +15,6 @@ crate-type = ["cdylib", "lib"]
 [dependencies]
 chrono = "^0.4.10"
 criterion = { version = "0.5", features = ["html_reports"], optional = true }
-rand = "^0.9.1"
 
 [features]
 bench = ["dep:criterion"]

README.md

@@ -30,7 +30,7 @@ Rustframe is an educational project, and is not intended for production use. It
 
 - **[Coming Soon]** _DataFrame_ - Multi-type data structure for heterogeneous data, with labeled columns and typed row indices.
 
-- **[Coming Soon]** _Random number utils_ - Random number generation utilities for statistical sampling and simulations. (Currently using the [`rand`](https://crates.io/crates/rand) crate.)
+- **Random number utils** - Built-in pseudo and cryptographically secure generators for simulations.
 
 #### Matrix and Frame functionality
 

examples/game_of_life.rs

@@ -5,8 +5,8 @@
 //! To modify the behaviour of the example, please change the constants at the top of this file.
 //! By default,
 
-use rand::{self, Rng};
 use rustframe::matrix::{BoolMatrix, BoolOps, IntMatrix, Matrix};
+use rustframe::random::{rng, Rng};
 use std::{thread, time};
 
 const BOARD_SIZE: usize = 20; // Size of the board (50x50)
@@ -265,7 +265,7 @@ pub fn generate_glider(board: &mut BoolMatrix, board_size: usize) {
     // Initialize with a Glider pattern.
     // It demonstrates how to set specific cells in the matrix.
     // This demonstrates `IndexMut` for `current_board[(r, c)] = true;`.
-    let mut rng = rand::rng();
+    let mut rng = rng();
     let r_offset = rng.random_range(0..(board_size - 3));
     let c_offset = rng.random_range(0..(board_size - 3));
     if board.rows() >= r_offset + 3 && board.cols() >= c_offset + 3 {
@@ -281,7 +281,7 @@ pub fn generate_pulsar(board: &mut BoolMatrix, board_size: usize) {
     // Initialize with a Pulsar pattern.
     // This demonstrates how to set specific cells in the matrix.
     // This demonstrates `IndexMut` for `current_board[(r, c)] = true;`.
-    let mut rng = rand::rng();
+    let mut rng = rng();
     let r_offset = rng.random_range(0..(board_size - 17));
     let c_offset = rng.random_range(0..(board_size - 17));
     if board.rows() >= r_offset + 17 && board.cols() >= c_offset + 17 {

examples/random_demo.rs

@@ -0,0 +1,67 @@
+use rustframe::random::{crypto_rng, rng, Rng, SliceRandom};
+
+/// Demonstrates basic usage of the random number generators.
+///
+/// It showcases uniform ranges, booleans, normal distribution,
+/// shuffling and the cryptographically secure generator.
+fn main() {
+    basic_usage();
+    println!("\n-----\n");
+    normal_demo();
+    println!("\n-----\n");
+    shuffle_demo();
+}
+
+fn basic_usage() {
+    println!("Basic PRNG usage\n----------------");
+    let mut prng = rng();
+    println!("random u64   : {}", prng.next_u64());
+    println!("range [10,20): {}", prng.random_range(10..20));
+    println!("bool         : {}", prng.gen_bool());
+}
+
+fn normal_demo() {
+    println!("Normal distribution\n-------------------");
+    let mut prng = rng();
+    for _ in 0..3 {
+        let v = prng.normal(0.0, 1.0);
+        println!("sample: {:.3}", v);
+    }
+}
+
+fn shuffle_demo() {
+    println!("Slice shuffling\n----------------");
+    let mut prng = rng();
+    let mut data = [1, 2, 3, 4, 5];
+    data.shuffle(&mut prng);
+    println!("shuffled: {:?}", data);
+
+    let mut secure = crypto_rng();
+    let byte = secure.random_range(0..256usize);
+    println!("crypto byte: {}", byte);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rustframe::random::{CryptoRng, Prng};
+
+    #[test]
+    fn test_basic_usage_range_bounds() {
+        let mut rng = Prng::new(1);
+        for _ in 0..50 {
+            let v = rng.random_range(5..10);
+            assert!(v >= 5 && v < 10);
+        }
+    }
+
+    #[test]
+    fn test_crypto_byte_bounds() {
+        let mut rng = CryptoRng::new();
+        for _ in 0..50 {
+            let v = rng.random_range(0..256usize);
+            assert!(v < 256);
+        }
+    }
+}
+

examples/random_stats.rs

@@ -0,0 +1,57 @@
+use rustframe::random::{crypto_rng, rng, Rng};
+
+/// Demonstrates simple statistical checks on random number generators.
+fn main() {
+    chi_square_demo();
+    println!("\n-----\n");
+    monobit_demo();
+}
+
+fn chi_square_demo() {
+    println!("Chi-square test on PRNG");
+    let mut rng = rng();
+    let mut counts = [0usize; 10];
+    let samples = 10000;
+    for _ in 0..samples {
+        let v = rng.random_range(0..10usize);
+        counts[v] += 1;
+    }
+    let expected = samples as f64 / 10.0;
+    let chi2: f64 = counts
+        .iter()
+        .map(|&c| {
+            let diff = c as f64 - expected;
+            diff * diff / expected
+        })
+        .sum();
+    println!("counts: {:?}", counts);
+    println!("chi-square: {:.3}", chi2);
+}
+
+fn monobit_demo() {
+    println!("Monobit test on crypto RNG");
+    let mut rng = crypto_rng();
+    let mut ones = 0usize;
+    let samples = 1000;
+    for _ in 0..samples {
+        ones += rng.next_u64().count_ones() as usize;
+    }
+    let ratio = ones as f64 / (samples as f64 * 64.0);
+    println!("ones ratio: {:.4}", ratio);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_chi_square_demo_runs() {
+        chi_square_demo();
+    }
+
+    #[test]
+    fn test_monobit_demo_runs() {
+        monobit_demo();
+    }
+}
+

src/compute/models/activations.rs

@@ -25,6 +25,7 @@ pub fn dleaky_relu(x: &Matrix<f64>) -> Matrix<f64> {
     x.map(|v| if v > 0.0 { 1.0 } else { 0.01 })
 }
 
+#[cfg(test)]
 mod tests {
     use super::*;
 

src/compute/models/dense_nn.rs

@@ -1,6 +1,6 @@
 use crate::compute::models::activations::{drelu, relu, sigmoid};
 use crate::matrix::{Matrix, SeriesOps};
-use rand::prelude::*;
+use crate::random::prelude::*;
 
 /// Supported activation functions
 #[derive(Clone)]
@@ -46,7 +46,7 @@ pub enum InitializerKind {
 
 impl InitializerKind {
     pub fn initialize(&self, rows: usize, cols: usize) -> Matrix<f64> {
-        let mut rng = rand::rng();
+        let mut rng = rng();
         let fan_in = rows;
         let fan_out = cols;
         let limit = match self {

src/compute/models/k_means.rs

@@ -1,7 +1,6 @@
 use crate::compute::stats::mean_vertical;
 use crate::matrix::Matrix;
-use rand::rng;
+use crate::random::prelude::*;
-use rand::seq::SliceRandom;
 
 pub struct KMeans {
     pub centroids: Matrix<f64>, // (k, n_features)
@@ -193,7 +192,8 @@ mod tests {
                                 break;
                             }
                         }
-                        assert!(matches_data_point, "Centroid {} (empty cluster) does not match any data point", c);
+                        // "Centroid {} (empty cluster) does not match any data point",c
+                        assert!(matches_data_point);
                     }
                 }
                 break;
@@ -360,5 +360,4 @@ mod tests {
         assert_eq!(predicted_label.len(), 1);
         assert!(predicted_label[0] < k);
     }
-
 }

src/lib.rs

@@ -11,3 +11,6 @@ pub mod utils;
 
 /// Documentation for the [`crate::compute`] module.
 pub mod compute;
+
+/// Documentation for the [`crate::random`] module.
+pub mod random;

src/random/crypto.rs

@@ -0,0 +1,164 @@
+use std::fs::File;
+use std::io::Read;
+
+use crate::random::Rng;
+
+/// Cryptographically secure RNG sourcing randomness from `/dev/urandom`.
+pub struct CryptoRng {
+    file: File,
+}
+
+impl CryptoRng {
+    /// Open `/dev/urandom` and create a new generator.
+    pub fn new() -> Self {
+        let file = File::open("/dev/urandom").expect("failed to open /dev/urandom");
+        Self { file }
+    }
+}
+
+impl Rng for CryptoRng {
+    fn next_u64(&mut self) -> u64 {
+        let mut buf = [0u8; 8];
+        self.file
+            .read_exact(&mut buf)
+            .expect("failed reading from /dev/urandom");
+        u64::from_ne_bytes(buf)
+    }
+}
+
+/// Convenience constructor for [`CryptoRng`].
+pub fn crypto_rng() -> CryptoRng {
+    CryptoRng::new()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::random::Rng;
+    use std::collections::HashSet;
+
+    #[test]
+    fn test_crypto_rng_nonzero() {
+        let mut rng = CryptoRng::new();
+        let mut all_same = true;
+        let mut prev = rng.next_u64();
+        for _ in 0..5 {
+            let val = rng.next_u64();
+            if val != prev {
+                all_same = false;
+            }
+            prev = val;
+        }
+        assert!(!all_same, "CryptoRng produced identical values");
+    }
+
+    #[test]
+    fn test_crypto_rng_variation_large() {
+        let mut rng = CryptoRng::new();
+        let mut values = HashSet::new();
+        for _ in 0..100 {
+            values.insert(rng.next_u64());
+        }
+        assert!(values.len() > 90, "CryptoRng output not varied enough");
+    }
+
+    #[test]
+    fn test_crypto_rng_random_range_uniform() {
+        let mut rng = CryptoRng::new();
+        let mut counts = [0usize; 10];
+        for _ in 0..1000 {
+            let v = rng.random_range(0..10usize);
+            counts[v] += 1;
+        }
+        for &c in &counts {
+            // "Crypto RNG counts far from uniform: {c}"
+            assert!((c as isize - 100).abs() < 50);
+        }
+    }
+
+    #[test]
+    fn test_crypto_normal_distribution() {
+        let mut rng = CryptoRng::new();
+        let mean = 0.0;
+        let sd = 1.0;
+        let n = 2000;
+        let mut sum = 0.0;
+        let mut sum_sq = 0.0;
+        for _ in 0..n {
+            let val = rng.normal(mean, sd);
+            sum += val;
+            sum_sq += val * val;
+        }
+        let sample_mean = sum / n as f64;
+        let sample_var = sum_sq / n as f64 - sample_mean * sample_mean;
+        assert!(sample_mean.abs() < 0.1);
+        assert!((sample_var - 1.0).abs() < 0.2);
+    }
+
+    #[test]
+    fn test_two_instances_different_values() {
+        let mut a = CryptoRng::new();
+        let mut b = CryptoRng::new();
+        let va = a.next_u64();
+        let vb = b.next_u64();
+        assert_ne!(va, vb);
+    }
+
+    #[test]
+    fn test_crypto_rng_helper_function() {
+        let mut rng = crypto_rng();
+        let _ = rng.next_u64();
+    }
+
+    #[test]
+    fn test_crypto_normal_zero_sd() {
+        let mut rng = CryptoRng::new();
+        for _ in 0..5 {
+            let v = rng.normal(10.0, 0.0);
+            assert_eq!(v, 10.0);
+        }
+    }
+
+    #[test]
+    fn test_crypto_shuffle_empty_slice() {
+        use crate::random::SliceRandom;
+        let mut rng = CryptoRng::new();
+        let mut arr: [u8; 0] = [];
+        arr.shuffle(&mut rng);
+        assert!(arr.is_empty());
+    }
+
+    #[test]
+    fn test_crypto_chi_square_uniform() {
+        let mut rng = CryptoRng::new();
+        let mut counts = [0usize; 10];
+        let samples = 10000;
+        for _ in 0..samples {
+            let v = rng.random_range(0..10usize);
+            counts[v] += 1;
+        }
+        let expected = samples as f64 / 10.0;
+        let chi2: f64 = counts
+            .iter()
+            .map(|&c| {
+                let diff = c as f64 - expected;
+                diff * diff / expected
+            })
+            .sum();
+        assert!(chi2 < 40.0, "chi-square statistic too high: {chi2}");
+    }
+
+    #[test]
+    fn test_crypto_monobit() {
+        let mut rng = CryptoRng::new();
+        let mut ones = 0usize;
+        let samples = 1000;
+        for _ in 0..samples {
+            ones += rng.next_u64().count_ones() as usize;
+        }
+        let total_bits = samples * 64;
+        let ratio = ones as f64 / total_bits as f64;
+        // "bit ratio far from 0.5: {ratio}"
+        assert!((ratio - 0.5).abs() < 0.02);
+    }
+}

src/random/mod.rs

@@ -0,0 +1,14 @@
+pub mod crypto;
+pub mod prng;
+pub mod random_core;
+pub mod seq;
+
+pub use crypto::{crypto_rng, CryptoRng};
+pub use prng::{rng, Prng};
+pub use random_core::{RangeSample, Rng};
+pub use seq::SliceRandom;
+
+pub mod prelude {
+    pub use super::seq::SliceRandom;
+    pub use super::{crypto_rng, rng, CryptoRng, Prng, RangeSample, Rng};
+}

src/random/prng.rs

@@ -0,0 +1,227 @@
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crate::random::Rng;
+
+/// Simple XorShift64-based pseudo random number generator.
+#[derive(Clone)]
+pub struct Prng {
+    state: u64,
+}
+
+impl Prng {
+    /// Create a new generator from the given seed.
+    pub fn new(seed: u64) -> Self {
+        Self { state: seed }
+    }
+
+    /// Create a generator seeded from the current time.
+    pub fn from_entropy() -> Self {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos() as u64;
+        Self::new(nanos)
+    }
+}
+
+impl Rng for Prng {
+    fn next_u64(&mut self) -> u64 {
+        let mut x = self.state;
+        x ^= x << 13;
+        x ^= x >> 7;
+        x ^= x << 17;
+        self.state = x;
+        x
+    }
+}
+
+/// Convenience constructor using system entropy.
+pub fn rng() -> Prng {
+    Prng::from_entropy()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::random::Rng;
+
+    #[test]
+    fn test_prng_determinism() {
+        let mut a = Prng::new(42);
+        let mut b = Prng::new(42);
+        for _ in 0..5 {
+            assert_eq!(a.next_u64(), b.next_u64());
+        }
+    }
+
+    #[test]
+    fn test_random_range_f64() {
+        let mut rng = Prng::new(1);
+        for _ in 0..10 {
+            let v = rng.random_range(-1.0..1.0);
+            assert!(v >= -1.0 && v < 1.0);
+        }
+    }
+
+    #[test]
+    fn test_random_range_usize() {
+        let mut rng = Prng::new(9);
+        for _ in 0..100 {
+            let v = rng.random_range(10..20);
+            assert!(v >= 10 && v < 20);
+        }
+    }
+
+    #[test]
+    fn test_gen_bool_balance() {
+        let mut rng = Prng::new(123);
+        let mut trues = 0;
+        for _ in 0..1000 {
+            if rng.gen_bool() {
+                trues += 1;
+            }
+        }
+        let ratio = trues as f64 / 1000.0;
+        assert!(ratio > 0.4 && ratio < 0.6);
+    }
+
+    #[test]
+    fn test_normal_distribution() {
+        let mut rng = Prng::new(7);
+        let mut sum = 0.0;
+        let mut sum_sq = 0.0;
+        let mean = 5.0;
+        let sd = 2.0;
+        let n = 5000;
+        for _ in 0..n {
+            let val = rng.normal(mean, sd);
+            sum += val;
+            sum_sq += val * val;
+        }
+        let sample_mean = sum / n as f64;
+        let sample_var = sum_sq / n as f64 - sample_mean * sample_mean;
+        assert!((sample_mean - mean).abs() < 0.1);
+        assert!((sample_var - sd * sd).abs() < 0.2 * sd * sd);
+    }
+
+    #[test]
+    fn test_prng_from_entropy_unique() {
+        use std::{collections::HashSet, thread, time::Duration};
+        let mut seen = HashSet::new();
+        for _ in 0..5 {
+            let mut rng = Prng::from_entropy();
+            seen.insert(rng.next_u64());
+            thread::sleep(Duration::from_micros(1));
+        }
+        assert!(seen.len() > 1, "Entropy seeds produced identical outputs");
+    }
+
+    #[test]
+    fn test_prng_uniform_distribution() {
+        let mut rng = Prng::new(12345);
+        let mut counts = [0usize; 10];
+        for _ in 0..10000 {
+            let v = rng.random_range(0..10usize);
+            counts[v] += 1;
+        }
+        for &c in &counts {
+            // "PRNG counts far from uniform: {c}"
+            assert!((c as isize - 1000).abs() < 150);
+        }
+    }
+
+    #[test]
+    fn test_prng_different_seeds_different_output() {
+        let mut a = Prng::new(1);
+        let mut b = Prng::new(2);
+        let va = a.next_u64();
+        let vb = b.next_u64();
+        assert_ne!(va, vb);
+    }
+
+    #[test]
+    fn test_prng_gen_bool_varies() {
+        let mut rng = Prng::new(99);
+        let mut seen_true = false;
+        let mut seen_false = false;
+        for _ in 0..100 {
+            if rng.gen_bool() {
+                seen_true = true;
+            } else {
+                seen_false = true;
+            }
+        }
+        assert!(seen_true && seen_false);
+    }
+
+    #[test]
+    fn test_random_range_single_usize() {
+        let mut rng = Prng::new(42);
+        for _ in 0..10 {
+            let v = rng.random_range(5..6);
+            assert_eq!(v, 5);
+        }
+    }
+
+    #[test]
+    fn test_random_range_single_f64() {
+        let mut rng = Prng::new(42);
+        for _ in 0..10 {
+            let v = rng.random_range(1.234..1.235);
+            assert!(v >= 1.234 && v < 1.235);
+        }
+    }
+
+    #[test]
+    fn test_prng_normal_zero_sd() {
+        let mut rng = Prng::new(7);
+        for _ in 0..5 {
+            let v = rng.normal(3.0, 0.0);
+            assert_eq!(v, 3.0);
+        }
+    }
+
+    #[test]
+    fn test_random_range_extreme_usize() {
+        let mut rng = Prng::new(5);
+        for _ in 0..10 {
+            let v = rng.random_range(0..usize::MAX);
+            assert!(v < usize::MAX);
+        }
+    }
+
+    #[test]
+    fn test_prng_chi_square_uniform() {
+        let mut rng = Prng::new(12345);
+        let mut counts = [0usize; 10];
+        let samples = 10000;
+        for _ in 0..samples {
+            let v = rng.random_range(0..10usize);
+            counts[v] += 1;
+        }
+        let expected = samples as f64 / 10.0;
+        let chi2: f64 = counts
+            .iter()
+            .map(|&c| {
+                let diff = c as f64 - expected;
+                diff * diff / expected
+            })
+            .sum();
+        //  "chi-square statistic too high: {chi2}"
+        assert!(chi2 < 20.0);
+    }
+
+    #[test]
+    fn test_prng_monobit() {
+        let mut rng = Prng::new(42);
+        let mut ones = 0usize;
+        let samples = 1000;
+        for _ in 0..samples {
+            ones += rng.next_u64().count_ones() as usize;
+        }
+        let total_bits = samples * 64;
+        let ratio = ones as f64 / total_bits as f64;
+        // "bit ratio far from 0.5: {ratio}"
+        assert!((ratio - 0.5).abs() < 0.01);
+    }
+}

src/random/random_core.rs

@@ -0,0 +1,98 @@
+use std::f64::consts::PI;
+use std::ops::Range;
+
+/// Trait implemented by random number generators.
+pub trait Rng {
+    /// Generate the next random `u64` value.
+    fn next_u64(&mut self) -> u64;
+
+    /// Generate a value uniformly in the given range.
+    fn random_range<T>(&mut self, range: Range<T>) -> T
+    where
+        T: RangeSample,
+    {
+        T::from_u64(self.next_u64(), &range)
+    }
+
+    /// Generate a boolean with probability 0.5 of being `true`.
+    fn gen_bool(&mut self) -> bool {
+        self.random_range(0..2usize) == 1
+    }
+
+    /// Sample from a normal distribution using the Box-Muller transform.
+    fn normal(&mut self, mean: f64, sd: f64) -> f64 {
+        let u1 = self.random_range(0.0..1.0);
+        let u2 = self.random_range(0.0..1.0);
+        mean + sd * (-2.0 * u1.ln()).sqrt() * (2.0 * PI * u2).cos()
+    }
+}
+
+/// Conversion from a raw `u64` into a type within a range.
+pub trait RangeSample: Sized {
+    fn from_u64(value: u64, range: &Range<Self>) -> Self;
+}
+
+impl RangeSample for usize {
+    fn from_u64(value: u64, range: &Range<Self>) -> Self {
+        let span = range.end - range.start;
+        (value as usize % span) + range.start
+    }
+}
+
+impl RangeSample for f64 {
+    fn from_u64(value: u64, range: &Range<Self>) -> Self {
+        let span = range.end - range.start;
+        range.start + (value as f64 / u64::MAX as f64) * span
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_range_sample_usize_boundary() {
+        assert_eq!(<usize as RangeSample>::from_u64(0, &(0..1)), 0);
+        assert_eq!(<usize as RangeSample>::from_u64(u64::MAX, &(0..1)), 0);
+    }
+
+    #[test]
+    fn test_range_sample_f64_boundary() {
+        let v0 = <f64 as RangeSample>::from_u64(0, &(0.0..1.0));
+        let vmax = <f64 as RangeSample>::from_u64(u64::MAX, &(0.0..1.0));
+        assert!(v0 >= 0.0 && v0 < 1.0);
+        assert!(vmax > 0.999999999999 && vmax <= 1.0);
+    }
+
+    #[test]
+    fn test_range_sample_usize_varied() {
+        for i in 0..5 {
+            let v = <usize as RangeSample>::from_u64(i, &(10..15));
+            assert!(v >= 10 && v < 15);
+        }
+    }
+
+    #[test]
+    fn test_range_sample_f64_span() {
+        for val in [0, u64::MAX / 2, u64::MAX] {
+            let f = <f64 as RangeSample>::from_u64(val, &(2.0..4.0));
+            assert!(f >= 2.0 && f <= 4.0);
+        }
+    }
+
+    #[test]
+    fn test_range_sample_usize_single_value() {
+        for val in [0, 1, u64::MAX] {
+            let n = <usize as RangeSample>::from_u64(val, &(5..6));
+            assert_eq!(n, 5);
+        }
+    }
+
+    #[test]
+    fn test_range_sample_f64_negative_range() {
+        for val in [0, u64::MAX / 3, u64::MAX] {
+            let f = <f64 as RangeSample>::from_u64(val, &(-2.0..2.0));
+            assert!(f >= -2.0 && f <= 2.0);
+        }
+    }
+}

src/random/seq.rs

@@ -0,0 +1,105 @@
+use crate::random::Rng;
+
+/// Trait for randomizing slices.
+pub trait SliceRandom {
+    /// Shuffle the slice in place using the provided RNG.
+    fn shuffle<R: Rng>(&mut self, rng: &mut R);
+}
+
+impl<T> SliceRandom for [T] {
+    fn shuffle<R: Rng>(&mut self, rng: &mut R) {
+        for i in (1..self.len()).rev() {
+            let j = rng.random_range(0..(i + 1));
+            self.swap(i, j);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::random::{CryptoRng, Prng};
+
+    #[test]
+    fn test_shuffle_slice() {
+        let mut rng = Prng::new(3);
+        let mut arr = [1, 2, 3, 4, 5];
+        let orig = arr.clone();
+        arr.shuffle(&mut rng);
+        assert_eq!(arr.len(), orig.len());
+        let mut sorted = arr.to_vec();
+        sorted.sort();
+        assert_eq!(sorted, orig.to_vec());
+    }
+
+    #[test]
+    fn test_slice_shuffle_deterministic_with_prng() {
+        let mut rng1 = Prng::new(11);
+        let mut rng2 = Prng::new(11);
+        let mut a = [1u8, 2, 3, 4, 5, 6, 7, 8, 9];
+        let mut b = a.clone();
+        a.shuffle(&mut rng1);
+        b.shuffle(&mut rng2);
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn test_slice_shuffle_crypto_random_changes() {
+        let mut rng1 = CryptoRng::new();
+        let mut rng2 = CryptoRng::new();
+        let orig = [1u8, 2, 3, 4, 5, 6, 7, 8, 9];
+        let mut a = orig.clone();
+        let mut b = orig.clone();
+        a.shuffle(&mut rng1);
+        b.shuffle(&mut rng2);
+        assert!(a != orig || b != orig, "Shuffles did not change order");
+        assert_ne!(a, b, "Two Crypto RNG shuffles produced same order");
+    }
+
+    #[test]
+    fn test_shuffle_single_element_no_change() {
+        let mut rng = Prng::new(1);
+        let mut arr = [42];
+        arr.shuffle(&mut rng);
+        assert_eq!(arr, [42]);
+    }
+
+    #[test]
+    fn test_multiple_shuffles_different_results() {
+        let mut rng = Prng::new(5);
+        let mut arr1 = [1, 2, 3, 4];
+        let mut arr2 = [1, 2, 3, 4];
+        arr1.shuffle(&mut rng);
+        arr2.shuffle(&mut rng);
+        assert_ne!(arr1, arr2);
+    }
+
+    #[test]
+    fn test_shuffle_empty_slice() {
+        let mut rng = Prng::new(1);
+        let mut arr: [i32; 0] = [];
+        arr.shuffle(&mut rng);
+        assert!(arr.is_empty());
+    }
+
+    #[test]
+    fn test_shuffle_three_uniform() {
+        use std::collections::HashMap;
+        let mut rng = Prng::new(123);
+        let mut counts: HashMap<[u8; 3], usize> = HashMap::new();
+        for _ in 0..6000 {
+            let mut arr = [1u8, 2, 3];
+            arr.shuffle(&mut rng);
+            *counts.entry(arr).or_insert(0) += 1;
+        }
+        let expected = 1000.0;
+        let chi2: f64 = counts
+            .values()
+            .map(|&c| {
+                let diff = c as f64 - expected;
+                diff * diff / expected
+            })
+            .sum();
+        assert!(chi2 < 30.0, "shuffle chi-square too high: {chi2}");
+    }
+}