Improve documentation (#5255)

Description of changes:
- rewrite changelog based on Keep a Changelog v1.1.0
- move `NotesForTutors.md` to `Readme.md` to make the information more discoverable
- add citations and update user guide

Author: jngrad

NEWS CHANGELOG.mdNEWS renamed to CHANGELOG.md

@@ -180,6 +180,23 @@ @Article{banchio03a
   doi     = {10.1063/1.1571819},
 }
 
+@InProceedings{batatia22a,
+author = {Batatia, Ilyes and Kov{\'a}cs, D{\'a}vid P{\'e}ter and Simm, Gregor N. C. and Ortner, Christoph and Cs{\'a}nyi, G{\'a}bor},
+title = {{MACE}: higher order equivariant message passing neural networks for fast and accurate force fields},
+booktitle = {Advances in Neural Information Processing Systems},
+editor = {Koyejo, Sanmi and Mohamed, Shakir and Agarwal, Alekh and Belgrave, Danielle and Cho, Kyunghyun and Oh, Alice},
+volume = {35},
+year = {2022},
+pages = {11423--11436},
+eventtitle = {36\textsuperscript{th} Conference on Neural Information Processing Systems ({NeurIPS} 2022)},
+eventdate = {2022-11-28/2022-12-09},
+venue = {New Orleans Convention Center, Louisiana, USA},
+isbn = {978-1-7138-7108-8},
+url = {https://proceedings.neurips.cc/paper_files/paper/2022/file/4a36c3c51af11ed9f34615b81edb5bbc-Paper-Conference.pdf},
+publisher = {Curran Associates, Inc.},
+address={Red Hook, New York, USA},
+}
+
 @Article{batatia25a,
 author = {Batatia, Ilyes and Benner, Philipp and Chiang, Yuan and Elena, Alin M. and Kov{\'a}cs, D{\'a}vid P. and Riebesell, Janosh and Advincula, Xavier R. and Asta, Mark and Avaylon, Matthew and Baldwin, William J. and Berger, Fabian and Bernstein, Noam and Bhowmik, Arghya and Bigi, Filippo and Blau, Samuel M. and C\{u a}rare, Vlad and Ceriotti, Michele and Chong, Sanggyu and Darby, James P. and De, Sandip and Della Pia, Flaviano and Deringer, Volker L. and Elijo{\v s}ius, Rokas and El-Machachi, Zakariya and Fako, Edvin and Falcioni, Fabio and Ferrari, Andrea C. and Gardner, John L. A. and Gawkowski, Miko{\l}aj J. and Genreith-Schriever, Annalena and George, Janine and Goodall, Rhys E. A. and Grandel, Jonas and Grey, Clare P. and Grigorev, Petr and Han, Shuang and Handley, Will and Heenen, Hendrik H. and Hermansson, Kersti and Ho, Cheuk Hin and Hofmann, Stephan and Holm, Christian and Jaafar, Jad and Jakob, Konstantin S. and Jung, Hyunwook and Kapil, Venkat and Kaplan, Aaron D. and Karimitari, Nima and Kermode, James R. and Kourtis, Panagiotis and Kroupa, Namu and Kullgren, Jolla and Kuner, Matthew C. and Kuryla, Domantas and Liepuoniute, Guoda and Lin, Chen and Margraf, Johannes T. and Magd\{u a}u, Ioan-Bogdan and Michaelides, Angelos and Moore, J. Harry and Naik, Aakash A. and Niblett, Samuel P. and Norwood, Sam Walton and O'Neill, Niamh and Ortner, Christoph and Persson, Kristin A. and Reuter, Karsten and Rosen, Andrew S. and Rosset, Louise A. M. and Schaaf, Lars L. and Schran, Christoph and Shi, Benjamin X. and Sivonxay, Eric and Stenczel, Tam{\'a}s K. and Sutton, Christopher and Svahn, Viktor and Swinburne, Thomas D. and Tilly, Jules and van der Oord, Cas and Vargas, Santiago and Varga-Umbrich, Eszter and Vegge, Tejs and Vondr{\'a}k, Martin and Wang, Yangshuai and Witt, William C. and Wolf, Thomas and Zills, Fabian and Cs{\'a}nyi, G{\'a}bor},
 title = {A foundation model for atomistic materials chemistry},
@@ -1484,6 +1501,21 @@ @Article{wang01a
   doi       = {10.1063/1.1398588},
 }
 
+@InCollection{weeber24a,
+  author    = {Weeber, Rudolf and Grad, Jean-No\"{e}l and Beyer, David and Blanco, Pablo M. and Kreissl, Patrick and Reinauer, Alexander and Tischler, Ingo and Ko{\v{s}}ovan, Peter and Holm, Christian},
+  title     = {{ESPResSo}, a Versatile Open-Source Software Package for Simulating Soft Matter Systems},
+  booktitle = {Comprehensive Computational Chemistry},
+  year      = {2024},
+  editor    = {Y{\'a}{\~n}ez, Manuel and Boyd, Russell J.},
+  edition   = {1st},
+  volume    = {3},
+  publisher = {Elsevier},
+  isbn      = {978-0-12-823256-9},
+  pages     = {578--601},
+  doi       = {10.1016/B978-0-12-821978-2.00103-3},
+  address   = {Oxford},
+}
+
 @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},

ChangeLog

@@ -35,7 +35,7 @@ Velocity Verlet algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The velocity Verlet integrator is active by default.
-If you used a different integrator and want to switch back, use 
+If you used a different integrator and want to switch back, use
 :meth:`system.integrator.set_vv() <espressomd.integrate.IntegratorHandle.set_vv>`.
 
 The Velocity Verlet algorithm is used for equations of motion of the general form
@@ -75,22 +75,25 @@ Read, e.g., :math:`\vec{x}` as the position of all particles.
 
 Note that this implementation of the velocity Verlet algorithm reuses
 forces in step 1. That is, they are computed once in step 3,
-but used twice, in step 4 and in step 1 of the next iteration. 
-The first time the integrator is called, there are no forces present yet. 
+but used twice, in step 4 and in step 1 of the next iteration.
+The first time the integrator is called, there are no forces present yet.
 Therefore, |es| has
 to compute them before the first time step. That has two consequences:
-first, if thermostats are active, random forces are computed twice during 
+first, if thermostats are active, random forces are computed twice during
 the first time step, resulting in a narrower distribution of the random forces.
 Second,
 coupling forces of, e.g., the lattice-Boltzmann fluid cannot be computed
 and are therefore lacking in the first half time step. In order to
 minimize these effects, |es| has a quite conservative heuristics to decide
-whether a change makes it necessary to recompute forces before the first time step. 
-Therefore, calling 
-:meth:`espressomd.integrate.Integrator.run` 100 times with ``steps=1`` is equivalent to calling it once with ``steps=100``.
-
-When resuming a simulation, you can either use the forces that are stored on the particles by using the additional parameter ``reuse_forces = True``, or recalculate the forces again from the current configuration ``reuse_forces = False``.
-Setting ``reuse_forces = True`` is useful when restarting a simulation from a checkpoint to obtain exactlty the same result as if the integration had continued without interruption.
+whether a change makes it necessary to recompute forces before the first time step.
+Therefore, calling :meth:`espressomd.integrate.Integrator.run` 100 times
+with ``steps=1`` is equivalent to calling it once with ``steps=100``.
+
+When resuming a simulation, you can either use the forces that are stored
+on the particles by using the additional parameter ``reuse_forces = True``,
+or recalculate the forces again from the current configuration ``reuse_forces = False``.
+Setting ``reuse_forces = True`` is useful when restarting a simulation from a checkpoint
+to obtain exactly the same result as if the integration had continued without interruption.
 You can also use ``recalc_forces = True`` to recalculate forces even if they are already correctly computed.
 
 .. _Isotropic NpT integrator:
@@ -121,7 +124,7 @@ with parameters:
 * ``gamma0``: Friction coefficient of the bath
 * ``gammav``: Artificial friction coefficient for the volume fluctuations.
 
-The physical meaning of these parameters and the equations of motion are described below. 
+The physical meaning of these parameters and the equations of motion are described below.
 We recommend reading :ref:`Langevin thermostat` before continuing.
 
 The relaxation towards a desired pressure :math:`P` (parameter ``ext_pressure``)
@@ -137,7 +140,7 @@ associated with the volume is postulated. This results in a "force" on the box s
 
 where
 
-.. math:: \mathcal{P} = \frac{1}{Vd} \sum_{i,j} \vec{f}_{ij}\vec{x}_{ij} + \frac{1}{Vd} \sum_i m_i v_i^2 , 
+.. math:: \mathcal{P} = \frac{1}{Vd} \sum_{i,j} \vec{f}_{ij}\vec{x}_{ij} + \frac{1}{Vd} \sum_i m_i v_i^2,
 
 is the instantaneous pressure, with :math:`d` the dimension
 of the system (number of flags set by ``direction``), :math:`\vec{f}_{ij}` the
@@ -319,8 +322,8 @@ A code snippet could look like::
 
     max_steps = 20 # maximal number of steps
     system.integrator.set_steepest_descent(
-        f_max=0, gamma=0.1, max_displacement=0.1)
-    system.integrator.run(max_steps)   
+        f_max=0., gamma=0.1, max_displacement=0.1)
+    system.integrator.run(max_steps)
     system.integrator.set_vv()  # to switch back to velocity Verlet
 
 The 'equation of motion' in discretised form reads
@@ -335,7 +338,7 @@ This feature is used to propagate each particle by a small distance parallel to
 When only conservative forces for which a potential exists are in use, this is equivalent to a steepest descent energy minimization.
 A common application is removing overlap between randomly placed particles.
 Please note that the behavior is undefined if a thermostat is activated,
-in which case the integrator will generate an error. 
+in which case the integrator will generate an error.
 
 Steepest descent is applied
 while the maximal force/torque is bigger than ``f_max``, or for at most ``max_steps`` times. The energy
@@ -357,12 +360,11 @@ The ``f_max`` parameter can be set to zero to prevent the integrator from
 halting when a specific force/torque is reached. The integration can then
 be carried out in a loop with a custom convergence criterion::
 
-    min_dist_target = 1 # minimum distance that all particles should have
-    
-    system.integrator.set_steepest_descent(f_max=0, gamma=10,
+    min_dist_target = 1. # minimum distance that all particles should have
+    system.integrator.set_steepest_descent(f_max=0., gamma=10.,
                                            max_displacement= 0.01)
     # gradient descent until particles are separated by at least min_dist_target
-    min_dist = 0.0
+    min_dist = 0.
     while min_dist < min_dist_target:
         min_dist = system.analysis.min_dist()
         system.integrator.run(10)
@@ -389,7 +391,7 @@ The correct forces need to be re-calculated after running the integration::
     p1 = system.part.add(pos=[0, 0, 0], type=1)
     p2 = system.part.add(pos=[0, 0, 0.1], type=1)
     p2.vs_auto_relate_to(p1)
-    system.integrator.set_steepest_descent(f_max=800, gamma=1.0, max_displacement=0.01)
+    system.integrator.set_steepest_descent(f_max=800., gamma=1., max_displacement=0.01)
     while convergence_criterion(system.part.all().f):
         system.integrator.run(10)
         system.integrator.run(0, recalc_forces=True)  # re-calculate forces from virtual sites
@@ -398,7 +400,7 @@ The correct forces need to be re-calculated after running the integration::
 The algorithm can also be used for energy minimization::
 
     # minimize until energy difference < 5% or energy < 1e-3
-    system.integrator.set_steepest_descent(f_max=0, gamma=1.0, max_displacement=0.01)
+    system.integrator.set_steepest_descent(f_max=0., gamma=1., max_displacement=0.01)
     relative_energy_change = float('inf')
     relative_energy_change_threshold = 0.05
     energy_threshold = 1e-3
@@ -441,7 +443,7 @@ The particle trajectories are governed by
 
 .. math:: \dot{\vec{x}}_i(t) = \gamma^{-1} \vec{F}_i(\{\vec{x}_j\}, \{\vec{v}_j\}, t) + \sqrt{2 k_B T \gamma^{-1}} \vec{\eta}_i(t),
 
-where :math:`\vec{F}_i` are all deterministic forces from interactions and :math:`\vec{\eta}_i` 
+where :math:`\vec{F}_i` are all deterministic forces from interactions and :math:`\vec{\eta}_i`
 are random forces with zero mean and unit variance.
 This equation of motion follows from Langevin's equation of motion (see :ref:`Langevin thermostat`)
 by setting the mass of the particle to zero.
@@ -452,15 +454,15 @@ and reads
 .. math:: \vec{x}(t+ dt) = \gamma^{-1} \vec{F}(\vec{x}(t), \vec{v}(t), t) dt + \sqrt{2 k_B T \gamma^{-1} dt} \vec{\eta}_*(t)
 
 where :math:`\vec{\eta_*}` are pseudo-random numbers with zero mean and unit variance (particle indices are omitted for clarity).
-Velocities are obtained directly from 
+Velocities are obtained directly from
 
 .. math:: \vec{v}(t) = \gamma^{-1} \vec{F} + \sqrt{2 k_B T \gamma^{-1} dt^{-1}} \vec{\eta}_{*}(t)
 
 Be aware that the velocity contains random terms and is therefore not continuous in time.
 
 Rotational motion is implemented analogously.
 Note: the rotational Brownian dynamics implementation is only compatible with particles which have
-the isotropic moment of inertia tensor. 
+the isotropic moment of inertia tensor.
 Otherwise, the viscous terminal angular velocity
 is not defined, i.e., it has no constant direction.
 
@@ -549,7 +551,7 @@ subsections.
 
 You may combine different thermostats by turning them on sequentially.
 Not all combinations of thermostats are sensible, though, and some
-thermostats only work with specific integrators. 
+thermostats only work with specific integrators.
 The list of possible combinations of integrators and thermostats is hardcoded and automatically
 checked against at the start of integration.
 Note that there is only one temperature for all thermostats.
@@ -595,23 +597,22 @@ The friction term accounts for dissipation in a surrounding fluid whereas
 the random force  mimics collisions of the particle with solvent molecules
 at temperature :math:`T` and satisfies
 
-.. math:: <\vec{\eta}(t)> = \vec{0} , <\eta^\alpha_i(t)\eta^\beta_j(t')> = \delta_{\alpha\beta} \delta_{ij}\delta(t-t')
+.. math:: \left\langle\vec{\eta}(t)\right\rangle = \vec{0} , \left\langle\eta^\alpha_i(t)\eta^\beta_j(t')\right\rangle = \delta_{\alpha\beta} \delta_{ij}\delta(t-t')
 
-(:math:`<\cdot>` denotes the ensemble average and :math:`\alpha,\beta` are spatial coordinates).
+(:math:`\langle\cdot\rangle` denotes the ensemble average and :math:`\alpha,\beta` are spatial coordinates).
 
 In the |es| implementation of the Langevin thermostat,
 the additional terms only enter in the force calculation.
 The general form of the equation of motion is still the same as
-for Newton's equations, therefore the velocity Verlet integrator is 
-used.
+for Newton's equations, therefore the velocity Verlet integrator is used.
 The accuracy of the velocity Verlet integrator is reduced by
 one order in :math:`dt` because forces are now velocity-dependent.
 
 The random process :math:`\vec{\eta}(t)` is discretized by drawing an uncorrelated random numbers
 :math:`\vec{\eta_*}` for each particle.
 The distribution of :math:`{\vec{\eta}_*}` is uniform and satisfies
 
-.. math:: <\vec{\eta}_*> = \vec{0} ,\, <\eta_*^\alpha \eta_*^\beta> =  \frac{\delta_{\alpha,\beta}}{dt},
+.. math:: \left\langle\vec{\eta}_*\right\rangle = \vec{0} ,\, \left\langle\eta_*^\alpha \eta_*^\beta\right\rangle =  \frac{\delta_{\alpha,\beta}}{dt},
 
 approximating the delta-correlation of the continuous equation.
 
@@ -717,7 +718,7 @@ The :ref:`Lattice-Boltzmann` thermostat acts similar to the :ref:`Langevin therm
 .. math::  m_i \dot{\vec{v}}_i(t) = \vec{f}_i(\{\vec{x}_j\},\vec{v}_i,t) - \gamma (\vec{v}_i(t)-\vec{u}(\vec{x}_i(t),t)) + \sqrt{2\gamma k_B T} \vec{\eta}_i(t).
 
 where :math:`\vec{u}(\vec{x},t)` is the fluid velocity at position :math:`\vec{x}` and time :math:`t`.
-Different from the Langevin thermostat, here, the friction is calculated with respect to a moving fluid. 
+Different from the Langevin thermostat, here, the friction is calculated with respect to a moving fluid.
 
 An LB fluid must be used to provide the fluid velocity, while also including hydrodynamic interactions between particles.
 The LB thermostat expects an instance of :class:`espressomd.lb.LBFluid`.
@@ -750,7 +751,7 @@ according to the given temperature and the relaxation parameters. All
 fluctuations can be switched off by setting the temperature to zero.
 The deterministic part of the hydrodynamic interaction is then still active.
 
-If the LB thermostat is active, no other thermostatting mechanism is necessary. 
+If the LB thermostat is active, no other thermostatting mechanism is necessary.
 Please switch off any other thermostat before starting the LB
 thermostatting mechanism.
 

doc/bibliography.bib

@@ -320,7 +320,7 @@ The following tutorials are available:
 * :file:`electrokinetics`: Modelling electrokinetics together with hydrodynamic interactions.
 * :file:`constant_pH`: Modelling the titration of a weak acid using the constant pH method
 * :file:`widom_insertion`: Measuring the excess chemical potential of a salt solution using the Widom particle insertion method
-* :file:`mlip`: Atomistic simulations using machine-learned interatomic potentials and the MACE-MP-0 model :cite:`batatia25a`
+* :file:`mlip`: Atomistic simulations using machine-learned interatomic potentials and the MACE-MP-0 model :cite:`batatia22a,batatia25a`
 * :file:`mlip-water`: Modelling water using the TIP4P model :cite:`abascal05a` and machine-learning interatomic potentials with Apax :cite:`schafer25a`
 
 The executed notebooks with solutions and plots are periodically deployed
@@ -617,10 +617,13 @@ such as in ``1.1.5-dev`` or ``1.1.5.git8b603b12``, |es| doesn't offer a mechanis
 How to cite |es|
 ^^^^^^^^^^^^^^^^
 
-Please cite :cite:t:`weik19a` (BibTeX key ``weik19a`` in :file:`doc/bibliography.bib`)
+Please cite both :cite:t:`weeber24a` and :cite:t:`weik19a`
+(BibTeX keys ``weeber24a`` and ``weik19a`` in :file:`doc/bibliography.bib`)
 for |es| 4.0 and later, or both :cite:t:`arnold13a` and :cite:t:`limbach06a`
 (BibTeX keys ``arnold13a`` and ``limbach06a`` in :file:`doc/bibliography.bib`)
-for |es| 2.0 to 3.3. To find the version number, use the following command:
+for |es| 2.0 to 3.3.
+
+To find the version number, use the following command:
 
 .. code-block:: bash
 
@@ -634,11 +637,16 @@ publications, using the BibTeX entries indicated in this user guide.
 
 A complete citation would look like this:
 
-    Simulations were carried out with ESPResSo 4.2.2[24] using the ICC\*
+    Simulations were carried out with ESPResSo 4.2.2[23,24] using the ICC\*
     algorithm[25].
 
     | ____________
 
+    | [23] R. Weeber, J.-N. Grad, D. Beyer *et al.* ESPResSo, a versatile
+      open-source software package for simulating soft matter systems.
+      In M. Yáñez and R. J. Boyd, eds, *Comprehensive Computational Chemistry*,
+      vol. 3, pages 578--601. Elsevier, Oxford, 1st edition, 2024.
+      doi:\ `10.1016/B978-0-12-821978-2.00103-3 <https://doi.org/10.1016/B978-0-12-821978-2.00103-3>`_.
     | [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).
@@ -651,18 +659,13 @@ A complete citation would look like this:
 If you developed code for |es| and made it available in a publicly accessible repository,
 consider providing a permanent URL, such as a commit revision or a git tag:
 
-    The method was implemented for ESPResSo 4.2.2[24] and its source code is
+    The method was implemented for ESPResSo 4.2.2[23,24] and its source code is
     available online\ :superscript:`note 1`.
 
     | ____________
 
     | :superscript:`note 1` https://github.com/username/espresso/releases/tag/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>`_.
-
 The URL of a branch can be ambiguous, since extra commits can be pushed in the future,
 for example to fix a bug, thus creating confusion as to which commit was actually
 used to produce the paper data.