Using Templates
WebMO presents the user with a list of pre-defined calculation types for each of the various computational engines. These calculation types are defined by template files, which WebMO uses to build input files for jobs with user selected options.
WebMO Pro and Enterprise provide a template editor that allows administrators and users to customize existing or add new templates, and thereby extend the capabilities of WebMO. Editing templates is useful for implementing new calculation types, running jobs with customized settings in a research setting, or running fully pre-defined jobs in a classroom setting.
The WebMO admin user can edit the pre-defined WebMO templates and/or create new templates that are visible to all WebMO users. An admin-{group} user can create new templates that are visible to all users in the group. And regular users can create new templates that are visible only to themselves.
Editing Templates
The WebMO admin and admin-{group} administrators can access the template editor by logging in and clicking the Template Manager link.
Regular users can access the template editor by clicking the Add templates or variables on the Advanced tab of the Job Options page.
At the top of the Template Manager, select the Engine for which you wish to create new calculation types. On the Variables tab, define any new variables that your template will require, and click Create. On the Templates tab, select a template that is similar to the one you wish to create. Click the Save As... button, and provide a new name for the template. Edit the template as described below, and click Save.
 WebMO Variables Tab |
 WebMO Templates Tab |
Defining Variables
It is often useful to create a variable for use within the template, for which the user can interactively select a value.
The Template Editor allows one to define three types of variables:
- Text: user editable textbox (e.g., Continuum solvation model: solvation_model: default = "COSMO")
- Checkbox: user selectable on/off checkbox (e.g., Enable solvent: solvent_on: default = "")
- Drop-down: user selectable among options (e.g., Grid size: grid_size: default = "medium": options = "course,medium,fine")
The value of defined variables can be selected by the user on the Advanced tab of the Job Options page. To not overwhelm the user with variable choices, defined variables appear ONLY if they are referenced in the template for the selected calculation type and computational engine.
Template Syntax
Text
Regular text in a template is duplicated into the input file.
Special Characters
The following characters are treated specially within templates:
| Character | Description |
|---|---|
| \n | New-line |
| / (at end of line) | Continue onto next line as if no line break occurred |
| \$ | Dollar sign ($) |
| [% ... %] | Template directive |
Variables
Templates usually contain variables, which are replaced with their values when the input file is created. Variables are preceded by a dollar sign ($), e.g., $theory. However, variables referred to in a template directive do not use the dollar sign, e.g., [% IF theory != "PM3" %].
The following table includes some pre-defined variables which the user can access from the Job Options page. Other more specialized variables for each engine are accessed on the Advanced tab of the Job Options page.
| Variable | Description |
|---|---|
| $jobName | The name given to this job by the user |
| $theory | The selected level of theory |
| $basisSet | The selected basis set |
| $charge | The charge of the molecule |
| $multiplicity | The multiplicity of the molecule |
| $geometry | The molecular geometry, in an appropriate form |
| $additionalKeywords | Any user specified additional keywords |
| $calculation | The type of calculation specified by the user (only used when "Other" is selected) |
For example, the following is an excerpt from a Gaussian template:
#$outputMode $theory/$basisSet OPT FREQ $additionalKeywords
If the user chose normal output mode, HF theory, the 3-21G basis set, and no additional keywords, then this line would result in the following input file text:
#N HF/3-21G OPT FREQ
A complete set of pre-defined variables for each engine is listed on the Variables tab of the Template Editor.
Conditional Expressions
Templates often contain conditional expressions, whose result depends upon evaluation of a condition such as the value of a variable.
"If-Then-Else" conditional expressions have the syntax:
[% IF {condition} %] {text if true} [% ELSE %] {text if false} [% END %]
The following conditional and boolean operators may be used:
== (equals), != (not equal to), <, <=, >, >=, && (and), || (or), ! (not)
Parentheses may be used to determine the evaluation order.
For example, , the following is an excerpt from a Gaussian template:
[%IF includeConnectivity %]Geom=Connectivity[%END%]
If the "Include Connectivity" checkbox on the Advanced tab is checked, then includeConnectivity evaluates to "on" and this results in
Geom=Connectivity
If "Include Connectivity" is unchecked, includeConnectivity evaluates to "" and this results in no output.
More Details
WebMO templates use the Template Toolkit library to interpret variables and evaluate conditional expressions. Other powerful constructs are available, such as loops, etc. Full documentation on syntax and additional features are available online at Template Toolkit Homepage.
Examples
The WebMO pre-defined calculations found in the default templates provide many useful examples.
In general, start with an existing template that is similar to the calculation you wish to define, and save a copy of the template with Save As... Then define any necessary new variables, and edit and Save the new template. Load the new calculation on the Job Options page, check newly defined variables on the Advanced tab, and click Generate in the Preview tab. Alternate between the editing in Template Manager and viewing the result on the Job Options page. This iterative process will allow the creation of new templates based on existing examples.
Template File Locations
Template files are text files divided into sections which are separated by a line of equal signs (=). The first line of each section contains the name of the calculation, for example "Geometry Optimization". The remainder of the section is used to generate the input file which is provided to the appropriate computational engine.
Pre-defined global templates are contained in the {cgiBase}/interfaces/*.tmpl template files, e.g., Gaussian job templates can be found in gaussian.tmpl. Custom-defined global templates and variables are contained in {userBase}/admin/*.tmpl and *.vars files. Calculations defined in this location can be edited only by the WebMO administrator, but are available to all WebMO users.
Group templates may be defined by the admin-{group} group administrator. These are contained in the {userBase}/admin-{group}/*.tmpl and *.vars files. Calculations defined in this location are visible to all users within the group.
User templates may be defined by each user. These are contained in the {userBase}/{username}/*.tmpl and *.vars files. Calculations defined in this location are visible only to the user who defined them.
Updating WebMO will overwrite the pre-defined global templates in {cgiBase}/interfaces/*.tmpl. But updates will not overwrite newly defined templates in {userBase}/admin/*.tmpl. Thus it is strongly recommended that the WebMO administrator create new global templates rather than re-define existing templates.