Merge #2886

2886: Swimmer reactions r=KaiSzuttor a=fweik

Fixes #2498.

This was broken in multiple ways (see #2498) and seems abandoned.
Also It uses an interface (access to verlet lists and cells) that we do not
plan to provide in the future.

Description of changes:
 - Remove SWIMMER_REACTSION feature and functionality


Co-authored-by: Florian Weik <[email protected]>
Co-authored-by: Kai Szuttor <[email protected]>

doc/sphinx/advanced_methods.rst

@@ -119,109 +119,6 @@ The following limitations currently apply for the collision detection:
 * The ``"bind at point of collision"`` approach cannot handle collisions
   between virtual sites
 
-.. _Swimmer Reactions:
-
-Swimmer Reactions
------------------
-
-
-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 seldom occur at the surface. A typical model for the propulsion of such a particle assumes
-
-.. math::
-
-    \begin{aligned}
-      \mathrm{H_2 O_2} &\xrightarrow{\text{Pt}} \mathrm{2 H^{+} + 2 e^{-} + O_2} \\
-      \mathrm{2 H^{+} + 2 e^{-} + H_2 O_2} &\xrightarrow{\text{Au}} \mathrm{2 H_2 O}
-    \end{aligned}
-
-That is, catalytic surfaces induce a reactions that produce charged species by consuming hydrogen peroxide. It is the change in distribution of charged species that leads to motion of the swimmer, a process referred to as self-electrophoresis. A minimal model for this would be
-
-.. math::
-
-    \begin{aligned}
-      A &\xrightarrow{C^{+}} B \\
-      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. 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^{-}` performs (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 therefore 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
-
-.. math::
-
-    P_{\text{move}} = 1 - \mathrm{e}^{-k_{\mathrm{ct}}\,\Delta t} ,
-
-with the reaction rate :math:`k_{\mathrm{ct}}` and the simulation time step :math:`\Delta t`. A pair may be swapped only once per MD time step, to avoid a no-net-effect situation. That is, we allow an exchange move only when the following conditions are met:
-
-1. Both partners of the reactant-product pair have to reside within the reaction range.
-2. The product has to reside in the upper half-space of the reaction range.
-3. The reactant has to reside in the lower half-space of the reaction range.
-
-Self-propulsion is achieved by imposing an interaction asymmetry between the partners of a swapped pair. That is, the heterogeneous distribution of chemical species induced by the swapping leads to a net force on the particle, counter balanced by friction.
-
-To set up the system for catalytic reactions the class :class:`espressomd.swimmer_reaction.Reaction`
-can be used. ::
-
-    from espressomd.swimmer_reaction import Reaction
-
-    system = espressomd.System()
-
-    # setting up particles etc
-
-    r = Reaction(product_type=1, reactant_type=2, catalyzer_type=0,
-                 ct_range=2, ct_rate=0.2, eq_rate=0)
-    r.start()
-    r.stop()
-
-    print r
-
-* the first invocation of ``Reaction``, in the above example,  defines a
-  reaction with particles of type number 2 as reactant, type 0 as catalyzer and
-  type 1 as product [#1]_. The catalytic reaction rate constant is given by :math:`\mathrm{ct\_rate}`
-  [#2]_ and to override the default rate constant for the equilibrium reaction
-  ( = 0), one can specify it by as ``eq_rata``.  By default each reactant particle is checked
-  against each catalyst particle (``react_once=False``). However, when creating
-  smooth surfaces using many catalyst particles, it can be desirable to let the
-  reaction rate be independent of the surface density of these particles. That
-  is, each particle has a likelihood of reacting in the vicinity of the surface
-  (distance is less than :math:`r`) as specified by the rate constant, i.e.,
-  *not* according to :math:`P_{\text{cvt}} = 1 - \exp \left( - n k\Delta t
-  \right)`, with :math:`n` the number of local catalysts. To accomplish this,
-  each reactant is considered only once each time step by using the option
-  ``react_once=True`` . The reaction command is set up such that the different
-  properties may be influenced individually.
-
-*  ``r.stop()`` disables the reaction. Note that at the moment, there can
-   only be one reaction in the simulation.
-
-*  ``print r``  returns the current reaction parameters.
-
-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.
-
-.. rubric:: Footnotes
-
-.. [#1]
-   Only one type of particle can be assigned to each of these three
-   reaction species and no particle type may be assigned to multiple
-   species. That is, currently does not support particles of type 1 and
-   2 both to be reactants, nor can particles of type 1 be a reactant as
-   well as a catalyst. Moreover, only one of these reactions can be
-   implemented in a single Tcl script. If, for instance, there is a
-   reaction involving particle types 1, 2, and 4, there cannot be a
-   second reaction involving particles of type 5, 6, and 8. It is
-   however possible to modify the reaction properties for a given set of
-   types during the simulation.
-
-.. [#2]
-   Currently only strictly positive values of the catalytic conversion
-   rate constant are allowed. Setting the value to zero is equivalent to
-   ``r.stop()``.
-
 ..
 .. _Lees-Edwards boundary conditions:
 

doc/sphinx/installation.rst

@@ -236,7 +236,7 @@ command:
 
     ./pypresso <SCRIPT>
 
-where ``<SCRIPT>`` is a ``python`` script which has to
+where is ``<SCRIPT>`` is a ``python`` script which has to
 be written by the user. You can find some examples in the :file:`samples`
 folder of the source code directory. If you want to run in parallel, you should
 have compiled with *Open MPI*, and need to tell MPI to run in parallel. The actual
@@ -429,14 +429,6 @@ General features
 
 -  ``METADYNAMICS``
 
--  ``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. 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:`Swimmer reactions`
 
 -  ``COLLISION_DETECTION`` Allows particles to be bound on collision.
 

doc/sphinx/introduction.rst

@@ -297,7 +297,6 @@ Currently, the following tutorials are available:
 * :file:`06-active_matter`: Modelling of self-propelling particles.
 * :file:`07-electrokinetics`: Modelling electrokinetics together with hydrodynamic interactions.
 * :file:`08-visualization`: Using the online visualizers of |es|.
-* :file:`09-swimmer_reactions`: Further modelling of self-propelling particles.
 * :file:`10-reaction_ensemble`: Modelling chemical reactions by means of the reaction ensemble.
 
 .. _Sample scripts: