Skip to content

perf(neon): tagged table-lookup hex parse with deferred validation - #61

Merged
mrecachinas merged 1 commit into
perf/neon-block-scannersfrom
perf/neon-hex-lut
Sep 23, 2026
Merged

mrecachinas merged 1 commit into
perf/neon-block-scannersfrom
perf/neon-hex-lut

Conversation

@mrecachinas

@mrecachinas mrecachinas commented Sep 23, 2026 •

Copy link
Copy Markdown
Owner

Replaces the NEON arithmetic hex parse with a tagged table lookup: one vqtbl4q_u8 per 16 chars, indexed by char - '0'.

How it works

  • Hex digits map to 0x10 | nibble; every other byte maps to 0.
  • XORing two valid chars cancels the tag, so vcnt of the unpacked XOR is the per-char distance. No nibble packing is needed.
  • Validation is deferred to one check per call of the running lane-wise minimum.
  • The final partial chunk re-reads the last 16 chars and masks off the overlap, replacing the 16-char and scalar tails.
  • Net effect: about 20 SIMD ops per 32 chars instead of about 50.

Semantics unchanged

  • check_hexstrings_within_dist uses the new parse inside the existing _with_max block structure, with the same check points.
  • Both parses accept exactly the hex digits, and invalid input is still tested before the threshold at every check point.
  • So results are identical, including which of "invalid char" and "over max_dist" wins.
  • The old pack kernel stays as the test reference and behind hex_hamming_distance_pack.

Criterion, "f"*n vs "0"*n (old pack kernel → new):

Chars Before After Speedup
32 2.84 ns 2.06 ns 1.38×
64 5.39 ns 3.74 ns 1.44×
128 10.66 ns 7.12 ns 1.50×
254 20.10 ns 13.71 ns 1.47×

Interleaved Python A/B (Apple M4 Max, CPython 3.14, previous layer → this layer):

Call Before After Speedup
hamming_distance_string 254 chars 46.7 ns 37.3 ns 1.25×
hamming_distance_string 1024 chars 106.7 ns 75.4 ns 1.42×
hamming_distance_string 4096 chars 378.4 ns 254.9 ns 1.48×
hamming_distance_string 63 chars 34.0 ns 28.4 ns 1.19×
check_hexstrings_within_dist 254 chars, d=60 38.5 ns 34.0 ns 1.13×

Tests

  • Exhaustive comparison against the classic kernel at lengths 0..=300 and around batch boundaries.
  • Every invalid byte class at every position for lengths 1..=80.
  • 6000 randomized _with_max cases against the pack kernel. The test asserts that precedence-deciding cases (invalid-wins and threshold-wins) both occur.
  • A 60k-case Python differential against the previous layer found no divergences in values or error messages.

@mrecachinas
mrecachinas added this pull request to stack #60 September 23, 2026 01:43
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

📊 Benchmark Comparison Results

