diff --git a/doc/src/pair_dipole.rst b/doc/src/pair_dipole.rst index 372ea26794..bd6bf483c4 100644 --- a/doc/src/pair_dipole.rst +++ b/doc/src/pair_dipole.rst @@ -78,12 +78,12 @@ Examples Description """"""""""" -Style *lj/cut/dipole/cut* computes interactions between pairs of particles -that each have a charge and/or a point dipole moment. In addition to -the usual Lennard-Jones interaction between the particles (Elj) the -charge-charge (Eqq), charge-dipole (Eqp), and dipole-dipole (Epp) -interactions are computed by these formulas for the energy (E), force -(F), and torque (T) between particles I and J. +Style *lj/cut/dipole/cut* computes interactions between pairs of +particles that each have a charge and/or a point dipole moment. In +addition to the usual Lennard-Jones interaction between the particles +(Elj) the charge-charge (Eqq), charge-dipole (Eqp), and dipole-dipole +(Epp) interactions are computed by these formulas for the energy (E), +force (F), and torque (T) between particles I and J. .. math:: @@ -112,18 +112,18 @@ interactions are computed by these formulas for the energy (E), force \frac{3}{r^5} (\vec{p_i} \bullet \vec{r}) (\vec{p_j} \times \vec{r}) -where :math:`q_i` and :math:`q_j` are the charges on the two particles, -:math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole moment vectors of -the two particles, r is their separation distance, and the vector r = -Ri - Rj is the separation vector between the two particles. Note that -Eqq and Fqq are simply Coulombic energy and force, Fij = -Fji as -symmetric forces, and Tij != -Tji since the torques do not act -symmetrically. These formulas are discussed in :ref:`(Allen) ` -and in :ref:`(Toukmaji) `. +where :math:`q_i` and :math:`q_j` are the charges on the two +particles, :math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole +moment vectors of the two particles, r is their separation distance, +and the vector r = Ri - Rj is the separation vector between the two +particles. Note that Eqq and Fqq are simply Coulombic energy and +force, Fij = -Fji as symmetric forces, and Tij != -Tji since the +torques do not act symmetrically. These formulas are discussed in +:ref:`(Allen) ` and in :ref:`(Toukmaji) `. Also note, that in the code, all of these terms (except Elj) have a -:math:`C/\epsilon` prefactor, the same as the Coulombic term in the LJ + -Coulombic pair styles discussed :doc:`here `. C is an +:math:`C/\epsilon` prefactor, the same as the Coulombic term in the +LJ + Coulombic pair styles discussed :doc:`here `. C is an energy-conversion constant and epsilon is the dielectric constant which can be set by the :doc:`dielectric ` command. The same is true of the equations that follow for other dipole pair @@ -135,11 +135,11 @@ moment. In general, a shifted-force potential is a (slightly) modified potential containing extra terms that make both the energy and its derivative go to zero at the cutoff distance; this removes (cutoff-related) problems in energy conservation and any numerical -instability in the equations of motion :ref:`(Allen) `. Shifted-force -interactions for the Lennard-Jones (E_LJ), charge-charge (Eqq), -charge-dipole (Eqp), dipole-charge (Epq) and dipole-dipole (Epp) -potentials are computed by these formulas for the energy (E), force -(F), and torque (T) between particles I and J: +instability in the equations of motion :ref:`(Allen) +`. Shifted-force interactions for the Lennard-Jones (E_LJ), +charge-charge (Eqq), charge-dipole (Eqp), dipole-charge (Epq) and +dipole-dipole (Epp) potentials are computed by these formulas for the +energy (E), force (F), and torque (T) between particles I and J: .. math:: @@ -207,65 +207,59 @@ potentials are computed by these formulas for the energy (E), force where :math:`\epsilon` and :math:`\sigma` are the standard LJ parameters, :math:`r_c` is the cutoff, :math:`q_i` and :math:`q_j` are the charges on the two particles, :math:`\vec{p_i}` and -:math:`\vec{p_j}` are the dipole moment vectors of the two particles, r -is their separation distance, and the vector r = Ri - Rj is the -separation vector between the two particles. Note that Eqq and Fqq are -simply Coulombic energy and force, Fij = -Fji as symmetric forces, and -Tij != -Tji since the torques do not act symmetrically. The +:math:`\vec{p_j}` are the dipole moment vectors of the two particles, +r is their separation distance, and the vector r = Ri - Rj is the +separation vector between the two particles. Note that Eqq and Fqq +are simply Coulombic energy and force, Fij = -Fji as symmetric forces, +and Tij != -Tji since the torques do not act symmetrically. The shifted-force formula for the Lennard-Jones potential is reported in :ref:`(Stoddard) `. The original (non-shifted) formulas for the electrostatic potentials, forces and torques can be found in -:ref:`(Price) `. The shifted-force electrostatic potentials have -been obtained by applying equation 5.13 of :ref:`(Allen) `. The -formulas for the corresponding forces and torques have been obtained by -applying the 'chain rule' as in appendix C.3 of :ref:`(Allen) `. +:ref:`(Price) `. The shifted-force electrostatic potentials +have been obtained by applying equation 5.13 of :ref:`(Allen) +`. The formulas for the corresponding forces and torques have +been obtained by applying the 'chain rule' as in appendix C.3 of +:ref:`(Allen) `. If one cutoff is specified in the pair_style command, it is used for both the LJ and Coulombic (q,p) terms. If two cutoffs are specified, they are used as cutoffs for the LJ and Coulombic (q,p) terms -respectively. This pair style also supports an optional *scale* keyword -as part of a pair_coeff statement, where the interactions can be -scaled according to this factor. This scale factor is also made available -for use with fix adapt. +respectively. This pair style also supports an optional *scale* +keyword as part of a pair_coeff statement, where the interactions can +be scaled according to this factor. This scale factor is also made +available for use with fix adapt. -Style *lj/cut/dipole/long* computes long-range point-dipole -interactions as discussed in :ref:`(Toukmaji) `. Dipole-dipole, -dipole-charge, and charge-charge interactions are all supported, along -with the standard 12/6 Lennard-Jones interactions, which are computed -with a cutoff. A :doc:`kspace_style ` must be defined to -use this pair style. Currently, only :doc:`kspace_style ewald/disp ` support long-range point-dipole -interactions. +Style *lj/cut/dipole/long* computes the short-range portion of +point-dipole interactions as discussed in :ref:`(Toukmaji) +`. Dipole-dipole, dipole-charge, and charge-charge +interactions are all supported, along with the standard 12/6 +Lennard-Jones interactions, which are computed with a cutoff. A +:doc:`kspace_style ` must be defined to use this pair +style. It can be one of these options, all of which compute the +long-range portion of dipole-dipole interactions: -Style *lj/long/dipole/long* also computes point-dipole interactions as -discussed in :ref:`(Toukmaji) `. Long-range dipole-dipole, -dipole-charge, and charge-charge interactions are all supported, along -with the standard 12/6 Lennard-Jones interactions. LJ interactions -can be cutoff or long-ranged. +* :doc:`kspace_style ewald/dipole ` +* :doc:`kspace_style ewald/disp/dipole ` +* :doc:`kspace_style pppm/dipole ` -For style *lj/long/dipole/long*, if *flag_lj* is set to *long*, no -cutoff is used on the LJ 1/r\^6 dispersion term. The long-range -portion is calculated by using the :doc:`kspace_style ewald_disp ` command. The specified LJ cutoff then -determines which portion of the LJ interactions are computed directly -by the pair potential versus which part is computed in reciprocal -space via the Kspace style. If *flag_lj* is set to *cut*, the LJ -interactions are simply cutoff, as with :doc:`pair_style lj/cut `. If *flag_lj* is set to *off*, LJ interactions -are not computed at all. +Style *lj/long/dipole/long* has options to compute the short-range +portion of both 12/6 Lennard-Jones (LJ) and point-dipole interactions +in a long-range context. The options are selected by the *flag_lj* +and *flag_coul* setings. For *flag_coul* is set to *long*, +point-dipole interactions are computed as as discussed in +:ref:`(Toukmaji) `. Dipole-dipole, dipole-charge, and +charge-charge interactions are all supported. If *flag_coul* is set +to *off*, no charge and dipole interactions are computed. -If *flag_coul* is set to *long*, no cutoff is used on the Coulombic or -dipole interactions. The long-range portion is calculated by using -*ewald_disp* of the :doc:`kspace_style ` command. If -*flag_coul* is set to *off*, Coulombic and dipole interactions are not -computed at all. +For LJ interactions, the *flag_lj* setting can be *long*, *cut*, or +*off*. If *long* is used, the doc:`kspace_style ewald/disp/dipole +` command must be used. If *cut* is used, LJ +interactions are only short-range and any of the 3 solvers listed +above for style *lj/cut/dipole/long* can be used. If *off* is used, +no LJ interactions are not computed. Any of the 3 solvers listed +above can be used for Coulombic long-range interactions. -Atoms with dipole moments should be integrated using the :doc:`fix nve/sphere update dipole ` or the :doc:`fix nvt/sphere update dipole ` command to rotate the -dipole moments. The *omega* option on the :doc:`fix langevin ` command can be used to thermostat the -rotational motion. The :doc:`compute temp/sphere ` -command can be used to monitor the temperature, since it includes -rotational degrees of freedom. The :doc:`atom_style hybrid dipole sphere ` command should be used since -it defines the point dipoles and their rotational state. -The magnitude and orientation of the dipole moment for each particle -can be defined by the :doc:`set ` command or in the "Atoms" section -of the data file read in by the :doc:`read_data ` command. +---------- The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples @@ -287,6 +281,40 @@ type pair. ---------- +Note that for systems using these pair styles, typically particles +should be able to exert torque on each other via their dipole moments +so that the particle and its dipole moment can rotate. This requires +they not be point particles, but finite-size spheres. Thus you should +use a command like :doc:`atom_style hybrid sphere dipole ` +to use particles with both attributes. + +The magnitude and orientation of the dipole moment for each particle +can be defined by the :doc:`set ` command or in the "Atoms" +section of the data file read in by the :doc:`read_data ` +command. + +Rotating finite-size particles have 6 degrees of freedom (DOFs), +translation and rotational. You can use the :doc:`compute temp/sphere +` command to monitor a temperature which includes +all these DOFs. + +Finite-size particles with dipole moments should be integrated using +one of these options: + +* :doc:`fix nve/sphere update dipole ` +* :doc:`fix nve/sphere update dipole ` plus :doc:`fix langevin omega yes ` +* :doc:`fix nvt/sphere update dipole ` +* :doc:`fix npt/sphere update dipole ` + +In all cases the "update dipole" setting insures the dipole moments +are also rotated when the finite-size spheres rotate. The 2nd and 3rd +bullets perform thermostatting; in the case of a Langevin thermostat +the "omega yes" option also thermostats the rotational degrees of +freedom (if desired). The 4th bullet performs thermostatting and +barostatting. + +---------- + .. include:: accel_styles.rst ----------