Merge branch 'python' of github.com:espressomd/espresso into dpd_bc

doc/sphinx/advanced_methods.rst

@@ -10,7 +10,7 @@ Advanced Methods
 Creating bonds when particles collide
 -------------------------------------
 
-Please cite :cite:`espresso2` when using dynamic bonding.
+Please cite :cite:`espresso2` when using dynamic bonding.
 
 With the help of this feature, bonds between particles can be created
 automatically during the simulation, every time two particles collide.
@@ -105,13 +105,13 @@ The following limitations currently apply for the collision detection:
 * The “bind at point of collision” approach cannot handle collisions
   between virtual sites
 
-.. _Catalytic Reactions:
+.. _Swimmer Reactions:
 
-Catalytic Reactions
--------------------
+Swimmer Reactions
+-----------------
 
 
-With the help of the feature ``CATALYTIC_REACTIONS``, one can define three particle types to act as reactant (e.g. :math:`\mathrm{H_2 O_2}`), catalyzer (e.g. platinum), and product (e.g. :math:`\mathrm{O_2}` and :math:`\mathrm{H_2 O}`). The current setup allows one to simulate active swimmers and their chemical propulsion.
+With the help of the feature ``SWIMMER_REACTIONS``, one can define three particle types to act as reactant (e.g. :math:`\mathrm{H_2 O_2}`), catalyzer (e.g. platinum), and product (e.g. :math:`\mathrm{O_2}` and :math:`\mathrm{H_2 O}`). The current setup allows one to simulate active swimmers and their chemical propulsion.
 
 For a Janus swimmer consisting of platinum on one hemisphere and gold on the other hemisphere, both surfaces catalytically induce a reaction. We assume an initial abundance of hydrogen peroxide and absence of products, so that back (recombination) reactions seldomly occur at the surface. A typical model for the propulsion of such a particle assumes
 
@@ -131,7 +131,7 @@ That is, catalytic surfaces induce a reactions that produce charged species by c
       B &\xrightarrow{C^{-}} A
     \end{aligned}
 
-where on the upper half of the catalyst :math:`C^{+}` a species :math:`A` is converted into :math:`B`, and on the lower half :math:`C^{-}` the opposite reaction takes place. Note that when :math:`A` and :math:`B` are charged, this reaction conserves charge, provided the rates are equal.
+where on the upper half of the catalyst :math:`C^{+}` a species :math:`A` is converted into :math:`B`, and on the lower half :math:`C^{-}` the opposite reaction takes place. Note that when :math:`A` and :math:`B` are charged, this reaction conserves charge, provided the rates are equal. Note that this feature uses the word catalyst in a meaning which cannot be brought into agreement with the definition of a catalyst. If the catalyst :math:`C^{+}` catalyzes (on average) the reaction, where :math:`A` is converted to :math:`B`, then it is impossible that a catalyst :math:`C^{-}` perfoms (on average) the reverse reaction. For the example with hydrogen peroxide this would mean that hydrogen peroxide is created spontaneously using a catalyst (under the same environment where another catalyst wants to split hydrogen peroxide). This is chemically impossible. What is meant to be modeled is that hydrogen peroxide is constantly flowing into the system from the bulk and therfore it is not depleted. This behaviour cannot be modeled using a catalyst (in the defined meaning of the word catalyst).
 
 In |es| the orientation of a catalyzer particle is used to define hemispheres; half spaces going through the particle's center. The reaction region is bounded by the *reaction range*: :math:`r`. Inside the reaction range, we react only reactant-product pairs. The particles in a pair are swapped from hemisphere to another with a rate prescribed by
 
@@ -183,7 +183,7 @@ can be used.::
 
 *  ``print r``  returns the current reaction parameters.
 
-In future versions of |es| the capabilities of the ``CATALYTIC_REACTIONS`` feature may be generalized
+In future versions of |es| the capabilities of the ``SWIMMER_REACTIONS`` feature may be generalized
 to handle multiple reactant, catalyzer, and product types, as well as
 more general reaction schemes. Other changes may involve merging the
 current implementation with the ``COLLISION_DETECTION`` feature.
@@ -316,8 +316,7 @@ University of Bayreuth if you plan to use this feature.
 This section describes an alternative way to include soft elastic
 objects somewhat different from the previous chapter. In the Immersed
 Boundary Method (IBM), soft particles are considered as an infinitely
-thin shell filled with liquid (see e.g.
- :cite:`Peskin2002,Crowl2010,KruegerThesis`). When the
+thin shell filled with liquid (see e.g. :cite:`Peskin2002,Crowl2010,KruegerThesis`). When the
 shell is deformed by an external flow it responds by elastic restoring
 forces which are transmitted into the fluid. In the present case, the
 inner and outer liquid are of the same type and are simulated using
@@ -397,7 +396,7 @@ ibm\_triel, ibm\_tribend and ibm\_volCons:
 Object-in-fluid
 ---------------
 
-Please cite  if you use the object-in-fluid implementation described
+Please cite  if you use the object-in-fluid implementation described
 below. For more details also see the documentation at
 http://cell-in-fluid.fri.uniza.sk/oif-documentation or contact the
 Cell-in-fluid Research Group at University of Žilina.
@@ -575,7 +574,7 @@ The following example shows an interaction.
      inter 106 oif_local_force 1.0 0.5 0.0 1.7 0.6 0.2 0.3 1.1 
 
 This command (“invisible” for the user who executes the
-``cript``/object\_in\_fluid.tcl  script) takes care of stretching,
+``cript``/object\_in\_fluid.tcl  script) takes care of stretching,
 bending and local area conservation all in one interaction with ID 106.
 Detailed description of the available types of interactions is presented
 in Section [sec:inter-bonded-oif].
@@ -587,8 +586,7 @@ Available commands
 
 In order to use the object-in-fluid (OIF) commands and work with
 immersed objects, the following features need to be compiled in:
-``ASS, \ \verb EXTERNAL_FORCES . We do not specifically require \verb LB, \ \verb LB_BOUNDARIES, \ \verb CONSTRAINTS, \ \verb SOFT_SPHERE, \ \verb ``\ EMBRANE\_COLLISION,
- ``IF_L``\ CAL\_FORCES,  ``IF_GL``\ BAL\_FORCES.  They are most likely
+``ASS, \ \verb EXTERNAL_FORCES . We do not specifically require \verb LB, \ \verb LB_BOUNDARIES, \ \verb CONSTRAINTS, \ \verb SOFT_SPHERE, \ \verb ``\ EMBRANE\_COLLISION, ``IF_L``\ CAL\_FORCES,  ``IF_GL``\ BAL\_FORCES.  They are most likely
 to be used (for objects immersed in fluid and interacting with
 boundaries and each other), but they are not necessary for the following
 commands. For up-to-date overview of available oif commands see the OIF

doc/sphinx/analysis.rst

@@ -747,7 +747,7 @@ The following observables are available:
      The particles are ordered according to the list of ids passed to the observable.
    - ParticleForces: Forces on the particles in the form
      :math:`f_{x1},\ f_{y1},\ f_{z1},\ f_{x2},\ f_{y2},\ f_{z2},\ \dots\ f_{xn},\ f_{yn},\ f_{zn}`.
-   - ParticleBodyVelocities: the particles' velocity in their respective body-fixed frames.
+   - ParticleBodyVelocities: the particles' velocities in their respective body-fixed frames (as per their orientation in space stored in their quaternions).
      :math:`v_{x1},\ v_{y1},\ v_{z1},\ v_{x2},\ v_{y2},\ v_{z2},\ \dots\ v_{xn},\ v_{yn},\ v_{zn}`.
      The particles are ordered according to the list of ids passed to the observable.
    - ParticleAngularVelocities: The particles' angular velocities in the space-fixed frame
@@ -780,6 +780,10 @@ The following observables are available:
 
    -  LBVelocityProfile
 
+- System-wide observables
+  StressTensor: Total stress tensor (see :ref:`stress tensor`)
+
+
 
 .. _Correlations:
 

doc/sphinx/installation.rst

@@ -378,14 +378,14 @@ General features
 
 -  ``METADYNAMICS``
 
--  ``CATALYTIC_REACTIONS`` Allows the user to define three particle types to be reactant,
+-  ``SWIMMER_REACTIONS`` Allows the user to define three particle types to be reactant,
    catalyzer, and product. Reactants get converted into products in the
    vicinity of a catalyst according to a used-defined reaction rate
    constant. It is also possible to set up a chemical equilibrium
    reaction between the reactants and products, with another rate
