docs(linalg): document the SIMD conversion panics and fix the AVX2 kernel's algorithm name - #8865
Open
LuciferYang wants to merge 1 commit into
Open
docs(linalg): document the SIMD conversion panics and fix the AVX2 kernel's algorithm name#8865LuciferYang wants to merge 1 commit into
LuciferYang wants to merge 1 commit into
Conversation
LuciferYang
force-pushed
the
docs/linalg-simd-contracts
branch
from
August 29, 2026 16:18
05b2d58 to
6f84c88
Compare
Contributor
There was a problem hiding this comment.
✅ Gate recommendation: approve.
After the rebase, the six minimum lengths still match the established assertions and render under their from methods; the AVX2 description still matches the PSHUFB nibble-lookup kernel. Open PR #8862 remains an equivalent duplicate, so only one should land.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Adds a
# Panicssection to the sixFrom<&[T]>conversions inrust/lance-linalg/src/simd/, and corrects one doc line inhamming.rsthat names an algorithm the code does not use. Comment-only, 31 added lines and 1 removed. Addresses #8861.Why
#8593 gave every slice-to-register conversion an always-on
assert!, so a short slice panics rather than reading out of bounds. None of the six said so, andFromis the conversion a caller reaches for without reading the body: the signature is infallible and nothing in the rendered docs warned thatf32x8::from(&slice[..])aborts the thread. The six aref32x8,f32x16,f64x4,f64x8,i32x8andu8x16, requiring 8, 16, 4, 8, 8 and 16 elements. TheFrom<&[T; N]>impls beside them take an array reference and cannot be short, so they are left alone.Separately,
hamming.rsdescribed the AVX2 kernel as "Harley-Seal / PSHUFB method". The body builds a nibble popcount table, looks both nibbles up with two_mm256_shuffle_epi8calls, and sums bytes with_mm256_sad_epu8. Harley-Seal is a carry-save-adder tree that folds several words together before any popcount runs, and there is none here: each 256-bit chunk is popcounted on its own. A grep for Harley-Seal across the crate now returns nothing, so that line was the only occurrence.Relationship to #8862
#8862 covers the same ground and was opened first. I have left review notes there rather than duplicating it, and this PR is the alternative if the placement question below is easier to take as a diff than as a comment.
The difference that matters is where the section goes. #8862 puts
# Panicson theimplblock; this puts it onfn from. I rendered both. On the impl block the heading attaches to the impl header and lands outsideimpl-items, so expandingfromon the struct page shows nothing:On the method it attaches to
from, one heading level lower, with a summary line above it:Both are valid rustdoc and neither warns under
-D warnings.Test plan
Comment-only, so there is nothing to test beyond the doc build.
RUSTDOCFLAGS="-D warnings" cargo doc -p lance-linalg --no-deps: clean, and all six sentences appear in the generated HTML under theirfrommethodcargo fmt --all -- --checkandcargo clippy -p lance-linalg --all-targets -- -D warnings: cleancargo test --profile ci -p lance-linalg --lib: 389 passed, 1 ignored, unchangedNot included, so it does not get lost:
dot_u8.rs,l2_u8.rsandcosine_u8.rshave zero# Panicsand zero# Safetybetween them despite the same always-on checks andunsafekernels whose raw loads depend on the lengths matching. That wants one change across all three files, and it has to follow whichever cosine length-contract PR lands.