From 42779eda439778e821da513dcd1e21af94b86739 Mon Sep 17 00:00:00 2001 From: jordandsullivan Date: Thu, 25 Apr 2024 14:13:28 -0700 Subject: [PATCH] 2189 remove unused folding functions (#2289) * Removed all instances of fold_from_left and fold_from_right in the zne.scaling subpackage and in tests * Updating typo in .gitignore * Formatting * removed remaining instances of fold_gates_from_left and fold_gates_from_right in testing * reverted accidentally modified .md notebook * formatting * Formatting for notebook md to myst * Remove fold_method as parameter for test * Update docstring to acurately reflect how folding indices are chosen (i.e. randomly) * Uncomment fold_gates_from_left call, as using directives now Co-authored-by: nate stemen * Replace note with note directive Co-authored-by: nate stemen * Removing the id outputs * Switching wording 'deprecated' to 'removed' * Remove parameterization for tests with only one test case, remove unused arguments for fold_method * Formatting * Remove fold_gates_from_left from pennylane demo * Previous commit msg was in error. This commit updates the pennylane example not to use fold_gates_from_left * Change notes to warnings, uncomment fold_gates_from_left and right code * Remove fold_gates_from_right from vqe-pennylane example, formatting * remove folding_method as optional argument to _create_fold_mask --------- Co-authored-by: nate stemen --- .../mitiq-paper/mitiq-paper-codeblocks.md | 133 ++-- .../examples/pennylane-ibmq-backends.md | 4 +- docs/source/examples/vqe-pyquil-demo.ipynb | 6 +- docs/source/guide/zne-3-options.md | 8 +- mitiq/zne/scaling/__init__.py | 2 - mitiq/zne/scaling/folding.py | 206 +------ mitiq/zne/scaling/tests/test_folding.py | 572 ++---------------- mitiq/zne/tests/test_zne.py | 6 - 8 files changed, 89 insertions(+), 848 deletions(-) diff --git a/docs/source/examples/mitiq-paper/mitiq-paper-codeblocks.md b/docs/source/examples/mitiq-paper/mitiq-paper-codeblocks.md index e0f236755a..fa1170460a 100644 --- a/docs/source/examples/mitiq-paper/mitiq-paper-codeblocks.md +++ b/docs/source/examples/mitiq-paper/mitiq-paper-codeblocks.md @@ -11,17 +11,13 @@ kernelspec: name: python3 --- -+++ {"id": "wjnIQWX8d5UY"} - # Mitiq paper codeblocks Codeblocks from the main text of the [Mitiq whitepaper](https://quantum-journal.org/papers/q-2022-08-11-774/) {cite}`LaRose_2022_Quantum` published in [Quantum](https://quantum-journal.org/). -+++ {"id": "DRplhovffVfk"} - **Codeblock 1** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -31,11 +27,9 @@ outputId: 38c2ce43-463f-4ab8-e402-fbc1d5877ce3 # !pip install mitiq --quiet ``` -+++ {"id": "Pghlsxv0fXA2"} - **Codeblock 2** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -44,19 +38,14 @@ outputId: b0419328-2fba-42eb-b27b-a8b20ed24f13 --- import mitiq - mitiq.about() ``` -+++ {"id": "lK7iAVVShWu3"} - **Codeblock 4** -+++ {"id": "IXykFfZ6hYW7"} - > Note: The paper just shows the signature of an executor function, but here we explicitly define one to use in examples. -```{code-cell} ipython3 +```{code-cell} :id: PyPWG95HhYfj import cirq @@ -70,11 +59,9 @@ def executor(circuit: mitiq.QPROGRAM) -> float: ).final_density_matrix[0, 0].real ``` -+++ {"id": "LxQh9Vehh_2Q"} - **Codeblock 5** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -90,15 +77,12 @@ zne_value = zne.execute_with_zne(circuit, executor) print("ZNE value:", zne_value) ``` -+++ {"id": "3Q2MyAxBiW0C"} - **Codeblock 6** -+++ {"id": "CqiFB4q0ib06"} > Note: The paper shows pseudocode; here we show an example. -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -114,15 +98,11 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "VAGU7qZAjKzD"} - **Codeblock 7** -+++ {"id": "-jbnFbQkjN5J"} - > Note: The paper shows pseudocode; here we show an example. -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -145,11 +125,9 @@ pec_value = pec.execute_with_pec( print("\n\nPEC value:", pec_value) ``` -+++ {"id": "UvTIzr0ZfYuI"} - **Codeblock 8** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -164,45 +142,36 @@ circ = cirq.Circuit( print("Original circuit:", circ, sep="\n") ``` -+++ {"id": "_5Q3P1DJfcar"} - **Codeblock 9** -```{code-cell} ipython3 ---- -colab: - base_uri: https://localhost:8080/ -id: tSWVDcJIeuck -outputId: e9d0c874-8814-4da0-c54b-a6881d3e614a ---- +```{warning} +The method `zne.scaling.fold_gates_from_left` has been removed as of v0.36.0. +``` +```python folded = zne.scaling.fold_gates_from_left( circ, scale_factor=2 ) print("Folded circuit:", folded, sep="\n") ``` -+++ {"id": "4ocoSlNIfnV0"} **Codeblock 10** -```{code-cell} ipython3 ---- -colab: - base_uri: https://localhost:8080/ -id: k8gLF_fPfneX -outputId: ac0ee6c0-4ad4-4524-dc3d-7c9a413fe2ba ---- +```{warning} +The method `zne.scaling.fold_gates_from_right` has been removed as of v0.36.0. +``` + +```python folded = zne.scaling.fold_gates_from_right( circ, scale_factor=2 ) print("Folded circuit:", folded, sep="\n") ``` -+++ {"id": "4vZ5JMpVfnyO"} **Codeblock 11** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -213,15 +182,12 @@ folded = zne.scaling.fold_global(circ, scale_factor=3.) print("Folded circuit:", folded, sep="\n") ``` -+++ {"id": "97Jtd6hNk2cg"} - **Codeblock 12** -+++ {"id": "FYJbOqK3k3zT"} > Note: The paper shows pseudocode; here we show an example. -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -239,11 +205,9 @@ print("\nScaled circuit:", scaled, sep="\n") **Codeblock 13** -+++ - > Note: The paper shows pseudocode; here we show an example. -```{code-cell} ipython3 +```{code-cell} from functools import partial from mitiq.zne.scaling import compute_parameter_variance, scale_parameters @@ -263,11 +227,9 @@ zne_value = zne.execute_with_zne( print("ZNE value via parameter noise scaling:", zne_value) ``` -+++ {"id": "ye9I9WLNrGxU"} - **Codeblock 14** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -282,21 +244,17 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "vm3EwufPfn_B"} - **Codeblock 15** -```{code-cell} ipython3 +```{code-cell} :id: AhnilvXffoF2 linear_factory = zne.inference.LinearFactory(scale_factors=[1.0, 2.0, 3.0]) ``` -+++ {"id": "3ubB9KrvfoLo"} - **Codeblock 16** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -311,11 +269,9 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "doyAREdJfoWC"} - **Codeblock 17** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -332,11 +288,9 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "zvIc-aLuGAut"} - **Codeblock 18** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -353,11 +307,9 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "bbaOzdc-GLeM"} - **Codeblock 19** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -387,11 +339,9 @@ zne_value = zne.execute_with_zne( print("ZNE value:", zne_value) ``` -+++ {"id": "t3o-Xc5rGLsR"} - **Codeblock 20** -```{code-cell} ipython3 +```{code-cell} :id: qqndfKFIGLy6 from mitiq import pec @@ -408,11 +358,9 @@ noisy_z = pec.NoisyOperation( ) ``` -+++ {"id": "J0rb6P6XGL42"} - **Codeblock 21 & 22** -```{code-cell} ipython3 +```{code-cell} :id: UsxGtCrAGL-h h_rep = pec.OperationRepresentation( @@ -422,21 +370,17 @@ h_rep = pec.OperationRepresentation( ) ``` -+++ {"id": "D2NVsYKVGMJ-"} - **Codeblock 23** -```{code-cell} ipython3 +```{code-cell} :id: Civ6U2OSGMQV noisy_op, sign, coeff = h_rep.sample() ``` -+++ {"id": "F8Ryo8cGGMWu"} - **Codeblock 24** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -451,19 +395,16 @@ print("Sampled circuit:", sampled, sep="\n") # Run many times to see different > Note: For a runnable code block in which PEC is applied to estimate an expectation value, see _Codeblock 7_. -+++ {"id": "RYh92EfKGMix"} **Codeblock 25 & 26** -+++ {"id": "C6K0VzUCLkcw"} See https://mitiq.readthedocs.io/en/stable/examples/cdr_api.html. -+++ {"id": "T73iRSXLGMud"} **Codeblock 27** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -477,11 +418,9 @@ zne_value = mitigated_executor(circuit) print("ZNE value:", zne_value) ``` -+++ {"id": "042uqn-fMiYj"} - **Codeblock 28** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -499,11 +438,9 @@ zne_value = execute(circuit) print("ZNE value:", zne_value) ``` -+++ {"id": "P5HEyCXwMio8"} - **Codeblock 29** -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ @@ -525,11 +462,9 @@ zne_then_pec_value = execute(circuit3) print("ZNE then PEC value:", zne_then_pec_value) # Note this is not accurate (bad representation). ``` -+++ {"id": "LQYPqUazMi3b"} - **Codeblock 30** -```{code-cell} ipython3 +```{code-cell} :id: dyk7Hj1nPB48 import qiskit @@ -556,7 +491,7 @@ def execute( return counts.get("00", 0.0) / shots ``` -```{code-cell} ipython3 +```{code-cell} --- colab: base_uri: https://localhost:8080/ diff --git a/docs/source/examples/pennylane-ibmq-backends.md b/docs/source/examples/pennylane-ibmq-backends.md index b68ce8d491..91826222b9 100644 --- a/docs/source/examples/pennylane-ibmq-backends.md +++ b/docs/source/examples/pennylane-ibmq-backends.md @@ -159,7 +159,7 @@ Finally, it is perhaps more common to define a circuit using a decorator when yo For this our circuit will be defined as above, but we will use decorators to indicate which device we would like to run it on, and that we would like to error-mitigate it. ```{code-cell} ipython3 -from mitiq.zne.scaling import fold_gates_from_left +from mitiq.zne.scaling import fold_gates_at_random @qml.qnode(dev) @@ -171,7 +171,7 @@ def circuit(): circuit = qml.transforms.mitigate_with_zne( circuit, [1, 2, 3], - fold_gates_from_left, + fold_gates_at_random, RichardsonFactory.extrapolate, ) diff --git a/docs/source/examples/vqe-pyquil-demo.ipynb b/docs/source/examples/vqe-pyquil-demo.ipynb index e36451d438..c4e033e222 100644 --- a/docs/source/examples/vqe-pyquil-demo.ipynb +++ b/docs/source/examples/vqe-pyquil-demo.ipynb @@ -51,7 +51,7 @@ "from scipy import optimize\n", "import mitiq\n", "from mitiq import zne\n", - "from mitiq.zne.scaling.folding import fold_gates_from_right" + "from mitiq.zne.scaling.folding import fold_gates_at_random" ] }, { @@ -429,7 +429,7 @@ " executable,\n", " lambda p: executor(thetas, backend, readout_qubit, samples, pauli_sum, p),\n", " factory=factory,\n", - " scale_noise=fold_gates_from_right,\n", + " scale_noise=fold_gates_at_random,\n", " )\n", " return mitigated_exp" ] @@ -470,7 +470,7 @@ "outputs": [ { "data": { - "image/png": "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HFPk4XKAqiq33nor7dq144ILLmDXrl1F25YsWcK5555Lt27d6NevHxkZGQC88sornHbaaXTq1InLL7+cI0eOBH0+t31HjBjBqFGj6NmzJ23atGHSpEmlynf33XfTvn170tLSiqynnTt3MmjQIDp16kSnTp34/vvvAbjsssvo1q0bHTp04OWXXy46Rq1atbjjjjvo0KEDffr0Yffu3QBs3LiRiy66iG7dunH22Wezdu3asny8hjDhZMmUpGxSEmIcr19e/044qG4WzjTgVhH5ECtoIEtVM0RkBvAvEalrz+sL3BPuk3vvoEtzxoH1Rfr/GLyE04Stjjz82WrWbD/gun3Z75kcLQhU5HdNWsEHC3933Kd90zo89McOQZ3/008/Zd26daxZs4adO3fSvn17rr/+evLy8rjtttuYOnUqDRs2ZOLEidx33328/vrrDB48mL/+9a8A3H///bz22mvcdtttQZ2vpH0zMjL49ttvWbt2LQMHDuSKK65wlW/v3r18+umnrF27FhEhMzMTgFGjRnHuuefy6aefUlBQULRs+Prrr1OvXj2ys7M57bTTuPzyy6lfvz6HDx+me/fujBs3jkceeYSHH36Y5557jpEjR/Liiy/Stm1bfvzxR/72t78xZ86coN6jIfyUdB3xv/4kxHhIH2j9/stzZSCiFI6IfIAVANBARLZiRZ7FAKjqi8AXwCVYPeCPANfZ2/aJyD+BRfahHvEGEISby7o0c/2CnNZSnZbgasdH88mSLTw9a71ZEioD/sqmtPFQ+eabbxg2bBgej4emTZty/vnnA7Bu3TpWrVrFhRdeCEBBQQGpqakArFq1ivvvv5/MzEwOHTpEv379gj5fSftedtllREVF0b59e3bu3FmifMnJycTHx/OXv/yFAQMGMGDAAADmzJnD229bgZ8ej4fk5GQAJkyYwKeffgrAli1bWL9+PfXr1ycqKoqrrroKgKuvvprBgwdz6NAhvv/+e4YMGVIkW25uboifrKGs+C8hX3Vac6I9Qp6DRdPM5/rjdH0pz+tMRCkcVR1WynYFbnHZ9jrwennIFQxuisjf8okSOJCTz98/XoH3p2J8O8UpzRI5a+wcR0XeLCWBiTeeWV5ioap06NCBH374IWDbiBEjmDJlCp06deLNN99k3rx5QR+3pH3j4uKKnb8koqOjWbhwIV9//TWTJk3iueee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\n", + "image/png": "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HFPk4XKAqiq33nor7dq144ILLmDXrl1F25YsWcK5555Lt27d6NevHxkZGQC88sornHbaaXTq1InLL7+cI0eOBH0+t31HjBjBqFGj6NmzJ23atGHSpEmlynf33XfTvn170tLSiqynnTt3MmjQIDp16kSnTp34/vvvAbjsssvo1q0bHTp04OWXXy46Rq1atbjjjjvo0KEDffr0Yffu3QBs3LiRiy66iG7dunH22Wezdu3asny8hjDhZMmUpGxSEmIcr19e/044qG4WzjTgVhH5ECtoIEtVM0RkBvAvEalrz+sL3BPuk3vvoEtzxoH1Rfr/GLyE04Stjjz82WrWbD/gun3Z75kcLQhU5HdNWsEHC3933Kd90zo89McOQZ3/008/Zd26daxZs4adO3fSvn17rr/+evLy8rjtttuYOnUqDRs2ZOLEidx33328/vrrDB48mL/+9a8A3H///bz22mvcdtttQZ2vpH0zMjL49ttvWbt2LQMHDuSKK65wlW/v3r18+umnrF27FhEhMzMTgFGjRnHuuefy6aefUlBQULRs+Prrr1OvXj2ys7M57bTTuPzyy6lfvz6HDx+me/fujBs3jkceeYSHH36Y5557jpEjR/Liiy/Stm1bfvzxR/72t78xZ86coN6jIfyUdB3xv/4kxHhIH2j9/stzZSCiFI6IfIAVANBARLZiRZ7FAKjqi8AXwCVYPeCPANfZ2/aJyD+BRfahHvEGEISby7o0c/2CnNZSnZbgasdH88mSLTw9a71ZEioD/sqmtPFQ+eabbxg2bBgej4emTZty/vnnA7Bu3TpWrVrFhRdeCEBBQQGpqakArFq1ivvvv5/MzEwOHTpEv379gj5fSftedtllREVF0b59e3bu3FmifMnJycTHx/OXv/yFAQMGMGDAAADmzJnD229bgZ8ej4fk5GQAJkyYwKeffgrAli1bWL9+PfXr1ycqKoqrrroKgKuvvprBgwdz6NAhvv/+e4YMGVIkW25uboifrKGs+C8hX3Vac6I9Qp6DRdPM5/rjdH0pz+tMRCkcVR1WynYFbnHZ9jrwennIFQxuisjf8okSOJCTz98/XoH3p2J8O8UpzRI5a+wcR0XeLCWBiTeeWV5ioap06NCBH374IWDbiBEjmDJlCp06deLNN99k3rx5QR+3pH3j4uKKnb8koqOjWbhwIV9//TWTJk3iueee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", "text/plain": [ "
" ] diff --git a/docs/source/guide/zne-3-options.md b/docs/source/guide/zne-3-options.md index fbbca471a2..4439b444bc 100644 --- a/docs/source/guide/zne-3-options.md +++ b/docs/source/guide/zne-3-options.md @@ -80,8 +80,6 @@ The Mitiq function for global folding is: The Mitiq functions for local folding are: - {func}`.fold_gates_at_random()`; -- {func}`.fold_gates_from_left()`; -- {func}`.fold_gates_from_right()`; - {func}`.fold_all()`. There are multiple functions for local folding since it can be applied to the gates of a circuit according to different orderings: @@ -137,9 +135,9 @@ for scale_factor in [1, 3, 5, 7]: print(f"For scale_factor={scale_factor}, the number of gates was scaled by {scaled_num_gates / num_gates}") ``` -**Note:** *When `scale_factor` is an odd integer, the number of gates is scaled exactly as dictated by the value of `scale_factor`. -In this case, since all gates are folded the same number of times, the three local folding functions -{func}`.fold_gates_at_random()`, {func}`.fold_gates_from_left()` and {func}`.fold_gates_from_right()` have the same (deterministic) effect.* +```{note} +When `scale_factor` is an odd integer, the number of gates is scaled exactly as dictated by the value of `scale_factor`. +``` +++ diff --git a/mitiq/zne/scaling/__init__.py b/mitiq/zne/scaling/__init__.py index 259508d867..468c0b6f74 100644 --- a/mitiq/zne/scaling/__init__.py +++ b/mitiq/zne/scaling/__init__.py @@ -6,8 +6,6 @@ """Methods for scaling noise in circuits by adding or modifying gates.""" from mitiq.zne.scaling.folding import ( fold_all, - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ) diff --git a/mitiq/zne/scaling/folding.py b/mitiq/zne/scaling/folding.py index 7a37e6fda4..707881f560 100644 --- a/mitiq/zne/scaling/folding.py +++ b/mitiq/zne/scaling/folding.py @@ -374,7 +374,6 @@ def _create_weight_mask( def _create_fold_mask( weight_mask: List[float], scale_factor: float, - folding_method: str, seed: Optional[int] = None, ) -> List[int]: r"""Returns a list of integers determining how many times each gate a @@ -394,19 +393,16 @@ def _create_fold_mask( total weight of the input circuit. For equal weights, this function reproduces the local unitary folding - method defined in equation (5) of :cite:`Giurgica_Tiron_2020_arXiv`. + method defined in equation (5) of :cite:`Giurgica_Tiron_2020_arXiv`, with + the layer indices chosen at random. Args: weight_mask: The weights of all the gates of the circuit to fold. Highly noisy gates should have a corresponding high weight. Gates with zero weight are assumed to be ideal and are not folded. scale_factor: The effective noise scale factor. - folding_method: A string equal to "at_random", or "from_left", or - "from_right". Determines the partial folding method described in - :cite:`Giurgica_Tiron_2020_arXiv`. If scale_factor is an odd - integer, all methods are equivalent and this option is irrelevant. - seed: A seed for the random number generator. This is used only when - folding_method is "at_random". + seed: A seed for the random number generator used to select the + subset of layer indices to fold. Returns: The list of integers determining to how many times one should fold the j_th gate of the circuit to be scaled. @@ -415,7 +411,6 @@ def _create_fold_mask( >>>_create_fold_mask( weight_mask=[1.0, 0.5, 2.0, 0.0], scale_factor=4, - folding_method="from_left", ) [2, 2, 1, 0] """ @@ -443,18 +438,9 @@ def _create_fold_mask( # Express folding order through a list of indices folding_order = list(range(len(weight_mask))) - if folding_method == "from_left": - pass - elif folding_method == "from_right": - folding_order.reverse() - elif folding_method == "at_random": - rnd_state = np.random.RandomState(seed) - rnd_state.shuffle(folding_order) - else: - raise ValueError( - "The option 'folding_method' is not valid." - "It must be 'at_random', or 'from_left', or 'from_right'." - ) + + rnd_state = np.random.RandomState(seed) + rnd_state.shuffle(folding_order) # Fold gates until the input scale_factor is better approximated input_circuit_weight = sum(weight_mask) @@ -540,176 +526,6 @@ def _apply_fold_mask( return folded_circuit -@accept_qprogram_and_validate -def fold_gates_from_left( - circuit: Circuit, scale_factor: float, **kwargs: Any -) -> Circuit: - """Returns a new folded circuit by applying the map G -> G G^dag G to a - subset of gates of the input circuit, starting with gates at the - left (beginning) of the circuit. - - The folded circuit has a number of gates approximately equal to - scale_factor * n where n is the number of gates in the input circuit. - - For equal gate fidelities, this function reproduces the local unitary - folding method defined in equation (5) of - :cite:`Giurgica_Tiron_2020_arXiv`. - - Args: - circuit: Circuit to fold. - scale_factor: Factor to scale the circuit by. Any real number >= 1. - - Keyword Args: - fidelities (Dict[str, float]): Dictionary of gate fidelities. Each key - is a string which specifies the gate and each value is the - fidelity of that gate. When this argument is provided, folded - gates contribute an amount proportional to their infidelity - (1 - fidelity) to the total noise scaling. Fidelity values must be - in the interval (0, 1]. Gates not specified have a default - fidelity of 0.99**n where n is the number of qubits the gates act - on. - - Supported gate keys are listed in the following table.:: - - Gate key | Gate - ------------------------- - "H" | Hadamard - "X" | Pauli X - "Y" | Pauli Y - "Z" | Pauli Z - "I" | Identity - "S" | Phase gate - "T" | T gate - "rx" | X-rotation - "ry" | Y-rotation - "rz" | Z-rotation - "CNOT" | CNOT - "CZ" | CZ gate - "SWAP" | Swap - "ISWAP" | Imaginary swap - "CSWAP" | CSWAP - "TOFFOLI" | Toffoli gate - "single" | All single qubit gates - "double" | All two-qubit gates - "triple" | All three-qubit gates - - Keys for specific gates override values set by "single", "double", - and "triple". - - For example, `fidelities = {"single": 1.0, "H", 0.99}` sets all - single-qubit gates except Hadamard to have fidelity one. - - squash_moments (bool): If True, all gates (including folded gates) are - placed as early as possible in the circuit. If False, new moments - are created for folded gates. This option only applies to QPROGRAM - types which have a "moment" or "time" structure. Default is True. - - return_mitiq (bool): If True, returns a Mitiq circuit instead of - the input circuit type (if different). Default is False. - - Returns: - folded: The folded quantum circuit as a QPROGRAM. - - """ - - weight_mask = _create_weight_mask(circuit, kwargs.get("fidelities", {})) - - num_folds_mask = _create_fold_mask( - weight_mask, scale_factor, folding_method="from_left" - ) - - return _apply_fold_mask( - circuit, - num_folds_mask, - squash_moments=kwargs.get("squash_moments", True), - ) - - -@accept_qprogram_and_validate -def fold_gates_from_right( - circuit: Circuit, scale_factor: float, **kwargs: Any -) -> Circuit: - r"""Returns a new folded circuit by applying the map G -> G G^dag G to a - subset of gates of the input circuit, starting with gates at the - right (end) of the circuit. - - The folded circuit has a number of gates approximately equal to - scale_factor * n where n is the number of gates in the input circuit. - - For equal gate fidelities, this function reproduces the local unitary - folding method defined in equation (5) of - :cite:`Giurgica_Tiron_2020_arXiv`. - - Args: - circuit: Circuit to fold. - scale_factor: Factor to scale the circuit by. Any real number >= 1. - - Keyword Args: - fidelities (Dict[str, float]): Dictionary of gate fidelities. Each key - is a string which specifies the gate and each value is the - fidelity of that gate. When this argument is provided, folded - gates contribute an amount proportional to their infidelity - (1 - fidelity) to the total noise scaling. Fidelity values must be - in the interval (0, 1]. Gates not specified have a default - fidelity of 0.99**n where n is the number of qubits the gates act - on. - - Supported gate keys are listed in the following table.:: - - Gate key | Gate - ------------------------- - "H" | Hadamard - "X" | Pauli X - "Y" | Pauli Y - "Z" | Pauli Z - "I" | Identity - "S" | Phase gate - "T" | T gate - "rx" | X-rotation - "ry" | Y-rotation - "rz" | Z-rotation - "CNOT" | CNOT - "CZ" | CZ gate - "SWAP" | Swap - "ISWAP" | Imaginary swap - "CSWAP" | CSWAP - "TOFFOLI" | Toffoli gate - "single" | All single qubit gates - "double" | All two-qubit gates - "triple" | All three-qubit gates - - Keys for specific gates override values set by "single", "double", - and "triple". - - For example, `fidelities = {"single": 1.0, "H", 0.99}` sets all - single-qubit gates except Hadamard to have fidelity one. - - squash_moments (bool): If True, all gates (including folded gates) are - placed as early as possible in the circuit. If False, new moments - are created for folded gates. This option only applies to QPROGRAM - types which have a "moment" or "time" structure. Default is True. - - return_mitiq (bool): If True, returns a Mitiq circuit instead of - the input circuit type (if different). Default is False. - - Returns: - folded: The folded quantum circuit as a QPROGRAM. - - """ - - weight_mask = _create_weight_mask(circuit, kwargs.get("fidelities", {})) - - num_folds_mask = _create_fold_mask( - weight_mask, scale_factor, folding_method="from_right" - ) - - return _apply_fold_mask( - circuit, - num_folds_mask, - squash_moments=kwargs.get("squash_moments", True), - ) - - @accept_qprogram_and_validate def fold_gates_at_random( circuit: Circuit, @@ -717,9 +533,10 @@ def fold_gates_at_random( seed: Optional[int] = None, **kwargs: Any, ) -> Circuit: - r"""Returns a new folded circuit by applying the map G -> G G^dag G to a - subset of gates of the input circuit, starting with gates at the - right (end) of the circuit. + r""" + Returns a new folded circuit by applying the map G -> G G^dag G to a + subset of gates of the input circuit, different indices randomly sampled + without replacement. The folded circuit has a number of gates approximately equal to scale_factor * n where n is the number of gates in the input circuit. @@ -791,7 +608,6 @@ def fold_gates_at_random( num_folds_mask = _create_fold_mask( weight_mask, scale_factor, - folding_method="at_random", seed=seed, ) diff --git a/mitiq/zne/scaling/tests/test_folding.py b/mitiq/zne/scaling/tests/test_folding.py index cba794531c..4f70bb4076 100644 --- a/mitiq/zne/scaling/tests/test_folding.py +++ b/mitiq/zne/scaling/tests/test_folding.py @@ -41,8 +41,6 @@ _squash_moments, fold_all, fold_gates_at_random, - fold_gates_from_left, - fold_gates_from_right, fold_global, ) @@ -216,22 +214,14 @@ def test_folding_with_bad_scale_factor(): for fold_function in ( fold_all, fold_gates_at_random, - fold_gates_from_left, - fold_gates_from_right, ): with pytest.raises(ValueError, match="Requires scale_factor >= 1"): fold_function(Circuit(), scale_factor=0.0) def test_create_mask_with_bad_scale_factor(): - for method in ("at_random", "from_right", "from_left"): - with pytest.raises(ValueError, match="Requires scale_factor >= 1"): - _create_fold_mask([1], scale_factor=0.999, folding_method=method) - - -def test_create_mask_with_bad_folding_method(): - with pytest.raises(ValueError, match="'folding_method' is not valid."): - _create_fold_mask([1], scale_factor=1.5, folding_method=None) + with pytest.raises(ValueError, match="Requires scale_factor >= 1"): + _create_fold_mask([1], scale_factor=0.999) def test_fold_all_bad_exclude(): @@ -246,137 +236,9 @@ def test_fold_all_bad_exclude(): fold_all(Circuit(), scale_factor=1.0, exclude=frozenset((7,))) -def test_fold_from_left_two_qubits(): - qreg = LineQubit.range(2) - circ = Circuit( - [ - ops.H.on_each(*qreg), - ops.CNOT.on(qreg[0], qreg[1]), - ops.T.on(qreg[1]), - ] - ) - - # Intermediate scale factor - folded = fold_gates_from_left(circ, scale_factor=2.5) - correct = Circuit( - [ops.H.on_each(*qreg)] * 3, - [ops.CNOT.on(*qreg)] * 3, - [ops.T.on(qreg[1])], - ) - assert _equal(folded, _squash_moments(correct)) - - # Full scale factor - folded = fold_gates_from_left(circ, scale_factor=3) - correct = Circuit( - [ops.H.on_each(*qreg)] * 3, - [ops.CNOT.on(*qreg)] * 3, - [ops.T.on(qreg[1]), ops.T.on(qreg[1]) ** -1, ops.T.on(qreg[1])], - ) - assert _equal(folded, correct) - - -def test_fold_from_left_three_qubits(): - """Unit test for folding gates from left to scale a circuit.""" - qreg = LineQubit.range(3) - circ = Circuit( - [ - ops.H.on_each(*qreg), - ops.CNOT.on(qreg[0], qreg[1]), - ops.T.on(qreg[2]), - ops.TOFFOLI.on(*qreg), - ] - ) - - folded = fold_gates_from_left(circ, scale_factor=2) - correct = Circuit([ops.H.on_each(*qreg)] * 2, list(circ.all_operations())) - assert _equal(folded, correct) - - -def test_fold_from_left_no_stretch(): - """Unit test for folding gates from left for a scale factor of one.""" - circuit = testing.random_circuit(qubits=2, n_moments=10, op_density=0.99) - folded = fold_gates_from_left(circuit, scale_factor=1) - assert _equal(folded, _squash_moments(circuit)) - assert folded is not circuit - - -def test_fold_from_left_scale_factor_larger_than_three(): - """Tests folding from left with a scale_factor larger than three.""" - qreg = LineQubit.range(2) - circuit = Circuit([ops.SWAP.on(*qreg)], [ops.CNOT.on(*qreg)]) - folded = fold_gates_from_left(circuit, scale_factor=5.0) - correct = Circuit([ops.SWAP.on(*qreg)] * 5, [ops.CNOT.on(*qreg)] * 5) - assert _equal(folded, _squash_moments(correct)) - - -def test_fold_from_right_scale_factor_larger_than_three(): - """Tests folding from right with a scale_factor larger than three.""" - qreg = LineQubit.range(2) - circuit = Circuit([ops.SWAP.on(*qreg)], [ops.CNOT.on(*qreg)]) - folded = fold_gates_from_right(circuit, scale_factor=5.0) - correct = Circuit([ops.SWAP.on(*qreg)] * 5, [ops.CNOT.on(*qreg)] * 5) - assert _equal(folded, correct) - - -def test_fold_from_left_with_terminal_measurements_min_stretch(): - """Tests folding from left with terminal measurements.""" - # Test circuit - # 0: ───H───@───@───M─── - # │ │ - # 1: ───H───X───@───M─── - # │ - # 2: ───H───T───X───M─── - qreg = LineQubit.range(3) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - folded = fold_gates_from_left(circ, scale_factor=1.0) - correct = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - assert _equal(folded, correct) - - -def test_fold_from_left_with_terminal_measurements_max_stretch(): - """Tests folding from left with terminal measurements.""" - # Test circuit - # 0: ───H───@───@───M─── - # │ │ - # 1: ───H───X───@───M─── - # │ - # 2: ───H───T───X───M─── - qreg = LineQubit.range(3) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - folded = fold_gates_from_left(circ, scale_factor=3.0) - correct = Circuit( - [ops.H.on_each(*qreg)] * 3, - [ops.CNOT.on(qreg[0], qreg[1])] * 3, - [ops.T.on(qreg[2]), ops.T.on(qreg[2]) ** -1, ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)] * 3, - [ops.measure_each(*qreg)], - ) - assert _equal(folded, correct) - - @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ], @@ -397,8 +259,6 @@ def test_fold_with_intermediate_measurements_raises_error(fold_method): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ], @@ -420,8 +280,6 @@ def test_fold_with_channels_raises_error(fold_method): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ], @@ -441,8 +299,6 @@ def test_parametrized_circuit_folding(fold_method): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ], @@ -464,8 +320,6 @@ def test_parametrized_circuit_folding_terminal_measurement(fold_method): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ], @@ -493,156 +347,6 @@ def test_errors_raised_parametrized_circuits(fold_method): fold_method(circ, scale_factor=3.0) -def test_fold_from_right_basic(): - """Tests folding gates from the right for a two-qubit circuit.""" - # Test circuit: - # 0: ───H───@─────── - # │ - # 1: ───H───X───T─── - qreg = LineQubit.range(2) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[1])], - ) - - # Small scale factor - folded = fold_gates_from_right(circ, scale_factor=1.5) - correct = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(*qreg)], - [ops.T.on(qreg[1]), ops.T.on(qreg[1]) ** -1, ops.T.on(qreg[1])], - ) - assert _equal(folded, correct) - - # Intermediate scale factor - folded = fold_gates_from_right(circ, scale_factor=2.5) - correct = Circuit( - [ops.H.on(qreg[0])], - [ops.H.on(qreg[1])] * 3, - [ops.CNOT.on(*qreg)] * 3, - [ops.T.on(qreg[1]), ops.T.on(qreg[1]) ** -1, ops.T.on(qreg[1])], - ) - assert _equal(folded, correct) - - -def test_fold_from_right_max_stretch(): - """Tests that fold from right = fold from left with maximum scale.""" - # Test circuit - # 0: ───H───@───@─── - # │ │ - # 1: ───H───X───@─── - # │ - # 2: ───H───T───X─── - qreg = LineQubit.range(3) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - ) - - left_folded = fold_gates_from_left(circ, scale_factor=3.0) - right_folded = fold_gates_from_right(circ, scale_factor=3.0) - assert _equal(left_folded, right_folded) - - -def test_fold_from_right_with_terminal_measurements_min_stretch(): - """Tests folding from left with terminal measurements.""" - # Test circuit - # 0: ───H───@───@───M─── - # │ │ - # 1: ───H───X───@───M─── - # │ - # 2: ───H───T───X───M─── - qreg = LineQubit.range(3) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - folded = fold_gates_from_right(circ, scale_factor=1.0) - correct = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - assert _equal(folded, correct) - assert _equal(circ, correct) - - -def test_fold_from_right_with_terminal_measurements_max_stretch(): - """Tests folding from left with terminal measurements.""" - # Test circuit - # 0: ───H───@───@───M─── - # │ │ - # 1: ───H───X───@───M─── - # │ - # 2: ───H───T───X───M─── - qreg = LineQubit.range(3) - circ = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - folded = fold_gates_from_right(circ, scale_factor=3.0) - correct = Circuit( - [ops.H.on_each(*qreg)] * 3, - [ops.CNOT.on(qreg[0], qreg[1])] * 3, - [ops.T.on(qreg[2]), ops.T.on(qreg[2]) ** -1, ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)] * 3, - [ops.measure_each(*qreg)], - ) - assert _equal(folded, correct) - - # Make sure the original circuit is not modified - original = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - assert _equal(circ, original) - - -def test_fold_right_retains_terminal_measurements_in_input_circuit(): - """Tests that folding from the right doesn't modify the terminal - measurements in the input circuit. - """ - qbit = LineQubit(1) - circ = Circuit(ops.H.on(qbit), ops.measure(qbit)) - folded = fold_gates_from_right(circ, scale_factor=1.0) - assert _equal(circ, folded) - - -def test_local_folding_methods_match_on_odd_scale_factors(): - circuit = testing.random_circuit( - qubits=3, n_moments=5, op_density=1.0, random_state=11 - ) - for s in (3, 7, 15): - assert _equal( - fold_gates_from_left(circuit, s), - fold_gates_from_right(circuit, s), - require_qubit_equality=True, - require_measurement_equality=True, - ) - - for s in (3, 7, 15): - assert _equal( - fold_gates_from_left(circuit, s), - fold_gates_at_random(circuit, s), - require_qubit_equality=True, - require_measurement_equality=True, - ) - - def test_fold_gates_at_random_no_stretch(): """Tests folded circuit is identical for a scale factor of one.""" circuit = testing.random_circuit(qubits=3, n_moments=10, op_density=0.99) @@ -1082,94 +786,6 @@ def test_convert_to_from_mitiq_qiskit(): assert isinstance(original_circuit, QuantumCircuit) -def test_fold_from_left_with_qiskit_circuits(): - """Tests folding from left with Qiskit circuits.""" - # Test Qiskit circuit: - # ┌───┐ - # q0_0: |0>┤ H ├──■────■── - # ├───┤┌─┴─┐ │ - # q0_1: |0>┤ H ├┤ X ├──■── - # ├───┤├───┤┌─┴─┐ - # q0_2: |0>┤ H ├┤ T ├┤ X ├ - # └───┘└───┘└───┘ - qiskit_qreg = QuantumRegister(3) - qiskit_creg = ClassicalRegister(3) - qiskit_circuit = QuantumCircuit(qiskit_qreg, qiskit_creg) - qiskit_circuit.h(qiskit_qreg) - qiskit_circuit.cx(qiskit_qreg[0], qiskit_qreg[1]) - qiskit_circuit.t(qiskit_qreg[2]) - qiskit_circuit.ccx(*qiskit_qreg) - qiskit_circuit.measure(qiskit_qreg, qiskit_creg) - - folded_circuit = fold_gates_from_left( - qiskit_circuit, scale_factor=1.0, return_mitiq=True - ) - - qreg = LineQubit.range(3) - correct_folded_circuit = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - - assert isinstance(folded_circuit, Circuit) - assert _equal(folded_circuit, correct_folded_circuit) - - # Keep the input type - qiskit_folded_circuit = fold_gates_from_left( - qiskit_circuit, scale_factor=1.0, return_mitiq=False - ) - assert isinstance(qiskit_folded_circuit, QuantumCircuit) - assert qiskit_folded_circuit.qregs == qiskit_circuit.qregs - assert qiskit_folded_circuit.cregs == qiskit_circuit.cregs - - -def test_fold_from_right_with_qiskit_circuits(): - """Tests folding from right with Qiskit circuits.""" - # Test Qiskit circuit: - # ┌───┐ - # q0_0: |0>┤ H ├──■────■── - # ├───┤┌─┴─┐ │ - # q0_1: |0>┤ H ├┤ X ├──■── - # ├───┤├───┤┌─┴─┐ - # q0_2: |0>┤ H ├┤ T ├┤ X ├ - # └───┘└───┘└───┘ - qiskit_qreg = QuantumRegister(3) - qiskit_creg = ClassicalRegister(3) - qiskit_circuit = QuantumCircuit(qiskit_qreg, qiskit_creg) - qiskit_circuit.h(qiskit_qreg) - qiskit_circuit.cx(qiskit_qreg[0], qiskit_qreg[1]) - qiskit_circuit.t(qiskit_qreg[2]) - qiskit_circuit.ccx(*qiskit_qreg) - qiskit_circuit.measure(qiskit_qreg, qiskit_creg) - - folded_circuit = fold_gates_from_right( - qiskit_circuit, scale_factor=1.0, return_mitiq=True - ) - - qreg = LineQubit.range(3) - correct_folded_circuit = Circuit( - [ops.H.on_each(*qreg)], - [ops.CNOT.on(qreg[0], qreg[1])], - [ops.T.on(qreg[2])], - [ops.TOFFOLI.on(*qreg)], - [ops.measure_each(*qreg)], - ) - - assert isinstance(folded_circuit, Circuit) - assert _equal(folded_circuit, correct_folded_circuit) - - # Keep the input type - qiskit_folded_circuit = fold_gates_from_right( - qiskit_circuit, scale_factor=1.0 - ) - assert isinstance(qiskit_folded_circuit, QuantumCircuit) - assert qiskit_folded_circuit.qregs == qiskit_circuit.qregs - assert qiskit_folded_circuit.cregs == qiskit_circuit.cregs - - def test_fold_at_random_with_qiskit_circuits(): """Tests folding at random with Qiskit circuits.""" # Test Qiskit circuit: @@ -1237,14 +853,14 @@ def test_fold_global_with_qiskit_circuits(): folded_circuit = fold_global( qiskit_circuit, scale_factor=2.71828, - fold_method=fold_gates_from_left, + fold_method=fold_gates_at_random, return_mitiq=True, ) assert isinstance(folded_circuit, Circuit) # Return input circuit type folded_qiskit_circuit = fold_global( - qiskit_circuit, scale_factor=2.0, fold_method=fold_gates_from_left + qiskit_circuit, scale_factor=2.0, fold_method=fold_gates_at_random ) assert isinstance(folded_qiskit_circuit, QuantumCircuit) assert folded_qiskit_circuit.qregs == qiskit_circuit.qregs @@ -1286,14 +902,14 @@ def test_fold_global_with_qiskit_circuits_and_idle_qubits(): folded_circuit = fold_global( qiskit_circuit, scale_factor=2.71828, - fold_method=fold_gates_from_left, + fold_method=fold_gates_at_random, return_mitiq=True, ) assert isinstance(folded_circuit, Circuit) # Return input circuit type folded_qiskit_circuit = fold_global( - qiskit_circuit, scale_factor=2.0, fold_method=fold_gates_from_left + qiskit_circuit, scale_factor=2.0, fold_method=fold_gates_at_random ) assert isinstance(folded_qiskit_circuit, QuantumCircuit) assert folded_qiskit_circuit.qregs == qiskit_circuit.qregs @@ -1316,10 +932,10 @@ def test_fold_left_squash_moments(): [ops.TOFFOLI.on(*qreg)], [ops.measure_each(*qreg)], ) - folded_not_squashed = fold_gates_from_left( + folded_not_squashed = fold_gates_at_random( circ, scale_factor=3, squash_moments=False ) - folded_and_squashed = fold_gates_from_left( + folded_and_squashed = fold_gates_at_random( circ, scale_factor=3, squash_moments=True ) correct = Circuit( @@ -1334,15 +950,7 @@ def test_fold_left_squash_moments(): assert len(folded_and_squashed) == 10 -@pytest.mark.parametrize( - "fold_method", - [ - fold_gates_from_left, - fold_gates_from_right, - fold_gates_at_random, - ], -) -def test_fold_and_squash_max_stretch(fold_method): +def test_fold_and_squash_max_stretch(): """Tests folding and squashing a two-qubit circuit.""" # Test circuit: # 0: ───────H───────H───────H───────H───────H─── @@ -1356,13 +964,13 @@ def test_fold_and_squash_max_stretch(fold_method): for i in range(d): circuit.insert(0, ops.H.on(qreg[i % 2]), strategy=InsertStrategy.NEW) - folded_not_squashed = fold_method( + folded_not_squashed = fold_gates_at_random( circuit, scale_factor=3.0, squash_moments=False ) - folded_and_squashed = fold_method( + folded_and_squashed = fold_gates_at_random( circuit, scale_factor=3.0, squash_moments=True ) - folded_with_squash_moments_not_specified = fold_method( + folded_with_squash_moments_not_specified = fold_gates_at_random( circuit, scale_factor=3.0 ) # Checks that the default is to squash moments @@ -1371,15 +979,7 @@ def test_fold_and_squash_max_stretch(fold_method): assert len(folded_with_squash_moments_not_specified) == 15 -@pytest.mark.parametrize( - "fold_method", - [ - fold_gates_from_left, - fold_gates_from_right, - fold_gates_at_random, - ], -) -def test_fold_and_squash_random_circuits_random_stretches(fold_method): +def test_fold_and_squash_random_circuits_random_stretches(): """Tests folding and squashing random circuits and ensures the number of moments in the squashed circuits is never greater than the number of moments in the un-squashed circuit. @@ -1390,13 +990,13 @@ def test_fold_and_squash_random_circuits_random_stretches(fold_method): qubits=8, n_moments=8, op_density=0.75 ) scale = 2 * rng.random() + 1 - folded_not_squashed = fold_method( + folded_not_squashed = fold_gates_at_random( circuit, scale_factor=scale, squash_moments=False, seed=trial, ) - folded_and_squashed = fold_method( + folded_and_squashed = fold_gates_at_random( circuit, scale_factor=scale, squash_moments=True, @@ -1413,12 +1013,8 @@ def test_default_weight(): assert np.isclose(_default_weight(ops.TOFFOLI.on(*qreg[:3])), 0.970299) -@pytest.mark.parametrize( - "fold_method", - [fold_gates_from_left, fold_gates_from_right, fold_gates_at_random], -) @pytest.mark.parametrize("qiskit", [True, False]) -def test_fold_local_with_fidelities(fold_method, qiskit): +def test_fold_local_with_fidelities(qiskit): qreg = LineQubit.range(3) circ = Circuit( ops.H.on_each(*qreg), @@ -1430,7 +1026,9 @@ def test_fold_local_with_fidelities(fold_method, qiskit): circ = convert_from_mitiq(circ, "qiskit") # Only fold the Toffoli gate fidelities = {"H": 1.0, "T": 1.0, "CNOT": 1.0, "TOFFOLI": 0.95} - folded = fold_method(circ, scale_factor=3.0, fidelities=fidelities) + folded = fold_gates_at_random( + circ, scale_factor=3.0, fidelities=fidelities + ) correct = Circuit( [ops.H.on_each(*qreg)], [ops.CNOT.on(qreg[0], qreg[1])], @@ -1444,12 +1042,8 @@ def test_fold_local_with_fidelities(fold_method, qiskit): assert _equal(folded, correct) -@pytest.mark.parametrize( - "fold_method", - [fold_gates_from_left, fold_gates_from_right, fold_gates_at_random], -) @pytest.mark.parametrize("qiskit", [True, False]) -def test_fold_local_with_single_qubit_gates_fidelity_one(fold_method, qiskit): +def test_fold_local_with_single_qubit_gates_fidelity_one(qiskit): """Tests folding only two-qubit gates by using fidelities = {"single": 1.}. """ @@ -1462,7 +1056,7 @@ def test_fold_local_with_single_qubit_gates_fidelity_one(fold_method, qiskit): ) if qiskit: circ = convert_from_mitiq(circ, "qiskit") - folded = fold_method( + folded = fold_gates_at_random( circ, scale_factor=3.0, fidelities={"single": 1.0, "CNOT": 0.99, "TOFFOLI": 0.95}, @@ -1482,12 +1076,8 @@ def test_fold_local_with_single_qubit_gates_fidelity_one(fold_method, qiskit): assert _equal(folded, correct) -@pytest.mark.parametrize( - "fold_method", - [fold_gates_from_left, fold_gates_from_right, fold_gates_at_random], -) @pytest.mark.parametrize("qiskit", [True, False]) -def test_all_gates_folded_at_max_scale_with_fidelities(fold_method, qiskit): +def test_all_gates_folded_at_max_scale_with_fidelities(qiskit): """Tests that all gates are folded regardless of the input fidelities when the scale factor is three. """ @@ -1505,7 +1095,7 @@ def test_all_gates_folded_at_max_scale_with_fidelities(fold_method, qiskit): if qiskit: circ = convert_from_mitiq(circ, "qiskit") - folded = fold_method( + folded = fold_gates_at_random( circ, scale_factor=3.0, fidelities={ @@ -1531,19 +1121,21 @@ def test_all_gates_folded_at_max_scale_with_fidelities(fold_method, qiskit): assert len(list(folded.all_operations())) == 3 * ngates -@pytest.mark.parametrize( - "fold_method", - [fold_gates_from_left, fold_gates_from_right, fold_gates_at_random], -) -def test_fold_local_raises_error_with_bad_fidelities(fold_method): +def test_fold_local_raises_error_with_bad_fidelities(): with pytest.raises(ValueError, match="Fidelities should be"): - fold_method(Circuit(), scale_factor=1.21, fidelities={"H": -1.0}) + fold_gates_at_random( + Circuit(), scale_factor=1.21, fidelities={"H": -1.0} + ) with pytest.raises(ValueError, match="Fidelities should be"): - fold_method(Circuit(), scale_factor=1.21, fidelities={"CNOT": 0.0}) + fold_gates_at_random( + Circuit(), scale_factor=1.21, fidelities={"CNOT": 0.0} + ) with pytest.raises(ValueError, match="Fidelities should be"): - fold_method(Circuit(), scale_factor=1.21, fidelities={"triple": 1.2}) + fold_gates_at_random( + Circuit(), scale_factor=1.21, fidelities={"triple": 1.2} + ) @pytest.mark.parametrize("conversion_type", ("qiskit", "pyquil")) @@ -1583,8 +1175,6 @@ def test_convert_pyquil_to_mitiq_circuit_conversion_error(): @pytest.mark.parametrize( "fold_method", ( - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ), @@ -1605,8 +1195,6 @@ def test_folding_circuit_conversion_error_qiskit(fold_method): @pytest.mark.parametrize( "fold_method", ( - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ), @@ -1621,15 +1209,11 @@ def test_folding_circuit_conversion_error_pyquil(fold_method): fold_method(prog, scale_factor=2.0) -@pytest.mark.parametrize( - "fold_method", - [fold_gates_from_left, fold_gates_from_right, fold_gates_at_random], -) @pytest.mark.parametrize("scale", [1, 3, 5, 9]) -def test_fold_fidelity_large_scale_factor_only_twoq_gates(fold_method, scale): +def test_fold_fidelity_large_scale_factor_only_twoq_gates(scale): qreg = LineQubit.range(2) circuit = Circuit(ops.H(qreg[0]), ops.CNOT(*qreg)) - folded = fold_method( + folded = fold_gates_at_random( circuit, scale_factor=scale, fidelities={"single": 1.0} ) correct = Circuit(ops.H(qreg[0]), [ops.CNOT(*qreg)] * scale) @@ -1686,87 +1270,10 @@ def test_create_weight_mask_with_fidelities(): weight_mask = _create_weight_mask(circ, fidelities) -@pytest.mark.parametrize( - "weight_mask", - ([0.1, 0.2, 0.3, 0.0], [0.3, 0.5, 0.7, 0.0], [1.0, 1.0, 1.0, 0.0]), -) -@pytest.mark.parametrize("scale_factor", (1, 3, 5, 7, 9, 11)) -@pytest.mark.parametrize("method", ("at_random", "from_left", "from_right")) -def test_create_fold_mask_with_odd_scale_factors( - weight_mask, - scale_factor, - method, -): - fold_mask = _create_fold_mask(weight_mask, scale_factor, method) - num_folds = int((scale_factor - 1) / 2) - assert fold_mask == [num_folds, num_folds, num_folds, 0] - - -def test_create_fold_mask_with_real_scale_factors_from_left(): - fold_mask = _create_fold_mask( - weight_mask=[0.1, 0.2, 0.3, 0.0], - scale_factor=1.0, - folding_method="from_left", - ) - assert fold_mask == [0, 0, 0, 0] - - fold_mask = _create_fold_mask( - weight_mask=[0.1, 0.1, 0.1, 0.1], - scale_factor=1.5, - folding_method="from_left", - ) - assert fold_mask == [1, 0, 0, 0] - - fold_mask = _create_fold_mask( - weight_mask=[1.0, 1.0, 1.0, 1.0], - scale_factor=2, - folding_method="from_left", - ) - assert fold_mask == [1.0, 1.0, 0.0, 0.0] - - fold_mask = _create_fold_mask( - weight_mask=[1.0, 1.0, 1.0, 1.0], - scale_factor=3.9, - folding_method="from_left", - ) - assert fold_mask == [2, 2, 1, 1] - - -def test_create_fold_mask_with_real_scale_factors_from_right(): - fold_mask = _create_fold_mask( - weight_mask=[0.1, 0.2, 0.3, 0.0], - scale_factor=1.0, - folding_method="from_right", - ) - assert fold_mask == [0, 0, 0, 0] - - fold_mask = _create_fold_mask( - weight_mask=[0.1, 0.1, 0.1, 0.1], - scale_factor=1.5, - folding_method="from_right", - ) - assert fold_mask == [0, 0, 0, 1] - - fold_mask = _create_fold_mask( - weight_mask=[1.0, 1.0, 1.0, 1.0], - scale_factor=2, - folding_method="from_right", - ) - assert fold_mask == [0.0, 0.0, 1.0, 1.0] - - fold_mask = _create_fold_mask( - weight_mask=[1.0, 1.0, 1.0, 1.0], - scale_factor=3.9, - folding_method="from_right", - ) - assert fold_mask == [1, 1, 2, 2] - - def test_create_fold_mask_with_real_scale_factors_at_random(): fold_mask = _create_fold_mask( weight_mask=[0.1, 0.2, 0.3, 0.0], scale_factor=1.0, - folding_method="at_random", seed=1, ) assert fold_mask == [0, 0, 0, 0] @@ -1774,7 +1281,6 @@ def test_create_fold_mask_with_real_scale_factors_at_random(): fold_mask = _create_fold_mask( weight_mask=[0.1, 0.1, 0.1, 0.1, 0.0], scale_factor=1.5, - folding_method="at_random", seed=2, ) assert fold_mask == [0, 0, 1, 0, 0] @@ -1782,7 +1288,6 @@ def test_create_fold_mask_with_real_scale_factors_at_random(): fold_mask = _create_fold_mask( weight_mask=[1, 1, 1, 1], scale_factor=2, - folding_method="at_random", seed=3, ) assert fold_mask == [0, 1, 0, 1] @@ -1790,14 +1295,12 @@ def test_create_fold_mask_with_real_scale_factors_at_random(): fold_mask = _create_fold_mask( weight_mask=[1, 1, 1, 1], scale_factor=3.9, - folding_method="at_random", seed=7, ) assert fold_mask == [1, 2, 2, 1] -@pytest.mark.parametrize("method", ("at_random", "from_left", "from_right")) -def test_create_fold_mask_approximates_well(method): +def test_create_fold_mask_approximates_well(): """Check _create_fold_mask well approximates the scale factor.""" rnd_state = np.random.RandomState(seed=0) for scale_factor in [1, 1.5, 1.7, 2.7, 6.7, 18.7, 19.0, 31]: @@ -1806,7 +1309,6 @@ def test_create_fold_mask_approximates_well(method): fold_mask = _create_fold_mask( weight_mask, scale_factor, - folding_method=method, seed=seed, ) out_weights = [w + 2 * n * w for w, n in zip(weight_mask, fold_mask)] @@ -1915,8 +1417,6 @@ def test_apply_fold_mask_with_squash_moments_option(): @pytest.mark.parametrize( "fold_method", ( - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, fold_global, ), diff --git a/mitiq/zne/tests/test_zne.py b/mitiq/zne/tests/test_zne.py index 2c66328534..3689572a3d 100644 --- a/mitiq/zne/tests/test_zne.py +++ b/mitiq/zne/tests/test_zne.py @@ -41,8 +41,6 @@ ) from mitiq.zne.scaling import ( fold_gates_at_random, - fold_gates_from_left, - fold_gates_from_right, get_layer_folding, insert_id_layers, ) @@ -154,8 +152,6 @@ def test_with_observable_two_qubits(): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, insert_id_layers, ], @@ -178,8 +174,6 @@ def test_execute_with_zne_no_noise(fold_method, factory, num_to_average): @pytest.mark.parametrize( "fold_method", [ - fold_gates_from_left, - fold_gates_from_right, fold_gates_at_random, insert_id_layers, ],