INCLUDE

This is part of the generic module

Includes an external input file, similar to #include in C preprocessor.

Useful to split very large plumed.dat files. Notice that in PLUMED 2.4 this action cannot be used before the initial setup part of the file (e.g. in the part with UNITS, MOLINFO, etc). As of PLUMED 2.5, INCLUDE can be used in any position of the file.

Examples

This input:

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

c1: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =1-100 The COM action with label c1 calculates the position of a virtual atom
c2: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =101-202 The COM action with label c2 calculates the position of a virtual atom
d: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =c1,c2 The DISTANCE action with label d calculates a single scalar value
PRINT ARGthe input for this action is the scalar output from one or more other actions. =d The PRINT action with label 

can be replaced with this input:

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

INCLUDE FILEcompulsory keyword 
file to be included =pippo.dat The INCLUDE action with label 
d: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =c1,c2 The DISTANCE action with label d calculates a single scalar value
PRINT ARGthe input for this action is the scalar output from one or more other actions. =d The PRINT action with label 

where the content of file pippo.dat is

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

#SETTINGS FILENAME=pippo.dat
# this is pippo.dat
c1: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =1-100 The COM action with label c1 calculates the position of a virtual atom
c2: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =101-202 The COM action with label c2 calculates the position of a virtual atom

The files in this example are rather short, but imagine a case like this one:

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

INCLUDE FILEcompulsory keyword 
file to be included =groups.dat The INCLUDE action with label 
c: COORDINATION GROUPAFirst list of atoms. =groupa GROUPBSecond list of atoms (if empty, N*(N-1)/2 pairs in GROUPA are counted). =groupb R_0 could not find this keyword =0.5 The COORDINATION action with label c calculates a single scalar value
METAD ARGthe input for this action is the scalar output from one or more other actions. =c HEIGHTthe heights of the Gaussian hills. =0.2 PACEcompulsory keyword 
the frequency for hill addition =100 SIGMAcompulsory keyword 
the widths of the Gaussian hills =0.2 BIASFACTORuse well tempered metadynamics and use this bias factor. =5 The METAD action with label 

Here groups.dat could be a huge file containing group definitions. This groups.dat file might look something like the following example but with more atom indices in the groups.

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

#SETTINGS FILENAME=groups.dat
# this is groups.dat
groupa: GROUP ...
   ATOMSthe numerical indexes for the set of atoms in the group. ={ 
     10 
     50 
     60 
     70 
     80 
     120 
   }  
...The GROUP action with label groupa defines a group of atoms so that they can be referred to later in the input
groupb: GROUP ...
   ATOMSthe numerical indexes for the set of atoms in the group. ={ 
     11 
     51 
     61 
     71 
     81 
     121 
   }  
...The GROUP action with label groupb defines a group of atoms so that they can be referred to later in the input

So, included files are the best place where one can store long definitions.

Another case where INCLUDE is very useful is when running multi-replica simulations. Here different replicas might have different input files, but perhaps a large part of the input is shared. This part can be put in a common included file. For instance you could have common.dat:

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

#SETTINGS FILENAME=common.dat
# this is common.dat
t: TORSION ATOMSthe four atoms involved in the torsional angle =1,2,3,4 The TORSION action with label t calculates a single scalar value

Then plumed.0.dat:

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

# this is plumed.0.dat
INCLUDE FILEcompulsory keyword 
file to be included =common.dat The INCLUDE action with label 
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. =t ATcompulsory keyword 
the position of the restraint =1.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 =10 The RESTRAINT action with label 

And plumed.1.dat:

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

# this is plumed.1.dat
INCLUDE FILEcompulsory keyword 
file to be included =common.dat The INCLUDE action with label 
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. =t ATcompulsory keyword 
the position of the restraint =1.2 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 =10 The RESTRAINT action with label 

Warning

Remember that when using multi replica simulations whenever plumed tried to open a file for reading it looks for a file with the replica suffix first. This is true also for files opened by INCLUDE!

As an example, the same result of the inputs above could have been obtained using the following plumed.dat file:

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

#SETTINGS NREPLICAS=2
t: TORSION ATOMSthe four atoms involved in the torsional angle =1,2,3,4 The TORSION action with label t calculates a single scalar value
INCLUDE FILEcompulsory keyword 
file to be included =other.inc The INCLUDE action with label 

Then other.0.inc:

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

#SETTINGS FILENAME=other.0.inc
# this is other.0.inc
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. =t ATcompulsory keyword 
the position of the restraint =1.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 =10  You cannot view the components that are calculated by each action for this input file. Sorry 

And other.1.inc:

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

#SETTINGS FILENAME=other.1.inc
# this is other.1.inc
RESTRAINT ARGthe input for this action is the scalar output from one or more other actions. =t ATcompulsory keyword 
the position of the restraint =1.2 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 =10  You cannot view the components that are calculated by each action for this input file. Sorry 

Glossary of keywords and components

Compulsory keywords

FILE	file to be included