Meta Workflow Builder Panel

Set up workflows to combine multiple simulation tasks from a simulation protocol into one job.

To open this panel: click the Tasks button and browse to Materials → Tools → Meta Workflows → Meta Workflow Builder .

The following licenses are required to use this panel: MS Maestro, additional licenses are workflow dependent

Using the Meta Workflow Builder Panel

The Meta Workflow Builder panel allows you to automate multi-step protocols for various material science applications using a graphical user interface rather than through writing a script. You can combine built-in single stage workflows, molecular dynamics (MD) simulations, and custom tasks into a "meta" workflow. A graph-based representation of the workflow provides visualization for the stages and how they connect.

Meta workflows can be saved and applied to different systems from the Run Meta Workflow Panel.

There are five types of meta workflow stages to choose from:

  • Workflow stages allow you to add built-in single stage workflows. See Single Stage Workflows for a list of currently supported workflows.

  • Simulation stages allow you to choose from 7 types of MD simulation stages.

  • Molecular QM stages allow you to run quantum mechanics calculations with Jaguar.

  • Custom script stages allow you to incorporate a custom script, or run a single stage workflow which has not been added to the built-in list (e.g., Uncertainty Quantification)

  • Flow control stages allow you to launch duplicate workflows from distinct output structures, and later merge the workflow by recombining separate structures into one input.

When the panel opens, a single Workflow stage is shown. You can add stages in the following ways:

  • Click Append Stage to add a new Workflow stage at the end of the list.

  • Click Append Workflow to add a built-in single stage workflow or a stages from a previously saved meta workflow.

  • Click the Duplicate button at the top right of a stage to duplicate the stage, with all its settings. The new stage is placed below the source stage.

  • Click the Append Stages from File button to add stages from a workflow .wfw file.

You can rearrange stages with the arrow buttons    at the top right of the stages. This makes it easy to duplicate an earlier stage then move it down into the desired location, and modify the settings.

If you want to see only some of the stages, you can show or hide the options with the show and hide buttons   . This is useful when you have a number of stages and want to compare two separated stages, for example. You can also show or hide a stage by clicking on the stage label, or clicking on the stage in the Workflow diagram. Show or hide all the stages with the expand all (++) and collapse all (--) buttons.

When the meta workflow job is run, each stage is submitted to the queueing system for execution in the proper sequence. Stages which have a parent stage or other required stages do not run until the parent or required stages have successfully completed. Stages which do not depend on results from another stage are simultaneously submitted to the queue and continue to run even if another stage has failed. Certain stages can be submitted to both CPU or GPU hosts, while other require a Linux GPU host. You can specify hosts for the meta workflow stages as well as the meta workflow driver from the Meta Workflow Builder - Job Settings Dialog Box

When the job finishes, the structures produced by all stages are incorporated into the project. All properties generated by a step are stored on the output structure for that step.

To write out the input file and a script for running the job from the command line, click the arrow next to the Settings button and choose Write. For information on command usage and options, see matsci_meta_workflow_driver.py Command Help.

Meta Workflow Builder Panel Features

Structure Source

Choose the source of initial structures for the calculations and how to incorporate them in the workflow. The type of input structure required for a meta workflow depends on the initial stage of the workflow. For example, if the initial stage normally requires a fully prepared Desmond system in a standalone calculation, then the meta workflow requires a fully prepared Desmond system. Two single stage workflows, Disordered System Builder and Polymer Builder, can combine multiple input structures into a single output structure. For the Polymer Builder, head and tail atoms for each monomer can be assigned with the Mark Monomer Head and Tail Panel prior to using them in the meta workflow. SMILES files (.smi, .smi.gz, .smigz, or .cxsmiles) are accepted as input for the Meta Workflow using the File option. The format of the file is one SMILES per line, with each line optionally containing a second (space-delimited) column with the structure title.

Use structures from option menu

Choose the structure source for the workflow.

  • Project Table (n selected entries)—Use the entries that are currently selected in the Project Table or Entry List. The number of entries selected is shown on the menu item. An icon is displayed to the right which you can click to open the Project Table and select entries. When this option is selected, a Load button is displayed to the right.
  • Workspace (included entry)—Use the entry that is currently included in the Workspace. Only one entry must be included in the Workspace. When this option is selected, a Load button is displayed to the right.
  • File—Use the specified file. When this option is selected, the File name text box and Browse button are displayed.
Open Project Table button

Open the Project Table panel, so you can select or include the entries for the structure source.

File name text box and Browse button

Enter the file name in this text box, or click Browse and navigate to the file. The name of the file you selected is displayed in the text box.

For multiple entries, run options

You can choose to run separate meta workflows for each selected entry or run a single meta workflow on a selection of multiple structures.

