Skip to content

Decompose TurboQuant into 2 ScalarFnArrays and DictArray#7374

Merged
connortsui20 merged 10 commits intodevelopfrom
ct/tq-decomp
Apr 10, 2026
Merged

Decompose TurboQuant into 2 ScalarFnArrays and DictArray#7374
connortsui20 merged 10 commits intodevelopfrom
ct/tq-decomp

Conversation

@connortsui20
Copy link
Copy Markdown
Contributor

@connortsui20 connortsui20 commented Apr 9, 2026

Summary

Tracking issue: #7297

Decomposes TurboQuant into:

ScalarFnArray(L2Denorm, [
    ScalarFnArray(SorfTransform, [
        Extension<Vector>(
            FixedSizeListArray(
                DictArray(codes=Primitive<u8>, values=Primitive<f32>),
                padded_dim
            )
        )
    ]),
    norms
])

This makes the implementation more modular and turns the TurboQuant-specific pieces into reusable building blocks.

Also defines SORF sign generation with a frozen local SplitMix64 implementation and cleans up related vector compute code.

API Changes

  • add SorfTransform
  • remove the TurboQuant encoding/array type
  • keep TurboQuantScheme as the compressor entry point
  • simplify a all scalar fn APIs as we no longer need ApproxOptions

Note that ApproxOptions doesn't actually make sense here because we are doing exact compute here, it is the encoding itself that is lossy. Until we figure out what the exact semantics are of a lossy encoding I will remove this.

Testing

More tests:

  • TurboQuant roundtrip / structural coverage
  • SORF roundtrip + norm preservation
  • deterministic SplitMix64 / sign generation coverage
  • readthrough behavior (when children are normalized) for vector similarity ops

@connortsui20 connortsui20 added the changelog/feature A new feature label Apr 9, 2026
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq bot commented Apr 9, 2026

Merging this PR will not alter performance

✅ 1122 untouched benchmarks
⏩ 1455 skipped benchmarks1


Comparing ct/tq-decomp (c0f6037) with develop (360b41d)

Open in CodSpeed

Footnotes

  1. 1455 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

claude and others added 9 commits April 9, 2026 16:29
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
@connortsui20 connortsui20 marked this pull request as ready for review April 9, 2026 20:38
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
// norms that are already stored.
// L2Norm(L2Denorm(normalized, norms)) is defined to read back the authoritative stored
// norms. Exact callers of lossy encodings like TurboQuant opt into that storage semantics
// instead of forcing a decode-and-recompute path here.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems wrong to me...

As in, I don't think ScalarFn::execute should be matching on child array type should it? CC @joseph-isaacs

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we resolved this, this is fine

@connortsui20 connortsui20 enabled auto-merge (squash) April 10, 2026 17:33
@connortsui20 connortsui20 merged commit 8d9052e into develop Apr 10, 2026
61 checks passed
@connortsui20 connortsui20 deleted the ct/tq-decomp branch April 10, 2026 17:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog/feature A new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants