Skip to content

Installation FAQ

Jump to bottom
Jean-Noël Grad edited this page Mar 15, 2022 · 16 revisions

Table of Contents

Installation

From sources

Installation instructions for Linux and macOS are available online for the following releases:

From packages

The software is available via package managers on:

In a Docker container

Dockerfiles with fully functional build environments can be found for multiple Linux operating systems in espressomd/docker. There is one branch per ESPResSo minor release. The docker images can be downloaded from GitHub (espressomd/packages) or DockerHub (espressomd).

Here is a general procedure to setup a Jupyter-ready ESPResSo installation in a Docker container that can spawn a local server in the container that is accessible from outside. If the installation commands or Docker image get out of date, simply update this bash script based on the tutorials-samples-maxset job in the top-level .gitlab-ci.yml file. If you have a compatible NVIDIA GPU, you can make it visible by adding --runtime=nvidia or --gpus device=0 to the Docker command and then set the environment variable with_cuda=true to build ESPResSo with GPU support. 

docker run --user espresso -p 8888:8888 -it espressomd/docker-ubuntu-20.04:08d67d67a4d3c3279cacee975b68c02ec89b2a21 bash
pip3 install --user jupyter_contrib_nbextensions
jupyter contrib nbextension install --user
jupyter nbextension enable rubberband/main
jupyter nbextension enable exercise2/main
git clone --depth=1 --recursive -b python https://github.com/espressomd/espresso.git
cd espresso
export CC=gcc-8 CXX=g++-8 myconfig=maxset with_cuda=false make_check_unit_tests=false make_check_python=false
export build_procs=$(nproc) check_procs=$(nproc)
bash maintainer/CI/build_cmake.sh
cd build
make tutorials
cd doc/tutorials
../../ipypresso notebook --ip 0.0.0.0 --no-browser

The output of the ipypresso command will show the localhost URL and the token, usually in this form: 

  To access the notebook, copy and paste one of these URLs:
      http://127.0.0.1:8888/?token=d47146dbd0ad986250730bb091c991f5dadc3b6ec4c75e59
   or localhost:8888/?token=d47146dbd0ad986250730bb091c991f5dadc3b6ec4c75e59

Copy one of these URLs in your browser to connect to the local server. If port 8888 is already busy, you can use another port with e.g. -p 8891:8888 in the Docker command; in that case the output of ipypresso will incorrectly show 8888 in the URL and you will have to replace it with 8891.

Troubleshooting

CMake issues

CMake version is too old

Ubuntu 18.04 ships CMake 3.10, which is no longer supported. You can install a more recent version with: 

pip3 install --user 'cmake==3.17'

If you need ccmake (the curses interface to CMake), you will need to compile CMake from sources.

CMake 3.20.2 cannot fetch external projects

When running CMake twice in the same build folder with external projects enabled (e.g. Stokesian Dynamics or waLBerla), CMake can fail the second time with the following message: 

cmake -DWITH_CUDA=OFF -DWITH_WALBERLA=ON ..
[ 11%] Performing update step for 'stokesian_dynamics-populate'
fatal: reference is not a tree: 862a7537a366f0c32f0c25e46bd107bea590faea
CMake Error at /ssd/espresso/build/_deps/stokesian_dynamics-subbuild/stokesian_dynamics-populate-prefix/tmp/stokesian_dynamics-populate-gitupdate.cmake:175 (execute_process):
  execute_process failed command indexes:

    1: "Child return code: 128"

-- Configuring incomplete, errors occurred!

This is a regression in CMake 3.20.2 that was patched in 3.20.3 (ticket cmake/cmake#22166).

CMake cannot find ScaFaCoS

Follow the installation instructions in build-and-install-scafacos.sh. The --enable-portable-binary flag disables several architecture-specific optimizations.

This will install ScaFaCoS system-wide. To install it in a custom directory, add --prefix=${HOME}/bin/scafacos to the ./configure command, remove the ldconfig command, and add the following to your ~/.bashrc file after the installation: 

export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}${HOME}/bin/scafacos/lib"
export PKG_CONFIG_PATH="${PKG_CONFIG_PATH:+$PKG_CONFIG_PATH:}${HOME}/bin/scafacos/lib/pkgconfig"

Compilation issues

Compiler error with GCC 11

ESPResSo 4.1.3 and 4.1.4 are missing includes. Apply the patch for 4.1.3 (rpms/espresso@77dad47a) or 4.1.4 (rpms/espresso@e7dd6efa).

