Rapid prototyping of Monte Carlo methods

Provide an alternative implementation of SingleReaction,
ReactionAlgorithm and ConstantpHEnsemble in pure Python
for rapid prototyping of new Monte Carlo methods.

Co-authored-by: Pablo Miguel Blanco Andrés <[email protected]>

doc/sphinx/reaction_methods.rst

@@ -379,4 +379,41 @@ If the exclusion radius of one particle type is not defined, the value
 of the parameter provided in ``exclusion_range`` is used by default.
 If the value in ``exclusion_radius_per_type`` is equal to 0,
 then the exclusion range of that particle type with any other particle is 0.
-For more detail, see :class:`espressomd.cell_system.ExclusionRadius`.
+For more detail, see :class:`~espressomd.reaction_methods.ExclusionRadius`.
+
+.. _Writing new Monte Carlo methods:
+
+Writing new Monte Carlo methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most of the logic for reaction methods is implemented at the Python level.
+The C++ core is only used for performance-relevant operations on particles.
+Hence, one can prototype new reaction methods with relative ease.
+For example, the acceptance probability for a Monte Carlo trial move
+is exposed in :meth:`ReactionAlgorithm.calculate_acceptance_probability()
+<espressomd.reaction_methods.ReactionAlgorithm.calculate_acceptance_probability>`.
+Reaction method classes override this function with their custom expression
+for the acceptance probability.
+
+Alternatively, the sample script :file:`samples/monte_carlo.py` provides
+a re-implementation of the core functionality of reaction methods in Python,
+with a focus on the :ref:`constant pH <Constant pH>` and
+:ref:`reaction ensemble <Reaction Ensemble>` methods.
+More specifically, the :class:`~espressomd.reaction_methods.SingleReaction`,
+:class:`~espressomd.reaction_methods.ReactionAlgorithm`,
+:class:`~espressomd.reaction_methods.ReactionEnsemble`, and
+:class:`~espressomd.reaction_methods.ConstantpHEnsemble`
+classes are rewritten in Python.
+
+The goal of this sample is to assist in the rapid prototyping of new Monte Carlo
+methods. In particular, the sampling and move generation schemes are expressed
+in Python, and can be leveraged by users without C++ programming experience.
+The sample is designed to run with the :ref:`kernprof` profiler attached:
+
+.. code-block:: bash
+
+    pypresso --kernprof monte_carlo.py --mode=core
+    pypresso --kernprof monte_carlo.py --mode=python
+
+These Python implementations are roughly four times slower
+than their corresponding core implementations.