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 
ATOMS
the 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 
ATOMS
the 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 
ATOMS
the pair of atom that we are calculating the distance between. 
=c1,c2 The DISTANCE action with label d calculates a single scalar value
PRINT 
ARG
the 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 
FILE
compulsory keyword 
file to be included 
=pippo.dat The INCLUDE action with label 
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=c1,c2 The DISTANCE action with label d calculates a single scalar value
PRINT 
ARG
the 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 
ATOMS
the 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 
ATOMS
the 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 
FILE
compulsory keyword 
file to be included 
=groups.dat The INCLUDE action with label 
c: COORDINATION 
GROUPA
First list of atoms. 
=groupa 
GROUPB
Second 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 
ARG
the input for this action is the scalar output from one or more other actions. 
=c 
HEIGHT
the heights of the Gaussian hills. 
=0.2 
PACE
compulsory keyword 
the frequency for hill addition 
=100 
SIGMA
compulsory keyword 
the widths of the Gaussian hills 
=0.2 
BIASFACTOR
use 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 ...
   
ATOMS
the 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 ...
   
ATOMS
the 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 
ATOMS
the 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 
FILE
compulsory keyword 
file to be included 
=common.dat The INCLUDE action with label 
RESTRAINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=t 
AT
compulsory keyword 
the position of the restraint 
=1.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 
=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 
FILE
compulsory keyword 
file to be included 
=common.dat The INCLUDE action with label 
RESTRAINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=t 
AT
compulsory keyword 
the position of the restraint 
=1.2 
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 
=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 
ATOMS
the four atoms involved in the torsional angle 
=1,2,3,4 The TORSION action with label t calculates a single scalar value
INCLUDE 
FILE
compulsory 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 
ARG
the input for this action is the scalar output from one or more other actions. 
=t 
AT
compulsory keyword 
the position of the restraint 
=1.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 
=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 
ARG
the input for this action is the scalar output from one or more other actions. 
=t 
AT
compulsory keyword 
the position of the restraint 
=1.2 
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 
=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