Add interfaces for a general Quantum Time Evolution Framework (Qiskit…

…#7858)

* Revert "Revert "Implemented general Quantum Time Evolution Framework interfaces. (Qiskit#7669)" (Qiskit#7845)"

This reverts commit 12ab98d.

Co-authored-by: dlasecki <dal@zurich.ibm.com>

* remove Evolver base class

* Don't import list or dict from MES

Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>

* fix import order

Co-authored-by: dlasecki <dal@zurich.ibm.com>
Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>

qiskit/algorithms/__init__.py

@@ -93,6 +93,22 @@
    NumPyEigensolver
 
 
+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.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+    RealEvolver
+    ImaginaryEvolver
+    EvolutionResult
+    EvolutionProblem
+
 Factorizers
 -----------
 
@@ -188,6 +204,9 @@
 """
 
 from .algorithm_result import AlgorithmResult
+from .evolvers import EvolutionResult, EvolutionProblem
+from .evolvers.real.real_evolver import RealEvolver
+from .evolvers.imaginary.imaginary_evolver import ImaginaryEvolver
 from .variational_algorithm import VariationalAlgorithm, VariationalResult
 from .amplitude_amplifiers import Grover, GroverResult, AmplificationProblem, AmplitudeAmplifier
 from .amplitude_estimators import (
@@ -245,6 +264,10 @@
     "MaximumLikelihoodAmplitudeEstimationResult",
     "EstimationProblem",
     "NumPyEigensolver",
+    "RealEvolver",
+    "ImaginaryEvolver",
+    "EvolutionResult",
+    "EvolutionProblem",
     "LinearSolverResult",
     "Eigensolver",
     "EigensolverResult",

qiskit/algorithms/aux_ops_evaluator.py

@@ -16,7 +16,6 @@
 import numpy as np
 
 from qiskit import QuantumCircuit
-from qiskit.algorithms.eigen_solvers.eigen_solver import ListOrDict
 from qiskit.opflow import (
     CircuitSampler,
     ListOp,
@@ -28,6 +27,8 @@
 from qiskit.quantum_info import Statevector
 from qiskit.utils import QuantumInstance
 
+from .list_or_dict import ListOrDict
+
 
 def eval_observables(
     quantum_instance: Union[QuantumInstance, BaseBackend, Backend],

qiskit/algorithms/eigen_solvers/eigen_solver.py

@@ -13,15 +13,13 @@
 """The Eigensolver interface"""
 
 from abc import ABC, abstractmethod
-from typing import Dict, Optional, List, Union, Tuple, TypeVar
+from typing import Optional, List, Tuple
 
 import numpy as np
+
 from qiskit.opflow import OperatorBase
 from ..algorithm_result import AlgorithmResult
-
-# Introduced new type to maintain readability.
-_T = TypeVar("_T")  # Pylint does not allow single character class names.
-ListOrDict = Union[List[Optional[_T]], Dict[str, _T]]
+from ..list_or_dict import ListOrDict
 
 
 class Eigensolver(ABC):

qiskit/algorithms/eigen_solvers/numpy_eigen_solver.py

@@ -21,7 +21,8 @@
 from qiskit.opflow import I, ListOp, OperatorBase, StateFn
 from qiskit.utils.validation import validate_min
 from ..exceptions import AlgorithmError
-from .eigen_solver import Eigensolver, EigensolverResult, ListOrDict
+from .eigen_solver import Eigensolver, EigensolverResult
+from ..list_or_dict import ListOrDict
 
 logger = logging.getLogger(__name__)
 

qiskit/algorithms/evolvers/__init__.py

@@ -0,0 +1,21 @@
+# 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.
+
+"""Quantum Time Evolution package."""
+
+from .evolution_result import EvolutionResult
+from .evolution_problem import EvolutionProblem
+
+__all__ = [
+    "EvolutionResult",
+    "EvolutionProblem",
+]

qiskit/algorithms/evolvers/evolution_problem.py

@@ -0,0 +1,58 @@
+# 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.
+
+"""Evolution problem class."""
+
+from typing import Union, Optional, Dict
+
+from qiskit import QuantumCircuit
+from qiskit.circuit import Parameter
+from qiskit.opflow import OperatorBase, StateFn
+from ..list_or_dict import ListOrDict
+
+
+class EvolutionProblem:
+    """Evolution problem class.
+
+    This class is the input to time evolution algorithms and contains
+    information on e.g. the total evolution time and under which Hamiltonian
+    the state is evolved.
+    """
+
+    def __init__(
+        self,
+        hamiltonian: OperatorBase,
+        time: float,
+        initial_state: Union[StateFn, QuantumCircuit],
+        aux_operators: Optional[ListOrDict[OperatorBase]] = None,
+        t_param: Optional[Parameter] = None,
+        hamiltonian_value_dict: Optional[Dict[Parameter, Union[complex]]] = None,
+    ):
+        """
+        Args:
+            hamiltonian: The Hamiltonian under which to evolve the system.
+            time: Total time of evolution.
+            initial_state: Quantum state to be evolved.
+            aux_operators: Optional list of auxiliary operators to be evaluated with the
+                evolved ``initial_state`` and their expectation values returned.
+            t_param: Time parameter in case of a time-dependent Hamiltonian. This
+                free parameter must be within the ``hamiltonian``.
+            hamiltonian_value_dict: If the Hamiltonian contains free parameters, this
+                dictionary maps all these parameters to values.
+        """
+
+        self.hamiltonian = hamiltonian
+        self.time = time
+        self.initial_state = initial_state
+        self.aux_operators = aux_operators
+        self.t_param = t_param
+        self.hamiltonian_value_dict = hamiltonian_value_dict

qiskit/algorithms/evolvers/evolution_result.py

@@ -0,0 +1,40 @@
+# 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.
+
+"""Class for holding evolution result."""
+
+from typing import Optional, Union, Tuple
+
+from qiskit import QuantumCircuit
+from qiskit.algorithms.list_or_dict import ListOrDict
+from qiskit.opflow import StateFn
+from ..algorithm_result import AlgorithmResult
+
+
+class EvolutionResult(AlgorithmResult):
+    """Class for holding evolution result."""
+
+    def __init__(
+        self,
+        evolved_state: Union[StateFn, QuantumCircuit],
+        aux_ops_evaluated: Optional[ListOrDict[Tuple[complex, complex]]] = None,
+    ):
+        """
+        Args:
+            evolved_state: An evolved quantum state.
+            aux_ops_evaluated: Optional list of observables for which expected values on an evolved
+                state are calculated. These values are in fact tuples formatted as (mean, standard
+                deviation).
+        """
+
+        self.evolved_state = evolved_state
+        self.aux_ops_evaluated = aux_ops_evaluated

qiskit/algorithms/evolvers/imaginary/__init__.py

@@ -0,0 +1,11 @@
+# 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.

qiskit/algorithms/evolvers/imaginary/imaginary_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 ..evolution_problem import EvolutionProblem
+from ..evolution_result import EvolutionResult
+
+
+class ImaginaryEvolver(ABC):
+    """Interface for Quantum Imaginary Time Evolution."""
+
+    @abstractmethod
+    def evolve(self, evolution_problem: EvolutionProblem) -> EvolutionResult:
+        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/evolvers/real/__init__.py

@@ -0,0 +1,11 @@
+# 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.

qiskit/algorithms/evolvers/real/real_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 ..evolution_problem import EvolutionProblem
+from ..evolution_result import EvolutionResult
+
+
+class RealEvolver(ABC):
+    """Interface for Quantum Real Time Evolution."""
+
+    @abstractmethod
+    def evolve(self, evolution_problem: EvolutionProblem) -> EvolutionResult:
+        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()

qiskit/algorithms/list_or_dict.py

@@ -0,0 +1,18 @@
+# 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.
+
+"""Introduced new type to maintain readability."""
+
+from typing import TypeVar, List, Union, Optional, Dict
+
+_T = TypeVar("_T")  # Pylint does not allow single character class names.
+ListOrDict = Union[List[Optional[_T]], Dict[str, _T]]

qiskit/algorithms/minimum_eigen_solvers/minimum_eigen_solver.py

@@ -13,15 +13,13 @@
 """The Minimum Eigensolver interface"""
 
 from abc import ABC, abstractmethod
-from typing import Dict, Optional, List, Union, Tuple, TypeVar
+from typing import Optional, Tuple
 
 import numpy as np
+
 from qiskit.opflow import OperatorBase
 from ..algorithm_result import AlgorithmResult
-
-# Introduced new type to maintain readability.
-_T = TypeVar("_T")  # Pylint does not allow single character class names.
-ListOrDict = Union[List[Optional[_T]], Dict[str, _T]]
+from ..list_or_dict import ListOrDict
 
 
 class MinimumEigensolver(ABC):

qiskit/algorithms/minimum_eigen_solvers/numpy_minimum_eigen_solver.py

@@ -18,7 +18,8 @@
 
 from qiskit.opflow import OperatorBase
 from ..eigen_solvers.numpy_eigen_solver import NumPyEigensolver
-from .minimum_eigen_solver import MinimumEigensolver, MinimumEigensolverResult, ListOrDict
+from .minimum_eigen_solver import MinimumEigensolver, MinimumEigensolverResult
+from ..list_or_dict import ListOrDict
 
 logger = logging.getLogger(__name__)
 

qiskit/algorithms/minimum_eigen_solvers/vqe.py

@@ -40,9 +40,10 @@
 from qiskit.utils.validation import validate_min
 from qiskit.utils.backend_utils import is_aer_provider
 from qiskit.utils import QuantumInstance, algorithm_globals
+from ..list_or_dict import ListOrDict
 from ..optimizers import Optimizer, SLSQP, OptimizerResult
 from ..variational_algorithm import VariationalAlgorithm, VariationalResult
-from .minimum_eigen_solver import MinimumEigensolver, MinimumEigensolverResult, ListOrDict
+from .minimum_eigen_solver import MinimumEigensolver, MinimumEigensolverResult
 from ..exceptions import AlgorithmError
 from ..aux_ops_evaluator import eval_observables
 

test/python/algorithms/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.