lammps/lib/quip/README

QUIP library

Albert Bartok-Partay
apbartok at gmail dot com
2014

This library provides a plug-in for calling QUIP potentials from
LAMMPS. The QUIP package should be built separately, and then the
resulting libraries can be linked to the LAMMPS code. In case of some
potentials, such as BOP or GAP, third-party packages are needed, which
must be downloaded and compiled separately. NB: although GAP has to be
downloaded separately as it is licensed under a different license
agreement, it is compiled together with the rest of QUIP.

Building LAMMPS with QUIP support:

1) Building QUIP
1.1) Obtaining QUIP

The most current release of QUIP can be obtained from github:

$ git clone https://github.com/libAtoms/QUIP.git QUIP

If GAP is needed, it may be downloaded from the `Software' section of
libatoms.org, after accepting the terms and conditions of the Academic
License Agreement. Extract the tarball under the /path/to/QUIP/src/ directory.

1.2) Building QUIP

There is a README file in the top-level QUIP directory, but here are
the main steps.

The arch directory contains a selection of machine- and
compiler-specific makefiles,
e.g. Makefile.linux_x86_64_gfortran. Decide which one is most
appropriate for your system, and edit if necessary. The configuring
step will use the makefile based on the QUIP_ARCH environment
variable, i.e. Makefile.${QUIP_ARCH}. The script will create a build
directory, build/${QUIP_ARCH}, and all the building will happen
there. First it will ask you some questions about where you keep
libraries and other stuff.

Please note: if you are building QUIP to link it to LAMMPS, the serial version
of QUIP must be compiled. For example, QUIP_ARCH may be:
darwin_x86_64_gfortran
linux_x86_64_gfortran
linux_x86_64_ifort_icc etc.

If you don't use something it is asking for, just leave it blank. NB
make sure to answer `y' to `Do you want to compile with GAP prediction
support ? [y/n]'. The answers will be stored in Makefile.inc in the
build/${QUIP_ARCH} directory, and you can edit them later (e.g. to
change optimisation or debug options). Note that the default state is
usually with rather heavy debugging on, including bounds checking,
which makes the code quite slow. The make command has to be executed
from the top-level directory. Making `libquip' ensures all the
necessary libraries will be built.

for example:

$ cd QUIP
$ export QUIP_ROOT=${PWD}
$ export QUIP_ARCH=linux_x86_64_gfortran
$ make config
$ make libquip

Optionally, do
$ make test
to run a test suite.

2) Building LAMMPS

Edit Makefile.lammps in the lib/quip folder, if necessary.  If you
have cloned, configured, and built QUIP inside this folder, QUIP_ROOT
and QUIP_ARCH should be autodetected, even without having to set
the environment variables.  Otherwise export the environment variables
as shown above or edit Makefile.lammps

LAMMPS ships with a user package containing the interface necessary
to use QUIP potentials, but it needs to be added to the compilation
first. To do that, enter the LAMMPS source directory and type:

$ make yes-user-quip

2.2) Build LAMMPS according to the instructions on the LAMMPS website.

3) There are three example sets in examples/USER/quip:

- a set of input files to compute the energy of an 8-atom cubic
  diamond cell of silicon with the Stillinger-Weber potential. Use
  this to benchmark that the interface is working correctly.

- a set of input files demonstrating the use of the QUIP pair style
  for a molecular system with pair style hybrid/overlay and different
  exclusion settings for different pair styles. This input is
  for DEMONSTRATION purposes only, and does not simulate a physically
  meaningful system.

- a set of input files to demonstrate how GAP potentials are specified
  in a LAMMPS input file to run a short MD. The GAP parameter file
  gap_example.xml is intended for TESTING purposes only. Potentials can be
  downloaded from http://www.libatoms.org or obtained from the authors of QUIP.