# qbraid-algorithms
<p align="left">
<a href="https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml">
<img src="https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml/badge.svg?branch=main" alt="CI"/>
</a>
<a href="https://codecov.io/gh/qBraid/qbraid-algorithms">
<img src="https://codecov.io/gh/qBraid/qbraid-algorithms/graph/badge.svg?token=7jYcnneDys"/>
</a>
<a href="https://pypi.org/project/qbraid-algorithms/">
<img src="https://img.shields.io/pypi/v/qbraid-algorithms.svg?color=blue" alt="PyPI version"/>
</a>
<a href="https://pypi.org/project/qbraid-algorithms/">
<img src="https://img.shields.io/pypi/pyversions/qbraid-algorithms.svg?color=blue" alt="PyPI version"/>
</a>
<a href='http://www.apache.org/licenses/LICENSE-2.0'>
<img src='https://img.shields.io/github/license/qBraid/qbraid-qir.svg' alt='License'/>
</a>
<a href="https://discord.gg/TPBU2sa8Et">
<img src="https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white" alt="Discord"/>
</a>
</p>
Python package for building, simulating, and benchmarking hybrid quantum-classical algorithms.
[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com?gitHubUrl=https://github.com/qBraid/qbraid-algorithms.git)
## Installation
qbraid-algorithms requires Python 3.11 or greater, and can be installed with pip as follows:
```bash
pip install qbraid-algorithms
```
>[!WARNING]
> **This project is "pre-alpha", and is not yet stable or fully realized. Use with caution, as the API and functionality are subject to significant changes.**
### Install from source
You can also install from source by cloning this repository and running a pip install command
in the root directory of the repository:
```bash
git clone https://github.com/qBraid/qbraid-algorithms.git
cd qbraid-algorithms
pip3 install .
```
## Check version
You can view the version of qbraid-algorithms you have installed within a Python shell as follows:
```python
import qbraid_algorithms
qbraid_algorithms.__version__
```
## Key Features: Load algorithms as PyQASM modules and QASM files
qBraid Algorithms provides a collection of quantum algorithms that can be loaded
as [PyQASM](https://docs.qbraid.com/pyqasm/user-guide/overview) modules, or
you can generate .qasm files to use them as subroutines in your own circuits.
### Loading Algorithms as PyQASM Modules
To load an algorithm as a PyQASM module, use the `load_algorithm` function from the `qbraid_algorithms` package, passing algorithm-specific parameters. For example, to load the Quantum Fourier Transform (QFT) algorithm:
```python
from qbraid_algorithms import qft
qft_module = qft.load_algorithm(3) # Load QFT for 3 qubits
```
Now, you can perform operations with the PyQASM module, such as unrolling, and
converting back to a QASM string:
```python
qft_module.unroll()
qasm_str = pyqasm.dumps(qft_module)
```
### Loading Algorithms as `.qasm` Files
In order to utilize algorithms as subroutines in your own circuits, use the
`generate_subroutine` function for your desired algorithm. By passing algorithm-specific parameters, and optionally a desired output path, you can
generate a .qasm file containing a subroutine for the paramterized circuit. For
example, to generate a QFT subroutine for 4 qubits:
```python
from qbraid_algorithms import qft, iqft
path = "path/to/output" # Specify your desired output path
qft.generate_subroutine(4) # Generate 4-qubit QFT in the current directory
iqft.generate_subroutine(4, path=path) # Generate 4-qubit IQFT in specified path
```
To utilize the generated subroutine in your own circuit, include the generated
.qasm file, and call the subroutine on an qubit register of the size specified
when generating the subroutine. For example, after running
```python
qft.generate_subroutine(4)
```
you can append `include "qft.qasm";` to your OpenQASM file, and call the
subroutine. For example:
```qasm
OPENQASM 3.0;
include "qft.qasm";
qubit[4] q;
bit[4] c;
qft(q);
measure q -> c;
```
## CLI Usage
qBraid Algorithms includes a command-line interface (CLI) for generating quantum algorithm subroutines.
### Installation
To use the CLI, install with CLI dependencies:
```bash
pip install "qbraid-algorithms[cli]"
```
Or install from source:
```bash
pip install -e ".[cli]"
```
### Generate Subroutines
Generate quantum algorithm subroutines that can be included in other circuits:
```bash
# Generate QFT subroutine for 4 qubits
qbraid-algorithms generate qft --qubits 4
# Generate IQFT subroutine for 3 qubits with custom name and show the circuit
qbraid-algorithms generate iqft -q 3 -o my_iqft.qasm --gate-name my_iqft --show
# Generate Bernstein-Vazirani circuit for secret "101" and display it
qbraid-algorithms generate bernvaz --secret "101" --show
# Generate only the oracle for Bernstein-Vazirani
qbraid-algorithms generate bernvaz -s "1001" --oracle-only --show
# Generate QPE subroutine for 4 qubits with a custom unitary gate
qbraid-algorithms generate qpe --unitary-file my_gate.qasm --qubits 4
# Generate QPE with custom output and show the circuit
qbraid-algorithms generate qpe -u gate.qasm -q 3 -o my_qpe.qasm --show
```
### Help
Get help for any command:
```bash
qbraid-algorithms --help
qbraid-algorithms generate --help
qbraid-algorithms generate qft --help
qbraid-algorithms generate iqft --help
qbraid-algorithms generate bernvaz --help
qbraid-algorithms generate qpe --help
qbraid-algorithms generate bernvaz --help
```
### Examples
#### Complete Workflow
1. Generate a QFT subroutine:
```bash
qbraid-algorithms generate qft --qubits 3
```
2. Generate a Bernstein-Vazirani oracle and view it:
```bash
qbraid-algorithms generate bernvaz --secret "101" --oracle-only --show
```
3. Generate an IQFT circuit with custom output:
```bash
qbraid-algorithms generate iqft --qubits 4 --output my_iqft_4.qasm --show
```
4. Generate a QPE subroutine for phase estimation:
```bash
qbraid-algorithms generate qpe --unitary-file t_gate.qasm --qubits 3 --show
```
## Community
**We are actively looking for new contributors!**
- Interested in contributing code, or making a PR? See
[CONTRIBUTING.md](CONTRIBUTING.md)
- For feature requests and bug reports: [Submit an issue](https://github.com/qBraid/qbraid-algorithms/issues)
- For discussions and/or specific questions about qBraid services, [join our discord community](https://discord.gg/TPBU2sa8Et)
- For questions that are more suited for a forum, post to [Stack Exchange](https://quantumcomputing.stackexchange.com/) with the [`qbraid`](https://quantumcomputing.stackexchange.com/questions/tagged/qbraid) tag.
- By participating, you are expected to uphold our [code of conduct](CODE_OF_CONDUCT).
## License
[Apache-2.0 License](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "qbraid-algorithms",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "qbraid, quantum, algorithms, openqasm",
"author": "qBraid Development Team",
"author_email": "contact@qbraid.com",
"download_url": "https://files.pythonhosted.org/packages/26/71/2c51cea8a313f8babcafa3e3850da7dfe4ccb78393348a96448901f9ed37/qbraid_algorithms-0.1.0.tar.gz",
"platform": null,
"description": "# qbraid-algorithms\n\n<p align=\"left\">\n <a href=\"https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml\">\n <img src=\"https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml/badge.svg?branch=main\" alt=\"CI\"/>\n </a>\n <a href=\"https://codecov.io/gh/qBraid/qbraid-algorithms\"> \n <img src=\"https://codecov.io/gh/qBraid/qbraid-algorithms/graph/badge.svg?token=7jYcnneDys\"/>\n </a>\n <a href=\"https://pypi.org/project/qbraid-algorithms/\">\n <img src=\"https://img.shields.io/pypi/v/qbraid-algorithms.svg?color=blue\" alt=\"PyPI version\"/>\n </a>\n <a href=\"https://pypi.org/project/qbraid-algorithms/\">\n <img src=\"https://img.shields.io/pypi/pyversions/qbraid-algorithms.svg?color=blue\" alt=\"PyPI version\"/>\n </a>\n <a href='http://www.apache.org/licenses/LICENSE-2.0'>\n <img src='https://img.shields.io/github/license/qBraid/qbraid-qir.svg' alt='License'/>\n </a>\n <a href=\"https://discord.gg/TPBU2sa8Et\">\n <img src=\"https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white\" alt=\"Discord\"/>\n </a>\n</p>\n\nPython package for building, simulating, and benchmarking hybrid quantum-classical algorithms.\n\n[<img src=\"https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png\" width=\"150\">](https://account.qbraid.com?gitHubUrl=https://github.com/qBraid/qbraid-algorithms.git)\n\n## Installation\n\nqbraid-algorithms requires Python 3.11 or greater, and can be installed with pip as follows:\n\n```bash\npip install qbraid-algorithms\n```\n\n>[!WARNING]\n> **This project is \"pre-alpha\", and is not yet stable or fully realized. Use with caution, as the API and functionality are subject to significant changes.**\n\n### Install from source\n\nYou can also install from source by cloning this repository and running a pip install command\nin the root directory of the repository:\n\n```bash\ngit clone https://github.com/qBraid/qbraid-algorithms.git\ncd qbraid-algorithms\npip3 install .\n```\n\n## Check version\n\nYou can view the version of qbraid-algorithms you have installed within a Python shell as follows:\n\n```python\nimport qbraid_algorithms\n\nqbraid_algorithms.__version__\n```\n\n## Key Features: Load algorithms as PyQASM modules and QASM files\n\nqBraid Algorithms provides a collection of quantum algorithms that can be loaded\nas [PyQASM](https://docs.qbraid.com/pyqasm/user-guide/overview) modules, or\nyou can generate .qasm files to use them as subroutines in your own circuits.\n\n### Loading Algorithms as PyQASM Modules\n\nTo load an algorithm as a PyQASM module, use the `load_algorithm` function from the `qbraid_algorithms` package, passing algorithm-specific parameters. For example, to load the Quantum Fourier Transform (QFT) algorithm:\n\n```python\nfrom qbraid_algorithms import qft\n\nqft_module = qft.load_algorithm(3) # Load QFT for 3 qubits\n```\n\nNow, you can perform operations with the PyQASM module, such as unrolling, and\nconverting back to a QASM string:\n\n```python\nqft_module.unroll()\nqasm_str = pyqasm.dumps(qft_module)\n```\n\n### Loading Algorithms as `.qasm` Files\n\nIn order to utilize algorithms as subroutines in your own circuits, use the\n`generate_subroutine` function for your desired algorithm. By passing algorithm-specific parameters, and optionally a desired output path, you can\ngenerate a .qasm file containing a subroutine for the paramterized circuit. For\nexample, to generate a QFT subroutine for 4 qubits:\n\n```python\nfrom qbraid_algorithms import qft, iqft\npath = \"path/to/output\" # Specify your desired output path\nqft.generate_subroutine(4) # Generate 4-qubit QFT in the current directory\niqft.generate_subroutine(4, path=path) # Generate 4-qubit IQFT in specified path\n\n```\n\nTo utilize the generated subroutine in your own circuit, include the generated\n.qasm file, and call the subroutine on an qubit register of the size specified\nwhen generating the subroutine. For example, after running\n\n```python\nqft.generate_subroutine(4)\n```\n\nyou can append `include \"qft.qasm\";` to your OpenQASM file, and call the\nsubroutine. For example:\n\n```qasm\nOPENQASM 3.0;\ninclude \"qft.qasm\";\n\nqubit[4] q;\nbit[4] c;\n\nqft(q);\nmeasure q -> c;\n```\n\n## CLI Usage\n\nqBraid Algorithms includes a command-line interface (CLI) for generating quantum algorithm subroutines.\n\n### Installation\n\nTo use the CLI, install with CLI dependencies:\n\n```bash\npip install \"qbraid-algorithms[cli]\"\n```\n\nOr install from source:\n\n```bash\npip install -e \".[cli]\"\n```\n\n### Generate Subroutines\n\nGenerate quantum algorithm subroutines that can be included in other circuits:\n\n```bash\n# Generate QFT subroutine for 4 qubits\nqbraid-algorithms generate qft --qubits 4\n\n# Generate IQFT subroutine for 3 qubits with custom name and show the circuit\nqbraid-algorithms generate iqft -q 3 -o my_iqft.qasm --gate-name my_iqft --show\n\n# Generate Bernstein-Vazirani circuit for secret \"101\" and display it\nqbraid-algorithms generate bernvaz --secret \"101\" --show\n\n# Generate only the oracle for Bernstein-Vazirani\nqbraid-algorithms generate bernvaz -s \"1001\" --oracle-only --show\n\n# Generate QPE subroutine for 4 qubits with a custom unitary gate\nqbraid-algorithms generate qpe --unitary-file my_gate.qasm --qubits 4\n\n# Generate QPE with custom output and show the circuit\nqbraid-algorithms generate qpe -u gate.qasm -q 3 -o my_qpe.qasm --show\n```\n\n### Help\n\nGet help for any command:\n\n```bash\nqbraid-algorithms --help\nqbraid-algorithms generate --help\nqbraid-algorithms generate qft --help\nqbraid-algorithms generate iqft --help\nqbraid-algorithms generate bernvaz --help\nqbraid-algorithms generate qpe --help\nqbraid-algorithms generate bernvaz --help\n```\n\n### Examples\n\n#### Complete Workflow\n\n1. Generate a QFT subroutine:\n\n ```bash\n qbraid-algorithms generate qft --qubits 3\n ```\n\n2. Generate a Bernstein-Vazirani oracle and view it:\n\n ```bash\n qbraid-algorithms generate bernvaz --secret \"101\" --oracle-only --show\n ```\n\n3. Generate an IQFT circuit with custom output:\n\n ```bash\n qbraid-algorithms generate iqft --qubits 4 --output my_iqft_4.qasm --show\n ```\n\n4. Generate a QPE subroutine for phase estimation:\n ```bash\n qbraid-algorithms generate qpe --unitary-file t_gate.qasm --qubits 3 --show\n ```\n\n## Community\n\n**We are actively looking for new contributors!**\n\n- Interested in contributing code, or making a PR? See\n [CONTRIBUTING.md](CONTRIBUTING.md)\n- For feature requests and bug reports: [Submit an issue](https://github.com/qBraid/qbraid-algorithms/issues)\n- For discussions and/or specific questions about qBraid services, [join our discord community](https://discord.gg/TPBU2sa8Et)\n- For questions that are more suited for a forum, post to [Stack Exchange](https://quantumcomputing.stackexchange.com/) with the [`qbraid`](https://quantumcomputing.stackexchange.com/questions/tagged/qbraid) tag.\n- By participating, you are expected to uphold our [code of conduct](CODE_OF_CONDUCT).\n\n## License\n\n[Apache-2.0 License](LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package for utilizing, implementing, and building quantum algorithms in OpenQASM 3.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/qBraid/qbraid-algorithms/issues",
"Discord": "https://discord.gg/TPBU2sa8Et",
"Documentation": "https://docs.qbraid.com",
"Homepage": "https://github.com/qBraid/qbraid-algorithms",
"Launch on Lab": "https://account.qbraid.com/?gitHubUrl=https://github.com/qBraid/qbraid-algorithms.git"
},
"split_keywords": [
"qbraid",
" quantum",
" algorithms",
" openqasm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85e6f107f819f4d110043b86b07d27d4f8a6bf75a0c72e81365acd5ff74c77bd",
"md5": "644ce7794a8e18396022cb52f5b71aca",
"sha256": "2fdcd1e18aaae9f2f81dcd20a48fc5a736d753f8ce53fa87deff24171eee6428"
},
"downloads": -1,
"filename": "qbraid_algorithms-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "644ce7794a8e18396022cb52f5b71aca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 25824,
"upload_time": "2025-08-25T21:02:58",
"upload_time_iso_8601": "2025-08-25T21:02:58.050932Z",
"url": "https://files.pythonhosted.org/packages/85/e6/f107f819f4d110043b86b07d27d4f8a6bf75a0c72e81365acd5ff74c77bd/qbraid_algorithms-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26712c51cea8a313f8babcafa3e3850da7dfe4ccb78393348a96448901f9ed37",
"md5": "5e2d14a25debf2e46b84f3d54fbe3141",
"sha256": "72c3d2390e634a2728ae04b44cb613cad2e1a18851b3f4bd7896c0be12cf8aa1"
},
"downloads": -1,
"filename": "qbraid_algorithms-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5e2d14a25debf2e46b84f3d54fbe3141",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 190294,
"upload_time": "2025-08-25T21:02:58",
"upload_time_iso_8601": "2025-08-25T21:02:58.928842Z",
"url": "https://files.pythonhosted.org/packages/26/71/2c51cea8a313f8babcafa3e3850da7dfe4ccb78393348a96448901f9ed37/qbraid_algorithms-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 21:02:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qBraid",
"github_project": "qbraid-algorithms",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "qbraid",
"specs": [
[
"==",
"0.9.9.dev20250821232849"
]
]
},
{
"name": "pyqasm",
"specs": [
[
">=",
"0.5.0"
],
[
"<",
"0.6.0"
]
]
}
],
"tox": true,
"lcname": "qbraid-algorithms"
}
JSON