Status Benchmark Base PR Delta
❌ fixed_width_array_scan_matrix[all-random_no_match-16] 0.0007ms 0.0075ms 901.1% slower
❌ fixed_width_array_scan_matrix[all-exact_early-16] 0.0008ms 0.0073ms 841.4% slower
❌ fixed_width_array_scan_matrix[all-threshold_d_minus_1-16] 0.0007ms 0.0064ms 760.8% slower
❌ fixed_width_array_scan_matrix[all-exact_late-16] 0.0008ms 0.0065ms 719.9% slower
❌ fixed_width_array_scan_matrix[all-threshold_d_plus_1-16] 0.0008ms 0.0064ms 697.4% slower
❌ fixed_width_array_scan_matrix[all-exact_mid-16] 0.0008ms 0.0064ms 696.5% slower
❌ fixed_width_array_scan_matrix[all-threshold_d-16] 0.0009ms 0.0064ms 610.2% slower
❌ check_bytes_arrays_all_within_dist[ 512 elems,s=16,end] 0.0005ms 0.0033ms 608.0% slower
❌ check_bytes_arrays_all_within_dist[ 512 elems,s=16,mid] 0.0005ms 0.0033ms 587.3% slower
❌ check_bytes_arrays_all_within_dist[ 512 elems,s=16,at 0] 0.0005ms 0.0033ms 506.3% slower
❌ fixed_width_array_scan_matrix[all-random_no_match-32] 0.0013ms 0.0050ms 271.1% slower
❌ fixed_width_array_scan_matrix[all-exact_early-32] 0.0014ms 0.0050ms 245.1% slower
❌ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,mid] 0.0015ms 0.0050ms 241.8% slower
❌ fixed_width_array_scan_matrix[all-threshold_d-32] 0.0014ms 0.0044ms 214.9% slower
❌ fixed_width_array_scan_matrix[all-exact_mid-32] 0.0014ms 0.0044ms 214.6% slower
❌ fixed_width_array_scan_matrix[all-threshold_d_minus_1-32] 0.0014ms 0.0044ms 212.1% slower
❌ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,at 0] 0.0014ms 0.0044ms 210.1% slower
❌ fixed_width_array_scan_matrix[all-threshold_d_plus_1-32] 0.0015ms 0.0044ms 200.1% slower
❌ fixed_width_array_scan_matrix[all-exact_late-32] 0.0016ms 0.0045ms 174.4% slower
❌ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,end] 0.0017ms 0.0045ms 162.8% slower
➖ 84 benchmarks within noise (click to expand)
Benchmark Base PR Delta
check_bytes_arrays_all_within_dist[16384 elems,s=64,at 0] 0.0562ms 0.0520ms 7.6% faster
check_bytes_arrays_all_within_dist[16384 elems,s=64,end] 0.0548ms 0.0546ms 0.4% faster
check_bytes_arrays_all_within_dist[16384 elems,s=64,mid] 0.0555ms 0.0563ms 1.4% slower
check_bytes_arrays_best_within_dist[ 512 elems,s=16,at 0] 0.0001ms 0.0001ms 0.4% faster
check_bytes_arrays_best_within_dist[ 512 elems,s=16,end] 0.0004ms 0.0004ms 10.0% faster
check_bytes_arrays_best_within_dist[ 512 elems,s=16,mid] 0.0002ms 0.0002ms 8.6% faster
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,at 0] 0.0016ms 0.0014ms 10.9% faster
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,end] 0.0015ms 0.0016ms 5.1% slower
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,mid] 0.0016ms 0.0017ms 0.7% slower
check_bytes_arrays_best_within_dist[16384 elems,s=64,at 0] 0.0550ms 0.0550ms 0.0% faster
check_bytes_arrays_best_within_dist[16384 elems,s=64,end] 0.0550ms 0.0551ms 0.3% slower
check_bytes_arrays_best_within_dist[16384 elems,s=64,mid] 0.0543ms 0.0547ms 0.7% slower
check_bytes_arrays_first_within_dist[ 512 elems,s=16,at 0] 0.0000ms 0.0000ms 0.3% faster
check_bytes_arrays_first_within_dist[ 512 elems,s=16,end] 0.0004ms 0.0003ms 8.4% faster
check_bytes_arrays_first_within_dist[ 512 elems,s=16,mid] 0.0002ms 0.0002ms 5.4% faster
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,at 0] 0.0000ms 0.0000ms 0.3% slower
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,end] 0.0013ms 0.0013ms 0.3% slower
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,mid] 0.0007ms 0.0007ms 0.1% slower
check_bytes_arrays_first_within_dist[16384 elems,s=64,at 0] 0.0001ms 0.0001ms 0.2% slower
check_bytes_arrays_first_within_dist[16384 elems,s=64,end] 0.0508ms 0.0530ms 4.3% slower
check_bytes_arrays_first_within_dist[16384 elems,s=64,mid] 0.0255ms 0.0255ms 0.0% faster
check_bytes_within_dist[127 bytes,d=500] 0.0000ms 0.0000ms 0.6% faster
check_bytes_within_dist[16 bytes,d=0] 0.0000ms 0.0000ms 8.4% faster
check_bytes_within_dist[64 bytes,d=100] 0.0000ms 0.0000ms 2.4% faster
hex_within_dist 0.0001ms 0.0000ms 11.0% faster
fixed_width_array_scan_matrix[best-exact_early-16] 0.0001ms 0.0001ms 1.2% slower
fixed_width_array_scan_matrix[best-exact_early-32] 0.0001ms 0.0001ms 7.5% faster
fixed_width_array_scan_matrix[best-exact_late-16] 0.0006ms 0.0006ms 0.5% faster
fixed_width_array_scan_matrix[best-exact_late-32] 0.0014ms 0.0014ms 0.2% slower
fixed_width_array_scan_matrix[best-exact_mid-16] 0.0004ms 0.0004ms 8.9% faster
fixed_width_array_scan_matrix[best-exact_mid-32] 0.0007ms 0.0007ms 0.6% slower
fixed_width_array_scan_matrix[best-random_no_match-16] 0.0007ms 0.0006ms 14.0% faster
fixed_width_array_scan_matrix[best-random_no_match-32] 0.0014ms 0.0014ms 0.2% faster
fixed_width_array_scan_matrix[best-threshold_d-16] 0.0007ms 0.0006ms 8.2% faster
fixed_width_array_scan_matrix[best-threshold_d-32] 0.0014ms 0.0014ms 0.1% slower
fixed_width_array_scan_matrix[best-threshold_d_minus_1-16] 0.0006ms 0.0006ms 0.2% slower
fixed_width_array_scan_matrix[best-threshold_d_minus_1-32] 0.0014ms 0.0014ms 0.1% slower
fixed_width_array_scan_matrix[best-threshold_d_plus_1-16] 0.0006ms 0.0006ms 0.1% slower
fixed_width_array_scan_matrix[best-threshold_d_plus_1-32] 0.0014ms 0.0014ms 0.1% slower
fixed_width_array_scan_matrix[first-exact_early-16] 0.0000ms 0.0000ms 0.1% slower
fixed_width_array_scan_matrix[first-exact_early-32] 0.0000ms 0.0000ms 0.3% slower
fixed_width_array_scan_matrix[first-exact_late-16] 0.0006ms 0.0006ms 0.5% slower
fixed_width_array_scan_matrix[first-exact_late-32] 0.0014ms 0.0012ms 9.0% faster
fixed_width_array_scan_matrix[first-exact_mid-16] 0.0003ms 0.0003ms 1.8% slower
fixed_width_array_scan_matrix[first-exact_mid-32] 0.0007ms 0.0007ms 0.2% slower
fixed_width_array_scan_matrix[first-random_no_match-16] 0.0006ms 0.0006ms 2.5% faster
fixed_width_array_scan_matrix[first-random_no_match-32] 0.0012ms 0.0012ms 0.1% faster
fixed_width_array_scan_matrix[first-threshold_d-16] 0.0003ms 0.0003ms 0.6% slower
fixed_width_array_scan_matrix[first-threshold_d-32] 0.0007ms 0.0007ms 0.2% slower
fixed_width_array_scan_matrix[first-threshold_d_minus_1-16] 0.0006ms 0.0006ms 0.0% faster
fixed_width_array_scan_matrix[first-threshold_d_minus_1-32] 0.0012ms 0.0012ms 0.2% faster
fixed_width_array_scan_matrix[first-threshold_d_plus_1-16] 0.0003ms 0.0003ms 0.0% faster
fixed_width_array_scan_matrix[first-threshold_d_plus_1-32] 0.0007ms 0.0007ms 0.5% slower
hd_bytes[1000-diff] 0.0001ms 0.0001ms 9.6% faster
hd_bytes[1000-same] 0.0000ms 0.0000ms 6.3% faster
hd_bytes[1024-diff] 0.0001ms 0.0001ms 7.6% slower
hd_bytes[1024-same] 0.0000ms 0.0000ms 5.0% faster
hd_bytes[3-diff] 0.0001ms 0.0000ms 59.1% faster
hd_bytes[3-same] 0.0000ms 0.0000ms 0.3% slower
hd_bytes[64-diff] 0.0000ms 0.0000ms 5.9% slower
hd_bytes_buffer[bytearray] 0.0001ms 0.0001ms 4.6% faster
hd_bytes_buffer[memoryview] 0.0001ms 0.0001ms 4.2% faster
hd_bytes_gil_boundary[16376] 0.0002ms 0.0003ms 49.6% slower
hd_bytes_gil_boundary[16384] 0.0004ms 0.0003ms 18.1% faster
hd_bytes_gil_boundary[16392] 0.0003ms 0.0004ms 38.0% slower
hd_bytes_random[1024] 0.0001ms 0.0001ms 0.4% slower
hd_bytes_random[16] 0.0000ms 0.0000ms 7.3% faster
hd_bytes_random[64] 0.0001ms 0.0000ms 8.1% faster
hd_string[1000-diff] 0.0001ms 0.0001ms 4.2% faster
hd_string[1000-same] 0.0001ms 0.0001ms 0.1% slower
hd_string[1024-diff] 0.0001ms 0.0001ms 3.0% faster
hd_string[1024-same] 0.0001ms 0.0001ms 2.9% faster
hd_string[3-diff] 0.0000ms 0.0001ms 132.7% slower
hd_string[3-same] 0.0000ms 0.0000ms 0.3% slower
hd_string[64-diff] 0.0001ms 0.0000ms 8.2% faster
hd_string_random[1024] 0.0001ms 0.0001ms 0.2% slower
hd_string_random[16] 0.0000ms 0.0001ms 117.7% slower
hd_string_random[64] 0.0001ms 0.0000ms 4.9% faster
stdlib_bytes_distance_random[1024] 0.0019ms 0.0019ms 0.3% faster
stdlib_bytes_distance_random[16] 0.0002ms 0.0002ms 0.7% faster
stdlib_bytes_distance_random[64] 0.0003ms 0.0003ms 0.6% faster
stdlib_hex_distance_random[1024] 0.0024ms 0.0024ms 0.2% faster
stdlib_hex_distance_random[16] 0.0002ms 0.0003ms 42.3% slower
stdlib_hex_distance_random[64] 0.0003ms 0.0003ms 0.2% faster

