From 445b1ca25feb815e293e80208cf677464b95c5bf Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Tue, 11 Jun 2024 18:20:57 +0000 Subject: [PATCH] c_api/ --- c_api/AutoTune_c.cpp | 114 ++++++++++++ c_api/AutoTune_c.h | 83 +++++++++ c_api/CMakeLists.txt | 59 ++++++ c_api/Clustering_c.cpp | 171 ++++++++++++++++++ c_api/Clustering_c.h | 139 ++++++++++++++ c_api/INSTALL.md | 100 +++++++++++ c_api/IndexBinary_c.cpp | 143 +++++++++++++++ c_api/IndexBinary_c.h | 170 ++++++++++++++++++ c_api/IndexFlat_c.cpp | 166 +++++++++++++++++ c_api/IndexFlat_c.h | 130 ++++++++++++++ c_api/IndexIVFFlat_c.cpp | 101 +++++++++++ c_api/IndexIVFFlat_c.h | 86 +++++++++ c_api/IndexIVF_c.cpp | 131 ++++++++++++++ c_api/IndexIVF_c.h | 163 +++++++++++++++++ c_api/IndexLSH_c.cpp | 47 +++++ c_api/IndexLSH_c.h | 45 +++++ c_api/IndexPreTransform_c.cpp | 71 ++++++++ c_api/IndexPreTransform_c.h | 50 ++++++ c_api/IndexReplicas_c.cpp | 62 +++++++ c_api/IndexReplicas_c.h | 48 +++++ c_api/IndexScalarQuantizer_c.cpp | 122 +++++++++++++ c_api/IndexScalarQuantizer_c.h | 100 +++++++++++ c_api/IndexShards_c.cpp | 65 +++++++ c_api/IndexShards_c.h | 46 +++++ c_api/Index_c.cpp | 190 ++++++++++++++++++++ c_api/Index_c.h | 254 ++++++++++++++++++++++++++ c_api/MetaIndexes_c.cpp | 82 +++++++++ c_api/MetaIndexes_c.h | 100 +++++++++++ c_api/VectorTransform_c.cpp | 228 +++++++++++++++++++++++ c_api/VectorTransform_c.h | 174 ++++++++++++++++++ c_api/clone_index_c.cpp | 24 +++ c_api/clone_index_c.h | 31 ++++ c_api/error_c.h | 42 +++++ c_api/error_impl.cpp | 27 +++ c_api/error_impl.h | 16 ++ c_api/example_c.c | 104 +++++++++++ c_api/faiss_c.h | 57 ++++++ c_api/gpu/CMakeLists.txt | 22 +++ c_api/gpu/DeviceUtils_c.cpp | 47 +++++ c_api/gpu/DeviceUtils_c.h | 38 ++++ c_api/gpu/GpuAutoTune_c.cpp | 113 ++++++++++++ c_api/gpu/GpuAutoTune_c.h | 67 +++++++ c_api/gpu/GpuClonerOptions_c.cpp | 59 ++++++ c_api/gpu/GpuClonerOptions_c.h | 71 ++++++++ c_api/gpu/GpuIndex_c.cpp | 17 ++ c_api/gpu/GpuIndex_c.h | 30 ++++ c_api/gpu/GpuIndicesOptions_c.h | 38 ++++ c_api/gpu/GpuResources_c.cpp | 130 ++++++++++++++ c_api/gpu/GpuResources_c.h | 83 +++++++++ c_api/gpu/StandardGpuResources_c.cpp | 70 ++++++++ c_api/gpu/StandardGpuResources_c.h | 61 +++++++ c_api/gpu/example_gpu_c.c | 120 +++++++++++++ c_api/gpu/macros_impl.h | 41 +++++ c_api/impl/AuxIndexStructures_c.cpp | 259 +++++++++++++++++++++++++++ c_api/impl/AuxIndexStructures_c.h | 168 +++++++++++++++++ c_api/index_factory_c.cpp | 31 ++++ c_api/index_factory_c.h | 34 ++++ c_api/index_io_c.cpp | 86 +++++++++ c_api/index_io_c.h | 78 ++++++++ c_api/macros_impl.h | 102 +++++++++++ c_api/utils/distances_c.cpp | 102 +++++++++++ c_api/utils/distances_c.h | 109 +++++++++++ 62 files changed, 5717 insertions(+) create mode 100644 c_api/AutoTune_c.cpp create mode 100644 c_api/AutoTune_c.h create mode 100644 c_api/CMakeLists.txt create mode 100644 c_api/Clustering_c.cpp create mode 100644 c_api/Clustering_c.h create mode 100644 c_api/INSTALL.md create mode 100644 c_api/IndexBinary_c.cpp create mode 100644 c_api/IndexBinary_c.h create mode 100644 c_api/IndexFlat_c.cpp create mode 100644 c_api/IndexFlat_c.h create mode 100644 c_api/IndexIVFFlat_c.cpp create mode 100644 c_api/IndexIVFFlat_c.h create mode 100644 c_api/IndexIVF_c.cpp create mode 100644 c_api/IndexIVF_c.h create mode 100644 c_api/IndexLSH_c.cpp create mode 100644 c_api/IndexLSH_c.h create mode 100644 c_api/IndexPreTransform_c.cpp create mode 100644 c_api/IndexPreTransform_c.h create mode 100644 c_api/IndexReplicas_c.cpp create mode 100644 c_api/IndexReplicas_c.h create mode 100644 c_api/IndexScalarQuantizer_c.cpp create mode 100644 c_api/IndexScalarQuantizer_c.h create mode 100644 c_api/IndexShards_c.cpp create mode 100644 c_api/IndexShards_c.h create mode 100644 c_api/Index_c.cpp create mode 100644 c_api/Index_c.h create mode 100644 c_api/MetaIndexes_c.cpp create mode 100644 c_api/MetaIndexes_c.h create mode 100644 c_api/VectorTransform_c.cpp create mode 100644 c_api/VectorTransform_c.h create mode 100644 c_api/clone_index_c.cpp create mode 100644 c_api/clone_index_c.h create mode 100644 c_api/error_c.h create mode 100644 c_api/error_impl.cpp create mode 100644 c_api/error_impl.h create mode 100644 c_api/example_c.c create mode 100644 c_api/faiss_c.h create mode 100644 c_api/gpu/CMakeLists.txt create mode 100644 c_api/gpu/DeviceUtils_c.cpp create mode 100644 c_api/gpu/DeviceUtils_c.h create mode 100644 c_api/gpu/GpuAutoTune_c.cpp create mode 100644 c_api/gpu/GpuAutoTune_c.h create mode 100644 c_api/gpu/GpuClonerOptions_c.cpp create mode 100644 c_api/gpu/GpuClonerOptions_c.h create mode 100644 c_api/gpu/GpuIndex_c.cpp create mode 100644 c_api/gpu/GpuIndex_c.h create mode 100644 c_api/gpu/GpuIndicesOptions_c.h create mode 100644 c_api/gpu/GpuResources_c.cpp create mode 100644 c_api/gpu/GpuResources_c.h create mode 100644 c_api/gpu/StandardGpuResources_c.cpp create mode 100644 c_api/gpu/StandardGpuResources_c.h create mode 100644 c_api/gpu/example_gpu_c.c create mode 100644 c_api/gpu/macros_impl.h create mode 100644 c_api/impl/AuxIndexStructures_c.cpp create mode 100644 c_api/impl/AuxIndexStructures_c.h create mode 100644 c_api/index_factory_c.cpp create mode 100644 c_api/index_factory_c.h create mode 100644 c_api/index_io_c.cpp create mode 100644 c_api/index_io_c.h create mode 100644 c_api/macros_impl.h create mode 100644 c_api/utils/distances_c.cpp create mode 100644 c_api/utils/distances_c.h diff --git a/c_api/AutoTune_c.cpp b/c_api/AutoTune_c.cpp new file mode 100644 index 0000000..5c1a037 --- /dev/null +++ b/c_api/AutoTune_c.cpp @@ -0,0 +1,114 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "AutoTune_c.h" +#include +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::ParameterRange; +using faiss::ParameterSpace; + +const char* faiss_ParameterRange_name(const FaissParameterRange* range) { + return reinterpret_cast(range)->name.c_str(); +} + +void faiss_ParameterRange_values( + FaissParameterRange* range, + double** p_values, + size_t* p_size) { + auto& values = reinterpret_cast(range)->values; + *p_values = values.data(); + *p_size = values.size(); +} + +int faiss_ParameterSpace_new(FaissParameterSpace** space) { + try { + auto new_space = new ParameterSpace(); + *space = reinterpret_cast(new_space); + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(ParameterSpace) + +size_t faiss_ParameterSpace_n_combinations(const FaissParameterSpace* space) { + return reinterpret_cast(space)->n_combinations(); +} + +int faiss_ParameterSpace_combination_name( + const FaissParameterSpace* space, + size_t cno, + char* char_buffer, + size_t size) { + try { + auto rep = reinterpret_cast(space) + ->combination_name(cno); + strncpy(char_buffer, rep.c_str(), size); + } + CATCH_AND_HANDLE +} + +int faiss_ParameterSpace_set_index_parameters( + const FaissParameterSpace* space, + FaissIndex* cindex, + const char* param_string) { + try { + auto index = reinterpret_cast(cindex); + reinterpret_cast(space)->set_index_parameters( + index, param_string); + } + CATCH_AND_HANDLE +} + +/// set a combination of parameters on an index +int faiss_ParameterSpace_set_index_parameters_cno( + const FaissParameterSpace* space, + FaissIndex* cindex, + size_t cno) { + try { + auto index = reinterpret_cast(cindex); + reinterpret_cast(space)->set_index_parameters( + index, cno); + } + CATCH_AND_HANDLE +} + +int faiss_ParameterSpace_set_index_parameter( + const FaissParameterSpace* space, + FaissIndex* cindex, + const char* name, + double value) { + try { + auto index = reinterpret_cast(cindex); + reinterpret_cast(space)->set_index_parameter( + index, name, value); + } + CATCH_AND_HANDLE +} + +void faiss_ParameterSpace_display(const FaissParameterSpace* space) { + reinterpret_cast(space)->display(); +} + +int faiss_ParameterSpace_add_range( + FaissParameterSpace* space, + const char* name, + FaissParameterRange** p_range) { + try { + ParameterRange& range = + reinterpret_cast(space)->add_range(name); + if (p_range) { + *p_range = reinterpret_cast(&range); + } + } + CATCH_AND_HANDLE +} diff --git a/c_api/AutoTune_c.h b/c_api/AutoTune_c.h new file mode 100644 index 0000000..2bb5529 --- /dev/null +++ b/c_api/AutoTune_c.h @@ -0,0 +1,83 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_AUTO_TUNE_C_H +#define FAISS_AUTO_TUNE_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// possible values of a parameter, sorted from least to most expensive/accurate +FAISS_DECLARE_CLASS(ParameterRange) + +FAISS_DECLARE_GETTER(ParameterRange, const char*, name) + +/// Getter for the values in the range. The output values are invalidated +/// upon any other modification of the range. +void faiss_ParameterRange_values(FaissParameterRange*, double**, size_t*); + +/** Uses a-priori knowledge on the Faiss indexes to extract tunable parameters. + */ +FAISS_DECLARE_CLASS(ParameterSpace) + +FAISS_DECLARE_DESTRUCTOR(ParameterSpace) + +/// Parameter space default constructor +int faiss_ParameterSpace_new(FaissParameterSpace** space); + +/// nb of combinations, = product of values sizes +size_t faiss_ParameterSpace_n_combinations(const FaissParameterSpace*); + +/// get string representation of the combination +/// by writing it to the given character buffer. +/// A buffer size of 1000 ensures that the full name is collected. +int faiss_ParameterSpace_combination_name( + const FaissParameterSpace*, + size_t, + char*, + size_t); + +/// set a combination of parameters described by a string +int faiss_ParameterSpace_set_index_parameters( + const FaissParameterSpace*, + FaissIndex*, + const char*); + +/// set a combination of parameters on an index +int faiss_ParameterSpace_set_index_parameters_cno( + const FaissParameterSpace*, + FaissIndex*, + size_t); + +/// set one of the parameters +int faiss_ParameterSpace_set_index_parameter( + const FaissParameterSpace*, + FaissIndex*, + const char*, + double); + +/// print a description on stdout +void faiss_ParameterSpace_display(const FaissParameterSpace*); + +/// add a new parameter (or return it if it exists) +int faiss_ParameterSpace_add_range( + FaissParameterSpace*, + const char*, + FaissParameterRange**); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/CMakeLists.txt b/c_api/CMakeLists.txt new file mode 100644 index 0000000..01789a3 --- /dev/null +++ b/c_api/CMakeLists.txt @@ -0,0 +1,59 @@ +# 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. + +cmake_minimum_required(VERSION 3.17 FATAL_ERROR) + +project(faiss_c_library LANGUAGES C CXX) + +set(CMAKE_C_STANDARD 11) + +set(FAISS_C_SRC + AutoTune_c.cpp + Clustering_c.cpp + IndexFlat_c.cpp + IndexIVFFlat_c.cpp + IndexIVF_c.cpp + IndexLSH_c.cpp + IndexPreTransform_c.cpp + VectorTransform_c.cpp + IndexShards_c.cpp + IndexReplicas_c.cpp + Index_c.cpp + IndexBinary_c.cpp + IndexScalarQuantizer_c.cpp + MetaIndexes_c.cpp + clone_index_c.cpp + error_impl.cpp + index_factory_c.cpp + index_io_c.cpp + impl/AuxIndexStructures_c.cpp + utils/distances_c.cpp +) +add_library(faiss_c ${FAISS_C_SRC}) +target_link_libraries(faiss_c PRIVATE faiss) + +function(faiss_install_headers headers p) + foreach(h ${headers}) + get_filename_component(f ${h} DIRECTORY) + install(FILES ${h} + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/faiss/${p}/${f} + ) + endforeach() +endfunction() + +file(GLOB FAISS_C_API_HEADERS + RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} + "*.h" + "impl/*.h" + "utils/*.h") + +faiss_install_headers("${FAISS_C_API_HEADERS}" c_api) + +add_executable(example_c EXCLUDE_FROM_ALL example_c.c) +target_link_libraries(example_c PRIVATE faiss_c) + +if(FAISS_ENABLE_GPU) + add_subdirectory(gpu) +endif() diff --git a/c_api/Clustering_c.cpp b/c_api/Clustering_c.cpp new file mode 100644 index 0000000..2206f6d --- /dev/null +++ b/c_api/Clustering_c.cpp @@ -0,0 +1,171 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "Clustering_c.h" +#include +#include +#include +#include "macros_impl.h" + +extern "C" { + +using faiss::Clustering; +using faiss::ClusteringIterationStats; +using faiss::ClusteringParameters; +using faiss::Index; + +DEFINE_GETTER(Clustering, int, niter) +DEFINE_GETTER(Clustering, int, nredo) +DEFINE_GETTER(Clustering, int, verbose) +DEFINE_GETTER(Clustering, int, spherical) +DEFINE_GETTER(Clustering, int, int_centroids) +DEFINE_GETTER(Clustering, int, update_index) +DEFINE_GETTER(Clustering, int, frozen_centroids) + +DEFINE_GETTER(Clustering, int, min_points_per_centroid) +DEFINE_GETTER(Clustering, int, max_points_per_centroid) + +DEFINE_GETTER(Clustering, int, seed) +DEFINE_GETTER(Clustering, size_t, decode_block_size) + +/// getter for d +DEFINE_GETTER(Clustering, size_t, d) + +/// getter for k +DEFINE_GETTER(Clustering, size_t, k) + +DEFINE_GETTER(ClusteringIterationStats, float, obj) +DEFINE_GETTER(ClusteringIterationStats, double, time) +DEFINE_GETTER(ClusteringIterationStats, double, time_search) +DEFINE_GETTER(ClusteringIterationStats, double, imbalance_factor) +DEFINE_GETTER(ClusteringIterationStats, int, nsplit) + +void faiss_ClusteringParameters_init(FaissClusteringParameters* params) { + ClusteringParameters d; + params->frozen_centroids = d.frozen_centroids; + params->max_points_per_centroid = d.max_points_per_centroid; + params->min_points_per_centroid = d.min_points_per_centroid; + params->niter = d.niter; + params->nredo = d.nredo; + params->seed = d.seed; + params->spherical = d.spherical; + params->int_centroids = d.int_centroids; + params->update_index = d.update_index; + params->verbose = d.verbose; + params->decode_block_size = d.decode_block_size; +} + +// This conversion is required because the two types are not memory-compatible +inline ClusteringParameters from_faiss_c( + const FaissClusteringParameters* params) { + ClusteringParameters o; + o.frozen_centroids = params->frozen_centroids; + o.max_points_per_centroid = params->max_points_per_centroid; + o.min_points_per_centroid = params->min_points_per_centroid; + o.niter = params->niter; + o.nredo = params->nredo; + o.seed = params->seed; + o.spherical = params->spherical; + o.update_index = params->update_index; + o.int_centroids = params->int_centroids; + o.verbose = params->verbose; + o.decode_block_size = params->decode_block_size; + return o; +} + +/// getter for centroids (size = k * d) +void faiss_Clustering_centroids( + FaissClustering* clustering, + float** centroids, + size_t* size) { + std::vector& v = + reinterpret_cast(clustering)->centroids; + if (centroids) { + *centroids = v.data(); + } + if (size) { + *size = v.size(); + } +} + +/// getter for iteration stats +void faiss_Clustering_iteration_stats( + FaissClustering* clustering, + FaissClusteringIterationStats** iteration_stats, + size_t* size) { + std::vector& v = + reinterpret_cast(clustering)->iteration_stats; + if (iteration_stats) { + *iteration_stats = + reinterpret_cast(v.data()); + } + if (size) { + *size = v.size(); + } +} + +/// the only mandatory parameters are k and d +int faiss_Clustering_new(FaissClustering** p_clustering, int d, int k) { + try { + Clustering* c = new Clustering(d, k); + *p_clustering = reinterpret_cast(c); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_Clustering_new_with_params( + FaissClustering** p_clustering, + int d, + int k, + const FaissClusteringParameters* cp) { + try { + Clustering* c = new Clustering(d, k, from_faiss_c(cp)); + *p_clustering = reinterpret_cast(c); + return 0; + } + CATCH_AND_HANDLE +} + +/// Index is used during the assignment stage +int faiss_Clustering_train( + FaissClustering* clustering, + idx_t n, + const float* x, + FaissIndex* index) { + try { + reinterpret_cast(clustering) + ->train(n, x, *reinterpret_cast(index)); + return 0; + } + CATCH_AND_HANDLE +} + +void faiss_Clustering_free(FaissClustering* clustering) { + delete reinterpret_cast(clustering); +} + +int faiss_kmeans_clustering( + size_t d, + size_t n, + size_t k, + const float* x, + float* centroids, + float* q_error) { + try { + float out = faiss::kmeans_clustering(d, n, k, x, centroids); + if (q_error) { + *q_error = out; + } + return 0; + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/Clustering_c.h b/c_api/Clustering_c.h new file mode 100644 index 0000000..18a6bba --- /dev/null +++ b/c_api/Clustering_c.h @@ -0,0 +1,139 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c -*- + +#ifndef FAISS_CLUSTERING_C_H +#define FAISS_CLUSTERING_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Class for the clustering parameters. Can be passed to the + * constructor of the Clustering object. + */ +typedef struct FaissClusteringParameters { + int niter; ///< clustering iterations + int nredo; ///< redo clustering this many times and keep best + + int verbose; ///< (bool) + int spherical; ///< (bool) do we want normalized centroids? + int int_centroids; ///< (bool) round centroids coordinates to integer + int update_index; ///< (bool) update index after each iteration? + int frozen_centroids; ///< (bool) use the centroids provided as input and do + ///< not change them during iterations + + int min_points_per_centroid; ///< otherwise you get a warning + int max_points_per_centroid; ///< to limit size of dataset + + int seed; ///< seed for the random number generator + size_t decode_block_size; ///< how many vectors at a time to decode +} FaissClusteringParameters; + +/// Sets the ClusteringParameters object with reasonable defaults +void faiss_ClusteringParameters_init(FaissClusteringParameters* params); + +/** clustering based on assignment - centroid update iterations + * + * The clustering is based on an Index object that assigns training + * points to the centroids. Therefore, at each iteration the centroids + * are added to the index. + * + * On output, the centroids table is set to the latest version + * of the centroids and they are also added to the index. If the + * centroids table it is not empty on input, it is also used for + * initialization. + * + * To do several clusterings, just call train() several times on + * different training sets, clearing the centroid table in between. + */ +FAISS_DECLARE_CLASS(Clustering) + +FAISS_DECLARE_GETTER(Clustering, int, niter) +FAISS_DECLARE_GETTER(Clustering, int, nredo) +FAISS_DECLARE_GETTER(Clustering, int, verbose) +FAISS_DECLARE_GETTER(Clustering, int, spherical) +FAISS_DECLARE_GETTER(Clustering, int, int_centroids) +FAISS_DECLARE_GETTER(Clustering, int, update_index) +FAISS_DECLARE_GETTER(Clustering, int, frozen_centroids) + +FAISS_DECLARE_GETTER(Clustering, int, min_points_per_centroid) +FAISS_DECLARE_GETTER(Clustering, int, max_points_per_centroid) + +FAISS_DECLARE_GETTER(Clustering, int, seed) +FAISS_DECLARE_GETTER(Clustering, size_t, decode_block_size) + +/// getter for d +FAISS_DECLARE_GETTER(Clustering, size_t, d) + +/// getter for k +FAISS_DECLARE_GETTER(Clustering, size_t, k) + +FAISS_DECLARE_CLASS(ClusteringIterationStats) +FAISS_DECLARE_GETTER(ClusteringIterationStats, float, obj) +FAISS_DECLARE_GETTER(ClusteringIterationStats, double, time) +FAISS_DECLARE_GETTER(ClusteringIterationStats, double, time_search) +FAISS_DECLARE_GETTER(ClusteringIterationStats, double, imbalance_factor) +FAISS_DECLARE_GETTER(ClusteringIterationStats, int, nsplit) + +/// getter for centroids (size = k * d) +void faiss_Clustering_centroids( + FaissClustering* clustering, + float** centroids, + size_t* size); + +/// getter for iteration stats +void faiss_Clustering_iteration_stats( + FaissClustering* clustering, + FaissClusteringIterationStats** iteration_stats, + size_t* size); + +/// the only mandatory parameters are k and d +int faiss_Clustering_new(FaissClustering** p_clustering, int d, int k); + +int faiss_Clustering_new_with_params( + FaissClustering** p_clustering, + int d, + int k, + const FaissClusteringParameters* cp); + +int faiss_Clustering_train( + FaissClustering* clustering, + idx_t n, + const float* x, + FaissIndex* index); + +void faiss_Clustering_free(FaissClustering* clustering); + +/** simplified interface + * + * @param d dimension of the data + * @param n nb of training vectors + * @param k nb of output centroids + * @param x training set (size n * d) + * @param centroids output centroids (size k * d) + * @param q_error final quantization error + * @return error code + */ +int faiss_kmeans_clustering( + size_t d, + size_t n, + size_t k, + const float* x, + float* centroids, + float* q_error); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/INSTALL.md b/c_api/INSTALL.md new file mode 100644 index 0000000..cdccfb8 --- /dev/null +++ b/c_api/INSTALL.md @@ -0,0 +1,100 @@ +Faiss C API +=========== + +Faiss provides a pure C interface, which can subsequently be used either in pure C programs or to produce bindings for programming languages with Foreign Function Interface (FFI) support. Although this is not required for the Python interface, some other programming languages (e.g. Rust and Julia) do not have SWIG support. + +Compilation instructions +------------------------ + +The full contents of the pure C API are in the ["c_api"](c_api/) folder. +Please be sure to follow the instructions on [building the main C++ library](../INSTALL.md#step-1-compiling-the-c-faiss) first. +Then, enter the [c_api](c_api/) directory and run + + `make` + +This builds the dynamic library "faiss_c", containing the full implementation of Faiss and the necessary wrappers for the C interface. It does not depend on libfaiss.a or the C++ standard library. It will also build an example program `bin/example_c`. + +Using the API +------------- + +The C API is composed of: + +- A set of C header files comprising the main Faiss interfaces, converted for use in C. Each file follows the format `«name»_c.h`, where `«name»` is the respective name from the C++ API. For example, the file [Index_c.h](./Index_c.h) file corresponds to the base `Index` API. Functions are declared with the `faiss_` prefix (e.g. `faiss_IndexFlat_new`), whereas new types have the `Faiss` prefix (e.g. `FaissIndex`, `FaissMetricType`, ...). +- A dynamic library, compiled from the sources in the same folder, encloses the implementation of the library and wrapper functions. + +The index factory is available via the `faiss_index_factory` function in `AutoTune_c.h`: + +```c +FaissIndex* index = NULL; +int c = faiss_index_factory(&index, 64, "Flat", METRIC_L2); +if (c) { + // operation failed +} +``` + +Most operations that you would find as member functions are available with the format `faiss_«classname»_«member»`. + +```c +idx_t ntotal = faiss_Index_ntotal(index); +``` + +Since this is C, the index needs to be freed manually in the end: + +```c +faiss_Index_free(index); +``` + +Error handling is done by examining the error code returned by operations with recoverable errors. +The code identifies the type of exception that rose from the implementation. Fetching the +corresponding error message can be done by calling the function `faiss_get_last_error()` from +`error_c.h`. Getter functions and `free` functions do not return an error code. + +```c +int c = faiss_Index_add(index, nb, xb); +if (c) { + printf("%s", faiss_get_last_error()); + exit(-1); +} +``` + +An example is included, which is built automatically for the target `all`. It can also be built separately: + + `make bin/example_c` + +Building with GPU support +------------------------- + +For GPU support, a separate dynamic library in the "c_api/gpu" directory needs to be built. + + `make` + +The "gpufaiss_c" dynamic library contains the GPU and CPU implementations of Faiss, which means that +it can be used in place of "faiss_c". The same library will dynamically link with the CUDA runtime +and cuBLAS. + +Using the GPU with the C API +---------------------------- + +A standard GPU resources object can be obtained by the name `FaissStandardGpuResources`: + +```c +FaissStandardGpuResources* gpu_res = NULL; +int c = faiss_StandardGpuResources_new(&gpu_res); +if (c) { + printf("%s", faiss_get_last_error()); + exit(-1); +} +``` + +Similarly to the C++ API, a CPU index can be converted to a GPU index: + +```c +FaissIndex* cpu_index = NULL; +int c = faiss_index_factory(&cpu_index, d, "Flat", METRIC_L2); +if (c) { /* ... */ } +FaissGpuIndex* gpu_index = NULL; +c = faiss_index_cpu_to_gpu(gpu_res, 0, cpu_index, &gpu_index); +if (c) { /* ... */ } +``` + +A more complete example is available by the name `bin/example_gpu_c`. diff --git a/c_api/IndexBinary_c.cpp b/c_api/IndexBinary_c.cpp new file mode 100644 index 0000000..85986af --- /dev/null +++ b/c_api/IndexBinary_c.cpp @@ -0,0 +1,143 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexBinary_c.h" +#include +#include "macros_impl.h" + +extern "C" { + +DEFINE_DESTRUCTOR(IndexBinary) + +DEFINE_GETTER(IndexBinary, int, d) + +DEFINE_GETTER(IndexBinary, int, is_trained) + +DEFINE_GETTER(IndexBinary, idx_t, ntotal) + +DEFINE_GETTER(IndexBinary, FaissMetricType, metric_type) + +DEFINE_GETTER(IndexBinary, int, verbose); +DEFINE_SETTER(IndexBinary, int, verbose); + +int faiss_IndexBinary_train( + FaissIndexBinary* index, + idx_t n, + const uint8_t* x) { + try { + reinterpret_cast(index)->train(n, x); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_add(FaissIndexBinary* index, idx_t n, const uint8_t* x) { + try { + reinterpret_cast(index)->add(n, x); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_add_with_ids( + FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + const idx_t* xids) { + try { + reinterpret_cast(index)->add_with_ids(n, x, xids); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_search( + const FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + idx_t k, + int32_t* distances, + idx_t* labels) { + try { + reinterpret_cast(index)->search( + n, x, k, distances, labels); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_range_search( + const FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + int radius, + FaissRangeSearchResult* result) { + try { + reinterpret_cast(index)->range_search( + n, + x, + radius, + reinterpret_cast(result)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_assign( + FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + idx_t* labels, + idx_t k) { + try { + reinterpret_cast(index)->assign(n, x, labels, k); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_reset(FaissIndexBinary* index) { + try { + reinterpret_cast(index)->reset(); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_remove_ids( + FaissIndexBinary* index, + const FaissIDSelector* sel, + size_t* n_removed) { + try { + size_t n{reinterpret_cast(index)->remove_ids( + *reinterpret_cast(sel))}; + if (n_removed) { + *n_removed = n; + } + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_reconstruct( + const FaissIndexBinary* index, + idx_t key, + uint8_t* recons) { + try { + reinterpret_cast(index)->reconstruct( + key, recons); + } + CATCH_AND_HANDLE +} + +int faiss_IndexBinary_reconstruct_n( + const FaissIndexBinary* index, + idx_t i0, + idx_t ni, + uint8_t* recons) { + try { + reinterpret_cast(index)->reconstruct_n( + i0, ni, recons); + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/IndexBinary_c.h b/c_api/IndexBinary_c.h new file mode 100644 index 0000000..84e6e00 --- /dev/null +++ b/c_api/IndexBinary_c.h @@ -0,0 +1,170 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c -*- + +#ifndef FAISS_INDEX_BINARY_C_H +#define FAISS_INDEX_BINARY_C_H + +#include +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// forward declaration required here +FAISS_DECLARE_CLASS(RangeSearchResult) + +// typedef struct FaissRangeSearchResult_H FaissRangeSearchResult; +typedef struct FaissIDSelector_H FaissIDSelector; + +/// Opaque type for referencing to a binary index object +FAISS_DECLARE_CLASS(IndexBinary) +FAISS_DECLARE_DESTRUCTOR(IndexBinary) + +/// Getter for d +FAISS_DECLARE_GETTER(IndexBinary, int, d) + +/// Getter for is_trained +FAISS_DECLARE_GETTER(IndexBinary, int, is_trained) + +/// Getter for ntotal +FAISS_DECLARE_GETTER(IndexBinary, idx_t, ntotal) + +/// Getter for metric_type +FAISS_DECLARE_GETTER(IndexBinary, FaissMetricType, metric_type) + +FAISS_DECLARE_GETTER_SETTER(IndexBinary, int, verbose) + +/** Perform training on a representative set of vectors + * + * @param index opaque pointer to index object + * @param n nb of training vectors + * @param x training vectors, size n * d + */ +int faiss_IndexBinary_train(FaissIndexBinary* index, idx_t n, const uint8_t* x); + +/** Add n vectors of dimension d to the index. + * + * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1 + * This function slices the input vectors in chunks smaller than + * blocksize_add and calls add_core. + * @param index opaque pointer to index object + * @param x input matrix, size n * d + */ +int faiss_IndexBinary_add(FaissIndexBinary* index, idx_t n, const uint8_t* x); + +/** Same as add, but stores xids instead of sequential ids. + * + * The default implementation fails with an assertion, as it is + * not supported by all indexes. + * + * @param index opaque pointer to index object + * @param xids if non-null, ids to store for the vectors (size n) + */ +int faiss_IndexBinary_add_with_ids( + FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + const idx_t* xids); + +/** query n vectors of dimension d to the index. + * + * return at most k vectors. If there are not enough results for a + * query, the result array is padded with -1s. + * + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param labels output labels of the NNs, size n*k + * @param distances output pairwise distances, size n*k + */ +int faiss_IndexBinary_search( + const FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + idx_t k, + int32_t* distances, + idx_t* labels); + +/** query n vectors of dimension d to the index. + * + * return all vectors with distance < radius. Note that many + * indexes do not implement the range_search (only the k-NN search + * is mandatory). + * + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param radius search radius + * @param result result table + */ +int faiss_IndexBinary_range_search( + const FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + int radius, + FaissRangeSearchResult* result); + +/** return the indexes of the k vectors closest to the query x. + * + * This function is identical as search but only return labels of neighbors. + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param labels output labels of the NNs, size n*k + */ +int faiss_IndexBinary_assign( + FaissIndexBinary* index, + idx_t n, + const uint8_t* x, + idx_t* labels, + idx_t k); + +/** removes all elements from the database. + * @param index opaque pointer to index object + */ +int faiss_IndexBinary_reset(FaissIndexBinary* index); + +/** removes IDs from the index. Not supported by all indexes + * @param index opaque pointer to index object + * @param nremove output for the number of IDs removed + */ +int faiss_IndexBinary_remove_ids( + FaissIndexBinary* index, + const FaissIDSelector* sel, + size_t* n_removed); + +/** Reconstruct a stored vector (or an approximation if lossy coding) + * + * this function may not be defined for some indexes + * @param index opaque pointer to index object + * @param key id of the vector to reconstruct + * @param recons reconstructed vector (size d) + */ +int faiss_IndexBinary_reconstruct( + const FaissIndexBinary* index, + idx_t key, + uint8_t* recons); + +/** Reconstruct vectors i0 to i0 + ni - 1 + * + * this function may not be defined for some indexes + * @param index opaque pointer to index object + * @param recons reconstructed vector (size ni * d) + */ +int faiss_IndexBinary_reconstruct_n( + const FaissIndexBinary* index, + idx_t i0, + idx_t ni, + uint8_t* recons); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexFlat_c.cpp b/c_api/IndexFlat_c.cpp new file mode 100644 index 0000000..2d0cbb6 --- /dev/null +++ b/c_api/IndexFlat_c.cpp @@ -0,0 +1,166 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexFlat_c.h" +#include +#include +#include "macros_impl.h" + +extern "C" { + +using faiss::Index; +using faiss::IndexFlat; +using faiss::IndexFlat1D; +using faiss::IndexFlatIP; +using faiss::IndexFlatL2; +using faiss::IndexRefineFlat; + +DEFINE_DESTRUCTOR(IndexFlat) +DEFINE_INDEX_DOWNCAST(IndexFlat) + +int faiss_IndexFlat_new(FaissIndexFlat** p_index) { + try { + *p_index = reinterpret_cast(new IndexFlat()); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexFlat_new_with( + FaissIndexFlat** p_index, + idx_t d, + FaissMetricType metric) { + try { + IndexFlat* index = + new IndexFlat(d, static_cast(metric)); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +void faiss_IndexFlat_xb(FaissIndexFlat* index, float** p_xb, size_t* p_size) { + IndexFlat* indexf = reinterpret_cast(index); + *p_xb = indexf->get_xb(); + if (p_size) { + *p_size = indexf->codes.size() / sizeof(float); + } +} + +int faiss_IndexFlat_compute_distance_subset( + FaissIndex* index, + idx_t n, + const float* x, + idx_t k, + float* distances, + const idx_t* labels) { + try { + reinterpret_cast(index)->compute_distance_subset( + n, x, k, distances, labels); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(IndexFlatIP) +DEFINE_INDEX_DOWNCAST(IndexFlatIP) + +int faiss_IndexFlatIP_new(FaissIndexFlatIP** p_index) { + try { + IndexFlatIP* index = new IndexFlatIP(); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexFlatIP_new_with(FaissIndexFlatIP** p_index, idx_t d) { + try { + IndexFlatIP* index = new IndexFlatIP(d); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(IndexFlatL2) +DEFINE_INDEX_DOWNCAST(IndexFlatL2) + +int faiss_IndexFlatL2_new(FaissIndexFlatL2** p_index) { + try { + IndexFlatL2* index = new IndexFlatL2(); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexFlatL2_new_with(FaissIndexFlatL2** p_index, idx_t d) { + try { + IndexFlatL2* index = new IndexFlatL2(d); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexRefineFlat_new( + FaissIndexRefineFlat** p_index, + FaissIndex* base_index) { + try { + IndexRefineFlat* index = new IndexRefineFlat( + reinterpret_cast(base_index)); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(IndexRefineFlat) +DEFINE_INDEX_DOWNCAST(IndexRefineFlat) + +DEFINE_GETTER(IndexRefineFlat, int, own_fields) +DEFINE_SETTER(IndexRefineFlat, int, own_fields) + +DEFINE_GETTER(IndexRefineFlat, float, k_factor) +DEFINE_SETTER(IndexRefineFlat, float, k_factor) + +DEFINE_DESTRUCTOR(IndexFlat1D) +DEFINE_INDEX_DOWNCAST(IndexFlat1D) + +int faiss_IndexFlat1D_new(FaissIndexFlat1D** p_index) { + try { + IndexFlat1D* index = new IndexFlat1D(); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexFlat1D_new_with( + FaissIndexFlat1D** p_index, + int continuous_update) { + try { + IndexFlat1D* index = + new IndexFlat1D(static_cast(continuous_update)); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexFlat1D_update_permutation(FaissIndexFlat1D* index) { + try { + reinterpret_cast(index)->update_permutation(); + return 0; + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/IndexFlat_c.h b/c_api/IndexFlat_c.h new file mode 100644 index 0000000..16f70e4 --- /dev/null +++ b/c_api/IndexFlat_c.h @@ -0,0 +1,130 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c -*- + +#ifndef FAISS_INDEX_FLAT_C_H +#define FAISS_INDEX_FLAT_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// forward declaration +typedef enum FaissMetricType FaissMetricType; + +/** Opaque type for IndexFlat */ +FAISS_DECLARE_CLASS_INHERITED(IndexFlat, Index) + +int faiss_IndexFlat_new(FaissIndexFlat** p_index); + +int faiss_IndexFlat_new_with( + FaissIndexFlat** p_index, + idx_t d, + FaissMetricType metric); + +/** get a pointer to the index's internal data (the `xb` field). The outputs + * become invalid after any data addition or removal operation. + * + * @param index opaque pointer to index object + * @param p_xb output, the pointer to the beginning of `xb`. + * @param p_size output, the current size of `sb` in number of float values. + */ +void faiss_IndexFlat_xb(FaissIndexFlat* index, float** p_xb, size_t* p_size); + +/** attempt a dynamic cast to a flat index, thus checking + * check whether the underlying index type is `IndexFlat`. + * + * @param index opaque pointer to index object + * @return the same pointer if the index is a flat index, NULL otherwise + */ +FAISS_DECLARE_INDEX_DOWNCAST(IndexFlat) + +FAISS_DECLARE_DESTRUCTOR(IndexFlat) + +/** compute distance with a subset of vectors + * + * @param index opaque pointer to index object + * @param x query vectors, size n * d + * @param labels indices of the vectors that should be compared + * for each query vector, size n * k + * @param distances + * corresponding output distances, size n * k + */ +int faiss_IndexFlat_compute_distance_subset( + FaissIndex* index, + idx_t n, + const float* x, + idx_t k, + float* distances, + const idx_t* labels); + +/** Opaque type for IndexFlatIP */ +FAISS_DECLARE_CLASS_INHERITED(IndexFlatIP, Index) + +FAISS_DECLARE_INDEX_DOWNCAST(IndexFlatIP) +FAISS_DECLARE_DESTRUCTOR(IndexFlatIP) + +int faiss_IndexFlatIP_new(FaissIndexFlatIP** p_index); + +int faiss_IndexFlatIP_new_with(FaissIndexFlatIP** p_index, idx_t d); + +/** Opaque type for IndexFlatL2 */ +FAISS_DECLARE_CLASS_INHERITED(IndexFlatL2, Index) + +FAISS_DECLARE_INDEX_DOWNCAST(IndexFlatL2) +FAISS_DECLARE_DESTRUCTOR(IndexFlatL2) + +int faiss_IndexFlatL2_new(FaissIndexFlatL2** p_index); + +int faiss_IndexFlatL2_new_with(FaissIndexFlatL2** p_index, idx_t d); + +/** Opaque type for IndexRefineFlat + * + * Index that queries in a base_index (a fast one) and refines the + * results with an exact search, hopefully improving the results. + */ +FAISS_DECLARE_CLASS_INHERITED(IndexRefineFlat, Index) + +int faiss_IndexRefineFlat_new( + FaissIndexRefineFlat** p_index, + FaissIndex* base_index); + +FAISS_DECLARE_DESTRUCTOR(IndexRefineFlat) +FAISS_DECLARE_INDEX_DOWNCAST(IndexRefineFlat) + +FAISS_DECLARE_GETTER_SETTER(IndexRefineFlat, int, own_fields) + +/// factor between k requested in search and the k requested from +/// the base_index (should be >= 1) +FAISS_DECLARE_GETTER_SETTER(IndexRefineFlat, float, k_factor) + +/** Opaque type for IndexFlat1D + * + * optimized version for 1D "vectors" + */ +FAISS_DECLARE_CLASS_INHERITED(IndexFlat1D, Index) + +FAISS_DECLARE_INDEX_DOWNCAST(IndexFlat1D) +FAISS_DECLARE_DESTRUCTOR(IndexFlat1D) + +int faiss_IndexFlat1D_new(FaissIndexFlat1D** p_index); +int faiss_IndexFlat1D_new_with( + FaissIndexFlat1D** p_index, + int continuous_update); + +int faiss_IndexFlat1D_update_permutation(FaissIndexFlat1D* index); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexIVFFlat_c.cpp b/c_api/IndexIVFFlat_c.cpp new file mode 100644 index 0000000..69f113a --- /dev/null +++ b/c_api/IndexIVFFlat_c.cpp @@ -0,0 +1,101 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexIVFFlat_c.h" +#include +#include "Clustering_c.h" +#include "Index_c.h" +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexIVFFlat; +using faiss::MetricType; + +DEFINE_DESTRUCTOR(IndexIVFFlat) +DEFINE_INDEX_DOWNCAST(IndexIVFFlat) + +/// number of possible key values +DEFINE_GETTER(IndexIVFFlat, size_t, nlist) +/// number of probes at query time +DEFINE_GETTER(IndexIVFFlat, size_t, nprobe) +DEFINE_SETTER(IndexIVFFlat, size_t, nprobe) + +/// quantizer that maps vectors to inverted lists +DEFINE_GETTER_PERMISSIVE(IndexIVFFlat, FaissIndex*, quantizer) + +/** + * = 0: use the quantizer as index in a kmeans training + * = 1: just pass on the training set to the train() of the quantizer + * = 2: kmeans training on a flat index + add the centroids to the quantizer + */ +DEFINE_GETTER(IndexIVFFlat, char, quantizer_trains_alone) + +/// whether object owns the quantizer +DEFINE_GETTER(IndexIVFFlat, int, own_fields) +DEFINE_SETTER(IndexIVFFlat, int, own_fields) + +int faiss_IndexIVFFlat_new(FaissIndexIVFFlat** p_index) { + try { + *p_index = reinterpret_cast(new IndexIVFFlat()); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFFlat_new_with( + FaissIndexIVFFlat** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist) { + try { + auto q = reinterpret_cast(quantizer); + *p_index = reinterpret_cast( + new IndexIVFFlat(q, d, nlist)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFFlat_new_with_metric( + FaissIndexIVFFlat** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist, + FaissMetricType metric) { + try { + auto q = reinterpret_cast(quantizer); + auto m = static_cast(metric); + *p_index = reinterpret_cast( + new IndexIVFFlat(q, d, nlist, m)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFFlat_add_core( + FaissIndexIVFFlat* index, + idx_t n, + const float* x, + const idx_t* xids, + const int64_t* precomputed_idx) { + try { + reinterpret_cast(index)->add_core( + n, x, xids, precomputed_idx); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFFlat_update_vectors( + FaissIndexIVFFlat* index, + int nv, + idx_t* idx, + const float* v) { + try { + reinterpret_cast(index)->update_vectors(nv, idx, v); + } + CATCH_AND_HANDLE +} diff --git a/c_api/IndexIVFFlat_c.h b/c_api/IndexIVFFlat_c.h new file mode 100644 index 0000000..7ea35da --- /dev/null +++ b/c_api/IndexIVFFlat_c.h @@ -0,0 +1,86 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_INDEX_IVF_FLAT_C_H +#define FAISS_INDEX_IVF_FLAT_C_H + +#include "Clustering_c.h" +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Inverted file with stored vectors. Here the inverted file + * pre-selects the vectors to be searched, but they are not otherwise + * encoded, the code array just contains the raw float entries. + */ +FAISS_DECLARE_CLASS_INHERITED(IndexIVFFlat, Index) +FAISS_DECLARE_DESTRUCTOR(IndexIVFFlat) +FAISS_DECLARE_INDEX_DOWNCAST(IndexIVFFlat) + +/// number of possible key values +FAISS_DECLARE_GETTER(IndexIVFFlat, size_t, nlist) +/// number of probes at query time +FAISS_DECLARE_GETTER_SETTER(IndexIVFFlat, size_t, nprobe) +/// quantizer that maps vectors to inverted lists +FAISS_DECLARE_GETTER(IndexIVFFlat, FaissIndex*, quantizer) +/** + * = 0: use the quantizer as index in a kmeans training + * = 1: just pass on the training set to the train() of the quantizer + * = 2: kmeans training on a flat index + add the centroids to the quantizer + */ +FAISS_DECLARE_GETTER(IndexIVFFlat, char, quantizer_trains_alone) + +/// whether object owns the quantizer +FAISS_DECLARE_GETTER_SETTER(IndexIVFFlat, int, own_fields) + +int faiss_IndexIVFFlat_new(FaissIndexIVFFlat** p_index); + +int faiss_IndexIVFFlat_new_with( + FaissIndexIVFFlat** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist); + +int faiss_IndexIVFFlat_new_with_metric( + FaissIndexIVFFlat** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist, + FaissMetricType metric); + +int faiss_IndexIVFFlat_add_core( + FaissIndexIVFFlat* index, + idx_t n, + const float* x, + const idx_t* xids, + const int64_t* precomputed_idx); + +/** Update a subset of vectors. + * + * The index must have a direct_map + * + * @param nv nb of vectors to update + * @param idx vector indices to update, size nv + * @param v vectors of new values, size nv*d + */ +int faiss_IndexIVFFlat_update_vectors( + FaissIndexIVFFlat* index, + int nv, + idx_t* idx, + const float* v); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexIVF_c.cpp b/c_api/IndexIVF_c.cpp new file mode 100644 index 0000000..768a3d8 --- /dev/null +++ b/c_api/IndexIVF_c.cpp @@ -0,0 +1,131 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexIVF_c.h" +#include +#include "Clustering_c.h" +#include "Index_c.h" +#include "macros_impl.h" + +using faiss::IndexIVF; +using faiss::IndexIVFStats; + +DEFINE_DESTRUCTOR(IndexIVF) +DEFINE_INDEX_DOWNCAST(IndexIVF) + +/// number of possible key values +DEFINE_GETTER(IndexIVF, size_t, nlist) +/// number of probes at query time +DEFINE_GETTER(IndexIVF, size_t, nprobe) +DEFINE_SETTER(IndexIVF, size_t, nprobe) + +/// quantizer that maps vectors to inverted lists +DEFINE_GETTER_PERMISSIVE(IndexIVF, FaissIndex*, quantizer) + +/** + * = 0: use the quantizer as index in a kmeans training + * = 1: just pass on the training set to the train() of the quantizer + * = 2: kmeans training on a flat index + add the centroids to the quantizer + */ +DEFINE_GETTER(IndexIVF, char, quantizer_trains_alone) + +/// whether object owns the quantizer +DEFINE_GETTER(IndexIVF, int, own_fields) +DEFINE_SETTER(IndexIVF, int, own_fields) + +using faiss::IndexIVF; + +int faiss_IndexIVF_merge_from( + FaissIndexIVF* index, + FaissIndexIVF* other, + idx_t add_id) { + try { + reinterpret_cast(index)->merge_from( + *reinterpret_cast(other), add_id); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVF_copy_subset_to( + const FaissIndexIVF* index, + FaissIndexIVF* other, + int subset_type, + idx_t a1, + idx_t a2) { + try { + reinterpret_cast(index)->copy_subset_to( + *reinterpret_cast(other), subset_type, a1, a2); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVF_search_preassigned( + const FaissIndexIVF* index, + idx_t n, + const float* x, + idx_t k, + const idx_t* assign, + const float* centroid_dis, + float* distances, + idx_t* labels, + int store_pairs) { + try { + reinterpret_cast(index)->search_preassigned( + n, x, k, assign, centroid_dis, distances, labels, store_pairs); + } + CATCH_AND_HANDLE +} + +size_t faiss_IndexIVF_get_list_size( + const FaissIndexIVF* index, + size_t list_no) { + return reinterpret_cast(index)->get_list_size(list_no); +} + +int faiss_IndexIVF_make_direct_map( + FaissIndexIVF* index, + int new_maintain_direct_map) { + try { + reinterpret_cast(index)->make_direct_map( + static_cast(new_maintain_direct_map)); + } + CATCH_AND_HANDLE +} + +double faiss_IndexIVF_imbalance_factor(const FaissIndexIVF* index) { + return reinterpret_cast(index) + ->invlists->imbalance_factor(); +} + +/// display some stats about the inverted lists +void faiss_IndexIVF_print_stats(const FaissIndexIVF* index) { + reinterpret_cast(index)->invlists->print_stats(); +} + +/// get inverted lists ids +void faiss_IndexIVF_invlists_get_ids( + const FaissIndexIVF* index, + size_t list_no, + idx_t* invlist) { + const idx_t* list = + reinterpret_cast(index)->invlists->get_ids( + list_no); + size_t list_size = + reinterpret_cast(index)->get_list_size(list_no); + memcpy(invlist, list, list_size * sizeof(idx_t)); +} + +void faiss_IndexIVFStats_reset(FaissIndexIVFStats* stats) { + reinterpret_cast(stats)->reset(); +} + +FaissIndexIVFStats* faiss_get_indexIVF_stats() { + return reinterpret_cast(&faiss::indexIVF_stats); +} diff --git a/c_api/IndexIVF_c.h b/c_api/IndexIVF_c.h new file mode 100644 index 0000000..4d6f1d6 --- /dev/null +++ b/c_api/IndexIVF_c.h @@ -0,0 +1,163 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_INDEX_IVF_C_H +#define FAISS_INDEX_IVF_C_H + +#include "Clustering_c.h" +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Index based on a inverted file (IVF) + * + * In the inverted file, the quantizer (an Index instance) provides a + * quantization index for each vector to be added. The quantization + * index maps to a list (aka inverted list or posting list), where the + * id of the vector is then stored. + * + * At search time, the vector to be searched is also quantized, and + * only the list corresponding to the quantization index is + * searched. This speeds up the search by making it + * non-exhaustive. This can be relaxed using multi-probe search: a few + * (nprobe) quantization indices are selected and several inverted + * lists are visited. + * + * Sub-classes implement a post-filtering of the index that refines + * the distance estimation from the query to database vectors. + */ +FAISS_DECLARE_CLASS_INHERITED(IndexIVF, Index) +FAISS_DECLARE_DESTRUCTOR(IndexIVF) +FAISS_DECLARE_INDEX_DOWNCAST(IndexIVF) + +/// number of possible key values +FAISS_DECLARE_GETTER(IndexIVF, size_t, nlist) +/// number of probes at query time +FAISS_DECLARE_GETTER_SETTER(IndexIVF, size_t, nprobe) +/// quantizer that maps vectors to inverted lists +FAISS_DECLARE_GETTER(IndexIVF, FaissIndex*, quantizer) +/** + * = 0: use the quantizer as index in a kmeans training + * = 1: just pass on the training set to the train() of the quantizer + * = 2: kmeans training on a flat index + add the centroids to the quantizer + */ +FAISS_DECLARE_GETTER(IndexIVF, char, quantizer_trains_alone) + +/// whether object owns the quantizer +FAISS_DECLARE_GETTER_SETTER(IndexIVF, int, own_fields) + +/** moves the entries from another dataset to self. On output, + * other is empty. add_id is added to all moved ids (for + * sequential ids, this would be this->ntotal */ +int faiss_IndexIVF_merge_from( + FaissIndexIVF* index, + FaissIndexIVF* other, + idx_t add_id); + +/** copy a subset of the entries index to the other index + * + * if subset_type == 0: copies ids in [a1, a2) + * if subset_type == 1: copies ids if id % a1 == a2 + * if subset_type == 2: copies inverted lists such that a1 + * elements are left before and a2 elements are after + */ +int faiss_IndexIVF_copy_subset_to( + const FaissIndexIVF* index, + FaissIndexIVF* other, + int subset_type, + idx_t a1, + idx_t a2); + +/** search a set of vectors, that are pre-quantized by the IVF + * quantizer. Fill in the corresponding heaps with the query + * results. search() calls this. + * + * @param n nb of vectors to query + * @param x query vectors, size nx * d + * @param assign coarse quantization indices, size nx * nprobe + * @param centroid_dis + * distances to coarse centroids, size nx * nprobe + * @param distance + * output distances, size n * k + * @param labels output labels, size n * k + * @param store_pairs store inv list index + inv list offset + * instead in upper/lower 32 bit of result, + * instead of ids (used for reranking). + */ +int faiss_IndexIVF_search_preassigned( + const FaissIndexIVF* index, + idx_t n, + const float* x, + idx_t k, + const idx_t* assign, + const float* centroid_dis, + float* distances, + idx_t* labels, + int store_pairs); + +size_t faiss_IndexIVF_get_list_size(const FaissIndexIVF* index, size_t list_no); + +/** initialize a direct map + * + * @param new_maintain_direct_map if true, create a direct map, + * else clear it + */ +int faiss_IndexIVF_make_direct_map( + FaissIndexIVF* index, + int new_maintain_direct_map); + +/** Check the inverted lists' imbalance factor. + * + * 1= perfectly balanced, >1: imbalanced + */ +double faiss_IndexIVF_imbalance_factor(const FaissIndexIVF* index); + +/// display some stats about the inverted lists of the index +void faiss_IndexIVF_print_stats(const FaissIndexIVF* index); + +/// Get the IDs in an inverted list. IDs are written to `invlist`, which must be +/// large enough +//// to accommodate the full list. +/// +/// @param list_no the list ID +/// @param invlist output pointer to a slice of memory, at least as long as the +/// list's size +/// @see faiss_IndexIVF_get_list_size(size_t) +void faiss_IndexIVF_invlists_get_ids( + const FaissIndexIVF* index, + size_t list_no, + idx_t* invlist); + +typedef struct FaissIndexIVFStats { + size_t nq; // nb of queries run + size_t nlist; // nb of inverted lists scanned + size_t ndis; // nb of distances computed + size_t nheap_updates; // nb of times the heap was updated + double quantization_time; // time spent quantizing vectors (in ms) + double search_time; // time spent searching lists (in ms) +} FaissIndexIVFStats; + +void faiss_IndexIVFStats_reset(FaissIndexIVFStats* stats); + +inline void faiss_IndexIVFStats_init(FaissIndexIVFStats* stats) { + faiss_IndexIVFStats_reset(stats); +} + +/// global var that collects all statists +FaissIndexIVFStats* faiss_get_indexIVF_stats(); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexLSH_c.cpp b/c_api/IndexLSH_c.cpp new file mode 100644 index 0000000..b63d967 --- /dev/null +++ b/c_api/IndexLSH_c.cpp @@ -0,0 +1,47 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexLSH_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexLSH; + +DEFINE_DESTRUCTOR(IndexLSH) +DEFINE_INDEX_DOWNCAST(IndexLSH) + +DEFINE_GETTER(IndexLSH, int, nbits) +DEFINE_GETTER(IndexLSH, int, code_size) +DEFINE_GETTER_PERMISSIVE(IndexLSH, int, rotate_data) +DEFINE_GETTER_PERMISSIVE(IndexLSH, int, train_thresholds) + +int faiss_IndexLSH_new(FaissIndexLSH** p_index, idx_t d, int nbits) { + try { + *p_index = reinterpret_cast(new IndexLSH(d, nbits)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexLSH_new_with_options( + FaissIndexLSH** p_index, + idx_t d, + int nbits, + int rotate_data, + int train_thresholds) { + try { + *p_index = reinterpret_cast(new IndexLSH( + d, + nbits, + static_cast(rotate_data), + static_cast(train_thresholds))); + } + CATCH_AND_HANDLE +} diff --git a/c_api/IndexLSH_c.h b/c_api/IndexLSH_c.h new file mode 100644 index 0000000..602c191 --- /dev/null +++ b/c_api/IndexLSH_c.h @@ -0,0 +1,45 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#ifndef INDEX_LSH_C_H +#define INDEX_LSH_C_H + +#include "Clustering_c.h" +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** The sign of each vector component is put in a binary signature */ +FAISS_DECLARE_CLASS_INHERITED(IndexLSH, Index) +FAISS_DECLARE_DESTRUCTOR(IndexLSH) +FAISS_DECLARE_INDEX_DOWNCAST(IndexLSH) + +FAISS_DECLARE_GETTER(IndexLSH, int, nbits) +FAISS_DECLARE_GETTER(IndexLSH, int, code_size) +FAISS_DECLARE_GETTER(IndexLSH, int, rotate_data) +FAISS_DECLARE_GETTER(IndexLSH, int, train_thresholds) + +int faiss_IndexLSH_new(FaissIndexLSH** p_index, idx_t d, int nbits); + +int faiss_IndexLSH_new_with_options( + FaissIndexLSH** p_index, + idx_t d, + int nbits, + int rotate_data, + int train_thresholds); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexPreTransform_c.cpp b/c_api/IndexPreTransform_c.cpp new file mode 100644 index 0000000..5930eb1 --- /dev/null +++ b/c_api/IndexPreTransform_c.cpp @@ -0,0 +1,71 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexPreTransform_c.h" +#include +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexPreTransform; +using faiss::VectorTransform; + +extern "C" { + +DEFINE_DESTRUCTOR(IndexPreTransform) +DEFINE_INDEX_DOWNCAST(IndexPreTransform) + +DEFINE_GETTER_PERMISSIVE(IndexPreTransform, FaissIndex*, index) + +DEFINE_GETTER(IndexPreTransform, int, own_fields) +DEFINE_SETTER(IndexPreTransform, int, own_fields) + +int faiss_IndexPreTransform_new(FaissIndexPreTransform** p_index) { + try { + *p_index = reinterpret_cast( + new IndexPreTransform()); + } + CATCH_AND_HANDLE +} + +int faiss_IndexPreTransform_new_with( + FaissIndexPreTransform** p_index, + FaissIndex* index) { + try { + auto ind = reinterpret_cast(index); + *p_index = reinterpret_cast( + new IndexPreTransform(ind)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexPreTransform_new_with_transform( + FaissIndexPreTransform** p_index, + FaissVectorTransform* ltrans, + FaissIndex* index) { + try { + auto lt = reinterpret_cast(ltrans); + auto ind = reinterpret_cast(index); + *p_index = reinterpret_cast( + new IndexPreTransform(lt, ind)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexPreTransform_prepend_transform( + FaissIndexPreTransform* index, + FaissVectorTransform* ltrans) { + try { + auto lt = reinterpret_cast(ltrans); + reinterpret_cast(index)->prepend_transform(lt); + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/IndexPreTransform_c.h b/c_api/IndexPreTransform_c.h new file mode 100644 index 0000000..0e55289 --- /dev/null +++ b/c_api/IndexPreTransform_c.h @@ -0,0 +1,50 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_INDEX_PRETRANSFORM_C_H +#define FAISS_INDEX_PRETRANSFORM_C_H + +#include "Index_c.h" +#include "VectorTransform_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Index that applies a LinearTransform transform on vectors before + * handing them over to a sub-index */ +FAISS_DECLARE_CLASS_INHERITED(IndexPreTransform, Index) +FAISS_DECLARE_DESTRUCTOR(IndexPreTransform) +FAISS_DECLARE_INDEX_DOWNCAST(IndexPreTransform) + +FAISS_DECLARE_GETTER(IndexPreTransform, FaissIndex*, index) +FAISS_DECLARE_GETTER_SETTER(IndexPreTransform, int, own_fields) + +int faiss_IndexPreTransform_new(FaissIndexPreTransform** p_index); + +int faiss_IndexPreTransform_new_with( + FaissIndexPreTransform** p_index, + FaissIndex* index); + +int faiss_IndexPreTransform_new_with_transform( + FaissIndexPreTransform** p_index, + FaissVectorTransform* ltrans, + FaissIndex* index); + +int faiss_IndexPreTransform_prepend_transform( + FaissIndexPreTransform* index, + FaissVectorTransform* ltrans); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexReplicas_c.cpp b/c_api/IndexReplicas_c.cpp new file mode 100644 index 0000000..37b42a5 --- /dev/null +++ b/c_api/IndexReplicas_c.cpp @@ -0,0 +1,62 @@ +/** + * 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. + */ + +#include "IndexReplicas_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexReplicas; + +DEFINE_DESTRUCTOR(IndexReplicas) + +DEFINE_GETTER(IndexReplicas, int, own_fields) +DEFINE_SETTER(IndexReplicas, int, own_fields) + +int faiss_IndexReplicas_new(FaissIndexReplicas** p_index, idx_t d) { + try { + auto out = new IndexReplicas(d); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_IndexReplicas_new_with_options( + FaissIndexReplicas** p_index, + idx_t d, + int threaded) { + try { + auto out = new IndexReplicas(d, static_cast(threaded)); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_IndexReplicas_add_replica( + FaissIndexReplicas* index, + FaissIndex* replica) { + try { + reinterpret_cast(index)->add_replica( + reinterpret_cast(replica)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexReplicas_remove_replica( + FaissIndexReplicas* index, + FaissIndex* replica) { + try { + reinterpret_cast(index)->remove_replica( + reinterpret_cast(replica)); + } + CATCH_AND_HANDLE +} + +FaissIndex* faiss_IndexReplicas_at(FaissIndexReplicas* index, int i) { + auto replica = reinterpret_cast(index)->at(i); + return reinterpret_cast(replica); +} diff --git a/c_api/IndexReplicas_c.h b/c_api/IndexReplicas_c.h new file mode 100644 index 0000000..3d14eee --- /dev/null +++ b/c_api/IndexReplicas_c.h @@ -0,0 +1,48 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#ifndef INDEXREPLICAS_C_H +#define INDEXREPLICAS_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Index that concatenates the results from several sub-indexes + */ +FAISS_DECLARE_CLASS_INHERITED(IndexReplicas, Index) +FAISS_DECLARE_DESTRUCTOR(IndexReplicas) + +FAISS_DECLARE_GETTER_SETTER(IndexReplicas, int, own_fields) + +int faiss_IndexReplicas_new(FaissIndexReplicas** p_index, idx_t d); + +int faiss_IndexReplicas_new_with_options( + FaissIndexReplicas** p_index, + idx_t d, + int threaded); + +int faiss_IndexReplicas_add_replica( + FaissIndexReplicas* index, + FaissIndex* replica); + +int faiss_IndexReplicas_remove_replica( + FaissIndexReplicas* index, + FaissIndex* replica); + +FaissIndex* faiss_IndexReplicas_at(FaissIndexReplicas* index, int i); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/IndexScalarQuantizer_c.cpp b/c_api/IndexScalarQuantizer_c.cpp new file mode 100644 index 0000000..5c00e34 --- /dev/null +++ b/c_api/IndexScalarQuantizer_c.cpp @@ -0,0 +1,122 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "IndexScalarQuantizer_c.h" +#include +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexIVFScalarQuantizer; +using faiss::IndexScalarQuantizer; + +DEFINE_DESTRUCTOR(IndexScalarQuantizer) +DEFINE_INDEX_DOWNCAST(IndexScalarQuantizer) + +int faiss_IndexScalarQuantizer_new(FaissIndexScalarQuantizer** p_index) { + try { + *p_index = reinterpret_cast( + new IndexScalarQuantizer()); + } + CATCH_AND_HANDLE +} + +int faiss_IndexScalarQuantizer_new_with( + FaissIndexScalarQuantizer** p_index, + idx_t d, + FaissQuantizerType qt, + FaissMetricType metric) { + try { + IndexScalarQuantizer* index = new IndexScalarQuantizer( + d, + static_cast(qt), + static_cast(metric)); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(IndexIVFScalarQuantizer) +DEFINE_INDEX_DOWNCAST(IndexIVFScalarQuantizer) + +/// quantizer that maps vectors to inverted lists +DEFINE_GETTER_PERMISSIVE(IndexIVFScalarQuantizer, FaissIndex*, quantizer) + +/// number of possible key values +DEFINE_GETTER(IndexIVFScalarQuantizer, size_t, nlist) +/// number of probes at query time +DEFINE_GETTER(IndexIVFScalarQuantizer, size_t, nprobe) +DEFINE_SETTER(IndexIVFScalarQuantizer, size_t, nprobe) + +/// whether object owns the quantizer +DEFINE_GETTER(IndexIVFScalarQuantizer, int, own_fields) +DEFINE_SETTER(IndexIVFScalarQuantizer, int, own_fields) + +int faiss_IndexIVFScalarQuantizer_new_with( + FaissIndexIVFScalarQuantizer** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist, + FaissQuantizerType qt) { + try { + auto q = reinterpret_cast(quantizer); + auto qt_ = static_cast(qt); + IndexIVFScalarQuantizer* index = + new IndexIVFScalarQuantizer(q, d, nlist, qt_); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFScalarQuantizer_new_with_metric( + FaissIndexIVFScalarQuantizer** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist, + FaissQuantizerType qt, + FaissMetricType metric, + int encode_residual) { + try { + auto q = reinterpret_cast(quantizer); + auto mt = static_cast(metric); + auto er = static_cast(encode_residual); + auto qt_ = static_cast(qt); + IndexIVFScalarQuantizer* index = + new IndexIVFScalarQuantizer(q, d, nlist, qt_, mt, er); + *p_index = reinterpret_cast(index); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFScalarQuantizer_add_core( + FaissIndexIVFScalarQuantizer* index, + idx_t n, + const float* x, + const idx_t* xids, + const idx_t* precomputed_idx) { + try { + reinterpret_cast(index)->add_core( + n, x, xids, precomputed_idx); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIVFScalarQuantizer_train_residual( + FaissIndexIVFScalarQuantizer* index, + idx_t n, + const float* x) { + try { + reinterpret_cast(index)->train_residual(n, x); + } + CATCH_AND_HANDLE +} diff --git a/c_api/IndexScalarQuantizer_c.h b/c_api/IndexScalarQuantizer_c.h new file mode 100644 index 0000000..becdb20 --- /dev/null +++ b/c_api/IndexScalarQuantizer_c.h @@ -0,0 +1,100 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_INDEX_SCALAR_QUANTIZER_C_H +#define FAISS_INDEX_SCALAR_QUANTIZER_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef enum FaissQuantizerType { + QT_8bit, ///< 8 bits per component + QT_4bit, ///< 4 bits per component + QT_8bit_uniform, ///< same, shared range for all dimensions + QT_4bit_uniform, + QT_fp16, + QT_8bit_direct, ///< fast indexing of uint8s + QT_6bit, ///< 6 bits per component +} FaissQuantizerType; + +// forward declaration +typedef enum FaissMetricType FaissMetricType; + +/** Opaque type for IndexScalarQuantizer */ +FAISS_DECLARE_CLASS_INHERITED(IndexScalarQuantizer, Index) + +int faiss_IndexScalarQuantizer_new(FaissIndexScalarQuantizer** p_index); + +int faiss_IndexScalarQuantizer_new_with( + FaissIndexScalarQuantizer** p_index, + idx_t d, + FaissQuantizerType qt, + FaissMetricType metric); + +FAISS_DECLARE_INDEX_DOWNCAST(IndexScalarQuantizer) + +FAISS_DECLARE_DESTRUCTOR(IndexScalarQuantizer) + +/** Opaque type for IndexIVFScalarQuantizer */ +FAISS_DECLARE_CLASS_INHERITED(IndexIVFScalarQuantizer, Index) + +FAISS_DECLARE_INDEX_DOWNCAST(IndexIVFScalarQuantizer) + +FAISS_DECLARE_DESTRUCTOR(IndexIVFScalarQuantizer) + +int faiss_IndexIVFScalarQuantizer_new(FaissIndexIVFScalarQuantizer** p_index); + +int faiss_IndexIVFScalarQuantizer_new_with( + FaissIndexIVFScalarQuantizer** p_index, + FaissIndex* quantizer, + idx_t d, + size_t nlist, + FaissQuantizerType qt); + +int faiss_IndexIVFScalarQuantizer_new_with_metric( + FaissIndexIVFScalarQuantizer** p_index, + FaissIndex* quantizer, + size_t d, + size_t nlist, + FaissQuantizerType qt, + FaissMetricType metric, + int encode_residual); + +/// number of possible key values +FAISS_DECLARE_GETTER(IndexIVFScalarQuantizer, size_t, nlist) +/// number of probes at query time +FAISS_DECLARE_GETTER_SETTER(IndexIVFScalarQuantizer, size_t, nprobe) +/// quantizer that maps vectors to inverted lists +FAISS_DECLARE_GETTER(IndexIVFScalarQuantizer, FaissIndex*, quantizer) + +/// whether object owns the quantizer +FAISS_DECLARE_GETTER_SETTER(IndexIVFScalarQuantizer, int, own_fields) + +int faiss_IndexIVFScalarQuantizer_add_core( + FaissIndexIVFScalarQuantizer* index, + idx_t n, + const float* x, + const idx_t* xids, + const idx_t* precomputed_idx); + +int faiss_IndexIVFScalarQuantizer_train_residual( + FaissIndexIVFScalarQuantizer* index, + idx_t n, + const float* x); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/IndexShards_c.cpp b/c_api/IndexShards_c.cpp new file mode 100644 index 0000000..e4d2c47 --- /dev/null +++ b/c_api/IndexShards_c.cpp @@ -0,0 +1,65 @@ +/** + * 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. + */ + +#include "IndexShards_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexShards; + +DEFINE_DESTRUCTOR(IndexShards) + +DEFINE_GETTER(IndexShards, int, own_fields) +DEFINE_SETTER(IndexShards, int, own_fields) + +DEFINE_GETTER(IndexShards, int, successive_ids) +DEFINE_SETTER(IndexShards, int, successive_ids) + +int faiss_IndexShards_new(FaissIndexShards** p_index, idx_t d) { + try { + auto out = new IndexShards(d); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_IndexShards_new_with_options( + FaissIndexShards** p_index, + idx_t d, + int threaded, + int successive_ids) { + try { + auto out = new IndexShards( + d, + static_cast(threaded), + static_cast(successive_ids)); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_IndexShards_add_shard(FaissIndexShards* index, FaissIndex* shard) { + try { + reinterpret_cast(index)->add_shard( + reinterpret_cast(shard)); + } + CATCH_AND_HANDLE +} + +int faiss_IndexShards_remove_shard(FaissIndexShards* index, FaissIndex* shard) { + try { + reinterpret_cast(index)->remove_shard( + reinterpret_cast(shard)); + } + CATCH_AND_HANDLE +} + +FaissIndex* faiss_IndexShards_at(FaissIndexShards* index, int i) { + auto shard = reinterpret_cast(index)->at(i); + return reinterpret_cast(shard); +} diff --git a/c_api/IndexShards_c.h b/c_api/IndexShards_c.h new file mode 100644 index 0000000..9810890 --- /dev/null +++ b/c_api/IndexShards_c.h @@ -0,0 +1,46 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#ifndef INDEXSHARDS_C_H +#define INDEXSHARDS_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Index that concatenates the results from several sub-indexes + */ +FAISS_DECLARE_CLASS_INHERITED(IndexShards, Index) +FAISS_DECLARE_DESTRUCTOR(IndexShards) + +FAISS_DECLARE_GETTER_SETTER(IndexShards, int, own_fields) +FAISS_DECLARE_GETTER_SETTER(IndexShards, int, successive_ids) + +int faiss_IndexShards_new(FaissIndexShards** p_index, idx_t d); + +int faiss_IndexShards_new_with_options( + FaissIndexShards** p_index, + idx_t d, + int threaded, + int successive_ids); + +int faiss_IndexShards_add_shard(FaissIndexShards* index, FaissIndex* shard); + +int faiss_IndexShards_remove_shard(FaissIndexShards* index, FaissIndex* shard); + +FaissIndex* faiss_IndexShards_at(FaissIndexShards* index, int i); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/Index_c.cpp b/c_api/Index_c.cpp new file mode 100644 index 0000000..5151aca --- /dev/null +++ b/c_api/Index_c.cpp @@ -0,0 +1,190 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "Index_c.h" +#include +#include "macros_impl.h" + +extern "C" { + +DEFINE_DESTRUCTOR(Index) + +DEFINE_GETTER(Index, int, d) + +DEFINE_GETTER(Index, int, is_trained) + +DEFINE_GETTER(Index, idx_t, ntotal) + +DEFINE_GETTER(Index, FaissMetricType, metric_type) + +DEFINE_GETTER(Index, int, verbose); +DEFINE_SETTER(Index, int, verbose); + +int faiss_Index_train(FaissIndex* index, idx_t n, const float* x) { + try { + reinterpret_cast(index)->train(n, x); + } + CATCH_AND_HANDLE +} + +int faiss_Index_add(FaissIndex* index, idx_t n, const float* x) { + try { + reinterpret_cast(index)->add(n, x); + } + CATCH_AND_HANDLE +} + +int faiss_Index_add_with_ids( + FaissIndex* index, + idx_t n, + const float* x, + const idx_t* xids) { + try { + reinterpret_cast(index)->add_with_ids(n, x, xids); + } + CATCH_AND_HANDLE +} + +int faiss_Index_search( + const FaissIndex* index, + idx_t n, + const float* x, + idx_t k, + float* distances, + idx_t* labels) { + try { + reinterpret_cast(index)->search( + n, x, k, distances, labels); + } + CATCH_AND_HANDLE +} + +int faiss_Index_range_search( + const FaissIndex* index, + idx_t n, + const float* x, + float radius, + FaissRangeSearchResult* result) { + try { + reinterpret_cast(index)->range_search( + n, + x, + radius, + reinterpret_cast(result)); + } + CATCH_AND_HANDLE +} + +int faiss_Index_assign( + FaissIndex* index, + idx_t n, + const float* x, + idx_t* labels, + idx_t k) { + try { + reinterpret_cast(index)->assign(n, x, labels, k); + } + CATCH_AND_HANDLE +} + +int faiss_Index_reset(FaissIndex* index) { + try { + reinterpret_cast(index)->reset(); + } + CATCH_AND_HANDLE +} + +int faiss_Index_remove_ids( + FaissIndex* index, + const FaissIDSelector* sel, + size_t* n_removed) { + try { + size_t n{reinterpret_cast(index)->remove_ids( + *reinterpret_cast(sel))}; + if (n_removed) { + *n_removed = n; + } + } + CATCH_AND_HANDLE +} + +int faiss_Index_reconstruct(const FaissIndex* index, idx_t key, float* recons) { + try { + reinterpret_cast(index)->reconstruct(key, recons); + } + CATCH_AND_HANDLE +} + +int faiss_Index_reconstruct_n( + const FaissIndex* index, + idx_t i0, + idx_t ni, + float* recons) { + try { + reinterpret_cast(index)->reconstruct_n( + i0, ni, recons); + } + CATCH_AND_HANDLE +} + +int faiss_Index_compute_residual( + const FaissIndex* index, + const float* x, + float* residual, + idx_t key) { + try { + reinterpret_cast(index)->compute_residual( + x, residual, key); + } + CATCH_AND_HANDLE +} + +int faiss_Index_compute_residual_n( + const FaissIndex* index, + idx_t n, + const float* x, + float* residuals, + const idx_t* keys) { + try { + reinterpret_cast(index)->compute_residual_n( + n, x, residuals, keys); + } + CATCH_AND_HANDLE +} + +int faiss_Index_sa_code_size(const FaissIndex* index, size_t* size) { + try { + reinterpret_cast(index)->sa_code_size(); + } + CATCH_AND_HANDLE +} + +int faiss_Index_sa_encode( + const FaissIndex* index, + idx_t n, + const float* x, + uint8_t* bytes) { + try { + reinterpret_cast(index)->sa_encode(n, x, bytes); + } + CATCH_AND_HANDLE +} + +int faiss_Index_sa_decode( + const FaissIndex* index, + idx_t n, + const uint8_t* bytes, + float* x) { + try { + reinterpret_cast(index)->sa_decode(n, bytes, x); + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/Index_c.h b/c_api/Index_c.h new file mode 100644 index 0000000..ca07ed9 --- /dev/null +++ b/c_api/Index_c.h @@ -0,0 +1,254 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c -*- + +#ifndef FAISS_INDEX_C_H +#define FAISS_INDEX_C_H + +#include +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// forward declaration required here +FAISS_DECLARE_CLASS(RangeSearchResult) + +// typedef struct FaissRangeSearchResult_H FaissRangeSearchResult; +typedef struct FaissIDSelector_H FaissIDSelector; + +/// Some algorithms support both an inner product version and a L2 search +/// version. +typedef enum FaissMetricType { + METRIC_INNER_PRODUCT = 0, ///< maximum inner product search + METRIC_L2 = 1, ///< squared L2 search + METRIC_L1, ///< L1 (aka cityblock) + METRIC_Linf, ///< infinity distance + METRIC_Lp, ///< L_p distance, p is given by metric_arg + + /// some additional metrics defined in scipy.spatial.distance + METRIC_Canberra = 20, + METRIC_BrayCurtis, + METRIC_JensenShannon, +} FaissMetricType; + +/// Opaque type for referencing to an index object +FAISS_DECLARE_CLASS(Index) +FAISS_DECLARE_DESTRUCTOR(Index) + +/// Getter for d +FAISS_DECLARE_GETTER(Index, int, d) + +/// Getter for is_trained +FAISS_DECLARE_GETTER(Index, int, is_trained) + +/// Getter for ntotal +FAISS_DECLARE_GETTER(Index, idx_t, ntotal) + +/// Getter for metric_type +FAISS_DECLARE_GETTER(Index, FaissMetricType, metric_type) + +FAISS_DECLARE_GETTER_SETTER(Index, int, verbose) + +/** Perform training on a representative set of vectors + * + * @param index opaque pointer to index object + * @param n nb of training vectors + * @param x training vectors, size n * d + */ +int faiss_Index_train(FaissIndex* index, idx_t n, const float* x); + +/** Add n vectors of dimension d to the index. + * + * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1 + * This function slices the input vectors in chunks smaller than + * blocksize_add and calls add_core. + * @param index opaque pointer to index object + * @param x input matrix, size n * d + */ +int faiss_Index_add(FaissIndex* index, idx_t n, const float* x); + +/** Same as add, but stores xids instead of sequential ids. + * + * The default implementation fails with an assertion, as it is + * not supported by all indexes. + * + * @param index opaque pointer to index object + * @param xids if non-null, ids to store for the vectors (size n) + */ +int faiss_Index_add_with_ids( + FaissIndex* index, + idx_t n, + const float* x, + const idx_t* xids); + +/** query n vectors of dimension d to the index. + * + * return at most k vectors. If there are not enough results for a + * query, the result array is padded with -1s. + * + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param labels output labels of the NNs, size n*k + * @param distances output pairwise distances, size n*k + */ +int faiss_Index_search( + const FaissIndex* index, + idx_t n, + const float* x, + idx_t k, + float* distances, + idx_t* labels); + +/** query n vectors of dimension d to the index. + * + * return all vectors with distance < radius. Note that many + * indexes do not implement the range_search (only the k-NN search + * is mandatory). + * + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param radius search radius + * @param result result table + */ +int faiss_Index_range_search( + const FaissIndex* index, + idx_t n, + const float* x, + float radius, + FaissRangeSearchResult* result); + +/** return the indexes of the k vectors closest to the query x. + * + * This function is identical as search but only return labels of neighbors. + * @param index opaque pointer to index object + * @param x input vectors to search, size n * d + * @param labels output labels of the NNs, size n*k + */ +int faiss_Index_assign( + FaissIndex* index, + idx_t n, + const float* x, + idx_t* labels, + idx_t k); + +/** removes all elements from the database. + * @param index opaque pointer to index object + */ +int faiss_Index_reset(FaissIndex* index); + +/** removes IDs from the index. Not supported by all indexes + * @param index opaque pointer to index object + * @param nremove output for the number of IDs removed + */ +int faiss_Index_remove_ids( + FaissIndex* index, + const FaissIDSelector* sel, + size_t* n_removed); + +/** Reconstruct a stored vector (or an approximation if lossy coding) + * + * this function may not be defined for some indexes + * @param index opaque pointer to index object + * @param key id of the vector to reconstruct + * @param recons reconstructed vector (size d) + */ +int faiss_Index_reconstruct(const FaissIndex* index, idx_t key, float* recons); + +/** Reconstruct vectors i0 to i0 + ni - 1 + * + * this function may not be defined for some indexes + * @param index opaque pointer to index object + * @param recons reconstructed vector (size ni * d) + */ +int faiss_Index_reconstruct_n( + const FaissIndex* index, + idx_t i0, + idx_t ni, + float* recons); + +/** Computes a residual vector after indexing encoding. + * + * The residual vector is the difference between a vector and the + * reconstruction that can be decoded from its representation in + * the index. The residual can be used for multiple-stage indexing + * methods, like IndexIVF's methods. + * + * @param index opaque pointer to index object + * @param x input vector, size d + * @param residual output residual vector, size d + * @param key encoded index, as returned by search and assign + */ +int faiss_Index_compute_residual( + const FaissIndex* index, + const float* x, + float* residual, + idx_t key); + +/** Computes a residual vector after indexing encoding. + * + * The residual vector is the difference between a vector and the + * reconstruction that can be decoded from its representation in + * the index. The residual can be used for multiple-stage indexing + * methods, like IndexIVF's methods. + * + * @param index opaque pointer to index object + * @param n number of vectors + * @param x input vector, size (n x d) + * @param residuals output residual vectors, size (n x d) + * @param keys encoded index, as returned by search and assign + */ +int faiss_Index_compute_residual_n( + const FaissIndex* index, + idx_t n, + const float* x, + float* residuals, + const idx_t* keys); + +/* The standalone codec interface */ + +/** The size of the produced codes in bytes. + * + * @param index opaque pointer to index object + * @param size the returned size in bytes + */ +int faiss_Index_sa_code_size(const FaissIndex* index, size_t* size); + +/** encode a set of vectors + * + * @param index opaque pointer to index object + * @param n number of vectors + * @param x input vectors, size n * d + * @param bytes output encoded vectors, size n * sa_code_size() + */ +int faiss_Index_sa_encode( + const FaissIndex* index, + idx_t n, + const float* x, + uint8_t* bytes); + +/** decode a set of vectors + * + * @param index opaque pointer to index object + * @param n number of vectors + * @param bytes input encoded vectors, size n * sa_code_size() + * @param x output vectors, size n * d + */ +int faiss_Index_sa_decode( + const FaissIndex* index, + idx_t n, + const uint8_t* bytes, + float* x); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/MetaIndexes_c.cpp b/c_api/MetaIndexes_c.cpp new file mode 100644 index 0000000..3b53579 --- /dev/null +++ b/c_api/MetaIndexes_c.cpp @@ -0,0 +1,82 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "MetaIndexes_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexIDMap; +using faiss::IndexIDMap2; + +DEFINE_GETTER(IndexIDMap, int, own_fields) +DEFINE_SETTER(IndexIDMap, int, own_fields) + +DEFINE_INDEX_DOWNCAST(IndexIDMap) + +DEFINE_GETTER(IndexIDMap2, int, own_fields) +DEFINE_SETTER(IndexIDMap2, int, own_fields) + +DEFINE_INDEX_DOWNCAST(IndexIDMap2) + +int faiss_IndexIDMap_new(FaissIndexIDMap** p_index, FaissIndex* index) { + try { + auto out = new IndexIDMap(reinterpret_cast(index)); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +void faiss_IndexIDMap_id_map( + FaissIndexIDMap* index, + idx_t** p_id_map, + size_t* p_size) { + auto idx = reinterpret_cast(index); + if (p_id_map) + *p_id_map = idx->id_map.data(); + if (p_size) + *p_size = idx->id_map.size(); +} + +FaissIndex* faiss_IndexIDMap_sub_index(FaissIndexIDMap* index) { + auto idx = reinterpret_cast(index); + return (FaissIndex*)reinterpret_cast(idx->index); +} + +int faiss_IndexIDMap2_new(FaissIndexIDMap2** p_index, FaissIndex* index) { + try { + auto out = new IndexIDMap2(reinterpret_cast(index)); + *p_index = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_IndexIDMap2_construct_rev_map(FaissIndexIDMap2* index) { + try { + reinterpret_cast(index)->construct_rev_map(); + } + CATCH_AND_HANDLE +} + +void faiss_IndexIDMap2_id_map( + FaissIndexIDMap2* index, + idx_t** p_id_map, + size_t* p_size) { + auto idx = reinterpret_cast(index); + if (p_id_map) + *p_id_map = idx->id_map.data(); + if (p_size) + *p_size = idx->id_map.size(); +} + +FaissIndex* faiss_IndexIDMap2_sub_index(FaissIndexIDMap2* index) { + auto idx = reinterpret_cast(index); + return (FaissIndex*)reinterpret_cast(idx->index); +} diff --git a/c_api/MetaIndexes_c.h b/c_api/MetaIndexes_c.h new file mode 100644 index 0000000..8cd5cae --- /dev/null +++ b/c_api/MetaIndexes_c.h @@ -0,0 +1,100 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#ifndef METAINDEXES_C_H +#define METAINDEXES_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Index that translates search results to ids */ +FAISS_DECLARE_CLASS_INHERITED(IndexIDMap, Index) + +FAISS_DECLARE_GETTER_SETTER(IndexIDMap, int, own_fields) + +int faiss_IndexIDMap_new(FaissIndexIDMap** p_index, FaissIndex* index); + +/** attempt a dynamic cast to a IDMap, thus checking + * check whether the underlying index type is `IndexIDMap`. + * + * @param index opaque pointer to index object + * @return the same pointer if the index is a IDMap index, NULL otherwise + */ +FAISS_DECLARE_INDEX_DOWNCAST(IndexIDMap) + +/** get a pointer to the index map's internal ID vector (the `id_map` field). + * The outputs of this function become invalid after any operation that can + * modify the index. + * + * @param index opaque pointer to index object + * @param p_id_map output, the pointer to the beginning of `id_map`. + * @param p_size output, the current length of `id_map`. + */ +void faiss_IndexIDMap_id_map( + FaissIndexIDMap* index, + idx_t** p_id_map, + size_t* p_size); + +/** get a pointer to the sub-index (the `index` field). + * The outputs of this function become invalid after any operation that can + * modify the index. + * + * @param index opaque pointer to index object + */ +FaissIndex* faiss_IndexIDMap_sub_index(FaissIndexIDMap* index); + +/** same as IndexIDMap but also provides an efficient reconstruction + implementation via a 2-way index */ +FAISS_DECLARE_CLASS_INHERITED(IndexIDMap2, Index) + +FAISS_DECLARE_GETTER_SETTER(IndexIDMap2, int, own_fields) + +int faiss_IndexIDMap2_new(FaissIndexIDMap2** p_index, FaissIndex* index); + +/// make the rev_map from scratch +int faiss_IndexIDMap2_construct_rev_map(FaissIndexIDMap2* index); + +/** attempt a dynamic cast to a IDMap2, thus checking + * check whether the underlying index type is `IndexIDMap`. + * + * @param index opaque pointer to index object + * @return the same pointer if the index is a IDMap2 index, NULL otherwise + */ +FAISS_DECLARE_INDEX_DOWNCAST(IndexIDMap2) + +/** get a pointer to the index map's internal ID vector (the `id_map` field). + * The outputs of this function become invalid after any operation that can + * modify the index. + * + * @param index opaque pointer to index object + * @param p_id_map output, the pointer to the beginning of `id_map`. + * @param p_size output, the current length of `id_map`. + */ +void faiss_IndexIDMap2_id_map( + FaissIndexIDMap2* index, + idx_t** p_id_map, + size_t* p_size); + +/** get a pointer to the sub-index (the `index` field). + * The outputs of this function become invalid after any operation that can + * modify the index. + * + * @param index opaque pointer to index object + */ +FaissIndex* faiss_IndexIDMap2_sub_index(FaissIndexIDMap2* index); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/VectorTransform_c.cpp b/c_api/VectorTransform_c.cpp new file mode 100644 index 0000000..4304705 --- /dev/null +++ b/c_api/VectorTransform_c.cpp @@ -0,0 +1,228 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "VectorTransform_c.h" +#include +#include "macros_impl.h" + +extern "C" { + +DEFINE_DESTRUCTOR(VectorTransform) + +DEFINE_GETTER(VectorTransform, int, is_trained) + +DEFINE_GETTER(VectorTransform, int, d_in) + +DEFINE_GETTER(VectorTransform, int, d_out) + +int faiss_VectorTransform_train( + FaissVectorTransform* vt, + idx_t n, + const float* x) { + try { + reinterpret_cast(vt)->train(n, x); + } + CATCH_AND_HANDLE +} + +float* faiss_VectorTransform_apply( + const FaissVectorTransform* vt, + idx_t n, + const float* x) { + return reinterpret_cast(vt)->apply(n, x); +} + +void faiss_VectorTransform_apply_noalloc( + const FaissVectorTransform* vt, + idx_t n, + const float* x, + float* xt) { + return reinterpret_cast(vt)->apply_noalloc( + n, x, xt); +} + +void faiss_VectorTransform_reverse_transform( + const FaissVectorTransform* vt, + idx_t n, + const float* xt, + float* x) { + return reinterpret_cast(vt) + ->reverse_transform(n, xt, x); +} + +/********************************************* + * LinearTransform + *********************************************/ + +DEFINE_DESTRUCTOR(LinearTransform) + +DEFINE_GETTER(LinearTransform, int, have_bias) + +DEFINE_GETTER(LinearTransform, int, is_orthonormal) + +void faiss_LinearTransform_transform_transpose( + const FaissLinearTransform* vt, + idx_t n, + const float* y, + float* x) { + return reinterpret_cast(vt) + ->transform_transpose(n, y, x); +} + +void faiss_LinearTransform_set_is_orthonormal(FaissLinearTransform* vt) { + return reinterpret_cast(vt)->set_is_orthonormal(); +} + +/********************************************* + * RandomRotationMatrix + *********************************************/ + +DEFINE_DESTRUCTOR(RandomRotationMatrix) + +int faiss_RandomRotationMatrix_new_with( + FaissRandomRotationMatrix** p_vt, + int d_in, + int d_out) { + try { + *p_vt = reinterpret_cast( + new faiss::RandomRotationMatrix(d_in, d_out)); + } + CATCH_AND_HANDLE +} + +/********************************************* + * PCAMatrix + *********************************************/ + +DEFINE_DESTRUCTOR(PCAMatrix) + +int faiss_PCAMatrix_new_with( + FaissPCAMatrix** p_vt, + int d_in, + int d_out, + float eigen_power, + int random_rotation) { + try { + bool random_rotation_ = static_cast(random_rotation); + *p_vt = reinterpret_cast(new faiss::PCAMatrix( + d_in, d_out, eigen_power, random_rotation_)); + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(PCAMatrix, float, eigen_power) + +DEFINE_GETTER(PCAMatrix, int, random_rotation) + +/********************************************* + * ITQMatrix + *********************************************/ + +DEFINE_DESTRUCTOR(ITQMatrix) + +int faiss_ITQMatrix_new_with(FaissITQMatrix** p_vt, int d) { + try { + *p_vt = reinterpret_cast(new faiss::ITQMatrix(d)); + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(ITQTransform) + +int faiss_ITQTransform_new_with( + FaissITQTransform** p_vt, + int d_in, + int d_out, + int do_pca) { + try { + bool do_pca_ = static_cast(do_pca); + *p_vt = reinterpret_cast( + new faiss::ITQTransform(d_in, d_out, do_pca_)); + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(ITQTransform, int, do_pca) + +/********************************************* + * OPQMatrix + *********************************************/ + +DEFINE_DESTRUCTOR(OPQMatrix) + +int faiss_OPQMatrix_new_with(FaissOPQMatrix** p_vt, int d, int M, int d2) { + try { + *p_vt = reinterpret_cast( + new faiss::OPQMatrix(d, M, d2)); + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(OPQMatrix, int, verbose) +DEFINE_SETTER(OPQMatrix, int, verbose) + +DEFINE_GETTER(OPQMatrix, int, niter) +DEFINE_SETTER(OPQMatrix, int, niter) + +DEFINE_GETTER(OPQMatrix, int, niter_pq) +DEFINE_SETTER(OPQMatrix, int, niter_pq) + +/********************************************* + * RemapDimensionsTransform + *********************************************/ + +DEFINE_DESTRUCTOR(RemapDimensionsTransform) + +int faiss_RemapDimensionsTransform_new_with( + FaissRemapDimensionsTransform** p_vt, + int d_in, + int d_out, + int uniform) { + try { + bool uniform_ = static_cast(uniform); + *p_vt = reinterpret_cast( + new faiss::RemapDimensionsTransform(d_in, d_out, uniform_)); + } + CATCH_AND_HANDLE +} + +/********************************************* + * NormalizationTransform + *********************************************/ + +DEFINE_DESTRUCTOR(NormalizationTransform) + +int faiss_NormalizationTransform_new_with( + FaissNormalizationTransform** p_vt, + int d, + float norm) { + try { + *p_vt = reinterpret_cast( + new faiss::NormalizationTransform(d, norm)); + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(NormalizationTransform, float, norm) + +/********************************************* + * CenteringTransform + *********************************************/ + +DEFINE_DESTRUCTOR(CenteringTransform) + +int faiss_CenteringTransform_new_with(FaissCenteringTransform** p_vt, int d) { + try { + *p_vt = reinterpret_cast( + new faiss::CenteringTransform(d)); + } + CATCH_AND_HANDLE +} +} diff --git a/c_api/VectorTransform_c.h b/c_api/VectorTransform_c.h new file mode 100644 index 0000000..3798eac --- /dev/null +++ b/c_api/VectorTransform_c.h @@ -0,0 +1,174 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_VECTOR_TRANSFORM_C_H +#define FAISS_VECTOR_TRANSFORM_C_H + +/** Defines a few objects that apply transformations to a set of + * vectors Often these are pre-processing steps. + */ + +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// Opaque type for referencing to a VectorTransform object +FAISS_DECLARE_CLASS(VectorTransform) +FAISS_DECLARE_DESTRUCTOR(VectorTransform) + +/// Getter for is_trained +FAISS_DECLARE_GETTER(VectorTransform, int, is_trained) + +/// Getter for input dimension +FAISS_DECLARE_GETTER(VectorTransform, int, d_in) + +/// Getter for output dimension +FAISS_DECLARE_GETTER(VectorTransform, int, d_out) + +/** Perform training on a representative set of vectors + * + * @param vt opaque pointer to VectorTransform object + * @param n nb of training vectors + * @param x training vectors, size n * d + */ +int faiss_VectorTransform_train( + FaissVectorTransform* vt, + idx_t n, + const float* x); + +/** apply the random rotation, return new allocated matrix + * @param x size n * d_in + * @return size n * d_out + */ +float* faiss_VectorTransform_apply( + const FaissVectorTransform* vt, + idx_t n, + const float* x); + +/** apply transformation and result is pre-allocated + * @param x size n * d_in + * @param xt size n * d_out + */ +void faiss_VectorTransform_apply_noalloc( + const FaissVectorTransform* vt, + idx_t n, + const float* x, + float* xt); + +/// reverse transformation. May not be implemented or may return +/// approximate result +void faiss_VectorTransform_reverse_transform( + const FaissVectorTransform* vt, + idx_t n, + const float* xt, + float* x); + +/// Opaque type for referencing to a LinearTransform object +FAISS_DECLARE_CLASS_INHERITED(LinearTransform, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(LinearTransform) + +/// compute x = A^T * (x - b) +/// is reverse transform if A has orthonormal lines +void faiss_LinearTransform_transform_transpose( + const FaissLinearTransform* vt, + idx_t n, + const float* y, + float* x); + +/// compute A^T * A to set the is_orthonormal flag +void faiss_LinearTransform_set_is_orthonormal(FaissLinearTransform* vt); + +/// Getter for have_bias +FAISS_DECLARE_GETTER(LinearTransform, int, have_bias) + +/// Getter for is_orthonormal +FAISS_DECLARE_GETTER(LinearTransform, int, is_orthonormal) + +FAISS_DECLARE_CLASS_INHERITED(RandomRotationMatrix, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(RandomRotationMatrix) + +int faiss_RandomRotationMatrix_new_with( + FaissRandomRotationMatrix** p_vt, + int d_in, + int d_out); + +FAISS_DECLARE_CLASS_INHERITED(PCAMatrix, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(PCAMatrix) + +int faiss_PCAMatrix_new_with( + FaissPCAMatrix** p_vt, + int d_in, + int d_out, + float eigen_power, + int random_rotation); + +/// Getter for eigen_power +FAISS_DECLARE_GETTER(PCAMatrix, float, eigen_power) + +/// Getter for random_rotation +FAISS_DECLARE_GETTER(PCAMatrix, int, random_rotation) + +FAISS_DECLARE_CLASS_INHERITED(ITQMatrix, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(ITQMatrix) + +int faiss_ITQMatrix_new_with(FaissITQMatrix** p_vt, int d); + +FAISS_DECLARE_CLASS_INHERITED(ITQTransform, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(ITQTransform) + +int faiss_ITQTransform_new_with( + FaissITQTransform** p_vt, + int d_in, + int d_out, + int do_pca); + +/// Getter for do_pca +FAISS_DECLARE_GETTER(ITQTransform, int, do_pca) + +FAISS_DECLARE_CLASS_INHERITED(OPQMatrix, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(OPQMatrix) + +int faiss_OPQMatrix_new_with(FaissOPQMatrix** p_vt, int d, int M, int d2); + +FAISS_DECLARE_GETTER_SETTER(OPQMatrix, int, verbose) +FAISS_DECLARE_GETTER_SETTER(OPQMatrix, int, niter) +FAISS_DECLARE_GETTER_SETTER(OPQMatrix, int, niter_pq) + +FAISS_DECLARE_CLASS_INHERITED(RemapDimensionsTransform, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(RemapDimensionsTransform) + +int faiss_RemapDimensionsTransform_new_with( + FaissRemapDimensionsTransform** p_vt, + int d_in, + int d_out, + int uniform); + +FAISS_DECLARE_CLASS_INHERITED(NormalizationTransform, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(NormalizationTransform) + +int faiss_NormalizationTransform_new_with( + FaissNormalizationTransform** p_vt, + int d, + float norm); + +FAISS_DECLARE_GETTER(NormalizationTransform, float, norm) + +FAISS_DECLARE_CLASS_INHERITED(CenteringTransform, VectorTransform) +FAISS_DECLARE_DESTRUCTOR(CenteringTransform) + +int faiss_CenteringTransform_new_with(FaissCenteringTransform** p_vt, int d); + +#ifdef __cplusplus +} +#endif + +#endif \ No newline at end of file diff --git a/c_api/clone_index_c.cpp b/c_api/clone_index_c.cpp new file mode 100644 index 0000000..8211156 --- /dev/null +++ b/c_api/clone_index_c.cpp @@ -0,0 +1,24 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c++ -*- +// I/O code for indexes + +#include "clone_index_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; + +int faiss_clone_index(const FaissIndex* idx, FaissIndex** p_out) { + try { + auto out = faiss::clone_index(reinterpret_cast(idx)); + *p_out = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} diff --git a/c_api/clone_index_c.h b/c_api/clone_index_c.h new file mode 100644 index 0000000..3d0bd67 --- /dev/null +++ b/c_api/clone_index_c.h @@ -0,0 +1,31 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c++ -*- +// I/O code for indexes + +#ifndef FAISS_CLONE_INDEX_C_H +#define FAISS_CLONE_INDEX_C_H + +#include +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* cloning functions */ + +/** Clone an index. This is equivalent to `faiss::clone_index` */ +int faiss_clone_index(const FaissIndex*, FaissIndex** p_out); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/error_c.h b/c_api/error_c.h new file mode 100644 index 0000000..8c5575f --- /dev/null +++ b/c_api/error_c.h @@ -0,0 +1,42 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_ERROR_C_H +#define FAISS_ERROR_C_H + +#ifdef __cplusplus +extern "C" { +#endif + +/// An error code which depends on the exception thrown from the previous +/// operation. See `faiss_get_last_error` to retrieve the error message. +typedef enum FaissErrorCode { + /// No error + OK = 0, + /// Any exception other than Faiss or standard C++ library exceptions + UNKNOWN_EXCEPT = -1, + /// Faiss library exception + FAISS_EXCEPT = -2, + /// Standard C++ library exception + STD_EXCEPT = -4 +} FaissErrorCode; + +/** + * Get the error message of the last failed operation performed by Faiss. + * The given pointer is only invalid until another Faiss function is + * called. + */ +const char* faiss_get_last_error(); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/error_impl.cpp b/c_api/error_impl.cpp new file mode 100644 index 0000000..27f2972 --- /dev/null +++ b/c_api/error_impl.cpp @@ -0,0 +1,27 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "error_impl.h" +#include +#include +#include "error_c.h" + +thread_local std::exception_ptr faiss_last_exception; + +const char* faiss_get_last_error() { + if (faiss_last_exception) { + try { + std::rethrow_exception(faiss_last_exception); + } catch (std::exception& e) { + return e.what(); + } + } + return nullptr; +} diff --git a/c_api/error_impl.h b/c_api/error_impl.h new file mode 100644 index 0000000..b44254a --- /dev/null +++ b/c_api/error_impl.h @@ -0,0 +1,16 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include + +/** global variable for holding the last exception thrown by + * calls to Faiss functions through the C API + */ +extern thread_local std::exception_ptr faiss_last_exception; diff --git a/c_api/example_c.c b/c_api/example_c.c new file mode 100644 index 0000000..c739b43 --- /dev/null +++ b/c_api/example_c.c @@ -0,0 +1,104 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#include +#include +#include + +#include "AutoTune_c.h" +#include "IndexFlat_c.h" +#include "Index_c.h" +#include "clone_index_c.h" +#include "error_c.h" +#include "index_factory_c.h" +#include "index_io_c.h" + +#define FAISS_TRY(C) \ + { \ + if (C) { \ + fprintf(stderr, "%s", faiss_get_last_error()); \ + exit(-1); \ + } \ + } + +double drand() { + return (double)rand() / (double)RAND_MAX; +} + +int main() { + time_t seed = time(NULL); + srand(seed); + printf("Generating some data...\n"); + int d = 128; // dimension + int nb = 100000; // database size + int nq = 10000; // nb of queries + float* xb = malloc(d * nb * sizeof(float)); + float* xq = malloc(d * nq * sizeof(float)); + + for (int i = 0; i < nb; i++) { + for (int j = 0; j < d; j++) + xb[d * i + j] = drand(); + xb[d * i] += i / 1000.; + } + for (int i = 0; i < nq; i++) { + for (int j = 0; j < d; j++) + xq[d * i + j] = drand(); + xq[d * i] += i / 1000.; + } + + printf("Building an index...\n"); + + FaissIndex* index = NULL; + FAISS_TRY(faiss_index_factory( + &index, d, "Flat", METRIC_L2)); // use factory to create index + printf("is_trained = %s\n", + faiss_Index_is_trained(index) ? "true" : "false"); + FAISS_TRY(faiss_Index_add(index, nb, xb)); // add vectors to the index + printf("ntotal = %lld\n", faiss_Index_ntotal(index)); + + printf("Searching...\n"); + int k = 5; + + { // sanity check: search 5 first vectors of xb + idx_t* I = malloc(k * 5 * sizeof(idx_t)); + float* D = malloc(k * 5 * sizeof(float)); + FAISS_TRY(faiss_Index_search(index, 5, xb, k, D, I)); + printf("I=\n"); + for (int i = 0; i < 5; i++) { + for (int j = 0; j < k; j++) + printf("%5lld (d=%2.3f) ", I[i * k + j], D[i * k + j]); + printf("\n"); + } + free(I); + free(D); + } + { // search xq + idx_t* I = malloc(k * nq * sizeof(idx_t)); + float* D = malloc(k * nq * sizeof(float)); + FAISS_TRY(faiss_Index_search(index, nq, xq, k, D, I)); + printf("I=\n"); + for (int i = 0; i < 5; i++) { + for (int j = 0; j < k; j++) + printf("%5lld (d=%2.3f) ", I[i * k + j], D[i * k + j]); + printf("\n"); + } + free(I); + free(D); + } + + printf("Saving index to disk...\n"); + FAISS_TRY(faiss_write_index_fname(index, "example.index")); + + printf("Freeing index...\n"); + faiss_Index_free(index); + printf("Done.\n"); + + return 0; +} diff --git a/c_api/faiss_c.h b/c_api/faiss_c.h new file mode 100644 index 0000000..9a514be --- /dev/null +++ b/c_api/faiss_c.h @@ -0,0 +1,57 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +/// Macros and typedefs for C wrapper API declarations + +#ifndef FAISS_C_H +#define FAISS_C_H + +#include + +typedef int64_t faiss_idx_t; ///< all indices are this type +typedef faiss_idx_t idx_t; +typedef float faiss_component_t; ///< all vector components are this type +typedef float faiss_distance_t; ///< all distances between vectors are this type + +/// Declare an opaque type for a class type `clazz`. +#define FAISS_DECLARE_CLASS(clazz) typedef struct Faiss##clazz##_H Faiss##clazz; + +/// Declare an opaque type for a class type `clazz`, while +/// actually aliasing it to an existing parent class type `parent`. +#define FAISS_DECLARE_CLASS_INHERITED(clazz, parent) \ + typedef struct Faiss##parent##_H Faiss##clazz; + +/// Declare a dynamic downcast operation from a base `FaissIndex*` pointer +/// type to a more specific index type. The function returns the same pointer +/// if the downcast is valid, and `NULL` otherwise. +#define FAISS_DECLARE_INDEX_DOWNCAST(clazz) \ + Faiss##clazz* faiss_##clazz##_cast(FaissIndex*); + +/// Declare a getter for the field `name` in class `clazz`, +/// of return type `ty` +#define FAISS_DECLARE_GETTER(clazz, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz*); + +/// Declare a setter for the field `name` in class `clazz`, +/// in which the user provides a value of type `ty` +#define FAISS_DECLARE_SETTER(clazz, ty, name) \ + void faiss_##clazz##_set_##name(Faiss##clazz*, ty); + +/// Declare a getter and setter for the field `name` in class `clazz`. +#define FAISS_DECLARE_GETTER_SETTER(clazz, ty, name) \ + FAISS_DECLARE_GETTER(clazz, ty, name) \ + FAISS_DECLARE_SETTER(clazz, ty, name) + +/// Declare a destructor function which frees an object of +/// type `clazz`. +#define FAISS_DECLARE_DESTRUCTOR(clazz) \ + void faiss_##clazz##_free(Faiss##clazz* obj); + +#endif diff --git a/c_api/gpu/CMakeLists.txt b/c_api/gpu/CMakeLists.txt new file mode 100644 index 0000000..397462c --- /dev/null +++ b/c_api/gpu/CMakeLists.txt @@ -0,0 +1,22 @@ +# 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. + +target_sources(faiss_c PRIVATE + DeviceUtils_c.cpp + GpuAutoTune_c.cpp + GpuClonerOptions_c.cpp + GpuIndex_c.cpp + GpuResources_c.cpp + StandardGpuResources_c.cpp +) + +file(GLOB FAISS_C_API_GPU_HEADERS RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} "*.h") +faiss_install_headers("${FAISS_C_API_GPU_HEADERS}" c_api/gpu) + +find_package(CUDAToolkit REQUIRED) +target_link_libraries(faiss_c PUBLIC CUDA::cudart CUDA::cublas) + +add_executable(example_gpu_c EXCLUDE_FROM_ALL example_gpu_c.c) +target_link_libraries(example_gpu_c PRIVATE faiss_c) diff --git a/c_api/gpu/DeviceUtils_c.cpp b/c_api/gpu/DeviceUtils_c.cpp new file mode 100644 index 0000000..99194c5 --- /dev/null +++ b/c_api/gpu/DeviceUtils_c.cpp @@ -0,0 +1,47 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "DeviceUtils_c.h" +#include +#include "macros_impl.h" + +/// Returns the number of available GPU devices +int faiss_get_num_gpus(int* p_output) { + try { + int output = faiss::gpu::getNumDevices(); + *p_output = output; + } + CATCH_AND_HANDLE +} + +/// Starts the CUDA profiler (exposed via SWIG) +int faiss_gpu_profiler_start() { + try { + faiss::gpu::profilerStart(); + } + CATCH_AND_HANDLE +} + +/// Stops the CUDA profiler (exposed via SWIG) +int faiss_gpu_profiler_stop() { + try { + faiss::gpu::profilerStop(); + } + CATCH_AND_HANDLE +} + +/// Synchronizes the CPU against all devices (equivalent to +/// cudaDeviceSynchronize for each device) +int faiss_gpu_sync_all_devices() { + try { + faiss::gpu::synchronizeAllDevices(); + } + CATCH_AND_HANDLE +} diff --git a/c_api/gpu/DeviceUtils_c.h b/c_api/gpu/DeviceUtils_c.h new file mode 100644 index 0000000..df35fc6 --- /dev/null +++ b/c_api/gpu/DeviceUtils_c.h @@ -0,0 +1,38 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_DEVICE_UTILS_C_H +#define FAISS_DEVICE_UTILS_C_H + +#include +#include +#include "../faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// Returns the number of available GPU devices +int faiss_get_num_gpus(int* p_output); + +/// Starts the CUDA profiler (exposed via SWIG) +int faiss_gpu_profiler_start(); + +/// Stops the CUDA profiler (exposed via SWIG) +int faiss_gpu_profiler_stop(); + +/// Synchronizes the CPU against all devices (equivalent to +/// cudaDeviceSynchronize for each device) +int faiss_gpu_sync_all_devices(); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/GpuAutoTune_c.cpp b/c_api/gpu/GpuAutoTune_c.cpp new file mode 100644 index 0000000..cbfdf08 --- /dev/null +++ b/c_api/gpu/GpuAutoTune_c.cpp @@ -0,0 +1,113 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "GpuAutoTune_c.h" +#include +#include +#include +#include +#include +#include +#include "GpuClonerOptions_c.h" +#include "macros_impl.h" + +using faiss::Index; +using faiss::gpu::GpuClonerOptions; +using faiss::gpu::GpuMultipleClonerOptions; +using faiss::gpu::GpuResourcesProvider; + +int faiss_index_gpu_to_cpu(const FaissIndex* gpu_index, FaissIndex** p_out) { + try { + auto cpu_index = faiss::gpu::index_gpu_to_cpu( + reinterpret_cast(gpu_index)); + *p_out = reinterpret_cast(cpu_index); + } + CATCH_AND_HANDLE +} + +/// converts any CPU index that can be converted to GPU +int faiss_index_cpu_to_gpu( + FaissGpuResourcesProvider* provider, + int device, + const FaissIndex* index, + FaissGpuIndex** p_out) { + try { + auto res = reinterpret_cast(provider); + auto gpu_index = faiss::gpu::index_cpu_to_gpu( + res, device, reinterpret_cast(index)); + *p_out = reinterpret_cast(gpu_index); + } + CATCH_AND_HANDLE +} + +int faiss_index_cpu_to_gpu_with_options( + FaissGpuResourcesProvider* provider, + int device, + const FaissIndex* index, + const FaissGpuClonerOptions* options, + FaissGpuIndex** p_out) { + try { + auto res = reinterpret_cast(provider); + auto gpu_index = faiss::gpu::index_cpu_to_gpu( + res, + device, + reinterpret_cast(index), + reinterpret_cast(options)); + *p_out = reinterpret_cast(gpu_index); + } + CATCH_AND_HANDLE +} + +int faiss_index_cpu_to_gpu_multiple( + FaissGpuResourcesProvider* const* providers_vec, + const int* devices, + size_t devices_size, + const FaissIndex* index, + FaissGpuIndex** p_out) { + try { + std::vector res(devices_size); + for (auto i = 0u; i < devices_size; ++i) { + res[i] = reinterpret_cast(providers_vec[i]); + } + + std::vector dev(devices, devices + devices_size); + + auto gpu_index = faiss::gpu::index_cpu_to_gpu_multiple( + res, dev, reinterpret_cast(index)); + *p_out = reinterpret_cast(gpu_index); + } + CATCH_AND_HANDLE +} + +int faiss_index_cpu_to_gpu_multiple_with_options( + FaissGpuResourcesProvider** providers_vec, + size_t providers_vec_size, + int* devices, + size_t devices_size, + const FaissIndex* index, + const FaissGpuMultipleClonerOptions* options, + FaissGpuIndex** p_out) { + try { + std::vector res(providers_vec_size); + for (auto i = 0u; i < providers_vec_size; ++i) { + res[i] = reinterpret_cast(providers_vec[i]); + } + + std::vector dev(devices, devices + devices_size); + + auto gpu_index = faiss::gpu::index_cpu_to_gpu_multiple( + res, + dev, + reinterpret_cast(index), + reinterpret_cast(options)); + *p_out = reinterpret_cast(gpu_index); + } + CATCH_AND_HANDLE +} diff --git a/c_api/gpu/GpuAutoTune_c.h b/c_api/gpu/GpuAutoTune_c.h new file mode 100644 index 0000000..fbc935b --- /dev/null +++ b/c_api/gpu/GpuAutoTune_c.h @@ -0,0 +1,67 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_GPU_AUTO_TUNE_C_H +#define FAISS_GPU_AUTO_TUNE_C_H + +#include +#include "../Index_c.h" +#include "../faiss_c.h" +#include "GpuClonerOptions_c.h" +#include "GpuIndex_c.h" +#include "GpuResources_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// converts any GPU index inside gpu_index to a CPU index +int faiss_index_gpu_to_cpu(const FaissIndex* gpu_index, FaissIndex** p_out); + +/// converts any CPU index that can be converted to GPU +int faiss_index_cpu_to_gpu( + FaissGpuResourcesProvider* provider, + int device, + const FaissIndex* index, + FaissGpuIndex** p_out); + +/// converts any CPU index that can be converted to GPU +int faiss_index_cpu_to_gpu_with_options( + FaissGpuResourcesProvider* provider, + int device, + const FaissIndex* index, + const FaissGpuClonerOptions* options, + FaissGpuIndex** p_out); + +/// converts any CPU index that can be converted to GPU +int faiss_index_cpu_to_gpu_multiple( + FaissGpuResourcesProvider* const* providers_vec, + const int* devices, + size_t devices_size, + const FaissIndex* index, + FaissGpuIndex** p_out); + +/// converts any CPU index that can be converted to GPU +int faiss_index_cpu_to_gpu_multiple_with_options( + FaissGpuResourcesProvider* const* providers_vec, + size_t providers_vec_size, + const int* devices, + size_t devices_size, + const FaissIndex* index, + const FaissGpuMultipleClonerOptions* options, + FaissGpuIndex** p_out); + +/// parameter space and setters for GPU indexes +FAISS_DECLARE_CLASS_INHERITED(GpuParameterSpace, ParameterSpace) + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/GpuClonerOptions_c.cpp b/c_api/gpu/GpuClonerOptions_c.cpp new file mode 100644 index 0000000..9f6abed --- /dev/null +++ b/c_api/gpu/GpuClonerOptions_c.cpp @@ -0,0 +1,59 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "GpuClonerOptions_c.h" +#include +#include "macros_impl.h" + +using faiss::gpu::GpuClonerOptions; +using faiss::gpu::GpuMultipleClonerOptions; +using faiss::gpu::IndicesOptions; + +int faiss_GpuClonerOptions_new(FaissGpuClonerOptions** p) { + try { + *p = reinterpret_cast(new GpuClonerOptions()); + } + CATCH_AND_HANDLE +} + +int faiss_GpuMultipleClonerOptions_new(FaissGpuMultipleClonerOptions** p) { + try { + *p = reinterpret_cast( + new GpuMultipleClonerOptions()); + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(GpuClonerOptions) +DEFINE_DESTRUCTOR(GpuMultipleClonerOptions) + +DEFINE_GETTER(GpuClonerOptions, FaissIndicesOptions, indicesOptions) +DEFINE_GETTER(GpuClonerOptions, int, useFloat16CoarseQuantizer) +DEFINE_GETTER(GpuClonerOptions, int, useFloat16) +DEFINE_GETTER(GpuClonerOptions, int, usePrecomputed) +DEFINE_GETTER(GpuClonerOptions, long, reserveVecs) +DEFINE_GETTER(GpuClonerOptions, int, storeTransposed) +DEFINE_GETTER(GpuClonerOptions, int, verbose) +DEFINE_GETTER(GpuMultipleClonerOptions, int, shard) +DEFINE_GETTER(GpuMultipleClonerOptions, int, shard_type) + +DEFINE_SETTER_STATIC( + GpuClonerOptions, + IndicesOptions, + FaissIndicesOptions, + indicesOptions) +DEFINE_SETTER_STATIC(GpuClonerOptions, bool, int, useFloat16CoarseQuantizer) +DEFINE_SETTER_STATIC(GpuClonerOptions, bool, int, useFloat16) +DEFINE_SETTER_STATIC(GpuClonerOptions, bool, int, usePrecomputed) +DEFINE_SETTER(GpuClonerOptions, long, reserveVecs) +DEFINE_SETTER_STATIC(GpuClonerOptions, bool, int, storeTransposed) +DEFINE_SETTER_STATIC(GpuClonerOptions, bool, int, verbose) +DEFINE_SETTER_STATIC(GpuMultipleClonerOptions, bool, int, shard) +DEFINE_SETTER(GpuMultipleClonerOptions, int, shard_type) diff --git a/c_api/gpu/GpuClonerOptions_c.h b/c_api/gpu/GpuClonerOptions_c.h new file mode 100644 index 0000000..6c97586 --- /dev/null +++ b/c_api/gpu/GpuClonerOptions_c.h @@ -0,0 +1,71 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_GPU_CLONER_OPTIONS_C_H +#define FAISS_GPU_CLONER_OPTIONS_C_H + +#include "../faiss_c.h" +#include "GpuIndicesOptions_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +FAISS_DECLARE_CLASS(GpuClonerOptions) + +FAISS_DECLARE_DESTRUCTOR(GpuClonerOptions) + +/// Default constructor for GpuClonerOptions +int faiss_GpuClonerOptions_new(FaissGpuClonerOptions**); + +/// how should indices be stored on index types that support indices +/// (anything but GpuIndexFlat*)? +FAISS_DECLARE_GETTER_SETTER( + GpuClonerOptions, + FaissIndicesOptions, + indicesOptions) + +/// (boolean) is the coarse quantizer in float16? +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, int, useFloat16CoarseQuantizer) + +/// (boolean) for GpuIndexIVFFlat, is storage in float16? +/// for GpuIndexIVFPQ, are intermediate calculations in float16? +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, int, useFloat16) + +/// (boolean) use precomputed tables? +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, int, usePrecomputed) + +/// reserve vectors in the invfiles? +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, long, reserveVecs) + +/// (boolean) For GpuIndexFlat, store data in transposed layout? +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, int, storeTransposed) + +/// (boolean) Set verbose options on the index +FAISS_DECLARE_GETTER_SETTER(GpuClonerOptions, int, verbose) + +FAISS_DECLARE_CLASS_INHERITED(GpuMultipleClonerOptions, GpuClonerOptions) + +FAISS_DECLARE_DESTRUCTOR(GpuMultipleClonerOptions) + +/// Default constructor for GpuMultipleClonerOptions +int faiss_GpuMultipleClonerOptions_new(FaissGpuMultipleClonerOptions**); + +/// (boolean) Whether to shard the index across GPUs, versus replication +/// across GPUs +FAISS_DECLARE_GETTER_SETTER(GpuMultipleClonerOptions, int, shard) + +/// IndexIVF::copy_subset_to subset type +FAISS_DECLARE_GETTER_SETTER(GpuMultipleClonerOptions, int, shard_type) + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/GpuIndex_c.cpp b/c_api/gpu/GpuIndex_c.cpp new file mode 100644 index 0000000..9be2ca3 --- /dev/null +++ b/c_api/gpu/GpuIndex_c.cpp @@ -0,0 +1,17 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "GpuIndex_c.h" +#include +#include "macros_impl.h" + +using faiss::gpu::GpuIndexConfig; + +DEFINE_GETTER(GpuIndexConfig, int, device) diff --git a/c_api/gpu/GpuIndex_c.h b/c_api/gpu/GpuIndex_c.h new file mode 100644 index 0000000..8003ec5 --- /dev/null +++ b/c_api/gpu/GpuIndex_c.h @@ -0,0 +1,30 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_GPU_INDEX_C_H +#define FAISS_GPU_INDEX_C_H + +#include "../faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +FAISS_DECLARE_CLASS(GpuIndexConfig) + +FAISS_DECLARE_GETTER(GpuIndexConfig, int, device) + +FAISS_DECLARE_CLASS_INHERITED(GpuIndex, Index) + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/gpu/GpuIndicesOptions_c.h b/c_api/gpu/GpuIndicesOptions_c.h new file mode 100644 index 0000000..6d05383 --- /dev/null +++ b/c_api/gpu/GpuIndicesOptions_c.h @@ -0,0 +1,38 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_GPU_INDICES_OPTIONS_C_H +#define FAISS_GPU_INDICES_OPTIONS_C_H + +#ifdef __cplusplus +extern "C" { +#endif + +/// How user vector index data is stored on the GPU +typedef enum FaissIndicesOptions { + /// The user indices are only stored on the CPU; the GPU returns + /// (inverted list, offset) to the CPU which is then translated to + /// the real user index. + INDICES_CPU = 0, + /// The indices are not stored at all, on either the CPU or + /// GPU. Only (inverted list, offset) is returned to the user as the + /// index. + INDICES_IVF = 1, + /// Indices are stored as 32 bit integers on the GPU, but returned + /// as 64 bit integers + INDICES_32_BIT = 2, + /// Indices are stored as 64 bit integers on the GPU + INDICES_64_BIT = 3, +} FaissIndicesOptions; + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/GpuResources_c.cpp b/c_api/gpu/GpuResources_c.cpp new file mode 100644 index 0000000..3f9115a --- /dev/null +++ b/c_api/gpu/GpuResources_c.cpp @@ -0,0 +1,130 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "GpuResources_c.h" +#include +#include "macros_impl.h" + +using faiss::gpu::GpuResources; +using faiss::gpu::GpuResourcesProvider; + +DEFINE_DESTRUCTOR(GpuResources) + +int faiss_GpuResources_initializeForDevice(FaissGpuResources* res, int device) { + try { + reinterpret_cast(res)->initializeForDevice(device); + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getBlasHandle( + FaissGpuResources* res, + int device, + cublasHandle_t* out) { + try { + auto o = reinterpret_cast(res)->getBlasHandle(device); + *out = o; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getDefaultStream( + FaissGpuResources* res, + int device, + cudaStream_t* out) { + try { + auto o = reinterpret_cast(res)->getDefaultStream(device); + *out = o; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getPinnedMemory( + FaissGpuResources* res, + void** p_buffer, + size_t* p_size) { + try { + auto o = reinterpret_cast(res)->getPinnedMemory(); + *p_buffer = o.first; + *p_size = o.second; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getAsyncCopyStream( + FaissGpuResources* res, + int device, + cudaStream_t* out) { + try { + auto o = reinterpret_cast(res)->getAsyncCopyStream( + device); + *out = o; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getBlasHandleCurrentDevice( + FaissGpuResources* res, + cublasHandle_t* out) { + try { + auto o = reinterpret_cast(res) + ->getBlasHandleCurrentDevice(); + *out = o; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getDefaultStreamCurrentDevice( + FaissGpuResources* res, + cudaStream_t* out) { + try { + auto o = reinterpret_cast(res) + ->getDefaultStreamCurrentDevice(); + *out = o; + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_syncDefaultStream(FaissGpuResources* res, int device) { + try { + reinterpret_cast(res)->syncDefaultStream(device); + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_syncDefaultStreamCurrentDevice(FaissGpuResources* res) { + try { + reinterpret_cast(res)->syncDefaultStreamCurrentDevice(); + } + CATCH_AND_HANDLE +} + +int faiss_GpuResources_getAsyncCopyStreamCurrentDevice( + FaissGpuResources* res, + cudaStream_t* out) { + try { + auto o = reinterpret_cast(res) + ->getAsyncCopyStreamCurrentDevice(); + *out = o; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(GpuResourcesProvider) + +int faiss_GpuResourcesProvider_getResources( + FaissGpuResourcesProvider* res, + FaissGpuResources** out) { + try { + auto o = reinterpret_cast(res)->getResources(); + *out = reinterpret_cast(o.get()); + } + CATCH_AND_HANDLE +} diff --git a/c_api/gpu/GpuResources_c.h b/c_api/gpu/GpuResources_c.h new file mode 100644 index 0000000..aaef6d4 --- /dev/null +++ b/c_api/gpu/GpuResources_c.h @@ -0,0 +1,83 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_GPU_RESOURCES_C_H +#define FAISS_GPU_RESOURCES_C_H + +#include +#include +#include "../faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// Base class of GPU-side resource provider; hides provision of +/// cuBLAS handles, CUDA streams and a temporary memory manager +FAISS_DECLARE_CLASS(GpuResources) + +FAISS_DECLARE_DESTRUCTOR(GpuResources) + +/// Call to pre-allocate resources for a particular device. If this is +/// not called, then resources will be allocated at the first time +/// of demand +int faiss_GpuResources_initializeForDevice(FaissGpuResources*, int); + +/// Returns the cuBLAS handle that we use for the given device +int faiss_GpuResources_getBlasHandle(FaissGpuResources*, int, cublasHandle_t*); + +/// Returns the stream that we order all computation on for the +/// given device +int faiss_GpuResources_getDefaultStream(FaissGpuResources*, int, cudaStream_t*); + +/// Returns the available CPU pinned memory buffer +int faiss_GpuResources_getPinnedMemory(FaissGpuResources*, void**, size_t*); + +/// Returns the stream on which we perform async CPU <-> GPU copies +int faiss_GpuResources_getAsyncCopyStream( + FaissGpuResources*, + int, + cudaStream_t*); + +/// Calls getBlasHandle with the current device +int faiss_GpuResources_getBlasHandleCurrentDevice( + FaissGpuResources*, + cublasHandle_t*); + +/// Calls getDefaultStream with the current device +int faiss_GpuResources_getDefaultStreamCurrentDevice( + FaissGpuResources*, + cudaStream_t*); + +/// Synchronizes the CPU with respect to the default stream for the +/// given device +// equivalent to cudaDeviceSynchronize(getDefaultStream(device)) +int faiss_GpuResources_syncDefaultStream(FaissGpuResources*, int); + +/// Calls syncDefaultStream for the current device +int faiss_GpuResources_syncDefaultStreamCurrentDevice(FaissGpuResources*); + +/// Calls getAsyncCopyStream for the current device +int faiss_GpuResources_getAsyncCopyStreamCurrentDevice( + FaissGpuResources*, + cudaStream_t*); + +FAISS_DECLARE_CLASS(GpuResourcesProvider) + +FAISS_DECLARE_DESTRUCTOR(GpuResourcesProvider) + +int faiss_GpuResourcesProvider_getResources( + FaissGpuResourcesProvider*, + FaissGpuResources**); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/StandardGpuResources_c.cpp b/c_api/gpu/StandardGpuResources_c.cpp new file mode 100644 index 0000000..31766d1 --- /dev/null +++ b/c_api/gpu/StandardGpuResources_c.cpp @@ -0,0 +1,70 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "StandardGpuResources_c.h" +#include +#include "macros_impl.h" + +using faiss::gpu::StandardGpuResources; + +DEFINE_DESTRUCTOR(StandardGpuResources) + +int faiss_StandardGpuResources_new(FaissStandardGpuResources** p_res) { + try { + auto p = new StandardGpuResources(); + *p_res = reinterpret_cast(p); + } + CATCH_AND_HANDLE +} + +int faiss_StandardGpuResources_noTempMemory(FaissStandardGpuResources* res) { + try { + reinterpret_cast(res)->noTempMemory(); + } + CATCH_AND_HANDLE +} + +int faiss_StandardGpuResources_setTempMemory( + FaissStandardGpuResources* res, + size_t size) { + try { + reinterpret_cast(res)->setTempMemory(size); + } + CATCH_AND_HANDLE +} + +int faiss_StandardGpuResources_setPinnedMemory( + FaissStandardGpuResources* res, + size_t size) { + try { + reinterpret_cast(res)->setPinnedMemory(size); + } + CATCH_AND_HANDLE +} + +int faiss_StandardGpuResources_setDefaultStream( + FaissStandardGpuResources* res, + int device, + cudaStream_t stream) { + try { + reinterpret_cast(res)->setDefaultStream( + device, stream); + } + CATCH_AND_HANDLE +} + +int faiss_StandardGpuResources_setDefaultNullStreamAllDevices( + FaissStandardGpuResources* res) { + try { + reinterpret_cast(res) + ->setDefaultNullStreamAllDevices(); + } + CATCH_AND_HANDLE +} diff --git a/c_api/gpu/StandardGpuResources_c.h b/c_api/gpu/StandardGpuResources_c.h new file mode 100644 index 0000000..1b8c6e7 --- /dev/null +++ b/c_api/gpu/StandardGpuResources_c.h @@ -0,0 +1,61 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_STANDARD_GPURESOURCES_C_H +#define FAISS_STANDARD_GPURESOURCES_C_H + +#include +#include "../faiss_c.h" +#include "GpuResources_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/// Default implementation of GpuResourcesProvider that allocates a cuBLAS +/// stream and 2 streams for use, as well as temporary memory +FAISS_DECLARE_CLASS_INHERITED(StandardGpuResources, GpuResourcesProvider) + +FAISS_DECLARE_DESTRUCTOR(StandardGpuResources) + +/// Default constructor for StandardGpuResources +int faiss_StandardGpuResources_new(FaissStandardGpuResources**); + +/// Disable allocation of temporary memory; all temporary memory +/// requests will call cudaMalloc / cudaFree at the point of use +int faiss_StandardGpuResources_noTempMemory(FaissStandardGpuResources*); + +/// Specify that we wish to use a certain fixed size of memory on +/// all devices as temporary memory +int faiss_StandardGpuResources_setTempMemory( + FaissStandardGpuResources*, + size_t size); + +/// Set amount of pinned memory to allocate, for async GPU <-> CPU +/// transfers +int faiss_StandardGpuResources_setPinnedMemory( + FaissStandardGpuResources*, + size_t size); + +/// Called to change the stream for work ordering +int faiss_StandardGpuResources_setDefaultStream( + FaissStandardGpuResources*, + int device, + cudaStream_t stream); + +/// Called to change the work ordering streams to the null stream +/// for all devices +int faiss_StandardGpuResources_setDefaultNullStreamAllDevices( + FaissStandardGpuResources*); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/gpu/example_gpu_c.c b/c_api/gpu/example_gpu_c.c new file mode 100644 index 0000000..81cefa0 --- /dev/null +++ b/c_api/gpu/example_gpu_c.c @@ -0,0 +1,120 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#include +#include +#include + +#include "../AutoTune_c.h" +#include "../Index_c.h" +#include "../error_c.h" +#include "../index_factory_c.h" +#include "DeviceUtils_c.h" +#include "GpuAutoTune_c.h" +#include "StandardGpuResources_c.h" + +#define FAISS_TRY(C) \ + { \ + if (C) { \ + fprintf(stderr, "%s", faiss_get_last_error()); \ + exit(-1); \ + } \ + } + +double drand() { + return (double)rand() / (double)RAND_MAX; +} + +int main() { + time_t seed = time(NULL); + srand(seed); + + int gpus = -1; + FAISS_TRY(faiss_get_num_gpus(&gpus)); + printf("%d GPU devices are available\n", gpus); + + printf("Generating some data...\n"); + int d = 128; // dimension + int nb = 100000; // database size + int nq = 10000; // nb of queries + float* xb = malloc(d * nb * sizeof(float)); + float* xq = malloc(d * nq * sizeof(float)); + + for (int i = 0; i < nb; i++) { + for (int j = 0; j < d; j++) + xb[d * i + j] = drand(); + xb[d * i] += i / 1000.; + } + for (int i = 0; i < nq; i++) { + for (int j = 0; j < d; j++) + xq[d * i + j] = drand(); + xq[d * i] += i / 1000.; + } + + printf("Loading standard GPU resources...\n"); + FaissStandardGpuResources* gpu_res = NULL; + FAISS_TRY(faiss_StandardGpuResources_new(&gpu_res)); + + printf("Building an index...\n"); + FaissIndex* cpu_index = NULL; + FAISS_TRY(faiss_index_factory( + &cpu_index, d, "Flat", METRIC_L2)); // use factory to create index + + printf("Moving index to the GPU...\n"); + FaissGpuIndex* index = NULL; + FaissGpuClonerOptions* options = NULL; + FAISS_TRY(faiss_GpuClonerOptions_new(&options)); + FAISS_TRY(faiss_index_cpu_to_gpu_with_options( + gpu_res, 0, cpu_index, options, &index)); + + printf("is_trained = %s\n", + faiss_Index_is_trained(index) ? "true" : "false"); + FAISS_TRY(faiss_Index_add(index, nb, xb)); // add vectors to the index + printf("ntotal = %ld\n", faiss_Index_ntotal(index)); + + printf("Searching...\n"); + int k = 5; + + { // sanity check: search 5 first vectors of xb + idx_t* I = malloc(k * 5 * sizeof(idx_t)); + float* D = malloc(k * 5 * sizeof(float)); + FAISS_TRY(faiss_Index_search(index, 5, xb, k, D, I)); + printf("I=\n"); + for (int i = 0; i < 5; i++) { + for (int j = 0; j < k; j++) + printf("%5ld (d=%2.3f) ", I[i * k + j], D[i * k + j]); + printf("\n"); + } + free(I); + free(D); + } + { // search xq + idx_t* I = malloc(k * nq * sizeof(idx_t)); + float* D = malloc(k * nq * sizeof(float)); + FAISS_TRY(faiss_Index_search(index, 5, xb, k, D, I)); + printf("I=\n"); + for (int i = 0; i < 5; i++) { + for (int j = 0; j < k; j++) + printf("%5ld (d=%2.3f) ", I[i * k + j], D[i * k + j]); + printf("\n"); + } + free(I); + free(D); + } + + printf("Freeing index...\n"); + faiss_Index_free(index); + printf("Freeing GPU resources...\n"); + faiss_GpuResources_free(gpu_res); + faiss_GpuClonerOptions_free(options); + printf("Done.\n"); + + return 0; +} diff --git a/c_api/gpu/macros_impl.h b/c_api/gpu/macros_impl.h new file mode 100644 index 0000000..f0cf6b8 --- /dev/null +++ b/c_api/gpu/macros_impl.h @@ -0,0 +1,41 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#ifndef GPU_MACROS_IMPL_H +#define GPU_MACROS_IMPL_H +#include "../macros_impl.h" + +#undef DEFINE_GETTER +#define DEFINE_GETTER(clazz, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz* obj) { \ + return static_cast( \ + reinterpret_cast(obj)->name); \ + } + +#undef DEFINE_SETTER +#define DEFINE_SETTER(clazz, ty, name) \ + void faiss_##clazz##_set_##name(Faiss##clazz* obj, ty val) { \ + reinterpret_cast(obj)->name = val; \ + } + +#undef DEFINE_SETTER_STATIC +#define DEFINE_SETTER_STATIC(clazz, ty_to, ty_from, name) \ + void faiss_##clazz##_set_##name(Faiss##clazz* obj, ty_from val) { \ + reinterpret_cast(obj)->name = \ + static_cast(val); \ + } + +#undef DEFINE_DESTRUCTOR +#define DEFINE_DESTRUCTOR(clazz) \ + void faiss_##clazz##_free(Faiss##clazz* obj) { \ + delete reinterpret_cast(obj); \ + } + +#endif diff --git a/c_api/impl/AuxIndexStructures_c.cpp b/c_api/impl/AuxIndexStructures_c.cpp new file mode 100644 index 0000000..af0d923 --- /dev/null +++ b/c_api/impl/AuxIndexStructures_c.cpp @@ -0,0 +1,259 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "AuxIndexStructures_c.h" +#include +#include +#include +#include +#include "../macros_impl.h" + +using faiss::BufferList; +using faiss::DistanceComputer; +using faiss::IDSelector; +using faiss::IDSelectorBatch; +using faiss::IDSelectorRange; +using faiss::RangeQueryResult; +using faiss::RangeSearchPartialResult; +using faiss::RangeSearchResult; + +DEFINE_GETTER(RangeSearchResult, size_t, nq) + +int faiss_RangeSearchResult_new(FaissRangeSearchResult** p_rsr, idx_t nq) { + try { + *p_rsr = reinterpret_cast( + new RangeSearchResult(nq)); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_RangeSearchResult_new_with( + FaissRangeSearchResult** p_rsr, + idx_t nq, + int alloc_lims) { + try { + *p_rsr = reinterpret_cast( + new RangeSearchResult(nq, static_cast(alloc_lims))); + return 0; + } + CATCH_AND_HANDLE +} + +/// called when lims contains the nb of elements result entries +/// for each query +int faiss_RangeSearchResult_do_allocation(FaissRangeSearchResult* rsr) { + try { + reinterpret_cast(rsr)->do_allocation(); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(RangeSearchResult) + +/// getter for buffer_size +DEFINE_GETTER(RangeSearchResult, size_t, buffer_size) + +/// getter for lims: size (nq + 1) +void faiss_RangeSearchResult_lims(FaissRangeSearchResult* rsr, size_t** lims) { + *lims = reinterpret_cast(rsr)->lims; +} + +/// getter for labels and respective distances (not sorted): +/// result for query i is labels[lims[i]:lims[i+1]] +void faiss_RangeSearchResult_labels( + FaissRangeSearchResult* rsr, + idx_t** labels, + float** distances) { + auto sr = reinterpret_cast(rsr); + *labels = sr->labels; + *distances = sr->distances; +} + +DEFINE_DESTRUCTOR(IDSelector) + +int faiss_IDSelector_is_member(const FaissIDSelector* sel, idx_t id) { + return reinterpret_cast(sel)->is_member(id); +} + +DEFINE_DESTRUCTOR(IDSelectorRange) + +DEFINE_GETTER(IDSelectorRange, idx_t, imin) +DEFINE_GETTER(IDSelectorRange, idx_t, imax) + +int faiss_IDSelectorRange_new( + FaissIDSelectorRange** p_sel, + idx_t imin, + idx_t imax) { + try { + *p_sel = reinterpret_cast( + new IDSelectorRange(imin, imax)); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(IDSelectorBatch, int, nbits) +DEFINE_GETTER(IDSelectorBatch, idx_t, mask) + +int faiss_IDSelectorBatch_new( + FaissIDSelectorBatch** p_sel, + size_t n, + const idx_t* indices) { + try { + *p_sel = reinterpret_cast( + new IDSelectorBatch(n, indices)); + return 0; + } + CATCH_AND_HANDLE +} + +// Below are structures used only by Index implementations + +DEFINE_DESTRUCTOR(BufferList) + +DEFINE_GETTER(BufferList, size_t, buffer_size) +DEFINE_GETTER(BufferList, size_t, wp) + +int faiss_BufferList_append_buffer(FaissBufferList* bl) { + try { + reinterpret_cast(bl)->append_buffer(); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_BufferList_new(FaissBufferList** p_bl, size_t buffer_size) { + try { + *p_bl = reinterpret_cast(new BufferList(buffer_size)); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_BufferList_add(FaissBufferList* bl, idx_t id, float dis) { + try { + reinterpret_cast(bl)->add(id, dis); + return 0; + } + CATCH_AND_HANDLE +} + +/// copy elemnts ofs:ofs+n-1 seen as linear data in the buffers to +/// tables dest_ids, dest_dis +int faiss_BufferList_copy_range( + FaissBufferList* bl, + size_t ofs, + size_t n, + idx_t* dest_ids, + float* dest_dis) { + try { + reinterpret_cast(bl)->copy_range( + ofs, n, dest_ids, dest_dis); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER(RangeQueryResult, idx_t, qno) +DEFINE_GETTER(RangeQueryResult, size_t, nres) +DEFINE_GETTER_PERMISSIVE(RangeQueryResult, FaissRangeSearchPartialResult*, pres) + +int faiss_RangeQueryResult_add(FaissRangeQueryResult* qr, float dis, idx_t id) { + try { + reinterpret_cast(qr)->add(dis, id); + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_GETTER_PERMISSIVE(RangeSearchPartialResult, FaissRangeSearchResult*, res) + +int faiss_RangeSearchPartialResult_new( + FaissRangeSearchPartialResult** p_res, + FaissRangeSearchResult* res_in) { + try { + *p_res = reinterpret_cast( + new RangeSearchPartialResult( + reinterpret_cast(res_in))); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_RangeSearchPartialResult_finalize( + FaissRangeSearchPartialResult* res) { + try { + reinterpret_cast(res)->finalize(); + return 0; + } + CATCH_AND_HANDLE +} + +/// called by range_search before do_allocation +int faiss_RangeSearchPartialResult_set_lims( + FaissRangeSearchPartialResult* res) { + try { + reinterpret_cast(res)->set_lims(); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_RangeSearchPartialResult_new_result( + FaissRangeSearchPartialResult* res, + idx_t qno, + FaissRangeQueryResult** qr) { + try { + auto q = &reinterpret_cast(res)->new_result( + qno); + if (qr) { + *qr = reinterpret_cast(&q); + } + return 0; + } + CATCH_AND_HANDLE +} + +DEFINE_DESTRUCTOR(DistanceComputer) + +int faiss_DistanceComputer_set_query( + FaissDistanceComputer* dc, + const float* x) { + try { + reinterpret_cast(dc)->set_query(x); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_DistanceComputer_vector_to_query_dis( + FaissDistanceComputer* dc, + idx_t i, + float* qd) { + try { + *qd = reinterpret_cast(dc)->operator()(i); + return 0; + } + CATCH_AND_HANDLE +} + +int faiss_DistanceComputer_symmetric_dis( + FaissDistanceComputer* dc, + idx_t i, + idx_t j, + float* vd) { + try { + *vd = reinterpret_cast(dc)->symmetric_dis(i, j); + return 0; + } + CATCH_AND_HANDLE +} diff --git a/c_api/impl/AuxIndexStructures_c.h b/c_api/impl/AuxIndexStructures_c.h new file mode 100644 index 0000000..a1d4c6f --- /dev/null +++ b/c_api/impl/AuxIndexStructures_c.h @@ -0,0 +1,168 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_AUX_INDEX_STRUCTURES_C_H +#define FAISS_AUX_INDEX_STRUCTURES_C_H + +#include "../Index_c.h" +#include "../faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +FAISS_DECLARE_CLASS(RangeSearchResult) + +FAISS_DECLARE_GETTER(RangeSearchResult, size_t, nq) + +int faiss_RangeSearchResult_new(FaissRangeSearchResult** p_rsr, idx_t nq); + +int faiss_RangeSearchResult_new_with( + FaissRangeSearchResult** p_rsr, + idx_t nq, + int alloc_lims); + +/// called when lims contains the nb of elements result entries +/// for each query +int faiss_RangeSearchResult_do_allocation(FaissRangeSearchResult* rsr); + +FAISS_DECLARE_DESTRUCTOR(RangeSearchResult) + +/// getter for buffer_size +FAISS_DECLARE_GETTER(RangeSearchResult, size_t, buffer_size) + +/// getter for lims: size (nq + 1) +void faiss_RangeSearchResult_lims(FaissRangeSearchResult* rsr, size_t** lims); + +/// getter for labels and respective distances (not sorted): +/// result for query i is labels[lims[i]:lims[i+1]] +void faiss_RangeSearchResult_labels( + FaissRangeSearchResult* rsr, + idx_t** labels, + float** distances); + +/** Encapsulates a set of ids to remove. */ +FAISS_DECLARE_CLASS(IDSelector) +FAISS_DECLARE_DESTRUCTOR(IDSelector) + +int faiss_IDSelector_is_member(const FaissIDSelector* sel, idx_t id); + +/** remove ids between [imni, imax) */ +FAISS_DECLARE_CLASS(IDSelectorRange) +FAISS_DECLARE_DESTRUCTOR(IDSelectorRange) + +FAISS_DECLARE_GETTER(IDSelectorRange, idx_t, imin) +FAISS_DECLARE_GETTER(IDSelectorRange, idx_t, imax) + +int faiss_IDSelectorRange_new( + FaissIDSelectorRange** p_sel, + idx_t imin, + idx_t imax); + +/** Remove ids from a set. Repetitions of ids in the indices set + * passed to the constructor does not hurt performance. The hash + * function used for the bloom filter and GCC's implementation of + * unordered_set are just the least significant bits of the id. This + * works fine for random ids or ids in sequences but will produce many + * hash collisions if lsb's are always the same */ +FAISS_DECLARE_CLASS(IDSelectorBatch) + +FAISS_DECLARE_GETTER(IDSelectorBatch, int, nbits) +FAISS_DECLARE_GETTER(IDSelectorBatch, idx_t, mask) + +int faiss_IDSelectorBatch_new( + FaissIDSelectorBatch** p_sel, + size_t n, + const idx_t* indices); + +// Below are structures used only by Index implementations + +/** List of temporary buffers used to store results before they are + * copied to the RangeSearchResult object. */ +FAISS_DECLARE_CLASS(BufferList) +FAISS_DECLARE_DESTRUCTOR(BufferList) + +FAISS_DECLARE_GETTER(BufferList, size_t, buffer_size) +FAISS_DECLARE_GETTER(BufferList, size_t, wp) + +typedef struct FaissBuffer { + idx_t* ids; + float* dis; +} FaissBuffer; + +int faiss_BufferList_append_buffer(FaissBufferList* bl); + +int faiss_BufferList_new(FaissBufferList** p_bl, size_t buffer_size); + +int faiss_BufferList_add(FaissBufferList* bl, idx_t id, float dis); + +/// copy elemnts ofs:ofs+n-1 seen as linear data in the buffers to +/// tables dest_ids, dest_dis +int faiss_BufferList_copy_range( + FaissBufferList* bl, + size_t ofs, + size_t n, + idx_t* dest_ids, + float* dest_dis); + +/// the entries in the buffers are split per query +FAISS_DECLARE_CLASS(RangeSearchPartialResult) + +/// result structure for a single query +FAISS_DECLARE_CLASS(RangeQueryResult) +FAISS_DECLARE_GETTER(RangeQueryResult, idx_t, qno) +FAISS_DECLARE_GETTER(RangeQueryResult, size_t, nres) +FAISS_DECLARE_GETTER(RangeQueryResult, FaissRangeSearchPartialResult*, pres) + +int faiss_RangeQueryResult_add(FaissRangeQueryResult* qr, float dis, idx_t id); + +FAISS_DECLARE_GETTER(RangeSearchPartialResult, FaissRangeSearchResult*, res) + +int faiss_RangeSearchPartialResult_new( + FaissRangeSearchPartialResult** p_res, + FaissRangeSearchResult* res_in); + +int faiss_RangeSearchPartialResult_finalize(FaissRangeSearchPartialResult* res); + +/// called by range_search before do_allocation +int faiss_RangeSearchPartialResult_set_lims(FaissRangeSearchPartialResult* res); + +int faiss_RangeSearchPartialResult_new_result( + FaissRangeSearchPartialResult* res, + idx_t qno, + FaissRangeQueryResult** qr); + +FAISS_DECLARE_CLASS(DistanceComputer) +/// called before computing distances +int faiss_DistanceComputer_set_query(FaissDistanceComputer* dc, const float* x); + +/** + * Compute distance of vector i to current query. + * This function corresponds to the function call operator: + * DistanceComputer::operator() + */ +int faiss_DistanceComputer_vector_to_query_dis( + FaissDistanceComputer* dc, + idx_t i, + float* qd); +/// compute distance between two stored vectors +int faiss_DistanceComputer_symmetric_dis( + FaissDistanceComputer* dc, + idx_t i, + idx_t j, + float* vd); + +FAISS_DECLARE_DESTRUCTOR(DistanceComputer) + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/index_factory_c.cpp b/c_api/index_factory_c.cpp new file mode 100644 index 0000000..e9abf14 --- /dev/null +++ b/c_api/index_factory_c.cpp @@ -0,0 +1,31 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "index_factory_c.h" +#include +#include +#include "macros_impl.h" + +using faiss::Index; + +/** Build and index with the sequence of processing steps described in + * the string. + */ +int faiss_index_factory( + FaissIndex** p_index, + int d, + const char* description, + FaissMetricType metric) { + try { + *p_index = reinterpret_cast(faiss::index_factory( + d, description, static_cast(metric))); + } + CATCH_AND_HANDLE +} diff --git a/c_api/index_factory_c.h b/c_api/index_factory_c.h new file mode 100644 index 0000000..11fb0fa --- /dev/null +++ b/c_api/index_factory_c.h @@ -0,0 +1,34 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_INDEX_FACTORY_C_H +#define FAISS_INDEX_FACTORY_C_H + +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Build and index with the sequence of processing steps described in + * the string. + */ +int faiss_index_factory( + FaissIndex** p_index, + int d, + const char* description, + FaissMetricType metric); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/c_api/index_io_c.cpp b/c_api/index_io_c.cpp new file mode 100644 index 0000000..8814db5 --- /dev/null +++ b/c_api/index_io_c.cpp @@ -0,0 +1,86 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c++ -*- +// I/O code for indexes + +#include "index_io_c.h" +#include +#include "macros_impl.h" + +using faiss::Index; +using faiss::IndexBinary; + +int faiss_write_index(const FaissIndex* idx, FILE* f) { + try { + faiss::write_index(reinterpret_cast(idx), f); + } + CATCH_AND_HANDLE +} + +int faiss_write_index_fname(const FaissIndex* idx, const char* fname) { + try { + faiss::write_index(reinterpret_cast(idx), fname); + } + CATCH_AND_HANDLE +} + +int faiss_read_index(FILE* f, int io_flags, FaissIndex** p_out) { + try { + auto out = faiss::read_index(f, io_flags); + *p_out = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_read_index_fname( + const char* fname, + int io_flags, + FaissIndex** p_out) { + try { + auto out = faiss::read_index(fname, io_flags); + *p_out = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_write_index_binary(const FaissIndexBinary* idx, FILE* f) { + try { + faiss::write_index_binary(reinterpret_cast(idx), f); + } + CATCH_AND_HANDLE +} + +int faiss_write_index_binary_fname( + const FaissIndexBinary* idx, + const char* fname) { + try { + faiss::write_index_binary( + reinterpret_cast(idx), fname); + } + CATCH_AND_HANDLE +} + +int faiss_read_index_binary(FILE* f, int io_flags, FaissIndexBinary** p_out) { + try { + auto out = faiss::read_index_binary(f, io_flags); + *p_out = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} + +int faiss_read_index_binary_fname( + const char* fname, + int io_flags, + FaissIndexBinary** p_out) { + try { + auto out = faiss::read_index_binary(fname, io_flags); + *p_out = reinterpret_cast(out); + } + CATCH_AND_HANDLE +} diff --git a/c_api/index_io_c.h b/c_api/index_io_c.h new file mode 100644 index 0000000..8935de0 --- /dev/null +++ b/c_api/index_io_c.h @@ -0,0 +1,78 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved +// -*- c++ -*- +// I/O code for indexes + +#ifndef FAISS_INDEX_IO_C_H +#define FAISS_INDEX_IO_C_H + +#include +#include "IndexBinary_c.h" +#include "Index_c.h" +#include "faiss_c.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** Write index to a file. + * This is equivalent to `faiss::write_index` when a file descriptor is + * provided. + */ +int faiss_write_index(const FaissIndex* idx, FILE* f); + +/** Write index to a file. + * This is equivalent to `faiss::write_index` when a file path is provided. + */ +int faiss_write_index_fname(const FaissIndex* idx, const char* fname); + +#define FAISS_IO_FLAG_MMAP 1 +#define FAISS_IO_FLAG_READ_ONLY 2 + +/** Read index from a file. + * This is equivalent to `faiss:read_index` when a file descriptor is given. + */ +int faiss_read_index(FILE* f, int io_flags, FaissIndex** p_out); + +/** Read index from a file. + * This is equivalent to `faiss:read_index` when a file path is given. + */ +int faiss_read_index_fname(const char* fname, int io_flags, FaissIndex** p_out); + +/** Write index to a file. + * This is equivalent to `faiss::write_index_binary` when a file descriptor is + * provided. + */ +int faiss_write_index_binary(const FaissIndexBinary* idx, FILE* f); + +/** Write index to a file. + * This is equivalent to `faiss::write_index_binary` when a file path is + * provided. + */ +int faiss_write_index_binary_fname( + const FaissIndexBinary* idx, + const char* fname); + +/** Read index from a file. + * This is equivalent to `faiss:read_index_binary` when a file descriptor is + * given. + */ +int faiss_read_index_binary(FILE* f, int io_flags, FaissIndexBinary** p_out); + +/** Read index from a file. + * This is equivalent to `faiss:read_index_binary` when a file path is given. + */ +int faiss_read_index_binary_fname( + const char* fname, + int io_flags, + FaissIndexBinary** p_out); +#ifdef __cplusplus +} +#endif +#endif diff --git a/c_api/macros_impl.h b/c_api/macros_impl.h new file mode 100644 index 0000000..506ae42 --- /dev/null +++ b/c_api/macros_impl.h @@ -0,0 +1,102 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +/// Utility macros for the C wrapper implementation. + +#ifndef MACROS_IMPL_H +#define MACROS_IMPL_H + +#include +#include +#include +#include "error_impl.h" +#include "faiss_c.h" + +#ifdef NDEBUG +#define CATCH_AND_HANDLE \ + catch (faiss::FaissException & e) { \ + faiss_last_exception = std::make_exception_ptr(e); \ + return -2; \ + } \ + catch (std::exception & e) { \ + faiss_last_exception = std::make_exception_ptr(e); \ + return -4; \ + } \ + catch (...) { \ + faiss_last_exception = \ + std::make_exception_ptr(std::runtime_error("Unknown error")); \ + return -1; \ + } \ + return 0; +#else +#define CATCH_AND_HANDLE \ + catch (faiss::FaissException & e) { \ + std::cerr << e.what() << '\n'; \ + faiss_last_exception = std::make_exception_ptr(e); \ + return -2; \ + } \ + catch (std::exception & e) { \ + std::cerr << e.what() << '\n'; \ + faiss_last_exception = std::make_exception_ptr(e); \ + return -4; \ + } \ + catch (...) { \ + std::cerr << "Unrecognized exception!\n"; \ + faiss_last_exception = \ + std::make_exception_ptr(std::runtime_error("Unknown error")); \ + return -1; \ + } \ + return 0; +#endif + +#define DEFINE_GETTER(clazz, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz* obj) { \ + return static_cast( \ + reinterpret_cast(obj)->name); \ + } + +#define DEFINE_GETTER_SUBCLASS(clazz, parent, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz* obj) { \ + return static_cast( \ + reinterpret_cast(obj)->name); \ + } + +#define DEFINE_GETTER_PERMISSIVE(clazz, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz* obj) { \ + return (ty)(reinterpret_cast(obj)->name); \ + } + +#define DEFINE_GETTER_SUBCLASS_PERMISSIVE(clazz, parent, ty, name) \ + ty faiss_##clazz##_##name(const Faiss##clazz* obj) { \ + return (ty)(reinterpret_cast(obj)->name); \ + } + +#define DEFINE_SETTER(clazz, ty, name) \ + void faiss_##clazz##_set_##name(Faiss##clazz* obj, ty val) { \ + reinterpret_cast(obj)->name = val; \ + } + +#define DEFINE_SETTER_STATIC(clazz, ty_to, ty_from, name) \ + void faiss_##clazz##_set_##name(Faiss##clazz* obj, ty_from val) { \ + reinterpret_cast(obj)->name = static_cast(val); \ + } + +#define DEFINE_DESTRUCTOR(clazz) \ + void faiss_##clazz##_free(Faiss##clazz* obj) { \ + delete reinterpret_cast(obj); \ + } + +#define DEFINE_INDEX_DOWNCAST(clazz) \ + Faiss##clazz* faiss_##clazz##_cast(FaissIndex* index) { \ + return reinterpret_cast(dynamic_cast( \ + reinterpret_cast(index))); \ + } + +#endif diff --git a/c_api/utils/distances_c.cpp b/c_api/utils/distances_c.cpp new file mode 100644 index 0000000..05872e1 --- /dev/null +++ b/c_api/utils/distances_c.cpp @@ -0,0 +1,102 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c++ -*- + +#include "distances_c.h" +#include +#include + +void faiss_pairwise_L2sqr( + int64_t d, + int64_t nq, + const float* xq, + int64_t nb, + const float* xb, + float* dis, + int64_t ldq, + int64_t ldb, + int64_t ldd) { + faiss::pairwise_L2sqr(d, nq, xq, nb, xb, dis, ldq, ldb, ldd); +} + +void faiss_pairwise_L2sqr_with_defaults( + int64_t d, + int64_t nq, + const float* xq, + int64_t nb, + const float* xb, + float* dis) { + faiss::pairwise_L2sqr(d, nq, xq, nb, xb, dis); +} + +void faiss_fvec_inner_products_ny( + float* ip, + const float* x, + const float* y, + size_t d, + size_t ny) { + faiss::fvec_inner_products_ny(ip, x, y, d, ny); +} + +void faiss_fvec_L2sqr_ny( + float* dis, + const float* x, + const float* y, + size_t d, + size_t ny) { + faiss::fvec_L2sqr_ny(dis, x, y, d, ny); +} + +float faiss_fvec_norm_L2sqr(const float* x, size_t d) { + return faiss::fvec_norm_L2sqr(x, d); +} + +void faiss_fvec_norms_L2(float* norms, const float* x, size_t d, size_t nx) { + faiss::fvec_norms_L2(norms, x, d, nx); +} + +void faiss_fvec_norms_L2sqr(float* norms, const float* x, size_t d, size_t nx) { + faiss::fvec_norms_L2sqr(norms, x, d, nx); +} + +void faiss_fvec_renorm_L2(size_t d, size_t nx, float* x) { + faiss::fvec_renorm_L2(d, nx, x); +} + +void faiss_set_distance_compute_blas_threshold(int value) { + faiss::distance_compute_blas_threshold = value; +} + +int faiss_get_distance_compute_blas_threshold() { + return faiss::distance_compute_blas_threshold; +} + +void faiss_set_distance_compute_blas_query_bs(int value) { + faiss::distance_compute_blas_query_bs = value; +} + +int faiss_get_distance_compute_blas_query_bs() { + return faiss::distance_compute_blas_query_bs; +} + +void faiss_set_distance_compute_blas_database_bs(int value) { + faiss::distance_compute_blas_database_bs = value; +} + +int faiss_get_distance_compute_blas_database_bs() { + return faiss::distance_compute_blas_database_bs; +} + +void faiss_set_distance_compute_min_k_reservoir(int value) { + faiss::distance_compute_min_k_reservoir = value; +} + +int faiss_get_distance_compute_min_k_reservoir() { + return faiss::distance_compute_min_k_reservoir; +} diff --git a/c_api/utils/distances_c.h b/c_api/utils/distances_c.h new file mode 100644 index 0000000..1ec54a9 --- /dev/null +++ b/c_api/utils/distances_c.h @@ -0,0 +1,109 @@ +/** + * 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. + */ + +// Copyright 2004-present Facebook. All Rights Reserved. +// -*- c -*- + +#ifndef FAISS_DISTANCES_C_H +#define FAISS_DISTANCES_C_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/********************************************************* + * Optimized distance/norm/inner prod computations + *********************************************************/ + +/// Compute pairwise distances between sets of vectors +void faiss_pairwise_L2sqr( + int64_t d, + int64_t nq, + const float* xq, + int64_t nb, + const float* xb, + float* dis, + int64_t ldq, + int64_t ldb, + int64_t ldd); + +/// Compute pairwise distances between sets of vectors +/// arguments from "faiss_pairwise_L2sqr" +/// ldq equal -1 by default +/// ldb equal -1 by default +/// ldd equal -1 by default +void faiss_pairwise_L2sqr_with_defaults( + int64_t d, + int64_t nq, + const float* xq, + int64_t nb, + const float* xb, + float* dis); + +/// compute the inner product between nx vectors x and one y +void faiss_fvec_inner_products_ny( + float* ip, /* output inner product */ + const float* x, + const float* y, + size_t d, + size_t ny); + +/// compute ny square L2 distance between x and a set of contiguous y vectors +void faiss_fvec_L2sqr_ny( + float* dis, + const float* x, + const float* y, + size_t d, + size_t ny); + +/// squared norm of a vector +float faiss_fvec_norm_L2sqr(const float* x, size_t d); + +/// compute the L2 norms for a set of vectors +void faiss_fvec_norms_L2(float* norms, const float* x, size_t d, size_t nx); + +/// same as fvec_norms_L2, but computes squared norms +void faiss_fvec_norms_L2sqr(float* norms, const float* x, size_t d, size_t nx); + +/// L2-renormalize a set of vector. Nothing done if the vector is 0-normed +void faiss_fvec_renorm_L2(size_t d, size_t nx, float* x); + +/// Setter of threshold value on nx above which we switch to BLAS to compute +/// distances +void faiss_set_distance_compute_blas_threshold(int value); + +/// Getter of threshold value on nx above which we switch to BLAS to compute +/// distances +int faiss_get_distance_compute_blas_threshold(); + +/// Setter of block sizes value for BLAS distance computations +void faiss_set_distance_compute_blas_query_bs(int value); + +/// Getter of block sizes value for BLAS distance computations +int faiss_get_distance_compute_blas_query_bs(); + +/// Setter of block sizes value for BLAS distance computations +void faiss_set_distance_compute_blas_database_bs(int value); + +/// Getter of block sizes value for BLAS distance computations +int faiss_get_distance_compute_blas_database_bs(); + +/// Setter of number of results we switch to a reservoir to collect results +/// rather than a heap +void faiss_set_distance_compute_min_k_reservoir(int value); + +/// Getter of number of results we switch to a reservoir to collect results +/// rather than a heap +int faiss_get_distance_compute_min_k_reservoir(); + +#ifdef __cplusplus +} +#endif + +#endif