Skip to content

Commit

Permalink
Merge pull request #5 from iic-jku/teleportation
Browse files Browse the repository at this point in the history 
Teleportation in QMAP

- QMAP now supports Teleportation as in the 2021 ASPDAC paper
  • Loading branch information
@hillmich
hillmich authored Mar 1, 2021
2 parents b683470 + 60b4d27 commit 7e60c55
Show file tree
Hide file tree
Showing 18 changed files with 510 additions and 85 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
- name: Configure CMake
shell: bash
run: cmake -S "${{github.workspace}}" -B "${{github.workspace}}/build" -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBUILD_QMAP_TESTS=ON -DZ3_ROOT=z3/build
run: cmake -S "${{github.workspace}}" -B "${{github.workspace}}/build" -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBUILD_QMAP_TESTS=ON -DZ3_ROOT=z3/build -DBINDINGS=ON

- name: Build
shell: bash
Expand Down Expand Up @@ -130,7 +130,7 @@ jobs:
uses: actions/cache@v2
with:
path: ${{github.workspace}}/boost_1_70_0
key: ${{ runner.OS }}-boost
key: ${{ runner.OS }}-boost170

- name: Download boost
if: steps.cache-boost.outputs.cache-hit != 'true'
Expand Down Expand Up @@ -169,7 +169,7 @@ jobs:
setx path "%path%;${{github.workspace}}\boost_1_70_0"
setx lib "%lib%;${{github.workspace}}\boost_1_70_0\stage\lib"
setx libpath "%libpath%;${{github.workspace}}\boost_1_70_0\stage\lib"
cmake -S "${{github.workspace}}" -B "${{github.workspace}}/build" -DCMAKE_BUILD_TYPE=$BUILD_TYPE -T "ClangCl" -DBoost_USE_STATIC_LIBS=ON -DBoost_USE_MULTITHREADED=ON -DBoost_USE_STATIC_RUNTIME=OFF -DBOOST_ROOT="${{github.workspace}}\boost_1_70_0" -DBOOST_INCLUDEDIR="${{github.workspace}}\boost_1_70_0\include" -DBOOST_LIBRARYDIR="${{github.workspace}}\boost_1_70_0\lib" -DZ3_ROOT=z3/build
cmake -S "${{github.workspace}}" -B "${{github.workspace}}/build" -DCMAKE_BUILD_TYPE=$BUILD_TYPE -T "ClangCl" -DBoost_USE_STATIC_LIBS=ON -DBoost_USE_MULTITHREADED=ON -DBoost_USE_STATIC_RUNTIME=OFF -DBOOST_ROOT="${{github.workspace}}\boost_1_70_0" -DBOOST_INCLUDEDIR="${{github.workspace}}\boost_1_70_0\include" -DBOOST_LIBRARYDIR="${{github.workspace}}\boost_1_70_0\stage\lib" -DZ3_ROOT=z3/build
- name: Build
shell: bash
Expand Down
2 changes: 1 addition & 1 deletion CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.14...3.19)

project(qmap
LANGUAGES CXX
VERSION 1.2.1
VERSION 1.3.0
DESCRIPTION "QMAP - A JKQ library for mapping of quantum circuits to quantum architectures"
)

