Skip to content

Commit

Permalink
fix: merge master
Browse files Browse the repository at this point in the history
  • Loading branch information
@BrunoLiegiBastonLiegi
BrunoLiegiBastonLiegi committed Nov 29, 2024
2 parents ed5dd43 + bbf0ccf commit 1fc22e4
Show file tree
Hide file tree
Showing 44 changed files with 1,653 additions and 2,771 deletions.
9 changes: 4 additions & 5 deletions doc/source/api-reference/qibo.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
64 changes: 35 additions & 29 deletions doc/source/code-examples/advancedexamples.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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─

.
.
Expand Down Expand Up @@ -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::

Expand All @@ -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::

Expand All @@ -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.


Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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))

Expand All @@ -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()
)
Expand Down
28 changes: 14 additions & 14 deletions doc/source/code-examples/examples.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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?
--------------------------------------
Expand Down
88 changes: 39 additions & 49 deletions doc/source/getting-started/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Loading

0 comments on commit 1fc22e4

Please sign in to comment.