Adam Włodarczyk (Wrocław Centre of Networking and Supercomputing),
Alan O'Cais (Juelich Supercomputing Centre)
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
...
...
@@ -38,10 +37,11 @@
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).
.. _htc_mpi:
#####
pybop
#####
####################
HTC Multi-node Tasks
####################
.. Let's add a local table of contents to help people navigate the page
...
...
@@ -52,30 +52,22 @@ pybop
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."
``pybop`` is a python module for calculation of bond orientational order parameters [#]_. The core functionality of ``pybop`` is written in C++ with python wrappers using `pybind11 <https://pybind11.readthedocs.io/en/stable/intro.html>`_ . This allows for fast calculations with possibilities for seamless expansion in python.
This module is the third in a sequence that will form the overall capabilities of the HTC library (see :ref:`htc_yaml`
for the previous module). This module deals with enabling tasks to be run over a set of nodes (specifically MPI/OpenMP
tasks).
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
Bond orientational order parameters have been widely used in distinction of crystal structures in computational studies [#]_. Additionally, these parameters have also been used to distinguish between solid and liquid particles in studies of crystallisation during solidification [#]_.
``pybop`` provides a flexible post-processing python environment for these calculations, at the same time ensuring speed and efficiency as the core code is written in C++ with `pybind11 bindings <https://pybind11.readthedocs.io/en/stable/intro.html>`_. ``pybop`` also links with `Voro++ <http://math.lbl.gov/voro++/>`_ code to carry out calculations of voronoi volumes, indices and face areas.
Some of the major uses of ``pybop`` are listed below-
- calculations including the bond order parameters :math:`q_{i}` where :math:`i = \{2,3 \to 12\}`.
- averaged versions which has been to improve the resolution in identification of crystal structures [#]_.
- weighted :math:`q_{i}` where the contributions are weighted by the voronoi face area shared with adjacent atoms [#]_.
- distinction of liquid and solid atoms based on :math:`q_{6}` parameter.
- calculation of the parameters in non-orthogonal simulation boxes.
- other quantities like radial distribution function, coordination number and voronoi volume of individual particles.
``pybop`` can read in output data from LAMMPS [#]_ `dump format <https://lammps.sandia.gov/doc/dump.html>`_ and POSCAR files from VASP. The module also provides an easy interface for extension of the available data formats or linking with other codes to read in input data.
.. I will add information about the paper and results using pybop.
The initial goal is to allow the HTC library to control tasks that are executed via the MPI launcher command. The task
tracked by Dask is actually the process created by the launcher. The launcher is a forked process from within the
library.
The implementation is intended to be generic but the specific example implementation provided is for ``srun`` launcher
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
See the `application documentation <https://srmnitc.github.io/pybop/html/index.html>`_ 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.
This module builds upon the work described in :ref:`htc_yaml`.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
**Installation**
The library is a Python module and can be installed with
::
First, clone the ``pybop`` repository by ``git clone https://github.com/srmnitc/pybop.git``.
After cloning the repository, ``pybop`` can be installed by running ``python setup.py install`` from main code directory. It can be uninstalled by ``pip uninstall pybop``. All the dependencies of ``pybop`` are installed automatically.
python setup.py install
**Testing**
More details about how to install a Python package can be found at, for example, `Install Python packages on the
research computing systems at IU <https://kb.iu.edu/d/acey>`_
``pybop`` also 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.
To run the tests for the decorators within the library, you need the ``pytest`` Python package. You can run all the
relevant tests from the ``jobqueue_features`` directory with
::
**Examples**
pytest tests/test_mpi_wrapper.py
Examples uses of ``pybop`` can be found `here <https://srmnitc.github.io/pybop/html/examples.html>`_. An `interactive notebook <https://mybinder.org/v2/gh/srmnitc/pybop/master?filepath=examples%2F>`_ using binder is also available.
Specific examples of usage for the JURECA system are available in the ``examples`` subdirectory.
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
The `source code <https://github.com/srmnitc/pybop>`_. of the module can be found on GitHub.
The latest version of the library is available on the `jobqueue_features GitHub repository
<https://github.com/E-CAM/jobqueue_features>`_
.. [#] Steinhardt, PJ, Nelson, DR, Ronchetti, M. Phys. Rev. B 28, 1983.
.. [#] Lechner, W, Dellago, C, Bolhuis, P.G. J. Chem. Phys. 125, 2011., Diaz Leines, G, Drautz, R, Rogal, J. J. Chem. Phys. 146, 2017.
.. [#] Diaz Leines, G, Drautz, R, Rogal, J. J. Chem. Phys. 146, 2017.
.. [#] Lechner, W, Dellago, C. J. Chem. Phys. 129, 2008.
.. [#] Mickel, W, Kapfer, S.C, Schroder-Turk, G.E, Mecke, K. J. Chem. Phys. 138, 2013.
.. [#] Plimpton, S. J Comp. Phys. 117, 1995.
The code that was originally created specifically for this module can be seen in the
`HTC/MPI Merge Request <https://gitlab.e-cam2020.eu/adam/jobqueue_features/merge_requests/5>`_ which can be found in
the original private repository of the code. Additional, more complex, examples were provided in the
.. 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).
.. _minDist2segments_KKT:
#################################
E-CAM minDist2segments_KKT module
#################################
.. 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."
The minDist2segments_KKT module returns the minimal distance between two `line segments <https://en.wikipedia.org/wiki/Line_segment>`_.
It uses the Karush-Kuhn-Tucker conditions `(KKT) <https://en.wikipedia.org/wiki/Karush%E2%80%93Kuhn%E2%80%93Tucker_conditions>`_
for the minimization under constraints.
.. The E-CAM library is purely a set of documentation that describes software development efforts related to the project.
A *module* for E-CAM is the documentation of the single development of effort associated to the project. In that sense, a
module does not directly contain source code but instead contains links to source code, typically stored elsewhere. Each
module references the source code changes to which it direcctly applies (usually via a URL), and provides detailed
information on the relevant *application* for the changes as well as how to build and test the associated software.
.. The original source of this page (:download:`readme.rst`) contains lots of additional comments to help you create your
documentation *module* so please use this as a starting point. We use Sphinx_ (which in turn uses ReST_) to create this
documentation. You are free to add any level of complexity you wish (within the bounds of what Sphinx_ and ReST_ can
do). More general instructions for making your contribution can be found in ":ref:`contributing`".
.. Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application
must pass a number of acceptance criteria:
.. * Style *(use meaningful variable names, no global variables,...)*
.. * Source code documentation *(each function should be documented with each argument explained)*
.. * Tests *(everything you add should have either unit or regression tests)*
.. * Performance *(If what you introduce has a significant computational load you should make some performance optimisation
effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected
performance penalties, are threadsafe if needed,...)*
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
To study the long term memory of the initial conformation of a highly entangled polymer we need to preserve the topology.
It means that two polymer bonds cannot cross. It is of great importance for the study of post-mitotic chromosome unfolding.
To resolve the excluded volume constraints one could use a soft or hard potential between the two points associated to the
minimal distance.
.. Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
it fits into the larger picture of what you want to achieve. The overview should be comprehensible to a scientist
non-expert in the domain area of the software module.
.. This section should also include the following (where appropriate):
* Polymer simulation.
* To resolve the excluded volume constraints.
* It is used in a scientific collaborations.
* Publications: not currently available.
.. note::
We would use the present module to avoid topology violation in an entangled polymer system.
This module is used by other ongoing work.
.. If needed you can include latex mathematics like :math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`
which won't show up on GitLab/GitHub but will in final online documentation.
.. If you want to add a citation, such as [CIT2009]_, please check the source code to see how this is done. Note that
citations may get rearranged, e.g., to the bottom of the "page".
.. .. [CIT2009] This is a citation (as often used in journals).
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
.. If the modifications are to an existing code base (which is typical) then this would be the place to name that
application. List any relevant urls and explain how to get access to that code. There needs to be enough information
here so that the person reading knows where to get the source code for the application, what version this information is
relevant for, whether this requires any additional patches/plugins, etc.
.. Overall, this module is supposed to be self-contained, but linking to specific URLs with more detailed information is
encouraged. In other words, the reader should not need to do a websearch to understand the context of this module, all
the links they need should be already in this module.
You can find pdf file with a detailed derivation of the minimal distance between two segments using the Karush-Kuhn-Tucker
conditions on the `minDist2segments_KKT GitLab repository <https://gitlab.e-cam2020.eu/carrivain/mindist2segments_kkt>`_.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
I provide a simple Makefile you can find at the same location that the source code.
You need C++11 in order to use the pseudo-random number generator.
The example also has OpenMP acceleration, edit the ``Makefile`` to enable it.
Before the compilation you can clean the previous build with the ``make mrproper`` command.
The purpose of the module is to calculate the minimal distance between two segments.
For each distance we compare the result to an "exact enumeration" of all the possible
distances and return a warning if the two results differ by more than the enumeration
precision.
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
.. Here link the source code *that was created for the module*. If you are using Github or GitLab and the `Gitflow Workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow>`_ you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits.
The source code and more information can be find at `minDist2segments_KKT GitLab repository <https://gitlab.e-cam2020.eu/carrivain/mindist2segments_kkt>`_.
.. 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).
.. _velocities_resolve_EVC:
###################################
E-CAM velocities_resolve_EVC module
###################################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
``velocities_resolve_EVC`` is a module that resolves the excluded volume constraint with a velocity formulation (no potential
applied between two overlapped bonds).
``velocities_resolve_EVC`` uses the module :ref:`minDist2segments_KKT` to find the minimal distance between two bonds.
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
To study the long term memory of the initial conformation of a highly entangled polymer we need to preserve the topology.
It means that two bonds cannot cross. It is of great importance for the study of post-mitotic chromosome unfolding.
To resolve the excluded volume constraints you could use a soft or hard potential between the two points associated to the
minimal distance. Here, we propose to change the relative velocity between overlapped bonds to resolve the excluded volume
constraint in one time-step of molecular dynamics.
* Polymer simulation.
* To resolve the excluded volume constraints.
* It is used in a scientific collaboration.
* Publications: not currently available.
.. note::
We would use the present module to avoid topology violation in an entangled polymer system.
The present module uses the E-CAM module :ref:`minDist2segments_KKT`.
.. note::
This module is a part of a pilot project (E-CAM post-doc). We would use it to avoid topology violation in an entangled polymer system.
Background Information
______________________
You can find a PDF file with a detailed derivation of the velocity-based method we use to resolve the excluded volume constraint
in one time-step of molecular dynamics on the `velocities_resolve_EVC GitLab repository <https://gitlab.e-cam2020.eu/carrivain/velocities_resolve_EVC>`_.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
I provide a simple Makefile you can find at the same location as the source code.
You need C++11 in order to use pseudo-random number generator.
Before the compilation you can clean the previous build with "make mrproper" command.
The purpose of the module is to resolve excluded volume constraints.
Therefore, we provide a simple example of a system of ``N`` bonds with volume interactions.
We test every ``n`` iterations the average overlap pairwise.
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
.. Here link the source code *that was created for the module*. If you are using Github or GitLab and the `Gitflow Workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow>`_ you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits.
The source code and more information can be find at `velocities_resolve_EVC GitLab repository <https://gitlab.e-cam2020.eu/carrivain/velocities_resolve_EVC>`_.
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>`_.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. sidebar:: General Information
.. contents:: :depth: 2
* :ref:`contributing`
* :ref:`search`
.. _readme_electronic_structure:
****************************
...
...
@@ -12,14 +19,7 @@ Electronic Structure Modules
Introduction
============
.. sidebar:: General Information
.. contents:: :depth: 2
* :ref:`contributing`
* :ref:`search`
.. figure:: ./images/wake_nova-rgb.png
.. figure:: ./images/protein-metal-cluster.png
:figwidth: 25 %
:align: left
...
...
@@ -55,6 +55,7 @@ The first Electronic Structure ESDW in Zaragoza in June 2016 was the starting po
./modules/sqare-grids-doc/readme
./modules/sqare-ode-doc/readme
./modules/sqare-states-doc/readme
./modules/esl-demo/readme
ESDW San Sebastian 2016
...
...
@@ -98,7 +99,7 @@ The ESDW in Dublin in January 2019 was the starting point for the modules below.
:maxdepth: 1
./modules/esl-easyconfigs/readme
./modules/ELSI/readme
Other Modules
-------------
...
...
@@ -110,6 +111,8 @@ Modules not coming from ESDWs
:maxdepth: 1
./modules/flook/readme
./modules/libgridxc/readme
./modules/libvdwxc/readme
./modules/MatrixSwitchDBCSR/readme
Pilot Projects
...
...
@@ -136,8 +139,28 @@ Below is a list of the modules developed directly within the context of the pilo
./modules/Gaussian_interface/README
./modules/WLRR/README
./modules/SCDM_WFs/readme
./modules/W90_MaX_collab/readme
./modules/W90_solution_booklet/readme
./modules/FFTXlib/readme
./modules/W90_cube_format_non-orthogonal/readme
./modules/miniPWPP/readme
./modules/PANNA-GVECT/readme
./modules/PANNA-TFR/readme
./modules/PANNA-TRAIN/readme
./modules/PANNA-EVAL/readme
./modules/PANNA-Charges/readme
QMCPack interfaces
------------------
The following modules related to interfaces for the QMCPack code have been produced so far in the context of an `associated Pilot Project <https://www.e-cam2020.eu/qmcpack-interfaces-for-es-computations/>`_:
To obtain accurate results with ground state Quantum Monte Carlo methods (such as Variational and Diffusion Monte Carlo) an accurate trial wave function is essential.
Such a wave function for an electron system will be typically given by the product of two factors: (1) a Jastrow term :math:`J` describing electronic correlations and (2) a Slater determinant of suitable single particle orbitals :math:`\phi_i`
where :math:`R` is the vector containing the position of all electrons and :math:`r_i` is the position of the :math:`i`-th electron.
While there is great freedom in the definition of the Jastrow term, that can then be variationally optimized, the single particle orbitals have to be computed in using Density Functional Theory.
The ESHDF5Interface module provides a derived class of ESInterfaceBase to generate single particle orbitals for QMC simulations performed using QMCPack from a suitable HDF5 file.
Background Information
______________________
QMCPack is available from the github repository `<https://github.com/QMCPACK/qmcpack>`_,
and the documentation can be found at the QMCPack website `<https://qmcpack.org/documentation>`_.
Building and testing
____________________
The EHDF5Interface module can be found in the QMCQEPack branch of the QMCPack git repository
detailed in the official QMCPack documentation `<https://qmcpack.org/documentation>`_, or in the manual available
in the ``manual`` subdirectory in the main QMCPack directory.
To use the interface one must use the ``interfaceh5`` keyword in the ``determinantset`` block in a QMCPack input file; further information can be found in Section 22.5.2 of the QMCPack manual, that can be compiled with the files in the ``manual`` directory.
The tests for this code are part of the deterministic unit tests for QMCPack, that can be run with the command
``ctest -R interface``
Note that the code is tested using the GCC compiler and OpenMPI.
Source Code
___________
The source code is available available from `<https://github.com/michruggeri/qmcpack/tree/QMCQEPack>`_ in the ``QMCQEPack`` branch. Specifically relevant files for this module include:
To obtain accurate results with ground state Quantum Monte Carlo methods (such as Variational and Diffusion Monte Carlo) an accurate trial wave function is essential.
Such a wave function for an electron system will be typically given by the product of two factors: (1) a Jastrow term :math:`J` describing electronic correlations and (2) a Slater determinant of suitable single particle orbitals :math:`\phi_i`
where :math:`R` is the vector containing the position of all electrons and :math:`r_i` is the position of the :math:`i`-th electron.
While there is great freedom in the definition of the Jastrow term, that can then be variationally optimized, the single particle orbitals have to be computed in using Density Functional Theory.
The ESInterfaceBase module provides a base class for a general interface to generate single particle orbitals for QMC simulations performed using QMCPack; implementations of specific interfaces as derived classes of ESInterfaceBase are available as separate modules.
Background Information
______________________
QMCPack is available from the github repository `<https://github.com/QMCPACK/qmcpack>`_,