Time Evolution Framework with primitives.

qiskit/algorithms/__init__.py

@@ -108,6 +108,11 @@
 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`_
+
 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.
@@ -127,6 +132,23 @@
     EvolutionProblem
 
 
+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.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+    RealTimeEvolver
+    ImaginaryTimeEvolver
+    TimeEvolutionResult
+    TimeEvolutionProblem
+
+
 Factorizers
 -----------
 
@@ -257,6 +279,10 @@
 from .evolvers import EvolutionResult, EvolutionProblem
 from .evolvers.real_evolver import RealEvolver
 from .evolvers.imaginary_evolver import ImaginaryEvolver
+from .time_evolvers.imaginary_time_evolver import ImaginaryTimeEvolver
+from .time_evolvers.real_time_evolver import RealTimeEvolver
+from .time_evolvers.time_evolution_problem import TimeEvolutionProblem
+from .time_evolvers.time_evolution_result import TimeEvolutionResult
 from .variational_algorithm import VariationalAlgorithm, VariationalResult
 from .amplitude_amplifiers import Grover, GroverResult, AmplificationProblem, AmplitudeAmplifier
 from .amplitude_estimators import (
@@ -322,11 +348,15 @@
     "NumPyEigensolver",
     "RealEvolver",
     "ImaginaryEvolver",
+    "RealTimeEvolver",
+    "ImaginaryTimeEvolver",
     "TrotterQRTE",
     "VarQITE",
     "VarQRTE",
     "EvolutionResult",
     "EvolutionProblem",
+    "TimeEvolutionResult",
+    "TimeEvolutionProblem",
     "LinearSolverResult",
     "Eigensolver",
     "EigensolverResult",

qiskit/algorithms/evolvers/evolution_problem.py

@@ -17,16 +17,29 @@
 from qiskit import QuantumCircuit
 from qiskit.circuit import Parameter
 from qiskit.opflow import OperatorBase, StateFn
+from qiskit.utils.deprecation import deprecate_function
 from ..list_or_dict import ListOrDict
 
 
 class EvolutionProblem:
-    """Evolution problem class.
+    """Pending deprecation: Evolution problem class.
+
+    The EvolutionProblem class has been superseded by the
+    :class:`qiskit.algorithms.time_evolvers.TimeEvolutionProblem` class.
+    This class will be deprecated in a future release and subsequently
+    removed after that.
 
     This class is the input to time evolution algorithms and must contain information on the total
     evolution time, a quantum state to be evolved and under which Hamiltonian the state is evolved.
     """
 
+    @deprecate_function(
+        "The EvolutionProblem class has been superseded by the "
+        "qiskit.algorithms.time_evolvers.TimeEvolutionProblem class. "
+        "This class will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def __init__(
         self,
         hamiltonian: OperatorBase,

qiskit/algorithms/evolvers/evolution_result.py

@@ -17,12 +17,27 @@
 from qiskit import QuantumCircuit
 from qiskit.algorithms.list_or_dict import ListOrDict
 from qiskit.opflow import StateFn, OperatorBase
+from qiskit.utils.deprecation import deprecate_function
 from ..algorithm_result import AlgorithmResult
 
 
 class EvolutionResult(AlgorithmResult):
-    """Class for holding evolution result."""
+    """Pending deprecation: Class for holding evolution result.
 
+    The EvolutionResult class has been superseded by the
+    :class:`qiskit.algorithms.time_evolvers.TimeEvolutionResult` class.
+    This class will be deprecated in a future release and subsequently
+    removed after that.
+
+    """
+
+    @deprecate_function(
+        "The EvolutionResult class has been superseded by the "
+        "qiskit.algorithms.time_evolvers.TimeEvolutionResult class. "
+        "This class will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def __init__(
         self,
         evolved_state: Union[StateFn, QuantumCircuit, OperatorBase],

qiskit/algorithms/evolvers/imaginary_evolver.py

@@ -14,12 +14,30 @@
 
 from abc import ABC, abstractmethod
 
+from qiskit.utils.deprecation import deprecate_function
 from .evolution_problem import EvolutionProblem
 from .evolution_result import EvolutionResult
 
 
 class ImaginaryEvolver(ABC):
-    """Interface for Quantum Imaginary Time Evolution."""
+    """Pending deprecation: Interface for Quantum Imaginary Time Evolution.
+
+    The ImaginaryEvolver interface has been superseded by the
+    :class:`qiskit.algorithms.time_evolvers.ImaginaryTimeEvolver` interface.
+    This interface will be deprecated in a future release and subsequently
+    removed after that.
+
+    """
+
+    @deprecate_function(
+        "The ImaginaryEvolver interface has been superseded by the "
+        "qiskit.algorithms.time_evolvers.ImaginaryTimeEvolver interface. "
+        "This interface will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
+    def __init__(self) -> None:
+        pass
 
     @abstractmethod
     def evolve(self, evolution_problem: EvolutionProblem) -> EvolutionResult:

qiskit/algorithms/evolvers/pvqd/pvqd.py

@@ -149,6 +149,7 @@ def __init__(
                 a random vector with elements in the interval :math:`[-0.01, 0.01]`.
             quantum_instance: The backend or quantum instance used to evaluate the circuits.
         """
+        super().__init__()
         if evolution is None:
             evolution = LieTrotter()
 

qiskit/algorithms/evolvers/real_evolver.py

@@ -13,13 +13,31 @@
 """Interface for Quantum Real Time Evolution."""
 
 from abc import ABC, abstractmethod
+from qiskit.utils.deprecation import deprecate_function
 
 from .evolution_problem import EvolutionProblem
 from .evolution_result import EvolutionResult
 
 
 class RealEvolver(ABC):
-    """Interface for Quantum Real Time Evolution."""
+    """Pending deprecation: Interface for Quantum Real Time Evolution.
+
+    The RealEvolver interface has been superseded by the
+    :class:`qiskit.algorithms.time_evolvers.RealTimeEvolver` interface.
+    This interface will be deprecated in a future release and subsequently
+    removed after that.
+
+    """
+
+    @deprecate_function(
+        "The RealEvolver interface has been superseded by the "
+        "qiskit.algorithms.time_evolvers.RealTimeEvolver interface. "
+        "This interface will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
+    def __init__(self) -> None:
+        pass
 
     @abstractmethod
     def evolve(self, evolution_problem: EvolutionProblem) -> EvolutionResult:

qiskit/algorithms/evolvers/trotterization/trotter_qrte.py

@@ -13,6 +13,7 @@
 """An algorithm to implement a Trotterization real time-evolution."""
 
 from typing import Union, Optional
+import warnings
 
 from qiskit import QuantumCircuit
 from qiskit.algorithms.aux_ops_evaluator import eval_observables
@@ -32,10 +33,17 @@
 from qiskit.providers import Backend
 from qiskit.synthesis import ProductFormula, LieTrotter
 from qiskit.utils import QuantumInstance
+from qiskit.utils.deprecation import deprecate_function
 
 
 class TrotterQRTE(RealEvolver):
-    """Quantum Real Time Evolution using Trotterization.
+    """Pending deprecation: Quantum Real Time Evolution using Trotterization.
+
+    The TrotterQRTE class has been superseded by the
+    :class:`qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE` class.
+    This class will be deprecated in a future release and subsequently
+    removed after that.
+
     Type of Trotterization is defined by a ProductFormula provided.
 
     Examples:
@@ -58,6 +66,13 @@ class TrotterQRTE(RealEvolver):
             evolved_state = trotter_qrte.evolve(evolution_problem).evolved_state
     """
 
+    @deprecate_function(
+        "The TrotterQRTE class has been superseded by the "
+        "qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE class. "
+        "This class will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def __init__(
         self,
         product_formula: Optional[ProductFormula] = None,
@@ -73,6 +88,9 @@ def __init__(
             quantum_instance: A quantum instance used for calculating expectation values of
                 EvolutionProblem.aux_operators.
         """
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            super().__init__()
         if product_formula is None:
             product_formula = LieTrotter()
         self._product_formula = product_formula

qiskit/algorithms/time_evolvers/__init__.py

@@ -0,0 +1,11 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.

qiskit/algorithms/time_evolvers/imaginary_time_evolver.py

@@ -0,0 +1,37 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021, 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Interface for Quantum Imaginary Time Evolution."""
+
+from abc import ABC, abstractmethod
+
+from .time_evolution_problem import TimeEvolutionProblem
+from .time_evolution_result import TimeEvolutionResult
+
+
+class ImaginaryTimeEvolver(ABC):
+    """Interface for Quantum Imaginary Time Evolution."""
+
+    @abstractmethod
+    def evolve(self, evolution_problem: TimeEvolutionProblem) -> TimeEvolutionResult:
+        r"""Perform imaginary time evolution :math:`\exp(-\tau H)|\Psi\rangle`.
+
+        Evolves an initial state :math:`|\Psi\rangle` for an imaginary time :math:`\tau`
+        under a Hamiltonian  :math:`H`, as provided in the ``evolution_problem``.
+
+        Args:
+            evolution_problem: The definition of the evolution problem.
+
+        Returns:
+            Evolution result which includes an evolved quantum state.
+        """
+        raise NotImplementedError()

qiskit/algorithms/time_evolvers/real_time_evolver.py

@@ -0,0 +1,37 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021, 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Interface for Quantum Real Time Evolution."""
+
+from abc import ABC, abstractmethod
+
+from .time_evolution_problem import TimeEvolutionProblem
+from .time_evolution_result import TimeEvolutionResult
+
+
+class RealTimeEvolver(ABC):
+    """Interface for Quantum Real Time Evolution."""
+
+    @abstractmethod
+    def evolve(self, evolution_problem: TimeEvolutionProblem) -> TimeEvolutionResult:
+        r"""Perform real time evolution :math:`\exp(-i t H)|\Psi\rangle`.
+
+        Evolves an initial state :math:`|\Psi\rangle` for a time :math:`t`
+        under a Hamiltonian  :math:`H`, as provided in the ``evolution_problem``.
+
+        Args:
+            evolution_problem: The definition of the evolution problem.
+
+        Returns:
+            Evolution result which includes an evolved quantum state.
+        """
+        raise NotImplementedError()