lorann 0.2__tar.gz

lorann-0.2/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.2/MANIFEST.in

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

lorann-0.2/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.2
+Name: lorann
+Version: 0.2
+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: 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>
+
+---
+
+- Lightweight 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 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 highly 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++ LDFLAGS=-L/opt/homebrew/opt/llvm/lib 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,
+    euclidean=True,
+)
+
+index.build()
+
+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)
+```
+
+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<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/TPU support in LoRANN is experimental and available only as a Python module. Currently, the GPU is used only for queries and not for index building.
+
+To use it, install the Python package and import `Lorann` from the desired submodule:
+
+```python
+from lorann_gpu.jax import Lorann
+```
+
+The available GPU submodules are `jax`, `torch`, `cupy`, and `mlx` with corresponding dependencies [Jax](https://jax.readthedocs.io/en/latest/), [PyTorch](https://pytorch.org/), [CuPy](https://cupy.dev/), or [MLX](https://github.com/ml-explore/mlx). The Jax implementation will probably be the fastest, at least on NVIDIA GPUs.
+
+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. (2024). LoRANN: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search. Advances in Neural Information Processing Systems, 37.
+
+~~~~
+@article{Jaasaari2024,
+  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},
+  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.2/README.md

@@ -0,0 +1,125 @@
+<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>
+
+---
+
+- Lightweight 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 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 highly 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++ LDFLAGS=-L/opt/homebrew/opt/llvm/lib 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,
+    euclidean=True,
+)
+
+index.build()
+
+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)
+```
+
+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<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/TPU support in LoRANN is experimental and available only as a Python module. Currently, the GPU is used only for queries and not for index building.
+
+To use it, install the Python package and import `Lorann` from the desired submodule:
+
+```python
+from lorann_gpu.jax import Lorann
+```
+
+The available GPU submodules are `jax`, `torch`, `cupy`, and `mlx` with corresponding dependencies [Jax](https://jax.readthedocs.io/en/latest/), [PyTorch](https://pytorch.org/), [CuPy](https://cupy.dev/), or [MLX](https://github.com/ml-explore/mlx). The Jax implementation will probably be the fastest, at least on NVIDIA GPUs.
+
+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. (2024). LoRANN: Low-Rank Matrix Factorization for Approximate Nearest Neighbor Search. Advances in Neural Information Processing Systems, 37.
+
+~~~~
+@article{Jaasaari2024,
+  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},
+  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.2/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.2/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.2/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