# Copyright 2018-2021 Xanadu Quantum Technologies Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
r"""
Contains the Permute template.
"""
import copy
from collections import Counter
from jax import numpy as jnp
from pennylane import capture
from pennylane.core.operator import Operation
from pennylane.decomposition import add_decomps, register_resources
from pennylane.ops import SWAP, cond
from pennylane.wires import Wires
[docs]
class Permute(Operation):
r"""Applies a permutation to a set of wires.
Args:
permutation (Sequence): A list of wire labels that represents the new ordering of wires
after the permutation. The list may consist of integers or strings, so long as
they match the labels of ``wires``.
wires (Iterable or Wires): Wires that the permutation acts on. Accepts an iterable
of numbers or strings, or a Wires object.
Raises:
ValueError: if inputs do not have the correct format
**Example**
.. code-block:: python
import pennylane as qp
dev = qp.device('default.qubit', wires=5)
@qp.qnode(dev)
def apply_perm():
# Send contents of wire 4 to wire 0, of wire 2 to wire 1, etc.
qp.templates.Permute([4, 2, 0, 1, 3], wires=dev.wires)
return qp.expval(qp.Z(0))
See "Usage Details" for further examples.
.. details::
:title: Usage Details
As a simple example, suppose we have a 4-qubit device with wires labeled
by the integers ``[0, 1, 2, 3]``. We apply a permutation to shuffle the
order to ``[3, 2, 0, 1]`` (i.e., the qubit state that was previously on
wire 3 is now on wire 0, the one from 2 is on wire 1, etc.).
.. code-block:: python
dev = qp.device('default.qubit', wires=4)
@qp.qnode(dev)
def apply_perm():
qp.Permute([3, 2, 0, 1], dev.wires)
return qp.expval(qp.Z(0))
>>> print(qp.draw(apply_perm, level="device")())
0: ─╭SWAP─────────────┤ <Z>
1: ─│─────╭SWAP───────┤
2: ─│─────╰SWAP─╭SWAP─┤
3: ─╰SWAP───────╰SWAP─┤
``Permute`` can also be used with quantum tapes. For example, suppose we
have a tape with 5 wires ``[0, 1, 2, 3, 4]``, and we'd like to reorder them
so that wire 4 is moved to the location of wire 0, wire 2 is moved to the
original location of wire 1, and so on.
.. code-block:: python
import pennylane as qp
op = qp.Permute([4, 2, 0, 1, 3], wires=[0, 1, 2, 3, 4])
tape = qp.tape.QuantumTape([op])
>>> [tape_expanded], _ = qp.transforms._tape_decompose(tape, gate_set={qp.SWAP})
>>> print(qp.drawer.tape_text(tape_expanded, wire_order=range(5)))
0: ─╭SWAP───────────────────┤
1: ─│─────╭SWAP─────────────┤
2: ─│─────╰SWAP─╭SWAP───────┤
3: ─│───────────│─────╭SWAP─┤
4: ─╰SWAP───────╰SWAP─╰SWAP─┤
``Permute`` can also be applied to wires with arbitrary labels, like so:
.. code-block:: python
wire_labels = [3, 2, "a", 0, "c"]
dev = qp.device('default.qubit', wires=wire_labels)
@qp.qnode(dev)
def circuit():
qp.Permute(["c", 3,"a",2,0], wires=wire_labels)
return qp.expval(qp.Z("c"))
The permuted circuit is:
>>> print(qp.draw(circuit, level="device")())
3: ─╭SWAP─────────────┤
2: ─│─────╭SWAP───────┤
0: ─│─────│─────╭SWAP─┤
c: ─╰SWAP─╰SWAP─╰SWAP─┤ <Z>
It is also possible to permute a subset of wires by
specifying a subset of labels. For example,
.. code-block:: python
wire_labels = [3, 2, "a", 0, "c"]
dev = qp.device('default.qubit', wires=wire_labels)
@qp.qnode(dev)
def circuit():
# Only permute the order of 3 of them
qp.Permute(["c", 2, 0], wires=[2, 0, "c"])
return qp.expval(qp.Z("c"))
will permute only the second, third, and fifth wires as follows:
>>> print(qp.draw(circuit, level="device", show_all_wires=True)())
3: ─────────────┤
2: ─╭SWAP───────┤
a: ─│───────────┤
0: ─│─────╭SWAP─┤
c: ─╰SWAP─╰SWAP─┤ <Z>
"""
def __repr__(self):
return f"Permute({self.hyperparameters['permutation']}, wires={self.wires})"
grad_method = None
resource_keys = {"wires", "permutation"}
def __init__(self, permutation, wires):
if len(permutation) <= 1 or len(wires) <= 1:
raise ValueError("Permutations must involve at least 2 qubits.")
# Make sure the lengths of permutation and wires are the same
if len(permutation) != len(wires):
raise ValueError("Permutation must specify outcome of all wires.")
# Permutation order must contain all unique values
if len(set(permutation)) != len(permutation):
raise ValueError("Values in a permutation must all be unique.")
# Make sure everything in the permutation has an associated label in wires
for label in permutation:
if label not in wires:
raise ValueError(f"Cannot permute wire {label} not present in wire set.")
self._hyperparameters = {"permutation": tuple(permutation)}
super().__init__(wires=wires)
[docs]
def map_wires(self, wire_map: dict):
# pylint: disable=protected-access
new_op = copy.deepcopy(self)
new_op._wires = Wires([wire_map.get(wire, wire) for wire in self.wires])
new_op._hyperparameters["permutation"] = tuple(
wire_map.get(w, w) for w in new_op._hyperparameters["permutation"]
)
return new_op
@property
def resource_params(self) -> dict:
return {
"permutation": self.hyperparameters["permutation"],
"wires": self.wires,
}
@property
def num_params(self):
return 0
[docs]
@staticmethod
def compute_decomposition(wires, permutation): # pylint: disable=arguments-differ
r"""Representation of the operator as a product of other operators.
.. math:: O = O_1 O_2 \dots O_n.
.. seealso:: :meth:`~.Permute.decomposition`.
Args:
wires (Any or Iterable[Any]): wires that the operator acts on
permutation (list[Any]): A list of wire labels that represents the new ordering of wires
after the permutation.
Returns:
list[.Operator]: decomposition of the operator
"""
op_list = []
# Temporary storage to keep track as we permute
working_order = wires.tolist()
# Go through the new order and shuffle things one by one
for idx_here, here in enumerate(permutation):
if working_order[idx_here] != here:
# Where do we need to send the qubit at this location?
idx_there = working_order.index(permutation[idx_here])
# SWAP based on the labels of the wires
op_list.append(SWAP(wires=wires.subset([idx_here, idx_there])))
# Update the working order to account for the SWAP
working_order[idx_here], working_order[idx_there] = (
working_order[idx_there],
working_order[idx_here],
)
return op_list
def _permute_resources(wires, permutation):
resources = Counter()
working_order = wires.tolist()
for idx_here, here in enumerate(permutation):
if working_order[idx_here] != here:
idx_there = working_order.index(permutation[idx_here])
resources[SWAP] += 1
working_order[idx_here], working_order[idx_there] = (
working_order[idx_there],
working_order[idx_here],
)
return dict(resources)
@register_resources(_permute_resources)
def _permute_decomposition(wires, permutation):
# Temporary storage to keep track as we permute
working_order = wires.tolist()
if capture.enabled():
# The swap index is traced inside ``cond``. JAX arrays support indexing with that
# tracer and the functional updates needed to carry the new order between branches.
wires = jnp.array(wires)
working_order = wires
for idx_here, here in enumerate(permutation):
def swap(order, idx_here=idx_here, here=here):
idx_there = jnp.argmax(order == here)
SWAP(wires=[wires[idx_here], wires[idx_there]])
here_value = order[idx_here]
order = order.at[idx_here].set(order[idx_there])
return order.at[idx_there].set(here_value)
working_order = cond(working_order[idx_here] != here, swap, lambda order: order)(
working_order
)
return
# Go through the new order and shuffle things one by one
for idx_here, here in enumerate(permutation):
if working_order[idx_here] != here:
# Where do we need to send the qubit at this location?
idx_there = working_order.index(permutation[idx_here])
# SWAP based on the labels of the wires
SWAP(wires=wires.subset([idx_here, idx_there]))
# Update the working order to account for the SWAP
working_order[idx_here], working_order[idx_there] = (
working_order[idx_there],
working_order[idx_here],
)
add_decomps(Permute, _permute_decomposition)