lorann 0.4.4__tar.gz

lorann-0.4.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Elias Jääsaari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lorann-0.4.4/MANIFEST.in

@@ -0,0 +1,5 @@
+graft lorann
+graft python/lorann
+graft python/lorann_gpu
+include README.md
+include LICENSE

lorann-0.4.4/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: lorann
+Version: 0.4.4
+Summary: Approximate Nearest Neighbor search library with extremely fast queries, tiny memory usage, and rapid indexing.
+Home-page: https://github.com/ejaasaari/lorann
+Author: Elias Jääsaari
+Author-email: elias.jaasaari@gmail.com
+License: MIT
+Keywords: vector search,approximate nearest neighbor search
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+<h1 align="center">LoRANN</h1>
+<div align="center">
+Approximate nearest neighbor search library implementing <a href="https://arxiv.org/abs/2410.18926">reduced-rank regression</a> (NeurIPS '24), a technique enabling extremely fast queries, tiny memory usage, and rapid indexing on modern embedding datasets.
+</div>
+<br/>
+
+<div align="center">
+    <a href="https://github.com/ejaasaari/lorann/actions/workflows/build.yml"><img src="https://github.com/ejaasaari/lorann/actions/workflows/build.yml/badge.svg" alt="Build status" /></a>
+    <a href="https://arxiv.org/abs/2410.18926"><img src="https://img.shields.io/badge/Paper-NeurIPS%3A_LoRANN-salmon" alt="Paper" /></a>
+    <a href="https://ejaasaari.github.io/lorann"><img src="https://img.shields.io/badge/api-reference-blue.svg" alt="Documentation" /></a>
+    <a href="https://pypi.org/project/lorann/"><img src="https://img.shields.io/pypi/v/lorann?color=blue" alt="PyPI" /></a>
+    <a href="https://github.com/ejaasaari/lorann/blob/master/LICENSE"><img src="https://img.shields.io/github/license/ejaasaari/lorann" alt="License" /></a>
+    <a href="https://github.com/ejaasaari/lorann/stargazers"><img src="https://img.shields.io/github/stars/ejaasaari/lorann" alt="GitHub stars" /></a>
+</div>
+
+---
+
+- Header-only C++17 library with Python bindings
+- Query speed matching state-of-the-art graph methods but with tiny memory usage
+- Optimized for modern high-dimensional (d > 100) embedding data sets
+- Optimized for modern CPU architectures with acceleration for AVX2, AVX-512, and ARM NEON
+- State-of-the-art query speed for GPU batch queries (experimental)
+- Supported data types: float32, float16, bfloat16, uint8, binary
+- Supported distances: (negative) inner product, Euclidean distance, cosine distance
+- Support for index serialization
+
+## Getting started
+
+### Python
+
+Install the module with `pip install lorann`
+
+> [!TIP]
+> On macOS, it is recommended to use the Homebrew version of Clang as the compiler:
+
+```shell script
+brew install llvm libomp
+CC=/opt/homebrew/opt/llvm/bin/clang CXX=/opt/homebrew/opt/llvm/bin/clang++ pip install lorann
+```
+
+A minimal example for indexing and querying a dataset using LoRANN is provided below:
+
+```python
+import lorann
+import numpy as np
+from sklearn.datasets import fetch_openml  # scikit-learn is used only for loading the data
+
+X, _ = fetch_openml("mnist_784", version=1, return_X_y=True, as_frame=False)
+X = np.ascontiguousarray(X, dtype=np.float32)
+
+data = X[:60_000]
+index = lorann.LorannIndex(
+    data=data,
+    n_clusters=256,
+    global_dim=128,
+    quantization_bits=8,
+    distance=lorann.L2,
+)
+
+index.build(verbose=False)
+
+k = 10
+approximate = index.search(X[-1], k, clusters_to_search=8, points_to_rerank=100)
+exact       = index.exact_search(X[-1], k)
+
+print('Approximate:', approximate)
+print('Exact:', exact)
+```
+
+The data matrix should have type `float32`, `float16`, `uint8`, or `uint16` ([for bfloat16](https://github.com/ashvardanian/SimSIMD?tab=readme-ov-file#half-precision-brain-float-numbers)). For binary data (packed into uint8 bytes using e.g. `numpy.packbits`), use `LorannBinaryIndex`.
+
+The distance should be either `lorann.L2` (for squared Euclidean distance), `lorann.IP` (for inner product), or `lorann.HAMMING` (only for binary data). For cosine distance, normalize vectors to unit norm and use `lorann.IP`.
+
+For a more detailed example, see [examples/example.py](examples/example.py).
+
+[Python documentation](https://eliasjaasaari.com/lorann/python.html)
+
+### C++
+
+LoRANN is a header-only library so no installation is required: just include the header `lorann/lorann.h`. A C++ compiler with C++17 support (e.g. gcc/g++ >= 7) is required.
+
+> [!TIP]
+> It is recommended to target the correct instruction set (e.g., by using `-march=native`) as LoRANN makes heavy use of SIMD intrinsics. The quantized version of LoRANN can use AVX-512 VNNI instructions, available in Intel Cascade Lake (and later) and AMD Zen 4, for improved performance.
+
+Usage is similar to the Python version:
+
+```cpp
+Lorann::Lorann<float, Lorann::SQ8Quantizer> index(data, n_samples, dim, n_clusters, global_dim);
+index.build();
+
+index.search(query, k, clusters_to_search, points_to_rerank, output);
+```
+
+For a complete example, see [examples/cpp](examples/cpp).
+
+[C++ documentation](https://eliasjaasaari.com/lorann/cpp.html)
+
+### GPU
+
+Hardware accelerators such as GPUs and TPUs can be used to speed up ANN search for queries that arrive in batches. GPU support in LoRANN is experimental and available only as a Python module. For index building, the GPU is currently used only partially.
+
+Usage is similar to the CPU version, just with a different import:
+
+```python
+from lorann_gpu import LorannIndex
+```
+
+The GPU submodule is implemented with and depends on [PyTorch](https://pytorch.org/), but a native CUDA implementation would provide better performance and will be available in the future. All index structures are by default saved as `torch.float32` to ensure numerical stability. However, for most embedding datasets, better performance can be obtained by passing `dtype=torch.float16` to the index constructor.
+
+For a complete example, see [examples/gpu_example.py](examples/gpu_example.py)
+
+## Citation
+
+If you use the library in an academic context, please consider citing the following paper:
+
+> Jääsaari, E., Hyvönen, V., Roos, T. LoRANN: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search. Advances in Neural Information Processing Systems 37 (2024): 102121-102153.
+
+~~~~
+@article{Jaasaari2024lorann,
+  title={{LoRANN}: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search},
+  author={J{\"a}{\"a}saari, Elias and Hyv{\"o}nen, Ville and Roos, Teemu},
+  journal={Advances in Neural Information Processing Systems},
+  volume={37},
+  pages={102121--102153},
+  year={2024}
+}
+~~~~
+
+## License
+
+LoRANN is available under the MIT License (see [LICENSE](LICENSE)). Note that third-party libraries in the [lorann](lorann) folder may be distributed under other open source licenses (see [licenses](licenses)).

lorann-0.4.4/README.md

@@ -0,0 +1,131 @@
+<h1 align="center">LoRANN</h1>
+<div align="center">
+Approximate nearest neighbor search library implementing <a href="https://arxiv.org/abs/2410.18926">reduced-rank regression</a> (NeurIPS '24), a technique enabling extremely fast queries, tiny memory usage, and rapid indexing on modern embedding datasets.
+</div>
+<br/>
+
+<div align="center">
+    <a href="https://github.com/ejaasaari/lorann/actions/workflows/build.yml"><img src="https://github.com/ejaasaari/lorann/actions/workflows/build.yml/badge.svg" alt="Build status" /></a>
+    <a href="https://arxiv.org/abs/2410.18926"><img src="https://img.shields.io/badge/Paper-NeurIPS%3A_LoRANN-salmon" alt="Paper" /></a>
+    <a href="https://ejaasaari.github.io/lorann"><img src="https://img.shields.io/badge/api-reference-blue.svg" alt="Documentation" /></a>
+    <a href="https://pypi.org/project/lorann/"><img src="https://img.shields.io/pypi/v/lorann?color=blue" alt="PyPI" /></a>
+    <a href="https://github.com/ejaasaari/lorann/blob/master/LICENSE"><img src="https://img.shields.io/github/license/ejaasaari/lorann" alt="License" /></a>
+    <a href="https://github.com/ejaasaari/lorann/stargazers"><img src="https://img.shields.io/github/stars/ejaasaari/lorann" alt="GitHub stars" /></a>
+</div>
+
+---
+
+- Header-only C++17 library with Python bindings
+- Query speed matching state-of-the-art graph methods but with tiny memory usage
+- Optimized for modern high-dimensional (d > 100) embedding data sets
+- Optimized for modern CPU architectures with acceleration for AVX2, AVX-512, and ARM NEON
+- State-of-the-art query speed for GPU batch queries (experimental)
+- Supported data types: float32, float16, bfloat16, uint8, binary
+- Supported distances: (negative) inner product, Euclidean distance, cosine distance
+- Support for index serialization
+
+## Getting started
+
+### Python
+
+Install the module with `pip install lorann`
+
+> [!TIP]
+> On macOS, it is recommended to use the Homebrew version of Clang as the compiler:
+
+```shell script
+brew install llvm libomp
+CC=/opt/homebrew/opt/llvm/bin/clang CXX=/opt/homebrew/opt/llvm/bin/clang++ pip install lorann
+```
+
+A minimal example for indexing and querying a dataset using LoRANN is provided below:
+
+```python
+import lorann
+import numpy as np
+from sklearn.datasets import fetch_openml  # scikit-learn is used only for loading the data
+
+X, _ = fetch_openml("mnist_784", version=1, return_X_y=True, as_frame=False)
+X = np.ascontiguousarray(X, dtype=np.float32)
+
+data = X[:60_000]
+index = lorann.LorannIndex(
+    data=data,
+    n_clusters=256,
+    global_dim=128,
+    quantization_bits=8,
+    distance=lorann.L2,
+)
+
+index.build(verbose=False)
+
+k = 10
+approximate = index.search(X[-1], k, clusters_to_search=8, points_to_rerank=100)
+exact       = index.exact_search(X[-1], k)
+
+print('Approximate:', approximate)
+print('Exact:', exact)
+```
+
+The data matrix should have type `float32`, `float16`, `uint8`, or `uint16` ([for bfloat16](https://github.com/ashvardanian/SimSIMD?tab=readme-ov-file#half-precision-brain-float-numbers)). For binary data (packed into uint8 bytes using e.g. `numpy.packbits`), use `LorannBinaryIndex`.
+
+The distance should be either `lorann.L2` (for squared Euclidean distance), `lorann.IP` (for inner product), or `lorann.HAMMING` (only for binary data). For cosine distance, normalize vectors to unit norm and use `lorann.IP`.
+
+For a more detailed example, see [examples/example.py](examples/example.py).
+
+[Python documentation](https://eliasjaasaari.com/lorann/python.html)
+
+### C++
+
+LoRANN is a header-only library so no installation is required: just include the header `lorann/lorann.h`. A C++ compiler with C++17 support (e.g. gcc/g++ >= 7) is required.
+
+> [!TIP]
+> It is recommended to target the correct instruction set (e.g., by using `-march=native`) as LoRANN makes heavy use of SIMD intrinsics. The quantized version of LoRANN can use AVX-512 VNNI instructions, available in Intel Cascade Lake (and later) and AMD Zen 4, for improved performance.
+
+Usage is similar to the Python version:
+
+```cpp
+Lorann::Lorann<float, Lorann::SQ8Quantizer> index(data, n_samples, dim, n_clusters, global_dim);
+index.build();
+
+index.search(query, k, clusters_to_search, points_to_rerank, output);
+```
+
+For a complete example, see [examples/cpp](examples/cpp).
+
+[C++ documentation](https://eliasjaasaari.com/lorann/cpp.html)
+
+### GPU
+
+Hardware accelerators such as GPUs and TPUs can be used to speed up ANN search for queries that arrive in batches. GPU support in LoRANN is experimental and available only as a Python module. For index building, the GPU is currently used only partially.
+
+Usage is similar to the CPU version, just with a different import:
+
+```python
+from lorann_gpu import LorannIndex
+```
+
+The GPU submodule is implemented with and depends on [PyTorch](https://pytorch.org/), but a native CUDA implementation would provide better performance and will be available in the future. All index structures are by default saved as `torch.float32` to ensure numerical stability. However, for most embedding datasets, better performance can be obtained by passing `dtype=torch.float16` to the index constructor.
+
+For a complete example, see [examples/gpu_example.py](examples/gpu_example.py)
+
+## Citation
+
+If you use the library in an academic context, please consider citing the following paper:
+
+> Jääsaari, E., Hyvönen, V., Roos, T. LoRANN: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search. Advances in Neural Information Processing Systems 37 (2024): 102121-102153.
+
+~~~~
+@article{Jaasaari2024lorann,
+  title={{LoRANN}: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search},
+  author={J{\"a}{\"a}saari, Elias and Hyv{\"o}nen, Ville and Roos, Teemu},
+  journal={Advances in Neural Information Processing Systems},
+  volume={37},
+  pages={102121--102153},
+  year={2024}
+}
+~~~~
+
+## License
+
+LoRANN is available under the MIT License (see [LICENSE](LICENSE)). Note that third-party libraries in the [lorann](lorann) folder may be distributed under other open source licenses (see [licenses](licenses)).

lorann-0.4.4/lorann/Eigen/AccelerateSupport

@@ -0,0 +1,52 @@
+// This file is part of Eigen, a lightweight C++ template library
+// for linear algebra.
+//
+// This Source Code Form is subject to the terms of the Mozilla
+// Public License v. 2.0. If a copy of the MPL was not distributed
+// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#ifndef EIGEN_ACCELERATESUPPORT_MODULE_H
+#define EIGEN_ACCELERATESUPPORT_MODULE_H
+
+#include "SparseCore"
+
+#include "src/Core/util/DisableStupidWarnings.h"
+
+/** \ingroup Support_modules
+ * \defgroup AccelerateSupport_Module AccelerateSupport module
+ *
+ * This module provides an interface to the Apple Accelerate library.
+ * It provides the seven following main factorization classes:
+ * - class AccelerateLLT: a Cholesky (LL^T) factorization.
+ * - class AccelerateLDLT: the default LDL^T factorization.
+ * - class AccelerateLDLTUnpivoted: a Cholesky-like LDL^T factorization with only 1x1 pivots and no pivoting
+ * - class AccelerateLDLTSBK: an LDL^T factorization with Supernode Bunch-Kaufman and static pivoting
+ * - class AccelerateLDLTTPP: an LDL^T factorization with full threshold partial pivoting
+ * - class AccelerateQR: a QR factorization
+ * - class AccelerateCholeskyAtA: a QR factorization without storing Q (equivalent to A^TA = R^T R)
+ *
+ * \code
+ * #include <Eigen/AccelerateSupport>
+ * \endcode
+ *
+ * In order to use this module, the Accelerate headers must be accessible from
+ * the include paths, and your binary must be linked to the Accelerate framework.
+ * The Accelerate library is only available on Apple hardware.
+ *
+ * Note that many of the algorithms can be influenced by the UpLo template
+ * argument. All matrices are assumed to be symmetric. For example, the following
+ * creates an LDLT factorization where your matrix is symmetric (implicit) and
+ * uses the lower triangle:
+ *
+ * \code
+ * AccelerateLDLT<SparseMatrix<float>, Lower> ldlt;
+ * \endcode
+ */
+
+// IWYU pragma: begin_exports
+#include "src/AccelerateSupport/AccelerateSupport.h"
+// IWYU pragma: end_exports
+
+#include "src/Core/util/ReenableStupidWarnings.h"
+
+#endif  // EIGEN_ACCELERATESUPPORT_MODULE_H

lorann-0.4.4/lorann/Eigen/Cholesky

@@ -0,0 +1,43 @@
+// This file is part of Eigen, a lightweight C++ template library
+// for linear algebra.
+//
+// This Source Code Form is subject to the terms of the Mozilla
+// Public License v. 2.0. If a copy of the MPL was not distributed
+// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#ifndef EIGEN_CHOLESKY_MODULE_H
+#define EIGEN_CHOLESKY_MODULE_H
+
+#include "Core"
+#include "Jacobi"
+
+#include "src/Core/util/DisableStupidWarnings.h"
+
+/** \defgroup Cholesky_Module Cholesky module
+ *
+ *
+ *
+ * This module provides two variants of the Cholesky decomposition for selfadjoint (hermitian) matrices.
+ * Those decompositions are also accessible via the following methods:
+ *  - MatrixBase::llt()
+ *  - MatrixBase::ldlt()
+ *  - SelfAdjointView::llt()
+ *  - SelfAdjointView::ldlt()
+ *
+ * \code
+ * #include <Eigen/Cholesky>
+ * \endcode
+ */
+
+// IWYU pragma: begin_exports
+#include "src/Cholesky/LLT.h"
+#include "src/Cholesky/LDLT.h"
+#ifdef EIGEN_USE_LAPACKE
+#include "src/misc/lapacke_helpers.h"
+#include "src/Cholesky/LLT_LAPACKE.h"
+#endif
+// IWYU pragma: end_exports
+
+#include "src/Core/util/ReenableStupidWarnings.h"
+
+#endif  // EIGEN_CHOLESKY_MODULE_H

lorann-0.4.4/lorann/Eigen/CholmodSupport

@@ -0,0 +1,48 @@
+// This file is part of Eigen, a lightweight C++ template library
+// for linear algebra.
+//
+// This Source Code Form is subject to the terms of the Mozilla
+// Public License v. 2.0. If a copy of the MPL was not distributed
+// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#ifndef EIGEN_CHOLMODSUPPORT_MODULE_H
+#define EIGEN_CHOLMODSUPPORT_MODULE_H
+
+#include "SparseCore"
+
+#include "src/Core/util/DisableStupidWarnings.h"
+
+#include <cholmod.h>
+
+/** \ingroup Support_modules
+ * \defgroup CholmodSupport_Module CholmodSupport module
+ *
+ * This module provides an interface to the Cholmod library which is part of the <a
+ * href="http://www.suitesparse.com">suitesparse</a> package. It provides the two following main factorization classes:
+ * - class CholmodSupernodalLLT: a supernodal LLT Cholesky factorization.
+ * - class CholmodDecomposition: a general L(D)LT Cholesky factorization with automatic or explicit runtime selection of
+ * the underlying factorization method (supernodal or simplicial).
+ *
+ * For the sake of completeness, this module also propose the two following classes:
+ * - class CholmodSimplicialLLT
+ * - class CholmodSimplicialLDLT
+ * Note that these classes does not bring any particular advantage compared to the built-in
+ * SimplicialLLT and SimplicialLDLT factorization classes.
+ *
+ * \code
+ * #include <Eigen/CholmodSupport>
+ * \endcode
+ *
+ * In order to use this module, the cholmod headers must be accessible from the include paths, and your binary must be
+ * linked to the cholmod library and its dependencies. The dependencies depend on how cholmod has been compiled. For a
+ * cmake based project, you can use our FindCholmod.cmake module to help you in this task.
+ *
+ */
+
+// IWYU pragma: begin_exports
+#include "src/CholmodSupport/CholmodSupport.h"
+// IWYU pragma: end_exports
+
+#include "src/Core/util/ReenableStupidWarnings.h"
+
+#endif  // EIGEN_CHOLMODSUPPORT_MODULE_H