qiskit 1.0.2__cp38-abi3-win32.whl → 1.1.0__cp38-abi3-win32.whl

qiskit/circuit/controlflow/control_flow.py

@@ -18,28 +18,67 @@ import typing
 from abc import ABC, abstractmethod
 
 from qiskit.circuit.instruction import Instruction
+from qiskit.circuit.exceptions import CircuitError
 
 if typing.TYPE_CHECKING:
     from qiskit.circuit import QuantumCircuit
+    from qiskit.circuit.classical import expr
 
 
 class ControlFlowOp(Instruction, ABC):
-    """Abstract class to encapsulate all control flow operations."""
+    """Abstract class to encapsulate all control flow operations.
+
+    All subclasses of :class:`ControlFlowOp` have an internal attribute,
+    :attr:`~ControlFlowOp.blocks`, which exposes the inner subcircuits used in the different blocks
+    of the control flow.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        for block in self.blocks:
+            if block.num_input_vars:
+                raise CircuitError("control-flow blocks cannot contain input variables")
 
     @property
     @abstractmethod
     def blocks(self) -> tuple[QuantumCircuit, ...]:
-        """Tuple of QuantumCircuits which may be executed as part of the
-        execution of this ControlFlowOp. May be parameterized by a loop
-        parameter to be resolved at run time.
-        """
+        """Tuple of :class:`.QuantumCircuit`\\ s which may be executed as part of the
+        execution of this :class:`ControlFlowOp`."""
 
     @abstractmethod
     def replace_blocks(self, blocks: typing.Iterable[QuantumCircuit]) -> ControlFlowOp:
-        """Replace blocks and return new instruction.
+        """Return a new version of this control-flow operations with the :attr:`blocks` mapped to
+        the given new ones.
+
+        Typically this is used in a workflow such as::
+
+            existing_op = ...
+
+            def map_block(block: QuantumCircuit) -> QuantumCircuit:
+                new_block = block.copy_empty_like()
+                # ... do something to `new_block` ...
+                return new_block
+
+            new_op = existing_op.replace_blocks(
+                map_block(block) for block in existing_op.blocks
+            )
+
+        It is the caller's responsibility to ensure that the mapped blocks are defined over a
+        unified set of circuit resources, much like constructing a :class:`ControlFlowOp` using its
+        default constructor.
+
         Args:
-            blocks: Tuple of QuantumCircuits to replace in instruction.
+            blocks: the new subcircuit blocks to use.
 
         Returns:
-            New ControlFlowOp with replaced blocks.
+            New :class:`ControlFlowOp` with replaced blocks.
         """
+
+    def iter_captured_vars(self) -> typing.Iterable[expr.Var]:
+        """Get an iterator over the unique captured variables in all blocks of this construct."""
+        seen = set()
+        for block in self.blocks:
+            for var in block.iter_captured_vars():
+                if var not in seen:
+                    seen.add(var)
+                    yield var

qiskit/circuit/controlflow/for_loop.py

@@ -29,28 +29,6 @@ class ForLoopOp(ControlFlowOp):
     """A circuit operation which repeatedly executes a subcircuit
     (``body``) parameterized by a parameter ``loop_parameter`` through
     the set of integer values provided in ``indexset``.
-
-    Parameters:
-        indexset: A collection of integers to loop over.
-        loop_parameter: The placeholder parameterizing ``body`` to which
-            the values from ``indexset`` will be assigned.
-        body: The loop body to be repeatedly executed.
-        label: An optional label for identifying the instruction.
-
-    **Circuit symbol:**
-
-    .. parsed-literal::
-
-             ┌───────────┐
-        q_0: ┤0          ├
-             │           │
-        q_1: ┤1          ├
-             │  for_loop │
-        q_2: ┤2          ├
-             │           │
-        c_0: ╡0          ╞
-             └───────────┘
-
     """
 
     def __init__(
@@ -60,9 +38,16 @@ class ForLoopOp(ControlFlowOp):
         body: QuantumCircuit,
         label: Optional[str] = None,
     ):
+        """
+        Args:
+            indexset: A collection of integers to loop over.
+            loop_parameter: The placeholder parameterizing ``body`` to which
+                the values from ``indexset`` will be assigned.
+            body: The loop body to be repeatedly executed.
+            label: An optional label for identifying the instruction.
+        """
         num_qubits = body.num_qubits
         num_clbits = body.num_clbits
-
         super().__init__(
             "for_loop", num_qubits, num_clbits, [indexset, loop_parameter, body], label=label
         )

qiskit/circuit/controlflow/if_else.py

