|
1 | | -[](https://travis-ci.com/iic-jku/qcec) |
2 | | -[](https://codecov.io/gh/iic-jku/qcec) |
3 | | -[](https://opensource.org/licenses/MIT) |
4 | | -[](https://arxiv.org/abs/2004.08420) |
5 | | -[](https://arxiv.org/abs/2009.02376) |
6 | | -[](https://github.com/iic-jku/jkq) |
| 1 | +[](https://pypi.org/project/jkq.qcec/) |
| 2 | +[](https://travis-ci.com/iic-jku/qcec) |
| 3 | +[](https://codecov.io/gh/iic-jku/qcec) |
| 4 | + |
| 5 | +[](https://arxiv.org/abs/2004.08420) |
| 6 | +[](https://arxiv.org/abs/2009.02376) |
| 7 | +[](https://github.com/iic-jku/jkq) |
7 | 8 |
|
8 | 9 | # JKQ QCEC - A JKQ tool for **Q**uantum **C**ircuit **E**quivalence **C**hecking |
9 | 10 |
|
@@ -34,59 +35,93 @@ If you have any questions, feel free to contact us via [ [email protected]](mail |
34 | 35 |
|
35 | 36 | ## Usage |
36 | 37 |
|
37 | | -This tool can either be used as a **standalone executable** with command-line interface, or as a **library** for the incorporation in other projects. [Python bindings](#python-bindings) are available since version 1.4.5. |
38 | | -- The standalone executable is launched in the following way: |
39 | | - ```commandline |
40 | | - qcec_app <PATH_TO_FILE_1> <PATH_TO_FILE_2> (--method <method>) |
| 38 | +JKQ QCEC is mainly developed as a C++ library with a [commandline interface](#command-line-executable). However, using it in Python is as easy as |
| 39 | +```bash |
| 40 | +pip install jkq.qcec |
| 41 | +``` |
| 42 | +and then in Python |
| 43 | +```python |
| 44 | +from jkq import qcec |
| 45 | +qcec.verify(...) |
| 46 | +``` |
| 47 | +where the `verify` function is defined as follows: |
| 48 | +```python |
| 49 | +""" |
| 50 | +Interface to the JKQ QCEC tool for verifying quantum circuits |
| 51 | +
|
| 52 | +Params: |
| 53 | + file1 – Path to first file (required) |
| 54 | + file2 – Path to second file (required) |
| 55 | + method – Equivalence checking method to use (reference | naive | *proportional* | lookahead | simulation | compilation flow) |
| 56 | + tolerance – Numerical tolerance used during computation |
| 57 | + nsims – Number of simulations to conduct (for simulation method) |
| 58 | + fidelity – Fidelity limit for comparison (for simulation method) |
| 59 | + csv – Create CSV string for result |
| 60 | + statistics – Print statistics |
| 61 | + swapGateFusion – Optimization pass reconstructing SWAP operations |
| 62 | + singleQubitGateFusion – Optimization pass fusing consecutive single qubit gates |
| 63 | + removeDiagonalGatesBeforeMeasure – Optimization pass removing diagonal gates before measurements |
| 64 | +Returns: |
| 65 | + JSON object containing results |
| 66 | +""" |
| 67 | +def verify(file1: Union[str, bytes, PathLike], |
| 68 | + file2: Union[str, bytes, PathLike], |
| 69 | + method: Method = Method.proportional, |
| 70 | + tolerance: float = 1e-13, |
| 71 | + nsims: int = 16, |
| 72 | + fidelity: float = 0.999, |
| 73 | + csv: bool = False, |
| 74 | + statistics: bool = False, |
| 75 | + swapGateFusion: bool = False, |
| 76 | + singleQubitGateFusion: bool = False, |
| 77 | + removeDiagonalGatesBeforeMeasure: bool = False) -> object |
| 78 | +``` |
| 79 | +### Command-line Executable |
| 80 | +JKQ QCEC also provides a **standalone executable** with command-line interface called `qcec_app`. |
| 81 | +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. |
| 82 | +If the `--csv` flag is present, a CSV entry according to the following header is printed |
| 83 | +```csv |
| 84 | +filename1;nqubits1;ngates1;filename2;nqubits2;ngates2;expectedEquivalent;equivalent;method;time;maxActive;nsims |
| 85 | +``` |
| 86 | +For a full list of options, call `qcec_app --help`. |
| 87 | + |
| 88 | +### Library Organisation |
| 89 | +Internally the JKQ QCEC library works in the following way |
| 90 | +- Import both input files into a `qc::QuantumComputation` object |
| 91 | + ```c++ |
| 92 | + std::string file1 = "<PATH_TO_FILE_1>"; |
| 93 | + qc::QuantumComputation qc1(file1); |
| 94 | + |
| 95 | + std::string file2 = "<PATH_TO_FILE_2>"; |
| 96 | + qc::QuantumComputation qc2(file2); |
41 | 97 | ``` |
42 | | - where *\<method\>* is one of |
43 | | - - reference |
44 | | - - naive |
45 | | - - proportional (**default**) |
46 | | - - lookahead |
47 | | - - simulation |
48 | | - - compilationflow |
49 | | - |
50 | | - An optional parameter ```--tol e``` allows to specify the numerical tolerance *e* (default: *1e-13*) used during the computation. |
51 | | - The ```simulation``` method has two optional parameters ```--nsims r``` and ```--fid F```, controlling the maximum number of simulations *r* (default: *16*) and the considered fidelity limit *F* (default *0.999*), respectively. |
52 | | - |
53 | | - The executable performs the equivalence check and prints its result to the standard output. Per default, this produces JSON formatted output. Additional statistics (e.g., verification time, maximum number of nodes, required simulations, etc.) can be obtained by additionally providing the `--ps` flag. |
54 | | - If the `--csv` flag is present, a CSV entry according to the following header is printed |
55 | | - ```csv |
56 | | - filename1;nqubits1;ngates1;filename2;nqubits2;ngates2;expectedEquivalent;equivalent;method;time;maxActive;nsims |
57 | | - ``` |
58 | | - |
59 | | -- Internally the library works in the following way |
60 | | - - Import both input files into a `qc::QuantumComputation` object |
61 | | - ```c++ |
62 | | - std::string file1 = "<PATH_TO_FILE_1>"; |
63 | | - qc::QuantumComputation qc1(file1); |
64 | | - |
65 | | - std::string file2 = "<PATH_TO_FILE_2>"; |
66 | | - qc::QuantumComputation qc2(file2); |
67 | | - ``` |
68 | | - - Instantiate an `ec::EquivalenceChecker` object with both circuits |
69 | | - ```c++ |
70 | | - ec::Method method = ec::{ Reference | Naive | Proportional | Lookahead }; |
71 | | - auto eq = ec::ImprovedDDEquivalenceChecker(qc1, qc2, method); |
72 | | - ``` |
73 | | - or |
74 | | - ```c++ |
75 | | - auto eq = ec::PowerOfSimulationEquivalenceChecker(qc1, qc2); |
76 | | - ``` |
77 | | - or |
78 | | - ```c++ |
79 | | - auto eq = ec::CompilationFlowEquivalenceChecker(qc1, qc2); |
80 | | - ``` |
81 | | - - Perform the actual equivalence check |
82 | | - ```c++ |
83 | | - eq.check(); |
84 | | - ``` |
85 | | - - Print the results |
86 | | - ```c++ |
87 | | - eq.printResult(); |
88 | | - ``` |
89 | | - or access them through the ```eq.results``` member. |
| 98 | +- Instantiate an `ec::EquivalenceChecker` object with both circuits |
| 99 | + ```c++ |
| 100 | + ec::Method method = ec::{ Reference | Naive | Proportional | Lookahead }; |
| 101 | + auto eq = ec::ImprovedDDEquivalenceChecker(qc1, qc2, method); |
| 102 | + ``` |
| 103 | + or |
| 104 | + ```c++ |
| 105 | + auto eq = ec::PowerOfSimulationEquivalenceChecker(qc1, qc2); |
| 106 | + ``` |
| 107 | + or |
| 108 | + ```c++ |
| 109 | + auto eq = ec::CompilationFlowEquivalenceChecker(qc1, qc2); |
| 110 | + ``` |
| 111 | +- Set configuration options, e.g., |
| 112 | + ```c++ |
| 113 | + ec::Configuration config{}; |
| 114 | + config.printStatistics = true; |
| 115 | + ``` |
| 116 | +- Perform the actual equivalence check |
| 117 | + ```c++ |
| 118 | + eq.check(config); |
| 119 | + ``` |
| 120 | +- Print the results |
| 121 | + ```c++ |
| 122 | + ec.printJSONResult(config.printStatistics); |
| 123 | + ``` |
| 124 | + or access them through the ```eq.results``` member. |
90 | 125 |
|
91 | 126 | ### System requirements |
92 | 127 |
|
@@ -132,28 +167,6 @@ In order to build the library execute the following in the project's main direct |
132 | 167 | target_link_libraries(${TARGET_NAME} PRIVATE JKQ::qcec) |
133 | 168 | ``` |
134 | 169 |
|
135 | | -### Python Bindings |
136 | | -
|
137 | | -Running `pip install .` in the main project directory creates Python bindings for the JKQ QCEC tool. Then, using it in Python is as simple as: |
138 | | -```python |
139 | | -from jkq import qcec |
140 | | -qcec.verify({"file1": "<PATH_TO_FILE_1>", "file2:": "<PATH_TO_FILE_2>"}) |
141 | | -``` |
142 | | -The full list of parameters as described in [Usage](#usage) which can be passed to `qcec.verify(...)` as a Python dictionary, are: |
143 | | -```python |
144 | | -instance = { |
145 | | - "file1": "<PATH_TO_FILE_1>", # required |
146 | | - "file2": "<PATH_TO_FILE_2>", # required |
147 | | - "method": "proportional", |
148 | | - "tolerance": 1e-13, |
149 | | - "nsims": 16, |
150 | | - "fidelity": 0.999, |
151 | | - "statistics": False, |
152 | | - "csv": False, |
153 | | -} |
154 | | -``` |
155 | | - |
156 | | - |
157 | 170 | ## Reference |
158 | 171 |
|
159 | 172 | If you use our tool for your research, we will be thankful if you refer to it by citing the appropriate publication: |
|
0 commit comments