diff --git a/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx index 068cd65ac66..72f371e9204 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx @@ -58,7 +58,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata This method computes the accumulated error for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices. - The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`). + The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`). Since a general Lp-norm (other than `p=2`) is *not* an inner product norm, it does *not* satisfy the [parallelogram law](https://en.wikipedia.org/wiki/Parallelogram_law). Hence, we must use the Minkowski inequality as the upper bound of the accumulated error. @@ -103,7 +103,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata This method computes the left-over error budget for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices. - The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). + The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). See also the explanations in [`accumulated_error()`](#qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error") for more details on how the individual slice errors are summed up to form an upper bound to the real error via the Minkowski inequality. diff --git a/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx index 2b2ffb5ef4d..3734069e460 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx @@ -63,7 +63,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.SliceMetadata The sum of the coefficients for each observable that were trimmed during operator simplification because each individual coefficient was below the trimming threshold. - This sum is *not* affected by the value of [`p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")! + This sum is *not* affected by the value of [`p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")! diff --git a/docs/api/qiskit-ibm-runtime/0.31/_toc.json b/docs/api/qiskit-ibm-runtime/0.31/_toc.json index aacef710182..85e82fa0c29 100644 --- a/docs/api/qiskit-ibm-runtime/0.31/_toc.json +++ b/docs/api/qiskit-ibm-runtime/0.31/_toc.json @@ -514,4 +514,3 @@ ], "collapsed": true } - diff --git a/docs/guides/latest-updates.mdx b/docs/guides/latest-updates.mdx index 7e91d26559c..1434503f753 100644 --- a/docs/guides/latest-updates.mdx +++ b/docs/guides/latest-updates.mdx @@ -202,5 +202,5 @@ Join, participate, contribute! See what events are coming up on the [Qiskit comm ## See all product updates -Visit the [Product announcements](https://docs.quantum.ibm.com/announcements/product-updates) to browse all product updates and news. +Visit the [Product announcements](/announcements/product-updates) to browse all product updates and news. diff --git a/docs/guides/qedma-qesem.ipynb b/docs/guides/qedma-qesem.ipynb index 7a33b04e84a..85597163355 100644 --- a/docs/guides/qedma-qesem.ipynb +++ b/docs/guides/qedma-qesem.ipynb @@ -37,56 +37,55 @@ "id": "74823696", "metadata": {}, "source": [ - "## Unique error mitigation features\n", "QESEM has been demonstrated to provide high-accuracy results for a variety of quantum applications and on the largest circuit volumes achievable today. QESEM offers the following user-facing features, demonstrated in the benchmarks section below:\n", - "1.\t**Guaranteed accuracy:** QESEM outputs unbiased estimations for expectation values of observables. Its EM method is equipped with theoretical guarantees, which - together with Qedma’s cutting-edge characterization - ensure the mitigation converges to the noiseless circuit output up to the user-specified accuracy. In contrast to many heuristic EM methods that are prone to systematic errors or biases, QESEM’s guaranteed accuracy is essential for ensuring reliable results in generic quantum circuits and observables.\n", - "2.\t**Scalability to large QPUs:** QESEM’s QPU time depends on circuit volumes, but is otherwise independent of the number of qubits. Qedma has demonstrated QESEM on the largest quantum devices available today, including the IBM Quantum 127-qubit Eagle and 133-qubit Heron devices.\n", - "3.\t**Application-agnostic:** QESEM has been demonstrated on a variety of applications, including Hamiltonian simulation, VQE, QAOA, and amplitude estimation. Users can input any quantum circuit and observable to be measured, and obtain accurate error-free results. The only limitations are dictated by the hardware specifications and allocated QPU time, which determine the accessible circuit volumes and output accuracies. In contrast, many error reduction solutions are application-specific or involve uncontrolled heuristics, rendering them inapplicable for generic quantum circuits and applications.\n", - "4. **Extended gate set:** QESEM supports fractional-angle gates, and provides Qedma-optimized fractional-angle $Rzz(\\theta)$ gates on IBM Quantum Eagle devices. This extended gate set enables more efficient compilation and unlocks circuit volumes larger by a factor of up to 2 compared to default CX/CZ compilation.\n", - "5.\t**Multibase observables:** QESEM supports input observables composed of many non-commuting Pauli strings, such as generic Hamiltonians. The choice of measurement bases and the optimization of QPU resource allocation (shots and circuits) is then performed automatically by QESEM to minimize the required QPU time for the requested accuracy. This optimization, which takes into account hardware fidelities and execution rates, enables you to run deeper circuits and obtain higher accuracies." + "-\t**Guaranteed accuracy:** QESEM outputs unbiased estimations for expectation values of observables. Its EM method is equipped with theoretical guarantees, which - together with Qedma’s cutting-edge characterization - ensure the mitigation converges to the noiseless circuit output up to the user-specified accuracy. In contrast to many heuristic EM methods that are prone to systematic errors or biases, QESEM’s guaranteed accuracy is essential for ensuring reliable results in generic quantum circuits and observables.\n", + "-\t**Scalability to large QPUs:** QESEM’s QPU time depends on circuit volumes, but is otherwise independent of the number of qubits. Qedma has demonstrated QESEM on the largest quantum devices available today, including the IBM Quantum 127-qubit Eagle and 133-qubit Heron devices.\n", + "-\t**Application-agnostic:** QESEM has been demonstrated on a variety of applications, including Hamiltonian simulation, VQE, QAOA, and amplitude estimation. Users can input any quantum circuit and observable to be measured, and obtain accurate error-free results. The only limitations are dictated by the hardware specifications and allocated QPU time, which determine the accessible circuit volumes and output accuracies. In contrast, many error reduction solutions are application-specific or involve uncontrolled heuristics, rendering them inapplicable for generic quantum circuits and applications.\n", + "- **Extended gate set:** QESEM supports fractional-angle gates, and provides Qedma-optimized fractional-angle $Rzz(\\theta)$ gates on IBM Quantum Eagle devices. This extended gate set enables more efficient compilation and unlocks circuit volumes larger by a factor of up to 2 compared to default CX/CZ compilation.\n", + "-\t**Multibase observables:** QESEM supports input observables composed of many non-commuting Pauli strings, such as generic Hamiltonians. The choice of measurement bases and the optimization of QPU resource allocation (shots and circuits) is then performed automatically by QESEM to minimize the required QPU time for the requested accuracy. This optimization, which takes into account hardware fidelities and execution rates, enables you to run deeper circuits and obtain higher accuracies." ] }, { "cell_type": "markdown", - "id": "8b901258", + "id": "57b41ab0", "metadata": {}, "source": [ - "## Function parameters\n", + "## Benchmarks\n", "\n", - "| Name | Type | Description | Required | Default | Example |\n", - "| -----| ------| ------------| -------- | ------- | -------- |\n", - "| `instance` | str| The hub/group/project to use in that format | No | N/A | “hub1/group1/project1” |\n", - "| `action` | str | The required action: \"estimate_qpu_time\" or \"execute\" | Yes | N/A | \"execute\" |\n", - "| `pubs` | Iterable[EstimatorPubLike] | A pub-like object in the form of (circuit, observables) | Yes| N/A | (circ1, [obs1,obs2,obs3]) |\n", - "| `precision` | float | The target precision for expectation value estimates of each observable | Yes| N/A | 0.03 |\n", - "| `run_options` | dict | Includes the name of the backend to run on | Yes | N/A | `{ backend_name = \"ibm_fez\" }` |\n", - "| `custom_options` |dict | Advanced features: `transpilation_level` and `max_qpu_time` (in seconds)| No | `max_qpu_time` = 14400 , `transpilation_level`= 1 | `{ max_qpu_time = 14400, transpilation_level = 0 }` |" + "QESEM has been tested on a wide variety of use cases and applications. The following examples can assist you with assessing which types of workloads you can run with QESEM.\n", + "\n", + "A key figure of merit for quantifying the hardness of both error mitigation and classical simulation for a given circuit and observable is **active volume**: the number of CNOT gates affecting the observable in the circuit. The active volume depends on the circuit depth and width, on the observable weight, and on the circuit structure, which determines the light cone of the observable. For further details, see the talk from the [2024 IBM Quantum Summit](https://www.youtube.com/watch?v=Hd-IGvuARfE&t=1730s). QESEM provides particularly large value in the high-volume regime, giving reliable results for generic circuits and observables.\n", + "\n", + "![Active volume](/images/guides/qedma-qesem/active_volume.svg)\n", + "\n", + "\n", + "| Application | Number of qubits | Device | Circuit description | Accuracy | Total time | Runtime usage |\n", + "| --------- | ---------------- | ----- | -------------------------- | -------- | ---------- | ------------- |\n", + "| VQE circuit | 8 | Eagle (r3) | 21 total layers, 9 measurement bases, 1D chain | 98% | 35 min | 14 min |\n", + "| Kicked Ising | 28 | Eagle (r3) | 3 unique layers x 3 steps, 2D heavy-hex topology | 97% | 22 min | 4 min |\n", + "| Kicked Ising | 28 | Eagle (r3) | 3 unique layers x 8 steps, 2D heavy-hex topology | 97% | 116 min | 23 min |\n", + "| Trotterized Hamiltonian simulation | 40 | Eagle (r3) | 2 unique layers x 10 Trotter steps, 1D chain | 97% | 3 hours | 25 min |\n", + "| Trotterized Hamiltonian simulation | 119 | Eagle (r3) | 3 unique layers x 9 Trotter steps, 2D heavy-hex topology | 95% | 6.5 hours | 45 min |\n", + "| Kicked Ising | 136 | Heron (r2) | 3 unique layers x 15 steps, 2D heavy-hex topology | 99% | 52 min | 9 min |\n", + "\n", + "Accuracy is measured here relative to the ideal value of the observable: $\\frac{\\langle O \\rangle_{ideal} - \\epsilon}{\\langle O \\rangle_{ideal}}$, where '$\\epsilon$' is the absolute precision of the mitigation (set by the user input), and $\\langle O \\rangle_{ideal}$ is the observable at the noiseless circuit.\n", + "'Runtime usage' measures the usage of the benchmark in batch mode (sum over usage of individual jobs), whereas 'total time' measures usage in session mode (experiment wall time), which includes additional classical and communication times. QESEM is available for execution in both modes, so that users can make the best use of their available resources.\n", + "\n", + "The 28-qubit Kicked Ising circuits simulate the Discrete Time Quasicrystal studied by Shinjo et al. (see [arXiv 2403.16718](https://arxiv.org/abs/2403.16718) and [Q2B24 Tokyo](https://www.youtube.com/watch?v=tQW6FdLc6zo)) on three connected loops of ibm_kawasaki. The circuit parameters taken here are $(\\theta_x, \\theta_z) = (0.9 \\pi, 0)$, with a ferromagnetic initial state $| \\psi_0 \\rangle = | 0 \\rangle ^{\\otimes n}$. The measured observable is the absolute value of the magnetization $M = |\\frac{1}{28} \\sum_{i=0}^{27} \\langle Z_i \\rangle|$. The utility-scale Kicked Ising experiment was run on the 136 best qubits of ibm_fez; this particular benchmark was run at the Clifford angle $(\\theta_x, \\theta_z) = (\\pi, 0)$, at which the active volume grows slowly with circuit depth, which - together with the high device fidelities - enables high accuracy at a short runtime.\n", + "\n", + "Trotterized Hamiltonian simulation circuits are for a Transverse-Field Ising model at fractional angles: $(\\theta_{zz}, \\theta_x) = (\\pi / 4, \\pi /8)$ and $(\\theta_{zz}, \\theta_x) = (\\pi / 6, \\pi / 8)$ correspondingly (see [Q2B24 Tokyo](https://www.youtube.com/watch?v=tQW6FdLc6zo)). The utility-scale circuit was run on the 119 best qubits of ibm_brisbane, whereas the 40-qubit experiment was run on the best available chain. The accuracy is reported for the magnetization; high-accuracy results were obtained for higher-weight observables as well.\n", + "\n", + "The VQE circuit was developed together with researchers from the Center for Quantum Technology and Applications at the Deutsches Elektronen-Synchrotron (DESY). The target observable here was a Hamiltonian consisting of a large number of non-commuting Pauli strings, emphasizing QESEM's optimized performance for multi-basis observables. Mitigation was applied to a classically-optimized ansatz; although these results are still unpublished, results of the same quality will be obtained for different circuits with similar structural properties." ] }, { "cell_type": "markdown", - "id": "73390a19", + "id": "d6fb65de", "metadata": {}, "source": [ "## Get started\n", "\n", - "Authenticate using your [IBM Quantum Platform API token](http://quantum.ibm.com/), and select the Qiskit Function as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "613c4d93", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# This cell is hidden from users\n", - "# It stops the linter complaining about undefined variables\n", - "# ruff: noqa: F821" + "Authenticate using your [IBM Quantum Platform API token](http://quantum.ibm.com/), and select the QESEM Qiskit Function as follows:" ] }, { @@ -96,6 +95,8 @@ "metadata": {}, "outputs": [], "source": [ + "import qiskit\n", + "\n", "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", "catalog = QiskitFunctionsCatalog(token=\"\")\n", @@ -105,19 +106,12 @@ }, { "cell_type": "markdown", - "id": "e8837f5f", + "id": "5f0120d8", "metadata": {}, "source": [ "## Example\n", "\n", - "The QESEM function must get the following parameters to be executed:\n", - "- action\n", - "- pubs (circuit, observables)\n", - "- precision\n", - "- run_options\n", - "\n", - "\n", - "To get started, try the basic example of estimating QPU time:" + "To get started, try this basic example of estimating the required QPU time to run the QESEM for a given `pub`:" ] }, { @@ -127,25 +121,39 @@ "metadata": {}, "outputs": [], "source": [ + "circ= qiskit.QuantumCircuit(5)\n", + "circ.cx(0, 1)\n", + "circ.cx(2, 3)\n", + "circ.cx(1, 2)\n", + "circ.cx(3, 4)\n", + "\n", + "avg_magnetization= qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", + " [(\"Z\", [q], 1 / 5) for q in range(5)],\n", + " num_qubits = 5\n", + ")\n", + "other_observable = qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", + " [(\"ZZ\", [0, 1], 1.0), (\"XZ\", [1, 4], 0.5)],\n", + " num_qubits = 5\n", + ")\n", + "\n", "job = qesem_function.run(\n", - " action = \"estimate_qpu_time\",\n", - " instance = \"hub/group/project\",\n", + " instance = \"hub1/group1/project1\",\n", " pubs = [\n", " (\n", " circ,\n", - " [obs1,obs2,obs3]\n", + " [avg_magnetization, other_observable]\n", " )\n", " ],\n", - " precision = 0.03,\n", - " run_options = {\n", - " \"backend_name\": \"ibm_brisbane\",\n", - " }\n", + " options = {\n", + " \"estimate_time_only\": True,\n", + " },\n", + " backend_name = \"ibm_brisbane\",\n", ")" ] }, { "cell_type": "markdown", - "id": "2e5869f3", + "id": "ae10a4c8", "metadata": {}, "source": [ "The following example executes a QESEM job:" @@ -159,36 +167,20 @@ "outputs": [], "source": [ "job = qesem_function.run(\n", - " action = \"execute\",\n", - " instance = \"hub/group/project\",\n", + " instance = \"hub1/group1/project1\",\n", " pubs = [\n", " (\n", " circ,\n", - " [obs1,obs2,obs3]\n", + " [avg_magnetization, other_observable]\n", " )\n", " ],\n", - " precision = 0.03,\n", - " run_options = {\n", - " \"backend_name\": \"ibm_brisbane\",\n", - " }\n", + " backend_name = \"ibm_brisbane\",\n", ")" ] }, { "cell_type": "markdown", - "id": "399b0deb", - "metadata": {}, - "source": [ - "\n", - "- The `precision` parameter signifies the acceptable error on the expectation values of the observables in absolute value. Namely, the QPU runtime for mitigation will be determined to provide output values for all the observables of interest that fall within a `1σ` confidence interval of the target precision. If multiple observables are provided, the mitigation will run until the target precision is reached for each of the input observables.\n", - "\n", - "- Currently QESEM supports a single `PUB`.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "03998691", + "id": "dfe99043", "metadata": {}, "source": [ "You can use the familiar Qiskit Serverless APIs to check your Qiskit Function workload's status or return results:" @@ -207,95 +199,154 @@ }, { "cell_type": "markdown", - "id": "e2817b13", + "id": "8b901258", "metadata": {}, "source": [ - "## Custom options\n", + "## Function parameters\n", + "\n", + "\n", + "| Name | Type | Description | Required | Default | Example |\n", + "| -----| ------| ------------| -------- | ------- | -------- |\n", + "| `pubs` | [EstimatorPubLike](https://docs.quantum.ibm.com/guides/primitive-input-output) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", + "| `backend_name`| string|Name of the backend to use |No | QESEM will get least busy device reported by IBM| `\"ibm_fez\"`|\n", + "| `instance` | string| The hub/group/project to use in that format | No | N/A | `“hub1/group1/project1”` |\n", + "| `options` | dictionary |Input options. See **Options** section for more details. | No | See the **Options** section for details. | `{ default_precision = 0.03, \"max_execution_time\" = 3600, \"transpilation_level\" = 0, \"estimate_time_only\" = False}` |\n", "\n", - "Provide the `custom_options` parameter to set additional advanced features for the QESEM function:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c2ce65e3", - "metadata": {}, - "outputs": [], - "source": [ - "# example execute QESEM job\n", - "job = qesem_function.run(\n", - " action = \"execute\",\n", - " instance = \"hub/group/project\",\n", - " pubs = [\n", - " (\n", - " bell,\n", - " [obs1,obs2,obs3]\n", - " )\n", - " ],\n", - " precision = 0.03,\n", - " run_options = {\n", - " \"backend_name\": \"ibm_brisbane\",\n", - " },\n", - " custom_options = {\n", - " \"max_qpu_time\": 14400,\n", - " \"transpilation_level\": 0\n", - " }\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "bcd50b21", - "metadata": {}, - "source": [ - "`max_qpu_time`: Allows you to limit the QPU time, specified in seconds, to be used for the entire QESEM process. Since the final QPU time required to reach the target accuracy is determined dynamically during the QESEM job, this parameter enables you to limit the cost of the experiment. If the dynamically-determined QPU time is shorter than the time allocated by the user, this parameter will not affect the experiment. The `max_qpu_time` parameter is particularly useful in cases where the analytical time estimate provided by QESEM before the job starts is too pessimistic and the user wants to initiate a mitigation job anyway. After the time limit it reached, QESEM stops sending new circuits. Circuits that have already been sent continue running (so the total time may surpass the limit by up to 30 minutes), and the user receives the processed results from the circuits that ran up to that point. If you want to apply a QPU time limit shorter than the analytical time estimate, consult with Qedma to obtain an estimate for the accuracy achievable within the time limit.\n", "\n", "\n", - "`transpilation_level`: After a circuit is submitted to QESEM, it automatically prepares several alternative circuit transpilations and chooses the one that minimizes QPU time. For instance, alternative transpilations might utilize Qedma-optimized fractional RZZ gates to reduce the circuit depth. Of course, all transpilations are equivalent to the input circuit, in terms of their ideal output.\n", + "### Options\n", "\n", - "To exert more control over the circuit transpilation, set the transpilation level in the `QesemOptions`. While ‘level 1’ corresponds to the default behavior described above, ‘level 0’ includes only minimal modifications required for high-accuracy output; for example, ‘layerification’ - the organization of circuit operations into ‘layers’ of simultaneous two-qubit gates. Note that automatic hardware-mapping onto high-fidelity qubits is applied in any case.\n", + "\n", + "| Option | Choices | Description | Default |\n", + "| -----| -----------| -------- | ------- |\n", + "| `estimate_time_only` | True / False | Specifies whether to execute the mitigation process or only get QPU time estimation. Please note that the QPU time estimation process does not consume QPU time.| False|\n", + "|`default_precision` | 0 < float | Will apply to `pubs` that don't have presicion. The precision signifies the acceptable error on the expectation values of the observables in absolute value. Namely, the QPU runtime for mitigation will be determined to provide output values for all the observables of interest that fall within a `1σ` confidence interval of the target precision. If multiple observables are provided, the mitigation will run until the target precision is reached for each of the input observables. | 0.02|\n", + "|`max_execution_time` | 0 < integer < 28,800 (8 hours)| Allows you to limit the QPU time, specified in seconds, to be used for the entire QESEM process. Please find additional details below.| 3,600 (one hour)|\n", + "| `transpilation_level` | 0 / 1 | See description below | 1|\n", + "\n", + "The QPU time estimation changes from one backend to another. Therefore, when executing the QESEM function, make sure to run it on the same backend that was selected when obtaining the QPU time estimation. \n", + "\n", + "QESEM will end its run when it reaches the target precision or when it reaches `max_execution_time`, whichever comes first. \n", + "\n", + "- `max_execution_time`: Allows you to limit the QPU time, specified in seconds, to be used for the entire QESEM process. Since the final QPU time required to reach the target accuracy is determined dynamically during the QESEM job, this parameter enables you to limit the cost of the experiment. If the dynamically-determined QPU time is shorter than the time allocated by the user, this parameter will not affect the experiment. The `max_execution_time` parameter is particularly useful in cases where the analytical time estimate provided by QESEM before the job starts is too pessimistic and the user wants to initiate a mitigation job anyway. After the time limit it reached, QESEM stops sending new circuits. Circuits that have already been sent continue running (so the total time may surpass the limit by up to 30 minutes), and the user receives the processed results from the circuits that ran up to that point. If you want to apply a QPU time limit shorter than the analytical time estimate, consult with Qedma to obtain an estimate for the accuracy achievable within the time limit.\n", + "\n", + "\n", + "- `transpilation_level`: After a circuit is submitted to QESEM, it automatically prepares several alternative circuit transpilations and chooses the one that minimizes QPU time. For instance, alternative transpilations might utilize Qedma-optimized fractional RZZ gates to reduce the circuit depth. Of course, all transpilations are equivalent to the input circuit, in terms of their ideal output. To exert more control over the circuit transpilation, set the transpilation level in the `options`. While `\"transpilation_level\": 1 ` corresponds to the default behavior described above, `\"transpilation_level\": 0 ` includes only minimal modifications required for high-accuracy output; for example, ‘layerification’ - the organization of circuit operations into ‘layers’ of simultaneous two-qubit gates. Note that automatic hardware-mapping onto high-fidelity qubits is applied in any case.\n", "\n", "| `transpilation_level` | description |\n", "|:-:|:--|\n", "| `1` | Default QESEM transpilation. Prepares several alternative transpilations and chooses the one that minimizes QPU time. Barriers may be modified in the layerification step. |\n", - "| `0` | Minimal transpilation: the mitigated circuit will closely resemble the input circuit structurally. Circuits provided in level 0 should match the device connectivity and should be specified in terms of the following gates: CX, Rzz(α), and standard single-qubit gates (U, x, sx, rz, etc). Barriers will be respected in the layerification step. |\n", + "| `0` | Minimal transpilation: the mitigated circuit will closely resemble the input circuit structurally. Circuits provided in level 0 should match the device connectivity and should be specified in terms of the following gates: CX, Rzz(α), and standard single-qubit gates (U, x, sx, rz, and so on). Barriers will be respected in the layerification step. |\n", "\n", "\n", - "Qiskit barriers are typically used to specify the layers of two-qubit gates in quantum circuits. In level 0, QESEM preserves the layers specified by the barriers. In level 1, the layers specified by the barriers are considered as one transpilation alternative when minimizing QPU time.\n", + "Barriers operations are typically used to specify the layers of two-qubit gates in quantum circuits. In level 0, QESEM preserves the layers specified by the barriers. In level 1, the layers specified by the barriers are considered as one transpilation alternative when minimizing QPU time.\n", "" ] }, { "cell_type": "markdown", - "id": "895db40f", + "id": "5ec8053b", "metadata": {}, "source": [ - "## Benchmarks\n", - "\n", - "QESEM has been tested on a wide variety of use cases and applications. The following examples can assist you with assessing which types of workloads you can run with QESEM.\n", + "### Outputs\n", + "The output of a Circuit function is a [PrimitiveResult](/api/qiskit/qiskit.primitives.PrimitiveResult), which contains two fields:\n", "\n", - "A key figure of merit for quantifying the hardness of both error mitigation and classical simulation for a given circuit and observable is **active volume**: the number of CNOT gates affecting the observable in the circuit. The active volume depends on the circuit depth and width, on the observable weight, and on the circuit structure, which determines the lightcone of the observable. For further details, see the talk from the [2024 IBM Quantum Summit](https://www.youtube.com/watch?v=Hd-IGvuARfE&t=1730s). QESEM provides particularly large value in the high-volume regime, giving reliable results for generic circuits and observables.\n", + "- One [PubResult](/api/qiskit/qiskit.primitives.PubResult) object. It can be indexed directly from the `PrimitiveResult`.\n", "\n", - "![Active volume](/images/guides/qedma-qesem/active_volume.svg)\n", + "- Job-level metadata.\n", "\n", + "Each `PubResult` contains a `data` and a `metadata` field.\n", "\n", - "| Application | Number of qubits | Device | Circuit description | Accuracy | Total time | Runtime usage |\n", - "| --------- | ---------------- | ----- | -------------------------- | -------- | ---------- | ------------- |\n", - "| VQE circuit | 8 | Eagle (r3) | 21 total layers, 9 measurement bases, 1D chain | 98% | 35 min | 14 min |\n", - "| Kicked Ising | 28 | Eagle (r3) | 3 unique layers x 3 steps, 2D heavy-hex topology | 97% | 22 min | 4 min |\n", - "| Kicked Ising | 28 | Eagle (r3) | 3 unique layers x 8 steps, 2D heavy-hex topology | 97% | 116 min | 23 min |\n", - "| Trotterized Hamiltonian simulation | 40 | Eagle (r3) | 2 unique layers x 10 Trotter steps, 1D chain | 97% | 3 hours | 25 min |\n", - "| Trotterized Hamiltonian simulation | 119 | Eagle (r3) | 3 unique layers x 9 Trotter steps, 2D heavy-hex topology | 95% | 6.5 hours | 45 min |\n", - "| Kicked Ising | 136 | Heron (r2) | 3 unique layers x 15 steps, 2D heavy-hex topology | 99% | 52 min | 9 min |\n", - "\n", - "Accuracy is measured here relative to the ideal value of the observable: $\\frac{\\langle O \\rangle_{ideal} - \\epsilon}{\\langle O \\rangle_{ideal}}$, where '$\\epsilon$' is the absolute precision of the mitigation (set by the user input), and $\\langle O \\rangle_{ideal}$ is the observable at the noiseless circuit.\n", - "'Runtime usage' measures the usage of the benchmark in batch mode (sum over usage of individual jobs), whereas 'total time' measures usage in session mode (experiment wall time), which includes additional classical and communication times. QESEM is available for execution in both modes, so that users can make the best use of their available resources.\n", + "- The `data` field contains at least an array of expectation values (`PubResult.data.evs`) and an array of standard errors (`PubResult.data.stds`). It can also contain more data, depending on the options used.\n", "\n", - "The 28-qubit Kicked Ising circuits simulate the Discrete Time Quasicrystal studied by Shinjo et al. (see [arXiv 2403.16718](https://arxiv.org/abs/2403.16718) and [Q2B24 Tokyo](https://www.youtube.com/watch?v=tQW6FdLc6zo)) on three connected loops of ibm_kawasaki. The circuit parameters taken here are $(\\theta_x, \\theta_z) = (0.9 \\pi, 0)$, with a ferromagnetic initial state $| \\psi_0 \\rangle = | 0 \\rangle ^{\\otimes n}$. The measured observable is the absolute value of the magnetization $M = |\\frac{1}{28} \\sum_{i=0}^{27} \\langle Z_i \\rangle|$. The utility-scale Kicked Ising experiment was run on the 136 best qubits of ibm_fez; this particular benchmark was run at the Clifford angle $(\\theta_x, \\theta_z) = (\\pi, 0)$, at which the active volume grows slowly with circuit depth, which - together with the high device fidelities - enables high accuracy at a short runtime.\n", + "- The `metadata` field contains PUB-level metadata (`PubResult.metadata`).\n", "\n", - "Trotterized Hamiltonian simulation circuits are for a Transverse-Field Ising model at fractional angles: $(\\theta_{zz}, \\theta_x) = (\\pi / 4, \\pi /8)$ and $(\\theta_{zz}, \\theta_x) = (\\pi / 6, \\pi / 8)$ correspondingly (see [Q2B24 Tokyo](https://www.youtube.com/watch?v=tQW6FdLc6zo)). The utility-scale circuit was run on the 119 best qubits of ibm_brisbane, whereas the 40-qubit experiment was run on the best available chain. The accuracy is reported for the magnetization; high-accuracy results were obtained for higher-weight observables as well.\n", + "The following code snippet describes how to retrieve the QPU time estimation (i.e., `estimate_time_only` is True):" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "48821756", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimated QPU time for this PUB is: \n", + "{'time_estimation_sec': 3600}\n" + ] + } + ], + "source": [ + "print(f'The estimated QPU time for this PUB is: \\n{result[0].metadata}')" + ] + }, + { + "cell_type": "markdown", + "id": "a9e51542", + "metadata": {}, + "source": [ + "The following code snippet describes how to retrieve the mitigation results (i.e., `estimate_time_only` is False)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fda5f739", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The result of the submitted job had 1 PUB\n", + "The expectation values measured from this PUB are: \n", + "[0.98, 1.01]\n", + "The error-bar values are: \n", + "[0.028, 0.015]\n", + "And the associated metadata contains the original observables, making the results easier to interpret: \n", + "{\n", + " 'observables': [\n", + " SparsePauliOp(\n", + " ['IIIIZ', 'IIIZI', 'IIZII', 'IZIII', 'ZIIII'],\n", + " coeffs=[0.2 + 0.0j, 0.2 + 0.0j, 0.2 + 0.0j, 0.2 + 0.0j, 0.2 + 0.0j]\n", + " ),\n", + " SparsePauliOp(\n", + " ['IIIZZ', 'ZIXII'],\n", + " coeffs=[1.0 + 0.0j, 0.5 + 0.0j]\n", + " )\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "print(f'The result of the submitted job had {len(result)} PUB')\n", + "print(f'The expectation values measured from this PUB are: \\n{result[0].data.evs}')\n", + "print(f'The error-bar values are: \\n{result[0].data.stds}')\n", + "print(f'And the associated metadata contains the original observables, making the results easier to interpret: \\n{result[0].metadata}')" + ] + }, + { + "cell_type": "markdown", + "id": "35aed54a", + "metadata": {}, + "source": [ + "## Fetch error messages\n", "\n", - "The VQE circuit was developed together with researchers from the Center for Quantum Technology and Applications at the Deutsches Elektronen-Synchrotron (DESY). The target observable here was a Hamiltonian consisting of a large number of non-commuting Pauli strings, emphasizing QESEM's optimized performance for multi-basis observables. Mitigation was applied to a classically-optimized ansatz; although these results are still unpublished, results of the same quality will be obtained for different circuits with similar structural properties." + "If your workload status is ERROR, use job.result() to fetch the error message to fetch the error message as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d95a3f30", + "metadata": {}, + "outputs": [], + "source": [ + "print(job.result())" ] }, { @@ -312,14 +363,13 @@ "To help us assist you more efficiently, please provide the following information when you contact us:\n", "\n", "- A detailed description of the issue\n", + "- The job ID\n", "- Any relevant error messages or codes\n", - "- Steps to reproduce the issue\n", - "- Your contact information\n", "\n", "\n", - "We are committed to providing you with prompt and effective support to ensure you have the best possible experience with our API.\n", + "We are committed to providing you with prompt and effective support to ensure you have the best possible experience with our Qiskit Function.\n", "\n", - "We are always looking to improve our product and we welcome your suggestions! If you have ideas on how we can enhance our services or features you'd like to see, please send us your thoughts to support@qedma.com" + "We are always looking to improve our product and we welcome your suggestions! If you have ideas on how we can enhance our services or features you'd like to see, please send us your thoughts at support@qedma.com" ] }, { diff --git a/public/api/qiskit-addon-mpf/objects.inv b/public/api/qiskit-addon-mpf/objects.inv index b81cc33c74e..51ccd43abce 100644 Binary files a/public/api/qiskit-addon-mpf/objects.inv and b/public/api/qiskit-addon-mpf/objects.inv differ diff --git a/public/api/qiskit-addon-obp/objects.inv b/public/api/qiskit-addon-obp/objects.inv index 68def90a132..7e24627f394 100644 Binary files a/public/api/qiskit-addon-obp/objects.inv and b/public/api/qiskit-addon-obp/objects.inv differ diff --git a/public/api/qiskit-addon-utils/objects.inv b/public/api/qiskit-addon-utils/objects.inv index f2490ecc096..4a1fdd08628 100644 Binary files a/public/api/qiskit-addon-utils/objects.inv and b/public/api/qiskit-addon-utils/objects.inv differ diff --git a/scripts/config/cspell/dictionaries/qiskit.txt b/scripts/config/cspell/dictionaries/qiskit.txt index 01d40011afa..f673845cdf0 100644 --- a/scripts/config/cspell/dictionaries/qiskit.txt +++ b/scripts/config/cspell/dictionaries/qiskit.txt @@ -111,6 +111,11 @@ fermionic fsim gphase ibmq +IIIIZ +IIIZI +IIZII +IZIII +IIIZZ initialised initialiser ints @@ -199,3 +204,5 @@ unphysical venv watsonx xgate +ZIIII +ZIXII diff --git a/scripts/js/commands/checkInternalLinks.ts b/scripts/js/commands/checkInternalLinks.ts index e17a93aeba7..1badf90ba70 100644 --- a/scripts/js/commands/checkInternalLinks.ts +++ b/scripts/js/commands/checkInternalLinks.ts @@ -26,9 +26,7 @@ const SYNTHETIC_FILES: string[] = [ "docs/errors.mdx", "docs/api/runtime/index.mdx", "docs/api/runtime/tags/jobs.mdx", - "docs/announcements/product-updates/2024-04-15-backend-run-deprecation.mdx", "docs/api/qiskit-transpiler-service-rest/index.mdx", - "docs/announcements/product-updates/2024-09-16-code-assistant.mdx", ]; interface Arguments { @@ -277,8 +275,6 @@ async function determineHistoricalFileBatches( } async function determineQiskitLegacyReleaseNotes(): Promise { - const result: FileBatch[] = []; - const legacyVersions = ( await globby("docs/api/qiskit/release-notes/[!index]*") ) diff --git a/scripts/js/lib/api/updateLinks.test.ts b/scripts/js/lib/api/updateLinks.test.ts index e84bed82872..125715a5af0 100644 --- a/scripts/js/lib/api/updateLinks.test.ts +++ b/scripts/js/lib/api/updateLinks.test.ts @@ -31,6 +31,8 @@ test.describe("updateLinks", () => { [link8](#qiskit_ibm_runtime.RuntimeJob.job) [link9](https://qiskit.org/documentation/apidoc/algorithms.html) [link10](https://qiskit.org/documentation/stubs/qiskit.circuit.BreakLoopOp.html#assemble) +[link11](qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.a_method) +[link12](qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.InlineClass.another_method) `, meta: { apiType: "class", @@ -97,7 +99,9 @@ test.describe("updateLinks", () => { [link7](qiskit_ibm_runtime.RuntimeJob) [link8](#qiskit_ibm_runtime.RuntimeJob.job) [link9](/api/qiskit/algorithms) -[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)\n`, +[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble) +[link11](qiskit_ibm_runtime.RuntimeJob#a_method) +[link12](qiskit_ibm_runtime.RuntimeJob#another_method)\n`, meta: { apiName: "qiskit_ibm_runtime.RuntimeJob", apiType: "class", @@ -149,7 +153,9 @@ test.describe("updateLinks", () => { [link7](runtime-job) [link8](#qiskit_ibm_runtime.RuntimeJob.job) [link9](/api/qiskit/algorithms) -[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)\n`, +[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble) +[link11](runtime-job#a_method) +[link12](runtime-job#another_method)\n`, meta: { apiName: "qiskit_ibm_runtime.RuntimeJob", apiType: "class", diff --git a/scripts/js/lib/api/updateLinks.ts b/scripts/js/lib/api/updateLinks.ts index c63649d64b5..3e09ff27294 100644 --- a/scripts/js/lib/api/updateLinks.ts +++ b/scripts/js/lib/api/updateLinks.ts @@ -92,9 +92,21 @@ export function normalizeUrl( url = normalizedUrlWithoutHash; } + // Rather than linking to the component like `Function` or `Attribute`, we link to the header. + // This is necessary because until we implement https://github.com/Qiskit/documentation/issues/1395, the + // anchor for the component would take you too low in the page, given that the header is above the component. // qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.job -> qiskit_ibm_runtime.RuntimeJob#job + // + // TODO(#2217): Remove this special case and use the full ID instead. if (hash?.startsWith(`${page}.`)) { - const member = removePrefix(hash, `${page}.`); + let member = removePrefix(hash, `${page}.`); + // Also check for inline classes, which often show up on module pages. + // qiskit_addon_obp.utils.truncating#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm + // -> qiskit_addon_obp.utils.truncating#p_norm, whereas without this check + // it would be qiskit_addon_obp.utils.truncating#TruncationErrorBudget.p_norm. + if (member.includes(".")) { + member = member.split(".", 2)[1]; + } url = `${normalizedUrlWithoutHash}#${member}`; } } diff --git a/scripts/js/lib/links/FileBatch.ts b/scripts/js/lib/links/FileBatch.ts index 1a520d0b649..4071220d4ff 100644 --- a/scripts/js/lib/links/FileBatch.ts +++ b/scripts/js/lib/links/FileBatch.ts @@ -15,6 +15,7 @@ import { globby } from "globby"; import { InternalLink, File } from "./InternalLink.js"; import { ALWAYS_IGNORED_URLS, + ALWAYS_IGNORED_URL_PREFIXES, FILES_TO_IGNORES, IGNORED_FILES, } from "./ignores.js"; @@ -115,6 +116,7 @@ export function addLinksToMap( links.forEach((link) => { if ( ALWAYS_IGNORED_URLS.has(link) || + ALWAYS_IGNORED_URL_PREFIXES.some((prefix) => link.startsWith(prefix)) || FILES_TO_IGNORES[filePath]?.includes(link) ) { return; diff --git a/scripts/js/lib/links/ignores.ts b/scripts/js/lib/links/ignores.ts index 670c029ecfb..deb24874ca5 100644 --- a/scripts/js/lib/links/ignores.ts +++ b/scripts/js/lib/links/ignores.ts @@ -76,6 +76,14 @@ export const ALWAYS_IGNORED_URLS = new Set([ ...ALWAYS_IGNORED_URLS__SHOULD_FIX, ]); +// ----------------------------------------------------------------------------------- +// Always ignored URL prefixes - be careful using this +// ----------------------------------------------------------------------------------- + +export const ALWAYS_IGNORED_URL_PREFIXES: string[] = [ + "/announcements/product-updates", +]; + // ----------------------------------------------------------------------------------- // Files to ignores // ----------------------------------------------------------------------------------- @@ -332,14 +340,7 @@ const FILES_TO_IGNORES__EXPECTED: FilesToIgnores = mergeFilesToIgnores( _legacyQiskitSDKIssues(), ); -const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = { - "docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx": [ - "utils-truncating#TruncationErrorBudget.p_norm", - ], - "docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx": [ - "utils-truncating#TruncationErrorBudget.p_norm", - ], -}; +const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = {}; export const FILES_TO_IGNORES: FilesToIgnores = mergeFilesToIgnores( FILES_TO_IGNORES__EXPECTED,