qiskit 2.0.3__cp39-abi3-win_amd64.whl → 2.1.0__cp39-abi3-win_amd64.whl

qiskit/VERSION.txt

@@ -1 +1 @@
-2.0.3
+2.1.0

qiskit/__init__.py

@@ -44,6 +44,14 @@ else:
             " See https://qisk.it/packaging-1-0 for more detail."
         )
 
+if sys.version_info < (3, 10):
+    warnings.warn(
+        "Using Qiskit with Python 3.9 is deprecated as of the 2.1.0 release. "
+        "Support for running Qiskit with Python 3.9 will be removed in the "
+        "2.3.0 release, which coincides with when Python 3.9 goes end of life.",
+        DeprecationWarning,
+    )
+
 from . import _accelerate
 import qiskit._numpy_compat
 
@@ -52,10 +60,14 @@ import qiskit._numpy_compat
 # We manually define them on import so people can directly import qiskit._accelerate.* submodules
 # and not have to rely on attribute access.  No action needed for top-level extension packages.
 sys.modules["qiskit._accelerate.circuit"] = _accelerate.circuit
+sys.modules["qiskit._accelerate.circuit.classical"] = _accelerate.circuit.classical
+sys.modules["qiskit._accelerate.circuit.classical.expr"] = _accelerate.circuit.classical.expr
+sys.modules["qiskit._accelerate.circuit.classical.types"] = _accelerate.circuit.classical.types
 sys.modules["qiskit._accelerate.circuit_library"] = _accelerate.circuit_library
 sys.modules["qiskit._accelerate.basis_translator"] = _accelerate.basis_translator
 sys.modules["qiskit._accelerate.converters"] = _accelerate.converters
 sys.modules["qiskit._accelerate.dense_layout"] = _accelerate.dense_layout
+sys.modules["qiskit._accelerate.disjoint_utils"] = _accelerate.disjoint_utils
 sys.modules["qiskit._accelerate.equivalence"] = _accelerate.equivalence
 sys.modules["qiskit._accelerate.error_map"] = _accelerate.error_map
 sys.modules["qiskit._accelerate.gates_in_basis"] = _accelerate.gates_in_basis
@@ -64,9 +76,13 @@ sys.modules["qiskit._accelerate.uc_gate"] = _accelerate.uc_gate
 sys.modules["qiskit._accelerate.euler_one_qubit_decomposer"] = (
     _accelerate.euler_one_qubit_decomposer
 )
+sys.modules["qiskit._accelerate.optimize_1q_gates_decomposition"] = (
+    _accelerate.optimize_1q_gates_decomposition
+)
 sys.modules["qiskit._accelerate.nlayout"] = _accelerate.nlayout
 sys.modules["qiskit._accelerate.optimize_1q_gates"] = _accelerate.optimize_1q_gates
 sys.modules["qiskit._accelerate.pauli_expval"] = _accelerate.pauli_expval
