Fixed more documentation

Gareth Aneurin Tribello · Gareth Aneurin Tribello · commit 5dab89c085bb · 2025-06-08T21:25:24.000+01:00
diff --git a/src/bias/BiasValue.cpp b/src/bias/BiasValue.cpp
@@ -107,6 +107,7 @@ void BiasValue::registerKeywords(Keywords& keys) {
                           "these quantities will named with  the arguments of the bias followed by "
                           "the character string _bias. These quantities tell the user how much the bias is "
                           "due to each of the colvars.");
+  keys.reset_style("NUMERICAL_DERIVATIVES","hidden");
 }
 
 BiasValue::BiasValue(const ActionOptions&ao):
diff --git a/src/colvar/DRMSD.cpp b/src/colvar/DRMSD.cpp
@@ -64,14 +64,21 @@ position. Only pairs of atoms whose distance in the reference structure is withi
 
 ```plumed
 #SETTINGS INPUTFILES=regtest/basic/rt-drmsd/test1.pdb
-DRMSD REFERENCE=regtest/basic/rt-drmsd/test1.pdb LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8
+d: DRMSD ...
+  REFERENCE=regtest/basic/rt-drmsd/test1.pdb
+  LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8
+...
 ```
 
-The following tells plumed to calculate a DRMSD value for a pair of molecules.
+The following tells plumed to calculate the square of the DRMSD value for a pair of molecules.
 
 ```plumed
 #SETTINGS INPUTFILES=regtest/basic/rt-drmsd/test0.pdb
-DRMSD REFERENCE=regtest/basic/rt-drmsd/test0.pdb LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8 TYPE=INTER-DRMSD
+d: DRMSD ...
+  REFERENCE=regtest/basic/rt-drmsd/test0.pdb
+  LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8 TYPE=INTER-DRMSD
+  SQUARED
+...
 ```
 
 Notice that in the input reference file (which you can see by clicking on regtest/basic/rt-drmsd/test0.pdb )
@@ -83,6 +90,20 @@ quantity is computed involve one atom from each of the two molecules.  If this i
 by INTRA-DRMSD then only those distances involving pairs of atoms that are both in the same
 molecule are computed.
 
+## Periodic boundary conditions
+
+Notice that PLUMED does not use periodic boundary conditions when computing the reference distances.  However, the instantaneous
+values of the distances are computed using periodic boundary conditions.  If you would like not to use periodic boundary conditions
+when computing these instaneous distances you use the NOPBC flag as illustrated below:
+
+```plumed
+#SETTINGS INPUTFILES=regtest/basic/rt-drmsd/test1.pdb
+d: DRMSD ...
+  REFERENCE=regtest/basic/rt-drmsd/test1.pdb
+  LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8 NOPBC
+...
+```
+
 */
 //+ENDPLUMEDOC
 
