Jean-Noël Grad

Author's posts

ESPResSo 4.1.3 released

This release provides a number of corrections for the ESPResSo 4.1 line. We recommend that this release be used for all production simulations. The interface has not been changed between ESPResSo 4.1.2 and 4.1.3. However, some bugs were discovered which can affect simulation results. Please find the list of changes below. The numbers in brackets refer to ticket numbers on

Feature configuration at compile time

  • The number of features which need to be defined at compile time in myconfig.hpp has been reduced. Features without performance impact are now always present. These are:

General corrections and improvements:

  • Many bonded interactions were not considered in the bond cutoff calculation: umbrella, OIF local, OIF global, IBM tribend, IBM volcons, angle harmonic, angle cosine, angle cossquare, tabulated angle, bonded Coulomb, subtracted bonded Coulomb, subtracted LJ, quartic, harmonic dumbbell. This can lead to sub-optimal skin values when such bonds are used with an inter-particle distance that is longer than other bonded (FENE, harmonic bond, rigid bond, thermalized distance, tabulated bond, tabulated dihedral, dihedral, IBM triel), non-bonded (LJ, Morse, Buckingham, etc.) and long-range (electrostatics, magnetostatics) interactions in the same system. All bonded interactions are now considered in the cutoff calculation (#3443).
  • Fix a bug in a rotation function that resulted in improper treatment of rotation vectors with norm different from unity (#3559); all observable classes inheriting from CylindricalProfile are affected
  • Fix a bug in the LB GPU implementation that lead to incorrect velocity interpolation near LB boundaries (#3593)
  • Fix a bug in the LB CPU implementation that lead to incorrect grid sizes (#3678)
  • Object-in-fluid bugfixes have been backported from the OIF development branch; in particular, the bending force between two triangles is now torque-free (#3385)
  • Rewrite the linear polymer position generator, which was inefficient and frequently rejected valid positions (#3402, #3484, #3491)
  • Fix an error in the distance calculation of the SpheroCylinder shape (#3629)
  • Fix a sign flip in the surface normal calculation of the Torus shape (#3728)
  • Fix an IndexError when running system.number_of_particles() without a value for the argument type (#3496, #3494) and fix the range check (#3536)
  • Fix a NameError when running system.analysis.rdf() without a value for the argument r_max (#3496, #3494)
  • Fix a NameError raised by the OpenGL visualizer when drawing bonds in periodic images of the unit cell (#3511)
  • Correctly calculate the orientation of bonds cut by the faces of the simulation box in the OpenGL visualizer (#3511)
  • Fix a memory leak in the OpenGL visualizer when drawing shapes containing cylindrical elements (Cylinder, SpheroCylinder, SimplePore, Slitpore) and drawing bonds between particles (#3533)
  • Fix an issue in the OpenGL visualizer that drew the channel of the Slitpore shape at the center of the box, instead of using the dividing_plane attribute (#3728)
  • Fix a bug in the ELC algorithm that ignored the Coulomb prefactor (#3731). The same bug is also present in MMM2D but could not be fixed.
  • Correctly check the P3M parameter mesh (#3676)
  • The LB checkpointing argument binary now takes a boolean value (#3541); integers values 0 and 1 are still accepted (integers are implicitly cast to boolean values)
  • Reinitialize the P3M and dipolar P3M solvers when the box size or skin changes (#3717)
  • Clarify error messages in the Steepest Descent integrator (#3763)
  • Fix an incorrect formula in the tensor_product mode of the Correlator class that always returned an array of 0’s since 4.1.0 (#3781)
  • Fix a runtime error when calling the get_params() method of a ScaFaCoS-based actor (#3784)

Documentation and tutorials corrections and improvements:

  • Fix paragraph formatting in Jupyter notebooks and update Sphinx bibliography (#3395).
  • The Sphinx documentation generation doesn’t run in parallel any longer due to plugin sphinxcontrib.bibtex throwing a warning when executed with more than one thread in Sphinx v2.3.1 (#3393). The slowdown is not significant (less than a second).
  • Fix compatibility issues with Sphinx 2.4.0 (#3480), 3.0.1 (#3642, #3659) and 1.6.7 (#3743)
  • Clarify the quaternion formalism used in ESPResSo (#3392, #3748)
  • The sample showcased an incorrect usage of the ELC actor (the gap region was missing). The actor was removed and a new, stand-alone sample was created (#3468)
  • The sample showcased an incorrect usage of the Slitpore and Wall shapes that lead to a discontinuous potential; this is now fixed (#3728)
  • Correct errors in the documentation of the constructor parameters for shape classes Cylinder, SpheroCylinder, Rhomboid (#3567), for class System (#3542) and for cylindrical observables (#3569)
  • Correct an error in the formula of the electrostatic prefactor in the electrostatics documentation, give the full expression of the electrostatic prefactor in tutorials and samples (#3673)
  • Improve documentation of the Slitpore shape and document the Torus shape (#3728)
  • Improve installation instructions (#3673, #3699, #3732)
  • Document BoxGeometry-related functions (#3747)
  • Explain release workflow and how to obtain released versions of ESPResSo (#3745)
  • Improve citation instructions with examples (#3745)
  • General improvements (#3740, #3743)

Build system and platform-related corrections and improvements:

  • The benchmarks can now be run with any MPI library supported by ESPResSo (#3412)
  • The CMake logic was simplified (#3574, parts of #3582). The minimal required Cython version is now checked. CMake now generates an error message if WITH_CLANG_TIDY is ON but no Clang-Tidy can be found with a version matching the Clang version. The CUDA library installed via the Ubuntu package nvidia-cuda-toolkit is now correctly detected.
  • Add support for ROCm versions 3.0 (#3386), 3.1 (#3574) and 3.3 (#3623)
  • Fix compiler errors with HDF5 > 1.10.2 (#3604)
  • Fix compiler errors with Boost 1.73 (#3725)
  • Fix a deprecation warning from the that will become an error in the upcoming Python 3.9 interpreter (#3568)
  • Fix a compatibility issue with pint 0.10.1 in tutorial 12 – constant pH (#3423)

Improved testing:

  • Fix a tolerance value that was incorrectly divided by 100, causing unit tests to fail on i586 architectures (#3427)
  • Compile CUDA code in the Travis-CI image to detect more compiler errors (#3699). GPU tests are skipped on Travis-CI.
  • Add a test for the Utils::get_n_triangle function used in OIF (#3391)
  • Add a test for sample (#3533)
  • Add missing LENNARD_JONES and GPU feature guards in Python tests (#3403, #3676)
  • Fix a few non-functional Python tests (#3419) and sample tests (#3791)
  • Improve testing of ELC (#3731)
  • Improve testing of the Slitpore shape (#3728)
  • Fix an issue in a core test (#3677)
  • Add cleanup function in the checkpointing tests (#3699)
  • Add a test for fold_position() (#3747)
  • Improve testing of observables, correlators and accumulators (#3781, #3783, #3784)

Under the hood changes:

  • Remove unused code (#3556, #3738)
  • Remove the unused FindPythonModule CMake module (#3736)
  • Update the espresso-ci bot scripts (#3613)

Invitation to the ESPResSo Summer School 2020

ESPResSo and Python: Versatile Tools for Soft Matter Research

Oct 5-9, 2020

online course


Notes from the Organizers

Due to the uncertainty related to the current Covid-19 situation, we have decided to virtualize the school, although maintaining the highly interactive format. Hands-on sessions will be tutored by experienced ESPResSo users and developers in small groups of participants, remotely via videoconferencing. There will be additional opportunities for scientific exchange during the social event, the user & developer meeting and the interactive talks.

The originally planned dates for the school are maintained. The coding sessions will take place in the afternoon, Central European Summer Time (UTC+02:00). Some tutoring groups could start earlier or later to accommodate for participants from different time zones, if there is sufficient interest.

Although this course is offered online, it is not designed as a MOOC: participation will be highly interactive, which limits the number of participants we can accept in the tutoring sessions. When registering for this course, please mention whether you are interested in taking part in the tutoring, or if you’re just interested in watching the lectures and talks. The lectures and talks will be recorded and made available on our website after the event, accessible to everyone enrolled in this course.

Course description

In this school, participants learn to conduct simulations in the fields of statistical physics, soft matter and active matter using the software ESPResSo. It is an open-source particle-based simulation package with a focus on coarse-grained molecular dynamics models. In addition, it offers a wide range of schemes for solving electrostatics and magnetostatics, hydrodynamics, electrokinetics, as well as algorithms for active matter, rigid bodies, and chemical reactions. ESPResSo consists of an MPI-parallelized simulation core written in C++ and a scripting interface in Python. This allows for good interoperability with other science and visualization tools for Python.

After an introduction to particle-based simulations and the simulation software, a wide range of topics will be covered: colloids, gels, polymers, magnetic fluids, and active matter. Lectures will provide an introduction to the physics and simulation model building as well as an overview of the necessary simulation algorithms such as electrostatics and hydrodynamics solvers. During the afternoon, participants will practice running simulations in hands-on sessions with the help of developers of the software. Participants can also get advice on their specific simulation projects. The final day of the school will be dedicated to research talks on projects that have been conducted using ESPResSo.


  • Analysis and management of scientific data
  • Basic simulations in ESPResSo and Python
  • Understanding and quantifying simulation errors
  • Polymer melts
  • Polyelectrolyte electrophoresis
  • Colloids and gels
  • Long-range interactions, electrostatics, magnetostatics, P3M algorithm
  • Hydrodynamic interactions, lattice-Boltzmann method
  • Electrokinetics
  • Molecular dynamics
  • Rigid body mechanics, virtual sites
  • Magnetic fluids
  • Active matter
  • Monte Carlo

Attendance to the summer school is free.

ESPResSo 4.1.2 released

This release provides a number of corrections for the ESPResSo 4.1 line. We recommend that this release be used for all production simulations. The interface has not been changed between ESPResSo 4.1.1 and 4.1.2. However, some bugs were discovered which can affect simulation results. Below, please find the list of changes. The numbers in brackets refer to ticket numbers on

General corrections and improvements:

  • Remove correlation between the rotational noise and translational noise in the Langevin thermostat (#3355)
  • Fix a bug that may cause the wrong temperature to be set by the Langevin and DPD thermostats in the first time step after the system was altered from the Python level, e.g., by changing particles or interactions (#3341)
  • Fix a bug that caused the DPD thermostat to generate an incorrect velocity distribution when used together with the Langevin thermostat (#3352)
  • Fix a bug in MMM2D and ELC with potential boundary conditions, where one of the correction factors was over-counted resulting in wrong energies (#3310)
  • Fix a bug that caused the wrong bonds to be deleted when removing particles from the system (#3356)
  • Fix an ambiguity in ParticleSlice: the values in the square brackets refer to particle ids, not array indices (#3367). This means the ill-defined syntax system.part[0:-1] is no longer valid. See the User Guide section on Setting up particles for more information.
  • Remove the mass prefactor in the ComForce observable and use the correct Particle ids in the ParticleAngularVelocities and ParticleBodyVelocities observables (#3380)
  • Fix a rounding error that caused debug builds of ESPResSo running with multiple MPI threads to crash when a particle was placed exactly on the boundary between two cells (#3377)
  • Fix espressomd.has_features() for the corner case where the list of all compiled-in features is passed as argument, returning False instead of True (#3318)
  • Refactor the random number generator code (#3349)
  • Minor fixes (#3351, #3336)

Documentation and tutorials corrections and improvements:

  • Improve documentation of Monte Carlo methods (#3254, #3330)
  • Minor fixes (#3342, #3334)

Build system and platform-related corrections and improvements:

  • List all Python dependencies in requirements.txt with the supported version numbers (#3300). Please note that most of them are optional.
  • Add MPIEXEC_PREFLAGS and MPIEXEC_POSTFLAGS to the command lines of parallel tests (#3221)
  • Add the -oversubscribe flag to the command lines of parallel tests running with OpenMPI v2.X to avoid exiting early from a Python test configured without MAX_NUM_PROC on a machine with a hyperthreaded CPU where OpenMPI is configured such that the number of threads cannot exceed the number of cores (#3335)
  • Refactor the CI, maintainer, Doxygen and pypresso shell scripts to make them more portable and support filepaths containing whitespaces (#3326, #3373)
  • Fix a nvcc compiler warning on the empty config (#3329)

Improved testing:

  • Add a test for ELC and MMM2D using analytic expressions of the force and energy (#3331)
  • Sped-up seven Python tests (#3319)
  • Fix a test that broke on s390x architectures with Fedora 31 (#3312)
  • Fix tests that broke on i586 architectures with OpenSUSE Tumbleweed (#3327, #3358)

ESPResSo 4.1.1 released

This release provides a number of corrections for Espresso 4.1. We recommend that this release be used for all production simulations. The interface is mostly unchanged between Espresso 4.1 and 4.1.1; the two exceptions are limited to these experimental features:

  • Integrator.set_isotropic_npt(): input value direction=[0,0,0] now throws an error instead of being silently changed to [1,1,1]
  • ParticleHandle.swimming: deprecated value 'rotational_friction' is now disabled

These changes are unlikely to affect production simulations. However, some bugs were discovered which can affect simulation results. Below, please find the list of changes. The numbers in brackets refer to ticket numbers on

General corrections and improvements:

  • Restore checkpointing mechanism for the steepest descent and NPT integrators, LB and NPT thermostats (#3245)
  • Increase the minimum MPI version to 3.0; OpenMPI versions 1.6.5 and lower are no longer supported (#3236)
  • Fix Integrator.set_isotropic_npt(): remove the silent conversion of the incorrect input parameter direction=[0,0,0] to [1,1,1] in the core; the function now throws an exception for fixed-volume boxes; this change is unlikely to break pypresso scripts since not providing a value to direction or providing [1,1,1] were the two standard ways to set up a box with all directions allowed to rescale (#3253)
  • Fix Integrator.set_vv(): this function failed to set the velocity Verlet integrator if the NPT integrator was active; this is now resolved (#3274)
  • Fix the random segmentation fault triggered by the removal of a particle with a bond or a virtual site relationship to another particle (#3288)
  • Fix system.part.writevtk(): the function now writes down all particles when using types="all" (#3290)
  • Disable the deprecated and broken ENGINE shear torque calculation feature; the feature will be completely removed from the core in the upcoming 4.2 release (#3277)
  • Fix unit conversion for the LB fluid viscosity (#3287)

Documentation and tutorials corrections and improvements:

  • Add more detailed installation instructions for ESPResSo and its Python dependencies on MacOS X (#3236)
  • Add links to Dockerfiles providing installation instructions for ESPResSo and its Python dependencies on CentOS 7, Fedora 30, Debian 10 and OpenSUSE Leap 15.1 (#3244)
  • Add instructions to read PDB files with MDAnalysis, which is one of the recommended tools to read/write molecular dynamics topologies and trajectories in ESPResSo; the PdbParser feature will be removed in the upcoming 4.2 release (#3257)
  • Add a new tutorial on the constant pH method; the reaction ensemble tutorial will be removed in the upcoming 4.2 release (#3184)

Build system and platform-related corrections and improvements:

  • Fix a PYTHONPATH error when ESPResSo is built in a directory containing whitespace characters (#3238)
  • Fix several issues with the command make install that lead to import errors in Python (incorrect runtime path, missing shared objects, name collision for submodule cluster_analysis) and deprecate the make install DESTDIR=/path/to/espresso command in favor of the standard cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/espresso command (#3228), install espressomd module in a platform-dependent python path, typically lib{,64}/python3.X/{dist,site}-packages (#3258)
  • Fix an issue in mpiio that triggered an assertion in systems with no bonds when ESPResSo is built with stdlibc++ range checking enabled (#3234)
  • Fix the pypresso script to correctly parse filepaths containing whitespaces passed after a pypresso flag, such as --gdb, and make conditional statements cross-platform (#3292)

Improved testing:

  • Test checkpointing of integrators and thermostats (#3245)
  • Fix and improve check_cmake_install test (#3228, #3258) and add a new CI job to test an installed version of ESPResSo (#3228)
  • Test engine LB (#3277)
  • Add more LB tests (#2748)

ESPResSo 4.1 released

This is a feature release, i.e., new functionality is added to Espresso. An additional focus of this release is quality assurance and modernization. The testing of Espresso’s functionality has been extended considerably. Also, sample and tutorial scripts are now automatically tested. Moreover, a large effort was put into modernizing the C++ simulation core. Work has been done, e.g., on particle sorting, the MPI communication infrastructure, and the lattice-Boltzmann implementations. Electrostatic and magnetostatic methods now have a clear and common interface. These changes will facilitate future extensions of Espresso and make the code more understandable to new developers.

We recommend that this release be used for all production simulations. No further bug fix releases will be provided for the 4.0 line, and not all fixes are present in Espresso 4.0.2.

Please carefully read the detailed list of changes below before using this release. The numbers in brackets refer to ticket numbers on

Get it in the Download area

Changed requirements

  • Python 2 support has been dropped. Espresso now requires Python 3. For additional information, please see
  • Espresso now needs a C++14-capable compiler, such as GCC 4.9 and later or Clang 4 and later.
  • It is discouraged to use Espresso with Boost versions below 1.67.

Added functionality and documentation

  • The distance between a shape (such as sphere) and a position can now be queried via shape.calc_distance().
  • The lattice nodes of a lattice-Boltzmann fluid can now be iterated using LBFluid.nodes().
  • A tutorial on magnetic fluids has been added.
  • The stress created by the dissipative particle dynamics interaction (DPD) can now be obtained via the DPDStress observable.
  • The stress of a lattice-Boltzmann fluid can now be obtained via the LBFluidStress observable.
  • A torus shape has been added.
  • Two new accumulators for observables have been added: MeanVarianceCalculator and TimeSeries.
  • An ElectricPlaneWave constraint was added.
  • Experimental support for AMD GPUs via HIP. The future of this feature is unclear. Please do not base hardware buying decisions on its presence.
  • Visualization of slit pores in the OpenGL visualizer.
  • A Weeks-Chandler-Anderson short-range potential has been added (WCA).
  • The external force density applied to a lattice-Boltzmann fluid can now be changed during the simulation.
  • Sanity checks for Mach limits and unequal MD and lattice-Boltzmann time steps have been added.
  • The system.cell_system.tune_skin() method now has a keyword argument adjust_max_skin. If set to True, the maximum skin to be tested will be reduced such that it is compatible with the local box size.
  • For the CPU lattice-Boltzmann implementation, the limit on the Verlet list skin (<0.5 agrid) has been lifted.
  • A new observable CosPersistenceAngles has been added for the bond angles of a polymer (needed, e.g., for determining the persistence length).

Feature configuration at compile time

  • The number of features which need to be defined at compile time in myconfig.hpp has been reduced. Features without performance impact are now always present. These are:
    • LB
    • LB_GPU (for builds with CUDA)
  • For most compilers, it is checked that only known features are declared in myconfig.hpp.
  • The default feature configuration applied when no myconfig.hpp is present has been extended significantly. In particular, all tutorials can now be run with the default feature configuration. For production simulations, it is still recommended to use a custom myconfig.hpp containing only necessary features. This is true in particular, if particle rotation is not needed.
  • Features that do not have automated tests now require EXPERIMENTAL_FEATURES to be defined in myconfig.hpp.

Interface changes

Changed and removed functionality

  • The remove_total_momentum() method for lattice-Boltzmann fluids has been removed. The overall velocity of a fluid can be changed using the lb_fluid.nodes() iterator.
  • The CATALYTIC_REACTIONS feature has been removed.
  • The method for creating a polymer has been replaced. espressomd.polymer.positions() can now be used to obtain particle positions for one or more polymer chains.
  • Checkpointing has been added for the electrokinetics method.
  • The global random number seed has been partly replaced by method-specific ones. These are specified when activating the relevant feature such as the Langevin, DPD and lattice-Boltzmann thermostats via a seed keyword argument.
  • The random number generator has been switched to Philox for most algorithms requiring random numbers.
  • Limitations on the exclusion radius have been relaxed in the reaction ensemble method.
  • A new observable CosPersistenceAngles has been added for the bond angles of a polymer (needed, e.g., for determining the persistence length).
  • ELC has been disabled for non-neutral systems with constant potential.
  • The calculation of the linear particle momentum included the forces of the last time step. The function system.analysis.linear_momentum() now returns the sum of the product of mass and velocity of all particles, if no lattice-Boltzmann fluid is coupled.

Performance enhancements

  • Speedup in the short-range force calculation in situations where the short-range cutoff varies strongly for different pairs of particles, e.g., in a bidisperse fluid.
  • Speedup in particle resorting triggered when particles have moved by more than a skin.
  • Significantly faster back-transfer of particle forces from GPU-based methods such as the GPU implementations of lattice-Boltzmann and P3M.

Bug fixes

  • Lattice-Boltzmann boundaries, constraints and auto_update_accumulators are now included in checkpointing. (#2915)
  • Collision detection is now checkpointed. (#2342)
  • The rhomboid shape was fixed. (#2756)
  • Deadlocks on certain GPUs have been resolved for the dipolar Barnes-Hut method. (#2719)
  • The visualization of dihedrals has been fixed. (#2677)
  • The ENGINE implementation for CPU LB has been fixed. (#3025)
  • The external force density in lattice-Boltzmann fluids is no longer ignored in the first integration step after setting the force density. (#3144)
  • The positions of virtual sites and the charges of ICC particles are now updated before observable calculation. (#3128)
  • The forces and torques for the Gay-Berne potential have been corrected. (#3091)
  • Remove undocumented behaviour in the case of using a cylindrical sampling area in the reaction ensemble, constant pH ensemble, Wang-Landau ensemble, Widom-Insertion method. (#3174)
  • The ELC tuning error calculation has been rearranged to produce correct results for higher accuracies. (#3123)

New tutorials

  • Tutorials for simulating ferrofluids and for using the constant-pH method have been added.

Under the hood changes

  • Automated testing has been enhanced. It now also includes samples and tutorials. The overall test coverage for the simulation core has increased by ~12% since Espresso 4.0.2.
  • The CPU LB and LB-particle coupling have been refactored.
  • Particle resorting has been simplified and sped-up.
  • The MPI callback mechanism has been simplified. Furthermore, reduction operations such as summing values from all MPI ranks can now be performed.
  • Nearly all manual memory management and C-style arrays have been removed.
  • The rotation-related code has been simplified.
  • Long-range electrostatic and magnetostatic methods now have a common interface.
  • The kernels for short-range and bonded interactions have been simplified.
  • The CMake build system has been refactored and dependencies between different parts of the code have been made clear.
  • Python code formatting: the autopep8 version now matches the one in Ubuntu 18.04 (autopep8 v1.3.4 with pycodestyle v2.3.1).