+sys.modules["qiskit._accelerate.pauli_lindblad_map"] = _accelerate.pauli_lindblad_map
 sys.modules["qiskit._accelerate.qasm2"] = _accelerate.qasm2
 sys.modules["qiskit._accelerate.qasm3"] = _accelerate.qasm3
 sys.modules["qiskit._accelerate.remove_diagonal_gates_before_measure"] = (
@@ -77,7 +93,6 @@ sys.modules["qiskit._accelerate.sabre"] = _accelerate.sabre
 sys.modules["qiskit._accelerate.sampled_exp_val"] = _accelerate.sampled_exp_val
 sys.modules["qiskit._accelerate.sparse_observable"] = _accelerate.sparse_observable
 sys.modules["qiskit._accelerate.sparse_pauli_op"] = _accelerate.sparse_pauli_op
-sys.modules["qiskit._accelerate.star_prerouting"] = _accelerate.star_prerouting
 sys.modules["qiskit._accelerate.elide_permutations"] = _accelerate.elide_permutations
 sys.modules["qiskit._accelerate.target"] = _accelerate.target
 sys.modules["qiskit._accelerate.two_qubit_decompose"] = _accelerate.two_qubit_decompose
@@ -95,9 +110,11 @@ sys.modules["qiskit._accelerate.commutation_cancellation"] = _accelerate.commuta
 sys.modules["qiskit._accelerate.consolidate_blocks"] = _accelerate.consolidate_blocks
 sys.modules["qiskit._accelerate.synthesis.linear_phase"] = _accelerate.synthesis.linear_phase
 sys.modules["qiskit._accelerate.synthesis.evolution"] = _accelerate.synthesis.evolution
+sys.modules["qiskit._accelerate.synthesis.discrete_basis"] = _accelerate.synthesis.discrete_basis
 sys.modules["qiskit._accelerate.synthesis.multi_controlled"] = (
     _accelerate.synthesis.multi_controlled
 )
+sys.modules["qiskit._accelerate.synthesis.qft"] = _accelerate.synthesis.qft
 sys.modules["qiskit._accelerate.split_2q_unitaries"] = _accelerate.split_2q_unitaries
 sys.modules["qiskit._accelerate.gate_direction"] = _accelerate.gate_direction
 sys.modules["qiskit._accelerate.inverse_cancellation"] = _accelerate.inverse_cancellation
@@ -107,6 +124,7 @@ sys.modules["qiskit._accelerate.twirling"] = _accelerate.twirling
 sys.modules["qiskit._accelerate.high_level_synthesis"] = _accelerate.high_level_synthesis
 sys.modules["qiskit._accelerate.remove_identity_equiv"] = _accelerate.remove_identity_equiv
 sys.modules["qiskit._accelerate.circuit_duration"] = _accelerate.circuit_duration
+sys.modules["qiskit._accelerate.cos_sin_decomp"] = _accelerate.cos_sin_decomp
 
 from qiskit.exceptions import QiskitError, MissingOptionalLibraryError
 

qiskit/circuit/__init__.py

@@ -269,11 +269,16 @@ circuit.  The top-level ones are:
 * :class:`ControlFlowOp`, which has specific subclasses:
     * :class:`BreakLoopOp`, to break out of the nearest containing loop
     * :class:`ContinueLoopOp`, to move immediately to the next iteration of the containing loop
+    * :class:`BoxOp`, a simple grouping of instructions
     * :class:`ForLoopOp`, to loop over a fixed range of values
     * :class:`IfElseOp`, to conditionally enter one of two subcircuits
     * :class:`SwitchCaseOp`, to conditionally enter one of many subcircuits
-    * :class:`WhileLoopOp`, to repeat a subcircuit until a condition is falsified
-    * :class:`BoxOp`, to group a series of instructions for later processing
+    * :class:`WhileLoopOp`, to repeat a subcircuit until a condition is falsified.
+
+Certain instructions can be "annotated" with metadata, which is typically intended to be consumed by
+a compiler pass either locally, or in later backend processing.  Currently this is limited to
+:class:`BoxOp`.  These annotations are represented by custom subclasses of :class:`Annotation`, and
+there is further discussion of the support infrastructure in :mod:`qiskit.circuit.annotation`.
 
 :ref:`Circuits can include classical expressions that are evaluated in real time
 <circuit-repr-real-time-classical>`, while the QPU is executing a single shot of the circuit.  These
@@ -307,6 +312,7 @@ assist compilation workflows.  These include:
 There are also utilities for generating random circuits:
 
 * :func:`random.random_circuit`
+* :func:`random.random_circuit_from_graph`
 * :func:`random.random_clifford_circuit`
 
 Finally, the circuit module has its own exception class, to indicate when things went wrong in
@@ -556,12 +562,15 @@ happen incoherently and to collapse any entanglement.
 
 Hardware can be instructed to apply a real-time idle period on a given qubit.  A scheduled circuit
 (see :mod:`qiskit.transpiler`) will include all the idle times on qubits explicitly in terms of this
-:class:`Delay`.
+:class:`Delay`.  :class:`.BoxOp` can also have an explicit duration attached, in its
+:attr:`.BoxOp.duration` field.
 
 .. autoclass:: Delay
     :show-inheritance:
-.. autoclass:: Duration
 
+Delay durations can be specified either with concrete, constant times, or with delayed-resolution
+"duration expressions" built out of :class:`.expr.Stretch` objects.  See :ref:`circuit-stretches`
+for more on this.
 
 The :class:`Barrier` instruction can span an arbitrary number of qubits and clbits, and is a no-op
 in hardware.  During transpilation and optimization, however, it blocks any optimizations from
@@ -711,9 +720,9 @@ classes associated to each name.
 .. autofunction:: get_control_flow_name_mapping
 
 These control-flow operations (:class:`IfElseOp`, :class:`WhileLoopOp`,
-:class:`SwitchCaseOp`, :class:`ForLoopOp` and :class:`BoxOp`) all have specific state that defines
-the branching conditions and strategies, but contain all the different subcircuit blocks that
-might be entered in their :attr:`~ControlFlowOp.blocks` property.
+:class:`SwitchCaseOp`, :class:`ForLoopOp` and :class:`.BoxOp`) all have specific state that defines
+the branching conditions and strategies, but contain all the different subcircuit blocks that might
+be entered in their :attr:`~ControlFlowOp.blocks` property.
 
 .. autosummary::
     :toctree: ../stubs/
