Installation 

Asap is released under the GNU Lesser Public License version 3. See the file LICENSE which accompanies the downloaded files. For more information, see our License page.

NIFLHEIM USERS: Please see the page Asap on Niflheim.

Simple installation 

In the vast majority of cases, you can simply install Asap using pip. You will need to have numpy installed (including header files, sometimes that package is called numpy-dev). You need a C++ compiler installed (probably g++). If you want to run Asap in parallel, you should also have openmpi (or another MPI implementation) installed. In most scientific Linux environments, these prerequisites are already fulfilled.

You can install Asap with the command

pip install --upgrade --user asap3

Note that we pass the --user option to cause installation into $HOME/.local instead of into the global Python distribution. We explicitly tell pip to upgrade if an older installation is present.

If you install into a virtual environment (a very good idea!) you should leave out the --user option.

Testing the installation 

Of course it works. But it may still be wise to test it!

Starting with version 3.13.10 (not yet released), the test suite is installed together with the rest of the package. It is run through pytest, which may need to be installed separately.

Testing an end-user installation 

If Asap has been installed with pip (or as a software module on a cluster), it can be tested with pytest like this:

Quick test:

pytest --pyargs asap3 -m core
mpirun -np 2 pytest --pyargs asap3 -m core

More thorough test:

pytest --pyargs asap3
mpirun -np 2 pytest --pyargs asap3

Also include slow tests:

pytest --pyargs asap3 --slow
mpirun -np 2 pytest --pyargs asap3 --slow

The first line tests the serial installation, and the second the parallel installation. As shown, the parallel test suite is run on 2 MPI tasks; it can also be run using 3, 4, 6 or 8 tasks.

The serial test can be sped up if you have pytest-xdist installed by adding -n auto to the command line, running tests in parallel on all cpus. Don’t combine that with mpirun!

Testing a developer installation 

Do as above, but run pytest from the folder with the source code, and leave out the --pytest asap3 from the command line. For example:

cd asap3
pytest -n auto -v

(the -v flag gives a bit extra output for developers).

Testing version 3.13.9 or before 

Unfortunately, when pip-installing Asap the test suite is not installed. So testing requires downloading the source code.

Get the source code from GitLab’s asap release page.
Unpack it into a temporary folder
Go to the Test subfolder, and run the test suite
- run python TestAll.py for the serial test suite. Or run python TestAll.py --slow if you want a more thorough test, it may take 5-10 minutes.
- run ./TestParallel.sh for the parallel test suite (only if you have MPI installed on your machine).
Once the test has passed, you may delete the temporary folder with the source code.

Optimized installation 

Building with the Intel Compiler for optimal performance 

Compiling with the Intel Compiler (icc/icpc) gives more than a factor two in performance compared to using the GNU Compilers (gcc/g++), used per default when installing with pip. If you have the Intel Compiler available, you can use it like this:

pip install --upgrade --user --install-option="--with-intel" asap3

NB: The Intel compilers are a commercial product, but it is available for free for students for personal use.

Manual installation from source 

If you want to tweak the installation, if you need the developer version, or if the simple installation does not work for some reason you can install manually´.

Download Asap 

Download the source code of the latest release from GitLab’s asap release page.

… or get the developer version from GitLab 

It is also possible to get the latest developer version of Asap from GitLab:

$ git clone https://gitlab.com/asap/asap.git

Then proceed to compile it using the Installation instructions, in particular the section regarding In-place installation for Git users.

If you want to browse the source code (including changes), it is most convenient to use the GitLab source browser

Quick installing guide 

Unpack the tarball and rename the resulting folder to something sensible:
```
tar xvf asap-ASAP_VERSION_3_13_10.tar.gz
```
Install the downloaded source code with pip:
```
pip install --user asap-ASAP_VERSION_3_13_10/
```
(leave out --user if you install into a venv, which is recommended!)

OpenKIM support 

Starting with version 3.11.7, support for OpenKIM v. 2.X is automatically enabled when compiling Asap. The OpenKIM libraries are found using the pkg-config program, as found in the pkgconf package (or its now obsolete predecessor pkg-config).

Starting with version 3.13.2, it is no longer possible to install OpenKIM without pkg-config , as the alternate way rarely worked anyway.

Special installation instructions 

Installing on Niflheim 

Please see the page Asap on Niflheim.

Installation using the Intel compiler and/or installation on clusters 

If you want to install Asap with the Intel C++ compiler (for better performance), you can install Asap using GNU make. The Intel compiler is automatically detected and used if available.

To install the serial version:

make depend
make serial

To install both the serial and parallel version:

make depend
make all

If you are using a Python venv, then the compiled code is automatically made available to the Python interpreter. If you do not use a venv, you need to put the absolute paths to the folders Python and x86_64 on your PYTHONPATH, so Python can find Asap. (Note that the folder named x86_64 will have a different name if you do not have an Intel CPU or if you have an unusual Unix distribution. make info will tell you the name (look for the variable OBJDIR).

For more information, please read the Installing Asap with a Makefile.

In-place installation for Git users 

If you got Asap by cloning the GitLab repository, and always want to use the newest version, you probably want to compile it in-place.

IMPORTANT: If you use the developer version of Asap from GitLab, you should also use the developer version of ASE from GitLab.

For Niflheim users:

See the page Asap on Niflheim.

For everybody else:

Compile Asap with:

make depend
make serial

if you only want the serial version, or:

make depend
make all

if you also need the parallel version. After updating from gitlab, you only need to re-run make depend if make serial (or make all) fails with an instruction to do so.

If you are using a Python venv, then the compiled code is automatically made available to the Python interpreter. If you do not use a venv, you need to put it on your PATH and your PYTHONPATH. Assuming that Asap is placed in $HOME/asap, these variables should be set to:

export PATH=$HOME/asap/XXX:$PATH
export PYTHONPATH=$HOME/asap/Python:$HOME/asap/XXX:$PYTHONPATH

where XXX is the output of the command uname -m.

Installation on a Mac 

Please read Installing ASE, Asap and GPAW on a Mac