Prerequisites

To use this code, you need some other software.

A C++ compiler.
The GNU compiler is fine, but on Intel and AMD CPUs you get better performance from Intel's own compiler.
GNU make.
The makefile is unlikely to work with any other version of make. GNU make is the default on Linux and other GNU-based Unixes. On other machines it may be installed under the name gmake (try gmake --version). Otherwise get it from www.gnu.org, and install it.
For parallel simulations ONLY: A version of MPI.
We use OpenMPI but other versions should in principle work as well.
Python.
We have used most Python versions 2.6.X and 2.7.X. Python is included in most Linux distributions, and can easily be installed under almost all Unix versions. Get it from http://www.python.org. Python 3 is not yet supported
NumPy.
A modern replacement for Numerical Python. Get the newest version from XXXX Asap has been tested with versio 1.0.4, but get the newest you can.
The Atomic Simulation Environment (ASE).
This is the part of our code which is shared by Asap, GPAW and Dacapo. Get it from http://wiki.fysik.dtu.dk/ase and follow the instructions there.

Download Asap

The newest official release is available from the Installation page. You can also get Asap from our SVN server.

Compiling and installing using distutils

This is likely to be the easiest way to install Asap, but not the most flexible. It will not install the parallel version, it will not use the Intel compiler, and it will not support OpenKIM.

  1. Unpack the ASAP tar file, or check it out from SVN.
  2. Either do a systemwide installation (as root):

    python setup.py install

    or a user-installation (for example in $HOME/python):

    python setup.py --prefix=$HOME/python install

Compiling and installing using the Makefile

This is the recommended way to install Asap if you want to use the Intel compiler and/or if you are installing Asap on a cluster.

  1. Unpack the ASAP tar file, or check it out from SVN.
  2. You may have to change the makefile to reflect your local system.

    The Asap Makefile system use a number of configuration files, and tries to pick the correct one. They have names like makefile-x86_64-gnu for use on an Intel 64 bit system with GNU compilers.

    You can see which version the system picks by typing make version:

    [Lubuntu32] Asap$ make version
    Getting configuration from makefile-i686-gnu
    ASAP version 3.8.3

    If you need to modify the configuration, or if the Asap make system chose the wrong one, please copy the desired configuration and name it makefile-local. That one will overrule other makefile names. You can then edit the file to choose the correct compilers and compiler options.

    If you need to modify this behavior (most likely on exotic systems), please read the section Modifying the Makefile below.

  3. Create the makefile dependencies by running

    make depend

    If you do not have MPI installed you will get error messages during the second part of this. This is harmless.

  4. Compile the code.

    To make only the serial version (e.g. if MPI is not installed):, type

    make serial

    To make both the serial and parallel version, type

    make parallel

System-wide installation

Following these instructions will install ASAP in such a way that all users can use it WITHOUT setting their PYTHONPATH. Unless you own the Python installation directory, you will need to be root.

  1. Install the ASE by unpacking it / checking it out from SVN. and typing "python setup.py install" (Or, ideally, reading the installation instructions and following them). :-)

    It will install itself in ...path-to-python.../site-packages/ase

  2. Compile ASAP as described above.
  3. Install ASAP by typing:

    make install.

    The binaries will be installed in site-packages, the Python part in site-packages/asap3.

  4. If you compiled the parallel version, you need to install it by typing:

    make install-parallel.

User installation (alternative 1: using $PYTHONPATH)

If you cannot make a system wide installation, or if you want your local copy to make modifications (or just to stay in sync with the SVN version), you can install it in any directory you like.

In the following I assume you install in a subdirectory of your home directory ($HOME or ~). If it is NFS mounted, you may want to use a local harddisk instead (/scratch/username on the CAMP desktops).

  1. (optional) Unpack the ASE in some directory (or check it out from CVS) In the following I will assume that it is in $HOME/ase
  2. Place the ASAP source code in another directory, for example $HOME/Asap
  3. Compile Asap as above.
  4. Place the ASE and the both the Asap Python code and the compiled modue on the PYTHONPATH:

    Set PYTHONPATH to $HOME/ase:$HOME/Asap/Python:$HOME/Asap/XXXXXX where XXXXXX is the output of "uname -m". If you use the bash shell on an Intel Linux machine, you could place this command in your .bashrc

    setenv PYTHONPATH $HOME/ase:$HOME/Asap/Python:$HOME/Asap/i686

    Of course you should leave out the $HOME/ase: part if you skipped point 1 above.

  5. If you change the Asap source code (or update from SVN) you can just type make to generate a new executable.

