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

qiskit/VERSION.txt

@@ -1 +1 @@
-1.1.0
+1.1.0rc1

qiskit/assembler/__init__.py

@@ -17,18 +17,23 @@ Circuit and Schedule Assembler (:mod:`qiskit.assembler`)
 
 .. currentmodule:: qiskit.assembler
 
-Functions
-=========
-
+Circuit Assembler
+=================
 
 .. autofunction:: assemble_circuits
 
+Schedule Assembler
+==================
+
 .. autofunction:: assemble_schedules
 
+Disassembler
+============
+
 .. autofunction:: disassemble
 
-Classes
-=======
+RunConfig
+=========
 
 .. autosummary::
    :toctree: ../stubs/

qiskit/circuit/__init__.py

@@ -203,8 +203,8 @@ virtual qubit
 
 .. _circuit-module-api:
 
-API overview of qiskit.circuit
-==============================
+API overview of :mod:`qiskit.circuit`
+=====================================
 
 All objects here are described in more detail, and in their greater context in the following
 sections.  This section provides an overview of the API elements documented here.
@@ -321,6 +321,16 @@ an abstract circuit or a physical circuit.  There is much more information about
 :class:`QuantumCircuit` class itself and the multitude of available methods on it in its class
 documentation.
 
+..
+    TODO: the intention is to replace this `autosummary` directive with a proper entry in the API
+    toctree once the `QuantumCircuit` class-level documentation has been completely rewritten into
+    more of this style.  For now, this just ensures it gets *any* page generated.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    QuantumCircuit
+
 Internally, a :class:`QuantumCircuit` contains the qubits, classical bits, compile-time parameters,
 real-time variables, and other tracking information about the data it acts on and how it is
 parametrized.  It then contains a sequence of :class:`CircuitInstruction`\ s, which contain
