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)

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
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)
#define our input file
input_file_contents = """PM6 BONDS CHARGE=0 SINGLET XYZ PRNT=2 PRTXYZ FLEPO PRECISE GNORM=0.0
H2O

O 0.0000000 0 0.0000000 0 0.0000000 0 0 0 0
H 1.0500000 1 0.0000000 0 0.0000000 0 1 0 0
H 1.0500000 1 109.47122 1 0.0000000 0 1 2 0"""
#submit the job and grab the job number
jobNumber = rest.submit_job("H2O Optimization (from_python)", input_file_contents, "mopac")
#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:

$ submit.py
Enter WebMO username: smith
Enter WebMO password for user smith: ......
...
"pm6_heat_of_formation": {
"value": -54.30636,
"units": "kcal/mol"
},
...

and results in a new job file within WebMO:

Additional examples of Python programs are provided in the <cgiBase>/REST/templates directory:

webmo Python Library Functions

The "help" function in Python will produce detailed documentation for the WebMOREST interface, including available functions, their arguments, and return codes. As an example, run the following Python program:

#webmohelp.py
from webmo import WebMOREST
#output detailed documentation for the REST interface
help(WebMOREST)
#or for a specific function
help(WebMOREST.get_job_info)

which produces the following documentation:

$ webmohelp.py
class WebMOREST(builtins.object)
 |  WebMOREST(base_url, username, password='')
 | 
 |  The WebMOREST class provides an object-oriented Python API for the WebMO REST interface.
 | 
 |  The WebMOREST class provides a simple Python API to access the WebMO REST interface. As of now
 |  there are no public methods. Session tokens are handled automatically handled during object
 |  creation/destruction.
 | 
 |  Methods defined here:
...
 |  get_job_geometry(self, job_number)
 |       Returns the final optimized geometry from the specified job.
 |       
 |       This call returns an XYZ formatted file of the final optimized geometry from the specified job.
 |       
 |       Arguments:
 |           job_number(int): The job about whom to return information
 |           
 |       Returns:
 |           A string containing XYZ formatted optmized geometry |
...

A summary of available functions follows:

Function Description
WebMOREST(base_url, username, password='') Generates a WebMOREST object and also generates and stores a newly session token
delete_job(job_number) Permanently deletes a WebMO job
get_folders(target_user='') Fetches a list of folders owned by the current user or the specified target user
get_group_info(groupname) Returns information about the specified group
get_groups(self) Fetches a list of available WebMO groups
get_job_archive(job_number) Returns a WebMO archive from the specified job
get_job_geometry(job_number) Returns the final optimized geometry from the specified job
get_job_info(job_number) Returns information about the specified job
get_job_output(job_number) Returns the raw text output from the specified job
get_job_results(job_number) Returns detailed results of the calculation (e.g. energy, properties) from the specified job
get_jobs(engine='', status='', folder_id='', job_name='', target_user='') Fetches a list of jobs satisfying the specified filter criteria
get_user_info(username) Returns information about the specified user
get_users(self) Fetches a list of available WebMO users
import_job(job_name, filename, engine) Imports an existing output file into WebMO
submit_job(job_name, input_file_contents, engine, queue=None) Submits and executes a new WebMO job
wait_for_job(job_number, poll_frequency=5) Waits for completion of the specified WebMO job
wait_for_jobs(job_numbers, poll_frequency=5) Waits for completion of the specified list of WebMO jobs

The source code for the webmo Python library is available on github.

Use the "help" function as illustrated above for argument data types and returned data type. The help function will also include any recent changes made to the library.