Library for solving linear inverse problems with state-of-the-art proximal algorithms.

## Project description

Pycsou is a Python 3 package for solving linear inverse problems with state-of-the-art proximal algorithms. The software implements in a highly modular way the main building blocks -cost functionals, penalty terms and linear operators- of generic penalised convex optimisation problems.

Pycsou’s documentation is available at https://matthieumeo.github.io/pycsou/html/index

This Python library is inspired by the MATLAB GlobalBioIm project. The LinearOperator interface is based on scipy.sparse and Pylops.

## Functionalities

Pycsou makes it very easy to construct and solve penalised optimisation problems:

1. It offers a rich collection of linear operators, loss functionals and penalty functionals commonly used in practice.

2. It implements arithmetic operations for linear operators, loss functionals and penalty functionals, hence allowing to add, substract, scale, compose, exponentiate or stack those various objects with one another and hence quickly design custom complex optimisation problems.

3. It implements a rich collection of state-of-the-art iterative proximal algorithms, including efficient primal-dual splitting methods which involve only gradient steps, proximal steps and simple linear evaluations.

4. It supports matrix-free linear operators, making it easy to work with large scale linear operators that may not necessarily fit in memory. Matrix-free linear operators can be implemented from scratch by subclassing the asbtract class LinearOperator, or built from Scipy sparse matrices, distributed Dask arrays or Pylops matrix-free operators (which now support GPU computations).

5. It implements automatic differentiation/proximation rules, allowing to automatically compute the derivative/proximal operators of functionals constructed from arithmetic operations on common functionals shipped with Pycsou.

6. It leverages powerful rule-of-thumbs for setting automatically the hyper-parameters of the provided proximal algorithms.

7. Pycsou is designed to easily interface with the packages scipy.sparse and Pylops. This allows to use the sparse linear algebra routines from scipy.sparse on Pycsou LinearOperator, and benefit from the large catalogue of linear operators and solvers from Pylops.

## Installation

Pycsou requires Python 3.6 or greater.It is developed and tested on x86_64 systems running MacOS and Linux.

### Dependencies

The package dependencies are listed in the files requirements.txt and requirements-conda.txt. It is recommended to install dependencies using Miniconda or Anaconda. This is not just a pure stylistic choice but comes with some hidden advantages, such as the linking to Intel MKL library (a highly optimized BLAS library created by Intel).

To do so we create an environment named pycsou (you can change that if you wish) and equip it with the necessary requirements:

>> conda create -n pycsou python=3.6
>> conda install -n pycsou --channel=conda-forge --file=requirements-conda.txt
>> conda activate pycsou

### Quick Install

Pycsou is available on Pypi. You can hence install it very simply via the command:

>> pip install pycsou

If you have previously activated your conda environment pip will install Pycsou in said environment. Otherwise it will install it in your base environment together with the various dependencies obtained from the file requirements.txt.

### Developper Install

It is also possible to install Pycsou from the source for developpers:

>> git clone https://github.com/matthieumeo/pycsou
>> cd <repository_dir>/
>> pip install -e .

The package documentation can be generated with:

>> conda install -n pycsou sphinx=='2.1.*'            \
sphinx_rtd_theme=='0.4.*'
>> conda activate pycsou
>> python3 setup.py build_sphinx

You can verify that the installation was successful by running the package doctests:

>> conda activate pycsou
>> python3 test.py

### Cite

For citing this package, please see: http://doi.org/10.5281/zenodo.4486431