refactor: add RowIndex(u32) newtype (#1408)

CHANGELOG.md

@@ -31,6 +31,7 @@
 - Added source code management primitives in `miden-core` (#1419)
 - Added `make test-fast` and `make test-skip-proptests` Makefile targets for faster testing during local development
 - Added `ProgramFile::read_with` constructor that takes a `SourceManager` impl to use for source management
+- Added `RowIndex(u32)` (#1408)
 
 #### Changed
 

air/Cargo.toml

@@ -27,13 +27,14 @@ harness = false
 
 [features]
 default = ["std"]
-std = ["vm-core/std", "winter-air/std"]
+std = ["vm-core/std", "winter-air/std", "thiserror/std"]
 testing = []
 
 [dependencies]
 vm-core = { package = "miden-core", path = "../core", version = "0.10", default-features = false }
 winter-air = { package = "winter-air", version = "0.9", default-features = false }
 winter-prover = { package = "winter-prover", version = "0.9", default-features = false }
+thiserror = { version = "1.0", git = "https://github.com/bitwalker/thiserror", branch = "no-std", default-features = false }
 
 [dev-dependencies]
 criterion = "0.5"

air/src/constraints/chiplets/bitwise/mod.rs

@@ -418,16 +418,3 @@ pub fn agg_bits<E: FieldElement>(row: &[E], start_idx: usize) -> E {
 pub const BITWISE_K0_MASK: [Felt; OP_CYCLE_LEN] = [ONE, ZERO, ZERO, ZERO, ZERO, ZERO, ZERO, ZERO];
 
 pub const BITWISE_K1_MASK: [Felt; OP_CYCLE_LEN] = [ONE, ONE, ONE, ONE, ONE, ONE, ONE, ZERO];
-
-// TEST HELPERS
-// ================================================================================================
-
-/// Returns the values from the bitwise periodic columns for the specified cycle row.
-#[cfg(test)]
-fn get_periodic_values(cycle_row: usize) -> [Felt; 2] {
-    match cycle_row {
-        0 => [ONE, ONE],
-        8 => [ZERO, ZERO],
-        _ => [ZERO, ONE],
-    }
-}

air/src/constraints/chiplets/bitwise/tests.rs

@@ -1,8 +1,7 @@
 use super::{
-    enforce_constraints, get_periodic_values, EvaluationFrame, BITWISE_A_COL_IDX,
-    BITWISE_A_COL_RANGE, BITWISE_B_COL_IDX, BITWISE_B_COL_RANGE, BITWISE_OUTPUT_COL_IDX,
-    BITWISE_PREV_OUTPUT_COL_IDX, BITWISE_SELECTOR_COL_IDX, NUM_CONSTRAINTS, NUM_DECOMP_BITS, ONE,
-    OP_CYCLE_LEN, ZERO,
+    enforce_constraints, EvaluationFrame, BITWISE_A_COL_IDX, BITWISE_A_COL_RANGE,
+    BITWISE_B_COL_IDX, BITWISE_B_COL_RANGE, BITWISE_OUTPUT_COL_IDX, BITWISE_PREV_OUTPUT_COL_IDX,
+    BITWISE_SELECTOR_COL_IDX, NUM_CONSTRAINTS, NUM_DECOMP_BITS, ONE, OP_CYCLE_LEN, ZERO,
 };
 use crate::{
     trace::{
@@ -12,7 +11,7 @@ use crate::{
         },
         TRACE_WIDTH,
     },
-    Felt,
+    Felt, RowIndex,
 };
 use rand_utils::rand_value;
 
@@ -29,7 +28,7 @@ fn test_bitwise_change_ops_fail() {
 
     let a = rand_value::<u32>();
     let b = rand_value::<u32>();
-    let cycle_row: usize = rand_value::<u8>() as usize % (OP_CYCLE_LEN - 1);
+    let cycle_row: RowIndex = (rand_value::<u8>() as usize % (OP_CYCLE_LEN - 1)).into();
 
     let frame = get_test_frame_with_two_ops(BITWISE_XOR, BITWISE_AND, a, b, cycle_row);
     let result = get_constraint_evaluation(frame, cycle_row);
@@ -45,7 +44,7 @@ fn test_bitwise_change_ops_fail() {
 /// cycle when the low limb of a is one.
 #[test]
 fn output_aggregation_and() {
-    let cycle_row = 0;
+    let cycle_row: RowIndex = 0.into();
 
     // create a valid test frame manually
     let mut current = vec![ZERO; TRACE_WIDTH];
@@ -116,8 +115,8 @@ proptest! {
     #[test]
     fn test_bitwise_and(a in any::<u32>(), b in any::<u32>(), cycle_row in 0..(OP_CYCLE_LEN - 1)) {
         let expected = [ZERO; NUM_CONSTRAINTS];
-        let frame = get_test_frame(BITWISE_AND, a, b, cycle_row);
-        let result = get_constraint_evaluation(frame, cycle_row);
+        let frame = get_test_frame(BITWISE_AND, a, b, cycle_row.into());
+        let result = get_constraint_evaluation(frame, cycle_row.into());
         assert_eq!(expected, result);
     }
 
@@ -126,8 +125,8 @@ proptest! {
     #[test]
     fn test_bitwise_xor(a in any::<u32>(), b in any::<u32>(), cycle_row in 0..(OP_CYCLE_LEN - 1)) {
         let expected = [ZERO; NUM_CONSTRAINTS];
-        let frame = get_test_frame(BITWISE_XOR, a, b, cycle_row);
-        let result = get_constraint_evaluation(frame, cycle_row);
+        let frame = get_test_frame(BITWISE_XOR, a, b, cycle_row.into());
+        let result = get_constraint_evaluation(frame, cycle_row.into());
         assert_eq!(expected, result);
     }
 }
@@ -137,7 +136,10 @@ proptest! {
 
 /// Returns the result of Bitwise constraint evaluations on the provided frame starting at the
 /// specified row.
-fn get_constraint_evaluation(frame: EvaluationFrame<Felt>, row: usize) -> [Felt; NUM_CONSTRAINTS] {
+fn get_constraint_evaluation(
+    frame: EvaluationFrame<Felt>,
+    row: RowIndex,
+) -> [Felt; NUM_CONSTRAINTS] {
     let periodic_values = get_periodic_values(row);
     let mut result = [ZERO; NUM_CONSTRAINTS];
 
@@ -151,16 +153,16 @@ fn get_constraint_evaluation(frame: EvaluationFrame<Felt>, row: usize) -> [Felt;
 /// cycle.
 ///
 /// # Errors
-/// It expects the specified `cycle_row_num` for the current row to be such that the next row will
+/// It expects the specified `cycle_row` for the current row to be such that the next row will
 /// still be in the same cycle. It will fail if the row number input is >= OP_CYCLE_LEN - 1.
 pub fn get_test_frame(
     operation: Felt,
     a: u32,
     b: u32,
-    cycle_row_num: usize,
+    cycle_row: RowIndex,
 ) -> EvaluationFrame<Felt> {
     assert!(
-        cycle_row_num < OP_CYCLE_LEN - 1,
+        cycle_row < OP_CYCLE_LEN - 1,
         "Failed to build test EvaluationFrame for bitwise operation. The next row would be in a new cycle."
     );
 
@@ -173,16 +175,16 @@ pub fn get_test_frame(
     next[BITWISE_SELECTOR_COL_IDX] = operation;
 
     // Set the input aggregation and decomposition values.
-    set_frame_inputs(&mut current, &mut next, a, b, cycle_row_num);
+    set_frame_inputs(&mut current, &mut next, a, b, cycle_row);
 
     // Compute the output for the specified operation and inputs and shift it for each row.
-    let (previous_shift, current_shift, next_shift) = get_row_shifts(cycle_row_num);
+    let (previous_shift, current_shift, next_shift) = get_row_shifts(cycle_row);
     let result = get_output(operation, a, b);
     let output_current = result >> current_shift;
     let output_next = result >> next_shift;
 
     // Set the previous output.
-    let output_prev = if cycle_row_num == 0 {
+    let output_prev = if cycle_row == 0 {
         ZERO
     } else {
         Felt::new((result >> previous_shift) as u64)
@@ -202,17 +204,17 @@ pub fn get_test_frame(
 /// frames within a cycle.
 ///
 /// # Errors
-/// It expects the specified `cycle_row_num` for the current row to be such that the next row will
+/// It expects the specified `cycle_row` for the current row to be such that the next row will
 /// still be in the same cycle. It will fail if the row number input is >= OP_CYCLE_LEN - 1.
 pub fn get_test_frame_with_two_ops(
     op_current: Felt,
     op_next: Felt,
     a: u32,
     b: u32,
-    cycle_row_num: usize,
+    cycle_row: RowIndex,
 ) -> EvaluationFrame<Felt> {
     assert!(
-        cycle_row_num < OP_CYCLE_LEN - 1,
+        cycle_row < OP_CYCLE_LEN - 1,
         "Failed to build test EvaluationFrame for bitwise operation. The next row would be in a new cycle."
     );
 
@@ -225,16 +227,16 @@ pub fn get_test_frame_with_two_ops(
     next[BITWISE_SELECTOR_COL_IDX] = op_next;
 
     // Set the input aggregation and decomposition values.
-    set_frame_inputs(&mut current, &mut next, a, b, cycle_row_num);
+    set_frame_inputs(&mut current, &mut next, a, b, cycle_row);
 
     // Compute the outputs for the specified operations and inputs and shift them for each row.
-    let (previous_shift, current_shift, next_shift) = get_row_shifts(cycle_row_num);
+    let (previous_shift, current_shift, next_shift) = get_row_shifts(cycle_row);
     let result_op_current = get_output(op_current, a, b);
     let output_current = result_op_current >> current_shift;
     let output_next = get_output(op_next, a, b) >> next_shift;
 
     // Set the previous output.
-    let output_prev = if cycle_row_num == 0 {
+    let output_prev = if cycle_row == 0 {
         ZERO
     } else {
         Felt::new((result_op_current >> previous_shift) as u64)
@@ -249,11 +251,11 @@ pub fn get_test_frame_with_two_ops(
     EvaluationFrame::<Felt>::from_rows(current, next)
 }
 
-/// Returns the shift amount for the previous, current, and next rows, based on the `cycle_row_num`,
+/// Returns the shift amount for the previous, current, and next rows, based on the `cycle_row`,
 /// which is the number of the `current` row within the operation cycle.
-fn get_row_shifts(cycle_row_num: usize) -> (usize, usize, usize) {
+fn get_row_shifts(cycle_row: RowIndex) -> (usize, usize, usize) {
     // Define the shift amount for output in this row and the next row.
-    let current_shift = NUM_DECOMP_BITS * (OP_CYCLE_LEN - cycle_row_num - 1);
+    let current_shift = NUM_DECOMP_BITS * (OP_CYCLE_LEN - usize::from(cycle_row) - 1);
     let previous_shift = current_shift + NUM_DECOMP_BITS;
     let next_shift = current_shift - NUM_DECOMP_BITS;
 
@@ -262,10 +264,10 @@ fn get_row_shifts(cycle_row_num: usize) -> (usize, usize, usize) {
 
 /// Sets the input aggregation and decomposition columns in the provided current and next rows with
 /// the correct values corresponding to the provided inputs `a` and `b` and the specified
-/// `cycle_row_num`, which is the number of the `current` row within the operation cycle.
-fn set_frame_inputs(current: &mut [Felt], next: &mut [Felt], a: u32, b: u32, cycle_row_num: usize) {
+/// `cycle_row`, which is the number of the `current` row within the operation cycle.
+fn set_frame_inputs(current: &mut [Felt], next: &mut [Felt], a: u32, b: u32, cycle_row: RowIndex) {
     // Get the shift amounts for the specified rows.
-    let (_, current_shift, next_shift) = get_row_shifts(cycle_row_num);
+    let (_, current_shift, next_shift) = get_row_shifts(cycle_row);
 
     // Set the input aggregation values.
     let current_a = (a >> current_shift) as u64;
@@ -297,3 +299,13 @@ fn get_output(operation: Felt, a: u32, b: u32) -> u32 {
         panic!("Test bitwise EvaluationFrame requested for unrecognized operation.");
     }
 }
+
+/// Returns the values from the bitwise periodic columns for the specified cycle row.
+#[cfg(test)]
+fn get_periodic_values(cycle_row: crate::RowIndex) -> [Felt; 2] {
+    match cycle_row.into() {
+        0u32 => [ONE, ONE],
+        8u32 => [ZERO, ZERO],
+        _ => [ZERO, ONE],
+    }
+}

air/src/constraints/chiplets/hasher/tests.rs

@@ -4,7 +4,7 @@ use super::{
 };
 use crate::{
     trace::chiplets::hasher::{Selectors, LINEAR_HASH, STATE_WIDTH},
-    Felt, TRACE_WIDTH,
+    Felt, RowIndex, TRACE_WIDTH,
 };
 use alloc::vec::Vec;
 use rand_utils::rand_array;
@@ -20,12 +20,12 @@ use winter_air::EvaluationFrame;
 fn hash_round() {
     let expected = [ZERO; NUM_CONSTRAINTS];
 
-    let cycle_row_num: usize = 3;
+    let cycle_row = 3.into();
     let current_selectors = [ZERO, LINEAR_HASH[1], LINEAR_HASH[2]];
     let next_selectors = current_selectors;
 
-    let frame = get_test_hashing_frame(current_selectors, next_selectors, cycle_row_num);
-    let result = get_constraint_evaluation(frame, cycle_row_num);
+    let frame = get_test_hashing_frame(current_selectors, next_selectors, cycle_row);
+    let result = get_constraint_evaluation(frame, cycle_row);
     assert_eq!(expected, result);
 }
 
@@ -36,23 +36,23 @@ fn hash_round() {
 /// the specified row.
 fn get_constraint_evaluation(
     frame: EvaluationFrame<Felt>,
-    cycle_row_num: usize,
+    cycle_row: RowIndex,
 ) -> [Felt; NUM_CONSTRAINTS] {
     let mut result = [ZERO; NUM_CONSTRAINTS];
-    let periodic_values = get_test_periodic_values(cycle_row_num);
+    let periodic_values = get_test_periodic_values(cycle_row);
 
     enforce_constraints(&frame, &periodic_values, &mut result, ONE);
 
     result
 }
 
 /// Returns the values from the periodic columns for the specified cycle row.
-fn get_test_periodic_values(cycle_row: usize) -> Vec<Felt> {
+fn get_test_periodic_values(cycle_row: RowIndex) -> Vec<Felt> {
     // Set the periodic column values.
-    let mut periodic_values = match cycle_row {
-        0 => vec![ZERO, ZERO, ONE],
-        7 => vec![ZERO, ONE, ZERO],
-        8 => vec![ONE, ZERO, ZERO],
+    let mut periodic_values = match cycle_row.into() {
+        0u32 => vec![ZERO, ZERO, ONE],
+        7u32 => vec![ZERO, ONE, ZERO],
+        8u32 => vec![ONE, ZERO, ZERO],
         _ => vec![ZERO, ZERO, ZERO],
     };
 
@@ -70,7 +70,7 @@ fn get_test_periodic_values(cycle_row: usize) -> Vec<Felt> {
 fn get_test_hashing_frame(
     current_selectors: Selectors,
     next_selectors: Selectors,
-    cycle_row_num: usize,
+    cycle_row: RowIndex,
 ) -> EvaluationFrame<Felt> {
     let mut current = vec![ZERO; TRACE_WIDTH];
     let mut next = vec![ZERO; TRACE_WIDTH];
@@ -84,7 +84,7 @@ fn get_test_hashing_frame(
     current[HASHER_STATE_COL_RANGE].copy_from_slice(&state);
 
     // Set the hasher state after a single permutation.
-    apply_round(&mut state, cycle_row_num);
+    apply_round(&mut state, cycle_row.into());
     next[HASHER_STATE_COL_RANGE].copy_from_slice(&state);
 
     // Set the node index values to zero for hash computations.

air/src/lib.rs

@@ -23,6 +23,7 @@ pub use constraints::stack;
 use constraints::{chiplets, range};
 
 pub mod trace;
+pub use trace::rows::RowIndex;
 use trace::*;
 
 mod errors;