Legend: ✅ Faster (>5%) · ⚠️ Slower (5-30%) · ❌ Regression (>30%) · 🆕 New · 🗑️ Removed


⛔ This PR has severe performance regressions (>20% slower). Please investigate before merging.

Parse hex with one vqtbl4q_u8 per 16 chars, indexed by `char - '0'`.
Hex digits map to 0x10 | nibble and everything else to 0 (indices past
63, including bytes below '0' after wrapping, also yield 0). XOR of
two valid chars cancels the tag, so vcnt of the unpacked XOR is the
per-char distance and no nibble packing is needed. Validity is the
running lane-wise minimum, checked once per call; the final partial
chunk re-reads the last 16 chars and masks the overlap, replacing the
16-char and scalar tails. This takes the steady-state loop from ~50 to
~20 SIMD ops per 32 chars.

check_hexstrings_within_dist uses the same parse inside the existing
_with_max block structure (eager 32-char blocks, 31-block batches,
16-char chunk, scalar tail). Both parses accept exactly the hex
digits and invalid input is still tested before the threshold at
every check point, so results are unchanged, including which of
"invalid char" and "over max_dist" is reported. The old pack kernel
stays as the reference for the tests and hex_hamming_distance_pack.

Criterion, "f"*n vs "0"*n (old pack kernel -> new):
  32 chars   2.84 ->  2.06 ns  1.38x
  64 chars   5.39 ->  3.74 ns  1.44x
  128 chars 10.66 ->  7.12 ns  1.50x
  254 chars 20.10 -> 13.71 ns  1.47x

Interleaved Python A/B (Apple M4 Max, CPython 3.14, previous layer ->
this layer):
  hamming_distance_string/254     46.7 ->  37.3 ns  1.25x
  hamming_distance_string/1024   106.7 ->  75.4 ns  1.42x
  hamming_distance_string/4096   378.4 -> 254.9 ns  1.48x
  hamming_distance_string/63      34.0 ->  28.4 ns  1.19x
  check_hexstrings_within_dist/254,d=60  38.5 -> 34.0 ns  1.13x

Tests:
- Exhaustive comparison against the classic kernel at lengths 0..=300
  and around the batch boundaries.
- Every invalid byte class at every position for lengths 1..=80.
- 6000 randomized _with_max cases against the pack kernel. The test
  asserts that cases decided by precedence occur, both invalid-wins and
  threshold-wins.
- A 60k-case Python differential against the previous layer found no
  divergences in values or error messages.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c7edd725-5714-4044-acf4-c9afc6ec8cf8
@mrecachinas
mrecachinas merged commit ac2e987 into main Sep 23, 2026
31 checks passed
@mrecachinas
mrecachinas deleted the perf/neon-hex-lut branch September 23, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant