🚸 Improve native gate support for the Qiskit-to-OpenQASM3 conversion in the QDMI-Qiskit interface (#1719)

## Description

While working on iqm-finland/QDMI-on-IQM#53, I
wanted to try and plug an MQT Bench Grover circuit into the DDSIM QDMI
device, which screamed at me with an error that turned out to actually
be a Qiskit error.
Qiskit's support for exporting to OpenQASM3 is still lacking when it
comes to custom gates; it fails to provide a proper definition of
multi-controlled gates such as MCXGate.

However, I found out that one can pass a list of basis gates to the
exporter, which it subsequently treats as "builtin" operations which do
not necessitate a definition.
This lets us work around the limitations of Qiskit in the sense that the
DDSIM device claims to natively support the `mcx` gate and its OpenQASM
parser (the one here in MQT Core) natively parses this operation.
As a result, the export works without problems and simulations can be
properly conducted.

No AI was used in this pull request.

## Checklist

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

**If PR contains AI-assisted content:**

- [x] I have disclosed the use of AI tools in the PR description as per
our [AI Usage
Guidelines](https://github.com/munich-quantum-toolkit/core/blob/main/docs/ai_usage.md).
- [x] AI-assisted commits include an `Assisted-by: [Model Name] via
[Tool Name]` footer.
- [x] I confirm that I have personally reviewed and understood all
AI-generated content, and accept full responsibility for it.

---------

Signed-off-by: Lukas Burgholzer <burgholzer@me.com>

Author: burgholzer

CHANGELOG.md

@@ -21,6 +21,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- 🚸 Improve native gate support for the Qiskit-to-OpenQASM3 conversion in the QDMI-Qiskit interface ([#1719]) ([**@burgholzer**])
 - ⬆️ Require LLVM 22.1 for C++ library builds ([#1549]) ([**@burgholzer**], [**@denialhaag**])
 - 📦 Build MLIR by default for C++ library builds ([#1356]) ([**@burgholzer**], [**@denialhaag**])
 
@@ -388,6 +389,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 <!-- PR links -->
 
+[#1719]: https://github.com/munich-quantum-toolkit/core/pull/1719
 [#1709]: https://github.com/munich-quantum-toolkit/core/pull/1709
 [#1702]: https://github.com/munich-quantum-toolkit/core/pull/1702
 [#1700]: https://github.com/munich-quantum-toolkit/core/pull/1700

include/mqt-core/qasm3/StdGates.hpp

@@ -64,6 +64,9 @@ const std::map<std::string, std::shared_ptr<Gate>> STANDARD_GATES = {
     {"u1",
      std::make_shared<StandardGate>(StandardGate(
          {.nControls = 0, .nTargets = 1, .nParameters = 1, .type = qc::P}))},
+    {"cu1",
+     std::make_shared<StandardGate>(StandardGate(
+         {.nControls = 1, .nTargets = 1, .nParameters = 1, .type = qc::P}))},
     {"phase",
      std::make_shared<StandardGate>(StandardGate(
          {.nControls = 0, .nTargets = 1, .nParameters = 1, .type = qc::P}))},

python/mqt/core/plugins/qiskit/backend.py

@@ -80,6 +80,7 @@ def _build_gate_mappings_for_backend(
         "mcx": MCXGate,
         "mcphase": MCPhaseGate,
         "mcp": MCPhaseGate,
+        "mcx_gray": MCXGate,
     })
 
     qiskit_to_qdmi: dict[str, set[str]] = {}
@@ -143,6 +144,9 @@ def is_convertible(device: fomac.Device) -> bool:
         "gphase": {"global_phase"},  # OpenQASM canonical name
         "mcphase": {"mcp"},  # Qiskit canonical name
         "mcp": {"mcphase"},  # OpenQASM canonical name
+        "mcx_gray": {"mcx"},  # Alias for MCX with specific encoding
+        "mcx_vchain": {"mcx"},  # Alias for MCX with specific encoding
+        "mcx_recursive": {"mcx"},  # Alias for MCX with specific encoding
     }
 
     _QDMI_TO_QISKIT_GATE_MAP: ClassVar[dict[str, str]] = {
@@ -445,16 +449,65 @@ def _convert_circuit(
 
         # Try OpenQASM3
         if fomac.ProgramFormat.QASM3 in supported_program_formats:
+            # Qiskit's OpenQASM3 exporter is fairly limited in terms of which gates it supports natively.
+            # So it needs some help from us.
+            exclusion_list = set()
+
+            # Qiskit treats "measure", "reset", and "barrier" as keywords rather than gates
+            exclusion_list.update({"measure", "reset", "barrier"})
+
+            # We also need to remove all gates that are defined in the OpenQASM `stdlib.inc`.
+            # Qiskit's exporter will otherwise complain about duplicate definitions.
+            exclusion_list.update({
+                "p",
+                "x",
+                "y",
+                "z",
+                "h",
+                "s",
+                "sdg",
+                "t",
+                "tdg",
+                "sx",
+                "rx",
+                "ry",
+                "rz",
+                "cx",
+                "cy",
+                "cz",
+                "cp",
+                "crx",
+                "cry",
+                "crz",
+                "ch",
+                "swap",
+                "ccx",
+                "cswap",
+                "cu",
+                "CX",
+                "phase",
+                "cphase",
+                "id",
+                "u1",
+                "u2",
+                "u3",
+            })
+
+            # By excluding already defined gates, we allow the exporter to emit otherwise unsupported gates without
+            # needing to provide a definition for them. The exporter will then treat them as opaque gates, which is fine
+            # as long as the target device supports them.
+            basis_gates = [gate for gate in self.target.operation_names if gate not in exclusion_list] + ["U"]
+
             try:
-                return str(qasm3.dumps(circuit)), fomac.ProgramFormat.QASM3
+                return qasm3.dumps(circuit, basis_gates=basis_gates), fomac.ProgramFormat.QASM3
             except Exception as exc:
                 msg = f"Failed to convert circuit to QASM3: {exc}"
                 raise TranslationError(msg) from exc
 
         # Try OpenQASM2 (legacy)
         if fomac.ProgramFormat.QASM2 in supported_program_formats:
             try:
-                return str(qasm2.dumps(circuit)), fomac.ProgramFormat.QASM2
+                return qasm2.dumps(circuit), fomac.ProgramFormat.QASM2
             except Exception as exc:
                 msg = f"Failed to convert circuit to QASM2: {exc}"
                 raise TranslationError(msg) from exc

test/python/plugins/qiskit/test_backend.py

@@ -581,6 +581,23 @@ def test_backend_supports_multicontrolled_gates(ddsim_backend: QDMIBackend) -> N
     assert sum(counts.values()) == 100
 
 
+def test_backend_openqasm3_translation_works_for_native_gates(ddsim_backend: QDMIBackend) -> None:
+    """Ensures the backend can run circuits with gates that are not natively supported by OpenQASM 3.
+
+    The DDSIM backend defines support for `mcx` gates, which are not native to OpenQASM3.
+    Qiskit's OpenQASM3 exporter has problems providing proper definitions for such gates,
+    which we work around by declaring the device's basis gates in the export call.
+    This test ensures that this workaround is effective and that the backend can successfully run such circuits.
+    """
+    qc = QuantumCircuit(6)
+    qc.mcx([0, 1, 2, 3, 4], 5)
+    qc.measure_all()
+
+    job = ddsim_backend.run(qc, shots=100)
+    counts = job.result().get_counts()
+    assert sum(counts.values()) == 100
+
+
 def test_zoned_operation_rejected_at_backend_init() -> None:
     """Backend rejects devices exposing zoned operations."""
     session = fomac.Session()