forked from plumed/plumed2
/
Doc.txt
240 lines (221 loc) · 10.5 KB
/
Doc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
// This document is formatted for Doxygen
/**
\mainpage Plumed 2
Roadmap:
- Cloning most PLUMED1 features (to be defined)
- Public beta release (to be defined)
- 2.0 public release (to be defined)
\section FeaturesAndChanges Features and changes
This are some comments about the structure of the code:
- Re-designed from scratch, hopefully better.
- Input is conceptually similar but NON compatible. It is difficult to automatically
convert old input files, but we could provide a short transition guide.
The new plumed.dat is a sort of script containing a list of actions to be performed at each step.
Notable differences in input:
- An Action is composed of a line (possibly with continuations) of
space-separated words, and corresponds more-or-less to a directive in PLUMED1.
\verbatim
DISTANCE ATOMS=0,300 LABEL=dist NOPBC
\endverbatim
The first word (DISTANCE here) defines the directive type, all other words are arguments
Most arguments are named, and has the form "NAME=VALUE" (ATOMS and LABEL in the example).
Others are flags (NOPBC in the example).
- Continuation can be done with "..." syntax (notice the space between DISTANCE and dots):
\verbatim
DISTANCE ...
ATOMS=0,300
LABEL=dist
NOPBC
... DISTANCE
\endverbatim
- All directives can be labeled (LABEL=dist in the example)
- A bias can only act on a labeled colvar:
\verbatim
DISTANCE ATOMS=0,300 LABEL=dist
# This is a harmonic restraint
RESTRAINT ARG=dist KAPPA=1.0 AT=1.0
\endverbatim
- Some colvars have extra named values, which can be accessed with "." syntax
\verbatim
DISTANCE ATOMS=1,10 LABEL=dist COMPONENTS
RESTRAINT ARG=dist.x KAPPA=1.0 AT=1.0
\endverbatim
Here COMPONENTS is telling to DISTANCE to also compute the three components.
This is expected to be useful for variables which have multiple components
but that are heavy and we would like to compute only once (e.g. components
of the inertia tensor of a large molecule).
Also methods can have extra named values, such as the energy for a restraint.
- to print a COLVAR-like file (name can be changed), use PRINT directive
\verbatim
PRINT ARG=d1,d1.x,d1.y,d1.z STRIDE=100 FILE=COLVAR
# or
PRINT ARG=d1.* STRIDE=100 FILE=COLVAR1
# or, to print all the variables defined in the plumed.dat up to this point
PRINT ARG=* STRIDE=100 FILE=COLVAR_ALL
\endverbatim
- The library has been written in C++ for a more flexible structure:
- Extensive use of STL containers for things such as lists/vectors/maps/...
- Polymorphism for collective variables/free energy methods
However, for compatibility, its main interface is in plain C (with FORTRAN
and C++ wrappers). All the C++ definitions are hidden in a PLMD namespace.
- Hierarchy of classes describing each possible Action performed by PLUMED.
There is a class for each CV (e.g. PLMD::ColvarDistance, PLMD::ColvarEnergy,
PLMD::ColvarVolume), a class for each bias (e.g. PLMD::BiasRestraint, PLMD::BiasMovingRestraint),
and a class for each function (e.g. PLMD::FunctionCombine).
There are also auxiliary classes to write the output (PLMD::Print),
to set the units (PLMD::Units), to print dedug information (PLMD::Debug),
to flush the open files (PLMD::Flush), etc.
More or less, there should be a class for each possible directive of "plumed.dat".
To see the full hierarchy, look at PLMD::Action.
- It should be possible to program Actions independently from each other. To this
aim, there is a register (PLMD::ActionRegister, contained in the function
PLMD::actionRegister()) where, during C++ initialization, each
Action registers itself. Thus, if a new CV or bias is added, there is no need
for recompilation. If dlopen() is available on a system, it should be possible
to load Actions runtime (using LOAD directive).
In the long run we can imagine libraries of CVs
suitable for different problems and, possibly, released independently from
the kernel. On a mainframe, one could add CVs without recompiling neither plumed
nor the MD engine.
- There is an option to load the plumed kernel at runtime. If you patch with
--runtime, the plumed kernel is looked for at the path in variable PLUMED_KERNEL.
If the variable is not set, basic (un-plumed) version of MD is used.
On a mainframe, one can have multiple installed plumed versions.
- Ideally, inside the kernel there is nothing related to specific CVs or FE-methods. Thus, CVs and
methods are optional plugins for PLUMED. The only exception
are tools which are common to several CVs/methods, such as grid interpolators, etc.
- Ideally, inside the kernel there is nothing related to specific MD code. The interface is kept
as standard as possibly. Anyway, all the details of the interaction PLUMED/MD are inside the
src/Atoms.cpp file. E.g., there are two (templated) versionsi of class PLMD::MDAtoms,
one for double precision and the other
for single precision MD. Code specific tools could be added here. In the future, we may try to
design a plugin approach also for MD engines (similarly to CVs/methods).
- To simplify interface, there is a single routine plumed_cmd which takes a string and a pointer.
It can be used to pass any information to plumed, such as:
\verbatim
plumed p=plumed_create();
plumed_cmd(p,"setNatoms",&natoms);
plumed_cmd(p,"setMDEngine","gromacs");
plumed_cmd(p,"init",NULL);
...
plumed_cmd(plumedmain,"setPositions",pos);
plumed_cmd(plumedmain,"setBox",box);
plumed_cmd(plumedmain,"setEnergy",&energy);
plumed_cmd(plumedmain,"setForces",forces);
plumed_cmd(plumedmain,"setVirial",virial);
plumed_cmd(plumedmain,"calc",NULL);
...
plumed_finalize(p);
\endverbatim
Fortran/C++ interfaces are similar (see src/Plumed.c for details), and are based on the C interface
(wrappers).
- Units: PLUMED reads and writes only in its internal units, which, by default, are
nm and kj/mol. In plumed.dat it is possible to change it to other choices:
\verbatim
UNITS ...
LENGTH=A
TIME=fs
ENERGY=kcal/mol
... UNITS
\endverbatim
The MD code should specify to plumed its internal units, so as to allow proper conversion.
E.g., a code using angstrom and kcal should do the following calls
\verbatim
double energyUnits=4.184;
double lengthUnits=0.1;
plumed_cmd(plumedmain,"setMDEnergyUnits",&energyUnits);
plumed_cmd(plumedmain,"setMDLengthUnits",&lengthUnits);
\endverbatim
- Other cool features:
- Functions of colvars (or functions of functions) can be used. For example, defining:
\verbatim
COMBINE LABEL=sum2 ARG=dist.x,dist.y,dist.z POWERS=2,2,2
COMBINE LABEL=sqrtsum2 ARG=sum2 POWERS=0.5
# The following two restraints are equivalent:
RESTRAINT ARG=dist AT=1.2 KAPPA=1.0
RESTRAINT ARG=sqrtsum2 AT=1.2 KAPPA=1.0
\endverbatim
- Multiple-time-step: biases can be applied with multiple-time-step using a stride. This should
help for variables which are heavy to compute but smooth
\verbatim
RESTRAINT ARG=dist AT=1.2 KAPPA=1.0 STRIDE=2
\endverbatim
- It is possible to include other files:
\verbatim
INCLUDE FILE=anotherplumed.dat
\endverbatim
- It is possible to load shared libraries implementing new CVs and methods:
\verbatim
LOAD FILE=share-object.so
\endverbatim
\section Install Install
- Configure and compile your MD code
- Configure and compile PLUMED, possibly using the same compiler:
\verbatim
$ ./configure.sh
... choose your compiler interactively here ...
... it may be necessary to edit the Makefile.conf file ...
$ make -j 4
\endverbatim
- Source the ./sourceme.sh file
\verbatim
$ source sourceme.sh
\endverbatim
\attention This should be done on every shell where you want to patch/run plumed
- Go to your MD code directory and do the patch
\verbatim
$ plumed patch --patch
\endverbatim
(use -h to get information about other options). Also experiment other linking modes (e.g. --runtime)
- Recompile your MD code (without necessarily cleaning it)
\section Content Content
src/
Plumed library source code (C++) plus a two wrapper files (Plumed.c and PlumedStatic.cpp; the latter is just
equivalent to the former but is compiled as cpp, for testing, and does not allow runtime binding).
Sources are compiled into a libplumed.so library and a libplumedKernel.so library
(replace .so with .dylib on Mac).
The src/Plumed.inc file contains shortcuts for the compilation. Just include it in your makefile and:
- link the src/Plumed.h file in an included directory
- add to the linker command the $(PLUMED_LDFLAG) options, to have the proper link flags
- add to the linker command the $(PLUMED_LIBS) variable, to link the proper external libraries
- add to the linker command one of the following variables:
- (A) \$(PLUMED_OBJ) : plumed will be statically bound
- (B) \$(PLUMED_SHARED_OBJ) : plumed will be dynamically bound
- (C) \$(PLUMED_WRAPPER) : behavior depend on runtime value of the PLUMED_KERNEL environment variable.
If set to the full path of the libplumedKernel.so library, plumed will be available.
If unset, or if set to a wrong file, plumed will not be available.
- The difference between (A) and (B) is that in case (B) if you recompile plumed and rerun MD your code
is automatically up to date.
The difference between (B) and (C) is that in case (C) the MD code is able to run also if plumed is
not available. This allows to have a single compiled MD code for both plumed users and others.
Moreover, in case (C) it is trivial to change plumed version at execution time, by properly setting
the PLUMED_KERNEL environment variable.
Notice that in (B) case the full path of the plumed library is recorded, thus it should not
be changed after patching, and it should be reachable from computing nodes.
All these task can be done automatically with "plumed patch" using respectively the flags:
- (A) --static
- (B) --shared
- (C) --runtime
extensions/
Plumed extensions (e.g. contributed collective variables, ...)
They are compiled into a libplumedExtensions.so file which can be loaded at runtime.
To load them, use LOAD command inside plumed.dat
test/link/
A few simple executables to test compilation/linking
Executables are:
- (A) XXX-static statically linked with src/*.o (except src/Plumed.o)
- (B) XXX dynamically linked with libplumed.so
- (C) XXX-dummy statically linked with src/Plumed.o
user-doc/
User documentation
developer-doc/
Developer documentation
\section Notes Notes
Information about C++
http://www.parashift.com/c++-faq-lite/
Compiler options to use shared libraries on many architectures:
http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html
\page HowToAddACollectiveVariable How to add a collective variable
\page HowToAddAFunction How to add a function
\page HowToAddABias How to add a biasing potential
*/