Expand Down
117 changes: 80 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,22 @@
[![toolset: JKQ](https://img.shields.io/static/v1?label=toolset&message=JKQ&color=blue&style=plastic)](https://github.com/iic-jku/jkq)
[![arXiv](https://img.shields.io/static/v1?label=arXiv&message=1712.04722&color=inactive&style=plastic)](https://arxiv.org/abs/1712.04722)
[![arXiv](https://img.shields.io/static/v1?label=arXiv&message=2009.02376&color=inactive&style=plastic)](https://arxiv.org/abs/2009.02376)
[![arXiv](https://img.shields.io/static/v1?label=arXiv&message=2011.07314&color=inactive&style=plastic)](https://arxiv.org/abs/2011.07314)

# QMAP - A JKQ tool for Quantum Circuit Mapping written in C++
A [JKQ](https://github.com/iic-jku/jkq) tool for quantum circuit mapping by the [Institute for Integrated Circuits](https://iic.jku.at/eda/) at the [Johannes Kepler University Linz](https://jku.at) based on methods proposed in [[1]](https://iic.jku.at/files/eda/2018_tcad_efficient_mapping_of_quantum_circuits_to_ibm_qx_architectures.pdf), [[2]](https://iic.jku.at/files/eda/2019_dac_mapping_quantum_circuits_ibm_architectures_using_minimal_number_swap_h_gates.pdf).
A [JKQ](https://github.com/iic-jku/jkq) tool for quantum circuit mapping by the [Institute for Integrated Circuits](https://iic.jku.at/eda/) at the [Johannes Kepler University Linz](https://jku.at) based on methods proposed in [[1]](https://iic.jku.at/files/eda/2018_tcad_efficient_mapping_of_quantum_circuits_to_ibm_qx_architectures.pdf), [[2]](https://iic.jku.at/files/eda/2019_dac_mapping_quantum_circuits_ibm_architectures_using_minimal_number_swap_h_gates.pdf), [[3]](https://iic.jku.at/files/eda/2021_aspdac_exploiting_teleportation_in_quantum_circuit_mappping.pdf).

[[1]](https://iic.jku.at/files/eda/2018_tcad_efficient_mapping_of_quantum_circuits_to_ibm_qx_architectures.pdf)
A. Zulehner, A. Paler, and R. Wille. **"An Efficient Methodology for Mapping Quantum Circuits to the IBM QX Architectures"**.
IEEE Transactions on Computer Aided Design of Integrated Circuits and Systems (TCAD), 2018.
A. Zulehner, A. Paler, and R. Wille. An Efficient Methodology for Mapping Quantum Circuits to the IBM QX Architectures.
*IEEE Transactions on Computer Aided Design of Integrated Circuits and Systems (TCAD)*, 2018.

[[2]](https://iic.jku.at/files/eda/2019_dac_mapping_quantum_circuits_ibm_architectures_using_minimal_number_swap_h_gates.pdf)
R. Wille, L. Burgholzer, and A. Zulehner. **"Mapping Quantum Circuits to IBM QX Architectures
Using the Minimal Number of SWAP and H Operations"**. In Design Automation Conference (DAC), 2019.
R. Wille, L. Burgholzer, and A. Zulehner. Mapping Quantum Circuits to IBM QX Architectures
Using the Minimal Number of SWAP and H Operations. In *Design Automation Conference (DAC)*, 2019.

[[3]](https://iic.jku.at/files/eda/2021_aspdac_exploiting_teleportation_in_quantum_circuit_mappping.pdf)
S. Hillmich, A. Zulehner, and R. Wille. Exploiting Quantum Teleportation in Quantum Circuit Mapping.
*In Asia and South Pacific Design Automation Conference (ASP-DAC)*, 2021.

The tool can be used for mapping quantum circuits in any of the following formats:
* `QuantumCircuit` object from IBM's [Qiskit](https://github.com/Qiskit/qiskit) (only through the JKQ QMAP Python bindings)
Expand All @@ -37,18 +42,20 @@ to any given architecture, e.g., the IBM Q London architecture, which is specifi
4 3
```
with the following available methods:
- **Heuristic Mapper**: Heuristic solution based on A* search. For details see [[1]](https://iic.jku.at/files/eda/2018_tcad_efficient_mapping_of_quantum_circuits_to_ibm_qx_architectures.pdf).
- **Heuristic Mapper**: Heuristic solution based on A* search. For details see [[1]](https://iic.jku.at/files/eda/2018_tcad_efficient_mapping_of_quantum_circuits_to_ibm_qx_architectures.pdf) and [[3]](https://iic.jku.at/files/eda/2021_aspdac_exploiting_teleportation_in_quantum_circuit_mappping.pdf).
- **Exact Mapper**: Exact solution utilizing the SMT Solver Z3. For details see [[2]](https://iic.jku.at/files/eda/2019_dac_mapping_quantum_circuits_ibm_architectures_using_minimal_number_swap_h_gates.pdf).

Note that, at the moment, circuits to be mapped are assumed to be already decomposed into elementary gates supported by the targeted device. More specifically, circuits must not contain gates acting on more than two qubits.
Note that, at the moment, circuits to be mapped are assumed to be already decomposed into elementary gates supported by the targeted device.
More specifically, circuits must not contain gates acting on more than two qubits.

For more information, please visit [iic.jku.at/eda/research/ibm_qx_mapping/](https://iic.jku.at/eda/research/ibm_qx_mapping/).

If you have any questions, feel free to contact us via [iic-quantum@jku.at](mailto:iic-quantum@jku.at) or by creating an issue on [GitHub](https://github.com/iic-jku/qmap/issues).

## Usage

JKQ QMAP is mainly developed as a C++ library with a [commandline interface](#command-line-executable). However, using it in Python is as easy as
JKQ QMAP is mainly developed as a C++ library with a [commandline interface](#command-line-executable).
However, using it in Python is as easy as
```bash
pip install jkq.qmap
```
Expand All @@ -60,12 +67,13 @@ qmap.compile(circ, arch, ...)
where `circ` is either a Qiskit `QuantumCircuit` object or the path to an input file (supporting various formats, such as `.qasm`, `.real`,...)
and `arch` is either one of the pre-defined architectures (see below) or the path to a file containing the number of qubits and a line-by-line enumeration of the qubit connections.

Architectures that are available per default (under `qmap.Arch.<...>`) include:
- IBM_QX4 (5 qubit, directed bow tie layout)
- IBM_QX5 (16 qubit, directed ladder layout)
- IBMQ_Yorktown (5 qubit, undirected bow tie layout)
- IBMQ_London (5 qubit, undirected T-shape layout)
- IBMQ_Bogota (5 qubit, undirected linear chain layout)
Architectures that are available per default (under `qmap.Arch.<...>`) include (corresponding files are available in `extern/architectures/`):
- `IBM_QX4` (5 qubit, directed bow tie layout)
- `IBM_QX5` (16 qubit, directed ladder layout)
- `IBMQ_Yorktown` (5 qubit, undirected bow tie layout)
- `IBMQ_London` (5 qubit, undirected T-shape layout)
- `IBMQ_Bogota` (5 qubit, undirected linear chain layout)
- `IBMQ_Tokyo` (20 qubit, undirected brick-like layout)

Whether the heuristic (*default*) or the exact mapper is used can be controlled by passing `method=qmap.Method.heuristic` or `method=qmap.Method.exact` to the `compile` function.

Expand All @@ -81,6 +89,9 @@ Params:
method – Mapping technique to use (*heuristic* | exact)
initial_layout – Strategy to use for determining initial layout (only relevant for heuristic mapper)
layering – Circuit layering strategy to use (*individual_gates* | disjoint_qubits | odd_qubits | qubit_triangle)
use_teleportation - Use teleportation in addition to swaps
teleportation_fake - Assign qubits as ancillary for teleportation but don't actually use them
teleportation_seed - Fix a seed for the initial ancilla placement (0 means no fixed seed)
save_mapped_circuit – Include .qasm string of the mapped circuit in result
csv – Create CSV string for result
statistics – Print statistics
Expand All @@ -89,15 +100,19 @@ Returns:
JSON object containing results
"""
def compile(circ, arch: Union[str, Arch],
calibration = "",
calibration: str = "",
method: Method = Method.heuristic,
initial_layout: InitialLayoutStrategy = InitialLayoutStrategy.dynamic,
layering: LayeringStrategy = LayeringStrategy.individual_gates,
use_teleportation: bool = False,
teleportation_fake: bool = False,
teleportation_seed: int = 0,
save_mapped_circuit: bool = False,
csv: bool = False,
statistics: bool = False,
verbose: bool = False
) -> object
) -> Dict[str, Any]:
...
```

Note that in order for the bindings to work the SMT Solver [Z3 >= 4.8.3](https://github.com/Z3Prover/z3) has to be installed on the system and the dynamic linker has to be able to find the library.
Expand All @@ -110,12 +125,14 @@ This can be accomplished in a multitude of ways:
```
- Download pre-built binaries from https://github.com/Z3Prover/z3/releases and copy the files to the respective system directories
- Build Z3 from source and install it to the system


### Command-line Executable
JKQ QMAP also provides two **standalone executables** with command-line interface called `qmap_heuristic` and `qmap_exact`.
They provide the same options as the Python module as flags (e.g., `--ps` for printing statistics). Per default, this produces JSON formatted output.

```commandline
$ ./qmap_heuristic --in grover_2.qasm --out grover_2m.qasm --arch ibmq_london.arch --ps
$ ./qmap_heuristic --in grover_2.qasm --out grover_2m.qasm --arch extern/architectures/ibm_london_5qubit.arch --ps
{
"circuit": {
"name": "grover_2",
Expand All @@ -138,7 +155,7 @@ $ ./qmap_heuristic --in grover_2.qasm --out grover_2m.qasm --arch ibmq_london.ar
The heuristic mapping tool `qmap_heuristic` also offers the `--initiallayout` option, which allows to choose one of the following strategies for choosing an initial layout:
- `identity`: map logical qubit q_i to physical qubit Q_i,
- `static`: determine fixed initial layout statically at the start of mapping,
- `dynamic` (*default*): determine initial layout on demand during the mapping.
- `dynamic` (*default*): determine initial layout on demand during the mapping (this is the only one compatible with teleportation).

Both, the exact and the heuristic mapping tool also offer the `--layering` option, which allows to choose one of the following strategies for partitioning the circuit:
- `individual` (*default*): consider each gate separately,
Expand Down Expand Up @@ -203,9 +220,10 @@ Internally the JKQ QMAP library works in the following way
To start off, clone this repository using
```shell
git clone --recurse-submodules -j8 https://github.com/iic-jku/qmap
$ git clone --recurse-submodules -j8 https://github.com/iic-jku/qmap
```
Note the `--recurse-submodules` flag. It is required to also clone all the required submodules. If you happen to forget passing the flag on your initial clone, you can initialize all the submodules by executing `git submodule update --init --recursive` in the main project directory.
Note the `--recurse-submodules` flag. It is required to also clone all the required submodules.
If you happen to forget passing the flag on your initial clone, you can initialize all the submodules by executing `git submodule update --init --recursive` in the main project directory.
Our projects use CMake as the main build configuration tool. Building a project using CMake is a two-stage process. First, CMake needs to be *configured* by calling
```shell
Expand All @@ -216,7 +234,7 @@ The flag `-DCMAKE_BUILD_TYPE=Release` tells CMake to configure a *Release* build
After configuring with CMake, the project can be built by calling
```shell
cmake --build build --config Release
$ cmake --build build --config Release
```
This tries to build the project in the `build` directory (passed via `--build`).
Some operating systems and developer environments explicitly require a configuration to be set, which is why the `--config` flag is also passed to the build command. The flag `--parallel <NUMBER_OF_THREADS>` may be added to trigger a parallel build.
Expand All @@ -229,29 +247,54 @@ Building the project this way generates
- the exact mapper commandline executable `qmap_exact` in the `build/apps` directory (only available if Boost and Z3 is found)
- a test executable `qmap_exact_test` containing a small set of unit tests for the exact mapper in the `build/test` directory (only available if Z3 is found)
### Extending the Python Bindings
To extend the Python bindings you can locally install the package in edit mode, so that changes in the Python code are instantly available.
The following example assumes you have a [virtual environment](https://docs.python.org/3/library/venv.html) set up and activated.
```commandline
(venv) $ pip install cmake
(venv) $ pip install --editable .
```
If you change parts of the C++ code, you have to run the second line to make the changes visible in Python.
## Reference
If you use our tool for your research, we will be thankful if you refer to it by citing one or both of the following publications.
If you use our tool for your research, we will be thankful if you refer to it by citing the appropriate publications.
For the [heuristic mapping](https://dblp.org/rec/journals/tcad/ZulehnerPW19.html?view=bibtex), please cite
```bibtex
@article{DBLP:journals/tcad/ZulehnerPW19,
author = {Alwin Zulehner and Alexandru Paler and Robert Wille},
title = {An Efficient Methodology for Mapping Quantum Circuits to the {IBM QX} Architectures},
journal = {{IEEE} Transactions on Computer-Aided Design of Integrated Circuits and Systems},
volume = {38},
number = {7},
pages = {1226--1236},
year = {2019}
}
```
If you used the heuristic mapping, please cite
For the [teleportation in the heuristic mapping](https://dblp.org/rec/conf/aspdac/HillmichZW21.html?view=bibtex), please cite
```bibtex
@article{zulehner2019efficient,
title={An efficient methodology for mapping quantum circuits to the {IBM} {QX} architectures},
author={Zulehner, Alwin and Paler, Alexandru and Wille, Robert},
journal={{IEEE} Transactions on Computer-Aided Design of Integrated Circuits and Systems},
volume={38},
number={7},
pages={1226--1236},
year={2019}
@inproceedings{DBLP:conf/aspdac/HillmichZW21,
author = {Stefan Hillmich and Alwin Zulehner and Robert Wille},
title = {Exploiting Quantum Teleportation in Quantum Circuit Mapping},
booktitle = {Asia and South Pacific Design Automation Conference},
pages = {792--797},
publisher = {{ACM}},
year = {2021}
}
```
If you used the exact mapping, please cite
For the [exact mapping](https://dblp.org/rec/conf/dac/WilleBZ19.html?view=bibtex), please cite
```bibtex
@inproceedings{wille2019mapping,
title={Mapping Quantum Circuits to {IBM QX} Architectures Using the Minimal Number of {SWAP} and {H} Operations},
author={Wille, Robert and Burgholzer, Lukas and Zulehner, Alwin},
booktitle={Design Automation Conference},
year={2019}
@inproceedings{DBLP:conf/dac/WilleBZ19,
author = {Robert Wille and Lukas Burgholzer and Alwin Zulehner},
title = {Mapping Quantum Circuits to {IBM QX} Architectures Using the Minimal Number of {SWAP} and {H} Operations},
booktitle = {Design Automation Conference},
publisher = {{ACM}},
year = {2019}
}
````
11 changes: 10 additions & 1 deletion apps/heuristic_app.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ int main(int argc, char** argv) {
("calibration", po::value<std::string>(), "Calibration to use (points to a file)")
("initiallayout", po::value<std::string>(), R"(Initial layout strategy ("identity" | "static" | "dynamic"))")
("layering", po::value<std::string>(), R"(Layering strategy ("individual" | "disjoint"))")
("teleportation", po::value<unsigned long long int>()->implicit_value(0), "Use teleportation with optionally specifying the seed for the RNG used for initial placement")
("teleportation_fake", "Assign qubits as ancillary for teleportation in the initial placement but don't actually use them")
("ps", "print statistics")
("verbose", "Increase verbosity and output additional information to stderr")
;
Expand Down Expand Up @@ -100,7 +102,14 @@ int main(int argc, char** argv) {
}

ms.verbose = vm.count("verbose") > 0;
mapper.map(ms);

if (vm.count("teleportation")) {
ms.teleportation_qubits = std::min((arch.getNqubits() - qc.getNqubits()) & ~1u, 8u);
ms.teleportation_seed = vm["teleportation"].as<unsigned long long int>();
ms.teleportation_fake = vm.count("teleportation_fake") > 0;
}

mapper.map(ms);

mapper.dumpResult(vm["out"].as<std::string>());

Expand Down
88 changes: 88 additions & 0 deletions extern/architectures/ibmq_tokyo_20qubit.arch
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
20

0 1
1 0
1 2
2 1
2 3
3 2
3 4
4 3
5 6
6 5
6 7
7 6
7 8
8 7
8 9
9 8
10 11
11 10
11 12
12 11
12 13
13 12
13 14
14 13
15 16
16 15
16 17
17 16
17 18
18 17
18 19
19 18
0 5
5 0
5 10
10 5
10 15
15 10
1 6
6 1
6 11
11 6
11 16
16 11
2 7
7 2
7 12
12 7
12 17
17 12
3 8
8 3
8 13
13 8
13 18
18 13
4 9
9 4
9 14
14 9
14 19
19 14
5 11
11 5
11 17
17 11
1 7
7 1
7 13
13 7
13 9
9 13
3 9
9 3
2 6
6 2
6 10
10 6
4 8
8 4
8 12
12 8
12 16
16 12
14 18
18 14
19 changes: 19 additions & 0 deletions extern/architectures/linear_10qubit.arch
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
10ibm_tokyo_20qubit
0 1
1 0
1 2
2 1
2 3
3 2
3 4
4 3
4 5
5 4
5 6
6 5
6 7
7 6
7 8
8 7
8 9
9 8
2 changes: 1 addition & 1 deletion extern/qfr
Submodule qfr updated from 409c73 to 77e6d3
Loading

0 comments on commit 7e60c55

Please sign in to comment.