This module has been included in the OpenPathSampling core. Its tests can
be run by installing pytest and OPS (with commit 8e767872, which will be
part of release 1.0 and later), and running the command ``py.test --pyargs
openpathsampling``.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``py.test`` from the
.. root directory of the repository.
Examples
________
This module is used in the OPS `alanine dipeptide MSTIS example <https://github.com/openpathsampling/openpathsampling/blob/master/examples/alanine_dipeptide_mstis/AD_mstis_1_setup.ipynb>`_, during the creation of initial trajectories.
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
This module has been merged into OpenPathSampling. It is composed of the
This is the core module for the particle insertion suite of codes
Languages
C, Python 2.7, LAMMPS Scripting language
Licence
MIT -however note that LAMMPS is now changing from GPL to LGPL so when used togetherwith LAMMPS LGPL applies
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
Application Documentation
See `PIcore repository <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIcore>`_
Relevant Training Material
None
.. contents:: :local:
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of the Module
_____________________
This software module computes the change in free energy associated with the insertion or deletion of Lennard Jones particles in dilute or dense
conditions in a variety of Thermodynamic Ensembles, where statistical sampling through molecular dynamics is performed under `LAMMPS <https://lammps.sandia.gov/>`_ but
will be extended to other molecular dynamics engines at a later date. Lennard-Jones type interactions are the key source of
difficulty associated with particle insertion or deletion, which is why this module is a core module, as other interactions including
Coulombic and bond, angle and dihedral interactions will be added in a second module. It differs from the main community approach used to
date to compute such changes as it does not use soft-core potentials. Its key advantages over soft-core potentials are: (a) electrostatic interactions
can in principle be performed simultaneously
with particle insertion (this and other functionalities will be added in a new module); and, (b) essentially exact long-range dispersive interactions
using `dispersion Particle Mesh Ewald <https://doi.org/10.1063/1.4764089>`_ (PMME) or EWALD if desired can be selected at runtime by the user.
Background Information
______________________
Particle insertion can be used to compute the free energy associated with hydration/drying, the insertion of cavities in fluids/crystals,
changes in salt levels, changes in solvent mixtures, and alchemical changes such as the mutation of amino-acids. in crystals. It can also
be used to compute the free energy of solvent mixtures and the addition of salts, which is used in the purification processing
industrially, for instance in the purification of pharmaceutical active ingredients. Particle insertion can in principle also be
used to compute the free energy associated with changes in the pH, that is the proton transfer from a titratable site to the bulk,
for example in water.
Our approach consists of rescaling the effective size of inserted atoms through a parameter :math:`\lambda` so that all interactions between
nserted atoms and interactions between inserted atoms and atoms already present in the system are zero when :math:`\lambda = 0`, creating at most an
integrable singularity which we can safely handle. In the context of Lennard-Jones type pair potentials,
our approach at a mathematical level is similar to Simonson, who investigated the mathematical conditions required to `avoid the
singularity of insertion <https://doi.org/10.1080/00268979300102371>`_. It turns out that a non-linear dependence of the
interaction on :math: '\\lambda' between inserted
atoms and those already present is required (i.e. a simple linear dependence on :math: '\lambda' necessarily introduces a singularity).
This module and upcoming modules include computing the free energy changes associated with the following applications
(a) hydration and drying;
(b) the addition of multiple molecules into a condenses environment;
(c) residue mutation and alchemy;
(d) constant pH simulations, this also will also exploit modules created in E-CAM work package 3 (quantum dynamics); and,
(e) free energy changes in chemical potentials associated with changes in solvent mixtures.
General Formulation
___________________
Consider a system consisting of :math:`N+M` degrees of freedom and the Hamiltonian
and the mixing rule for Van der Waals diameters and binding energy between different atoms uses the geometric mean.
The dependence of :math:`\sigma` on :math:`\lambda` has the consequence that the mean
:math:`\sigma` between a pair of inserted atoms scales as :math:`\lambda`, but scales as :math:`\sqrt{\lambda}` when one atom in the pair is
inserted and the other is already present. These choices of perturbations guarantees that the particle insertion and deletion catastrophes are avoided.
Algorithms
__________
At the core of the PI core module there are four functions/codes. The first written in python generates the interpolation points which are
the zero's of suitably transformed Chebyshev functions.
The second code written ln LAMMPS scripting language performs the simulation in user-defined ensembles at the selected
interpolation values of :math:'lambda', at a user-specified frequency, computing two-point central difference estimates of derivatives of the
potential energy needed for thermodynamic integration, computing the energy
functions for all values of :math:'lambda' in the context of MBAR. The user also specifies the locations of the inserted particles.
The user also specifies whether
Particle Mesh Ewald or EWALD should be used for dispersive interactions.
The third code written in python takes the output data from LAMMPS, prepares it so that free energy differences in the
selected ensemble can be computed using MBAR provided by the pymbar suite of python codes of the Chodera group.
The fourth code, also written in python take the LAMMPS output and performs the thermodynamic integration.
.. image:: ./flowchart1.png
Source Code
___________
All files can be found in the ``PIcore`` subdirectory of the `particle_insertion git repository <https://gitlab.e-cam2020.eu/mackernan/particle_insertion>`_.
Compilation and Linking
_______________________
See `PIcore README <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIcore/README.rst>`_ for full details.
Scaling and Performance
________________________
As the module uses LAMMPS, the performance and scaling of this module should essentially be the same, provided data for thermodynamic integration and
MBAR are not generated too often, as is demonstated below. In the case of thermodynamic integration, this is due to the central difference approximation of derivatives, and in the case
of MBAR, it is due to the fact that many virtual moves are made which can be extremely costly if the number of interpolating points is large. Also, when using
PMME, the initial setup cost is computationally expensive, and should, therefore, be done as infrequently as possible. A future module in preparation will
circumvent the use of central difference approximations of derivatives. The scaling performance of PI-CORE was tested on Jureca multi node.
The results for weak scaling (where the number of core and the system size are doubled from 4 to 768 core) are as follows.
Weak Scaling:
================== ===========
Number of MPI Core timesteps/s
================== ===========
4 1664.793
8 1534.013
16 1458.936
24 1454.075
48 1350.257
96 1301.325
192 1263.402
384 1212.539
768 1108.306
================== ===========
and for the strong scaling (where the number of core are doubled from 4 to 384 but the system size is fixed equal to 768 times the original system
size considered for one core/processor for weak scaling) Strong Scaling:
This is the core module for the particle insertion suite of codes
Languages
C, Python 2.7, LAMMPS Scripting language
Licence
MIT -however, note that LAMMPS is GPL so when used together GPL applies
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
Application Documentation
See `PIhydration README file <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIhydration>`_
Relevant Training Material
Add a link to any relevant training material.
.. contents:: :local:
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of the Module
_____________________
This software module computes the change in free energy associated with the insertion or deletion of water in dilute or dense conditions in a variety of Thermodynamic Ensembles, where statistical sampling through molecular dynamics is performed under `LAMMPS <https://lammps.sandia.gov/>`_ but will be extended to other molecular dynamics engines at a later date. It builds on the PI Core module of codes by adding electrostatic, bond, and angle
:math:`\lambda` dependent interactions including SHAKE to the Lennard-Jones interactions that were dealt with in PIcore. It differs from the main community approach used to date to compute such changes as it does not use soft-core potentials. Its key advantages over soft-core potentials are: (a) electrostatic interactions
can in principle be performed simultaneously
with particle insertion (this and other functionalities will be added in a new module); and, (b) essentially exact long-range dispersive interactions
using `dispersion Particle Mesh Ewald <https://doi.org/10.1063/1.4764089>`_ (PMME) or EWALD if desired can be selected at runtime by the user.
Background Information
______________________
Particle insertion can be used to compute the free energy associated with hydration/drying, the insertion of cavities in fluids/crystals,
changes in salt levels, changes in solvent mixtures, and alchemical changes such as the mutation of amino-acids. in crystals. It can also be used to compute the free energy of solvent mixtures and the addition of salts, which is used in the purification processing industrially, for instance in the purification of pharmaceutical active ingredients. Particle insertion can in principle also be used to compute the free energy associated with changes in the pH, that is the proton transfer from a titratable site to the bulk,
for example in water.
Our approach consists of rescaling electrostatic charges of inserted atoms so that they converge to zero faster than inerted Van der Waals
atoms where the later uses the geometric mean for Lennard Jones diameters and binding energies, and that bond, angle, and dihedral spring constants and where
necessary also bond lengths scale to zero in the same fashion
the effective size of inserted atoms through a parameter :math:`\lambda` so that all interactions between inserted atoms and interactions between inserted atoms and atoms already present in the system are zero when :math:`\lambda = 0`, creating at most an integrable singularity which we can safely handle. In the context of Lennard-Jones type pair potentials,
our approach at a mathematical level is similar to Simonson, who investigated the mathematical conditions required to `avoid the
singularity of insertion <https://doi.org/10.1080/00268979300102371>`_. It turns out that a non-linear dependence of the interaction on :math: '\\lambda' between inserted
atoms and those already present is required (i.e. a simple linear dependence on :math: '\\lambda' necessarily introduces a singularity).
The applications of this module use in upcoming modules include computing the free energy changes associated with:
::
(a) hydration and drying;
(b) the addition of multiple molecules into a condenses environment;
(c) residue mutation and alchemy;
(d) constant pH simulations, this also will also exploit modules created in E-CAM work package 3
(quantum dynamics); and,
(e) free energy changes in chemical potentials associated with changes in solvent mixtures.
General Formulation
___________________
Consider a system consisting of :math:`N+M` degrees of freedom and the Hamiltonian
where :math:`H_0` corresponds to an unperturbed Hamiltonian, and the perturbation :math:`\Delta V(r, \lambda)` depends nonlinearly on a control parameter :math:`\lambda`. The first set of N degrees of freedom is denoted by A and the second set of M degrees of freedom is denoted by B. To explore equilibrium properties of the system, thermostats, and barostats are used to sample either the NVT (canonical) ensemble or the NPT (Gibbs) ensemble. The perturbation is devised so that
when :math:`\lambda = 0`, :math:`\Delta V(r, \lambda) = 0`, B is in purely virtual. When :math:`\lambda = 1`, B
corresponds to a fully physical augmentation of the original system.
In the present software module, we include in the perturbation interaction Lennard Jones potenetials, harmonic bond and angle interactions, and
and the mixing rule for Van der Waals diameters and binding energy between different atoms uses the geometric mean for atoms pairs where one or more of the atoms is inserted but retains the mixing rule for atoms already present. The dependence of
:math:`\sigma` on :math:`\lambda` has the consequence that the mean
:math:`\sigma` between a pair of inserted atoms scales as :math:`\lambda`, but scales as :math:`\sqrt{\lambda}` when one atom in the pair is
inserted and the other is already present. The dependence of math:`\epsilon` on :math:`\lambda` ensures that forces behave regularly when
:math:`\lambda` is very small. These choices of perturbations guarantees that the particle insertion and deletion catastrophes are avoided.
Regarding electrostatic interactions, the exponent p allows the rate of convergence electrostatic interactions to zero to be faster than the rate at which that the effective diameters between corresponding Lennard Jones atoms go to zero, so as to ensure divergences are avoided. Currently p = 1.5. The spring constants for harmonic, angular and torsional interactions involving inserted atoms are currently simply multiplied by :math:`\lambda`.It is also possible to replace
bond, angle and torsional interactions involving only inserted atoms with shake constraints. In such cases, the shake constraints are continuously on. For cases where arithmetic sum rules apply to the original system, an additional lambda bases perturbation stage can be applied to transform geometric mean based mixing rules for Lennard Jones interactions to arithmetic mean rules governing interactions between inserted atoms or inserted atoms and original atoms.
Algorithms
__________
At the core of the PI core module there are four functions/codes. The first written in python generates the interpolation points which are
the zero's of suitably transformed Chebyshev functions.
The second code written ln LAMMPS scripting language performs the simulation in user-defined ensembles at the selected
interpolation values of :math:'lambda', at a user-specified frequency, computing two-point central difference estimates of derivatives of the
potential energy needed for thermodynamic integration, computing the energy
functions for all values of :math:'lambda' in the context of MBAR. The user also specifies the locations of the inserted particles.
The user also specifies whether
Particle Mesh Ewald or EWALD should be used for dispersive interactions.
The third code written in python takes the output data from LAMMPPS, prepares it so that free energy differences in the selected ensemble can be computed using MBAR provided by the pymbar suite of python codes of the Chodera group.
The fourth code, also written in python take the LAMMPS output and performs the thermodynamic integration.
Source Code
___________
All files can be found in the ``PIhydration`` subdirectory of the `particle_insertion git repository <https://gitlab.e-cam2020.eu/mackernan/particle_insertion>`_.
Compilation and Linking
_______________________
See `PIhydration README <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIhydration/README.rst>`_ for full details.
Scaling and Performance
_________________________
As the module uses LAMMPS, the performance and scaling of this module should essentially be the same, provided data for thermodynamic integration and
MBAR is not generated too often. In the case of thermodynamic integration, this is due to the central difference approximation of derivatives, and in the case
of MBAR, it is due to the fact that many virtual moves are made which can be extremely costly if the number of interpolating points is large. Also, when using
PMME, the initial setup cost is computationally expensive, and should, therefore, be done as infrequently as possible. A future module in preparation will
circumvent the use of central difference approximations of derivatives.
**pyscal** is a python module for the calculation of local atomic structural environments including Steinhardt's bond orientational order parameters [1]_ during post-processing
of atomistic simulation data. The core functionality of pyscal is written in C++ with python wrappers using
`pybind11 <https://pybind11.readthedocs.io/en/stable/intro.html>`_ which allows for fast calculations and
easy extensions in python.
Purpose of Module
_________________
Steinhardt's order parameters are widely used for the identification of crystal structures [3]_. They are also used to distinguish
if an atom is in a solid or liquid environment [4]_. pyscal is inspired by the
but has since incorporated many additional features and modifications. The pyscal module includes the following functionalities:
* calculation of Steinhardt's order parameters and their averaged version [2]_.
* links with the `Voro++ <http://math.lbl.gov/voro++/>`_ code, for the calculation of Steinhardt parameters weighted using the face areas of Voronoi polyhedra [3]_.
* classification of atoms as solid or liquid [4]_.
* clustering of particles based on a user defined property.
* methods for calculating radial distribution functions, Voronoi volumes of particles, number of vertices and face area of Voronoi polyhedra, and coordination numbers.
Background Information
______________________
See the `application documentation <https://pyscal.readthedocs.io/en/latest/>`_ for full details.
The utilisation of Dask within the project came about as a result of the `E-CAM High Throughput Computing ESDW <https://www.e-cam2020.eu/event/4424/?instance_id=71>`_ held in Turin in 2018 and 2019.
Building and Testing
____________________
**Installation**
pyscal can be installed directly using `Conda <https://docs.conda.io/en/latest/>`_ by the following statement-
.. code:: console
conda install -c pyscal pyscal
pyscal can be built from the repository by-
.. code:: console
git clone https://github.com/srmnitc/pyscal.git
cd pyscal
python setup.py install --user
**Testing**
pyscal contains automated tests which
use the `pytest <https://docs.pytest.org/en/latest/>`_ python library, which can be installed by ``pip install pytest``.
The tests can be run by executing the command ``pytest tests/`` from the main code directory.
**Examples**
Examples using pyscal can be found `here <https://pyscal.readthedocs.io/en/latest/examples.html>`_.
An `interactive notebook <https://mybinder.org/v2/gh/srmnitc/pyscal/master?filepath=examples%2F>`_
using binder is also available.
Source Code
___________
The `source code <https://github.com/srmnitc/pyscal>`_. of the module can be found on GitHub.
.. [1] `Steinhardt, P. J., Nelson, D. R., & Ronchetti, M. (1983). Physical Review B, 28 <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.28.784>`_.
.. [2] `Lechner, W., & Dellago, C. (2008). The Journal of Chemical Physics, 129 <https://aip.scitation.org/doi/full/10.1063/1.2977970>`_.
.. [3] `Mickel, W., Kapfer, S. C., Schröder-Turk, G. E., & Mecke, K. (2013). The Journal of Chemical Physics, 138 <https://aip.scitation.org/doi/full/10.1063/1.4774084>`_.
.. [4] `Auer, S., & Frenkel, D. (2005). Advances in Polymer Science, 173 <https://link.springer.com/chapter/10.1007/b99429>`_.
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
reference to work (so don't insert a comment between).
.. _elpa_easyblock:
###############################
Add ELPA easyblock to EasyBuild
###############################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
EasyBuild is used by a number of large HPC sites and integrating targeted support for ELPA ensures that those sites
use optimally built versions of ELPA.
Purpose of Module
_________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Automate the selection of appropriate configuration flags for ELPA within EasyBuild depending on the type of CPU and available features.
Include additional options as appropriate. Build single and double precision versions of ELPA and also ensure it is linked against the expected version of the linear algebra libraries.
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
EasyBuild is a software build and installation framework that allows you to manage (scientific) software on High
Performance Computing (HPC) systems in an efficient way. Full details on can be found in the