Restructure benchmarks: add C++/Python/GPU suites, relocate legacy

.github/actions/build_cmake/action.yml

@@ -273,7 +273,7 @@ runs:
       shell: bash
       run: |
         conda list --show-channel-urls
-        find ./build/perf_tests/ -executable -type f -name "bench*" -exec '{}' -v \;
+        find ./build/benchs/legacy/perf_tests/ -executable -type f -name "bench*" -exec '{}' -v \;
     - name: Install Python extension
       if: inputs.metal != 'ON'
       shell: bash

CMakeLists.txt

@@ -85,7 +85,9 @@ set(CMAKE_CXX_STANDARD 20)
 list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
 # Valid values are "generic", "avx2", "avx512", "avx512_spr", "sve".
-option(FAISS_OPT_LEVEL "" "generic")
+set(FAISS_OPT_LEVEL "generic" CACHE STRING
+  "FAISS SIMD optimization level (generic, avx2, avx512, avx512_spr, sve, dd).")
+set_property(CACHE FAISS_OPT_LEVEL PROPERTY STRINGS generic avx2 avx512 avx512_spr sve dd)
 option(FAISS_ENABLE_GPU "Enable support for GPU indexes." ON)
 option(FAISS_GPU_STATIC "Link GPU libraries statically." OFF)
 option(FAISS_ENABLE_CUVS "Enable cuVS for GPU indexes." OFF)
@@ -148,16 +150,21 @@ endif()
 
 if(FAISS_ENABLE_EXTRAS)
   add_subdirectory(demos)
-  add_subdirectory(benchs)
+  add_subdirectory(benchs/legacy/benchs)
   add_subdirectory(tutorial/cpp)
 endif()
 
+option(FAISS_BUILD_BENCHMARKS "Build the benchmark suite" OFF)
+if(FAISS_BUILD_BENCHMARKS)
+  add_subdirectory(benchs)
+endif()
+
 # CTest must be included in the top level to enable `make test` target.
 include(CTest)
 if(BUILD_TESTING)
   add_subdirectory(tests)
   if(NOT WIN32 AND NOT CMAKE_CROSSCOMPILING)
-    add_subdirectory(perf_tests)
+    add_subdirectory(benchs/legacy/perf_tests)
   endif()
   if(FAISS_ENABLE_GPU)
     if(FAISS_ENABLE_ROCM)

INSTALL.md

@@ -140,6 +140,9 @@ Several options can be passed to CMake, among which:
     are `ON` and `OFF`),
   - `-DFAISS_ENABLE_SVS=ON` in order to enable the Intel(R) Scalable Vector Search (SVS) integration (default is `OFF`, possible values are `ON` and `OFF`).
     Note: This will download and build the SVS runtime library (`libsvs_runtime.so`). When installing the python package, this library will be copied into the package directory. For C++ usage, ensure this library is in your library path.
