Merge branch 'python' into tune_skin

doc/doxygen/Doxyfile.in

@@ -28,7 +28,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = $(PACKAGE)
+PROJECT_NAME           =
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -40,7 +40,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Extensible Simulation Package for Soft Matter Research"
+PROJECT_BRIEF          = "Extensible Simulation Package for Research on Soft Matter Systems"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not
@@ -647,7 +647,8 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @CMAKE_SOURCE_DIR@/src
+INPUT                  = @CMAKE_SOURCE_DIR@/src \
+                         @CMAKE_SOURCE_DIR@/doc/doxygen/main.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -685,7 +686,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = $(SRCDIR)/src/core/myconfig-default.hpp
+EXCLUDE                = @CMAKE_SOURCE_DIR@/src/config/myconfig-default.hpp
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -713,7 +714,7 @@ EXCLUDE_SYMBOLS        = detail
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           = $(SRCDIR)
+EXAMPLE_PATH           =
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp

doc/doxygen/gen_doxyconfig.py

@@ -19,7 +19,6 @@
 #
 # This script generates the file doxy-features
 #
-from __future__ import print_function
 import inspect
 import sys
 import os

doc/doxygen/main.dox

@@ -19,55 +19,28 @@
   along with this program.  If not, see <http://www.gnu.org/licenses/>. 
 
 */
-/** \mainpage ESPResSo Code documentation
+/**
+
+@mainpage ESPResSo code documentation
 
 This is the code documentation of ESPResSo. It is primarily intended
-for people that want to extend or just understand the C-code of
+for people that want to extend or just understand the C++ core of
 ESPResSo.
 
-If you just have obtained a release of ESPResSo, and you are looking
-for documentation on how to use ESPResSo, you might first want to have
-a look at the User's Guide, which is to be found in \c doc/ug/ug.pdf
-in the ESPResSo release.
+If you just have obtained a release of ESPResSo, and you are looking for
+documentation on how to use the software, you might first want to have a look
+at the User's Guide, which is available at <http://espressomd.org/html/doc/>.
 
 If you want to start developing code for ESPResSo, you might first
-want to have a look at the Developer's Guide (DG). You can find the
-most recent version of the DG at the <a
-href="http://espressomd.org/html/doc/dg.html">ESPResSo
-homepage</a>. The DG explains
+want to have a look at the Developer's Guide on the GitHub wiki at
+<https://github.com/espressomd/espresso/wiki>. The wiki explains:
 
 - how to obtain the development code
 - what tools are required to develop the code
 - how to get your modifications into the main code repository
 - how the documentation is updated
 
-\section entry Entry points to the C-code
-
-The script is interpreted on one node, the master node, whereas the
-other nodes wait for the master node to issue specific actions,
-i. e. a client-server model is utilized. More details can be found in
-\ref communication.hpp "communication.hpp". During the actual integration,
-however, the communication is done synchronously.  For more details
-see \ref integrate.cpp "integrate.cpp".
-
-\section Copyright and License of the Code Documentation
-Copyright (C) 2010-2018 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.
-
-  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/>. 
+If you need to develop new features in the core, you can find detailed
+instructions in the [Related Pages](pages.html).
 
 */

doc/sphinx/installation.rst

@@ -491,7 +491,7 @@ Interaction features
 The following switches turn on various short ranged interactions (see
 section :ref:`Isotropic non-bonded interactions`):
 
--  ``TABULATED`` Enable support for user-defined interactions.
+-  ``TABULATED`` Enable support for user-defined non-bonded interaction potentials.
 
 -  ``LENNARD_JONES`` Enable the Lennard-Jones potential.
 
@@ -521,25 +521,21 @@ section :ref:`Isotropic non-bonded interactions`):
 -  ``BMHTF_NACL`` Enable the Born-Meyer-Huggins-Tosi-Fumi potential, which can be used
    to model salt melts.
 
-Some of the short range interactions have additional features:
-
--  ``LJ_WARN_WHEN_CLOSE`` This adds an additional check to the Lennard-Jones potentials that
-   prints a warning if particles come too close so that the simulation
-   becomes unphysical.
-
-If you want to use bond-angle potentials (see section :ref:`Bond-angle interactions`), you need the
-following features.
-
--  ``BOND_ANGLE``
-
--  ``LJGEN_SOFTCORE``
-
 -  ``GAUSSIAN``
 
 -  ``HAT``
 
 -  ``UMBRELLA`` (experimental)
 
