From 1ff053ef7aca3136f55764bdde0a6ecd4bf1b7d6 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Tue, 28 Jul 2015 17:40:16 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@13758 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/Section_packages.html | 4 +- doc/balance.html | 2 +- doc/balance.txt | 2 +- doc/pair_hybrid.html | 11 +++++ doc/pair_hybrid.txt | 11 +++++ doc/pair_modify.html | 87 ++++++++++++++++++++++++++++++++------- doc/pair_modify.txt | 87 ++++++++++++++++++++++++++++++++------- doc/run_style.html | 33 ++++++++++----- doc/run_style.txt | 32 +++++++++----- 9 files changed, 217 insertions(+), 52 deletions(-) diff --git a/doc/Section_packages.html b/doc/Section_packages.html index d1498cf8bd..4b9bd92756 100644 --- a/doc/Section_packages.html +++ b/doc/Section_packages.html @@ -42,7 +42,7 @@ packages, more details are provided.

The current list of standard packages is as follows:

-
+
@@ -119,7 +119,7 @@ on how to build LAMMPS with both kinds of auxiliary libraries.

The current list of user-contributed packages is as follows:

-
Package Description Author(s) Doc page Example Library
ASPHERE aspherical particles - Section_howto 6.14 ellipse -
BODY body-style particles - body body -
+
diff --git a/doc/balance.html b/doc/balance.html index 8431ec8124..39acba35ea 100644 --- a/doc/balance.html +++ b/doc/balance.html @@ -152,7 +152,7 @@ partitioning of the simulation box across processors (one sub-box for each of 16 processors); the middle diagram is after a "grid" method has been applied.

-
+

The rcb style is a "tiling" method which does not produce a logical 3d grid of processors. Rather it tiles the simulation domain with diff --git a/doc/balance.txt b/doc/balance.txt index cd21545126..c894cdddd3 100644 --- a/doc/balance.txt +++ b/doc/balance.txt @@ -142,7 +142,7 @@ partitioning of the simulation box across processors (one sub-box for each of 16 processors); the middle diagram is after a "grid" method has been applied. -:c,image(JPG/balance_uniform_small.jpg,JPG/balance_uniform.jpg),image(JPG/balance_nonuniform_small.jpg,JGP/balance_nonuniform.jpg),image(JPG/balance_rcb_small.jpg,JPG/balance_rcb.jpg) +:c,image(JPG/balance_uniform_small.jpg,JPG/balance_uniform.jpg),image(JPG/balance_nonuniform_small.jpg,JPG/balance_nonuniform.jpg),image(JPG/balance_rcb_small.jpg,JPG/balance_rcb.jpg) The {rcb} style is a "tiling" method which does not produce a logical 3d grid of processors. Rather it tiles the simulation domain with diff --git a/doc/pair_hybrid.html b/doc/pair_hybrid.html index a00eef8e14..47d53fbef8 100644 --- a/doc/pair_hybrid.html +++ b/doc/pair_hybrid.html @@ -190,6 +190,17 @@ potentials.

+

Different force fields (e.g. CHARMM vs AMBER) may have different rules +for applying these factors to modulate the strength of pairwise +interactions bewteen pairs of atoms that are also 1-2, 1-3, and 1-4 +neighbors in the molecular bond topology. Specific +special_bonds settings can be assigned to +different pair hybrid sub-styles via the pair_modify +special special command, using its pair keyword +and optional special argument. This allows multiple force fields to +be used to a model a hybrid system. See the +special_bonds doc page for details. +

