Main branch update (gcolab, 2 extra notebooks)

CHANGELOG.md

@@ -12,8 +12,6 @@ This file documents the main changes between versions of the code.
 - iQCC ansatz for VQE
 - IonQConnection class and notebook, to facilitate experiments through IonQ's API
 - FCISolver active space selection / frozen orbitals: restrictions for half-empty orbitals
-- HybridOperator for speedup for QubitOperator on certain operations in stabilizer notation
-- Support for symmetry in pyscf computations
 
 ### Changed
 

Dockerfile

@@ -1,13 +1,17 @@
 FROM fedora:30
 
+# Fundamentals
+# ============
 RUN dnf -y update
 RUN dnf -y install wget libgomp openblas-devel pandoc
 RUN dnf clean all
 
 # Python, C/C++ compilers, git
+# ============================
 RUN dnf -y install gcc redhat-rpm-config gcc-c++ python3-devel make cmake git
 
 # Set up a virtual environment, set all calls to pip3 and python3 to use it
+# =========================================================================
 RUN pip3 install virtualenv
 ENV VIRTUAL_ENV=/root/env
 RUN virtualenv -p python3 $VIRTUAL_ENV
@@ -17,26 +21,22 @@ RUN more /root/.bashrc
 RUN echo "export PATH=$PATH" >> /root/.bashrc
 
 # Python packages for documentation, Jupyter notebook support and visualization
+# =============================================================================
 RUN pip3 install --upgrade pip
-RUN pip3 install h5py==2.9.0 ipython jupyter setuptools wheel sphinx py3Dmol sphinx_rtd_theme nbsphinx scikit-build
-
-# Copy and set root directory,
-ENV PYTHONPATH=/root/tangelo:$PYTHONPATH
-WORKDIR /root/
-COPY . /root
+RUN pip3 install ipython jupyter setuptools wheel sphinx py3Dmol sphinx_rtd_theme nbsphinx scikit-build
 
 # Install Tangelo and its immediate dependencies (pyscf, openfermion, ...)
-RUN python3 /root/setup.py install
+# ========================================================================
 
-# Install Microsoft QDK qsharp package
-WORKDIR /tmp/
-RUN dnf clean all
-RUN rpm --import https://packages.microsoft.com/keys/microsoft.asc
-RUN wget -q -O /etc/yum.repos.d/microsoft-prod.repo https://packages.microsoft.com/config/fedora/30/prod.repo
-RUN dnf install -y dotnet-sdk-3.1
-RUN dotnet tool install -g Microsoft.Quantum.IQSharp
-RUN /root/.dotnet/tools/dotnet-iqsharp install --user
-RUN pip3 install qsharp
-
-# Install other simulators
-RUN pip install amazon-braket-sdk qiskit qulacs projectq
+# > Option 1: install from pypi
+RUN pip3 install tangelo-gc
+
+# > Option 2: install from locally mounted Tangelo, in the docker container
+# ENV PYTHONPATH=/root/tangelo:$PYTHONPATH
+# WORKDIR /root/
+# COPY . /root
+# RUN python3 -m pip install .
+
+# OPTIONAL: common dependencies (quantum circuit simulator and quantum cloud services)
+# ====================================================================================
+ RUN pip3 install cirq amazon-braket-sdk qiskit qulacs projectq

README.rst

@@ -61,20 +61,23 @@ This package requires a Python 3 environment. We recommend:
 * installing the "dev" version of Python3 if you encounter missing header errors, such as ``python.h file not found``.
 * having good C/C++ compilers and BLAS libraries to ensure good overall performance of computation-intensive code.
 
+
+
 Using pip
 ^^^^^^^^^
 
-The easiest way to install Tangelo in your environment. We recommend upgrading pip first:
+The easiest way to install Tangelo in your local environment. We recommend upgrading pip first:
 
 .. code-block::
 
    python -m pip install -–upgrade pip.
    pip install tangelo-gc
 
+
 From source, using setuptools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This package can be installed locally by copying the contents of this repository to any machine.
+This package can be installed locally by copying the contents of this repository to any machine. This can be useful if you need a bit more control on your install (such as installing from a particular branch, or tweaking the ``setup.py`` install to circumvent any issue on your system).
 Type the following command in the root directory:
 
 .. code-block::
