Refactor documentation and improve clarity across multiple modules

Author: vinayswamik

qbraid_algorithms/bernstein_vazirani/bernvaz.py

@@ -33,11 +33,10 @@ def generate_program(bitstring: Union[str, list[int]]) -> QasmModule:
     Load the Bernstein-Vazirani circuit as a pyqasm module.
 
     Args:
-        bitstring (Union[str, list[int]]): The hidden bitstring `s` as a string of '0's
-        and '1's
+        bitstring (Union[str, list[int]]): The hidden bitstring `s` as a string of '0's and '1's
 
     Returns:
-        (PyQasm Module) pyqasm module containing the Bernstein-Vazirani circuit
+        PyQASM module containing the Bernstein-Vazirani circuit
     """
 
     # Load the Bernstein-Vazirani QASM files into a staging directory

qbraid_algorithms/iqft/__init__.py

@@ -53,7 +53,7 @@
         1 & 1 & 1 & \\cdots & 1 \\\\
         1 & \\omega_n^{-1} & \\omega_n^{-2} & \\cdots & \\omega_n^{-(2^n-1)} \\\\
         \\vdots & \\vdots & \\vdots & \\ddots & \\vdots \\\\
-        1 & \\omega_n^{-(2^n-1)} & \\omega_n^{-2(2^n-1)} & \\cdots & \\omega_n^{-(2^n-1)^2}
+        1 & \\omega_n^{-(2^n-1)} & \\omega_n^{-2(2^n-1)} & \\cdots & \\omega_n^{-(2^n-1)(2^n-1)}
         \\end{pmatrix}`
 
 

qbraid_algorithms/qft/qft.py

@@ -13,21 +13,8 @@
 # limitations under the License.
 
 """
-Quantum Fourier Transform (QFT) Algorithm Implementation
+Quantum Fourier Transform (QFT) Algorithm Interface
 
-This module provides a complete implementation of the Quantum Fourier Transform,
-a fundamental building block for many quantum algorithms.
-
-The QFT transforms quantum states from the computational basis to the Fourier basis
-by applying Hadamard gates and controlled phase rotations. It's essential for
-algorithms like Shor's algorithm and quantum phase estimation, providing the
-quantum analogue of the classical discrete Fourier transform.
-
-Formulation:
-    The QFT transforms a quantum state |j⟩ to |ψ⟩ = 1/√N Σₖ₌₀^(N-1) e^(2πijk/N)|k⟩
-    where N = 2ⁿ for n qubits. The circuit implements this using Hadamard gates H
-    and controlled phase rotations R_k with phase φ = 2π/2^k. The total circuit
-    depth is O(n²) with O(n²) gates.
 """
 import os
 import shutil
@@ -45,6 +32,7 @@
 def generate_program(num_qubits: int) -> QasmModule:
     """
     Load the Quantum Fourier Transform circuit as a pyqasm module.
+
     Args:
         num_qubits (int): The number of qubits for the QFT.
 

qbraid_algorithms/qft/qft_lib.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """
-Quantum Fourier Transform (QFT) Algorithm Implementation
+Quantum Fourier Transform (QFT) Library Implementation
 
 """
 

qbraid_algorithms/qpe/phase_est.py

@@ -32,8 +32,8 @@
 class PhaseEstimationLibrary(GateLibrary):
     """
     Library to implement phase estimation circuits directly related to classical
-    phase estimation algorithms. Iterative phase estimation will be supported via
-    the Rodeo package. This library supports both static and time-dependent Hamiltonians.
+    phase estimation algorithms.
+
     """
 
     def __init__(self, *args, **kwargs):

qbraid_algorithms/qtran/gate_library.py

@@ -22,11 +22,12 @@
 built to inject definitions into whatever FileBuilder class it is connected to.
 
 Key (Base) Features:
-- Gate application with controls and phases
-- Measurements and classical bit operations
-- Control flow (loops, conditionals)
-- Gate and subroutine definitions
-- Code generation and scope management
+
+    - Gate application with controls and phases
+    - Measurements and classical bit operations
+    - Control flow (loops, conditionals)
+    - Gate and subroutine definitions
+    - Code generation and scope management
 
 Class Extensions:
 - std_gates
@@ -41,11 +42,12 @@ class GateLibrary:
 
     Core class for quantum gate operations and circuit building.
     Provides fundamental operations for:
-    - Gate application with controls and phases
-    - Measurements and classical bit operations
-    - Control flow (loops, conditionals)
-    - Gate and subroutine definitions
-    - Code generation and scope management
+
+        - Gate application with controls and phases
+        - Measurements and classical bit operations
+        - Control flow (loops, conditionals)
+        - Gate and subroutine definitions
+        - Code generation and scope management
 
     """
 
@@ -210,10 +212,11 @@ def begin_loop(self, iterator, ident: str = "i"):
         LOOPS
 
         Start a loop block with various iteration patterns:
-        - int: for int i in [0:n]
-        - (start, end): for int i in [start:end]
-        - (start, step, end): for int i in [start:end:step]
-        - string: custom loop syntax
+
+            - int: for int i in [0:n]
+            - (start, end): for int i in [start:end]
+            - (start, step, end): for int i in [start:end:step]
+            - string: custom loop syntax
 
         Args:
             iterator: Loop specification (int, tuple, or string)
@@ -432,9 +435,10 @@ class std_gates(GateLibrary):
     Implementation of std_lib quantum gates following OpenQASM 3.0 standards.
 
     Available Gates:
-    - Single-qubit: phase, x, y, z, h, s, sdg, sx
-    - Two-qubit: cx, cy, cz, cp, crx, cry, crz, swap
-    - Multi-qubit: ccx (Toffoli), cswap (Fredkin)
+
+        - Single-qubit: phase, x, y, z, h, s, sdg, sx
+        - Two-qubit: cx, cy, cz, cp, crx, cry, crz, swap
+        - Multi-qubit: ccx (Toffoli), cswap (Fredkin)
     """
 
     # Standard gate set from OpenQASM 3.0 specification

