Prerequisites
WebMO can be accessed from an external program using REST (Representational State Transfer) queries. Although REST queries can be issued directly from Python, a webmo library of wrapper functions has been written to greatly simplify this process.
Accessing WebMO from a Python program requires the following:
- The webserver must be configured to support REST queries, as described on the REST-JSON Interface for WebMO.
- Python must be available to the local user. Windows and Mac OS users can do this most easily by installing Anaconda. Linux systems typically have Python installed by default. Python can also be obtained from the official Python website. For WebMO usage, Python can be provided without having to install any software on the user's computer via a hosted instance of JupyterLab.
- The Python requests library must be installed to support REST queries. If not already present, this can be done with:
% python -m pip install requests
- The Python webmo library must be installed, which can be done with:
% python -m pip install webmo
(from the command line)
OR
%pip install webmo
(from inside a JuypterLab notebook; note that one must type the "%" in "%pip" because it is a magic command)
To check your version of the webmo library against available versions and then potentially update it, from the command line type:
% python -m pip show webmo
% python -m pip index versions webmo
% python -m pip install --upgrade webmo
Accessing WebMO Using the webmo Python Library
The webmo Python library greatly simplifies the use of REST queries.
The following Python program is similar to the command line calls that directly use REST, but it is much easier to follow. It obtains an authorization token, uses of the token to obtain information about the user and results of a job, and deletes the token.
#minimal.py
from webmo import WebMOREST
#obtain a REST session
rest = WebMOREST("https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi", "smith")
#request information about user
results = rest.get_user_info("smith")
print(results)
#request information about job
results = rest.get_job_results(2)
print(results)
#end the REST sessions
rest = None
Running this Python program on the local computer results in the following output:
$ python minimal.py
Enter WebMO password for user smith: ......
{"admin":false,"user":"smith","properties":{"archiveFormat":"tar","fullName":"John Smith","allowNewUsers":"1","enabledQueues":"all","jobTimeLimit":"-1","timeLimit":"-1","email":"smith@university.edu","viewJobInNewWindow":"0","enabledInterfaces":"all","emailNotification":"0","enabledServers":"all"}}
{"success":true,"molecular_multiplicity":1,"connectivity":[[1,2,1],[1,3,1]],"provenance":{"creator":"Gaussian"},"molecular_charge":0,"schema_name":"QC_JSON","properties":{"rhf_energy":{"value":-76.0107465155,"units":"Hartree"},"rotational_constants":[858.6603475,440.9401844,291.3340235],"route":" #N HF/6-31G(d) OPT Geom=Connectivity","scf_dipole_moment":[0,0,2.1989],"symmetry":"C2V","dipole_moment":[0,0,2.1989],"cpu_time":{"value":6.1,"units":"sec"},"stoichiometry":"H<sub>2</sub>O","basis":"6-31G(d)"},"comment":"H2O; Geometry Optimization","symbols":["O","H","H"],"geometry":[0,0,0.114681,0,0.754069,-0.458726,0,-0.754069,-0.458726],"schema_version":0}
Sample Python Programs
One could extend the previous program to access any job and extract specific information as follows:
#minimal2.py
from webmo import WebMOREST
baseURL = "https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi"
#obtain a REST session
username=input('Enter WebMO username:')
rest = WebMOREST(baseURL, username)
#request information about user
results = rest.get_user_info(username)
print(results["properties"]["email"])
#request information about job
jobNumber=int(input('Enter WebMO job number:'))
results = rest.get_job_results(jobNumber)
print(results["properties"]["rhf_energy"])
#end the REST session
rest = None
which when run produces:
$ python minimal2.py
Enter WebMO username: smith
Enter WebMO password for user smith: ......
smith@university.edu
Enter WebMO job number: 2
{'value': -76.0107465155, 'units': 'Hartree'}
Another example is submitting a job to be run on the WebMO server and then printing the results:
#submit.py
from webmo import WebMOREST
from webmo.util import xyz_from_name
import json
baseURL = "https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi"
#obtain a REST session
username=input('Enter WebMO username:')
rest = WebMOREST(baseURL, username)
#generate our input file
templates = rest.get_templates('gaussian')
template = templates['Geometry Optimization']
jobName = "H2O Optimization (from Python)"
input_file_contents = rest.generate_input(template, variables={
'jobName' : jobName,
'geometry' : xyz_from_name('water'),
'theory' : 'HF',
'basisSet' : '6-31G(d)'})
jobNumber = rest.submit_job(jobName, input_file_contents, "gaussian")
print("Submitted job", jobNumber)
#wait for the job to complete
rest.wait_for_job(jobNumber)
#fetch the job results (as JSON)
rest.get_job_results(jobNumber)
results = rest.get_job_results(jobNumber)
print(json.dumps(results, indent=4))
#end the REST session
rest = None
which when run produces:
$ python submit.py
Enter WebMO username: smith
Enter WebMO password for user smith: ......
Submitted job 723
...
"rhf_energy": {
"value": -76.0107465155,
"units": "Hartree"
},
...
and results in a new job file within WebMO:
Additional examples of Python programs are provided in the <cgiBase>/REST/templates directory:
- _print_results.py: display job results in formatted JSON
- _visualize_results.py: display job geometry image (requires JupyterLab notebook)
- coordinate_scan: graph coordinate scan energies as a function of geometry change
- geometry_convergence.py: graph convergence of energy and rms geometry change from an optimization job
- orbital_diagram.py: graph orbital energy levels from a molecular orbital job
- spectra.py: display job infrared spectrum image (requires JupyterLab notebook)
- thermochemistry.py: use computed energy and frequencies to calculate and graph internal energy and Cvib as a function of temperature
When using these additional examples, one will have to replace the template variables ($baseURL, $username, $jobNumber, etc) with values or python variables. This is done automatically when these template programs are opened in a Jupyter Notebook from within WebMO.
JupyterLab Python Program Examples
JupyterLab is a convenient web-based interface for Python programming and interacting with WebMO.
The following JupyterLab notebooks (*.ipynb) illustrate a variety of applications:
- Simple.ipynb: very simple Jupyter notebook to obtain the results of a completed WebMO job
- RunJob_Simple.ipynb: runs a WebMO job from a Jupyter notebook and prints the resulting energy
- RunJob_Template.ipynb: runs a WebMO job by defining variables that populate a template
- Image_Simple.ipynb: displays example images from completed WebMO jobs
- Image_Multi.ipynb: displays images in a grid from completed WebMO jobs
- Spectrum_Simple.ipynb: computes and plots the infrared spectrum of a molecule
- Spectrum_Overlay.ipynb: overlays computed and experimental spectra
- Automation_and_Templates.ipynb: automates the computation and display of computed properties as a function of model chemistry
- Documentation.ipynb: Description of webmo REST commands, examples, and documentation