<?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>
      <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/python_script_code_editor.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    
    The <emphasis>Python script</emphasis> modifier allows you to write your own modifier function and manipulate or analyze the simulation data in any way you want.
    This is useful in cases where the available <link linkend="particles.modifiers">standard modifiers</link> of OVITO are not sufficient for your purposes.
    </para>
  <para>
    A <emphasis>Python script</emphasis> modifier participates in OVITO's data pipeline system like the built-in modifiers do.
    It consists of a user-defined Python function that you write. This function is automatically invoked by the system in a callback fashion every time
    the data pipeline is re-evaluated.
  </para>
  
  <para>
    Please 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 <guibutton>Edit script</guibutton> button in the modifies panel opens the code editor.
    This is where you can enter the Python code for 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 <emphasis>Commit and run script</emphasis> button in the code editor's toolbar after you are done editing
    the Python script. This will recompile the code and trigger a new evaluation of the data pipeline and your modifier script.
  </para>
  
  <para>
    Furthermore, the text field at the top of the modifier panel allows you to assign a custom 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 pipeline list.
    Also note that it is possible to save the Python script modifier including your 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 your user-defined modifier in future program sessions.
  </para>
  
  </simplesect>
  
</section>