@@ -44,38 +44,11 @@ class IfElseOp(ControlFlowOp):
     provided condition (``condition``) evaluates to true, and
     optionally evaluates another program (``false_body``) otherwise.
 
-    Parameters:
-        condition: A condition to be evaluated at circuit runtime which,
-            if true, will trigger the evaluation of ``true_body``. Can be
-            specified as either a tuple of a ``ClassicalRegister`` to be
-            tested for equality with a given ``int``, or as a tuple of a
-            ``Clbit`` to be compared to either a ``bool`` or an ``int``.
-        true_body: A program to be executed if ``condition`` evaluates
-            to true.
-        false_body: A optional program to be executed if ``condition``
-            evaluates to false.
-        label: An optional label for identifying the instruction.
-
     If provided, ``false_body`` must be of the same ``num_qubits`` and
     ``num_clbits`` as ``true_body``.
 
     The classical bits used in ``condition`` must be a subset of those attached
     to the circuit on which this ``IfElseOp`` will be appended.
-
-    **Circuit symbol:**
-
-    .. parsed-literal::
-
-             ┌───────────┐
-        q_0: ┤0          ├
-             │           │
-        q_1: ┤1          ├
-             │  if_else  │
-        q_2: ┤2          ├
-             │           │
-        c_0: ╡0          ╞
-             └───────────┘
-
     """
 
     def __init__(
@@ -85,6 +58,19 @@ class IfElseOp(ControlFlowOp):
         false_body: QuantumCircuit | None = None,
         label: str | None = None,
     ):
+        """
+        Args:
+            condition: A condition to be evaluated in real time during circuit execution which,
+                if true, will trigger the evaluation of ``true_body``. Can be
+                specified as either a tuple of a ``ClassicalRegister`` to be
+                tested for equality with a given ``int``, or as a tuple of a
+                ``Clbit`` to be compared to either a ``bool`` or an ``int``.
+            true_body: A program to be executed if ``condition`` evaluates
+                to true.
+            false_body: A optional program to be executed if ``condition``
+                evaluates to false.
+            label: An optional label for identifying the instruction.
+        """
         # pylint: disable=cyclic-import
         from qiskit.circuit import QuantumCircuit
 

qiskit/circuit/controlflow/switch_case.py

@@ -32,39 +32,25 @@ if TYPE_CHECKING:
 
 
 class _DefaultCaseType:
-    """The type of the default-case singleton.  This is used instead of just having
-    ``CASE_DEFAULT = object()`` so we can set the pretty-printing properties, which are class-level
-    only."""
+    # Note: Sphinx uses the docstring of this singleton class object as the documentation of the
+    # `CASE_DEFAULT` object.
+
+    """A special object that represents the "default" case of a switch statement.  If you use this
+    as a case target, it must be the last case, and will match anything that wasn't already matched.
+    When using the builder interface of :meth:`.QuantumCircuit.switch`, this can also be accessed as
+    the ``DEFAULT`` attribute of the bound case-builder object."""
 
     def __repr__(self):
         return "<default case>"
 
 
 CASE_DEFAULT = _DefaultCaseType()
-"""A special object that represents the "default" case of a switch statement.  If you use this
-as a case target, it must be the last case, and will match anything that wasn't already matched.
-When using the builder interface of :meth:`.QuantumCircuit.switch`, this can also be accessed as the
-``DEFAULT`` attribute of the bound case-builder object."""
 
 
 class SwitchCaseOp(ControlFlowOp):
     """A circuit operation that executes one particular circuit block based on matching a given
     ``target`` against an ordered list of ``values``.  The special value :data:`.CASE_DEFAULT` can
     be used to represent a default condition.
-
-    This is the low-level interface for creating a switch-case statement; in general, the circuit
-    method :meth:`.QuantumCircuit.switch` should be used as a context manager to access the
-    builder interface.  At the low level, you must ensure that all the circuit blocks contain equal
-    numbers of qubits and clbits, and that the order the virtual bits of the containing circuit
-    should be bound is the same for all blocks.  This will likely mean that each circuit block is
-    wider than its natural width, as each block must span the union of all the spaces covered by
-    *any* of the blocks.
-
-    Args:
-        target: the runtime value to switch on.
-        cases: an ordered iterable of the corresponding value of the ``target`` and the circuit
-            block that should be executed if this is matched.  There is no fall-through between
-            blocks, and the order matters.
     """
 
     def __init__(
@@ -74,6 +60,13 @@ class SwitchCaseOp(ControlFlowOp):
         *,
         label: Optional[str] = None,
     ):
+        """
+        Args:
+            target: the real-time value to switch on.
+            cases: an ordered iterable of the corresponding value of the ``target`` and the circuit
+                block that should be executed if this is matched.  There is no fall-through between
+                blocks, and the order matters.
+        """
         # pylint: disable=cyclic-import
         from qiskit.circuit import QuantumCircuit
 

qiskit/circuit/controlflow/while_loop.py

@@ -30,31 +30,8 @@ class WhileLoopOp(ControlFlowOp):
     """A circuit operation which repeatedly executes a subcircuit (``body``) until
     a condition (``condition``) evaluates as False.
 
