706 lines
88 KiB
Plaintext
706 lines
88 KiB
Plaintext
{
|
||
"cells": [
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "dde95705",
|
||
"metadata": {},
|
||
"source": [
|
||
"# Performance Management: A Qiskit Function by Q-CTRL Fire Opal\n",
|
||
"\n",
|
||
"<Admonition type=\"note\">\n",
|
||
"Qiskit Functions are an experimental feature available only to IBM Quantum™ Premium Plan users. They are in preview release status and subject to change.\n",
|
||
"</Admonition>\n",
|
||
"\n",
|
||
"## Overview\n",
|
||
"\n",
|
||
"Fire Opal Performance Management makes it simple for anyone to achieve meaningful results from quantum computers at scale without needing to be quantum hardware experts. When running circuits with Fire Opal Performance Management, AI-driven error suppression techniques are automatically applied, enabling the scaling of larger problems with more gates and qubits. This approach reduces the number of shots required to reach the correct answer, with no added overhead — resulting in significant savings in both compute time and cost.\n",
|
||
"\n",
|
||
"Performance Management suppresses errors and increases the probability of getting the correct answer on noisy hardware. In other words, it increases the signal-to-noise ratio. The following image shows how increased accuracy enabled by Performance Management can reduce the need for additional shots in the case of a 10-qubit Quantum Fourier Transform algorithm. With only 30 shots, Q-CTRL reaches the 99% confidence threshold, whereas the default (`QiskitRuntime` Sampler, `optimization_level`=3 and `resilience_level`=1, `ibm_sherbrooke`) requires 170,000 shots. By getting the right answer faster, you save significant compute runtime.\n",
|
||
"\n",
|
||
"\n",
|
||
"\n",
|
||
"The Performance Management function can be used with any algorithm, and you can easily use it in place of the standard [Qiskit Runtime primitives](./primitives). Behind the scenes, multiple error suppression techniques work together to prevent errors from happening at runtime. All Fire Opal pipeline methods are pre-configured and algorithm-agnostic, meaning you always get the best performance out of the box.\n",
|
||
"\n",
|
||
"To get access to Performance Management, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "5f761442",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Description\n",
|
||
"\n",
|
||
"Fire Opal Performance Management has two options for execution that are similar to the Qiskit Runtime primitives, so you can easily swap in the Q-CTRL Sampler and Estimator. The general workflow for using the Performance Management function is:\n",
|
||
"1. Define your circuit (and operators in the case of the Estimator).\n",
|
||
"2. Run the circuit.\n",
|
||
"3. Retrieve the results.\n",
|
||
"\n",
|
||
"To reduce hardware noise, Fire Opal employs a range of AI-driven error suppression techniques depicted in the following image. With Fire Opal, the entire pipeline is completely automated with zero need for configuration.\n",
|
||
"\n",
|
||
"Fire Opal's pipeline eliminates the need for additional overhead, such as increased quantum runtime or extra physical qubits. Note that classical processing time remains a factor (refer to the [Benchmarks](#benchmarks) section for estimates, where \"Total time\" reflects both classical and quantum processing). In contrast to error mitigation, which requires overhead in the form of sampling, Fire Opal's error suppression works at both the gate and pulse levels to address various sources of noise and to prevent the likelihood of an error occurring. By preventing errors, the need for expensive post-processing is eliminated.\n",
|
||
"\n",
|
||
"The following image depicts the error suppression methods automated by Fire Opal Performance Management.\n",
|
||
"\n",
|
||
"\n",
|
||
"\n",
|
||
"The function offers two primitives, Sampler and Estimator, and the inputs and outputs of both extend the implemented spec for [Qiskit Runtime V2 primitives](/guides/primitive-input-output)."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "64534d1a",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Benchmarks\n",
|
||
"\n",
|
||
"[Published algorithmic benchmarking](https://journals.aps.org/prapplied/abstract/10.1103/PhysRevApplied.20.024034) results demonstrate significant performance improvement across various algorithms, including Bernstein-Vazirani, quantum Fourier transform, Grover’s search, quantum approximate optimization algorithm, and variational quantum eigensolver. The rest of this section provides more details about types of algorithms you can run, as well as the expected performance and runtimes.\n",
|
||
"\n",
|
||
"The following independent studies demonstrate how Q-CTRL's Performance Management enables algorithmic research at record-breaking scale:\n",
|
||
"- [Parametrized Energy-Efficient Quantum Kernels for Network Service Fault Diagnosis](https://arxiv.org/abs/2405.09724v1) - up to 50-qubit quantum kernel learning\n",
|
||
"- [Tensor-based quantum phase difference estimation for large-scale demonstration](https://arxiv.org/abs/2408.04946) - up to 33-qubit quantum phase estimation\n",
|
||
"- [Hierarchical Learning for Quantum ML: Novel Training Technique for Large-Scale Variational Quantum Circuits](https://arxiv.org/abs/2311.12929) - up to 21-qubit quantum data loading\n",
|
||
"\n",
|
||
"The following table provides a rough guide on accuracy and runtimes from prior benchmarking runs on `ibm_fez`. Performance on other devices may vary. The usage time is based on an assumption of 10,000 shots per circuit. The \"Number of qubits\" indicated is not a hard limitation but represents rough thresholds where you can expect extremely consistent solution accuracy. Larger problem sizes have been successfully solved, and testing beyond these limits is encouraged.\n",
|
||
"\n",
|
||
"\n",
|
||
"| Example | Number of qubits | Accuracy | Measure of accuracy | Total time (s) | Runtime usage (s) | Primitive (Mode) |\n",
|
||
"| --------- | ---------------- | -------------------------- | -------- | ---------- | ------------- |------------- |\n",
|
||
"| Bernstein–Vazirani | 50Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n",
|
||
"| Quantum Fourier Transform | 30Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n",
|
||
"| Quantum Phase Estimation | 30Q | 99.9998% | Accuracy of the angle found: `1- abs(real_angle - angle_found)/pi` | 10 | 8 | Sampler |\n",
|
||
"| Quantum simulation: Ising model (15 steps) | 20Q | 99.775% | $A$ (defined below) | 60 (per step) | 15 (per step) | Estimator |\n",
|
||
"| Quantum simulation 2: molecular dynamics (20 time points) | 34Q | 96.78% | $A_{mean}$ (defined below) | 10 (per time point) | 6 (per time point) | Estimator |\n",
|
||
"\n",
|
||
"Defining the accuracy of the measurement of an expectation value - the metric $A$ is defined as follows:\n",
|
||
"$$\n",
|
||
"A = 1 - \\frac{|\\epsilon^{ideal} - \\epsilon^{meas}|}{\\epsilon^{ideal}_{max} - \\epsilon^{ideal}_{min}},\n",
|
||
"$$\n",
|
||
"where $ \\epsilon^{ideal} $ = ideal expectation value, $ \\epsilon^{meas} $ = measured expectation value, $\\epsilon^{ideal}_{max} $ = ideal maximum value, and $\\epsilon^{ideal}_{min}$ = ideal minimum value. $A_{mean}$ is simply the average of the value of $A$ across multiple measurements.\n",
|
||
"\n",
|
||
"This metric is used because it is invariant to global shifts and scaling in the range of attainable values. In other words, regardless of whether you shift the range of possible expectation values higher or lower or increase the spread, the value of $A$ should remain consistent."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "870af0fe",
|
||
"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": "11af8fb4",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
|
||
"\n",
|
||
"# Credentials\n",
|
||
"token = \"<YOUR_IQP_API_TOKEN>\"\n",
|
||
"hub = \"<YOUR_IQP_HUB>\"\n",
|
||
"group = \"<YOUR_IQP_GROUP>\"\n",
|
||
"project = \"<YOUR_IQP_PROJECT>\"\n",
|
||
"\n",
|
||
"# Authentication\n",
|
||
"catalog = QiskitFunctionsCatalog(token=token)\n",
|
||
"\n",
|
||
"# Access Function\n",
|
||
"perf_mgmt = catalog.load(\"q-ctrl/performance-management\")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "2947b5c3",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Estimator primitive"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "df2788d5",
|
||
"metadata": {},
|
||
"source": [
|
||
"### Estimator example\n",
|
||
"\n",
|
||
"Use Fire Opal Performance Management's Estimator primitive to determine the expectation value of a single circuit-observable pair."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "82932760",
|
||
"metadata": {},
|
||
"source": [
|
||
"In addition to the `qiskit-ibm-catalog` and `qiskit` packages, you will also use the `numpy` package to run this example. You can install this package by uncommenting the following cell if you are running this example in a notebook using the IPython kernel."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "70bb93ef",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# %pip install numpy"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "02b2a79a",
|
||
"metadata": {},
|
||
"source": [
|
||
"**1. Create the circuit**\n",
|
||
"\n",
|
||
"As an example, generate a random Hermitian operator and an observable to input to the Performance Management function."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 28,
|
||
"id": "32037218",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"import numpy as np\n",
|
||
"from qiskit.circuit.library import IQP\n",
|
||
"from qiskit.quantum_info import random_hermitian, SparsePauliOp\n",
|
||
"\n",
|
||
"n_qubits = 50\n",
|
||
"\n",
|
||
"# Generate a random circuit\n",
|
||
"mat = np.real(random_hermitian(n_qubits, seed=1234))\n",
|
||
"circuit = IQP(mat)\n",
|
||
"circuit.measure_all()\n",
|
||
"\n",
|
||
"# Define observables as a string\n",
|
||
"observable = SparsePauliOp(\"Z\" * n_qubits)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 29,
|
||
"id": "476fae6a",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# Create PUB tuple\n",
|
||
"estimator_pubs = [(circuit, observable)]"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "09e64cd7",
|
||
"metadata": {},
|
||
"source": [
|
||
"**2. Run the circuit**\n",
|
||
"\n",
|
||
"Run the circuit and optionally define the backend and number of shots."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 30,
|
||
"id": "26952e1f",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# Choose a backend or remove this option to default to the least busy device\n",
|
||
"backend_name = \"<CHOOSE_A_BACKEND>\"\n",
|
||
"\n",
|
||
"# Run the circuit using the sampler\n",
|
||
"qctrl_estimator_job = perf_mgmt.run(\n",
|
||
" primitive=\"estimator\",\n",
|
||
" pubs=estimator_pubs,\n",
|
||
" instance=hub + \"/\" + group + \"/\" + project,\n",
|
||
" backend_name=backend_name,\n",
|
||
")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "c07af9d0",
|
||
"metadata": {},
|
||
"source": [
|
||
"You can use the familiar [Qiskit Serverless APIs](./serverless) to check your Qiskit Function workload's status:"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 41,
|
||
"id": "2b309861",
|
||
"metadata": {},
|
||
"outputs": [
|
||
{
|
||
"data": {
|
||
"text/plain": [
|
||
"'DONE'"
|
||
]
|
||
},
|
||
"execution_count": 41,
|
||
"metadata": {},
|
||
"output_type": "execute_result"
|
||
}
|
||
],
|
||
"source": [
|
||
"qctrl_estimator_job.status()"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "23556c8e",
|
||
"metadata": {},
|
||
"source": [
|
||
"**3. Retrieve the result**"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 42,
|
||
"id": "8be67088",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# Retrieve the counts from the result list\n",
|
||
"result = qctrl_estimator_job.result()"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "7375fcad",
|
||
"metadata": {},
|
||
"source": [
|
||
"The results have the same format as an [Estimator result](/guides/primitive-input-output#estimator-output):"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": 44,
|
||
"id": "ef85a036",
|
||
"metadata": {},
|
||
"outputs": [
|
||
{
|
||
"name": "stdout",
|
||
"output_type": "stream",
|
||
"text": [
|
||
"The result of the submitted job had 1 PUB and has a value:\n",
|
||
" PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(1,), dtype=float64>), stds=np.ndarray(<shape=(1,), dtype=float64>)), metadata={'precision': None})], metadata={})\n",
|
||
"\n",
|
||
"The associated PubResult of this job has the following DataBins:\n",
|
||
" DataBin(evs=np.ndarray(<shape=(1,), dtype=float64>), stds=np.ndarray(<shape=(1,), dtype=float64>))\n",
|
||
"\n",
|
||
"And this DataBin has attributes: dict_keys(['evs', 'stds'])\n",
|
||
"The expectation values measured from this PUB are: \n",
|
||
"[-0.01464844]\n"
|
||
]
|
||
}
|
||
],
|
||
"source": [
|
||
"print(\n",
|
||
" f\"The result of the submitted job had {len(result)} PUB and has a value:\\n {result}\\n\"\n",
|
||
")\n",
|
||
"print(\n",
|
||
" f\"The associated PubResult of this job has the following DataBins:\\n {result[0].data}\\n\"\n",
|
||
")\n",
|
||
"print(f\"And this DataBin has attributes: {result[0].data.keys()}\")\n",
|
||
"print(\n",
|
||
" f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n",
|
||
")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "20cb6ab1",
|
||
"metadata": {},
|
||
"source": [
|
||
"### Estimator inputs\n",
|
||
"<Admonition type=\"caution\">Fire Opal Performance Management accepts abstract circuits, in contrast to the native Qiskit Runtime primitives, which only accept circuits that are written in the target backend’s Instruction Set Architecture (ISA). For best results, do not transpile circuits before submitting via the Performance Management function. </Admonition>\n",
|
||
"\n",
|
||
"| Name | Type | Description | Required | Default | Example |\n",
|
||
"|------|------|----------|----------|-----------|-----------|\n",
|
||
"| pubs | `QctrlEstimatorPubLike` or `list[QctrlEstimatorPubLike]` | One or more tuples containing the inputs listed under `EstimatorPubLike` components | Yes | N/A | `(circuit, observables, parameter_values)` |\n",
|
||
"| instance | `str` | The hub/group/project to use in that format | No | A Premium access instance is randomly chosen if your account has access to multiple instances | `\"hub1/group1/project1\"` |\n",
|
||
"| backend_name| `str` | The name of the backend | No | The least busy backend that your instance has access to | `\"ibm_fez\"` |\n",
|
||
"| options| `dict` | Input options; see Options section for more details | No | See the Options section for details | `{\"default_shots\": 2048}` |\n",
|
||
"\n",
|
||
"**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/guides/primitive-input-output#estimator-pub)):**\n",
|
||
"- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n",
|
||
"- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n",
|
||
"- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./primitive-input-output#broadcasting-rules) as the `QiskitRuntime` primitives.\n",
|
||
"- (Optional) A target precision for expectation values to estimate.\n",
|
||
"- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": <int>}`.\n",
|
||
"\n",
|
||
"**Supported observables formats:**\n",
|
||
"- Any one of the `ObservablesArrayLike` formats, such as `Pauli`, `SparsePauliOp`, `PauliList`, or `str`\n",
|
||
"- A Pauli string: `\"XY\"`\n",
|
||
"- A dictionary - Pauli strings with coefficients: `{\"XY\": 0.5, \"YZ\": 0.3}`\n",
|
||
"- A list of Pauli strings: `[\"XY\", \"YZ\", \"ZX\"]`\n",
|
||
"- A list of Pauli strings with coefficients: `[(\"XY\", 0.5), (\"YZ\", 0.3)]`\n",
|
||
"- A nested list of Pauli strings: `[[\"XY\", \"YZ\"], [\"ZX\", \"XX\"]]`\n",
|
||
"- A nested list of Pauli strings with coefficients: `[[(\"XY\", 0.1), (\"YZ\", 0.2)], [(\"ZX\", 0.3), (\"XX\", 0.4)]]`\n",
|
||
"\n",
|
||
"**Supported backends:**\n",
|
||
"The following list of backends are currently supported. If your device is not listed, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n",
|
||
"- ibm_brisbane\n",
|
||
"- ibm_brussels\n",
|
||
"- ibm_cleveland\n",
|
||
"- ibm_fez\n",
|
||
"- ibm_kawasaki\n",
|
||
"- ibm_kyiv\n",
|
||
"- ibm_nazca\n",
|
||
"- ibm_quebec\n",
|
||
"- ibm_rensselaer\n",
|
||
"- ibm_sherbrooke\n",
|
||
"- ibm_strasbourg\n",
|
||
"- ibm_torino\n",
|
||
"\n",
|
||
"**Options:**\n",
|
||
"| Name | Type | Description | Default |\n",
|
||
"|--------|----------|-----------------------|---------------------|\n",
|
||
"| session_id | `str` | An existing Qiskit Runtime session ID | `\"cw4r3je6f0t010870y3g\"` |\n",
|
||
"| default_shots | `int` | The number of shots to use for each circuit | `2048` |\n",
|
||
"| default_precision | `float` | The target precision for expectation values to estimate for each circuit | `0.015625` |\n",
|
||
"\n",
|
||
"### Estimator outputs\n",
|
||
"| Name | Type | Description | Example |\n",
|
||
"|--------|---------------------------------|------------------------------------|---------------------|\n",
|
||
"| N/A | `PrimitiveResult` | The [`PrimitiveResult`](/api/qiskit/qiskit.primitives.PrimitiveResult) corresponding to the list of input PUBs | `PubResult(data=DataBin(evs=[0.1234], stds=[0.1]))` |"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "a78ce8bd",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Sampler primitive"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "b1300f06",
|
||
"metadata": {},
|
||
"source": [
|
||
"### Sampler example\n",
|
||
"\n",
|
||
"Use Fire Opal Performance Management's Sampler primitive to run a Bernstein–Vazirani circuit. This algorithm, used to find a hidden string from the outputs of a black box function, is a common benchmarking algorithm because there is a single correct answer."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "144e48f3",
|
||
"metadata": {},
|
||
"source": [
|
||
"**1. Create the circuit**\n",
|
||
"\n",
|
||
"Define the correct answer to the algorithm, the hidden bitstring, and the Bernstein–Vazirani circuit. You can adjust the width of the circuit by simply changing the `circuit_width`."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "2cd807b1",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"import qiskit\n",
|
||
"\n",
|
||
"circuit_width = 35\n",
|
||
"hidden_bitstring = \"1\" * circuit_width\n",
|
||
"\n",
|
||
"# Create circuit, reserving one qubit for BV oracle\n",
|
||
"bv_circuit = qiskit.QuantumCircuit(circuit_width + 1, circuit_width)\n",
|
||
"bv_circuit.x(circuit_width)\n",
|
||
"bv_circuit.h(range(circuit_width + 1))\n",
|
||
"for input_qubit, bit in enumerate(reversed(hidden_bitstring)):\n",
|
||
" if bit == \"1\":\n",
|
||
" bv_circuit.cx(input_qubit, circuit_width)\n",
|
||
"bv_circuit.barrier()\n",
|
||
"bv_circuit.h(range(circuit_width + 1))\n",
|
||
"bv_circuit.barrier()\n",
|
||
"for input_qubit in range(circuit_width):\n",
|
||
" bv_circuit.measure(input_qubit, input_qubit)\n",
|
||
"\n",
|
||
"# Create PUB tuple\n",
|
||
"sampler_pubs = [(bv_circuit,)]"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "85d3c00b",
|
||
"metadata": {},
|
||
"source": [
|
||
"**2. Run the circuit**\n",
|
||
"\n",
|
||
"Run the circuit and optionally define the backend and number of shots."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "2595df84",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# Choose a backend or remove this option to default to the least busy device\n",
|
||
"backend_name = \"<CHOOSE_A_BACKEND>\"\n",
|
||
"\n",
|
||
"# Run the circuit using the sampler\n",
|
||
"qctrl_sampler_job = perf_mgmt.run(\n",
|
||
" primitive=\"sampler\",\n",
|
||
" pubs=sampler_pubs,\n",
|
||
" instance=hub + \"/\" + group + \"/\" + project,\n",
|
||
" backend_name=backend_name,\n",
|
||
")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "3c49fbba",
|
||
"metadata": {},
|
||
"source": [
|
||
"Check your Qiskit Function workload's [status](/guides/functions#check-job-status) or return [results](/guides/functions#retrieve-results) as follows:"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "b7acbb7f",
|
||
"metadata": {},
|
||
"outputs": [
|
||
{
|
||
"name": "stdout",
|
||
"output_type": "stream",
|
||
"text": [
|
||
"DONE\n"
|
||
]
|
||
}
|
||
],
|
||
"source": [
|
||
"qctrl_sampler_job.status()"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "35921605",
|
||
"metadata": {},
|
||
"source": [
|
||
"**3. Retrieve the result**"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "2d4f5f7d",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# Retrieve the job results\n",
|
||
"sampler_result = qctrl_sampler_job.result()"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "302032d7",
|
||
"metadata": {},
|
||
"outputs": [
|
||
{
|
||
"name": "stdout",
|
||
"output_type": "stream",
|
||
"text": [
|
||
"Counts for the meas output register: {'00000000000000000000000000000000001': 3, '00000001111111111111111111111111111': 6, '00111111111111111111111111111111111': 2, '01110111111111111111111111111111111': 1, '01111111111111111111111101111111111': 39, '01111111111111111111111111111110111': 1, '01111111111111111111111111111111111': 73, '10111111111111111111111111111111111': 18, '11101111101111111111111111111110111': 2, '11110111111111111111111111111111111': 37, '11111101011111111111111111111111111': 16, '11111101111111111111111111111111111': 15, '11111111011111111111101111111111111': 6, '11111111011111111111111111011111111': 19, '11111111110111111111111101111111111': 2, '11111111110111111111111111111111111': 24, '11111111111110111111111111111111111': 42, '11111111111111011111111111111111111': 10, '11111111111111110111111111111111111': 15, '11111111111111111011111111111111111': 12, '11111111111111111101111111111101111': 13, '11111111111111111101111111111110111': 7, '11111111111111111101111111111111111': 8, '11111111111111111110111111111111111': 28, '11111111111111111111011111111111111': 36, '11111111111111111111101101110111111': 2, '11111111111111111111110101111111111': 17, '11111111111111111111110111111111111': 39, '11111111111111111111111011111110111': 19, '11111111111111111111111011111111111': 1, '11111111111111111111111100111111111': 6, '11111111111111111111111101011111111': 1, '11111111111111111111111101101111111': 11, '11111111111111111111111101111011111': 5, '11111111111111111111111101111110111': 47, '11111111111111111111111101111111011': 26, '11111111111111111111111101111111111': 244, '11111111111111111111111110111111111': 15, '11111111111111111111111111011111111': 42, '11111111111111111111111111101111111': 2, '11111111111111111111111111110111111': 23, '11111111111111111111111111111011111': 37, '11111111111111111111111111111101111': 22, '11111111111111111111111111111110111': 188, '11111111111111111111111111111111011': 2, '11111111111111111111111111111111101': 24, '11111111111111111111111111111111110': 34, '11111111111111111111111111111111111': 806}\n"
|
||
]
|
||
}
|
||
],
|
||
"source": [
|
||
"# Get results for the first (and only) PUB\n",
|
||
"pub_result = sampler_result[0]\n",
|
||
"counts = pub_result.data.c.get_counts()\n",
|
||
"\n",
|
||
"print(f\"Counts for the meas output register: {counts}\")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "d920922e",
|
||
"metadata": {},
|
||
"source": [
|
||
"**3. Plot the top bitstrings**\n",
|
||
"\n",
|
||
"Plot the bitstring with the highest counts to see if the hidden bitstring was the mode."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "cefa2234",
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"import matplotlib.pyplot as plt\n",
|
||
"\n",
|
||
"\n",
|
||
"def plot_top_bitstrings(counts_dict, hidden_bitstring=None):\n",
|
||
" # Sort and take the top 100 bitstrings\n",
|
||
" top_100 = sorted(counts_dict.items(), key=lambda x: x[1], reverse=True)[\n",
|
||
" :100\n",
|
||
" ]\n",
|
||
" if not top_100:\n",
|
||
" print(\"No bitstrings found in the input dictionary.\")\n",
|
||
" return\n",
|
||
"\n",
|
||
" # Unzip the bitstrings and their counts\n",
|
||
" bitstrings, counts = zip(*top_100)\n",
|
||
"\n",
|
||
" # Assign colors: purple if the bitstring matches hidden_bitstring, otherwise gray\n",
|
||
" colors = [\n",
|
||
" \"#680CE9\" if bit == hidden_bitstring else \"gray\" for bit in bitstrings\n",
|
||
" ]\n",
|
||
"\n",
|
||
" # Create the bar plot\n",
|
||
" plt.figure(figsize=(15, 8))\n",
|
||
" plt.bar(\n",
|
||
" range(len(bitstrings)), counts, tick_label=bitstrings, color=colors\n",
|
||
" )\n",
|
||
"\n",
|
||
" # Rotate the bitstrings for better readability\n",
|
||
" plt.xticks(rotation=90, fontsize=8)\n",
|
||
" plt.xlabel(\"Bitstrings\")\n",
|
||
" plt.ylabel(\"Counts\")\n",
|
||
" plt.title(\"Top 100 Bitstrings by Counts\")\n",
|
||
"\n",
|
||
" # Show the plot\n",
|
||
" plt.tight_layout()\n",
|
||
" plt.show()"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "1d9d3b69",
|
||
"metadata": {},
|
||
"source": [
|
||
"The hidden bitstring is highlighted in purple, and it should be the bitstring with the highest number of counts."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"id": "0f463b7e",
|
||
"metadata": {},
|
||
"outputs": [
|
||
{
|
||
"data": {
|
||
"image/png": "iVBORw0KGgoAAAANSUhEUgAABdEAAAMWCAYAAAAeaM88AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjkuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8hTgPZAAAACXBIWXMAAA9hAAAPYQGoP6dpAACrP0lEQVR4nOzdfZxWdZ0//jcDirczOMqNs8wIhDADamxWOkAlRLJGkRu0a19KmCzRhSgtI5e8zXLX2pTaFGtbBmz81ld2u7PNMjDzCyTebGVS09RYQ6MgYTDqrqAz5/fH/ry+jczhZri4rrnOPJ+PxzxqzufM9fp8zvnM8VxvrvmcAUmSJAEAAAAAAOylrNgdAAAAAACAvkoRHQAAAAAAUiiiAwAAAABACkV0AAAAAABIoYgOAAAAAAApFNEBAAAAACCFIjoAAAAAAKRQRAcAAAAAgBSK6AAAAAAAkEIRHQAACmzUqFGxYMGCovZhwYIFMWrUqKL2Ic3vfve7GDBgQHz2s58tdlcAAEARHQCAAzNgwIAD+vrRj3502Pty2223xbve9a6oqamJAQMG7LMgvXPnzrj44otj6NChceyxx8a0adPi0Ucf7XHfb3/72/Ga17wmjjrqqKipqYlrrrkmXnrppf3250c/+tFex6GysjLOPvvsaGpq2u/Pb968Oa699tr43e9+t999X+m//uu/4tprry3Icc+q3/72t7Fw4cIYM2ZMHHXUUVFeXh5TpkyJ5cuXx3//938Xu3sREXHrrbdGY2NjsbsBANAvDSp2BwAAKA133HFHt+9Xr14d9957717b6+rqDntf/vEf/zGeffbZeP3rXx9PPfVU6n5dXV0xa9as+NnPfhZXXHFFnHTSSXHrrbfGOeecE4888kiceuqpuX2/973vxfnnnx/nnHNOfOELX4jHHnssbrjhhnj66afjtttuO6B+LVmyJF73utdFRMSOHTvi61//erznPe+JnTt3xqJFi3L7NTc3R1nZ//s8y+bNm+O6666Lc84556A/Hf5f//Vfcd1110VExDnnnHPAP/flL385urq6Diori7773e/Gu971rhg8eHBceOGFcdppp8WePXvi//7f/xtXXHFFPP744/GlL32p2N2MW2+9NU466aSi/wUDAEB/pIgOAMABec973tPt+5/85Cdx77337rW9EO6///7cp9CPO+641P3WrFkTGzZsiLvuuivmzp0bERF/8zd/E+PGjYtrrrkm7rzzzty+H/3oR+OMM86IH/zgBzFo0P/cJpeXl8enP/3p+NCHPhS1tbX77dcb3vCGXE5ExKWXXhpjxoyJO++8s1sRffDgwQc95nx5/vnn49hjj40jjjiiaH3oK5544om44IIL4pRTTol169bFySefnGtbtGhR/OY3v4nvfve7RewhAAB9geVcAADIm+effz4+8pGPRHV1dQwePDjGjx8fn/3sZyNJkm77DRgwIBYvXhxNTU0xfvz4OOqoo+LMM8+MH//4xweUc8opp8SAAQP2u9+aNWti+PDh8c53vjO3bejQofE3f/M38a1vfSt2794dEf/zSfDNmzfHxRdfnCugR0T83d/9XSRJEmvWrDmgfr3SkUceGSeccEK314zoviZ6Y2NjvOtd74qIiGnTpu21LM7DDz8cM2fOjJNOOimOPvroGD16dLzvfe+LiP9ZO3zo0KEREXHdddflfvbaa6+NiP9Z9/y4446L3/72t/HWt741jj/++Jg3b16u7c8/9f7n65B/6Utfile96lUxePDgeN3rXhcPPfTQXmO76667YsKECXHUUUfFaaedFt/4xjd6XGf9a1/7Wpx55plx/PHHR3l5eZx++umxfPnyAz6GN998c5xyyilx9NFHx5ve9Kb4xS9+kWtbuXJlDBgwIP7zP/9zr5/79Kc/HQMHDoz29vbU177pppviueeei6985SvdCugvGzt2bHzoQx/Kff/SSy/FJz/5ydyxGTVqVPz93/99bh697M/PwZ975Vr4jY2NMWDAgFi/fn1cfvnluSWH/vqv/zq2b9/e7ecef/zxuP/++3Pn+OW/OnjxxRfjuuuui1NPPTWOOuqoOPHEE2Pq1Klx7733po4bAICD45PoAADkRZIkMXv27LjvvvvioosuikmTJsX3v//9uOKKK6K9vT1uvvnmbvvff//98fWvfz2WLFkSgwcPjltvvTX+6q/+KjZt2hSnnXZaXvr0n//5n/Ga17ym29IpERGvf/3r40tf+lL8+te/jtNPPz1XhH3ta1/bbb+qqqoYOXJkj0Xanjz77LPxxz/+MSIinnnmmbjzzjvjF7/4RXzlK19J/Zk3vvGNsWTJkvj85z8ff//3f59bDqeuri6efvrpOPfcc2Po0KHx8Y9/PIYMGRK/+93v4t///d8j4n/+QeC2226LSy+9NP76r/86948FZ5xxRu71X3rppZg5c2ZMnTo1PvvZz8YxxxyzzzHceeed8eyzz8bChQtjwIABcdNNN8U73/nOaG1tzX16/bvf/W787d/+bZx++ulx4403xp/+9Ke46KKL4i/+4i+6vda9994b7373u+PNb35z/OM//mNERPzyl7+M9evXdytOp1m9enU8++yzsWjRonjhhRdi+fLlMX369Hjsscdi+PDhMXfu3Fi0aFE0NTXFX/7lX3b72aampjjnnHP26tOf+853vhNjxoyJyZMn77cvERHvf//7Y9WqVTF37tz4yEc+Eg8++GDceOON8ctf/jK+8Y1vHNBr9OSDH/xgnHDCCXHNNdfE7373u7jlllti8eLF8fWvfz0iIm655Zb44Ac/GMcdd1wsW7YsIiKGDx8eERHXXntt3HjjjfH+978/Xv/610dHR0c8/PDD8eijj8Zb3vKWXvcJAIA/kwAAQC8sWrQo+fPbyW9+85tJRCQ33HBDt/3mzp2bDBgwIPnNb36T2xYRSUQkDz/8cG7b73//++Soo45K/vqv//qg+nHssccm8+fPT2173/vet9f27373u0lEJPfcc0+SJEnymc98JomIpK2tba99X/e61yVnn332Pvtw33335cb0519lZWXJpz71qb32P+WUU7r1+a677koiIrnvvvu67feNb3wjiYjkoYceSs3evn17EhHJNddcs1fb/Pnzk4hIPv7xj/fYdsopp+S+f+KJJ5KISE488cTkmWeeyW3/1re+lURE8p3vfCe37fTTT09GjhyZPPvss7ltP/rRj5KI6PaaH/rQh5Ly8vLkpZdeSu1/T17uy9FHH5384Q9/yG1/8MEHk4hILrvssty2d7/73UlVVVXS2dmZ2/boo48mEZGsXLkyNWPXrl1JRCTveMc7DqhPP/3pT5OISN7//vd32/7Rj340iYhk3bp1uW1p5+OV533lypVJRCQzZsxIurq6ctsvu+yyZODAgcnOnTtz2yZOnJi86U1v2us1X/3qVyezZs06oDEAANA7lnMBACAv/uM//iMGDhwYS5Ys6bb9Ix/5SCRJEt/73ve6ba+vr48zzzwz931NTU284x3viO9///vR2dmZlz7993//d4/rjx911FG59j//37R9X27fn6uvvjruvffeuPfee+PrX/96vPvd745ly5Yd1PIlf27IkCEREXH33XfHiy++2KvXiPiftdkP1N/+7d/GCSeckPv+DW94Q0REtLa2RkTEk08+GY899lhceOGF3dajf9Ob3hSnn356t9caMmRIPP/8871eWuT888/v9kny17/+9XHWWWfFf/zHf+S2XXjhhfHkk0/Gfffdl9vW1NQURx99dMyZMyf1tTs6OiIi4vjjjz+gvrycefnll3fb/pGPfCQi4pDWTr/44ou7LU/0hje8ITo7O+P3v//9fn92yJAh8fjjj0dLS0uv8wEA2DdFdAAA8uL3v/99VFVV7VWUfHl5klcWBE899dS9XmPcuHHxX//1X93Wgz4URx999F7rVUdEvPDCC7n2P//ftH1fbt+f008/PWbMmBEzZsyIv/mbv4mvfvWr8ba3vS0+/vGP92pMb3rTm2LOnDlx3XXXxUknnRTveMc7YuXKlT32M82gQYNi5MiRB7x/TU1Nt+9fLqj/6U9/ioj/dx7Hjh2718++ctvf/d3fxbhx4+K8886LkSNHxvve97645557DrgvaXPkd7/7Xe77t7zlLXHyySdHU1NTRER0dXXF//7f/zve8Y537LNAXl5eHhH/swTPgfj9738fZWVle41xxIgRMWTIkAMqeKfZ3zHfl+uvvz527twZ48aNi9NPPz2uuOKK+PnPf97rvgAAsDdFdAAAMuvkk0+Op556aq/tL2+rqqrK7ffn21+578v79cab3/zmeOGFF2LTpk0H/bMDBgyINWvWxMaNG2Px4sXR3t4e73vf++LMM8+M55577oBeY/DgwXutCb8vAwcO7HF78oqHwx6IYcOGxU9/+tP49re/nVsv/7zzzov58+cf9GulGThwYPyv//W/4t/+7d/ihRdeiPvuuy+efPLJeM973rPPnysvL4+qqqpuDyo9EAfyQNs0aX9hcSjH/I1vfGP89re/jX/913+N0047Lf7lX/4lXvOa18S//Mu/9LqfAAB0p4gOAEBenHLKKfHkk0/u9cneX/3qV7n2P9fT8hO//vWv45hjjomhQ4fmpU+TJk2KRx99NLq6urptf/DBB+OYY46JcePG5faLiHj44Ye77ffkk0/GH/7wh1x7b7z00ksREfsseu+vMHv22WfHpz71qXj44YejqakpHn/88fja1752QD+bby+fx9/85jd7tfW07cgjj4y3v/3tceutt8Zvf/vbWLhwYaxevbrHfV8pbY6MGjWq27YLL7wwOjo64jvf+U40NTXF0KFDY+bMmft9/be97W3x29/+NjZu3LjffU855ZTo6uraq0/btm2LnTt3dpvfJ5xwQuzcubPbfnv27OnxH2kO1L7Oc2VlZTQ0NMT//t//O7Zs2RJnnHFGXHvttb3OAgCgO0V0AADy4q1vfWt0dnbGP//zP3fbfvPNN8eAAQPivPPO67Z948aN8eijj+a+37JlS3zrW9+Kc889N/WTuQdr7ty5sW3btvj3f//33LY//vGPcdddd8Xb3/723BroEydOjNra2vjSl77U7dPCt912WwwYMCDmzp3b6z7cfffdERHx6le/OnWfY489NiJir8Lrn/70p70+jfxyQf/lJV2OOeaYHn/2cKmqqorTTjstVq9e3e0fBu6///547LHHuu27Y8eObt+XlZXFGWecERE9L53zSt/85jejvb099/2mTZviwQcf3GsunXHGGXHGGWfEv/zLv8S//du/xQUXXBCDBg3a7+t/7GMfi2OPPTbe//73x7Zt2/Zq/+1vf5tbz/6tb31rRETccsst3fb53Oc+FxERs2bNym171ateFT/+8Y+77ffKuXWwjj322B7P8SuP8XHHHRdjx449qCV/AADYt/3fWQIAwAF4+9vfHtOmTYtly5bF7373u3j1q18dP/jBD+Jb3/pWfPjDH45XvepV3fY/7bTTYubMmbFkyZIYPHhw3HrrrRERcd111+036zvf+U787Gc/i4iIF198MX7+85/HDTfcEBERs2fPzhVq586dG2effXY0NDTE5s2b46STTopbb701Ojs798r5zGc+E7Nnz45zzz03LrjggvjFL34R//zP/xzvf//7c+u6788DDzyQW2/9mWeeiW9/+9tx//33xwUXXBC1tbWpPzdp0qQYOHBg/OM//mPs2rUrBg8eHNOnT48777wzbr311vjrv/7reNWrXhXPPvtsfPnLX47y8vJcUffoo4+OCRMmxNe//vUYN25cVFZWxmmnnRannXbaAfW5Nz796U/HO97xjpgyZUo0NDTEn/70p/jnf/7nOO2007oV1t///vfHM888E9OnT4+RI0fG73//+/jCF74QkyZNOqBjOnbs2Jg6dWpceumlsXv37rjlllvixBNPjI997GN77XvhhRfGRz/60YiI/S7l8rJXvepVceedd8bf/u3f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AAAApChqEX3UqFExYMCAvb4WLVoUEREvvPBCLFq0KE488cQ47rjjYs6cObFt27Zur9HW1hazZs2KY445JoYNGxZXXHFFvPTSS8UYDgAAAAAAGVPUIvpDDz0UTz31VO7r3nvvjYiId73rXRERcdlll8V3vvOduOuuu+L++++PJ598Mt75znfmfr6zszNmzZoVe/bsiQ0bNsSqVauisbExrr766qKMBwAAAACAbBmQJElS7E687MMf/nDcfffd0dLSEh0dHTF06NC48847Y+7cuRER8atf/Srq6upi48aNcfbZZ8f3vve9eNvb3hZPPvlkDB8+PCIiVqxYEUuXLo3t27fHkUceeUC5HR0dUVFREbt27Yry8vLDNr6+7NLjn877a9727LC8vyYAAAAAQD4caF24z6yJvmfPnvjqV78a73vf+2LAgAHxyCOPxIsvvhgzZszI7VNbWxs1NTWxcePGiIjYuHFjnH766bkCekTEzJkzo6OjIx5//PHUrN27d0dHR0e3LwAAAAAAeKU+U0T/5je/GTt37owFCxZERMTWrVvjyCOPjCFDhnTbb/jw4bF169bcPn9eQH+5/eW2NDfeeGNUVFTkvqqrq/M3EAAAAAAAMqPPFNG/8pWvxHnnnRdVVVWHPevKK6+MXbt25b62bNly2DMBAAAAACg9g4rdgYiI3//+9/HDH/4w/v3f/z23bcSIEbFnz57YuXNnt0+jb9u2LUaMGJHbZ9OmTd1ea9u2bbm2NIMHD47BgwfncQQAAAAAAGRRn/gk+sqVK2PYsGExa9as3LYzzzwzjjjiiFi7dm1uW3Nzc7S1tUV9fX1ERNTX18djjz0WTz/9/x6Kee+990Z5eXlMmDChcAMAAAAAACCTiv5J9K6urli5cmXMnz8/Bg36f92pqKiIiy66KC6//PKorKyM8vLy+OAHPxj19fVx9tlnR0TEueeeGxMmTIj3vve9cdNNN8XWrVvjE5/4RCxatMgnzQEAAAAAOGRFL6L/8Ic/jLa2tnjf+963V9vNN98cZWVlMWfOnNi9e3fMnDkzbr311lz7wIED4+67745LL7006uvr49hjj4358+fH9ddfX8ghAAAAAACQUQOSJEmK3Yli6+joiIqKiti1a1eUl5cXuztFcenxT+9/p4N027PD8v6aAAAAAAD5cKB14T6xJjoAAAAAAPRFiugAAAAA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AAAAAIAUiugAAAAAAJBCER0AAAAAAFIoogMAAAAAQApFdAAAAAAASKGIDgAAAAAAKRTRAQAAAAAghSI6AAAAAACkUEQHAAAAAIAUvSqiP/roo/HYY4/lvv/Wt74V559/fvz93/997NmzJ2+dAwAAAACAYupVEX3hwoXx61//OiIiWltb44ILLohjjjkm7rrrrvjYxz6W1w4CAAAAAECx9KqI/utf/zomTZoUERF33XVXvPGNb4w777wzGhsb49/+7d/y2T8AAAAAACiaXhXRkySJrq6uiIj44Q9/GG9961sjIqK6ujr++Mc/5q93AAAAAABQRL0qor/2ta+NG264Ie644464//77Y9asWRER8cQTT8Tw4cPz2kEAAAAAACiWXhXRb7755nj00Udj8eLFsWzZshg7dmxERKxZsyYmT56c1w4CAAAAAECxDOrND7361a+Oxx57bK/tn/nMZ2LQoF69JAAAAAAA9Dm9+iT6mDFjYseOHXttf+GFF2LcuHGH3CkAAAAAAOgLelVE/93vfhednZ17bd+9e3f84Q9/OOROAQAAAABAX3BQa698+9vfzv3/73//+1FRUZH7vrOzM9auXRujR4/OX+8AAAAAAKCIDqqIfv7550dExIABA2L+/Pnd2o444ogYNWpU/NM//VPeOgcAAAAAAMV0UEX0rq6uiIgYPXp0PPTQQ3HSSScdlk4BAAAAAEBfcFBF9Jc98cQT+e4HAAAAAAD0Ob0qokdErF27NtauXRtPP/107hPqL/vXf/3XQ+4YAAAAAAAUW6+K6Nddd11cf/318drXvjZOPvnkGDBgQL77BQAAAAAARderIvqKFSuisbEx3vve9+a7PwAAAAAA0GeU9eaH9uzZE5MnT853XwAAAAAAoE/pVRH9/e9/f9x555357gsAAAAAAPQpvVrO5YUXXogvfelL8cMf/jDOOOOMOOKII7q1f+5zn8tL5wAAAAAAoJh6VUT/+c9/HpMmTYqIiF/84hfd2jxkFAAAAACArOhVEf2+++7Ldz8AAAAAAKDP6dWa6AAAAAAA0B/06pPo06ZN2+eyLevWret1hwAAAAAAoK/oVRH95fXQX/biiy/GT3/60/jFL34R8+fPz0e/AAAAAACg6HpVRL/55pt73H7ttdfGc889d0gdAgAAAACAviKva6K/5z3viX/913/N50sCAAAAAEDR5LWIvnHjxjjqqKPy+ZIAAAAAAFA0vVrO5Z3vfGe375MkiaeeeioefvjhuOqqq/LSMQAAAAAAKLZeFdErKiq6fV9WVhbjx4+P66+/Ps4999y8dAwAAAAAAIqtV0X0lStX5rsfAAAAAADQ5xzSmuiPPPJIfPWrX42vfvWr8Z//+Z+H1JF/+Id/iAEDBsSHP/zh3LYXXnghFi1aFCeeeGIcd9xxMWfOnNi2bVu3n2tra4tZs2bFMcccE8OGDYsrrrgiXnrppUPqCwAAAAAARPTyk+hPP/10XHDBBfGjH/0ohgwZEhERO3fujGnTpsXXvva1GDp06EG93kMPPRS33357nHHGGd22X3bZZfHd73437rrrrqioqIjFixfHO9/5zli/fn1ERHR2dsasWbNixIgRsWHDhnjqqafiwgsvjCOOOCI+/elP92ZoAAAAAACQ06tPon/wgx+MZ599Nh5//PF45pln4plnnolf/OIX0dHREUuWLDmo13ruuedi3rx58eUvfzlOOOGE3PZdu3bFV77ylfjc5z4X06dPjzPPPDNWrlwZGzZsiJ/85CcREfGDH/wgNm/eHF/96ldj0qRJcd5558UnP/nJ+OIXvxh79uzpzdAAAAAAACCnV0X0e+65J2699daoq6vLbZswYUJ88YtfjO9973sH9VqLFi2KWbNmxYwZM7ptf+SRR+LFF1/str22tjZqampi48aNERGxcePGOP3002P48OG5fWbOnBkdHR3x+OOP92ZoAAAAAACQ06vlXLq6uuKII47Ya/sRRxwRXV1dB/w6X/va1+LRRx+Nhx56aK+2rVu3xpFHHplbLuZlw4cPj61bt+b2+fMC+svtL7el2b17d+zevTv3fUdHxwH3GQAAAACA/qNXn0SfPn16fOhDH4onn3wyt629vT0uu+yyePOb33xAr7Fly5b40Ic+FE1NTXHUUUf1phu9duONN0ZFRUXuq7q6uqD5AAAAAACUhl4V0f/5n/85Ojo6YtSoUfGqV70qXvWqV8Xo0aOjo6MjvvCFLxzQazzyyCPx9NNPx2te85oYNGhQDBo0KO6///74/Oc/H4MGDYrhw4fHnj17YufOnd1+btu2bTFixIiIiBgxYkRs27Ztr/aX29JceeWVsWvXrtzXli1bDmL0AAAAAAD0F71azqW6ujoeffTR+OEPfxi/+tWvIiKirq5ur3XN9+XNb35zPPbYY922NTQ0RG1tbSxdujSqq6vjiCOOiLVr18acOXMiIqK5uTna2tqivr4+IiLq6+vjU5/6VDz99NMxbNiwiIi49957o7y8PCZMmJCaPXjw4Bg8ePBBjRkAAAAAgP7noIro69ati8WLF8dPfvKTKC8vj7e85S3xlre8JSIidu3aFRMnTowVK1bEG97whv2+1vHHHx+nnXZat23HHntsnHjiibntF110UVx++eVRWVkZ5eXl8cEPfjDq6+vj7LPPjoiIc889NyZMmBDvfe9746abboqtW7fGJz7xiVi0aJEiOQAAAAAAh+yglnO55ZZb4gMf+ECUl5fv1VZRURELFy6Mz33uc3nr3M033xxve9vbYs6cOfHGN74xRowYEf/+7/+eax84cGDcfffdMXDgwKivr4/3vOc9ceGFF8b111+ftz4AAAAAANB/DUiSJDnQnU855ZS45557oq6ursf2X/3qV3HuuedGW1tb3jpYCB0dHVFRURG7du3q8R8I+oNLj386769527PD8v6aAAAAAAD5cKB14YP6JPq2bdviiCOOSG0fNGhQbN++/WBeEgAAAAAA+qyDKqL/xV/8RfziF79Ibf/5z38eJ5988iF3CgAAAAAA+oKDKqK/9a1vjauuuipeeOGFvdr++7//O6655pp429velrfOAQAAAABAMR3Umujbtm2L17zmNTFw4MBYvHhxjB8/PiL+Zy30L37xi9HZ2RmPPvpoDB8+/LB1+HCwJro10QEAAACA/uVA68KDDuZFhw8fHhs2bIhLL700rrzyyni5/j5gwICYOXNmfPGLXyy5AjoAAAAAAKQ5qCJ6RMQpp5wS//Ef/xF/+tOf4je/+U0kSRKnnnpqnHDCCYejfwAAAAAAUDQHXUR/2QknnBCve93r8tkXAAAAAADoUw7qwaIAAAAAANCfKKIDAAAAAEAKRXQAAAAAAEihiA4AAAAAACkU0QEAAAAAIIUiOgAAAAAApFBEBwAAAACAFIroAAAAAACQQhEdAAAAAABSKKIDAAAAAEAKRXQAAAAAAEihiA4AAAAAACkU0QEAAAAAIIUiOgAAAAAApFBEBwAAAACAFIroAAAAAACQQhEdAAAAAABSKKIDAAAAAEAKRXQAAAAAAEihiA4AAAAAACkU0QEAAAAAIIUiOgAAAAAApFBEBwAAAACAFIroAAAA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xzo+Ptb29rZu376tZ555RpL0yCOP6KmnntLt27dbfh7f/va39dhjj+nJJ59seQsAAACIAm6iAwAAAG3ge77ne/TUU0/pqaee0vDwsD760Y/q6OhIJycnDz3O5atf/arGx8clSW94wxt069Ytzc3NSZK2trb0tre9TY899pieeOIJvfe979VLL72kj33sY1pfX9ff/u3fXv60+wsvvHD53/sXf/EX+tEf/VE9+uijKhaLVx7n8rGPfUzDw8Pa3NxUT0+Pksmkfu7nfk7f+MY3Lv/MN77xDc3Ozup1r3ud7ty5oz/8wz/Uu9/9bn3kIx+5/DN/8id/ore85S169NFH9aY3vUkzMzM2phYAAAB4VbiJDgAAALSZb37zm/qzP/sz9ff364knnnjomOd5+su//EtJUqlU0vHxsZaXl3V8fKyf//mf1y/8wi/oy1/+sl544QU9++yzMsbo13/91/UzP/MzD/20++jo6OV/50c/+lH96q/+qr785S/rfe97X91z+spXvqK/+Zu/0fPPP6/nn39e//RP/6Tf/d3fvTz+a7/2a9rb29Pf/d3f6XOf+5x2d3f1hS984fL4v/zLv2hxcVGf+MQnVCqV9NnPflbvete7gpw2AAAAoCVa//ugAAAAAG70/PPP63u/93slSS+99JLu3Lmj559/XonEwz/38sgjj6ijo0OS9OSTT17+xPhXvvIV/e///q+effZZPf3005Kkt73tbZf/3mOPPaZvfetbeuqpp660P/KRj+jZZ59teH4XFxcqFAp6/PHHJUkf+tCHtL29rd/5nd/RN77xDa2vr+vP//zP9Z73vEeStLa2pq6urst/v1Kp6HWve52eeeYZPf7443r66af1Az/wA69kigAAAIBQ8JPoAAAAQBsYHx/Xl770JX3pS1/SwcGB3ve+9+kDH/iA/v3f//1l/ftvf/vb9Z73vEdve9vb9NM//dP61Kc+pa997Wsv6999xzveceOf6enpubyBLkl37tzRf/3Xf0mSyuWyvv3tb+vu3buXx5PJpAYHBy//84/92I/p6aefVl9fnz70oQ+pWCzqv//7v1/W+QEAAABh4iY6AAAA0AZe97rXqb+/X/39/XrnO9+pP/3TP9VLL72kT33qUy/r33/kkUf0uc99Tv/wD/+gt771rfqjP/ojDQ4O6t/+7d9eVvsmr3nNax76z7du3dLFxcXLOjdJevzxx/WFL3xBn/70p3Xnzh391m/9lt7+9rfr7OzsZf93AAAAAGHgJjoAAADQhm7duqVEIqH/+Z//uXLsta99rSSpVqtd+Xey2aw+/vGP64tf/KJe+9rX6q//+q8v/53//58PSl9fn17zmtfo85///OVrX//61/XgwYOH/tzt27f13ve+V7/3e7+n+/fv66tf/ap2dnZack4AAABAUHgmOgAAANAGvvWtb+k///M/JUlf+9rX9Md//Mf65je/qZ/4iZ+48meffvpp3bp1S88//7w++MEP6rHHHtOLL76o7e1t/fiP/7iefPJJ3bt3TycnJ8pkMpK+8ziWf/zHf1SpVNITTzyhZDIZ2Lk//vjj+vCHP6zf+I3fUEdHh5588kn99m//thKJhG7duiXpO898L5fLete73qU3vOEN+vu//3tdXFw89MgXAAAAoB3xk+gAAABAG/jsZz+rO3fu6M6dO/rhH/5hff7zn9dnPvMZvfvd777yZ9/85jfr4x//uD760Y/qTW96k375l39Z3/d936d//ud/1gc/+EENDAzoN3/zN/XJT35SH/jAByRJv/RLv6TBwUG94x3vUGdnp/b29gI9/z/4gz/QyMiInnnmGb33ve9VNptVJpPRo48+Kkl6/etfr7/6q7/SxMSEMpmMVlZW9OlPf1pDQ0OBngcAAAAQtFvGGBP2SQAAAABwy0svvaQ3v/nN+uQnP6lf/MVfDPt0AAAAgKbxOBcAAAAAr9oXv/hF/eu//qvu3r2rr3/96/rEJz4hSfrJn/zJkM8MAAAAeHW4iQ4AAAAgEL//+7+vUqmk1772tfqhH/oh7e7u6o1vfGPYpwUAAAC8KjzOBQAAAAAAAACAa/DFogAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXIOb6AAAAAAAAAAAXOP/AapDGsmwADvzAAAAAElFTkSuQmCC",
|
||
"text/plain": [
|
||
"<Figure size 1500x800 with 1 Axes>"
|
||
]
|
||
},
|
||
"metadata": {},
|
||
"output_type": "display_data"
|
||
}
|
||
],
|
||
"source": [
|
||
"plot_top_bitstrings(counts, hidden_bitstring)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "773466d6",
|
||
"metadata": {},
|
||
"source": [
|
||
"### Sampler inputs\n",
|
||
"<Admonition type=\"caution\">Fire Opal Performance Management accepts abstract circuits, in contrast to the native Qiskit Runtime primitives, which only accept circuits that are written in the target backend’s Instruction Set Architecture (ISA). For best results, do not transpile circuits before submitting via the Performance Management function. </Admonition>\n",
|
||
"\n",
|
||
"| Name | Type | Description | Required | Default | Example |\n",
|
||
"|------------|---------------|------------------|----------|----------|--------------------|\n",
|
||
"| pubs | `QctrlSamplerPubLike` or `list[QctrlSamplerPubLike]` | One or more tuples containing the inputs listed under `SamplerPubLike` components | Yes | N/A | `(circuit, parameter_values)` |\n",
|
||
"| instance | `str` | The hub/group/project to use in that format | No | A Premium access instance is randomly chosen if your account has access to multiple instances | `\"hub1/group1/project1\"` |\n",
|
||
"| backend_name| `str` | The name of the backend | No | The least busy backend that your instance has access to | `\"ibm_fez\"` |\n",
|
||
"| options| `dict` | Input options; see Options section for more details | No | See the Options section for details | `{\"default_shots\": 2048}` |\n",
|
||
"\n",
|
||
"**`QctrlSamplerPubLike` components (derived from the [Qiskit Runtime PUB definition](/guides/primitive-input-output#sampler-pub)):**\n",
|
||
"- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n",
|
||
"- (Optional) A collection of parameter values to bind the circuit against.\n",
|
||
"- (Optional) An integer representing the shot count, or a dictionary of runtime options containing the shot count. For example: `(circ, None, 123)` or `(circ, None, {\"shots\": 123})`.\n",
|
||
"\n",
|
||
"**Supported backends:**\n",
|
||
"The following list of backends are currently supported. If your device is not listed, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n",
|
||
"- ibm_brisbane\n",
|
||
"- ibm_brussels\n",
|
||
"- ibm_cleveland\n",
|
||
"- ibm_fez\n",
|
||
"- ibm_kawasaki\n",
|
||
"- ibm_kyiv\n",
|
||
"- ibm_nazca\n",
|
||
"- ibm_quebec\n",
|
||
"- ibm_rensselaer\n",
|
||
"- ibm_sherbrooke\n",
|
||
"- ibm_strasbourg\n",
|
||
"- ibm_torino\n",
|
||
"\n",
|
||
"**Options:**\n",
|
||
"| Name | Type | Description | Default |\n",
|
||
"|--------|----------|-----------------------|---------------------|\n",
|
||
"| session_id | `str` | An existing Qiskit Runtime session ID | `\"cw4r3je6f0t010870y3g\"` |\n",
|
||
"| default_shots | `int` | The number of shots to use for each circuit | `2048` |\n",
|
||
"\n",
|
||
"### Sampler outputs\n",
|
||
"| Name | Type | Description | Example |\n",
|
||
"|--------|----------------------------------------|-------------------------------------------------------------------------------------------|---------------------------------|\n",
|
||
"| N/A | `PrimitiveResult` | The [`PrimitiveResult`](/api/qiskit/qiskit.primitives.PrimitiveResult) corresponding to the list of input PUBs | `PrimitiveResult([PubResult(data=DataBin(c=BitArray(<shape=(), num_shots=2048, num_bits=35>)), metadata={'shots': 2048})], metadata={})` |"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "bb33258d",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Get support\n",
|
||
"\n",
|
||
"For any questions or issues, [contact Q-CTRL](https://form.typeform.com/to/iuujEAEI)."
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"id": "2fe4a6ea",
|
||
"metadata": {},
|
||
"source": [
|
||
"## Next steps\n",
|
||
"\n",
|
||
"<Admonition type=\"tip\" title=\"Recommendations\">\n",
|
||
"\n",
|
||
"- Request access to [Q-CTRL Performance Management](https://quantum.ibm.com/functions?id=c750648c-ba44-4137-8c34-4140a3aaa7a9)\n",
|
||
"\n",
|
||
"</Admonition>"
|
||
]
|
||
}
|
||
],
|
||
"metadata": {
|
||
"description": "Apply automated error suppression using Fire Opal Performance Management by Q-CTRL",
|
||
"kernelspec": {
|
||
"display_name": "Python 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",
|
||
"version": "3"
|
||
},
|
||
"title": "Performance Management - A Qiskit Function by Q-CTRL Fire Opal"
|
||
},
|
||
"nbformat": 4,
|
||
"nbformat_minor": 5
|
||
}
|