Navigation

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.

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:

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:

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

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/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: makeinstall

It can invoke code checks: makecheck

It can build this documentation: makesphinx

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

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:

EXCLUSIONS Allows to exclude specific short ranged interactions within
molecules.

See also

espressomd.particle_data.ParticleHandle.exclude

COMFIXED Allows to fix the center of mass of all particles of a certain type.

MOLFORCES (EXPERIMENTAL)

BOND_CONSTRAINT Turns on the RATTLE integrator which allows for fixed lengths bonds
between particles.

VIRTUAL_SITES_COM Virtual 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.

VIRTUAL_SITES_RELATIVE Virtual 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.

SWIMMER_REACTIONS Allows the user to define three particle types to be reactant,
catalyzer, and product. Reactants get converted into products in the
vicinity of a catalyst according to a used-defined reaction rate
constant. It is also possible to set up a chemical equilibrium
reaction between the reactants and products, with another rate
constant. Be careful the model makes usage of the word catalyst. This usage of the word cannot be brought into agreement with the correct usage of the word catalyst.

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.

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.

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 mkdirsrcdir/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.

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.

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:

all

Compiles the complete source code. The variable can be used to
specify the name of the configuration header to be used.

check

Runs the testsuite. By default, all available tests will be run on
1, 2, 3, 4, 6, or 8 processors.

clean

Deletes all files that were created during the compilation.

install

Install ESPResSo.
Use makeDESTDIR=/home/johninstall to install to a
specific directory.

doxygen

Creates the Doxygen code documentation in the doc/doxygen
subdirectory.

sphinx

Creates the sphinx code documentation in the doc/sphinx
subdirectory.

tutorials

Creates the tutorials in the doc/tutorials subdirectory.

doc

Creates all documentation in the doc subdirectory (only when
using the development sources).

A number of options are available when calling make. The most
interesting option is probably -jnum_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.

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 . 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 , 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 our
self built python modules to the systems python interpreter by
modifying the $PYTHONPATH.
Please see the following chapters describing how to actually write
a simulation script for 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.