The potential energy contribution to the overall system due to an individual sub-style can be accessed and output via the compute pair command. diff --git a/doc/pair_hybrid.txt b/doc/pair_hybrid.txt index 8692d4a20e..6f65e8706d 100644 --- a/doc/pair_hybrid.txt +++ b/doc/pair_hybrid.txt @@ -184,6 +184,17 @@ potentials. :line +Different force fields (e.g. CHARMM vs AMBER) may have different rules +for applying these factors to modulate the strength of pairwise +interactions bewteen pairs of atoms that are also 1-2, 1-3, and 1-4 +neighbors in the molecular bond topology. Specific +"special_bonds"_special_bonds.html settings can be assigned to +different pair hybrid sub-styles via the "pair_modify +special"_pair_modify.html special command, using its {pair} keyword +and optional {special} argument. This allows multiple force fields to +be used to a model a hybrid system. See the +"special_bonds"_special_bonds.html doc page for details. + The potential energy contribution to the overall system due to an individual sub-style can be accessed and output via the "compute pair"_compute_pair.html command. diff --git a/doc/pair_modify.html b/doc/pair_modify.html index 0366343f1f..af59650b6c 100644 --- a/doc/pair_modify.html +++ b/doc/pair_modify.html @@ -19,9 +19,12 @@

  • keyword = pair or shift or mix or table or table/disp or tabinner or tabinner/disp or tail or compute -
      pair values = sub-style N
+
      pair values = sub-style N special which w1 wt2 wt3
     sub-style = sub-style of pair hybrid
     N = which instance of sub-style (only if sub-style is used multiple times)
+    special = optional if want to override special_bonds settings for sub-style
+    which = lj/coul or lj or coul
+    w1,w2,w3 = weights from 0.0 to 1.0 inclusive
   mix value = geometric or arithmetic or sixthpower
   shift value = yes or no
   table value = N
@@ -48,19 +51,15 @@ pair_modify table 12
 
    Modify the parameters of the currently defined pair style.  Not all
 parameters are relevant to all pair styles.
 
    
-
    If used, the pair keyword must appear first in the list of keywords.
-It can only be used with the hybrid and
-hybrid/overlay pair styles.  It means that the
-following parameters will only be modified for the specified
-sub-style, which must be a sub-style defined by the pair_style
-hybrid command.  If the sub-style is defined
-multiple times, then an additional numeric argument N must also be
-specified which is a number from 1 to M where M is the number of times
-the sub-style was listed in the pair_style hybrid
-command.  The extra number indicates which instance of the sub-style
-these modifications apply to.  Note that if the pair keyword is not
-used, and the pair style is hybrid or hybrid/overlay, the
-pair_modify keywords will be applied to all sub-styles.
+
    If used, the pair keyword and its optional special arguments must
+appear first in the list of keywords.  It can only be used with the
+hybrid and hybrid/overlay pair styles and when used
+it means that all the following parameters will only be modified for
+the specified sub-style.  If the pair keyword is not used, and the
+pair style is hybrid or hybrid/overlay, all the following
+parameters keywords will be applied to all sub-styles.  A more detailed
+explanation of the pair keyword syntax, including its optional
+special argument are given below.
 
    
 
    The mix keyword affects pair coefficients for interactions between
 atoms of type I and J, when I != J and the coefficients are not
@@ -202,6 +201,66 @@ a pair style will not work, because the
 kspace_style command requires a Kspace-compatible
 pair style be defined.
 
    
+
    
+
+
    Use of the pair keyword 
+
    
+
    If used, the pair keyword and its optional special arguments must
+appear first in the list of keywords.  It can only be used with the
+hybrid and hybrid/overlay pair styles and when used
+it means that all the following parameters will only be modified for
+the specified sub-style.  If the pair keyword is not used, and the
+pair style is hybrid or hybrid/overlay, all the following
+parameters keywords will be applied to all sub-styles.  A more detailed
+explanation of the pair keyword syntax, including its optional
+special argument are given below.
+
    
+
    As mentioned above, the pair keyword can only be used with the
+hybrid and hybrid/overlay pair styles, and must
+come first in the list of keywords.  If used, the subsequent keywords
+will only be applied to the specified sub-style.  If the sub-style is
+defined multiple times, then an additional numeric argument N must
+also be specified, which is a number from 1 to M where M is the number
+of times the sub-style was listed in the pair_style
+hybrid command.  The extra number indicates which
+instance of the sub-style the pair_modify keywords will be applied to.
+
    
+
    If the optional special argument is used, then the settings of the
