From 54851037146ee8fef607165bb13ff368aed5150c Mon Sep 17 00:00:00 2001
From: Gareth Tribello <gt@eider.phy.qub.ac.uk>
Date: Sat, 21 Jun 2014 16:56:23 +0100
Subject: [PATCH] Added documentation for last undocumented action.
This commit resolves issue #97 However, I also changed the layout of
the colvar page on the manual so I thought I would push it on a branch
before merging it into master. Let me know if there are any objections
to the changes I have made.
---
src/manyrestraints/UWalls.cpp | 34 +++++++++++++++++++++++++++++
user-doc/Colvar.txt | 40 +++++++++++++++++++++++++++++++----
user-doc/PlumedLayout.xml | 2 ++
user-doc/extract | 5 +++--
4 files changed, 75 insertions(+), 6 deletions(-)
diff --git a/src/manyrestraints/UWalls.cpp b/src/manyrestraints/UWalls.cpp
index 9a278140f..0b3a6e3cb 100644
--- a/src/manyrestraints/UWalls.cpp
+++ b/src/manyrestraints/UWalls.cpp
@@ -25,6 +25,40 @@
namespace PLMD {
namespace manyrestraints {
+//+PLUMEDOC MCOLVARB UWALLS
+/*
+Add \ref UWALL restraints on all the multicolvar values
+
+This action takes the set of values calculated by the colvar specified by label in the DATA
+keyword and places a restraint on each quantity, \f$x\f$, with the following functional form:
+
+\f$
+ k((x-a+o)/s)^e
+\f$
+
+\f$k\f$ (KAPPA) is an energy constant in internal unit of the code, \f$s\f$ (EPS) a rescaling factor and
+\f$e\f$ (EXP) the exponent determining the power law. By default: EXP = 2, EPS = 1.0, OFF = 0.
+
+\par Examples
+
+The following set of commands can be used to stop a cluster composed of 20 atoms subliming. The position of
+the centre of mass of the cluster is calculated by the \ref COM command labelled c1. The \ref DISTANCES
+command labelled d1 is then used to calculate the distance between each of the 20 atoms in the cluster
+and the center of mass of the cluster. These distances are then passed to the UWALLS command, which adds
+a \ref UWALL restraint on each of them and thereby prevents each of them from moving very far from the centre
+of mass of the cluster.
+
+\verbatim
+COM ATOMS=1-20 LABEL=c1
+DISTANCES GROUPA=c1 GROUPB=1-20 LABEL=d1
+UWALLS DATA=d1 AT=2.5 KAPPA=0.2 LABEL=sr
+\endverbatim
+
+
+*/
+//+ENDPLUMEDOC
+
+
class UWalls : public ManyRestraintsBase {
private:
double at;
diff --git a/user-doc/Colvar.txt b/user-doc/Colvar.txt
index 1a451b696..6b81cc426 100644
--- a/user-doc/Colvar.txt
+++ b/user-doc/Colvar.txt
@@ -9,14 +9,23 @@ interested in and monitor these simpler quantities instead. These CVs are used
implemented in PLUMED - there values can be monitored using \ref PRINT, \ref Function of them can be calculated
or they can be analyzed or biased using the \ref Analysis and \ref Bias "Biasing" methods implemented in PLUMED.
Before doing any of these things however we first have to tell PLUMED how to calculate them.
-
+
+On this page we list the simplest collective variables that are implemented in PLUMED 2. These colvars all take in a
+set of atomic positions and output one or multiple scalar CV values. Many other collective variables are available in PLUMED.
+In particular, the page on \dists describes the various ways that you can calculate the distance from a particular reference
+configuration. Meanwhile, the page on \ref Function describes the various functions of collective variables that can be used in the
+code. Lastly the page on \mcolv describes MultiColvars. MultiColvars allow you to use many different colvars and allow us to
+implement all these collective variables without implementing having an unmanigiably large ammount of code. For some things (e.g.
+\ref DISTANCES GROUPA=1 GROUPB=2-100 LESS_THAN={RATIONAL R_0=3}) there are more computationally efficient options available in plumed
+(e.g. \ref COORDIATION). However, MultiColvars are worth investigating as they provide a flexible syntax for many quite-complex CVs.
+
\section cvavail CV Documentation
The following list contains descriptions of a number of the colvars that are currently implemented in PLUMED 2.
@COLVAR@
-\section dists Distances from reference configurations
+\page dists Distances from reference configurations
One colvar that has been shown to be very sucessful in studying protein folding is the distance between the instantaneous configuration
and a reference configuration - often the structure of the folded state. When the free energy of a protein is shown as a function
@@ -37,9 +46,9 @@ with the ammount the collective variables change. A full list of the ways dista
These options for calculating distances are re-used in a number of places in the code. For instance they are used in some of the
analysis algorithms that are implemented in PLUMED and in \ref PATH collective variables.
-\section mcolv MultiColvar Documentation
+\page mcolv MultiColvar Documentation
-Often you do not need one of the collective variables described in the previous section. What you want instead is a
+Oftentimes, when you do not need one of the collective variables described elsewhere in the manual, what you want instead is a
function of a distribution of collective variables of a particular type. For instance you might need to calculate a
minimum distance or the number of coordination numbers greater than a 3.0. To avoid dupilcating the code to calculate
an angle or distance many times and to make it easier to implement very complex collective variables PLUMED provides
@@ -94,5 +103,28 @@ base colvars can be computed by employing multicolvars in conjuction with the fo
@MCOLVARF@
+\section multicolvarbias MultiColvar bias
+
+There may be occasitions when you want add restraints on many collective variables. For instance if you are studying a cluster
+you might want to add a wall on the distances between each of the atoms and the center of mass of the cluster in order to
+prevent the cluster subliming. Alternatively, you may wish to insist that a particular set of atoms in your system all have a
+coordination number greater than 2. You can add these sorts of restraints by employing the following biases, which all act
+on the set of collective variable values calculated by a multicolvar. So for example the following set of commands:
+
+\verbatim
+COM ATOMS=1-20 LABEL=c1
+DISTANCES GROUPA=c1 GROUPB=1-20 LABEL=d1
+UWALLS DATA=d1 AT=2.5 KAPPA=0.2 LABEL=sr
+\endverbatim
+
+creates the aforementioned set of restraints on the distances between the 20 atoms in a cluster and the center of mass of the cluster.
+
+The list of biases of this type are as follows:
+
+@MCOLVARB@
+
+Notice that (in theory) you could also use this functionality to add additional terms to your forcefield or to implement your
+forcefield.
+
*/
diff --git a/user-doc/PlumedLayout.xml b/user-doc/PlumedLayout.xml
index 2c1dce92a..438093e04 100644
--- a/user-doc/PlumedLayout.xml
+++ b/user-doc/PlumedLayout.xml
@@ -15,7 +15,9 @@
<tab type="usergroup" title="Collective variables">
<tab type="user" visible="yes" url="_group.html" title="Groups and Atoms"/>
<tab type="user" visible="yes" url="_colvar.html" title="Collective Variables"/>
+ <tab type="user" visible="yes" url="dists.html" title="Distances from reference configurations"/>
<tab type="user" visible="yes" url="_function.html" title="Functions"/>
+ <tab type="user" visible="yes" url="mcolv.html" title="MultiColvar documentation"/>
</tab>
<tab type="user" visible="yes" url="_analysis.html" title="Analysis"/>
<tab type="user" visible="yes" url="_bias.html" title="Bias"/>
diff --git a/user-doc/extract b/user-doc/extract
index a0ab7e878..415fd1b51 100755
--- a/user-doc/extract
+++ b/user-doc/extract
@@ -65,7 +65,7 @@ awk 'BEGIN{gfile="automatic/GLOSSARY.list"; dfile="automatic/DICTIONARY.list"; }
if(inside==3){ printf "%s", $0 > dfile; }
}
if($1=="//+PLUMEDOC"){
- if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="MCOLVAR" || $2=="DCOLVAR"|| $2=="MCOLVARF" || $2=="FUNCTION" || $2=="ANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
+ if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="MCOLVAR" || $2=="DCOLVAR"|| $2=="MCOLVARF" || $2=="MCOLVARB" || $2=="FUNCTION" || $2=="ANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
lfile="automatic/"$2".list"
printf "<tr> <td width=%s> \\subpage %s </td> <td>","5%", $3 > lfile
@@ -192,7 +192,7 @@ do
fi
done
-for file in COLVAR MCOLVAR DCOLVAR MCOLVARF ANALYSIS BIAS GLOSSARY \
+for file in COLVAR MCOLVAR DCOLVAR MCOLVARF MCOLVARB ANALYSIS BIAS GLOSSARY \
DICTIONARY TUTORIALS WEBSITES FUNCTION TOPOLOGY VATOM \
TOOLS
do
@@ -218,6 +218,7 @@ cat $file.txt |
/^ *@MCOLVAR@ *$/r automatic/MCOLVAR.list
/^ *@DCOLVAR@ *$/r automatic/DCOLVAR.list
/^ *@MCOLVARF@ *$/r automatic/MCOLVARF.list
+ /^ *@MCOLVARB@ *$/r automatic/MCOLVARB.list
/^ *@ANALYSIS@ *$/r automatic/ANALYSIS.list
/^ *@BIAS@ *$/r automatic/BIAS.list
/^ *@GLOSSARY@ *$/r automatic/GLOSSARY.list
--
GitLab