faiss 0.4.3 → 0.5.1

data/vendor/faiss/faiss/impl/index_write.cpp

@@ -27,11 +27,13 @@
 #include <faiss/IndexIVFAdditiveQuantizer.h>
 #include <faiss/IndexIVFAdditiveQuantizerFastScan.h>
 #include <faiss/IndexIVFFlat.h>
+#include <faiss/IndexIVFFlatPanorama.h>
 #include <faiss/IndexIVFIndependentQuantizer.h>
 #include <faiss/IndexIVFPQ.h>
 #include <faiss/IndexIVFPQFastScan.h>
 #include <faiss/IndexIVFPQR.h>
 #include <faiss/IndexIVFRaBitQ.h>
+#include <faiss/IndexIVFRaBitQFastScan.h>
 #include <faiss/IndexIVFSpectralHash.h>
 #include <faiss/IndexLSH.h>
 #include <faiss/IndexLattice.h>
@@ -41,8 +43,16 @@
 #include <faiss/IndexPQFastScan.h>
 #include <faiss/IndexPreTransform.h>
 #include <faiss/IndexRaBitQ.h>
+#include <faiss/IndexRaBitQFastScan.h>
 #include <faiss/IndexRefine.h>
 #include <faiss/IndexRowwiseMinMax.h>
+#ifdef FAISS_ENABLE_SVS
+#include <faiss/impl/svs_io.h>
+#include <faiss/svs/IndexSVSFlat.h>
+#include <faiss/svs/IndexSVSVamana.h>
+#include <faiss/svs/IndexSVSVamanaLVQ.h>
+#include <faiss/svs/IndexSVSVamanaLeanVec.h>
+#endif
 #include <faiss/IndexScalarQuantizer.h>
 #include <faiss/MetaIndexes.h>
 #include <faiss/VectorTransform.h>
@@ -68,7 +78,7 @@
  * or deprecated fields), the fourcc can be replaced. New code should
  * be able to read the old fourcc and fill in new classes.
  *
- * TODO: in this file, the read functions that encouter errors may
+ * TODO: in this file, the read functions that encounter errors may
  * leak memory.
  **************************************************************/
 
