🚚 Create resource_estimation module (#173)

## Description

This PR moves the resource estimation code into a new
`resource_estimation` module.

## Checklist:

- [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] 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.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: denialhaag

docs/_static/mqt_dark.png

@@ -1,3 +1,11 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+mystnb:
+  number_source_lines: true
+---
+
 # MQT ProblemSolver
 
 MQT ProblemSolver provides a framework to utilize quantum computing as a technology for users with little to no quantum computing knowledge
@@ -26,7 +34,7 @@ In the current implementation, two case studies are conducted:
 
 ### A SAT Problem: Constraint Satisfaction Problem
 
-This exemplary implementation can be found in the [`csp_example.ipynb`](https://github.com/cda-tum/mqt-problemsolver/blob/main/notebooks/csp_example.ipynb) Jupyter notebook.
+This exemplary implementation can be found in the [`csp_example.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/csp_example.ipynb) Jupyter notebook.
 Here, the solution to a Kakuro riddle with a 2x2 grid can be solved for arbitrary sums `s0` to `s3`:
 
 <p align="center">
@@ -37,7 +45,7 @@ MQT ProblemSolver will return valid values to `a`, `b`, `c`, and `d` if a soluti
 
 ### A Graph-based Optimization Problem: Travelling Salesman Problem
 
-This exemplary implementation can be found in the [`tsp_example.ipynb`](https://github.com/cda-tum/mqt-problemsolver/blob/main/notebooks/tsp_example.ipynb) Jupyter notebook.
+This exemplary implementation can be found in the [`tsp_example.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/tsp_example.ipynb) Jupyter notebook.
 Here, the solution to a Travelling Salesman Problem with 4 cities can be solved for arbitrary distances `dist_1_2` to `dist_3_4`between the cities.
 
 <p align="center">
@@ -84,7 +92,7 @@ For more details, see {cite:p}`quetschlich2023precompilation`.
 Resource estimation is a promising alternative to actually execute quantum circuits on real quantum hardware which is currently restricted by the number of qubits and the error rates. By estimating the resources needed for a quantum circuit,
 the development of quantum computing applications can be accelerated without the need to wait for the availability of large-enough quantum hardware.
 
-In `resource_estimation/RE_experiments.py`, we evaluate the resources to calculate the ground state energy of a Hamiltonian to chemical accuracy of 1 mHartree using the qubitization quantum simulation algorithm.
+In [`experiments.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/resource_estimation/experiments.ipynb), we evaluate the resources to calculate the ground state energy of a Hamiltonian to chemical accuracy of 1 mHartree using the qubitization quantum simulation algorithm.
 The Hamiltonian describes the 64 electron and 56 orbital active space of one of the stable intermediates in the ruthenium-catalyzed carbon fixation cycle.
 
 In this evaluation, we investigate
@@ -118,14 +126,15 @@ In the `equivalence_checking` module, our approach to this problem by utilizing
 - A second one to actually input a miter expression (in form of a string) together with some parameters independent from the miter (shots and delta) and use our approach to find the counter examples (if the circuits are non-equivalent).
 
 These two implementations are provided by the functions `try_parameter_combinations()` and `find_counter_examples()`, respectively.
-Examples for their usages are shown in the [`equivalence_checking_example.ipynb`](https://github.com/cda-tum/mqt-problemsolver/blob/main/notebooks/equivalence_checking/equivalence_checking_example.ipynb) Jupyter notebook.
+Examples for their usages are shown in the [`equivalence_checking_example.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/equivalence_checking/equivalence_checking_example.ipynb) Jupyter notebook.
 
 For more details, see {cite:p}`quetschlich2024equivalence_checking`.
 
 ## Improving Hardware Requirements for Fault-Tolerant Quantum Computing by Optimizing Error Budget Distributions
 
 Applying error correction to execute quantum circuits fault-tolerantly induces massive overheads in the required physical resources, often in the orders of magnitude.
-This leads to thousands of qubits already for toy-sized quantum applications. Obviously, these need to be reduced, for which the so-called error budget can be a particular lever.
+This leads to thousands of qubits already for toy-sized quantum applications.
+Obviously, these need to be reduced, for which the so-called error budget can be a particular lever.
 Even though error correction is applied, a certain error rate still remains in the execution of the quantum circuit.
 Hence, the end user defines a maximum tolerated error rate, the error budget, for the quantum application to be considered by the compiler.
 Since an error-corrected quantum circuit consists of different parts, this error budget is distributed among these parts.
@@ -136,18 +145,44 @@ To find an efficient distribution, we use resource estimation to evaluate differ
 <img src="_static/error_budget_approach.svg" height=150px>
 </p>
 
-The implementation of the approach can be found under `resource_estimation/error_budget_optimization`.
-An example usage of the implementation is shown in the [`example_use.ipynb`](https://github.com/cda-tum/mqt-problemsolver/blob/main/resource_estimation/error_budget_optimization/example_use.ipynb) Jupyter notebook.
+For an examplary usage of the implementation, see below.
+
+```{code-cell} ipython3
+from mqt.problemsolver.resource_estimation.error_budget_optimization import (
+    evaluate,
+    generate_data,
+    plot_results,
+    train,
+)
+
+total_error_budget = 0.1
+benchmarks_and_sizes = [("ae", [3, 4, 5, 6, 7, 8, 9, 10])]
+data = generate_data(
+    total_error_budget=total_error_budget,
+    number_of_randomly_generated_distributions=1000,
+    benchmarks_and_sizes=benchmarks_and_sizes,
+)
+model, x_test, y_test = train(data)
+y_pred = model.predict(x_test)
+product_diffs = evaluate(x_test, y_pred, total_error_budget)
+product_diffs_dataset = evaluate(x_test, y_test, total_error_budget)
+plot_results(product_diffs, product_diffs_dataset, legend=True, bin_width=4)
+```
+
+A more elaborate example of the implementation is shown in the [`example.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/resource_estimation/error_budget_optimization/example.ipynb) Jupyter notebook.
 
 For more details, see {cite:p}`forster2025error_budget_optimization`.
 
 ## Quantum Circuit Optimization for the Fault-Tolerance Era: Do We Have to Start from Scratch?
 
-Translating quantum circuits into a device's native gate set often increases gate count, amplifying noise in today's error-prone Noisy Intermediate-Scale Quantum (NISQ) devices. Although optimizations exist to reduce gate counts, scaling to larger qubit and circuit sizes will see hardware errors dominate, blocking industrial-scale use. Error correction can enable Fault-Tolerant Quantum Computing (FTQC) but demands massive qubit overheads, often tens of thousands for small problems.
+Translating quantum circuits into a device's native gate set often increases gate count, amplifying noise in today's error-prone Noisy Intermediate-Scale Quantum (NISQ) devices.
+Although optimizations exist to reduce gate counts, scaling to larger qubit and circuit sizes will see hardware errors dominate, blocking industrial-scale use. Error correction can enable Fault-Tolerant Quantum Computing (FTQC) but demands massive qubit overheads, often tens of thousands for small problems.
 
-This motivates FTQC-oriented optimization techniques and raises the question: can NISQ techniques be adapted, or must new ones be developed? We address this question by evaluating Qiskit and TKET optimization passes on benchmark circuits from MQT Bench. As tools to directly design and evaluate fault-tolerant quantum circuit instances, we use resource estimation to assess FTQC requirements.
+This motivates FTQC-oriented optimization techniques and raises the question: can NISQ techniques be adapted, or must new ones be developed?
+We address this question by evaluating Qiskit and TKET optimization passes on benchmark circuits from MQT Bench.
+As tools to directly design and evaluate fault-tolerant quantum circuit instances, we use resource estimation to assess FTQC requirements.
 
-The implementation of the approach can be found under `resource_estimation/ft_optimization`.
+An example usage of the implementation is shown in the [`example.ipynb`](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/notebooks/resource_estimation/fault_tolerant_optimization/example.ipynb) Jupyter notebook.
 
 For more details, see {cite:p}`forster2025ft_circuit_optimization`.
 

docs/_static/mqt_light.png

@@ -10,9 +10,12 @@
     "import csv\n",
     "from pathlib import Path\n",
     "\n",
-    "from evaluate import evaluate, plot_results\n",
-    "from generate_data import generate_data\n",
-    "from training import train"
+    "from mqt.problemsolver.resource_estimation.error_budget_optimization import (\n",
+    "    evaluate,\n",
+    "    generate_data,\n",
+    "    plot_results,\n",
+    "    train,\n",
+    ")"
    ]
   },
   {
@@ -36,7 +39,7 @@
     "use_zip_file_circuits = False\n",
     "\n",
     "if use_paper_data:\n",
-    "    csv_path = Path(\"paper_data/logical_counts.csv\")\n",
+    "    csv_path = Path(\"logical_counts.csv\")\n",
     "    with Path.open(csv_path, encoding=\"utf-8\", newline=\"\") as csvfile:\n",
     "        reader = csv.DictReader(csvfile)\n",
     "        logical_counts = [{k: int(v) for k, v in row.items()} for row in reader]\n",
@@ -47,9 +50,9 @@
     "    )\n",
     "\n",
     "elif use_zip_file_circuits:\n",
-    "    zip_file_path = Path(\"paper_data\") / \"mqtbench.zip\"\n",
+    "    zip_file_path = Path(\"mqt_bench.zip\")\n",
     "    if not zip_file_path.exists():\n",
-    "        msg = f\"Paper data not found at {zip_file_path}\"\n",
+    "        msg = f\"Data not found at {zip_file_path}\"\n",
     "        raise FileNotFoundError(msg)\n",
     "    data = generate_data(\n",
     "        total_error_budget,\n",
@@ -101,8 +104,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Y_pred = model.predict(x_test)\n",
-    "product_diffs = evaluate(x_test, Y_pred, total_error_budget)\n",
+    "y_pred = model.predict(x_test)\n",
+    "product_diffs = evaluate(x_test, y_pred, total_error_budget)\n",
     "product_diffs_dataset = evaluate(x_test, y_test, total_error_budget)\n",
     "\n",
     "plot_results(product_diffs, product_diffs_dataset, legend=True, bin_width=4)"
@@ -111,7 +114,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "mqt-problemsolver (3.13.3)",
    "language": "python",
    "name": "python3"
   },

docs/index.md

@@ -0,0 +1,210 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a5210510",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from math import ceil\n",
+    "\n",
+    "from qsharp.estimator import EstimatorParams, EstimatorResult, LogicalCounts, QECScheme, QubitParams"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "25ef4938",
+   "metadata": {},
+   "source": [
+    "# Experiments"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "06e15253",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# For all experiments, we are using the logical resource counts as a starting\n",
+    "# point.  These have been computed using the qsharp Python package (version\n",
+    "# 1.8.0) for the https://aka.ms/fcidump/XVIII-cas4-fb-64e-56o Hamiltonian on\n",
+    "# the sample\n",
+    "# https://github.com/microsoft/qsharp/tree/main/samples/estimation/df-chemistry:\n",
+    "#\n",
+    "# ```\n",
+    "# $ python chemistry.py -f https://aka.ms/fcidump/XVIII-cas4-fb-64e-56o\n",
+    "# $ jq '.logicalCounts' < resource_estimate.json\n",
+    "# ```\n",
+    "\n",
+    "logical_counts = LogicalCounts({\n",
+    "    \"numQubits\": 1318,\n",
+    "    \"tCount\": 96,\n",
+    "    \"rotationCount\": 11987084,\n",
+    "    \"rotationDepth\": 11986482,\n",
+    "    \"cczCount\": 67474931068,\n",
+    "    \"measurementCount\": 63472407520,\n",
+    "})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7b396e6b",
+   "metadata": {},
+   "source": [
+    "## Default qubit models"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "582477ec",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "params = EstimatorParams(6)\n",
+    "params.error_budget = 0.01\n",
+    "params.items[0].qubit_params.name = QubitParams.GATE_US_E3\n",
+    "params.items[1].qubit_params.name = QubitParams.GATE_US_E4\n",
+    "params.items[2].qubit_params.name = QubitParams.GATE_NS_E3\n",
+    "params.items[3].qubit_params.name = QubitParams.GATE_NS_E4\n",
+    "params.items[4].qubit_params.name = QubitParams.MAJ_NS_E4\n",
+    "params.items[4].qec_scheme.name = QECScheme.FLOQUET_CODE\n",
+    "params.items[5].qubit_params.name = QubitParams.MAJ_NS_E6\n",
+    "params.items[5].qec_scheme.name = QECScheme.FLOQUET_CODE\n",
+    "\n",
+    "results = logical_counts.estimate(params=params)\n",
+    "\n",
+    "print(results.summary_data_frame())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a707e2e5",
+   "metadata": {},
+   "source": [
+    "## Evaluating different number of T factories"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f16bbe88",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "params = EstimatorParams(num_items=14)\n",
+    "params.qubit_params.name = QubitParams.MAJ_NS_E6\n",
+    "params.qec_scheme.name = QECScheme.FLOQUET_CODE\n",
+    "\n",
+    "params.error_budget = 0.01\n",
+    "for i in range(14):\n",
+    "    params.items[i].constraints.max_t_factories = 14 - i\n",
+    "\n",
+    "results = logical_counts.estimate(params=params)\n",
+    "\n",
+    "print(results.summary_data_frame())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d94cb722",
+   "metadata": {},
+   "source": [
+    "## Modifying error rates and operating times"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "75fe4f65",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "base_time = 50  # ns\n",
+    "base_error = 1e-3\n",
+    "\n",
+    "error_growth = 1e-1\n",
+    "time_growth = 0.9\n",
+    "\n",
+    "params = EstimatorParams(num_items=5)\n",
+    "params.error_budget = 0.01\n",
+    "for t in range(5):\n",
+    "    params.items[t].qubit_params.instruction_set = \"gateBased\"\n",
+    "    params.items[t].qubit_params.name = f\"t{t}\"\n",
+    "    params.items[t].qubit_params.one_qubit_measurement_time = f\"{(2 * base_time) * time_growth**t} ns\"\n",
+    "    params.items[t].qubit_params.one_qubit_gate_time = f\"{base_time * time_growth**t} ns\"\n",
+    "    params.items[t].qubit_params.two_qubit_gate_time = f\"{base_time * time_growth**t} ns\"\n",
+    "    params.items[t].qubit_params.t_gate_time = f\"{base_time * time_growth**t} ns\"\n",
+    "    params.items[t].qubit_params.one_qubit_measurement_error_rate = base_error * error_growth**t\n",
+    "    params.items[t].qubit_params.one_qubit_gate_error_rate = base_error * error_growth**t\n",
+    "    params.items[t].qubit_params.two_qubit_gate_error_rate = base_error * error_growth**t\n",
+    "    params.items[t].qubit_params.t_gate_error_rate = base_error * error_growth**t\n",
+    "    params.items[t].qubit_params.idle_error_rate = base_error * error_growth**t\n",
+    "\n",
+    "results = logical_counts.estimate(params=params)\n",
+    "\n",
+    "print(results.summary_data_frame())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a272e940",
+   "metadata": {},
+   "source": [
+    "##  Modifying logical counts"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "43a81d61",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def modified_logical_counts(space_factor: float, time_factor: float) -> LogicalCounts:\n",
+    "    return LogicalCounts({\n",
+    "        \"numQubits\": ceil(logical_counts[\"numQubits\"] * space_factor),\n",
+    "        \"tCount\": ceil(logical_counts[\"tCount\"] * time_factor),\n",
+    "        \"rotationCount\": ceil(logical_counts[\"rotationCount\"] * time_factor),\n",
+    "        \"rotationDepth\": ceil(logical_counts[\"rotationDepth\"] * time_factor),\n",
+    "        \"cczCount\": ceil(logical_counts[\"cczCount\"] * time_factor),\n",
+    "        \"measurementCount\": ceil(logical_counts[\"measurementCount\"] * time_factor),\n",
+    "    })\n",
+    "\n",
+    "\n",
+    "params = EstimatorParams()\n",
+    "params.error_budget = 0.01\n",
+    "params.qubit_params.name = QubitParams.MAJ_NS_E6\n",
+    "params.qec_scheme.name = QECScheme.FLOQUET_CODE\n",
+    "estimates = []\n",
+    "for space_factor, time_factor in [(1.0, 1.0), (0.5, 2.0), (2.0, 0.5), (0.75, 0.75)]:\n",
+    "    counts = modified_logical_counts(space_factor, time_factor)\n",
+    "    estimates.append(counts.estimate(params=params))\n",
+    "\n",
+    "print(EstimatorResult(estimates).summary_data_frame())"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "mqt-problemsolver (3.13.3)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}