Filing bug reports

If you discover a bug in ESPResSo, please let the developers know, so that they can fix it in the next release. The following sections explain how to file a bug report.

Before reporting a bug

Sometimes, bugs are already fixed in more recent version of ESPResSo, or in the development branch. You can save a lot of time by checking if the bug was already reported:

• check the release notes to see if the behavior has been fixed in a more recent versions of ESPResSo; you can get the version of ESPResSo with the shell command ./pypresso -c "import espressomd.version as v; print(v.friendly())"
• check the release notes of upcoming releases in the GitHub wiki, which are listed under "Planned releases" in the navigation bar
• query the bug in the ESPResSo issue tracker to check whether the bug has already been reported
• check the ESPResSo user's mailing list (Archives)

You may also consider activating C++ assertions by updating the build directory with cmake . -DCMAKE_BUILD_TYPE=RelWithAssert and rebuilding ESPResSo. The resulting binaries will run slightly slower, but will produce an error message if a runtime exception was found, for example a division by zero or an access out of bounds.

Reporting a bug

To help us finding the bug in the code, please open a ticket or send an e-mail to the mailing list.

Make sure to provide us with the following information:

• In what component of ESPResSo did you find the bug?
• In what version did you find the bug?
  • For an ESPResSo release, provide us with the exact release using ./pypresso -c "import espressomd.version as v; print(v.friendly())"
  • For the development branch, provide us with the commit SHA using git log --pretty=oneline -1
• Please give all possible information that you can provide, but at least the following:
  • The script that failed
    • If the script comes from ESPResSo, give us its filepath
    • For custom scripts, please remove as much of the code that is not relevant to reproduce the bug, and attach that minimal working example to the GitHub issue or email
  • All relevant error messages
    • The CMake output: it contains valuable information about your libraries
    • The pypresso error message or backtrace; please compile ESPResSo in debug mode to help us track the source of the error
      • You can usually get a backtrace by updating the build directory with cmake . -DCMAKE_BUILD_TYPE=Debug and rebuilding ESPResSo
      • In case of a fatal exception that shows no backtrace, try running the script with GDB to show where the exception is thrown:
        $> ./pypresso --gdb script.py
        (gdb) catch throw
        (gdb) run
        (gdb) bt
    • Here is a workflow to generate the required information in two files (cmake.log and trace.log) that can be attached to the GitHub issue or email, together with the minimal working example mwe.py:
      cmake --version | tee cmake.log
      cmake .. -DCMAKE_BUILD_TYPE=Debug 2>&1 | tee -a cmake.log
      make -j$(nproc)
      ./pypresso mwe.py 2>&1 | c++filt | tee trace.log
  • All relevant information about your build environment
    • Your operating system name and version, for example Ubuntu 20.04
    • The file myconfig.hpp that you used, or "default myconfig" if you didn't use one

If your bug report doesn't contain enough information to be actionable, a core developer will ask you to provide more detail.