What's the problem this feature will solve?

Using QMAP to optimize Clifford subcircuits within a larger non-Clifford circuit requires manually extracting, optimizing, and re-adding the Clifford blocks. It would be nice if QMAP would do this automatically.

Describe the solution you'd like

This requires a reimplementation of Qiskits CollectCliffords transpiler pass within QMAP.

Environment information

• OS: Ubuntu 22.04
• mqt.qmap version: 2.4.0
• python version: 3.10.12
• pytest version: 7.4.2
• pdm version: 2.9.1
• vscode version: 1.82 with python extension v2023.16.0

Description

Using qmap leads to a parsing error during test discovery with pytest:

2023-09-12 15:17:52.978 [error] Error discovering pytest tests:
 [SyntaxError: 
	at JSON.parse (<anonymous>)
	at a.runTestDiscovery (~/.vscode/extensions/ms-python.python-2023.16.0/out/client/extension.js:2:825931)
	at async Promise.all (index 0)
	at async _.refreshTestData (~/.vscode/extensions/ms-python.python-2023.16.0/out/client/extension.js:2:867010)
	at async A.refreshTestDataInternal (~/.vscode/extensions/ms-python.python-2023.16.0/out/client/extension.js:2:853424)]

Running pytest manually results in a core dump:

╰─ ./.venv/bin/python -m pytest --collect-only 
[1]    1282921 illegal hardware instruction (core dumped)  ./.venv/bin/python -m pytest --collect-only

Expected behavior

pytest should not be influenced by the qmap package.

How to Reproduce

In an empty directory, run the following (also works with pip, but needs some boilerplate):

1. pdm venv create
2. pdm init (and select the freshly created environment)
3. pdm add pytest mqt-qmap
4. echo 'from mqt import qmap' >> src/example_package/__init__.py
5. echo 'from src import example_package' >> tests/test_qmap.py
6. ./.venv/bin/python -m pytest --collect-only

What's the problem this feature will solve?

Pauli gates can always be pushed to the end of the circuit when synthesizing Clifford circuits. At the moment Pauli gates are explicitely considered at every depth in the encoding which unnecessarily increases the size of the formulation and the search space.

Describe the solution you'd like

Since the Pauli gates only ever change the Phase of the stabilizer tableau, all constraints on the phase and the phase variables themselves can be dropped in the encoding. After circuit synthesis, the phases can be corrected by simulating the circuit and flipping phases with the appropriate Pauli gate.

At the moment, our mappers track the initial layout (initial logical to physical qubit mapping) and output permutation (which physical qubit has to be measured to obtain which logical qubit result) of the mapped circuits and, upon dumping the respective circuits to .qasm, emit them as comments of the form

// i 0 1 ... n
// o 0 1 ... m

This is not standardized in any way and might even change in our own toolset in the future.

At least for the output permutation a possible fix would be to add appropriate measurements to the mapped circuits. For example:

// o 1 0
OPENQASM 2.0;
include "qelib1.inc";

qreg q[2];
creg c[2];

[... circuit ...]

could become

OPENQASM 2.0;
include "qelib1.inc";

qreg q[2];
creg c[2];

[... circuit ...]
measure q[1] -> c[0];
measure q[0] -> c[1];

At the moment there does not seem to exist an apparent/standardized solution for conveying the initial layout in .qasm other than the solution available right now.

At least for the Python bindings, circumventing the .qasm dump and directly constructing a Qiskit QuantumCircuit should be possible. At the moment, Qiskit hides the initial layout in a private member _layout of QuantumCircuit.
Setting this member appropriately and adding measurements to convey the output permutation should allow to use the resulting circuits, e.g., for our verification tool QCEC.

If anyone is interested in working on this, feel free to reach out!

The teleportation functionality is flaky and fails with some initial placements.

The current documentation doesn't include any information on options regarding limiting search space in the compile method.

I suggest introducing a subsection regarding this topic in the Exact Mapper section in Mapping.rst.

What's the problem this feature will solve?

The current implementation only allows for vertical splitting of circuits. Other decomposition schemes (like horizontal decompositions) have to be done manually before calling the solver several times. It would be an interesting direction to look at improved decomposition schemes.

Describe the solution you'd like

One way to provide maximal flexibility is to be able to specify a maximal depth and a maximal number of qubits that limit the kind of decompositions that are possible. Since parallelism of decomposed circuit is traded off with depth, an even more advanced way would be to figure the "optimal" parameters out without user input. Something like an analysis of the connectivity of the unoptimized input circuit could provide key insights.

What's the problem this feature will solve?

At the moment the gate set {H, S, I, X, Y, Z, CX} is hardcoded in the Clifford synthesis algorithm. It would be hugely beneficial to make the gate set a configurable parameter.

