[C API] Update for compatibility with v1.5 (#858)

* [c_api] Update impl and interface for v1.5

- move IndexShards to dedicated module IndexShards_c.{h|cpp}
- remove getter/setters to unreachable fields
- reimplement faiss_IndexIVF_imbalance_factor (to use invlists)
- minor IndexIVF documentation tweaks
- Remove QueryResult, provide RangeQueryResult

* [c_api] Document FaissErrorCode

* [c_api] Update GPU impl and interface for v1.5

- Remove unavailable method setTempMemoryFraction

* [c_api] Relicense to MIT

In accordance to the rest of the project

c_api/AutoTune_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/AutoTune_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/AuxIndexStructures_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
@@ -14,14 +13,13 @@
 #include "macros_impl.h"
 #include <iostream>
 
-extern "C" {
-
 using faiss::BufferList;
 using faiss::IDSelector;
 using faiss::IDSelectorBatch;
 using faiss::IDSelectorRange;
 using faiss::RangeSearchResult;
 using faiss::RangeSearchPartialResult;
+using faiss::RangeQueryResult;
 
 DEFINE_GETTER(RangeSearchResult, size_t, nq)
 
@@ -140,6 +138,17 @@ int faiss_BufferList_copy_range(
     } 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<RangeQueryResult*>(qr)->add(dis, id);
+        return 0;
+    } CATCH_AND_HANDLE
+}
+
 DEFINE_GETTER_PERMISSIVE(RangeSearchPartialResult, FaissRangeSearchResult*, res)
 
 int faiss_RangeSearchPartialResult_new(
@@ -170,38 +179,15 @@ int faiss_RangeSearchPartialResult_set_lims(
     } CATCH_AND_HANDLE
 }
 
-/// called by range_search after do_allocation
-int faiss_RangeSearchPartialResult_set_result(
-    FaissRangeSearchPartialResult* res, int incremental) {
-    try {
-        reinterpret_cast<RangeSearchPartialResult*>(res)->set_result(
-            static_cast<bool>(incremental));
-        return 0;
-    } CATCH_AND_HANDLE
-}
-
-DEFINE_GETTER_SUBCLASS(QueryResult, RangeSearchPartialResult, idx_t, qno)
-DEFINE_GETTER_SUBCLASS(QueryResult, RangeSearchPartialResult, size_t, nres)
-DEFINE_GETTER_SUBCLASS_PERMISSIVE(QueryResult, RangeSearchPartialResult, FaissRangeSearchPartialResult*, pres)
-
 int faiss_RangeSearchPartialResult_new_result(
-    FaissRangeSearchPartialResult* res, idx_t qno, FaissQueryResult** qr) {
+    FaissRangeSearchPartialResult* res, idx_t qno, FaissRangeQueryResult** qr) {
 
     try {
-        RangeSearchPartialResult::QueryResult* q = 
+        auto q = 
             &reinterpret_cast<RangeSearchPartialResult*>(res)->new_result(qno);
         if (qr) {
-            *qr = reinterpret_cast<FaissQueryResult*>(q);
+            *qr = reinterpret_cast<FaissRangeQueryResult*>(&q);
         }
         return 0;
     } CATCH_AND_HANDLE
 }
-
-int faiss_QueryResult_add(FaissQueryResult* qr, float dis, idx_t id) {
-    try {
-        reinterpret_cast<RangeSearchPartialResult::QueryResult*>(qr)->add(dis, id);
-        return 0;
-    } CATCH_AND_HANDLE
-}
-
-}

c_api/AuxIndexStructures_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
@@ -103,6 +102,15 @@ int faiss_BufferList_copy_range(
 /// 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(
@@ -115,20 +123,8 @@ int faiss_RangeSearchPartialResult_finalize(
 int faiss_RangeSearchPartialResult_set_lims(
     FaissRangeSearchPartialResult* res);
 
-/// called by range_search after do_allocation
-int faiss_RangeSearchPartialResult_set_result(
-    FaissRangeSearchPartialResult* res, int incremental);
-
-/// result structure for a single query
-FAISS_DECLARE_CLASS(QueryResult)
-FAISS_DECLARE_GETTER(QueryResult, idx_t, qno)
-FAISS_DECLARE_GETTER(QueryResult, size_t, nres)
-FAISS_DECLARE_GETTER(QueryResult, FaissRangeSearchPartialResult*, pres)
-
 int faiss_RangeSearchPartialResult_new_result(
-    FaissRangeSearchPartialResult* res, idx_t qno, FaissQueryResult** qr);
-
-int faiss_QueryResult_add(FaissQueryResult* qr, float dis, idx_t id);
+    FaissRangeSearchPartialResult* res, idx_t qno, FaissRangeQueryResult** qr);
 
 #ifdef __cplusplus
 }

