From db8993cb96a2cad3807eec8c32c92803e1707381 Mon Sep 17 00:00:00 2001
From: Gareth Tribello <gareth.tribello@gmail.com>
Date: Tue, 29 Apr 2014 14:17:53 +0100
Subject: [PATCH] Added documentation for Steinhardt parameters and related
---
src/crystallization/Q3.cpp | 128 +++++++++++++++++++++++++-
src/crystallization/Q4.cpp | 125 ++++++++++++++++++++++++-
src/crystallization/Q6.cpp | 125 ++++++++++++++++++++++++-
src/crystallization/VectorAverage.cpp | 22 ++++-
src/multicolvar/LocalAverage.cpp | 45 +++++++++
src/multicolvar/NumberOfLinks.cpp | 23 ++++-
user-doc/bibliography.bib | 13 +++
7 files changed, 475 insertions(+), 6 deletions(-)
diff --git a/src/crystallization/Q3.cpp b/src/crystallization/Q3.cpp
index 322b6cb14..5279ceb6f 100644
--- a/src/crystallization/Q3.cpp
+++ b/src/crystallization/Q3.cpp
@@ -25,22 +25,146 @@
//+PLUMEDOC MCOLVAR Q3
/*
-Calculate 3th order Steinhardt parameters.
+Calculate 3rd order Steinhardt parameters.
+
+The 3rd order Steinhardt parameters allow us to measure the degree to which the first coordination shell
+around an atom is ordered. The Steinhardt parameter for atom, \f$i\f$ is complex vector whose components are
+calculated using the following formula:
+
+\f[
+q_{3m}(i) = \frac{\sum_j \sigma( r_{ij} ) Y_{3m}(\mathbf{r}_{ij}) }{\sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$Y_{3m}\f$ is one of the 3rd order spherical harmonics so \f$m\f$ is a number that runs from \f$-3\f$ to
+\f$+3\f$. The function \f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between
+atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set so that it the function is equal to one
+when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise.
+
+The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways. The
+simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the above vector i.e.
+
+\f[
+Q_3(i) = \sqrt{ \sum_{m=-3}^3 q_{3m}(i)^{*} q_{3m}(i) }
+\f]
+
+This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered. Furthermore, when
+the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this colvar it is the distribution of these normed quantities
+that is investigated.
+
+Other measures of order can be taken by averaging the components of the individual \f$q_3\f$ vectors individually or by taking dot products of
+the \f$q_{3}\f$ vectors on adjacent atoms. More information on these variables can be found in the documentation for \ref LOCAL_Q3,
+\ref LOCAL_AVERAGE, \ref AVERAGE_VECTOR and \ref NLINKS.
\par Examples
+The following command calculates the average Q3 parameter for the 64 atoms in a box of Lennard Jones and prints this
+quantity to a file called colvar:
+
+\verbatim
+Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q3
+PRINT ARG=q3.mean FILE=colvar
+\endverbatim
+
+The following command calculates the histogram of Q3 parameters for the 64 atoms in a box of Lennard Jones and prints these
+quantities to a file called colvar:
+
+\verbatim
+Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q3
+PRINT ARG=q3.* FILE=colvar
+\endverbatim
+
+The following command could be used to measure the Q3 paramters that describe the arrangement of chlorine ions around the
+sodium atoms in NaCl. The imagined system here is composed of 64 NaCl formula units and the atoms are arranged in the input
+with the 64 Na\f$^+\f$ ions followed by the 64 Cl\f$-\f$ ions. Once again the average Q3 paramter is calculated and output to a
+file called colvar
+
+\verbatim
+Q3 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q3
+PRINT ARG=q3.mean FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
//+PLUMEDOC MCOLVARF LOCAL_Q3
/*
-Calculate 3th order Steinhardt parameters.
+Calculate the local degree of order around an atoms by taking the average dot product between the \f$q_3\f$ vector on the central atom and the \f$q_3\f$ vector
+on the atoms in the first coordination sphere.
+
+The \ref Q3 command allows one to calculate one complex vectors for each of the atoms in your system that describe the degree of order in the coordination sphere
+around a particular atom. The difficulty with these vectors comes when combining the order parameters from all of the individual atoms/molecules so as to get a
+measure of the global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter - can be problematic. If one is
+examining nucleation say only the order parameters for those atoms in the nucleus will change significantly when the nucleus forms. The order parameters for the
+atoms in the surrounding liquid will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of solution/melt any
+change in the average order parameter will be negligible. Substantial changes in the value of this average can be observed in simulations of nucleation but only
+because the number of atoms is relatively small.
+
+When the average \ref Q3 parameter is used to bias the dynamics a problems
+can occur. These averaged coordinates cannot distinguish between the correct,
+single-nucleus pathway and a concerted pathway in which all the atoms rearrange
+themselves into their solid-like configuration simultaneously. This second type
+of pathway would be impossible in reality because there is a large entropic
+barrier that prevents concerted processes like this from happening. However,
+in the finite sized systems that are commonly simulated this barrier is reduced
+substantially. As a result in simulations where average Steinhardt parameters
+are biased there are often quite dramatic system size effects
+
+If one wants to simulate nucleation using some form on
+biased dynamics what is really required is an order parameter that measures:
+
+- Whether or not the coordination spheres around atoms are ordered
+- Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
+
+\ref LOCAL_AVERAGE and \ref NLINKS are variables that can be combined with the Steinhardt parameteters allow to calculate variables that satisfy these requirements.
+LOCAL_Q3 is another variable that can be used in these sorts of calculations. The LOCAL_Q3 parameter for a particular atom is a number that measures the extent to
+which the orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does this by calculating the following
+quantity for each of the atoms in the system:
+
+\f[
+ s_i = \frac{ \sum_j \sigma( r_{ij} ) \sum_{m=-3}^3 q_{3m}^{*}(i)q_{3m}(j) }{ \sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$q_{3m}(i)\f$ and \f$q_{3m}(j)\f$ are the 3rd order Steinhardt vectors calculated for atom \f$i\f$ and atom \f$j\f$ respectively and the asterix denotes complex
+conjugation. The function
+\f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set
+so that it the function is equal to one when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise. The sum in the numerator
+of this expression is the dot product of the Steinhardt parameters for atoms \f$i\f$ and \f$j\f$ and thus measures the degree to which the orientations of these
+adjacent atoms is correlated.
\par Examples
+The following command calculates the average value of the LOCAL_Q3 parameter for the 64 Lennard Jones atoms in the system under study and prints this
+quantity to a file called colvar.
+
+\verbatim
+Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
+LOCAL_Q3 ARG=q3 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq3
+PRINT ARG=lq3.mean FILE=colvar
+\endverbatim
+
+The following input calculates the distribution of LOCAL_Q3 parameters at any given time and outputs this information to a file.
+
+\verbatim
+Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
+LOCAL_Q3 ARG=q3 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=lq3
+PRINT ARG=lq3.* FILE=colvar
+\endverbatim
+
+The following calculates the LOCAL_Q3 parameters for atoms 1-5 only. For each of these atoms comparisons of the geometry of the coordination sphere
+are done with those of all the other atoms in the system. The final quantity is the average and is outputted to a file
+
+\verbatim
+Q3 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q3a
+Q3 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q3b
+
+LOCAL_Q3 ARG=q3a,q3b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w3
+PRINT ARG=w3.* FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
+
namespace PLMD {
namespace crystallization {
diff --git a/src/crystallization/Q4.cpp b/src/crystallization/Q4.cpp
index cdc7b8222..6aba434cd 100644
--- a/src/crystallization/Q4.cpp
+++ b/src/crystallization/Q4.cpp
@@ -27,17 +27,140 @@
/*
Calculate 4th order Steinhardt parameters.
+The 4th order Steinhardt parameters allow us to measure the degree to which the first coordination shell
+around an atom is ordered. The Steinhardt parameter for atom, \f$i\f$ is complex vector whose components are
+calculated using the following formula:
+
+\f[
+q_{4m}(i) = \frac{\sum_j \sigma( r_{ij} ) Y_{4m}(\mathbf{r}_{ij}) }{\sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$Y_{4m}\f$ is one of the 4th order spherical harmonics so \f$m\f$ is a number that runs from \f$-4\f$ to
+\f$+4\f$. The function \f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between
+atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set so that it the function is equal to one
+when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise.
+
+The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways. The
+simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the above vector i.e.
+
+\f[
+Q_4(i) = \sqrt{ \sum_{m=-4}^4 q_{4m}(i)^{*} q_{4m}(i) }
+\f]
+
+This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered. Furthermore, when
+the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this colvar it is the distribution of these normed quantities
+that is investigated.
+
+Other measures of order can be taken by averaging the components of the individual \f$q_4\f$ vectors individually or by taking dot products of
+the \f$q_{4}\f$ vectors on adjacent atoms. More information on these variables can be found in the documentation for \ref LOCAL_Q4,
+\ref LOCAL_AVERAGE, \ref AVERAGE_VECTOR and \ref NLINKS.
+
\par Examples
+The following command calculates the average Q4 parameter for the 64 atoms in a box of Lennard Jones and prints this
+quantity to a file called colvar:
+
+\verbatim
+Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q4
+PRINT ARG=q4.mean FILE=colvar
+\endverbatim
+
+The following command calculates the histogram of Q4 parameters for the 64 atoms in a box of Lennard Jones and prints these
+quantities to a file called colvar:
+
+\verbatim
+Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q4
+PRINT ARG=q4.* FILE=colvar
+\endverbatim
+
+The following command could be used to measure the Q4 paramters that describe the arrangement of chlorine ions around the
+sodium atoms in NaCl. The imagined system here is composed of 64 NaCl formula units and the atoms are arranged in the input
+with the 64 Na\f$^+\f$ ions followed by the 64 Cl\f$-\f$ ions. Once again the average Q4 paramter is calculated and output to a
+file called colvar
+
+\verbatim
+Q4 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q4
+PRINT ARG=q4.mean FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
//+PLUMEDOC MCOLVARF LOCAL_Q4
/*
-Calculate 4th order Steinhardt parameters.
+Calculate the local degree of order around an atoms by taking the average dot product between the \f$q_4\f$ vector on the central atom and the \f$q_4\f$ vector
+on the atoms in the first coordination sphere.
+
+The \ref Q4 command allows one to calculate one complex vectors for each of the atoms in your system that describe the degree of order in the coordination sphere
+around a particular atom. The difficulty with these vectors comes when combining the order parameters from all of the individual atoms/molecules so as to get a
+measure of the global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter - can be problematic. If one is
+examining nucleation say only the order parameters for those atoms in the nucleus will change significantly when the nucleus forms. The order parameters for the
+atoms in the surrounding liquid will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of solution/melt any
+change in the average order parameter will be negligible. Substantial changes in the value of this average can be observed in simulations of nucleation but only
+because the number of atoms is relatively small.
+
+When the average \ref Q4 parameter is used to bias the dynamics a problems
+can occur. These averaged coordinates cannot distinguish between the correct,
+single-nucleus pathway and a concerted pathway in which all the atoms rearrange
+themselves into their solid-like configuration simultaneously. This second type
+of pathway would be impossible in reality because there is a large entropic
+barrier that prevents concerted processes like this from happening. However,
+in the finite sized systems that are commonly simulated this barrier is reduced
+substantially. As a result in simulations where average Steinhardt parameters
+are biased there are often quite dramatic system size effects
+
+If one wants to simulate nucleation using some form on
+biased dynamics what is really required is an order parameter that measures:
+
+- Whether or not the coordination spheres around atoms are ordered
+- Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
+
+\ref LOCAL_AVERAGE and \ref NLINKS are variables that can be combined with the Steinhardt parameteters allow to calculate variables that satisfy these requirements.
+LOCAL_Q4 is another variable that can be used in these sorts of calculations. The LOCAL_Q4 parameter for a particular atom is a number that measures the extent to
+which the orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does this by calculating the following
+quantity for each of the atoms in the system:
+
+\f[
+ s_i = \frac{ \sum_j \sigma( r_{ij} ) \sum_{m=-4}^4 q_{4m}^{*}(i)q_{4m}(j) }{ \sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$q_{4m}(i)\f$ and \f$q_{4m}(j)\f$ are the 4th order Steinhardt vectors calculated for atom \f$i\f$ and atom \f$j\f$ respectively and the asterix denotes
+complex conjugation. The function
+\f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set
+so that it the function is equal to one when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise. The sum in the numerator
+of this expression is the dot product of the Steinhardt parameters for atoms \f$i\f$ and \f$j\f$ and thus measures the degree to which the orientations of these
+adjacent atoms is correlated.
\par Examples
+The following command calculates the average value of the LOCAL_Q4 parameter for the 64 Lennard Jones atoms in the system under study and prints this
+quantity to a file called colvar.
+
+\verbatim
+Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
+LOCAL_Q4 ARG=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq4
+PRINT ARG=lq4.mean FILE=colvar
+\endverbatim
+
+The following input calculates the distribution of LOCAL_Q4 parameters at any given time and outputs this information to a file.
+
+\verbatim
+Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
+LOCAL_Q4 ARG=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=lq4
+PRINT ARG=lq4.* FILE=colvar
+\endverbatim
+
+The following calculates the LOCAL_Q4 parameters for atoms 1-5 only. For each of these atoms comparisons of the geometry of the coordination sphere
+are done with those of all the other atoms in the system. The final quantity is the average and is outputted to a file
+
+\verbatim
+Q4 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q4a
+Q4 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q4b
+
+LOCAL_Q4 ARG=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
+PRINT ARG=w4.* FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/crystallization/Q6.cpp b/src/crystallization/Q6.cpp
index 90b5f7001..89df0268b 100644
--- a/src/crystallization/Q6.cpp
+++ b/src/crystallization/Q6.cpp
@@ -27,17 +27,140 @@
/*
Calculate 6th order Steinhardt parameters.
+The 6th order Steinhardt parameters allow us to measure the degree to which the first coordination shell
+around an atom is ordered. The Steinhardt parameter for atom, \f$i\f$ is complex vector whose components are
+calculated using the following formula:
+
+\f[
+q_{6m}(i) = \frac{\sum_j \sigma( r_{ij} ) Y_{6m}(\mathbf{r}_{ij}) }{\sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$Y_{6m}\f$ is one of the 6th order spherical harmonics so \f$m\f$ is a number that runs from \f$-6\f$ to
+\f$+6\f$. The function \f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between
+atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set so that it the function is equal to one
+when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise.
+
+The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways. The
+simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the above vector i.e.
+
+\f[
+Q_6(i) = \sqrt{ \sum_{m=-6}^6 q_{6m}(i)^{*} q_{6m}(i) }
+\f]
+
+This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered. Furthermore, when
+the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this colvar it is the distribution of these normed quantities
+that is investigated.
+
+Other measures of order can be taken by averaging the components of the individual \f$q_6\f$ vectors individually or by taking dot products of
+the \f$q_{6}\f$ vectors on adjacent atoms. More information on these variables can be found in the documentation for \ref LOCAL_Q6,
+\ref LOCAL_AVERAGE, \ref AVERAGE_VECTOR and \ref NLINKS.
+
\par Examples
+The following command calculates the average Q6 parameter for the 64 atoms in a box of Lennard Jones and prints this
+quantity to a file called colvar:
+
+\verbatim
+Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q6
+PRINT ARG=q6.mean FILE=colvar
+\endverbatim
+
+The following command calculates the histogram of Q6 parameters for the 64 atoms in a box of Lennard Jones and prints these
+quantities to a file called colvar:
+
+\verbatim
+Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q6
+PRINT ARG=q6.* FILE=colvar
+\endverbatim
+
+The following command could be used to measure the Q6 paramters that describe the arrangement of chlorine ions around the
+sodium atoms in NaCl. The imagined system here is composed of 64 NaCl formula units and the atoms are arranged in the input
+with the 64 Na\f$^+\f$ ions followed by the 64 Cl\f$-\f$ ions. Once again the average Q6 paramter is calculated and output to a
+file called colvar
+
+\verbatim
+Q6 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q6
+PRINT ARG=q6.mean FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
//+PLUMEDOC MCOLVARF LOCAL_Q6
/*
-Calculate 4th order Steinhardt parameters.
+Calculate the local degree of order around an atoms by taking the average dot product between the \f$q_6\f$ vector on the central atom and the \f$q_6\f$ vector
+on the atoms in the first coordination sphere.
+
+The \ref Q6 command allows one to calculate one complex vectors for each of the atoms in your system that describe the degree of order in the coordination sphere
+around a particular atom. The difficulty with these vectors comes when combining the order parameters from all of the individual atoms/molecules so as to get a
+measure of the global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter - can be problematic. If one is
+examining nucleation say only the order parameters for those atoms in the nucleus will change significantly when the nucleus forms. The order parameters for the
+atoms in the surrounding liquid will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of solution/melt any
+change in the average order parameter will be negligible. Substantial changes in the value of this average can be observed in simulations of nucleation but only
+because the number of atoms is relatively small.
+
+When the average \ref Q6 parameter is used to bias the dynamics a problems
+can occur. These averaged coordinates cannot distinguish between the correct,
+single-nucleus pathway and a concerted pathway in which all the atoms rearrange
+themselves into their solid-like configuration simultaneously. This second type
+of pathway would be impossible in reality because there is a large entropic
+barrier that prevents concerted processes like this from happening. However,
+in the finite sized systems that are commonly simulated this barrier is reduced
+substantially. As a result in simulations where average Steinhardt parameters
+are biased there are often quite dramatic system size effects
+
+If one wants to simulate nucleation using some form on
+biased dynamics what is really required is an order parameter that measures:
+
+- Whether or not the coordination spheres around atoms are ordered
+- Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
+
+\ref LOCAL_AVERAGE and \ref NLINKS are variables that can be combined with the Steinhardt parameteters allow to calculate variables that satisfy these requirements.
+LOCAL_Q6 is another variable that can be used in these sorts of calculations. The LOCAL_Q6 parameter for a particular atom is a number that measures the extent to
+which the orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does this by calculating the following
+quantity for each of the atoms in the system:
+
+\f[
+ s_i = \frac{ \sum_j \sigma( r_{ij} ) \sum_{m=-6}^6 q_{6m}^{*}(i)q_{6m}(j) }{ \sum_j \sigma( r_{ij} ) }
+\f]
+
+where \f$q_{6m}(i)\f$ and \f$q_{6m}(j)\f$ are the 6th order Steinhardt vectors calculated for atom \f$i\f$ and atom \f$j\f$ respectively and the asterix denotes
+complex conjugation. The function
+\f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set
+so that it the function is equal to one when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise. The sum in the numerator
+of this expression is the dot product of the Steinhardt parameters for atoms \f$i\f$ and \f$j\f$ and thus measures the degree to which the orientations of these
+adjacent atoms is correlated.
\par Examples
+The following command calculates the average value of the LOCAL_Q6 parameter for the 64 Lennard Jones atoms in the system under study and prints this
+quantity to a file called colvar.
+
+\verbatim
+Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
+LOCAL_Q6 ARG=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq6
+PRINT ARG=lq6.mean FILE=colvar
+\endverbatim
+
+The following input calculates the distribution of LOCAL_Q6 parameters at any given time and outputs this information to a file.
+
+\verbatim
+Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
+LOCAL_Q6 ARG=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=lq6
+PRINT ARG=lq6.* FILE=colvar
+\endverbatim
+
+The following calculates the LOCAL_Q6 parameters for atoms 1-5 only. For each of these atoms comparisons of the geometry of the coordination sphere
+are done with those of all the other atoms in the system. The final quantity is the average and is outputted to a file
+
+\verbatim
+Q6 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q6a
+Q6 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q6b
+
+LOCAL_Q6 ARG=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
+PRINT ARG=w6.* FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/crystallization/VectorAverage.cpp b/src/crystallization/VectorAverage.cpp
index 27d515c1d..241ff7227 100644
--- a/src/crystallization/VectorAverage.cpp
+++ b/src/crystallization/VectorAverage.cpp
@@ -29,10 +29,30 @@
//+PLUMEDOC MCOLVARF AVERAGE_VECTOR
/*
-Calculate an average vector
+Calculate the average vector by averaging each component of the vector separately
+
+This colvar takes a set of atom centered vectors and calculates the average vector. Unlike
+the average calculated by using the following command:
+
+\verbatim
+Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q6
+\endverbatim
+
+which calculates the average value for the norm of the Q6 vectors, the AVERAGE_VECTOR command takes
+the average by averaging each component of the vector in turn. This sort of thing has is sometimes
+used to measure the average Q4 parameter in a cluster.
\par Examples
+The following command calculates the average Q6 vector for a 75 atom cluster of Lennard Jones. The
+average is then printed to a file called colvar.
+
+\verbatim
+Q6 SPECIES=1-75 SWITCH={GAUSSIAN D_0=1.391 R_0=0.01} LABEL=q6
+AVERAGE_VECTOR DATA=q6 LABEL=a6a
+PRINT ARG=a6a FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/multicolvar/LocalAverage.cpp b/src/multicolvar/LocalAverage.cpp
index 9da67a5a8..6be7b8de5 100644
--- a/src/multicolvar/LocalAverage.cpp
+++ b/src/multicolvar/LocalAverage.cpp
@@ -27,8 +27,53 @@
/*
Calculate averages over spherical regions centered on atoms
+As is explained in <a href="http://www.youtube.com/watch?v=iDvZmbWE5ps"> this video </a> certain multicolvars
+calculate one scalar quantity or one vector for each of the atoms in the system. For example
+\ref COORDINATIONNUMBERS measures the coordination number of each of the atoms in the system and \ref Q4 measures
+the 4th order Steinhardt parameter for each of the atoms in the system. These quantities provide tell us something about
+the disposition of the atoms in the first coordination sphere of each of the atoms of interest. Lechner and Dellago \cite dellago-q6
+have suggested that one can probe local order in a system by taking the average value of such symmetry functions over
+the atoms within a spherical cutoff of each of these atoms in the systems. When this is done with Steinhardt parameters
+they claim this gives a coordinate that is better able to distinguish solid and liquid configurations of Lennard-Jones atoms.
+
+You can calculate such locally averaged quantities within plumed by using the LOCAL_AVERAGE command. This command calculates
+the following atom-centered quantities:
+
+\f[
+s_i = \frac{ c_i + \sum_j \sigma(r_{ij})c_j }{ 1 + \sum_j \sigma(r_{ij}) }
+\f]
+
+where the \f$c_i\f$ and \f$c_j\f$ values can be for any one of the symmetry functions that can be calculated using plumed
+multicolvars. The function \f$\sigma( r_{ij} )\f$ is a \ref switching function that acts on the distance between
+atoms \f$i\f$ and \f$j\f$. Lechner and Dellago suggest that the parameters of this function should be set so that it the function is equal to one
+when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise.
+
+The \f$s_i\f$ quantities calculated using the above command can be again thought of as atom-centred symmetry functions. They
+thus operate much like multicolvars. You can thus calculate properties of the distribution of \f$s_i\f$ values using MEAN, LESS_THAN, HISTOGRAM
+and so on. You can also probe the value of these averaged variables in regions of the box by using the command in tandem with the
+\ref AROUND command.
+
\par Examples
+This example input calculates the coordination numbers for all the atoms in the system. These coordination numbers are then averaged over
+spherical regions. The number of averaged coordination numbers that are greater than 4 is then output to a file.
+
+\verbatim
+COORDINATIONNUMBERS SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=d1
+LOCAL_AVERAGE ARG=d1 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MORE_THAN={RATIONAL R_0=4} LABEL=la
+PRINT ARG=la.* FILE=colvar
+\endverbatim
+
+This example input calculates the \f$q_4\f$ (see \ref Q4) vectors for each of the atoms in the system. These vectors are then averaged
+component by component over a spherical region. The average value for this quantity is then outputeed to a file. This calculates the
+quantities that were used in the paper by Lechner and Dellago \cite dellago-q6
+
+\verbatim
+Q4 SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=q4
+LOCAL_AVERAGE ARG=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=la
+PRINT ARG=la.* FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/src/multicolvar/NumberOfLinks.cpp b/src/multicolvar/NumberOfLinks.cpp
index 7e1742272..086dfae94 100644
--- a/src/multicolvar/NumberOfLinks.cpp
+++ b/src/multicolvar/NumberOfLinks.cpp
@@ -34,10 +34,31 @@ In its simplest guise this coordinate calculates a coordination number. Each pa
of atoms is assumed "linked" if they are within some cutoff of each other. In more
complex applications each entity is a vector and this quantity measures whether
pairs of vectors are (a) within a certain cutoff and (b) if the two vectors have
-similar orientations
+similar orientations. The vectors on individual atoms could be Steinhardt parameters
+(see \ref Q3, \ref Q4 and \ref Q6) or they could describe some internal vector in a molecule.
\par Examples
+The following calculates how many bonds there are in a system containing 64 atoms and outputs
+this quantity to a file.
+
+\verbatim
+DENSITY SPECIES=1-64 LABEL=d1
+NLINKS ARG=d1 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=dd
+PRINT ARG=dd FILE=colvar
+\endverbatim
+
+The following calculates how many pairs of neighbouring atoms in a system containg 64 atoms have
+similar dispositions for the atoms in their coordination sphere. This calculation uses the
+dot product of the Q6 vectors on adjacent atoms to measure whether or not two atoms have the same
+``orientation"
+
+\verbatim
+Q6 SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=q6
+NLINKS ARG=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=dd
+PRINT ARG=dd FILE=colvar
+\endverbatim
+
*/
//+ENDPLUMEDOC
diff --git a/user-doc/bibliography.bib b/user-doc/bibliography.bib
index b2c70a405..2f7ff66c8 100644
--- a/user-doc/bibliography.bib
+++ b/user-doc/bibliography.bib
@@ -1991,3 +1991,16 @@ pages = {331--346},
url = {http://link.aps.org/doi/10.1103/PhysRevLett.111.230602},
publisher = {American Physical Society}
}
+
+@article{dellago-q6,
+ author = "Lechner, Wolfgang and Dellago, Christoph",
+ title = "Accurate determination of crystal structures based on averaged local bond order parameters",
+ journal = "The Journal of Chemical Physics",
+ year = "2008",
+ volume = "129",
+ number = "11",
+ eid = 114707,
+ pages = "-",
+ url = "http://scitation.aip.org/content/aip/journal/jcp/129/11/10.1063/1.2977970",
+ doi = "http://dx.doi.org/10.1063/1.2977970"
+}
--
GitLab