Notebooks enabled for Google colab ("No local install" needed)

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::
@@ -85,11 +88,18 @@ If the installation of a dependency fails and the reason is not obvious, we sugg
 separately with ``pip``\ , before trying again.
 
 
+"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 +146,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 +161,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.

examples/classical_shadows.ipynb

@@ -6,6 +6,8 @@
    "source": [
     "# Classical Shadows\n",
     "\n",
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/goodchemistryco/Tangelo/blob/develop/examples/classical_shadows.ipynb)\n",
+    "\n",
     "The output of a quantum computer is a histogram of measurements, corresponding to the different outcomes observed, usually expressed as bitstrings. The cost and duration of a quantum experiment is roughly linear with the number of shots used to build such histograms, which also correlates with the accuracy of the results. This measurement overhead can be prohibitive for state tomography and computation of observables for quantum chemistry applications.\n",
     "\n",
     "The emergent method *classical shadows* ([Nat. Phys. 2020, 16, 1050–1057](https://arxiv.org/abs/2002.08953)) has been developed to mitigate the measurement overhead by offloading quantum tasks to the pre- and post-processing steps. This prediction protocol exhibits logarithmic scaling with the number of terms to measure, in order to compute the expectation value of a term within a given accuracy.\n",
@@ -14,7 +16,22 @@
     "\n",
     "![Classical Shadows overview](img/classical_shadow_overview.png \"Classical Shadow\")\n",
     "\n",
-    "The randomized, derandomized and adaptive shadow protocols using the single-qubit Pauli basis as a set of unitaries  are currently available in Tangelo. This introduction will shed light on how to leverage their use in your own investigation, and highlight the main differences between these approaches. At the end of this notebook, a comparison is made between energies predicted with those techniques and the one computed by using a Hamiltonian partitioning approach relying on qubitwise commutativity."
+    "The randomized, derandomized and adaptive shadow protocols using the single-qubit Pauli basis as a set of unitaries  are currently available in Tangelo. This introduction will shed light on how to leverage their use in your own investigation, and highlight the main differences between these approaches. At the end of this notebook, a comparison is made between energies predicted with those techniques and the one computed by using a Hamiltonian partitioning approach relying on qubitwise commutativity.\n",
+    "\n",
+    "This notebook assumes that you already have installed Tangelo in your Python environment, or have updated your Python path so that the imports can be resolved. If not, executing the cell below installs the minimal requirements for this notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Installation of tangelo if not already installed.\n",
+    "try:\n",
+    "    import tangelo\n",
+    "except ModuleNotFoundError:\n",
+    "    !pip install git+https://github.com/goodchemistryco/Tangelo.git@develop --quiet"
    ]
   },
   {
@@ -27,7 +44,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
@@ -66,7 +83,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [
     {
@@ -95,14 +112,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Energy from statevector simulation: -1.1475 hartree\n"
+      "Energy from statevector simulation: -1.1473 hartree\n"
      ]
     }
    ],
@@ -132,7 +149,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -153,15 +170,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Energy from randomized single-Pauli classical shadow: -0.8362 hartree\n",
-      "Error vs statevector simulation: 0.311 hartree\n"
+      "Energy from randomized single-Pauli classical shadow: -1.0593 hartree\n",
+      "Error vs statevector simulation: 0.088 hartree\n"
      ]
     }
    ],
@@ -187,15 +204,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Energy from derandomized single-Pauli classical shadow: -1.1598 hartree\n",
-      "Error vs statevector simulation: 0.012 hartree\n"
+      "Energy from derandomized single-Pauli classical shadow: -1.1765 hartree\n",
+      "Error vs statevector simulation: 0.029 hartree\n"
      ]
     }
    ],
@@ -221,15 +238,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Energy from adaptive single-Pauli classical shadow: -1.2052 hartree\n",
-      "Error vs statevector simulation: 0.058 hartree\n"
+      "Energy from adaptive single-Pauli classical shadow: -1.3384 hartree\n",
+      "Error vs statevector simulation: 0.191 hartree\n"
      ]
     }
    ],
@@ -258,15 +275,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Energy with qubitwise commutativity and equally distributed shots: -1.2053 hartree\n",
-      "Error vs statevector simulation: 0.058 hartree\n"
+      "Energy with qubitwise commutativity and equally distributed shots: -1.3012 hartree\n",
+      "Error vs statevector simulation: 0.154 hartree\n"
      ]
     }
    ],
@@ -308,7 +325,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {