diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 75fc589b64..ee30fa776b 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -5,7 +5,7 @@ "id": "f7d9993f", "metadata": {}, "source": [ - "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez */}" + "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme */}" ] }, { @@ -21,18 +21,52 @@ "\n", "## Overview\n", "\n", - "The Tensor-network error mitigation (TEM) function computes expectation values of quantum circuits and observables by post-processing noise-induced errors in estimations of physical observables.\n", - "\n", - "The method consists of constructing a tensor network representing the inverse of the global noise channel affecting the state of the quantum processor, and then applying the map to informationally complete measurement outcomes obtained from the noisy state.\n", - "\n", - "As an advantage, TEM leverages informationally complete measurements to give access to a vast set of mitigated expectation values of observables and has optimal sampling\n", - "overhead on the quantum hardware [1]. TEM can also be advantageous with respect to purely classical tensor network methods, giving accurate results with a smaller computational cost than a classical-only tensor network approach.\n", - "\n", - "See reference [1] for further details.\n", - "\n", - "#### References\n", - "\n", - "1. S. Filippov, M. Leahy, M. A. C. Rossi, G. García-Pérez, Scalable tensor-network error mitigation for near-term quantum computing, [arXiv:1111.6950](https://arxiv.org/abs/2307.11740) [quant-ph]" + "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid\n", + "quantum-classical algorithm designed for performing noise mitigation entirely at\n", + "the classical post-processing stage. With TEM, the user can compute the\n", + "expectation values of observables mitigating the inevitable noise-induced errors\n", + "that occur on quantum hardware with increased accuracy and cost efficiency,\n", + "making it a highly attractive option for quantum researchers and industry\n", + "practitioners alike.\n", + "\n", + "The method consists of constructing a tensor network representing the inverse of\n", + "the global noise channel affecting the state of the quantum processor and then\n", + "applying the map to informationally complete measurement outcomes acquired from\n", + "the noisy state to obtain unbiased estimators for the observables.\n", + "\n", + "As an advantage, TEM leverages informationally complete measurements to give\n", + "access to a vast set of mitigated expectation values of observables and has\n", + "optimal sampling overhead on the quantum hardware, as described in Filippov at\n", + "al. (2023), [arXiv:2307.11740](https://arxiv.org/abs/2307.11740), and Filippov\n", + "at al. (2024), [arXiv:2403.13542](https://arxiv.org/abs/2403.13542). The\n", + "measurement overhead refers to the number of additional measurements required to\n", + "perform efficient error mitigation, a critical factor in the feasibility of\n", + "quantum computations. Therefore, TEM has the potential to enable quantum\n", + "advantage in complex scenarios, such as applications in the fields of quantum\n", + "chaos, many-body physics, Hubbard dynamics, and small molecule chemistry\n", + "simulations.\n", + "\n", + "The main features and benefits of TEM can be summarized as:\n", + "\n", + "1. **Optimal measurement overhead**: TEM is optimal with respect to\n", + "[theoretical bounds](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.131.210601),\n", + "meaning that no method can achieve a smaller measurement overhead. In other\n", + "words, TEM requires the minimum number of additional measurements to perform\n", + "error mitigation. This in turns means that TEM uses minimal quantum runtime.\n", + "2. **Cost-effectiveness**: Since TEM handles noise mitigation entirely in the\n", + "post-processing stage, there is no need to add extra circuits to the quantum\n", + "computer, which not only makes the computation cheaper but also diminishes the\n", + "risk of introducing additional errors due to the imperfections of quantum\n", + "devices.\n", + "3. **Estimation of multiple observables**: Thanks to informationally-complete\n", + "measurements, TEM efficiently estimates multiple observables with the same\n", + "measurement data from the quantum computer.\n", + "4. **Measurement error mitigation**: The TEM Qiskit Function also includes a\n", + "[proprietary measurement error mitigation method](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.5.033154)\n", + "able to significantly reduce readout errors after a short calibration run.\n", + "5. **Accuracy**: TEM significantly improves the accuracy and reliability of\n", + "digital quantum simulations, making quantum algorithms more precise and\n", + "dependable." ] }, { @@ -40,89 +74,56 @@ "id": "5f761442", "metadata": {}, "source": [ - "## Function description\n", - "\n", + "## Description\n", "\n", - "The TEM function takes a noisy circuit with the noisy layers identified. The circuit is measured with an informationally complete positive operator-valued measure (IC-POVM), and the collected measurement outcomes are processed on a classical computer. This measurement is used to perform the tensor network methods and build a noise-inversion map $\\mathcal{N}^{-1}$. The function applies a map $\\mathcal{M}$ that fully inverts the whole noisy circuit using matrix product operators to represent the noisy layers.\n", + "The TEM function allows you to obtain error-mitigated expectation values for\n", + "multiple observables on a quantum circuit with minimal sampling overhead. The\n", + "circuit is measured with an informationally complete positive operator-valued\n", + "measure (IC-POVM), and the collected measurement outcomes are processed on a\n", + "classical computer. This measurement is used to perform the tensor network\n", + "methods and build a noise-inversion map. The function applies a map that fully\n", + "inverts the whole noisy circuit using tensor networks to represent the noisy\n", + "layers.\n", "\n", "![TEM schematics](/images/guides/algorithmiq-tem/tem_scheme.svg \"Error-mitigated estimation of an observable O via post-processing measurement outcomes of the noisy quantum processor. U and N denote an ideal quantum operation and the associated noise map, which can be generally non-local (and extended to grey boxes). D stands for a tensor of operators that are dual to the effects in the IC measurement. The noise mitigation module M is a tensor network that is efficiently contracted from the middle out. The first iteration of the contraction is represented by the dotted purple line, the second one by the dashed line, and the third one by the solid line.\")\n", "\n", - "To mitigate the noise, the algorithm performs a contraction that starts from the middle (where the inverted noisy circuit ends and the ideal circuit starts) and propagates outward by involving two layers on the left side and one layer on the right side at each iteration. Therefore, the noisy circuit output state $\\rho$ is reverted back to $(\\vert 0 \\rangle\\langle0\\vert)^{\\otimes N}$, which in turn is mapped to the ideal noiseless state operator $\\vert\\psi\\rangle\\langle \\psi\\vert$.\n", - "\n", - "The noise-mitigated estimation of an observable ${O}$ is then read as\n", - "$$\n", - "\\bar{O}_{\\text{n}.\\text{m}} = \\frac{1}{S} \\sum_{\\mathbf{k}} \\text{tr} [\\mathcal{M}(D_{\\mathbf{k}})O] = \\frac{1}{S} \\sum_{\\mathbf{k}} \\text{tr} [D_{\\mathbf{k}}\\mathcal{M}^{\\dagger}(O)],\n", - "$$\n", - "where $D\\mathbf{k}$ is the dual operator of the corresponding POVM associated with a measurement shot $\\mathbf{k}$ in a set of $S$ shots.\n", - "\n", - "\n", - "The algorithm is described in further detail in [Filippov et al. (2023)](https://arxiv.org/abs/2307.11740).\n", - "\n", - "\n", - "### Methods\n", - "\n", - "#### run\n", - "\n", - "`run(pubs,options)`\n", - "\n", - "\n", - "The run() method allows computing the expectation values for a primitive unified bloc (PUB) containing a circuit and a list of observables.\n", - "\n", - "**Parameters**\n", - "Name | Type | Description | Required | Example\n", - "-- | -- | -- | -- | --\n", - "pubs | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/guides/primitive-input-output#overview-of-pubs) for more information. The circuits don’t need to be ISA circuits. | Yes | (circuit, observables, parameter_values)\n", - "instance | str | The hub/group/project to use in that format. | No | \"hub1/group1/project1\"\n", - "options | dict | Input options. See `Options` section for more details. | No | \\{\"optimization_level\": 3\\}\n", - "\n", - "**Options**\n", - "\n", - "A dictionary containing the options for the TEM. The dictionary should contain the following keys:\n", - "\n", - "Name | Type | Description | Example\n", - "-- | -- | -- | --\n", - "backend_name | str | Name of the backend to make the query.| \"ibm_fez\"\n", - "simulate_with_noise_model | bool | A Boolean flag indicating whether to simulate the noisy circuit or not.| False\n", - "max_bond_dimension | int | The maximum bond dimension to be used for MPOs. | True\n", - "tem_compression_cutoff | float | The cutoff value to be used for MPOs. | 1e-16\n", - "num_max_shots | int | The maximum number of shots. | 10_000\n", - "num_randomizations | int | The number of randomizations to be used for gate twirling. | 32\n", - "mitigate_readout_error | bool | A Boolean flag indicating whether to perform QDT readout error mitigation or not. | 24\n", - "num_readout_calibration_shots | int | The number of shots to be used for QDT readout error mitigation. | 1000\n", - "logging_level | str | The logging level to be used for the TEM runner. | \"INFO\"\n", - "\n", - "**Returns**\n", - "\n", - "A PubResult containing the TEM mitigated result:\n", - "\n", - "\n", - "Name |Type | Description\n", - "-- | -- | --\n", - "data | DataBin | A DataBin containing the TEM mitigated observable and its standard error. The DataBin has the following fields: \n", - "metadadata | dict | A dictionary containing additional results. The dictionary contains the following keys: " + "Once the circuits are submitted to the function, they are transpiled and\n", + "optimized to minimize the number of layers with two-qubit gates (the noisier\n", + "gates on quantum devices). The noise affecting the layers is learned through\n", + "[Qiskit Runtime](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.noise_learner.NoiseLearner)\n", + "using a sparse Pauli-Lindblad noise model as described in E. van den Berg, Z.\n", + "Minev, A. Kandala, K. Temme, Nat. Phys. (2023).\n", + "[arXiv:2201.09866](https://arxiv.org/abs/2201.09866).\n", + "\n", + "The noise model is an accurate description of the noise on the device able to\n", + "capture subtle features, including qubit cross-talk. However, noise on the\n", + "devices can fluctuate and drift and the learned noise might not be accurate at\n", + "the point at which the estimation is done. This might result in inaccurate\n", + "results." ] }, { "cell_type": "markdown", - "id": "73390a19", + "id": "2995da29", "metadata": {}, "source": [ "## Get started\n", "\n", - "Authenticate using your [IBM Quantum Platform API token](http://quantum.ibm.com/), and select the TEM as follows:" + "Authenticate using your [IBM Quantum Platform API token](http://quantum.ibm.com/), and select the TEM function as follows:" ] }, { "cell_type": "code", - "execution_count": 1, - "id": "95a715d2", + "execution_count": null, + "id": "cc0a8093", "metadata": {}, "outputs": [], "source": [ "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", "tem_function_name = \"algorithmiq/tem\"\n", - "catalog = QiskitFunctionsCatalog(token = \"\")\n", + "\n", + "catalog = QiskitFunctionsCatalog(token=\"\")\n", "\n", "# Load your function\n", "tem = catalog.load(tem_function_name)" @@ -130,7 +131,7 @@ }, { "cell_type": "markdown", - "id": "e8837f5f", + "id": "ae7adcc7", "metadata": {}, "source": [ "## Example\n", @@ -141,8 +142,8 @@ }, { "cell_type": "code", - "execution_count": 7, - "id": "d56e1440", + "execution_count": null, + "id": "ab05b87f", "metadata": {}, "outputs": [], "source": [ @@ -165,70 +166,143 @@ " qc.u(-1.2, -1.2, 0.3, 2)\n", "\n", "# Define the observables\n", - "observable = SparsePauliOp(\"YXZ\", 1.0)\n", + "observable = SparsePauliOp(\"IYX\", 1.0)\n", "\n", "# Define the execution options\n", "service = QiskitRuntimeService()\n", "backend_name = service.least_busy(operational=True).name\n", + "\n", "instance = \"\"\n", "\n", - "pub = (qc, observable)\n", + "pub = (qc, [observable])\n", "options = {\n", - " \"backend_name\": backend_name,\n", - " \"num_max_shots\": 100,\n", + " \"max_execution_time\": 60,\n", "}\n", - "job = tem.run(instance=instance, pub=pub, options=options)" + "job = tem.run(pubs=[pub], instance=instance, backend_name=backend_name, options=options)" ] }, { "cell_type": "markdown", - "id": "03998691", + "id": "6e2a97e2", "metadata": {}, "source": [ - "The following code checks your Qiskit Function workload's status or return results:" + "Use the Qiskit Serverless APIs to check your Qiskit Function workload's status:" ] }, { "cell_type": "code", "execution_count": null, - "id": "856fe992", + "id": "47b0db71", "metadata": {}, "outputs": [], "source": [ - "print(job.status())\n", - "result = job.result()" + "print(job.status())" ] }, { "cell_type": "markdown", - "id": "e2817b13", + "id": "fbaeace8", "metadata": {}, "source": [ - "## Advanced options\n", - "\n", - "You can fine-tune your calculations and get more verbose information by passing additional options to TEM." + "You can return the results as:" ] }, { "cell_type": "code", - "execution_count": 7, - "id": "c2ce65e3", + "execution_count": null, + "id": "ad5b9a53", "metadata": {}, "outputs": [], "source": [ - "import logging\n", + "result = job.result()\n", + "evs = result[0].data.evs" + ] + }, + { + "cell_type": "markdown", + "id": "e5e138d3", + "metadata": {}, + "source": [ + "\n", + " The expected value for the noiseless circuit for the given operator should be around `0.18409094298943401`.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "c6ffb685", + "metadata": {}, + "source": [ + "## Inputs\n", "\n", - "options = {\n", - " \"backend_name\": backend_name,\n", - " \"num_max_shots\": 1_000,\n", - " \"simulate_with_noise_model\": True,\n", - " \"mitigate_readout_error\": True,\n", - " \"num_readout_calibration_shots\": 10_000,\n", - " \"logging_level\": logging.WARNING\n", - " }\n", + "**Parameters**\n", + "Name | Type | Description | Required | Default | Example\n", + "-- | -- | -- | -- | -- | --\n", + "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/guides/primitive-input-output#overview-of-pubs) for more information. The circuits don't need to be ISA circuits. | Yes | N/A | (circuit, observables)\n", + "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least busy backend will be used. | \"ibm_fez\"\n", + "`instance` | str | The hub/group/project to use in that format. | Yes | N/A |\"hub1/group1/project1\"\n", + "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", + "\n", + "\n", + " TEM does not currently support parametrized circuits. The `parameters` argument should be set to `None` if `precision` is specified.\n", + "\n", + " TEM currently supports circuits with linear connectivity. This restriction will be removed in future versions." + ] + }, + { + "cell_type": "markdown", + "id": "1ebd5f9b", + "metadata": {}, + "source": [ + "### Options\n", + "\n", + "A dictionary containing the advanced options for the TEM. The dictionary may contain the keys in the following table. If any of the options are not provided, the default value listed in the table will be used. The default values are good for typical use of TEM.\n", + "\n", + "Name | Choices | Description | Default\n", + "-- | -- | -- | --\n", + "`max_bond_dimension` | int | The maximum bond dimension to be used for the tensor networks. | 500 |\n", + "`tem_compression_cutoff` | float | The cutoff value to be used for the tensor networks. | 1e-16\n", + "`max_execution_time` | int or `None` | The maximum execution time on the QPU in seconds. If the runtime exceeds this value, the job will be canceled. If `None`, a default limit set by Qiskit Runtime will apply. | `None`\n", + "`num_randomizations` | int | The number of randomizations to be used for gate twirling. | 32\n", + "`mitigate_readout_error` | bool | A Boolean flag indicating whether to perform readout error mitigation or not. | True\n", + "`num_readout_calibration_shots` | int | The number of shots to be used for readout error mitigation. | 10000\n", + "`default_precision` | float | The default precision to be used for the PUBs for which the precision is not specified. |0.02" + ] + }, + { + "cell_type": "markdown", + "id": "7a04364c", + "metadata": {}, + "source": [ + "## Outputs\n", "\n", + "A Qiskit [PrimitiveResults](/api/qiskit/qiskit.primitives.PrimitiveResult) containing the TEM-mitigated result. The result for each PUB is returned as a [PubResult](/api/qiskit/qiskit.primitives.PubResult) containing the following fields:\n", "\n", - "job = tem.run(instance = instance, pub = pub, options = options)" + "\n", + "Name |Type | Description\n", + "-- | -- | --\n", + "data | DataBin | A Qiskit [DataBin](/api/qiskit/qiskit.primitives.DataBin) containing the TEM mitigated observable and its standard error. The DataBin has the following fields:
  • `evs`: The TEM-mitigated observable value.
  • `stds`: The standard error of the TEM-mitigated observable.
\n", + "metadadata | dict | A dictionary containing additional results. The dictionary contains the following keys:
  • `\"evs_non_mitigated\"`: The observable value without error mitigation.
  • `\"stds_non_mitigated\"`: The standard error of the result without error mitigation.
  • `\"evs_mitigated_no_readout_mitigation\"`: The observable value with error mitigation but without readout error mitigation.
  • `\"stds_mitigated_no_readout_mitigation\"`: The standard error of the result with error mitigation but without readout error mitigation.
  • `\"evs_non_mitigated_with_readout_mitigation\"`: The observable value without error mitigation but with readout error mitigation.
  • `\"stds_non_mitigated_with_readout_mitigation\"`: The standard error of the result without error mitigation but with readout error mitigation.
" + ] + }, + { + "cell_type": "markdown", + "id": "fd045ee6", + "metadata": {}, + "source": [ + "## Fetching error messages\n", + "\n", + "If your workload status is ERROR, use job.result() to fetch the error message as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0433171c", + "metadata": {}, + "outputs": [], + "source": [ + "print(job.result())" ] }, {