Using WebMO Results in Python programs
Results from WebMO calculations can be acessed programmatically via a REST-JSON interface. Although this can be done from any programming language with http communication capabilities, Python is widely available, very popular, and particularly convenient for this purpose. To simplify this process, a Python Interface for WebMO has been written that allows user, job, result information to be retrieved. Jobs may also be submitted to WebMO from Python.
Python typically needs to be installed on a user's local computer as a programming language, from which it can be accessed in a terminal session or through a Integrated Programming Environment (IDE). An increasingly popular Python environment is JupyterLab, which includes both Python and a notebook interface, so that programs and explanatory comments can exist within one interactive document. JupyterLab is web-based, so all interaction is done through a web-browser.
WebMO Enterprise includes a built-in interface to JupyterLab. When viewing WebMO results, one can invoke a JupyterLab session that download job results and perform subsequent calculations and/or display graphical analysis. Several demonstration programs are provided within WebMO to illustrate this capability:
- Print results: display available job results in formatted JSON
- Coordinate scan: graph coordinate scan energies as a function of geometry change
- Geometry convergence: graph convergence of energy and rms geometry change from an optimization job
- Orbital diagram: graph orbital energy levels from a molecular orbital job
- Thermochemistry: use computed energy and frequencies to calculate and graph internal energy and Cvib as a function of temperature from a frequency job
These demonstration programs are available from the Jupyter link in the navigation panel on the View Results page. The WebMO administrator can add additonal Python programs by placing them in the <cgiBase>/REST/templates directory.
JupyterLab is a web-based Python programming environment. The JupyterLab server is often installed on a user's local computer, which has the advantage of being able to locally save Jupyter notebooks (programs and results). A Jupyterlab server can also be accessed on the web, which has the advantage of not having to install any software on a user's computer.
JupyterLab provide web-based Python programming
Jupyter (JUlia, PYThon,and R) is an interactive Python programming environment available within a web-browser. The previous Jupyter notebook interface is now distributed as a much more pwerful and flexible JupyterLab interface. JupyterLab can load and execute pre-written python programs or notebooks.
Prerequisites: The WebMO webserver must be capable of processing REST requests. JupyterLab (or notebook) must be available to the WebMO user and running. JupyterLab typically runs on the user's local computer so that notebooks can be saved, although installations on remote servers are also common.
Several options exist for allowing WebMO users to access to WebMO output files via JupyterLab:
Option 1: JupyterLab is usually installed on a local machine
The easiest and recommended way to install JupyterLab is by installing Anaconda, which includes Python, JupyterLab, and Navigator to optionally install additional conda packages for numerical analysis:
- Download Anaconda for your local operating system. Use the latest Python 3.X version.
- Install the downloaded version of Anaconda.
- From a command prompt (Windows) or Terminal (Mac/Linux), navigate to a jupyter folder, and run JupyterLab on the local machine:
$ jupyter-lab - Open and use an existing Python3 notebook (*.ipynb)
or
Click the Python 3 Notebook icon to open a new notebook - If not already done, install the webmo python library by typing "%pip install webmo" in a cell and clicking the Run icon (or pressing control-Enter)
- When done, choose File:Shutdown to exit JupyterLab
Option 2: MyBinder.Org can host an instance of JupyterLab and reference a GitHub repository of notebooks
MyBinder.org provides an executable Jupyter notebook environment for a GitHub repository, thereby eliminating the need for each user to install JupyterLab on their local machine:
- In a web browser, open
https://mybinder.org/v2/gh/<github_user>/<github_repository>/master
which will open JupyterLab. This is most easily done by clicking the Jupyter link in the navigation bar, followed by Open Jupyter button. Servers pre-configured for WebMO are available at
https://mybinder.org/v2/gh/webmodemo/demoserver/master - Open and use an existing Python3 notebook (*.ipynb)
or
Click the Python 3 Notebook icon to open a new notebook - When done, choose File:Shutdown to exit JupyterLab. Note that results will not be saved locally, as they were stored on the virtual JupyterLab server which is being deleted!
Additional notebooks can be saved as *.ipynb files in the GitHub repository, which must directly reference your WebMO server. Required python modules can be specified in a requirements.txt file in the repository.
Option 3: JupyterLab can be hosted on the WebMO server (under development)
A development version of The Littlest Jupyterhub (TLJB) is available, though it is untested by WebMO. TLJB allows up to 100 users to access Jupyter notebooks running on the WebMO server itself.
Use System Manager to specify whether the JupyterLab server is expected on a user's local machine or on a web-based host. The Open Jupyter button will open the location defined by Jupyer notebook URL.
Running WebMO Python Programs in a JupyterLab notebook
While viewing a job within the the WebMO interface, click the Jupyter link to open the Jupyter Notebook Templates dialog box
Jupyter Notebook Templates
To run a WebMO python program in your Jupyter notebook:
- Select a script from the dropdown list
- Click Copy to Clipboard to copy the %load template command
- Click Open Jupyter to open Jupyter in your web browser; it will either be a local or remote Jupyter server, depending on the Jupyter notebook URL specification in System Manager
- Click the Notebook: Python3 icon to open a notebook
- Paste in the %load template command into a code cell, and click the Run icon (or press control-Enter) to load the Python program
- Click Run again to execute the program
Python scripts added to the <cgiBase>/REST/templates directory will be dynamically displayed to in the dropdown list for users to select.
 MyBinder Jupyter Server |
 JupyterLab |
 %load Template |
 Python Program |
 Python Output |
 Python Output, continued |
