Add HITS use case

Author: mtsokol

.github/workflows/ci.yml

@@ -68,7 +68,7 @@ jobs:
     - name: Build and install Sparse
       run: |
         pip install -U setuptools wheel
-        pip install '.[finch]' scipy
+        pip install '.[finch]' scipy dask networkx graphblas-algorithms
     - name: Run examples
       run: ci/test_examples.sh
 

ci/Finch-array-api-skips.txt

@@ -4,3 +4,5 @@ array_api_tests/test_searching_functions.py::test_nonzero_zerodim_error
 array_api_tests/test_special_cases.py::test_unary[sign((x_i is -0 or x_i == +0)) -> 0]
 # `broadcast_to` is not defined in Finch, hangs as xfail
 array_api_tests/test_searching_functions.py::test_where
+# `test_solve` is not defined in Finch, hangs as xfail
+array_api_tests/test_linalg.py::test_solve

ci/Finch-array-api-xfails.txt

@@ -59,7 +59,17 @@ array_api_tests/test_signatures.py::test_extension_func_signature[linalg.pinv]
 array_api_tests/test_signatures.py::test_extension_func_signature[linalg.svdvals]
 array_api_tests/test_signatures.py::test_extension_func_signature[linalg.tensordot]
 array_api_tests/test_signatures.py::test_extension_func_signature[linalg.vecdot]
-array_api_tests/test_signatures.py::test_extension_func_signature[linalg.vector_norm]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.det]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.diagonal]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.eigh]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.eigvalsh]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.inv]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.matrix_power]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.qr]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.slogdet]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.solve]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.svd]
+array_api_tests/test_signatures.py::test_extension_func_signature[linalg.trace]
 # Array object namespace
 array_api_tests/test_signatures.py::test_array_method_signature[__dlpack__]
 array_api_tests/test_signatures.py::test_array_method_signature[__dlpack_device__]
@@ -116,7 +126,6 @@ array_api_tests/test_has_names.py::test_has_names[linalg-svdvals]
 array_api_tests/test_has_names.py::test_has_names[linalg-tensordot]
 array_api_tests/test_has_names.py::test_has_names[linalg-trace]
 array_api_tests/test_has_names.py::test_has_names[linalg-vecdot]
-array_api_tests/test_has_names.py::test_has_names[linalg-vector_norm]
 array_api_tests/test_has_names.py::test_has_names[statistical-cumulative_sum]
 array_api_tests/test_has_names.py::test_has_names[statistical-mean]
 array_api_tests/test_has_names.py::test_has_names[statistical-std]
@@ -173,6 +182,27 @@ array_api_tests/test_indexing_functions.py::test_take
 # not implemented
 array_api_tests/test_linalg.py::test_matrix_transpose
 array_api_tests/test_linalg.py::test_vecdot
+array_api_tests/test_linalg.py::test_eigh
+array_api_tests/test_linalg.py::test_eigvalsh
+array_api_tests/test_linalg.py::test_inv
+array_api_tests/test_linalg.py::test_linalg_matmul
+array_api_tests/test_linalg.py::test_matrix_norm
+array_api_tests/test_linalg.py::test_matrix_power
+array_api_tests/test_linalg.py::test_matrix_rank
+array_api_tests/test_linalg.py::test_linalg_matrix_transpose
+array_api_tests/test_linalg.py::test_outer
+array_api_tests/test_linalg.py::test_pinv
+array_api_tests/test_linalg.py::test_qr
+array_api_tests/test_linalg.py::test_slogdet
+array_api_tests/test_linalg.py::test_cholesky
+array_api_tests/test_linalg.py::test_det
+array_api_tests/test_linalg.py::test_diagonal
+array_api_tests/test_linalg.py::test_vector_norm
+array_api_tests/test_linalg.py::test_svdvals
+array_api_tests/test_linalg.py::test_svd
+array_api_tests/test_linalg.py::test_trace
+array_api_tests/test_linalg.py::test_linalg_vecdot
+array_api_tests/test_linalg.py::test_linalg_tensordot
 
 # test_manipulation_functions
 

ci/environment.yml

@@ -6,7 +6,7 @@ dependencies:
   - python
   - pip
   - pip:
-    - finch-tensor>=0.2.4
+    - finch-tensor>=0.2.8
     - finch-mlir>=0.0.2
     - pytest-codspeed
     - numpy

ci/test_examples.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -euxo pipefail
 
