Merge pull request #3 from ColibrITD-SAS/dev

repo synchronization

.env.example

@@ -0,0 +1 @@
+SPHINX_GITHUB_CHANGELOG_TOKEN=...

.gitignore

@@ -0,0 +1,12 @@
+build/
+docs/html/
+out/
+*.egg-info/
+dist/
+__pycache__/
+*.pyc
+.vscode/
+.mypy_cache/
+.pytest_cache/
+.dockerenv
+.env

README.md

@@ -1,34 +1,99 @@
+![license badge](https://img.shields.io/github/license/ColibrITD-SAS/mpqp)
+![test status badge](https://img.shields.io/github/actions/workflow/status/ColibrITD-SAS/mpqp/test?label=tests)
+![doc status badge](https://img.shields.io/github/actions/workflow/status/ColibrITD-SAS/mpqp/doc?label=doc)
+![pipy deployment status badge](https://img.shields.io/github/actions/workflow/status/ColibrITD-SAS/mpqp/pipy?label=pipy)
+
+![mpqp logo](resources/logo.svg)
+
 # The MPQP library
 
+MPQP stands for Multi-Platform Quantum Programming. It is a python library we at
+Colibri felt the need for but couldn't find a solution. We are working on
+quantum algorithms, but until now, there was no good solution to study quantum
+algorithms across devices, compares the devices, etc...
+
+MPQP is thus the solution we bring to the community to tackle this problem.
+
+![mpqp examples](resources/mpqp-usage.gif)
+
+On this page, you will find:
+
+1. how to [install](#install) the library;
+2. how to [start using](#usage) it;
+3. how to [contribute](#contribute) to the development;
+4. and the current active [contributors](#contributors).
+
 ## Install
 
-### Install MPQP (and user dependencies)
+For now, we support python versions 3.9 to 3.11, and both Windows and Linux
+(specifically, if was validated on Ubuntu LTS 20.04, while Ubuntu 18.04 is not
+supported). MacOS versions will come very soon!
+
+The preferred installation method is with the `pipy` repo. In order to use this
+installation method, simply run
 
 ```
-pip install .
+pip install mpqp
+```
+
+You can also clone this repo and install from source, for instance if you need
+to modify something. In that case, we advise you to see the
+[Contribute](#contribute) section of this document.
+
+## Usage
+
+To get started with MPQP, you can create a quantum circuit with a few gates, and
+run it against the backend of your choice:
+
+```py
+from mpqp import QCircuit
+from mpqp.gates import *
+from mpqp.execution import run, IBMDevice
+circ = QCircuit([H(0), H(1), Rx(0,0), CNOT(1,2), Y(2)])
+print(circ)
+#      ┌───┐┌───────┐
+# q_0: ┤ H ├┤ Rx(0) ├─────
+#      ├───┤└───────┘
+# q_1: ┤ H ├────■─────────
+#      └───┘  ┌─┴─┐  ┌───┐
+# q_2: ───────┤ X ├──┤ Y ├
+#             └───┘  └───┘
+print(run(circ, IBMDevice.AER_SIMULATOR_STATEVECTOR))
+# Result: IBMDevice, AER_SIMULATOR_STATEVECTOR
+#
+#         State vector: [0.-0.j  0.+0.5j 0.-0.5j 0.+0.j  0.-0.j  0.+0.5j 0.-0.5j 0.+0.j ]
+#         Probabilities: [0.   0.25 0.25 0.   0.   0.25 0.25 0.  ]
+#         Number of qubits: 3
 ```
 
-### Install dev dependencies
+More details are available in our [documentation](https://mpqpdoc.colibri-quantum.com).
+
+## Contribute
+
+To contribute, once you cloned this repo, you'll need to install the development
+dependencies.
 
 ```
 pip install -r requirements-dev.txt
 ```
 
-### Install only user dependencies
+We advise you to get in touch with us on
+[our Discord server](https://discord.gg/yyukutWbzf) so we help you on any
+difficulty you may encounter along the way.
 
-```
-pip install -r requirements.txt
-```
+Two tools are useful when working on MPQP:
 
-## Documentation
+- the test suite
+- the documentation generation
 
-To generate the website documentation with sphinx
+If you need to try out some behaviors of the library during the development, you
+can install it from source using the command.
 
 ```
-sphinx-build -b html docs build
+pip install .
 ```
 
-## Tests
+### Tests
 
 To run the test suite, run the following command:
 
@@ -41,12 +106,36 @@ devs. The full suit can be run by adding the option `-l` or `--long` to the
 previous command. This should still be run regularly to validate retro
 compatibility.
 
-TODO: add doctest for doc testing and tox for multiversions testing
+<!-- 3M-TODO: add doctest for doc testing and tox for multiversions testing -->
+
+### Documentation
+
+The website documentation is generated with
+[sphinx](https://www.sphinx-doc.org/en/master/index.html). You probably don't
+need to generate it if you work on new features, but if you want to help us by
+improving the documentation, you need to know two things:
+
+- how our documentation is structured, _i.e._ most of it is in the docstrings in
+  the code. This is done on purpose to keep code and documentation close
+  together.
+- you only need to run one command to generate the documentation:
+
+```
+sphinx-build -b html docs build
+```
+
+The changelog is generated from github's versions section. For this to work, you
+need to get a github token with public repo read right and save is as an
+environment variable with the key `SPHINX_GITHUB_CHANGELOG_TOKEN`.
+Alternatively, you can create a `.env` file by duplicating the `.env.example`
+one and removing the `.example` extension, and replace in this file the ellipsis
+by your token. This said, you don't need the changelog to generate to work on
+the documentation.
 
 ## Contributors
 
-Henri de Boutray - ColibrITD
+Henri de Boutray - ColibriTD
 
-Hamza Jaffali - ColibrITD
+Hamza Jaffali - ColibriTD
 
-Muhammad Attallah - ColibrITD
+Muhammad Attallah - ColibriTD

docs/conf.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 from typing import Literal
+import dotenv
 
 # Configuration file for the Sphinx documentation builder.
 from sphinx.application import Sphinx
@@ -36,14 +37,16 @@
     "sphinx.ext.mathjax",
     "sphinx_rtd_dark_mode",
     "sphinx_copybutton",
-    "sphinx_github_changelog",
 ]
 default_dark_mode = True
 autodoc_typehints = "description"
 autodoc_type_aliases = {"Matrix": "Matrix", "AvailableDevice": "AvailableDevice"}
 simplify_optional_unions = True
 typehints_defaults = "comma"
-sphinx_github_changelog_token = "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"
+dotenv.load_dotenv()
+sphinx_github_changelog_token = os.getenv("SPHINX_GITHUB_CHANGELOG_TOKEN")
+if sphinx_github_changelog_token is not None:
+    extensions.append("sphinx_github_changelog")
 
 # The suffix of source filenames.
 source_suffix = ".rst"

docs/execution-extras.rst

@@ -15,7 +15,7 @@ for you are most likely:
 Provider specifics
 ------------------
 
-Even though most of our interfaces use abstractions such that you don't need to
+Even though most of our interfaces use abstractions such that you do not need to
 know on which provider's QPU your code is running, we need at some point to
 tackle the specifics of each providers. Most (hopefully all soon) of it is
 tackle in these modules.

docs/execution.rst

@@ -6,7 +6,7 @@ Execution
     from mpqp.execution import *
 
 Execution is the core of this library. Our goal is to allow you to run a circuit
-on any hardware without you having to rewrite your circuit in the providers's
+on any hardware without you having to rewrite your circuit in the providers'
 ``sdk``. We introduce here how execution works in ``mpqp``, both in local
 simulator and in remote QPUs.
 
@@ -22,7 +22,7 @@ it regroups methods common to all providers' devices.
 
 Then, for each supported quantum computer/simulator provider, we create a
 specific subclass enumerating all available devices. When devices are retrieved
-using a given name (a string), we use it to set the value associated to each key
+using a given name (a string), we use it to set the value associated with each key
 of the :class:`AvailableDevice<mpqp.execution.devices.AvailableDevice>`.
 Specific device's info and manipulation are handled by additional methods
 (sometimes static).
@@ -46,16 +46,16 @@ of data needed to setup the connection, summed up here:
 - Atos/Eviden (Qaptiva/QLM): for this provider, several connection methods
   exist. For now we only support the username/password method. You should have
   received you username and password by email;
-- AWS (braket): for this provider, you'll need more information: all of them can
+- AWS (braket): for this provider, you will need more information: all of them can
   be found in your 
   `AWS console <https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin>`_.
   In the console go to the ``IAM service``, in the ``Users`` tab, click on your
   username, in the ``Security credential`` tab, you'll find an ``Access keys`` 
   section. In this section, you can create a new access key for MPQP, you should
   save it because you will not be able to get back your secret latter on.
-  This will give you your key and your secret, for the configuration you also
+  This will give you your key and your secret, but for the configuration you also
   need a region (for example ``us-east-1``).
-  In short, you'll need:
+  In short, one would need:
 
   + ``AWS Access Key ID``,
   + ``AWS Secret Access Key`` and

docs/getting-started.rst

@@ -36,40 +36,46 @@ Setup remote connection
 -----------------------
 
 After you installed MPQP package using ``pip install``, the script
-:mod:`setup_connections.py<mpqp.execution.connection.setup_connections>` can be called from everywhere, not only in
-``mpqp`` folder, using the following command line:
+:mod:`setup_connections.py<mpqp.execution.connection.setup_connections>` can be
+called from everywhere, not only in ``mpqp`` folder, using the following command
+line:
 
 .. code-block:: console
 
     $ setup_connections
 
-This script will allow you to configure and save your personal account to connect to remote machines.
-Depending on the provider, different credentials can be asked. Information concerning which provider is configured and
-related credentials are stored in the ``~/.mpqp`` file.
+This script will allow you to configure and save your personal account to
+connect to remote machines. Depending on the provider, different credentials can
+be asked. Information concerning which provider is configured and related
+credentials are stored in the ``~/.mpqp`` file.
 
 IBM Quantum
 ^^^^^^^^^^^
 
-Each IBM Quantum account is associated to a unique token. It is accessible by first logging in the
-`IBM Quantum Platform <https://quantum.ibm.com/>`_ and then looking for the ``API Token`` on the top right (that you can
-copy). This token is sufficient to configure your account, and to be able to submit job to remote devices. When inputting
-you token in the MPQP configuration script, this will configure the account for all your current environment, meaning
-that this account will still be configured outside of MPQP.
+Each IBM Quantum account is associated to a unique token. It is accessible by
+first logging in the `IBM Quantum Platform <https://quantum.ibm.com/>`_ and then
+looking for the ``API Token`` on the top right (that you can copy). This token
+is sufficient to configure your account, and to be able to submit jobs to remote
+devices. When inputting your token in the MPQP configuration script, this will
+configure the account for all your current environments, meaning that this
+account will still be configured outside of MPQP.
 
 QLMaaS / Qaptiva
 ^^^^^^^^^^^^^^^^
 
-QLM propose several way of setting up the account to submit jobs on their simulators. We made the choice to use the
-``username`` and ``password`` credentials to identify yourself on the QLM. When configuring the connection with
-``setup_connections`` script, we ask you the between configuring the account only in the scope of MPQP, or for your whole
-environment.
+QLM proposes several ways of setting up the account to submit jobs on their
+simulators. We made the choice to use the ``username`` and ``password``
+credentials to identify yourself on the QLM. When configuring the connection
+with ``setup_connections`` script, we ask you to choose the between configuring
+the account only in the scope of MPQP, or for your whole environment.
 
 AWS Braket
 ^^^^^^^^^^
 
-For setting up your AWS Braket account, we call the CLI ``aws configure`` that handles it for us. It will ask you your
-``AWS Access Key ID``, ``AWS Secret Access Key`` and ``Default region name``. Note that it will configure the account
-not only in MPQP scope.
+For setting up your AWS Braket account, we call the CLI ``aws configure`` that
+handles it for us. It will ask you your ``AWS Access Key ID``, ``AWS Secret
+Access Key`` and ``Default region name``. Note that it will configure the
+account not only in MPQP scope.
 
 
 Execute examples

docs/qasm.rst

@@ -20,7 +20,7 @@ From OpenQASM2.0 to OpenQASM3.0
 
 Recently, a new version of OpenQASM (3.0) has been released by conjoint members
 of IBM Quantum, AWS Quantum Computing, Zapata Computing, Zurich Instruments and
-University of Oxford. This version extends the version 2.0, adding some advanced
+University of Oxford. This version extends the 2.0 one, adding some advanced
 features, and modifying parts of syntax and grammar, making some part of
 OpenQASM2.0 not fully retro-compatible.
 
@@ -30,8 +30,8 @@ can use the function :func:`open_qasm_2_to_3` to translate a code given in
 parameter as a string. The other facultative parameters are used for recursive
 calls of the function (when having to translate included files for instance),
 but are not relevant from a user point of view, expect the parameter
-``path_to_file``, useful for locating imports. The translator also convert also
-imported files, and include the new ones in the converted code.
+``path_to_file``, useful for locating imports. The translator converts also
+imported files, and includes the new ones in the converted code.
 
 .. autofunction:: mpqp.qasm.open_qasm_2_and_3.open_qasm_2_to_3
 
@@ -102,7 +102,7 @@ combination of supported standard gates (``rx``, ``ry``, ``rz``, ``cnot``,
 ``phaseshift`` for instance). Besides, the inclusion of files is not yet handled
 by Braket library. Therefore, we temporarily created a custom file to *hard-*
 include (see :ref:`above<hard-include>`) directly in the OpenQASM 3.0 code, to
-be sure the parser and interpreter has all definitions in there. We also
+be sure the parser and interpreter have all definitions in there. We also
 hard-include all included files in the OpenQASM 3.0 code inputted for
 conversion.
 
@@ -113,7 +113,7 @@ conversion.
 
 .. autofunction:: mpqp.qasm.qasm_to_braket.qasm3_to_braket_Circuit
 
-In needed, one can also generate a Braket ``Program`` from an OpenQASM 3.0 input
+If needed, one can also generate a Braket ``Program`` from an OpenQASM 3.0 input
 string using the function below. However, in this case, the program parser does
 not need to redefine the native gates, and thus only performing a hard import of
 standard gates and other included file is sufficient. However, note that a

docs/tools.rst

@@ -2,11 +2,11 @@ Tools
 =====
 
 Some additional tools are provided with our library. Even though most of them
-are geared at internal usage, there are all presented here. Amongst them, the
+are geared at internal usage, they are all presented here. Amongst them, the
 ones most probable of being of use for you are in:
 
 - the section :ref:`viz` presents visualization tools for several data types.
-  They might be integrated in these types is they are popular enough.
+  They might be integrated in these types if they are popular enough.
 - the section :ref:`math` presents mathematical tools for linear algebra,
   functions generalized to more data types, etc...
 
@@ -52,10 +52,10 @@ relevant, we also append the trace of the error raised by a provider's SDK.
 Choice Tree
 -----------
 
-This module provides functionality for working with decision trees, allowing for
+This module provides functionalities for working with decision trees, allowing for
 seamless navigation and interaction within a tree structure.
 
-The user define a :class:`QuestionNode<mpqp.tools.choice_tree.QuestionNode>`,
+The user defines a :class:`QuestionNode<mpqp.tools.choice_tree.QuestionNode>`,
 containing a question or requesting and answer from the user. Then the user can
 select among a list of possible answers, encoded in
 :class:`AnswerNode<mpqp.tools.choice_tree.AnswerNode>`. For each answer, either