Faiss

- Main Page
- Namespaces
- Classes
- Files

- File List

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends
/data/users/matthijs/github_faiss/faiss/AutoTune.h
1
2 /**
3 * Copyright (c) 2015-present, Facebook, Inc.
4 * All rights reserved.
5 *
6 * This source code is licensed under the CC-by-NC license found in the
7 * LICENSE file in the root directory of this source tree.
8 */
9
10 // Copyright 2004-present Facebook. All Rights Reserved.
11 // -*- c++ -*-
12
13 #ifndef FAISS_AUTO_TUNE_H
14 #define FAISS_AUTO_TUNE_H
15
16 #include <vector>
17
18 #include "Index.h"
19
20 namespace faiss {
21
22
23 /**
24 * Evaluation criterion. Returns a performance measure in [0,1],
25 * higher is better.
26 */
27 struct AutoTuneCriterion {
28 typedef Index::idx_t idx_t;
29 idx_t nq; ///< nb of queries this criterion is evaluated on
30 idx_t nnn; ///< nb of NNs that the query should request
31 idx_t gt_nnn; ///< nb of GT NNs required to evaluate crterion
32
33 std::vector<float> gt_D; ///< Ground-truth distances (size nq * gt_nnn)
34 std::vector<idx_t> gt_I; ///< Ground-truth indexes (size nq * gt_nnn)
35
36 AutoTuneCriterion (idx_t nq, idx_t nnn);
37
38 /** Intitializes the gt_D and gt_I vectors. Must be called before evaluating
39 *
40 * @param gt_D_in size nq * gt_nnn
41 * @param gt_I_in size nq * gt_nnn
42 */
43 void set_groundtruth (int gt_nnn, const float *gt_D_in,
44 const idx_t *gt_I_in);
45
46 /** Evaluate the criterion.
47 *
48 * @param D size nq * nnn
49 * @param I size nq * nnn
50 * @return the criterion, between 0 and 1. Larger is better.
51 */
52 virtual double evaluate (const float *D, const idx_t *I) const = 0;
53
54 virtual ~AutoTuneCriterion () {}
55
56 };
57
58 struct OneRecallAtRCriterion: AutoTuneCriterion {
59
60 idx_t R;
61
62 OneRecallAtRCriterion (idx_t nq, idx_t R);
63
64 virtual double evaluate (const float *D, const idx_t *I) const override;
65
66 virtual ~OneRecallAtRCriterion () {}
67 };
68
69
70 struct IntersectionCriterion: AutoTuneCriterion {
71
72 idx_t R;
73
74 IntersectionCriterion (idx_t nq, idx_t R);
75
76 virtual double evaluate (const float *D, const idx_t *I) const override;
77
78 virtual ~IntersectionCriterion () {}
79 };
80
81 /**
82 * Maintains a list of experimental results. Each operating point is a
83 * (perf, t, key) triplet, where higher perf and lower t is
84 * better. The key field is an arbitrary identifier for the operating point
85 */
86
87 struct OperatingPoint {
88 double perf; ///< performance measure (output of a Criterion)
89 double t; ///< corresponding execution time (ms)
90 std::string key; ///< key that identifies this op pt
91 long cno; ///< integer identifer
92 };
93
94 struct OperatingPoints {
95 /// all operating points
96 std::vector<OperatingPoint> all_pts;
97
98 /// optimal operating points, sorted by perf
99 std::vector<OperatingPoint> optimal_pts;
100
101 // begins with a single operating point: t=0, perf=0
102 OperatingPoints ();
103
104 /// add operating points from other to this, with a prefix to the keys
105 int merge_with (const OperatingPoints &other,
106 const std::string & prefix = "");
107
108 void clear ();
109
110 /// add a performance measure. Return whether it is an optimal point
111 bool add (double perf, double t, const std::string & key, size_t cno = 0);
112
113 /// get time required to obtain a given performance measure
114 double t_for_perf (double perf) const;
115
116 /// easy-to-read output
117 void display (bool only_optimal = true) const;
118
119 /// output to a format easy to digest by gnuplot
120 void all_to_gnuplot (const char *fname) const;
121 void optimal_to_gnuplot (const char *fname) const;
122
123 };
124
125 /// possible values of a parameter, sorted from least to most expensive/accurate
126 struct ParameterRange {
127 std::string name;
128 std::vector<double> values;
129 };
130
131 /** Uses a-priori knowledge on the Faiss indexes to extract tunable parameters.
132 */
133 struct ParameterSpace {
134 /// all tunable parameters
135 std::vector<ParameterRange> parameter_ranges;
136
137 // exploration parameters
138
139 /// verbosity during exploration
140 int verbose;
141
142 /// nb of experiments during optimization (0 = try all combinations)
143 int n_experiments;
144
145 /// maximum number of queries to submit at a time.
146 size_t batchsize;
147
148 /// use multithreading over batches (useful to benchmark
149 /// independent single-searches)
150 bool thread_over_batches;
151
152 ParameterSpace ();
153
154 /// nb of combinations, = product of values sizes
155 size_t n_combinations () const;
156
157 /// returns whether combinations c1 >= c2 in the tuple sense
158 bool combination_ge (size_t c1, size_t c2) const;
159
160 /// get string representation of the combination
161 std::string combination_name (size_t cno) const;
162
163 /// print a description on stdout
164 void display () const;
165
166 /// add a new parameter
167 ParameterRange &add_range(const char * name);
168
169 /// initialize with reasonable parameters for the index
170 virtual void initialize (const Index * index);
171
172 /// set a combination of parameters on an index
173 void set_index_parameters (Index *index, size_t cno) const;
174
175 /// set a combination of parameters described by a string
176 void set_index_parameters (Index *index, const char *param_string) const;
177
178 /// set one of the parameters
179 virtual void set_index_parameter (
180 Index * index, const std::string & name, double val) const;
181
182 /** find an upper bound on the performance and a lower bound on t
183 * for configuration cno given another operating point op */
184 void update_bounds (size_t cno, const OperatingPoint & op,
185 double *upper_bound_perf,
186 double *lower_bound_t) const;
187
188 /** explore operating points
189 * @param index index to run on
190 * @param xq query vectors (size nq * index.d)
191 * @param crit selection criterion
192 * @param ops resutling operating points
193 */
194 void explore (Index *index,
195 size_t nq, const float *xq,
196 const AutoTuneCriterion & crit,
197 OperatingPoints * ops) const;
198
199 virtual ~ParameterSpace () {}
200 };
201
202 /** Build and index with the sequence of processing steps described in
203 * the string. */
204 Index *index_factory (int d, const char *description,
205 MetricType metric = METRIC_L2);
206
207
208
209 } // namespace faiss
210
211
212
213 #endif
faiss::ParameterSpace::explore
void explore(Index *index, size_t nq, const float *xq, const AutoTuneCriterion &crit, OperatingPoints *ops) const
Definition: AutoTune.cpp:512
faiss::ParameterSpace::parameter_ranges
std::vector< ParameterRange > parameter_ranges
all tunable parameters
Definition: AutoTune.h:135
faiss::OperatingPoint::key
std::string key
key that identifies this op pt
Definition: AutoTune.h:90
faiss::OperatingPoint::cno
long cno
integer identifer
Definition: AutoTune.h:91
faiss::OperatingPoints::clear
void clear()
Definition: AutoTune.cpp:101
faiss::OperatingPoint
Definition: AutoTune.h:87
faiss::OperatingPoints::display
void display(bool only_optimal=true) const
easy-to-read output
Definition: AutoTune.cpp:220
faiss::OperatingPoint::perf
double perf
performance measure (output of a Criterion)
Definition: AutoTune.h:88
faiss::OperatingPoints
Definition: AutoTune.h:94
faiss::OperatingPoints::t_for_perf
double t_for_perf(double perf) const
get time required to obtain a given performance measure
Definition: AutoTune.cpp:173
faiss::AutoTuneCriterion::nnn
idx_t nnn
nb of NNs that the query should request
Definition: AutoTune.h:30
faiss::IntersectionCriterion::evaluate
virtual double evaluate(const float *D, const idx_t *I) const override
Definition: AutoTune.cpp:78
faiss::OperatingPoints::add
bool add(double perf, double t, const std::string &key, size_t cno=0)
add a performance measure. Return whether it is an optimal point
Definition: AutoTune.cpp:111
faiss::ParameterSpace::batchsize
size_t batchsize
maximum number of queries to submit at a time.
Definition: AutoTune.h:146
faiss::AutoTuneCriterion::evaluate
virtual double evaluate(const float *D, const idx_t *I) const =0
faiss::AutoTuneCriterion::nq
idx_t nq
nb of queries this criterion is evaluated on
Definition: AutoTune.h:29
faiss::OperatingPoints::optimal_pts
std::vector< OperatingPoint > optimal_pts
optimal operating points, sorted by perf
Definition: AutoTune.h:99
faiss::AutoTuneCriterion::set_groundtruth
void set_groundtruth(int gt_nnn, const float *gt_D_in, const idx_t *gt_I_in)
Definition: AutoTune.cpp:37
faiss::ParameterSpace::add_range
ParameterRange & add_range(const char *name)
add a new parameter
Definition: AutoTune.cpp:321
faiss::IntersectionCriterion
Definition: AutoTune.h:70
faiss::AutoTuneCriterion::gt_nnn
idx_t gt_nnn
nb of GT NNs required to evaluate crterion
Definition: AutoTune.h:31
faiss::OperatingPoints::all_to_gnuplot
void all_to_gnuplot(const char *fname) const
output to a format easy to digest by gnuplot
Definition: AutoTune.cpp:187
faiss::ParameterSpace::thread_over_batches
bool thread_over_batches
Definition: AutoTune.h:150
faiss::OperatingPoints::all_pts
std::vector< OperatingPoint > all_pts
all operating points
Definition: AutoTune.h:96
faiss::Index::idx_t
long idx_t
all indices are this type
Definition: Index.h:64
faiss::AutoTuneCriterion
Definition: AutoTune.h:27
faiss::AutoTuneCriterion::gt_D
std::vector< float > gt_D
Ground-truth distances (size nq * gt_nnn)
Definition: AutoTune.h:33
faiss::ParameterSpace::combination_name
std::string combination_name(size_t cno) const
get string representation of the combination
Definition: AutoTune.cpp:276
faiss::ParameterSpace::update_bounds
void update_bounds(size_t cno, const OperatingPoint &op, double *upper_bound_perf, double *lower_bound_t) const
Definition: AutoTune.cpp:498
faiss::ParameterSpace::initialize
virtual void initialize(const Index *index)
initialize with reasonable parameters for the index
Definition: AutoTune.cpp:330
faiss::ParameterSpace::verbose
int verbose
verbosity during exploration
Definition: AutoTune.h:140
faiss::OperatingPoints::merge_with
int merge_with(const OperatingPoints &other, const std::string &prefix="")
add operating points from other to this, with a prefix to the keys
Definition: AutoTune.cpp:158
faiss::ParameterSpace::set_index_parameter
virtual void set_index_parameter(Index *index, const std::string &name, double val) const
set one of the parameters
Definition: AutoTune.cpp:419
faiss::ParameterSpace::n_combinations
size_t n_combinations() const
nb of combinations, = product of values sizes
Definition: AutoTune.cpp:267
faiss::ParameterSpace::set_index_parameters
void set_index_parameters(Index *index, size_t cno) const
set a combination of parameters on an index
Definition: AutoTune.cpp:388
faiss::ParameterSpace
Definition: AutoTune.h:133
faiss::Index
Definition: Index.h:61
faiss::ParameterSpace::display
void display() const
print a description on stdout
Definition: AutoTune.cpp:480
faiss::ParameterSpace::combination_ge
bool combination_ge(size_t c1, size_t c2) const
returns whether combinations c1 &gt;= c2 in the tuple sense
Definition: AutoTune.cpp:291
faiss::ParameterRange
possible values of a parameter, sorted from least to most expensive/accurate
Definition: AutoTune.h:126
faiss::index_factory
Index * index_factory(int d, const char *description_in, MetricType metric)
Definition: AutoTune.cpp:623
faiss::ParameterSpace::n_experiments
int n_experiments
nb of experiments during optimization (0 = try all combinations)
Definition: AutoTune.h:143
faiss::AutoTuneCriterion::gt_I
std::vector< idx_t > gt_I
Ground-truth indexes (size nq * gt_nnn)
Definition: AutoTune.h:34
faiss::OperatingPoint::t
double t
corresponding execution time (ms)
Definition: AutoTune.h:89
faiss::OneRecallAtRCriterion
Definition: AutoTune.h:58
faiss::MetricType
MetricType
Some algorithms support both an inner product vetsion and a L2 search version.
Definition: Index.h:44