sparse-kappa 0.0.1__tar.gz

sparse_kappa-0.0.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: sparse-kappa
+Version: 0.0.1
+Summary: GPU-accelerated sparse matrix condition number estimation using CuPy
+Home-page: https://github.com/chenxinye/sparse-kappa
+Author: Xinye Chen
+Author-email: Xinye Chen <xinyechenai@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chenxinye/sparse-kappa
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cupy>=10.0.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# CuPy Sparse Condition Number Estimation
+
+A GPU-accelerated library for estimating condition numbers of sparse matrices using CuPy.
+
+## Features
+
+- **GPU-Accelerated**: All computations run on NVIDIA GPUs via CuPy
+- **Multiple Norms**: Support for 1-norm and 2-norm condition numbers
+- **Rich Algorithm Suite**:
+  - **1-norm**: Hager-Higham algorithm
+  - **2-norm**: Power method, Lanczos, Arnoldi, Golub-Kahan bidiagonalization
+  - **CuPy integrations**: svds, eigsh, lobpcg wrappers
+- **Automatic Method Selection**: Chooses optimal algorithm based on matrix properties
+- **Memory Efficient**: Designed for large sparse matrices
+
+## Installation
+
+
+Simply via pip manager
+```bash
+pip install sparse-kappa
+```
+
+```bash
+git clone https://github.com/chenxinye/sparse-kappa
+pip install cupy-cuda11x  # or cupy-cuda12x for CUDA 12
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import cupy as cp
+import cupyx.scipy.sparse as sp
+from sparse_kappa import cond_estimate
+
+# Create sparse matrix on GPU
+A = sp.random(10000, 10000, density=0.01, format='csr')
+
+# Estimate condition number (automatic method selection)
+cond = cond_estimate(A)
+print(f"Condition number: {cond:.2e}")
+
+# Use specific method
+cond = cond_estimate(A, norm=2, method='lanczos')
+
+# Get detailed results
+result = cond_estimate(A, norm=2, method='svds', verbose=True)
+print(f"Method: {result['method']}")
+print(f"Iterations: {result['iterations']}")
+print(f"σ_max: {result['sigma_max']:.4e}")
+print(f"σ_min: {result['sigma_min']:.4e}")
+```
+
+## Available Methods
+
+### 1-Norm Methods
+
+| Method | Description | Best For |
+|--------|-------------|----------|
+| `hager-higham` | Iterative refinement algorithm | General matrices, fast estimation |
+
+### 2-Norm Methods
+
+| Method | Description | Best For | Complexity |
+|--------|-------------|----------|------------|
+| `svds` | Partial SVD (most accurate) | Small-medium matrices (<5k) | O(k·nnz) |
+| `eigsh` | Symmetric eigenvalue solver | Symmetric matrices | O(k·nnz) |
+| `lobpcg` | Block preconditioned CG | Large matrices | O(k·nnz) |
+| `power` | Power iteration | Quick estimates | O(k·nnz) |
+| `lanczos` | Lanczos tridiagonalization | Medium matrices | O(k²·nnz) |
+| `arnoldi` | Arnoldi iteration | Non-symmetric | O(k²·nnz) |
+| `golub-kahan` | Bidiagonalization | Numerically stable | O(k·nnz) |
+| `auto` | Automatic selection | All cases | - |
+
+## Examples
+
+### Example 1: Compare Methods
+
+```python
+import cupyx.scipy.sparse as sp
+from sparse_kappa import cond_estimate
+
+A = sp.random(2000, 2000, density=0.005, format='csr')
+
+methods = ['power', 'lanczos', 'svds', 'golub-kahan']
+for method in methods:
+    cond = cond_estimate(A, norm=2, method=method)
+    print(f"{method:12s}: {cond:.4e}")
+```
+
+### Example 2: 1-Norm Estimation
+
+```python
+result = cond_estimate(A, norm=1, method='hager-higham', verbose=True)
+print(f"κ₁(A) = {result['condition_number']:.4e}")
+print(f"||A||₁ = {result['norm_A']:.4e}")
+print(f"||A⁻¹||₁ = {result['norm_Ainv']:.4e}")
+```
+
+### Example 3: Symmetric Matrix
+
+```python
+# Create symmetric matrix
+A = sp.random(1000, 1000, density=0.01, format='csr')
+A = (A + A.T) / 2
+
+# Use eigsh (optimized for symmetric)
+cond = cond_estimate(A, norm=2, method='eigsh')
+```
+
+## Performance Tips
+
+1. **Auto mode is recommended** for first-time usage
+2. **For symmetric matrices**, use `eigsh` or `lanczos`
+3. **For large sparse matrices** (>10k), use `golub-kahan` or `lobpcg`
+4. **For highest accuracy on small matrices**, use `svds`
+5. **Increase `max_iter`** if convergence fails
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_norm2.py -v
+
+# Run with coverage
+pytest tests/ --cov=sparse_kappa
+```
+
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions welcome! Please submit issues and pull requests on GitHub.
+
+
+## References
+
+1. Hager, W. W. (1984). "Condition estimates." SIAM J. Sci. Stat. Comput.
+2. Higham, N. J., & Tisseur, F. (2000). "A block algorithm for matrix 1-norm estimation." SIAM J. Matrix Anal. Appl.
+3. Golub, G. H., & Van Loan, C. F. (2013). "Matrix Computations" (4th ed.)
+4. Saad, Y. (2011). "Numerical Methods for Large Eigenvalue Problems" (2nd ed.)
+
+## Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{sparse_kappa,
+  title={Sparse Matrices Condition Number Estimation on GPUs},
+  author={Xinye Chen},
+  year={2026},
+  url={https://github.com/chenxinye/sparse_kappa}
+}
+```

