diff --git a/doc/_sources/pair_thole.txt b/doc/_sources/pair_thole.txt index 91cacd93c7..6cf4f1bb58 100644 --- a/doc/_sources/pair_thole.txt +++ b/doc/_sources/pair_thole.txt @@ -3,16 +3,31 @@ pair_style thole command ======================== +pair_style lj/cut/thole/long command +==================================== + +pair_style lj/cut/thole/long/omp command +======================================== + Syntax """""" .. parsed-literal:: - pair_style thole damp cutoff + pair_style style args -* thole = style name -* damp = global damping parameter -* cutoff = global cutoff +* style = *thole* or *lj/cut/thole/long* or *lj/cut/thole/long/omp* +* args = list of arguments for a particular style + +.. parsed-literal:: + + *thole* args = damp cutoff + damp = global damping parameter + cutoff = global cutoff (distance units) + *lj/cut/thole/long* or *lj/cut/thole/long/omp* args = damp cutoff (cutoff2) + damp = global damping parameter + cutoff = global cutoff for LJ (and Thole if only 1 arg) (distance units) + cutoff2 = global cutoff for Thole (optional) (distance units) Examples """""""" @@ -24,10 +39,14 @@ Examples pair_coeff 1 2 thole 1.0 2.6 10.0 pair_coeff * 2 thole 1.0 2.6 +.. parsed-literal:: + + pair_style lj/cut/thole/long 2.6 12.0 + Description """"""""""" -The *thole* pair style is meant to be used with force fields that +The *thole* pair styles are meant to be used with force fields that include explicit polarization through Drude dipoles. This link describes how to use the :doc:`thermalized Drude oscillator model ` in LAMMPS and polarizable models in LAMMPS are discussed in :ref:`this Section `. @@ -37,7 +56,17 @@ The *thole* pair style should be used as a sub-style within in the main pair style including Coulomb interactions, i.e. any pair style containing *coul/cut* or *coul/long* in its style name. -The *thole* pair style computes the Coulomb interaction damped at +The *lj/cut/thole/long* pair style is equivalent to, but more convenient that +the frequent combination *hybrid/overlay lj/cut/coul/long cutoff thole damp +cutoff2*. It is not only a shorthand for this pair_style combination, but +it also allows for mixing pair coefficients instead of listing them all. +The *lj/cut/thole/long* pair style is also a bit faster because it avoids an +overlay and can benefit from OMP acceleration. Moreover, it uses a more +precise approximation of the direct Coulomb interaction at short range similar +to :doc:`coul/long/cs `, which stabilizes the temperature of +Drude particles. + +The *thole* pair styles compute the Coulomb interaction damped at short distances by a function @@ -79,9 +108,9 @@ non-polarizable atoms are also subject to these weighting factors. The Drude particles inherit the 1-2, 1-3 and 1-4 neighbor relations from their respective cores. -The following coefficients must be defined for each pair of atoms -types via the :doc:`pair_coeff ` command as in the example -above. +For pair_style *thole*, the following coefficients must be defined for +each pair of atoms types via the :doc:`pair_coeff ` command +as in the example above. * alpha (distance units^3) * damp @@ -92,11 +121,60 @@ Thole damping parameter or global cutoff specified in the pair_style command are used. In order to specify a cutoff (third argument) a damp parameter (second argument) must also be specified. +For pair style *lj/cut/thole/long*, the following coefficients must be +defined for each pair of atoms types via the :doc:`pair_coeff ` +command. + +* epsilon (energy units) +* sigma (length units) +* alpha (distance units^3) +* damps +* LJ cutoff (distance units) + +The last two coefficients are optional and default to the global values from +the *pair_style* command line. + + +---------- + + +Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are +functionally the same as the corresponding style without the suffix. +They have been optimized to run faster, depending on your available +hardware, as discussed in :doc:`Section_accelerate ` +of the manual. The accelerated styles take the same arguments and +should produce the same results, except for round-off and precision +issues. + +These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL, +KOKKOS, USER-OMP and OPT packages, respectively. They are only +enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS ` section for more info. + +You can specify the accelerated styles explicitly in your input script +by including their suffix, or you can use the :ref:`-suffix command-line switch ` when you invoke LAMMPS, or you can +use the :doc:`suffix ` command in your input script. + +See :doc:`Section_accelerate ` of the manual for +more instructions on how to use the accelerated styles effectively. + **Mixing**: The *thole* pair style does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly. +The *lj/cut/thole/long* pair style does support mixing. Mixed coefficients +are defined using + + +.. math:: + + \begin{equation} \alpha_{ij} = \sqrt{\alpha_i\alpha_j}\end{equation} + + +.. math:: + + \begin{equation} a_{ij} = \frac 1 2 (a_i + a_j)\end{equation} + Restrictions """""""""""" @@ -108,10 +186,15 @@ This pair_style should currently not be used with the :doc:`charmm dihedral styl factors. This is because the *thole* pair style does not know which pairs are 1-4 partners of which dihedrals. +The *lj/cut/thole/long* pair style should be used with a :doc:`Kspace solver ` +like PPPM or Ewald, which is only enabled if LAMMPS was built with the kspace +package. + Related commands """""""""""""""" :doc:`fix drude `, :doc:`fix langevin/drude `, :doc:`fix drude/transform `, :doc:`compute temp/drude ` +`pair_style lj/cut/coul/long `_ **Default:** none diff --git a/doc/pair_thole.html b/doc/pair_thole.html index 86d87c1584..cd1cdaa93a 100644 --- a/doc/pair_thole.html +++ b/doc/pair_thole.html @@ -126,16 +126,30 @@

pair_style thole command

+
+
+

pair_style lj/cut/thole/long command

+
+
+

pair_style lj/cut/thole/long/omp command

Syntax

-
pair_style thole damp cutoff
+
pair_style style args
 

 

 
    
-
  • thole = style name
    • 
-
  • damp = global damping parameter
    • 
-
  • cutoff = global cutoff
    • 
+
  • style = thole or lj/cut/thole/long or lj/cut/thole/long/omp
    • 
+
  • args = list of arguments for a particular style
    • 
 

+
+thole args = damp cutoff
+  damp = global damping parameter
+  cutoff = global cutoff (distance units)
+lj/cut/thole/long or lj/cut/thole/long/omp args = damp cutoff (cutoff2)
+  damp = global damping parameter
+  cutoff = global cutoff for LJ (and Thole if only 1 arg) (distance units)
+  cutoff2 = global cutoff for Thole (optional) (distance units)
+

Examples

@@ -145,10 +159,13 @@ pair_coeff 1 2 thole 1.0 2.6 10.0 pair_coeff * 2 thole 1.0 2.6
+
pair_style lj/cut/thole/long 2.6 12.0
+
+

Description

-

The thole pair style is meant to be used with force fields that +

The thole pair styles are meant to be used with force fields that include explicit polarization through Drude dipoles. This link describes how to use the thermalized Drude oscillator model in LAMMPS and polarizable models in LAMMPS are discussed in this Section.

@@ -156,15 +173,24 @@ are discussed in pair_hybrid/overlay command, in conjunction with a main pair style including Coulomb interactions, i.e. any pair style containing coul/cut or coul/long in its style name.

-

The thole pair style computes the Coulomb interaction damped at +

The lj/cut/thole/long pair style is equivalent to, but more convenient that +the frequent combination hybrid/overlay lj/cut/coul/long cutoff thole damp +cutoff2. It is not only a shorthand for this pair_style combination, but +it also allows for mixing pair coefficients instead of listing them all. +The lj/cut/thole/long pair style is also a bit faster because it avoids an +overlay and can benefit from OMP acceleration. Moreover, it uses a more +precise approximation of the direct Coulomb interaction at short range similar +to coul/long/cs, which stabilizes the temperature of +Drude particles.

+

The thole pair styles compute the Coulomb interaction damped at short distances by a function

\[\begin{equation} T_{ij}(r_{ij}) = 1 - \left( 1 + \frac{s_{ij} r_{ij} }{2} \right) \exp \left( - s_{ij} r_{ij} \right) \end{equation}\]

This function results from an adaptation to point charges -(Noskov) of the dipole screening scheme originally proposed -by Thole. The scaling coefficient \(s_{ij}\) is determined +(Noskov) of the dipole screening scheme originally proposed +by Thole. The scaling coefficient \(s_{ij}\) is determined by the polarizability of the atoms, \(\alpha_i\), and by a Thole damping parameter \(a\). This Thole damping parameter usually takes a value of 2.6, but in certain force fields the value can depend upon @@ -188,9 +214,9 @@ interactions between Drude particles and core charges or non-polarizable atoms are also subject to these weighting factors. The Drude particles inherit the 1-2, 1-3 and 1-4 neighbor relations from their respective cores.

-

The following coefficients must be defined for each pair of atoms -types via the pair_coeff command as in the example -above.

+

For pair_style thole, the following coefficients must be defined for +each pair of atoms types via the pair_coeff command +as in the example above.

  • alpha (distance units^3)
  • damp
    • @@ -200,9 +226,43 @@ above.

    Thole damping parameter or global cutoff specified in the pair_style command are used. In order to specify a cutoff (third argument) a damp parameter (second argument) must also be specified.

    +

    For pair style lj/cut/thole/long, the following coefficients must be +defined for each pair of atoms types via the pair_coeff +command.

    +
      +
    • epsilon (energy units)
      • +
    • sigma (length units)
      • +
    • alpha (distance units^3)
      • +
    • damps
      • +
    • LJ cutoff (distance units)
      • +
    +

    The last two coefficients are optional and default to the global values from +the pair_style command line.

    +
    +

    Styles with a cuda, gpu, intel, kk, omp, or opt suffix are +functionally the same as the corresponding style without the suffix. +They have been optimized to run faster, depending on your available +hardware, as discussed in Section_accelerate +of the manual. The accelerated styles take the same arguments and +should produce the same results, except for round-off and precision +issues.

    +

    These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL, +KOKKOS, USER-OMP and OPT packages, respectively. They are only +enabled if LAMMPS was built with those packages. See the Making LAMMPS section for more info.

    +

    You can specify the accelerated styles explicitly in your input script +by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can +use the suffix command in your input script.

    +

    See Section_accelerate of the manual for +more instructions on how to use the accelerated styles effectively.

    Mixing:

    The thole pair style does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly.

    +

    The lj/cut/thole/long pair style does support mixing. Mixed coefficients +are defined using

    +
    +\[\begin{equation} \alpha_{ij} = \sqrt{\alpha_i\alpha_j}\end{equation}\]
    +
    +\[\begin{equation} a_{ij} = \frac 1 2 (a_i + a_j)\end{equation}\]

Restrictions

@@ -211,10 +271,14 @@ enabled if LAMMPS was built with that package. See the charmm dihedral style if the latter has non-zero 1-4 weighting factors. This is because the thole pair style does not know which pairs are 1-4 partners of which dihedrals.

+

The lj/cut/thole/long pair style should be used with a Kspace solver +like PPPM or Ewald, which is only enabled if LAMMPS was built with the kspace +package.