Separate Bit Transpose from Bittable by xrvdg · Pull Request #137 · worldfnd/BitZ

xrvdg · 2026-09-28T10:01:53Z

Preparation for the lookup table optimisation for GKR, which builds lookups from short bit strings during tree construction and the sumcheck rounds. That needs bit layouts that no protocol Shape describes.

The witness is now read as u128 words, with StepIter yielding them S bits at a time. BitTable stays the shaped view of the witness, and its transpose returns a geometry-only BitMatrix that GrandProductCircuit::new builds the leaves from.

Tables with fewer than 128 columns are now rejected by BitZParams instead of taking the prover's bit-at-a-time fallback; production shapes never have them. Commit 336e809 has a more general transpose that also takes rows shorter than a word, which might be useful later but isn't needed now.

BitTable has been split into BitTable (protocol specific) and BitMatrix (bit operations) to not have the extra restrictions when building the lookup table.

…stants

…ence

…BitTable with OwnedBitTable

…ence

…-fine butterflies

…torise

…omment

…lumns view and let transpose take fewer than 128 columns

… WordColumns view and let transpose take fewer than 128 columns

… images and the transposed table

…y BitMatrix, moving the t >= 7 gate back to Shape

… BitZParams Production never transposes a table with fewer than 128 columns: the CLI builds t = 7, s = m - 7 shapes and the reference split has s >= 8. Go back to origin/main's 128x128 block kernel and drop the small-dim1 machinery (bit_transpose_blocks, rotate_bit_index, rotation_swaps and StepIter::preloaded) together with its tests. That version lives in 336e809. The bit_transpose doc comment points there and notes that it extends to dim2 < 128 if needed. BitZParams::new now rejects s < 7 with ParamsError::ColumnCountTooNarrow rather than letting the reduction panic in the transpose. It is not a protocol bound but a limit of the kernel, and restoring that version lifts it.

…d let GrandProductCircuit::new take the table BitTable::as_matrix wraps the table's words as an [columns][rows] BitMatrix without moving a bit, and transposing goes only through BitMatrix::transpose. To borrow the words, BitMatrix now holds a Cow<'a, [Word]>; transpose always returns an owned BitMatrix<'static>. The crate-private transposed helper is gone, and BitMatrix computes no ilog2. GrandProductCircuit::new takes the BitTable and does as_matrix().transpose() itself, so the prover and the verifier test no longer transpose before building the circuit. BitMatrix::bit was only read by tests, so it moves into the matrix test module as the oracle there; the as_matrix test reads columns through bits() instead.

zkfriendly

Thanks, the PR looks clean and correct. Left some minor comments!

