qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/_utils.py

@@ -0,0 +1,167 @@
+# 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.
+"""
+This module contains utility functions for circuits.
+"""
+
+import math
+import numpy
+
+from qiskit import _numpy_compat
+from qiskit.exceptions import QiskitError
+from qiskit.circuit.exceptions import CircuitError
+
+
+def _compute_control_matrix(base_mat, num_ctrl_qubits, ctrl_state=None):
+    r"""
+    Compute the controlled version of the input matrix with qiskit ordering.
+    This function computes the controlled unitary with :math:`n` control qubits
+    and :math:`m` target qubits,
+
+    .. math::
+
+        V_n^j(U_{2^m}) = (U_{2^m} \otimes |j\rangle\!\langle j|) +
+                         (I_{2^m} \otimes (I_{2^n} - |j\rangle\!\langle j|)).
+
+    where :math:`|j\rangle \in \mathcal{H}^{2^n}` is the control state.
+
+    Args:
+        base_mat (ndarray): unitary to be controlled
+        num_ctrl_qubits (int): number of controls for new unitary
+        ctrl_state (int or str or None): The control state in decimal or as
+            a bitstring (e.g. '111'). If None, use 2**num_ctrl_qubits-1.
+
+    Returns:
+        ndarray: controlled version of base matrix.
+
+    Raises:
+        QiskitError: unrecognized mode or invalid ctrl_state
+    """
+    num_target = int(math.log2(base_mat.shape[0]))
+    ctrl_dim = 2**num_ctrl_qubits
+    ctrl_grnd = numpy.repeat([[1], [0]], [1, ctrl_dim - 1])
+    if ctrl_state is None:
+        ctrl_state = ctrl_dim - 1
+    elif isinstance(ctrl_state, str):
+        ctrl_state = int(ctrl_state, 2)
+    if isinstance(ctrl_state, int):
+        if not 0 <= ctrl_state < ctrl_dim:
+            raise QiskitError("Invalid control state value specified.")
+    else:
+        raise QiskitError("Invalid control state type specified.")
+    ctrl_proj = numpy.diag(numpy.roll(ctrl_grnd, ctrl_state))
+    full_mat = numpy.kron(numpy.eye(2**num_target), numpy.eye(ctrl_dim) - ctrl_proj) + numpy.kron(
+        base_mat, ctrl_proj
+    )
+    return full_mat
+
+
+def _ctrl_state_to_int(ctrl_state, num_ctrl_qubits):
+    """Convert ctrl_state to int.
+
+    Args:
+        ctrl_state (None, str, int): ctrl_state. If None, set to 2**num_ctrl_qubits-1.
+            If str, convert to int. If int, pass.
+        num_ctrl_qubits (int): The number of control qubits.
+
+    Return:
+        int: ctrl_state
+
+    Raises:
+        CircuitError: invalid ctrl_state
+    """
+    ctrl_state_std = None
+    if isinstance(ctrl_state, str):
+        try:
+            assert len(ctrl_state) == num_ctrl_qubits
+            ctrl_state = int(ctrl_state, 2)
+        except ValueError as ex:
+            raise CircuitError("invalid control bit string: " + ctrl_state) from ex
+        except AssertionError as ex:
+            raise CircuitError("invalid control bit string: length != num_ctrl_qubits") from ex
+    if isinstance(ctrl_state, int):
+        if 0 <= ctrl_state < 2**num_ctrl_qubits:
+            ctrl_state_std = ctrl_state
+        else:
+            raise CircuitError("invalid control state specification")
+    elif ctrl_state is None:
+        ctrl_state_std = 2**num_ctrl_qubits - 1
+    else:
+        raise CircuitError(f"invalid control state specification: {repr(ctrl_state)}")
+    return ctrl_state_std
+
+
+def with_gate_array(base_array):
+    """Class decorator that adds an ``__array__`` method to a :class:`.Gate` instance that returns a
+    singleton nonwritable view onto the complex matrix described by ``base_array``."""
+    nonwritable = numpy.array(base_array, dtype=numpy.complex128)
+    nonwritable.setflags(write=False)
+
+    def __array__(_self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+        dtype = nonwritable.dtype if dtype is None else dtype
+        return numpy.array(nonwritable, dtype=dtype, copy=copy)
+
+    def decorator(cls):
+        if hasattr(cls, "__array__"):
+            raise RuntimeError("Refusing to decorate a class that already has '__array__' defined.")
+        cls.__array__ = __array__
+        return cls
+
+    return decorator
+
+
+def with_controlled_gate_array(base_array, num_ctrl_qubits, cached_states=None):
+    """Class decorator that adds an ``__array__`` method to a :class:`.ControlledGate` instance that
+    returns singleton nonwritable views onto a relevant precomputed complex matrix for the given
+    control state.
+
+    If ``cached_states`` is not given, then all possible control states are precomputed.  If it is
+    given, it should be an iterable of integers, and only these control states will be cached."""
+    base = numpy.asarray(base_array, dtype=numpy.complex128)
+
+    def matrix_for_control_state(state):
+        out = numpy.asarray(
+            _compute_control_matrix(base, num_ctrl_qubits, state),
+            dtype=numpy.complex128,
+        )
+        out.setflags(write=False)
+        return out
+
+    if cached_states is None:
+        nonwritables = [matrix_for_control_state(state) for state in range(2**num_ctrl_qubits)]
+
+        def __array__(self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+            arr = nonwritables[self.ctrl_state]
+            dtype = arr.dtype if dtype is None else dtype
+            return numpy.array(arr, dtype=dtype, copy=copy)
+
+    else:
+        nonwritables = {state: matrix_for_control_state(state) for state in cached_states}
+
+        def __array__(self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+            if (arr := nonwritables.get(self.ctrl_state)) is not None:
+                dtype = arr.dtype if dtype is None else dtype
+                return numpy.array(arr, dtype=dtype, copy=copy)
+
+            if copy is False and copy is not _numpy_compat.COPY_ONLY_IF_NEEDED:
+                raise ValueError("could not produce matrix without calculation")
+            return numpy.asarray(
+                _compute_control_matrix(base, num_ctrl_qubits, self.ctrl_state), dtype=dtype
+            )
+
+    def decorator(cls):
+        if hasattr(cls, "__array__"):
+            raise RuntimeError("Refusing to decorate a class that already has '__array__' defined.")
+        cls.__array__ = __array__
+        return cls
+
+    return decorator

qiskit/circuit/annotated_operation.py

@@ -0,0 +1,279 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+"""Annotated Operations."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Union, List
+
+from qiskit.circuit.operation import Operation
+from qiskit.circuit.parameterexpression import ParameterValueType
+from qiskit.circuit._utils import _compute_control_matrix, _ctrl_state_to_int
+from qiskit.circuit.exceptions import CircuitError
+
+
+class Modifier:
+    """The base class that all modifiers of :class:`~.AnnotatedOperation` should
+    inherit from."""
+
+    pass
+
+
+@dataclasses.dataclass
+class InverseModifier(Modifier):
+    """Inverse modifier: specifies that the operation is inverted."""
+
+    pass
+
+
+@dataclasses.dataclass
+class ControlModifier(Modifier):
+    """Control modifier: specifies that the operation is controlled by ``num_ctrl_qubits``
+    and has control state ``ctrl_state``."""
+
+    num_ctrl_qubits: int = 0
+    ctrl_state: Union[int, str, None] = None
+
+    def __init__(self, num_ctrl_qubits: int = 0, ctrl_state: Union[int, str, None] = None):
+        self.num_ctrl_qubits = num_ctrl_qubits
+        self.ctrl_state = _ctrl_state_to_int(ctrl_state, num_ctrl_qubits)
+
+
+@dataclasses.dataclass
+class PowerModifier(Modifier):
+    """Power modifier: specifies that the operation is raised to the power ``power``."""
+
+    power: float
+
+
+class AnnotatedOperation(Operation):
+    """Annotated operation."""
+
+    def __init__(self, base_op: Operation, modifiers: Union[Modifier, List[Modifier]]):
+        """
+        Create a new AnnotatedOperation.
+
+        An "annotated operation" allows to add a list of modifiers to the
+        "base" operation. For now, the only supported modifiers are of
+        types :class:`~.InverseModifier`, :class:`~.ControlModifier` and
+        :class:`~.PowerModifier`.
+
+        An annotated operation can be viewed as an extension of
+        :class:`~.ControlledGate` (which also allows adding control to the
+        base operation). However, an important difference is that the
+        circuit definition of an annotated operation is not constructed when
+        the operation is declared, and instead happens during transpilation,
+        specifically during the :class:`~.HighLevelSynthesis` transpiler pass.
+
+        An annotated operation can be also viewed as a "higher-level"
+        or "more abstract" object that can be added to a quantum circuit.
+        This enables writing transpiler optimization passes that make use of
+        this higher-level representation, for instance removing a gate
+        that is immediately followed by its inverse.
+
+        Args:
+            base_op: base operation being modified
+            modifiers: ordered list of modifiers. Supported modifiers include
+                ``InverseModifier``, ``ControlModifier`` and ``PowerModifier``.
+
+        Examples::
+
+            op1 = AnnotatedOperation(SGate(), [InverseModifier(), ControlModifier(2)])
+
+            op2_inner = AnnotatedGate(SGate(), InverseModifier())
+            op2 = AnnotatedGate(op2_inner, ControlModifier(2))
+
+        Both op1 and op2 are semantically equivalent to an ``SGate()`` which is first
+        inverted and then controlled by 2 qubits.
+        """
+        self.base_op = base_op
+        """The base operation that the modifiers in this annotated operation applies to."""
+        self.modifiers = modifiers if isinstance(modifiers, List) else [modifiers]
+        """Ordered sequence of the modifiers to apply to :attr:`base_op`.  The modifiers are applied
+        in order from lowest index to highest index."""
+
+    @property
+    def name(self):
+        """Unique string identifier for operation type."""
+        return "annotated"
+
+    @property
+    def num_qubits(self):
+        """Number of qubits."""
+        num_ctrl_qubits = 0
+        for modifier in self.modifiers:
+            if isinstance(modifier, ControlModifier):
+                num_ctrl_qubits += modifier.num_ctrl_qubits
+
+        return num_ctrl_qubits + self.base_op.num_qubits
+
+    @property
+    def num_clbits(self):
+        """Number of classical bits."""
+        return self.base_op.num_clbits
+
+    def __eq__(self, other) -> bool:
+        """Checks if two AnnotatedOperations are equal."""
+        return (
+            isinstance(other, AnnotatedOperation)
+            and self.modifiers == other.modifiers
+            and self.base_op == other.base_op
+        )
+
+    def copy(self) -> "AnnotatedOperation":
+        """Return a copy of the :class:`~.AnnotatedOperation`."""
+        return AnnotatedOperation(base_op=self.base_op.copy(), modifiers=self.modifiers.copy())
+
+    def to_matrix(self):
+        """Return a matrix representation (allowing to construct Operator)."""
+        from qiskit.quantum_info.operators import Operator  # pylint: disable=cyclic-import
+
+        operator = Operator(self.base_op)
+
+        for modifier in self.modifiers:
+            if isinstance(modifier, InverseModifier):
+                operator = operator.power(-1)
+            elif isinstance(modifier, ControlModifier):
+                operator = Operator(
+                    _compute_control_matrix(
+                        operator.data, modifier.num_ctrl_qubits, modifier.ctrl_state
+                    )
+                )
+            elif isinstance(modifier, PowerModifier):
+                operator = operator.power(modifier.power)
+            else:
+                raise CircuitError(f"Unknown modifier {modifier}.")
+        return operator
+
+    def control(
+        self,
+        num_ctrl_qubits: int = 1,
+        label: str | None = None,
+        ctrl_state: int | str | None = None,
+        annotated: bool = True,
+    ) -> AnnotatedOperation:
+        """
+        Return the controlled version of itself.
+
+        Implemented as an annotated operation, see  :class:`.AnnotatedOperation`.
+
+        Args:
+            num_ctrl_qubits: number of controls to add to gate (default: ``1``)
+            label: ignored (used for consistency with other control methods)
+            ctrl_state: The control state in decimal or as a bitstring
+                (e.g. ``'111'``). If ``None``, use ``2**num_ctrl_qubits-1``.
+            annotated: ignored (used for consistency with other control methods)
+
+        Returns:
+            Controlled version of the given operation.
+        """
+        # pylint: disable=unused-argument
+        extended_modifiers = self.modifiers.copy()
+        extended_modifiers.append(
+            ControlModifier(num_ctrl_qubits=num_ctrl_qubits, ctrl_state=ctrl_state)
+        )
+        return AnnotatedOperation(self.base_op, extended_modifiers)
+
+    def inverse(self, annotated: bool = True):
+        """
+        Return the inverse version of itself.
+
+        Implemented as an annotated operation, see  :class:`.AnnotatedOperation`.
+
+        Args:
+            annotated: ignored (used for consistency with other inverse methods)
+
+        Returns:
+            Inverse version of the given operation.
+        """
+        # pylint: disable=unused-argument
+        extended_modifiers = self.modifiers.copy()
+        extended_modifiers.append(InverseModifier())
+        return AnnotatedOperation(self.base_op, extended_modifiers)
+
+    def power(self, exponent: float, annotated: bool = False):
+        """
+        Raise this gate to the power of ``exponent``.
+
+        Implemented as an annotated operation, see  :class:`.AnnotatedOperation`.
+
+        Args:
+            exponent: the power to raise the gate to
+            annotated: ignored (used for consistency with other power methods)
+
+        Returns:
+            An operation implementing ``gate^exponent``
+        """
+        # pylint: disable=unused-argument
+        extended_modifiers = self.modifiers.copy()
+        extended_modifiers.append(PowerModifier(exponent))
+        return AnnotatedOperation(self.base_op, extended_modifiers)
+
+    @property
+    def params(self) -> list[ParameterValueType]:
+        """The params of the underlying base operation."""
+        return getattr(self.base_op, "params", [])
+
+    @params.setter
+    def params(self, value: list[ParameterValueType]):
+        if hasattr(self.base_op, "params"):
+            self.base_op.params = value
+        else:
+            raise AttributeError(
+                f"Cannot set attribute ``params`` on the base operation {self.base_op}."
+            )
+
+    def validate_parameter(self, parameter: ParameterValueType) -> ParameterValueType:
+        """Validate a parameter for the underlying base operation."""
+        if hasattr(self.base_op, "validate_parameter"):
+            return self.base_op.validate_parameter(parameter)
+
+        raise AttributeError(f"Cannot validate parameters on the base operation {self.base_op}.")
+
+
+def _canonicalize_modifiers(modifiers):
+    """
+    Returns the canonical representative of the modifier list. This is possible
+    since all the modifiers commute; also note that InverseModifier is a special
+    case of PowerModifier. The current solution is to compute the total number
+    of control qubits / control state and the total power. The InverseModifier
+    will be present if total power is negative, whereas the power modifier will
+    be present only with positive powers different from 1.
+    """
+    power = 1
+    num_ctrl_qubits = 0
+    ctrl_state = 0
+
+    for modifier in modifiers:
+        if isinstance(modifier, InverseModifier):
+            power *= -1
+        elif isinstance(modifier, ControlModifier):
+            num_ctrl_qubits += modifier.num_ctrl_qubits
+            ctrl_state = (ctrl_state << modifier.num_ctrl_qubits) | modifier.ctrl_state
+        elif isinstance(modifier, PowerModifier):
+            power *= modifier.power
+        else:
+            raise CircuitError(f"Unknown modifier {modifier}.")
+
+    canonical_modifiers = []
+    if power < 0:
+        canonical_modifiers.append(InverseModifier())
+        power *= -1
+
+    if power != 1:
+        canonical_modifiers.append(PowerModifier(power))
+    if num_ctrl_qubits > 0:
+        canonical_modifiers.append(ControlModifier(num_ctrl_qubits, ctrl_state))
+
+    return canonical_modifiers