Describe the solution you'd like

The single-qubit gates are coded into constexpr all over the code. These would have to be made dynamic. Furthermore, the functionality of the gates needs to be declared for all possible single and two-qubit gates. There are quite a few, but there is still a relatively small amount of different rules.

Instead of handling all cases via an enormous switch-statement we could have a LUT that just encodes the columns and the type of column operation for every gate. Since every gate performs a (mixture) of column XORs and swaps on 2 columns, this would probably allow for the most concise formulation.

There seems to be a bug in the custom commander and bimander encodings. The following MWE (added as an additional test case to the test_exact.cpp file) produces very unexpected results:

TEST_F(ExactTest, MWE) {
    using namespace dd::literals;

    auto circ = qc::QuantumComputation(3U);
    circ.x(2, 1_pc);
    circ.x(1, 0_pc);

    auto arch = Architecture("../../extern/architectures/ibmq_casablanca.arch");

    auto mapper = ExactMapper(circ, arch);
    auto settings = Configuration();
    settings.useSubsets = false;
    settings.encoding = Encoding::Commander; // or Encoding::Bimander
    settings.commanderGrouping = CommanderGrouping::Halves; // or CommanderGrouping::Fixed2, CommanderGrouping::Fixed3, CommanderGrouping::Logarithm
    mapper.map(settings);
    mapper.printResult(std::cout);
}

The results (running under macOS 12.3.1 using z3-4.8.17) can be summarized as follows:

As reported by CI in #89, the newest update of Z3 seems to have broken the QMAP build as both the tests as well as the Python package build fail to compile. This might need some investigation.

If anyone is up for that, feel free to submit a PR.

mqt.qmap version

mqt-qmap 2.1.2 via pip

OS

Ubuntu

Python version

No response

C++ compiler

No response

Additional environment information

No response

Description

Please find below an (incomplete) list of benchmarks where the current implementation of the exact mapping algorithm shows differences when reproducing the results of Wille et al. (IBM QX4 arch):

• 3_17_13.qasm
• 4gt11_83.qasm
• 4mod5-v0_19.qasm
• alu-v3_34.qasm

Expected behavior

I would expect the same results as mentioned in the paper.

How to Reproduce

Run listed benchmarks above with exact mapper for arch graph resembling IBM QX4 (asymmetric) connectivity and compare with results of publication.

Thank you for this work, it is very interesting and I found it quite helpful.
I had a question about changing the layering strategy in heuristic mapper. I noticed in the output, the gates are not grouped to form a layer, instead each gate is considered as its own layer. Is it possible to change the layering strategy?

I wanted to see if I could somehow change the root node of the A* algorithm, to get more than one mapping possibilities at each layer.

Any help would be greatly appreciated. Thanks in advance.

The current documentation doesn't include any information on the teleportation feature for the heuristic mapper.

I suggest introducing a subsection regarding this topic in the Heuristic Mapper section in Mapping.rst.

mqt.qmap version

mqt-qmap 2.1.1 via pip

OS

Ubuntu

Python version

No response

C++ compiler

No response

Additional environment information

No response

Description

See MEW below:

from qiskit import QuantumCircuit
from mqt import qmap

circ = QuantumCircuit(4)
circ.cx(1,0)
circ.cx(0,1)
circ.cx(2,1)
circ.cx(1,2)
circ.cx(3,2)

arch = qmap.Architecture(
    5,
    {
        (1, 0),
        (2, 0),
        (2, 1),
        (4, 2),
        (3, 2),
        (3, 4),
    },
)

qc_mapped_exact, res = qmap.compile(circ, arch, method="exact", post_mapping_optimizations=False)
qc_mapped_heu, res = qmap.compile(circ, arch, method="heuristic", post_mapping_optimizations=False)

print(f"Exact: {qc_mapped_exact.count_ops()}") # gives 12 addtional H - sub-optimal but correct
print(f"Heuristic: {qc_mapped_heu.count_ops()}") # gives 8 addtional H - correct + optimal

Expected behavior

• I would assume that the heuristic approach, in contrast to the exact approach, is not better in terms of added number of gates
• The solution of the exact mapper is not the minimal number of addtional H gates

How to Reproduce

• Run MWE above
• MWE can be computed via pen&paper

Hey there!
I am trying to implement JKQ tool in Python, mainly Google Colab and I made a Qiskit circuit and imported a coupling map (json file) in my programme. My code is:-

from jkq import qmap
from google.colab import files
uploaded = files.upload()
file_name = "coupling.json"
file1 = open(file_name, "r")
qmap.compile(circ,file1)

