redzed-tda 0.1.0__tar.gz

redzed_tda-0.1.0/CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.15...3.31)
+project(redzed LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Development.Module (not the full Development) is what a extension module needs,
+# and is the component that works when there are no static Python libraries around
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_core cpp/bindings.cpp)
+
+target_compile_definitions(_core PRIVATE
+    REDZED_NO_MAIN      # drop the command line driver in redzed.cpp
+    NDEBUG
+)
+
+if(MSVC)
+    target_compile_options(_core PRIVATE /O2)
+    # windows.h defines min and max as macros, which breaks std::max in redzed.cpp
+    target_compile_definitions(_core PRIVATE NOMINMAX WIN32_LEAN_AND_MEAN)
+else()
+    target_compile_options(_core PRIVATE -O3)
+endif()
+
+install(TARGETS _core DESTINATION redzed_tda)

redzed_tda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Kershaw
+
+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.

redzed_tda-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: redzed-tda
+Version: 0.1.0
+Summary: Fast Vietoris-Rips persistent homology
+Keywords: topology,persistent homology,vietoris-rips,tda
+Author-Email: Chris Kapulkin <krzysztof.r.kapulkin@vanderbilt.edu>, Nathan Kershaw <nkershaw@uwo.ca>
+Maintainer-Email: Nathan Kershaw <nkershaw@uwo.ca>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/nkershaw01/RedZeD
+Project-URL: Source, https://github.com/nkershaw01/RedZeD/tree/main/python
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Description-Content-Type: text/markdown
+
+# redzed-tda
+
+Fast Vietoris–Rips persistent homology, implemented in C++ with a NumPy interface.
+
+This is the Python package for **RedZeD**, an algorithm to compute Vietoris-Rips
+persistent homology. A key technique is *active enumeration*, allowing one to avoid enumerating 
+almost all (n+1) birth simplices in a filtration.
+RedZeD often gives a considerable improvement in both time and memory over 
+existing implementations. Full details are in the paper:
+
+> Chris Kapulkin and Nathan Kershaw.
+> *RedZeD: Computing persistent homology by Reduction to Zero Differentials.*
+> arXiv:2606.06310 (2026). <https://arxiv.org/abs/2606.06310>
+
+The [main repository](https://github.com/nkershaw01/RedZeD) also holds the
+reference Julia implementation.
+
+If you encounter any errors or bugs, please email nkershaw@uwo.ca.
+
+## Install
+
+```bash
+pip install redzed-tda
+```
+
+The distribution is `redzed-tda` and the import name is `redzed_tda`. (The name
+`redzed` on PyPI belongs to an unrelated project.)
+
+Wheels are provided for Linux, macOS and Windows, so no compiler is needed.
+
+If no wheel matches your platform, or your Python version is newer than the last
+release, pip falls back to building from source. That needs a C++17 compiler on
+your machine. On Windows the compiler must be MSVC, not MinGW.
+
+## Quick start
+
+```python
+import numpy as np
+import redzed_tda as rz
+
+points = np.random.default_rng(0).normal(size=(200, 3))
+distances = rz.pairwise_distances(points)
+
+h0, h1 = rz.rips(distances, maxdim=1)
+
+print(h1)          # (k, 2) array of [birth, death] rows
+```
+
+## Input
+
+`rips` takes a **distance matrix, not coordinates**. If your data is an array of 
+points in R^n, either form works:
+
+```python
+# square (n, n) matrix
+h0, h1 = rz.rips(rz.pairwise_distances(points), maxdim=1)
+
+# condensed vector of n(n-1)/2 values, in scipy pdist order 
+from scipy.spatial.distance import pdist
+h0, h1 = rz.rips(pdist(points), maxdim=1)
+```
+
+pairwise_distances and pdist both take in an array of points and return the 
+distance matrix. You may also pass redzed_tda.rips a square matrix constructed 
+yourself. Only the lower triangle of a square input is read, so your matrix is
+assumed symmetric with a zero diagonal. Passing a non-square array raises 
+`ValueError`, but symmetry is not checked, so the user is responsible for 
+ensuring the matrix is symmetric.
+
+## Options
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `distances` | — | Square `(n, n)` matrix or condensed `n(n-1)/2` vector. |
+| `maxdim` | `1` | Highest homology dimension. `maxdim=1` returns H0 and H1. |
+| `threshold` | `inf` | Ignore simplices with greater diameter. |
+| `simplex_pairs` | `False` | Also return the birth and death simplex associated to every interval. |
+
+## Output
+
+A list of `maxdim + 1` arrays. Entry `d` has shape `(k, 2)` and holds the
+`[birth, death]` pairs in dimension `d`:
+
+```python
+diagrams = rz.rips(distances, maxdim=2)
+h0, h1, h2 = diagrams
+```
+
+With `simplex_pairs=True` you get `(diagrams, simplices)` instead, where
+`simplices[d][i]` is a `(birth_vertices, death_vertices)` tuple corresponding to 
+`diagrams[d][i]`. The death tuple is empty for an infinite interval.
+
+## Building from source
+
+```bash
+git clone https://github.com/nkershaw01/RedZeD
+cd RedZeD/python
+pip install -e ".[test]"
+pytest
+```
+
+Requires a C++17 compiler. On Windows that must be MSVC.
+
+## Citing
+
+If you use this software in published work, please cite the paper:
+
+```bibtex
+@misc{kapulkin2026redzed,
+  title         = {RedZeD: Computing persistent homology by Reduction to Zero Differentials},
+  author        = {Kapulkin, Chris and Kershaw, Nathan},
+  year          = {2026},
+  eprint        = {2606.06310},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.CG},
+  doi           = {10.48550/arXiv.2606.06310},
+  url           = {https://arxiv.org/abs/2606.06310}
+}
+```
+
+## License
+
+MIT. See [LICENSE](https://github.com/nkershaw01/RedZeD/blob/main/python/LICENSE).

redzed_tda-0.1.0/README.md

@@ -0,0 +1,123 @@
+# redzed-tda
+
+Fast Vietoris–Rips persistent homology, implemented in C++ with a NumPy interface.
+
+This is the Python package for **RedZeD**, an algorithm to compute Vietoris-Rips
+persistent homology. A key technique is *active enumeration*, allowing one to avoid enumerating 
+almost all (n+1) birth simplices in a filtration.
+RedZeD often gives a considerable improvement in both time and memory over 
+existing implementations. Full details are in the paper:
+
+> Chris Kapulkin and Nathan Kershaw.
+> *RedZeD: Computing persistent homology by Reduction to Zero Differentials.*
+> arXiv:2606.06310 (2026). <https://arxiv.org/abs/2606.06310>
+
+The [main repository](https://github.com/nkershaw01/RedZeD) also holds the
+reference Julia implementation.
+
+If you encounter any errors or bugs, please email nkershaw@uwo.ca.
+
+## Install
+
+```bash
+pip install redzed-tda
+```
+
+The distribution is `redzed-tda` and the import name is `redzed_tda`. (The name
+`redzed` on PyPI belongs to an unrelated project.)
+
+Wheels are provided for Linux, macOS and Windows, so no compiler is needed.
+
+If no wheel matches your platform, or your Python version is newer than the last
+release, pip falls back to building from source. That needs a C++17 compiler on
+your machine. On Windows the compiler must be MSVC, not MinGW.
+
+## Quick start
+
+```python
+import numpy as np
+import redzed_tda as rz
+
+points = np.random.default_rng(0).normal(size=(200, 3))
+distances = rz.pairwise_distances(points)
+
+h0, h1 = rz.rips(distances, maxdim=1)
+
+print(h1)          # (k, 2) array of [birth, death] rows
+```
+
+## Input
+
+`rips` takes a **distance matrix, not coordinates**. If your data is an array of 
+points in R^n, either form works:
+
+```python
+# square (n, n) matrix
+h0, h1 = rz.rips(rz.pairwise_distances(points), maxdim=1)
+
+# condensed vector of n(n-1)/2 values, in scipy pdist order 
+from scipy.spatial.distance import pdist
+h0, h1 = rz.rips(pdist(points), maxdim=1)
+```
+
+pairwise_distances and pdist both take in an array of points and return the 
+distance matrix. You may also pass redzed_tda.rips a square matrix constructed 
+yourself. Only the lower triangle of a square input is read, so your matrix is
+assumed symmetric with a zero diagonal. Passing a non-square array raises 
+`ValueError`, but symmetry is not checked, so the user is responsible for 
+ensuring the matrix is symmetric.
+
+## Options
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `distances` | — | Square `(n, n)` matrix or condensed `n(n-1)/2` vector. |
+| `maxdim` | `1` | Highest homology dimension. `maxdim=1` returns H0 and H1. |
+| `threshold` | `inf` | Ignore simplices with greater diameter. |
+| `simplex_pairs` | `False` | Also return the birth and death simplex associated to every interval. |
+
+## Output
+
+A list of `maxdim + 1` arrays. Entry `d` has shape `(k, 2)` and holds the
+`[birth, death]` pairs in dimension `d`:
+
+```python
+diagrams = rz.rips(distances, maxdim=2)
+h0, h1, h2 = diagrams
+```
+
+With `simplex_pairs=True` you get `(diagrams, simplices)` instead, where
+`simplices[d][i]` is a `(birth_vertices, death_vertices)` tuple corresponding to 
+`diagrams[d][i]`. The death tuple is empty for an infinite interval.
+
+## Building from source
+
+```bash
+git clone https://github.com/nkershaw01/RedZeD
+cd RedZeD/python
+pip install -e ".[test]"
+pytest
+```
+
+Requires a C++17 compiler. On Windows that must be MSVC.
+
+## Citing
+
+If you use this software in published work, please cite the paper:
+
+```bibtex
+@misc{kapulkin2026redzed,
+  title         = {RedZeD: Computing persistent homology by Reduction to Zero Differentials},
+  author        = {Kapulkin, Chris and Kershaw, Nathan},
+  year          = {2026},
+  eprint        = {2606.06310},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.CG},
+  doi           = {10.48550/arXiv.2606.06310},
+  url           = {https://arxiv.org/abs/2606.06310}
+}
+```
+
+## License
+
+MIT. See [LICENSE](https://github.com/nkershaw01/RedZeD/blob/main/python/LICENSE).

redzed_tda-0.1.0/cpp/bindings.cpp

@@ -0,0 +1,119 @@
+// Python bindings for redzed
+
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <pybind11/stl.h>
+
+#include "redzed.cpp"
+
+namespace py = pybind11;
+
+typedef py::array_t<double, py::array::c_style | py::array::forcecast> DoubleArray;
+
+// ------------------------------------------------------------
+// Input conversion
+// ------------------------------------------------------------
+
+// Accepts either a square (n, n) matrix or a condensed 1-D vector in scipy's
+// pdist order
+static DistanceMatrix matrix_from_array(const DoubleArray& arr) {
+    DistanceMatrix D;
+
+    if (arr.ndim() == 2) {
+        if (arr.shape(0) != arr.shape(1))
+            throw std::invalid_argument("a 2-D distance matrix must be square, got shape (" +
+                                        std::to_string(arr.shape(0)) + ", " +
+                                        std::to_string(arr.shape(1)) + ")");
+        int nv = (int)arr.shape(0);
+        D.resize_lower(nv);
+        auto a = arr.unchecked<2>();
+        // only the lower triangle is read, so an asymmetric input is not an error here
+        for (int j = 1; j < nv; ++j) {
+            value_t* dst = D.mat.data() + DistanceMatrix::offset(0, j);
+            for (int i = 0; i < j; ++i) dst[i] = (value_t)a(j, i);
+        }
+    } else if (arr.ndim() == 1) {
+        int64_t m = (int64_t)arr.shape(0);
+        // invert m = nv(nv-1)/2
+        int64_t nv = (int64_t)((1.0 + std::sqrt(1.0 + 8.0 * (double)m)) / 2.0 + 0.5);
+        if (nv < 1 || nv * (nv - 1) / 2 != m)
+            throw std::invalid_argument("a condensed distance vector must hold n(n-1)/2 values, "
+                                        "and " + std::to_string(m) + " is not such a length");
+        D.resize_lower((int)nv);
+        auto a = arr.unchecked<1>();
+        int64_t k = 0;
+        for (int64_t i = 0; i < nv; ++i)
+            for (int64_t j = i + 1; j < nv; ++j)
+                D.mat[DistanceMatrix::offset((int)i, (int)j)] = (value_t)a((py::ssize_t)k++);
+    } else {
+        throw std::invalid_argument("expected a 2-D distance matrix or a 1-D condensed "
+                                    "distance vector, got a " + std::to_string(arr.ndim()) +
+                                    "-D array");
+    }
+    return D;
+}
+
+// ------------------------------------------------------------
+// Output conversion
+// ------------------------------------------------------------
+
+// one array of [birth, death] intervals per dimension
+static py::array_t<double> pairs_to_array(const std::vector<std::pair<value_t, value_t>>& v) {
+    py::array_t<double> out({(py::ssize_t)v.size(), (py::ssize_t)2});
+    auto r = out.mutable_unchecked<2>();
+    for (size_t t = 0; t < v.size(); ++t) {
+        r((py::ssize_t)t, 0) = (double)v[t].first;
+        r((py::ssize_t)t, 1) = (double)v[t].second;
+    }
+    return out;
+}
+
+// (birth_vertices, death_vertices)
+static py::list spx_to_list(const std::vector<SimplexPair>& v) {
+    py::list out;
+    for (const SimplexPair& sp : v)
+        out.append(py::make_tuple(py::cast(sp.first), py::cast(sp.second)));
+    return out;
+}
+
+// ------------------------------------------------------------
+// Entry point
+// ------------------------------------------------------------
+
+static py::object rips_impl(const DoubleArray& distances, int maxdim, double threshold,
+                            bool simplex_pairs) {
+    if (maxdim < 0)
+        throw std::invalid_argument("maxdim must be >= 0, got " + std::to_string(maxdim));
+
+    DistanceMatrix D = matrix_from_array(distances);
+    if (D.n < 1)
+        throw std::invalid_argument("need at least one point");
+
+    std::vector<std::vector<std::pair<value_t, value_t>>> pairs;
+    std::vector<std::vector<SimplexPair>> spx;
+    {
+        // the solver never touches Python, so other threads can run meanwhile
+        py::gil_scoped_release unlocked;
+        pairs = redzed(D, maxdim, (value_t)threshold, simplex_pairs,
+                       simplex_pairs ? &spx : nullptr);
+    }
+
+    py::list diagrams;
+    for (int d = 0; d <= maxdim; ++d) diagrams.append(pairs_to_array(pairs[d]));
+    if (!simplex_pairs) return diagrams;
+
+    py::list simplices;
+    for (int d = 0; d <= maxdim; ++d) simplices.append(spx_to_list(spx[d]));
+    return py::make_tuple(diagrams, simplices);
+}
+
+PYBIND11_MODULE(_core, m) {
+    m.doc() = "Compiled core of redzed: Vietoris-Rips persistent homology.";
+
+    m.def("rips", &rips_impl,
+          py::arg("distances"),
+          py::arg("maxdim") = 1,
+          py::arg("threshold") = std::numeric_limits<double>::infinity(),
+          py::arg("simplex_pairs") = false,
+          "Compute Vietoris-Rips persistence from a distance matrix.");
+}