Improve the qiskit.algorithms docs: clearly show legacy vs. primi…

…tive algorithms (#9382) (#9415)

* Algorithms init cleanup

Emphasize the split in primitive-based and legacy algorithms more clearly

* add "pending deprecation" in heading

* apply same layout to time evolvers

* temporarily pin to get CI done, merge from main later

* pin to 1.23.1

* remove "pending deprecation"

* add missing TrotterQRTE import

* Apply suggestions from code review

Co-authored-by: ElePT <57907331+ElePT@users.noreply.github.com>

* trailing whitespaces

* more trailing whitespace -- this time at front

* reword

Co-authored-by: ElePT <57907331+ElePT@users.noreply.github.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit e58ac56)

Co-authored-by: Julien Gacon <gaconju@gmail.com>

qiskit/algorithms/__init__.py

@@ -72,71 +72,56 @@
    MaximumLikelihoodAmplitudeEstimationResult
 
 
-Eigen Solvers
--------------
-
-Algorithms to find eigenvalues of an operator. For chemistry these can be used to find excited
-states of a molecule, and qiskit-nature has some algorithms that leverage chemistry specific
-knowledge to do this in that application domain. These algorithms are pending deprecation.
-One should instead make use of the Eigensolver classes in the section below, which leverage
-Runtime primitives.
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   Eigensolver
-   EigensolverResult
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   NumPyEigensolver
-   VQD
-   VQDResult
-
 Eigensolvers
 ------------
 
 Algorithms to find eigenvalues of an operator. For chemistry these can be used to find excited
-states of a molecule, and qiskit-nature has some algorithms that leverage chemistry specific
+states of a molecule, and ``qiskit-nature`` has some algorithms that leverage chemistry specific
 knowledge to do this in that application domain.
 
+Primitive-based Eigensolvers
+++++++++++++++++++++++++++++
+
+These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use
+of :class:`.QuantumInstance` in algorithms. To ensure continued support and development, we recommend
+using the primitive-based Eigensolvers in place of the legacy :class:`.QuantumInstance`-based ones.
+
 .. autosummary::
    :toctree: ../stubs/
 
    eigensolvers
 
-Evolvers
---------
-
-Pending deprecation: This package has been superseded by the package below. It will be
-deprecated in a future release and subsequently removed after that:
 
-`Time Evolvers`_
+Legacy Eigensolvers
++++++++++++++++++++
 
-Algorithms to evolve quantum states in time. Both real and imaginary time evolution is possible
-with algorithms that support them. For machine learning, Quantum Imaginary Time Evolution might be
-used to train Quantum Boltzmann Machine Neural Networks for example.
+These algorithms, still based on the :class:`.QuantumInstance`, are superseded
+by the primitive-based versions in the section above but are still supported for now.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-   RealEvolver
-   ImaginaryEvolver
-   TrotterQRTE
-   EvolutionResult
-   EvolutionProblem
+   Eigensolver
+   EigensolverResult
+   NumPyEigensolver
+   VQD
+   VQDResult
 
 
 Time Evolvers
 -------------
 
-Primitives-enabled algorithms to evolve quantum states in time. Both real and imaginary time
-evolution is possible with algorithms that support them. For machine learning, Quantum Imaginary
-Time Evolution might be used to train Quantum Boltzmann Machine Neural Networks for example.
+Algorithms to evolve quantum states in time. Both real and imaginary time evolution is possible
+with algorithms that support them. For machine learning, Quantum Imaginary Time Evolution might be
+used to train Quantum Boltzmann Machine Neural Networks for example.
+
+Primitive-based Time Evolvers
++++++++++++++++++++++++++++++
+
+These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use
+of :class:`.QuantumInstance` in algorithms. To ensure continued support and development, we recommend
+using the primitive-based Time Evolvers in place of the legacy :class:`.QuantumInstance`-based ones.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -153,11 +138,28 @@
    VarQITE
    VarQRTE
 
