A toolbox for error analysis in quantum tomography.
This project comprises three parts:
-
The
tomorunprogram — use this to analyze data from a typical tomography experiment; -
The generic,
TomographerC++ 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.
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.
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
tomographerin 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
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".
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 ...".
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
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')
For an overview, you may want to check out the online quick start page.
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 pip install commands (e.g. pip install SOMEPACKAGE) might have to be
prefixed by sudo -H (e.g. sudo -H pip install SOMEPACKAGE) if you need
administrator priviledges, or you can use the option --user to install into a
user directory (e.g. pip install SOMEPACKAGE --user).
Now, install tomographer itself, using pip (this should also work within a
conda environment):
# for both *conda* and *pip* users:
> pip install tomographer
When installing tomographer using pip, you don't need the Eigen and Boost
libraries (which are otherwise prerequisites), as they are bundled along with
the tomographer PyPI python package.
If the installation fails because of a compilation error, then run pip with
the --verbose option, and look at which settings are detected by the setup
script for variables such as CXX_FLAGS. You may override these using
environment variables, for instance: CXX_FLAGS="-stdlib=libc++" OPTIMIZATION_CXX_FLAGS="" pip install tomographer. Consider submitting
a bug report if you think
it's an issue.
Important note for conda users: You must use the same C/C++ compiler as for
the python libraries bundled in conda itself. On Linux, you should use the
version of gcc which conda provides (conda install gcc), and which you might
have to specify explicitly:
> CC=path-to-conda/bin/gcc CXX=path-to-conda/bin/g++ pip install tomographer
I'm not too sure of the exact situation with conda on Mac OS X. It appears
that conda's python is built using Apple's clang, but after some tests it
seems that tomographer will also happily compile with conda's gcc.
The python tomographer package can be installed by entering the py/
directory and running the setup.py script as for usual manual installation of
python packages:
tomographer/py> python setup.py install
If tomographer's C++ library dependencies aren't installed in standard paths,
you may need to specify them directly to the setup.py script in the form of
environment variables (they can also be read from a CMake cache file). Check the
output of setup.py for more info. Compilers may be specified using the
environment variables CC=/path/to/gcc and CXX=/path/to/g++.
The python interface provides a convenient entry point to the C++ routines, with data
provided as NumPy arrays. There are also some additional tools, for example to simulate
measurement outcomes, or to calculate the maximum likelihood estimate given some data.
A couple examples to get started are provided in the examples/ subfolder. We suggest
the use of jupyter notebooks, as they provide a simple and
convenient environment to run python code interactively.
The full documentation of the Python interface can be generated via Sphinx, and is available online here.
Tomographer, at its core, is a set of C++ template classes which can be put together in the way that fits your needs. C++ template metaprogramming is very advantageous performancewise, as most optimizations and specializations are performed during compilation and thus avoiding runtime look-ups.
In most cases, the tomorun executable or the python interface is probably what
you're looking for. However, if you would like to consider a more general
setting (such as a different random walk method), then you can do so by reusing
existing code as much as possible.
The API documentation of the Tomographer C++ Framework can be found
here. You can also build the API documentation of the
Tomographer C++ Framework using Doxygen ≥ 1.8. You'll also need
dot (from the graphviz suite). To build the documentation, simply run
tomographer-X.X/build> make doc
This will create API documentation in both HTML and LaTeX format. The HTML
output is located in build/html and the latex files are in build/latex.
If doxygen was not found by CMake, then re-run cmake specifying the location
of Doxygen using the -DDOXYGEN_EXECUTABLE=/location/of/doxygen switch.
To build the latex documentation, enter the latex directory and run make.
The output file is called refman.pdf.
There is a test suite which checks that the tomographer C++ framework works
correctly, and that no bugs or regressions are being introduced as the code is
being changed and maintained. The tests cover tomorun and the python
interface as well.
To compile and run the test suite, you need to specify to cmake that you want to build it:
tomographer-X.X/build> cmake .. -DTOMOGRAPHER_ENABLE_TESTS=on
The test suite will then be compiled normally when you run make. Use the -j
option with the number of CPU cores on your system to speed up the compilation:
tomographer-X.X/build> make -j4
Run the test suite with the command
tomographer-X.X/build> make test
The test suite uses CTest. You can also run the test programs individually. Most test executables use the Boost Unit Test Framework and as such accept various options to tune verbosity, which tests to run, etc.
Currently, the test suite does not compile entirely under Windows/mingw32/g++ because g++ can't allocate enough memory. I'm not sure how to fix this at the moment (might need to use 64-bit compiler).
Please report bugs, issues and wishes at:
https://github.com/Tomographer/tomographer/issues
Contributions are welcome. The preferred way to submit enhancements is to fork the repo and send me a pull request. Also, don't hesitate to contact me for questions.
If you use this software in your research, please consider citing the following works:
-
Philippe Faist and Renato Renner. Practical and Reliable Error Bars in Quantum Tomography. Physical Review Letters 117:1, 010404 (2016). arXiv:1509.06763
-
Philippe Faist. The Tomographer Project. Available at https://github.com/Tomographer/tomographer/.
Author: Philippe Faist, phfaist@caltech.edu.
Copyright (c) 2016 ETH Zurich, Institute for Theoretical Physics, Philippe Faist
Copyright (c) 2017 Caltech, Institute for Quantum Information and Matter, Philippe Faist
Released under the terms of the MIT License (see file LICENSE.txt)