Python script modifier
The Python script modifier lets you write your own user-defined modifier function for manipulating or analyzing simulation data. Writing a user-defined modifier function is useful when the built-in modifiers of OVITO are insufficient to solve your specific problem.
The Python script modifier participates in OVITO's data pipeline system in the same way the built-in modifier types of OVITO do. Whenever it is invoked by the system as part of a pipeline evaluation, it executes a user-defined function that you write in the Python programming language. This function has full access to the data that is produced by the upstream part of the pipeline and may modify or extend the data if desired.
After inserting a new Python script modifier into the pipeline, you can open its code editor using the
modify(). Note that you are free to define additional helper functions
in case you want to invoke them as sub-routines from the main
The corresponding section of the scripting manual provides further
instructions on how to write a user-defined modifier function.
When you are done writing or changing the user-defined modifier function in the code editor, you need to press the
Commit and run script button in the editor's toolbar (the "Play" button). This will compile and run the code
currently in the code editor once. Note that during this commit step, the
modify() function itself does not
get invoked yet. Only the main program statements of the code are executed if there are any aside from the definition of the
modify() function. After the commit was successful, the modifier function will automatically and repeatedly be invoked by the system whenever
data pipeline results need to be recomputed.
This also means you have to write the
modify() function in a way such that it can be called an arbitrary number of times
and for arbitrary animation times. Since it is completely up to the system when and how often the
gets invoked, the function should not perform any actions that could have side effects on the global state of the program.
In other words, the function may only operate on the data that it receives from the system as an input parameter, and nothing else.
Reusing user-defined modifiers
The modifier panel contains an input field that lets you optionally assign a descriptive name to your
script modifier. This name will be displayed in the pipeline editor and
makes it easier for you to identify the modifier in case you use several different Python modifiers in a pipeline.
If you have written a user-defined modifier function that you would like to
re-use in future program sessions, it is possible to save the entire Python script modifier, including the source code of the
modify() function, as a modifier template. This template will appear as a new
entry in the list of available modifiers, allowing you to easily access your user-defined modifier in the future.