sparse_kappa-0.0.1/README.md

@@ -0,0 +1,161 @@
+# CuPy Sparse Condition Number Estimation
+
+A GPU-accelerated library for estimating condition numbers of sparse matrices using CuPy.
+
+## Features
+
+- **GPU-Accelerated**: All computations run on NVIDIA GPUs via CuPy
+- **Multiple Norms**: Support for 1-norm and 2-norm condition numbers
+- **Rich Algorithm Suite**:
+  - **1-norm**: Hager-Higham algorithm
+  - **2-norm**: Power method, Lanczos, Arnoldi, Golub-Kahan bidiagonalization
+  - **CuPy integrations**: svds, eigsh, lobpcg wrappers
+- **Automatic Method Selection**: Chooses optimal algorithm based on matrix properties
+- **Memory Efficient**: Designed for large sparse matrices
+
+## Installation
+
+
+Simply via pip manager
+```bash
+pip install sparse-kappa
+```
+
+```bash
+git clone https://github.com/chenxinye/sparse-kappa
+pip install cupy-cuda11x  # or cupy-cuda12x for CUDA 12
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import cupy as cp
+import cupyx.scipy.sparse as sp
+from sparse_kappa import cond_estimate
+
+# Create sparse matrix on GPU
+A = sp.random(10000, 10000, density=0.01, format='csr')
+
+# Estimate condition number (automatic method selection)
+cond = cond_estimate(A)
+print(f"Condition number: {cond:.2e}")
+
+# Use specific method
+cond = cond_estimate(A, norm=2, method='lanczos')
+
+# Get detailed results
+result = cond_estimate(A, norm=2, method='svds', verbose=True)
+print(f"Method: {result['method']}")
+print(f"Iterations: {result['iterations']}")
+print(f"σ_max: {result['sigma_max']:.4e}")
+print(f"σ_min: {result['sigma_min']:.4e}")
+```
+
+## Available Methods
+
+### 1-Norm Methods
+
+| Method | Description | Best For |
+|--------|-------------|----------|
+| `hager-higham` | Iterative refinement algorithm | General matrices, fast estimation |
+
+### 2-Norm Methods
+
+| Method | Description | Best For | Complexity |
+|--------|-------------|----------|------------|
+| `svds` | Partial SVD (most accurate) | Small-medium matrices (<5k) | O(k·nnz) |
+| `eigsh` | Symmetric eigenvalue solver | Symmetric matrices | O(k·nnz) |
+| `lobpcg` | Block preconditioned CG | Large matrices | O(k·nnz) |
+| `power` | Power iteration | Quick estimates | O(k·nnz) |
+| `lanczos` | Lanczos tridiagonalization | Medium matrices | O(k²·nnz) |
+| `arnoldi` | Arnoldi iteration | Non-symmetric | O(k²·nnz) |
+| `golub-kahan` | Bidiagonalization | Numerically stable | O(k·nnz) |
+| `auto` | Automatic selection | All cases | - |
+
+## Examples
+
+### Example 1: Compare Methods
+
+```python
+import cupyx.scipy.sparse as sp
+from sparse_kappa import cond_estimate
+
+A = sp.random(2000, 2000, density=0.005, format='csr')
+
+methods = ['power', 'lanczos', 'svds', 'golub-kahan']
+for method in methods:
+    cond = cond_estimate(A, norm=2, method=method)
+    print(f"{method:12s}: {cond:.4e}")
+```
+
+### Example 2: 1-Norm Estimation
+
+```python
+result = cond_estimate(A, norm=1, method='hager-higham', verbose=True)
+print(f"κ₁(A) = {result['condition_number']:.4e}")
+print(f"||A||₁ = {result['norm_A']:.4e}")
+print(f"||A⁻¹||₁ = {result['norm_Ainv']:.4e}")
+```
+
+### Example 3: Symmetric Matrix
+
+```python
+# Create symmetric matrix
+A = sp.random(1000, 1000, density=0.01, format='csr')
+A = (A + A.T) / 2
+
+# Use eigsh (optimized for symmetric)
+cond = cond_estimate(A, norm=2, method='eigsh')
+```
+
+## Performance Tips
+
+1. **Auto mode is recommended** for first-time usage
+2. **For symmetric matrices**, use `eigsh` or `lanczos`
+3. **For large sparse matrices** (>10k), use `golub-kahan` or `lobpcg`
+4. **For highest accuracy on small matrices**, use `svds`
+5. **Increase `max_iter`** if convergence fails
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_norm2.py -v
+
+# Run with coverage
+pytest tests/ --cov=sparse_kappa
+```
+
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions welcome! Please submit issues and pull requests on GitHub.
+
+
+## References
+
+1. Hager, W. W. (1984). "Condition estimates." SIAM J. Sci. Stat. Comput.
+2. Higham, N. J., & Tisseur, F. (2000). "A block algorithm for matrix 1-norm estimation." SIAM J. Matrix Anal. Appl.
+3. Golub, G. H., & Van Loan, C. F. (2013). "Matrix Computations" (4th ed.)
+4. Saad, Y. (2011). "Numerical Methods for Large Eigenvalue Problems" (2nd ed.)
+
+## Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{sparse_kappa,
+  title={Sparse Matrices Condition Number Estimation on GPUs},
+  author={Xinye Chen},
+  year={2026},
+  url={https://github.com/chenxinye/sparse_kappa}
+}
+```