@@ -796,6 +805,28 @@ automatically.
 Consult :ref:`the control-flow construction documentation <circuit-control-flow-methods>` for more
 information on how to build circuits with control flow.
 
+
+Instruction-local annotations
+-----------------------------
+
+.. seealso::
+
+    :mod:`qiskit.circuit.annotation`
+        The module-level discussion of the annotation framework, including how to defined custom
+        annotations, and how the system interacts with the compiler and with serialization to other
+        formats.
+
+
+Certain circuit instructions can be "annotated" with instruction-local annotations.  As of Qiskit
+2.1.0, this is limited to :class:`.BoxOp`.  All annotations are subclasses of one base
+interface-defining object, but typically represent entirely custom analyses and commands.
+
+.. autosummary::
+    :toctree: ../stubs
+
+    Annotation
+
+
 Investigating commutation relations
 -----------------------------------
 
@@ -820,6 +851,70 @@ are available in the :class:`CommutationChecker`.
    CommutationChecker
 
 
+.. _circuit-stretches:
+
+Delayed-resolution scheduling
+-----------------------------
+
+Typically, the output of Qiskit's compiler cannot be directly executed on a QPU.  First, it is
+likely to pass through some vendor-specific pulse-level compiler, which converts the gates and
+measurements into signals to the controlling electronics of the QPU.  While Qiskit's
+:class:`.Target` can represent *some* of the timing constraints that these pulses will have, it is
+generally not entirely complete.  This is especially true when dynamic circuits (feed-forward
+operations) are involved; the delays induced by the classical components are often dependent on
+low-level post-optimization details of backend compilers, and cannot be known by Qiskit.
+
+In these situations, a user can still exert control over the relative scheduling of pulses, such as
+for dynamical decoupling, by using "stretch" durations.  These are constructed by
+:meth:`.QuantumCircuit.add_stretch`, and interact with the classical-expression system described in
+:mod:`qiskit.circuit.classical`, although they are not real-time mutable.
+
+For example, we can add stretches and boxes to set up a system where two separate dynamic-decoupling
+sequences are applied to the same qubit, while a pair of other qubits undergoes a delay of unknown
+duration.  The two sequences are constrained to have the same length, even though internally the
+concrete DD pulses have differing lengths.
+
+.. code-block:: python
+
+    from qiskit import QuantumCircuit
+    from qiskit.circuit.classical import expr
+
+    qc = QuantumCircuit(3, 3)
+    # This sets up three duration "degrees of freedom" that will
+    # be resolved later by a backend compiler.
+    a = qc.add_stretch("a")
+    b = qc.add_stretch("b")
+    c = qc.add_stretch("c")
+
+    # This set of operations involves feed-forward operations that
+    # Qiskit cannot know the length of.
+    with qc.box():
+        qc.h(1)
+        qc.cx(1, 2)
+        qc.measure([1, 2], [1, 2])
+        with qc.if_test(expr.equal(qc.clbits[1], qc.clbits[2])):
+            qc.h(1)
+
+    # While that stuff is happening to qubits (1, 2), we want
+    # qubit 0 to do two different DD sequences.  The two DD
+    # sequences are fixed to be the same length as each other,
+    # even though they're both internally stretchy.
+    with qc.box(duration=a):
+        # Textbook NMRish XX DD.
+        qc.delay(b, 0)
+        qc.x(0)
+        qc.delay(expr.mul(2, b), 0)
+        qc.x(0)
+        qc.delay(b, 0)
+    with qc.box(duration=a):
+        # XY4-like DD.
+        for _ in range(2):
+            qc.delay(c, 0)
+            qc.y(0)
+            qc.delay(expr.mul(2, c), 0)
+            qc.x(0)
+            qc.delay(c, 0)
+
 .. _circuit-custom-gates:
 
 Creating custom instructions