Compiler error with boost::optional

Error message: 

/usr/include/boost/serialization/optional.hpp:98:8: error: ‘version’ is not a class template
   98 | struct version<boost::optional<T> > {
or 
/usr/include/boost/serialization/optional.hpp:98:8: error: explicit specialization of undeclared template struct ‘version'
/usr/include/boost/serialization/version.hpp:36:8: error: redefinition of ‘version'

ESPResSo 4.1.3 and 4.1.4 are hit by a bug in Boost 1.74.0. Apply the patch in #3864 (comment).

Cannot import io when building the Cython code

Error message: Fatal Python error: Py_Initialize: can't initialize sys standard streams (#3149).

This is due to a faulty $PYTHONPATH environment variable. This typically happens when writing the following statement in ~/.bashrc: 

export PYTHONPATH=$PYTHONPATH:$HOME/bin/python-modules

If $PYTHONPATH was initially undefined or equal to the empty string, it is now equal to :/home/user/bin/python-modules. The colon symbol is used to separate folders. A leading colon means an empty string is part of the $PYTHONPATH, which is interpreted as the current working directory. The same happens with a trailing colon.

Here is a one-liner to remove the leading colon if $PYTHONPATH is empty: 

export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}${HOME}/bin/python-modules"

Works on Bash, Dash, C shell, Z shell.

Runtime issues

Tutorial constant-pH fails with pint

Ubuntu 18.04 ships pint 0.8 which has several known bugs. You can install a more recent version of pint with: 

pip3 install --user 'pint>=X.Y' # X.Y is found in requirements.txt

Import errors due to missing symbols

The following error message may appear when converting Cython modules to Python modules: 

Traceback (most recent call last):
  File "simulation_script.py", line 6, in <module>
    import espressomd.reaction_ensemble
ImportError: /home/user/espresso/build/src/python/espressomd/reaction_ensemble.so: undefined symbol:
_ZN15ReactionMethods17ReactionAlgorithm12add_reactionEdRKSt6vectorIiSaIiEES5_S5_S5_

When Cython source files (.pyx files) are deleted and replaced with Python files, the build folder will contain a mix of Python modules (.py files) and Cython shared objects (.so files) with the same base name but with a different extension, e.g. reaction_ensemble.py and reaction_ensemble.so. When importing espressomd.reaction_ensemble, the Python interpreter may resolve the outdated .so file instead of the .py file, in which case it will attempt to load symbols that may no longer exist in the ESPResSo core. To remediate this issue, delete the outdated .so file.

Likewise, when Cython include files (.pxd files) are deleted, all existing .so files in the build folder will attempt to load symbols that may no longer exist in the ESPResSo core during import, because .pxd files are included in all .pyx files. This can lead to confusing error messages about missing CUDA shared objects or about missing symbols for a feature X in an unrelated module Y. Since CMake doesn't explicitly track .pxd files, it cannot detect their deletion and therefore will not flag the existing .so files as out-of-date. To remediate this issue, whenever a .pxd file is deleted, clear all generated Cython data with rm src/python/espressomd/*.cpp and re-build ESPResSo.

Unit tests runtime error about libcuda.so

The following error message can appear if your OpenMPI library was built with CUDA support but your hardware doesn't have a CUDA-capable GPU: 

--------------------------------------------------------------------------
The library attempted to open the following supporting CUDA libraries,
but each of them failed.  CUDA-aware support is disabled.
libcuda.so.1: cannot open shared object file: No such file or directory
libcuda.dylib: cannot open shared object file: No such file or directory
/usr/lib64/libcuda.so.1: cannot open shared object file: No such file or directory
/usr/lib64/libcuda.dylib: cannot open shared object file: No such file or directory
If you are not interested in CUDA-aware support, then run with
--mca opal_warn_on_missing_libcuda 0 to suppress this message.  If you are interested
in CUDA-aware support, then try setting LD_LIBRARY_PATH to the location
of libcuda.so.1 to get passed this issue.
--------------------------------------------------------------------------
If this message is generated by a Boost unit test, make sure that it was properly linked against Boost::mpi and MPI::MPI_CXX. Otherwise, you can remediate the issue with export OMPI_MCA_opal_cuda_support=0 or by reconfiguring the ESPResSo tests with cmake . -D MPIEXEC_PREFLAGS="--mca;opal_warn_on_missing_libcuda;0".
Clone this wiki locally