@@ -380,7 +390,7 @@ hardware.
 Circuits track registers, but registers themselves impart almost no behavioral differences on
 circuits.  The only exception is that :class:`ClassicalRegister`\ s can be implicitly cast to
 unsigned integers for use in conditional comparisons of :ref:`control flow operations
-<circuit-control-flow-repr>`.
+<circuit-control-flow>`.
 
 Classical registers and bits were the original way of representing classical data in Qiskit, and
 remain the most supported currently.  Longer term, the data model is moving towards a more complete
@@ -423,8 +433,6 @@ methods to perform post-append mutations on instructions (which *will* be propag
 circuit), but these are now discouraged and you should use the alternatives noted in those methods.
 
 
-.. _circuit-operations-instructions:
-
 Operations, instructions and gates
 ----------------------------------
 
@@ -590,14 +598,17 @@ The :class:`Store` instruction is particularly special, in that it allows writin
 Real-time classical computation
 -------------------------------
 
-.. seealso::
-    :mod:`qiskit.circuit.classical`
-        Module-level documentation for how the variable-, expression- and type-systems work, the
-        objects used to represent them, and the classical operations available.
+.. note::
 
-    :ref:`circuit-real-time-methods`
-        The :class:`QuantumCircuit` methods for working with these variables in the context of a
-        single circuit.
+    The primary documentation for real-time classical computation is in the module-level
+    documentation of :mod:`qiskit.circuit.classical`.
+
+    You might also want to read about the circuit methods for working with real-time variables on
+    the :class:`QuantumCircuit` class page.
+
+    ..
+        TODO: write a section in the QuantumCircuit-level guide about real-time-variable methods and
+        cross-ref to it.
 
 Qiskit has rudimentary low-level support for representing real-time classical computations, which
 happen during the QPU execution and affect the results.  We are still relatively early into hardware
@@ -663,7 +674,7 @@ avoid you needing to come up with many names), you can use the convenience const
 
     ParameterVector
 
-.. _circuit-control-flow-repr:
+.. _circuit-control-flow:
 
 Control flow in circuits
 ------------------------
@@ -707,8 +718,11 @@ that affect the flow of control when within loops.  These correspond to typical
     The classes representations are documented here, but please note that manually constructing
     these classes is a low-level operation that we do not expect users to need to do frequently.
 
-    Users should read :ref:`circuit-control-flow-methods` for the recommended workflows for building
-    control-flow-enabled circuits.
+    ..
+        TODO: make this below statement valid, and reinsert.
+
+        Users should read :ref:`circuit-creating-control-flow` for the recommended workflows for
+        building control-flow-enabled circuits.
 
 Since :class:`ControlFlowOp` subclasses are also :class:`Instruction` subclasses, this means that
 the way they are stored in :class:`CircuitInstruction` instances has them "applied" to a sequence of
@@ -758,8 +772,11 @@ them to the block using :meth:`~QuantumCircuit.add_capture` (or the ``captures``
 argument), but user code will typically use the control-flow builder interface, which handles this
 automatically.
 
-Consult :ref:`the control-flow construction documentation <circuit-control-flow-methods>` for more
-information on how to build circuits with control flow.
+..
+    TODO: make the below sentence valid, then re-insert.
+
+    Consult :ref:`the control-flow construction documentation <circuit-creating-control-flow>` for
+    more information on how to build circuits with control flow.
 
 .. _circuit-custom-gates:
 
@@ -903,6 +920,122 @@ After this, for the duration of the Python interpreter session, translators like
 Working with circuit-level objects
 ==================================
 
+Circuit properties
+------------------
+
+..
+    TODO: rewrite this section and move it into the `QuantumCircuit` class-level overview of its
+    functions.
+
+When constructing quantum circuits, there are several properties that help quantify
+the "size" of the circuits, and their ability to be run on a noisy quantum device.
+Some of these, like number of qubits, are straightforward to understand, while others
+like depth and number of tensor components require a bit more explanation.  Here we will
+explain all of these properties, and, in preparation for understanding how circuits change
+when run on actual devices, highlight the conditions under which they change.
+
+Consider the following circuit:
+
+.. plot::
+   :include-source:
+
+   from qiskit import QuantumCircuit
+   qc = QuantumCircuit(12)
+   for idx in range(5):
+      qc.h(idx)
+      qc.cx(idx, idx+5)
+
+   qc.cx(1, 7)
+   qc.x(8)
+   qc.cx(1, 9)
+   qc.x(7)
+   qc.cx(1, 11)
+   qc.swap(6, 11)
+   qc.swap(6, 9)
+   qc.swap(6, 10)
+   qc.x(6)
+   qc.draw('mpl')
+
+From the plot, it is easy to see that this circuit has 12 qubits, and a collection of
+Hadamard, CNOT, X, and SWAP gates.  But how to quantify this programmatically? Because we
+can do single-qubit gates on all the qubits simultaneously, the number of qubits in this
+circuit is equal to the **width** of the circuit:
+
+.. code-block::
+
+   qc.width()
+
+.. parsed-literal::
+
+   12
+
+We can also just get the number of qubits directly:
+
+.. code-block::
+
+   qc.num_qubits
+
+.. parsed-literal::
+
+   12
+
+.. important::
+
+   For a quantum circuit composed from just qubits, the circuit width is equal
+   to the number of qubits. This is the definition used in quantum computing. However,
+   for more complicated circuits with classical registers, and classically controlled gates,
+   this equivalence breaks down. As such, from now on we will not refer to the number of
+   qubits in a quantum circuit as the width.
+
+
+It is also straightforward to get the number and type of the gates in a circuit using
+:meth:`QuantumCircuit.count_ops`:
+
+.. code-block::
+
+   qc.count_ops()
+
+.. parsed-literal::
+
+   OrderedDict([('cx', 8), ('h', 5), ('x', 3), ('swap', 3)])
+
+We can also get just the raw count of operations by computing the circuits
+:meth:`QuantumCircuit.size`:
+
+.. code-block::
+
+   qc.size()
+
+.. parsed-literal::
+
+   19
+
+A particularly important circuit property is known as the circuit **depth**.  The depth
+of a quantum circuit is a measure of how many "layers" of quantum gates, executed in
+parallel, it takes to complete the computation defined by the circuit.  Because quantum
+gates take time to implement, the depth of a circuit roughly corresponds to the amount of
+time it takes the quantum computer to execute the circuit.  Thus, the depth of a circuit
+is one important quantity used to measure if a quantum circuit can be run on a device.
+
+The depth of a quantum circuit has a mathematical definition as the longest path in a
+directed acyclic graph (DAG).  However, such a definition is a bit hard to grasp, even for
+experts.  Fortunately, the depth of a circuit can be easily understood by anyone familiar
+with playing `Tetris <https://en.wikipedia.org/wiki/Tetris>`_.  Lets see how to compute this
+graphically:
+
+.. image:: /source_images/depth.gif
+
+
+We can verify our graphical result using :meth:`QuantumCircuit.depth`:
+
+.. code-block::
+
+   qc.depth()
+
+.. parsed-literal::
+
+   9
+
 .. _circuit-abstract-to-physical:
 
 Converting abstract circuits to physical circuits

