File AutoTune.h¶

namespace faiss

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree.

Throughout the library, vectors are provided as float * pointers. Most algorithms can be optimized when several vectors are processed (added/searched) together in a batch. In this case, they are passed in as a matrix. When n vectors of size d are provided as float * x, component j of vector i is

x[ i * d + j ]

where 0 <= i < n and 0 <= j < d. In other words, matrices are always compact. When specifying the size of the matrix, we call it an n*d matrix, which implies a row-major storage.

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. I/O functions can read/write to a filename, a file handle or to an object that abstracts the medium.

The read functions return objects that should be deallocated with delete. All references within these objectes are owned by the object.

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. Definition of inverted lists + a few common classes that implement the interface.

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. Since IVF (inverted file) indexes are of so much use for large-scale use cases, we group a few functions related to them in this small library. Most functions work both on IndexIVFs and IndexIVFs embedded within an IndexPreTransform.

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. In this file are the implementations of extra metrics beyond L2 and inner product

Copyright (c) Facebook, Inc. and its affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. Defines a few objects that apply transformations to a set of vectors Often these are pre-processing steps.

struct AutoTuneCriterion¶

#include <AutoTune.h>

Evaluation criterion. Returns a performance measure in [0,1], higher is better.

Subclassed by faiss::IntersectionCriterion, faiss::OneRecallAtRCriterion

Public Functions

AutoTuneCriterion(idx_t nq, idx_t nnn)¶

void set_groundtruth(int gt_nnn, const float *gt_D_in, const idx_t *gt_I_in)¶

Intitializes the gt_D and gt_I vectors. Must be called before evaluating

Parameters:

gt_D_in – size nq * gt_nnn
gt_I_in – size nq * gt_nnn

virtual double evaluate(const float *D, const idx_t *I) const = 0¶

Evaluate the criterion.

Parameters:

D – size nq * nnn
I – size nq * nnn

Returns:

the criterion, between 0 and 1. Larger is better.

inline virtual ~AutoTuneCriterion()¶

Public Members

idx_t nq¶: nb of queries this criterion is evaluated on

idx_t nnn¶: nb of NNs that the query should request

idx_t gt_nnn¶: nb of GT NNs required to evaluate criterion

std::vector<float> gt_D¶: Ground-truth distances (size nq * gt_nnn)

std::vector<idx_t> gt_I¶: Ground-truth indexes (size nq * gt_nnn)

struct OneRecallAtRCriterion : public faiss::AutoTuneCriterion ¶

Public Functions

OneRecallAtRCriterion(idx_t nq, idx_t R)¶

virtual double evaluate(const float *D, const idx_t *I) const override¶

Evaluate the criterion.

Parameters:

D – size nq * nnn
I – size nq * nnn

Returns:

the criterion, between 0 and 1. Larger is better.

inline ~OneRecallAtRCriterion() override¶

void set_groundtruth(int gt_nnn, const float *gt_D_in, const idx_t *gt_I_in)¶

Intitializes the gt_D and gt_I vectors. Must be called before evaluating

Parameters:

gt_D_in – size nq * gt_nnn
gt_I_in – size nq * gt_nnn

Public Members

idx_t R¶

idx_t nq¶: nb of queries this criterion is evaluated on

idx_t nnn¶: nb of NNs that the query should request

idx_t gt_nnn¶: nb of GT NNs required to evaluate criterion

std::vector<float> gt_D¶: Ground-truth distances (size nq * gt_nnn)

std::vector<idx_t> gt_I¶: Ground-truth indexes (size nq * gt_nnn)

struct IntersectionCriterion : public faiss::AutoTuneCriterion ¶

Public Functions

IntersectionCriterion(idx_t nq, idx_t R)¶

virtual double evaluate(const float *D, const idx_t *I) const override¶

Evaluate the criterion.

Parameters:

D – size nq * nnn
I – size nq * nnn

Returns:

the criterion, between 0 and 1. Larger is better.

inline ~IntersectionCriterion() override¶

