Adds execute_with_qse, qse_decorator and mitigate_executor

mitiq/qse/__init__.py

@@ -3,4 +3,8 @@
 # This source code is licensed under the GPL license (v3) found in the
 # LICENSE file in the root directory of this source tree.
 
-from mitiq.qse.qse_utils import get_projector
+from mitiq.qse.qse import execute_with_qse, mitigate_executor, qse_decorator
+from mitiq.qse.qse_utils import (
+    get_projector,
+    get_expectation_value_for_observable,
+)

mitiq/qse/qse.py

@@ -0,0 +1,163 @@
+# Copyright (C) 2021 Unitary Fund
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""High-level Quantum Susbapce Expansion tools."""
+
+from typing import Callable, Sequence, Dict, List
+from mitiq import Executor, Observable, QPROGRAM, QuantumResult, PauliString
+from functools import wraps
+from .qse_utils import get_projector, get_expectation_value_for_observable
+
+
+def execute_with_qse(
+    circuit: QPROGRAM,
+    executor: Callable[[QPROGRAM], QuantumResult],
+    check_operators: Sequence[PauliString],
+    code_hamiltonian: Observable,
+    observable: Observable,
+    pauli_string_to_expectation_cache: Dict[PauliString, complex] = {},
+) -> float:
+    """Function for the calculation of an observable from some circuit of
+        interest to be mitigated with Quantum Subspace Expansion
+    Args:
+        circuit: Quantum program to execute with error mitigation.
+        executor: Executes a circuit and returns a `QuantumResult`.
+        check_operators: List of check operators that define the
+        stabilizer code space.
+        code_hamiltonian: Hamiltonian of the code space.
+        observable: Observable to compute the mitigated expectation value of.
+        pauli_string_to_expectation_cache: Cache for expectation values of
+        Pauli strings used to compute the projector and the observable.
+    Returns:
+        The expectation value estimated with QSE.
+    """
+    P = get_projector(
+        circuit,
+        executor,
+        check_operators,
+        code_hamiltonian,
+        pauli_string_to_expectation_cache,
+    )
+    # Compute the expectation value of the observable: <P O P>
+    pop = get_expectation_value_for_observable(
+        circuit,
+        executor,
+        P * observable * P,
+        pauli_string_to_expectation_cache,
+    )
+    # Compute the normalization factor: <P P>
+    pp = get_expectation_value_for_observable(
+        circuit, executor, P * P, pauli_string_to_expectation_cache
+    )
+    return pop / pp
+
+
+def mitigate_executor(
+    executor: Callable[[QPROGRAM], QuantumResult],
+    check_operators: Sequence[PauliString],
+    code_hamiltonian: Observable,
+    observable: Observable,
+    pauli_string_to_expectation_cache: Dict[PauliString, complex] = {},
+) -> Callable[[QPROGRAM], float]:
+    """Returns a modified version of the input 'executor' which is
+    error-mitigated with zero-noise extrapolation (ZNE).
+
+    Args:
+        circuit: Quantum program to execute with error mitigation.
+        executor: Executes a circuit and returns a `QuantumResult`.
+        check_operators: List of check operators that define the
+        stabilizer code space.
+        code_hamiltonian: Hamiltonian of the code space.
+        observable: Observable to compute the mitigated expectation value of.
+        pauli_string_to_expectation_cache: Cache for expectation values of
+        Pauli strings used to compute the projector and the observable.
+        share_cache: Only applicable for batched executors. If True, the
+        cache is shared between the all circuits in the batch.
+    Returns:
+        The error-mitigated version of the input executor.
+    """
+    executor_obj = Executor(executor)
+    if not executor_obj.can_batch:
+
+        @wraps(executor)
+        def new_executor(circuit: QPROGRAM) -> float:
+            return execute_with_qse(
+                circuit,
+                executor,
+                check_operators,
+                code_hamiltonian,
+                observable,
+                pauli_string_to_expectation_cache,
+            )
+
+    else:
+
+        @wraps(executor)
+        def new_executor(circuits: List[QPROGRAM]) -> List[float]:
+            return [
+                execute_with_qse(
+                    circuit,
+                    executor,
+                    check_operators,
+                    code_hamiltonian,
+                    observable,
+                    pauli_string_to_expectation_cache,
+                )
+                for circuit in circuits
+            ]
+
+    return new_executor
+
+
+def qse_decorator(
+    check_operators: Sequence[PauliString],
+    code_hamiltonian: Observable,
+    observable: Observable,
+    pauli_string_to_expectation_cache: Dict[PauliString, complex] = {},
+) -> Callable[
+    [Callable[[QPROGRAM], QuantumResult]], Callable[[QPROGRAM], float]
+]:
+    """Decorator which adds an error-mitigation layer based on quantum
+    subspace expansion (QSE) to an executor function, i.e., a function which
+    executes a quantum circuit with an arbitrary backend and returns a
+    ``QuantumResult``.
+
+    Args:
+        check_operators: List of check operators that define the
+        stabilizer code space.
+        code_hamiltonian: Hamiltonian of the code space.
+        observable: Observable to compute the mitigated expectation value of.
+        pauli_string_to_expectation_cache: Cache for expectation values of
+        Pauli strings used to compute the projector and the observable.
+        share_cache: Only applicable for batched executors. If True, the
+        cache is shared between the all circuits in the batch.
+
+    Returns:
+        The error-mitigating decorator to be applied to an executor function.
+    """
+
+    def decorator(
+        executor: Callable[[QPROGRAM], QuantumResult]
+    ) -> Callable[[QPROGRAM], float]:
+        val = mitigate_executor(
+            executor,
+            check_operators,
+            code_hamiltonian,
+            observable,
+            pauli_string_to_expectation_cache,
+        )
+        return val
+
+    return decorator

mitiq/qse/qse_utils.py

@@ -5,9 +5,8 @@
 
 """Functions for computing the projector for subspace expansion."""
 
-from typing import Callable, Sequence, Union
+from typing import Callable, Sequence, Union, Dict
 from mitiq import Observable, QPROGRAM, QuantumResult, PauliString
-from typing import Dict
 import numpy as np
 import numpy.typing as npt
 from scipy.linalg import eigh
@@ -19,13 +18,13 @@ def get_projector(
     executor: Callable[[QPROGRAM], QuantumResult],
     check_operators: Sequence[PauliString],
     code_hamiltonian: Observable,
+    pauli_string_to_expectation_cache: Dict[PauliString, complex] = {},
 ) -> Observable:
     """Computes the projector onto the code space defined by the
     check_operators provided that minimizes the code_hamiltonian.
 
     Returns: Projector as an Observable.
     """
-    pauli_string_to_expectation_cache: Dict[PauliString, complex] = {}
     S = _compute_overlap_matrix(
         circuit, executor, check_operators, pauli_string_to_expectation_cache
     )
@@ -48,12 +47,18 @@ def get_projector(
     return projector
 
 
-def _get_expectation_value_for_observable(
+def get_expectation_value_for_observable(
     circuit: QPROGRAM,
     executor: Callable[[QPROGRAM], QuantumResult],
     observable: Union[PauliString, Observable],
     pauli_string_to_expectation_cache: Dict[PauliString, complex] = {},
 ) -> float:
+    """Provide pauli_string_to_expectation_cache if you want to take advantage
+    of caching.
+
+    This function modifies pauli_string_to_expectation_cache in place.
+    """
+
     def get_expectation_value_for_one_pauli(
         pauli_string: PauliString,
     ) -> float:
@@ -91,7 +96,7 @@ def _compute_overlap_matrix(
     for i in range(len(check_operators)):
         S.append([])
         for j in range(len(check_operators)):
-            sij = _get_expectation_value_for_observable(
+            sij = get_expectation_value_for_observable(
                 circuit,
                 executor,
                 check_operators[i] * check_operators[j],
@@ -114,7 +119,7 @@ def _compute_hamiltonian_overlap_matrix(
         H.append([])
         for j in range(len(check_operators)):
             H[-1].append(
-                _get_expectation_value_for_observable(
+                get_expectation_value_for_observable(
                     circuit,
                     executor,
                     check_operators[i] * code_hamiltonian * check_operators[j],