A quick guide to running HighTEA via Jupyter Notebooks

on Google Colab or on a local machine

 

HighTEA analyses are run with the help of Jupyter notebooks. The simplest way to get started with HighTEA is to run the Tutorial available on HighTEA’s Google Colab site. One can then adapt one of the several example Jupyter notebooks available on that site to one’s specific case.

 

There are two ways one can run a Jupyter notebook: on a local machine or in the Cloud, using Google Colab. Detailed instructions can be found in the following.

 

Running a HighTEA Jupyter notebook on Google Colab

 

This is the default and simplest way for using HighTEA since it offer full flexibility and access to all options, yet it does not require any computer infrastructure besides a web browser and a Google account.

1. Go to this page and open any one of the example Notebooks.
2. Click on the button “Copy to Drive” located in the top left part of the screen. Alternatively, use the main page menu: File/Save a copy on your Drive.
3. The Notebook has now been saved to your Google Drive (it can be found in a dedicated folder named “Colab Notebooks”). The saved Notebook can be renamed, edited and cloned as the user sees fit.
4. A notebook that has been saved on the user’s Google Drive can be run directly; there is no need to go back to HighTEA’s Colab page.
5. Running a Notebook is very easy – one simply “Runs” each command line. Once a command has been executed a green check mark appears next to it. Please also see the directions in our Tutorial or in any one of the example Notebooks.

Couple of words about saving the notebook and the results from a calculation.

1. Once a notebook is run (i.e. a job is submitted, results are received etc) the complete information about the job is automatically saved in a .job file. The directory in which this file is saved is set to a default value (at the very start of the notebook).
2. Once the notebook has been closed, Colab still “remembers” it for some time, i.e. if one reopens it after a period of time, they system will behave as if it was never closed. If one wishes to change this behavior please go to the menu and select “Runtime/Disconnect and delete runtime”.
3. Sometimes jobs can take some time to complete. This is due to either the length of the job or to the number of jobs already queued by the HighTEA server. The user does not need to wait for the job to complete. Once a job has been submitted (a message to that effect appears accompanied by a time stamp) the Notebook can be closed and exited. At a later time the user can open the notebook and rerun it from the very beginning. Operations that have been performed before will not be recomputed (a message to that effect is displayed). Once the point of job retrieval is reached the Notebook will internally ask the HighTEA server if the job has been computed and if yes, the result will be fetched. One can continue executing the Notebook as if it was never closed.

A note: the reason it is possible to retrieve a result from a job at a later time is that each job request is assigned by the HighTEA server a unique token which never expires. To reduce clutter, this token is not displayed in the Notebook. The token is not secret and is stored in the .job file discussed above.

 

 

Installing and Running a HighTEA Jupyter notebook on a local machine

 

1. Go to this page and open any one of the example Notebooks.
2. Create a directory on your local machine where the Notebooks and their outputs will be saved. For concreteness, in the following we call such a directory “hightea”.
3. Download the Notebook and save it in the directory “hightea” (from the page menu: File/Download; select the output with extension .ipynb).
4. Set the first line in the Notebook as follows: UseGoogleColab = False.

To install the Jupyter Notebook Interface on your machine please follow the instructions on this website. For information about other possible Notebook options, please see here.

Once the Jupyter Notebook Interface has been installed, the notebook can be run by opening a CLI, going to the directory “hightea”, and then typing the command

jupyter notebook

in the CLI (see here for more details). Please note that running a notebook on your local machine may require some adapting of the example Notebook provided as well as further adjustments based on your local software installation.