.. _particles.modifiers.bond_length_distribution:

Bond length distribution |ovito-pro|
------------------------------------

.. image:: /images/modifiers/bond_length_distribution_panel.png
  :width: 35%
  :align: right

This modifier computes the distribution of the **bond lengths**, i.e., the histogram of distances between pairs of
particles connected by :ref:`bonds <scene_objects.bonds>`.

The modifier only includes :ref:`bonded <scene_objects.bonds>` particles in the distribution,
whereas non-bonded pairs will be ignored. Typically, the bond topology is read from the
input simulation file or it needs to be generated within OVITO using the :ref:`particles.modifiers.create_bonds` modifier.

For computing the radial distribution function (RDF), i.e., the histogram of the distances between *all* pairs of
particles, including non-bonded ones, you can use the :ref:`particles.modifiers.radial_distribution_function` modifier instead.
The :ref:`particles.modifiers.bond_angle_distribution` modifier computes the distribution of angles formed by triplets of bonded particles.

.. versionchanged:: 3.15.0
  This modifier partially replaces the functionality of the "Bond Analysis" modifier found in earlier program versions.

Bond length distribution
""""""""""""""""""""""""

The bond length histogram ranges from 0 to the cutoff parameter of the modifier.
Bonds exceeding the specified length cutoff will not be included in the bond length distribution.

The modifier outputs the bond length histogram as a :ref:`data table <scene_objects.data_table>`, which can be opened in the
pipeline data inspector using the button :guilabel:`Show in data inspector`.

Partitioned distributions
"""""""""""""""""""""""""

The modifier can break the computed distribution down into several partial histograms,
one for each combination of bond or particle types. The following partitioning modes are available:

Bond type
  Computes a separate bond length histogram for each individual bond type.

Bond selection
  Treats currently selected bonds and unselected bonds as two different kinds of bonds,
  thus computing two separate bond length histograms.

Particle type
  Computes separate bond length histograms for each pair-wise combination of particle types.
  If the number of particle types in the system is :math:`N`,
  then the bond length distribution, which involves pairs of particles, will be partitioned into
  :math:`N (N+1)/2` partial distributions.

Particle selection
  Treats currently selected and unselected particles as two different species.
  Computes three separate bond length histograms: one for bonds connecting two selected particles,
  one for bonds connecting two unselected particles, and one for bonds connecting one selected and one unselected particle.

Time-averaged distributions
"""""""""""""""""""""""""""

The *Bond length distribution* modifier calculates the instantaneous bond length distribution for
just one simulation frame at a time. You can subsequently apply the :ref:`particles.modifiers.time_averaging` modifier to reduce
the instantaneous distributions to a single mean distribution by averaging the
output :ref:`data table <scene_objects.data_table>` over all frames of the loaded MD trajectory.

.. seealso::

  :py:class:`ovito.modifiers.BondLengthDistributionModifier` (Python API)