Merge pull request lammps#4435 from athomps/hybrid-scaled-peratom

Hybrid scaled peratom

doc/src/pair_hybrid.rst

@@ -70,6 +70,12 @@ Examples
    pair_coeff 1 1 lj/cut 1.0 1.0 2.5
    pair_coeff 1 1 morse 1.0 1.0 1.0 2.5
 
+   variable peratom1 atom 1/(1+exp(-$k*vx^2)
+   variable peratom2 atom 1-v_peratom1
+   pair_style hybrid/scaled v_peratom1 lj/cut 2.5 v_peratom2 morse 2.5
+   pair_coeff 1 1 lj/cut 1.0 1.0 2.5
+   pair_coeff 1 1 morse 1.0 1.0 1.0 2.5
+
 Description
 """""""""""
 
@@ -78,7 +84,7 @@ styles enable the use of multiple pair styles in one simulation.  With
 the *hybrid* style, exactly one pair style is assigned to each pair of
 atom types.  With the *hybrid/overlay* and *hybrid/scaled* styles, one
 or more pair styles can be assigned to each pair of atom types.  With
-the hybrid/molecular style, pair styles are assigned to either intra-
+the *hybrid/molecular* style, pair styles are assigned to either intra-
 or inter-molecular interactions.
 
 The assignment of pair styles to type pairs is made via the
@@ -114,16 +120,26 @@ restrictions discussed below.
 
 If the *hybrid/scaled* style is used instead of *hybrid/overlay*,
 contributions from sub-styles are weighted by their scale factors, which
-may be fractional or even negative.  Furthermore the scale factors may
-be variables that may change during a simulation.  This enables
+may be fractional or even negative.  Furthermore the scale factor for
+each sub-style may a constant, an *equal* style variable, or an *atom*
+style variable. Variable scale factors may change during the simulation.
+Different sub-styles may use different scale factor styles.
+In the case of a sub-style scale factor that is an *atom* style variable,
+the force contribution to each atom from that sub-style is weighted
+by the value of the variable for that atom, while the contribution
+from that sub-style to the global potential energy is zero.
+All other contributions to the per-atom energy, per-atom
+virial, and global virial (if not obtained from forces)
+from that sub-style are zero.
+This enables
 switching smoothly between two different pair styles or two different
 parameter sets during a run in a similar fashion as could be done
 with :doc:`fix adapt <fix_adapt>` or :doc:`fix alchemy <fix_alchemy>`.
-
 All pair styles that will be used are listed as "sub-styles" following
 the *hybrid* or *hybrid/overlay* keyword, in any order.  In case of the
 *hybrid/scaled* pair style, each sub-style is prefixed with a scale
-factor.  The scale factor is either a floating point number or an equal
+factor.  The scale factor is either a floating point number or an
+*equal* or *atom*
 style (or equivalent) variable.  Each sub-style's name is followed by
 its usual arguments, as illustrated in the examples above.  See the doc
 pages of the individual pair styles for a listing and explanation of the
@@ -374,7 +390,7 @@ between all atoms of types 1,3,4 will be computed by that potential.
 Pair_style hybrid allows interactions between type pairs 2-2, 1-2,
 2-3, 2-4 to be specified for computation by other pair styles.  You
 could even add a second interaction for 1-1 to be computed by another
-pair style, assuming pair_style hybrid/overlay is used.
+pair style, assuming pair_style *hybrid/overlay* is used.
 
 But you should not, as a general rule, attempt to exclude the many-body
 interactions for some subset of the type pairs within the set of 1,3,4
@@ -414,7 +430,7 @@ passed to the Tersoff potential, which means it would compute no
 3-body interactions containing both type 1 and 2 atoms.
 
 Here is another example to use 2 many-body potentials together in an
-overlapping manner using hybrid/overlay.  Imagine you have CNT (C atoms)
+overlapping manner using *hybrid/overlay*.  Imagine you have CNT (C atoms)
 on a Si surface.  You want to use Tersoff for Si/Si and Si/C
 interactions, and AIREBO for C/C interactions.  Si atoms are type 1; C
 atoms are type 2.  Something like this will work: