Metadata-Version: 2.4
Name: aljabr
Version: 0.5.2
Summary: Linear operators interfaces
Keywords: linear algebra,implicit operator
Author: François Orieux
Author-email: François Orieux <francois.orieux@universite-paris-saclay.fr>
License-Expression: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Dist: array-api-compat>=1.13.0
Requires-Dist: numpy>=2.4.1
Requires-Dist: udft>=4.0.2
Requires-Dist: sphinx>=7 ; extra == 'docs'
Requires-Dist: furo ; extra == 'docs'
Requires-Dist: myst-parser ; extra == 'docs'
Requires-Dist: scipy>=1.17.1 ; extra == 'scipy'
Requires-Dist: pywavelets>=1.9.0 ; extra == 'wavelet'
Maintainer: François Orieux
Maintainer-email: François Orieux <francois.orieux@universite-paris-saclay.fr>
Requires-Python: >=3.12
Project-URL: homepage, https://aljabr.readthedocs.io/
Project-URL: documentation, https://aljabr.readthedocs.io/
Project-URL: repository, https://github.com/forieux/aljabr/
Project-URL: changelog, https://github.com/forieux/aljabr/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/forieux/aljabr/issues
Project-URL: Author webpage, https://pro.orieux.fr/
Provides-Extra: docs
Provides-Extra: scipy
Provides-Extra: wavelet
Description-Content-Type: text/markdown

# aljabr — Implicit linear operators

**aljabr** is a small Python library providing an interface for implicit linear
operators: linear maps defined by `forward` and `adjoint` callables rather than
an explicit matrix. It is useful when an explicit matrix representation is not
adequate — for instance when the dimension is large, when a more efficient
algorithm exists, or when the operator is naturally expressed as a function.

A typical example is the Discrete Fourier Transform, which is a linear operator
available through `fft` and `ifft` functions. aljabr lets you treat it — and
compose it with others — as if it were a matrix.

The foundation is the `LinOp` type. Everything else — concrete operators,
utilities, algebraic composition — is built on top of it and optional. I made
this library for my own use.

## Key differences from similar tools

**vs. `scipy.sparse.linalg.LinearOperator`** — input and output arrays can have
any shape, not just vectors. A 2D FFT operator maps an image to an image. Shapes
are fixed at construction: a `DFT` on a 512² image is a different object than
one on a 256² image. This is intentional.

**vs. PyLops** — aljabr is deliberately minimal. It does not provide solvers or
choose algorithms for you. There is no `x = A / y`. It stays out of your way,
offering only readability and convenience.

## Features

- Abstract base class `LinOp` with `forward` (`A·x`) and `adjoint` (`Aᴴ·y`)
- Algebraic composition: `A + B`, `A - B`, `A @ B`, `scalar * A`, `A.H`, `A.S`
- Array-API compatible — works with NumPy, PyTorch, JAX, and others via
  [array-api-compat](https://data-apis.org/array-api-compat/)
- Compatible with `scipy.sparse.linalg.LinearOperator` — can also be passed
  directly as argument
- Concrete operators: `Identity`, `Diag`, `DFT`, `RealDFT`, `Conv`,
  `DirectConv`, `CircConv`, `FreqFilter`, `Diff`, `Sampling`, `Slice`,
  wavelet, …
- Utilities: `dottest`, `fwadjtest`, `is_sym`, `is_pos_def`, `cond`, …

## Installation

```bash
# with poetry (or uv)
poetry add aljabr

# with pip
pip install aljabr
```

Optional dependencies:

```bash
poetry add aljabr[wavelet]   # PyWavelets — required for DWT, Analysis2, Synthesis2
poetry add aljabr[scipy]     # SciPy — required for DirectConv and fcond
```

## Quick example

```python
import numpy as np
import aljabr

# Wrap the FFT as a linear operator
F = aljabr.DFT(shape=(256, 256), ndim=2)

x = np.random.randn(256, 256)

y = F.forward(x)        # F·x
# or
y = F * x
# or
y = F(x)

z = F.adjoint(y)        # Fᴴ·y
# or
z = y * F  # (= Fʰ·yᵗ)

# Algebraic composition
A = aljabr.Diff(axis=0, ishape=(256, 256))
B = A.H @ A             # AᴴA as a Symmetric operator

# Validate with the dot test
from aljabr import dottest
assert dottest(A, num=5)
```

## Documentation

[https://aljabr.readthedocs.io](https://aljabr.readthedocs.io)

## Status

Pre-Alpha. The API may change. Feedback welcome:
<francois.orieux@universite-paris-saclay.fr>

## License

MIT — see [LICENSE](LICENSE).
