qBraid Algos v0.1

README.md

@@ -57,6 +57,150 @@ 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!**
@@ -68,12 +212,6 @@ qbraid_algorithms.__version__
 - 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).
 
-## Acknowledgements
-
-This project was conceived in cooperation with the Quantum Open Source Foundation ([QOSF](https://qosf.org/)).
-
-<a href="https://qosf.org/"><img src="https://qbraid-static.s3.amazonaws.com/logos/qosf.png" width="100px" style="vertical-align: middle;" /></a>
-
 ## License
 
 [Apache-2.0 License](LICENSE)

bin/qbraid-algorithms

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# Copyright 2025 qBraid
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Entry point script for qbraid-algorithms CLI.
+"""
+
+from qbraid_algorithms.cli.main import app
+
+if __name__ == "__main__":
+    app()

docs/conf.py

@@ -14,7 +14,7 @@
 
 # Set the version
 version = qbraid_algorithms.__version__
-
+release = version
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be

docs/index.rst

@@ -51,7 +51,7 @@
       <span style="color:#808080"> | algorithms</span>
    </h1>
    <p style="text-align:center;font-style:italic;color:#808080">
-      Build hybrid quantum-classical algorithms with qBraid.
+      Use and build quantum algorithms with qBraid.
    </p>
    </body>
    </html>
@@ -63,7 +63,7 @@
 Overview
 ---------
 
-Python package for building, simulating, and benchmarking hybrid quantum-classical algorithms.
+Python package for utilizing, implementing, and building quantum algorithms in OpenQASM 3.
 
 
 Installation
@@ -91,44 +91,44 @@ You can also install from source by cloning this repository and running a pip in
 Resources
 ----------
 
-- `User Guide <https://docs.qbraid.com/sdk/user-guide>`_
-- `Example Notebooks <https://github.com/qBraid/qbraid-lab-demo>`_
-- `API Reference <https://qbraid.github.io/qBraid/api/qbraid_algorithms.html>`_
+- `User Guide <https://docs.qbraid.com/qbraid-algorithms/user-guide/overview>`_
+- `Example Notebooks <https://github.com/qBraid/qbraid-algorithms/tree/main/examples>`_
+- `API Reference <https://sdk.qbraid.com/qBraid/api/qbraid_algorithms.html>`_
 - `Source Code <https://github.com/qBraid/qbraid-algorithms>`_
 
 .. toctree::
    :maxdepth: 1
    :caption: SDK API Reference
    :hidden:
 
-   qbraid <https://qbraid.github.io/qBraid/api/qbraid.html>
-   qbraid.programs <https://qbraid.github.io/qBraid/api/qbraid.programs.html>
-   qbraid.interface <https://qbraid.github.io/qBraid/api/qbraid.interface.html>
-   qbraid.transpiler <https://qbraid.github.io/qBraid/api/qbraid.transpiler.html>
-   qbraid.passes <https://qbraid.github.io/qBraid/api/qbraid.passes.html>
-   qbraid.runtime <https://qbraid.github.io/qBraid/api/qbraid.runtime.html>
-   qbraid.visualization <https://qbraid.github.io/qBraid/api/qbraid.visualization.html>
+   qbraid <https://sdk.qbraid.com/qBraid/api/qbraid.html>
+   qbraid.programs <https://sdk.qbraid.com/qBraid/api/qbraid.programs.html>
+   qbraid.interface <https://sdk.qbraid.com/qBraid/api/qbraid.interface.html>
+   qbraid.transpiler <https://sdk.qbraid.com/qBraid/api/qbraid.transpiler.html>
+   qbraid.passes <https://sdk.qbraid.com/qBraid/api/qbraid.passes.html>
+   qbraid.runtime <https://sdk.qbraid.com/qBraid/api/qbraid.runtime.html>
+   qbraid.visualization <https://sdk.qbraid.com/qBraid/api/qbraid.visualization.html>
 
 .. toctree::
    :caption: QIR API Reference
    :hidden:
 
-   qbraid_qir <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.html>
-   qbraid_qir.cirq <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.cirq.html>
-   qbraid_qir.qasm3 <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.qasm3.html>
+   qbraid_qir <https://sdk.qbraid.com/qbraid-qir/api/qbraid_qir.html>
+   qbraid_qir.cirq <https://sdk.qbraid.com/qbraid-qir/api/qbraid_qir.cirq.html>
+   qbraid_qir.qasm3 <https://sdk.qbraid.com/qbraid-qir/api/qbraid_qir.qasm3.html>
 
 .. toctree::
    :caption: CORE API Reference
    :hidden:
 
-   qbraid_core <https://qbraid.github.io/qbraid-core/api/qbraid_core.html>
-   qbraid_core.services <https://qbraid.github.io/qbraid-core/api/qbraid_core.services.html>
+   qbraid_core <https://sdk.qbraid.com/qbraid-core/api/qbraid_core.html>
+   qbraid_core.services <https://sdk.qbraid.com/qbraid-core/api/qbraid_core.services.html>
 
 .. toctree::
    :caption: PYQASM API Reference
    :hidden:
 
-   pyqasm <https://qbraid.github.io/pyqasm/api/pyqasm.html>
+   pyqasm <https://sdk.qbraid.com/pyqasm/api/pyqasm.html>
 
 
 .. toctree::

examples/QPE/prepare_state.qasm

@@ -0,0 +1,6 @@
+OPENQASM 3.0;
+include "stdgates.inc";
+
+gate prep q {
+    x q;
+}