@@ -84,12 +87,24 @@ Type the following command in the root directory:
 If the installation of a dependency fails and the reason is not obvious, we suggest installing that dependency
 separately with ``pip``\ , before trying again.
 
+With Docker
+^^^^^^^^^^^
+
+Use our Docker file to deploy Tangelo in a Linux environment, either retrieved from pip or mounted locally.
+Comment / uncomment the relevant sections of the Dockerfile to control installation and dependencies.
+
+"No install" notebook method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A good alternative for users that simply want to quickly get a working environment ready, especially for quick tests, demos, tutorials.
+Check out the tutorial section below to see how services such as Google Colab may help you circumvent local installation challenges or go beyond the limitations of your personal computer if you feel short of compute power or memory.
+
 
 Optional dependencies
 ^^^^^^^^^^^^^^^^^^^^^
 
 Tangelo enables users to target various backends. In particular, it integrates quantum circuit simulators such as
-``qulacs``\ , ``qiskit``\ , ``cirq`` or ``qdk``. We leave it to you to install the packages of your choice.
+``qulacs``\ , ``qiskit``\ , ``cirq`` or ``qdk``. We leave it to you to install the packages of your choice, and refer to their own documentation.
 Most packages can be installed through pip in a straightforward way:
 
 .. code-block::
@@ -136,9 +151,10 @@ Tutorials
 ---------
 
 The ``examples`` folder of this repository contains various Jupyter notebook tutorials, and other examples.
-We wrote a number of them, but nothing prevents users from contributing more notebook content !
-You can visualize a number of pre-run notebooks directly on Github or in our Sphinx documentation. If you'd like to be able to run
-them locally, we suggest you use `Jupyter notebooks inside a virtual environment <https://janakiev.com/blog/jupyter-virtual-envs/>`_.
+We wrote a number of them, but nothing prevents users from contributing more notebook content, to show what they have been doing with Tangelo!
+You can visualize notebooks directly on Github, most of them have been pre-run.
+
+If you'd like to be able to run them locally, we suggest you use `Jupyter notebooks inside a virtual environment <https://janakiev.com/blog/jupyter-virtual-envs/>`_.
 
 - Install Jupyter and ipykernel in your environment:
 .. code-block::
