# XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# X
# X   libAtoms+QUIP: atomistic simulation library
# X
# X   Portions of this code were written by
# X     Albert Bartok-Partay, Silvia Cereda, Gabor Csanyi, James Kermode,
# X     Ivan Solt, Wojciech Szlachta, Csilla Varnai, Steven Winfield.
# X
# X   Copyright 2006-2010.
# X
# X   These portions of the source code are released under the GNU General
# X   Public License, version 2, http://www.gnu.org/copyleft/gpl.html
# X
# X   If you would like to license the source code under different terms,
# X   please contact Gabor Csanyi, gc121@cam.ac.uk
# X
# X   Portions of this code were written by Noam Bernstein as part of
# X   his employment for the U.S. Government, and are not subject
# X   to copyright in the USA.
# X
# X
# X   When using this software, please cite the following reference:
# X
# X   http://www.libatoms.org
# X
# X  Additional contributions by
# X    Alessio Comisso, Chiara Gattinoni, and Gianpietro Moras
# X
# XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This is the top level directory for QUIP, libAtoms and friends. 

1) decide your architecture by looking at the Makefiles/README, and
define an environmental variable QUIP_ARCH, e.g. 

   export QUIP_ARCH=linux_x86_64_ifort_icc

You may well need to create your own Makefiles/Makefile.${QUIP_ARCH}
file based on an existing file.

2) Ensure that you have sufficiently up-to-date compilers. If you are using
   GNU compiler suite, you need version 4.4 or later. From Intel, you need
   version > 11.0.084.

3) customise QUIP, set the maths libraries and provide linking options:

   make config

   Makefile.config will create a build directory, build.${QUIP_ARCH}, and
   all the building happen there. First it will ask you some questions
   about where you keep libraries and other stuff, if you don't use
   something it is asking for, just leave it blank. 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.

4) make something:

   make libAtoms
 
   or (usually)

   make QUIP_Programs/<progname>

   Note that the `make' command has to be executed from the top level
   directory, even for targets in subdirectories. 

   Most useful make targets include
    all : pretty much every vaguely useful top level program
    QUIP_Programs/eval : evaluate energies, forces, minimize energy etc
    QUIP_Programs/md : basic md program
    QUIP_Core : generates everything that is necessary to use QUIP as a library
    install : copies all compiled programs it can find to QUIP_INSTDIR,
      if it's defined and is a directory

   You can also use QUIP and libAtoms as a library and link to it. To make the
   library version only, execute

   make libquip

   This will make all the various libraries and combine them into one: 
   build.${QUIP_ARCH}/libquip.a, which is what you need to link (and of course
   LAPACK). 
 
5) QUIP/libatoms is a "developer's" code, and is not for the faint hearted. A 
   good start is to use the 'eval' program, which is under QUIP_Programs, and
   allows the evaluation of properties of an atomic configuration using a variety
   of models. For example:

   eval at_file=test.xyz init_args='IP LJ' param_file=QUIP_Core/parameters/ip.parms.LJ.xml E

   assuming that you have a file called test.xyz with the following data in it
   (without the dashes, obviously) representing Cu atoms in a simple cubic lattice:

   ----
   1
   Lattice="4 0 0 0 4 0 0 0 4" Properties=Z:I:1:pos:R:3
   29 0 0 0 
   ----

   The Lennard-Jones parameters in the above example is defined in the ip.parms.LJ.xml
   file. 

   Most string arguments can be replaced by '--help' and QUIP programs will then print a 
   list of allowable keywords with brief help messages as to their usage, so e.g. 'init_args=--help'
   will give a list of potential model types (and some combinations). The parsing is recursive, so
   'init_args=IP --help' will then proceed to list the types of interatomic potentials (IP) that are
   available. 

6) Some functionality is only available if you check out other packages
   within the QUIP tree, e.g. the ThirdParty (DFTB parameters, TTM3f water model),
   GAP (Gaussian Approximation Potential models) and GAP-filler (Gaussian Approximation
   Potential model training).