-for example in $(find ./docs/examples/ -iname *.py); do
+for example in $(find ./examples/ -iname '*.py'); do
   CI_MODE=1 python $example
 done

examples/hits_example.py

@@ -0,0 +1,81 @@
+import os
+from typing import Any
+
+import graphblas as gb
+import graphblas_algorithms as ga
+
+import numpy as np
+import scipy.sparse as sps
+from numpy.testing import assert_allclose
+
+os.environ["SPARSE_BACKEND"] = "Finch"
+import sparse
+
+# select namespace
+xp = sparse  # np jnp
+Array = Any
+
+
+def converged(xprev: Array, x: Array, N: int, tol: float) -> bool:
+    err = xp.sum(xp.abs(x - xprev))
+    return err < xp.asarray(N * tol)
+
+
+class Graph:
+    def __init__(self, A: Array):
+        assert A.ndim == 2 and A.shape[0] == A.shape[1]
+        self.N = A.shape[0]
+        self.A = A
+
+
+@sparse.compiled()
+def kernel(hprev: Array, A: Array, N: int, tol: float) -> tuple[Array, Array, Array]:
+    a = hprev.mT @ A
+    h = A @ a.mT
+    h = h / xp.max(h)
+    conv = converged(hprev, h, N, tol)
+    return h, a, conv
+
+
+def hits_finch(G: Graph, max_iter: int = 100, tol: float = 1e-8, normalized: bool = True) -> tuple[Array, Array]:
+    N = G.N
+    if N == 0:
+        return xp.asarray([]), xp.asarray([])
+
+    h = xp.full((N, 1), 1.0 / N)
+    A = xp.asarray(G.A)
+
+    for _ in range(max_iter):
+        hprev = h
+        a = hprev.mT @ A
+        h = A @ a.mT
+        h = h / xp.max(h)
+        if converged(hprev, h, N, tol):
+            break
+        # alternatively these lines can be compiled
+        # h, a, conv = kernel(h, A, N, tol)
+    else:
+        raise Exception("Didn't converge")
+
+    if normalized:
+        h = h / xp.sum(xp.abs(h))
+        a = a / xp.sum(xp.abs(a))
+    return h, a
+
+
+if __name__ == "__main__":
+    coords = (np.array([0, 0, 1, 2, 2, 3]), np.array([1, 3, 0, 0, 1, 2]))
+    data = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
+    A = sps.coo_array((data, coords))
+    G = Graph(A)
+
+    h_finch, a_finch = hits_finch(G)
+
+    print(h_finch, a_finch)
+
+    M = gb.io.from_scipy_sparse(A)
+    G = ga.Graph(M)
+    h_gb, a_gb = ga.hits(G)
+
+    assert_allclose(h_finch.todense().ravel(), h_gb.to_dense())
+    assert_allclose(a_finch.todense().ravel(), a_gb.to_dense())

examples/triangles_example.py

@@ -25,7 +25,7 @@
 
     @sparse.compiled()
     def count_triangles_finch(a):
-        return sparse.sum(a @ a * a) / 6
+        return sparse.sum(a @ a * a) / sparse.asarray(6)
 
     # Compile & Benchmark
     result_finch = benchmark(count_triangles_finch, args=[a], info="Finch", iters=ITERS)

pixi.toml

@@ -55,7 +55,7 @@ juliaup = ">=1.17.10"
 
 [feature.finch.pypi-dependencies]
 scipy = ">=1.13"
-finch-tensor = ">=0.2.4"
+finch-tensor = ">=0.2.8"
 
 [feature.finch.activation.env]
 SPARSE_BACKEND = "Finch"

pyproject.toml

@@ -54,7 +54,7 @@ tests = [
 tox = ["sparse[tests]", "tox"]
 notebooks = ["sparse[tests]", "nbmake", "matplotlib"]
 all = ["sparse[docs,tox,notebooks,mlir]", "matrepr"]
-finch = ["finch-tensor>=0.2.4"]
+finch = ["finch-tensor>=0.2.8"]
 mlir = ["finch-mlir>=0.0.2"]
 
 [project.urls]

sparse/finch_backend/__init__.py

@@ -69,6 +69,7 @@
     lazy,
     less,
     less_equal,
+    linalg,
     linspace,
     log,
     log1p,
@@ -161,6 +162,7 @@
     "int64",
     "int_",
     "lazy",
+    "linalg",
     "matmul",
     "multiply",
     "negative",