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,169 @@
+# 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 QPROGRAM, 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[
+ [QPROGRAM, float], QPROGRAM
+ ] = fold_gates_at_random, # type: ignore [has-type]
+ 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 value required for unitary folding which
+ is used to generate the scale factor vectors.
+ 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
+ if not len(lre_exp_values) == len( # pragma: no cover
+ linear_combination_coeffs
+ ):
+ raise AssertionError(
+ "The number of expectation values are not equal "
+ + "to the number of coefficients required for "
+ + "multivariate extrapolation."
+ )
+
+ 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,139 @@
+"""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."""
+ 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)
+ideal_val = execute(test_cirq, noise_level=0)
+
+
+@pytest.mark.parametrize(
+ "input_degree, input_fold_multiplier", [(2, 2), (2, 3), (3, 4)]
+)
+def test_lre_exp_value(input_degree, input_fold_multiplier):
+ """Verify LRE executors work as expected."""
+ assert abs(ideal_val - noisy_val) > 0
+ lre_exp_val = execute_with_lre(
+ test_cirq,
+ execute,
+ degree=input_degree,
+ fold_multiplier=input_fold_multiplier,
+ )
+ assert abs(lre_exp_val - ideal_val) <= abs(noisy_val - ideal_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 abs(exp_val_from_mitigate_executor - ideal_val) <= abs(
+ noisy_val - ideal_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 abs(execute(test_cirq) - ideal_val) <= abs(noisy_val - ideal_val)
+
+
+def test_lre_decorator_raised_error():
+ """Verify an error is raised when the required 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 abs(execute(test_cirq) - ideal_val) <= abs(
+ noisy_val - ideal_val
+ )
+
+
+def test_lre_executor_with_chunking():
+ """Verify the executor works as expected for chunking a large circuit into
+ a smaller circuit."""
+ # define a larger circuit
+ test_cirq = benchmarks.generate_rb_circuits(n_qubits=1, num_cliffords=12)[
+ 0
+ ]
+ 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, num_chunks=10
+ )
+ assert abs(lre_exp_val - ideal_val) <= abs(noisy_val - ideal_val)
+
+
+@pytest.mark.parametrize(
+ "test_input", [(1), (2), (3), (4), (5), (6), (7), (8), (9)]
+)
+@pytest.mark.xfail
+def test_lre_executor_with_chunking_failures(test_input):
+ """Verify chunking fails when a large number of layers are chunked into a
+ smaller number of circuit layers."""
+ # define a larger circuit
+ test_cirq = benchmarks.generate_rb_circuits(n_qubits=1, num_cliffords=15)[
+ 0
+ ]
+ 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, num_chunks=test_input
+ )
+ assert abs(lre_exp_val - ideal_val) <= abs(noisy_val - ideal_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 abs(lre_exp_val - ideal_val) <= abs(noisy_val - ideal_val)