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.
After inserting a new Python script modifier into the pipeline you can open the integrated code editor using 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.
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.
<HOME>/.config/Ovito/scripts/modifiers/*.py
<INSTALLDIR>/share/ovito/scripts/modifiers/*.py
<INSTALLDIR>/scripts/modifiers/*.py
<INSTALLDIR>/Ovito.app/Contents/Resources/scripts/modifiers/*.py
<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.
The scripting manual contains several code examples
demonstrating how to write a modify()
function: