diff --git a/src/setup/Load.cpp b/src/setup/Load.cpp index cd68a58da2..15c56ca5e8 100644 --- a/src/setup/Load.cpp +++ b/src/setup/Load.cpp @@ -107,7 +107,7 @@ Instead of the command: PLUMED_REGISTER_ACTION(Distance,"DISTANCE2") ``` -that was used in `Distance2.cpp. Consequently, when we load the `Distance3.cpp` file here we redefine the DISTANCE command. +that was used in `Distance2.cpp`. Consequently, when we load the `Distance3.cpp` file here we redefine the DISTANCE command. The functions that compute `d` and `d2` in the above input are thus different. A final point to note is that, starting with PLUMED 2.10, the LOAD action can be used in contexts where diff --git a/src/vatom/ArgsToVatom.cpp b/src/vatom/ArgsToVatom.cpp index 8b0087bd02..623031e487 100644 --- a/src/vatom/ArgsToVatom.cpp +++ b/src/vatom/ArgsToVatom.cpp @@ -31,7 +31,39 @@ /* Create a virtual atom from the input scalars -\par Examples +This action takes five scalars that are computed by other actions in input and uses them to set the +x, y and z positions and the mass and charge of a virtual atom. This action is used within the +[CENTER](CENTER.md) shortcut to compute a center of mass. An example input that shows how you +can use this command to calculate the center of mass of atoms 1-10 is as follows: + +```plumed +# Calculate the total mass of the atoms +m: MASS ATOMS=1-10 +mass: SUM ARG=m PERIODIC=NO +# Calculate the totla charge of the atoms +q: CHARGE ATOMS=1-10 +charge: SUM ARG=q PERIODIC=NO +# Now get the positions of the atoms +pos: POSITION WHOLEMOLECULES ATOMS=1-10 +# Multiply each vector of positions by the masses +xwvec: CUSTOM ARG=m,pos.x FUNC=x*y PERIODIC=NO +ywvec: CUSTOM ARG=m,pos.y FUNC=x*y PERIODIC=NO +zwvec: CUSTOM ARG=m,pos.z FUNC=x*y PERIODIC=NO +# Sum the numerators in the expression for the center of mass +xnum: SUM ARG=xwvec PERIODIC=NO +ynum: SUM ARG=ywvec PERIODIC=NO +znum: SUM ARG=zwvec PERIODIC=NO +# And compute the x, y and z positions of the center of mass +x: CUSTOM ARG=xnum,mass FUNC=x/y PERIODIC=NO +y: CUSTOM ARG=ynum,mass FUNC=x/y PERIODIC=NO +z: CUSTOM ARG=znum,mass FUNC=x/y PERIODIC=NO +# And now create the virtual atom +p: ARGS2VATOM XPOS=x YPOS=y ZPOS=z MASS=mass CHARGE=charge +``` + +This input provides a very slow way of providing a center of mass - PLUMED contains a faster implementation that does all this. +This type of input is nevertheless useful if you are using arbitary weights when computing the sums in the numerator +and denominator of the expression for the center as is detailed in the documentation for the [CENTER](CENTER.md) command. */ //+ENDPLUMEDOC diff --git a/src/vatom/Center.cpp b/src/vatom/Center.cpp index 10ce5169f8..499e7225ab 100644 --- a/src/vatom/Center.cpp +++ b/src/vatom/Center.cpp @@ -41,50 +41,83 @@ Calculate the center for a group of atoms, with arbitrary weights. /* Calculate the center for a group of atoms, with arbitrary weights. -The computed -center is stored as a virtual atom that can be accessed in -an atom list through the label for the CENTER action that creates it. -Notice that the generated virtual atom has charge equal to the sum of the -charges and mass equal to the sum of the masses. If used with the MASS flag, -then it provides a result identical to \ref COM. - -When running with periodic boundary conditions, the atoms should be -in the proper periodic image. This is done automatically since PLUMED 2.2, -by considering the ordered list of atoms and rebuilding the molecule using a procedure -that is equivalent to that done in \ref WHOLEMOLECULES . Notice that -rebuilding is local to this action. This is different from \ref WHOLEMOLECULES -which actually modifies the coordinates stored in PLUMED. - -In case you want to recover the old behavior you should use the NOPBC flag. -In that case you need to take care that atoms are in the correct -periodic image. - -\note As an experimental feature, CENTER also supports a keyword PHASES. -This keyword finds the center of mass for sets of atoms that have been split by the period boundaries by computing scaled coordinates and average -trigonometric functions, similarly to \ref CENTER_OF_MULTICOLVAR. -Notice that by construction this center position is -not invariant with respect to rotations of the atoms at fixed cell lattice. -In addition, for symmetric Bravais lattices, it is not invariant with respect -to special symmetries. E.g., if you have an hexagonal cell, the center will -not be invariant with respect to rotations of 120 degrees. -On the other hand, it might make the treatment of PBC easier in difficult cases. +The position of the center ${r}_{\rm COM}$ given by: -\par Examples +$$ +{r}_{\rm COM}=\frac{\sum_{i=1}^{n} {r}_i\ w_i }{\sum_i^{n} w_i} +$$ + +In these expressions $r_i$ indicates the position of atom $i$ and $w_i$ is the weight for atom $i$. The following input +shows how you can calculate the expressions for a set of atoms by using PLUMED: -\plumedfile -# a point which is on the line connecting atoms 1 and 10, so that its distance -# from 10 is twice its distance from 1: +```plumed +# This action calculates the position of the point on the line connecting atoms 1 and 10 that is +# twice as far atom 10 as it is from atom 1 c1: CENTER ATOMS=1,1,10 -# this is another way of stating the same: +# this is another way of calculating this position c1bis: CENTER ATOMS=1,10 WEIGHTS=2,1 -# center of mass among these atoms: -c2: CENTER ATOMS=2,3,4,5 MASS +DUMPATOMS ATOMS=c1,c1bis FILE=atoms.xyz +``` -d1: DISTANCE ATOMS=c1,c2 +Notice that center's position is stored as [a virtual atom](specifying_atoms.md). The positions of the centers in the above input +used in the DUMPATOMS command by using the labels for the CENTER actions. Notice, furthermore, that the mass and charge of this new center +are equal to the sums of the masses and charges of the input atoms. -PRINT ARG=d1 -\endplumedfile +The input below shows how you can use the CENTER action in place of the [COM](COM) action to calculate the center of mass for a group of atoms. + +```plumed +c: CENTER ATOMS=1-5 MASS +``` + +Center is more powerful than COM because you can use arbitrary vectors of weights as in the first example above or vector of weights that are calculated by +another action as has been done in the input below. + +```plumed +fcc: FCCUBIC SPECIES=1-1000 SWITCH={RATIONAL D_0=3.0 R_0=1.5} +sfcc: MORE_THAN ARG=fcc SWITCH={RATIONAL R_0=0.5} +c: CENTER ATOMS=1-1000 WEIGHTS=sfcc +DUMPATOMS ATOMS=c FILE=atom.xyz +``` + +This input assumes you have a cluster of solid atoms in a liquid. The actions with labels `fcc` and `sfcc` +are used to differentiate between atoms in solid-like and liquid-like atoms. `sfcc` is thus a vector with +one element for each atom. These elements are equal to one if the environment around the corresponding atom +are solid like and zero if the environment around the atom is liquid like. + +## A note on periodic boundary conditions + +If you run with periodic boundary conditions +these are taken into account automatically when computing the center of mass. The way this is +handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command. +However, at variance to [WHOLEMOLECULES](WHOLEMOLECULES.md), the copies of the atomic positions in this +action are modified. The global positions (i.e. those that are used in all other actions) +are not changed when the alignment is performed. + +If you believe that PBC should not be applied when calculating the position fo the center of mass you can use the +NOPBC flag. + +An additional way of managing periodic boundary conditions is offered in CENTER by using the PHASES keyword as shown +in the example input below + +```plumed +c: CENTER ATOMS=1-100 PHASES +``` + +The scaled value for the $x$ component of the position of the center is calculated from the scaled components of the input atoms, $x_i$, +using the following expression when the PHASES option is employed + +$$ +x_\textrm{com} = \frac{1}{2\pi} \atan\left( \frac{\sum_{i=1}^n w_i \sin(2 \pi x_i ) }{ \sum_{i=1}^n w_i \cos(2 \pi x_i ) } \right) +$$ + +Similar, expressions are used to calculae the values of the scaled $y$ and $z$ components. The final cartesian coordinates of the center are then computed +by multiplying these scaled components by the cell vectors. Notice that by construction this center position is +not invariant with respect to rotations of the atoms at fixed cell lattice. +In addition, for symmetric Bravais lattices, it is not invariant with respect +to special symmetries. E.g., if you have an hexagonal cell, the center will +not be invariant with respect to rotations of 120 degrees. +On the other hand, it might make the treatment of PBC easier in difficult cases. */ //+ENDPLUMEDOC @@ -93,33 +126,34 @@ PRINT ARG=d1 /* Calculate the center of mass for a group of atoms. -The computed -center of mass is stored as a virtual atom that can be accessed in -an atom list through the label for the COM action that creates it. - -For arbitrary weights (e.g. geometric center) see \ref CENTER. +The following example input shows how you can use this shortcut to calculate the center of +mass for atoms 1,2,3,4,5,6,7 and for atoms 15,20. You can then compute the distance between +the two center of masses. -When running with periodic boundary conditions, the atoms should be -in the proper periodic image. This is done automatically since PLUMED 2.2, -by considering the ordered list of atoms and rebuilding the molecule using a procedure -that is equivalent to that done in \ref WHOLEMOLECULES . Notice that -rebuilding is local to this action. This is different from \ref WHOLEMOLECULES -which actually modifies the coordinates stored in PLUMED. - -In case you want to recover the old behavior you should use the NOPBC flag. -In that case you need to take care that atoms are in the correct -periodic image. - -\par Examples - -The following input instructs plumed to print the distance between the -center of mass for atoms 1,2,3,4,5,6,7 and that for atoms 15,20: -\plumedfile +```plumed c1: COM ATOMS=1-7 c2: COM ATOMS=15,20 d1: DISTANCE ATOMS=c1,c2 PRINT ARG=d1 -\endplumedfile +``` + +The center of mass is stored as a [virtual atom](specifying_atoms.md). As you can see from the +above to refer to the position of the center of mass when specifying the atoms that should be used +when calculating some other action you use the lable of the COM action that computes the center of mass +of interest. + +The COM command is a shortcut because it is a wrapper to [CENTER](CENTER.md). CENTER is more powerful than +comm as it allows you to use arbitrary weights in place of the masses. + +If you run with periodic boundary conditions +these are taken into account automatically when computing the center of mass. The way this is +handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command. +However, at variance to [WHOLEMOLECULES](WHOLEMOLECULES.md), the copies of the atomic positions in this +action are modified. The global positions (i.e. those that are used in all other actions) +are not changed when the alignment is performed. + +If you believe that PBC should not be applied when calculating the position fo the center of mass you can use the +NOPBC flag. */ //+ENDPLUMEDOC diff --git a/src/vatom/FixedAtom.cpp b/src/vatom/FixedAtom.cpp index fe2482cd66..8be55ca2a4 100644 --- a/src/vatom/FixedAtom.cpp +++ b/src/vatom/FixedAtom.cpp @@ -31,52 +31,35 @@ namespace vatom { /* Add a virtual atom in a fixed position. -This action creates a virtual atom at a fixed position. -The coordinates can be specified in Cartesian components (by default) -or in scaled coordinates (SCALED_COMPONENTS). -It is also possible to assign a predefined charge or mass to the atom. - -\attention -Similar to \ref POSITION this variable is not invariant for translation -of the system. Adding a force on it can create serious troubles. - -Notice that the distance between two atoms created -using FIXEDATOM is invariant for translation. -Additionally, if one first align atoms to a reference using \ref FIT_TO_TEMPLATE, -then it is safe to add further fixed atoms without breaking translational invariance. - -\par Examples +This action creates [a virtual atom](specifying_atoms.md) at a fixed position. The example input below illustrates +how this idea can be used to compute the angle between the vector connecting atoms 15 and 20 and the z axis and how this +quantity can then be restrained so that the angle stays close to zero. -The following input instructs plumed to compute the angle between -distance of atoms 15 and 20 and the z axis and keeping it close to zero. -\plumedfile +```plumed a: FIXEDATOM AT=0,0,0 b: FIXEDATOM AT=0,0,1 an: ANGLE ATOMS=a,b,15,20 RESTRAINT ARG=an AT=0.0 KAPPA=100.0 -\endplumedfile +``` -The following input instructs plumed to align a protein to a template -and to then compute the distance between one of the atoms in the protein and the point -(10,20,30). -\plumedfile -FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=SIMPLE -a: FIXEDATOM AT=10,20,30 -d: DISTANCE ATOMS=a,20 -PRINT ARG=d FILE=colvar -\endplumedfile +By default PLUMED assumes that any coordinates specified using the AT keyword specified are the cartesian coordinates of the fixed atom. +However, if you use the SCALED_COMPONENTS flag the coordinates specified using the AT keyword are interpretted as scaled coordinates. +It is also possible to assign a predefined charge or mass to the atom by using the `SET_MASS` and `SET_CHARGE` keywords. -The reference structure to align to is provided in a pdb file called ref.pdb as shown below: +> [!CAUTION] +> This action, like [POSITION](POSITION.md) is not invariant for translation of the system so adding a force on it can cause trouble. -\auxfile{ref.pdb} -ATOM 8 HT3 ALA 2 -1.480 -1.560 1.212 1.00 1.00 DIA H -ATOM 9 CAY ALA 2 -0.096 2.144 -0.669 1.00 1.00 DIA C -ATOM 10 HY1 ALA 2 0.871 2.385 -0.588 1.00 1.00 DIA H -ATOM 12 HY3 ALA 2 -0.520 2.679 -1.400 1.00 1.00 DIA H -ATOM 14 OY ALA 2 -1.139 0.931 -0.973 1.00 1.00 DIA O -END -\endauxfile +The problem is that the vector connecting any atom and a virtual atom created using the FIXEDATOM atoms command is not invariant to translation. +However, if, as has been done in the following example input, one first aligns atoms to a reference using [FIT_TO_TEMPLATE](FIT_TO_TEMPLATE.md), +then it is safe to add further fixed atoms without breaking translational invariance. +```plumed +#SETTINGS INPUTFILES=regtest/basic/rt63/align.pdb +FIT_TO_TEMPLATE STRIDE=1 REFERENCE=regtest/basic/rt63/align.pdb TYPE=SIMPLE +a: FIXEDATOM AT=10,20,30 +d: DISTANCE ATOMS=a,20 +PRINT ARG=d FILE=colvar +``` */ //+ENDPLUMEDOC diff --git a/src/vatom/Ghost.cpp b/src/vatom/Ghost.cpp index adedc4c223..773ed6fe4d 100644 --- a/src/vatom/Ghost.cpp +++ b/src/vatom/Ghost.cpp @@ -32,30 +32,39 @@ namespace vatom { /* Calculate the absolute position of a ghost atom with fixed coordinates in the local reference frame formed by three atoms. -The computed ghost atom is stored as a virtual atom that can be accessed in - an atom list through the the label for the GHOST action that creates it. +This action allows you to create a virtual atom that has a fixed set of coordinates in a local reference +frame that is formed by three atoms. The way that this action is used is illustrated below: -When running with periodic boundary conditions, the atoms should be -in the proper periodic image. This is done automatically since PLUMED 2.10, -by considering the ordered list of atoms and rebuilding the molecule using a procedure -that is equivalent to that done in \ref WHOLEMOLECULES . Notice that -rebuilding is local to this action. This is different from \ref WHOLEMOLECULES -which actually modifies the coordinates stored in PLUMED. - -In case you want to recover the old behavior you should use the NOPBC flag. -In that case you need to take care that atoms are in the correct -periodic image. - -\par Examples - -The following input instructs plumed to print the distance between the -ghost atom and the center of mass for atoms 15,20: -\plumedfile +```plumed c1: GHOST ATOMS=1,5,10 COORDINATES=10.0,10.0,10.0 c2: COM ATOMS=15,20 d1: DISTANCE ATOMS=c1,c2 PRINT ARG=d1 -\endplumedfile +``` + +Notice that ghost atom's position is stored as [a virtual atom](specifying_atoms.md). The position of this atom can thus be +used in the DISTANCE command by using the label for the GHOST action. + +The position of the ghost atom `c1` for the input above is: + +$$ +r_{c1} = r_1 + 10\hat{a} + 10c + 10 \hat{b} 10\hat{c} +$$ + +where unit vectors, $\hat{a}$, $\hat{b}$ and $\hat{c}$ in the expression above are obtained by dividing each +of the three (orthogonal) vectors below by their magnitudes: + +$$ +a = (r_5-r_1) \quad b = (r_5-r_1) \time (r_{10}-r_1) \quad (r_5-r_1)\times b +$$ + +In all these expressions $r_i$ is used to indicate the position of atom $i$. If you run with periodic boundary conditions +these are taken into account automatically when computing the differences between position vectors above. The way this is +handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command. For the example above +this would ensure that atom 5 is shifted to the periodic image where it is closest to atom 1 and atom 10 is shifted to the +periodic image where it is closest to atom 10. If you wish to +turn off this behaviour and you wish to disregard the periodic boundaries when computing these differences you should use +the NOPBC flag. */ //+ENDPLUMEDOC