Tips on Using Jupyter Notebooks
What is Jupyter?
Jupyter notebooks are similar to Mathematica notebooks, Maple worksheets, or MathCAD documents, which allow for interactive analysis and documentation of scientific questions. Jupyter extends these prior examples from stand-alone applications to the web.
A Jupyter Notebook Document (*.ipynb), or simply "Jupyter notebook", contains both code and rich text elements (figures, links, equations, ...). Because of the mix of code and text elements, a Jupyter notebook can bring together data, description of analysis, real-time analysis and results. JupyterLab allows you to edit and run notebooks via a web browser.
The two main components of JupyterLab are the Notebooks and a kernel:
- The Notebook displays notebook documents (*.ipynb) and can open them.
- A kernel is a program that runs the user's code. The JupyterLab has a kernel for Python code, but there are also kernels available for other programming languages.
Starting Jupyter
After installing JupyterLab (see above), Jupyter can be started from a shortcut or a terminal session:
$ jupyter-lab
A webpage containing JupyterLab will open up with a menu, file navigator, and launcher. Note that the URL for a locally-installed instance will be something like:
http://localhost:8888/lab
"localhost" is not a website, but your own computer. "lab" is your home or root JupyterLab directory.
JupyterLabe
Running an existing notebook
Navigate to folder with your *.ipynb ("iPython notebook") files and run the desired file. A kernel will be started to run notebook, and the existing notebook will appear in a new tab.
The notebook can be edited, etc. Changes are automatically saved.
To exit the document, File: Close Tab.
Creating a new notebook
In the Launcher, select a Python 3 Notebook. A kernel will be started to run notebook, and the blank notebook will appear in a new webbrowser tab.
 Launch Python3 Notebook |
 Empty Python 3 Notebook |
Interacting with a JupyterLab notebook
A notebook consists of cells, which may be of the following types:
- Code: contains python code or resulting output
- Markdown: contains formatted text for explanatory purposes
- Raw: very rare; content that should be included unmodified in nbconvert output
There are two modes of interacting with a JupyterLab notebook page:
- Edit: type code or text into a cell (press Enter to enable)
- Command: edit cells or notebook as a whole (press Escape to enable)
Within Edit mode there are several important keyboard shortcuts:
- Ordinary keystrokes: edit cell contents
- Shift-Enter: run current cell (run Python if a code cell; display markdown if a markdown cell)
- Esc: switch to Command mode
Within Command mode there are several important keyboard shortcuts:
- Shift-Enter: run current cell (run Python if a code cell; display markdown if a markdown cell)
- m: change cell to markdown
- y: change cell to code
- Enter: switch to Edit mode
A Code cell contains python code to be executed by the kernel. Output will appear at the bottom of the cell. It has a label "[ ]" on the left. The contents of "[ ]" is blank if not yet run, * if running, or a number representing the order of processing by the kernel. The bar on the left of the cell is blue if unedited, but orange of edited since it was last run.
A Markdown cell contains text formatted in markdown language and is editable in edit mode. It displays its formatted output when run from command mode. It does not have a label on the left.
IMPORTANT: You must run the contents of a cell to see the code output or formatted display!
Example
Open a new Python3 notebook. In code cell, type
print ('Hello World!')
and click the run icon (or select Run: Run Selected Cells, or press Shift+Enter). The program output will appear below the code cell.
JupyterLab Python Program
Magic commands
There are also "magic" commands that execute outside of Python:
- %load: inserts code from an external script
- %pip: runs the pip command to install or uninstall python packages
- %quickref: display a list of useful commands
Exiting JupyterLab
Save your notebook. Choose File:Shutdown from the menu system.