Python script modifier

The Python script modifier allows you to write your own modifier function and manipulate or analyze the simulation data in any way you want. This is useful in cases where the available standard modifiers of OVITO are not sufficient for your purposes.

A Python script modifier participates in OVITO's data pipeline system like the built-in modifiers do. It consists of a user-defined Python function that you write. This function is automatically invoked by the system in a callback fashion every time the data pipeline is re-evaluated.

Please take a look at the Running Scripts manual section first to understand the different ways Python scripting is used within OVITO. Python-based modifiers provide a way to extend the functionality of OVITO. This is in contrast to regular Python scripts, which allow you to automate tasks and programmatically invoke built-in program functions (e.g. adding a modifier to the data pipeline and configuring its parameters).

Applications

The Python script modifier of OVITO allows you to develop your own type of data modifier, which can directly operate on or manipulate the simulation data in the way you need it. The user-defined modifier function participates in the data pipeline architecture of OVITO and can be used like the built-in standard modifiers. Typical applications of a Python script modifier are:

  • Selecting particles in a way not covered by the Expression select modifier.

  • Compute a new scalar quantity from the simulation data or the output generated by other modifiers in the pipeline, which can then be exported to a text file using OVITO's file export function.

  • Assign a new particle property or manipulate the values of an existing property in a more complex way than what is possible with the Compute property modifier.

  • Develop special analysis algorithms that require direct access to individual particles, their properties, bonds, and neighbors, for example.

Usage

The Edit script button in the modifies panel opens the code editor. This is where you can enter the Python code for the custom modifier function, which must be named modify(). How to write a Python modifier function is described in detail in the Scripting Manual. Note that the custom modify() function is automatically executed by the system whenever the pipeline is re-evaluated (e.g. when the input data changes). That means it is called repeatedly and should not manipulate the global program state or the pipeline itself.

Note that you have to press Commit and run script button in the code editor's toolbar after you are done editing the Python script. This will recompile the code and trigger a new evaluation of the data pipeline and your modifier script.

Furthermore, the text field at the top of the modifier panel allows you to assign a custom name to the script modifier. This name will be shown in the pipeline editor and makes it easier for you to find the modifier in the pipeline list. Also note that it is possible to save the Python script modifier including your code as a modifier preset. This preset will appear as an additional entry in the list of available modifiers, allowing you to easily access your user-defined modifier in future program sessions.