Merge branch 'main' of ssh://github.com/peekxc/primate

.github/workflows/build_macos.yml

@@ -31,18 +31,19 @@ jobs:
         brew install --force libomp llvm
     - name: Update environment flags for Clang 
       run: |
-        export PATH="/usr/local/opt/llvm/bin:$PATH"
-        export LDFLAGS="-L/usr/local/opt/llvm/lib"
-        export CPPFLAGS="-I/usr/local/opt/llvm/include"
-        echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.bash_profile
-        echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> /Users/runner/.bash_profile
+        # export CLANG_PATH="/opt/homebrew/opt/llvm"
+        export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
+        export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
+        export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"
+        echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.bash_profile
+        echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> /Users/runner/.bash_profile
         source ~/.bash_profile
     - name: Verify Clang version 
       run: | 
-        /usr/local/opt/llvm/bin/clang --version
+        /opt/homebrew/opt/llvm/bin/clang --version
       env:
-        CC: /usr/local/opt/llvm/bin/clang
-        CXX: /usr/local/opt/llvm/bin/clang
+        CC: /opt/homebrew/opt/llvm/bin/clang
+        CXX: /opt/homebrew/opt/llvm/bin/clang
     - name: Install OpenBLAS
       run: |
         brew install openblas
@@ -57,8 +58,8 @@ jobs:
       run: |
         python -m pip install . --verbose
       env:
-        CC: /usr/local/opt/llvm/bin/clang
-        CXX: /usr/local/opt/llvm/bin/clang++
+        CC: /opt/homebrew/opt/llvm/bin/clang
+        CXX: /opt/homebrew/opt/llvm/bin/clang++
     - name: Test with pytest
       run: |
         python -m pytest tests/ --cov=primate --benchmark-skip

.github/workflows/build_windows.yml

@@ -48,7 +48,7 @@ jobs:
     ## NOTE: this installs clang, clang-cl, lld, etc
     - name: Install Clang with OpenMP support using Chocolatey
       run: |
-        choco install -y llvm --params "clang;compiler=clang" --version 17.0.0
+        choco install -y llvm --params "clang;compiler=clang" --version 18.1.0
         $env:PATH = "C:\Program Files\LLVM\bin;$env:PATH"
         clang --version
     # - name: Install OpenBLAS using Chocolatey

.github/workflows/wheels.yml

@@ -47,6 +47,10 @@ jobs:
       - name: Set VSDev RC (windows only)
         if: runner.os == 'Windows'
         run: | 
+          choco install -y llvm --params "clang;compiler=clang" --version 18.1.0
+          $env:PATH = "C:\Program Files\LLVM\bin;$env:PATH"
+          clang --version
+          
           function Invoke-VSDevEnvironment {
             $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
               $installationPath = & $vswhere -prerelease -legacy -latest -property installationPath
@@ -61,7 +65,7 @@ jobs:
           Get-Command rc.exe | Format-Table -AutoSize
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.16.2
+        uses: pypa/cibuildwheel@v2.17.0
         env:
           CIBW_BUILD: ${{ matrix.python[0] }}-${{ matrix.buildplat[1] }}*
           CIBW_ARCHS: ${{ matrix.buildplat[2] }}

README.md

@@ -10,7 +10,7 @@
 
 $$ f(A) \triangleq U f(\Lambda) U^{\intercal}, \quad \quad f : [a,b] \to \mathbb{R}$$
 
-Estimator approximations are obtained via the _Lanczos_[^1] and _stochastic Lanczos quadrature_[^2] methods, which are well-suited for sparse or structured operators supporting fast $v \mapsto Av$ actions.
+This definition is quite general in that different parameterizations of $f$ produce a variety of spectral quantities, including the [numerical rank](https://doi.org/10.1016/j.amc.2007.06.005), the [log-determinant](https://en.wikipedia.org/wiki/Determinant#Trace), the trace inverse, the [Schatten norms](https://en.wikipedia.org/wiki/Schatten_norm), the trace of [matrix exponentials](https://en.wikipedia.org/wiki/Matrix_exponential), the [eigencount](https://doi.org/10.1002/nla.2048), the [spectral density](https://doi.org/10.1137/130934283), etc. 
 
 Notable features of `primate` include:
 
@@ -20,10 +20,24 @@ Notable features of `primate` include:
 - Support for _arbitrary_ `LinearOperator`'s, e.g. those in [SciPy](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html#scipy-sparse-linalg-linearoperator) or [Pylops](https://pylops.readthedocs.io/en/stable/index.html)
 - Matrix-free interface to the _Lanczos_, _Golub-Welsch_, and _Gram Schmidt_ methods
 
+`primate` was partially inspired by the [`imate` package](https://github.com/ameli/imate)---for a comparison of the two, see [here](https://peekxc.github.io/primate/imate_compare.html).
+
+## Applications 
+
+Applications of matrix functions include [characterizing folding in proteins](https://en.wikipedia.org/wiki/Estrada_index), [principal component regression](https://en.wikipedia.org/wiki/Principal_component_regression), [spectral clustering](https://en.wikipedia.org/wiki/Spectral_clustering),  [Gaussian process likelihood estimation](https://en.wikipedia.org/wiki/Gaussian_process), [counting triangles in distributed-memory networks](https://doi.org/10.1137/23M1548323), [characterizing graph similarity](https://doi.org/10.1016/j.patcog.2008.12.029), and [deep neural loss landscape analysis](https://proceedings.mlr.press/v97/ghorbani19b).
 <!-- Moreover, `primate`'s C++ API uses a generic template interface written with [C++20 Concepts](https://en.cppreference.com/w/cpp/language/constraints)---thus, any `LinearOperator` [fitting the constraints](https://github.com/peekxc/primate/blob/d09459c017fcba68a11eaeb56296ef0c97d6c053/include/_linear_operator/linear_operator.h#L21-L49).  -->
 <!-- To use,, the library is is [header-only](https://en.wikipedia.org/wiki/Header-only), so integration is a si.  -->
 
-`primate` was partially inspired by the [`imate` package](https://github.com/ameli/imate)---for a comparison of the two, see [here](https://peekxc.github.io/primate/imate_compare.html).
+
+## Installation
+
+`primate` is a standard PEP-517 package that can be installed via pip:
+
+```{bash}
+python -m pip install scikit-primate
+```
+
+Assuming your platform is supported, no compilation is needed—see the [installation page](https://peekxc.github.io/primate/basic/install.html) for details.
 
 [^1]: Musco, Cameron, Christopher Musco, and Aaron Sidford. (2018) "Stability of the Lanczos method for matrix function approximation."
 [^2]: Ubaru, S., Chen, J., & Saad, Y. (2017). Fast estimation of tr(f(A)) via stochastic Lanczos quadrature.

pyproject.toml

@@ -57,7 +57,7 @@ environment = { CC="gcc", CXX="g++" } # for manylinux2014
 
 [tool.cibuildwheel.macos]
 before-build = "bash {project}/tools/cibw_macos.sh"
-environment = { CC="/usr/local/opt/llvm/bin/clang", CXX="/usr/local/opt/llvm/bin/clang++" }
+environment = { CC="/opt/homebrew/opt/llvm/bin/clang", CXX="/opt/homebrew/opt/llvm/bin/clang++" }
 
 [tool.cibuildwheel.windows]
 before-build = "bash {project}/tools/cibw_windows.sh"

tools/cibw_macos.sh

@@ -3,15 +3,23 @@
 rm -rf /usr/local/bin/2to3/*
 brew install --force libomp llvm openblas
 
+export LDDFLAGS="$LDFLAGS -L/opt/homebrew/opt/libomp"
+export PKG_CONFIG_PATH="/opt/homebrew/opt/openblas/lib/pkgconfig:$PKG_CONFIG_PATH"
+
 export CC=/usr/local/opt/llvm/bin/clang
 export CXX=/usr/local/opt/llvm/bin/clang++
+export PREFIX=
 export CPPFLAGS="$CPPFLAGS -Xpreprocessor -fopenmp"
 export CFLAGS="$CFLAGS -Wno-implicit-function-declaration -I$PREFIX/include"
 export CXXFLAGS="$CXXFLAGS -I$PREFIX/include"
 export LDFLAGS="$LDFLAGS -Wl,-rpath,$PREFIX/lib -L$PREFIX/lib -lomp"
 export LDFLAGS="$LDFLAGS -Wl,-S -Wl,-rpath,$PREFIX/lib -L$PREFIX/lib -lomp"
 export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
 
+# Add OpenMP LD FLags
+export LDFLAGS="$LDFLAGS -L/opt/homebrew/opt/libomp/lib"
+export CXXFLAGS="$CXXFLAGS -I/opt/homebrew/opt/libomp/include"
+
 if [[ $(uname -m) == "arm64" && "$CIBW_BUILD" == "cp38-macosx_arm64" ]]; then
   # Enables native building and testing for macosx arm on Python 3.8. For details see:
   # https://cibuildwheel.readthedocs.io/en/stable/faq/#macos-building-cpython-38-wheels-on-arm64