Metadata-Version: 2.4
Name: nbklu
Version: 0.3.0
Summary: Python wrapper for KLU
Author-Email: Azuk 443 <me@azuk.top>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Project-URL: Homepage, https://github.com/determ1ne/nbklu
Project-URL: Issues, https://github.com/determ1ne/nbklu/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0.0
Provides-Extra: scipy
Requires-Dist: scipy>=1.11; extra == "scipy"
Description-Content-Type: text/markdown

# nbklu: Python bindings for SuiteSparse KLU

`nbklu` provides:
- Full low-level bindings for the public `klu.h` API families
  - 32-bit index real (`klu_*`)
  - 32-bit index complex (`klu_z_*`)
  - 64-bit index real (`klu_l_*`)
  - 64-bit index complex (`klu_zl_*`)
- A high-level solver API with typed variants.

## Installation

```bash
pip install nbklu
# optional SciPy integration
pip install "nbklu[scipy]"
# or from source
pip install git+https://github.com/determ1ne/nbklu.git
```

## Solver usage

```python
import numpy as np
from nbklu import KLUSolver

n = 5
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.0, 3.0, 3.0, -1.0, 4.0, 4.0, -3.0, 1.0, 2.0, 2.0, 6.0, 1.0], dtype=np.float64)
b = np.array([8.0, 45.0, -3.0, 3.0, 19.0], dtype=np.float64)

solver = KLUSolver(index_bits=32, complex_values=False)
solver.analyze(n, Ap, Ai)
solver.factor(Ax)
x = solver.solve(b)
print(x)
```

## Typed solver variants

- `KLUSolver32Real`
- `KLUSolver32Complex`
- `KLUSolver64Real`
- `KLUSolver64Complex`

All variants support:
- `analyze` / `analyze_given`
- `factor` / `refactor`
- `solve` / `tsolve`
- `sort`, `flops`, `rgrowth`, `condest`, `rcond`, `scale`, `extract`

## Low-level API

Import `nbklu._ext` for direct C-parity functions (`analyze`, `z_factor`, `l_solve`, `zl_extract`, `version`, ...).
Complex APIs accept both:
- interleaved `float64` arrays (KLU layout)
- `numpy.complex128` arrays.

## Notes

- KLU docs: <https://github.com/DrTimothyAldenDavis/SuiteSparse/blob/dev/KLU/Doc/KLU_UserGuide.pdf>
- Python API docs: `docs/python-api.md`

## SciPy API (`nbklu.scipy`)

SciPy integration interface mirrors `scipy.sparse.linalg` patterns:

```python
import numpy as np
from scipy.sparse import csc_matrix
from nbklu.scipy import spsolve, factorized, splu

A = csc_matrix(...)
b = np.array(...)

x = spsolve(A, b)

solve = factorized(A)
x2 = solve(b)

lu = splu(A)
x3 = lu.solve(b)
x4 = lu.solve(b, trans="T")
```

This module accepts SciPy sparse matrices/arrays and internally dispatches to the appropriate KLU family.