qiskit/circuit/_classical_resource_map.py

@@ -143,6 +143,3 @@ class VariableMapper(expr.ExprVisitor[expr.Expr]):
 
     def visit_cast(self, node, /):
         return expr.Cast(node.operand.accept(self), node.type, implicit=node.implicit)
-
-    def visit_index(self, node, /):
-        return expr.Index(node.target.accept(self), node.index.accept(self), node.type)

qiskit/circuit/classical/expr/__init__.py

@@ -43,7 +43,7 @@ The base for dynamic variables is the :class:`Var`, which can be either an arbit
 real-time variable, or a wrapper around a :class:`.Clbit` or :class:`.ClassicalRegister`.
 
 .. autoclass:: Var
-    :members: var, name, new
+    :members: var, name
 
 Similarly, literals used in expressions (such as integers) should be lifted to :class:`Value` nodes
 with associated types.

qiskit/circuit/classical/types/__init__.py

@@ -47,14 +47,13 @@ type, which may be slightly different to the 'classical' programming languages y
 Working with types
 ==================
 
-There are some additional functions on these types documented in the subsequent sections. 
-These are mostly expected to be used only in manipulations of the expression tree;
-users who are building expressions using the
+There are some functions on these types exposed here as well.  These are mostly expected to be used
+only in manipulations of the expression tree; users who are building expressions using the
 :ref:`user-facing construction interface <circuit-classical-expressions-expr-construction>` should
 not need to use these.
 
 Partial ordering of types
-=========================
+-------------------------
 
 The type system is equipped with a partial ordering, where :math:`a < b` is interpreted as
 ":math:`a` is a strict subtype of :math:`b`".  Note that the partial ordering is a subset of the
@@ -79,7 +78,7 @@ Some helper methods are then defined in terms of this low-level :func:`order` pr
 
 
 Casting between types
-=====================
+---------------------
 
 It is common to need to cast values of one type to another type.  The casting rules for this are
 embedded into the :mod:`types` module.  You can query the casting kinds using :func:`cast_kind`:

qiskit/circuit/classicalfunction/__init__.py

@@ -81,7 +81,6 @@ classical_function
 
 Decorator for a classical function that returns a `ClassicalFunction` object.
 
-.. autofunction:: classical_function
 
 ClassicalFunction
 -----------------

qiskit/circuit/library/__init__.py

@@ -129,19 +129,35 @@ 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.
 
-* :class:`qiskit.circuit.Barrier`
+..
+    This summary table deliberately does not generate toctree entries; these directives are "owned"
+    by ``qiskit.circuit``.
+
+.. autosummary::
+
+   Barrier
 
 Standard Operations
 ===================
 
 Operations are non-reversible changes in the quantum state of the circuit.
 
-* :class:`qiskit.circuit.Measure`
-* :class:`qiskit.circuit.Reset`
+..
+    This summary table deliberately does not generate toctree entries; these directives are "owned"
+    by ``qiskit.circuit``.
+
+.. autosummary::
+
+   Measure
+   Reset
 
 Generalized Gates
 =================