qiskit 1.3.0b1__cp39-abi3-macosx_10_9_x86_64.whl

qiskit/circuit/equivalence.py

@@ -0,0 +1,295 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Gate equivalence library."""
+
+import copy
+from collections import namedtuple
+
+from rustworkx.visualization import graphviz_draw
+import rustworkx as rx
+
+from qiskit.exceptions import InvalidFileError
+from .exceptions import CircuitError
+from .parameter import Parameter
+from .parameterexpression import ParameterExpression
+
+Key = namedtuple("Key", ["name", "num_qubits"])
+Equivalence = namedtuple("Equivalence", ["params", "circuit"])  # Ordered to match Gate.params
+NodeData = namedtuple("NodeData", ["key", "equivs"])
+EdgeData = namedtuple("EdgeData", ["index", "num_gates", "rule", "source"])
+
+
+class EquivalenceLibrary:
+    """A library providing a one-way mapping of Gates to their equivalent
+    implementations as QuantumCircuits."""
+
+    def __init__(self, *, base=None):
+        """Create a new equivalence library.
+
+        Args:
+            base (Optional[EquivalenceLibrary]):  Base equivalence library to
+                be referenced if an entry is not found in this library.
+        """
+        self._base = base
+
+        if base is None:
+            self._graph = rx.PyDiGraph()
+            self._key_to_node_index = {}
+            # Some unique identifier for rules.
+            self._rule_id = 0
+        else:
+            self._graph = base._graph.copy()
+            self._key_to_node_index = copy.deepcopy(base._key_to_node_index)
+            self._rule_id = base._rule_id
+
+    @property
+    def graph(self) -> rx.PyDiGraph:
+        """Return graph representing the equivalence library data.
+
+        This property should be treated as read-only as it provides
+        a reference to the internal state of the :class:`~.EquivalenceLibrary` object.
+        If the graph returned by this property is mutated it could corrupt the
+        the contents of the object. If you need to modify the output ``PyDiGraph``
+        be sure to make a copy prior to any modification.
+
+        Returns:
+            PyDiGraph: A graph object with equivalence data in each node.
+        """
+        return self._graph
+
+    def _set_default_node(self, key):
+        """Create a new node if key not found"""
+        if key not in self._key_to_node_index:
+            self._key_to_node_index[key] = self._graph.add_node(NodeData(key=key, equivs=[]))
+        return self._key_to_node_index[key]
+
+    def add_equivalence(self, gate, equivalent_circuit):
+        """Add a new equivalence to the library. Future queries for the Gate
+        will include the given circuit, in addition to all existing equivalences
+        (including those from base).
+
+        Parameterized Gates (those including `qiskit.circuit.Parameters` in their
+        `Gate.params`) can be marked equivalent to parameterized circuits,
+        provided the parameters match.
+
+        Args:
+            gate (Gate): A Gate instance.
+            equivalent_circuit (QuantumCircuit): A circuit equivalently
+                implementing the given Gate.
+        """
+
+        _raise_if_shape_mismatch(gate, equivalent_circuit)
+        _raise_if_param_mismatch(gate.params, equivalent_circuit.parameters)
+
+        key = Key(name=gate.name, num_qubits=gate.num_qubits)
+        equiv = Equivalence(params=gate.params.copy(), circuit=equivalent_circuit.copy())
+
+        target = self._set_default_node(key)
+        self._graph[target].equivs.append(equiv)
+
+        sources = {
+            Key(name=instruction.operation.name, num_qubits=len(instruction.qubits))
+            for instruction in equivalent_circuit
+        }
+        edges = [
+            (
+                self._set_default_node(source),
+                target,
+                EdgeData(index=self._rule_id, num_gates=len(sources), rule=equiv, source=source),
+            )
+            for source in sources
+        ]
+        self._graph.add_edges_from(edges)
+        self._rule_id += 1
+
+    def has_entry(self, gate):
+        """Check if a library contains any decompositions for gate.
+
+        Args:
+            gate (Gate): A Gate instance.
+
+        Returns:
+            Bool: True if gate has a known decomposition in the library.
+                False otherwise.
+        """
+        key = Key(name=gate.name, num_qubits=gate.num_qubits)
+
+        return key in self._key_to_node_index
+
+    def set_entry(self, gate, entry):
+        """Set the equivalence record for a Gate. Future queries for the Gate
+        will return only the circuits provided.
+
+        Parameterized Gates (those including `qiskit.circuit.Parameters` in their
+        `Gate.params`) can be marked equivalent to parameterized circuits,
+        provided the parameters match.
+
+        Args:
+            gate (Gate): A Gate instance.
+            entry (List['QuantumCircuit']) : A list of QuantumCircuits, each
+                equivalently implementing the given Gate.
+        """
+        for equiv in entry:
+            _raise_if_shape_mismatch(gate, equiv)
+            _raise_if_param_mismatch(gate.params, equiv.parameters)
+
+        node_index = self._set_default_node(Key(name=gate.name, num_qubits=gate.num_qubits))
+        # Remove previous equivalences of this node, leaving in place any later equivalences that
+        # were added that use `gate`.
+        self._graph[node_index].equivs.clear()
+        for parent, child, _ in self._graph.in_edges(node_index):
+            # `child` should always be ourselves, but there might be parallel edges.
+            self._graph.remove_edge(parent, child)
+        for equivalence in entry:
+            self.add_equivalence(gate, equivalence)
+
+    def get_entry(self, gate):
+        """Gets the set of QuantumCircuits circuits from the library which
+        equivalently implement the given Gate.
+
+        Parameterized circuits will have their parameters replaced with the
+        corresponding entries from Gate.params.
+
+        Args:
+            gate (Gate) - Gate: A Gate instance.
+
+        Returns:
+            List[QuantumCircuit]: A list of equivalent QuantumCircuits. If empty,
+                library contains no known decompositions of Gate.
+
+                Returned circuits will be ordered according to their insertion in
+                the library, from earliest to latest, from top to base. The
+                ordering of the StandardEquivalenceLibrary will not generally be
+                consistent across Qiskit versions.
+        """
+        key = Key(name=gate.name, num_qubits=gate.num_qubits)
+        query_params = gate.params
+
+        return [_rebind_equiv(equiv, query_params) for equiv in self._get_equivalences(key)]
+
+    def keys(self):
+        """Return list of keys to key to node index map.
+
+        Returns:
+            List: Keys to the key to node index map.
+        """
+        return self._key_to_node_index.keys()
+
+    def node_index(self, key):
+        """Return node index for a given key.
+
+        Args:
+            key (Key): Key to an equivalence.
+
+        Returns:
+            Int: Index to the node in the graph for the given key.
+        """
+        return self._key_to_node_index[key]
+
+    def draw(self, filename=None):
+        """Draws the equivalence relations available in the library.
+
+        Args:
+            filename (str): An optional path to write the output image to
+                if specified this method will return None.
+
+        Returns:
+            PIL.Image or IPython.display.SVG: Drawn equivalence library as an
+                IPython SVG if in a jupyter notebook, or as a PIL.Image otherwise.
+
+        Raises:
+            InvalidFileError: if filename is not valid.
+        """
+        image_type = None
+        if filename:
+            if "." not in filename:
+                raise InvalidFileError("Parameter 'filename' must be in format 'name.extension'")
+            image_type = filename.split(".")[-1]
+        return graphviz_draw(
+            self._build_basis_graph(),
+            lambda node: {"label": node["label"]},
+            lambda edge: edge,
+            filename=filename,
+            image_type=image_type,
+        )
+
+    def _build_basis_graph(self):
+        graph = rx.PyDiGraph()
+
+        node_map = {}
+        for key in self._key_to_node_index:
+            name, num_qubits = key
+            equivalences = self._get_equivalences(key)
+
+            basis = frozenset([f"{name}/{num_qubits}"])
+            for params, decomp in equivalences:
+                decomp_basis = frozenset(
+                    f"{name}/{num_qubits}"
+                    for name, num_qubits in {
+                        (instruction.operation.name, instruction.operation.num_qubits)
+                        for instruction in decomp.data
+                    }
+                )
+                if basis not in node_map:
+                    basis_node = graph.add_node({"basis": basis, "label": str(set(basis))})
+                    node_map[basis] = basis_node
+                if decomp_basis not in node_map:
+                    decomp_basis_node = graph.add_node(
+                        {"basis": decomp_basis, "label": str(set(decomp_basis))}
+                    )
+                    node_map[decomp_basis] = decomp_basis_node
+
+                label = f"{str(params)}\n{str(decomp) if num_qubits <= 5 else '...'}"
+                graph.add_edge(
+                    node_map[basis],
+                    node_map[decomp_basis],
+                    {"label": label, "fontname": "Courier", "fontsize": str(8)},
+                )
+
+        return graph
+
+    def _get_equivalences(self, key):
+        """Get all the equivalences for the given key"""
+        return (
+            self._graph[self._key_to_node_index[key]].equivs
+            if key in self._key_to_node_index
+            else []
+        )
+
+
+def _raise_if_param_mismatch(gate_params, circuit_parameters):
+    gate_parameters = [p for p in gate_params if isinstance(p, ParameterExpression)]
+
+    if set(gate_parameters) != circuit_parameters:
+        raise CircuitError(
+            "Cannot add equivalence between circuit and gate "
+            f"of different parameters. Gate params: {gate_parameters}. "
+            f"Circuit params: {circuit_parameters}."
+        )
+
+
+def _raise_if_shape_mismatch(gate, circuit):
+    if gate.num_qubits != circuit.num_qubits or gate.num_clbits != circuit.num_clbits:
+        raise CircuitError(
+            "Cannot add equivalence between circuit and gate "
+            f"of different shapes. Gate: {gate.num_qubits} qubits and {gate.num_clbits} clbits. "
+            f"Circuit: {circuit.num_qubits} qubits and {circuit.num_clbits} clbits."
+        )
+
+
+def _rebind_equiv(equiv, query_params):
+    equiv_params, equiv_circuit = equiv
+    param_map = {x: y for x, y in zip(equiv_params, query_params) if isinstance(x, Parameter)}
+    equiv = equiv_circuit.assign_parameters(param_map, inplace=False, flat_input=True)
+
+    return equiv

qiskit/circuit/equivalence_library.py

@@ -0,0 +1,18 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Session gates."""
+
+from .library.standard_gates.equivalence_library import StandardEquivalenceLibrary
+from .equivalence import EquivalenceLibrary
+
+SessionEquivalenceLibrary = EquivalenceLibrary(base=StandardEquivalenceLibrary)

