PhasePack

A phase retrieval library

Phase retrieval is the recovery of a signal from only the magnitudes, and not the phases, of complex-valued linear measurements. Phase retrieval problems arise in many different applications, particularly in crystallography and microscopy. Mathematically, phase retrieval recovers a complex valued signal \(x\in \mathbb{C}^n\) from \(m\) measurements of the form

\begin{align} \label{eq:original} b_i = | a_i^T x|, \quad i = 1,2,\ldots,m, \end{align}

where \(\{a_i\}\) are complex-valued measurement vectors.

PhasePack is a collection of sub-routines for solving classical phase retrieval problems. PhasePack contains implementations of both classical and contemporary phase retrieval routines. It also contains scripts that apply these signal recovery routines to datasets, and compares the results of different methods in terms of speed and quality. PhasePack can do comparisons not only with synthetic datasets, but also with several publicly available real-world datasets.

The routines implemented in PhasePack share a simple common interface, making it easy to switch between solvers. The interface also gives users the option to control the initialization and runtime of different algorithms, making it easy to “plug and play” different routines and options.

Downloads

You can obtain the most up-to-date PhasePack by clicking the “Clone or Download” button from the GitHub page below. PhasePack comes with a detailed user guide that explains how to use the library and contains worked examples. Finally, the original PhasePack paper contains information about how various algorithms are implemented and optimized for performance.

PhasePack Download Page on GitHub
PhasePack User Guide
PhasePack Paper

What can PhasePack do?

PhasePack can compare different methods under varying conditions using both real and synthetic datasets. This example output shows results produced by the runBenchmark1DGaussianMN script located inside the benchmarks folder. It shows the relative error in the reconstructed signal produced by several algorithms as a function of the oversampling ratio (the number of measurements divided by the signal dimensionality). Results are shown for both synthetic (random Gaussian) and empirical (transmission matrix) measurement operators.

PhasePack can also reconstruct images from empirical optical measurements, and produce quantitative measures of the resulting image quality. Below are images reconstructed from empirical measurements using a range of algorithms, and accompanying residual error of each. These results were produced by the script runBenchmarkTransmissionMatrix within the benchmarks folder.

Getting Started

PhasePack comes with a short user guide that explains how to get started, and how to obtain and use the empirical datasets. We include a high-level overview below, but we suggest consulting the user guide before use.

After downloading the PhasePack distribution, add it (and its sub-folders) to your Matlab path. Files with names that begin with “run…” are runnable scripts that require no arguments or setup. The top-level folder contains a script called runSignalReconstructionDemo, which contains a simple example of obtaining phaseless measurements from a signal using a random Gaussian measurement matrix, and recovering the signal using PhasePack. The top-level folder also contains a script called runImageReconstructionDemo, which contains a more complex example of building a Fourier measurement operator from scratch, extracting phaseless measurements from an image using the operator, and recovering the image from the measurements using PhasePack.

The examples sub-folder contains demos of how to use each of the specific solvers implemented in PhasePack. For example, the script examples/runWirtFlow builds a simple test problem and solves it using the Wirtinger flow algorithm, whereas examples/runTruncatedAmpFlow does the sample thing with Truncated Amplitude Flow.

The benchmarks folder contains scripts for comparing and benchmarking the performance of different solvers. To run a comparison between numerous solvers for signal reconstruction from Gaussian measurements, run the script benchmarks/runBenchmark1DGaussianMN. This script measures the accuracy of signal recovery using various algorithms, and plots the accuracy as a function of the number of measurements.

Using empirical data

PhasePack can be used to evaluate methods on pre-packaged empirical datasets. The library contains functions that will unpack and pre-process that datasets for you, and return a simple measurement operator (\(A\)) and measurement vector (\(b\)) that can be used for phase retrieval. The empirical datasets recover images from measurements through a diffusive medium by using “transmission matrices.” See this article for details of the phase retrieval problem, and how the transmission matrix data is constructed.

Before using the empirical transmission matrix datasets, the data needs to be downloaded and installed into the data folder that comes with PhasePack. To do this, visit this link, and click the black “Download” button in the upper right corner. The download is a zip file named “TransmissionMatrices.zip.” The folder contains over 1Gb of data, and may take some time to download.

Locate the “data” sub-folder of the PhasePack distribution, and unzip the contents into the location “data/TransmissionMatrices.” If successful, “data/TransmissionMatrices” should contain the sub-folders “Coherent_Data,” “Functions,” and the file “ReadMe.txt.”

What methods are currently implemented?

Currently, PhasePack contains implementations of the methods listed below. For each method, we list the short name (used when selecting the algorithm in PhasePack) in addition to a longer, more descriptive name.

Short name	Full name
WirtFlow	Wirtinger Flow Algorithm
TWF	Truncated Wirtinger Flow Algorithm
RWF	Reweighted Wirtinger Flow Algorithm
TAF	Truncated Amplitude Flow Algorithm
RAF	Re-Weighted Amplitude Flow Algorithm
GerchbergSaxton	Gerchberg-Saxton Algorithm
Fienup	Fineup Algorithm
Kaczmarz	Kaczmarz Algorithm
CoordinateDescent	Coordinate Descent Algorithm
PhaseMax	Phasemax Algorithm
AmplitudeFlow	AmplitudeFlow Algorithm
PhaseLift	Phaselift Algorithm
SketchyCGM	SketchyCGM Algorithm
PhaseLamp	PhaseLamp algorithm

PhasePack also has numerous methods for algorithm initialization. This includes spectral methods (including variants with different weighting schemes), and the orthogonality-promoting (aka Null) initializer.

Detailed algorithmic descriptions and citations to relevant papers are included in the headers of the corresponding implementation files.

Want to contribute a method?

If you think we’re missing something, or you’d like to add your own routine to PhasePack, email the developers or create a pull request on Github.

Who?

PhasePack was developed by

Rohan Chandra - University of Maryland
Ziyuan Zhong - Columbia University
Justin Hontz - University of Maryland
Val McCulloch - Smith College

…and faculty advisors
Christoph Studer - Cornell University
Tom Goldstein - University of Maryland

How to cite PhasePack

If you find that PhasePack has contributed to your work, please cite the following article.

@article{chandra2017phasepack,
    title={PhasePack: A Phase Retrieval Library},
    author={Chandra, Rohan and Zhong, Ziyuan and Hontz, Justin and McCulloch, Val  
     and Studer, Christoph and Goldstein, Tom},
    journal={Asilomar Conference on Signals, Systems, and Computers},
    year={2017}
}

Also, if you use the empirical transmission matrix datasets, then please cite the creators.

@article{metzler2017coherent,
    title={Coherent inverse scattering via transmission matrices: Efficient phase   
    retrieval algorithms and a public dataset},
    author={Metzler, Christopher A and Sharma, Manoj K and Nagesh, Sudarshan and Baraniuk, Richard G and Cossairt, Oliver and Veeraraghavan, Ashok},
    journal={IEEE International Conference on Computational Photography (ICCP)},
    year={2017}
}

Acknowledgements

This work was made possible by the generous support of the National Science Foundation.
Datasets were furnished by Chris Metzler, Manoj Sharma, and Ashok Veeraraghavan.