@@ -150,6 +166,10 @@ them locally, we suggest you use `Jupyter notebooks inside a virtual environment
 
    python -m ipykernel install --user --name=myenv
 
+Jupyter notebooks can also be displayed and executed in the cloud, with services such as Google Colab. This removes the constraint of building a local development envrionement, and enables users to run interactive notebooks on machines that may provide a better configuration than their own (more RAM, compute power, access to GPUs...). This may come in handy for users who want to get started quickly, especially for quick tests, demos and tutorials.
+
+Check out our `tutorials <./TUTORIALS.rst>`_ file for more details.
+
 Tests
 -----
 

TUTORIALS.rst

@@ -0,0 +1,64 @@
+Tutorials
+=========
+
+Jupyter notebook python tutorials
+---------------------------------
+
+Chemistry, quantum computing and software development is tough stuff. We believe that tutorials in the form of jupyter notebooks are
+a great tool to both disseminate knowledge, but also to showcase all the cool stuff the community has done with Tangelo.
+Working on notebooks is a great way to contribute to this project, and to show everyone something neat you've worked on:
+perhaps something that led to a hardware experiment, or implemented an interesting approach.
+
+If you are new to Jupyter notebooks, check out `this page <https://realpython.com/jupyter-notebook-introduction/>`_.
+I hope you enjoy it.
+
+Quickly deploy a notebook in the cloud
+--------------------------------------
+
+Sometimes, you don't want to spend time setting up a local python environment. Maybe it's too cumbersome, or maybe it's
+just that your computer's performance is not quite as good as what you'd like. Maybe you simply want to run an existing
+notebook and try a few things, right now. Or maybe you intend to run a workshop and you want to avoid any delays
+incurred by installation issues experienced by your attendees (the worst). Some cloud providers offer services that can
+help with that.
+
+
+Google Colab
+^^^^^^^^^^^^
+
+.. |gcolab| image:: https://colab.research.google.com/assets/colab-badge.svg
+
+`Google Colab <https://research.google.com/colaboratory/faq.html>`_ is a rather straightforward way to achieve the above, as explained on this `webpage <https://colab.research.google.com/github/googlecolab/colabtools/blob/master/notebooks/colab-github-demo.ipynb#scrollTo=K-NVg7RjyeTk>`_.
+If you see a |gcolab| badge like this one in a notebook, you can just deploy the notebook on Google Colab by just clicking on it.
+
+Users can read, execute and collaborate through their internet browser. The notebook is hosted and executed on a machine
+in the cloud. There are several subscription tiers: the first one is free and may provide you with what you need. The
+others can provide you with access to more performant hardware, including GPUs and TPUs, or extra features.
+
+Most of our notebooks are ready to be deployed through Google Colab as-is. A few notebooks require dependencies
+that are not publicly available (at the time of writing, QEMIST Cloud is not), or are a bit trickier to install: you may
+have to contact us to get access to non-public material.
+
+If you also have access to Google Drive, you can upload your notebooks there and just open then in Google Colab by
+double-clicking or right-clicking "open with". To enable this, connect Google Drive to Google Colab by
+going to the settings (wheel on top-right of screen), clicking "manage apps" and then searching and installing Colab.
+
+It is possible that Google Colab is not available in your region of the world. Maybe other cloud providers offer similar
+services in your area.
+
+Setting up your environment through an already-deployed notebook
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have access to an already-deployed notebook in a remote environment you have little control on, you can actually make python run shell commands to modify
+the environment in which it runs. We use that trick to check right at the start if Tangelo or the other dependencies
+for our notebooks are already installed, and install them for you if not. This is what the cell looks like:
+
+.. code-block::
+
+   try:
+      import tangelo
+   except ModuleNotFoundError:
+      !pip install git+https://github.com/goodchemistryco/Tangelo.git@develop --quiet
+
+You can use pip to install python packages, but you can run any other shell command: use other package managers for other
+software and libraries, download data from somewhere else...
+`These examples <https://colab.research.google.com/notebooks/snippets/importing_libraries.ipynb>`_ are not specific to Google Colab.

dev_tools/release_guide.rst

