Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modernized Readme file #3745

Merged
merged 9 commits into from
Jun 5, 2020
Merged

Modernized Readme file #3745

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b178521
docs: Cleanup API policy
jngrad May 30, 2020
f56ffbf
docs: Format GNU GPL license
jngrad May 30, 2020
e28cf22
docs: Add links to documentation resources
jngrad May 30, 2020
2735815
docs: Explain how to get ESPResSo releases
jngrad May 31, 2020
2d71cd1
docs: Explain release workflow and mailing list
jngrad May 31, 2020
f8ec2dd
docs: Show how to cite ESPResSo and its algorithms
jngrad May 31, 2020
06e19da
docs: Shorten license section
jngrad Jun 5, 2020
23a1e25
docs: Move mailing list up
jngrad Jun 5, 2020
448c048
Merge branch 'python' into rewrite-readme
kodiakhq[bot] Jun 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 36 additions & 27 deletions Readme.md
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should just refer to the (non-existing) License file that could then also serve as the header template.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be fine with shortening this section of the Readme to the following text, which links to the license and acknowledges both the MPI and ESPResSo organizations:

Copyright (C) 2010-2019 The ESPResSo project
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. A copy of the license is provided in [COPYING](COPYING).

The issue with providing instead a link to the header template is that the MPI line is missing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the MPI part missing in the header template? I think we should move the header template to LICENSE in the root and add the MPI part.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The license header can only contain years where the file received non-trivial contributions, therefore the MPI cannot appear for files created from scratch after 2010. Having this header template puts us in a grey area, since source files committed without a license header in the first commit where they appear are automatically licensed in a way that depends on the country(ies) of origin of the contributor, if I recall correctly. Adding the GPL after the fact during releases is not really permitted without the agreement of all people who committed non-trivial things in that file since its creation. That's why Google and Fedora have annoying bots that reject your contributions until you sign a legal document that allows them to relicense your contributions as GNU GPL if you forgot to put it in the first commit.

If I'm not mistaken, COPYING is the standard place to put the license in GNU GPL projects, while LICENSE is the standard place to put the license in Apache projects.


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
Open in desktop
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
Open in desktop
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
Open in desktop
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