THE TOMOGRAPHER PROJECT

A toolbox for error analysis in quantum tomography.

Overview

This project comprises three parts:

• The tomorun program — use this to analyze data from a typical tomography experiment;

• The generic, Tomographer C++ framework — a flexible set of tools to run Metropolis-Hastings random walks, deal with density matrices, and other utilities;

• A python interface — analyze data from a typical tomography experiment in a python workflow.

The tomorun executable produces a histogram of a figure of merit under the distribution relevant for a reliable error analysis as described in Faist & Renner, Practical and Reliable Error Bars in Quantum Tomography, Phys. Rev. Lett. 117, 010404 (2016) (arXiv:1509.06763). The python interface provides an interface to the essentially the same functionality as tomorun from python/numpy code (plus the possibility for calculating a custom figure of merit).

The C++ framework is a set of abstract and generic classes which you can combine in your preferred way to implement this random walk for even more general settings.

Download

Tomographer can be downloaded from our releases page:

https://github.com/Tomographer/tomographer/releases

There are precompiled binary releases for Mac OS X, Linux, and Windows. If a binary isn't available for your platform or if it doesn't run, you may have to compile from source. Don't worry, that's not complicated. If you haven't already done so, install all the usual development tools (gcc/g++/make/etc.) and follow the Installation instructions below.

If you compile from source, make sure you download the offical source package from our releases page (or clone the git repo). If you use github's automatic `Download ZIP' links from the source code, you'll end up with missing files.

If you wish to contribute to development, don't hesitate to fork the repo on github and send me pull requests, or to contact me if you have questions.

Prerequisites

To run tomorun: If you're lucky and there's a binary release for your system, you won't need anything else.

To compile tomorun from source, you'll need:

• a recent C++ compiler (g++ ≥ 4.8, Intel ICC ≥ 14, LLVM/Clang++ ≥ 3.3)
• CMake ≥ 3.1
• Boost libraries ≥ 1.40
• Eigen3 library ≥ 3.3
• MatIO library

To install the Python tomographer package, you'll need:

• pip, the Python package manager — you probably already have it (≥ 7.1)
• a recent C++ compiler (g++ ≥ 4.8, Intel ICC ≥ 14, LLVM/Clang++ ≥ 3.3)
• Optional: you can also install tomographer in a conda environment, which can automatically provide both above requirements

OR: you can compile from source, in which case you'll need:

• a recent C++ compiler (g++ ≥ 4.8, Intel ICC ≥ 14, LLVM/Clang++ ≥ 3.3)
• Boost headers ≥ 1.40 and BCP
• PyBind11 ≥ 2.2
• Python 2.7 or Python 3
• Eigen3 library ≥ 3.3

In any case a recent C++ compiler is required as some C++11 features and elements of its standard library are used.

Tomorun is tested on Linux/Ubuntu, Mac OS X and Windows (MinGW32). The python package is tested on Linux and Mac OS X.

Note: OpenMP is now no longer needed if your compiler supports C++ threads (std::thread). This is the case for many compilers, including Apple's clang.

Tip: On Apple Mac OS X with homebrew, the following commands will get you started with all the prerequisites for compiling both tomorun and the Python tomographer package, using Homebrew's python3. For python, you should also consider using conda.

> brew tap homebrew/science
> brew install python3 boost boost-bcp eigen libmatio pybind11

Installing and Running tomorun

If you found a binary release for your system, simply unpack it wherever you like. It is then ready for use—skip down to "Running tomorun".

Compiling Tomorun from source

