Merge pull request #1510 from qiboteam/torch_migration

Migrating Pytorch backend to Qiboml

Author: MatteoRobbiati

doc/source/api-reference/qibo.rst

@@ -2595,12 +2595,11 @@ The main calculation engine is defined in the abstract backend object
 :class:`qibo.backends.abstract.Backend`. This object defines the methods
 required by all Qibo models to perform simulation.
 
-Qibo currently provides two different calculation backends, one based on
-numpy and one based on Tensorflow. It is possible to define new backends by
-inheriting :class:`qibo.backends.abstract.Backend` and implementing
-its abstract methods.
+Qibo supports several backends (see the :ref:`Backend drivers section <backend-drivers>`),
+which can be used depending on the specific needs:
+lightweight simulation, quantum machine learning, hardware execution, etc.
 
-An additional backend is shipped as the separate library qibojit.
+Among them, the default choice is a backend provided by the qibojit library.
 This backend is supplemented by custom operators defined under which can be
 used to efficiently apply gates to state vectors or density matrices.
 

doc/source/code-examples/advancedexamples.rst

@@ -554,7 +554,9 @@ refer to the :ref:`Optimizers <Optimizers>` section of the documentation.
 Note that if the Stochastic Gradient Descent optimizer is used then the user
 has to use a backend based on tensorflow or pytorch primitives and not the default custom
 backend, as custom operators currently do not support automatic differentiation.
-To switch the backend one can do ``qibo.set_backend("tensorflow")`` or ``qibo.set_backend("pytorch")``.
+To switch the backend one can do ``qibo.set_backend(backend="qiboml", platform="tensorflow")``
+or ``qibo.set_backend(backend="qiboml", platform="pytorch")``, after ensuring the
+``qiboml`` package has been installed.
 Check the :ref:`How to use automatic differentiation? <autodiff-example>`
 section for more details.
 
@@ -800,7 +802,7 @@ using the ``pytorch`` framework.
     import torch
 
     from qibo import Circuit, gates, set_backend
-    set_backend("pytorch")
+    set_backend(backend="qiboml", platform="pytorch")
 
     # Optimization parameters
     nepochs = 1000
@@ -1501,8 +1503,10 @@ combined with the readout mitigation:
 Clifford Data Regression (CDR)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For CDR instead, you don't need to define anything additional. However, keep in mind that the input
-circuit is expected to be decomposed in the set of primitive gates :math:`RX(\frac{\pi}{2}), CNOT, X` and :math:`RZ(\theta)`.
+For CDR instead, you don't need to define anything additional.
+However, keep in mind that the input circuit is expected to be
+decomposed in the set of primitive gates
+:math:`RX(\frac{\pi}{2}), CNOT, X` and :math:`RZ(\theta)`.
 
 .. testcode::
 
