Skip to content

Commit

Permalink
Modernized Readme file (#3745)
Browse files Browse the repository at this point in the history 
Follow-up to the [2020-05-26 ESPResSo meeting](https://github.com/espressomd/espresso/wiki/Espresso-meeting-2020-05-26#user-survey)

Description of changes:
- explain how to get released versions
- invite users to subscribe to the mailing list
- give clear instructions on how to cite ESPResSo
- for contributors, briefly explain our release workflow
  • Loading branch information
@kodiakhq
kodiakhq[bot] authored Jun 5, 2020
2 parents 6d509f7 + 448c048 commit eb54eda
Show file tree
Hide file tree
Showing 4 changed files with 162 additions and 39 deletions.
63 changes: 36 additions & 27 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <http://www.gnu.org/licenses/>.

You should have received a [copy](COPYING) of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
2 changes: 1 addition & 1 deletion doc/sphinx/contributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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|

Expand Down
125 changes: 114 additions & 11 deletions doc/sphinx/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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|

Expand Down Expand Up @@ -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 <Contributing>` and
:ref:`citing the software <How to cite ESPResSo>` 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 <https://github.com/espressomd/espresso/releases>`_.
Older releases from 2.1 to 3.3 can be found in
`GNU Savannah <http://download.savannah.gnu.org/releases/espressomd/>`_.
See our policy on :ref:`API backward compatibility
<Intended interface compatibility between ESPResSo versions>`
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 <https://github.com/espressomd/espresso/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 <https://github.com/espressomd/espresso/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
<https://github.com/espressomd/espresso/wiki/Offline-Espresso-meeting>`_,
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 <https://doi.org/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 <https://doi.org/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 <https://doi.org/10.1140/epjst/e2019-800186-9>`_.
11 changes: 11 additions & 0 deletions doc/sphinx/zrefs.bib
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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},
Expand Down

0 comments on commit eb54eda

Please sign in to comment.