Updated Makefile and Readme

src/hash/blake/tests.rs

@@ -1,8 +1,9 @@
+use alloc::vec::Vec;
+
 use proptest::prelude::*;
 use rand_utils::rand_vector;
 
 use super::*;
-use alloc::vec::Vec;
 
 #[test]
 fn blake3_hash_elements() {

src/hash/rescue/arch/x86_64_avx2.rs

@@ -4,42 +4,29 @@ use core::arch::x86_64::*;
 // https://github.com/0xPolygonZero/plonky2/blob/main/plonky2/src/hash/arch/x86_64/poseidon_goldilocks_avx2_bmi2.rs
 
 // Preliminary notes:
-// 1. AVX does not support addition with carry but 128-bit (2-word) addition can be easily
-//    emulated. The method recognizes that for a + b overflowed iff (a + b) < a:
-//        i. res_lo = a_lo + b_lo
-//       ii. carry_mask = res_lo < a_lo
-//      iii. res_hi = a_hi + b_hi - carry_mask
-//    Notice that carry_mask is subtracted, not added. This is because AVX comparison instructions
-//    return -1 (all bits 1) for true and 0 for false.
+// 1. AVX does not support addition with carry but 128-bit (2-word) addition can be easily emulated.
+//    The method recognizes that for a + b overflowed iff (a + b) < a: i. res_lo = a_lo + b_lo ii.
+//    carry_mask = res_lo < a_lo iii. res_hi = a_hi + b_hi - carry_mask Notice that carry_mask is
+//    subtracted, not added. This is because AVX comparison instructions return -1 (all bits 1) for
+//    true and 0 for false.
 //
 // 2. AVX does not have unsigned 64-bit comparisons. Those can be emulated with signed comparisons
 //    by recognizing that a <u b iff a + (1 << 63) <s b + (1 << 63), where the addition wraps around
-//    and the comparisons are unsigned and signed respectively. The shift function adds/subtracts
-//    1 << 63 to enable this trick.
-//      Example: addition with carry.
-//        i. a_lo_s = shift(a_lo)
-//       ii. res_lo_s = a_lo_s + b_lo
-//      iii. carry_mask = res_lo_s <s a_lo_s
-//       iv. res_lo = shift(res_lo_s)
-//        v. res_hi = a_hi + b_hi - carry_mask
-//    The suffix _s denotes a value that has been shifted by 1 << 63. The result of addition is
-//    shifted if exactly one of the operands is shifted, as is the case on line ii. Line iii.
-//    performs a signed comparison res_lo_s <s a_lo_s on shifted values to emulate unsigned
-//    comparison res_lo <u a_lo on unshifted values. Finally, line iv. reverses the shift so the
-//    result can be returned.
-//      When performing a chain of calculations, we can often save instructions by letting the shift
-//    propagate through and only undoing it when necessary. For example, to compute the addition of
-//    three two-word (128-bit) numbers we can do:
-//        i. a_lo_s = shift(a_lo)
-//       ii. tmp_lo_s = a_lo_s + b_lo
-//      iii. tmp_carry_mask = tmp_lo_s <s a_lo_s
-//       iv. tmp_hi = a_hi + b_hi - tmp_carry_mask
-//        v. res_lo_s = tmp_lo_s + c_lo
-//       vi. res_carry_mask = res_lo_s <s tmp_lo_s
-//      vii. res_lo = shift(res_lo_s)
-//     viii. res_hi = tmp_hi + c_hi - res_carry_mask
-//    Notice that the above 3-value addition still only requires two calls to shift, just like our
-//    2-value addition.
+//    and the comparisons are unsigned and signed respectively. The shift function adds/subtracts 1
+//    << 63 to enable this trick. Example: addition with carry. i. a_lo_s = shift(a_lo) ii. res_lo_s
+//    = a_lo_s + b_lo iii. carry_mask = res_lo_s <s a_lo_s iv. res_lo = shift(res_lo_s) v. res_hi =
+//    a_hi + b_hi - carry_mask The suffix _s denotes a value that has been shifted by 1 << 63. The
+//    result of addition is shifted if exactly one of the operands is shifted, as is the case on
+//    line ii. Line iii. performs a signed comparison res_lo_s <s a_lo_s on shifted values to
+//    emulate unsigned comparison res_lo <u a_lo on unshifted values. Finally, line iv. reverses the
+//    shift so the result can be returned. When performing a chain of calculations, we can often
+//    save instructions by letting the shift propagate through and only undoing it when necessary.
+//    For example, to compute the addition of three two-word (128-bit) numbers we can do: i. a_lo_s
+//    = shift(a_lo) ii. tmp_lo_s = a_lo_s + b_lo iii. tmp_carry_mask = tmp_lo_s <s a_lo_s iv. tmp_hi
+//    = a_hi + b_hi - tmp_carry_mask v. res_lo_s = tmp_lo_s + c_lo vi. res_carry_mask = res_lo_s <s
+//    tmp_lo_s vii. res_lo = shift(res_lo_s) viii. res_hi = tmp_hi + c_hi - res_carry_mask Notice
+//    that the above 3-value addition still only requires two calls to shift, just like our 2-value
+//    addition.
 
 #[inline(always)]
 pub fn branch_hint() {
@@ -60,10 +47,10 @@ pub fn branch_hint() {
 }
 
 macro_rules! map3 {
-    ($f:ident::<$l:literal>, $v:ident) => {
+    ($f:ident:: < $l:literal > , $v:ident) => {
         ($f::<$l>($v.0), $f::<$l>($v.1), $f::<$l>($v.2))
     };
-    ($f:ident::<$l:literal>, $v1:ident, $v2:ident) => {
+    ($f:ident:: < $l:literal > , $v1:ident, $v2:ident) => {
         ($f::<$l>($v1.0, $v2.0), $f::<$l>($v1.1, $v2.1), $f::<$l>($v1.2, $v2.2))
     };
     ($f:ident, $v:ident) => {
@@ -72,11 +59,11 @@ macro_rules! map3 {
     ($f:ident, $v0:ident, $v1:ident) => {
         ($f($v0.0, $v1.0), $f($v0.1, $v1.1), $f($v0.2, $v1.2))
     };
-    ($f:ident, rep $v0:ident, $v1:ident) => {
+    ($f:ident,rep $v0:ident, $v1:ident) => {
         ($f($v0, $v1.0), $f($v0, $v1.1), $f($v0, $v1.2))
     };
 
-    ($f:ident, $v0:ident, rep $v1:ident) => {
+    ($f:ident, $v0:ident,rep $v1:ident) => {
         ($f($v0.0, $v1), $f($v0.1, $v1), $f($v0.2, $v1))
     };
 }

src/hash/rescue/mds/freq.rs

@@ -7,9 +7,9 @@
 /// of two vectors in "frequency domain". This follows from the simple fact that every circulant
 /// matrix has the columns of the discrete Fourier transform matrix as orthogonal eigenvectors.
 /// The implementation also avoids the use of 3-point FFTs, and 3-point iFFTs, and substitutes that
-/// with explicit expressions. It also avoids, due to the form of our matrix in the frequency domain,
-/// divisions by 2 and repeated modular reductions. This is because of our explicit choice of
-/// an MDS matrix that has small powers of 2 entries in frequency domain.
+/// with explicit expressions. It also avoids, due to the form of our matrix in the frequency
+/// domain, divisions by 2 and repeated modular reductions. This is because of our explicit choice
+/// of an MDS matrix that has small powers of 2 entries in frequency domain.
 /// The following implementation has benefited greatly from the discussions and insights of
 /// Hamish Ivey-Law and Jacqueline Nabaglo of Polygon Zero and is base on Nabaglo's Plonky2
 /// implementation.
@@ -19,8 +19,9 @@
 // the MDS matrix i.e. just before the multiplication with the appropriate twiddle factors
 // and application of the final four 3-point FFT in order to get the full 12-point FFT.
 // The entries have been scaled appropriately in order to avoid divisions by 2 in iFFT2 and iFFT4.
-// The code to generate the matrix in frequency domain is based on an adaptation of a code, to generate
-// MDS matrices efficiently in original domain, that was developed by the Polygon Zero team.
+// The code to generate the matrix in frequency domain is based on an adaptation of a code, to
+// generate MDS matrices efficiently in original domain, that was developed by the Polygon Zero
+// team.
 const MDS_FREQ_BLOCK_ONE: [i64; 3] = [16, 8, 16];
 const MDS_FREQ_BLOCK_TWO: [(i64, i64); 3] = [(-1, 2), (-1, 1), (4, 8)];
 const MDS_FREQ_BLOCK_THREE: [i64; 3] = [-8, 1, 1];

src/hash/rescue/rpo/digest.rs

@@ -459,6 +459,7 @@ impl IntoIterator for RpoDigest {
 #[cfg(test)]
 mod tests {
     use alloc::string::String;
+
     use rand_utils::rand_value;
 
     use super::{Deserializable, Felt, RpoDigest, Serializable, DIGEST_BYTES, DIGEST_SIZE};

src/hash/rescue/rpo/mod.rs

@@ -152,11 +152,10 @@ impl Hasher for Rpo256 {
     fn merge_with_int(seed: Self::Digest, value: u64) -> Self::Digest {
         // initialize the state as follows:
         // - seed is copied into the first 4 elements of the rate portion of the state.
-        // - if the value fits into a single field element, copy it into the fifth rate element
-        //   and set the sixth rate element to 1.
-        // - if the value doesn't fit into a single field element, split it into two field
-        //   elements, copy them into rate elements 5 and 6, and set the seventh rate element
-        //   to 1.
+        // - if the value fits into a single field element, copy it into the fifth rate element and
+        //   set the sixth rate element to 1.
+        // - if the value doesn't fit into a single field element, split it into two field elements,
+        //   copy them into rate elements 5 and 6, and set the seventh rate element to 1.
         // - set the first capacity element to 1
         let mut state = [ZERO; STATE_WIDTH];
         state[INPUT1_RANGE].copy_from_slice(seed.as_elements());

src/hash/rescue/rpo/tests.rs

@@ -1,3 +1,5 @@
+use alloc::{collections::BTreeSet, vec::Vec};
+
 use proptest::prelude::*;
 use rand_utils::rand_value;
 
@@ -6,7 +8,6 @@ use super::{
     Felt, FieldElement, Hasher, Rpo256, RpoDigest, StarkField, ONE, STATE_WIDTH, ZERO,
 };
 use crate::Word;
-use alloc::{collections::BTreeSet, vec::Vec};
 
 #[test]
 fn test_sbox() {
@@ -58,7 +59,8 @@ fn merge_vs_merge_in_domain() {
     ];
     let merge_result = Rpo256::merge(&digests);
 
-    // ------------- merge with domain = 0 ----------------------------------------------------------
+    // ------------- merge with domain = 0
+    // ----------------------------------------------------------
 
     // set domain to ZERO. This should not change the result.
     let domain = ZERO;
@@ -66,7 +68,8 @@ fn merge_vs_merge_in_domain() {
     let merge_in_domain_result = Rpo256::merge_in_domain(&digests, domain);
     assert_eq!(merge_result, merge_in_domain_result);
 
-    // ------------- merge with domain = 1 ----------------------------------------------------------
+    // ------------- merge with domain = 1
+    // ----------------------------------------------------------
 
     // set domain to ONE. This should change the result.
     let domain = ONE;

src/hash/rescue/rpx/digest.rs

@@ -459,6 +459,7 @@ impl IntoIterator for RpxDigest {
 #[cfg(test)]
 mod tests {
     use alloc::string::String;
+
     use rand_utils::rand_value;
 
     use super::{Deserializable, Felt, RpxDigest, Serializable, DIGEST_BYTES, DIGEST_SIZE};

src/hash/rescue/rpx/mod.rs

@@ -26,8 +26,10 @@ pub type CubicExtElement = CubeExtension<Felt>;
 /// * Capacity size: 4 field elements.
 /// * S-Box degree: 7.
 /// * Rounds: There are 3 different types of rounds:
-/// - (FB): `apply_mds` → `add_constants` → `apply_sbox` → `apply_mds` → `add_constants` → `apply_inv_sbox`.
-/// - (E): `add_constants` → `ext_sbox` (which is raising to power 7 in the degree 3 extension field).
+/// - (FB): `apply_mds` → `add_constants` → `apply_sbox` → `apply_mds` → `add_constants` →
+///   `apply_inv_sbox`.
+/// - (E): `add_constants` → `ext_sbox` (which is raising to power 7 in the degree 3 extension
+///   field).
 /// - (M): `apply_mds` → `add_constants`.
 /// * Permutation: (FB) (E) (FB) (E) (FB) (E) (M).
 ///
@@ -158,8 +160,8 @@ impl Hasher for Rpx256 {
         // - seed is copied into the first 4 elements of the rate portion of the state.
         // - if the value fits into a single field element, copy it into the fifth rate element and
         //   set the first capacity element to 5.
-        // - if the value doesn't fit into a single field element, split it into two field
-        //   elements, copy them into rate elements 5 and 6 and set the first capacity element to 6.
+        // - if the value doesn't fit into a single field element, split it into two field elements,
+        //   copy them into rate elements 5 and 6 and set the first capacity element to 6.
         let mut state = [ZERO; STATE_WIDTH];
         state[INPUT1_RANGE].copy_from_slice(seed.as_elements());
         state[INPUT2_RANGE.start] = Felt::new(value);