add documentation for pair style agni

doc/src/Section_commands.txt

@@ -995,6 +995,7 @@ These are additional pair styles in USER packages, which can be used
 if "LAMMPS is built with the appropriate
 package"_Section_start.html#start_3.
 
+"agni (o)"_pair_agni.html,
 "awpmd/cut"_pair_awpmd.html,
 "buck/mdf"_pair_mdf.html,
 "coul/cut/soft (o)"_pair_lj_soft.html,

doc/src/pair_agni.txt

@@ -0,0 +1,128 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+pair_style agni command :h3
+pair_style agni/omp command :h3
+
+[Syntax:]
+
+pair_style agni :pre
+
+[Examples:]
+pair_style      agni
+pair_coeff      * * Al.agni Al
+
+[Description:]
+
+Style {agni} style computes the manybody vectorial force components for
+an atom as
+
+:c,image(Eqs/pair_agni.jpg)
+
+{u} labels the individual components, i.e. x, y or z, and {V} is the
+corresponding atomic fingerprint. {d} is the Euclidean distance between
+any two atomic fingerprints. A total of N_t reference atomic
+environments are considered to construct the force field file. {alpha_t}
+and {l} are the weight coefficients and length scale parameter of the
+non-linear regression model.
+
+The method implements the recently proposed machine learning access to
+atomic forces as discussed extensively in the following publications -
+"(Botu1)"_#Botu2015adaptive and "(Botu2)"_#Botu2015learning. The premise
+of the method is to map the atomic enviornment numerically into a
+fingerprint, and use machine learning methods to create a mapping to the
+vectorial atomic forces.
+
+Only a single pair_coeff command is used with the {agni} style which
+specifies an AGNI potential file containing the parameters of the
+force field for the needed elements. These are mapped to LAMMPS atom 
+types by specifying N additional arguments after the filename in the 
+pair_coeff command, where N is the number of LAMMPS atom types:
+
+filename
+N element names = mapping of AGNI elements to atom types :ul
+
+See the "pair_coeff"_pair_coeff.html doc page for alternate ways
+to specify the path for the force field file.
+
+An AGNI force field is fully specified by the filename which contains the
+parameters of the force field, i.e., the reference training environments
+used to construct the machine learning force field. Example force field 
+and input files are provided in the examples/USER/misc/agni directory. 
+
+:line
+
+Styles with {omp} suffix is 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 5"_Section_accelerate.html
+of the manual.  The accelerated style takes the same arguments and
+should produce the same results, except for round-off and precision
+issues.
+
+The accelerated style is part of the USER-OMP.  They are only enabled if
+LAMMPS was built with those packages.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
+
+You can specify the accelerated style explicitly in your input script
+by including their suffix, 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 command in your input script.
+
+See "Section 5"_Section_accelerate.html of the manual for
+more instructions on how to use the accelerated styles effectively.
+
+:line
+
+[Mixing, shift, table, tail correction, restart, rRESPA info]:
+
+This pair style does not support the "pair_modify"_pair_modify.html
+shift, table, and tail options.
+
+This pair style does not write its information to "binary restart
+files"_restart.html, since it is stored in potential files.  Thus, you
+need to re-specify the pair_style and pair_coeff commands in an input
+script that reads a restart file.
+
+This pair style can only be used via the {pair} keyword of the
+"run_style respa"_run_style.html command.  It does not support the
+{inner}, {middle}, {outer} keywords.
+
+:line
+
+[Restrictions:]
+
+Currently, only elemental systems are implemented. Also, the method only
+provides access to the forces and not energies or stresses. However, one
+can access the energy via thermodynamic integration of the forces as
+discussed in "(Botu3)"_#Botu2016construct.  This pair style is part
+of the USER-MISC package. It is only enabled if LAMMPS was built with
+that package. See the "Making LAMMPS"_Section_start.html#start_3 section
+for more info.
+
+The AGNI force field files provided with LAMMPS (see the
+potentials directory) are parameterized for metal "units"_units.html.
+You can use the AGNI potential with any LAMMPS units, but you would need
+to create your own AGNI potential file with coefficients listed in the
+appropriate units if your simulation doesn't use "metal" units.
+
+[Related commands:]
+
+"pair_coeff"_pair_coeff.html
+
+[Default:] none
+
+:line
+
+:link(Botu2015adaptive)
+[(Botu1)] V. Botu and R. Ramprasad, Int. J. Quant. Chem., 115(16), 1074 (2015).
+
+:link(Botu2015learning)
+[(Botu2)] V. Botu and R. Ramprasad, Phys. Rev. B, 92(9), 094306 (2015).
+
+:link(Botu2016construct)
+[(Botu3)] V. Botu, R. Batra, J. Chapman and R. Ramprasad, https://arxiv.org/abs/1610.02098 (2016).

src/USER-MISC/README

@@ -49,6 +49,7 @@ improper_style cossq, Georgios Vogiatzis, gvog at chemeng.ntua.gr, 25 May 12
 improper_style fourier, Loukas Peristeras, loukas.peristeras at scienomics.com, 27 Oct 12
 improper_style ring, Georgios Vogiatzis, gvog at chemeng.ntua.gr, 25 May 12
 improper_style distance, Paolo Raiteri, p.raiteri at curtin.edu.au, 2 Dec 15
+pair_style agni, Axel Kohlmeyer, akohlmey at gmail.com, 9 Nov 16
 pair_style buck/mdf, Paolo Raiteri, p.raiteri at curtin.edu.au, 2 Dec 15
 pair_style coul/diel, Axel Kohlmeyer, akohlmey at gmail.com, 1 Dec 11
 pair_style dipole/sf, Mario Orsi, orsimario at gmail.com, 8 Aug 11