qbraid-algorithms

Python package for building, simulating, and benchmarking hybrid quantum-classical algorithms.

Installation

qbraid-algorithms requires Python 3.11 or greater, and can be installed with pip as follows:

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:

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:

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 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 generate_program function from the qbraid_algorithms package, passing algorithm-specific parameters. For example, to load the Quantum Fourier Transform (QFT) algorithm:

from qbraid_algorithms import qft

qft_module = qft.generate_program(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:

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 save_to_qasm 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:

from qbraid_algorithms import qft, iqft
path = "path/to/output" # Specify your desired output path
qft.save_to_qasm(4) # Generate 4-qubit QFT in the current directory
iqft.save_to_qasm(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

qft.save_to_qasm(4)

you can append include "qft.qasm"; to your OpenQASM file, and call the subroutine. For example:

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:

pip install "qbraid-algorithms[cli]"

Or install from source:

pip install -e ".[cli]"

Generate Subroutines

Generate quantum algorithm subroutines that can be included in other circuits:

# 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:

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:

   qbraid-algorithms generate qft --qubits 3
   

2. Generate a Bernstein-Vazirani oracle and view it:

   qbraid-algorithms generate bernvaz --secret "101" --oracle-only --show
   

3. Generate an IQFT circuit with custom output:

   qbraid-algorithms generate iqft --qubits 4 --output my_iqft_4.qasm --show
   

4. Generate a QPE subroutine for phase estimation:

   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
• For feature requests and bug reports: Submit an issue
• For discussions and/or specific questions about qBraid services, join our discord community
• For questions that are more suited for a forum, post to Stack Exchange with the qbraid tag.
• By participating, you are expected to uphold our code of conduct.

License

Apache-2.0 License