PLUMED

This is part of the generic module

Embed a separate PLUMED instance.

This command can be used to embed a separate PLUMED instance. Only required atoms will be passed to that instance, using an interface that is similar to the one used when calling PLUMED from the NAMD engine.

Notice that the two instances are running in the same UNIX process, so that they cannot be perfectly isolated. However, most of the features are expected to work correctly.

Notes:

• The LOAD action will not work correctly since registers will be shared among the two instances. In particular, the loaded actions will be visible to both guest and host irrespective of where they are loaded from. This can be fixed and will probably be fixed in a later version.
• CHDIR is not thread safe. However, in most implementations there will be a single process running PLUMED, with perhaps multiple OpenMP threads spawn in order to parallelize the calculation of individual variables. So, this is likely not a problem.
• MPI is working correctly. However, notice that the guest PLUMED will always run with a single process. Multiple replicas should be handled correctly.

As an advanced feature, one can use the option KERNEL to select the version of the guest PLUMED instance. In particular, an empty KERNEL (default) implies that the guest PLUMED instance is the same as the host one (no library is loaded). On the other hand, KERNEL=/path/to/libplumedKernel.so will allow specifying a library to be loaded for the guest instance. In addition to those mentioned above, this feature has limitations mostly related to clashes in the symbols defined in the different instances of the PLUMED library. Clashes might be due by synonymous symbols from the PLUMED library or synonymous symbols from libraries linked to PLUMED, and would differ depending on the operating system you are using:

• On OSX:
  • Symbols from the PLUMED library would clash. The only way to avoid is to load PLUMED dynamically:
    • If you are are using PLUMED with an MD code, it should be patched with --runtime.
    • If you are using PLUMED driver, you should launch the plumed-runtime executable (contained in the prefix/lib/plumed/ directory) and export PLUMED_KERNEL equal to the path of the host kernel library (as usual in runtime loading). Notice that as of PLUMED 2.10 we load kernels with RTLD_LOCAL by default.
    • Symbols from dependent libraries should not clash since, as of version 2.5, we are using two-level namespace. Problems when loading previous versions should anyway be solved using runtime mode as explained above.
• On Linux, any KERNEL should in principle work correctly. To achieve namespace separation we are loading the guest kernel with RTLD_DEEPBIND. However, this might create difficult to track problems in other linked libraries.
• On Unix systems where RTLD_DEEPBIND is not available kernels will not load correctly.

• In general, there might be unexpected crashes. Particularly difficult are situations where different kernels were compiled with different libraries.

  Todo:

Examples

Here an example plumed file:

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

# plumed.dat
p: PLUMED 
FILE
input file for the guest PLUMED instance 
=plumed2.dat The PLUMED action with label p calculates a single scalar value
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=p.bias 
FILE
the name of the file on which to output these quantities 
=COLVAR The PRINT action with label 

plumed2.dat can be an arbitrary plumed input file, for instance

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

contract shortcuts

#SETTINGS FILENAME=plumed2.dat
# plumed2.dat
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,10 The DISTANCE action with label d calculates a single scalar value
RESTRAINT 
ARG
the arguments on which the bias is acting. 
=d 
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 
AT
compulsory keyword 
the position of the restraint 
=2 The RESTRAINT action with label 

#SETTINGS FILENAME=plumed2.dat
# plumed2.dat
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,10 The DISTANCE action with label d calculates a single scalar value
@2: RESTRAINT_SCALAR 
ARG
the input for this action is the scalar output from one or more other actions. 
=d 
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 
AT
compulsory keyword 
the position of the restraint 
=2 The RESTRAINT_SCALAR action with label @2 calculates the following quantities:

 Quantity   
 Description  
@2.bias
the instantaneous value of the bias potential
@2.force2
the instantaneous value of the squared force due to this bias potential

Now a more useful example. Imagine that you ran simulations using two different PLUMED input files. The files are long and complex and there are some clashes in the name of the variables (that is: same names are used in both files, same files are written, etc). In addition, files might have been written using different units (see UNITS`). If you want to run a single simulation with a bias potential that is the sum of the two bias potentials, you can:

• Place the two input files, as well as all the files required by plumed, in separate directories directory1 and directory2.
• Run with the following input file in the parent directory:
  Click on the labels of the actions for more information on what each action computes
  

  # plumed.dat
  PLUMED 
  FILE
  input file for the guest PLUMED instance 
  =plumed.dat 
  CHDIR
  run guest in a separate directory 
  =directory1  You cannot view the components that are calculated by each action for this input file. Sorry 
  PLUMED 
  FILE
  input file for the guest PLUMED instance 
  =plumed.dat 
  CHDIR
  run guest in a separate directory 
  =directory2  You cannot view the components that are calculated by each action for this input file. Sorry 
  

Glossary of keywords and components

Description of components

Quantity	Description
bias	the instantaneous value of the bias potential

Compulsory keywords

STRIDE

( default=1 ) stride different from 1 are not supported yet

Options

NOREPLICAS	( default=off ) run multiple replicas as isolated ones, without letting them know that the host has multiple replicas
FILE	input file for the guest PLUMED instance
KERNEL	kernel to be used for the guest PLUMED instance (USE WITH CAUTION!)
LOG	log file for the guest PLUMED instance. By default the host log is used
CHDIR	run guest in a separate directory