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:

  • On OSX, if you load a KERNEL with version >=2.5 there should be no problem thanks to the use of two-level namespaces.
  • On OSX, if you load a KERNEL with version <=2.4 there should be clashes in symbol resolution. The only possible workarounds are:
    • If you are are using PLUMED with an MD code, it should be patched with --runtime and you should export PLUMED_LOAD_NAMESPACE=LOCAL before starting the MD engine.
    • If you are using PLUMED driver, you should launch the plumed-runtime executable (contained in the prefix/lib/plumed/ directory), export PLUMED_KERNEL equal to the path of the host kernel library (as usual in runtime loading) and export PLUMED_LOAD_NAMESPACE=LOCAL before launching plumed-runtime driver.
  • 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.

A possible solution for the symbol clashes (not tested) could be to recompile the alternative PLUMED versions using separate C++ namespaces (e.g. ./configure CPPFLAGS=-DPLMD=PLMD_2_3).

Todo:
  • Add support for multiple time stepping (STRIDE different from 1).
  • Add the possibility to import CVs calculated in the host PLUMED instance into the guest PLUMED instance. Will be possible after #83 will be closed.
  • Add the possibility to export CVs calculated in the guest PLUMED instance into the host PLUMED instance. Could be implemented using the DataFetchingObject class.
Examples

Here an example plumed file:

Click on the labels of the actions for more information on what each action computes
tested on v2.7
# plumed.dat
p: PLUMED 
FILE
input file for the guest PLUMED instance 
=plumed2.dat 
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

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
tested on v2.7
#SETTINGS FILENAME=plumed2.dat
# plumed2.dat
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,10 
RESTRAINT 
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

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
    tested on v2.7
    # plumed.dat
PLUMED 
    FILE
    input file for the guest PLUMED instance 
    =plumed.dat 
    CHDIR
    run guest in a separate directory 
    =directory1 
PLUMED 
    FILE
    input file for the guest PLUMED instance 
    =plumed.dat 
    CHDIR
    run guest in a separate directory 
    =directory2
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