Faiss

- Main Page
- Namespaces
- Classes
- Files

- File List

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends
/data/users/matthijs/github_faiss/faiss/IndexIVFPQ.h
1 /**
2 * Copyright (c) 2015-present, Facebook, Inc.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD+Patents license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9 // Copyright 2004-present Facebook. All Rights Reserved.
10 // -*- c++ -*-
11
12 #ifndef FAISS_INDEX_IVFPQ_H
13 #define FAISS_INDEX_IVFPQ_H
14
15
16 #include <vector>
17
18 #include "IndexIVF.h"
19 #include "IndexPQ.h"
20
21
22 namespace faiss {
23
24
25
26 /** Inverted file with Product Quantizer encoding. Each residual
27 * vector is encoded as a product quantizer code.
28 */
29 struct IndexIVFPQ: IndexIVF {
30 bool by_residual; ///< Encode residual or plain vector?
31 int use_precomputed_table; ///< if by_residual, build precompute tables
32 ProductQuantizer pq; ///< produces the codes
33
34 bool do_polysemous_training; ///< reorder PQ centroids after training?
35 PolysemousTraining *polysemous_training; ///< if NULL, use default
36
37 // search-time parameters
38 size_t scan_table_threshold; ///< use table computation or on-the-fly?
39 size_t max_codes; ///< max nb of codes to visit to do a query
40 int polysemous_ht; ///< Hamming thresh for polysemous filtering
41
42
43 /// if use_precompute_table
44 /// size nlist * pq.M * pq.ksub
45 std::vector <float> precomputed_table;
46
47 IndexIVFPQ (
48 Index * quantizer, size_t d, size_t nlist,
49 size_t M, size_t nbits_per_idx);
50
51 void add_with_ids(idx_t n, const float* x, const long* xids = nullptr)
52 override;
53
54 /// same as add_core, also:
55 /// - output 2nd level residuals if residuals_2 != NULL
56 /// - use precomputed list numbers if precomputed_idx != NULL
57 void add_core_o (idx_t n, const float *x,
58 const long *xids, float *residuals_2,
59 const long *precomputed_idx = nullptr);
60
61 /// trains the product quantizer
62 void train_residual(idx_t n, const float* x) override;
63
64 /// same as train_residual, also output 2nd level residuals
65 void train_residual_o (idx_t n, const float *x, float *residuals_2);
66
67
68 /** Reconstruct a subset of the indexed vectors
69 *
70 * @param i0 first vector to reconstruct
71 * @param ni nb of vectors to reconstruct
72 * @param recons output array of reconstructed vectors, size ni * d
73 */
74 void reconstruct_n(idx_t i0, idx_t ni, float* recons) const override;
75
76 void reconstruct(idx_t key, float* recons) const override;
77
78 /** Find exact duplicates in the dataset.
79 *
80 * the duplicates are returned in pre-allocated arrays (see the
81 * max sizes).
82 *
83 * @params lims limits between groups of duplicates
84 * (max size ntotal / 2 + 1)
85 * @params ids ids[lims[i]] : ids[lims[i+1]-1] is a group of
86 * duplicates (max size ntotal)
87 * @return n number of groups found
88 */
89 size_t find_duplicates (idx_t *ids, size_t *lims) const;
90
91 // map a vector to a binary code knowning the index
92 void encode (long key, const float * x, uint8_t * code) const;
93
94 /** Encode multiple vectors
95 *
96 * @param n nb vectors to encode
97 * @param keys posting list ids for those vectors (size n)
98 * @param x vectors (size n * d)
99 * @param codes output codes (size n * code_size)
100 * @param compute_keys if false, assume keys are precomputed,
101 * otherwise compute them
102 */
103 void encode_multiple (size_t n, long *keys,
104 const float * x, uint8_t * codes,
105 bool compute_keys = false) const;
106
107 /// inverse of encode_multiple
108 void decode_multiple (size_t n, const long *keys,
109 const uint8_t * xcodes, float * x) const;
110
111 void search_preassigned (idx_t n, const float *x, idx_t k,
112 const idx_t *assign,
113 const float *centroid_dis,
114 float *distances, idx_t *labels,
115 bool store_pairs) const override;
116
117 /** Same as the search function, but also reconstruct approximate
118 * vectors for the search results
119 *
120 * @param reconstructed size (n, k, d)
121 **/
122 void search_and_reconstruct (idx_t n, const float *x, idx_t k,
123 float *distances, idx_t *labels,
124 float *reconstructed);
125
126
127 /// build precomputed table
128 void precompute_table ();
129
130 IndexIVFPQ ();
131
132 };
133
134
135 /// statistics are robust to internal threading, but not if
136 /// IndexIVFPQ::search_preassigned is called by multiple threads
137 struct IndexIVFPQStats {
138 size_t nq; // nb of queries run
139 size_t nlist; // nb of inverted lists scanned
140 size_t ncode; // nb of codes visited
141 size_t nrefine; // nb of refines (IVFPQR)
142
143 size_t n_hamming_pass;
144 // nb of passed Hamming distance tests (for polysemous)
145
146 // timings measured with the CPU RTC
147 // on all threads
148 size_t assign_cycles;
149 size_t search_cycles;
150 size_t refine_cycles; // only for IVFPQR
151
152 // single thread (double-counted with search_cycles)
153 size_t init_query_cycles;
154 size_t init_list_cycles;
155 size_t scan_cycles;
156 size_t heap_cycles;
157
158 IndexIVFPQStats () {reset (); }
159 void reset ();
160 };
161
162 // global var that collects them all
163 extern IndexIVFPQStats indexIVFPQ_stats;
164
165
166
167 /** Index with an additional level of PQ refinement */
168 struct IndexIVFPQR: IndexIVFPQ {
169 ProductQuantizer refine_pq; ///< 3rd level quantizer
170 std::vector <uint8_t> refine_codes; ///< corresponding codes
171
172 /// factor between k requested in search and the k requested from the IVFPQ
173 float k_factor;
174
175 IndexIVFPQR (
176 Index * quantizer, size_t d, size_t nlist,
177 size_t M, size_t nbits_per_idx,
178 size_t M_refine, size_t nbits_per_idx_refine);
179
180 void reset() override;
181
182 long remove_ids(const IDSelector& sel) override;
183
184 /// trains the two product quantizers
185 void train_residual(idx_t n, const float* x) override;
186
187 void add_with_ids(idx_t n, const float* x, const long* xids) override;
188
189 /// same as add_with_ids, but optionally use the precomputed list ids
190 void add_core (idx_t n, const float *x, const long *xids,
191 const long *precomputed_idx = nullptr);
192
193 void reconstruct_n(idx_t i0, idx_t ni, float* recons) const override;
194
195 void merge_from (IndexIVF &other, idx_t add_id) override;
196
197
198 void search(
199 idx_t n,
200 const float* x,
201 idx_t k,
202 float* distances,
203 idx_t* labels) const override;
204
205 IndexIVFPQR();
206 };
207
208
209 /** Index with 32-bit ids and flat tables. Must be constructed from an
210 * exisiting IndexIVFPQ. Cannot be copy-constructed/assigned. The
211 * actual data is stored in the compact_* tables, the ids and codes
212 * tables are not used. */
213 struct IndexIVFPQCompact: IndexIVFPQ {
214
215 explicit IndexIVFPQCompact (const IndexIVFPQ &other);
216
217 /// how were the compact tables allocated?
218 enum Alloc_type_t {
219 Alloc_type_none, ///< alloc from outside
220 Alloc_type_new, ///< was allocated with new
221 Alloc_type_mmap ///< was mmapped
222 };
223
224 Alloc_type_t alloc_type;
225
226 uint32_t *limits; ///< size nlist + 1
227 uint32_t *compact_ids; ///< size ntotal
228 uint8_t *compact_codes; ///< size ntotal * code_size
229
230 // file and buffer this was mmapped (will be unmapped when object
231 // is deleted)
232 char * mmap_buffer;
233 long mmap_length;
234
235 void search_preassigned (idx_t n, const float *x, idx_t k,
236 const idx_t *assign,
237 const float *centroid_dis,
238 float *distances, idx_t *labels,
239 bool store_pairs) const override;
240
241 /// the three following functions will fail at runtime
242 void add(idx_t, const float*) override;
243 void reset() override;
244 void train(idx_t, const float*) override;
245
246 ~IndexIVFPQCompact() override;
247
248 IndexIVFPQCompact ();
249
250 };
251
252
253
254 } // namespace faiss
255
256
257
258
259
260 #endif
faiss::IndexIVFPQCompact::compact_ids
uint32_t * compact_ids
size ntotal
Definition: IndexIVFPQ.h:227
faiss::IndexIVF
Definition: IndexIVF.h:45
faiss::IndexIVFPQCompact::compact_codes
uint8_t * compact_codes
size ntotal * code_size
Definition: IndexIVFPQ.h:228
faiss::IndexIVFPQ::precompute_table
void precompute_table()
build precomputed table
Definition: IndexIVFPQ.cpp:356
faiss::IndexIVFPQR::merge_from
void merge_from(IndexIVF &other, idx_t add_id) override
Definition: IndexIVFPQ.cpp:1320
faiss::IndexIVFPQ::reconstruct
void reconstruct(idx_t key, float *recons) const override
Definition: IndexIVFPQ.cpp:302
faiss::IndexIVFPQR
Definition: IndexIVFPQ.h:168
faiss::IndexIVFPQR::refine_pq
ProductQuantizer refine_pq
3rd level quantizer
Definition: IndexIVFPQ.h:169
faiss::IndexIVFPQ::polysemous_training
PolysemousTraining * polysemous_training
if NULL, use default
Definition: IndexIVFPQ.h:35
faiss::IndexIVFPQCompact::add
void add(idx_t, const float *) override
the three following functions will fail at runtime
Definition: IndexIVFPQ.cpp:1416
faiss::IndexIVFPQStats
Definition: IndexIVFPQ.h:137
faiss::IndexIVFPQR::reconstruct_n
void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override
Definition: IndexIVFPQ.cpp:1301
faiss::IndexIVFPQCompact::search_preassigned
void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs) const override
Definition: IndexIVFPQ.cpp:1446
faiss::Index::assign
void assign(idx_t n, const float *x, idx_t *labels, idx_t k=1)
Definition: Index.cpp:23
faiss::IDSelector
Definition: AuxIndexStructures.h:52
faiss::IndexIVFPQCompact::Alloc_type_mmap
was mmapped
Definition: IndexIVFPQ.h:221
faiss::IndexIVFPQ::decode_multiple
void decode_multiple(size_t n, const long *keys, const uint8_t *xcodes, float *x) const
inverse of encode_multiple
Definition: IndexIVFPQ.cpp:169
faiss::IndexIVFPQ::train_residual_o
void train_residual_o(idx_t n, const float *x, float *residuals_2)
same as train_residual, also output 2nd level residuals
Definition: IndexIVFPQ.cpp:71
faiss::IndexIVFPQ::do_polysemous_training
bool do_polysemous_training
reorder PQ centroids after training?
Definition: IndexIVFPQ.h:34
faiss::IndexIVFPQ::scan_table_threshold
size_t scan_table_threshold
use table computation or on-the-fly?
Definition: IndexIVFPQ.h:38
faiss::IndexIVFPQR::train_residual
void train_residual(idx_t n, const float *x) override
trains the two product quantizers
Definition: IndexIVFPQ.cpp:1169
faiss::IndexIVFPQR::add_core
void add_core(idx_t n, const float *x, const long *xids, const long *precomputed_idx=nullptr)
same as add_with_ids, but optionally use the precomputed list ids
Definition: IndexIVFPQ.cpp:1193
faiss::IndexIVFPQCompact::limits
uint32_t * limits
size nlist + 1
Definition: IndexIVFPQ.h:226
faiss::IndexIVFPQ::precomputed_table
std::vector< float > precomputed_table
Definition: IndexIVFPQ.h:45
faiss::IndexIVFPQ::polysemous_ht
int polysemous_ht
Hamming thresh for polysemous filtering.
Definition: IndexIVFPQ.h:40
faiss::IndexIVFPQR::reset
void reset() override
removes all elements from the database.
Definition: IndexIVFPQ.cpp:1160
faiss::IndexIVFPQ::add_with_ids
void add_with_ids(idx_t n, const float *x, const long *xids=nullptr) override
Definition: IndexIVFPQ.cpp:186
faiss::IndexIVFPQCompact
Definition: IndexIVFPQ.h:213
faiss::IndexIVF::ids
std::vector< std::vector< long > > ids
Inverted lists for indexes.
Definition: IndexIVF.h:62
faiss::Index::d
int d
vector dimension
Definition: Index.h:64
faiss::IndexIVF::quantizer
Index * quantizer
quantizer that maps vectors to inverted lists
Definition: IndexIVF.h:49
faiss::IndexIVFPQ::max_codes
size_t max_codes
max nb of codes to visit to do a query
Definition: IndexIVFPQ.h:39
faiss::IndexIVFPQCompact::Alloc_type_t
Alloc_type_t
how were the compact tables allocated?
Definition: IndexIVFPQ.h:218
faiss::IndexIVFPQR::refine_codes
std::vector< uint8_t > refine_codes
corresponding codes
Definition: IndexIVFPQ.h:170
faiss::IndexIVFPQ::train_residual
void train_residual(idx_t n, const float *x) override
trains the product quantizer
Definition: IndexIVFPQ.cpp:65
faiss::IndexIVFPQ
Definition: IndexIVFPQ.h:29
faiss::IndexIVFPQ::encode_multiple
void encode_multiple(size_t n, long *keys, const float *x, uint8_t *codes, bool compute_keys=false) const
Definition: IndexIVFPQ.cpp:150
faiss::IndexIVFPQCompact::train
void train(idx_t, const float *) override
Trains the quantizer and calls train_residual to train sub-quantizers.
Definition: IndexIVFPQ.cpp:1424
faiss::Index::idx_t
long idx_t
all indices are this type
Definition: Index.h:62
faiss::PolysemousTraining
optimizes the order of indices in a ProductQuantizer
Definition: PolysemousTraining.h:125
faiss::IndexIVFPQ::by_residual
bool by_residual
Encode residual or plain vector?
Definition: IndexIVFPQ.h:30
faiss::IndexIVFPQCompact::Alloc_type_none
alloc from outside
Definition: IndexIVFPQ.h:219
faiss::IndexIVFPQ::search_and_reconstruct
void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *reconstructed)
Definition: IndexIVFPQ.cpp:1032
faiss::IndexIVFPQ::pq
ProductQuantizer pq
produces the codes
Definition: IndexIVFPQ.h:32
faiss::IndexIVF::nlist
size_t nlist
number of possible key values
Definition: IndexIVF.h:46
faiss::Index
Definition: Index.h:60
faiss::IndexIVFPQ::reconstruct_n
void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override
Definition: IndexIVFPQ.cpp:274
faiss::IndexIVFPQ::add_core_o
void add_core_o(idx_t n, const float *x, const long *xids, float *residuals_2, const long *precomputed_idx=nullptr)
Definition: IndexIVFPQ.cpp:192
faiss::IndexIVFPQR::remove_ids
long remove_ids(const IDSelector &sel) override
Dataset manipulation functions.
Definition: IndexIVFPQ.cpp:1333
faiss::IndexIVFPQ::search_preassigned
void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs) const override
Definition: IndexIVFPQ.cpp:931
faiss::ProductQuantizer
Definition: ProductQuantizer.h:25
faiss::IndexIVFPQCompact::reset
void reset() override
removes all elements from the database.
Definition: IndexIVFPQ.cpp:1420
faiss::IndexIVFPQCompact::Alloc_type_new
was allocated with new
Definition: IndexIVFPQ.h:220
faiss::IndexIVFPQR::add_with_ids
void add_with_ids(idx_t n, const float *x, const long *xids) override
Definition: IndexIVFPQ.cpp:1189
faiss::IndexIVFPQR::search
void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels) const override
Definition: IndexIVFPQ.cpp:1212
faiss::IndexIVFPQ::find_duplicates
size_t find_duplicates(idx_t *ids, size_t *lims) const
Definition: IndexIVFPQ.cpp:1104
faiss::IndexIVFPQR::k_factor
float k_factor
factor between k requested in search and the k requested from the IVFPQ
Definition: IndexIVFPQ.h:173
faiss::IndexIVFPQ::use_precomputed_table
int use_precomputed_table
if by_residual, build precompute tables
Definition: IndexIVFPQ.h:31