✨🐍 DD Package Python bindings (#838)

## Description

This PR adds long-overdue Python bindings for the MQT Core DD Package.
As a starting point, it exposes the most important functionality and
adds corresponding documentation as well as tests.

Along the way, it fixes two small bugs in the `sample` method and the
matrix DD traversal.

## 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 related to it.
- [x] I have added appropriate tests and documentation.
- [x] I have made sure that all CI jobs on GitHub pass.
- [x] The pull request introduces no new warnings and follows the
project's style guidelines.

Author: burgholzer

docs/conf.py

@@ -85,6 +85,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "qiskit": ("https://docs.quantum.ibm.com/api/qiskit", None),
     "mqt": ("https://mqt.readthedocs.io/en/latest", None),
     "ddsim": ("https://mqt.readthedocs.io/projects/ddsim/en/latest", None),

docs/dd_package_evaluation.md

@@ -25,7 +25,7 @@ After running the target, you will see a `results_<your_argument>.json` file in
 import json
 from pathlib import Path
 
-filepath = Path("../test/python/results_baseline.json")
+filepath = Path("../test/python/dd/evaluation/results_baseline.json")
 
 with filepath.open(mode="r", encoding="utf-8") as f:
     data = json.load(f)
@@ -39,27 +39,27 @@ To compare the performance of your newly proposed changes to the existing implem
 
 ## Running the comparison
 
-There are two ways to run the comparison. Either you can use the Python module {py:mod}`mqt.core.dd.evaluation` or you can use the CLI.
+There are two ways to run the comparison. Either you can use the Python module {py:mod}`mqt.core.dd_evaluation` or you can use the CLI.
 Both ways are shown below.
 In both cases, you need to have the `evaluation` extra of `mqt-core` (i.e., `mqt.core[evaluation]`) installed.
 
 +++
 
 ### Using the Python package
 
-The Python package provides a function {py:func}`~mqt.core.dd.evaluation.compare` that can be used to compare two generate result files.
+The Python package provides a function {py:func}`~mqt.core.dd_evaluation.compare` that can be used to compare two generate result files.
 The function takes two arguments, the file path of the baseline json and the file path of the json results from your changes.
 The function will then print a detailed comparison. An exemplary run is shown below.
 
 ```{code-cell} ipython3
-from mqt.core.dd.evaluation import compare
+from mqt.core.dd_evaluation import compare
 
-baseline_path = "../test/python/results_baseline.json"
-feature_path = "../test/python/results_feature.json"
+baseline_path = "../test/python/dd/evaluation/results_baseline.json"
+feature_path = "../test/python/dd/evaluation/results_feature.json"
 compare(baseline_path, feature_path)
 ```
 
-Note that the method offers several parameters to customize the comparison. See {py:func}`mqt.core.dd.evaluation.compare`.
+Note that the method offers several parameters to customize the comparison. See {py:func}`mqt.core.dd_evaluation.compare`.
 An exemplary run adjusting the parameters is shown below.
 
 ```{code-cell} ipython3
@@ -72,13 +72,13 @@ In an even simpler fashion, the comparison can be run from the command line via
 Examples of such runs are shown below.
 
 ```{code-cell} ipython3
-! mqt-core-dd-compare ../test/python/results_baseline.json ../test/python/results_feature.json --factor=0.2 --only_changed
+! mqt-core-dd-compare ../test/python/dd/evaluation/results_baseline.json ../test/python/dd/evaluation/results_feature.json --factor=0.2 --only_changed
 ```
 
 ```{code-cell} ipython3
-! mqt-core-dd-compare ../test/python/results_baseline.json ../test/python/results_feature.json --no_split --dd --task=functionality
+! mqt-core-dd-compare ../test/python/dd/evaluation/results_baseline.json ../test/python/dd/evaluation/results_feature.json --no_split --dd --task=functionality
 ```
 
 ```{code-cell} ipython3
-! mqt-core-dd-compare ../test/python/results_baseline.json ../test/python/results_feature.json --dd --algorithm=bv --num_qubits=1024
+! mqt-core-dd-compare ../test/python/dd/evaluation/results_baseline.json ../test/python/dd/evaluation/results_feature.json --dd --algorithm=bv --num_qubits=1024
 ```

include/mqt-core/dd/Edge.hpp

@@ -308,7 +308,6 @@ template <class Node> struct Edge {
   template <typename T = Node, isMatrixVariant<T> = true>
   void printMatrix(std::size_t numQubits) const;
 
-private:
   /**
    * @brief Recursively traverse the DD and call a function for each non-zero
    * matrix entry.
@@ -331,7 +330,6 @@ template <class Node> struct Edge {
   ///---------------------------------------------------------------------------
   ///                  \n Methods for density matrix DDs \n
   ///---------------------------------------------------------------------------
-public:
   template <typename T = Node, isDensityMatrix<T> = true>
   [[maybe_unused]] static void setDensityConjugateTrue(Edge& e) {
     Node::setConjugateTempFlagTrue(e.p);

include/mqt-core/dd/Operations.hpp

@@ -257,7 +257,7 @@ template <class Config>
 qc::VectorDD
 applyClassicControlledOperation(const qc::ClassicControlledOperation& op,
                                 const qc::VectorDD& in, Package<Config>& dd,
-                                std::vector<bool>& measurements,
+                                const std::vector<bool>& measurements,
                                 const qc::Permutation& permutation = {}) {
   const auto& expectedValue = op.getExpectedValue();
   const auto& comparisonKind = op.getComparisonKind();

include/mqt-core/dd/Package.hpp

@@ -623,6 +623,22 @@ template <class Config> class Package {
     return makeTwoQubitGateDD(mat, qc::Controls{}, target0, target1);
   }
 
+  /**
+   * @brief Creates the DD for a two-qubit gate
+   * @param mat Matrix representation of the gate
+   * @param control Control qubit of the two-qubit gate
+   * @param target0 First target qubit
+   * @param target1 Second target qubit
+   * @return DD representing the gate
+   * @throws std::runtime_error if the number of qubits is larger than the
+   * package configuration
+   */
+  mEdge makeTwoQubitGateDD(const TwoQubitGateMatrix& mat,
+                           const qc::Control& control, const qc::Qubit target0,
+                           const qc::Qubit target1) {
+    return makeTwoQubitGateDD(mat, qc::Controls{control}, target0, target1);
+  }
+
   /**
   Creates the DD for a two-qubit gate
   @param mat Matrix representation of the gate

pyproject.toml

@@ -43,7 +43,7 @@ qiskit = [
 ]
 
 [project.scripts]
-mqt-core-dd-compare = "mqt.core.dd.evaluation:main"
+mqt-core-dd-compare = "mqt.core.dd_evaluation:main"
 mqt-core-cli = "mqt.core.__main__:main"
 
 [project.urls]
@@ -79,6 +79,7 @@ build.targets = [
   "mqt-core-ds",
   "mqt-core-na",
   "ir",
+  "dd",
 ]
 
 metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
@@ -213,7 +214,7 @@ isort.required-imports = ["from __future__ import annotations"]
     "I002", # Allow missing `from __future__ import annotations` import
 ]
 "src/mqt/core/_compat/**.py" = ["TID251", "A005"]
-"src/mqt/core/dd/evaluation.py" = ["T201"]
+"src/mqt/core/dd_evaluation.py" = ["T201"]
 "src/mqt/core/__main__.py" = ["T201"]
 
 [tool.ruff.lint.pydocstyle]

src/dd/Edge.cpp

@@ -484,8 +484,8 @@ void Edge<Node>::traverseMatrix(const std::complex<fp>& amp,
   const std::size_t x = i | (1ULL << nextLevel);
   const std::size_t y = j | (1ULL << nextLevel);
   if (isTerminal() || p->v < nextLevel) {
-    traverseMatrix(c, i, j, f, nextLevel, threshold);
-    traverseMatrix(c, x, y, f, nextLevel, threshold);
+    traverseMatrix(amp, i, j, f, nextLevel, threshold);
+    traverseMatrix(amp, x, y, f, nextLevel, threshold);
     return;
   }
 

src/dd/Simulation.cpp

@@ -124,22 +124,24 @@ sample(const QuantumComputation& qc, const VectorDD& in, Package<Config>& dd,
     dd.decRef(e);
 
     std::map<std::string, std::size_t> actualCounts{};
+    const auto numBits =
+        qc.getClassicalRegisters().empty() ? qc.getNqubits() : qc.getNcbits();
     for (const auto& [bitstring, count] : counts) {
-      std::string measurement(qc.getNcbits(), '0');
+      std::string measurement(numBits, '0');
       if (hasMeasurements) {
         // if the circuit contains measurements, we only want to return the
         // measured bits
         for (const auto& [qubit, bit] : measurementMap) {
           // measurement map specifies that the circuit `qubit` is measured into
           // a certain `bit`
-          measurement[qc.getNcbits() - 1U - bit] =
+          measurement[numBits - 1U - bit] =
               bitstring[bitstring.size() - 1U - qc.outputPermutation.at(qubit)];
         }
       } else {
         // otherwise, we consider the output permutation for determining where
         // to measure the qubits to
         for (const auto& [qubit, bit] : qc.outputPermutation) {
-          measurement[qc.getNcbits() - 1U - bit] =
+          measurement[numBits - 1U - bit] =
               bitstring[bitstring.size() - 1U - qubit];
         }
       }