18. Contributing

Up to date information about the development of ESPResSo can be found at the web page http://espressomd.org As the important information can change in time, we will not describe its contents in detail but rather request the reader to go directly to the URL. Among other things, one can find information about the following topics there:

  • Latest stable release of and older releases

  • Obtaining development version of ESPResSo

  • Archives of both developers’ and users’ mailing lists

  • Registering to mailing lists

  • Submitting a bug report

18.1. Community support

If you have any questions concerning ESPResSo which you cannot resolve by yourself, you may search for an answer on:

If you still didn’t find a solution, you may consider either opening a new issue on GitHub or sending an email on the mailing list. Instructions on how to register to the mailing lists and post messages can be found in Mailing Lists.

For several reasons it is recommended to send all questions to the issue tracker or mailing list rather than to contact individual developers:

  • All registered users get your message and you have a higher probability that it is answered soon.

  • Your question and the answers are archived and the archives can be searched by others.

  • The answer may be useful also to other registered users.

  • There may not be a unique answer to your problem and it may be useful to get suggestions from different people.

Please remember that this is a community mailing list and a community issue tracker. It is other users and developers who are answering your questions. They do it in their free time and are not paid for doing it.

18.2. Contributing your own code

If you are planning to make an extension to or already have a piece of your own code which could be useful to others, you are very welcome to contribute it to the community. Before you start making any changes to the code, you should fork the espressomd/espresso repository and work in a new branch.

It is also generally a good idea to contact the developers on the mailing lists before you start major coding projects. It might be that someone else is already working on the problem or has a solution at hand.

You will find more detailed information on our development processes in Contributing to ESPResSo. Please also refer to our wiki.

18.2.1. Required Development Tools

  • First of all, please install the dependencies for compiling ESPResSo. See the section Installation.

  • To be able to access the development version of ESPResSo, you will need the distributed versioning control system git and a GitHub account to fork the espressomd/espresso repository

  • To build the user documentation, you will need Sphinx.

  • To build the tutorials, you will need Jupyter.

  • To build the core documentation, you will need Doxygen.

All of these tools should be easy to install on most Unix operating systems.

You can find all Python dependencies of ESPResSo in requirements.txt in the top-level source directory. Several optional packages for graphics, external devices and continuous integration (CI) are not strictly essential and can be safely removed if you’re planning on installing dependencies via pip:

pip3 install --upgrade --user -r requirements.txt

Note that some distributions now use pip3 for Python3 and pip2 for Python2.

18.3. Building the User’s guide

If, while reading this documentation, you notice any mistakes or badly (if at all) described features or commands, you are very welcome to contribute to the guide and have others benefit from your knowledge.

For this, you should clone the development version at espressomd/espresso. Next build the software as shown in Installation and then the documentation with make sphinx.