| Module |
setup |
| Description |
Usage |
| Loads a library, possibly defining new actions. |
  |
Further details and examples
Loads a library, possibly defining new actions.
The LOAD action is only available on systems that allow dynamic loading.
This action allows you load new funcionality into PLUMED at runtime.
This new functionality can be in a .so file or a .cpp file. If the
new functionality is in a cpp file then the code is compiled and the
the resulting object is loaded.
Using the LOAD action is useful for making quick tests while developing your own
actions. Of course, once your implementation is ready you should
add it to the PLUMED source tree and recompile PLUMED.
One way to use the LOAD action is to directly load a cpp file as illustrated in the input below.
Click on the labels of the actions for more information on what each action computes
LOADLoads a library, possibly defining new actions. More details FILEfile to be loaded= /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Copyright (c) 2013 The plumed team
(see the PEOPLE file at the root of the distribution for a list of names)
See http://www.plumed-code.org for more information.
This file is part of plumed, version 2.0.
plumed is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
plumed is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with plumed. If not, see <http://www.gnu.org/licenses/>.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
#include "colvar/Colvar.h"
#include "core/ActionRegister.h"
#include <string>
#include <cmath>
using namespace std;
namespace PLMD{
class Distance : public colvar::Colvar {
bool components;
bool pbc;
public:
static void registerKeywords( Keywords& keys );
Distance(const ActionOptions&);
// active methods:
virtual void calculate();
};
PLUMED_REGISTER_ACTION(Distance,"DISTANCE2")
void Distance::registerKeywords( Keywords& keys ){
Colvar::registerKeywords( keys );
keys.add("atoms","ATOMS","the pair of atom that we are calculating the distance between");
keys.addFlag("COMPONENTS",false,"calculate the x, y and z components of the distance separately and store them as label.x, label.y and label.z");
keys.setValueDescription("scalar","the distance between the input atoms");
}
Distance::Distance(const ActionOptions&ao):
PLUMED_COLVAR_INIT(ao),
components(false),
pbc(true)
{
vector<AtomNumber> atoms;
parseAtomList("ATOMS",atoms);
if(atoms.size()!=2)
error("Number of specified atoms should be 2");
parseFlag("COMPONENTS",components);
bool nopbc=!pbc;
parseFlag("NOPBC",nopbc);
pbc=!nopbc;
checkRead();
log.printf(" between atoms %d %d\n",atoms[0].serial(),atoms[1].serial());
if(pbc) log.printf(" using periodic boundary conditions\n");
else log.printf(" without periodic boundary conditions\n");
if(!components){
addValueWithDerivatives(); setNotPeriodic();
} else{
addComponentWithDerivatives("x"); componentIsNotPeriodic("x");
addComponentWithDerivatives("y"); componentIsNotPeriodic("y");
addComponentWithDerivatives("z"); componentIsNotPeriodic("z");
}
requestAtoms(atoms);
}
// calculator
void Distance::calculate(){
Vector distance;
if(pbc){
distance=pbcDistance(getPosition(0),getPosition(1));
} else {
distance=delta(getPosition(0),getPosition(1));
}
const double value=distance.modulo();
const double invvalue=1.0/value;
if(!components){
setAtomsDerivatives(0,-invvalue*distance);
setAtomsDerivatives(1,invvalue*distance);
setBoxDerivatives (-invvalue*Tensor(distance,distance));
setValue (value);
}else{
Value* valuex=getPntrToComponent("x");
Value* valuey=getPntrToComponent("y");
Value* valuez=getPntrToComponent("z");
setAtomsDerivatives (valuex,0,Vector(-1,0,0));
setAtomsDerivatives (valuex,1,Vector(+1,0,0));
setBoxDerivatives (valuex,Tensor(distance,Vector(-1,0,0)));
valuex->set(distance[0]);
setAtomsDerivatives (valuey,0,Vector(0,-1,0));
setAtomsDerivatives (valuey,1,Vector(0,+1,0));
setBoxDerivatives (valuey,Tensor(distance,Vector(0,-1,0)));
valuey->set(distance[1]);
setAtomsDerivatives (valuez,0,Vector(0,0,-1));
setAtomsDerivatives (valuez,1,Vector(0,0,+1));
setBoxDerivatives (valuez,Tensor(distance,Vector(0,0,-1)));
valuez->set(distance[2]);
};
}
}
The LOAD action with label calculates somethingd: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,10
The DISTANCE action with label d calculates the following quantities:| Quantity | Description |
| d.value | the DISTANCE between this pair of atoms |
d2: DISTANCE2This action is not part of PLUMED and was included by using a LOAD command More details ATOMS=1,10
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d,d2 FILEthe name of the file on which to output these quantities=compare-them
When PLUMED reads the input above it first compiles the code in Distance2.cpp. The resulting object file
is then loaded into PLUMED. If you look at the cpp file that is input in the command above you can see that
a new action called DISTANCE2 is defined within it. We can thus use this new action in the input above.
Instead of compiling the code at runtime you can construct a shared object from the Distance2.cpp file and LOAD the shared library instead of
the cpp file. To construct the shared object you would use the following command:
> plumed mklib Distance2.cpp
When you run this command a new file called Distance2.so (or Distance2.dylib on a mac) is created.
You can then load this shared object in PLUMED by using the following LOAD command
LOAD FILE=Distance2.so
The new functionality within the Distance2.cpp file can then be used in the remainder of the input in the same way it was
used in the previous example.
(Notice that the only reason for not using the usual PLUMED syntax highlightling in the example above is that we have no
file called Distance2.so.)
From PLUMED 2.10 onwards the LOAD action can be placed at any point of the input
file. The loaded functionality will then only affect commands that are placed after the LOAD action.
These features are illustrated in the input below:
Click on the labels of the actions for more information on what each action computes
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,10
The DISTANCE action with label d calculates the following quantities:| Quantity | Description |
| d.value | the DISTANCE between this pair of atoms |
LOADLoads a library, possibly defining new actions. More details FILEfile to be loaded= /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Copyright (c) 2013 The plumed team
(see the PEOPLE file at the root of the distribution for a list of names)
See http://www.plumed-code.org for more information.
This file is part of plumed, version 2.0.
plumed is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
plumed is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with plumed. If not, see <http://www.gnu.org/licenses/>.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
#include "colvar/Colvar.h"
#include "core/ActionRegister.h"
#include <string>
#include <cmath>
using namespace std;
namespace PLMD{
class Distance : public colvar::Colvar {
bool components;
bool pbc;
public:
static void registerKeywords( Keywords& keys );
Distance(const ActionOptions&);
// active methods:
virtual void calculate();
};
PLUMED_REGISTER_ACTION(Distance,"DISTANCE")
void Distance::registerKeywords( Keywords& keys ){
Colvar::registerKeywords( keys );
keys.add("atoms","ATOMS","the pair of atom that we are calculating the distance between");
keys.addFlag("COMPONENTS",false,"calculate the x, y and z components of the distance separately and store them as label.x, label.y and label.z");
keys.setValueDescription("scalar","the distance between the input atoms");
}
Distance::Distance(const ActionOptions&ao):
PLUMED_COLVAR_INIT(ao),
components(false),
pbc(true)
{
vector<AtomNumber> atoms;
parseAtomList("ATOMS",atoms);
if(atoms.size()!=2)
error("Number of specified atoms should be 2");
parseFlag("COMPONENTS",components);
bool nopbc=!pbc;
parseFlag("NOPBC",nopbc);
pbc=!nopbc;
checkRead();
log.printf(" between atoms %d %d\n",atoms[0].serial(),atoms[1].serial());
if(pbc) log.printf(" using periodic boundary conditions\n");
else log.printf(" without periodic boundary conditions\n");
if(!components){
addValueWithDerivatives(); setNotPeriodic();
} else{
addComponentWithDerivatives("x"); componentIsNotPeriodic("x");
addComponentWithDerivatives("y"); componentIsNotPeriodic("y");
addComponentWithDerivatives("z"); componentIsNotPeriodic("z");
}
requestAtoms(atoms);
}
// calculator
void Distance::calculate(){
Vector distance;
if(pbc){
distance=pbcDistance(getPosition(0),getPosition(1));
} else {
distance=delta(getPosition(0),getPosition(1));
}
const double value=distance.modulo()+10;
const double invvalue=1.0/value;
if(!components){
setAtomsDerivatives(0,-invvalue*distance);
setAtomsDerivatives(1,invvalue*distance);
setBoxDerivatives (-invvalue*Tensor(distance,distance));
setValue (value);
}else{
Value* valuex=getPntrToComponent("x");
Value* valuey=getPntrToComponent("y");
Value* valuez=getPntrToComponent("z");
setAtomsDerivatives (valuex,0,Vector(-1,0,0));
setAtomsDerivatives (valuex,1,Vector(+1,0,0));
setBoxDerivatives (valuex,Tensor(distance,Vector(-1,0,0)));
valuex->set(distance[0]);
setAtomsDerivatives (valuey,0,Vector(0,-1,0));
setAtomsDerivatives (valuey,1,Vector(0,+1,0));
setBoxDerivatives (valuey,Tensor(distance,Vector(0,-1,0)));
valuey->set(distance[1]);
setAtomsDerivatives (valuez,0,Vector(0,0,-1));
setAtomsDerivatives (valuez,1,Vector(0,0,+1));
setBoxDerivatives (valuez,Tensor(distance,Vector(0,0,-1)));
valuez->set(distance[2]);
};
}
}
The LOAD action with label calculates somethingd2: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,10
The DISTANCE action with label d2 calculates the following quantities:| Quantity | Description |
| d2.value | the DISTANCE between this pair of atoms |
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d,d2 FILEthe name of the file on which to output these quantities=compare-them
Notice that Distance3.cpp replaces DISTANCE2 in the command that was used in Distance2.cpp; namely:
PLUMED_REGISTER_ACTION(Distance,"DISTANCE2")
with DISTANCE. Consequently, when we load the Distance3.cpp file here we redefine the DISTANCE command.
The functions that compute d and d2 in the above input are thus different.
A final point to note is that, starting with PLUMED 2.10, the LOAD action can be used in contexts where
multiple Plumed objects exist. A possible example is multithreading: loading an action
from a Plumed object used in one thread will not affect other threads.
Another example is if multiple Plumed objects are created in the C/C++ or Python interface.
If a LOAD command is used in one of these objects, the loaded action will not affect
the other objects.
[!NOTE]
The example inputs on this page appear as not working because you cannot use the dynamic loading on GitHub Actions. On a machine where this functionality is available these inputs should work.
Syntax
The following table describes the keywords and options that can be used with this action
| Keyword |
Type |
Default |
Description |
| FILE |
compulsory |
none |
file to be loaded |