sparse_kappa-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sparse-kappa"
+version = "0.0.1"
+description = "GPU-accelerated sparse matrix condition number estimation using CuPy"
+readme = "README.md"
+authors = [
+    {name = "Xinye Chen", email = "xinyechenai@gmail.com"}
+]
+license = {text = "MIT"}
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "cupy>=10.0.0",
+    "numpy>=1.20.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "black>=22.0",
+    "flake8>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/chenxinye/sparse-kappa"

sparse_kappa-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sparse_kappa-0.0.1/setup.py

@@ -0,0 +1,43 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="sparse-kappa",                    
+    version="0.0.1",
+    author="Xinye Chen",
+    author_email="xinyechenai@gmail.com",
+    description="GPU-accelerated sparse matrix condition number estimation using CuPy",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/chenxinye/sparse-kappa",
+    
+    packages=find_packages(include=["sparse_kappa", "sparse_kappa.*"]),
+    package_dir={"": "."},
+    
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering :: Mathematics",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "cupy>=10.0.0",
+        "numpy>=1.20.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0",
+            "pytest-cov>=2.0",
+            "black>=22.0",
+            "flake8>=4.0",
+        ],
+    },
+)

sparse_kappa-0.0.1/sparse_kappa/__init__.py

@@ -0,0 +1,11 @@
+"""
+CuPy Sparse Condition Number Estimation Library
+
+A comprehensive GPU-accelerated library for estimating condition numbers
+of sparse matrices using various iterative methods.
+"""
+
+from .sparse_kappa import cond_estimate, ConditionNumberEstimator
+
+__version__ = "0.0.1"
+__all__ = ["cond_estimate", "ConditionNumberEstimator"]

