pyproximal 0.13.0

Objective

This Python library provides all the needed building blocks for solving non-smooth convex optimization problems using the so-called proximal algorithms.

Whereas gradient based methods are first-order iterative optimization algorithms for solving unconstrained, smooth optimization problems, proximal algorithms can be viewed as an analogous tool for non-smooth and possibly constrained versions of these problems. Such algorithms sit at a higher level of abstraction than classical algorithms like Steepest descent or Newton’s method and require a basic operation to be performed at each iteration: the evaluation of the so-called proximal operator of the functional to be optimized.

Whilst evaluating a proximal operator does itself require solving a convex optimization problem, these subproblems often admit closed form solutions or can be solved very quickly with ad-hoc specialized methods. Several of such proximal operators are therefore implemented in this library.

Here is a simple example showing how to compute the proximal operator of the L1 norm of a vector:

import numpy as np
from pyproximal import L1

l1 = L1(sigma=1.)
x = np.arange(-5, 5, 0.1)
xp = l1.prox(x, 1)

and how this can be used to solve a basic denoising problem of the form: min ||x - y||_2^2 + ||Dx||_1:

import numpy as np
from pylops import FirstDerivative
from pyproximal import L1, L2
from pyproximal.optimization.primal import LinearizedADMM

np.random.seed(1)

# Create noisy data
nx = 101
x = np.zeros(nx)
x[:nx//2] = 10
x[nx//2:3*nx//4] = -5
n = np.random.normal(0, 2, nx)
y = x + n

# Define functionals
l2 = L2(b=y)
l1 = L1(sigma=5.)
Dop = FirstDerivative(nx, edge=True, kind='backward')

# Solve functional with L-ADMM
L = np.real((Dop.H * Dop).eigs(neigs=1, which='LM')[0])
tau = 1.
mu = 0.99 * tau / L
xladmm, _ = LinearizedADMM(l2, l1, Dop, tau=tau, mu=mu,
                           x0=np.zeros_like(x), niter=200)

Why another library for proximal algorithms?

Several other projects in the Python ecosystem provide implementations of proximal operators and/or algorithms, which present some clear overlap with this project.

A (possibly not exhaustive) list of other projects is:

• http://proximity-operator.net
• https://github.com/ganguli-lab/proxalgs
• https://github.com/pmelchior/proxmin
• https://github.com/comp-imaging/ProxImaL
• https://github.com/pyxu-org/pyxu

All of these projects are self-contained, meaning that they implement both proximal and linear operators as needed to solve a variety of problems in different areas of science.

The main difference with PyProximal lies in the fact that we decide not to intertangle linear and proximal operators within the same library. We leverage the extensive set of linear operators provided by the PyLops project and focus only on the proximal part of the problem. This makes the codebase more concise, and easier to understand and extend. Moreover many of the problems that are solved in PyLops can now be also solved by means of proximal algorithms!

Project structure

This repository is organized as follows:

• pyproximal: python library containing various orthogonal projections, proximial operators, and solvers
• pytests: set of pytests
• testdata: sample datasets used in pytests and documentation
• docs: sphinx documentation
• examples: set of python script examples for each proximal operator to be embedded in documentation using sphinx-gallery
• tutorials: set of python script tutorials to be embedded in documentation using sphinx-gallery

Getting started

You need Python 3.10 or greater.

From PyPI

To get the most out of PyProximal straight out of the box, we recommend using the PyPI distribution via uv:

uv pip install pyproximal

or directly via pip:

pip install pyproximal

From Conda

You can also install PyProximal via conda:

conda install -c conda-forge pyproximal

From Github

Finally, you can also directly install from the main branch (although this is not recommended) via uv:

uv add git+https://github.com/PyLops/pyproximal.git --branch main

or via pip:

pip install git+https://git@github.com/PyLops/pyproximal.git@main

Contributing

Feel like contributing to the project? Adding new operators or tutorial?

We advise using the Anaconda Python distribution to ensure that all the dependencies are installed via the Conda package manager. Follow the following instructions and read carefully the CONTRIBUTING file before getting started.

1. Fork and clone the repository

Execute the following command in your terminal:

git clone https://github.com/your_name_here/pyproximal.git

2. Install PyProximal in a new Conda environment

To ensure that further development of PyProximal is performed within the same environment (i.e., same dependencies) as that defined by environment-dev.yml/environment-dev-arm.yml files, we suggest to work off a new Conda enviroment.

The first time you clone the repository run the following command:

make dev-install_conda

To ensure that everything has been setup correctly, run tests:

make tests

Make sure no tests fail, this guarantees that the installation has been successfull.

Remember to always activate the conda environment every time you open a new terminal by typing:

source activate pyproximal

If you prefer to use uv, checkout the Contributing page in the official documentation.

Documentation

The official documentation of PyProximal is available here.

Moreover, if you have installed PyProximal using the developer environment you can also build the documentation locally by typing the following command:

make doc

Once the documentation is created, you can make any change to the source code and rebuild the documentation by simply typing

make docupdate

Note that if a new example or tutorial is created (and if any change is made to a previously available example or tutorial) you are required to rebuild the entire documentation before your changes will be visible.

Citing

When using PyProximal in scientific publications, please cite the following paper:

• Ravasi M, Örnhag M. V., Luiken N., Leblanc O. and Uruñuela E., 2024, PyProximal - scalable convex optimization in Python, Journal of Open Source Software, 9(95), 6326. doi: 10.21105/joss.06326 (link)

Contributors

• Matteo Ravasi, mrava87
• Nick Luiken, NickLuiken
• Eneko Uruñuela, eurunuela
• Marcus Valtonen Örnhag, marcusvaltonen
• Olivier Leblanc, olivierleblanc
• Toru Tamaki, tttamaki
• Mika Mikasuki, mikamikasuki