Merge pull request #394 from initqp/master

Added PLUMED manuals.

doc/gpumd/input_parameters/index.rst

@@ -19,7 +19,8 @@ Below you can find a listing of keywords for the ``run.in`` input file.
    ensemble
    fix
    time_step
-
+   plumed
+
 .. toctree::
    :maxdepth: 1
    :caption: Actions

doc/gpumd/input_parameters/plumed.rst

@@ -0,0 +1,70 @@
+.. _kw_plumed:
+.. index::
+   single: plumed (keyword in run.in)
+
+:attr:`plumed`
+===================
+
+Invoke the `PLUMED <https://www.plumed.org/>`_ plugin during a MD run.
+
+
+Syntax
+------
+
+This keyword has the following format::
+
+  plumed <plumed_file> <interval> <if_restart>
+
+The :attr:`plumed_file` parameter is the name of the PLUMED input file.
+The :attr:`interval` parameter is the interval (number of steps) of calling the PLUMED subroutines.
+The :attr:`if_restart` parameter determines if the PLUMED plugin should restart its calculations, which includes appending to its output files, reading the previous biases, etc.
+
+
+Requirements and specifications
+-------------------------------
+
+* This keyword requires an external package to operate.
+  Instructions for how to set up the `PLUMED package <https://www.plumed.org/>`_ can be found :ref:`here <plumed_setup>`.
+* Increasing the :attr:`interval` parameter will speed up your simulation if you only want PLUMED to calculate collective variables (CVs). But you have to set it to 1 if your simulation was biased by PLUMED.
+
+
+Examples
+--------
+
+Example 1
+^^^^^^^^^
+
+To calculate the distance between atoms, one can add::
+
+  plumed plumed.dat 1000 0
+
+before the :ref:`run command <kw_run>`. The plumed.dat file, for example, may look like::
+
+  UNITS LENGTH=A TIME=fs ENERGY=eV
+  FLUSH STRIDE=1
+  DISTANCE ATOMS=1,2 LABEL=d1
+  PRINT FILE=colvar ARG=d1
+
+The output file created by PLUMED (the colvar file) will be updated every 1000 steps.
+
+Example 2
+^^^^^^^^^
+
+To restrain the distance between atoms, one can add::
+
+  plumed plumed.dat 1 0
+
+before the :ref:`run command <kw_run>`. The plumed.dat file, for example, may look like::
+
+  UNITS LENGTH=A TIME=fs ENERGY=eV
+  FLUSH STRIDE=1
+  DISTANCE ATOMS=1,2 LABEL=d1
+  RESTRAINT ARG=d1 AT=0.0 KAPPA=2.0 LABEL=restraint
+  PRINT FILE=colvar ARG=d1,restraint.bias
+
+
+Caveats
+-------
+
+* This keyword is not propagating.
+  That means, its effect will not be passed from one run to the next.

doc/installation.rst

@@ -67,8 +67,64 @@ The setup instructions are below:
      INC = -I<path>/netcdf/include
      LDFLAGS = -L<path>/netcdf/lib
      LIBS = -l:libnetcdf.a
-     
+
   where :attr:`<path>` should be replaced with the installation path for NetCDF (defined in :attr:`--prefix` of the ``./configure`` command).
 * Follow the remaining :program:`GPUMD` installation instructions
 
 Following these steps will enable the :ref:`dump_netcdf keyword <kw_dump_netcdf>`.
+
+
+.. _plumed_setup:
+.. index::
+   single: PLUMED setup
+
+PLUMED Setup Instructions
+=========================
+
+To use `PLUMED <https://www.plumed.org/>`_ (see :ref:`plumed keyword <kw_plumed>`) with :program:`GPUMD`, a few extra steps must be taken before building :program:`GPUMD`.
+First, you must download and install PLUMED.
+
+The setup instructions are below:
+
+* Download `the latest version of PLUMED <https://github.com/plumed/plumed2/releases/>`_, e.g. the `plumed-src-2.8.2.tgz <https://github.com/plumed/plumed2/releases/download/v2.8.2/plumed-src-2.8.2.tgz>`_ tarball.
+* Configure and build PLUMED.
+  It is best to follow the `instructions <https://www.plumed.org/doc-v2.8/user-doc/html/_installation.html>`_, but for a quick installation, you may use the following setup:
+
+  .. code:: bash
+
+     ./configure --prefix=/home/user/plumed --disable-mpi --enable-openmp --enable-modules=all
+
+  Here, the :attr:`--prefix` determines the output directory of the build. Then make and install PLUMED:
+
+  .. code:: bash
+
+     make && make install
+
+  Then update your environment variables (e.g., add the following lines to your bashrc file):
+
+  .. code:: bash
+
+     export PLUMED_KERNEL=<path>/lib/libplumedKernel.so
+     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path>/lib
+     export PATH=$PATH:<path>/bin
+
+  where :attr:`<path>` should be replaced with the installation path for PLUMED (defined in :attr:`--prefix` of the ``./configure`` command). Finally, reopen your shell to apply changes.
+* Enable the PLUMED functionality.
+  To do this, one must enable the :attr:`USE_PLUMED` flag.
+  In the makefile, this will look as follows:
+
+  .. code:: make
+
+     CFLAGS = -std=c++11 -O3 -arch=sm_75 -DUSE_PLUMED
+
+  In addition to that line the makefile must also be updated to the following:
+
+  .. code:: make
+
+     INC = -I<path>/include
+     LDFLAGS = -L<path>/lib -lplumed -lplumedKernel
+
+  where :attr:`<path>` should be replaced with the installation path for PLUMED (defined in :attr:`--prefix` of the ``./configure`` command).
+* Follow the remaining :program:`GPUMD` installation instructions
+
+Following these steps will enable the :ref:`plumed keyword <kw_plumed>`.