diff --git a/Readme.md b/Readme.md index 1f64fd52b68..276c42d8d36 100644 --- a/Readme.md +++ b/Readme.md @@ -47,45 +47,54 @@ simulations. It is mainly developed at the Institute for Computational Physics of the University of Stuttgart, but has contributors from all over the world. - ## Documentation -You can find documentation on how to compile, use and develop ESPResSo -on the homepage at [http://espressomd.org/html/doc/index.html](http://espressomd.org/html/doc/index.html). +The [user guide](http://espressomd.org/html/doc/index.html) will +walk you through the basic usage of ESPResSo. Advanced simulation +methods are extensively documented, with examples and links to the +relevant literature. Additional resources can be found on the +homepage at http://espressomd.org/wordpress/documentation/, such +as tutorials and doxygen documentation. + +## Installation + +Detailed installation instructions for Ubuntu and macOS can be found in the +documentation, section [Installation](http://espressomd.org/html/doc/installation.html). -ESPResSo is intended to be used by people that have proper knowledge -of simulation techniques and know how to use them. We do not take -responsibility if you use ESPResSo to create and publish bogus -results. You have been warned! +For most users, we recommend downloading the latest release version of ESPResSo. You +can find it in the [release page](https://github.com/espressomd/espresso/releases), +together with past releases until 4.0. When choosing a release, we recommend that +you get the latest bugfix release in that line. For example, for 4.1 you would like +to use 4.1.2. -## PLEASE CITE US! +### Join the community -If you use ESPResSo and obtain scientific results that you publish, we -would ask you to acknowledge the usage of ESPResSo by citing the relevant papers: -http://espressomd.org/wordpress/about/please-cite-us/ +Please consider subscribing to our +[mailing list](http://espressomd.org/wordpress/community-and-support/mailing-lists/) +if you're actively using ESPResSo, as we occasionally need community +feedback when making decisions on the future of specific features in +upcoming releases. You'll also get notifications on bugfix releases. -A number of algorithms in ESPResSo are fairly advanced and unique to -ESPResSo. The authors of these contributions kindly ask you to cite the -relevant publications, as indicated in the ESPResSo User's Guide. +### Please cite us! + +If you use ESPResSo to publish scientific results, we would ask you to +acknowledge this usage by mentioning the software with its version number and +[citing the relevant papers](http://espressomd.org/wordpress/about/please-cite-us/). +A number of algorithms in ESPResSo are fairly advanced and unique to ESPResSo. +The authors of these contributions kindly ask you to cite the relevant +publications, as indicated in the documentation. For detailed instructions, see +[How to cite ESPResSo](http://espressomd.org/html/doc/introduction.html#how-to-cite-espresso). ## License Copyright (C) 2010-2019 The ESPResSo project -Copyright (C) 2002,2003,2004,2005,2006,2007,2008,2009,2010 -Max-Planck-Institute for Polymer Research, Theory Group - -This file is part of ESPResSo. - + +Copyright (C) 2002-2010 Max-Planck-Institute for Polymer Research, Theory Group + ESPResSo is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - -ESPResSo is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . +You should have received a [copy](COPYING) of the GNU General Public License +along with this program. If not, see . diff --git a/doc/sphinx/contributing.rst b/doc/sphinx/contributing.rst index f5f9b9c4ca8..f889df7b86b 100644 --- a/doc/sphinx/contributing.rst +++ b/doc/sphinx/contributing.rst @@ -9,7 +9,7 @@ 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 +- Latest stable release of |es| and older releases - Obtaining development version of |es| diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index 2288cf5bf83..2277afedde7 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -417,7 +417,7 @@ use. We distinguish between five levels: In the "Tested" column, we note whether there is an integration test for the method. If you believe that the status of a certain method is wrong, please -report so to the developers. +report so to the developers using the instructions in :ref:`Contributing`. .. tabularcolumns:: |l|c|c|c| @@ -503,22 +503,125 @@ report so to the developers. -Intended interface compatibility between ESPResSo versions ----------------------------------------------------------- +.. _Software releases: -We use the following versioning scheme: -major.minor.patch_level +Software releases +----------------- -With regards to the stability of the Python interface, we plan the following guidelines: +|es| releases use the following versioning scheme: ``major.minor.patch_level``. +New features are introduced in major and minor releases, while bugfix releases +only patch bugs without adding or removing features. Since the ``patch_level`` +doesn't affect the capabilities of the software, it's common to refer to +releases simply as ``major.minor``. - * patch_level: The Python interface will not change, if only the patch_level number is different. Example: 4.0.0 -> 4.0.1. +New users should always choose the latest release. When opting for an +older release, we recommend using the latest bugfix release from that +line (for example 4.0.2 instead of 4.0), unless you need to capture the +behavior of bugs for reproducibility reasons. When filing bug reports +or citing |es|, the version should always be mentioned. See +our policies on :ref:`bug reports ` and +:ref:`citing the software ` for more details. - * minor: There will be no silent interface changes between two versions with different minor numbers. I.e., a simulation script will not silently produce different results with the new version. The interface can, however, be extended. In important cases, the interface can change in such a way that using the old interface produces a clear error message and the simulation is terminated. Example: 4.0.1 -> 4.1.0 +Releases from 4.0 onwards can be found on +`GitHub `_. +Older releases from 2.1 to 3.3 can be found in +`GNU Savannah `_. +See our policy on :ref:`API backward compatibility +` +if you need more details. - * major: No guarantees are made for a transition between major versions. Example 4.1.2 -> 5.0. +.. _Release workflow: - * No guarantees are made with regards to the development branch on GitHub. +Release workflow +^^^^^^^^^^^^^^^^ - * No guarantees are made with respect to the C++ bindings in the simulation core. +Major and minor releases are branched from the development branch ``python``. +When a version ``X.Y.0`` is released, the ``python`` branch is copied +to a new branch named ``X.Y``, at which point the ``python`` branch is ready +to accept contributions for the ``X.Y+1.0`` release. The ``X.Y`` branch +still gets bugfix releases ``X.Y.1``, ``X.Y.2``, ..., for several months. +`GitHub milestones `_ +track the progress of each release. They can give you an idea of the changes +in future releases, although it's more convenient to follow the live release +notes in the `wiki `_ (listed +under "Planned releases" in the side bar). These notes are updated monthly. +Most users will only be interested in the live release notes of the +planned bugfix release for the version of |es| they're using. + +If you're actively developing code for |es|, you might also be interested in +the summaries of the `ESPResSo meetings +`_, +where the core team discusses plans for future releases and feature freezes. + +.. _Intended interface compatibility between ESPResSo versions: + +Intended interface compatibility between |es| versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With regards to the stability of the Python interface, we have the following +guidelines: + +* ``patch_level``: The Python interface will not change if only the + ``patch_level`` number is different. Example: 4.0.0 :math:`\to` 4.0.1. + +* ``minor``: There will be no silent interface changes between two versions + with different minor numbers, i.e. a simulation script will not silently + produce different results with the new version. The interface can, however, + be extended. In important cases, the interface can change in such a way + that using the old interface produces a clear error message and the + simulation is terminated. Example: 4.0.2 :math:`\to` 4.1.0. + +* ``major``: No guarantees are made for a transition between major versions. + Example: 4.1.2 :math:`\to` 5.0. + +* No guarantees are made with regards to the development branch on GitHub. + +* No guarantees are made with respect to the C++ bindings in the simulation core. + +.. _How to cite ESPResSo: + +How to cite |es| +^^^^^^^^^^^^^^^^ + +Please cite :cite:`weik19a` (BibTeX key ``weik19a`` in :file:`doc/sphinx/zrefs.bib`) +for |es| 4.0 and later, or :cite:`arnold13a` and :cite:`limbach06a` +(BibTeX keys ``arnold13a`` and ``limbach06a`` in :file:`doc/sphinx/zrefs.bib`) +for |es| 2.0 to 3.3. To find the version number, use the following command: + +.. code-block:: bash + + ./pypresso -c "import espressomd.version;print(espressomd.version.friendly())" + +A number of algorithms in |es| are fairly advanced and unique to |es|. +The authors of these contributions kindly ask you to cite the relevant +publications, using the BibTeX entries indicated in this user guide. + +A complete citation would look like this: + + Simulations were carried out with ESPResSo 4.1[24] using the ICC\* + algorithm[25]. + + | [24] F. Weik, R. Weeber, K. Szuttor *et al.* ESPResSo 4.0 -- an + extensible software package for simulating soft matter systems. + *Eur. Phys. J. Spec. Top.* **227**, 1789--1816 (2019). + doi:\ `10.1140/epjst/e2019-800186-9 `_. + | [25] C. Tyagi, M. Süzen, M. Sega *et al.* An iterative, fast, + linear-scaling method for computing induced charges on arbitrary + dielectric boundaries. *J. Chem. Phys.* **132**, 154112 (2010). + doi:\ `10.1063/1.3376011 `_. + +You may also provide the patch level, when relevant. If you developed code +for |es| and made it available in a publicly accessible repository, you +should consider providing the corresponding URL, for example in a footnote: + + The method was implemented for ESPResSo 4.1.2[24]. The full code is + available online\*. + + | \* https://github.com/username/espresso/tree/implemented-algorithm + + | [24] F. Weik, R. Weeber, K. Szuttor *et al.* ESPResSo 4.0 -- an + extensible software package for simulating soft matter systems. + *Eur. Phys. J. Spec. Top.* **227**, 1789--1816 (2019). + doi:\ `10.1140/epjst/e2019-800186-9 `_. diff --git a/doc/sphinx/zrefs.bib b/doc/sphinx/zrefs.bib index 3f551bd0a91..4908486963d 100644 --- a/doc/sphinx/zrefs.bib +++ b/doc/sphinx/zrefs.bib @@ -976,6 +976,17 @@ @Article{hofling11a doi = {10.1039/C0SM00718H}, } +@Article{weik19a, + author = {Weik, Florian and Weeber, Rudolf and Szuttor, Kai and Breitsprecher, Konrad and de Graaf, Joost and Kuron, Michael and Landsgesell, Jonas and Menke, Henri and Sean, David and Holm, Christian}, + title = {{ESPResSo} 4.0 -- An Extensible Software Package for Simulating Soft Matter Systems}, + journal = {The European Physical Journal Special Topics}, + year = {2019}, + volume = {227}, + number = {14}, + pages = {1789--1816}, + doi = {10.1140/epjst/e2019-800186-9}, +} + @article{yaghoubi2015a, title={New modified weight function for the dissipative force in the {DPD} method to increase the {S}chmidt number}, author={Yaghoubi, S and Shirani, E and Pishevar, AR and Afshar, Yaser},