<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="particles.modifiers.python_script"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Python script modifier</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/python_script_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    
    In cases where the available <link linkend="particles.modifiers">standard modifiers</link>  provided by OVITO are not sufficient for your purposes,
    the special <emphasis>Python script</emphasis> modifier allows you to write your own modifier function and directly manipulate or analyze simulation data in any way you want.
    A <emphasis>Python script</emphasis> 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.
  </para>
  
  <para>
    Please make sure you take a look at the <link xlink:href="python/introduction/running.html#running-scripts">Running Scripts</link> manual section first to
    understand the different ways Python scripting is used within OVITO. Python-based <emphasis>modifiers</emphasis> 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).
  </para>
  
  <simplesect>
    <title>Applications</title>
  
  <para>
    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:
    <itemizedlist>  
    <listitem><para>Selecting particles in a way not covered by the <link linkend="particles.modifiers.expression_select">Expression select</link> modifier.</para></listitem>
    <listitem><para>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 <link linkend="usage.export">file export function</link>.</para></listitem>
    <listitem><para>Assign a new particle property or manipulate the values of an existing property in a more complex way than what is possible with the <link linkend="particles.modifiers.compute_property">Compute property</link> modifier.</para></listitem>
    <listitem><para>Develop special analysis algorithms that require direct access to individual particles, their properties, bonds, and neighbors, for example.</para></listitem>
    </itemizedlist>
  </para>
  
  </simplesect>
  
  <simplesect>
    <title>Usage</title>
  
  <para>
    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 <code>modify()</code>.
    How to write a Python modifier function is described in detail in  
    the <link xlink:href="python/introduction/custom_modifiers.html">Scripting Manual</link>.
    Note that the custom <code>modify()</code> 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.    
  </para>
  
  <para>
    Note that you have to press <guibutton>Commit script</guibutton> 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.
  </para>
  
  <para>
    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 <link linkend="modifier_presets">modifier preset</link>. 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.
  </para>
  
  </simplesect>
  
</section>
