linalg bug fix & cython integration

.github/workflows/main.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11']
+        python-version: ['3.10', '3.11', '3.12']
 
     steps:
       - uses: actions/checkout@v4
@@ -33,7 +33,7 @@ jobs:
       - name: Upload built package
         uses: actions/upload-artifact@v4
         with:
-          name: built-package
+          name: built-package-${{ matrix.python-version }}
           path: dist/*.whl
 
   test:
@@ -54,7 +54,7 @@ jobs:
       - name: Download built package
         uses: actions/download-artifact@v4
         with:
-          name: built-package
+          name: built-package-${{ matrix.python-version }}
           path: dist
       - name: Install package wheel with extras
         run: |
@@ -70,4 +70,4 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: false
           files: ./build/coverage/coverage.xml
-          verbose: true
+          verbose: true

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# Cython build files
+src/pyqasm/accelerate/linalg.c
+
 # Distribution / packaging
 .Python
 build/
@@ -25,7 +28,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
-pyqasm/_version.py
+src/pyqasm/_version.py
 
 
 # PyInstaller

CHANGELOG.md

@@ -79,12 +79,17 @@ qubit[2] q1;
 qubit[2] q2;
 ```
 - Added definitions for various gates in `maps.py` and tests for qasm formatting functions of the qbraid-sdk ([#82](https://github.com/qBraid/pyqasm/pull/82), [#84](https://github.com/qBraid/pyqasm/pull/84))
+- Added `pyqasm.accelerate` module to hold `.pyx` files with Cython-based optimizations for computationally intensive functions  ([#83](https://github.com/qBraid/pyqasm/pull/83))
 
 ### Improved / Modified
 - Changed the `__init__` method for the `QasmModule` class to only accept an `openqasm3.ast.Program` object as input ([#71](https://github.com/qBraid/pyqasm/pull/71))
 - Changed `DepthNode`, `QubitDepthNode`, `ClbitDepthNode`, and `Variable` to dataclasses. `__repr__` method is therefore handled automatically and you don't need all of the redundant private / public attribute and setters ([#79](https://github.com/qBraid/pyqasm/pull/79))
 - Simplified `map_qasm_op_to_callable` redundant `KeyError` handling with loop ([#79](https://github.com/qBraid/pyqasm/pull/79))
 - The `load` function has been renamed to `loads` and `load` is now used to load a QASM file. `QasmModule.dumps()` has been replaced with `__str__` method ([#76](https://github.com/qBraid/pyqasm/pull/76))
+- Experimental Cython integration:  ([#83](https://github.com/qBraid/pyqasm/pull/83))
+    - Migrated `pyqasm.linalg._kronecker_factor` to `pyqasm.linalg_cy` with ~60% speedup
+    - Migrated `pyqasm.linalg._so4_to_so2()` to to `pyqasm.linalg_cy` with ~5% speedup
+- Changed source code directory from `./pyqasm` to `./src/pyqasm` to prevents conflicts between the local source directory and the installed package in site-packages, ensuring Python's module resolution prioritizes the correct version. Required for local testing with new Cython build step ([#83](https://github.com/qBraid/pyqasm/pull/83))
 
 ### Deprecated
 
@@ -94,11 +99,14 @@ qubit[2] q2;
 
 ### Fixed
 - Updated docs custom CSS used for sphinx to make version stable/latest drop-down visible. Previously was set white so blended into background and wasn't visible. ([#78](https://github.com/qBraid/pyqasm/pull/78))
+- Fixed bug in `pyqasm.linalg.so_bidiagonalize()` in final dot product order ([#83](https://github.com/qBraid/pyqasm/pull/83))
 
 ### Dependencies
 
 ## Past Release Notes
 
 Archive of changelog entries from previous releases:
 
+- [v0.0.3](https://github.com/qBraid/pyqasm/releases/tag/v0.0.3)
+- [v0.0.2](https://github.com/qBraid/pyqasm/releases/tag/v0.0.2)
 - [v0.0.1](https://github.com/qBraid/pyqasm/releases/tag/v0.0.1)

MANIFEST.in

@@ -1,5 +1,3 @@
-include *.txt *.md
-recursive-include docs *.rst *.py *.png *.ico *.txt
-recursive-include pyqasm *.py
-include pyqasm/py.typed
-prune docs/build/
+include README.md
+recursive-include src/pyqasm *.py *.pyx
+include src/pyqasm/py.typed

bin/create_dev_build.sh

@@ -13,7 +13,7 @@
 ################################################################################
 # Description:
 # Script for creating development package builds. It temporarily checks out
-# a new branch, modifies the `_version.py` file to reflect the provided
+# a new branch, modifies the `pyproject.toml` file to reflect the provided
 # development version, and then triggers the build process.
 #
 # Usage:
@@ -24,7 +24,7 @@
 #   OUT_DIR: The directory where the built packages will be stored.
 #
 # Example:
-#   ./create_dev_build.sh "1.0.0dev" "/path/to/output_directory"
+#   ./create_dev_build.sh "1.0.0-a1" "/path/to/output_directory"
 ################################################################################
 
 set -e
@@ -40,7 +40,7 @@ OUT_DIR="${2}"
 
 # Constants
 REPO_DIR=$(git rev-parse --show-toplevel)
-VERSION_FILE="${REPO_DIR}/pyqasm/_version.py"
+PYPROJECT_TOML_PATH="${REPO_DIR}/pyproject.toml"
 TMP_BRANCH="tmp_build_branch_$(date "+%Y%m%d%H%M%S")"
 
 # Cleanup function
@@ -49,11 +49,11 @@ cleanup() {
 
     # If the TMP_BRANCH exists, checkout the original branch and delete TMP_BRANCH
     if git rev-parse --verify "${TMP_BRANCH}" >/dev/null 2>&1; then
-        git checkout HEAD -- "${VERSION_FILE}" 2>/dev/null
+        git checkout HEAD -- "${PYPROJECT_TOML_PATH}" 2>/dev/null
         git checkout - 2>/dev/null
         git branch -D "${TMP_BRANCH}" 2>/dev/null
     else
-        git checkout HEAD -- "${VERSION_FILE}" 2>/dev/null
+        git checkout HEAD -- "${PYPROJECT_TOML_PATH}" 2>/dev/null
     fi
 }
 
@@ -70,9 +70,16 @@ fi
 echo "Creating and checking out temporary branch: ${TMP_BRANCH}"
 git checkout -b "${TMP_BRANCH}"
 
+# Check if toml-cli is installed
+if ! command -v toml &> /dev/null
+then
+    echo "toml-cli could not be found. Please install toml-cli to use this script."
+    exit 1
+fi
+
 # Update the version in the version file
 echo "Setting version to ${DEV_VERSION}"
-echo '__version__ = "'"${DEV_VERSION}"'"' > "${VERSION_FILE}"
+toml set "$PYPROJECT_TOML_PATH" "project.version" "$DEV_VERSION" > tmp.$$.toml && mv tmp.$$.toml "$PYPROJECT_TOML_PATH"
 
 # Check if `build` module is installed
 if ! python -c "import build" 2>/dev/null; then
@@ -84,4 +91,4 @@ fi
 echo "Building the project..."
 python -m build --outdir "${OUT_DIR}"
 
-echo "Done."
+echo "Done."

docs/index.rst

@@ -91,7 +91,7 @@ Example
 
 .. code-block:: python
 
-   import pyqasm
+   from pyqasm import loads, dumps
 
    qasm = """
    OPENQASM 3;
@@ -118,10 +118,10 @@ Example
    result = measure q;
    """
 
-   module = pyqasm.loads(qasm)
-   module.unroll()
+   program = loads(qasm)
+   program.unroll()
 
-   unrolled_qasm = pyqasm.dumps(module)
+   unrolled_qasm = dumps(program)
 
    print(unrolled_qasm)
 

examples/README.md

@@ -3,9 +3,9 @@
 ### Program Unrolling
 
 ```python
-import pyqasm 
+from pyqasm import loads, dumps
 
-program = """
+qasm = """
 OPENQASM 3;
 include "stdgates.inc";
 
@@ -30,9 +30,9 @@ bit[4] result;
 result = measure q;
 """
 
-qasm_module = pyqasm.loads(program)
-qasm_module.unroll()
-print(pyqasm.dumps(qasm_module))
+module = loads(qasm)
+module.unroll()
+print(dumps(module))
 ```
 
 ```text
@@ -66,7 +66,7 @@ result[3] = measure q[3];
 ### Program Validation
 
 ```python
-import pyqasm
+from pyqasm import loads
 
 program = """
 OPENQASM 3;
@@ -81,7 +81,9 @@ h q[2];
 c = measure q;
 """
 
-pyqasm.loads(program).validate()
+module = loads(program)
+
+module.validate()
 ```
 
 ```text

examples/unroll_example.py

@@ -15,9 +15,9 @@
 
 """
 
-import pyqasm
+from pyqasm import dumps, loads
 
-qasm_program = """
+qasm = """
 // A program containing the Deutsch-Josza algorithm in OpenQASM 3
 OPENQASM 3;
 include "stdgates.inc";
@@ -70,7 +70,8 @@ def deutsch_jozsa(qubit[N] q_func, qubit[1] ancilla_q) {
 result = measure q;
 """
 
-qasm_module = pyqasm.loads(qasm_program)
-qasm_module.unroll()
+program = loads(qasm)
 
-print(pyqasm.dumps(qasm_module))
+program.unroll()
+
+print(dumps(program))

examples/validate_example.py

@@ -15,9 +15,9 @@
 
 """
 
-import pyqasm
+from pyqasm import loads
 
-qasm_program = """
+qasm = """
 OPENQASM 3;
 include "stdgates.inc";
 
@@ -84,4 +84,6 @@ def generic_operation(qubit[N] q) {
 c = measure q;
 """
 
-pyqasm.loads(qasm_program).validate()
+program = loads(qasm)
+
+program.validate()

pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=61", "setuptools_scm"]
+requires = ["setuptools>=74.1", "setuptools_scm", "Cython>=3.0", "numpy"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyqasm"
-version = "0.0.3"
+version = "0.1.0-alpha"
 description = "Python toolkit providing an OpenQASM 3 semantic analyzer and utilities for program analysis and compilation."
 authors = [{name = "qBraid Development Team"}, {email = "[email protected]"}]
 readme = "README.md"
@@ -44,11 +44,20 @@ lint = ["black", "isort", "pylint", "mypy", "qbraid-cli>=0.8.5"]
 docs = ["sphinx>=7.3.7,<8.2.0", "sphinx-autodoc-typehints>=1.24,<2.6", "sphinx-rtd-theme>=2.0.0,<4.0.0", "docutils<0.22", "sphinx-copybutton"]
 
 [tool.setuptools_scm]
-write_to = "pyqasm/_version.py"
+write_to = "src/pyqasm/_version.py"
+
+[tool.setuptools.package-data]
+pyqasm = ["py.typed", "*.pyx"]
+
+[tool.setuptools]
+packages = {find = {where = ["src"]}}
+ext-modules = [
+  {name = "pyqasm.accelerate.linalg", sources = ["src/pyqasm/accelerate/linalg.pyx"], include-dirs = ["numpy"]}
+]
 
 [tool.black]
 line-length = 100
-target-version = ["py310", "py311", "py312"]
+target-version = ["py310", "py311", "py312", "py313"]
 
 [tool.isort]
 profile = "black"
@@ -65,6 +74,7 @@ testpaths = ["tests"]
 [tool.coverage.run]
 source = ["pyqasm"]
 omit = ["**/pyqasm/_version.py"]
+relative_files = true
 
 [tool.coverage.report]
 show_missing = true

src/pyqasm/accelerate/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (C) 2024 qBraid
+#
+# This file is part of pyqasm
+#
+# Pyqasm is free software released under the GNU General Public License v3
+# or later. You can redistribute and/or modify it under the terms of the GPL v3.
+# See the LICENSE file in the project root or <https://www.gnu.org/licenses/gpl-3.0.html>.
+#
+# THERE IS NO WARRANTY for pyqasm, as per Section 15 of the GPL v3.
+
+"""
+Module providing Cython-based optimizations for computationally intensive functions.
+
+.. currentmodule:: pyqasm.accelerate
+
+"""