QCEC - A JKQ tool for Quantum Circuit Equivalence Checking
Project description
QCEC - A JKQ tool for Quantum Circuit Equivalence Checking
A JKQ tool for Quantum Circuit Equivalence Checking by the Institute for Integrated Circuits at the Johannes Kepler University Linz based on methods proposed in [1], [2], [3].
[1] L. Burgholzer and R. Wille. "Advanced Equivalence Checking for Quantum Circuits". IEEE Transactions on Computer Aided Design of Integrated Circuits and Systems (TCAD), 2021 (pre-print arXiv:2004.08420)
[2] L. Burgholzer, R. Raymond, and R. Wille. "Verifying Results of the IBM Qiskit Quantum Circuit Compilation Flow". In International Conference on Quantum Computing and Engineering (QCE), 2020 (pre-print arXiv:2009.02376)
[3] L. Burgholzer, R. Kueng, and R. Wille. "Random Stimuli Generation for the Verification of Quantum Circuits". In Asia and South Pacific Design Automation Conference (ASP-DAC), 2021 (pre-print arxiv:2011.07288)
This tool can be used for checking the equivalence of two quantum circuits provided in any of the following formats:
QuantumCircuit
object from IBM's Qiskit (only through the JKQ QCEC Python bindings)OpenQASM
(e.g. used by IBM's Qiskit),Real
(e.g. from RevLib),TFC
(e.g. from Reversible Logic Synthesis Benchmarks Page)QC
(e.g. from Feynman)
with the following available methods:
- Reference - Construct and compare the DD for both circuits [1, Section III.B],
- - Starting from the identity I, either apply gates from G or (inverted) gates from G' according to one of the following strategies [1, Section IV.A]:
- Naive - Alternate between applications of G and G' [1, Section V.A],
- Proportional - Proportionally apply gates according to the gate count ratio of G and G' [1, Section V.B],
- Lookahead - Always apply the gate yielding the smaller DD [1, Section V.C],
- Simulation - Conduct simulation runs to prove non-equivalence or give a strong indication of equivalence [1, Section IV.B] using:
- Classical Stimuli - computational basis states [1, Section IV.B], [3, Section 3.1]
- Local Quantum Stimuli - each qubit value is independently chosen from any of the six basis states (|0>, |1>, |+>, |->, |L>, |R>) [3, Section 3.2]
- Global Quantum Stimuli - random stabilizer states [3, Section 3.3]
- Verification of compilation results - A dedicated scheme for verifying results of the IBM Qiskit Compilation Flow explicitly exploiting certain knowledge about the compilation process. [2]
The tool builds upon our decision diagram (DD) package as well as our quantum functionality representation (QFR). For more information, please visit iic.jku.at/eda/research/quantum_verification. If you want to visually explore decision diagrams for quantum computing, check out our installation-free web-tool JKQ DDVis.
If you have any questions, feel free to contact us via iic-quantum@jku.at or by creating an issue on GitHub.
Usage
JKQ QCEC is mainly developed as a C++ library with a commandline interface. However, using it in Python is as easy as
pip install jkq.qcec
and then in Python
from jkq import qcec
qcec.verify(...)
where the verify
function is defined as follows:
"""
Interface to the JKQ QCEC tool for verifying quantum circuits
Params:
circ1 – Qiskit QuantumCircuit object, path to circuit file or Qiskit QuantumCircuit pickle (required)
circ2 – Qiskit QuantumCircuit object, path to circuit file or Qiskit QuantumCircuit pickle (required)
method – Equivalence checking method to use (reference | naive | *proportional* | lookahead | simulation | compilationflow)
tolerance – Numerical tolerance used during computation
nsims – Number of simulations to conduct (for simulation method)
fidelity – Fidelity limit for comparison (for simulation method)
stimuliType - Type of stimuli to use (for simulation method: *classical* | localquantum | globalquantum)
csv – Create CSV string for result
statistics – Print statistics
storeCEXinput: Store counterexample input state vector (for simulation method)
storeCEXoutput: Store resulting counterexample state vectors (for simulation method)
swapGateFusion – Optimization pass reconstructing SWAP operations
singleQubitGateFusion – Optimization pass fusing consecutive single qubit gates
removeDiagonalGatesBeforeMeasure – Optimization pass removing diagonal gates before measurements
Returns:
JSON object containing results
"""
def verify(circ1, circ2,
method: Method = Method.proportional,
tolerance: float = 1e-13,
nsims: int = 16,
fidelity: float = 0.999,
stimuliType: StimuliType = StimuliType.classical,
csv: bool = False,
statistics: bool = False,
storeCEXinput: bool = False,
storeCEXoutput: bool = False,
swapGateFusion: bool = False,
singleQubitGateFusion: bool = False,
removeDiagonalGatesBeforeMeasure: bool = False) -> object
Integration of IBM Qiskit
The JKQ QCEC tool is designed to natively integrate with IBM Qiskit. In particular, using our tool to verify, e.g., the results of IBM Qiskit's quantum circuit compilation flow, is as easy as:
from jkq import qcec
from qiskit import QuantumCircuit, transpile
# create your quantum circuit
qc = <...>
# append measurements to save output mapping of physical to logical (qu)bits
qc.measure_all()
# compile circuit to appropriate backend using some optimization level
qc_comp = transpile(qc, backend=<...>, optimization_level=<0 | 1 | 2 | 3>)
# verify the compilation result
qcec.verify(qc, qc_comp, method=qcec.Method.compilationflow, statistics=True)
Command-line Executable
JKQ QCEC also provides a standalone executable with command-line interface called qcec_app
.
It provides the same options as the Python module as flags (e.g., --ps
for printing statistics, or --method <method>
for setting the method). Per default, this produces JSON formatted output.
If the --csv
flag is present, a CSV entry according to the following header is printed
filename1;nqubits1;ngates1;filename2;nqubits2;ngates2;expectedEquivalent;equivalent;method;time;maxActive;nsims
For a full list of options, call qcec_app --help
.
Library Organisation
Internally the JKQ QCEC library works in the following way
- Import both input files into a
qc::QuantumComputation
objectstd::string file1 = "<PATH_TO_FILE_1>"; qc::QuantumComputation qc1(file1); std::string file2 = "<PATH_TO_FILE_2>"; qc::QuantumComputation qc2(file2);
- Instantiate an
ec::EquivalenceChecker
object with both circuitsec::Method method = ec::{ Reference | Naive | Proportional | Lookahead }; auto eq = ec::ImprovedDDEquivalenceChecker(qc1, qc2, method);
orauto eq = ec::PowerOfSimulationEquivalenceChecker(qc1, qc2);
orauto eq = ec::CompilationFlowEquivalenceChecker(qc1, qc2);
- Set configuration options, e.g.,
ec::Configuration config{}; config.printStatistics = true;
- Perform the actual equivalence check
eq.check(config);
- Print the results
ec.printJSONResult(config.printStatistics);
or access them through theeq.results
member.
System requirements
Building (and running) is continuously tested under Linux, MacOS, and Windows using the latest available system versions for GitHub Actions. However, the implementation should be compatible with any current C++ compiler supporting C++14 and a minimum CMake version of 3.10.
Configure, Build, and Install
In order to build the library execute the following in the project's main directory
-
Configure CMake
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
Windows users using Visual Studio and the MSVC compiler may try
cmake -S . -B build -G "Visual Studio 15 2017" -A x64 -DCMAKE_BUILD_TYPE=Release
Older CMake versions not supporting the above syntax (< 3.13) may be used with
mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release
-
Build the respective target.
cmake --build ./build --config Release --target <target>
The following CMake targets are available
qcec_app
: The commandline executableqcec_sim_app
: Commandline tool dedicated for simulative verificationqcec
: The standalone libraryqcec_example
: A small commandline demo exampleqcec_test
: Unit tests using GoogleTest
-
Optional: The QCEC library and tool may be installed on the system by executing
cmake --build ./build --config Release --target install
It can then also be included in other projects using the following CMake snippet
find_package(qcec) target_link_libraries(${TARGET_NAME} PRIVATE JKQ::qcec)
Reference
If you use our tool for your research, we will be thankful if you refer to it by citing the appropriate publication:
[1] L. Burgholzer and R. Wille. "Advanced Equivalence Checking for Quantum Circuits". IEEE Trans. on CAD of Integrated Circuits and Systems (TCAD), 2021
@article{burgholzer2020advanced,
author = {Burgholzer, Lukas and Wille, Robert},
title = {Advanced Equivalence Checking for Quantum Circuits},
year = 2021,
journaltitle = {{IEEE} Trans. on {CAD} of Integrated Circuits and Systems}
}
[2] L. Burgholzer, R. Raymond, and R. Wille. "Verifying Results of the IBM Qiskit Quantum Circuit Compilation Flow". In International Conference on Quantum Computing and Engineering (QCE), 2020
@inproceedings{burgholzer2020verifyingResultsIBM,
title = {Verifying results of the {{IBM Qiskit}} quantum circuit compilation flow},
booktitle = {International Conference on Quantum Computing and Engineering},
author = {Burgholzer, Lukas and Raymond, Rudy and Wille, Robert},
year = {2020}
}
[3] L. Burgholzer, R. Kueng, and R. Wille. "Random Stimuli Generation for the Verification of Quantum Circuits". Asia and South Pacific Design Automation Conference (ASP-DAC), 2021
@inproceedings{burgholzer2021randomStimuliGenerationQuantum,
title = {Random stimuli generation for the verification of quantum circuits},
booktitle = {Asia and South Pacific Design Automation Conf.},
author = {Burgholzer, Lukas and Richard, Kueng and Wille, Robert},
year = {2021}
}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for jkq.qcec-1.7.2-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e49a9653367ef24dcda397dbd33dbd3603ae6f5d244a2a7cafe78e8f8f32fe6 |
|
MD5 | d92089ceefecfd8a6028a70b184bef6a |
|
BLAKE2b-256 | 54946f070cf493c92c009d298715cdb6592f5385bb0be081c34a1da1491b1acc |
Hashes for jkq.qcec-1.7.2-cp39-cp39-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b2bb3507ed08f8774805924b3b45bad2032dfd64f8e8821dc4d4f92a50ce3b2a |
|
MD5 | b7dc391b57e54557ff559b32a6220c39 |
|
BLAKE2b-256 | 73e342583e32ec75f0850c8117e2be642c3a60d85d8592a2578d674fc4d19f0d |
Hashes for jkq.qcec-1.7.2-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 17cef7c5ae70b27637bc508650b6571d717e0d4eb0b385ce0bfaf165a9645a1e |
|
MD5 | e0e634d1e94f036cdd252d92cbdc039a |
|
BLAKE2b-256 | fce392324321d3c49af803bf35b1b4f8d5764dd2f5bec6bd21a43a6432c92259 |
Hashes for jkq.qcec-1.7.2-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b8b8434168a05e8c065d5cc43165d0473db7bf5f47ed8c13ead2e74d9b4866e6 |
|
MD5 | aff2254832a4ecb38883d14f69bf0834 |
|
BLAKE2b-256 | 99e887423487b3025728fb34e43c3ff332cc1d1a4b6f0438ad184bdd8695086b |
Hashes for jkq.qcec-1.7.2-cp38-cp38-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9cd9b7c29c6321a0f6e7fa49f7f67dd3d03743e80c2d979143a9a77f546221c2 |
|
MD5 | 28852bba4ca07f147ffaeed572ef3564 |
|
BLAKE2b-256 | f6a54b6516cc1087d60057e9c06c882c16de9d50266a5895b7270fa84fbee6ff |
Hashes for jkq.qcec-1.7.2-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b6ab9f26343ccd70823378813fdd31ce2d31599bd5c670846da8d31c5a3d7591 |
|
MD5 | d49841c6e92a1a062878f36dc01a630e |
|
BLAKE2b-256 | c40bfe27333305457cd959c55842afc41f4a3643429a8f170c8541b18cbcdf30 |
Hashes for jkq.qcec-1.7.2-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f0d832d1ba35d4bea1ca3f701e20ee92bcf4b893788bdfe8fdc39129e65c5ad |
|
MD5 | 5a317e99c40afddd118fdbe3b96dacb8 |
|
BLAKE2b-256 | 01b30a536dc717f3246a45c4ab0acc60d364df91ad091ee696acc1c51266b40d |
Hashes for jkq.qcec-1.7.2-cp37-cp37m-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9b7ab925d64232e9ac9f7cb0f18fa5dc8ef72db3736c2e2391e8046ffebfc64a |
|
MD5 | dba88fb5f896dd35f76765648d68c909 |
|
BLAKE2b-256 | 8ab436cf3cbd0971091e0a12bea6b4ccc2a7df9091ce0bfcc0c3e7e952ca1572 |
Hashes for jkq.qcec-1.7.2-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7cde9e6a58a8e453c05b5593d1d7af2e246f9e4af43662975b03349a1b7a75e2 |
|
MD5 | a8253fc7bc4026d2d7b1f93aa8a54ec7 |
|
BLAKE2b-256 | 4ba1669908e1876ce59573310a7957b926383da8763cc89b6d484fb19d92f3c4 |
Hashes for jkq.qcec-1.7.2-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b5578b5d302fccbc874704b6a67cfce99ec4cc1b7e045d97df959ee31810c184 |
|
MD5 | 2664f782ee809e125dc8dcc2f8d26793 |
|
BLAKE2b-256 | 36f6b4d96d0c2fce0c637fb75d88bbc1596ca2860dd173b5c46ec776ccc6907f |
Hashes for jkq.qcec-1.7.2-cp36-cp36m-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 16e6699268c1598d8ef182fff9243cdbbc351c5c5babc72b1f2b2f4b8bb5de19 |
|
MD5 | 2a617b6207324ff1e02d1cbd75c9da4b |
|
BLAKE2b-256 | de70e37c8d3f6b4d7ad9c468e38780eb3df2038e1262375a494cea71d34f05aa |
Hashes for jkq.qcec-1.7.2-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 779897e401b2806c0234e328254afe707904d25ca2ebfe234b9c36161a37bc2b |
|
MD5 | f4d517c5f1f9de6b62c64b178d62e74c |
|
BLAKE2b-256 | 19761cd8da743f393966c40e1cdad579caa4c4ed1c394554c51e1eaf3fdc85e4 |