+special_bonds command are overridden for the
+specified sub-style.  The special argument requires 4 additional
+arguments: which and w1,w2,w3.  These are analogous to arguments in
+the special_bonds command.  The which argument
+can be lj to change the Lennard-Jones settings, coul to change the
+Coulombic settings, or lj/coul to change both to the same values.
+The w1,w2,w3 arguments are numeric weights from 0.0 to 1.0 inclusive,
+for the 1-2, 1-3, and 1-4 bond topology neighbors.  For example, these
+commands
+
    
+
    special_bonds lj/coul 0.0 0.0 0.1
+pair_hybrid lj/charmm/coul/charmm 8.0 10.0 lj/cut/coul/cut 10.0
+pair_modify pair lj/charmm/coul/charmm special lj/coul 0.0 0.0 0.0
+pair_modify pair lj/cut/coul/cut special lj 0.0 0.0 0.5
+pair_modify pair lj/cut/coul/cut special coul 0.0 0.0 0.8333 
+
    
+
    show how to use both the CHARMM and AMBER force fields in a single
+simulation.  The first pair modify command sets the special bonds to
+CHARMM values (all 0.0).  The latter 2 pair modify commands set the
+standard AMBER values for LJ and Coulombic weights.
+
    
+
    IMPORTANT NOTE: The global settings specified by the
+special_bonds command affect the construction of
+neighbor lists.  Weights of 0.0 (for 1-2, 1-3, or 1-4 neighbors)
+exclude those pairs from the neighbor list entirely.  Weights of 1.0
+store the neighbor with no weight flag applied.  Neither of these
+neighbor effects can be changed by setting a sub-style weight to a
+non-zero or non-one value.  Thus an error is generated if the new
+sub-style value is not 0.0 (or 1.0) and the global setting is 0.0 (or
+1.0).  Note that as in the example above, the global factor can simply
+be set a value other than 0.0 or 1.0, then overridden by any of the
+sub-styles to a value that is 0.0 or 1.0.
+
    
+
    
+
 
    Restrictions: none
 
    
 
    You cannot use shift yes with tail yes, since those are
diff --git a/doc/pair_modify.txt b/doc/pair_modify.txt
index a9bc403e4a..2ea1a8ce9a 100644
--- a/doc/pair_modify.txt
+++ b/doc/pair_modify.txt
@@ -14,9 +14,12 @@ pair_modify keyword values ... :pre
 
 one or more keyword/value pairs may be listed :ulb,l
 keyword = {pair} or {shift} or {mix} or {table} or {table/disp} or {tabinner} or {tabinner/disp} or {tail} or {compute} :l
-  {pair} values = sub-style N
+  {pair} values = sub-style N special which w1 wt2 wt3
     sub-style = sub-style of "pair hybrid"_pair_hybrid.html
     N = which instance of sub-style (only if sub-style is used multiple times)
+    special = optional if want to override "special_bonds"_special_bonds.html settings for sub-style
+    which = {lj/coul} or {lj} or {coul}
+    w1,w2,w3 = weights from 0.0 to 1.0 inclusive
   {mix} value = {geometric} or {arithmetic} or {sixthpower}
   {shift} value = {yes} or {no}
   {table} value = N
@@ -42,19 +45,15 @@ pair_modify table 12 :pre
 Modify the parameters of the currently defined pair style.  Not all
 parameters are relevant to all pair styles.
 
-If used, the {pair} keyword must appear first in the list of keywords.
-It can only be used with the "hybrid and
-hybrid/overlay"_pair_hybrid.html pair styles.  It means that the
-following parameters will only be modified for the specified
-sub-style, which must be a sub-style defined by the "pair_style
-hybrid"_pair_hybrid.html command.  If the sub-style is defined
-multiple times, then an additional numeric argument {N} must also be
-specified which is a number from 1 to M where M is the number of times
-the sub-style was listed in the "pair_style hybrid"_pair_hybrid.html
-command.  The extra number indicates which instance of the sub-style
-these modifications apply to.  Note that if the {pair} keyword is not
-used, and the pair style is {hybrid} or {hybrid/overlay}, the
-pair_modify keywords will be applied to all sub-styles.
+If used, the {pair} keyword and its optional {special} arguments must
+appear first in the list of keywords.  It can only be used with the
+"hybrid and hybrid/overlay"_pair_hybrid.html pair styles and when used
+it means that all the following parameters will only be modified for
+the specified sub-style.  If the {pair} keyword is not used, and the
+pair style is {hybrid} or {hybrid/overlay}, all the following
+parameters keywords will be applied to all sub-styles.  A more detailed
+explanation of the {pair} keyword syntax, including its optional
+{special} argument are given below.
 
 The {mix} keyword affects pair coefficients for interactions between
 atoms of type I and J, when I != J and the coefficients are not