+Some of the short-range interactions have additional features:
+
+-  ``LJ_WARN_WHEN_CLOSE`` This adds an additional check to the Lennard-Jones
+   potentials that prints a warning if particles come so close to each other
+   that the simulation becomes unphysical.
+
+-  ``LJGEN_SOFTCORE`` This modifies the generic Lennard-Jones potential
+   (``LENNARD_JONES_GENERIC``) with tunable parameters.
+
 
 .. _Debug messages:
 

doc/sphinx/inter_bonded.rst

@@ -227,11 +227,6 @@ is named :math:`vtol`.
 Tabulated bond interactions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
-
-    Requires ``TABULATED`` feature.
-
-
 A tabulated bond can be instantiated via
 :class:`espressomd.interactions.Tabulated`::
 

doc/sphinx/inter_non-bonded.rst

@@ -559,60 +559,80 @@ DPD interaction
     Feature ``DPD`` required.
 
 This is a special interaction that is to be used in conjunction with the
-`Dissipative Particle Dynamics (DPD)` thermostat, for a general description
-of the algorithm see there. The parameters can be set via::
+:ref:`Dissipative Particle Dynamics (DPD)` thermostat.
+The parameters can be set via::
 
     system.non_bonded_inter[type1, type2].dpd.set_params(**kwargs)
 
-This command defines a velocity-dependent interaction
-between particles of the types ``type1`` and ``type2``. For a description of the input arguments
-see :class:`espressomd.interactions.DPDInteraction`. The interaction
-only has an effect if the DPD thermostat activated, and acts according to the
-temperature of the thermostat.
+This command defines an interaction between particles of the types ``type1`` and ``type2``
+that contains velocity-dependent friction and noise according 
+to a temperature set by :py:meth:`espressomd.thermostat.Thermostat.set_dpd()`. 
+The parameters for the interaction are
 
-The interaction consists of a dissipative force :math:`\vec{F}_{ij}^{D}` and
-a random force :math:`\vec{F}_{ij}^R`, and is decomposed into a component
-parallel and perpendicular to the distance vector of the particle pair :math:`\vec{F}_{ij}`.
-The parameters for the two parts can be chosen independently.
-The force contributions of the parallel part are
+* ``gamma``
+* ``weight_function``
+* ``r_cut``
+* ``trans_gamma``
+* ``trans_weight_function``
+* ``trans_r_cut``
 
-.. math:: \vec{F}_{ij}^{D} = -\zeta w^D (r_{ij}) (\hat{r}_{ij} \cdot \vec{v}_{ij}) \hat{r}_{ij}
+which will be explained below. The interaction
+only has an effect if the DPD thermostat is activated.
 
-for the dissipative force and
+The interaction consists of a friction force :math:`\vec{F}_{ij}^{D}` and
+a random force :math:`\vec{F}_{ij}^R` added to the other interactions
+between particles :math:`i` and :math:`j`. It is decomposed into a component
+parallel and perpendicular to the distance vector :math:`\vec{r}_{ij}` of the particle pair .
+The friction force contributions of the parallel part are
 
-.. math:: \vec{F}_{ij}^R = \sigma w^R (r_{ij}) \Theta_{ij} \hat{r}_{ij}
+.. math:: \vec{F}_{ij}^{D} = -\gamma_\parallel w_\parallel (r_{ij}) (\hat{r}_{ij} \cdot \vec{v}_{ij}) \hat{r}_{ij}
 
-for the random force. Here :math:`w^D` and :math:`w^R` are weight functions that
-can be specified via the weight_function parameter of the interaction. The dissipative
-and random weight function are related by the dissipation-fluctuation theorem:
+for the dissipative force and
 
-.. math:: (\sigma w^R (r_{ij}))^2=\zeta w^D (r_{ij}) \text{k}_\text{B} T
+.. math:: \vec{F}_{ij}^R = \sqrt{2 k_B T \gamma_\parallel w_\parallel (r_{ij}) }  \eta_{ij}(t) \hat{r}_{ij}
 
