Qubit Allocation

This project aims to reproduce the results of CGO’18 paper “Qubit Allocation”.

Inside we have Enfield, IBM’s qiskit-sdk-py, benchmarks and scripts that shall help running the experiments.
There are some software dependencies: flex (2.6.1); bison (3.0.4); googletest; python3; and R (with ggplot2).

Installation and download of the qiskit-sdk-py can be found here.
Note that the only thing left to be done is to install the python dependencies with pip the dependencies in the path qiskit-sdk-py/requires.txt:

$ pip install -r requires.txt

Installation and download of the googletest framework can be found here.
After installing R, you should run it by issuing R in the command line, then:

install.packages("ggplot2")

Project Structure

The top-level of this project contains the following:

• [enfield/]: the Enfield QASM front-end;
• [enfield-bench/]: all the benchmarks used;
• [qiskit-sdk-py/]: the IBM SDK for quantum information;
• [scripts/]: scripts that help executing the experiments;
• [results/]: files generated from the script for reproducing experiments;
• [compile.sh]: compiles Enfield;
• [compile-with-tests.sh]: compiles Enfield;
• [reproduce_experiments.sh]: executes all experiments from the paper;
• [enfield_args]: enfield extra command lines.

Building

As qiskit-sdk-py is a python project there is nothing more to be done. Enfield must be compiled issuing the following:

# If you wish to run the unit tests
$ ./compile-with-tests.sh
# If you do not wish to run the unit tests
$ ./compile.sh

Or, if one wants to compile manually:

$ cd enfield
$ mkdir build
$ cmake ../ -DENABLE_TESTS=ON
$ make && make test

If you don’t have googletest framework, you should execute the following instead:

$ cd enfield
$ mkdir build
$ cmake ../
$ make && make test

Reproducing the Paper’s Experiments

After compiling, one should issue the command:

./reproduce_experiments.sh <number-of-runs>

where <number-of-runs> refers to the number of times each benchmark should be run. In this paper we have set it to 5. After executing this command (which should take a while), you should get these seven files:

• ibm-data.txt: raw data from ibm-benchmarks benchmarks;
• qx2-data.txt: raw data from random-ibmqx2 benchmarks;
• qx3-data.txt: raw data from random-ibmqx3 benchmarks;
• Figure14.pdf;
• Figure15.pdf;
• Figure17.pdf;
• Figure18.pdf.

(Note that the raw data files are in csv format, first line being a header line)
With these in hands, one should be able to verify the paper’s results. There are also the results obtained for the paper inside the folder results/ (both the images and as well as the raw data).

The above command runs three experiments. One can also run them separately as the table below shows:

Script	Architecture	Benchmark	Figures
scripts/run-ibm.sh	ibmqx2	ibm-benchmarks	14, 17
scripts/run-qx2.sh	ibmqx2	random-ibmqx2	15
scripts/run-qx3.sh	ibmqx3	random-ibmqx3	18

Customizing Experiments

Enfield lets the user tweak it by passing command line arguments. One of the things is the cost of the quantum transformations: reversal, swap and bridge. In order for passing more command lines to enfield’s execution in the scripts the user should only edit the file enfield\_args in the root directory (one command at each line).

For example, if one wishes to change the costs of reversal to 10, swap to 20 and bridge to 30, the enfield_args should look like this:

--rev-cost
10
--swap-cost
20
--lcx-cost
30

It is not the same for qiskit-sdk-py. If one wants to tweak it also, he should change the hard-coded cost inside: qiskit-sdk-py/qiskit/mapping/\_mapping.py.

Running Separately

Enfield

Enfield’s binary is in enfield/build/tool/efd. It has some command line arguments, such as:

Argument	Description
-i	input file
-o	output file
-stats	show statistical information after execution
-alloc	specify the qubit allocator to be used
-arch	specify the quantum architecture to be used

The option -alloc can have the following values:

• dynprog: the exact qubit allocator;
• wpm: our qubit allocator heuristic;
• qubiter: a qubit allocator cited in the paper;
• wqubiter: a variation of the above;
• random: same as wpm without the initial allocation phase.

The option -arch can have the following values:

• ibmqx2: 5-qubit IBM architecture;
• ibmqx3: 16-qubit IBM architecture;
• <filename>: it searches for <filename> and loads as an architecture.

Given that n is the number of vertices and ai bi indicates an edge between them:

n
a1 b1
a1 bn
a2 b3
an bn
...

It also has command line arguments for changing the cost for each quantum transformation:

Argument	Transformation
--rev-cost	reversal gate
--swap-cost	swap gate
--lcx-cost	bridge gate

One example of usage:

$ enfield/build/tools/efd -i enfield-bench/ibm-benchmarks/pea.qasm \
            -alloc wpm -arch ibmqx2 \
            --rev-cost 8 --swap-cost 20 --lcx-cost 22 \
            -stats

qiskit-sdk-py

When running the experiments for qiskit-sdk-py, one should use the python script we implemented qiskit-sdk-py/IBMFront.py. It should be used as follows:

$ python3 IBMFront.py <filename> <architecture>

Where <architecture> may be either:

• ibmqx2: 5-qubit IBM architecture;
• ibmqx3: 16-qubit IBM architecture;

Example:

$ python3 qiskit-sdk-py/IBMFront.py enfield-bench/ibm-benchmarks/grv.qasm ibmqx2