qiskit 1.3.0__cp39-abi3-win32.whl

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

qiskit/circuit/barrier.py

@@ -0,0 +1,50 @@
+# 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.
+
+"""Barrier instruction.
+
+Can be applied to a :class:`~qiskit.circuit.QuantumCircuit`
+with the :meth:`~qiskit.circuit.QuantumCircuit.barrier` method.
+"""
+
+from __future__ import annotations
+
+from qiskit.exceptions import QiskitError
+from qiskit.utils import deprecate_func
+from .instruction import Instruction
+
+
+class Barrier(Instruction):
+    """A directive for circuit compilation to separate pieces of a circuit so that any optimizations
+    or re-writes are constrained to only act between barriers.
+
+    This will also appear in visualizations as a visual marker.
+    """
+
+    _directive = True
+
+    def __init__(self, num_qubits: int, label: str | None = None):
+        """
+        Args:
+            num_qubits: the number of qubits for the barrier.
+            label: the optional label of this barrier.
+        """
+        self._label = label
+        super().__init__("barrier", num_qubits, 0, [], label=label)
+
+    def inverse(self, annotated: bool = False):
+        """Special case. Return self."""
+        return Barrier(self.num_qubits)
+
+    @deprecate_func(since="1.3.0", removal_timeline="in 2.0.0")
+    def c_if(self, classical, val):
+        raise QiskitError("Barriers are compiler directives and cannot be conditional.")

qiskit/circuit/bit.py

@@ -0,0 +1,94 @@
+# 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.
+
+"""
+Quantum bit and Classical bit objects.
+"""
+import copy
+
+from qiskit.circuit.exceptions import CircuitError
+
+
+class Bit:
+    """Implement a generic bit.
+
+    .. note::
+        This class should not be instantiated directly. This is just a superclass
+        for :class:`~.Clbit` and :class:`~.circuit.Qubit`.
+    """
+
+    __slots__ = {"_register", "_index", "_hash", "_repr"}
+
+    def __init__(self, register=None, index=None):
+        """Create a new generic bit."""
+        if (register, index) == (None, None):
+            self._register = None
+            self._index = None
+            # To sidestep the overridden Bit.__hash__ and use the default hash
+            # algorithm (only new-style Bits), call default object hash method.
+            self._hash = object.__hash__(self)
+        else:
+            try:
+                index = int(index)
+            except Exception as ex:
+                raise CircuitError(
+                    f"index needs to be castable to an int: type {type(index)} was provided"
+                ) from ex
+
+            if index < 0:
+                index += register.size
+
+            if index >= register.size:
+                raise CircuitError(
+                    f"index must be under the size of the register: {index} was provided"
+                )
+
+            self._register = register
+            self._index = index
+            self._hash = hash((self._register, self._index))
+            self._repr = f"{self.__class__.__name__}({self._register}, {self._index})"
+
+    def __repr__(self):
+        """Return the official string representing the bit."""
+        if (self._register, self._index) == (None, None):
+            # Similar to __hash__, use default repr method for new-style Bits.
+            return object.__repr__(self)
+        return self._repr
+
+    def __hash__(self):
+        return self._hash
+
+    def __eq__(self, other):
+        if (self._register, self._index) == (None, None):
+            return other is self
+
+        try:
+            return self._repr == other._repr
+        except AttributeError:
+            return False
+
+    def __copy__(self):
+        # Bits are immutable.
+        return self
+
+    def __deepcopy__(self, memo=None):
+        if (self._register, self._index) == (None, None):
+            return self
+
+        # Old-style bits need special handling for now, since some code seems
+        # to rely on their registers getting deep-copied.
+        bit = type(self).__new__(type(self))
+        bit._register = copy.deepcopy(self._register, memo)
+        bit._index = self._index
+        bit._hash = self._hash
+        bit._repr = self._repr
+        return bit

qiskit/circuit/classical/__init__.py

@@ -0,0 +1,41 @@
+# 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.
+
+"""
+=======================================================
+Classical expressions (:mod:`qiskit.circuit.classical`)
+=======================================================
+
+This module contains an exploratory representation of real-time operations on classical values
+during circuit execution.
+
+Currently, only simple expressions on bits and registers that result in a Boolean value are
+supported, and these are only valid for use in the conditions of :meth:`.QuantumCircuit.if_test`
+(:class:`.IfElseOp`) and :meth:`.QuantumCircuit.while_loop` (:class:`.WhileLoopOp`), and in the
+target of :meth:`.QuantumCircuit.switch` (:class:`.SwitchCaseOp`).
+
+.. note::
+    This is an exploratory module, and while we will commit to the standard Qiskit deprecation
+    policy within it, please be aware that the module will be deliberately limited in scope at the
+    start, and early versions may not evolve cleanly into the final version.  It is possible that
+    various components of this module will be replaced (subject to deprecations) instead of improved
+    into a new form.
+
+    The type system and expression tree will be expanded over time, and it is possible that the
+    allowed types of some operations may need to change between versions of Qiskit as the classical
+    processing capabilities develop.
+
+.. automodule:: qiskit.circuit.classical.expr
+.. automodule:: qiskit.circuit.classical.types
+"""
+
+from . import types, expr