The configuration, compilation and installation process is done using CMake. (You'll need CMake ≥ 3.1. Don't worry, it's easy to install a binary release.) Download an official release of Tomographer, unpack it, and enter the unpacked directory. Then, issue the commands:

tomographer-X.X> mkdir build
tomographer-X.X> cd build
tomographer-X.X/build> cmake ..
tomographer-X.X/build> make
tomographer-X.X/build> make install/strip

And you'll have the tomorun installed on your system.

You may also run CMake multiple times to adjust all the relevant options. You can specify some standard CMake variables, such as CMAKE_INSTALL_PREFIX. If you installed a recent compiler manually, you'll need to point CMake to that compiler, e.g. with

> cmake .. -DCMAKE_C_COMPILER=/path/to/gcc -DCMAKE_CXX_COMPILER=/path/to/g++ 

To specify paths to the Boost, Eigen3 and MatIO libraries, use the CMake switches:

-DEIGEN3_INCLUDE_DIR=/path/to/include/eigen3
-DBOOST_ROOT=/path/to/boost
-DMATIO_LIBRARY=/path/to/libmatio.a
-DMATIO_INCLUDE_DIR=/path/to/include

You may of course also alternatively use CMake's graphical interface, CMake-GUI.

Note the compilation step (make) is quite computation-heavy because of the extensive C++11 template metaprogramming. It might take a minute or two to complete depending on your hardware, and might be pretty greedy on RAM.

GCC/G++ and RAM usage: The heavy template meta-programming can cause GCC/G++ to use a LOT of memory while compiling. If your system is limited on memory, you should consider tuning the gcc flags --param ggc-min-expand and --param ggc-min-heapsize: I have found --param ggc-min-expand=10 --param ggc-min-heapsize=32768 to work all right for 4GB of memory; if you want to be really conservative use --param ggc-min-expand=0 --param ggc-min-heapsize=8192. These options should be specified to CMake as -DCMAKE_CXX_FLAGS="--param ...".

Running tomorun

Check out the online quick start page. In the binary distributions, tomorun is located in the bin/ subdirectory. Detailed information about how to use & run tomorun is obtained by querying its help text:

> tomorun --help

Data is read from a file in MATLAB format (see option --data-file-name), and several options control which figure of merit to calculate as well as the parameters and behavior of the random walk.

As tomorun is running, you may query its progress by hitting CTRL-C (Linux/Mac OS X). If you want to interrupt tomorun and quit the current task, hit CTRL-C twice in short succession.

Also, it is often more convenient to make tomorun read its options from a configuration file:

> tomorun --config myconfigfile

An example config file would be:

# Configuration file for an execution of `tomorun`.  Lines starting with '#'
# are comments and are ignored.

# The data file which contains the POVM effects and frequencies etc.
data-file-name=the_data.mat

# Write the histogram to the file named "<myconfigfile>-histogram.csv"
write-histogram-from-config-file-name = 1

# Number of random walk instances. Tip: Use all your CPU's.
n-repeats = 12

# Step size of the random walk. Adjust so that the acceptance ratio is
# around 0.25-0.4.
step-size = 0.01

# Sweep size. Keep only one in so many samples, to decorrelate them.
# Choose of the order of 1/<step-size>
n-sweep = 100

# Run this many sweeps before recording any samples (to thermalize the
# random walk)
n-therm = 1024

# Run until we have recorded this number of samples. Power of two
# recommended for binning analysis (the default)
n-run = 32768

# Choice of figure of merit. Here for example, tr(rho*rho_ref). If rho_ref
# is pure, this is exactly the (squared) fidelity to rho_ref. "rho_ref" is
# the name of a variable defined in 'the_data.mat'
value-type=obs-value:rho_ref

# The parameters of the histogram. MIN:MAX/NUM_BINS
value-hist=0.9:1/50

MATLAB Tools

Some tools are provided for fitting the resulting histogram to our theoretical model. These are MATLAB scripts located in the tools subdirectory.

For more information on how to run the histogram analyzer/fitter, run:

>> analyze_tomorun_histogram('Help')

Installing and Using the Python Package

For an overview, you may want to check out the online quick start page.

Install using PIP — the easy way

First, make sure you install the prerequisites. (You do have to install the numpy and pybind11 dependencies manually before installing tomographer. This is because pip apparently doesn't know how to correctly handle build-time dependencies.)

# If using *conda*:

> conda install numpy gcc libgcc
> conda install -c conda-forge pybind11

# OR: if using *pip* by itself:

> pip install numpy pybind11

All `pi