Merge branch 'docs_cleanup' into 'develop'

--------------------------

.. nothing-to-avoid-a-sphinx-warning:

    :members:

types

-------------------

-----

.. automodule:: quantify.scheduler.types

    :members:

enums

-----

.. automodule:: quantify.scheduler.enums

    :members:

gate_library

---------------

------------

.. automodule:: quantify.scheduler.gate_library

    :members:

pulse_library

---------------

-------------

.. automodule:: quantify.scheduler.pulse_library

    :members:

acquisition_library

---------------

-------------------

.. automodule:: quantify.scheduler.acquisition_library

    :members:

.. _api-resources:

resources

---------------

---------

.. automodule:: quantify.scheduler.resources

    :members:

waveforms

---------------

---------

.. automodule:: quantify.scheduler.waveforms

    :members:

.. _api-compilation:

compilation

---------------

-----------

.. automodule:: quantify.scheduler.compilation

    :members:

frontends

---------------

---------

.. automodule:: quantify.scheduler.frontends

    :members:

backends

---------------

--------

.. automodule:: quantify.scheduler.backends

    :members:

visualization

---------------

-------------

.. automodule:: quantify.scheduler.visualization

pulse_scheme

~~~~~~~~~~~~

.. automodule:: quantify.scheduler.visualization.pulse_scheme

    :members:

circuit_diagram

~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~

.. automodule:: quantify.scheduler.visualization.pulse_scheme

.. automodule:: quantify.scheduler.visualization.circuit_diagram

    :members:

    "jupyter_sphinx",

    "sphinxcontrib.blockdiag",

    "sphinx_togglebutton",

    "scanpydoc.elegant_typehints",

]

# Add any paths that contain templates here, relative to this directory.

        "https://quantify-quantify-core.readthedocs-hosted.com/en/latest/",

        None,

    ),

    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),

}

    ),

]

# avoid duplicate label warning even when manual label has been used

suppress_warnings = ["autosectionlabel.*"]

blockdiag_html_image_format = "SVG"

# At some point we might want to make no warnings imperative

autodoc_warningiserror = False

qualname_overrides = {

    "matplotlib.axes._axes.Axes": "matplotlib.axes.Axes",

}

numfig = True

.. _sec-tutorial1:

Tutorial 1. Basic experiments

================================

=============================

.. jupyter-kernel::

  :id: Tutorial 1. Basic experiment

We next show the `Chevron` experiment in which the user is required to mix gate-type and pulse-type information when defining the :class:`~quantify.scheduler.Schedule`.

Basics: The Bell experiment

-----------------------------

---------------------------

As the first example, we want to perform the `Bell experiment <https://en.wikipedia.org/wiki/Bell%27s_theorem>`_ .

The goal of the Bell experiment is to create a Bell state :math:`|\Phi ^+\rangle=\frac{1}{2}(|00\rangle+|11\rangle)` followed by a measurement.

Bell circuit

~~~~~~~~~~~~~~~~

~~~~~~~~~~~~

We create this experiment using :ref:`gates acting on qubits<Gate-level description>` .

    q0, q1 = ('q0', 'q1') # we use strings because qubit resources have not been implemented yet.

Creating the circuit

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~

We will now add some operations to the schedule.

Because this experiment is most conveniently described on the gate level, we use operations defined in the :mod:`quantify.scheduler.gate_library` .

Visualizing the circuit

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~

And we can use this to create a default visualization:

Datastructure internals

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~

Let's take a look at the internals of the :class:`~quantify.scheduler.Schedule`.

.. jupyter-execute::

    sched

We can see that the number of unique operations is 24 corresponding to 4 operations that occur in every loop and 21 unique rotations for the different theta angles. (21+4 = 25 so we are missing something.

We can see that the number of unique operations is 26 corresponding to 5 operations that occur in every loop (the measurement is considered an operation as well) and 21 unique rotations for the different theta angles.

.. jupyter-execute::

Compilation of a circuit diagram into pulses

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The compilation from the gate-level to the pulse-level description is done using the :ref:`device configuration file<Device configuration file>`.

Here we will use a configuration file for a transmon based system that is part of the quantify-scheduler test suite.

    pulse_diagram_plotly(sched, port_list=["q0:mw", "q0:res", "q0:fl", "q1:mw"], modulation_if = 10e6, sampling_rate = 1e9)

Compilation of pulses onto physical hardware

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. jupyter-execute::

    add_pulse_information_transmon(sched, device_cfg=transmon_test_config)

    determine_absolute_timing(schedule=sched)

The compilation from the pulse-level description for execution on physical hardware is done using a backend and based on the :ref:`hardware mapping file<Hardware mapping file>`.

The compilation from the pulse-level description for execution on physical hardware is done using a backend and based on the :ref:`hardware mapping file <sec-hardware-config>`.

Here we will use the :class:`~quantify.scheduler.backends.pulsar_backend.pulsar_assembler_backend` made for the Qblox pulsar series hardware.

Precise timing control: The Ramsey experiment

------------------------------------------------

---------------------------------------------

.. todo::

A hybrid experiment: The Chevron

------------------------------------------------

--------------------------------

As well as defining our schedules in terms of Gates, we can also interleave arbitrary Pulse shapes, or even define a

schedule entirely with Pulses. This can be useful for experiments involving pulse sequences not easily represented by

User guide

================================

==========

.. jupyter-kernel::

  :id: Tutorial 1. Scheduler concepts

  :id: Scheduler user guide

Introduction

----------------

------------

Quantify-scheduler is a module for writing quantum programs.

It features a unique hybrid control model allowing quantum gate- and pulse-level descriptions to be combined in a clearly defined and hardware-agnostic way.

Quantify-scheduler is designed to allow experimentalists to easily define complex experiments, and produces synchronized pulse schedules to be distributed to control hardware.

- :ref:`Schedules <sec-schedule>`: describe when an operation needs to be applied.

- :ref:`Operations <sec-operation>`: describe what needs to be done.

- :ref:`Resources <sec-resources>`: describe where an operation should be applied.

- :ref:`Compilation<sec-compilation>` between different abstraction layers and onto a hardware backend.

- :ref:`Compilation <sec-compilation>`: between different abstraction layers and onto a hardware backend.

The following table shows an overview of the different concepts and how these are represented at the gate- and pulse-level abstraction.

.. _sec-schedule:

Schedule

--------------------------------

--------

The :class:`~quantify.scheduler.Schedule` is a data structure that is at the core of the Quantify-scheduler.

The :class:`~quantify.scheduler.Schedule` contains information on *when* operations should be performed.

.. _sec-operation:

Operation

--------------------------------

---------

The :class:`~quantify.scheduler.types.Operation` object is a datastructure that describes the operation that should be performed, it also contains information on *where* it should be applied.

Gate-level description

~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~

The (quantum) gate-level description is an idealized mathematical description of the operations.

In this description operations are `quantum gates <https://en.wikipedia.org/wiki/Quantum_logic_gate>`_  that act on idealized qubits as part of a `quantum circuit <https://en.wikipedia.org/wiki/Quantum_circuit>`_.

Operations can be represented by (idealized) unitaries acting on qubits which are represented here as strings (e.g., :code:`"q0"`, :code:`"q1"`, :code:`"qubit_left"`, etc.).

Pulse-level description

~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~

The pulse-level description describes waveforms applied to a sample.

These waveforms can be used to implement the unitaries of the gate-level description, in which case there is a one-to-one correspondence, but this is not required.

The pulse-level description typically contain parameterization information, such as amplitudes, durations and so forth required to synthesize the waveform on control hardware.

The location on chip is denoted by a *port* while the frequency is set using a *clock*, both are represented as strings.

These resources are described in detail in :ref:`the next section<sec-resources>`.

A :class:`~quantify.scheduler.Schedule` containing operations can be visualized using as a pulse diagram using :func:`quantify.scheduler.visualization.circuit_diagram.pulse_diagram_plotly`.

A :class:`~quantify.scheduler.Schedule` containing operations can be visualized using as a pulse diagram using :func:`quantify.scheduler.visualization.pulse_scheme.pulse_diagram_plotly`.

An example of such a visualization is shown below:

.. _sec-resources:

Resources

--------------------------------------

---------

Resources denote where an operation should be applied.

Here we explain these concept using a simple cQED device shown in :numref:`resources_fig`.

Qubits

~~~~~~~

~~~~~~

At the gate-level description, operations are applied to (abstract) qubits.

Qubits are represented by strings corresponding to the name of a qubit (e.g., :code:`q0`, :code:`q1`, :code:`A1`, :code:`QL`, :code:`qubit_1`, etc.).

Valid qubit names are those that appear in the :ref:`device config<sec-device-config>` used for compilation.

Ports

~~~~~~~

~~~~~

For many systems, it is possible to associate a qubit with an element or location on a device that a signal can be applied to.

We call such a location on a device a port.

Associating a port with a single qubit is not required so as not to complicate matters when ports are associated with multiple qubits or with non-qubit elements such as tunable couplers.

Clocks

~~~~~~~~~~~~~~~~~

~~~~~~

Besides the physical location on a device, a pulse is typically applied at a certain frequency.

A :class:`~quantify.scheduler.resources.ClockResource` can be used to track the phase of a certain transition or simply to ensure the signal ends up at the right frequency.

.. _sec-compilation:

Compilation

-------------

-----------

Different compilation steps are required to go from a high-level description of a schedule to something that can be executed on hardware.

The scheduler supports two main compilation steps, the first from the gate to the pulse level, and a second from the pulse-level to a hardware backend.

.. _sec-device-config:

Device configuration file

~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~

The device configuration file is used to compile from the  gate-level to the device specific pulse-level description.

The main responsibility is to add a pulse-representation to every operation that has a gate-level description.

Example device configuration file

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Here we show an example of such a device configuration file:

.. jupyter-execute::

.. _sec-hardware-config:

Hardware configuration file

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~~~

The hardware configuration file is used to compile pulses to specific control electronics.

To do this, it contains information on what ports are connected to what hardware outputs/inputs, as well as other hardware-specific settings.

Here we show an example of such a device configuration file:

Example Qblox hardware configuration file

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. jupyter-execute::

  :hide-code: