QasmBuilder Macro (#59)

* initial commit - created first qasm file

* bells inequality .qasm file update

* bells inequality qasm

* bern-vaz example ('1001')

* load .qasm w/ pyqasm

* fix

* prelim autoqasm bern-vaz - needs sdk integration

* pqasm loading fix

* Update CONTRIBUTING.md

fixed coverage report test

* simple bells inequality circuit example, cleaned up

* testing for bell's inequality qasm3 circuits

* fix init docs & update measurement from qasm2 to qasm3

* change load_circuit to load_program, create simple jupyter notebook example for Bell's

* fix QasmModoule Error

* attempt to fix module import issue

* formatting

* fixing format issue ... hopefully

* test fix

* first comparision implementation of QFT

* qft qasm only test and first  pass at ampl amp

* file structure change to prevent future merge conflicts

* module compatibility correction

* minor edits and acommodating to regular workflow

* generated test file, demo file and fixed module init. slow progress on debugging the autoqasm closure primitives due to definement of qubit register after submodule definition

* included init file for amplitude amplification

* added new extensible macro generator, need work on gate parameterization, text formatting, and merging includes from gatebuilders

* edits for formatting and procedural correctness

* prep to ampl amplification, staging for HHL and fixes to phase est

* debug and comment on qasmbuilder

* checkpoint for working on HHL and debugging named and inverse operations

* squashed commit for file restructure, syntax, debug, and annotation edits

* cleaning up init ifles and validation edits to amp ampl

* fixed module namespace conflicts and improvements to amplitude amplification

* fix dangling file edits

* remove remnants of autoqasm from local branch

* cleaned up hamil closures and heavily improved demo qasmbuilder

* eod commit, further debug on all and implementation of rodeo, both direct ancillas and mid circuit measurement

* midway commit, fillout of block encoding.

* eod work towards completion of prep select embedding

* initial completion commit of prep select library, moving to debug and annotate

* commenting and completed debug of prep block encoding

* clearer directory name

* eod, near completion of toeplitz and diagonal libraries

* toeplitz complete, onto gqsp and loads

* gqsp initial

* cleanup of files and initial completion of trotter

* improvements in subroutine calls and namespace fix in trotter

* added multi trotter and linear trotter

* building out unit tests

* added and partially debugged test suite

* progress towards final implementation using test driven debug

* fixed doctree and ran linter

* 100% test coverage, shift to load integrations and linting fixes

* fixed imports to be named

* aligned naming to pep 8 convention+ linting improvements

* name fixes and duplicate code edited for linter

* semi final commit, changeover to full pull request, addition of final grover unit test and further debugging of behavior + name fixes, and demo notebook

* test fix and removal of local package requirements used for  extended testing

* doc build fixes

* updates to function for debug +buld and new tests

* update to HHL

* weekend updates for local build tests 1

* fixed lint check and final test pass

* minor edits, cannot fix bug in reSt with ampl amp as there is no traceback

* fix unit-tests + format check

* fix ci and other stuff

* fix the string error

---------

Co-authored-by: LukeAndreesen <[email protected]>
Co-authored-by: Ryan Hill <[email protected]>
Co-authored-by: Harshit Gupta <[email protected]>

Author: 4 people

examples/bells_inequality.ipynb

@@ -58,10 +58,10 @@ multi_line_output = 3
 include_trailing_comma = true
 force_grid_wrap = 0
 use_parentheses = true
-line_length = 100
+line_length = 120
 
 [tool.pylint.'MESSAGES CONTROL']
-max-line-length = 100
+max-line-length = 120
 disable = "W0108,W0511,W0401,R0902,R0903,R0913,E0401"
 
 [tool.pylint.MASTER]

examples/demo_hamiltonians.ipynb

@@ -24,15 +24,20 @@
 
 .. autosummary::
     :toctree: ../stubs/
-
+    
     bernstein_vazirani
     qft
     iqft
     qpe
+    qtran
+    hhl
+    evolution
+    embedding
+    amplitude_amplification
+    rodeo
 
 """
 
-from . import bernstein_vazirani, iqft, qft, qpe
 from ._version import __version__
 
 __all__ = [
@@ -41,4 +46,10 @@
     "iqft",
     "bernstein_vazirani",
     "qpe",
+    "qtran",
+    'evolution',
+    'embedding',
+    'amplitude_amplification',
+    'hhl',
+    'rodeo'
 ]

examples/demo_qasmbuilder.ipynb

@@ -0,0 +1,32 @@
+# 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.
+
+"""
+Module providing Amplitude Amplification implementation.
+
+Functions
+----------
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    AALibrary
+
+"""
+
+from .amp_ampl import AALibrary
+
+__all__ = [
+    "AALibrary"
+]

pyproject.toml

@@ -0,0 +1,269 @@
+# 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.
+'''
+Amplitude Amplification Library for Quantum Algorithms
+This module implements amplitude amplification techniques for quantum algorithms,
+including Grover's algorithm and general amplitude amplification. It provides
+the `AALibrary` class, which extends `GateLibrary` to offer reusable quantum
+subroutines for amplifying the probability amplitudes of desired quantum states.
+Classes:
+    AALibrary(GateLibrary):
+        Implements Grover's algorithm and general amplitude amplification.
+Usage:
+    - Use `grover` for unstructured search problems.
+    - Use `amp_ampl` for general amplitude amplification with arbitrary oracles and state preparation.
+Notes:
+    - The library uses subroutine-based implementations for compact qasm code generation.
+    - Multi-controlled Z gates are used for phase inversion in the diffusion operator.
+    - The code is designed to be extensible for other amplitude amplification algorithms.
+'''
+from typing import List
+
+from qbraid_algorithms.qtran import GateBuilder, GateLibrary, std_gates
+
+# TODO: once again Physics notation was originally used convert to better naming
+# pylint: disable=invalid-name
+# mypy: disable_error_code="call-arg"
+
+class AALibrary(GateLibrary):
+    """
+    Amplitude Amplification Library implementing Grover's algorithm and general amplitude amplification.
+
+    This library provides quantum algorithms for amplitude amplification, including:
+    - Grover's algorithm for unstructured search
+    - General amplitude amplification for arbitrary oracles
+
+    Both algorithms use the principle of selective phase rotation to amplify desired
+    quantum state amplitudes while suppressing unwanted ones.
+    """
+
+    name = "AmplitudeAmplification"
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the AALibrary by calling the parent GateLibrary constructor."""
+        super().__init__(*args, **kwargs)
+        self.name = "AmplAmp"
+
+    def grover(self, H, qubits: List[int], depth: int) -> None:
+        """
+        Implement Grover's algorithm for quantum search.
+
+        Grover's algorithm provides a quadratic speedup for searching unsorted databases.
+        It uses amplitude amplification with a specific oracle (H) to amplify the amplitude
+        of target states while suppressing others.
+
+        The algorithm structure:
+        1. Initialize qubits in superposition with Hadamard gates
+        2. Repeat depth times:
+           - Apply oracle H (marks target states)
+           - Apply diffusion operator (inverts amplitudes about average)
+
+        Args:
+            H: Oracle/Hamiltonian that marks target states
+            qubits: List of qubit indices to operate on
+            depth: Number of Grover iterations to perform
+        """
+        # Generate unique subroutine name based on parameters
+        name = f'Grover{len(qubits)}{H.name}{depth}'
+
+        # Check if subroutine already exists to avoid regeneration
+        if name in self.gate_ref:
+            qubit_list = "{" + " ,".join(str(i) for i in qubits) + "}"
+            self.call_subroutine(name, [self.call_space.format(qubit_list)])
+            # Alternative gate-based call (currently commented out):
+            # self.call_gate(name, qubits[-1], qubits[:-1])
+            return
+
+        # Create new gate builder for defining the subroutine
+        gate_system = GateBuilder()
+        std_library = gate_system.import_library(std_gates)
+        std_library.call_space = " {}"
+        oracle_library = gate_system.import_library(H)
+
+        # NOTE: Alternative gate-based implementation is commented out below.
+        # The current subroutine approach keeps generated code compact,
+        # whereas gates cannot use loops (would require Python loops instead).
+
+        # Alternative gate implementation (commented out):
+        # std_library.begin_gate(name, qargs)
+        # # Initial superposition
+        # [std_library.h(i) for i in qargs]
+        # # Grover iteration: Za -> Z0
+        # std_library.begin_loop(depth)
+        # std_library.comment("Za")
+        # oracle_library.apply(qargs)
+        # [std_library.h(i) for i in qargs]
+        # std_library.comment("Z0")
+        # [std_library.x(i) for i in qargs]
+        # std_library.controlled_op("z", (qargs[-1], qargs[:-1]), n=len(qubits)-1)
+        # [std_library.x(i) for i in qargs]
+        # [std_library.h(i) for i in qargs]
+        # std_library.end_loop()
+        # std_library.end_gate()
+
+        # Current subroutine-based implementation
+        register = "reg"
+        std_library.begin_subroutine(name, [f"qubit[{len(qubits)}] {register}"])
+
+        # Initialize all qubits in superposition
+        std_library.h(register)
+
+        # Main Grover iteration loop
+        std_library.begin_loop(depth)
+
+        # Apply oracle (marks target states with phase flip)
+        std_library.comment("Za")
+        oracle_library.apply([f"reg[{i}]" for i in range(len(qubits))])
+
+        # Apply diffusion operator (inverts amplitudes about average)
+        std_library.h(register)
+        std_library.comment("Z0")
+        std_library.x(register)  # Flip all qubits
+        # Multi-controlled Z gate (phase flip when all qubits are |1⟩)
+        std_library.controlled_op("z",(f"{register}[0]", [f"{register}[{i}]" for i in range(len(qubits) - 1)]),
+        n=len(qubits) - 1
+        )
+        std_library.x(register)  # Flip back
+        std_library.h(register)
+
+        std_library.end_loop()
+        std_library.end_subroutine()
+
+        # Build and merge the subroutine into main library
+        self.merge(*gate_system.build(), name)
+
+        # Call the created subroutine
+        qubit_list = "{" + " ,".join(str(i) for i in qubits) + "}"
+        self.call_subroutine(name, [self.call_space.format(qubit_list)])
+
+    def amp_ampl(self, Z, H, qubits: List[int], depth: int) -> None:
+        """
+        Implement general amplitude amplification algorithm.
+
+        This is a generalization of Grover's algorithm that works with arbitrary
+        oracles Z and state preparation operators H. It amplifies amplitudes of
+        states marked by oracle Z after preparation by operator H.
+
+        The algorithm structure:
+        1. Unapply state preparation Z†
+        2. Initialize superposition
+        3. Repeat depth times:
+           - Apply state preparation H
+           - Unapply oracle Z†
+           - Apply diffusion operator Z0
+           - Apply oracle Z
+
+        Args:
+            Z: Oracle operator that marks target states
+            H: State preparation operator
+            qubits: List of qubit indices to operate on
+            depth: Number of amplitude amplification iterations
+
+        Note:
+            There's a bug in the original code where 'z' is used instead of 'Z'
+            in the name generation. This is preserved to maintain exact logic.
+        """
+        name = f'AmplAmp{len(qubits)}{Z.name}{depth}'
+
+        # Check if subroutine already exists
+        if name in self.gate_ref:
+            qubit_list = "{" + " ,".join(str(i) for i in qubits) + "}"
+            self.call_subroutine(name, [self.call_space.format(qubit_list)])
+            # Alternative gate-based call (currently commented out):
+            # self.call_gate(name, qubits[-1], qubits[:-1])
+            return
+
+        # Create new gate builder for defining the subroutine
+        gate_system = GateBuilder()
+        std_library = gate_system.import_library(std_gates)
+        oracle_z = gate_system.import_library(Z)
+        state_prep_h = gate_system.import_library(H)
+
+        # NOTE: Alternative gate-based implementations are commented out below.
+        # Multiple different approaches were tried during development.
+
+        # Alternative gate implementation attempt 1 (commented out):
+        # std_library.begin_gate(name, qargs)
+        # std_library.call_space = " {} "
+        # # Initial superposition
+        # [std_library.h(i) for i in qargs]
+        # # Amplitude amplification iteration
+        # std_library.begin_loop(depth)
+        # std_library.comment("Za")
+        # state_prep_h.apply(qargs)
+        # [std_library.h(i) for i in qargs]
+        # std_library.comment("Z0")
+        # [std_library.x(i) for i in qargs]
+        # std_library.controlled_op("cz", (qargs[-1], qargs[:-1]), n=len(qubits)-2)
+        # [std_library.x(i) for i in qargs]
+        # [std_library.h(i) for i in qargs]
+        # std_library.end_loop()
+        # std_library.end_gate()
+
+        # Alternative gate implementation attempt 2 (commented out):
+        # for _ in range(depth):
+        #     std_library.comment("Za")
+        #     oracle_z.apply(qargs)
+        #     [std_library.h(i) for i in qargs]
+        #     std_library.comment("Z0")
+        #     print((qargs[-1], qargs[:-1]))  # Debug print
+        #     std_library.controlled_op("cp", (qargs[-1], qargs[:-1]), n=len(qubits)-2)
+        #     [std_library.h(i) for i in qargs]
+
+        # Current subroutine-based implementation
+        register = "reg"
+        std_library.begin_subroutine(name, [f"qubit[{len(qubits)}] {register}"])
+
+        # Initial unapplication of oracle (inverse preparation)
+        oracle_z.unapply([f"reg[{i}]" for i in range(len(qubits))])
+
+        # Initialize superposition
+        std_library.h(register)
+
+        # Main amplitude amplification loop
+        std_library.begin_loop(depth)
+
+        # Apply state preparation operator
+        std_library.comment("H")
+        state_prep_h.apply([f"reg[{i}]" for i in range(len(qubits))])
+
+        # Unapply oracle (Z†)
+        std_library.comment("Zp*")
+        oracle_z.unapply([f"reg[{i}]" for i in range(len(qubits))])
+
+        # Apply diffusion operator (same as Grover)
+        std_library.comment("Z0")
+        std_library.x(register)
+        std_library.controlled_op(
+            "z",
+            (f"{register}[0]", [f"{register}[{i}]" for i in range(len(qubits) - 1)]),
+            n=len(qubits) - 1
+        )
+        std_library.x(register)
+
+        # Reapply oracle (Z)
+        std_library.comment("Zp")
+        oracle_z.apply([f"reg[{i}]" for i in range(len(qubits))])
+
+        std_library.end_loop()
+        std_library.end_subroutine()
+
+        # Build and merge the subroutine
+        self.merge(*gate_system.build(), name)
+
+        # Call the created subroutine
+        # Alternative gate-based call (commented out):
+        # self.call_gate(name, qubits[-1], qubits[:-1])
+        qubit_list = "{" + " ,".join(str(i) for i in qubits) + "}"
+        self.call_subroutine(name, [self.call_space.format(qubit_list)])

qbraid_algorithms/__init__.py

@@ -0,0 +1,32 @@
+# 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.
+
+"""
+Module providing Bell's Inequality experiment implementation.
+
+Functions
+----------
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    load_program
+
+"""
+
+from .bells_inequality import load_program
+
+__all__ = [
+    "load_program",
+]