Overview

SParse Optimization Research COde (SPORCO) is a Python package for solving optimisation problems with sparsity-inducing regularisation [36]. These consist primarily of sparse coding [16] and dictionary learning [20] problems, including convolutional sparse coding and dictionary learning [53], but there is also support for other problems such as Total Variation regularisation [41] [3], Robust PCA [11], and Plug and Play Priors [48]. The optimisation algorithms in the current version are based on the Alternating Direction Method of Multipliers (ADMM) [9] or on the Fast Iterative Shrinkage-Thresholding Algorithm (PGM) [6].

In addition to this documentation, an overview of the design and functionality of SPORCO is also available in [57].

GPU Acceleration

GPU accelerated versions of some of the SPORCO solvers are provided within the sporco.cuda and sporco.cupy subpackages. Use of the former requires installation of the SPORCO-CUDA extension package, while the latter requires installation of CuPy [38]. The sporco.cupy subpackage supports a much wider range of problems than sporco.cuda, which only supports four different variants of convolutional sparse coding. However, the sporco.cuda functions are substantially faster than the corresponding functions in sporco.cupy since those in sporco.cuda are implemented directly in CUDA, while those in sporco.cupy use CuPy as a replacement for NumPy.

Usage Examples

Usage examples are available as Python scripts and Jupyter Notebooks.

Example Scripts

A large collection of scripts illustrating usage of the package can be found in the examples directory of the source distribution. These examples can be run from the root directory of the package by, for example

python examples/scripts/sc/bpdn.py

To run these scripts prior to installing the package it will be necessary to first set the PYTHONPATH environment variable to include the root directory of the package. For example, in a bash shell

export PYTHONPATH=$PYTHONPATH:`pwd`

from the root directory of the package, or in a Windows Command Prompt shell

set PYTHONPATH=%PYTHONPATH%;C:\path_to_sporco_root

If SPORCO has been installed via pip, the examples can be found in the directory in which pip installs documentation, e.g. /usr/local/share/doc/sporco-x.y.z/examples/.

Jupyter Notebooks

Jupyter Notebook examples are also available. These examples can be viewed online via nbviewer, or run interactively at binder.

Citing

If you use this library for published work, please cite [54] or [57] (see bibtex entries wohlberg-2016-sporco and wohlberg-2017-sporco in docs/source/references.bib in the source distribution). If you use of any of the convolutional sparse representation classes, please also cite any other papers relevant to the specific functionality that is used, e.g. [53], [51], [52], [50], [26].

Contact

Please submit bug reports, feature requests, etc. via the GitHub Issues interface.

License

This package was developed at Los Alamos National Laboratory, and has been approved for public release under the approval number LA-CC-14-057. It is made available under the terms of the BSD 3-Clause License (see the LICENSE file for details).

This package was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so. If this software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.