LRE Executors

.gitignore

@@ -15,7 +15,7 @@ mitiq.egg-info/
 dist/
 build/
 jupyter_execute/
-
+.mypy_cache/
 # Coverage reports
 coverage.xml
 .coverage

docs/source/apidoc.md

@@ -89,6 +89,11 @@ See Ref. {cite}`Czarnik_2021_Quantum` for more details on these methods.
 
 ### Layerwise Richardson Extrapolation
 
+```{eval-rst}
+.. automodule:: mitiq.lre.lre
+   :members:
+```
+
 ```{eval-rst}
 .. automodule:: mitiq.lre.multivariate_scaling.layerwise_folding
    :members:

mitiq/lre/__init__.py

@@ -10,4 +10,6 @@
 from mitiq.lre.inference.multivariate_richardson import (
     multivariate_richardson_coefficients,
     sample_matrix,
-)
+)
+
+from mitiq.lre.lre import execute_with_lre, mitigate_executor, lre_decorator

mitiq/lre/lre.py

@@ -0,0 +1,161 @@
+# Copyright (C) Unitary Fund
+#
+# This source code is licensed under the GPL license (v3) found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Extrapolation methods for Layerwise Richardson Extrapolation (LRE)"""
+
+from functools import wraps
+from typing import Any, Callable, Optional, Union
+
+import numpy as np
+from cirq import Circuit
+
+from mitiq import QuantumResult
+from mitiq.lre import (
+    multivariate_layer_scaling,
+    multivariate_richardson_coefficients,
+)
+from mitiq.zne.scaling import fold_gates_at_random
+
+
+def execute_with_lre(
+    input_circuit: Circuit,
+    executor: Callable[[Circuit], QuantumResult],
+    degree: int,
+    fold_multiplier: int,
+    folding_method: Callable[
+        [Union[Any], float], Union[Any]
+    ] = fold_gates_at_random,
+    num_chunks: Optional[int] = None,
+) -> float:
+    r"""
+    Defines the executor required for Layerwise Richardson
+    Extrapolation as defined in :cite:`Russo_2024_LRE`.
+
+    Note that this method only works for the multivariate extrapolation
+    methods. It does not allows a user to choose which layers in the input
+    circuit will be scaled.
+
+    .. seealso::
+
+        If you would prefer to choose the layers for unitary
+        folding, use :func:`mitiq.zne.scaling.layer_scaling.get_layer_folding`
+        instead.
+
+    Args:
+        input_circuit: Circuit to be scaled.
+        executor: Executes a circuit and returns a `QuantumResult`
+        degree: Degree of the multivariate polynomial.
+        fold_multiplier: Scaling gap required by unitary folding.
+        folding_method: Unitary folding method. Default is
+            :func:`fold_gates_at_random`.
+        num_chunks: Number of desired approximately equal chunks. When the
+            number of chunks is the same as the layers in the input circuit,
+            the input circuit is unchanged.
+
+
+    Returns:
+        Error-mitigated expectation value
+
+    """
+    noise_scaled_circuits = multivariate_layer_scaling(
+        input_circuit, degree, fold_multiplier, num_chunks, folding_method
+    )
+    linear_combination_coeffs = multivariate_richardson_coefficients(
+        input_circuit, degree, fold_multiplier, num_chunks
+    )
+
+    lre_exp_values = []
+    for scaled_circuit in noise_scaled_circuits:
+        circ_exp_val = executor(scaled_circuit)
+        lre_exp_values.append(circ_exp_val)
+
+    # verify the linear combination coefficients and the calculated expectation
+    # values have the same length
+    assert len(lre_exp_values) == len(linear_combination_coeffs)
+
+    return np.dot(lre_exp_values, linear_combination_coeffs)
+
+
+def mitigate_executor(
+    executor: Callable[[Circuit], QuantumResult],
+    degree: int,
+    fold_multiplier: int,
+    folding_method: Callable[
+        [Union[Any], float], Union[Any]
+    ] = fold_gates_at_random,
+    num_chunks: Optional[int] = None,
+) -> Callable[[Circuit], float]:
+    """Returns a modified version of the input `executor` which is
+    error-mitigated with layerwise richardson extrapolation (LRE).
+
+    Args:
+    input_circuit: Circuit to be scaled.
+    executor: Executes a circuit and returns a `QuantumResult`
+    degree: Degree of the multivariate polynomial.
+    fold_multiplier: Scaling gap required by unitary folding.
+    folding_method: Unitary folding method. Default is
+        :func:`fold_gates_at_random`.
+    num_chunks: Number of desired approximately equal chunks. When the
+        number of chunks is the same as the layers in the input circuit,
+        the input circuit is unchanged.
+
+
+    Returns:
+        Error-mitigated version of the circuit executor.
+    """
+
+    @wraps(executor)
+    def new_executor(input_circuit: Circuit) -> float:
+        return execute_with_lre(
+            input_circuit,
+            executor,
+            degree,
+            fold_multiplier,
+            folding_method,
+            num_chunks,
+        )
+
+    return new_executor
+
+
+def lre_decorator(
+    degree: int,
+    fold_multiplier: int,
+    folding_method: Callable[[Circuit, float], Circuit] = fold_gates_at_random,
+    num_chunks: Optional[int] = None,
+) -> Callable[
+    [Callable[[Circuit], QuantumResult]], Callable[[Circuit], float]
+]:
+    """Decorator which adds an error-mitigation layer based on
+    layerwise richardson extrapolation (LRE).
+
+    Args:
+    input_circuit: Circuit to be scaled.
+    executor: Executes a circuit and returns a `QuantumResult`
+    degree: Degree of the multivariate polynomial.
+    fold_multiplier: Scaling gap required by unitary folding.
+    folding_method: Unitary folding method. Default is
+        :func:`fold_gates_at_random`.
+    num_chunks: Number of desired approximately equal chunks. When the
+        number of chunks is the same as the layers in the input circuit,
+        the input circuit is unchanged.
+
+
+    Returns:
+        Error-mitigated decorator.
+    """
+
+    def decorator(
+        executor: Callable[[Circuit], QuantumResult],
+    ) -> Callable[[Circuit], float]:
+        return mitigate_executor(
+            executor,
+            degree,
+            fold_multiplier,
+            folding_method,
+            num_chunks,
+        )
+
+    return decorator

mitiq/lre/tests/test_lre.py

@@ -0,0 +1,107 @@
+"""Unit tests for the LRE extrapolation methods."""
+
+import re
+
+import pytest
+from cirq import DensityMatrixSimulator, depolarize
+
+from mitiq import benchmarks
+from mitiq.lre import execute_with_lre, lre_decorator, mitigate_executor
+from mitiq.zne.scaling import fold_all, fold_global
+
+# default circuit for all unit tests
+test_cirq = benchmarks.generate_rb_circuits(
+    n_qubits=1,
+    num_cliffords=2,
+)[0]
+
+
+def execute(circuit, noise_level=0.025):
+    """Default executor for all unit tests."""
+    # Replace with code based on your frontend and backend.
+    noisy_circuit = circuit.with_noise(depolarize(p=noise_level))
+    rho = DensityMatrixSimulator().simulate(noisy_circuit).final_density_matrix
+    return rho[0, 0].real
+
+
+noisy_val = execute(test_cirq)
+
+
+def test_lre_exp_value():
+    """Verify LRE executors work as expected."""
+    ideal_val = execute(test_cirq, noise_level=0)
+    assert abs(ideal_val - noisy_val) > 0
+    lre_exp_val = execute_with_lre(
+        test_cirq, execute, degree=2, fold_multiplier=2
+    )
+    assert lre_exp_val > noisy_val
+
+    # verify the mitigated decorator work as expected
+    mitigated_executor = mitigate_executor(
+        execute, degree=2, fold_multiplier=2
+    )
+    exp_val_from_mitigate_executor = mitigated_executor(test_cirq)
+    assert exp_val_from_mitigate_executor > noisy_val
+
+
+def test_lre_decorator():
+    """Verify LRE decorators work as expected."""
+
+    @lre_decorator(degree=2, fold_multiplier=2)
+    def execute(circuit, noise_level=0.025):
+        mitiq_circuit = circuit
+        noisy_circuit = mitiq_circuit.with_noise(depolarize(p=noise_level))
+        rho = (
+            DensityMatrixSimulator()
+            .simulate(noisy_circuit)
+            .final_density_matrix
+        )
+        return rho[0, 0].real
+
+    assert noisy_val < execute(test_cirq)
+
+
+def test_lre_decorator_raised_error():
+    """Verify error is raised when the defualt parameters for the decorator are
+    not specified."""
+    with pytest.raises(TypeError, match=re.escape("lre_decorator() missing")):
+
+        @lre_decorator()
+        def execute(circuit, noise_level=0.025):
+            mitiq_circuit = circuit
+            noisy_circuit = mitiq_circuit.with_noise(depolarize(p=noise_level))
+            rho = (
+                DensityMatrixSimulator()
+                .simulate(noisy_circuit)
+                .final_density_matrix
+            )
+            return rho[0, 0].real
+
+        assert noisy_val < execute(test_cirq)
+
+
+def test_lre_executor_with_chunking():
+    """Verify the executor works as expected for chunking a large circuit into
+    a smaller circuit."""
+    ideal_val = execute(test_cirq * 20, noise_level=0)
+    assert abs(ideal_val - noisy_val) > 0
+    lre_exp_val = execute_with_lre(
+        test_cirq, execute, degree=2, fold_multiplier=2, num_chunks=5
+    )
+    assert lre_exp_val > noisy_val
+
+
+@pytest.mark.parametrize("input_method", [(fold_global), (fold_all)])
+def test_lre_executor_with_different_folding_methods(input_method):
+    """Verify the executor works as expected for using non-default unitary
+    folding methods."""
+    ideal_val = execute(test_cirq, noise_level=0)
+    assert abs(ideal_val - noisy_val) > 0
+    lre_exp_val = execute_with_lre(
+        test_cirq,
+        execute,
+        degree=2,
+        fold_multiplier=2,
+        folding_method=input_method,
+    )
+    assert lre_exp_val > noisy_val