Refactor: Restructure qBraid-Algorithms, update docs, and fix functionality

.github/ISSUE_TEMPLATE/algorithm-implementation.md

@@ -8,8 +8,8 @@ assignees: ''
 ---
 
 **Required functions to implement:**
-- [ ] `load_program()` - Load complete executable circuit
-- [ ] `generate_subroutine()` - Generate reusable subroutine
+- [ ] `generate_program()` - Load complete executable circuit
+- [ ] `save_to_qasm()` - Generate reusable subroutine
 - [ ] Additional functions: _______________
 
 **CLI integration needed:**

README.md

@@ -65,12 +65,12 @@ 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:
+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:
 
 ```python
 from qbraid_algorithms import qft
 
-qft_module = qft.load_algorithm(3) # Load QFT for 3 qubits
+qft_module = qft.generate_program(3) # Load QFT for 3 qubits
 ```
 
 Now, you can perform operations with the PyQASM module, such as unrolling, and
@@ -84,15 +84,15 @@ 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
+`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:
 
 ```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
+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
 
 ```
 
@@ -101,7 +101,7 @@ To utilize the generated subroutine in your own circuit, include the generated
 when generating the subroutine. For example, after running
 
 ```python
-qft.generate_subroutine(4)
+qft.save_to_qasm(4)
 ```
 
 you can append `include "qft.qasm";` to your OpenQASM file, and call the

docs/_static/css/custom.css

@@ -17,15 +17,11 @@
   --font-color4: #ffffff;
   --brand-color0: #46096f;
   --brand-color1: #df0982;
-  --active-gradient0: linear-gradient(
-    45deg,
-    var(--brand-color1),
-    var(--brand-color0)
-  );
-  --active-gradient1: linear-gradient(
-    rgb(135, 0, 202) -41.11%,
-    rgba(216, 164, 250, 0.92) 197.13%
-  );
+  --active-gradient0: linear-gradient(45deg,
+      var(--brand-color1),
+      var(--brand-color0));
+  --active-gradient1: linear-gradient(rgb(135, 0, 202) -41.11%,
+      rgba(216, 164, 250, 0.92) 197.13%);
 }
 
 .wy-body-for-nav {
@@ -44,14 +40,14 @@
   color: var(--font-color0);
 }
 
-.wy-side-nav-search > a {
+.wy-side-nav-search>a {
   color: var(--font-color0);
   display: flex;
   align-items: center;
   justify-content: center;
 }
 
-.wy-side-nav-search > a::before {
+.wy-side-nav-search>a::before {
   content: "";
   background-image: url(../logo.png);
   background-size: contain;
@@ -64,7 +60,7 @@
   color: var(--font-color2) !important;
 }
 
-.wy-menu-vertical li.current > a,
+.wy-menu-vertical li.current>a,
 .wy-menu-vertical li.on a {
   background-image: var(--active-gradient0);
   background-size: 150%;
@@ -73,14 +69,14 @@
   transition: background-position 150ms ease;
 }
 
-.wy-menu-vertical li.current > a:hover,
+.wy-menu-vertical li.current>a:hover,
 .wy-menu-vertical li.on a:hover {
   background-image: var(--active-gradient0);
   background-size: 150%;
   background-position: right;
 }
 
-.wy-menu-vertical li.current > a:hover button.toctree-expand,
+.wy-menu-vertical li.current>a:hover button.toctree-expand,
 .wy-menu-vertical li.on a:hover button.toctree-expand {
   color: var(--font-color3);
 }
@@ -104,7 +100,7 @@
 }
 
 /* headers */
-.rst-content .toctree-wrapper > p.caption,
+.rst-content .toctree-wrapper>p.caption,
 h1,
 h2,
 h3,
@@ -117,12 +113,22 @@ legend {
   color: var(--brand-color0);
 }
 
+
+/* Style h1 headers only on API and stubs pages */
+html[data-content_root="../"] h1 {
+  opacity: 0.5 !important;
+  color: #000000 !important;
+  font-size: 100% !important;
+  font-weight: normal !important;
+  font-style: italic !important;
+}
+
 .wy-menu-vertical header,
 .wy-menu-vertical p.caption {
   color: var(--brand-color0);
 }
 
-.wy-menu-vertical li.current > a button.toctree-expand,
+.wy-menu-vertical li.current>a button.toctree-expand,
 .wy-menu-vertical li.on a button.toctree-expand {
   color: var(--font-color4);
 }
@@ -137,7 +143,7 @@ legend {
   transition: transform 150ms ease;
 }
 
-.card > h3 {
+.card>h3 {
   color: var(--font-color0);
 }
 
@@ -221,17 +227,6 @@ legend {
   font-family: "Source Sans Pro", sans-serif;
 }
 
-/* Foot note */
-.rst-content .seealso .admonition-title {
-  background: var(--active-gradient0);
-}
-
-.rst-content .seealso {
-  background: var(--layout-color0);
-  border-radius: 8px;
-  overflow: hidden;
-}
-
 /* common elements */
 .rst-content p a {
   -webkit-text-fill-color: transparent;
@@ -241,7 +236,7 @@ legend {
   background-clip: text;
 }
 
-.wy-breadcrumbs > li.wy-breadcrumbs-aside > a {
+.wy-breadcrumbs>li.wy-breadcrumbs-aside>a {
   -webkit-text-fill-color: transparent;
   text-fill-color: transparent;
   background: var(--active-gradient0);
@@ -267,3 +262,125 @@ a .rst-content tt {
   -webkit-text-fill-color: var(--brand-color0);
   text-fill-color: var(--brand-color0);
 }
+
+/* =============================================================================
+   ADMONITION BOXES STYLING
+   ============================================================================= */
+
+/* Shared border radius for enhanced elements */
+.rst-content .note-enhanced,
+.rst-content .seealso,
+.rst-content .seealso table.autosummary {
+  border-radius: 10px;
+}
+
+/* Note Enhanced Boxes */
+.rst-content .note-enhanced {
+  font-size: 1.5em;
+  background: white;
+  box-shadow: 0 4px 18px rgba(70, 9, 111, 0.50);
+}
+
+.rst-content .note-enhanced .admonition-title {
+  border-radius: 10px 10px 0 0;
+  background: var(--active-gradient0);
+  color: #ffffff !important;
+  font-weight: bold;
+  text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.8);
+  padding: 12px 16px;
+}
+
+.rst-content .note-enhanced .admonition-title::before {
+  display: none !important;
+}
+
+/* Seealso Boxes */
+.rst-content .seealso {
+  font-size: 1.1em;
+  background: white;
+  box-shadow: 0 4px 18px rgba(70, 9, 111, 0.50);
+}
+
+/* Reduce line spacing in formulation sections */
+.rst-content .seealso p {
+  margin-bottom: 0.5em;
+  line-height: 1.3;
+}
+
+.rst-content .seealso ol,
+.rst-content .seealso ul {
+  margin-bottom: 0.5em;
+}
+
+.rst-content .seealso li {
+  margin-bottom: 0.3em;
+  line-height: 1.3;
+}
+
+.rst-content .seealso .math {
+  margin: 0.2em 0;
+  line-height: 1.2;
+}
+
+.rst-content .seealso .admonition-title {
+  border-radius: 10px 10px 0 0;
+  padding-top: 16px;
+  background: white;
+  color: var(--brand-color0) !important;
+  font-weight: bold;
+}
+
+.rst-content .seealso.note-enhanced-size .admonition-title::before,
+.rst-content .left-box .admonition-title::before,
+.rst-content .right-box .admonition-title::before {
+  display: none !important;
+}
+
+.rst-content .seealso.note-enhanced-size>.admonition-title {
+  font-weight: bold;
+  text-align: center;
+}
+
+/* Tables */
+.rst-content .seealso table.autosummary {
+  border-collapse: separate;
+  border-spacing: 0;
+  border-width: 2px !important;
+}
+
+/* =============================================================================
+   SIDE-BY-SIDE ALGORITHM LAYOUT
+   ============================================================================= */
+
+/* Container Layout */
+.side-by-side {
+  display: flex;
+}
+
+.left-box,
+.right-box {
+  flex-direction: column;
+}
+
+/* Algorithm Boxes */
+.rst-content .left-box .note,
+.rst-content .right-box .note {
+  background: white !important;
+  overflow: hidden !important;
+}
+
+/* Algorithm Titles */
+.left-box .admonition-title,
+.right-box .admonition-title {
+  text-align: center;
+  font-size: 1em !important;
+}
+
+/* =============================================================================
+   PAGE-SPECIFIC FIXES
+   ============================================================================= */
+
+/* Hide duplicate title on all qbraid_algorithms submodule pages */
+section[id^="module-qbraid_algorithms."]>p:first-of-type {
+  display: none;
+}

docs/conf.py

@@ -25,7 +25,7 @@
     "sphinx.ext.autodoc",
     "sphinx_autodoc_typehints",
     "sphinx.ext.autosummary",
-    "sphinx_copybutton"
+    "sphinx_copybutton",
 ]
 
 autodoc_mock_imports = ["qbraid", "pyqasm"]
@@ -52,4 +52,4 @@
 html_favicon = "_static/favicon.ico"
 html_show_sphinx = False
 
-html_css_files = ["css/s4defs-roles.css"]
+html_css_files = ["css/s4defs-roles.css", "css/custom.css"]

docs/index.rst

@@ -51,7 +51,7 @@
       <span style="color:#808080"> | algorithms</span>
    </h1>
    <p style="text-align:center;font-style:italic;color:#808080">
-      Use and build quantum algorithms with qBraid.
+      Build Quantum Algorithms with qBraid.
    </p>
    </body>
    </html>
@@ -61,10 +61,21 @@
 :Release: |release|
 
 Overview
----------
+--------
 
-Python package for utilizing, implementing, and building quantum algorithms in OpenQASM 3.
+`qBraid Algorithms <https://docs.qbraid.com/qbraid-algorithms/user-guide/overview>`_ is a Python package designed for quantum algorithm development, implementation, and execution. Built on the `OpenQASM3 <https://openqasm.com/>`_ standard, this library provides researchers, developers, and quantum computing enthusiasts with a robust toolkit for exploring and deploying quantum algorithms across various domains.
 
+**Key Features:**
+
+* **Comprehensive Algorithm Library**: Implementation of fundamental quantum algorithms including Grover's search, Quantum Fourier Transform (QFT), Quantum Phase Estimation (QPE), and advanced techniques like amplitude amplification and Hamiltonian evolution.
+
+* **OpenQASM 3 Integration**: Native support for OpenQASM 3, enabling seamless integration with modern quantum hardware and simulators while maintaining compatibility with the evolving quantum computing ecosystem.
+
+* **Modular Architecture**: Clean, modular design that allows for easy extension, customization, and integration into existing quantum computing workflows.
+
+* **Research-Ready Implementation**: Optimized for both educational purposes and cutting-edge research, with implementations suitable for near-term quantum devices (NISQ era) and fault-tolerant quantum computers.
+
+* **Hardware Agnostic**: Designed to work across different quantum computing platforms and simulators, providing flexibility in deployment and testing.
 
 Installation
 -------------
@@ -77,7 +88,7 @@ qbraid-algorithms requires Python 3.11 or greater, and can be installed with pip
 
 
 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: