# 2. Installation¶

This chapter will describe how to get, compile and run the software.

ESPResSo releases are available as source code packages from the homepage 1. This is where new users should get the code. The code within release packages is tested and known to run on a number of platforms. Alternatively, people that want to use the newest features of ESPResSo or that want to start contributing to the software can instead obtain the current development code via the version control system software 2 from ESPResSo ‘s project page at Github 3. This code might be not as well tested and documented as the release code; it is recommended to use this code only if you have already gained some experience in using ESPResSo.

Unlike most other software, no binary distributions of ESPResSo are available, and the software is usually not installed globally for all users. Instead, users of ESPResSo should compile the software themselves. The reason for this is that it is possible to activate and deactivate various features before compiling the code. Some of these features are not compatible with each other, and some of the features have a profound impact on the performance of the code. Therefore it is not possible to build a single binary that can satisfy all needs. For performance reasons a user should always activate only those features that are actually needed. This means, however, that learning how to compile is a necessary evil. The build system of ESPResSo uses cmake 4 to compile software easily on a wide range of platforms.

## 2.1. Requirements¶

The following tools libraries, including header files, are required to be able to compile and use ESPResSo:

CMake

The build system is based on CMake

C++ Compiler

C++14 capable C++ compiler (e.g., gcc 5 or later)

Boost

A number of advanced C++ features used by ESPResSo is provided by Boost. We strongly recommend to use at least boost 1.67.

FFTW

For some algorithms (P$$^3$$M), ESPResSo needs the FFTW library version 3 or later 5 for Fourier transforms, including header files.

MPI

Because ESPResSo is parallelized with MPI, you need a working MPI environment that implements the MPI standard version 1.2.

Python

ESPResSo’s main user interface is via the Python scripting interface. We strongly recommend Python 3. Python 2 support is about to be removed.

Cython

Cython is used for connecting the C++ core to Python. At least version 0.23 is required.

### 2.1.1. Installing Requirements on Ubuntu Linux¶

These instructions pertain to Python 3. If you need to use the deprecated Python 2 support, leave out the 3 in the Python package names. I.e., use python-numpy rather than python3-numpy.

To make ESPResSo run on 18.04 LTS, its dependencies can be installed with:

sudo apt install build-essential cmake cython python3-numpy \
libboost-all-dev openmpi-common fftw3-dev libhdf5-dev libhdf5-openmpi-dev \
doxygen python3-opengl python3-sphinx python3-pip libgsl-dev


Optionally the ccmake utility can be installed for easier configuration:

sudo apt install cmake-curses-gui


If your computer has an Nvidia graphics card, you should also download and install the CUDA SDK to make use of GPU computation:

sudo apt install nvidia-cuda-toolkit


On Ubuntu 18.04, you need to modify a file to make CUDA work with the default compiler:

sudo sed -i 's/__GNUC__ > 6/__GNUC__ > 7/g' /usr/include/crt/host_config.h
sudo sed -i 's/than 6/than 7/g' /usr/include/crt/host_config.h


If your computer has an AMD graphics card, you should also download and install the ROCm SDK to make use of GPU computation:

wget -qO - http://repo.radeon.com/rocm/apt/debian/rocm.gpg.key | sudo apt-key add -
echo 'deb [arch=amd64] http://repo.radeon.com/rocm/apt/debian/ xenial main' | sudo tee /etc/apt/sources.list.d/rocm.list
sudo apt update
sudo apt install libnuma-dev rocm-dkms rocblas rocfft rocrand hip-thrust


### 2.1.2. Installing Requirements on Mac OS X¶

To make ESPResSo run on Mac OS X 10.9 or higher, its dependencies can be installed using MacPorts. First, download the installer package appropriate for your Mac OS X version from https://www.macports.org/install.php and install it. Then, run the following commands:

sudo xcode-select --install
sudo port selfupdate
sudo port install cmake python27 py27-cython py27-numpy \
openmpi-default fftw-3 +openmpi boost +openmpi +python27 \
doxygen py27-opengl py27-sphinx py27-pip gsl hdf5 +openmpi
sudo port select --set cython cython27
sudo port select --set python python27
sudo port select --set pip pip27
sudo port select --set mpi openmpi-mp-fortran


Alternatively, you can use Homebrew.

sudo xcode-select --install
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" brew install cmake python@3 cython boost boost-mpi fftw \ doxygen gsl brew install hdf5 --with-mpi brew install numpy --without-python@2 ln -s /usr/local/bin/python2 /usr/local/bin/python pip install --user PyOpenGL  Note: If both MacPorts and Homebrew are installed, you will not be able to run ESPResSo. Therefore, if you have both installed, please uninstall one or the other by running one of the following two commands: sudo port -f uninstall installed && rm -r /opt/local ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"


