use reference in rok_*

Author: mhchia

src/mat.rs

@@ -1,4 +1,3 @@
-use rand::rand_core::block;
 
 use crate::ring::Ring;
 use std::ops::{Add, Index, Mul, Range};
@@ -11,9 +10,18 @@ pub struct Mat<R> {
 }
 
 impl<R> Mat<R> {
+    /// Build a matrix from row vectors.
+    ///
+    /// Panics on empty outer vec — the column count is undeterminable
+    /// from an empty input. For 0-row matrices, use `Mat::zero(0, ncols)`
+    /// or `Mat::from_fn(0, ncols, _)` so `ncols` is explicit.
+    /// `vec![vec![], vec![]]` (M rows of width 0) is fine — ncols = 0.
     pub fn new(rows: impl Into<Vec<Vec<R>>>) -> Self {
         let rows: Vec<Vec<R>> = rows.into();
-        assert!(!rows.is_empty(), "Mat::new requires at least one row");
+        assert!(
+            !rows.is_empty(),
+            "Mat::new: empty rows — use Mat::zero(0, ncols) for 0×ncols",
+        );
         let nrows = rows.len();
         let ncols = rows[0].len();
         assert!(
@@ -126,12 +134,15 @@ impl<R: Clone> Mat<R> {
     /// Both ranges are half-open (`start..end`). Panics if the end of either
     /// range exceeds the corresponding dimension.
     pub fn submatrix(&self, rows: Range<usize>, cols: Range<usize>) -> Self {
-        assert!(rows.end <= self.nrows && cols.end <= self.ncols, "submatrix OOB");
+        assert!(
+            rows.end <= self.nrows && cols.end <= self.ncols,
+            "submatrix OOB"
+        );
         Mat::<R>::from_fn(
             rows.end - rows.start,
             cols.end - cols.start,
             // i \in [0, nrows), j \in [0, ncols)
-            |i, j| self[(i + rows.start, j + cols.start)].clone()
+            |i, j| self[(i + rows.start, j + cols.start)].clone(),
         )
     }
 }
@@ -159,16 +170,16 @@ impl<R: Ring> Mat<R> {
     ///
     /// Example: `block_diagonal(&[I_1, I_2, I_1])` is the 4×4 identity.
     pub fn block_diagonal(blocks: &[Mat<R>]) -> Self {
-        let nrows_new: usize  = blocks.iter().map(|x| x.nrows).sum();
+        let nrows_new: usize = blocks.iter().map(|x| x.nrows).sum();
         let ncols_new: usize = blocks.iter().map(|x| x.ncols).sum();
-        let mut data: Vec<R> = vec![R::zero();nrows_new * ncols_new];
+        let mut data: Vec<R> = vec![R::zero(); nrows_new * ncols_new];
         let mut cur_start_row: usize = 0;
         let mut cur_start_col: usize = 0;
         // Fill in each b in the diagonal of `data`.
         for b in blocks.iter() {
             for i in 0..b.nrows {
                 for j in 0..b.ncols {
-                    data[(cur_start_row + i) * ncols_new + cur_start_col + j] = b[(i, j)].clone();
+                    data[(cur_start_row + i) * ncols_new + cur_start_col + j] = b[(i, j)];
                 }
             }
             cur_start_row += b.nrows;
@@ -268,18 +279,90 @@ mod tests {
     }
 
     #[test]
-    #[should_panic(expected = "at least one row")]
+    #[should_panic(expected = "empty rows")]
     fn test_new_empty_panics() {
+        // Empty outer Vec is ambiguous (ncols undeterminable) — must panic.
         let _: Mat<F> = Mat::new(Vec::<Vec<F>>::new());
     }
 
+    #[test]
+    fn test_new_zero_cols_from_empty_inner_rows() {
+        // M × 0: outer has rows, inner rows have width 0 → ncols = 0 is determined.
+        let mat: Mat<F> = Mat::new(vec![vec![], vec![], vec![]]);
+        assert_eq!(mat.dimensions(), (3, 0));
+    }
+
     #[test]
     fn test_from_fn_matches_new() {
         let by_new = m(&[[0, 1, 2], [10, 11, 12]]);
         let by_fn = Mat::<F>::from_fn(2, 3, |i, j| z((i * 10 + j) as u64));
         assert_eq!(by_new, by_fn);
     }
 
+    // ─── 0-dim matrices ───
+
+    #[test]
+    fn test_from_fn_zero_rows() {
+        // 0 × m: closure never invoked, but ncols is preserved.
+        let mat = Mat::<F>::from_fn(0, 5, |_, _| panic!("must not be called"));
+        assert_eq!(mat.dimensions(), (0, 5));
+    }
+
+    #[test]
+    fn test_from_fn_zero_cols() {
+        let mat = Mat::<F>::from_fn(3, 0, |_, _| panic!("must not be called"));
+        assert_eq!(mat.dimensions(), (3, 0));
+    }
+
+    #[test]
+    fn test_zero_with_zero_rows() {
+        let mat = Mat::<F>::zero(0, 4);
+        assert_eq!(mat.dimensions(), (0, 4));
+    }
+
+    #[test]
+    fn test_zero_with_zero_cols() {
+        let mat = Mat::<F>::zero(2, 0);
+        assert_eq!(mat.dimensions(), (2, 0));
+    }
+
+    #[test]
+    fn test_stack_onto_zero_row_keeps_ncols() {
+        // 0 × 3 stacked on 2 × 3 = 2 × 3 (caller can drop the empty top half).
+        let top = Mat::<F>::zero(0, 3);
+        let bot = m(&[[1, 2, 3], [4, 5, 6]]);
+        let stacked = top.stack(&bot);
+        assert_eq!(stacked.dimensions(), (2, 3));
+        assert_eq!(stacked, bot);
+    }
+
+    #[test]
+    #[should_panic(expected = "col mismatch")]
+    fn test_stack_zero_x_zero_onto_real_matrix_panics() {
+        // 0 × 0 ≠ "any ncols" — stack must reject this.
+        let zero_zero = Mat::<F>::from_fn(0, 0, |_, _| unreachable!());
+        let real = m(&[[1, 2, 3]]);
+        let _ = zero_zero.stack(&real);
+    }
+
+    #[test]
+    fn test_augment_with_zero_col_keeps_nrows() {
+        // (2 × 0) augment (2 × 3) = 2 × 3.
+        let left = Mat::<F>::zero(2, 0);
+        let right = m(&[[1, 2, 3], [4, 5, 6]]);
+        let aug = left.augment(&right);
+        assert_eq!(aug.dimensions(), (2, 3));
+        assert_eq!(aug, right);
+    }
+
+    #[test]
+    fn test_transpose_zero_row() {
+        // (0 × 5)^T = (5 × 0).
+        let mat = Mat::<F>::zero(0, 5);
+        let t = mat.transpose();
+        assert_eq!(t.dimensions(), (5, 0));
+    }
+
     #[test]
     fn test_from_flatten() {
         let data = [z(1), z(2), z(3), z(4)];
@@ -676,7 +759,7 @@ mod tests {
     fn test_block_diagonal_mixed_dims() {
         // diag(2×3 block, 1×2 block) → 3×5 matrix
         let a = m(&[[1, 2, 3], [4, 5, 6]]); // 2×3
-        let b = m(&[[7, 8]]);                // 1×2
+        let b = m(&[[7, 8]]); // 1×2
         let bd = Mat::<F>::block_diagonal(&[a, b]);
 
         assert_eq!(bd.dimensions(), (3, 5));

src/relations.rs

@@ -6,8 +6,6 @@
 //!
 //! where F = F_com stacked over F_eval, and ‖·‖₂ is the column l_2 norm
 //! over the concatenated coefficient vector of each column of W.
-//!
-//! Reference: SALSAA paper §3–4. Python: `06_salsaa/relations.py`.
 
 use crate::mat::Mat;
 use crate::ring::Rq;
@@ -67,7 +65,7 @@ impl<const Q: u64, const D: usize> LinInstance<Q, D> {
         self.h.ncols()
     }
 
-    /// n_top — cols of H = rows of F.
+    /// n_top — \bar F, number of rows of the commitment matrix.
     pub fn n_top(&self) -> usize {
         self.f_com.nrows()
     }
@@ -113,38 +111,37 @@ impl<const Q: u64, const D: usize> LinWitness<Q, D> {
     }
 }
 
-/// A LinInstance plus a verified LinWitness. Construction must enforce:
-///   1. Dimension consistency (H, F, W, Y all line up)
-///   2. Algebraic relation:   H · (F · W) = Y
-///   3. l_2 norm bound:        max_i ‖w_i‖₂ ≤ β
-///
-/// `new` returns `Self` here for symmetry with Python. You can refactor
-/// to `Result<Self, RelError>` (Ch 9 practice) if you want explicit
-/// error variants instead of panic.
-#[derive(Debug, Clone)]
-pub struct LinRelation<const Q: u64, const D: usize> {
-    pub instance: LinInstance<Q, D>,
-    pub witness: LinWitness<Q, D>,
-}
-
+/// l2 norm squared of a column is the sum of the norm squared of all ring elements
 fn col_l2_norm_squared<const Q: u64, const D: usize>(col: &[Rq<Q, D>]) -> u64 {
     col.iter().map(|r| r.l2_norm_squared()).sum()
 }
 
-fn max_col_l2_norm_squared<const Q: u64, const D: usize>(w: &Mat<Rq<Q, D>>) -> u64 {
+/// l2 norm of a matrix is the max norm among its columns.
+/// this function returns the max l2 norm **squared**
+fn mat_l2_norm_squared<const Q: u64, const D: usize>(w: &Mat<Rq<Q, D>>) -> u64 {
     (0..w.ncols())
         .map(|j| col_l2_norm_squared(&w.col(j)))
         .max()
         .unwrap_or(0)
 }
 
+/// A LinInstance plus a verified LinWitness. Construction must enforce:
+///   1. Dimension consistency (H, F, W, Y all line up)
+///   2. Algebraic relation:   H · (F · W) = Y
+///   3. l_2 norm bound:        max_i ‖w_i‖₂ ≤ β
+#[derive(Debug, Clone)]
+pub struct LinRelation<const Q: u64, const D: usize> {
+    pub instance: LinInstance<Q, D>,
+    pub witness: LinWitness<Q, D>,
+}
+
 impl<const Q: u64, const D: usize> LinRelation<Q, D> {
     pub fn new(instance: LinInstance<Q, D>, witness: LinWitness<Q, D>) -> Self {
         // 1. l_2 norm of W must be <= \beta
-        let l2_norm_squared_w = max_col_l2_norm_squared(&witness.w);
+        let l2_norm_squared_w = mat_l2_norm_squared(&witness.w);
         let l2_norm_bound_squared = instance.beta * instance.beta;
         assert!(
-            l2_norm_squared_w < l2_norm_bound_squared,
+            l2_norm_squared_w <= l2_norm_bound_squared,
             "exceeded norm bound: actual norm squared={}, norm bound={}",
             l2_norm_squared_w,
             l2_norm_bound_squared,
@@ -217,12 +214,6 @@ mod tests {
         Mat::new(v)
     }
 
-    // NOTE: Initial Σ^lin has F_eval = 0 × m. Current `Mat::new` requires
-    // at least one row, so 0-row matrices can't be constructed yet. All
-    // tests below use F_eval with ≥ 1 row to dodge that limitation. When
-    // you decide how to handle the empty case (Option, Mat::empty, etc.),
-    // add a test for the initial state.
-
     // ─── LinWitness ───
 
     #[test]
@@ -346,8 +337,73 @@ mod tests {
         let _ = LinRelation::new(inst, wit);
     }
 
-    // NOTE: norm-bound violation test (||w_i||_2 > β) is deferred — it
-    // needs `Zq::centered()` (mapping v ∈ [0, q) → signed [-q/2, q/2])
-    // which isn't on Zq yet. Once that exists, add a `should_panic` test
-    // putting a column of large-coefficient entries into W with β = 1.
+    // ─── norm-bound checks (the ‖·‖₂ branch of LinRelation::new) ───
+
+    #[test]
+    fn test_relation_norm_at_boundary_constructs() {
+        // ‖w‖² == β². Bound is non-strict (≤) so this MUST pass.
+        // W = [[c(1)]]: coeffs [1, 0, 0, 0]. centered norm² = 1. β = 1 → β² = 1.
+        // F = F_com = [[1]] (no eval block), so F · W = [[1]] = Y.
+        let h = Mat::<R>::identity(1);
+        let f_com = mat(&[[1]]);
+        let f_eval = Mat::<R>::zero(0, 1);
+        let w = mat(&[[1]]);
+        let y = mat(&[[1]]);
+
+        let inst = LinInstance::new(h, f_com, f_eval, y, 1);
+        let wit = LinWitness::new(w);
+        let _ = LinRelation::new(inst, wit); // must not panic
+    }
+
+    #[test]
+    #[should_panic(expected = "exceeded norm bound")]
+    fn test_relation_norm_violation_panics() {
+        // ‖w‖² > β². W = [[c(5)]]: centered coeffs [5, 0, 0, 0], norm² = 25.
+        // β = 1 → β² = 1. 25 > 1 ⇒ must panic.
+        // Y = F · W = c(5) so the algebraic relation alone would still hold.
+        let h = Mat::<R>::identity(1);
+        let f_com = mat(&[[1]]);
+        let f_eval = Mat::<R>::zero(0, 1);
+        let w = mat(&[[5]]);
+        let y = mat(&[[5]]);
+
+        let inst = LinInstance::new(h, f_com, f_eval, y, 1);
+        let wit = LinWitness::new(w);
+        let _ = LinRelation::new(inst, wit);
+    }
+
+    // ─── initial state: empty evaluation block ───
+
+    #[test]
+    fn test_instance_initial_state_empty_f_eval() {
+        // F_eval = 0 × m means "no evaluation rows yet". This is the
+        // initial Σ^lin shape before any with_extra_eval call. F should
+        // equal F_com (stacking 0 rows on top changes nothing).
+        let h = Mat::<R>::identity(2);
+        let f_com = mat(&[[1, 2], [3, 4]]);
+        let f_eval = Mat::<R>::zero(0, 2); // explicit 0 × 2 — ncols carried
+        let y = Mat::<R>::zero(2, 1);
+        let inst = LinInstance::new(h, f_com.clone(), f_eval, y, 10);
+
+        assert_eq!(inst.n_hat(), 2);
+        assert_eq!(inst.n(), 2); // F_com.nrows + F_eval.nrows = 2 + 0
+        assert_eq!(inst.n_top(), 2); // F_com.nrows
+        assert_eq!(inst.m(), 2);
+        assert_eq!(inst.f(), f_com, "F == F_com when F_eval is empty");
+    }
+
+    #[test]
+    fn test_relation_with_empty_f_eval_constructs() {
+        // End-to-end: a satisfied Σ^lin with the initial empty F_eval.
+        let h = Mat::<R>::identity(2);
+        let f_com = mat(&[[1, 2], [3, 4]]);
+        let f_eval = Mat::<R>::zero(0, 2);
+        let w = mat(&[[1], [1]]);
+        // F · W = [[1+2], [3+4]] = [[3], [7]] (constant-poly entries)
+        let y = mat(&[[3], [7]]);
+
+        let inst = LinInstance::new(h, f_com, f_eval, y, 10);
+        let wit = LinWitness::new(w);
+        let _ = LinRelation::new(inst, wit); // must not panic
+    }
 }

src/rok/batch.rs

@@ -1,3 +1,12 @@
-//! Batch reduction: combines multiple sumcheck claims into one.
-//!
-//! Reference: `06_salsaa/rok/batch.py`.
+use crate::relations::LinRelation;
+
+/// Batch evaluation statements into smaller statements.
+///     E.g. \tilde f(r)      = s
+///     \tilde f(\bar r) = \bar s
+///     -> tilde f(r) + c \tilde f(\bar r) = s + c \bar s
+pub fn rok_join<const Q: u64, const D: usize>(
+    _lin: &LinRelation<Q, D>,
+    _n_target_eval_rows: usize,
+) -> LinRelation<Q, D> {
+    todo!()
+}