From 02fcb756532512c341e0a41cf8e0fca5862dc471 Mon Sep 17 00:00:00 2001 From: Jonas Landsgesell Date: Wed, 20 Nov 2019 15:02:43 +0100 Subject: [PATCH 1/7] change indentation and chapter title --- doc/sphinx/advanced_methods.rst | 71 ++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index fb023eec324..c128ebcb00e 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -1689,10 +1689,15 @@ bonded particles. to damp dipole-dipole interactions on short distances. It is available in |es| as a non-bonded interaction. +.. _Monte Carlo Methods: + +Monte Carlo Methods +------------------- + .. _Reaction Ensemble: Reaction Ensemble ------------------ +~~~~~~~~~~~~~~~~~ .. 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. @@ -1805,7 +1810,7 @@ reaction. .. _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`. @@ -1855,6 +1860,38 @@ Wang-Landau reaction ensemble. Multiple reactions and multiple collective variables can be set. For a description of the available methods see :mod:`espressomd.reaction_ensemble`: + + +.. _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. + .. _Constant pH simulation using the Reaction Ensemble: Constant pH simulation @@ -1903,36 +1940,6 @@ a constant pH simulation, see the file in the testsuite directory. For a description of the available methods see :mod:`espressomd.reaction_ensemble`. -.. _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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 27510ff23ec962fd71f1d5c18112da749c84ea47 Mon Sep 17 00:00:00 2001 From: Jonas Landsgesell Date: Wed, 20 Nov 2019 15:10:24 +0100 Subject: [PATCH 2/7] add a word on invalidated particle ids --- doc/sphinx/advanced_methods.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index c128ebcb00e..ca02bffc9f0 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -1694,13 +1694,13 @@ bonded particles. 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. Please also note that the Monte Carlo methods may create and delete particles from the system. This process can invalidate particle ids. + .. _Reaction Ensemble: Reaction Ensemble ~~~~~~~~~~~~~~~~~ -.. 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. - 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: From 8b55aed5f3f17187827eef01a26f92e20db85975 Mon Sep 17 00:00:00 2001 From: Jonas Landsgesell Date: Wed, 20 Nov 2019 15:24:48 +0100 Subject: [PATCH 3/7] rm backward reaction --- doc/sphinx/advanced_methods.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index ca02bffc9f0..080a3f18c2b 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -1992,10 +1992,9 @@ 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: From af4bc2396cf1aca223da575fd105538445330814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Wed, 20 Nov 2019 17:35:42 +0100 Subject: [PATCH 4/7] Fix grammar and capitalization --- doc/sphinx/advanced_methods.rst | 60 +++++++++---------- doc/sphinx/electrostatics.rst | 18 +++--- doc/sphinx/installation.rst | 2 +- doc/sphinx/io.rst | 2 +- doc/sphinx/lb.rst | 2 +- doc/sphinx/magnetostatics.rst | 18 +++--- .../01-lennard_jones/01-lennard_jones.ipynb | 2 +- .../11-ferrofluid/11-ferrofluid_part1.ipynb | 2 +- .../11-ferrofluid/11-ferrofluid_part2.ipynb | 2 +- .../11-ferrofluid/11-ferrofluid_part3.ipynb | 2 +- .../12-constant_pH/12-constant_pH.ipynb | 6 +- 11 files changed, 57 insertions(+), 59 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index 080a3f18c2b..c78e855d22c 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -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], ...) @@ -1694,7 +1694,7 @@ bonded particles. 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. Please also note that the Monte Carlo methods may create and delete particles from the system. This process can invalidate particle ids. +.. 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. Please also note that Monte Carlo methods may create and delete particles from the system. This process can invalidate particle ids. .. _Reaction Ensemble: @@ -1702,8 +1702,8 @@ Reaction Ensemble ~~~~~~~~~~~~~~~~~ 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: +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 `_ @@ -1793,7 +1793,7 @@ The parameter :math:`\Gamma` proportional to the reaction constant. It is define where :math:`\left/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 @@ -1807,16 +1807,16 @@ 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: +.. _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:: @@ -1847,8 +1847,7 @@ An example script can be found here: * `Wang-Landau reaction ensemble `__ 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 @@ -1860,17 +1859,16 @@ Wang-Landau reaction ensemble. Multiple reactions and multiple collective variables can be set. For a description of the available methods see :mod:`espressomd.reaction_ensemble`: - - .. _Grand canonical ensemble simulation using the Reaction Ensemble: -Grand canonical ensemble simulation +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 +reaction can be set to zero. Such a reaction creates particles *ex nihilo*, and +is equivalent to exchanging particles with a reservoir. Then the simulation +in the reaction ensemble becomes equivalent to the grand canonical simulation. +Formally, this can be expressed by the reaction .. math:: @@ -1878,17 +1876,17 @@ grandcanonical simulation. Formally, this can be expressed by the reaction 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. +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 +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 +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 +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. @@ -1912,7 +1910,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 `_ @@ -1943,7 +1941,7 @@ For a description of the available methods see :mod:`espressomd.reaction_ensembl 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:: @@ -1964,9 +1962,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.: @@ -1976,7 +1974,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: @@ -1994,9 +1992,9 @@ For this one has to provide the following reaction to the Widom method: product_coefficients=[1,1], default_charges={1: 0}) 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 removed. 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 `_ diff --git a/doc/sphinx/electrostatics.rst b/doc/sphinx/electrostatics.rst index 55f39dd2cd7..0e1c2a86d70 100644 --- a/doc/sphinx/electrostatics.rst +++ b/doc/sphinx/electrostatics.rst @@ -455,24 +455,24 @@ one. For details on the MMM family of algorithms, refer to appendix :ref:`The MMM family of algorithms`. -.. _Scafacos Electrostatics: +.. _ScaFaCoS Electrostatics: -Scafacos Electrostatics +ScaFaCoS Electrostatics ----------------------- -Espresso can use the electrostatics methods from the SCAFACOS *Scalable +|es| can use the electrostatics methods from the ScaFaCoS *Scalable fast Coulomb solvers* library. The specific methods available depend on the compile-time options of the library, and can be queried using :meth:`espressomd.scafacos.available_methods` -To use SCAFACOS, create an instance of :class:`espressomd.electrostatics.Scafacos` and add it to the list of active actors. Three parameters have to be specified: +To use ScaFaCoS, create an instance of :class:`espressomd.electrostatics.Scafacos` and add it to the list of active actors. Three parameters have to be specified: -* ``method_name``: name of the SCAFACOS method being used. +* ``method_name``: name of the ScaFaCoS method being used. * ``method_params``: dictionary containing the method-specific parameters * ``prefactor``: Coulomb prefactor as defined in :eq:`coulomb_prefactor`. -The method-specific parameters are described in the SCAFACOS manual. -Additionally, methods supporting tuning have the parameter ``tolerance_field`` which sets the desired root mean square accuracy for the electric field +The method-specific parameters are described in the ScaFaCoS manual. +In addition, methods supporting tuning have a parameter ``tolerance_field`` which sets the desired root mean square accuracy for the electric field. -To use the, e.g., ``ewald`` solver from SCAFACOS as electrostatics solver for your system, set its +To use the, e.g., ``ewald`` solver from ScaFaCoS as electrostatics solver for your system, set its cutoff to :math:`1.5` and tune the other parameters for an accuracy of :math:`10^{-3}`, use:: @@ -483,5 +483,5 @@ cutoff to :math:`1.5` and tune the other parameters for an accuracy of For details of the various methods and their parameters please refer to -the SCAFACOS manual. To use this feature, SCAFACOS has to be built as a shared library. SCAFACOS can be used only once, either for Coulomb or for dipolar interactions. +the ScaFaCoS manual. To use this feature, ScaFaCoS has to be built as a shared library. ScaFaCoS can be used only once, either for Coulomb or for dipolar interactions. diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst index b37f55cc01b..e99d4c02c44 100644 --- a/doc/sphinx/installation.rst +++ b/doc/sphinx/installation.rst @@ -240,7 +240,7 @@ lines below (optional steps which modify the build process are commented out): #cp myconfig-default.hpp myconfig.hpp # use the default configuration as template #nano myconfig.hpp # edit to add/remove features as desired cmake .. - #ccmake . // in order to add/remove features like SCAFACOS or CUDA + #ccmake . // in order to add/remove features like ScaFaCoS or CUDA make This will build |es| with a default feature set, namely diff --git a/doc/sphinx/io.rst b/doc/sphinx/io.rst index c077db5409c..a9f04ef40a7 100644 --- a/doc/sphinx/io.rst +++ b/doc/sphinx/io.rst @@ -98,7 +98,7 @@ Be aware of the following limitations: * Checkpointing makes use of the ``pickle`` python package. Objects will only be restored as far as they support pickling. This is the case for Python's basic data types, ``numpy`` arrays and many other objects. Still, pickling support cannot be taken for granted. - * Pickling support of the Espresso system instance and contained objects such as bonded and non-bonded interactions and electrostatics methods. However, there are many more combinations of active interactions and algorithms then can be tested. + * Pickling support of the :class:`espressomd.system.System` instance and contained objects such as bonded and non-bonded interactions and electrostatics methods. However, there are many more combinations of active interactions and algorithms then can be tested. * The active actors, i.e., the content of ``system.actors``, are checkpointed. For lattice-Boltzmann fluids, this only includes the parameters such as the lattice constant (``agrid``). The actual flow field has to be saved separately with the lattice-Boltzmann specific methods :meth:`espressomd.lb.HydrodynamicInteraction.save_checkpoint` diff --git a/doc/sphinx/lb.rst b/doc/sphinx/lb.rst index f0b10f18041..c059a2a355a 100644 --- a/doc/sphinx/lb.rst +++ b/doc/sphinx/lb.rst @@ -259,7 +259,7 @@ Choosing between the GPU and CPU implementations .. note:: Feature ``CUDA`` required -Espresso contains an implementation of the LBM for NVIDIA +|es| contains an implementation of the LBM for NVIDIA GPUs using the CUDA framework. On CUDA-supporting machines this can be activated by compiling with the feature ``CUDA``. Within the Python script, the :class:`~espressomd.lb.LBFluid` object can be substituted with the :class:`~espressomd.lb.LBFluidGPU` object to switch from CPU based to GPU based execution. For further diff --git a/doc/sphinx/magnetostatics.rst b/doc/sphinx/magnetostatics.rst index f14b2fcc09e..5c423d20def 100644 --- a/doc/sphinx/magnetostatics.rst +++ b/doc/sphinx/magnetostatics.rst @@ -163,28 +163,28 @@ To use the method, create an instance of :class:`~espressomd.magnetostatics.Dipo bh = DipolarBarnesHutGpu(prefactor=pf_dds_gpu, epssq=200.0, itolsq=8.0) system.actors.add(bh) -.. _Scafacos Magnetostatics: +.. _ScaFaCoS Magnetostatics: -Scafacos Magnetostatics +ScaFaCoS Magnetostatics ----------------------- -Espresso can use the methods from the Scafacos *Scalable fast Coulomb solvers* +|es| can use the methods from the ScaFaCoS *Scalable fast Coulomb solvers* library for dipoles, if the methods support dipolar calculations. The feature ``SCAFACOS_DIPOLES`` has to be added to :file:`myconfig.hpp` to activate this feature. Dipolar calculations are only included in the ``dipolar`` branch of -the Scafacos code. +the ScaFaCoS code. -To use SCAFACOS, create an instance of :class:`~espressomd.magnetostatics.Scafacos` +To use ScaFaCoS, create an instance of :class:`~espressomd.magnetostatics.Scafacos` and add it to the list of active actors. Three parameters have to be specified: -* ``method_name``: name of the SCAFACOS method being used. +* ``method_name``: name of the ScaFaCoS method being used. * ``method_params``: dictionary containing the method-specific parameters * ``prefactor`` -The method-specific parameters are described in the SCAFACOS manual. -Additionally, methods supporting tuning have the parameter ``tolerance_field`` which sets the desired root mean square accuracy for the electric field +The method-specific parameters are described in the ScaFaCoS manual. +In addition, methods supporting tuning have a parameter ``tolerance_field`` which sets the desired root mean square accuracy for the electric field For details of the various methods and their parameters please refer to -the SCAFACOS manual. To use this feature, SCAFACOS has to be built as a shared library. SCAFACOS can be used only once, either for Coulomb or for dipolar interactions. +the ScaFaCoS manual. To use this feature, ScaFaCoS has to be built as a shared library. ScaFaCoS can be used only once, either for Coulomb or for dipolar interactions. diff --git a/doc/tutorials/01-lennard_jones/01-lennard_jones.ipynb b/doc/tutorials/01-lennard_jones/01-lennard_jones.ipynb index 93d6da2c1ee..2e469523ce5 100644 --- a/doc/tutorials/01-lennard_jones/01-lennard_jones.ipynb +++ b/doc/tutorials/01-lennard_jones/01-lennard_jones.ipynb @@ -86,7 +86,7 @@ "source": [ "## Units\n", "\n", - "Novice users must understand that Espresso has no fixed unit system. The unit \n", + "Novice users must understand that ESPResSo has no fixed unit system. The unit \n", "system is set by the user. Conventionally, reduced units are employed, in other \n", "words LJ units." ] diff --git a/doc/tutorials/11-ferrofluid/11-ferrofluid_part1.ipynb b/doc/tutorials/11-ferrofluid/11-ferrofluid_part1.ipynb index 21218c5f320..ad6ed8ac2af 100644 --- a/doc/tutorials/11-ferrofluid/11-ferrofluid_part1.ipynb +++ b/doc/tutorials/11-ferrofluid/11-ferrofluid_part1.ipynb @@ -221,7 +221,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We start with checking for the presence of Espresso features and importing all necessary packages." + "We start with checking for the presence of ESPResSo features and importing all necessary packages." ] }, { diff --git a/doc/tutorials/11-ferrofluid/11-ferrofluid_part2.ipynb b/doc/tutorials/11-ferrofluid/11-ferrofluid_part2.ipynb index 1c7d1f03d62..0b7622ae642 100644 --- a/doc/tutorials/11-ferrofluid/11-ferrofluid_part2.ipynb +++ b/doc/tutorials/11-ferrofluid/11-ferrofluid_part2.ipynb @@ -41,7 +41,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We import all necessary packages and check for the required Espresso features" + "We import all necessary packages and check for the required ESPResSo features" ] }, { diff --git a/doc/tutorials/11-ferrofluid/11-ferrofluid_part3.ipynb b/doc/tutorials/11-ferrofluid/11-ferrofluid_part3.ipynb index 6846c1514e5..f0794e64e93 100644 --- a/doc/tutorials/11-ferrofluid/11-ferrofluid_part3.ipynb +++ b/doc/tutorials/11-ferrofluid/11-ferrofluid_part3.ipynb @@ -112,7 +112,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "First we import all necessary packages and check for the required Espresso features" + "First we import all necessary packages and check for the required ESPResSo features" ] }, { diff --git a/doc/tutorials/12-constant_pH/12-constant_pH.ipynb b/doc/tutorials/12-constant_pH/12-constant_pH.ipynb index 740ec4fa84d..96667cb798f 100644 --- a/doc/tutorials/12-constant_pH/12-constant_pH.ipynb +++ b/doc/tutorials/12-constant_pH/12-constant_pH.ipynb @@ -71,7 +71,7 @@ "\n", "The constant pH method [Reed1992](https://doi.org/10.1063/1.462145) is designed to simulate an acid-base ionization reaction at a given pH. It assumes that the simulated system is coupled to an implicit reservoir of $\\mathrm{H^+}$ ions but exchange of ions with this reservoir is not explicitly simulated. Therefore, the concentration of ions in the simulation box is not equal to the concentration of $\\mathrm{H^+}$ ions at the chosen pH. This may lead to artifacts when simulating interacting systems, especially at high of low pH values. Discussion of these artifacts is beyond the scope of this tutorial (see e.g. [Landsgesell2019](https://doi.org/10.1039/C8SM02085J) for further details).\n", "\n", - "In Espresso, the forward step of the ionization reaction (from left to right) is implemented by \n", + "In ESPResSo, the forward step of the ionization reaction (from left to right) is implemented by \n", "changing the chemical identity (particle type) of a randomly selected $\\mathrm{HA}$ particle to $\\mathrm{A}^-$, and inserting another particle that represents a neutralizing counterion. The neutralizing counterion is not necessarily an $\\mathrm{H^+}$ ion. Therefore, we give it a generic name $\\mathrm{B^+}$. In the reverse direction (from right to left), the chemical identity (particle type) of a randomly selected $\\mathrm{A}^{-}$ is changed to $\\mathrm{HA}$, and a randomly selected $\\mathrm{B}^+$ is deleted from the simulation box. The probability of proposing the forward reaction step is $P_\\text{prop}=N_\\mathrm{HA}/N_0$, and probability of proposing the reverse step is $P_\\text{prop}=N_\\mathrm{A}/N_0$. The trial move is accepted with the acceptance probability\n", "\n", "$$ P_{\\mathrm{acc}} = \\operatorname{min}\\left(1, \\exp(-\\beta \\Delta E_\\mathrm{pot} \\pm \\ln(10) \\cdot (\\mathrm{pH - p}K_A) ) \\right)$$\n", @@ -187,7 +187,7 @@ "pHmax = pK+offset # highest pH value to be used\n", "pHs = np.linspace(pHmin, pHmax, num_pHs) # list of pH values\n", "\n", - "# Initialize the Espresso system\n", + "# Initialize the ESPResSo system\n", "##############################################\n", "system = espressomd.System(box_l=[Box_L_in_sigma] * 3)\n", "system.time_step = 0.01\n", @@ -295,7 +295,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The next step is to define the reaction system. The order in which species are written in the lists of reactants and products is very important for Espresso. When a reaction move is performed, identity of the first species in the list of reactants is changed to the first species in the list of products, the second reactant species is changed to the second product species, and so on. If the reactant list has more species than the product list, then excess reactant species are deleted from the system. If the product list has more species than the reactant list, then product the excess product species are created and randomly placed inside the simulation box. This convention is especially important if some of the species belong to a chain-like molecule, and cannot be placed at an arbitrary position.\n", + "The next step is to define the reaction system. The order in which species are written in the lists of reactants and products is very important for ESPResSo. When a reaction move is performed, identity of the first species in the list of reactants is changed to the first species in the list of products, the second reactant species is changed to the second product species, and so on. If the reactant list has more species than the product list, then excess reactant species are deleted from the system. If the product list has more species than the reactant list, then product the excess product species are created and randomly placed inside the simulation box. This convention is especially important if some of the species belong to a chain-like molecule, and cannot be placed at an arbitrary position.\n", "\n", "In the example below, the order of reactants and products ensures that identity of $\\mathrm{HA}$ is changed to $\\mathrm{A^{-}}$ and vice versa, while $\\mathrm{H^{+}}$ is inserted/deleted in the reaction move. Reversing the order of products in our reaction (i.e. from `product_types=[TYPE_B, TYPE_A]` to `product_types=[TYPE_A, TYPE_B]`), would result in a reaction move, where the identity HA would be changed to $\\mathrm{H^{+}}$, while $\\mathrm{A^{-}}$ would be inserted/deleted at a random position in the box. We also assign charges to each type because the charge will play an important role later, in simulations with electrostatic interactions." ] From a2ff8068a69f1e2a7567be3ac1df9c3eb256934d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Wed, 20 Nov 2019 17:36:58 +0100 Subject: [PATCH 5/7] Update docs on Reaction Ensemble Move links to scripts and classes after the algorithm descriptions. Provide a link to the class instead of a link to the module. Remove outdated comments. Discuss particle ordering after a reaction step. --- doc/sphinx/advanced_methods.rst | 49 +++++++++++++++------------------ 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index c78e855d22c..1859971e398 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -1694,19 +1694,13 @@ bonded particles. 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. Please also note that Monte Carlo methods may create and delete particles from the system. This process can invalidate particle ids. +.. 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 and cause ``system.part`` to return particles slices with a different particle ordering after each reaction step. .. _Reaction Ensemble: Reaction Ensemble ~~~~~~~~~~~~~~~~~ -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 / constant pH ensemble `_ - The reaction ensemble :cite:`smith94c,turner2008simulation` allows to simulate chemical reactions which can be represented by the general equation: @@ -1807,6 +1801,14 @@ 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. +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 `_ + +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 @@ -1840,24 +1842,21 @@ 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 `__ - Combination of the Reaction Ensemble with the Wang-Landau algorithm :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 `__ + +For a description of the available methods, see :class:`espressomd.reaction_ensemble.ReactionEnsemble`. .. _Grand canonical ensemble simulation using the Reaction Ensemble: @@ -1866,8 +1865,8 @@ 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. Then the simulation -in the reaction ensemble becomes equivalent to the grand canonical simulation. +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:: @@ -1895,10 +1894,7 @@ reaction ensemble transition probabilities. 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 @@ -1933,9 +1929,7 @@ 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`. Widom Insertion (for homogeneous systems) @@ -1998,4 +1992,5 @@ An example script which demonstrates the usage for measuring the pair excess che * `Widom Insertion `_ +For a description of the available methods, see :class:`espressomd.reaction_ensemble.WidomInsertion`. From 5c1f2e85471ab19d97ccc6fcfa156d6737bcb10d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Wed, 13 Nov 2019 11:33:00 +0100 Subject: [PATCH 6/7] Add 4.1.1 release notes --- NEWS | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/NEWS b/NEWS index 7d2ca453635..88aa923adac 100644 --- a/NEWS +++ b/NEWS @@ -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 ============ From 5ed58849a43b5643aa064f515b820293df4fb56e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 22 Nov 2019 15:56:19 +0100 Subject: [PATCH 7/7] Apply code review feedback --- doc/sphinx/advanced_methods.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index 1859971e398..75536c02699 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -1694,7 +1694,7 @@ bonded particles. 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 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 and cause ``system.part`` to return particles slices with a different particle ordering after each reaction step. +.. 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. .. _Reaction Ensemble: