Pulse builder interface

[taalexander]

Summary

This PR adds a new imperative pulse builder interface based on contextvars. This enables an interface like described below.

Details and comments

Example of using the pulse builder interface:

    import math

    from qiskit import QuantumCircuit
    import qiskit.pulse as pulse
    import qiskit.pulse.pulse_lib as pulse_lib
    from qiskit.test.mock import FakeOpenPulse2Q

    backend = FakeOpenPulse2Q()

    with pulse.build(backend) as pulse_prog:
        # Create a pulse.
        gaussian_pulse = pulse_lib.gaussian(10, 1.0, 2)
        # Get the qubit's corresponding drive channel from the backend.
        d0 = pulse.drive_channel(0)
        d1 = pulse.drive_channel(1)
        # Play a pulse at t=0.
        pulse.play(gaussian_pulse, d0)
        # Play another pulse directly after the previous pulse at t=10.
        pulse.play(gaussian_pulse, d0)
        # The default scheduling behavior is to schedule pulses in parallel
        # across channels. For example, the statement below
        # plays the same pulse on a different channel at t=0.
        pulse.play(gaussian_pulse, d1)

        # We also provide pulse scheduling alignment contexts.
        # The default alignment context is align_left.

        # The sequential context schedules pulse instructions sequentially in time.
        # This context starts at t=10 due to earlier pulses above.
        with pulse.align_sequential():
            pulse.play(gaussian_pulse, d0)
            # Play another pulse after at t=20.
            pulse.play(gaussian_pulse, d1)

            # We can also nest contexts as each instruction is
            # contained in its local scheduling context.
            # The output of a child context is a scheduled block
            # with the internal instructions timing fixed relative to
            # one another. This is block is then called in the parent context.

            # Context starts at t=30.
            with pulse.align_left():
                # Start at t=30.
                pulse.play(gaussian_pulse, d0)
                # Start at t=30.
                pulse.play(gaussian_pulse, d1)
            # Context ends at t=40.

            # Alignment context where all pulse instructions are
            # aligned to the right, ie., as late as possible.
            with pulse.align_right():
                # Shift the phase of a pulse channel.
                pulse.shift_phase(math.pi, d1)
                # Starts at t=40.
                pulse.delay(100, d0)
                # Ends at t=140.

                # Starts at t=130.
                pulse.play(gaussian_pulse, d1)
                # Ends at t=140.

            # Acquire data for a qubit and store in a memory slot.
            pulse.acquire(100, 0, pulse.MemorySlot(0))

            # We also support a variety of macros for common operations.

            # Measure all qubits.
            pulse.measure_all()

            # Delay on some qubits.
            # This requires knowledge of which channels belong to which qubits.
            pulse.delay_qubits(100, 0, 1)

            # Call a quantum circuit. The pulse builder lazily constructs a quantum
            # circuit which is then transpiled and scheduled before inserting into
            # a pulse schedule.
            # NOTE: Quantum register indices correspond to physical qubit indices.
            qc = QuantumCircuit(2, 2)
            qc.cx(0, 1)
            pulse.call(qc)
            # Calling a small set of standard gates and decomposing to pulses is
            # also supported with more natural syntax.
            pulse.u3(0, math.pi, 0, 0)
            pulse.cx(0, 1)


            # It is also be possible to call a preexisting schedule
            tmp_sched = pulse.Schedule()
            tmp_sched += pulse.Play(gaussian_pulse, d0)
            pulse.call(tmp_sched)

            # We also support:

            # frequency instructions
            pulse.set_frequency(5.0e9, d0)

            # phase instructions
            pulse.shift_phase(0.1, d0)

            # offset contexts
            with pulse.phase_offset(math.pi, d0):
                pulse.play(gaussian_pulse, d0)

Todo:

• Contextvars are only supported in Python 3.7+, there is a backport package that should be installed.
• Flesh out the documentation for the builder interface.
• Update the tutorials to use the pulse builder interface. See here.

[lcapelluto]

Let's not merge until one other person has reviewed builder.py

[taalexander]

Thanks for the approval!

Let's not merge until one other person has reviewed builder.py

More eyes are important, but I'm also not sure we can continue to hold this up. There is a lot of follow on work we need to add and schedule. @ajavadia, could you please recommend how we proceed.

[ajavadia]

@taalexander were you going to add more documentation/release note saying it is experimental feature? otherwise i'm good to add the automerge label.

[taalexander]

@taalexander were you going to add more documentation/release note saying it is experimental feature? otherwise i'm good to add the automerge label.

I'll do this in a separate follow up PR. I'll submit that shortly after this gets merged.