Finish converting migration guides to MDX (#304)

Closes #213. These changes are all manual. I looked over the rendered site and MDX files to see issues like `[My link]` without the corresponding `()` for the link itself. But for tables, I used the script from #296.
Qiskit · Nov 8, 2023 · a36c9ba · a36c9ba
1 parent 70601ea
commit a36c9ba
Show file tree

Hide file tree

Showing 5 changed files with 465 additions and 489 deletions.
diff --git a/docs/api/migration-guides/_toc.json b/docs/api/migration-guides/_toc.json
@@ -17,6 +17,23 @@
             "url": "/api/migration-guides/qiskit-runtime-examples"
           }
         ]
+      },
+      {
+        "title": "Qiskit 0.44 changes",
+        "children": [
+          {
+            "title": "QuantumInstance deprecation",
+            "url": "/api/migration-guides/qiskit-quantum-instance"
+          },
+          {
+            "title": "qiskit.algorithms new interface",
+            "url": "/api/migration-guides/qiskit-algorithms-module"
+          },
+          {
+            "title": "qiskit.opflow deprecation",
+            "url": "/api/migration-guides/qiskit-opflow-module"
+          }
+        ]
       }
     ]
   }

diff --git a/docs/api/migration-guides/index.mdx b/docs/api/migration-guides/index.mdx
@@ -11,3 +11,7 @@ We've prepared various migration guides to help you more effectively use Qiskit
 * Migrate to Qiskit Runtime
    * [How to migrate](./qiskit-runtime)
    * [Examples](./qiskit-runtime-examples)
+* Qiskit 0.44 changes
+   * [`qiskit.algorithms` new interface](./qiskit-algorithms-module)
+   * [`qiskit.opflow` deprecation](./qiskit-opflow-module)
+   * [`QuantumIntance` deprecation](./qiskit-quantum-instance)
diff --git a/docs/api/migration-guides/qiskit-algorithms-module.mdx b/docs/api/migration-guides/qiskit-algorithms-module.mdx
@@ -5,6 +5,22 @@ description: Use the new interface for `qiskit.algorithms`
 
 # Algorithms Migration Guide
 