@@ -1053,19 +1148,6 @@ default instances of the :class:`.BasisTranslator`.
     :data:`StandardEquivalenceLibrary`.
 
 
-
-Generating random circuits
---------------------------
-
-..
-    If we expand these capabilities in the future, it's probably best to move it to its own
-    module-level documentation page than to expand this "inline" module documentation.
-
-.. currentmodule:: qiskit.circuit.random
-.. autofunction:: random_circuit
-.. autofunction:: random_clifford_circuit
-.. currentmodule:: qiskit.circuit
-
 Apply Pauli twirling to a circuit
 ---------------------------------
 
@@ -1306,6 +1388,8 @@ from .quantumcircuit import QuantumCircuit
 from .gate import Gate
 
 # pylint: disable=cyclic-import
+from . import annotation
+from .annotation import Annotation
 from .controlledgate import ControlledGate
 from . import singleton
 from .instruction import Instruction

qiskit/circuit/_add_control.py

@@ -24,21 +24,47 @@ from . import ControlledGate, Gate, QuantumRegister, QuantumCircuit
 from ._utils import _ctrl_state_to_int
 
 
+# The list of gates whose controlled versions have efficient synthesis algorithms.
+# For example, a controlled version of X is MCX (with many synthesis algorithms avalable),
+# and a controlled version of Z is MCX + two Hadamard gates.
+#
+# Note: when adding a new gate to this list, also add the decomposition of its controlled
+# version to apply_basic_controlled_gate.
+EFFICIENTLY_CONTROLLED_GATES = [
+    "p",
+    "u",
+    "x",
+    "z",
+    "y",
+    "h",
+    "sx",
+    "sxdg",
+    "rx",
+    "ry",
+    "rz",
+    "cx",
+    "cz",
+]
+
+
 def add_control(
     operation: Gate | ControlledGate,
     num_ctrl_qubits: int,
     label: str | None,
     ctrl_state: str | int | None,
 ) -> ControlledGate:
-    """For standard gates, if the controlled version already exists in the
-    library, it will be returned (e.g. XGate.control() = CnotGate().
+    """Return the controlled version of the gate.
 
-    For more generic gates, this method implements the controlled
-    version by first decomposing into the ['u1', 'u3', 'cx'] basis, then
-    controlling each gate in the decomposition.
+    This function first checks whether the gate's name corresponds to a known
+    method for generating its controlled version. Currently, these methods exist
+    for gates in ``EFFICIENTLY_CONTROLLED_GATES``.
 
-    Open controls are implemented by conjugating the control line with
-    X gates. Adds num_ctrl_qubits controls to operation.
+    For gates not in ``EFFICIENTLY_CONTROLLED_GATES``, the function calls the unroller
+    to decompose the gate into gates in ``EFFICIENTLY_CONTROLLED_GATES``,
+    and then generates the controlled version by controlling every gate in this
+    decomposition.
+
+    Open controls are implemented by conjugating the control line with X gates.
 
     This function is meant to be called from the
     :method:`qiskit.circuit.gate.Gate.control()` method.
@@ -72,11 +98,18 @@ def control(
     label: str | None = None,
     ctrl_state: str | int | None = None,
 ) -> ControlledGate:
-    """Return controlled version of gate using controlled rotations. This function
-    first checks the name of the operation to see if it knows of a method from which
-    to generate a controlled version. Currently, these are ``x``, ``rx``, ``ry``, and ``rz``.
-    If a method is not directly known, it calls the unroller to convert to `u1`, `u3`,
-    and `cx` gates.
+    """Return the controlled version of the gate.
+
+    This function first checks whether the gate's name corresponds to a known
+    method for generating its controlled version. Currently, these methods exist
+    for gates in ``EFFICIENTLY_CONTROLLED_GATES``.
+
+    For gates not in ``EFFICIENTLY_CONTROLLED_GATES``, the function calls the unroller
+    to decompose the gate into gates in ``EFFICIENTLY_CONTROLLED_GATES``,
+    and then generates the controlled version by controlling every gate in this
+    decomposition.
+
+    Open controls are implemented by conjugating the control line with X gates.
 
     Args:
         operation: The gate used to create the ControlledGate.
