Skip to content

Commit

Permalink
Merge espressomd#3330 espressomd#3332
Browse files Browse the repository at this point in the history 
3330: Structure mc documentation r=jngrad a=jonaslandsgesell

Fixes espressomd#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 <[email protected]>
Co-authored-by: Jean-Noël Grad <[email protected]>
  • Loading branch information
@bors @jonaslandsgesell @jngrad
3 people authored Nov 22, 2019
3 parents d588ea8 + 5ed5884 + 5c1f2e8 commit 9415194
Show file tree
Hide file tree
Showing 12 changed files with 207 additions and 105 deletions.
103 changes: 103 additions & 0 deletions NEWS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,109 @@
= ESPRESSO NEWS =
=================

ESPResSo 4.1.1
==============

This release provides a number of corrections for Espresso 4.1.
We recommend that this release be used for all production simulations.
The interface is mostly unchanged between Espresso 4.1 and 4.1.1; the
two exceptions are limited to these experimental features:

* `Integrator.set_isotropic_npt()`: input value `direction=[0,0,0]`
now throws an error instead of being silently changed to `[1,1,1]`

* `ParticleHandle.swimming`: deprecated value `'rotational_friction'`
is now disabled

These changes are unlikely to affect production simulations.
However, some bugs were discovered which can affect simulation results.
Below, please find the list of changes. The numbers in brackets refer
to ticket numbers on https://github.com/espressomd/espresso

General corrections and improvements:

