✨♻️ Refactor QuantumComputation API and Expose to Python

[pehamTom]

Description

To make mqt-core accessible from python - in particular to make commonly used mqt-core methods and datatypes available to other mqt tools in python - this PR aims to port the core functionality to python.

This PR does not aim to provide every functionality available in the C++ library to python. This is left for future changes when the demand for such functionality arises.

In the process, some of the interfaces of the QuantumComputation class where adjusted drastically.
This constitutes a breaking change and will require consuming libraries to adapt.
However, it greatly simplifies some constructions and makes the interface way cleaner.
In particular,

• some operation names have changed to more closely map to the Qiskit names
• the order of function parameters in the QuantumComputation class was switched to be more natural and in-line with what other SDKs are providing. The same convenience functions were given more suitable names to indicate their functionality (e.g., x, cx, and mcx). Lots of boilerplate code was reduced and refactored.
• Control objects are now implicitly constructible from Qubit indices which, again, simplifies a lot of constructs
• Operations and Quantum Computations are now copyable by default. There never was a good reason for them to not be copyable and it limited us and the API in quite some ways. This makes use of the previously defined clone methods.
• The reliability of circuit printing was improved considerably.
• The new and native Qiskit import can properly handle Initial Layouts composed of multiple registers in not-necessarily alphabetical order. This should eliminate some error that people encountered in certain applications, e.g., using QCEC.

Last, but certainly not least, this PR also adds full API documentation for the exposed functionality and a Quickstart Guide to get started.

Checklist:

• The pull request only contains commits that are related to it.
• I have added appropriate tests and documentation.
• I have made sure that all CI jobs on GitHub pass.
• The pull request introduces no new warnings and follows the project's style guidelines.

[burgholzer]

@pehamTom many thanks for working on this; much appreciated help!
Just wanted to write down some thoughts:

Once the QuantumComputation class is "fully" exposed to Python, I would argue that the existing binding functionality from the .../qiskit/*.cpp files should be directly ported to Python as the C++ implementation is cumbersome (and not even that efficient I believe, due to the frequent calls from C++ to Python).
One could think about adopting a similar naming to the TKET library, which would be something like qiskit_to_mqt and mqt_to_qiskit.

To this end, I would like to introduce a certain separation of concerns between the core library and its extensions (like the adapter to Qiskit).
Someone who does not depend or rely on Qiskit should not have to install it as part of MQT Core. I believe this should be fairly easy to accomplish by adding an optional qiskit extra to the package and handling all related code in a separate submodule mqt.core.qiskit. The functions of that module are not re-exported as part of the mqt.core.__init__.py. Users have to explicitly import the submodule and/or the functions to use them.

This allows us to set a precedent for how to provide adapters from the MQT to other toolkits and should keep the code rather modular. I hope this makes sense. If you do not agree with something or something is not clear, let's discuss.

Edit: I also references two issues that are closed by this PR. The first is essentially just the binding of the QuantumComputation class. This should be a no-brainer. The second is the mqt_to_qiskit method. I believe it is fair to assume qiskit-terra>=0.23 so that you have access to the qc.layout.final_layout attribute to indicate the output permutation. If we'd like to get some more backwards compatibility we could add a flag (indicate_output_permutation_via_measurements or so) to optionally add measurements at the end of the circuit that encode the output permutation.

[github-actions]

Cpp-Linter Report ✔️

No problems need attention.

Have any feedback or feature suggestions? Share it here.

[pehamTom]

Given the size of the PR and the scope of the changes, this looks good to me. I am probably going to be the first user of this when I try to adapt QMAP so I will take care of any issues that arise in the process. If there is nothing further to discuss, I would say this is ready to merge. And thanks for all the help and refactoring!

[burgholzer]

Alright. In that case, let's go.

Thanks for this great and important contribution!