<?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="usage.particle_properties" 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>Particle properties</title>

  <simplesect>
    <title>Introduction</title>
    
	  <para>Particle properties are data values associated with every particle and play a central role in OVITO.
	  For example, the particle position, type, or velocity vector are all properties managed by OVITO.
	  Properties can be read from the imported simulation file, or their value can be computed within OVITO by a modifier.
	  The modifiers in the <link linkend="usage.modification_pipeline">modification pipeline</link> 
	  can access to existing properties, change them, or assign new properties to particles. 
	  For instance, the <link linkend="particles.modifiers.coordination_analysis">Coordination Analysis modifier</link> 
	  computes the number of neighbors of each particle and stores it in a new particle property named <literal>Coordination number</literal>. 
	  Subsequent modifiers in the pipeline, for instance a <link linkend="particles.modifiers.color_coding">Color Coding</link> modifier, can then
	  access this property; or you can <link linkend="usage.export">export the computed values to an output file</link>.
	  </para>
	  
	  <para>
	  Internally, each particle property is stored as a data array containing one record per particle. 
	  Properties can be scalar numbers or more complex quantities such as vectors or tensors.
	  The <literal>Position</literal> particle property, for instance, stores a vector with three components for each particle.
	  The individual vector components are referred to as <literal>Position.X</literal>, <literal>Position.Y</literal>, 
	  and <literal>Position.Z</literal> in OVITO's user interface. 
	  </para>
  </simplesect>

  <simplesect>
    <title>Standard properties</title>

	  <para>Furthermore, one can distinguish two types of particle properties: Standard properties and user-defined properties.
	  Standard properties have a predefined name, data type, and a specific meaning within OVITO.
	  The standard property <literal>Position</literal>, for instance, is used by the program to store the coordinates
	  of particles, and the <literal>Color</literal> property stores the display color of particles. 
	  User-defined properties, in contrast, simply contain arbitrary per-particle quantities (as read from a simulation file or .
	  This data is not interpreted by OVITO in a particular way. 
	  However, it can be used within the program, for instance, to <link linkend="particles.modifiers.expression_select">select particles</link>,
	  <link linkend="particles.modifiers.color_coding">color particles</link>, or <link linkend="particles.modifiers.compute_property">perform other computations</link>.
	  </para>
	
	  <para>As explained above, certain standard properties have a special meaning and control how OVITO displays particles. 
	  The following table lists some important standard properties and their function:
	   <informaltable>
	        <tgroup cols="3">
				<colspec colnum="1" colname="name" colwidth="2*" />
				<colspec colnum="2" colname="datatype" colwidth="1*" />
				<colspec colnum="3" colname="description" colwidth="4*" />
	          <thead>
	            <row>
	              <entry>Standard property</entry>
	              <entry>Data type / Components</entry>
	              <entry>Description</entry>
	            </row>
	          </thead>
	
	          <tbody>
	            <row>
	              <entry><literal>Position</literal></entry>
	              <entry>X, Y, Z</entry>
	              <entry><para>The particle coordinates.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Color</literal></entry>
	              <entry>R, G, B</entry>
	              <entry><para>If present, this property controls the display color of particles.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Radius</literal></entry>
	              <entry>Real</entry>
	              <entry><para>If present, this property controls the display size of particles.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Particle Type</literal></entry>
	              <entry>Integer</entry>
	              <entry><para>Stores the type identifier of each particle. This determines the particle display size and color 
	              unless the <emphasis>Radius</emphasis> or <emphasis>Color</emphasis> property are present.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Particle Identifier</literal></entry>
	              <entry>Integer</entry>
	              <entry><para>Stores the unique ID of each particle. This is used by some modifiers
	              to track particles over time if the storage order of particles changes between simulation
	              frames.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Transparency</literal></entry>
	              <entry>Real</entry>
	              <entry><para>A value between 0 and 1 controlling the particle transparency.</para></entry>
	            </row>
	            <row>
	              <entry><literal>Selection</literal></entry>
	              <entry>Integer</entry>
	              <entry><para>Stores the selection state of particles (1 for selected particles; 0 otherwise).</para></entry>
	            </row>
	          </tbody>
	        </tgroup>
	      </informaltable>
	      The <link linkend="particles.modifiers.compute_property">Compute Property</link> modifier gives you full control over the values of these properties.
	    </para>
  </simplesect>    

  <simplesect>
    <title>Input and output</title>
    <para>
       Most file formats used by simulation codes support an arbitrary number of 
       per-particle properties, which are stored in individual file columns. 
       When loading such a file into OVITO, the columns of the file must be mapped to OVITO's internal particle properties. It most cases this 
       happens automatically based on the metadata found in the file's header.
    </para>
    <para>
       Files in the XYZ format are an exception since they contain no metadata that could help OVITO to
       interpret the file's columns. When opening such a file, the program displays a dialog box to let you
       specify the mapping of file columns to particle properties. A similar step is necessary when 
       <link linkend="usage.export">exporting particle data to a file</link>: 
       You will be asked to specify which particle properties to export and in which order.
    </para>
  </simplesect>

</section>
