Rename opt_l to l_search (#411)

jparismorgan · web-flow · commit 6bb3ce103b1b · 2024-06-12T10:59:09.000+02:00
diff --git a/apis/python/src/tiledb/vector_search/type_erased_module.cc b/apis/python/src/tiledb/vector_search/type_erased_module.cc
@@ -341,13 +341,13 @@ void init_type_erased_module(py::module_& m) {
           [](IndexVamana& index,
              FeatureVectorArray& vectors,
              size_t top_k,
-             size_t opt_l) {
-            auto r = index.query(vectors, top_k, opt_l);
+             size_t l_search) {
+            auto r = index.query(vectors, top_k, l_search);
             return make_python_pair(std::move(r));
           },
           py::arg("vectors"),
           py::arg("top_k"),
-          py::arg("opt_l"))
+          py::arg("l_search"))
       .def(
           "write_index",
           [](IndexVamana& index,
diff --git a/apis/python/src/tiledb/vector_search/vamana_index.py b/apis/python/src/tiledb/vector_search/vamana_index.py
@@ -97,7 +97,7 @@ def query_internal(
         self,
         queries: np.ndarray,
         k: int = 10,
-        opt_l: Optional[int] = 100,
+        l_search: Optional[int] = 100,
         **kwargs,
     ):
         """
@@ -109,17 +109,17 @@ def query_internal(
             2D array of query vectors. This can be used as a batch query interface by passing multiple queries in one call.
         k: int
             Number of results to return per query vector.
-        opt_l: int
+        l_search: int
             How deep to search. Should be >= k, and if it's not, we will set it to k.
         """
         if self.size == 0:
             return np.full((queries.shape[0], k), MAX_FLOAT32), np.full(
                 (queries.shape[0], k), MAX_UINT64
             )
 
-        if opt_l < k:
-            warnings.warn(f"opt_l ({opt_l}) should be >= k ({k}), setting to k")
-            opt_l = k
+        if l_search < k:
+            warnings.warn(f"l_search ({l_search}) should be >= k ({k}), setting to k")
+            l_search = k
 
         if queries.ndim == 1:
             queries = np.array([queries])
@@ -128,7 +128,7 @@ def query_internal(
             queries = queries.copy(order="F")
         queries_feature_vector_array = vspy.FeatureVectorArray(queries)
 
-        distances, ids = self.index.query(queries_feature_vector_array, k, opt_l)
+        distances, ids = self.index.query(queries_feature_vector_array, k, l_search)
 
         return np.array(distances, copy=False), np.array(ids, copy=False)
 
diff --git a/apis/python/test/test_ingestion.py b/apis/python/test/test_ingestion.py
@@ -1244,14 +1244,14 @@ def test_ingestion_with_additions_and_timetravel(tmp_path):
 
         index_uri = move_local_index_to_new_location(index_uri)
         index = index_class(uri=index_uri)
-        _, result = index.query(queries, k=k, nprobe=partitions, opt_l=k * 2)
+        _, result = index.query(queries, k=k, nprobe=partitions, l_search=k * 2)
         assert 0.45 < accuracy(result, gt_i)
 
         if index_type == "IVF_PQ":
             # TODO(SC-48888): Fix consolidation for IVF_PQ.
             continue
         index = index.consolidate_updates()
-        _, result = index.query(queries, k=k, nprobe=partitions, opt_l=k * 2)
+        _, result = index.query(queries, k=k, nprobe=partitions, l_search=k * 2)
         assert 0.45 < accuracy(result, gt_i)
 
         assert vfs.dir_size(index_uri) > 0
diff --git a/apis/python/test/test_object_index.py b/apis/python/test/test_object_index.py
@@ -263,7 +263,7 @@ def test_object_index(tmp_path):
 
         evaluate_query(
             index_uri=index_uri,
-            query_kwargs={"nprobe": 10, "opt_l": 250},
+            query_kwargs={"nprobe": 10, "l_search": 250},
             dim_id=42,
             vector_dim_offset=0,
         )
@@ -273,7 +273,7 @@ def test_object_index(tmp_path):
         index.update_index(partitions=10)
         evaluate_query(
             index_uri=index_uri,
-            query_kwargs={"nprobe": 10, "opt_l": 500},
+            query_kwargs={"nprobe": 10, "l_search": 500},
             dim_id=42,
             vector_dim_offset=0,
         )
@@ -289,7 +289,7 @@ def test_object_index(tmp_path):
         index.update_index(partitions=10)
         evaluate_query(
             index_uri=index_uri,
-            query_kwargs={"nprobe": 10, "opt_l": 500},
+            query_kwargs={"nprobe": 10, "l_search": 500},
             dim_id=1042,
             vector_dim_offset=0,
         )
@@ -305,7 +305,7 @@ def test_object_index(tmp_path):
         index.update_index(partitions=10)
         evaluate_query(
             index_uri=index_uri,
-            query_kwargs={"nprobe": 10, "opt_l": 500},
+            query_kwargs={"nprobe": 10, "l_search": 500},
             dim_id=2042,
             vector_dim_offset=1000,
         )
diff --git a/apis/python/test/test_type_erased_module.py b/apis/python/test/test_type_erased_module.py
@@ -285,7 +285,7 @@ def test_construct_IndexVamana():
 
 
 def test_construct_IndexVamana_with_empty_vector(tmp_path):
-    opt_l = 100
+    l_search = 100
     k_nn = 10
     index_uri = os.path.join(tmp_path, "array")
     dimensions = 128
@@ -313,7 +313,7 @@ def test_construct_IndexVamana_with_empty_vector(tmp_path):
 
     a.train(training_set)
 
-    s, t = a.query(query_set, k_nn, opt_l)
+    s, t = a.query(query_set, k_nn, l_search)
 
     intersections = vspy.count_intersections(t, groundtruth_set, k_nn)
     nt = np.double(t.num_vectors()) * np.double(k_nn)
@@ -322,7 +322,7 @@ def test_construct_IndexVamana_with_empty_vector(tmp_path):
 
 
 def test_inplace_build_query_IndexVamana():
-    opt_l = 100
+    l_search = 100
     k_nn = 10
 
     a = vspy.IndexVamana(id_type="uint32", feature_type="float32")
@@ -335,7 +335,7 @@ def test_inplace_build_query_IndexVamana():
     assert groundtruth_set.feature_type_string() == "uint64"
 
     a.train(training_set)
-    s, t = a.query(query_set, k_nn, opt_l)
+    s, t = a.query(query_set, k_nn, l_search)
 
     intersections = vspy.count_intersections(t, groundtruth_set, k_nn)
 
diff --git a/src/include/api/vamana_index.h b/src/include/api/vamana_index.h
@@ -217,11 +217,11 @@ class IndexVamana {
   [[nodiscard]] auto query(
       const QueryVectorArray& vectors,
       size_t top_k,
-      std::optional<size_t> opt_L = std::nullopt) {
+      std::optional<size_t> l_search = std::nullopt) {
     if (!index_) {
       throw std::runtime_error("Cannot query() because there is no index.");
     }
-    return index_->query(vectors, top_k, opt_L);
+    return index_->query(vectors, top_k, l_search);
   }
 
   void write_index(
@@ -337,7 +337,7 @@ class IndexVamana {
     query(
         const QueryVectorArray& vectors,
         size_t top_k,
-        std::optional<size_t> opt_L) = 0;
+        std::optional<size_t> l_search) = 0;
 
     virtual void write_index(
         const tiledb::Context& ctx,
@@ -424,7 +424,7 @@ class IndexVamana {
     [[nodiscard]] std::tuple<FeatureVectorArray, FeatureVectorArray> query(
         const QueryVectorArray& vectors,
         size_t top_k,
-        std::optional<size_t> opt_L) override {
+        std::optional<size_t> l_search) override {
       // @todo using index_type = size_t;
       auto dtype = vectors.feature_type();
 
@@ -435,7 +435,7 @@ class IndexVamana {
               (float*)vectors.data(),
               extents(vectors)[0],
               extents(vectors)[1]};  // @todo ??
-          auto [s, t] = impl_index_.query(qspan, top_k, opt_L);
+          auto [s, t] = impl_index_.query(qspan, top_k, l_search);
           auto x = FeatureVectorArray{std::move(s)};
           auto y = FeatureVectorArray{std::move(t)};
           return {std::move(x), std::move(y)};
@@ -445,7 +445,7 @@ class IndexVamana {
               (uint8_t*)vectors.data(),
               extents(vectors)[0],
               extents(vectors)[1]};  // @todo ??
-          auto [s, t] = impl_index_.query(qspan, top_k, opt_L);
+          auto [s, t] = impl_index_.query(qspan, top_k, l_search);
           auto x = FeatureVectorArray{std::move(s)};
           auto y = FeatureVectorArray{std::move(t)};
           return {std::move(x), std::move(y)};
diff --git a/src/include/index/vamana_index.h b/src/include/index/vamana_index.h
@@ -467,8 +467,8 @@ class vamana_index {
 
   template <query_vector_array Q>
   auto best_first_O2(
-      const Q& queries, size_t k_nn, std::optional<size_t> opt_L) {
-    size_t Lbuild = opt_L ? *opt_L : l_build_;
+      const Q& queries, size_t k_nn, std::optional<size_t> l_search) {
+    size_t Lbuild = l_search ? *l_search : l_build_;
 
     auto top_k = ColMajorMatrix<id_type>(k_nn, ::num_vectors(queries));
     auto top_k_scores =
@@ -494,8 +494,8 @@ class vamana_index {
 
   template <query_vector_array Q>
   auto best_first_O3(
-      const Q& queries, size_t k_nn, std::optional<size_t> opt_L) {
-    size_t Lbuild = opt_L ? *opt_L : l_build_;
+      const Q& queries, size_t k_nn, std::optional<size_t> l_search) {
+    size_t Lbuild = l_search ? *l_search : l_build_;
 
     auto top_k = ColMajorMatrix<id_type>(k_nn, ::num_vectors(queries));
     auto top_k_scores =
@@ -521,8 +521,8 @@ class vamana_index {
 
   template <query_vector_array Q>
   auto best_first_O4(
-      const Q& queries, size_t k_nn, std::optional<size_t> opt_L) {
-    size_t Lbuild = opt_L ? *opt_L : l_build_;
+      const Q& queries, size_t k_nn, std::optional<size_t> l_search) {
+    size_t Lbuild = l_search ? *l_search : l_build_;
 
     auto top_k = ColMajorMatrix<id_type>(k_nn, ::num_vectors(queries));
     auto top_k_scores =
@@ -548,8 +548,8 @@ class vamana_index {
 
   template <query_vector_array Q>
   auto best_first_O5(
-      const Q& queries, size_t k_nn, std::optional<size_t> opt_L) {
-    size_t Lbuild = opt_L ? *opt_L : l_build_;
+      const Q& queries, size_t k_nn, std::optional<size_t> l_search) {
+    size_t Lbuild = l_search ? *l_search : l_build_;
 
     auto top_k = ColMajorMatrix<id_type>(k_nn, ::num_vectors(queries));
     auto top_k_scores =
@@ -578,18 +578,18 @@ class vamana_index {
    * @tparam Q Type of query set
    * @param query_set Container of query vectors
    * @param k How many nearest neighbors to return
-   * @param opt_L How deep to search
+   * @param l_search How deep to search
    * @return Tuple of top k scores and top k ids
    */
   template <query_vector_array Q, class Distance = sum_of_squares_distance>
   auto query(
       const Q& query_set,
       size_t k,
-      std::optional<size_t> opt_L = std::nullopt,
+      std::optional<size_t> l_search = std::nullopt,
       Distance distance = Distance{}) {
     scoped_timer __{tdb_func__ + std::string{" (outer)"}};
 
-    size_t L = opt_L ? *opt_L : l_build_;
+    size_t L = l_search ? *l_search : l_build_;
     // L = std::min<size_t>(L, l_build_);
 
     auto top_k = ColMajorMatrix<id_type>(k, ::num_vectors(query_set));
@@ -646,16 +646,16 @@ class vamana_index {
    * @tparam Q Type of query vector
    * @param query_vec The vector to query
    * @param k How many nearest neighbors to return
-   * @param opt_L How deep to search
+   * @param l_search How deep to search
    * @return Top k scores and top k ids
    */
   template <query_vector Q, class Distance = sum_of_squares_distance>
   auto query(
       const Q& query_vec,
       size_t k,
-      std::optional<size_t> opt_L = std::nullopt,
+      std::optional<size_t> l_search = std::nullopt,
       Distance distance = Distance{}) {
-    size_t L = opt_L ? *opt_L : l_build_;
+    size_t L = l_search ? *l_search : l_build_;
     auto&& [top_k_scores, top_k, V] = greedy_search(
         graph_, feature_vectors_, medoid_, query_vec, k, L, distance, true);
 
