.. _particles.modifiers.create_bonds:

Create bonds
------------

.. image:: /images/modifiers/create_bonds_panel.png
  :width: 30%
  :align: right

This modifier creates new :ref:`bonds <scene_objects.bonds>` between pairs of particles according to a distance-based criterion.
Existing bonds will not be affected by the modifier, and it will not create another bond for a pair of particles that is already connected by a bond.

.. figure:: /images/modifiers/create_bonds_example_input.png
  :figwidth: 20%
  
  Input

.. figure:: /images/modifiers/create_bonds_example_output.png
  :figwidth: 20%
  
  Output

The modifier supports three modes of operation that use different criteria to decide which particles to connect by a bond:

Uniform cutoff distance
  The same uniform cutoff distance is used to create bonds between pairs of particles, irrespective of their respective type(s).

Van der Waals radii
  A bond is created between two atoms if their separation is less than 60% of the sum of their van der Waals radii. This standard criterion has been 
  adopted from the popular software :program:`VMD`. The Van der Waals radii of all particle types of the system are displayed in the table. OVITO initializes these 
  values during file import based on the chemical element names found in the input file. If needed, you can override the standard Van der Waals radius of each atom type 
  in the :ref:`particle type <scene_objects.particle_types>` editor or, permanently, in the :ref:`application settings <application_settings.particles>` dialog. 
  The *Create bonds* modifier will only create bonds between pairs of particles which both have a positive Van der Waals radius.

  Furthermore, the option :guilabel:`Don't generate H-H bonds` is turned on by default, which means the modifier will not generate any bonds connecting 
  two hydrogen atoms, i.e., which both have a particle type named "H" - even if they fulfill the distance-based criterion.

Pair-wise cutoffs
  This mode gives you full control over the bond distance cutoff for each pair-wise combination of particle types.
  The table lists all pair-wise type combinations defined for the current system, and some of the cutoff values in the third column may already be pre-initialized according to the Van der Waals 
  criterion described above. A positive cutoff value is needed to create bonds between pairs of particles of the given type(s).
  Note that this mode is only available if particle types have been defined for the system, i.e., the particle property ``Particle Type`` exists.

The option :guilabel:`Suppress inter-molecular bonds` restricts generation of bonds to particles that
are part of the same molecule, i.e. which have matching values of the ``Molecule Identifier`` property.
If the ``Molecule Identifier`` particle property is not defined for the system, this option has no effect.

The modifier lets you specify an optional :guilabel:`Lower cutoff` value. It effectively restricts the generation of bonds
to the distance interval between the lower and upper cutoffs.

The modifier defines a new bond type, which is assigned to the newly created bonds.
The properties of this bond type, in particular its name and display color, can be edited in the second parameter panel.
Furthermore, the modifier will automatically create a :ref:`bonds visual element <visual_elements.bonds>` if needed, 
which lets you control the visual appearance of bonds. The display settings of this visual element are found in the third parameter panel.

As for particles, OVITO supports the assignment of arbitrary properties to bonds which have been generated by this modifier or which were created during simulation file import.
Certain bond properties (see :ref:`this section <usage.bond_properties.special>`) are used by OVITO
to control the visualization of bonds. By changing the values of these properties, for example using the :ref:`particles.modifiers.compute_property` modifier,
you can adjust the visual representation of individual bonds.

Technical notes
"""""""""""""""

OVITO stores a triplet of integer numbers with every bond in the ``Periodic Image`` property field.
This triplet specifies whether a bond crosses the periodic boundaries of the simulation cell (if any) and in which direction.
For example, a bond crossing the periodic cell boundary in the positive X direction is associated with the triplet (1,0,0) and
will be visualized as two separate half bonds, one on either end of the cell. Bonds in the interior of the simulation box which do not cross a
periodic boundary have a ``Periodic Image`` value of (0,0,0).

.. seealso::
  
  :py:class:`ovito.modifiers.CreateBondsModifier` (Python API)
