Merge branch 'master' into quantum_info_docs

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
@@ -1314,9 +1316,9 @@ Let's see how to use them. For starters, let's define a dummy circuit with some
    # visualize the circuit
    circuit.draw()
 
-   #  q0: ─RZ─RX─RZ─RX─RZ─o────o────────M─
-   #  q1: ─RZ─RX─RZ─RX─RZ─X─RZ─X─o────o─M─
-   #  q2: ─RZ─RX─RZ─RX─RZ────────X─RZ─X─M─
+   #  0: ─RZ─RX─RZ─RX─RZ─o────o────────M─
+   #  1: ─RZ─RX─RZ─RX─RZ─X─RZ─X─o────o─M─
+   #  2: ─RZ─RX─RZ─RX─RZ────────X─RZ─X─M─
 
 .. testoutput::
    :hide:
@@ -1432,12 +1434,12 @@ number of CNOT or RX pairs (depending on the value of ``insertion_gate``) insert
 circuit in correspondence to the original ones. Since we decided to simulate noisy CNOTs::
 
    Level 1
-   q0: ─X─  -->  q0: ─X───X──X─
-   q1: ─o─  -->  q1: ─o───o──o─
+   0: ─X─  -->  0: ─X───X──X─
+   1: ─o─  -->  1: ─o───o──o─
 
    Level 2
-   q0: ─X─  -->  q0: ─X───X──X───X──X─
-   q1: ─o─  -->  q1: ─o───o──o───o──o─
+   0: ─X─  -->  0: ─X───X──X───X──X─
+   1: ─o─  -->  1: ─o───o──o───o──o─
 
    .
    .
@@ -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:
 
@@ -2139,8 +2150,6 @@ Qibo implements a built-in transpiler with customizable options for each step. T
 be used at each transpiler step are reported below with a short description.
 
 The initial placement can be found with one of the following procedures:
-- Trivial: logical-physical qubit mapping is an identity.
-- Custom: custom logical-physical qubit mapping.
 - Random greedy: the best mapping is found within a set of random layouts based on a greedy policy.
 - Subgraph isomorphism: the initial mapping is the one that guarantees the execution of most gates at
 the beginning of the circuit without introducing any SWAP.
@@ -2168,22 +2177,22 @@ Multiple transpilation steps can be implemented using the :class:`qibo.transpile
 
     from qibo import gates
     from qibo.models import Circuit
-    from qibo.transpiler.pipeline import Passes, assert_transpiling
+    from qibo.transpiler.pipeline import Passes
     from qibo.transpiler.optimizer import Preprocessing
     from qibo.transpiler.router import ShortestPaths
     from qibo.transpiler.unroller import Unroller, NativeGates
     from qibo.transpiler.placer import Random
+    from qibo.transpiler.asserts import assert_transpiling
 
     # Define connectivity as nx.Graph
     def star_connectivity():
-        chip = nx.Graph()
-        chip.add_nodes_from(list(range(5)))
-        graph_list = [(i, 2) for i in range(5) if i != 2]
-        chip.add_edges_from(graph_list)
+        chip = nx.Graph([("q0", "q2"), ("q1", "q2"), ("q2", "q3"), ("q2", "q4")])
         return chip
 
     # Define the circuit
-    circuit = Circuit(2)
+    # wire_names must match nodes in the connectivity graph.
+    # The index in wire_names represents the logical qubit number in the circuit.
+    circuit = Circuit(2, wire_names=["q0", "q1"])
     circuit.add(gates.H(0))
     circuit.add(gates.CZ(0, 1))
 
@@ -2205,13 +2214,10 @@ Multiple transpilation steps can be implemented using the :class:`qibo.transpile
     transpiled_circ, final_layout = custom_pipeline(circuit)
 
     # Optinally call assert_transpiling to check that the final circuit can be executed on hardware
-    # For this test it is necessary to get the initial layout
-    initial_layout = custom_pipeline.get_initial_layout()
     assert_transpiling(
         original_circuit=circuit,
         transpiled_circuit=transpiled_circ,
         connectivity=star_connectivity(),
-        initial_layout=initial_layout,
         final_layout=final_layout,
         native_gates=NativeGates.default()
     )

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
@@ -313,20 +313,20 @@ For example
     circuit.draw()
     # Prints
     '''
-    q0: ─H─U1─U1─U1─U1───────────────────────────x───
-    q1: ───o──|──|──|──H─U1─U1─U1────────────────|─x─
-    q2: ──────o──|──|────o──|──|──H─U1─U1────────|─|─
-    q3: ─────────o──|───────o──|────o──|──H─U1───|─x─
-    q4: ────────────o──────────o───────o────o──H─x───
+    0: ─H─U1─U1─U1─U1───────────────────────────x───
+    1: ───o──|──|──|──H─U1─U1─U1────────────────|─x─
+    2: ──────o──|──|────o──|──|──H─U1─U1────────|─|─
+    3: ─────────o──|───────o──|────o──|──H─U1───|─x─
+    4: ────────────o──────────o───────o────o──H─x───
     '''
 .. testoutput::
     :hide:
 
-    q0: ─H─U1─U1─U1─U1───────────────────────────x───
-    q1: ───o──|──|──|──H─U1─U1─U1────────────────|─x─
-    q2: ──────o──|──|────o──|──|──H─U1─U1────────|─|─
-    q3: ─────────o──|───────o──|────o──|──H─U1───|─x─
-    q4: ────────────o──────────o───────o────o──H─x───
+    0: ─H─U1─U1─U1─U1───────────────────────────x───
+    1: ───o──|──|──|──H─U1─U1─U1────────────────|─x─
+    2: ──────o──|──|────o──|──|──H─U1─U1────────|─|─
+    3: ─────────o──|───────o──|────o──|──H─U1───|─x─
+    4: ────────────o──────────o───────o────o──H─x───
 
 How to visualize a circuit with style?
 --------------------------------------

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