-The possible values for weight_function are 0 and 1, corresponding to the
-order of :math:`w^D`:
+for the random force. This introduces the friction coefficient :math:`\gamma_\parallel` (parameter ``gamma``) and the weight function
+:math:`w_\parallel`. The thermal energy :math:`k_B T` is not set by the interaction, 
+but by the DPD thermostat (:py:meth:`espressomd.thermostat.Thermostat.set_dpd()`) 
+to be equal for all particles. The weight function can be specified via the ``weight_function`` switch. 
+The possible values for ``weight_function`` are 0 and 1, corresponding to the
+order of :math:`w_\parallel`:
 
 .. math::
 
-   w^D (r_{ij}) = ( w^R (r_{ij})) ^2 =
-      \left\{
+   w_\parallel (r_{ij}) =  \left\{
    \begin{array}{clcr}
                 1                      & , \; \text{weight_function} = 0 \\
-                {( 1 - \frac{r_{ij}}{r_c}} )^2 & , \; \text{weight_function} = 1
+                {( 1 - \frac{r_{ij}}{r^\text{cut}_\parallel}} )^2 & , \; \text{weight_function} = 1
       \end{array}
       \right.
+      
+Both weight functions are set to zero for :math:`r_{ij}>r^\text{cut}_\parallel` (parameter ``r_cut``).
 
-For the perpendicular part, the dissipative force is calculated by
+The random force has the properties
 
-.. math:: \vec{F}_{ij}^{D} = -\zeta w^D (r_{ij}) (I-\hat{r}_{ij}\otimes\hat{r}_{ij}) \cdot \vec{v}_{ij}
+.. math:: <\eta_{ij}(t)> = 0 , <\eta_{ij}^\alpha(t)\eta_{kl}^\beta(t')> = \delta_{\alpha\beta} \delta_{ik}\delta_{jl}\delta(t-t')
 
-The random force by
+and is numerically discretized to a random number :math:`\overline{\eta}` for each spatial 
+component for each particle pair drawn from a uniform distribution
+with properties
 
-.. math:: \vec{F}_{ij}^R = \sigma w^R (r_{ij}) (I-\hat{r}_{ij}\otimes\hat{r}_{ij}) \cdot \vec{\Theta}_{ij}
+.. math:: <\overline{\eta}> = 0 , <\overline{\eta}\overline{\eta}> = 1/dt
+
+For the perpendicular part, the dissipative and random force are calculated analogously
 
-The parameters define the strength of the friction and the cutoff in the
-same way as above. Note: This interaction does *not* conserve angular
+.. math:: \vec{F}_{ij}^{D} = -\gamma_\bot w^D (r_{ij}) (I-\hat{r}_{ij}\otimes\hat{r}_{ij}) \cdot \vec{v}_{ij}
+.. math:: \vec{F}_{ij}^R = \sqrt{2 k_B T \gamma_\bot w_\bot (r_{ij})} (I-\hat{r}_{ij}\otimes\hat{r}_{ij}) \cdot \vec{\eta}_{ij}
+
+and introduce the second set of parameters prefixed with ``trans_``.
+For :math:`w_\bot (r_{ij})` (parameter ``trans_weight_function``)
+the same options are available as for :math:`w_\parallel (r_{ij})`.
+
+Note: This interaction does *not* conserve angular
 momentum.
 
+A more detailed description of the interaction can be found in :cite:`soddeman03a`.
+
 .. _Thole correction:
 
 Thole correction

doc/sphinx/introduction.rst

@@ -548,7 +548,7 @@ report so to the developers.
 +--------------------------------+------------------------+------------------+------------+
 | Langevin Thermostat            | Core                   | Core             | Yes        |
 +--------------------------------+------------------------+------------------+------------+
-| Isotropic NPT                  | None                   | Single           | Yes        |
+| Isotropic NPT                  | Experimental           | None             | Yes        |
 +--------------------------------+------------------------+------------------+------------+
 | Quaternion Integrator          | Core                   | Good             | Yes        |
 +--------------------------------+------------------------+------------------+------------+
@@ -594,6 +594,8 @@ report so to the developers.
 +--------------------------------+------------------------+------------------+------------+
 | VTK output                     | Group                  | Group            | No         |
 +--------------------------------+------------------------+------------------+------------+
+| Checkpointing                  | Experimental           | Experimental     | Yes        |
++--------------------------------+------------------------+------------------+------------+
 |                              **Visualization**                                          |
 +--------------------------------+------------------------+------------------+------------+
 | Online visualisation (Mayavi)  | Good                   | Good             | No         |