Add Migration guide from BackendV1 to BackendV2

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": [

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).
+
+<Admonition type="note">
+ 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.
+ </Admonition>
+
+
+## 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).
+
+<Admonition type="important">
+Scroll to the right to see important notes.
+</Admonition>
+
+|[`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).|

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"