Debian Codegraph @

c_api/IndexBinary_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_BINARY_C_H
11 #define FAISS_INDEX_BINARY_C_H
12
13 #include <stddef.h>
14 #include "Index_c.h"
15 #include "faiss_c.h"
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 // forward declaration required here
22 FAISS_DECLARE_CLASS(RangeSearchResult)
23
24 // typedef struct FaissRangeSearchResult_H FaissRangeSearchResult;
25 typedef struct FaissIDSelector_H FaissIDSelector;
26
27 /// Opaque type for referencing to a binary index object
28 FAISS_DECLARE_CLASS(IndexBinary)
29 FAISS_DECLARE_DESTRUCTOR(IndexBinary)
30
31 /// Getter for d
32 FAISS_DECLARE_GETTER(IndexBinary, int, d)
33
34 /// Getter for is_trained
35 FAISS_DECLARE_GETTER(IndexBinary, int, is_trained)
36
37 /// Getter for ntotal
38 FAISS_DECLARE_GETTER(IndexBinary, idx_t, ntotal)
39
40 /// Getter for metric_type
41 FAISS_DECLARE_GETTER(IndexBinary, FaissMetricType, metric_type)
42
43 FAISS_DECLARE_GETTER_SETTER(IndexBinary, int, verbose)
44
45 /** Perform training on a representative set of vectors
46 *
47 * @param index opaque pointer to index object
48 * @param n nb of training vectors
49 * @param x training vectors, size n * d
50 */
51 int faiss_IndexBinary_train(FaissIndexBinary* index, idx_t n, const uint8_t* x);
52
53 /** Add n vectors of dimension d to the index.
54 *
55 * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1
56 * This function slices the input vectors in chunks smaller than
57 * blocksize_add and calls add_core.
58 * @param index opaque pointer to index object
59 * @param x input matrix, size n * d
60 */
61 int faiss_IndexBinary_add(FaissIndexBinary* index, idx_t n, const uint8_t* x);
62
63 /** Same as add, but stores xids instead of sequential ids.
64 *
65 * The default implementation fails with an assertion, as it is
66 * not supported by all indexes.
67 *
68 * @param index opaque pointer to index object
69 * @param xids if non-null, ids to store for the vectors (size n)
70 */
71 int faiss_IndexBinary_add_with_ids(
72 FaissIndexBinary* index,
73 idx_t n,
74 const uint8_t* x,
75 const idx_t* xids);
76
77 /** query n vectors of dimension d to the index.
78 *
79 * return at most k vectors. If there are not enough results for a
80 * query, the result array is padded with -1s.
81 *
82 * @param index opaque pointer to index object
83 * @param x input vectors to search, size n * d
84 * @param labels output labels of the NNs, size n*k
85 * @param distances output pairwise distances, size n*k
86 */
87 int faiss_IndexBinary_search(
88 const FaissIndexBinary* index,
89 idx_t n,
90 const uint8_t* x,
91 idx_t k,
92 int32_t* distances,
93 idx_t* labels);
94
95 /** query n vectors of dimension d to the index.
96 *
97 * return all vectors with distance < radius. Note that many
98 * indexes do not implement the range_search (only the k-NN search
99 * is mandatory).
100 *
101 * @param index opaque pointer to index object
102 * @param x input vectors to search, size n * d
103 * @param radius search radius
104 * @param result result table
105 */
106 int faiss_IndexBinary_range_search(
107 const FaissIndexBinary* index,
108 idx_t n,
109 const uint8_t* x,
110 int radius,
111 FaissRangeSearchResult* result);
112
113 /** return the indexes of the k vectors closest to the query x.
114 *
115 * This function is identical as search but only return labels of neighbors.
116 * @param index opaque pointer to index object
117 * @param x input vectors to search, size n * d
118 * @param labels output labels of the NNs, size n*k
119 */
120 int faiss_IndexBinary_assign(
121 FaissIndexBinary* index,
122 idx_t n,
123 const uint8_t* x,
124 idx_t* labels,
125 idx_t k);
126
127 /** removes all elements from the database.
128 * @param index opaque pointer to index object
129 */
130 int faiss_IndexBinary_reset(FaissIndexBinary* index);
131
132 /** removes IDs from the index. Not supported by all indexes
133 * @param index opaque pointer to index object
134 * @param nremove output for the number of IDs removed
135 */
136 int faiss_IndexBinary_remove_ids(
137 FaissIndexBinary* index,
138 const FaissIDSelector* sel,
139 size_t* n_removed);
140
141 /** Reconstruct a stored vector (or an approximation if lossy coding)
142 *
143 * this function may not be defined for some indexes
144 * @param index opaque pointer to index object
145 * @param key id of the vector to reconstruct
146 * @param recons reconstructed vector (size d)
147 */
148 int faiss_IndexBinary_reconstruct(
149 const FaissIndexBinary* index,
150 idx_t key,
151 uint8_t* recons);
152
153 /** Reconstruct vectors i0 to i0 + ni - 1
154 *
155 * this function may not be defined for some indexes
156 * @param index opaque pointer to index object
157 * @param recons reconstructed vector (size ni * d)
158 */
159 int faiss_IndexBinary_reconstruct_n(
160 const FaissIndexBinary* index,
161 idx_t i0,
162 idx_t ni,
163 uint8_t* recons);
164
165 #ifdef __cplusplus
166 }
167 #endif
168
169 #endif