@@ -245,6 +255,33 @@ void write_InvertedLists(const InvertedLists* ils, IOWriter* f) {
     if (ils == nullptr) {
         uint32_t h = fourcc("il00");
         WRITE1(h);
+    } else if (
+            const auto& ailp =
+                    dynamic_cast<const ArrayInvertedListsPanorama*>(ils)) {
+        uint32_t h = fourcc("ilpn");
+        WRITE1(h);
+        WRITE1(ailp->nlist);
+        WRITE1(ailp->code_size);
+        WRITE1(ailp->n_levels);
+        uint32_t list_type = fourcc("full");
+        WRITE1(list_type);
+        std::vector<size_t> sizes;
+        sizes.reserve(ailp->nlist);
+        for (size_t i = 0; i < ailp->nlist; i++) {
+            sizes.push_back(ailp->ids[i].size());
+        }
+        WRITEVECTOR(sizes);
+
+        // Write codes, ids, and cum_sums
+        for (size_t i = 0; i < ailp->nlist; i++) {
+            size_t n = ailp->ids[i].size();
+            if (n > 0) {
+                WRITEANDCHECK(ailp->codes[i].data(), ailp->codes[i].size());
+                WRITEANDCHECK(ailp->ids[i].data(), n);
+                WRITEANDCHECK(
+                        ailp->cum_sums[i].data(), ailp->cum_sums[i].size());
+            }
+        }
     } else if (
             const auto& ails = dynamic_cast<const ArrayInvertedLists*>(ils)) {
         uint32_t h = fourcc("ilar");
@@ -366,11 +403,17 @@ static void write_NNDescent(const NNDescent* nnd, IOWriter* f) {
     WRITEVECTOR(nnd->final_graph);
 }
 
-static void write_RaBitQuantizer(const RaBitQuantizer* rabitq, IOWriter* f) {
-    // don't care about rabitq->centroid
+// Write RaBitQuantizer for 1-bit format (backward compatible)
+static void write_RaBitQuantizer(
+        const RaBitQuantizer* rabitq,
+        IOWriter* f,
+        bool multi_bit = true) {
     WRITE1(rabitq->d);
     WRITE1(rabitq->code_size);
     WRITE1(rabitq->metric_type);
+    if (multi_bit) {
+        WRITE1(rabitq->nb_bits);
+    }
 }
 
 static void write_direct_map(const DirectMap* dm, IOWriter* f) {
@@ -402,6 +445,18 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
         // eg. for a storage component of HNSW that is set to nullptr
         uint32_t h = fourcc("null");
         WRITE1(h);
+    } else if (
+            const IndexFlatL2Panorama* idxpan =
+                    dynamic_cast<const IndexFlatL2Panorama*>(idx)) {
+        uint32_t h = fourcc("IxFP");
+        WRITE1(h);
+        WRITE1(idxpan->d);
+        WRITE1(idxpan->n_levels);
+        WRITE1(idxpan->batch_size);
+        WRITE1(idxpan->ntotal);
+        WRITE1(idxpan->is_trained);
+        WRITEVECTOR(idxpan->codes);
+        WRITEVECTOR(idxpan->cum_sums);
     } else if (const IndexFlat* idxf = dynamic_cast<const IndexFlat*>(idx)) {
         uint32_t h =
                 fourcc(idxf->metric_type == METRIC_INNER_PRODUCT ? "IxFI"
@@ -638,6 +693,14 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
             WRITEVECTOR(tab);
         }
         write_InvertedLists(ivfl->invlists, f);
+    } else if (
+            const IndexIVFFlatPanorama* ivfp =
+                    dynamic_cast<const IndexIVFFlatPanorama*>(idx)) {
+        uint32_t h = fourcc("IwPn");
+        WRITE1(h);
+        write_ivf_header(ivfp, f);
+        WRITE1(ivfp->n_levels);
+        write_InvertedLists(ivfp->invlists, f);
     } else if (
             const IndexIVFFlat* ivfl_2 =
                     dynamic_cast<const IndexIVFFlat*>(idx)) {
@@ -752,7 +815,9 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
         write_ProductQuantizer(&imiq->pq, f);
     } else if (
             const IndexRefine* idxrf = dynamic_cast<const IndexRefine*>(idx)) {
-        uint32_t h = fourcc("IxRF");
+        bool is_pano =
+                dynamic_cast<const IndexRefinePanorama*>(idxrf) != nullptr;
+        uint32_t h = is_pano ? fourcc("IxRP") : fourcc("IxRF");
         WRITE1(h);
         write_index_header(idxrf, f);
         write_index(idxrf->base_index, f);
@@ -768,15 +833,23 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
         write_index(idxmap->index, f);
         WRITEVECTOR(idxmap->id_map);
     } else if (const IndexHNSW* idxhnsw = dynamic_cast<const IndexHNSW*>(idx)) {
-        uint32_t h = dynamic_cast<const IndexHNSWFlat*>(idx) ? fourcc("IHNf")
-                : dynamic_cast<const IndexHNSWPQ*>(idx)      ? fourcc("IHNp")
-                : dynamic_cast<const IndexHNSWSQ*>(idx)      ? fourcc("IHNs")
-                : dynamic_cast<const IndexHNSW2Level*>(idx)  ? fourcc("IHN2")
-                : dynamic_cast<const IndexHNSWCagra*>(idx)   ? fourcc("IHc2")
-                                                             : 0;
+        uint32_t h = dynamic_cast<const IndexHNSWFlatPanorama*>(idx)
+                ? fourcc("IHfP")
+                : dynamic_cast<const IndexHNSWFlat*>(idx)   ? fourcc("IHNf")
+                : dynamic_cast<const IndexHNSWPQ*>(idx)     ? fourcc("IHNp")
+                : dynamic_cast<const IndexHNSWSQ*>(idx)     ? fourcc("IHNs")
+                : dynamic_cast<const IndexHNSW2Level*>(idx) ? fourcc("IHN2")
+                : dynamic_cast<const IndexHNSWCagra*>(idx)  ? fourcc("IHc2")
+                                                            : 0;
         FAISS_THROW_IF_NOT(h != 0);
         WRITE1(h);
         write_index_header(idxhnsw, f);
+        if (h == fourcc("IHfP")) {
+            auto idx_panorama =
+                    dynamic_cast<const IndexHNSWFlatPanorama*>(idxhnsw);
+            WRITE1(idx_panorama->num_panorama_levels);
+            WRITEVECTOR(idx_panorama->cum_sums);
+        }
         if (h == fourcc("IHc2")) {
             WRITE1(idxhnsw->keep_max_size_level0);
             auto idx_hnsw_cagra = dynamic_cast<const IndexHNSWCagra*>(idxhnsw);
@@ -848,7 +921,7 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
     } else if (
             const IndexRowwiseMinMax* imm =
                     dynamic_cast<const IndexRowwiseMinMax*>(idx)) {
-        // IndexRowwiseMinmaxFloat
+        // IndexRowwiseMinMaxFloat
         uint32_t h = fourcc("IRMf");
         WRITE1(h);
         write_index_header(imm, f);
@@ -856,31 +929,151 @@ void write_index(const Index* idx, IOWriter* f, int io_flags) {
     } else if (
             const IndexRowwiseMinMaxFP16* imm_2 =
                     dynamic_cast<const IndexRowwiseMinMaxFP16*>(idx)) {
-        // IndexRowwiseMinmaxHalf
+        // IndexRowwiseMinMaxHalf
         uint32_t h = fourcc("IRMh");
         WRITE1(h);
         write_index_header(imm_2, f);
         write_index(imm_2->index, f);
     } else if (
-            const IndexRaBitQ* idxq = dynamic_cast<const IndexRaBitQ*>(idx)) {
-        uint32_t h = fourcc("Ixrq");
+            const IndexRaBitQFastScan* idxqfs =
+                    dynamic_cast<const IndexRaBitQFastScan*>(idx)) {
+        uint32_t h = fourcc("Irfs");
         WRITE1(h);
         write_index_header(idx, f);
-        write_RaBitQuantizer(&idxq->rabitq, f);
+        write_RaBitQuantizer(&idxqfs->rabitq, f);
+        WRITEVECTOR(idxqfs->center);
+        WRITE1(idxqfs->qb);
+        WRITEVECTOR(idxqfs->flat_storage);
+        WRITE1(idxqfs->bbs);
+        WRITE1(idxqfs->ntotal2);
+        WRITE1(idxqfs->M2);
+        WRITE1(idxqfs->code_size);
+        WRITEVECTOR(idxqfs->codes);
+    } else if (
+            const IndexRaBitQ* idxq = dynamic_cast<const IndexRaBitQ*>(idx)) {
+        // Use different fourcc codes for 1-bit vs multi-bit
+        if (idxq->rabitq.nb_bits == 1) {
+            uint32_t h = fourcc("Ixrq"); // 1-bit (backward compatible)
+            WRITE1(h);
+            write_index_header(idx, f);
+            write_RaBitQuantizer(&idxq->rabitq, f, false);
+        } else {
+            uint32_t h = fourcc("Ixrr"); // multi-bit (new format)
+            WRITE1(h);
+            write_index_header(idx, f);
+            write_RaBitQuantizer(&idxq->rabitq, f, true);
+        }
         WRITEVECTOR(idxq->codes);
         WRITEVECTOR(idxq->center);
         WRITE1(idxq->qb);
     } else if (
             const IndexIVFRaBitQ* ivrq =
                     dynamic_cast<const IndexIVFRaBitQ*>(idx)) {
-        uint32_t h = fourcc("Iwrq");
-        WRITE1(h);
-        write_ivf_header(ivrq, f);
-        write_RaBitQuantizer(&ivrq->rabitq, f);
+        // Use different fourcc codes for 1-bit vs multi-bit
+        if (ivrq->rabitq.nb_bits == 1) {
+            uint32_t h = fourcc("Iwrq"); // 1-bit (backward compatible)
+            WRITE1(h);
+            write_ivf_header(ivrq, f);
+            write_RaBitQuantizer(&ivrq->rabitq, f, false);
+        } else {
+            uint32_t h = fourcc("Iwrr"); // multi-bit (new format)
+            WRITE1(h);
+            write_ivf_header(ivrq, f);
+            write_RaBitQuantizer(&ivrq->rabitq, f, true);
+        }
         WRITE1(ivrq->code_size);
         WRITE1(ivrq->by_residual);
         WRITE1(ivrq->qb);
         write_InvertedLists(ivrq->invlists, f);
+    }
+#ifdef FAISS_ENABLE_SVS
+    else if (
+            const IndexSVSVamana* svs =
+                    dynamic_cast<const IndexSVSVamana*>(idx)) {
+        uint32_t h;
+        auto* lvq = dynamic_cast<const IndexSVSVamanaLVQ*>(svs);
+        auto* lean = dynamic_cast<const IndexSVSVamanaLeanVec*>(svs);
+        if (lvq != nullptr) {
+            h = fourcc("ILVQ"); // LVQ
+        } else if (lean != nullptr) {
+            h = fourcc("ISVL"); // LeanVec
+        } else {
+            h = fourcc("ISVD"); // uncompressed
+        }
+
+        WRITE1(h);
+        write_index_header(svs, f);
+        WRITE1(svs->graph_max_degree);
+        WRITE1(svs->alpha);
+        WRITE1(svs->search_window_size);
+        WRITE1(svs->search_buffer_capacity);
+        WRITE1(svs->construction_window_size);
+        WRITE1(svs->max_candidate_pool_size);
+        WRITE1(svs->prune_to);
+        WRITE1(svs->use_full_search_history);
+        WRITE1(svs->storage_kind);
+
+        if (lean != nullptr) {
+            WRITE1(lean->leanvec_d);
+        }
+
+        bool initialized = (svs->impl != nullptr);
+        WRITE1(initialized);
+        if (initialized) {
+            faiss::BufferedIOWriter bwr(f);
+            faiss::svs_io::WriterStreambuf wbuf(&bwr);
+            std::ostream os(&wbuf);
+            svs->serialize_impl(os);
+            os.flush();
+        }
+
+        if (lean != nullptr) {
+            // Store training data info
+            bool trained = (lean->training_data != nullptr);
+            WRITE1(trained);
+            if (trained) {
+                faiss::BufferedIOWriter bwr(f);
+                faiss::svs_io::WriterStreambuf wbuf(&bwr);
+                std::ostream os(&wbuf);
+                lean->serialize_training_data(os);
+                os.flush();
+            }
+        }
+    } else if (
+            const IndexSVSFlat* svs = dynamic_cast<const IndexSVSFlat*>(idx)) {
+        uint32_t h = fourcc("ISVF");
+        WRITE1(h);
+        write_index_header(idx, f);
+
+        bool initialized = (svs->impl != nullptr);
+        WRITE1(initialized);
+        if (initialized) {
+            // Wrap SVS I/O and stream to IOWriter
+            faiss::BufferedIOWriter bwr(f);
+            faiss::svs_io::WriterStreambuf wbuf(&bwr);
+            std::ostream os(&wbuf);
+            svs->serialize_impl(os);
+            os.flush();
+        }
+    }
+#endif // FAISS_ENABLE_SVS
+    else if (
+            const IndexIVFRaBitQFastScan* ivrqfs =
+                    dynamic_cast<const IndexIVFRaBitQFastScan*>(idx)) {
+        uint32_t h = fourcc("Iwrf");
+        WRITE1(h);
+        write_ivf_header(ivrqfs, f);
+        write_RaBitQuantizer(&ivrqfs->rabitq, f);
+        WRITE1(ivrqfs->by_residual);
+        WRITE1(ivrqfs->code_size);
+        WRITE1(ivrqfs->bbs);
+        WRITE1(ivrqfs->qbs2);
+        WRITE1(ivrqfs->M2);
+        WRITE1(ivrqfs->implem);
+        WRITE1(ivrqfs->qb);
+        WRITE1(ivrqfs->centered);
+        WRITEVECTOR(ivrqfs->flat_storage);
+        write_InvertedLists(ivrqfs->invlists, f);
     } else {
         FAISS_THROW_MSG("don't know how to serialize this type of index");
     }

data/vendor/faiss/faiss/impl/io.cpp

@@ -74,7 +74,7 @@ FileIOReader::FileIOReader(const char* fname) {
 FileIOReader::~FileIOReader() {
     if (need_close) {
         int ret = fclose(f);
-        if (ret != 0) { // we cannot raise and exception in the destructor
+        if (ret != 0) { // we cannot raise an exception in the destructor
             fprintf(stderr,
                     "file %s close error: %s",
                     name.c_str(),
@@ -109,7 +109,7 @@ FileIOWriter::~FileIOWriter() {
     if (need_close) {
         int ret = fclose(f);
         if (ret != 0) {
-            // we cannot raise and exception in the destructor
+            // we cannot raise an exception in the destructor
             fprintf(stderr,
                     "file %s close error: %s",
                     name.c_str(),

data/vendor/faiss/faiss/impl/io.h

@@ -65,9 +65,9 @@ struct FileIOReader : IOReader {
     FILE* f = nullptr;
     bool need_close = false;
 
-    FileIOReader(FILE* rf);
+    explicit FileIOReader(FILE* rf);
 
-    FileIOReader(const char* fname);
+    explicit FileIOReader(const char* fname);
 
     ~FileIOReader() override;
 
@@ -80,9 +80,9 @@ struct FileIOWriter : IOWriter {
     FILE* f = nullptr;
     bool need_close = false;
 
-    FileIOWriter(FILE* wf);
+    explicit FileIOWriter(FILE* wf);
 
-    FileIOWriter(const char* fname);
+    explicit FileIOWriter(const char* fname);
 
     ~FileIOWriter() override;
 

data/vendor/faiss/faiss/impl/kmeans1d.cpp

@@ -141,7 +141,7 @@ void smawk(
 namespace {
 
 class CostCalculator {
-    // The reuslt would be inaccurate if we use float
+    // The result would be inaccurate if we use float
     std::vector<double> cumsum;
     std::vector<double> cumsum2;
 

data/vendor/faiss/faiss/impl/kmeans1d.h

@@ -41,7 +41,7 @@ void smawk(
  * @param n          input array length
  * @param nclusters  number of clusters
  * @param centroids  output centroids, size nclusters
- * @return  imbalancce factor
+ * @return  imbalance factor
  */
 double kmeans1d(const float* x, size_t n, size_t nclusters, float* centroids);
 

data/vendor/faiss/faiss/impl/lattice_Zn.h

@@ -26,7 +26,7 @@ struct ZnSphereSearch {
     int dimS, r2;
     int natom;
 
-    /// size dim * ntatom
+    /// size dim * natom
     std::vector<float> voc;
 
     ZnSphereSearch(int dim, int r2);
@@ -138,7 +138,7 @@ struct ZnSphereCodec : ZnSphereSearch, EnumeratedVectors {
  *
  * Uses a recursive decomposition on the dimensions to encode
  * centroids found by the ZnSphereSearch. The codes are *not*
- * compatible with the ones of ZnSpehreCodec
+ * compatible with the ones of ZnSphereCodec
  */
 struct ZnSphereCodecRec : EnumeratedVectors {
     int r2;

data/vendor/faiss/faiss/impl/mapped_io.cpp

@@ -33,7 +33,7 @@ struct MmappedFileMappingOwner::PImpl {
     void* ptr = nullptr;
     size_t ptr_size = 0;
 
-    PImpl(const std::string& filename) {
+    explicit PImpl(const std::string& filename) {
         auto f = std::unique_ptr<FILE, decltype(&fclose)>(
                 fopen(filename.c_str(), "r"), &fclose);
         FAISS_THROW_IF_NOT_FMT(
@@ -64,7 +64,7 @@ struct MmappedFileMappingOwner::PImpl {
         ptr_size = filesize;
     }
 
-    PImpl(FILE* f) {
+    explicit PImpl(FILE* f) {
         // get the size
         struct stat s;
         int status = fstat(fileno(f), &s);

data/vendor/faiss/faiss/impl/mapped_io.h

@@ -18,8 +18,8 @@ namespace faiss {
 
 // holds a memory-mapped region over a file
 struct MmappedFileMappingOwner : public MaybeOwnedVectorOwner {
-    MmappedFileMappingOwner(const std::string& filename);
-    MmappedFileMappingOwner(FILE* f);
+    explicit MmappedFileMappingOwner(const std::string& filename);
+    explicit MmappedFileMappingOwner(FILE* f);
     ~MmappedFileMappingOwner();
 
     void* data() const;
@@ -37,7 +37,8 @@ struct MappedFileIOReader : IOReader {
 
     size_t pos = 0;
 
-    MappedFileIOReader(const std::shared_ptr<MmappedFileMappingOwner>& owner);
+    explicit MappedFileIOReader(
+            const std::shared_ptr<MmappedFileMappingOwner>& owner);
 
     // perform a copy
     size_t operator()(void* ptr, size_t size, size_t nitems) override;

data/vendor/faiss/faiss/impl/maybe_owned_vector.h

@@ -51,7 +51,7 @@ struct MaybeOwnedVector {
     size_t c_size = 0;
 
     MaybeOwnedVector() = default;
-    MaybeOwnedVector(const size_t initial_size) {
+    explicit MaybeOwnedVector(const size_t initial_size) {
         is_owned = true;
 
         owned_data.resize(initial_size);
@@ -295,9 +295,16 @@ struct is_maybe_owned_vector : std::false_type {};
 template <typename T>
 struct is_maybe_owned_vector<MaybeOwnedVector<T>> : std::true_type {};
 
+// guard with c++-17 (maybe, it is available somewhere in
+// faiss/impl/platform.h?).
+// This allows headers to be included in c++11 code.
+#if ((defined(_MSVC_LANG) && _MSVC_LANG >= 201703L) || __cplusplus >= 201703L)
+
 template <typename T>
 inline constexpr bool is_maybe_owned_vector_v = is_maybe_owned_vector<T>::value;
 
+#endif
+
 template <typename T>
 bool operator==(
         const MaybeOwnedVector<T>& lhs,

data/vendor/faiss/faiss/impl/platform_macros.h

@@ -107,6 +107,12 @@ inline int __builtin_clzll(uint64_t x) {
 
 #define FAISS_ALWAYS_INLINE __forceinline
 
+// MSVC uses pragma pack instead of __attribute__((packed))
+// Use FAISS_PACK_STRUCTS_BEGIN/END to wrap packed structure definitions
+#define FAISS_PACKED
+#define FAISS_PACK_STRUCTS_BEGIN __pragma(pack(push, 1))
+#define FAISS_PACK_STRUCTS_END __pragma(pack(pop))
+
 #else
 /*******************************************************
  * Linux and OSX
@@ -119,10 +125,16 @@ inline int __builtin_clzll(uint64_t x) {
 // windows
 #ifdef SWIG
 #define ALIGNED(x)
+#define FAISS_PACKED
 #else
 #define ALIGNED(x) __attribute__((aligned(x)))
+#define FAISS_PACKED __attribute__((packed))
 #endif
 
+// On non-Windows, FAISS_PACKED handles packing, so these are no-ops
+#define FAISS_PACK_STRUCTS_BEGIN
+#define FAISS_PACK_STRUCTS_END
+
 #define FAISS_ALWAYS_INLINE __attribute__((always_inline)) inline
 
 #endif

data/vendor/faiss/faiss/impl/pq4_fast_scan.cpp

@@ -49,7 +49,19 @@ void pq4_pack_codes(
         size_t nb,
         size_t bbs,
         size_t nsq,
-        uint8_t* blocks) {
+        uint8_t* blocks,
+        size_t code_stride) {
+    // Determine stride: use custom if provided, otherwise use legacy
+    // calculation
+    size_t actual_stride = (code_stride == 0) ? (M + 1) / 2 : code_stride;
+
+    // Input validation for custom stride
+    if (code_stride != 0) {
+        FAISS_THROW_IF_NOT_MSG(
+                code_stride >= (M + 1) / 2,
+                "Custom stride must be >= minimum code size");
+    }
+
     FAISS_THROW_IF_NOT(bbs % 32 == 0);
     FAISS_THROW_IF_NOT(nb % bbs == 0);
     FAISS_THROW_IF_NOT(nsq % 2 == 0);
@@ -72,7 +84,8 @@ void pq4_pack_codes(
             for (size_t i = 0; i < bbs; i += 32) {
                 std::array<uint8_t, 32> c, c0, c1;
                 get_matrix_column(
-                        codes, ntotal, (M + 1) / 2, i0 + i, sq / 2, c);
+                        codes, ntotal, actual_stride, i0 + i, sq / 2, c);
+
                 for (int j = 0; j < 32; j++) {
                     c0[j] = c[j] & 15;
                     c1[j] = c[j] >> 4;
@@ -97,7 +110,19 @@ void pq4_pack_codes_range(
         size_t i1,
         size_t bbs,
         size_t nsq,
-        uint8_t* blocks) {
+        uint8_t* blocks,
+        size_t code_stride) {
+    // Determine stride: use custom if provided, otherwise use legacy
+    // calculation
+    size_t actual_stride = (code_stride == 0) ? (M + 1) / 2 : code_stride;
+
+    // Input validation for custom stride
+    if (code_stride != 0) {
+        FAISS_THROW_IF_NOT_MSG(
+                code_stride >= (M + 1) / 2,
+                "Custom stride must be >= minimum code size");
+    }
+
 #ifdef FAISS_BIG_ENDIAN
     const uint8_t perm0[16] = {
             8, 0, 9, 1, 10, 2, 11, 3, 12, 4, 13, 5, 14, 6, 15, 7};
@@ -117,7 +142,8 @@ void pq4_pack_codes_range(
             for (size_t i = 0; i < bbs; i += 32) {
                 std::array<uint8_t, 32> c, c0, c1;
                 get_matrix_column(
-                        codes, i1 - i0, (M + 1) / 2, i_base + i, sq / 2, c);
+                        codes, i1 - i0, actual_stride, i_base + i, sq / 2, c);
+
                 for (int j = 0; j < 32; j++) {
                     c0[j] = c[j] & 15;
                     c1[j] = c[j] >> 4;

data/vendor/faiss/faiss/impl/pq4_fast_scan.h

@@ -34,9 +34,11 @@ struct SIMDResultHandler;
  * @param ntotal  number of input codes
  * @param nb      output number of codes (ntotal rounded up to a multiple of
  *                bbs)
- * @param nsq      number of sub-quantizers (=M rounded up to a muliple of 2)
+ * @param nsq      number of sub-quantizers (=M rounded up to a multiple of 2)
  * @param bbs     size of database blocks (multiple of 32)
  * @param blocks  output array, size nb * nsq / 2.
+ * @param code_stride  optional stride between consecutive codes (0 = use
+default (M + 1) / 2)
  */
 void pq4_pack_codes(
         const uint8_t* codes,
@@ -45,7 +47,8 @@ void pq4_pack_codes(
         size_t nb,
         size_t bbs,
         size_t nsq,
-        uint8_t* blocks);
+        uint8_t* blocks,
+        size_t code_stride = 0);
 
 /** Same as pack_codes but write in a given range of the output,
  * leaving the rest untouched. Assumes allocated entries are 0 on input.
@@ -54,6 +57,8 @@ void pq4_pack_codes(
  * @param i0      first output code to write
  * @param i1      last output code to write
  * @param blocks  output array, size at least ceil(i1 / bbs) * bbs * nsq / 2
+ * @param code_stride  optional stride between consecutive codes (0 = use
+ * default (M + 1) / 2)
  */
 void pq4_pack_codes_range(
         const uint8_t* codes,
@@ -62,7 +67,8 @@ void pq4_pack_codes_range(
         size_t i1,
         size_t bbs,
         size_t nsq,
-        uint8_t* blocks);
+        uint8_t* blocks,
+        size_t code_stride = 0);
 
 /** get a single element from a packed codes table
  *
@@ -104,7 +110,7 @@ struct CodePackerPQ4 : CodePacker {
 /** Pack Look-up table for consumption by the kernel.
  *
  * @param nq      number of queries
- * @param nsq     number of sub-quantizers (muliple of 2)
+ * @param nsq     number of sub-quantizers (multiple of 2)
  * @param src     input array, size (nq, 16)
  * @param dest    output array, size (nq, 16)
  */
@@ -115,7 +121,7 @@ void pq4_pack_LUT(int nq, int nsq, const uint8_t* src, uint8_t* dest);
  * @param nq      number of queries
  * @param nb      number of database elements
  * @param bbs     size of database blocks (multiple of 32)
- * @param nsq     number of sub-quantizers (muliple of 2)
+ * @param nsq     number of sub-quantizers (multiple of 2)
  * @param codes   packed codes array
  * @param LUT     packed look-up table
  * @param scaler  scaler to scale the encoded norm
@@ -154,7 +160,7 @@ int pq4_preferred_qbs(int nq);
  *
  * @param qbs     4-bit encoded number of query blocks, the total number of
  *                queries handled (nq) is deduced from it
- * @param nsq     number of sub-quantizers (muliple of 2)
+ * @param nsq     number of sub-quantizers (multiple of 2)
  * @param src     input array, size (nq, 16)
  * @param dest    output array, size (nq, 16)
  * @return nq
@@ -173,11 +179,11 @@ int pq4_pack_LUT_qbs_q_map(
 /** Run accumulation loop.
  *
  * @param qbs     4-bit encoded number of queries
- * @param nb      number of database codes (mutliple of bbs)
+ * @param nb      number of database codes (multiple of bbs)
  * @param nsq     number of sub-quantizers
  * @param codes   encoded database vectors (packed)
  * @param LUT     look-up table (packed)
- * @param res     call-back for the resutls
+ * @param res     call-back for the results
  * @param scaler  scaler to scale the encoded norm
  */
 void pq4_accumulate_loop_qbs(