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 are 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 3 scripting interface.
- 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¶
To make ESPResSo run on 18.04 LTS, its dependencies can be installed with:
sudo apt install build-essential cmake cython3 python3-numpy \
libboost-all-dev openmpi-common fftw3-dev libhdf5-dev libhdf5-openmpi-dev \
python3-opengl libgsl-dev
Optionally the ccmake utility can be installed for easier configuration:
sudo apt install cmake-curses-gui
To run the tutorials and generate the documentation, additional Python packages are required:
sudo apt install python3-matplotlib python3-scipy ipython3 jupyter-notebook
sudo pip3 install 'pint>=0.9'
2.1.1.1. Nvidia GPU acceleration¶
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, the default GCC compiler is too recent for nvcc, which will generate
compiler errors. You can either install an older version of GCC and select it
with environment variables CC and CXX when building ESPResSo, or edit the
system header files as shown in the following example for Ubuntu 18.04:
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
2.1.1.2. AMD GPU acceleration¶
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 rocthrust
After installing the ROCm SDK, please reboot your computer.
2.1.2. Installing requirements on other Linux distributions¶
Please refer to the following Dockerfiles to find the minimum set of packages required to compile ESPResSo on other Linux distributions:
2.1.3. Installing requirements on Mac OS X¶
2.1.3.1. Preparation¶
To make ESPResSo run on Mac OS X 10.9 or higher, you need to install its dependencies. There are two possibilities for this, MacPorts and Homebrew. We recommend MacPorts, but if you already have Homebrew installed, you can use that too. To check whether you already have one or the other installed, run the following commands:
test -e /opt/local/bin/port && echo "MacPorts is installed"
test -e /usr/local/bin/brew && echo "Homebrew is installed"
If both are installed, you need to remove one of the two. To do that, run 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 Homebrew is already installed, you should resolve any problems reported by the command
brew doctor
If Anaconda Python or the Python from www.python.org are installed, you will likely not be able to run ESPResSo. Therefore, please uninstall them using the following commands:
sudo rm -r ~/anaconda[23]
sudo rm -r /Library/Python
If you want to install MacPorts, download the installer package appropriate for your Mac OS X version from https://www.macports.org/install.php and install it.
If you want to install Homebrew, use the following commands.
sudo xcode-select --install
sudo xcodebuild -license accept
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
2.1.3.2. Installing packages using MacPorts¶
Run the following commands:
sudo xcode-select --install
sudo xcodebuild -license accept
sudo port selfupdate
sudo port install cmake python37 py37-cython py37-numpy \
openmpi-default fftw-3 +openmpi boost +openmpi +python37 \
doxygen py37-opengl py37-sphinx gsl hdf5 +openmpi \
py37-matplotlib py37-ipython py37-jupyter
sudo port select --set cython cython37
sudo port select --set python3 python37
sudo port select --set mpi openmpi-mp-fortran
2.1.3.3. Installing packages using Homebrew¶
brew install cmake python cython boost boost-mpi fftw \
doxygen gsl numpy ipython jupyter
brew install hdf5-mpi
brew link --force cython
pip install PyOpenGL matplotlib
2.2. Quick installation¶
If you have installed the requirements (see section Requirements) in
standard locations, compiling ESPResSo is usually only a matter of creating a build
directory and calling cmake and make in it. See for example the command
lines below (optional steps which modify the build process are commented out):
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 ..
#ccmake . // in order to add/remove features like ScaFaCoS or CUDA
make
This will build ESPResSo with a default feature set, namely
src/config/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 installIt can invoke code checks:
make checkIt can build this documentation:
make sphinx
When these steps have successfully completed, ESPResSo can be started with the command:
./pypresso <SCRIPT>
where <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. Features¶
This chapter describes the features that can be activated in ESPResSo. Even if possible, it is not recommended to activate all features, because this will negatively affect ESPResSo’s performance.
Features can be activated in the configuration header myconfig.hpp (see
section myconfig.hpp: Activating and deactivating features). To
activate FEATURE, add the following line to the header file:
#define FEATURE
2.3.1. General features¶
ELECTROSTATICSThis enables the use of the various electrostatics algorithms, such as P3M.See also
MMM1D_GPUDIPOLESThis activates the dipole-moment property of particles; In addition, the various magnetostatics algorithms, such as P3M are switched on.SCAFACOS_DIPOLESROTATIONSwitch on rotational degrees of freedom for the particles, as well as the corresponding quaternion integrator.See also
Note
When this feature is activated, every particle has three additional degrees of freedom, which for example means that the kinetic energy changes at constant temperature is twice as large.
LANGEVIN_PER_PARTICLEAllows to choose the Langevin temperature and friction coefficient per particle.ROTATIONAL_INERTIAEXTERNAL_FORCESAllows to define an arbitrary constant force for each particle individually. Also allows to fix individual coordinates of particles, keep them at a fixed position or within a plane.MASSAllows particles to have individual masses. Note that some analysis procedures have not yet been adapted to take the masses into account correctly.EXCLUSIONSAllows to exclude specific short ranged interactions within molecules.BOND_CONSTRAINTTurns on the RATTLE integrator which allows for fixed lengths bonds between particles.VIRTUAL_SITES_COMVirtual sites are particles, the position and velocity of which is not obtained by integrating equations of motion. Rather, they are placed using the position (and orientation) of other particles. The feature allows to place a virtual particle into the center of mass of a set of other particles.See also
VIRTUAL_SITES_RELATIVEVirtual sites are particles, the position and velocity of which is not obtained by integrating equations of motion. Rather, they are placed using the position (and orientation) of other particles. The feature allows for rigid arrangements of particles.See also
METADYNAMICSCOLLISION_DETECTIONAllows particles to be bound on collision.
In addition, there are switches that enable additional features in the integrator or thermostat:
NPTEnables an on-the-fly NPT integration scheme.See also
MEMBRANE_COLLISIONENGINEPARTICLE_ANISOTROPY
2.3.2. Fluid dynamics and fluid structure interaction¶
DPDEnables the dissipative particle dynamics thermostat and interaction.See also
LB_BOUNDARIESLB_BOUNDARIES_GPUAFFINITYLB_ELECTROHYDRODYNAMICSEnables the implicit calculation of electro-hydrodynamics for charged particles and salt ions in an electric field.ELECTROKINETICSEK_BOUNDARIESEK_DEBUGEK_DOUBLE_PREC
2.3.3. Interaction features¶
The following switches turn on various short ranged interactions (see section Isotropic non-bonded interactions):
TABULATEDEnable support for user-defined non-bonded interaction potentials.LENNARD_JONESEnable the Lennard-Jones potential.LENNARD_JONES_GENERICEnable the generic Lennard-Jones potential with configurable exponents and individual prefactors for the two terms.LJCOSEnable the Lennard-Jones potential with a cosine-tail.LJCOS2Same asLJCOS, but using a slightly different way of smoothing the connection to 0.WCAEnable the Weeks–Chandler–Andersen potential.GAY_BERNEEnable the Gay–Berne potential (experimental).HERTZIANEnable the Hertzian potential.MORSEEnable the Morse potential.BUCKINGHAMEnable the Buckingham potential.SOFT_SPHEREEnable the soft sphere potential.SMOOTH_STEPEnable the smooth step potential, a step potential with two length scales.BMHTF_NACLEnable the Born–Meyer–Huggins–Tosi–Fumi potential, which can be used to model salt melts.GAUSSIANEnable the Gaussian potential.HATEnable the Hat potential.UMBRELLAEnable the umbrella potential (experimental).
Some of the short-range interactions have additional features:
LJGEN_SOFTCOREThis modifies the generic Lennard-Jones potential (LENNARD_JONES_GENERIC) with tunable parameters.THOLESee Thole correction
2.3.4. Debug messages¶
Finally, there is a flag for debugging:
ADDITIONAL_CHECKSEnables numerous additional checks which can detect inconsistencies especially in the cell systems. These checks are however too slow to be enabled in production runs.Note
Because of a bug in OpenMPI versions 2.0-2.1, 3.0.0-3.0.2 and 3.1.0-3.1.2 that causes a segmentation fault when running the ESPResSo OpenGL visualizer with feature
ADDITIONAL_CHECKSenabled together with eitherELECTROSTATICSorDIPOLES, the subset of additional checks for those two features are disabled if an unpatched version of OpenMPI is detected during compilation.
2.3.5. Features marked as experimental¶
Some of the above features are marked as EXPERIMENTAL. Activating these features can have unexpected side effects and some of them have known issues. If you activate any of these features, you should understand the corresponding source code and do extensive testing. Furthermore, it is necessary to define EXPERIMENTAL_FEATURES in myconfig.hpp.
2.3.6. External features¶
External features cannot be added to the myconfig.hpp file by the user.
They are added by CMake if the corresponding dependency was found on the
system. Some of these external features are optional and must be activated
using a CMake flag (see Options and Variables).
CUDAEnables GPU-specific features.FFTWEnables features relying on the fast Fourier transforms, e.g. P3M.H5MDWrite data to H5MD-formatted hdf5 files (see Writing H5MD-files)SCAFACOSEnables features relying on the ScaFaCoS library (see ScaFaCoS electrostatics, ScaFaCoS magnetostatics).GSLEnables features relying on the GNU Scientific Library, e.g.espressomd.cluster_analysis.Cluster.fractal_dimension().
2.4. Configuring¶
2.4.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 ESPResSo 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. LENNARD_JONES. For 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. Subsection Features describes all available features. If a
file named myconfig.hpp is present in the build directory when cmake
is run, all features defined in it will be compiled in. If no such file exists,
the configuration file src/config/myconfig-default.hpp will be used
instead, which 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
$builddir2/myconfig.hpp:
#define LJCOS
Then you can simply compile two different versions of ESPResSo via:
cd builddir1
cmake ..
make
cd builddir2
cmake ..
make
To see what features were activated in myconfig.hpp, run:
./pypresso
and then in the Python interpreter:
import espressomd
print(espressomd.features())
2.4.2. cmake¶
In order to build the first step is to create a build directory in which
cmake can be executed. In cmake, the source directory (that contains
all the source files) is completely separated from the build directory
(where the files created by the build process are put). cmake is
designed to not be executed in the source directory. cmake will
determine how to use and where to find the compiler, as well as the
different libraries and tools required by the compilation process. By
having multiple build directories you can build several variants of ESPResSo,
each variant having different activated features, and for as many
platforms as you want.
Once you’ve run ccmake, you can list the configured variables with
cmake -LAH -N .. | less (uses a pager) or with ccmake .. and pressing
key t to toggle the advanced mode on (uses the curses interface).
Example:
When the source directory is srcdir (the files where unpacked to this
directory), then the user can create a build directory build below that
path by calling mkdir srcdir/build. In the build directory cmake is to be
executed, followed by a call to make. None of the files in the source directory
are ever modified by the build process.
cd build
cmake ..
make
Afterwards ESPResSo can be run via calling ./pypresso from the command line.
2.4.3. ccmake¶
Optionally and for easier use, the curses interface to cmake can be used to configure ESPResSo interactively.
Example:
Alternatively to the previous example, instead of cmake, the ccmake executable is called in the build directory to configure ESPResSo, followed by a call to make:
cd build
ccmake ..
make
Fig. ccmake interface shows the interactive ccmake UI.
ccmake interface¶
2.4.4. Options and Variables¶
The behavior of ESPResSo can be controlled by means of options and variables
in the CMakeLists.txt file. Also options are defined there. The following
options are available:
WITH_CUDA: Build with GPU supportWITH_HDF5: Build with HDF5WITH_TESTS: Enable testsWITH_SCAFACOS: Build with ScaFaCoS supportWITH_VALGRIND_INSTRUMENTATION: Build with valgrind instrumentation markers
When the value in the CMakeLists.txt file is set to ON, the corresponding
option is created; if the value of the option is set to OFF, the
corresponding option is not created. These options can also be modified
by calling cmake with the command line argument -D:
cmake -D WITH_HDF5=OFF srcdir
In the rare event when working with cmake and you want to have a totally clean build (for example because you switched the compiler), remove the build directory and create a new one.
Environment variables can be passed to CMake. For example, to select Clang, use
CC=clang CXX=clang++ cmake .. -DWITH_CUDA=ON -DCUDA_NVCC_EXECUTABLE=$(which clang++).
If you have multiple versions of the CUDA library installed, you can select the
correct one with CUDA_BIN_PATH=/usr/local/cuda-9.0 cmake .. -DWITH_CUDA=ON
(with Clang as the CUDA compiler, you also need to override its default CUDA
path with -DCMAKE_CXX_FLAGS=--cuda-path=/usr/local/cuda-9.0).
2.5. Compiling, testing and installing¶
The command make is mainly used to compile the source code, but it
can do a number of other things. The generic syntax of the make
command is:
make [options] [target] [variable=value]
When no target is given, the target all is used. The following
targets are available:
allCompiles the complete source code. The variable can be used to specify the name of the configuration header to be used.
checkRuns the testsuite. By default, all available tests will be run on 1, 2, 3, 4, 6, or 8 processors.
cleanDeletes all files that were created during the compilation.
installInstall ESPResSo in the path specified by the CMake variable
CMAKE_INSTALL_PREFIX. The path can be changed by calling CMake withcmake .. -DCMAKE_INSTALL_PREFIX=/path/to/espresso. Do not usemake DESTDIR=/path/to/espresso installto install to a specific path, this will cause issues with the runtime path (RPATH) and will conflict with the CMake variableCMAKE_INSTALL_PREFIXif it has been set.doxygenCreates the Doxygen code documentation in the
doc/doxygensubdirectory.sphinxCreates the
sphinxcode documentation in thedoc/sphinxsubdirectory.tutorialsCreates the tutorials in the
doc/tutorialssubdirectory.docCreates all documentation in the
docsubdirectory (only when using the development sources).
A number of options are available when calling make. The most
interesting option is probably -j num_jobs, which can be used for
parallel compilation on computers that have more than one CPU or core.
num_jobs specifies the maximal number of jobs that will be run.
Setting num_jobs to the number of available processors speeds up the
compilation process significantly.
2.6. Running ESPResSo¶
2.6.1. Executing a simulation script¶
ESPResSo is implemented as a Python module. This means that you need to write a
python script for any task you want to perform with ESPResSo. In this chapter,
the basic structure of the interface will be explained. For a practical
introduction, see the tutorials, which are also part of the
distribution. To use ESPResSo, you need to import the espressomd module in your
Python script. To this end, the folder containing the python module
needs to be in the Python search path. The module is located in the
src/python folder under the build directory. A convenient way to run
python with the correct path is to use the pypresso script located in
the build directory.
./pypresso simulation.py
The pypresso script is just a wrapper in order to expose the ESPResSo python
module to the system’s python interpreter by modifying the $PYTHONPATH.
Please see the following chapter Setting up the system describing how
to actually write a simulation script for ESPResSo.
2.6.2. Running an interactive notebook¶
Running the Jupyter interpreter requires using the ipypresso script, which
is also located in the build directory (its name comes from the IPython
interpreter, today known as Jupyter). To run the tutorials, you will need
to start the Jupyter interpreter in notebook mode:
cd doc/tutorials
../../ipypresso notebook
You may then browse through the different tutorial folders. Files whose name
ends with extension .ipynb can be opened in the browser. Click on the Run
button to execute the current block, or use the keyboard shortcut Shift+Enter.
If the current block is a code block, the In [ ] label to the left will
change to In [*] while the code is being executed, and become In [1]
once the execution has completed. The number increments itself every time a
code cell is executed. This bookkeeping is extremely useful when modifying
previous code cells, as it shows which cells are out-of-date. It’s also
possible to run all cells by clicking on the “Run” drop-down menu, then on
“Run All Below”. This will change all labels to In [*] to show that the
first one is running, while the subsequent ones are awaiting execution.
You’ll also see that many cells generate an output. When the output becomes
very long, Jupyter will automatically put it in a box with a vertical scrollbar.
The output may also contain static plots, dynamic plots and videos. It is also
possible to start a 3D visualizer in a new window, however closing the window
will exit the Python interpreter and Jupyter will notify you that the current
Python kernel stopped. If a cell takes too long to execute, you may interrupt
it with the stop button.
To close the Jupyter notebook, go to the terminal where it was started and use the keyboard shortcut Ctrl+C twice.
When starting the Jupyter interpreter in notebook mode, you may see the following warning in the terminal:
[TerminalIPythonApp] WARNING | Subcommand `ipython notebook` is deprecated and will be removed in future versions.
[TerminalIPythonApp] WARNING | You likely want to use `jupyter notebook` in the future
This only means ESPResSo was compiled with IPython instead of Jupyter. If Jupyter
is installed on your system, the notebook will automatically close IPython and
start Jupyter. To recompile ESPResSo with Jupyter, provide cmake with the flag
-DIPYTHON_EXECUTABLE=$(which jupyter).
You can find the official Jupyter documentation at https://jupyter.readthedocs.io/en/latest/running.html
2.7. 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|