[ranbenbasat]

Faiss's HadamardRotation currently applies three sign-flip/FWHT rounds
unconditionally. This change makes the depth selectable so users can measure
and tune the preprocessing-cost/quantization-quality tradeoff with one, two,
or three rounds. The default remains three rounds.

rotation = faiss.HadamardRotation(d, 42, 2)
index = faiss.index_factory(d, "HR42r2,IVF128,RaBitQ2")

Existing HR and HR42 factory strings keep their current three-round
behavior; 42 remains the seed. New HRr1, HRr2, HRr3, and HR42r2
tokens explicitly select the count. Dense rotation and no preprocessing remain
available through the existing interfaces.

Implementation

• Select one, two, or three existing sign/FWHT factors in one parallel region,
  with the matching inverse and count validation.
• Preserve the existing sign stream and three-round arithmetic. Equal seeds
  give nested sign prefixes for paired comparisons.
• Keep three-round HRot serialization byte-for-byte compatible. Use a
  distinct counted format, HRnd, for one/two rounds and validate it before
  allocation. Existing files read as three rounds.
• Update the Python typing declarations and add numerical-reference,
  legacy-compatibility, factory, IO, malformed-input, and search tests.

Motivation and reproducible evaluation

Quantizing With Randomized Hadamard Transforms: Efficient Heuristic Now
Proven distinguishes scalar marginal behavior
after two RHTs from fixed-block vector behavior after three. This motivates
measuring depth as an explicit choice; it is not a theorem about ANN recall.

benchs/bench_rht.py and its reproduction guide compare RaBitQ and EDEN at
2/3/4 stored bits under none, shared Haar URR, and 1/2/3 RHTs. They report:

• Reconstruction NMSE/vNMSE, using the full multibit RaBitQ code rather than
  its sign-only decoder.
• Exact-ground-truth set Recall@k, paired seed/query confidence intervals,
  and raw per-query recalls.
• Full search time including query preprocessing, plus separate transform,
  initialization, training, and encoding/add timings.
• Physical code/serialized sizes, native-size and matched-padded-dimension
  controls, and effective BLAS/OpenMP thread limits.
• Dataset/split/hash, native-library/build, hostname, seed, batch, and command
  provenance, with a host guard for designated measurement machines.

The current runner covers flat compressed scans. IVF/FastScan measurements
and matched-recall QPS curves are follow-up evidence; flat results will not be
presented as validation of those structures. No adaptive routing is included.

Initial Amumu pilot

An optimized Arrow Lake/AVX2 build on Amumu completed a 150-case MSong flat-scan pilot: 4,096 training vectors, 20,000 base vectors, 200 queries, all five preprocessing modes, both quantizers, 2/3/4 bits, and five paired transform seeds. The table gives set Recall@100 and percentage-point deltas relative to 1RHT, with paired seed/query bootstrap 95% intervals.

Quantizer	Bits	1RHT recall %	2RHT delta pp [95% CI]	3RHT delta pp [95% CI]
RaBitQ	2	86.657	2.234 [1.616, 2.901]	2.262 [1.639, 2.943]
RaBitQ	3	94.039	-0.190 [-0.463, 0.081]	-0.241 [-0.460, -0.034]
RaBitQ	4	96.478	0.034 [-0.113, 0.178]	-0.014 [-0.185, 0.165]
EDEN	2	88.682	0.245 [-0.170, 0.644]	0.315 [-0.130, 0.729]
EDEN	3	94.062	-0.115 [-0.394, 0.159]	-0.049 [-0.288, 0.173]
EDEN	4	96.857	-0.082 [-0.262, 0.113]	-0.102 [-0.279, 0.062]

Both added depths improve 2-bit RaBitQ recall in this subset. EDEN intervals include zero; higher-bit RaBitQ outcomes are mixed. Pooled NMSE and vNMSE, computed on the first 10,000 searched vectors, were higher with 2/3RHT than 1RHT for both quantizers at every tested budget. All three RHT depths use the same 512-coordinate output; native-size none/URR retain 420 coordinates and have a separate matched-padding control queued.

This pilot is not a replication of the paper's MSong figure. The archived experiment uses a 448-dimensional block-FHT/Kac construction, fixed Gaussian-calibrated code thresholds, 128 residual centers, full-precision queries and the full database. This contribution uses full 512-dimensional RHTs and native per-vector code scaling; its flat pilot uses one center and the RaBitQ query-bit setting of 4. The paper's best-scalar residual vNMSE also differs from the actual-score reconstruction diagnostic above.

A bounded quality audit on Amumu completed 216 transform/centering/quantizer cases and 90 native query-bit cases. With the same pilot data, 128 frozen centroids and historical thresholds, the block/Kac construction retained large depth gains, while full-512 started with higher one-round mean recall and gained little. This comparison changes transform construction and code dimension together (512 versus 448), so it does not isolate the Kac layer or establish an equal-storage advantage. It uses two NumPy transform seeds and is not a full historical replication. Changing qb=4 to qb=0 on identical native codes changed mean recall by at most 0.002 percentage points; all 45 qb=4 replays exactly matched the original pilot's per-query recalls. Query precision is therefore not a material explanation in this pilot.

This prefix subset has disjoint training/base source-row ranges but 21 exact-value overlaps. Results condition on its fixed data and five seeds. Speed remains provisional: 14/95 workload samples exceeded the declared desktop-activity threshold. No speedup is claimed from this pilot.

Full five-way results, metric definitions, uncertainty and provenance and the hash-verified raw evidence capsule are on the separate evidence branch. Native-dimension IVF/RaBitQ, IVF/EDEN and IVF/RaBitQFastScan nprobe sweeps have completed; matched-padding sweeps are running on Amumu. Their interpretation, broader datasets, randomized splits and quieter runtime replication remain in progress.

Validation

• Generic CPU build and SWIG bindings built successfully on Windows/MSVC.
• Focused Python regression suite: 402 passed, 9 skipped, 321 subtests
  passed. One existing PCA overflow warning remains.
• Focused C++ suite: 6 passed, including the new round-count tests.
• Amumu's optimized build: 28 focused tests passed (11 transform and 17
  benchmark checks), including one-bit reconstruction/score validation.
• CPU/GPU/cuVS Conda test source layouts include the benchmark script;
  all 13 helper tests pass in each staged layout.
• Independent review covered native arithmetic, factory/IO compatibility,
  full-code NMSE, Haar construction, and benchmark threading.
• Changed native C++ files match clang-format 21.1.8; whitespace checks pass.

Draft status

The code, tests, benchmark tooling and qualified first pilot are ready for
early maintainer feedback. Amumu experiments are in progress, including
ANN, matched-padding, additional datasets and clean runtime replication.
The contribution remains a draft while that evidence is collected and reviewed.
Neutral and negative cases are retained. Historical rebuttal figures used a
different transform for some dimensions and are not treated as validation
of this implementation.