Debian Codegraph @

c_api/Index_c.h

raw
1 /*
2 * Copyright (c) Meta Platforms, Inc. and 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_C_H
11 #define FAISS_INDEX_C_H
12
13 #include <stddef.h>
14 #include "faiss_c.h"
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 // forward declaration required here
21 FAISS_DECLARE_CLASS(RangeSearchResult)
22
23 // typedef struct FaissRangeSearchResult_H FaissRangeSearchResult;
24 typedef struct FaissIDSelector_H FaissIDSelector;
25
26 /// Some algorithms support both an inner product version and a L2 search
27 /// version.
28 typedef enum FaissMetricType {
29 METRIC_INNER_PRODUCT = 0, ///< maximum inner product search
30 METRIC_L2 = 1, ///< squared L2 search
31 METRIC_L1, ///< L1 (aka cityblock)
32 METRIC_Linf, ///< infinity distance
33 METRIC_Lp, ///< L_p distance, p is given by metric_arg
34
35 /// some additional metrics defined in scipy.spatial.distance
36 METRIC_Canberra = 20,
37 METRIC_BrayCurtis,
38 METRIC_JensenShannon,
39 } FaissMetricType;
40
41 FAISS_DECLARE_CLASS(SearchParameters)
42 FAISS_DECLARE_DESTRUCTOR(SearchParameters)
43
44 int faiss_SearchParameters_new(
45 FaissSearchParameters** p_sp,
46 FaissIDSelector* sel);
47
48 /// Opaque type for referencing to an index object
49 FAISS_DECLARE_CLASS(Index)
50 FAISS_DECLARE_DESTRUCTOR(Index)
51
52 /// Getter for d
53 FAISS_DECLARE_GETTER(Index, int, d)
54
55 /// Getter for is_trained
56 FAISS_DECLARE_GETTER(Index, int, is_trained)
57
58 /// Getter for ntotal
59 FAISS_DECLARE_GETTER(Index, idx_t, ntotal)
60
61 /// Getter for metric_type
62 FAISS_DECLARE_GETTER(Index, FaissMetricType, metric_type)
63
64 FAISS_DECLARE_GETTER_SETTER(Index, int, verbose)
65
66 /** Perform training on a representative set of vectors
67 *
68 * @param index opaque pointer to index object
69 * @param n nb of training vectors
70 * @param x training vectors, size n * d
71 */
72 int faiss_Index_train(FaissIndex* index, idx_t n, const float* x);
73
74 /** Add n vectors of dimension d to the index.
75 *
76 * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1
77 * This function slices the input vectors in chunks smaller than
78 * blocksize_add and calls add_core.
79 * @param index opaque pointer to index object
80 * @param x input matrix, size n * d
81 */
82 int faiss_Index_add(FaissIndex* index, idx_t n, const float* x);
83
84 /** Same as add, but stores xids instead of sequential ids.
85 *
86 * The default implementation fails with an assertion, as it is
87 * not supported by all indexes.
88 *
89 * @param index opaque pointer to index object
90 * @param xids if non-null, ids to store for the vectors (size n)
91 */
92 int faiss_Index_add_with_ids(
93 FaissIndex* index,
94 idx_t n,
95 const float* x,
96 const idx_t* xids);
97
98 /** query n vectors of dimension d to the index.
99 *
100 * return at most k vectors. If there are not enough results for a
101 * query, the result array is padded with -1s.
102 *
103 * @param index opaque pointer to index object
104 * @param x input vectors to search, size n * d
105 * @param labels output labels of the NNs, size n*k
106 * @param distances output pairwise distances, size n*k
107 */
108 int faiss_Index_search(
109 const FaissIndex* index,
110 idx_t n,
111 const float* x,
112 idx_t k,
113 float* distances,
114 idx_t* labels);
115
116 /**
117 * query n vectors of dimension d with search parameters to the index.
118 *
119 * return at most k vectors. If there are not enough results for a query,
120 * the result is padded with -1s.
121 *
122 * @param index opaque pointer to index object
123 * @param x input vectors to search, size n * d
124 * @param params input params to modify how search is done
125 * @param labels output labels of the NNs, size n*k
126 * @param distances output pairwise distances, size n*k
127 */
128 int faiss_Index_search_with_params(
129 const FaissIndex* index,
130 idx_t n,
131 const float* x,
132 idx_t k,
133 const FaissSearchParameters* params,
134 float* distances,
135 idx_t* labels);
136
137 /** query n vectors of dimension d to the index.
138 *
139 * return all vectors with distance < radius. Note that many
140 * indexes do not implement the range_search (only the k-NN search
141 * is mandatory).
142 *
143 * @param index opaque pointer to index object
144 * @param x input vectors to search, size n * d
145 * @param radius search radius
146 * @param result result table
147 */
148 int faiss_Index_range_search(
149 const FaissIndex* index,
150 idx_t n,
151 const float* x,
152 float radius,
153 FaissRangeSearchResult* result);
154
155 /** return the indexes of the k vectors closest to the query x.
156 *
157 * This function is identical as search but only return labels of neighbors.
158 * @param index opaque pointer to index object
159 * @param x input vectors to search, size n * d
160 * @param labels output labels of the NNs, size n*k
161 */
162 int faiss_Index_assign(
163 FaissIndex* index,
164 idx_t n,
165 const float* x,
166 idx_t* labels,
167 idx_t k);
168
169 /** removes all elements from the database.
170 * @param index opaque pointer to index object
171 */
172 int faiss_Index_reset(FaissIndex* index);
173
174 /** removes IDs from the index. Not supported by all indexes
175 * @param index opaque pointer to index object
176 * @param nremove output for the number of IDs removed
177 */
178 int faiss_Index_remove_ids(
179 FaissIndex* index,
180 const FaissIDSelector* sel,
181 size_t* n_removed);
182
183 /** Reconstruct a stored vector (or an approximation if lossy coding)
184 *
185 * this function may not be defined for some indexes
186 * @param index opaque pointer to index object
187 * @param key id of the vector to reconstruct
188 * @param recons reconstructed vector (size d)
189 */
190 int faiss_Index_reconstruct(const FaissIndex* index, idx_t key, float* recons);
191
192 /** Reconstruct vectors i0 to i0 + ni - 1
193 *
194 * this function may not be defined for some indexes
195 * @param index opaque pointer to index object
196 * @param recons reconstructed vector (size ni * d)
197 */
198 int faiss_Index_reconstruct_n(
199 const FaissIndex* index,
200 idx_t i0,
201 idx_t ni,
202 float* recons);
203
204 /** Computes a residual vector after indexing encoding.
205 *
206 * The residual vector is the difference between a vector and the
207 * reconstruction that can be decoded from its representation in
208 * the index. The residual can be used for multiple-stage indexing
209 * methods, like IndexIVF's methods.
210 *
211 * @param index opaque pointer to index object
212 * @param x input vector, size d
213 * @param residual output residual vector, size d
214 * @param key encoded index, as returned by search and assign
215 */
216 int faiss_Index_compute_residual(
217 const FaissIndex* index,
218 const float* x,
219 float* residual,
220 idx_t key);
221
222 /** Computes a residual vector after indexing encoding.
223 *
224 * The residual vector is the difference between a vector and the
225 * reconstruction that can be decoded from its representation in
226 * the index. The residual can be used for multiple-stage indexing
227 * methods, like IndexIVF's methods.
228 *
229 * @param index opaque pointer to index object
230 * @param n number of vectors
231 * @param x input vector, size (n x d)
232 * @param residuals output residual vectors, size (n x d)
233 * @param keys encoded index, as returned by search and assign
234 */
235 int faiss_Index_compute_residual_n(
236 const FaissIndex* index,
237 idx_t n,
238 const float* x,
239 float* residuals,
240 const idx_t* keys);
241
242 /* The standalone codec interface */
243
244 /** The size of the produced codes in bytes.
245 *
246 * @param index opaque pointer to index object
247 * @param size the returned size in bytes
248 */
249 int faiss_Index_sa_code_size(const FaissIndex* index, size_t* size);
250
251 /** encode a set of vectors
252 *
253 * @param index opaque pointer to index object
254 * @param n number of vectors
255 * @param x input vectors, size n * d
256 * @param bytes output encoded vectors, size n * sa_code_size()
257 */
258 int faiss_Index_sa_encode(
259 const FaissIndex* index,
260 idx_t n,
261 const float* x,
262 uint8_t* bytes);
263
264 /** decode a set of vectors
265 *
266 * @param index opaque pointer to index object
267 * @param n number of vectors
268 * @param bytes input encoded vectors, size n * sa_code_size()
269 * @param x output vectors, size n * d
270 */
271 int faiss_Index_sa_decode(
272 const FaissIndex* index,
273 idx_t n,
274 const uint8_t* bytes,
275 float* x);
276
277 #ifdef __cplusplus
278 }
279 #endif
280
281 #endif