Action: DUMPATOMS

Module generic
Description Usage
Dump selected atoms on a file. used in 3 tutorialsused in 5 eggs
This action outputs data to a file. You can read more about how PLUMED manages output files here

Input

The arguments and atoms that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword Type Description
ARG vector the labels of vectors that should be output in the xyz file
ATOMS atoms the atom indices whose positions you would like to print out

Further details and examples

Dump selected atoms on a file.

This command can be used to output the positions of a particular set of atoms. For example, the following input instructs PLUMED to print out the positions of atoms 1-10 together with the position of the center of mass of atoms 11-20 every 10 steps to a file called file.xyz.

Click on the labels of the actions for more information on what each action computes
tested on2.11
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz ATOMSthe atom indices whose positions you would like to print out=1-10,c1

By default, the coordinates in the output xyz file are in nm but you can change these units by using the UNITS keyword as shown below:

Click on the labels of the actions for more information on what each action computes
tested on2.11
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz ATOMSthe atom indices whose positions you would like to print out=1-10,c1 UNITS the units in which to print out the coordinates=A

or by using the UNITS action as shown below:

Click on the labels of the actions for more information on what each action computes
tested on2.11
UNITSThis command sets the internal units for the code. More details LENGTHthe units of lengths=A
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz ATOMSthe atom indices whose positions you would like to print out=1-10,c1

Notice, however, that if you use the second option here all the quantitities with units of length in your input file must be provided in Angstrom and not nm.

DUMPATOMS and WHOLEMOLECULES

The commands WHOLEMOLECULES, WRAPAROUND, FIT_TO_TEMPLATE and RESET_CELL all edit the global positions of the atoms. If you use an input like this one:

Click on the labels of the actions for more information on what each action computes
tested on2.11
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz
WHOLEMOLECULESThis action is used to rebuild molecules that can become split by the periodic boundary conditions. More details ENTITY0the atoms that make up a molecule that you wish to align=1-10

then the positions of the atoms that were passed to PLUMED by the MD code are output. However, if you use an input like this one:

Click on the labels of the actions for more information on what each action computes
tested on2.11
WHOLEMOLECULESThis action is used to rebuild molecules that can become split by the periodic boundary conditions. More details ENTITY0the atoms that make up a molecule that you wish to align=1-10
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz

the positions outputted by the DUMPATOMS command will have been editted by the WHOLEMOLECULES command.

Outputting other file types

The extension that is given to the file specified using the FILE keyword determines the output file type. Hence, the following example will output a gro file rather than an xyz file:

Click on the labels of the actions for more information on what each action computes
tested on2.11
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.gro ATOMSthe atom indices whose positions you would like to print out=1-10,c1

You can also enforce the output file type by using the TYPE keyword as shown below:

Click on the labels of the actions for more information on what each action computes
tested on2.11
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xyz ATOMSthe atom indices whose positions you would like to print out=1-10,c1 TYPEfile type, either xyz, gro, xtc, or trr, can override an automatically detected file extension=gro
FLUSHThis command instructs plumed to flush all the open files with a user specified frequency. More details STRIDEthe frequency with which all the open files should be flushed=1

Notice that DUMPATOMS command here outputs the atoms in the gro-file format even though the author of this input has used the xyz extension. Further note that by using the FLUSH we force PLUMED to output flush all the open files every step and not to store output data in a buffer before printing it to the output files.

Outputting the atomic positions using the gro file format is particularly advantageous if you also have a MOLINFO command in your input file as shown below:

Click on the labels of the actions for more information on what each action computes
tested on2.11
#SETTINGS MOLFILE=regtest/basic/rt32/helix.pdb
# this is required to have proper atom names:
MOLINFOThis command is used to provide information on the molecules that are present in your system. More details STRUCTUREa file in pdb format containing a reference structure=
regtest/basic/rt32/helix.pdb
 Click here to see an extract from this file.
  
  ×  
FILE: regtest/basic/rt32/helix.pdb
    
ATOM      1 HH31 ACE     1      -9.105  -2.402  21.804  0.00  0.00            
ATOM      2  CH3 ACE     1      -8.930  -3.352  22.308  0.00  0.00            
ATOM      3 HH32 ACE     1      -9.504  -3.501  23.223  0.00  0.00            
ATOM      4 HH33 ACE     1      -9.067  -4.173  21.604  0.00  0.00            
ATOM      5  C   ACE     1      -7.450  -3.303  22.659  0.00  0.00            
...
ATOM    129  CH3 NME    14      -1.690  -7.089  20.487  0.00  0.00            
ATOM    130 HH31 NME    14      -1.873  -6.629  21.459  0.00  0.00            
ATOM    131 HH32 NME    14      -1.152  -6.284  19.986  0.00  0.00            
ATOM    132 HH33 NME    14      -1.135  -8.020  20.602  0.00  0.00            
END

  

# if omitted, atoms will have "X" name...

c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.gro ATOMSthe atom indices whose positions you would like to print out=1-10,c1
# notice that last atom is a virtual one and will not have
# a correct name in the resulting gro file

The reason that using the gro file format is advantageous in this case is that PLUMED will also output the atom and residue names for the non-virtual atoms. PLUMED is able to do this in this case as it is able to use the information that was read in from the pdb file that was provided to the MOLINFO command.

If PLUMED has been compiled with xdrfile support, then PLUMED can output xtc and trr files as well as xyz and gro files. If you want to use these output types you should install the xdrfile library by following the instructions here. If the xdrfile library is installed properly the PLUMED configure script should be able to detect it and enable it. The following example shows how you can use DUMPATOMS to output an xtc file:

Click on the labels of the actions for more information on what each action computes
tested on2.11
c1: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xtc ATOMSthe atom indices whose positions you would like to print out=1-10,c1

The xtc file that is output by this command will be significantly smaller than a gro and xyz file.

Finally, notice that gro and xtc file store coordinates with limited precision set by the PRECISION keyword. The default value is 3, which means "3 digits after dot" in nm (1/1000 of a nm). The following will write a larger xtc file with high resolution coordinates:

Click on the labels of the actions for more information on what each action computes
tested on2.11
COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=11-20 LABELa label for the action so that its output can be referenced in the input to other actions=c1
DUMPATOMSDump selected atoms on a file. More details STRIDE the frequency with which the atoms should be output=10 FILEfile on which to output coordinates; extension is automatically detected=file.xtc ATOMSthe atom indices whose positions you would like to print out=1-10,c1 PRECISIONThe number of digits in trajectory file=7

Outputting atomic positions and vectors

The atoms section of an xyz file normally contains four columns of data - a symbol that tells you the atom type and then three columns containing the atom's x, y and z coordinates. PLUMED allows you to output more columns of data in this file. For example, the following input outputs five columns of data. The first four columns of data are the usual ones you would expect in an xyz file, while the fifth contains the coordination numbers for each of the atom that have been calculated using PLUMED

Click on the labels of the actions for more information on what each action computes
tested on2.11
# These three lines calculate the coordination numbers of 100 atoms
c1: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details GROUPspecifies the list of atoms that should be assumed indistinguishable=1-100 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL R_0=0.1 NN=6 MM=12}
ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=100
cc: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=c1,ones
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-100 ARGthe labels of vectors that should be output in the xyz file=cc FILEfile on which to output coordinates; extension is automatically detected=file.xyz

This command is used in the shortcut that recovered the old DUMPMULTICOLVAR command. This new version of the command is better, however, as you can output more than one vector of symmetry functions at once as is demonstrated by the following input that outputs the coordination numbers and the values that were obtained when the coordination numbers were all transformed by a switching function:

Click on the labels of the actions for more information on what each action computes
tested on2.11
# These three lines calculate the coordination numbers of 100 atoms
c1: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details GROUPspecifies the list of atoms that should be assumed indistinguishable=1-100 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL R_0=0.1 NN=6 MM=12}
ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=100
cc: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=c1,ones
fcc: LESS_THANUse a switching function to determine how many of the input variables are less than a certain cutoff. More details ARGthe values input to this function=cc SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL R_0=4}
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-100 ARGthe labels of vectors that should be output in the xyz file=cc,fcc FILEfile on which to output coordinates; extension is automatically detected=file.xyz

Notice that when we use an ARG keyword we can also use DUMPATOMS to only print those atoms whose corresponding element in the the input vector satisfies a certain criteria. For example the input file below only prints the positions (and coordination numbers) of atoms that have a coordination number that is greater than or equal to 4.

Click on the labels of the actions for more information on what each action computes
tested on2.11
# These three lines calculate the coordination numbers of 100 atoms
c1: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details GROUPspecifies the list of atoms that should be assumed indistinguishable=1-100 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL R_0=0.1 NN=6 MM=12}
ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=100
cc: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=c1,ones
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-100 ARGthe labels of vectors that should be output in the xyz file=cc GREATER_THAN_OR_EQUALwhen printing with arguments that are vectors only print components of vectors have a value greater than or equal to this value=4 FILEfile on which to output coordinates; extension is automatically detected=file.xyz

Commands like these are useful if you want to print the coordinates of the atom that are in a paricular cluster that has been identified using the DFSCLUSTERING command.

You can only use the ARG keyword if you are outputting an xyz file

Syntax

The following table describes the keywords and options that can be used with this action

Keyword Type Default Description
ARG input none the labels of vectors that should be output in the xyz file
ATOMS input none the atom indices whose positions you would like to print out
STRIDE compulsory 1 the frequency with which the atoms should be output
FILE compulsory none file on which to output coordinates; extension is automatically detected
UNITS compulsory PLUMED the units in which to print out the coordinates
PRECISION optional not used The number of digits in trajectory file
TYPE optional not used file type, either xyz, gro, xtc, or trr, can override an automatically detected file extension
LESS_THAN_OR_EQUAL optional not used when printing with arguments that are vectors only print components of vectors have a value less than or equal to this value
GREATER_THAN_OR_EQUAL optional not used when printing with arguments that are vectors only print components of vectors have a value greater than or equal to this value
RESTART optional not used allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM optional not used Only update this action from this time
UPDATE_UNTIL optional not used Only update this action until this time