From 87c233f1d60a4097b149e202bf8fa83e5dbbf272 Mon Sep 17 00:00:00 2001
From: Gareth Tribello <gareth.tribello@gmail.com>
Date: Sat, 30 Jul 2016 21:48:47 +0100
Subject: [PATCH] Added documentation to MTRANSFORMS, MFILTERS and
OUTPUT_CLUSTER
[makedoc]
---
src/adjmat/OutputCluster.cpp | 25 +++++++
src/multicolvar/FilterBetween.cpp | 101 ++++++++++++++++++++++++++++-
src/multicolvar/FilterLessThan.cpp | 74 +++++++++++++++++++++
src/multicolvar/FilterMoreThan.cpp | 91 ++++++++++++++++++++++++++
user-doc/Colvar.txt | 7 ++
user-doc/extract | 5 +-
6 files changed, 300 insertions(+), 3 deletions(-)
diff --git a/src/adjmat/OutputCluster.cpp b/src/adjmat/OutputCluster.cpp
index 6f34cc977..f99fcb2b8 100644
--- a/src/adjmat/OutputCluster.cpp
+++ b/src/adjmat/OutputCluster.cpp
@@ -30,6 +30,31 @@
/*
Output the indices of the atoms in one of the clusters identified by a clustering object
+This action provides one way of getting output from a \ref DFSCLUSTERING calculation.
+The output in question here is either
+
+- a file that contains a list of the atom indices that form part of one of the clusters that was identified using \ref DFSCLUSTERING
+- an xyz file containing the positions of the atoms in one of the the clusters that was identified using \ref DFSCLUSTERING
+
+Notice also that if you choose to output an xyz file you can ask PLUMED to try to reconstruct the cluster
+taking the periodic boundary conditions into account by using the MAKE_WHOLE flag.
+
+\par Examples
+
+The input shown below identifies those atoms with a coordination number less than 13
+and then constructs a contact matrix that describes the connectivity between the atoms
+that satisfy this criteria. The DFS algorithm is then used to find the connected components
+in this matrix and the indices of the atoms in the largest connected component are then output
+to a file.
+
+\verbatim
+c1: COORDINATIONNUMBER SPECIES=1-1996 SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
+cf: MFILTER_LESS DATA=c1 SWITCH={CUBIC D_0=13 D_MAX=13.5}
+mat: CONTACT_MATRIX ATOMS=cf SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
+dfs: DFSCLUSTERING MATRIX=mat
+OUTPUT_CLUSTER CLUSTERS=dfs CLUSTER=1 FILE=dfs.dat
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/multicolvar/FilterBetween.cpp b/src/multicolvar/FilterBetween.cpp
index d1f2e4941..29a163a5e 100644
--- a/src/multicolvar/FilterBetween.cpp
+++ b/src/multicolvar/FilterBetween.cpp
@@ -23,13 +23,112 @@
#include "tools/HistogramBead.h"
#include "MultiColvarFilter.h"
+//+PLUMEDOC MTRANSFORMS MTRANSFORM_BETWEEN
+/*
+This action can be useed to transform the colvar values calculated by a multicolvar using a \ref histogrambead
+
+In this action each colvar, \f$s_i\f$, calculated by multicolvar is transformed by a \ref histogrambead function that
+is equal to one if the colvar is within a certain range and which is equal to zero otherwise. In other words, we
+compute:
+
+\f[
+f_i = \int_a^b K\left( \frac{s-s_i}{w} \right)
+\f]
+
+where \f$a, b\f$ and \f$w\f$ are parameters.
+
+It is important to understand the distinction between what is done here and what is done by \ref MFILTER_BETWEEN.
+In \ref MFILTER_BETWEEN a weight, \f$w_i\f$ for the colvar is calculated using the \ref histogrambead. If one calculates the
+MEAN for \ref MFILTER_BETWEEN one is thus calculating:
+
+\f[
+\mu = \frac{ \sum_i f_i s_i }{ \sum_i f_i}
+\f]
+
+In this action by contrast the colvar is being transformed by the \ref histogram bead. If one thus calculates a MEAN for
+thia action one computes:
+
+\f[
+\mu = \frac{ \sum_{i=1}^N f_i }{ N }
+\f]
+
+In other words, you are calculating the mean for the transformed colvar.
+
+\par Examples
+
+The following input gives an example of how a MTRANSFORM_BETWEEN action can be used to duplicate
+functionality that is elsehwere in PLUMED.
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ LABEL=d1
+... DISTANCES
+MTRANSFORM_BETWEEN DATA=d1 LOWER=1.0 UPPER=2.0 SMEAR=0.5
+\endverbatim
+
+In this case you can achieve the same result by using:
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ BETWEEN={GAUSSIAN LOWER=1.0 UPPER=2.0}
+... DISTANCES
+\endverbatim
+(see \ref DISTANCES)
+
+The advantage of MTRANSFORM_BETWEEN comes, however, if you want to use transformed colvars as input
+for \ref MULTICOLVARDENS
+
+*/
+//+ENDPLUMEDOC
+
//+PLUMEDOC MFILTERS MFILTER_BETWEEN
/*
-This action can be used to filter the distribution of colvar values in a multicolvar
+This action can be used to filter the colvar values calculated by a multicolvar
so that one can compute the mean and so on for only those multicolvars within a certain range.
+This action can be used to create a dynamic group of atom based on the value of a multicolvar.
+In this action a multicolvar is within the dynamic group if its value lies in a particular range.
+In practise a weight, \f$w_i\f$ is ascribed to each colvar, \f$s_i\f$ calculated by a multicolvar
+and this weight measures the degree to which a colvar is a member of the group. This weight is
+calculated using a \ref histogrambead so it is given by:
+
+\f[
+w_i = \int_a^b K\left( \frac{s - s_i}{w} \right)
+\f]
+
+where \f$a, b\f$ and \f$w\f$ are parameters. If one calculates a function of the set of multicolvars
+these weights are included in the calculation. As such if one calculates the MEAN, $f\mu\f$ of a filtered
+multicolvar what is computed is the following:
+
+\f[
+\mu = \frac{ \sum_i w_i s_i }{ \sum_i w_i}
+\f]
+
+One is thus calculating the mean for those colvars that are within the range of interest.
+
\par Examples
+The example shown below calculates the mean for those distances that are between 0 and 3 nm in length
+
+\verbatim
+DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
+MFILTER_BETWEEN DATA=d1 LOWER=0 UPPER=3.0 SMEAR=0.0001 MEAN LABEL=d4
+\endverbatim
+
+More complicated things can be done by using the label of a filter as input to a new multicolvar as shown
+in the example below. Here the coordination numbers of all atoms are computed. The atoms with a coordination
+number between 4 and 6 are then identified using the filter. This reduced list of atoms is then used as input
+to a second coordination number calculation. This second coordination number thus measures the number of atoms
+4-6 coordinated atoms each of the 4-6 coordination atoms is bound to.
+
+\verbatim
+c1: COORDINATIONNUMBER SPECIES=1-150 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
+cf: MFILTER_BETWEEN DATA=c1 LOWER=4 UPPER=6 SMEAR=0.5 LOWMEM
+c2: COORDINATIONNUMBER SPECIES=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0} MORE_THAN={RATIONAL D_0=2.0 R_0=0.1}
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/multicolvar/FilterLessThan.cpp b/src/multicolvar/FilterLessThan.cpp
index 29f05ba8d..86f178b92 100644
--- a/src/multicolvar/FilterLessThan.cpp
+++ b/src/multicolvar/FilterLessThan.cpp
@@ -23,13 +23,87 @@
#include "tools/SwitchingFunction.h"
#include "MultiColvarFilter.h"
+//+PLUMEDOC MTRANSFORMS MTRANSFORM_LESS
+/*
+This action can be useed to transform the colvar values calculated by a multicolvar using a \ref switchingfunction
+
+In this action each colvar, \f$s_i\f$, calculated by multicolvar is transformed by a \ref switchingfunction function that
+is equal to one if the colvar is less than a certain target value and which is equal to zero otherwise.
+It is important to understand the distinction between what is done here and what is done by \ref MFILTER_LESS.
+In \ref MFILTER_LESS a weight, \f$w_i\f$ for the colvar is calculated using the \ref switchingfunction. If one calculates the
+MEAN for \ref MFILTER_LESS one is thus calculating:
+
+\f[
+\mu = \frac{ \sum_i \sigma(s_i) s_i }{\sum_i \simga(s_i) }
+\f]
+
+where \f$\sigma\f$ is the \ref switchingfunction. In this action by contrast the colvar is being transformed by
+the \ref switchingfunction. If one thus calculates a MEAN for thia action one computes:
+
+\f[
+\mu = \frac{ \sum_{i=1}^N \simga(s_i) }{ N }
+\f]
+
+In other words, you are calculating the mean for the transformed colvar.
+
+\par Examples
+
+The following input gives an example of how a MTRANSFORM_LESS action can be used to duplicate
+functionality that is elsehwere in PLUMED.
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ LABEL=d1
+... DISTANCES
+MTRANSFORM_LESS DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001}
+\endverbatim
+
+In this case you can achieve the same result by using:
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ LESS_THAN={GAUSSIAN D_0=1.5 R_0=0.00001}
+... DISTANCES
+\endverbatim
+(see \ref DISTANCES)
+
+The advantage of MTRANSFORM_LESS comes, however, if you want to use transformed colvars as input
+for \ref MULTICOLVARDENS
+
+*/
+//+ENDPLUMEDOC
+
//+PLUMEDOC MFILTERS MFILTER_LESS
/*
This action can be used to filter the distribution of colvar values in a multicolvar
so that one can compute the mean and so on for only those multicolvars less than a tolerance.
+This action can be used to create a dynamic group of atom based on the value of a multicolvar.
+In this action a multicolvar is within the dynamic group if its value is less than a target.
+In practise a weight, \f$w_i\f$ is ascribed to each colvar, \f$s_i\f$ calculated by a multicolvar
+and this weight measures the degree to which a colvar is a member of the group. This weight is a number
+between 0 and 1 that is calculated using a \ref switchingfunction , \f$\sigma\f$.
+If one calculates a function of the set of multicolvars
+these weights are included in the calculation. As such if one calculates the MEAN, $f\mu\f$ of a filtered
+multicolvar what is computed is the following:
+
+\f[
+\mu = \frac{ \sum_i w_i s_i }{ \sum_i w_i}
+\f]
+
+One is thus calculating the mean for those colvars that are less than the target.
+
\par Examples
+The example shown below calculates the mean for those distances that less than 1.5 nm in length
+
+\verbatim
+DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
+MFILTER_LESS DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001} MEAN LABEL=d4
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/multicolvar/FilterMoreThan.cpp b/src/multicolvar/FilterMoreThan.cpp
index 1eb01b351..8d85f1b78 100644
--- a/src/multicolvar/FilterMoreThan.cpp
+++ b/src/multicolvar/FilterMoreThan.cpp
@@ -23,13 +23,104 @@
#include "tools/SwitchingFunction.h"
#include "MultiColvarFilter.h"
+//+PLUMEDOC MTRANSFORMS MTRANSFORM_MORE
+/*
+This action can be useed to transform the colvar values calculated by a multicolvar using one minus a \ref switchingfunction
+
+In this action each colvar, \f$s_i\f$, calculated by multicolvar is transformed by a \ref switchingfunction function that
+is equal to one if the colvar is greater than a certain target value and which is equal to zero otherwise.
+It is important to understand the distinction between what is done here and what is done by \ref MFILTER_MORE.
+In \ref MFILTER_MORE a weight, \f$w_i\f$ for the colvar is calculated using the \ref histogrambead. If one calculates the
+MEAN for \ref MFILTER_MORE one is thus calculating:
+
+\f[
+\mu = \frac{ \sum_i [1 - \sigma(s_i) ] s_i }{\sum_i [1 - \sigma(s_i)] }
+\f]
+
+where $\sigma$ is the \ref switchingfunction. In this action by contrast the colvar is being transformed by the \ref switchingfunction.
+If one thus calculates a MEAN for this action one computes:
+
+\f[
+\mu = \frac{ \sum_{i=1}^N 1 - \sigma(s_i) }{ N }
+\f]
+
+In other words, you are calculating the mean for the transformed colvar.
+
+\par Examples
+
+The following input gives an example of how a MTRANSFORM_MORE action can be used to duplicate
+functionality that is elsehwere in PLUMED.
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ LABEL=d1
+... DISTANCES
+MTRANSFORM_MORE DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001}
+\endverbatim
+
+In this case you can achieve the same result by using:
+
+\verbatim
+DISTANCES ...
+ GROUPA=1-10 GROUPB=11-20
+ MORE_THAN={GAUSSIAN D_0=1.5 R_0=0.00001}
+... DISTANCES
+\endverbatim
+(see \ref DISTANCES)
+
+The advantage of MTRANSFORM_MORE comes, however, if you want to use transformed colvars as input
+for \ref MULTICOLVARDENS
+
+*/
+//+ENDPLUMEDOC
+
//+PLUMEDOC MFILTERS MFILTER_MORE
/*
This action can be used to filter the distribution of colvar values in a multicolvar
so that one can compute the mean and so on for only those multicolvars more than a tolerance.
+This action can be used to create a dynamic group of atom based on the value of a multicolvar.
+In this action a multicolvar is within the dynamic group if its value is greater than a target.
+In practise a weight, \f$w_i\f$ is ascribed to each colvar, \f$s_i\f$ calculated by a multicolvar
+and this weight measures the degree to which a colvar is a member of the group. This weight is
+calculated using a \ref switchingfunction , \f$\sigma\f$ so it is given by:
+
+\f[
+w_i = 1 - \sigma(s_i)
+\f]
+
+If one calculates a function of the set of multicolvars
+these weights are included in the calculation. As such if one calculates the MEAN, $f\mu\f$ of a filtered
+multicolvar what is computed is the following:
+
+\f[
+\mu = \frac{ \sum_i w_i s_i }{ \sum_i w_i}
+\f]
+
+One is thus calculating the mean for those colvars that are greater than the target.
+
\par Examples
+The example shown below calculates the mean for those distances that greater than 1.5 nm in length
+
+\verbatim
+DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
+MFILTER_MORE DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001} MEAN LABEL=d4
+\endverbatim
+
+More complicated things can be done by using the label of a filter as input to a new multicolvar as shown
+in the example below. Here the coordination numbers of all atoms are computed. The atoms with a coordination
+number greater than 2 are then identified using the filter. This reduced list of atoms is then used as input
+to a second coordination number calculation. This second coordination number thus measures the number of
+two-coordinated atoms that each of the two-coordinated atoms is bound to.
+
+\verbatim
+1: COORDINATIONNUMBER SPECIES=1-150 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
+cf: MFILTER_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
+c2: COORDINATIONNUMBER SPECIES=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0} MORE_THAN={RATIONAL D_0=2.0 R_0=0.1}
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/user-doc/Colvar.txt b/user-doc/Colvar.txt
index 929fde7f2..9a8f7215b 100644
--- a/user-doc/Colvar.txt
+++ b/user-doc/Colvar.txt
@@ -148,6 +148,13 @@ taking dot products of vectors on adjacent atoms as described below:
@MCOLVARF@
+The final set of functions that you can apply on multicolvars are functions that transform all the colvars calculated using a
+multicolvar using a function. This can be useful if you are calculating some complicated derived quantity of some simpler
+quantity. It is also useful if you are calculating a Willard Chandler surface or a histogram. The actions that you can use to
+perform these transforms are:
+
+@MTRANSFORMS@
+
\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
diff --git a/user-doc/extract b/user-doc/extract
index 04dbae63f..f07e4794f 100755
--- a/user-doc/extract
+++ b/user-doc/extract
@@ -89,7 +89,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=="MFILTERS" || $2=="VOLUMES" || $2=="MCOLVARF" || $2=="MCOLVARB" || $2=="MATRIX" || $2=="MATRIXF" || $2=="CONCOMP" || $2=="FUNCTION" || $2=="GRIDCALC" || $2=="REWEIGHTING"|| $2=="PRINTANALYSIS" || $2=="DIMRED" || $2=="GRIDANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
+ if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="MCOLVAR" || $2=="DCOLVAR"|| $2=="MFILTERS" || $2=="MTRANSFORMS" || $2=="VOLUMES" || $2=="MCOLVARF" || $2=="MCOLVARB" || $2=="MATRIX" || $2=="MATRIXF" || $2=="CONCOMP" || $2=="FUNCTION" || $2=="GRIDCALC" || $2=="REWEIGHTING"|| $2=="PRINTANALYSIS" || $2=="DIMRED" || $2=="GRIDANALYSIS" || $2=="BIAS" || $2=="GENERIC" || $2=="VATOM" || $2=="TOOLS" ){
if(lfile!="") close(lfile)
lfile="automatic/"$2".list"
@@ -234,7 +234,7 @@ done
sed -ie 's/<b> --/<b> \\c \\-\\-/g' automatic/*.txt
rm automatic/*.txte
-for file in COLVAR MCOLVAR MFILTERS VOLUMES DCOLVAR MCOLVARF MCOLVARB MATRIX MATRIXF CONCOMP REWEIGHTING PRINTANALYSIS BIAS GLOSSARY \
+for file in COLVAR MCOLVAR MFILTERS MTRANSFORMS VOLUMES DCOLVAR MCOLVARF MCOLVARB MATRIX MATRIXF CONCOMP REWEIGHTING PRINTANALYSIS BIAS GLOSSARY \
DICTIONARY TUTORIALS WEBSITES FUNCTION TOPOLOGY VATOM GRIDCALC GRIDANALYSIS DIMRED \
TOOLS
do
@@ -266,6 +266,7 @@ cat $file.txt |
/^ *@MCOLVAR@ *$/r automatic/MCOLVAR.list
/^ *@DCOLVAR@ *$/r automatic/DCOLVAR.list
/^ *@MFILTERS@ *$/r automatic/MFILTERS.list
+ /^ *@MTRANSFORMS@ *$/r automatic/MTRANSFORMS.list
/^ *@VOLUMES@ *$/r automatic/VOLUMES.list
/^ *@MCOLVARF@ *$/r automatic/MCOLVARF.list
/^ *@MCOLVARB@ *$/r automatic/MCOLVARB.list
--
GitLab