Debian Codegraph @

c_api/Clustering_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_CLUSTERING_C_H
11 #define FAISS_CLUSTERING_C_H
12
13 #include "Index_c.h"
14 #include "faiss_c.h"
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 /** Class for the clustering parameters. Can be passed to the
21 * constructor of the Clustering object.
22 */
23 typedef struct FaissClusteringParameters {
24 int niter; ///< clustering iterations
25 int nredo; ///< redo clustering this many times and keep best
26
27 int verbose; ///< (bool)
28 int spherical; ///< (bool) do we want normalized centroids?
29 int int_centroids; ///< (bool) round centroids coordinates to integer
30 int update_index; ///< (bool) update index after each iteration?
31 int frozen_centroids; ///< (bool) use the centroids provided as input and do
32 ///< not change them during iterations
33
34 int min_points_per_centroid; ///< otherwise you get a warning
35 int max_points_per_centroid; ///< to limit size of dataset
36
37 int seed; ///< seed for the random number generator
38 size_t decode_block_size; ///< how many vectors at a time to decode
39 } FaissClusteringParameters;
40
41 /// Sets the ClusteringParameters object with reasonable defaults
42 void faiss_ClusteringParameters_init(FaissClusteringParameters* params);
43
44 /** clustering based on assignment - centroid update iterations
45 *
46 * The clustering is based on an Index object that assigns training
47 * points to the centroids. Therefore, at each iteration the centroids
48 * are added to the index.
49 *
50 * On output, the centroids table is set to the latest version
51 * of the centroids and they are also added to the index. If the
52 * centroids table it is not empty on input, it is also used for
53 * initialization.
54 *
55 * To do several clusterings, just call train() several times on
56 * different training sets, clearing the centroid table in between.
57 */
58 FAISS_DECLARE_CLASS(Clustering)
59
60 FAISS_DECLARE_GETTER(Clustering, int, niter)
61 FAISS_DECLARE_GETTER(Clustering, int, nredo)
62 FAISS_DECLARE_GETTER(Clustering, int, verbose)
63 FAISS_DECLARE_GETTER(Clustering, int, spherical)
64 FAISS_DECLARE_GETTER(Clustering, int, int_centroids)
65 FAISS_DECLARE_GETTER(Clustering, int, update_index)
66 FAISS_DECLARE_GETTER(Clustering, int, frozen_centroids)
67
68 FAISS_DECLARE_GETTER(Clustering, int, min_points_per_centroid)
69 FAISS_DECLARE_GETTER(Clustering, int, max_points_per_centroid)
70
71 FAISS_DECLARE_GETTER(Clustering, int, seed)
72 FAISS_DECLARE_GETTER(Clustering, size_t, decode_block_size)
73
74 /// getter for d
75 FAISS_DECLARE_GETTER(Clustering, size_t, d)
76
77 /// getter for k
78 FAISS_DECLARE_GETTER(Clustering, size_t, k)
79
80 FAISS_DECLARE_CLASS(ClusteringIterationStats)
81 FAISS_DECLARE_GETTER(ClusteringIterationStats, float, obj)
82 FAISS_DECLARE_GETTER(ClusteringIterationStats, double, time)
83 FAISS_DECLARE_GETTER(ClusteringIterationStats, double, time_search)
84 FAISS_DECLARE_GETTER(ClusteringIterationStats, double, imbalance_factor)
85 FAISS_DECLARE_GETTER(ClusteringIterationStats, int, nsplit)
86
87 /// getter for centroids (size = k * d)
88 void faiss_Clustering_centroids(
89 FaissClustering* clustering,
90 float** centroids,
91 size_t* size);
92
93 /// getter for iteration stats
94 void faiss_Clustering_iteration_stats(
95 FaissClustering* clustering,
96 FaissClusteringIterationStats** iteration_stats,
97 size_t* size);
98
99 /// the only mandatory parameters are k and d
100 int faiss_Clustering_new(FaissClustering** p_clustering, int d, int k);
101
102 int faiss_Clustering_new_with_params(
103 FaissClustering** p_clustering,
104 int d,
105 int k,
106 const FaissClusteringParameters* cp);
107
108 int faiss_Clustering_train(
109 FaissClustering* clustering,
110 idx_t n,
111 const float* x,
112 FaissIndex* index);
113
114 void faiss_Clustering_free(FaissClustering* clustering);
115
116 /** simplified interface
117 *
118 * @param d dimension of the data
119 * @param n nb of training vectors
120 * @param k nb of output centroids
121 * @param x training set (size n * d)
122 * @param centroids output centroids (size k * d)
123 * @param q_error final quantization error
124 * @return error code
125 */
126 int faiss_kmeans_clustering(
127 size_t d,
128 size_t n,
129 size_t k,
130 const float* x,
131 float* centroids,
132 float* q_error);
133
134 #ifdef __cplusplus
135 }
136 #endif
137
138 #endif