Merge pull request #81 from BoxiLi/qutip-qip-0.1.X

Prepare the qutip-qip-0.1.1 release

.github/workflows/build.yml

@@ -0,0 +1,148 @@
+name: Build wheels, optionally deploy to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm_ref:
+        description: "Confirm chosen branch name to deploy to PyPI (optional):"
+        default: ""
+      override_version:
+        description: "Override version number (optional):"
+        default: ""
+
+
+jobs:
+  # The deploy_test job is part of the test of whether we should deploy to PyPI.
+  # The job will succeed if either the confirmation reference is empty or if the
+  # confirmation is the selected branch or tag name.  It will fail if it is
+  # nonempty and does not match.  All later jobs depend on this job, so that
+  # they will be immediately cancelled if the confirmation is bad.  The
+  # dependency is currently necessary (2021-03) because GitHub Actions does not
+  # have a simpler method of cancelling an entire workflow---the normal use-case
+  # expects to try and run as much as possible despite one or two failures.
+  deploy_test:
+    name: Verify PyPI deployment confirmation
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_REF: ${{ github.ref }}
+      CONFIRM_REF: ${{ github.event.inputs.confirm_ref }}
+    steps:
+      - name: Compare confirmation to current reference
+        shell: bash
+        run: |
+          [[ -z $CONFIRM_REF || $GITHUB_REF =~ ^refs/(heads|tags)/$CONFIRM_REF$ ]]
+          if [[ -z $CONFIRM_REF ]]; then
+            echo "Build only.  Nothing will be uploaded to PyPI."
+          else
+            echo "Full build and deploy.  Wheels and source will be uploaded to PyPI."
+          fi
+
+
+  build_sdist:
+    name: Build sdist on Ubuntu
+    needs: deploy_test
+    runs-on: ubuntu-latest
+    env:
+      OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          # For the sdist we should be as conservative as possible with our
+          # Python version.  This should be the lowest supported version.  This
+          # means that no unsupported syntax can sneak through.
+          python-version: '3.6'
+
+      - name: Install pip build
+        run: |
+          python -m pip install 'build'
+
+      - name: Build sdist tarball
+        shell: bash
+        run: |
+          if [[ ! -z "$OVERRIDE_VERSION" ]]; then echo "$OVERRIDE_VERSION" > VERSION; fi
+          # The build package is the reference PEP 517 package builder.  All
+          # dependencies are specified by our setup code.
+          python -m build --sdist .
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+
+  build_wheels:
+    name: Build wheels
+    needs: deploy_test
+    runs-on: ubuntu-latest
+    env:
+      OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          # This is about the build environment, not the released wheel version.
+          python-version: '3.7'
+
+      - name: Install pip build
+        run: |
+          python -m pip install 'build'
+
+      - name: Build wheels
+        shell: bash
+        run: |
+          # If the version override was specified, then write it the VERSION
+          # file with it.
+          if [[ ! -z "$OVERRIDE_VERSION" ]]; then echo "$OVERRIDE_VERSION" > VERSION; fi
+          # The build package is the reference PEP 517 package builder.  All
+          # dependencies are specified by our setup code.
+          python -m build --wheel --outdir wheelhouse .
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: wheels
+          path: ./wheelhouse/*.whl
+          if-no-files-found: error
+
+
+  deploy:
+    name: "Deploy to PyPI if desired"
+    # The confirmation is tested explicitly in `deploy_test`, so we know it is
+    # either a missing confirmation (so we shouldn't run this job) or a valid
+    # confirmation.  We don't need to retest the value of the confirmation,
+    # beyond checking that one existed.
+    if: ${{ github.event.inputs.confirm_ref != '' }}
+    needs: [deploy_test, build_sdist, build_wheels]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download build artifacts to local runner
+        uses: actions/download-artifact@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.7'
+
+      - name: Verify this is not a dev version
+        shell: bash
+        run: |
+          python -m pip install wheels/*.whl
+          python -c 'import qutip_qip; print(qutip_qip.__version__); assert "dev" not in qutip_qip.__version__; assert "+" not in qutip_qip.__version__'
+
+      - name: Upload sdist and wheels to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+          TWINE_NON_INTERACTIVE: 1
+          TWINE_REPOSITORY: pypi
+        run: |
+          python -m pip install "twine"
+          python -m twine upload --verbose wheels/*.whl sdist/*.tar.gz

.github/workflows/build_documentation.yml

@@ -0,0 +1,46 @@
+name: Build HTML documentation
+
+on:
+  [push, pull_request]
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.8'
+
+      - name: Install documentation dependencies
+        run: |
+          python -mpip install -r doc/requirements.txt
+
+      - name: Install qutip-qip from GitHub
+        run: |
+          python -mpip install -e .[full]
+          # Install in editable mode so it doesn't matter if we import from
+          # inside the installation directory, otherwise we can get some errors
+          # because we're importing from the wrong location.
+          python -c 'import qutip_qip; print("QuTiP QIP Version:      %s" % qutip_qip.__version__)'
+          python -c 'import qutip; qutip.about()'
+
+      - name: Build documentation
+        working-directory: doc
+        run: |
+          make html SPHINXOPTS="-W --keep-going -T"
+          # Above flags are:
+          #   -W : turn warnings into errors
+          #   --keep-going : do not stop after the first error
+          #   -T : display a full traceback if a Python exception occurs
+
+      - name: Upload built files
+        uses: actions/upload-artifact@v2
+        with:
+          name: qutip_qip_html_docs
+          path: doc/_build/html/*
+          if-no-files-found: error

.github/workflows/test.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [ master ]
   pull_request:
-    branches: [ master ]
 
 jobs:
   test:
@@ -32,7 +31,7 @@ jobs:
 
   doctest:
     runs-on: ubuntu-latest
-        
+
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python
@@ -43,9 +42,14 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install numpy scipy cython sphinx matplotlib numpydoc sphinx_rtd_theme
-        pip install git+https://github.com/qutip/qutip.git
+        pip install qutip
         pip install .
-    - name: Test with pytest
+    - name: Test code snippets in the documentation
       run: |
-        cd docs
+        cd doc
         make doctest
+    - name: Test code examples for the pulse paper
+      run: |
+        python -m pip install joblib pytest pytest-custom_exit_code
+        cd doc/pulse-paper
+        pytest *.py --suppress-no-test-exit-code

.gitignore

@@ -71,7 +71,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -2,14 +2,14 @@
 
 version: 2
 
-# Build from the docs/ directory with Sphinx
+# Build from the doc/ directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: doc/source/conf.py
 
 # Explicitly set the version of Python and its requirements
 python:
   version: 3.8
   install:
-    - requirements: docs/requirements.txt
+    - requirements: doc/requirements.txt
     - method: pip
       path: .

README.md

@@ -2,6 +2,8 @@
 
 [![build](https://github.com/qutip/qutip-qip/workflows/Tests/badge.svg)](https://github.com/qutip/qutip-qip/actions)
 [![Documentation Status](https://readthedocs.org/projects/qutip-qip/badge/?version=latest)](https://qutip-qip.readthedocs.io/en/latest/)
+[![PyPI version](https://badge.fury.io/py/qutip-qip.svg)](https://badge.fury.io/py/qutip-qip)
+[![arXiv paper](https://img.shields.io/badge/arXiv-2105.09902-<COLOR>.svg)](https://arxiv.org/abs/2105.09902)
 
 The qutip-qip package used to be a module ``qutip.qip`` under [QuTiP (Quantum Toolbox in Python)](http://qutip.org/index.html).
 From QuTiP 5.0, the community has decided to decrease the size of the core QuTiP package by reducing the external dependencies, in order to simplify maintenance.
@@ -14,25 +16,42 @@ The package offers two different approaches for simulating quantum circuits, one
 
 If you would like to know the future development plan and ideas, have a look at the [discussion panel](https://github.com/qutip/qutip-qip/discussions) as well as the [qutip documentation for ideas](https://github.com/qutip/qutip-doc/tree/master/development/ideas).
 
-Installation
-------------
-To install the package, download to source code and run
+Quick start
+-----------
+To install the package, use
 ```
-pip install qutip_qip
+pip install qutip-qip
 ```
 
-If you want to edit the source code, please download the source code and run the following command under the folder with `setup.cfg`
+Migrating from ``qutip.qip``
+--------------------------
+As the introduction suggested, this package is based on a module in the [QuTiP](http://qutip.org/docs/latest/) package `qutip.qip`.
+If you were using the `qutip` package and now want to try out the new features included in this package, you can simply install this package and replace all the `qutip.qip` in your import statement with `qutip_qip`. Everything should work smoothly as usual.
+
+Documentation and tutorials
+-------------
+
+The documentation of `qutip-qip` updated to the latest development version is hosted at [qutip-qip.readthedocs.io/](https://qutip-qip.readthedocs.io/en/latest/).
+Tutorials related to using quantum gates and circuits in `qutip-qip` can be found [*here*](https://qutip.org/tutorials#quantum-information-processing) and those related to using noise simulators areavailable at [*this link*](https://qutip.org/tutorials#nisq). 
+
+Code examples used in the preprint [*Pulse-level noisy quantum circuits with QuTiP*](https://arxiv.org/abs/2105.09902), updated for the latest code version, are hosted in [this folder](https://github.com/qutip/qutip-qip/tree/master/doc/pulse-paper).
+
+Installation from source
+------------------------
+If you want to edit the source code, please download the source code and run the following command under the root `qutip-qip` folder,
 ```
+pip install --upgrade pip
 pip install -e .
 ```
+which makes sure that you are up to date with the latest `pip` version. Contribution guidelines are available [*here*](https://qutip-qip.readthedocs.io/en/latest/contribution-code.html). 
 
 To build and test the documentation, additional packages need to be installed:
 
 ```
-pip install matplotlib sphinx numpydoc sphinx_rtd_theme
+pip install pytest matplotlib sphinx numpydoc sphinx_rtd_theme
 ```
 
-Under the `docs` directory, use
+Under the `doc` directory, use
 ```
 make html
 ```
@@ -42,18 +61,26 @@ make doctest
 ```
 to test the code in the documentation.
 
-Documentation
--------------
-
-The documentation of `qutip-qip` updated to the latest development version is hosted at [qutip-qip.readthedocs.io/](https://qutip-qip.readthedocs.io/en/latest/).
-
 Testing
 ------------
 To test the installation from a download of the source code, run from the `qutip-qip` directory
 ```
-    pytest tests
+pytest tests
+```
+Citing `qutip-qip`
+------------
+If you use `qutip-qip` in your research, the  [*preprint*](https://arxiv.org/abs/2105.09902) can be cited as
+
+```bibtex
+@misc{li2021pulselevel,
+      title={Pulse-level noisy quantum circuits with QuTiP},
+      author={Boxi Li and Shahnawaz Ahmed and Sidhant Saraogi and Neill Lambert and Franco Nori and Alexander Pitchford and Nathan Shammah},
+      year={2021},
+      eprint={2105.09902},
+      archivePrefix={arXiv},
+      primaryClass={quant-ph}
+}
 ```
-
 Support
 -------
 This package is supported and maintained by the same developers group as QuTiP.

VERSION

@@ -0,0 +1 @@
+0.1.1

docs/Makefile → doc/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/make.bat → doc/make.bat

@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
+set BUILDDIR=_build
 
 if "%1" == "" goto help
 

doc/pulse-paper/README.md

@@ -0,0 +1,15 @@
+This folder contains code examples used in the publication [*Pulse-level noisy quantum circuits with QuTiP*](https://arxiv.org/abs/2105.09902). To run the examples, please first install the software package qutip-qip
+```
+pip install qutip_qip[full] joblib
+```
+All examples are self-contained and running the code should reproduce the plots used in the paper.
+
+The following table summarizes the sections in the paper and the corresponding code examples:
+
+| Section | Code example |
+| ----------- | ----------- |
+| Appendix A | `pulse_simulation.py` |
+| Appendix B | `dj_algorithm.py` |
+| Fig.4 and Appendix C | `customize.py` |
+| Fig.5 in Section 4 | `decoherence.py` |
+| Appendix D | `deutsch_jozsa.qasm` and `deutsch_jozsa-qasm.py` |