Release 0.3 (#22)

* Update tests to conform with new qml.matrix argument requirements. * Create python-package.yml * Update python-package.yml * Update python-package.yml * Update python-package.yml * Update python-package.yml * Auto-format with black * Update python-package.yml * Start linting * Add pylintrc file * Continue linting files. Reorganize identity hunter. * Add linting to workflow * Update linting workflow * Add new linted files * Finish linting * Disable pylint on import order * Disable pylint wrong import order * Fix error * Update docstring * Update black to only check. * Try caching * Fix spacing * Pin PennyLane version * Break formatting to test CI * Fix formatting * Added pyproject.toml so that black lines 100 is set as default. * Pin pylint versions and fix issues in identity hunter * Add missing version * Track dependencies with Poetry * Try running CI with poetry build * Update lock file and pyproject.toml * Fix yaml file * convert tabs to spaces :( * add pre-commit to dependencies * remove unnecessary requirements files * Add pre-commit hooks. Convert CI to use ruff instead of pylint and black * Delete unused config files * Update preconfig * Update PennyLane version and Poetry lock file * Add documentation with readthedocs (#23) * Add readthedocs yaml file * Add rst files for sphinx documentation. Adjust some docstrings to conform. * Restructuring documentation files so web-based docs can be built. * Rename docs directory * Fix path in conf.py file * Update readthedocs yaml to use poetry * Update poetry lock file * Revert change to python version. * Add MS gate matrix example. Convert all docstrings to raw strings. * Restructure docs files. Add instructions and basic usage. * Update lock file * Fix math rendering in many docs * Clarify docs for identity hunter. * Fix formatting in docs * Fix formatting in docs * Formatting fix * Example for commute_through_ms_gates * Examples for virtualize_rz_gates and single_qubit_fusion_gpi * Update convert_to_gpi and add example * Add inverse cancellation pass * Example for ionize transform * Hide more contents of identity hunter module. Small text tweaks. * Example for lookup gate identity * Finish documenting utils. Update a JSON parameter based on new API. * Fix typo * Remove transform utils from docs. Fix tests for new API * Restructure identity hunter module * Run precommit hooks * Try enabling source linking * Remove attempted source link --------- Co-authored-by: Olivia Di Matteo <[email protected]> * Add equivalence checking mechanism to transforms and tests (#24) * Add equivalence checking mechanism to transforms and tests * Relocate equivalence checker. Add a test suite for it. * Add description of equivalence checking to docs. * Push changes to basic usage section. * Remove print statements from tests * Glassnotes/21 update readme for release 03 (#25) * Example for flag_non_equivalence utility function * Update README to reflect new instructions * Fix formatting of links in README * Add docs badge to README * Remove broken badge. --------- Co-authored-by: glassnotes <[email protected]> Co-authored-by: Olivia Di Matteo <[email protected]> Co-authored-by: Gabriel Bottrill <[email protected]> Co-authored-by: Gabriel Bottrill <[email protected]>
QSAR-UBC · Aug 24, 2024 · d862117 · d862117
1 parent 83e10a5
commit d862117
Show file tree

Hide file tree

Showing 31 changed files with 2,887 additions and 497 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main", "rc-0.*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip poetry
+          poetry --version
+          poetry install
+      - name: Check linting and formatting with ruff
+        run: |
+          poetry run ruff check ionizer/*.py tests/*.py
+      - name: Test with pytest
+        run: |
+          poetry run pytest tests/test_*.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,83 @@
+# To run all pre-commit checks, use:
+#
+#     pre-commit run -a
+#
+# To install pre-commit hooks that run every time you commit:
+#
+#     pre-commit install
+#
+# This file was constructed based on an example file provided by our friends
+# at TUM Chair for Design Automation - thanks!
+
+ci:
+  autoupdate_commit_msg: "update pre-commit hooks"
+  autofix_commit_msg: "pre-commit fixes"
+
+repos:
+  # Standard hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.6.0"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  # Handling unwanted unicode characters
+  - repo: https://github.com/sirosen/texthooks
+    rev: "0.6.6"
+    hooks:
+      - id: fix-ligatures
+      - id: fix-smartquotes
+
+  # Check for common mistakes
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  # Check for spelling
+  - repo: https://github.com/codespell-project/codespell
+    rev: "v2.3.0"
+    hooks:
+      - id: codespell
+
+  # Format configuration files with prettier
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v4.0.0-alpha.8"
+    hooks:
+      - id: prettier
+        types_or: [yaml, markdown, html, css, javascript, json]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.9
+    hooks:
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+        types_or: [python, pyi, jupyter]
+      - id: ruff-format
+        types_or: [python, pyi, jupyter]
+
+  # Also run Black on examples in the documentation
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.16.0
+    hooks:
+      - id: blacken-docs
+        additional_dependencies: [black==24.*]
+
+  # Catch common capitalization mistakes
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: PyBind|Numpy|Github|PyTest|Pennylane
+        exclude: .pre-commit-config.yaml
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
+
+sphinx:
+  configuration: docs/conf.py
diff --git a/README.md b/README.md
@@ -2,16 +2,17 @@
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10761367.svg)](https://doi.org/10.5281/zenodo.10761367)
 
-Transpile and optimize your [PennyLane](https://github.com/pennylaneai/pennylane) circuits into
+Transpile and optimize your PennyLane circuits into
 IonQ's native trapped-ion gate set (GPI, GPI2, MS) with just a single extra line
 of code!
 
 ```python
 from ionizer.transforms import ionize
 
+
 @qml.qnode(dev)
 @ionize
-def circuit(x): 
+def circuit(x):
     qml.Hadamard(wires=0)
     qml.CNOT(wires=[0, 1])
     qml.RX(x, wires=1)
@@ -21,61 +22,62 @@ def circuit(x):
 ```pycon
 >>> qml.draw(circuit)(0.3)
 0: ──GPI2(0.00)─╭MS──GPI2(-1.57)─────────────────────────┤  <Z>
-1: ──GPI2(3.14)─╰MS──GPI2(1.57)───GPI(-1.42)──GPI2(1.57)─┤     
+1: ──GPI2(3.14)─╰MS──GPI2(1.57)───GPI(-1.42)──GPI2(1.57)─┤
 ```
 
-
 ## Installation
 
-Requirements:
- * PennyLane >= 0.33
 
-The Ionizer is not currently available via a package manager. To install, clone the repository and run
+The Ionizer is available via PyPI:
 
 ```
-python -m pip install .
+pip install ionizer
 ```
 
-or
+The core requirement is [PennyLane](https://pennylane.ai/) 0.37.
 
-```
-python setup.py install
-```
+Python versions 3.10-3.12 are supported and tested against.
 
-If you need to run Ionizer with a version of PennyLane between 0.29 and 0.32,
-please use version 0.1.2 of the package.
+To install from source, clone this repository and use
+[Poetry](https://python-poetry.org/) to install the dependencies listed in the
+`pyproject.toml` file.
 
 ## Examples
 
+For more detailed explanations and usage examples, please check the full
+online documentation.
+
 The Ionizer is implemented using [quantum function
 transforms](https://arxiv.org/abs/2202.13414), similar to PennyLane's [existing
 compilation
 tools](https://docs.pennylane.ai/en/stable/introduction/compiling_circuits.html). To
 compile and execute the circuit using trapped ion gates, the
-``@ionize`` decorator  performs the following steps:
+`@ionize` transform will
 
- * Decomposes all operations into Paulis/Pauli rotations, Hadamard, and CNOT 
- * Merges all single-qubit rotations
- * Converts everything except RZ to GPI/GPI2/MS gates (`@ionizer.transforms.convert_to_gpi`)
- * Virtually applies all RZ gates (`@ionizer.transforms.virtualize_rz_gates`)
- * Repeatedly applies gate fusion and commutation through MS gates which performs simplification based on some circuit identities (`@ionizer.transforms.single_qubit_fusion_gpi` and `@ionizer.transforms.commute_through_ms_gates`)
+ - Decompose all operations into Paulis/Pauli rotations, Hadamard, and CNOT
+ - Cancel inverses and merge single-qubit rotations
+ - Convert everything except RZ to GPI, GPI2, and MS gates
+ - Virtually apply RZ gates
+ - Repeatedly apply single-qubit gate fusion and commutation through MS gates,
+   and perform simplification based on a database of circuit identities.
 
 ```python
 from ionizer.transforms import ionize
 
+
 @qml.qnode(dev)
 @ionize
 def circuit_ionized(params):
     for idx in range(5):
         qml.Hadamard(wires=idx)
-        
+
     for idx in range(4):
         qml.RY(params[idx], wires=idx)
-        qml.CNOT(wires=[idx+1, idx])
-        
+        qml.CNOT(wires=[idx + 1, idx])
+
     for wire in dev.wires:
         qml.PauliX(wires=wire)
-        
+
     return qml.expval(qml.PauliX(0))
 ```
 
@@ -97,43 +99,53 @@ tensor(0.99500417, requires_grad=True)
 
 ```
 
-Note that while this comes packaged together as the ``@ionize`` transform, the
-individual transforms can also be accessed and used independently.
+The consistuent transforms can also be accessed and used independently.
 
-There is currently not direct support for other frameworks. However, if you would like to do this with a Qiskit circuit, it can be accomplished as follows through the [`pennylane-qiskit`](https://github.com/PennyLaneAI/pennylane-qiskit) package.
+There is currently not direct support for other frameworks. However, if you
+would like to apply the transforms to Qiskit circuits, this can be accomplished
+using the
+[`pennylane-qiskit`](https://github.com/PennyLaneAI/pennylane-qiskit) package as
+shown belown.
 
 ```python
 qiskit_circuit = QuantumCircuit(...)
 
 # Turns a Qiskit circuit into a PennyLane quantum function
 qfunc = qml.from_qiskit(qiskit_circuit)
 
+
 @qml.qnode(dev)
 @ionize
 def pennylane_circuit():
     qfunc()
     return qml.expval(qml.PauliX(0))
 ```
 
-
 ## Notes
 
 This package is a work in progress. While it has been verified to work on some
 fairly large circuits, we still need to work on:
- * finding circuit identities involving the 2-qubit gate
- * improving the documentation and usage instructions
- * ensuring differentiability of variational parameters
- * writing more tests (compile at your own risk!)
 
+- finding circuit identities involving the 2-qubit gate
+- ensuring differentiability of variational parameters
+- writing more tests (compile at your own risk!)
 
 ## Resources
 
- * [IonQ documentation](https://ionq.com/docs/getting-started-with-native-gates)
- * [Basic circuit compilation techniques for an ion-trap quantum machine](https://arxiv.org/abs/1603.07678)
-
- ## Citing
+- [IonQ documentation](https://ionq.com/docs/getting-started-with-native-gates)
+- [Basic circuit compilation techniques for an ion-trap quantum machine](https://arxiv.org/abs/1603.07678)
+
+
+## Contributing
+
+The Ionizer is available open source under the MIT License.  Contributions are
+welcome. Please open an issue if you are interested in contributing, or if you
+encounter a bug.
+
+
+## Reference
 
- If you use the Ionizer as part of your workflow, we would appreciate if you cite it using the BibTeX below.
+If you use the Ionizer as part of your workflow, we would appreciate if you cite it using the BibTeX below.
 
 ```
 @software{di_matteo_2024_10761367,

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/api/decompositions.rst b/docs/api/decompositions.rst
@@ -0,0 +1,7 @@
+.. _decompositions:
+
+Decompositions of trapped-ion native gates
+==========================================
+
+.. automodule:: ionizer.decompositions
+   :members:
diff --git a/docs/api/identity_hunter.rst b/docs/api/identity_hunter.rst
@@ -0,0 +1,5 @@
+Circuit identity generation
+===========================
+
+.. automodule:: ionizer.identity_hunter
+   :members:
diff --git a/docs/api/ops.rst b/docs/api/ops.rst
@@ -0,0 +1,5 @@
+Operations
+==========
+
+.. automodule:: ionizer.ops
+   :members:
diff --git a/docs/api/transforms.rst b/docs/api/transforms.rst
@@ -0,0 +1,11 @@
+Compilation transforms
+======================
+
+.. automodule:: ionizer.transforms
+   :members:
+
+   .. automethod:: ionizer.transforms.ionize
+   .. automethod:: ionizer.transforms.commute_through_ms_gates
+   .. automethod:: ionizer.transforms.virtualize_rz_gates
+   .. automethod:: ionizer.transforms.single_qubit_fusion_gpi
+   .. automethod:: ionizer.transforms.convert_to_gpi
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
@@ -0,0 +1,5 @@
+Utility functions
+=================
+
+.. automodule:: ionizer.utils
+   :members: