Action: INCLUDE

Module	generic
Description	Usage
Includes an external input file, similar to #include in C preprocessor.

Further details and examples

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

The INCLUDE command is Useful when you want to split very large plumed.dat files.

In PLUMED 2.4 this action was now allowed to appear before the initial setup part of the file (e.g. in the part that conained any UNITS and MOLINFO commands). However, from PLUMED 2.5 onwards, INCLUDE commands can be used in any position of the file.

Basic example

This input:

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

c1The COM action with label c1 calculates the following quantities:
 Quantity   
 Type   
 Description  
c1
atoms
virtual atom calculated by COM action: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=1-100
c2The COM action with label c2 calculates the following quantities:
 Quantity   
 Type   
 Description  
c2
atoms
virtual atom calculated by COM action: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=101-202
dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=c1,c2
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d

can be replaced with this input:

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

INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/pippo.dat
# The command:
# INCLUDE FILE=extras/pippo.dat
# ensures PLUMED loads the contents of the file called extras/pippo.dat
# The contents of this file are shown below (click the red comment to hide them).
The INCLUDE action with label extras/pippo.dat calculates somethingc1The COM action with label c1 calculates the following quantities:
 Quantity   
 Type   
 Description  
c1
atoms
virtual atom calculated by COM action: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=1-100
c2The COM action with label c2 calculates the following quantities:
 Quantity   
 Type   
 Description  
c2
atoms
virtual atom calculated by COM action: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=101-202
# --- End of included input --- dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=c1,c2
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d

Notice that you can see the contents of pippo.dat by clicking on the name of the file

Using INCLUDE to define groups

Using INCLUDE for the input in the previous section is rather pointless as the included file is rather short. In a case like the one shown below the INCLUDE command is much more useful:

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

INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/groups.dat
# The command:
# INCLUDE FILE=extras/groups.dat
# ensures PLUMED loads the contents of the file called extras/groups.dat
# The contents of this file are shown below (click the red comment to hide them).
The INCLUDE action with label extras/groups.dat calculates somethinggroupaThe GROUP action with label groupa calculates the following quantities:
 Quantity   
 Type   
 Description  
groupa
atoms
indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ...
  ATOMSthe numerical indexes for the set of atoms in the group={
    10
    50
    60
    70
    80
    120
  }
...
groupbThe GROUP action with label groupb calculates the following quantities:
 Quantity   
 Type   
 Description  
groupb
atoms
indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ...
  ATOMSthe numerical indexes for the set of atoms in the group={
    11
    51
    61
    71
    81
    121
  }
...
# --- End of included input --- cThe COORDINATION action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
scalar
the value of the coordination: COORDINATIONCalculate coordination numbers. This action has hidden defaults. More details GROUPAFirst list of atoms=groupa GROUPBSecond list of atoms (if empty, N*(N-1)/2 pairs in GROUPA are counted)=groupb R_0The r_0 parameter of the switching function=0.5
c: COORDINATIONCalculate coordination numbers. This action uses the defaults shown here. More details GROUPAFirst list of atoms=groupa GROUPBSecond list of atoms (if empty, N*(N-1)/2 pairs in GROUPA are counted)=groupb R_0The r_0 parameter of the switching function=0.5  D_0 The d_0 parameter of the switching function=0.0 NN The n parameter of the switching function =6 MM The m parameter of the switching function; 0 implies 2*NN=0
METADUsed to performed metadynamics on one or more collective variables. More details ARGthe labels of the scalars on which the bias will act=c HEIGHTthe heights of the Gaussian hills=0.2 PACEthe frequency for hill addition=100 SIGMAthe widths of the Gaussian hills=0.2 BIASFACTORuse well tempered metadynamics and use this bias factor=5

Although the groups.dat file here is short again it could be much larger if the groups contained very lage numbers of atoms.

INCLUDE and multiple replicas

Another case where INCLUDE can be 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 use a common.dat to share part of the input across the input for the two replica simulation which has the following plumed.0.dat input file:

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

# this is plumed.0.dat
INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/common.dat
# The command:
# INCLUDE FILE=extras/common.dat
# ensures PLUMED loads the contents of the file called extras/common.dat
# The contents of this file are shown below (click the red comment to hide them).
The INCLUDE action with label extras/common.dat calculates somethingtThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
# --- End of included input --- RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t ATthe position of the restraint=1.0 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10

and the following plumed.1.dat input file

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

# this is plumed.1.dat
INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/common.dat
# The command:
# INCLUDE FILE=extras/common.dat
# ensures PLUMED loads the contents of the file called extras/common.dat
# The contents of this file are shown below (click the red comment to hide them).
The INCLUDE action with label extras/common.dat calculates somethingtThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
# --- End of included input --- RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t ATthe position of the restraint=1.2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10

When you run calculations in this way it is important to reember that PLUMED will always try to open files for reading with a replica suffix first. This is also even for files opened by INCLUDE! We can thus implement the calculation above using the following common input for the two replicas:

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

#SETTINGS NREPLICAS=2
tThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/other.inc
# The command:
# INCLUDE FILE=extras/other.inc
# ensures PLUMED loads the contents of the file called extras/other.inc
# There are different versions of this file on each replica
# The contents of the version of this file (extras/other.0.inc) on replica 0 is shown below.
The INCLUDE action with label extras/other.inc calculates somethingRESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t ATthe position of the restraint=1.0 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10
# The contents of the version of this file (extras/other.1.inc) on replica 1 is shown below.
The RESTRAINT action with label  calculates the following quantities:
 Quantity   
 Description  
.bias
the instantaneous value of the bias potential
.force2
the instantaneous value of the squared force due to this bias potentialRESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t ATthe position of the restraint=1.2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10
#(click the red comment to hide this expanded text).
# --- End of included input --- 

We would then have an other.0.inc file that contains the defintion of the RESTRAINT command with AT=1.0 and an other.1.inc file that contains the defintion of the RESTRAINT command with AT=1.2.

In practice, however, we recommend using the special replica syntax that is discussed on this page in place of the INCLUDE file approach that has been described above. If you are using this syntax the input for the calculation above is as follows:

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

#SETTINGS NREPLICAS=2
tThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.1.0,1.2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10

The version of this input that uses INCLUDE files is an older syntax that was used in older versions of PLUMED before the special replica syntax was made available.

Syntax

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