Metadata-Version: 2.1
Name: blocksolver
Version: 0.8.0
Summary: Block Quasi-Minimal-Residual sparse linear solver
Keywords: sparse,linear-algebra,iterative-solver,qmr,fortran,umfpack
Author-Email: Qianqian Fang <q.fang@neu.edu>
License: BSD-3-Clause OR LGPL-3.0-or-later OR GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Fortran
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
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Project-URL: Homepage, https://blit.sourceforge.net
Project-URL: Repository, https://github.com/fangq/blocksolver
Project-URL: Documentation, https://blit.sourceforge.net
Project-URL: Bug Tracker, https://github.com/fangq/blocksolver/issues
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.0
Provides-Extra: fast
Requires-Dist: numba>=0.50; extra == "fast"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Description-Content-Type: text/markdown

# BLIT Python Bindings

Python interface for the BLIT (Block Iterative) sparse linear solver library.

## Installation

### Prerequisites

- Python >= 3.8
- NumPy
- Fortran compiler (gfortran, ifort)
- UMFPACK/SuiteSparse library
- BLAS/LAPACK

On Ubuntu/Debian:
```bash
sudo apt install gfortran libsuitesparse-dev libblas-dev liblapack-dev
```

On macOS (Homebrew):
```bash
brew install gcc suite-sparse openblas
```

### Install

```bash
cd python
pip install .
```

For development:
```bash
pip install -e .
```

## Usage

### Basic Usage

```python
import numpy as np
from blocksolver import blqmr_solve

# Define sparse matrix in CSC format (0-based indexing)
Ap = np.array([0, 2, 5, 9, 10, 12], dtype=np.int32)
Ai = np.array([0, 1, 0, 2, 4, 1, 2, 3, 4, 2, 1, 4], dtype=np.int32)
Ax = np.array([2., 3., 3., -1., 4., 4., -3., 1., 2., 2., 6., 1.])
b = np.array([8.0, 45.0, -3.0, 3.0, 19.0])

# Solve
result = blqmr_solve(Ap, Ai, Ax, b, tol=1e-8)

print(f"Solution: {result.x}")
print(f"Converged: {result.converged}")
print(f"Iterations: {result.iter}")
```

### With SciPy Sparse Matrices

```python
from scipy.sparse import csc_matrix
from blocksolver import blqmr_scipy

A = csc_matrix([[4, 1, 0], [1, 3, 1], [0, 1, 2]])
b = np.array([1., 2., 3.])

x, flag = blqmr_scipy(A, b, tol=1e-10)
```

### Multiple Right-Hand Sides

```python
from blocksolver import blqmr_solve_multi

B = np.column_stack([b1, b2, b3])  # n x nrhs
result = blqmr_solve_multi(Ap, Ai, Ax, B)
# result.x is n x nrhs
```

## API Reference

### `blqmr_solve(Ap, Ai, Ax, b, **kwargs) -> BLQMRResult`

Solve sparse system Ax = b.

**Parameters:**
- `Ap`: Column pointers (int32, length n+1)
- `Ai`: Row indices (int32, length nnz)
- `Ax`: Non-zero values (float64, length nnz)
- `b`: Right-hand side (float64, length n)
- `tol`: Convergence tolerance (default: 1e-6)
- `maxiter`: Maximum iterations (default: n)
- `droptol`: ILU drop tolerance (default: 0.001)
- `use_precond`: Use ILU preconditioner (default: True)
- `zero_based`: Input uses 0-based indexing (default: True)

**Returns:** `BLQMRResult` with attributes:
- `x`: Solution vector
- `flag`: 0=converged, 1=maxiter, 2=precond fail, 3=stagnation
- `iter`: Iterations performed
- `relres`: Relative residual
- `converged`: Boolean property

## Testing

```bash
make test
# or
pytest tests/ -v
```

## License

BSD / LGPL / GPL - see LICENSE files in parent directory.
