FIT_TO_TEMPLATE
This is part of the generic module

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 RMSD). Make sure your PDB file is correctly formatted as explained 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 the DUMPATOMS directive to output the atomic positions.

Also notice that PLUMED propagate forces correctly so that you can add a bias on a CV computed after alignment. For many CVs this has no effect, but in some case the alignment can change the result. Examples are:

  • POSITION CV since it is affected by a rigid shift of the system.
  • DISTANCE CV with COMPONENTS. Since the alignment could involve a rotation (with TYPE=OPTIMAL) the actual components could be different from the original ones.
  • CELL components for a similar reason.
  • DISTANCE from a FIXEDATOM, provided the fixed atom is introduced after the FIT_TO_TEMPLATE action.
Attention
The implementation of TYPE=OPTIMAL is available but should be considered in testing phase. Please report any strange behavior.
This directive modifies the stored position at the precise moment it is executed. This means that only collective variables which are below it in the input script will see the corrected positions. As a general rule, put it at the top of the input file. Also, unless you know exactly what you are doing, leave the default stride (1), so that this action is performed at every MD step.

When running with periodic boundary conditions, the atoms 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 molecules using a procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This is different from 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.

Examples

Align the atomic position to a template then print them. The following example is only translating the system so as to align the center of mass of a molecule to the one in the reference structure ref.pdb:

Click on the labels of the actions for more information on what each action computes
tested on master
# dump coordinates before fitting, to see the difference:
DUMPATOMS 
FILE
compulsory keyword file on which to output coordinates; extension is automatically detected
=dump-before.xyz
ATOMS
the atom indices whose positions you would like to print out.
=1-20 # fit coordinates to ref.pdb template # this is a "TYPE=SIMPLE" fit, so that only translations are used. FIT_TO_TEMPLATE
STRIDE
compulsory keyword ( default=1 ) the frequency with which molecules are reassembled.
=1
REFERENCE
compulsory keyword a file in pdb format containing the reference structure and the atoms involved in the CV.
=ref.pdb
TYPE
compulsory keyword ( default=SIMPLE ) the manner in which RMSD alignment is performed.
=SIMPLE # dump coordinates after fitting, to see the difference: DUMPATOMS
FILE
compulsory keyword file on which to output coordinates; extension is automatically detected
=dump-after.xyz
ATOMS
the atom indices whose positions you would like to print out.
=1-20

The following example instead performs a rototranslational fit.

Click on the labels of the actions for more information on what each action computes
tested on master
# dump coordinates before fitting, to see the difference:
DUMPATOMS 
FILE
compulsory keyword file on which to output coordinates; extension is automatically detected
=dump-before.xyz
ATOMS
the atom indices whose positions you would like to print out.
=1-20 # fit coordinates to ref.pdb template # this is a "TYPE=OPTIMAL" fit, so that rototranslations are used. FIT_TO_TEMPLATE
STRIDE
compulsory keyword ( default=1 ) the frequency with which molecules are reassembled.
=1
REFERENCE
compulsory keyword a file in pdb format containing the reference structure and the atoms involved in the CV.
=ref.pdb
TYPE
compulsory keyword ( default=SIMPLE ) the manner in which RMSD alignment is performed.
=OPTIMAL # dump coordinates after fitting, to see the difference: DUMPATOMS
FILE
compulsory keyword file on which to output coordinates; extension is automatically detected
=dump-after.xyz
ATOMS
the atom indices whose positions you would like to print out.
=1-20

In both these cases the reference structure should be provided in a reference pdb file such as the one below:

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

In the following example you see two completely equivalent way to restrain an atom close to a position that is defined in the reference frame of an aligned molecule. You could for instance use this command to calculate the position of the center of mass of a ligand after having aligned the atoms to the reference frame of the protein that is determined by aligning the atoms in the protein to the coordinates provided in the file ref.pdb

Click on the labels of the actions for more information on what each action computes
tested on master
# center of the ligand:
center: CENTER 
ATOMS
the list of atoms which are involved the virtual atom's definition.
=100-110 FIT_TO_TEMPLATE
REFERENCE
compulsory keyword a file in pdb format containing the reference structure and the atoms involved in the CV.
=ref.pdb
TYPE
compulsory keyword ( default=SIMPLE ) the manner in which RMSD alignment is performed.
=OPTIMAL # place a fixed atom in the protein reference coordinates: fix: FIXEDATOM
AT
compulsory keyword coordinates of the virtual atom
=1.0,1.1,1.0 # take the distance between the fixed atom and the center of the ligand d: DISTANCE
ATOMS
the pair of atom that we are calculating the distance between.
=center,fix # apply a restraint RESTRAINT
ARG
the input for this action is the scalar output from one or more other actions.
=d
AT
compulsory keyword the position of the restraint
=0.0
KAPPA
compulsory keyword ( default=0.0 ) specifies that the restraint is harmonic and what the values of the force constants on each of the variables are
=100.0

Notice that you could have obtained an (almost) identical result by adding a fictitious atom to ref.pdb with the serial number corresponding to the atom labelled center (there is no automatic way to get it, but in this example it should be the number of atoms of the system plus one), and properly setting the weights for alignment and displacement in RMSD. There are two differences to be expected: (ab) FIT_TO_TEMPLATE might be slower since it has to rototranslate all the available atoms and (b) variables employing periodic boundary conditions (such as DISTANCE without NOPBC, as in the example above) are allowed after FIT_TO_TEMPLATE, whereas RMSD expects the issues related to the periodic boundary conditions to be already solved. The latter means that before the RMSD statement one should use WRAPAROUND or WHOLEMOLECULES to properly place the ligand.

Glossary of keywords and components
Compulsory keywords
STRIDE ( default=1 ) the frequency with which molecules are reassembled. Unless you are completely certain about what you are doing leave this set equal to 1!
REFERENCE a file in pdb format containing the reference structure and the atoms involved in the CV.
TYPE ( default=SIMPLE ) the manner in which RMSD alignment is performed. Should be OPTIMAL or SIMPLE.
Options
NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances