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

# dump coordinates before fitting, to see the difference:
DUMPATOMS FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=dump-before.xyz ATOMSthe atom indices whose positions you would like to print out. 
=1-20 The DUMPATOMS action with label 
# fit coordinates to ref.pdb template
# this is a "TYPE=SIMPLE" fit, so that only translations are used.
FIT_TO_TEMPLATE STRIDEcompulsory keyword ( default=1 )
the frequency with which molecules are reassembled. 
=1 REFERENCEcompulsory keyword 
a file in pdb format containing the reference structure and the atoms involved in
the CV. 
=ref.pdb TYPEcompulsory keyword ( default=SIMPLE )
the manner in which RMSD alignment is performed. 
=SIMPLE The FIT_TO_TEMPLATE action with label 
# dump coordinates after fitting, to see the difference:
DUMPATOMS FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=dump-after.xyz ATOMSthe atom indices whose positions you would like to print out. 
=1-20 The DUMPATOMS action with label

The following example instead performs a rototranslational fit.

Click on the labels of the actions for more information on what each action computes

# dump coordinates before fitting, to see the difference:
DUMPATOMS FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=dump-before.xyz ATOMSthe atom indices whose positions you would like to print out. 
=1-20 The DUMPATOMS action with label 
# fit coordinates to ref.pdb template
# this is a "TYPE=OPTIMAL" fit, so that rototranslations are used.
FIT_TO_TEMPLATE STRIDEcompulsory keyword ( default=1 )
the frequency with which molecules are reassembled. 
=1 REFERENCEcompulsory keyword 
a file in pdb format containing the reference structure and the atoms involved in
the CV. 
=ref.pdb TYPEcompulsory keyword ( default=SIMPLE )
the manner in which RMSD alignment is performed. 
=OPTIMAL The FIT_TO_TEMPLATE action with label 
# dump coordinates after fitting, to see the difference:
DUMPATOMS FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=dump-after.xyz ATOMSthe atom indices whose positions you would like to print out. 
=1-20 The DUMPATOMS action with label

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

# center of the ligand:
center: CENTER ATOMSthe list of atoms which are involved the virtual atom's definition. 
=100-110 The CENTER action with label center calculates the position of a virtual atom
FIT_TO_TEMPLATE REFERENCEcompulsory keyword 
a file in pdb format containing the reference structure and the atoms involved in
the CV. 
=ref.pdb TYPEcompulsory keyword ( default=SIMPLE )
the manner in which RMSD alignment is performed. 
=OPTIMAL The FIT_TO_TEMPLATE action with label 
# place a fixed atom in the protein reference coordinates:
fix: FIXEDATOM ATcompulsory keyword 
coordinates of the virtual atom 
=1.0,1.1,1.0 The FIXEDATOM action with label fix calculates the position of a virtual atom
# take the distance between the fixed atom and the center of the ligand
d: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. 
=center,fix The DISTANCE action with label d calculates a single scalar value
# apply a restraint
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. 
=d ATcompulsory keyword 
the position of the restraint 
=0.0 KAPPAcompulsory 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 The RESTRAINT action with label

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