In cases where the available standard modifiers provided by OVITO are not sufficient for your purposes, the special Python script modifier allows you to write your own modifier function and directly manipulate or analyze simulation data in any way you want. A Python script modifier participates in OVITO's data pipeline system like the built-in modifier types do. It essentially consists of a user-defined Python function that you write. This script function is automatically invoked by the system in a callback fashion every time the data pipeline is re-evaulated.
Please make sure you 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).
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.
The modifier's panel, which is shown on the right, provides an input field
where you enter the code of 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
after you are done editing the Python code in the input field. This will recompile the code and trigger a new evaluation of the data pipeline.Furthermore, the text field at the top of the panel allows you to assign a user-defined 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 list. Also note that it is possible to save the Python script modifier including the entered source code as a modifier preset. This preset will appear as an additional entry in the list of available modifiers, allowing you to easily access the custom modifier in future program sessions.