Track 2: 2D arrays + matrix multiplication

Adds the minimum primitives for small linear-algebra workloads on top
of the existing substrate-typed dtype:

  arr_matmul(A, B)   — standard matmul, A * B = C
  arr_transpose(M)   — swap rows/cols
  arr_eye(n)         — n×n identity
  arr_zeros_2d(r, c) — r×c zero matrix

Matrices are array-of-arrays — no new Value variant, so they round-trip
cleanly through dict/array indexing, generators, classes. Element math
goes through f64 so matmul stays sensible when fed float-valued rows
(autograd-style scalars in the next step).

Tests: 9 cases — identity, non-square, row-vector dot, transpose
involution, and a substrate-pipeline composition (Fibonacci weights
× substrate-typed feature row).

Sets up the substrate-aware autograd MVP, which needs matmul + transpose
for backward passes through linear layers.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

examples/tests/test_matmul.omc

@@ -0,0 +1,139 @@
+# Track 2: 2D arrays + matrix multiplication.
+#
+# Matrices in OMC are arrays of arrays. arr_matmul, arr_transpose,
+# arr_eye, and arr_zeros_2d give us the minimum primitives to assemble
+# small linear-algebra workloads on top of the substrate-typed dtype.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) {
+    if !cond { test_record_failure(msg); }
+}
+
+fn approx_eq(a, b, tol) {
+    h d = a - b;
+    if d < 0.0 { d = 0.0 - d; }
+    return d <= tol;
+}
+
+# ---- arr_eye (identity matrix) ----
+
+fn test_eye_3() {
+    h I = arr_eye(3);
+    assert_eq(arr_len(I), 3, "I has 3 rows");
+    h r0 = arr_get(I, 0);
+    h r1 = arr_get(I, 1);
+    assert_eq(arr_len(r0), 3, "row has 3 cols");
+    assert_eq(arr_get(r0, 0), 1, "I[0][0]=1");
+    assert_eq(arr_get(r0, 1), 0, "I[0][1]=0");
+    assert_eq(arr_get(r1, 1), 1, "I[1][1]=1");
+}
+
+# ---- arr_zeros_2d ----
+
+fn test_zeros_2d() {
+    h Z = arr_zeros_2d(2, 3);
+    assert_eq(arr_len(Z), 2, "Z has 2 rows");
+    h r0 = arr_get(Z, 0);
+    assert_eq(arr_len(r0), 3, "row has 3 cols");
+    assert_eq(arr_get(r0, 0), 0, "all zeros");
+    assert_eq(arr_get(r0, 2), 0, "all zeros");
+}
+
+# ---- arr_transpose ----
+
+fn test_transpose_2x3() {
+    h A = [[1, 2, 3], [4, 5, 6]];
+    h At = arr_transpose(A);
+    assert_eq(arr_len(At), 3, "transpose has 3 rows (was 3 cols)");
+    h r0 = arr_get(At, 0);
+    assert_eq(arr_len(r0), 2, "row has 2 cols (was 2 rows)");
+    assert_eq(arr_get(r0, 0), 1, "At[0][0]=A[0][0]=1");
+    assert_eq(arr_get(r0, 1), 4, "At[0][1]=A[1][0]=4");
+    h r2 = arr_get(At, 2);
+    assert_eq(arr_get(r2, 1), 6, "At[2][1]=A[1][2]=6");
+}
+
+fn test_transpose_twice_identity() {
+    h A = [[1, 2], [3, 4], [5, 6]];
+    h Att = arr_transpose(arr_transpose(A));
+    h r0 = arr_get(Att, 0);
+    h r2 = arr_get(Att, 2);
+    assert_eq(arr_get(r0, 0), 1, "(A^T)^T = A");
+    assert_eq(arr_get(r2, 1), 6, "(A^T)^T = A");
+}
+
+# ---- arr_matmul ----
+
+fn test_matmul_2x2_2x2() {
+    # [[1,2],[3,4]] * [[5,6],[7,8]] = [[19,22],[43,50]]
+    h A = [[1, 2], [3, 4]];
+    h B = [[5, 6], [7, 8]];
+    h C = arr_matmul(A, B);
+    h r0 = arr_get(C, 0);
+    h r1 = arr_get(C, 1);
+    assert_true(approx_eq(arr_get(r0, 0), 19.0, 0.001), "C[0][0]=19");
+    assert_true(approx_eq(arr_get(r0, 1), 22.0, 0.001), "C[0][1]=22");
+    assert_true(approx_eq(arr_get(r1, 0), 43.0, 0.001), "C[1][0]=43");
+    assert_true(approx_eq(arr_get(r1, 1), 50.0, 0.001), "C[1][1]=50");
+}
+
+fn test_matmul_identity() {
+    # A * I = A
+    h A = [[2, 3], [4, 5]];
+    h I = arr_eye(2);
+    h C = arr_matmul(A, I);
+    h r0 = arr_get(C, 0);
+    h r1 = arr_get(C, 1);
+    assert_true(approx_eq(arr_get(r0, 0), 2.0, 0.001), "AI[0][0]=2");
+    assert_true(approx_eq(arr_get(r0, 1), 3.0, 0.001), "AI[0][1]=3");
+    assert_true(approx_eq(arr_get(r1, 0), 4.0, 0.001), "AI[1][0]=4");
+    assert_true(approx_eq(arr_get(r1, 1), 5.0, 0.001), "AI[1][1]=5");
+}
+
+fn test_matmul_nonsquare() {
+    # (2x3) * (3x2) = (2x2)
+    h A = [[1, 2, 3], [4, 5, 6]];
+    h B = [[7, 8], [9, 10], [11, 12]];
+    h C = arr_matmul(A, B);
+    assert_eq(arr_len(C), 2, "result has 2 rows");
+    h r0 = arr_get(C, 0);
+    assert_eq(arr_len(r0), 2, "result row has 2 cols");
+    # row 0: 1*7+2*9+3*11 = 58 ; 1*8+2*10+3*12 = 64
+    # row 1: 4*7+5*9+6*11 = 139; 4*8+5*10+6*12 = 154
+    assert_true(approx_eq(arr_get(r0, 0), 58.0, 0.001), "C[0][0]=58");
+    assert_true(approx_eq(arr_get(r0, 1), 64.0, 0.001), "C[0][1]=64");
+    h r1 = arr_get(C, 1);
+    assert_true(approx_eq(arr_get(r1, 0), 139.0, 0.001), "C[1][0]=139");
+    assert_true(approx_eq(arr_get(r1, 1), 154.0, 0.001), "C[1][1]=154");
+}
+
+fn test_matmul_row_vector() {
+    # (1x3) * (3x1) = (1x1) — dot product
+    h r = [[1, 2, 3]];
+    h c = [[4], [5], [6]];
+    h R = arr_matmul(r, c);
+    h r0 = arr_get(R, 0);
+    # 1*4 + 2*5 + 3*6 = 32
+    assert_true(approx_eq(arr_get(r0, 0), 32.0, 0.001), "dot via 1x3*3x1");
+}
+
+# ---- Pipeline: substrate-aware features into matmul ----
+
+fn test_matmul_substrate_pipeline() {
+    # Build feature vector via substrate-typed primitives,
+    # then project through a Fibonacci-weight matrix.
+    h feat = [[1, 2, 3, 5]];   # Fibonacci-like row
+    # 4x2 weight matrix (Fibonacci entries — substrate-resonant)
+    h W = [[1, 0], [1, 1], [2, 1], [3, 2]];
+    h out = arr_matmul(feat, W);
+    h r0 = arr_get(out, 0);
+    # col 0: 1*1 + 2*1 + 3*2 + 5*3 = 1+2+6+15 = 24
+    # col 1: 1*0 + 2*1 + 3*1 + 5*2 = 0+2+3+10 = 15
+    assert_true(approx_eq(arr_get(r0, 0), 24.0, 0.001), "proj col 0 = 24");
+    assert_true(approx_eq(arr_get(r0, 1), 15.0, 0.001), "proj col 1 = 15");
+}