-    Parameters:
-        condition: A condition to be checked prior to executing ``body``. Can be
-            specified as either a tuple of a ``ClassicalRegister`` to be tested
-            for equality with a given ``int``, or as a tuple of a ``Clbit`` to
-            be compared to either a ``bool`` or an ``int``.
-        body: The loop body to be repeatedly executed.
-        label: An optional label for identifying the instruction.
-
     The classical bits used in ``condition`` must be a subset of those attached
     to ``body``.
-
-    **Circuit symbol:**
-
-    .. parsed-literal::
-
-             ┌─────────────┐
-        q_0: ┤0            ├
-             │             │
-        q_1: ┤1            ├
-             │  while_loop │
-        q_2: ┤2            ├
-             │             │
-        c_0: ╡0            ╞
-             └─────────────┘
-
     """
 
     def __init__(
@@ -63,6 +40,15 @@ class WhileLoopOp(ControlFlowOp):
         body: QuantumCircuit,
         label: str | None = None,
     ):
+        """
+        Args:
+            condition: A condition to be checked prior to executing ``body``. Can be
+                specified as either a tuple of a ``ClassicalRegister`` to be tested
+                for equality with a given ``int``, or as a tuple of a ``Clbit`` to
+                be compared to either a ``bool`` or an ``int``.
+            body: The loop body to be repeatedly executed.
+            label: An optional label for identifying the instruction.
+        """
         num_qubits = body.num_qubits
         num_clbits = body.num_clbits
 

qiskit/circuit/controlledgate.py

@@ -111,9 +111,9 @@ class ControlledGate(Gate):
     @property
     def definition(self) -> QuantumCircuit:
         """Return definition in terms of other basic gates. If the gate has
-        open controls, as determined from `self.ctrl_state`, the returned
+        open controls, as determined from :attr:`ctrl_state`, the returned
         definition is conjugated with X without changing the internal
-        `_definition`.
+        ``_definition``.
         """
         if self._open_ctrl:
             closed_gate = self.to_mutable()

qiskit/circuit/delay.py

@@ -17,14 +17,20 @@ import numpy as np
 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
 
 
+@_utils.with_gate_array(np.eye(2, dtype=complex))
 class Delay(Instruction):
     """Do nothing and just delay/wait/idle for a specified duration."""
 
     def __init__(self, duration, unit="dt"):
-        """Create new delay instruction."""
+        """
+        Args:
+            duration: the length of time of the duration.  Given in units of ``unit``.
+            unit: the unit of the duration.  Must be ``"dt"`` or an SI-prefixed seconds unit.
+        """
         if unit not in {"s", "ms", "us", "ns", "ps", "dt"}:
             raise CircuitError("Unknown unit %s is specified." % unit)
 
@@ -49,10 +55,6 @@ class Delay(Instruction):
         """Set the duration of this delay."""
         self.params = [duration]
 
-    def __array__(self, dtype=None):
-        """Return the identity matrix."""
-        return np.array([[1, 0], [0, 1]], dtype=dtype)
-
     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.

qiskit/circuit/gate.py

@@ -18,7 +18,7 @@ import numpy as np
 
 from qiskit.circuit.parameterexpression import ParameterExpression
 from qiskit.circuit.exceptions import CircuitError
-from .annotated_operation import AnnotatedOperation, ControlModifier
+from .annotated_operation import AnnotatedOperation, ControlModifier, PowerModifier
 from .instruction import Instruction
 
 
@@ -62,23 +62,36 @@ class Gate(Instruction):
             return self.__array__(dtype=complex)
         raise CircuitError(f"to_matrix not defined for this {type(self)}")
 
-    def power(self, exponent: float):
-        """Creates a unitary gate as `gate^exponent`.
+    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): Gate^exponent
+            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:
-            .library.UnitaryGate: To which `to_matrix` is self.to_matrix^exponent.
+            An operation implementing ``gate^exponent``
 
         Raises:
-            CircuitError: If Gate is not unitary
+            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
 
