Skip to content

es 430 release notes

Jump to bottom
Jean-Noël Grad edited this page Nov 22, 2024 · 11 revisions

These are the draft release notes for ESPResSo 4.3.0 (milestone).

ESPResSo 4.3

This is a feature release, i.e., new functionality is added to ESPResSo.

An additional focus of this release is replacing the original lattice-Boltzmann and electrokinetics codes by the waLBerla library. This structural change will allow the community to develop new LB and EK methods via pystencils and lbmpy and couple them to ESPResSo's molecular dynamics engine with relative ease.

Added functionality

  • The original LB and EK methods have been completely replaced with equivalent implementations based on the high-performance waLBerla library (#4726). This is a major API change that requires adapting all LB and EK scripts to use the new classes and arguments.

  • LB and EK methods now support setting boundary slip velocities on individual nodes (#4252).

  • LB now supports per-particle gamma (#4743). Only works for isotropic particles.

  • The OpenGL visualizer now uses different colors for arrows representing fluid velocities and slip velocities (#4252).

  • ESPResSo now supports the ZnDraw visualizer (#4967).

  • ESPResSo now has Atomic Simulation Environment (ASE) bindings (#4912). One application is interfacing ESPResSo with machine-learned potentials.

  • Thermostats and integrators have been redesigned as unified propagators (#4820, #4603). Multiple combinations of thermostats and integrators are now supported to solve multiphysics problems. While the Python interface remains mostly unchanged, internally the user-selected integrator is now the "main" integrator. Alternative integration schemes can then be enabled on a per-particle basis using the new propagation flag. An important consequence is that all virtual site types can now be enabled in the same simulation.

  • The magnetostatics.DipolarDirectSumCpu() feature now supports replicas and works in a MPI-parallel simulation (#4559).

  • The magnetostatics.DipolarDirectSumCpu() feature can now calculate the total dipole field experienced by each particle (#4626). Requires feature DIPOLE_FIELD_TRACKING.

  • Particle-based observables ParticleDirectors() and ParticleDipoleFields() were added (#4627, #4626).

  • It is now possible to extract particle neighbor lists with system.analysis.particle_neighbor_pids() (#4662). This feature will help prototyping simulations that interface with machine-learned potentials, which take a list of particle positions as input and output the force on the central particle.

  • The bond breakage feature now supports angle bonds (#4716).

  • Instrumentation tools Caliper, CUDA-GDB and kernprof are now natively supported (#4747).

Changed requirements

  • The project now requires C++20, CUDA 12 (#4612, #4931).

  • The Intel oneAPI C++ Compiler is now recognized by the CMake build system (#4532).

  • The minimal version of all dependencies was increased (#4532, #4612, #4717, #4931): CMake >= 3.25.2, Python >= 3.10, Cython >= 0.29.28, Boost >= 1.74, CUDA >= 12.0, OpenMPI >= 4.0, MPICH >= 3.4.1, GCC >= 10.5, Clang >= 14.0, AppleClang >= 14.0, Intel C++ Compiler Classic >= 2021.9, Intel oneAPI C++ Compiler >= 2023.1, and Python packages versions are pinned on versions available in the Ubuntu 22.04 repository.

  • All project-specific CMake options have been renamed (#4612). This change was required to avoid name collisions with external projects. Please refer to the user guide chapter on installing ESPResSo to find out the new option names. Using the old option names will generate warnings, but CMake will carry on and use default values instead of the values you provided. Please don't ignore these warnings when adapting your build scripts.

  • The waLBerla package is now a dependency of ESPResSo for all LB and EK methods (#2701, #4726).

Feature configuration at compile time

  • A Gitpod config file is now available to build the code automatically in a remote Gitpod workspace (#4531).

  • waLBerla support is opt-in and can be requested with the -D ESPRESSO_BUILD_WITH_WALBERLA=ON CMake flag (#2701, #4726).

  • The CMake option ESPRESSO_CUDA_COMPILER was removed in favor of the environment variable CUDACXX (#4642).

Improved documentation

  • A Widom insertion tutorial was added (#4546)

  • A lattice-Boltzmann sedimentation tutorial was added (#4570)

  • A machine-learned potentials tutorial was added (#4982).

  • An electrodes tutorial with ICC/ELC/ELC-IC was added (#4784).

  • The electrokinetics tutorial was completely rewritten and now features chemical reactions (#4782).

  • All tutorials were re-designed for JupyterLab (#4830). Reliance on Jupyter extensions and plugins has been significantly reduced in an effort to improve compatibility with other Jupyter backends. In particular, VS Code Jupyter is still actively supported. Jupyter Notebook (Classic Notebook) should still be compatible, although it is not actively tested. We no longer support compatibility with IPython.

  • Most tutorials adopted ZnDraw as the visualization backend (#4976, #4975).

  • A high-throughput computing sample based on the Dask scheduler was added ( #4781).

  • All supported debuggers and profilers are now documented: Caliper, Valgrind, GDB, CUDA-GDB, kernprof, perf, UBSAN, ASAN (#4747).

  • The CUDA 12 circular dependency in Ubuntu 24.04 packages is documented (#4642).

Interface changes

  • The original LB classes LBFluid and LBFluidGPU were removed in favor of LBFluidWalberla and LBFluidWalberlaGPU (#2701, #4726). Their arguments have also changed, e.g. dens became density and visc became viscosity. The pressure_tensor_neq property was removed.

  • The original EK class Electrokinetics was removed in favor of EKSpecies (#2701, #4726).

  • LB now support Lees-Edwards boundary conditions (#4977).

  • Self-propelled particles (swimmers) have been completely re-implemented (#4745). The propulsion mechanism can now only be set up with a force. When coupling to a LB fluid, a real particle and a virtual site are used to create the dipole.

  • The long-range actors API was completely redesigned (#4749).

  • The virtual sites API was completely redesigned (#4820, #4603).

  • The collision detection API was completely redesigned (#4987).

  • The Galilei transform API was completely redesigned (#4816).

  • Class attributes expecting 3 boolean values no longer accept integer values (#4541). It is no longer possible to set properties system.periodicity, particle.fix and particle.rotation with e.g. [1, 1, 1] or [0, 0, 1].

  • reaction_methods.ReactionAlgorithm.reaction() now takes steps instead of reaction_steps as argument for consistency with the MD integrator (#4666)

  • io.mpiio.Mpiio() now takes a system as argument (#4950).

  • cluster_analysis.ClusterStructure() now takes a system as argument (#4950).

  • interactions.ThermalizedBond() parameter seed was moved to system.thermostat.set_thermalized_bond() (#4845). This change better reflects the fact there is only one global seed for all thermalized bonds; until now this global seed was overwritten by any newly created thermalized bond, whether it was added to the system or not.

Removed functionality

  • The lb.LBBoundaries() framework was removed (#4381). Shapes can now be passed directly to LB and EK objects.

  • The magnetostatics.DipolarDirectSumWithReplicaCpu() method was removed, since the magnetostatics.DipolarDirectSumCpu() method now supports replicas (#4559).

  • The electrostatics.MMM1DGPU() feature was removed (#4928).

  • The magnetostatics.DipolarBarnesHutGpu() feature was removed (#4928).

  • The MDAnalysis bindings were removed (#4535)

  • The bind_three_particles collision mode was removed (#4823).

Improved testing

Performance enhancements

  • LB now supports multi-GPU acceleration (#5007).

  • Observables are now fully MPI-parallel and show better performance than equivalent operations by hdf5 or MPI-IO writing on a SSD (#4748).

  • Reaction methods are now fully MPI-parallel and now only invalidate the system state after a batch of particle changes have been applied (#4666).

Bug fixes

  • The particle_data.ParticleHandle() and io.writer.h5md.H5md() writer now use properly folded particle coordinates (#4940, #4944). In previous ESPResSo versions, cached coordinates would be used, which could be out-of-date when large Verlet list skin values were used.

  • Updating an active non-bonded interactions via e.g. system.non_bonded_inter[0, 0].lennard_jones.set_params() now uses the default arguments when optional arguments are missing and raises an error when required arguments are missing (#4558). In previous ESPResSo versions, missing optional and required arguments would be recycled from the previous state of the non-bonded interaction.

  • It is no longer possible to change the reaction constant of an existing reaction with a gamma value less or equal to 0 (#4666)

  • When setting up a reaction method with two or more reactions, a runtime error is raised if a reaction accidentally overwrites the default charge of a specific type with a different value (#4666)

  • It is no longer possible to add an angle bond or dihedral bond with a list partner particle ids containing duplicate entries, since the angle would be undefined (#5012).

  • Lees-Edwards boundary conditions now support the regular decomposition cell system via the new fully_connected_boundary argument (#4958).

  • Thermalized LB simulations are now fully decorrelated (#4845, #4848). In previous ESPResSo versions, the LB thermostat seed argument was actually used as the RNG counter, thus ensemble runs would produce almost the same trajectory.

  • Adding the same object twice in an ObjectList now raises a runtime error; removing an unknown object from an ObjectList now raises a runtime error (#4779). In previous ESPResSo versions, adding the same object twice in a list could have unintended side-effects.

Under the hood changes

  • Most Cython files have been converted to Python files (#4541, #4713).

  • Cython 3 is now supported (#4845).

  • GPU algorithms no longer leak device memory (#4741, #4764).

  • CPU implementations of the P3M algorithm no longer leak memory (#4947).

  • Project-specific compiler diagnostics are no longer propagated to external projects like waLBerla (#4642).

  • The build system now relies on CMake's native CUDA support (#4642).

  • The build system now installs the object-in-fluid Python module when espressomd is installed (#4931).

  • The script interface was massively simplified (#4816).

  • Most global variables were removed (#4741, #4783, #4816, #4845, #4950).

Clone this wiki locally