omnimcode-core/src/compiler.rs

@@ -251,6 +251,9 @@ impl Compiler {
                         | "harmonic_dedupe"
                         // polish round (arrays)
                         | "arr_zip" | "arr_unique"
+                        // 2D array primitives (Track 2 — 2026-05-16)
+                        | "arr_matmul" | "arr_transpose"
+                        | "arr_eye" | "arr_zeros_2d"
                         // introspection
                         | "defined_functions"
                         // test runner: get_failures returns array of strings

omnimcode-core/src/interpreter.rs

@@ -5594,6 +5594,129 @@ impl Interpreter {
                     Err("arr_him_vec: requires an array".to_string())
                 }
             }
+            // ---- 2D array primitives (Track 2) ----------------------
+            //
+            // A "matrix" in OMC is an array of arrays, all inner arrays
+            // the same length. arr_matmul(A, B) does the standard
+            // multiplication: output[i][j] = sum_k A[i][k] * B[k][j].
+            // All values treated as f64 to keep results sensible for
+            // small floating workloads (autograd-style scalars).
+            "arr_matmul" => {
+                if args.len() < 2 {
+                    return Err("arr_matmul requires (matrix_a, matrix_b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let b = self.eval_expr(&args[1])?;
+                if let (Value::Array(am), Value::Array(bm)) = (a, b) {
+                    let arows = am.items.borrow();
+                    let brows = bm.items.borrow();
+                    if arows.is_empty() || brows.is_empty() {
+                        return Err("arr_matmul: empty matrix".to_string());
+                    }
+                    let a_rows = arows.len();
+                    let a_cols = match &arows[0] {
+                        Value::Array(r) => r.items.borrow().len(),
+                        _ => return Err("arr_matmul: A rows must be arrays".to_string()),
+                    };
+                    let b_rows = brows.len();
+                    let b_cols = match &brows[0] {
+                        Value::Array(r) => r.items.borrow().len(),
+                        _ => return Err("arr_matmul: B rows must be arrays".to_string()),
+                    };
+                    if a_cols != b_rows {
+                        return Err(format!(
+                            "arr_matmul: shape mismatch — A is {}x{}, B is {}x{}",
+                            a_rows, a_cols, b_rows, b_cols
+                        ));
+                    }
+                    // Materialize as Vec<Vec<f64>> for the inner loop.
+                    let a_mat: Vec<Vec<f64>> = arows.iter().map(|r| {
+                        if let Value::Array(row) = r {
+                            row.items.borrow().iter().map(|v| v.to_float()).collect()
+                        } else { Vec::new() }
+                    }).collect();
+                    let b_mat: Vec<Vec<f64>> = brows.iter().map(|r| {
+                        if let Value::Array(row) = r {
+                            row.items.borrow().iter().map(|v| v.to_float()).collect()
+                        } else { Vec::new() }
+                    }).collect();
+                    let mut out: Vec<Value> = Vec::with_capacity(a_rows);
+                    for i in 0..a_rows {
+                        let mut row: Vec<Value> = Vec::with_capacity(b_cols);
+                        for j in 0..b_cols {
+                            let mut s = 0.0f64;
+                            for k in 0..a_cols {
+                                s += a_mat[i][k] * b_mat[k][j];
+                            }
+                            row.push(Value::HFloat(s));
+                        }
+                        out.push(Value::Array(HArray::from_vec(row)));
+                    }
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_matmul: requires two 2D arrays".to_string())
+                }
+            }
+            "arr_transpose" => {
+                // Transpose a 2D array. Output[j][i] = input[i][j].
+                if args.is_empty() {
+                    return Err("arr_transpose requires (matrix)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                if let Value::Array(am) = a {
+                    let rows = am.items.borrow();
+                    if rows.is_empty() {
+                        return Ok(Value::Array(HArray::from_vec(vec![])));
+                    }
+                    let n_cols = match &rows[0] {
+                        Value::Array(r) => r.items.borrow().len(),
+                        _ => return Err("arr_transpose: rows must be arrays".to_string()),
+                    };
+                    let mut out: Vec<Value> = Vec::with_capacity(n_cols);
+                    for j in 0..n_cols {
+                        let mut col: Vec<Value> = Vec::with_capacity(rows.len());
+                        for row_v in rows.iter() {
+                            if let Value::Array(row) = row_v {
+                                col.push(row.items.borrow()[j].clone());
+                            }
+                        }
+                        out.push(Value::Array(HArray::from_vec(col)));
+                    }
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_transpose: requires a 2D array".to_string())
+                }
+            }
+            "arr_eye" => {
+                // arr_eye(n) -> identity matrix (n x n) of ints.
+                if args.is_empty() {
+                    return Err("arr_eye requires (n)".to_string());
+                }
+                let n = self.eval_expr(&args[0])?.to_int().max(0) as usize;
+                let mut rows: Vec<Value> = Vec::with_capacity(n);
+                for i in 0..n {
+                    let mut row: Vec<Value> = Vec::with_capacity(n);
+                    for j in 0..n {
+                        row.push(Value::HInt(HInt::new(if i == j { 1 } else { 0 })));
+                    }
+                    rows.push(Value::Array(HArray::from_vec(row)));
+                }
+                Ok(Value::Array(HArray::from_vec(rows)))
+            }
+            "arr_zeros_2d" => {
+                // arr_zeros_2d(rows, cols) -> (rows x cols) zero matrix.
+                if args.len() < 2 {
+                    return Err("arr_zeros_2d requires (rows, cols)".to_string());
+                }
+                let r = self.eval_expr(&args[0])?.to_int().max(0) as usize;
+                let c = self.eval_expr(&args[1])?.to_int().max(0) as usize;
+                let mut rows: Vec<Value> = Vec::with_capacity(r);
+                for _ in 0..r {
+                    let row: Vec<Value> = (0..c).map(|_| Value::HInt(HInt::new(0))).collect();
+                    rows.push(Value::Array(HArray::from_vec(row)));
+                }
+                Ok(Value::Array(HArray::from_vec(rows)))
+            }
             // arr_fold_all(arr) -> new array with every element snapped
             // to its nearest Fibonacci attractor. Vectorized fold.
             // Substrate-canonical denoising / quantization primitive.