From 25ba7c17a5c20c73b51c6221e4dadc3e6e62fc53 Mon Sep 17 00:00:00 2001 From: Gareth Aneurin Tribello Date: Mon, 4 Nov 2024 09:49:48 +0000 Subject: [PATCH] Added new style documentation for stuff in volume module --- src/volumes/VolumeAround.cpp | 4 +- src/volumes/VolumeBetweenContours.cpp | 37 ++++---- src/volumes/VolumeCavity.cpp | 108 ++++++++++++----------- src/volumes/VolumeInCylinder.cpp | 71 ++++++++------- src/volumes/VolumeInSphere.cpp | 60 +++++++------ src/volumes/VolumeTetrapore.cpp | 119 +++++++++++++------------- 6 files changed, 206 insertions(+), 193 deletions(-) diff --git a/src/volumes/VolumeAround.cpp b/src/volumes/VolumeAround.cpp index f5695bf8f8..926c2f7507 100644 --- a/src/volumes/VolumeAround.cpp +++ b/src/volumes/VolumeAround.cpp @@ -42,10 +42,10 @@ The 100 elements of the vector `a` that is returned from the AROUND action in th 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) $$ -where \f$K\f$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits +where $K$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits for the integrals are the values specified using the keywords XLOWER, XUPPER, YLOWER, YUPPER, YUPPER, ZLOWER and ZUPPER. $x_i$, $y_i$ and $z_i$ are then the components of the vector that connects the $i$th atom that was specified using the ATOMS keyword to the atom that was specified using the ORIGIN keyword. In other words, -$w((x_i,y_i,z_i)$ is 1 if the atom is within a rectangular box that is centered on the atom that is specified as the origin and zero otherwise. +$w(x_i,y_i,z_i)$ is 1 if the atom is within a rectangular box that is centered on the atom that is specified as the origin and zero otherwise. ## Calculating the number of atoms in a particular part of the box diff --git a/src/volumes/VolumeBetweenContours.cpp b/src/volumes/VolumeBetweenContours.cpp index ac3f249a78..1555f1a2cc 100644 --- a/src/volumes/VolumeBetweenContours.cpp +++ b/src/volumes/VolumeBetweenContours.cpp @@ -31,29 +31,32 @@ /* This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a region where the density of a certain type of atom is high. -This collective variable can be used to determine whether colvars are within region where the density -of a particular atom is high. This is achieved by calculating the following function at the point where -the atom is located \f$(x,y,z)\f$: +This collective variable can be used to determine whether atoms are within region where the density +of a particular atom type is high. This is achieved by calculating the following function at the point where +each atom is located $(x_i,y_i,z_i)$: -\f[ -w_j = 1 - \sigma\left[ \sum_{i=1}^N K\left( \frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right) \right] -\f] +$$ +w_i = 1 - \sigma\left[ \sum_{i=1}^N K\left( \frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right) \right] +$$ -Here \f$\sigma\f$ is a \ref switchingfunction and \f$K\f$ is a \ref kernelfunctions. The sum runs over the atoms -specified using the ATOMS keyword and a \f$w_j\f$ value is calculated for each of the central atoms of the input +Here $\sigma$ is one of the switching functions that is discussed in the documentation for the action [LESS_THAN](LESS_THAN.md) and $K$ is +one of the kernel functions that is discussed in the documentation for the action [BETWEEN](BETWEEN.md). The sum runs over the atoms +specified using the FIELD_ATOMS keyword and a $w_j$ value is calculated for each of the central atoms of the input multicolvar. -\par Examples - -The input below calculates a density field from the positions of atoms 1-14400. The number of the atoms -that are specified in the DENSITY action that are within a region where the density field is greater than -2.0 is then calculated. +The input below shows how this action works in practise. This input calculates a density field from the positions of atoms 1-14400. A vector which has +as many elements as atoms that were specified using the ATOMS keyword. The $i$th element of this vector is calculated using the expression above with $(x_i,y_i,z_i)$ +being the position of the $i$th atom that was specified using that ATOMS keyword. -\plumedfile -d1: DENSITY SPECIES=14401-74134:3 LOWMEM -fi: INENVELOPE DATA=d1 ATOMS=1-14400 CONTOUR={RATIONAL D_0=2.0 R_0=1.0} BANDWIDTH=0.1,0.1,0.1 LOWMEM +```plumed +fi: INENVELOPE ATOMS=14401-74134:3 FIELD_ATOMS=1-14400 CONTOUR={RATIONAL D_0=2.0 R_0=1.0} BANDWIDTH=0.1,0.1,0.1 PRINT ARG=fi FILE=colvar -\endplumedfile +``` + +This particular action was developed with the intention of determining whether water molecules had penetrated a membrane or not. The FIELD_ATOMS were thus the atoms of the +lipid molecules that made up the membrane and the ATOMS were the oxygens of the water molecules. The vector that is output by this action can be used in all the ways that the +vector that is output by the [AROUND](AROUND.md) action is used. In other words, this action can be used to calculate the number of water molecules in the membrane or the average +values for a symmetry function for those atoms that are within the membrane. */ //+ENDPLUMEDOC diff --git a/src/volumes/VolumeCavity.cpp b/src/volumes/VolumeCavity.cpp index fb53c8775a..58845e770e 100644 --- a/src/volumes/VolumeCavity.cpp +++ b/src/volumes/VolumeCavity.cpp @@ -30,29 +30,25 @@ /* This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms. -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(u_i,v_i,w_i) }{ \sum_i w(u_i,v_i,w_i) } -\f] - -where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (u_i,v_i,z_i)\f$. -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. -Notice that here (at variance with what is done in \ref AROUND) we have transformed from the usual \f$(x_i,y_i,z_i)\f$ -position to a position in \f$ (u_i,v_i,z_i)\f$. This is done using a rotation matrix as follows: - -\f[ +This action can be used similarly to the way [AROUND](AROUND.md) is used. Like [AROUND](AROUND.md) this action returns a vector +with elements that tell you whether an input atom is within a part of the box that is of particular interest or not. However, for this action +the elements of this vector are calculated using: + +$$ +w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w + K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_i}{\sigma} \right) +$$ + +with $u_i,v_i,w_i$ being calculated from the positon of the $i$th atom, $(x_i,y_i,z_i)$, by performing the following transformation. + +$$ \left( \begin{matrix} u_i \\ v_i \\ w_i \end{matrix} -\right) = \mathbf{R} +\right) = R \left( \begin{matrix} x_i - x_o \\ @@ -60,44 +56,52 @@ position to a position in \f$ (u_i,v_i,z_i)\f$. This is done using a rotation m z_i - z_o \end{matrix} \right) -\f] +$$ -where \f$\mathbf{R}\f$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the +In this expression $R$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the reference positions specified by the user. The first of these unit vectors points from the first reference atom to the second. The second is then the normal to the plane containing atoms 1,2 and 3 and the the third is the unit vector orthogonal to -these first two vectors. \f$(x_o,y_o,z_o)\f$, meanwhile, specifies the position of the first reference atom. - -In the previous function \f$ w(u_i,v_i,w_i) \f$ measures whether or not the system is in the subregion of interest. It -is equal to: - -\f[ -w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w - K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_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 vector connecting atom 1 to atom 4 is used to define the extent of the box in each of the \f$u\f$, \f$v\f$ and \f$w\f$ -directions. Essentially the vector connecting atom 1 to atom 4 is projected onto the three unit vectors -described above and the resulting projections determine the \f$u'\f$, \f$v'\f$ and \f$w'\f$ parameters in the above expression. - -\par Examples - -The following commands tell plumed to calculate the number of atoms in an ion channel in a protein. -The extent of the channel is calculated from the positions of atoms 1, 4, 5 and 11. The final value will be labeled cav. - -\plumedfile -d1: DENSITY SPECIES=20-500 -CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 LABEL=cav -\endplumedfile - -The following command tells plumed to calculate the coordination numbers (with other water molecules) for the water -molecules in the protein channel described above. The average coordination number and the number of coordination -numbers more than 4 is then calculated. The values of these two quantities are given the labels cav.mean and cav.morethan - -\plumedfile -d1: COORDINATIONNUMBER SPECIES=20-500 R_0=0.1 -CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 MEAN MORE_THAN={RATIONAL R_0=4} LABEL=cav -\endplumedfile +these first two vectors. $(x_o,y_o,z_o)$, meanwhile, specifies the position of the first reference atom. + +In the first expression above $K$ is one of the kernel functions described in the documentation for the action [BETWEEN](BETWEEN.md) +and $\sigma$ is a bandwidth parameter. Furthermore, The vector connecting atom 1 to atom 4 is used to define the extent of the box in +each of the $u$, $v$ and $w$ directions. This vector connecting atom 1 to atom 4 is projected onto the three unit vectors +described above and the resulting projections determine the $u'$, $v'$ and $w'$ parameters in the above expression. + +The following commands illustrate how this works in practise. We are using PLUMED here to calculate the number of atoms from the group specified using the ATOMS keyword below are +in an ion channel in a protein. The extent of the channel is calculated from the positions of atoms 1, 4, 5 and 11. + +```plumed +cav: CAVITY ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1 +s: SUM ARG=cav PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +By contrst the following command tells plumed to calculate the coordination numbers (with other water molecules) for the water +molecules in the protein channel described above. The average coordination number and the number of coordination +numbers more than 4 is then calculated for those molecules that are in the region of interest. + +```plumed +# Calculate the atoms that are in the cavity +cav: CAVITY ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1 +# Calculate the coordination numbers of all the atoms +d1: COORDINATIONNUMBER SPECIES=20-500 SWITCH={RATIONAL R_0=0.1} +# Do atoms have a coordination number that is greater than 4 +fd1: MORE_THAN ARG=d1 SWITCH={RATIONAL R_0=4} +# Calculate the mean coordination number in the channel +nnn: CUSTOM ARG=cav,d1 FUNC=x*y PERIODIC=NO +numer: SUM ARG=nnn PERIODIC=NO +denom: SUM ARG=cav PERIODIC=NO +mean: CUSTOM ARG=numer,denom FUNC=x/y PERIODIC=NO +# Calculate the number of atoms that are in the channel and that have a coordination number that is greater than 4 +sss: CUSTOM ARG=fd1,cav FUNC=x*y PERIODIC=NO +mt: SUM ARG=sss PERIODIC=NO +# And print these two quantities to a file +PRINT ARG=mean,mt FILE=colvar +``` + +As with [AROUND](AROUND.md) earlier version of PLUMED used a different syntax for doing these types of calculations, which can +still be used with this new version of the command. However, we strongly recommend using the newer syntax. */ //+ENDPLUMEDOC diff --git a/src/volumes/VolumeInCylinder.cpp b/src/volumes/VolumeInCylinder.cpp index aeb854031e..8fa3ea81de 100644 --- a/src/volumes/VolumeInCylinder.cpp +++ b/src/volumes/VolumeInCylinder.cpp @@ -29,41 +29,48 @@ /* 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) \sigma(r_{xy}) }{ \sum_i \sigma(r_{xy}) } -\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$\sigma\f$ is a \ref switchingfunction that acts on the distance between the point at which the -collective is located \f$(x_i,y_i,z_i)\f$ and the position of the atom that was specified using the ORIGIN keyword -projected in the xy plane if DIRECTION=z is used. In other words: -\f[ -r_{xy} = sqrt{ ( x_i - x_0)^2 + ( y_i - y_0)^2 } -\f] -In short this function, \f$\sigma(r_{xy})\f$, measures whether or not the CV is within a cylinder that -runs along the axis specified using the DIRECTION keyword and that is centered on the position of the atom specified using -ORIGIN. - -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 INCYLINDER is used with the \ref DENSITY action the number of atoms in the specified region is calculated +This action can be used to calculate whether each of the atoms are within a particular part of the simulation box or not as illustrated by the following example: -\par Examples +```plumed +f: FIXEDATOM AT=0,0,0 +a: INCYLINDER ATOMS=1-100 CENTER=f DIRECTION=Z RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-1.0 UPPER=1.0 +PRINT ARG=a FILE=colvar +``` + +The 100 elements of the vector `a` that is returned from the INCYLINDER action in the above input are calculated using: + +$$ +w(x_i,y_i,z_i) = s\left( r_{xy} \right) \int_{zl}^{zu} \textrm{d}z K\left( \frac{z - z_i}{\sigma} \right) +$$ + +where + +$$ +r_{xy} = \sqrt{ x_i^2 + y_i^2 } +$$ + +In these expressions $K$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits +for the integrals are the values specified using the keywords `LOWER` and `UPPER`. $x_i$, $y_i$ and $z_i$ are then the components +of the vector that connects the $i$th atom that was specified using the `ATOMS` keyword to the atom that was specified using the `CENTER` keyword. In other words, +$w(x_i,y_i,z_i)$ is 1 if the atom is within a cylinder that is centered on the $z$ axis that has an extent along the $z$ direction around the position of atom `f` that +is determined by the values specified by `LOWER` and `UPPER` keywords. The radial extent of this cylinder is determined by the parameters of the switching function that is +specified using the `RADIUS` keyword. + +If you want to caluclate and print the number of atoms in the cylinder of interest you can use an input like the one shown below: + +```plumed +f: FIXEDATOM AT=0,0,0 +a: INCYLINDER ATOMS=1-100 CENTER=f DIRECTION=X RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-1.0 UPPER=1.0 +s: SUM ARG=a PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +Notice that now the cylinder is centered on the `x` axis rather than the `z` axis as we have changed the input for the `DIRECTION` keyword. -The input below can be use to calculate the average coordination numbers for those atoms that are within a cylindrical tube -of radius 1.5 nm that is centered on the position of atom 101 and that has its long axis parallel to the z-axis. +You can also calculate the average values of symmetry functions in the cylinder of interest by using inputs similar to those described the documentation for the [AROUND](AROUND.md) +action. In other words, you can swap out AROUND actions for an INCLYLINDER actions. Also as with [AROUND](AROUND.md), earlier versions of PLUMED used a different syntax for doing these +types of calculations, which can still be used with this new version of the command. However, we strongly recommend using the newer syntax. -\plumedfile -c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1} -d2: INCYLINDER ATOM=101 DATA=c1 DIRECTION=Z RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-0.1 UPPER=0.1 MEAN -PRINT ARG=d2.* FILE=colvar -\endplumedfile */ //+ENDPLUMEDOC diff --git a/src/volumes/VolumeInSphere.cpp b/src/volumes/VolumeInSphere.cpp index 3709bf09f8..4651a6a6ff 100644 --- a/src/volumes/VolumeInSphere.cpp +++ b/src/volumes/VolumeInSphere.cpp @@ -29,40 +29,38 @@ /* 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) \sigma(r) }{ \sum_i \sigma(r) } -\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$\sigma\f$ is a \ref switchingfunction that acts on the distance between the point at which the -collective is located \f$(x_i,y_i,z_i)\f$ and the position of the atom that was specified using the ORIGIN keyword. -In other words: -\f[ -r = sqrt{ ( x_i - x_0)^2 + ( y_i - y_0)^2 + ( z_i - z_0)^2} -\f] -In short this function, \f$\sigma(r_{xy})\f$, measures whether or not the CV is within a sphere that is -centered on the position of the atom specified using the keyword ORIGIN. - -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 INCYLINDER is used with the \ref DENSITY action the number of atoms in the specified region is calculated +This action can be used to calculate whether each of the atoms are within a particular part of the simulation box or not as illustrated by the following example: -\par Examples +```plumed +f: FIXEDATOM AT=0,0,0 +a: INSPHERE ATOMS=1-100 CENTER=f RADIUS={GAUSSIAN R_0=1.5} +PRINT ARG=a FILE=colvar +``` + +The 100 elements of the vector `a` that is returned from the INSPHERE action in the above input are calculated using: + +$$ +w(x_i,y_i,z_i) = \sigma\left( \sqrt{ x_i^2 + y_i^2 + z_i^2} \right) +$$ + +In this expression $x_i$, $y_i$ and $z_i$ are the components of the vector that connects the $i$th atom that was specified using the `ATOMS` keyword to the atom that was specified using the `CENTER` keyword and +$\sigma$ is one of the switching functions that is described that in the documentation for the action [LESS_THAN](LESS_THAN.md). In other words, +$w(x_i,y_i,z_i)$ is 1 if atom $i$ is within a sphere with a radial extent that is determined by the parameters of the specified switching function +and zero otherwise. + +If you want to caluclate and print the number of atoms in the sphere of interest you can use an input like the one shown below: + +```plumed +f: FIXEDATOM AT=0,0,0 +a: INSPHERE ATOMS=1-100 CENTER=f RADIUS={GAUSSIAN R_0=1.5} +s: SUM ARG=a PERIODIC=NO +PRINT ARG=s FILE=colvar +``` -The input below can be use to calculate the average coordination numbers for those atoms that are within a sphere -of radius 1.5 nm that is centered on the position of atom 101. +You can also calculate the average values of symmetry functions in the sphere of interest by using inputs similar to those described the documentation for the [AROUND](AROUND.md) +action. In other words, you can swap out AROUND actions for an INSPHERE actions. Also as with [AROUND](AROUND.md), earlier versions of PLUMED used a different syntax for doing these types of calculations, which can +still be used with this new version of the command. However, we strongly recommend using the newer syntax. -\plumedfile -c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1} -d2: INSPHERE ATOM=101 DATA=c1 RADIUS={TANH R_0=1.5} MEAN -PRINT ARG=d2.* FILE=colvar -\endplumedfile */ //+ENDPLUMEDOC diff --git a/src/volumes/VolumeTetrapore.cpp b/src/volumes/VolumeTetrapore.cpp index 9037331722..47f539f95d 100644 --- a/src/volumes/VolumeTetrapore.cpp +++ b/src/volumes/VolumeTetrapore.cpp @@ -30,29 +30,25 @@ /* This quantity can be used to calculate functions of the distribution of collective variables for the atoms lie that lie in a box defined by the positions of four atoms at the corners of a tetrahedron. -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(u_i,v_i,w_i) }{ \sum_i w(u_i,v_i,w_i) } -\f] - -where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (u_i,v_i,z_i)\f$. -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. -Notice that here (at variance with what is done in \ref AROUND) we have transformed from the usual \f$(x_i,y_i,z_i)\f$ -position to a position in \f$ (u_i,v_i,z_i)\f$. This is done using a rotation matrix as follows: - -\f[ +This action can be used similarly to the way [AROUND](AROUND.md) is used. Like [AROUND](AROUND.md) this action returns a vector +with elements that tell you whether an input atom is within a part of the box that is of particular interest or not. However, for this action +the elements of this vector are calculated using: + +$$ +w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w + K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_i}{\sigma} \right) +$$ + +with $u_i,v_i,w_i$ being calculated from the positon of the $i$th atom, $(x_i,y_i,z_i)$, by performing the following transformation. + +$$ \left( \begin{matrix} u_i \\ v_i \\ w_i \end{matrix} -\right) = \mathbf{R} +\right) = R \left( \begin{matrix} x_i - x_o \\ @@ -60,52 +56,57 @@ position to a position in \f$ (u_i,v_i,z_i)\f$. This is done using a rotation m z_i - z_o \end{matrix} \right) -\f] +$$ -where \f$\mathbf{R}\f$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the -reference positions specified by the user. Initially unit vectors are found by calculating the bisector, \f$\mathbf{b}\f$, and -cross product, \f$\mathbf{c}\f$, of the vectors connecting atoms 1 and 2. A third unit vector, \f$\mathbf{p}\f$ is then found by taking the cross -product between the cross product calculated during the first step, \f$\mathbf{c}\f$ and the bisector, \f$\mathbf{b}\f$. From this -second cross product \f$\mathbf{p}\f$ and the bisector \f$\mathbf{b}\f$ two new vectors are calculated using: +where $\mathbf{R}$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the +reference positions specified by the user. Initially unit vectors are found by calculating the bisector, $\mathbf{b}$, and +cross product, $\mathbf{c}$, of the vectors connecting the first and second and first and third of the atoms that were specified +using the `BOX` keyword. A third unit vector, $\mathbf{p}$ is then found by taking the cross +product between the cross product calculated during the first step, $\mathbf{c}$ and the bisector, $\mathbf{b}$. From this +second cross product $\mathbf{p}$ and the bisector $\mathbf{b}$ two new vectors are calculated using: -\f[ +$$ v_1 = \cos\left(\frac{\pi}{4}\right)\mathbf{b} + \sin\left(\frac{\pi}{4}\right)\mathbf{p} \qquad \textrm{and} \qquad v_2 = \cos\left(\frac{\pi}{4}\right)\mathbf{b} - \sin\left(\frac{\pi}{4}\right)\mathbf{p} -\f] - -In the previous function \f$ w(u_i,v_i,w_i) \f$ measures whether or not the system is in the subregion of interest. It -is equal to: - -\f[ -w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w - K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_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 values of \f$u'\f$ and \f$v'\f$ are found by finding the projections of the vectors connecting atoms 1 and 2 and 1 -and 3 \f$v_1\f$ and \f$v_2\f$. This gives four projections: the largest two projections are used in the remainder of -the calculations. \f$w'\f$ is calculated by taking the projection of the vector connecting atoms 1 and 4 on the vector -\f$\mathbf{c}\f$. Notice that the manner by which this box is constructed differs from the way this is done in \ref CAVITY. -This is in fact the only point of difference between these two actions. - -\par Examples - -The following commands tell plumed to calculate the number of atom inside a tetrahedral cavity. The extent of the tetrahedral -cavity is calculated from the positions of atoms 1, 4, 5, and 11, The final value will be labeled cav. - -\plumedfile -d1: DENSITY SPECIES=20-500 -TETRAHEDRALPORE DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 LABEL=cav -\endplumedfile - -The following command tells plumed to calculate the coordination numbers (with other water molecules) for the water -molecules in the tetrahedral cavity described above. The average coordination number and the number of coordination -numbers more than 4 is then calculated. The values of these two quantities are given the labels cav.mean and cav.morethan - -\plumedfile -d1: COORDINATIONNUMBER SPECIES=20-500 R_0=0.1 -CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 MEAN MORE_THAN={RATIONAL R_0=4} LABEL=cav -\endplumedfile +$$ + +In the first expression above $K$ is one of the kernel functions described in the documentation for the action [BETWEEN](BETWEEN.md) +and $\sigma$ is a bandwidth parameter. Furthermore, The vector connecting atom first and fourth atoms that were specified using the `BOX` keyword is used to define the extent of the box in +each of the $u$, $v$ and $w$ directions. This vector connecting atom 1 to atom 4 is projected onto the three unit vectors +described above and the resulting projections determine the $u'$, $v'$ and $w'$ parameters in the above expression. + +The following commands illustrate how this works in practise. We are using PLUMED here to calculate the number of atoms from the group specified using the ATOMS keyword below are +in a tetrahedral pore. The extent of the pore is calculated from the positions of atoms 1, 4, 5 and 11. + +```plumed +cav: TETRAHEDRALPORE ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1 +``` + +By contrst the following command tells plumed to calculate the coordination numbers for the atoms +in the pre described above. The average coordination number and the number of coordination +numbers more than 4 is then calculated for those molecules that are in the region of interest. + +```plumed +# Calculate the atoms that are in the pore +cav: TETRAHEDRALPORE ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1 +# Calculate the coordination numbers of all the atoms +d1: COORDINATIONNUMBER SPECIES=20-500 SWITCH={RATIONAL R_0=0.1} +# Do atoms have a coordination number that is greater than 4 +fd1: MORE_THAN ARG=d1 SWITCH={RATIONAL R_0=4} +# Calculate the mean coordination number in the pore +nnn: CUSTOM ARG=cav,d1 FUNC=x*y PERIODIC=NO +numer: SUM ARG=nnn PERIODIC=NO +denom: SUM ARG=cav PERIODIC=NO +mean: CUSTOM ARG=numer,denom FUNC=x/y PERIODIC=NO +# Calculate the number of atoms that are in the pore and that have a coordination number that is greater than 4 +sss: CUSTOM ARG=fd1,cav FUNC=x*y PERIODIC=NO +mt: SUM ARG=sss PERIODIC=NO +# And print these two quantities to a file +PRINT ARG=mean,mt FILE=colvar +``` + +As with [AROUND](AROUND.md) earlier version of PLUMED used a different syntax for doing these types of calculations, which can +still be used with this new version of the command. However, we strongly recommend using the newer syntax. */ //+ENDPLUMEDOC