@@ -106,7 +127,7 @@ void DRMSD::registerKeywords( Keywords& keys ) {
   keys.addFlag("SQUARED",false,"This should be setted if you want MSD instead of RMSD ");
   keys.addFlag("NOPBC",false,"ignore the periodic boundary conditions when calculating distances");
   // This is just ignored in reality which is probably bad
-  keys.addFlag("NUMERICAL_DERIVATIVES",false,"calculate the derivatives for these quantities numerically");
+  keys.addDeprecatedFlag("NUMERICAL_DERIVATIVES","");
   keys.setValueDescription("scalar/vector","the DRMSD distance between the instantaneous structure and the reference structure");
   keys.needsAction("SUM");
   keys.needsAction("DISTANCE");
diff --git a/src/colvar/Dipole.cpp b/src/colvar/Dipole.cpp
@@ -52,6 +52,7 @@ PRINT ARG=d.* FILE=output
 
 This command will output three values d.x, d.y and d.z, which are the x, y and z components of the dipole respectively.
 
+
 You can calculate three instinguishable dipoles using a single DIPOLE command by using an input like the one below:
 
 ```plumed
@@ -71,14 +72,15 @@ PRINT ARG=d.x,d.y,d.z FILE=output
 The output from the DIPOLE command now consists of three three dimensional vectors called d.x, d.y and d.z that contain the
 x, y and z components of the three dipoles respectively.
 
-When running with periodic boundary conditions, the atoms in every group should be
-in the proper periodic image. This is done automatically since PLUMED 2.5,
-by considering the ordered list of atoms and rebuilding the molecule with a procedure
-that is equivalent to that done in [WHOLEMOLECULES](WHOLEMOLECULES.md). Notice that
-rebuilding is local to this action. This is different from [WHOLEMOLECULES](WHOLEMOLECULES.md)
-which actually modifies the coordinates stored in PLUMED.  If 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.
+A final important thing to note is that in all the commands above the default is to use a procedure akin to that used in [WHOLEMOLECULES](WHOLEMOLECULES.md) to ensure
+that the sets of atoms that are specified to each GROUP keyword are not broken by the periodic
+boundary conditions.  If you would like to turn this off for any reason you add the NOPBC in your input file as shown
+below:
+
+```plumed
+d: DIPOLE GROUP=1-10 NOPBC
+PRINT FILE=output STRIDE=5 ARG=d
+```
 
 !!! caution "behaviour for non charge neutral groups"
 
diff --git a/src/colvar/Plane.cpp b/src/colvar/Plane.cpp
@@ -44,7 +44,13 @@ PRINT ARG=p.x,p.y,p.z FILE=colvar
 
 The three components, p.x, p.y and p.z, output by the PLANE action here are the x, y and z components of the normal
 vector to the plane that is obtained by taking the cross product between the vector connecting atoms 1 and 2 and
-the vector connecting atoms 2 and 3.
+the vector connecting atoms 2 and 3.  Notice that the default here is to evaluate these two vectors in a way that takes
+any periodic boundary conditions (PBC) into account. If you wish to disregard the PBC you can use the NOPBC flag as shown in the following input:
+
+```plumed
+p: PLANE ATOMS=1,2,3 NOPBC
+PRINT ARG=p.x,p.y,p.z FILE=colvar
+```
 
 To calculate the cross product of the vector connecting atoms 1 and 2 and the vector connecting atoms 3 and 4 you use
 an input like this:
diff --git a/src/contour/DumpContour.cpp b/src/contour/DumpContour.cpp
@@ -55,16 +55,22 @@ center: CENTER ATOMS=1-96000 WEIGHTS=tfcc
 # This determines the positions of the atoms of interest relative to the center of the solid region
 dens_dist: DISTANCES ORIGIN=center ATOMS=1-96000 COMPONENTS
 # This computes the numerator in the expression above for the phase field
-dens_numer: KDE VOLUMES=tfcc ARG=dens_dist.x,dens_dist.y,dens_dist.z GRID_BIN=80,80,80 BANDWIDTH=1.0,1.0,1.0
+dens_numer: KDE ...
+  VOLUMES=tfcc ARG=dens_dist.x,dens_dist.y,dens_dist.z
+  GRID_BIN=80,80,80 BANDWIDTH=1.0,1.0,1.0
+...
 # This computes the denominator
-dens_denom: KDE ARG=dens_dist.x,dens_dist.y,dens_dist.z GRID_BIN=80,80,80 BANDWIDTH=1.0,1.0,1.0
+dens_denom: KDE ...
+  ARG=dens_dist.x,dens_dist.y,dens_dist.z
+  GRID_BIN=80,80,80 BANDWIDTH=1.0,1.0,1.0
+...
 # This computes the final phase field
 dens: CUSTOM ARG=dens_numer,dens_denom FUNC=x/y PERIODIC=NO
 
 # Find the isocontour
 cont: FIND_CONTOUR ARG=dens CONTOUR=0.5
 # Use the special method for outputting the contour to a file
-DUMPCONTOUR ARG=cont FILE=surface.xyz
+DUMPCONTOUR ARG=cont FILE=surface.xyz STRIDE=1 FMT=%8.4f
 ```
 
 */
@@ -92,13 +98,12 @@ void DumpContour::registerKeywords( Keywords& keys ) {
   keys.addInputKeyword("compulsory","ARG","vector","the labels of the FIND_CONTOUR action that you would like to output");
   keys.add("compulsory","STRIDE","1","the frequency with which the grid should be output to the file.");
   keys.add("compulsory","FILE","density","the file on which to write the grid.");
-  keys.add("optional","FMT","the format that should be used to output real numbers");
+  keys.add("compulsory","FMT","%f","the format that should be used to output real numbers");
 }
 
 DumpContour::DumpContour(const ActionOptions&ao):
   Action(ao),
-  ActionPilot(ao),
-  fmt("%f") {
+  ActionPilot(ao) {
 
   std::string argname;
   parse("ARG",argname);
diff --git a/src/core/ActionToPutData.cpp b/src/core/ActionToPutData.cpp
@@ -61,14 +61,19 @@ You would only use the PUT command if you were calling PLUMED from python or an
 # This is how you create a value to hold the energy the MD code passes energy in plumed
 eng: PUT UNIT=energy PERIODIC=NO
 # This is how you create an vector of the 100 x positions to plumed
-xpos: PUT SHAPE=100 UNIT=length PERIODIC=NO
+# Notice how we use ROLE here in order to tell PLUMED that these are the x coordinates.
+# Further note that we need to use the FROM_DOMAINS flag if the MD code we are using uses
+# domain decomposition.
+xpos: PUT SHAPE=100 UNIT=length PERIODIC=NO ROLE=x FROM_DOMAINS
 # This is how you create a scalar to hold the timestep
 # The constant flag indicates that the value of the timestep doesn't change during the simulation
 tstep: PUT CONSTANT UNIT=time PERIODIC=NO
 # This is how you create a value to hold a 10 x 10 matrix in plumed whose elements are unitless
 matrix: PUT SHAPE=10,10 UNIT=number PERIODIC=NO
 # Lastly, if you want to pass a value that has a periodic domain you can do so as follows
-tor: PUT UNIT=number PERIODIC=-pi,pi
+# By adding the MUTABLE flag here we pass the data to PLUMED in a way that ensures that PLUMED can modify
+# the value that was passed from the MD code and thus pass back a different value to the underlying MD code.
+tor: PUT UNIT=number PERIODIC=-pi,pi MUTABLE
 ```
 
 */
diff --git a/src/core/Group.cpp b/src/core/Group.cpp
@@ -87,7 +87,7 @@ Further notice that starting from version 2.10 it is possible to directly use an
 DUMPATOMS ATOMS={@ndx:{extras/index.ndx Protein}} FILE=traj.gro
 ```
 
-Lastly notice that it is also possible to remove atoms from the list of atoms specified in a GROUP by using the keywords `REMOVE`, `SORT`, and `UNIQUE` as shown below:
+Notice that it is possible to remove atoms from the list of atoms specified in a GROUP by using the keyword `REMOVE` as shown below:
 
 ```plumed
 # take one atom every three, that is oxygens
@@ -98,6 +98,22 @@ DUMPATOMS ATOMS=ox FILE=ox.gro
 DUMPATOMS ATOMS=hy FILE=hy.gro
 ```
 
+You can also `SORT` the atoms in a group into ascending order by using the SORT keyword as shown below:
+
+```plumed
+# If you ask for this group in the input to another action the atoms will be
+# in ascending order i.e. the specified atoms will be 2,3,4,4,5,6
+g: GROUP ATOMS=5,4,6,3,4,2 SORT
+```
+
+or you can sort the atoms and remove duplicated atoms by using the `UNIQUE` flag
+
+```plumed
+# If you ask for this group in the input to another action the duplicate atom specifications will be removed
+# and the atoms will be ascending order i.e. the specified atoms will be 2,3,4,5,6
+g: GROUP ATOMS=5,4,6,3,4,2 UNIQUE
+```
+
 When you used the GROUP command the flow as follows:
 
 - If `ATOMS` is present, then take the ordered list of atoms from the `ATOMS` keyword as a starting list.
diff --git a/src/function/Custom.cpp b/src/function/Custom.cpp
@@ -486,6 +486,9 @@ and that the MATHEVAL action evaluates functions [the Lepton library](https://si
 //+ENDPLUMEDOC
 
 void Custom::registerKeywords(Keywords& keys) {
+  if( keys.getDisplayName()=="MATHEVAL") {
+    keys.setDeprecated("CUSTOM");
+  }
   keys.use("PERIODIC");
   keys.add("compulsory","FUNC","the function you wish to evaluate");
   keys.add("optional","VAR","the names to give each of the arguments in the function.  If you have up to three arguments in your function you can use x, y and z to refer to them.  Otherwise you must use this flag to give your variables names.");
diff --git a/src/generic/UpdateIf.cpp b/src/generic/UpdateIf.cpp
@@ -58,7 +58,19 @@ only when another variable is within a given range.
 
 ## Examples
 
-The following input instructs plumed dump all the snapshots where an atom is in touch with
+The following input instructs plumed to dump all the snapshots in which atoms 1 and 2 are within
+0.3 nm of each other:
+
+```plumed
+d: DISTANCE ATOMS=1,2
+UPDATE_IF ARG=d LESS_THAN=0.3 STRIDE=1
+DUMPATOMS ATOMS=@mdatoms FILE=output.xyz
+UPDATE_IF ARG=d END
+```
+
+Notice, that the STRIDE is set equal to one by default.  You will likely always want to set it to this value.
+
+The following input instructs plumed to dump all the snapshots where an atom is in touch with
 the solute.
 
 ```plumed
diff --git a/src/gridtools/ReadGridInSetup.cpp b/src/gridtools/ReadGridInSetup.cpp
@@ -57,6 +57,15 @@ function at the various grid points.
 
 N.B. This method with lepton was implemented to facilitate the implementation of the normalisation in the implementation of the [RDF](RDF.md) shortcut.
 
+Lastly note that you can specify the grid spacing in the input to this action rather than the number of bins as shown below:
+
+```plumed
+d2: REFERENCE_GRID GRID_MIN=0 GRID_MAX=10 GRID_SPACING=0.5 FUNC=d1*d1 VAR=d1 PERIODIC=NO
+d1: DISTANCE ATOMS=1,2
+ff: EVALUATE_FUNCTION_FROM_GRID GRID=d2
+PRINT ARG=d1,ff FMT=%8.4f FILE=colvar
+```
+
 */
 //+ENDPLUMEDOC
 
@@ -85,7 +94,7 @@ class ReadGridInSetup : public ActionWithGrid {
   std::vector<std::string> dernames;
   void createGridAndValue( const std::string& gtype, const std::vector<bool>& ipbc, const unsigned& nfermi,
                            const std::vector<std::string>& gmin, const std::vector<std::string>& gmax,
-                           const std::vector<std::size_t>& gbin );
+                           const std::vector<std::size_t>& gbin, std::vector<double>& gspacing );
 public:
   static void registerKeywords( Keywords& keys );
   explicit ReadGridInSetup(const ActionOptions&ao);
@@ -130,6 +139,8 @@ ReadGridInSetup::ReadGridInSetup(const ActionOptions&ao):
     parseVector("GRID_MAX",gmax);
     std::vector<std::size_t> gbin(gmin.size());
     parseVector("GRID_BIN",gbin);
+    std::vector<double> spacing(gmin.size());
+    parseVector("GRID_SPACING",spacing);
     std::vector<std::string> pbc(gmin.size());
     parseVector("PERIODIC",pbc);
     std::vector<bool> ipbc( pbc.size() );
@@ -165,7 +176,7 @@ ReadGridInSetup::ReadGridInSetup(const ActionOptions&ao):
     }
 
     // Create the grid and the value of the grid
-    createGridAndValue( "flat", ipbc, 0, gmin, gmax, gbin );
+    createGridAndValue( "flat", ipbc, 0, gmin, gmax, gbin, spacing );
 
     // Read in stuff for function
     log.printf("  evaluating function : %s\n",func.c_str());
@@ -275,7 +286,8 @@ ReadGridInSetup::ReadGridInSetup(const ActionOptions&ao):
     if( !flatgrid ) {
       ifile.scanField( "nbins", gbin1);
       gbin[0]=gbin1;
-      createGridAndValue( "fibonacci", ipbc, gbin[0], gmin, gmax, gbin );
+      std::vector<double> spacing;
+      createGridAndValue( "fibonacci", ipbc, gbin[0], gmin, gmax, gbin, spacing );
     } else {
       for(unsigned i=0; i<dernames.size(); ++i) {
         ifile.scanField( "min_" + dernames[i], gmin[i]);
@@ -298,7 +310,8 @@ ReadGridInSetup::ReadGridInSetup(const ActionOptions&ao):
           plumed_merror("missing derivatives from grid file");
         }
       }
-      createGridAndValue( "flat", ipbc, 0, gmin, gmax, gbin );
+      std::vector<double> spacing;
+      createGridAndValue( "flat", ipbc, 0, gmin, gmax, gbin, spacing );
     }
     // And finally read all the grid points
     Value* valout=getPntrToComponent(0);
@@ -338,9 +351,8 @@ ReadGridInSetup::ReadGridInSetup(const ActionOptions&ao):
 
 void ReadGridInSetup::createGridAndValue( const std::string& gtype, const std::vector<bool>& ipbc, const unsigned& nfermi,
     const std::vector<std::string>& gmin, const std::vector<std::string>& gmax,
-    const std::vector<std::size_t>& gbin ) {
+    const std::vector<std::size_t>& gbin, std::vector<double>& gspacing ) {
   gridobject.setup( gtype, ipbc, nfermi, 0.0 );
-  std::vector<double> gspacing;
   if( gtype=="flat" ) {
     gridobject.setBounds( gmin, gmax, gbin, gspacing );
     // Now create the value
diff --git a/src/refdist/EuclideanDistance.cpp b/src/refdist/EuclideanDistance.cpp
@@ -42,7 +42,7 @@ which can be expressed in matrix form as:
 d^2 = (u-v)^T (u-v)
 $$
 
-The inputs below shows an example where this is used to calculate the Euclidean distance
+The input below shows an example where this is used to calculate the Euclidean distance
 between the instaneous values of some torsional angles and some reference values
 for these torsion.  In this first example the input values are vectors:
 
@@ -66,6 +66,18 @@ dd: EUCLIDEAN_DISTANCE ARG1=c1,c2,c3 ARG2=d1,d2,d3
 PRINT ARG=dd FILE=colvar
 ```
 
+Lastly, note that if you want to calculate the square of the distance rather than the distance you can use
+the `SQUARED` flag as shown below:
+
+```plumed
+c: CONSTANT VALUES=1,2,3
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6
+dd: EUCLIDEAN_DISTANCE ARG1=c ARG2=d SQUARED
+PRINT ARG=dd FILE=colvar
+```
+
+Calculating the square of the distance is slightly cheapter than computing the distance as you avoid taking the square root.
+
 ## Calculating multiple distances
 
 Suppose that we now have $m$ reference configurations we can define the following $m$ distances
diff --git a/src/refdist/MahalanobisDistance.cpp b/src/refdist/MahalanobisDistance.cpp
@@ -67,6 +67,19 @@ dd: MAHALANOBIS_DISTANCE ARG1=c1,c2 ARG2=d1,d2 METRIC=m
 PRINT ARG=dd FILE=colvar
 ```
 
+Lastly, note that if you want to calculate the square of the distance rather than the distance you can use
+the `SQUARED` flag as shown below:
+
+```plumed
+m: CONSTANT VALUES=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS=2 NCOLS=2
+c: CONSTANT VALUES=1,2
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4
+dd: MAHALANOBIS_DISTANCE ARG1=c ARG2=d METRIC=m SQUARED
+PRINT ARG=dd FILE=colvar
+```
+
+Calculating the square of the distance is slightly cheapter than computing the distance as you avoid taking the square root.
+
 ## Dealing with periodic variables
 
 When you are calculating a distance from a reference point you need to be careful when the input variables
diff --git a/src/refdist/NormalizedEuclideanDistance.cpp b/src/refdist/NormalizedEuclideanDistance.cpp
@@ -72,6 +72,19 @@ dd: NORMALIZED_EUCLIDEAN_DISTANCE ARG1=c1,c2,c3 ARG2=d1,d2,d3 METRIC=m
 PRINT ARG=dd FILE=colvar
 ```
 
+Lastly, note that if you want to calculate the square of the distance rather than the distance you can use
+the `SQUARED` flag as shown below:
+
+```plumed
+m: CONSTANT VALUES=0.1,0.2,0.3
+c: CONSTANT VALUES=1,2,3
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6
+dd: NORMALIZED_EUCLIDEAN_DISTANCE ARG1=c ARG2=d METRIC=m SQUARED
+PRINT ARG=dd FILE=colvar
+```
+
+Calculating the square of the distance is slightly cheapter than computing the distance as you avoid taking the square root.
+
 ## Calculating multiple distances
 
 Suppose that we now have $m$ reference configurations we can define the following $m$ distances
@@ -84,7 +97,7 @@ d_j^2 = (u-v_j)^T a \odot (u-v_j)
 Lets suppose that we put the $m$, $n$-dimensional $(u-v_j)$ vectors in this expression into a
 $n\times m$ matrix, $A$, by using the [DISPLACEMENT](DISPLACEMENT.md) command.  It is then
 straightforward to show that the $d_j^2$ values in the above expression are the diagonal
-elements of the matrix product $A^T K \odot A$, where $K$ is an $n \times $m$ matrix that contains
+elements of the matrix product $A^T K \cdot A$, where $K$ is an $n \times m$ matrix that contains
 $m$ copies of the inverse covariance matrix $a$ in its columns.
 
 We can use this idea to calculate multiple NORMALIZED_EUCLIDEAN_DISTANCE values in the following inputs.
diff --git a/src/setup/Units.cpp b/src/setup/Units.cpp

Original file line number	Diff line number	Diff line change
`@@ -107,6 +107,7 @@ void BiasValue::registerKeywords(Keywords& keys) {`
`107`	`107`	`"these quantities will named with the arguments of the bias followed by "`
`108`	`108`	`"the character string _bias. These quantities tell the user how much the bias is "`
`109`	`109`	`"due to each of the colvars.");`
	`110`	`+ keys.reset_style("NUMERICAL_DERIVATIVES","hidden");`
`110`	`111`	`}`
`111`	`112`
`112`	`113`	`BiasValue::BiasValue(const ActionOptions&ao):`