feat(bench): add Criterion.rs benchmark scaffold (mohu-benchmarks)

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'
     steps:
-      - uses: christophebedard/dco-check@v0.5.0
+      - uses: christophebedard/dco-check@0.5.1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 

Cargo.toml

@@ -28,6 +28,7 @@ members = [
 
     # ── Developer tooling ─────────────────────────────────────────────────────
     "crates/mohu-testing",    # test fixtures, property tests, array comparison
+    "crates/mohu-benchmarks",
 ]
 resolver = "2"
 
@@ -104,6 +105,7 @@ serde        = { version = "1", features = ["derive"] }
 
 # ── I/O ───────────────────────────────────────────────────────────────────────
 memmap2      = "0.9"
+csv          = "1.4"
 
 # ── Python bindings ───────────────────────────────────────────────────────────
 pyo3         = { version = "0.23", features = ["extension-module"] }

README.md

@@ -26,6 +26,15 @@ Polars proved you can rewrite the data layer in Rust and win. mohu is that same
 
 Early. The foundation is being laid. If you believe the Python numerical stack deserves a rewrite, watch this repo or contribute.
 
+## windows
+
+On Windows, use `scripts/use-llvm-mingw.ps1` to run the `mohu-io` test target
+with the LLVM-MinGW linker setup that works in this workspace.
+
+```powershell
+.\scripts\use-llvm-mingw.ps1
+```
+
 ## built with
 
 - [Rust](https://rust-lang.org)

crates/mohu-array/src/array.rs

@@ -0,0 +1 @@
+

crates/mohu-array/src/iter.rs

@@ -0,0 +1 @@
+

crates/mohu-array/src/shape.rs

@@ -0,0 +1 @@
+

crates/mohu-array/src/slice.rs

@@ -0,0 +1 @@
+

crates/mohu-array/src/view.rs

@@ -0,0 +1 @@
+

crates/mohu-benchmarks/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "mohu-benchmarks"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+criterion = { version = "0.4", features = ["html_reports"] }
+# Use the workspace mohu-array crate when available; maintainers can enable this
+# once the public API for benchmarks is agreed.
+mohu-array = { workspace = true }
+
+[package.metadata]
+description = "Benchmark suite scaffolding for the Mohu project using Criterion.rs"
+repository = "https://github.com/mohu-org/mohu"

crates/mohu-benchmarks/README.md

@@ -0,0 +1,23 @@
+# Mohu Benchmarks
+
+This crate provides a Criterion.rs-based benchmark scaffold for the Mohu project. It intentionally starts small with well-documented microbenchmarks for:
+
+- Element-wise arithmetic (vector add)
+- Reduction (sum)
+- Memory stride access comparison (row-major vs column-major scanning)
+
+Maintainers and contributors should extend this suite with:
+
+- `mohu-array` focused benchmarks for `compute`, `ufunc`, `ops` paths
+- I/O benchmarks for `.npy`/.csv` using `mohu-io`
+- Cross-comparisons with NumPy (scripted externally via Python)
+- SIMD vs scalar kernels and threaded vs sequential experiments
+
+Run locally:
+
+```sh
+cd crates/mohu-benchmarks
+cargo bench --bench bench_core
+```
+
+CI integration recommendation: run benchmarks in a scheduled job, store the resulting Criterion reports/artifacts in an S3-compatible storage, and detect regressions by comparing specific baseline outputs or trend analysis.

crates/mohu-benchmarks/benches/bench_core.rs

@@ -0,0 +1,70 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+// Lightweight core benchmarks scaffold. These are intentionally simple and
+// provide maintainers a starting point to add mohu-array-specific benchmarks.
+
+fn bench_arithmetic_add(c: &mut Criterion) {
+    let size = 1_000_000usize;
+    let a: Vec<f64> = (0..size).map(|i| (i as f64) * 0.5).collect();
+    let b: Vec<f64> = (0..size).map(|i| (i as f64) * 1.5).collect();
+
+    c.bench_function("vec_add_iter", |bencher| {
+        bencher.iter(|| {
+            let mut r = vec![0.0f64; size];
+            for i in 0..size {
+                r[i] = black_box(a[i]) + black_box(b[i]);
+            }
+            black_box(r)
+        })
+    });
+}
+
+fn bench_reduction_sum(c: &mut Criterion) {
+    let size = 2_000_000usize;
+    let a: Vec<f64> = (0..size).map(|i| (i as f64) * 0.25).collect();
+
+    c.bench_function("vec_sum_iter", |bencher| {
+        bencher.iter(|| {
+            let mut s = 0.0f64;
+            for &v in &a {
+                s += black_box(v);
+            }
+            black_box(s)
+        })
+    });
+}
+
+fn bench_stride_access(c: &mut Criterion) {
+    let rows = 10_000usize;
+    let cols = 1_000usize;
+    // simulate flat storage
+    let mut data: Vec<f64> = vec![0.0; rows * cols];
+    for i in 0..(rows * cols) { data[i] = (i as f64) % 100.0; }
+
+    c.bench_function("row_major_sum", |bencher| {
+        bencher.iter(|| {
+            let mut s = 0.0f64;
+            for r in 0..rows {
+                for cidx in 0..cols {
+                    s += black_box(data[r * cols + cidx]);
+                }
+            }
+            black_box(s)
+        })
+    });
+
+    c.bench_function("col_major_sum", |bencher| {
+        bencher.iter(|| {
+            let mut s = 0.0f64;
+            for cidx in 0..cols {
+                for r in 0..rows {
+                    s += black_box(data[r * cols + cidx]);
+                }
+            }
+            black_box(s)
+        })
+    });
+}
+
+criterion_group!(benches, bench_arithmetic_add, bench_reduction_sum, bench_stride_access);
+criterion_main!(benches);

crates/mohu-buffer/examples/alloc_and_pool.rs

@@ -7,10 +7,8 @@
 // directly, but is critical for high-performance scientific computing.
 
 use mohu_buffer::{
-    AllocHandle, AllocStats, Strategy,
-    BufferPool, PoolStats, GLOBAL_POOL,
-    SIMD_ALIGN, CACHE_LINE,
-    Buffer,
+    AllocHandle, AllocStats, Buffer, CACHE_LINE, GLOBAL_POOL, SIMD_ALIGN,
+    Strategy,
 };
 use mohu_dtype::DType;
 
@@ -22,22 +20,32 @@ fn main() {
     // ── Direct allocation with AllocHandle ─────────────────────────────────
     println!("\n── AllocHandle (raw aligned allocation) ──");
     let handle = AllocHandle::alloc(1024, SIMD_ALIGN).unwrap();
-    println!("Allocated: len={}, align={}, strategy={:?}",
-        handle.len(), handle.align(), handle.strategy());
+    println!(
+        "Allocated: len={}, align={}, strategy={:?}",
+        handle.len(),
+        handle.align(),
+        handle.strategy()
+    );
     println!("  Pointer: {:p}", handle.as_ptr());
     println!("  Aligned to 64 bytes: {}", handle.is_aligned_to(64));
     assert!(matches!(handle.strategy(), Strategy::Heap));
 
     // Zeroed allocation
     let zeroed = AllocHandle::alloc_zeroed(512, SIMD_ALIGN).unwrap();
-    println!("\nZeroed alloc: len={}, all zeros: {}",
+    println!(
+        "\nZeroed alloc: len={}, all zeros: {}",
         zeroed.len(),
-        zeroed.as_byte_slice().iter().all(|&b| b == 0));
+        zeroed.as_byte_slice().iter().all(|&b| b == 0)
+    );
 
     // Zero-size allocation
     let empty = AllocHandle::alloc(0, SIMD_ALIGN).unwrap();
-    println!("Zero-size: len={}, is_empty={}, strategy={:?}",
-        empty.len(), empty.is_empty(), empty.strategy());
+    println!(
+        "Zero-size: len={}, is_empty={}, strategy={:?}",
+        empty.len(),
+        empty.is_empty(),
+        empty.strategy()
+    );
 
     // ── Global allocation stats ────────────────────────────────────────────
     println!("\n── Allocation stats (global) ──");
@@ -89,13 +97,17 @@ fn main() {
     println!("\n── Pool warm-up ──");
     pool.warm(&[8192, 32768], 2).unwrap();
     let after_warm = pool.stats();
-    println!("After warm-up: cached={} bytes, blocks={}",
-        after_warm.cached_bytes, after_warm.cached_blocks);
+    println!(
+        "After warm-up: cached={} bytes, blocks={}",
+        after_warm.cached_bytes, after_warm.cached_blocks
+    );
 
     // Per-size-class breakdown
     for sc in pool.size_class_stats() {
-        println!("  Class {:>8} bytes: {} handles ({} bytes cached)",
-            sc.size_class, sc.cached_handles, sc.cached_bytes);
+        println!(
+            "  Class {:>8} bytes: {} handles ({} bytes cached)",
+            sc.size_class, sc.cached_handles, sc.cached_bytes
+        );
     }
 
     // ── Pool trim (reduce memory footprint) ────────────────────────────────
@@ -106,8 +118,11 @@ fn main() {
     println!("\n── Buffer reuse pattern ──");
     for i in 0..3 {
         let buf = Buffer::zeros(DType::F32, &[1000]).unwrap();
-        println!("  Iteration {i}: allocated {} elements, {} bytes",
-            buf.len(), buf.nbytes());
+        println!(
+            "  Iteration {i}: allocated {} elements, {} bytes",
+            buf.len(),
+            buf.nbytes()
+        );
         // buf is dropped here, its allocation returns to the pool
     }
     println!("  Pool after loop: {} cached bytes", pool.cached_bytes());

crates/mohu-buffer/examples/buffer_basics.rs

@@ -12,15 +12,20 @@
 
 use mohu_buffer::{
     Buffer, SliceArg,
-    strides::{c_strides, f_strides, NdIndexIter, unravel_index, ravel_multi_index},
+    strides::{NdIndexIter, c_strides, f_strides, ravel_multi_index, unravel_index},
 };
 use mohu_dtype::DType;
 
 fn main() {
     // ── Buffer creation from a Rust slice ──────────────────────────────────
     // NumPy: a = np.array([1.0, 2.0, 3.0, 4.0, 5.0], dtype=np.float32)
     let a = Buffer::from_slice::<f32>(&[1.0, 2.0, 3.0, 4.0, 5.0]).unwrap();
-    println!("from_slice: dtype={}, shape={:?}, len={}", a.dtype(), a.shape(), a.len());
+    println!(
+        "from_slice: dtype={}, shape={:?}, len={}",
+        a.dtype(),
+        a.shape(),
+        a.len()
+    );
 
     // Read elements back
     let v: f32 = a.get(&[2]).unwrap();
@@ -30,7 +35,11 @@ fn main() {
     // NumPy: a = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float64)
     let rows: &[&[f64]] = &[&[1.0, 2.0, 3.0], &[4.0, 5.0, 6.0]];
     let a2d = Buffer::from_slice_2d(rows).unwrap();
-    println!("\nfrom_slice_2d: shape={:?}, strides={:?}", a2d.shape(), a2d.strides());
+    println!(
+        "\nfrom_slice_2d: shape={:?}, strides={:?}",
+        a2d.shape(),
+        a2d.strides()
+    );
     let v: f64 = a2d.get(&[1, 2]).unwrap();
     println!("  a[1,2] = {v}"); // 6.0
 
@@ -79,7 +88,11 @@ fn main() {
     // ── Transpose (zero-copy view operation) ───────────────────────────────
     // NumPy: a.T
     let t = a2d.transpose();
-    println!("\nTranspose: shape={:?}, strides={:?}", t.shape(), t.strides());
+    println!(
+        "\nTranspose: shape={:?}, strides={:?}",
+        t.shape(),
+        t.strides()
+    );
     let v: f64 = t.get(&[2, 1]).unwrap(); // was a2d[1,2] = 6.0
     println!("  a.T[2,1] = {v}"); // 6.0
 
@@ -93,14 +106,25 @@ fn main() {
     // ── Slicing (zero-copy view with adjusted strides) ─────────────────────
     // NumPy: a[::2]  (every other element)
     let five = Buffer::from_slice::<f32>(&[10.0, 20.0, 30.0, 40.0, 50.0]).unwrap();
-    let sliced = five.slice_axis(0, SliceArg { start: Some(0), stop: None, step: Some(2) }).unwrap();
+    let sliced = five
+        .slice_axis(
+            0,
+            SliceArg {
+                start: Some(0),
+                stop: None,
+                step: Some(2),
+            },
+        )
+        .unwrap();
     let data = sliced.to_vec::<f32>().unwrap();
     println!("\nslice [::2]: {:?}", data); // [10.0, 30.0, 50.0]
 
     // ── Broadcast (zero-copy virtual replication) ──────────────────────────
     // NumPy: np.broadcast_to(np.array([1, 2, 3]), (3, 3))
-    let row = Buffer::from_slice::<f32>(&[1.0, 2.0, 3.0]).unwrap()
-        .expand_dims(0).unwrap();
+    let row = Buffer::from_slice::<f32>(&[1.0, 2.0, 3.0])
+        .unwrap()
+        .expand_dims(0)
+        .unwrap();
     let bc = row.broadcast_to(&[3, 3]).unwrap();
     println!("\nBroadcast to (3,3): shape={:?}", bc.shape());
     for i in 0..3 {
@@ -115,8 +139,8 @@ fn main() {
     println!("\n── Layout inspection ──");
     println!("a2d C-contiguous: {}", a2d.is_c_contiguous());
     println!("a2d F-contiguous: {}", a2d.is_f_contiguous());
-    println!("a2d.T C-contiguous: {}", t.is_c_contiguous());  // false after transpose
-    println!("a2d.T F-contiguous: {}", t.is_f_contiguous());  // true
+    println!("a2d.T C-contiguous: {}", t.is_c_contiguous()); // false after transpose
+    println!("a2d.T F-contiguous: {}", t.is_f_contiguous()); // true
 
     // ── Stride arithmetic ──────────────────────────────────────────────────
     println!("\n── Stride arithmetic ──");