.. _metadynamics:
Metadynamics
------------
Introduction
^^^^^^^^^^^^
Metadynamics defines a class of flat-histogram methods useful for
molecular dynamics simulations. Within metadynamics, a
history-dependent bias is accrued through the periodic application of
elemental Gaussian biases to the collective variables (CVs) of
interest. The form of the individual biases is
.. math::
g(\vec{\xi},\vec{s}_i) = W_i
e^{-\frac{\left[\vec{\xi}-\vec{s}_i\right]^2}{2\sigma_i^2}}\;.
Here, :math:`\vec{\xi}` is the collective variable, :math:`\vec{s}_i` is
the location of the :math:`i^\text{th}` hill, :math:`W_i` is the weight and
:math:`\sigma_i` the width of the hill. This bias acts to push the
system away from previously visited states. As this bias accrues to
the height of nearby features in the free energy surface, the system's
trajectory will begin to explore an expanded area in CV space. After a
sufficient number of biases have been applied, the total applied bias
within a given region will begin to oscillate around the negative of
the free energy in that region.
The free energy surface (FES) at any time :math:`t` may be
reconstructed by summing over all applied biases thusly
.. math::
F(\vec{\xi},t) = -V(\vec{\xi}) = -\sum_{i < n(t)} W_i
e^{-\frac{\left[\vec{\xi}-\vec{s}_i\right]^2}{2\sigma_i^2}}\;.
Here, :math:`n(t)` refers to the number of biases applied before time
:math:`t`. The time-dependent FES can be used to determine whether or
not a simulation has reached a converged FES by computing block
averages of the applied bias (see :cite:`SINGH2012369`).
Metadynamics can be applied to unbounded regions of CV space, or to
bounded regions. For the case of bounded, non-periodic CVs, boundary
corrections must be applied which alter the structure of the hills
:math:`g(\vec{\xi},\vec{s}_i)` (see :cite:`MCGOVERN2013084102`)
Metadynamics exists in many flavors, in which :math:`W_i` and
:math:`\sigma_i` are altered in a time- or trajectory- dependent
fashion. These include Well-Tempered Metadynamics, Transition-Tempered
Metadynamics and Metadynamics with Adaptive Gaussians. Each of these
methods has advantages and drawbacks. Currently, SSAGES includes only
standard Metadynamics with fixed-shape hills and no tempering
algorithm. Details on how to use these algorithms within SSAGES are
given in the following sections.
Options & Parameters
^^^^^^^^^^^^^^^^^^^^
Metadynamics is selected by defining ``type" : "Metadynamics"`` as the
method in the JSON input file. It supports the following options:
widths
*array of doubles (length: number of CVs)*.
This array defines the width of the Gaussians being deposited over time
in each CV dimension.
height
*double*.
This value defines the height of the Gaussians being deposited over time,
in units of energy used by the MD engine.
hill_frequency
*double*
This value defines the frequency in iterations with which the Gaussians
are deposited.
.. note::
The Metadynamics method does not yet support CV bounds.
.. note::
The Metadynamics method does not yet support restarts.
.. warning::
Metadynamics will run for the duration specified in the input files. It is
the user's responsibility to ensure that enough time is given for
Metadynamics to obtain an satisfactory representation of the free energy
surface of interest. A simple way to prevent Metadynamics from terminating
before convergence is to define a very large number of timesteps and to
check the output file periodically for convergence.
Example Input
^^^^^^^^^^^^^
.. code-block:: javascript
"method": {
"type": "Metadynamics",
"widths": [0.1, 0.1],
"height": 0.1,
"hill_frequency": 1
}
Output
^^^^^^
The output of Metadynamics is stored in a file called "hills.out". This file
contains the location, width and height of each Gaussian that has been deposited
over time. Each time Gaussian is deposited, a new line is written to the file
in the following format:
*center1 center2 ... width1 width2 ... height*
The centers denote the locations in CV space where each Gaussian has been
deposited, listed in the order in which the CVs appear within the SSAGES JSON
input file. The widths denote the corresponding Gaussian widths for each CV
dimension. The height is the Gaussian height, which should match the parameter
height defined in the JSON input file.
.. note::
Although the widths and height of the Gaussian currently do not change in
time, future additions to the Metadynamics method will allow for adaptive
Gaussians.
Example MATLAB scripts are provided in the ``Examples/User/Meta`` directory.
These scripts sum the Gaussians and generate a free energy surface from
the "hills.out" file.
.. _metadynamics-tutorial:
Tutorial
^^^^^^^^
Two Metadynamics examples are included in the ``Examples/User/Meta`` directory.
In the first example, Metadynamics is used to sample the free energy surface of
a two-dimensional particle undergoing Langevin dynamics. This example is found in
the ``Single_Atom`` directory and uses LAMMPS.
The files included are described below:
* ``in.LAMMPS_Meta_Test``: LAMMPS input file describing the Langevin particle
and underlying free energy surface to be sampled. The free energy surface
consists of two Gaussian wells at (0.98, 0.98) and (-0.98, -0.98)
respectively, and one Gaussian barrier at the origin.
* ``Meta.json``: SSAGES JSON input file specifying Metadynamics and CVs to be
sampled. In this case the CVs are the *x* and *y* coordinates of the particle.
* ``analysis.m``: MATLAB script that analyzes the output of the Metadynamics
method.
* ``Movie.m``: MATLAB script that generates a movie of the free energy
surface estimate over time.
To run this example:
1. Either copy or create a symbolic link to the SSAGES executable in the
examples directory.
.. code-block:: bash
ln -s /path/to/SSAGES/build/ssages
2. Run the example by issuing the command below. Please note that in this
example, two walkers are used to explore the system more efficiently. If
you would like to use more walkers (1 processor per walker), simply include
more drivers in the ``Meta.json`` input file.
.. code-block:: bash
mpirun -np 2 ./ssages Meta.json
3. After the run is complete use the provided ``analysis.m`` or ``analysis.py``
script to generate a representation of the underlying free energy surface using
MatLab or python (Matplotlib and numpy required).
Developer
^^^^^^^^^
* Hythem Sidky