Compare commits

...

66 Commits

Author SHA1 Message Date
Palash Tyagi
a96cb41d97
Merge cd3aa84e6019bad5492e9cbc6948caf6c0e0f726 into af70f9ffd71dc7bd9c0be0ae0c5737a02b33a5a5 2025-07-30 18:39:14 +01:00
af70f9ffd7
Merge pull request #65 from Magnus167/win-random
Refactor CryptoRng for cross-platform secure random byte generation
2025-07-29 23:29:58 +01:00
Palash Tyagi
7f33223496 Fix type name for BCRYPT_ALG_HANDLE in win_fill function 2025-07-29 23:25:07 +01:00
Palash Tyagi
73dbb25242 Refactor CryptoRng implementation for Windows and Unix, adding support for secure random byte generation on Windows. 2025-07-29 23:23:04 +01:00
4061ebf8ae
Merge pull request #64 from Magnus167/randomx
Implement built-in random number generation utilities
2025-07-29 22:21:29 +01:00
Palash Tyagi
ef322fc6a2 Refactor assertions in tests to simplify error messages for KMeans, CryptoRng, and Prng modules 2025-07-29 22:15:45 +01:00
Palash Tyagi
750adc72e9 Add missing #[cfg(test)] attribute to tests module in activations.rs 2025-07-29 21:42:47 +01:00
Palash Tyagi
3207254564 Add examples for random number generation and statistical tests 2025-07-29 00:36:14 +01:00
Palash Tyagi
2ea83727a1 enhance unittests for all random functionalities 2025-07-29 00:36:05 +01:00
Palash Tyagi
3f56b378b2 Add unit tests for SliceRandom trait and shuffle functionality 2025-07-28 23:12:20 +01:00
Palash Tyagi
afcb29e716 Add extensive tests for Prng functionality, including range checks and distribution properties 2025-07-28 23:11:54 +01:00
Palash Tyagi
113831dc8c Add comprehensive tests for CryptoRng functionality and distribution properties 2025-07-28 23:11:26 +01:00
Palash Tyagi
289c70d9e9 Refactor tests to remove unused random number generator tests and enhance range sample validation 2025-07-28 23:11:17 +01:00
Palash Tyagi
cd13d98110 Remove rand dependency from Cargo.toml 2025-07-28 20:37:37 +01:00
Palash Tyagi
b4520b0d30 Update README to reflect built-in random number generation utilities 2025-07-28 20:37:24 +01:00
Palash Tyagi
5934b163f5 Refactor random number generation to use rustframe's random module 2025-07-28 20:37:08 +01:00
Palash Tyagi
4a1843183a Add documentation for the random module 2025-07-28 20:36:52 +01:00
Palash Tyagi
252c8a3d29 Refactor KMeans module to use inbuilt random 2025-07-28 20:23:59 +01:00
Palash Tyagi
5a5baf9716 Add initial implementation of random module with submodules and prelude exports 2025-07-28 20:19:12 +01:00
Palash Tyagi
28793e5b07 Add CryptoRng for cryptographically secure random number generation 2025-07-28 20:19:01 +01:00
Palash Tyagi
d75bd7a08f Add XorShift64-based pseudo random number generator implementation 2025-07-28 20:17:59 +01:00
Palash Tyagi
6fd796cceb Add SliceRandom trait for shuffling slices using RNG 2025-07-28 20:17:35 +01:00
Palash Tyagi
d0b0f295b1 Implement Rng trait and RangeSample conversion for random number generation 2025-07-28 20:17:21 +01:00
556b08216f
Merge pull request #61 from Magnus167/add-examples
Adding examples for various functionalities
2025-07-26 23:10:16 +01:00
Palash Tyagi
17201b4d29 Add example commands for statistical operations in README 2025-07-26 23:06:47 +01:00
Palash Tyagi
2a99d8930c Add examples for descriptive stats 2025-07-26 23:06:08 +01:00
Palash Tyagi
38213c73c7 Add examples for covariance and correlation 2025-07-26 23:05:56 +01:00
Palash Tyagi
c004bd8334 Add inferential statistics examples 2025-07-26 23:05:41 +01:00
Palash Tyagi
dccbba9d1b Add examples for distribution helpers 2025-07-26 23:05:25 +01:00
Palash Tyagi
ab3509fef4 Added examples/stats_overview 2025-07-26 23:04:34 +01:00
f5c56d02e2
Merge branch 'main' into add-examples 2025-07-26 21:49:14 +01:00
069ef25ef4
Merge pull request #63 from Magnus167/update-runner
Fix package installation in runner Dockerfile
2025-07-26 21:41:08 +01:00
Palash Tyagi
f9a60608df attempting fix 2025-07-26 20:59:28 +01:00
526e22b1b7
Merge pull request #62 from Magnus167/update-cargo-authors
Add authors field to Cargo.toml
2025-07-26 20:54:53 +01:00
Palash Tyagi
845667c60a Add authors field to Cargo.toml 2025-07-26 20:53:47 +01:00
Palash Tyagi
3935e80be6 Fix typo in assertion 2025-07-26 20:35:47 +01:00
Palash Tyagi
0ce970308b Add step to run all examples in debug mode during unit tests 2025-07-26 20:33:28 +01:00
Palash Tyagi
72d02e2336 Add script to run all example programs with debug mode 2025-07-26 20:33:19 +01:00
Palash Tyagi
26213b28d6 Refactor GitHub Actions workflow to streamline unit tests and add example tests 2025-07-26 20:31:08 +01:00
Palash Tyagi
44ff16a0bb Refactor Game of Life example to support debug mode and improve board printing 2025-07-26 20:30:03 +01:00
Palash Tyagi
1192a78955 Add example demos to README.md 2025-07-26 18:38:53 +01:00
Palash Tyagi
d0f9e80dfc add test as examples 2025-07-26 18:38:27 +01:00
Palash Tyagi
b0d8050b11 add test as examples 2025-07-26 13:26:44 +01:00
Palash Tyagi
45ec754d47 add test as examples 2025-07-26 12:21:27 +01:00
Palash Tyagi
733a4da383 Add unit test in pca.rs 2025-07-26 10:51:35 +01:00
Palash Tyagi
ded5f1aa29 Add k-means examples 2025-07-26 04:06:12 +01:00
Palash Tyagi
fe9498963d Add linear regression examples 2025-07-26 04:05:56 +01:00
Palash Tyagi
6b580ec5eb Add logistic regression examples 2025-07-26 04:05:43 +01:00
Palash Tyagi
45f147e651 Add PCA examples 2025-07-26 04:05:27 +01:00
cd3aa84e60
Merge branch 'main' into csv 2025-07-06 11:35:13 +01:00
27275e2479
Merge branch 'main' into csv 2025-07-06 11:05:20 +01:00
9ef719316a
Merge branch 'main' into csv 2025-07-06 01:04:10 +01:00
960fd345c2
Merge branch 'main' into csv 2025-07-04 00:59:25 +01:00
325e75419c
Merge branch 'main' into csv 2025-06-07 13:38:30 +01:00
b1dc18d05b
Merge branch 'main' into csv 2025-05-15 18:35:46 +01:00
8cbb957764
Merge branch 'main' into csv 2025-05-13 00:08:38 +01:00
b937ed1cdf
Merge branch 'main' into csv 2025-05-11 02:00:25 +01:00
2e071a6974
Merge branch 'main' into csv 2025-05-05 02:13:15 +01:00
689169bab2
Merge branch 'main' into csv 2025-05-05 02:01:45 +01:00
a45a5ecf4e
Merge branch 'main' into csv 2025-05-04 02:29:12 +01:00
84e1b423f4
Merge branch 'main' into csv 2025-05-04 02:10:55 +01:00
197739bc2f
Merge branch 'main' into csv 2025-05-04 01:07:58 +01:00
d2c2ebca0f
Merge branch 'main' into csv 2025-05-03 01:32:05 +01:00
f5f3f2c100
Merge branch 'main' into csv 2025-05-02 23:38:37 +01:00
9fcb1ea2cf
Merge branch 'main' into csv 2025-05-01 01:14:09 +01:00
Palash Tyagi
623303cf72 Update README to include upcoming features for CSV I/O, Date Utils, and more math functions 2025-05-01 01:13:34 +01:00
26 changed files with 1572 additions and 32 deletions

