Release 0.1.0 (#353)

Author: oschusler

.devcontainer/Dockerfile

@@ -10,7 +10,7 @@ RUN apt-get update -y && \
     apt-get clean
 
 # Set up user
-ARG USER=vscode
+ARG USER=pydev
 ENV PATH /home/${USER}/.local/bin:$PATH
 RUN groupadd -r ${USER} && \
     useradd -m -r -s /bin/bash -g ${USER} ${USER} && \

.devcontainer/devcontainer.json

@@ -3,8 +3,8 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"USER": "vscode"
+			"USER": "pydev"
 		}
 	},
-	"remoteUser": "vscode"
+	"remoteUser": "pydev"
 }

.github/workflows/release.yaml

@@ -0,0 +1,56 @@
+name: Releases
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "release-*"
+  release:
+    types:
+      - created
+
+jobs:
+  publish:
+    name: Publish assets
+    runs-on: "ubuntu-latest"
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@master
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v3
+        with:
+          poetry-version: "1.8.3"
+
+      # Setting the proper version
+      - name: Get previous Tag
+        if: contains(github.ref, 'refs/heads/release-')
+        id: previous_tag
+        uses: WyriHaximus/github-action-get-previous-tag@v1
+        with:
+          fallback: 0.1.0
+      - name: Set Build version
+        if: contains(github.ref, 'refs/heads/release-')
+        run: poetry version "${{ steps.previous_tag.outputs.tag }}.dev${{ github.run_number }}"
+      - name: Set Release version
+        if: github.event_name == 'release' && github.event.action == 'created'
+        run: poetry version ${{ github.ref_name }}
+
+      # Build package
+      - name: Build poetry package
+        run: poetry build
+
+      # Publishing the package
+      - name: Publish distribution 📦 to Test PyPI
+        if: contains(github.ref, 'refs/heads/release-')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verbose: true
+      - name: Publish distribution 📦 to PyPI
+        if: github.event_name == 'release' && github.event.action == 'created'
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yaml

@@ -13,17 +13,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.11"
       - name: Install poetry
-        uses: abatilo/actions-poetry@v2
+        uses: abatilo/actions-poetry@v3
         with:
           poetry-version: "1.3.2"
       - name: Install tox
         run: pip install tox
       - name: run tox lint and type
-        run: tox -e lint #,type
+        run: tox -e lint,type
   unit-test:
     name: Unit testing
     needs: lint
@@ -35,7 +35,6 @@ jobs:
           - macos-latest
           - windows-latest
         python-version:
-          - "3.8"
           - "3.9"
           - "3.10"
           - "3.11"
@@ -44,11 +43,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install poetry
-        uses: abatilo/actions-poetry@v2
+        uses: abatilo/actions-poetry@v3
         with:
           poetry-version: "1.3.2"
       - name: Install tox

.gitignore

@@ -68,15 +68,16 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
+# MkDocs documentation
+site/
 
 # PyBuilder
 .pybuilder/
 target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
+example/tutorials/.ipynb_checkpoints
 
 # IPython
 profile_default/
@@ -127,6 +128,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+venv38/
 
 # Spyder project settings
 .spyderproject
@@ -153,6 +155,7 @@ dmypy.json
 cython_debug/
 
 # PyCharm
+.idea/
 #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+We recommend working on a feature branch and pull request from there.
+
+## Requirements
+
+- `poetry`,
+- `PyCharm` (recommended).
+
+## Creating a feature branch
+
+Make sure your environment contains all the updated versions of the dependencies.
+
+From an OpenSquirrel checkout:
+
+```
+$ poetry shell
+$ poetry install
+```
+
+And that you base your feature branch off an updated `develop`.
+
+From a `poetry` shell (started from an OpenSquirrel checkout):
+
+```
+$ git checkout develop
+$ git fetch origin
+$ git pull
+$ git branch <feature branch name>
+```
+
+## Before creating the pull request
+
+Make sure the tests and the following linters pass.
+From a `poetry` shell (started from an OpenSquirrel checkout):
+
+```
+$ poetry run pytest . -vv
+$ poetry run ruff check --fix
+$ poetry run ruff format
+$ poetry run mypy opensquirrel --strict
+```
+
+## Setting the Python interpreter (PyCharm)
+
+You can choose the Python interpreter from the `poetry` environment.
+
+- Go to `Settings` > `Project: OpenSquirrel` > `Python Interpreter`.
+- Click on `Add Interpeter`, and then select `Add Local Interpreter`.
+- Select `Poetry Environment`, and then `Existing environment`.
+- Click on `...` to navigate to the `Interpreter` binary.
+
+## Running/Debugging tests (PyCharm)
+
+To run/debug all tests:
+
+- Right-click on the `test` folder of the Project tree.
+- Click `Run 'pytest' in test` or `Debug 'pytest' in test`.
+
+This will also create a `Run/Debug Configuration`.
+
+### Troubleshooting
+
+If breakpoints are not hit during debugging:
+
+- Go to `Run/Debug Configurations`.
+- Add `--no-cov` in the `Additional arguments` text box.
+
+This issue may be due to the code coverage module _hijacking_ the tracing mechanism
+(check [this link](https://stackoverflow.com/a/56235965/260313) for a more detailed explanation).

LICENSE renamed to LICENSE.md

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2023 Quantum Inspire: QuTech (TNO, TU Delft)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,4 +1,11 @@
-### Mini-compiler for Quantum Inspire's quantum chip[munks]
+# OpenSquirrel: a flexible quantum program compiler.
+
+![CI](https://github.com/QuTech-Delft/OpenSquirrel/actions/workflows/tests.yaml/badge.svg)
+[![pypi](https://img.shields.io/pypi/v/opensquirrel.svg)](https://pypi.org/project/opensquirrel/)
+[![image](https://img.shields.io/pypi/pyversions/opensquirrel.svg)](https://pypi.python.org/pypi/opensquirrel)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pytest](https://img.shields.io/badge/py-test-blue?logo=pytest)](https://github.com/pytest-dev/pytest)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 ```
  ,;;:;,
@@ -11,43 +18,133 @@
           ``'"`
 ```
 
-# Installation
+OpenSquirrel is a quantum compiler that chooses a _modular_, over a _configurable_,
+approach to prepare and optimize quantum circuits for heterogeneous target architectures.
+
+It has a user-friendly interface and is straightforwardly extensible with custom-made readers,
+compiler passes, and exporters.
+As a quantum circuit compiler,
+it is fully aware of the semantics of each gate and arbitrary quantum gates can be constructed manually.
+It supports the [cQASM](https://qutech-delft.github.io/cQASM-spec/latest/) quantum programming language,
+using [libQASM](https://github.com/QuTech-Delft/libqasm) as language parser.
+It is developed in modern Python and follows best practices.
+
+## Installation
 
-## General installation
+OpenSquirrel can be easily installed from PyPI.
+We recommend using a virtual environment (_e.g._, venv).
 
 ```shell
 $ pip install opensquirrel
 ```
 
-## Editable installation
+To install the dependencies to run the examples on `jupyter`, install:
 
-To perform an editable install, run the following command in the root directory of `OpenSquirrel` with the `-e` flag
 ```shell
-$ pip install -e .
+$ pip install opensquirrel[examples]
 ```
 
-To install the developer specific dependencies, run the command
-```shell
-$ pip install -e '.[dev]'
+## Getting started
+
+Once installed, the `opensquirrel` module can be imported accordingly:
+
+```python
+import opensquirrel
 ```
 
-# Documentation
+Essentially, compiling a quantum circuit in OpenSquirrel can be seen as a 3-stage process:
+1. Defining and building the quantum circuit using either the `CircuitBuilder` or from a cQASM string.
+2. Executing (multiple) compilation passes on the circuit,
+each traversing and modifying it (_e.g._, decomposition of the gates).
+3. Writing the circuit to cQASM or exporting it to a specific quantum circuit format.
+
+Here is an example of building a circuit using the `CircuitBuilder`:
 
-The package exposes only the `Circuit` class, whose up-to-date documentation is accessed:
+```python
+import math
+from opensquirrel.circuit_builder import CircuitBuilder
+from opensquirrel.ir import Qubit, Float
 
-- from the Python console:
-```pycon
->>> import opensquirrel
->>> help(opensquirrel.Circuit)
+# Initialize the builder and build your circuit
+builder = CircuitBuilder(qubit_register_size=1)
+builder.H(Qubit(0)).Z(Qubit(0)).Y(Qubit(0)).Rx(Qubit(0), Float(math.pi / 3))
+
+# Get the circuit from the circuit builder
+qc = builder.to_circuit()
 ```
 
-- from a Linux shell: `python3 -c "import opensquirrel; help(opensquirrel.Circuit)"`
+Alternatively, one can define the same circuit as a cQASM string:
 
-Currently there is also a set of default gates exposed as `opensquirrel.DefaultGates` to use in the `Circuit` constructor.
+```python
+cqasm_string = ("""
+    version 3.0
 
-# Testing
+    qubit q
 
-To run the tests, run the following command in the root directory of `OpenSquirrel`
-```shell
-$ pytest
+    H q
+    Z q
+    Y q
+    Rx(1.0471976) q
+""")
+
+from opensquirrel.circuit import Circuit
+qc = Circuit.from_string(cqasm_string)
+```
+
+The circuit can then be decomposed using a decomposition strategy.
+The different decomposition strategies can be found in the
+[examples](https://github.com/QuTech-Delft/OpenSquirrel/tree/develop/example/tutorials).
+In the example below, the circuit is decomposed using the Z-Y-Z decomposer.
+
+```python
+from opensquirrel.decomposer.aba_decomposer import ZYZDecomposer
+
+qc.decompose(decomposer=ZYZDecomposer())
+```
+
+Once the circuit is decomposed, it can be written back to cQASM.
+This is done by invoking the `writer` class, as can be seen below.
+
+```python
+from opensquirrel.writer import writer
+
+writer.circuit_to_string(qc)
 ```
+
+The output is then given by the following cQASM string:
+
+    version 3.0
+
+    qubit[1] q
+
+    Rz(3.1415927) q[0]
+    Ry(1.5707963) q[0]
+    Rz(3.1415927) q[0]
+    Ry(3.1415927) q[0]
+    Rz(1.5707963) q[0]
+    Ry(1.0471976) q[0]
+    Rz(-1.5707963) q[0]
+
+> __*Note*__: The cQASM writer is the standard writer of OpenSquirrel.
+> This means that the string representation of the `Circuit` object is by default a cQASM string. Moreover, simply printing the `Circuit` object will result in its cQASM string representation.
+
+## Documentation
+
+The [OpenSquirrel documentation](https://QuTech-Delft.github.io/OpenSquirrel/) is hosted through GitHub Pages.
+
+
+## Contributing
+
+The contribution guidelines and set up can be found
+[here](https://github.com/QuTech-Delft/OpenSquirrel/blob/develop/CONTRIBUTING.md).
+
+
+## Licensing
+
+OpenSquirrel is licensed under the Apache License, Version 2.0. See
+[LICENSE](https://github.com/QuTech-Delft/OpenSquirrel/blob/master/LICENSE.md) for the full license text.
+
+
+## Authors
+
+Quantum Inspire: [support@quantum-inspire.com](mailto:"support@quantum-inspire.com")