From eb3c401c702e22509e43208de39cae01de780c4c Mon Sep 17 00:00:00 2001 From: Stavros Efthymiou <35475381+stavros11@users.noreply.github.com> Date: Fri, 19 Jan 2024 22:32:02 +0400 Subject: [PATCH] Keep compiler tutorial --- doc/source/index.rst | 5 +- doc/source/main-documentation/qibolab.rst | 2 +- doc/source/tutorials/circuits.rst | 4 +- doc/source/tutorials/compiler.rst | 132 ++++++++++++++++++++++ doc/source/tutorials/index.rst | 1 + 5 files changed, 138 insertions(+), 6 deletions(-) create mode 100644 doc/source/tutorials/compiler.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 3d56ac920b..9add0a6283 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,9 +15,8 @@ circuits on quantum hardware. Qibolab includes: 1. :ref:`Platform API `: support custom allocation of quantum hardware platforms / lab setup. 2. :ref:`Drivers `: supports commercial and open-source firmware for hardware control. 3. :ref:`Arbitrary pulse API `: provide a library of custom pulses for execution through instruments. -4. :ref:`Transpiler `: compiles quantum circuits into pulse sequences matching chip topology. -5. :ref:`Quantum Circuit Deployment `: seamlessly deploys quantum circuit models on - quantum hardware. +4. :ref:`Compiler `: compiles quantum circuits into pulse sequences. +5. :ref:`Quantum Circuit Deployment `: seamlessly deploys quantum circuit models on quantum hardware. Components ---------- diff --git a/doc/source/main-documentation/qibolab.rst b/doc/source/main-documentation/qibolab.rst index ad2c467d1b..e7e772b37a 100644 --- a/doc/source/main-documentation/qibolab.rst +++ b/doc/source/main-documentation/qibolab.rst @@ -647,7 +647,7 @@ The shape of the values of an integreted acquisition with 2 sweepers will be: ) shape = (options.nshots, len(sweeper1.values), len(sweeper2.values)) -.. _main_doc_transpiler: +.. _main_doc_compiler: Transpiler and Compiler ----------------------- diff --git a/doc/source/tutorials/circuits.rst b/doc/source/tutorials/circuits.rst index 243ffd7a3f..bdc718e007 100644 --- a/doc/source/tutorials/circuits.rst +++ b/doc/source/tutorials/circuits.rst @@ -128,5 +128,5 @@ Returns the following plot: :class: only-dark .. note:: - Executing circuits using the Qibolab backend results to automatic application of the transpilation and compilation pipelines (:ref:`main_doc_transpiler`) which convert the circuit to a pulse sequence that is executed by the given platform. - It is possible to modify these pipelines following the instructions in the :ref:`tutorials_transpiler` example. + Executing circuits using the Qibolab backend results to automatic application of the transpilation and compilation pipelines (:ref:`main_doc_compiler`) which convert the circuit to a pulse sequence that is executed by the given platform. + It is possible to modify these pipelines following the instructions in the :ref:`tutorials_compiler` example. diff --git a/doc/source/tutorials/compiler.rst b/doc/source/tutorials/compiler.rst new file mode 100644 index 0000000000..4151831a6f --- /dev/null +++ b/doc/source/tutorials/compiler.rst @@ -0,0 +1,132 @@ +.. _tutorials_compiler: + +How to modify the default circuit transpilation. +================================================ + +A Qibolab platform can execute pulse sequences. +As shown in :ref:`tutorials_circuits`, Qibo circuits can be executed by invoking the :class:`qibolab.backends.QibolabBackend`, which is the object integrating Qibolab to Qibo. +When a Qibo circuit is executed, the backend will automatically transpile and compile it to a pulse sequence, which will be sent to the platform for execution. +The default transpiler and compiler outlined in the :ref:`main_doc_compiler` section will be used in this process. +In this tutorial we will demonstrate how the user can modify this process for custom applications. + +The ``transpiler`` and ``compiler`` objects used when executing a circuit are attributes of :class:`qibolab.backends.QibolabBackend`. +Creating an instance of the backend provides access to these objects: + +.. testcode:: python + + from qibolab.backends import QibolabBackend + + backend = QibolabBackend(platform="dummy") + + print(type(backend.transpiler)) + print(type(backend.compiler)) + +.. testoutput:: python + :hide: + + + + +The transpiler is responsible for transforming any circuit to one that respects +the chip connectivity and native gates. The compiler then transforms this circuit +to the equivalent pulse sequence. +The user can modify the default transpilation and compilation process by changing +the ``transpiler`` and ``compiler`` attributes of the ``QibolabBackend``. + +.. testcode:: python + + from qibo import gates + from qibo.models import Circuit + from qibolab.backends import QibolabBackend + + # define circuit + circuit = Circuit(1) + circuit.add(gates.U3(0, 0.1, 0.2, 0.3)) + circuit.add(gates.M(0)) + + backend = QibolabBackend(platform="dummy") + # disable the transpiler + backend.transpiler = None + + # execute circuit + result = backend.execute_circuit(circuit, nshots=1000) + +completely disables the transpilation steps and the circuit is sent directly to the compiler. + +In this example, we executed circuits using the backend ``backend.execute_circuit`` method, +unlike the previous example (:ref:`tutorials_circuits`) where circuits were executed directly using ``circuit(nshots=1000)``. +It is possible to perform transpiler and compiler manipulation in both approaches. +When using ``circuit(nshots=1000)``, Qibo is automatically initializing a ``GlobalBackend()`` singleton that is used to execute the circuit. +Therefore the previous manipulations can be done as follows: + +.. testcode:: python + + import qibo + from qibo import gates + from qibo.models import Circuit + from qibo.backends import GlobalBackend + + # define circuit + circuit = Circuit(1) + circuit.add(gates.U3(0, 0.1, 0.2, 0.3)) + circuit.add(gates.M(0)) + + # set backend to qibolab + qibo.set_backend("qibolab", platform="dummy") + # disable the transpiler + GlobalBackend().transpiler = None + + # execute circuit + result = circuit(nshots=1000) + + +Defining custom compiler rules +============================== + +The compiler can be modified by adding new compilation rules or changing existing ones. +As explained in :ref:`main_doc_compiler` section, a rule is a function that accepts a Qibo gate and a Qibolab platform +and returns the pulse sequence implementing this gate. + +The following example shows how to modify the transpiler and compiler in order to execute a circuit containing a Pauli X gate using a single pi-pulse: + +.. testcode:: python + + from qibo import gates + from qibo.models import Circuit + from qibolab.backends import QibolabBackend + from qibolab.pulses import PulseSequence + + # define the circuit + circuit = Circuit(1) + circuit.add(gates.X(0)) + circuit.add(gates.M(0)) + + + # define a compiler rule that translates X to the pi-pulse + def x_rule(gate, platform): + """X gate applied with a single pi-pulse.""" + qubit = gate.target_qubits[0] + sequence = PulseSequence() + sequence.add(platform.create_RX_pulse(qubit, start=0)) + return sequence, {} + + + # the empty dictionary is needed because the X gate does not require any virtual Z-phases + + backend = QibolabBackend(platform="dummy") + # disable the transpiler + backend.transpiler = None + # register the new X rule in the compiler + backend.compiler[gates.X] = x_rule + + # execute the circuit + result = backend.execute_circuit(circuit, nshots=1000) + +Here we completely disabled the transpiler to avoid transforming the X gate to a different gate and we added a rule that instructs the compiler how to transform the X gate. + +The default set of compiler rules is defined in :py:mod:`qibolab.compilers.default`. + +.. note:: + If the compiler receives a circuit that contains a gate for which it has no rule, an error will be raised. + This means that the native gate set that the transpiler uses, should be compatible with the available compiler rules. + If the transpiler is disabled, a rule should be available for all gates in the original circuit. diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst index c3e11046d8..c904d19324 100644 --- a/doc/source/tutorials/index.rst +++ b/doc/source/tutorials/index.rst @@ -12,4 +12,5 @@ In this section we present code examples from basic to advanced features impleme pulses circuits calibration + compiler instrument