-   constant. 
+   constant. Be careful the model makes usage of the word catalyst. This usage of the word cannot be brought into agreement with the correct usage of the word catalyst.
    
-   .. seealso:: :ref:`Catalytic reactions`
+   .. seealso:: :ref:`Swimmer reactions`
 
 -  ``OVERLAPPED``
 
@@ -586,9 +586,9 @@ looking directly at the code.
 
 -  ``COMM_DEBUG`` Output from the asynchronous communication code.
 
--  ``EVENT_DEBUG`` Notifications for event calls, i. e. the ``on_...`` functions in
+-  ``EVENT_DEBUG`` Notifications for event calls, i. e. the ``on_...`` functions in
    ``initialize.c``. Useful if some module does not correctly respond to
-   changes of e. g. global variables.
+   changes of e. g. global variables.
 
 -  ``INTEG_DEBUG`` Integrator output.
 
@@ -728,7 +728,7 @@ compilation followed by a call of make:
     $ ccmake .. 
     $ make
 
-Fig. :ref:`ccmake-figure` shows the interactive ccmake UI.
+Fig. :ref:`ccmake-figure` shows the interactive ccmake UI.
 
 .. _ccmake-figure:
 

doc/sphinx/introduction.rst

@@ -58,7 +58,7 @@ Hand-in-hand with the extensibility and readability of the code comes the
 flexibility of the whole program. On the one hand, it is provided by the
 generalized functionality of its parts, avoiding highly specialized functions.
 An example can be the implementation of the Generic Lennard-Jones potential
-described in section :ref:`Generic Lennard-Jones interaction` where the user
+described in section :ref:`Generic Lennard-Jones interaction` where the user
 can change all available parameters. Where possible, default values are
 avoided, providing the user with the possibility of choice. |es| cannot be
 aware whether your particles are representing atoms or billard balls, so it
@@ -296,7 +296,7 @@ There is a number of tutorials that guide you through the different features of
 * `Raspberry electrophoresis              <https://github.com/espressomd/espresso/blob/python/doc/tutorials/05-raspberry_electrophoresis/05-raspberry_electrophoresis.pdf>`_
 * `Electrokinetics                        <https://github.com/espressomd/espresso/blob/python/doc/tutorials/07-electrokinetics/07-electrokinetics.pdf>`_
 * `Visualization                          <https://github.com/espressomd/espresso/blob/python/doc/tutorials/08-visualization/08-visualization.pdf>`_
-* `Catalytic reactions                    <https://github.com/espressomd/espresso/blob/python/doc/tutorials/09-catalytic_reactions/09-catalytic_reactions.pdf>`_
+* `Swimmer reactions                    <https://github.com/espressomd/espresso/blob/python/doc/tutorials/09-swimmer_reactions/09-swimmer_reactions.pdf>`_
 
 You can also find the tutorials and related scripts in the directory ``/doc/tutorials``.
 
@@ -594,16 +594,16 @@ report so to the developers.
 +--------------------------------+------------------------+------------------+------------+
 |                               **Miscellaneous**                                         |
 +--------------------------------+------------------------+------------------+------------+
-| Grand canonical feature        | Single                 | Single           | No         |
-+--------------------------------+------------------------+------------------+------------+
 | Electrokinetics                | Group                  | Group            | Yes        |
 +--------------------------------+------------------------+------------------+------------+
 | Collision Detection            | Group                  | Group            | Yes        |
 +--------------------------------+------------------------+------------------+------------+
-| Catalytic Reactions            | Single                 | Single           | Yes        |
+| Swimmer Reactions              | Single                 | Single           | Yes        |
 +--------------------------------+------------------------+------------------+------------+
 | Reaction Ensemble              | Group                  | Group            | Yes        |
 +--------------------------------+------------------------+------------------+------------+
+| Constant pH Method             | Group                  | Group            | Yes        |
++--------------------------------+------------------------+------------------+------------+
 | Object-in-fluid                | Group                  | Group            | Yes        |
 +--------------------------------+------------------------+------------------+------------+
 | DPD                            | Single                 | Good             | Yes        |

doc/sphinx/running.rst

@@ -54,27 +54,14 @@ enforce force recalculation.
 Run steepest descent minimization
 ---------------------------------
 
-In Python the ``minimize_energy`` functionality can be imported from
-:mod:`espressomd.minimize_energy` as class
-:class:`espressomd.minimize_energy.MinimizeEnergy`. Alternatively it
-is already part of the :class:`espressomd.system.System` class object
-and can be called from there (second variant)::
-
-    espressomd.minimize_energy.init(
-        f_max = <double>,
-        gamma = <double>,
-        max_steps = <double>,
-        max_displacement = <double>)
-    espressomd.minimize_energy.minimize()
-
-    system.minimize_energy.init(
-        f_max = <double>,
-        gamma = <double>,
-        max_steps = <double>,
-        max_displacement = <double>)
-    system.minimize_energy.minimize()
-
-This command runs a steepest descent energy minimization on the system.
+:func:`espressomd.espresso.thermostat.Thermostat.set_steepest_descent`
+
+
+
+This feature is used to propagate each particle by a small distance parallel to the force acting on it. 
+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 either a thermostat,
 Maggs electrostatics or Lattice-Boltzmann is activated. It runs a simple
 steepest descent algorithm:
@@ -90,8 +77,17 @@ Rotational degrees of freedom are treated similarly: each particle is
 rotated around an axis parallel to the torque acting on the particle.
 Please be aware of the fact that this needs not to converge to a local
 minimum in periodic boundary conditions. Translational and rotational
-coordinates that are fixed using the ``fix`` command or the
-``ROTATION_PER_PARTICLE`` feature are not altered.
+coordinates that are fixed using the ``fix`` and ``rotation`` attribute of particles are not altered.
+
+Usage example::
+
+        system.integrator.set_steepest_descent(
+            f_max=0, gamma=0.1, max_displacement=0.1)
+        system.integrator.run(20)
+        system.integrator.set_vv() # to switch back to velocity verlet
+
+
+
 
 .. _Multi-timestepping:
 

doc/tutorials/01-lennard_jones/scripts/lj_tutorial.py

@@ -33,7 +33,7 @@
 # System parameters
 #############################################################
 n_part  = 500
-density = 0.8442
+density = 0.2
 
 skin        = 0.4
 time_step   = 0.01 
