bann 0.0.1__tar.gz

bann-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tuyen P
+
+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.

bann-0.0.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include bann.pyx
+recursive-include cpp_src *.cpp *.h
+global-include *.pyx *.cpp *.h

bann-0.0.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: bann
+Version: 0.0.1
+Summary: A Cython wrapper for Bregman ANN searches
+Home-page: https://github.com/tuqpham0/bann
+Author: Tuyen Pham
+Author-email: tuyen.pham@ufl.edu
+License: MIT
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Cython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: author-email
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Bregman Approximate Nearest Neighbours for Python
+This is a python wrapper for the (Decomposable) Bregman Approximate Nearest Neighbour(Bregman ANN, or BANN) package adapted by Hubert Wagner and Tuyen Pham. The original ANN package was written by David Mount and Sunil Arya. The original package uses Kd-trees to search for nearest neighbours in Euclidean space equipped with an $L^{p}$-norm. [See David Mount's page for documention for the original ANN package.](https://www.cs.umd.edu/~mount/ANN/)
+
+For a Python wrapped version of the original ANN, see:
+   - [pyANN by Dmitriy Morozov](https://mrzv.org/software/pyANN/)
+   - [PyANN by Anna Nevison](https://github.com/annacnev/pyann)
+
+#### Bregman Divergences
+Bregman divergences are measurements of generalized distances in a space. Unlike metrics, they are often assymmetric and do not globally satisfy the triangle inequality. Recently, these divergences have been useful in machine learning, with the most prominent example being the Kullback--Leibler divergence.
+
+## About
+The BANN package currently uses Kd-trees for two primary computations:
+   - (approximate) $k$-nearest neighbour searches with decomposable Bregman divergences
+   - Bregman--Hausdorff divergence for decomposable Bregman divergences
+
+Currently, this package supports the following divergences:
+   - Kullback--Leibler divergence (primal and dual)
+   - Itakura--Saito divergence (primal and dual)
+   - Squared Euclidean divergence
+
+Additional decomposable divergences can be simply added to the source code, and passing a divergence from Python is a planned implementation.
+
+### Details
+Let $D_F:\Omega\times\Omega\to [0,\infty]$ be a decomposable Bregman divergence and let $P = \\{p_n\\}^N_{n=1}$, $Q = \\{q_m\\}^M_{m=1}$ be subsets of $\Omega$.
+
+#### Bregman $k$-nn search
+For $q\in Q$, the Bregman $k$-nearest neighbour search returns the ordered list of indices $(x_1,x_2,\dots,x_k)$, such that $D_F(q\\|p_{x_1})\leq D_F(q\\|p_{x_2})\leq\cdots\leq D_F(q\\|p_{x_k})$ and $D_F(q\\|p_{x_k})\leq D_F(q\\|p_{\ell})$ for all $\ell\notin\\{x_{1},x_{2},\dots,x_{k}\\}$. As Bregman divergences are rarely symmetric, we can reverse the arguments as necessary.
+
+This package also supports $\epsilon$-approximate nearest neighbour searches, where the divergence to the reported nearest neighbour is at most $(1+\epsilon)$-times the divergence to the true nearest neighbour.
+
+[Further details of using Kd-trees with Bregman Divergences are discussed here.](https://arxiv.org/abs/2502.13425)
+
+#### Bregman—Hausdorff divergence
+The Bregman—Hausdorff divergence generalizes the Bregman divergence between two vectors to the Bregman divergence between to *sets* of vectors. The Bregman—Hausdorff divergence was introduced by Pham, Dal Poz Kouřimská, and Wagner, where they also provide algorithms for its computation. Specifically, we compute 
+$$H_{D_F}(P\|Q) = \inf \\{r\geq0 : P\subseteq\bigcup_{q\in Q}B_F(q;r)\\}$$ and $$H_{D_F}' = \inf \\{r\geq0 : P\subseteq\bigcup_{q\in Q}B'_F(q;r)\\}$$ via the shell algorithm, where $B_F(q;r)=\\{x\in \Omega\,:\, D_F(q\|x)\leq r\\}$ and $B'_F(q;r) = \\{x\in \Omega\,:\,D_F(x\|q)\leq r\\}$. Note that the directions of computations for the Bregman--Hausdorff divergences are reversed compared to the directions for the nearest neighbour searches.
+
+[The Bregman—Hausdorff divergence and shell algorithm for computation are introduced here.](https://www.mdpi.com/2504-4990/7/2/48)
+
+#### Further details
+For further details and example uses, see the [documentation](docs.md).
+## Requirements
+### Python Version
+BANN requires Python >=3.11.
+### Dependencies
+   - [Numpy](https://numpy.org/)
+## Installation
+
+## Feedback
+Bug reports, pull requests after forking, and other questions may be sent to the maintainer: tuyen.pham@ufl.edu
+## Copyright and License
+See [Copyright](COPYRIGHT) and [License](LICENSE) for copyright and license information.

bann-0.0.1/README.md

@@ -0,0 +1,51 @@
+# Bregman Approximate Nearest Neighbours for Python
+This is a python wrapper for the (Decomposable) Bregman Approximate Nearest Neighbour(Bregman ANN, or BANN) package adapted by Hubert Wagner and Tuyen Pham. The original ANN package was written by David Mount and Sunil Arya. The original package uses Kd-trees to search for nearest neighbours in Euclidean space equipped with an $L^{p}$-norm. [See David Mount's page for documention for the original ANN package.](https://www.cs.umd.edu/~mount/ANN/)
+
+For a Python wrapped version of the original ANN, see:
+   - [pyANN by Dmitriy Morozov](https://mrzv.org/software/pyANN/)
+   - [PyANN by Anna Nevison](https://github.com/annacnev/pyann)
+
+#### Bregman Divergences
+Bregman divergences are measurements of generalized distances in a space. Unlike metrics, they are often assymmetric and do not globally satisfy the triangle inequality. Recently, these divergences have been useful in machine learning, with the most prominent example being the Kullback--Leibler divergence.
+
+## About
+The BANN package currently uses Kd-trees for two primary computations:
+   - (approximate) $k$-nearest neighbour searches with decomposable Bregman divergences
+   - Bregman--Hausdorff divergence for decomposable Bregman divergences
+
+Currently, this package supports the following divergences:
+   - Kullback--Leibler divergence (primal and dual)
+   - Itakura--Saito divergence (primal and dual)
+   - Squared Euclidean divergence
+
+Additional decomposable divergences can be simply added to the source code, and passing a divergence from Python is a planned implementation.
+
+### Details
+Let $D_F:\Omega\times\Omega\to [0,\infty]$ be a decomposable Bregman divergence and let $P = \\{p_n\\}^N_{n=1}$, $Q = \\{q_m\\}^M_{m=1}$ be subsets of $\Omega$.
+
+#### Bregman $k$-nn search
+For $q\in Q$, the Bregman $k$-nearest neighbour search returns the ordered list of indices $(x_1,x_2,\dots,x_k)$, such that $D_F(q\\|p_{x_1})\leq D_F(q\\|p_{x_2})\leq\cdots\leq D_F(q\\|p_{x_k})$ and $D_F(q\\|p_{x_k})\leq D_F(q\\|p_{\ell})$ for all $\ell\notin\\{x_{1},x_{2},\dots,x_{k}\\}$. As Bregman divergences are rarely symmetric, we can reverse the arguments as necessary.
+
+This package also supports $\epsilon$-approximate nearest neighbour searches, where the divergence to the reported nearest neighbour is at most $(1+\epsilon)$-times the divergence to the true nearest neighbour.
+
+[Further details of using Kd-trees with Bregman Divergences are discussed here.](https://arxiv.org/abs/2502.13425)
+
+#### Bregman—Hausdorff divergence
+The Bregman—Hausdorff divergence generalizes the Bregman divergence between two vectors to the Bregman divergence between to *sets* of vectors. The Bregman—Hausdorff divergence was introduced by Pham, Dal Poz Kouřimská, and Wagner, where they also provide algorithms for its computation. Specifically, we compute 
+$$H_{D_F}(P\|Q) = \inf \\{r\geq0 : P\subseteq\bigcup_{q\in Q}B_F(q;r)\\}$$ and $$H_{D_F}' = \inf \\{r\geq0 : P\subseteq\bigcup_{q\in Q}B'_F(q;r)\\}$$ via the shell algorithm, where $B_F(q;r)=\\{x\in \Omega\,:\, D_F(q\|x)\leq r\\}$ and $B'_F(q;r) = \\{x\in \Omega\,:\,D_F(x\|q)\leq r\\}$. Note that the directions of computations for the Bregman--Hausdorff divergences are reversed compared to the directions for the nearest neighbour searches.
+
+[The Bregman—Hausdorff divergence and shell algorithm for computation are introduced here.](https://www.mdpi.com/2504-4990/7/2/48)
+
+#### Further details
+For further details and example uses, see the [documentation](docs.md).
+## Requirements
+### Python Version
+BANN requires Python >=3.11.
+### Dependencies
+   - [Numpy](https://numpy.org/)
+## Installation
+
+## Feedback
+Bug reports, pull requests after forking, and other questions may be sent to the maintainer: tuyen.pham@ufl.edu
+## Copyright and License
+See [Copyright](COPYRIGHT) and [License](LICENSE) for copyright and license information.