User installation (Alternative 2: Your own, private Python installation)

You may want to make your own Python installation, and dump ASAP and everything else there. This is a good idea if some of the prerequisites are not installed or are installed incorrectly.

  1. Make a directory under your home directory (or on a local harddisk), for example called $HOME/MyPython.
  2. Make a subdirectory under MyPython called src.
  3. Get the newest version of the Python source code from www.python.org, and dump it in MyPython/src
  4. Install Python:

    tar xvfz Python-2.X.Y.tgz
    cd Python-2.X.Y
    ./configure --prefix=$HOME/MyPython
    make
    make install
  5. Place the new python on your path (edit .bashrc or corresponding and remember to reload it).

    Check it by typing "python" in the shell and see that the version number and compilation date is correct.

  6. Download Numpy from its web page, install it using

    python setup.py install

    It will now be installed in your private Python installation.

  1. Install ASE and Asap following the instructions for a system-wide install (now you do NOT need to be root).

You do not need to set the PYTHONPATH as long as you use your own version of Python.

Installing on multiple different machines

You can easily install Asap in a heterogeneous environment, e.g. where your home directory is NFS mounted to machines with different architectures (the output of uname -m). The makefile keeps the object files from different architectures in different subdirectories. Just remember to compile and install on a machine of each architecture.

Modifying the makefile

The only modification you should need to make to the makefile is to add a specification of how Asap should be compiled on your system (compiler flags etc). This is done by adding a file defining the relevant variable (probably by copying one of the existing files and modifying it). The main makefile loads these variables from the first of the following files that it finds

makefile-local
A file with this name can be used to local customizations if you only compile to a single architecture in the installation directory.
makefile-hostname
A file named makefile-hostname where hostname is replaced with the machines hostname (the output of uname -n) can be used for local customizations if you compile for multiple architectures in the same installation directory. Compiling with multiple setups but the same architecture (the output of uname -m) is not supported, as the object files will then end in the same subdirectories.
makefile-arch-compiler
Files named makefile-arch-compiler are used to specify setups for architectures where multiple compilers are supported (presently the i686 and x86_64 architectures). If you add new files of this type, please contribute them.
makefile-arch
Files named makefile-arch specify setups for architectures where only a single compiler is available. arch is the output of uname -m. If you add new files of this type, please contribute them.
makefile-default
This configuration is used if none of the above are found. Do not edit this file, instead make a new file of the type makefile-arch and contribute.

When making a new configuration file, the easiest is to copy one of the existing one (e.g. makefile-default) and modify it. As an alternative, include an old one in your file. For example, on the machine named gandalf you want to use the default configuration, but add an option to CFLAGS. Make a file called makefile-gandalf:

include makefile-default
CFLAGS += -march=wizard
CXXFLAGS = $(CFLAGS)

Typical problems and advanced topics

  • Error messages when attempting to compile asapparallel_wrap.cpp are most likely caused by not having MPI installed. Use "make serial" to just compile the serial version. It can also be caused by a broken installation of Scientific Python.
    • If the program mpicc or mpiCC cannot be found, MPI is not installed or not on your path.
    • If the header file mpi.h cannot be found, your MPI installation is probably broken or missing.
  • If the file stacktrace.c fails to compile, remove stacktrace.c from the variable CSRC_EXTRA, and remove -DSTACKTRACE=XXXXX from the CFLAGS and the CXXFLAGS lines. The stacktrace module causes a stack trace to be written into a file called CRASH if the program crashes. It is used for debugging. This has no impact on the performance, except when using the Intel compiler on Pentium 4 machines, where the -fp flag must be given together with -DSTACKTRACE. The -fp flag is supposed to decrease performance a little, although I have had troubles measuring it (it is apparently less than 1%).
  • The TIMING symbol causes timing code to be included. Remove -DTIMING if you do not want this. Removing the timing code will cause a marginal improvement of the performance.

Asap: ASAP detailed installation instructions (last edited 2014-12-11 13:29:43 by JakobSchiøtz)