qiskit/circuit/exceptions.py

@@ -0,0 +1,19 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Exceptions for errors raised while handling Quantum Circuits."""
+
+from qiskit.exceptions import QiskitError
+
+
+class CircuitError(QiskitError):
+    """Base class for errors raised while processing a circuit."""

qiskit/circuit/gate.py

@@ -0,0 +1,261 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Unitary gate."""
+
+from __future__ import annotations
+from typing import Iterator, Iterable
+import numpy as np
+
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit.circuit.exceptions import CircuitError
+from .annotated_operation import AnnotatedOperation, ControlModifier, PowerModifier
+from .instruction import Instruction
+
+
+class Gate(Instruction):
+    """Unitary gate."""
+
+    def __init__(
+        self,
+        name: str,
+        num_qubits: int,
+        params: list,
+        label: str | None = None,
+        duration=None,
+        unit="dt",
+    ) -> None:
+        """Create a new gate.
+
+        Args:
+            name: The Qobj name of the gate.
+            num_qubits: The number of qubits the gate acts on.
+            params: A list of parameters.
+            label: An optional label for the gate.
+        """
+        self.definition = None
+        super().__init__(name, num_qubits, 0, params, label=label, duration=duration, unit=unit)
+
+    # Set higher priority than Numpy array and matrix classes
+    __array_priority__ = 20
+
+    def to_matrix(self) -> np.ndarray:
+        """Return a Numpy.array for the gate unitary matrix.
+
+        Returns:
+            np.ndarray: if the Gate subclass has a matrix definition.
+
+        Raises:
+            CircuitError: If a Gate subclass does not implement this method an
+                exception will be raised when this base class method is called.
+        """
+        if hasattr(self, "__array__"):
+            return self.__array__(dtype=complex)
+        raise CircuitError(f"to_matrix not defined for this {type(self)}")
+
+    def power(self, exponent: float, annotated: bool = False):
+        """Raise this gate to the power of ``exponent``.
+
+        Implemented either as a unitary gate (ref. :class:`~.library.UnitaryGate`)
+        or as an annotated operation (ref. :class:`.AnnotatedOperation`). In the case of several standard
+        gates, such as :class:`.RXGate`, when the power of a gate can be expressed in terms of another
+        standard gate that is returned directly.
+
+        Args:
+            exponent (float): the power to raise the gate to
+            annotated (bool): indicates whether the power gate can be implemented
+                as an annotated operation. In the case of several standard
+                gates, such as :class:`.RXGate`, this argument is ignored when
+                the power of a gate can be expressed in terms of another
+                standard gate.
+
+        Returns:
+            An operation implementing ``gate^exponent``
+
+        Raises:
+            CircuitError: If gate is not unitary
+        """
+        # pylint: disable=cyclic-import
+        from qiskit.quantum_info.operators import Operator
+        from qiskit.circuit.library.generalized_gates.unitary import UnitaryGate
+
+        if not annotated:
+            return UnitaryGate(Operator(self).power(exponent), label=f"{self.name}^{exponent}")
+        else:
+            return AnnotatedOperation(self, PowerModifier(exponent))
+
+    def __pow__(self, exponent: float) -> "Gate":
+        return self.power(exponent)
+
+    def _return_repeat(self, exponent: float) -> "Gate":
+        gate = Gate(name=f"{self.name}*{exponent}", num_qubits=self.num_qubits, params=[])
+        gate.validate_parameter = self.validate_parameter
+        gate.params = self.params
+        return gate
+
+    def control(
+        self,
+        num_ctrl_qubits: int = 1,
+        label: str | None = None,
+        ctrl_state: int | str | None = None,
+        annotated: bool | None = None,
+    ):
+        """Return the controlled version of itself.
+
+        Implemented either as a controlled gate (ref. :class:`.ControlledGate`)
+        or as an annotated operation (ref. :class:`.AnnotatedOperation`).
+
+        Args:
+            num_ctrl_qubits: number of controls to add to gate (default: ``1``)
+            label: optional gate label. Ignored if implemented as an annotated
+                operation.
+            ctrl_state: the control state in decimal or as a bitstring
+                (e.g. ``'111'``). If ``None``, use ``2**num_ctrl_qubits-1``.
+            annotated: indicates whether the controlled gate is implemented
+                as an annotated gate. If ``None``, this is set to ``False``
+                if the controlled gate can directly be constructed, and otherwise
+                set to ``True``. This allows defering the construction process in case the
+                synthesis of the controlled gate requires more information (e.g.
+                values of unbound parameters).
+
+        Returns:
+            Controlled version of the given operation.
+
+        Raises:
+            QiskitError: unrecognized mode or invalid ctrl_state
+        """
+        if not annotated:  # captures both None and False
+            # pylint: disable=cyclic-import
+            from .add_control import add_control
+
+            return add_control(self, num_ctrl_qubits, label, ctrl_state)
+
+        else:
+            return AnnotatedOperation(
+                self, ControlModifier(num_ctrl_qubits=num_ctrl_qubits, ctrl_state=ctrl_state)
+            )
+
+    @staticmethod
+    def _broadcast_single_argument(qarg: list) -> Iterator[tuple[list, list]]:
+        """Expands a single argument.
+
+        For example: [q[0], q[1]] -> [q[0]], [q[1]]
+        """
+        # [q[0], q[1]] -> [q[0]]
+        #              -> [q[1]]
+        for arg0 in qarg:
+            yield [arg0], []
+
+    @staticmethod
+    def _broadcast_2_arguments(qarg0: list, qarg1: list) -> Iterator[tuple[list, list]]:
+        if len(qarg0) == len(qarg1):
+            # [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]]
+            #                              -> [q[1], r[1]]
+            for arg0, arg1 in zip(qarg0, qarg1):
+                yield [arg0, arg1], []
+        elif len(qarg0) == 1:
+            # [[q[0]], [r[0], r[1]]] -> [q[0], r[0]]
+            #                        -> [q[0], r[1]]
+            for arg1 in qarg1:
+                yield [qarg0[0], arg1], []
+        elif len(qarg1) == 1:
+            # [[q[0], q[1]], [r[0]]] -> [q[0], r[0]]
+            #                        -> [q[1], r[0]]
+            for arg0 in qarg0:
+                yield [arg0, qarg1[0]], []
+        else:
+            raise CircuitError(
+                f"Not sure how to combine these two-qubit arguments:\n {qarg0}\n {qarg1}"
+            )
+
+    @staticmethod
+    def _broadcast_3_or_more_args(qargs: list) -> Iterator[tuple[list, list]]:
+        if all(len(qarg) == len(qargs[0]) for qarg in qargs):
+            for arg in zip(*qargs):
+                yield list(arg), []
+        else:
+            raise CircuitError(f"Not sure how to combine these qubit arguments:\n {qargs}\n")
+
+    def broadcast_arguments(self, qargs: list, cargs: list) -> Iterable[tuple[list, list]]:
+        """Validation and handling of the arguments and its relationship.
+
+        For example, ``cx([q[0],q[1]], q[2])`` means ``cx(q[0], q[2]); cx(q[1], q[2])``. This
+        method yields the arguments in the right grouping. In the given example::
+
+            in: [[q[0],q[1]], q[2]],[]
+            outs: [q[0], q[2]], []
+                  [q[1], q[2]], []
+
+        The general broadcasting rules are:
+
+            * If len(qargs) == 1::
+
+                [q[0], q[1]] -> [q[0]],[q[1]]
+
+            * If len(qargs) == 2::
+
+                [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]]
+                [[q[0]], [r[0], r[1]]]       -> [q[0], r[0]], [q[0], r[1]]
+                [[q[0], q[1]], [r[0]]]       -> [q[0], r[0]], [q[1], r[0]]
+
+            * If len(qargs) >= 3::
+
+                [q[0], q[1]], [r[0], r[1]],  ...] -> [q[0], r[0], ...], [q[1], r[1], ...]
+
+        Args:
+            qargs: List of quantum bit arguments.
+            cargs: List of classical bit arguments.
+
+        Returns:
+            A tuple with single arguments.
+
+        Raises:
+            CircuitError: If the input is not valid. For example, the number of
+                arguments does not match the gate expectation.
+        """
+        if len(qargs) != self.num_qubits or cargs:
+            raise CircuitError(
+                f"The amount of qubit({len(qargs)})/clbit({len(cargs)}) arguments does"
+                f" not match the gate expectation ({self.num_qubits})."
+            )
+
+        if any(not qarg for qarg in qargs):
+            raise CircuitError("One or more of the arguments are empty")
+
+        if len(qargs) == 0:
+            return [
+                ([], []),
+            ]
+        if len(qargs) == 1:
+            return Gate._broadcast_single_argument(qargs[0])
+        elif len(qargs) == 2:
+            return Gate._broadcast_2_arguments(qargs[0], qargs[1])
+        elif len(qargs) >= 3:
+            return Gate._broadcast_3_or_more_args(qargs)
+        else:
+            raise CircuitError(f"This gate cannot handle {len(qargs)} arguments")
+
+    def validate_parameter(self, parameter):
+        """Gate parameters should be int, float, or ParameterExpression"""
+        if isinstance(parameter, ParameterExpression):
+            if len(parameter.parameters) > 0:
+                return parameter  # expression has free parameters, we cannot validate it
+            if not parameter.is_real():
+                msg = f"Bound parameter expression is complex in gate {self.name}"
+                raise CircuitError(msg)
+            return parameter  # per default assume parameters must be real when bound
+        if isinstance(parameter, (int, float)):
+            return parameter
+        elif isinstance(parameter, (np.integer, np.floating)):
+            return parameter.item()
+        else:
+            raise CircuitError(f"Invalid param type {type(parameter)} for gate {self.name}.")