c_api/Clustering_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/Clustering_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexFlat_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexFlat_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexIVFFlat_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexIVFFlat_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexIVF_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
@@ -80,12 +79,12 @@ int faiss_IndexIVF_make_direct_map(FaissIndexIVF* index,
 }
 
 double faiss_IndexIVF_imbalance_factor (const FaissIndexIVF* index) {
-    return reinterpret_cast<const IndexIVF*>(index)->imbalance_factor();
+    return reinterpret_cast<const IndexIVF*>(index)->invlists->imbalance_factor();
 }
 
 /// display some stats about the inverted lists
 void faiss_IndexIVF_print_stats (const FaissIndexIVF* index) {
-    reinterpret_cast<const IndexIVF*>(index)->print_stats();
+    reinterpret_cast<const IndexIVF*>(index)->invlists->print_stats();
 }
 
 void faiss_IndexIVFStats_reset(FaissIndexIVFStats* stats) {

c_api/IndexIVF_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
@@ -106,10 +105,13 @@ size_t faiss_IndexIVF_get_list_size(const FaissIndexIVF* index,
 int faiss_IndexIVF_make_direct_map(FaissIndexIVF* index,
     int new_maintain_direct_map);
 
-/// 1= perfectly balanced, >1: imbalanced
+/** 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
+/// display some stats about the inverted lists of the index
 void faiss_IndexIVF_print_stats (const FaissIndexIVF* index);
 
 

c_api/IndexLSH_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexLSH_c.h

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
 

c_api/IndexShards_c.cpp

@@ -0,0 +1,44 @@
+#include "IndexShards_c.h"
+#include "IndexShards.h"
+#include "macros_impl.h"
+
+using faiss::Index;
+using faiss::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<FaissIndexShards*>(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<bool>(threaded), static_cast<bool>(successive_ids));
+        *p_index = reinterpret_cast<FaissIndexShards*>(out);
+    } CATCH_AND_HANDLE
+}
+
+int faiss_IndexShards_add_shard(FaissIndexShards* index, FaissIndex* shard) {
+    try {
+        reinterpret_cast<IndexShards*>(index)->add_shard(
+            reinterpret_cast<Index*>(shard));
+    } CATCH_AND_HANDLE
+}
+
+int faiss_IndexShards_sync_with_shard_indexes(FaissIndexShards* index) {
+    try {
+        reinterpret_cast<IndexShards*>(index)->sync_with_shard_indexes();
+    } CATCH_AND_HANDLE
+}
+
+FaissIndex* faiss_IndexShards_at(FaissIndexShards* index, int i) {
+    auto shard = reinterpret_cast<IndexShards*>(index)->at(i);
+    return reinterpret_cast<FaissIndex*>(shard);
+}

c_api/IndexShards_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 INDEXSHARDS_C_H
+#define INDEXSHARDS_C_H
+
+#include "faiss_c.h"
+#include "Index_c.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Index that concatenates the results from several sub-indexes
+ */
+FAISS_DECLARE_CLASS_INHERITED(IndexShards, Index)
+
+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);
+
+/// update metric_type and ntotal
+int faiss_IndexShards_sync_with_shard_indexes(FaissIndexShards* index);
+
+FaissIndex* faiss_IndexShards_at(FaissIndexShards* index, int i);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

c_api/Index_c.cpp

@@ -1,8 +1,7 @@
 /**
- * Copyright (c) 2015-present, Facebook, Inc.
- * All rights reserved.
+ * Copyright (c) Facebook, Inc. and its affiliates.
  *
- * This source code is licensed under the BSD+Patents license found in the
+ * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */