Python script modifier pro

This modifier type lets you write your own user-defined function in the Python language to manipulate, analyze or extend the simulation data. User-defined modifier functions are useful when the toolset of built-in modifiers of OVITO is insufficient to solve your specific problem.

The system executes the user-defined Python function whenever it needs to recompute the results of the data pipeline, e.g. when jumping to a new frame of the loaded trajectory. Tne integrated code editor window lets you edit the function's source code and implement your own data processing algorithms. Within the user-defined Python function you have complete access to the input dataset produced by the upstream data pipeline, with the possibility to manipulate or extend the dataset as needed via OVITO's comprehensive Python programming interface.

Usage

After inserting a new Python script modifier into the pipeline you can open the integrated code editor using the Code editor button. The editor window lets you change the source code for the user-defined modifier function, which initially consists of a few example statements. You should replace these statements with your own code, performing the specific computations or actions that are needed to solve your problem. The scripting manual gives further instructions on how to write the user-defined modifier function. Note that the Python function must be named modify(), however, you are free to define additional functions within the same source file and call them as sub-routines from the main modifier function.

Once you are done writing the user-defined modifier function, press the Commit and run script button in the code editor window (the "Play" button). This will compile the code by executing any top-level statements including the function definition and then request an update of the data pipeline. As part of this pipeline update your modify() function will get invoked by the system.

Note that the pipeline system may run your modify() function repeatedly, for example when stepping through a simulation trajectory. That means you should always write your modify() function in such a way that it doesn't have any side effects on the global state of OVITO. The function should be "pure" and stateless in the sense that it only operates on the current dataset received from the system as a function parameter. The pipeline is free to decide whether it caches the results of your modifier function, and it may call your function repeatedly if necessary. Thus, the function must be designed such that it can process each trajectory frame in isolation.

Making the modifier function permanently available in OVITO

First, you should give your modifier a meaningful name, making it easier for you to identify the modifier in the data pipeline. The pipeline editor of OVITO lets you to change the title of the modifier from the default "Python script" to a more descriptive label that better summarizes the specific purpose of your Python function. In order to rename a modifier in the pipeline editor, make sure it is selected and then click the pipeline item a second time to edit its name.

Next, you have two alternative ways of making your Python modifier permanently available in future program sessions. One is to save the current modifier, including the source code of the modify() function, as a modifier template. The modifier template will appear as a new entry in the list of available modifiers, allowing you to easily access the user-defined modifier in the future and insert it into a new data pipeline.

The second option is to save the source code as a .py file in one of the following directories on your computer. OVITO Pro will automatically scan these directories and display all .py scripts in the available modifiers list, from where you can inserted them into a data pipeline with a single click.

  • All platforms: <HOME>/.config/Ovito/scripts/modifiers/*.py
  • Linux: <INSTALLDIR>/share/ovito/scripts/modifiers/*.py
  • Windows: <INSTALLDIR>/scripts/modifiers/*.py
  • macOS: <INSTALLDIR>/Ovito.app/Contents/Resources/scripts/modifiers/*.py
  • Anaconda: <INSTALLDIR>/share/ovito/scripts/modifiers/*.py

Here, <HOME> and <INSTALLDIR> refer to your home directory and the installation location of OVITO Pro on your computer, respectively. The latter location already contains a bunch of predefined Python modifier files shipping with the program.