@@ -87,10 +116,11 @@ To support this endeavor, please consider:
## Getting Started
-`mqt.predictor` is available via [PyPI](https://pypi.org/project/mqt.predictor/).
+`mqt.predictor` is available via
+[PyPI](https://pypi.org/project/mqt.predictor/).
```console
-(.venv) $ pip install mqt.predictor
+uv pip install mqt.predictor
```
The following code gives an example on the usage:
@@ -116,17 +146,21 @@ print(qc_compiled.draw())
```
> [!NOTE]
-> To execute the code, respective machine learning models must be trained before.
-> Up until mqt.predictor v2.0.0, pre-trained models were provided.
-> However, this is not feasible anymore due to the increasing number of devices and figures of merits.
-> Instead, we now provide a detailed documentation on how to train and setup the MQT Predictor framework.
+> To execute the code, respective machine learning models must be trained
+> before. Up until mqt.predictor v2.0.0, pre-trained models were provided.
+> However, this is not feasible anymore due to the increasing number of devices
+> and figures of merits. Instead, we now provide a detailed documentation on how
+> to train and setup the MQT Predictor framework.
-**Detailed documentation and examples are available at [ReadTheDocs](https://mqt.readthedocs.io/projects/predictor).**
+**Detailed documentation and examples are available at
+[ReadTheDocs](https://mqt.readthedocs.io/projects/predictor).**
## System Requirements
-MQT Predictor can be installed on all major operating systems with all supported Python versions.
-Building (and running) is continuously tested under Linux, macOS, and Windows using the [latest available system versions for GitHub Actions](https://github.com/actions/runner-images).
+MQT Predictor can be installed on all major operating systems with all supported
+Python versions. Building (and running) is continuously tested under Linux,
+macOS, and Windows using the
+[latest available system versions for GitHub Actions](https://github.com/actions/runner-images).
## Cite This
@@ -134,7 +168,8 @@ Please cite the work that best fits your use case.
### MQT Predictor (the tool)
-When citing the software itself or results produced with it, cite the MQT Predictor paper:
+When citing the software itself or results produced with it, cite the MQT
+Predictor paper:
```bibtex
@article{quetschlich2025mqtpredictor,
@@ -170,7 +205,12 @@ When discussing the overall MQT project or its ecosystem, cite the MQT Handbook:
## Acknowledgements
-The Munich Quantum Toolkit has been supported by the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation program (grant agreement No. 101001318), the Bavarian State Ministry for Science and Arts through the Distinguished Professorship Program, as well as the Munich Quantum Valley, which is supported by the Bavarian state government with funds from the Hightech Agenda Bayern Plus.
+The Munich Quantum Toolkit has been supported by the European Research Council
+(ERC) under the European Union's Horizon 2020 research and innovation program
+(grant agreement No. 101001318), the Bavarian State Ministry for Science and
+Arts through the Distinguished Professorship Program, as well as the Munich
+Quantum Valley, which is supported by the Bavarian state government with funds
+from the Hightech Agenda Bayern Plus.
diff --git a/UPGRADING.md b/UPGRADING.md
index 0706bcc8b..889e00a21 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,30 +1,38 @@
# Upgrade Guide
-This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md).
+This document describes breaking changes and how to upgrade. For a complete list
+of changes including minor and patch releases, please refer to the
+[changelog](CHANGELOG.md).
## [Unreleased]
### End of support for x86 macOS systems
Starting with this release, MQT Predictor no longer supports x86 macOS systems.
-This step is necessary to ensure compatibility with PyTorch.
-x86 macOS systems are no longer tested in our CI.
+This step is necessary to ensure compatibility with PyTorch. x86 macOS systems
+are no longer tested in our CI.
-## [2.3.0] - 2025-07-29
+## [2.3.0]
-In this release, we have migrated to using Qiskit's `Target` class to represent quantum devices.
-This change allows for better compatibility with the latest MQT Bench version and improves the overall usability of the library.
-Beyond that, we also support Qiskit v2 now.
+In this release, we have migrated to using Qiskit's `Target` class to represent
+quantum devices. This change allows for better compatibility with the latest MQT
+Bench version and improves the overall usability of the library. Beyond that, we
+also support Qiskit v2 now.
-Furthermore, both the ML and RL parts of MQT Predictor have been refactored to enhance their functionality and usability:
-The ML setup has been simplified and streamlined, making it easier to use and integrate into your workflows.
-The RL action handling has been updated to utilize dataclasses, which improves the structure and clarity of the code, making it easier to understand and maintain.
+Furthermore, both the ML and RL parts of MQT Predictor have been refactored to
+enhance their functionality and usability: The ML setup has been simplified and
+streamlined, making it easier to use and integrate into your workflows. The RL
+action handling has been updated to utilize dataclasses, which improves the
+structure and clarity of the code, making it easier to understand and maintain.
### General
-MQT Predictor has moved to the [munich-quantum-toolkit](https://github.com/munich-quantum-toolkit) GitHub organization under https://github.com/munich-quantum-toolkit/predictor.
-While most links should be automatically redirected, please update any links in your code to point to the new location.
-All links in the documentation have been updated accordingly.
+MQT Predictor has moved to the
+[munich-quantum-toolkit](https://github.com/munich-quantum-toolkit) GitHub
+organization under . While
+most links should be automatically redirected, please update any links in your
+code to point to the new location. All links in the documentation have been
+updated accordingly.
diff --git a/docs/compilation.md b/docs/compilation.md
index 1f418e6d7..be676b8f0 100644
--- a/docs/compilation.md
+++ b/docs/compilation.md
@@ -1,18 +1,40 @@
# Device-specific Compilation
-Once a target device has been selected, the quantum circuit — typically designed in a device-agnostic fashion that does not account for hardware limitations (such as a limited gate set or limited connectivity) — must be compiled so that it actually becomes executable on that device.
-
-Compilation itself is a sequential process consisting of a series of compilation passes that step-by-step transform the original quantum circuit until it conforms to the limitations imposed by the target device. Since many of the underlying problems in compilation are computationally hard, an ever-growing variety of compilation passes is available across several quantum SDKs and software tools—each with their own advantages and disadvantages.
-
-As a result of the sheer number of options, choosing the best sequence of compilation passes for a given application is nearly impossible. Consequently, most quantum SDKs (such as Qiskit and TKET) provide easy-to-use high-level function calls that encapsulate _their_ sequence of compilation passes into a single compilation flow. While this allows convenient circuit compilation, it has several drawbacks:
-
-- It creates a kind of vendor lock that limits the available compilation passes to those provided by the SDK offering the compilation flow.
-- The respective compilation flows are designed to be broadly applicable and are neither device-specific nor circuit-specific.
+Once a target device has been selected, the quantum circuit — typically designed
+in a device-agnostic fashion that does not account for hardware limitations
+(such as a limited gate set or limited connectivity) — must be compiled so that
+it actually becomes executable on that device.
+
+Compilation itself is a sequential process consisting of a series of compilation
+passes that step-by-step transform the original quantum circuit until it
+conforms to the limitations imposed by the target device. Since many of the
+underlying problems in compilation are computationally hard, an ever-growing
+variety of compilation passes is available across several quantum SDKs and
+software tools—each with their own advantages and disadvantages.
+
+As a result of the sheer number of options, choosing the best sequence of
+compilation passes for a given application is nearly impossible. Consequently,
+most quantum SDKs (such as Qiskit and TKET) provide easy-to-use high-level
+function calls that encapsulate _their_ sequence of compilation passes into a
+single compilation flow. While this allows convenient circuit compilation, it
+has several drawbacks:
+
+- It creates a kind of vendor lock that limits the available compilation passes
+ to those provided by the SDK offering the compilation flow.
+- The respective compilation flows are designed to be broadly applicable and are
+ neither device-specific nor circuit-specific.
- No means are provided to optimize for a customizable figure of merit.
-To overcome these limitations, the MQT Predictor framework provides **device-specific quantum circuit compilers** by combining compilation passes from various compiler tools and learning optimized sequences of those passes with respect to a customizable figure of merit. This mix-and-match approach eliminates vendor lock-in and enables optimized compilers that transcend the capabilities of individual tools.
+To overcome these limitations, the MQT Predictor framework provides
+**device-specific quantum circuit compilers** by combining compilation passes
+from various compiler tools and learning optimized sequences of those passes
+with respect to a customizable figure of merit. This mix-and-match approach
+eliminates vendor lock-in and enables optimized compilers that transcend the
+capabilities of individual tools.
-The compilation process is modeled as a **Markov Decision Process** and takes three inputs to train a reinforcement learning (RL) model that acts as a compiler:
+The compilation process is modeled as a **Markov Decision Process** and takes
+three inputs to train a reinforcement learning (RL) model that acts as a
+compiler:
1. Training circuits
2. The targeted quantum device
@@ -20,4 +42,5 @@ The compilation process is modeled as a **Markov Decision Process** and takes th
-The trained model can then be used to compile any quantum circuit for the targeted device.
+The trained model can then be used to compile any quantum circuit for the
+targeted device.
diff --git a/docs/conf.py b/docs/conf.py
index ca7fb441e..e18259e96 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -145,6 +145,7 @@ def format_url(self, _e: Entry) -> HRef:
napoleon_numpy_docstring = False
# -- Options for HTML output -------------------------------------------------
+
html_theme = "furo"
html_static_path = ["_static"]
html_theme_options = {
diff --git a/docs/contributing.md b/docs/contributing.md
index 9e305d3eb..9b4e422e1 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -73,9 +73,9 @@ Contributions that do not comply with these guidelines or violate our
- Focus on a single feature or bug at a time and only touch relevant files.
Split multiple features into separate contributions.
- Add tests for new features to ensure they work as intended.
-- Document new features.
- For user-facing changes, add a changelog entry; for breaking changes, update the
- upgrade guide. For details, see {ref}`maintaining-changelog-upgrade-guide`.
+- Document new features. For user-facing changes, add a changelog entry; for
+ breaking changes, update the upgrade guide. For details, see
+ {ref}`maintaining-changelog-upgrade-guide`.
- Add tests for bug fixes to demonstrate the fix.
- Document your code thoroughly and ensure it is readable.
- Keep your code clean by removing debug statements, leftover comments, and
@@ -206,9 +206,9 @@ These are explained in more detail in the following sections.
## Running the Tests
The Python code is tested by unit tests using the
-[{code}`pytest`](https://docs.pytest.org/en/latest/) framework.
-The corresponding test files can be found in the {code}`tests` directory.
-A {code}`nox` session is provided to conveniently run the Python tests.
+[{code}`pytest`](https://docs.pytest.org/en/latest/) framework. The
+corresponding test files can be found in the {code}`tests` directory. A
+{code}`nox` session is provided to conveniently run the Python tests.
```console
nox -s tests
@@ -426,16 +426,14 @@ prepares the release. This PR should:
reference to it in the changelog.
Before merging the PR preparing the release, check the GitHub release draft
-generated by the Release Drafter for unlabelled PRs.
-Unlabelled PRs would appear at the top of the release draft below the main
-heading.
-If you missed updating labels before merging, you can still update them and
-re-run the Release Drafter afterward.
-Furthermore, check whether the version number in the release draft is correct.
-The version number in the release draft is dictated by the presence of certain
-labels on the PRs involved in a release. By default, a patch release will be
-created. If any PR has the {code}`minor` or {code}`major` label, a minor or
-major release will be created, respectively.
+generated by the Release Drafter for unlabelled PRs. Unlabelled PRs would appear
+at the top of the release draft below the main heading. If you missed updating
+labels before merging, you can still update them and re-run the Release Drafter
+afterward. Furthermore, check whether the version number in the release draft is
+correct. The version number in the release draft is dictated by the presence of
+certain labels on the PRs involved in a release. By default, a patch release
+will be created. If any PR has the {code}`minor` or {code}`major` label, a minor
+or major release will be created, respectively.
:::{note}
diff --git a/docs/device_selection.md b/docs/device_selection.md
index f08556bb8..461d54ee9 100644
--- a/docs/device_selection.md
+++ b/docs/device_selection.md
@@ -13,18 +13,30 @@ mystnb:
# Automatic Device Selection
-To realize any quantum application, a suitable quantum device must be selected for the execution of the developed quantum algorithm.
-This alone is non-trivial since new quantum devices based on various underlying technologies emerge on an almost daily basis—each with their own advantages and disadvantages.
-There are hardly any practical guidelines on which device to choose based on the targeted application.
-As such, the best guess in many cases today is to simply try out many (if not all) possible devices and, afterwards, choose the best results—certainly a time- and resource-consuming endeavor that is not sustainable for the future.
+To realize any quantum application, a suitable quantum device must be selected
+for the execution of the developed quantum algorithm. This alone is non-trivial
+since new quantum devices based on various underlying technologies emerge on an
+almost daily basis—each with their own advantages and disadvantages. There are
+hardly any practical guidelines on which device to choose based on the targeted
+application. As such, the best guess in many cases today is to simply try out
+many (if not all) possible devices and, afterwards, choose the best
+results—certainly a time- and resource-consuming endeavor that is not
+sustainable for the future.
-A naive approach to select the best quantum device for a given quantum circuit would be to compile it for all devices, e.g., using the trained RL models which act as specialized compilers for supported quantum devices.
-Afterwards, the resulting compiled circuits must be evaluated according to some figure of merit to identify the most promising device.
-However, doing this for each and every to-be-compiled quantum circuit is practically infeasible since compilation is a time-consuming task.
+A naive approach to select the best quantum device for a given quantum circuit
+would be to compile it for all devices, e.g., using the trained RL models which
+act as specialized compilers for supported quantum devices. Afterwards, the
+resulting compiled circuits must be evaluated according to some figure of merit
+to identify the most promising device. However, doing this for each and every
+to-be-compiled quantum circuit is practically infeasible since compilation is a
+time-consuming task.
-The MQT Predictor framework provides an easy-to-use solution to this problem by using supervised machine learning.
-It learns from previous compilations of other quantum circuits and models the problem of determining the most promising device for a circuit and figure of merit as a statistical classification task — a task well suited for supervised machine learning.
-For that, the framework is trained with based on three inputs:
+The MQT Predictor framework provides an easy-to-use solution to this problem by
+using supervised machine learning. It learns from previous compilations of other
+quantum circuits and models the problem of determining the most promising device
+for a circuit and figure of merit as a statistical classification task — a task
+well suited for supervised machine learning. For that, the framework is trained
+with based on three inputs:
1. Training circuits
2. The compilation options for all supported devices
@@ -32,15 +44,17 @@ For that, the framework is trained with based on three inputs:
-The trained model then acts as a predictor and can be used to predict the most suitable device for a given quantum circuit and figure of merit.
+The trained model then acts as a predictor and can be used to predict the most
+suitable device for a given quantum circuit and figure of merit.
## Supported Quantum Devices
-Any device provided as a Qiskit `Target` object can be used with the MQT Predictor framework.
-MQT Bench provides a set of devices that can be used out-of-the-box which are available under
+Any device provided as a Qiskit `Target` object can be used with the MQT
+Predictor framework. MQT Bench provides a set of devices that can be used
+out-of-the-box which are available under
[MQT Bench Devices and Parameters](https://mqt.readthedocs.io/projects/bench/en/latest/parameter.html).
-Currently, the following devices are supported:
-So far, MQT Bench supports the following devices:
+Currently, the following devices are supported: So far, MQT Bench supports the
+following devices:
```{code-cell} ipython3
:tags: [hide-input]
@@ -50,4 +64,5 @@ for num, device_name in enumerate(get_available_device_names()):
print(f"{num+1}: {device_name} with {get_device(device_name).num_qubits} qubits")
```
-Adding further devices is straightforward and requires only to provide its native gate-set, connectivity, and calibration data.
+Adding further devices is straightforward and requires only to provide its
+native gate-set, connectivity, and calibration data.
diff --git a/docs/figure_of_merit.md b/docs/figure_of_merit.md
index 72faaedc9..d21ce6117 100644
--- a/docs/figure_of_merit.md
+++ b/docs/figure_of_merit.md
@@ -13,57 +13,84 @@ mystnb:
# Figure of Merit
-The figure of merit determines the optimization criteria for both the ML and RL model and, thus, is a crucial part of the MQT Predictor framework.
-In general, it can be completely customizable and consider anything from (compiled) circuit characteristics such as gate counts to actual execution costs by a specific vendor.
-Nevertheless, a comprehensive figure of merit should consider at least the characteristics of the compiled quantum circuit and the characteristics of the selected quantum device.
-Therefore, the respective hardware information needs to be collected, such as, e.g., gate/readout fidelities, gate execution times, or decoherence times.
-While for some devices, this information may be publicly available, for other devices it may be estimated from comparable devices, previous records, or insider knowledge.
-
-So far, two figures of merit are implemented for all devices: `expected_fidelity` and `critical_depth`.
-On top of that, the `estimated_success_probability` is available for devices where the necessary calibration data is available, as well as the `estimated_hellinger_distance` when a suitable (trained) model is provided.
+The figure of merit determines the optimization criteria for both the ML and RL
+model and, thus, is a crucial part of the MQT Predictor framework. In general,
+it can be completely customizable and consider anything from (compiled) circuit
+characteristics such as gate counts to actual execution costs by a specific
+vendor. Nevertheless, a comprehensive figure of merit should consider at least
+the characteristics of the compiled quantum circuit and the characteristics of
+the selected quantum device. Therefore, the respective hardware information
+needs to be collected, such as, e.g., gate/readout fidelities, gate execution
+times, or decoherence times. While for some devices, this information may be
+publicly available, for other devices it may be estimated from comparable
+devices, previous records, or insider knowledge.
+
+So far, two figures of merit are implemented for all devices:
+`expected_fidelity` and `critical_depth`. On top of that, the
+`estimated_success_probability` is available for devices where the necessary
+calibration data is available, as well as the `estimated_hellinger_distance`
+when a suitable (trained) model is provided.
## Expected Fidelity
Consider the figure of merit that takes into account the following two aspects:
-- If the selected device is not large enough to execute a given quantum circuit with respect to its number of qubits, the worst-possible score is assigned.
-- If the device is large enough, the evaluation score is calculated using the formula:
+- If the selected device is not large enough to execute a given quantum circuit
+ with respect to its number of qubits, the worst-possible score is assigned.
+- If the device is large enough, the evaluation score is calculated using the
+ formula:
-$
+```{math}
\mathit{\mathcal{F}} = \prod_{i=1}^{|G|} \mathit{\mathcal{F}}(g_i) \prod_{j=1}^{m} \mathit{\mathcal{F}_{RO}}(q_j)
-$
+```
-with
-$\mathit{\mathcal{F}}(g_i)$ being the expected execution fidelity of gate $g_i$ on its corresponding qubit(s),
-$\mathit{\mathcal{F}_{RO}}(q_j)$ being the expected execution fidelity of a measurement operation $q_j$ on its corresponding qubit, and
-$|G|$ respectively $m$ being the number of gates and measurements in the compiled circuit.
+with $\mathit{\mathcal{F}}(g_i)$ being the expected execution fidelity of gate
+$g_i$ on its corresponding qubit(s), $\mathit{\mathcal{F}_{RO}}(q_j)$ being the
+expected execution fidelity of a measurement operation $q_j$ on its
+corresponding qubit, and $|G|$ respectively $m$ being the number of gates and
+measurements in the compiled circuit.
-This figure of merit determines an estimate of the probability that a quantum circuit will return the expected result, the so-called `expected fidelity`, which ranges between $0.0$ and $1.0$ with higher values being better.
+This figure of merit determines an estimate of the probability that a quantum
+circuit will return the expected result, the so-called `expected fidelity`,
+which ranges between $0.0$ and $1.0$ with higher values being better.
## Critical Depth
-A potential alternative could be the `critical depth` (taken from {cite:labelpar}`tomesh2022supermarq`) — a measure to describe the percentage of multi-qubit gates on the longest path through a compiled quantum circuit (determining the depth).
-A respective value close to 1 would indicate a very sequential circuit while a value of 0 would indicate a highly parallel one.
+A potential alternative could be the `critical depth` (taken from
+{cite:labelpar}`tomesh2022supermarq`) — a measure to describe the percentage of
+multi-qubit gates on the longest path through a compiled quantum circuit
+(determining the depth). A respective value close to 1 would indicate a very
+sequential circuit while a value of 0 would indicate a highly parallel one.
## Estimated Success Probability
-The `estimated_success_probability` (based on {cite:labelpar}`esp-lifetime-min`, {cite:labelpar}`esp-lifetime`, and {cite:labelpar}`esp-idle`) is a figure of merit that is based on the `expected_fidelity` but also multiplies it with a factor that considers the decoherence times $T_1, T_2$ of a device:
+The `estimated_success_probability` (based on {cite:labelpar}`esp-lifetime-min`,
+{cite:labelpar}`esp-lifetime`, and {cite:labelpar}`esp-idle`) is a figure of
+merit that is based on the `expected_fidelity` but also multiplies it with a
+factor that considers the decoherence times $T_1, T_2$ of a device:
-$
+```{math}
\prod_{q} \exp{-(t_{q}^{\mathrm{idle}}/\min{(T_1, T_2)})}
-$
+```
with $t_{q}^{\mathrm{idle}}$ being the sum of each qubit's idle times.
-Therefore, exactly the execution times of all gates and the decoherence times must be available.
-Note that some variants of this figure of merit do not take the minimum of both decoherence times but create one exponential factor for each decoherence time, others consider the entire qubit lifetime instead of idle times only.
+Therefore, exactly the execution times of all gates and the decoherence times
+must be available. Note that some variants of this figure of merit do not take
+the minimum of both decoherence times but create one exponential factor for each
+decoherence time, others consider the entire qubit lifetime instead of idle
+times only.
## Estimated Hellinger Distance
-The `estimated_hellinger_distance` is a figure of merit based on a machine learning (ML) model that has been trained on a dataset of quantum circuits labeled with their respective Hellinger distance.
+The `estimated_hellinger_distance` is a figure of merit based on a machine
+learning (ML) model that has been trained on a dataset of quantum circuits
+labeled with their respective Hellinger distance.
To use this figure of merit, three steps are required:
-1. **Feature Extraction:** Prepare a set of compiled quantum circuits (e.g., from `MQT Bench`) for execution on a target device and extract corresponding feature vectors.
+1. **Feature Extraction:** Prepare a set of compiled quantum circuits (e.g.,
+ from `MQT Bench`) for execution on a target device and extract corresponding
+ feature vectors.
```{code-cell} ipython3
from mqt.predictor.hellinger import calc_device_specific_features
@@ -74,7 +101,9 @@ for qc in quantum_circuits:
feature_vector_list.append(feature_vector)
```
-2. **Label Generation:** Compute the Hellinger distance between the noisy probability distribution (obtained from executing on a quantum device) and the noiseless distribution (from simulation, e.g., using `MQT DDSIM`).
+2. **Label Generation:** Compute the Hellinger distance between the noisy
+ probability distribution (obtained from executing on a quantum device) and
+ the noiseless distribution (from simulation, e.g., using `MQT DDSIM`).
```{code-cell} ipython3
from mqt.predictor.hellinger import hellinger_distance
@@ -88,7 +117,8 @@ for noisy, noiseless in zip(noisy_distributions, noiseless_distributions):
training_data = TrainingData(X_train=feature_vector_list, y_train=labels_list)
```
-3. **Model Training:** Train an ML model using the compiled quantum circuit features and the Hellinger distance labels.
+3. **Model Training:** Train an ML model using the compiled quantum circuit
+ features and the Hellinger distance labels.
```{code-cell} ipython3
from mqt.predictor.ml import Predictor
@@ -99,7 +129,10 @@ pred = Predictor(
pred.train_random_forest_model(training_data)
```
-Once the model has been successfully trained, the `estimated_hellinger_distance` figure of merit can serve as a device-specific figure of merit to assess the quality of a compiled quantum circuit (i.e., calculate a Hellinger distance value $\in [0, 1]$):
+Once the model has been successfully trained, the `estimated_hellinger_distance`
+figure of merit can serve as a device-specific figure of merit to assess the
+quality of a compiled quantum circuit (i.e., calculate a Hellinger distance
+value $\in [0, 1]$):
```{code-cell} ipython3
from mqt.predictor.reward import estimated_hellinger_distance
@@ -107,4 +140,6 @@ from mqt.predictor.reward import estimated_hellinger_distance
print(estimated_hellinger_distance(quantum_circuits[0], device, trained_model))
```
-In the context of the MQT Predictor, it can be used as a reward function in the RL module and subsequently utilized in the ML module to score and compare quantum devices—just like any other figure of merit mentioned above.
+In the context of the MQT Predictor, it can be used as a reward function in the
+RL module and subsequently utilized in the ML module to score and compare
+quantum devices—just like any other figure of merit mentioned above.
diff --git a/docs/index.md b/docs/index.md
index bcffde184..f339aae33 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,25 +1,36 @@
-# Welcome to MQT Predictor's documentation!
+# Welcome to MQT Predictor's documentation
-MQT Predictor is a tool for automatic device selection with device-specific circuit compilation for quantum computing.
-It is part of the _{doc}`Munich Quantum Toolkit (MQT) `_.
+MQT Predictor is a tool for automatic device selection with device-specific
+circuit compilation for quantum computing. It is part of the
+_{doc}`Munich Quantum Toolkit (MQT) `_.
From a user's perspective, the framework works as follows:
-Any uncompiled quantum circuit can be provided together with the desired figure of merit.
-The framework then automatically predicts the most suitable device for the given circuit and figure of merit and compiles the circuit for the predicted device.
-The compiled circuit is returned together with the compilation information and the selected device.
+Any uncompiled quantum circuit can be provided together with the desired figure
+of merit. The framework then automatically predicts the most suitable device for
+the given circuit and figure of merit and compiles the circuit for the predicted
+device. The compiled circuit is returned together with the compilation
+information and the selected device.
The MQT Predictor framework is based on two main components:
-- An {doc}`Automatic Device Selection ` component that predicts the most suitable device for a given quantum circuit and figure of merit.
-- A {doc}`Device-Specific Circuit Compilation ` component that compiles a given quantum circuit for a given device.
+- An {doc}`Automatic Device Selection ` component that
+ predicts the most suitable device for a given quantum circuit and figure of
+ merit.
+- A {doc}`Device-Specific Circuit Compilation ` component that
+ compiles a given quantum circuit for a given device.
-Combining these two components, the framework can be used to automatically compile a given quantum circuit for the most suitable device optimizing a {doc}`customizable figure of merit `.
-How to install the framework is described in the {doc}`installation section `, how to set it up in the {doc}`setup section ` section, and how to use it in the {doc}`quickstart section ` section.
+Combining these two components, the framework can be used to automatically
+compile a given quantum circuit for the most suitable device optimizing a
+{doc}`customizable figure of merit `. How to install the
+framework is described in the {doc}`installation section `, how to
+set it up in the {doc}`setup section ` section, and how to use it in the
+{doc}`quickstart section ` section.
-If you are interested in the theory behind MQT Predictor, have a look at the publications in the {doc}`references list `.
+If you are interested in the theory behind MQT Predictor, have a look at the
+publications in the {doc}`references list `.
---
@@ -57,11 +68,15 @@ tooling
support
```
-```{only} html
## Contributors and Supporters
-The _[Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io)_ is developed by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/) and supported by [MQSC](https://mq.sc).
-Among others, it is part of the [Munich Quantum Software Stack (MQSS)](https://www.munich-quantum-valley.de/research/research-areas/mqss) ecosystem, which is being developed as part of the [Munich Quantum Valley (MQV)](https://www.munich-quantum-valley.de) initiative.
+The _[Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io)_ is developed by
+the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the
+[Technical University of Munich](https://www.tum.de/) and supported by
+[MQSC](https://mq.sc). Among others, it is part of the
+[Munich Quantum Software Stack (MQSS)](https://www.munich-quantum-valley.de/research/research-areas/mqss)
+ecosystem, which is being developed as part of the
+[Munich Quantum Valley (MQV)](https://www.munich-quantum-valley.de) initiative.
@@ -80,18 +95,21 @@ Thank you to all the contributors who have helped make MQT Predictor a reality!
-The MQT will remain free, open-source, and permissively licensed—now and in the future.
-We are firmly committed to keeping it open and actively maintained for the quantum computing community.
+The MQT will remain free, open-source, and permissively licensed—now and in the
+future. We are firmly committed to keeping it open and actively maintained for
+the quantum computing community.
To support this endeavor, please consider:
-- Starring and sharing our repositories: [https://github.com/munich-quantum-toolkit](https://github.com/munich-quantum-toolkit)
-- Contributing code, documentation, tests, or examples via issues and pull requests
+- Starring and sharing our repositories:
+ [https://github.com/munich-quantum-toolkit](https://github.com/munich-quantum-toolkit)
+- Contributing code, documentation, tests, or examples via issues and pull
+ requests
- Citing the MQT in your publications (see {doc}`References
`)
- Using the MQT in research and teaching, and sharing feedback and use cases
-- Sponsoring us on GitHub: [https://github.com/sponsors/munich-quantum-toolkit](https://github.com/sponsors/munich-quantum-toolkit)
+- Sponsoring us on GitHub:
+ [https://github.com/sponsors/munich-quantum-toolkit](https://github.com/sponsors/munich-quantum-toolkit)
-```
diff --git a/docs/references.md b/docs/references.md
index e16a822fd..c1fcb43fd 100644
--- a/docs/references.md
+++ b/docs/references.md
@@ -1,9 +1,10 @@
# References
-_MQT Predictor_ has a strong foundation in peer‑reviewed research.
-Many of its built‑in algorithms are based on methods published in scientific journals and conferences.
-For an overview of _MQT Predictor_ and its features, see {cite:p}`quetschlich2023mqtbench`.
-If you want to cite this article, please use the following BibTeX entry:
+_MQT Predictor_ has a strong foundation in peer‑reviewed research. Many of its
+built‑in algorithms are based on methods published in scientific journals and
+conferences. For an overview of _MQT Predictor_ and its features, see
+{cite:p}`quetschlich2023mqtbench`. If you want to cite this article, please use
+the following BibTeX entry:
```bibtex
@article{quetschlich2025mqtpredictor,
@@ -17,8 +18,9 @@ If you want to cite this article, please use the following BibTeX entry:
}
```
-_MQT Predictor_ is part of the Munich Quantum Toolkit, which is described in {cite:p}`mqt`.
-If you want to cite the Munich Quantum Toolkit, please use the following BibTeX entry:
+_MQT Predictor_ is part of the Munich Quantum Toolkit, which is described in
+{cite:p}`mqt`. If you want to cite the Munich Quantum Toolkit, please use the
+following BibTeX entry:
```bibtex
@inproceedings{mqt,
@@ -34,7 +36,8 @@ If you want to cite the Munich Quantum Toolkit, please use the following BibTeX
}
```
-If you are explicitly referring to the application-aware compilation scheme, please cite {cite:p}`quetschlich2024application_compilation`.
+If you are explicitly referring to the application-aware compilation scheme,
+please cite {cite:p}`quetschlich2024application_compilation`.
A full list of references is given below.
diff --git a/docs/setup.md b/docs/setup.md
index 5a70bd659..1582cbb5e 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -13,11 +13,14 @@ mystnb:
# Framework Setup
-To use the MQT Predictor framework, you must first configure the devices and train the reinforcement learning and supervised machine learning models. This section outlines how to do that.
+To use the MQT Predictor framework, you must first configure the devices and
+train the reinforcement learning and supervised machine learning models. This
+section outlines how to do that.
## Step 1: Add Devices
-All devices supported by [MQT Bench](https://github.com/cda-tum/mqt-bench) are natively supported. Currently, the following devices are available:
+All devices supported by [MQT Bench](https://github.com/cda-tum/mqt-bench) are
+natively supported. Currently, the following devices are available:
```{code-cell} ipython3
:tags: [hide-input]
@@ -27,11 +30,14 @@ for num, device_name in enumerate(get_available_device_names()):
print(f"{num+1}: {device_name} with {get_device(device_name).num_qubits} qubits")
```
-Custom devices are also supported as long as they are defined as Qiskit `Target` objects.
+Custom devices are also supported as long as they are defined as Qiskit `Target`
+objects.
## Step 2: Train Reinforcement Learning Models
-For each device to be considered, a dedicated reinforcement learning (RL) model must be trained. This is based on a figure of merit and a set of training circuits in QASM format.
+For each device to be considered, a dedicated reinforcement learning (RL) model
+must be trained. This is based on a figure of merit and a set of training
+circuits in QASM format.
```python
from mqt.predictor.rl import Predictor as RL_Predictor
@@ -52,7 +58,8 @@ print(figure_of_merit)
Further figures of merit can be added to `mqt.predictor.reward`.
-To register additional compilation passes (e.g., from Qiskit, TKET, or BQSKit), use:
+To register additional compilation passes (e.g., from Qiskit, TKET, or BQSKit),
+use:
```python
from mqt.predictor.rl.actions import (
@@ -72,11 +79,13 @@ action = DeviceIndependentAction(
register_action(action)
```
-For other compilation sources, a new `CompilationOrigin` must be defined and conversions to/from Qiskit's `QuantumCircuit` must be implemented.
+For other compilation sources, a new `CompilationOrigin` must be defined and
+conversions to/from Qiskit's `QuantumCircuit` must be implemented.
## Step 3: Generate Training Data and Train ML Model
-Once the RL models are trained, generate the training data and train the supervised ML model using:
+Once the RL models are trained, generate the training data and train the
+supervised ML model using:
```python
from mqt.predictor.ml import setup_device_predictor
@@ -99,11 +108,13 @@ This function will:
- Generate training data from the compiled circuits.
- Train and save a supervised model for device prediction.
-You can optionally specify custom paths for uncompiled and compiled QASM files using the `path_uncompiled_circuits` and `path_compiled_circuits` arguments.
+You can optionally specify custom paths for uncompiled and compiled QASM files
+using the `path_uncompiled_circuits` and `path_compiled_circuits` arguments.
## Step 4: Compile a Circuit with `qcompile`
-After setup, any quantum circuit can be compiled for the most suitable device with:
+After setup, any quantum circuit can be compiled for the most suitable device
+with:
```python
from mqt.predictor import qcompile
@@ -119,4 +130,5 @@ This returns:
- the compilation metadata, and
- the selected device.
-`qcompile` combines automatic device selection with device-specific compilation based on the selected figure of merit.
+`qcompile` combines automatic device selection with device-specific compilation
+based on the selected figure of merit.
diff --git a/docs/tooling.md b/docs/tooling.md
index ade8fac7d..4c9fda1af 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -4,8 +4,8 @@
# Tooling
This page summarizes the main tools, software, and standards used in MQT
-Predictor. It serves as a quick reference for new contributors and users who want
-to understand the project's ecosystem.
+Predictor. It serves as a quick reference for new contributors and users who
+want to understand the project's ecosystem.
## Python
diff --git a/docs/tracing.md b/docs/tracing.md
index 65ea4a092..76bb3f0dd 100644
--- a/docs/tracing.md
+++ b/docs/tracing.md
@@ -1,14 +1,23 @@
# Tracing the Compilation Process
-The MQT Predictor framework allows you to extract detailed, step-by-step information about the reinforcement learning agent's compilation process by generating a comprehensive JSON trace.
+The MQT Predictor framework allows you to extract detailed, step-by-step
+information about the reinforcement learning agent's compilation process by
+generating a comprehensive JSON trace.
## Enabling the Tracer
-By default, the compilation environment acts as a black box: it takes an uncompiled circuit and returns the final compiled version alongside a list of the applied passes. To minimize overhead during standard execution, detailed step-by-step logging is _disabled_.
+By default, the compilation environment acts as a black box: it takes an
+uncompiled circuit and returns the final compiled version alongside a list of
+the applied passes. To minimize overhead during standard execution, detailed
+step-by-step logging is _disabled_.
-To illuminate this process and track the exact sequence of transformations and intermediate circuit metrics, you can enable the compilation tracer. This is done by simply passing a valid file path to the `tracer_output_path` argument when calling the `qcompile` function.
+To illuminate this process and track the exact sequence of transformations and
+intermediate circuit metrics, you can enable the compilation tracer. This is
+done by simply passing a valid file path to the `tracer_output_path` argument
+when calling the `qcompile` function.
-Here is an example of how to compile a 5-qubit GHZ state while simultaneously generating a trace file:
+Here is an example of how to compile a 5-qubit GHZ state while simultaneously
+generating a trace file:
```python
from mqt.predictor import qcompile
@@ -25,47 +34,74 @@ compiled_qc, compilation_info, selected_device = qcompile(
## Trace File Structure
-The generated trace file is a standard JSON document that closely mirrors the internal Python dataclasses used to track the compilation. The file is structured into three main components: top-level compilation metadata, target device information, and a sequential list of compilation steps.
+The generated trace file is a standard JSON document that closely mirrors the
+internal Python dataclasses used to track the compilation. The file is
+structured into three main components: top-level compilation metadata, target
+device information, and a sequential list of compilation steps.
### Top-Level Metadata
The root of the JSON file provides general context about the compilation run:
- **`circuit_name`**: The name of the original uncompiled circuit.
-- **`figure_of_merit`**: The primary metric the RL agent optimized for (e.g., `expected_fidelity`).
-- **`mdp_policy`**: The Markov Decision Process (MDP) transition policy used during the episode.
-- **`schema_version`**: The version of the JSON schema (useful for ensuring compatibility with visualization tools like MQT FlowViz).
+- **`figure_of_merit`**: The primary metric the RL agent optimized for (e.g.,
+ `expected_fidelity`).
+- **`mdp_policy`**: The Markov Decision Process (MDP) transition policy used
+ during the episode.
+- **`schema_version`**: The version of the JSON schema (useful for ensuring
+ compatibility with visualization tools like MQT FlowViz).
- **`timestamp`**: The exact Unix timestamp when the compilation started.
-- **`total_duration`**: The total time (in seconds) taken to execute the entire compilation pipeline.
+- **`total_duration`**: The total time (in seconds) taken to execute the entire
+ compilation pipeline.
### Target Device Information (`device`)
-The `device` object captures a snapshot of the backend hardware the circuit is being compiled for. This ensures the trace is entirely self-contained, even if the actual hardware specifications change in the future.
+The `device` object captures a snapshot of the backend hardware the circuit is
+being compiled for. This ensures the trace is entirely self-contained, even if
+the actual hardware specifications change in the future.
- **`name`**: The identifier of the target device (e.g., `ibm_washington`).
-- **`device_qubits`**: The total number of physical qubits available on the device.
-- **`native_gates`**: A list of the basic gate instructions supported natively by the hardware.
-- **`topology`**: A list of directional edges (defined by `control` and `target` qubit indices) representing the device's connectivity graph.
-- **`calibration_data`**: Detailed error rates and execution durations for every native gate applied to specific qubit combinations.
+- **`device_qubits`**: The total number of physical qubits available on the
+ device.
+- **`native_gates`**: A list of the basic gate instructions supported natively
+ by the hardware.
+- **`topology`**: A list of directional edges (defined by `control` and `target`
+ qubit indices) representing the device's connectivity graph.
+- **`calibration_data`**: Detailed error rates and execution durations for every
+ native gate applied to specific qubit combinations.
### Compilation Steps (`steps`)
-The `steps` array is the core of the trace file. It contains an ordered sequence of snapshots, with each entry representing the state of the circuit and the RL environment _after_ a specific compilation pass has been applied.
+The `steps` array is the core of the trace file. It contains an ordered sequence
+of snapshots, with each entry representing the state of the circuit and the RL
+environment _after_ a specific compilation pass has been applied.
Each step includes:
- **Action Details**:
- `step_index`: The chronological step number.
- - `action_name`: The specific compiler pass applied (e.g., `OptimizeCliffords`).
- - `action_type`: The category of the pass (e.g., Optimization, Routing, Synthesis).
+ - `action_name`: The specific compiler pass applied (e.g.,
+ `OptimizeCliffords`).
+ - `action_type`: The category of the pass (e.g., Optimization, Routing,
+ Synthesis).
- `action_duration`: How long the pass took to execute.
- - `reward`: The numeric reward granted to the RL agent for choosing this action.
+ - `reward`: The numeric reward granted to the RL agent for choosing this
+ action.
- **Circuit Representation**:
- - `circuit_qasm3`: The physical structure of the quantum circuit at this exact timestep, serialized in standard OpenQASM 3.0 format.
+ - `circuit_qasm3`: The physical structure of the quantum circuit at this exact
+ timestep, serialized in standard OpenQASM 3.0 format.
- **High-Level Statistics**:
- Simple counts like `current_depth`, `num_qubits`, and `total_gates`.
- - `gates_per_operation`: A dictionary breaking down the frequency of each specific gate type currently present in the circuit.
-- **State Flags**: Boolean markers (`synthesized`, `laid_out`, `routed`) indicating the circuit's progress through the necessary compilation phases, ending with `is_terminal` when the process concludes.
+ - `gates_per_operation`: A dictionary breaking down the frequency of each
+ specific gate type currently present in the circuit.
+- **State Flags**: Boolean markers (`synthesized`, `laid_out`, `routed`)
+ indicating the circuit's progress through the necessary compilation phases,
+ ending with `is_terminal` when the process concludes.
- **Environment Features & Metrics**:
- - **Figures of Merit**: The evaluated metrics for the current state (e.g., Expected Fidelity, Critical Depth, Hellinger Distance, Success Probability). Each metric includes its calculated `value` and the `kind` of calculation used (exact vs. approximated).
- - **Feature Vector**: The specific circuit characteristics observed by the RL agent to make its next decision, including `program_communication`, `raw_critical_depth`, `entanglement_ratio`, `parallelism`, and `liveness`.
+ - **Figures of Merit**: The evaluated metrics for the current state (e.g.,
+ Expected Fidelity, Critical Depth, Hellinger Distance, Success Probability).
+ Each metric includes its calculated `value` and the `kind` of calculation
+ used (exact vs. approximated).
+ - **Feature Vector**: The specific circuit characteristics observed by the RL
+ agent to make its next decision, including `program_communication`,
+ `raw_critical_depth`, `entanglement_ratio`, `parallelism`, and `liveness`.
diff --git a/pyproject.toml b/pyproject.toml
index 6603bf6a8..dec16e75a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -247,7 +247,6 @@ fom = "fom"
GH200 = "We use Renovate instead of Dependabot"
MY100 = "We use ty instead of mypy"
PC111 = "We use ruff instead of blacken-docs"
-PC140 = "We use ty instead of mypy"
PC160 = "We use a mirror of crate-ci/typos"
PC170 = "We do not use rST files anymore"