Matrix multiplication
Source-owned programs from the current OA SDK. Rust and Python examples follow their respective public APIs.
Rust · Python
The Rust program validates matrix multiplication against an independent CPU reference and reports exploratory eager timings. The Python tab demonstrates the current Core basics API; it is not a paired timing run.
Example
1use std::{env, hint::black_box, time::Instant};23use anyhow::{Context, bail, ensure};4use oa::{Matrix, matrix};56const CORRECTNESS_CASES: &[ShapeCase] = &[7 ShapeCase::new("tiny-square", 8, 8, 8),8 ShapeCase::new("square", 128, 128, 128),9 ShapeCase::new("tall-skinny", 512, 64, 128),10 ShapeCase::new("short-wide", 64, 512, 128),11 ShapeCase::new("irregular", 100, 130, 77),12 ShapeCase::new("gemv-decode", 1, 256, 256),13 ShapeCase::new("mnist-hidden", 64, 128, 784),14 ShapeCase::new("mnist-logits", 64, 10, 128),15];1617const PERFORMANCE_CASES: &[ShapeCase] = &[18 ShapeCase::new("square-512", 512, 512, 512),19 ShapeCase::new("square-1024", 1024, 1024, 1024),20 ShapeCase::new("square-2048", 2048, 2048, 2048),21 ShapeCase::new("tall-skinny", 4096, 128, 1024),22 ShapeCase::new("short-wide", 128, 4096, 1024),23 ShapeCase::new("gemv-decode", 1, 4096, 4096),24];2526#[derive(Clone, Copy)]27struct ShapeCase {28 name: &'static str,29 m: usize,30 n: usize,31 k: usize,32}3334impl ShapeCase {35 const fn new(name: &'static str, m: usize, n: usize, k: usize) -> Self {36 Self { name, m, n, k }37 }38}3940struct Options {41 correctness: bool,42 benchmark: bool,43 warmup: usize,44 samples: usize,45 case: Option<String>,46}4748struct PerfResult {49 p50_ms: f64,50 p95_ms: f64,51 gflops: f64,52}5354fn main() -> anyhow::Result<()> {55 let options = parse_options()?;5657 println!("OA Rust Core MatMul Intro — C = A @ Bᵀ");58 println!("contract: FP32 [M,K] × [N,K] -> [M,N]");59 demo_basic_syntax()?;6061 if options.correctness {62 run_correctness_suite()?;63 }64 if options.benchmark {65 run_performance_suite(&options)?;66 }67 Ok(())68}6970fn parse_options() -> anyhow::Result<Options> {71 let mut options = Options {72 correctness: true,73 benchmark: true,74 warmup: 5,75 samples: 20,76 case: None,77 };78 let mut arguments = env::args().skip(1);79 while let Some(argument) = arguments.next() {80 match argument.as_str() {81 "--correctness-only" => options.benchmark = false,82 "--benchmark-only" => options.correctness = false,83 "--warmup" => options.warmup = parse_count("--warmup", arguments.next())?,84 "--samples" => options.samples = parse_count("--samples", arguments.next())?,85 "--case" => {86 options.case = Some(87 arguments88 .next()89 .context("--case requires a performance-case name")?,90 );91 }92 "--help" | "-h" => {93 println!(94 "usage: core_mat_mul_intro [--correctness-only|--benchmark-only] \95 [--case NAME] [--warmup N] [--samples N]"96 );97 std::process::exit(0);98 }99 _ => bail!("unknown argument: {argument}"),100 }101 }102 ensure!(options.samples > 0, "--samples must be greater than zero");103 Ok(options)104}105106fn parse_count(flag: &str, value: Option<String>) -> anyhow::Result<usize> {107 value108 .with_context(|| format!("{flag} requires a non-negative integer"))?109 .parse()110 .with_context(|| format!("{flag} requires a non-negative integer"))111}112113fn demo_basic_syntax() -> anyhow::Result<()> {114 println!("\n1. Basic syntax");115 let one = matrix::ones([2, 3])?;116 let two = matrix::full([2, 3], 2.0)?;117 let product = matrix::mat_mul_nt(&one, &two)?;118 let values = product.read_f32()?;119 ensure!(product.shape() == [2, 2], "unexpected output shape");120 ensure!(121 values == [6.0; 4],122 "unexpected introductory result: {values:?}"123 );124 println!(" [2,3] × [2,3]ᵀ -> {:?}: {values:?}", product.shape());125126 // Operators, methods, associated calls and module functions share one body.127 // Elementwise multiplication is distinct from A @ B-transpose above.128 for elementwise in [129 (&one * &two)?,130 one.mul(&two)?,131 Matrix::mul(&one, &two)?,132 matrix::mul(&one, &two)?,133 ] {134 ensure!(135 elementwise.read_f32()? == [2.0; 6],136 "elementwise API mismatch"137 );138 }139 let added = (&one + &two)?;140 ensure!(added.read_f32()? == [3.0; 6], "addition operator mismatch");141 println!(" operator / method / associated / module calls agree");142 Ok(())143}144145fn run_correctness_suite() -> anyhow::Result<()> {146 println!("\n2. Correctness vs independent CPU reference");147 for (index, &case) in CORRECTNESS_CASES.iter().enumerate() {148 let left_values = values(case.m * case.k, index * 2 + 3);149 let right_values = values(case.n * case.k, index * 2 + 11);150 let expected = cpu_mat_mul_nt(&left_values, &right_values, case.m, case.n, case.k);151 let left = Matrix::new_from_f32([case.m, case.k], &left_values)?;152 let right = Matrix::new_from_f32([case.n, case.k], &right_values)?;153 let output = matrix::mat_mul_nt(&left, &right)?;154 let actual = output.read_f32()?;155 let error = normalized_error(&actual, &expected)?;156 ensure!(error <= 1.0e-4, "{} exceeded the FP32 tolerance", case.name);157 println!(158 " {:<16} [{:5},{:5},{:5}] norm_err={error:.2e} ok",159 case.name, case.m, case.n, case.k160 );161 }162 println!(" All correctness checks passed.");163 Ok(())164}165166fn run_performance_suite(options: &Options) -> anyhow::Result<()> {167 println!("\n3. Exploratory eager end-to-end performance");168 println!(" boundary: mat_mul_nt call through synchronized full output readback");169 println!(170 " warmup={} samples={} (one process; not release benchmark evidence)",171 options.warmup, options.samples172 );173174 let mut matched = options.case.is_none();175 for &case in PERFORMANCE_CASES {176 if options177 .case178 .as_deref()179 .is_some_and(|name| name != case.name)180 {181 continue;182 }183 matched = true;184 let result = bench_one(case, options.warmup, options.samples)?;185 println!(186 " {:<16} [{:5},{:5},{:5}] p50={:9.3} ms p95={:9.3} ms {:9.2} GFLOP/s",187 case.name, case.m, case.n, case.k, result.p50_ms, result.p95_ms, result.gflops188 );189 println!(190 "BENCH name={} m={} n={} k={} boundary=eager_submit_readback p50_ms={:.6} p95_ms={:.6} gflops={:.6}",191 case.name, case.m, case.n, case.k, result.p50_ms, result.p95_ms, result.gflops192 );193 }194 ensure!(matched, "unknown performance case: {:?}", options.case);195 Ok(())196}197198fn bench_one(case: ShapeCase, warmup: usize, sample_count: usize) -> anyhow::Result<PerfResult> {199 let left = matrix::full([case.m, case.k], 0.25)?;200 let right = matrix::full([case.n, case.k], 0.5)?;201 // Constant-input oracle checks every timed geometry before warmup.202 // A positive norm or maximum-error reduction alone must not hide NaNs.203 let expected = case.k as f32 * 0.125;204 let actual = matrix::mat_mul_nt(&left, &right)?.read_f32()?;205 ensure!(206 actual.len() == case.m * case.n207 && actual208 .iter()209 .all(|&value| value.is_finite()210 && (value - expected).abs() <= expected.abs().max(1.0) * 1.0e-5),211 "{} independent constant-input oracle failed",212 case.name213 );214 println!(215 "ORACLE name={} correctness=pass elements={} expected={expected}",216 case.name,217 actual.len()218 );219 for _ in 0..warmup {220 let output = matrix::mat_mul_nt(&left, &right)?;221 black_box(output.read_f32()?);222 }223224 let mut samples = Vec::with_capacity(sample_count);225 for _ in 0..sample_count {226 let start = Instant::now();227 let output = matrix::mat_mul_nt(&left, &right)?;228 black_box(output.read_f32()?);229 samples.push(start.elapsed().as_secs_f64() * 1_000.0);230 }231 samples.sort_by(f64::total_cmp);232 let p50_ms = percentile(&samples, 0.50);233 let p95_ms = percentile(&samples, 0.95);234 let gflop = 2.0 * case.m as f64 * case.n as f64 * case.k as f64 / 1.0e9;235 Ok(PerfResult {236 p50_ms,237 p95_ms,238 gflops: gflop / (p50_ms / 1_000.0),239 })240}241242fn percentile(samples: &[f64], percentile: f64) -> f64 {243 let index = ((percentile * samples.len() as f64).ceil() as usize)244 .saturating_sub(1)245 .min(samples.len() - 1);246 samples[index]247}248249fn values(length: usize, salt: usize) -> Vec<f32> {250 (0..length)251 .map(|index| (((index * 17 + salt) % 29) as f32 - 14.0) / 7.0)252 .collect()253}254255fn cpu_mat_mul_nt(left: &[f32], right: &[f32], m: usize, n: usize, k: usize) -> Vec<f32> {256 let mut output = vec![0.0; m * n];257 for row in 0..m {258 for column in 0..n {259 for inner in 0..k {260 output[row * n + column] += left[row * k + inner] * right[column * k + inner];261 }262 }263 }264 output265}266267fn normalized_error(actual: &[f32], expected: &[f32]) -> anyhow::Result<f64> {268 ensure!(269 actual.len() == expected.len(),270 "output length differs from CPU oracle"271 );272 let mut max_error = 0.0_f64;273 let mut max_reference = 1.0e-6_f64;274 for (&actual, &expected) in actual.iter().zip(expected) {275 max_error = max_error.max((f64::from(actual) - f64::from(expected)).abs());276 max_reference = max_reference.max(f64::from(expected).abs());277 }278 Ok(max_error / max_reference)279}280
Run Rust tutorials from the OA checkout with cargo run --release --example <name>. Run Python with the environment containing the OA native extension. Consult each program's arguments and capability checks before running it.