From be8407d37da23dcfc58a13510679ed9fa480ee98 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 10 Jul 2024 13:43:45 -0500 Subject: [PATCH] Initial changes for Mode (#1598) closes #1542 Frank did a lot of the code changes already (#1580 ), but the migration guides weren't included, so I still need to update that code. --------- Co-authored-by: abbycross Co-authored-by: Jessie Yu --- .../api/migration-guides/local-simulators.mdx | 2 +- .../qiskit-runtime-examples.mdx | 29 ++++++++++--------- .../qiskit-runtime-from-ibm-provider.mdx | 22 +++++++------- docs/api/migration-guides/v2-primitives.mdx | 8 ++--- docs/guides/configure-error-mitigation.mdx | 2 +- docs/guides/configure-error-suppression.mdx | 2 +- docs/guides/execution-modes.mdx | 12 +++++--- docs/guides/get-started-with-primitives.mdx | 22 +++++++------- docs/guides/instances.mdx | 18 ++++++------ docs/guides/primitives-examples.mdx | 4 +-- docs/guides/run-jobs-batch.mdx | 2 +- docs/guides/run-jobs-session.mdx | 6 ++-- docs/guides/runtime-options-overview.mdx | 14 ++++----- docs/guides/sessions.mdx | 1 + .../variational-quantum-eigensolver/vqe.ipynb | 2 +- 15 files changed, 77 insertions(+), 69 deletions(-) diff --git a/docs/api/migration-guides/local-simulators.mdx b/docs/api/migration-guides/local-simulators.mdx index 93cb32ef6b8..78279377d0d 100644 --- a/docs/api/migration-guides/local-simulators.mdx +++ b/docs/api/migration-guides/local-simulators.mdx @@ -119,7 +119,7 @@ aer_sim = AerSimulator() pm = generate_preset_pass_manager(backend=aer_sim, optimization_level=1) isa_qc = pm.run(qc) with Session(backend=aer_sim) as session: - sampler = Sampler(session=session) + sampler = Sampler() result = sampler.run([isa_qc]).result() ``` diff --git a/docs/api/migration-guides/qiskit-runtime-examples.mdx b/docs/api/migration-guides/qiskit-runtime-examples.mdx index f6b9fe12f54..86c049bb62d 100644 --- a/docs/api/migration-guides/qiskit-runtime-examples.mdx +++ b/docs/api/migration-guides/qiskit-runtime-examples.mdx @@ -60,7 +60,7 @@ service = QiskitRuntimeService() # Get a backend backend = service.least_busy(operational=True, simulator=False) -# Define Estimator +# Define Estimator estimator = Estimator(backend) # Run an expectation value calculation @@ -77,10 +77,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2 # Run the sampler job locally using FakeManilaV2 fake_manila = FakeManilaV2() -# You can use a fixed seed to get fixed results. +# You can use a fixed seed to get fixed results. options = {"simulator": {"seed_simulator": 42}} -# Define Estimator +# Define Estimator estimator = Estimator(backend=fake_manila, options=options) # Run an expectation value calculation @@ -225,7 +225,8 @@ Output -The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls. The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance` `run` and `transpile` methods. This degree of nesting is no longer supported, the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm. +The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls. The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance`, `run`, and `transpile` methods. This degree of nesting is no longer supported; the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm. + ``` python from qiskit.opflow import StateFn, PauliExpectation, CircuitSampler @@ -256,7 +257,7 @@ expectation: -1.065734058826613 -## Use Sampler to design an algorithm +## Use Sampler to design an algorithm The Sampler primitive is used to design an algorithm that samples circuits and extracts probability distributions. @@ -286,7 +287,7 @@ difference is the format of the output: `backend.run()` outputs # Run result = backend.run(isa_circuits) ``` - + @@ -317,7 +318,7 @@ difference is the format of the output: `backend.run()` outputs backend = service.least_busy(operational=True, simulator=False) # Define Sampler - sampler = Sampler(backend=backend) + sampler = Sampler(mode=backend) # Run calculation job = sampler.run([isa_circuit]) @@ -334,10 +335,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2 # Run the sampler job locally using FakeManilaV2 fake_manila = FakeManilaV2() -# You can use a fixed seed to get fixed results. +# You can use a fixed seed to get fixed results. options = {"simulator": {"seed_simulator": 42}} -# Define Sampler +# Define Sampler sampler = Sampler(backend=fake_manila, options=options) # Run calculation @@ -366,7 +367,7 @@ When using the `Sampler` primitive, the circuit **must contain measurements**. ``` python from qiskit_ibm_runtime import SamplerV2 as Sampler - + # Define a local backend from qiskit_ibm_runtime.fake_provider import FakeManilaV2 backend = FakeManilaV2() @@ -430,7 +431,7 @@ isa_circuit = pm.run(circuit) ``` python -sampler = Sampler(backend=backend) +sampler = Sampler(mode=backend) job = sampler.run([isa_circuit]) @@ -438,11 +439,11 @@ result = job.result() # Get results for the first (and only) PUB pub_result = result[0] -# Get counts from the classical register "meas". +# Get counts from the classical register "meas". print(f" >> Meas output register counts: {pub_result.data.meas.get_counts()}") ->> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1} -``` +>> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1} +``` diff --git a/docs/api/migration-guides/qiskit-runtime-from-ibm-provider.mdx b/docs/api/migration-guides/qiskit-runtime-from-ibm-provider.mdx index 8d341673792..ff323daf880 100644 --- a/docs/api/migration-guides/qiskit-runtime-from-ibm-provider.mdx +++ b/docs/api/migration-guides/qiskit-runtime-from-ibm-provider.mdx @@ -22,7 +22,7 @@ information on retrieving account credentials, see [Install and set up](/guides/ ``` python from qiskit_ibm_runtime import QiskitRuntimeService -# IBM Quantum channel; set to default +# IBM Quantum channel; set to default QiskitRuntimeService.save_account(channel="ibm_quantum", token="", overwrite=True, default=true) ``` @@ -101,7 +101,7 @@ provider = IBMProvider(instance="my_hub/my_group/my_project") -## Get a backend +## Get a backend Use the updated code to specify a backend. @@ -153,19 +153,19 @@ Change the import and run statements, instantiate the primitive, and make sure t from qiskit import QuantumCircuit from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler - + service = QiskitRuntimeService() - + backend = service.least_busy(operational=True, simulator=False, min_num_qubits=127) - + circuit = QuantumCircuit(2, 2) circuit.h(0) circuit.cx(0, 1) circuit.measure_all() - + pm = generate_preset_pass_manager(backend=backend, optimization_level=1) isa_circuit = pm.run(circuit) - + sampler = Sampler(backend) job = sampler.run([isa_circuit]) result = job.result() @@ -203,10 +203,10 @@ print(f" > Counts: {job.result().get_counts()}") from qiskit_ibm_runtime import Session from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler -with Session(service=service, backend=backend) as session: - sampler = Sampler(session=session) - job = sampler.run([isa_circuit]) - another_job = sampler.run([another_isa_circuit]) +with Session(service=service, backend=backend) as session: + sampler = Sampler() + job = sampler.run([isa_circuit]) + another_job = sampler.run([another_isa_circuit]) result = job.result() another_result = another_job.result() ``` diff --git a/docs/api/migration-guides/v2-primitives.mdx b/docs/api/migration-guides/v2-primitives.mdx index 62d49bced6c..13583dac121 100644 --- a/docs/api/migration-guides/v2-primitives.mdx +++ b/docs/api/migration-guides/v2-primitives.mdx @@ -776,7 +776,7 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False, min_num_qubits=127) with Session(service=service, backend=backend) as session: - estimator = Estimator(session=session) + estimator = Estimator() estimator.options.optimization_level = 1 estimator.options.resilience_level = 1 @@ -829,7 +829,7 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False, min_num_qubits=127) with Session(service=service, backend=backend) as session: - estimator = Estimator(session=session, options=options) + estimator = Estimator(options=options) job = estimator.run(isa_circuit, isa_observable) another_job = estimator.run(another_isa_circuit, another_isa_observable) result = job.result() @@ -1119,7 +1119,7 @@ sampler.options.dynamical_decoupling.sequence_type = "XpXm" backend = service.least_busy(operational=True, simulator=False, min_num_qubits=127) with Session(service=service, backend=backend) as session: - sampler = Sampler(session=session) + sampler = Sampler() job = sampler.run([isa_circuit]) another_job = sampler.run([another_isa_circuit]) result = job.result() @@ -1159,7 +1159,7 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False, min_num_qubits=127) with Session(service=service, backend=backend) as session: - sampler = Sampler(session=session, options=options) + sampler = Sampler(options=options) job = sampler.run(circuit) another_job = sampler.run(another_circuit) result = job.result() diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index b223816b176..76e1f8ff9f8 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -334,7 +334,7 @@ options.resilience_level = 2 options.optimization_level = 1 backend = service.least_busy(operational=True, simulator=False) -estimator = Estimator(options=options, mode=backend) +estimator = Estimator(options=options, backend=backend) ``` diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index e99036d07e9..9663ac900d7 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -117,7 +117,7 @@ pm = generate_preset_pass_manager(backend=backend, optimization_level=1) psi = pm.run(psi) H = H.apply_layout(psi.layout) -estimator = Estimator(options=options, mode=backend) +estimator = Estimator(options=options, backend=backend) job = estimator.run(circuits=[psi], observables=[H], parameter_values=[theta]) psi1_H1 = job.result() diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index a96ea5e32e8..15bfa6d3f69 100644 --- a/docs/guides/execution-modes.mdx +++ b/docs/guides/execution-modes.mdx @@ -7,11 +7,15 @@ description: An overview of the available execution modes in Qiskit Runtime; ses There are several ways to run workloads, depending on your needs. -**Job mode**: A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. + +The `mode` option is only available for V2 primitives and requires `qiskit-ibm-runtime` 0.24 or later. + -[**Session mode**](sessions): A dedicated window for running a multi-job workload. This allows users to experiment with variational algorithms in a more predictable way and even run multiple experiments simultaneously taking advantage of parallelism in the stack. Use sessions for iterative workloads or experiments that require dedicated access. See [Run jobs in a session](./run-jobs-session) for examples. +**Job mode**: A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify `mode=backend` when instantiating a primitive. See [Primitives examples](primitives-examples) for examples. -[**Batch mode**](run-jobs-batch): A multi-job manager for efficiently running an experiment that is comprised of bundle of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously. +[**Session mode**](sessions): A dedicated window for running a multi-job workload. This allows users to experiment with variational algorithms in a more predictable way and even run multiple experiments simultaneously taking advantage of parallelism in the stack. Use sessions for iterative workloads or experiments that require dedicated access. To run in session mode, specify `mode=session` when instantiating a primitive or run the job in a session context manager. See [Run jobs in a session](run-jobs-session) for examples. + +[**Batch mode**](run-jobs-batch): A multi-job manager for efficiently running an experiment that is comprised of bundle of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously. To run in batch mode, specify `mode=batch` when instantiating a primitive or run the job in a batch context manager. See [Run jobs in a batch](run-jobs-batch) for examples. The differences are summarized in the following table: @@ -31,7 +35,7 @@ To ensure the most efficient use of the execution modes, the following practices A job's QPU time is listed in the **Usage** column on the IBM Quantum Platform [Jobs](https://quantum.ibm.com/jobs) page, or you can query it by using `qiskit-ibm-runtime` with this command `job.metrics()["usage"]["quantum_seconds"]` -- If each of your jobs consumes more than one minute of QPU time, or if combining jobs is not practical, you can still run multiple jobs in parallel. Every job goes through both classical and quantum processing. While a QPU can process only one job at a time, up to five classical jobs can be processed in parallel. You can take advantage of this by submitting multiple jobs in [batch](run-jobs-batch#partition) or [session](./run-jobs-session#two-vqe) execution mode. +- If each of your jobs consumes more than one minute of QPU time, or if combining jobs is not practical, you can still run multiple jobs in parallel. Every job goes through both classical and quantum processing. While a QPU can process only one job at a time, up to five classical jobs can be processed in parallel. You can take advantage of this by submitting multiple jobs in [batch](run-jobs-batch#partition) or [session](run-jobs-session#two-vqe) execution mode. The above are general guidelines, and you should tune your workload to find the optimal ratio, especially when using sessions. For example, if you are using a session to get exclusive access to a backend, consider breaking up large jobs into smaller ones and running them in parallel. This might be more cost effective because it can reduce wall clock time. diff --git a/docs/guides/get-started-with-primitives.mdx b/docs/guides/get-started-with-primitives.mdx index ee2106da752..b79d69d4300 100644 --- a/docs/guides/get-started-with-primitives.mdx +++ b/docs/guides/get-started-with-primitives.mdx @@ -9,7 +9,7 @@ description: How to use the Estimator and Sampler primitives in Qiskit Runtime. The steps in this topic describes how to set up primitives, explore the options you can use to configure them, and invoke them in a program. -To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, set `optimization_level=0`. +To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, set `optimization_level=0`. *Exception*: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported. @@ -20,7 +20,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") - While this documentation uses the primitives from Qiskit Runtime, which allow you to use IBM® backends, the primitives can be run on any provider by using the [backend primitives](#backend) instead. Additionally, you can use the *reference* primitives to run on a local statevector simulator. See [Exact simulation with Qiskit primitives](./simulate-with-qiskit-sdk-primitives) for details. + While this documentation uses the primitives from Qiskit Runtime, which allow you to use IBM® backends, the primitives can be run on any provider by using the [backend primitives](#backend) instead. Additionally, you can use the *reference* primitives to run on a local statevector simulator. See [Exact simulation with Qiskit primitives](simulate-with-qiskit-sdk-primitives) for details. @@ -32,7 +32,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") Because Qiskit Runtime `Estimator` is a managed service, you first need to initialize your account. You can then select the simulator or real system you want to use to calculate the expectation value. -Follow the steps in the [Install and set up topic](./install-qiskit) if you don't already have an account. +Follow the steps in the [Install and set up topic](install-qiskit) if you don't already have an account. ```python from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator @@ -73,7 +73,7 @@ isa_observable = observable.apply_layout(isa_circuit.layout) ### 3. Initialize Qiskit Runtime Estimator -When you initialize the Estimator, pass in the system or simulator you previously selected as the target. +When you initialize the `Estimator`, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes.](execution-modes) To use the Estimator V2, import the **EstimatorV2** class. The **Estimator** class still refers to the version 1 Estimator, for backwards compatibility. @@ -91,7 +91,7 @@ estimator = Estimator(mode=backend) ```python from qiskit_ibm_runtime import Estimator -estimator = Estimator(mode=backend) +estimator = Estimator(backend=backend) ``` @@ -153,7 +153,7 @@ print(f" > Metadata: {result.metadata[0]}") Because Qiskit Runtime `Sampler` is a managed service, you first need to initialize your account. You can then select the simulator or real system you want to use to calculate the expectation value. -Follow the steps in the [Install and set up topic](./install-qiskit) if you don't already have an account set up. +Follow the steps in the [Install and set up topic](install-qiskit) if you don't already have an account set up. ```python from qiskit_ibm_runtime import QiskitRuntimeService @@ -188,7 +188,7 @@ isa_circuit = pm.run(circuit) ### 3. Initialize the Qiskit Runtime Sampler -When you initialize the `Sampler`, pass in the simulator or system you previously selected as the target. +When you initialize the `Sampler`, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes.](execution-modes) To use the Sampler V2, import the **SamplerV2** class. The **Sampler** class still refers to the version 1 Sampler, for backward compatibility. @@ -205,7 +205,7 @@ sampler = Sampler(mode=backend) ```python from qiskit_ibm_runtime import Sampler -sampler = Sampler(mode=backend) +sampler = Sampler(backend=backend) ``` @@ -262,7 +262,7 @@ print(f" > Metadata: {result.metadata[0]}") ## Get started with the backend primitives -The `Sampler` primitive can be run with any provider by using [`qiskit.primitives.BackendSampler`](../api/qiskit/qiskit.primitives.BackendSampler). Likewise, the `Estimator` primitive can be run with any provider using [`qiskit.primitives.BackendEstimator`](../api/qiskit/qiskit.primitives.BackendEstimator). Equivalent implementations in V2 are coming soon. +The `Sampler` primitive can be run with any provider by using [`qiskit.primitives.BackendSampler`](/api/qiskit/qiskit.primitives.BackendSampler). Likewise, the `Estimator` primitive can be run with any provider using [`qiskit.primitives.BackendEstimator`](../api/qiskit/qiskit.primitives.BackendEstimator). Equivalent implementations in V2 are coming soon. Some providers implement primitives natively (see [the Qiskit Ecosystem page](https://qiskit.github.io/ecosystem#provider) for more details). @@ -291,10 +291,10 @@ sampler = BackendSampler(backend) ## Next steps - - Learn how to [test locally](./local-testing-mode) before running on quantum computers. + - Learn how to [test locally](local-testing-mode) before running on quantum computers. - Review detailed [primitives examples.](primitives-examples) - Read [Migrate to V2 primitives](/api/migration-guides/v2-primitives). - Practice with primitives by working through the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum Learning. - - Learn how to transpile locally in the [Transpile](./transpile) section. + - Learn how to transpile locally in the [Transpile](transpile/) section. - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. diff --git a/docs/guides/instances.mdx b/docs/guides/instances.mdx index c1cb2d1ac19..921dfe245e4 100644 --- a/docs/guides/instances.mdx +++ b/docs/guides/instances.mdx @@ -7,14 +7,14 @@ description: What IBM Quantum Platform instances are and how to use them Access to IBM Quantum™ Platform services is controlled by the **instances** (previously called providers) to which you are assigned. An instance is defined by a hierarchical organization of **hub**, **group**, and **project**. A hub is the top level of a given hierarchy (organization) and contains within it one or more groups. These groups are in turn populated with projects. The combination of hub/group/project is called an instance. Users can belong to more than one instance at any given time. - IBM Cloud® instances are different from IBM Quantum Platform instances. IBM Cloud does not use the hub/group/project structure for user management. This section describes instances in IBM Quantum Platform. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances). Click the name of an instance to see details such as your CRN for that instance, what compute resources (programs, systems, and simulators) are available to you by using that instance, and what jobs you have run on that instance. + IBM Cloud® instances are different from IBM Quantum Platform instances. IBM Cloud does not use the hub/group/project structure for user management. This section describes instances in IBM Quantum Platform. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances). Click the name of an instance to see details such as your CRN for that instance, what compute resources (programs, systems, and simulators) are available to you by using that instance, and what jobs you have run on that instance. ![Alice, Bob, and Charlie are all in Hub A. Hub A has Group 1 and 2. Alice and Bob are in Group 1. Charlie is in Group 2. Group 1 has Project X and Y. Alice is in both projects. Bob is only in project X. Group 2 has Project Z. Charlie is in project Z. Therefore, Charlie's instance is Hub-A/Group-2/Project-Z.](/images/guides/providers1.jpg "Hub / group / project hierarchy") The hub/group/project hierarchy that makes up an IBM Quantum instance. -Users with a public account automatically belong to the ibm-q/open/main [open plan](#open-plan). For organizations outside of IBM, designated hub or group administrators assign users to instances. +Users with a public account automatically belong to the ibm-q/open/main [open plan](#open-plan). For organizations outside of IBM, designated hub or group administrators assign users to instances. To see the instances to which you have access, look at the bottom of your [Account page](https://quantum.ibm.com/account). @@ -26,15 +26,15 @@ You can view a list of your instances on your [account settings page](https://qu ## Switch instances -If you have access to run on multiple instances, the [IBM Quantum interface](https://quantum.ibm.com/) menu bar contains a dropdown that lets you switch between instances. The IBM Quantum Platform dashboard, Compute resources, and Jobs pages display information such as usage metrics, jobs, and systems based on the selected instance. +If you have access to run on multiple instances, the [IBM Quantum interface](https://quantum.ibm.com/) menu bar contains a dropdown that lets you switch between instances. The IBM Quantum Platform dashboard, Compute resources, and Jobs pages display information such as usage metrics, jobs, and systems based on the selected instance. The instance switcher does not appear in the Administration application. -If you switch to a different instance, it is remembered the next time you log on and, assuming that it's still a valid instance, information pertaining to that instance is displayed. By default, the first premium instance you have access to is used. If you do not have any premium instances, the first open instance is shown. +If you switch to a different instance, it is remembered the next time you log on and, assuming that it's still a valid instance, information pertaining to that instance is displayed. By default, the first premium instance you have access to is used. If you do not have any premium instances, the first open instance is shown. -The first instance is determined alphabetically. +The first instance is determined alphabetically. ## Instances and jobs @@ -66,7 +66,7 @@ print(service.instances()) service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1") backend1 = service.backend("ibmq_manila") -# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used. +# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used. backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2") sampler1 = SamplerV2(mode=backend1) # this will use hub1/group1/project1 @@ -85,11 +85,11 @@ print(service.instances()) service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1") backend1 = service.backend("ibmq_manila") -# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used. +# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used. backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2") -sampler1 = Sampler(mode=backend1) # this will use hub1/group1/project1 -sampler2 = Sampler(mode=backend2) # this will use hub2/group2/project2 +sampler1 = Sampler(backend=backend1) # this will use hub1/group1/project1 +sampler2 = Sampler(backend=backend2) # this will use hub2/group2/project2 ``` diff --git a/docs/guides/primitives-examples.mdx b/docs/guides/primitives-examples.mdx index 7afc73fe8a3..89f912497a4 100644 --- a/docs/guides/primitives-examples.mdx +++ b/docs/guides/primitives-examples.mdx @@ -414,7 +414,7 @@ options.optimization_level = 2 options.resilience_level = 2 with Session(service=service, backend=backend) as session: - estimator = Estimator(mode=session, options=options) + estimator = Estimator(session=session, options=options) job = estimator.run(isa_circuit, isa_observable) another_job = estimator.run(another_isa_circuit, another_isa_observable) result = job.result() @@ -746,7 +746,7 @@ options.optimization_level = 2 options.resilience_level = 0 with Session(service=service, backend=backend) as session: - sampler = Sampler(mode=session, options=options) + sampler = Sampler(session=session, options=options) job = sampler.run(isa_circuit) another_job = sampler.run(another_isa_circuit) result = job.result() diff --git a/docs/guides/run-jobs-batch.mdx b/docs/guides/run-jobs-batch.mdx index a34bbed37ab..0139fd4b5f4 100644 --- a/docs/guides/run-jobs-batch.mdx +++ b/docs/guides/run-jobs-batch.mdx @@ -49,5 +49,5 @@ The following example shows how you can partition a long list of circuits into m - If you set `backend=backend` in a V2 primitive it will run the program in job mode, even if it's inside a batch/session context. Avoid setting the backend parameter if you want to run in batch/session mode. + If you set `backend=backend` in a V2 primitive, the program is run in job mode, even if it's inside a batch or session context. Setting `backend=backend` is deprecated as of IBM Qiskit Runtime 0.24.0. Instead, use the `mode` parameter. \ No newline at end of file diff --git a/docs/guides/run-jobs-session.mdx b/docs/guides/run-jobs-session.mdx index b29a4c811bd..ece80b38806 100644 --- a/docs/guides/run-jobs-session.mdx +++ b/docs/guides/run-jobs-session.mdx @@ -52,8 +52,8 @@ from qiskit_ibm_runtime import Session, Sampler, Estimator backend = service.least_busy(operational=True, simulator=False) session = Session(service=service, backend=backend) -estimator = Estimator(mode=session) -sampler = Sampler(mode=session) +estimator = Estimator(session=session) +sampler = Sampler(session=session) ``` @@ -132,6 +132,8 @@ If you are not using a context manager, manually close the session to avoid unwa ``` python session = Session(backend=backend) + +# If using qiskit-ibm-runtime earlier than 0.24.0, change `mode=` to `session=` estimator = Estimator(mode=session) job1 = estimator.run(...) job2 = estimator.run(...) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index dadd658728c..59a68079954 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -74,7 +74,7 @@ estimator.options.default_shots = 4000 When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example: ```python -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) result = estimator.run(circuit, observable).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -131,7 +131,7 @@ sampler.run([circuit1, circuit2], shots=128) You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the options category. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid). ```python -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) result = estimator.run(circuit, observable, shots=1024).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -176,7 +176,7 @@ from qiskit_ibm_runtime import Estimator, Options options = Options() options.execution.shots = 1024 -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) ``` If you need to modify the number of shots set between iterations (primitive calls), you can set the @@ -185,7 +185,7 @@ shots directly in the `run()` method. This overwrites the initial `shots` settin ```python from qiskit_ibm_runtime import Estimator -estimator = Estimator(mode=backend) +estimator = Estimator(backend=backend) estimator.run(circuits=circuits, observables=observables, shots=50) @@ -243,7 +243,7 @@ options = Options(optimization_level=1) options = Options() options.optimization_level = 1 -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) ``` Turning off all optional runtime compilation steps requires a "second-level option", as follows: @@ -254,7 +254,7 @@ from qiskit_ibm_runtime import Estimator, Options options = Options() options.transpilation.skip_transpilation = True -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) ``` For more information and a complete list of advanced transpilation options, see the Advanced transpilation options table in the @@ -298,7 +298,7 @@ options = Options(resilience_level = 2) options = Options() options.resilience_level = 2 -estimator = Estimator(mode=backend, options=options) +estimator = Estimator(backend=backend, options=options) ``` diff --git a/docs/guides/sessions.mdx b/docs/guides/sessions.mdx index ac98e9a8c1d..41b6041de2d 100644 --- a/docs/guides/sessions.mdx +++ b/docs/guides/sessions.mdx @@ -83,6 +83,7 @@ x0 = 2 * np.pi * np.random.random(num_params) session = Session(backend=backend) +# If using qiskit-ibm-runtime earlier than 0.24.0, change `mode=` to `session=` estimator = Estimator(mode=session, options={"shots": int(1e4)}) res = minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method="cobyla") diff --git a/tutorials/variational-quantum-eigensolver/vqe.ipynb b/tutorials/variational-quantum-eigensolver/vqe.ipynb index 2e93887790c..795a73bec04 100644 --- a/tutorials/variational-quantum-eigensolver/vqe.ipynb +++ b/tutorials/variational-quantum-eigensolver/vqe.ipynb @@ -185,7 +185,7 @@ "id": "ed01c675-6506-4779-bf71-74f0de9212fb", "metadata": {}, "source": [ - "To reduce the total job execution time, Qiskit primitives only accept circuits (ansatz) and observables (Hamiltonian) that conform to the instructions and connectivity supported by the target system (referred to as instruction set architecture (ISA) circuits and observables)." + "To reduce the total job execution time, Qiskit primitives only accept circuits (ansatz) and observables (Hamiltonian) that conform to the instructions and connectivity supported by the target QPU (referred to as instruction set architecture (ISA) circuits and observables)." ] }, {