{"id":15442812,"url":"https://github.com/pyriemann/pyriemann-qiskit","last_synced_at":"2026-03-10T05:03:48.670Z","repository":{"id":37012222,"uuid":"410098026","full_name":"pyRiemann/pyRiemann-qiskit","owner":"pyRiemann","description":"A library for machine learning and quantum programming based on pyRiemann and Qiskit projects","archived":false,"fork":false,"pushed_at":"2024-07-01T08:24:01.000Z","size":4013,"stargazers_count":21,"open_issues_count":34,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-07-06T09:39:04.306Z","etag":null,"topics":["covariance-matrix","machine-learning","python","qiskit","quantum-computing","riemannian-geometry"],"latest_commit_sha":null,"homepage":"https://pyriemann-qiskit.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyRiemann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-24T20:49:04.000Z","updated_at":"2024-07-09T19:02:05.180Z","dependencies_parsed_at":"2023-10-25T18:48:14.643Z","dependency_job_id":"7ae99cde-6a93-4325-b7ab-d68b7bbe6d56","html_url":"https://github.com/pyRiemann/pyRiemann-qiskit","commit_stats":{"total_commits":92,"total_committers":5,"mean_commits":18.4,"dds":0.5,"last_synced_commit":"10108a1870acadbb1b3b5d1d36e04754135466e7"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyRiemann%2FpyRiemann-qiskit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyRiemann%2FpyRiemann-qiskit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyRiemann%2FpyRiemann-qiskit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyRiemann%2FpyRiemann-qiskit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyRiemann","download_url":"https://codeload.github.com/pyRiemann/pyRiemann-qiskit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230388129,"owners_count":18217755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["covariance-matrix","machine-learning","python","qiskit","quantum-computing","riemannian-geometry"],"created_at":"2024-10-01T19:30:25.714Z","updated_at":"2026-03-10T05:03:48.656Z","avatar_url":"https://github.com/pyRiemann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Qiskit Ecosystem](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fqiskit.github.io%2Fecosystem%2Fb%2Ffb1907a7)](https://qisk.it/e)\n[![PyPI version](https://badge.fury.io/py/pyriemann-qiskit.svg)](https://badge.fury.io/py/pyriemann-qiskit)\n[![Documentation Status](https://readthedocs.org/projects/pyriemann-qiskit/badge/?version=latest)](https://pyriemann-qiskit.readthedocs.io/)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![Python 3.10-3.12](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/downloads/)\n\n# pyRiemann-qiskit\n\n**Quantum-enhanced machine learning for Brain-Computer Interfaces and EEG analysis**\n\npyRiemann-qiskit bridges quantum computing (via Qiskit) with Riemannian geometry (via\npyRiemann) to enable quantum classification algorithms for BCI and EEG data. The library\nimplements quantum versions of Support Vector Classifiers (QSVC), Variational Quantum\nClassifiers (VQC), and the Nearest Centroid Hypersphere (NCH) algorithm with convex\noptimization.\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Overview](#overview)\n- [Limitations \u0026 Considerations](#limitations--considerations)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Citation](#how-to-cite)\n- [References](#references)\n- [Links \u0026 Resources](#links--resources)\n- [Troubleshooting](#troubleshooting)\n\n## Key Features\n\n- 🔬 **Quantum Classifiers**: QSVC and VQC implementations with Riemannian geometry\n- 🧠 **Quantum NCH**: Quantum Nearest Convex Hull (convex optimization with constraint\n  programming)\n- 📊 **BCI/EEG Focus**: Optimized for covariance matrix classification\n- 🔗 **Scikit-learn Compatible**: Follows scikit-learn API conventions\n- 🎨 **Visualization Tools**: Quantum art and manifold visualization\n- 🔥 **Firebase Integration**: Remote storage for experiment results\n\n## Overview\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 can emulate or be a\nquantum machine. Qiskit's 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 NCH algorithm with convex\noptimization. See a dedicated example on quantum-NCH\n[here](https://github.com/pyRiemann/pyRiemann-qiskit/blob/main/examples/ERP/noplot_classify_P300_nch.py).\n\nThe remainder of this README details some of the quantum limitations and will guide you\nthrough installation. Full documentation, including API description, is available at\n\u003chttps://pyriemann-qiskit.readthedocs.io/\u003e. The repository also includes a\n[wiki](https://github.com/pyRiemann/pyRiemann-qiskit/wiki) where you can find additional\ninformation.\n\n## Limitations \u0026 Considerations\n\n### Hardware Constraints\n\nThe number of qubits (and therefore the feature dimension) is limited to:\n\n- **Local simulator**: ~36 qubits (depends on system memory)\n- **Open plan quantum hardware**: 127 qubits\n- **Exploratory hardware**: 156 qubits (IBM Heron QPU, restricted access)\n\n### Performance Considerations\n\n- **Time complexity**: Quantum algorithms are computationally expensive, especially when\n  running locally. A higher number of trials or dimensions increases the time to\n  completion.\n- **Queue times**: Remote backends may experience delays depending on the number of\n  concurrent users.\n- **Recommended use**: Offline analysis only\n\n⚠️ **Note**: The number of trials is limited in the examples we provide for demonstration\npurposes. However, you should avoid such practices in your own analysis and use sufficient\niterations for reliable results.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 - 3.12\n- [Anaconda](https://www.anaconda.com/) (recommended)\n\n### Basic Installation\n\n**From PyPI (stable release):**\n\n```bash\npip install pyriemann-qiskit\n```\n\n**From source (development version):**\n\n```bash\ngit clone https://github.com/pyRiemann/pyRiemann-qiskit.git\ncd pyRiemann-qiskit\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\n**Verify installation:**\n\n```python\nimport pyriemann_qiskit\nprint(pyriemann_qiskit.__version__)\n```\n\n### Optional Dependencies\n\n**GPU optimization (Linux only):**\n\n```bash\npip install .[optim_linux]\n```\n\nNote: Qiskit only provides binaries for Linux. For other platforms, or if you want to\nenable specific NVIDIA optimization for quantum computing, you need to build the binary\n[yourself](https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md#building-with-gpu-support).\n\n**Symbolic simulation:**\n\n```bash\npip install .[optim]\n```\n\nThis enables [qiskit-symb](https://github.com/SimoneGasperini/qiskit-symb) integration.\n\n**Documentation and examples:**\n\n```bash\npip install .[docs]\n```\n\n**Testing:**\n\n```bash\npip install .[tests]\n```\n\n### Running Examples\n\nTo run a specific example on your local machine, first install dependencies for\ndocumentation:\n\n```bash\npip install .[docs]\n```\n\nThen you can run the python example of your choice:\n\n```bash\npython examples/ERP/plot_classify_P300_bi.py\n```\n\n### Docker Installation\n\n**Using VS Code Dev Containers:**\n\n1. Install VS Code with \"Remote - Containers\" extension\n2. Open project in VS Code\n3. Press `F1` → \"Rebuild and Reopen in Container\"\n4. Wait for the container to build\n5. Verify installation:\n\n```python\nimport pyriemann_qiskit\n```\n\n**Using Docker CLI:**\n\n```bash\n# Build image\ndocker build -t pyrq .\n\n# Run container\ndocker run --detach pyrq\n```\n\n**Pre-built images:**\n\nDocker images are available at\n[GitHub Container Registry](https://github.com/pyRiemann/pyRiemann-qiskit/pkgs/container/pyriemann-qiskit).\nThey are pushed to the registry on each release.\n\n## Quick Start\n\nHere's a sketch example using P300 EEG data from MOABB:\n\n```python\nfrom moabb.datasets import bi2012\nfrom moabb.evaluations import WithinSessionEvaluation\nfrom moabb.paradigms import P300\nfrom sklearn.pipeline import make_pipeline\nfrom pyriemann.estimation import XdawnCovariances\nfrom pyriemann.tangentspace import TangentSpace\nfrom sklearn.decomposition import PCA\nfrom sklearn.discriminant_analysis import LinearDiscriminantAnalysis as LDA\n\nfrom pyriemann_qiskit.pipelines import QuantumClassifierWithDefaultRiemannianPipeline\n\n# Load P300 dataset\nparadigm = P300(resample=128)\ndataset = bi2012()\ndataset.subject_list = dataset.subject_list[0:2]  # Use 2 subjects for demo\n\n# Create pipelines\npipelines = {}\n\n# Quantum pipeline with Riemannian geometry\npipelines[\"RG+QuantumSVM\"] = QuantumClassifierWithDefaultRiemannianPipeline(\n    shots=512,  # Use None for classical SVM\n    nfilter=2,\n    dim_red=PCA(n_components=5),\n    params={\"n_jobs\": 1}\n)\n\n# Classical pipeline for comparison\nlabels_dict = {\"Target\": 1, \"NonTarget\": 0}\npipelines[\"RG+LDA\"] = make_pipeline(\n    XdawnCovariances(nfilter=2, classes=[labels_dict[\"Target\"]],\n                     estimator=\"lwf\", xdawn_estimator=\"scm\"),\n    TangentSpace(),\n    PCA(n_components=10),\n    LDA(solver=\"lsqr\", shrinkage=\"auto\")\n)\n\n# Evaluate\nevaluation = WithinSessionEvaluation(paradigm=paradigm, datasets=[dataset])\nresults = evaluation.process(pipelines)\nprint(results.groupby(\"pipeline\").mean(\"score\")[[\"score\", \"time\"]])\n```\n\nFor a complete working example, see\n[examples/ERP/plot_classify_P300_bi.py](examples/ERP/plot_classify_P300_bi.py).\n\nFor more examples, see the [examples](examples/) directory.\n\n## Documentation\n\nFull documentation is available at \u003chttps://pyriemann-qiskit.readthedocs.io/\u003e, including:\n\n- API reference\n- Tutorials and examples\n- Theory and background\n- Advanced usage\n\n## Contributing\n\nWe welcome contributions! 🎉\n\n### Ways to Contribute\n\n1. **Report Issues**:\n   [Create an issue](https://github.com/pyRiemann/pyRiemann-qiskit/issues/new) for bugs or\n   feature requests\n2. **Submit Pull Requests**: Fork, develop, and submit PRs against `master`\n3. **Improve Documentation**: Help us make docs clearer\n4. **Share Examples**: Contribute new use cases\n\n### Development Guidelines\n\n- Use `git rebase` instead of merge commits\n- Follow scikit-learn conventions\n- Run `flake8` for code formatting\n- Add tests for new features\n- Document all public methods (NumPy docstring format)\n\n**Code contribution** can be on core functionalities, documentation, or automation:\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).\n\n**Check code style:**\n\n```bash\npip install flake8\nflake8\n```\n\n**Run tests:**\n\n```bash\npip install .[tests]\npytest\n```\n\nYou can also specify a specific test file:\n\n```bash\npytest tests/test_classification.py\n```\n\n**Automated workflows**: GitHub Actions run automatically when you push a commit. However,\nthe workflow for example execution is only triggered when you modify one of the examples\nor the 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)\nin your fork to see the result of the CI pipeline. Results are also indicated at the end\nof your pull request when raised. However note, that workflows in the pull request need\napproval from the maintainers before being executed.\n\nSee [AGENTS.md](AGENTS.md) for detailed development guidelines.\n\n## How to cite?\n\nAnton Andreev, Grégoire Cattan, Sylvain Chevallier, and Quentin Barthélemy.\n'pyRiemann-qiskit: A Sandbox for Quantum Classification Experiments with Riemannian\nGeometry'. 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## References\n\n[1] **Blance, A., \u0026 Spannowsky, M.** (2021). Quantum machine learning for particle physics\nusing a variational quantum classifier. _Journal of High Energy Physics_, 2021(2), 212.\nhttps://doi.org/10.1007/JHEP02(2021)212\n\n[2] **Rebentrost, P., Mohseni, M., \u0026 Lloyd, S.** (2014). Quantum Support Vector Machine\nfor Big Data Classification. _Physical Review Letters_, 113(13), 130503.\nhttps://doi.org/10.1103/PhysRevLett.113.130503\n\n[3] **Abraham, H., et al.** (2019). Qiskit: An Open-source Framework for Quantum\nComputing. Zenodo. https://doi.org/10.5281/zenodo.2562110\n\n[4] **Havlíček, V., et al.** (2019). Supervised learning with quantum-enhanced feature\nspaces. _Nature_, 567(7747), 209–212. https://doi.org/10.1038/s41586-019-0980-2\n\n[5] **Cattan, G., \u0026 Andreev, A.** (2022). First steps to the classification of ERPs using\nquantum computation. _NTB Berlin 2022 - International Forum on Neural Engineering \u0026 Brain\nTechnologies_, Berlin, Germany. https://hal.archives-ouvertes.fr/hal-03672246/\n\n## Links \u0026 Resources\n\n- 📖 [Documentation](https://pyriemann-qiskit.readthedocs.io/)\n- 🐛 [Issue Tracker](https://github.com/pyRiemann/pyRiemann-qiskit/issues)\n- 📝 [Wiki](https://github.com/pyRiemann/pyRiemann-qiskit/wiki)\n- 🐳\n  [Docker Images](https://github.com/pyRiemann/pyRiemann-qiskit/pkgs/container/pyriemann-qiskit)\n- 🌐 [Qiskit Ecosystem](https://qisk.it/e)\n\n## Troubleshooting\n\nSee our\n[dedicated troubleshooting page](https://github.com/pyRiemann/pyRiemann-qiskit/wiki/Troubleshooting)\non the wiki.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyriemann%2Fpyriemann-qiskit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyriemann%2Fpyriemann-qiskit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyriemann%2Fpyriemann-qiskit/lists"}