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.

Usage

After inserting a new Python script modifier into the pipeline, you can open its code editor using the Edit script button. The editor window lets you enter the source code for the user-defined modifier function. This Python function must be called modify(). Note that you are free to define additional helper functions in case you want to invoke them as sub-routines from the main modify() function. 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 modify() function 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.

See also

How to write user-defined modifier functions
PythonScriptModifier (Python API)