<?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.create_bonds"
         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>Create bonds</title>

  <para>
  
   <informalfigure>
      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row valign="bottom">
              <entry>Input:</entry>
              <entry>Output:</entry>
            </row>
            <row valign="top">
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/create_bonds_example_input.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/create_bonds_example_output.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
    
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/create_bonds_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>

	This modifier creates bonds between particles using a cutoff-based criterion.
  </para>
  
  <para>
    The visual appearance of the generated bonds is controlled by the <link linkend="display_objects.bonds">bonds
    display object</link> attached to the modifier. 
  </para>
  
  <simplesect>
    <title>Parameters</title>
 	<para>The modifier supports two different modes that determine how bonds are created between particles:</para>
 	
    <variablelist>
      <varlistentry>
        <term>Uniform cutoff radius</term>
        <listitem>
          <para>Use this mode to create bonds between pairs of particles irrespective of their types if the pair separation is below  
                the specified cutoff.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Pair-wise cutoff radii</term>
        <listitem>
          <para>This mode gives you more control over which particle types get connected by bonds. 
          The table lists all pair-wise combinations of particle types. Enter a cutoff distance into the third
          column to connect pairs of particles of the given types with bonds. </para>
          <para>Note that is mode is only available if the <literal>Particle Type</literal> property is defined for particles.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>No bonds between different molecules</term>
        <listitem>
          <para>If this option is active, bonds will only be created between particles that belong to the same molecule.
          Two particles belong to the same molecule if their <literal>Molecule Identifier</literal> property values
          are the same. If the <literal>Molecule Identifier</literal> property is not defined for the particles, this option has no effect.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Lower cutoff</term>
        <listitem>
          <para>This parameter allows to set a lower cutoff, i.e. a minimum length, for the bonds to be created.</para>
        </listitem>
      </varlistentry>
    </variablelist>
     	  
  </simplesect>
  
 <simplesect>
    <title>Technical background information</title>
 	<para>OVITO stores each bond generated by this modifier as a pair of particle indices. 
 	It makes sure that, if a particle is subsequently deleted, the dangling bonds are deleted too.
 	</para>
 	<para>In addition to the two particle indices, OVITO stores a periodic shift vector with every bond. 
 	This shift vector indicates whether the bond crosses a periodic boundary of the simulation cell. 
 	The shift vector of bonds that do not cross a periodic boundary is (0,0,0). A bond that crosses a 
 	periodic cell boundary in the positive X direction, for instance, has the shift vector (1,0,0) and 
 	will be displayed as two half bonds.
 	</para>
  </simplesect>
    
</section>