And now I am getting this error:-
Could not import architecture: Unable to cast Python instance to C++ type (compile in debug mode for details)
{'error': 'Could not import architecture: Unable to cast Python instance to C++ type (compile in debug mode for details)'}

Please help me solve this, thankyou!

What's the problem this feature will solve?

At the moment the heuristic synthesizer for Clifford circuits can only be called with a given given circuit. It would be nice if tableaus could also be synthesized with the heuristic.

Describe the solution you'd like

If only a tableau is given as an input to the synthesis, a non-optimal circuit should be synthesized with the AG algorithm before handing the circuit over to the heuristic optimizer.

The timeout handling for the Exact Mapper could be improved:

• currently, timeout is set to True (ExactMapper.757) whenever z3 returns does not return sat (ExactMapper.690), hence it is not possible to tell these situations apart from those in which unsat or unknown is reported (might be useful for debugging purposes).
• the timeout set in the Configuration (Configuration.hpp.53) is merely passed to Z3. For one this seems to lead to problems as even though a timeout of e.g. 5400s is set, mapping times >5400 are reported in the MappingResult.
  Furthermore, simply passing the timeout to Z3 means that it is not a timeout for the whole mapping task (as implied by the name of the field). It would be nice to separate these notions of timeout and to enable the possibility of setting a timeout after which the whole task is simply killed, e.g., by using a process or thread like mechanism.
• In relation to the previous aspect, it would be desirable to report both, times for the duration of the mapping construction and the SAT solving part instead of only the time needed by Z3 to do the solving.

What's the problem this feature will solve?

When synthesizing depth-optimal state-preparation circuits it is often the case that many redundant gates are placed on the circuit because they do not change the depth. For example the circuit IH is treated the same as ZH.

Describe the solution you'd like

The redundant gates can be removed in a post-processing step by stabilizer tableau simulation. If a gate is applied that doesn't change the tableau it should be removed.

What's the problem this feature will solve?

The current encoding for the CNOT-constraints in the Clifford synthesizer assumes all-to-all connectivity. Many quantum computing platforms only offer limited qubit connectivity.

Describe the solution you'd like

Allow passing a coupling map to the synthesizer. A class for this already exists within QMAP. The only thing that changes is the encoding loop for the two-qubit constraints.

It would be of general interest to see how a constant limited connectivity might help scalability to larger circuits as the CNOT constraints are the (asymptotically) dominant factor for the size of the encoding.

Hi, I was using the files in your examples/ directory for my own testing and I noticed that qft_10.qasm and qft_16.qasm both optimize to the identity circuit using basic rewrite rules. This may be what you intended, but I thought I'd let you know in case it's a bug.

What's the problem this feature will solve?

CI builds can be quite slow and take up a considerable amount of time.
ccache, in particular https://github.com/hendrikmuhs/ccache-action allows to set up a consistent compiler cache for your GitHub CI workflows that speeds up compilation across runs.

Describe the solution you'd like

Adopt ccache for our CI builds. Should be as simple as

- name: Setup ccache
  uses: hendrikmuhs/[email protected]
  with:
    key: '${{matrix.os}}-${{matrix.compiler}}-${{matrix.build_type}}'
    variant: ccache
    save: true
    max-size: 10G

and passing -D CMAKE_C_COMPILER_LAUNCHER=ccache -D CMAKE_CXX_COMPILER_LAUNCHER=ccache to CMake.

Some slight modification might be necessary for Windows.

Reference PR:

• cda-tum/mqt-core#323

mqt.qmap version

mqt.qmap == 2.1.2

OS

ubuntu

Python version

3.8

C++ compiler

No response

Additional environment information

No response

Description

For some benchmark algorithms, the following error happens.

qc_mapped, res = qmap.compile(qc, arch, method="exact")
File "/home/user/anaconda3/lib/python3.8/site-packages/mqt/qmap/compile.py", line 138, in compile
results = map(circ, architecture, config)
ValueError: Error during mapping: Circuit contains gates with more than one control. Please make sure that the input circuit's gates are decomposed to the appropriate gate set!

Expected behavior

No response

How to Reproduce

from mqt import qmap, bench
from qiskit.providers.fake_provider import FakeNairobi

arch = FakeNairobi()
qc = bench.get_benchmark(benchmark_name="qft", circuit_size=7, level="indep")

qc_mapped, res = qmap.compile(qc, arch, method="exact")

What's the problem this feature will solve?

At the moment the Logicblocks library serves only as an abstraction layer to Z3 without adding much benefit. Since the Logicblocks library is probably not going to be maintained anymore, I propose removing it and replacing it with something else.

Describe the solution you'd like

