Metadata-Version: 2.5
Name: lazylinop
Version: 1.24.33
Summary: A package dedicated to lazy linear operators based on diverse backends/libraries.
Project-URL: Homepage, https://faustgrp.gitlabpages.inria.fr/lazylinop/
Project-URL: Documentation, https://faustgrp.gitlabpages.inria.fr/lazylinop/api.html
Project-URL: Repository, https://gitlab.inria.fr/faustgrp/lazylinop
Project-URL: Bug Tracker, https://gitlab.inria.fr/faustgrp/lazylinop/-/issues
Author-email: Inria <remi.gribonval@inria.fr>, Pascal Carrivain <pascal.carrivain@inria.fr>, Simon Delamare <simon.delamare@ens-lyon.fr>, Hakim Hadj-Djilani <hakim.hadj-djilani@inria.fr>, Rémi Gribonval <remi.gribonval@inria.fr>
License-Expression: BSD-2-Clause
License-File: LICENSE.txt
Keywords: butterfly,lazy computation,matrix-free,quantization,signal processing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: array-api-compat>=1.12.0
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Requires-Dist: sympy>=1.14
Provides-Extra: doc
Requires-Dist: myst-parser; extra == 'doc'
Requires-Dist: nbsphinx; extra == 'doc'
Requires-Dist: sphinx; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-book-theme; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-design; extra == 'doc'
Requires-Dist: sphinx-math-dollar; extra == 'doc'
Requires-Dist: sphinxcontrib-jquery; extra == 'doc'
Provides-Extra: full
Requires-Dist: array-api-compat>=1.12; extra == 'full'
Requires-Dist: cufinufft; extra == 'full'
Requires-Dist: cupy-cuda12x>=13.4.1; extra == 'full'
Requires-Dist: finufft; extra == 'full'
Requires-Dist: matplotlib; extra == 'full'
Requires-Dist: mpi4py; extra == 'full'
Requires-Dist: ninja; extra == 'full'
Requires-Dist: numba; extra == 'full'
Requires-Dist: numpy>=2.0; extra == 'full'
Requires-Dist: pandas; extra == 'full'
Requires-Dist: psutil; extra == 'full'
Requires-Dist: pycuda; extra == 'full'
Requires-Dist: pyfaust; extra == 'full'
Requires-Dist: pyopencl; extra == 'full'
Requires-Dist: pywavelets; extra == 'full'
Requires-Dist: scikit-image; extra == 'full'
Requires-Dist: scipy>=1.13; extra == 'full'
Requires-Dist: shapely>=2.0.6; extra == 'full'
Requires-Dist: sympy>=1.14; extra == 'full'
Requires-Dist: tensorflow-cpu; extra == 'full'
Requires-Dist: torch; extra == 'full'
Requires-Dist: torchaudio; extra == 'full'
Description-Content-Type: text/markdown

## Lazylinop

![License](https://img.shields.io/badge/License-BSD_2-blue.svg)
[![Downloads](https://static.pepy.tech/badge/lazylinop)](https://pepy.tech/project/lazylinop)
[![Downloads](https://static.pepy.tech/badge/lazylinop/month)](https://pepy.tech/project/lazylinop)
[![PyPI version](https://badge.fury.io/py/lazylinop.svg)](https://pypi.org/project/lazylinop/)
[![Anaconda version](https://anaconda.org/lazylinop/lazylinop/badges/version.svg)](https://anaconda.org/lazylinop/lazylinop)

Lazylinop is a python toolbox to ease and accelerate computations with ("matrix-free") linear operators.
It provides glue to combine linear operators as easily as NumPy arrays, PyTorch/CuPy compatibility, standard signal/image processing linear operators, as well as advanced tools to approximate large matrices by efficient butterfly operators.

A `LazyLinOp` is a high-level linear operator based on an arbitrary underlying implementation, such as:

- custom Python functions,
- a [NumPy array](https://numpy.org/doc/stable/reference/generated/numpy.array.html),
- a [SciPy matrix](https://docs.scipy.org/doc/scipy/reference/sparse.html),
- a [CuPy array](https://docs.cupy.dev/en/stable/reference/generated/cupy.array.html),
- a [torch tensor](https://docs.pytorch.org/docs/stable/tensors.html),
- any Python linear operator.

Thanks to the Lazylinop API, this operator can be easily manipulated, transformed or aggregated with other linear operators to form more complex `LazyLinOp` objects.
Thus, many operations are available such as the addition, concatenation, adjoint etc.
These operations are all ruled by the **lazy paradigm**: their evaluation is delayed until the resulting `LazyLinOp` is actually applied to a vector (or to a collection of vectors, seen as a matrix).

## Install

Please refer to the [documentation](https://faustgrp.gitlabpages.inria.fr/lazylinop/install.html) to install Lazylinop.

## Get started

You can read our [documentation](https://faustgrp.gitlabpages.inria.fr/lazylinop/index.html) and our [quick tour](https://faustgrp.gitlabpages.inria.fr/lazylinop/quick_tour.html).

Please refer to [tutorials](https://faustgrp.gitlabpages.inria.fr/lazylinop/tutorials.html) for advanced examples.

## 2D Magnetic-Resonance-Imaging (MRI)

```python
from skimage.data import shepp_logan_phantom
from lazylinop.signal2d import dft2d, colvec, uncolvec
from lazylinop.basicops import diag, eye, kron, roll
import matplotlib.pyplot as plt
import numpy as np

img = shepp_logan_phantom()
M, N = img.shape
```

The following code shows how to create a MRI operator and apply to Shepp-Logan phantom image.

```python
# Pre-built 2D FFT.
F2 = dft2d(img.shape)
# Construct a 2D FFT-shift.
shift = kron(roll(N, shift=N // 2), roll(M, shift=M // 2))
# Apply random mask to the columns.
v = np.zeros(N, dtype=img.dtype)
v[np.random.randint(0, high=N, size=int(0.9 * N))] = 1
mask = kron(diag(v), eye(M))
# MRI operator.
op = mask @ shift.T @ F2 @ shift

y = op @ colvec(img)
x_hat = op.H @ y
```

From left to right we plot the original image, the undersampling in the Fourier space and the reconstruction using the adjoint of the MRI operator.

```python
fig, axs = plt.subplots(1, 3, figsize=(12, 4))
axs[0].imshow(img, cmap="gray", vmin=0, vmax=1)
axs[0].set_title("original")
axs[1].imshow(uncolvec(np.sqrt(y * np.conj(y)).real, (M, N)), cmap="rainbow", vmin=0, vmax=1)
axs[1].set_title("undersampling")
axs[2].imshow(uncolvec(np.real(x_hat), (M, N)), cmap="gray", vmin=0, vmax=1)
axs[2].set_title("adjoint reconstruction")
fig.tight_layout()
```

![](sphinx/source/_static/mri.png)

## Authors

- Pascal Carrivain
- Simon Delamare
- Hakim Hadj-Djilani
- Remi Gribonval

## Contributing

You can contribute to Lazylinop with bug report, feature request and merge request.

## Running unit tests

```bash
cd tests
python3 -m unittest TestLazyLinOp.py
python3 -m unittest TestBasicops.py
python3 -m unittest TestSignal.py
python3 -m unittest TestButterfly.py
python3 -m unittest TestQuantization.py
python3 -m unittest TestLinalg.py
```