Faiss

- Main Page
- Namespaces
- Classes
- Files

- File List

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends
/data/users/hoss/faiss/IndexBinary.h
1 /**
2 * Copyright (c) Facebook, Inc. and its affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 */
7
8 // -*- c++ -*-
9
10 #ifndef FAISS_INDEX_BINARY_H
11 #define FAISS_INDEX_BINARY_H
12
13 #include <cstdio>
14 #include <typeinfo>
15 #include <string>
16 #include <sstream>
17
18 #include "FaissAssert.h"
19 #include "Index.h"
20
21
22 namespace faiss {
23
24
25 /// Forward declarations see AuxIndexStructures.h
26 struct IDSelector;
27 struct RangeSearchResult;
28
29 /** Abstract structure for a binary index.
30 *
31 * Supports adding vertices and searching them.
32 *
33 * All queries are symmetric because there is no distinction between codes and
34 * vectors.
35 */
36 struct IndexBinary {
37 using idx_t = Index::idx_t; ///< all indices are this type
38 using component_t = uint8_t;
39 using distance_t = int32_t;
40
41 int d; ///< vector dimension
42 int code_size; ///< number of bytes per vector ( = d / 8 )
43 idx_t ntotal; ///< total nb of indexed vectors
44 bool verbose; ///< verbosity level
45
46 /// set if the Index does not require training, or if training is done already
47 bool is_trained;
48
49 /// type of metric this index uses for search
50 MetricType metric_type;
51
52 explicit IndexBinary(idx_t d = 0, MetricType metric = METRIC_L2)
53 : d(d),
54 code_size(d / 8),
55 ntotal(0),
56 verbose(false),
57 is_trained(true),
58 metric_type(metric) {
59 FAISS_THROW_IF_NOT(d % 8 == 0);
60 }
61
62 virtual ~IndexBinary();
63
64
65 /** Perform training on a representative set of vectors.
66 *
67 * @param n nb of training vectors
68 * @param x training vecors, size n * d / 8
69 */
70 virtual void train(idx_t n, const uint8_t *x);
71
72 /** Add n vectors of dimension d to the index.
73 *
74 * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1
75 * @param x input matrix, size n * d / 8
76 */
77 virtual void add(idx_t n, const uint8_t *x) = 0;
78
79 /** Same as add, but stores xids instead of sequential ids.
80 *
81 * The default implementation fails with an assertion, as it is
82 * not supported by all indexes.
83 *
84 * @param xids if non-null, ids to store for the vectors (size n)
85 */
86 virtual void add_with_ids(idx_t n, const uint8_t *x, const long *xids);
87
88 /** Query n vectors of dimension d to the index.
89 *
90 * return at most k vectors. If there are not enough results for a
91 * query, the result array is padded with -1s.
92 *
93 * @param x input vectors to search, size n * d / 8
94 * @param labels output labels of the NNs, size n*k
95 * @param distances output pairwise distances, size n*k
96 */
97 virtual void search(idx_t n, const uint8_t *x, idx_t k,
98 int32_t *distances, idx_t *labels) const = 0;
99
100 /** Query n vectors of dimension d to the index.
101 *
102 * return all vectors with distance < radius. Note that many
103 * indexes do not implement the range_search (only the k-NN search
104 * is mandatory).
105 *
106 * @param x input vectors to search, size n * d / 8
107 * @param radius search radius
108 * @param result result table
109 */
110 virtual void range_search(idx_t n, const uint8_t *x, int radius,
111 RangeSearchResult *result) const;
112
113 /** Return the indexes of the k vectors closest to the query x.
114 *
115 * This function is identical to search but only returns labels of neighbors.
116 * @param x input vectors to search, size n * d / 8
117 * @param labels output labels of the NNs, size n*k
118 */
119 void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1);
120
121 /// Removes all elements from the database.
122 virtual void reset() = 0;
123
124 /** Removes IDs from the index. Not supported by all indexes.
125 */
126 virtual long remove_ids(const IDSelector& sel);
127
128 /** Reconstruct a stored vector.
129 *
130 * This function may not be defined for some indexes.
131 * @param key id of the vector to reconstruct
132 * @param recons reconstucted vector (size d / 8)
133 */
134 virtual void reconstruct(idx_t key, uint8_t *recons) const;
135
136
137 /** Reconstruct vectors i0 to i0 + ni - 1.
138 *
139 * This function may not be defined for some indexes.
140 * @param recons reconstucted vectors (size ni * d / 8)
141 */
142 virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const;
143
144 /** Similar to search, but also reconstructs the stored vectors (or an
145 * approximation in the case of lossy coding) for the search results.
146 *
147 * If there are not enough results for a query, the resulting array
148 * is padded with -1s.
149 *
150 * @param recons reconstructed vectors size (n, k, d)
151 **/
152 virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k,
153 int32_t *distances, idx_t *labels,
154 uint8_t *recons) const;
155
156 /** Display the actual class name and some more info. */
157 void display() const;
158 };
159
160
161 } // namespace faiss
162
163 #endif // FAISS_INDEX_BINARY_H
faiss::IndexBinary::search
virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels) const =0
faiss::IndexBinary::reset
virtual void reset()=0
Removes all elements from the database.
faiss::IDSelector
Definition: AuxIndexStructures.h:54
faiss::IndexBinary::verbose
bool verbose
verbosity level
Definition: IndexBinary.h:44
faiss::IndexBinary::remove_ids
virtual long remove_ids(const IDSelector &sel)
Definition: IndexBinary.cpp:38
faiss::IndexBinary::is_trained
bool is_trained
set if the Index does not require training, or if training is done already
Definition: IndexBinary.h:47
faiss::IndexBinary::train
virtual void train(idx_t n, const uint8_t *x)
Definition: IndexBinary.cpp:19
faiss::IndexBinary::code_size
int code_size
number of bytes per vector ( = d / 8 )
Definition: IndexBinary.h:42
faiss::IndexBinary::idx_t
Index::idx_t idx_t
all indices are this type
Definition: IndexBinary.h:37
faiss::IndexBinary::d
int d
vector dimension
Definition: IndexBinary.h:41
faiss::IndexBinary::display
void display() const
Definition: IndexBinary.cpp:72
faiss::Index::idx_t
long idx_t
all indices are this type
Definition: Index.h:62
faiss::IndexBinary::reconstruct
virtual void reconstruct(idx_t key, uint8_t *recons) const
Definition: IndexBinary.cpp:43
faiss::IndexBinary::assign
void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k=1)
Definition: IndexBinary.cpp:28
faiss::IndexBinary::range_search
virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result) const
Definition: IndexBinary.cpp:23
faiss::IndexBinary::add_with_ids
virtual void add_with_ids(idx_t n, const uint8_t *x, const long *xids)
Definition: IndexBinary.cpp:34
faiss::IndexBinary::search_and_reconstruct
virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons) const
Definition: IndexBinary.cpp:53
faiss::IndexBinary::reconstruct_n
virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const
Definition: IndexBinary.cpp:47
faiss::RangeSearchResult
Definition: AuxIndexStructures.h:31
faiss::IndexBinary::ntotal
idx_t ntotal
total nb of indexed vectors
Definition: IndexBinary.h:43
faiss::IndexBinary
Definition: IndexBinary.h:36
faiss::IndexBinary::add
virtual void add(idx_t n, const uint8_t *x)=0
faiss::IndexBinary::metric_type
MetricType metric_type
type of metric this index uses for search
Definition: IndexBinary.h:50
faiss::MetricType
MetricType
Some algorithms support both an inner product version and a L2 search version.
Definition: Index.h:44