* Restore checkpointing mechanism for the steepest descent and NPT
integrators, LB and NPT thermostats (#3245)

* Increase the minimum MPI version to 3.0; OpenMPI versions 1.6.5 and
lower are no longer supported (#3236)

* Fix `Integrator.set_isotropic_npt()`: remove the silent conversion of
the incorrect input parameter `direction=[0,0,0]` to `[1,1,1]` in the
core; the function now throws an exception for fixed-volume boxes;
this change is unlikely to break pypresso scripts since not providing
a value to `direction` or providing `[1,1,1]` were the two standard
ways to set up a box with all directions allowed to rescale (#3253)

* Fix `Integrator.set_vv()`: this function failed to set the velocity
Verlet integrator if the NPT integrator was active; this is now
resolved (#3274)

* Fix the random segmentation fault triggered by the removal of a
particle with a bond or a virtual site relationship to another
particle (#3288)

* Fix `system.part.writevtk()`: the function now writes down all
particles when using `types="all"` (#3290)

* Disable the deprecated and broken ENGINE shear torque calculation
feature; the feature will be completely removed from the core in
the upcoming 4.2 release (#3277)

* Fix unit conversion for the LB fluid viscosity (#3287)

Documentation and tutorials corrections and improvements:

* Add more detailed installation instructions for ESPResSo and its
Python dependencies on MacOS X (#3236)

* Add links to Dockerfiles providing installation instructions for
ESPResSo and its Python dependencies on CentOS 7, Fedora 30, Debian 10
and OpenSUSE Leap 15.1 (#3244)

* Add instructions to read PDB files with `MDAnalysis`, which is one of
the recommended tools to read/write molecular dynamics topologies and
trajectories in ESPResSo; the PdbParser feature will be removed in the
upcoming 4.2 release (#3257)

* Add a new tutorial on the constant pH method; the reaction ensemble
tutorial will be removed in the upcoming 4.2 release (#3184)

Build system and platform-related corrections and improvements:

* Fix a PYTHONPATH error when ESPResSo is built in a directory
containing whitespace characters (#3238)

* Fix several issues with the command `make install` that lead to import
errors in Python (incorrect runtime path, missing shared objects,
name collision for submodule `cluster_analysis`) and deprecate the
`make install DESTDIR=/path/to/espresso` command in favor of the
standard `cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/espresso` command
(#3228), install espressomd module in a platform-dependent python
path, typically `lib{,64}/python3.X/{dist,site}-packages` (#3258)

* Fix an issue in mpiio that triggered an assertion in systems with no
bonds when ESPResSo is built with stdlibc++ range checking enabled
(#3234)

* Fix the pypresso script to correctly parse filepaths containing
whitespaces passed after a pypresso flag, such as `--gdb`, and make
conditional statements cross-platform (#3292)

Improved testing:

* Test checkpointing of integrators and thermostats (#3245)

* Fix and improve `check_cmake_install` test (#3228, #3258) and add a
new CI job to test an installed version of ESPResSo (#3228)

* Test engine LB (#3277)

* Add more LB tests (#2748)




Espresso 4.1
============

Expand Down
153 changes: 76 additions & 77 deletions doc/sphinx/advanced_methods.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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], ...)
Expand Down Expand Up @@ -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.
An Example script can be found here:
.. _Reaction Ensemble:

* `Reaction ensemble / constant pH ensemble <https://github.com/espressomd/espresso/blob/python/samples/reaction_ensemble.py>`_
Reaction Ensemble
~~~~~~~~~~~~~~~~~

The reaction ensemble :cite:`smith94c,turner2008simulation` allows to simulate
chemical reactions which can be represented by the general equation:
Expand Down Expand Up @@ -1788,7 +1787,7 @@ The parameter :math:`\Gamma` proportional to the reaction constant. It is define
where :math:`\left<N_i\right>/V` is the average number density of particles of type :math:`i`.
Note that the dimension of :math:`\Gamma` is :math:`V^{\bar\nu}`, therefore its
units must be consistent with the units in which Espresso measures the box volume,
units must be consistent with the units in which |es| measures the box volume,
i.e. :math:`\sigma^3`.

It is often convenient, and in some cases even necessary, that some particles
Expand All @@ -1802,16 +1801,24 @@ coefficients allow for it. Corresponding means having the same position (index)
the python lists of reactants and products which are used to set up the
reaction.

.. _Converting tabulated reaction constants to internal units in Espresso:
Multiple reactions can be added to the same instance of the reaction ensemble.

An example script can be found here:

* `Reaction ensemble / constant pH ensemble <https://github.com/espressomd/espresso/blob/python/samples/reaction_ensemble.py>`_

For a description of the available methods, see :class:`espressomd.reaction_ensemble.ReactionEnsemble`.

.. _Converting tabulated reaction constants to internal units in ESPResSo:

Converting tabulated reaction constants to internal units in Espresso
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Converting tabulated reaction constants to internal units in ESPResSo
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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::
Expand All @@ -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.
An example script can be found here:

* `Wang-Landau reaction ensemble <https://github.com/espressomd/espresso/blob/python/samples/wang_landau_reaction_ensemble.py>`__

Combination of the Reaction Ensemble with the Wang-Landau algorithm
:cite:`wang01a`
allows for enhanced sampling of the reacting system, and
:cite:`wang01a`. Allows for enhanced sampling of the reacting system
and for the determination of the density of states with respect
to the reaction coordinate or with respect to some other collective
variable :cite:`landsgesell17a`. Here the 1/t Wang-Landau
algorithm :cite:`belardinelli07a` is implemented since it
does not suffer from systematic errors.
Additionally to the above
commands for the reaction ensemble use the following commands for the
Wang-Landau reaction ensemble.
does not suffer from systematic errors.

Multiple reactions and multiple collective variables can be set.
For a description of the available methods see :mod:`espressomd.reaction_ensemble`:

An example script can be found here:

* `Wang-Landau reaction ensemble <https://github.com/espressomd/espresso/blob/python/samples/wang_landau_reaction_ensemble.py>`__

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\neq 1`, 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
Expand All @@ -1875,7 +1906,7 @@ As before in the Reaction Ensemble one can define multiple reactions (e.g. for a
cpH.add_reaction(gamma=1/(10**-14/K_diss), reactant_types=[3], reactant_coefficients=[1], product_types=[0, 2], product_coefficients=[1, 1], default_charges={0:0, 2:1, 3:1} )
An Example script can be found here:
An example script can be found here:

* `Reaction ensemble / constant pH ensemble <https://github.com/espressomd/espresso/blob/python/samples/reaction_ensemble.py>`_

Expand All @@ -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\neq 1`, 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::
Expand All @@ -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.:
Expand All @@ -1969,7 +1968,7 @@ The implementation can also deal with the simultaneous insertion of multiple par
\mu^\mathrm{ex, pair}&:=\Delta F^\mathrm{ex, pair}:= F^\mathrm{ex}(N_1+1, N_2+1,V,T)-F^\mathrm{ex}(N_1, N_2 ,V,T)\\
&=-kT \ln \left(\frac{1}{V^2} \int_V \int_V d^3r_{N_1+1} d^3 r_{N_2+1} \langle \exp(-\beta \Delta E_\mathrm{pot}) \rangle_{N_1, N_2} \right)
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:
Expand All @@ -1985,13 +1984,13 @@ For this one has to provide the following reaction to the Widom method:
widom.add_reaction(reactant_types=[type_3],
reactant_coefficients=[1], product_types=[type_1, type_2],
product_coefficients=[1,1], default_charges={1: 0})
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:

* `Widom Insertion <https://github.com/espressomd/espresso/blob/python/samples/widom_insertion.py>`_

For a description of the available methods, see :class:`espressomd.reaction_ensemble.WidomInsertion`.

Loading

0 comments on commit 9415194

Please sign in to comment.