@@ -196,6 +195,66 @@ a pair style will not work, because the
 "kspace_style"_kspace_style.html command requires a Kspace-compatible
 pair style be defined.
 
+:line
+
+Use of the pair keyword :h4
+
+If used, the {pair} keyword and its optional {special} arguments must
+appear first in the list of keywords.  It can only be used with the
+"hybrid and hybrid/overlay"_pair_hybrid.html pair styles and when used
+it means that all the following parameters will only be modified for
+the specified sub-style.  If the {pair} keyword is not used, and the
+pair style is {hybrid} or {hybrid/overlay}, all the following
+parameters keywords will be applied to all sub-styles.  A more detailed
+explanation of the {pair} keyword syntax, including its optional
+{special} argument are given below.
+
+As mentioned above, the {pair} keyword can only be used with the
+"hybrid and hybrid/overlay"_pair_hybrid.html pair styles, and must
+come first in the list of keywords.  If used, the subsequent keywords
+will only be applied to the specified sub-style.  If the sub-style is
+defined multiple times, then an additional numeric argument {N} must
+also be specified, which is a number from 1 to M where M is the number
+of times the sub-style was listed in the "pair_style
+hybrid"_pair_hybrid.html command.  The extra number indicates which
+instance of the sub-style the pair_modify keywords will be applied to.
+
+If the optional {special} argument is used, then the settings of the
+"special_bonds"_special_bonds.html command are overridden for the
+specified sub-style.  The {special} argument requires 4 additional
+arguments: {which} and w1,w2,w3.  These are analogous to arguments in
+the "special_bonds"_special_bonds.html command.  The {which} argument
+can be {lj} to change the Lennard-Jones settings, {coul} to change the
+Coulombic settings, or {lj/coul} to change both to the same values.
+The w1,w2,w3 arguments are numeric weights from 0.0 to 1.0 inclusive,
+for the 1-2, 1-3, and 1-4 bond topology neighbors.  For example, these
+commands
+
+special_bonds lj/coul 0.0 0.0 0.1
+pair_hybrid lj/charmm/coul/charmm 8.0 10.0 lj/cut/coul/cut 10.0
+pair_modify pair lj/charmm/coul/charmm special lj/coul 0.0 0.0 0.0
+pair_modify pair lj/cut/coul/cut special lj 0.0 0.0 0.5
+pair_modify pair lj/cut/coul/cut special coul 0.0 0.0 0.8333 :pre
+
+show how to use both the CHARMM and AMBER force fields in a single
+simulation.  The first pair modify command sets the special bonds to
+CHARMM values (all 0.0).  The latter 2 pair modify commands set the
+standard AMBER values for LJ and Coulombic weights.
+
+IMPORTANT NOTE: The global settings specified by the
+"special_bonds"_special_bonds.html command affect the construction of
+neighbor lists.  Weights of 0.0 (for 1-2, 1-3, or 1-4 neighbors)
+exclude those pairs from the neighbor list entirely.  Weights of 1.0
+store the neighbor with no weight flag applied.  Neither of these
+neighbor effects can be changed by setting a sub-style weight to a
+non-zero or non-one value.  Thus an error is generated if the new
+sub-style value is not 0.0 (or 1.0) and the global setting is 0.0 (or
+1.0).  Note that as in the example above, the global factor can simply
+be set a value other than 0.0 or 1.0, then overridden by any of the
+sub-styles to a value that is 0.0 or 1.0.
+
+:line
+
 [Restrictions:] none
 
 You cannot use {shift} yes with {tail} yes, since those are
diff --git a/doc/run_style.html b/doc/run_style.html
index 2cb3ceaee9..2e12bbac8c 100644
--- a/doc/run_style.html
+++ b/doc/run_style.html
@@ -24,7 +24,7 @@
     n1, n2, ... = loop factor between rRESPA levels (N-1 values)
     zero or more keyword/value pairings may be appended to the loop factors
     keyword = bond or angle or dihedral or improper or
-	      pair or inner or middle or outer or kspace
+	      pair or inner or middle or outer or hybrid or kspace
       bond value = M
         M = which level (1-N) to compute bond forces in
       angle value = M
@@ -47,6 +47,10 @@
 	cut2 = outer cutoff between pair middle and pair outer (distance units)
       outer value = M
         M = which level (1-N) to compute pair outer forces in
+      hybrid values = M1 [M2 ...] (as many values as there are hybrid sub-styles 
+        M1 = which level (1-N) to compute the first pair_style hybrid sub-style in
+        M2 = which level (1-N) to compute the second pair_style hybrid sub-style in
+        ...
       kspace value = M
         M = which level (1-N) to compute kspace forces in 
 
    
@@ -58,6 +62,8 @@
 run_style respa 4 2 2 2 bond 1 dihedral 2 pair 3 kspace 4
 run_style respa 4 2 2 2 bond 1 dihedral 2 inner 3 5.0 6.0 outer 4 kspace 4
    +
    run_style respa 3 4 2 bond 1 hybrid 2 2 1 kspace 3 
+

    Description:

    Choose the style of time integrator used for molecular dynamics @@ -168,7 +174,17 @@ compute forces for all pairs from 5.0 outward, with those from 5.0 to and outer keywords. If not, only the pair keyword can be used with that pair style, meaning all pairwise forces are computed at the same rRESPA level. See the doc pages for individual pair styles for -details. +details.i +

    +

    Another variant to use pair potentials in rRESPA is with the hybrid +keyword, which requires the use of a hybrid pair_style +In this scenario, different sub-styles of the hybrid pair style are +evaluated at different rRESPA levels. Thus the hybrid keyword requires +as many level assignments as there are hybrid substyles which designate +the respective sub-styles to the rRESPA level according to their order +of definition in the pair_style command. Since the hybrid designates +pair force computations, it is mututally exclusive with either the pair +or the inner/middle/outer keywords.

    When using rRESPA (or for any MD simulation) care must be taken to choose a timestep size(s) that insures the Hamiltonian for the chosen @@ -237,16 +253,12 @@ run_style respa 3 3 4 inner 1 3.0 4.0 middle 2 6.0 7.0 outer 3

    The respa/omp styles is a variant of respa adapted for use with pair, bond, angle, dihedral, improper, or kspace styles with an omp -suffix. It is functionally to respa but performs additional required -operations. For more on omp styles see the -Section_accelerate of the manual. +suffix. It is functionally equivalent to respa but performs additional +operations required for managing omp styles. For more on omp styles +see the Section_accelerate of the manual. Accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues.

    -

    The respa/omp style is part of the USER-OMP packages. It is only -enabled if LAMMPS was built with this package included. See the -Making LAMMPS section for more info. -

    You can specify respa/omp explicitly in your input script, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix @@ -260,7 +272,8 @@ more instructions on how to use the accelerated styles effectively.

    Restrictions:

    The verlet/split style can only be used if LAMMPS was built with the -REPLICA package. See the Making LAMMPS +REPLICA package. Correspondingly the respa/omp style is available only +if the USER-OMP package was included. See the Making LAMMPS section for more info on packages.

    Whenever using rRESPA, the user should experiment with trade-offs in diff --git a/doc/run_style.txt b/doc/run_style.txt index 7c1deb744f..36bd6e3c50 100644 --- a/doc/run_style.txt +++ b/doc/run_style.txt @@ -20,7 +20,7 @@ style = {verlet} or {verlet/split} or {respa} or {respa/omp} :ulb,l n1, n2, ... = loop factor between rRESPA levels (N-1 values) zero or more keyword/value pairings may be appended to the loop factors keyword = {bond} or {angle} or {dihedral} or {improper} or - {pair} or {inner} or {middle} or {outer} or {kspace} + {pair} or {inner} or {middle} or {outer} or {hybrid} or {kspace} {bond} value = M M = which level (1-N) to compute bond forces in {angle} value = M @@ -43,6 +43,10 @@ style = {verlet} or {verlet/split} or {respa} or {respa/omp} :ulb,l cut2 = outer cutoff between pair middle and pair outer (distance units) {outer} value = M M = which level (1-N) to compute pair outer forces in + {hybrid} values = M1 \[M2 ...\] (as many values as there are hybrid sub-styles + M1 = which level (1-N) to compute the first pair_style hybrid sub-style in + M2 = which level (1-N) to compute the second pair_style hybrid sub-style in + ... {kspace} value = M M = which level (1-N) to compute kspace forces in :pre :ule @@ -52,6 +56,7 @@ style = {verlet} or {verlet/split} or {respa} or {respa/omp} :ulb,l run_style verlet run_style respa 4 2 2 2 bond 1 dihedral 2 pair 3 kspace 4 run_style respa 4 2 2 2 bond 1 dihedral 2 inner 3 5.0 6.0 outer 4 kspace 4 :pre +run_style respa 3 4 2 bond 1 hybrid 2 2 1 kspace 3 :pre [Description:] @@ -163,7 +168,17 @@ Only some pair potentials support the use of the {inner} and {middle} and {outer} keywords. If not, only the {pair} keyword can be used with that pair style, meaning all pairwise forces are computed at the same rRESPA level. See the doc pages for individual pair styles for -details. +details.i + +Another variant to use pair potentials in rRESPA is with the {hybrid} +keyword, which requires the use of a "hybrid pair_style"_pair_hybrid.html +In this scenario, different sub-styles of the hybrid pair style are +evaluated at different rRESPA levels. Thus the hybrid keyword requires +as many level assignments as there are hybrid substyles which designate +the respective sub-styles to the rRESPA level according to their order +of definition in the pair_style command. Since the {hybrid} designates +pair force computations, it is mututally exclusive with either the {pair} +or the {inner}/{middle}/{outer} keywords. When using rRESPA (or for any MD simulation) care must be taken to choose a timestep size(s) that insures the Hamiltonian for the chosen @@ -232,16 +247,12 @@ run_style respa 3 3 4 inner 1 3.0 4.0 middle 2 6.0 7.0 outer 3 :pre The {respa/omp} styles is a variant of {respa} adapted for use with pair, bond, angle, dihedral, improper, or kspace styles with an {omp} -suffix. It is functionally to {respa} but performs additional required -operations. For more on {omp} styles see the -"Section_accelerate"_Section_accelerate.html of the manual. +suffix. It is functionally equivalent to {respa} but performs additional +operations required for managing {omp} styles. For more on {omp} styles +see the "Section_accelerate"_Section_accelerate.html of the manual. Accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues. -The {respa/omp} style is part of the USER-OMP packages. It is only -enabled if LAMMPS was built with this package included. See the -"Making LAMMPS"_Section_start.html#start_3 section for more info. - You can specify {respa/omp} explicitly in your input script, or you can use the "-suffix command-line switch"_Section_start.html#start_7 when you invoke LAMMPS, or you can use the "suffix"_suffix.html @@ -255,7 +266,8 @@ more instructions on how to use the accelerated styles effectively. [Restrictions:] The {verlet/split} style can only be used if LAMMPS was built with the -REPLICA package. See the "Making LAMMPS"_Section_start.html#start_3 +REPLICA package. Correspondingly the {respa/omp} style is available only +if the USER-OMP package was included. See the "Making LAMMPS"_Section_start.html#start_3 section for more info on packages. Whenever using rRESPA, the user should experiment with trade-offs in

    • Package Description Author(s) Doc page Example Pic/movie Library
    USER-ATC atom-to-continuum coupling Jones & Templeton & Zimmerman (1) fix atc USER/atc atc lib/atc
    USER-AWPMD wave-packet MD Ilya Valuev (JIHT) pair_style awpmd/cut USER/awpmd - lib/awpmd