Prepare 0.12.0 release (#3798)

* Prepare for 0.12.0 release

This commit moves the release notes into a 0.12.0 subdirectory to keep
them separate from development notes post-release. It also adds a
release note to add the prelude section providing the high level
overview of the release. When this merges it should be the commit used
to tag the 0.12.0 release.

* Update parametric pulse documentation

As part of updating the release notes for recent pulse changes linking
to the new parametric pulse command classes was impossible because they
were not included in the documentation. This commit corrects that
oversight and adds the new parameters to the documentation and also
updates the formatting for some of the classes.

* Update release notes for formatting and content

This commit goes through the release notes for the 0.12 release and
updates them for content and formatting. It also adds the 0.12.0 release
note with a single prelude to describe the release at a high level.

* Update more release notes

This commit continues the process of reworking and updating the release
notes. There are still a few more files to update and fix, which will
happen in a follow on commit.

* Add missing release note

Change #3773 introduced some backwards incompatible api changes but
forgot to add a release note documenting these. This commit corrects the
oversight and adds release notes for the changes in that PR.

* Final round of release note updates

This commit finishes the cleanup and fixes for the existing release
notes in the 0.12.0 release.

* Migrate and update formatting for new release note

A new release note file was merged since this PR was originally opened.
This commit moves it to the release subdir and updates the formatting so
it links to classes and the table fits in the 100 character limit on the
meta repo when we add it there.

* Move and fix another new release note

* Minor typo fix in the release notes

* Move and update last release note

* Undo accidental change in tox.ini

constraints.txt

@@ -1,2 +1 @@
-matplotlib==3.2.0rc1;python_version=='3.8'
 nbformat==4.4.0

qiskit/circuit/__init__.py

@@ -38,6 +38,7 @@
    :toctree: ../stubs/
 
    Gate
+   ControlledGate
    Measure
    Reset
    Instruction

qiskit/pulse/__init__.py

@@ -41,6 +41,7 @@
 
    Instruction
    Acquire
+   AcquireInstruction
    FrameChange
    PersistentValue
    SamplePulse
@@ -49,6 +50,13 @@
    Discriminator
    Delay
    functional_pulse
+   ParametricPulse
+   ParametricInstruction
+   Gaussian
+   GaussianSquare
+   Drag
+   ConstantPulse
+   functional_pulse
 
 Schedules
 =========
@@ -82,9 +90,10 @@
                        MeasureChannel, AcquireChannel,
                        ControlChannel, RegisterSlot, MemorySlot)
 from .cmd_def import CmdDef
-from .commands import (Instruction, Acquire, FrameChange, PersistentValue,
-                       SamplePulse, Snapshot, Kernel, Discriminator, Delay,
-                       ParametricPulse, ParametricInstruction, Gaussian,
+from .commands import (Instruction, Acquire, AcquireInstruction, FrameChange,
+                       PersistentValue, SamplePulse, Snapshot, Kernel,
+                       Discriminator, Delay, ParametricPulse,
+                       ParametricInstruction, Gaussian,
                        GaussianSquare, Drag, ConstantPulse, functional_pulse)
 from .configuration import LoConfig, LoRange
 from .exceptions import PulseError

qiskit/pulse/commands/parametric_pulses.py

@@ -127,6 +127,8 @@ class Gaussian(ParametricPulse):
     A truncated pulse envelope shaped according to the Gaussian function whose mean is centered at
     the center of the pulse (duration / 2):
 
+    .. math::
+
         f(x) = amp * exp( -(1/2) * (x - duration/2)^2 / sigma^2) )  ,  0 <= x < duration
     """
 
@@ -178,15 +180,20 @@ class GaussianSquare(ParametricPulse):
     """
     A square pulse with a Gaussian shaped risefall on either side:
 
+    .. math::
+
         risefall = (duration - width) / 2
 
-    0 <= x < risefall
+        0 <= x < risefall
+
         f(x) = amp * exp( -(1/2) * (x - risefall/2)^2 / sigma^2) )
 
-    risefall <= x < risefall + width
+        risefall <= x < risefall + width
+
         f(x) = amp
 
-    risefall + width <= x < duration
+        risefall + width <= x < duration
+
         f(x) = amp * exp( -(1/2) * (x - (risefall + width)/2)^2 / sigma^2) )
     """
 
@@ -252,10 +259,15 @@ class Drag(ParametricPulse):
     spectrum of a normal gaussian pulse near the |1>-|2> transition, reducing the chance of
     leakage to the |2> state.
 
+    .. math::
+
         f(x) = Gaussian + 1j * beta * d/dx [Gaussian]
              = Gaussian + 1j * beta * (-(x - duration/2) / sigma^2) [Gaussian]
 
     where 'Gaussian' is:
+
+    .. math::
+
         Gaussian(x, amp, sigma) = amp * exp( -(1/2) * (x - duration/2)^2 / sigma^2) )
 
     Ref:
@@ -344,6 +356,8 @@ class ConstantPulse(ParametricPulse):
     """
     A simple constant pulse, with an amplitude value and a duration:
 
+    .. math::
+
         f(x) = amp    ,  0 <= x < duration
         f(x) = 0      ,  elsewhere
     """

releasenotes/notes/0.12/0.12.0-release-d787c88f1d8815d4.yaml

@@ -0,0 +1,9 @@
+---
+prelude: >
+    The 0.12.0 release includes several new features and bug fixes. The biggest
+    changes for this release is the addition of support for parametric pulses
+    to OpenPulse. These are Pulse commands which take parameters rather than
+    sample points to describe a pulse. 0.12.0 is also the first release to
+    include support for Python 3.8. It also marks the beginning of the
+    deprecation for Python 3.5 support, which will be removed when the upstream
+    community stops supporting it.

releasenotes/notes/0.12/2482-decompose-does-not-propagate-bound-parameters-71fb409de3416255.yaml

@@ -0,0 +1,9 @@
+---
+fixes:
+  - |
+    Previously, calling :meth:`qiskit.circuit.QuantumCircuit.bind_parameters`
+    prior to decomposing a circuit would result in the bound values not being
+    correctly substituted into the decomposed gates. This has been resolved
+    such that binding and decomposition may occur in any order. Fixes
+    `issue #2482 <https://github.com/Qiskit/qiskit-terra/issues/2482>`_ and
+    `issue #3509 <https://github.com/Qiskit/qiskit-terra/issues/3509>`_

releasenotes/notes/3215-ConsolidateBlocks-drops-classical-conditional-c5ed03f9a6d15284.yaml → releasenotes/notes/0.12/3215-ConsolidateBlocks-drops-classical-conditional-c5ed03f9a6d15284.yaml

@@ -1,9 +1,10 @@
 ---
 fixes:
   - |
-    The `Collect2qBlocks` pass had previously not considered classical
+    The ``Collect2qBlocks`` pass had previously not considered classical
     conditions when determining whether to include a gate within an
     existing block. In some cases, this resulted in classical
     conditions being lost when transpiling with
-    `optimization_level=3`. This has been resolved so that classically
+    ``optimization_level=3``. This has been resolved so that classically
     conditioned gates are never included in a block.
+    Fixes `issue #3215 <https://github.com/Qiskit/qiskit-terra/issues/3215>`_

releasenotes/notes/0.12/3399-Change-QuantumCircuit-method-input-arg-names-8422b6abfdfff081.yaml

@@ -0,0 +1,99 @@
+---
+deprecations:
+  - |
+    Methods for adding gates to a :class:`qiskit.circuit.QuantumCircuit` with
+    abbreviated keyword arguments (e.g. ``ctl``, ``tgt``) have had their keyword
+    arguments renamed to be more descriptive (e.g. ``control_qubit``,
+    ``target_qubit``). The old names have been deprecated. A table including the
+    old and new calling signatures for the ``QuantumCircuit`` methods is included below.
+
+    .. list-table:: New signatures for ``QuantumCircuit`` gate methods
+       :header-rows: 1
+
+       * - Instruction Type
+         - Former Signature
+         - New Signature
+       * - :class:`qiskit.extensions.HGate`
+         - ``qc.h(q)``
+         - ``qc.h(qubit)``
+       * - :class:`qiskit.extensions.CHGate`
+         - ``qc.ch(ctl, tgt)``
+         - ``qc.ch((control_qubit, target_qubit))``
+       * - :class:`qiskit.extensions.IdGate`
+         - ``qc.iden(q)``
+         - ``qc.iden(qubit)``
+       * - :class:`qiskit.extensions.RGate`
+         - ``qc.iden(q)``
+         - ``qc.iden(qubit)``
+       * - :class:`qiskit.extensions.RGate`
+         - ``qc.r(theta, phi, q)``
+         - ``qc.r(theta, phi, qubit)``
+       * - :class:`qiskit.extensions.RXGate`
+         - ``qc.rx(theta, q)``
+         - ``qc.rx(theta, qubit)``
+       * - :class:`qiskit.extensions.CrxGate`
+         - ``qc.crx(theta, ctl, tgt)``
+         - ``qc.crx(theta, control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.RYGate`
+         - ``qc.ry(theta, q)``
+         - ``qc.ry(theta, qubit)``
+       * - :class:`qiskit.extensions.CryGate`
+         - ``qc.cry(theta, ctl, tgt)``
+         - ``qc.cry(theta, control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.RZGate`
+         - ``qc.rz(phi, q)``
+         - ``qc.rz(phi, qubit)``
+       * - :class:`qiskit.extensions.CrzGate`
+         - ``qc.crz(theta, ctl, tgt)``
+         - ``qc.crz(theta, control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.SGate`
+         - ``qc.s(q)``
+         - ``qc.s(qubit)``
+       * - :class:`qiskit.extensions.SdgGate`
+         - ``qc.sdg(q)``
+         - ``qc.sdg(qubit)``
+       * - :class:`qiskit.extensions.FredkinGate`
+         - ``qc.cswap(ctl, tgt1, tgt2)``
+         - ``qc.cswap(control_qubit, target_qubit1, target_qubit2)``
+       * - :class:`qiskit.extensions.TGate`
+         - ``qc.t(q)``
+         - ``qc.t(qubit)``
+       * - :class:`qiskit.extensions.TdgGate`
+         - ``qc.tdg(q)``
+         - ``qc.tdg(qubit)``
+       * - :class:`qiskit.extensions.U1Gate`
+         - ``qc.u1(theta, q)``
+         - ``qc.u1(theta, qubit)``
+       * - :class:`qiskit.extensions.Cu1Gate`
+         - ``qc.cu1(theta, ctl, tgt)``
+         - ``qc.cu1(theta, control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.U2Gate`
+         - ``qc.u2(phi, lam, q)``
+         - ``qc.u2(phi, lam, qubit)``
+       * - :class:`qiskit.extensions.U3Gate`
+         - ``qc.u3(theta, phi, lam, q)``
+         - ``qc.u3(theta, phi, lam, qubit)``
+       * - :class:`qiskit.extensions.Cu3Gate`
+         - ``qc.cu3(theta, phi, lam, ctl, tgt)``
+         - ``qc.cu3(theta, phi, lam, control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.XGate`
+         - ``qc.x(q)``
+         - ``qc.x(qubit)``
+       * - :class:`qiskit.extensions.CnotGate`
+         - ``qc.cx(ctl, tgt)``
+         - ``qc.cx(control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.ToffoliGate`
+         - ``qc.ccx(ctl1, ctl2, tgt)``
+         - ``qc.ccx(control_qubit1, control_qubit2, target_qubit)``
+       * - :class:`qiskit.extensions.YGate`
+         - ``qc.y(q)``
+         - ``qc.y(qubit)``
+       * - :class:`qiskit.extensions.CyGate`
+         - ``qc.cy(ctl, tgt)``
+         - ``qc.cy(control_qubit, target_qubit)``
+       * - :class:`qiskit.extensions.ZGate`
+         - ``qc.z(q)``
+         - ``qc.z(qubit)``
+       * - :class:`qiskit.extensions.CzGate`
+         - ``qc.cz(ctl, tgt)``
+         - ``qc.cz(control_qubit, target_qubit)``

releasenotes/notes/0.12/CSPLayout_limit-e0643857e866d1ee.yaml

@@ -0,0 +1,10 @@
+---
+features:
+  - |
+    The pass :class:`qiskit.transpiler.passes.CSPLayout` was extended with two
+    new parameters: ``call_limit`` and ``time_limit``. These options allow to
+    limit how long this pass will run. The option ``call_limit`` limits the
+    amount of time that the recursive function in the backtracking solver is
+    called. Similarly, ``call_limit`` limits how long (in seconds) the solver
+    will be running. The defaults are ``1000`` calls and ``10`` seconds
+    respectively.

releasenotes/notes/0.12/acquire-single-channel-ea83cef8d991f945.yaml

@@ -0,0 +1,20 @@
+---
+features:
+  - |
+    :class:`qiskit.pulse.Acquire` can now be applied to a single qubit.
+    This makes pulse programming more consistent and easier to reason
+    about, as now all operations in now apply to a single channel.
+    For example::
+
+      acquire = Acquire(duration=10)
+      schedule = Schedule()
+      schedule.insert(60, acquire(AcquireChannel(0), MemorySlot(0), RegisterSlot(0)))
+      schedule.insert(60, acquire(AcquireChannel(1), MemorySlot(1), RegisterSlot(1)))
+
+deprecations:
+  - |
+    Running :class:`qiskit.pulse.Acquire` on multiple qubits has been
+    deprecated and will be removed in a future release. Additionally, the
+    :class:`qiskit.pulse.AcquireInstruction` parameters ``mem_slots`` and
+    ``reg_slots`` have been deprecated. Instead ``reg_slot`` and ``mem_slot``
+    should be used instead.

releasenotes/notes/0.12/add-couplingmap-draw-45b8750065719e2c.yaml

@@ -0,0 +1,15 @@
+---
+features:
+  - |
+    A new method :meth:`qiskit.transpiler.CouplingMap.draw` was added to
+    :class:`qiskit.transpiler.CouplingMap` to generate a graphviz images from
+    the coupling map graph. For example:
+
+    .. jupyter-execute::
+
+        from qiskit.transpiler import CouplingMap
+
+
+        coupling_map = CouplingMap(
+            [[0, 1], [1, 0], [1, 2], [1, 3], [2, 1], [3, 1], [3, 4], [4, 3]])
+        coupling_map.draw()

releasenotes/notes/0.12/add-parametric-pulses-51184457faf31053.yaml

@@ -0,0 +1,51 @@
+---
+features:
+  - |
+    Parametric pulses have been added to OpenPulse. These are pulse commands
+    which are parameterized and understood by the backend. Arbitrary pulse
+    shapes are still supported by the SamplePulse Command. The new supported
+    pulse classes are:
+
+      - :class:`qiskit.pulse.ConstantPulse`
+      - :class:`qiskit.pulse.Drag`
+      - :class:`qiskit.pulse.Gaussian`
+      - :class:`qiskit.pulse.GaussianSquare`
+
+    They can be used like any other Pulse command. An example::
+
+        from qiskit.pulse import (Schedule, Gaussian, Drag, ConstantPulse,
+                                  GaussianSquare)
+
+        sched = Schedule(name='parametric_demo')
+        sched += Gaussian(duration=25, sigma=4, amp=0.5j)(DriveChannel(0))
+        sched += Drag(duration=25, amp=0.1, sigma=5, beta=4)(DriveChannel(1))
+        sched += ConstantPulse(duration=25, amp=0.3+0.1j)(DriveChannel(1))
+        sched += GaussianSquare(duration=1500, amp=0.2, sigma=8,
+                                width=140)(MeasureChannel(0)) << sched.duration
+
+    The resulting schedule will be similar to a SamplePulse schedule built
+    using :mod:`qiskit.pulse.pulse_lib`, however, waveform sampling will be
+    performed by the backend. The method :meth:`qiskit.pulse.Schedule.draw`
+    can still be used as usual. However, the command will be converted to a
+    ``SamplePulse`` with the
+    :meth:`qiskit.pulse.ParametricPulse.get_sample_pulse` method, so the
+    pulse shown may not sample the continuous function the same way that the
+    backend will.
+
+    This feature can be used to construct Pulse programs for any backend, but
+    the pulses will be converted to ``SamplePulse`` objects if the backend does
+    not support parametric pulses. Backends which support them will have the
+    following new attribute::
+
+        backend.configuration().parametric_pulses: List[str]
+        # e.g. ['gaussian', 'drag', 'constant']
+
+    Note that the backend does not need to support all of the parametric
+    pulses defined in Qiskit.
+
+    When the backend supports parametric pulses, and the Pulse schedule is
+    built with them, the assembled Qobj is significantly smaller. The size
+    of a PulseQobj built entirely with parametric pulses is dependent only
+    on the number of instructions, whereas the size of a PulseQobj built
+    otherwise will grow with the duration of the instructions (since every
+    sample must be specified with a value).

releasenotes/notes/add-utility-function-measure-4b951766cdfe5cd6.yaml → releasenotes/notes/0.12/add-utility-function-measure-4b951766cdfe5cd6.yaml

@@ -1,8 +1,10 @@
 ---
 features:
   - |
-    Added utility functions - ``measure`` and ``measure_all`` in scheduler module to return a
-    ``Schedule`` which measures qubits using OpenPulse. For example::
+    Added utility functions, :func:`qiskit.scheduler.measure` and
+    :func:`qiskit.scheduler.measure_all` to `qiskit.scheduler` module. These
+    functions return a :class:`qiskit.pulse.Schedule` object which measures
+    qubits using OpenPulse. For example::
 
         from qiskit.scheduler import measure, measure_all
 

releasenotes/notes/0.12/better-pulse-repr-9e5ba50649322b6b.yaml

@@ -0,0 +1,18 @@
+---
+features:
+  - |
+    Pulse :class:`qiskit.pulse.Schedule` objects now have better
+    representations that for simple schedules should be valid Python
+    expressions.
+
+    for example:
+
+    .. jupyter-execute::
+
+        from qiskit import pulse
+
+        sched = pulse.Schedule(name='test')
+        sched += pulse.SamplePulse(
+            [0., 0,], name='test_pulse')(pulse.DriveChannel(0))
+        sched += pulse.FrameChange(1.0)(pulse.DriveChannel(0))
+        print(sched)

releasenotes/notes/0.12/better_support_for_controlled_gates_in_text_drawer-b18cff47d64271ef.yaml

@@ -0,0 +1,10 @@
+---
+fixes:
+  - |
+    All the output types for the circuit drawers in
+    :meth:`qiskit.circuit.QuantumCircuit.draw` and
+    :func:`qiskit.visualization.circuit_drawer` have fixed and/or improved
+    support for drawing controlled custom gates. Fixes
+    `issue #3546 <https://github.com/Qiskit/qiskit-terra/issues/3546>`_,
+    `issue #3763 <https://github.com/Qiskit/qiskit-terra/issues/3763>`_,
+    and `issue #3764 <https://github.com/Qiskit/qiskit-terra/issues/3764>`_

releasenotes/notes/0.12/change-rep-time-unit-48533d8fe474a035.yaml

@@ -0,0 +1,12 @@
+upgrade:
+  - |
+    The value of the ``rep_time`` parameter for Pulse backend's configuration
+    object are now in units of seconds, not microseconds. The first time a
+    ``PulseBackendConfiguration`` object is initialized it will raise a single
+    warning to the user to indicate this.
+  - |
+    The ``rep_time`` argument for :func:`qiskit.compiler.assemble` now takes
+    in a value in units of seconds, not microseconds. This was done to make
+    the units with everything else in pulse. If you were passing in a value for
+    ``rep_time`` ensure that you update the value to account for this change.
+