Adding new examples for documenation. (#173)

Adding new examples to show how to build and use SVS when using the
shared library enabling LVQ/LeanVec as well as the open-source only.

---------

Co-authored-by: ethanglaser <[email protected]>
Co-authored-by: Ethan Glaser <[email protected]>

Author: aguerreb

examples/cpp/README.md

@@ -16,4 +16,6 @@
 
 # SVS C++ examples
 
+To fully leverage SVS performance optimizations, see the [shared folder](./shared) for examples that utilize LVQ and LeanVec compression via the SVS shared or static library.
+
 The examples provided here showcase SVS features. `vamana.cpp` shows search features; see the [getting started tutorial](https://intel.github.io/ScalableVectorSearch/start_cpp.html) for more details. `types.cpp` shows the types supported. `saveload.cpp` shows data structure saving and loading. `dispatcher.cpp` shows compile-time specialization with generic fallbacks.

examples/cpp/shared/CMakeLists.txt

@@ -19,7 +19,7 @@ project(svs_shared_library_example
 )
 
 # Other AVX versions can be found at https://github.com/intel/ScalableVectorSearch/releases.
-set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/v0.0.8-dev/svs-shared-library-0.0.8-NIGHTLY-20250520-256-AVX512.tar.gz")
+set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/v0.0.9/svs-shared-library-0.0.9.tar.gz")
 
 include(FetchContent)
 FetchContent_Declare(
@@ -35,6 +35,15 @@ find_library(SVS_SHARED svs_shared_library)
 set(SVS_CXX_STANDARD 20)
 SET(CMAKE_CXX_FLAGS  "-O3 -DNDEBUG -std=gnu++20 -march=native -mtune=native -Werror -Wall -Wextra -Wpedantic" )
 
-add_executable(shared shared.cpp)
-target_link_libraries(shared PUBLIC ${SVS_SHARED} svs::svs)
+# Configure path to the datasets used in these examples
+set(DATA_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/../../../data/test_dataset")
 
+function(create_example_executable exe file)
+    add_executable(${exe} ${file})
+    target_compile_definitions(${exe} PRIVATE SVS_DATA_DIR="${DATA_DIRECTORY}")
+    target_link_libraries(${exe} PUBLIC ${SVS_SHARED} svs::svs)
+endfunction()
+
+create_example_executable(shared shared.cpp)
+create_example_executable(example_vamana_with_compression_lvq example_vamana_with_compression_lvq.cpp)
+create_example_executable(example_vamana_with_compression example_vamana_with_compression.cpp)

examples/cpp/shared/README.md

@@ -14,9 +14,11 @@
   ~ limitations under the License.
 -->
 
-A simple example to use SVS shared library.
+These examples utilize LVQ and LeanVec interfaces which are available when linking to a SVS shared/static library, which are published with [releases](https://github.com/intel/ScalableVectorSearch/releases). Note that these examples will _not_ run after building the open source codebase without the shared/static library. These examples include:
+- [example_vamana_with_compression.cpp](./example_vamana_with_compression.cpp): Demonstrates building, searching, saving, and reloading an index with a LeanVec-compressed dataset.
+- [example_vamana_with_compression_lvq.cpp](./example_vamana_with_compression_lvq.cpp): Demonstrates building, searching, saving, and reloading an index with a LVQ-compressed dataset.
 
-Follow the commands below to compile and use SVS shared library:
+See [CMakeLists.txt](./CMakeLists.txt) for details on linking to the SVS shared library and follow the commands below to compile and use the SVS shared library to run shared.cpp example:
 
 ```
 mkdir build

examples/cpp/shared/example_vamana_with_compression.cpp

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SVS
+#include "svs/core/recall.h"
+#include "svs/extensions/flat/leanvec.h"
+#include "svs/extensions/flat/lvq.h"
+#include "svs/extensions/vamana/leanvec.h"
+#include "svs/extensions/vamana/lvq.h"
+#include "svs/orchestrators/dynamic_vamana.h"
+#include "svs/orchestrators/exhaustive.h"
+#include "svs/orchestrators/vamana.h"
+
+
+int main() {
+    // STEP 1: Compress Data with LeanVec, reducing dimensionality to leanvec_dim dimensions and using 
+    // 4 and 8 bits for primary and secondary levels respectively.
+    //! [Compress data]    
+    const size_t num_threads = 4;
+    size_t padding = 32;
+    size_t leanvec_dim = 64;
+    auto threadpool = svs::threads::as_threadpool(num_threads);
+    auto loaded = svs::VectorDataLoader<float>(std::filesystem::path(SVS_DATA_DIR) / "data_f32.svs").load();    
+    auto data = svs::leanvec::LeanDataset<svs::leanvec::UsingLVQ<4>, svs::leanvec::UsingLVQ<8>, svs::Dynamic, svs::Dynamic>::reduce(
+		     loaded, std::nullopt, threadpool, padding, svs::lib::MaybeStatic<svs::Dynamic>(leanvec_dim)
+		);
+    //! [Compress data]
+
+
+    // STEP 2: Build Vamana Index    
+    //! [Index Build]
+    auto parameters = svs::index::vamana::VamanaBuildParameters{};
+    svs::Vamana index = svs::Vamana::build<float>(parameters, data, svs::distance::DistanceL2(), num_threads);
+    //! [Index Build]
+
+    // STEP 3: Search the Index
+    //! [Perform Queries]
+    const size_t search_window_size = 50;
+    const size_t n_neighbors = 10;
+    index.set_search_window_size(search_window_size);
+
+    auto queries = svs::load_data<float>(std::filesystem::path(SVS_DATA_DIR) / "queries_f32.fvecs");
+    auto results = index.search(queries, n_neighbors);
+    //! [Perform Queries]
+
+    //! [Recall]
+    auto groundtruth = svs::load_data<int>(std::filesystem::path(SVS_DATA_DIR) / "groundtruth_euclidean.ivecs");
+    double recall = svs::k_recall_at_n(groundtruth, results, n_neighbors, n_neighbors);
+
+    fmt::print("Recall@{} = {:.4f}\n", n_neighbors, recall);
+    //! [Recall]
+
+    // STEP 4: Saving and reloading the index
+    //! [Saving Loading]
+    index.save("config", "graph", "data");
+    index = svs::Vamana::assemble<float>(        
+        "config", svs::GraphLoader("graph"), svs::lib::load_from_disk<svs::leanvec::LeanDataset<svs::leanvec::UsingLVQ<4>, svs::leanvec::UsingLVQ<8>, svs::Dynamic, svs::Dynamic>>("data", padding), svs::distance::DistanceL2(), num_threads
+    );
+    //! [Saving Loading]
+    index.set_search_window_size(search_window_size);
+    recall = svs::k_recall_at_n(groundtruth, results, n_neighbors, n_neighbors);
+
+    fmt::print("Recall@{} after saving and reloading = {:.4f}\n", n_neighbors, recall);
+
+
+    return 0;
+}

examples/cpp/shared/example_vamana_with_compression_lvq.cpp

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SVS
+#include "svs/core/recall.h"
+#include "svs/extensions/flat/leanvec.h"
+#include "svs/extensions/flat/lvq.h"
+#include "svs/extensions/vamana/leanvec.h"
+#include "svs/extensions/vamana/lvq.h"
+#include "svs/orchestrators/dynamic_vamana.h"
+#include "svs/orchestrators/exhaustive.h"
+#include "svs/orchestrators/vamana.h"
+
+
+int main() {
+    // STEP 1: Compress Data with LVQ
+    //! [Compress data]
+    size_t padding = 32;
+    const size_t num_threads = 4;
+    auto threadpool = svs::threads::as_threadpool(num_threads);
+    auto loaded = svs::VectorDataLoader<float>(std::filesystem::path(SVS_DATA_DIR) / "data_f32.svs").load();
+    auto data = svs::quantization::lvq::LVQDataset<4, 8>::compress(loaded, threadpool, padding);
+    //! [Compress data]
+
+    // STEP 2: Build Vamana Index    
+    //! [Index Build]
+    auto parameters = svs::index::vamana::VamanaBuildParameters{};
+    svs::Vamana index = svs::Vamana::build<float>(parameters, data, svs::distance::DistanceL2(), num_threads);
+    //! [Index Build]
+
+    // STEP 3: Search the Index
+    //! [Perform Queries]
+    const size_t search_window_size = 40;
+    const size_t n_neighbors = 10;
+    index.set_search_window_size(search_window_size);
+
+    auto queries = svs::load_data<float>(std::filesystem::path(SVS_DATA_DIR) / "queries_f32.fvecs");
+    auto results = index.search(queries, n_neighbors);
+    //! [Perform Queries]
+
+    //! [Recall]
+    auto groundtruth = svs::load_data<int>(std::filesystem::path(SVS_DATA_DIR) / "groundtruth_euclidean.ivecs");
+    double recall = svs::k_recall_at_n(groundtruth, results, n_neighbors, n_neighbors);
+
+    fmt::print("Recall@{} = {:.4f}\n", n_neighbors, recall);
+    //! [Recall]
+
+    // STEP 4: Saving and reloading the index
+    //! [Saving Loading]
+    index.save("config", "graph", "data");
+    index = svs::Vamana::assemble<float>(
+        "config", svs::GraphLoader("graph"), svs::lib::load_from_disk<svs::quantization::lvq::LVQDataset<4, 8>>("data", padding), svs::distance::DistanceL2(), num_threads        
+    );
+    //! [Saving Loading]
+    index.set_search_window_size(search_window_size);
+    recall = svs::k_recall_at_n(groundtruth, results, n_neighbors, n_neighbors);
+
+    fmt::print("Recall@{} after saving and reloading = {:.4f}\n", n_neighbors, recall);
+
+
+    return 0;
+}