.. _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 are not affected by the modifier and the modifier won't create another bond between a pair of particles already connected
by an existing 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.

.. attention::

  In case the modifier generated more than 1,000,000 bonds, it will show a warning message and automatically turn off the display
  of the bonds as a precaution, because rendering too many bonds in the interactive viewports of OVITO on a slow machine could take exceedingly long and freeze
  the entire program. If desired, you can manually show the bonds again by re-enabling the :ref:`bonds visual element <visual_elements.bonds>` in the pipeline editor.

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

To correctly deal with periodic simulations, OVITO maintains a triplet of integer numbers with every bond, which is stored in the ``Periodic Image`` bond property array.
Each bond's triplet specifies whether that bond crosses the periodic boundaries of the simulation cell (and in which direction).
For example, a bond crossing the periodic cell boundary in the positive X direction is indicates by the triplet (1,0,0) and
will be visualized as two separate half bonds, one on either side of the simulation 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)