If your Mac has an Nvidia graphics card, you should also download and install the CUDA SDK 6 to make use of GPU computation.

### 2.1.3. Installing python dependencies¶

There are a few python packages needed to e.g. build the documentation. To install the required packages as a non-root user execute the following command in ESPResSo ‘s source directory:

pip3 install -r requirements.txt --user --upgrade


Please note that on some systems, pip3 has to be replaced by pip or pip2 to install Python 2 versions of the packages.

## 2.2. Quick installation¶

If you have installed the requirements (see section Requirements ) in standard locations, to compile, it is usually enough to create a build directory and call cmake and make (optional steps which modify the build process are commented out). To chose the correct Python version, run

python -V
python3 -V


This shows which Python version the binaries are for. Then pass the one you’d like to use in the cmake command line, below.

mkdir build
cd build
#cp myconfig-default.hpp myconfig.hpp # use the default configuration as template
#nano myconfig.hpp                    # edit to add/remove features as desired
cmake -DPYTHON_EXECUTABLE=which python3 ..
#ccmake . // in order to add/remove features like SCAFACOS or CUDA
make


This will build ESPResSo with a default feature set, namely src/core/myconfig-default.hpp. This file is a c++ header file, which defines the features that should be compiled in. You may want to adjust the feature set to your needs. This can be easily done by copying the myconfig-sample.hpp which has been created in the build directory to myconfig.hpp and only uncomment the features you want to use in your simulation.

The cmake command looks for libraries and tools needed by ESPResSo. So ESPResSo can only be built if cmake reports no errors.

The command make will compile the source code. Depending on the options passed to the program, make can also be used for a number of other things:

• It can install and uninstall the program to some other directories. However, normally it is not necessary to actually install to run it: make install

• It can invoke code checks: make check

• It can build this documentation: make sphinx

When these steps have successfully completed, ESPResSo can be started with the command:

./pypresso <SCRIPT>


where is <SCRIPT> is a python script which has to be written by the user. You can find some examples in the samples folder of the source code directory. If you want to run in parallel, you should have compiled with Open MPI, and need to tell MPI to run in parallel. The actual invocation is implementation dependent, but in many cases, such as Open MPI, you can use

mpirun -n <N> ./pypresso <SCRIPT>


where <N> is the number of processors to be used.

## 2.3. Configuring¶

### 2.3.1. myconfig.hpp: Activating and deactivating features¶

ESPResSo has a large number of features that can be compiled into the binary. However, it is not recommended to actually compile in all possible features, as this will slow down significantly. Instead, compile in only the features that are actually required. A strong gain in speed can be achieved, by disabling all non-bonded interactions except for a single one, e.g. . For the developers, it is also possible to turn on or off a number of debugging messages. The features and debug messages can be controlled via a configuration header file that contains C-preprocessor declarations. Appendix lists and describes all available features. The file myconfig-sample.hpp that configure will generate in the build directory contains a list of all possible features that can be copied into your own configuration file. When no configuration header is provided by the user, a default header, found in src/core/myconfig-default.hpp, will be used that turns on the default features.

When you distinguish between the build and the source directory, the configuration header can be put in either of these. Note, however, that when a configuration header is found in both directories, the one in the build directory will be used.

By default, the configuration header is called myconfig.hpp. The configuration header can be used to compile different binary versions of with a different set of features from the same source directory. Suppose that you have a source directory $srcdir and two build directories $builddir1 and $builddir2 that contain different configuration headers: • $builddir1/myconfig.hpp:

#define ELECTROSTATICS
#define LENNARD-JONES


## 2.6. Debugging ESPResSo¶

Exceptional situations occur in every program. If ESPResSo crashes with a segmentation fault that means that there was a memory fault in the simulation core which requires running the program in a debugger. The pypresso executable file is actually not a program but a script which sets the Python path appropriately and starts the Python interpreter with your arguments. Thus it is not possible to directly run pypresso in a debugger. However, we provide some useful command line options for the most common tools.

./pypresso --tool <args>


where --tool can be any from the following table. You can only use one tool at a time.

Tool

Effect

--gdb

gdb --args python <args>

--lldb

lldb -- python <args>

--valgrind

valgrind --leak-check=full python <args>

--cuda-gdb

cuda-gdb --args python <args>

--cuda-memcheck

cuda-memcheck python <args>

1

http://espressomd.org

2

http://git.org

3

https://github.com/espressomd/espresso

4

https://cmake.org/

5

http://www.fftw.org/

6