An intermediate layer between SMT and SAT solvers is perfectly fine, however the most important features that such a layer should provide are:

• easy export to Dimacs format
• efficient representations (Logicblocks just stores an entire syntax tree)
• active maintenance

With an export feature, we can still use Z3 but also other solvers as well without too much hassle.

mqt.qmap version

mqt.qmap==2.1.4

OS

macOS 12.6.3

Python version

No response

C++ compiler

AppleClang 14.0.0.140000

Additional environment information

No response

Description

When implementing TwoQubitMultiplicity in the heuristic mapper as an std::unordered_map instead of the current ordered std::map using the following custom hash function for the Edge keys:

struct PairHash {
  template <class T1, class T2>
  std::size_t operator()(const std::pair<T1, T2>& p) const {
    auto h1 = std::hash<T1>{}(p.first);
    auto h2 = std::hash<T2>{}(p.second);

    if constexpr (sizeof(size_t) >= 8) {
      return h1 ^ (h2 + 0x517cc1b727220a95 + (h2 << 6) + (h2 >> 2));
    }
    return h1 ^ (h2 + 0x9e3779b9 + (h2 << 6) + (h2 >> 2));
  }
};

using TwoQubitMultiplicity =
    std::unordered_map<Edge, std::pair<std::uint16_t, std::uint16_t>, PairHash>;

The test Heuristic/HeuristicTest16Q.Disjoint2qBlocks/ising_model_10 fails consistently because of a timeout in the Github CI job C++/Tests macos-latest (Ubuntu and Windows pass without too much difference in mapping time between both implementations)

Has not yet been tested with a local macOS system.

Expected behavior

Any use of TwoQubitMultiplicity in the heuristic mapper should be agnostic of the specific map implementation used (apart from negligible performance differences).

How to Reproduce

1. change the line HeuristicMapper.hpp:21 in the source from

using TwoQubitMultiplicity = std::map<Edge, std::pair<std::uint16_t, std::uint16_t>>;

to

struct PairHash {
  template <class T1, class T2>
  std::size_t operator()(const std::pair<T1, T2>& p) const {
    auto h1 = std::hash<T1>{}(p.first);
    auto h2 = std::hash<T2>{}(p.second);

    if constexpr (sizeof(size_t) >= 8) {
      return h1 ^ (h2 + 0x517cc1b727220a95 + (h2 << 6) + (h2 >> 2));
    }
    return h1 ^ (h2 + 0x9e3779b9 + (h2 << 6) + (h2 >> 2));
  }
};

using TwoQubitMultiplicity =
    std::unordered_map<Edge, std::pair<std::uint16_t, std::uint16_t>, PairHash>;

2. run the Github CI on the altered source (or probably also possible to compile using equivalent local macOS system)
3. Heuristic/HeuristicTest16Q.Disjoint2qBlocks/ising_model_10 fails with a timeout

Hi there~
I want to use JKQ QMAP in Python to map a qiskit QuantumCircuit to a real quantum device, but have some trouble with it.
I constructed a Qiskit QuantumCircuit object added some gates on it(with parameters) :

from qiskit import QuantumCircuit
circ = QuantumCircuit(n,n)
circ.append(...)

I checked my circuit and plotted it, it is valid. Then following the instruction I wrote my code :

qmap.compile(circ, 'IBM_QX5', method=qmap.Method.heuristic)

now I am getting the error :
'Could not import circuit: Unable to cast Python instance to C++ type (compile in debug mode for details)'

I don't know what is wrong. Could you please help me to solve it? Thanks a lot!

The final circuit always comes with the measurement operations at the end. Is that possible to remove or not-add the measurement?

Thanks

What's the problem this feature will solve?

Maybe not particularly interesting for a user but for developing and testing it would be great if it would be possible to set the behaviour of z3 with some configuration arguments.

This way one can quickly test a whole bunch of settings rapidly without needing to recompile.

Describe the solution you'd like

A class Z3Config could be defined globally. That class carries all solver config information with it. This can then be used by the mapper and the Clifford synthesizer.

At the moment, QMAP provides a default set of hard-coded architectures to map to. While we allow to specify own architectures (and, in theory, calibration data) in the form of individual input files this is rather inflexible and can be improved.

It should be possible to take an arbitrary Qiskit backend in Python, e.g., anything from https://github.com/Qiskit/qiskit-terra/tree/main/qiskit/test/mock/backends, and extract the corresponding information about the architecture from there.
This might even include calibration information, which is currently not used by our mappers, but might be in the future.

If you are interested in working on this, feel free to reach out!

mqt-qmap depends on qiskit-terra (>=0.20.2) https://www.wheelodex.org/projects/mqt-qmap/ which is reaching EoL: