Specifying Atoms

The vast majority of the CVs implemented in PLUMED are calculated from a list of atom positions. Within PLUMED atoms are specified using their numerical indices in the molecular dynamics input file.

In PLUMED lists of atoms can be either provided directly inside the definition of each collective variable, or predefined as a GROUP that can be reused multiple times. Lists of atoms can be written as:

comma separated lists of numbers (GROUP ATOMS=10,11,15,20 LABEL=g1)
numerical ranges. So GROUP ATOMS=10-20 LABEL=g2 is equivalent to GROUP ATOMS=10,11,12,13,14,15,16,17,18,19,20 LABEL=g2
numerical ranges with a stride. So GROUP ATOMS=10-100:10 LABEL=g3 is equivalent toGROUP ATOMS=10,20,30,40,50,60,70,80,90,100 LABEL=g3
atoms ranges with a negative stride. SoGROUP ATOMS=100-10:-10 LABEL=g4 is equivalent to GROUP ATOMS=100,90,80,70,60,50,40,30,20,10 LABEL=g4

In addition, there are a few shortcuts that can be used:

@mdatoms indicate all the physical atoms present in the MD engine (e.g. DUMPATOMS ATOMS=@mdatoms).
@allatoms indicates all atoms, including those defined only in PLUMED (e.g. DUMPATOMS ATOMS=@allatoms).

The list of the virtual atoms defined in PLUMED can be obtained by using the command GROUP ATOMS=@allatoms REMOVE=@mdatoms.

Other shortcuts are available if you loaded the structure of the molecule using the MOLINFO command.

All the above methods can be combined just putting one name after the other separated by a comma:

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

g5: DUMPATOMS ATOMSthe atom indices whose positions you would like to print out. 
=1,2,10-20,40-60:5,100-70:-2 FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=test.xyz The DUMPATOMS action with label g5

Some collective variable must accept a fixed number of atoms, for example a DISTANCE is calculated using two atoms only, an ANGLE is calculated using either 3 or 4 atoms and TORSION is calculated using 4 atoms.

Additional material and examples can be also found in the tutorial Belfast tutorial: Analyzing CVs.

Molecules

In addition, for certain colvars, pdb files can be read in using the following keywords and used to select ATOMS:

MOLINFO

This command is used to provide information on the molecules that are present in your system.

Broken Molecules and PBC

PLUMED is designed so that for the majority of the CVs implemented the periodic boundary conditions are treated in the same manner as they would be treated in the host code. In some codes this can be problematic when the colvars you are using involve some property of a molecule. These codes allow the atoms in the molecules to become separated by periodic boundaries, a fact which PLUMED could only deal with were the topology passed from the MD code to PLUMED. Making this work would involve a lot laborious programming and goes against our original aim of having a general patch that can be implemented in a wide variety of MD codes. Consequentially, we have implemented a more pragmatic solution to this problem - the user specifies in input any molecules (or parts of molecules) that must be kept in tact throughout the simulation run. In PLUMED 1 this was done using the ALIGN_ATOMS keyword. In PLUMED 2 the same effect can be achieved using the WHOLEMOLECULES command.

The following input computes the end-to-end distance for a polymer of 100 atoms and keeps it at a value around 5.

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

WHOLEMOLECULES ENTITY0the atoms that make up a molecule that you wish to align. 
=1-100 The WHOLEMOLECULES action with label 
e2e: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. 
=1,100 NOPBC( default=off ) ignore the periodic boundary conditions when calculating distances
 The DISTANCE action with label e2e calculates a single scalar value
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. 
=e2e 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 
=1 ATcompulsory keyword 
the position of the restraint 
=5 The RESTRAINT action with label

Notice that NOPBC is used to be sure in DISTANCE that if the end-to-end distance is larger than half the simulation box the distance is compute properly. Also notice that, since many MD codes break molecules across cell boundary, it might be necessary to use the WHOLEMOLECULES keyword (also notice that it should be before distance).

Notice that most expressions are invariant with respect to a change in the order of the atoms, but some of them depend on that order. E.g., with WHOLEMOLECULES it could be useful to specify atom lists in a reversed order.

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

# to see the effect, one could dump the atoms as they were before molecule reconstruction:
# DUMPATOMS FILE=dump-broken.xyz ATOMS=1-20
WHOLEMOLECULES STRIDEcompulsory keyword ( default=1 )
the frequency with which molecules are reassembled. 
=1 ENTITY0the atoms that make up a molecule that you wish to align. 
=1-20 The WHOLEMOLECULES action with label 
DUMPATOMS FILEcompulsory keyword 
file on which to output coordinates; extension is automatically detected 
=dump.xyz ATOMSthe atom indices whose positions you would like to print out. 
=1-20 The DUMPATOMS action with label

Notice that there are other ways to manipulate the coordinates stored within PLUMED:

Using the FIT_TO_TEMPLATE they can be aligned to a template structure.
Using WRAPAROUND you can bring a set of atom as close as possible to another set of atoms.
Using RESET_CELL you can rotate the periodic cell.

Virtual Atoms

Sometimes, when calculating a colvar, you may not want to use the positions of a number of atoms directly. Instead you may wish to use the position of a virtual atom whose position is generated based on the positions of a collection of other atoms. For example you might want to use the center of mass of a group of atoms. Plumed has a number of routines for calculating the positions of these virtual atoms from lists of atoms:

CENTER	Calculate the center for a group of atoms, with arbitrary weights.
CENTER_OF_MULTICOLVAR	Calculate a a weighted average position based on the value of some multicolvar.
COM	Calculate the center of mass for a group of atoms.
FIXEDATOM	Add a virtual atom in a fixed position.
GHOST	Calculate the absolute position of a ghost atom with fixed coordinates in the local reference frame formed by three atoms.

To specify to a colvar that you want to use the position of a virtual atom to calculate a colvar rather than one of the atoms in your system you simply use the label for your virtual atom in place of the usual numerical index. Virtual atoms and normal atoms can be mixed together in the input to colvars as shown below:

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

com1: COM ATOMSthe list of atoms which are involved the virtual atom's definition. 
=1,10 The COM action with label com1 calculates the position of a virtual atom
DISTANCE ATOMSthe pair of atom that we are calculating the distance between. 
=11,com1 The DISTANCE action with label

If you don't want to calculate CVs from the virtual atom. That is to say you just want to monitor the position of a virtual atom (or any set of atoms) over the course of your trajectory you can do this using DUMPATOMS.