View File

@ -7,7 +7,7 @@ ARG DEBIAN_FRONTEND=noninteractive
RUN apt update -y && apt upgrade -y && useradd -m docker
RUN apt install -y --no-install-recommends \
curl jq git unzip \
curl jq git zip unzip \
# dev dependencies
build-essential libssl-dev libffi-dev python3 python3-venv python3-dev python3-pip \
# dot net core dependencies

16
.github/scripts/run_examples.sh vendored Normal file
View File

@ -0,0 +1,16 @@
cargo build --release --examples
for ex in examples/*.rs; do
name=$(basename "$ex" .rs)
echo
echo "🟡 Running example: $name"
if ! cargo run --release --example "$name" -- --debug; then
echo
echo "❌ Example '$name' failed. Aborting."
exit 1
fi
done
echo
echo "✅ All examples ran successfully."

View File

@ -12,14 +12,12 @@ concurrency:
jobs:
pick-runner:
if: github.event.pull_request.draft == false
runs-on: ubuntu-latest
outputs:
runner: ${{ steps.choose.outputs.use-runner }}
steps:
- uses: actions/checkout@v4
- id: choose
uses: ./.github/actions/runner-fallback
@ -27,7 +25,6 @@ jobs:
primary-runner: "self-hosted"
fallback-runner: "ubuntu-latest"
github-token: ${{ secrets.CUSTOM_GH_TOKEN }}
run-unit-tests:
needs: pick-runner
@ -56,6 +53,20 @@ jobs:
- name: Test docs generation
run: cargo doc --no-deps --release
- name: Test examples
run: cargo test --examples --release
- name: Run all examples
run: |
for example in examples/*.rs; do
name=$(basename "$example" .rs)
echo "Running example: $name"
cargo run --release --example "$name" -- --debug || exit 1
done
- name: Cargo test all targets
run: cargo test --all-targets --release
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v3
with:

View File

@ -1,5 +1,6 @@
[package]
name = "rustframe"
authors = ["Palash Tyagi (https://github.com/Magnus167)"]
version = "0.0.1-a.20250716"
edition = "2021"
license = "GPL-3.0-or-later"
@ -14,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"]

View File

@ -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
@ -55,6 +55,12 @@ The `compute` module provides implementations for various statistical computatio
- Logistic Regression
- Principal Component Analysis
### Coming soon
- **CSV I/O** - read/write CSV files with a simple API.
- **Date Utils** - date math, calendar slicing, indexing, and more.
- **More math** - more math functions and aggregations.
### Heads up
- **Not memoryefficient (yet)** - footprint needs work.
@ -64,6 +70,7 @@ The `compute` module provides implementations for various statistical computatio
- Optional GPU acceleration (Vulkan or similar) for heavier workloads.
- Straightforward Python bindings using `pyo3`.
- Integration with common ML libraries, or introduce simple ML features.
---
@ -192,6 +199,29 @@ E.g. to run the `game_of_life` example:
cargo run --example game_of_life
```
More demos:
```bash
cargo run --example linear_regression
cargo run --example logistic_regression
cargo run --example k_means
cargo run --example pca
cargo run --example stats_overview
cargo run --example descriptive_stats
cargo run --example correlation
cargo run --example inferential_stats
cargo run --example distributions
```
To simply list all available examples, you can run:
```bash
# this technically raises an error, but it will list all examples
cargo run --example
```
Each demo runs a couple of mini-scenarios showcasing the APIs.
### Running benchmarks
To run the benchmarks, use:

45
examples/correlation.rs Normal file
View File

@ -0,0 +1,45 @@
use rustframe::compute::stats::{covariance, covariance_matrix, pearson};
use rustframe::matrix::{Axis, Matrix};
/// Demonstrates covariance and correlation utilities.
fn main() {
pairwise_cov();
println!("\n-----\n");
matrix_cov();
}
fn pairwise_cov() {
println!("Covariance & Pearson r\n----------------------");
let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let y = Matrix::from_vec(vec![1.0, 2.0, 3.0, 5.0], 2, 2);
println!("covariance : {:.2}", covariance(&x, &y));
println!("pearson r : {:.3}", pearson(&x, &y));
}
fn matrix_cov() {
println!("Covariance matrix\n-----------------");
let data = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let cov = covariance_matrix(&data, Axis::Col);
println!("cov matrix : {:?}", cov.data());
}
#[cfg(test)]
mod tests {
use super::*;
const EPS: f64 = 1e-8;
#[test]
fn test_pairwise_cov() {
let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let y = Matrix::from_vec(vec![1.0, 2.0, 3.0, 5.0], 2, 2);
assert!((covariance(&x, &y) - 1.625).abs() < EPS);
assert!((pearson(&x, &y) - 0.9827076298239908).abs() < 1e-5,);
}
#[test]
fn test_matrix_cov() {
let data = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let cov = covariance_matrix(&data, Axis::Col);
assert_eq!(cov.data(), &[2.0, 2.0, 2.0, 2.0]);
}
}

View File

@ -0,0 +1,56 @@
use rustframe::compute::stats::{mean, mean_horizontal, mean_vertical, median, percentile, stddev};
use rustframe::matrix::Matrix;
/// Demonstrates descriptive statistics utilities.
///
/// Part 1: simple mean/stddev/median/percentile on a vector.
/// Part 2: mean across rows and columns.
fn main() {
simple_stats();
println!("\n-----\n");
axis_stats();
}
fn simple_stats() {
println!("Basic stats\n-----------");
let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
println!("mean : {:.2}", mean(&data));
println!("stddev : {:.2}", stddev(&data));
println!("median : {:.2}", median(&data));
println!("90th pct. : {:.2}", percentile(&data, 90.0));
}
fn axis_stats() {
println!("Row/column means\n----------------");
// 2x3 matrix
let data = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 2, 3);
let v = mean_vertical(&data); // 1x3
let h = mean_horizontal(&data); // 2x1
println!("vertical means : {:?}", v.data());
println!("horizontal means: {:?}", h.data());
}
#[cfg(test)]
mod tests {
use super::*;
const EPS: f64 = 1e-8;
#[test]
fn test_simple_stats() {
let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
assert!((mean(&data) - 3.0).abs() < EPS);
assert!((stddev(&data) - 1.4142135623730951).abs() < EPS);
assert!((median(&data) - 3.0).abs() < EPS);
assert!((percentile(&data, 90.0) - 5.0).abs() < EPS);
}
#[test]
fn test_axis_stats() {
let data = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 2, 3);
let v = mean_vertical(&data);
assert_eq!(v.data(), &[2.5, 3.5, 4.5]);
let h = mean_horizontal(&data);
assert_eq!(h.data(), &[2.0, 5.0]);
}
}

66
examples/distributions.rs Normal file
View File

@ -0,0 +1,66 @@
use rustframe::compute::stats::{binomial_cdf, binomial_pmf, normal_cdf, normal_pdf, poisson_pmf};
use rustframe::matrix::Matrix;
/// Demonstrates some probability distribution helpers.
fn main() {
normal_example();
println!("\n-----\n");
binomial_example();
println!("\n-----\n");
poisson_example();
}
fn normal_example() {
println!("Normal distribution\n-------------------");
let x = Matrix::from_vec(vec![0.0, 1.0], 1, 2);
let pdf = normal_pdf(x.clone(), 0.0, 1.0);
let cdf = normal_cdf(x, 0.0, 1.0);
println!("pdf : {:?}", pdf.data());
println!("cdf : {:?}", cdf.data());
}
fn binomial_example() {
println!("Binomial distribution\n---------------------");
let k = Matrix::from_vec(vec![0_u64, 1, 2], 1, 3);
let pmf = binomial_pmf(4, k.clone(), 0.5);
let cdf = binomial_cdf(4, k, 0.5);
println!("pmf : {:?}", pmf.data());
println!("cdf : {:?}", cdf.data());
}
fn poisson_example() {
println!("Poisson distribution\n--------------------");
let k = Matrix::from_vec(vec![0_u64, 1, 2], 1, 3);
let pmf = poisson_pmf(3.0, k);
println!("pmf : {:?}", pmf.data());
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_normal_example() {
let x = Matrix::from_vec(vec![0.0, 1.0], 1, 2);
let pdf = normal_pdf(x.clone(), 0.0, 1.0);
let cdf = normal_cdf(x, 0.0, 1.0);
assert!((pdf.get(0, 0) - 0.39894228).abs() < 1e-6);
assert!((cdf.get(0, 1) - 0.8413447).abs() < 1e-6);
}
#[test]
fn test_binomial_example() {
let k = Matrix::from_vec(vec![0_u64, 1, 2], 1, 3);
let pmf = binomial_pmf(4, k.clone(), 0.5);
let cdf = binomial_cdf(4, k, 0.5);
assert!((pmf.get(0, 2) - 0.375).abs() < 1e-6);
assert!((cdf.get(0, 2) - 0.6875).abs() < 1e-6);
}
#[test]
fn test_poisson_example() {
let k = Matrix::from_vec(vec![0_u64, 1, 2], 1, 3);
let pmf = poisson_pmf(3.0, k);
assert!((pmf.get(0, 1) - 3.0_f64 * (-3.0_f64).exp()).abs() < 1e-6);
}
}

View File

@ -1,11 +1,26 @@
use rand::{self, Rng};
//! Conway's Game of Life Example
//! This example implements Conway's Game of Life using a `BoolMatrix` to represent the game board.
//! It demonstrates matrix operations like shifting, counting neighbors, and applying game rules.
//! The game runs in a loop, updating the board state and printing it to the console.
//! To modify the behaviour of the example, please change the constants at the top of this file.
//! By default,
use rustframe::matrix::{BoolMatrix, BoolOps, IntMatrix, Matrix};
use rustframe::random::{rng, Rng};
use std::{thread, time};
const BOARD_SIZE: usize = 50; // Size of the board (50x50)
const TICK_DURATION_MS: u64 = 10; // Milliseconds per frame
const BOARD_SIZE: usize = 20; // Size of the board (50x50)
const MAX_FRAMES: u32 = 1000;
const TICK_DURATION_MS: u64 = 0; // Milliseconds per frame
const SKIP_FRAMES: u32 = 1;
const PRINT_BOARD: bool = true; // Set to false to disable printing the board
fn main() {
let args = std::env::args().collect::<Vec<String>>();
let debug_mode = args.contains(&"--debug".to_string());
let print_mode = if debug_mode { false } else { PRINT_BOARD };
// Initialize the game board.
// This demonstrates `BoolMatrix::from_vec`.
let mut current_board =
@ -24,20 +39,12 @@ fn main() {
let mut print_bool_int = 0;
loop {
// print!("{}[2J", 27 as char); // Clear screen and move cursor to top-left
// if print_board_bool {
if print_bool_int % 10 == 0 {
print!("{}[2J", 27 as char);
println!("Conway's Game of Life - Generation: {}", generation_count);
if print_bool_int % SKIP_FRAMES == 0 {
print_board(&current_board, generation_count, print_mode);
print_board(&current_board);
println!("Alive cells: {}", &current_board.count());
// print_board_bool = false;
print_bool_int = 0;
} else {
// print_board_bool = true;
print_bool_int += 1;
}
// `current_board.count()` demonstrates a method from `BoolOps`.
@ -71,10 +78,10 @@ fn main() {
generation_count += 1;
thread::sleep(time::Duration::from_millis(TICK_DURATION_MS));
// if generation_count > 500 { // Optional limit
// println!("\nReached generation limit.");
// break;
// }
if (MAX_FRAMES > 0) && (generation_count > MAX_FRAMES) {
println!("\nReached generation limit.");
break;
}
}
}
@ -82,7 +89,13 @@ fn main() {
///
/// - `board`: A reference to the `BoolMatrix` representing the current game state.
/// This function demonstrates `board.rows()`, `board.cols()`, and `board[(r, c)]` (Index trait).
fn print_board(board: &BoolMatrix) {
fn print_board(board: &BoolMatrix, generation_count: u32, print_mode: bool) {
if !print_mode {
return;
}
print!("{}[2J", 27 as char);
println!("Conway's Game of Life - Generation: {}", generation_count);
let mut print_str = String::new();
print_str.push_str("+");
for _ in 0..board.cols() {
@ -107,6 +120,8 @@ fn print_board(board: &BoolMatrix) {
}
print_str.push_str("+\n\n");
print!("{}", print_str);
println!("Alive cells: {}", board.count());
}
/// Helper function to create a shifted version of the game board.
@ -250,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 {
@ -266,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 {

View File

@ -0,0 +1,66 @@
use rustframe::compute::stats::{anova, chi2_test, t_test};
use rustframe::matrix::Matrix;
/// Demonstrates simple inferential statistics tests.
fn main() {
t_test_demo();
println!("\n-----\n");
chi2_demo();
println!("\n-----\n");
anova_demo();
}
fn t_test_demo() {
println!("Two-sample t-test\n-----------------");
let a = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
let b = Matrix::from_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
let (t, p) = t_test(&a, &b);
println!("t statistic: {:.2}, p-value: {:.4}", t, p);
}
fn chi2_demo() {
println!("Chi-square test\n---------------");
let observed = Matrix::from_vec(vec![12.0, 5.0, 8.0, 10.0], 2, 2);
let (chi2, p) = chi2_test(&observed);
println!("chi^2: {:.2}, p-value: {:.4}", chi2, p);
}
fn anova_demo() {
println!("One-way ANOVA\n-------------");
let g1 = Matrix::from_vec(vec![1.0, 2.0, 3.0], 1, 3);
let g2 = Matrix::from_vec(vec![2.0, 3.0, 4.0], 1, 3);
let g3 = Matrix::from_vec(vec![3.0, 4.0, 5.0], 1, 3);
let (f, p) = anova(vec![&g1, &g2, &g3]);
println!("F statistic: {:.2}, p-value: {:.4}", f, p);
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_t_test_demo() {
let a = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
let b = Matrix::from_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
let (t, _p) = t_test(&a, &b);
assert!((t + 5.0).abs() < 1e-5);
}
#[test]
fn test_chi2_demo() {
let observed = Matrix::from_vec(vec![12.0, 5.0, 8.0, 10.0], 2, 2);
let (chi2, p) = chi2_test(&observed);
assert!(chi2 > 0.0);
assert!(p > 0.0 && p < 1.0);
}
#[test]
fn test_anova_demo() {
let g1 = Matrix::from_vec(vec![1.0, 2.0, 3.0], 1, 3);
let g2 = Matrix::from_vec(vec![2.0, 3.0, 4.0], 1, 3);
let g3 = Matrix::from_vec(vec![3.0, 4.0, 5.0], 1, 3);
let (f, p) = anova(vec![&g1, &g2, &g3]);
assert!(f > 0.0);
assert!(p > 0.0 && p < 1.0);
}
}

65
examples/k_means.rs Normal file
View File

@ -0,0 +1,65 @@
use rustframe::compute::models::k_means::KMeans;
use rustframe::matrix::Matrix;
/// Two quick K-Means clustering demos.
///
/// Example 1 groups store locations on a city map.
/// Example 2 segments customers by annual spending habits.
fn main() {
city_store_example();
println!("\n-----\n");
customer_spend_example();
}
fn city_store_example() {
println!("Example 1: store locations");
// (x, y) coordinates of stores around a city
let raw = vec![
1.0, 2.0, 1.5, 1.8, 5.0, 8.0, 8.0, 8.0, 1.0, 0.6, 9.0, 11.0, 8.0, 2.0, 10.0, 2.0, 9.0, 3.0,
];
let x = Matrix::from_rows_vec(raw, 9, 2);
// Group stores into two areas
let (model, labels) = KMeans::fit(&x, 2, 100, 1e-4);
println!("Centres: {:?}", model.centroids.data());
println!("Labels: {:?}", labels);
let new_points = Matrix::from_rows_vec(vec![0.0, 0.0, 8.0, 3.0], 2, 2);
let pred = model.predict(&new_points);
println!("New store assignments: {:?}", pred);
}
fn customer_spend_example() {
println!("Example 2: customer spending");
// (grocery spend, electronics spend) in dollars
let raw = vec![
200.0, 150.0, 220.0, 170.0, 250.0, 160.0, 800.0, 750.0, 820.0, 760.0, 790.0, 770.0,
];
let x = Matrix::from_rows_vec(raw, 6, 2);
let (model, labels) = KMeans::fit(&x, 2, 100, 1e-4);
println!("Centres: {:?}", model.centroids.data());
println!("Labels: {:?}", labels);
let new_customers = Matrix::from_rows_vec(vec![230.0, 155.0, 810.0, 760.0], 2, 2);
let pred = model.predict(&new_customers);
println!("Cluster of new customers: {:?}", pred);
}
#[test]
fn k_means_store_locations() {
let raw = vec![
1.0, 2.0, 1.5, 1.8, 5.0, 8.0, 8.0, 8.0, 1.0, 0.6, 9.0, 11.0, 8.0, 2.0, 10.0, 2.0, 9.0, 3.0,
];
let x = Matrix::from_rows_vec(raw, 9, 2);
let (model, labels) = KMeans::fit(&x, 2, 100, 1e-4);
assert_eq!(labels.len(), 9);
assert_eq!(model.centroids.rows(), 2);
let new_points = Matrix::from_rows_vec(vec![0.0, 0.0, 8.0, 3.0], 2, 2);
let pred = model.predict(&new_points);
assert_eq!(pred.len(), 2);
}

View File

@ -0,0 +1,118 @@
use rustframe::compute::models::linreg::LinReg;
use rustframe::matrix::Matrix;
/// Two quick linear regression demonstrations.
///
/// Example 1 fits a model to predict house price from floor area.
/// Example 2 adds number of bedrooms as a second feature.
fn main() {
example_one_feature();
println!("\n-----\n");
example_two_features();
}
/// Price ~ floor area
fn example_one_feature() {
println!("Example 1: predict price from floor area only");
// Square meters of floor area for a few houses
let sizes = vec![50.0, 60.0, 70.0, 80.0, 90.0, 100.0];
// Thousands of dollars in sale price
let prices = vec![150.0, 180.0, 210.0, 240.0, 270.0, 300.0];
// Each row is a sample with one feature
let x = Matrix::from_vec(sizes.clone(), sizes.len(), 1);
let y = Matrix::from_vec(prices.clone(), prices.len(), 1);
// Train with a small learning rate
let mut model = LinReg::new(1);
model.fit(&x, &y, 0.0005, 20000);
let preds = model.predict(&x);
println!("Size (m^2) -> predicted price (k) vs actual");
for i in 0..x.rows() {
println!(
"{:>3} -> {:>6.1} | {:>6.1}",
sizes[i],
preds[(i, 0)],
prices[i]
);
}
let new_house = Matrix::from_vec(vec![120.0], 1, 1);
let pred = model.predict(&new_house);
println!("Predicted price for 120 m^2: {:.1}k", pred[(0, 0)]);
}
/// Price ~ floor area + bedrooms
fn example_two_features() {
println!("Example 2: price from area and bedrooms");
// (size m^2, bedrooms) for each house
let raw_x = vec![
50.0, 2.0, 70.0, 2.0, 90.0, 3.0, 110.0, 3.0, 130.0, 4.0, 150.0, 4.0,
];
let prices = vec![160.0, 195.0, 250.0, 285.0, 320.0, 350.0];
let x = Matrix::from_rows_vec(raw_x, 6, 2);
let y = Matrix::from_vec(prices.clone(), prices.len(), 1);
let mut model = LinReg::new(2);
model.fit(&x, &y, 0.0001, 50000);
let preds = model.predict(&x);
println!("size, beds -> predicted | actual (k)");
for i in 0..x.rows() {
let size = x[(i, 0)];
let beds = x[(i, 1)];
println!(
"{:>3} m^2, {:>1} -> {:>6.1} | {:>6.1}",
size,
beds,
preds[(i, 0)],
prices[i]
);
}
let new_home = Matrix::from_rows_vec(vec![120.0, 3.0], 1, 2);
let pred = model.predict(&new_home);
println!(
"Predicted price for 120 m^2 with 3 bedrooms: {:.1}k",
pred[(0, 0)]
);
}
#[test]
fn test_linear_regression_one_feature() {
let sizes = vec![50.0, 60.0, 70.0, 80.0, 90.0, 100.0];
let prices = vec![150.0, 180.0, 210.0, 240.0, 270.0, 300.0];
let scaled: Vec<f64> = sizes.iter().map(|s| s / 100.0).collect();
let x = Matrix::from_vec(scaled, sizes.len(), 1);
let y = Matrix::from_vec(prices.clone(), prices.len(), 1);
let mut model = LinReg::new(1);
model.fit(&x, &y, 0.1, 2000);
let preds = model.predict(&x);
for i in 0..y.rows() {
assert!((preds[(i, 0)] - prices[i]).abs() < 1.0);
}
}
#[test]
fn test_linear_regression_two_features() {
let raw_x = vec![
50.0, 2.0, 70.0, 2.0, 90.0, 3.0, 110.0, 3.0, 130.0, 4.0, 150.0, 4.0,
];
let prices = vec![170.0, 210.0, 270.0, 310.0, 370.0, 410.0];
let scaled_x: Vec<f64> = raw_x
.chunks(2)
.flat_map(|pair| vec![pair[0] / 100.0, pair[1]])
.collect();
let x = Matrix::from_rows_vec(scaled_x, 6, 2);
let y = Matrix::from_vec(prices.clone(), prices.len(), 1);
let mut model = LinReg::new(2);
model.fit(&x, &y, 0.01, 50000);
let preds = model.predict(&x);
for i in 0..y.rows() {
assert!((preds[(i, 0)] - prices[i]).abs() < 1.0);
}
}

View File

@ -0,0 +1,101 @@
use rustframe::compute::models::logreg::LogReg;
use rustframe::matrix::Matrix;
/// Two binary classification demos using logistic regression.
///
/// Example 1 predicts exam success from hours studied.
/// Example 2 predicts whether an online shopper will make a purchase.
fn main() {
student_passing_example();
println!("\n-----\n");
purchase_prediction_example();
}
fn student_passing_example() {
println!("Example 1: exam pass prediction");
// Hours studied for each student
let hours = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
// 0 = fail, 1 = pass
let passed = vec![0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1.0];
let x = Matrix::from_vec(hours.clone(), hours.len(), 1);
let y = Matrix::from_vec(passed.clone(), passed.len(), 1);
let mut model = LogReg::new(1);
model.fit(&x, &y, 0.1, 10000);
let preds = model.predict(&x);
println!("Hours -> pred | actual");
for i in 0..x.rows() {
println!(
"{:>2} -> {} | {}",
hours[i] as i32,
preds[(i, 0)] as i32,
passed[i] as i32
);
}
// Probability estimate for a new student
let new_student = Matrix::from_vec(vec![5.5], 1, 1);
let p = model.predict_proba(&new_student);
println!("Probability of passing with 5.5h study: {:.2}", p[(0, 0)]);
}
fn purchase_prediction_example() {
println!("Example 2: purchase likelihood");
// minutes on site, pages viewed -> made a purchase?
let raw_x = vec![1.0, 2.0, 3.0, 1.0, 2.0, 4.0, 5.0, 5.0, 3.5, 2.0, 6.0, 6.0];
let bought = vec![0.0, 0.0, 0.0, 1.0, 0.0, 1.0];
let x = Matrix::from_rows_vec(raw_x, 6, 2);
let y = Matrix::from_vec(bought.clone(), bought.len(), 1);
let mut model = LogReg::new(2);
model.fit(&x, &y, 0.05, 20000);
let preds = model.predict(&x);
println!("time, pages -> pred | actual");
for i in 0..x.rows() {
println!(
"{:>4}m, {:>2} -> {} | {}",
x[(i, 0)],
x[(i, 1)] as i32,
preds[(i, 0)] as i32,
bought[i] as i32
);
}
let new_visit = Matrix::from_rows_vec(vec![4.0, 4.0], 1, 2);
let p = model.predict_proba(&new_visit);
println!("Prob of purchase for 4min/4pages: {:.2}", p[(0, 0)]);
}
#[test]
fn test_student_passing_example() {
let hours = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
let passed = vec![0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1.0];
let x = Matrix::from_vec(hours.clone(), hours.len(), 1);
let y = Matrix::from_vec(passed.clone(), passed.len(), 1);
let mut model = LogReg::new(1);
model.fit(&x, &y, 0.1, 10000);
let preds = model.predict(&x);
for i in 0..y.rows() {
assert_eq!(preds[(i, 0)], passed[i]);
}
}
#[test]
fn test_purchase_prediction_example() {
let raw_x = vec![1.0, 2.0, 3.0, 1.0, 2.0, 4.0, 5.0, 5.0, 3.5, 2.0, 6.0, 6.0];
let bought = vec![0.0, 0.0, 0.0, 1.0, 0.0, 1.0];
let x = Matrix::from_rows_vec(raw_x, 6, 2);
let y = Matrix::from_vec(bought.clone(), bought.len(), 1);
let mut model = LogReg::new(2);
model.fit(&x, &y, 0.05, 20000);
let preds = model.predict(&x);
for i in 0..y.rows() {
assert_eq!(preds[(i, 0)], bought[i]);
}
}

60
examples/pca.rs Normal file
View File

@ -0,0 +1,60 @@
use rustframe::compute::models::pca::PCA;
use rustframe::matrix::Matrix;
/// Two dimensionality reduction examples using PCA.
///
/// Example 1 reduces 3D sensor readings to two components.
/// Example 2 compresses a small four-feature dataset.
fn main() {
sensor_demo();
println!("\n-----\n");
finance_demo();
}
fn sensor_demo() {
println!("Example 1: 3D sensor data");
// Ten 3D observations from an accelerometer
let raw = vec![
2.5, 2.4, 0.5, 0.5, 0.7, 1.5, 2.2, 2.9, 0.7, 1.9, 2.2, 1.0, 3.1, 3.0, 0.6, 2.3, 2.7, 0.9,
2.0, 1.6, 1.1, 1.0, 1.1, 1.9, 1.5, 1.6, 2.2, 1.1, 0.9, 2.1,
];
let x = Matrix::from_rows_vec(raw, 10, 3);
let pca = PCA::fit(&x, 2, 0);
let reduced = pca.transform(&x);
println!("Components: {:?}", pca.components.data());
println!("First row -> {:.2?}", [reduced[(0, 0)], reduced[(0, 1)]]);
}
fn finance_demo() {
println!("Example 2: 4D finance data");
// Four daily percentage returns of different stocks
let raw = vec![
0.2, 0.1, -0.1, 0.0, 0.3, 0.2, -0.2, 0.1, 0.1, 0.0, -0.1, -0.1, 0.4, 0.3, -0.3, 0.2, 0.0,
-0.1, 0.1, -0.1,
];
let x = Matrix::from_rows_vec(raw, 5, 4);
// Keep two principal components
let pca = PCA::fit(&x, 2, 0);
let reduced = pca.transform(&x);
println!("Reduced shape: {:?}", reduced.shape());
println!("First row -> {:.2?}", [reduced[(0, 0)], reduced[(0, 1)]]);
}
#[test]
fn test_sensor_demo() {
let raw = vec![
2.5, 2.4, 0.5, 0.5, 0.7, 1.5, 2.2, 2.9, 0.7, 1.9, 2.2, 1.0, 3.1, 3.0, 0.6, 2.3, 2.7, 0.9,
2.0, 1.6, 1.1, 1.0, 1.1, 1.9, 1.5, 1.6, 2.2, 1.1, 0.9, 2.1,
];
let x = Matrix::from_rows_vec(raw, 10, 3);
let pca = PCA::fit(&x, 2, 0);
let reduced = pca.transform(&x);
assert_eq!(reduced.rows(), 10);
assert_eq!(reduced.cols(), 2);
}

67
examples/random_demo.rs Normal file
View File

@ -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);
}
}
}

57
examples/random_stats.rs Normal file
View File

@ -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();
}
}

View File

@ -0,0 +1,93 @@
use rustframe::compute::stats::{
chi2_test, covariance, covariance_matrix, mean, median, pearson, percentile, stddev, t_test,
};
use rustframe::matrix::{Axis, Matrix};
/// Demonstrates some of the statistics utilities in Rustframe.
///
/// The example is split into three parts:
/// 1. Basic descriptive statistics on a small data set.
/// 2. Covariance and correlation calculations.
/// 3. Simple inferential tests (t-test and chi-square).
fn main() {
descriptive_demo();
println!("\n-----\n");
correlation_demo();
println!("\n-----\n");
inferential_demo();
}
fn descriptive_demo() {
println!("Descriptive statistics\n----------------------");
let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
println!("mean : {:.2}", mean(&data));
println!("std dev : {:.2}", stddev(&data));
println!("median : {:.2}", median(&data));
println!("25th percentile: {:.2}", percentile(&data, 25.0));
}
fn correlation_demo() {
println!("Covariance and Correlation\n--------------------------");
let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let y = Matrix::from_vec(vec![1.0, 2.0, 3.0, 5.0], 2, 2);
let cov = covariance(&x, &y);
let cov_mat = covariance_matrix(&x, Axis::Col);
let corr = pearson(&x, &y);
println!("covariance : {:.2}", cov);
println!("cov matrix : {:?}", cov_mat.data());
println!("pearson r : {:.2}", corr);
}
fn inferential_demo() {
println!("Inferential statistics\n----------------------");
let s1 = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
let s2 = Matrix::from_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
let (t_stat, t_p) = t_test(&s1, &s2);
println!("t statistic : {:.2}, p-value: {:.4}", t_stat, t_p);
let observed = Matrix::from_vec(vec![12.0, 5.0, 8.0, 10.0], 2, 2);
let (chi2, chi_p) = chi2_test(&observed);
println!("chi^2 : {:.2}, p-value: {:.4}", chi2, chi_p);
}
#[cfg(test)]
mod tests {
use super::*;
const EPS: f64 = 1e-8;
#[test]
fn test_descriptive_demo() {
let data = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
assert!((mean(&data) - 3.0).abs() < EPS);
assert!((stddev(&data) - 1.4142135623730951).abs() < EPS);
assert!((median(&data) - 3.0).abs() < EPS);
assert!((percentile(&data, 25.0) - 2.0).abs() < EPS);
}
#[test]
fn test_correlation_demo() {
let x = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0], 2, 2);
let y = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 5.0], 2, 2);
let cov = covariance(&x, &y);
assert!((cov - 1.625).abs() < EPS);
let cov_mat = covariance_matrix(&x, Axis::Col);
assert!((cov_mat.get(0, 0) - 2.0).abs() < EPS);
assert!((cov_mat.get(1, 1) - 2.0).abs() < EPS);
let corr = pearson(&x, &y);
assert!((corr - 0.9827076298239908).abs() < 1e-6);
}
#[test]
fn test_inferential_demo() {
let s1 = Matrix::from_rows_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0], 1, 5);
let s2 = Matrix::from_rows_vec(vec![6.0, 7.0, 8.0, 9.0, 10.0], 1, 5);
let (t_stat, p_value) = t_test(&s1, &s2);
assert!((t_stat + 5.0).abs() < 1e-5);
assert!(p_value > 0.0 && p_value < 1.0);
let observed = Matrix::from_rows_vec(vec![12.0, 5.0, 8.0, 10.0], 2, 2);
let (chi2, p) = chi2_test(&observed);
assert!(chi2 > 0.0);
assert!(p > 0.0 && p < 1.0);
}
}

View File

@ -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::*;

View File

@ -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 {

View File

@ -1,7 +1,6 @@
use crate::compute::stats::mean_vertical;
use crate::matrix::Matrix;
use rand::rng;
use rand::seq::SliceRandom;
use crate::random::prelude::*;
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);
}
}

View File

@ -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;

227
src/random/crypto.rs Normal file
View File

@ -0,0 +1,227 @@
#[cfg(unix)]
use std::{fs::File, io::Read};
use crate::random::Rng;
#[cfg(unix)]
pub struct CryptoRng {
file: File,
}
#[cfg(unix)]
impl CryptoRng {
/// Open `/dev/urandom`.
pub fn new() -> Self {
let file = File::open("/dev/urandom").expect("failed to open /dev/urandom");
Self { file }
}
}
#[cfg(unix)]
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)
}
}
#[cfg(windows)]
pub struct CryptoRng;
#[cfg(windows)]
impl CryptoRng {
/// No handle is needed on Windows.
pub fn new() -> Self {
Self
}
}
#[cfg(windows)]
impl Rng for CryptoRng {
fn next_u64(&mut self) -> u64 {
let mut buf = [0u8; 8];
win_fill(&mut buf).expect("BCryptGenRandom failed");
u64::from_ne_bytes(buf)
}
}
/// Fill `buf` with cryptographically secure random bytes using CNG.
///
/// * `BCryptGenRandom(NULL, buf, len, BCRYPT_USE_SYSTEM_PREFERRED_RNG)`
/// asks the OS for its systempreferred DRBG (CTR_DRBG on modern
/// Windows).
#[cfg(windows)]
fn win_fill(buf: &mut [u8]) -> Result<(), ()> {
use core::ffi::c_void;
type BcryptAlgHandle = *mut c_void;
type NTSTATUS = i32;
const BCRYPT_USE_SYSTEM_PREFERRED_RNG: u32 = 0x0000_0002;
#[link(name = "bcrypt")]
extern "system" {
fn BCryptGenRandom(
hAlgorithm: BcryptAlgHandle,
pbBuffer: *mut u8,
cbBuffer: u32,
dwFlags: u32,
) -> NTSTATUS;
}
// NT_SUCCESS(status) == status >= 0
let status = unsafe {
BCryptGenRandom(
core::ptr::null_mut(),
buf.as_mut_ptr(),
buf.len() as u32,
BCRYPT_USE_SYSTEM_PREFERRED_RNG,
)
};
if status >= 0 {
Ok(())
} else {
Err(())
}
}
/// 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);
}
}

14
src/random/mod.rs Normal file
View File

@ -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};
}

227
src/random/prng.rs Normal file
View File

@ -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);
}
}

98
src/random/random_core.rs Normal file
View File

@ -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);
}
}
}

105
src/random/seq.rs Normal file
View File

@ -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}");
}
}