Faiss

- Main Page
- Namespaces
- Classes
- Files

- File List

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends
Index_c.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_C_H
13 #define FAISS_INDEX_C_H
14
15 #include <stdio.h>
16 #include "faiss_c.h"
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 // forward declaration required here
23 FAISS_DECLARE_CLASS(RangeSearchResult)
24
25 //typedef struct FaissRangeSearchResult_H FaissRangeSearchResult;
26 typedef struct FaissIDSelector_H FaissIDSelector;
27
28 /// Some algorithms support both an inner product version and a L2 search version.
29 typedef enum FaissMetricType {
30 METRIC_INNER_PRODUCT = 0,
31 METRIC_L2 = 1,
32 } FaissMetricType;
33
34 /// Opaque type for referencing to an index object
35 FAISS_DECLARE_CLASS(Index)
36 FAISS_DECLARE_DESTRUCTOR(Index)
37
38 /// Getter for d
39 FAISS_DECLARE_GETTER(Index, int, d)
40
41 /// Getter for is_trained
42 FAISS_DECLARE_GETTER(Index, int, is_trained)
43
44 /// Getter for ntotal
45 FAISS_DECLARE_GETTER(Index, idx_t, ntotal)
46
47 /// Getter for metric_type
48 FAISS_DECLARE_GETTER(Index, FaissMetricType, metric_type)
49
50 /** Perform training on a representative set of vectors
51 *
52 * @param index opaque pointer to index object
53 * @param n nb of training vectors
54 * @param x training vecors, size n * d
55 */
56 int faiss_Index_train(FaissIndex* index, idx_t n, const float* x);
57
58 /** Add n vectors of dimension d to the index.
59 *
60 * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1
61 * This function slices the input vectors in chuncks smaller than
62 * blocksize_add and calls add_core.
63 * @param index opaque pointer to index object
64 * @param x input matrix, size n * d
65 */
66 int faiss_Index_add(FaissIndex* index, idx_t n, const float* x);
67
68 /** Same as add, but stores xids instead of sequential ids.
69 *
70 * The default implementation fails with an assertion, as it is
71 * not supported by all indexes.
72 *
73 * @param index opaque pointer to index object
74 * @param xids if non-null, ids to store for the vectors (size n)
75 */
76 int faiss_Index_add_with_ids(FaissIndex* index, idx_t n, const float* x, const long* xids);
77
78 /** query n vectors of dimension d to the index.
79 *
80 * return at most k vectors. If there are not enough results for a
81 * query, the result array is padded with -1s.
82 *
83 * @param index opaque pointer to index object
84 * @param x input vectors to search, size n * d
85 * @param labels output labels of the NNs, size n*k
86 * @param distances output pairwise distances, size n*k
87 */
88 int faiss_Index_search(const FaissIndex* index, idx_t n, const float* x, idx_t k,
89 float* distances, idx_t* labels);
90
91 /** query n vectors of dimension d to the index.
92 *
93 * return all vectors with distance < radius. Note that many
94 * indexes do not implement the range_search (only the k-NN search
95 * is mandatory).
96 *
97 * @param index opaque pointer to index object
98 * @param x input vectors to search, size n * d
99 * @param radius search radius
100 * @param result result table
101 */
102 int faiss_Index_range_search(const FaissIndex* index, idx_t n, const float* x,
103 float radius, FaissRangeSearchResult* result);
104
105 /** return the indexes of the k vectors closest to the query x.
106 *
107 * This function is identical as search but only return labels of neighbors.
108 * @param index opaque pointer to index object
109 * @param x input vectors to search, size n * d
110 * @param labels output labels of the NNs, size n*k
111 */
112 int faiss_Index_assign(FaissIndex* index, idx_t n, const float * x, idx_t * labels, idx_t k);
113
114 /** removes all elements from the database.
115 * @param index opaque pointer to index object
116 */
117 int faiss_Index_reset(FaissIndex* index);
118
119 /** removes IDs from the index. Not supported by all indexes
120 * @param index opaque pointer to index object
121 * @param nremove output for the number of IDs removed
122 */
123 int faiss_Index_remove_ids(FaissIndex* index, const FaissIDSelector* sel, long* n_removed);
124
125 /** Reconstruct a stored vector (or an approximation if lossy coding)
126 *
127 * this function may not be defined for some indexes
128 * @param index opaque pointer to index object
129 * @param key id of the vector to reconstruct
130 * @param recons reconstucted vector (size d)
131 */
132 int faiss_Index_reconstruct(const FaissIndex* index, idx_t key, float* recons);
133
134 /** Reconstruct vectors i0 to i0 + ni - 1
135 *
136 * this function may not be defined for some indexes
137 * @param index opaque pointer to index object
138 * @param recons reconstucted vector (size ni * d)
139 */
140 int faiss_Index_reconstruct_n (const FaissIndex* index, idx_t i0, idx_t ni, float* recons);
141
142 /** Computes a residual vector after indexing encoding.
143 *
144 * The residual vector is the difference between a vector and the
145 * reconstruction that can be decoded from its representation in
146 * the index. The residual can be used for multiple-stage indexing
147 * methods, like IndexIVF's methods.
148 *
149 * @param index opaque pointer to index object
150 * @param x input vector, size d
151 * @param residual output residual vector, size d
152 * @param key encoded index, as returned by search and assign
153 */
154 int faiss_Index_compute_residual(const FaissIndex* index, const float* x, float* residual, idx_t key);
155
156 /** Display the actual class name and some more info
157 * @param index opaque pointer to index object
158 */
159 int faiss_Index_display(const FaissIndex* index);
160
161 #ifdef __cplusplus
162 }
163 #endif
164
165 #endif