Metadata-Version: 2.4
Name: fast-linsolve
Version: 0.1.0
Summary: A high-performance linear system solver library: 3 direct + 3 iterative methods, accelerated with Numba JIT and Cython.
Author: linsolve contributors
License-Expression: MIT
Project-URL: Homepage, https://example.com/fast-linsolve
Project-URL: Repository, https://example.com/fast-linsolve
Keywords: linear-algebra,numerical-methods,solver,numba,cython,scientific-computing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: numba
Requires-Dist: numba>=0.57; extra == "numba"
Provides-Extra: cython
Requires-Dist: cython>=0.29; extra == "cython"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: sphinx>=5; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# linsolve (`fast-linsolve`)

High-performance linear-system solvers in Python — 3 direct methods + 3
iterative methods, accelerated with **Numba JIT** and **Cython** static
compilation, with automatic fallback to pure NumPy.

## Features

| Category | Algorithm | Notes |
|---|---|---|
| Direct | Gaussian elimination | partial pivoting |
| Direct | LU factorisation | PA = LU, Doolittle form, partial pivoting |
| Direct | Cholesky factorisation | symmetric positive-definite matrices |
| Iterative | Jacobi | classical fixed-point |
| Iterative | Gauss–Seidel | in-place updates |
| Iterative | SOR | successive over-relaxation, ω ∈ (0, 2) |

Three backends, auto-selected at runtime:

1. `cython`  — compiled C extension (fastest, needs a C toolchain at build)
2. `numba`    — JIT compiled native code
3. `python`   — pure NumPy loop reference (always available)

## Install

```bash
pip install fast-linsolve
```

For the accelerated layers:

```bash
pip install fast-linsolve[numba]     # Numba JIT
pip install fast-linsolve[cython]    # Cython (needs MSVC Build Tools / gcc)
```

## Quick start

```python
import numpy as np
from linsolve import solve, gauss_solve, lu_solve, cholesky_solve
from linsolve import jacobi, gauss_seidel, sor

A = np.array([[4, 1, 2], [0, 5, 1], [1, 0, 3]], dtype=float)
b = np.array([7, 7, 4], dtype=float)

# unified entry point
x = solve(A, b, method="lu")
print(np.allclose(A @ x, b))   # True

# direct methods
x = gauss_solve(A, b)
x = lu_solve(A, b)

# symmetric positive-definite matrix -> Cholesky
Aspd = np.array([[4, 1, 1], [1, 3, 0], [1, 0, 2]], dtype=float)
x = cholesky_solve(Aspd, np.array([6, 7, 5], dtype=float))

# iterative methods return (x, info)
x, info = jacobi(A, b, tol=1e-8, max_iter=200)
print(info)   # {'iterations': ..., 'residual': ..., 'converged': True}

x, info = sor(A, b, omega=1.2, tol=1e-8)
```

Force a specific backend:

```python
x = lu_solve(A, b, backend="numba")
x = lu_solve(A, b, backend="python")   # slow reference
```

## Performance

Measured on a dense well-conditioned matrix (Windows, Python 3.14,
single-threaded Numba, LAPACK via NumPy):

| Size | Method | Pure Python | Numba JIT | Speedup | NumPy LAPACK |
|---|---|---|---|---|---|
| 300 | LU | 4.84 s | 5.0 ms | **960×** | 24.6 ms |
| 300 | Cholesky | 2.00 s | 0.9 ms | **5,600×** | 9.4 ms |
| 1000 | LU | 180.4 s | 260 ms | **694×** | 67 ms |
| 1000 | Cholesky | 74.9 s | 34 ms | **5,400×** | 42 ms |

Notes:

- The Numba speedup over the pure-Python loop is in the **100–800×** range
  for LU and even larger for Cholesky (lower arithmetic intensity => Python
  interpreter overhead dominates the baseline).
- On large dense LU, NumPy's bundled LAPACK/BLAS (blocked, SIMD, sometimes
  multi-threaded) still wins; the Numba LU kernel reaches ~26% of NumPy on
  n=1000. Cholesky, with lower arithmetic density, is on par with or slightly
  faster than NumPy out of the box.
- The Cython kernel is expected to add another **1.5–3×** over Numba on
  supported platforms (compiled automatically when a C toolchain is present).

Run the benchmark yourself:

```bash
python benchmarks/benchmark.py --n 1000
```

## Development

```bash
git clone <repo>
cd fast-linsolve
python -m pip install -e .[dev,numba]

# run tests
pytest

# build docs
sphinx-build -b html docs/source docs/build

# build and publish to PyPI
python -m build
twine upload dist/*
```

## Project layout

```
src/linsolve/
  __init__.py        public API
  direct.py          gauss / lu / cholesky wrappers
  iterative.py       jacobi / gauss_seidel / sor wrappers
  _raw.py            pure-Python loop reference
  _numba.py          @njit JIT implementations
  _cython_core.pyx   Cython statically-typed kernel
  _backend.py        runtime backend detection
tests/               pytest suite (23 tests)
benchmarks/          benchmark script
docs/source/         Sphinx sources
```

## License

MIT