-        return UnitaryGate(Operator(self).power(exponent), label=f"{self.name}^{exponent}")
+        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)

qiskit/circuit/instruction.py

@@ -41,7 +41,6 @@ from typing import List, Type
 import numpy
 
 from qiskit.circuit.exceptions import CircuitError
-from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.circuit.classicalregister import ClassicalRegister, Clbit
 from qiskit.qobj.qasm_qobj import QasmQobjInstruction
 from qiskit.circuit.parameter import ParameterExpression
@@ -241,8 +240,8 @@ class Instruction(Operation):
         """
         if (
             self.name != other.name
-            or other.num_qubits != other.num_qubits
-            or other.num_clbits != other.num_clbits
+            or self.num_qubits != other.num_qubits
+            or self.num_clbits != other.num_clbits
             or len(self.params) != len(other.params)
         ):
             return False
@@ -269,12 +268,17 @@ class Instruction(Operation):
         return True
 
     def _define(self):
-        """Populates self.definition with a decomposition of this gate."""
+        """Populate the cached :attr:`_definition` field of this :class:`Instruction`.
+
+        Subclasses should implement this method to provide lazy construction of their public
+        :attr:`definition` attribute.  A subclass can use its :attr:`params` at the time of the
+        call.  The method should populate :attr:`_definition` with a :class:`.QuantumCircuit` and
+        not return a value."""
         pass
 
     @property
     def params(self):
-        """return instruction params."""
+        """The parameters of this :class:`Instruction`.  Ideally these will be gate angles."""
         return self._params
 
     @params.setter
@@ -291,7 +295,8 @@ class Instruction(Operation):
         return parameter
 
     def is_parameterized(self):
-        """Return True .IFF. instruction is parameterized else False"""
+        """Return whether the :class:`Instruction` contains :ref:`compile-time parameters
+        <circuit-compile-time-parameters>`."""
         return any(
             isinstance(param, ParameterExpression) and param.parameters for param in self.params
         )
@@ -520,18 +525,6 @@ class Instruction(Operation):
             cpy._definition = copy.deepcopy(self._definition, memo)
         return cpy
 
-    def _qasmif(self, string):
-        """Print an if statement if needed."""
-        from qiskit.qasm2 import QASM2ExportError  # pylint: disable=cyclic-import
-
-        if self.condition is None:
-            return string
-        if not isinstance(self.condition[0], ClassicalRegister):
-            raise QASM2ExportError(
-                "OpenQASM 2 can only condition on registers, but got '{self.condition[0]}'"
-            )
-        return "if(%s==%d) " % (self.condition[0].name, self.condition[1]) + string
-
     def broadcast_arguments(self, qargs, cargs):
         """
         Validation of the arguments.
@@ -572,7 +565,13 @@ class Instruction(Operation):
         )
 
     def repeat(self, n):
-        """Creates an instruction with `gate` repeated `n` amount of times.
+        """Creates an instruction with ``self`` repeated :math`n` times.
+
+        If this operation has a conditional, the output instruction will have the same conditional
+        and the inner repeated operations will be unconditional; instructions within a compound
+        definition cannot be conditioned on registers within Qiskit's data model.  This means that
+        it is not valid to apply a repeated instruction to a clbit that it both writes to and reads
+        from in its condition.
 
         Args:
             n (int): Number of times to repeat the instruction
@@ -589,22 +588,24 @@ class Instruction(Operation):
         n = int(n)
 
         instruction = self._return_repeat(n)
-        qargs = [] if self.num_qubits == 0 else QuantumRegister(self.num_qubits, "q")
-        cargs = [] if self.num_clbits == 0 else ClassicalRegister(self.num_clbits, "c")
-
         if instruction.definition is None:
             # pylint: disable=cyclic-import
             from qiskit.circuit import QuantumCircuit, CircuitInstruction
 
-            qc = QuantumCircuit()
-            if qargs:
-                qc.add_register(qargs)
-            if cargs:
-                qc.add_register(cargs)
-            circuit_instruction = CircuitInstruction(self, qargs, cargs)
+            qc = QuantumCircuit(self.num_qubits, self.num_clbits)
+            qargs = tuple(qc.qubits)
+            cargs = tuple(qc.clbits)
+            base = self.copy()
+            if self.condition:
+                # Condition is handled on the outer instruction.
+                base = base.to_mutable()
+                base.condition = None
             for _ in [None] * n:
-                qc._append(circuit_instruction)
-        instruction.definition = qc
+                qc._append(CircuitInstruction(base, qargs, cargs))
+
+            instruction.definition = qc
+        if self.condition:
+            instruction = instruction.c_if(*self.condition)
         return instruction
 
     @property

