WebMO Help - Python Interface (Enterprise)

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:

  1. The webserver must be configured to support REST queries, as described on the REST-JSON Interface for WebMO.
  2. 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.
  3. 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
  4. 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:

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:

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: