diff --git a/docs/migration-guides/_toc.json b/docs/migration-guides/_toc.json index 0f79fc34c2b..0f04bbcfdc2 100644 --- a/docs/migration-guides/_toc.json +++ b/docs/migration-guides/_toc.json @@ -6,6 +6,16 @@ "title": "Introduction", "url": "/migration-guides" }, + { + "title": "Migrate to Qiskit 2.0", + "children": [ + { + "title": "Migrate from BackendV1 to BackendV2", + "isNew": true, + "url": "/migration-guides/qiskit-backendv1-to-v2" + } + ] + }, { "title": "Migrate to the new version of IBM Quantum Platform", "isNew": true, @@ -72,8 +82,14 @@ "title": "Migrate from qiskit-ibm-provider", "url": "/migration-guides/qiskit-runtime-from-ibm-provider" }, + { + "title": "Migrate provider interfaces from backend.run to primitives", + "isNew": true, + "url": "/migration-guides/external-providers-primitives-v2" + }, { "title": "Migrate to primitives for users of third-party providers with backend.run", + "isNew": true, "url": "/migration-guides/qiskit-backend-primitives" }, { @@ -90,10 +106,6 @@ } ] }, - { - "title": "Migrate provider interfaces from backend.run to primitives", - "url": "/migration-guides/external-providers-primitives-v2" - }, { "title": "Qiskit 0.44 changes", "children": [ diff --git a/docs/migration-guides/qiskit-backendv1-to-v2.mdx b/docs/migration-guides/qiskit-backendv1-to-v2.mdx new file mode 100644 index 00000000000..70eeaaf09af --- /dev/null +++ b/docs/migration-guides/qiskit-backendv1-to-v2.mdx @@ -0,0 +1,76 @@ +--- +title: Migrate from BackendV1 to BackendV2 +description: How to update your code to use `BackendV2` instead of `BackendV1`. +--- + +# Migrate from `BackendV1` to `BackendV2` + +The Qiskit [`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) class has been deprecated and will be removed from service. This migration guide describes the small adjustments you need to make if you use a provider that upgraded from [`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) to [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2). + + + If you exclusively use `qiskit_ibm_runtime` and `qiskit_aer`, no action is needed. The `qiskit_ibm_runtime` package has always used `BackendV2`, and `qiskit_aer` has used `BackendV2` since version 0.13. + + + +## High-level changes in `BackendV2` + +The Qiskit [`Backend`](/api/qiskit/qiskit.providers.Backend) model was designed to provide the Qiskit SDK with an abstraction +layer that enabled reasoning about quantum computers within the scope of the SDK. The first iteration of the model was introduced with the +[`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) class. This class stored the backend information in a series +of data containers, namely the [`BackendConfiguration`](/api/qiskit/1.4/qiskit.providers.models.BackendConfiguration) and +[`BackendProperties`](/api/qiskit/1.4/qiskit.providers.models.BackendProperties) classes. + +The [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) class redefined +user access for most backend properties to make them work with native Qiskit data structures and have flatter +access patterns. The core of the [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) model is the +[`Target`](/api/qiskit/qiskit.transpiler.Target) class, a representation of the QPU that contains the transpilation constraints that Qiskit can use to optimize circuits for execution. + +The Qiskit SDK has been updated to work exclusively with [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) inputs, +and most providers have upgraded from [`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) to [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2). It is expected that existing providers will deprecate the old access where possible to provide a graceful migration, but eventually users will need to adjust their code. + +The principle behind [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) is +that most of the information about a backend is contained in its +[`Target`](/api/qiskit/qiskit.transpiler.Target) object, and the backend's attributes often query +its `BackendV2.target` attribute to return information. However, in many cases the attributes only provide +a subset of information that the target can contain. For example, `backend.coupling_map` +returns a [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap) constructed from the +[`Target`](/api/qiskit/qiskit.transpiler.Target) accessible in the +`BackendV2.target` attribute. However, the target might contain +instructions that operate on more than two qubits (which can't be represented in a +[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap)) or it might have instructions that only operate on +a subset of qubits (or two qubit links, for a two qubit instruction), which won't be +detailed in the full coupling map returned by +`BackendV2.coupling_map`. So depending on your use case, +it might be necessary to look deeper than just the equivalent access with +[`BackendV2`](/api/qiskit/qiskit.providers.BackendV2). + +## Specific changes in `BackendV2` + +Most attributes have a direct replacement, simplifying the migration efforts. The only point of mismatch between interfaces is in the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap). + + +Following is a table of example access patterns in [`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) and the new form +with [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2). + + +Scroll to the right to see important notes. + + +|[`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) | [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) | Notes | +| --- | --- | --- | +|`backend.configuration().n_qubits` | `backend.num_qubits`| | +|`backend.configuration().coupling_map` | `backend.coupling_map` | The return from [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) is a [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap) object. In [`BackendV1`](/api/qiskit/1.4/qiskit.providers.BackendV1) it is an edge list. Also, this is just a view of the information contained in `backend.target` which may only be a subset of the information contained in the [`Target`](/api/qiskit/qiskit.transpiler.Target) object. | +|`backend.configuration().backend_name` | `backend.name` | | +|`backend.configuration().backend_version` | `backend.backend_version` | The `BackendV2.version` attribute represents the version of the abstract [`Backend`](/api/qiskit/qiskit.providers.Backend) interface that the object implements, while `BackendV2.backend_version` is metadata about the version of the backend itself. | +|`backend.configuration().basis_gates` | `backend.operation_names` | The [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) returns a list of operation names contained in the `backend.target` attribute. The [`Target`](/api/qiskit/qiskit.transpiler.Target) might contain more information than can be expressed by this list of names. For example, some operations only work on a subset of qubits, and some names implement the same gate with different parameters.| +|`backend.configuration().dt`|`backend.dt`| | +|`backend.configuration().dtm`|`backend.dtm` | | +|`backend.configuration().max_experiments` |`backend.max_circuits` | | +|`backend.configuration().online_date` | `backend.online_date`| | +|`InstructionDurations.from_backend(backend)`|`backend.instruction_durations`| | +|`backend.defaults().instruction_schedule_map`|`backend.instruction_schedule_map`| | +|`backend.properties().t1(0)`|`backend.qubit_properties(0).t1`| | +|`backend.properties().t2(0)`|`backend.qubit_properties(0).t2`| | +|`backend.properties().frequency(0)`|`backend.qubit_properties(0).frequency`| | +|`backend.properties().readout_error(0)`|`backend.target["measure"][(0,)].error`| In [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2), the error rate for the [`Measure`](/api/qiskit/circuit#measure) operation on a given qubit is used to model the readout error. However, a [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) object can implement multiple measurement types and list them separately in a [`Target`](/api/qiskit/qiskit.transpiler.Target).| +|`backend.properties().readout_length(0)`|`backend.target["measure"][(0,)].duration`| In [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2), the duration for the [`Measure`](/api/qiskit/circuit#measure) operation on a given qubit is used to model the readout length. However, a [`BackendV2`](/api/qiskit/qiskit.providers.BackendV2) object can implement multiple measurement types and list them separately in a [`Target`](/api/qiskit/qiskit.transpiler.Target).| diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index fa8b4b93ffc..53080e85617 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -300,6 +300,8 @@ notifications: - "@ElePT" "docs/migration-guides/qiskit-quantum-instance": - "@ElePT" + "docs/migration-guides/qiskit-backendv1-to-v2": + - "@ElePT" "docs/migration-guides/qiskit-runtime": - "@beckykd" - "@jyu00"