+  - `-DFAISS_BUILD_BENCHMARKS=ON` in order to build the C++ benchmark suite in
+  `benchs/` (default is `OFF`, possible values are `ON` and `OFF`). See
+  [Benchmark suite](#benchmark-suite) below.
 - optimization-related options:
   - `-DCMAKE_BUILD_TYPE=Release` in order to enable generic compiler
   optimization options (enables `-O3` on gcc for instance),
@@ -269,6 +272,34 @@ $ ./build/demos/demo_ivfpq_indexing_gpu
 This produces the GPU code equivalent to the CPU `demo_ivfpq_indexing`. It also
 shows how to translate indexes from/to a GPU.
 
+### Benchmark suite
+
+Faiss ships a performance benchmark suite under [`benchs/`](benchs/README.md)
+covering both low-level kernels (distances, quantizers, hamming, heap, k-means,
+...) and end-to-end index operations (build, add, search across Flat, IVF,
+fast-scan, PQ, HNSW/NSG, binary, RaBitQ, and more). A C++ suite uses
+[Google Benchmark](https://github.com/google/benchmark) and a companion Python
+suite uses [pytest-benchmark](https://pytest-benchmark.readthedocs.io/); both
+emit machine-readable JSON for regression tracking.
+
+The suite is not built by default. Enable it with `-DFAISS_BUILD_BENCHMARKS=ON`,
+and always build in `Release` — an unoptimized build produces meaningless
+numbers. From the root of the source directory:
+
+``` shell
+$ cmake -B build \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DFAISS_BUILD_BENCHMARKS=ON \
+    -DFAISS_OPT_LEVEL=dd \
+    -DFAISS_ENABLE_GPU=OFF \
+    -DFAISS_ENABLE_PYTHON=OFF
+$ cmake --build build --config Release --target benchmarks -j$(nproc)
+```
+
+This builds all benchmark executables into `build/benchs/cpp/`. See the
+[benchmarks README](benchs/README.md) for running instructions, the full
+list of benchmarks, and the C++ ↔ Python mapping.
+
 ### A real-life benchmark
 
 A longer example runs and evaluates Faiss on the SIFT1M dataset. To run it,

README.md

@@ -37,8 +37,8 @@ The following are entry points for documentation:
 
 - the full documentation can be found on the [wiki page](https://github.com/facebookresearch/faiss/wiki), including a [tutorial](https://github.com/facebookresearch/faiss/wiki/Getting-started), a [FAQ](https://github.com/facebookresearch/faiss/wiki/FAQ) and a [troubleshooting section](https://github.com/facebookresearch/faiss/wiki/Troubleshooting)
 - the [doxygen documentation](https://faiss.ai/) gives per-class information extracted from code comments
-- to reproduce results from our research papers, [Polysemous codes](https://arxiv.org/abs/1609.01882) and [Billion-scale similarity search with GPUs](https://arxiv.org/abs/1702.08734), refer to the [benchmarks README](benchs/README.md). For [
-Link and code: Fast indexing with graphs and compact regression codes](https://arxiv.org/abs/1804.09996), see the [link_and_code README](benchs/link_and_code)
+- to reproduce results from our research papers, [Polysemous codes](https://arxiv.org/abs/1609.01882) and [Billion-scale similarity search with GPUs](https://arxiv.org/abs/1702.08734), refer to the [benchmarks README](benchs/legacy/benchs/README.md). For [
+Link and code: Fast indexing with graphs and compact regression codes](https://arxiv.org/abs/1804.09996), see the [link_and_code README](benchs/legacy/benchs/link_and_code)
 
 ## Authors
 

benchs/CMakeLists.txt

@@ -3,15 +3,11 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-find_package(BLAS REQUIRED)
-find_package(LAPACK REQUIRED)
-find_package(OpenMP REQUIRED)
+# C++ benchmark suite (Google Benchmark). The Python suite in python/ is
+# driven by pytest and needs no CMake integration.
+add_subdirectory(cpp)
 
-add_executable(bench_ivf_selector EXCLUDE_FROM_ALL bench_ivf_selector.cpp)
-target_link_libraries(bench_ivf_selector PRIVATE faiss_avx512 ${BLAS_LIBRARIES} ${LAPACK_LIBRARIES} OpenMP::OpenMP_CXX)
-target_compile_options(bench_ivf_selector PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-mavx2 -mfma -mf16c -mavx512f -mavx512cd -mavx512vl -mavx512dq -mavx512bw -mpopcnt>)
-
-add_executable(bench_result_handler_overhead EXCLUDE_FROM_ALL
-  bench_result_handler_overhead.cpp)
-target_link_libraries(bench_result_handler_overhead PRIVATE faiss_avx512 ${BLAS_LIBRARIES} ${LAPACK_LIBRARIES} OpenMP::OpenMP_CXX)
-target_compile_options(bench_result_handler_overhead PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-mavx2 -mfma -mf16c -mavx512f -mavx512cd -mavx512vl -mavx512dq -mavx512bw -mpopcnt>)
+# GPU benchmark suite (Google Benchmark). Added after cpp/ so it can reuse the
+# FetchContent'd googlebenchmark target and the `benchmarks` meta-target; the
+# subdirectory no-ops when FAISS_ENABLE_GPU=OFF.
+add_subdirectory(gpu)