.. index:: angle_style dipole

angle_style dipole command
==========================

angle_style dipole/omp command
==============================

Syntax
""""""

.. code-block:: LAMMPS

   angle_style dipole

Examples
""""""""

.. code-block:: LAMMPS

   angle_style dipole
   angle_coeff 6 2.1 180.0

Description
"""""""""""

The *dipole* angle style is used to control the orientation of a dipolar
atom within a molecule :ref:`(Orsi) <Orsi>`. Specifically, the *dipole* angle
style restrains the orientation of a point dipole :math:`\mu_j` (embedded in atom
:math:`j`) with respect to a reference (bond) vector
:math:`\vec{r_{ij}} = \vec{r_i} - \vec{r_j}`, where :math:`i` is another atom of
the same molecule (typically, :math:`i` and :math:`j` are also covalently bonded).

It is convenient to define an angle gamma between the 'free' vector :math:`\vec{\mu_j}`
and the reference (bond) vector :math:`\vec{r_{ij}}`:

.. math::

   \cos\gamma = \frac{\vec{\mu_j}\cdot\vec{r_{ij}}}{\mu_j\,r_{ij}}

The *dipole* angle style uses the potential:

.. math::

   E = K (\cos\gamma - \cos\gamma_0)^2

where :math:`K` is a rigidity constant and gamma0 is an equilibrium (reference)
angle.

The torque on the dipole can be obtained by differentiating the
potential using the 'chain rule' as in appendix C.3 of
:ref:`(Allen) <Allen1>`:

.. math::

   \vec{T_j} = \frac{2K(\cos\gamma - \cos\gamma_0)}{\mu_j\,r_{ij}}\, \vec{r_{ij}} \times \vec{\mu_j}

Example: if :math:`\gamma_0` is set to 0 degrees, the torque generated by
the potential will tend to align the dipole along the reference
direction defined by the (bond) vector :math:`\vec{r_{ij}}` (in other words, :math:`\vec{\mu_j}` is
restrained to point towards atom :math:`i`).

The dipolar torque :math:`\vec{T_j}` must be counterbalanced in order to conserve
the local angular momentum. This is achieved via an additional force
couple generating a torque equivalent to the opposite of :math:`\vec{T_j}`:

.. math::

   -\vec{T_j} & = \vec{r_{ij}} \times \vec{F_i} \\
   \vec{F_j}  & = -\vec{F_i}

where :math:`\vec{F_i}` and :math:`\vec{F_j}` are applied on atoms :math:`i`
and :math:`j`, respectively.

The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:

* :math:`K` (energy)
* :math:`\gamma_0` (degrees)

----------

.. include:: accel_styles.rst

Restrictions
""""""""""""

This angle style can only be used if LAMMPS was built with the
USER-MISC package.  See the :doc:`Build package <Build_package>` doc
page for more info.

.. note::

   In the "Angles" section of the data file, the atom ID :math:`j`
   defining the direction of the dipole vector to restrain must come
   before the atom ID of the reference atom :math:`i`. A third atom ID :math:`k` must
   also be provided to comply with the requirement of a valid angle
   definition. This atom ID :math:`k` should be chosen to be that of an atom
   bonded to atom :math:`i` to avoid errors with "lost angle atoms" when running
   in parallel. Since the LAMMPS code checks for valid angle definitions,
   cannot use the same atom ID of either :math:`i` or :math:`j` (this was allowed
   and recommended with older LAMMPS versions).

The :doc:`newton <newton>` command for intramolecular interactions must be "on"
(which is the default except when using some accelerator packages).

This angle style should not be used with SHAKE.

Related commands
""""""""""""""""

:doc:`angle_coeff <angle_coeff>`, :doc:`angle_hybrid <angle_hybrid>`

**Default:** none

----------

.. _Orsi:

**(Orsi)** Orsi & Essex, The ELBA force field for coarse-grain modeling of
lipid membranes, PloS ONE 6(12): e28637, 2011.

.. _Allen1:

**(Allen)** Allen & Tildesley, Computer Simulation of Liquids,
Clarendon Press, Oxford, 1987.