qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/controlledgate.py

@@ -0,0 +1,274 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""Controlled unitary gate."""
+
+from __future__ import annotations
+import copy
+from typing import Optional, Union
+
+from qiskit.circuit.exceptions import CircuitError
+
+# pylint: disable=cyclic-import
+from . import QuantumRegister
+from .quantumcircuit import QuantumCircuit
+from .gate import Gate
+from ._utils import _ctrl_state_to_int
+
+
+class ControlledGate(Gate):
+    """Controlled unitary gate."""
+
+    def __init__(
+        self,
+        name: str,
+        num_qubits: int,
+        params: list,
+        label: Optional[str] = None,
+        num_ctrl_qubits: Optional[int] = 1,
+        definition: Optional["QuantumCircuit"] = None,
+        ctrl_state: Optional[Union[int, str]] = None,
+        base_gate: Optional[Gate] = None,
+        *,
+        _base_label=None,
+    ):
+        """Create a new ControlledGate. In the new gate the first ``num_ctrl_qubits``
+        of the gate are the controls.
+
+        Args:
+            name: The name of the gate.
+            num_qubits: The number of qubits the gate acts on.
+            params: A list of parameters for the gate.
+            label: An optional label for the gate.
+            num_ctrl_qubits: Number of control qubits.
+            definition: A list of gate rules for implementing this gate. The
+                elements of the list are tuples of (:meth:`~qiskit.circuit.Gate`, [qubit_list],
+                [clbit_list]).
+            ctrl_state: The control state in decimal or as
+                a bitstring (e.g. '111'). If specified as a bitstring the length
+                must equal num_ctrl_qubits, MSB on left. If None, use
+                2**num_ctrl_qubits-1.
+            base_gate: Gate object to be controlled.
+
+        Raises:
+            CircuitError: If ``num_ctrl_qubits`` >= ``num_qubits``.
+            CircuitError: ctrl_state < 0 or ctrl_state > 2**num_ctrl_qubits.
+
+        Examples:
+
+        Create a controlled standard gate and apply it to a circuit.
+
+        .. plot::
+           :alt: Circuit diagram output by the previous code.
+           :include-source:
+
+           from qiskit import QuantumCircuit, QuantumRegister
+           from qiskit.circuit.library.standard_gates import HGate
+
+           qr = QuantumRegister(3)
+           qc = QuantumCircuit(qr)
+           c3h_gate = HGate().control(2)
+           qc.append(c3h_gate, qr)
+           qc.draw('mpl')
+
+        Create a controlled custom gate and apply it to a circuit.
+
+        .. plot::
+           :alt: Circuit diagram output by the previous code.
+           :include-source:
+
+           from qiskit import QuantumCircuit, QuantumRegister
+           from qiskit.circuit.library.standard_gates import HGate
+
+           qc1 = QuantumCircuit(2)
+           qc1.x(0)
+           qc1.h(1)
+           custom = qc1.to_gate().control(2)
+
+           qc2 = QuantumCircuit(4)
+           qc2.append(custom, [0, 3, 1, 2])
+           qc2.draw('mpl')
+        """
+        self.base_gate = None if base_gate is None else base_gate.copy()
+        super().__init__(name, num_qubits, params, label=label)
+        self._num_ctrl_qubits = 1
+        self.num_ctrl_qubits = num_ctrl_qubits
+        self.definition = copy.deepcopy(definition)
+        self._ctrl_state = None
+        self._open_ctrl = None
+        self.ctrl_state = ctrl_state
+        self._name = name
+
+    @property
+    def definition(self) -> QuantumCircuit:
+        """Return definition in terms of other basic gates. If the gate has
+        open controls, as determined from :attr:`ctrl_state`, the returned
+        definition is conjugated with X without changing the internal
+        ``_definition``.
+        """
+        if self._open_ctrl:
+            closed_gate = self.to_mutable()
+            closed_gate.ctrl_state = None
+            bit_ctrl_state = bin(self.ctrl_state)[2:].zfill(self.num_ctrl_qubits)
+            qreg = QuantumRegister(self.num_qubits, "q")
+            qc_open_ctrl = QuantumCircuit(qreg)
+            for qind, val in enumerate(bit_ctrl_state[::-1]):
+                if val == "0":
+                    qc_open_ctrl.x(qind)
+            qc_open_ctrl.append(closed_gate, qargs=qreg[:])
+            for qind, val in enumerate(bit_ctrl_state[::-1]):
+                if val == "0":
+                    qc_open_ctrl.x(qind)
+            return qc_open_ctrl
+        else:
+            return super().definition
+
+    @definition.setter
+    def definition(self, excited_def: "QuantumCircuit"):
+        """Set controlled gate definition with closed controls.
+
+        Args:
+            excited_def: The circuit with all closed controls.
+        """
+        self._definition = excited_def
+
+    @property
+    def name(self) -> str:
+        """Get name of gate. If the gate has open controls the gate name
+        will become:
+
+           <original_name_o<ctrl_state>
+
+        where <original_name> is the gate name for the default case of
+        closed control qubits and <ctrl_state> is the integer value of
+        the control state for the gate.
+        """
+        if self._open_ctrl:
+            return f"{self._name}_o{self.ctrl_state}"
+        else:
+            return self._name
+
+    @name.setter
+    def name(self, name_str):
+        """Set the name of the gate. Note the reported name may differ
+        from the set name if the gate has open controls.
+        """
+        self._name = name_str
+
+    @property
+    def num_ctrl_qubits(self):
+        """Get number of control qubits.
+
+        Returns:
+            int: The number of control qubits for the gate.
+        """
+        return self._num_ctrl_qubits
+
+    @num_ctrl_qubits.setter
+    def num_ctrl_qubits(self, num_ctrl_qubits):
+        """Set the number of control qubits.
+
+        Args:
+            num_ctrl_qubits (int): The number of control qubits.
+
+        Raises:
+            CircuitError: ``num_ctrl_qubits`` is not an integer in ``[1, num_qubits]``.
+        """
+        if num_ctrl_qubits != int(num_ctrl_qubits):
+            raise CircuitError("The number of control qubits must be an integer.")
+        num_ctrl_qubits = int(num_ctrl_qubits)
+        # This is a range rather than an equality limit because some controlled gates represent a
+        # controlled version of the base gate whose definition also uses auxiliary qubits.
+        upper_limit = self.num_qubits - getattr(self.base_gate, "num_qubits", 0)
+        if num_ctrl_qubits < 1 or num_ctrl_qubits > upper_limit:
+            limit = "num_qubits" if self.base_gate is None else "num_qubits - base_gate.num_qubits"
+            raise CircuitError(f"The number of control qubits must be in `[1, {limit}]`.")
+        self._num_ctrl_qubits = num_ctrl_qubits
+
+    @property
+    def ctrl_state(self) -> int:
+        """Return the control state of the gate as a decimal integer."""
+        return self._ctrl_state
+
+    @ctrl_state.setter
+    def ctrl_state(self, ctrl_state: Union[int, str, None]):
+        """Set the control state of this gate.
+
+        Args:
+            ctrl_state: The control state of the gate.
+
+        Raises:
+            CircuitError: ctrl_state is invalid.
+        """
+        self._ctrl_state = _ctrl_state_to_int(ctrl_state, self.num_ctrl_qubits)
+        self._open_ctrl = self.ctrl_state < 2**self.num_ctrl_qubits - 1
+
+    @property
+    def params(self):
+        """Get parameters from base_gate.
+
+        Returns:
+            list: List of gate parameters.
+
+        Raises:
+            CircuitError: Controlled gate does not define a base gate
+        """
+        if self.base_gate:
+            return self.base_gate.params
+        else:
+            raise CircuitError("Controlled gate does not define base gate for extracting params")
+
+    @params.setter
+    def params(self, parameters):
+        """Set base gate parameters.
+
+        Args:
+            parameters (list): The list of parameters to set.
+
+        Raises:
+            CircuitError: If controlled gate does not define a base gate.
+        """
+        if self.base_gate:
+            if self.base_gate.mutable:
+                self.base_gate.params = parameters
+            elif parameters:
+                raise CircuitError("cannot set parameters on immutable base gate")
+        else:
+            raise CircuitError("Controlled gate does not define base gate for extracting params")
+
+    def __deepcopy__(self, memo=None):
+        cpy = copy.copy(self)
+        cpy.base_gate = self.base_gate.copy()
+        if self._definition:
+            cpy._definition = copy.deepcopy(self._definition, memo)
+        return cpy
+
+    def __eq__(self, other) -> bool:
+        return (
+            isinstance(other, ControlledGate)
+            and self.num_ctrl_qubits == other.num_ctrl_qubits
+            and self.ctrl_state == other.ctrl_state
+            and self.base_gate == other.base_gate
+            and self.num_qubits == other.num_qubits
+            and self.num_clbits == other.num_clbits
+            and self.definition == other.definition
+        )
+
+    def inverse(self, annotated: bool = False) -> "ControlledGate" | "AnnotatedOperation":
+        """Invert this gate by calling inverse on the base gate."""
+        if not annotated:
+            inverse_gate = self.base_gate.inverse().control(
+                self.num_ctrl_qubits, ctrl_state=self.ctrl_state
+            )
+        else:
+            inverse_gate = super().inverse(annotated=annotated)
+        return inverse_gate

qiskit/circuit/delay.py

@@ -0,0 +1,159 @@
+# 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.
+
+"""
+Delay instruction (for circuit module).
+"""
+import numpy as np
+
+from qiskit.circuit.classical import expr, types
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.circuit.instruction import Instruction
+from qiskit.circuit.gate import Gate
+from qiskit.circuit import _utils
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit._accelerate.circuit import StandardInstructionType
+
+
+@_utils.with_gate_array(np.eye(2, dtype=complex))
+class Delay(Instruction):
+    """Do nothing and just delay/wait/idle for a specified duration."""
+
+    _standard_instruction_type = StandardInstructionType.Delay
+
+    def __init__(self, duration, unit=None):
+        """
+        Args:
+            duration: the length of time of the duration. If this is an
+                :class:`~.expr.Expr`, it must be a constant expression of type
+                :class:`~.types.Duration` and the ``unit`` parameter should be
+                omitted (or MUST be "expr" if it is specified).
+            unit: the unit of the duration, if ``duration`` is a numeric
+                value. Must be ``"dt"``, an SI-prefixed seconds unit, or "expr".
+
+        Raises:
+            CircuitError: A ``duration`` expression was specified with a resolved
+                type that is not timing-based, or the ``unit`` was improperly specified.
+        """
+        duration, self._unit = self._validate_arguments(duration, unit)
+        super().__init__("delay", 1, 0, params=[duration])
+
+    @staticmethod
+    def _validate_arguments(duration, unit):
+        # This method is a centralization of the unit-handling logic, so used elsewhere in Qiskit
+        # (e.g. in `BoxOp`).
+        if isinstance(duration, expr.Expr):
+            if unit is not None and unit != "expr":
+                raise CircuitError(
+                    "Argument 'unit' must not be specified for a duration expression."
+                )
+            if duration.type.kind is not types.Duration:
+                raise CircuitError(
+                    f"Expression of type '{duration.type}' is not valid for 'duration'."
+                )
+            if not duration.const:
+                raise CircuitError("Duration expressions must be constant.")
+            unit = "expr"
+        elif unit is None:
+            unit = "dt"
+        elif unit not in {"s", "ms", "us", "ns", "ps", "dt"}:
+            raise CircuitError(f"Unknown unit {unit} is specified.")
+        return duration, unit
+
+    broadcast_arguments = Gate.broadcast_arguments
+
+    def inverse(self, annotated: bool = False):
+        """Special case. Return self."""
+        return self
+
+    @property
+    def unit(self):
+        """The unit for the duration of the delay in :attr`.params`"""
+        return self._unit
+
+    @unit.setter
+    def unit(self, value):
+        if value not in {"s", "ms", "us", "ns", "ps", "dt"}:
+            raise CircuitError(f"Unknown unit {value} is specified.")
+        self._unit = value
+
+    @property
+    def duration(self):
+        """Get the duration of this delay."""
+        return self.params[0]
+
+    @duration.setter
+    def duration(self, duration):
+        """Set the duration of this delay."""
+        self.params = [duration]
+
+    def to_matrix(self) -> np.ndarray:
+        """Return a Numpy.array for the unitary matrix. This has been
+        added to enable simulation without making delay a full Gate type.
+
+        Returns:
+            np.ndarray: matrix representation.
+        """
+        return self.__array__(dtype=complex)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, Delay) and self.unit == other.unit and self._compare_parameters(other)
+        )
+
+    def __repr__(self):
+        """Return the official string representing the delay."""
+        return f"{self.__class__.__name__}(duration={self.params[0]}[unit={self.unit}])"
+
+    # pylint: disable=too-many-return-statements
+    def validate_parameter(self, parameter):
+        """Delay parameter (i.e. duration) must be Expr, int, float or ParameterExpression."""
+        if isinstance(parameter, int):
+            if parameter < 0:
+                raise CircuitError(
+                    f"Duration for Delay instruction must be positive. Found {parameter}"
+                )
+            return parameter
+        elif isinstance(parameter, float):
+            if parameter < 0:
+                raise CircuitError(
+                    f"Duration for Delay instruction must be positive. Found {parameter}"
+                )
+            if self._unit == "dt":
+                parameter_int = int(parameter)
+                if parameter != parameter_int:
+                    raise CircuitError("Integer duration is expected for 'dt' unit.")
+                return parameter_int
+            return parameter
+        elif isinstance(parameter, expr.Expr):
+            if parameter.type.kind is not types.Duration:
+                raise CircuitError(f"Expression duration of type '{parameter.type}' is not valid.")
+            if not parameter.const:
+                raise CircuitError("Duration expressions must be constant.")
+            return parameter
+        elif isinstance(parameter, ParameterExpression):
+            if len(parameter.parameters) > 0:
+                return parameter  # expression has free parameters, we cannot validate it
+            if not parameter.is_real():
+                raise CircuitError(f"Bound parameter expression is complex in delay {self.name}")
+            fval = float(parameter)
+            if fval < 0:
+                raise CircuitError(f"Duration for Delay instruction must be positive. Found {fval}")
+            if self.unit == "dt":
+                ival = int(parameter)
+                rounding_error = abs(fval - ival)
+                if rounding_error > 1e-15:
+                    raise CircuitError("Integer parameter is required for duration in 'dt' unit.")
+                return ival
+            return fval  # per default assume parameters must be real when bound
+        else:
+            raise CircuitError(f"Invalid param type {type(parameter)} for delay {self.name}.")

qiskit/circuit/duration.py

@@ -0,0 +1,80 @@
+# 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.
+
+"""
+Utilities for handling duration of a circuit instruction.
+"""
+import warnings
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.utils.units import apply_prefix
+
+
+def duration_in_dt(duration_in_sec: float, dt_in_sec: float) -> int:
+    """
+    Return duration in dt.
+
+    Args:
+        duration_in_sec: duration [s] to be converted.
+        dt_in_sec: duration of dt in seconds used for conversion.
+
+    Returns:
+        Duration in dt.
+    """
+    res = round(duration_in_sec / dt_in_sec)
+    rounding_error = abs(duration_in_sec - res * dt_in_sec)
+    if rounding_error > 1e-15:
+        warnings.warn(
+            f"Duration is rounded to {res:d} [dt] = {res * dt_in_sec:e} [s] "
+            f"from {duration_in_sec:e} [s]",
+            UserWarning,
+        )
+    return res
+
+
+def convert_durations_to_dt(qc: QuantumCircuit, dt_in_sec: float, inplace=True):
+    """Convert all the durations in SI (seconds) into those in dt.
+
+    Returns a new circuit if `inplace=False`.
+
+    Parameters:
+        qc (QuantumCircuit): Duration of dt in seconds used for conversion.
+        dt_in_sec (float): Duration of dt in seconds used for conversion.
+        inplace (bool): All durations are converted inplace or return new circuit.
+
+    Returns:
+        QuantumCircuit: Converted circuit if `inplace = False`, otherwise None.
+
+    Raises:
+        CircuitError: if fail to convert durations.
+    """
+    if inplace:
+        circ = qc
+    else:
+        circ = qc.copy()
+
+    if circ.duration is not None and circ.unit != "dt":
+        if not circ.unit.endswith("s"):
+            raise CircuitError(f"Invalid time unit: '{circ.unit}'")
+
+        duration = circ.duration
+        if circ.unit != "s":
+            duration = apply_prefix(duration, circ.unit)
+
+        circ.duration = duration_in_dt(duration, dt_in_sec)
+        circ.unit = "dt"
+
+    if not inplace:
+        return circ
+    else:
+        return None

qiskit/circuit/equivalence.py

@@ -0,0 +1,94 @@
+# 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."""
+
+from rustworkx.visualization import graphviz_draw
+import rustworkx as rx
+
+
+from qiskit.exceptions import InvalidFileError
+from qiskit._accelerate.equivalence import (  # pylint: disable=unused-import
+    BaseEquivalenceLibrary,
+    Key,
+    Equivalence,
+    NodeData,
+    EdgeData,
+)
+
+
+class EquivalenceLibrary(BaseEquivalenceLibrary):
+    """A library providing a one-way mapping of Gates to their equivalent
+    implementations as QuantumCircuits."""
+
+    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 super().keys():
+            name, num_qubits = key.name, key.num_qubits
+            equivalences = self._get_equivalences(key)
+
+            basis = frozenset([f"{name}/{num_qubits}"])
+            for equivalence in equivalences:
+                params, decomp = equivalence.params, equivalence.circuit
+                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

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."""