@@ -105,10 +105,10 @@
 """.strip().format(warm_n_time, warm_steps, min_dist))
 
 i = 0
-act_min_dist = system.analysis.mindist()
+act_min_dist = system.analysis.min_dist()
 while i < warm_n_time and act_min_dist < min_dist :
     system.integrator.run(warm_steps)
-    act_min_dist = system.analysis.mindist()
+    act_min_dist = system.analysis.min_dist()
     print("run {} at time = {} (LJ cap= {} ) min dist = {}".strip().format(i, system.time, lj_cap, act_min_dist))
     i+=1
     lj_cap += 1.0

doc/tutorials/09-catalytic_reactions/09-catalytic_reactions.tex → doc/tutorials/09-swimmer_reactions/09-swimmer_reactions.tex

@@ -152,9 +152,11 @@ \section{Catalytic Reactions for Swimming in \es}
   \caption{\label{fig:nc}Illustration of the catalytic scheme. The cut-off range of $r$ around the catalyzer (green) is subdivided into two half-spaces. A reactant-product pair (blue and red connected by dotted line)is converted by swapping them if the pair is selected, and only if the product (red) resides in the upper half-space (silver background) and the corresponding reactant (blue) resides in the lower half-space (gold background). The catalytic reaction leads to a conversion of one reactant-product pair of particles in this example, denoted by the arrows annotated with $k_{\text{ct}}$. The second reactant-product pair within the reaction range is not viable for conversion. Additionally, particles in a pair may only undergo only one exhange per time step.}
 \end{figure}
 
+Note: Let the \textit{catalyst} $C^{+}$ (on average) convert more $A$ to $B$. Then the assumption of the model that the \textit{catalyst} $C^{-}$ would convert (on average) more $B$ to $A$ such that the number of $A$ and $B$ is constant in time is hair-raising! $C^{-}$ would have changed the position of chemical equilibrium which it can by the definition of a \textit{catalyst} cannot do. Let s say that $A$ is hydrogen peroxide and $B$ is water and oxygen. Then it is totally clear that a \textit{catalyst} cannot recreate (on average) hydrogen peroxide from water and oxygen under the same conditions where splitting hydrogen peroxide is energetically favourable. Therefore the usage of the word catalyst is wrong here. What the swimmer reactions aim to model is that new hydrogen peroxide (high energetic molecules) enter from the bulk to the vincinity of the active simmer and get split there. This cannot be modeled via a \textit{catalyst} which magically creates new high energetic molecules from low energetic moleucles (water and oxygen). This cannot happen repeatedly spontaneously. It is wrong to assume that a chemical reaction would recover high energetic molecules.
+
 \subsection{Usage in \es}
 
-Catalytic reactions can be enabled in \es\ by compiling in the eponymous feature \code{CATALYTIC_REACTIONS} and the \code{ROTATION} feature to provide the particles with an orientation vector. In \es\ the orientation of the particle is defined by a quaternion; this in turn defines a rotation matrix that acts on the particle's initial orientation (along the $z$-axis), which then defines the particles current orientation~\cite{UG,Limbach_06,Arnold_13}.
+Catalytic reactions can be enabled in \es\ by compiling in the eponymous feature \code{SWIMMER_REACTIONS} and the \code{ROTATION} feature to provide the particles with an orientation vector. In \es\ the orientation of the particle is defined by a quaternion; this in turn defines a rotation matrix that acts on the particle's initial orientation (along the $z$-axis), which then defines the particles current orientation~\cite{UG,Limbach_06,Arnold_13}.
 
 To setup the reaction there is the \es\ command \codees{Reaction}, which operates on particle types. The general syntax is
 \begin{espresso}
@@ -192,7 +194,7 @@ \section{Configuring \es\ for Catalytic Reactions}
 #define ROTATION
 #define ROTATIONAL_INERTIA
 #define LANGEVIN_PER_PARTICLE
-#define CATALYTIC_REACTIONS
+#define SWIMMER_REACTIONS
 #define LENNARD_JONES
 \end{lstlisting}
 Now you are ready to build \es.  You have to run \code{cmake} again to process the modified \code{myconfig.hpp}.

doc/tutorials/09-catalytic_reactions/SOLUTIONS/reaction.py → doc/tutorials/09-swimmer_reactions/SOLUTIONS/reaction.py

@@ -39,7 +39,7 @@
 assert_features(["ROTATION",
                  "ROTATIONAL_INERTIA",
                  "LANGEVIN_PER_PARTICLE",
-                 "CATALYTIC_REACTIONS",
+                 "SWIMMER_REACTIONS",
                  "LENNARD_JONES"])
 
 ################################################################################

doc/tutorials/CMakeLists.txt

@@ -27,7 +27,7 @@ add_subdirectory(05-raspberry_electrophoresis)
 add_subdirectory(06-active_matter)
 add_subdirectory(07-electrokinetics)
 add_subdirectory(08-visualization)
-add_subdirectory(09-catalytic_reactions)
+add_subdirectory(09-swimmer_reactions)
 
 
 ### here: add the appropriate tutorial target after DEPENDS

maintainer/configs/immersed_boundaries.hpp

@@ -14,7 +14,7 @@
 
 #define COLLISION_DETECTION
 #define LANGEVIN_PER_PARTICLE
-#define CATALYTIC_REACTIONS
+#define SWIMMER_REACTIONS
 
 #define NEMD
 #define NPT 

maintainer/configs/lees-edwards.hpp

@@ -14,7 +14,7 @@
 
 #define COLLISION_DETECTION
 #define LANGEVIN_PER_PARTICLE
-#define CATALYTIC_REACTIONS
+#define SWIMMER_REACTIONS
 
 #define NEMD
 #define NPT

maintainer/configs/maxset.hpp

@@ -15,7 +15,7 @@
 #define BOND_CONSTRAINT
 #define COLLISION_DETECTION
 #define LANGEVIN_PER_PARTICLE
-#define CATALYTIC_REACTIONS
+#define SWIMMER_REACTIONS
 
 #define NEMD
 #define NPT