void set_groundtruth(int gt_nnn, const float *gt_D_in, const idx_t *gt_I_in)¶

Intitializes the gt_D and gt_I vectors. Must be called before evaluating

Parameters:

gt_D_in – size nq * gt_nnn
gt_I_in – size nq * gt_nnn

Public Members

idx_t R¶

idx_t nq¶: nb of queries this criterion is evaluated on

idx_t nnn¶: nb of NNs that the query should request

idx_t gt_nnn¶: nb of GT NNs required to evaluate criterion

std::vector<float> gt_D¶: Ground-truth distances (size nq * gt_nnn)

std::vector<idx_t> gt_I¶: Ground-truth indexes (size nq * gt_nnn)

struct OperatingPoint¶

#include <AutoTune.h>

Maintains a list of experimental results. Each operating point is a (perf, t, key) triplet, where higher perf and lower t is better. The key field is an arbitrary identifier for the operating point.

Includes primitives to extract the Pareto-optimal operating points in the (perf, t) space.

Public Members

double perf¶: performance measure (output of a Criterion)

double t¶: corresponding execution time (ms)

std::string key¶: key that identifies this op pt

int64_t cno¶: integer identifer

struct OperatingPoints¶

Public Functions

OperatingPoints()¶

int merge_with(const OperatingPoints &other, const std::string &prefix = "")¶: add operating points from other to this, with a prefix to the keys

void clear()¶

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

double t_for_perf(double perf) const¶: get time required to obtain a given performance measure

void display(bool only_optimal = true) const¶: easy-to-read output

void all_to_gnuplot(const char *fname) const¶: output to a format easy to digest by gnuplot

void optimal_to_gnuplot(const char *fname) const¶

Public Members

std::vector<OperatingPoint> all_pts¶: all operating points

std::vector<OperatingPoint> optimal_pts¶: optimal operating points, sorted by perf

struct ParameterRange¶

#include <AutoTune.h>

possible values of a parameter, sorted from least to most expensive/accurate

Public Members

std::string name¶

std::vector<double> values¶

struct ParameterSpace¶

#include <AutoTune.h>

Uses a-priori knowledge on the Faiss indexes to extract tunable parameters.

Subclassed by faiss::gpu::GpuParameterSpace

Public Functions

ParameterSpace()¶

size_t n_combinations() const¶: nb of combinations, = product of values sizes

bool combination_ge(size_t c1, size_t c2) const¶: returns whether combinations c1 >= c2 in the tuple sense

std::string combination_name(size_t cno) const¶: get string representation of the combination

void display() const¶: print a description on stdout

ParameterRange &add_range(const std::string &name)¶: add a new parameter (or return it if it exists)

virtual void initialize(const Index *index)¶: initialize with reasonable parameters for the index

void set_index_parameters(Index *index, size_t cno) const¶: set a combination of parameters on an index

void set_index_parameters(Index *index, const char *param_string) const¶: set a combination of parameters described by a string

virtual void set_index_parameter(Index *index, const std::string &name, double val) const¶: set one of the parameters, returns whether setting was successful

void update_bounds(size_t cno, const OperatingPoint &op, double *upper_bound_perf, double *lower_bound_t) const¶: find an upper bound on the performance and a lower bound on t for configuration cno given another operating point op

void explore(Index *index, size_t nq, const float *xq, const AutoTuneCriterion &crit, OperatingPoints *ops) const¶

explore operating points

Parameters:

index – index to run on
xq – query vectors (size nq * index.d)
crit – selection criterion
ops – resulting operating points

inline virtual ~ParameterSpace()¶

Public Members

std::vector<ParameterRange> parameter_ranges¶: all tunable parameters

int verbose¶: verbosity during exploration

int n_experiments¶: nb of experiments during optimization (0 = try all combinations)

size_t batchsize¶: maximum number of queries to submit at a time.

bool thread_over_batches¶: use multithreading over batches (useful to benchmark independent single-searches)

double min_test_duration¶: run tests several times until they reach at least this duration (to avoid jittering in MT mode)