+<Admonition type="caution">
+  The `qiskit.algorithms` module has been superseded by a new standalone library, `qiskit_algorithms`,
+  available on [GitHub](https://github.com/qiskit-community/qiskit-algorithms) and 
+  [PyPi](https://pypi.org/project/qiskit-algorithms).
+
+  As of Qiskit's 0.44 release, active development of algorithm features has migrated to this new package.
+  If your code used `qiskit.algorithms`, you should:
+   1. Check that you are not using any legacy algorithm implementation. If you are, follow this guide to
+      migrate to the primitives-based implementation.
+   2. Once your code is updated, run `pip install qiskit-algorithms` and update your imports from 
+      `qiskit.algorithms` to `qiskit_algorithms`.
+
+  The decision to migrate the `qiskit.algorithms` module to a
+  separate package was made to clarify the purpose of Qiskit and make a distinction between the tools and libraries built on top of it.
+</Admonition>
+
 ## TL;DR
 
 The [`qiskit.algorithms`](../qiskit/algorithms) module has been fully refactored to use the [`qiskit.primitives`](../qiskit/primitives), for circuit execution, instead of the [`qiskit.utils.QuantumInstance`](../qiskit/qiskit.utils.QuantumInstance), which is now deprecated.
@@ -21,16 +37,16 @@ There have been **3 types of refactoring**:
    >   **specify the full import path** (e.g., `from qiskit.algorithms.eigensolvers import VQD`)
    > </Admonition>
    >
-   > - [Minimum Eigensolvers]
-   > - [Eigensolvers]
-   > - [Time Evolvers]
+   > - [Minimum Eigensolvers](#minimum-eigensolvers)
+   > - [Eigensolvers](#eigensolvers)
+   > - [Time Evolvers](#time-evolvers)
 
 2. Algorithms refactored in-place (same namespace) to support both [`qiskit.utils.QuantumInstance`](../qiskit/qiskit.utils.QuantumInstance) and
    [`qiskit.primitives`](../qiskit/primitives). In the future, the use of [`qiskit.utils.QuantumInstance`](../qiskit/qiskit.utils.QuantumInstance) will be removed.
 
-   > - [Amplitude Amplifiers]
-   > - [Amplitude Estimators]
-   > - [Phase Estimators]
+   > - [Amplitude Amplifiers](#amplitude-amplifiers)
+   > - [Amplitude Estimators](#amplitude-estimators)
+   > - [Phase Estimators](#phase-estimators)
 
 3. Algorithms that were deprecated and are now removed entirely from [`qiskit.algorithms`](../qiskit/algorithms). These are algorithms that do not currently serve
    as building blocks for applications. Their main value is educational. You can consult the below tutorials:
@@ -93,13 +109,13 @@ In this guide, we will cover 3 different common configurations for algorithms th
 1. Running an algorithm with a statevector simulator (i.e., using [`qiskit.opflow`](../qiskit/opflow)'s legacy
    [`qiskit.opflow.expectations.MatrixExpectation`](../qiskit/qiskit.opflow.expectations.MatrixExpectation)), when you want the ideal outcome without shot noise:
 
-   > - Reference Primitives with default configuration (see [QAOA] example):
+   > - Reference Primitives with default configuration (see [QAOA](https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/algorithms/05_qaoa.ipynb) example):
    >
    > ```python
    > from qiskit.primitives import Sampler, Estimator
    > ```
    >
-   > - Aer Primitives **with statevector simulator** (see [QAOA] example):
+   > - Aer Primitives **with statevector simulator** (see [QAOA](https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/algorithms/05_qaoa.ipynb) example):
    >
    > ```python
    > from qiskit_aer.primitives import Sampler, Estimator
@@ -111,7 +127,7 @@ In this guide, we will cover 3 different common configurations for algorithms th
 2. Running an algorithm using a simulator/device with shot noise
    (i.e., using [`qiskit.opflow`](../qiskit/opflow)'s legacy [`qiskit.opflow.expectations.PauliExpectation`](../qiskit/qiskit.opflow.expectations.PauliExpectation)):
 
-   > - Reference Primitives **with shots** (see [VQE] examples):
+   > - Reference Primitives **with shots** (see [VQE](#vqe) examples):
    >
    > ```python
    > from qiskit.primitives import Sampler, Estimator
@@ -127,22 +143,22 @@ In this guide, we will cover 3 different common configurations for algorithms th
    > job = estimator.run(circuits, observables, shots=100)
    > ```
    >
-   > - Aer Primitives with default configuration (see [VQE] examples):
+   > - Aer Primitives with default configuration (see [VQE](#vqe) examples):
    >
    > ```python
    > from qiskit_aer.primitives import Sampler, Estimator
    > ```
    >
-   > - IBM's Qiskit Runtime Primitives with default configuration (see [VQD] example):
+   > - IBM's Qiskit Runtime Primitives with default configuration (see [VQD](https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/algorithms/04_vqd.ipynb) example):
    >
    > ```python
    > from qiskit_ibm_runtime import Sampler, Estimator
    > ```
 
-3\. Running an algorithm on an Aer simulator using a custom instruction (i.e., using [`qiskit.opflow`](../qiskit/opflow)'s legacy
+3. Running an algorithm on an Aer simulator using a custom instruction (i.e., using [`qiskit.opflow`](../qiskit/opflow)'s legacy
 [`qiskit.opflow.expectations.AerPauliExpectation`](../qiskit/qiskit.opflow.expectations.AerPauliExpectation)):
 
-> - Aer Primitives with `shots=None`, `approximation=True` (see [TrotterQRTE] example):
+> - Aer Primitives with `shots=None`, `approximation=True` (see [TrotterQRTE](#trotterqrte) example):
 >
 > ```python
 > from qiskit_aer.primitives import Sampler, Estimator

diff --git a/docs/api/migration-guides/qiskit-opflow-module.mdx b/docs/api/migration-guides/qiskit-opflow-module.mdx
@@ -357,22 +357,11 @@ to initialize it.
 <Admonition type="tip">
   Interpreting [`qiskit.opflow.primitive_ops.PrimitiveOp`](../qiskit/qiskit.opflow.primitive_ops.PrimitiveOp) as a factory class:
 
-  ```{eval-rst}
-  .. list-table::
-     :header-rows: 1
-
-     * - Class passed to [`qiskit.opflow.primitive_ops.PrimitiveOp`](../qiskit/qiskit.opflow.primitive_ops.PrimitiveOp)
-       - Subclass returned
-
-     * - [`qiskit.quantum_info.Pauli`](../qiskit/qiskit.quantum_info.Pauli)
-       - [`qiskit.opflow.primitive_ops.PauliOp`](../qiskit/qiskit.opflow.primitive_ops.PauliOp)
-
-     * - [`qiskit.circuit.Instruction`](../qiskit/qiskit.circuit.Instruction), [`qiskit.circuit.QuantumCircuit`](../qiskit/qiskit.circuit.QuantumCircuit)
-       - [`qiskit.opflow.primitive_ops.CircuitOp`](../qiskit/qiskit.opflow.primitive_ops.CircuitOp)
-
-     * - ``list``, ``np.ndarray``, ``scipy.sparse.spmatrix``, [`qiskit.quantum_info.Operator`](../qiskit/qiskit.quantum_info.Operator)
-       - [`qiskit.opflow.primitive_ops.MatrixOp`](../qiskit/qiskit.opflow.primitive_ops.MatrixOp)
-  ```
+  | Class passed to [`qiskit.opflow.primitive_ops.PrimitiveOp`](../qiskit/qiskit.opflow.primitive_ops.PrimitiveOp) | Subclass returned |
+  | --- | --- |
+  | [`qiskit.quantum_info.Pauli`](../qiskit/qiskit.quantum_info.Pauli) | [`qiskit.opflow.primitive_ops.PauliOp`](../qiskit/qiskit.opflow.primitive_ops.PauliOp) |
+  | [`qiskit.circuit.Instruction`](../qiskit/qiskit.circuit.Instruction), [`qiskit.circuit.QuantumCircuit`](../qiskit/qiskit.circuit.QuantumCircuit) | [`qiskit.opflow.primitive_ops.CircuitOp`](../qiskit/qiskit.opflow.primitive_ops.CircuitOp) |
+  | `list`, `np.ndarray`, `scipy.sparse.spmatrix`, [`qiskit.quantum_info.Operator`](../qiskit/qiskit.quantum_info.Operator) | [`qiskit.opflow.primitive_ops.MatrixOp`](../qiskit/qiskit.opflow.primitive_ops.MatrixOp) |
 </Admonition>
 
 Thus, when migrating opflow code, it is important to look for alternatives to replace the specific subclasses that
@@ -390,7 +379,7 @@ are used "under the hood" in the original code:
 
 <span id="example-pauli-sum-op"></span>
 
-#### Example 1: ``PauliSumOp``
+#### Example 1: `PauliSumOp`
 
 Opflow:
 
@@ -423,7 +412,7 @@ SparsePauliOp(['XYZY'],
 
 <span id="example-z2-sym"></span>
 
-#### Example 2: ``Z2Symmetries`` and ``TaperedPauliSumOp``
+#### Example 2: `Z2Symmetries` and `TaperedPauliSumOp`
 
 Opflow:
 
@@ -545,25 +534,12 @@ acts as a factory to create the corresponding subclass depending on the computat
 <Admonition type="tip">
   Interpreting [`qiskit.opflow.state_fns.StateFn`](../qiskit/qiskit.opflow.state_fns.StateFn) as a factory class:
 
-  ```{eval-rst}
-  .. list-table::
-     :header-rows: 1
-
-     * - Class passed to [`qiskit.opflow.state_fns.StateFn`](../qiskit/qiskit.opflow.state_fns.StateFn)
-       - Sub-class returned
-
-     * - ``str``, ``dict``, [`qiskit.result.Result`](../qiskit/qiskit.result.Result)
-       - [`qiskit.opflow.state_fns.DictStateFn`](../qiskit/qiskit.opflow.state_fns.DictStateFn)
-
-     * - ``list``, ``np.ndarray``, [`qiskit.quantum_info.Statevector`](../qiskit/qiskit.quantum_info.Statevector)
-       - [`qiskit.opflow.state_fns.VectorStateFn`](../qiskit/qiskit.opflow.state_fns.VectorStateFn)
-
-     * - [`qiskit.circuit.QuantumCircuit`](../qiskit/qiskit.circuit.QuantumCircuit), [`qiskit.circuit.Instruction`](../qiskit/qiskit.circuit.Instruction)
-       - [`qiskit.opflow.state_fns.CircuitStateFn`](../qiskit/qiskit.opflow.state_fns.CircuitStateFn)
-
-     * - [`qiskit.opflow.OperatorBase`](../qiskit/qiskit.opflow.OperatorBase)
-       - [`qiskit.opflow.state_fns.OperatorStateFn`](../qiskit/qiskit.opflow.state_fns.OperatorStateFn)
-  ```
+| Class passed to [`qiskit.opflow.state_fns.StateFn`](../qiskit/qiskit.opflow.state_fns.StateFn) | Subclass returned |
+| --- | --- |
+| `str`, `dict`, [`qiskit.result.Result`](../qiskit/qiskit.result.Result) | [`qiskit.opflow.state_fns.DictStateFn`](../qiskit/qiskit.opflow.state_fns.DictStateFn) |
+| `list`, `np.ndarray`, [`qiskit.quantum_info.Statevector`](../qiskit/qiskit.quantum_info.Statevector) | [`qiskit.opflow.state_fns.VectorStateFn`](../qiskit/qiskit.opflow.state_fns.VectorStateFn) |
+| [`qiskit.circuit.QuantumCircuit`](../qiskit/qiskit.circuit.QuantumCircuit), [`qiskit.circuit.Instruction`](../qiskit/qiskit.circuit.Instruction) | [`qiskit.opflow.state_fns.CircuitStateFn`](../qiskit/qiskit.opflow.state_fns.CircuitStateFn) |
+| [`qiskit.opflow.OperatorBase`](../qiskit/qiskit.opflow.OperatorBase) | [`qiskit.opflow.state_fns.OperatorStateFn`](../qiskit/qiskit.opflow.state_fns.OperatorStateFn) |
 </Admonition>
 
 This means that references to [`qiskit.opflow.state_fns.StateFn`](../qiskit/qiskit.opflow.state_fns.StateFn) in opflow code should be examined to
@@ -668,7 +644,7 @@ Notably, this functionality has been replaced by the [`qiskit.primitives`](../qi
 
 <span id="example-convert-state"></span>
 
-### Example 1: ``CircuitSampler`` for sampling parametrized circuits
+### Example 1: `CircuitSampler` for sampling parametrized circuits
 
 Opflow:
 
@@ -733,7 +709,7 @@ print(sampled)
 [{0: 1.0}, {0: 1.0}, {0: 1.0}]
 ```
 
-### Example 2: ``CircuitSampler`` for computing expectation values
+### Example 2: `CircuitSampler` for computing expectation values
 
 Opflow:
 
@@ -783,7 +759,7 @@ print(expectation_value)
 
 <span id="example-commuting"></span>
 
-### Example 3: ``AbelianGrouper`` for grouping operators
+### Example 3: `AbelianGrouper` for grouping operators
 
 Opflow:
 
@@ -1260,42 +1236,23 @@ qfi = QFI(qgt)
   Here is a quick guide for migrating the most common gradient settings. Please note that all new gradient
   imports follow the format:
 
-  > ```python
-  > from qiskit.algorithms.gradients import MethodPrimitiveGradient, QFI
-  > ```
-
-  ```{eval-rst}
-  .. dropdown:: Gradients
-      :animate: fade-in-slide-down
-
-      .. list-table::
-         :header-rows: 1
-
-         * - Opflow
-           - Alternative
-
-         * - ``Gradient(method="lin_comb")``
-           - ``LinCombEstimatorGradient(estimator=estimator)`` or ``LinCombSamplerGradient(sampler=sampler)``
-         * - ``Gradient(method="param_shift")``
-           - ``ParamShiftEstimatorGradient(estimator=estimator)`` or ``ParamShiftSamplerGradient(sampler=sampler)``
-         * - ``Gradient(method="fin_diff")``
-           - ``FiniteDiffEstimatorGradient(estimator=estimator)`` or ``ParamShiftSamplerGradient(sampler=sampler)``
+  ```python
+  from qiskit.algorithms.gradients import MethodPrimitiveGradient, QFI
   ```
 
-  ```{eval-rst}
-  .. dropdown:: QFI/QGT
-      :animate: fade-in-slide-down
+  Gradients:
 
-      .. list-table::
-         :header-rows: 1
+  | Opflow | Alternative |
+  | --- | --- |
+  | `Gradient(method="lin_comb")` | `LinCombEstimatorGradient(estimator=estimator)` or `LinCombSamplerGradient(sampler=sampler)` |
+  | `Gradient(method="param_shift")` | `ParamShiftEstimatorGradient(estimator=estimator)` or `ParamShiftSamplerGradient(sampler=sampler)` |
+  | `Gradient(method="fin_diff")` | `FiniteDiffEstimatorGradient(estimator=estimator)` or `ParamShiftSamplerGradient(sampler=sampler)` |
 
-         * - Opflow
-           - Alternative
+  QFI/QGT:
 
-         * - ``QFI(method="lin_comb_full")``
-           - ``qgt=LinCombQGT(Estimator())``
-             ``QFI(qgt=qgt)``
-  ```
+  | Opflow | Alternative |
+  | --- | --- |
+  | `QFI(method="lin_comb_full")` | `qgt=LinCombQGT(Estimator())` |
 </Admonition>
 
 Other auxiliary classes in the legacy gradient framework have now been deprecated. Here is the complete migration