qbraid_algorithms/qtran/module_loader.py

@@ -38,8 +38,9 @@ def qasm_pipe(func: Callable) -> Callable:
     then writes the function's (file_name, program_string) output to a .qasm file.
 
     The decorated function should:
-    1. Accept 'path' and 'quiet' as keyword arguments
-    2. Return a tuple of (file_name, program_string)
+
+        1. Accept 'path' and 'quiet' as keyword arguments
+        2. Return a tuple of (file_name, program_string)
 
     The decorator will create a file named "{file_name}.qasm" and write the program_string to it.
     """

qbraid_algorithms/qtran/qasm_builder.py

@@ -22,16 +22,17 @@
 structure/semantics requirements unique to each file
 
 Key Features:
-- Automatic scope and indentation management
-- Library import and gate definition tracking
-- Multiple output formats (QASM circuits, includes, gate definitions)
-- Resource allocation for qubits and classical bits
-- Extensible design for custom quantum libraries
+
+    - Automatic scope and indentation management
+    - Library import and gate definition tracking
+    - Multiple output formats (QASM circuits, includes, gate definitions)
+    - Resource allocation for qubits and classical bits
+    - Extensible design for custom quantum libraries
 
 Class Extensions:
-- GateBuilder
-- QasmBuilder
-- IncludeBuilder
+    - GateBuilder
+    - QasmBuilder
+    - IncludeBuilder
 """
 
 
@@ -44,23 +45,25 @@ class FileBuilder:
     for specialized builders that generate different types of OpenQASM output.
 
     The FileBuilder maintains several key data structures:
-    - imports: List of library files to include
-    - gate_defs: Dictionary mapping gate names to their definitions
-    - gate_refs: List of available gate names for validation
-    - program: Accumulated program code with proper indentation
-    - scope: Current nesting level for proper code formatting
+
+        - imports: List of library files to include
+        - gate_defs: Dictionary mapping gate names to their definitions
+        - gate_refs: List of available gate names for validation
+        - program: Accumulated program code with proper indentation
+        - scope: Current nesting level for proper code formatting
     """
 
     def __init__(self):
         """
         Initialize the base file builder with empty data structures.
 
         Sets up the foundational components needed for code generation:
-        - Empty import list for library dependencies
-        - Empty gate definitions dictionary for custom gates
-        - Empty gate references list for scope validation
-        - Empty program string for accumulating generated code
-        - Zero scope level for proper indentation tracking
+
+            - Empty import list for library dependencies
+            - Empty gate definitions dictionary for custom gates
+            - Empty gate references list for scope validation
+            - Empty program string for accumulating generated code
+            - Zero scope level for proper indentation tracking
         """
         self.imports = []  # List of library names to import (e.g., "std_gates.inc")
         self.gate_defs = {}  # Dictionary mapping gate names to definition strings
@@ -125,9 +128,10 @@ class GateBuilder(FileBuilder):
     complete circuit structure.
 
     Use cases:
-    - Creating custom gate libraries
-    - Generating reusable quantum subroutines
-    - Building modular quantum components
+
+        - Creating custom gate libraries
+        - Generating reusable quantum subroutines
+        - Building modular quantum components
     """
 
     def import_library(self, lib_class, annotated=False):
@@ -168,12 +172,13 @@ class QasmBuilder(FileBuilder):
     resource allocation and generates standards-compliant OpenQASM code.
 
     Features:
-    - Automatic OpenQASM version header generation
-    - Qubit and classical bit resource management
-    - Dynamic resource allocation with claim methods
-    - Complete circuit structure generation
-    - Library import management
-    - Gate definition embedding
+
+        - Automatic OpenQASM version header generation
+        - Qubit and classical bit resource management
+        - Dynamic resource allocation with claim methods
+        - Complete circuit structure generation
+        - Library import management
+        - Gate definition embedding
     """
 
     def __init__(self, qubits, clbits=None, version=3):
@@ -256,11 +261,12 @@ def build(self):
         Generate the complete OpenQASM circuit code.
 
         Assembles all components into a valid OpenQASM program including:
-        1. Version header (OPENQASM 3;)
-        2. Include statements for imported libraries
-        3. Qubit and classical bit declarations
-        4. Custom gate definitions
-        5. Main program code
+
+            1. Version header (OPENQASM 3;)
+            2. Include statements for imported libraries
+            3. Qubit and classical bit declarations
+            4. Custom gate definitions
+            5. Main program code
 
         Returns:
             str: Complete OpenQASM program ready for execution
@@ -319,10 +325,11 @@ class IncludeBuilder(FileBuilder):
     subroutines but do not include qubit declarations or main program logic.
 
     Include files are useful for:
-    - Sharing gate definitions across multiple circuits
-    - Creating domain-specific gate libraries
-    - Modular quantum program development
-    - Standardizing common quantum operations
+
+        - Sharing gate definitions across multiple circuits
+        - Creating domain-specific gate libraries
+        - Modular quantum program development
+        - Standardizing common quantum operations
     """
 
     def build(self):