+Legacy Time Evolvers
+++++++++++++++++++++
+
+These algorithms, still based on the :class:`.QuantumInstance`, are superseded
+by the primitive-based versions in the section above but are still supported for now.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+    RealEvolver
+    ImaginaryEvolver
+    TrotterQRTE
+    EvolutionResult
+    EvolutionProblem
+
 
 Variational Quantum Time Evolution
 ++++++++++++++++++++++++++++++++++
 
-Classes used by variational quantum time evolution algorithms - VarQITE and VarQRTE.
+Classes used by variational quantum time evolution algorithms - :class:`.VarQITE` and
+:class:`.VarQRTE`.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -168,7 +170,8 @@
 Trotterization-based Quantum Real Time Evolution
 ++++++++++++++++++++++++++++++++++++++++++++++++
 
-Package for primitives-enabled Trotterization-based quantum time evolution algorithm - TrotterQRTE.
+Package for primitives-enabled Trotterization-based quantum time evolution
+algorithm - :class:`~.time_evolvers.TrotterQRTE`.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -212,37 +215,40 @@
    linear_solvers
 
 
-Minimum Eigen Solvers
+Minimum Eigensolvers
 ---------------------
 
 Algorithms that can find the minimum eigenvalue of an operator.
-These algorithms are pending deprecation. One should instead make use of the
-Minimum Eigensolver classes in the section below, which leverage Runtime primitives.
 
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
+Primitive-based Minimum Eigensolvers
+++++++++++++++++++++++++++++++++++++
 
-   MinimumEigensolver
-   MinimumEigensolverResult
+These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use
+of :class:`.QuantumInstance` in algorithms. To ensure continued support and development, we recommend
+using the primitive-based Minimum Eigensolvers in place of the legacy :class:`.QuantumInstance`-based
+ones.
 
 .. autosummary::
    :toctree: ../stubs/
-   :nosignatures:
 
-   NumPyMinimumEigensolver
-   QAOA
-   VQE
+   minimum_eigensolvers
 
-Minimum Eigensolvers
---------------------
 
-Algorithms that can find the minimum eigenvalue of an operator and leverage primitives.
+Legacy Minimum Eigensolvers
++++++++++++++++++++++++++++
+
+These algorithms, still based on the :class:`.QuantumInstance`, are superseded
+by the primitive-based versions in the section above but are still supported for now.
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
-   minimum_eigensolvers
+   MinimumEigensolver
+   MinimumEigensolverResult
+   NumPyMinimumEigensolver
+   QAOA
+   VQE
 
 
 Optimizers

qiskit/algorithms/time_evolvers/__init__.py

@@ -16,6 +16,7 @@
 from .real_time_evolver import RealTimeEvolver
 from .time_evolution_problem import TimeEvolutionProblem
 from .time_evolution_result import TimeEvolutionResult
+from .trotterization import TrotterQRTE
 from .pvqd import PVQD, PVQDResult
 from .classical_methods import SciPyImaginaryEvolver, SciPyRealEvolver
 from .variational import VarQITE, VarQRTE, VarQTE, VarQTEResult
@@ -25,6 +26,7 @@
     "RealTimeEvolver",
     "TimeEvolutionProblem",
     "TimeEvolutionResult",
+    "TrotterQRTE",
     "PVQD",
     "PVQDResult",
     "SciPyImaginaryEvolver",

test/python/algorithms/time_evolvers/test_trotter_qrte.py

@@ -19,8 +19,7 @@
 import numpy as np
 from numpy.testing import assert_raises
 
-from qiskit.algorithms.time_evolvers.time_evolution_problem import TimeEvolutionProblem
-from qiskit.algorithms.time_evolvers.trotterization.trotter_qrte import TrotterQRTE
+from qiskit.algorithms.time_evolvers import TimeEvolutionProblem, TrotterQRTE
 from qiskit.primitives import Estimator
 from qiskit import QuantumCircuit
 from qiskit.circuit.library import ZGate