zkfriendly · 2026-10-08T08:31:39Z

 impl GrandProductCircuit {
-    // Fails if the leafs are 0.
-    pub fn new(mut leafs: Vec<Field>) -> Self {
+    pub fn new(row_images: &[F128], bittable: &BitTable) -> Self {


We are assuming row_images has the same length as bittable rows. Worth explicitly checking it?

assert_eq!(row_images.len(), bittable.shape().rows());

zkfriendly · 2026-10-08T08:36:13Z

+        let dim2 = matrix.dim2();
+        let dim = matrix.dim1() * dim2;


After transposition, dim2 means columns and dim is num_leaves. It would be easier to follow if use the more descriptive names

zkfriendly · 2026-10-08T08:58:49Z

+        let packed = packed.into();
+        let bits = packed.len() * BITS;
+        assert!(
+            bits.is_power_of_two() && (1 << log_dim2) <= bits,


1 << log_dim2 can wrap in optimized builds, so the check can accept dimensions larger than the available bits. We could do log_dim2 <= bits.ilog2() instead.

zkfriendly · 2026-10-08T09:03:57Z

+const DIM1: usize = 128;
+/// `2^20` bits per row: a 16 MiB matrix, well past the last-level cache.
+const DIM2: usize = 1 << 20;


The CLI uses 128 for rows, and 1 << 20 columns, and I understand DIM1 here is the columns, in that case, this benchmark should have DIM1 = 1 << 20 and DIM2 = 128 to represent realistic witnesses

zkfriendly · 2026-10-08T09:49:38Z

    /// anything but a checked parameter set.
    pub fn table<'a>(&self, packed: &'a [F128]) -> Result<BitTable<'a>, TableError> {
-        BitTable::new(self.shape, packed)
+        BitTable::new(self.shape, bytemuck::cast_slice(packed))


Doesn't cast_slice depend on byte order? seems to me that this will not work properly on big endian machines.

zkfriendly · 2026-10-08T09:51:06Z

+    out
+}
+
+/// Benchmark-only access to the private transposes; see `benches/table.rs`.


file was renamed to benches/matrix.rs

zkfriendly · 2026-10-08T09:52:18Z

 impl<'a> BitTable<'a> {
+    pub const BITS: usize = Word::BITS as usize;
+
    /// Wraps `packed` in `shape`, least significant bit first inside `lo`.


outdated comment here, lo no longer exists

xrvdg added 10 commits September 28, 2026 17:58

common: back BitTable with a machine-sized Word instead of F128

f869b88

common: rename ColumnBits to BitsIter

e6a2e4c

common: generalise BitsIter into StepIter yielding S-bit chunks

dd89f3f

common: transpose BitTable via word-level 64x64 bit block transpose

448fe41

common: add a test-only transpose_reference and drop F128 packing con…

0abcaf0

…stants

common: let bit_block_transpose handle dim1-row tiles and test d = 4

d626b3d

common: support any power-of-two dim1 in bit_transpose

e5543a0

common: reduce bit_transpose_blocks to a single butterfly sweep

b8418a6

common: compute butterfly masks inline instead of precomputing them

5b37d62

common: add divan benchmark of bit_transpose against the reference

f891e96

xrvdg marked this pull request as draft September 28, 2026 10:02

xrvdg changed the title ~~Bit transpose for all power of twos~~ Bit transpose and bit indexing for all power of twos Sep 28, 2026

xrvdg added 7 commits September 28, 2026 18:08

fixup! common: add divan benchmark of bit_transpose against the refer…

2d7fe1e

…ence

common: make BitTable generic over its storage and replace Transposed…

b0340d2

…BitTable with OwnedBitTable

fixup! common: add divan benchmark of bit_transpose against the refer…

403e34a

…ence

common: switch Word to u128 and rotate bit indices ahead of coarse-to…

8f8c5e5

…-fine butterflies

common: run in-lane bit index rotation swaps on u64 lanes so they vec…

435d745

…torise

common: replace bit_transpose's derivation comment with a short doc c…

c56514d

…omment

common: move the t >= 7 gate from Shape to BitZParams behind a WordCo…

783a529

…lumns view and let transpose take fewer than 128 columns

xrvdg marked this pull request as ready for review October 5, 2026 12:06

xrvdg commented Oct 5, 2026

View reviewed changes

Comment thread crates/common/src/params.rs Outdated

xrvdg requested a review from zkfriendly October 5, 2026 12:14

xrvdg added 4 commits October 6, 2026 14:37

fixup! common: move the t >= 7 gate from Shape to BitZParams behind a…

f8405bc

… WordColumns view and let transpose take fewer than 128 columns

gkr: move leaf construction into GrandProductCircuit::new, taking row…

706a2ae

… images and the transposed table

common: split BitTable into a shaped BitTable view and a geometry-onl…

336e809

…y BitMatrix, moving the t >= 7 gate back to Shape

xrvdg changed the title ~~Bit transpose and bit indexing for all power of twos~~ Separate Bit Transpose from Bittable Oct 7, 2026

xrvdg added 2 commits October 8, 2026 11:52

Merge remote-tracking branch 'origin/main' into xr/bittable

202028a

zkfriendly requested changes Oct 8, 2026

View reviewed changes

Navigation Menu

Repository navigation

Separate Bit Transpose from Bittable - #137

Separate Bit Transpose from Bittable#137
xrvdg wants to merge 23 commits into
mainfrom
xr/bittable

xrvdg commented Sep 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

zkfriendly left a comment

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

zkfriendly Oct 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

xrvdg commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

zkfriendly left a comment

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

zkfriendly Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xrvdg commented Sep 28, 2026 •

edited

Loading