Installation of QUIP and quippy

These intructions provide more details on the compilation and installation of QUIP (Fortran library and main programs) and quippy (Python interface).

Compilation Instructions

These instructions are excerpted from the top-level README, which is the most up-to-date source of information.

  1. To compile QUIP the minimum requirements are:

    • A working Fortran compiler. QUIP is tested with gfortran 4.4 and later, and ifort 11.1.
    • Linear algebra libraries BLAS and LAPACK. QUIP is tested with reference versions libblas-dev and liblapack-dev on Ubuntu 12.04, and mkl 11.1 with ifort.
  2. Clone the QUIP repository from GitHub. The --recursive option brings in submodules automatically (If you don’t do this, then you will need to run git submodule update --init from the top-level QUIP directory after cloning)

    git clone --recursive https://github.com/libAtoms/QUIP.git
    
  3. Decide your architecture by looking in the arch/ directory, and define an environmental variable QUIP_ARCH, e.g.:

    export QUIP_ARCH=linux_x86_64_gfortran
    

    for standard gfortran on Linux. You may need to create your own arch/Makefile.${QUIP_ARCH} file based on an existing file for more exotic systems.

  4. 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).

    If you later make significant changes to the configuration such as enabling or disabling tight-binding support you should force a full rebuild by doing a make deepclean; make.

  5. Compile all programs, modules and libraries:

    make
    

    From the top-level QUIP directory. All programs are built in build/${QUIP_ARCH}/. You can also find compiled object files and libraries (libquip.a) in that directory. Programs can be called directly from that directory.

    Other useful make targets include:

    • make install : copies all compiled programs it can find to QUIP_INSTALLDIR, if it’s defined and is a directory (full path required), and copies bundled structures to QUIP_STRUCTS_DIR if it is defined.
    • make libquip: Compile QUIP as a library and link to it. This will make all the various libraries and combine them into one: build/${QUIP_ARCH}/libquip.a, which is what you need to link with (as well as LAPACK).
  6. A good starting point is to use the quip program, which can calculate the properties of an atomic configuration using a variety of models. For example:

    quip at_file=test.xyz init_args='IP LJ' \
        param_file=share/Parameters/ip.parms.LJ.xml E
    

    assuming that you have a file called test.xyz with the following data in it representing Cu atoms in a cubic fcc lattice:

    4
    Lattice="3.61 0 0 0 3.61 0 0 0 3.61" Properties=species:S:1:pos:R:3
    Cu     0.000 0.000 0.000
    Cu     0.000 1.805 1.805
    Cu     1.805 0.000 1.805
    Cu     1.805 1.805 0.000
    

    The Lennard-Jones parameters in the above example are defined in the ip.parms.LJ.xml file under share/Parameters (ensure the path to this file is correct). The format of the atomic configuration is given in [Extended XYZ](http://libatoms.github.io/QUIP/io.html#extendedxyz) format, in which the first line is the number of atoms, the second line is a series of key=value pairs, which must at least contain the Lattice key giving the periodic bounding box and the Properties key that describes the remaining lines. The value of Properties is a sequence of triplets separated by a colon (:), that give the name, type and number of columns, with the type given by I for integers, R for reals, S for strings.

    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.

  7. To compile the Python wrappers (quippy), the minimum requirements are:

  8. If you are using a Python virtual environment (virtualenv) and would like to install quippy into it, ensure the environment is activated (source <env_dir>/bin/activate, where <env_dir> is the root of your virtual environment) _before_ building quippy (otherwise library versions may cause unexpected conflicts).

  9. To compile the Python wrappers (quippy), run:

    make quippy
    

    Quippy can be used by adding the lib directory in quippy/build/${QUIP_ARCH} to your $PYTHONPATH, however it can be more convenient to install into a specific Python distribution:

    make install-quippy
    

    will either install into the current virtualenv or attempt to install systemwide (usually fails without sudo). To install only for the current user (into ~\.local), execute the command QUIPPY_INSTALL_OPTS=--user make install-quippy, or use QUIPPY_INSTALL_OPTS=--prefix=<directory> to install into a specific directory. QUIPPY_INSTALL_OPTS can also be set in the file build/${QUIP_ARCH}/Makefile.inc.

  10. More details on the quippy installation process and troubleshooting for

common build problems are available in the [online documentation](http://libatoms.github.io/QUIP/).
  1. To run the unit and regression tests, which depend on quippy:

    make test
    
  2. Some functionality is only available if you check out other modules within the QUIP/src/ directories, e.g. the ThirdParty (DFTB parameters, TTM3f water model), GAP (Gaussian Approximation Potential models) and GAP-filler (Gaussian Approximation Potential model training). These packages are not distributed with QUIP because they come with different licensing restrictions.

  3. In order to run QUIP potentials via LAMMPS, make libquip to get QUIP into library form, and then follow the instructions in the [LAMMPS documentation](http://lammps.sandia.gov/doc/pair_quip.html).

Custom settings

MATHS_LINKOPTS

Library options needed to link to BLAS and LAPACK libraries. Any working BLAS/LAPACK installation is fine. If you are using Linux, ATLAS is a good option, and you should use something like the following:

-L/usr/local/atlas -llapack -lf77blas -lcblas -latlas

On Mac OS X, there are build in LAPACK libraries in the Accelerate framework, which you can use by entering

-framework Accelerate
FOX_LIBDIR, FOX_INCDIR and FOX_LIBS
Directories containing FoX libraries and header files, and required link options. Should be read automatically from QUIP Makefiles.
QUIPPY_FCOMPILER

Fortran compiler to use. The shell command:

$ f2py -c --help-fcompiler

will print a list of detected compilers on your system. Use gnu95 for gfortran, intel for ifort on 32-bit platforms and intelem for ifort on 64-bit platforms.

QUIPPY_DEFINES Preprocessor macros which should be defined
when compiling quippy. Note that since the Fortran source files are preprocessed before being scanned by f90doc, it’s important to put all the -D options needed here and not in QUIPPY_F90FLAGS.
QUIPPY_F90FLAGS and QUIPPY_F77FLAGS
Extra flags to pass to Fortran 90 and 77 compilers
QUIPPY_OPT
Optimisation settings for Fortran compiler
QUIPPY_DEBUG
Set this to 1 to include debugging information in the compiled extension code. This also disables optimisation.
QUIPPY_CPP
Fortran preprocessor to use. Default is system cpp.
QUIPPY_INSTALL_OPTS
Installation options, e.g. specify --user to install for the current user --prefix=${PREFIX} to install in a non-default location.
QUIPPY_NO_TOOLS
If set to 1, omit compilation of extra tools such as the elasticity module.
QUIPPY_NO_CRACK
If set to 1, omit compilation of crack utilities.
HAVE_NETCDF
Should be set to 1 to enable NetCDF support. Should be read automatically from QUIP.
NETCDF4
If set to 1, use version 4 of NetCDF. Should be read automatically from QUIP.
NETCDF_LIBDIR, NETCDF_INCDIR, NETCDF_LIBS and NETCDF4_LIBS
Directories containing NetCDF libraries and header files, and required link options. Should be read automatically from QUIP.

Common Problems

Permission errors when installing

If you are installing as root, you may need to make sure the value of the QUIP_ARCH gets through to the install script, e.g.

sudo QUIP_ARCH=darwin_x86_64_gfortran make install-quippy

Installating on Mac OS X with macports

Macports requires various packages to be installed to compile everything, and may require extra linking arguments. See the README.macports for the latest details.

RuntimeError when importing

If, after installing quippy, you get the error shown below when you try to import it for the first time, then you are a victim of a bug in early versions of Python 2.6.

>>> import quippy
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/home/ab686/QUIP/Tools/quippy/quippy/__init__.py", line 31, in
<module>
   _quippy.system.verbosity_push(0)
RuntimeError: more argument specifiers than keyword list entries
(remaining format:'|:_quippy.system.verbosity_push')

The solution is either to compile your own Python from the current svn snapshot, or to update numpy to workaround the fix. This can be done either by compiling numpy from source from an up-to-date svn snapshot, or by applying the patch manually.

ImportError when importing

If you get an ImportError with a message about unresolved dependancies then something went wrong with the linking process - check that all the libraries you’re linking against are correct. You can used ldd on Linux of otool -L on Mac OS X to check which libraries the _quippy.so Python extension is linked against.

Possible problems installing atomeye module

If you get an ImportError with a message ::
>>> import atomeye
ImportError: dlopen(/Users/silvia/lib/python/_atomeye.so, 2): Symbol not found: _Config_load_libatoms
Referenced from: /Users/silvia/lib/python/_atomeye.so
Expected in: flat namespace
in /Users/silvia/lib/python/_atomeye.so

be sure that you have set QUIP_ROOT variable before starting the compilation. If not make clean and recompile again

If you get an ImportError with a message ::
>>> import atomeye
ImportError: dlopen(/Users/silvia/lib/python/_atomeye.so, 2): Symbol not found: __gfortran_adjustl
Referenced from: /Users/silvia/lib/python/_atomeye.so
Expected in: flat namespace
in /Users/silvia/lib/python/_atomeye.so

be sure that the gfortran libraries are properly set in ATOMEYE_LIBS in Makefile.atomeye

Error compiling IPModel_GAP

If you get the following error during compilation:

/src/Potentials/IPModel_GAP.f95:51.22:

use descriptors_module
                      1
Fatal Error: Can't open module file 'descriptors_module.mod' for reading at (1): No such file or directory

The GAP_predict module is not publicly available, so the Makefile.inc must contain HAVE_GP_PREDICT = 0, and HAVE_GP_TEACH = 0.

Warning about quippy.castep when importing quippy

If you get the following warning message when importing quippy:

$ python
>>> from quippy import *
WARNING:root:quippy.castep import quippy.failed.

then don’t worry, the quippy.castep module is not redistributed with the main code. The rest of quippy works fine without it.

Internal compiler error with ifort

If you see an error like the following when using the Intel fortran compiler:

fortcom: Severe: **Internal compiler error: internal abort** Please
report this error along with the circumstances in which it occurred
in a Software Problem Report.
 Note: File and line given may not be explicit cause of this error.

ifort: error #10014: problem during multi-file optimization compilation (code 3)
backend signals

Then the problem is due to bugs in the compiler. As a workaround, setting QUIPPY_NO_CRACK =1 in Makefile.inc should solve the problem, at the cost of excluding the fracture utilities from quippy.

Linking error on Mac OS X

When recompiling quippy on top of a previous compilation, you may see errors like this:

collect2: ld returned 1 exit status ld: in
/QUIP/build.darwin_x86_64_gfortran/libquiputils.a, malformed
archive TOC entry for  ___elasticity_module_MOD_einstein_frequencies,
offset 1769103734 is beyond end of file 1254096

This seems to be a Mac OS X Lion problem with rebuilding static libraries (.a files). Removing the static libraries with rm ../../build.${QUIP_ARCH}/*.a and recompiling should solve the problem.

Segmentation Faults with OpenBLAS

The threading in OpenBLAS can interfere with the OpenMP resulting in segfaults. Either recompile OpenBLAS with USE_OPENMP=1 or disable threading with export OPENBLAS_NUM_THREADS=1 at runtime.