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
tested on master
c1: COM 
ATOMS
the list of atoms which are involved the virtual atom's definition.
=1-100 c2: COM
ATOMS
the list of atoms which are involved the virtual atom's definition.
=101-202 d: DISTANCE
ATOMS
the pair of atom that we are calculating the distance between.
=c1,c2 PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=d

can be replaced with this input:

Click on the labels of the actions for more information on what each action computes
tested on master
INCLUDE 
FILE
compulsory keyword file to be included
=pippo.dat d: DISTANCE
ATOMS
the pair of atom that we are calculating the distance between.
=c1,c2 PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=d

where the content of file pippo.dat is

Click on the labels of the actions for more information on what each action computes
tested on master
#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 c2: COM
ATOMS
the list of atoms which are involved the virtual atom's definition.
=101-202

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
tested on master
INCLUDE 
FILE
compulsory keyword file to be included
=groups.dat 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 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

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
tested on master
#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 } ... groupb: GROUP ...
ATOMS
the numerical indexes for the set of atoms in the group.
={ 11 51 61 71 81 121 } ...

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
tested on master
#SETTINGS FILENAME=common.dat
# this is common.dat
t: TORSION 
ATOMS
the four atoms involved in the torsional angle
=1,2,3,4

Then plumed.0.dat:

Click on the labels of the actions for more information on what each action computes
tested on master
# this is plumed.0.dat
INCLUDE 
FILE
compulsory keyword file to be included
=common.dat 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

And plumed.1.dat:

Click on the labels of the actions for more information on what each action computes
tested on master
# this is plumed.1.dat
INCLUDE 
FILE
compulsory keyword file to be included
=common.dat 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
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
tested on master
#SETTINGS NREPLICAS=2
t: TORSION 
ATOMS
the four atoms involved in the torsional angle
=1,2,3,4 INCLUDE
FILE
compulsory keyword file to be included
=other.inc

Then other.0.inc:

Click on the labels of the actions for more information on what each action computes
tested on master
#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

And other.1.inc:

Click on the labels of the actions for more information on what each action computes
tested on master
#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
Glossary of keywords and components
Compulsory keywords
FILE file to be included