3330: Structure mc documentation r=jngrad a=jonaslandsgesell
Fixes#3309
* correctly indent the Reaction Ensemble subsections in the Sphinx docs
* add a note explaining particle ids may be invalidated when a chemical reaction is added
3332: Add 4.1.1 release notes in master r=fweik a=jngrad
Co-authored-by: Jonas Landsgesell <jonaslandsgesell@users.noreply.github.com>
Co-authored-by: Jean-Noël Grad <jgrad@icp.uni-stuttgart.de>
Loading branch information
3 people
committed
Nov 22, 2019
Verified
This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.
@@ -1428,7 +1428,7 @@ it is possible to choose parameters for which the LB is more stable. The species
ek.add_species(species)
One can also add the species during the initialization step of the
One can also add the species during the initialization step of the
:class:`espressomd.electrokinetics.Electrokinetics` by defining the list variable ``species``::
ek = espressomd.electrokinetics.Electrokinetics(species=[species], ...)
@@ -1689,18 +1689,17 @@ bonded particles.
to damp dipole-dipole interactions on short distances. It is available in |es|
as a non-bonded interaction.
.. _Reaction Ensemble:
.. _Monte Carlo Methods:
Reaction Ensemble
-----------------
Monte Carlo Methods
-------------------
.. note:: The whole Reaction Ensemble module uses Monte Carlo moves which require potential energies. Therefore the Reaction Ensemble requires support for energy calculations for all interactions which are used in the simulation.
.. note:: The whole Reaction Ensemble module uses Monte Carlo moves which require potential energies. Therefore the Reaction Ensemble requires support for energy calculations for all active interactions in the simulation. Please also note that Monte Carlo methods may create and delete particles from the system. This process can invalidate particle ids, in which case the particles are no longer numbered contiguously. Particle slices returned by ``system.part`` are still iterable, but the indices no longer match the particle ids.
For a description of the available methods see :mod:`espressomd.reaction_ensemble`.
Multiple reactions can be added to the same instance of the reaction ensemble.
The implementation in Espresso requires that the dimension of :math:`\Gamma`
is consistent with the internal unit of volume, :math:`\sigma^3`.
The tabulated values of equilibrium constants for reactions in solution, :math:`K_c`, typically use
The implementation in |es| requires that the dimension of :math:`\Gamma`
is consistent with the internal unit of volume, :math:`\sigma^3`. The tabulated
values of equilibrium constants for reactions in solution, :math:`K_c`, typically use
:math:`c^{\ominus} = 1\,\mathrm{moldm^{-3}}` as the reference concentration,
and have the dimension of :math:`(c^{\ominus})^{\bar\nu}`. To be used with Espresso, the
and have the dimension of :math:`(c^{\ominus})^{\bar\nu}`. To be used with |es|, the
value of :math:`K_c` has to be converted as
.. math::
@@ -1835,35 +1842,59 @@ Consider using the python module pint for unit conversion.
Wang-Landau Reaction Ensemble
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. .. note:: Requires support for energy calculations for all used interactions since it uses Monte-Carlo moves which use energies in one way or the other.
For a description of the available methods, see :class:`espressomd.reaction_ensemble.ReactionEnsemble`.
.. _Grand canonical ensemble simulation using the Reaction Ensemble:
Grand canonical ensemble simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As a special case, all stoichiometric coefficients on one side of the chemical
reaction can be set to zero. Such a reaction creates particles *ex nihilo*, and
is equivalent to exchanging particles with a reservoir. This type of simulation
in the reaction ensemble is equivalent to the grand canonical simulation.
Formally, this can be expressed by the reaction
.. math::
\mathrm{\emptyset\rightleftharpoons\ \nu_A A } \,,
where, if :math:`\nu_A=1`, the reaction constant :math:`\Gamma` defines the chemical potential of species A.
However, if :math:`\nu_A\neq1`, the statistics of the reaction ensemble becomes
equivalent to the grand canonical only in the limit of large average number of species A in the box.
If the reaction contains more than one product, then the reaction constant
:math:`\Gamma` defines only the sum of their chemical potentials but not the
chemical potential of each product alone.
Since the Reaction Ensemble acceptance transition probability can be
derived from the grand canonical acceptance transition probability, we
can use the reaction ensemble to implement grand canonical simulation
moves. This is done by adding reactions that only have reactants (for the
deletion of particles) or only have products (for the creation of
particles). There exists a one-to-one mapping of the expressions in the
grand canonical transition probabilities and the expressions in the
reaction ensemble transition probabilities.
.. _Constant pH simulation using the Reaction Ensemble:
Constant pH simulation
~~~~~~~~~~~~~~~~~~~~~~
.. .. note:: Requires support for energy calculations for all used interactions since it uses Monte-Carlo moves which use energies.
As before in the Reaction Ensemble one can define multiple reactions (e.g. for an ampholytic system which contains an acid and a base) in one ConstantpHEnsemble instance:
As before in the Reaction Ensemble one can define multiple reactions (e.g. for an ampholytic system which contains an acid and a base) in one :class:`~espressomd.reaction_ensemble.ConstantpHEnsemble` instance:
.. code-block:: python
@@ -1875,7 +1906,7 @@ As before in the Reaction Ensemble one can define multiple reactions (e.g. for a
@@ -1898,45 +1929,13 @@ constant :math:`K_c` for the following reaction:
\mathrm{HA \rightleftharpoons\ H^+ + A^- } \,,
For an example of how to setup
a constant pH simulation, see the file in the testsuite directory.
For a description of the available methods see :mod:`espressomd.reaction_ensemble`.
For a description of the available methods, see :class:`espressomd.reaction_ensemble.ConstantpHEnsemble`.
.. _Grand canonical ensemble simulation using the Reaction Ensemble:
Grand canonical ensemble simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As a special case, all stoichiometric coefficients on one side of the chemical
reaction can be set to zero. Such reaction creates particles *ex nihilo*, and
is equivalent to exchange with a reservoir. Then the simulation in the reaction ensemble becomes equivalent with the
grandcanonical simulation. Formally, this can be expressed by the reaction
.. math::
\mathrm{\emptyset\rightleftharpoons\ \nu_A A } \,,
where, if :math:`\nu_A=1`, the reaction constant :math:`\Gamma` defines the chemical potential of species A.
However, if :math:`\nu_A\neq1`, the statistics of the reaction ensemble becomes
equivalent to the grandcanonical only in the limit of large average number of species A in the box.
If the reaction contains more than one product, then the reaction constant
:math:`\Gamma` defines only the sum of their chemical potentials but not the
chemical potential of each product alone.
Since the Reaction Ensemble acceptance transition probability can be
derived from the grand canonical acceptance transition probability we
can use the reaction ensemble to implement grand canonical simulation
moves. This is done via adding reactions that only have reactants (for the
deletion of particles) or only have products (for the creation of
particles). There exists a one to one mapping of the expressions in the
grand canonical transition probabilities and the expressions in the
reaction ensemble transition probabilities.
Widom Insertion (for homogeneous systems)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Widom insertion method measures the change in excess free energy, i.e. the excess chemical potential due to the insertion of a new particle, or a group of particles:
The Widom insertion method measures the change in excess free energy, i.e. the excess chemical potential due to the insertion of a new particle, or a group of particles:
.. math::
@@ -1957,9 +1956,9 @@ For this one has to provide the following reaction to the Widom method:
The call of ``add_reaction`` define the insertion :math:`\mathrm{\emptyset\to type_B}` (which is the 0th defined reaction).
Multiple reactions for the insertions of different types can be added to the same ``WidomInsertion`` instance.
Measuring the excess chemical potential using the insertion method is done via calling ``widom.measure_excess_chemical_potential(0)``.
If another particle isertion is defined, then the excess chemical potential for this insertion can be measured by calling ``widom.measure_excess_chemical_potential(1)``.
Multiple reactions for the insertions of different types can be added to the same ``WidomInsertion`` instance.
Measuring the excess chemical potential using the insertion method is done via calling ``widom.measure_excess_chemical_potential(0)``.
If another particle isertion is defined, then the excess chemical potential for this insertion can be measured by calling ``widom.measure_excess_chemical_potential(1)``.
Be aware that the implemented method only works for the canonical ensemble. If the numbers of particles fluctuate (i.e. in a semi grand canonical simulation) one has to adapt the formulas from which the excess chemical potential is calculated! This is not implemented. Also in a isobaric-isothermal simulation (NPT) the corresponding formulas for the excess chemical potentials need to be adapted. This is not implemented.
The implementation can also deal with the simultaneous insertion of multiple particles and can therefore measure the change of excess free energy of multiple particles like e.g.:
@@ -1969,7 +1968,7 @@ The implementation can also deal with the simultaneous insertion of multiple par
Note that the measurement involves three averages: the canonical ensemble average :math:`\langle\cdot\rangle_{N_1, N_2}` and the two averages over the position of particles :math:`N_1+1` and :math:`N_2+1`.
Note that the measurement involves three averages: the canonical ensemble average :math:`\langle\cdot\rangle_{N_1, N_2}` and the two averages over the position of particles :math:`N_1+1` and :math:`N_2+1`.
Since the averages over the position of the inserted particles are obtained via brute force sampling of the insertion positions it can be beneficial to have multiple insertion tries on the same configuration of the other particles.
One can measure the change in excess free energy due to the simultaneous insertions of particles of type 1 and 2 and the simultaneous removal of a particle of type 3:
@@ -1985,13 +1984,13 @@ For this one has to provide the following reaction to the Widom method:
widom.measure_excess_chemical_potential(0) #for the forward reaction
widom.measure_excess_chemical_potential(1) #for the backward reaction
widom.measure_excess_chemical_potential(0)
Be aware that in the current implementation for MC moves which add and remove particles the insertion of the new particle always takes place at the position where the last particle was remove. Be sure that this is the behaviour you want to have. Otherwise implement a new function ``WidomInsertion::make_reaction_attempt`` in the core.
Be aware that in the current implementation, for MC moves which add and remove particles, the insertion of the new particle always takes place at the position where the last particle was removed. Be sure that this is the behaviour you want to have. Otherwise implement a new function ``WidomInsertion::make_reaction_attempt`` in the core.
An example script which demonstrates the useage for measuring the pair excess chemical potential for inserting an ion pair into a salt solution can be found here:
An example script which demonstrates the usage for measuring the pair excess chemical potential for inserting an ion pair into a salt solution can be found here:
0 comments on commit
9415194