Installation of QUIP, quippy and GAP

These instructions provide more details on the compilation and installation of QUIP (Fortran library and main programs) and and GAP (Fortran add-on to QUIP), and the quippy (Python interface).

Precompiled Containers

If you have access to Docker or Singularity, you can try one of the precompiled images to get up and running quickly.

Compilation Instructions

First try the quickstart below, which should work with most Linux systems.

Quick start

Install 1 the prerequisites: GCC, gfortran, Python, and the linear algebra libraries. For example, on Ubuntu, do (in a terminal):

$ sudo apt-get install gcc gfortran python python-pip libblas-dev liblapack-dev

For other systems, replace the apt-get part with your system package manager. Beware that the packages might also have slightly different names; these can usually be found with a quick search.

Don’t forget the quippy prerequisites:

$ pip install numpy ase f90wrap

Now you can get the code and compile:

$ git clone --recursive https://github.com/libAtoms/QUIP.git
$ export QUIP_ARCH=linux_x86_64_gfortran
$ export QUIPPY_INSTALL_OPTS=--user  # omit for a system-wide installation
$ make config

Answer all the questions with their defaults (by pressing enter) for now, just to get things working.

$ make
$ make install-quippy

And now open a Python terminal and see if it works:

$ python
>>> import quippy
>>>

If the import completes successfully (i.e. with no output) then the installation was successful. You may want to continue with Installing the Jupyter notebook to run the interactive tutorials.

1

If this isn’t your machine and you don’t have root access, these packages might already be installed by the system administrator. If not, ask them.

Step by step

If that didn’t work, try these step-by-step instructions instructions excerpted from the top-level README. The README file is the most up-to-date source of installation 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 –recursive from the top-level QUIP directory after cloning) :: `bash 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.:: `bash export QUIP_ARCH=linux_x86_64_gfortran ` for standard gfortran on Linux. Here is where you can adjust which compiler is being used, if you do not like the defaults. 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:: `bash 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 compiler, 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:: `bash 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:: ```bash 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: - Python 3 - [NumPy](http://www.numpy.org) (numpy>=1.5.0) - [Atomic Simulation Environment ](https://wiki.fysik.dtu.dk/ase/) (ase>=3.17.0) - [f90wrap](https://github.com/jameskermode/f90wrap) - (optional) [SciPy](http://www.scipy.org) - (optional) [matscipy](https://github.com/libAtoms/matscipy).

    Note: 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).

    The required version of f90wrap can be installed with: `bash git submodule update --init --recursive pip install src/f90wrap `

  1. To compile the Python wrappers (quippy), run:: `bash 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:: `bash 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.

  2. 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:

`bash make test `

  1. To get back to a state near to a fresh clone, use

`bash make distclean `

  1. 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 training). These packages are not distributed with QUIP because they come with different licensing restrictions, but you can get them [here](http://www.libatoms.org/gap/gap_download.html)

    GAP is a machine learning method that uses Gaussian process regression, and needs large data files to run. You can find potentials that have been published as well as training data in our [data repository](http://www.libatoms.org/Home/DataRepository), see also the [online docs](https://libatoms.github.io/GAP).

  2. 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). You need at least 11 Aug 2017 version or later.

# Developer notes:

## Fixing/updating the version f90wrap:

`bash cd src/f90wrap ` `bash git checkout <commit> ` OR ```bash git checkout master

` Updating the version in the `QUIP` repository: ` cd ../.. git add src/f90wrap git commit -m “updating the version of f90wrap” ```

If that still doesn’t work or you’re using a nonstandard architecture, try looking at Custom settings and Common Problems. As a last resort you can consult the issue tracker on Github.

Installing the Jupyter notebook

Jupyter is an environment for interactive computing that makes using Python much easier and more intuitive. Especially useful is its notebook environment, which provides a handy way to experiment with code, see the results, and have a record of your progress. The interactive getting-started tutorial is a Jupyter notebook that you can run and modify yourself.

To get Jupyter up and running, the following should suffice 2:

$ pip install jupyter
$ jupyter notebook

This will open a new window in your browser that you can use to navigate through your filesystem. To access the interactive tutorials, you can run the jupyter notebook command from your QUIP/src/GAP/doc/Examples directory (or any enclosing directory) then navigate to the notebooks and open Introduction.ipynb to get started.

2

This assumes you’ve already run sudo apt-get install python-pip; pip install numpy; pip install ase as in the Quick start.

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_INSTALL_OPTS

Installation options, e.g. specify --user to install for the current user --prefix=${PREFIX} to install in a non-default location.

HAVE_NETCDF4

Should be set to 1 to enable NetCDF4 support. Should be read automatically from QUIP.

NETCDF4_LIBS, NETCDF4_FLAGS

Linker flags for compiling with NetCDF4 support, and flags for finding header files. 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

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 module is not publicly available, so the Makefile.inc must contain HAVE_GAP = 1.