From 0a54692d3fc847fccde769f8a27e80be1c5753b2 Mon Sep 17 00:00:00 2001
From: Gareth Tribello <gareth.tribello@gmail.com>
Date: Tue, 26 Mar 2013 11:47:05 +0000
Subject: [PATCH] Improved documentation for multicolvars
---
src/multicolvar/VolumeSubcell.cpp | 35 ++++++++++++++++----
user-doc/Colvar.txt | 53 ++++++++++++++++++++++++++++---
user-doc/extract | 7 +++-
3 files changed, 84 insertions(+), 11 deletions(-)
diff --git a/src/multicolvar/VolumeSubcell.cpp b/src/multicolvar/VolumeSubcell.cpp
index e9c7c0af1..03d86c5c4 100644
--- a/src/multicolvar/VolumeSubcell.cpp
+++ b/src/multicolvar/VolumeSubcell.cpp
@@ -22,18 +22,41 @@
#include "core/ActionRegister.h"
#include "ActionVolume.h"
-//+PLUMEDOC GENERIC SUBCELL
+//+PLUMEDOC MCOLVARF SUBCELL
/*
-This action is used in conjunction with \ref region keyword. It is used to specify that
-a particular quantity is to be averaged for the atoms in a particular part of the cell.
-
+This quantity can be used to calculate functions of the distribution of collective
+variables for the atoms that lie in a particular, user-specified part of of the cell.
+
+Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three
+dimensional space. For example, if we have the coordination numbers for all the atoms in the
+system each coordination number can be assumed to lie on the position of the central atom.
+Because each base quantity can be assigned to a particular point in space we can calculate functions of the
+distribution of base quantities in a particular part of the box by using:
+
+\f[
+\overline{s}_{\tau} = \frac{ \sum_i f(s_i) w(x_i,y_i,z_i) }{ \sum_i w(x_i,y_i,z_i) }
+\f]
+
+where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (x_i,y_i,z_i)\f$.
+The function \f$ w(x_i,y_i,z_i) \f$ measures whether or not the system is in the subregion of interest. It
+is equal to:
+
+\f[
+w(x_i,y_i,z_i) = \int_{xl}^{xu} \int_{yl}^{yu} \int_{zl}^{zu} \textrm{d}x\textrm{d}y\textrm{d}z K\left( \frac{x - x_i}{\sigma} \right)K\left( \frac{y - y_i}{\sigma} \right)K\left( \frac{z - z_i}{\sigma} \right)
+\f]
+
+where \f$K\f$ is one of the kernel functions described on \ref histogrambead and \f$\sigma\f$ is a bandwidth parameter.
+The function \f$(s_i)\f$ can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars.
+
+When REGION is used with the \ref DENSITY action the number of atoms in the specified region is calculated
+
\par Examples
The following commands tell plumed to calculate the average coordination number for the atoms
-that have x (in fractional coordinates) less than 0.5. The final value will be labeled r1_av.
+that have x (in fractional coordinates) less than 0.5. The final value will be labeled s.mean.
\verbatim
COORDINATIONNUMBER SPECIES=1-100 R_0=1.0 LABEL=c
-SUBCELL ARG=c XLOWER=0.0 XUPPER=0.5 SIGMA=0.1 LABEL=s
+SUBCELL ARG=c XLOWER=0.0 XUPPER=0.5 SIGMA=0.1 MEAN LABEL=s
\endverbatim
*/
diff --git a/user-doc/Colvar.txt b/user-doc/Colvar.txt
index 0ab587b8a..2b7dec450 100644
--- a/user-doc/Colvar.txt
+++ b/user-doc/Colvar.txt
@@ -77,12 +77,57 @@ The following list contains all the colvars that are currently implemented in pl
@COLVAR@
-Often you do not need one of these collective variables directly. 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. Descriptions as to how to use plumed to calculate these kinds of CVs are given
+\section mcolv MultiColvar Documentation
+
+Often you do not need one of the collective variables described in the previous section. 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
+these sort of collective variables using so-called MultiColvars. MultiColvars are named in this way because a single
+plumed action can be used to calculate a number of different collective variables. For instance the \ref DISTANCES
+action can be used to calculate the minimum distance, the number of distances less than a certain value, the number of
+distances within a certain range... Descriptions as to how to use plumed to calculate these kinds of CVs are given
below:
-@MCOLVAR@
+@MCOLVAR@
+
+To instruct plumed to calculate a multicolvar you give an instruction that looks something like this:
+
+\verbatim
+NAME <atoms involved> <parameters> <what am I calculating> TOL=0.001 LABEL=label
+\endverbatim
+
+Oftentimes the simplest way to specify the atoms involved is to use multiple instances of the ATOMS keyword
+i.e. ATOMS1, ATOMS2, ATOMS3,... Separate instances of the quantity specified by NAME are then calculated for
+each of the sets of atoms. For example if the command issued contains the following:
+
+\verbatim
+DISTANCES ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6
+\endverbatim
+
+The distances between atoms 1 and 2, atoms 3 and 4, and atoms 5 and 6 are calculated. Obviously, generating
+this sort of input is rather tedious so short cuts are also available many of the collective variables.
+These are described on the manual pages for the actions.
+
+After specifying the atoms involved you sometimes need to specify some parameters that required in the
+calculation. For instance, for \ref COORDINATIONNUMBERS - the number of atoms in the first coordination
+sphere of each of the atoms in the system - you need to specify the parameters for a \ref switchingfunction
+that will tell us whether or not an atom is in the first coordination sphere. Details as to how to do this
+are provided on the manual pages.
+
+One of the most important keywords for multicolvars is the TOL keyword. This specifies that terms in sums
+that contribute less than a certain value can be ignored. In addition, it is assumed that the derivative
+with respect to these terms are essentially zero. By increasing the TOL parameter you can increase the speed
+of the calculation. Be aware, however, that this increase in speed is only possible because you are lowering the
+accuracy with which you are computing the quantity of interest.
+
+Once you have specified the base quanties that are to be calculated from the atoms involved and any parameters
+you need to specify what function of these base quanties is to be calculated. For most multicolvars you can calculate
+the minimum, the number less than a target value, the number within a certain range, the number more than a target
+value and the average value directly. In addition, the following more complex functions of the distribution of values
+can be computed:
+
+@MCOLVARF@
*/
diff --git a/user-doc/extract b/user-doc/extract
index 39eb7b713..15fae1c77 100755
--- a/user-doc/extract
+++ b/user-doc/extract
@@ -51,7 +51,7 @@ awk 'BEGIN{gfile="automatic/GLOSSARY1.list"; dfile="automatic/DICTIONARY1.list";
if(inside==3){ printf "%s", $0 > dfile; }
}
if($1=="//+PLUMEDOC"){
- if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="MCOLVAR" || $2=="FUNCTION" || $2=="ANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
+ if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="MCOLVAR" || $2=="MCOLVARF" || $2=="FUNCTION" || $2=="ANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
lfile="automatic/"$2".list"
print "<tr> <td width=5%> \\subpage ", $3,"</td> <td>" > lfile
@@ -150,6 +150,11 @@ cat $file.txt |
echo "<table align=center frame=void width=95%% cellpadding=5%%>"
cat automatic/MCOLVAR.list
echo "</table>"
+ elif [ "$LINE" = "@MCOLVARF@" ]
+ then
+ echo "<table align=center frame=void width=95%% cellpadding=5%%>"
+ cat automatic/MCOLVARF.list
+ echo "</table>"
elif [ "$LINE" = "@ANALYSIS@" ]
then
echo "<table align=center frame=void width=95%% cellpadding=5%%>"
--
GitLab