corrections & suggestions for dreiding docs

Hi Steve

I have 5 suggestions for the hbond/dreiding documentation at:

http://lammps.sandia.gov/doc/pair_hbond_dreiding.html

I also wanted to give you a friendly nag regarding bugs in the code.
I've re-attached the same copy of patches for
"pair_hbond_dreiding_lj.cpp" and "pair_hbond_dreiding_morse.cpp".
Please include them in the next release of LAMMPS. (These are really
trivial changes. All I did was change the order of two lines in Tod's
code. Check with "diff".)

I think that suggestions 2) and 4) below are the most important
because the problems they refer to are difficult to detect.

1)
The argument list for each pair_style is missing an argument. There
should be two distance cutoffs (inner outer) for each pair_style.
(Check this in file pair_hbond_dreiding_lj.cpp, line 310 and
pair_hbond_dreiding_morse.cpp, line 237.)

The correct list of arguments is here:

For the hbond/dreiding/lj style the list of coefficients is as follows:
    K = hydrogen atom type = 1 to Ntypes
    donor flag = i or j
    epsilon (energy units)
    sigma (distance units)
    n = exponent in formula above
    distance cutoff Rin (distance units)
    distance cutoff Rout (distance units)
    angle cutoff (degrees)

For the hbond/dreiding/morse style the list of coefficients is as follows:
    K = hydrogen atom type = 1 to Ntypes
    donor flag = i or j
    D0 (energy units)
    alpha (1/distance units)
    r0 (distance units)
    n = exponent in formula above
    distance cutoff Rin (distance units)
    distance cutoff Rout (distance units)
    angle cutoff (degrees)

2) Use hybrid/overlay, never hybrid

Although you may differ with this suggestion, I view the following
statement as incorrect:

"It is common to use it as a sub-style in a pair_style hybrid or
hybrid/overlay command."

Please change this to say:

"It is common to use it as a sub-style in a pair_style hybrid/overlay command."

pair_style hbond/dreiding should never be used with "hybrid". The
dreiding hbond force can not represent the complete force between
donor and acceptor atoms, because it lacks a repulsive core. There is
a non-repulsive singularity at distance 0 (between donor and
acceptor). At certain angles the donor and acceptor atoms can get
arbitrarily close to each other and the forces there can be enormous.
This singularity can cause difficult-to-detect physics problems in
complex molecules. I can not imagine a situation where anyone would
use this pair_style with out overlaying it with an additional
repulsive interactions to keep the donor and acceptor atoms apart.

In fact, after reading the original Dreiding paper (1990) is that they
always superimpose the Dreiding hydrogen bond interactions onto
ordinary van der Waals (Lennard-Jones) interactions between donor and
acceptor atoms. Unfortunately this detail is never explicitly stated
in the paper, but it is implied. Users may not realize they are
supposed to use "hybrid/overlay" instead of "hybrid" unless they are
careful to check energy conservation.

Tod, if you have a comment on this point, please add it. (I was
unable to get a reply from Dr. Goddard.)

3)
Usage examples:

Because one should never use hbond/dreiding alone, I would also change
the usage examples to reflect this. Here is a list of examples I am
using to simulate hydrogen bonds in protein backbones. (I have tested
both examples and they work.)

pair_style hybrid/overlay lj/cut 10.0 hbond/dreiding/lj 4 9.0 11.0 90
pair_coeff 1 2 hbond/dreiding/lj 3 i 9.5 2.75 4 9.0 11.0 90.0

  -- or --

pair_style hybrid/overlay lj/cut 10.0 hbond/dreiding/morse 2 9.0 11.0 90
pair_coeff 1 2 hbond/dreiding/morse 3 i 3.88 1.7241379 2.9 2 9 11 90

pair_hbond_dreiding_lj.cpp (16 KB)

pair_hbond_dreiding_morse.cpp (13.4 KB)