qiskit/circuit/instructionset.py

@@ -87,7 +87,11 @@ class InstructionSet:
         self._instructions.append((data, pos))
 
     def inverse(self, annotated: bool = False):
-        """Invert all instructions."""
+        """Invert all instructions.
+
+        .. note::
+            It is preferable to take the inverse *before* appending the gate(s) to the circuit.
+        """
         for i, instruction in enumerate(self._instructions):
             if isinstance(instruction, CircuitInstruction):
                 self._instructions[i] = instruction.replace(
@@ -105,6 +109,10 @@ class InstructionSet:
         """Set a classical equality condition on all the instructions in this set between the
         :obj:`.ClassicalRegister` or :obj:`.Clbit` ``classical`` and value ``val``.
 
+        .. note::
+            You should prefer to use the :meth:`.QuantumCircuit.if_test` builder interface, rather
+            than using this method.
+
         .. note::
 
             This is a setter method, not an additive one.  Calling this multiple times will silently
@@ -124,27 +132,6 @@ class InstructionSet:
         Raises:
             CircuitError: if the passed classical resource is invalid, or otherwise not resolvable
                 to a concrete resource that these instructions are permitted to access.
-
-        Example:
-            .. plot::
-               :include-source:
-
-               from qiskit import ClassicalRegister, QuantumRegister, QuantumCircuit
-
-               qr = QuantumRegister(2)
-               cr = ClassicalRegister(2)
-               qc = QuantumCircuit(qr, cr)
-               qc.h(range(2))
-               qc.measure(range(2), range(2))
-
-               # apply x gate if the classical register has the value 2 (10 in binary)
-               qc.x(0).c_if(cr, 2)
-
-               # apply y gate if bit 0 is set to 1
-               qc.y(1).c_if(0, 1)
-
-               qc.draw('mpl')
-
         """
         if self._requester is None and not isinstance(classical, (Clbit, ClassicalRegister)):
             raise CircuitError(

qiskit/circuit/library/__init__.py

@@ -129,29 +129,19 @@ For example:
 Standard Directives
 ===================
 
-..
-    This summary table deliberately does not generate toctree entries; these directives are "owned"
-    by ``qiskit.circuit``.
-
 Directives are operations to the quantum stack that are meant to be interpreted by the backend or
 the transpiler. In general, the transpiler or backend might optionally ignore them if there is no
 implementation for them.
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   Barrier
+* :class:`qiskit.circuit.Barrier`
 
 Standard Operations
 ===================
 
 Operations are non-reversible changes in the quantum state of the circuit.
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   Measure
-   Reset
+* :class:`qiskit.circuit.Measure`
+* :class:`qiskit.circuit.Reset`
 
 Generalized Gates
 =================

qiskit/circuit/library/arithmetic/integer_comparator.py

@@ -14,7 +14,7 @@
 """Integer Comparator."""
 
 from __future__ import annotations
-import numpy as np
+import math
 
 from qiskit.circuit import QuantumCircuit, QuantumRegister, AncillaRegister
 from qiskit.circuit.exceptions import CircuitError
@@ -140,7 +140,7 @@ class IntegerComparator(BlueprintCircuit):
         Returns:
              The 2's complement of ``self.value``.
         """
-        twos_complement = pow(2, self.num_state_qubits) - int(np.ceil(self.value))
+        twos_complement = pow(2, self.num_state_qubits) - math.ceil(self.value)
         twos_complement = f"{twos_complement:b}".rjust(self.num_state_qubits, "0")
         twos_complement = [
             1 if twos_complement[i] == "1" else 0 for i in reversed(range(len(twos_complement)))

qiskit/circuit/library/arithmetic/quadratic_form.py

@@ -13,6 +13,7 @@
 """A circuit implementing a quadratic form on binary variables."""
 
 from typing import Union, Optional, List
+import math
 
 import numpy as np
 
@@ -190,8 +191,8 @@ class QuadraticForm(QuantumCircuit):
 
         # the minimum number of qubits is the number of qubits needed to represent
         # the minimum/maximum value plus one sign qubit
-        num_qubits_for_min = int(np.ceil(np.log2(max(-bounds[0], 1))))
-        num_qubits_for_max = int(np.ceil(np.log2(bounds[1] + 1)))
+        num_qubits_for_min = math.ceil(math.log2(max(-bounds[0], 1)))
+        num_qubits_for_max = math.ceil(math.log2(bounds[1] + 1))
         num_result_qubits = 1 + max(num_qubits_for_min, num_qubits_for_max)
 
         return num_result_qubits