@@ -109,16 +142,14 @@ def control(
 
     global_phase = 0
 
-    basis = ["p", "u", "x", "z", "y", "h", "sx", "sxdg", "rx", "ry", "rz", "cx"]
-
-    if operation.name in basis:
-        apply_basic_controlled_gate(controlled_circ, operation, q_control, q_target[0])
+    if operation.name in EFFICIENTLY_CONTROLLED_GATES:
+        apply_basic_controlled_gate(controlled_circ, operation, q_control, q_target)
     else:
         if isinstance(operation, controlledgate.ControlledGate):
             operation = operation.to_mutable()
             operation.ctrl_state = None
 
-        unrolled_gate = _unroll_gate(operation, basis_gates=basis)
+        unrolled_gate = _unroll_gate(operation, basis_gates=EFFICIENTLY_CONTROLLED_GATES)
         if unrolled_gate.definition.global_phase:
             global_phase += unrolled_gate.definition.global_phase
 
@@ -139,9 +170,6 @@ def control(
 
             apply_basic_controlled_gate(controlled_circ, gate, q_control, target)
 
-            if gate.definition is not None and gate.definition.global_phase and gate.name != "rz":
-                global_phase += gate.definition.global_phase
-
     # apply controlled global phase
     if global_phase:
         if len(q_control) < 2:
@@ -185,16 +213,14 @@ def control(
 def apply_basic_controlled_gate(circuit, gate, controls, target):
     """Apply a controlled version of ``gate`` to the circuit.
 
-    This implements multi-control operations for the following basis gates:
-
-        ["p", "u", "x", "z", "y", "h", "sx", "sxdg", "rx", "ry", "rz", "cx"]
+    This implements multi-control operations for every gate in
+    ``EFFICIENTLY_CONTROLLED_GATES``.
 
     """
     num_ctrl_qubits = len(controls)
 
     if gate.name == "x":
         circuit.mcx(controls, target)
-
     elif gate.name == "rx":
         circuit.mcrx(
             gate.definition.data[0].operation.params[0],
@@ -217,7 +243,6 @@ def apply_basic_controlled_gate(circuit, gate, controls, target):
             target,
             use_basis_gates=False,
         )
-        # continue
     elif gate.name == "p":
         from qiskit.circuit.library import MCPhaseGate
 
@@ -230,6 +255,13 @@ def apply_basic_controlled_gate(circuit, gate, controls, target):
             controls[:] + [target[0]],  # CX has two targets
             target[1],
         )
+    elif gate.name == "cz":
+        circuit.h(target[1])
+        circuit.mcx(
+            controls[:] + [target[0]],  # CZ has two targets
+            target[1],
+        )
+        circuit.h(target[1])
     elif gate.name == "u":
         theta, phi, lamb = gate.params
         if num_ctrl_qubits == 1:
@@ -254,17 +286,14 @@ def apply_basic_controlled_gate(circuit, gate, controls, target):
                 circuit.mcry(theta, controls, target, use_basis_gates=False)
                 circuit.mcrz(phi, controls, target, use_basis_gates=False)
                 circuit.mcp((phi + lamb) / 2, controls[1:], controls[0])
-
     elif gate.name == "z":
         circuit.h(target)
         circuit.mcx(controls, target)
         circuit.h(target)
-
     elif gate.name == "y":
         circuit.sdg(target)
         circuit.mcx(controls, target)
         circuit.s(target)
-
     elif gate.name == "h":
         circuit.s(target)
         circuit.h(target)
@@ -273,17 +302,14 @@ def apply_basic_controlled_gate(circuit, gate, controls, target):
         circuit.tdg(target)
         circuit.h(target)
         circuit.sdg(target)
-
     elif gate.name == "sx":
         circuit.h(target)
         circuit.mcp(pi / 2, controls, target)
         circuit.h(target)
-
     elif gate.name == "sxdg":
         circuit.h(target)
         circuit.mcp(3 * pi / 2, controls, target)
         circuit.h(target)
-
     else:
         raise CircuitError(f"Gate {gate} not in supported basis.")
 

qiskit/circuit/_classical_resource_map.py

@@ -36,6 +36,10 @@ class VariableMapper(expr.ExprVisitor[expr.Expr]):
     ``ValueError`` will be raised instead.  The given ``add_register`` callable may choose to raise
     its own exception."""
 
+    # We don't want docstrings for the inherited visitor methods, which are self-explanatory and
+    # would just be noise.
+    # pylint: disable=missing-function-docstring
+
     __slots__ = ("target_cregs", "register_map", "bit_map", "var_map", "add_register")
 
     def __init__(