Only available if multiple entries are selected in the Use structures from option menu.

  • One workflow per entry— For each selected entry, the meta workflow is independently run.

  • A single workflow—The selected entries are combined and run in a single workflow. This option is only possible if the first step of the meta workflow can combine multiple structures (e.g., Disordered Systems Builder, Polymer Builder). Otherwise, an error is thrown when you click Run.

Collapse/expand all buttons

These two buttons (labeled -- and ++) allow you to collapse all workflow stages or expand all workflow stages. When expanded, a scroll bar allows you to navigate the stages.

Stage Management

The left hand side of the panel has a list of workflow stages, which are executed in the sequence that they appear in this list. You can visualize the stages and how they connect in the workflow diagram.

Stage label

The label indicates the stage number, stage name, and the type of the stage. It is updated if the stage type or name is changed, or the stage is moved. If the stage settings are hidden, the label gives a brief summary of the main stage parameters. Click the label to expand or collapse the individual stage. You can also expand individual stages by clicking on the stage in the Workflow diagram.

stage management buttons

These buttons perform display and ordering operations on the stage. They allow for easy duplication and rearrangement of stages.

    Show or hide the contents of the stage. When hidden, only the stage number, label (if any) and these buttons are displayed. This is useful when you have a number of stages and want to compare two separate stages, for example.
    Move the stage up or down one place in the list.
Duplicate the stage. This is useful for creating similar stages with variations on the settings.
Delete the stage.

Stage type option menu

Select the type of simulation stage, from Workflow, Simulation, Molecular QM, Custom Script, or Flow control. When you select a stage type, the label is updated with the type, and the relevant settings are displayed below. Click on a stage type below to see the features for that option.

Stage and Workflow Buttons

These buttons allow you to add stages to the workflow, save the workflow, and manage existing workflows.

Append Stage button

Add a stage to the end of the workflow. By default, the stage is a Workflow stage and the preceding stage is set as the Parent stage.

Append Workflow button

Append stages from the saved workflows set. Opens the Load Workflow dialog box where you can select single stage workflows that are included by default, as well as any workflows you have previously saved.

Append Stages From File button

Add stages by importing them from a workflow file (.wfw) that is not in the default location. Opens a file selector, in which you can navigate to and open the file. All stages from the file are appended to the workflow.

Save as Workflow button

Save the current workflow in the standard location in your Schrödinger user resources directory. The Workflow Metadata dialog box opens, where you can enter the workflow Name and Description, any Tags, the associated Schrödinger Suite version, and the Creator of the workflow. The workflow is stored in a single plain text file with the extension _workflow.wfw. You can access any saved workflows from the Load Workflow dialog box, Manage Workflows dialog box, and Run Meta Workflow Panel.

Manage Workflows button

Opens the Manage Workflows dialog box, which lists single stage workflows that are included by default and any workflows you have previously saved. You can delete saved workflows by selecting it from the list and clicking the Delete button. Deleted workflows are no longer available from the Load Workflow dialog box or Run Meta Workflow Panel.

Workflow diagram

The Workflow diagram provides a graphical representation of the meta workflow.

Each stage in the workflow is represented by a circle. The label inside each circle indicates the name of the stage. Parent and child stages are connected by arrow (→) from the parent stage to the child stage. If a stage produces multiple output structures which launch duplicate workflows, it is indicated by triple arrows. A stage which requires other stages are connected to them by a dotted line (---). A stage which generates multiple output structures and launches duplicate workflows on those structures is indicated by multiple arrows (⇛) flowing from the stage.

The colors of the circles indicate the type of stage:

  • Tan (

    )—The stage uses a structure builder.
  • Cyan (

    )—The stage runs a molecular dynamics simulation.
  • Green (

    )—The stage runs a quantum mechanics calculation.
  • Gold (

    )—The stage uses a custom script.
  • Gray (

    )—The stage is a Flow control stage.
  • Magenta (

    )—Other. For example, a stage which involves trajectory analysis is magenta.

Click on a circle to expand the settings for that stage and collapses the other stages in the Stage Management section.

Job toolbar

Manage job submission and settings. See Job Toolbar for a description of this toolbar.

The Job Settings button opens the Meta Workflow Builder - Job Settings Dialog Box, where you can make settings for running the job.

Status bar

Use the Reset button to reset the panel to its default settings and clear any data from the panel. If the panel has a Job toolbar, you can also reset the panel from the Settings button menu.

If you can submit a job from the panel, the status bar displays information about the current job settings and status for the panel. The settings include the job name, task name and task settings (if any), number of subjobs (if any) and the host name and job incorporation setting. The job status can include messages about job start, job completion and incorporation.

The status bar also contains the Help button , which opens an option menu with choices to open the help topic for the panel (Documentation), launch Maestro Assistant, or if available, choose from an option menu of Tutorials. If the panel is used by one or more tutorials, hover over the Tutorials option to display a list of tutorials. Choosing a tutorial opens the tutorial topic.