Realm

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};
2
3use anyhow::{Context, bail, ensure};
4use oa::{Matrix, matrix};
5
6const 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];
16
17const 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];
25
26#[derive(Clone, Copy)]
27struct ShapeCase {
28 name: &'static str,
29 m: usize,
30 n: usize,
31 k: usize,
32}
33
34impl ShapeCase {
35 const fn new(name: &'static str, m: usize, n: usize, k: usize) -> Self {
36 Self { name, m, n, k }
37 }
38}
39
40struct Options {
41 correctness: bool,
42 benchmark: bool,
43 warmup: usize,
44 samples: usize,
45 case: Option<String>,
46}
47
48struct PerfResult {
49 p50_ms: f64,
50 p95_ms: f64,
51 gflops: f64,
52}
53
54fn main() -> anyhow::Result<()> {
55 let options = parse_options()?;
56
57 println!("OA Rust Core MatMul Intro — C = A @ Bᵀ");
58 println!("contract: FP32 [M,K] × [N,K] -> [M,N]");
59 demo_basic_syntax()?;
60
61 if options.correctness {
62 run_correctness_suite()?;
63 }
64 if options.benchmark {
65 run_performance_suite(&options)?;
66 }
67 Ok(())
68}
69
70fn 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 arguments
88 .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}
105
106fn parse_count(flag: &str, value: Option<String>) -> anyhow::Result<usize> {
107 value
108 .with_context(|| format!("{flag} requires a non-negative integer"))?
109 .parse()
110 .with_context(|| format!("{flag} requires a non-negative integer"))
111}
112
113fn 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());
125
126 // 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}
144
145fn 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.k
160 );
161 }
162 println!(" All correctness checks passed.");
163 Ok(())
164}
165
166fn 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.samples
172 );
173
174 let mut matched = options.case.is_none();
175 for &case in PERFORMANCE_CASES {
176 if options
177 .case
178 .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.gflops
188 );
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.gflops
192 );
193 }
194 ensure!(matched, "unknown performance case: {:?}", options.case);
195 Ok(())
196}
197
198fn 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.n
207 && actual
208 .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.name
213 );
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 }
223
224 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}
241
242fn 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}
248
249fn 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}
254
255fn 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 output
265}
266
267fn 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.