@@ -0,0 +1,154 @@
+Release guide
+=============
+
+This document is here to assist project maintainers in creating and deploying new releases on Github and pypi.
+It covers the processes of bumping the main branch to a new version number, ensuring the develop branch catches up, and
+then creating and deploying new releases on Github and pypi (pip). All of these steps take place on the public repo.
+
+In order to complete the steps of this release process, you must have adequate permissions on Github, and pypi.
+If you're not sure you have them, reach out to project maintainers and owners BEFORE you start doing anything.
+
+ In the following, we assume that the project is to be bumped to a new version number x.y.z, that reflects the progress that
+ was made in the project since the previous release, and has been already agreed on by maintainers.
+
+1. Bumping the main branch to the new version
+----------------------------------------------
+
+1a. Creating the release/x.y.z branch to main PR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can do this through an automated Github workflow/action, called `create_release_branch` at the time of writing this document.
+This will create a release branch with the desired version number, and a Pull Request from the release branch into main.
+To achieve this, go to the `action tab <https://github.com/goodchemistryco/Tangelo/actions/workflows/create_release_branch.yml>`_
+of the project, and go through the following steps:
+
+|release_action|
+
+.. |release_action| image:: ./release_action.png
+   :width: 600
+   :alt: release_action
+
+- Click the desired workflow on the left
+- Click the "run workflow" button in the blue zone
+- Use workflow from branch "develop"
+- Enter the desired release version number
+- Click the green button that reads "run workflow"
+
+ Our workflow is defined in our repo under `.github/workflows`: it is thus versioned by git and we expect the version in develop
+ to be the latest. But if you make changes to it and want to try it out, you may want to run the version of the workflow
+ from your branch. It would be preferable to run workflow tests on a private version of the repo, to avoid leaving traces
+ of the tests and messing up the history of the public one.
+
+This workflow should only take a few seconds to run: stay on the action tab to make sure it appears in the log, and has
+successfully completed. Feel free to explore the different steps. This should have created a `release/x.y.z` branch and a
+PR attempting to merge that branch into main.
+
+
+1b. Merging the release to main PR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new PR should have been created. The description tells you how it came to be, and what you should be doing.
+Here's a `past example <https://github.com/goodchemistryco/Tangelo/pull/187>`_ so that you can get an idea of what it may look like.
+
+This PR does not need to be reviewed in details: virtually all its contents are changes have already been reviewed, tested and
+merged into develop. What matters is that:
+
+- the tests passed
+- the version string in `tangelo/_version.py` is as expected
+- `CHANGELOG.md` has been updated (you may have to do that manually until we figure out a better way)
+
+To update the CHANGELOG: use the PR conversation tab and trim the history down to the essentials (you can take example
+on the previous entries of changelogs).
+
+Ask someone to kindly look at the version and CHANGELOG files, and approve the PR once tests have passed.
+Once the PR has been merged, main has officially been updated!
+
+
+1c. Updating develop to new version number
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The main branch is now slightly ahead of the develop branch (version number, CHANGELOG): open a PR from main into develop.
+This PR should be very small, once you fixed the conflicts. Likewise, get the tests to pass and ask for a trivial review.
+Once approved, we can merge that PR and develop has caught up with main.
+
+
+2. Creating a new release on Github
+-----------------------------------
+
+Notice the release section on the right part of the screen, on the github project page.
+Go to the `release page <https://github.com/goodchemistryco/Tangelo/releases>`_ (you can also reach it by clicking "Releases").
+
+|release_github|
+
+.. |release_github| image:: ./release_github.png
+   :width: 600
+   :alt: release_github
+
+- Click “draft a new release”
+- Create a new tag (vx.y.z for the version number is usually good)
+- Base this release on the main branch
+- Populate the release message (changelog info, contributors, and a human-friendly message that addresses our readers).
+- You do not need to attach any files to the release, github will attach a zip and a tar.gz snapshot of the main branch.
+
+The release message can be as nice as we want it to be: announcements, roadmap, exciting news, special thanks,
+pretty figures, links ... It's an opportunity to celebrate and acknowledge the contributions of everyone, and make people
+excited for this new version.
+
+ You can populate the "changelog" part manually or try the "Generate release notes" button with the tag of the previous version.
+
+After you click the green button, the release section should now feature a new entry, with your release message, and a tar.gz and zip
+snapshot of the code in main attached. You did it!
+
+3. Creating a new release on pypi (pip)
+---------------------------------------
+
+Most of the process follows the information on `this page <https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives>`_.
+Before proceeding, you need:
+
+- an account on pypi with adequate privileges for this project
+- a pypi token for this project (see link above)
+
+The following steps will take place in a terminal on your personal computer. Make sure you are doing them using the latest
+version of the main branch, where the release is based from (you can just work in a folder that unpacked the zip or tar.gz
+archives found in the github release you have just completed).
+
+.. code-block::
+
+   # Create new virtualenv with version number (release_x.y.z), activate it
+   python3 -m venv release_x.y.z
+   source release_x.y.z/bin/activate
+
+   # Upgrade pip and build
+   python -m pip install --upgrade pip
+   python -m pip install --upgrade build
+
+   # Ensure no dist folder is present under the root folder of Tangelo
+   # Create distribution files (wheel and from-source distrib), they should appear under a dist folder.
+   # It seems that we do not need a pyproject.toml file and that setup.py is used.
+   python -m build
+
+   # Upload to pypi with Twine
+   python3 -m pip install --upgrade twine
+   python3 -m twine upload dist/*
+
+
+You will be prompted for a username and password.
+For the username, use __token__ (two underscores before and after).
+For the password, use the token value, including the pypi- prefix (ex: pypi-s32fdg3fg2fd3....).
+
+If successful, the release is now available on pypi!
+You should try to create another fresh virtual environment and install the package with pip to make sure it works
+(maybe just do a simple import and query for the version number with tangelo.__version__)
+
+.. code-block::
+
+   pip install tangelo-gc
+
+Share the news with others, ask them to try installing the new version through pip in their environments: the more datapoints, the better.
+We really do not want users to have issues with pip installs.
+
+
+Finally, you're done! Thank you for creating a new release. If you think this release process can be made easier or improved
+in general, feel free to provide feedback.
+
+© Good Chemistry Company 2022. This software is released under the Apache Software License version 2.0.