sparse_kappa-0.0.1/sparse_kappa/norm1/__init__.py

@@ -0,0 +1,7 @@
+"""
+1-norm condition number estimation methods.
+"""
+
+from .hager_higham import hager_higham_norm1
+
+__all__ = ['hager_higham_norm1']

sparse_kappa-0.0.1/sparse_kappa/norm1/hager_higham.py

@@ -0,0 +1,198 @@
+"""
+Hager-Higham algorithm for 1-norm condition number estimation.
+
+References
+----------
+- Hager, W. W. (1984). Condition estimates. SIAM Journal on 
+  Scientific and Statistical Computing, 5(2), 311-316.
+- Higham, N. J., & Tisseur, F. (2000). A block algorithm for matrix 
+  1-norm estimation, with an application to 1-norm pseudospectra.
+  SIAM Journal on Matrix Analysis and Applications, 21(4), 1185-1201.
+"""
+
+import cupy as cp
+import cupyx.scipy.sparse as sp
+from typing import Dict, Any
+from ..utils import sparse_matrix_norm, apply_inverse, print_iteration
+
+
+def hager_higham_norm1(
+    A: sp.spmatrix,
+    max_iter: int = 5,
+    tol: float = 1e-6,
+    verbose: bool = False,
+    variant: str = 'higham',
+    **kwargs
+) -> Dict[str, Any]:
+    """
+    Estimate 1-norm condition number using Hager-Higham algorithm.
+    
+    Estimates κ₁(A) = ||A||₁ · ||A⁻¹||₁ using iterative refinement.
+    
+    Parameters
+    ----------
+    A : sparse matrix
+        Input matrix (n x n)
+    max_iter : int, default=5
+        Maximum number of iterations
+    tol : float, default=1e-6
+        Convergence tolerance
+    verbose : bool, default=False
+        Print iteration information
+    variant : str, default='higham'
+        Algorithm variant ('hager' or 'higham')
+    
+    Returns
+    -------
+    result : dict
+        - 'condition_number': estimated κ₁(A)
+        - 'norm_A': ||A||₁
+        - 'norm_Ainv': ||A⁻¹||₁
+        - 'iterations': number of iterations
+        - 'converged': convergence status
+    
+    Algorithm
+    ---------
+    1. Compute ||A||₁ exactly (max column sum)
+    2. Estimate ||A⁻¹||₁ using iterative refinement:
+       - Start with random vector x
+       - Iterate: solve A y = x, update x based on sign pattern
+       - Stop when estimate converges
+    
+    Complexity: O(k · nnz(A)) where k is number of iterations
+    """
+    n = A.shape[0]
+    
+    # Step 1: Compute ||A||₁ exactly
+    norm_A = sparse_matrix_norm(A, ord=1)
+    
+    if verbose:
+        print(f"Hager-Higham 1-norm condition number estimation")
+        print(f"Matrix size: {n} x {n}")
+        print(f"||A||₁ = {norm_A:.6e}")
+        print(f"Estimating ||A⁻¹||₁...")
+    
+    # Step 2: Estimate ||A⁻¹||₁
+    norm_Ainv, iterations, converged = estimate_inverse_norm1(
+        A, max_iter, tol, verbose, variant
+    )
+    
+    # Step 3: Compute condition number
+    cond = norm_A * norm_Ainv
+    
+    if verbose:
+        print(f"\n||A⁻¹||₁ = {norm_Ainv:.6e}")
+        print(f"κ₁(A) = {cond:.6e}")
+        print(f"Converged: {converged} after {iterations} iterations")
+    
+    return {
+        'condition_number': float(cond),
+        'norm_A': float(norm_A),
+        'norm_Ainv': float(norm_Ainv),
+        'iterations': iterations,
+        'converged': converged,
+    }
+
+
+def estimate_inverse_norm1(
+    A: sp.spmatrix,
+    max_iter: int,
+    tol: float,
+    verbose: bool,
+    variant: str
+) -> tuple:
+    """
+    Estimate ||A⁻¹||₁ using Hager-Higham algorithm.
+    
+    Returns
+    -------
+    norm_estimate : float
+        Estimated ||A⁻¹||₁
+    iterations : int
+        Number of iterations
+    converged : bool
+        Convergence status
+    """
+    n = A.shape[0]
+    
+    # Initialize with random vector
+    x = cp.ones(n, dtype=A.dtype) / n
+    
+    norm_estimate = 0.0
+    converged = False
+    
+    for it in range(max_iter):
+        # Solve A^T z = sign(x)
+        sign_x = cp.sign(cp.real(x))
+        sign_x[sign_x == 0] = 1
+        
+        # Solve A^T z = sign_x
+        z = apply_inverse(A.T, sign_x, method='lsmr', atol=1e-10, btol=1e-10)
+        
+        # Find index with maximum |z_i|
+        abs_z = cp.abs(z)
+        j = cp.argmax(abs_z)
+        
+        # Check convergence
+        new_estimate = float(abs_z[j])
+        
+        if verbose:
+            print_iteration(it + 1, new_estimate)
+        
+        if it > 0 and abs(new_estimate - norm_estimate) < tol * norm_estimate:
+            converged = True
+            norm_estimate = new_estimate
+            iterations = it + 1
+            break
+        
+        norm_estimate = new_estimate
+        
+        # Update x: x = A^{-1} e_j
+        e_j = cp.zeros(n, dtype=A.dtype)
+        e_j[j] = 1.0
+        x = apply_inverse(A, e_j, method='lsmr', atol=1e-10, btol=1e-10)
+        
+        # Compute 1-norm of x
+        norm_x = float(cp.sum(cp.abs(x)))
+        
+        if norm_x > norm_estimate:
+            norm_estimate = norm_x
+    
+    if not converged:
+        iterations = max_iter
+    
+    return norm_estimate, iterations, converged
+
+
+def inverse_norm1_direct(A: sp.spmatrix, num_samples: int = 10) -> float:
+    """
+    Estimate ||A⁻¹||₁ using random sampling (simpler but less accurate).
+    
+    Parameters
+    ----------
+    A : sparse matrix
+        Input matrix
+    num_samples : int
+        Number of random vectors to sample
+    
+    Returns
+    -------
+    norm_estimate : float
+        Estimated ||A⁻¹||₁
+    """
+    n = A.shape[0]
+    max_norm = 0.0
+    
+    for _ in range(num_samples):
+        # Random unit vector in 1-norm
+        b = cp.random.randn(n).astype(A.dtype)
+        b /= cp.linalg.norm(b, ord=1)
+        
+        # Solve A x = b
+        x = apply_inverse(A, b, method='lsmr')
+        
+        # Compute 1-norm
+        norm_x = float(cp.linalg.norm(x, ord=1))
+        max_norm = max(max_norm, norm_x)
+    
+    return max_norm