# 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 their 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 onComputational 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.