@@ -1526,14 +1530,16 @@ circuit is expected to be decomposed in the set of primitive gates :math:`RX(\fr
 
    ...
 
-Again, the mitigated expected value improves over the noisy one and is also slightly better compared to ZNE.
+Again, the mitigated expected value improves over the noisy one
+and is also slightly better compared to ZNE.
 
 
 Variable Noise CDR (vnCDR)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Being a combination of ZNE and CDR, vnCDR requires you to define the noise levels as done in ZNE, and the same
-caveat about the input circuit for CDR is valid here as well.
+Being a combination of ZNE and CDR, vnCDR requires you to define
+the noise levels as done in ZNE, and the same caveat about the
+input circuit for CDR is valid here as well.
 
 .. testcode::
 
@@ -1559,8 +1565,10 @@ caveat about the input circuit for CDR is valid here as well.
 
    ...
 
-The result is similar to the one obtained by CDR. Usually, one would expect slightly better results for vnCDR,
-however, this can substantially vary depending on the circuit and the observable considered and, therefore, it is hard to tell
+The result is similar to the one obtained by CDR.
+Usually, one would expect slightly better results for vnCDR.
+However, this can substantially vary depending on the circuit
+and the observable considered and, therefore, it is hard to tell
 a priori.
 
 
@@ -1591,8 +1599,11 @@ The use of iCS is straightforward, analogous to CDR and vnCDR.
 
    ...
 
-Again, the mitigated expected value improves over the noisy one and is also slightly better compared to ZNE.
-This was just a basic example usage of the three methods, for all the details about them you should check the API-reference page :ref:`Error Mitigation <error-mitigation>`.
+Again, the mitigated expected value improves over the noisy
+one and is also slightly better compared to ZNE.
+This was just a basic example usage of the three methods,
+for all the details about them you should check the API-reference page
+:ref:`Error Mitigation <error-mitigation>`.
 
 .. _timeevol-example:
 

doc/source/code-examples/examples.rst

@@ -39,9 +39,9 @@ evaluation performance, e.g.:
 .. code-block::  python
 
     import numpy as np
-    # switch backend to "tensorflow"
+    # switch backend to "tensorflow" through the Qiboml provider
     import qibo
-    qibo.set_backend("tensorflow")
+    qibo.set_backend(backend="qiboml", platform="tensorflow")
     from qibo import Circuit, gates
 
     circuit = Circuit(2)
@@ -54,7 +54,7 @@ evaluation performance, e.g.:
         init_state = np.ones(4) / 2.0 + i
         circuit(init_state)
 
-Note that compiling is only supported when the native ``tensorflow`` backend is
+Note that compiling is only supported when the ``tensorflow`` backend is
 used. This backend is much slower than ``qibojit`` which uses custom operators
 to apply gates.
 
@@ -226,7 +226,7 @@ For applications that require the state vector to be collapsed during measuremen
 we refer to the :ref:`How to collapse state during measurements? <collapse-examples>`
 
 The measured shots are obtained using pseudo-random number generators of the
-underlying backend (numpy or Tensorflow). If the user has installed a custom
+underlying backend. If the user has installed a custom
 backend (eg. qibojit) and asks for frequencies with more than 100000 shots,
 a custom Metropolis algorithm will be used to obtain the corresponding samples,
 for increase performance. The user can change the threshold for which this

doc/source/getting-started/installation.rst

@@ -7,15 +7,15 @@ Operating systems support
 In the table below we summarize the status of *pre-compiled binaries
 distributed with pypi* for the packages listed above.
 
-+------------------+------+---------+------------+
-| Operating System | qibo | qibojit | tensorflow |
-+==================+======+=========+============+
-| Linux x86        | Yes  | Yes     | Yes        |
-+------------------+------+---------+------------+
-| MacOS >= 10.15   | Yes  | Yes     | Yes        |
-+------------------+------+---------+------------+
-| Windows          | Yes  | Yes     | Yes        |
-+------------------+------+---------+------------+
++------------------+------+---------+-----------+---------+
+| Operating System | qibo | qibojit |Tensorflow | Pytorch |
++==================+======+=========+===========+=========+
+| Linux x86        | Yes  | Yes     | Yes       | Yes     |
++------------------+------+---------+-----------+---------+
+| MacOS >= 10.15   | Yes  | Yes     | Yes       | Yes     |
++------------------+------+---------+-----------+---------+
+| Windows          | Yes  | Yes     | Yes       | Yes     |
++------------------+------+---------+-----------+---------+
 
 .. note::
       All packages are supported for Python >= 3.9.
@@ -148,35 +148,6 @@ Then proceed with the ``qibojit`` installation using ``pip``
 
 _______________________
 
-.. _installing-tensorflow:
-
-tensorflow
-^^^^^^^^^^
-
-If the `TensorFlow <https://www.tensorflow.org>`_ package is installed Qibo
-will detect and provide to the user the possibility to use ``tensorflow``
-backend.
-
-This backend is used by default if ``qibojit`` is not installed, however, if
-needed, in order to switch to the ``tensorflow`` backend please do:
-
-.. code-block::  python
-
-      import qibo
-      qibo.set_backend("tensorflow")
-
-In order to install the package, we recommend the installation using:
-
-.. code-block:: bash
-
-      pip install qibo tensorflow
-
-.. note::
-      TensorFlow can be installed following its `documentation
-      <https://www.tensorflow.org/install>`_.
-
-_______________________
-
 .. _installing-numpy:
 
 numpy
@@ -197,26 +168,45 @@ please do:
 _______________________
 
 
-.. _installing-pytorch:
+.. _installing-qml-backends:
 
-pytorch
-^^^^^^^
+Backends with automatic differentiation support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need automatic differentiation support, for tracing gradients of your
+quantum algorithm or for building some quantum machine learning routine,
+the right backends for you are those provided by the `Qiboml <https://github.com/qiboteam/qiboml>`__
+package.
 
-If the `PyTorch <https://pytorch.org/>`_ package is installed Qibo
-will detect and provide to the user the possibility to use ``pytorch``
-backend.
+In particular, Qiboml currently support `Pytorch <https://pytorch.org/>`_ and
+`Tensorflow <https://www.tensorflow.org>`_ interfaces, integrating the qibo functionalities
+into these well-known machine learning frameworks. Quantum layers can be constructed
+and added to your Pytorch or Tensorflow models, and trained using any supported
+optimization routine.
 
-In order to switch to the ``pytorch`` backend please do:
+In order to use these quantum machine learning backends please make sure the
+preferred package is installed following `Tensorflow's <https://www.tensorflow.org/install>`_
+or `Pytorch's <https://pytorch.org/get-started/locally/>`_ installation instructions.
+
+To switch to Tensorflow or Pytorch backend please do:
 
 .. code-block::  python
 
       import qibo
-      qibo.set_backend("pytorch")
+      # in case of Tensorflow
+      qibo.set_backend(backend="qiboml", platform="tensorflow")
+      # in case of Pytorch
+      qibo.set_backend(backend="qiboml", platform="pytorch")
 
-In order to install the package, we recommend the installation using:
+In order to start using automatic differentiation tools with Qibo,
+we recommend the installation using:
 
 .. code-block:: bash
 
-      pip install qibo torch
+      pip install qibo qiboml tensorflow
 
-_______________________
+or
+
+.. code-block:: bash
+
+      pip install qibo qiboml torch