Merge branch 'v2.3'

src/colvar/RMSD.cpp

@@ -105,6 +105,7 @@ you really know what you are doing however as the results can be rather strange.
 In PDB files the atomic coordinates and box lengths should be in Angstroms unless
 you are working with natural units.  If you are working with natural units then the coordinates
 should be in your natural length unit.  For more details on the PDB file format visit http://www.wwpdb.org/docs.html.
+Make sure your PDB file is correclty formatted as explained \ref pdbreader "in this page".
 
 A different method is used to calculate the RMSD distance when you use TYPE=OPTIMAL on the input line.  In this case  the root mean square
 deviation is calculated after the positions of geometric centers in the reference and instantaneous configurations are aligned AND after

src/generic/FitToTemplate.cpp

@@ -48,8 +48,9 @@ namespace generic {
 This action is used to align a molecule to a template.
 
 This can be used to move the coordinates stored in plumed
-so as to be aligned with a provided template in pdb format. Pdb should contain
-also weights for alignment (see the format of pdb files used e.g. for \ref RMSD).
+so as to be aligned with a provided template in PDB format. Pdb should contain
+also weights for alignment (see the format of PDB files used e.g. for \ref RMSD).
+Make sure your PDB file is correclty formatted as explained \ref pdbreader "in this page".
 Weights for displacement are ignored, since no displacement is computed here.
 Notice that all atoms (not only those in the template) are aligned.
 To see what effect try

src/setup/MolInfo.cpp

@@ -37,12 +37,14 @@ then use this information in later commands to specify atom lists in terms resid
 using this command you can find the backbone atoms in your structure automatically.
 
 \warning
-Please be aware that the pdb parser in plumed is far from perfect. You should thus check the log file
+Please be aware that the PDB parser in plumed is far from perfect. You should thus check the log file
 and examine what plumed is actually doing whenenver you use the MOLINFO action.
 Also make sure that the atoms are listed in the pdb with the correct order.
 If you are using gromacs, the safest way is to use reference pdb file
 generated with `gmx editconf -f topol.tpr -o reference.pdb`.
 
+More information of the PDB parser implemented in PLUMED can be found \ref pdbreader "at this page".
+
 
 Using MOLINFO with a protein's or nucleic acid's pdb extends the possibility of atoms selection using the @ special
 symbol.

src/tools/PDB.cpp

@@ -27,6 +27,76 @@
 
 using namespace std;
 
+//+PLUMEDOC INTERNAL pdbreader
+/*
+
+PLUMED use PDB formats in several places, including
+- To read molecular structure (\ref MOLINFO).
+- To read reference conformations (\ref RMSD, but also many other methods in \ref dists, \ref FIT_TO_TEMPLATE, etc).
+
+The implemented PDB reader expects a file formatted correctly according to the
+[PDB standard](http://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html).
+In particular, the following columns are read from ATOM records
+\verbatim
+columns | content
+1-6     | record name (ATOM or HETATM)
+7-11    | serial number of the atom (starting from 1)
+13-16   | atom name
+18-20   | residue name
+22      | chain id
+23-26   | residue number
+31-38   | x coordinate
+39-46   | y coordinate
+47-54   | z coordinate
+55-60   | occupancy
+61-66   | beta factor
+\endverbatim
+PLUMED parser is slightly more permissive than the official PDB format
+in the fact that the format of real numbers is not fixed. In other words,
+any parsable real number is ok and the dot can be placed anywhere. However,
+__columns are interpret strictly__. A sample PDB should look like the following
+\verbatim
+ATOM      2  CH3 ACE     1      12.932 -14.718  -6.016  1.00  1.00
+ATOM      5  C   ACE     1      21.312  -9.928  -5.946  1.00  1.00
+ATOM      9  CA  ALA     2      19.462 -11.088  -8.986  1.00  1.00
+\endverbatim
+
+Notice that serial numbers need not to be consecutive. In the three-line example above,
+only the coordinates of three atoms are provided. This is perfectly legal and indicates PLUMED
+that information about these atoms only is available. This could be both for structural
+information in \ref MOLINFO, where the other atoms would have no name assigned, and for
+reference structures used in \ref RMSD, where only the provided atoms would be used to compute RMSD.
+
+\par Occupancy and beta factors
+
+PLUMED reads also occupancy and beta factors that however are given a very special meaning.
+In cases where the PDB structure is used as a reference for an alignment (that's the case
+for instance in \ref RMSD and in \ref FIT_TO_TEMPLATE), the occupancy column is used
+to provide the weight of each atom in the alignment. In cases where, perhaps after alignment,
+the displacement between running coordinates and the provided PDB is computed, the beta factors
+are used as weight for the displacement.
+Since setting the weights to zero is the same as __not__ including an atom in the alignement or
+displacement calculation, the two following reference files would be equivalent when used in an \ref RMSD
+calculation. First file:
+\verbatim
+ATOM      2  CH3 ACE     1      12.932 -14.718  -6.016  1.00  1.00
+ATOM      5  C   ACE     1      21.312  -9.928  -5.946  1.00  1.00
+ATOM      9  CA  ALA     2      19.462 -11.088  -8.986  0.00  0.00
+\endverbatim
+Second file:
+\verbatim
+ATOM      2  CH3 ACE     1      12.932 -14.718  -6.016  1.00  1.00
+ATOM      5  C   ACE     1      21.312  -9.928  -5.946  1.00  1.00
+\endverbatim
+However notice that many extra atoms with zero weight might slow down the calculation, so
+removing lines is better than setting their weights to zero.
+In addition, weights for alignment need not to be equivalent to weights for displacement.
+
+
+*/
+//+ENDPLUMEDOC
+
+
 namespace PLMD {
 
 unsigned PDB::getNumberOfAtomBlocks()const {

user-doc/Colvar.txt

@@ -58,6 +58,8 @@ with the ammount the collective variables change.  A full list of the ways dista
 
 These options for calculating distances are re-used in a number of places in the code.  For instance they are used in some of the 
 analysis algorithms that are implemented in PLUMED and in \ref PATH collective variables. 
+Notice that most of these actions read the reference configuration from a PDB file. Be sure
+you understand how to format properly a PDB file to use used in PLUMED (see \ref pdbreader).
 
 \page mcolv MultiColvar