time evolution + detuning dev (#20)

time evolution + detuning dev
qBraid · Jul 11, 2024 · f53337b · f53337b
2 parents 0eaa20d + 09c95af
commit f53337b
Show file tree

Hide file tree

Showing 20 changed files with 363 additions and 577 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,9 @@
  <a href="https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml">
  <img src="https://github.com/qBraid/qbraid-algorithms/actions/workflows/main.yml/badge.svg?branch=main" alt="CI"/>
  </a>
+ <a href="https://codecov.io/gh/qBraid/qbraid-algorithms"> 
+ <img src="https://codecov.io/gh/qBraid/qbraid-algorithms/graph/badge.svg?token=7jYcnneDys"/>
+ </a>
  <a href="https://pypi.org/project/qbraid-algorithms/">
  <img src="https://img.shields.io/pypi/v/qbraid-algorithms.svg?color=blue" alt="PyPI version"/>
  </a>

diff --git a/docs/_static/cards/jupyter.png b/docs/_static/cards/jupyter.png
diff --git a/docs/_static/cards/python.png b/docs/_static/cards/python.png
diff --git a/docs/_static/cards/terminal.png b/docs/_static/cards/terminal.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -8,7 +8,7 @@
 
 import qbraid_algorithms
 
-project = "qbraid-algorithms"
+project = "qBraid"
 copyright = "2024, qBraid Development Team"
 author = "qBraid Development Team"
 
@@ -25,6 +25,7 @@
  "sphinx.ext.autodoc",
  "sphinx_autodoc_typehints",
  "sphinx.ext.autosummary",
+ "sphinx_copybutton"
 ]
 
 autodoc_mock_imports = ["torchvision"]

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,3 @@
-Documentation
-==============
-
 .. raw:: html
 
  <html>
@@ -49,47 +46,57 @@ Documentation
  </head>
  <body>
  <h1 style="text-align: center">
- <img src="_static/logo.png" alt="qbraid logo" style="width:50px;height:50px;">
+ <img src="_static/logo.png" alt="qbraid logo" style="width:60px;height:60px;">
  <span> qBraid</span>
- <span style="color:#808080"></span>
+ <span style="color:#808080"> | algorithms</span>
  </h1>
  <p style="text-align:center;font-style:italic;color:#808080">
- A cloud-based platform for quantum computing.
+ Build hybrid quantum-classical algorithms with qBraid.
  </p>
- <div class="row">
- <div class="column">
- <a href="https://docs.qbraid.com/projects/lab/en/latest/lab/overview.html">
- <div class="card">
- <h3>Lab</h3>
- <img src="_static/cards/jupyter.png" alt="terminal" style="width:60px;height:60px;">
- </div>
- </a>
- </div>
-
- <div class="column">
- <a href="https://docs.qbraid.com/projects/cli/en/latest/guide/overview.html">
- <div class="card">
- <h3>CLI</h3>
- <img src="_static/cards/terminal.png" alt="terminal" style="width:60px;height:60px;">
- </div>
- </a>
- </div>
-
- <div class="column">
- <a href="https://docs.qbraid.com/en/latest/sdk/overview.html">
- <div class="card">
- <h3>SDK</h3>
- <img src="_static/cards/python.png" alt="terminal" style="width:60px;height:60px;">
- </div>
- </a>
- </div>
- </div>
-
  </body>
  </html>
 
 |
 
+:Release: |release|
+
+Overview
+---------
+
+Python package for building, simulating, and benchmarking hybrid quantum-classical algorithms.
+
+
+Installation
+-------------
+
+qbraid-algorithms requires Python 3.9 or greater, and can be installed with pip as follows:
+
+.. code-block:: bash
+
+ pip install qbraid-algorithms
+
+
+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:
+
+.. code-block:: bash
+
+ git clone https://github.com/qBraid/qbraid-algorithms.git
+ cd qbraid-algorithms
+ pip3 install .
+
+
+Resources
+----------
+
+- `User Guide <https://docs.qbraid.com/algorithms/user-guide>`_
+- `Example Notebooks <https://github.com/qBraid/qbraid-algorithms/tree/main/examples>`_
+- `API Reference <https://sdk.qbraid.com/projects/algorithms/en/stable/api/qbraid_algorithms.html>`_
+
+|
+
 .. toctree::
  :maxdepth: 1
  :caption: API Reference

diff --git a/examples/sandbox/README.md b/examples/sandbox/README.md
@@ -0,0 +1,3 @@
+# qBraid-Algorithms Developer Sandbox
+
+This sandbox directory is provided as a collaborative and temporary space where contributors can freely share experimental notebooks and early-stage code. Its main purpose is to increase transparency about ongoing work, thus enhancing collaboration. Feel free to push your notebooks and code frequently, regardless of their completeness or correctness. This directory will be removed with the release of version 0.1 of the `qbraid-algorithms` project.
diff --git a/pyproject.toml b/pyproject.toml
@@ -29,7 +29,7 @@ dependencies = ["torch>=2.3.0,<3.0", "numpy>=1.17,<2.1", "scipy~=1.13.1", "bloqa
 
 [project.urls]
 Homepage = "https://github.com/qBraid/qbraid-algorithms"
-Documentation = "https://docs.qbraid.com/en/stable/"
+Documentation = "https://docs.qbraid.com"
 "Bug Tracker" = "https://github.com/qBraid/qbraid-algorithms/issues"
 Discord = "https://discord.gg/TPBU2sa8Et"
 "Launch on Lab" = "https://account.qbraid.com/?gitHubUrl=https://github.com/qBraid/qbraid-algorithms.git"
@@ -38,7 +38,7 @@ Discord = "https://discord.gg/TPBU2sa8Et"
 visualization = ["matplotlib"]
 test = ["pytest", "pytest-cov"]
 lint = ["isort", "ruff", "qbraid-cli"]
-docs = ["sphinx~=7.3.7", "sphinx-autodoc-typehints>=1.24,<2.3", "sphinx-rtd-theme~=2.0.0", "docutils<0.22"]
+docs = ["sphinx~=7.3.7", "sphinx-autodoc-typehints>=1.24,<2.3", "sphinx-rtd-theme~=2.0.0", "docutils<0.22", "sphinx-copybutton"]
 
 [tool.setuptools_scm]
 write_to = "qbraid_algorithms/_version.py"
@@ -67,7 +67,7 @@ exclude = '''
 
 [tool.pylint.'MESSAGES CONTROL']
 max-line-length = 100
-disable = "W0108, W0511, W0401, R0902"
+disable = "W0108,W0511,W0401,R0902,R0903,R0913"
 
 [tool.pylint.MASTER]
 ignore-paths = [

diff --git a/qbraid_algorithms/qrc/__init__.py b/qbraid_algorithms/qrc/__init__.py
@@ -19,10 +19,31 @@
 
  QRCModel
  MagnusExpansion
+ DetuningLayer
+ MagnusExpansion
+ AnalogProgramEvolver
+
+Functions
+----------
+
+.. autosummary::
+ :toctree: ../stubs/
+
+ one_hot_encoding
+ pca_reduction
 
 """
 
-from .magnus import MagnusExpansion
-from .model import QRCModel
+from .encoding import one_hot_encoding, pca_reduction
+from .magnus_expansion import MagnusExpansion
+from .qrc_model import DetuningLayer, QRCModel
+from .time_evolution import AnalogProgramEvolver
 
-__all__ = ["QRCModel", "MagnusExpansion"]
+__all__ = [
+ "QRCModel",
+ "MagnusExpansion",
+ "DetuningLayer",
+ "AnalogProgramEvolver",
+ "one_hot_encoding",
+ "pca_reduction",
+]
diff --git a/qbraid_algorithms/qrc/dynamics.py b/qbraid_algorithms/qrc/dynamics.py
diff --git a/qbraid_algorithms/qrc/encoding.py b/qbraid_algorithms/qrc/encoding.py
@@ -9,12 +9,11 @@
 # THERE IS NO WARRANTY for the qBraid-SDK, as per Section 15 of the GPL v3.
 
 """
-Module for encoding of data.
+Module for encoding of classical data.
 
 """
 import numpy as np
 import torch
-from sklearn.preprocessing import OneHotEncoder
 
 
 def one_hot_encoding(labels: np.ndarray, train: bool = True) -> torch.Tensor:
@@ -28,10 +27,52 @@ def one_hot_encoding(labels: np.ndarray, train: bool = True) -> torch.Tensor:
  torch.Tensor: The one-hot encoded matrix where each row corresponds to a label.
 
  """
+ # pylint: disable-next=import-outside-toplevel
+ from sklearn.preprocessing import OneHotEncoder
+
  encoder = OneHotEncoder(sparse_output=False)
  reshaped_data = labels.reshape(-1, 1)
  if train:
  encoded_data = encoder.fit_transform(reshaped_data)
  else:
  encoded_data = encoder.transform(reshaped_data)
  return encoded_data
+
+
+def pca_reduction(
+ data: torch.Tensor,
+ n_components: int,
+ data_dim: int,
+ delta_max: int,
+ train: bool = True,
+) -> torch.Tensor:
+ """
+ Perform PCA reduction on the provided data using PyTorch's pca_lowrank to
+ reduce its dimensionality.
+
+ Args:
+ data (torch.Tensor): The input data tensor where each row represents a sample.
+ n_components (int): The number of principal components to retain.
+ data_dim (int): The dimension of the input data required for doing PCA.
+ delta_max (int): Scaling factor to bring PCA vals into a feasible range for local detuning.
+ train (bool, optional): Whether the data is training data. Defaults to True.
+
+ Returns:
+ torch.Tensor: The transformed data
+ """
+ # pylint: disable-next=import-outside-toplevel
+ from sklearn.decomposition import PCA
+
+ # Perform PCA on training data
+ pca = PCA(n_components=n_components)
+ data_array: np.ndarray = data.data.numpy()
+ data_reshaped = data_array.reshape(-1, data_dim)
+ if train:
+ data_pca = pca.fit_transform(data_reshaped)
+ else:
+ data_pca = pca.transform(data_reshaped)
+
+ # Scale PCA values to feasible range of local detuning
+ scaled_data_pca = data_pca / np.max(np.abs(data_pca)) * delta_max
+
+ return scaled_data_pca