[<img src=https://github.com/Qiskit/ecosystem/blob/main/badges/pyRiemann-qiskit.svg>](https://qiskit.org/ecosystem)
# pyRiemann-qiskit
Literature on quantum computing suggests it may offer an advantage compared with classical
computing in terms of computational time and outcomes, such as for pattern recognition or
when using limited training sets [1, 2].
A ubiquitous library on quantum computing is Qiskit [3]. Qiskit is an IBM library
distributed under Apache 2.0 which provides both quantum algorithms and backends. A
backend can be either your local machine or a remote machine, which one can emulate or be
a quantum machine. Qiskit abstraction over the type of machine you want to use, makes
designing quantum algorithms seamless.
Qiskit implements a quantum version of support vector-like classifiers, known as
quantum-enhanced support vector classifiers (QSVCs) and variational quantum classifiers
(VQCs) [4]. These classifiers likely offer an advantage over classical SVM in situations
where the classification task is complex. Task complexity is raised by the encoding of the
data into a quantum state, the number of available data, and the quality of the data. An
initial study is available in [5], and it can be downloaded from
[here](doc/Presentations/QuantumERPClassification.pdf). Although there is no study on this
topic at the time of writing, this could be an interesting research direction to
investigate BCI illiteracy.
`pyRiemann-qiskit` implements a wrapper around QSVC and VQC, to use quantum classification
with Riemannian geometry. A use case would be to use vectorized covariance matrices in the
tangent space as an input for these classifiers, enabling a possible sandbox for
researchers and engineers in the field.
`pyRiemann-qiskit` also introduces a quantum version of the famous MDM algorithm. There is
a dedicated example on quantum-MDM
[here](https://github.com/pyRiemann/pyRiemann-qiskit/blob/main/examples/ERP/classify_P300_bi_quantum_mdm.py).
The remaining of this readme details some of the quantum drawbacks and will guide you
through installation. Full documentation, including API description, is available at
<https://pyriemann-qiskit.readthedocs.io/>. The repository also includes a
[wiki](https://github.com/pyRiemann/pyRiemann-qiskit/wiki) where you can find additional
information.
## Quantum drawbacks
- Limitation of the feature dimension
The number of qubits (and therefore the feature dimension) is limited to:
- ~36 (depends on system memory size) on a local quantum simulator, and up to:
- 5000 on a remote quantum simulator;
- 7 on free real quantum computers, and up to:
- 127 on exploratory quantum computers (not available for public use).
- Time complexity
A higher number of trials or dimensions increases the time to completion of the quantum
algorithm, especially when running on a local machine. This is why the number of trials
is limited in the examples we provided. However, you should avoid such practices in your
own analysis.
Although these aspects are less important in a remote backend, it may happen that the
quantum algorithm is queued depending on the number of concurrent users.
For all these aspects, the use of `pyRiemann-qiskit` should be limited to offline
analysis only.
## References
[1] A. Blance and M. Spannowsky, ‘Quantum machine learning for particle physics using a
variational quantum classifier’, J. High Energ. Phys., vol. 2021, no. 2, p. 212, Feb.
2021, https://doi.org/10.1007/JHEP02(2021)212
[2] P. Rebentrost, M. Mohseni, and S. Lloyd, ‘Quantum Support Vector Machine for Big Data
Classification’, Phys. Rev. Lett., vol. 113, no. 13, p. 130503, Sep. 2014,
https://doi.org/10.1103/PhysRevLett.113.130503
[3] H. Abraham et al., Qiskit: An Open-source Framework for Quantum Computing. Zenodo,
2019, https://doi.org/10.5281/zenodo.2562110.
[4] V. Havlíček et al., ‘Supervised learning with quantum-enhanced feature spaces’,
Nature, vol. 567, no. 7747, pp. 209–212, Mar. 2019,
https://doi.org/10.1038/s41586-019-0980-2
[5] G. Cattan, A. Andreev, First steps to the classification of ERPs using quantum
computation, NTB Berlin 2022 - International Forum on Neural Engineering & Brain
Technologies, May 2022, Berlin, Germany, https://hal.archives-ouvertes.fr/hal-03672246/
### How to cite?
Anton Andreev, Grégoire Cattan, Sylvain Chevallier, and Quentin Barthélemy.
‘pyRiemann-qiskit: A Sandbox for Quantum Classification Experiments with Riemannian
Geometry’. Research Ideas and Outcomes 9 (20 March 2023).
https://doi.org/10.3897/rio.9.e101006.
This library is part of the [Qiskit Ecosystem](https://qiskit.org/ecosystem)
## Installation
_We recommend the use of [Anaconda](https://www.anaconda.com/) to manage python
environements._
`pyRiemann-qiskit` currently supports Windows, Mac and Linux OS with **Python 3.9 -
3.11**.
You can install `pyRiemann-qiskit` release from PyPI:
```
pip install pyriemann-qiskit
```
The development version can be installed by cloning this repository and installing the
package on your local machine using the `setup.py` script. We recommand to do it using
`pip`:
```
pip install .
```
Note that the steps above need to be re-executed in your local environment after any
changes inside your local copy of the `pyriemann_qiskit` folder, including pulling from
remote.
To check the installation, open a python shell and type:
```
import pyriemann_qiskit
```
To enable Qiskit GPU optimization (for Linux) when using quantum simulation, run:
```
pip install .[optim_linux]
```
To use symbolic quantum simulation, run:
```
pip install .[optim]
```
Which will enable [qiskit-symb](https://github.com/SimoneGasperini/qiskit-symb)
integration.
Note, Qiskit only provide binaries for Linux. For other platforms, or if you want to
enable specific NVIDIA optimization for quantum, you need to build the binary
[yourself](https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md#building-with-gpu-support).
To run a specific example on your local machine, you should install first dependencies for
the documentation:
```
pip install .[docs]
```
Then you can run the python example of your choice like:
```
python examples\ERP\classify_P300_bi.py
```
### Installation with docker
We also offer the possibility to set up the dev environment within docker. To this end, we
recommand to use `vscode` with the `Remote Containers` extension from Microsoft.
Once the installation is successful, just open the project in `vscode` and enter `F1`. In
the search bar that opens, type `Rebuild and Reopen Container`.
Wait for the container to build, and open a python shell within the container. Then ensure
everything went smoothly by typing:
```
import pyriemann_qiskit
```
Alternatively, you can from the console (Windows or Linux) build the docker image from our
Dockerfile. Go to the root folder of `pyRiemann-qiskit` and type:
```
docker build -t pyrq .
```
Next use `docker run --detach pyrq` to enter the `pyRiemann-qiskit` image.
If you wish, you can also download docker images directly from github docker registry:
https://github.com/pyRiemann/pyRiemann-qiskit/pkgs/container/pyriemann-qiskit
They are pushed to the docker registry on each release.
## Contributor Guidelines
Everyone is welcome to contribute to this repository. There are two types of
contributions:
- [Raise an issue](https://github.com/pyRiemann/pyRiemann-qiskit/issues/new) on the
repository. Issues can be either a bug report or an enhancement proposal. Note that it
is necessary to register on GitHub before. There is no special template that is expected
but, if you raise a defect please provide as many details as possible.
- [Raise a pull request](https://github.com/pyRiemann/pyRiemann-qiskit/compare). Fork the
repository and work on your own branch. Then raise a pull request with your branch
against master. As much as possible, we ask you to:
- avoid merging master into your branch. Always prefer git rebase.
- always provide full documentation of public methods.
Code contribution (pull request) can be either on core functionalities, documentation or
automation.
- The core functionalities are based on `Python`,
[pyRiemann](https://github.com/pyRiemann/pyRiemann),
[Qiskit ML](https://github.com/Qiskit/qiskit-machine-learning) and follow the best
practice from [scikit-learn](https://scikit-learn.org/stable/index.html). We use
`flake8` for code formatting. `flake8` is installed with the testing dependencies (see
below) or can be installed directly from `pip`:
```
pip install flake8
```
To execute `flake8`, just type `flake8` from the root repository, and correct all errors
related to your changes.
- The documentation is based on [Sphinx](https://www.sphinx-doc.org/en/master/).
- Automation is based on `GitHub Action` and `pytest`. It consists in two automated
workflows for running the example and the tests. To run the tests on your local machine,
you should first install the dependencies for testing:
```
pip install .[tests]
```
and then type `pytest` from the root repository. You can also specify a file like:
```
pytest tests/test_classification.py
```
Workflows are automatically triggered when you push a commit. However, the workflow for
example execution is only triggered when you modify one of the examples or the
documentation as the execution takes a lot of time. You can enable
[Github Actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
in your fork to see the result of the CI pipeline. Results are also indicated at the end
of your pull request when raised. However note, that workflows in the pull request need
approval from the maintainers before being executed.
# Troubleshooting
See our [dedicated](https://github.com/pyRiemann/pyRiemann-qiskit/wiki/Troubleshooting)
wiki page.
Raw data
{
"_id": null,
"home_page": "https://pyriemann-qiskit.readthedocs.io",
"name": "pyriemann-qiskit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Gregoire Cattan",
"author_email": "gcattan@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/b0/c5ffb875fc7e7ddca82ae4d0e4248b28439fcae3d43d6ffbcffb9ee43b74/pyriemann_qiskit-0.4.0.tar.gz",
"platform": "any",
"description": "[<img src=https://github.com/Qiskit/ecosystem/blob/main/badges/pyRiemann-qiskit.svg>](https://qiskit.org/ecosystem)\n\n# pyRiemann-qiskit\n\nLiterature on quantum computing suggests it may offer an advantage compared with classical\ncomputing in terms of computational time and outcomes, such as for pattern recognition or\nwhen using limited training sets [1, 2].\n\nA ubiquitous library on quantum computing is Qiskit [3]. Qiskit is an IBM library\ndistributed under Apache 2.0 which provides both quantum algorithms and backends. A\nbackend can be either your local machine or a remote machine, which one can emulate or be\na quantum machine. Qiskit abstraction over the type of machine you want to use, makes\ndesigning quantum algorithms seamless.\n\nQiskit implements a quantum version of support vector-like classifiers, known as\nquantum-enhanced support vector classifiers (QSVCs) and variational quantum classifiers\n(VQCs) [4]. These classifiers likely offer an advantage over classical SVM in situations\nwhere the classification task is complex. Task complexity is raised by the encoding of the\ndata into a quantum state, the number of available data, and the quality of the data. An\ninitial study is available in [5], and it can be downloaded from\n[here](doc/Presentations/QuantumERPClassification.pdf). Although there is no study on this\ntopic at the time of writing, this could be an interesting research direction to\ninvestigate BCI illiteracy.\n\n`pyRiemann-qiskit` implements a wrapper around QSVC and VQC, to use quantum classification\nwith Riemannian geometry. A use case would be to use vectorized covariance matrices in the\ntangent space as an input for these classifiers, enabling a possible sandbox for\nresearchers and engineers in the field.\n\n`pyRiemann-qiskit` also introduces a quantum version of the famous MDM algorithm. There is\na dedicated example on quantum-MDM\n[here](https://github.com/pyRiemann/pyRiemann-qiskit/blob/main/examples/ERP/classify_P300_bi_quantum_mdm.py).\n\nThe remaining of this readme details some of the quantum drawbacks and will guide you\nthrough installation. Full documentation, including API description, is available at\n<https://pyriemann-qiskit.readthedocs.io/>. The repository also includes a\n[wiki](https://github.com/pyRiemann/pyRiemann-qiskit/wiki) where you can find additional\ninformation.\n\n## Quantum drawbacks\n\n- Limitation of the feature dimension\n\n The number of qubits (and therefore the feature dimension) is limited to:\n\n - ~36 (depends on system memory size) on a local quantum simulator, and up to:\n - 5000 on a remote quantum simulator;\n - 7 on free real quantum computers, and up to:\n - 127 on exploratory quantum computers (not available for public use).\n\n- Time complexity\n\n A higher number of trials or dimensions increases the time to completion of the quantum\n algorithm, especially when running on a local machine. This is why the number of trials\n is limited in the examples we provided. However, you should avoid such practices in your\n own analysis.\n\n Although these aspects are less important in a remote backend, it may happen that the\n quantum algorithm is queued depending on the number of concurrent users.\n\n For all these aspects, the use of `pyRiemann-qiskit` should be limited to offline\n analysis only.\n\n## References\n\n[1] A. Blance and M. Spannowsky, \u2018Quantum machine learning for particle physics using a\nvariational quantum classifier\u2019, J. High Energ. Phys., vol. 2021, no. 2, p. 212, Feb.\n2021, https://doi.org/10.1007/JHEP02(2021)212\n\n[2] P. Rebentrost, M. Mohseni, and S. Lloyd, \u2018Quantum Support Vector Machine for Big Data\nClassification\u2019, Phys. Rev. Lett., vol. 113, no. 13, p. 130503, Sep. 2014,\nhttps://doi.org/10.1103/PhysRevLett.113.130503\n\n[3] H. Abraham et al., Qiskit: An Open-source Framework for Quantum Computing. Zenodo,\n2019, https://doi.org/10.5281/zenodo.2562110.\n\n[4] V. Havl\u00ed\u010dek et al., \u2018Supervised learning with quantum-enhanced feature spaces\u2019,\nNature, vol. 567, no. 7747, pp. 209\u2013212, Mar. 2019,\nhttps://doi.org/10.1038/s41586-019-0980-2\n\n[5] G. Cattan, A. Andreev, First steps to the classification of ERPs using quantum\ncomputation, NTB Berlin 2022 - International Forum on Neural Engineering & Brain\nTechnologies, May 2022, Berlin, Germany, https://hal.archives-ouvertes.fr/hal-03672246/\n\n### How to cite?\n\nAnton Andreev, Gr\u00e9goire Cattan, Sylvain Chevallier, and Quentin Barth\u00e9lemy.\n\u2018pyRiemann-qiskit: A Sandbox for Quantum Classification Experiments with Riemannian\nGeometry\u2019. Research Ideas and Outcomes 9 (20 March 2023).\nhttps://doi.org/10.3897/rio.9.e101006.\n\nThis library is part of the [Qiskit Ecosystem](https://qiskit.org/ecosystem)\n\n## Installation\n\n_We recommend the use of [Anaconda](https://www.anaconda.com/) to manage python\nenvironements._\n\n`pyRiemann-qiskit` currently supports Windows, Mac and Linux OS with **Python 3.9 -\n3.11**.\n\nYou can install `pyRiemann-qiskit` release from PyPI:\n\n```\npip install pyriemann-qiskit\n```\n\nThe development version can be installed by cloning this repository and installing the\npackage on your local machine using the `setup.py` script. We recommand to do it using\n`pip`:\n\n```\npip install .\n```\n\nNote that the steps above need to be re-executed in your local environment after any\nchanges inside your local copy of the `pyriemann_qiskit` folder, including pulling from\nremote.\n\nTo check the installation, open a python shell and type:\n\n```\nimport pyriemann_qiskit\n```\n\nTo enable Qiskit GPU optimization (for Linux) when using quantum simulation, run:\n\n```\npip install .[optim_linux]\n```\n\nTo use symbolic quantum simulation, run:\n\n```\npip install .[optim]\n```\n\nWhich will enable [qiskit-symb](https://github.com/SimoneGasperini/qiskit-symb)\nintegration.\n\nNote, Qiskit only provide binaries for Linux. For other platforms, or if you want to\nenable specific NVIDIA optimization for quantum, you need to build the binary\n[yourself](https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md#building-with-gpu-support).\n\nTo run a specific example on your local machine, you should install first dependencies for\nthe documentation:\n\n```\npip install .[docs]\n```\n\nThen you can run the python example of your choice like:\n\n```\npython examples\\ERP\\classify_P300_bi.py\n```\n\n### Installation with docker\n\nWe also offer the possibility to set up the dev environment within docker. To this end, we\nrecommand to use `vscode` with the `Remote Containers` extension from Microsoft.\n\nOnce the installation is successful, just open the project in `vscode` and enter `F1`. In\nthe search bar that opens, type `Rebuild and Reopen Container`.\n\nWait for the container to build, and open a python shell within the container. Then ensure\neverything went smoothly by typing:\n\n```\nimport pyriemann_qiskit\n```\n\nAlternatively, you can from the console (Windows or Linux) build the docker image from our\nDockerfile. Go to the root folder of `pyRiemann-qiskit` and type:\n\n```\ndocker build -t pyrq .\n```\n\nNext use `docker run --detach pyrq` to enter the `pyRiemann-qiskit` image.\n\nIf you wish, you can also download docker images directly from github docker registry:\nhttps://github.com/pyRiemann/pyRiemann-qiskit/pkgs/container/pyriemann-qiskit\n\nThey are pushed to the docker registry on each release.\n\n## Contributor Guidelines\n\nEveryone is welcome to contribute to this repository. There are two types of\ncontributions:\n\n- [Raise an issue](https://github.com/pyRiemann/pyRiemann-qiskit/issues/new) on the\n repository. Issues can be either a bug report or an enhancement proposal. Note that it\n is necessary to register on GitHub before. There is no special template that is expected\n but, if you raise a defect please provide as many details as possible.\n\n- [Raise a pull request](https://github.com/pyRiemann/pyRiemann-qiskit/compare). Fork the\n repository and work on your own branch. Then raise a pull request with your branch\n against master. As much as possible, we ask you to:\n - avoid merging master into your branch. Always prefer git rebase.\n - always provide full documentation of public methods.\n\nCode contribution (pull request) can be either on core functionalities, documentation or\nautomation.\n\n- The core functionalities are based on `Python`,\n [pyRiemann](https://github.com/pyRiemann/pyRiemann),\n [Qiskit ML](https://github.com/Qiskit/qiskit-machine-learning) and follow the best\n practice from [scikit-learn](https://scikit-learn.org/stable/index.html). We use\n `flake8` for code formatting. `flake8` is installed with the testing dependencies (see\n below) or can be installed directly from `pip`:\n\n ```\n pip install flake8\n ```\n\n To execute `flake8`, just type `flake8` from the root repository, and correct all errors\n related to your changes.\n\n- The documentation is based on [Sphinx](https://www.sphinx-doc.org/en/master/).\n- Automation is based on `GitHub Action` and `pytest`. It consists in two automated\n workflows for running the example and the tests. To run the tests on your local machine,\n you should first install the dependencies for testing:\n\n ```\n pip install .[tests]\n ```\n\n and then type `pytest` from the root repository. You can also specify a file like:\n\n ```\n pytest tests/test_classification.py\n ```\n\n Workflows are automatically triggered when you push a commit. However, the workflow for\n example execution is only triggered when you modify one of the examples or the\n documentation as the execution takes a lot of time. You can enable\n [Github Actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)\n in your fork to see the result of the CI pipeline. Results are also indicated at the end\n of your pull request when raised. However note, that workflows in the pull request need\n approval from the maintainers before being executed.\n\n# Troubleshooting\n\nSee our [dedicated](https://github.com/pyRiemann/pyRiemann-qiskit/wiki/Troubleshooting)\nwiki page.\n",
"bugtrack_url": null,
"license": "BSD (3-clause)",
"summary": "Qiskit wrapper for pyRiemann",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://pyriemann-qiskit.readthedocs.io/",
"Homepage": "https://pyriemann-qiskit.readthedocs.io",
"Source": "https://github.com/pyRiemann/pyRiemann-qiskit",
"Tracker": "https://github.com/pyRiemann/pyRiemann-qiskit/issues/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f46ba710ad327c72e6dc607ba5493c1d92369cb3c7241fc7a5e2afae55ef354c",
"md5": "946145454526a82f124c95853343ef60",
"sha256": "a5249280d07ab5842983f6e5bbc6742bc465cdd82e84e340e3c79be1ab372866"
},
"downloads": -1,
"filename": "pyriemann_qiskit-0.4.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "946145454526a82f124c95853343ef60",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 53441,
"upload_time": "2024-10-17T20:57:10",
"upload_time_iso_8601": "2024-10-17T20:57:10.651551Z",
"url": "https://files.pythonhosted.org/packages/f4/6b/a710ad327c72e6dc607ba5493c1d92369cb3c7241fc7a5e2afae55ef354c/pyriemann_qiskit-0.4.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50b0c5ffb875fc7e7ddca82ae4d0e4248b28439fcae3d43d6ffbcffb9ee43b74",
"md5": "596c5d527ca1af97cfc4fbfbe740f62c",
"sha256": "64344331b79cedb1e18233d21c03a794c73fbea33be4596e3efd41b4bf223e27"
},
"downloads": -1,
"filename": "pyriemann_qiskit-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "596c5d527ca1af97cfc4fbfbe740f62c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 57233,
"upload_time": "2024-10-17T20:57:12",
"upload_time_iso_8601": "2024-10-17T20:57:12.986643Z",
"url": "https://files.pythonhosted.org/packages/50/b0/c5ffb875fc7e7ddca82ae4d0e4248b28439fcae3d43d6ffbcffb9ee43b74/pyriemann_qiskit-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 20:57:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyRiemann",
"github_project": "pyRiemann-qiskit",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"<",
"2.2"
]
]
},
{
"name": "cython",
"specs": []
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.5.2"
]
]
},
{
"name": "pyriemann",
"specs": []
},
{
"name": "qiskit",
"specs": [
[
"==",
"1.*"
]
]
},
{
"name": "qiskit_algorithms",
"specs": [
[
"==",
"0.3.0"
]
]
},
{
"name": "qiskit_machine_learning",
"specs": [
[
"==",
"0.7.2"
]
]
},
{
"name": "qiskit-ibm-provider",
"specs": [
[
"==",
"0.11.0"
]
]
},
{
"name": "qiskit-optimization",
"specs": [
[
"==",
"0.6.1"
]
]
},
{
"name": "qiskit-aer",
"specs": [
[
"==",
"0.15.1"
]
]
},
{
"name": "cvxpy",
"specs": [
[
"==",
"1.5.2"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.13.1"
]
]
},
{
"name": "docplex",
"specs": [
[
">=",
"2.21.207"
]
]
},
{
"name": "firebase_admin",
"specs": [
[
"==",
"6.5.0"
]
]
},
{
"name": "tqdm",
"specs": []
},
{
"name": "pandas",
"specs": []
}
],
"lcname": "pyriemann-qiskit"
}
JSON
