Introduction

With OVITO’s Python module you can

  • automate simulation post-processing, visualization, and data analysis tasks,

  • integrate OVITO’s file I/O, data analysis, and rendering capabilities into custom workflows and external Python programs,

  • develop new modifiers, file readers, and viewport layers that are fully integrated into the OVITO Pro desktop application.

Automation scripts

A common use case for OVITO’s Python programming interface is to automate laborious tasks, which you would otherwise have to perform by hand in the OVITO desktop application. The Python API lets you carry out all actions non-interactively.

The following example script remove_hydrogens.py loads an atomic structure from a simulation data file, selects all hydrogen atoms, deletes them, and writes the resulting structure back to an output file:

from ovito.io import import_file, export_file
from ovito.modifiers import SelectTypeModifier, DeleteSelectedModifier

pipeline = import_file('input.data')
pipeline.modifiers.append(SelectTypeModifier(property='Particle Type', types={'H'}))
pipeline.modifiers.append(DeleteSelectedModifier())
export_file(pipeline, 'output.xyz', 'xyz', columns=['Particle Type', 'Position.X', 'Position.Y', 'Position.Z'])

Like in the OVITO desktop application, the described task is performed by first building up a data pipeline containing two modifiers, which gets executed when writing the results to an output file.

Tip

Automation scripts like this can be easily created with OVITO Pro’s built-in code generator, which frees you from writing the Python code yourself.

You can then run the above Python script from the system terminal using your Python 3.x interpreter:

python3 remove_hydrogens.py

Important

For this to work, you first need to install the ovito module in your Python interpreter as will be explained later.

Executing scripts within the OVITO Pro application

Python scripts may also be executed within the context of an interactive session of the OVITO Pro desktop application thanks to its embedded Python interpreter. This possibility is useful during script development since it allows you to directly observe what your automation script is doing and how the outcome looks like in the interactive 3d viewports.

In OVITO Pro, use the Run Script File menu function to execute a Python automation script. The script’s actions will be executed in the context of the current program session – as if you would perform them by hand.

Extending OVITO Pro with custom modifiers, file readers, and viewport layers

OVITO’s scripting interface enables you to develop new types of modifiers that manipulate or analyze simulation data in ways not covered by any of the built-in modifiers of the program. So-called Python script modifiers (see User-defined modifiers section for more information) participate in the data pipeline system of OVITO and behave just like the built-in modifiers from a user’s perspective. A script-based modifier is essentially a single Python function written by you, which gets executed by OVITO whenever the data pipeline needs to be evaluated.

See also