Overview

SParse Optimization Research COde (SPORCO) is a Python package for solving optimisation problems with sparsity-inducing regularisation [22]. These consist primarily of sparse coding [11] and dictionary learning [13] problems, including convolutional sparse coding and dictionary learning [32], but there is also support for other problems such as Total Variation regularisation [24] [3] and Robust PCA [7]. The optimisation algorithms in the current version are based on the Alternating Direction Method of Multipliers (ADMM) [6] or on the Fast Iterative Shrinkage-Thresholding Algorithm (FISTA) [4].

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

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. 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 [33] or [36] (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. [32], [30], [31], [29], [17].

Contact

Please submit bug reports, comments, etc. to brendt@ieee.org. Bugs and feature requests can also be reported 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 material was produced under U.S. Government contract DE-AC52-06NA25396 for Los Alamos National Laboratory (LANL), which is operated by Los Alamos National Security, LLC for the U.S. Department of Energy. The U.S. Government has rights to use, reproduce, and distribute this software. NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE. If 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.